Using accessors

Tutorials
This article is one several tutorials, guides, and annotated examples available in this wiki.
Multipage tutorials:  • COLLADA DOM user guide Shorter how-tos:  • Using accessors  • Schema validation • Using URIs  • Various annotated examples Instructions for adding a tutorial

[[Category: ]]

This tutorial about using accessors provides examples of COLLADA <accessor>

 and <param> use.

==Overview==
Surveys of COLLADA users have shown that the 1.4.1 [[specification]] description of how to use accessors and params to read a source can be confusing and needs to be clarified.  Many people think this is much more complicated than it actually is so we recommend everyone read this, as it may save you some work.

==How accessors work==
To properly read a source through an accessor, the program has to consider:
* The data expected by a particular semantic
* The stride
* The offset
* The number of params with non-null names to decide which values to read and which to skip

Semantics in an <input> imply a specific data ordering in a source, such as X, Y, Z  for positions or R, G, B for colors.  If the name= attribute in a <param> is missing or empty, the corresponding value in the source should be skipped.  

'''''Note:''' The text in the name attribute is a user label only and does not affect how the data in the source is read.''

If you have a POSITION semantic reading a source with three params, it doesn’t matter whether the params are named X, Y, Z or ONE, TWO, THREE: the first value should always be treated as the X position, the second as Y, and the third as Z.  If there are fewer param tags than the stride for the source, skip the values that are missing params.  For example, if you have a stride of 5 and only three param tags, you would read three values, skip two, read three more, skip 2, and so on.

'''''Note:''' While the COLLADA conformance test process is not yet complete, at this time we do not plan to require basic COLLADA programs to support skipping of params with blank or missing name attributes.  This behavior is rarely useful for “technique_common” semantics and COLLADA data.  The parameter skipping feature is mainly of use with application-defined techniques that may have application-defined semantics where skipping values in the middle of an array is useful.  Because application-defined techniques and semantics are considered an advanced feature, skipping params with blank names will also be considered an advanced feature.''

==Example 1: A simple case==
The following examples show how param, count, stride, and offset interact.
For all of them, assume that your application has the following vertex-map-like structure array that it’s trying to fill with geometry.

 struct
 {
    float x_pos, y_pos, z_pos, x_norm, y_norm, z_norm, text1_U, tex1_V, tex2_U tex2_V;
 } my_array[1000];

Given a COLLADA source and a triangles tag with inputs like this:

 <source id=test1>
   <float_array name="values" count="9">
     1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0 9.0
   </ float _array>
   <technique_common>
     <accessor source="#values" count="3" stride=”3”>
       <param name="A" type="float"/>
       <param name="F" type="float"/>
       <param name="X" type="float"/>
     </accessor>
   </technique_common>

<triangles count=”1”> 
<input semantic="POSITION" source="#test1" offset=”0”/>
<p>0 1 2</p>

((EDITOR: This page needs the following improvement: Check closing of triangles in all examples ))

You can read the data into my_array sequentially. Because the stride of the accessor is 3 and all three params have names, the source is assumed to contain 3d positions and my_array would be filled in like this:

X_pos	Y_pos	Z_pos	X_norm	Y_norm	Z_norm	Tex1_U	Tex1_V	Tex2_U	Tex2_v
1.0	2.0	3.0
4.0	5.0	6.0
7.0	8.0	9.0

Example 2: Parameter Skipping

This is an example of the advanced parameter skipping usage:

   <float_array name="values" count="9">
     1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0 9.0
   </ float _array>
   <technique_common>
     <accessor source="#values" count="3" stride=”3”>
       <param name="A" type="float"/>
       <param type="float"/>
       <param name="X" type="float"/>
     </accessor>
   </technique_common>

<triangles count=”1”>
<input semantic="POSITION" source="#test1" offset=”0”/>
<p>0 1 2</p> 

Because the second param now has no name, it gets skipped. With only two named params, the source is assumed to contain 2d positions and is read like this:

X_pos	Y_pos	Z_pos	X_norm	Y_norm	Z_norm	Tex1_U	Tex1_V	Tex2_U	Tex2_v
1.0	3.0
4.0	6.0
7.0	9.0

Example 3: ?

Most of the time an application will create one source and float array for each type of data. For example, a stride-3 array for positions, another for normals, a stride-2 array for texture coordinates, and so on. Most COLLADA documents you download will be organized this way, so it’s easy to find an example of how this looks.

Some applications may want to pack all the information about a vertex into a single source array that is similar to an OpenGL vertex array. This requires creating several sources and accessors that all reference data in the same float_array. This can be done using only basic COLLADA features, so all COLLADA applications should be able to handle this data.

   <float_array name="values" count="30">
     1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
   </ float _array>
   <technique_common>
     <accessor source="#values" count="3" stride=”10”>
       <param name="NAME" type="float"/>
       <param name="VALUES" type="float"/>
       <param name="ARE" type="float"/>
     </accessor>
   </technique_common>

   <technique_common>
     <accessor source="#values" offset=”3” count="3" stride=”10”>
       <param name="NOT" type="float"/>
       <param name="SIGNIFICANT" type="float"/>
       <param name="X" type="float"/>
     </accessor>
   </technique_common>

   <technique_common>
     <accessor source="#values" offset=”6” count="3" stride=”10”>
       <param name="A" type="float"/>
       <param name="F" type="float"/>
     </accessor>
   </technique_common>

   <technique_common>
     <accessor source="#values" offset=”8”  count="3" stride=”10”>
       <param name="Q" type="float"/>
       <param name="F" type="float"/>
     </accessor>
   </technique_common>

<triangles count=”1”>
<input semantic="POSITION" source="#positions" offset=”0”/>
<input semantic="NORMAL" source="#normals" offset=”0”/>
<input semantic="TEXCOORD" source="#texture1" offset=”0”/>
<input semantic="TEXCOORD" source="#texture2" offset=”0”/>
<p>1 2 3</p> 

The first accessor tells you to start with the first value in the source, read three values into the position part of your array, skip 7 values, read three more positions, and so on. The second accessor begins by skipping 3 values (the “offset”) then reads 3, skips 7, and so on. An application could also decide to read the entire COLLADA float_array into a 10-column-wide array in memory, then use the accessors as a way to identify what is in each column of the array. Regardless of how you do it, “my_array” would end up getting filled in like this:

X_pos	Y_pos	Z_pos	X_norm	Y_norm	Z_norm	Tex1_U	Tex1_V	Tex2_U	Tex2_v
1.0	2.0	3.0	4.0	5.0	6.0	7.0	8.0	9.0	10.0
11.0	12.0	13.0	14.0	15.0	16.0	17.0	18.0	19.0	20.0
21.0	22.0	23.0	24.0	25.0	26.0	27.0	28.0	29.0	30.0

Example 4: Parameters with blank names

This next example produces the same results as the preceding example, but it uses the “skipping parameters with blank names” approach rather than an offset. This skipping behavior is supported only by advanced programs, so it may be wise to avoid using it if you can.

   <float_array name="values" count="30">
     1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
   </ float _array>
   <technique_common>
     <accessor source="#values" count="3" stride=”10”>
       <param name="A" type="float"/>
       <param name="F" type="float"/>
       <param name="X" type="float"/>
     </accessor>
   </technique_common>

   <technique_common>
     <accessor source="#values" count="3" stride=”10”>
       <param type="float"/>
       <param type="float"/>
       <param type="float"/>
       <param name="A" type="float"/>
       <param name="F" type="float"/>
       <param name="X" type="float"/>
     </accessor>
   </technique_common>

   <technique_common>
     <accessor source="#values" count="3" stride=”10”>
       <param type="float"/>
       <param type="float"/>
       <param type="float"/>
       <param type="float"/>
       <param type="float"/>
       <param type="float"/>
       <param name="A" type="float"/>
       <param name="F" type="float"/>
     </accessor>
   </technique_common>

   <technique_common>
     <accessor source="#values" count="3" stride=”10”>
       <param type="float"/>
       <param type="float"/>
       <param type="float"/>
       <param type="float"/>
       <param type="float"/>
       <param type="float"/>
       <param type="float"/>
       <param type="float"/>
       <param name="F" type="float"/>
       <param name="X" type="float"/>
     </accessor>
   </technique_common>

<triangles count=”1”>
<input semantic="POSITION" source="#positions" offset=”0”/>
<input semantic="NORMAL" source="#normals" offset=”0”/>
<input semantic="TEXCOORD" source="#texture1" offset=”0”/>
<input semantic="TEXCOORD" source="#texture2" offset=”0”/>
<p>1 2 3</p>

After reading this example you have probably realized that there are very few occasions where the “skipping param’s with blank names” behavior would be used, at least with “technique_common” COLLADA data. The parameter skipping is mainly of use for user-defined techniques which may have user-defined semantics where skipping values in the middle of a source array is useful. That is why this feature is not required for basic programs. ((EDITOR: This page needs the following improvement: check whether this paragraph is redundant with earlier note ))

An example of how this might be useful in an advanced program might be where an application has defined its own semantic that reads a vertex array positions and a set of texture coordinates. The float_array in the COLLADA document could potentially contain more than one set of texture coordinates, each designed to produce an object with a different appearance. The blank param skipping behavior could be used to select which set of texture coordinates would be used when drawing primitives for different versions of the object.