DOM guide: Architecture

From COLLADA Public Wiki
Jump to navigation Jump to search

The COLLADA DOM architecture provides access to, and manipulation of, COLLADA documents.

Components

The following diagram shows the components and communication flow of the COLLADA DOM.

Figure 1 - The COLLADA DOM
DOMarchitecture.png

The key components are:

  • COLLADA DOM:
    • I/O plug-in: The components responsible for translating external COLLADA instance data into C++ runtime COLLADA objects. The default plug-in 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 I/O plug-in.
  • 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.

DAE Interface

The DAE class provides a simple, general-purpose interface to the replaceable I/O plug-in 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 I/O plug-in. Query results assembled by the I/O plug-in 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.

Object Model

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.

Figure 2 - The COLLADA Object Model
DOMobjectModel.png

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.

Runtime Database

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 I/O plug-in 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 plug-in data store to optimize query and retrieval of data for a particular application. The API has attempted to facilitate these extensions.

I/O Plug-In

The COLLADA DOM I/O plug-in 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.

Integration Library

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.


COLLADA DOM - Version 2.4 Historical Reference
List of main articles under the DOM portal.
User Guide chapters:  • Intro  • Architecture  • Setting up  • Working with documents  • Creating docs  • Importing docs  • Representing elements  • Working with elements  • Resolving URIs  • Resolving SIDs  • Using custom COLLADA data  • Integration templates  • Error handling

Systems:  • URI resolver  • Meta  • Load/save flow  • Runtime database  • Memory • StringRef  • Code generator
Additional information:  • What's new  • Backward compatibility  • Future work
Terminology categories:  • COLLADA  • DOM  • XML