7.31. ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT

7.31.1. 名稱

VIDIOC_G_FMT - VIDIOC_S_FMT - VIDIOC_TRY_FMT - 獲取或設定資料格式，嘗試格式

7.31.2. 概要

VIDIOC_G_FMT

int ioctl(int fd, VIDIOC_G_FMT, struct v4l2_format *argp)

VIDIOC_S_FMT

int ioctl(int fd, VIDIOC_S_FMT, struct v4l2_format *argp)

VIDIOC_TRY_FMT

int ioctl(int fd, VIDIOC_TRY_FMT, struct v4l2_format *argp)

7.31.3. 引數

fd

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

argp

指向 struct v4l2_format 的指標。

7.31.4. 描述

這些 ioctl 用於協商驅動程式和應用程式之間交換的資料格式（通常是影像格式）。

要查詢當前引數，應用程式將 struct v4l2_format 的 type 欄位設定為相應的緩衝區（流）型別。例如，影片捕獲裝置使用 V4L2_BUF_TYPE_VIDEO_CAPTURE 或 V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE。當應用程式使用指向此結構的指標呼叫 VIDIOC_G_FMT ioctl 時，驅動程式會填充 fmt 聯合體的相應成員。如果是影片捕獲裝置，則是 struct v4l2_pix_format pix 或 struct v4l2_pix_format_mplane pix_mp 成員。如果不支援請求的緩衝區型別，驅動程式將返回 EINVAL 錯誤程式碼。

要更改當前格式引數，應用程式初始化 type 欄位和相應 fmt 聯合體成員的所有欄位。有關詳細資訊，請參見 介面 中各種裝置型別的文件。好的做法是首先查詢當前引數，然後僅修改那些不適合應用程式的引數。當應用程式使用指向 struct v4l2_format 結構的指標呼叫 VIDIOC_S_FMT ioctl 時，驅動程式會檢查引數並根據硬體能力進行調整。除非 type 欄位無效，否則驅動程式不應返回錯誤程式碼，這是一種探測裝置功能並接近應用程式和驅動程式都可接受的引數的機制。成功後，驅動程式可以對硬體進行程式設計、分配資源並通常為資料交換做準備。最後，VIDIOC_S_FMT ioctl 返回當前格式引數，就像 VIDIOC_G_FMT 一樣。非常簡單、不靈活的裝置甚至可能忽略所有輸入並始終返回預設引數。但是，所有與應用程式交換資料的 V4L2 裝置都必須實現 VIDIOC_G_FMT 和 VIDIOC_S_FMT ioctl。如果不支援請求的緩衝區型別，驅動程式會在 VIDIOC_S_FMT 嘗試時返回 EINVAL 錯誤程式碼。如果 I/O 已經在進行中或者由於其他原因資源不可用，驅動程式會返回 EBUSY 錯誤程式碼。

VIDIOC_TRY_FMT ioctl 等效於 VIDIOC_S_FMT，但有一個例外：它不會更改驅動程式狀態。它也可以隨時呼叫，永遠不會返回 EBUSY。此函式用於協商引數、瞭解硬體限制，而無需停用 I/O 或可能耗時的硬體準備。雖然強烈建議，但不需要驅動程式實現此 ioctl。

由 VIDIOC_TRY_FMT 返回的格式必須與 VIDIOC_S_FMT 為相同輸入或輸出返回的格式相同。

type v4l2_format

struct v4l2_format

__u32	type	資料流的型別，請參見 v4l2_buf_type。
union {	fmt
struct v4l2_pix_format	pix	影像格式的定義，請參見 影像格式，由影片捕獲和輸出裝置使用。
struct v4l2_pix_format_mplane	pix_mp	影像格式的定義，請參見 影像格式，由支援 API 的多平面版本 的影片捕獲和輸出裝置使用。
struct v4l2_window	win	覆蓋影像的定義，請參見 影片覆蓋介面，由影片覆蓋裝置使用。
struct v4l2_vbi_format	vbi	原始 VBI 捕獲或輸出引數。這將在 原始 VBI 資料介面 中更詳細地討論。由原始 VBI 捕獲和輸出裝置使用。
struct v4l2_sliced_vbi_format	sliced	Sliced VBI 捕獲或輸出引數。有關詳細資訊，請參見 Sliced VBI 資料介面。由 sliced VBI 捕獲和輸出裝置使用。
struct v4l2_sdr_format	sdr	資料格式的定義，請參見 影像格式，由 SDR 捕獲和輸出裝置使用。
struct v4l2_meta_format	meta	元資料格式的定義，請參見 元資料格式，由元資料捕獲裝置使用。
__u8	raw_data[200]	未來擴充套件的佔位符。
}

7.31.5. 返回值

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

EINVAL

struct v4l2_format type 欄位無效或不支援請求的緩衝區型別。

EBUSY

裝置忙，無法更改格式。這可能是因為裝置正在流式傳輸或者緩衝區已分配或排隊到驅動程式。僅與 VIDIOC_S_FMT 相關。