DOM meta system

Summary: The COLLADA DOM meta system is a series of classes that make up the reflective object system. This system is used to provide the type information for all COLLADA elements in the COLLADA DOM.

Purpose

((ANDY: Details about why this system exists, why it is what/where it is, how it helps the user/developer.)) ((ELLEN: This system is the core of the COLLADA DOM. It is the whole ROS mentioned later in the user guide sections. It doesn't help the developer at all. 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 model

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 IO plugin ((ANDY: where does the plug-in come from?/where to find it?) (ELLEN: its part of the DOM. Its there when you download the DOM. Its not quite like a plugin in the "Maya plugin" sense)) access an element’s data.

daeMetaElement and daeMetaAttribute

daeMetaElement is the main class for an element’s type description. It stores:

• daeMetaAttribute objects ((ANDY: is "object" correct here?) (ELLEN: Objects are instances of a class. Thats basic object oriented programming. Do you think its not clear enough for people who would be readingi this article? I expect advanced users to be the only people who care to read this ) and their variations ((ANDY: more later)(ELLEN:These variations are described 5 "paragraphs" below this), 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. ((ANDY: I'm not following why this is different from the next array; the order is 1, 2, 3, and the ordinal values would be 1,2,3--obviously a subtlety or coding convention that I'm not catching.) (ELLEN: This _contents array stores the elements, ie <triangles>, <polylist> (but as the DOM types domTriangles, etc. The next array stores an int value associated with the element. This int is used when adding new elements to maintain valid ordering according to the COLLADA schema)

Accompanying the _contents array is a parallel array _contentsOrder which stores ordinal values associated with the children. The base ordinal values for each child are 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.

The subclasses are named after the schema content model type that they are modeled after. i.e. daeMetaSequence represents an xs:sequence group.

daeMetaGroup is slightly special since it contains a daeMetaElementAttribute that represents the group daeElement 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 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 type descriptions. ((ANDY, sorry, I don't know what a particle type is?)(ELLEN: Good point I don't think many people would get it. In XML a particle is a piece of data, ie an array 1 2 3 is 3 particles. ))

The code generator can generate new types. They are registered in the registerDomTypes function in domTypes.cpp.

The process is straight forward. For each new type defined in the schema, the function first searches for the type that the new type is derived from. If it finds the a descriptor for the base type, it will add the new type's name to the binding list. If the base type is not found, then a new rawRef type is created(I don’t think this every actually happens).

Enum types always generate a new type. The enum type also stores parallel arrays for the values and their string equivalents. ((ANDY: Are the values sometimes not sequential? e.g., I'd assume that an enum of "A", "B", "C" would have values of 1,2,3 (or 0, 1, 2); why is separate value needed?)(ELLEN: Yes they are not always sequential.)

The daeResolverType represents types of daeURI. The memoryToString and stringToMemory functions currently are where special characters are handled. Memory to string is also where there is logic to output only URI fragments instead of full URIs for same document references.