Talk:DOM guide: Working with documents/old version

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.

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

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

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.