kinect/codes/Azure-Kinect-Sensor-SDK/include/k4arecord/playback.h

918 lines
36 KiB
C
Raw Normal View History

2024-03-06 18:05:53 +00:00
/** \file playback.h
* Copyright (c) Microsoft Corporation. All rights reserved.
* Licensed under the MIT License.
* Kinect For Azure Recording Playback SDK.
*/
#ifndef K4A_PLAYBACK_H
#define K4A_PLAYBACK_H
#include <k4arecord/types.h>
#include <k4arecord/k4arecord_export.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
*
* \addtogroup Functions
*
* @{
*/
/** Opens an existing recording file for reading.
*
* \param path
* Filesystem path of the existing recording.
*
* \param playback_handle
* If successful, this contains a pointer to the recording handle. Caller must call k4a_playback_close() when
* finished with the recording.
*
* \headerfile playback.h <k4arecord/playback.h>
*
* \returns ::K4A_RESULT_SUCCEEDED is returned on success
*
* \relates k4a_playback_t
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT k4a_result_t k4a_playback_open(const char *path, k4a_playback_t *playback_handle);
/** Get the raw calibration blob for the Azure Kinect device used during recording.
*
* \param playback_handle
* Handle obtained by k4a_playback_open().
*
* \param data
* Location to write the calibration data to. This field may optionally be set to NULL if the caller wants to query for
* the needed data size.
*
* \param data_size
* On passing \p data_size into the function this variable represents the available size to write the raw data to. On
* return this variable is updated with the amount of data actually written to the buffer.
*
* \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, ::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.
*
* \remarks
* The raw calibration may not exist if the device was not specified during recording.
*
* \relates k4a_playback_t
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT k4a_buffer_result_t k4a_playback_get_raw_calibration(k4a_playback_t playback_handle,
uint8_t *data,
size_t *data_size);
/** Get the camera calibration for Azure Kinect device used during recording. The output struct is used as input to all
* transformation functions.
*
* \param playback_handle
* Handle obtained by k4a_playback_open().
*
* \param calibration
* Location to write the calibration.
*
* \returns
* ::K4A_RESULT_SUCCEEDED if \p calibration was successfully written. ::K4A_RESULT_FAILED otherwise.
*
* \remarks
* The calibration may not exist if the device was not specified during recording.
*
* \relates k4a_playback_t
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT k4a_result_t k4a_playback_get_calibration(k4a_playback_t playback_handle,
k4a_calibration_t *calibration);
/** Get the device configuration used during recording.
*
* \param playback_handle
* Handle obtained by k4a_playback_open().
*
* \param config
* Location to write the recording configuration.
*
* \returns
* ::K4A_RESULT_SUCCEEDED if \p config was successfully written. ::K4A_RESULT_FAILED otherwise.
*
* \relates k4a_playback_t
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT k4a_result_t k4a_playback_get_record_configuration(k4a_playback_t playback_handle,
k4a_record_configuration_t *config);
/** Checks whether a track with the given track name exists in the playback file.
*
* \param playback_handle
* Handle obtained by k4a_playback_open().
*
* \param track_name
* The track name to be checked to see whether it exists or not.
*
* \returns true if the track exists.
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT bool k4a_playback_check_track_exists(k4a_playback_t playback_handle, const char *track_name);
/** Get the number of tracks in a playback file.
*
* \param playback_handle
* Handle obtained by k4a_playback_open().
*
* \returns the number of tracks in the playback file.
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT size_t k4a_playback_get_track_count(k4a_playback_t playback_handle);
/** Gets the name of a track at a specific index.
*
* \param playback_handle
* Handle obtained by k4a_playback_open().
*
* \param track_index
* The index of the track to read the name form.
*
* \param track_name
* Location to write the track name. This will be a UTF8 null terminated string. If a NULL buffer is specified,
* \p track_name_size will be set to the size of buffer needed to store the string.
*
* \param track_name_size
* On input, the size of the \p track_name buffer. On output, this is set to the length of the track_name value
* (including the null terminator).
*
* \returns
* A return of ::K4A_BUFFER_RESULT_SUCCEEDED means that the \p track_name has been filled in. If the buffer is too small
* the function returns ::K4A_BUFFER_RESULT_TOO_SMALL and the needed size of the \p track_name buffer is returned in the
* \p track_name_size parameter. ::K4A_BUFFER_RESULT_FAILED is returned if the track index does not exist. All other
* failures return ::K4A_BUFFER_RESULT_FAILED.
*
* \remarks
* When used along with k4a_playback_get_track_count(), this function can be used to enumerate all the available tracks
* in a playback file. Additionally k4a_playback_track_is_builtin() can be used to filter custom tracks.
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT k4a_buffer_result_t k4a_playback_get_track_name(k4a_playback_t playback_handle,
size_t track_index,
char *track_name,
size_t *track_name_size);
/** Checks whether a track is one of the built-in tracks: "COLOR", "DEPTH", etc...
*
* \param playback_handle
* Handle obtained by k4a_playback_open().
*
* \param track_name
* The track name to be checked to see whether it is a built-in track.
*
* \returns true if the track is built-in. If the provided track name does not exist, false will be returned.
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT bool k4a_playback_track_is_builtin(k4a_playback_t playback_handle, const char *track_name);
/** Gets the video-specific track information for a particular video track.
*
* \param playback_handle
* Handle obtained by k4a_playback_open().
*
* \param track_name
* The track name to read video settings from.
*
* \param video_settings
* Location to write the track's video settings.
*
* \returns ::K4A_RESULT_SUCCEEDED is returned on success, ::K4A_RESULT_FAILED is returned if the specified track does
* not exist or is not a video track.
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT k4a_result_t k4a_playback_track_get_video_settings(k4a_playback_t playback_handle,
const char *track_name,
k4a_record_video_settings_t *video_settings);
/** Gets the codec id string for a particular track.
*
* The codec ID is a string that corresponds to the codec of the track's data. Some of the existing formats are listed
* here: https://www.matroska.org/technical/specs/codecid/index.html. It can also be custom defined by the user.
*
* \param playback_handle
* Handle obtained by k4a_playback_open().
*
* \param track_name
* The track name to read the codec id from.
*
* \param codec_id
* Location to write the codec id. This will be a UTF8 null terminated string. If a NULL buffer is specified,
* \p codec_id_size will be set to the size of buffer needed to store the string.
*
* \param codec_id_size
* On input, the size of the \p codec_id buffer. On output, this is set to the length of the codec_id value (including
* the null terminator).
*
* \returns
* A return of ::K4A_BUFFER_RESULT_SUCCEEDED means that the \p codec_id has been filled in. If the buffer is too small
* the function returns ::K4A_BUFFER_RESULT_TOO_SMALL and the needed size of the \p codec_id buffer is returned in the
* \p codec_id_size parameter. ::K4A_BUFFER_RESULT_FAILED is returned if the track_name does not exist. All other
* failures return ::K4A_BUFFER_RESULT_FAILED.
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT k4a_buffer_result_t k4a_playback_track_get_codec_id(k4a_playback_t playback_handle,
const char *track_name,
char *codec_id,
size_t *codec_id_size);
/** Gets the codec context for a particular track.
*
* The codec context is a codec-specific buffer that contains any required codec metadata that is only known to the
* codec. It is mapped to the matroska Codec Private field.
*
* \param playback_handle
* Handle obtained by k4a_playback_open().
*
* \param track_name
* The track name to read the codec context from.
*
* \param codec_context
* Location to write the codec context data. If a NULL buffer is specified, \p codec_context_size will be set to the
* size of buffer needed to store the data.
*
* \param codec_context_size
* On input, the size of the \p codec_context buffer. On output, this is set to the length of the codec_context data.
*
* \returns
* A return of ::K4A_BUFFER_RESULT_SUCCEEDED means that the \p codec_context has been filled in. If the buffer is too
* small the function returns ::K4A_BUFFER_RESULT_TOO_SMALL and the needed size of the \p codec_context buffer is
* returned in the \p codec_context_size parameter. ::K4A_BUFFER_RESULT_FAILED is returned if the track_name does not
* exist. All other failures return ::K4A_BUFFER_RESULT_FAILED.
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT k4a_buffer_result_t k4a_playback_track_get_codec_context(k4a_playback_t playback_handle,
const char *track_name,
uint8_t *codec_context,
size_t *codec_context_size);
/** Read the value of a tag from a recording.
*
* \param playback_handle
* Handle obtained by k4a_playback_open().
*
* \param name
* The name of the tag to read.
*
* \param value
* Location to write the tag value. This will be a UTF8 null terminated string. If a NULL buffer is specified,
* \p value_size will be set to the size of buffer needed to store the string.
*
* \param value_size
* On input, the size of the \p value buffer. On output, this is set to the length of the tag value (including the null
* terminator).
*
* \returns
* A return of ::K4A_BUFFER_RESULT_SUCCEEDED means that the \p value has been filled in. If the buffer is too small the
* function returns ::K4A_BUFFER_RESULT_TOO_SMALL and the needed size of the \p value buffer is returned in the
* \p value_size parameter. ::K4A_BUFFER_RESULT_FAILED is returned if the tag does not exist. All other failures return
* ::K4A_BUFFER_RESULT_FAILED.
*
* \remarks
* Tags are global to a file, and should store data related to the entire recording, such as camera configuration or
* recording location.
*
* \relates k4a_playback_t
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT k4a_buffer_result_t k4a_playback_get_tag(k4a_playback_t playback_handle,
const char *name,
char *value,
size_t *value_size);
/** Set the image format that color captures will be converted to. By default the conversion format will be the same as
* the image format stored in the recording file, and no conversion will occur.
*
* \param playback_handle
* Handle obtained by k4a_playback_open().
*
* \param target_format
* The target image format to be returned in captures.
*
* \returns
* ::K4A_RESULT_SUCCEEDED if the format conversion is supported. ::K4A_RESULT_FAILED otherwise.
*
* \remarks
* After the color conversion format is set, all \ref k4a_capture_t objects returned from the playback handle will have
* their color images converted to the \p target_format.
*
* \remarks
* Color format conversion occurs in the user-thread, so setting \p target_format to anything other than the format
* stored in the file may significantly increase the latency of \p k4a_playback_get_next_capture() and
* \p k4a_playback_get_previous_capture().
*
* \relates k4a_playback_t
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT k4a_result_t k4a_playback_set_color_conversion(k4a_playback_t playback_handle,
k4a_image_format_t target_format);
/** Reads an attachment file from a recording.
*
* \param playback_handle
* Handle obtained by k4a_playback_open().
*
* \param file_name
* The attachment file name.
*
* \param data
* Location to write the attachment data. If a NULL buffer is specified, \p data_size will be set to the size of
* buffer needed to store the data.
*
* \param data_size
* On input, the size of the \p data buffer. On output, this is set to the length of the attachment data.
*
* \returns
* A return of ::K4A_BUFFER_RESULT_SUCCEEDED means that the \p data has been filled in. If the buffer is too small the
* function returns ::K4A_BUFFER_RESULT_TOO_SMALL and the needed size of the \p data buffer is returned in the
* \p data_size parameter. ::K4A_BUFFER_RESULT_FAILED is returned if the attachment \p file_name does not exist. All
* other failures return ::K4A_BUFFER_RESULT_FAILED.
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT k4a_buffer_result_t k4a_playback_get_attachment(k4a_playback_t playback_handle,
const char *file_name,
uint8_t *data,
size_t *data_size);
/** Read the next capture in the recording sequence.
*
* \param playback_handle
* Handle obtained by k4a_playback_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
*
* \returns
* ::K4A_STREAM_RESULT_SUCCEEDED if a capture is returned, or ::K4A_STREAM_RESULT_EOF if the end of the recording is
* reached. All other failures will return ::K4A_STREAM_RESULT_FAILED.
*
* \relates k4a_playback_t
*
* \remarks
* k4a_playback_get_next_capture() always returns the next capture in sequence after the most recently returned capture.
*
* \remarks
* The first call to k4a_playback_get_next_capture() after k4a_playback_seek_timestamp() will return the capture
* in the recording closest to the seek time with an image timestamp greater than or equal to the seek time.
*
* \remarks
* If a call was made to k4a_playback_get_previous_capture() that returned ::K4A_STREAM_RESULT_EOF, the playback
* position is at the beginning of the stream and k4a_playback_get_next_capture() will return the first capture in the
* recording.
*
* \remarks
* Capture objects returned by the playback API will always contain at least one image, but may have images missing if
* frames were dropped in the original recording. When calling k4a_capture_get_color_image(),
* k4a_capture_get_depth_image(), or k4a_capture_get_ir_image(), the image should be checked for NULL.
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_next_capture(k4a_playback_t playback_handle,
k4a_capture_t *capture_handle);
/** Read the previous capture in the recording sequence.
*
* \param playback_handle
* Handle obtained by k4a_playback_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.
*
* \returns
* ::K4A_STREAM_RESULT_SUCCEEDED if a capture is returned, or ::K4A_STREAM_RESULT_EOF if the start of the recording is
* reached. All other failures will return ::K4A_STREAM_RESULT_FAILED.
*
* \relates k4a_playback_t
*
* \remarks
* k4a_playback_get_previous_capture() always returns the previous capture in the sequence before the most
* recently returned capture.
*
* \remarks
* If a call was made to k4a_playback_get_next_capture() that returned ::K4A_STREAM_RESULT_EOF, the playback position
* is at the end of the stream and k4a_playback_get_previous_capture() will return the last capture in
* the recording.
*
* \remarks
* The first call to k4a_playback_get_previous_capture() after k4a_playback_seek_timestamp() will return the
* capture in the recording closest to the seek time with all image timestamps less than the seek time.
*
* \remarks
* Capture objects returned by this API will always contain at least one image, but may have images missing if frames
* were dropped in the original recording. When calling k4a_capture_get_color_image(), k4a_capture_get_depth_image(), or
* k4a_capture_get_ir_image(), the image should be checked for NULL.
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_previous_capture(k4a_playback_t playback_handle,
k4a_capture_t *capture_handle);
/** Read the next IMU sample in the recording sequence.
*
* \param playback_handle
* Handle obtained by k4a_playback_open().
*
* \param imu_sample
* The location to write the IMU sample.
*
* \returns
* ::K4A_STREAM_RESULT_SUCCEEDED if a sample is returned, or ::K4A_STREAM_RESULT_EOF if the end of the recording is
* reached. All other failures will return ::K4A_STREAM_RESULT_FAILED.
*
* \relates k4a_playback_t
*
* \remarks
* k4a_playback_get_next_imu_sample() always returns the IMU sample after the most recently returned sample.
*
* \remarks
* If a call was made to k4a_playback_get_previous_imu_sample() which returned ::K4A_STREAM_RESULT_EOF, then the
* playback position is at the beginning of the recording and k4a_playback_get_next_imu_sample() will return the first
* IMU sample in the recording.
*
* \remarks
* The first call to k4a_playback_get_next_imu_sample() after k4a_playback_seek_timestamp() will return the IMU
* sample in the recording closest to the seek time with a timestamp greater than or equal to the seek time.
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_next_imu_sample(k4a_playback_t playback_handle,
k4a_imu_sample_t *imu_sample);
/** Read the previous IMU sample in the recording sequence.
*
* \param playback_handle
* Handle obtained by k4a_playback_open().
*
* \param imu_sample [OUT]
* The location to write the IMU sample.
*
* \returns
* ::K4A_STREAM_RESULT_SUCCEEDED if a sample is returned, or ::K4A_STREAM_RESULT_EOF if the start of the recording is
* reached. All other failures will return ::K4A_STREAM_RESULT_FAILED.
*
* \relates k4a_playback_t
*
* \remarks
* k4a_playback_get_previous_imu_sample() always returns the IMU sample before the most recently returned sample.
*
* \remarks
* If a call was made to to k4a_playback_get_next_imu_sample() which returned ::K4A_STREAM_RESULT_EOF, then the playback
* position is at the end of the recording and k4a_playback_get_previous_imu_sample() will return the last IMU sample in
* the recording.
*
* \remarks
* The first call to k4a_playback_get_previous_imu_sample() after k4a_playback_seek_timestamp() will return the
* IMU sample closest to the seek time with a timestamp less than the seek time.
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_previous_imu_sample(k4a_playback_t playback_handle,
k4a_imu_sample_t *imu_sample);
/** Read the next data block for a particular track.
*
* \param playback_handle
* Handle obtained by k4a_playback_open().
*
* \param track_name
* The name of the track to read the next data block from.
*
* \param data_block_handle
* The location to write the data block handle.
*
* \returns
* ::K4A_STREAM_RESULT_SUCCEEDED if a data block is returned, or ::K4A_STREAM_RESULT_EOF if the end of the recording is
* reached. All other failures will return ::K4A_STREAM_RESULT_FAILED.
*
* \relates k4a_playback_t
*
* \remarks
* k4a_playback_get_next_data_block() always returns the data block after the most recently returned data block for a
* particular track.
*
* \remarks
* If a call was made to k4a_playback_get_previous_data_block() which returned ::K4A_STREAM_RESULT_EOF, then the
* playback position is at the beginning of the recording and calling k4a_playback_get_next_data_block() with the same
* track will return the first data block in the track.
*
* \remarks
* The first call to k4a_playback_get_next_data_block() after k4a_playback_seek_timestamp() will return the data
* block in the recording closest to the seek time with a timestamp greater than or equal to the seek time.
*
* \remarks
* k4a_playback_get_next_data_block() cannot be used with the built-in tracks: "COLOR", "DEPTH", etc...
* k4a_playback_track_is_builtin() can be used to determine if a track is a built-in track.
*
* \remarks
* If the call is successful, callers must call k4a_playback_data_block_release() to return the allocated memory for
* data_block_handle.
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_next_data_block(k4a_playback_t playback_handle,
const char *track_name,
k4a_playback_data_block_t *data_block_handle);
/** Read the previous data block for a particular track.
*
* \param playback_handle
* Handle obtained by k4a_playback_open().
*
* \param track_name
* The name of the track to read the previous data block from.
*
* \param data_block_handle
* The location to write the data block.
*
* \returns
* ::K4A_STREAM_RESULT_SUCCEEDED if a sample is returned, or ::K4A_STREAM_RESULT_EOF if the start of the recording is
* reached. All other failures will return ::K4A_STREAM_RESULT_FAILED.
*
* \relates k4a_playback_t
*
* \remarks
* k4a_playback_get_previous_data_block() always returns the data block before the most recently returned data block for
* a particular track.
*
* \remarks
* If a call was made to to k4a_playback_get_next_data_block() which returned ::K4A_STREAM_RESULT_EOF, then the playback
* position is at the end of the recording and calling k4a_playback_get_previous_data_block() with the same track will
* return the last data block in the track.
*
* \remarks
* The first call to k4a_playback_get_previous_data_block() after k4a_playback_seek_timestamp() will return the
* data block closest to the seek time with a timestamp less than the seek time.
*
* \remarks
* If the call is successful, callers must call k4a_playback_data_block_release() to return the allocated memory for
* data_block_handle.
*
* \remarks
* k4a_playback_get_previous_data_block() cannot be used with the built-in tracks: "COLOR", "DEPTH", etc...
* k4a_playback_track_is_builtin() can be used to determine if a track is a built-in track.
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_previous_data_block(k4a_playback_t playback_handle,
const char *track_name,
k4a_playback_data_block_t *data_block_handle);
/** Get the device timestamp of a data block in microseconds.
*
* \param data_block_handle
* Handle obtained by k4a_playback_get_next_data_block() or k4a_playback_get_previous_data_block().
*
* \returns
* Returns the device timestamp of the data block. If the \p data_block_handle is invalid this function will return 0.
* It is also possible for 0 to be a valid timestamp originating from when a device was first powered on.
*
* \relates k4a_playback_data_block_t
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT uint64_t
k4a_playback_data_block_get_device_timestamp_usec(k4a_playback_data_block_t data_block_handle);
/** Get the buffer size of a data block.
*
* \param data_block_handle
* Handle obtained by k4a_playback_get_next_data_block() or k4a_playback_get_previous_data_block().
*
* \returns
* Returns the buffer size of the data block, or 0 if the data block is invalid.
*
* \relates k4a_playback_data_block_t
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT size_t k4a_playback_data_block_get_buffer_size(k4a_playback_data_block_t data_block_handle);
/** Get the buffer of a data block.
*
* \param data_block_handle
* Handle obtained by k4a_playback_get_next_data_block() or k4a_playback_get_previous_data_block().
*
* \remarks
* Use this buffer to access the data written to a custom recording track.
*
* \returns
* Returns a pointer to the data block buffer, or NULL if the data block is invalid.
*
* \relates k4a_playback_data_block_t
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT uint8_t *k4a_playback_data_block_get_buffer(k4a_playback_data_block_t data_block_handle);
/** Release a data block handle.
*
* \param data_block_handle
* Handle obtained by k4a_playback_get_next_data_block() or k4a_playback_get_previous_data_block().
*
* \remarks
* Release the memory of a data block. The caller must not access the object after it is released.
*
* \relates k4a_playback_data_block_t
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT void k4a_playback_data_block_release(k4a_playback_data_block_t data_block_handle);
/** Seek to a specific timestamp within a recording.
*
* \param playback_handle
* Handle obtained by k4a_playback_open().
*
* \param offset_usec
* The timestamp offset to seek to, relative to \p origin
*
* \param origin
* Specifies how the given timestamp should be interpreted. Seek can be done relative to the beginning or end of the
* recording, or using an absolute device timestamp.
*
* \returns
* ::K4A_RESULT_SUCCEEDED if the seek operation was successful, or ::K4A_RESULT_FAILED if an error occured. The current
* seek position is left unchanged if a failure is returned.
*
* \relates k4a_playback_t
*
* \remarks
* The first device timestamp in a recording is usually non-zero. The recording file starts at the device timestamp
* defined by start_timestamp_offset_usec, which is accessible via k4a_playback_get_record_configuration().
*
* \remarks
* The first call to k4a_playback_get_next_capture() after k4a_playback_seek_timestamp() will return the first capture
* containing an image timestamp greater than or equal to the seek time.
*
* \remarks
* The first call to k4a_playback_get_previous_capture() after k4a_playback_seek_timestamp() will return the first
* capture with all image timestamps less than the seek time.
*
* \remarks
* The first call to k4a_playback_get_next_imu_sample() after k4a_playback_seek_timestamp() will return the first imu
* sample with a timestamp greter than or equal to the seek time.
*
* \remarks
* The first call to k4a_playback_get_previous_imu_sample() after k4a_playback_seek_timestamp() will return the first
* imu sample with a timestamp less than the seek time.
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT k4a_result_t k4a_playback_seek_timestamp(k4a_playback_t playback_handle,
int64_t offset_usec,
k4a_playback_seek_origin_t origin);
/** Returns the length of the recording in microseconds.
*
* \param playback_handle
* Handle obtained by k4a_playback_open().
*
* \returns
* The recording length, calculated as the difference between the first and last timestamp in the file.
*
* \relates k4a_playback_t
*
* \remarks
* The recording length may be longer than an individual track if, for example, the IMU continues to run after the last
* color image is recorded.
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT uint64_t k4a_playback_get_recording_length_usec(k4a_playback_t playback_handle);
/** Gets the last timestamp in a recording, relative to the start of the recording.
*
* \param playback_handle
* Handle obtained by k4a_playback_open().
*
* \returns
* The file timestamp of the last capture image or IMU sample in microseconds.
*
* \relates k4a_playback_t
*
* \remarks
* This function returns a file timestamp, not an absolute device timestamp, meaning it is relative to the start of the
* recording. This function is equivalent to the length of the recording.
*
* \deprecated
* Deprecated starting in 1.2.0. Please use k4a_playback_get_recording_length_usec().
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_DEPRECATED_EXPORT uint64_t k4a_playback_get_last_timestamp_usec(k4a_playback_t playback_handle);
/** Closes a recording playback handle.
*
* \param playback_handle
* Handle obtained by k4a_playback_open().
*
* \headerfile playback.h <k4arecord/playback.h>
*
* \relates k4a_playback_t
*
* \xmlonly
* <requirements>
* <requirement name="Header">playback.h (include k4arecord/playback.h)</requirement>
* <requirement name="Library">k4arecord.lib</requirement>
* <requirement name="DLL">k4arecord.dll</requirement>
* </requirements>
* \endxmlonly
*/
K4ARECORD_EXPORT void k4a_playback_close(k4a_playback_t playback_handle);
/**
* @}
*/
#ifdef __cplusplus
} // extern "C"
#endif
#endif /* K4A_PLAYBACK_H */