Making Data Available using the WaitXUpdateAll() Methods

Generator nodes can be generating new data all the time. Meanwhile, however, an application typically needs to be using one consistent data set (data frame and associated data) all received at any one time, until it has completed processing the frame. For this reason, an OpenNI generator holds its new data internally only, until the application explicitly asks the generator to update its data to the new data. This request is done by an 'Update Data' command. OpenNI API provides the xn::Generator::WaitAndUpdateData() method to let the application wait for the generator to have generated new data. This method causes it to be 'updated', which means that it copies it to the node's application buffer.

In some cases, the production graph comprises of more than one node, and the application will usually want all the nodes to be updated at once. OpenNI supplies a family of methods – called the WaitXUpdateAll() methods – to update the nodes all at once, depending on which approach the application wants to use to update the nodes. For a summary of the WaitXUpdateAll methods, see 'Wait and Update' Methods below.

Unless needing to update only a specific node, it is highly advised to use one of the 'Update All' functions. In addition, for updating all the nodes these 'Update All' functions have some further benefits:

• If nodes are dependent on each other, it promises that the needed node will be updated before the needing node.

• If playing a recording, it reads data from the recording until the condition is met.

• If a recorder exists, it records the data from all nodes added to it (without the need to call xn::Recorder::Record()).

'Wait and Update' Methods

The 'WaitXandUpdateAll' methods are a family of methods of the Context class that act on the entire production graph, i.e., they act on each and every one of the generator nodes in the context. Calling a 'WaitXandUpdateAll' method 'updates' the nodes, that is, the method ensures that the accessible data from each and every node is the node's most recently generated data.

Each of the 'WaitXandUpdateAll' methods performs a different type of 'wait' prior to performing the 'update' – see below for separate descriptions of each of these methods.

• xnWaitAndUpdateAll() (xn::Context::WaitAndUpdateAll()) - Updates all generator nodes in the context, first waiting for each node to have new data available.

• xnWaitAnyUpdateAll() (xn::Context::WaitAnyUpdateAll()) - Waits for any node to have new data. Once new data is available from any node, all nodes are updated.

• xnWaitOneUpdateAll() (xn::Context::WaitOneUpdateAll()) - Waits for a specific node to have new data. Once new data is available from this node, all nodes are updated. This is especially useful when having several nodes producing data, but only one determines the progress of the application.

• xnWaitNoneUpdateAll() (xn::Context::WaitNoneUpdateAll()) - Does not wait for anything. All nodes are updated.

There is also a WaitAndUpdateData() method that is a member of a specific node. This is a member of the xn::Generator class. The difference between them is that the 'WaitXAndUpdateData' methods update the application buffers of all the nodes in the entire context all at once, specifying which type of wait to perform first. In contrast, the xn::Generator::WaitAndUpdateData() method waits only on the specified node and then updates its application buffer.

In Depth

It is understood from the above that even when nodes are generating data, the application cannot get any of their new data until it calls one of these 'wait and update' methods. Typically, a call to one of these methods will be placed in the main program loop.

Note that these methods are not one-off calls for setting a mode for all future updates. As already mentioned, one of these methods must be called each time the application wishes to cause new generated data to be output.

These methods exit after a timeout of two seconds.

The nodes output their next new generated data items in their order of dependencies, i.e., these methods guarantee that the 'server' node (the lower-level node generating the data for another node) is updated before the 'client' node.

When Player playing data from a recording, depending on the mode, these methods read data from the recreated nodes exactly as for live nodes.

If a recorder exists, these methods automatically record the data from all nodes added to this recorder.

Sample Code

Here is an example of updating data and getting data. This particular example uses a node with an associated frame object". The frame object is contained in a @ref conc_meta_data "metadata" object.

After calling an 'Update Data' method (in this example, the node's WaitAndUpdateData() method), the application must call the node's GetMetaData() method to get the node's latest generated frame object and save it as metadata.

The node's GetMetaData() method gets the node's frame object that is. An example of a metadata object is xn::DepthMetaData, which is the metadata object for a DepthGenerator node.

Code example:

    DepthGenerator depth;
    depth.StartGenerating();

    DepthMetaData depthMD;
    while forever
    { 
        depth.WaitAndUpdateData();  
        depth.GetMetaData(depthMD); 
        
        XnUInt32 xRes = depthMD.XRes();
        const XnDepthPixel* pDepthMap = depthMD.Data();
    }

Note that for each 'Update Data' call (e.g., xn::Generator::WaitAndUpdateData() above) the application must then again get the new data (using the node's GetMetaData() method). This is true also when accessing the data through metadata. That is, the metadata is not permanently attached to the node's new output.

In some cases, the production graph comprises of more than one node, and the application will usually want all the nodes to be updated at once. OpenNI supplies a family of methods &nbsp called the WaitXUpdateAll() methods &nbsp to update the nodes all at once. For more information on the WaitXUpdateAll() methods see Making Data Available using the WaitXUpdateAll() Methods.