4.2. 视频叠加接口

也称为帧缓冲区叠加或预览。

视频叠加设备能够将（电视）视频锁定到显卡的（VGA）视频信号中，或者将捕获的图像直接存储在显卡的视频存储器中，通常带有剪切。这比捕获图像并通过其他方式显示它们要高效得多。在过去只有核电站需要冷却塔的时候，这曾经是将实时视频放入窗口的唯一方法。

视频叠加设备通过与视频捕获设备相同的字符特殊文件进行访问。

注意

/dev/video设备的默认功能是视频捕获。只有在调用VIDIOC_S_FMT ioctl之后，叠加功能才可用。

驱动程序可以使用读/写和流式I/O方法支持同时叠加和捕获。如果是这样，则不能保证以视频标准的标称帧率进行操作。帧可能会从叠加重定向到捕获，或者如果捕获参数允许，一个字段可能用于叠加，另一个字段用于捕获。

应用程序应使用不同的文件描述符进行捕获和叠加。所有能够同时捕获和叠加的驱动程序都必须支持这一点。可选地，这些驱动程序还可以允许使用单个文件描述符进行捕获和叠加，以便与V4L和早期版本的V4L2兼容。[1]

两个文件描述符的常见应用是X11 Xv/V4L接口驱动程序和V4L2应用程序。当X服务器控制视频叠加时，应用程序可以利用内存映射和DMA。

4.2.1. 查询功能

支持视频叠加接口的设备在v4l2_capability结构体的capabilities字段中设置V4L2_CAP_VIDEO_OVERLAY标志，该结构体由ioctl VIDIOC_QUERYCAP ioctl返回。必须支持下面指定的叠加I/O方法。调谐器和音频输入是可选的。

4.2.2. 补充功能

视频叠加设备应根据需要支持音频输入、调谐器和调制器、控制、裁剪和缩放以及流式参数ioctl。所有视频叠加设备都必须支持视频输入和视频标准 ioctl。

4.2.3. 设置

注意：对此的支持已被删除。 在开始叠加之前，应用程序必须使用帧缓冲参数对驱动程序进行编程，即帧缓冲区的地址和大小以及图像格式，例如RGB 5:6:5。VIDIOC_G_FBUF和VIDIOC_S_FBUF ioctl分别用于获取和设置这些参数。VIDIOC_S_FBUF ioctl是特权的，因为它允许设置到物理内存的DMA，绕过内核的内存保护机制。只有超级用户才能更改帧缓冲区的地址和大小。用户不应以root身份或设置SUID位运行电视应用程序。具有适当权限的小助手应用程序应查询图形系统，并在适当的时候对V4L2驱动程序进行编程。

某些设备将视频叠加添加到显卡的输出信号中。在这种情况下，帧缓冲区不会被视频设备修改，驱动程序不需要帧缓冲区的地址和像素格式。VIDIOC_S_FBUF ioctl不是特权的。应用程序可以通过调用VIDIOC_G_FBUF ioctl来检查此类型的设备。

驱动程序可以支持五种剪切/混合方法中的任何一种（或不提供任何一种）

  1. 色度键控仅在主图形表面中的像素呈现某种颜色时显示叠加的图像。

  2. 注意：对此的支持已被删除。 可以指定一个位图，其中每个位对应于叠加图像中的一个像素。当设置该位时，将显示相应的视频像素，否则显示图形表面的像素。

  3. 注意：对此的支持已被删除。 可以指定一个剪切矩形列表。在这些区域中，不显示视频，因此可以在此处看到图形表面。

  4. 帧缓冲区具有一个alpha通道，该通道可用于剪切或混合帧缓冲区和视频。

  5. 可以指定全局alpha值来混合帧缓冲区内容和视频图像。

当支持同时捕获和叠加，并且硬件禁止不同的图像和帧缓冲区格式时，首先请求的格式优先。尝试捕获（VIDIOC_S_FMT）或叠加（VIDIOC_S_FBUF）可能会失败，并出现EBUSY错误代码，或者返回相应修改的参数。

4.2.4. 叠加窗口

叠加的图像由裁剪和叠加窗口参数确定。前者选择要捕获的视频图片区域，后者选择如何叠加和剪切图像。裁剪初始化至少需要将参数重置为默认值。在图像裁剪、插入和缩放 - CROP API中给出了一个示例。

叠加窗口由v4l2_window结构体描述。它定义了图像的大小、在图形表面上的位置以及要应用的剪切。要获取当前参数，应用程序将v4l2_format结构体的type字段设置为V4L2_BUF_TYPE_VIDEO_OVERLAY，并调用VIDIOC_G_FMT ioctl。驱动程序填充名为win的v4l2_window子结构体。无法检索先前编程的剪切列表或位图。

要对叠加窗口进行编程，应用程序将v4l2_format结构体的type字段设置为V4L2_BUF_TYPE_VIDEO_OVERLAY，初始化win子结构体，并调用VIDIOC_S_FMT ioctl。驱动程序会根据硬件限制调整参数，并像VIDIOC_G_FMT一样返回实际参数。与VIDIOC_S_FMT类似，VIDIOC_TRY_FMT ioctl可用于了解驱动程序的功能，而无需实际更改驱动程序状态。与VIDIOC_S_FMT不同，这在启用叠加后也有效。

叠加图像的缩放因子由v4l2_window结构体中给出的宽度和高度以及裁剪矩形的大小暗示。有关更多信息，请参见图像裁剪、插入和缩放 - CROP API。

当支持同时捕获和叠加，并且硬件禁止不同的图像和窗口大小时，首先请求的大小优先。尝试捕获或叠加（VIDIOC_S_FMT）可能会失败，并出现EBUSY错误代码，或者返回相应修改的参数。

type v4l2_window

4.2.4.1. 结构体 v4l2_window

struct v4l2_rect w

窗口相对于使用VIDIOC_S_FBUF定义的帧缓冲区的左上角的大小和位置。窗口可以超出帧缓冲区的宽度和高度，x和y坐标可以为负数，并且可以完全位于帧缓冲区之外。驱动程序会相应地剪切窗口，如果不可能，则修改其大小和/或位置。

enum v4l2_field field

应用程序设置此字段以确定应叠加哪个视频字段，通常为V4L2_FIELD_ANY（0）、V4L2_FIELD_TOP、V4L2_FIELD_BOTTOM或V4L2_FIELD_INTERLACED之一。驱动程序可能必须选择不同的字段顺序并在此处返回实际设置。

__u32 chromakey

当与 VIDIOC_S_FBUF 协商好色度键控后，应用程序应将此字段设置为色度键所需的像素值。格式与帧缓冲区的像素格式相同（结构体 v4l2_framebuffer 的 fmt.pixelformat 字段），字节顺序为主机字节顺序。例如，对于 V4L2_PIX_FMT_BGR24，在小端主机上该值应为 0xRRGGBB，在大端主机上应为 0xBBGGRR。

struct v4l2_clip * clips

注意：对此的支持已移除。 当色度键控未协商，且 VIDIOC_G_FBUF 指示此功能时，应用程序可以将此字段设置为指向裁剪矩形数组。

与窗口坐标 w 一样，裁剪矩形是相对于帧缓冲区左上角定义的。但是，裁剪矩形不得超出帧缓冲区的宽度和高度，并且它们不得重叠。如果可能，应用程序应合并相邻的矩形。这必须创建 x-y 或 y-x 带，还是矩形的顺序，都未定义。当不支持裁剪列表时，驱动程序将忽略此字段。在调用 VIDIOC_S_FMT 之后，其内容是未定义的。

__u32 clipcount

注意：对此的支持已移除。 当应用程序设置 clips 字段时，此字段必须包含列表中裁剪矩形的数量。当不支持裁剪列表时，驱动程序将忽略此字段，在调用 VIDIOC_S_FMT 之后，其内容是未定义的。当支持裁剪列表但不需要裁剪时，此字段必须设置为零。

void * bitmap

注意：对此的支持已移除。 当色度键控未协商，且 VIDIOC_G_FBUF 指示此功能时，应用程序可以将此字段设置为指向裁剪位掩码。

它的大小必须与窗口大小相同，即 w.width 和 w.height。每个位对应于叠加图像中的一个像素，仅当该位为设置时才会显示该像素。像素坐标转换为位的规则如下：

((__u8 *) bitmap)[w.width * y + x / 8] & (1 << (x & 7))

其中 0 ≤ x < w.width 且 0 ≤ y <w.height。 [2]

当不支持裁剪位掩码时，驱动程序将忽略此字段，在调用 VIDIOC_S_FMT 之后，其内容是未定义的。当支持位掩码但不需要裁剪时，此字段必须设置为 NULL。

应用程序不需要创建裁剪列表或位掩码。当它们同时传递两者时，或者尽管协商了色度键控，结果也是未定义的。无论选择哪种方法，硬件的裁剪能力都可能在数量或质量上受到限制。超出这些限制时的结果是未定义的。 [3]

__u8 global_alpha

全局 alpha 值，用于将帧缓冲区与视频图像混合，如果已协商全局 alpha 混合（V4L2_FBUF_FLAG_GLOBAL_ALPHA，请参阅 VIDIOC_S_FBUF, 帧缓冲区标志）。

注意

此字段在 Linux 2.6.23 中添加，扩展了结构体。但是，采用指向具有末尾填充字节的 v4l2_format 父结构体的指针的 VIDIOC_[G|S|TRY]_FMT ioctl 不受影响。

类型 v4l2_clip

4.2.4.2. 结构体 v4l2_clip [4]

struct v4l2_rect c

裁剪矩形的坐标，相对于帧缓冲区的左上角。仅显示所有裁剪矩形之外的窗口像素。

struct v4l2_clip * next

指向下一个裁剪矩形的指针，当这是最后一个矩形时为 NULL。驱动程序会忽略此字段，它不能用于传递裁剪矩形的链表。

类型 v4l2_rect

4.2.4.3. 结构体 v4l2_rect

__s32 left

矩形左上角的水平偏移量，以像素为单位。

__s32 top

矩形左上角的垂直偏移量，以像素为单位。偏移量向右和向下增加。

__u32 width

矩形的宽度，以像素为单位。

__u32 height

矩形的高度，以像素为单位。

4.2.5. 启用叠加

要启动或停止帧缓冲区叠加，应用程序应调用 ioctl VIDIOC_OVERLAY ioctl。