kinect/codes/Azure-Kinect-Sensor-SDK/include/k4ainternal/depth.h

151 lines
5.0 KiB
C
Raw Permalink Normal View History

2024-03-06 18:05:53 +00:00
/** \file depth.h
* Copyright (c) Microsoft Corporation. All rights reserved.
* Licensed under the MIT License.
* Kinect For Azure SDK.
*/
#ifndef DEPTH_H
#define DEPTH_H
#include <k4a/k4atypes.h>
#include <k4ainternal/handle.h>
#include <k4ainternal/depth_mcu.h>
#include <k4ainternal/calibration.h>
#ifdef __cplusplus
extern "C" {
#endif
/** Delivers a sample to the registered callback function when a capture is ready for processing.
*
* \param result
* indicates if the capture being passed in is complete
*
* \param capture_handle
* Capture being read by hardware.
*
* \param callback_context
* Context for the callback function
*
* \remarks
* Capture is only of one type. At this point it is not linked to other captures. Capture is safe to use during this
* callback as the caller ensures a ref is held. If the callback function wants the capture to exist beyond this
* callback, a ref must be taken with capture_inc_ref().
*/
typedef void(depth_cb_streaming_capture_t)(k4a_result_t result, k4a_capture_t capture_handle, void *callback_context);
/** Handle to the depth device.
*
* Handles are created with \ref depth_create and closed
* with \ref depth_destroy.
* Invalid handles are set to 0.
*/
K4A_DECLARE_HANDLE(depth_t);
/** Open a handle to the depth device.
*
* \param depthmcu_handle [IN]
* Handle to the MCU communication module
*
* \param calibration_handle [IN]
* Handle to the calibration module.
*
* \param capture_ready_cb [IN]
* A function pointer to call when new depth captures are ready
*
* \param capture_ready_cb_context [IN]
* A context to go with the depth_capture_ready callback function
*
* \param depth_handle [OUT]
* A pointer to write the opened depth device handle to
*
* \return K4A_RESULT_SUCCEEDED if the device was opened, otherwise an error code
*
* If successful, \ref depth_create will return a depth device handle in the depth
* parameter. This handle grants exclusive access to the device and may be used in
* the other k4a API calls.
*
* When done with the device, close the handle with \ref depth_destroy
*/
k4a_result_t depth_create(depthmcu_t depthmcu_handle,
calibration_t calibration_handle,
depth_cb_streaming_capture_t *capture_ready_cb,
void *capture_ready_cb_context,
depth_t *depth_handle);
/** Closes the handle to the depth device.
*
* \param depth_handle [IN]
* The depth device handle to close
*
* If the sensor was streaming at the time /ref depth_destroy is called, /ref depth_stop will be implicitly called to
* stop the sensor.
*/
void depth_destroy(depth_t depth_handle);
/** Returns the Azure Kinect device serial number.
*
* \param depth_handle [IN]
* The depth device handle.
*
* \param serial_number [IN]
* char array to write to serial number to.
*
* \param serial_number_size [IN OUT]
* [IN] the maximum size of the memory pointed to by /ref serial_number
* [OUT] When used with /ref serial_number set to NULL, this value will represent the minimum allocation size needed for
* this call to succeed.
*
* \return ::K4A_BUFFER_RESULT_SUCCEEDED if the serial number was successfully read and written into /ref serial_number.
* ::K4A_BUFFER_RESULT_TOO_SMALL if the size of serial_number was too small, in this case /ref serial_number_size will
* have been updated with the size needed. ::K4A_BUFFER_RESULT_FAILED if an error was encountered. device was opened,
* otherwise an error code
* *
* If successful, /ref serial_number will contain a NULL terminated string.
*/
k4a_buffer_result_t depth_get_device_serialnum(depth_t depth_handle, char *serial_number, size_t *serial_number_size);
/** Returns the Azure Kinect device versions.
*
* \param depth_handle [IN]
* The depth device handle.
*
* \param version [OUT]
* Pre allocated version structure for the function to write the version info to.
*
* \return ::K4A_RESULT_SUCCEEDED if the verison was successfully from the device and written into /ref version.
* ::K4A_RESULT_FAILED if an error was encountered.
*/
k4a_result_t depth_get_device_version(depth_t depth_handle, k4a_hardware_version_t *version);
/** Starts the depth sensor streaming
*
* \param depth_handle [IN]
* The depth device handle.
*
* \param config [IN]
* The configuration of the depth sensor the user wants the sensor to run in.
*
* \return ::K4A_RESULT_SUCCEEDED if the depth sensor was successfully started. ::K4A_RESULT_FAILED if an error was
* encountered.
*
* call /ref depth_stop when the sensor no longer needs to stream.
*/
k4a_result_t depth_start(depth_t depth_handle, const k4a_device_configuration_t *config);
/** Stops the depth sensor when it has been streaming
*
* \param depth_handle [IN]
* The depth device handle.
*
* Stops depth sensor when it has been running. /ref depth_destroy implicitly calls this API if the sensor is in a
* running state.
*/
void depth_stop(depth_t depth_handle);
#ifdef __cplusplus
}
#endif
#endif /* DEPTH_H */