7.14. ioctl VIDIOC_ENUM_FMT

7.14.1. 名称

VIDIOC_ENUM_FMT - 枚举图像格式

7.14.2. 概要

VIDIOC_ENUM_FMT

int ioctl(int fd, VIDIOC_ENUM_FMT, struct v4l2_fmtdesc *argp)

7.14.3. 参数

fd

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

argp

指向 struct v4l2_fmtdesc 的指针。

7.14.4. 描述

要枚举图像格式，应用程序初始化 struct v4l2_fmtdesc 的 type、 mbus_code 和 index 字段，并使用指向此结构的指针调用 ioctl VIDIOC_ENUM_FMT ioctl。驱动程序填写结构的其余部分或返回 EINVAL 错误代码。通过从索引零开始并递增一，直到返回 EINVAL，可以枚举所有格式。如果适用，驱动程序应按偏好顺序返回格式，其中首选格式在不太首选的格式之前返回（即，具有较低的 index 值）。

根据 V4L2_CAP_IO_MC 功能，mbus_code 字段的处理方式不同

1. 未设置 V4L2_CAP_IO_MC（也称为“以视频节点为中心”的驱动程序）

   应用程序应将 mbus_code 字段初始化为零，驱动程序应忽略该字段的值。

   驱动程序应枚举所有图像格式。

   注意

   切换输入或输出后，枚举的图像格式列表可能会有所不同。

2. 设置了 V4L2_CAP_IO_MC（也称为“以 MC 为中心”的驱动程序）

   如果 mbus_code 字段为零，则应枚举所有图像格式。

   如果 mbus_code 字段初始化为有效的（非零） 媒体总线格式代码，则驱动程序应将枚举限制为仅可生成（对于视频输出设备）或从该媒体总线代码生成的（对于视频捕获设备）的图像格式。如果驱动程序不支持 mbus_code，则应返回 EINVAL。

   无论 mbus_code 字段的值如何，枚举的图像格式都不应依赖于视频设备或设备管道的活动配置。

type v4l2_fmtdesc

struct v4l2_fmtdesc

__u32	index	枚举中格式的编号，由应用程序设置。这与 pixelformat 字段无关。当索引与 V4L2_FMTDESC_FLAG_ENUM_ALL 进行或运算时，驱动程序将清除该标志并枚举所有可能的格式，忽略当前配置的任何限制。不支持此标志的驱动程序始终返回 EINVAL 错误代码，而不清除此标志。当调用 VIDIOC_ENUM_FRAMESIZES() 或 VIDIOC_ENUM_FRAMEINTERVALS() 时，不应使用使用 V4L2_FMTDESC_FLAG_ENUM_ALL 标志枚举的格式。V4L2_FMTDESC_FLAG_ENUM_ALL 仅应由可以根据此标志返回不同格式列表的驱动程序使用。
__u32	type	数据流的类型，由应用程序设置。此处仅这些类型有效：V4L2_BUF_TYPE_VIDEO_CAPTURE、V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE、V4L2_BUF_TYPE_VIDEO_OUTPUT、V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE、V4L2_BUF_TYPE_VIDEO_OVERLAY、V4L2_BUF_TYPE_SDR_CAPTURE、V4L2_BUF_TYPE_SDR_OUTPUT、V4L2_BUF_TYPE_META_CAPTURE 和 V4L2_BUF_TYPE_META_OUTPUT。请参见 v4l2_buf_type。
__u32	flags	请参见 图像格式描述标志
__u8	description[32]	格式的描述，以 NUL 结尾的 ASCII 字符串。此信息供用户使用，例如：“YUV 4:2:2”。
__u32	pixelformat	图像格式标识符。这是由 v4l2_fourcc() 宏计算的四字符代码
#define v4l2_fourcc(a,b,c,d) (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24)) 此规范已在 图像格式 中定义了几种图像格式。 注意 这些代码与 Windows 世界中使用的代码不同。
__u32	mbus_code	限制枚举格式的媒体总线代码，由应用程序设置。仅适用于声明 V4L2_CAP_IO_MC 功能 的驱动程序，否则应为 0。
__u32	reserved[3]	保留供将来扩展。驱动程序必须将数组设置为零。

图像格式描述标志

V4L2_FMT_FLAG_COMPRESSED	0x0001	这是一种压缩格式。
V4L2_FMT_FLAG_EMULATED	0x0002	此格式不是设备的本机格式，而是通过软件（通常是 libv4l2）模拟的，如果可能，请尝试使用本机格式以获得更好的性能。
V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM	0x0004	此压缩字节流格式（又名编码格式）的硬件解码器能够解析连续字节流。应用程序无需自行解析字节流即可找到帧/字段之间的边界。 此标志只能与 V4L2_FMT_FLAG_COMPRESSED 标志结合使用，因为这仅适用于压缩格式。此标志仅对有状态解码器有效。
V4L2_FMT_FLAG_DYN_RESOLUTION	0x0008	设备对这种压缩字节流格式（又名编码格式）支持动态分辨率切换。当检测到视频参数发生更改时，它将通过事件 V4L2_EVENT_SOURCE_CHANGE 通知用户。 此标志只能与 V4L2_FMT_FLAG_COMPRESSED 标志结合使用，因为这仅适用于压缩格式。此标志仅对有状态编解码器有效。
V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL	0x0010	硬件编码器支持将 CAPTURE 编码帧间隔与 OUTPUT 原始帧间隔分开设置。使用 VIDIOC_S_PARM 设置 OUTPUT 原始帧间隔时，也会将 CAPTURE 编码帧间隔设置为相同的值。如果设置了此标志，则可以随后将 CAPTURE 编码帧间隔设置为不同的值。这通常用于离线编码，其中 OUTPUT 原始帧间隔用作保留硬件编码器资源的提示，而 CAPTURE 编码帧间隔是嵌入到编码视频流中的实际帧率。 此标志只能与 V4L2_FMT_FLAG_COMPRESSED 标志组合使用，因为它仅适用于压缩格式。此标志仅对有状态编码器有效。
V4L2_FMT_FLAG_CSC_COLORSPACE	0x0020	驱动程序允许应用程序尝试更改默认的色彩空间。此标志仅与捕获设备相关。应用程序可以在调用 VIDIOC_S_FMT ioctl 时，设置 V4L2_PIX_FMT_FLAG_SET_CSC，从而请求配置捕获设备的色彩空间。
V4L2_FMT_FLAG_CSC_XFER_FUNC	0x0040	驱动程序允许应用程序尝试更改默认的传递函数。此标志仅与捕获设备相关。应用程序可以在调用 VIDIOC_S_FMT ioctl 时，设置 V4L2_PIX_FMT_FLAG_SET_CSC，从而请求配置捕获设备的传递函数。
V4L2_FMT_FLAG_CSC_YCBCR_ENC	0x0080	驱动程序允许应用程序尝试更改默认的 Y’CbCr 编码。此标志仅与捕获设备相关。应用程序可以在调用 VIDIOC_S_FMT ioctl 时，设置 V4L2_PIX_FMT_FLAG_SET_CSC，从而请求配置捕获设备的 Y’CbCr 编码。
V4L2_FMT_FLAG_CSC_HSV_ENC	0x0080	驱动程序允许应用程序尝试更改默认的 HSV 编码。此标志仅与捕获设备相关。应用程序可以在调用 VIDIOC_S_FMT ioctl 时，设置 V4L2_PIX_FMT_FLAG_SET_CSC，从而请求配置捕获设备的 HSV 编码。
V4L2_FMT_FLAG_CSC_QUANTIZATION	0x0100	驱动程序允许应用程序尝试更改默认的量化。此标志仅与捕获设备相关。应用程序可以在调用 VIDIOC_S_FMT ioctl 时，设置 V4L2_PIX_FMT_FLAG_SET_CSC，从而请求配置捕获设备的量化。
V4L2_FMT_FLAG_META_LINE_BASED	0x0200	元数据格式是基于行的。在这种情况下，v4l2_meta_format 的 width、height 和 bytesperline 字段有效。缓冲区由 height 行组成，每行具有 width 个数据单元，并且每两个连续行开头的偏移量（以字节为单位）是 bytesperline。
V4L2_FMTDESC_FLAG_ENUM_ALL	0x80000000	当应用程序将 index 与 V4L2_FMTDESC_FLAG_ENUM_ALL 标志进行 OR 运算时，驱动程序会枚举所有可能的像素格式，而不考虑任何已设置的配置。不支持此标志的驱动程序始终返回 EINVAL，而不清除此标志。

7.14.5. 返回值

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

EINVAL

v4l2_fmtdesc 结构体的 type 不受支持或 index 超出范围。

如果设置了 V4L2_CAP_IO_MC 且指定的 mbus_code 不受支持，则也会返回此错误代码。