video_frame.h
This file includes the type definition for a video frame along with several function declarations useful when handling them.
Data structures: otc_video_frame_planar_memory_callbacks
Includes: unistd.h, base.h, config.h
typedef otc_video_frame
Video frame type definition.
typedef struct otc_video_frame otc_video_frame;
typedef otc_video_frame_memory_release_callback
Type definition for the video frame memory release callback function.
This is a function pointer to the callback function that is called when the app should release the memory holding a video frame.
typedef void(*) otc_video_frame_memory_release_callback(const uint8_t *buffer, void *arg)(const uint8_t *buffer, void *arg);
typedef video_transform_callback
Note: This functionality only applies to the Vonage Video API macOS SDK. It does not work in the Vonage Video API Linux SDK.
typedef void(*) video_transform_callback(void *user_data, struct otc_video_frame *frame)(void *user_data, struct otc_video_frame *frame);
enum otc_video_frame_format
Video frame video format enumeration.
This enumeration represents several video frame formats.
| Name | Value | Description |
|---|---|---|
OTC_VIDEO_FRAME_FORMAT_UNKNOWN |
0 |
Uknown video frame format enum value. |
OTC_VIDEO_FRAME_FORMAT_YUV420P |
1 |
YUV420P video frame format enum value. |
OTC_VIDEO_FRAME_FORMAT_NV12 |
2 |
NV12 video frame format enum value. |
OTC_VIDEO_FRAME_FORMAT_NV21 |
3 |
NV21 video frame format enum value. |
OTC_VIDEO_FRAME_FORMAT_YUY2 |
4 |
YUY2 video frame format enum value. |
OTC_VIDEO_FRAME_FORMAT_UYVY |
5 |
UYVY video frame format enum value. |
OTC_VIDEO_FRAME_FORMAT_ARGB32 |
6 |
ARGB32 video frame format enum value. |
OTC_VIDEO_FRAME_FORMAT_BGRA32 |
7 |
BGRA32 video frame format enum value. |
OTC_VIDEO_FRAME_FORMAT_RGB24 |
8 |
RGB24 video frame format enum value. |
OTC_VIDEO_FRAME_FORMAT_ABGR32 |
9 |
ABGR32 video frame format enum value. |
OTC_VIDEO_FRAME_FORMAT_MJPEG |
10 |
MJPEG video frame format enum value. |
OTC_VIDEO_FRAME_FORMAT_RGBA32 |
11 |
RGBA video frame format enum value. |
OTC_VIDEO_FRAME_FORMAT_MAX |
Maxinum value. | |
OTC_VIDEO_FRAME_FORMAT_COMPRESSED |
255 |
Compressed video frame format enum value. |
enum otc_video_frame_plane
Video frame video plane enumeration.
| Name | Value | Description |
|---|---|---|
OTC_VIDEO_FRAME_PLANE_Y |
0 |
Video frame plane Y enum value. |
OTC_VIDEO_FRAME_PLANE_U |
1 |
Video frame plane U enum value. |
OTC_VIDEO_FRAME_PLANE_V |
2 |
Video frame plane V enum value. |
OTC_VIDEO_FRAME_PLANE_PACKED |
0 |
Video frame plane packed enum value. |
OTC_VIDEO_FRAME_PLANE_UV_INTERLEAVED |
1 |
Video frame plane UV interleaved enum value. |
OTC_VIDEO_FRAME_PLANE_VU_INTERLEAVED |
1 |
Video frame plane VU interleaved enum value. |
Functions
| Name | Description |
|---|---|
otc_video_frame_get_native_handle(frame) → {void *} |
|
otc_video_frame_new(format, width, height, buffer) → {otc_video_frame *} |
Creates a new video frame with a given format. |
otc_video_frame_delete(frame) → {otc_status} |
Free resources associated with the frame. |
otc_video_frame_new_I420(width, height, y_plane, y_stride, u_plane, u_stride, v_plane, v_stride) → {otc_video_frame *} |
Creates a new video frame with I420 format. |
otc_video_frame_new_MJPEG(width, height, buffer, size) → {otc_video_frame *} |
Creates a new video frame with MJPEG format. |
otc_video_frame_new_compressed(width, height, buffer, size) → {otc_video_frame *} |
Creates a new compressed video frame. |
otc_video_frame_new_from_planes(format, width, height, planes, strides) → {otc_video_frame *} |
Creates a new video frame with a given format from its planes. |
otc_video_frame_new_I420_from_planes_with_format(input_format, width, height, planes, strides) → {otc_video_frame *} |
Creates a new video frame with I420 format from a list of planes. |
otc_video_frame_new_contiguous_memory_wrapper(format, width, height, is_shallow_copyable, buffer, size, callback, arg) → {otc_video_frame *} |
Creates a new video frame from data in a contiguous memmory buffer. |
otc_video_frame_new_planar_memory_wrapper(format, width, height, is_shallow_copyable, callbacks) → {otc_video_frame *} |
Creates a new video frame from a planar memory wrapper. |
otc_video_frame_new_I420_wrapper(width, height, y_plane, y_stride, u_plane, u_stride, v_plane, v_stride) → {otc_video_frame *} |
Creates a new I420 format video frame from YUV data. |
otc_video_frame_new_NV21_wrapper(width, height, y_plane, y_stride, uv_plane, uv_stride) → {otc_video_frame *} |
Creates a new video frame with an NV21 wrapper. |
otc_video_frame_new_NV12_wrapper(width, height, y_plane, y_stride, uv_plane, uv_stride) → {otc_video_frame *} |
Creates a new video frame with an NV12 wrapper. |
otc_video_frame_get_buffer(frame) → {const uint8_t *} |
Gets a pointer to the buffer containing video frame data. |
otc_video_frame_get_buffer_size(frame) → {size_t} |
Gets the size of the buffer containing video frame data. |
otc_video_frame_get_timestamp(frame) → {int64_t} |
Gets a video frame timestamp in milliseconds since epoch time. |
otc_video_frame_set_timestamp(frame, timestamp) |
Sets the timestamp for a video frame in milliseconds since epoch time. |
otc_video_frame_get_width(frame) → {int} |
Gets the width of a video frame, in pixels. |
otc_video_frame_get_height(frame) → {int} |
Gets the height of a video frame, in pixels. |
otc_video_frame_get_number_of_planes(frame) → {size_t} |
Gets the number of planes of a video frame. |
otc_video_frame_get_format(frame) → {enum otc_video_frame_format} |
Gets the video format of a video frame. |
otc_video_frame_set_format(frame, format) |
Sets the video format of a video frame. |
otc_video_frame_get_plane_binary_data(frame, plane) → {const uint8_t *} |
Gets the binary data from one of the planes of a video frame. |
otc_video_frame_get_plane_size(frame, plane) → {size_t} |
Gets the size of a plane in a video frame. |
otc_video_frame_get_plane_stride(frame, plane) → {int} |
Gets plane stride from a give plane in a video frame. |
otc_video_frame_get_plane_width(frame, plane) → {int} |
Gets the width of a plane in a video frame. |
otc_video_frame_get_plane_height(frame, plane) → {int} |
Gets the height of a plane in a video frame. |
otc_video_frame_copy(frame) → {otc_video_frame *} |
Copies a given video frame. |
otc_video_frame_mutable_copy(frame) → {otc_video_frame *} |
Makes a mutable copy of a given video frame. |
otc_video_frame_convert(format, frame) → {otc_video_frame *} |
Converts a given frame. |
otc_video_frame_convert_inplace(format, planes, strides, input_frame) → {otc_status} |
Converts a given frame in place. |
otc_video_frame_is_packed(frame) → {otc_bool} |
Checks whether a video frame is packed or not. |
otc_video_frame_is_contiguous(frame) → {otc_bool} |
Checks whether a video frame is contiguous or not. |
otc_video_frame_get_native_handle(frame) → {void *}
Parameters:
| Name | Type | Description |
|---|---|---|
frame |
const otc_video_frame * |
Returns:
void *
otc_video_frame_new(format, width, height, buffer) → {otc_video_frame *}
Creates a new video frame with a given format.
Parameters:
| Name | Type | Description |
|---|---|---|
format |
enum otc_video_frame_format | The desired format. |
width |
int | The width of the video, in pixels. |
height |
int | The height of the video, in pixels. |
buffer |
const uint8_t * | A pointer to a buffer containing video frame data. |
Returns:
A pointer to a video frame instance. This can be null if there is an error.
otc_video_frame_delete(frame) → {otc_status}
Free resources associated with the frame.
Parameters:
| Name | Type | Description |
|---|---|---|
frame |
otc_video_frame * | A pointer to a video frame instance. |
See: : - otc_error_code
Returns:
Return value indicating either error or success.
otc_video_frame_new_I420(width, height, y_plane, y_stride, u_plane, u_stride, v_plane, v_stride) → {otc_video_frame *}
Creates a new video frame with I420 format.
Parameters:
| Name | Type | Description |
|---|---|---|
width |
int | The width of the video, in pixels. |
height |
int | The height of the video, in pixels. |
y_plane |
const uint8_t * | A pointer to a buffer containing Y plane data. |
y_stride |
int | Y stride. |
u_plane |
const uint8_t * | A pointer to a buffer containing U plane data. |
u_stride |
int | U stride. |
v_plane |
const uint8_t * | A pointer to a buffer containing V plane data. |
v_stride |
int | V stride. |
Returns:
A pointer to a video frame instance. This can be null if there is an error.
otc_video_frame_new_MJPEG(width, height, buffer, size) → {otc_video_frame *}
Creates a new video frame with MJPEG format.
Parameters:
| Name | Type | Description |
|---|---|---|
width |
int | The width of the video, in pixels. |
height |
int | The height of the video, in pixels. |
buffer |
const uint8_t * | A pointer to a buffer containing video frame data. |
size |
size_t | The video frame size in memory. |
Returns:
A pointer to a video frame instance. This can be null if there is an error.
otc_video_frame_new_compressed(width, height, buffer, size) → {otc_video_frame *}
Creates a new compressed video frame.
Parameters:
| Name | Type | Description |
|---|---|---|
width |
int | The width of the video, in pixels. |
height |
int | The height of the video, in pixels. |
buffer |
const uint8_t * | A pointer to a buffer containing video frame data. |
size |
size_t | The video frame size in memory. |
Returns:
A pointer to a video frame instance. This can be null if there is an error.
otc_video_frame_new_from_planes(format, width, height, planes, strides) → {otc_video_frame *}
Creates a new video frame with a given format from its planes.
Parameters:
| Name | Type | Description |
|---|---|---|
format |
enum otc_video_frame_format | The desired format. |
width |
int | The width of the video, in pixels. |
height |
int | The height of the video, in pixels. |
planes |
const uint8_t * * | A pointer to a pointer to the buffer containing the video frame planes. |
strides |
int * | Strides. |
Returns:
A pointer to a video frame instance. This can be null if there is an error.
otc_video_frame_new_I420_from_planes_with_format(input_format, width, height, planes, strides) → {otc_video_frame *}
Creates a new video frame with I420 format from a list of planes.
Parameters:
| Name | Type | Description |
|---|---|---|
input_format |
enum otc_video_frame_format | The format for the video frame passed as input. |
width |
int | The width of the video, in pixels. |
height |
int | The height of the video, in pixels. |
planes |
const uint8_t * * | A pointer to a pointer to the buffer containing the video frame planes. |
strides |
int * | Strides. |
Returns:
A pointer to a video frame instance. This can be null if there is an error.
otc_video_frame_new_contiguous_memory_wrapper(format, width, height, is_shallow_copyable, buffer, size, callback, arg) → {otc_video_frame *}
Creates a new video frame from data in a contiguous memmory buffer.
Parameters:
| Name | Type | Description |
|---|---|---|
format |
enum otc_video_frame_format | The format for the video frame passed in. |
width |
int | The width of the video, in pixels. |
height |
int | The height of the video, in pixels. |
is_shallow_copyable |
otc_bool | Whether you can make a shallow copy of the frame. |
buffer |
const uint8_t * | A pointer to the buffer containing the frame data. |
size |
size_t | The size of the frame data. |
callback |
otc_video_frame_memory_release_callback | The video frame memory release callback function. |
arg |
void * | A pointer to additional arguments. |
Returns:
A pointer to a video frame instance. This can be null if there is an error.
otc_video_frame_new_planar_memory_wrapper(format, width, height, is_shallow_copyable, callbacks) → {otc_video_frame *}
Creates a new video frame from a planar memory wrapper. The otc_video_frame_planar_memory_callbacks struct, passed in, defines callback functions that are invoked when video frame and stride data is requested.
Parameters:
| Name | Type | Description |
|---|---|---|
format |
enum otc_video_frame_format | The format for the video frame passed in. |
width |
int | The width of the video, in pixels. |
height |
int | The height of the video, in pixels. |
is_shallow_copyable |
otc_bool | Whether you can make a shallow copy of the frame. |
callbacks |
struct otc_video_frame_planar_memory_callbacks * | A pointer to the struct containing the video frame callback functions. |
Returns:
A pointer to a video frame instance. This can be null if there is an error.
otc_video_frame_new_I420_wrapper(width, height, y_plane, y_stride, u_plane, u_stride, v_plane, v_stride) → {otc_video_frame *}
Creates a new I420 format video frame from YUV data.
Parameters:
| Name | Type | Description |
|---|---|---|
width |
int | The width of the video, in pixels. |
height |
int | The height of the video, in pixels. |
y_plane |
const uint8_t * | A pointer the Y plane. |
y_stride |
int | The Y stride. |
u_plane |
const uint8_t * | A pointer the U plane. |
u_stride |
int | The U stride. |
v_plane |
const uint8_t * | A pointer the V plane. |
v_stride |
int | The V stride. |
Returns:
A pointer to a video frame instance. This can be null if there is an error.
otc_video_frame_new_NV21_wrapper(width, height, y_plane, y_stride, uv_plane, uv_stride) → {otc_video_frame *}
Creates a new video frame with an NV21 wrapper.
Parameters:
| Name | Type | Description |
|---|---|---|
width |
int | The width of the video, in pixels. |
height |
int | The height of the video, in pixels. |
y_plane |
const uint8_t * | A pointer the Y plane. |
y_stride |
int | The Y stride. |
uv_plane |
const uint8_t * | A pointer the UV plane. |
uv_stride |
int | The UV stride. |
Returns:
A pointer to a video frame instance. This can be null if there is an error.
otc_video_frame_new_NV12_wrapper(width, height, y_plane, y_stride, uv_plane, uv_stride) → {otc_video_frame *}
Creates a new video frame with an NV12 wrapper.
Parameters:
| Name | Type | Description |
|---|---|---|
width |
int | The width of the video, in pixels. |
height |
int | The height of the video, in pixels. |
y_plane |
const uint8_t * | A pointer the Y plane. |
y_stride |
int | The Y stride. |
uv_plane |
const uint8_t * | A pointer the UV plane. |
uv_stride |
int | The UV stride. |
Returns:
A pointer to a video frame instance. This can be null if there is an error.
otc_video_frame_get_buffer(frame) → {const uint8_t *}
Gets a pointer to the buffer containing video frame data.
Parameters:
| Name | Type | Description |
|---|---|---|
frame |
const otc_video_frame * | A pointer to the video frame instance to get the buffer from. |
Returns:
A pointer to the buffer containing video frame data.
otc_video_frame_get_buffer_size(frame) → {size_t}
Gets the size of the buffer containing video frame data.
Parameters:
| Name | Type | Description |
|---|---|---|
frame |
const otc_video_frame * | A pointer to the video frame instance to get the buffer size from. |
Returns:
The size of the buffer containing video frame data.
otc_video_frame_get_timestamp(frame) → {int64_t}
Gets a video frame timestamp in milliseconds since epoch time.
Parameters:
| Name | Type | Description |
|---|---|---|
frame |
const otc_video_frame * | A pointer to the video frame instance. |
Returns:
The video frame timestamp.
otc_video_frame_set_timestamp(frame, timestamp)
Sets the timestamp for a video frame in milliseconds since epoch time.
Parameters:
| Name | Type | Description |
|---|---|---|
frame |
otc_video_frame * | A pointer to the video frame instance. |
timestamp |
int64_t | The timestamp value. |
otc_video_frame_get_width(frame) → {int}
Gets the width of a video frame, in pixels.
Parameters:
| Name | Type | Description |
|---|---|---|
frame |
const otc_video_frame * | A pointer to the video frame instance. |
Returns:
The width of the given, frame in pixels.
otc_video_frame_get_height(frame) → {int}
Gets the height of a video frame, in pixels.
Parameters:
| Name | Type | Description |
|---|---|---|
frame |
const otc_video_frame * | A pointer to the video frame instance. |
Returns:
The height of the given frame, in pixels.
otc_video_frame_get_number_of_planes(frame) → {size_t}
Gets the number of planes of a video frame. Typically, this returns 3 for a YUV fame and 1 for a RGBA/BGRA fame.
Parameters:
| Name | Type | Description |
|---|---|---|
frame |
const otc_video_frame * | A pointer to the video frame instance. |
Returns:
The number of planes.
otc_video_frame_get_format(frame) → {enum otc_video_frame_format}
Gets the video format of a video frame.
Parameters:
| Name | Type | Description |
|---|---|---|
frame |
const otc_video_frame * | A pointer to the video frame instance. |
See: : - otc_video_frame_format
Returns:
The video frame format.
otc_video_frame_set_format(frame, format)
Sets the video format of a video frame.
Parameters:
| Name | Type | Description |
|---|---|---|
frame |
otc_video_frame * | A pointer to the video frame instance. |
format |
enum otc_video_frame_format | The video frame format. |
See: : - otc_video_frame_format
otc_video_frame_get_plane_binary_data(frame, plane) → {const uint8_t *}
Gets the binary data from one of the planes of a video frame.
Parameters:
| Name | Type | Description |
|---|---|---|
frame |
const otc_video_frame * | A pointer to the video frame instance. |
plane |
enum otc_video_frame_plane | The video plane to get data from. |
Returns:
A pointer to a buffer containing the plane data. This can be null if there is an error.
otc_video_frame_get_plane_size(frame, plane) → {size_t}
Gets the size of a plane in a video frame.
Parameters:
| Name | Type | Description |
|---|---|---|
frame |
const otc_video_frame * | A pointer to the video frame instance. |
plane |
enum otc_video_frame_plane | The video plane to get the size from. |
Returns:
Size of the plane.
otc_video_frame_get_plane_stride(frame, plane) → {int}
Gets plane stride from a give plane in a video frame.
Parameters:
| Name | Type | Description |
|---|---|---|
frame |
const otc_video_frame * | A pointer to the video frame instance. |
plane |
enum otc_video_frame_plane | The video plane to get the stride from. |
Returns:
Stride.
otc_video_frame_get_plane_width(frame, plane) → {int}
Gets the width of a plane in a video frame.
Parameters:
| Name | Type | Description |
|---|---|---|
frame |
const otc_video_frame * | A pointer to the video frame instance. |
plane |
enum otc_video_frame_plane | The video plane to get the width from. |
Returns:
With.
otc_video_frame_get_plane_height(frame, plane) → {int}
Gets the height of a plane in a video frame.
Parameters:
| Name | Type | Description |
|---|---|---|
frame |
const otc_video_frame * | A pointer to the video frame instance. |
plane |
enum otc_video_frame_plane | The video plane to get the height from. |
Returns:
Height.
otc_video_frame_copy(frame) → {otc_video_frame *}
Copies a given video frame.
Parameters:
| Name | Type | Description |
|---|---|---|
frame |
const otc_video_frame * | A pointer to the video frame instance. |
Returns:
A pointer to the new video frame instance.
otc_video_frame_mutable_copy(frame) → {otc_video_frame *}
Makes a mutable copy of a given video frame.
Parameters:
| Name | Type | Description |
|---|---|---|
frame |
const otc_video_frame * | A pointer to the video frame instance. |
Returns:
A pointer to the new video frame instance.
otc_video_frame_convert(format, frame) → {otc_video_frame *}
Converts a given frame. All the video frames provided by the SDK callback functions are bound to this. If you plan to save the frame so you use it later, you'll need to copy it. In addition to that, if you want to convert a video frame to a different format, you'll use this function also If the destination format is the same as the source, a shallow copy (n buffer copy) will be made if possible.
Parameters:
| Name | Type | Description |
|---|---|---|
format |
enum otc_video_frame_format | The format of the video frame which will be returned. This function can convert frames to the following formats: OTC_VIDEO_FRAME_FORMAT_ARGB32, OTC_VIDEO_FRAME_FORMAT_BGRA32, OTC_VIDEO_FRAME_FORMAT_ABGR32, OTC_VIDEO_FRAME_FORMAT_RGBA32 and OTC_VIDEO_FRAME_FORMAT_YUV420P. |
frame |
const otc_video_frame * | A pointer to the video frame instance. |
See: : - otc_video_frame_format
Returns:
A copy of the video frame in the specified format. This can be null if there is an error. Keep in mind that you will need to destroy this frame later by yourself.
otc_video_frame_convert_inplace(format, planes, strides, input_frame) → {otc_status}
Converts a given frame in place. This changes the data of the input frame.
Parameters:
| Name | Type | Description |
|---|---|---|
format |
enum otc_video_frame_format | The format of the video frame. This function can convert frames to the following formats: OTC_VIDEO_FRAME_FORMAT_ARGB32, OTC_VIDEO_FRAME_FORMAT_BGRA32, OTC_VIDEO_FRAME_FORMAT_ABGR32, and OTC_VIDEO_FRAME_FORMAT_YUV420P. |
planes |
uint8_t * * | A pointer to a pointer to the video frame planes. |
strides |
const int * | A pointer to a pointer to the video frame stride. |
input_frame |
const otc_video_frame * | A pointer to the video frame instance. |
See: : - otc_error_code - otc_video_frame_format
Returns:
A return value indicating either error or success.
otc_video_frame_is_packed(frame) → {otc_bool}
Checks whether a video frame is packed or not.
Parameters:
| Name | Type | Description |
|---|---|---|
frame |
const otc_video_frame * | A pointer to the video frame instance. |
Returns:
A Boolean value with the result.
otc_video_frame_is_contiguous(frame) → {otc_bool}
Checks whether a video frame is contiguous or not.
Parameters:
| Name | Type | Description |
|---|---|---|
frame |
const otc_video_frame * | A pointer to the video frame instance. |
Returns:
A Boolean value with the result.