Extension

From COLLADA Public Wiki
Jump to: navigation, search
This article is about COLLADA extensions. For:

COLLADA provides flexibility by allowing applications to define extensions to existing COLLADA elements. These extensions take the form of alternative <technique> elements, additive <extra> elements, and scalable <input> elements.

Extension by alternative

COLLADA enables extensibility and multiple representation of many of its elements using one <technique_common> and zero or more alternative <technique> elements:

  • The common technique, which is required by the schema, is a strongly typed representation of the element.
  • Other techniques are defined by the vendor supplying the alternative representation. Each <technique> has a profile attribute that specifies the platform (product name or similar) to which the representation applies.

Each alternative representation contains values that describe the element for that profile. The representations may have coherency between profiles, although that is not required. For example, if <technique_common> describes an ambient light, an alternative <technique> for that light could validly describe either a different kind of ambient light or something else, such as an area light, for the specified profile.

Using <technique> to choose profiles

Where alternative choices are possible within the schema, the <technique> element models the alternative extensions. A COLLADA processor chooses one, and only one, of the available alternatives, either the <technique_common> or one of the <technique> elements. For example:

 <light>
   <technique_common>
     <ambient>
       <color/>
     </ambient>
  </technique_common>
  <technique profile="alternative_1">
    <ambient>
      <color/>
    </ambient>
  </technique>
  <technique profile="alternative_2">
    <arealight />
  </technique>
 </list>

Extension by addition

An extensible schema also requires a means for specifying arbitrary information. This extra information can represent additional real data or semantic (meta) data to the application.

COLLADA represents extra information using <technique> elements within an <extra> element. Each <technique> contains arbitrary XML elements and data and is labeled with a profile attribute specifying the environment to which it applies.

Using <extra> to add data

Here is an example of an <extra> element that outlines both structured and unstructured additional content:

<geometry>
 <extra>
   <technique profile="Max" xmlns:max="some/max/schema"> 
     <param name="wow" sid="animated" type="string">a validated string parameter from the COLLADA schema.</param> 
     <max:someElement>defined in the Max schema and validated.</max:someElement> 
     <uhoh>something well-formed and legal, but that can’t be validated because there is no schema for it!</uhoh> 
   </technique>
 </extra>
<geometry>

Scalable Data Streams

The COLLADA schema design takes different approaches for low and high frequency data in order to achieve a good balance between information and (self describing) verbosity. Low frequency data is modeled as individual XML elements and attributes, with descriptive names. High frequency data is modeled as streams (homogeneous arrays) of values, often with a terse element name (e.g. <p> for "primitive").

High frequency data, such at vertex attribute or animation key-frame data, is represented by a streaming data model where a data sink connects inputs to a data source. The data sources are represented by the <source> element. Examples of data sinks are: <triangles>, <polylist>, <vertex_weights>, etc.; basically anything that uses the <input> element is a data sink.

In COLLADA, the <source> element does not have or provide data semantics. It is raw data that can be shared by any number of data sinks (consumers). It is the consumer of that data that binds a semantic to the data for its own usage model. The text value of the semantic attribute can be any user-defined word that's valid for the XML Schema NMTOKEN data type.

NOTE: User-defined stream semantics are not constrained to a specific profile as they are meant to be well-known and shared.

Using <input> to add Vertex Attribute streams

The COLLADA geometry model represents a geometry as a high level collection of data sources and sinks. The collection is categorized as a mesh, convex mesh, spline, or boundary representation (B-rep). The data sinks are geometric primitives that describe the collation of vertex data from their input streams, one vertex at a time; thereby assembling the primitives.

The number of attributes values per vertex is not predefined or fixed. Each geometric primitive can declare an unbounded number of inputs from which to assemble primitives. Each input provides a connection to a data source and binds a semantic to the stream, e.g. a vertex attribute semantic such as VERTEX, POSITION, NORMAL, or TEXCOORD.

A typical geometry is the mesh geometry, represented roughly as:

<geometry>
 <mesh>
  <source id="A" />
  <vertices id="V" >
   <input semantic="POSITION" source="#A" />
  </vertices>
  <triangles>
   <input semantic="VERTEX" source="#V" />
   <p> ... </p>
  </triangles>
 </mesh>
</geometry>

The previous example shows a single geometric primitive that assembles triangles with minimal vertex attributes (i.e. position data). It is trivial to extend the attribute data bound to each vertex with additional inputs. For example we can add mesh vertex normals to the previous example as follows:

<geometry>
 <mesh>
  <source id="A" />
  <source id="B" />
  <vertices id="V" >
   <input semantic="POSITION" source="#A" />
   <input semantic="NORMAL"   source="#B" />
  </vertices>
  <triangles>
   <input semantic="VERTEX" source="#V" />
   <p> ... </p>
  </triangles>
 </mesh>
</geometry>

Alternatively, we can add per-primitive vertex normals to the first example instead (compare this to the previous example):

<geometry>
 <mesh>
  <source id="A" />
  <source id="B" />
  <vertices id="V" >
   <input semantic="POSITION" source="#A" />
  </vertices>
  <triangles>
   <input semantic="VERTEX" source="#V" />
   <input semantic="NORMAL" source="#B" />
   <p> ... </p>
  </triangles>
 </mesh>
</geometry>

Furthermore, we can add both mesh (invariant to primitives) and per-primitive vertex attributes in combination, as follows:

<geometry>
 <mesh>
  <source id="A" />
  <source id="B" />
  <source id="C" />
  <vertices id="V" >
   <input semantic="POSITION" source="#A" />
   <input semantic="NORMAL"   source="#B" />
  </vertices>
  <triangles>
   <input semantic="VERTEX" source="#V" />
   <input semantic="NORMAL" source="#C" />
   <p> ... </p>
  </triangles>
 </mesh>
</geometry>

Finally, we can add new input semantics, either from the COLLADA specification or user-defined, to extend (scale up) the number of attribute values bound to each vertex. For example:

<geometry>
 <mesh>
  <source id="A" />
  <source id="B" />
  <source id="C" />
  <source id="D" />
  <source id="M1" />
  <source id="M2" />
  <vertices id="V" >
   <input semantic="POSITION"          source="#A" />
   <input semantic="NORMAL"            source="#B" />
   <input semantic="MY_VERT_ATTRIBUTE" source="#M1" />
  </vertices>
  <triangles>
   <input semantic="VERTEX"           source="#V" />
   <input semantic="NORMAL"           source="#C" />
   <input semantic="TEXCOORD"         source="#D" />
   <input semantic="MY_TRI_ATTRIBUTE" source="#M2" />
   <p> ... </p>
  </triangles>
 </mesh>
</geometry>

See also