OpenTok C SDK
Data Structures | Macros | Typedefs | Enumerations | Functions
video_frame.h File Reference

Video frame. More...

#include <unistd.h>
#include "base.h"
#include "config.h"

Go to the source code of this file.

Data Structures

struct  otc_video_frame_planar_memory_callbacks
 

Macros

#define OTC_VIDEO_FRAME_METADATA_MAX_SIZE   32
 

Typedefs

typedef struct otc_video_frame otc_video_frame
 
typedef void(* otc_video_frame_memory_release_callback) (const uint8_t *buffer, void *arg)
 
typedef void(* video_transform_callback) (void *user_data, struct otc_video_frame *frame)
 The callback that will perform the custom transformation. More...
 

Enumerations

enum  otc_video_frame_format {
  OTC_VIDEO_FRAME_FORMAT_UNKNOWN, OTC_VIDEO_FRAME_FORMAT_YUV420P, OTC_VIDEO_FRAME_FORMAT_NV12 = 2, OTC_VIDEO_FRAME_FORMAT_NV21 = 3,
  OTC_VIDEO_FRAME_FORMAT_YUY2 = 4, OTC_VIDEO_FRAME_FORMAT_UYVY = 5, OTC_VIDEO_FRAME_FORMAT_ARGB32, OTC_VIDEO_FRAME_FORMAT_BGRA32,
  OTC_VIDEO_FRAME_FORMAT_RGB24 = 8, OTC_VIDEO_FRAME_FORMAT_ABGR32, OTC_VIDEO_FRAME_FORMAT_MJPEG, OTC_VIDEO_FRAME_FORMAT_RGBA32,
  OTC_VIDEO_FRAME_FORMAT_MAX, OTC_VIDEO_FRAME_FORMAT_COMPRESSED
}
 
enum  otc_video_frame_plane {
  OTC_VIDEO_FRAME_PLANE_Y = 0, OTC_VIDEO_FRAME_PLANE_U = 1, OTC_VIDEO_FRAME_PLANE_V = 2, OTC_VIDEO_FRAME_PLANE_PACKED,
  OTC_VIDEO_FRAME_PLANE_UV_INTERLEAVED, OTC_VIDEO_FRAME_PLANE_VU_INTERLEAVED
}
 

Functions

void * otc_video_frame_get_native_handle (const otc_video_frame *frame)
 
otc_video_frameotc_video_frame_new (enum otc_video_frame_format format, int width, int height, const uint8_t *buffer)
 
otc_status otc_video_frame_delete (otc_video_frame *frame)
 
otc_video_frameotc_video_frame_new_I420 (int width, int height, const uint8_t *y_plane, int y_stride, const uint8_t *u_plane, int u_stride, const uint8_t *v_plane, int v_stride)
 
otc_video_frameotc_video_frame_new_MJPEG (int width, int height, const uint8_t *buffer, size_t size)
 
otc_video_frameotc_video_frame_new_compressed (int width, int height, const uint8_t *buffer, size_t size)
 
otc_video_frameotc_video_frame_new_from_planes (enum otc_video_frame_format format, int width, int height, const uint8_t **planes, int *strides)
 
otc_video_frameotc_video_frame_new_I420_from_planes_with_format (enum otc_video_frame_format input_format, int width, int height, const uint8_t **planes, int *strides)
 
otc_video_frameotc_video_frame_new_contiguous_memory_wrapper (enum otc_video_frame_format format, int width, int height, otc_bool is_shallow_copyable, const uint8_t *buffer, size_t size, otc_video_frame_memory_release_callback callback, void *arg)
 
otc_video_frameotc_video_frame_new_planar_memory_wrapper (enum otc_video_frame_format format, int width, int height, otc_bool is_shallow_copyable, struct otc_video_frame_planar_memory_callbacks *callbacks)
 
otc_video_frameotc_video_frame_new_I420_wrapper (int width, int height, const uint8_t *y_plane, int y_stride, const uint8_t *u_plane, int u_stride, const uint8_t *v_plane, int v_stride)
 
otc_video_frameotc_video_frame_new_NV21_wrapper (int width, int height, const uint8_t *y_plane, int y_stride, const uint8_t *uv_plane, int uv_stride)
 
otc_video_frameotc_video_frame_new_NV12_wrapper (int width, int height, const uint8_t *y_plane, int y_stride, const uint8_t *uv_plane, int uv_stride)
 
const uint8_t * otc_video_frame_get_buffer (const otc_video_frame *frame)
 
size_t otc_video_frame_get_buffer_size (const otc_video_frame *frame)
 
int64_t otc_video_frame_get_timestamp (const otc_video_frame *frame)
 
void otc_video_frame_set_timestamp (otc_video_frame *frame, int64_t timestamp)
 
int otc_video_frame_get_width (const otc_video_frame *frame)
 
int otc_video_frame_get_height (const otc_video_frame *frame)
 
size_t otc_video_frame_get_number_of_planes (const otc_video_frame *frame)
 
enum otc_video_frame_format otc_video_frame_get_format (const otc_video_frame *frame)
 
void otc_video_frame_set_format (otc_video_frame *frame, enum otc_video_frame_format format)
 
const uint8_t * otc_video_frame_get_plane_binary_data (const otc_video_frame *frame, enum otc_video_frame_plane plane)
 
size_t otc_video_frame_get_plane_size (const otc_video_frame *frame, enum otc_video_frame_plane plane)
 
int otc_video_frame_get_plane_stride (const otc_video_frame *frame, enum otc_video_frame_plane plane)
 
int otc_video_frame_get_plane_width (const otc_video_frame *frame, enum otc_video_frame_plane plane)
 
int otc_video_frame_get_plane_height (const otc_video_frame *frame, enum otc_video_frame_plane plane)
 
otc_video_frameotc_video_frame_copy (const otc_video_frame *frame)
 
otc_video_frameotc_video_frame_mutable_copy (const otc_video_frame *frame)
 
otc_video_frameotc_video_frame_convert (enum otc_video_frame_format format, const otc_video_frame *frame)
 
otc_status otc_video_frame_convert_inplace (enum otc_video_frame_format format, uint8_t **planes, const int *strides, const otc_video_frame *input_frame)
 
otc_bool otc_video_frame_is_packed (const otc_video_frame *frame)
 
otc_bool otc_video_frame_is_contiguous (const otc_video_frame *frame)
 
otc_status otc_video_frame_set_metadata (otc_video_frame *frame, const uint8_t *data, size_t size)
 
const uint8_t * otc_video_frame_get_metadata (const otc_video_frame *frame, size_t *size)
 

Detailed Description

Video frame.

This file includes the type definition for a video frame along with several function declarations useful when handling them.

Macro Definition Documentation

◆ OTC_VIDEO_FRAME_METADATA_MAX_SIZE

#define OTC_VIDEO_FRAME_METADATA_MAX_SIZE   32

Max size for an array containing metadata items in a video frame.

Typedef Documentation

◆ otc_video_frame

Video frame type definition.

◆ otc_video_frame_memory_release_callback

typedef void(* otc_video_frame_memory_release_callback) (const uint8_t *buffer, void *arg)

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.

Parameters
bufferA function pointer to the buffer.
argA pointer to additional arguments.

◆ video_transform_callback

typedef void(* video_transform_callback) (void *user_data, struct otc_video_frame *frame)

The callback that will perform the custom transformation.

Note: This functionality only applies to the Vonage Video API macOS SDK. It does not work in the Vonage Video API Linux SDK.

Enumeration Type Documentation

◆ otc_video_frame_format

Video frame video format enumeration.

This enumeration represents several video frame formats.

Enumerator
OTC_VIDEO_FRAME_FORMAT_UNKNOWN 

Uknown video frame format enum value.

OTC_VIDEO_FRAME_FORMAT_YUV420P 

YUV420P video frame format enum value.

OTC_VIDEO_FRAME_FORMAT_NV12 

NV12 video frame format enum value.

OTC_VIDEO_FRAME_FORMAT_NV21 

NV21 video frame format enum value.

OTC_VIDEO_FRAME_FORMAT_YUY2 

YUY2 video frame format enum value.

OTC_VIDEO_FRAME_FORMAT_UYVY 

UYVY video frame format enum value.

OTC_VIDEO_FRAME_FORMAT_ARGB32 

ARGB32 video frame format enum value.

OTC_VIDEO_FRAME_FORMAT_BGRA32 

BGRA32 video frame format enum value.

OTC_VIDEO_FRAME_FORMAT_RGB24 

RGB24 video frame format enum value.

OTC_VIDEO_FRAME_FORMAT_ABGR32 

ABGR32 video frame format enum value.

OTC_VIDEO_FRAME_FORMAT_MJPEG 

MJPEG video frame format enum value.

OTC_VIDEO_FRAME_FORMAT_RGBA32 

RGBA video frame format enum value.

OTC_VIDEO_FRAME_FORMAT_MAX 

Maxinum value.

OTC_VIDEO_FRAME_FORMAT_COMPRESSED 

Compressed video frame format enum value.

◆ otc_video_frame_plane

Video frame video plane enumeration.

Enumerator
OTC_VIDEO_FRAME_PLANE_Y 

Video frame plane Y enum value.

OTC_VIDEO_FRAME_PLANE_U 

Video frame plane U enum value.

OTC_VIDEO_FRAME_PLANE_V 

Video frame plane V enum value.

OTC_VIDEO_FRAME_PLANE_PACKED 

Video frame plane packed enum value.

OTC_VIDEO_FRAME_PLANE_UV_INTERLEAVED 

Video frame plane UV interleaved enum value.

OTC_VIDEO_FRAME_PLANE_VU_INTERLEAVED 

Video frame plane VU interleaved enum value.

Function Documentation

◆ otc_video_frame_convert()

otc_video_frame* otc_video_frame_convert ( enum otc_video_frame_format  format,
const otc_video_frame 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
formatThe 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.
frameA pointer to the video frame instance.
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.
See also
otc_video_frame_format

◆ otc_video_frame_convert_inplace()

otc_status otc_video_frame_convert_inplace ( enum otc_video_frame_format  format,
uint8_t **  planes,
const int *  strides,
const otc_video_frame input_frame 
)

Converts a given frame in place. This changes the data of the input frame.

Parameters
formatThe 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.
input_frameA pointer to the video frame instance.
planesA pointer to a pointer to the video frame planes.
stridesA pointer to a pointer to the video frame stride.
Returns
A return value indicating either error or success.
See also
otc_error_code
otc_video_frame_format

◆ otc_video_frame_copy()

otc_video_frame* otc_video_frame_copy ( const otc_video_frame frame)

Copies a given video frame.

Parameters
frameA pointer to the video frame instance.
Returns
A pointer to the new video frame instance.

◆ otc_video_frame_delete()

otc_status otc_video_frame_delete ( otc_video_frame frame)

Free resources associated with the frame.

Parameters
frameA pointer to a video frame instance.
Returns
Return value indicating either error or success.
See also
otc_error_code

◆ otc_video_frame_get_buffer()

const uint8_t* otc_video_frame_get_buffer ( const otc_video_frame frame)

Gets a pointer to the buffer containing video frame data.

Parameters
frameA 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()

size_t otc_video_frame_get_buffer_size ( const otc_video_frame frame)

Gets the size of the buffer containing video frame data.

Parameters
frameA 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_format()

enum otc_video_frame_format otc_video_frame_get_format ( const otc_video_frame frame)

Gets the video format of a video frame.

Parameters
frameA pointer to the video frame instance.
Returns
The video frame format.
See also
otc_video_frame_format

◆ otc_video_frame_get_height()

int otc_video_frame_get_height ( const otc_video_frame frame)

Gets the height of a video frame, in pixels.

Parameters
frameA pointer to the video frame instance.
Returns
The height of the given frame, in pixels.

◆ otc_video_frame_get_metadata()

const uint8_t* otc_video_frame_get_metadata ( const otc_video_frame frame,
size_t *  size 
)

Gets the metadata associated with the video frame.

Parameters
frameA pointer to the video frame instance.
sizeThe size of the metadata buffer associated with this frame.
Returns
A pointer to the internal metadata buffer in the video frame or a null pointer if there is no metadata associated with it. This pointer will get invalidated after destroying the frame.

◆ otc_video_frame_get_number_of_planes()

size_t otc_video_frame_get_number_of_planes ( const otc_video_frame frame)

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
frameA pointer to the video frame instance.
Returns
The number of planes.

◆ otc_video_frame_get_plane_binary_data()

const uint8_t* otc_video_frame_get_plane_binary_data ( const otc_video_frame frame,
enum otc_video_frame_plane  plane 
)

Gets the binary data from one of the planes of a video frame.

Parameters
frameA pointer to the video frame instance.
planeThe 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_height()

int otc_video_frame_get_plane_height ( const otc_video_frame frame,
enum otc_video_frame_plane  plane 
)

Gets the height of a plane in a video frame.

Parameters
frameA pointer to the video frame instance.
planeThe video plane to get the height from.
Returns
Height.

◆ otc_video_frame_get_plane_size()

size_t otc_video_frame_get_plane_size ( const otc_video_frame frame,
enum otc_video_frame_plane  plane 
)

Gets the size of a plane in a video frame.

Parameters
frameA pointer to the video frame instance.
planeThe video plane to get the size from.
Returns
Size of the plane.

◆ otc_video_frame_get_plane_stride()

int otc_video_frame_get_plane_stride ( const otc_video_frame frame,
enum otc_video_frame_plane  plane 
)

Gets plane stride from a give plane in a video frame.

Parameters
frameA pointer to the video frame instance.
planeThe video plane to get the stride from.
Returns
Stride.

◆ otc_video_frame_get_plane_width()

int otc_video_frame_get_plane_width ( const otc_video_frame frame,
enum otc_video_frame_plane  plane 
)

Gets the width of a plane in a video frame.

Parameters
frameA pointer to the video frame instance.
planeThe video plane to get the width from.
Returns
With.

◆ otc_video_frame_get_timestamp()

int64_t otc_video_frame_get_timestamp ( const otc_video_frame frame)

Gets a video frame timestamp in milliseconds since epoch time.

Parameters
frameA pointer to the video frame instance.
Returns
The video frame timestamp.

◆ otc_video_frame_get_width()

int otc_video_frame_get_width ( const otc_video_frame frame)

Gets the width of a video frame, in pixels.

Parameters
frameA pointer to the video frame instance.
Returns
The width of the given, frame in pixels.

◆ otc_video_frame_is_contiguous()

otc_bool otc_video_frame_is_contiguous ( const otc_video_frame frame)

Checks whether a video frame is contiguous or not.

Parameters
frameA pointer to the video frame instance.
Returns
A Boolean value with the result.

◆ otc_video_frame_is_packed()

otc_bool otc_video_frame_is_packed ( const otc_video_frame frame)

Checks whether a video frame is packed or not.

Parameters
frameA pointer to the video frame instance.
Returns
A Boolean value with the result.

◆ otc_video_frame_mutable_copy()

otc_video_frame* otc_video_frame_mutable_copy ( const otc_video_frame frame)

Makes a mutable copy of a given video frame.

Parameters
frameA pointer to the video frame instance.
Returns
A pointer to the new video frame instance.

◆ otc_video_frame_new()

otc_video_frame* otc_video_frame_new ( enum otc_video_frame_format  format,
int  width,
int  height,
const uint8_t *  buffer 
)

Creates a new video frame with a given format.

Parameters
formatThe desired format.
widthThe width of the video, in pixels.
heightThe height of the video, in pixels.
bufferA 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_new_compressed()

otc_video_frame* otc_video_frame_new_compressed ( int  width,
int  height,
const uint8_t *  buffer,
size_t  size 
)

Creates a new compressed video frame.

Parameters
widthThe width of the video, in pixels.
heightThe height of the video, in pixels.
bufferA pointer to a buffer containing video frame data.
sizeThe 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_contiguous_memory_wrapper()

otc_video_frame* otc_video_frame_new_contiguous_memory_wrapper ( enum otc_video_frame_format  format,
int  width,
int  height,
otc_bool  is_shallow_copyable,
const uint8_t *  buffer,
size_t  size,
otc_video_frame_memory_release_callback  callback,
void *  arg 
)

Creates a new video frame from data in a contiguous memmory buffer.

Parameters
formatThe format for the video frame passed in.
widthThe width of the video, in pixels.
heightThe height of the video, in pixels.
is_shallow_copyableWhether you can make a shallow copy of the frame.
bufferA pointer to the buffer containing the frame data.
sizeThe size of the frame data.
callbackThe video frame memory release callback function.
argA 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_from_planes()

otc_video_frame* otc_video_frame_new_from_planes ( enum otc_video_frame_format  format,
int  width,
int  height,
const uint8_t **  planes,
int *  strides 
)

Creates a new video frame with a given format from its planes.

Parameters
formatThe desired format.
widthThe width of the video, in pixels.
heightThe height of the video, in pixels.
planesA pointer to a pointer to the buffer containing the video frame planes.
stridesStrides.
Returns
A pointer to a video frame instance. This can be null if there is an error.

◆ otc_video_frame_new_I420()

otc_video_frame* otc_video_frame_new_I420 ( int  width,
int  height,
const uint8_t *  y_plane,
int  y_stride,
const uint8_t *  u_plane,
int  u_stride,
const uint8_t *  v_plane,
int  v_stride 
)

Creates a new video frame with I420 format.

Parameters
widthThe width of the video, in pixels.
heightThe height of the video, in pixels.
y_planeA pointer to a buffer containing Y plane data.
y_strideY stride.
u_planeA pointer to a buffer containing U plane data.
u_strideU stride.
v_planeA pointer to a buffer containing V plane data.
v_strideV stride.
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()

otc_video_frame* otc_video_frame_new_I420_from_planes_with_format ( enum otc_video_frame_format  input_format,
int  width,
int  height,
const uint8_t **  planes,
int *  strides 
)

Creates a new video frame with I420 format from a list of planes.

Parameters
input_formatThe format for the video frame passed as input.
widthThe width of the video, in pixels.
heightThe height of the video, in pixels.
planesA pointer to a pointer to the buffer containing the video frame planes.
stridesStrides.
Returns
A pointer to a video frame instance. This can be null if there is an error.

◆ otc_video_frame_new_I420_wrapper()

otc_video_frame* otc_video_frame_new_I420_wrapper ( int  width,
int  height,
const uint8_t *  y_plane,
int  y_stride,
const uint8_t *  u_plane,
int  u_stride,
const uint8_t *  v_plane,
int  v_stride 
)

Creates a new I420 format video frame from YUV data.

Parameters
widthThe width of the video, in pixels.
heightThe height of the video, in pixels.
y_planeA pointer the Y plane.
y_strideThe Y stride.
u_planeA pointer the U plane.
u_strideThe U stride.
v_planeA pointer the V plane.
v_strideThe V stride.
Returns
A pointer to a video frame instance. This can be null if there is an error.

◆ otc_video_frame_new_MJPEG()

otc_video_frame* otc_video_frame_new_MJPEG ( int  width,
int  height,
const uint8_t *  buffer,
size_t  size 
)

Creates a new video frame with MJPEG format.

Parameters
widthThe width of the video, in pixels.
heightThe height of the video, in pixels.
bufferA pointer to a buffer containing video frame data.
sizeThe 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_NV12_wrapper()

otc_video_frame* otc_video_frame_new_NV12_wrapper ( int  width,
int  height,
const uint8_t *  y_plane,
int  y_stride,
const uint8_t *  uv_plane,
int  uv_stride 
)

Creates a new video frame with an NV12 wrapper.

Parameters
widthThe width of the video, in pixels.
heightThe height of the video, in pixels.
y_planeA pointer the Y plane.
y_strideThe Y stride.
uv_planeA pointer the UV plane.
uv_strideThe UV stride.
Returns
A pointer to a video frame instance. This can be null if there is an error.

◆ otc_video_frame_new_NV21_wrapper()

otc_video_frame* otc_video_frame_new_NV21_wrapper ( int  width,
int  height,
const uint8_t *  y_plane,
int  y_stride,
const uint8_t *  uv_plane,
int  uv_stride 
)

Creates a new video frame with an NV21 wrapper.

Parameters
widthThe width of the video, in pixels.
heightThe height of the video, in pixels.
y_planeA pointer the Y plane.
y_strideThe Y stride.
uv_planeA pointer the UV plane.
uv_strideThe UV stride.
Returns
A pointer to a video frame instance. This can be null if there is an error.

◆ otc_video_frame_new_planar_memory_wrapper()

otc_video_frame* otc_video_frame_new_planar_memory_wrapper ( enum otc_video_frame_format  format,
int  width,
int  height,
otc_bool  is_shallow_copyable,
struct otc_video_frame_planar_memory_callbacks callbacks 
)

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
formatThe format for the video frame passed in.
widthThe width of the video, in pixels.
heightThe height of the video, in pixels.
is_shallow_copyableWhether you can make a shallow copy of the frame.
callbacksA 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_set_format()

void otc_video_frame_set_format ( otc_video_frame frame,
enum otc_video_frame_format  format 
)

Sets the video format of a video frame.

Parameters
frameA pointer to the video frame instance.
formatThe video frame format.
See also
otc_video_frame_format

◆ otc_video_frame_set_metadata()

otc_status otc_video_frame_set_metadata ( otc_video_frame frame,
const uint8_t *  data,
size_t  size 
)

Sets the metadata associated with a video frame.

Parameters
frameA pointer to the video frame instance.
dataA pointer to the metadata buffer to be copied into the frame.
sizeThe size of the metadata buffer to be copied.
Returns
A return value indicating either error or success.
See also
otc_error_code

◆ otc_video_frame_set_timestamp()

void otc_video_frame_set_timestamp ( otc_video_frame frame,
int64_t  timestamp 
)

Sets the timestamp for a video frame in milliseconds since epoch time.

Parameters
frameA pointer to the video frame instance.
timestampThe timestamp value.