Syntax rules for COLLADA Extensions

From COLLADA Public Wiki
Jump to: navigation, search

This page describes the rules and guidelines for COLLADA syntax that is helpful while defining extensions.

Data conventions

Use the following conventions for the order of values and preferred constraints within a single element, for example:

<color>0 0 1 0</color>
Values Order
Colors/channels RGB or RGBA
Arrays and matrices Matrices in COLLADA are column matrices in the mathematical sense. Matrices are written in row at a time to aid the human reader.
 [ Sx  0   0   X
0 Sy 0 Y
0 0 Sz Z
0 0 0 1 ]
Radii Major (u direction) followed by minor (v direction)
Spatial info (translate, rotate, scale, etc.) Column vector [ X, Y, Z ], followed by a fourth value if appropriate. Only <translate> is a true column vector. The others are simply vectors of values that satisfy their respective designs. <scale> is the diagonal of a matrix. <skew> is an angle plus two column vectors as-in the Renderman notation. Prefer graphics industry over other conventions or local practices.
Translation/rotation combined Possible using either a matrix or a lookat element. Not recommended. Always allow discrete access to transforms.
Matrices Use only invertible matrices.
Tokens Text values that comprise a set of enumerants should be grouped as such.

Tokens

The COLLADA schema, and therefore an extension schema, has a few things that are comparable to API tokens:

  • public element names (e.g. <asset>)
  • public attribute names (e.g. <extra type="">)
  • public enumerations (e.g. <effect> profiles)
  • public text values (e.g. "X_AXIS", "LINEAR", "POSITION")

Enumeration elements that appear in a schema should have their values included and documented in the extension specification where appropriate. If the XML Schema language data type that expresses the enumeration's values is purely an implementation detail of the schema, its schema type name can be omitted from the specification.

Naming conventions

Abbreviations in element names

Spell out words fully (for example, vertices, not verts), except for the following existing COLLADA conventions:

  • Some names follow the problem domain conventions like OpenGL.
  • Some names follow the XML Schema naming conventions (e.g. IDREF).
  • Most names follow the COLLADA 1.5 Schema conventions (e.g. lowercase with underscores).
    • As a rule, follow the COLLADA 1.5 naming conventions.
Abbrev Word Example Note
2d, 3d 2-dimensional, 3-dimensional <create_2d> Exception like <sampler2D> follow a shading language conventions like Cg and OpenGL
brep boundary representation <brep>
coord coordinate(s) <fog_coord_src>
dest destination <dest_rgb>
env environment <texture_env_color>
fov field of view <xfov>
func function <alpha_func>
hex hexadecimal <hex>
id identifier <IDREF_array> id has specific meaning within XML and COLLADA
info information <axis_info>
init initialize <init_from>
int integer <int_array>
mag magnification <magfilter> This follows OpenGL conventions.
min, max minimum, maximum <minfilter>, <max>
mip MIPmap <mip_bias>
op operation, operator <color_logic_op_enable> In attribute names, spell out ("operator")
param parameter <connect_param>
RECT rectangle <samplerRECT> These follow OpenGL conventions.
ref reference <ref>, <ref_attachment> ref used as reference to id, sid, or URI.
RGB red/green/blue <RGB> This follows OpenGL conventions.
src source <fog_coord_src> The latter follows OpenGL conventions.
sid scoped identifier <SIDREF_array> sid has specific meaning within COLLADA
tex texture <texcombiner>, <texenv> The latter follows OpenGL conventions.

Following apply only when specifying indices (primitive values) for constructing polygons or vertices. The reason they are abbreviated (terse) is because they can be high frequency markup in the document:

Abbrev Word Example Note
p primitive - indices/vertex attributes for a polygon/etc. <p>, <pcurves>
ph primitive/hole - indices/vertex attributes for polygon with a hole <ph>
h hole - indices/vertex attributes for the hole within a polygon <h>
v vertices - indices for a vertex <v>

Attribute names

COLLADA uses the following names for attributes. Extensions should use the same names for equivalent functionality.

Note: This is not a complete list. Attributes that appear in only one or two elements aren't usually listed unless they might be of obvious future use.


Identifiers and references

Name Type(s) Meaning/Notes
axis xs:token (should be sidref_type) reference to a sid of an axis (in articulated_system/kinematics) or of an axis_info (in articulated_system/motion)
joint xs:token (should be sidref_type) reference to a sid of a joint or instance_joint
link xs:token (should be sidref_type) reference to a sid of a link
node xs:token (should be sidref_type) reference to a sid of a node
body sidref_type reference to sid of rigid body
id xs:ID unique identifier for element within instance document
material xs:NCName declares a symbol for a material that is bound at instantiation
name xs:token name for an element; not used by COLLADA, so application-defined usage. For names of anything else, qualify the attribute's name; for example, type_name. Exception is that <usertype> typename follows Cg/OpenGL conventions.
parent xs:anyURI reference to id
proxy xs:anyURI reference to the id of a node that is a proxy to the url node.
ref xs:token or xs:NCName refers to the sid of an existing element (in <param>, <setparam>)
rigid_body xs:anyURI reference to sid of rigid body
sid sid_type scoped identifer, unique within scope of parent element
source urifragment_type or xs:anyURI URI reference to some kind of input in the same or another document
target sidref_type or xs:anyURI or xs:string or xs:token where fragment identifier is id of element
url xs:anyURI or xs:anyURL reference to another resource that may include a fragment identifier

Measurements, counts, numeric values

Name Type(s) Meaning
array_index xs:unsignedInt index into an array
count uint_type or xs:unsignedLong quantity of values within the element, such as number of elements in array, number of edges, and so on
depth xs:unsignedInt depth value for a 3D image
digits xs:unsignedByte significant decimal digits in a float_array
height xs:unsignedInt or float_type second dimension of an area or image
index xs:nonNegativeInteger generic index
length xs:positiveInteger number of elements in array that uses a shading language convention. Also a spatial dimension.
magnitude xs:short largest exponent for values in a float_array
offset uint_type index of the first value to sample from an array
scale float_type generic scalar
value float4_type generic vector
width xs:unsignedInt or float_type first dimension of an area or image

Other values

Name Type(s) Meaning
enable xs:boolean generic flag
end xs:double end time
entry xs:token name of entry point into referenced program
face enumeration indicates a cube map face
format xs:token indicates the format of a binary encoded shader or image
mip xs:nonNegativeInteger MIP level
mode enumeration geo-spatial altitude mode
operator enumeration texture combiner operators
param xs:NCName SID of a shader value
platform xs:NCName or xs:string vendor-defined platform
profile xs:NMTOKEN or xs:NCName vendor or standard defined scope for a technique (i.e. extension).
semantic xs:NMTOKEN or xs:NCName shader, kinematic, or input semantic
set uint_type input set identifier
source enumeration texture combiner sources
source xs:anyURI or xs:NCName reference to a data source
start xs:double start time
stride uint_type sample size for a data source
symbol xs:NCName identifier that will be bound
type xs:NMTOKEN or enumeration meta data hint
typename xs:token shader data type
xmlns xs:anyURI points to XML Namespace

Constructing names and choosing terms

Note: Whereas some of the other rules in this document are intended to be strictly adhered to, this section is intended as a set of guidelines to assist in name decisions. The guidelines should be considered, and then accepted or rejected, for each case.

Terms used in COLLADA should have a consistent meaning. When new functionality is introduced, it is desired to use terms that are previously established in COLLADA. If no term exists that fits with the new functionality, a new term may be used. Whenever a new term is used, the precise meaning of that term should be specified and added to this text so that future functionality has the option of reusing the term with a consistent meaning.

A term in COLLADA should encompass more then the meaning of the word found in a dictionary. It should encompass limitations and usages and give the reader a broader sense of the usage of the word in the context of COLLADA.

When choosing new words, always name the item for what it does or what it describes or stores, not for the intended usage of the data and preferably not for its name in any one specific DCC tool.

General naming conventions

  • Always use specified abbreviations if one is given; otherwise, spell out words if possible for clarity. Never abbreviate terms that are already in the COLLADA schema and are not abbreviated. If you add terms to your extensions, abbreviate consistently, maintaining a local version of additions to the list of abbreviations.
  • Element and attribute names are singular and use all lowercase, separating words with underscores, with the following exceptions:
    • The <COLLADA> element matches the trademarked name in uppercase.
    • Profile names, second part all uppercase (<profile_COMMON>, <profile_GLES>...)
    • Certain FX names, no underscores and second part all uppercase (<sampler3D>, <samplerCUBE>, <texture3D...)
    • Plural only when necessary (<control_vertices>, <edges>,...).
  • COLLADA reserves UPPERCASE for text values (such as semantic values) in the common profile. For example, use "TEMPERATURE" not "temperature" or "Temperature". This is to ease migration from extension to standard schema specification.
  • Refer to "Naming in parameters" section.

Enums, groups, and common

Names follow all other naming conventions and:

  • Enumerations: end in _enum. Use the element or attribute name as the prefix when possible; for example, version_type defines values for the version attribute.
  • Groups: end in _group.
  • Common Profile Types: end in _common.

Naming in parameters

The COLLADA common profile uses the following naming conventions for canonical names:

  • Parameter names are uppercase. For example, the values for the <param> element’s name attribute are all uppercase letters:
 <param name="X" type="float"/> 
  • Parameter types are lowercase when they correspond to a primitive type in the COLLADA schema, in the XML Schema, or in the C/C++ languages. Type names are otherwise intercapitalized. For example, the values for the <param> element’s type attribute follow this rule:
 <param name="X" type="float"/> 
  • Input and parameter semantic names are uppercase. For example, the values for the <input> and <newparam> elements’ semantic attribute are all uppercase letters:
 <input semantic="POSITION" source="#grid-Position"/> 
 <newparam sid="blah">
   <semantic>DOUBLE_SIDED</semantic>
   <float>1.0</float>
 </newparam>

Canonical terms in the schema

The following terms have specific meanings in COLLADA or are used by convention in the same way throughout the COLLADA schema:

Term Examples Convention
array <IDEF_array>, <bool_array> Array type prepended
id <element id=xxx> ID attribute always
instance <instance_animation> Instances are always singular
library <library_animations> Libraries are always plural
name <element name=xxx> User-defined Name attribute always
profile <profile_GLES>, <profile_BRIDGE>, <technique profile="xxx"> Profiles include the profile name
sid <element sid=xxx> SID attribute always
url <element url=xxx> URL attribute always

Schema Internal Types

  • Simple and Complex Types are used to define elements and attributes in the COLLADA schema. The types do not appear in the Specification and are not intended for use in COLLADA documents.

Naming: Names follow all other naming conventions and:

  • types: end in _type. If it makes sense to do so, the name prefix is the same as the element that it defines; for example, instance_kinematics_scene_type describes the <instance_kinematics_scene> element.
  • Abstract types and/or substitution groups, for a specific area or product can be prefixed with an appropriate domain name (namespace name); for example, fx_sampler3D_type for use within COLLADA FX.

Numbers: To make the underlying format of numbers more flexible, COLLADA uses the following types:

  • float_type (floating point)
  • int_type (integer)
  • uint_type (unsigned integer)

Lists and matrices: User-visible (Spec-level) names include numbers indicating required quantity of values:

  • example:
<xs:simpleType name="bool3_type">
   <xs:restriction base="list_of_bools_type">
      <xs:minLength value="3"/>
      <xs:maxLength value="3"/>
   </xs:restriction>
</xs:simpleType>
  • example:
<xs:simpleType name="bool2x2_type">
   <xs:restriction base="list_of_bools_type">
      <xs:minLength value="4"/>
      <xs:maxLength value="4"/>
   </xs:restriction>
</xs:simpleType>


References: Attributes or element values that reference other elements that have id or sid attributes:

  • xs:IDREF (XML Schema type for an ID reference)
  • xs:anyURI (XML Schema type for a URI, typically a URL to another document with an ID fragment)
  • urifragment_type (COLLADA URI that is just an ID fragment)
  • sidref_type (COLLADA Scoped ID reference)