7.31. ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT

7.31.1. 名称

VIDIOC_G_FMT - VIDIOC_S_FMT - VIDIOC_TRY_FMT - 获取或设置数据格式，尝试格式

7.31.2. 概要

VIDIOC_G_FMT

int ioctl(int fd, VIDIOC_G_FMT, struct v4l2_format *argp)

VIDIOC_S_FMT

int ioctl(int fd, VIDIOC_S_FMT, struct v4l2_format *argp)

VIDIOC_TRY_FMT

int ioctl(int fd, VIDIOC_TRY_FMT, struct v4l2_format *argp)

7.31.3. 参数

fd

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

argp

指向 struct v4l2_format 的指针。

7.31.4. 描述

这些 ioctl 用于协商驱动程序和应用程序之间交换的数据格式（通常是图像格式）。

要查询当前参数，应用程序将 struct v4l2_format 的 type 字段设置为相应的缓冲区（流）类型。例如，视频捕获设备使用 V4L2_BUF_TYPE_VIDEO_CAPTURE 或 V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE。当应用程序使用指向此结构的指针调用 VIDIOC_G_FMT ioctl 时，驱动程序会填充 fmt 联合体的相应成员。如果是视频捕获设备，则是 struct v4l2_pix_format pix 或 struct v4l2_pix_format_mplane pix_mp 成员。如果不支持请求的缓冲区类型，驱动程序将返回 EINVAL 错误代码。

要更改当前格式参数，应用程序初始化 type 字段和相应 fmt 联合体成员的所有字段。有关详细信息，请参见 接口 中各种设备类型的文档。好的做法是首先查询当前参数，然后仅修改那些不适合应用程序的参数。当应用程序使用指向 struct v4l2_format 结构的指针调用 VIDIOC_S_FMT ioctl 时，驱动程序会检查参数并根据硬件能力进行调整。除非 type 字段无效，否则驱动程序不应返回错误代码，这是一种探测设备功能并接近应用程序和驱动程序都可接受的参数的机制。成功后，驱动程序可以对硬件进行编程、分配资源并通常为数据交换做准备。最后，VIDIOC_S_FMT ioctl 返回当前格式参数，就像 VIDIOC_G_FMT 一样。非常简单、不灵活的设备甚至可能忽略所有输入并始终返回默认参数。但是，所有与应用程序交换数据的 V4L2 设备都必须实现 VIDIOC_G_FMT 和 VIDIOC_S_FMT ioctl。如果不支持请求的缓冲区类型，驱动程序会在 VIDIOC_S_FMT 尝试时返回 EINVAL 错误代码。如果 I/O 已经在进行中或者由于其他原因资源不可用，驱动程序会返回 EBUSY 错误代码。

VIDIOC_TRY_FMT ioctl 等效于 VIDIOC_S_FMT，但有一个例外：它不会更改驱动程序状态。它也可以随时调用，永远不会返回 EBUSY。此函数用于协商参数、了解硬件限制，而无需禁用 I/O 或可能耗时的硬件准备。虽然强烈建议，但不需要驱动程序实现此 ioctl。

由 VIDIOC_TRY_FMT 返回的格式必须与 VIDIOC_S_FMT 为相同输入或输出返回的格式相同。

type v4l2_format

struct v4l2_format

__u32	type	数据流的类型，请参见 v4l2_buf_type。
union {	fmt
struct v4l2_pix_format	pix	图像格式的定义，请参见 图像格式，由视频捕获和输出设备使用。
struct v4l2_pix_format_mplane	pix_mp	图像格式的定义，请参见 图像格式，由支持 API 的多平面版本 的视频捕获和输出设备使用。
struct v4l2_window	win	覆盖图像的定义，请参见 视频覆盖接口，由视频覆盖设备使用。
struct v4l2_vbi_format	vbi	原始 VBI 捕获或输出参数。这将在 原始 VBI 数据接口 中更详细地讨论。由原始 VBI 捕获和输出设备使用。
struct v4l2_sliced_vbi_format	sliced	Sliced VBI 捕获或输出参数。有关详细信息，请参见 Sliced VBI 数据接口。由 sliced VBI 捕获和输出设备使用。
struct v4l2_sdr_format	sdr	数据格式的定义，请参见 图像格式，由 SDR 捕获和输出设备使用。
struct v4l2_meta_format	meta	元数据格式的定义，请参见 元数据格式，由元数据捕获设备使用。
__u8	raw_data[200]	未来扩展的占位符。
}

7.31.5. 返回值

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

EINVAL

struct v4l2_format type 字段无效或不支持请求的缓冲区类型。

EBUSY

设备忙，无法更改格式。这可能是因为设备正在流式传输或者缓冲区已分配或排队到驱动程序。仅与 VIDIOC_S_FMT 相关。