7.30. ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF

7.30.1. 名称

VIDIOC_G_FBUF - VIDIOC_S_FBUF - 获取或设置帧缓冲区覆盖参数

7.30.2. 概要

VIDIOC_G_FBUF

int ioctl(int fd, VIDIOC_G_FBUF, struct v4l2_framebuffer *argp)

VIDIOC_S_FBUF

int ioctl(int fd, VIDIOC_S_FBUF, const struct v4l2_framebuffer *argp)

7.30.3. 参数

fd

open() 返回的文件描述符。

argp

指向 struct v4l2_framebuffer 的指针。

7.30.4. 描述

应用程序可以使用 VIDIOC_G_FBUFVIDIOC_S_FBUF ioctl 获取和设置 视频覆盖视频输出覆盖 (OSD) 的帧缓冲区参数。覆盖类型由设备类型(捕获或输出设备)隐含,可以使用 ioctl VIDIOC_QUERYCAP ioctl 确定。一个 /dev/videoN 设备不得同时支持这两种类型的覆盖。

V4L2 API 区分破坏性和非破坏性覆盖。破坏性覆盖将捕获的视频图像复制到显卡的视频存储器中。非破坏性覆盖将视频图像混合到 VGA 信号中,或将图形混合到视频信号中。视频输出覆盖 始终是非破坏性的。

破坏性覆盖支持已被删除:使用现代 GPU 和 CPU,不再需要此功能,而且它一直是一个非常危险的功能。

要获取当前参数,应用程序可以使用指向 struct v4l2_framebuffer 结构的指针调用 VIDIOC_G_FBUF ioctl。驱动程序会填充结构的全部字段,或者在不支持覆盖时返回 EINVAL 错误代码。

要设置 视频输出覆盖 的参数,应用程序必须初始化 struct v4l2_framebufferflags 字段。由于帧缓冲区是在电视卡上实现的,因此所有其他参数都由驱动程序确定。当应用程序使用指向此结构的指针调用 VIDIOC_S_FBUF 时,驱动程序会为覆盖做准备,并以 VIDIOC_G_FBUF 的方式返回帧缓冲区参数,或者返回错误代码。

要设置 视频捕获覆盖 的参数,应用程序必须初始化 flags 字段和 fmt 子结构,然后调用 VIDIOC_S_FBUF。同样,驱动程序会为覆盖做准备,并以 VIDIOC_G_FBUF 的方式返回帧缓冲区参数,或者返回错误代码。

type v4l2_framebuffer
struct v4l2_framebuffer

__u32

capability

驱动程序设置的覆盖能力标志,请参阅 帧缓冲区能力标志

__u32

flags

应用程序和驱动程序设置的覆盖控制标志,请参阅 帧缓冲区标志

void *

base

帧缓冲区的物理基地址,即帧缓冲区左上角像素的地址。对于 VIDIOC_S_FBUF,不再支持此字段,内核将始终将其设置为 NULL。对于 视频输出覆盖,驱动程序将返回有效的基地址,因此应用程序可以找到相应的 Linux 帧缓冲区设备(请参阅 视频输出覆盖接口)。对于 视频捕获覆盖,此字段将始终为 NULL。

struct

fmt

帧缓冲区的布局。

__u32

width

帧缓冲区的宽度(以像素为单位)。

__u32

height

帧缓冲区的高度(以像素为单位)。

__u32

pixelformat

帧缓冲区的像素格式。

对于 非破坏性视频覆盖,此字段仅定义 struct v4l2_window chromakey 字段的格式。

对于 视频输出覆盖,驱动程序必须返回有效的格式。

通常这是 RGB 格式(例如 V4L2_PIX_FMT_RGB565),但也允许 YUV 格式(仅当使用色度键控时才打包 YUV 格式,不包括 V4L2_PIX_FMT_YUYVV4L2_PIX_FMT_UYVY)和 V4L2_PIX_FMT_PAL8 格式。当应用程序请求压缩格式时,驱动程序的行为是未定义的。有关像素格式的信息,请参阅 图像格式

enum v4l2_field

field

驱动程序和应用程序应忽略此字段。如果适用,字段顺序使用 VIDIOC_S_FMT ioctl 选择,使用 struct v4l2_windowfield 字段。

__u32

bytesperline

两条相邻线中最左侧像素之间的距离(以字节为单位)。

此字段与 非破坏性视频覆盖 无关。

对于 视频输出覆盖,驱动程序必须返回有效值。

视频硬件可能会访问填充字节,因此它们必须位于可访问的内存中。例如,考虑图像最后一行之后的填充字节跨越系统页面边界的情况。捕获设备可能会写入填充字节,该值是未定义的。输出设备忽略填充字节的内容。

当图像格式是平面时,bytesperline 值应用于第一个平面,并除以与其他平面的 width 字段相同的比例因子。例如,YUV 4:2:0 图像的 Cb 和 Cr 平面在每行之后具有一半的填充字节,就像 Y 平面一样。为避免歧义,驱动程序必须返回一个 bytesperline 值,该值四舍五入到比例因子的倍数。

__u32

sizeimage

此字段与 非破坏性视频覆盖 无关。对于 视频输出覆盖,驱动程序必须返回有效的格式。

base 一起,它定义了驱动程序可访问的帧缓冲区内存。

enum v4l2_colorspace

colorspace

此信息补充了 pixelformat,必须由驱动程序设置,请参阅 色彩空间

__u32

priv

保留。驱动程序和应用程序必须将此字段设置为零。

帧缓冲区能力标志

V4L2_FBUF_CAP_EXTERNOVERLAY

0x0001

该设备能够进行非破坏性覆盖。当驱动程序清除此标志时,仅支持破坏性覆盖。目前还没有驱动程序同时支持破坏性和非破坏性覆盖。实际上,视频输出覆盖始终是非破坏性的。

V4L2_FBUF_CAP_CHROMAKEY

0x0002

该设备支持通过色度键控图像进行裁剪。也就是说,只有在后者呈现特定颜色时,图像像素才会替换 VGA 或视频信号中的像素。色度键控对于破坏性覆盖没有意义。

V4L2_FBUF_CAP_LIST_CLIPPING

0x0004

该设备支持使用剪辑矩形列表进行裁剪。请注意,不再支持此功能。

V4L2_FBUF_CAP_BITMAP_CLIPPING

0x0008

该设备支持使用位掩码进行裁剪。请注意,不再支持此功能。

V4L2_FBUF_CAP_LOCAL_ALPHA

0x0010

该设备支持使用帧缓冲区或 VGA 信号的 alpha 通道进行裁剪/混合。Alpha 混合对于破坏性覆盖没有意义。

V4L2_FBUF_CAP_GLOBAL_ALPHA

0x0020

该设备支持使用全局 alpha 值进行 alpha 混合。Alpha 混合对于破坏性覆盖没有意义。

V4L2_FBUF_CAP_LOCAL_INV_ALPHA

0x0040

该设备支持使用帧缓冲区或 VGA 信号的反转 alpha 通道进行裁剪/混合。Alpha 混合对于破坏性覆盖没有意义。

V4L2_FBUF_CAP_SRC_CHROMAKEY

0x0080

该设备支持源色度键控。具有色度键颜色的视频像素被帧缓冲区像素替换,这与 V4L2_FBUF_CAP_CHROMAKEY 完全相反

帧缓冲区标志

V4L2_FBUF_FLAG_PRIMARY

0x0001

帧缓冲区是主图形表面。换句话说,覆盖是破坏性的。此标志通常由任何不具有 V4L2_FBUF_CAP_EXTERNOVERLAY 能力的驱动程序设置,否则将被清除。

V4L2_FBUF_FLAG_OVERLAY

0x0002

如果为视频捕获设备设置此标志,则驱动程序会将初始覆盖大小设置为覆盖完整的帧缓冲区大小,否则将使用现有覆盖大小(由 VIDIOC_S_FMT 设置)。只有一个视频捕获驱动程序 (bttv) 支持此标志。不建议将此标志用于捕获设备。无法检测到哪些驱动程序支持此标志,因此设置覆盖大小的唯一可靠方法是通过 VIDIOC_S_FMT。如果为视频输出设备设置此标志,则视频输出覆盖窗口相对于帧缓冲区的左上角,并限制为帧缓冲区的大小。如果清除该标志,则视频输出覆盖窗口相对于视频输出显示器。

V4L2_FBUF_FLAG_CHROMAKEY

0x0004

使用色度键控。色度键颜色由 struct v4l2_windowchromakey 字段确定,并使用 VIDIOC_S_FMT ioctl 协商,请参阅 视频覆盖接口视频输出覆盖接口

没有标志可以使用剪辑矩形列表或位图启用裁剪。这些方法使用 VIDIOC_S_FMT ioctl 协商,请参阅 视频覆盖接口视频输出覆盖接口

V4L2_FBUF_FLAG_LOCAL_ALPHA

0x0008

使用帧缓冲区的 alpha 通道裁剪帧缓冲区像素或将帧缓冲区像素与视频图像混合。混合函数为:output = 帧缓冲区像素 * alpha + 视频像素 * (1 - alpha)。实际 alpha 深度取决于帧缓冲区像素格式。

V4L2_FBUF_FLAG_GLOBAL_ALPHA

0x0010

使用全局 alpha 值将帧缓冲区与视频图像混合。混合函数为:output = (帧缓冲区像素 * alpha + 视频像素 * (255 - alpha)) / 255。alpha 值由 struct v4l2_windowglobal_alpha 字段确定,并使用 VIDIOC_S_FMT ioctl 协商,请参阅 视频覆盖接口视频输出覆盖接口

V4L2_FBUF_FLAG_LOCAL_INV_ALPHA

0x0020

V4L2_FBUF_FLAG_LOCAL_ALPHA 类似,使用帧缓冲区的 alpha 通道裁剪帧缓冲区像素或将帧缓冲区像素与视频图像混合,但使用反转的 alpha 值。混合函数为:output = 帧缓冲区像素 * (1 - alpha) + 视频像素 * alpha。实际 alpha 深度取决于帧缓冲区像素格式。

V4L2_FBUF_FLAG_SRC_CHROMAKEY

0x0040

使用源色度键控。源色度键颜色由 struct v4l2_windowchromakey 字段确定,并使用 VIDIOC_S_FMT ioctl 协商,请参阅 视频覆盖接口视频输出覆盖接口。两种色度键控相互排斥,因此使用 struct v4l2_window 的同一个 chromakey 字段。

7.30.5. 返回值

成功时返回 0,出错时返回 -1,并相应地设置 errno 变量。通用错误代码在 通用错误代码 一章中进行了描述。

EPERM

只有特权用户才能调用 VIDIOC_S_FBUF 来协商破坏性覆盖的参数。

EINVAL

VIDIOC_S_FBUF 参数不合适。