OpenNI 1.5.7
Public Member Functions | List of all members

#include <XnCppWrapper.h>

Inheritance diagram for xn::Generator:
Inheritance graph
[legend]

Public Member Functions

 Generator (XnNodeHandle hNode=NULL)
 
 Generator (const NodeWrapper &other)
 
XnStatus StartGenerating ()
 
XnBool IsGenerating () const
 
XnStatus StopGenerating ()
 
XnStatus RegisterToGenerationRunningChange (StateChangedHandler handler, void *pCookie, XnCallbackHandle &hCallback)
 
void UnregisterFromGenerationRunningChange (XnCallbackHandle hCallback)
 
XnStatus RegisterToNewDataAvailable (StateChangedHandler handler, void *pCookie, XnCallbackHandle &hCallback)
 
void UnregisterFromNewDataAvailable (XnCallbackHandle hCallback)
 
XnBool IsNewDataAvailable (XnUInt64 *pnTimestamp=NULL) const
 
XnStatus WaitAndUpdateData ()
 
XnBool IsDataNew () const
 
const void * GetData ()
 
XnUInt32 GetDataSize () const
 
XnUInt64 GetTimestamp () const
 
XnUInt32 GetFrameID () const
 
const MirrorCapability GetMirrorCap () const
 
MirrorCapability GetMirrorCap ()
 
const
AlternativeViewPointCapability 
GetAlternativeViewPointCap () const
 
AlternativeViewPointCapability GetAlternativeViewPointCap ()
 
const FrameSyncCapability GetFrameSyncCap () const
 
FrameSyncCapability GetFrameSyncCap ()
 
- Public Member Functions inherited from xn::ProductionNode
 ProductionNode (XnNodeHandle hNode=NULL)
 
 ProductionNode (const NodeWrapper &other)
 
NodeInfo GetInfo () const
 
XnStatus AddNeededNode (ProductionNode &needed)
 
XnStatus RemoveNeededNode (ProductionNode &needed)
 
void GetContext (Context &context) const
 
Context GetContext () const
 
XnBool IsCapabilitySupported (const XnChar *strCapabilityName) const
 
XnStatus SetIntProperty (const XnChar *strName, XnUInt64 nValue)
 
XnStatus SetRealProperty (const XnChar *strName, XnDouble dValue)
 
XnStatus SetStringProperty (const XnChar *strName, const XnChar *strValue)
 
XnStatus SetGeneralProperty (const XnChar *strName, XnUInt32 nBufferSize, const void *pBuffer)
 
XnStatus GetIntProperty (const XnChar *strName, XnUInt64 &nValue) const
 
XnStatus GetRealProperty (const XnChar *strName, XnDouble &dValue) const
 
XnStatus GetStringProperty (const XnChar *strName, XnChar *csValue, XnUInt32 nBufSize) const
 
XnStatus GetGeneralProperty (const XnChar *strName, XnUInt32 nBufferSize, void *pBuffer) const
 
XnStatus LockForChanges (XnLockHandle *phLock)
 
void UnlockForChanges (XnLockHandle hLock)
 
XnStatus LockedNodeStartChanges (XnLockHandle hLock)
 
void LockedNodeEndChanges (XnLockHandle hLock)
 
const ErrorStateCapability GetErrorStateCap () const
 
ErrorStateCapability GetErrorStateCap ()
 
GeneralIntCapability GetGeneralIntCap (const XnChar *strCapability)
 
- Public Member Functions inherited from xn::NodeWrapper
 NodeWrapper (XnNodeHandle hNode)
 
 NodeWrapper (const NodeWrapper &other)
 
NodeWrapperoperator= (const NodeWrapper &other)
 
 ~NodeWrapper ()
 
 operator XnNodeHandle () const
 
XnNodeHandle GetHandle () const
 
XnBool operator== (const NodeWrapper &other)
 
XnBool operator!= (const NodeWrapper &other)
 
XnBool IsValid () const
 
const XnChar * GetName () const
 
XnStatus AddRef ()
 
void Release ()
 
void SetHandle (XnNodeHandle hNode)
 
void TakeOwnership (XnNodeHandle hNode)
 

Detailed Description

Purpose: A generator node produces some type of data. This is in addition to the node's basic characteristic, as a derivative of the xn::ProductionNode class, i.e., that it represents a logical entity in the OpenNI ProductionGraph".

Usage summary: Immediate base class for all generator types. It itself is not usually instantiated.

Class Overview:

Each generator can be in Generating state or Non-Generating state. The application makes the node enter Generating state by calling the xn::Generator::StartGenerating() method.

When a generator node is created, by default it is in Non-Generating state, so it does not generate data.

Generators have a default configuration (for example the FOV resolution) and an application can change the default configuration before actual data generation starts.

Once the application has completed configuring the generator node, the application can cause the node to start generating data.

Typically, the application will configure the generator only in the configuration stage, i.e., in Non-Generating state. The application can usually also configure the node while generating data, however configuration might then take longer and the application could also lose some frames of data. For example, if the application changes the resolution while in the Configuration stage (Non-Generating state), the resolution change occurs immediately; but if the application changes the configuration while the generator is generating data, the resolution change can take up to a few seconds to occur.

Data Storage:

Each call to an 'Update Data' method updates the generator node's application buffer, making the latest data available for applications to access. After a call to an 'Update Data' method, all subsequent calls to GetData() will return exactly the same data until you call 'Update Data' again. The 'Update Data' method can be the generator node's own WaitAndUpdateData() method or one of the Context's 'WaitXUpdateAll' methods.

Getting the Generated Data:

Generator nodes will not output data to make it available for getting, until the application calls the node's WaitAndUpdateData() method (see below) or one of the context's 'WaitXUpdateAll' methods.

Sample Code

Constructor & Destructor Documentation

xn::Generator::Generator ( XnNodeHandle  hNode = NULL)
inline

Ctor

Parameters
[in]hNodeNode handle
xn::Generator::Generator ( const NodeWrapper other)
inline

Member Function Documentation

const AlternativeViewPointCapability xn::Generator::GetAlternativeViewPointCap ( ) const
inline

Gets an AlternativeViewPointCapability object for accessing Alternative Viewpoint functionality.

Remarks:

It is the application's responsibility to check first if XN_CAPABILITY_ALTERNATIVE_VIEW_POINT is supported by calling xn::Generator::IsCapabilitySupported().

AlternativeViewPointCapability xn::Generator::GetAlternativeViewPointCap ( )
inline

Gets an AlternativeViewPointCapability object for accessing Alternative Viewpoint functionality.

Remarks:

It is the application's responsibility to check first if XN_CAPABILITY_ALTERNATIVE_VIEW_POINT is supported by calling xn::Generator::IsCapabilitySupported().

const void* xn::Generator::GetData ( )
inline

Gets the frame data from the generator node. This is the latest data that the generator node has generated.

Remarks:

This method gets the data directly from the Generator node; not from the metadata object.

Compare this method with the Data() method of the xn::OutputMetaData object, where the latter gets the data from the metadata object. GetData() returns the same data as the GetMetaData().Data() method. However, using the GetData() method is slightly more costly.

The application usually should not use this method, but call each generator own data access methods, e.g. DepthGenerator::GetDepthMap().

XnUInt32 xn::Generator::GetDataSize ( ) const
inline

Gets the data size of the frame data. This method gets the data size directly from the Generator node.

Remarks:

The size of the data is returned as a number of bytes.

Compare this method with the DataSize() method of the xn::OutputMetaData object, where the latter gets the data from the metadata object. GetDataSize() returns the same data as the GetMetaData().DataSize() method. However, using the GetDataSize() method is slightly more costly.

XnUInt32 xn::Generator::GetFrameID ( ) const
inline

Gets the frame ID of the current frame data from the Generator node.

Remarks:

This method gets the frame ID directly from the Generator node.

Compare this method with the GetFrameID() method of the xn::OutputMetaData object, where the latter gets the data from the metadata object. GetFrameID() returns the same data as the GetMetaData().GetFrameID() method. However, using the GetFrameID() method is slightly more costly.

const FrameSyncCapability xn::Generator::GetFrameSyncCap ( ) const
inline

Gets an FrameSyncCapability object for accessing Frame Sync functionality.

Remarks:

It is the application's responsibility to check first if XN_CAPABILITY_FRAME_SYNC is supported by calling xn::Generator::IsCapabilitySupported().

FrameSyncCapability xn::Generator::GetFrameSyncCap ( )
inline

Gets an FrameSyncCapability object for accessing Frame Sync functionality.

Remarks:

It is the application's responsibility to check first if XN_CAPABILITY_FRAME_SYNC is supported by calling xn::Generator::IsCapabilitySupported().

const MirrorCapability xn::Generator::GetMirrorCap ( ) const
inline

Gets a MirrorCapability object for accessing Mirror functionality.

Remarks:

It is the application's responsibility to check first if XN_CAPABILITY_MIRROR is supported by calling xn::ProductionNode::IsCapabilitySupported().

MirrorCapability xn::Generator::GetMirrorCap ( )
inline

Gets a MirrorCapability object for accessing Mirror functionality.

Remarks:

It is the application's responsibility to check first if XN_CAPABILITY_MIRROR is supported by calling xn::ProductionNode::IsCapabilitySupported().

XnUInt64 xn::Generator::GetTimestamp ( ) const
inline

Gets the frame timestamp from the Generator node This method gets the timestamp directly from the Generator node.

Remarks:

The time is returned in microseconds.

Compare this method with the GetTimestamp() method of the xn::OutputMetaData object, where the latter gets the data from the metadata object. GetTimestamp() returns the same data as the GetMetaData().GetTimestamp() method. However, using the GetTimestamp() method is slightly more costly.

XnBool xn::Generator::IsDataNew ( ) const
inline

Returns whether this node's frame data was updated by the most recent call to any 'WaitXUpdateAll()' function, e.g., xn::Context::WaitAnyUpdateAll().

XnBool xn::Generator::IsGenerating ( ) const
inline

Returns whether the node is currently in Generating state.

XnBool xn::Generator::IsNewDataAvailable ( XnUInt64 *  pnTimestamp = NULL) const
inline

Returns whether the node has new data available. The new data is available for updating, but can not yet be accessed by the application. The application needs to call 'Update Data' to gain access to that new data.

Parameters
[out]pnTimestamp[Optional] If new data is available (TRUE is returned from the method), this param will hold the timestamp of that new data.
XnStatus xn::Generator::RegisterToGenerationRunningChange ( StateChangedHandler  handler,
void *  pCookie,
XnCallbackHandle hCallback 
)
inline

Registers an event handler for the 'Generation State Change' event.

Registers a callback function to be called when generation starts or stops, i.e., when the generation state toggles between generating and not generating.

Parameters
[in]handlerCallback function to be invoked when the event is raised.
[in]pCookieUser's cookie, to be delivered to the callback.
[out]hCallbackHandle to the callback to be used for unregistering it.

For full details and usage of the parameters, see Registering to Events.

XnStatus xn::Generator::RegisterToNewDataAvailable ( StateChangedHandler  handler,
void *  pCookie,
XnCallbackHandle hCallback 
)
inline

Registers an event handler for the 'New Data Available' event.

The 'New Data Available' event is raised whenever a generator node has new data available. The new data is available for updating, but can not yet be accessed by the application. The application needs to call 'Update Data' to gain access to that new data.

Parameters
[in]handlerCallback function to be invoked when the event is raised.
[in]pCookieUser's cookie, to be delivered to the callback.
[out]hCallbackHandle to the callback to be used for unregistering it.

For full details and usage of the parameters, see Registering to Events.

XnStatus xn::Generator::StartGenerating ( )
inline

Enters the node into Generating state.

Enters the node into Generating state. In this state the node generates new frames.

After the application has called this method it can call an 'Update Data' method, e.g., xn::Generator::WaitAndUpdateData(), to make a new frame available for getting. The application can then get the data (for example, using a metadata GetData() method, or some other mechanism depending on the type of node).

Remarks:

On entering the node into Generating state, OpenNI enters also all dependent nodes into Generating state. For example, if a UserGenerator node depends on data input from a DepthGenerator node, and the UserGenerator node is entered into Generating state, then OpenNI will enter also the DepthGenerator node into Generating state.

XnStatus xn::Generator::StopGenerating ( )
inline

Makes the node leave Generating state (enters Non-Generating state).

Remarks:

If the node has metadata, after calling this method the data is still available as a saved frame object in the metadata object.

void xn::Generator::UnregisterFromGenerationRunningChange ( XnCallbackHandle  hCallback)
inline

Unregisters the 'Generation State Change' event handler.

Parameters
[in]hCallbackHandle received from registration.

For full details and usage of the parameter, see Unregistering from Events .

void xn::Generator::UnregisterFromNewDataAvailable ( XnCallbackHandle  hCallback)
inline

Unregisters the event handler for the 'New Data Available' event.

Parameters
[in]hCallbackHandle received from registration.

For full details and usage of the parameter, see Unregistering from Events .

XnStatus xn::Generator::WaitAndUpdateData ( )
inline

Updates the generator node to the latest available data, first waiting for the node to have new data available.

Remarks:

This method requests from OpenNI to cause the node to update its application buffers with new data, if it has new data available.

At this stage the generator node has "generated" new data. This method returns a success status. The application can now read the newly generated data.

An error situation is defined as: after a preset timeout, the node has not yet notified OpenNI it has new data available. On error, the method stops waiting and returns an error status.

Return values
XN_STATUS_INVALID_OPERATIONThis production node is not a generator.
XN_STATUS_WAIT_DATA_TIMEOUTNo new data available within 2 seconds.

The documentation for this class was generated from the following file: