vu

package module
v0.8.1 Latest Latest
Warning

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

 Go to latest Published: Oct 21, 2017 License: BSD-2-Clause, Zlib Imports: 14 Imported by: 1

README

Vu

Vu (Virtual Universe) is a 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.
  • tools/sdf Signed distance field converstion utility.

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 OpenAL32.dll to c:/mingw64/x86_64-w64-mingw32/lib/OpenAL32.dll
  • 64-bit OpenAL for Windows machines is available at http://openal.org/downloads. Running the OpenAL installer results in a 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. OSX, iOS, 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.
  • Loading and controlling groups of graphics and audio assets.

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

Vu dependencies are:

  • OpenGL (ES) 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.
  • Xcode for iOS cross-compiling & build. 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.

Keys are expected to be used for controlling game actions. There is no text entry or text layout support.

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  // Created once, rendered many times.
	DynamicDraw = render.DynamicDraw // Data 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 lines and boxes.

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

Engine constants needed as input to methods as noted.

Variables

This section is empty.

Functions

func Run added in v0.8.0 

func Run(app App) (err error)

Run creates the engine and initializes the underlying device layers. It does not return, transferring control to the main render loop. The render loop calls the application through the App interface. Run is expected to be called once on application startup. 

app  : used by engine to communicate with App.

func Symbol added in v0.8.0 

func Symbol(keycode int) rune

Symbol 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 in a manner similar to game console controllers.

Types

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 methods are called by the engine. It is implemented by the application and registered once on engine creation as follows: 

err := vu.Run(app) // Register app and run engine.

The application communicates with the engine by calling the Eng methods as well as creating and controlling entities.

type Body added in v0.8.0 

type Body physics.Body

Body wraps physics.Body and groups the physics wrappers together in the documentation. Allows engine users to access common physics methods without including physics package.

func Box added in v0.8.0 

func Box(hx, hy, hz float64) Body

Box 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 Plane added in v0.8.0 

func Plane(nx, ny, nz float64) Body

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

func Ray added in v0.8.0 

func Ray(dx, dy, dz float64) Body

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

func Sphere added in v0.8.0 

func Sphere(radius float64) Body

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

type Camera 

type Camera struct {
	Pitch float64 // X-axis rotation in degrees. Set using SetPitch.
	Yaw   float64 // Y-axis rotation in degrees. Set using SetYaw.
	Look  *lin.Q  // Y-axis quaternion rotation updated by SetYaw.
	// contains filtered or unexported fields
}

Camera makes rendered models visible within a frame. A camera is associated with a scene where it is used to render the scenes 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(wx, wy, wz float64) float64

Distance returns the distance squared of the camera to the given Pov. Uses the existing Pov world coordinates.

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) SetClip added in v0.8.0 

func (c *Camera) SetClip(near, far float64) *Camera

SetClip sets the near and far clipping planes for perspective and orthographic cameras.

func (*Camera) SetFov added in v0.8.0 

func (c *Camera) SetFov(deg float64) *Camera

SetFov sets the field of view for perspective projection cameras. Ignored for orthographic projection cameras.

func (*Camera) SetPitch 

func (c *Camera) SetPitch(deg float64)

SetPitch sets the rotation around the X axis and updates the Look direction.

func (*Camera) SetYaw 

func (c *Camera) SetYaw(deg float64)

SetYaw sets the rotation around the Y axis and updates the Look and Lookat directions.

type Culler added in v0.6.5 

type Culler interface {

	// Culled returns true if a model, represented by the Pov p,
	// should be culled using the given camera c.
	Culled(c *Camera, wx, wy, wz 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, eg: top down minimaps.

type Eng 

type Eng interface {
	Shutdown()     // Stop the engine and free allocated resources.
	State() *State // Query engine state. State updated per tick.

	// AddScene creates a new application scene graph and camera.
	AddScene() *Ent // Group rendered objects with a Camera.

	// AddSound loads audio data and returns a unique sound identifier.
	// Passing the sound identifier to an entity PlaySound() method will
	// play the sound at the entities location. Set the single listener
	// location using SetListener(). Sounds are louder the closer the
	// played sound to the sound listener.
	AddSound(name string) uint32

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

	// Times for the previous update loop. The application
	// can average times over multiple updates.
	Times() *Profile // Per update loop performance metrics.
}

Eng provides support for a 3D application conforming to the App interface. Eng uses scenes to display application created entities using a camera. The application creates one or more scenes, configures the scene cameras, and adds render components to each scene.

Eng also controls the overall engine lifetime, sets global engine state, and provides application profiling timing.

type EngAttr added in v0.6.5 

type EngAttr func(*engine)

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

eng.Set(Color(1,1,1), Mute(true))

func Color added in v0.6.5 

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

Color sets the background window clear color. Engine attribute for use 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 for use in Eng.Set().

func CursorOn added in v0.6.5 

func CursorOn(show bool) EngAttr

CursorOn hides or shows the cursor. Engine attribute for use in Eng.Set().

func Gravity added in v0.6.5 

func Gravity(g float64) EngAttr

Gravity changes the physics gravity constant. Engine attribute for use in Eng.Set().

func Mute added in v0.6.5 

func Mute(mute bool) EngAttr

Mute toggles the sound volume. Engine attribute for use 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 for use in Eng.Set().

func Size added in v0.8.0 

func Size(x, y, w, h int) EngAttr

Size sets the window starting location and size in pixels. For windowed mode. Engine attribute for use in Eng.Set().

func Title added in v0.8.0 

func Title(t string) EngAttr

Title sets the window title. For windowed mode. Engine attribute for use in Eng.Set().

func ToggleFullScreen added in v0.6.5 

func ToggleFullScreen() EngAttr

ToggleFullScreen flips full screen and windowed mode. Engine attribute for use in Eng.Set().

func Volume added in v0.6.5 

func Volume(zeroToOne float64) EngAttr

Volume sets the sound volume. Engine attribute for use in Eng.Set().

type Ent added in v0.8.0 

type Ent struct {
	// contains filtered or unexported fields
}

Ent is an application created entity. Common application entities are scenes and models. For example: 

scene := eng.AddScene()
part := scene.AddPart().MakeModel("uv", "msh:icon", "tex:goal")

Scenes are used to group models with cameras. Models are used to group assets with shaders. Together they are used to render frames.

Entities have methods that expect one or more components (data) to have been established by the application before being called. For example a label can only be Typeset once the entities label data has been created using MakeLabel, eg: 

banner := scene.AddPart().MakeLabel("txt", font)
banner.Typeset("Floating Text") // Typeset implies MakeLabel.

Methods that work with all entities are: Dispose, Exists. Other Ent methods will generate a log for missing component dependencies when applied to the wrong entity.

Components are different types of data that can be associated with an entity. Entity methods, listed below, work with specific components as follows:

Scene : Eng.AddScene creates a scene entity with a Camera. 

Cam, Is2DSetCuller, SetOrtho, SetOver, SetUI.

Part : AddPart creates a new entity with a point-of-view and a scene graph node. 

AddPart, At, SetAt, World, Move, Cull, Culled,
View, SetView, Spin, SetSpin, Scale, SetScale,

Model : MakeModel attaches model data to a part entity. 

MakeModel, Load, Mesh, GenMesh, Tex, GenTex, SetTex, SetFirst,
SetUniform, Alpha, SetAlpha, SetColor, SetDraw, Clamp.

Actor : MakeActor attaches an animated model with a part entity. 

MakeActor, Animate, Action, Actions, Pose.

Label : MakeLabel attaches a string model with a part entity. 

MakeLabel, Typeset, SetWrap, Size.

Body : MakeBody attaches a physics body with a part entity. 

MakeBody, Body, DisposeBody, SetSolid, Cast, Push.

Light : MakeLight attaches light data to a part entity. 

MakeLight, SetLightColor.

Sound : Eng.AddSound creates a new sound entity. 

PlaySound, SetListener.

Shadow: SetShadows adds shadows to an existing scene entity. 

SetShadows.

Target: AsTex controls rendering a scene to a texture for an existing scene entity. 

AsTex.

func (*Ent) Action added in v0.8.0 

func (e *Ent) Action() (move, frame, nFrames int)

Action returns the current animation information. Animations consist of a number of different movements, each with a number of frames. 

move    the currently selected animation.
frame   the current animation frame.
nFrames the number of frames in the selected animation movement.

Depends on initialization with Ent.MakeActor.

func (*Ent) Actions added in v0.8.0 

func (e *Ent) Actions() []string

Actions returns the names of the different animations available to this Actor. An empty list is returned if the animation data has not yet been loaded.

Depends on initialization with Ent.MakeActor and loaded animation data.

func (*Ent) AddPart added in v0.8.0 

func (e *Ent) AddPart() *Ent

AddPart creates a new entity with a point-of-view component (pov). A pov adds a location and orientation to an entity. The entity can now be positioned and rotated.

The entity is also added to the scene graph so that this entities world pov is affected by its parents and will also affect any child entities created from this one.

func (*Ent) AddSky added in v0.8.0 

func (e *Ent) AddSky() *Ent

AddSky adds one sky dome to a 3D scene entity. A sky is an optional pov with static model that is rendered prior to and behind all other scene objects. It uses the scene camera rotation and ignores the camera location.

The returned entity expects to be populated with a sky dome model and sky texture. Nil is returned if the scene is not 3D.

func (*Ent) Alpha added in v0.8.0 

func (e *Ent) Alpha() float64

Alpha returns the alpha value for this model entity.

Depends on Ent.MakeModel. Returns 0 if there is no model component.

func (*Ent) Animate added in v0.8.0 

func (e *Ent) Animate(move, frame int) bool

Animate requests a particular animation for the model. Returns true if the requested animation was available.

Depends on initialization with Ent.MakeActor and loaded animation data.

func (*Ent) AsTex added in v0.8.0 

func (e *Ent) AsTex(on bool) *Ent

AsTex controls the scene render output. Use on=true to render the scene to a texture buffer. The scene can now be used as a texture for a model in another scene. The default is to render the scene to the display buffer.

Depends on Eng.AddScene.

func (*Ent) At added in v0.8.0 

func (e *Ent) At() (x, y, z float64)

At gets the local space location. This is world space if the entity does not have a parent.

Depends on Ent.AddPart. Returns 0,0,0 if there is no part component.

func (*Ent) Body added in v0.8.0 

func (e *Ent) Body() Body

Body returns the physics body for this entity, returning nil if no physics body exists.

func (*Ent) Cam added in v0.8.0 

func (e *Ent) Cam() *Camera

Cam returns the camera instace for a scene, returning nil if the entity is not a scene.

Depends on Eng.AddScene.

func (*Ent) Cast added in v0.8.0 

func (e *Ent) Cast(ray Body) (hit bool, x, y, z float64)

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

Depends on Ent.MakeBody.

func (*Ent) Clamp added in v0.8.0 

func (e *Ent) Clamp(name string) *Ent

Clamp a texture instead of using the default repeating texture. Expected to be called after a model with texture assets has been defined, but before the model assets have been loaded. Ie: something that is set before first use, not for flipping back and forth.

func (*Ent) Cull added in v0.8.0 

func (e *Ent) Cull(culled bool)

Cull sets the culled state.

Depends on Ent.AddPart.

func (*Ent) Culled added in v0.8.0 

func (e *Ent) Culled() bool

Culled returns true if entity has been culled from rendering.

Depends on Ent.AddPart. Returns true if there was no part component.

func (*Ent) Dispose added in v0.8.0 

func (e *Ent) Dispose()

Dispose all components for this entity. If the entity is a scene or a part with child entities, then all child entities are also disposed.

func (*Ent) DisposeBody added in v0.8.0 

func (e *Ent) DisposeBody()

DisposeBody removes the physics body from the given entity. Does nothing if there was no physics body.

func (*Ent) Exists added in v0.8.0 

func (e *Ent) Exists() bool

Exists returns true if the entity has been created and not yet disposed.

func (*Ent) GenMesh added in v0.8.0 

func (e *Ent) GenMesh(name string) *Mesh

GenMesh is used to create a mesh where the data is filled by the application instead of the loader. Does nothing if the original MakeModel call already loaded a mesh.

Depends on Ent.MakeModel. Returns nil if missing model component.

func (*Ent) GenTex added in v0.8.0 

func (e *Ent) GenTex(name string) *Texture

GenTex is used to create a mesh where the data is filled by the application instead of the loader. Can be called on an existing model entity.

Depends on Ent.MakeModel. Returns nil if missing model component.

func (*Ent) Is2D added in v0.8.0 

func (e *Ent) Is2D() bool

Is2D returns true if the entity is a UI scene. 2D scenes are used to draw information over a 3D scene.

Depends on Eng.AddScene.

func (*Ent) Load added in v0.8.0 

func (e *Ent) Load(assets ...string) *Ent

Load more model assets after the model has been created. The assets can be in any order and are prefixed with an asset type. Names must be unique within an asset type. 

msh: "msh:name" - one per model.
tex: "txt:name" - 0 to 14 per model.
mat: "mat:name" - 0 to 1 per model.

Depends on Ent.MakeModel.

func (*Ent) MakeActor added in v0.8.0 

func (e *Ent) MakeActor(shader, actor string) *Ent

MakeActor creates an animated model associated with this Entity. Actor is a specialized static Model that combines a mesh with animation data and an animation aware shader. 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. 

shader: animation aware shader eg: "anim".
actor : name of the actor animation data file and actor texture.
        eg: "actor" finds models/actor.anm and images/actor0.png

func (*Ent) MakeBody added in v0.8.0 

func (e *Ent) MakeBody(b Body) *Ent

MakeBody creates non-colliding body associated with this Entity. Bodies are generally set on top level pov transforms which always have valid world coordindates. 

b: a physics body eg: vu.Box, vu.Sphere.

func (*Ent) MakeEffect added in v0.8.0 

func (e *Ent) MakeEffect(shader, texture string) *Ent

MakeEffect adds an particle effect component to an entity. Effect is a model that uses point based vertex data to display, move, create, and destroy, a bunch of small images. 

shader : particle effect capable shader.
texture: particle texture applied to each particle.

func (*Ent) MakeLabel added in v0.8.0 

func (e *Ent) MakeLabel(shader, font string) *Ent

MakeLabel adds a label component to an entity. It is intended for single words or small phrases. 

shader: a font aware shader like "txt" or "sdf".
font  : identifies the font mapping file and font texture file, eg:
        "lucidiaSu22" -> source/lucidiaSu22.fnt images/lucidiaSu22.png

Internally it is a model with a quad mesh that displays a series of characters mapped from a font texture file. Manipulating a label amounts to setting the string value and centering it using its width in pixels. The default color is white: 1,1,1.

Consider using a signed-distance-field (sdf) shader plus matching texture data to reduce pixelization for 3D labels.

func (*Ent) MakeLight added in v0.8.0 

func (e *Ent) MakeLight() *Ent

MakeLight adds a light component to an entity. Light is used by shaders to interact with a models material values. Internally light is has a position and orientation in world space. Light is defaulted to white 1,1,1. See SetLightColor.

func (*Ent) MakeModel added in v0.8.0 

func (e *Ent) MakeModel(shader string, attrs ...string) *Ent

MakeModel adds a model component to an entity. The following assets can be loaded into a model. The first parameter is the shader asset name. The remaining assets can be in any order and are prefixed with an asset type. Names must be unique within an asset type. 

shd: first parameter, "name" of shader - one per model.
msh: "msh:name" - one per model.
tex: "tex:name" - 0 to 14 per model.
mat: "mat:name" - 0 or 1 per model.

A model manages rendered 3D objects. It is the link between loaded assets and the data needed by the rendering system for the shader. Assets, such as shaders, mesh, textures, etc., are specified as unique strings. The assets are located, loaded, and converted to intermediate data which is later converted to render draws for the render system.

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.

A model is attached to an entity with a point-of-view to give it a 3D location and orientation.

func (*Ent) Mesh added in v0.8.0 

func (e *Ent) Mesh() *Mesh

Mesh returns the vertex data for an entity with a model component. The Mesh will be marked for rebinding as the expected reason to get a mesh is to modify it.

Depends on Ent.MakeModel. Returns nil if missing model component.

func (*Ent) Move added in v0.8.0 

func (e *Ent) 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.

Depends on Ent.AddPart.

func (*Ent) PlaySound added in v0.8.0 

func (e *Ent) PlaySound(soundID uint32)

PlaySound plays the given sound at this entities location. 

soundID : entity created with Eng.AddSound.

Depends on Ent.AddPart.

func (*Ent) Pose added in v0.8.0 

func (e *Ent) Pose(index int) *lin.M4

Pose returns the bone transform, or the identity matrix if there was no transform for the model. The returned matrix should not be altered. It is intended for transforming points.

Depends on initialization with Ent.MakeActor.

func (*Ent) Push added in v0.8.0 

func (e *Ent) Push(x, y, z float64)

Push adds to the body's linear velocity. It is a wrapper for physics.Body.Push

Depends on Ent.MakeBody.

func (*Ent) Scale added in v0.8.0 

func (e *Ent) Scale() (x, y, z float64)

Scale retrieves the local per-axis scale values at 3 separate XYZ values. World scale needs to incorporate any parents values.

Depends on Ent.AddPart. Returns 0,0,0 if there is no part component.

func (*Ent) SetAlpha added in v0.8.0 

func (e *Ent) SetAlpha(a float64) *Ent

SetAlpha sets the alpha value for this model entity.

Depends on Ent.MakeModel. Sets nothing if there is no model component.

func (*Ent) SetAt added in v0.8.0 

func (e *Ent) SetAt(x, y, z float64) *Ent

SetAt sets the local space location, ie: relative to its parent. This is world space if there is no parent location.

Depends on Ent.AddPart.

func (*Ent) SetColor added in v0.8.0 

func (e *Ent) SetColor(r, g, b float64) *Ent

SetColor sets a model component material color where the r,g,b values are from 0-1.

Depends on Ent.MakeModel.

func (*Ent) SetCuller added in v0.8.0 

func (e *Ent) SetCuller(culler Culler)

SetCuller sets a method that reduces the number of Models rendered each update. It can be application supplied or engine supplied.

Depends on Eng.AddScene.

func (*Ent) SetDraw added in v0.8.0 

func (e *Ent) SetDraw(mode int) *Ent

SetDraw affects rendered meshes by rendering with Triangles, Lines, Points. The default mode is Triangles.

Depends on Ent.MakeModel.

func (*Ent) SetFirst added in v0.8.0 

func (e *Ent) SetFirst(name string) *Ent

SetFirst ensures that the named texture is at texture position 0. Position 0 is the texture position most shaders use to color a model. This allows models to have multiple textures and change from displaying one texture to another. The order of the remaining textures is not guaranteed.

Nothing happens if the texture is invalid. Expected to be called after textures have been loaded.

Depends on Ent.MakeModel.

func (*Ent) SetLightColor added in v0.8.0 

func (e *Ent) SetLightColor(r, g, b float64) *Ent

SetLightColor sets the light component color using the r,g,b values from 0-1.

Depends on Ent.MakeLight.

func (*Ent) SetListener added in v0.8.0 

func (e *Ent) SetListener()

SetListener sets the location of the sound listener to be this entity.

Depends on Ent.AddPart.

func (*Ent) SetMover added in v0.8.0 

func (e *Ent) SetMover(mover Mover, maxParticles int) *Ent

SetMover ties the optional particle effect updater to this entity. Ignored if there is already a particle effect mover for this entity.

func (*Ent) SetOrtho added in v0.8.0 

func (e *Ent) SetOrtho() *Ent

SetOrtho configures the scene to use a 3D orthographic projection.

Depends on Eng.AddScene.

func (*Ent) SetOver added in v0.8.0 

func (e *Ent) SetOver(over uint8) *Ent

SetOver draws this scene over scenes with lower values. Default value for a 3D scene is 0, a 2D scene is 1.

Depends on Eng.AddScene.

func (*Ent) SetScale added in v0.8.0 

func (e *Ent) SetScale(x, y, z float64) *Ent

SetScale assigns the XYZ per-axis scale values. Scale default is 1, greater than 1 enlarges, a positive fraction shrinks.

Depends on Ent.AddPart.

func (*Ent) SetShadows added in v0.8.0 

func (e *Ent) SetShadows() *Ent

SetShadows enables models casting and receiving shadows for a scene component. Requests for shadows on 2D scenes are logged.

Depends on Eng.AddScene.

func (*Ent) SetSolid added in v0.8.0 

func (e *Ent) SetSolid(mass, bounce float64)

SetSolid makes the existing physics Body collide.

Depends on Ent.MakeBody.

func (*Ent) SetSpin added in v0.8.0 

func (e *Ent) SetSpin(x, y, z float64)

SetSpin sets the rotation to 0 before spinning the entity like the Spin method.

Depends on Ent.AddPart.

func (*Ent) SetTex added in v0.8.0 

func (e *Ent) SetTex(scene *Ent) *Ent

SetTex assigns the model a texture that has been generated from a scene and which already exists on the GPU. Ignored if there is already a texture assigned to the model.

Depends on Ent.MakeModel. 

scene : depends on Eng.AddScene.

func (*Ent) SetUI added in v0.8.0 

func (e *Ent) SetUI() *Ent

SetUI configures a scene to be 2D and drawn over 3D scenes using an orthographic projection.

Depends on initialization with Eng.AddScene.

func (*Ent) SetUniform added in v0.8.0 

func (e *Ent) SetUniform(id string, floats ...interface{}) *Ent

SetUniform combines floats values into a slice of float32's that will be passed to rendering and used to set shader uniform values.

Depends on Ent.MakeModel.

func (*Ent) SetView added in v0.8.0 

func (e *Ent) SetView(q *lin.Q) *Ent

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

Depends on Ent.AddPart.

func (*Ent) SetWrap added in v0.8.0 

func (e *Ent) SetWrap(w int) *Ent

SetWrap sets the string wrap length in pixels.

Depends on Ent.MakeLabel.

func (*Ent) Size added in v0.8.0 

func (e *Ent) Size() (w, h int)

Size returns the Label width, height in pixels. Returns 0 if not loaded or the Label is the empty string.

Depends on Ent.MakeLabel.

func (*Ent) Spin added in v0.8.0 

func (e *Ent) 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.

Depends on Ent.AddPart.

func (*Ent) Tex added in v0.8.0 

func (e *Ent) Tex(index int) *Texture

Tex returns the texture for an entity with a model component and a texture at the given index. The Texture will be marked for rebinding as the expected reason to get a texture is to modify it.

Depends on Ent.MakeModel. Returns nil if missing model component.

func (*Ent) Typeset added in v0.8.0 

func (e *Ent) Typeset(s string) *Ent

Typeset the given string, setting the labels string and regenerating the existing mesh. Will cause a mesh rebind.

Depends on Ent.MakeLabel.

func (*Ent) View added in v0.8.0 

func (e *Ent) 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.

Depends on Ent.AddPart.

func (*Ent) World added in v0.8.0 

func (e *Ent) World() (wx, wy, wz float64)

World returns the world space coordinates for this entity. World space is recalculated after every update.

Depends on Ent.AddPart.

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     // Update delta time in seconds. Set on create.
	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 Mesh added in v0.6.5 

type Mesh struct {
	// contains filtered or unexported fields
}

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 rendering. 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.

A mesh is expected to be referenced by multiple models and thus does not contain any instance information like location or scale. A mesh is most often created by the asset pipeline from disk based files that were in turn created by tools like Blender.

func (*Mesh) InitData added in v0.6.5 

func (m *Mesh) InitData(lloc, span, usage uint32, normalize bool) *Mesh

InitData creates a vertex data buffer.

func (*Mesh) InitFaces added in v0.6.5 

func (m *Mesh) InitFaces(usage uint32) *Mesh

InitFaces creates a triangle face index buffer. Must be called before calling SetFaces.

func (*Mesh) SetData added in v0.6.5 

func (m *Mesh) SetData(lloc uint32, data interface{})

SetData stores data in the specified vertex buffer. May be called one or more times after a one-time call to InitData. Marks the mesh as needing a rebind.

func (*Mesh) SetFaces added in v0.6.5 

func (m *Mesh) SetFaces(data []uint16)

SetFaces stores data for a triangle face index buffer. May be called one or more times after a one-time call to InitFaces. Marks the mesh as needing a rebind.

type Mover added in v0.8.0 

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

Mover is used to update CPU particle effects. It is the application that does the work of controlling particle lifespans and positions. All particles are passed in and the active particles are returned. 

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

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 Mover. A slice of these are returned by the Mover update method to be rendered by the engine.

type Profile added in v0.8.0 

type Profile struct {
	Elapsed time.Duration // Total time since last update.
	Update  time.Duration // Time used by last update.

	// Key indication that the application is asking to much from the
	// underlying platform. A non-zero value means the game is running
	// slower than desired.
	Skipped int // Updates skipped since last update.

	// The number of renders completed and the real time used.
	Renders int           // Renders completed since last update.
	Render  time.Duration // Render time used since last update.
}

Profile is used to collect timing values while the application is running. The numbers are reset each update. Applications are expected to track and smooth these per-update values over a number of updates.

In general expect things to go slower on slower machines and slower as the number of models, draw calls, and verticies increases.

FPS = Renders/Elapsed. When all is well the number of renders matches the monitor refresh rate, which is 60fps, for most flat screens. Skipped updates indicate when the program is overwhelming the platform it is running on and also means the game is slowing down.

func (*Profile) Dump added in v0.8.0 

func (p *Profile) Dump()

Dump current amount of update loop time, tracked in milliseconds, to the console. Times are expected to be reset each update. Expected to be used for development debugging.

func (*Profile) Modelled added in v0.8.0 

func (p *Profile) Modelled(eng Eng) (models, tris, verts int)

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

func (*Profile) Rendered added in v0.8.0 

func (p *Profile) Rendered(eng Eng) (models, tris, verts int)

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

func (*Profile) Zero added in v0.8.0 

func (p *Profile) Zero()

Zero all time and counter values. Called by the engine after each application update callback.

type State 

type State struct {
	X, Y, W, H int  // Window lower left corner and size in pixels.
	Cursor     bool // True when cursor is visible.
	CullBacks  bool // True to set backface culling on.
	Blend      bool // True for texture blending.
	Full       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 Texture added in v0.8.0 

type Texture struct {
	// contains filtered or unexported fields
}

Texture manages the link between loaded texture assets and textures bound to the GPU.

Texture is an 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 entity and consumed by a shader.

func (*Texture) Set added in v0.8.0 

func (t *Texture) Set(img image.Image)

Set replaces the texture image - no questions asked. Marks the texture as needing to be updated on the GPU.

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.
Package tools holds independent utilities that complement the vu engine.
 Package tools holds independent utilities that complement the vu engine.
sdf
Package sdf generates signed distance field images and font description text files from a pair of angle code bmfont font files.
 Package sdf generates signed distance field images and font description text files from a pair of angle code bmfont font files.

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.