Video for Linux Two API Specification: Revision 0.24
PrevNext

ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF

Name

VIDIOC_G_FBUF, VIDIOC_S_FBUF -- Get or set frame buffer overlay parameters

Synopsis

int ioctl(int fd, int request, struct v4l2_framebuffer *argp);

int ioctl(int fd, int request, const struct v4l2_framebuffer *argp);

Arguments

fd

File descriptor returned by open().

request

VIDIOC_G_FBUF, VIDIOC_S_FBUF

argp

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 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 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 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.

Table 1. struct v4l2_framebuffer

__u32capability Overlay capability flags set by the driver, see Table 2.
__u32flags Overlay control flags set by application and driver, see Table 3
void *base 

Physical base address of the framebuffer, that is the address of the pixel in the top left corner of the framebuffer.a

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 Section 4.4).

struct v4l2_pix_formatfmt Layout of the frame buffer. The v4l2_pix_format structure is defined in Chapter 2, for clarification the fields and acceptable values are listed below:
 __u32widthWidth of the frame buffer in pixels.
 __u32heightHeight of the frame buffer in pixels.
 __u32pixelformat

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 Chapter 2 for information on pixel formats.

 enum v4l2_fieldfieldDrivers 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.
 __u32bytesperlineDistance 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 width times bytes-per-pixel or a larger value required by the hardware. That implies applications can just set this field to zero to get a reasonable default.

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 bytesperline value applies to the largest plane and is divided by the same factor as the width field for any smaller planes. For example the Cb and Cr planes of a YUV 4:2:0 image have half as many padding bytes following each line as the Y plane. To avoid ambiguities drivers must return a bytesperline value rounded up to a multiple of the scale factor.

 __u32sizeimage

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 base it defines the framebuffer memory accessible by the driver.

 enum v4l2_colorspacecolorspaceThis information supplements the pixelformat and must be set by the driver, see Section 2.2.
 __u32privReserved for additional information about custom (driver defined) formats. When not used drivers and applications must set this field to zero.
Notes:
a. 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 Video4Linux mailing list: https://listman.redhat.com/mailman/listinfo/video4linux-list.

Table 2. Frame Buffer Capability Flags

V4L2_FBUF_CAP_EXTERNOVERLAY0x0001The 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.
V4L2_FBUF_CAP_CHROMAKEY0x0002The 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_CLIPPING0x0004The device supports clipping using a list of clip rectangles.
V4L2_FBUF_CAP_BITMAP_CLIPPING0x0008The device supports clipping using a bit mask.
V4L2_FBUF_CAP_LOCAL_ALPHA0x0010The 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_ALPHA0x0020The device supports alpha blending using a global alpha value. Alpha blending makes no sense for destructive overlays.
V4L2_FBUF_CAP_LOCAL_INV_ALPHA0x0040The device supports clipping/blending using the inverted alpha channel of the framebuffer or VGA signal. Alpha blending makes no sense for destructive overlays.

Table 3. Frame Buffer Flags

V4L2_FBUF_FLAG_PRIMARY0x0001The framebuffer is the primary graphics surface. In other words, the overlay is destructive. [?]
V4L2_FBUF_FLAG_OVERLAY0x0002The frame buffer is an overlay surface the same size as the capture. [?]
The purpose of V4L2_FBUF_FLAG_PRIMARY and V4L2_FBUF_FLAG_OVERLAY was never quite clear. Most drivers seem to ignore these flags. For compatibility with the bttv driver applications should set the V4L2_FBUF_FLAG_OVERLAY flag.
V4L2_FBUF_FLAG_CHROMAKEY0x0004Use 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 Section 4.2 and Section 4.4.
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 Section 4.2 and Section 4.4.
V4L2_FBUF_FLAG_LOCAL_ALPHA0x0008Use 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_ALPHA0x0010Use 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 Section 4.2 and Section 4.4.
V4L2_FBUF_FLAG_LOCAL_INV_ALPHA0x0020Like 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.

Return Value

On success 0 is returned, on error -1 and the errno variable is set appropriately:

EPERM

VIDIOC_S_FBUF can only be called by a privileged user to negotiate the parameters for a destructive overlay.

EBUSY

The framebuffer parameters cannot be changed at this time because overlay is already enabled, or capturing is enabled and the hardware cannot capture and overlay simultaneously.

EINVAL

The ioctl is not supported or the VIDIOC_S_FBUF parameters are unsuitable.

PrevHomeNext
ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, VIDIOC_TRY_EXT_CTRLSUpioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT