gpu(3pf) OpenGL Performer 3.2.2 libpfdb Reference Pages gpu(3pf)NAME
pfdLoadFile_gpu - Loader for loading xml based .gpu Performer files
FUNCTION SPECIFICATION
pfNode* pfdLoadFile_gpu(const char *fileName);
DESCRIPTION
pfdLoadFile_gpu loads .gpu files, an XML based database format which
allows users to add shader programs and parameters to existing databases
more easily.
The XML tag hierarchy is as follows:
<gpuData>
<Database>
<Node>
<VertexProgram />
<FragmentProgram />
<ProgramParameter>
<ProgramType />
<ParameterType />
<Index />
<Value />
<Callback />
</ProgramParameter>
<VertexShader />
<FragmentShader />
<ShaderUniform>
<Value />
<Callback />
</ShaderUniform>
<Material>
<Face />
<ColorMode />
<Ambient />
<Diffuse />
<Specular />
<Shininess />
</Material>
<Texture>
<TextureUnit />
<File />
<Slice />
Page 1
gpu(3pf) OpenGL Performer 3.2.2 libpfdb Reference Pages gpu(3pf)
<Volume />
<NegativeXFile />
<PositiveXFile />
<NegativeYFile />
<PositiveYFile />
<NegativeZFile />
<PositiveZFile />
</Texture>
</Node>
<Root>
<VertexProgram />
<FragmentProgram />
<ProgramParameter>
<ProgramType />
<ParameterType />
<Index />
<Value />
<Callback />
</ProgramParameter>
<VertexShader />
<FragmentShader />
<ShaderUniform>
<Value />
<Callback />
</ShaderUniform>
<Material>
<Face />
<ColorMode />
<Ambient />
<Diffuse />
<Specular />
<Shininess />
</Material>
<Texture>
<TextureUnit />
<File />
<Slice />
<Volume />
<NegativeXFile />
<PositiveXFile />
Page 2
gpu(3pf) OpenGL Performer 3.2.2 libpfdb Reference Pages gpu(3pf)
<NegativeYFile />
<PositiveYFile />
<NegativeZFile />
<PositiveZFile />
</Texture>
</Root>
</Database>
</gpuData>
VertexProgram, FragmentProgram, and ProgramParameter tags should be used
in conjunction to define data related to assembly style gpu programs.
VertexShader, FragmentShader, and ShaderUniform tags should be used
together to define data related to GLslang style gpu shaders. These tags
cannot be mixed.
All tag names can be in any case.
Specific Tag Information
Attributes are strings included in an opening tag (e.g.,
<Node name="tire">
where name is an attribute of the Node tag).
Subtags are tags included in the body of the tag (e.g.,
<Node>
<Material />
</Node>
where material is a subtag of Node tag).
Values are data in the body of a tag only enclosed by that tag (e.g.,
<Index>6</Index>
where the value of the Index tag is 6).
<gpuData>
Subtags:
<Database>
This tag is the top level container, and may contain as many <Database>
tags as desired.
<Database>
Attributes:
file - mandatory attribute which indicates the file to load to be
modified by the subtags of this tag.
Subtags:
Page 3
gpu(3pf) OpenGL Performer 3.2.2 libpfdb Reference Pages gpu(3pf)
<Node>
<Root>
This a high level container. The subtags enable specifying whether the
data should be applied to a subtree rooted at a specified node (found by
name), or applied to the entire tree. If a <Database> tag includes both
<Node> and <Root> tags, then any data from the <Root> will be applied
first and then overwritten by specific data from <Node> tags.
<Node>
Attributes:
name - name of the node in the scenegraph to apply the data to.
Subtags:
<VertexProgram>
<FragmentProgram>
<ProgramParameter>
<VertexShader>
<FragmentShader>
<ShaderUniform>
<Material>
<Texture>
This tag is a container to the data to be applied to the node specified
by the name attribute. This is a cascading application - that is,
applying the data to a node will also apply the data to all children of
the node.
<Root>
Subtags:
<VertexProgram>
<FragmentProgram>
<ProgramParameter>
<VertexShader>
<FragmentShader>
<ShaderUniform>
<Material>
<Texture>
This tag is a container to the data to be applied to the entire database
loaded.
<VertexProgram>
Value:
The name of the file containing the vertex program to apply
This tag specifies the vertex program to apply to a subtree of the parent
node tag. The program should be in the ARB_vertex_program format.
<FragmentProgram>
Value:
The name of the file containing the fragment program to apply
Page 4
gpu(3pf) OpenGL Performer 3.2.2 libpfdb Reference Pages gpu(3pf)
This tag specifies the fragment program to apply to a subtree of the
parent node tag. The program should be in the ARB_fragment_program
format.
<ProgramParameter>
Attributes:
name - an optional string with the parameter name.
Subtags:
<ProgramType>
<ParameterType>
<Index>
<Value>
<Callback>
This tag specifies data related to a single program parameter used with
the ARB_vertex_program and ARB_fragment_program style gpu programs.
There are two different types of parameters, set value parameters, and
callback parameters. All parameters require valid <ProgramType>,
<ParameterType>, and <Index> tags. Set value parameters require the
<Value> tag. Callback parameters require the <Callback> tag. These two
tags should not be mixed.
<ProgramType>
Value:
The type of the program the parameteris used with, either vertex or
fragment
<ParameterType>
Value:
The type of parameter, either local or environment.
<Index>
Value:
An integer which indicates which location this parameter will be
placed. This location is the index used in the corresponding
program to access the value associated to this parameter.
<Value>
Attributes:
size - the number of elements of the specified type in the value.
type - the data type of the value elements, and must be one of:
float, int, sampler1D, sampler2D, sampler3D, samplerCube,
sampler1DShadow, or sampler2DShadow.
Value:
A comma separated list of elements, of the type described in the
type attribute, of the length indicated in the size attribute.
This tag is only used with set value parameters. Default size is 1, and
default type is float. Other types or sizes must be specified with the
Page 5
gpu(3pf) OpenGL Performer 3.2.2 libpfdb Reference Pages gpu(3pf)
appropriate attributes. The sampler data types are only appropriate for
shader uniforms, and not for program parameters. An example of a fully
specified <Value> tag:
<Value size="4" type="float">0.25, 0.5, 0.35, 1.0</Value>
<Callback>
Attributes:
modifier - describes the modification done to the input provided by
the callback parameter done before setting to the program parameter.
Can be one of inverse, transpose, or inverseTranspose. For certain
parameters, only certain modifiers will have effect.
value - a single floating point value used in conjunction with
parameter to calculate output.
Value:
The parameter used for callback to calculate parameter value. Legal
callback types are, with value attribute information :
ModelMatrix - ignores callback value
ViewMatrix - ignores callback value
ViewPosition - ignores callback value
Timer - callback value indicates time when timer resets to zero
Callback tags indicate that resulting data passed to a program parameter
or shader uniform will come from updated graphics state. The value of
the tag indicates which parameter is the input. This can be modified by
the specification of a modifier or used in conjunction with a single
value, specifiable by attributes, to calculate a resulting output value
which will be updated per frame on a parameter. Callbacks which
reference matrices can be modified by the above modifiers (inverse,
transpose, and inverse transpose).
For example, a valid callback to set the value of a uniform to the
inverse of the model matrix would be:
<Callback modifier="inverse">ModelMatrix</Callback>
or to set a timer which cycles every 60 seconds:
<Callback value="60.0">Timer</Callback>
<VertexShader>
Value:
The name of the file containing the vertex shader to apply
This tag specifies the vertex shader to apply to a subtree of the parent
node tag. The program should be written in ARB_shading_language_100
format.
<FragmentShader>
Value:
Page 6
gpu(3pf) OpenGL Performer 3.2.2 libpfdb Reference Pages gpu(3pf)
The name of the file containing the fragment shader to apply
This tag specifies the fragment shader to apply to a subtree of the
parent node tag. The program should be written in
ARB_shading_language_100 format.
<ShaderUniform>
Attributes:
name - a mandatory string with the parameter name.
Subtags:
<Value>
<Callback>
This tag specifies data related to a single program parameter used with
the ARB_shading_language style gpu programs. There are two different
types of parameters, set value parameters, and callback parameters. All
parameters require valid <ProgramType>, <ParameterType>, and <Index>
tags. Set value parameters require the <Value> tag. Callback parameters
require the <Callback> tag. These two tags should not be mixed. Unlike
program parameters, the name attribute is mandatory, as names are used
for indexing instead of integers in GLslang programs.
<Material>
Subtags:
<Face>
<ColorMode>
<Ambient>
<Diffuse>
<Specular>
<Shininess>
Describes a material to apply to all geometry under the given node.
<Face>
Value:
Either front, back, or both, describing which face of the geometry
this material effects. The default is front.
<ColorMode>
Value:
Either ambient, diffuse, ambientAndDiffuse, specular, or off,
indicating the color material mode used by this material. Color
material mode indicates the per vertex colors are used to modify
current material values. The default is off.
<Ambient>
<Diffuse>
<Specular>
Value:
Four comma separated floating point values describing the
appropriate material property.
Page 7
gpu(3pf) OpenGL Performer 3.2.2 libpfdb Reference Pages gpu(3pf)
<Shininess>
Value:
A single floating point value describing the shininess of the
surface.
<Texture>
Attributes:
type - mandatory attribute describing the format of the texture,
either 2D, 3D, or CubeMap.
Subtags:
<TextureUnit>
<File>
<Volume>
<Slice>
<NegativeXFile>
<PositiveXFile>
<NegativeYFile>
<PositiveYFile>
<NegativeZFile>
<PositiveZFile>
Describes a texture to apply to all geometry under the given node. A
texture must be have a type of either 2D, 3D, or CubeMap. All texture
types must include the <TextureUnit> tag. 2D types must have a single
<File> tag. 3D textures have either a single <Volume> tag, or several
<Slice> tags, with each slice describing a single 2D layer of the 3D
texture. Cubemaps can be specified with one each of the <NegativeXFile>,
<PositiveXFile>, <NegativeYFile>, <PositiveYFile>, <NegativeZFile>, and
<PositiveZFile> tags.
<TextureUnit>
Value:
A single integer indicating which texture unit the texture will be
placed in.
<File>
Value:
The filename for a 2D texture
<Volume>
Attributes:
width - integer, measuring distance of the range of the x (or s)
coordinate in texels.
height - integer, measuring distance of the range of the y (or t)
coordinate in texels.
depth - integer measuring distance of the range of the z (or u)
coordinate in texels.
Value:
Page 8
gpu(3pf) OpenGL Performer 3.2.2 libpfdb Reference Pages gpu(3pf)
The name of the file with the data.
3D texture data can be supplied in a raw format, where the data is in
RGBA format, with each channel being an unsigned byte (i.e., each four-
tuple of color data is an unsigned int). The size of the texture must be
specified in the attributes to insure correct loading of the data.
<Slice>
Value
The filename of the next file in the stack.
Slice tags must be specified in the order they are to be added to the
stack to create the 3D texture, with earlier slices related to lower z
values. All slices of a volume must have equal dimensions, data type,
and number of components.
<NegativeXFile>
<PositiveXFile>
<NegativeYFile>
<PositiveYFile>
<NegativeZFile>
<PositiveZFile>
Value:
The filename of the file used for the appropriate side of the cube.
These tags are only used for cube map textures. All files of a single
cube map must have equal dimensions, data type, and number of components.
Two sample .gpu files are provided, in
/usr/share/Performer/data/marblecow/marblecow.gpu and
/usr/share/Performer/data/plastictorus/torus.gpu. These samples will
only work on platforms which support either OpenGL 2.0 or the
GL_ARB_shading_language_100 extension.
NOTES
The libpfdb source code, object code and documentation are provided as
unsupported software. Routines are subject to change in future releases.
SEE ALSOpfdLoadFile(3pf), pfVertexProgram, pfFragmentProgram, pfGProgramParms,
pfShaderProgram, pfMaterial, pfTexture
Page 9
