Classes | |
| struct | _NUI_IMAGE_VIEW_AREA |
| struct | _NUI_LOCKED_RECT |
| struct | _NUI_SURFACE_DESC |
| struct | _NUI_IMAGE_FRAME |
| struct | _NUI_DEPTH_IMAGE_PIXEL |
| struct | _NUI_DEPTH_IMAGE_POINT |
| struct | _NUI_COLOR_IMAGE_POINT |
Typedefs | |
| typedef enum _NUI_IMAGE_TYPE | NUI_IMAGE_TYPE |
| typedef enum _NUI_IMAGE_RESOLUTION | NUI_IMAGE_RESOLUTION |
| typedef enum _NUI_BACKLIGHT_COMPENSATION_MODE | NUI_BACKLIGHT_COMPENSATION_MODE |
| typedef enum _NUI_POWER_LINE_FREQUENCY | NUI_POWER_LINE_FREQUENCY |
| typedef enum _NUI_IMAGE_DIGITALZOOM | NUI_IMAGE_DIGITALZOOM |
| typedef struct _NUI_IMAGE_VIEW_AREA | NUI_IMAGE_VIEW_AREA |
| typedef struct _NUI_LOCKED_RECT | NUI_LOCKED_RECT |
| typedef struct _NUI_SURFACE_DESC | NUI_SURFACE_DESC |
| typedef struct _NUI_IMAGE_FRAME | NUI_IMAGE_FRAME |
| typedef struct _NUI_DEPTH_IMAGE_PIXEL | NUI_DEPTH_IMAGE_PIXEL |
| typedef struct _NUI_DEPTH_IMAGE_POINT | NUI_DEPTH_IMAGE_POINT |
| typedef struct _NUI_COLOR_IMAGE_POINT | NUI_COLOR_IMAGE_POINT |
Functions | |
| void | NuiImageResolutionToSize (_In_ NUI_IMAGE_RESOLUTION res, _Out_ DWORD &refWidth, _Out_ DWORD &refHeight) |
| Converts the resolution to a size. More... | |
| USHORT | NuiDepthPixelToDepth (USHORT packedPixel) |
| USHORT | NuiDepthPixelToPlayerIndex (USHORT packedPixel) |
| _Check_return_ HRESULT NUIAPI | NuiImageStreamSetImageFrameFlags (_In_ HANDLE hStream, _In_ DWORD dwImageFrameFlags) |
| Sets the image frame flags for the specified stream. More... | |
| _Check_return_ HRESULT NUIAPI | NuiImageStreamGetImageFrameFlags (_In_ HANDLE hStream, _Out_ DWORD *pdwImageFrameFlags) |
| Gets the image frame flags for the specified stream. More... | |
| _Check_return_ HRESULT NUIAPI | NuiSetFrameEndEvent (_In_ HANDLE hEvent, _In_ DWORD dwFrameEventFlag) |
| Sets the event that signals the last frame. More... | |
| _Check_return_ HRESULT NUIAPI | NuiImageStreamOpen (_In_ NUI_IMAGE_TYPE eImageType, _In_ NUI_IMAGE_RESOLUTION eResolution, _In_ DWORD dwImageFrameFlags, _In_ DWORD dwFrameLimit, _In_opt_ HANDLE hNextFrameEvent, _Out_ HANDLE *phStreamHandle) |
| Opens an image stream. More... | |
| _Check_return_ HRESULT NUIAPI | NuiImageStreamGetNextFrame (_In_ HANDLE hStream, _In_ DWORD dwMillisecondsToWait, _Deref_out_ CONST NUI_IMAGE_FRAME **ppcImageFrame) |
| Gets the next frame of data from the specified image stream. More... | |
| _Check_return_ HRESULT NUIAPI | NuiImageStreamReleaseFrame (_In_ HANDLE hStream, _In_ CONST NUI_IMAGE_FRAME *pImageFrame) |
| Releases the specified frame of data from the specified stream. More... | |
| _Check_return_ HRESULT NUIAPI | NuiImageGetColorPixelCoordinatesFromDepthPixel (_In_ NUI_IMAGE_RESOLUTION eColorResolution, _In_opt_ CONST NUI_IMAGE_VIEW_AREA *pcViewArea, _In_ LONG lDepthX, _In_ LONG lDepthY, _In_ USHORT usDepthValue, _Out_ LONG *plColorX, _Out_ LONG *plColorY) |
| Gets the pixel coordinates in color space that correspond to the specified pixel coordinates in depth space. More... | |
| _Check_return_ HRESULT NUIAPI | NuiImageGetColorPixelCoordinatesFromDepthPixelAtResolution (_In_ NUI_IMAGE_RESOLUTION eColorResolution, _In_ NUI_IMAGE_RESOLUTION eDepthResolution, _In_opt_ CONST NUI_IMAGE_VIEW_AREA *pcViewArea, _In_ LONG lDepthX, _In_ LONG lDepthY, _In_ USHORT usDepthValue, _Out_ LONG *plColorX, _Out_ LONG *plColorY) |
| Gets the pixel coordinates in color space that correspond to the specified pixel coordinates in depth space, using the specified depth resolution. More... | |
| _Check_return_ HRESULT NUIAPI | NuiCameraElevationGetAngle (_Out_ LONG *plAngleDegrees) |
| Gets the elevation angle of the Kinect sensor. More... | |
| _Check_return_ HRESULT NUIAPI | NuiCameraElevationSetAngle (_In_ LONG lAngleDegrees) |
| Sets the elevation angle of the Kinect sensor. More... | |
| #define _NUI_BACKLIGHT_COMPENSATION_MODE_ |
Definition at line 48 of file NuiImageCamera.h.
| #define _NUI_COLOR_IMAGE_POINT_ |
Definition at line 242 of file NuiImageCamera.h.
| #define _NUI_DEPTH_IMAGE_PIXEL_ |
Definition at line 214 of file NuiImageCamera.h.
| #define _NUI_DEPTH_IMAGE_POINT_ |
Definition at line 227 of file NuiImageCamera.h.
| #define _NUI_IMAGE_FRAME_ |
Definition at line 200 of file NuiImageCamera.h.
| #define _NUI_IMAGE_RESOLUTION_ |
Definition at line 36 of file NuiImageCamera.h.
| #define _NUI_IMAGE_TYPE_ |
Definition at line 22 of file NuiImageCamera.h.
| #define _NUI_IMAGE_VIEW_AREA_ |
Definition at line 158 of file NuiImageCamera.h.
| #define _NUI_LOCKED_RECT_ |
Definition at line 177 of file NuiImageCamera.h.
| #define _NUI_POWER_LINE_FREQUENCY_ |
Definition at line 60 of file NuiImageCamera.h.
| #define _NUI_SURFACE_DESC_ |
Definition at line 188 of file NuiImageCamera.h.
| #define NUI_CAMERA_COLOR_NOMINAL_DIAGONAL_FOV ( 73.9f) |
Definition at line 128 of file NuiImageCamera.h.
| #define NUI_CAMERA_COLOR_NOMINAL_FOCAL_LENGTH_IN_PIXELS (531.15f) |
Definition at line 126 of file NuiImageCamera.h.
| #define NUI_CAMERA_COLOR_NOMINAL_HORIZONTAL_FOV ( 62.0f) |
Definition at line 129 of file NuiImageCamera.h.
| #define NUI_CAMERA_COLOR_NOMINAL_INVERSE_FOCAL_LENGTH_IN_PIXELS (1.83e-3f) |
Definition at line 127 of file NuiImageCamera.h.
| #define NUI_CAMERA_COLOR_NOMINAL_VERTICAL_FOV ( 48.6f) |
Definition at line 130 of file NuiImageCamera.h.
| #define NUI_CAMERA_DEPTH_NOMINAL_DIAGONAL_FOV (70.0f) |
Definition at line 122 of file NuiImageCamera.h.
| #define NUI_CAMERA_DEPTH_NOMINAL_FOCAL_LENGTH_IN_PIXELS (285.63f) |
Definition at line 120 of file NuiImageCamera.h.
| #define NUI_CAMERA_DEPTH_NOMINAL_HORIZONTAL_FOV (58.5f) |
Definition at line 123 of file NuiImageCamera.h.
| #define NUI_CAMERA_DEPTH_NOMINAL_INVERSE_FOCAL_LENGTH_IN_PIXELS (3.501e-3f) |
Definition at line 121 of file NuiImageCamera.h.
| #define NUI_CAMERA_DEPTH_NOMINAL_VERTICAL_FOV (45.6f) |
Definition at line 124 of file NuiImageCamera.h.
| #define NUI_CAMERA_ELEVATION_MAXIMUM 27 |
Definition at line 768 of file NuiImageCamera.h.
| #define NUI_CAMERA_ELEVATION_MINIMUM (-27) |
Definition at line 769 of file NuiImageCamera.h.
| #define NUI_DEPTH_DEPTH_UNKNOWN_VALUE NUI_IMAGE_DEPTH_UNKNOWN_VALUE |
Definition at line 114 of file NuiImageCamera.h.
| #define NUI_DEPTH_UNKNOWN 0 |
Definition at line 117 of file NuiImageCamera.h.
| #define NUI_IMAGE_DEPTH_MAXIMUM ((4000 << NUI_IMAGE_PLAYER_INDEX_SHIFT) | NUI_IMAGE_PLAYER_INDEX_MASK) |
Definition at line 107 of file NuiImageCamera.h.
| #define NUI_IMAGE_DEPTH_MAXIMUM_NEAR_MODE ((3000 << NUI_IMAGE_PLAYER_INDEX_SHIFT) | NUI_IMAGE_PLAYER_INDEX_MASK) |
Definition at line 109 of file NuiImageCamera.h.
| #define NUI_IMAGE_DEPTH_MINIMUM (800 << NUI_IMAGE_PLAYER_INDEX_SHIFT) |
Definition at line 108 of file NuiImageCamera.h.
| #define NUI_IMAGE_DEPTH_MINIMUM_NEAR_MODE (400 << NUI_IMAGE_PLAYER_INDEX_SHIFT) |
Definition at line 110 of file NuiImageCamera.h.
| #define NUI_IMAGE_DEPTH_NO_VALUE 0 |
Definition at line 111 of file NuiImageCamera.h.
| #define NUI_IMAGE_DEPTH_TOO_FAR_VALUE (0x0fff << NUI_IMAGE_PLAYER_INDEX_SHIFT) |
Definition at line 112 of file NuiImageCamera.h.
| #define NUI_IMAGE_DEPTH_UNKNOWN_VALUE (0x1fff << NUI_IMAGE_PLAYER_INDEX_SHIFT) |
Definition at line 113 of file NuiImageCamera.h.
| #define NUI_IMAGE_FRAME_FLAG_NEAR_MODE_ENABLED 0x00020000 |
Definition at line 172 of file NuiImageCamera.h.
| #define NUI_IMAGE_FRAME_FLAG_NONE 0x00000000 |
Definition at line 170 of file NuiImageCamera.h.
| #define NUI_IMAGE_FRAME_FLAG_VIEW_AREA_UNKNOWN 0x00000001 |
Definition at line 171 of file NuiImageCamera.h.
| #define NUI_IMAGE_PLAYER_INDEX_MASK ((1 << NUI_IMAGE_PLAYER_INDEX_SHIFT)-1) |
Definition at line 106 of file NuiImageCamera.h.
| #define NUI_IMAGE_PLAYER_INDEX_SHIFT 3 |
Definition at line 105 of file NuiImageCamera.h.
| #define NUI_IMAGE_STREAM_FLAG_DISTINCT_OVERFLOW_DEPTH_VALUES 0x00040000 |
Definition at line 262 of file NuiImageCamera.h.
| #define NUI_IMAGE_STREAM_FLAG_ENABLE_NEAR_MODE 0x00020000 |
Definition at line 260 of file NuiImageCamera.h.
| #define NUI_IMAGE_STREAM_FLAG_SUPPRESS_NO_FRAME_DATA 0x00010000 |
Definition at line 258 of file NuiImageCamera.h.
| #define NUI_IMAGE_STREAM_FRAME_LIMIT_MAXIMUM 4 |
Definition at line 265 of file NuiImageCamera.h.
| #define NUI_PIXEL_COORDINATE_UNKNOWN INT_MIN |
Definition at line 118 of file NuiImageCamera.h.
| typedef struct _NUI_COLOR_IMAGE_POINT NUI_COLOR_IMAGE_POINT |
| typedef struct _NUI_DEPTH_IMAGE_PIXEL NUI_DEPTH_IMAGE_PIXEL |
| typedef struct _NUI_DEPTH_IMAGE_POINT NUI_DEPTH_IMAGE_POINT |
| typedef enum _NUI_IMAGE_DIGITALZOOM NUI_IMAGE_DIGITALZOOM |
| typedef struct _NUI_IMAGE_FRAME NUI_IMAGE_FRAME |
| typedef enum _NUI_IMAGE_RESOLUTION NUI_IMAGE_RESOLUTION |
| typedef enum _NUI_IMAGE_TYPE NUI_IMAGE_TYPE |
| typedef struct _NUI_IMAGE_VIEW_AREA NUI_IMAGE_VIEW_AREA |
| typedef struct _NUI_LOCKED_RECT NUI_LOCKED_RECT |
| typedef enum _NUI_POWER_LINE_FREQUENCY NUI_POWER_LINE_FREQUENCY |
| typedef struct _NUI_SURFACE_DESC NUI_SURFACE_DESC |
Definition at line 49 of file NuiImageCamera.h.
| Enumerator | |
|---|---|
| NUI_IMAGE_DIGITAL_ZOOM_1X | |
Definition at line 149 of file NuiImageCamera.h.
Definition at line 37 of file NuiImageCamera.h.
| enum _NUI_IMAGE_TYPE |
Definition at line 23 of file NuiImageCamera.h.
| Enumerator | |
|---|---|
| NUI_POWER_LINE_FREQUENCY_DISABLED | |
| NUI_POWER_LINE_FREQUENCY_50HZ | |
| NUI_POWER_LINE_FREQUENCY_60HZ | |
| NUI_POWER_LINE_FREQUENCY_DISABLED | |
| NUI_POWER_LINE_FREQUENCY_50HZ | |
| NUI_POWER_LINE_FREQUENCY_60HZ | |
Definition at line 61 of file NuiImageCamera.h.
| _Check_return_ HRESULT NUIAPI NuiCameraElevationGetAngle | ( | _Out_ LONG * | plAngleDegrees | ) |
Gets the elevation angle of the Kinect sensor.
| plAngleDegrees | Pointer to a LONG which receives the angle of the sensor in degrees. |
| Error code | Description |
|---|---|
| E_NUI_DEVICE_NOT_READY | The device is uninitialized. NuiInitialize. |
| E_POINTER | The plAngleDegrees parameter is NULL. |
An elevation angle of zero indicates that the Kinect sensor is pointing perpendicular to gravity. The tilt is relative to gravity rather than relative to the sensor base. The angle is subject to the physical limitations of the sensor. If the sensor base is resting on a tilted surface, the middle of the sensor's tilt range will not correspond to a tilt angle of zero, and the sensor may not be physically capable of reaching the outer limits of the range allowed by the API. If the sensor is moved so that the base is at a different angle relative to gravity, or if the sensor is tilted manually, the angle reported by the API will change, even if the tilt angle has not been changed programmatically.
| _Check_return_ HRESULT NUIAPI NuiCameraElevationSetAngle | ( | _In_ LONG | lAngleDegrees | ) |
Sets the elevation angle of the Kinect sensor.
| lAngleDegrees | The elevation angle relative to gravity, in degrees. A value of zero indicates that the sensor array should point exactly horizontally. Positive values indicate that the sensor array should point above the horizon, and negative values indicate that the sensor array should point below the horizon. This value is constrained between NUI_CAMERA_ELEVATION_MINIMUM and NUI_CAMERA_ELEVATION_MAXIMUM. |
| Error code | Description |
|---|---|
| __HRESULT_FROM_WIN32(ERROR_TOO_MANY_CMDS) | There were too many calls to NuiCameraElevationSetAngle within a given timespan. |
| __HRESULT_FROM_WIN32(ERROR_RETRY) | There was too little time between subsequent NuiCameraElevationSetAngle calls. |
| E_NUI_DEVICE_NOT_READY | The device is uninitialized. NuiInitialize. |
You should tilt the Kinect sensor as few times as possible, to minimize wear on the sensor and to minimize tilting time. The tilt motor is not designed for constant or repetitive movement, and attempts to use it that way can cause degradation of motor function. To reduce wear on the Kinect sensor's tilt motor, your application can change the elevation angle no more than once per second. In addition, you must allow at least 20 seconds of rest after 15 consecutive changes. If your application exceeds these limits, additional attempts to set the elevation angle during the lockout period will result in an error code.
An elevation angle of zero indicates that the Kinect sensor is pointing perpendicular to gravity. The tilt is relative to gravity rather than relative to the sensor base. The angle is subject to the physical limitations of the sensor. If the sensor base is resting on a tilted surface, the middle of the sensor's tilt range will not correspond to a tilt angle of zero, and the sensor may not be physically capable of reaching the outer limits of the range allowed by the API. If the sensor is moved so that the base is at a different angle relative to gravity, or if the sensor is tilted manually, the angle reported by the API will change, even if the tilt angle has not been changed programmatically.
|
inline |
Definition at line 136 of file NuiImageCamera.h.
|
inline |
Definition at line 144 of file NuiImageCamera.h.
| _Check_return_ HRESULT NUIAPI NuiImageGetColorPixelCoordinatesFromDepthPixel | ( | _In_ NUI_IMAGE_RESOLUTION | eColorResolution, |
| _In_opt_ CONST NUI_IMAGE_VIEW_AREA * | pcViewArea, | ||
| _In_ LONG | lDepthX, | ||
| _In_ LONG | lDepthY, | ||
| _In_ USHORT | usDepthValue, | ||
| _Out_ LONG * | plColorX, | ||
| _Out_ LONG * | plColorY | ||
| ) |
Gets the pixel coordinates in color space that correspond to the specified pixel coordinates in depth space.
| eColorResolution | The resolution of the color image, as a NUI_IMAGE_RESOLUTION enumeration constant. |
| pcViewArea | The optional zoom and pan settings of the color image, as a pointer to a NUI_IMAGE_VIEW_AREA structure. To ensure that the settings are valid, use the ViewArea member of the NUI_IMAGE_FRAME that you are registering pixels against. Do not instantiate and populate this structure manually. |
| lDepthX | The X coordinate in depth image space. |
| lDepthY | The Y coordinate in depth image space. |
| usDepthValue | The depth value in depth image space. This value is constrained between NUI_IMAGE_DEPTH_MINIMUM and NUI_IMAGE_DEPTH_MAXIMUM. |
| plColorX | Pointer to a LONG value that receives the X coordinate of the pixel in color image space. This pointer must be non-NULL when you call this function. If this method does not return S_OK, this data is invalid. This value can be outside of the bounds of the color image. |
| plColorY | Pointer to a LONG value that receives the Y coordinate of the pixel in color image space. This pointer must be non-NULL when you call this function. If this method does not return S_OK, this data is invalid. This value can be outside of the bounds of the color image. |
| Error code | Description |
|---|---|
| E_INVALIDARG | The eColorResolution parameter does not specify a valid resolution, or pcViewArea is provided but does not describe the full frame. |
| E_NUI_DEVICE_NOT_READY | The device is uninitialized. NuiInitialize. |
| E_POINTER | The plColorX or plColorY parameter is NULL. |
Because depth image data and color image data come from separate sensors, pixels in the two images may not always line up exactly. The two sensors may have different fields of view, or may not be aimed precisely in the same direction. This means that a point near the edge of the depth image may correspond to a pixel just beyond the edge of the color image, or vice versa.
This function accepts coordinates outside the bounds of the depth image. It may return pixels outside the color image. This means that you can use data from the two images in combination, even when the two images do not line up completely. You must verify that the coordinates that are returned lie within the color image before using the coordinates to reference pixels in that color image.
The depth image coordinates you specify are not required to be within the bounds of the depth frame image, but they should not be too far outside the depth frame image bounds. If the coordinates are far outside the depth frame image, they are unlikely to map to coordinates inside the bounds of the color image. This function will then return color image coordinates that are unlikely to be useful.
| _Check_return_ HRESULT NUIAPI NuiImageGetColorPixelCoordinatesFromDepthPixelAtResolution | ( | _In_ NUI_IMAGE_RESOLUTION | eColorResolution, |
| _In_ NUI_IMAGE_RESOLUTION | eDepthResolution, | ||
| _In_opt_ CONST NUI_IMAGE_VIEW_AREA * | pcViewArea, | ||
| _In_ LONG | lDepthX, | ||
| _In_ LONG | lDepthY, | ||
| _In_ USHORT | usDepthValue, | ||
| _Out_ LONG * | plColorX, | ||
| _Out_ LONG * | plColorY | ||
| ) |
Gets the pixel coordinates in color space that correspond to the specified pixel coordinates in depth space, using the specified depth resolution.
| eColorResolution | The resolution of the color image, as a NUI_IMAGE_RESOLUTION enumeration constant. |
| eDepthResolution | The resolution of the depth image, as a NUI_IMAGE_RESOLUTION enumeration constant. |
| pcViewArea | The optional zoom and pan settings of the color image, as a pointer to a NUI_IMAGE_VIEW_AREA structure. To ensure that the settings are valid, use the ViewArea member of the NUI_IMAGE_FRAME that you are registering pixels against. Do not instantiate and populate this structure manually. |
| lDepthX | The X coordinate in depth image space. |
| lDepthY | The Y coordinate in depth image space. |
| usDepthValue | The depth value in depth image space. This value is constrained between NUI_IMAGE_DEPTH_MINIMUM and NUI_IMAGE_DEPTH_MAXIMUM. |
| plColorX | Pointer to a LONG value that receives the X coordinate of the pixel in color image space. This pointer must be non-NULL when you call this function. If this method does not return S_OK, this data is invalid. This value can be outside of the bounds of the color image. |
| plColorY | Pointer to a LONG value that receives the Y coordinate of the pixel in color image space. This pointer must be non-NULL when you call this function. If this method does not return S_OK, this data is invalid. This value can be outside of the bounds of the color image. |
| Error code | Description |
|---|---|
| E_INVALIDARG | The eColorResolution or eDepthResolution parameter does not specify a valid resolution, or pcViewArea is provided but does not describe the full frame. |
| E_NUI_DEVICE_NOT_READY | The device is uninitialized. NuiInitialize. |
| E_POINTER | The plColorX or plColorY parameter is NULL. |
Because depth image data and color image data come from separate sensors, pixels in the two images may not always line up exactly. The two sensors may have different fields of view, or may not be aimed precisely in the same direction. This means that a point near the edge of the depth image may correspond to a pixel just beyond the edge of the color image, or vice versa.
This function accepts coordinates outside the bounds of the depth image. It may return pixels outside the color image. This means that you can use data from the two images in combination, even when the two images do not line up completely. You must verify that the coordinates that are returned lie within the color image before using the coordinates to reference pixels in that color image.
The depth image coordinates you specify are not required to be within the bounds of the depth frame image, but they should not be too far outside the depth frame image bounds. If the coordinates are far outside the depth frame image, they are unlikely to map to coordinates inside the bounds of the color image. This function will then return color image coordinates that are unlikely to be useful.
|
inline |
Converts the resolution to a size.
| res | The image resolution. |
| refWidth | The width of the image. |
| refHeight | The height of the image. |
Definition at line 78 of file NuiImageCamera.h.
| _Check_return_ HRESULT NUIAPI NuiImageStreamGetImageFrameFlags | ( | _In_ HANDLE | hStream, |
| _Out_ DWORD * | pdwImageFrameFlags | ||
| ) |
Gets the image frame flags for the specified stream.
| hStream | A handle to the stream. |
| pdwImageFrameFlags | A pointer to a DWORD that receives the image frame flags. |
| Error code | Description |
|---|---|
| E_INVALIDARG | The hStream parameter is NULL. |
| E_NUI_DEVICE_NOT_READY | The device is uninitialized. NuiInitialize. |
| E_POINTER | The pdwImageFrameFlags parameter is NULL. |
| _Check_return_ HRESULT NUIAPI NuiImageStreamGetNextFrame | ( | _In_ HANDLE | hStream, |
| _In_ DWORD | dwMillisecondsToWait, | ||
| _Deref_out_ CONST NUI_IMAGE_FRAME ** | ppcImageFrame | ||
| ) |
Gets the next frame of data from the specified image stream.
| hStream | A handle to the image stream. This stream must have been opened by a call to the NuiImageStreamOpen method. |
| dwMillisecondsToWait | The timeout (in milliseconds) before returning without a new frame. |
| pImageFrame | A pointer to a NUI_IMAGE_FRAME structure that receives the next image frame in the specified stream. The pFrameTexture member of the structure points to an INuiFrameTexture instance that contains the frame data. |
| Error code | Description |
|---|---|
| S_FALSE | The wait timeout expired before a new frame was available and hStream was opened with the NUI_IMAGE_STREAM_FLAG_SUPPRESS_NO_FRAME_DATA flag. |
| E_INVALIDARG | The hStream parameter is NULL. |
| E_NUI_FRAME_NO_DATA | The wait timeout expired before a new frame was available. |
| E_POINTER | The pImageFrame parameter is NULL. |
| _Check_return_ HRESULT NUIAPI NuiImageStreamOpen | ( | _In_ NUI_IMAGE_TYPE | eImageType, |
| _In_ NUI_IMAGE_RESOLUTION | eResolution, | ||
| _In_ DWORD | dwImageFrameFlags, | ||
| _In_ DWORD | dwFrameLimit, | ||
| _In_opt_ HANDLE | hNextFrameEvent, | ||
| _Out_ HANDLE * | phStreamHandle | ||
| ) |
Opens an image stream.
| eImageType | A NUI_IMAGE_TYPE value that specifies which image stream to open. The valid values for this parameter depend on the flags passed to the NuiInitialize method; for more information see remarks. |
| eResolution | A NUI_IMAGE_RESOLUTION value that specifies which resolution to use for the image stream. The valid values for this parameter depend on the flags passed to the NuiInitialize method; for more information, see remarks. |
| dwImageFrameFlags | The stream options, as a bitwise-OR combination of the NUI_IMAGE_STREAM_FLAG constants. |
| dwFrameLimit | The number of frames that the NUI runtime should buffer. The maximum value is NUI_IMAGE_STREAM_FRAME_LIMIT_MAXIMUM. Most applications should use a frame limit of two. |
| hNextFrameEvent | A handle to a manual reset event that will be fired when the next frame in the stream is available. |
| phStreamHandle | A pointer that receives a handle to the opened stream. This must not be NULL. |
| Error code | Description |
|---|---|
| E_INVALIDARG | The dwFrameLimit parameter is out of range. |
| E_NUI_DEVICE_NOT_READY | The device has not been initialized. NuiInitialize. |
| E_OUTOFMEMORY | The hEvent parameter is an invalid handle. |
| E_POINTER | The hEvent parameter is an invalid handle. |
| E_FAIL | An unspecified error occurred. |
The NUI runtime buffers the number of frames specified by the dwFrameLimit parameter. If the application does not retrieve and release a frame before the buffer is full, the runtime replaces the oldest frame in the buffer with an incoming frame. As a result, frames can occasionally be dropped.
The valid values for the eImageType and eResolution parameters depend on the NUI initialization flags passed to the NuiInitialize method in the dwFlags parameter. The following tables summarize the combinations that are currently valid.
If dwFlags includes NUI_INITIALIZE_FLAG_USES_DEPTH:
NUI_IMAGE_TYPE value NUI_IMAGE_RESOLUTION value NUI_IMAGE_TYPE_DEPTH NUI_IMAGE_RESOLUTION_640x480 NUI_IMAGE_TYPE_DEPTH NUI_IMAGE_RESOLUTION_320x240 NUI_IMAGE_TYPE_DEPTH NUI_IMAGE_RESOLUTION_80x60
If dwFlags includes NUI_INITIALIZE_FLAG_USES_DEPTH_AND_PLAYER_INDEX:
NUI_IMAGE_TYPE value NUI_IMAGE_RESOLUTION value NUI_IMAGE_TYPE_DEPTH_AND_PLAYER_INDEX NUI_IMAGE_RESOLUTION_320x240 NUI_IMAGE_TYPE_DEPTH_AND_PLAYER_INDEX NUI_IMAGE_RESOLUTION_80x60
If dwFlags includes NUI_INITIALIZE_FLAG_USES_COLOR:
NUI_IMAGE_TYPE value NUI_IMAGE_RESOLUTION value NUI_IMAGE_TYPE_COLOR NUI_IMAGE_RESOLUTION_1280x960 NUI_IMAGE_TYPE_COLOR NUI_IMAGE_RESOLUTION_640x480 NUI_IMAGE_TYPE_COLOR_YUV NUI_IMAGE_RESOLUTION_640x480 NUI_IMAGE_TYPE_COLOR_RAW_YUV NUI_IMAGE_RESOLUTION_640x480 NUI_IMAGE_TYPE_COLOR_INFRARED NUI_IMAGE_RESOLUTION_640x480
| _Check_return_ HRESULT NUIAPI NuiImageStreamReleaseFrame | ( | _In_ HANDLE | hStream, |
| _In_ CONST NUI_IMAGE_FRAME * | pImageFrame | ||
| ) |
Releases the specified frame of data from the specified stream.
| hStream | A handle to the image stream. This stream must have been opened by a call to the NuiImageStreamOpen method. |
| pImageFrame | A pointer to the frame to release. |
| Error code | Description |
|---|---|
| E_INVALIDARG | The hStream or pImageFrame parameter is NULL. |
| E_NOINTERFACE | The pImageFrame parameter's pFrameTexture member is NULL. |
| E_NUI_DEVICE_NOT_READY | The device is uninitialized. NuiInitialize. |
Before you call this function, reset the notification event for the stream.
| _Check_return_ HRESULT NUIAPI NuiImageStreamSetImageFrameFlags | ( | _In_ HANDLE | hStream, |
| _In_ DWORD | dwImageFrameFlags | ||
| ) |
Sets the image frame flags for the specified stream.
| hStream | A handle to the stream. |
| dwImageFrameFlags | The image frame flags, as a bitwise-OR combination of the NUI_IMAGE_STREAM_FLAG constants. |
| Error code | Description |
|---|---|
| E_INVALIDARG | The hStream parameter is NULL. |
| E_NUI_DEVICE_NOT_READY | The device is uninitialized. NuiInitialize. |
The maximum number of output frames you can set is defined by NUI_IMAGE_STREAM_FRAME_LIMIT_MAXIMUM.
| _Check_return_ HRESULT NUIAPI NuiSetFrameEndEvent | ( | _In_ HANDLE | hEvent, |
| _In_ DWORD | dwFrameEventFlag | ||
| ) |
Sets the event that signals the last frame.
| hEvent | A handle to the event. |
| dwFrameEventFlag | The frame event options, as a bitwise-OR combination of the NUI_IMAGE_STREAM_FLAG constants. |
| Error code | Description |
|---|---|
| E_INVALIDARG | The hEvent parameter is an invalid handle. |
If the frame does not process any data, the event is still signaled unless you specify NUI_FRAME_EVENT_FLAG_SUPPRESS_NO_FRAME_DATA.
The event provided is signaled after the NUI runtime is finished processing all data associated with a frame. When you use NuiImageStreamGetNextFrame and NuiSkeletonGetNextFrame, all stream data generated in that frame is available before the event is signaled.
This event is never reset by the NUI runtime because there is not a well-defined time to do so. This is unlike the events provided to NuiImageStreamOpen and NuiSkeletonTrackingEnable. Similarly, proper operation requires an auto-reset event, instead of a manual reset event.
When pumping multiple streams with a single thread, you should use a NuiSetFrameEndEvent event over separate per-stream events.
The flag NUI_IMAGE_STREAM_FLAG_SUPPRESS_NO_FRAME_DATA still applies on a per-stream basis when you call NuiImageStreamGetNextFrame provided you specify that flag for the stream in NuiImageStreamOpen.
The flag NUI_SKELETON_TRACKING_FLAG_SUPPRESS_NO_FRAME_DATA still applies on a per-stream basis when you call NuiSkeletonGetNextFrame provided you specify that flag for the stream in NuiSkeletonTrackingEnable.
When processing multiple streams on multiple threads, it's more efficient to create a separate event for each stream instead of using NuiSetFrameEndEvent. Using separate events ensures that the app doesn't have to wait until processing for skeleton tracking is done before it can get color and depth data.
For signaling when skeleton data is available, use an event in NuiSkeletonTrackingEnable. For signaling when an image stream is available, use an event in NuiImageStreamOpen.