A <mesh> usually has multiple <source> elements, each containing numeric values related to the same set of vertices. One <source> element might contain vertex positions. while another holds normal vector parameters. A third <source> element may store texture coordinates. These elements are distinguished by their id attribute, which is required and must be unique.

Information in <source> elements usually consists of two parts. The first part holds a numeric array within a subelement that identifies the datatype of the numbers. The second part specifies how the numbers should be accessed. This is contained within <technique_common> or <technique> subelements.

There are many possible subelements that hold numeric arrays. <float_array>, <int_array>, and <bool_array> are the most popular. Only one array can be included in a <source> element. In each case, the only required attribute is count, which represents the number of values inside the element.

For example, the following <source> element contains 12 floating-point values. The only required attribute of <source> is id, and the only required attribute of <float_array> is count:

<source name="Example Source" id="example_source">
   <float_array count="12" id="example_array">
      0.1 0.2 0.3 0.4 0.5 0.6
      0.7 0.8 0.9 1.0 1.1 1.2
   </float>
</source>

This example doesn’t say anything about the purpose of these numeric values: They could be coordinates or color values or polynomial coefficients. The <source> element just lists them in order and matches them to an identifier. The interpretation of these values is identified by the <technique> or <technique_common> subelement.

A technique specifies the manner in which a graphic should be displayed on a target platform. An object may need to be rendered one way on mobile platforms and another way on personal computers. For each method of presentation, you should have a separate <technique> subelement under the <source>. In many cases, however, you’ll provide only a single technique that applies to all platforms. This is identified with <technique_common>.

As a child of <source>, the <technique_common> element contains a single child of its own: <accessor>. This defines how the values in the array should be accessed. It does this by partitioning the source array into subarrays with specific names. For example, the following code defines the same 12-element array as before, but the accessor divides the values into four subarrays with three elements (x, y, and z) each:

<source name="Example Source" id="example_source">
   <float_array count="12" id="example_array">
      0.1 0.2 0.3 0.4 0.5 0.6
      0.7 0.8 0.9 1.0 1.1 1.2
   </float>
   <technique-common>
      <accessor count="4" source="#example_source" stride="3">
         <param name="x" type="float"/>
         <param name="y" type="float"/>
         <param name="z" type="float"/>
      </accessor>
   </technique-common>
</source>

The <technique_common> element has two required attributes: source and count. The first defines the source element whose numeric arrays will be accessed. Notice that the name of the source element is preceded with a #. This states that the text that follows is an id value. The count attribute identifies how many subarrays the source array will be divided into.

The stride attribute isn’t required, but it shows how many array elements should be accessed at a time. With each access, the array elements are assigned names identified in the param declarations. In the example, the array is accessed three elements at a time, and the floating-point values are named x, y, and z in succession.

Many of the other <mesh> subelements identify how the <source> values should be used. The <vertices> subelement matches subarrays in the <source> element with coordinates in the mesh. It has one required attribute, id, and must have at least one child element, <input>.

The <input> element identifies the <source> of the numeric values and states that they represent positions within the mesh. The following <vertices> element accesses the values in the example_source element and identifies them as vertex positions:

<vertices id="example_vertices">
   <input semantic="POSITION" source="#example_source"/>
</vertices>

Each <input> inside a <vertices> element must have a semantic attribute equal to POSITION and a source attribute equal to a defined source element. It may also have an optional offset attribute that identifies a position inside the array. A <vertices> element may have multiple <input> elements identifying different <source> elements.

Before proceeding further, let’s summarize the elements discussed so far:

The vertices can now be combined to create shapes, such as lines, triangles, and polygons. This is discussed next.

Chapter 20, “OpenGL on the Cell: Gallium and Mesa,” explained how OpenGL creates shapes from vertices. COLLADA shapes are similar, and are defined by one of the following:

These shape elements all have the same three attributes: name, count, and material. Only count is required, and states how many shapes will be constructed. material is optional and identifies a defined material. If the mesh material isn’t defined, properties like light and shading must be defined elsewhere.

Each shape element has at least three subelements: <input>, <p>, and <extra>. The <input> subelement has the same attributes as the <input> subelement inside <vertices>. But the offset attribute is required and possible values for semantic include VERTEX, COLOR, NORMAL, TEXCOORD, TEXTURE, TANGENT, BINORMAL, and UV. Different values of semantic refer to different <source> elements, and a shape element may contain multiple <input> values to represent different vertex data.

The <p> subelement creates shapes from vertices. Each vertex is assigned an index, and the <p> element lists indices in the order in which they form the named shape. An example will clarify how <p> is used. Let’s say you want to create two triangles from five vertices: Triangle 1 consists of P0, P1, and P2, and Triangle 2 consists of P1, P3, and P4. The <triangles> element would be declared as follows:

<triangles count="2">
   <input offset="0" semantic="VERTEX" source="vertex_data">
   <p>0 1 2 1 3 4</p>
</triangles>

Instead of listing all the indices in a single <p> element, a separate <p> subelement can be declared for each shape. For this simple example, the triangles are created with the following:

<triangles count="2">
   <input offset="0" semantic="VERTEX" source="vertex_data">
   <p>0 1 2</p>
   <p>1 3 4</p>
</triangles>

To show how a shape element accesses multiple inputs, the next <triangles> element associates each vertex index with an index into an array of normal data. Here, the vertices are defined in the vertex_data source, and the normal data is defined in the normal_data source:

<triangles count="2">
   <input offset="0" semantic="VERTEX" source="vertex_data">
   <input offset="1" semantic="NORMAL" source="normal_data">
   <p>0 0  1 1  2 3</p>
   <p>1 4  3 5  4 6</p>
</triangles>

There are two inputs and twice as many values in the <p> elements. In this case, the <p> values are grouped in twos: The first value in each group is taken from the input with offset 0, and the second is taken from the input with offset 1. Each vertex index is matched with a corresponding normal vector.

The shape determines how many vertices are accessed at a time, but polygons may have an arbitrary number of points. For this reason, the vertex indices are separated into individual <p> elements rather than being grouped into a single list. For example, the following element defines two polygons, the first consisting of five vertices and the second consisting of seven:

<polygons count="2">
   <input offset="0" semantic="VERTEX" source="vertex_data" />
   <p>0 3 2 4 1</p>
   <p>3 7 5 8 6 9 10</p>
</polygons>

If the polygon contains holes, the <ph> element is used. This contains subelements <p> and <h>, where <p> represents the vertices of the polygon and <h> represents vertices of the hole.

The last shape element is <polylist>, which differs from <polygons> in two respects. First, it identifies how many vertices are in each polygon with the <vcount> subelement. This makes it possible to specify all the vertices in a single list. The following code shows how a <polylist> can declare the same two polygons as those declared previously:

<polylist count="2">
   <input offset="0" semantic="VERTEX" source="vertex_data" />
   <vcount>5 7</vcount>
   <p>0 3 2 4 1 3 7 5 8 6 9 10</p>
</polylist>

The second difference between <polylist> and <polygons> is that no holes are allowed in a <polylist> declaration.

Ogre3D skeleton files group vertices and polygons into bones, which move as individual objects during animation. A bone’s position is determined by the joint that connects it with its parent bone. The entire parent-child bone hierarchy forms the object’s skeleton. The vertices and polygons covering the skeleton form its skin.

The goal of the <skin> element is to show how vertices combine to form bones and how the bones move. It’s important to understand the coordinates and transformations involved. An object’s bind shape is formed of the vertices that make up its skin. The inverse bind matrix transforms a vertex’s world coordinates so that it can be expressed in the local coordinates used by its joint.

The bind shape matrix transforms the local coordinates so that the vertices move as their joints move. This is identified with the optional <bind_shape_matrix> element, which is set to the identity matrix by default. Both matrices have to be identified for animation to work properly.

Like the <mesh> element described earlier, the <skin> element places its numeric values inside <source> elements. At least three <source> elements are required for each <skin> element:

These values are accessed by the other <skin> subelements: <joints> and <vertex_weights>.

The <joints> element creates an association between the names of the joints and their attributes. At the very least, it has to match joint names to inverse bind matrices. This is shown with the following code:

<joints>
   <input semantic="JOINT" source="#example_joints" />
   <input semantic="INV_BIND_MATRIX" source="#example_ibms" />
</joints>

As the skeleton moves, multiple bones may influence a vertex’s transformation. This information is provided by the <vertex_weights> element. The numeric weights are identified in a <source> element and accessed through an <input> element. A second <input> element must identify the <source> element holding the names of the joints.

The <vertex_weights> attribute has a required count attribute that specifies the number of vertices. For each vertex, the <vcount> element contains the number of bones that influence it. Finally, the <v> parameter matches the bone index with the weight index. If the bone index is −1, the weight is matched to the entire body pose.

For example, the following declaration identifies weighting for three vertices:

<vertex_weights count="3">
   <input semantic="JOINT" source="#example_joints" />
   <input semantic="WEIGHT" source="#example_weights" />
   <vcount>3 2 4</vcount>
   <v>-1 0  1 1  4 2  -1 3  2 4  -1 5  2 6  3 7  4 8</v>
</vertex_weights>

The first vertex is affected by Bones −1, 1, and 4; the second is affected by Bones −1 and 2; and the third is affected by −1, 2, 3, and 4. Each influence is identified by sequential weights indexed from zero to eight.

Morphing is similar to animation, but transforms each vertex separately, without bones or a skeleton structure. This process interpolates values between a base mesh and a target mesh, and transforms each vertex of the base mesh until they form the target mesh. The nature of the transformation is affected by the base mesh, the target mesh, and vertex weighting.

There are two main methods of morphing vertices. The first, called normalized morphing, normalizes vertex weights so that their sum equals one. Then it performs the transformation using the following equation:

The relative method is simpler, and is given by the following formula:

The <morph> element sets up the transformation by matching target meshes and vertex weights. One attribute, method, identifies the morphing method, and source names the symbol corresponding to the base mesh. It also has three subelements: <source>, <targets>, and <extra>. The <targets> element contains at least two <input> elements. This is shown in the following declaration:

<morph method="normalized" source="#example_base">
   <input semantic="MORPH_TARGET" source="#example_target" />
   <input semantic="MORPH_WEIGHT" source="#example_weight" />
</morph>

In this example, the morphing process transforms the vertices in example_base mesh into the example_target mesh using the normalized method and the weights in the example_weight source element.

Before defining the rendering properties of a material, it’s important to specify what rendering platform should be used. The <technique_hint> subelement identifies a platform that the material properties are intended for. A <material> element may have more than one <technique_hint> to identify multiple suitable platforms.

The <technique_hint> element has three attributes and no subelements. The attributes are as follows:

Only the ref attribute is required. Examples of profile values include profile_COMMON, profile_CG, profile_GLES, and profile_GLSL. In each case, the attribute’s value is set to the profile name without the profile_. This is shown in the following declarations:

<technique_hint platform="PS3" ref="texture" profile="CG"/>
<technique_hint ref="shader" profile="GLSL"/>

In this example, profile_CG should be used for texture on the PS3, and profile_GLSL should be used for shading.

<setparam> assigns a value to a previously identified parameter. The name of the parameter is identified by the ref attribute, which is required for all <setparam> elements. Its value is specified by placing numbers or characters between tags that represent datatypes. Table 22.2 lists the datatypes available for parameter values.

The parameter can be set to a single value or an array of values. For numbers, one-dimensional arrays are identified with a number following the datatype (for instance, int3), and two-dimensional arrays are identified with two numbers following the datatype, such as float3x2. Parameters can also be set to previously declared objects, such as surfaces and samplers.

As an example, the following <setparam> declaration assigns the array (0.25 0.50 0.75) to the parameter emit_color:

<setparam ref="emit_color">
   <float3>0.25 0.50 0.75</float>
</setparam>

The COLLADA standard provides for a number of other libraries and elements, and many of these are needed to fully flesh out an object’s properties and rendering. For a thorough treatment of the subject, I strongly recommend COLLADA: Sailing the Gulf of 3-D Content Creation, by Remi Arnaud and Mark Barnes.

As shown in Listing 22.1, the primary object in the COLLADA API is the DAE. This opens the COLLADA file and creates a document object with the same name. The XML elements in the document are cached inside a runtime database, which may contain elements of one or more documents. The elements can then be read, written to, and saved to a file. Table 22.3 lists some of the DAE functions that make this possible.

The first seven functions in the table are concerned with documents stored in the runtime database. They can be accessed by name or index, and can be loaded, unloaded, or saved as needed. The save function stores the document to the URI it was extracted from, and saveAs saves it to a new URI.

getDatabase returns a pointer to the runtime database. This is encapsulated within a daeDatabase object whose functions access the list of documents and their elements. The default database can be accessed by calling setDatabase with 0 or NULL as the argument:

dae->setDatabase(0);

The database can now be used to create documents and analyze their structure.