load

Documentation

Overview

Package load fetches disk based 3D assets. Assets are loaded into one of the following intermediate data structures:

FntData.Load uses Fnt to load bitmapped characters.
ImgData.Load uses Png to load model textures.
ModData.Load uses Iqm to load animated models.
MshData.Load uses Obj to load static models.
MtlData.Load uses Mtl to load model lighting data.
ShdData.Load uses Src to load GPU shader programs.
SndData.Load uses Wav to load 3D audio.

Each intermediate data format is currently associated with one file format. Asset loading is currently intended for smaller 3D applications where data is loaded directly from disk to memory, i.e. no database.

A default file Locator is provided. It can be replaced with a different Locator that follows a different string based naming convention for finding disk based assets. Overall package load attempts to shield users from knowledge about:

File Formats  : how asset contents are stored on disk.
File Types    : how file types map to asset data structs.
File Locations: where asset files are stored on disk.

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

Index

• func Fnt(r io.Reader, d *FntData) (err error)
• func Iqm(r io.Reader, d *ModData) error
• func Mtl(r io.Reader, d *MtlData) error
• func Obj(r io.Reader, d *MshData) error
• func Png(r io.Reader, d *ImgData) (err error)
• func Wav(r io.Reader, d *SndData) (err error)
• type AnmData
• type ChrData
• type FntData
  • func (d *FntData) Load(name string, l Locator) (err error)
• type ImgData
  • func (d *ImgData) Load(name string, l Locator) (err error)
• type Locator
  • func NewLocator() Locator
• type ModData
  • func (d *ModData) Load(name string, l Locator) (err error)
• type Movement
• type MshData
  • func (d *MshData) Load(name string, l Locator) (err error)
• type MtlData
  • func (d *MtlData) Load(name string, l Locator) (err error)
• type ShdData
  • func (d *ShdData) Load(name string, l Locator) (err error)
• type SndAttributes
• type SndData
  • func (d *SndData) Load(name string, l Locator) (err error)
• type SrcData
  • func Src(r io.Reader) (d SrcData, err error)
• type TexMap

Functions

func Fnt

func Fnt(r io.Reader, d *FntData) (err error)

Fnt reads in a text file describing the UV texture mapping for a character set of a particular font. The FNT files have been created using: www.anglecode.com/products/bmfont. The file data format is described at:

http://www.angelcode.com/products/bmfont/doc/file_format.html

The Reader r is expected to be opened and closed by the caller. A successful import overwrites the data in FntData.

func Iqm

func Iqm(r io.Reader, d *ModData) error

Iqm loads an Inter-Quake model IQM file into ModData. IQM is A binary format for 3D models that includes skeletal animation. See: http://sauerbraten.org/iqm. This loader has been tested against a subset of the full specification. The Reader r is expected to be opened and closed by the caller.

func Mtl

func Mtl(r io.Reader, d *MtlData) error

Mtl loads a Wavefront MTL file which is a text representation of one or more material descriptions. See the MTL file format specification at:

https://en.wikipedia.org/wiki/Wavefront_.obj_file#File_format
http://web.archive.org/web/20080813073052/
http://paulbourke.net/dataformats/mtl/

The Reader r is expected to be opened and closed by the caller. A successful import overwrites the data in MtlData.

func Obj

func Obj(r io.Reader, d *MshData) error

Obj loads a Wavefront OBJ file containing one or more mesh descriptions. A Wavefront OBJ file is a text representation of one or more 3D models. This loader supports a limited subset of the full specification. It is specifically looking for a single object triangle mesh with normals.

https://en.wikipedia.org/wiki/Wavefront_.obj_file#File_format
http://www.martinreddy.net/gfx/3d/OBJ.spec

The Reader r is expected to be opened and closed by the caller. A successful import overwrites the data in ObjData.

func Png

func Png(r io.Reader, d *ImgData) (err error)

Png populates image data using the given reader. The Reader r is expected to be opened and closed by the caller. A successful import replaces the image in ImgData with a new image.

func Wav

func Wav(r io.Reader, d *SndData) (err error)

Wav attempts to load WAV based audio data into SndData. The wave PCM soundfile format is from:

https://ccrma.stanford.edu/courses/422/projects/WaveFormat

The Reader r is expected to be opened and closed by the caller. A successful import overwrites the data in SndData.

Types

type AnmData

type AnmData struct {
	Movements []Movement // Indexes into the given frames.
	Blends    []byte     // Vertex blend indicies. Arranged as [][4]byte
	Weights   []byte     // Vertex blend weights.  Arranged as [][4]byte
	Joints    []int32    // Joint parent information for each joint.
	Frames    []*lin.M4  // Animation transforms: [NumFrames][NumJoints].
}

AnmData holds the data necessary to a. It is an intermediate data format that needs further processing by something like vu.Ent.MakeModel to bind the data to a GPU.

type ChrData

type ChrData struct {
	Char       rune // Character.
	X, Y, W, H int  // Character bit size.
	Xo, Yo, Xa int  // Character offset.
}

ChrData holds UV texture mapping information for one character. Expected to be used as part of FntData.

type FntData

type FntData struct {
	W, H  int       // Width and height
	Chars []ChrData // Character data.
}

FntData holds UV texture mapping information for a font. It is intended for populating rendered models of strings. This is an intermediate data format that needs further processing by something like a vu.Ent.MakeModel to bind the data to a GPU and associate it with a texture atlas containing the bitmapped font images.

func (*FntData) Load

func (d *FntData) Load(name string, l Locator) (err error)

Load font character mapping data. Existing FntData is overwritten with information found by the Locator.

type ImgData

type ImgData struct {
	Img image.Image
}

ImgData uses standard images as the underlying data format for textures. The image height, width, and bytes in (N)RGBA format are:

width  := img.Bounds().Max.X - img.Bounds().Min.X
height := img.Bounds().Max.Y - img.Bounds().Min.Y
rgba, _ := img.(*image.(N)RGBA)

Note that golang NRGBA are images with an alpha channel, but without alpha pre-multiplication. RGBA are images originally without an alpha channel, but assigned an alpha of 1 when read in.

This is an intermediate data format that needs further processing by something like vu.Ent.MakeModel to bind the data to a GPU based texture.

func (*ImgData) Load

func (d *ImgData) Load(name string, l Locator) (err error)

Load image data. Existing ImgData is discarded and replaced with information found by the Locator.

type Locator

type Locator interface {
	Dir(ext, dir string) Locator // Map a file extension to a directory.
	Dispose()                    // Properly terminate asset loading

	// GetResource allows applications to include and find custom resources.
	//   name: specific resource identifier, like a file or full file path.
	//   dir : prepended to the name path like a directory.
	GetResource(name string) (file io.ReadCloser, err error)
}

Locator knows how to search disk based locations for files. Locator uses a built in knowledge of paths and file types. It uses a convention for locating file types in directories where the defaults can be overridden or added to using the Dir method.

func NewLocator

func NewLocator() Locator

NewLocator returns the default asset locator. The default Locator looks directly to disk for development builds and for a zip file for production builds. The default asset locator expects all locations are directories relative to the application location. The default Locator maps the following file types to the given directories.

PNG               : "images"
WAV               : "audio"
OBJ, IQM, MTL     : "models"
FNT, VSH, FSH, TXT: "source"

type ModData

type ModData struct {
	MshData          // Vertex based data.
	AnmData          // Animation data.
	TMap    []TexMap // Texture name and vertex mapping data.
}

ModData combines vertex data, animation data and some texture names for a complete animated model. It is an intermediate data format that needs further processing by something like vu.Ent.MakeModel to bind the data to a GPU.

func (*ModData) Load

func (d *ModData) Load(name string, l Locator) (err error)

Load model vertex and animation data. Existing ModData is overwritten with information found by the Locator.

type Movement

type Movement struct {
	Name   string  // Name of the animation
	F0, Fn uint32  // First frame, number of frames.
	Rate   float32 // Frames per second.
}

Movement marks a number of frames as a particular animated move that affects frames from F0 to F0+FN. Expected to be used as part of AnmData.

type MshData

type MshData struct {
	Name string    // Imported model name.
	V    []float32 // Vertex positions.    Arranged as [][3]float32
	N    []float32 // Vertex normals.      Arranged as [][3]float32
	T    []float32 // Texture coordinates. Arranged as [][2]float32
	X    []float32 // Vertex tangents.     Arranged as [][2]float32
	F    []uint16  // Triangle faces.      Arranged as [][3]uint16
}

MshData stores vertex data from .obj files. It is intended for populating rendered models. The V,F buffers are expected to have data. The N,T,X buffers are optional.

MshData is an intermediate data format that needs further processing by something like vu.Ent.MakeModel to bind the data to a GPU.

func (*MshData) Load

func (d *MshData) Load(name string, l Locator) (err error)

Load model mesh vertex data. Existing MshData is overwritten with information found by the Locator.

type MtlData

type MtlData struct {
	KaR, KaG, KaB float32 // Ambient color.
	KdR, KdG, KdB float32 // Diffuse color.
	KsR, KsG, KsB float32 // Specular color.
	Ns            float32 // Specular exponent.
	Alpha         float32 // Transparency
}

MtlData holds color and alpha information. It is intended for populating rendered models and is often needed for as attributes for shaders with lighting.

MtlData is an intermediate data format that needs further processing by something like vu.Ent.MakeModel to bind the data to uniforms in a GPU shader.

func (*MtlData) Load

func (d *MtlData) Load(name string, l Locator) (err error)

Load model lighting material data. Existing MtlData is overwritten with information found by the Locator.

type ShdData

type ShdData struct {
	Vsh SrcData // Vertex shader.
	Fsh SrcData // Fragment (pixel) shader.
}

ShdData includes both vertex and fragment shader program source. Each line is terminated by a linefeed so that it will compile on the GPU.

ShdData is an intermediate data format that needs further processing by something like vu.Ent.MakeModel to compile the shader program and bind it to a GPU.

func (*ShdData) Load

func (d *ShdData) Load(name string, l Locator) (err error)

Load vertex and fragment shader program source code. Shader source is appended to the existing ShdData source. Assumes both the vertex and fragment shader files have the same name prefix.

type SndAttributes

type SndAttributes struct {
	Channels   uint16 // Number of audio channels.
	Frequency  uint32 // 8000, 44100, etc.
	DataSize   uint32 // Size of audio data.
	SampleBits uint16 // 8 bits = 8, 16 bits = 16, etc.
}

SndAttributes describe how sound data is interpreted and played.

type SndData

type SndData struct {
	Data  []byte         // the sound data bytes.
	Attrs *SndAttributes // Attributes describing the sound data.
}

SndData consists of the actual audio data bytes along with sounds attributes that describe how the sound data is interpreted and played.

SndData is an intermediate data format that needs further processing by something like vu.Eng.AddSound and vu.Ent.PlaySound to associate the noise with a 3D location and bind it to an audio card.

func (*SndData) Load

func (d *SndData) Load(name string, l Locator) (err error)

Load sound data. Existing SoundData is overwritten with information found by the Locator.

type SrcData

type SrcData []string

SrcData is a slice of linefeed terminated strings used to load text based files.

func Src

func Src(r io.Reader) (d SrcData, err error)

Src loads text based data into SrcData. Each line terminated with a single linefeed (needed for shader source). The Reader r is expected to be opened and closed by the caller. A successful import returns a new slice of strings in SrcData.

type TexMap

type TexMap struct {
	Name   string // Name of the texture resource.
	F0, Fn uint32 // First triangle face index and number of faces.
}

TexMap allows a model to have multiple textures. The named texture resource affects triangle faces from F0 to F0+FN. Expected to be used as part of ModData.