Utilities
C Reference

## General

XN_C_API XnStatus XN_C_DECL | xnGetVersion (XnVersion *pVersion)

## ProductionNodeType Utils

XN_C_API const XnChar *XN_C_DECL | xnProductionNodeTypeToString (XnProductionNodeType Type)
XN_C_API XnStatus XN_C_DECL | xnProductionNodeTypeFromString (const XnChar *strType, XnProductionNodeType *pType)
XN_C_API XnBool XN_C_DECL | xnIsTypeGenerator (XnProductionNodeType type)
XN_C_API XnBool XN_C_DECL | xnIsTypeDerivedFrom (XnProductionNodeType type, XnProductionNodeType base)

## PixelFormat Utils

XN_C_API const XnChar *XN_C_DECL | xnPixelFormatToString (XnPixelFormat format)
XN_C_API XnStatus XN_C_DECL | xnPixelFormatFromString (const XnChar *strName, XnPixelFormat *pFormat)
XN_C_API XnUInt32 XN_C_DECL | xnGetBytesPerPixelForPixelFormat (XnPixelFormat format)

## Resolution Utilities

XN_C_API XnUInt32 XN_C_DECL | xnResolutionGetXRes (XnResolution resolution)
XN_C_API XnUInt32 XN_C_DECL | xnResolutionGetYRes (XnResolution resolution)
XN_C_API XnResolution XN_C_DECL | xnResolutionGetFromXYRes (XnUInt32 xRes, XnUInt32 yRes)
XN_C_API XnResolution XN_C_DECL | xnResolutionGetFromName (const XnChar *strName)
XN_C_API const XnChar *XN_C_DECL | xnResolutionGetName (XnResolution resolution)

## XnVersion Utilities

XN_C_API XnInt32 XN_C_DECL | xnVersionCompare (const XnVersion *pVersion1, const XnVersion *pVersion2)
XN_C_API XnStatus XN_C_DECL | xnVersionToString (const XnVersion *pVersion, XnChar *csResult, XnUInt32 nSize)

## XnProductionNodeDescription Utilities

XN_C_API XnStatus XN_C_DECL | xnProductionNodeDescriptionToString (const XnProductionNodeDescription *pDescription, XnChar *csResult, XnUInt32 nSize)

## C Style Constructors

XN_C_API XnPoint3D XN_C_DECL | xnCreatePoint3D (XnFloat x, XnFloat y, XnFloat z)
XN_C_API XnPlane3D XN_C_DECL | xnCreatePlane3D (XnPoint3D ptPoint, XnVector3D vNormal)

## Modules Registry Management

XN_C_API XnStatus XN_C_DECL | xnRegisterModule (const XnChar *strModule, const XnChar *strConfigDir)
XN_C_API XnStatus XN_C_DECL | xnUnregisterModule (const XnChar *strModule)
XN_C_API XnStatus XN_C_DECL | xnPrintRegisteredModules ()

## Global Licenses Registry Management

XN_C_API XnStatus XN_C_DECL | xnRegisterGlobalLicense (XnLicense *pLicense)
XN_C_API XnStatus XN_C_DECL | xnUnregisterGlobalLicense (XnLicense *pLicense)
XN_C_API XnStatus XN_C_DECL | xnPrintRegisteredLicenses ()

## MetaData Objects Management

XN_C_API XnOutputMetaData *XN_C_DECL | xnAllocateOutputMetaData ()
XN_C_API void XN_C_DECL | xnFreeOutputMetaData (const XnOutputMetaData *pMetaData)
XN_C_API XnStatus XN_C_DECL | xnCopyOutputMetaData (XnOutputMetaData *pDestination, const XnOutputMetaData *pSource)
XN_C_API XnMapMetaData *XN_C_DECL | xnAllocateMapMetaData ()
XN_C_API void XN_C_DECL | xnFreeMapMetaData (const XnMapMetaData *pMetaData)
XN_C_API XnStatus XN_C_DECL | xnCopyMapMetaData (XnMapMetaData *pDestination, const XnMapMetaData *pSource)
XN_C_API XnDepthMetaData *XN_C_DECL | xnAllocateDepthMetaData ()
XN_C_API void XN_C_DECL | xnFreeDepthMetaData (const XnDepthMetaData *pMetaData)
XN_C_API XnStatus XN_C_DECL | xnCopyDepthMetaData (XnDepthMetaData *pDestination, const XnDepthMetaData *pSource)
XN_C_API XnImageMetaData *XN_C_DECL | xnAllocateImageMetaData ()
XN_C_API void XN_C_DECL | xnFreeImageMetaData (const XnImageMetaData *pMetaData)
XN_C_API XnStatus XN_C_DECL | xnCopyImageMetaData (XnImageMetaData *pDestination, const XnImageMetaData *pSource)
XN_C_API XnIRMetaData *XN_C_DECL | xnAllocateIRMetaData ()
XN_C_API void XN_C_DECL | xnFreeIRMetaData (const XnIRMetaData *pMetaData)
XN_C_API XnStatus XN_C_DECL | xnCopyIRMetaData (XnIRMetaData *pDestination, const XnIRMetaData *pSource)
XN_C_API XnAudioMetaData *XN_C_DECL | xnAllocateAudioMetaData ()
XN_C_API void XN_C_DECL | xnFreeAudioMetaData (const XnAudioMetaData *pMetaData)
XN_C_API XnStatus XN_C_DECL | xnCopyAudioMetaData (XnAudioMetaData *pDestination, const XnAudioMetaData *pSource)
XN_C_API XnSceneMetaData *XN_C_DECL | xnAllocateSceneMetaData ()
XN_C_API void XN_C_DECL | xnFreeSceneMetaData (const XnSceneMetaData *pMetaData)
XN_C_API XnStatus XN_C_DECL | xnCopySceneMetaData (XnSceneMetaData *pDestination, const XnSceneMetaData *pSource)

## Functions for Modules Implementors

XN_C_API XnStatus XN_C_DECL | xnAutoEnumerateOverSingleInput (XnContext *pContext, XnNodeInfoList *pList, XnProductionNodeDescription *pDescription, const XnChar *strCreationInfo, XnProductionNodeType InputType, XnEnumerationErrors *pErrors, XnNodeQuery *pQuery)
XN_C_API XnStatus XN_C_DECL | xnRegisterExtensionNode (const XnChar *strTypeName, XnProductionNodeType baseType, XnProductionNodeType *pTypeID)
XN_C_API XnModuleNodeHandle XN_C_DECL | xnGetModuleNodeHandle (XnNodeHandle hNode)
XN_C_API XnStatus XN_C_DECL | xnRegisterModuleWithOpenNI (XnOpenNIModuleInterface *pInterface, const XnChar *strConfigDir, const XnChar *strName)

## Detailed Description

This page details some utility functions.

## Function Documentation

## xnAllocateAudioMetaData()

XN_C_API XnAudioMetaData *XN_C_DECL xnAllocateAudioMetaData | ( |  | ) |

Allocates and returns an XnAudioMetaData object. When no longer needed, this object should be freed by calling xnFreeAudioMetaData().

Returns
  NULL if allocation failed.

## xnAllocateDepthMetaData()

XN_C_API XnDepthMetaData *XN_C_DECL xnAllocateDepthMetaData | ( |  | ) |

Allocates and returns an XnDepthMetaData object. When no longer needed, this object should be freed by calling xnFreeDepthMetaData().

Returns
  NULL if allocation failed.

## xnAllocateImageMetaData()

XN_C_API XnImageMetaData *XN_C_DECL xnAllocateImageMetaData | ( |  | ) |

Allocates and returns an XnImageMetaData object. When no longer needed, this object should be freed by calling xnFreeImageMetaData().

Returns
  NULL if allocation failed.

## xnAllocateIRMetaData()

XN_C_API XnIRMetaData *XN_C_DECL xnAllocateIRMetaData | ( |  | ) |

Allocates and returns an XnIRMetaData object. When no longer needed, this object should be freed by calling xnFreeIRMetaData().

Returns
  NULL if allocation failed.

## xnAllocateMapMetaData()

XN_C_API XnMapMetaData *XN_C_DECL xnAllocateMapMetaData | ( |  | ) |

Allocates and returns an XnMapMetaData object. When no longer needed, this object should be freed by calling xnFreeMapMetaData().

Returns
  NULL if allocation failed.

## xnAllocateOutputMetaData()

XN_C_API XnOutputMetaData *XN_C_DECL xnAllocateOutputMetaData | ( |  | ) |

Allocates and returns an XnOutputMetaData object. When no longer needed, this object should be freed by calling xnFreeOutputMetaData().

Returns
  NULL if allocation failed.

## xnAllocateSceneMetaData()

XN_C_API XnSceneMetaData *XN_C_DECL xnAllocateSceneMetaData | ( |  | ) |

Allocates and returns an XnSceneMetaData object. When no longer needed, this object should be freed by calling xnFreeSceneMetaData().

Returns
  NULL if allocation failed.

## xnAutoEnumerateOverSingleInput()

XN_C_API XnStatus XN_C_DECL xnAutoEnumerateOverSingleInput | ( | XnContext * | pContext,
|  | XnNodeInfoList * | pList,
|  | XnProductionNodeDescription * | pDescription,
|  | const XnChar * | strCreationInfo,
|  | XnProductionNodeType | InputType,
|  | XnEnumerationErrors * | pErrors,
|  | XnNodeQuery * | pQuery )

A helper function for production nodes implementers. Enumerates needed child nodes (assuming there is only one needed input), and populates a list with production trees over that input.

Parameters

  pContext | [in] OpenNI Context.
  pList | [in] The list to be populated.
  pDescription | [in] The description of the enumerated node.
  strCreationInfo | [in] [Optional] Additional creation info.
  InputType | [in] The type of the input required by this production node.
  pErrors | [in] The errors object passed to Enumerate method.
  pQuery | [in] [Optional] A filter to be used for finding the appropriate input.

## xnCopyAudioMetaData()

XN_C_API XnStatus XN_C_DECL xnCopyAudioMetaData | ( | XnAudioMetaData * | pDestination,
|  | const XnAudioMetaData * | pSource )

Shallow-Copies an Audio Meta Data object. Note that the data buffer is not copied, and that both object will point to the same buffer.

Parameters

  pDestination | [in] Destination object.
  pSource | [in] Source object.

## xnCopyDepthMetaData()

XN_C_API XnStatus XN_C_DECL xnCopyDepthMetaData | ( | XnDepthMetaData * | pDestination,
|  | const XnDepthMetaData * | pSource )

Shallow-Copies a Depth Meta Data object. Note that the data buffer is not copied, and that both object will point to the same buffer.

Parameters

  pDestination | [in] Destination object.
  pSource | [in] Source object.

## xnCopyImageMetaData()

XN_C_API XnStatus XN_C_DECL xnCopyImageMetaData | ( | XnImageMetaData * | pDestination,
|  | const XnImageMetaData * | pSource )

Shallow-Copies an Image Meta Data object. Note that the data buffer is not copied, and that both object will point to the same buffer.

Parameters

  pDestination | [in] Destination object.
  pSource | [in] Source object.

## xnCopyIRMetaData()

XN_C_API XnStatus XN_C_DECL xnCopyIRMetaData | ( | XnIRMetaData * | pDestination,
|  | const XnIRMetaData * | pSource )

Shallow-Copies an IR Meta Data object. Note that the data buffer is not copied, and that both object will point to the same buffer.

Parameters

  pDestination | [in] Destination object.
  pSource | [in] Source object.

## xnCopyMapMetaData()

XN_C_API XnStatus XN_C_DECL xnCopyMapMetaData | ( | XnMapMetaData * | pDestination,
|  | const XnMapMetaData * | pSource )

Shallow-Copies a Map Meta Data object.

Parameters

  pDestination | [in] Destination object.
  pSource | [in] Source object.

## xnCopyOutputMetaData()

XN_C_API XnStatus XN_C_DECL xnCopyOutputMetaData | ( | XnOutputMetaData * | pDestination,
|  | const XnOutputMetaData * | pSource )

Shallow-Copies an Output Meta Data object.

Parameters

  pDestination | [in] Destination object.
  pSource | [in] Source object.

## xnCopySceneMetaData()

XN_C_API XnStatus XN_C_DECL xnCopySceneMetaData | ( | XnSceneMetaData * | pDestination,
|  | const XnSceneMetaData * | pSource )

Shallow-Copies a Scene Meta Data object. Note that the data buffer is not copied, and that both object will point to the same buffer.

Parameters

  pDestination | [in] Destination object.
  pSource | [in] Source object.

## xnCreatePlane3D()

XN_C_API XnPlane3D XN_C_DECL xnCreatePlane3D | ( | XnPoint3D | ptPoint,
|  | XnVector3D | vNormal )

## xnCreatePoint3D()

XN_C_API XnPoint3D XN_C_DECL xnCreatePoint3D | ( | XnFloat | x,
|  | XnFloat | y,
|  | XnFloat | z )

## xnFreeAudioMetaData()

XN_C_API void XN_C_DECL xnFreeAudioMetaData | ( | const XnAudioMetaData * | pMetaData | ) |

Frees a previously allocated XnAudioMetaData object.

Parameters

  pMetaData | [in] object to be freed.

## xnFreeDepthMetaData()

XN_C_API void XN_C_DECL xnFreeDepthMetaData | ( | const XnDepthMetaData * | pMetaData | ) |

Frees a previously allocated XnDepthMetaData object.

Parameters

  pMetaData | [in] object to be freed.

## xnFreeImageMetaData()

XN_C_API void XN_C_DECL xnFreeImageMetaData | ( | const XnImageMetaData * | pMetaData | ) |

Frees a previously allocated XnImageMetaData object.

Parameters

  pMetaData | [in] object to be freed.

## xnFreeIRMetaData()

XN_C_API void XN_C_DECL xnFreeIRMetaData | ( | const XnIRMetaData * | pMetaData | ) |

Frees a previously allocated XnIRMetaData object.

Parameters

  pMetaData | [in] object to be freed.

## xnFreeMapMetaData()

XN_C_API void XN_C_DECL xnFreeMapMetaData | ( | const XnMapMetaData * | pMetaData | ) |

Frees a previously allocated XnMapMetaData object.

Parameters

  pMetaData | [in] object to be freed.

## xnFreeOutputMetaData()

XN_C_API void XN_C_DECL xnFreeOutputMetaData | ( | const XnOutputMetaData * | pMetaData | ) |

Frees a previously allocated XnOutputMetaData object.

Parameters

  pMetaData | [in] object to be freed.

## xnFreeSceneMetaData()

XN_C_API void XN_C_DECL xnFreeSceneMetaData | ( | const XnSceneMetaData * | pMetaData | ) |

Frees a previously allocated XnSceneMetaData object.

Parameters

  pMetaData | [in] object to be freed.

## xnGetBytesPerPixelForPixelFormat()

XN_C_API XnUInt32 XN_C_DECL xnGetBytesPerPixelForPixelFormat | ( | XnPixelFormat | format | ) |

Gets the bytes per pixel of a pixel format.

Parameters

  format | [in] The pixel format.

## xnGetModuleNodeHandle()

XN_C_API XnModuleNodeHandle XN_C_DECL xnGetModuleNodeHandle | ( | XnNodeHandle | hNode | ) |

Gets the module node handle of a node. This is useful for extension implementors.

Parameters

  hNode | [in] The node to get its module node handle.

## xnGetVersion()

XN_C_API XnStatus XN_C_DECL xnGetVersion | ( | XnVersion * | pVersion | ) |

Gets current OpenNI version

Parameters

  pVersion | [out] Current DLL version

## xnIsTypeDerivedFrom()

XN_C_API XnBool XN_C_DECL xnIsTypeDerivedFrom | ( | XnProductionNodeType | type,
|  | XnProductionNodeType | base )

Checks if a certain production node type is a derived of another type.

Parameters

  type | [in] The type to check
  base | [in] The base type to check against

## xnIsTypeGenerator()

XN_C_API XnBool XN_C_DECL xnIsTypeGenerator | ( | XnProductionNodeType | type | ) |

Checks if a certain production node type is a generator or not.

Parameters

  type | [in] The type to check

## xnPixelFormatFromString()

XN_C_API XnStatus XN_C_DECL xnPixelFormatFromString | ( | const XnChar * | strName,
|  | XnPixelFormat * | pFormat )

Gets pixel format by its name.

Parameters

  strName | [in] Name of the pixel format.
  pFormat | [out] Pixel format.

## xnPixelFormatToString()

XN_C_API const XnChar *XN_C_DECL xnPixelFormatToString | ( | XnPixelFormat | format | ) |

Get the name of the pixel format.

Parameters

  format | [in] Pixel Format

## xnPrintRegisteredLicenses()

XN_C_API XnStatus XN_C_DECL xnPrintRegisteredLicenses | ( |  | ) |

## xnPrintRegisteredModules()

XN_C_API XnStatus XN_C_DECL xnPrintRegisteredModules | ( |  | ) |

## xnProductionNodeDescriptionToString()

XN_C_API XnStatus XN_C_DECL xnProductionNodeDescriptionToString | ( | const XnProductionNodeDescription * | pDescription,
|  | XnChar * | csResult,
|  | XnUInt32 | nSize )

## xnProductionNodeTypeFromString()

XN_C_API XnStatus XN_C_DECL xnProductionNodeTypeFromString | ( | const XnChar * | strType,
|  | XnProductionNodeType * | pType )

Gets a type from its string representation.

Parameters

  strType | [in] The string representation of the type.
  pType | [out] The type of the production node.

## xnProductionNodeTypeToString()

XN_C_API const XnChar *XN_C_DECL xnProductionNodeTypeToString | ( | XnProductionNodeType | Type | ) |

Gets a string representation of the production node type.

Parameters

  Type | [in] The type of the production node.

## xnRegisterExtensionNode()

XN_C_API XnStatus XN_C_DECL xnRegisterExtensionNode | ( | const XnChar * | strTypeName,
|  | XnProductionNodeType | baseType,
|  | XnProductionNodeType * | pTypeID )

Registers an extension node with OpenNI. An extension node is a node of type not defined by OpenNI.

Parameters

  strTypeName | [in] Name of this new node type.
  baseType | [in] Type of the direct base for this extension.
  pTypeID | [out] The new ID registered with OpenNI.

## xnRegisterGlobalLicense()

XN_C_API XnStatus XN_C_DECL xnRegisterGlobalLicense | ( | XnLicense * | pLicense | ) |

## xnRegisterModule()

XN_C_API XnStatus XN_C_DECL xnRegisterModule | ( | const XnChar * | strModule,
|  | const XnChar * | strConfigDir )

## xnRegisterModuleWithOpenNI()

XN_C_API XnStatus XN_C_DECL xnRegisterModuleWithOpenNI | ( | XnOpenNIModuleInterface * | pInterface,
|  | const XnChar * | strConfigDir,
|  | const XnChar * | strName )

Registers a module to OpenNI in environments where dynamic library loading is not supported.

Parameters

  pInterface | [in] The module interface.
  strConfigDir | [in] The module configuration directory.
  strName | [in] Name of this module.

## xnResolutionGetFromName()

XN_C_API XnResolution XN_C_DECL xnResolutionGetFromName | ( | const XnChar * | strName | ) |

Gets resolution by its name. If resolution is unknown, XN_RESOLUTION_CUSTOM is returned.

Parameters

  strName | [in] Name of the resolution.

## xnResolutionGetFromXYRes()

XN_C_API XnResolution XN_C_DECL xnResolutionGetFromXYRes | ( | XnUInt32 | xRes,
|  | XnUInt32 | yRes )

Gets the resolution from the number of pixels in every row and column.

Parameters

  xRes | [in] Number of pixels in a row.
  yRes | [in] Number of pixels in a column.

## xnResolutionGetName()

XN_C_API const XnChar *XN_C_DECL xnResolutionGetName | ( | XnResolution | resolution | ) |

Get the name of the resolution.

Parameters

  resolution | [in] Resolution.

## xnResolutionGetXRes()

XN_C_API XnUInt32 XN_C_DECL xnResolutionGetXRes | ( | XnResolution | resolution | ) |

Gets the number of pixels in a row for given resolution.

Parameters

  resolution | [in] The resolution to translate.

## xnResolutionGetYRes()

XN_C_API XnUInt32 XN_C_DECL xnResolutionGetYRes | ( | XnResolution | resolution | ) |

Gets the number of pixels in a column for given resolution.

Parameters

  resolution | [in] The resolution to translate.

## xnUnregisterGlobalLicense()

XN_C_API XnStatus XN_C_DECL xnUnregisterGlobalLicense | ( | XnLicense * | pLicense | ) |

## xnUnregisterModule()

XN_C_API XnStatus XN_C_DECL xnUnregisterModule | ( | const XnChar * | strModule | ) |

## xnVersionCompare()

XN_C_API XnInt32 XN_C_DECL xnVersionCompare | ( | const XnVersion * | pVersion1,
|  | const XnVersion * | pVersion2 )

Compares two versions.

Parameters

  pVersion1 | [in] First version.
  pVersion2 | [in] Second version.

Returns
  <0 if first is smaller than second, 0 if same, >0 if first is greater than second.

## xnVersionToString()

XN_C_API XnStatus XN_C_DECL xnVersionToString | ( | const XnVersion * | pVersion,
|  | XnChar * | csResult,
|  | XnUInt32 | nSize )