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。