DOM guide: Working with documents

This section describes how to load COLLADA instance documents into the COLLADA runtime database and how to save the runtime database into COLLADA instance documents.

Instantiating the COLLADA DOM

In order to use the COLLADA DOM your client code needs to include the following two header files.

#include <dae.h>
#include <dom/domCOLLADA.h>

In order to use a specific effect profile, i.e. profile_COMMON, or profile_CG, you must include the header for that profile. For example,

#include <dom/domProfile_CG.h>

A very useful header to include is dom/domConstants.h. domConstants.h provides constants for strings that are commonly used in the DOM. These strings include all of the COLLADA element names and element type names.

• All examples in this users guide will use code that uses these constants.

After including the appropriate headers, your application needs to create a DAE object.

DAE *collada_dom = new DAE();

The DAE object is most commonly created from heap memory (using operator new) and accessed as a pointer but it can be created globally or on the stack and accessed directly. When finished with the COLLADA DOM, make sure that your DAE object is properly destructed. If using a pointer,

delete collada_dom;

is all that is needed.

Loading COLLADA Documents

Use the DAE::load() method to read an existing COLLADA document into the runtime database. When you load a document, the COLLADA DOM uses the document URI as the name of the document when searching or doing other operations where the document needs to be identified. In this example, the name of the document created by the load process is “file:///input_url_name.dae”, the same as the URI it was loaded from.

daeInt error = daeObject->load("file:///input_url_name.dae");

If the load was sucessful a value of DAE_OK will be returned. If a document with the same name, or the same docuemnt, has already been loaded, calling load will return DAE_ERR_COLLECTION_ALREADY_EXISTS.

• Please not that the terms "collection" and "document" mean the same thing in the COLLADA DOM interface and documentation.

A value of DAE_ERR_BACKEND_IO is returned for other errors encountered during load.

Unloading COLLADA Documents

Use the DAE::unload() method to unload a document from the runtime database. The document to be unloaded is specified by its document URI name. This function will return DAE_OK upon success or DAE_ERR_COLLECTION_DOES_NOT_EXIST if the document does not exist in the runtime database.

Saving COLLADA Documents

After you have completed any changes to the elements in the database, you can write the contents of the database to a new URL using the DAE::saveAs() method to save the specific collection. You can use either the document name or the document index to choose which collection to save.

daeInt error = daeObject->saveAs("output_url_name.xml", "file:///input_url_name.xml");

To save the document to the same location that it was loaded from use the DAE:save() function. DAE::save has two arguments that can be passed in. The first one is either the document name or the document index. The second and last one is an optional flag that specifies whether or not to overwrite any existing document. This flag defaults to true. DAE::saveAs has three arguments. The first is the URI to save the document as. The second is either the document name or the document index. If this argument is ommitted the COLLADA DOM defaults to saving the first document in the runtime database. The last argument is an optional flag that specifies whether or not to overwrite any existing document. This flag defaults to true.

• Note. The COLLADA DOM XML parser does not fully validate the data. It detects some types of errors in XML

input but not all of them. You may want to run new COLLADA data through an XML validator before loading it into the DOM. If you are developing programs that write COLLADA data, you should run a validator on the output of your programs during testing.

See also

• DOM load and save flow