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>/<param> use with

 element arrays.

==Overview==
Surveys of COLLADA users have shown that the 1.4.1 [[specification]] description of how to use <accessor>s and <param>s 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 that 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 <input> ''semantic''
* The ''stride'' attribute value
* The ''offset'' attribute value
* The number of <param>s with nonnull 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> is skipped.  

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

If you have a POSITION ''semantic'' reading a <source> with three <param>s, it doesn’t matter whether the <param>s 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> elements than the ''stride'' for the source, skip the values that are missing <param>s.  For example, if you have a ''stride'' of 5 and only three <param> elements, you would read three values, skip two, read three more, skip 2, and so on.

==Example target data structure==
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];

==Example 1: A simple case==
Given a COLLADA <source> and a <triangles> element with <input>s 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>
</triangles>

You can read the data into my_array sequentially. Because the stride of the <accessor> is 3 and all three <param>s have names, the

 is assumed to contain 3D positions and '''my_array''' would be filled in like this:

{| border=1 cellpadding=3 cellspacing=0
|-
!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: 

 <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 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> 
</triangles>

Because the second <param> now has no name, it is skipped. With only two named <param>s, the

 is assumed to contain 2D positions and is read like this:


{| border=1 cellpadding=3 cellspacing=0
|-
!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: Multiple accessors with a single source array==
Usually an application creates one <source>/<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 that 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 <source>s and <accessor>s 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.

 <source id=positions>
   <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> 
</triangles>

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 <accessor>s 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 <param>s 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>
</triangles>

After reading this example, you may realize 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 application-defined techniques that may have application-defined semantics where skipping values in the middle of a source array is useful.

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's 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.

Conformance testing note

Although the COLLADA conformance test process is not yet complete, at this time (April 2007) we do not plan to require basic COLLADA programs to support skipping of <param>s with blank or missing name attributes. This behavior is rarely useful for <technique_common> semantics and COLLADA data. Because application-defined techniques and semantics are considered advanced features, skipping <param>s with blank names will also be considered an advanced feature.