[−][src]Function k4a_sys::k4a_device_get_capture
pub unsafe extern "C" fn k4a_device_get_capture(
device_handle: k4a_device_t,
capture_handle: *mut k4a_capture_t,
timeout_in_ms: i32
) -> k4a_wait_result_t
Reads a sensor capture.
\param device_handle Handle obtained by k4a_device_open().
\param capture_handle If successful this contains a handle to a capture object. Caller must call k4a_capture_release() when its done using this capture.
\param 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.
\relates k4a_device_t
\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.
\remarks Upon successfully reading a capture this function will return success and populate \p capture. If a capture is not available in the configured \p timeout_in_ms, then the API will return ::K4A_WAIT_RESULT_TIMEOUT.
\remarks If the call is successful and a capture is returned, callers must call k4a_capture_release() to return the allocated memory.
\remarks 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.
\remarks 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().
\remarks 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.
\xmlonly