pxu

Documentation

Overview

Package pxu provides useful utilites for the Pixel 2D graphics library.

This library can be found on github at https://github.com/faiface/pixel . "pxu" is maintained by Ben Stabley (quillaja), and is provided as-is under the "unlicense". Do whatever you want.

Index

• func GetZoomLevelFromMouseScroll(win *pixelgl.Window) func() float64
• func PixIndex(x, y, width int) int
• type Camera
• type KeyCamera
  • func NewKeyCamera(worldZeroInWindow pixel.Vec) *KeyCamera
  • func NewKeyCameraParams(worldZeroInWindow, origPosition pixel.Vec, ...) *KeyCamera
  • func (cam *KeyCamera) GetMatrix() pixel.Matrix
  • func (cam *KeyCamera) GetPosition() pixel.Vec
  • func (cam *KeyCamera) GetZoom() float64
  • func (cam *KeyCamera) Reset()
  • func (cam *KeyCamera) ResetPan()
  • func (cam *KeyCamera) ResetXPan()
  • func (cam *KeyCamera) ResetYPan()
  • func (cam *KeyCamera) ResetZoom()
  • func (cam *KeyCamera) Unproject(point pixel.Vec) pixel.Vec
  • func (cam *KeyCamera) Update(win *pixelgl.Window)
• type MouseCamera
  • func NewMouseCamera(worldZeroInWindow pixel.Vec) *MouseCamera
  • func NewMouseCameraParams(worldZeroInWindow, origPos pixel.Vec, origZoom, zoomSpeed float64) *MouseCamera
  • func (c *MouseCamera) GetMatrix() pixel.Matrix
  • func (c *MouseCamera) GetPosition() pixel.Vec
  • func (c *MouseCamera) GetZoom() float64
  • func (c *MouseCamera) Reset()
  • func (c *MouseCamera) ResetPosition()
  • func (c *MouseCamera) ResetZoom()
  • func (c *MouseCamera) Unproject(point pixel.Vec) pixel.Vec
  • func (c *MouseCamera) Update(win *pixelgl.Window)

Functions

func GetZoomLevelFromMouseScroll

func GetZoomLevelFromMouseScroll(win *pixelgl.Window) func() float64

GetZoomLevelFromMouseScroll provides a convenient way to make a KeyCamera's "ZoomLvl" property, which is a func() float64.

cam.ZoomLvl = GetZoomLevelFromMouseScroll(win)
for !win.Closed() {
    ...

func PixIndex

func PixIndex(x, y, width int) int

PixIndex is a convenience method to calculate the index of a pixel in a pixelgl.Canvas pixel array used in Pixels()/SetPixels(). The formula is

4*y*width + x*4

Types

type Camera

type Camera interface {
	Update(*pixelgl.Window)
	GetMatrix() pixel.Matrix
	Reset()
	Unproject(pixel.Vec) pixel.Vec
	GetPosition() pixel.Vec
	GetZoom() float64
}

Camera is the basic interface for all camera types. Example usage within the context of Pixel:

// ... prior initialization
var cam Camera = NewKeyCamera(win.Bounds().Center()) // using defaults
// alternatively: NewKeyCameraParams(<somex>, <somey>, 200, 1.1) for another starting point
// or NewMouseCamera() etc.

for !win.Closed() {

    // Reset() should be called before Update() and before
    // setting the window's matrix (via SetMatrix())
    if win.JustPressed(pixelgl.KeyHome) {
        cam.Reset() // reset Position and Zoom to (0,0) and 1
    }

    cam.Update(win) // camera updates position, zoom, etc
    win.SetMatrix(cam.GetMatrix()) // provide transformation matrix to window
    win.Clear()
    //... redraw window, update state, etc

type KeyCamera

type KeyCamera struct {
	Position  pixel.Vec // X,Y location in "world" of the camera
	PanSpeed  float64   // pixels/sec speed of camera pan
	Zoom      float64   // current zoom factor of the camera
	ZoomSpeed float64   // speed at which the camera zooms, eg 2=2x zoom for each 'zoom level'

	XExtents clamp // min and max extents the camera can pan horizontally
	YExtents clamp // min and max extents the camera can pan vertically
	ZExtents clamp // min and max zoom factor

	UpButton, DownButton        pixelgl.Button // which buttons are to be used for up/down panning
	LeftButton, RightButton     pixelgl.Button // which buttons are to be used for left/right panning
	ZoomInButton, ZoomOutButton pixelgl.Button // which buttons are to be used for zoom in/out
	ZoomLevel                   func() float64 // func to get a zoom level as alternative to buttons
	// contains filtered or unexported fields
}

KeyCamera provides a simple but relatively feature rich 2D camera for use with the Pixel graphics library.

Position (panning) is controlled via the Position and PanSpeed members. By default, the Position is controled by the user via the Up, Down, Left, and Right keys. However, this can be customized by setting the UpButton, DownButton, LeftButton, and RightButton members to a pixelgl.Button value.

Zoom is controlled by the Zoom and ZoomSpeed members. Zooming is based on multication, so a "zero" zoom is Zoom == 1. The ZoomSpeed is based on expotentiation where ZoomSpeed is the base which is raised to some "zoom level" power (ie ZoomSpeed**zoomlvl). This zoom level controlled by the + and - keys by default, but can be customized by setting ZoomLevel to a function with the signature `func() float64`. For example, this library provides `GetZoomLevelFromMouseScroll()` which creates such a function to get the zoom level from the mouse's scroll wheel when provided with a pointer to a pixelgl.Window.

Limits on panning and zooming are provided by XExtents, YExtents, and ZExtents which provide "Low" and "High" limits to which Position.X, Position.Y, and Position.Z are clamped to, respectively.

The Reset() series of methods allow the camera position and/or zoom to be reset to their original values. If NewKeyCamera() was used to instantiate, then those defaults are the "origCenter" parameter and Zoom(1). If NewKeyCameraParams() was used, the initial values for position and zoom provided as parameters are saved within the camera and then used when Reset() is called.

func NewKeyCamera

func NewKeyCamera(worldZeroInWindow pixel.Vec) *KeyCamera

NewKeyCamera creates a new camera with sane defaults.

A recommended worldZeroInWindow is `win.Bounds().Center()` (center of window). Default values are:

PanSpeed: 200 // pixels/sec
Zoom: 1
ZoomSpeed: 1.1
XExtents.Low = -5000, XExtents.High = 5000
YExtents.Low = -5000, YExtents.High = 5000
ZExtents.Low = 0.1, ZExtents.High = 50

Keyboard Up, Down, Left, and Right control panning, and the + and - buttons (aka = and -) control zooming.

func NewKeyCameraParams

func NewKeyCameraParams(worldZeroInWindow, origPosition pixel.Vec, origZoom, panSpeed, zoomSpeed float64) *KeyCamera

NewKeyCameraParams creates a new camera with the given parameters. "origPosition" and "origZoom" are stored and used for calls to Reset(). Other camera parameters are set according to the defaults (see NewKeyCamera()) but can be changed.

func (*KeyCamera) GetMatrix

func (cam *KeyCamera) GetMatrix() pixel.Matrix

GetMatrix gets the transformation matrix to apply the camera's settings to a window.

win.SetMatrix(cam.GetMatrix())

func (*KeyCamera) GetPosition

func (cam *KeyCamera) GetPosition() pixel.Vec

GetPosition returns the camera's position.

func (*KeyCamera) GetZoom

func (cam *KeyCamera) GetZoom() float64

GetZoom returns the camera's zoom factor.

func (*KeyCamera) Reset

func (cam *KeyCamera) Reset()

Reset restores the camera's Position and Zoom to its initial settings.

func (*KeyCamera) ResetPan

func (cam *KeyCamera) ResetPan()

ResetPan restores the camera's Position to its initial settings.

func (*KeyCamera) ResetXPan

func (cam *KeyCamera) ResetXPan()

ResetXPan restores the camera's Position.X (horizontal pan) to its initial setting.

func (*KeyCamera) ResetYPan

func (cam *KeyCamera) ResetYPan()

ResetYPan restores the camera's Position.Y (vertical pan) to its initial setting.

func (*KeyCamera) ResetZoom

func (cam *KeyCamera) ResetZoom()

ResetZoom restores the camera's Zoom to its initial setting.

func (*KeyCamera) Unproject

func (cam *KeyCamera) Unproject(point pixel.Vec) pixel.Vec

Unproject will translate a point from its window position to its "world" position. This method is identical to:

m := cam.GetMatrix()
m.Unproject(point)

func (*KeyCamera) Update

func (cam *KeyCamera) Update(win *pixelgl.Window)

Update recalculates the camera position and zoom, and is generally called each frame before setting the window's matrx. Update checks the keyboard for the status of the defined panning and zooming controls (see `KeyCamera`). Position.X, Position.Y, and Zoom are clamped to XExtents, YExtents, and ZExtents respectively.

type MouseCamera

type MouseCamera struct {
	Position  pixel.Vec // the 'world' location of the camera
	Zoom      float64   // the zoom factor of the camera
	ZoomSpeed float64   // how quickly the camera zooms. should be >1

	XExtents clamp // min and max extents the camera can pan horizontally
	YExtents clamp // min and max extents the camera can pan vertically
	ZExtents clamp // min and max extents for the zoom factor

	DragButton pixelgl.Button // the button which performs drag when pressed and held. default is left mouse buttom
	// contains filtered or unexported fields
}

MouseCamera is a camera type that uses only the mouse for camera control. Panning is done by a mouse drag action like that commonly found in photo editing software. Zooming is done such that the "zoom locus" is the point the mouse is currently over.

For a basic example of how to use the camera, see the `Camera` interface, and read more in the documentation for `KeyCamera`.

func NewMouseCamera

func NewMouseCamera(worldZeroInWindow pixel.Vec) *MouseCamera

NewMouseCamera creates a new camera with default values. A recommended setting for worldZeroInWindow is `win.Bounds().Center` (center of the window).

Defaults:

Position:   pixel.ZV (0,0),
Zoom:       1,
ZoomSpeed:  1.1,
XExtents:   Low: -5000, High: 5000,
YExtents:   Low: -5000, High: 5000,
ZExtents:   Low: 0.1, High: 50,
DragButton: pixelgl.MouseButtonLeft

func NewMouseCameraParams

func NewMouseCameraParams(worldZeroInWindow, origPos pixel.Vec, origZoom, zoomSpeed float64) *MouseCamera

NewMouseCameraParams creates a camera with the parameters specified. Other paramaters can be still be modified. See `NewMouseCamera` for more info.

func (*MouseCamera) GetMatrix

func (c *MouseCamera) GetMatrix() pixel.Matrix

GetMatrix gets a transformation matrix to apply to the window.

win.SetMatrix(cam.GetMatrix())

func (*MouseCamera) GetPosition

func (c *MouseCamera) GetPosition() pixel.Vec

GetPosition returns the camera's position.

func (*MouseCamera) GetZoom

func (c *MouseCamera) GetZoom() float64

GetZoom returns the camera's zoom factor.

func (*MouseCamera) Reset

func (c *MouseCamera) Reset()

Reset resets the camera's position and zoom factor.

func (*MouseCamera) ResetPosition

func (c *MouseCamera) ResetPosition()

ResetPosition resets the camera's position.

func (*MouseCamera) ResetZoom

func (c *MouseCamera) ResetZoom()

ResetZoom resets the camera's zoom factor.

func (*MouseCamera) Unproject

func (c *MouseCamera) Unproject(point pixel.Vec) pixel.Vec

Unproject gets a "world" coordinate from a "screen" coordinate, and is indentical to:

cam.GetMatrix().Unproject(point)

func (*MouseCamera) Update

func (c *MouseCamera) Update(win *pixelgl.Window)

Update recalculates the camera's position and zoom, and is generally called each frame before setting the window's matrix.