7.49. ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL 和 VIDIOC_QUERYMENU

7.49.1. 名稱

VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - 列舉控制元件和選單控制元件項

7.49.2. 概要

int ioctl(int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp)

VIDIOC_QUERY_EXT_CTRL

int ioctl(int fd, VIDIOC_QUERY_EXT_CTRL, struct v4l2_query_ext_ctrl *argp)

VIDIOC_QUERYMENU

int ioctl(int fd, VIDIOC_QUERYMENU, struct v4l2_querymenu *argp)

7.49.3. 引數

fd

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

argp

指向 struct v4l2_queryctrl、v4l2_query_ext_ctrl 或 v4l2_querymenu 的指標（取決於 ioctl）。

7.49.4. 描述

要查詢控制元件的屬性，應用程式需要設定 struct v4l2_queryctrl 的 id 欄位，並使用指向此結構的指標呼叫 VIDIOC_QUERYCTRL ioctl。驅動程式會填充結構的其餘部分，或者當 id 無效時返回 EINVAL 錯誤程式碼。

可以透過從 V4L2_CID_BASE 開始，直到但不包括 V4L2_CID_LASTP1，連續呼叫 VIDIOC_QUERYCTRL 並使用遞增的 id 值來列舉控制元件。如果不支援此範圍內的控制元件，驅動程式可能會返回 EINVAL。此外，應用程式可以透過從 V4L2_CID_PRIVATE_BASE 開始並遞增 id，直到驅動程式返回 EINVAL，來列舉此規範中未定義的私有控制元件。

在這兩種情況下，當驅動程式在 flags 欄位中設定 V4L2_CTRL_FLAG_DISABLED 標誌時，此控制元件將被永久停用，應用程式應忽略它。[1]

當應用程式將 id 與 V4L2_CTRL_FLAG_NEXT_CTRL 進行 OR 運算時，驅動程式將返回下一個支援的非複合控制元件，如果沒有，則返回 EINVAL。此外，可以指定 V4L2_CTRL_FLAG_NEXT_COMPOUND 標誌來列舉所有複合控制元件（即型別 ≥ V4L2_CTRL_COMPOUND_TYPES 和/或陣列控制元件的控制元件，換句話說，包含多個值的控制元件）。同時指定 V4L2_CTRL_FLAG_NEXT_CTRL 和 V4L2_CTRL_FLAG_NEXT_COMPOUND 以列舉所有控制元件，無論是否為複合控制元件。尚不支援這些標誌的驅動程式始終返回 EINVAL。

引入 VIDIOC_QUERY_EXT_CTRL ioctl 是為了更好地支援可以使用複合型別的控制元件，並公開無法在 struct v4l2_queryctrl 中返回的其他控制元件資訊，因為該結構已滿。

VIDIOC_QUERY_EXT_CTRL 的使用方式與 VIDIOC_QUERYCTRL 相同，只是 reserved 陣列也必須清零。

選單控制元件需要額外的資訊：選單項的名稱。要查詢它們，應用程式需要設定 struct v4l2_querymenu 的 id 和 index 欄位，並使用指向此結構的指標呼叫 VIDIOC_QUERYMENU ioctl。驅動程式會填充結構的其餘部分，或者當 id 或 index 無效時返回 EINVAL 錯誤程式碼。透過呼叫 VIDIOC_QUERYMENU 並使用從 struct v4l2_queryctrl 的 minimum 到 maximum（包括兩者）的遞增的 index 值來列舉選單項。

注意

VIDIOC_QUERYMENU 可能會為 minimum 和 maximum 之間的一些索引返回 EINVAL 錯誤程式碼。在這種情況下，該特定選單項不受此驅動程式的支援。另請注意，minimum 值不一定為 0。

另請參閱 使用者控制元件 中的示例。

struct v4l2_queryctrl

__u32	id	標識控制元件，由應用程式設定。有關預定義的 ID，請參閱 控制元件 ID。當 ID 與 V4L2_CTRL_FLAG_NEXT_CTRL 進行 OR 運算時，驅動程式會清除該標誌並返回第一個 ID 較高的控制元件。尚不支援此標誌的驅動程式始終返回 EINVAL 錯誤程式碼。
__u32	type	控制元件型別，請參閱 v4l2_ctrl_type。
__u8	name[32]	控制元件的名稱，以 NUL 結尾的 ASCII 字串。此資訊供使用者使用。
__s32	minimum	最小值，包括。此欄位給出了控制元件的下限。有關最小值如何用於每種可能的控制元件型別，請參閱 enum v4l2_ctrl_type。請注意，這是一個有符號的 32 位值。
__s32	maximum	最大值，包括。此欄位給出了控制元件的上限。有關最大值如何用於每種可能的控制元件型別，請參閱 enum v4l2_ctrl_type。請注意，這是一個有符號的 32 位值。
__s32	step	此欄位給出了控制元件的步長。有關步長值如何用於每種可能的控制元件型別，請參閱 enum v4l2_ctrl_type。請注意，這是一個無符號的 32 位值。 通常，驅動程式不應縮放硬體控制元件值。例如，當 name 或 id 暗示特定單位，而硬體實際上只接受該單位的倍數時，這可能是必要的。如果是這樣，驅動程式必須注意在縮放時正確舍入值，這樣錯誤才不會在重複的讀寫週期中累積。 此欄位給出了整數控制元件的最小更改，該更改實際影響硬體。通常，當用戶可以透過鍵盤或 GUI 按鈕而不是滑塊來更改控制元件時，需要此資訊。例如，當硬體暫存器接受 0-511 的值，而驅動程式報告 0-65535 時，步長應為 128。 請注意，儘管已簽名，但步長值應始終為正值。
__s32	default_value	V4L2_CTRL_TYPE_INTEGER、_BOOLEAN、_BITMASK、_MENU 或 _INTEGER_MENU 控制元件的預設值。對其他型別的控制元件無效。 注意 驅動程式僅在首次載入驅動程式時將控制元件重置為其預設值，之後不再重置。
__u32	flags	控制元件標誌，請參閱 控制元件標誌。
__u32	reserved[2]	為將來的擴充套件保留。驅動程式必須將陣列設定為零。

struct v4l2_query_ext_ctrl

__u32	id	標識控制元件，由應用程式設定。有關預定義的 ID，請參閱 控制元件 ID。當 ID 與 V4L2_CTRL_FLAG_NEXT_CTRL 進行 OR 運算時，驅動程式會清除該標誌並返回第一個 ID 較高的非複合控制元件。當 ID 與 V4L2_CTRL_FLAG_NEXT_COMPOUND 進行 OR 運算時，驅動程式會清除該標誌並返回第一個 ID 較高的複合控制元件。同時設定兩者以獲取第一個 ID 較高的控制元件（無論是否為複合控制元件）。
__u32	type	控制元件型別，請參閱 v4l2_ctrl_type。
char	name[32]	控制元件的名稱，以 NUL 結尾的 ASCII 字串。此資訊供使用者使用。
__s64	minimum	最小值，包括。此欄位給出了控制元件的下限。有關最小值如何用於每種可能的控制元件型別，請參閱 enum v4l2_ctrl_type。請注意，這是一個有符號的 64 位值。
__s64	maximum	最大值，包括。此欄位給出了控制元件的上限。有關最大值如何用於每種可能的控制元件型別，請參閱 enum v4l2_ctrl_type。請注意，這是一個有符號的 64 位值。
__u64	step	此欄位給出了控制元件的步長。有關步長值如何用於每種可能的控制元件型別，請參閱 enum v4l2_ctrl_type。請注意，這是一個無符號的 64 位值。 通常，驅動程式不應縮放硬體控制元件值。例如，當 name 或 id 暗示特定單位，而硬體實際上只接受該單位的倍數時，這可能是必要的。如果是這樣，驅動程式必須注意在縮放時正確舍入值，這樣錯誤才不會在重複的讀寫週期中累積。 此欄位給出了整數控制元件的最小更改，該更改實際影響硬體。通常，當用戶可以透過鍵盤或 GUI 按鈕而不是滑塊來更改控制元件時，需要此資訊。例如，當硬體暫存器接受 0-511 的值，而驅動程式報告 0-65535 時，步長應為 128。
__s64	default_value	V4L2_CTRL_TYPE_INTEGER、_INTEGER64、_BOOLEAN、_BITMASK、_MENU、_INTEGER_MENU、_U8 或 _U16 控制元件的預設值。對其他型別的控制元件無效。 注意 驅動程式僅在首次載入驅動程式時將控制元件重置為其預設值，之後不再重置。
__u32	flags	控制元件標誌，請參閱 控制元件標誌。
__u32	elem_size	陣列單個元素的大小（以位元組為單位）。給定一個指向 3 維陣列的 char 指標 p，您可以找到單元格 (z, y, x) 的位置，如下所示：p + ((z * dims[1] + y) * dims[0] + x) * elem_size。elem_size 始終有效，即使控制元件不是陣列也是如此。對於字串控制元件，elem_size 等於 maximum + 1。
__u32	elems	N 維陣列中的元素數。如果此控制元件不是陣列，則 elems 為 1。elems 欄位永遠不能為 0。
__u32	nr_of_dims	N 維陣列中的維數。如果此控制元件不是陣列，則此欄位為 0。
__u32	dims[V4L2_CTRL_MAX_DIMS]	每個維度的大小。此陣列的前 nr_of_dims 個元素必須為非零，所有剩餘元素必須為零。
__u32	reserved[32]	為將來的擴充套件保留。應用程式和驅動程式必須將陣列設定為零。

struct v4l2_querymenu

__u32	id	標識控制元件，由應用程式從相應的 struct v4l2_queryctrl id 設定。
__u32	index	選單項的索引，從零開始，由應用程式設定。
union {	(anonymous)
__u8	name[32]	選單項的名稱，以 NUL 結尾的 ASCII 字串。此資訊供使用者使用。此欄位對 V4L2_CTRL_TYPE_MENU 型別的控制元件有效。
__s64	value	整數選單項的值。此欄位對 V4L2_CTRL_TYPE_INTEGER_MENU 型別的控制元件有效。
}
__u32	reserved	為將來的擴充套件保留。驅動程式必須將陣列設定為零。

type v4l2_ctrl_type

enum v4l2_ctrl_type

型別	minimum	step	maximum	描述
V4L2_CTRL_TYPE_INTEGER	任意	任意	任意	一個整數值控制元件，範圍從最小值到最大值（包括）。步長值表示值之間的增量。
V4L2_CTRL_TYPE_BOOLEAN	0	1	1	一個布林值控制元件。零對應於“已停用”，一表示“已啟用”。
V4L2_CTRL_TYPE_MENU	≥ 0	1	N-1	控制元件具有 N 個選項的選單。可以使用 VIDIOC_QUERYMENU ioctl 列舉選單項的名稱。
V4L2_CTRL_TYPE_INTEGER_MENU	≥ 0	1	N-1	控制元件具有 N 個選項的選單。可以使用 VIDIOC_QUERYMENU ioctl 列舉選單項的值。這與 V4L2_CTRL_TYPE_MENU 類似，只是選單項是有符號的 64 位整數而不是字串。
V4L2_CTRL_TYPE_BITMASK	0	n/a	任意	一個位掩碼欄位。最大值是可以使用的位集，所有其他位都應為 0。最大值被解釋為 __u32，允許在位掩碼中使用位 31。
V4L2_CTRL_TYPE_BUTTON	0	0	0	一個在設定時執行操作的控制元件。驅動程式必須忽略使用 VIDIOC_S_CTRL 傳遞的值，並在 VIDIOC_G_CTRL 嘗試時返回 EACCES 錯誤程式碼。
V4L2_CTRL_TYPE_INTEGER64	任意	任意	任意	一個 64 位整數值控制元件。無法使用 VIDIOC_QUERYCTRL 查詢最小值、最大值和步長。只有 VIDIOC_QUERY_EXT_CTRL 可以檢索 64 位 min/max/step 值，在使用 VIDIOC_QUERYCTRL 時應將其解釋為 n/a。
V4L2_CTRL_TYPE_STRING	≥ 0	≥ 1	≥ 0	最小和最大字串長度。步長表示字串的長度必須為（最小值 + N * 步長），其中 N ≥ 0。這些長度不包括終止零，因此為了將長度為 8 的字串傳遞給 VIDIOC_S_EXT_CTRLS，需要將 struct v4l2_ext_control 的 size 欄位設定為 9。對於 VIDIOC_G_EXT_CTRLS，可以將 size 欄位設定為 maximum + 1。使用的字元編碼將取決於字串控制元件本身，並且應該是控制元件文件的一部分。
V4L2_CTRL_TYPE_CTRL_CLASS	n/a	n/a	n/a	這不是控制元件。當使用等於控制元件類程式碼（請參閱 控制元件類）+ 1 的控制元件 ID 呼叫 VIDIOC_QUERYCTRL 時，ioctl 返回控制元件類的名稱和此控制元件型別。不支援此功能的舊驅動程式返回 EINVAL 錯誤程式碼。
V4L2_CTRL_TYPE_U8	任意	任意	任意	一個無符號的 8 位值控制元件，範圍從最小值到最大值（包括）。步長值表示值之間的增量。
V4L2_CTRL_TYPE_U16	任意	任意	任意	一個無符號的 16 位值控制元件，範圍從最小值到最大值（包括）。步長值表示值之間的增量。
V4L2_CTRL_TYPE_U32	任意	任意	任意	一個無符號的 32 位值控制元件，範圍從最小值到最大值（包括）。步長值表示值之間的增量。
V4L2_CTRL_TYPE_MPEG2_QUANTISATION	n/a	n/a	n/a	一個 struct v4l2_ctrl_mpeg2_quantisation，包含用於無狀態影片解碼器的 MPEG-2 量化矩陣。
V4L2_CTRL_TYPE_MPEG2_SEQUENCE	n/a	n/a	n/a	一個 struct v4l2_ctrl_mpeg2_sequence，包含用於無狀態影片解碼器的 MPEG-2 序列引數。
V4L2_CTRL_TYPE_MPEG2_PICTURE	n/a	n/a	n/a	一個 struct v4l2_ctrl_mpeg2_picture，包含用於無狀態影片解碼器的 MPEG-2 圖片引數。
V4L2_CTRL_TYPE_AREA	n/a	n/a	n/a	一個 struct v4l2_area，包含矩形區域的寬度和高度。單位取決於用例。
V4L2_CTRL_TYPE_RECT	n/a	n/a	n/a	一個 struct v4l2_rect，包含由其左上角的位置、寬度和高度描述的矩形。單位取決於用例。對 V4L2_CTRL_WHICH_MIN_VAL 和 V4L2_CTRL_WHICH_MAX_VAL 的支援是可選的，並且取決於 V4L2_CTRL_FLAG_HAS_WHICH_MIN_MAX 標誌。有關如何解釋最小值和最大值的文件，請參閱特定控制元件的文件。
V4L2_CTRL_TYPE_H264_SPS	n/a	n/a	n/a	一個 struct v4l2_ctrl_h264_sps，包含用於無狀態影片解碼器的 H264 序列引數。
V4L2_CTRL_TYPE_H264_PPS	n/a	n/a	n/a	一個 struct v4l2_ctrl_h264_pps，包含用於無狀態影片解碼器的 H264 圖片引數。
V4L2_CTRL_TYPE_H264_SCALING_MATRIX	n/a	n/a	n/a	一個 struct v4l2_ctrl_h264_scaling_matrix，包含用於無狀態影片解碼器的 H264 縮放矩陣。
V4L2_CTRL_TYPE_H264_SLICE_PARAMS	n/a	n/a	n/a	一個 struct v4l2_ctrl_h264_slice_params，包含用於無狀態影片解碼器的 H264 片段引數。
V4L2_CTRL_TYPE_H264_DECODE_PARAMS	n/a	n/a	n/a	一個 struct v4l2_ctrl_h264_decode_params，包含用於無狀態影片解碼器的 H264 解碼引數。
V4L2_CTRL_TYPE_FWHT_PARAMS	n/a	n/a	n/a	一個 struct v4l2_ctrl_fwht_params，包含用於無狀態影片解碼器的 FWHT 引數。
V4L2_CTRL_TYPE_HEVC_SPS	n/a	n/a	n/a	一個 struct v4l2_ctrl_hevc_sps，包含用於無狀態影片解碼器的 HEVC 序列引數集。
V4L2_CTRL_TYPE_HEVC_PPS	n/a	n/a	n/a	一個 struct v4l2_ctrl_hevc_pps，包含用於無狀態影片解碼器的 HEVC 圖片引數集。
V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS	n/a	n/a	n/a	一個 struct v4l2_ctrl_hevc_slice_params，包含用於無狀態影片解碼器的 HEVC 片段引數。
V4L2_CTRL_TYPE_HEVC_SCALING_MATRIX	n/a	n/a	n/a	一個 struct v4l2_ctrl_hevc_scaling_matrix，包含用於無狀態影片解碼器的 HEVC 縮放矩陣。
V4L2_CTRL_TYPE_VP8_FRAME	n/a	n/a	n/a	一個 struct v4l2_ctrl_vp8_frame，包含用於無狀態影片解碼器的 VP8 幀引數。
V4L2_CTRL_TYPE_HEVC_DECODE_PARAMS	n/a	n/a	n/a	一個 struct v4l2_ctrl_hevc_decode_params，包含用於無狀態影片解碼器的 HEVC 解碼引數。
V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR	n/a	n/a	n/a	一個 struct v4l2_ctrl_vp9_compressed_hdr，包含用於無狀態影片解碼器的 VP9 機率更新。
V4L2_CTRL_TYPE_VP9_FRAME	n/a	n/a	n/a	一個 struct v4l2_ctrl_vp9_frame，包含用於無狀態影片解碼器的 VP9 幀解碼引數。
V4L2_CTRL_TYPE_AV1_SEQUENCE	n/a	n/a	n/a	一個 struct v4l2_ctrl_av1_sequence，包含用於無狀態影片解碼器的 AV1 序列 OBU 解碼引數。
V4L2_CTRL_TYPE_AV1_TILE_GROUP_ENTRY	n/a	n/a	n/a	一個 struct v4l2_ctrl_av1_tile_group_entry，包含用於無狀態影片解碼器的 AV1 圖塊組 OBU 解碼引數。
V4L2_CTRL_TYPE_AV1_FRAME	n/a	n/a	n/a	一個 struct v4l2_ctrl_av1_frame，包含用於無狀態影片解碼器的 AV1 幀/幀頭 OBU 解碼引數。
V4L2_CTRL_TYPE_AV1_FILM_GRAIN	n/a	n/a	n/a	一個 struct v4l2_ctrl_av1_film_grain，包含用於無狀態影片解碼器的 AV1 膠片顆粒引數。

控制元件標誌

V4L2_CTRL_FLAG_DISABLED	0x0001	此控制元件已永久停用，應被應用程式忽略。任何更改控制元件的嘗試都將導致 EINVAL 錯誤程式碼。
V4L2_CTRL_FLAG_GRABBED	0x0002	此控制元件暫時無法更改，例如因為另一個應用程式控制了相應的資源。此類控制元件可能會在使用者介面中以特殊方式顯示。 嘗試更改控制元件可能會導致 EBUSY 錯誤程式碼。
V4L2_CTRL_FLAG_READ_ONLY	0x0004	此控制元件永久只讀。 任何更改控制元件的嘗試都會導致 EINVAL 錯誤程式碼。
V4L2_CTRL_FLAG_UPDATE	0x0008	提示：更改此控制元件可能會影響同一控制元件類中其他控制元件的值。 應用程式應相應地更新其使用者介面。
V4L2_CTRL_FLAG_INACTIVE	0x0010	此控制元件不適用於當前配置，應在使用者介面中相應地顯示。 例如，當使用另一個控制元件選擇 MPEG 音訊編碼級別 1 時，可以在 MPEG 音訊級別 2 位元率控制元件上設定此標誌。
V4L2_CTRL_FLAG_SLIDER	0x0020	提示：此控制元件最好在使用者介面中表示為類似滑塊的元素。
V4L2_CTRL_FLAG_WRITE_ONLY	0x0040	此控制元件永久只寫。 任何讀取控制元件的嘗試都會導致 EACCES 錯誤程式碼。 此標誌通常用於相對控制元件或操作控制元件，寫入值將導致裝置執行給定的操作（例如電機控制），但無法返回有意義的值。
V4L2_CTRL_FLAG_VOLATILE	0x0080	此控制元件是可變的，這意味著控制元件的值會持續變化。 一個典型的例子是如果裝置處於自動增益模式，則為當前增益值。 在這種情況下，硬體會根據光照條件計算增益值，而光照條件可能會隨著時間的推移而變化。 注意 除非同時設定了 V4L2_CTRL_FLAG_EXECUTE_ON_WRITE，否則設定可變控制元件的新值將被忽略。 設定可變控制元件的新值永遠不會觸發 V4L2_EVENT_CTRL_CH_VALUE 事件。
V4L2_CTRL_FLAG_HAS_PAYLOAD	0x0100	此控制元件具有指標型別，因此必須使用結構體 v4l2_ext_control 的指標欄位之一訪問其值。 對於陣列、字串或具有複合型別的控制元件，將設定此標誌。 在所有情況下，您都必須設定一個指標，指向包含控制元件有效負載的記憶體。
V4L2_CTRL_FLAG_EXECUTE_ON_WRITE	0x0200	即使提供給控制元件的值保持不變，也會將其傳播到驅動程式。 當控制元件表示硬體上的操作時，這是必需的。 例如：清除錯誤標誌或觸發閃光燈。 所有 V4L2_CTRL_TYPE_BUTTON 型別的控制元件都設定了此標誌。
V4L2_CTRL_FLAG_MODIFY_LAYOUT	0x0400	更改此控制元件值可能會修改緩衝區（對於影片裝置）或媒體匯流排格式（對於子裝置）的佈局。 一個典型的例子是 V4L2_CID_ROTATE 控制元件。 請注意，通常，當緩衝區分配或流傳輸正在進行時，具有此標誌的控制元件也將設定 V4L2_CTRL_FLAG_GRABBED 標誌，因為大多數驅動程式在這種情況下不支援更改格式。
V4L2_CTRL_FLAG_DYNAMIC_ARRAY	0x0800	此控制元件是動態大小的一維陣列。 它的行為與常規陣列相同，只是 elems 欄位報告的元素數量介於 1 和 dims[0] 之間。 因此，使用大小不同的陣列設定控制元件將更改之後查詢控制元件時的 elems 欄位。
V4L2_CTRL_FLAG_HAS_WHICH_MIN_MAX	0x1000	此控制元件支援使用 vidioc_g_ext_ctrls 和 V4L2_CTRL_WHICH_MIN/MAX_VAL 獲取最小值和最大值。

7.49.5. 返回值

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

EINVAL

結構體 v4l2_queryctrl 的 id 無效。 結構體 v4l2_querymenu 的 id 無效，或者 index 超出範圍（小於 minimum 或大於 maximum），或者驅動程式不支援此特定選單項。

EACCES

嘗試讀取只寫控制元件。

[1]

V4L2_CTRL_FLAG_DISABLED 旨在用於兩個目的：驅動程式可以跳過硬體不支援的預定義控制元件（雖然返回 EINVAL 也可以），或者在硬體檢測後停用預定義和私有控制元件，而無需重新排序控制元件陣列和索引的麻煩（EINVAL 不能用於跳過私有控制元件，因為它會過早結束列舉）。