API Documentation

Video

The Video API provides an interface for image devices, encoder, decoder, and utilities. In Linux, this uses a mixture of Video4Linux2 (V4L) on the hardware/interface side and GStreamer on the image data side.

Usage #include <polysync_video.h>

Enumerations

ps_h264_encoder_profile_kind

H264 encoder profile kinds.

This standard defines a sets of capabilities, which are referred to as profiles, that target specific classes of applications. These are declared as a profile code, represented by this enumerated type, and a set of constraints applied in the encoder. This allows a decoder to recognize the requirements to decode that specific stream.

For image-devices, editing, and professional applications, the standard contains four additional intra-frame-only profiles, which are defined as simple subsets of other corresponding profiles. These are mostly for professional (e.g. camera and editing system) applications.

Name Description
H264_ENCODER_PROFILE_NOT_AVAILABLE Profile information is not available.
H264_ENCODER_PROFILE_HIGH_444 High 4:4:4 predictive profile ‘high-4:4:4’. This profile builds on top of the high 4:2:2 profile, supporting up to 4:4:4 chroma sampling, up to 14 bits per sample, and additionally supporting efficient lossless region coding and the coding of each picture as three separate color planes.
H264_ENCODER_PROFILE_HIGH_444_INTRA High 4:4:4 intra profile ‘high-4:4:4-intra’. The high 4:4:4 profile constrained to all-intra use.
H264_ENCODER_PROFILE_HIGH_422 High 4:2:2 profile ‘high-4:2:2’. Primarily targeting professional applications that use interlaced video, this profile builds on top of the high 10 profile, adding support for the 4:2:2 chroma subsampling format while using up to 10 bits per sample of decoded picture precision.
H264_ENCODER_PROFILE_HIGH_422_INTRA High 4:2:2 intra profile ‘high-4:2:2-intra’. The high 4:2:2 profile constrained to all-intra use
H264_ENCODER_PROFILE_HIGH_10 High 10 profile ‘high-10’. Going beyond typical mainstream consumer product capabilities, this profile builds on top of the high profile, adding support for up to 10 bits per sample of decoded picture precision.
H264_ENCODER_PROFILE_HIGH_10_INTRA High 10 intra profile ‘high-10-intra’. The high 10 profile constrained to all-intra use.
H264_ENCODER_PROFILE_HIGH High profile ‘high’. The primary profile for broadcast and disc storage applications, particularly for high-definition applications.
H264_ENCODER_PROFILE_MAIN Main profile ‘main’. This profile is used for standard-definition digital broadcasts that use the MPEG-4 format as defined in the DVB standard. It is not, however, used for high-definition broadcasts, as the importance of this profile faded with the use of the high profile.
H264_ENCODER_PROFILE_BASELINE Baseline profile ‘baseline’. Primarily used in applications that require additional data loss robustness, this profile is used in some videoconferencing and mobile applications. This profile includes all features that are supported in the constrained baseline profile, plus three additional features that can be used for loss robustness (or for other purposes such as low-delay video stream compositing).
H264_ENCODER_PROFILE_CONSTRAINED_BASELINE Constrained baseline profile ‘constrained-baseline’. This profile is most typically used in videoconferencing and mobile applications. It corresponds to the subset of features that are in common between the baseline, main, and high profiles.
H264_ENCODER_PROFILE_KIND_COUNT Number of ps_h264_encoder_profile_kind values.

ps_h264_encoder_preset_kind

H264 encoder speed preset kinds.

The encoder speed/quality trade-off options.

Name Description
H264_ENCODER_PRESET_NOT_AVAILABLE Preset information is not available.
H264_ENCODER_PRESET_NONE No preset used.
H264_ENCODER_PRESET_ULTRA_FAST Preset ‘ultrafast’.
H264_ENCODER_PRESET_SUPER_FAST Preset ‘superfast’.
H264_ENCODER_PRESET_VERY_FAST Preset ‘veryfast’.
H264_ENCODER_PRESET_FASTER Preset ‘faster’.
H264_ENCODER_PRESET_FAST Preset ‘fast’.
H264_ENCODER_PRESET_MEDIUM Preset ‘medium’.
H264_ENCODER_PRESET_SLOW Preset ‘slow’.
H264_ENCODER_PRESET_SLOWER Preset ‘slower’.
H264_ENCODER_PRESET_VERYSLOW Preset ‘veryslow’.
H264_ENCODER_PRESET_KIND_COUNT Number of ps_h264_encoder_preset_kind values.

Functions

psync_video_check_format ( … )

This will check if a video device format configuration is available.

psync_video_check_format checks if a device will accept the given format configuration.

Parameters
in/out type name description
in ps_video_device *const device A pointer to ps_video_device that receives the configuration test.
in const ps_pixel_format_kind pixel_format The desired pixel format.
in const unsigned long width The desired image width. [pixels]
in const unsigned long height The desired image height. [pixels]
Returns

psync_video_close ( … )

This will close a video device.

Parameters
in/out type name description
in ps_video_device *const device A pointer to ps_video_device that specifies the configuration.
Returns

psync_video_decoder_copy_bytes ( … )

This will copy the decoded buffer data if it is available.

psync_video_decoder_copy_bytes copies the decoded buffer data into a user buffer.

Parameters
in/out type name description
in ps_video_decoder *const decoder A pointer to ps_video_decoder that specifies the configuration.
out unsigned char *const buffer A pointer to an unsigned char that receives the decoded buffer data.
in const unsigned long buffer_max_len The size of the specified buffer. [bytes]
out unsigned long *const buffer_len The size of the received decoded buffer data. A value of zero means no data available. [bytes]
Returns

psync_video_decoder_decode ( … )

This will decode new data.

Parameters
in/out type name description
in ps_video_decoder *const decoder A pointer to ps_video_decoder that specifies the configuration.
in const ps_timestamp buffer_timestamp The timestamp associated with the supplied buffer. [microseconds]
in const unsigned char *const buffer A pointer to an unsigned char that specifies the buffer to decode.
in const unsigned long buffer_size The size of the specified buffer. [bytes]
Returns

psync_video_decoder_init ( … )

This will initialize a video decoder.

Supported input formats: - PIXEL_FORMAT_H264 - PIXEL_FORMAT_MJPEG

Supported output formats: - all uncompressed ps_pixel_format_kind values

Parameters
in/out type name description
in ps_video_decoder *const decoder A pointer to ps_video_decoder that receives the initialization.
in const ps_pixel_format_kind in_pixel_format The pixel format of the input encoded data to be decoded.
in const unsigned long in_width The width of the input data to be decoded. [pixels]
in const unsigned long in_height The height of the input data to be decoded. [pixels]
in const ps_pixel_format_kind out_pixel_format The pixel format of the output decoded data.
in const unsigned long out_width The width of the output decoded data. [pixels]
in const unsigned long out_height The height of the output decoded data. [pixels]
in const unsigned long out_frames_per_second The expected/desired frames per second. [N frames / 1 second]
Returns

psync_video_decoder_release ( … )

This will release a video decoder.

Parameters
in/out type name description
in ps_video_decoder *const decoder A pointer to ps_video_decoder that specifies the configuration.
Returns

psync_video_enable_streaming ( … )

This will enable video device streaming.

psync_video_enable_streaming starts data capture on a video device.

Parameters
in/out type name description
in ps_video_device *const device A pointer to ps_video_device that receives the configuration.
Returns

psync_video_encoder_copy_bytes ( … )

This will copy the encoded buffer data if it is available.

psync_video_encoder_copy_bytes copies the encoded buffer data into a user buffer.

Parameters
in/out type name description
in ps_video_encoder *const encoder A pointer to ps_video_encoder that specifies the configuration.
out unsigned char *const buffer A pointer to unsigned char that receives the encoded buffer data.
in const unsigned long buffer_max_len The size of the specified buffer. [bytes]
out unsigned long *const buffer_len The size of the received encoded buffer data. Value zero means no data available. [bytes]
Returns

psync_video_encoder_encode ( … )

This will encode new data.

Parameters
in/out type name description
in ps_video_encoder *const encoder A pointer to ps_video_encoder that specifies the configuration.
in const ps_timestamp buffer_timestamp The timestamp associated with the supplied buffer. [microseconds]
in const unsigned char *const buffer A pointer to an unsigned char that specifies the buffer to encode.
in const unsigned long buffer_size The size of the specified buffer. [bytes]
Returns

psync_video_encoder_init ( … )

This will initialize a video encoder.

Supported input formats: - all uncompressed ps_pixel_format_kind values

Supported output formats: - PIXEL_FORMAT_H264 - PIXEL_FORMAT_MJPEG

Parameters
in/out type name description
in ps_video_encoder *const encoder A pointer to ps_video_encoder that receives the initialization.
in const ps_pixel_format_kind in_pixel_format The pixel format of the input data to be encoded.
in const unsigned long in_width The width of the input data to be encoded. [pixels]
in const unsigned long in_height The height of the input data to be encoded. [pixels]
in const unsigned long in_frames_per_second The input data frames per second. [N frames / 1 second]
in const ps_pixel_format_kind out_pixel_format The pixel format of the output encoded data.
in const unsigned long out_width The width of the output encoded data. [pixels]
in const unsigned long out_height The height of the output encoded data. [pixels]
Returns

psync_video_encoder_release ( … )

This will release a video encoder.

Parameters
in/out type name description
in ps_video_encoder *const encoder A pointer to ps_video_encoder that specifies the configuration.
Returns

psync_video_enumerate_devices ( … )

This will enumerate valid video devices.

psync_video_enumerate_devices populates a list of video devices detected on the host.

Parameters
in/out type name description
in ps_video_device *const devices A pointer to ps_video_device buffer that receives the data.
in const unsigned long max_devices The maximum number of elements that can be stored in the device array.
out unsigned long *const num_devices A pointer to an unsigned long that receives the number of valid devices in the array.
Returns

psync_video_enumerate_formats ( … )

This will enumerate valid video devices.

Parameters
in/out type name description
in ps_video_device *const device A pointer to ps_video_device that specifies the configuration.
out ps_pixel_format_kind * formats A pointer to ps_pixel_format_kind that specifies the user’s array to be populated.
in const unsigned long formats_len The number of elements in the user format array.
out unsigned long *const num_formats The number of elements in the user format array populated by this routine.
Returns

psync_video_open ( … )

This will open a video device.

psync_video_open establishes a connection to a video device by name.

In Linux, the device name is the full device path, i.e. ‘/dev/video0’.

Parameters
in/out type name description
in ps_video_device *const device A pointer to ps_video_device that receives the initialization.
in const char *const name A pointer to char that specifies the device name buffer.
Returns

psync_video_poll ( … )

This will poll video device for image data.

psync_video_poll blocks until new data is received or timeout is exceeded.

Parameters
in/out type name description
in ps_video_device *const device A pointer to ps_video_device that specifies the configuration.
in const ps_timestamp timeout The amount of time to block waiting for new data. Value zero means block indefinitely. [microseconds]
out ps_timestamp *const timestamp The time at which the video device was polled.
Returns

psync_video_set_format ( … )

This will apply a video device format configuration.

Parameters
in/out type name description
in ps_video_device *const device A pointer to ps_video_device that receives the configuration.
in const ps_pixel_format_kind pixel_format The desired pixel format.
in const unsigned long width The desired image width. [pixels]
in const unsigned long height The desired image height. [pixels]
Returns

psync_video_set_frame_rate ( … )

This will apply video device frame rate settings.

Parameters
in/out type name description
in ps_video_device const* device A pointer to ps_video_device that receives the configuration.
in unsigned long frames_per_second The desired frames per second. [N frames / 1 second]
Returns

Macros

PSYNC_VIDEO_HANDLE_INVALID

Value Type Description
-1 int Invalid ps_video_device.handle value.

PSYNC_VIDEO_ENCODER_DATA_INVALID

Value Type Description
NULL int Invalid ps_video_encoder.data value.

PSYNC_VIDEO_DECODER_DATA_INVALID

Value Type Description
NULL int Invalid ps_video_decoder.data value.

PSYNC_VIDEO_DEFAULT_FRAMES_PER_SECOND

Value Type Description
30 int Default video frames-per-second value.

PSYNC_H264_ENCODER_TUNE_NONE

Value Type Description
0x00000000 int No H264 tuning options set. Used in ps_h264_configuration.tune.

PSYNC_H264_ENCODER_TUNE_STILL_IMAGE

Value Type Description
0x00000001 int Still image H264 tuning option bit. Used in ps_h264_configuration.tune.

PSYNC_H264_ENCODER_TUNE_FAST_DECODE

Value Type Description
0x00000002 int Fast decode H264 tuning option bit. Used in ps_h264_configuration.tune.

PSYNC_H264_ENCODER_TUNE_ZERO_LATENCY

Value Type Description
0x00000004 int Zero latency H264 tuning option bit. Used in ps_h264_configuration.tune.

Structures

ps_video_device

Data Type Name Description
unsigned char * buffer The pointer to a device data buffer, used to read data when available.
unsigned long buffer_len The size of the device data buffer. [bytes]
int handle The device handle. In Linux, this is the device file descriptor. Value PSYNC_VIDEO_HANDLE_INVALID means invalid device.
char name[PSYNC_DEFAULT_STRING_LEN] The device name. In Linux, this is the full device path, i.e. ‘/dev/video0’.
char type[PSYNC_DEFAULT_STRING_LEN] The device/card type. Usually, this is the device card type, i.e. ‘HD Pro Webcam C920’.

ps_video_encoder

Data Type Name Description
void * data The internal data used by the encoder back-end.

ps_video_decoder

Data Type Name Description
void* data The internal data used by the encoder back-end.

ps_video_configuration

Data Type Name Description
unsigned long width Image width. [pixels]
unsigned long height Image height. [pixels]
ps_pixel_format_kind pixel_format Pixel format.
unsigned long frames_per_second Frames per second. [N frames / 1 second]

ps_h264_configuration

Data Type Name Description
char plugin_name[1024] Encoder plugin name. If string length is less than or equal to zero, the default plugin is used.
ps_h264_encoder_profile_kind profile Encoder profile. Value H264_ENCODER_PROFILE_NOT_AVAILABLE means use the default.
ps_h264_encoder_preset_kind speed Speed preset. Value H264_ENCODER_PRESET_NOT_AVAILABLE means use the default.
unsigned long tune Tuning options bitfield. Value PSYNC_H264_ENCODER_TUNE_NONE means no options set.
unsigned long bitrate Bitrate. [kbit/second] Value zero means use the default.