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 引數不合適。