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

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, 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 daeDatabase::getDocumentCount, daeDatabase::getDocument, and daeDatabase::isDocumentLoaded allow you to query for and iterate over documents in the runtime database.

daeDatabase::removeDocument 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->setIOPlugin(NULL);

Each document in the COLLADA DOM requres a domCOLLADA element as the root element for the document. daeDatabase::insertDocument(daeString, daeDocument**) and daeDatabase::createDocument(daeString, daeDocument**) will create a domCOLLADA root element automatically.

daeDatabase::insertDocument(daeString, daeElement*, daeDocument**) and daeDatabase::createDocument(daeString, daeElement*, daeDocument**) allow you to pass in an existing domCOLLADA element to be used for the document root.

daeDatabase::insertDocument(daeString, daeDocument**) and daeDatabase::insertDocument(daeString, daeElement*, daeDocument**) will create a daeDocument and insert it into the database. The document created will be returned in the last argument.

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.