DOM guide: Architecture
The COLLADA DOM architecture provides access to, and manipulation of, COLLADA documents.
The following diagram shows the components and communication flow of the COLLADA DOM.
The key components are:
- External instance data: The nonresident storage of COLLADA instance documents or databases.
- COLLADA DOM:
- COLLADA DOM backend: The components responsible for translating external COLLADA instance data into C++ runtime COLLADA objects. The default backend uses the libxml2 library to intelligently parse and translate the XML instance data.
- DAE interface: Provides the means through which applications interact with the COLLADA DOM. This interface provides document load and save functionality, access to the runtime database, access to the object model, and registration of integration objects.
- Object model: A set of C++ objects (COLLADA dom* objects) generated directly from the COLLADA schema. Each COLLADA dom* object derives from a specialized base class designed to provide reflectivity and robustness to the API. The generated object model is the basis of the runtime database, and is a C++ representation of the COLLADA schema elements.
- Runtime database: A resident, active cache of COLLADA elements. This cache is based on C++ COLLADA elements handed to the cache by the COLLADA DOM backend.
- Client application: The client application uses the COLLADA DOM to interact with COLLADA documents. Perhaps the client is a game engine that wants to load a COLLADA model for rendering in the game world. Or the client could be a 3D model editing package that wants to write a COLLADA model created by a user to a file.
The DAE class provides a simple, general-purpose interface to the replaceable COLLADA DOM backend and runtime database. This class serves as a wrapper for the entire pipeline, ensuring a consistent interface regardless of extensions to, or replacements for, the various DOM components.
The following is a subset of the public database-interface API. The complete API is defined in dae.h.
virtual DLLSPEC daeInt setDatabase(daeDatabase* database); virtual DLLSPEC daeInt load(daeString name, daeString docBuffer = NULL); virtual DLLSPEC daeInt save(daeString documentName, daeBool replace=true);
The COLLADA DOM was designed to allow the underlying database mechanism to be supplemented or replaced without affecting performance of the rest of the API components. The included front-end interface hands off generic queries through the API to any configured backend. Query results assembled by the backend are handed back to the runtime database for delivery in response to the original query. In addition, the front-end interface itself could be extended to provide a more robust or specific query feature set.
The COLLADA DOM is built upon a C++ object model that includes a reflective object system (ROS) and an object model that corresponds directly to the COLLADA XML schema definition.
Reflective Object System (ROS)
The COLLADA DOM is built upon a set of functionality that defines a self-managed, reflective object system (ROS). The ROS creates, manages, and manipulates DOM objects and the data that define their structure (meta-data) and contents.
The ROS is configured with metadata that, for COLLADA, defines the COLLADA object model. The COLLADA object model classes are created by the ROS at runtime, loaded with instance data, and passed to the runtime database.
COLLADA Object Model
The COLLADA object model is a C++ equivalent representation of the elements defined in the COLLADA schema.
The entire object model class hierarchy is automatically generated by Sony using a code generator that translates the COLLADA schema element definitions into C++ classes. Code generation of the COLLADA Object Model structures guarantees consistency with the schema and accuracy of the code.
Every COLLADA object model class is prefixed with "dom". The code generation builds in registration of meta-information about the structure of each element in the COLLADA object model. Via the static method registerElement() contained in every COLLADA object model class, the metadata about an element and its subelements are registered with the ROS, allowing it to understand, track, and manage each COLLADA DOM object.
At the heart of the COLLADA DOM is a runtime database, a resident cache of COLLADA elements. The runtime database is implemented as a C++ object, daeDatabase, with a virtual interface. The runtime database allows for simple requests of COLLADA objects by name, type, document, or any combination of the three through the database interface.
Database Query Manager
The COLLADA DOM does not include a query manager at this time, but it warrants mention because the addition of this component may be a useful extension to the runtime database. The COLLADA backend is essentially a wrapper providing access to a persistent data store. While the provided mechanism uses local XML files, it is expected that extensions for binary file formats as well as full database systems will be implemented. An intelligent query manager in the runtime database could cooperate with a particular backend data store to optimize query and retrieval of data for a particular application. The API has attempted to facilitate these extensions.
COLLADA DOM Backend
The COLLADA DOM backend consists of an abstract class, daeIOPlugin, with a virtual interface for reading and writing COLLADA to and from a persistent data store. Included with the API is one implementation, daeLIBXMLPlugin, which uses the libxml2 library to provide fully standards-compliant XML document loading. It is expected that other implementations of this interface would yield I/O modules for other types of persistent data stores, for example, binary files and database systems.
The COLLADA integration library is a set of generated template classes that exactly mirror the DOM objects. Every integration class is prefixed with int. Each integration class derives from a base class, daeIntegrationObject, which provides a virtual interface that defines the semantics for translation of COLLADA data to application structures. Starting with the COLLADA DOM integration library, developers need only define object equivalence by filling in translation functions from one C++ structure to another. See DOM guide: Integration templates for an example of how the integration library templates can be used.