Difference between revisions of "DOM load and save flow"

From COLLADA Public Wiki
Jump to navigation Jump to search
(more editing and some questions)
(minor text tweaks)
Line 6: Line 6:
  
 
The '''libxml''' I/O plug-in contains the following functions used while reading:
 
The '''libxml''' I/O plug-in contains the following functions used while reading:
* '''read''' calls a recursive function that reads the XML element hierarchy using libxml’s [http://en.wikipedia.org/wiki/Simple_API_for_XML SAX] parsing functionality.
+
* '''read''' calls a recursive function that reads the XML element hierarchy using '''libxml'''’s [http://en.wikipedia.org/wiki/Simple_API_for_XML SAX] parsing functionality.
 
*''' nextElement''' calls the appropriate functions based on the XML SAX type currently being parsed, that is, an attribute, a value, or a new element.
 
*''' nextElement''' calls the appropriate functions based on the XML SAX type currently being parsed, that is, an attribute, a value, or a new element.
*'''readAttributes''' handles the white space delimiting of array values. It then calls setAttribute on the current element. (See [[DOM meta system]] for information on what this does.) This has a nasty, but purposely designed this way, side effect that if the element is an array type, the particle is appended to the attribute type list and is not actually “set”.
+
*'''readAttributes''' handles the white space delimiting of array values. It then calls the current element's '''setAttribute''' function. (See [[DOM meta system]] for information on what this does.) This has a nasty, but purposely designed, side effect that if the element is an array type, the particle is appended to the attribute type list and is not actually “set”.
* '''readValue''' does the same as readAttributes except it doesn’t call setAttribute on the element but instead uses the meta value attribute (more in [[DOM meta system]]) to set the data.
+
* '''readValue''' does the same as '''readAttributes''' except it doesn’t call '''setAttribute''' on the element but instead uses the meta value attribute (more in [[DOM meta system]]) to set the data.
  
 
After the libxml plug-in reads and converts all of the XML document, it does the following:
 
After the libxml plug-in reads and converts all of the XML document, it does the following:
Line 22: Line 22:
 
DAE save just checks whether the I/O plug-in and database exist, creating them if they don’t. (If there is no database, then save will most certainly fail, but it creates it anyway.) Then it calls '''write''' in the I/O plug-in.
 
DAE save just checks whether the I/O plug-in and database exist, creating them if they don’t. (If there is no database, then save will most certainly fail, but it creates it anyway.) Then it calls '''write''' in the I/O plug-in.
  
The '''libxml''' plug-in does the following while writing:
+
The '''libxml''' I/O plug-in does the following while writing:
* uses '''libxml2'''’s SAX writer to write out the COLLADA document.
+
* Uses '''libxml2'''’s SAX writer to write out the COLLADA document.
*Calls a recursive '''write''' function that writes each element and its child subtree. ''((ANDY, not clear on whether this & preceding bullet are the same thing?  Also, where does '''writeElement''' fall in this list?))''
+
* Calls a recursive '''write''' function that writes each element and its child subtree. ''((ANDY, not clear on whether this & preceding bullet are the same thing?  Also, where does '''writeElement''' fall in this list?))''
 
* Does some special-case handling if you have the option set to save the float data as a [[.raw file]]. ''((more on this later))''
 
* Does some special-case handling if you have the option set to save the float data as a [[.raw file]]. ''((more on this later))''
*If an element’s meta type is not flagged transparent then a new XML tag is created and the attributes are written ''((using '''writeAttribute'''?))''. (See [[DOM COLLADA code generator]] for rules on what is marked transparent.)
+
* If an element’s meta type is not flagged transparent then a new XML tag is created and the attributes are written ''((using '''writeAttribute'''?))''. (See [[DOM COLLADA code generator]] for rules on what is marked transparent.)
 
* '''writeAttribute''' does some processing to check whether an attribute should be written:
 
* '''writeAttribute''' does some processing to check whether an attribute should be written:
** It does some special case handling so string types aren’t bound by the same size constraints that other types are.
+
** Does some special case handling so string types aren’t bound by the same size constraints that other types are.
 
**Attributes that are required are always written. An element’s value is an attribute that is always considered required.
 
**Attributes that are required are always written. An element’s value is an attribute that is always considered required.
 
**If the attribute is not required, it checks whether it was set. If not, then it is not written.
 
**If the attribute is not required, it checks whether it was set. If not, then it is not written.

Revision as of 23:21, 21 March 2007

Summary: This article describes the internal loading and saving flow of the COLLADA DOM.

Loading

Calling load on the DAE object just checks whether an I/O plug-in and database exist, creating default ones if they don’t, then calls read in the I/O plug-in.

The libxml I/O plug-in contains the following functions used while reading:

  • read calls a recursive function that reads the XML element hierarchy using libxml’s SAX parsing functionality.
  • nextElement calls the appropriate functions based on the XML SAX type currently being parsed, that is, an attribute, a value, or a new element.
  • readAttributes handles the white space delimiting of array values. It then calls the current element's setAttribute function. (See DOM meta system for information on what this does.) This has a nasty, but purposely designed, side effect that if the element is an array type, the particle is appended to the attribute type list and is not actually “set”.
  • readValue does the same as readAttributes except it doesn’t call setAttribute on the element but instead uses the meta value attribute (more in DOM meta system) to set the data.

After the libxml plug-in reads and converts all of the XML document, it does the following:

  1. Creates a daeDocument with the root being the root that was created on parse.
  2. Creates all of the integration objects if they are used.
  3. Resolves all elements that require resolution (more in DOM meta system).
  4. Calls the integration object conversion functions.

Saving

DAE save just checks whether the I/O plug-in and database exist, creating them if they don’t. (If there is no database, then save will most certainly fail, but it creates it anyway.) Then it calls write in the I/O plug-in.

The libxml I/O plug-in does the following while writing:

  • Uses libxml2’s SAX writer to write out the COLLADA document.
  • Calls a recursive write function that writes each element and its child subtree. ((ANDY, not clear on whether this & preceding bullet are the same thing? Also, where does writeElement fall in this list?))
  • Does some special-case handling if you have the option set to save the float data as a .raw file. ((more on this later))
  • If an element’s meta type is not flagged transparent then a new XML tag is created and the attributes are written ((using writeAttribute?)). (See DOM COLLADA code generator for rules on what is marked transparent.)
  • writeAttribute does some processing to check whether an attribute should be written:
    • Does some special case handling so string types aren’t bound by the same size constraints that other types are.
    • Attributes that are required are always written. An element’s value is an attribute that is always considered required.
    • If the attribute is not required, it checks whether it was set. If not, then it is not written.
    • If the attribute is set then it is compared to the default value, if one was specified. If the attribute is the same as the default then it ignored. This always fails for array types (I think).

See also