7.24. ioctl VIDIOC_G_CROP, VIDIOC_S_CROP

7.24.1. 名称

VIDIOC_G_CROP - VIDIOC_S_CROP - 获取或设置当前裁剪矩形

7.24.2. 概要

VIDIOC_G_CROP

int ioctl(int fd, VIDIOC_G_CROP, struct v4l2_crop *argp)

VIDIOC_S_CROP

int ioctl(int fd, VIDIOC_S_CROP, const struct v4l2_crop *argp)

7.24.3. 参数

fd

由 open() 返回的文件描述符。

argp

指向 struct v4l2_crop 的指针。

7.24.4. 描述

要查询裁剪矩形的大小和位置，应用程序将 struct v4l2_crop 结构的 type 字段设置为相应的缓冲区（流）类型，并使用指向此结构的指针调用 VIDIOC_G_CROP ioctl。如果不支持裁剪，驱动程序将填充结构的其余部分或返回 EINVAL 错误代码。

要更改裁剪矩形，应用程序初始化 v4l2_crop 结构的 type 和名为 c 的 struct v4l2_rect 子结构，并使用指向此结构的指针调用 VIDIOC_S_CROP ioctl。

驱动程序首先根据硬件限制调整请求的尺寸，即捕获/输出窗口给定的边界，并将其舍入到水平和垂直偏移、宽度和高度的最接近的可能值。特别是，驱动程序必须将裁剪矩形的垂直偏移舍入为帧线模 2，这样就不会混淆字段顺序。

其次，驱动程序调整图像大小（缩放过程的相反矩形，根据数据方向为源或目标），使其尽可能接近当前水平和垂直缩放因子的大小。

最后，驱动程序使用实际的裁剪和图像参数对硬件进行编程。VIDIOC_S_CROP 是一个只写 ioctl，它不返回实际的参数。要查询它们，应用程序必须调用 VIDIOC_G_CROP 和 ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT。当参数不合适时，应用程序可以修改裁剪或图像参数并重复该循环，直到协商出令人满意的参数。

如果不支持裁剪，则不会更改任何参数，并且 VIDIOC_S_CROP 返回 EINVAL 错误代码。

type v4l2_crop

struct v4l2_crop

__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	c	裁剪矩形。使用与 struct v4l2_cropcap bounds 相同的坐标系。

注意

不幸的是，在多平面缓冲区类型（V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE 和 V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE）的情况下，此 API 在 v4l2_crop type 字段的填充方式方面搞砸了。一些驱动程序只接受 _MPLANE 缓冲区类型，而其他驱动程序只接受非多平面缓冲区类型（即末尾没有 _MPLANE）。

从内核 4.13 开始，允许两种变体。

7.24.5. 返回值

成功时返回 0，错误时返回 -1，并适当设置 errno 变量。通用错误代码在 通用错误代码 一章中描述。

ENODATA

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