vu

Documentation

Overview

Package vu (virtual universe) provides 3D application support. Vu wraps the individual subsystems like rendering, physics, data loading, audio, etc. to provide higher level functionality that includes:

• Scene graphs and composite objects.
• Timestepped update/render loop.
• Regular user input updates.
• Cameras and transform manipulation.

The vu/eg (examples) package provides relatively small working code samples of engine functionality both for testing and demonstration purposes.

Vu dependencies are:

• OpenGL for graphics card access. See package vu/render.
• OpenAL for sound card access. See package vu/audio.
• Cocoa for OSX windowing and input. See pacakge vu/device.
• WinAPI for Windows windowing and input. See package vu/device.

Index

• Constants
• func Box(hx, hy, hz float64) move.Body
• func RenderMatrix(mm *lin.M4, rm *render.M4) *render.M4
• func Sphere(radius float64) move.Body
• type Director
• type Engine
  • func New(name string, x, y, width, height int) (e Engine, err error)
• type Input
• type Part
• type Parts
  • func (p Parts) Len() int
  • func (p Parts) Less(i, j int) bool
  • func (p Parts) Swap(i, j int)
• type Reaction
  • func NewReactOnce(name string, do func()) Reaction
  • func NewReaction(name string, do func()) Reaction
• type Scene

Constants

const (
	XAxis = iota // Affect only the X axis.
	YAxis        // Affect only the Y axis.
	ZAxis        // Affect only the Z axis.
)

3D Direction constants. Primarily used for panning or rotating a camera view. See Scene.PanView.

const (
	BLEND = render.BLEND // Alpha blending.
	CULL  = render.CULL  // Backface culling.
	DEPTH = render.DEPTH // Z-buffer awareness.
)

Global graphic state constants. These are attributes used in the Engine.Enable method.

const (
	VP    = iota // Perspective view transform.
	VO           // Orthographic view transform.
	VF           // First person view transform.
	XZ_XY        // Perspective to Ortho view transform.
)

View transform choices. These are used when adding a new scene. The view transform dictates the overall behaviour of the camera.

VP    is a perspective view transform. It is the reverse order of the
      model transforms so that the scene revolves around the camera.
VO    is an orthographic view transform used in 2D scenes.
VF    is a first person view transform that uses an up/down angle.
XZ_XY is an overlay view that transforms an X,-Z mapped object to X,Y.
      Useful for turning 3D floor plans into 2D mini-maps.

const RELEASED = device.KEY_RELEASED

RELEASED is used to indicate a released key or button.

Functions

func Box

func Box(hx, hy, hz float64) move.Body

Box creates a box shaped physics body located at the origin. The box size is w=2*hx, h=2*hy, d=2*hz.

func RenderMatrix

func RenderMatrix(mm *lin.M4, rm *render.M4) *render.M4

RenderMatrix turns a math/lin matrix into a matrix that can be used by the render system. The input math matrix, mm, is used to fill the values in the given render matrix rm. The updated rm matrix is returned.

func Sphere

func Sphere(radius float64) move.Body

Sphere creates a ball shaped physics body located at the origin. The sphere size is set by the radius.

Types

type Director

type Director interface {
	// Create is called to populate the initial Scenes and Parts.
	Create(eng Engine)

	// Update is called many times a second to update application state.
	// The engine will use the updated state in the next render.
	// It is expected that this method returns quickly.
	//
	// User input is provided as a map of currently pressed keys,
	// mouse buttons and their pressed durations.
	Update(i *Input)
}

Director gives the application a chance to react at key moments. It is expected to be used by the application as follows:

eng, _ = vu.New("Title", 800, 600) // App creates Engine.
eng.SetDirector(app)               // App registers as a Director.

type Engine

type Engine interface {
	SetDirector(director Director)    // Enable application callbacks.
	Action()                          // Kick off the main update loop.
	Shutdown()                        // Stop the engine and free allocated resources.
	AddScene(transform int) Scene     // Add a scene.
	RemScene(s Scene)                 // Remove a scene.
	SetOverlay(s Scene)               // Mark a scene as the overlay scene.
	Size() (x, y, width, height int)  // Get the current viewport size.
	Resize(x, y, width, height int)   // Resize the current viewport.
	Color(r, g, b, a float32)         // Set background clear colour.
	Enable(attr uint32, enabled bool) // Enable/disable global graphic attributes.
	ShowCursor(show bool)             // Hide or show the cursor.
	SetCursorAt(x, y int)             // Put the cursor at the given window location.

	// PlaceSoundListener sets the 3D location of the entity that can hear sounds.
	// Sounds that are played at other locations will be heard more faintly as the
	// distance between the played sound and listener increases.
	PlaceSoundListener(x, y, z float64)     // Create a sound listener.
	UseSound(sound string) audio.SoundMaker // Create a sound maker.
	Mute(mute bool)                         // Toggle game sound.
}

Engine initializes and runs 3D application support. Interaction with the application is through the Director interface callbacks.

func New

func New(name string, x, y, width, height int) (e Engine, err error)

New creates a 3D engine. The expected usage is:

if eng, err = vu.New("Title", 100, 100, 800, 600); err != nil {
    log.Printf("Failed to initialize engine %s", err)
    return
}
defer eng.Shutdown() // Close down nicely.
eng.SetDirector(app) // Enable application callbacks.
                     // Application 3D setup and initialization.
eng.Action()         // Run application loop (does not return).

type Input

type Input struct {
	Mx, My  int            // Current mouse location.
	Down    map[string]int // Pressed keys, buttons with duration.
	Shift   bool           // True if shift modifier is currently pressed.
	Control bool           // True if control modifier is currently pressed.
	Focus   bool           // True if window is in focus.
	Resized bool           // True if window was resized or moved.
	Dt      float64        // Delta time used for updates.
	Gt      float64        // Game time is the total number of updates.
}

Input is used to communicate current user input to the application. This gives the current cursor location, current pressed keys, mouse buttons, and modifiers.

The map of keys and mouse buttons that are currently pressed also include how long they have been pressed in update ticks. A negative value indicates a release where the duration can be calculated by (RELEASED - duration).

type Part

type Part interface {

	// Create, remove, and dispose parts and sub-parts (bit-parts?).
	AddPart() Part  // Create a new part attached (subordinate) to this one.
	RemPart(p Part) // Remove a subordinate part, without disposing the sub-part.
	Dispose()       // Remove this part, all sub-parts and any associated info.

	// Location, orientation, and scale.
	Location() (x, y, z float64)    // Get the current location.
	SetLocation(x, y, z float64)    // Set the current location.
	Rotation() (x, y, z, w float64) // Get the current quaternion rotation.
	SetRotation(x, y, z, w float64) // Set the current quaternion rotation.
	Scale() (x, y, z float64)       // Get the size, one value for each axis.
	SetScale(x, y, z float64)       // Set the size, one value for each axis.

	// Move and turn control cameras, players, and AIs. When there is a physics
	// body the velocity is updated. When there is no physics body the position
	// and direction are upated.
	Move(x, y, z float64) // Move an amount along the current direction.
	Spin(x, y, z float64) // Rotate degrees about the given axis.

	// Associates a visible facade with a Part. The facade methods that follow
	// only work when there is a facade associated with the part.
	SetFacade(mesh, shader string) Part   // Create a facade for this part.
	SetMaterial(name string)              // Set the material.
	Visible() bool                        // Get the parts visibility.
	SetVisible(visible bool)              // Set the parts visibility.
	SetCullable(cullable bool)            // Set the parts cullability.
	Alpha() float64                       // Get the transparency.
	SetAlpha(a float64)                   // Set the transparency.
	SetTexture(name string, spin float64) // Set the texture.

	// Associates a text facade with a Part. The banner methods only work
	// when there is a Banner associated with the part.  Only one of banner
	// or facade may be associated with a part.
	SetBanner(text, shader, glyphs, texture string) // Create a banner for this part.
	UpdateBanner(text string)                       // Change the text for the banner.
	BannerWidth() int                               // Get the banner width in pixels.

	// Associates a physics body with a Part. The body methods that follow
	// only work when there is a physics body associated with the part.
	SetBody(body move.Body, mass, bounce float64) // Create a physics body for this part.
	RemBody()                                     // Delete the physics body for this part.
	Speed() (x, y, z float64)                     // Current linear velocity.
	Push(x, y, z float64)                         // Change the linear velocity.
	Turn(x, y, z float64)                         // Change the angular velocity.
	Stop()                                        // Remove all velocity.
}

A part is a node in a scene graph (a part in the scene, yah?). Its main responsibility is positioning. A part can also be associated with one or more of the following:

facade  : A part can have a visible surface. The parts location becomes the
          location of the rendered object. SetFacade() and SetBanner() both
          associate a facade with a part.
physics : A part can interface with physics. The parts location becomes
          controlled by the physics simulation. SetBody() associates a
          physics body with a part.

Parts are scene graph nodes and as such can themselves have subordinate parts.

It is possible to have a transform-only part (no facade or physics) in order to group other objects in the scene graph. All subordinate parts will be affected by transform changes to parent parts.

type Parts

type Parts []*part

Parts is used to sort a slice of parts in order to get transparency working. Objects furthest away have to be drawn first. This is only public for the sort package and is not for application use.

func (Parts) Len

func (p Parts) Len() int

Sort parts ordered by distance.

func (Parts) Less

func (p Parts) Less(i, j int) bool

func (Parts) Swap

func (p Parts) Swap(i, j int)

type Reaction

type Reaction interface {
	Name() string    // Unique reaction identifier i.e. "moveUp".
	Do()             // Application action handler.
	Time() time.Time // Last time this reaction was triggered.
	SetTime()        // Updates Time.
}

Reaction links an application callback to a given user pressed key sequence. The "Do" reaction is triggered when the user pressed key sequence matches the reaction id.

func NewReactOnce

func NewReactOnce(name string, do func()) Reaction

NewReactOnce (metered reaction) wraps a Reaction with a hold off timer so that the reaction is performed every so often and not every event loop.

This is because key and mouse events are processed many times a second and even a quick key press will generate multiple user pressed key sequences. This works great for movement, but some actions need to be gated to ensure they are not spammed.

func NewReaction

func NewReaction(name string, do func()) Reaction

NewReaction creates a Reaction.

type Scene

type Scene interface {
	AddPart() Part                    // Add a scene node.
	RemPart(p Part)                   // Remove a scene node.
	SetTransform(transform int)       // Set a view transform.
	SetLightLocation(x, y, z float64) // Currently only one light.
	SetLightColour(r, g, b float64)   // Currently only one light.
	Set2D()                           // Overlays are 2D.
	Visible() bool                    // Only visible scenes are rendered.
	SetVisible(visible bool)          // Change whether or not the scene is rendered.

	// Camera.
	ViewLocation() (x, y, z float64)    // Get the view location.
	SetViewLocation(x, y, z float64)    // Set the camera position.
	ViewRotation() (x, y, z, w float64) // Get the view orientation.
	SetViewRotation(x, y, z, w float64) // Set the view orientation.
	MoveView(x, y, z float64)           // Alter camera position based direction.
	PanView(dir int, degrees float64)   // Rotate the camera.
	ViewTilt() (up float64)             // Get the camera tilt angle.
	SetViewTilt(up float64)             // Alter the camera tilt angle.

	// SetSorted orders the parts based on distance so that transparency
	// works. Objects furthest away are drawn first with transparency.
	SetSorted(sorted bool)

	// SetVisibleRadius limits the visible (rendered) objects in the scene to a
	// given radius from the scenes camera. Setting this to 0 or less will turn
	// off the visible radius and everything will be drawn.
	SetVisibleRadius(radius float64) // Restrict rendering to a circle around the camera.

	// SetVisibleDirection is used with SetVisibleRadius such that the visible
	// area is moved radius units in the camera's direction, i.e. the camera is
	// at the edge and facing the visible area.
	SetVisibleDirection(facing bool) // Move the rendering circle in front of the camera.

	// Create the perspective transform for this scene.
	SetPerspective(fov, ratio, near, far float64)                // 3D projection transform.
	SetOrthographic(left, right, bottom, top, near, far float64) // 2D projection transform.
}

Scene orgnanizes everything that needs to be rendered and is associated with a single camera and camera transform. It is also the top level scene node in a scene graph. There may be more than one Scene instance to allow for groups of objects, like overlays, to use different camera transforms.