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

	// Render buckets. Lower values drawn first. Used in Draw.SetHints.
	DepthPass   // draw first
	Opaque      // draw after shadow
	Transparent // draw after opaque
	Overlay     // draw last.

	// BindFrame buffer types.
	DepthBuffer // For depth only.
	ImageBuffer // For color and depth.
)

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 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 interface {
	SetMv(mv *lin.M4)            // Model-View transform.
	SetMvp(mvp *lin.M4)          // Model-View-Projection transform.
	SetPm(pm *lin.M4)            // Projection matrix only.
	SetDbm(dbm *lin.M4)          // Depth bias matrix for shadow maps.
	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.
	//   asTex : True to render to texture.
	SetHints(bucket int, tocam float64, depth bool, fbo uint32)

	// 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 for multiple textures on one mesh.
	SetTex(count, index int, tid, fn, f0 uint32)
	SetShadowmap(tid uint32) // Shadow depth map texture id.

	// 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) // Retrieve 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 the shader for this draw call has to be set.

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.

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

	// BindFrame creates a framebuffer object with an associated texture.
	//   buf : DEPTH_BUFF, for depth, or IMAGE_BUFF, for color and depth.
	//   fbo : returned frame buffer object identifier.
	//   tid : returned texture identifier.
	//   db  : returned depth buffer render buffer.
	BindFrame(buf int, fbo, tid, db *uint32) (err 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.
	ReleaseFrame(fbo, tid, db uint32) // Free framebuffer and texture.
}

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 render implementation as determined by the build.