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_FBUF 和 VIDIOC_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_framebuffer 的 flags 字段。由于帧缓冲区是在电视卡上实现的，因此所有其他参数都由驱动程序确定。当应用程序使用指向此结构的指针调用 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_YUYV` 和 `V4L2_PIX_FMT_UYVY`）和 `V4L2_PIX_FMT_PAL8` 格式。当应用程序请求压缩格式时，驱动程序的行为是未定义的。有关像素格式的信息，请参阅图像格式。
	enum `v4l2_field`	`field`	驱动程序和应用程序应忽略此字段。如果适用，字段顺序使用 VIDIOC_S_FMT ioctl 选择，使用 struct `v4l2_window` 的 `field` 字段。
	__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_window` 的 `chromakey` 字段确定，并使用 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_window` 的 `global_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_window` 的 `chromakey` 字段确定，并使用 VIDIOC_S_FMT ioctl 协商，请参阅视频覆盖接口和视频输出覆盖接口。两种色度键控相互排斥，因此使用 struct `v4l2_window` 的同一个 `chromakey` 字段。

7.30.5. 返回值¶

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

EPERM: 只有特权用户才能调用 VIDIOC_S_FBUF 来协商破坏性覆盖的参数。
EINVAL: VIDIOC_S_FBUF 参数不合适。

Linux内核

目录

本页