Frame.h File Reference

Frame related function is mainly used to obtain frame data and frame information. More...

#include "ObTypes.h"

Go to the source code of this file.

Macros
#define	ob_video_frame_metadata   ob_frame_get_metadata
#define	ob_video_frame_metadata_size   ob_frame_get_metadata_size
#define	ob_frame_index   ob_frame_get_index
#define	ob_frame_format   ob_frame_get_format
#define	ob_frame_time_stamp_us   ob_frame_get_timestamp_us
#define	ob_frame_set_device_time_stamp_us   ob_frame_set_timestamp_us
#define	ob_frame_system_time_stamp_us   ob_frame_get_system_timestamp_us
#define	ob_frame_global_time_stamp_us   ob_frame_get_global_timestamp_us
#define	ob_frame_data   ob_frame_get_data
#define	ob_frame_data_size   ob_frame_get_data_size
#define	ob_frame_metadata   ob_frame_get_metadata
#define	ob_frame_metadata_size   ob_frame_get_metadata_size
#define	ob_video_frame_width   ob_video_frame_get_width
#define	ob_video_frame_height   ob_video_frame_get_height
#define	ob_video_frame_pixel_available_bit_size   ob_video_frame_get_pixel_available_bit_size
#define	ob_points_frame_get_position_value_scale   ob_points_frame_get_coordinate_value_scale
#define	ob_frameset_frame_count   ob_frameset_get_count
#define	ob_frameset_depth_frame   ob_frameset_get_depth_frame
#define	ob_frameset_color_frame   ob_frameset_get_color_frame
#define	ob_frameset_ir_frame   ob_frameset_get_ir_frame
#define	ob_frameset_points_frame   ob_frameset_get_points_frame
#define	ob_accel_frame_value   ob_accel_frame_get_value
#define	ob_accel_frame_temperature   ob_accel_frame_get_temperature
#define	ob_gyro_frame_value   ob_gyro_frame_get_value
#define	ob_gyro_frame_temperature   ob_gyro_frame_get_temperature
#define	ob_frameset_get_frame_count   ob_frameset_get_count
#define	ob_frame_time_stamp(frame, err)
#define	ob_frame_system_time_stamp(frame, err)
#define	ob_frame_set_system_time_stamp(frame, system_timestamp, err)
#define	ob_frame_set_device_time_stamp(frame, device_timestamp, err)

Functions
OB_EXPORT ob_frame *	ob_create_frame (ob_frame_type frame_type, ob_format format, uint32_t data_size, ob_error **error)
	Crate a frame object based on the specified parameters.
OB_EXPORT ob_frame *	ob_create_frame_from_other_frame (const ob_frame *other_frame, bool should_copy_data, ob_error **error)
	Create (clone) a frame object based on the specified other frame object.
OB_EXPORT ob_frame *	ob_create_frame_from_stream_profile (const ob_stream_profile *stream_profile, ob_error **error)
	Create a frame object according to the specified stream profile.
OB_EXPORT ob_frame *	ob_create_video_frame (ob_frame_type frame_type, ob_format format, uint32_t width, uint32_t height, uint32_t stride_bytes, ob_error **error)
	Create an video frame object based on the specified parameters.
OB_EXPORT ob_frame *	ob_create_frame_from_buffer (ob_frame_type frame_type, ob_format format, uint8_t *buffer, uint32_t buffer_size, ob_frame_destroy_callback *buffer_destroy_cb, void *buffer_destroy_context, ob_error **error)
	Create a frame object based on an externally created buffer.
OB_EXPORT ob_frame *	ob_create_video_frame_from_buffer (ob_frame_type frame_type, ob_format format, uint32_t width, uint32_t height, uint32_t stride_bytes, uint8_t *buffer, uint32_t buffer_size, ob_frame_destroy_callback *buffer_destroy_cb, void *buffer_destroy_context, ob_error **error)
	Create a video frame object based on an externally created buffer.
OB_EXPORT ob_frame *	ob_create_frameset (ob_error **error)
	Create an empty frameset object.
OB_EXPORT void	ob_frame_add_ref (const ob_frame *frame, ob_error **error)
	Increase the reference count of a frame object.
OB_EXPORT void	ob_delete_frame (const ob_frame *frame, ob_error **error)
	Delete a frame object.
OB_EXPORT void	ob_frame_copy_info (const ob_frame *src_frame, ob_frame *dst_frame, ob_error **error)
	Copy the information of the source frame object to the destination frame object.
OB_EXPORT uint64_t	ob_frame_get_index (const ob_frame *frame, ob_error **error)
	Get the frame index.
OB_EXPORT ob_format	ob_frame_get_format (const ob_frame *frame, ob_error **error)
	Get the frame format.
OB_EXPORT ob_frame_type	ob_frame_get_type (const ob_frame *frame, ob_error **error)
	Get the frame type.
OB_EXPORT uint64_t	ob_frame_get_timestamp_us (const ob_frame *frame, ob_error **error)
	Get the frame timestamp (also known as device timestamp, hardware timestamp) of the frame in microseconds.
OB_EXPORT void	ob_frame_set_timestamp_us (ob_frame *frame, uint64_t timestamp_us, ob_error **error)
	Set the frame timestamp (also known as the device timestamp, hardware timestamp) of a frame object.
OB_EXPORT uint64_t	ob_frame_get_system_timestamp_us (const ob_frame *frame, ob_error **error)
	Get the system timestamp of the frame in microseconds.
OB_EXPORT void	ob_frame_set_system_timestamp_us (ob_frame *frame, uint64_t system_timestamp_us, ob_error **error)
	Set the system timestamp of the frame in microseconds.
OB_EXPORT uint64_t	ob_frame_get_global_timestamp_us (const ob_frame *frame, ob_error **error)
	Get the global timestamp of the frame in microseconds.
OB_EXPORT uint8_t *	ob_frame_get_data (const ob_frame *frame, ob_error **error)
	Get the data buffer of a frame.
OB_EXPORT void	ob_frame_update_data (ob_frame *frame, const uint8_t *data, uint32_t data_size, ob_error **error)
	Update the data of a frame.
OB_EXPORT uint32_t	ob_frame_get_data_size (const ob_frame *frame, ob_error **error)
	Get the frame data size.
OB_EXPORT uint8_t *	ob_frame_get_metadata (const ob_frame *frame, ob_error **error)
	Get the metadata of the frame.
OB_EXPORT uint32_t	ob_frame_get_metadata_size (const ob_frame *frame, ob_error **error)
	Get the metadata size of the frame.
OB_EXPORT void	ob_frame_update_metadata (ob_frame *frame, const uint8_t *metadata, uint32_t metadata_size, ob_error **error)
	Update the metadata of the frame.
OB_EXPORT bool	ob_frame_has_metadata (const ob_frame *frame, ob_frame_metadata_type type, ob_error **error)
	check if the frame contains the specified metadata
OB_EXPORT int64_t	ob_frame_get_metadata_value (const ob_frame *frame, ob_frame_metadata_type type, ob_error **error)
	Get the metadata value of the frame.
OB_EXPORT ob_stream_profile *	ob_frame_get_stream_profile (const ob_frame *frame, ob_error **error)
	Get the stream profile of the frame.
OB_EXPORT void	ob_frame_set_stream_profile (ob_frame *frame, const ob_stream_profile *stream_profile, ob_error **error)
	Set (override) the stream profile of the frame.
OB_EXPORT ob_sensor *	ob_frame_get_sensor (const ob_frame *frame, ob_error **error)
	Get the sensor of the frame.
OB_EXPORT ob_device *	ob_frame_get_device (const ob_frame *frame, ob_error **error)
	Get the device of the frame.
OB_EXPORT uint32_t	ob_video_frame_get_width (const ob_frame *frame, ob_error **error)
	Get video frame width.
OB_EXPORT uint32_t	ob_video_frame_get_height (const ob_frame *frame, ob_error **error)
	Get video frame height.
OB_EXPORT ob_pixel_type	ob_video_frame_get_pixel_type (const ob_frame *frame, ob_error **error)
	Get video frame pixel format.
OB_EXPORT void	ob_video_frame_set_pixel_type (ob_frame *frame, ob_pixel_type pixel_type, ob_error **error)
	Set video frame pixel format.
OB_EXPORT uint8_t	ob_video_frame_get_pixel_available_bit_size (const ob_frame *frame, ob_error **error)
	Get the effective number of pixels (such as Y16 format frame, but only the lower 10 bits are effective bits, and the upper 6 bits are filled with 0)
OB_EXPORT void	ob_video_frame_set_pixel_available_bit_size (ob_frame *frame, uint8_t bit_size, ob_error **error)
	Set the effective number of pixels (such as Y16 format frame, but only the lower 10 bits are effective bits, and the upper 6 bits are filled with 0)
OB_EXPORT ob_sensor_type	ob_ir_frame_get_source_sensor_type (const ob_frame *frame, ob_error **ob_error)
	Get the source sensor type of the ir frame (left or right for dual camera)
OB_EXPORT float	ob_depth_frame_get_value_scale (const ob_frame *frame, ob_error **error)
	Get the value scale of the depth frame. The pixel value of the depth frame is multiplied by the scale to give a depth value in millimeters. For example, if valueScale=0.1 and a certain coordinate pixel value is pixelValue=10000, then the depth value = pixelValue*valueScale = 10000*0.1=1000mm.
OB_EXPORT void	ob_depth_frame_set_value_scale (ob_frame *frame, float value_scale, ob_error **error)
	Set the value scale of the depth frame. The pixel value of the depth frame is multiplied by the scale to give a depth value in millimeters. For example, if valueScale=0.1 and a certain coordinate pixel value is pixelValue=10000, then the depth value = pixelValue*valueScale = 10000*0.1=1000mm.
OB_EXPORT float	ob_points_frame_get_coordinate_value_scale (const ob_frame *frame, ob_error **error)
	Get the point coordinate value scale of the points frame. The point position value of the points frame is multiplied by the scale to give a position value in millimeters. For example, if scale=0.1, the x-coordinate value of a point is x = 10000, which means that the actual x-coordinate value = x*scale = 10000*0.1 = 1000mm.
OB_EXPORT ob_accel_value	ob_accel_frame_get_value (const ob_frame *frame, ob_error **error)
	Get accelerometer frame data.
OB_EXPORT float	ob_accel_frame_get_temperature (const ob_frame *frame, ob_error **error)
	Get the temperature when acquiring the accelerometer frame.
OB_EXPORT ob_gyro_value	ob_gyro_frame_get_value (const ob_frame *frame, ob_error **error)
	Get gyroscope frame data.
OB_EXPORT float	ob_gyro_frame_get_temperature (const ob_frame *frame, ob_error **error)
	Get the temperature when acquiring the gyroscope frame.
OB_EXPORT uint32_t	ob_frameset_get_count (const ob_frame *frameset, ob_error **error)
	Get the number of frames contained in the frameset.
OB_EXPORT ob_frame *	ob_frameset_get_depth_frame (const ob_frame *frameset, ob_error **error)
	Get the depth frame from the frameset.
OB_EXPORT ob_frame *	ob_frameset_get_color_frame (const ob_frame *frameset, ob_error **error)
	Get the color frame from the frameset.
OB_EXPORT ob_frame *	ob_frameset_get_ir_frame (const ob_frame *frameset, ob_error **error)
	Get the infrared frame from the frameset.
OB_EXPORT ob_frame *	ob_frameset_get_points_frame (const ob_frame *frameset, ob_error **error)
	Get point cloud frame from the frameset.
OB_EXPORT ob_frame *	ob_frameset_get_frame (const ob_frame *frameset, ob_frame_type frame_type, ob_error **error)
	Get a frame of a specific type from the frameset.
OB_EXPORT ob_frame *	ob_frameset_get_frame_by_index (const ob_frame *frameset, uint32_t index, ob_error **error)
	Get a frame at a specific index from the FrameSet.
OB_EXPORT void	ob_frameset_push_frame (ob_frame *frameset, const ob_frame *frame, ob_error **error)
	Push a frame to the frameset.
OB_EXPORT uint32_t	ob_point_cloud_frame_get_width (const ob_frame *frame, ob_error **error)
	Get point cloud frame width.
OB_EXPORT uint32_t	ob_point_cloud_frame_get_height (const ob_frame *frame, ob_error **error)
	Get point cloud frame height.

Detailed Description

Frame related function is mainly used to obtain frame data and frame information.

Definition in file Frame.h.

Macro Definition Documentation

ob_video_frame_metadata

#define ob_video_frame_metadata   ob_frame_get_metadata

Definition at line 292 of file Frame.h.

ob_video_frame_metadata_size

#define ob_video_frame_metadata_size   ob_frame_get_metadata_size

Definition at line 302 of file Frame.h.

ob_frame_index

#define ob_frame_index   ob_frame_get_index

Definition at line 625 of file Frame.h.

ob_frame_format

#define ob_frame_format   ob_frame_get_format

Definition at line 626 of file Frame.h.

ob_frame_time_stamp_us

#define ob_frame_time_stamp_us   ob_frame_get_timestamp_us

Definition at line 627 of file Frame.h.

ob_frame_set_device_time_stamp_us

#define ob_frame_set_device_time_stamp_us   ob_frame_set_timestamp_us

Definition at line 628 of file Frame.h.

ob_frame_system_time_stamp_us

#define ob_frame_system_time_stamp_us   ob_frame_get_system_timestamp_us

Definition at line 629 of file Frame.h.

ob_frame_global_time_stamp_us

#define ob_frame_global_time_stamp_us   ob_frame_get_global_timestamp_us

Definition at line 630 of file Frame.h.

ob_frame_data

#define ob_frame_data   ob_frame_get_data

Definition at line 631 of file Frame.h.

ob_frame_data_size

#define ob_frame_data_size   ob_frame_get_data_size

Definition at line 632 of file Frame.h.

ob_frame_metadata

#define ob_frame_metadata   ob_frame_get_metadata

Definition at line 633 of file Frame.h.

ob_frame_metadata_size

#define ob_frame_metadata_size   ob_frame_get_metadata_size

Definition at line 634 of file Frame.h.

ob_video_frame_width

#define ob_video_frame_width   ob_video_frame_get_width

Definition at line 635 of file Frame.h.

ob_video_frame_height

#define ob_video_frame_height   ob_video_frame_get_height

Definition at line 636 of file Frame.h.

ob_video_frame_pixel_available_bit_size

#define ob_video_frame_pixel_available_bit_size   ob_video_frame_get_pixel_available_bit_size

Definition at line 637 of file Frame.h.

ob_points_frame_get_position_value_scale

#define ob_points_frame_get_position_value_scale   ob_points_frame_get_coordinate_value_scale

Definition at line 638 of file Frame.h.

ob_frameset_frame_count

#define ob_frameset_frame_count   ob_frameset_get_count

Definition at line 639 of file Frame.h.

ob_frameset_depth_frame

#define ob_frameset_depth_frame   ob_frameset_get_depth_frame

Definition at line 640 of file Frame.h.

ob_frameset_color_frame

#define ob_frameset_color_frame   ob_frameset_get_color_frame

Definition at line 641 of file Frame.h.

ob_frameset_ir_frame

#define ob_frameset_ir_frame   ob_frameset_get_ir_frame

Definition at line 642 of file Frame.h.

ob_frameset_points_frame

#define ob_frameset_points_frame   ob_frameset_get_points_frame

Definition at line 643 of file Frame.h.

ob_accel_frame_value

#define ob_accel_frame_value   ob_accel_frame_get_value

Definition at line 644 of file Frame.h.

ob_accel_frame_temperature

#define ob_accel_frame_temperature   ob_accel_frame_get_temperature

Definition at line 645 of file Frame.h.

ob_gyro_frame_value

#define ob_gyro_frame_value   ob_gyro_frame_get_value

Definition at line 646 of file Frame.h.

ob_gyro_frame_temperature

#define ob_gyro_frame_temperature   ob_gyro_frame_get_temperature

Definition at line 647 of file Frame.h.

ob_frameset_get_frame_count

#define ob_frameset_get_frame_count   ob_frameset_get_count

Definition at line 648 of file Frame.h.

ob_frame_time_stamp

#define ob_frame_time_stamp	(		frame,
			err )

Value:

(ob_frame_get_timestamp_us(frame, err) / 1000)

Definition at line 650 of file Frame.h.

ob_frame_system_time_stamp

#define ob_frame_system_time_stamp	(		frame,
			err )

Value:

(ob_frame_get_system_timestamp_us(frame, err))

Definition at line 651 of file Frame.h.

ob_frame_set_system_time_stamp

#define ob_frame_set_system_time_stamp	(		frame,
			system_timestamp,
			err )

Value:

(ob_frame_set_system_timestamp_us(frame, system_timestamp * 1000, err))

Definition at line 652 of file Frame.h.

ob_frame_set_device_time_stamp

#define ob_frame_set_device_time_stamp	(		frame,
			device_timestamp,
			err )

Value:

(ob_frame_set_timestamp_us(frame, device_timestamp * 1000, err))

Definition at line 653 of file Frame.h.

Function Documentation

ob_create_frame()

OB_EXPORT ob_frame * ob_create_frame	(	ob_frame_type	frame_type,
		ob_format	format,
		uint32_t	data_size,
		ob_error **	error )

Crate a frame object based on the specified parameters.

Attention

The frame object is created with a reference count of 1, and the reference count should be decreased by calling ob_delete_frame() when it is no longer needed.

Parameters

frame_type	The frame object type.
format	The frame object format.
data_size	The size of the frame object data.
error	Pointer to an error object that will be set if an error occurs.

Returns

ob_frame* Return the frame object.

Referenced by ob::FrameFactory::createFrame().

ob_create_frame_from_other_frame()

OB_EXPORT ob_frame * ob_create_frame_from_other_frame	(	const ob_frame *	other_frame,
		bool	should_copy_data,
		ob_error **	error )

Create (clone) a frame object based on the specified other frame object.

The new frame object will have the same properties as the other frame object, but the data buffer is newly allocated.

Attention

The frame object is created with a reference count of 1, and the reference count should be decreased by calling ob_delete_frame() when it is no longer needed.

Parameters

[in]	other_frame	The frame object to create the new frame object according to.
[in]	should_copy_data	If true, the data of the source frame object will be copied to the new frame object. If false, the new frame object will have a data buffer with random data.
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

ob_frame* Return the new frame object.

Referenced by ob::FrameFactory::createFrameFromOtherFrame().

ob_create_frame_from_stream_profile()

OB_EXPORT ob_frame * ob_create_frame_from_stream_profile	(	const ob_stream_profile *	stream_profile,
		ob_error **	error )

Create a frame object according to the specified stream profile.

Attention

The frame object is created with a reference count of 1, and the reference count should be decreased by calling ob_delete_frame() when it is no logger needed.

Parameters

stream_profile	The stream profile to create the new frame object according to.
error	Pointer to an error object that will be set if an error occurs.

Returns

ob_frame* Return the new frame object.

Referenced by ob::FrameFactory::createFrameFromStreamProfile().

ob_create_video_frame()

OB_EXPORT ob_frame * ob_create_video_frame	(	ob_frame_type	frame_type,
		ob_format	format,
		uint32_t	width,
		uint32_t	height,
		uint32_t	stride_bytes,
		ob_error **	error )

Create an video frame object based on the specified parameters.

Attention

The frame object is created with a reference count of 1, and the reference count should be decreased by calling ob_delete_frame() when it is no longer needed.

Parameters

[in]	frame_type	Frame object type.
[in]	format	Frame object format.
[in]	width	Frame object width.
[in]	height	Frame object height.
[in]	stride_bytes	Row span in bytes. If 0, the stride is calculated based on the width and format.
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

ob_frame* Return an empty frame object.

Referenced by ob::FrameFactory::createVideoFrame().

ob_create_frame_from_buffer()

OB_EXPORT ob_frame * ob_create_frame_from_buffer	(	ob_frame_type	frame_type,
		ob_format	format,
		uint8_t *	buffer,
		uint32_t	buffer_size,
		ob_frame_destroy_callback *	buffer_destroy_cb,
		void *	buffer_destroy_context,
		ob_error **	error )

Create a frame object based on an externally created buffer.

Attention

The buffer is owned by the user and will not be destroyed by the frame object. The user should ensure that the buffer is valid and not modified.

The frame object is created with a reference count of 1, and the reference count should be decreased by calling ob_delete_frame() when it is no longer needed.

Parameters

[in]	frame_type	Frame object type.
[in]	format	Frame object format.
[in]	buffer	Frame object buffer.
[in]	buffer_size	Frame object buffer size.
[in]	buffer_destroy_cb	Destroy callback, will be called when the frame object is destroyed.
[in]	buffer_destroy_context	Destroy context, user-defined context to be passed to the destroy callback.
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

ob_frame* Return the frame object.

Referenced by ob::FrameFactory::createFrameFromBuffer().

ob_create_video_frame_from_buffer()

OB_EXPORT ob_frame * ob_create_video_frame_from_buffer	(	ob_frame_type	frame_type,
		ob_format	format,
		uint32_t	width,
		uint32_t	height,
		uint32_t	stride_bytes,
		uint8_t *	buffer,
		uint32_t	buffer_size,
		ob_frame_destroy_callback *	buffer_destroy_cb,
		void *	buffer_destroy_context,
		ob_error **	error )

Create a video frame object based on an externally created buffer.

Attention

The buffer is owned by the user and will not be destroyed by the frame object. The user should ensure that the buffer is valid and not modified.

The frame object is created with a reference count of 1, and the reference count should be decreased by calling ob_delete_frame() when it is no longer needed.

Parameters

[in]	frame_type	Frame object type.
[in]	format	Frame object format.
[in]	width	Frame object width.
[in]	height	Frame object height.
[in]	stride_bytes	Row span in bytes. If 0, the stride is calculated based on the width and format.
[in]	buffer	Frame object buffer.
[in]	buffer_size	Frame object buffer size.
[in]	buffer_destroy_cb	Destroy callback, user-defined function to destroy the buffer.
[in]	buffer_destroy_context	Destroy context, user-defined context to be passed to the destroy callback.
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

ob_frame* Return the frame object.

Referenced by ob::FrameFactory::createVideoFrameFromBuffer().

ob_create_frameset()

OB_EXPORT ob_frame * ob_create_frameset

(

ob_error **

error

)

Create an empty frameset object.

A frameset object is a special type of frame object that can be used to store multiple frames.

Attention

The frameset object is created with a reference count of 1, and the reference count should be decreased by calling ob_delete_frame() when it is no longer needed.

Parameters

[out]

error

Pointer to an error object that will be set if an error occurs.

Returns

ob_frame* Return the frameset object.

Referenced by ob::FrameFactory::createFrameSet().

ob_frame_add_ref()

OB_EXPORT void ob_frame_add_ref	(	const ob_frame *	frame,
		ob_error **	error )

Increase the reference count of a frame object.

The reference count is used to manage the lifetime of the frame object.

Attention

When calling this function, the reference count of the frame object is increased and requires to be decreased by calling ob_delete_frame().

Parameters

[in]	frame	Frame object to increase the reference count.
[out]	error	Pointer to an error object that will be set if an error occurs.

Referenced by ob::Frame::as(), and ob::Frame::as().

ob_delete_frame()

OB_EXPORT void ob_delete_frame	(	const ob_frame *	frame,
		ob_error **	error )

Delete a frame object.

This function will decrease the reference count of the frame object and release the memory if the reference count becomes 0.

Parameters

[in]	frame	The frame object to delete.
[out]	error	Pointer to an error object that will be set if an error occurs.

Referenced by ob::Frame::~Frame().

ob_frame_copy_info()

OB_EXPORT void ob_frame_copy_info	(	const ob_frame *	src_frame,
		ob_frame *	dst_frame,
		ob_error **	error )

Copy the information of the source frame object to the destination frame object.

Including the index, timestamp, system timestamp, global timestamp and metadata will be copied.

Parameters

[in]	src_frame	Source frame object to copy the information from.
[in]	dst_frame	Destination frame object to copy the information to.
[out]	error	Pointer to an error object that will be set if an error occurs.

ob_frame_get_index()

OB_EXPORT uint64_t ob_frame_get_index	(	const ob_frame *	frame,
		ob_error **	error )

Get the frame index.

Parameters

[in]	frame	Frame object
[out]	error	Log wrong message

Returns

uint64_t return the frame index

Referenced by ob::Frame::getIndex().

ob_frame_get_format()

OB_EXPORT ob_format ob_frame_get_format	(	const ob_frame *	frame,
		ob_error **	error )

Get the frame format.

Parameters

[in]	frame	Frame object
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

ob_format return the frame format

Referenced by ob::Frame::getFormat().

ob_frame_get_type()

OB_EXPORT ob_frame_type ob_frame_get_type	(	const ob_frame *	frame,
		ob_error **	error )

Get the frame type.

Parameters

[in]	frame	Frame object
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

ob_frame_type return the frame type

Referenced by ob::Frame::getType().

ob_frame_get_timestamp_us()

OB_EXPORT uint64_t ob_frame_get_timestamp_us	(	const ob_frame *	frame,
		ob_error **	error )

Get the frame timestamp (also known as device timestamp, hardware timestamp) of the frame in microseconds.

The hardware timestamp is the time point when the frame was captured by the device (Typically in the mid-exposure, unless otherwise stated), on device clock domain.

Parameters

[in]	frame	Frame object
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

uint64_t return the frame hardware timestamp in microseconds

Referenced by ob::Frame::getTimeStampUs().

ob_frame_set_timestamp_us()

OB_EXPORT void ob_frame_set_timestamp_us	(	ob_frame *	frame,
		uint64_t	timestamp_us,
		ob_error **	error )

Set the frame timestamp (also known as the device timestamp, hardware timestamp) of a frame object.

Parameters

[in]	frame	Frame object to set the timestamp.
[in]	timestamp_us	frame timestamp to set in microseconds.
[out]	error	Pointer to an error object that will be set if an error occurs.

Referenced by ob::FrameHelper::setFrameDeviceTimestampUs().

ob_frame_get_system_timestamp_us()

OB_EXPORT uint64_t ob_frame_get_system_timestamp_us	(	const ob_frame *	frame,
		ob_error **	error )

Get the system timestamp of the frame in microseconds.

The system timestamp is the time point when the frame was received by the host, on host clock domain.

Parameters

[in]	frame	Frame object
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

uint64_t return the frame system timestamp in microseconds

Referenced by ob::Frame::getSystemTimeStampUs().

ob_frame_set_system_timestamp_us()

OB_EXPORT void ob_frame_set_system_timestamp_us	(	ob_frame *	frame,
		uint64_t	system_timestamp_us,
		ob_error **	error )

Set the system timestamp of the frame in microseconds.

Parameters

frame	Frame object
system_timestamp_us	frame system timestamp to set in microseconds.
error	Pointer to an error object that will be set if an error occurs.

ob_frame_get_global_timestamp_us()

OB_EXPORT uint64_t ob_frame_get_global_timestamp_us	(	const ob_frame *	frame,
		ob_error **	error )

Get the global timestamp of the frame in microseconds.

The global timestamp is the time point when the frame was captured by the device, and has been converted to the host clock domain. The conversion process base on the frame timestamp and can eliminate the timer drift of the device

Attention

The global timestamp is disabled by default. If global timestamp is not enabled, the function will return 0. To enable it, call ob_device_enable_global_timestamp() function.

Only some models of device support getting the global timestamp. Check the device support status by ob_device_is_global_timestamp_supported() function.

Parameters

[in]	frame	Frame object
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

uint64_t The global timestamp of the frame in microseconds.

Referenced by ob::Frame::getGlobalTimeStampUs().

ob_frame_get_data()

OB_EXPORT uint8_t * ob_frame_get_data	(	const ob_frame *	frame,
		ob_error **	error )

Get the data buffer of a frame.

Attention

The returned data buffer is mutable, but it is not recommended to modify it directly. Modifying the data directly may cause issues if the frame is being used in other threads or future use. If you need to modify the data, it is recommended to create a new frame object.

Parameters

[in]	frame	The frame object from which to retrieve the data.
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

uint8_t* Pointer to the frame data buffer.

Referenced by ob::Frame::getData().

ob_frame_update_data()

OB_EXPORT void ob_frame_update_data	(	ob_frame *	frame,
		const uint8_t *	data,
		uint32_t	data_size,
		ob_error **	error )

Update the data of a frame.

The data will be memcpy to the frame data buffer.

The frame data size will be also updated as the input data size.

Attention

It is not recommended to update the frame data if the frame was not created by the user. If you must update it, ensure that the frame is not being used in other threads.

The size of the new data should be equal to or less than the current data size of the frame. Exceeding the original size may cause memory exceptions.

Parameters

[in]	frame	The frame object to update.
[in]	data	The new data to update the frame with.
[in]	data_size	The size of the new data.
[out]	error	Pointer to an error object that will be set if an error occurs.

ob_frame_get_data_size()

OB_EXPORT uint32_t ob_frame_get_data_size	(	const ob_frame *	frame,
		ob_error **	error )

Get the frame data size.

Parameters

[in]	frame	Frame object
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

uint32_t return the frame data size If it is point cloud data, it return the number of bytes occupied by all point sets. If you need to find the number of points, you need to divide dataSize by the structure size of the corresponding point type.

Referenced by ob::Frame::getDataSize().

ob_frame_get_metadata()

OB_EXPORT uint8_t * ob_frame_get_metadata	(	const ob_frame *	frame,
		ob_error **	error )

Get the metadata of the frame.

Attention

The returned metadata is mutable, but it is not recommended to modify it directly. Modifying the metadata directly may cause issues if the frame is being used in other threads or future use. If you need to modify the metadata, it is recommended to create a new frame object.

Parameters

[in]	frame	frame object
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

const uint8_t * return the metadata pointer of the frame

Referenced by ob::Frame::getMetadata().

ob_frame_get_metadata_size()

OB_EXPORT uint32_t ob_frame_get_metadata_size	(	const ob_frame *	frame,
		ob_error **	error )

Get the metadata size of the frame.

Parameters

[in]	frame	frame object
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

uint32_t return the metadata size of the frame

Referenced by ob::Frame::getMetadataSize().

ob_frame_update_metadata()

OB_EXPORT void ob_frame_update_metadata	(	ob_frame *	frame,
		const uint8_t *	metadata,
		uint32_t	metadata_size,
		ob_error **	error )

Update the metadata of the frame.

The metadata will be memcpy to the frame metadata buffer.

The frame metadata size will be also updated as the input metadata size.

Attention

It is not recommended to update the frame metadata if the frame was not created by the user. If you must update it, ensure that the frame is not being used in other threads or future use.

The metadata size should be equal to or less than 256 bytes, otherwise it will cause memory exception.

Parameters

[in]	frame	frame object
[in]	metadata	The new metadata to update.
[in]	metadata_size	The size of the new metadata.
[out]	error	Pointer to an error object that will be set if an error occurs.

ob_frame_has_metadata()

OB_EXPORT bool ob_frame_has_metadata	(	const ob_frame *	frame,
		ob_frame_metadata_type	type,
		ob_error **	error )

check if the frame contains the specified metadata

Parameters

[in]	frame	frame object
[in]	type	metadata type, refer to ob_frame_metadata_type
[out]	error	Pointer to an error object that will be set if an error occurs.

Referenced by ob::Frame::hasMetadata().

ob_frame_get_metadata_value()

OB_EXPORT int64_t ob_frame_get_metadata_value	(	const ob_frame *	frame,
		ob_frame_metadata_type	type,
		ob_error **	error )

Get the metadata value of the frame.

Parameters

[in]	frame	frame object
[in]	type	metadata type, refer to ob_frame_metadata_type
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

int64_t return the metadata value of the frame

Referenced by ob::Frame::getMetadataValue().

ob_frame_get_stream_profile()

OB_EXPORT ob_stream_profile * ob_frame_get_stream_profile	(	const ob_frame *	frame,
		ob_error **	error )

Get the stream profile of the frame.

Attention

Require ob_delete_stream_profile() to release the return stream profile.

Parameters

frame	frame object
error	Pointer to an error object that will be set if an error occurs.

Returns

ob_stream_profile* Return the stream profile of the frame, if the frame is not captured by a sensor stream, it will return NULL

Referenced by ob::Frame::getStreamProfile().

ob_frame_set_stream_profile()

OB_EXPORT void ob_frame_set_stream_profile	(	ob_frame *	frame,
		const ob_stream_profile *	stream_profile,
		ob_error **	error )

Set (override) the stream profile of the frame.

Parameters

frame	frame object
stream_profile	The stream profile to set for the frame.
error	Pointer to an error object that will be set if an error occurs.

ob_frame_get_sensor()

OB_EXPORT ob_sensor * ob_frame_get_sensor	(	const ob_frame *	frame,
		ob_error **	error )

Get the sensor of the frame.

Attention

Require ob_delete_sensor() to release the return sensor.

Parameters

[in]	frame	frame object
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

ob_sensor* return the sensor of the frame, if the frame is not captured by a sensor or the sensor stream has been destroyed, it will return NULL

Referenced by ob::Frame::getSensor().

ob_frame_get_device()

OB_EXPORT ob_device * ob_frame_get_device	(	const ob_frame *	frame,
		ob_error **	error )

Get the device of the frame.

Attention

Require ob_delete_device() to release the return device.

Parameters

	frame	frame object
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

ob_device* return the device of the frame, if the frame is not captured by a sensor stream or the device has been destroyed, it will return NULL

Referenced by ob::Frame::getDevice().

ob_video_frame_get_width()

OB_EXPORT uint32_t ob_video_frame_get_width	(	const ob_frame *	frame,
		ob_error **	error )

Get video frame width.

Parameters

[in]	frame	Frame object
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

uint32_t return the frame width

Referenced by ob::VideoFrame::getWidth().

ob_video_frame_get_height()

OB_EXPORT uint32_t ob_video_frame_get_height	(	const ob_frame *	frame,
		ob_error **	error )

Get video frame height.

Parameters

[in]	frame	Frame object
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

uint32_t return the frame height

Referenced by ob::VideoFrame::getHeight().

ob_video_frame_get_pixel_type()

OB_EXPORT ob_pixel_type ob_video_frame_get_pixel_type	(	const ob_frame *	frame,
		ob_error **	error )

Get video frame pixel format.

Usually used to determine the pixel type of depth frame (depth, disparity, raw phase, etc.)

Attention

Always return OB_PIXEL_UNKNOWN for non-depth frame currently if user has not set the pixel type by ob_video_frame_set_pixel_type()

Parameters

frame	Frame object
error	Pointer to an error object that will be set if an error occurs.

Returns

ob_pixel_type return the pixel format of the frame.

Referenced by ob::VideoFrame::getPixelType().

ob_video_frame_set_pixel_type()

OB_EXPORT void ob_video_frame_set_pixel_type	(	ob_frame *	frame,
		ob_pixel_type	pixel_type,
		ob_error **	error )

Set video frame pixel format.

Parameters

frame	Frame object
pixel_type	the pixel format of the frame
error	Pointer to an error object that will be set if an error occurs.

ob_video_frame_get_pixel_available_bit_size()

OB_EXPORT uint8_t ob_video_frame_get_pixel_available_bit_size	(	const ob_frame *	frame,
		ob_error **	error )

Get the effective number of pixels (such as Y16 format frame, but only the lower 10 bits are effective bits, and the upper 6 bits are filled with 0)

Attention

Only valid for Y8/Y10/Y11/Y12/Y14/Y16 format

Parameters

[in]	frame	video frame object
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

uint8_t return the effective number of pixels in the pixel, or 0 if it is an unsupported format

Referenced by ob::VideoFrame::getPixelAvailableBitSize().

ob_video_frame_set_pixel_available_bit_size()

OB_EXPORT void ob_video_frame_set_pixel_available_bit_size	(	ob_frame *	frame,
		uint8_t	bit_size,
		ob_error **	error )

Set the effective number of pixels (such as Y16 format frame, but only the lower 10 bits are effective bits, and the upper 6 bits are filled with 0)

Attention

Only valid for Y8/Y10/Y11/Y12/Y14/Y16 format

Parameters

[in]	frame	video frame object
[in]	bit_size	the effective number of pixels in the pixel, or 0 if it is an unsupported format
[out]	error	Pointer to an error object that will be set if an error occurs.

ob_ir_frame_get_source_sensor_type()

OB_EXPORT ob_sensor_type ob_ir_frame_get_source_sensor_type	(	const ob_frame *	frame,
		ob_error **	ob_error )

Get the source sensor type of the ir frame (left or right for dual camera)

Parameters

frame	Frame object
ob_error	Pointer to an error object that will be set if an error occurs.

Returns

ob_sensor_type return the source sensor type of the ir frame

ob_depth_frame_get_value_scale()

OB_EXPORT float ob_depth_frame_get_value_scale	(	const ob_frame *	frame,
		ob_error **	error )

Get the value scale of the depth frame. The pixel value of the depth frame is multiplied by the scale to give a depth value in millimeters. For example, if valueScale=0.1 and a certain coordinate pixel value is pixelValue=10000, then the depth value = pixelValue*valueScale = 10000*0.1=1000mm.

Parameters

[in]	frame	Frame object
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

float The value scale of the depth frame

Referenced by ob::DepthFrame::getValueScale().

ob_depth_frame_set_value_scale()

OB_EXPORT void ob_depth_frame_set_value_scale	(	ob_frame *	frame,
		float	value_scale,
		ob_error **	error )

Set the value scale of the depth frame. The pixel value of the depth frame is multiplied by the scale to give a depth value in millimeters. For example, if valueScale=0.1 and a certain coordinate pixel value is pixelValue=10000, then the depth value = pixelValue*valueScale = 10000*0.1=1000mm.

Parameters

[in]	frame	Frame object
[in]	value_scale	The value scale of the depth frame
[out]	error	Pointer to an error object that will be set if an error occurs.

ob_points_frame_get_coordinate_value_scale()

OB_EXPORT float ob_points_frame_get_coordinate_value_scale	(	const ob_frame *	frame,
		ob_error **	error )

Get the point coordinate value scale of the points frame. The point position value of the points frame is multiplied by the scale to give a position value in millimeters. For example, if scale=0.1, the x-coordinate value of a point is x = 10000, which means that the actual x-coordinate value = x*scale = 10000*0.1 = 1000mm.

Parameters

[in]	frame	Frame object
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

float The coordinate value scale of the points frame

Referenced by ob::PointsFrame::getCoordinateValueScale().

ob_accel_frame_get_value()

OB_EXPORT ob_accel_value ob_accel_frame_get_value	(	const ob_frame *	frame,
		ob_error **	error )

Get accelerometer frame data.

Parameters

[in]	frame	Accelerometer frame.
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

ob_accel_value Return the accelerometer data.

Referenced by ob::AccelFrame::getValue().

ob_accel_frame_get_temperature()

OB_EXPORT float ob_accel_frame_get_temperature	(	const ob_frame *	frame,
		ob_error **	error )

Get the temperature when acquiring the accelerometer frame.

Parameters

[in]	frame	Accelerometer frame.
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

float Return the temperature value.

Referenced by ob::AccelFrame::getTemperature().

ob_gyro_frame_get_value()

OB_EXPORT ob_gyro_value ob_gyro_frame_get_value	(	const ob_frame *	frame,
		ob_error **	error )

Get gyroscope frame data.

Parameters

[in]	frame	Gyroscope frame.
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

ob_gyro_value Return the gyroscope data.

Referenced by ob::GyroFrame::getValue().

ob_gyro_frame_get_temperature()

OB_EXPORT float ob_gyro_frame_get_temperature	(	const ob_frame *	frame,
		ob_error **	error )

Get the temperature when acquiring the gyroscope frame.

Parameters

[in]	frame	Gyroscope frame.
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

float Return the temperature value.

Referenced by ob::GyroFrame::getTemperature().

ob_frameset_get_count()

OB_EXPORT uint32_t ob_frameset_get_count	(	const ob_frame *	frameset,
		ob_error **	error )

Get the number of frames contained in the frameset.

Attention

The frame returned by this function should call ob_delete_frame() to decrease the reference count when it is no longer needed.

Parameters

[in]	frameset	frameset object
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

uint32_t return the number of frames

Referenced by ob::FrameSet::getCount().

ob_frameset_get_depth_frame()

OB_EXPORT ob_frame * ob_frameset_get_depth_frame	(	const ob_frame *	frameset,
		ob_error **	error )

Get the depth frame from the frameset.

Attention

The frame returned by this function should call ob_delete_frame() to decrease the reference count when it is no longer needed.

Parameters

[in]	frameset	Frameset object.
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

ob_frame* Return the depth frame.

ob_frameset_get_color_frame()

OB_EXPORT ob_frame * ob_frameset_get_color_frame	(	const ob_frame *	frameset,
		ob_error **	error )

Get the color frame from the frameset.

Attention

The frame returned by this function should call ob_delete_frame() to decrease the reference count when it is no longer needed.

Parameters

[in]	frameset	Frameset object.
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

ob_frame* Return the color frame.

ob_frameset_get_ir_frame()

OB_EXPORT ob_frame * ob_frameset_get_ir_frame	(	const ob_frame *	frameset,
		ob_error **	error )

Get the infrared frame from the frameset.

Attention

The frame returned by this function should call ob_delete_frame() to decrease the reference count when it is no longer needed.

Parameters

[in]	frameset	Frameset object.
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

ob_frame* Return the infrared frame.

ob_frameset_get_points_frame()

OB_EXPORT ob_frame * ob_frameset_get_points_frame	(	const ob_frame *	frameset,
		ob_error **	error )

Get point cloud frame from the frameset.

Attention

The frame returned by this function should call ob_delete_frame() to decrease the reference count when it is no longer needed.

Parameters

[in]	frameset	Frameset object.
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

ob_frame* Return the point cloud frame.

ob_frameset_get_frame()

OB_EXPORT ob_frame * ob_frameset_get_frame	(	const ob_frame *	frameset,
		ob_frame_type	frame_type,
		ob_error **	error )

Get a frame of a specific type from the frameset.

Attention

The frame returned by this function should call ob_delete_frame() to decrease the reference count when it is no longer needed.

Parameters

[in]	frameset	Frameset object.
[in]	frame_type	Frame type.
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

ob_frame* Return the frame of the specified type, or nullptr if it does not exist.

Referenced by ob::FrameSet::getFrame().

ob_frameset_get_frame_by_index()

OB_EXPORT ob_frame * ob_frameset_get_frame_by_index	(	const ob_frame *	frameset,
		uint32_t	index,
		ob_error **	error )

Get a frame at a specific index from the FrameSet.

Parameters

[in]	frameset	Frameset object.
[in]	index	The index of the frame.
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

ob_frame* Return the frame at the specified index, or nullptr if it does not exist.

Referenced by ob::FrameSet::getFrameByIndex().

ob_frameset_push_frame()

OB_EXPORT void ob_frameset_push_frame	(	ob_frame *	frameset,
		const ob_frame *	frame,
		ob_error **	error )

Push a frame to the frameset.

Attention

If a frame with same type already exists in the frameset, it will be replaced by the new frame.

The frame push to the frameset will be add reference count, so you still need to call ob_delete_frame() to decrease the reference count when it is no longer needed.

Parameters

[in]	frameset	Frameset object.
[in]	frame	Frame object to push.
[out]	error	Pointer to an error object that will be set if an error occurs.

Referenced by ob::FrameSet::pushFrame().

ob_point_cloud_frame_get_width()

OB_EXPORT uint32_t ob_point_cloud_frame_get_width	(	const ob_frame *	frame,
		ob_error **	error )

Get point cloud frame width.

Parameters

[in]	frame	point cloud Frame object
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

uint32_t return the point cloud frame width

Referenced by ob::PointsFrame::getWidth().

ob_point_cloud_frame_get_height()

OB_EXPORT uint32_t ob_point_cloud_frame_get_height	(	const ob_frame *	frame,
		ob_error **	error )

Get point cloud frame height.

Parameters

[in]	frame	point cloud Frame object
[out]	error	Pointer to an error object that will be set if an error occurs.

Returns

uint32_t return the point cloud frame height

Referenced by ob::PointsFrame::getHeight().