7.39. ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION

7.39.1. 名稱

VIDIOC_G_SELECTION - VIDIOC_S_SELECTION - 獲取或設定一個選擇矩形

7.39.2. 概要

VIDIOC_G_SELECTION

int ioctl(int fd, VIDIOC_G_SELECTION, struct v4l2_selection *argp)

VIDIOC_S_SELECTION

int ioctl(int fd, VIDIOC_S_SELECTION, struct v4l2_selection *argp)

7.39.3. 引數

fd

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

argp

指向 struct v4l2_selection 的指標。

7.39.4. 描述

這些ioctl用於查詢和配置選擇矩形。

要查詢裁剪（合成）矩形，請將 struct v4l2_selection type 欄位設定為相應的緩衝區型別。下一步是將 struct v4l2_selection target 欄位的值設定為 V4L2_SEL_TGT_CROP (V4L2_SEL_TGT_COMPOSE)。有關其他目標，請參閱表 通用選擇定義 或 裁剪、合成和縮放 -- SELECTION API。struct v4l2_selection 的 flags 和 reserved 欄位將被忽略，並且必須填充為零。驅動程式填充結構的其餘部分，或者如果使用了不正確的緩衝區型別或目標，則返回 EINVAL 錯誤程式碼。如果不支援裁剪（合成），則活動矩形是不可變的，並且始終等於邊界矩形。最後，struct v4l2_rect r 矩形填充有當前裁剪（合成）座標。座標以驅動程式相關的單位表示。唯一的例外是原始格式影像的矩形，其座標始終以畫素表示。

要更改裁剪（合成）矩形，請將 struct v4l2_selection type 欄位設定為相應的緩衝區型別。下一步是將 struct v4l2_selection target 設定為 V4L2_SEL_TGT_CROP (V4L2_SEL_TGT_COMPOSE)。有關其他目標，請參閱表 通用選擇定義 或 裁剪、合成和縮放 -- SELECTION API。struct v4l2_rect r 矩形需要設定為所需的活動區域。欄位 struct v4l2_selection reserved 被忽略，必須填充為零。驅動程式可能會調整請求矩形的座標。應用程式可以引入約束來控制舍入行為。struct v4l2_selection flags 欄位必須設定為以下之一

  • 0 - 驅動程式可以自由調整矩形大小，並應選擇儘可能接近所請求的裁剪/合成矩形。

  • V4L2_SEL_FLAG_GE - 不允許驅動程式縮小矩形。原始矩形必須位於調整後的矩形內。

  • V4L2_SEL_FLAG_LE - 不允許驅動程式放大矩形。調整後的矩形必須位於原始矩形內。

  • V4L2_SEL_FLAG_GE | V4L2_SEL_FLAG_LE - 驅動程式必須選擇與請求的矩形完全相同的大小。

請參閱 使用約束標誌進行大小調整。。

驅動程式可能需要根據硬體限制和流水線的其他部分（例如捕獲/輸出視窗或電視顯示器給出的邊界）調整請求的尺寸。水平和垂直偏移以及大小的最接近可能值是根據以下優先順序選擇的

  1. 滿足來自 struct v4l2_selection flags 的約束。

  2. 將寬度、高度、左側和頂部調整為硬體限制和對齊方式。

  3. 保持調整後的矩形的中心儘可能接近原始矩形的中心。

  4. 保持寬度和高度儘可能接近原始寬度和高度。

  5. 保持水平和垂直偏移儘可能接近原始水平和垂直偏移。

成功後，struct v4l2_rect r 欄位包含調整後的矩形。當引數不合適時，應用程式可以修改裁剪（合成）或影像引數，並重復該迴圈，直到協商出令人滿意的引數。如果約束標誌必須被違反，則返回 ERANGE。該錯誤表示不存在滿足約束的矩形。

選擇目標和標誌記錄在 通用選擇定義 中。

constraints.svg

使用約束標誌進行大小調整。

不同約束標誌的矩形調整行為。

type v4l2_selection
struct v4l2_selection

__u32

type

緩衝區型別（來自 enum v4l2_buf_type）。

__u32

target

用於在 裁剪和合成矩形 之間進行選擇。

__u32

flags

控制選擇矩形調整的標誌，請參閱 選擇標誌。

struct v4l2_rect

r

選擇矩形。

__u32

reserved[9]

保留欄位供將來使用。驅動程式和應用程式必須將此陣列置零。

注意

不幸的是，對於多平面緩衝區型別（V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE 和 V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE），此API在 v4l2_selection type 欄位的填充方式上被搞砸了。一些驅動程式只接受 _MPLANE 緩衝區型別，而其他驅動程式只接受非多平面緩衝區型別（即，末尾沒有 _MPLANE）。

從核心4.13開始，允許兩種變體。

7.39.5. 返回值

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

EINVAL

給定的緩衝區型別 type 或選擇目標 target 不受支援，或者 flags 引數無效。

ERANGE

無法調整 struct v4l2_rect r 矩形以滿足 flags 引數中給出的所有約束。

ENODATA

此輸入或輸出不支援選擇。

EBUSY

目前無法應用選擇矩形的更改。通常是因為流式傳輸正在進行中。