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

指向结构体 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

结构体 v4l2_cropcap type 无效。

ENODATA

此输入或输出不支持裁剪。