7.59. ioctl VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP

7.59.1. 名称

VIDIOC_SUBDEV_G_CROP - VIDIOC_SUBDEV_S_CROP - 获取或设置子设备焊盘上的裁剪矩形

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. 描述

注意

这是一个 过时的 API 元素 接口，未来可能会被删除。它被 选择 API 取代。不会接受对 v4l2_subdev_crop 结构的任何新扩展。

要检索当前的裁剪矩形，应用程序将 struct v4l2_subdev_crop 的 pad 字段设置为媒体 API 报告的所需焊盘编号，并将 which 字段设置为 V4L2_SUBDEV_FORMAT_ACTIVE。然后，它们使用指向此结构的指针调用 VIDIOC_SUBDEV_G_CROP ioctl。驱动程序填充 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。

驱动程序不得仅仅因为请求的裁剪矩形与设备功能不匹配而返回错误。它们必须修改矩形以匹配硬件可以提供的功能。修改后的格式应尽可能接近原始请求。

类型 v4l2_subdev_crop

struct v4l2_subdev_crop

__u32	pad	媒体框架报告的焊盘编号。
__u32	which	要获取或设置的裁剪矩形，来自枚举 v4l2_subdev_format_whence。
struct v4l2_rect	rect	裁剪矩形边界，以像素为单位。
__u32	stream	流标识符。
__u32	reserved[7]	保留供未来扩展使用。应用程序和驱动程序必须将数组设置为零。

7.59.5. 返回值

成功时返回 0，错误时返回 -1，并根据情况设置 errno 变量。通用错误代码在 通用错误代码 章节中描述。

EBUSY

由于焊盘当前正忙，因此无法更改裁剪矩形。例如，这可能是由焊盘上的活动视频流引起的。必须在执行其他操作来首先解决问题的情况下，才能重试 ioctl。仅由 VIDIOC_SUBDEV_S_CROP 返回

EINVAL

struct v4l2_subdev_crop pad 引用了不存在的焊盘，which 字段具有不受支持的值，或者在给定的子设备焊盘上不支持裁剪。

EPERM

已在只读子设备上调用了 VIDIOC_SUBDEV_S_CROP ioctl，并且 which 字段设置为 V4L2_SUBDEV_FORMAT_ACTIVE。