vu

package module
v0.0.4 Latest Latest
Warning

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

 Go to latest Published: Dec 11, 2022 License: BSD-2-Clause, Zlib Imports: 16 Imported by: 0

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. More getting started and background information is available on the Wiki

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/Kuzm1ch-dev/physic

Now you can build and run examples:

cd $GOPATH/src/github.com/Kuzm1ch-dev/physic/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.

Games

  • Bampf Open source reference game.
  • Jewel of Kings A game available for purchase from MacOS, iOS, and Windows stores.

Limitations

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

  • Vu is programmer centric. For example, there is no 3D asset editor. A working application is used as an editor replacement. Programmers create a working application with stub 3D assets. Artists and modellers then polish and finish the application by replacing the stub assets.
  • 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 (
	DirectionalLight = iota
	PointLight
	SpotLight
)

Types of lights

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 

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 

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 

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 

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 

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 

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 

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 

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 

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

SetAt positions the camera in world space The camera instance is returned.

func (*Camera) SetClip 

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

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

func (*Camera) SetFov 

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) *Camera

SetPitch sets the rotation around the X axis and updates the Look direction. The camera instance is returned.

func (*Camera) SetYaw 

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

SetYaw sets the rotation around the Y axis and updates the Look and Lookat directions. The camera instance is returned.

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 

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 

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 

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

Color sets the background window clear color. Engine attribute for use in Eng.Set().

func CursorAt 

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 

func CursorOn(show bool) EngAttr

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

func Gravity 

func Gravity(g float64) EngAttr

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

func Mute 

func Mute(mute bool) EngAttr

Mute toggles the sound volume. Engine attribute for use in Eng.Set().

func On 

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 

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 

func Title(t string) EngAttr

Title sets the window title. 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().

func Volume 

func Volume(zeroToOne float64) EngAttr

Volume sets the sound volume. 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 

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 

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 

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 

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

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 

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 

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 

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 

func (e *Ent) Body() Body

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

func (*Ent) Cam 

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 

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 

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 

func (e *Ent) Cull(culled bool)

Cull sets the culled state.

Depends on Ent.AddPart.

func (*Ent) Culled 

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 

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 

func (e *Ent) DrawInstances(instances int) *Ent

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) Exists 

func (e *Ent) Exists() bool

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

func (*Ent) GenMesh 

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 

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 

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 

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 

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 

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 

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) MakeInstancedModel 

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

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 

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 

func (e *Ent) MakeLight(kindOfLight int) *Ent

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 

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 

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 

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 

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 

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 

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 

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) SetAa 

func (e *Ent) SetAa(x, y, z, angleInRadians float64) *Ent

SetAa sets the orientation using the given axis and angle information.

Depends on Ent.AddPart.

func (*Ent) SetAlpha 

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 

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 

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) SetConeAngles 

func (e *Ent) SetConeAngles(innerAngle, outerAngle float64) *Ent

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 

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 

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 

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) SetLightAttenuation 

func (e *Ent) SetLightAttenuation(kc, kl, kq float64) *Ent

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 

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

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 

func (e *Ent) SetLightIntensity(ambient, diffuse, specular float64) *Ent

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 

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 

func (e *Ent) SetOrtho() *Ent

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

Depends on Eng.AddScene.

func (*Ent) SetOver 

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 

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) SetScissor 

func (e *Ent) SetScissor(x, y, w, h int) *Ent

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 

func (e *Ent) SetShadows() *Ent

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) SetSolid 

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

SetSolid makes the existing physics Body collide.

Depends on Ent.MakeBody.

func (*Ent) SetSpin 

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

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

Depends on Ent.AddPart.

func (*Ent) SetStr 

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

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 

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) SetTrigger added in v0.0.2 

func (e *Ent) SetTrigger(value bool)

func (*Ent) SetUI 

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 

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 

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 

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

SetWrap sets the string wrap length in pixels.

Depends on Ent.MakeLabel.

func (*Ent) Size 

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 

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) Texture 

func (e *Ent) Texture(index int) *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 

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

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.

func (*Ent) World 

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

World returns the world space coordinates for this entity. World space is recalculated immediately on any change.

Depends on Ent.AddPart.

func (*Ent) WorldRot 

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

WorldRot returns the world rotation for this entity. WorldRot space is recalculated immediately on any change and returns nil if the entity does not have a part.

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) InitData 

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

InitData creates a vertex data buffer.

func (*Mesh) InitFaces 

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

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

func (*Mesh) InitInstances 

func (m *Mesh) InitInstances(lloc uint32)

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.

func (*Mesh) SetData 

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 or InitInstances. Marks the mesh as needing a rebind.

func (*Mesh) SetFaces 

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 

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 

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.

func (*Profile) Rendered 

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

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

func (*Profile) Zero 

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 

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 

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

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.