Using accessors: Difference between revisions
Jump to navigation
Jump to search
wiki format code & tables |
basic editing pass |
||
| Line 1: | Line 1: | ||
This is one of several COLLADA [[tutorials]]. | |||
This tutorial provides examples of [[COLLADA]] <accessor> <source> and <param> use. | This tutorial provides examples of [[COLLADA]] <accessor> <source> and <param> use. | ||
| Line 4: | Line 6: | ||
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. | 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 | 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.'' | |||
For all of them assume your application has the vertex-map-like structure array | |||
==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 | struct | ||
| Line 41: | Line 50: | ||
{{editor|what=Check closing of triangles in all examples}} | {{editor|what=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 | 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: | ||
{| border=1 cellpadding=3 cellspacing=0 | {| border=1 cellpadding=3 cellspacing=0 | ||
| Line 54: | Line 63: | ||
|} | |} | ||
==Example 2: Parameter Skipping== | |||
This is an example of the advanced parameter skipping usage: | This is an example of the advanced parameter skipping usage: | ||
| Line 73: | Line 83: | ||
<nowiki><p>0 1 2</p> </nowiki> | <nowiki><p>0 1 2</p> </nowiki> | ||
Because the | 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: | ||
| Line 87: | Line 97: | ||
|} | |} | ||
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 | ==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 | 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. | ||
<source id=positions> | <source id=positions> | ||
| Line 136: | Line 147: | ||
<nowiki><p>1 2 3</p> </nowiki> | <nowiki><p>1 2 3</p> </nowiki> | ||
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 | 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: | ||
{| border=1 cellpadding=3 cellspacing=0 | {| border=1 cellpadding=3 cellspacing=0 | ||
| Line 149: | Line 160: | ||
|} | |} | ||
==Example 4: Parameters with blank names== | |||
This next example produces the same results as the example | 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. | ||
<source id=positions> | <source id=positions> | ||
| Line 214: | Line 225: | ||
<nowiki><p>1 2 3</p></nowiki> | <nowiki><p>1 2 3</p></nowiki> | ||
After reading this example you have probably realized there are very few occasions where the “skipping | 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|what=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 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. | ||
[[Category:COLLADA|Accessors]] | [[Category:COLLADA|Accessors]] | ||
Revision as of 01:34, 28 April 2007
This is one of several COLLADA tutorials.
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.
==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.