8.30. ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF¶
8.30.1. Name¶
VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set frame buffer overlay parameters
8.30.2. Synopsis¶
-
int
ioctl
(int fd, int request, struct v4l2_framebuffer *argp)¶
-
int
ioctl
(int fd, int request, const struct v4l2_framebuffer *argp)¶
8.30.4. Description¶
Applications can use the VIDIOC_G_FBUF and VIDIOC_S_FBUF ioctl
to get and set the framebuffer parameters for a
Video Overlay or Video Output Overlay
(OSD). The type of overlay is implied by the device type (capture or
output device) and can be determined with the
ioctl VIDIOC_QUERYCAP ioctl. One /dev/videoN
device must not support both kinds of overlay.
The V4L2 API distinguishes destructive and non-destructive overlays. A destructive overlay copies captured video images into the video memory of a graphics card. A non-destructive overlay blends video images into a VGA signal or graphics into a video signal. Video Output Overlays are always non-destructive.
To get the current parameters applications call the VIDIOC_G_FBUF ioctl with a pointer to a struct v4l2_framebuffer structure. The driver fills all fields of the structure or returns an EINVAL error code when overlays are not supported.
To set the parameters for a Video Output Overlay, applications must
initialize the flags
field of a struct
struct v4l2_framebuffer. Since the framebuffer is
implemented on the TV card all other parameters are determined by the
driver. When an application calls VIDIOC_S_FBUF with a pointer to
this structure, the driver prepares for the overlay and returns the
framebuffer parameters as VIDIOC_G_FBUF does, or it returns an error
code.
To set the parameters for a non-destructive Video Overlay,
applications must initialize the flags
field, the fmt
substructure, and call VIDIOC_S_FBUF. Again the driver prepares for
the overlay and returns the framebuffer parameters as VIDIOC_G_FBUF
does, or it returns an error code.
For a destructive Video Overlay applications must additionally provide
a base
address. Setting up a DMA to a random memory location can
jeopardize the system security, its stability or even damage the
hardware, therefore only the superuser can set the parameters for a
destructive video overlay.
__u32 | capability |
Overlay capability flags set by the driver, see Frame Buffer Capability Flags. | |
__u32 | flags |
Overlay control flags set by application and driver, see Frame Buffer Flags | |
void * | base |
Physical base address of the framebuffer, that is the address of the pixel in the top left corner of the framebuffer. [1] | |
This field is irrelevant to non-destructive Video Overlays. For destructive Video Overlays applications must provide a base address. The driver may accept only base addresses which are a multiple of two, four or eight bytes. For Video Output Overlays the driver must return a valid base address, so applications can find the corresponding Linux framebuffer device (see Video Output Overlay Interface). | |||
struct | fmt |
Layout of the frame buffer. | |
__u32 | width |
Width of the frame buffer in pixels. | |
__u32 | height |
Height of the frame buffer in pixels. | |
__u32 | pixelformat |
The pixel format of the framebuffer. | |
For non-destructive Video Overlays this field only defines a
format for the struct v4l2_window
chromakey field. |
|||
For destructive Video Overlays applications must initialize this field. For Video Output Overlays the driver must return a valid format. | |||
Usually this is an RGB format (for example
V4L2_PIX_FMT_RGB565) but YUV
formats (only packed YUV formats when chroma keying is used, not
including V4L2_PIX_FMT_YUYV and V4L2_PIX_FMT_UYVY ) and the
V4L2_PIX_FMT_PAL8 format are also permitted. The behavior of
the driver when an application requests a compressed format is
undefined. See Image Formats for information on pixel formats. |
|||
enum v4l2_field | field |
Drivers and applications shall ignore this field. If applicable,
the field order is selected with the
VIDIOC_S_FMT ioctl, using the field
field of struct v4l2_window. |
|
__u32 | bytesperline |
Distance in bytes between the leftmost pixels in two adjacent lines. | |
This field is irrelevant to non-destructive Video Overlays. For destructive Video Overlays both applications and drivers can
set this field to request padding bytes at the end of each line.
Drivers however may ignore the requested value, returning
For Video Output Overlays the driver must return a valid value. Video hardware may access padding bytes, therefore they must reside in accessible memory. Consider for example the case where padding bytes after the last line of an image cross a system page boundary. Capture devices may write padding bytes, the value is undefined. Output devices ignore the contents of padding bytes. When the image format is planar the |
|||
__u32 | sizeimage |
This field is irrelevant to non-destructive Video Overlays. For destructive Video Overlays applications must initialize this field. For Video Output Overlays the driver must return a valid format. Together with |
|
enum v4l2_colorspace | colorspace |
This information supplements the pixelformat and must be set
by the driver, see Colorspaces. |
|
__u32 | priv |
Reserved. Drivers and applications must set this field to zero. |
V4L2_FBUF_CAP_EXTERNOVERLAY |
0x0001 | The device is capable of non-destructive overlays. When the driver clears this flag, only destructive overlays are supported. There are no drivers yet which support both destructive and non-destructive overlays. Video Output Overlays are in practice always non-destructive. |
V4L2_FBUF_CAP_CHROMAKEY |
0x0002 | The device supports clipping by chroma-keying the images. That is, image pixels replace pixels in the VGA or video signal only where the latter assume a certain color. Chroma-keying makes no sense for destructive overlays. |
V4L2_FBUF_CAP_LIST_CLIPPING |
0x0004 | The device supports clipping using a list of clip rectangles. |
V4L2_FBUF_CAP_BITMAP_CLIPPING |
0x0008 | The device supports clipping using a bit mask. |
V4L2_FBUF_CAP_LOCAL_ALPHA |
0x0010 | The device supports clipping/blending using the alpha channel of the framebuffer or VGA signal. Alpha blending makes no sense for destructive overlays. |
V4L2_FBUF_CAP_GLOBAL_ALPHA |
0x0020 | The device supports alpha blending using a global alpha value. Alpha blending makes no sense for destructive overlays. |
V4L2_FBUF_CAP_LOCAL_INV_ALPHA |
0x0040 | The device supports clipping/blending using the inverted alpha channel of the framebuffer or VGA signal. Alpha blending makes no sense for destructive overlays. |
V4L2_FBUF_CAP_SRC_CHROMAKEY |
0x0080 | The device supports Source Chroma-keying. Video pixels with the
chroma-key colors are replaced by framebuffer pixels, which is
exactly opposite of V4L2_FBUF_CAP_CHROMAKEY |
V4L2_FBUF_FLAG_PRIMARY |
0x0001 | The framebuffer is the primary graphics surface. In other words,
the overlay is destructive. This flag is typically set by any
driver that doesn’t have the V4L2_FBUF_CAP_EXTERNOVERLAY
capability and it is cleared otherwise. |
V4L2_FBUF_FLAG_OVERLAY |
0x0002 | If this flag is set for a video capture device, then the driver will set the initial overlay size to cover the full framebuffer size, otherwise the existing overlay size (as set by VIDIOC_S_FMT) will be used. Only one video capture driver (bttv) supports this flag. The use of this flag for capture devices is deprecated. There is no way to detect which drivers support this flag, so the only reliable method of setting the overlay size is through VIDIOC_S_FMT. If this flag is set for a video output device, then the video output overlay window is relative to the top-left corner of the framebuffer and restricted to the size of the framebuffer. If it is cleared, then the video output overlay window is relative to the video output display. |
V4L2_FBUF_FLAG_CHROMAKEY |
0x0004 | Use chroma-keying. The chroma-key color is determined by the
chromakey field of struct v4l2_window
and negotiated with the VIDIOC_S_FMT
ioctl, see Video Overlay Interface and Video Output Overlay Interface. |
There are no flags to enable clipping using a list of clip rectangles or a bitmap. These methods are negotiated with the VIDIOC_S_FMT ioctl, see Video Overlay Interface and Video Output Overlay Interface. | ||
V4L2_FBUF_FLAG_LOCAL_ALPHA |
0x0008 | Use the alpha channel of the framebuffer to clip or blend framebuffer pixels with video images. The blend function is: output = framebuffer pixel * alpha + video pixel * (1 - alpha). The actual alpha depth depends on the framebuffer pixel format. |
V4L2_FBUF_FLAG_GLOBAL_ALPHA |
0x0010 | Use a global alpha value to blend the framebuffer with video
images. The blend function is: output = (framebuffer pixel * alpha
+ video pixel * (255 - alpha)) / 255. The alpha value is
determined by the global_alpha field of struct
v4l2_window and negotiated with the
VIDIOC_S_FMT ioctl, see Video Overlay Interface
and Video Output Overlay Interface. |
V4L2_FBUF_FLAG_LOCAL_INV_ALPHA |
0x0020 | Like V4L2_FBUF_FLAG_LOCAL_ALPHA , use the alpha channel of the
framebuffer to clip or blend framebuffer pixels with video images,
but with an inverted alpha value. The blend function is: output =
framebuffer pixel * (1 - alpha) + video pixel * alpha. The actual
alpha depth depends on the framebuffer pixel format. |
V4L2_FBUF_FLAG_SRC_CHROMAKEY |
0x0040 | Use source chroma-keying. The source chroma-key color is
determined by the chromakey field of struct
v4l2_window and negotiated with the
VIDIOC_S_FMT ioctl, see Video Overlay Interface
and Video Output Overlay Interface. Both chroma-keying are mutual exclusive to each
other, so same chromakey field of struct
v4l2_window is being used. |
8.30.5. Return Value¶
On success 0 is returned, on error -1 and the errno
variable is set
appropriately. The generic error codes are described at the
Generic Error Codes chapter.
- EPERM
- VIDIOC_S_FBUF can only be called by a privileged user to negotiate the parameters for a destructive overlay.
- EINVAL
- The VIDIOC_S_FBUF parameters are unsuitable.
[1] | A physical base address may not suit all platforms. GK notes in theory we should pass something like PCI device + memory region + offset instead. If you encounter problems please discuss on the linux-media mailing list: https://linuxtv.org/lists.php. |