NuiSkeleton.h File Reference

Classes
struct	_Matrix4
struct	_Vector4
struct	_NUI_SKELETON_DATA
struct	_NUI_SKELETON_FRAME
struct	_NUI_TRANSFORM_SMOOTH_PARAMETERS
struct	_NUI_SKELETON_BONE_ROTATION
struct	_NUI_SKELETON_BONE_ORIENTATION

Macros
#define	FLT_EPSILON   1.192092896e-07F /* smallest such that 1.0+FLT_EPSILON != 1.0 */
#define	_Matrix4_
#define	_Vector4_
#define	NUI_SKELETON_COUNT   6
#define	NUI_SKELETON_MAX_TRACKED_COUNT   2
#define	NUI_SKELETON_INVALID_TRACKING_ID   0
#define	NUI_SKELETON_QUALITY_CLIPPED_RIGHT   0x00000001
#define	NUI_SKELETON_QUALITY_CLIPPED_LEFT   0x00000002
#define	NUI_SKELETON_QUALITY_CLIPPED_TOP   0x00000004
#define	NUI_SKELETON_QUALITY_CLIPPED_BOTTOM   0x00000008
#define	NUI_SKELETON_FRAME_FLAG_SEATED_SUPPORT_ENABLED   0x00000008
#define	NUI_SKELETON_TRACKING_FLAG_SUPPRESS_NO_FRAME_DATA   0x00000001
#define	NUI_SKELETON_TRACKING_FLAG_TITLE_SETS_TRACKED_SKELETONS   0x00000002
#define	NUI_SKELETON_TRACKING_FLAG_ENABLE_SEATED_SUPPORT   0x00000004
#define	NUI_SKELETON_TRACKING_FLAG_ENABLE_IN_NEAR_RANGE   0x00000008

Typedefs
typedef struct _Matrix4	Matrix4
typedef struct _Vector4	Vector4
typedef enum _NUI_SKELETON_POSITION_INDEX	NUI_SKELETON_POSITION_INDEX
typedef enum _NUI_SKELETON_POSITION_TRACKING_STATE	NUI_SKELETON_POSITION_TRACKING_STATE
typedef enum _NUI_SKELETON_TRACKING_STATE	NUI_SKELETON_TRACKING_STATE
typedef struct _NUI_SKELETON_DATA	NUI_SKELETON_DATA
typedef struct _NUI_SKELETON_FRAME	NUI_SKELETON_FRAME
typedef struct _NUI_TRANSFORM_SMOOTH_PARAMETERS	NUI_TRANSFORM_SMOOTH_PARAMETERS
typedef struct _NUI_SKELETON_BONE_ROTATION	NUI_SKELETON_BONE_ROTATION
typedef struct _NUI_SKELETON_BONE_ORIENTATION	NUI_SKELETON_BONE_ORIENTATION

Enumerations
enum	_NUI_SKELETON_POSITION_INDEX {   NUI_SKELETON_POSITION_HIP_CENTER = 0, NUI_SKELETON_POSITION_SPINE = ( NUI_SKELETON_POSITION_HIP_CENTER + 1 ), NUI_SKELETON_POSITION_SHOULDER_CENTER = ( NUI_SKELETON_POSITION_SPINE + 1 ), NUI_SKELETON_POSITION_HEAD = ( NUI_SKELETON_POSITION_SHOULDER_CENTER + 1 ),   NUI_SKELETON_POSITION_SHOULDER_LEFT = ( NUI_SKELETON_POSITION_HEAD + 1 ), NUI_SKELETON_POSITION_ELBOW_LEFT = ( NUI_SKELETON_POSITION_SHOULDER_LEFT + 1 ), NUI_SKELETON_POSITION_WRIST_LEFT = ( NUI_SKELETON_POSITION_ELBOW_LEFT + 1 ), NUI_SKELETON_POSITION_HAND_LEFT = ( NUI_SKELETON_POSITION_WRIST_LEFT + 1 ),   NUI_SKELETON_POSITION_SHOULDER_RIGHT = ( NUI_SKELETON_POSITION_HAND_LEFT + 1 ), NUI_SKELETON_POSITION_ELBOW_RIGHT = ( NUI_SKELETON_POSITION_SHOULDER_RIGHT + 1 ), NUI_SKELETON_POSITION_WRIST_RIGHT = ( NUI_SKELETON_POSITION_ELBOW_RIGHT + 1 ), NUI_SKELETON_POSITION_HAND_RIGHT = ( NUI_SKELETON_POSITION_WRIST_RIGHT + 1 ),   NUI_SKELETON_POSITION_HIP_LEFT = ( NUI_SKELETON_POSITION_HAND_RIGHT + 1 ), NUI_SKELETON_POSITION_KNEE_LEFT = ( NUI_SKELETON_POSITION_HIP_LEFT + 1 ), NUI_SKELETON_POSITION_ANKLE_LEFT = ( NUI_SKELETON_POSITION_KNEE_LEFT + 1 ), NUI_SKELETON_POSITION_FOOT_LEFT = ( NUI_SKELETON_POSITION_ANKLE_LEFT + 1 ),   NUI_SKELETON_POSITION_HIP_RIGHT = ( NUI_SKELETON_POSITION_FOOT_LEFT + 1 ), NUI_SKELETON_POSITION_KNEE_RIGHT = ( NUI_SKELETON_POSITION_HIP_RIGHT + 1 ), NUI_SKELETON_POSITION_ANKLE_RIGHT = ( NUI_SKELETON_POSITION_KNEE_RIGHT + 1 ), NUI_SKELETON_POSITION_FOOT_RIGHT = ( NUI_SKELETON_POSITION_ANKLE_RIGHT + 1 ),   NUI_SKELETON_POSITION_COUNT = ( NUI_SKELETON_POSITION_FOOT_RIGHT + 1 ), NUI_SKELETON_POSITION_HIP_CENTER = 0, NUI_SKELETON_POSITION_SPINE, NUI_SKELETON_POSITION_SHOULDER_CENTER,   NUI_SKELETON_POSITION_HEAD, NUI_SKELETON_POSITION_SHOULDER_LEFT, NUI_SKELETON_POSITION_ELBOW_LEFT, NUI_SKELETON_POSITION_WRIST_LEFT,   NUI_SKELETON_POSITION_HAND_LEFT, NUI_SKELETON_POSITION_SHOULDER_RIGHT, NUI_SKELETON_POSITION_ELBOW_RIGHT, NUI_SKELETON_POSITION_WRIST_RIGHT,   NUI_SKELETON_POSITION_HAND_RIGHT, NUI_SKELETON_POSITION_HIP_LEFT, NUI_SKELETON_POSITION_KNEE_LEFT, NUI_SKELETON_POSITION_ANKLE_LEFT,   NUI_SKELETON_POSITION_FOOT_LEFT, NUI_SKELETON_POSITION_HIP_RIGHT, NUI_SKELETON_POSITION_KNEE_RIGHT, NUI_SKELETON_POSITION_ANKLE_RIGHT,   NUI_SKELETON_POSITION_FOOT_RIGHT, NUI_SKELETON_POSITION_COUNT }
enum	_NUI_SKELETON_POSITION_TRACKING_STATE {   NUI_SKELETON_POSITION_NOT_TRACKED = 0, NUI_SKELETON_POSITION_INFERRED = ( NUI_SKELETON_POSITION_NOT_TRACKED + 1 ), NUI_SKELETON_POSITION_TRACKED = ( NUI_SKELETON_POSITION_INFERRED + 1 ), NUI_SKELETON_POSITION_NOT_TRACKED = 0,   NUI_SKELETON_POSITION_INFERRED, NUI_SKELETON_POSITION_TRACKED }
enum	_NUI_SKELETON_TRACKING_STATE {   NUI_SKELETON_NOT_TRACKED = 0, NUI_SKELETON_POSITION_ONLY = ( NUI_SKELETON_NOT_TRACKED + 1 ), NUI_SKELETON_TRACKED = ( NUI_SKELETON_POSITION_ONLY + 1 ), NUI_SKELETON_NOT_TRACKED = 0,   NUI_SKELETON_POSITION_ONLY, NUI_SKELETON_TRACKED }

Functions
	__declspec (selectany) DWORD NuiSkeletonDataSize
_Check_return_ HRESULT NUIAPI	NuiSkeletonTrackingEnable (_In_opt_ HANDLE hNextFrameEvent, _In_ DWORD dwFlags)
	Enables skeleton tracking. More...
_Check_return_ HRESULT NUIAPI	NuiSkeletonTrackingDisable ()
	Disables skeleton tracking. More...
_Check_return_ HRESULT NUIAPI	NuiSkeletonGetNextFrame (_In_ DWORD dwMillisecondsToWait, _Inout_ NUI_SKELETON_FRAME *pSkeletonFrame)
	Gets the next frame of data from the skeleton stream. More...
_Check_return_ HRESULT NUIAPI	NuiSkeletonSetTrackedSkeletons (_In_count_c_(2) DWORD TrackingIDs[2])
	Sets an array of IDs for skeletal tracking. More...
_Check_return_ HRESULT NUIAPI	NuiTransformSmooth (_Inout_ NUI_SKELETON_FRAME *pSkeletonFrame, _In_opt_ CONST NUI_TRANSFORM_SMOOTH_PARAMETERS *pSmoothingParams)
	Filters skeleton positions to reduce jitter between frames. More...
_Check_return_ STDMETHODIMP	NuiSkeletonCalculateBoneOrientations (_In_ const NUI_SKELETON_DATA *pSkeletonData, _Out_cap_c_(NUI_SKELETON_POSITION_COUNT) NUI_SKELETON_BONE_ORIENTATION *pBoneOrientations)
	Calculate bone orientations for a skeleton. More...

Macro Definition Documentation

#define _Matrix4_

Definition at line 24 of file NuiSkeleton.h.

#define _Vector4_

Definition at line 49 of file NuiSkeleton.h.

#define FLT_EPSILON   1.192092896e-07F /* smallest such that 1.0+FLT_EPSILON != 1.0 */

Definition at line 20 of file NuiSkeleton.h.

#define NUI_SKELETON_COUNT   6

Definition at line 108 of file NuiSkeleton.h.

#define NUI_SKELETON_FRAME_FLAG_SEATED_SUPPORT_ENABLED   0x00000008

Definition at line 190 of file NuiSkeleton.h.

#define NUI_SKELETON_INVALID_TRACKING_ID   0

Definition at line 122 of file NuiSkeleton.h.

#define NUI_SKELETON_MAX_TRACKED_COUNT   2

Definition at line 116 of file NuiSkeleton.h.

#define NUI_SKELETON_QUALITY_CLIPPED_BOTTOM   0x00000008

Definition at line 164 of file NuiSkeleton.h.

#define NUI_SKELETON_QUALITY_CLIPPED_LEFT   0x00000002

Definition at line 162 of file NuiSkeleton.h.

#define NUI_SKELETON_QUALITY_CLIPPED_RIGHT   0x00000001

Definition at line 161 of file NuiSkeleton.h.

#define NUI_SKELETON_QUALITY_CLIPPED_TOP   0x00000004

Definition at line 163 of file NuiSkeleton.h.

#define NUI_SKELETON_TRACKING_FLAG_ENABLE_IN_NEAR_RANGE   0x00000008

Definition at line 196 of file NuiSkeleton.h.

#define NUI_SKELETON_TRACKING_FLAG_ENABLE_SEATED_SUPPORT   0x00000004

Definition at line 195 of file NuiSkeleton.h.

#define NUI_SKELETON_TRACKING_FLAG_SUPPRESS_NO_FRAME_DATA   0x00000001

Definition at line 193 of file NuiSkeleton.h.

#define NUI_SKELETON_TRACKING_FLAG_TITLE_SETS_TRACKED_SKELETONS   0x00000002

Definition at line 194 of file NuiSkeleton.h.

Typedef Documentation

typedef struct _Matrix4 Matrix4

typedef struct _NUI_SKELETON_BONE_ORIENTATION NUI_SKELETON_BONE_ORIENTATION

typedef struct _NUI_SKELETON_BONE_ROTATION NUI_SKELETON_BONE_ROTATION

typedef struct _NUI_SKELETON_DATA NUI_SKELETON_DATA

typedef struct _NUI_SKELETON_FRAME NUI_SKELETON_FRAME

typedef enum _NUI_SKELETON_POSITION_INDEX NUI_SKELETON_POSITION_INDEX

typedef enum _NUI_SKELETON_POSITION_TRACKING_STATE NUI_SKELETON_POSITION_TRACKING_STATE

typedef enum _NUI_SKELETON_TRACKING_STATE NUI_SKELETON_TRACKING_STATE

typedef struct _NUI_TRANSFORM_SMOOTH_PARAMETERS NUI_TRANSFORM_SMOOTH_PARAMETERS

typedef struct _Vector4 Vector4

Enumeration Type Documentation

enum _NUI_SKELETON_POSITION_INDEX

Enumerator
NUI_SKELETON_POSITION_HIP_CENTER
NUI_SKELETON_POSITION_SPINE
NUI_SKELETON_POSITION_SHOULDER_CENTER
NUI_SKELETON_POSITION_HEAD
NUI_SKELETON_POSITION_SHOULDER_LEFT
NUI_SKELETON_POSITION_ELBOW_LEFT
NUI_SKELETON_POSITION_WRIST_LEFT
NUI_SKELETON_POSITION_HAND_LEFT
NUI_SKELETON_POSITION_SHOULDER_RIGHT
NUI_SKELETON_POSITION_ELBOW_RIGHT
NUI_SKELETON_POSITION_WRIST_RIGHT
NUI_SKELETON_POSITION_HAND_RIGHT
NUI_SKELETON_POSITION_HIP_LEFT
NUI_SKELETON_POSITION_KNEE_LEFT
NUI_SKELETON_POSITION_ANKLE_LEFT
NUI_SKELETON_POSITION_FOOT_LEFT
NUI_SKELETON_POSITION_HIP_RIGHT
NUI_SKELETON_POSITION_KNEE_RIGHT
NUI_SKELETON_POSITION_ANKLE_RIGHT
NUI_SKELETON_POSITION_FOOT_RIGHT
NUI_SKELETON_POSITION_COUNT
NUI_SKELETON_POSITION_HIP_CENTER
NUI_SKELETON_POSITION_SPINE
NUI_SKELETON_POSITION_SHOULDER_CENTER
NUI_SKELETON_POSITION_HEAD
NUI_SKELETON_POSITION_SHOULDER_LEFT
NUI_SKELETON_POSITION_ELBOW_LEFT
NUI_SKELETON_POSITION_WRIST_LEFT
NUI_SKELETON_POSITION_HAND_LEFT
NUI_SKELETON_POSITION_SHOULDER_RIGHT
NUI_SKELETON_POSITION_ELBOW_RIGHT
NUI_SKELETON_POSITION_WRIST_RIGHT
NUI_SKELETON_POSITION_HAND_RIGHT
NUI_SKELETON_POSITION_HIP_LEFT
NUI_SKELETON_POSITION_KNEE_LEFT
NUI_SKELETON_POSITION_ANKLE_LEFT
NUI_SKELETON_POSITION_FOOT_LEFT
NUI_SKELETON_POSITION_HIP_RIGHT
NUI_SKELETON_POSITION_KNEE_RIGHT
NUI_SKELETON_POSITION_ANKLE_RIGHT
NUI_SKELETON_POSITION_FOOT_RIGHT
NUI_SKELETON_POSITION_COUNT

Definition at line 79 of file NuiSkeleton.h.

{
    NUI_SKELETON_POSITION_HIP_CENTER = 0,
    NUI_SKELETON_POSITION_SPINE,
    NUI_SKELETON_POSITION_SHOULDER_CENTER,
    NUI_SKELETON_POSITION_HEAD,
    NUI_SKELETON_POSITION_SHOULDER_LEFT,
    NUI_SKELETON_POSITION_ELBOW_LEFT,
    NUI_SKELETON_POSITION_WRIST_LEFT,
    NUI_SKELETON_POSITION_HAND_LEFT,
    NUI_SKELETON_POSITION_SHOULDER_RIGHT,
    NUI_SKELETON_POSITION_ELBOW_RIGHT,
    NUI_SKELETON_POSITION_WRIST_RIGHT,
    NUI_SKELETON_POSITION_HAND_RIGHT,
    NUI_SKELETON_POSITION_HIP_LEFT,
    NUI_SKELETON_POSITION_KNEE_LEFT,
    NUI_SKELETON_POSITION_ANKLE_LEFT,
    NUI_SKELETON_POSITION_FOOT_LEFT,
    NUI_SKELETON_POSITION_HIP_RIGHT,
    NUI_SKELETON_POSITION_KNEE_RIGHT,
    NUI_SKELETON_POSITION_ANKLE_RIGHT,
    NUI_SKELETON_POSITION_FOOT_RIGHT,
    NUI_SKELETON_POSITION_COUNT
} NUI_SKELETON_POSITION_INDEX;

enum _NUI_SKELETON_POSITION_TRACKING_STATE

Enumerator
NUI_SKELETON_POSITION_NOT_TRACKED
NUI_SKELETON_POSITION_INFERRED
NUI_SKELETON_POSITION_TRACKED
NUI_SKELETON_POSITION_NOT_TRACKED
NUI_SKELETON_POSITION_INFERRED
NUI_SKELETON_POSITION_TRACKED

Definition at line 125 of file NuiSkeleton.h.

{
    NUI_SKELETON_POSITION_NOT_TRACKED = 0,
    NUI_SKELETON_POSITION_INFERRED,
    NUI_SKELETON_POSITION_TRACKED
} NUI_SKELETON_POSITION_TRACKING_STATE;

enum _NUI_SKELETON_TRACKING_STATE

Enumerator
NUI_SKELETON_NOT_TRACKED
NUI_SKELETON_POSITION_ONLY
NUI_SKELETON_TRACKED
NUI_SKELETON_NOT_TRACKED
NUI_SKELETON_POSITION_ONLY
NUI_SKELETON_TRACKED

Definition at line 132 of file NuiSkeleton.h.

{
    NUI_SKELETON_NOT_TRACKED = 0,
    NUI_SKELETON_POSITION_ONLY,
    NUI_SKELETON_TRACKED
} NUI_SKELETON_TRACKING_STATE;

Function Documentation

__declspec

(

selectany

)

_Check_return_ STDMETHODIMP NuiSkeletonCalculateBoneOrientations	(	_In_ const NUI_SKELETON_DATA *	pSkeletonData,
		_Out_cap_c_(NUI_SKELETON_POSITION_COUNT) NUI_SKELETON_BONE_ORIENTATION *	pBoneOrientations
	)

Calculate bone orientations for a skeleton.

Parameters

pSkeletonData	Pointer to the skeleton data to calculate joint angles for.
pBoneOrientations	Pointer to an array of NUI_SKELETON_BONE_ORIENTATION of dimension NUI_SKELETON_POSITION_COUNT (20). This array must be allocated by the user before calling this function.

Returns

Returns S_OK if successful; otherwise, returns one of the following error codes:

Error code	Description
E_INVALIDARG	The pSkeletonData parameter is NULL.
E_POINTER	The pBoneOrientations parameter is NULL.

S_FALSE The joints required to calculate the skeleton root are not visible. Hierarchical bone rotations are set to Identity.

The function calculates hierarchical and absolute joint angles for the skeleton, which can be used in animating an avatar (Avateering). The HipCenter joint is the root of the hierarchy, and describes an absolute rotation in the right-hand camera coordinate system. All other joints describe rotations relative to their parent joint orientation. The angles are returned in the same order as the joints are defined.

Examples:

_Check_return_ HRESULT NUIAPI NuiSkeletonGetNextFrame	(	_In_ DWORD	dwMillisecondsToWait,
		_Inout_ NUI_SKELETON_FRAME *	pSkeletonFrame
	)

Gets the next frame of data from the skeleton stream.

Parameters

dwMillisecondsToWait	The timeout (in milliseconds) before returning without a new frame.
pSkeletonFrame	A pointer to a NUI_SKELETON_FRAME structure that receives the next image frame in the skeleton stream. This must not be NULL.

Returns

Returns S_OK if successful; otherwise, returns one of the following error codes:

Error code	Description
S_FALSE	The wait timeout expired before a new frame was available and NuiSkeletonTrackingEnable was passed the NUI_SKELETON_TRACKING_FLAG_TITLE_SETS_TRACKED_SKELETONS flag.
E_NUI_FRAME_NO_DATA	The wait timeout expired before a new frame was available.
E_POINTER	The pSkeletonFrame parameter is NULL.

See also

NuiSkeletonTrackingEnable

_Check_return_ HRESULT NUIAPI NuiSkeletonSetTrackedSkeletons

(

_In_count_c_(2) DWORD

TrackingIDs[2]

)

Sets an array of IDs for skeletal tracking.

Parameters

TrackingIDs

A pointer to the first DWORD in an array of tracking IDs, one for each skeleton.

Returns

Returns S_OK if successful; otherwise, returns one of the following error codes:

Error code	Description
E_INVALIDARG	The TrackingIDs parameter is NULL.
E_NUI_STREAM_NOT_ENABLED	The device is uninitialized or the sensor is not initialized with the NUI_INITIALIZE_FLAG_USES_SKELETON flag. NuiInitialize.
E_NUI_FEATURE_NOT_INITIALIZED	Skeletal tracking is not enabled with the NUI_SKELETON_TRACKING_FLAG_TITLE_SETS_TRACKED_SKELETONS flag.

_Check_return_ HRESULT NUIAPI NuiSkeletonTrackingDisable

(

)

Disables skeleton tracking.

Returns

Returns S_OK if successful; otherwise, returns one of the following error codes:

Error code	Description
__HRESULT_FROM_WIN32(ERROR_INVALID_OPERATION)	The device is uninitialized or the sensor is not initialized with the NUI_INITIALIZE_FLAG_USES_SKELETON flag. NuiInitialize.

_Check_return_ HRESULT NUIAPI NuiSkeletonTrackingEnable	(	_In_opt_ HANDLE	hNextFrameEvent,
		_In_ DWORD	dwFlags
	)

Enables skeleton tracking.

Parameters

hNextFrameEvent	A handle to an application-allocated, manual reset event that will be set whenever a new frame of skeleton data is available, and will be reset whenever the latest frame data is returned. This can be NULL.
dwFlags	Flags that control skeleton tracking, as a bitwise-OR combination NUI_SKELETON_TRACKING values.

Returns

Returns S_OK if successful; otherwise, returns one of the following failure codes:

Error code	Description
__HRESULT_FROM_WIN32(ERROR_INVALID_OPERATION)	The device is uninitialized or the sensor is not initialized with the NUI_INITIALIZE_FLAG_USES_SKELETON flag. NuiInitialize.
E_INVALIDARG	The dwFlags parameter includes invalid flags.
E_OUTOFMEMORY	Allocation failed.

The following flags are supported:

NUI_SKELETON_TRACKING_FLAG_SUPPRESS_NO_FRAME_DATA	Prevents NuiSkeletonGetNextFrame from returning E_NUI_FRAME_NO_DATA errors. Instead, calls to NuiSkeletonGetNextFrame block until data is available or the timeout period passes.
NUI_SKELETON_TRACKING_FLAG_TITLE_SETS_TRACKED_SKELETONS	Disables the default player selection mode and enables the title to manage which players have tracked skeletons.
NUI_SKELETON_TRACKING_FLAG_ENABLE_SEATED_SUPPORT	Uses seated skeleton tracking mode. The 10 lower-body joints of each skeleton will not be tracked.

_Check_return_ HRESULT NUIAPI NuiTransformSmooth	(	_Inout_ NUI_SKELETON_FRAME *	pSkeletonFrame,
		_In_opt_ CONST NUI_TRANSFORM_SMOOTH_PARAMETERS *	pSmoothingParams
	)

Filters skeleton positions to reduce jitter between frames.

Parameters

pSkeletonFrame	On entry, points to a NUI_SKELETON_FRAME structure that contains the skeleton data to be smoothed. On exit, the skeleton data in the structure has been replaced by smoothed data. If this function does not return S_OK, this data is unchanged.
pSmoothingParams	The parameters for the smoothing function. See the NUI_TRANSFORM_SMOOTH_PARAMETERS structure for a description of the parameters.

Returns

Returns S_OK if successful; otherwise, returns one of the following error codes:

Error code	Description
E_OUTOFMEMORY	Failed allocation.
E_POINTER	The pSkeletonFrame parameter is NULL.

The filter used is based on the Holt Double Exponential Smoothing method used for statistical analysis of economic data, which provides smoothing with less latency than other smoothing filter algorithms. A single call of this function updates all currently-tracked skeletons.

Go to the source code of this file.