video_sink_open :: Quanser C Functions

navigation bar

video_sink_open

Open a video sink.

Description

The video_sink_open function opens a video sink, such as an MP4 or WMV file. The handle to the video sink returned by this function is used by the other functions in the Multimedia API to refer to the video sink. This handle must be closed using the video_sink_close function when the sink is no longer in use.

Prototype

t_error
video_sink_open(char * filename, t_double frame_rate, t_uint bit_rate, t_uint frame_width, t_uint frame_height, t_video_output_format video_format, t_image_format image_format, 
                t_image_data_type data_type, t_video_sink * sink);

Parameters

const char * filename

A string containing the filename to which to write the video. It may also be a URL.

t_double frame_rate

A real number specifying the frame rate in Hertz of the video being written. A value such as 30 Hz or 60 Hz is typical.

t_uint bit_rate

An integer number specifying the bit rate in Hertz for the video being written.

t_uint frame_width

The width of the image to be captured in pixels (number of columns).

t_uint frame_height

The height of the image to be captured in pixels (number of rows).

t_video_output_format video_format

The format of the file to write. Valid output formats are listed in the table below:

Video Format	Description
VIDEO_OUTPUT_FORMAT_H264	H.264 video (MP4).
VIDEO_OUTPUT_FORMAT_WMV3	Windows Media Video 9 codec (WMV).

t_image_format image_format

The format in which to provide video data. Valid video formats are listed in the table below. The format used by MATLAB for colour images is IMAGE_FORMAT_COL_MAJOR_PLANAR_RGB.

Format	Description
IMAGE_FORMAT_COL_MAJOR_PLANAR_RGB	A column major, planar, image format for colour images. The red, green and blue components of the image are stored as separate image planes rather than being interleaved. Within each image plane, each column is stored sequentially in memory.
IMAGE_FORMAT_COL_MAJOR_GRAYSCALE	A column major image format for grayscale images. Each column is stored sequentially in memory.
IMAGE_FORMAT_ROW_MAJOR_INTERLEAVED_BGR	A row major BGR image format for colour images that is suitable for OpenCV CV_8UC3 matrices (image data type must be IMAGE_DATA_TYPE_UINT8 in this case). Each row is stored sequentially in memory.
IMAGE_FORMAT_ROW_MAJOR_GRAYSCALE	A row major image format for grayscale images that is suitable for OpenCV CV_8UC1 matrices (image data type must be IMAGE_DATA_TYPE_UINT8 in this case). Each row is stored sequentially in memory.

t_image_data_type data_type

The data type to use for each pixel component in the image. This parameter is typically IMAGE_DATA_TYPE_UINT8. The full set of possible data types is enumerated in the table below:

Data type	Description
IMAGE_DATA_TYPE_UINT8	Each pixel component is an unsigned byte (8-bit) or t_uint8. Hence, pixel values range from 0 to 255. This data type is typically used. Image processing operations on this data type generally have the highest performance.
IMAGE_DATA_TYPE_UINT16	Each pixel component is an unsigned short (16-bit) or t_uint16. Hence, pixel values range from 0 to 65535.
IMAGE_DATA_TYPE_UINT32	Each pixel component is an unsigned integer (32-bit) or t_uint32. Hence, pixel values range from 0 to 4294967295. Image processing operations on this data type are often slower than the `IMAGE_DATA_TYPE_SINGLE` data type.
IMAGE_DATA_TYPE_SINGLE	Each pixel component is a single-precision (32-bit) floating-point value or t_single. Pixel values range from 0 to 1. Pixel values outside that range are not supported.
IMAGE_DATA_TYPE_DOUBLE	Each pixel component is a double-precision (64-bit) floating-point value or t_double. Pixel values range from 0 to 1. Pixel values outside that range are not supported. This data type is not recommended as operations on this data type are generally slowest. Use `IMAGE_DATA_TYPE_SINGLE` or better yet the `IMAGE_DATA_TYPE_UINT8` data type instead.

t_video_sink * sink

The address of a t_video_sink variable in which the handle to the video sink will be stored. This handle is then passed to the other video sink functions to identify the video sink.

Return value

The return value is 0 if the video sink is opened successfully. Otherwise a negative error code is returned. Error codes are defined in quanser_errors.h. A suitable error message may be retrieved using msg_get_error_message.

Error codes

QERR_INVALID_ARGUMENT

One of the arguments is invalid.

QERR_OUT_OF_MEMORY

There is not enough memory to complete the operation.

Requirements

Include Files	Libraries
quanser_video.h	quanser_media.lib;quanser_communications.lib;quanser_runtime.lib;quanser_common.lib

Examples

t_video_sink sink;
t_error result = video_sink_open("C:\my_video.mp4", 30.0, 2000000, 640, 480, VIDEO_OUTPUT_FORMAT_H264, IMAGE_FORMAT_COL_MAJOR_PLANAR_RGB, IMAGE_DATA_TYPE_UINT8, &sink);
if (result >= 0) {
    ...
    result = video_sink_write(sink, image, image_length);
    ...
    video_sink_close(sink);
} else {
    TCHAR message[512];
    msg_get_error_message(NULL, result, message, sizeof(message));
    _tprintf(_T("Failed to open video sink. %s (error %d)\n"), message, -result);
}