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。