Table of Contents
video_capture_open
Opens a video capture device, such as a camera, or a file or URL.
Description
The video_capture_open function opens a video capture device, such as a camera. It can also read video samples from a file, such as an MP3 file, or URL. The handle to the capture session returned by this function is used by the other functions in the Multimedia API to refer to the session. This handle must be closed using the video_capture_close function when the session is no longer in use.
Prototype
t_error video_capture_open(const char * url, t_double frame_rate, t_uint frame_width, t_uint frame_height, t_image_format format, t_image_data_type data_type, t_video_capture * capture, const t_video_capture_attribute * attributes, t_uint num_attributes);
Parameters
const char * url
A string identifying the video capture device to be opened as a URL. Various forms of the URL are shown in the table below:
Sample URL |
Description |
---|---|
"C:\Users\Me\Videos" |
Capture video from a file (path specified without "file:" scheme) |
"file://localhost/path" |
Capture video from a file. |
"http://host/path" |
Capture video from the web (only supported in Windows). The https scheme should also be supported (or other valid Internet schemes supported by Media Foundation). |
"video://localhost:id" |
Capture video from a camera or other device. If the URL followed by an "@" symbol and another URL then it will access a simulated video device or access a video device through a video proxy server, using the given communications URL. |
Note that additional options could potentially be specified as query options in the URL.
t_double frame_rate
A real number specifying the frame rate at which video input will be captured in Hertz. A value such as 30 Hz or 60 Hz is typical.
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_image_format 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 |
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 |
t_video_capture * capture
The address of a t_video_capture
variable in which the handle to the capture session
will be stored. This handle is then passed to the other video capture functions to identify the
capture session.
t_video_capture_attribute * attributes
The address of an array of t_video_capture_attribute structures. Each element in the array describes a setting for an attribute of the video capture device, such as the brightness or contrast to use. This argument may be NULL, in which case default values are used. In that case, the num_attributes argument should be zero.
Each element of the array is a structure containing four elements, as listed in the table below:
Field |
Data Type |
Description |
---|---|---|
property_code |
t_video_capture_property_code |
The property which is being set. Valid property codes are listed in below. |
value |
t_double |
The value to which to set the attribute, if the attribute is being set manually. The interpretation
of this value depends on the |
manual |
t_boolean |
Whether the value is being set manually or will be determined automatically. |
is_enumeration |
t_boolean |
Whether the value is an enumeration or fraction. See the discussion of the |
Property Code |
Description |
---|---|
VIDEO_CAPTURE_PROPERTY_BRIGHTNESS |
The brightness of the image from the device. |
VIDEO_CAPTURE_PROPERTY_CONTRAST |
The contrast of the image from the device. |
VIDEO_CAPTURE_PROPERTY_HUE |
The hue of the image from the device, which affects the colour of the image. |
VIDEO_CAPTURE_PROPERTY_SATURATION |
The saturation of the image from the device, which affects the depth of the colour of the image. If the saturation is zero then the image will be grayscale. |
VIDEO_CAPTURE_PROPERTY_SHARPNESS |
The sharpness of the image from the device, which affects the clarity of edges in the image. |
VIDEO_CAPTURE_PROPERTY_GAMMA |
The gamma factor of the image from the device, which affects the colour of the image. |
VIDEO_CAPTURE_PROPERTY_COLOREFFECT |
The colour effect to apply to the image from the device. See the
|
VIDEO_CAPTURE_PROPERTY_WHITEBALANCE |
The white balance to apply to the image from the device. |
VIDEO_CAPTURE_PROPERTY_BACKLIGHTCOMPENSATION |
The backlight compensation to use for the image from the device. |
VIDEO_CAPTURE_PROPERTY_GAIN |
The gain to apply to the image from the device. |
VIDEO_CAPTURE_PROPERTY_PAN |
How much to pan the camera view from the device. |
VIDEO_CAPTURE_PROPERTY_TILT |
How much to tilt the camera view from the device. |
VIDEO_CAPTURE_PROPERTY_ROLL |
How much to roll the camera view from the device. |
VIDEO_CAPTURE_PROPERTY_ZOOM |
How much to zoom the camera view from the device. |
VIDEO_CAPTURE_PROPERTY_EXPOSURE |
The exposure to use for the image from the device. |
VIDEO_CAPTURE_PROPERTY_IRIS |
The aperture to use for the image from the device. |
VIDEO_CAPTURE_PROPERTY_FOCUS |
The focus to use for the image from the device. |
t_uint num_attributes
The number of attributes in the attributes array.
Return value
The return value is 0 if the video capture session 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_capture capture; t_error result = video_capture_open("video://localhost:0", 30.0, 640, 480, IMAGE_FORMAT_COL_MAJOR_PLANAR_RGB, IMAGE_DATA_TYPE_UINT8, &capture, NULL, 0); if (result >= 0) { ... video_capture_close(capture); } else { TCHAR message[512]; msg_get_error_message(NULL, result, message, sizeof(message)); _tprintf(_T("Failed to open video capture session. %s (error %d)\n"), message, -result); }
See Also
Copyright ©2024 Quanser Inc. This page was generated 2024-10-17. Submit feedback to Quanser about this page.
Link to this page.