4.2. 视频叠加接口

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

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

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

注意

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

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

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

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

4.2.1. 查询能力

支持视频叠加接口的设备在ioctl VIDIOC_QUERYCAP ioctl 返回的 struct v4l2_capability 的 capabilities 字段中设置 V4L2_CAP_VIDEO_OVERLAY 标志。必须支持下面指定的叠加 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中给出了一个示例。

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

要对叠加窗口进行编程，应用程序将 struct 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 不同，这在启用叠加后也有效。

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

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

type v4l2_window

4.2.4.1. struct 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 协商色度键控时，应用程序将此字段设置为所需的色度键像素值。格式与帧缓冲区的像素格式（struct 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 中添加，扩展了结构。但是 VIDIOC_[G|S|TRY]_FMT ioctl 不受影响，它们接受指向 v4l2_format 父结构的指针，并在末尾添加填充字节。

type v4l2_clip

4.2.4.2. struct v4l2_clip [4]

struct v4l2_rect c

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

struct v4l2_clip * next

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

type v4l2_rect

4.2.4.3. struct v4l2_rect

__s32 left

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

__s32 top

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

__u32 width

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

__u32 height

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

4.2.5. 启用叠加

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