7.60. ioctl VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT¶

7.60.1. 名称¶

VIDIOC_SUBDEV_G_FMT - VIDIOC_SUBDEV_S_FMT - 获取或设置 subdev pad 上的数据格式

7.60.2. 概要¶

VIDIOC_SUBDEV_G_FMT¶

int ioctl(int fd, VIDIOC_SUBDEV_G_FMT, struct v4l2_subdev_format *argp)

VIDIOC_SUBDEV_S_FMT¶

int ioctl(int fd, VIDIOC_SUBDEV_S_FMT, struct v4l2_subdev_format *argp)

7.60.3. 参数¶

fd: 由 open() 返回的文件描述符。
argp: 指向 struct v4l2_subdev_format 的指针。

7.60.4. 描述¶

这些 ioctl 用于协商图像流水线中特定 subdev pad 的帧格式。

要检索当前格式，应用程序将 struct v4l2_subdev_format 的 pad 字段设置为媒体 API 报告的所需 pad 编号，并将 which 字段设置为 V4L2_SUBDEV_FORMAT_ACTIVE。当它们使用指向此结构的指针调用 VIDIOC_SUBDEV_G_FMT ioctl 时，驱动程序会填充 format 字段的成员。

要更改当前格式，应用程序同时设置 pad 和 which 字段以及 format 字段的所有成员。当它们使用指向此结构的指针调用 VIDIOC_SUBDEV_S_FMT ioctl 时，驱动程序会验证请求的格式，根据硬件功能对其进行调整并配置设备。返回时，struct v4l2_subdev_format 包含当前格式，就像 VIDIOC_SUBDEV_G_FMT 调用返回的一样。

应用程序可以通过将 which 设置为 V4L2_SUBDEV_FORMAT_TRY 来查询设备功能。设置后，驱动程序不会将“try”格式应用于设备，而是像活动格式一样进行更改并存储在子设备文件句柄中。因此，两个查询同一子设备的应用程序不会相互影响。

例如，要在子设备的输出 pad 上尝试一种格式，应用程序首先使用 VIDIOC_SUBDEV_S_FMT ioctl 在子设备输入处设置 try 格式。然后，它们将使用 VIDIOC_SUBDEV_G_FMT ioctl 检索输出 pad 上的默认格式，或者使用 VIDIOC_SUBDEV_S_FMT ioctl 设置所需的输出 pad 格式并检查返回值。

Try 格式不依赖于活动格式，但可以依赖于当前的链接配置或子设备控件值。例如，低通噪声滤波器可能会裁剪帧边界处的像素，从而修改其输出帧大小。

如果子设备节点已在只读模式下注册，则仅当 which 字段设置为 V4L2_SUBDEV_FORMAT_TRY 时，对 VIDIOC_SUBDEV_S_FMT 的调用才有效，否则会返回错误，并将 errno 变量设置为 -EPERM。

驱动程序不能仅仅因为请求的格式与设备功能不匹配而返回错误。相反，它们必须修改格式以匹配硬件可以提供的格式。修改后的格式应尽可能接近原始请求。

type v4l2_subdev_format¶

struct v4l2_subdev_format¶
__u32	`pad`	媒体控制器 API 报告的 Pad 编号。
__u32	`which`	要修改的格式，来自 enum v4l2_subdev_format_whence。
struct `v4l2_mbus_framefmt`	`format`	图像格式的定义，有关详细信息，请参见 `v4l2_mbus_framefmt`。
__u32	`stream`	流标识符。
__u32	`reserved`[7]	保留供将来扩展。应用程序和驱动程序必须将数组设置为零。

enum v4l2_subdev_format_whence¶
V4L2_SUBDEV_FORMAT_TRY	0	Try 格式，用于查询设备功能。
V4L2_SUBDEV_FORMAT_ACTIVE	1	活动格式，应用于硬件。

7.60.5. 返回值¶

成功时返回 0，错误时返回 -1，并适当地设置 errno 变量。泛型错误代码在泛型错误代码章节中进行了描述。

EBUSY: 由于 pad 当前正忙，无法更改格式。例如，这可能是由 pad 上的活动视频流引起的。在执行其他操作以首先解决问题之前，不得重试 ioctl。仅由 VIDIOC_SUBDEV_S_FMT 返回
EINVAL: struct v4l2_subdev_format pad 引用了不存在的 pad，或者 which 字段具有不支持的值。
EPERM: 已在只读子设备上调用了 VIDIOC_SUBDEV_S_FMT ioctl，并且 which 字段设置为 V4L2_SUBDEV_FORMAT_ACTIVE。