Difference between revisions of "DOM guide: Working with documents"

From COLLADA Public Wiki
Jump to navigation Jump to search
 
(30 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
This section describes how to load [[COLLADA instance document]]s into the [[COLLADA runtime database]] and how to save the runtime database into COLLADA instance documents.
 
This section describes how to load [[COLLADA instance document]]s into the [[COLLADA runtime database]] and how to save the runtime database into COLLADA instance documents.
 +
:'''''Note:''' In some cases, pointer and return value checks have been removed from this code for brevity.''
  
 
==Creating the DAE Object==
 
==Creating the DAE Object==
Line 13: Line 14:
 
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 <code>operator new</code>) and accessed as a pointer.
 
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 <code>operator new</code>) and accessed as a pointer.
 
  DAE *collada_dom = new DAE();
 
  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.
+
Don't forget to call <code>operator delete</code> to delete the object when you're done. You could also create the DAE object globally or on the stack.
  
==URIs and File Paths==
+
==Loading Documents==
 +
Use the <code>DAE::load</code> 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 <code>file:///input_url_name.dae</code>, the same as the URI it was loaded from:
 +
daeInt error = collada_dom->load("file:///C:/Test/colladaDocument.dae");
  
A common mistake is to pass a Windows or Linux file path to the <code>DAE::load</code> or <code>DAE::save</code> methods. Like COLLADA itself, the DOM uses [http://en.wikipedia.org/wiki/Uniform_Resource_Identifier URIs] exclusively to reference resources or files. A file path needs to be converted to a [http://en.wikipedia.org/wiki/URI_scheme file scheme] URI before being passed to the COLLADA DOM. Below are some examples of converting a file path to a URI.
+
'''''Note:''' A common mistake is to pass a Windows or Linux file path to the <code>DAE::load</code> or <code>DAE::save</code> methods. See [[Using URIs in COLLADA]].''
 
 
'''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
 
 
 
==Loading COLLADA Documents==
 
Use the <code>DAE::load</code> 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:///input_url_name.dae");
 
  
 
The <code>DAE::load</code> method returns:
 
The <code>DAE::load</code> method returns:
Line 40: Line 30:
 
'''''Note:''' The terms "collection" and "document" mean the same thing in the COLLADA DOM interface and documentation.''
 
'''''Note:''' The terms "collection" and "document" mean the same thing in the COLLADA DOM interface and documentation.''
  
==Creating COLLADA Documents==
+
==Creating New 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]].
 +
daeDocument *doc = NULL;
 +
collada_dom->getDatabase()->insertDocument("file:///C:/Test/colladaDocument.dae", &doc);
 +
// doc is now a valid COLLADA document
  
==Unloading COLLADA Documents==
+
==Saving Documents==
If you want to release a document from memory you can use the <code>DAE::unload</code> method. The document to be unloaded is specified by its document URI name. This method returns either:
+
After you have completed any changes to the elements in the document, you can write the document to a new URL using the <code>DAE::save</code> method. You can use either the document name or the document index to choose which collection to save:
* <code>DAE_OK</code> upon success.
+
daeInt error = collada_dom->save("file:///C:/Test/colladaDocument.dae");
* <code>DAE_ERR_COLLECTION_DOES_NOT_EXIST</code> if 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.
+
To save the document to a different URI than the URI that was used to create it, use the <code>DAE:saveAs</code> 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.
  
==Saving COLLADA Documents==
+
'''''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 [[schema validation]].''
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 a specific document. 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()''' method. This method has only two arguments; the first is either the document name or the document index. The second is an optional flag that specifies whether to overwrite any existing document. This flag defaults to true.
+
==Querying and Removing Documents==
 +
Three functions allow you to query for and iterate over documents in the runtime database:
 +
* <code>daeDatabase::getDocumentCount</code>
 +
* <code>daeDatabase::getDocument</code>
 +
* <code>daeDatabase::isDocumentLoaded</code>
  
'''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 omitted, the COLLADA DOM defaults to saving the first document that is currently in the runtime database. The last argument is an optional flag that specifies whether to overwrite any existing document. This flag defaults to true.
+
If you want to release a document from memory, you can use the <code>DAE::unload</code> 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:
 +
* <code>DAE_OK</code> upon success.
 +
* <code>DAE_ERR_COLLECTION_DOES_NOT_EXIST</code> if the document does not exist in the runtime database.
  
'''''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.''
+
It's necessary to call <code>DAE::unload</code> only if you want the document released from memory immediately. Otherwise, the document is automatically removed when the parent DAE object is destroyed.
  
 
==See also==
 
==See also==
 
*[[DOM load and save flow]]
 
*[[DOM load and save flow]]
  
{{DOM tutorial}}
+
{{DOM navigation}}
  
[[Category:DOM tutorial|Loading and saving]]
+
[[Category:COLLADA DOM|Documents]]

Latest revision as of 23:43, 6 February 2008

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.

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:

#include <dom/domProfile_CG.h>

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();

Don't forget to call operator delete to delete the object when you're done. You could also create the DAE object globally or on the stack.

Loading 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 = collada_dom->load("file:///C:/Test/colladaDocument.dae");

Note: A common mistake is to pass a Windows or Linux file path to the DAE::load or DAE::save methods. See Using URIs in COLLADA.

The DAE::load method returns:

  • DAE_OK if the load is successful.
  • DAE_ERR_COLLECTION_ALREADY_EXISTS iff a document with the same name, or the same document, has already been loaded.
  • DAE_ERR_BACKEND_IO for other errors encountered during load.

Note: The terms "collection" and "document" mean the same thing in the COLLADA DOM interface and documentation.

Creating New 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.

daeDocument *doc = NULL;
collada_dom->getDatabase()->insertDocument("file:///C:/Test/colladaDocument.dae", &doc);
// doc is now a valid COLLADA document

Saving 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. See schema validation.

Querying and Removing Documents

Three functions allow you to query for and iterate over documents in the runtime database:

  • daeDatabase::getDocumentCount
  • daeDatabase::getDocument
  • daeDatabase::isDocumentLoaded

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_OK upon success.
  • DAE_ERR_COLLECTION_DOES_NOT_EXIST if the document does not exist in the runtime database.

It's necessary to call DAE::unload only if you want the document released from memory immediately. Otherwise, the document is automatically removed when the parent DAE object is destroyed.

See also


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