OpenNI 1.5.4
Implementing a Generator

If your node implementation is a generator type (i.e., it produces data), you can usually implement it in one of two ways:

Although these two models require different implementations, they both fit in OpenNI interfaces.

Note
Currently, OpenNI interfaces do not enable writing active generators, which require data from another generator.

When a generator has generated 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 update its Last Updated Data. This flow is explained in detail in the following sections.

The Generating State

A generator can be in one of two states: Generating state or Non-generating state. When the node is created, it is in Non-generating state. Non-generating state is useful for defining configuration before actually starting to generate new data.

A generator's state can be changed to Generating state 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 for raising the 'Generation Running Changed' event whenever its generating state has changed.

In essence, when in Generating state, the generator constantly generates new data (as defined and limited by the specifications of the physical hardware devices).

New Data

When a generator is in Generating state it generates "new" data, meaning new data that the application hasn't received yet. The generator does not simply make newly generated data available as 'new data' as soon as it has generated it. Each generator preserves the content of its application buffer and is not allowed to modify it until the app request new data. When new data is available:

When the application calls one of the 'Wait X Update All methods and is pending, OpenNI waits until any new data arrives, by waiting for the 'New Data Available' event to be raised by any generator. Once this event was raised, OpenNI checks if the requested 'wait' condition has now been achieved (either 'All', 'Any', 'One' or 'None' of the nodes has new data) by calling the xn::ModuleGenerator::IsNewDataAvailable() to check if a specific generator has new data.

Once condition is met, OpenNI updates all the generators by calling their xn::ModuleGenerator::UpdateData() method. The UpdateData() method is the only place where the node implementation is allowed to modify its last updated data.

Note
The generator never calls its UpdateData() method. Only OpenNI calls this method, when the application calls one of the 'Wait X Update All' methods.

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 minimize copying data from one buffer to another, in order to reduce consumption of 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: