Share via

NuiImageStreamOpen

  • Article

Kinect for Windows 1.5, 1.6, 1.7, 1.8

Opens an image stream.

Syntax

HRESULT NuiImageStreamOpen(
         NUI_IMAGE_TYPE eImageType,
         NUI_IMAGE_RESOLUTION eResolution,
         DWORD dwImageFrameFlags,
         DWORD dwFrameLimit,
         HANDLE hNextFrameEvent,
         HANDLE *phStreamHandle
)

Parameters

  • eImageType
    Type: NUI_IMAGE_TYPE
    [in] A NUI_IMAGE_TYPE value that specifies which image stream to open. The valid values for this parameter depend on the flags that you passed to the dwFlags parameter of the NuiInitialize function; for more information, see the Remarks section.
  • eResolution
    Type: NUI_IMAGE_RESOLUTION
    [in] 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 that you passed to the dwFlags parameter of the NuiInitialize function; for more information, see the remarks section.
  • dwImageFrameFlags
    Type: DWORD
    [in] Specifies the frame event options, as a bitwise-OR combination of the NUI_IMAGE_STREAM_FLAG constants.
  • dwFrameLimit
    Type: DWORD
    [in] The number of frames that the Kinect runtime should buffer. The maximum value is NUI_IMAGE_STREAM_FRAME_LIMIT_MAXIMUM. Most applications should use a frame limit of two.
  • hNextFrameEvent
    Type: HANDLE
    [in, optional] A handle to a manual reset event that will be fired when the next frame in the stream is available.
  • phStreamHandle
    Type: HANDLE
    [out] A pointer that contains a handle to the opened stream. This parameter cannot be NULL.

Return Value

Type: HRESULT
Returns S_OK if successful; otherwise, returns one of the failure codes in the following table.

Error Description
E_FAIL An unspecified error occurred.
E_INVALIDARG The value of the dwFlags parameter is NULL.
E_NUI_DEVICE_NOT_READY Kinect has not been initialized.
E_OUTOFMEMORY The allocation failed.
E_POINTER The hNextFrameEvent parameter is an invalid handle.

Remarks

Note

Calling NuiImageStreamOpen on a stream that is already open does NOT open a new stream; it resets the existing stream with the new settings specified in the NuiImageStreamOpen call.

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.

Warning

As a result, frames can occasionally be dropped.

The valid values for the eImageType and eResolution parameters depend on the values you assigned to the dwFlags parameter of the NuiInitialize method. The following tables show the valid combinations.

  1. If dwFlags includes NUI_INITIALIZE_FLAG_USES_DEPTH.

    NUI_IMAGE_TYPE eImageType value NUI_IMAGE_RESOLUTION eResolution value
    NUI_IMAGE_TYPE_DEPTH NUI_IMAGE_RESOLUTION_640x480 or NUI_IMAGE_RESOLUTION_320x240 or NUI_IMAGE_RESOLUTION_80x60

  2. If dwFlags includes NUI_INITIALIZE_FLAG_USES_DEPTH_AND_PLAYER_INDEX.

    NUI_IMAGE_TYPE eImageType value NUI_IMAGE_RESOLUTION eResolution value
    NUI_IMAGE_TYPE_DEPTH_AND_PLAYER_INDEX NUI_IMAGE_RESOLUTION_320x240 or NUI_IMAGE_RESOLUTION_80x60

  3. If dwFlags includes NUI_INITIALIZE_FLAG_USES_COLOR.

    NUI_IMAGE_TYPE eImageType value NUI_IMAGE_RESOLUTION eResolution value
    NUI_IMAGE_TYPE_COLOR NUI_IMAGE_RESOLUTION_1280x960 or 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

Requirements

Header: Declared in NuiImageCamera.h; however, include NuiApi.h in your project.