OpenNI 1.5.2
Implemeting a Generator

If our node implementation is some sort of generator (i.e. produces data), it can be usually implemeted in one of two ways - an active generator (i.e. generates data in the background somehow) or a passive one (i.e. processes other nodes data in order to create new data). While those two models are different when implementing, they both fit in OpenNI interfaces.

When a generator has new data, it informs OpenNI by raising its New Data Available event. This will cause OpenNI to call its xn::ModuleGenerator::UpdateData() method in the application main-loop (assuming the application is using one of the WaitXUpdateAll methods. The UpdateData method is the only place where the node implementation is allowed to change its Last Updated Data. This flow is explained in details in the following sections.

The Generating State

A generator can be in one of two states: generating and non-generating. When the node is created, it is in the non-generating state. This state is useful for choosing configuration before actually starting to generate new data.

A generator's state can be changed to generating by calling its xn::ModuleGenerator::StartGenerating() method, and can be changed to non-generating by calling its xn::ModuleGenerator::StopGenerating() method. The generator is responsible to raise the "Generation Running Changed" event whenever its generating state is changed.

In essense, when in the generating state, the generator constantly generates new data (unless bounded by some input of course).

New Data

When a generator is in the generating state it generates "new" data, meaning, data that the application hasn't received yet. A generator does not simply replace its data when it can. Each generator is responsible of holding the last data that the application received, and not to modify it. Instead, when new data is available, the generator should raise its New Data Available event, as well as to return TRUE when its xn::ModuleGenerator::IsNewDataAvailable() method is called.

The event is used by OpenNI to check current state if the application called one of the WaitXUpdateAll methods. In those methods, OpenNI waits for some new data to arrive and then checks if the requested condition was completed. If so, it updates all the nodes which has new data. It uses the xn::ModuleGenerator::IsNewDataAvailable() method for checking if the node has new data, and the xn::ModuleGenerator::UpdateData() to make the node update its data. The UpdateData method is the only place where the node implementation is allowed to modify its last updated data.

Example A: An Active Generator

An active generator is a generator that does its generation in a thread other than the application thread.

Usually, its implementation will be as follows:

Of course, the explanation above is simplified. Usually, instead of allocating and deleting data buffers, a buffer pool is used, and the implementation should copy the data from one buffer to the other as little as possible, so that it wouldn't consume much hardware resources.

Example B: A Passive Generator

A passive generator usually depends on the data of another generator. It does some processing in the application thread to produce new data from its input node's data.

Usually, its implementation will be as follows: