These ioctls are used to negotiate the format of data (typically image format) exchanged between driver and application.
To query the current parameters applications set the
type field of a struct
v4l2_format to the respective buffer (stream)
type. For example video capture devices use
V4L2_BUF_TYPE_VIDEO_CAPTURE. When the application
calls the VIDIOC_G_FMT ioctl with a pointer to
this structure the driver fills the respective member of the
fmt union. In case of video capture devices
that is the struct v4l2_pix_format pix member.
When the requested buffer type is not supported drivers return an
EINVAL error code.
To change the current format parameters applications
initialize the type field and all
fields of the respective fmt
union member. For details see the documentation of the various devices
types in Chapter 4. Good practice is to query the
current parameters first, and to
modify only those parameters not suitable for the application. When
the application calls the VIDIOC_S_FMT ioctl
with a pointer to a v4l2_format structure
the driver checks
and adjusts the parameters against hardware abilities. Drivers
should not return an error code unless the input is ambiguous, this is
a mechanism to fathom device capabilities and to approach parameters
acceptable for both the application and driver. On success the driver
may program the hardware, allocate resources and generally prepare for
data exchange.
Finally the VIDIOC_S_FMT ioctl returns the
current format parameters as VIDIOC_G_FMT does.
Very simple, inflexible devices may even ignore all input and always
return the default parameters. However all V4L2 devices exchanging
data with the application must implement the
VIDIOC_G_FMT and
VIDIOC_S_FMT ioctl. When the requested buffer
type is not supported drivers return an EINVAL error code on a
VIDIOC_S_FMT attempt. When I/O is already in
progress or the resource is not available for other reasons drivers
return the EBUSY error code.
The VIDIOC_TRY_FMT ioctl is equivalent
to VIDIOC_S_FMT with one exception: it does not
change driver state. It can also be called at any time, never
returning EBUSY. This function is provided to
negotiate parameters, to learn about hardware limitations, without
disabling I/O or possibly time consuming hardware preparations.
Although strongly recommended drivers are not required to implement
this ioctl.
Table 1. struct v4l2_format
| enum v4l2_buf_type | type | Type of the data stream, see Table 3-2. | |
| union | fmt | ||
| struct v4l2_pix_format | pix | Definition of an image format, see Chapter 2, used by video capture and output devices. | |
| struct v4l2_window | win | Definition of an overlaid image, see Section 4.2, used by video overlay devices. | |
| struct v4l2_vbi_format | vbi | Raw VBI capture or output parameters. This is discussed in more detail in Section 4.7. Used by raw VBI capture and output devices. | |
| struct v4l2_sliced_vbi_format | sliced | Sliced VBI capture or output parameters. See Section 4.8 for details. Used by sliced VBI capture and output devices. | |
| __u8 | raw_data[200] | Place holder for future extensions and custom
(driver defined) formats with type
V4L2_BUF_TYPE_PRIVATE and higher. |
On success 0 is returned, on error -1 and the errno variable is set appropriately:
The data format cannot be changed at this time, for example because I/O is already in progress.
The struct v4l2_format type
field is invalid, the requested buffer type not supported, or
VIDIOC_TRY_FMT was called and is not
supported with this buffer type.