kinect for windows - DepthBasics-D2D详解之三
这篇文章我们将总结一下，之前两篇文章中提到的Kinect SDK的函数接。
函数接口：
NuiGetSensorCount： 获取连接的Kinect设备个数
原型：_Check_return_ HRESULT NUIAPI NuiGetSensorCount( _In_ int * pCount );
解释：KinectSDK支持多个Kinect设备连接，这个函数能获取到Kinect设备个数。
返回值：返回S_OK是成功，其他失败，其中E_POINTER表示pCount是空指针错误。
NuiCreateSensorByIndex：通过索引创建INuiSensor对象
原型：_Check_return_ HRESULT NUIAPI NuiCreateSensorByIndex( _In_ int index, _Out_ INuiSensor ** ppNuiSensor );
解释：通过指定的下标，获取对应的KinectSensor对象
返回值：返回S_OK是成功，其他失败，错误码有：E_INVALIDARG（index是负数），E_NUI_BADINDEX（index超出范围），E_POINTER（ppNuiSensor是空指针）
NuiStatus：获取Kinect设备状态，它是INuiSensor的成员函数
原型：virtual HRESULT STDMETHODCALLTYPE NuiStatus( void) = 0;
解释：当获取到INuiSensor对象时，应该调用这个函数查看Kinect设备状态，如果状态不对，也是不能使用的。
返回值：返回S_OK是正常，其他失败，错误码如下：
| S_NUI_INITIALIZING | The device is connected, but still initializing.设备初始化中 |
| E_NUI_NOTCONNECTED | The device is not connected.设备未连接 |
| E_NUI_NOTGENUINE | The device is not a valid Kinect.不是一个正常的Kinect |
| E_NUI_NOTSUPPORTED | The device is an unsupported model.模式不支持 |
| E_NUI_INSUFFICIENTBANDWIDTH | The device is connected to a hub without the necessary bandwidth requirements.插到usb hub中产生的问题 |
| E_NUI_NOTPOWERED | The device is connected, but unpowered.没插电 |
| E_NUI_NOTREADY | There was some other unspecified error.未知错误 |
NuiInitialize：初始化Kinect设备
原型：virtual HRESULT STDMETHODCALLTYPE NuiInitialize(
/* [in] */ DWORD dwFlags) = 0;
参数：指定初始化模式
| Constant | Description |
|---|---|
| NUI_INITIALIZE_DEFAULT_HARDWARE_THREAD | This flag was deprecated in version 1.5; it is no longer used. |
| NUI_INITIALIZE_FLAG_USES_AUDIO | Initialize the sensor to provide audio data. |
| NUI_INITIALIZE_FLAG_USES_COLOR | Initialize the sensor to provide color data. |
| NUI_INITIALIZE_FLAG_USES_DEPTH | Initialize the sensor to provide depth data. |
| NUI_INITIALIZE_FLAG_USES_DEPTH_AND_PLAYER_INDEX | Initialize the sensor to provide depth data with a player index. |
| NUI_INITIALIZE_FLAG_USES_SKELETON | Initialize the sensor to provide skeleton data. |
解释：一个设备只有第一次调用这个函数时候会成功，其他应用程序再调用这个函数会失败，也就是说一个设备只能给一个程序用。
返回值：S_OK成功，其他失败
NuiImageStreamOpen：打开Kinect流
原型： virtual HRESULT STDMETHODCALLTYPE NuiImageStreamOpen(
/* [in] */ NUI_IMAGE_TYPE eImageType, // 类型
/* [in] */ NUI_IMAGE_RESOLUTION eResolution, // 分辨率
/* [in] */ DWORD dwImageFrameFlags, // 帧事件选项
/* [in] */ DWORD dwFrameLimit, // kinect缓存的帧数量
/* [in] */ HANDLE hNextFrameEvent, // 手动reset的event，当下一帧数据到来时，kinect会reset它
/* [out] */ HANDLE *phStreamHandle) = 0; // 数据流句柄
返回值：S_OK表示成功，其他失败
| 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. |
NuiImageStreamGetNextFrame：取一帧数据
原型：virtual HRESULT STDMETHODCALLTYPE NuiImageStreamGetNextFrame(
/* [in] */ HANDLE hStream, // 数据流
/* [in] */ DWORD dwMillisecondsToWait, // 等待时间
/* [retval][out] */ NUI_IMAGE_FRAME *pImageFrame) = 0; // 保存数据的指针
返回值：S_OK成功，其他失败
| Error | Description |
|---|---|
| S_FALSE | The waiting timeout expired before a frame was available and hStream was opened using the NUI_IMAGE_STREAM_FLAG_SUPPRESS_NO_FRAME_DATA flag. |
| E_INVALIDARG | The value of the hStream parameter is NULL. |
| E_NUI_FRAME_NO_DATA | The waiting timeout expired before a frame was available. |
| E_POINTER | The value of the pImageFrame parameter is NULL. |
NuiImageFrameGetDepthImagePixelFrameTexture：将深度图转化成纹理
原型：virtual HRESULT STDMETHODCALLTYPE NuiImageFrameGetDepthImagePixelFrameTexture(
/* [in] */ HANDLE hStream, // 数据流
/* [in] */ NUI_IMAGE_FRAME *pImageFrame, // 帧数据
/* [out] */ BOOL *pNearMode, // 近模式，如果kinect离物体比较近，一般就会选择近模式
/* [out] */ INuiFrameTexture **ppFrameTexture) = 0; // 输出参数，转换后的纹理
返回值：S_OK成功，其他失败
LockRect：锁住矩形区域数据，让Kinect不要修改那些数据
原型：virtual HRESULT STDMETHODCALLTYPE LockRect(
UINT Level, // 必须为0
NUI_LOCKED_RECT* pLockedRect, // 传出参数，记录矩形
RECT* pRect, // 该参数暂时不用
DWORD flags) = 0; // 该参数暂时不用
返回值：S_OK成功，其他失败
| Error | Description |
|---|---|
| E_INVALIDARG | The Level parameter is not zero. |
| E_OUTOFMEMORY | The texture buffer could not be allocated. |
| E_POINTER | The pLockedRect parameter is NULL or the texture has zero height. |
UnlockRect：解锁
原型：HRESULT UnlockRect(UINT level); // Level参数必须为0
返回值：S_OK成功，其他失败，可能的错误码为E_INVALIDARG（level参数不为0）
| Error | Description |
|---|---|
| S_FALSE | The waiting timeout expired before a frame was available and hStream was opened using the NUI_IMAGE_STREAM_FLAG_SUPPRESS_NO_FRAME_DATA flag. |
| E_INVALIDARG | The value of the hStream parameter is NULL. |
| E_NUI_FRAME_NO_DATA | The waiting timeout expired before a frame was available. |
| E_POINTER | The value of the pImageFrame parameter is NULL. |
