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 M4ToData(m *lin.M4, d []float32) []float32
• func SortDraws(frame []*Draw)
• type Context
  • func New() Context
• type Data
  • func NewFaceData(usage uint32) Data
  • func NewInstancedData(lloc uint32) Data
  • func NewVertexData(lloc, span, usage uint32, normalize bool) Data
• type Draw
  • func NewDraw() *Draw
  • func (d *Draw) Reset()
  • func (d *Draw) SetCounts(faces, verts int)
  • func (d *Draw) SetM4Data(ref int32, m *lin.M4)
  • func (d *Draw) SetPoses(poses []lin.M4)
  • func (d *Draw) SetRefs(shader, meshes uint32, mode int)
  • func (d *Draw) SetShadowmap(tid uint32)
  • func (d *Draw) SetTex(count, index, order int, tid uint32)
  • func (d *Draw) SetUniformData(ref int32, floats ...float32)

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 M4ToData

func M4ToData(m *lin.M4, d []float32) []float32

M4ToData transforms a lin.M4 matrix to an array of floats needed by the rendering system. The passed in slice is set to 0 len before appending the matrix data in the order needed by the shader.

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
	Clone() Data          // Duplicate.
}

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 NewInstancedData

func NewInstancedData(lloc uint32) Data

NewInstancedData creates instanced vertex data for storing 4x4 transform matricies. The shader lloc location value consumes 4 values in total, ie: if lloc is 3, then 3,4,5,6 are used to represent the 4 vectors of the matrix.

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     : StaticDraw or DynamicDraw
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.

	// Rendering hints.
	Bucket    uint64 // Used to sort draws. Lower buckets rendered first.
	Depth     bool   // True to render with depth.
	Scissor   bool   // True to render with within scissor dimensions.
	Sx, Sy    int32  // Start of scissor area. First 2 parameters.
	Sw, Sh    int32  // Scissor width and height. Last 2 parameters.
	Fbo       uint32 // Framebuffer id. 0 for default.
	FaceCnt   int32  // Number of triangles to be rendered.
	VertCnt   int32  // Number of verticies to be rendered.
	Instances int32  // Postive instance count for instanced mesh.

	// Shader uniform data. The Uniforms are queried from the shader.
	// The UniformData is set by the Engine and App.
	Uniforms    map[string]int32    // Shader uniform variables, references.
	UniformData map[int32][]float32 // Uniform values indexed by ref.

	// Animation pose matrices are converted to a single slice.
	NumPoses int       // Number of animation bone data matricies.
	Poses    []float32 // All the bone data matricies.
}

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

func (d *Draw) Reset()

Reset clears old draw data so the draw call can be reused.

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

func (d *Draw) SetM4Data(ref int32, m *lin.M4)

SetM4Data sets the uniform matrix data given the shader reference.

func (*Draw) SetPoses

func (d *Draw) SetPoses(poses []lin.M4)

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

func (*Draw) SetUniformData

func (d *Draw) SetUniformData(ref int32, floats ...float32)

SetUniformData for the shader.