data

Documentation

Overview

Package data turns file resource data into data objects. Specifically data needed by 3D applications. This package:

• Defines a data type for each of the various data resources.
• Provides caching and fetching of data resources.
• Loads data directly from disk for a development build and loads data from a zip file attached to the binary for a production build.
• Loads data such that is easily consumed by the rendering and audio components.

The resource data that can be loaded from disk are the types exposed by this package:

  Data                          File           Object
 ------                        ------         --------
bitmapped fonts              : txtfile.fnt --> Glyphs
colour and surface data      : txtfile.mtl --> Material
vertex data                  : txtfile.obj --> Mesh
vertex shader program        : txtfile.vsh -┐
fragment shader program      : txtfile.fsh --> Shader
audio                        : binfile.wav --> Sound
images                       : binfile.png --> Texture

Implementation Notes:

• The intent is to eventually have more than one supported file type for a given resource.
• Currently intended for smaller 3D applications where data is loaded from disk and kept in memory. There is nothing preventing a more industrial strength (database) back end.

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

Index

• type Glyphs
  • func (gs *Glyphs) Panel(b *Mesh, phrase string) (panelWidth int)
• type Loader
  • func NewLoader() Loader
• type Material
• type Mesh
• type Rgb
• type Shader
  • func (s *Shader) EnsureNewLines()
• type Sound
• type Texture

Types

type Glyphs

type Glyphs struct {
	Name string // Unique id for a glyph set.
	// contains filtered or unexported fields
}

Glyphs holds a single bitmapped font. It knows how to pull individual character images out of a single image that contains all the characters for a font.

Glyphs just holds the pixel mapping information. It has to be combined with a texture (the font bitmapped image) in order to produce displayable strings. Glyphs can be used with any image of the same font and font size with identical bitmapped layouts. Effectively different colours of the same font and font size can use the same Glyph instance.

func (*Glyphs) Panel

func (gs *Glyphs) Panel(b *Mesh, phrase string) (panelWidth int)

Panel creates a string image for the given string. It does this by initializing the given mesh with a flat mesh big enough to display the given string. The mesh has all the necessary texture (uv) mapping information and is ready to be combined with a texture corresponding to the bitmapped font. Note that the mesh has not yet been bound to the graphics card.

The width in pixels for the resulting string image is returned.

type Loader

type Loader interface {

	// Load looks for the named resource on disk and returns a corresponding resource
	// data object. The loader will look for "name" with any of the supported file
	// types for the given resource.
	//
	// Load expects data to be a pointer to one of the resource data types.
	// If found the resource data is copied into the supplied data pointer,
	// otherwise the supplied data pointer is set to nil.
	Load(name string, data interface{})

	// Cache the given resource data so that any single resource only needs
	// to be loaded once. Cache expects data to be one of the valid resource data types
	// and to be uniquely named within its data type.
	Cache(data interface{})

	// Cached returns true if the named data resource has already been cached and ready
	// to use. Cached expects data to be one of the valid resource data types.
	Cached(name string, data interface{}) bool

	// Fetch retrieves a previously cached resource using the given name.
	// Fetch expects the resource data to be a pointer to one of the resource data types.
	// If found the resource data is copied into the supplied data pointer,
	// otherwise the supplied data pointer is set to nil
	Fetch(name string, data interface{})

	// SetDir overrides the default directory location for the given data type.
	// SetDir expects data to be one of the valid resource data types.
	//
	// Note that all directories are expected to be relative to the
	// application location.
	SetDir(dir string, data interface{})

	// Dispose needs to be called to properly terminate and clean up loaded resources.
	Dispose()
}

Loader provides methods for loading, caching, and fetching data resources from disk. The current resource data types are the types exposed by this package:

*Glyphs
*Material
*Mesh
*Shader
*Sound
*Texture

Loader methods log attempts to use unsupported data types as development errors.

func NewLoader

func NewLoader() Loader

NewLoader provides the default loader implmentation.

type Material

type Material struct {
	Name string  // Unique matrial name.
	Kd   Rgb     // Diffuse colour of the material.
	Ka   Rgb     // Ambient colour of the material.
	Ks   Rgb     // Specular colour of the material.
	Tr   float32 // Transparency (alpha, dissolve) for the material.
}

Material is used to cover a mesh. It specifies the surface colour and how the surface is lit. Materials are expected to be combined with a Mesh.

type Mesh

type Mesh struct {
	Name string // unique mesh name.

	// Verticies are points in 3D space.  Each vertex is specified with
	// (x, y, z, w) where
	//    x, y are  mandatory 2D minimum coordinates,
	//    z can be defaulted to 0 for a two dimensional vertex, and
	//    w can be defaulted to 1 for a constant depth.
	V []float32 // arranged as [][4]float32

	// Normals for each vertex. Normals are specified as (x, y, z) where each
	// value is between 0.0 and 1.0. The slice length is expected to be the same
	// length as the vertex slice, and each normal is calculated to be the
	// normalized sum of the normals for each face that shares the vertex.
	N []float32 // arranged as [][3]float32

	// Texture coordinates. Specifies how the texture data is aligned relative
	// to the fragment. There are two floats for each texture (u, v)  where the
	// values are expected to be between 0.0 and 1.0. The texture data is loaded
	// separately from an image file.
	//
	// The texture corresponding to these texture coordinates is expected to be
	// available to the rendering layer at the same time as this mesh.
	T []float32 // arranged as [][2]float32

	// Faces are used to index the vertex data into shapes. These are
	// expected to be triangles so 3 indicies form one face.  Each face value
	// refers to a single vertex.
	F []uint16 // arranged as [][3]uint16

	// Vao is an vertex array object that is a reference to the above
	// vertex and normal data.  The reference is to data is stored on the graphics
	// card. The "*buf" variables are graphic card references for
	// the above data.
	Vao  uint32 // vertex array references all buffers.
	Vbuf uint32 // vertex buffer
	Tbuf uint32 // texture buffer
	Nbuf uint32 // normals buffer
	Fbuf uint32 // face index buffer
}

Mesh holds 3D model data in a format that is easily consumed by a rendering layer. A mesh is expected to be reused and thus does not contain any instance information like location or scale.

An approximation is to keep an individual mesh to less than 65,000 verticies so that it works on lower capability systems like mobile devices.

type Rgb

type Rgb struct {
	R float32 // red
	G float32 // green
	B float32 // blue
}

Rgb holds colour information where each of the fields is expected to contain a value from 0.0 to 1.0. A value of 0 means none of that colour while a value of 1.0 means as much as possible of that colour. For example:

black := &Rgb{0, 0, 0}
white := &Rgb{1, 1, 1}
red := &Rgb{1, 0, 0}
gray := &Rgb{0.5, 0.5, 0.5}

type Shader

type Shader struct {
	Name     string           // Unique name (file name) of the shader.
	Vsh      []string         // Vertex shader source.
	Fsh      []string         // Fragment shader source.
	Program  uint32           // Reference to the compiled vertex and fragment program.
	Uniforms map[string]int32 // Uniform data is required.
}

Shader controls rendering. A shader is a set of programs that run on the graphics card. Different shaders are created for different effects. Shaders commonly need input from the CPU side. These input variables are called uniforms.

func (*Shader) EnsureNewLines

func (s *Shader) EnsureNewLines()

EnsureNewLines makes sure that shader program lines of code are properly terminated for the shader compiler.

type Sound

type Sound struct {
	Name       string // Unique sound name.
	AudioData  []byte // The raw audio data.
	Channels   uint16 // Number of audio channels.
	SampleBits uint16 // 8 bits = 8, 16 bits = 16, etc.
	Frequency  uint32 // 8000, 44100, etc.
	DataSize   uint32 // Size of audio data (total file size minus header size).

	// Buffer is the sound card buffer reference that the sound data is loaded
	// into. Sound buffers can be shared among many sound sources.
	Buffer uint32
}

Sound holds on to a shared audio resource. The audio data still needs to be bound to a sound card buffer.

type Texture

type Texture struct {
	Name string      // Unique name of the texture.
	Img  image.Image // The texture data.
	Tid  uint32      // The graphics card texture identifier.
}

Texture deals with 2D pictures that are mapped onto objects. Textures are copied to the graphics card and expected to be combined with a Mesh.