vcap-mgr commands

Graphics and Screen4.0 (8.x)Video Capture Developer's GuideAPIProgramming

The vcap-mgr utility provides a mount point for an interface through which it accepts commands.

You can issue these commands to the Video Capture manager by means of a configuration file or via write(). Some commands may require specific permissions to be able to execute successfully. All commands follow a similar format: 

command_name [options]

where command_name is one of the following:

  • load
  • unload
  • attach
  • detach
  • enable
  • disable
  • set

and each command has their own syntax and set of options:

Note:
Although each command and its options are described below on multiple lines, note that each command and all its options must be on one single line.
load
Syntax: 
load driver= driver_name
     device= device_number
     source= source_number
     [label= label_name]
     set_block dst_format=value
     dst_height=value
     dst_width=value
     [capture_property=value...]
Options:
driver= driver_name
Specify driver_name as the driver to load (e.g., libcapture-board-imx8x-nxp.so). The driver_name, together with device_number and source_number, uniquely identifies a video input.
device= device_number
Specify device_number as the device identifier of the video input (e.g., 0). The device_number, together with driver_name and source_number, uniquely identifies a video input.
source= source_number
Specify source_number as the source index of a video input (e.g., 0). The source_number, together with device_number and driver_name, uniquely identifies a video input.
[label= label_name]
Specify label_name as an alias to identify a video input (e.g., right_front).

If not specified, vcap-mgr will assign a unique label for the video input.

set_block dst_format=value dst_height=value dst_width=value [capture_property=value...]
Specify the capture_property as the property to the capture library (e.g., capture_property_dst_width). At a minimum, you must specify the following capture properties; other capture properties are optional:
  • CAPTURE_PROPERTY_DST_WIDTH
  • CAPTURE_PROPERTY_DST_HEIGHT
  • CAPTURE_PROPERTY_DST_FORMAT

The property is case insensitive and it's acceptable to provide the property without being prefixed by CAPTURE_PROPERTY_. For example, the following ways to specify the set_block option are equivalent: 

 set-block dst_format=yuy2 dst_width=1280 dst_height=720
 set-block capture_property_dst_format=yuy2 capture_property_dst_width=1280 capture_property_dst_height=720
 set-block CAPTURE_PROPERTY_DST_FORMAT=yuy2 CAPTURE_PROPERTY_DST_WIDTH=1280 CAPTURE_PROPERTY_DST_HEIGHT=720
For more information on capture properties, see Properties.
Desription:

Use this load command to load the specified driver and initialize the corresponding capture hardware. You must be running as root, or with an effective user id of 0, to be able to successfully execute this command. If the specified combination of driver_name, device_number, and source_number, has not been already previously loaded, the load command will:

  1. load the driver
  2. create a capture context
  3. set up the hardware with the specified capture properties
  4. allocate a number of buffers for capture use
  5. enable capture if you set CAPTURE_ENABLE to 1

The Video Capture manager executes this command immediately and, if applicable, error messages are shown in both your console as well as with the slog2info utility. The following may result in an error from the load command:

  • the driver fails to load
  • a capture context already exists
  • the specified label name isn't unique
  • incorrect syntax in the command options
  • any Video Capture API calls fail

Capture properties (with the exception of CAPTURE_ENABLE) can be set only using the load command and can't be changed at any time after.

Note:
The Video Capture manager allocates the number of capture buffers based on:
  • the capture property CAPTURE_PROPERTY_FRAME_NBUFFERS that you specify in the load command
  • one more than the number of buffers returned when you call capture_get_property_i() passing in the CAPTURE_PROPERTY_MIN_BUFFERS property as the prop argument (if you haven't already specified CAPTURE_PROPERTY_FRAME_NBUFFERS in the load command)
  • the default of 12 (if you haven't already specified CAPTURE_PROPERTY_FRAME_NBUFFERS in the load command and CAPTURE_PROPERTY_MIN_BUFFRS isn't supported by the capture library
Examples:
Using a configuration file:
You can issue the load command by means of providing a valid configuration file when you start vcap-mgr with the -c option. For example, a configuration file /etc/vcap-mgr.conf: 
load driver=libcapture-board-imx8x-nxp.so device=0 source=1  label=right_camera dst_width=1280 dst_height=720 src_width=1280 src_height=720 frame_nbuffers=6 dst_format=yuy2 enable=1
load driver=libcapture-uvc.so device=0 source=2 label=rear_view_camera CAPTURE_PROPERTY_DST_WIDTH=1280 DST_HEIGHT=720 DST_FORMAT=yuy2
Using a hardware enumerator:
You can issue the load command through a hardware enumerator. For example, the usblauncher registers a driver when it discovers a new UVC camera on the bus: 
“load driver=libcapture-uvc15.so device=0 source=1 label=uvc_1 dst_format=uyvy dst_width=1280 dst_height=720 ” > /dev/vcap-mgr/command
Using write():
You can issue the load command by calling write(). For example: 
...
char str[] = { “load driver=libcapture-uvc15.so device=0 source=1 label=uvc_1 dst_format=uyvy dst_width=1280 dst_height=720” };
int rc;
int fd  = open ("/dev/vcap-mgr/command", O_WRONLY);
rc = write(fd, str , sizeof(str));
close(fd);
...
unload
Syntax: 
unload [driver= driver_name device= device_number source= source_number]
       [label= label_name]
Options:
[driver= driver_name device= device_number source= source_number]
Specify the combination of driver_name, device_number, and source_number as the driver to unload where:
  • driver_name is the driver
  • device_number is the device identifier of the video input
  • source_number is the source index of a video input
[label= label_name]
Specify the unique label_name associated with the driver to unload.
Desription:

Use this unload command to unload the specified driver. You must be running as root, or with an effective user id of 0, to be able to successfully execute this command. You can either specify a combination of driver_name, device_number, and source_number to uniquely identify the driver to unload, or use a unique label. If you specify both a label and a combination of driver_name, device_number, and source_number, then both of these options specified must resolve to the same driver. The unload command will:

  1. disable the capture context and destroy it
  2. free the resources allocated for the capture buffers
  3. unload the driver
  4. detach all windows and/or streams
  5. a SCREEN_EVENT_CLOSE event is sent to all existing consumers (with the excpetion of external streams)

The Video Capture manager executes this command immediately and, if applicable, error messages are shown in both your console as well as with the slog2info utility.

Examples:
Using a hardware enumerator:
You can issue the load command through a hardware enumerator. For example, the usblauncher registers a driver when it discovers a new UVC camera on the bus: 
“unload driver=libcapture-board-imx8x-nxp.so device=0 source=1” > /dev/vcap-mgr/command
Using write():
You can issue the unload command by calling write(). For example: 
...
char str[] = { “unload label=right_camera” };
int rc;
int fd  = open ("/dev/vcap-mgr/command", O_WRONLY);
rc = write(fd, str , sizeof(str));
close(fd);
...
attach
Syntax: 
attach action video_input
       [nbufs= num_buffers]
       SCREEN_PROPERTY_ID_STRING= id_string
       [screen_property=value...]
       [sendto= destination]
       [recvfrom= pid]
       [grpname=] group_name]
       [driver= file_name device= device_number source= source_number]
       [label= label_name]
Options:
action video_input
Specify one of the following as the action:
  • new: to create a new window or stream
  • share: to share a new window or stream
  • external: to use an exsiting window or stream that you created outside of vcap-mgr
Specify the video_input as a "window" or a "stream" that you want to attach to.
[nbufs= num_buffers]
Specify the number of buffers to be created for the specified window or stream. This nbufs option is applicable only if you've specified new for vcap-mgr to create a new window or stream.
SCREEN_PROPERTY_ID_STRING= id_string
Specify the SCREEN_PROPERTY_ID_STRING= property that's used to identify the window or stream.

The property is case insensitive and it's acceptable to provide the property without being prefixed by SCREEN_PROPERTY_. For example, the following ways to specify the SCREEN_PROPERTY_ID_STRING= option are equivalent: 

attach share window id_string=free_window label=front_camera
attach share window SCREEN_PROPERTY_ID_STRING=free_window label=front_camera
attach share window screen_property_id_string=free_window label=front_camera
For more information on Screen properties, see Screen property types.
[screen_property=value...]
Specify the screen_property and its associated value for the window or stream. The vcap-mgr supports the following Screen properties:
  • SCREEN_PROPERTY_BUFFER_SIZE
  • SCREEN_PROPERTY_FORMAT
  • SCREEN_PROPERTY_DISPLAY
These properties can be set only at the attach command and can't be changed at any time after. Other window and stream properties that are managed by its owner

The property is case insensitive and it's acceptable to provide the property without being prefixed by SCREEN_PROPERTY_. For example, the following ways to specify the screen_property option are equivalent: 

attach new window id_string=signal_right format=rgb32 buffer_size=1280x720 sendto=pid:12345 label=right_camera
attach new window screen_property_id_string=signal_right screen_property_format=rgb32 screen_property_buffer_size=1280x720 sendto=pid:12345 label=right_camera
attach new window SCREEN_PROPERTY_ID_STRING=signal_right SCREEN_PROPERTY_FORMAT=rgb32 SCREEN_PROPERTY_BUFFER_SIZE=1280x720 sendto=pid:12345 label=right_camera
For more information on Screen properties, see Screen property types.
[sendto= destination]
Specify the destination of the window or stream; the destination can be a context, a user, etc. The format of the destination is specified similar to how you would when you set SCREEN_PROPERTY_PERMISSIONS as a string. The difference is to omit the access permissions. For example: 
attach new window id_string=signal_right format=rgb32 buffer_size=1280x720 sendto=pid:12345 label=right_camera
For more information on Screen permissions, see the Setting SCREEN_PROPERTY_PERMISSIONS as a string section of Permissions and Privileges of the Screen Developer's Guide.
[recvfrom= pid]
Specify the process id from which the external window or stream that owns the buffers; this recvfrom option is applicable only if you specified external as the action. The format of the process id must be specified as you would when you set SCREEN_PROPERTY_PERMISSIONS as a string. For example: 
attach new window id_string=signal_right format=rgb32 buffer_size=1280x720 recvfrom=pid:12345 label=right_camera
For more information on Screen permissions, see the Setting SCREEN_PROPERTY_PERMISSIONS as a string section of Permissions and Privileges of the Screen Developer's Guide.
[grpname=] group_name]
Specify the name of the group that the specified window is to join. This grpname= option is applicable only for windows.
[driver= driver_name device= device_number source= source_number]
Specify the combination of driver_name, device_number, and source_number as the driver to unload where:
  • driver_name is the driver
  • device_number is the device identifier of the video input
  • source_number is the source index of a video input
[label= label_name]
Specify the unique label_name of the video input that you want to attach to.
Desription:

As the consumer, use this attach command to attach to specified stream or window. No special permissions are required to be able to successfully execute this command. You can either specify a combination of driver_name, device_number, and source_number to uniquely identify the driver to attach, or use a unique label. If you specify both a label and a combination of driver_name, device_number, and source_number, then both of these options specified must resolve to the same driver. The attach command will, depending on the action that you specify:

new
  1. create a new specified stream or window (as the consumer, you will receive a SCREEN_EVENT_CREATE event from Screen)
  2. apply any specified Screen properties to the specified stream or window
  3. create the number of buffers specified by num_buffers for the specified stream or window (if you didn't specify num_buffers, then vcap-mgrwill use the default of 2)
  4. apply the SCREEN_PROPERTY_PERMISSIONS that you specified in the sendto option
  5. when a frame is available, blit content from the capture buffer to the specified stream or window and post
share
  1. create a new specified stream or window (as the consumer, you will receive a SCREEN_EVENT_CREATE event from Screen)
  2. apply any specified Screen properties to the specified stream or window
  3. create the number of buffers specified by num_buffers for the specified stream or window (if you didn't specify num_buffers, then vcap-mgrwill use the default of 2)
  4. when a frame is available, post the specified stream or window
external
  1. validate the specified process id
  2. apply any specified Screen properties to the specified stream or window
  3. create the number of buffers specified by num_buffers for the specified stream or window (if you didn't specify num_buffers, then vcap-mgrwill use the default of 2)
  4. when a frame is available, post the specified stream or window
Note:
The Video Capture manager enables capture if this attach command is called and is successful.
Examples: 
attach new stream id_string=signal_left sendto=context:screen-ctx-3-00000000-657eb725d72a0c965a743c0672534abf  label=left_camera
attach share window id_string=free_window label=front_camera
attach new window id_string=signal_right format=rgb32 buffer_size=1280x720 sendto=pid:12345 label=right_camera
detach
Syntax: 
detach id_string= id_string
Options:
id_string= id_string
Specify the identifier, as a string, of the window or stream to detach from.
Desription:

As a consumer, use this detach command to detach from the specified window or stream. You must be running as root, or with an effective user id of 0, or with an effective user id that matches the one who specified attach to be able to successfully execute this command. The detach command will:

  1. destroy the specified window or stream
  2. a SCREEN_EVENT_CLOSE event is sent to the consumer
Note:
The Video Capture manager disables capture if this detach command is called on the last consumer that's attached to the associated video input.
Examples: 
detach id_string=free_window
enable
Syntax: 
enable [driver= driver_name device= device_number source= source_number]
       [label= label_name]
Options:
[driver= driver_name device= device_number source= source_number]
Specify the combination of driver_name, device_number, and source_number as the driver to enable a video input where:
  • driver_name is the driver
  • device_number is the device identifier of the video input
  • source_number is the source index of a video input
[label= label_name]
Specify the unique label_name associated with the video input. When you specify this label option, it's the equivalent to the command: 
set label=label_name enable=1
Desription:

Use this enable command to enable the specified video input. You must be running as root, or with an effective user id of 0, to be able to successfully execute this command. You can either specify a unique combination of driver_name, device_number, and source_number or use a unique label to identify the video input to enable. If you specify both a label and a combination of driver_name, device_number, and source_number, then both of these options specified must resolve to the same driver.

The Video Capture manager executes this command immediately and, if applicable, error messages are shown in both your console as well as with the slog2info utility.

disable
Syntax: 
disable [driver= driver_name device= device_number source= source_number]
        [label= label_name]
Options:
[driver= driver_name device= device_number source= source_number]
Specify the combination of driver_name, device_number, and source_number as the driver to disable a video input where:
  • driver_name is the driver
  • device_number is the device identifier of the video input
  • source_number is the source index of a video input
[label= label_name]
Specify the unique label_name associated with the video input. When you specify this label option, it's the equivalent to the command: 
set label=label_name enable=0
Desription:

Use this disable command to disable the specified video input. You must be running as root, or with an effective user id of 0, to be able to successfully execute this command. You can either specify a unique combination of driver_name, device_number, and source_number to or use a unique label to identify the video input to disable. If you specify both a label and a combination of driver_name, device_number, and source_number, then both of these options specified must resolve to the same driver.

The Video Capture manager executes this command immediately and, if applicable, error messages are shown in both your console as well as with the slog2info utility.

set
Syntax: 
set [driver= driver_name device= device_number source= source_number]
    [label= label_name]
    set_block [capture_property=value...]
Options:
[driver= driver_name device= device_number source= source_number]
Specify the combination of driver_name, device_number, and source_number as the driver to enable a video input where:
  • driver_name is the driver
  • device_number is the device identifier of the video input
  • source_number is the source index of a video input
[label= label_name]
Specify the unique label_name associated with the video input.
set_block [capture_property=value...]
Specify the capture_property as the property to the capture library.

The property is case insensitive and it's acceptable to provide the property without being prefixed by CAPTURE_ or CAPTURE_PROPERTY_. For example, the following ways to specify the set_block option are equivalent: 

set label=label_name enable=1
set label=label_name CAPTURE_ENABLE=1
For more information on capture properties, see Properties.
Desription:

Use this set command to set the specified capture property and apply it. You must be running as root, or with an effective user id of 0, to be able to successfully execute this command. You can either specify a unique combination of driver_name, device_number, and source_number or use a unique label to identify the video input's properties to set. If you specify both a label and a combination of driver_name, device_number, and source_number, then both of these options specified must resolve to the same driver.

Note:
At this time, the only property that's supported is CAPTURE_ENABLE.

The Video Capture manager executes this command immediately and, if applicable, error messages are shown in both your console as well as with the slog2info utility.

Page updated: