render

Documentation

Overview

Package render provides access to 3D graphics. It encapsulates and provides a common interface to graphic card programming interfaces like OpenGL and DirectX.

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

Index

• Constants
• func SortDraws(frame []Draw)
• type Data
  • func NewFaceData(usage uint32) Data
  • func NewVertexData(lloc, span, usage uint32, normalize bool) Data
• type Draw
  • func NewDraw() Draw
• type Mvp
  • func NewMvp() Mvp
• type Renderer
  • func New() Renderer

Constants

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

	// Vertex data render hints. Used in the Buffer.SetUsage() method.
	STATIC  = gl.STATIC_DRAW  // Data created once and rendered many times.
	DYNAMIC = 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.

	// Render buckets. Lower values drawn first. Used in Draw.SetHints.
	OPAQUE      // draw first
	TRANSPARENT // draw after opaque
	OVERLAY     // draw last.
)

Renderer independent constants, ie: not specific to OpenGL or DirectX.

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 Data

type Data interface {
	Set(data interface{}) // Copy data in.
	Len() int             // Number of verticies
	Size() uint32         // Number of bytes
}

Data carries the buffer data that is bound/copied to the GPU. These can be vertex data, or triangle face data.

func NewFaceData

func NewFaceData(usage uint32) Data

NewFaceData creates and fixes settings for 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 fixes settings 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 interface {
	SetMv(mv *lin.M4)            // Model-View transform.
	SetMvp(mvp *lin.M4)          // Model-View-Projection transform.
	SetPm(pm *lin.M4)            // Projection matrix only.
	SetScale(sx, sy, sz float64) // Scaling, per axis.
	SetPose(pose []lin.M4)       // Animation joint/bone transforms.

	// SetHints affects how a draw is rendered.
	//   bucket : Sort order OPAQUE, TRANSPARENT, OVERLAY.
	//   toCam : Distance to Camera.
	//   depth : True to render with depth.
	SetHints(bucket int, tocam float64, depth bool)

	// SetCounts for bound references
	//   faces  : Number of triangles to be rendered.
	//   verts  : Number of verticies to be rendered.
	SetCounts(faces, verts int)
	// SetRefs of bound references
	//   shader : Program reference
	//   vao    : Vao ref for the mesh vertex buffers.
	//   mode   : POINTS, LINES, TRIANGLES
	SetRefs(shader, vao uint32, mode int)
	Vao() uint32 // The mesh vertex buffers reference.

	// SetTex assigns bound texture information for this draw.
	//   count  : Total number of textures for this draw.
	//   index  : Texture index starting from 0.
	//   tid    : Bound texture reference.
	//   fn, f0 : Used when there are multiple textures for one mesh.
	SetTex(count, index int, tid, fn, f0 uint32)

	// Shader uniform data. String keys match the variables expected
	// by the shader source. Each shader variable is expected to have
	// corresponding values in SetFloats.
	SetUniforms(u map[string]int32)          // Variable names:references.
	SetFloats(key string, floats ...float32) // Set variable data.
	Floats(key string) (vals []float32)      // Get variable data.
	SetAlpha(a float64)                      // Transparency.
	SetTime(t float64)                       // Time in seconds.

	// Allow the application to set an object tag. Used for fallback
	// object render sorting where lower values are rendered first.
	Tag() (t uint64) // Retreive the tag set for this draw.
	SetTag(t uint64) // Set a tag, like a unique model/entity identifier.
	Bucket() int     // Get draw bucket. Lower buckets are rendered first.
}

Draw contains the information necessary for a single draw call. A draw call needs references for vertex buffers, textures, and a shader that have been bound with render.Bind*(). Only the data needed by this draws shader has to be set.

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

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.

type Renderer

type Renderer 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 colour
	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) (err error)
	BindShader(vsh, fsh []string, uniforms map[string]int32,
		layouts map[string]uint32) (program uint32, err error)
	BindTexture(tid *uint32, img image.Image, repeat bool) (err error)
	Render(d Draw) // Render bound data and textures with bound shaders.

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

Renderer 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() Renderer

New provides the graphics implementation determined by the renderer implementation that was included by the build, ie: OpenGL on OSX and Linux.