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	切片 VBI 捕获或输出参数。 有关详细信息，请参阅 切片 VBI 数据接口。 由切片 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相关。