k4a_device_get_capture()

k4a_wait_result_t k4a_device_get_capture ( k4a_device_t  device_handle, k4a_capture_t *  capture_handle, int32_t  timeout_in_ms  )

related

Reads a sensor capture.

Parameters

device_handle	Handle obtained by k4a_device_open().
capture_handle	If successful this contains a handle to a capture object. Caller must call k4a_capture_release() when its done using this capture.
timeout_in_ms	Specifies the time in milliseconds the function should block waiting for the capture. If set to 0, the function will return without blocking. Passing a value of K4A_WAIT_INFINITE will block indefinitely until data is available, the device is disconnected, or another error occurs.

Returns

K4A_WAIT_RESULT_SUCCEEDED if a capture is returned. If a capture is not available before the timeout elapses, the function will return K4A_WAIT_RESULT_TIMEOUT. All other failures will return K4A_WAIT_RESULT_FAILED.

Remarks

Gets the next capture in the streamed sequence of captures from the camera. If a new capture is not currently available, this function will block until the timeout is reached. The SDK will buffer at least two captures worth of data before dropping the oldest capture. Callers needing to capture all data need to ensure they read the data as fast as the data is being produced on average.

Upon successfully reading a capture this function will return success and populate capture. If a capture is not available in the configured timeout_in_ms, then the API will return K4A_WAIT_RESULT_TIMEOUT.

If the call is successful and a capture is returned, callers must call k4a_capture_release() to return the allocated memory.

This function needs to be called while the device is in a running state; after k4a_device_start_cameras() is called and before k4a_device_stop_cameras() is called.

This function returns an error when an internal problem is encountered; such as loss of the USB connection, inability to allocate enough memory, and other unexpected issues. Any error returned by this function signals the end of streaming data, and caller should stop the stream using k4a_device_stop_cameras().

If this function is waiting for data (non-zero timeout) when k4a_device_stop_cameras() or k4a_device_close() is called on another thread, this function will return an error.

Returns

K4A_WAIT_RESULT_SUCCEEDED if a capture is returned. If a capture is not available before the timeout elapses, the function will return K4A_WAIT_RESULT_TIMEOUT. All other failures will return K4A_WAIT_RESULT_FAILED.