DOM meta system
Summary: The COLLADA DOM meta system is a series of classes that make up the reflective object system. This system provides the type information for all COLLADA elements in the COLLADA DOM.
Purpose
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
Element descriptions
Each daeElement
has a nonstatic pointer to its type information: _meta
.
Each strongly typed class inherits from daeElement
and has a static pointer to the type information: _Meta
.
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
The daeElement
class is the base class for the following:
- all strongly typed elements and
xs:group
elements. 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:
daeMetaAttribute
objects and their variations, for each attribute, value, element child, and some auxiliary data (like the_contents
arrays).
- a tree of
daeMetaCMPolicy
objects 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.
daeMetaElementAttribute
and 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 _resolvers
array.
Calling resolve
on a metaAttribute
in turn calls resolve
on the atomic type for the data the attribute describes. Only resolver
and idresolver
(uri and idref) types implement functionality for resolve.
daeMetaCMPolicy
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:
daeMetaGroup
is slightly special because it contains adaeMetaElementAttribute
that represents the groupdaeElement
that 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.daeMetaChoice
requires some additional per-object data. This data is stored as a char array indaeElement
. 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).
Additional notes:
- 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.
daeResolverType
represents types ofdaeURI
.memoryToString
andstringToMemory
handle special characters.Memory to string
also 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 |