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

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