7.14. ioctl VIDIOC_ENUM_FMT

7.14.1. 名稱

VIDIOC_ENUM_FMT - 列舉影像格式

7.14.2. 概要

VIDIOC_ENUM_FMT

int ioctl(int fd, VIDIOC_ENUM_FMT, struct v4l2_fmtdesc *argp)

7.14.3. 引數

fd

由 open() 返回的檔案描述符。

argp

指向 struct v4l2_fmtdesc 的指標。

7.14.4. 描述

要列舉影像格式，應用程式初始化 struct v4l2_fmtdesc 的 type、mbus_code 和 index 欄位，並呼叫 ioctl VIDIOC_ENUM_FMT ioctl，並將指向此結構的指標傳遞給它。 驅動程式填充結構的其餘部分或返回 EINVAL 錯誤程式碼。 透過從索引零開始並遞增一，直到返回 EINVAL，可以列舉所有格式。 如果適用，驅動程式應按首選項順序返回格式，其中首選格式在不太首選的格式之前返回（即，具有較低的 index 值）。

根據 V4L2_CAP_IO_MC 能力，mbus_code 欄位的處理方式不同

1. 未設定 V4L2_CAP_IO_MC（也稱為“以影片節點為中心”的驅動程式）

   應用程式應將 mbus_code 欄位初始化為零，驅動程式應忽略該欄位的值。

   驅動程式應列舉所有影像格式。

   注意

   切換輸入或輸出後，列舉的影像格式列表可能會有所不同。

2. 已設定 V4L2_CAP_IO_MC（也稱為“以 MC 為中心”的驅動程式）

   如果 mbus_code 欄位為零，則應列舉所有影像格式。

   如果 mbus_code 欄位已初始化為有效的（非零）媒體匯流排格式程式碼，則驅動程式應將列舉限制為只能生成（對於影片輸出裝置）或從該媒體匯流排程式碼生成的（對於影片捕獲裝置）影像格式。 如果驅動程式不支援 mbus_code，則應返回 EINVAL。

   無論 mbus_code 欄位的值如何，列舉的影像格式都不應依賴於影片裝置或裝置管道的活動配置。

type v4l2_fmtdesc

struct v4l2_fmtdesc

__u32	index	列舉中格式的編號，由應用程式設定。這與 pixelformat 欄位無關。當索引與 V4L2_FMTDESC_FLAG_ENUM_ALL 進行 OR 運算時，驅動程式清除該標誌並列舉所有可能的格式，忽略當前配置的任何限制。不支援此標誌的驅動程式始終返回 EINVAL 錯誤程式碼，而不清除此標誌。使用 V4L2_FMTDESC_FLAG_ENUM_ALL 標誌列舉的格式不應在呼叫 VIDIOC_ENUM_FRAMESIZES() 或 VIDIOC_ENUM_FRAMEINTERVALS() 時使用。 V4L2_FMTDESC_FLAG_ENUM_ALL 僅應由可以根據此標誌返回不同格式列表的驅動程式使用。
__u32	type	資料流的型別，由應用程式設定。此處只有這些型別有效：V4L2_BUF_TYPE_VIDEO_CAPTURE、V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE、V4L2_BUF_TYPE_VIDEO_OUTPUT、V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE、V4L2_BUF_TYPE_VIDEO_OVERLAY、V4L2_BUF_TYPE_SDR_CAPTURE、V4L2_BUF_TYPE_SDR_OUTPUT、V4L2_BUF_TYPE_META_CAPTURE 和 V4L2_BUF_TYPE_META_OUTPUT。 請參閱 v4l2_buf_type。
__u32	flags	請參閱 影像格式描述標誌
__u8	description[32]	格式的描述，以 NUL 結尾的 ASCII 字串。此資訊供使用者使用，例如：“YUV 4:2:2”。
__u32	pixelformat	影像格式識別符號。這是一個四字元程式碼，由 v4l2_fourcc() 宏計算得出
#define v4l2_fourcc(a,b,c,d) (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24)) 此規範已在 影像格式 中定義了幾個影像格式。 注意 這些程式碼與 Windows 世界中使用的程式碼不同。
__u32	mbus_code	限制列舉格式的媒體匯流排程式碼，由應用程式設定。僅適用於宣告 V4L2_CAP_IO_MC 能力 的驅動程式，否則應為 0。
__u32	reserved[3]	保留供將來擴充套件使用。驅動程式必須將陣列設定為零。

影像格式描述標誌

V4L2_FMT_FLAG_COMPRESSED	0x0001	這是一個壓縮格式。
V4L2_FMT_FLAG_EMULATED	0x0002	此格式不是裝置原生的，而是透過軟體（通常是 libv4l2）模擬的，如果可能，請嘗試使用本機格式以獲得更好的效能。
V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM	0x0004	此壓縮位元組流格式（也稱為編碼格式）的硬體解碼器能夠解析連續的位元組流。 應用程式無需自己解析位元組流來查詢幀/欄位之間的邊界。 此標誌只能與 V4L2_FMT_FLAG_COMPRESSED 標誌組合使用，因為它僅適用於壓縮格式。 此標誌僅對有狀態解碼器有效。
V4L2_FMT_FLAG_DYN_RESOLUTION	0x0008	裝置支援此壓縮位元組流格式（也稱為編碼格式）的動態解析度切換。 檢測到影片引數發生更改時，它將透過事件 V4L2_EVENT_SOURCE_CHANGE 通知使用者。 此標誌只能與 V4L2_FMT_FLAG_COMPRESSED 標誌組合使用，因為它僅適用於壓縮格式。 此標誌僅對有狀態編解碼器有效。
V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL	0x0010	硬體編碼器支援將 CAPTURE 編碼幀間隔與 OUTPUT 原始幀間隔分開設定。 使用 VIDIOC_S_PARM 設定 OUTPUT 原始幀間隔也會將 CAPTURE 編碼幀間隔設定為相同的值。 如果設定了此標誌，則可以稍後將 CAPTURE 編碼幀間隔設定為不同的值。 這通常用於離線編碼，其中 OUTPUT 原始幀間隔用作保留硬體編碼器資源的提示，而 CAPTURE 編碼幀間隔是嵌入在編碼影片流中的實際幀速率。 此標誌只能與 V4L2_FMT_FLAG_COMPRESSED 標誌組合使用，因為它僅適用於壓縮格式。 此標誌僅對有狀態編碼器有效。
V4L2_FMT_FLAG_CSC_COLORSPACE	0x0020	驅動程式允許應用程式嘗試更改預設顏色空間。 此標誌僅與捕獲裝置相關。 應用程式可以在呼叫 VIDIOC_S_FMT ioctl 時請求配置捕獲裝置的顏色空間，並設定 V4L2_PIX_FMT_FLAG_SET_CSC。
V4L2_FMT_FLAG_CSC_XFER_FUNC	0x0040	驅動程式允許應用程式嘗試更改預設傳輸函式。 此標誌僅與捕獲裝置相關。 應用程式可以在呼叫 VIDIOC_S_FMT ioctl 時請求配置捕獲裝置的傳輸函式，並設定 V4L2_PIX_FMT_FLAG_SET_CSC。
V4L2_FMT_FLAG_CSC_YCBCR_ENC	0x0080	驅動程式允許應用程式嘗試更改預設 Y'CbCr 編碼。 此標誌僅與捕獲裝置相關。 應用程式可以在呼叫 VIDIOC_S_FMT ioctl 時請求配置捕獲裝置的 Y'CbCr 編碼，並設定 V4L2_PIX_FMT_FLAG_SET_CSC。
V4L2_FMT_FLAG_CSC_HSV_ENC	0x0080	驅動程式允許應用程式嘗試更改預設 HSV 編碼。 此標誌僅與捕獲裝置相關。 應用程式可以在呼叫 VIDIOC_S_FMT ioctl 時請求配置捕獲裝置的 HSV 編碼，並設定 V4L2_PIX_FMT_FLAG_SET_CSC。
V4L2_FMT_FLAG_CSC_QUANTIZATION	0x0100	驅動程式允許應用程式嘗試更改預設量化。 此標誌僅與捕獲裝置相關。 應用程式可以在呼叫 VIDIOC_S_FMT ioctl 時請求配置捕獲裝置的量化，並設定 V4L2_PIX_FMT_FLAG_SET_CSC。
V4L2_FMT_FLAG_META_LINE_BASED	0x0200	元資料格式是基於行的。 在這種情況下，v4l2_meta_format 的 width、height 和 bytesperline 欄位有效。 緩衝區由 height 行組成，每行具有 width 個數據單元的資料，並且每兩個連續行開頭之間的偏移量（以位元組為單位）為 bytesperline。
V4L2_FMTDESC_FLAG_ENUM_ALL	0x80000000	當應用程式將 index 與 V4L2_FMTDESC_FLAG_ENUM_ALL 標誌進行 OR 運算時，驅動程式會列舉所有可能的畫素格式，而不考慮任何已設定的配置。 不支援此標誌的驅動程式始終返回 EINVAL，而不清除此標誌。

7.14.5. 返回值

成功時返回 0，出錯時返回 -1，並適當設定 errno 變數。 泛型錯誤程式碼在 泛型錯誤程式碼 章節中描述。

EINVAL

不支援 struct v4l2_fmtdesc type 或 index 超出範圍。

如果設定了 V4L2_CAP_IO_MC 並且不支援指定的 mbus_code，則也返回此錯誤程式碼。