DOM meta system
This system is the core of the COLLADA DOM. It is the whole Reflective Object System. No developers really need to deal with these objects directly. These objects exist under the hood to allow the DOM to do what the DOM does.
How it works
daeElement has a nonstatic pointer to its type information:
Each strongly typed class inherits from
daeElement and has a static pointer to the type information:
Each element can have its own element name. If
getElementName returns NULL then the element’s name is the same as its type name (its
daeMetaElement’s name ).
Reflective Object System
daeElement class is the base class for the following:
- all strongly typed elements and
xs:groupelements. It has storage for very little data; instead, the strongly typed subclasses provide storage for the data that is needed.
- reference counted objects. INTERNAL NOTE: This should be changed, however; see DOM future work#Class hierarchy reorganization.
The meta system allows access to a strongly typed subclass’s data given a
daeElement base class object by storing pointer offsets from the
daeElement pointer to the data. This is how all of the “dae” library functions and the
libxml2 I/O plug-in access an element’s data.
<nowiki>Insert non-formatted text here</nowiki>
daeMetaElement and daeMetaAttribute
daeMetaElement is the main class for an element’s type description. It stores:
daeMetaAttributeobjects and their variations, for each attribute, value, element child, and some auxiliary data (like the
- a tree of
daeMetaCMPolicyobjects that dictate the behavior and ordering of an element’s children.
- the pointer offset to the data that it describes.
daeMetaAttribute, in turn, stores type information for the data that an element contains.
The value of an element is just a
daeMetaAttribute that is kept separately from the attribute list.
daeMetaAttribute is the base class for
daeMetaAttributeArray. These two classes represent single values and arrays of values respectively.
daeMetaElementArrayAttribute are types of
daeMetaAttributes where the value is another element instead of a data type. They also inherit from
daeMetaCMPolicy and are part of the content model tree.
getWritableMemory returns a raw (byte) pointer to the data. This pointer needs to be cast appropriately to be used.
Any type in the COLLADA schema that has URI data is marked as
_needsResolve in the code generator when generating the classes for the COLLADA DOM. The
metaAttributes for the data is stored in the
resolve on a
metaAttribute in turn calls
resolve on the atomic type for the data the attribute describes. Only
idresolver (uri and idref) types implement functionality for resolve.
daeMetaCMPolicy and its subclasses were added to control the ordering of children.
Elements that contain complex content models or content models with an <xs:choice> will have an array (
_contents) that stores the order of these children. Accompanying the
_contents array is a parallel
array _contentsOrder, which stores ordinal values associated with the children. The base ordinal value for each child is calculated during code generation. The actual ordinal value given to a child is calculated at runtime. Children with a higher ordinal value get placed after children with lower ordinal values.
placeElement, removeElement, findChild, and getChildren are all recursive functions where the behavior is defined by the subclasses, which are named after the schema content model type that they are modeled after. For example,
daeMetaSequence represents an <xs:sequence> group. Also note:
daeMetaGroupis slightly special because it contains a
daeMetaElementAttributethat represents the group
daeElementthat needs to be placed. It has placing logic to place the group element in the parent element but then defers the placing of the child to the group element.
daeMetaChoicerequires some additional per-object data. This data is stored as a char array in
daeElement. Each choice is numbered and the value in the array at the numbered index represents which “choice” has been chosen for its children. A -1 represents that no subtrees have been populated yet.
Particle type descriptions
daeAtomicType is the base class for all particle (XML) type descriptions.
The code generator can generate new types. They are registered in the
registerDomTypes function in
domTypes.cpp. The process is straightforward. For each new type defined in the schema, the function first searches for the type from which the new type is derived. If it finds a descriptor for the base type, it adds the new type's name to the binding list. If the base type is not found, then a new
rawRef type is created (Internal note: This might not ever actually happen).
- Enum types always generate a new type. The enum type also stores parallel arrays for the values (as the values are not guaranteed to be sequential) and their string equivalents.
daeResolverTyperepresents types of
stringToMemoryhandle special characters.
Memory to stringalso contains logic to output URI fragments instead of full URIs for same-document references.
|COLLADA DOM - Version 2.4 Historical Reference|
|List of main articles under the DOM portal.|
| User Guide chapters: • Intro • Architecture • Setting up • Working with documents • Creating docs • Importing docs • Representing elements • Working with elements • Resolving URIs • Resolving SIDs • Using custom COLLADA data • Integration templates • Error handling|
Systems: • URI resolver • Meta • Load/save flow • Runtime database • Memory • StringRef • Code generator