Using accessors

From COLLADA Public Wiki
Revision as of 01:05, 28 April 2007 by Elf (talk | contribs) (first pass at adding Greg Corson's document dated April 19)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

This tutorial 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.

==subhead 1==
To properly read a source through an accessor, the program has to consider the data expected by a particular semantic, the stride, offset and 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.  The text in the name attribute is a user label only and does not effect how the data in the source is read. If you have a POSITION semantic reading a source with three params, it doesn’t matter if the params are named X, Y, Z or ONE, TWO, THREE the first value should always be treated as the X position, the second Y and the third Z.  If there are fewer param tags than the stride for the source, skip the values missing params.  ie: if you have a stride of 5 and only three param tags, you would read three values, skip two, read three more, skip 2…etc.

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 which 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.

Below are some examples that show how param, count, stride and offset interact.
For all of them assume your application has the vertex-map-like structure array below 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”/>

0 1 2

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

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

0 1 2

Because the 2nd param now has no name, it gets skipped, with only 2 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

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…etc. 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 veretex 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, all COLLADA applications should be able to handle data 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”/>

1 2 3

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…etc. The second accessor begins by skipping 3 values (the “offset”) then reads 3, skips 7…etc. 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


This next example produces the same results as the example above, but it uses the “skipping parameters with blank names” approach rather than an offset. This skipping behavior will only be supported 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”/>

1 2 3

After reading this example you have probably realized there are very few occasions where the “skipping praram’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.

An example of how this might be useful in an advanced program might be where a application has defined it’s 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.