7.4. ioctl VIDIOC_CROPCAP

7.4.1. 名称

VIDIOC_CROPCAP - 关于视频裁剪和缩放能力的信息

7.4.2. 概要

VIDIOC_CROPCAP

int ioctl(int fd, VIDIOC_CROPCAP, struct v4l2_cropcap *argp)

7.4.3. 参数

fd

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

argp

指向 struct v4l2_cropcap 的指针。

7.4.4. 描述

应用程序使用此函数查询裁剪限制、图像的像素宽高比并计算缩放因子。它们将 v4l2_cropcap 结构的 type 字段设置为相应的缓冲区(流)类型,并调用 ioctl VIDIOC_CROPCAP ioctl,并带有指向此结构的指针。驱动程序填充结构的其余部分。结果是常量,除非切换视频标准。请记住,当切换视频输入或输出时,可能会隐式发生此切换。

对于支持裁剪和/或缩放和/或具有非方形像素的视频捕获或输出设备,以及对于覆盖设备,必须实现此 ioctl。

type v4l2_cropcap
struct v4l2_cropcap

__u32

type

数据流的类型,由应用程序设置。只有以下类型在此处有效:V4L2_BUF_TYPE_VIDEO_CAPTUREV4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANEV4L2_BUF_TYPE_VIDEO_OUTPUTV4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANEV4L2_BUF_TYPE_VIDEO_OVERLAY。请参阅 v4l2_buf_type 和下面的注释。

struct v4l2_rect

bounds

定义了可以在其中进行捕获或输出的窗口,这可能会排除例如水平和垂直消隐区域。裁剪矩形不能超出这些限制。宽度和高度以像素为单位定义,驱动程序编写者可以自由选择模拟域中坐标系的原点和单位。

struct v4l2_rect

defrect

默认裁剪矩形,它应覆盖“整个图片”。假设像素宽高比为 1/1,对于 NTSC,这可以是例如 640 × 480 矩形,对于 PAL 和 SECAM,这可以是 768 × 576 矩形,并且位于活动图片区域的中心。使用与 bounds 相同的坐标系。

struct v4l2_fract

pixelaspect

这是未应用缩放时的像素宽高比 (y / x),实际采样频率与获得方形像素所需的频率之比。

当裁剪坐标引用方形像素时,驱动程序会将 pixelaspect 设置为 1/1。其他常见值为 PAL 和 SECAM 的 54/59,以及根据 [ITU BT.601] 采样的 NTSC 的 11/10。

注意

不幸的是,对于多平面缓冲区类型(V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANEV4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE),此API在 v4l2_cropcap type 字段的填充方式方面存在问题。某些驱动程序仅接受 _MPLANE 缓冲区类型,而其他驱动程序仅接受非多平面缓冲区类型(即,末尾没有 _MPLANE)。

从内核 4.13 开始,两种变体都是允许的。

struct v4l2_rect

__s32

left

矩形左上角的水平偏移量,以像素为单位。

__s32

top

矩形左上角的垂直偏移量,以像素为单位。

__u32

width

矩形的宽度,以像素为单位。

__u32

height

矩形的高度,以像素为单位。

7.4.5. 返回值

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

EINVAL

struct v4l2_cropcap type 无效。

ENODATA

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