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

From COLLADA Public Wiki
Jump to navigation Jump to search
(editing)
(rm catg from talk pg)
 
(9 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++ COLLADA elements handed to the cache by the [[COLLADA backend]].
+
'''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.'''
  
==Querying Database Elements==
 
The current version of the [[COLLADA DOM]] provides two methods to query the database to get
 
information about specific elements:
 
*'''daeDatabase::getElementCount()'''
 
*'''daeDatabase::getElement()'''
 
  
===getElementCount===
+
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.
'''getElementCount()''' returns the number of elements for a particular query. For example, the 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.
 
 
 
===getElement===
 
'''getElement()''' requests that the database return a specific element. For example, the
 
following code returns an '''<image>''' element with an index that matches the value in el_number.
 
domImage *thisImage;
 
daeInt error = daeObject->getDatabase()->getElement((daeElement**)&thisImage, el_number, NULL, COLLADA_ELEMENT_IMAGE, NULL);
 
 
 
The element itself is returned in the first parameter. The third parameter restricts the query to a specific element by ID, and the fifth parameter restricts the search to a specific document.
 
 
 
===Technique for querying elements===
 
Typically, '''getElementCount()''' and '''getElement()''' are used as a pair, first getting the number of elements that match a particular ID, type, or document query, and then iterating through those by 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);
 
for (unsigned int i=0; i<imageCount; i++)
 
{
 
    error = daeObject->getDatabase()->getElement((daeElement**)&thisImage, i, NULL, COLLADA_ELEMENT_IMAGE, NULL);
 
/* take action on this image */
 
}
 
 
 
As another example, 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==
 
==Querying Documents==
Line 69: Line 33:
 
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.
 
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|Runtime database]]
+
{{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