Initialization
Functions for initializing and shutting down an OpenNI context.
XN_C_API XnStatus	xnInit (XnContext **ppContext)
	Initializes the OpenNI library.
XN_C_API XnStatus	xnContextRunXmlScriptFromFile (XnContext pContext, const XnChar strFileName, XnEnumerationErrors *pErrors)
	Runs an XML script in the given context.
XN_C_API XnStatus	xnContextRunXmlScript (XnContext pContext, const XnChar xmlScript, XnEnumerationErrors *pErrors)
	Runs an XML script in the given context.
XN_C_API XnStatus	xnInitFromXmlFile (const XnChar strFileName, XnContext ppContext, XnEnumerationErrors pErrors)
	Initializes OpenNI context, and then configures it using the given file.
XN_C_API XnStatus	xnContextOpenFileRecording (XnContext pContext, const XnChar strFileName)
	Opens a recording file, adding all nodes in it to the context.
XN_C_API void	xnShutdown (XnContext *pContext)
	Shuts down the OpenNI library. No other OpenNI function can be called after calling this function.
Enumeration
Functions for enumeration and creation of nodes.
XN_C_API XnStatus	xnEnumerateProductionTrees (XnContext pContext, XnProductionNodeType Type, const XnNodeQuery pQuery, XnNodeInfoList *ppTreesList, XnEnumerationErrors pErrors)
	Enumerates all available production trees for a specific node type. The trees populated in the list should be freed by calling xnNodeInfoListFree() once not needed.
XN_C_API XnStatus	xnCreateProductionTree (XnContext pContext, XnNodeInfo pTree, XnNodeHandle *phNode)
	Creates a production node. If the tree specifies additional needed nodes, and those nodes do not exist, they will be created too, and passed to this node as input.
XN_C_API XnStatus	xnCreateAnyProductionTree (XnContext pContext, XnProductionNodeType type, XnNodeQuery pQuery, XnNodeHandle phNode, XnEnumerationErrors pErrors)
	Enumerates for production trees for a specific node type, and creates the first found tree. This function is a shortcut version for using xnEnumerateProductionTrees(), iterating the list, and then calling xnCreateProductionTree().
XN_C_API XnStatus	xnCreateMockNode (XnContext pContext, XnProductionNodeType type, const XnChar strName, XnNodeHandle *phNode)
	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().
XN_C_API XnStatus	xnCreateMockNodeBasedOn (XnContext pContext, XnNodeHandle hOriginalNode, const XnChar strName, XnNodeHandle *phMockNode)
	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().
XN_C_API XnStatus	xnRefProductionNode (XnNodeHandle hNode)
	References a production node, increasing its reference count by 1.
XN_C_API void	xnUnrefProductionNode (XnNodeHandle hNode)
	Unreference a production node, decreasing its reference count by 1. If the reference count reaches zero, the node will be destroyed.
XN_C_API XnStatus	xnEnumerateExistingNodes (XnContext pContext, XnNodeInfoList *ppList)
	Gets a list of all existing node in the context. Each node that was returned increases its ref count. The list must be freed using xnNodeInfoListFree().
XN_C_API XnStatus	xnEnumerateExistingNodesByType (XnContext pContext, XnProductionNodeType type, XnNodeInfoList *ppList)
	Gets a list of all existing node in the context. Each node that was returned increases its ref count. The list must be freed using xnNodeInfoListFree().
XN_C_API XnStatus	xnFindExistingNodeByType (XnContext pContext, XnProductionNodeType type, XnNodeHandle phNode)
	Returns the first found existing node of the specified type.
XN_C_API XnStatus	xnGetNodeHandleByName (XnContext pContext, const XnChar strInstanceName, XnNodeHandle *phNode)
	Gets a handle to an existing production node instance using that instance name.
Multi-Node Handling
Functions that affect all the nodes in the context.
XN_C_API XnStatus	xnWaitAndUpdateAll (XnContext *pContext)
	Updates all generators nodes in the context, waiting for all to have new data.
XN_C_API XnStatus	xnWaitOneUpdateAll (XnContext *pContext, XnNodeHandle hNode)
	Updates all generators nodes in the context, waiting for a specific one to have new data.
XN_C_API XnStatus	xnWaitAnyUpdateAll (XnContext *pContext)
	Updates all generators nodes in the context, once any of them have new data.
XN_C_API XnStatus	xnWaitNoneUpdateAll (XnContext *pContext)
	Updates all generator nodes in the context, without any waiting. If a node has new data, it will be updated.
XN_C_API XnStatus	xnStartGeneratingAll (XnContext *pContext)
	Make sure all generators are generating data.
XN_C_API XnStatus	xnStopGeneratingAll (XnContext *pContext)
	Stop all generators from generating data.
XN_C_API XnStatus	xnSetGlobalMirror (XnContext *pContext, XnBool bMirror)
	Sets the global mirror flag. This will set all current existing nodes' mirror state, and also affect future created nodes. The default mirror flag is FALSE.
XN_C_API XnBool	xnGetGlobalMirror (XnContext *pContext)
	Gets the global mirror flag.
XN_C_API XnStatus	xnGetGlobalErrorState (XnContext *pContext)
	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().
XN_C_API XnStatus	xnRegisterToGlobalErrorStateChange (XnContext pContext, XnErrorStateChangedHandler handler, void pCookie, XnCallbackHandle *phCallback)
	Registers a callback function to global error state changes.
XN_C_API void	xnUnregisterFromGlobalErrorStateChange (XnContext *pContext, XnCallbackHandle hCallback)
	Unregisters a callback function which was registered using xnRegisterToGlobalErrorStateChange().

Detailed Description

This page details functions for managing an OpenNI context.

Initializing and Deinitializing OpenNI Context

Initialization must be performed before using any OpenNI functionality, and similarly you must not call any OpenNI functions after deinitialization.

Enumerating and Creating Production Trees

A production tree is composed of a production node, and optionally a list of other production trees needed for this production node. Each production node has a type (one of the types defined by OpenNI spec), a vendor name, and a specific name (unique for this type and vendor), with a version. For example, a User generator may need a Depth generator, which in turn might need a Device node.

Enumeration Results

The results from an enumeration operation is a pointer to the first node of a linked list, representing all the different possibilities to get data of the requested type. A single possibility contains the provider description, an optional instance name (that can be used by the provider as proprietary information, like a device S/N), and the bExists field, which tells if this node already exists in the context (and as such, doesn't need to be created) or not, and a list of needed nodes by this node.

Enumerating Example

For example, let's take a look at an application in need of depth maps:

// Enumerate for production trees that can produce depth
XnNodeInfoList* pNodesList;
nRetVal = xnEnumerateProductionTrees(pNiteCtx, XN_NODE_TYPE_DEPTH, NULL, &pNodesList);
CHECK_RC(nRetVal, "Enumerate");

// choose a tree (for simplicity, take first one)
XnNodeInfoListIterator itChosen = xnNodeInfoListGetFirst(pNodesList);
XnNodeInfo* pChosen = xnNodeInfoListGetCurrent(itChosen);

// create first one
XnNodeHandle hDepth;
nRetVal = xnCreateProductionTree(pNiteCtx, pChosen, &hDepth);
CHECK_RC(nRetVal, "Create");

// free the list (it is no longer needed)
xnNodeInfoListFree(pNodesList);

// TODO: use handle for configuration and data extraction

Function Documentation

XN_C_API XnStatus xnContextOpenFileRecording	(	XnContext *	pContext,
		const XnChar *	strFileName
	)

Opens a recording file, adding all nodes in it to the context.

Parameters:

pContext	[in] The context.
strFileName	[in] The file to open.

XN_C_API XnStatus xnContextRunXmlScript	(	XnContext *	pContext,
		const XnChar *	xmlScript,
		XnEnumerationErrors *	pErrors
	)

Runs an XML script in the given context.

Parameters:

pContext	[in] The context.
xmlScript	[in] A string representation of the XML script. for a full description of the XML structure, see xmlscripts.
pErrors	[in/out] Optional. If provided, will be filled with enumeration errors.

XN_C_API XnStatus xnContextRunXmlScriptFromFile	(	XnContext *	pContext,
		const XnChar *	strFileName,
		XnEnumerationErrors *	pErrors
	)

Runs an XML script in the given context.

Parameters:

pContext	[in] The context to be configured.
strFileName	[in] The name of the file containing the script. for a full description of the XML structure, see xmlscripts.
pErrors	[in/out] Optional. If provided, will be filled with enumeration errors.

XN_C_API XnStatus xnCreateAnyProductionTree	(	XnContext *	pContext,
		XnProductionNodeType	type,
		XnNodeQuery *	pQuery,
		XnNodeHandle *	phNode,
		XnEnumerationErrors *	pErrors
	)

Enumerates for production trees for a specific node type, and creates the first found tree. This function is a shortcut version for using xnEnumerateProductionTrees(), iterating the list, and then calling xnCreateProductionTree().

Parameters:

pContext	[in] OpenNI context.
type	[in] The requested node type.
pQuery	[in] Optional. A query object that can be used to filter results.
phNode	[out] A handle to the newly created node.
pErrors	[in/out] Optional. If provided, will be filled with enumeration errors.

XN_C_API XnStatus xnCreateMockNode	(	XnContext *	pContext,
		XnProductionNodeType	type,
		const XnChar *	strName,
		XnNodeHandle *	phNode
	)

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().

Parameters:

pContext	[in] OpenNI context.
type	[in] The type of the mock to create.
strName	[in] Optional. The name of the node. If NULL is provided, a name will be automatically generated.
phNode	[out] A handle to the newly created node.

XN_C_API XnStatus xnCreateMockNodeBasedOn	(	XnContext *	pContext,
		XnNodeHandle	hOriginalNode,
		const XnChar *	strName,
		XnNodeHandle *	phMockNode
	)

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().

Parameters:

pContext	[in] OpenNI context.
hOriginalNode	[in] A handle to an existing node on which the mock node will be based on.
strName	[in] The name of the node. If set to NULL, a name will be generated based on the name of hOriginalNode.
phMockNode	[out] A handle to the newly created mock node.

XN_C_API XnStatus xnCreateProductionTree	(	XnContext *	pContext,
		XnNodeInfo *	pTree,
		XnNodeHandle *	phNode
	)

Creates a production node. If the tree specifies additional needed nodes, and those nodes do not exist, they will be created too, and passed to this node as input.

Parameters:

pContext	[in] OpenNI context.
pTree	[in] A production tree to create.
phNode	[out] A handle to the newly created node.

XN_C_API XnStatus xnEnumerateExistingNodes	(	XnContext *	pContext,
		XnNodeInfoList **	ppList
	)

Gets a list of all existing node in the context. Each node that was returned increases its ref count. The list must be freed using xnNodeInfoListFree().

Parameters:

pContext	[in] OpenNI context.
ppList	[out] A linked list of current existing nodes

XN_C_API XnStatus xnEnumerateExistingNodesByType	(	XnContext *	pContext,
		XnProductionNodeType	type,
		XnNodeInfoList **	ppList
	)

Gets a list of all existing node in the context. Each node that was returned increases its ref count. The list must be freed using xnNodeInfoListFree().

Parameters:

pContext	[in] OpenNI context.
type	[in] Type to look for.
ppList	[out] A linked list of current existing nodes

XN_C_API XnStatus xnEnumerateProductionTrees	(	XnContext *	pContext,
		XnProductionNodeType	Type,
		const XnNodeQuery *	pQuery,
		XnNodeInfoList **	ppTreesList,
		XnEnumerationErrors *	pErrors
	)

Enumerates all available production trees for a specific node type. The trees populated in the list should be freed by calling xnNodeInfoListFree() once not needed.

Parameters:

pContext	[in] OpenNI context.
Type	[in] The requested node type.
pQuery	[in] Optional. A query object that can be used to filter results.
ppTreesList	[out] A list of possible production trees.
pErrors	[in/out] Optional. If provided, will be filled with enumeration errors.

XN_C_API XnStatus xnFindExistingNodeByType	(	XnContext *	pContext,
		XnProductionNodeType	type,
		XnNodeHandle *	phNode
	)

Returns the first found existing node of the specified type.

Parameters:

pContext	[in] OpenNI context.
type	[in] Type to look for.
phNode	[out] A handle to the found node.

XN_C_API XnStatus xnGetGlobalErrorState ( XnContext * pContext )

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().

Parameters:

pContext [in] OpenNI context.

XN_C_API XnBool xnGetGlobalMirror ( XnContext * pContext )

Gets the global mirror flag.

Parameters:

pContext [in] OpenNI context.

XN_C_API XnStatus xnGetNodeHandleByName	(	XnContext *	pContext,
		const XnChar *	strInstanceName,
		XnNodeHandle *	phNode
	)

Gets a handle to an existing production node instance using that instance name.

Parameters:

pContext	[in] OpenNI context.
strInstanceName	[in] Name of the instance to get.
phNode	[out] A handle to that instance.

Returns:: XN_STATUS_BAD_NODE_NAME if node by name of strInstanceName doesn't exist.

XN_C_API XnStatus xnInit ( XnContext ** ppContext )

Initializes the OpenNI library.

This function must be called before calling any other OpenNI function (except for xnInitFromXmlFile())

Parameters:

ppContext [out] Output location for context pointer.

XN_C_API XnStatus xnInitFromXmlFile	(	const XnChar *	strFileName,
		XnContext **	ppContext,
		XnEnumerationErrors *	pErrors
	)

Initializes OpenNI context, and then configures it using the given file.

Parameters:

strFileName	[in] The name of the file to read configuration from.
ppContext	[out] Output location for context pointer.
pErrors	[in/out] Optional. If provided, will be filled with enumeration errors.

XN_C_API XnStatus xnRefProductionNode ( XnNodeHandle hNode )

References a production node, increasing its reference count by 1.

Parameters:

hNode [in] A handle to the node.

XN_C_API XnStatus xnRegisterToGlobalErrorStateChange	(	XnContext *	pContext,
		XnErrorStateChangedHandler	handler,
		void *	pCookie,
		XnCallbackHandle *	phCallback
	)

Registers a callback function to global error state changes.

Parameters:

pContext	[in] OpenNI context.
handler	[in] A pointer to a function that will be called when global error state changes.
pCookie	[in] A user cookie that will be passed to the callback function.
phCallback	[out] Optional. Will be filled with a handle to be passed to xnUnregisterFromGlobalErrorStateChange().

XN_C_API XnStatus xnSetGlobalMirror	(	XnContext *	pContext,
		XnBool	bMirror
	)

Sets the global mirror flag. This will set all current existing nodes' mirror state, and also affect future created nodes. The default mirror flag is FALSE.

Parameters:

pContext	[in] OpenNI context.
bMirror	[in] New Mirror state.

XN_C_API void xnShutdown ( XnContext * pContext )

Shuts down the OpenNI library. No other OpenNI function can be called after calling this function.

Parameters:

pContext [in] The context to be destroyed.

XN_C_API XnStatus xnStartGeneratingAll ( XnContext * pContext )

Make sure all generators are generating data.

Parameters:

pContext [in] OpenNI context.

XN_C_API XnStatus xnStopGeneratingAll ( XnContext * pContext )

Stop all generators from generating data.

Parameters:

pContext [in] OpenNI context.

XN_C_API void xnUnrefProductionNode ( XnNodeHandle hNode )

Unreference a production node, decreasing its reference count by 1. If the reference count reaches zero, the node will be destroyed.

Parameters:

hNode [in] A handle to the node.

XN_C_API void xnUnregisterFromGlobalErrorStateChange	(	XnContext *	pContext,
		XnCallbackHandle	hCallback
	)

Unregisters a callback function which was registered using xnRegisterToGlobalErrorStateChange().

Parameters:

pContext	[in] OpenNI context.
hCallback	[in] The handle to the callback returned from xnRegisterToGlobalErrorStateChange().

XN_C_API XnStatus xnWaitAndUpdateAll ( XnContext * pContext )

Updates all generators nodes in the context, waiting for all to have new data.

Parameters:

pContext [in] OpenNI context.

XN_C_API XnStatus xnWaitAnyUpdateAll ( XnContext * pContext )

Updates all generators nodes in the context, once any of them have new data.

Parameters:

pContext [in] OpenNI context.

XN_C_API XnStatus xnWaitNoneUpdateAll ( XnContext * pContext )

Updates all generator nodes in the context, without any waiting. If a node has new data, it will be updated.

Parameters:

pContext [in] OpenNI context.

XN_C_API XnStatus xnWaitOneUpdateAll	(	XnContext *	pContext,
		XnNodeHandle	hNode
	)

Updates all generators nodes in the context, waiting for a specific one to have new data.

Parameters:

pContext	[in] OpenNI context.
hNode	[in] The node to wait for.

Initialization

Enumeration

Multi-Node Handling

Detailed Description

Initializing and Deinitializing OpenNI Context

Enumerating and Creating Production Trees

Enumeration Results

Enumerating Example

Function Documentation