text: /** \file k4a.h
   * Copyright (c) Microsoft Corporation. All rights reserved.
   * Licensed under the MIT License.
   * Kinect For Azure SDK.
   */
  
  #ifndef K4A_H
  #define K4A_H
  
  #ifdef __cplusplus
  #include <cinttypes>
  #else
  #include <inttypes.h>
  #endif
  #include <k4a/k4aversion.h>
  #include <k4a/k4atypes.h>
  #include <k4a/k4a_export.h>
  
  #ifdef __cplusplus
  extern "C" {
  #endif
  
  /**
   * \defgroup Functions Functions
   * \ingroup csdk
   *
   * Public functions of the API
   *
   * @{
   */
  
  /** Gets the number of connected devices
   *
   * \returns Number of sensors connected to the PC.
   *
   * \relates k4a_device_t
   *
   * \remarks
   * This API counts the number of Azure Kinect devices connected to the host PC.
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT uint32_t k4a_device_get_installed_count(void);
  
  /** Sets and clears the callback function to receive debug messages from the Azure Kinect device.
   *
   * \param message_cb
   * The callback function to receive messages from. Set to NULL to unregister the callback function.
   *
   * \param message_cb_context
   * The callback functions context.
   *
   * \param min_level
   * The least critical error the user wants to be notified about.
   *
   * \return ::K4A_RESULT_SUCCEEDED if the callback function was set or cleared successfully. ::K4A_RESULT_FAILED if an
   * error is encountered or the callback function has already been set. ::K4A_RESULT_UNSUPPORTED if the operation is
   * not supported.
   *
   * \remarks
   * Call this function to set or clear the callback function that is used to deliver debug messages to the caller. This
   * callback may be called concurrently, it is up to the implementation of the callback function to ensure the
   * parallelization is handled.
   *
   * \remarks
   * Clearing the callback function will block until all pending calls to the callback function have completed.
   *
   * \remarks
   * To update \p min_level, \p k4a_set_debug_message_handler can be called with the same value \p message_cb and by
   * specifying a new \p min_level.
   *
   * \remarks
   * Logging provided via this API is independent of the logging controlled by the environmental variable controls \p
   * K4A_ENABLE_LOG_TO_STDOUT, \p K4A_ENABLE_LOG_TO_A_FILE, and \p K4A_LOG_LEVEL. However there is a slight change in
   * default behavior when using this function. By default, when \p k4a_set_debug_message_handler() has not been used to
   * register a message callback, the default for environmental variable controls is to send debug messages as if
   * K4A_ENABLE_LOG_TO_STDOUT=1 were set. If \p k4a_set_debug_message_handler registers a callback function before
   * k4a_device_open() is called, then the default for environmental controls is as if K4A_ENABLE_LOG_TO_STDOUT=0 was
   * specified. Physically specifying the environmental control will override the default.
   *
   * \p min_level
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_set_debug_message_handler(k4a_logging_message_cb_t *message_cb,
                                                        void *message_cb_context,
                                                        k4a_log_level_t min_level);
  
  /** Sets the callback functions for the SDK allocator
   *
   * \param allocate
   * The callback function to allocate memory. When the SDK requires memory allocation this callback will be
   * called and the application can provide a buffer and a context.
   *
   * \param free
   * The callback function to free memory. The SDK will call this function when memory allocated by \p allocate
   * is no longer needed.
   *
   * \return ::K4A_RESULT_SUCCEEDED if the callback function was set or cleared successfully. ::K4A_RESULT_FAILED if an
   * error is encountered or the callback function has already been set. ::K4A_RESULT_UNSUPPORTED if the operation is
   * not supported.
   *
   * \remarks
   * Call this function to hook memory allocation by the SDK. Calling with both \p allocate and \p free as NULL will
   * clear the hook and reset to the default allocator.
   *
   * \remarks
   * If this function is called after memory has been allocated, the previous version of \p free function may still be
   * called in the future. The SDK will always call the \p free function that was set at the time that the memory
   * was allocated.
   *
   * \remarks
   * Not all memory allocation by the SDK is performed by this allocate function. Small allocations or allocations
   * from special pools may come from other sources.
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_set_allocator(k4a_memory_allocate_cb_t allocate, k4a_memory_destroy_cb_t free);
  
  /** Get the device info and capabilities.
   *
   * \param device_handle
   * Handle obtained by k4a_device_open().
   *
   * \param device_info
   * Location to write the device info.
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED if \p device info was successfully written. ::K4A_RESULT_FAILED otherwise.
   *
   * \remarks
   * The device info output contains the vendor id, the device id and available capabilities.
   *
   * \sa k4a_device_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_device_get_info(k4a_device_t device_handle, k4a_device_info_t *device_info);
  
  /** Get the number of valid color modes.
   *
   * \param device_handle
   * Handle obtained by k4a_device_open().
   *
   * \param mode_count
   * Location to write the color mode count.
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED if \p mode count was successfully retrieved. ::K4A_RESULT_FAILED otherwise.
   *
   * \remarks
   * The mode count output is the number of available color modes for the device specified by device_handle.
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_device_get_color_mode_count(k4a_device_t device_handle, uint32_t *mode_count);
  
  /** Get the color mode info for a specified index.
   *
   * \param device_handle
   * Handle obtained by k4a_device_open().
   *
   * \param mode_index
   * The index of the color mode to get.
   *
   * \param mode_info
   * Location to write the color mode info.
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED if \p mode info was successfully retrieved. ::K4A_RESULT_FAILED otherwise.
   *
   * \sa k4a_color_mode_info_t
   *
   * \sa k4a_device_get_color_mode_count
   *
   * \remarks
   * The mode_index parameter has valid values [0, N-1] where N is the value returned by
   * k4a_device_get_color_mode_count().
   *
   * \remarks
   * The color mode info output contains image resolution, native image format, horizontal and vertical fov and min and
   * max fps.
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_device_get_color_mode(k4a_device_t device_handle,
                                                    uint32_t mode_index,
                                                    k4a_color_mode_info_t *mode_info);
  
  /** Get the number of valid depth modes.
   *
   * \param device_handle
   * Handle obtained by k4a_device_open().
   *
   * \param mode_count
   * Location to write the depth mode count.
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED if \p mode count was successfully retrieved. ::K4A_RESULT_FAILED otherwise.
   *
   * \remarks
   * The mode count output is the number of available depth modes for the device specified by device_handle.
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_device_get_depth_mode_count(k4a_device_t device_handle, uint32_t *mode_count);
  
  /** Get the depth mode info for a specified index.
   *
   * \param device_handle
   * Handle obtained by k4a_device_open().
   *
   * \param mode_index
   * The index of the color mode to get.
   *
   * \param mode_info
   * Location to write the depth mode info.
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED if \p mode info was successfully retrieved. ::K4A_RESULT_FAILED otherwise.
   *
   * \sa k4a_depth_mode_info_t
   *
   * \sa k4a_device_get_depth_mode_count
   *
   * \remarks
   * The mode_index parameter has valid values [0, N-1] where N is the value returned by
   * k4a_device_get_depth_mode_count().
   *
   * \remarks
   * The depth mode info output contains image resolution, image native format, horizontal and vertical fov, min and max
   * fps, min and max range and whether it is passive ir only.
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_device_get_depth_mode(k4a_device_t device_handle,
                                                    uint32_t mode_index,
                                                    k4a_depth_mode_info_t *mode_info);
  
  /** Get the number of valid fps modes.
   *
   * \param device_handle
   * Handle obtained by k4a_device_open().
   *
   * \param mode_count
   * Location to write the fps mode count.
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED if \p mode count was successfully retrieved. ::K4A_RESULT_FAILED otherwise.
   *
   * \remarks
   * The mode count output is the number of available fps modes for the device specified by device_handle.
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_device_get_fps_mode_count(k4a_device_t device_handle, uint32_t *mode_count);
  
  /** Get the fps mode info for a specified index.
   *
   * \param device_handle
   * Handle obtained by k4a_device_open().
   *
   * \param mode_index
   * The index of the color mode to get.
   *
   * \param mode_info
   * Location to write the fps mode info.
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED if \p mode info was successfully retrieved. ::K4A_RESULT_FAILED otherwise.
   *
   * \sa k4a_fps_mode_info_t
   *
   * \sa k4a_device_get_fps_mode_count
   *
   * \remarks
   * The mode_index parameter has valid values [0, N-1] where N is the value returned by k4a_device_get_fps_mode_count().
   *
   * \remarks
   * The fps mode info contains the frame rate per second.
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_device_get_fps_mode(k4a_device_t device_handle,
                                                  uint32_t mode_index,
                                                  k4a_fps_mode_info_t *mode_info);
  
  /** Open an Azure Kinect device.
   *
   * \param index
   * The index of the device to open, starting with 0. Optionally pass in #K4A_DEVICE_DEFAULT.
   *
   * \param device_handle
   * Output parameter which on success will return a handle to the device.
   *
   * \relates k4a_device_t
   *
   * \return ::K4A_RESULT_SUCCEEDED if the device was opened successfully. ::K4A_RESULT_FAILED if the device was
   * not opened successfully.
   *
   * \remarks
   * If successful, k4a_device_open() will return a device handle in the device_handle parameter.
   * This handle grants exclusive access to the device and may be used in the other Azure Kinect API calls.
   *
   * \remarks
   * When done with the device, close the handle with k4a_device_close()
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_device_open(uint32_t index, k4a_device_t *device_handle);
  
  /** Closes an Azure Kinect device.
   *
   * \param device_handle
   * Handle obtained by k4a_device_open().
   *
   * \relates k4a_device_t
   *
   * \remarks Once closed, the handle is no longer valid.
   *
   * \remarks Before closing the handle to the device, ensure that all \ref k4a_capture_t captures have been released with
   * k4a_capture_release().
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT void k4a_device_close(k4a_device_t device_handle);
  
  /** 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
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   *
   */
  K4A_EXPORT k4a_wait_result_t k4a_device_get_capture(k4a_device_t device_handle,
                                                      k4a_capture_t *capture_handle,
                                                      int32_t timeout_in_ms);
  
  /** Reads an IMU sample.
   *
   * \param device_handle
   * Handle obtained by k4a_device_open().
   *
   * \param imu_sample
   * Pointer to the location for the API to write the IMU sample.
   *
   * \param timeout_in_ms
   * Specifies the time in milliseconds the function should block waiting for the sample. 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 sample is returned. If a sample is not available before the timeout elapses, the
   * function will return ::K4A_WAIT_RESULT_TIMEOUT. If a device does not support an IMU, then
   * ::K4A_WAIT_RESULT_UNSUPPORTED is returned. All other failures will return ::K4A_WAIT_RESULT_FAILED.
   *
   * \relates k4a_device_t
   *
   * \remarks
   * Gets the next sample in the streamed sequence of IMU samples from the device. If a new sample is not currently
   * available, this function will block until the timeout is reached. The API will buffer at least two camera capture
   * intervals worth of samples before dropping the oldest sample. 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 sample this function will return success and populate \p imu_sample.
   * If a sample is not available in the configured \p timeout_in_ms, then the API will return ::K4A_WAIT_RESULT_TIMEOUT.
   *
   * \remarks
   * This function needs to be called while the device is in a running state;
   * after k4a_device_start_imu() is called and before k4a_device_stop_imu() 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_imu().
   *
   * \remarks
   * If this function is waiting for data (non-zero timeout) when k4a_device_stop_imu() or k4a_device_close() is
   * called on another thread, this function will return an error.
   *
   * \remarks
   * The memory the IMU sample is written to is allocated and owned by the caller, so there is no need to call an Azure
   * Kinect API to free or release the sample.
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_wait_result_t k4a_device_get_imu_sample(k4a_device_t device_handle,
                                                         k4a_imu_sample_t *imu_sample,
                                                         int32_t timeout_in_ms);
  
  /** Create an empty capture object.
   *
   * \param capture_handle
   * Pointer to a location to store the handle.
   *
   * \relates k4a_capture_t
   *
   * \remarks
   * Call this function to create a \ref k4a_capture_t handle for a new capture. Release it with k4a_capture_release().
   *
   * The new capture is created with a reference count of 1.
   *
   * \returns
   * Returns #K4A_RESULT_SUCCEEDED on success. Errors are indicated with #K4A_RESULT_FAILED and error specific data can be
   * found in the log.
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_capture_create(k4a_capture_t *capture_handle);
  
  /** Release a capture.
   *
   * \param capture_handle
   * Capture to release.
   *
   * \relates k4a_capture_t
   *
   * \remarks
   * Call this function when finished using the capture.
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT void k4a_capture_release(k4a_capture_t capture_handle);
  
  /** Add a reference to a capture.
   *
   * \param capture_handle
   * Capture to add a reference to.
   *
   * \relates k4a_capture_t
   *
   * \remarks
   * Call this function to add an additional reference to a capture. This reference must be removed with
   * k4a_capture_release().
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT void k4a_capture_reference(k4a_capture_t capture_handle);
  
  /** Get the color image associated with the given capture.
   *
   * \param capture_handle
   * Capture handle containing the image.
   *
   * \relates k4a_capture_t
   *
   * \remarks
   * Call this function to access the color image part of this capture. Release the \ref k4a_image_t with
   * k4a_image_release();
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_image_t k4a_capture_get_color_image(k4a_capture_t capture_handle);
  
  /** Get the depth image associated with the given capture.
   *
   * \param capture_handle
   * Capture handle containing the image.
   *
   * \relates k4a_capture_t
   *
   * \remarks
   * Call this function to access the depth image part of this capture. Release the \ref k4a_image_t with
   * k4a_image_release();
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_image_t k4a_capture_get_depth_image(k4a_capture_t capture_handle);
  
  /** Get the IR image associated with the given capture.
   *
   * \param capture_handle
   * Capture handle containing the image.
   *
   * \relates k4a_capture_t
   *
   * \remarks
   * Call this function to access the IR image part of this capture. Release the \ref k4a_image_t with
   * k4a_image_release();
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_image_t k4a_capture_get_ir_image(k4a_capture_t capture_handle);
  
  /** Set or add a color image to the associated capture.
   *
   * \param capture_handle
   * Capture handle to hold the image.
   *
   * \param image_handle
   * Image handle containing the image.
   *
   * \relates k4a_capture_t
   *
   * \remarks
   * When a \ref k4a_image_t is added to a \ref k4a_capture_t, the \ref k4a_capture_t will automatically add a reference
   * to the \ref k4a_image_t.
   *
   * \remarks
   * If there is already a color image contained in the capture, the existing image will be dereferenced and replaced with
   * the new image.
   *
   * \remarks
   * To remove a color image to the capture without adding a new image, this function can be called with a NULL
   * image_handle.
   *
   * \remarks
   * Any \ref k4a_image_t contained in this \ref k4a_capture_t will automatically be dereferenced when all references to
   * the \ref k4a_capture_t are released with k4a_capture_release().
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT void k4a_capture_set_color_image(k4a_capture_t capture_handle, k4a_image_t image_handle);
  
  /** Set or add a depth image to the associated capture.
   *
   * \param capture_handle
   * Capture handle to hold the image.
   *
   * \param image_handle
   * Image handle containing the image.
   *
   * \relates k4a_capture_t
   *
   * \remarks
   * When a \ref k4a_image_t is added to a \ref k4a_capture_t, the \ref k4a_capture_t will automatically add a reference
   * to the \ref k4a_image_t.
   *
   * \remarks
   * If there is already an image depth image contained in the capture, the existing image will be dereferenced and
   * replaced with the new image.
   *
   * \remarks
   * To remove a depth image to the capture without adding a new image, this function can be called with a NULL
   * image_handle.
   *
   * \remarks
   * Any \ref k4a_image_t contained in this \ref k4a_capture_t will automatically be dereferenced when all references to
   * the \ref k4a_capture_t are released with k4a_capture_release().
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT void k4a_capture_set_depth_image(k4a_capture_t capture_handle, k4a_image_t image_handle);
  
  /** Set or add an IR image to the associated capture.
   *
   * \param capture_handle
   * Capture handle to hold the image.
   *
   * \param image_handle
   * Image handle containing the image.
   *
   * \relates k4a_capture_t
   *
   * \remarks
   * When a \ref k4a_image_t is added to a \ref k4a_capture_t, the \ref k4a_capture_t will automatically add a reference
   * to the \ref k4a_image_t.
   *
   * \remarks
   * If there is already an IR image contained in the capture, the existing image will be dereferenced and replaced with
   * the new image.
   *
   * \remarks
   * To remove a IR image to the capture without adding a new image, this function can be called with a NULL image_handle.
   *
   * \remarks
   * Any \ref k4a_image_t contained in this \ref k4a_capture_t will automatically be dereferenced when all references to
   * the \ref k4a_capture_t are released with k4a_capture_release().
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT void k4a_capture_set_ir_image(k4a_capture_t capture_handle, k4a_image_t image_handle);
  
  /** Set the temperature associated with the capture.
   *
   * \param capture_handle
   * Capture handle to set the temperature on.
   *
   * \param temperature_c
   * Temperature in Celsius to store.
   *
   * \relates k4a_capture_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT void k4a_capture_set_temperature_c(k4a_capture_t capture_handle, float temperature_c);
  
  /** Get the temperature associated with the capture.
   *
   * \param capture_handle
   * Capture handle to retrieve the temperature from.
   *
   * \return
   * This function returns the temperature of the device at the time of the capture in Celsius. If
   * the temperature is unavailable, the function will return NAN.
   *
   * \relates k4a_capture_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT float k4a_capture_get_temperature_c(k4a_capture_t capture_handle);
  
  /** Create an image.
   *
   * \param format
   * The format of the image that will be stored in this image container.
   *
   * \param width_pixels
   * Width in pixels.
   *
   * \param height_pixels
   * Height in pixels.
   *
   * \param stride_bytes
   * The number of bytes per horizontal line of the image.
   * If set to 0, the stride will be set to the minimum size given the \p format and \p width_pixels.
   *
   * \param image_handle
   * Pointer to store image handle in.
   *
   * \remarks
   * This function is used to create images of formats that have consistent stride. The function is not suitable for
   * compressed formats that may not be represented by the same number of bytes per line.
   *
   * \remarks
   * For most image formats, the function will allocate an image buffer of size \p height_pixels * \p stride_bytes.
   * Buffers #K4A_IMAGE_FORMAT_COLOR_NV12 format will allocate an additional \p height_pixels / 2 set of lines (each of \p
   * stride_bytes). This function cannot be used to allocate #K4A_IMAGE_FORMAT_COLOR_MJPG buffers.
   *
   * \remarks
   * To create an image object without the API allocating memory, or to represent an image that has a non-deterministic
   * stride, use k4a_image_create_from_buffer().
   *
   * \remarks
   * The \ref k4a_image_t is created with a reference count of 1.
   *
   * \remarks
   * When finished using the created image, release it with k4a_image_release.
   *
   * \returns
   * Returns #K4A_RESULT_SUCCEEDED on success. Errors are indicated with #K4A_RESULT_FAILED.
   *
   * \relates k4a_image_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_image_create(k4a_image_format_t format,
                                           int width_pixels,
                                           int height_pixels,
                                           int stride_bytes,
                                           k4a_image_t *image_handle);
  
  /** Create an image from a pre-allocated buffer.
   *
   * \param format
   * The format of the image that will be stored in this image container.
   *
   * \param width_pixels
   * Width in pixels.
   *
   * \param height_pixels
   * Height in pixels.
   *
   * \param stride_bytes
   * The number of bytes per horizontal line of the image.
   *
   * \param buffer
   * Pointer to a pre-allocated image buffer.
   *
   * \param buffer_size
   * Size in bytes of the pre-allocated image buffer.
   *
   * \param buffer_release_cb
   * Callback to the buffer free function, called when all references to the buffer have been released. This parameter is
   * optional.
   *
   * \param buffer_release_cb_context
   * Context for the buffer free function. This value will be called as a parameter to \p buffer_release_cb when
   * the callback is invoked.
   *
   * \param image_handle
   * Pointer to store image handle in.
   *
   * \remarks
   * This function creates a \ref k4a_image_t from a pre-allocated buffer. When all references to this object reach zero
   * the provided \p buffer_release_cb callback function is called so that the memory can be released. If this function
   * fails, the API will not use the memory provided in \p buffer, and the API will not call \p buffer_release_cb.
   *
   * \remarks
   * The \ref k4a_image_t is created with a reference count of 1.
   *
   * \remarks
   * Release the reference on this function with k4a_image_release().
   *
   * \returns
   * Returns #K4A_RESULT_SUCCEEDED on success. Errors are indicated with #K4A_RESULT_FAILED and error specific data can be
   * found in the log.
   *
   * \relates k4a_image_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_image_create_from_buffer(k4a_image_format_t format,
                                                       int width_pixels,
                                                       int height_pixels,
                                                       int stride_bytes,
                                                       uint8_t *buffer,
                                                       size_t buffer_size,
                                                       k4a_memory_destroy_cb_t *buffer_release_cb,
                                                       void *buffer_release_cb_context,
                                                       k4a_image_t *image_handle);
  
  /** Get the image buffer.
   *
   * \param image_handle
   * Handle of the image for which the get operation is performed on.
   *
   * \remarks
   * Use this buffer to access the raw image data.
   *
   * \returns
   * The function will return NULL if there is an error, and will normally return a pointer to the image buffer.
   * Since all \ref k4a_image_t instances are created with an image buffer, this function should only return NULL if the
   * \p image_handle is invalid.
   *
   * \relates k4a_image_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT uint8_t *k4a_image_get_buffer(k4a_image_t image_handle);
  
  /** Get the image buffer size.
   *
   * \param image_handle
   * Handle of the image for which the get operation is performed on.
   *
   * \remarks
   * Use this function to know what the size of the image buffer is returned by k4a_image_get_buffer().
   *
   * \returns
   * The function will return 0 if there is an error, and will normally return the image size.
   * Since all \ref k4a_image_t instances are created with an image buffer, this function should only return 0 if the
   * \p image_handle is invalid.
   *
   * \relates k4a_image_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT size_t k4a_image_get_size(k4a_image_t image_handle);
  
  /** Get the format of the image.
   *
   * \param image_handle
   * Handle of the image for which the get operation is performed on.
   *
   * \remarks
   * Use this function to determine the format of the image buffer.
   *
   * \returns
   * This function is not expected to fail, all \ref k4a_image_t's are created with a known format. If the
   * \p image_handle is invalid, the function will return ::K4A_IMAGE_FORMAT_CUSTOM.
   *
   * \relates k4a_image_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_image_format_t k4a_image_get_format(k4a_image_t image_handle);
  
  /** Get the image width in pixels.
   *
   * \param image_handle
   * Handle of the image for which the get operation is performed on.
   *
   * \returns
   * This function is not expected to fail, all \ref k4a_image_t's are created with a known width. If the \p
   * image_handle is invalid, the function will return 0.
   *
   * \relates k4a_image_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT int k4a_image_get_width_pixels(k4a_image_t image_handle);
  
  /** Get the image height in pixels.
   *
   * \param image_handle
   * Handle of the image for which the get operation is performed on.
   *
   * \returns
   * This function is not expected to fail, all \ref k4a_image_t's are created with a known height. If the \p
   * image_handle is invalid, the function will return 0.
   *
   * \relates k4a_image_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT int k4a_image_get_height_pixels(k4a_image_t image_handle);
  
  /** Get the image stride in bytes.
   *
   * \param image_handle
   * Handle of the image for which the get operation is performed on.
   *
   * \returns
   * This function is not expected to fail, all \ref k4a_image_t's are created with a known stride. If the
   * \p image_handle is invalid, or the image's format does not have a stride, the function will return 0.
   *
   * \relates k4a_image_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT int k4a_image_get_stride_bytes(k4a_image_t image_handle);
  
  /** Get the image's device timestamp in microseconds.
   *
   * \param image_handle
   * Handle of the image for which the get operation is performed on.
   *
   * \remarks
   * Returns the device timestamp of the image. Timestamps are recorded by the device and represent the mid-point of
   * exposure. They may be used for relative comparison, but their absolute value has no defined meaning.
   *
   * \returns
   * If the \p image_handle is invalid or if no timestamp was set for the image,
   * this function will return 0. It is also possible for 0 to be a valid timestamp originating from the beginning
   * of a recording or the start of streaming.
   *
   * \deprecated
   * Deprecated starting in 1.2.0. Please use k4a_image_get_device_timestamp_usec().
   *
   * \relates k4a_image_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_DEPRECATED_EXPORT uint64_t k4a_image_get_timestamp_usec(k4a_image_t image_handle);
  
  /** Get the image's device timestamp in microseconds.
   *
   * \param image_handle
   * Handle of the image for which the get operation is performed on.
   *
   * \remarks
   * Returns the device timestamp of the image, as captured by the hardware. Timestamps are recorded by the device and
   * represent the mid-point of exposure. They may be used for relative comparison, but their absolute value has no
   * defined meaning.
   *
   * \returns
   * If the \p image_handle is invalid or if no timestamp was set for the image, this function will return 0. It is also
   * possible for 0 to be a valid timestamp originating from the beginning of a recording or the start of streaming.
   *
   * \relates k4a_image_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT uint64_t k4a_image_get_device_timestamp_usec(k4a_image_t image_handle);
  
  /** Get the image's system timestamp in nanoseconds.
   *
   * \param image_handle
   * Handle of the image for which the get operation is performed on.
   *
   * \remarks
   * Returns the system timestamp of the image. Timestamps are recorded by the host. They may be used for relative
   * comparision, as they are relative to the corresponding system clock. The absolute value is a monotonic count from
   * an arbitrary point in the past.
   *
   * \remarks
   * The system timestamp is captured at the moment host PC finishes receiving the image.
   *
   * \remarks
   * On Linux the system timestamp is read from clock_gettime(CLOCK_MONOTONIC), which measures realtime and is not
   * impacted by adjustments to the system clock. It starts from an arbitrary point in the past. On Windows the system
   * timestamp is read from QueryPerformanceCounter(), it also measures realtime and is not impacted by adjustments to the
   * system clock. It also starts from an arbitrary point in the past.
   *
   * \returns
   * If the \p image_handle is invalid or if no timestamp was set for the image, this function will return 0. It is also
   * possible for 0 to be a valid timestamp originating from the beginning of a recording or the start of streaming.
   *
   * \relates k4a_image_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT uint64_t k4a_image_get_system_timestamp_nsec(k4a_image_t image_handle);
  
  /** Get the image exposure in microseconds.
   *
   * \param image_handle
   * Handle of the image for which the get operation is performed on.
   *
   * \remarks
   * Returns an exposure time in microseconds. This is only supported on color image formats.
   *
   * \returns
   * If the \p image_handle is invalid, or no exposure was set on the image, the function will return 0. Otherwise,
   * it will return the image exposure time in microseconds.
   *
   * \relates k4a_image_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT uint64_t k4a_image_get_exposure_usec(k4a_image_t image_handle);
  
  /** Get the image white balance.
   *
   * \param image_handle
   * Handle of the image for which the get operation is performed on.
   *
   * \remarks
   * Returns the image's white balance. This function is only valid for color captures, and not for depth or IR captures.
   *
   * \returns
   * Returns the image white balance in Kelvin. If \p image_handle is invalid, or the white balance was not set or
   * not applicable to the image, the function will return 0.
   *
   * \relates k4a_image_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT uint32_t k4a_image_get_white_balance(k4a_image_t image_handle);
  
  /** Get the image ISO speed.
   *
   * \param image_handle
   * Handle of the image for which the get operation is performed on.
   *
   * \remarks
   * This function is only valid for color captures, and not for depth  or IR captures.
   *
   * \returns
   * Returns the ISO speed of the image. 0 indicates the ISO speed was not available or an error occurred.
   *
   * \relates k4a_image_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT uint32_t k4a_image_get_iso_speed(k4a_image_t image_handle);
  
  /** Set the device time stamp, in microseconds, of the image.
   *
   * \param image_handle
   * Handle of the image to set the timestamp on.
   *
   * \param timestamp_usec
   * Device timestamp of the image in microseconds.
   *
   * \remarks
   * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a
   * \ref k4a_image_t.
   *
   * \remarks
   * The device timestamp represents the mid-point of exposure of the image, as captured by the hardware.
   *
   * \relates k4a_image_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT void k4a_image_set_device_timestamp_usec(k4a_image_t image_handle, uint64_t timestamp_usec);
  
  /** Set the device time stamp, in microseconds, of the image.
   *
   * \param image_handle
   * Handle of the image to set the timestamp on.
   *
   * \param timestamp_usec
   * Device timestamp of the image in microseconds.
   *
   * \remarks
   * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a
   * \ref k4a_image_t.
   *
   * \remarks
   * The device timestamp represents the mid-point of exposure of the image, as captured by the hardware.
   *
   * \relates k4a_image_t
   *
   * \deprecated
   * Deprecated starting in 1.2.0. Please use k4a_image_set_device_timestamp_usec().
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_DEPRECATED_EXPORT void k4a_image_set_timestamp_usec(k4a_image_t image_handle, uint64_t timestamp_usec);
  
  /** Set the system time stamp, in nanoseconds, of the image.
   *
   * \param image_handle
   * Handle of the image to set the timestamp on.
   *
   * \param timestamp_nsec
   * Timestamp of the image in nanoseconds.
   *
   * \remarks
   * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a
   * \ref k4a_image_t.
   *
   * \remarks
   * The system timestamp is a high performance and increasing clock (from boot). The timestamp represents the time
   * immediately after the image buffer was read by the host PC.
   *
   * \relates k4a_image_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT void k4a_image_set_system_timestamp_nsec(k4a_image_t image_handle, uint64_t timestamp_nsec);
  
  /** Set the exposure time, in microseconds, of the image.
   *
   * \param image_handle
   * Handle of the image to set the exposure time on.
   *
   * \param exposure_usec
   * Exposure time of the image in microseconds.
   *
   * \remarks
   * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a
   * \ref k4a_image_t. An exposure time of 0 is considered invalid. Only color image formats are expected to have a valid
   * exposure time.
   *
   * \relates k4a_image_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT void k4a_image_set_exposure_usec(k4a_image_t image_handle, uint64_t exposure_usec);
  
  /** Set the exposure time, in microseconds, of the image.
   *
   * \param image_handle
   * Handle of the image to set the exposure time on.
   *
   * \param exposure_usec
   * Exposure time of the image in microseconds.
   *
   * \remarks
   * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a
   * \ref k4a_image_t. An exposure time of 0 is considered invalid. Only color image formats are expected to have a valid
   * exposure time.
   *
   * \deprecated
   * Deprecated starting in 1.2.0. Please use k4a_image_set_exposure_usec().
   *
   * \relates k4a_image_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_DEPRECATED_EXPORT void k4a_image_set_exposure_time_usec(k4a_image_t image_handle, uint64_t exposure_usec);
  
  /** Set the white balance of the image.
   *
   * \param image_handle
   * Handle of the image to set the white balance on.
   *
   * \param white_balance
   * White balance of the image in degrees Kelvin.
   *
   * \remarks
   * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a
   * \ref k4a_image_t. A white balance of 0 is considered invalid. White balance is only meaningful for color images,
   * and not expected on depth or IR images.
   *
   * \relates k4a_image_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT void k4a_image_set_white_balance(k4a_image_t image_handle, uint32_t white_balance);
  
  /** Set the ISO speed of the image.
   *
   * \param image_handle
   * Handle of the image to set the ISO speed on.
   *
   * \param iso_speed
   * ISO speed of the image.
   *
   * \remarks
   * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a
   * \ref k4a_image_t. An ISO speed of 0 is considered invalid. Only color images are expected to have a valid ISO speed.
   *
   * \relates k4a_image_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT void k4a_image_set_iso_speed(k4a_image_t image_handle, uint32_t iso_speed);
  
  /** Add a reference to the k4a_image_t.
   *
   * \param image_handle
   * Handle of the image for which the get operation is performed on.
   *
   * \remarks
   * References manage the lifetime of the object. When the references reach zero the object is destroyed. A caller must
   * not access the object after its reference is released.
   *
   * \relates k4a_image_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT void k4a_image_reference(k4a_image_t image_handle);
  
  /** Remove a reference from the k4a_image_t.
   *
   * \param image_handle
   * Handle of the image for which the get operation is performed on.
   *
   * \remarks
   * References manage the lifetime of the object. When the references reach zero the object is destroyed. A caller must
   * not access the object after its reference is released.
   *
   * \relates k4a_image_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT void k4a_image_release(k4a_image_t image_handle);
  
  /** Starts color and depth camera capture.
   *
   * \param device_handle
   * Handle obtained by k4a_device_open().
   *
   * \param config
   * The configuration we want to run the device in. This can be initialized with ::K4A_DEVICE_CONFIG_INIT_DISABLE_ALL.
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED is returned on success.
   *
   * \relates k4a_device_t
   *
   * \remarks
   * Individual sensors configured to run will now start to stream captured data.
   *
   * \remarks
   * It is not valid to call k4a_device_start_cameras() a second time on the same \ref k4a_device_t until
   * k4a_device_stop_cameras() has been called.
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_device_start_cameras(k4a_device_t device_handle, const k4a_device_configuration_t *config);
  
  /** Stops the color and depth camera capture.
   *
   * \param device_handle
   * Handle obtained by k4a_device_open().
   *
   * \relates k4a_device_t
   *
   * \remarks
   * The streaming of individual sensors stops as a result of this call. Once called, k4a_device_start_cameras() may
   * be called again to resume sensor streaming.
   *
   * \remarks
   * This function may be called while another thread is blocking in k4a_device_get_capture().
   * Calling this function while another thread is in that function will result in that function returning a failure.
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT void k4a_device_stop_cameras(k4a_device_t device_handle);
  
  /** Starts the IMU sample stream.
   *
   * \param device_handle
   * Handle obtained by k4a_device_open().
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED is returned on success. ::K4A_RESULT_FAILED if the sensor is already running or a failure is
   * encountered. If a device does not support an IMU, ::K4A_RESULT_UNSUPPORTED is returned.
   *
   * \relates k4a_device_t
   *
   * \remarks
   * Call this API to start streaming IMU data. It is not valid to call this function a second time on the same
   * \ref k4a_device_t until k4a_device_stop_imu() has been called.
   *
   * \remarks
   * This function is dependent on the state of the cameras. The color or depth camera must be started before the IMU.
   * ::K4A_RESULT_FAILED will be returned if one of the cameras is not running.
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_device_start_imu(k4a_device_t device_handle);
  
  /** Stops the IMU capture.
   *
   * \param device_handle
   * Handle obtained by k4a_device_open().
   *
   * \relates k4a_device_t
   *
   * \remarks
   * The streaming of the IMU stops as a result of this call. Once called, k4a_device_start_imu() may
   * be called again to resume sensor streaming, so long as the cameras are running.
   *
   * \remarks
   * This function may be called while another thread is blocking in k4a_device_get_imu_sample().
   * Calling this function while another thread is in that function will result in that function returning a failure.
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT void k4a_device_stop_imu(k4a_device_t device_handle);
  
  /** Get the Azure Kinect device serial number.
   *
   * \param device_handle
   * Handle obtained by k4a_device_open().
   *
   * \param serial_number
   * Location to write the serial number to. If the function returns ::K4A_BUFFER_RESULT_SUCCEEDED, this will be a NULL
   * terminated string of ASCII characters. If this input is NULL \p serial_number_size will still be updated to return
   * the size of the buffer needed to store the string.
   *
   * \param serial_number_size
   * On input, the size of the \p serial_number buffer if that pointer is not NULL. On output, this value is set to the
   * actual number of bytes in the serial number (including the null terminator).
   *
   * \returns
   * A return of ::K4A_BUFFER_RESULT_SUCCEEDED means that the \p serial_number has been filled in. If the buffer is too
   * small the function returns ::K4A_BUFFER_RESULT_TOO_SMALL and the size of the serial number is
   * returned in the \p serial_number_size parameter. All other failures return ::K4A_BUFFER_RESULT_FAILED.
   *
   * \relates k4a_device_t
   *
   * \remarks
   * Queries the device for its serial number. If the caller needs to know the size of the serial number to allocate
   * memory, the function should be called once with a NULL \p serial_number to get the needed size in the \p
   * serial_number_size output, and then again with the allocated buffer.
   *
   * \remarks
   * Only a complete serial number will be returned. If the caller's buffer is too small, the function will return
   * ::K4A_BUFFER_RESULT_TOO_SMALL without returning any data in \p serial_number.
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_buffer_result_t k4a_device_get_serialnum(k4a_device_t device_handle,
                                                          char *serial_number,
                                                          size_t *serial_number_size);
  
  /** Get the version numbers of the device's subsystems.
   *
   * \param device_handle
   * Handle obtained by k4a_device_open().
   *
   * \param version
   * Location to write the version info to.
   *
   * \returns A return of ::K4A_RESULT_SUCCEEDED means that the version structure has been filled in.
   * All other failures return ::K4A_RESULT_FAILED.
   *
   * \relates k4a_device_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_device_get_version(k4a_device_t device_handle, k4a_hardware_version_t *version);
  
  /** Get the Azure Kinect color sensor control capabilities.
   *
   * \param device_handle
   * Handle obtained by k4a_device_open().
   *
   * \param command
   * Color sensor control command.
   *
   * \param supports_auto
   * Location to store whether the color sensor's control support auto mode or not.
   * true if it supports auto mode, otherwise false.
   *
   * \param min_value
   * Location to store the color sensor's control minimum value of /p command.
   *
   * \param max_value
   * Location to store the color sensor's control maximum value of /p command.
   *
   * \param step_value
   * Location to store the color sensor's control step value of /p command.
   *
   * \param default_value
   * Location to store the color sensor's control default value of /p command.
   *
   * \param default_mode
   * Location to store the color sensor's control default mode of /p command.
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED if the value was successfully returned, ::K4A_RESULT_FAILED if an error occurred.
   * ::K4A_RESULT_UNSUPPORTED if the device does not support this operation.
   *
   * \relates k4a_device_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_device_get_color_control_capabilities(k4a_device_t device_handle,
                                                                    k4a_color_control_command_t command,
                                                                    bool *supports_auto,
                                                                    int32_t *min_value,
                                                                    int32_t *max_value,
                                                                    int32_t *step_value,
                                                                    int32_t *default_value,
                                                                    k4a_color_control_mode_t *default_mode);
  
  /** Get the Azure Kinect color sensor control
   * value.
   *
   * \param device_handle
   * Handle obtained by k4a_device_open().
   *
   * \param command
   * Color sensor control command.
   *
   * \param mode
   * Location to store the color sensor's control mode. This mode represents whether the command is in automatic or
   * manual mode.
   *
   * \param value
   * Location to store the color sensor's control value. This value is always written, but is only valid when the \p
   * mode returned is ::K4A_COLOR_CONTROL_MODE_MANUAL for the current \p command.
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED if the value was successfully returned, ::K4A_RESULT_FAILED if an error occurred.
   * ::K4A_RESULT_UNSUPPORTED if the device does not support this operation.
   *
   * \remarks
   * Each control command may be set to manual or automatic. See the definition of \ref k4a_color_control_command_t on
   * how to interpret the \p value for each command.
   *
   * \remarks
   * Some control commands are only supported in manual mode. When a command is in automatic mode, the \p value for
   * that command is not valid.
   *
   * \remarks
   * Control values set on a device are reset only when the device is power cycled. The device will retain the
   * settings even if the \ref k4a_device_t is closed or the application is restarted.
   *
   * \relates k4a_device_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_device_get_color_control(k4a_device_t device_handle,
                                                       k4a_color_control_command_t command,
                                                       k4a_color_control_mode_t *mode,
                                                       int32_t *value);
  
  /** Set the Azure Kinect color sensor control value.
   *
   * \param device_handle
   * Handle obtained by k4a_device_open().
   *
   * \param command
   * Color sensor control command.
   *
   * \param mode
   * Color sensor control mode to set. This mode represents whether the command is in automatic or manual mode.
   *
   * \param value
   * Value to set the color sensor's control to. The value is only valid if \p mode
   * is set to ::K4A_COLOR_CONTROL_MODE_MANUAL, and is otherwise ignored.
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED if the value was successfully set, ::K4A_RESULT_FAILED if an error occurred.
   * ::K4A_RESULT_UNSUPPORTED if the device does not support this operation.
   *
   * \remarks
   * Each control command may be set to manual or automatic. See the definition of \ref k4a_color_control_command_t on how
   * to interpret the \p value for each command.
   *
   * \remarks
   * Some control commands are only supported in manual mode. When a command is in automatic mode, the \p value for that
   * command is not valid.
   *
   * \remarks
   * Control values set on a device are reset only when the device is power cycled. The device will retain the settings
   * even if the \ref k4a_device_t is closed or the application is restarted.
   *
   * \relates k4a_device_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_device_set_color_control(k4a_device_t device_handle,
                                                       k4a_color_control_command_t command,
                                                       k4a_color_control_mode_t mode,
                                                       int32_t value);
  
  /** Get the raw calibration blob for the entire Azure Kinect device.
   *
   * \param device_handle
   * Handle obtained by k4a_device_open().
   *
   * \param data
   * Location to write the calibration data to. This field may optionally be set to NULL for the caller to query for
   * the needed data size.
   *
   * \param data_size
   * On passing \p data_size into the function this variable represents the available size of the \p data
   * buffer. On return this variable is updated with the amount of data actually written to the buffer, or the size
   * required to store the calibration buffer if \p data is NULL.
   *
   * \returns
   * ::K4A_BUFFER_RESULT_SUCCEEDED if \p data was successfully written. If \p data_size points to a buffer size that is
   * too small to hold the output or \p data is NULL, ::K4A_BUFFER_RESULT_TOO_SMALL is returned and \p data_size is
   * updated to contain the minimum buffer size needed to capture the calibration data.
   *
   * \relates k4a_device_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_buffer_result_t k4a_device_get_raw_calibration(k4a_device_t device_handle,
                                                                uint8_t *data,
                                                                size_t *data_size);
  
  /** Get the camera calibration for the entire Azure Kinect device.
   *
   * \param device_handle
   * Handle obtained by k4a_device_open().
   *
   * \param depth_mode_id
   * Mode in which depth camera is operated.
   *
   * \param color_mode_id
   * Mode in which color camera is operated.
   *
   * \param calibration
   * Location to write the calibration
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED if \p calibration was successfully written. ::K4A_RESULT_FAILED otherwise.
   *
   * \remarks
   * The \p calibration represents the data needed to transform between the camera views and may be
   * different for each operating \p depth_mode_id and \p color_mode_id the device is configured to operate in.
   *
   * \remarks
   * The \p calibration output is used as input to all calibration and transformation functions.
   *
   * \see k4a_calibration_2d_to_2d()
   * \see k4a_calibration_2d_to_3d()
   * \see k4a_calibration_3d_to_2d()
   * \see k4a_calibration_3d_to_3d()
   *
   * \relates k4a_device_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_device_get_calibration(k4a_device_t device_handle,
                                                     const uint32_t depth_mode_id,
                                                     const uint32_t color_mode_id,
                                                     k4a_calibration_t *calibration);
  
  /** Get the device jack status for the synchronization in and synchronization out connectors.
   *
   * \param device_handle
   * Handle obtained by k4a_device_open().
   *
   * \param sync_in_jack_connected
   * Upon successful return this value will be set to true if a cable is connected to this sync in jack.
   *
   * \param sync_out_jack_connected
   * Upon successful return this value will be set to true if a cable is connected to this sync out jack.
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED if the connector status was successfully read.
   * ::K4A_RESULT_UNSUPPORTED if the device does not support this operation.
   *
   * \relates k4a_device_t
   *
   * \remarks
   * If \p sync_out_jack_connected is true then \ref k4a_device_configuration_t wired_sync_mode mode can be set to \ref
   * K4A_WIRED_SYNC_MODE_STANDALONE or \ref K4A_WIRED_SYNC_MODE_MASTER. If \p sync_in_jack_connected is true then \ref
   * k4a_device_configuration_t wired_sync_mode mode can be set to \ref K4A_WIRED_SYNC_MODE_STANDALONE or \ref
   * K4A_WIRED_SYNC_MODE_SUBORDINATE.
   *
   * \see k4a_device_start_cameras()
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_device_get_sync_jack(k4a_device_t device_handle,
                                                   bool *sync_in_jack_connected,
                                                   bool *sync_out_jack_connected);
  
  /** Get the camera calibration for a device from a raw calibration blob.
   *
   * \param raw_calibration
   * Raw calibration blob obtained from a device or recording. The raw calibration must be NULL terminated.
   *
   * \param raw_calibration_size
   * The size, in bytes, of raw_calibration including the NULL termination.
   *
   * \param depth_mode_id
   * Mode in which depth camera is operated.
   *
   * \param color_mode_id
   * Resolution in which color camera is operated.
   *
   * \param calibration
   * Location to write the calibration.
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED if \p calibration was successfully written. ::K4A_RESULT_FAILED otherwise.
   *
   * \remarks
   * The \p calibration represents the data needed to transform between the camera views and is
   * different for each operating \p depth_mode_id and \p color_mode_id the device is configured to operate in.
   *
   * \remarks
   * The \p calibration output is used as input to all transformation functions.
   *
   * \see k4a_calibration_2d_to_2d()
   * \see k4a_calibration_2d_to_3d()
   * \see k4a_calibration_3d_to_2d()
   * \see k4a_calibration_3d_to_3d()
   *
   * \relates k4a_device_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_calibration_get_from_raw(char *raw_calibration,
                                                       size_t raw_calibration_size,
                                                       const uint32_t depth_mode_id,
                                                       const uint32_t color_mode_id,
                                                       k4a_calibration_t *calibration);
  
  /** Transform a 3D point of a source coordinate system into a 3D point of the target coordinate system
   *
   * \param calibration
   * Location to read the camera calibration data.
   *
   * \param source_point3d_mm
   * The 3D coordinates in millimeters representing a point in \p source_camera.
   *
   * \param source_camera
   * The current camera.
   *
   * \param target_camera
   * The target camera.
   *
   * \param target_point3d_mm
   * Pointer to the output where the new 3D coordinates of the input point in the coordinate space of \p target_camera is
   * stored in millimeters.
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED if \p target_point3d_mm was successfully written. ::K4A_RESULT_FAILED if \p calibration
   * contained invalid transformation parameters. ::K4A_RESULT_UNSUPPORTED if the device does not support this operation.
   *
   * \remarks
   * This function is used to transform 3D points between depth and color camera coordinate systems. The function uses the
   * extrinsic camera calibration. It computes the output via multiplication with a precomputed matrix encoding a 3D
   * rotation and a 3D translation. If \p source_camera and \p target_camera are the same, then \p target_point3d_mm will
   * be identical to \p source_point3d_mm.
   *
   * \relates k4a_calibration_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_calibration_3d_to_3d(const k4a_calibration_t *calibration,
                                                   const k4a_float3_t *source_point3d_mm,
                                                   const k4a_calibration_type_t source_camera,
                                                   const k4a_calibration_type_t target_camera,
                                                   k4a_float3_t *target_point3d_mm);
  
  /** Transform a 2D pixel coordinate with an associated depth value of the source camera into a 3D point of the target
   * coordinate system.
   *
   * \param calibration
   * Location to read the camera calibration obtained by k4a_device_get_calibration().
   *
   * \param source_point2d
   * The 2D pixel in \p source_camera coordinates.
   *
   * \param source_depth_mm
   * The depth of \p source_point2d in millimeters. One way to derive the depth value in the color camera geometry is to
   * use the function k4a_transformation_depth_image_to_color_camera().
   *
   * \param source_camera
   * The current camera.
   *
   * \param target_camera
   * The target camera.
   *
   * \param target_point3d_mm
   * Pointer to the output where the 3D coordinates of the input pixel in the coordinate system of \p target_camera is
   * stored in millimeters.
   *
   * \param valid
   * The output parameter returns a value of 1 if the \p source_point2d is a valid coordinate, and will return 0 if
   * the coordinate is not valid in the calibration model.
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED if \p target_point3d_mm was successfully written. ::K4A_RESULT_FAILED if \p calibration
   * contained invalid transformation parameters. If the function returns ::K4A_RESULT_SUCCEEDED, but \p valid is 0,
   * the transformation was computed, but the results in \p target_point3d_mm are outside of the range of valid
   * calibration and should be ignored. ::K4A_RESULT_UNSUPPORTED if the device does not support this operation.
   *
   * \remarks
   * This function applies the intrinsic calibration of \p source_camera to compute the 3D ray from the focal point of the
   * camera through pixel \p source_point2d. The 3D point on this ray is then found using \p source_depth_mm. If \p
   * target_camera is different from \p source_camera, the 3D point is transformed to \p target_camera using
   * k4a_calibration_3d_to_3d(). In practice, \p source_camera and \p target_camera will often be identical. In this
   * case, no 3D to 3D transformation is applied.
   *
   * \remarks
   * If \p source_point2d is not considered as valid pixel coordinate
   * according to the intrinsic camera model, \p valid is set to 0. If it is valid, \p valid will be set to 1. The user
   * should not use the value of \p target_point3d_mm if \p valid was set to 0.
   *
   * \relates k4a_calibration_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_calibration_2d_to_3d(const k4a_calibration_t *calibration,
                                                   const k4a_float2_t *source_point2d,
                                                   const float source_depth_mm,
                                                   const k4a_calibration_type_t source_camera,
                                                   const k4a_calibration_type_t target_camera,
                                                   k4a_float3_t *target_point3d_mm,
                                                   int *valid);
  
  /** Transform a 3D point of a source coordinate system into a 2D pixel coordinate of the target camera.
   *
   * \param calibration
   * Location to read the camera calibration obtained by k4a_device_get_calibration().
   *
   * \param source_point3d_mm
   * The 3D coordinates in millimeters representing a point in \p source_camera
   *
   * \param source_camera
   * The current camera.
   *
   * \param target_camera
   * The target camera.
   *
   * \param target_point2d
   * Pointer to the output where the 2D pixel in \p target_camera coordinates is stored.
   *
   * \param valid
   * The output parameter returns a value of 1 if the \p source_point3d_mm is a valid coordinate in the \p target_camera
   * coordinate system, and will return 0 if the coordinate is not valid in the calibration model.
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED if \p target_point2d was successfully written. ::K4A_RESULT_FAILED if \p calibration
   * contained invalid transformation parameters. If the function returns ::K4A_RESULT_SUCCEEDED, but \p valid is 0,
   * the transformation was computed, but the results in \p target_point2d are outside of the range of valid calibration
   * and should be ignored. ::K4A_RESULT_UNSUPPORTED if the device does not support this operation.
   *
   * \remarks
   * If \p target_camera is different from \p source_camera, \p source_point3d_mm is transformed to \p target_camera using
   * k4a_calibration_3d_to_3d(). In practice, \p source_camera and \p target_camera will often be identical. In this
   * case, no 3D to 3D transformation is applied. The 3D point in the coordinate system of \p target_camera is then
   * projected onto the image plane using the intrinsic calibration of \p target_camera.
   *
   * \remarks
   * If \p source_point3d_mm does not map to a valid 2D coordinate in the \p target_camera coordinate system, \p valid is
   * set to 0. If it is valid, \p valid will be set to 1. The user should not use the value of \p target_point2d if \p
   * valid was set to 0.
   *
   * \relates k4a_calibration_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_calibration_3d_to_2d(const k4a_calibration_t *calibration,
                                                   const k4a_float3_t *source_point3d_mm,
                                                   const k4a_calibration_type_t source_camera,
                                                   const k4a_calibration_type_t target_camera,
                                                   k4a_float2_t *target_point2d,
                                                   int *valid);
  
  /** Transform a 2D pixel coordinate with an associated depth value of the source camera into a 2D pixel coordinate of
   * the target camera.
   *
   * \param calibration
   * Location to read the camera calibration obtained by k4a_device_get_calibration().
   *
   * \param source_point2d
   * The 2D pixel in \p source_camera coordinates.
   *
   * \param source_depth_mm
   * The depth of \p source_point2d in millimeters. One way to derive the depth value in the color camera geometry is to
   * use the function k4a_transformation_depth_image_to_color_camera().
   *
   * \param source_camera
   * The current camera.
   *
   * \param target_camera
   * The target camera.
   *
   * \param target_point2d
   * The 2D pixel in \p target_camera coordinates.
   *
   * \param valid
   * The output parameter returns a value of 1 if the \p source_point2d is a valid coordinate in the \p target_camera
   * coordinate system, and will return 0 if the coordinate is not valid in the calibration model.
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED if \p target_point2d was successfully written. ::K4A_RESULT_FAILED if \p calibration
   * contained invalid transformation parameters. If the function returns ::K4A_RESULT_SUCCEEDED, but \p valid is 0,
   * the transformation was computed, but the results in \p target_point2d are outside of the range of valid calibration
   * and should be ignored. ::K4A_RESULT_UNSUPPORTED if the device does not support this operation.
   *
   * \remarks
   * This function maps a pixel between the coordinate systems of the depth and color cameras. It is equivalent to calling
   * k4a_calibration_2d_to_3d() to compute the 3D point corresponding to \p source_point2d and then using
   * k4a_calibration_3d_to_2d() to map the 3D point into the coordinate system of the \p target_camera.
   *
   * \remarks
   * If \p source_camera and \p target_camera are identical, the function immediately sets \p target_point2d to \p
   * source_point2d and returns without computing any transformations.
   *
   * \remarks
   * If \p source_point2d does not map to a valid 2D coordinate in the \p target_camera coordinate system, \p valid is set
   * to 0. If it is valid, \p valid will be set to 1. The user should not use the value of \p target_point2d if \p valid
   * was set to 0.
   *
   * \relates k4a_calibration_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_calibration_2d_to_2d(const k4a_calibration_t *calibration,
                                                   const k4a_float2_t *source_point2d,
                                                   const float source_depth_mm,
                                                   const k4a_calibration_type_t source_camera,
                                                   const k4a_calibration_type_t target_camera,
                                                   k4a_float2_t *target_point2d,
                                                   int *valid);
  
  /** Transform a 2D pixel coordinate from color camera into a 2D pixel coordinate of
   * the depth camera.
   *
   * \param calibration
   * Location to read the camera calibration obtained by k4a_device_get_calibration().
   *
   * \param source_point2d
   * The 2D pixel in \p color camera coordinates.
   *
   * \param depth_image
   * Handle to input depth image.
   *
   * \param target_point2d
   * The 2D pixel in \p depth camera coordinates.
   *
   * \param valid
   * The output parameter returns a value of 1 if the \p source_point2d is a valid coordinate in the \p target_camera
   * coordinate system, and will return 0 if the coordinate is not valid in the calibration model.
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED if \p target_point2d was successfully written. ::K4A_RESULT_FAILED if \p calibration
   * contained invalid transformation parameters. If the function returns ::K4A_RESULT_SUCCEEDED, but \p valid is 0,
   * the transformation was computed, but the results in \p target_point2d are outside of the range of valid calibration
   * and should be ignored. ::K4A_RESULT_UNSUPPORTED if the device does not support this operation.
   *
   * \remarks
   * This function represents an alternative to k4a_calibration_2d_to_2d() if the number of pixels that need to be
   * transformed is small. This function searches along an epipolar line in the depth image to find the corresponding
   * depth pixel. If a larger number of pixels need to be transformed, it might be computationally cheaper to call
   * k4a_transformation_depth_image_to_color_camera() to get correspondence depth values for these color pixels, then call
   * the function k4a_calibration_2d_to_2d().
   *
   * \remarks
   * If \p source_point2d does not map to a valid 2D coordinate in the \p target_camera coordinate system, \p valid is set
   * to 0. If it is valid, \p valid will be set to 1. The user should not use the value of \p target_point2d if \p valid
   * was set to 0.
   *
   * \relates k4a_calibration_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_calibration_color_2d_to_depth_2d(const k4a_calibration_t *calibration,
                                                               const k4a_float2_t *source_point2d,
                                                               const k4a_image_t depth_image,
                                                               k4a_float2_t *target_point2d,
                                                               int *valid);
  
  /** Get handle to transformation handle.
   *
   * \param calibration
   * A calibration structure obtained by k4a_device_get_calibration().
   *
   * \returns
   * A transformation handle. A NULL is returned if creation fails.
   *
   * \remarks
   * The transformation handle is used to transform images from the coordinate system of one camera into the other. Each
   * transformation handle requires some pre-computed resources to be allocated, which are retained until the handle is
   * destroyed.
   *
   * \remarks
   * The transformation handle must be destroyed with k4a_transformation_destroy() when it is no longer to be used.
   *
   * \relates k4a_calibration_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_transformation_t k4a_transformation_create(const k4a_calibration_t *calibration);
  
  /** Destroy transformation handle.
   *
   * \param transformation_handle
   * Transformation handle to destroy.
   *
   * \relates k4a_transformation_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT void k4a_transformation_destroy(k4a_transformation_t transformation_handle);
  
  /** Transforms the depth map into the geometry of the color camera.
   *
   * \param transformation_handle
   * Transformation handle.
   *
   * \param depth_image
   * Handle to input depth image.
   *
   * \param transformed_depth_image
   * Handle to output transformed depth image.
   *
   * \remarks
   * This produces a depth image for which each pixel matches the corresponding pixel coordinates of the color camera.
   *
   * \remarks
   * \p depth_image and \p transformed_depth_image must be of format ::K4A_IMAGE_FORMAT_DEPTH16.
   *
   * \remarks
   * \p transformed_depth_image must have a width and height matching the width and height of the color camera in the mode
   * specified by the \ref k4a_calibration_t used to create the \p transformation_handle with k4a_transformation_create().
   *
   * \remarks
   * The contents \p transformed_depth_image will be filled with the depth values derived from \p depth_image in the color
   * camera's coordinate space.
   *
   * \remarks
   * \p transformed_depth_image should be created by the caller using k4a_image_create() or
   * k4a_image_create_from_buffer().
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED if \p transformed_depth_image was successfully written and ::K4A_RESULT_FAILED otherwise.
   * ::K4A_RESULT_UNSUPPORTED if the device does not support this operation.
   *
   * \relates k4a_transformation_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_transformation_depth_image_to_color_camera(k4a_transformation_t transformation_handle,
                                                                         const k4a_image_t depth_image,
                                                                         k4a_image_t transformed_depth_image);
  
  /** Transforms depth map and a custom image into the geometry of the color camera.
   *
   * \param transformation_handle
   * Transformation handle.
   *
   * \param depth_image
   * Handle to input depth image.
   *
   * \param custom_image
   * Handle to input custom image.
   *
   * \param transformed_depth_image
   * Handle to output transformed depth image.
   *
   * \param transformed_custom_image
   * Handle to output transformed custom image.
   *
   * \param interpolation_type
   * Parameter that controls how pixels in \p custom_image should be interpolated when transformed to color camera space.
   * K4A_TRANSFORMATION_INTERPOLATION_TYPE_LINEAR if linear interpolation should be used.
   * K4A_TRANSFORMATION_INTERPOLATION_TYPE_NEAREST if nearest neighbor interpolation should be used.
   *
   * \param invalid_custom_value
   * Defines the custom image pixel value that should be written to \p transformed_custom_image in case the corresponding
   * depth pixel can not be transformed into the color camera space.
   *
   * \remarks
   * This produces a depth image and a corresponding custom image for which each pixel matches the corresponding
   * pixel coordinates of the color camera.
   *
   * \remarks
   * \p depth_image and \p transformed_depth_image must be of format ::K4A_IMAGE_FORMAT_DEPTH16.
   *
   * \remarks
   * \p custom_image and \p transformed_custom_image must be of format ::K4A_IMAGE_FORMAT_CUSTOM8 or
   * ::K4A_IMAGE_FORMAT_CUSTOM16.
   *
   * \remarks
   * \p transformed_depth_image and \p transformed_custom_image must have a width and height matching the width and
   * height of the color camera in the mode specified by the \ref k4a_calibration_t used to create the
   * \p transformation_handle with k4a_transformation_create().
   *
   * \remarks
   * \p custom_image must have a width and height matching the width and height of \p depth_image.
   *
   * \remarks
   * The contents \p transformed_depth_image will be filled with the depth values derived from \p depth_image in the color
   * camera's coordinate space.
   *
   * \remarks
   * The contents \p transformed_custom_image will be filled with the values derived from \p custom_image in the color
   * camera's coordinate space.
   *
   * \remarks
   * \p transformed_depth_image and \p transformed_custom_image should be created by the caller using k4a_image_create()
   * or k4a_image_create_from_buffer().
   *
   * \remarks
   * Using ::K4A_TRANSFORMATION_INTERPOLATION_TYPE_LINEAR for \p interpolation_type could create new values to \p
   * transformed_custom_image which do no exist in \p custom_image. Using ::K4A_TRANSFORMATION_INTERPOLATION_TYPE_NEAREST
   * will prevent this from happenning but will result in a less smooth image.
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED if \p transformed_depth_image and \p transformed_custom_image were successfully written and
   * ::K4A_RESULT_FAILED otherwise. ::K4A_RESULT_UNSUPPORTED if the device does not support this operation.
   *
   * \relates k4a_transformation_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t
  k4a_transformation_depth_image_to_color_camera_custom(k4a_transformation_t transformation_handle,
                                                        const k4a_image_t depth_image,
                                                        const k4a_image_t custom_image,
                                                        k4a_image_t transformed_depth_image,
                                                        k4a_image_t transformed_custom_image,
                                                        k4a_transformation_interpolation_type_t interpolation_type,
                                                        uint32_t invalid_custom_value);
  
  /** Transforms a color image into the geometry of the depth camera.
   *
   * \param transformation_handle
   * Transformation handle.
   *
   * \param depth_image
   * Handle to input depth image.
   *
   * \param color_image
   * Handle to input color image.
   *
   * \param transformed_color_image
   * Handle to output transformed color image.
   *
   * \remarks
   * This produces a color image for which each pixel matches the corresponding pixel coordinates of the depth camera.
   *
   * \remarks
   * \p depth_image and \p color_image need to represent the same moment in time. The depth data will be applied to the
   * color image to properly warp the color data to the perspective of the depth camera.
   *
   * \remarks
   * \p depth_image must be of type ::K4A_IMAGE_FORMAT_DEPTH16. \p color_image must be of format
   * ::K4A_IMAGE_FORMAT_COLOR_BGRA32.
   *
   * \remarks
   * \p transformed_color_image image must be of format ::K4A_IMAGE_FORMAT_COLOR_BGRA32. \p transformed_color_image must
   * have the width and height of the depth camera in the mode specified by the \ref k4a_calibration_t used to create
   * the \p transformation_handle with k4a_transformation_create().
   *
   * \remarks
   * \p transformed_color_image should be created by the caller using k4a_image_create() or
   * k4a_image_create_from_buffer().
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED if \p transformed_color_image was successfully written and ::K4A_RESULT_FAILED otherwise.
   * ::K4A_RESULT_UNSUPPORTED if the device does not support this operation.
   *
   * \relates k4a_transformation_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_transformation_color_image_to_depth_camera(k4a_transformation_t transformation_handle,
                                                                         const k4a_image_t depth_image,
                                                                         const k4a_image_t color_image,
                                                                         k4a_image_t transformed_color_image);
  
  /** Transforms the depth image into 3 planar images representing X, Y and Z-coordinates of corresponding 3D points.
   *
   * \param transformation_handle
   * Transformation handle.
   *
   * \param depth_image
   * Handle to input depth image.
   *
   * \param camera
   * Geometry in which depth map was computed.
   *
   * \param xyz_image
   * Handle to output xyz image.
   *
   * \remarks
   * \p depth_image must be of format ::K4A_IMAGE_FORMAT_DEPTH16.
   *
   * \remarks
   * The \p camera parameter tells the function what the perspective of the \p depth_image is. If the \p depth_image was
   * captured directly from the depth camera, the value should be ::K4A_CALIBRATION_TYPE_DEPTH. If the \p depth_image is
   * the result of a transformation into the color camera's coordinate space using
   * k4a_transformation_depth_image_to_color_camera(), the value should be ::K4A_CALIBRATION_TYPE_COLOR.
   *
   * \remarks
   * The format of \p xyz_image must be ::K4A_IMAGE_FORMAT_CUSTOM. The width and height of \p xyz_image must match the
   * width and height of \p depth_image. \p xyz_image must have a stride in bytes of at least 6 times its width in pixels.
   *
   * \remarks
   * Each pixel of the \p xyz_image consists of three int16_t values, totaling 6 bytes. The three int16_t values are the
   * X, Y, and Z values of the point.
   *
   * \remarks
   * \p xyz_image should be created by the caller using k4a_image_create() or k4a_image_create_from_buffer().
   *
   * \returns
   * ::K4A_RESULT_SUCCEEDED if \p xyz_image was successfully written and ::K4A_RESULT_FAILED otherwise.
   * ::K4A_RESULT_UNSUPPORTED if the device does not support this operation.
   *
   * \relates k4a_transformation_t
   *
   * \xmlonly
   * <requirements>
   *   <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
   *   <requirement name="Library">k4a.lib</requirement>
   *   <requirement name="DLL">k4a.dll</requirement>
   * </requirements>
   * \endxmlonly
   */
  K4A_EXPORT k4a_result_t k4a_transformation_depth_image_to_point_cloud(k4a_transformation_t transformation_handle,
                                                                        const k4a_image_t depth_image,
                                                                        const k4a_calibration_type_t camera,
                                                                        k4a_image_t xyz_image);
  
  /**
   * @}
   */
  
  #ifdef __cplusplus
  }
  #endif
  
  #endif /* K4A_H */
  