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
- func Run(app App) (err error)
- func Symbol(keycode int) rune
- type App
- type Body
- type Camera
- func (c *Camera) At() (x, y, z float64)
- func (c *Camera) Distance(wx, wy, wz float64) float64
- func (c *Camera) Lookat() *lin.Q
- func (c *Camera) Move(x, y, z float64, q *lin.Q)
- func (c *Camera) Ray(mx, my, ww, wh int) (x, y, z float64)
- func (c *Camera) Screen(wx, wy, wz float64, ww, wh int) (sx, sy int)
- func (c *Camera) SetAt(x, y, z float64) *Camera
- func (c *Camera) SetClip(near, far float64) *Camera
- func (c *Camera) SetFov(deg float64) *Camera
- func (c *Camera) SetPitch(deg float64) *Camera
- func (c *Camera) SetYaw(deg float64) *Camera
- type Culler
- type Eng
- type EngAttr
- func Color(r, g, b, a float32) EngAttr
- func CursorAt(x, y int) EngAttr
- func CursorOn(show bool) EngAttr
- func Gravity(g float64) EngAttr
- func Mute(mute bool) EngAttr
- func On(attr uint32, enabled bool) EngAttr
- func Size(x, y, w, h int) EngAttr
- func Title(t string) EngAttr
- func ToggleFullScreen() EngAttr
- func Volume(zeroToOne float64) EngAttr
- type Ent
- func (e *Ent) Action() (move, frame, nFrames int)
- func (e *Ent) Actions() []string
- func (e *Ent) AddPart() *Ent
- func (e *Ent) AddSky() *Ent
- func (e *Ent) Alpha() float64
- func (e *Ent) Animate(move, frame int) bool
- func (e *Ent) AsTex(on bool) *Ent
- func (e *Ent) At() (x, y, z float64)
- func (e *Ent) Body() Body
- func (e *Ent) Cam() *Camera
- func (e *Ent) Cast(ray Body) (hit bool, x, y, z float64)
- func (e *Ent) Clamp(name string) *Ent
- func (e *Ent) Cull(culled bool)
- func (e *Ent) Culled() bool
- func (e *Ent) Dispose()
- func (e *Ent) DisposeBody()
- func (e *Ent) DrawInstances(instances int) *Ent
- func (e *Ent) Exists() bool
- func (e *Ent) GenMesh(name string) *Mesh
- func (e *Ent) GenTex(name string) *Texture
- func (e *Ent) Is2D() bool
- func (e *Ent) Load(assets ...string) *Ent
- func (e *Ent) MakeActor(shader, actor string) *Ent
- func (e *Ent) MakeBody(b Body) *Ent
- func (e *Ent) MakeEffect(shader, texture string) *Ent
- func (e *Ent) MakeInstancedModel(shader string, attrs ...string) *Ent
- func (e *Ent) MakeLabel(shader, font string) *Ent
- func (e *Ent) MakeLight(kindOfLight int) *Ent
- func (e *Ent) MakeModel(shader string, attrs ...string) *Ent
- func (e *Ent) Mesh() *Mesh
- func (e *Ent) Move(x, y, z float64, dir *lin.Q)
- func (e *Ent) PlaySound(soundID uint32)
- func (e *Ent) Pose(index int) *lin.M4
- func (e *Ent) Push(x, y, z float64)
- func (e *Ent) Scale() (x, y, z float64)
- func (e *Ent) SetAa(x, y, z, angleInRadians float64) *Ent
- func (e *Ent) SetAlpha(a float64) *Ent
- func (e *Ent) SetAt(x, y, z float64) *Ent
- func (e *Ent) SetColor(r, g, b float64) *Ent
- func (e *Ent) SetConeAngles(innerAngle, outerAngle float64) *Ent
- func (e *Ent) SetCuller(culler Culler)
- func (e *Ent) SetDraw(mode int) *Ent
- func (e *Ent) SetFirst(name string) *Ent
- func (e *Ent) SetLightAttenuation(kc, kl, kq float64) *Ent
- func (e *Ent) SetLightColor(r, g, b float64) *Ent
- func (e *Ent) SetLightIntensity(ambient, diffuse, specular float64) *Ent
- func (e *Ent) SetListener()
- func (e *Ent) SetMover(mover Mover, maxParticles int) *Ent
- func (e *Ent) SetOrtho() *Ent
- func (e *Ent) SetOver(over uint8) *Ent
- func (e *Ent) SetScale(x, y, z float64) *Ent
- func (e *Ent) SetScissor(x, y, w, h int) *Ent
- func (e *Ent) SetShadows() *Ent
- func (e *Ent) SetSolid(mass, bounce float64)
- func (e *Ent) SetSpin(x, y, z float64) *Ent
- func (e *Ent) SetStr(s string) *Ent
- func (e *Ent) SetTex(scene *Ent) *Ent
- func (e *Ent) SetTrigger(value bool)
- func (e *Ent) SetUI() *Ent
- func (e *Ent) SetUniform(id string, floats ...interface{}) *Ent
- func (e *Ent) SetView(q *lin.Q) *Ent
- func (e *Ent) SetWrap(w int) *Ent
- func (e *Ent) Size() (w, h int)
- func (e *Ent) Spin(x, y, z float64)
- func (e *Ent) Texture(index int) *Texture
- func (e *Ent) View() (q *lin.Q)
- func (e *Ent) World() (wx, wy, wz float64)
- func (e *Ent) WorldRot() (q *lin.Q)
- type Input
- type Mesh
- type Mover
- type Particle
- type Profile
- type State
- type Texture
Constants ¶
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.
const ( DirectionalLight = iota PointLight SpotLight )
Types of lights
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 ¶
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.
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 ¶
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 ¶
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 ¶
Plane creates a plane located on the origin and oriented by the plane normal nx, ny, nz.
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) Distance ¶
Distance returns the distance squared of the camera to the given Pov. Uses the existing Pov world coordinates.
func (*Camera) Lookat ¶
Lookat returns an orientation which is good for flying around. It is a combination of Pitch and Yaw.
func (*Camera) Move ¶
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 ¶
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 ¶
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) SetClip ¶
SetClip sets the near and far clipping planes for perspective and orthographic cameras.
func (*Camera) SetFov ¶
SetFov sets the field of view for perspective projection cameras. Ignored for orthographic projection cameras.
type Culler ¶
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 ¶
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 ¶
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 ¶
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 CursorAt ¶
CursorAt places the cursor at the window pixel x,y. Engine attribute for use in Eng.Set().
func On ¶
On enables/disables render attributes like Blend, CullFace, etc... Engine attribute for use in Eng.Set().
func Size ¶
Size sets the window starting location and size in pixels. For windowed mode. Engine attribute for use in Eng.Set().
func ToggleFullScreen ¶
func ToggleFullScreen() EngAttr
ToggleFullScreen flips full screen and windowed mode. Engine attribute for use in Eng.Set().
type Ent ¶
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, SetAa, Spin, SetSpin, Scale, SetScale,
Model : MakeModel attaches model data to a part entity.
MakeModel, Load, Mesh, GenMesh, GenTex, SetTex, SetFirst, SetUniform, Alpha, SetAlpha, SetColor, SetDraw, Clamp, MakeInstancedModel, DrawInstances.
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 creates and attaches light data to a scene entity.
MakeLight, AffectAmbient, AffectDiffuse, AffectSpecular. SetAttenuation - for PointLights and SpotLights SetCutoffs - for SpotLights
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 ¶
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 ¶
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 ¶
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 ¶
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 while ignoring the scene camera location.
The returned entity expects to be populated with a sky dome model and sky texture. Nil is returned if the entity is not a 3D scene or if there is already a sky dome attached to the scene.
func (*Ent) Alpha ¶
Alpha returns the alpha value for this model entity.
Depends on Ent.MakeModel. Returns 0 if there is no model component.
func (*Ent) Animate ¶
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 ¶
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 ¶
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 ¶
Body returns the physics body for this entity, returning nil if no physics body exists.
func (*Ent) Cam ¶
Cam returns the camera instace for a scene, returning nil if the entity is not a scene.
Depends on Eng.AddScene.
func (*Ent) Cast ¶
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 ¶
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) Culled ¶
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 ¶
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 ¶
func (e *Ent) DisposeBody()
DisposeBody removes the physics body from the given entity. Does nothing if there was no physics body.
func (*Ent) DrawInstances ¶
DrawInstances overrides the number of instances that will be drawn. This applies to instanced models created with MakeInstancedModel. The value must be less or equal to the the number of child parts for this Ent. Setting to 0 (default) draws all instances.
Depends on Ent.MakeInstancedModel.
func (*Ent) GenMesh ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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) MakeInstancedModel ¶
MakeInstancedModel is similar to MakeModel except this model is marked as having multiple instances that will be rendered in a single draw call. An instanced model needs child Parts to be rendered. Each child Part provides the instance transform data (postion,rotation,scale) for one instance of this model.
This model cannot be a composite model in that its child Parts do not have models - only transform data. Works only with the default SetDraw mode of Triangles.
func (*Ent) MakeLabel ¶
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 ¶
MakeLight adds a light to a scene, creating and returning a new Part on the given scene entity. Lighting aware shaders combine the lights a models material values. All objects in the scene with lighting capable shades will be influenced by the light.
Internally light is has a position and orientation in world space. The default position is 0,0,0 and the default direction is 0,0,-1. A lights default color is white 1,1,1.
Depends on Eng.AddScene.
func (*Ent) MakeModel ¶
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 ¶
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 ¶
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 ¶
PlaySound plays the given sound at this entities location.
soundID : entity created with Eng.AddSound.
Depends on Ent.AddPart.
func (*Ent) Pose ¶
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 ¶
Push adds to the body's linear velocity. It is a wrapper for physics.Body.Push
Depends on Ent.MakeBody.
func (*Ent) Scale ¶
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) SetAa ¶
SetAa sets the orientation using the given axis and angle information.
Depends on Ent.AddPart.
func (*Ent) SetAlpha ¶
SetAlpha sets the alpha value for this model entity.
Depends on Ent.MakeModel. Sets nothing if there is no model component.
func (*Ent) SetAt ¶
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 ¶
SetColor sets a model component material color where the r,g,b values are from 0-1.
Depends on Ent.MakeModel.
func (*Ent) SetConeAngles ¶
SetConeAngles sets the area affected by a spotlight in degrees. The cone angles affects the size of the spot light, where the outerAngle is expected to be slightly larger than the innerAngle in order to create a blur around the edges of the spotlight.
Depends on Ent.MakeLight(SpotLight).
func (*Ent) SetCuller ¶
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 ¶
SetDraw affects rendered meshes by rendering with Triangles, Lines, Points. The default mode is Triangles.
Depends on Ent.MakeModel.
func (*Ent) SetFirst ¶
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) SetLightAttenuation ¶
SetLightAttenuation sets the lights constant, linear and quadratic attenuation factors: kc,kl,kq. Attenuation reduces the effect of light as distance increases. This affects PointLights and SpotLights.
Depends on Ent.MakeLight(SpotLight or PointLight).
func (*Ent) SetLightColor ¶
SetLightColor assigns a color to the light. The lights color is combined with objects material color to produce a final color. The R,G,B light values are between 0 (no color), and 1 (full color).
Depends on Ent.MakeLight.
func (*Ent) SetLightIntensity ¶
SetLightIntensity scales the amount of light affecting each component of the lighting model. The values are between 0 (dark) and 1 (full intensity).
Depends on Ent.MakeLight.
func (*Ent) SetListener ¶
func (e *Ent) SetListener()
SetListener sets the location of the sound listener to be this entity.
Depends on Ent.AddPart.
func (*Ent) SetMover ¶
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 ¶
SetOrtho configures the scene to use a 3D orthographic projection.
Depends on Eng.AddScene.
func (*Ent) SetOver ¶
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 ¶
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) SetScissor ¶
SetScissor restricts the scene to the given screen area. Scissor can be disabled by setting all values to 0. Any negative parameter values causes the call to be ignored.
Depends on Eng.AddScene.
func (*Ent) SetShadows ¶
SetShadows enables models casting and receiving shadows for a 3D scene. Invalid requests are logged. Returns the calling entity instance.
Depends on Eng.AddScene.
func (*Ent) SetSpin ¶
SetSpin sets the rotation to 0 before spinning the entity like the Spin method.
Depends on Ent.AddPart.
func (*Ent) SetStr ¶
SetStr the given string, setting the labels string and regenerating the existing mesh. Will cause a mesh rebind.
Depends on Ent.MakeLabel.
func (*Ent) SetTex ¶
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) SetTrigger ¶ added in v0.0.2
func (*Ent) SetUI ¶
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 ¶
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 ¶
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) Size ¶
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 ¶
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) Texture ¶
Texture returns the texture image at the given index for an entity. 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 or texture.
func (*Ent) View ¶
View returns the orientation of the Part. Orientation is a rotation about a axis. Orientation is relative to any parent Parts. It is world space if there is no parent orientation. Direct updates to the rotation matrix must be done with SetView or SetAa.
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 ¶
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 change the data. 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) InitFaces ¶
InitFaces creates a triangle face index buffer. Must be called before calling SetFaces.
func (*Mesh) InitInstances ¶
InitInstances allocates space for an array of instance transform matricies. The instance data needs to be set using SetData where the float data is an array of 4x4 transform matricies.
type Mover ¶
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 ¶
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 ¶
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 ¶
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.
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().
type Texture ¶
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.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package ai provides support for autonomous application unit behaviour.
|
Package ai provides support for autonomous 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 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 angel code bmfont font files.
|
Package sdf generates signed distance field images and font description text files from a pair of angel code bmfont font files. |