DOM guide: Integration templates

When you load a COLLADA XML instance document into the COLLADA DOM, it creates a DOM object for each XML element in the COLLADA document. An application can then use DOM methods to read and manipulate the DOM objects. However, your application might already have its own data structures designed to represent the data coming from COLLADA XML elements and its own tools for manipulating those data structures. In that case, you can implement the COLLADA DOM's integration templates, which, when loading a COLLADA document, convert DOM objects into your application's data structures, and back again when saving. The integration templates cannot be used to create new COLLADA documents based on your runtime data structures.

This article provides a step-by-step example of how to integrate application data structures with the COLLADA runtime infrastructure (COLLADA DOM). Detailed knowledge of the COLLADA DOM architecture is not necessary to understand this example or to successfully integrate your own application-specific data structures.

Overview

The COLLADA Object Model is a set of runtime COLLADA DOM objects that correspond to elements in a COLLADA XML instance document (a COLLADA document). For importing, the COLLADA DOM builds these objects when it parses a COLLADA document. For exporting into a COLLADA document, you need to provide code to build the appropriate DOM objects.

To convert data contained in COLLADA DOM objects into your own application's data structures, the DOM provides integration templates for every object. The integration templates include plug-in points where you can insert conversion code (otherwise, the templates do nothing). After a COLLADA document has been imported by the DOM into COLLADA DOM objects, the DOM calls your conversion code to convert between the DOM objects and the application's data structures.

The following figure shows what happens during a load when integration templates are used.

The basic steps during integration are the following:

1. Application initializes the COLLADA DOM by creating a DAE object.
2. Application registers its application-specific integration libraries.
3. When importing a COLLADA document:
   1. Application begins the import by calling load.
   2. The DOM reads the COLLADA document and places its elements into runtime COLLADA DOM objects.
   3. The COLLADA runtime calls the conversion methods in the integration libraries to convert the content of COLLADA DOM objects into their associated data structures.
4. When exporting to a COLLADA document:
   1. Application begins the export of a COLLADA DAE structure by calling save.
   2. The COLLADA runtime calls registered conversion methods in the integration libraries to convert the content of the application's data structures into COLLADA DOM objects.
   3. The DOM exports the COLLADA document.

COLLADA DOM Integration Templates

Integration templates are used to convert DOM objects to your run-time data structures. Each DOM object has its own integration template consisting of a header (.h) file and a code (.cpp) file. For example, the DOM object for the COLLADA <node> element is domNode, and the template files to convert domNode objects to or from application data structures are intNode.cpp and intNode.h.

Copy into your application directory the template files for the elements that you want to convert from DOM objects into application-specific data structures. These copies are the starting points for your customized integration libraries. You can then add code to these integration libraries to do the conversion.

The plug-in points for your code are identified in comments in the template source, which is available in the integrationTemplates folder.

Integration Objects

Your integration library provides the code that defines an integration object for each DOM object. The integration object serves as the focal point for all information about the conversion. It defines methods that perform the conversion, and it provides data members that bind the DOM object with the application-specific data structure being converted to.

Integration objects are represented with the daeIntegrationObject class. Every class derived from daeElement provides for an integration object through the data member daeElement::_intObject.

The integration object class for each element is defined with the prefix "int". For example, the domGeometry class provides an intGeometry integration object.

When you define integration code for a DOM object, your code binds the DOM object with your application-specific object, via the _element and _object data members of the integration object. You can use methods daeIntegrationObject::getElement and getObject to access these data members.

When you load a COLLADA instance document, the DOM automatically creates the appropriate integration objects.

To get the integration object for an element, use the method daeElement::getIntObject, which also initiates the conversion process for any objects that have not yet been converted.

Integration Template Plugin Points

The integration class for each DOM object provides six plug-in points into which you can add conversion code. The plug-in points are implemented as methods; you provide the code for the method bodies. You need to implement the body of the methods only for those plug-in points that are relevant to your application.

The methods are:

• createFrom: Defines the code to create the application-specific data structure associated with the DAE class for this template. This method sets up the integration object for the DAE class.
• fromCOLLADA: Defines the code to covert a DOM object into your application-specific data structure.
• fromCOLLADAPostProcess: Defines any post-processing code that must execute after the basic conversion to your data structure.
• createTo: Defines code to create the DOM object associated with the DAE class for this template if such a structure does not already exist (for example, if it was not created while importing).
• toCOLLADA: Defines the code to covert the content of your application’s data structures into DOM objects.
• toCOLLADAPostProcess: Defines any post-processing code that must execute after the basic conversion from your application’s data structure.

Geometry Integration Example

This example demonstrates integration with the <geometry> element.

Creating the example has three basic steps, summarized as follows:

1. Copy the corresponding integration templates to application-specific versions.
2. Register these classes with the COLLADA DOM.
3. In the application runtime, add code to initialize the COLLADA DOM, call the file load, and request application objects from the integration classes.

Copying Integration Templates

The first step in the process of creating conversion code is to copy the relevant integration template files from the integration subdirectory into your application’s directory. For this example, the relevant integration templates are intGeometry.cpp and intGeometry.h. You will modify the copied files to contain your conversion code.

Registering Integration Libraries

For the DOM to create integration objects during parsing or before exporting, you must register the integration classes with the infrastructure. To do this, call the registerElement method on each integration class that you are using. A function to register these classes with the COLLADA DOM is defined in intRegisterElements.cpp, which is also provided in the template directory. You can copy this function into your application's directory, though you should only register those classes that you'll be using, which in this example is intGeometry. The relevant code is shown here:

void intRegisterElements()
{
    intGeometry::registerElement();
}

The integration file intGeometry.cpp provides the definition for the intGeometry class. Its contents are explained in a later step.

After the intRegisterElements function is defined, pass a handle to this function into the DAE::setIntegrationLibrary method, as described in the “Invoking Integration Libraries Registration” section.

Defining Your Application Data Structure

Within the integration library files, provide the code to create your application-specific data structure for the COLLADA DOM objects that you want to convert.

For this example, the application's data structure used to represent geometry is defined in an application header file, in this case, myGeometry.h:

// Definition of application's myPologon class also included here
class myGeometry
{
public:
    unsigned int _iVertexCount;
    float *_pVertices;
    std::vector<myPolygon> _vPolygons;
};

Provide the Plug-in Code to Create an Application Object for Importing

The plug-in method relevant to this step for importing is the createFrom method. Within the createFrom method, add code to create a new myGeometry object, initialize it, and initialize the intGeometry integration object data members. Within intGeometry.cpp:

void intGeometry::createFrom(daeElementRef element)
{
    // create class to hold geometry information and
    // initialize the new object as empty
    _object = new myGeometry();
    _object->pVertices = NULL;
    // set up the _element data member of the integration object
    _element = element;
}

Now, when a COLLADA instance document is loaded and a domGeometry object is encountered, the createFrom method automatically creates a new myGeometry object, because the intGeometry integration class has been registered with the DOM.

Build Conversion Code for Importing

Now add code to the integration library to translate the data stored in a DOM object to its associated application data structure. The fromCOLLADA method is the plug-in point for the basic application-specific conversion code. The fromCOLLADAPostProcess method provides additional flexibility for the conversion process.

Depending on the COLLADA DOM object and the application data structure, the code may vary significantly. For this example, we use the intGeometry::fromCOLLADA method to create new vertex buffers from the COLLADA DOM geometry object.

The following code retrieves the mesh object from the COLLADA domGeometry object:

// Get the geometry element from this integration object
domGeometry* geomElement = (domGeometry*)(domElement*)getElement();
domMesh *meshEl = geomElement->getMesh();

When we have the mesh, we can construct our application-specific data structure iVertices for the myGeometry object. The following code shows how to create the new vertex buffer.

// Get a pointer to the application-defined geometry object that was
// automatically created during load by calling createFrom.
myGeometry *local = (myGeometry *)_object;

// Get a pointer to the domPolygons in this domMesh. To simplify this example,
// we will handle only a domMesh that has a single domPolygons.
if(meshElement->getPolygons_array().getCount() != 1)
{
    fprintf(stderr, "This example supports only one domPolygons per domMesh\n");
    return;
}
domPolygons *polygons = meshElement->getPolygons_array()[0];

// To simplify this example, we assume the domPolygons has only one domInput.
if(polygons->getInput_array().getCount() != 1)
{
    fprintf(stderr, "This example supports only one domInput per domPolygons\n");
    return;
}

// Loop over all the polygons in the domPolygons element
int polygonCount = polygons->getCount();
for (int i=0;i<polygonCount;i++)
{
    myPolygon myPoly;
    // Get pointer to this polygon (domP).
    domPolygons::domP *poly = polygons->getP_array()[i];
    // Get the number of indices from the domP and save it in my structure.
    myPoly._iIndexCount = poly->getValue().getCount();
    // You can modify the data as you copy it from
    // the COLLADA object to your object.
    // Here we repeat the first index in list as the last index,
    // to form a closed loop that can be drawn as a line strip.
    myPoly._iIndexCount++;
    myPoly._pIndexes = new unsigned short[myPoly._iIndexCount];
    // Copy all the indices from the domP into my structure.
    for (int j=0;j<myPoly._iIndexCount-1;j++)
    myPoly._pIndexes[j] = poly->getValue()[j];
    // Repeat the first index at the end of the list to create a closed loop.
    myPoly._pIndexes[j] = myPoly._pIndexes[0];
    // Push this polygon into the list of polygons in my structure.
    local->_vPolygons.push_back(myPoly);
}

// Copy the vertices we are going to use into myGeometry. To keep things simple,
// we will assume there is only one domSource and domFloatArray in the domMesh,
// that it is the array of vertices, and that it is in X, Y, Z format. A real
// app would find the vertices by starting with domPolygons and following
// the links through the domInput, domVertices, domSource, domFloat_array,
// and domTechnique.
if(meshElement->getSource_array().getCount() != 1)
{
    fprintf(stderr, "This example supports only one source array per domMesh\n");
    return;
}
domSource *source = meshElement->getSource_array()[0];

if(source->getFloat_array().getCount() != 1)
{
    fprintf(stderr, "This example supports only one float array per source\n");
}
domFloat_array *floatArray = source->getFloat_array()[0];

// Assume there are 3 values per vertex with a stride of 3.
local->_iVertexCount = floatArray->getCount()/3;
local->_pVertices = new float[local->_iVertexCount*3];

// Copy the vertices into my structure one-by-one
// (converts from COLLADA's doubles to floats).
for ( unsigned int i = 0; i < local->_iVertexCount*3; i++ ) 
{
    local->_pVertices[i] = floatArray->getValue()[i];
}

Access COLLADA Objects from the Application

Now put together the application code that registers the integration libraries, loads the COLLADA elements into the in-memory DOM objects, and accesses the converted data.

Invoke Integration Library Registration

You defined the intRegisterElements function as described in “Register Integration Libraries with the DOM.” Now you must pass a handle to this function into the DAE::setIntegrationLibrary method.

With this step, the elements that you want to convert are registered with the DOM, and are converted from COLLADA DOM objects to application-specific structures when a COLLADA document is loaded, or the reverse when an object is saved.

For example, your main application code could pass a handle to the integration library registration function as follows:

// Instantiate the reference implementation
collada_dom = new DAE;
//register the integration objects
collada_dom->setIntegrationLibrary(&intRegisterElements);

Parse a COLLADA File

Now parse a COLLADA document into the run-time COLLADA Object Model. The load step creates the integration objects and invokes the createFrom and fromCOLLADA methods to convert the data from the COLLADA DOM objects into the application-defined data structures.

//load the COLLADA file
int res = collada_dom->load(filename);

Access a COLLADA Object

Now we'll find a domGeometry object to get at our application-specific data. We'll use the database for this. Here we request that the database return the first geometry element, placing it into domGeom.

Note: See Querying Database Elements for additional details on how to use the database to retrieve COLLADA DOM objects.

//query the runtime to retrieve an element
domGeometry* domGeom = 0;
int res = collada_dom->getDatabase()->getElement(
  (daeElement**)&domGeom, 0, NULL, COLLADA_TYPE_GEOMETRY);

Acquire the Converted Application Object

In the following code, the myGeometry class represents the application data structure containing geometry data. The domGeometry object retrieved above into domGeom contains a reference to its associated integration object (thanks to its earlier registration). The intGeometry class converts the domGeometry data into a myGeometry instance, which can then be retrieved with the getObject method.

// Get the integration object from the element
intGeometry *intGeom = (intGeometry*)domGeom->getIntObject();
// Extract the user data from the integration object
myGeometry* myGeom = (myGeometry*)intGeom->getObject();

Exporting Using Integration

The preceding sections showed how to set up your integration objects, import a COLLADA instance document, and ensure that the data is converted into data structures specific to your application.

If you modify data values and want to write it to a COLLADA instance document, the process is similar to reversing the import-and-convert process, although there are some differences.

Creating a New COLLADA DOM Object Using createTo

The functionality for creating new COLLADA DOM documents with the integration templates via the createTo method has always been broken, and wouldn't have been very useful even if it did work. Creating new COLLADA documents via the integration templates is now officially deprecated and won't be supported in the future. See this thread in the COLLADA forums for more details.

Exporting Modified Data Values

If you have modified the values of your application object and want to save to a revised COLLADA instance document, you'll need to update the associated COLLADA DOM objects before saving. This example shows how you might do that.

When you call save, the DOM calls toCOLLADA for every COLLADA element with an integration class. In the toCOLLADA method we'll copy the data from our application objects to the COLLADA objects. The code is essentially the reverse of the fromCOLLADA code in the importing example. We make several assumptions about the nature of the changes to make the code simpler. These assumptions are explained in the comments.

void intGeometry::toCOLLADA()
{
    // This code takes data from an application-defined object and
    // puts it back into the appropriate collada objects.
    // Get a pointer to the COLLADA domGeometry element
    // (this is the element that called us)
    domGeometry* geometryElement = (domGeometry*)_element;

    // Get a pointer to the domGeometry's domMesh element
    domMesh *meshElement = geometryElement->getMesh();

    // Get a pointer to my object that's assocated with this collada object
    myGeometry *local = (myGeometry *)_object;

    // Get a pointer to the domPolygons in this domMesh.
    // To simplify this example, we will handle only a domMesh 
    // that has a single domPolygons
    if(meshElement->getPolygons_array().getCount() != 1)
    {
        fprintf(stderr, "this example supports only one domPolygons per domMesh\n");
        return;
    }
    domPolygons *polygons = meshElement->getPolygons_array()[0];

    // To simplify this example, we assume that the domPolygons has
    // only one domInput.
    if(polygons->getInput_array().getCount() != 1)
    {
        fprintf(stderr, "this example supports only one domInput per domPolygons\n");
        return;
    }

    // Loop over all the polygons in the domPolygons element and
    // put the data from myGeometry back into it. For the purposes 
    // of the example, assume the number of polygons and indices 
    // hasn't changed so we can just update the values in place.
    int polygonCount = local->_vPolygons.size();
    polygons->setCount(polygonCount);
    for (int i=0;i<polygonCount;i++)
    {
        // Get pointer to this polygon (domP)
        domPolygons::domP *poly = polygons->getP_array()[i];
        // Copy all the indices from my structure back to the domP
        for (int j=0;j< local->_vPolygons[i]._iIndexCount-1;j++)
            poly->getValue()[j] = local->_vPolygons[i]._pIndexes[j] ;
    }

    // Now copy the vertices from myGeometry back to the source.
    // Assume that the number of vertices hasn't changed so we can 
    // just update them in place.
    if(meshElement->getSource_array().getCount() != 1)
    {
        fprintf(stderr, "this example supports only one source array per domMesh\n");
        return;
    }
    domSource *source = meshElement->getSource_array()[0];

    if(source->getFloat_array_array().getCount() != 1)
    {
        fprintf(stderr, "this example supports only one float array per source\n");
    }
    domFloat_array *floatArray = source->getFloat_array()[0];

    // Copy the vertices from myGeometry back into the COLLADA float array
    floatArray->setCount(local->_iVertexCount*3);
    for ( unsigned int i = 0; i < local->_iVertexCount*3; i++ ) 
    {
        floatArray->getValue()[i] = local->_pVertices[i];
    }
}

Using integration versus using the DOM directly

Integration classes provide a SAX-like approach to using the DOM. The biggest problem with this is that the interdependent links between COLLADA elements have become very complex. Parsing a DOM structure lends itself better to handling these problems. Creating an integration class to process <material>s, for example, may take the same amount of work as accessing the DOM structures directly. Here's a comparison.

Import <material> with an integration class:

1. Create class that inherits from daeIntegrationObject.
2. Implement the fromCOLLADA code to do the conversion.
3. Implement the fromCOLLADAPostProcess code to do the processing needed to resolve links to other elements, for example, <effect>.
4. Register your integration library with the DOM.

Import <material> without an integration class:

1. Get DOM by calling getDOM or getDOMRoot from the daeDocument.
2. For each <material> in each <library_materials>, call your conversion function (which would be the same as your fromCOLLADA). Your conversion function can even do the postprocess linking since all the data required by the other elements would be available.

Also you can't create COLLADA documents from scratch with an integration library.

DOM structures give you finer-grained control over what to convert; for example, you can spend time converting only the <geometry> elements used by a specific <visual_scene> and not the possibly dozens (or hundreds or thousands) of other <geometry> elements, while the integration classes convert all of them. This is especially useful if you have documents that cross-reference other documents. For example, imagine loading a document that contains a <visual_scene> where all the <instance_geometry> elements reference a <geometry> from a separate document. This document has only one <library_geometries> and contains all the <geometry> elements used for all your scenes, not just the one being loaded. Because the COLLADA DOM, by default, loads external documents to resolve the URIs, the integration classes will convert every <geometry> found in the second document. There could be lots of <geometry> elements and that could take a long time to process. This is especially wasteful since many <geometry> elements won't ever get used in the scene you're loading.