7.4. ioctl VIDIOC_CROPCAP

7.4.1. 名稱

VIDIOC_CROPCAP - 關於影片裁剪和縮放能力的資訊

7.4.2. 概要

VIDIOC_CROPCAP

int ioctl(int fd, VIDIOC_CROPCAP, struct v4l2_cropcap *argp)

7.4.3. 引數

fd

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

argp

指向 struct v4l2_cropcap 的指標。

7.4.4. 描述

應用程式使用此函式查詢裁剪限制、影像的畫素寬高比並計算縮放因子。它們將 v4l2_cropcap 結構的 type 欄位設定為相應的緩衝區（流）型別，並呼叫 ioctl VIDIOC_CROPCAP ioctl，並帶有指向此結構的指標。驅動程式填充結構的其餘部分。結果是常量，除非切換影片標準。請記住，當切換影片輸入或輸出時，可能會隱式發生此切換。

對於支援裁剪和/或縮放和/或具有非方形畫素的影片捕獲或輸出裝置，以及對於覆蓋裝置，必須實現此 ioctl。

type v4l2_cropcap

struct v4l2_cropcap

__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 和下面的註釋。
struct v4l2_rect	bounds	定義了可以在其中進行捕獲或輸出的視窗，這可能會排除例如水平和垂直消隱區域。裁剪矩形不能超出這些限制。寬度和高度以畫素為單位定義，驅動程式編寫者可以自由選擇模擬域中座標系的原點和單位。
struct v4l2_rect	defrect	預設裁剪矩形，它應覆蓋“整個圖片”。假設畫素寬高比為 1/1，對於 NTSC，這可以是例如 640 × 480 矩形，對於 PAL 和 SECAM，這可以是 768 × 576 矩形，並且位於活動圖片區域的中心。使用與 bounds 相同的座標系。
struct v4l2_fract	pixelaspect	這是未應用縮放時的畫素寬高比 (y / x)，實際取樣頻率與獲得方形畫素所需的頻率之比。 當裁剪座標引用方形畫素時，驅動程式會將 pixelaspect 設定為 1/1。其他常見值為 PAL 和 SECAM 的 54/59，以及根據 [ITU BT.601] 取樣的 NTSC 的 11/10。

注意

不幸的是，對於多平面緩衝區型別（V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE 和 V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE），此API在 v4l2_cropcap type 欄位的填充方式方面存在問題。某些驅動程式僅接受 _MPLANE 緩衝區型別，而其他驅動程式僅接受非多平面緩衝區型別（即，末尾沒有 _MPLANE）。

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

struct v4l2_rect

__s32	left	矩形左上角的水平偏移量，以畫素為單位。
__s32	top	矩形左上角的垂直偏移量，以畫素為單位。
__u32	width	矩形的寬度，以畫素為單位。
__u32	height	矩形的高度，以畫素為單位。

7.4.5. 返回值

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

EINVAL

struct v4l2_cropcap type 無效。

ENODATA

此輸入或輸出不支援裁剪。