vu

package module
v0.7.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 30, 2016 License: BSD-2-Clause, Zlib Imports: 14 Imported by: 1

README

#Vu

Vu (Virtual Universe) is an agile 3D engine based on the modern programming language Go (Golang). Vu is composed of packages, detailed in GoDoc, and briefly summarized below.

Sub packages

  • audio Positions and plays sounds in a 3D environment.
  • audio/al OpenAL bindings. Links the audio layer and the sound hardware.
  • device Links the application to native OS specific window and user events.
  • load Asset loaders including models, textures, audio, shaders, and bitmapped fonts.
  • math/lin Vector, matrix, quaternion, and transform linear math library.
  • physics Repositions bodies based on simulated physics.
  • render 3D drawing and graphics interface.
  • render/gl Generated OpenGL bindings. Links rendering system to graphics hardware.
  • render/gl/gen OpenGL binding generator.

Less essential, but potentially more fun packages are:

  • eg Examples that both demonstrate and validate the vu engine.
  • ai Behaviour Tree for autonomous units.
  • grid Grid based random level generators. A-star and flow field pathfinding.
  • synth Procedural generation utilities.

Installation

Ensure you have installed Go 1.6+:

go get -u github.com/gazed/vu

Now you can build and run examples:

cd $GOPATH/src/github.com/gazed/vu/eg
go build .
./eg

Build Dependencies

  • OS X: Objective C and C compilers (clang) from Xcode command line tools.
  • Windows: C compiler (gcc) from mingw64-bit.

Runtime Dependencies

  • OpenGL version 3.3 or later.
  • OpenAL 64-bit version 2.1.

Building on Windows

  • Vu has been built and tested on Windows using gcc from mingw64-bit. Mingw64 was installed to c:/mingw64.
    • Put OpenAL on the gcc library path by copying openal-soft-1.15.1-bin/Win64/soft_oal.dll to c:/mingw64/x86_64-w64-mingw32/lib/OpenAL32.dll
  • 64-bit OpenAL may be difficult to locate for Windows machines. Try http://kcat.strangesoft.net/openal.html/openal-soft-1.15.1-bin.zip.
    • Extract Win64/soft_oal.dll from the zip to c:/Windows/System32/OpenAL32.dll.
  • Building with Cygwin has not been attempted. It may have special needs.

Limitations

The engine and its packages include the essentials by design. In particular:

  • There is no 3D editor.
  • There is no networking package.
  • Physics only handles boxes and spheres.
  • The device layer interface provides only the absolute minimum from the underlying windowing system. Only OSX and Windows 7+ are currently supported.
  • Rendering supports standard OpenGL 3.3 and later. OpenGL extensions are not used.
  • The Windows platform is sometimes limited by the availability of OpenGL and OpenAL. Generally OpenGL issues are fixed by downloading manufacturer's graphic card drivers. However older laptops with Intel graphics don't always have OpenGL drivers.

Documentation

Overview

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

  • Transform graphs and composite objects.
  • Timestepped update/render loop.
  • Access to user input events.
  • Cameras and transform manipulation.
  • Delivering loaded assets to render and audio devices.

Refer to the vu/eg package for examples of engine functionality.

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 package vu/device.
  • WinAPI for Windows windowing and input. See package vu/device.

Index

Constants

View Source 
const (
	K0     = device.K0     // 0 48     Standard keyboard numbers.
	K1     = device.K1     // 1 49       "
	K2     = device.K2     // 2 50       "
	K3     = device.K3     // 3 51       "
	K4     = device.K4     // 4 52       "
	K5     = device.K5     // 5 53       "
	K6     = device.K6     // 6 54       "
	K7     = device.K7     // 7 55       "
	K8     = device.K8     // 8 56       "
	K9     = device.K9     // 9 57       "
	KA     = device.KA     // A 65     Standard keyboard letters.
	KB     = device.KB     // B 66       "
	KC     = device.KC     // C 67       "
	KD     = device.KD     // D 68       "
	KE     = device.KE     // E 69       "
	KF     = device.KF     // F 70       "
	KG     = device.KG     // G 71       "
	KH     = device.KH     // H 72       "
	KI     = device.KI     // I 73       "
	KJ     = device.KJ     // J 74       "
	KK     = device.KK     // K 75       "
	KL     = device.KL     // L 76       "
	KM     = device.KM     // M 77       "
	KN     = device.KN     // N 78       "
	KO     = device.KO     // O 79       "
	KP     = device.KP     // P 80       "
	KQ     = device.KQ     // Q 81       "
	KR     = device.KR     // R 82       "
	KS     = device.KS     // S 83       "
	KT     = device.KT     // T 84       "
	KU     = device.KU     // U 85       "
	KV     = device.KV     // V 86       "
	KW     = device.KW     // W 87       "
	KX     = device.KX     // X 88       "
	KY     = device.KY     // Y 89       "
	KZ     = device.KZ     // Z 90       "
	KEqual = device.KEqual // = 61     Standard keyboard punctuation keys.
	KMinus = device.KMinus // - 45       "
	KRBkt  = device.KRBkt  // ] 93       "
	KLBkt  = device.KLBkt  // [ 91       "
	KQt    = device.KQt    // " 34       "
	KSemi  = device.KSemi  // ; 59       "
	KBSl   = device.KBSl   // \ 92       "
	KComma = device.KComma // , 44       "
	KSlash = device.KSlash // / 47       "
	KDot   = device.KDot   // . 46       "
	KGrave = device.KGrave // ~ 126      "
	KRet   = device.KRet   // ⇦ 8678     "
	KTab   = device.KTab   // ⇨ 8680     "
	KSpace = device.KSpace // ▭ 9645     "
	KDel   = device.KDel   // ⇍ 8653     "
	KEsc   = device.KEsc   // ⊶ 8886     "
	KF1    = device.KF1    // α 945    General Function keys.
	KF2    = device.KF2    // β 946      "
	KF3    = device.KF3    // γ 947      "
	KF4    = device.KF4    // δ 948      "
	KF5    = device.KF5    // ε 949      "
	KF6    = device.KF6    // ζ 950      "
	KF7    = device.KF7    // η 951      "
	KF8    = device.KF8    // θ 952      "
	KF9    = device.KF9    // ι 953      "
	KF10   = device.KF10   // κ 954      "
	KF11   = device.KF11   // λ 955      "
	KF12   = device.KF12   // μ 956      "
	KF13   = device.KF13   // ν 957      "
	KF14   = device.KF14   // ξ 958      "
	KF15   = device.KF15   // ο 959      "
	KF16   = device.KF16   // π 960      "
	KF17   = device.KF17   // ρ 961      "
	KF18   = device.KF18   // ς 962      "
	KF19   = device.KF19   // σ 963      "
	KHome  = device.KHome  // ◈ 9672   Specific function keys.
	KPgUp  = device.KPgUp  // ⇑ 8657     "
	KFDel  = device.KFDel  // ⇏ 8655     "
	KEnd   = device.KEnd   // ▣ 9635     "
	KPgDn  = device.KPgDn  // ⇓ 8659     "
	KLa    = device.KLa    // ◀ 9664   Arrow keys
	KRa    = device.KRa    // ▶ 9654     "
	KDa    = device.KDa    // ▼ 9660     "
	KUa    = device.KUa    // ▲ 9650     "
	KKpDot = device.KKpDot // ⊙ 8857   Extended keyboard keypad keys
	KKpMlt = device.KKpMlt // ⊗ 8855     "
	KKpAdd = device.KKpAdd // ⊕ 8853     "
	KKpClr = device.KKpClr // ⊠ 8864     "
	KKpDiv = device.KKpDiv // ⊘ 8856     "
	KKpEnt = device.KKpEnt // ⇐ 8656     "
	KKpSub = device.KKpSub // ⊖ 8854     "
	KKpEql = device.KKpEql // ⊜ 8860     "
	KKp0   = device.KKp0   // ₀ 8320     "
	KKp1   = device.KKp1   // ₁ 8321     "
	KKp2   = device.KKp2   // ₂ 8322     "
	KKp3   = device.KKp3   // ₃ 8323     "
	KKp4   = device.KKp4   // ₄ 8324     "
	KKp5   = device.KKp5   // ₅ 8325     "
	KKp6   = device.KKp6   // ₆ 8326     "
	KKp7   = device.KKp7   // ₇ 8327     "
	KKp8   = device.KKp8   // ₈ 8328     "
	KKp9   = device.KKp9   // ₉ 8329     "
	KLm    = device.KLm    // ◐ 9680   Mouse buttons treated like keys.
	KMm    = device.KMm    // ◓ 9683     "
	KRm    = device.KRm    // ◑ 9681     "
	KCtl   = device.KCtl   // ● 9679   Modifier keys.
	KFn    = device.KFn    // ◍ 9677     "
	KShift = device.KShift // ⇧ 8679     "
	KCmd   = device.KCmd   // ◆ 9670     "
	KAlt   = device.KAlt   // ◇ 9671     "
)

Expose the device package keys as a convenience so the device package does not always need including. The symbol associated to each key is shown in the comments.

View Source 
const (

	// Global graphic state constants. See Eng.State
	Blend       = render.Blend       // Alpha blending. Enabled by default.
	CullFace    = render.CullFace    // Backface culling. Enabled by default.
	DepthTest   = render.DepthTest   // Z-buffer awareness. Enabled by default.
	StaticDraw  = render.StaticDraw  // Data created once and rendered many times.
	DynamicDraw = render.DynamicDraw // Data is continually being updated.

	// Per-model rendering constants for Model DrawMode option.
	Triangles = render.Triangles // Triangles are the norm.
	Points    = render.Points    // Used for particle effects.
	Lines     = render.Lines     // Used for drawing squares and boxes.

	// KeyReleased indicator. Total time down, in update ticks,
	// is key down ticks minus KeyReleased. See App.Update.
	KeyReleased = device.KeyReleased

	// Application created and controlled objects associated with
	// the transform hierarchy. See Pov.Dispose.
	PovNode  = iota // Transform hierarchy node, 3D location:orientation.
	PovModel        // Rendered model attached to a Pov.
	PovBody         // Physics body attached to a Pov.
	PovCam          // Camera attached to a Pov.
	PovSound        // Sound attached to a Pov.
	PovLight        // Light attached to a Pov.
	PovLayer        // Render pass layer attached to a Pov.
)

Engine constants needed as input to methods as noted.

Variables

View Source 
var CastShadow = func(m Model) { m.(*model).castShadow = true }

CastShadow marks a model that can cast shadows. Casting shadows implies a scene with a light and objects that receive shadows. It also implies a shadow map capable shader.

View Source 
var HasShadows = func(m Model) { m.(*model).hasShadows = true }

HasShadows marks a model that reveals shadows. Revealing shadows implies a scene with a light and objects that cast shadows. It also implies a shadow map capable shader.

Functions

func Cast 

func Cast(ray, b physics.Body) (hit bool, x, y, z float64)

Cast checks if a ray r intersects the given Body b, returning the nearest point of intersection if there is one. The point of contact x, y, z is valid when hit is true.

func Keysym added in v0.5.2 

func Keysym(keycode int) rune

Keysym returns a single rune representing the given key. Zero is returned if there is no rune for the key. This is intended to provide a default means of representing each keyboard key with a displayable character.

func New 

func New(app App, name string, wx, wy, ww, wh int) (err error)

New creates the Engine and initializes the underlying resources needed by the engine. It then starts application callbacks through the engine App interface. New is expected to be called one time on application startup. 

app  : application callback handler.
name : window title.
wx,wy: bottom left window position in screen pixels.
ww,wh: window width and height in screen pixels.

func NewBox 

func NewBox(hx, hy, hz float64) physics.Body

NewBox creates a box shaped physics body located at the origin. The box size is given by the half-extents so that actual size is w=2*hx, h=2*hy, d=2*hz.

func NewPlane 

func NewPlane(nx, ny, nz float64) physics.Body

NewPlane creates a plane located on the origin and oriented by the plane normal nx, ny, nz.

func NewRay 

func NewRay(dx, dy, dz float64) physics.Body

NewRay creates a ray located at the origin and pointing in the direction dx, dy, dz.

func NewSphere 

func NewSphere(radius float64) physics.Body

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

func SetPlane added in v0.5.3 

func SetPlane(plane physics.Body, x, y, z float64)

SetPlane updates the plane normal.

func SetRay 

func SetRay(ray physics.Body, x, y, z float64)

SetRay updates the ray direction.

func VO 

func VO(pov *lin.T, scr *lin.Q, vm *lin.M4) *lin.M4

VO orthographic projection transform used for Camera.Vt.

func VP 

func VP(at *lin.T, scr *lin.Q, vm *lin.M4) *lin.M4

VP perspective projection transform used for Camera.Vt.

func XzXy added in v0.6.2 

func XzXy(at *lin.T, scr *lin.Q, vm *lin.M4) *lin.M4

XzXy perspective to ortho view transform used for Camera.Vt. Can help transform a 3D map to a 2D overlay.

Types

type Animator added in v0.6.5 

type Animator interface {
	Animate(action, frame int) bool        // Return true if available.
	Action() (action, frame, maxFrame int) // Current movement info.
	Actions() []string                     // Animation sequence names.
}

Animator is a Model that can have multiple animated actions. Actions are indexed from 0.

An animated model is a rigged model animation system. An animation is a sequence of positions (frames) for the joints (bones) of a model where the position of each vertex can be affected by up to 4 joints. Animation data is independent of any given instance, thus making it safe to cache and be referenced by multiple models. Animation data may contain more than one animation sequence (action).

type App 

type App interface {
	Create(eng Eng, s *State) // Called once after successful startup.

	// Update allows applications to change state prior to the next render.
	// Update is called many times a second after the initial call to Create.
	//    i : user input refreshed prior to each call.
	//    s : engine state refreshed prior to each call.
	Update(eng Eng, i *Input, s *State) // Process user input, update state.
}

App is the application callback interface to the engine. It is implemented by the application and registered once on engine creation as follows: 

err := vu.New(app, "Title", 0, 0, 800, 600) // Reg. app in new Eng.

The App communicates with the engine using the Eng methods.

type Camera 

type Camera struct {
	Pitch   float64 // X-axis rotation in degrees.
	Yaw     float64 // Y-axis rotation in degrees.
	Look    *lin.Q  // Y-axis quaternion rotation from Yaw.
	Depth   bool    // True by default for 3D depth processing.
	Overlay int     // Set render order bucket with OVERLAY or greater.

	// SetCull sets a method that reduces the number of Models rendered
	// each update. It can be application supplied or engine supplied.
	Cull Culler // Set by application, ie: c.Cull = vu.NewFacingCuller.

	// Set one of the possible view transfrom algorithms. This affects
	// the view portion of model-view-projection.
	Vt ViewTransform // Assigned view transform matrix generator.
	// contains filtered or unexported fields
}

Camera makes rendered models visible within a frame. A camera is attached to a point of view (Pov) where it renders all models in that Pov's hierarchy. Cameras location and orientation is independent from the Pov allowing a camera to be positioned independently from the models.

Camera combines a location+orientation using separate up/down angle tracking. This allows use as a first-person camera which can limit up/down to a given range, often 180deg. Overall orientation is calculated by combining Pitch and Yaw. Look is for walking cameras, Lookat is for flying cameras.

func (*Camera) At added in v0.6.5 

func (c *Camera) At() (x, y, z float64)

At returns the cameras current location in world space.

func (*Camera) Distance 

func (c *Camera) Distance(px, py, pz float64) float64

Distance returns the distance squared of the camera to the given point.

func (*Camera) Lookat 

func (c *Camera) Lookat() *lin.Q

Lookat returns an orientation which is good for flying around. It is a combination of Pitch and Yaw.

func (*Camera) Move 

func (c *Camera) Move(x, y, z float64, q *lin.Q)

Move adjusts the camera location relative to the given orientation. For orientation, use Lookat() to fly, use Look to run along XZ.

func (*Camera) Ray 

func (c *Camera) Ray(mx, my, ww, wh int) (x, y, z float64)

Ray applies inverse transforms to derive world space coordinates for a ray projected from the camera through the mouse's mx,my screen position given window width and height ww,wh.

func (*Camera) Screen 

func (c *Camera) Screen(wx, wy, wz float64, ww, wh int) (sx, sy int)

Screen applies the camera transform on a 3D point in world space wx,wy,wz and returns the 2D screen coordinate sx,sy. The window width and height ww,wh are needed. Essentially the reverse of the Ray method and duplicates what is done in the rendering pipeline. Returns -1,-1 if the point is outside the screen area.

func (*Camera) SetAt added in v0.6.5 

func (c *Camera) SetAt(x, y, z float64)

SetAt positions the camera in world space.

func (*Camera) SetOrthographic 

func (c *Camera) SetOrthographic(left, right, bottom, top, near, far float64)

SetOrthographic makes the camera use a 2D projection. This is the projection part of model-view-projection.

func (*Camera) SetPerspective 

func (c *Camera) SetPerspective(fov, ratio, near, far float64)

SetPerspective makes the camera use a 3D projection. This is the projection part of model-view-projection.

func (*Camera) SetPitch 

func (c *Camera) SetPitch(deg float64)

SetPitch sets the degrees of rotation around the X axis.

func (*Camera) SetUI added in v0.6.2 

func (c *Camera) SetUI() *Camera

SetUI configures the camera to be 2D: no depth, drawn last.

func (*Camera) SetYaw 

func (c *Camera) SetYaw(deg float64)

SetYaw sets the rotation around the Y axis.

type Culler added in v0.6.5 

type Culler interface {

	// Culled returns true if a model represented by point, px, py, pz
	// should be culled using the given camera.
	Culled(cam *Camera, px, py, pz float64) bool
}

Culler reduces the number of items sent for rendering. It is attached to a Camera.

func NewFrontCull 

func NewFrontCull(r float64) Culler

NewFrontCull returns a culler that keeps objects in a radius directly in front of the camera. Objects behind the camera and far away from the camera are culled.

func NewRadiusCull 

func NewRadiusCull(r float64) Culler

NewRadiusCull returns a culler that removes objects outside a given radius from the camera. Can be used to show objects around a camera like top down minimaps.

type Eng 

type Eng interface {
	Shutdown()     // Stop the engine and free allocated resources.
	Reset()        // Put the engine back to its initial state.
	State() *State // Query engine state. State updated per tick.
	Root() *Pov    // Single root of the transform hierarchy.

	// Physics returns the vu/physics system manager.
	Physics() physics.Physics // Allows setting of physics attributes.

	// Set changes engine wide attributes. It accepts one or more
	// functions that take an EngAttr parameter, ie: vu.Color(0,0,0).
	Set(...EngAttr) // Update one or more engine attributes.

	// Timing gives application feedback. It is updated each processing loop.
	// The returned update times should be averaged over multiple calls.
	Usage() *Timing // Per update loop performance metrics.
}

Eng provides support for a 3D application conforming to the App interface. Eng provides the root transform hierarchy node, a point-of-view (Pov) where models, physics bodies, and noises are attached and processed each update. Eng is also used to set global engine state and provides top level timing statistics.

type EngAttr added in v0.6.5 

type EngAttr func(Eng)

EngAttr defines an engine attribute that can be used in Eng.Set().

func Color added in v0.6.5 

func Color(r, g, b, a float32) EngAttr

Color sets the background window clear color. Engine attribute expected to be used in Eng.Set().

func CursorAt added in v0.6.5 

func CursorAt(x, y int) EngAttr

CursorAt places the cursor at the window pixel x,y. Engine attribute expected to be used in Eng.Set().

func CursorOn added in v0.6.5 

func CursorOn(show bool) EngAttr

CursorOn hides or shows the cursor. Engine attribute expected to be used in Eng.Set().

func Gravity added in v0.6.5 

func Gravity(g float64) EngAttr

Gravity changes the physics gravity constant. Engine attribute expected to be used in Eng.Set().

func Mute added in v0.6.5 

func Mute(mute bool) EngAttr

Mute toggles the sound volume. Engine attribute expected to be used in Eng.Set().

func On added in v0.6.5 

func On(attr uint32, enabled bool) EngAttr

On enables/disables render attributes like Blend, CullFace, etc... Engine attribute expected to be used in Eng.Set().

func ToggleFullScreen added in v0.6.5 

func ToggleFullScreen() EngAttr

ToggleFullScreen flips full screen and windowed mode. Engine attribute expected to be used in Eng.Set().

func Volume added in v0.6.5 

func Volume(zeroToOne float64) EngAttr

Volume sets the sound volume. Engine attribute expected to be used in Eng.Set().

type Input 

type Input struct {
	Mx, My  int         // Current mouse location.
	Down    map[int]int // Keys, buttons with down duration ticks.
	Focus   bool        // True if window is in focus.
	Resized bool        // True if window was resized or moved.
	Scroll  int         // Scroll amount: plus, minus or zero.
	Dt      float64     // Delta time for this update tick.
	Ut      uint64      // Total number of update ticks.
}

Input is used to communicate user feedback to the application. User feedback is the current cursor location, current pressed keys, mouse buttons, and modifiers. These are sent to the application each App.Update() callback. Overall the keyboard is treated like a gamepad controller. Keys and buttons are pressed or not pressed.

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 key release, upon which the total down duration can be calculated using the down duration less the KeyReleased timestamp.

type Labeler added in v0.6.5 

type Labeler interface {
	SetStr(text string) Labeler // Set the string to display.
	StrWidth() int              // Width in screen pixels, 0 if not loaded.
}

Labeler is a Model that displays a small text phrase. The Model combines a quad mesh, font mapping data, and a bitmapped font texture to display a string. Controlling a Labeler amounts to setting the string value and centering it using its width in pixels.

type Layer added in v0.6.2 

type Layer interface{}

Layer is used to render to a 1024x1024 sized frame buffer based texture. A layer represents the output of rendering to a texture instead of to the default framebuffer for the screen. The layer texture is then used as part of the final screen render. There are currently 2 uses for layers: a render.ImageBuffer and render.DepthBuffer. 

ImageBuffer: renders all or parts of a scene to a texture.
             Often used to generate a texture which is then used
             as a uv texture for another model. Think Portal.
DepthBuffer: render objects from the point of view of the
             light. Distance (depth) values are written to the
             texture and later used by a shadow capabable shader
             to draw object shadows.

Layers are created, associated with one Pov, and used by a Model at a potentially different Pov.

type Light 

type Light struct {
	R, G, B float64 // Red, Green, Blue values range from 0 to 1.
}

Light is used by shaders to interact with a models material values. Light is attached to a Pov to give it a position in world space. Light is defaulted to white 1,1,1. Valid R,G,B color values are from 0 to 1.

func (*Light) SetColor added in v0.6.2 

func (l *Light) SetColor(r, g, b float64)

SetColor is a convenience method for changing the light color.

type Mesh added in v0.6.5 

type Mesh interface {
	InitData(lloc, span, usage uint32, normalize bool) Mesh
	SetData(lloc uint32, data interface{}) // Only works after InitData
	InitFaces(usage uint32) Mesh           // Defaults to StaticDraw
	SetFaces(data []uint16)                // Indicies to vertex positions.
}

Mesh is an optional, but very common, part of a rendered Model. Mesh holds 3D model data in a format that is easily consumed by a rendering layer. The data consists of one or more sets of per-vertex data points and how the vertex positions are organized into shapes like triangles or lines.

Meshes are generally loaded from assets, but can also be generated. Mesh data is closely tied to a given shader. When generating and refreshing vertex data note that InitData must be called once and SetData is called as needed to refresh. Data parameters are: 

lloc     : layout location is the shader input reference.
span     : indicates the number of data points per vertex.
usage    : StaticDraw or DynamicDraw.
normalize: true to convert data to the 0->1 range.

Some vertex shader data conventions are: 

Vertex positions lloc=0 span=3_floats_per_vertex.
Vertex normals   lloc=1 span=3_floats_per_vertex.
UV tex coords    lloc=2 span=2_floats_per_vertex.
Color            lloc=3 span=4_floats_per_vertex.

Note each data buffer must refer to the same number of verticies, and the number of verticies in one mesh must be less than 65,000.

type ModAttr added in v0.6.5 

type ModAttr func(Model)

ModAttr defines optional model attributes that can be used in Model.Set().

func DrawMode added in v0.6.5 

func DrawMode(mode int) ModAttr

DrawMode affects rendered meshes by rendering with Triangles, Lines, Points.

func SetDepth added in v0.6.5 

func SetDepth(enabled bool) ModAttr

SetDepth toggles Z-Buffer awareness while rendering. Generally on, it is often disabled for particle effects.

type Model 

type Model interface {
	Shader() (name string)       // Rendered models have a shader.
	Load(assets ...string) Model // Create and import assets.
	Make(assets ...string) Model // Create msh or tex placeholders.
	Set(opts ...ModAttr) Model   // Config with functional options.

	// Mesh allows setting vertex data on meshes. Triggers rebind.
	// Needed for meshes created with Make.
	Mesh() Mesh // One mesh per model.

	// Tex allows setting a texture image. Triggers rebind.
	// Textures are in the order they were added. OrderTex puts the
	// named texture at the given index and shifts the remaining.
	Tex(index int) Tex           // Multiple textures per model.
	ClampTex(name string) Model  // Make texture non-repeating.
	OrderTex(name string, i int) // Order textures for shader.

	// A Model is expected to be one thing at a time. The following
	// are particular combinations of the shader, mesh, and textures
	Animator // Animators are animated Models.
	Labeler  // Labels are Models used to display small text phrases.

	// Particle effects are either CPU:application or GPU:shader based.
	// SetEffect sets a CPU controlled particle effect.
	SetEffect(mover ParticleEffect, maxParticles int)

	// Layers are used for shadows or render to texture.
	UseLayer(l Layer) // Use render pass texture.

	// Set/get shader uniform values where id is the shader uniform name.
	Uniform(id string) (value []float32)         // Uniform name/values.
	SetUniform(id string, floats ...interface{}) // Individual values.

	// Alpha is model transparency used in shaders.
	Alpha() (a float64) // 0 for fully transparent, to 1 fully opaque.
	SetAlpha(a float64) // Overrides any material alpha values.
}

Model manages rendered 3D objects. Model is the link between loaded assets and the data needed by the rendering system. Assets, such as shaders, mesh, textures, etc., are specified as unique strings in the Load method. Assets are loaded and converted to intermediate data which is later converted to render draws for the render system. Make is used for Models that are generated instead of loaded.

A model is expected to be attached to a point-of-view (Pov) to give it a 3D location and orientation in the render transform hierarchy.

It is the applications responsibility to call enough Model methods to ensure the Models shader is provided with its expected asset data. Ie: if the shader expects a texture, ensure a texture is loaded. Mismatches generate runtime logs.

type Particle added in v0.6.2 

type Particle struct {
	Index   float32 // Particle number.
	Alive   float32 // Goes from 1:new particle, to 0:dead.
	X, Y, Z float64 // Particle location.
}

Particle is one of the particles updated by a ParticleEffect. A set of these are returned by the ParticleEffect update method to be rendered by the engine.

type ParticleEffect added in v0.6.2 

type ParticleEffect func(all []*Particle, dt float64) (live []*Particle)

ParticleEffect is used for CPU particle effects where the application does the work of controlling particle lifespans and positions. ParticleEffect describes the application provided particle effect that updates a list of particles and returns the active particles. 

dt: delta-time is the elapsed time in seconds since the last update.

type Pov 

type Pov struct {
	T *lin.T  // Transform combines location and orientation.
	S *lin.V3 // Per axis scale: >1 to enlarge, fraction<1 to shrink.

	// Cull set to true removes this Pov and its child Pov's
	// from processing. Cull is false by default.
	Cull bool // True to exclude from scene graph processing.
	// contains filtered or unexported fields
}

Pov is a Point-of-view which is a combination of position and orientation. Pov's are created by the application and may have additional associated components like rendered models and physics bodies. The associated components use the location and orientation of the Pov.

A Pov can also have a child Pov's whose position and orientation are relative to the parent. This hiearchy of parent-child Pov's forms the transform scene graph. The hierarchy root is available through Eng.

func (*Pov) AddSound added in v0.7.1 

func (p *Pov) AddSound(name string)

AddSound loads audio data associated with this Pov. Played sounds occur at the associated Pov's location. Sounds that are played will be louder as the distance between the played noise and listener decreases. Place the single global noise listener at this Pov.

func (*Pov) At added in v0.6.5 

func (p *Pov) At() (x, y, z float64)

At gets the Pov's location. Location is relative to parent. World space if no parent location.

func (*Pov) Body 

func (p *Pov) Body() physics.Body

Body is an optional physics component associated with a Pov. Body returns nil if there is no physics body for this Pov.

func (*Pov) Cam added in v0.6.2 

func (p *Pov) Cam() *Camera

Cam returns nil if there is no camera for this Pov.

func (*Pov) Dispose 

func (p *Pov) Dispose(kind int)

Dispose deletes and removes either the entire PovNode, or one of its attachments, PovModel, PovBody, ...

func (*Pov) Layer added in v0.6.2 

func (p *Pov) Layer() Layer

Layer returns nil if there is no layer for this Pov.

func (*Pov) Light 

func (p *Pov) Light() *Light

Light returns nil if no there light for this Pov.

func (*Pov) Model 

func (p *Pov) Model() Model

Model returns nil if there is no model for this Pov.

func (*Pov) Move 

func (p *Pov) Move(x, y, z float64, dir *lin.Q)

Move directly affects the location by the given translation amounts along the given direction. Physics bodies should use Body.Push which affects velocity.

func (*Pov) NewBody 

func (p *Pov) NewBody(b physics.Body) physics.Body

NewBody creates non-colliding body associated with this Pov. Bodies are generally set on top level Pov transforms to ensure valid world coordindates.

func (*Pov) NewCam added in v0.6.2 

func (p *Pov) NewCam() *Camera

NewCam adds a camera to a Pov. This means that all rendered models in this Pov's hierarchy will be viewed with this camera settings.

func (*Pov) NewLabel added in v0.6.5 

func (p *Pov) NewLabel(shader, font, fontTexture string) Labeler

NewLabel creates a Model that displays a small text phrase. 

shader      is expected to be a texture mapping shader like "uv".
font        is the font mapping file.
fontTexture is the bitmapped font texture

func (*Pov) NewLayer added in v0.6.2 

func (p *Pov) NewLayer() Layer

NewLayer creates a rendered texture at this Pov. The model at this Pov and its children will be rendered to a texture for this layer. The default texture size is 1024x1024.

func (*Pov) NewLight 

func (p *Pov) NewLight() *Light

NewLight creates and associates a light with this Pov. Light is optional. It affects lighting calculations for this Pov and all child pov's.

func (*Pov) NewModel 

func (p *Pov) NewModel(shader string, attrs ...string) Model

NewModel creates an optional rendered component associated with this Pov. Returns nil if a model already exists.

func (*Pov) NewPov 

func (p *Pov) NewPov() *Pov

NewPov creates, attaches, and returns a new child transform Pov.

func (*Pov) PlaySound added in v0.7.1 

func (p *Pov) PlaySound(index int)

PlaySound plays the sound associated with this Pov. The sound index corresponds to the order the sound was added to the Pov. The first sound added has index 0.

func (*Pov) Scale 

func (p *Pov) Scale() (x, y, z float64)

Scale retrieves the per-axis scale values at 3 separate XYZ values.

func (*Pov) SetAt added in v0.6.5 

func (p *Pov) SetAt(x, y, z float64) *Pov

SetAt sets the Pov at the given location. Location is relative to parent. World space if no parent location.

func (*Pov) SetListener 

func (p *Pov) SetListener()

SetListener sets the location of the listener to be this Pov.

func (*Pov) SetScale 

func (p *Pov) SetScale(x, y, z float64) *Pov

SetScale assigns the XYZ per-axis scale values. Scale default is 1, greater than 1 enlarges, a positive fraction shrinks. Setting through this method causes world transform update while setting the Pov.S directly does not.

func (*Pov) SetSolid 

func (p *Pov) SetSolid(mass, bounce float64)

SetSolid makes the existing Pov physics Body collide. Nothing happens if there is no existing physics Body for this Pov.

func (*Pov) SetView added in v0.6.5 

func (p *Pov) SetView(q *lin.Q) *Pov

SetView directly sets the Pov's orientation. Often used to align this Pov with the orientation of another. Orientation is relative to parent. World space if no parent orientation.

func (*Pov) Spin 

func (p *Pov) Spin(x, y, z float64)

Spin rotates x,y,z degrees about the X,Y,Z axis. The spins are combined in XYZ order, but generally this is used to spin about a single axis at a time.

func (*Pov) View 

func (p *Pov) View() (q *lin.Q)

View returns the orientation of the Pov. Orientation combines direction and rotation about the direction. Orientation is relative to parent. World space if no parent orientation.

func (*Pov) World added in v0.6.2 

func (p *Pov) World() (x, y, z float64)

World returns the world space location. This method is valid in the Eng Update callback, not Create.

type State 

type State struct {
	X, Y, W, H int     // Window lower left corner and size in pixels.
	R, G, B, A float32 // Background clear color.
	Cursor     bool    // True when cursor is visible.
	CullBacks  bool    // True to set backface culling on.
	Blend      bool    // True for texture blending.
	FullScreen bool    // True when window is full screen.
	Mute       bool    // True when audio is muted.
}

State is used to communicate current engine wide variable settings. It is refreshed each update and provided to the application. Changing state is done through Eng methods, often Eng.Set().

func (*State) Screen 

func (s *State) Screen() (x, y, w, h int)

Screen is a convenience method returning the current window dimensions.

type Tex added in v0.6.5 

type Tex interface {
	Set(img image.Image) // Replace image, nil values ignored.
}

Tex is an texture. An optional, but very common, part of a rendered Model. Texture deals with 2D pictures that are mapped onto objects. Texture data is copied to the graphics card. One or more Textures can be associated with a Model and consumed by a Shader.

type Timing 

type Timing struct {
	Elapsed time.Duration // Total loop time since last update.
	Update  time.Duration // Time used for previous state update.
	Renders int           // Render requests since last update.
}

Timing is used to collect main processing loop numbers while the the application loop is active. The numbers are reset each update. Applications are expected to track and smooth these per-update values over a number of updates.

Timing gives a rough idea. Expect things to go slower the more models, draw calls, and the greater number of verticies.

FPS = Renders/Elapsed. This is how many render requests were generated. Actual number of renders likely matches the monitor refresh rate which is 60/sec for most flat screen monitors.

func (*Timing) Dump 

func (t *Timing) Dump()

Dump current amount of update loop time tracked in milliseconds. Times are expected to be reset each update.

func (*Timing) Modelled added in v0.7.1 

func (t *Timing) Modelled(eng Eng) (models, verts int)

Modelled returns the total number of models and the total number of verticies for all models.

func (*Timing) Rendered added in v0.7.1 

func (t *Timing) Rendered(eng Eng) (models, verts int)

Rendered returns the number of models and the number of verticies rendered in the last rendering pass.

func (*Timing) Zero 

func (t *Timing) Zero()

Zero all time and counter values.

type ViewTransform 

type ViewTransform func(*lin.T, *lin.Q, *lin.M4) *lin.M4

ViewTransform creates a transform matrix from location and orientation. This is expected to be used for camera transforms. The camera is thought of as being at 0,0,0. This means moving the camera forward by x:units really means moving the world (everything else) back -x:units. Likewise rotating the camera by x:degrees really means rotating the world by -x.

Source Files

View all Source files

Directories

Path Synopsis
Package ai provides support for application unit behaviour.
 Package ai provides support for application unit behaviour.
Package audio provides access to 3D sound capability.
 Package audio provides access to 3D sound capability.
al
Package al provides golang audio library bindings for OpenAL.
 Package al provides golang audio library bindings for OpenAL.
Package device provides minimal platform/os access to a 3D rendering context and user input.
 Package device provides minimal platform/os access to a 3D rendering context and user input.
Package eg is used to test and demonstrate different aspects of the vu (virtual universe) engine.
 Package eg is used to test and demonstrate different aspects of the vu (virtual universe) engine.
Package grid is used to generate layout data for random maze or skirmish levels.
 Package grid is used to generate layout data for random maze or skirmish levels.
Package load fetches disk based 3D assets.
 Package load fetches disk based 3D assets.
math
lin
Package lin provides a linear math library that includes vectors, matrices, quaternions, transforms and some utility functions.
 Package lin provides a linear math library that includes vectors, matrices, quaternions, transforms and some utility functions.
Package physics is a real-time simulation of real-world physics.
 Package physics is a real-time simulation of real-world physics.
Package render provides access to 3D graphics.
 Package render provides access to 3D graphics.
gl
Package gl provides golang bindings for OpenGL Use is governed by a BSD-style license found in the LICENSE file.
 Package gl provides golang bindings for OpenGL Use is governed by a BSD-style license found in the LICENSE file.
gl/gen
Package gen is used to generate golang OpenGL bindings using an OpenGL specification header file.
 Package gen is used to generate golang OpenGL bindings using an OpenGL specification header file.
Package synth is used to procedurally generate textures and models.
 Package synth is used to procedurally generate textures and models.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.