Getting the Next Frame of Data by Polling or Using Events

Kinect for Windows 1.5, 1.6, 1.7, 1.8

Application code gets the latest frame of image data (color or depth) by calling a frame retrieval method and passing a buffer. If the latest frame of data is ready, it is copied into the buffer. If the application code requests a frame of data before the new frame is available, an application can either wait for the next frame or return immediately and try again later. The sensor data streams never provide the same frame of data more than once.

Choose one of two models for getting the next frame of data: the polling model or the event model.

Polling Model

The polling model is the simplest option for reading data frames. First, the application code opens the image stream. It then requests a frame and specifies how long to wait for the next frame of data (between 0 and an infinite number of milliseconds). The request method returns when a new frame of data is ready or when the wait time expires, whichever comes first. Specifying an infinite wait causes the call for frame data to block and to wait as long as necessary for the next frame.

When the request returns successfully, the new frame is ready for processing. If the time-out value is set to zero, the application code can poll for completion of a new frame while it performs other work on the same thread. A C++ application calls NuiImageStreamOpen to open a color or depth stream and omits the optional event. To poll for color and depth frames, a C++ application calls NuiImageStreamGetNextFrame and a C# application calls ColorImageStream.OpenNextFrame.

Event Model

The event model supports the ability to integrate retrieval of a skeleton frame into an application engine with more flexibility and more accuracy.

In this model, C++ code passes an event handle to NuiImageStreamOpen to open a color or depth stream. The event handle should be a manual-reset event handle, created by a call to the Windows CreateEvent API. When a new frame of color or depth data is ready, the event is signaled. Any thread waiting on the event handle wakes and gets the frame of color or depth data by calling NuiImageStreamGetNextFrame or skeleton data by calling NuiSkeletonGetNextFrame. During this time, the event is reset by the NUI Image Camera API.

C# code uses the event model by hooking a Kinect.KinectSensor.ColorFrameReady, KinectSensor.DepthFrameReady, or KinectSensor.SkeletonFrameReady event to the appropriate color, depth, or skeleton event handler. When a new frame of data is ready, the event is signaled and the handler runs and calls the ColorImageStream.OpenNextFrame, DepthImageStream.OpenNextFrame, or SkeletonStream.OpenNextFrame method to get the frame.

In summary, here are the APIs to get the next frame of color, depth, and skeleton data for each of the two models.

Task	Polling Model	Event Model
Get next frame in C++	INuiSensor::NuiImageStreamGetNextFrame Method (color, depth), INuiSensor::NuiSkeletonGetNextFrame Method (skeleton)	INuiSensor::NuiSkeletonTrackingEnable Method
Get next frame in C#	ColorImageStream.OpenNextFrame Method, DepthImageStream.OpenNextFrame Method, SkeletonStream.OpenNextFrame Method	KinectSensor.ColorFrameReady Event, KinectSensor.DepthFrameReady Event, KinectSensor.SkeletonFrameReady Event, KinectSensor.AllFramesReady Event