Intel® RealSense™ Cross Platform API  2.13.0
Intel Realsense Cross-platform API
Classes | Typedefs | Enumerations | Functions
rs_frame.h File Reference

Exposes RealSense frame functionality for C compilers. More...

#include "rs_types.h"

Go to the source code of this file.

Classes

struct  rs2_vertex
 3D coordinates with origin at topmost left corner of the lense, with positive Z pointing away from the camera, positive X pointing camera right and positive Y pointing camera down More...
 
struct  rs2_pixel
 Pixel location within 2D image. (0,0) is the topmost, left corner. Positive X is right, positive Y is down. More...
 
struct  rs2_vector
 3D vector in Euclidean coordinate space More...
 
struct  rs2_quaternion
 Quaternion used to represent rotation. More...
 
struct  rs2_pose
 

Typedefs

typedef enum rs2_timestamp_domain rs2_timestamp_domain
 Specifies the clock in relation to which the frame timestamp was measured. More...
 
typedef enum rs2_frame_metadata_value rs2_frame_metadata_value
 Per-Frame-Metadata are set of read-only properties that might be exposed for each individual frame. More...
 
typedef struct rs2_vertex rs2_vertex
 3D coordinates with origin at topmost left corner of the lense, with positive Z pointing away from the camera, positive X pointing camera right and positive Y pointing camera down More...
 
typedef struct rs2_pixel rs2_pixel
 Pixel location within 2D image. (0,0) is the topmost, left corner. Positive X is right, positive Y is down. More...
 
typedef struct rs2_vector rs2_vector
 3D vector in Euclidean coordinate space More...
 
typedef struct rs2_quaternion rs2_quaternion
 Quaternion used to represent rotation. More...
 
typedef struct rs2_pose rs2_pose
 

Enumerations

enum  rs2_timestamp_domain { RS2_TIMESTAMP_DOMAIN_HARDWARE_CLOCK, RS2_TIMESTAMP_DOMAIN_SYSTEM_TIME, RS2_TIMESTAMP_DOMAIN_COUNT }
 Specifies the clock in relation to which the frame timestamp was measured. More...
 
enum  rs2_frame_metadata_value {
  RS2_FRAME_METADATA_FRAME_COUNTER, RS2_FRAME_METADATA_FRAME_TIMESTAMP, RS2_FRAME_METADATA_SENSOR_TIMESTAMP, RS2_FRAME_METADATA_ACTUAL_EXPOSURE,
  RS2_FRAME_METADATA_GAIN_LEVEL, RS2_FRAME_METADATA_AUTO_EXPOSURE, RS2_FRAME_METADATA_WHITE_BALANCE, RS2_FRAME_METADATA_TIME_OF_ARRIVAL,
  RS2_FRAME_METADATA_TEMPERATURE, RS2_FRAME_METADATA_BACKEND_TIMESTAMP, RS2_FRAME_METADATA_ACTUAL_FPS, RS2_FRAME_METADATA_FRAME_LASER_POWER,
  RS2_FRAME_METADATA_FRAME_LASER_POWER_MODE, RS2_FRAME_METADATA_EXPOSURE_PRIORITY, RS2_FRAME_METADATA_EXPOSURE_ROI_LEFT, RS2_FRAME_METADATA_EXPOSURE_ROI_RIGHT,
  RS2_FRAME_METADATA_EXPOSURE_ROI_TOP, RS2_FRAME_METADATA_EXPOSURE_ROI_BOTTOM, RS2_FRAME_METADATA_BRIGHTNESS, RS2_FRAME_METADATA_CONTRAST,
  RS2_FRAME_METADATA_SATURATION, RS2_FRAME_METADATA_SHARPNESS, RS2_FRAME_METADATA_AUTO_WHITE_BALANCE_TEMPERATURE, RS2_FRAME_METADATA_BACKLIGHT_COMPENSATION,
  RS2_FRAME_METADATA_HUE, RS2_FRAME_METADATA_GAMMA, RS2_FRAME_METADATA_MANUAL_WHITE_BALANCE, RS2_FRAME_METADATA_POWER_LINE_FREQUENCY,
  RS2_FRAME_METADATA_LOW_LIGHT_COMPENSATION, RS2_FRAME_METADATA_COUNT
}
 Per-Frame-Metadata are set of read-only properties that might be exposed for each individual frame. More...
 

Functions

const char * rs2_timestamp_domain_to_string (rs2_timestamp_domain info)
 
const char * rs2_frame_metadata_to_string (rs2_frame_metadata_value metadata)
 
const char * rs2_frame_metadata_value_to_string (rs2_frame_metadata_value metadata)
 
rs2_metadata_type rs2_get_frame_metadata (const rs2_frame *frame, rs2_frame_metadata_value frame_metadata, rs2_error **error)
 
int rs2_supports_frame_metadata (const rs2_frame *frame, rs2_frame_metadata_value frame_metadata, rs2_error **error)
 
rs2_timestamp_domain rs2_get_frame_timestamp_domain (const rs2_frame *frameset, rs2_error **error)
 
rs2_time_t rs2_get_frame_timestamp (const rs2_frame *frame, rs2_error **error)
 
unsigned long long rs2_get_frame_number (const rs2_frame *frame, rs2_error **error)
 
const void * rs2_get_frame_data (const rs2_frame *frame, rs2_error **error)
 
int rs2_get_frame_width (const rs2_frame *frame, rs2_error **error)
 
int rs2_get_frame_height (const rs2_frame *frame, rs2_error **error)
 
int rs2_get_frame_stride_in_bytes (const rs2_frame *frame, rs2_error **error)
 
int rs2_get_frame_bits_per_pixel (const rs2_frame *frame, rs2_error **error)
 
void rs2_frame_add_ref (rs2_frame *frame, rs2_error **error)
 
void rs2_release_frame (rs2_frame *frame)
 
void rs2_keep_frame (rs2_frame *frame)
 
rs2_vertexrs2_get_frame_vertices (const rs2_frame *frame, rs2_error **error)
 
void rs2_export_to_ply (const rs2_frame *frame, const char *fname, rs2_frame *texture, rs2_error **error)
 
rs2_pixelrs2_get_frame_texture_coordinates (const rs2_frame *frame, rs2_error **error)
 
int rs2_get_frame_points_count (const rs2_frame *frame, rs2_error **error)
 
const rs2_stream_profilers2_get_frame_stream_profile (const rs2_frame *frame, rs2_error **error)
 
int rs2_is_frame_extendable_to (const rs2_frame *frame, rs2_extension extension_type, rs2_error **error)
 
rs2_framers2_allocate_synthetic_video_frame (rs2_source *source, const rs2_stream_profile *new_stream, rs2_frame *original, int new_bpp, int new_width, int new_height, int new_stride, rs2_extension frame_type, rs2_error **error)
 
rs2_framers2_allocate_composite_frame (rs2_source *source, rs2_frame **frames, int count, rs2_error **error)
 
rs2_framers2_extract_frame (rs2_frame *composite, int index, rs2_error **error)
 
int rs2_embedded_frames_count (rs2_frame *composite, rs2_error **error)
 
void rs2_synthetic_frame_ready (rs2_source *source, rs2_frame *frame, rs2_error **error)
 
void rs2_pose_frame_get_pose_data (const rs2_frame *frame, rs2_pose *pose, rs2_error **error)
 

Detailed Description

Exposes RealSense frame functionality for C compilers.

Typedef Documentation

◆ rs2_frame_metadata_value

Per-Frame-Metadata are set of read-only properties that might be exposed for each individual frame.

◆ rs2_pixel

typedef struct rs2_pixel rs2_pixel

Pixel location within 2D image. (0,0) is the topmost, left corner. Positive X is right, positive Y is down.

◆ rs2_pose

typedef struct rs2_pose rs2_pose

◆ rs2_quaternion

Quaternion used to represent rotation.

◆ rs2_timestamp_domain

Specifies the clock in relation to which the frame timestamp was measured.

◆ rs2_vector

typedef struct rs2_vector rs2_vector

3D vector in Euclidean coordinate space

◆ rs2_vertex

typedef struct rs2_vertex rs2_vertex

3D coordinates with origin at topmost left corner of the lense, with positive Z pointing away from the camera, positive X pointing camera right and positive Y pointing camera down

Enumeration Type Documentation

◆ rs2_frame_metadata_value

Per-Frame-Metadata are set of read-only properties that might be exposed for each individual frame.

Enumerator
RS2_FRAME_METADATA_FRAME_COUNTER 

A sequential index managed per-stream. Integer value

RS2_FRAME_METADATA_FRAME_TIMESTAMP 

Timestamp set by device clock when data readout and transmit commence. usec

RS2_FRAME_METADATA_SENSOR_TIMESTAMP 

Timestamp of the middle of sensor's exposure calculated by device. usec

RS2_FRAME_METADATA_ACTUAL_EXPOSURE 

Sensor's exposure width. When Auto Exposure (AE) is on the value is controlled by firmware. usec

RS2_FRAME_METADATA_GAIN_LEVEL 

A relative value increasing which will increase the Sensor's gain factor. \ When AE is set On, the value is controlled by firmware. Integer value

RS2_FRAME_METADATA_AUTO_EXPOSURE 

Auto Exposure Mode indicator. Zero corresponds to AE switched off.

RS2_FRAME_METADATA_WHITE_BALANCE 

White Balance setting as a color temperature. Kelvin degrees

RS2_FRAME_METADATA_TIME_OF_ARRIVAL 

Time of arrival in system clock

RS2_FRAME_METADATA_TEMPERATURE 

Temperature of the device, measured at the time of the frame capture. Celsius degrees

RS2_FRAME_METADATA_BACKEND_TIMESTAMP 

Timestamp get from uvc driver. usec

RS2_FRAME_METADATA_ACTUAL_FPS 

Actual fps

RS2_FRAME_METADATA_FRAME_LASER_POWER 

Laser power value 0-360.

RS2_FRAME_METADATA_FRAME_LASER_POWER_MODE 

Laser power mode. Zero corresponds to Laser power switched off and one for switched on.

RS2_FRAME_METADATA_EXPOSURE_PRIORITY 

Exposure priority.

RS2_FRAME_METADATA_EXPOSURE_ROI_LEFT 

Left region of interest for the auto exposure Algorithm.

RS2_FRAME_METADATA_EXPOSURE_ROI_RIGHT 

Right region of interest for the auto exposure Algorithm.

RS2_FRAME_METADATA_EXPOSURE_ROI_TOP 

Top region of interest for the auto exposure Algorithm.

RS2_FRAME_METADATA_EXPOSURE_ROI_BOTTOM 

Bottom region of interest for the auto exposure Algorithm.

RS2_FRAME_METADATA_BRIGHTNESS 

Color image brightness.

RS2_FRAME_METADATA_CONTRAST 

Color image contrast.

RS2_FRAME_METADATA_SATURATION 

Color image saturation.

RS2_FRAME_METADATA_SHARPNESS 

Color image sharpness.

RS2_FRAME_METADATA_AUTO_WHITE_BALANCE_TEMPERATURE 

Auto white balance temperature Mode indicator. Zero corresponds to automatic mode switched off.

RS2_FRAME_METADATA_BACKLIGHT_COMPENSATION 

Color backlight compensation. Zero corresponds to switched off.

RS2_FRAME_METADATA_HUE 

Color image hue.

RS2_FRAME_METADATA_GAMMA 

Color image gamma.

RS2_FRAME_METADATA_MANUAL_WHITE_BALANCE 

Color image white balance.

RS2_FRAME_METADATA_POWER_LINE_FREQUENCY 

Power Line Frequency for anti-flickering Off/50Hz/60Hz/Auto.

RS2_FRAME_METADATA_LOW_LIGHT_COMPENSATION 

Color lowlight compensation. Zero corresponds to switched off.

RS2_FRAME_METADATA_COUNT 

◆ rs2_timestamp_domain

Specifies the clock in relation to which the frame timestamp was measured.

Enumerator
RS2_TIMESTAMP_DOMAIN_HARDWARE_CLOCK 

Frame timestamp was measured in relation to the camera clock

RS2_TIMESTAMP_DOMAIN_SYSTEM_TIME 

Frame timestamp was measured in relation to the OS system clock

RS2_TIMESTAMP_DOMAIN_COUNT 

Number of enumeration values. Not a valid input: intended to be used in for-loops.

Function Documentation

◆ rs2_allocate_composite_frame()

rs2_frame* rs2_allocate_composite_frame ( rs2_source source,
rs2_frame **  frames,
int  count,
rs2_error **  error 
)

Allocate new composite frame, aggregating a set of existing frames

Parameters
[in]sourceFrame pool to allocate the frame from
[in]framesArray of existing frames
[in]countNumber of input frames
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
reference to a newly allocated frame, must be released with release_frame when composite frame gets released it will automatically release all of the input frames

◆ rs2_allocate_synthetic_video_frame()

rs2_frame* rs2_allocate_synthetic_video_frame ( rs2_source source,
const rs2_stream_profile new_stream,
rs2_frame original,
int  new_bpp,
int  new_width,
int  new_height,
int  new_stride,
rs2_extension  frame_type,
rs2_error **  error 
)

Allocate new video frame using a frame-source provided form a processing block

Parameters
[in]sourceFrame pool to allocate the frame from
[in]new_streamNew stream profile to assign to newly created frame
[in]originalA reference frame that can be used to fill in auxilary information like format, width, height, bpp, stride (if applicable)
[in]new_bppNew value for bits per pixel for the allocated frame
[in]new_widthNew value for width for the allocated frame
[in]new_heightNew value for height for the allocated frame
[in]new_strideNew value for stride in bytes for the allocated frame
[in]frame_typeNew value for frame type for the allocated frame
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
reference to a newly allocated frame, must be released with release_frame memory for the frame is likely to be re-used from previous frame, but in lack of available frames in the pool will be allocated from the free store

◆ rs2_embedded_frames_count()

int rs2_embedded_frames_count ( rs2_frame composite,
rs2_error **  error 
)

Get number of frames embedded within a composite frame

Parameters
[in]compositeComposite input frame
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
Number of embedded frames

◆ rs2_export_to_ply()

void rs2_export_to_ply ( const rs2_frame frame,
const char *  fname,
rs2_frame texture,
rs2_error **  error 
)

When called on Points frame type, this method creates a ply file of the model with the given file name.

Parameters
[in]framePoints frame
[in]fnameThe name for the ply file
[in]textureTexture frame
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored

◆ rs2_extract_frame()

rs2_frame* rs2_extract_frame ( rs2_frame composite,
int  index,
rs2_error **  error 
)

Extract frame from within a composite frame

Parameters
[in]compositeComposite frame
[in]indexIndex of the frame to extract within the composite frame
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
returns reference to a frame existing within the composite frame If you wish to keep this frame after the composite is released, you need to call acquire_ref Otherwise the resulting frame lifetime is bound by owning composite frame

◆ rs2_frame_add_ref()

void rs2_frame_add_ref ( rs2_frame frame,
rs2_error **  error 
)

create additional reference to a frame without duplicating frame data

Parameters
[in]framehandle returned from a callback
[out]errorif non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
new frame reference, has to be released by rs2_release_frame

◆ rs2_frame_metadata_to_string()

const char* rs2_frame_metadata_to_string ( rs2_frame_metadata_value  metadata)

◆ rs2_frame_metadata_value_to_string()

const char* rs2_frame_metadata_value_to_string ( rs2_frame_metadata_value  metadata)

◆ rs2_get_frame_bits_per_pixel()

int rs2_get_frame_bits_per_pixel ( const rs2_frame frame,
rs2_error **  error 
)

retrieve bits per pixels in the frame image (note that bits per pixel is not necessarily divided by 8, as in 12bpp)

Parameters
[in]framehandle returned from a callback
[out]errorif non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
bits per pixel

◆ rs2_get_frame_data()

const void* rs2_get_frame_data ( const rs2_frame frame,
rs2_error **  error 
)

retrieve data from frame handle

Parameters
[in]framehandle returned from a callback
[out]errorif non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
the pointer to the start of the frame data

◆ rs2_get_frame_height()

int rs2_get_frame_height ( const rs2_frame frame,
rs2_error **  error 
)

retrieve frame height in pixels

Parameters
[in]framehandle returned from a callback
[out]errorif non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
frame height in pixels

◆ rs2_get_frame_metadata()

rs2_metadata_type rs2_get_frame_metadata ( const rs2_frame frame,
rs2_frame_metadata_value  frame_metadata,
rs2_error **  error 
)

retrieve metadata from frame handle

Parameters
[in]framehandle returned from a callback
[in]frame_metadatathe rs2_frame_metadata whose latest frame we are interested in
[out]errorif non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
the metadata value

◆ rs2_get_frame_number()

unsigned long long rs2_get_frame_number ( const rs2_frame frame,
rs2_error **  error 
)

retrieve frame number from frame handle

Parameters
[in]framehandle returned from a callback
[out]errorif non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
the frame nubmer of the frame, in milliseconds since the device was started

◆ rs2_get_frame_points_count()

int rs2_get_frame_points_count ( const rs2_frame frame,
rs2_error **  error 
)

When called on Points frame type, this method returns the number of vertices in the frame

Parameters
[in]framePoints frame
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
Number of vertices

◆ rs2_get_frame_stream_profile()

const rs2_stream_profile* rs2_get_frame_stream_profile ( const rs2_frame frame,
rs2_error **  error 
)

Returns the stream profile that was used to start the stream of this frame

Parameters
[in]frameframe reference, owned by the user
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
Pointer to the stream profile object, lifetime is managed elsewhere

◆ rs2_get_frame_stride_in_bytes()

int rs2_get_frame_stride_in_bytes ( const rs2_frame frame,
rs2_error **  error 
)

retrieve frame stride in bytes (number of bytes from start of line N to start of line N+1)

Parameters
[in]framehandle returned from a callback
[out]errorif non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
stride in bytes

◆ rs2_get_frame_texture_coordinates()

rs2_pixel* rs2_get_frame_texture_coordinates ( const rs2_frame frame,
rs2_error **  error 
)

When called on Points frame type, this method returns a pointer to an array of texture coordinates per vertex Each coordinate represent a (u,v) pair within [0,1] range, to be mapped to texture image

Parameters
[in]framePoints frame
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
Pointer to an array of texture coordinates, lifetime is managed by the frame

◆ rs2_get_frame_timestamp()

rs2_time_t rs2_get_frame_timestamp ( const rs2_frame frame,
rs2_error **  error 
)

retrieve timestamp from frame handle in milliseconds

Parameters
[in]framehandle returned from a callback
[out]errorif non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
the timestamp of the frame in milliseconds

◆ rs2_get_frame_timestamp_domain()

rs2_timestamp_domain rs2_get_frame_timestamp_domain ( const rs2_frame frameset,
rs2_error **  error 
)

retrieve timestamp domain from frame handle. timestamps can only be comparable if they are in common domain (for example, depth timestamp might come from system time while color timestamp might come from the device) this method is used to check if two timestamp values are comparable (generated from the same clock)

Parameters
[in]framesethandle returned from a callback
[out]errorif non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
the timestamp domain of the frame (camera / microcontroller / system time)

◆ rs2_get_frame_vertices()

rs2_vertex* rs2_get_frame_vertices ( const rs2_frame frame,
rs2_error **  error 
)

When called on Points frame type, this method returns a pointer to an array of 3D vertices of the model The coordinate system is: X right, Y up, Z away from the camera. Units: Meters

Parameters
[in]framePoints frame
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
Pointer to an array of vertices, lifetime is managed by the frame

◆ rs2_get_frame_width()

int rs2_get_frame_width ( const rs2_frame frame,
rs2_error **  error 
)

retrieve frame width in pixels

Parameters
[in]framehandle returned from a callback
[out]errorif non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
frame width in pixels

◆ rs2_is_frame_extendable_to()

int rs2_is_frame_extendable_to ( const rs2_frame frame,
rs2_extension  extension_type,
rs2_error **  error 
)

Test if the given frame can be extended to the requested extension

Parameters
[in]frameRealsense frame
[in]extension_typeThe extension to which the frame should be tested if it is extendable
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
non-zero value iff the frame can be extended to the given extension

◆ rs2_keep_frame()

void rs2_keep_frame ( rs2_frame frame)

communicate to the library you intend to keep the frame alive for a while this will remove the frame from the regular count of the frame pool once this function is called, the SDK can no longer guarantee 0-allocations during frame cycling

Parameters
[in]framehandle returned from a callback

◆ rs2_pose_frame_get_pose_data()

void rs2_pose_frame_get_pose_data ( const rs2_frame frame,
rs2_pose pose,
rs2_error **  error 
)

When called on Pose frame type, this method returns the transformation represented by the pose data

Parameters
[in]framePose frame
[out]posePointer to a user allocated struct, which contains the pose info after a successful return
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored

◆ rs2_release_frame()

void rs2_release_frame ( rs2_frame frame)

relases the frame handle

Parameters
[in]framehandle returned from a callback

◆ rs2_supports_frame_metadata()

int rs2_supports_frame_metadata ( const rs2_frame frame,
rs2_frame_metadata_value  frame_metadata,
rs2_error **  error 
)

determine device metadata

Parameters
[in]framehandle returned from a callback
[in]frame_metadatathe metadata to check for support
[out]errorif non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
true if device has this metadata

◆ rs2_synthetic_frame_ready()

void rs2_synthetic_frame_ready ( rs2_source source,
rs2_frame frame,
rs2_error **  error 
)

This method will dispatch frame callback on a frame

Parameters
[in]sourceFrame pool provided by the processing block
[in]frameFrame to dispatch, frame ownership is passed to this function, so you don't have to call release_frame after it
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored

◆ rs2_timestamp_domain_to_string()

const char* rs2_timestamp_domain_to_string ( rs2_timestamp_domain  info)