7.59. ioctl VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP

7.59.1. 名稱

VIDIOC_SUBDEV_G_CROP - VIDIOC_SUBDEV_S_CROP - 獲取或設定 subdev pad 上的裁剪矩形

7.59.2. 概要

VIDIOC_SUBDEV_G_CROP

int ioctl(int fd, VIDIOC_SUBDEV_G_CROP, struct v4l2_subdev_crop *argp)

VIDIOC_SUBDEV_S_CROP

int ioctl(int fd, VIDIOC_SUBDEV_S_CROP, const struct v4l2_subdev_crop *argp)

7.59.3. 引數

fd

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

argp

指向 struct v4l2_subdev_crop 的指標。

7.59.4. 描述

注意

這是一個 Obsolete API Elements 介面，將來可能會被刪除。它被 the selection API 取代。將不接受對 v4l2_subdev_crop 結構的任何新擴充套件。

要檢索當前的裁剪矩形，應用程式將 struct v4l2_subdev_crop 的 pad 欄位設定為媒體 API 報告的所需 pad 編號，並將 which 欄位設定為 V4L2_SUBDEV_FORMAT_ACTIVE。然後，它們使用指向此結構的指標呼叫 VIDIOC_SUBDEV_G_CROP ioctl。如果輸入引數無效，或者給定的 pad 不支援裁剪，則驅動程式會填充 rect 欄位的成員，或者返回 EINVAL 錯誤程式碼。

要更改當前的裁剪矩形，應用程式設定 pad 和 which 欄位以及 rect 欄位的所有成員。然後，它們使用指向此結構的指標呼叫 VIDIOC_SUBDEV_S_CROP ioctl。驅動程式驗證請求的裁剪矩形，根據硬體功能進行調整，並配置裝置。返回時，struct v4l2_subdev_crop 包含當前的格式，就像 VIDIOC_SUBDEV_G_CROP 呼叫返回的一樣。

應用程式可以透過將 which 設定為 V4L2_SUBDEV_FORMAT_TRY 來查詢裝置功能。設定後，驅動程式不會將 ‘try’ 裁剪矩形應用於裝置，而是像活動裁剪矩形一樣進行修改，並存儲在子裝置檔案控制代碼中。因此，查詢同一子裝置的兩個應用程式不會相互互動。

如果子裝置節點以只讀模式註冊，則僅當 which 欄位設定為 V4L2_SUBDEV_FORMAT_TRY 時，對 VIDIOC_SUBDEV_S_CROP 的呼叫才有效，否則將返回錯誤，並且 errno 變數設定為 -EPERM。

驅動程式不能僅因為請求的裁剪矩形與裝置功能不匹配而返回錯誤。相反，它們必須修改矩形以匹配硬體可以提供的功能。修改後的格式應儘可能接近原始請求。

type v4l2_subdev_crop

struct v4l2_subdev_crop

__u32	pad	媒體框架報告的 Pad 編號。
__u32	which	要獲取或設定的裁剪矩形，來自 enum v4l2_subdev_format_whence。
struct v4l2_rect	rect	裁剪矩形邊界，以畫素為單位。
__u32	stream	流識別符號。
__u32	reserved[7]	保留供將來擴充套件。應用程式和驅動程式必須將陣列設定為零。

7.59.5. 返回值

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

EBUSY

裁剪矩形無法更改，因為 pad 當前正忙。例如，這可能是由 pad 上活動的影片流引起的。在執行另一個操作來解決問題之前，不得重試 ioctl。僅由 VIDIOC_SUBDEV_S_CROP 返回

EINVAL

struct v4l2_subdev_crop pad 引用了一個不存在的 pad，which 欄位具有不支援的值，或者給定的 subdev pad 不支援裁剪。

EPERM

已在只讀子裝置上呼叫 VIDIOC_SUBDEV_S_CROP ioctl，並且 which 欄位設定為 V4L2_SUBDEV_FORMAT_ACTIVE。