Difference between revisions of "Talk:DOM guide: Working with documents/old version"

From COLLADA Public Wiki
Jump to navigation Jump to search
m (typos)
(rm catg from talk pg)
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
The Runtime Database is a resident, active cache of COLLADA elements. This cache is based on C++
+
'''NOTE: This is an obsolete version of this article. It is preserved here primarily to preserve its edit history; all the content from here was moved to other articles and now we're going to reuse the article title for something else.'''
COLLADA elements handed to the cache by the COLLADA Backend.
 
  
==Querying the Database==
 
===Querying Elements===
 
The current version of the COLLADA DOM provides two methods to query the database to get
 
information about specific elements, daeDatabase::getElementCount() and
 
daeDatabase::getElement().
 
  
The method getElementCount() returns the number of elements for a particular query. For example, the
+
After  you have loaded a [[COLLADA instance document]], or before saving one, it is represented in the [[DOM runtime database]]. You can manipulate the DOM representation of documents in the database using the '''daeDatabase''' object.
following code asks how many <image> elements are in the database:
 
imageCount = daeObject->getDatabase()->getElementCount(NULL, COLLADA_ELEMENT_IMAGE, NULL);
 
The additional parameters to getElementCount() make the request more specific. The first parameter
 
represents the ID of the element. The third parameter represents the name of the document, and
 
might be used if you have loaded elements from multiple instance documents.
 
  
The method getElement() requests that the database return a specific element. For example, the
+
==Querying Documents==
following code returns an image element with an index that matches the value in el_number.
+
Three functions allow you to query for and iterate over documents in the runtime database:
domImage *thisImage;
+
* <code>daeDatabase::getDocumentCount</code>
daeInt error = daeObject->getDatabase()->getElement((daeElement**)&thisImage, el_number, NULL, COLLADA_ELEMENT_IMAGE, NULL);
+
* <code>daeDatabase::getDocument</code>
The element itself is returned in the first parameter. The third parameter restricts the query to a specific
+
* <code>daeDatabase::isDocumentLoaded</code>  
element by ID, and the fifth parameter restricts the search to a specific document.
 
  
Typically, getElementCount() and getElement() are used as a pair, first getting the number of
+
The following function removes a document from the runtime database. Removing a document removes the root element and subsequently the entire element heirarchy from the database:
elements that match a particular ID, type, or document query, and then iterating through those by
+
* <code>daeDatabase::removeDocument</code>
using the getElement() method. For example, if you want to take an action on all of the images in the
 
database, you could do the following:
 
  
imageCount = daeObject->getDatabase()->getElementCount(NULL, COLLADA_ELEMENT_IMAGE, NULL);
+
==Creating New Documents==
for (unsigned int i=0; i<imageCount; i++)
+
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. To create and use the default database and backend, call
{
 
    error = daeObject->getDatabase()->getElement((daeElement**)&thisImage, i, NULL, COLLADA_ELEMENT_IMAGE, NULL);
 
/* take action on this image */
 
}
 
 
 
As another example, if you want to take action on all images with the name “landImage”, you could do
 
the following:
 
imageCount = daeObject->getDatabase()->getElementCount("landImage", COLLADA_ELEMENT_IMAGE, NULL);
 
for (unsigned int i=0; i<imageCount; i++)
 
{
 
    error = daeObject->getDatabase()->getElement((daeElement**)&thisImage, i, "landImage", COLLADA_ELEMENT_IMAGE, NULL);
 
/* take action on this land image */
 
}
 
 
 
The index passed to getElement() is not directly associated with the element within the database. The
 
index relates to the query itself. The queries used for getElementCount() and getElement() must
 
match in order for the index to be valid when passed to the getElement() method.
 
  
===Querying Documents===
 
The functions <code>daeDatabase::getDocumentCount</code>, <code>daeDatabase::getDocument</code>, and <code>daeDatabase::isDocumentLoaded</code> allow you to query for and iterate over documents in the runtime database.
 
 
<code>daeDatabase::removeDocument</code> will remove a document from the runtime database. Removing a document removes the root element and subsequently the entire element heirarchy from the database.
 
 
==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. To do this you need to ensure that you have a database created for use. When callind DAE::load or DAE::saveAs, the COLLADA DOM will create 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 backend and database created for use. To create and use the default database and backend call
 
 
  collada_dom->setDatabase(NULL);
 
  collada_dom->setDatabase(NULL);
 
  collada_DOM->setIOPlugin(NULL);
 
  collada_DOM->setIOPlugin(NULL);
Each document in the COLLADA DOM requres a domCOLLADA element as the root element for the document. <code>daeDatabase::insertDocument(daeString, daeDocument**)</code> and <code>daeDatabase::createDocument(daeString, daeDocument**)</code> will create a domCOLLADA root element automatically.
 
  
<code>daeDatabase::insertDocument(daeString, daeElement*, daeDocument**)</code> and <code>daeDatabase::createDocument(daeString, daeElement*, daeDocument**)</code> allow you to pass in an existing domCOLLADA element to be used for the document root.
+
Each document in the COLLADA DOM requres a '''domCOLLADA''' element as the root element for the document. These functions  create a '''domCOLLADA''' root element automatically:
 +
* '''daeDatabase::insertDocument(daeString, daeDocument**)'''
 +
* '''daeDatabase::createDocument(daeString, daeDocument**)'''
 +
 
 +
These functions allow you to pass in an existing domCOLLADA element to be used for the document root:
 +
*'''daeDatabase::insertDocument(daeString, daeElement*, daeDocument**)'''
 +
*'''daeDatabase::createDocument(daeString, daeElement*, daeDocument**)'''
  
<code>daeDatabase::insertDocument(daeString, daeDocument**)</code> and <code>daeDatabase::insertDocument(daeString, daeElement*, daeDocument**)</code> will create a daeDocument and insert it into the database. The document created will be returned in the last argument.
+
These functions  create a '''daeDocument''' and insert it into the database. The document created is returned in the last argument:
 +
* '''daeDatabase::insertDocument(daeString, daeDocument**)'''
 +
* '''daeDatabase::insertDocument(daeString, daeElement*, daeDocument**)'''
  
The <code>daeDatabase::createDocument</code> functions allow you to create a new COLLADA document without inserting it into the database. You can later call <code>daeDatabase::insertDocument( daeDocument *c )</code> to insert the document into the database.
+
The '''daeDatabase::createDocument''' functions allow you to create a new COLLADA document without inserting it into the database. You can later call '''daeDatabase::insertDocument( daeDocument *c )''' to insert the document into the database.
  
[[Category:DOM project]]
+
{{DOM tutorial}}

Latest revision as of 00:48, 31 May 2007

NOTE: This is an obsolete version of this article. It is preserved here primarily to preserve its edit history; all the content from here was moved to other articles and now we're going to reuse the article title for something else.


After you have loaded a COLLADA instance document, or before saving one, it is represented in the DOM runtime database. You can manipulate the DOM representation of documents in the database using the daeDatabase object.

Querying Documents

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

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

The following function removes a document from the runtime database. Removing a document removes the root element and subsequently the entire element heirarchy from the database:

  • daeDatabase::removeDocument

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. 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. To create and use the default database and backend, call

collada_dom->setDatabase(NULL);
collada_DOM->setIOPlugin(NULL);

Each document in the COLLADA DOM requres a domCOLLADA element as the root element for the document. These functions create a domCOLLADA root element automatically:

  • daeDatabase::insertDocument(daeString, daeDocument**)
  • daeDatabase::createDocument(daeString, daeDocument**)

These functions allow you to pass in an existing domCOLLADA element to be used for the document root:

  • daeDatabase::insertDocument(daeString, daeElement*, daeDocument**)
  • daeDatabase::createDocument(daeString, daeElement*, daeDocument**)

These functions create a daeDocument and insert it into the database. The document created is returned in the last argument:

  • daeDatabase::insertDocument(daeString, daeDocument**)
  • daeDatabase::insertDocument(daeString, daeElement*, daeDocument**)

The daeDatabase::createDocument functions allow you to create a new COLLADA document without inserting it into the database. You can later call daeDatabase::insertDocument( daeDocument *c ) to insert the document into the database.

Template:DOM tutorial