/** \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.
 *
 * \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.
 *
 * \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);

/** 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.
 *
 * \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. 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
 *
 * \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
 *
 * \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
 *
 * \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
 *
 * \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
 * Mode in which depth camera is operated.
 *
 * \param color_resolution
 * 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 may be
 * different for each operating \p depth_mode and \p color_resolution 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 k4a_depth_mode_t depth_mode,
                                                   const k4a_color_resolution_t color_resolution,
                                                   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.
 *
 * \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
 * Mode in which depth camera is operated.
 *
 * \param color_resolution
 * 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 and \p color_resolution 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 k4a_depth_mode_t depth_mode,
                                                     const k4a_color_resolution_t color_resolution,
                                                     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.
 *
 * \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.
 *
 * \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.
 *
 * \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.
 *
 * \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.
 *
 * \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.
 *
 * \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.
 *
 * \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.
 *
 * \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 a single image with voxels representing
 * X, Y and Z-coordinates in millimeters 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.
 *
 * \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 */