Frame Objects and Metadata Objects

The metadata classes provide frame objects to corresponding generator nodes to provide fast data access. For example, a DepthMetaData object provides a frame object for a DepthGenerator node. Many types of generator nodes are provided with frame objects (e.g., DepthGenerator and ImageGenerator), but not all types of generator nodes (e.g., xn::HandsGenerator).

In addition, the frame objects are used to freeze the configuration of a node at the time this data arrived. Sometimes an application changes the configuration of a node while reading data from it. In such a case, and until new data arrives, the data received from this node was produced using a different configuration. For example, lets say a DepthGenerator node was configured to produce QVGA depth maps, and the application constantly reads data from it. At some point, the application changes the node output mode to VGA. Until the moment a new frame arrives, calling xn::DepthGenerator::GetDepthMap() would return a QVGA map, but calling xn::DepthGenerator::GetMapOutputMode() would return VGA resolution. This might cause errors (or even an access violation) in the application.

To solve this, each node has a frame object, keeping the properties of the data when it was read. So, in the above case, by calling xn::DepthGenerator::GetMetaData() you would get a xn::DepthMetaData object. This object Data() method would return a pointer to the QVGA depth map, and the XRes() and YRes() functions would return QVGA resolution.

Metadata objects hold const pointers to the data (since this is what is returned from the generators). C++ metadata objects (all objects inheriting from xn::OutputMetaData) also provide a way to replace the data buffer with a self-allocated buffer, which can also be written to. Use the AllocateData() function for allocating a clean buffer, or the MakeDataWritable() function for also copying data from the buffer into the newly allocated writable buffer.

Also, the metadata objects support several types of copying:

• All InitFrom functions actually perform the shallow copy made by C functions (xnCopyDepthMetaData() for example).
• All CopyFrom functions allocates a new buffer and copies data to it (so that destination object now points to a private copy of the data of the source object).

Currently this creates a situation in which the functionality supplied by C and C++ interfaces is not the same. This is planned to be fixed in future versions.