7.39. ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION

7.39.1. 名称

VIDIOC_G_SELECTION - VIDIOC_S_SELECTION - 获取或设置一个选择矩形

7.39.2. 概要

VIDIOC_G_SELECTION

int ioctl(int fd, VIDIOC_G_SELECTION, struct v4l2_selection *argp)

VIDIOC_S_SELECTION

int ioctl(int fd, VIDIOC_S_SELECTION, struct v4l2_selection *argp)

7.39.3. 参数

fd

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

argp

指向 struct v4l2_selection 的指针。

7.39.4. 描述

ioctl 用于查询和配置选择矩形。

要查询裁剪（合成）矩形，请将 struct v4l2_selection 的 type 字段设置为相应的缓冲区类型。下一步是将 struct v4l2_selection 的 target 字段的值设置为 V4L2_SEL_TGT_CROP (V4L2_SEL_TGT_COMPOSE)。有关其他目标，请参阅表 通用选择定义 或 裁剪、合成和缩放 -- SELECTION API。struct v4l2_selection 的 flags 和 reserved 字段将被忽略，并且必须填充为零。如果使用了不正确的缓冲区类型或目标，则驱动程序会填充结构的其余部分或返回 EINVAL 错误代码。如果不支持裁剪（合成），则活动矩形是不可变的，并且始终等于边界矩形。最后，struct v4l2_rect 的 r 矩形将填充当前的裁剪（合成）坐标。这些坐标以驱动程序相关的单位表示。唯一的例外是原始格式的图像的矩形，其坐标始终以像素表示。

要更改裁剪（合成）矩形，请将 struct v4l2_selection 的 type 字段设置为相应的缓冲区类型。下一步是将 struct v4l2_selection 的 target 的值设置为 V4L2_SEL_TGT_CROP (V4L2_SEL_TGT_COMPOSE)。有关其他目标，请参阅表 通用选择定义 或 裁剪、合成和缩放 -- SELECTION API。struct v4l2_rect 的 r 矩形需要设置为所需的活动区域。struct v4l2_selection 的 reserved 字段将被忽略，并且必须填充为零。驱动程序可能会调整请求的矩形的坐标。应用程序可以引入约束来控制舍入行为。struct v4l2_selection 的 flags 字段必须设置为以下值之一

  • 0 - 驱动程序可以自由调整矩形大小，并且应选择尽可能接近请求的裁剪/合成矩形。

  • V4L2_SEL_FLAG_GE - 不允许驱动程序缩小矩形。原始矩形必须位于调整后的矩形内部。

  • V4L2_SEL_FLAG_LE - 不允许驱动程序放大矩形。调整后的矩形必须位于原始矩形内部。

  • V4L2_SEL_FLAG_GE | V4L2_SEL_FLAG_LE - 驱动程序必须选择与请求的矩形大小完全相同的大小。

请参阅 具有约束标志的大小调整。。

驱动程序可能需要根据硬件限制和管道的其他部分（例如，捕获/输出窗口或电视显示器给出的边界）调整请求的尺寸。水平和垂直偏移以及大小的最接近的可能值是根据以下优先级选择的

  1. 满足 struct v4l2_selection 的 flags 的约束。

  2. 将宽度、高度、左侧和顶部调整为硬件限制和对齐方式。

  3. 保持调整后矩形的中心尽可能接近原始矩形的中心。

  4. 保持宽度和高度尽可能接近原始值。

  5. 保持水平和垂直偏移尽可能接近原始值。

成功后，struct v4l2_rect 的 r 字段包含调整后的矩形。当参数不合适时，应用程序可能会修改裁剪（合成）或图像参数，并重复该循环，直到协商出令人满意的参数为止。如果必须违反约束标志，则返回 ERANGE。该错误表示不存在满足约束的矩形。

选择目标和标志在 通用选择定义 中进行了说明。

constraints.svg

具有约束标志的大小调整。

针对不同约束标志的矩形调整行为。

type v4l2_selection
struct v4l2_selection

__u32

type

缓冲区类型（来自枚举 v4l2_buf_type）。

__u32

target

用于在 裁剪和合成矩形 之间进行选择。

__u32

flags

控制选择矩形调整的标志，请参阅 选择标志。

struct v4l2_rect

r

选择矩形。

__u32

reserved[9]

保留字段以供将来使用。驱动程序和应用程序必须将此数组清零。

注意

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

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

7.39.5. 返回值

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

EINVAL

给定缓冲区类型 type 或选择目标 target 不受支持，或者 flags 参数无效。

ERANGE

无法调整结构体 v4l2_rect r 矩形以满足 flags 参数中给出的所有约束。

ENODATA

此输入或输出不支持选择。

EBUSY

目前无法应用选择矩形的更改。通常是因为流媒体正在进行中。