Video frame. More...

#include <unistd.h> #include "base.h" #include "config.h"
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...
Functions
void * otc_video_frame_get_native_handle (const otc_video_frame *frame)
otc_video_frame * otc_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_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)
otc_video_frame * otc_video_frame_new_MJPEG (int width, int height, const uint8_t *buffer, size_t size)
otc_video_frame * otc_video_frame_new_compressed (int width, int height, const uint8_t *buffer, size_t size)
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)
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)
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)
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)
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)
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)
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)
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_frame * otc_video_frame_copy (const otc_video_frame *frame)
otc_video_frame * otc_video_frame_mutable_copy (const otc_video_frame *frame)
otc_video_frame * otc_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 : | | | | --- | --- | | buffer | A function pointer to the buffer. | | arg | A 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 : | | | | --- | --- | | 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 | A 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 : | | | | --- | --- | | 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. | | input_frame | A pointer to the video frame instance. | | planes | A pointer to a pointer to the video frame planes. | | strides | A 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 : | | | | --- | --- | | frame | A 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 : | | | | --- | --- | | frame | A 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 : | | | | --- | --- | | 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()
size_t otc_video_frame_get_buffer_size ( const otc_video_frame * frame )

Gets the size of the buffer containing video frame data.

Parameters : | | | | --- | --- | | 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_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 : | | | | --- | --- | | frame | A 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 : | | | | --- | --- | | frame | A 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.

[Deprecated:] : This function is deprecated and will be removed in a future version of the library.

Parameters : | | | | --- | --- | | frame | A pointer to the video frame instance. | | size | The 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 : | | | | --- | --- | | frame | A 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 : | | | | --- | --- | | frame | A pointer to the video frame instance. | | 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_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 : | | | | --- | --- | | frame | A pointer to the video frame instance. | | plane | The 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 : | | | | --- | --- | | frame | A pointer to the video frame instance. | | plane | The 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 : | | | | --- | --- | | frame | A pointer to the video frame instance. | | plane | The 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 : | | | | --- | --- | | frame | A pointer to the video frame instance. | | plane | The 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 : | | | | --- | --- | | frame | A 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 : | | | | --- | --- | | frame | A 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 : | | | | --- | --- | | frame | A 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 : | | | | --- | --- | | frame | A 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 : | | | | --- | --- | | frame | A 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 : | | | | --- | --- | | format | The desired format. | | width | The width of the video, in pixels. | | height | The height of the video, in pixels. | | buffer | 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_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 : | | | | --- | --- | | width | The width of the video, in pixels. | | height | The height of the video, in pixels. | | buffer | A pointer to a buffer containing video frame data. | | size | 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_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 : | | | | --- | --- | | format | The format for the video frame passed in. | | width | The width of the video, in pixels. | | height | The height of the video, in pixels. | | is_shallow_copyable | Whether you can make a shallow copy of the frame. | | buffer | A pointer to the buffer containing the frame data. | | size | The size of the frame data. | | callback | The video frame memory release callback function. | | arg | 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_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 : | | | | --- | --- | | format | The desired format. | | width | The width of the video, in pixels. | | height | The height of the video, in pixels. | | planes | A pointer to a pointer to the buffer containing the video frame planes. | | strides | Strides. |

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 : | | | | --- | --- | | width | The width of the video, in pixels. | | height | The height of the video, in pixels. | | y_plane | A pointer to a buffer containing Y plane data. | | y_stride | Y stride. | | u_plane | A pointer to a buffer containing U plane data. | | u_stride | U stride. | | v_plane | A pointer to a buffer containing V plane data. | | v_stride | V 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_format | The format for the video frame passed as input. | | width | The width of the video, in pixels. | | height | The height of the video, in pixels. | | planes | A pointer to a pointer to the buffer containing the video frame planes. | | strides | Strides. |

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 : | | | | --- | --- | | width | The width of the video, in pixels. | | height | The height of the video, in pixels. | | y_plane | A pointer the Y plane. | | y_stride | The Y stride. | | u_plane | A pointer the U plane. | | u_stride | The U stride. | | v_plane | A pointer the V plane. | | v_stride | The 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 : | | | | --- | --- | | width | The width of the video, in pixels. | | height | The height of the video, in pixels. | | buffer | A pointer to a buffer containing video frame data. | | size | 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_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 : | | | | --- | --- | | width | The width of the video, in pixels. | | height | The height of the video, in pixels. | | y_plane | A pointer the Y plane. | | y_stride | The Y stride. | | uv_plane | A pointer the UV plane. | | uv_stride | The 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 : | | | | --- | --- | | width | The width of the video, in pixels. | | height | The height of the video, in pixels. | | y_plane | A pointer the Y plane. | | y_stride | The Y stride. | | uv_plane | A pointer the UV plane. | | uv_stride | The 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 : | | | | --- | --- | | format | The format for the video frame passed in. | | width | The width of the video, in pixels. | | height | The height of the video, in pixels. | | is_shallow_copyable | Whether you can make a shallow copy of the frame. | | 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_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 : | | | | --- | --- | | frame | A pointer to the video frame instance. | | format | The 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.

[Deprecated:] : This function is deprecated and will be removed in a future version of the library.

Parameters : | | | | --- | --- | | frame | A pointer to the video frame instance. | | data | A pointer to the metadata buffer to be copied into the frame. | | size | The 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 : | | | | --- | --- | | frame | A pointer to the video frame instance. | | timestamp | The timestamp value. |