render

Documentation

Overview

Package render provides access to 3D graphics. It encapsulates and provides a common interface to graphic card programming APIs like OpenGL or DirectX. Render is OS indepdent. It relies on OS specific graphics contexts to be created by vu/device.

Package render is provided as part of the vu (virtual universe) 3D engine.

Index

• Constants
• func SortDraws(frame []*Draw)
• type Context
  • func New() Context
• type Data
  • func NewFaceData(usage uint32) Data
  • func NewVertexData(lloc, span, usage uint32, normalize bool) Data
• type Draw
  • func NewDraw() *Draw
  • func (d *Draw) SetCounts(faces, verts int)
  • func (d *Draw) SetDbm(dbm *lin.M4)
  • func (d *Draw) SetFloats(key string, floats ...float32)
  • func (d *Draw) SetMv(mv *lin.M4)
  • func (d *Draw) SetMvp(mvp *lin.M4)
  • func (d *Draw) SetPm(pm *lin.M4)
  • func (d *Draw) SetPose(pose []lin.M4)
  • func (d *Draw) SetRefs(shader, meshes uint32, mode int)
  • func (d *Draw) SetScale(sx, sy, sz float64)
  • func (d *Draw) SetShadowmap(tid uint32)
  • func (d *Draw) SetTex(count, index, order int, tid, f0, fn uint32)
  • func (d *Draw) SetUniforms(u map[string]int32)
• type Mvp
  • func NewMvp() Mvp

Constants

const (
	// Values useed in Renderer.Enable() method.
	Blend     uint32 = gl.BLEND              // Alpha blending.
	CullFace         = gl.CULL_FACE          // Backface culling.
	DepthTest        = gl.DEPTH_TEST         // Z-buffer (depth) awareness.
	PointSize        = gl.PROGRAM_POINT_SIZE // Enable gl_PointSize in shaders.

	// Vertex data render hints. Used in the Buffer.SetUsage() method.
	StaticDraw  = gl.STATIC_DRAW  // Data created once and rendered many times.
	DynamicDraw = gl.DYNAMIC_DRAW // Data is continually being updated.
)

Renderer implementation specific constants.

const (
	// Draw modes for vertex data rendering. Used in Draw.SetRefs.
	Triangles = iota // Triangles are the default for 3D models.
	Points           // Points are used for particle effects.
	Lines            // Lines are used for drawing wireframe shapes.

	// BindFrame buffer types.
	DepthBuffer        // For depth only.
	ImageBuffer        // For color and depth.
	LayerSize   = 1024 // Render pass texture size.
)

Renderer implementation independent constants.

Functions

func SortDraws

func SortDraws(frame []*Draw)

SortDraws sorts draw requests by buckets then by distance to camera, and finally by object creation order with earlier objects rendered before later objects.

Types

type Context

type Context interface {
	Init() (err error)               // Call first, once at startup.
	Clear()                          // Clear all buffers before rendering.
	Color(r, g, b, a float32)        // Set the default render clear color
	Enable(attr uint32, enable bool) // Enable or disable graphic state.
	Viewport(width int, height int)  // Set the available screen real estate.

	// Rendering works with uniform values and data bound to the GPU.
	BindMesh(vao *uint32, vdata map[uint32]Data, fdata Data) error
	BindShader(vsh, fsh []string, uniforms map[string]int32,
		layouts map[string]uint32) (program uint32, err error)
	BindTexture(tid *uint32, img image.Image) error
	SetTextureMode(tid uint32, clamp bool)
	Render(d *Draw) // Render bound data, textures with bound shaders.

	// BindMap creates a framebuffer object with an associated
	// texture that can be used for shadow maps.
	//   fbo : returned frame buffer object identifier.
	//   tid : returned texture identifier.
	BindMap(fbo, tid *uint32) error

	// BindTarget creates a framebuffer object that can be used
	// as a render target.
	//   fbo : returned frame buffer object identifier.
	//   tid : returned texture identifier.
	//   db  : returned depth buffer render buffer.
	BindTarget(fbo, tid, db *uint32) error

	// Releasing frees up previous bound graphics card data.
	ReleaseMesh(vao uint32)            // Free bound vao reference.
	ReleaseShader(sid uint32)          // Free bound shader reference.
	ReleaseTexture(tid uint32)         // Free bound texture reference.
	ReleaseMap(fbo, tid uint32)        // Free shadow map framebuffer.
	ReleaseTarget(fbo, tid, db uint32) // Free render target framebuffer.
}

Context is used to draw 3D model objects within a graphics context. The expected usage is along the lines of:

• Initialize the graphics layer.
• Create some 3D models by binding graphics data to the GPU.
• Render the 3D models many times a second.

func New

func New() Context

New provides the render implementation as determined by the build.

type Data

type Data interface {
	Set(data interface{}) // Copy data in. Invalid types are logged.
	Len() int             // Number of elements.
	Size() uint32         // Number of bytes
}

Data carries the buffer data that is bound/copied to the GPU. Data is expected to be instances from NewVertexData or NewFaceData. A model is often comprised of multiple sets of data.

func NewFaceData

func NewFaceData(usage uint32) Data

NewFaceData creates and specifies usagefor a set of triangle faces. Triangle faces contain vertex indicies ordered to draw triangles. Data can now be loaded and updated using Data.Set().

usage     : STATIC or DYNAMIC

func NewVertexData

func NewVertexData(lloc, span, usage uint32, normalize bool) Data

NewVertexData creates and specifies usage for a set of vertex data. Vertex data can be the vertex positions or per-vertex data points like normals or UV texture information. Data can now be loaded and updated using Data.Set().

lloc      : shader layout location index.
span      : values per vertex.
usage     : STATIC or DYNAMIC
normalize : true to normalize data to the 0-1 range.

type Draw

type Draw struct {
	Shader uint32 // Bind reference for all shader programs.
	Vao    uint32 // Bind reference for all vertex buffers.
	Mode   int    // Points, Lines, Triangles
	Texs   []tex  // GPU bound texture references.
	Shtex  uint32 // GPU bound texture shadow depth map.
	Tag    uint32 // Application tag for debugging. Commonly an Entity id.

	// Shader uniform data.
	Uniforms map[string]int32     // Expected uniforms and shader references.
	Floats   map[string][]float32 // Uniform values.

	// Rendering hints.
	Bucket  uint64 // Used to sort draws. Lower buckets rendered first.
	Depth   bool   // True to render with depth.
	Fbo     uint32 // Framebuffer id. 0 for default.
	FaceCnt int32  // Number of triangles to be rendered.
	VertCnt int32  // Number of verticies to be rendered.

	// Transform data.
	Mv   *m4   // Model View.
	Mvp  *m4   // Model View projection.
	Pm   *m4   // Projection only.
	Dbm  *m4   // Depth bias matrix for shadow maps.
	Pose []m34 // Per render frame of animation bone data.
}

Draw holds the GPU references, shader uniforms, and the model-view-projection transforms needed for a single draw call. The GPU references are expected to have been obtained using render.Bind*() methods.

Only the data expected by the shader for this draw call has to be set. Draw provides setters to transform model data to the form needed for rendering. Often this means truncating float64 to float32.

Keep in mind that one draw call is often just one object in a scene and an entire scene needs to be redrawn 50 or 60 times a second. It is thus recommended to reuse allocated Draw instances where feasible by resetting the information as necessary before passing to Render.

func NewDraw

func NewDraw() *Draw

NewDraw allocates data needed for a single draw call. Scale is initialized to all 1's. Everything else is default.

func (*Draw) SetCounts

func (d *Draw) SetCounts(faces, verts int)

SetCounts specifies how many verticies and how many triangle faces for this draw object. This must match the vertex and face data.

faces  : Number of triangles to be rendered.
verts  : Number of verticies to be rendered.

func (*Draw) SetDbm

func (d *Draw) SetDbm(dbm *lin.M4)

SetDbm sets the depth bias matrix for shadow maps.

func (*Draw) SetFloats

func (d *Draw) SetFloats(key string, floats ...float32)

SetFloats sets the named shader uniform variable data.

func (*Draw) SetMv

func (d *Draw) SetMv(mv *lin.M4)

SetMv sets the Model-View transform.

func (*Draw) SetMvp

func (d *Draw) SetMvp(mvp *lin.M4)

SetMvp sets the Model-View-Projection transform.

func (*Draw) SetPm

func (d *Draw) SetPm(pm *lin.M4)

SetPm sets the Projection matrix.

func (*Draw) SetPose

func (d *Draw) SetPose(pose []lin.M4)

SetPose sets the Animation joint/bone transforms. It tries to reuse allocated model animation data where possible.

func (*Draw) SetRefs

func (d *Draw) SetRefs(shader, meshes uint32, mode int)

SetRefs of bound references

shader : Compiled, linked shader Program reference.
vao    : Vao ref for the mesh vertex buffers.
mode   : Render mode: Points, Lines, Triangles

func (*Draw) SetScale

func (d *Draw) SetScale(sx, sy, sz float64)

SetScale sets the scaling factors per axis.

func (*Draw) SetShadowmap

func (d *Draw) SetShadowmap(tid uint32)

SetShadowmap sets the texture id of the shadow map.

func (*Draw) SetTex

func (d *Draw) SetTex(count, index, order int, tid, f0, fn uint32)

SetTex assigns bound texture information for this draw reusing previously allocated memory where possible.

count  : Total number of textures for this draw.
index  : Texture index starting from 0.
tid    : Bound texture reference.
fn, f0 : Used for multiple textures on one mesh.

func (*Draw) SetUniforms

func (d *Draw) SetUniforms(u map[string]int32)

SetUniforms for the shader. String keys match the variables expected by the shader source. Each shader variable is expected to have corresponding values in SetFloats.

type Mvp

type Mvp interface {
	Set(tm *lin.M4) Mvp // Converts the transform matrix tm to internal data.
	Pointer() *float32  // A pointer to the internal transform data.
}

Mvp exposes the render matrix representation. This is needed by applications using the vu/render system, but not the vu engine.

func NewMvp

func NewMvp() Mvp

NewMvp creates a new internal render transform matrix. This is needed by applications using the vu/render system, but not the vu engine.