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: 指向结构体 v4l2_framebuffer 的指针。

7.30.4. 描述¶

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

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

破坏性覆盖支持已被删除：对于现代 GPU 和 CPU 来说，这不再需要，而且它一直是一个非常危险的功能。

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

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

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

类型 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`	帧缓冲区的像素格式。
			对于非破坏性视频覆盖，此字段仅为结构体 `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 选择字段顺序，使用结构体 `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 或视频信号呈现某种颜色时，图像像素才会替换 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	使用色度键控。色度键颜色由结构体 `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 值由结构体 `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	使用源色度键控。源色度键颜色由结构体 `v4l2_window` 的 `chromakey` 字段确定，并通过 VIDIOC_S_FMT ioctl 进行协商，请参阅视频叠加接口和视频输出叠加接口。两种色度键控是互斥的，因此使用结构体 `v4l2_window` 的同一个 `chromakey` 字段。

7.30.5. 返回值¶

成功时返回 0，错误时返回 -1，并适当设置 errno 变量。通用错误代码在通用错误代码章节中描述。

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

Linux 内核

目录

本页