DOM guide: Working with documents
- Note: In some cases pointer and return value checks have been removed from this code for brevity.
Creating the DAE Object
To use the COLLADA DOM, your client code needs to include the following header files:
#include <dae.h> #include <dom/domCOLLADA.h>
To use a specific effect profile, such as <profile_COMMON> or <profile_CG>, you must include the header for that profile. For example:
A useful header to include is
dom/domConstants.h. This provides constants for strings that are commonly used in the DOM. These strings include all the COLLADA element names and element type names. Many examples to follow use these constants.
After including the appropriate headers, your application needs to create a DAE object. The following example shows a DAE object created on the heap (using
operator new) and accessed as a pointer.
DAE *collada_dom = new DAE(); // use the collada_dom variable delete collada_dom;
You could also create the DAE object globally or on the stack.
URIs and File Paths
A common mistake is to pass a Windows or Linux file path to the
DAE::save methods. Like COLLADA itself, the DOM uses URIs exclusively to reference resources or files. A file path needs to be converted to a file scheme URI before being passed to the COLLADA DOM. Below are some examples of converting a file path to a URI.
Example Description File Path URI Windows absolute path C:\folder\file.dae file:///C:/folder/file.dae Windows relative path ..\folder\file.dae ../folder/file.dae UNC path \\remoteMachine\folder\file.dae file://///remoteMachine/folder/file.dae Linux absolute path /folder/file.dae file:///folder/file.dae Linux relative path ../folder/file.dae ../folder/file.dae
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 = collada_dom->load("file:///C:/Test/colladaDocument.dae");
DAE::load method returns:
DAE_OKif the load is successful.
DAE_ERR_COLLECTION_ALREADY_EXISTSiff a document with the same name, or the same document, has already been loaded.
DAE_ERR_BACKEND_IOfor other errors encountered during load.
Note: The terms "collection" and "document" mean the same thing in the COLLADA DOM interface and documentation.
Creating New COLLADA Documents
You can use the COLLADA DOM to create a set of elements, add them to an empty database, and write the database to a COLLADA instance document. To do this, you need to ensure that you have a database created for use. When calling DAE::load or DAE::saveAs, the COLLADA DOM creates the default database and backend to use for those operations. If you start by creating data from scratch then you must ensure that there is a backend and a database created for use. This only needs to be done once per DAE object. To create and use the default database and backend, call
Now you're ready to create the document.
daeDocument *doc = NULL; collada_dom->getDatabase()->insertDocument("file:///C:/Test/colladaDocument.dae", &doc); // doc is now a valid COLLADA document
Saving COLLADA Documents
After you have completed any changes to the elements in the document, you can write the document to a new URL using the DAE::save method. You can use either the document name or the document index to choose which collection to save:
daeInt error = collada_dom->save("file:///C:/Test/colladaDocument.dae");
To save the document to a different URI than the URI that was used to create it, use the DAE:saveAs method. The last argument to all of the save methods is an optional flag that specifies whether to overwrite an 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.
((EDITOR: This page needs the following improvement: Explain how to validate a COLLADA document. ))
Three functions allow you to query for and iterate over documents in the runtime database:
Unloading COLLADA Documents
If you want to release a document from memory you can use the
DAE::unload method. The document to be unloaded is specified by its URI name. Removing a document removes the root element and subsequently the entire element hierarchy from the database. This method returns either:
DAE_ERR_COLLECTION_DOES_NOT_EXISTif the document does not exist in the runtime database.
It's only necessary to call DAE::unload if you want the document released from memory immediately. Otherwise, the document is automatically unloaded when the parent DAE object is destroyed.