OpenNI 1.5.4: xn::Context Class Reference

OpenNI

#include <XnCppWrapper.h>

List of all members.

Classes

struct  NodeCreationCookie
struct  NodeDestructionCookie

Public Types

typedef void(* NodeCreationHandler )(Context &context, ProductionNode &createdNode, void *pCookie)
typedef void(* NodeDestructionHandler )(Context &context, const XnChar *strDestroyedNodeName, void *pCookie)

Public Member Functions

 Context ()
 Context (XnContext *pContext)
 Context (const Context &other)
 ~Context ()
Contextoperator= (const Context &other)
XnContextGetUnderlyingObject () const
XnBool operator== (const Context &other)
XnBool operator!= (const Context &other)
XnStatus Init ()
XnStatus RunXmlScript (const XnChar *strScript, ScriptNode &scriptNode, EnumerationErrors *pErrors=NULL)
XnStatus RunXmlScriptFromFile (const XnChar *strFileName, ScriptNode &scriptNode, EnumerationErrors *pErrors=NULL)
XnStatus InitFromXmlFile (const XnChar *strFileName, ScriptNode &scriptNode, EnumerationErrors *pErrors=NULL)
XnStatus OpenFileRecording (const XnChar *strFileName, ProductionNode &playerNode)
XnStatus CreateMockNode (XnProductionNodeType type, const XnChar *strName, ProductionNode &mockNode)
XnStatus CreateMockNodeBasedOn (ProductionNode &originalNode, const XnChar *strName, ProductionNode &mockNode)
XnStatus CreateCodec (XnCodecID codecID, ProductionNode &initializerNode, Codec &codec)
XnStatus AddRef ()
void Release ()
XnStatus AddLicense (const XnLicense &License)
XnStatus EnumerateLicenses (XnLicense *&aLicenses, XnUInt32 &nCount) const
XnStatus EnumerateProductionTrees (XnProductionNodeType Type, const Query *pQuery, NodeInfoList &TreesList, EnumerationErrors *pErrors=NULL) const
XnStatus CreateAnyProductionTree (XnProductionNodeType type, Query *pQuery, ProductionNode &node, EnumerationErrors *pErrors=NULL)
XnStatus CreateProductionTree (NodeInfo &Tree, ProductionNode &node)
XnStatus EnumerateExistingNodes (NodeInfoList &list) const
XnStatus EnumerateExistingNodes (NodeInfoList &list, XnProductionNodeType type) const
XnStatus FindExistingNode (XnProductionNodeType type, ProductionNode &node) const
XnStatus GetProductionNodeByName (const XnChar *strInstanceName, ProductionNode &node) const
XnStatus GetProductionNodeInfoByName (const XnChar *strInstanceName, NodeInfo &nodeInfo) const
XnStatus StartGeneratingAll ()
XnStatus StopGeneratingAll ()
XnStatus SetGlobalMirror (XnBool bMirror)
XnBool GetGlobalMirror ()
XnStatus GetGlobalErrorState ()
XnStatus RegisterToErrorStateChange (XnErrorStateChangedHandler handler, void *pCookie, XnCallbackHandle &hCallback)
void UnregisterFromErrorStateChange (XnCallbackHandle hCallback)
XnStatus RegisterToNodeCreation (NodeCreationHandler handler, void *pCookie, XnCallbackHandle &hCallback)
void UnregisterFromNodeCreation (XnCallbackHandle hCallback)
XnStatus RegisterToNodeDestruction (NodeDestructionHandler handler, void *pCookie, XnCallbackHandle &hCallback)
void UnregisterFromNodeDestruction (XnCallbackHandle hCallback)
XnStatus WaitAndUpdateAll ()
XnStatus WaitAnyUpdateAll ()
XnStatus WaitOneUpdateAll (ProductionNode &node)
XnStatus WaitNoneUpdateAll ()
XnStatus AutoEnumerateOverSingleInput (NodeInfoList &List, XnProductionNodeDescription &description, const XnChar *strCreationInfo, XnProductionNodeType InputType, EnumerationErrors *pErrors, Query *pQuery=NULL) const
void SetHandle (XnContext *pContext)
void TakeOwnership (XnContext *pContext)

Static Public Member Functions

static void FreeLicensesList (XnLicense aLicenses[])

Detailed Description

A context is a workspace where the application builds an OpenNI production graph. It contains methods for managing the production graph.

In order to use any of the OpenNI functionality you must first construct a Context object and initialize it. Prior to this, the application cannot do anything with OpenNI.

For a comprehensive overview to the Context class and its members, see Overview to Contexts.

Event: 'Global Error State Change'

Signals that the error state of any of the nodes has changed.

This event can be used by the application to get a signal as soon as any error occurs in one of the production nodes. The global error state aggregates error state from all the production nodes in the context.

Use RegisterToErrorStateChange() and UnregisterFromErrorStateChange() for using this event.

Event: 'Node Creation'

Signals that a new node was created in the context production graph.

Use RegisterToNodeCreation() and UnregisterFromNodeCreation() for using this event.

Event: 'Node Destruction'

Signals that a node was removed from the context production graph, and destroyed.

Use RegisterToNodeDestruction() and UnregisterFromNodeDestruction() for using this event.


Member Typedef Documentation

typedef void(* xn::Context::NodeCreationHandler)(Context &context, ProductionNode &createdNode, void *pCookie)

Callback prototype for the 'Node Creation' event handler.

Parameters:
[in]contextThe context that raised this event.
[in]createdNodeThe id of the hand that disappeared.
[in]pCookieA user-provided cookie that was given when registering to this event.

Example for such a handler:

         void XN_CALLBACK_TYPE OnNodeCreation(Context& context, ProductionNode& createdNode, void* pCookie)
         {}
typedef void(* xn::Context::NodeDestructionHandler)(Context &context, const XnChar *strDestroyedNodeName, void *pCookie)

Callback prototype for the 'Node Destruction' event handler.

Parameters:
[in]contextThe context that raised this event.
[in]strDestroyedNodeNameThe name of the node that was destroyed.
[in]pCookieA user-provided cookie that was given when registering to this event.

Example for such a handler:

         void XN_CALLBACK_TYPE OnNodeDestruction(Context& context, const XnChar* strDestroyedNodeName, void* pCookie)
         {}

Constructor & Destructor Documentation

xn::Context::Context ( ) [inline]

Ctor

xn::Context::Context ( XnContext pContext) [inline]

Ctor

Parameters:
[in]pContextUnderlying C object
xn::Context::Context ( const Context other) [inline]

Copy Ctor

Parameters:
[in]otherAnother context. Note that the context will only be destroyed when the original object is destroyed.
xn::Context::~Context ( ) [inline]

Dtor


Member Function Documentation

XnStatus xn::Context::AddLicense ( const XnLicense License) [inline]
For full details and usage, see xnAddLicense
XnStatus xn::Context::AddRef ( ) [inline]

Adds a reference to the context object.

For full details and usage, see xnContextAddRef
XnStatus xn::Context::AutoEnumerateOverSingleInput ( NodeInfoList List,
XnProductionNodeDescription description,
const XnChar *  strCreationInfo,
XnProductionNodeType  InputType,
EnumerationErrors pErrors,
Query pQuery = NULL 
) const [inline]
For full details and usage, see xnAutoEnumerateOverSingleInput
XnStatus xn::Context::CreateAnyProductionTree ( XnProductionNodeType  type,
Query pQuery,
ProductionNode node,
EnumerationErrors pErrors = NULL 
) [inline]

Enumerates for production nodes of a specific node type, and creates the first production node found of that type.

Parameters:
[in]typeRequested node type.
[in]pQueryOptional. A query object that can be used to filter results.
[out]nodeHandle to the newly created node.
[in,out]pErrorsOptional. To contain enumeration errors.

Remarks:

This method is a 'shortcut' version of using the EnumerateProductionTrees() method and then passing the first result to CreateProductionTree(). Thus, this method is exactly like the Create() method for nodes.

Other ways of creating a production graph let the application retrieve a complete list of alternatives and then choose the most appropriate alternative.

This method is the method used by the above XML script methods to create the ProductionNode objects. The XML method runs the XML script, and for each node description the XML method runs this function to create that node.

Using this function is called 'creating a node from the context'. You can also create a node by invoking the Create method of the node itself, e.g., the Create() method of a HandsGenerator node.

By default, this method does not enable the production nodes to start generating data immediately on creation.

See also:
Understanding the Create() method for more detail.
XnStatus xn::Context::CreateCodec ( XnCodecID  codecID,
ProductionNode initializerNode,
Codec codec 
) [inline]
For full details and usage, see xnCreateCodec
XnStatus xn::Context::CreateMockNode ( XnProductionNodeType  type,
const XnChar *  strName,
ProductionNode mockNode 
) [inline]

Creates a production node which is only a mock. This node does not represent an actual node, but only keeps a state and implements an interface above it. Mock nodes are useful when simulating nodes for playing recordings, or for use in tests. See also xnCreateMockNodeBasedOn().

For full details and usage, see xnCreateMockNode
XnStatus xn::Context::CreateMockNodeBasedOn ( ProductionNode originalNode,
const XnChar *  strName,
ProductionNode mockNode 
) [inline]

Creates a production node which is only a mock, base on the type and properties of another node. This node does not represent an actual node, but only keeps a state and implements an interface above it. Mock nodes are useful when simulating nodes for playing recordings, or for use in tests. See also xnCreateMockNode().

For full details and usage, see xnCreateMockNodeBasedOn
XnStatus xn::Context::CreateProductionTree ( NodeInfo Tree,
ProductionNode node 
) [inline]

Creates a production node from the information supplied in a xn::NodeInfo object.

Parameters:
[in]TreeNode properties for creating the new node.
[out]nodeReference to the new xn::ProductionNode object.

Remarks:

The application gets the NodeInfo object by choosing it from the list returned by the xn::Context::EnumerateProductionTrees() method.

If the new production node requires additional nodes for its input, and those nodes do not yet exist, then this method creates those additional nodes also and associates them with the "original" new production node.

XnStatus xn::Context::EnumerateExistingNodes ( NodeInfoList list) const [inline]

Returns a list of all the context's existing created nodes.

Parameters:
[out]listList of the context's existing created nodes.

You can use the xn::NodeInfoList::FilterList() method to filter the returned list of existing nodes.

XnStatus xn::Context::EnumerateExistingNodes ( NodeInfoList list,
XnProductionNodeType  type 
) const [inline]

Returns a list of the context's existing created nodes filtered by type.

Parameters:
[in]listList of the context's existing created nodes.
[in]typeType to enumerate for.

Remarks

Returns the list after filtering them by type, so it returns a list of the created nodes of the specific type only.

An example of a typical case of returning a list of two nodes of the same type is where there are two sensors in a 3D set-up and you need to retrieve the corresponding two depth nodes to generate data from them.

You can use the xn::NodeInfoList::FilterList() method to filter the returned list of existing nodes.

XnStatus xn::Context::EnumerateLicenses ( XnLicense *&  aLicenses,
XnUInt32 &  nCount 
) const [inline]
For full details and usage, see xnEnumerateLicenses
XnStatus xn::Context::EnumerateProductionTrees ( XnProductionNodeType  Type,
const Query pQuery,
NodeInfoList TreesList,
EnumerationErrors pErrors = NULL 
) const [inline]

Enumerates all available production nodes for a specific node type (e.g., the application wants to create a depth generator node) and returns a full list of matching production nodes.

Parameters:
[in]TypeRequested node type.
[in]pQueryOptional. A query object that can be used to filter results.
[out]TreesListList of possible production nodes.
[out]pErrorsOptional. To contain enumeration errors.

Remarks:

The application chooses one of the nodes from the node list returned by this method and uses it as input to the xn::Context::CreateProductionTree() method to create a new production node.

Using this method to help create a production node offers the greatest flexibility since it returns a complete list of matching production nodes and so the application can then choose the most suitable node.

By contrast, using CreateAnyProductionTree() or a node's Create() method creates a node from the first matching node that satisfies the query.

XnStatus xn::Context::FindExistingNode ( XnProductionNodeType  type,
ProductionNode node 
) const [inline]

Searches for an existing created node of a specified type and returns a reference to it.

Parameters:
[in]typeType of node to search for.
[out]nodeReference to an existing created node that was found.

Remarks

This method returns only the first node it finds; this method does not return the entire list of matching nodes. Compare this with the xn::Context::EnumerateExistingNodes() method, which returns the entire list of matching nodes. A typical usage is that the application already created all the nodes from XML. Then, when it needs to start generating data from a particular node, e.g., the skeleton data, it will call FindExistingNode specifying the skeleton type, and it will get it and start using it.

This method does not provide a query parameter (compare with xn::Context::EnumerateExistingNodes).

static void xn::Context::FreeLicensesList ( XnLicense  aLicenses[]) [inline, static]
For full details and usage, see xnFreeLicensesList
XnStatus xn::Context::GetGlobalErrorState ( ) [inline]

Gets the global error state of the context. If one of the nodes in the context is in error state, that state will be returned. If more than one node is in error state, XN_STATUS_MULTIPLE_NODES_ERROR is returned. An application can query each node error state by calling xnGetNodeErrorState().

For full details and usage, see xnGetGlobalErrorState
XnBool xn::Context::GetGlobalMirror ( ) [inline]

Gets the current state of the GlobalMirror flag.

XnStatus xn::Context::GetProductionNodeByName ( const XnChar *  strInstanceName,
ProductionNode node 
) const [inline]
For full details and usage, see xnGetNodeHandleByName
XnStatus xn::Context::GetProductionNodeInfoByName ( const XnChar *  strInstanceName,
NodeInfo nodeInfo 
) const [inline]
For full details and usage, see xnGetNodeHandleByName
XnContext* xn::Context::GetUnderlyingObject ( ) const [inline]

Gets the underlying C object

XnStatus xn::Context::Init ( ) [inline]

Builds the context's general software environment.

This method initializes runtime variables and data structures, and examines all registered plug-ins to learn the purpose and specific capabilities of each. In particular, during initialization the context initialization examines all registered plug-ins to learn the purpose and specific capabilities of each. For example, one plug-in is for creating a skeleton node, and another plug-in is for creating a depth node. Thus an entire database is built of plug-ins that can be queried according to vendor, model, and capabilities of each.

Once you have completed the initialization you can create nodes that are based on the plug-ins that OpenNI has discovered by this initialization process.

XnStatus xn::Context::InitFromXmlFile ( const XnChar *  strFileName,
ScriptNode scriptNode,
EnumerationErrors pErrors = NULL 
) [inline]

Shorthand combination of two other initialization methods - Init() and then RunXmlScriptFromFile() - to initialize the context object and then create a production graph.

Parameters:
[in]strFileNameName of file containing an XML script.
[out]scriptNodeScriptNode object as the root to all the nodes created from the XML file. When no longer needed, the node can be released, causing all the created nodes to decrement their reference counts.
[out]pErrorsOptional. To be filled with enumeration errors.

Remarks:

The XML script file describes all the nodes you want to create. For each node description in the XML file, this method creates a xn::ProductionNode object.

XnStatus xn::Context::OpenFileRecording ( const XnChar *  strFileName,
ProductionNode playerNode 
) [inline]

Recreates a production graph from a recorded ONI file and then replays the data generation exactly as it was recorded.

Parameters:
[in]strFileNameName of the recorded file to be run.
[out]playerNodeReturns a xn::Player object through which playback can be controlled, e.g., seeking and setting playback speed.

Remarks:

OpenNI provides great flexibility of recording. You can decide you want to record only the final output, e.g., just a skeleton in movement; or record both the output skeleton and the depth input; or record only the depth input and then recreate the skeleton at run-time after reading the recorded raw depth data. You can also choose which nodes to record.

XnBool xn::Context::operator!= ( const Context other) [inline]

Checks if two context objects are not references to the same context.

Parameters:
[in]otherAnother object
Context& xn::Context::operator= ( const Context other) [inline]
XnBool xn::Context::operator== ( const Context other) [inline]

Checks if two context objects are references to the same context.

Parameters:
[in]otherAnother object
XnStatus xn::Context::RegisterToErrorStateChange ( XnErrorStateChangedHandler  handler,
void *  pCookie,
XnCallbackHandle hCallback 
) [inline]

Registers an event handler for the 'Global Error State Change' event.

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::Context::RegisterToNodeCreation ( NodeCreationHandler  handler,
void *  pCookie,
XnCallbackHandle hCallback 
) [inline]

Registers an event handler for the 'Node Creation' event. see Event: 'Node Creation'.

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::Context::RegisterToNodeDestruction ( NodeDestructionHandler  handler,
void *  pCookie,
XnCallbackHandle hCallback 
) [inline]

Registers an event handler for the 'Node Destruction' event. see Event: 'Node Destruction'.

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.

void xn::Context::Release ( ) [inline]

Releases a context object, decreasing its ref count by 1. If reference count has reached 0, the context will be destroyed.

For full details and usage, see xnContextRelease
XnStatus xn::Context::RunXmlScript ( const XnChar *  strScript,
ScriptNode scriptNode,
EnumerationErrors pErrors = NULL 
) [inline]

Runs an XML script string to build a production graph.

Parameters:
[in]strScriptString containing an XML script.
[out]scriptNodexn::ScriptNode object as the root to all the nodes created from the XML file. When no longer needed, the node can be released, causing all the created nodes to decrement their reference counts.
[in,out]pErrorsOptional. To be filled with enumeration errors.

Remarks:

For a full description of the XML structure, see Xml Scripts. Compare this method with initialization methods that run an XML script from a file.

XnStatus xn::Context::RunXmlScriptFromFile ( const XnChar *  strFileName,
ScriptNode scriptNode,
EnumerationErrors pErrors = NULL 
) [inline]

Runs an XML script file to build a production graph.

Parameters:
[in]strFileNameName of file containing an XML script.
[out]scriptNodescriptNode object as the root to all the nodes created from the XML file. When no longer needed, the node can be released, causing all the created nodes to decrement their reference counts.
[in,out]pErrorsOptional. To be filled with enumeration errors.

Remarks:

The XML script file describes all the nodes you want to create. For each node description in the XML file, this method creates a xn::ProductionNode object.

XnStatus xn::Context::SetGlobalMirror ( XnBool  bMirror) [inline]

Enables/disables the GlobalMirror flag.

Parameters:
[in]bMirrorNew mirroring state.

Remarks:

See Global Mirror for understanding of the 'Global Mirror' concept.

void xn::Context::SetHandle ( XnContext pContext) [inline]

Replaces the underlying C object pointed to by this object.

XnStatus xn::Context::StartGeneratingAll ( ) [inline]

Ensures all created generator nodes are generating data.

XnStatus xn::Context::StopGeneratingAll ( ) [inline]

Ensures all generator nodes are not generating data.

void xn::Context::TakeOwnership ( XnContext pContext) [inline]
void xn::Context::UnregisterFromErrorStateChange ( XnCallbackHandle  hCallback) [inline]

Unregisters an event handler for the 'Global Error State Change' event.

Parameters:
[in]hCallbackHandle received from registration.

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

void xn::Context::UnregisterFromNodeCreation ( XnCallbackHandle  hCallback) [inline]

Unregisters an event handler for the 'Node Creation' event. see Event: 'Node Creation'.

Parameters:
[in]hCallbackHandle received from registration.

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

void xn::Context::UnregisterFromNodeDestruction ( XnCallbackHandle  hCallback) [inline]

Unregisters an event handler for the 'Node Destruction' event. see Event: 'Node Destruction'.

Parameters:
[in]hCallbackHandle received from registration.

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

XnStatus xn::Context::WaitAndUpdateAll ( ) [inline]

Updates all generator nodes in the context to their latest available data, first waiting for all nodes to have new data available.

Remarks

This method requests from OpenNI to cause all nodes in the context's Production Graph that have new data available to update their application buffers with the new data, each node updating its own application buffer.

Before OpenNI causes the data updates, it waits until all the nodes have notified that they have new data available. On receiving all the 'new data available' notifications, OpenNI then causes all nodes with new data available to update their application buffers with their new data. At this stage the generator nodes have "generated" new data. This method then stops waiting and returns a success status. The application can now read the newly generated data.

Note:
Using this method is not recommended for most applications since it requires all the nodes to have new data. Consider instead using WaitAnyUpdateAll() or WaitOneUpdateAll(). Typical applications use the WaitAnyUpdateAll() method.

An error situation is defined as: after a preset timeout, not all nodes have yet notified OpenNI they have new data available. On error, the method stops waiting and returns an error status. None of the nodes update their application buffers.

See 'Wait and Update' Methods for an overview to the 'WaitXUpdateAll' methods and how to read the data from the nodes.

Return values:
XN_STATUS_WAIT_DATA_TIMEOUTNo new data available within 2 seconds.
XnStatus xn::Context::WaitAnyUpdateAll ( ) [inline]

Updates all generator nodes in the context to their latest available data, first waiting for any of the nodes to have new data available.

Note:
Typical applications use this method. Consider using this method for your application.

Remarks

This method requests from OpenNI to cause all nodes with new data available in the context's Production Graph to update their application buffers with the new data, each node updating its own application buffer.

Before OpenNI causes the data updates, it waits for any of the nodes to have notified that it has new data available. On receiving a 'new data available' notification, OpenNI then causes all nodes with new data available to update their application buffers with their new data. At this stage the generator nodes have "generated" new data. This method then stops waiting and returns a success status. The application can now read the newly generated data.

A node that does not have new data available does not update its application buffer.

An error situation is defined as: after a preset timeout, none of the nodes have yet notified OpenNI they have new data available. On error, the method stops waiting and returns an error status. None of the nodes update their application buffers.

See 'Wait and Update' Methods for an overview to the 'WaitXUpdateAll' methods and how to read the data from the nodes.

Return values:
XN_STATUS_WAIT_DATA_TIMEOUTNo new data available within 2 seconds.
XnStatus xn::Context::WaitNoneUpdateAll ( ) [inline]

Immediately updates all generator nodes in the context to their latest available data, without waiting for notification that any node has new data available.

Remarks

This method requests from OpenNI to cause all nodes in the context's Production Graph with new data available to update their application buffers with the new data, each node updating its own application buffer.

OpenNI causes all nodes with new data available to update their application buffers with their new data. At this stage the generator nodes have "generated" new data. This method returns a success status. The application can now read the newly generated data.

A node that does not have new data available does not update its application buffer.

See 'Wait and Update' Methods for an overview to the 'WaitXUpdateAll' methods and how to read the data from the nodes.

XnStatus xn::Context::WaitOneUpdateAll ( ProductionNode node) [inline]

Updates all generator nodes in the context to their latest available data, first waiting for a specified node to have new data available.

Remarks

This method requests from OpenNI to cause all nodes in the context's Production Graph with new data available to update their application buffers with the new data, each node updating its own application buffer.

Before OpenNI causes the data updates, it waits for a specified node to notify that it has new data available. On receiving the 'new data available' notification, OpenNI then causes all nodes with new data available to update their application buffers with their new data. At this stage the generator nodes have "generated" new data. This method then stops waiting and returns a success status. The application can now read the newly generated data.

A node that does not have new data available does not update its application buffer.

An error situation is defined as: after a preset timeout, none of the nodes have yet notified OpenNI they have has new data available. On error, the method stops waiting and returns an error status. None of the nodes update their application buffers.

See 'Wait and Update' Methods for an overview to the 'WaitXUpdateAll' methods and how to read the data from the nodes.

Return values:
XN_STATUS_WAIT_DATA_TIMEOUTNo new data available within 2 seconds.

The documentation for this class was generated from the following file:
Generated on Wed May 16 2012 10:16:07 for OpenNI 1.5.4 by   doxygen 1.7.5.1