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

From COLLADA Public Wiki
Jump to navigation Jump to search
(→‎Creating New Documents: catg sort & some fmtting)
(editing)
Line 1: Line 1:
The Runtime Database is a resident, active cache of COLLADA elements. This cache is based on C++
+
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]].
COLLADA elements handed to the cache by the COLLADA Backend.
 
  
==Querying the Database==
+
==Querying Database Elements==
===Querying Elements===
+
The current version of the [[COLLADA DOM]] provides two methods to query the database to get
The current version of the COLLADA DOM provides two methods to query the database to get
+
information about specific elements:
information about specific elements, daeDatabase::getElementCount() and
+
*'''daeDatabase::getElementCount()'''
daeDatabase::getElement().
+
*'''daeDatabase::getElement()'''
  
The method getElementCount() returns the number of elements for a particular query. For example, the
+
===getElementCount===
following code asks how many <image> elements are in the database:
+
'''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);
 
  imageCount = daeObject->getDatabase()->getElementCount(NULL, COLLADA_ELEMENT_IMAGE, NULL);
The additional parameters to getElementCount() make the request more specific. The first parameter
+
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.
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
+
===getElement===
following code returns an image element with an index that matches the value in el_number.
+
'''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;
 
  domImage *thisImage;
 
  daeInt error = daeObject->getDatabase()->getElement((daeElement**)&thisImage, el_number, NULL, COLLADA_ELEMENT_IMAGE, NULL);
 
  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
+
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.
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
+
===Technique for querying elements===
database, you could do the following:
+
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);
 
  imageCount = daeObject->getDatabase()->getElementCount(NULL, COLLADA_ELEMENT_IMAGE, NULL);
Line 34: Line 30:
 
  }
 
  }
  
As another example, if you want to take action on all images with the name “landImage”, you could do
+
As another example, to take action on all images with the name “landImage”, you could do the following:
the following:
 
 
  imageCount = daeObject->getDatabase()->getElementCount("landImage", COLLADA_ELEMENT_IMAGE, NULL);
 
  imageCount = daeObject->getDatabase()->getElementCount("landImage", COLLADA_ELEMENT_IMAGE, NULL);
 
  for (unsigned int i=0; i<imageCount; i++)
 
  for (unsigned int i=0; i<imageCount; i++)
Line 43: Line 38:
 
  }
 
  }
  
The index passed to getElement() is not directly associated with the element within the database. The
+
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.
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==
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.
+
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>  
  
<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.
+
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:
 +
* <code>daeDatabase::removeDocument</code>
  
 
==Creating New Documents==
 
==Creating New Documents==
You can use the COLLADA DOM to create a set of elements, add them to an empty database, and write
+
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
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. '''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.
+
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**)'''
  
'''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.
+
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.
 
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]]
 
[[Category:DOM project|Runtime database]]

Revision as of 17:51, 30 March 2007

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.