Views of Captured Video - VIDIOC_ENUM_VIEWMODE, VIDIOC_G_VIEWMODE, VIDIOC_S_VIEWMODE
A "view" is the presentation of a moving video image on a screen or display that the user can see. If a device supports multiple views, that means it can show multiple moving video images simultaneously on its screen(s). Generally, each view can be controlled independently.
A view is often an overlay plane that displays "on top of" or blended with the graphics frame buffer on the screen, or is a rectangular region of the graphics frame buffer itself. However, it could be other things, such as a chroma-keyed pass-through, or a supplemental/bypass video output jack.
A view may have an associated frame buffer, or set of frame buffers. The application can set the frame buffer addresses with VIDIOC_S_VIEWFBUF. The application can set the on-screen size and position of video image "window" with VIDIOC_S_VIEWWIN.
An application can enumerate the views supported by the hardware and discover
what modes and visual priorities are supported for each view using the
VIDIOC_ENUM_VIEWMODE ioctl. The application fills in the index
field of a struct v4l2_viewmodedesc, and then passes it to the
VIDIOC_ENUM_VIEWMODE ioctl, which fills in the rest
of the fields. The application should use index values from 0 on up;
the ioctl will return an error when the index goes out of range.
| int index | Which view | |
| __u32 capability | The capability flags supported by this view | |
| __u32 extendedcap | Optional driver-specific capability flags | |
| __u32 ordermask | Bitmask indicating which planeorder values are valid for this plane | |
| __u32 extendeddesc[4] | Optional driver-specific extended mode or description information | |
| __u32 reserved[4] | reserved |
Use VIDIOC_G_VIEWMODE to get the current settings for the plane
modes. Use VIDIOC_S_VIEWMODE to change the modes of a view. Both
ioctls take a struct v4l2_viewmode object.
| int index | Which view | |
| __u32 source |
Source for the video stream to be shown in this view |
|
| __u32 modeflags | Currently active mode flags | |
| __u32 extendedflags | Driver-specific mode flags | |
| __u32 planeorder | In the case of multiple overlay planes, specifies in which order the planes should be drawn, 0 for the behind-most plane, 1 in front of that, etc. | |
| __u32 keycolor | Chromakey color if chromakey is enabled | |
| __u32 constalpha | Plane-wide alpha blend value if constant alpha is enabled | |
| __u32 extended[32] | Driver-specific view control data | |
| __u32 reserved[8] | reserved |
| V4L2_PLCAP_PRIORITY | Overlay supports a settable visual priority level | |
| V4L2_PLCAP_CHROMAKEY | Can use chromakey | |
| V4L2_PLCAP_PERPIXELALPHA | Supports alpha channel from alpha pixel component of plane | |
| V4L2_PLCAP_CONSTALPHA | Supports a constant alpha value for the whole plane |
| V4L2_PLMODE_CHROMAKEY | Use chromakey | |
| V4L2_PLMODE_PERPIXELALPHA | Use alpha from alpha pixel component of plane | |
| V4L2_PLMODE_CONSTALPHA | Use a constant alpha value for the whole plane |
View Framebuffer Memory Areas - VIDIOC_S_VIEWFBUF, VIDIOC_G_VIEWFBUF
These commands are used to set and query the pixel format and base addresses
of the planes. These commands use the v4l2_viewfbuffer structure.
An overlay may have more than one memory buffer associated with it so that
updates to the image may be sync'ed to a video-out port. Up to five additional
base addresses may be given. Use the buffers field to indicate how
many actual buffers will be used.
| int view | Which view | |
| struct v4l2_pix_format fmt | Physical layout and pixel format of the framebuffer | |
| __u32 buffers | Number of base addresses in the base field | |
| __u32 base[6] | Physical base address(es) for the view and its backbuffers | |
| __u32 extended[4] | Driver-specific framebuffer format data | |
| __u32 reserved[8] | reserved |
Video Windows - VIDIOC_S_VIEWWIN, VIDIOC_G_VIEWWIN
To set the on-screen size and position of a video window use VIDIOC_S_VIEWWIN
, and to query the current position use VIDIOC_G_VIEWWIN. Pass
a struct v4l2_viewwindow object with these commands. The
show field is only used for some drivers where the overlay plane is controlled
by the V4L2 driver.
| int view | Which view | |
| int x | X coordinate of the window | |
| int y | Y coordinate of the window | |
| int width | Width of the window in pixels | |
| int height | Height of the window | |
| __u32 show | Zero to hide (disable) overlay, 1 to show the overlay | |
| __u32 reserved[6] | reserved |