load

Documentation

Overview

Package load fetches disk based 3D asset data. It's main purpose is to find the asset file and load its data into intermediate data structs.

• ".spv" spir-v shader module byte code
• ".png" image data
• ".shd" shader configuration description
• ".glb" vertex data, image data, animation data, material data
• ".wav" audio data
• ".ttf" true type font file.
• ".yaml" data file

This package is primary used internally for getting data from disk that is then upload to the render and audio systems.

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

Index

• Constants
• Variables
• func SetAssetDir(ext, dir string)
• type AssetData
  • func Glb(name string, r io.Reader) (data []AssetData)
  • func LoadAssetFile(fname string) []AssetData
  • func Model(name string) (data []AssetData)
• type AttributeScope
• type AudioAttributes
• type AudioData
  • func Audio(name string) (aud *AudioData, err error)
  • func Wav(r io.Reader) (aud *AudioData, err error)
• type Buffer
  • func F32Buffer(verts []float32, dimension uint32) Buffer
  • func U16Buffer(indexes []uint16) Buffer
  • func U32Buffer(data []uint32, dimension uint32) Buffer
  • func (buff Buffer) PrintF32(name string)
  • func (buff Buffer) PrintU16(name string)
• type ByteData
  • func DataBytes(name string) (data ByteData, err error)
• type FontAtlas
  • func TTFont(name string) (atlas *FontAtlas, err error)
  • func Ttf(ttfBytes []byte, size int) (atlas *FontAtlas, err error)
• type Glyph
• type ImageData
  • func Image(name string) (idata *ImageData, err error)
• type MeshData
• type PBRMaterialData
• type PacketUniform
• type PassUniform
• type Shader
  • func ShaderConfig(name string) (cfg *Shader, err error)
  • func Shd(name string, data []byte) (shader *Shader, err error)
  • func (s *Shader) GetSamplerUniforms() (uniforms []*ShaderUniform)
  • func (s *Shader) GetSceneUniforms() (uniforms []*ShaderUniform)
• type ShaderAttribute
• type ShaderData
  • func ShaderBytes(name string) (data ShaderData, err error)
• type ShaderDataType
• type ShaderPass
• type ShaderStage
• type ShaderUniform
• type UniformScope

Constants

const (
	Vertexes    = iota // 0 required:V3 float32
	Texcoords          // 1 optional:V2 float32
	Normals            // 2 optional:V3 float32
	Tangents           // 3 optional:V4 float32
	Colors             // 4 optional:V3 uint8
	Joints             // 5 FUTURE:V4 uint8    animations
	Weights            // 6 FUTURE:V4 uint8    animations
	Indexes            // 7 required:uint16             - must be second last.
	VertexTypes        // 8 number of vertex data types - must be last.
)

Vertex MeshData attribute types.

const (
	InstancePosition = iota // position 0 V3 float32
	InstanceColors          // 1 V3 uint8
	InstanceScales          // 2 float32
	InstanceTypes           // number of instance data types - must be last.
)

Instance Data attribute types describe per-instance model data. These are defined here because they are similar to vertex data types.

Variables

var DataTypeSizes = map[ShaderDataType]uint32{
	DataType_INT:     4,
	DataType_FLOAT:   4,
	DataType_LIGHT3:  96,
	DataType_MAT3:    36,
	DataType_MAT4:    64,
	DataType_SAMPLER: 0,
	DataType_VEC2:    8,
	DataType_VEC3:    12,
	DataType_VEC4:    16,
}

var ReadFile func(string) ([]byte, error) = osReadFile

ReadFile can be overridden by the app to use other options than loading files from the file system. Eg: the app can use a go:embed FS.

var ShaderAttributeData = map[string]ShaderDataType{
	"float": DataType_FLOAT,
	"vec2":  DataType_VEC2,
	"vec3":  DataType_VEC3,
	"vec4":  DataType_VEC4,
}

ShaderAttributeData are the currently supported data types for vertex and model-instance data. Expected use is for passing data from the engine to the render system.

var ShaderAttributeScope = map[string]AttributeScope{
	"vertex":   VertexAttribute,
	"instance": InstanceAttribute,
}

ShaderAttributeScope categorizes vertex attributes into per-vertex data or per-model-instance data. Expected use is for passing data from the engine to the render system.

var ShaderAttributes = map[string]int{

	"position": Vertexes,
	"texcoord": Texcoords,
	"normal":   Normals,
	"tangent":  Tangents,
	"v_color":  Colors,
	"joint":    Joints,
	"weight":   Weights,

	"i_position": InstancePosition,
	"i_color":    InstanceColors,
	"i_scale":    InstanceScales,
}

ShaderAttributes map glsl vertex attributes from shader programs to model data provided by code. Expected use is for passing data from the engine to the render system.

var ShaderPacketUniforms = map[string]PacketUniform{
	"model":    MODEL,
	"scale":    SCALE,
	"color":    COLOR,
	"material": MATERIAL,
	"args4":    ARGS4,
	"args16":   ARGS16,
}

ShaderPacketUniforms are shader uniforms that apply to one model. Render data for a model is put into a render.Packet. Expected use is for passing data from the engine to the render system.

var ShaderPassUniforms = map[string]PassUniform{
	"proj":    PROJ,
	"view":    VIEW,
	"cam":     CAM,
	"lights":  LIGHTS,
	"nlights": NLIGHTS,
	"time":    TIME,
}

ShaderPassUniforms are shader uniforms that apply to the a single scene (render pass). Expected use is for passing data from the engine to the render system.

var ShaderUniformData = map[string]ShaderDataType{
	"int":     DataType_INT,
	"float":   DataType_FLOAT,
	"light3":  DataType_LIGHT3,
	"mat3":    DataType_MAT3,
	"mat4":    DataType_MAT4,
	"sampler": DataType_SAMPLER,
	"vec2":    DataType_VEC2,
	"vec3":    DataType_VEC3,
	"vec4":    DataType_VEC4,
}

ShaderUniformData are the supported uniform data types. Expected use is for passing data from the engine to the render system.

var ShaderUniformScope = map[string]UniformScope{
	"scene":    SceneScope,
	"material": MaterialScope,
	"model":    ModelScope,
}

ShaderUniformScope is used to bind data in shaders. Expected use is for passing data from the engine to the render system.

Functions

func SetAssetDir

func SetAssetDir(ext, dir string)

SetAssetDir can be used to add or change the default directory conventions for finding assets.

Types

type AssetData

type AssetData struct {
	Filename string      // request filename with extension
	Err      error       // nil if load was successful
	Data     interface{} // struct of loaded data.
}

AssetData is used to return loaded data. The caller is expected to switch on the Data type.

func Glb

func Glb(name string, r io.Reader) (data []AssetData)

Glb accepts a subset of a binary gltf.Document that describes a single mesh model. The single models limitiations is enforced as follows:

• one Scene
• one Node
• one Mesh
• one Mesh.Primitive

These conform to a single model exported from Blender.

func LoadAssetFile

func LoadAssetFile(fname string) []AssetData

LoadAssetFile returns one or more AssetData structs from the given asset filename.

func Model

func Model(name string) (data []AssetData)

Model loads 3D data including mesh, texture, material, animation, and transform data. Errors are returned inside AssetData which will always contain at least one element.

type AttributeScope

type AttributeScope uint8

AttributeScope identifies the two types of attributes.

const (
	VertexAttribute AttributeScope = iota
	InstanceAttribute
)

type AudioAttributes

type AudioAttributes 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.
}

AudioAttributes describe how sound data is interpreted and played.

type AudioData

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

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

AudioData is an intermediate data format that needs further processing to associate the sound with a 3D location and bind it to an audio device.

func Audio

func Audio(name string) (aud *AudioData, err error)

Audio loads audio data.

func Wav

func Wav(r io.Reader) (aud *AudioData, 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-winter-2014/projects/WaveFormat/

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

type Buffer

type Buffer struct {
	Data   []byte // bytes in little-endian order.
	Count  uint32 // total number of elements, ie: how many vertex vec3's.
	Stride uint32 // bytes for one element, eg: 12 for float32:vec3
}

Buffer holds byte data that can be uploaded to the GPU

func F32Buffer

func F32Buffer(verts []float32, dimension uint32) Buffer

F32Buffer converts a slice of float32s to a Buffer of bytes. Used to pass data to glsl vec float types

func U16Buffer

func U16Buffer(indexes []uint16) Buffer

U16Buffer converts a slice of uint16 to a Buffer of bytes. Used to pass data to glsl vertex indexes.

func U32Buffer

func U32Buffer(data []uint32, dimension uint32) Buffer

U32Buffer converts a slice of uint32 to a Buffer of bytes. Used to pass data to glsl uvec int types

func (Buffer) PrintF32

func (buff Buffer) PrintF32(name string)

PrintF32 dumps bytes as float32 vertices. Used to debug mesh data. eg: md[load.Vertexes].PrintF32()

func (Buffer) PrintU16

func (buff Buffer) PrintU16(name string)

PrintU16 dumps bytes as uint16 triangle indexes. Used to debug mesh data.

type ByteData

type ByteData []byte

ByteData loads the bytes for the given file.

func DataBytes

func DataBytes(name string) (data ByteData, err error)

DataBytes loads bytes from generic data files.

type FontAtlas

type FontAtlas struct {
	Tag    string    // asset ID is filename + font-size.
	Img    ImageData // Atlas image ready for upload to GPU.
	Glyphs []Glyph   // Character position mapping data.
	NRGBA  *image.NRGBA
}

FontAtlas holds UV texture mapping information for a font. This is an intermediate data format that needs further processing by something like a vu.Ent.MakeModel to send the atlas image to the GPU.

func TTFont

func TTFont(name string) (atlas *FontAtlas, err error)

TTFont loads font character mapping data from a true type font file. By convention, name includes the desired font size eg: "##:font.ttf".

func Ttf

func Ttf(ttfBytes []byte, size int) (atlas *FontAtlas, err error)

Ttf reads the truetype font and generates the atlas image and atlas character mapping data.

type Glyph

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

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

type ImageData

type ImageData struct {
	Width  uint32
	Height uint32
	Pixels []byte
	Opaque bool
}

ImageData contains image data for uploading to the GPU.

func Image

func Image(name string) (idata *ImageData, err error)

Image loads .png images as the underlying data format for textures.

type MeshData

type MeshData []Buffer

MeshData contains per-vertex data. Data will be index the GLTF buffer.

type PBRMaterialData

type PBRMaterialData struct {
	ColorR    float64 // material base color for solid PBR.
	ColorG    float64 //  ""
	ColorB    float64 //  ""
	ColorA    float64 //  ""
	Metallic  float64 // metallic value if no m-r texture
	Roughness float64 // roughness value if no m-r texture
}

PBRMaterialData describes a PBR solid material.

type PacketUniform

type PacketUniform uint8

PacketUniform is model scope uniform data.

const (
	MODEL          PacketUniform = iota // model
	SCALE                               // model
	COLOR                               // model
	MATERIAL                            // model
	ARGS4                               // model shader specific data passing.
	ARGS16                              // model shader specific data passing.
	PacketUniforms                      // must be last
)

type PassUniform

type PassUniform uint8

PassUniform is scene scope uniform data.

const (
	PROJ         PassUniform = iota // scene
	VIEW                            // scene
	CAM                             // scene
	LIGHTS                          // scene
	NLIGHTS                         // scene
	TIME                            // scene
	PassUniforms                    // must be last
)

type Shader

type Shader struct {
	// Name identifies the shader modules. eg: Name.frag, Name.vert
	Name   string      // unique name for this shader.
	Pass   string      // renderpass name for this shader.
	Stages ShaderStage // bit flags for the shader stages.

	// Set from shaderConfig.Render flags.
	CullModeNone bool // true disables backface culling.
	DrawLines    bool // true to render lines instead of triangles.

	// Attrs must match the shader attributes in name and position, ie:
	//   Attr[0].Name == position   ... which matches
	//	 "layout(location=0) in vec3 position;"
	Attrs []ShaderAttribute

	// Uniforms must match the shader attributes in name and position
	// where scope also identifies a DescriptorSet.
	Uniforms []ShaderUniform
}

Shader describes shader data and is used to generate render shaders on startup.

FUTURE: replace the yaml files with data gathered from shader code reflection. Not really a simple way to do Spirv reflection at the moment as the current tools generate lots of data which would be a pain to parse. See: spirv-cross, spirv-reflect command line tools.

func ShaderConfig

func ShaderConfig(name string) (cfg *Shader, err error)

ShaderConfig loads compiled shader (spir-v) byte data.

func Shd

func Shd(name string, data []byte) (shader *Shader, err error)

Shd loads a yaml shader configuration and returns it as a shader configuration struct. This is needed to provide a link between the render models and the shader programs.

func (*Shader) GetSamplerUniforms

func (s *Shader) GetSamplerUniforms() (uniforms []*ShaderUniform)

func (*Shader) GetSceneUniforms

func (s *Shader) GetSceneUniforms() (uniforms []*ShaderUniform)

type ShaderAttribute

type ShaderAttribute struct {
	Name      string         // unique name matching shader source code.
	AttrType  int            // matching mesh vertex attribute type
	AttrScope AttributeScope // vertex or instanced
	DataType  ShaderDataType // describes the attribute data.
}

ShaderAttribute identifies the data layouts for attributes.

type ShaderData

type ShaderData []byte

ShaderData differentiates shader data from other byte data.

func ShaderBytes

func ShaderBytes(name string) (data ShaderData, err error)

ShaderBytes loads compiled shader (spir-v) byte data.

type ShaderDataType

type ShaderDataType uint8

ShaderDataType helps describe shader attributes and uniforms

const (
	DataType_INT ShaderDataType = iota
	DataType_FLOAT
	DataType_LIGHT3 // array of 3 lights
	DataType_MAT3
	DataType_MAT4
	DataType_SAMPLER
	DataType_VEC2
	DataType_VEC3
	DataType_VEC4
)

type ShaderPass

type ShaderPass uint8

ShaderPass identifies the render pass that the shader uses.

const (
	Renderpass_3D ShaderPass = iota // 3D is rendered before 2D
	Renderpass_2D                   //
)

type ShaderStage

type ShaderStage uint8

ShaderStage identifies the currently supported programmable shader stages that a shader can have.

const (
	Stage_VERTEX   ShaderStage = 1 << iota // vertex processing.
	Stage_GEOMETRY                         // eg: turn points into quads.
	Stage_FRAGMENT                         // pixel processing.
)

type ShaderUniform

type ShaderUniform struct {
	Name      string         // unique name matching shader source code.
	Scope     UniformScope   //
	DataType  ShaderDataType //
	PassUID   PassUniform    // index to pass data
	PacketUID PacketUniform  // index to packet data
}

ShaderUniform identifies the data layouts for uniforms.

type UniformScope

type UniformScope uint8

UniformScope identifies the three supported types of uniforms. The scope is directly related to the layout(set=x) value in the shader code.

const (
	SceneScope    UniformScope = iota // set per render pass: set=0
	MaterialScope                     // set per material     : set=1
	ModelScope                        // set per model      : push constants
)