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 进行 OR 运算时，驱动程序清除该标志并枚举所有可能的格式，忽略当前配置的任何限制。不支持此标志的驱动程序始终返回 EINVAL 错误代码，而不清除此标志。使用 V4L2_FMTDESC_FLAG_ENUM_ALL 标志枚举的格式不应在调用 VIDIOC_ENUM_FRAMESIZES() 或 VIDIOC_ENUM_FRAMEINTERVALS() 时使用。 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 时请求配置捕获设备的 Y'CbCr 编码，并设置 V4L2_PIX_FMT_FLAG_SET_CSC。
V4L2_FMT_FLAG_CSC_HSV_ENC	0x0080	驱动程序允许应用程序尝试更改默认 HSV 编码。 此标志仅与捕获设备相关。 应用程序可以在调用 VIDIOC_S_FMT ioctl 时请求配置捕获设备的 HSV 编码，并设置 V4L2_PIX_FMT_FLAG_SET_CSC。
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

不支持 struct v4l2_fmtdesc type 或 index 超出范围。

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