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

缓冲区类型（来自 enum 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

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

ENODATA

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

EBUSY

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