1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3.. _VIDIOC_G_FMT:
4
5************************************************
6ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT
7************************************************
8
9Name
10====
11
12VIDIOC_G_FMT - VIDIOC_S_FMT - VIDIOC_TRY_FMT - Get or set the data format, try a format
13
14
15Synopsis
16========
17
18.. c:function:: int ioctl( int fd, VIDIOC_G_FMT, struct v4l2_format *argp )
19    :name: VIDIOC_G_FMT
20
21.. c:function:: int ioctl( int fd, VIDIOC_S_FMT, struct v4l2_format *argp )
22    :name: VIDIOC_S_FMT
23
24.. c:function:: int ioctl( int fd, VIDIOC_TRY_FMT, struct v4l2_format *argp )
25    :name: VIDIOC_TRY_FMT
26
27Arguments
28=========
29
30``fd``
31    File descriptor returned by :ref:`open() <func-open>`.
32
33``argp``
34    Pointer to struct :c:type:`v4l2_format`.
35
36
37Description
38===========
39
40These ioctls are used to negotiate the format of data (typically image
41format) exchanged between driver and application.
42
43To query the current parameters applications set the ``type`` field of a
44struct :c:type:`v4l2_format` to the respective buffer (stream)
45type. For example video capture devices use
46``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
47``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``. When the application calls the
48:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this structure the driver fills
49the respective member of the ``fmt`` union. In case of video capture
50devices that is either the struct
51:c:type:`v4l2_pix_format` ``pix`` or the struct
52:c:type:`v4l2_pix_format_mplane` ``pix_mp``
53member. When the requested buffer type is not supported drivers return
54an ``EINVAL`` error code.
55
56To change the current format parameters applications initialize the
57``type`` field and all fields of the respective ``fmt`` union member.
58For details see the documentation of the various devices types in
59:ref:`devices`. Good practice is to query the current parameters
60first, and to modify only those parameters not suitable for the
61application. When the application calls the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
62a pointer to a struct :c:type:`v4l2_format` structure the driver
63checks and adjusts the parameters against hardware abilities. Drivers
64should not return an error code unless the ``type`` field is invalid,
65this is a mechanism to fathom device capabilities and to approach
66parameters acceptable for both the application and driver. On success
67the driver may program the hardware, allocate resources and generally
68prepare for data exchange. Finally the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl returns
69the current format parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Very simple,
70inflexible devices may even ignore all input and always return the
71default parameters. However all V4L2 devices exchanging data with the
72application must implement the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
73ioctl. When the requested buffer type is not supported drivers return an
74EINVAL error code on a :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` attempt. When I/O is already in
75progress or the resource is not available for other reasons drivers
76return the ``EBUSY`` error code.
77
78The :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl is equivalent to :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` with one
79exception: it does not change driver state. It can also be called at any
80time, never returning ``EBUSY``. This function is provided to negotiate
81parameters, to learn about hardware limitations, without disabling I/O
82or possibly time consuming hardware preparations. Although strongly
83recommended drivers are not required to implement this ioctl.
84
85The format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical to what
86:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` returns for the same input or output.
87
88
89.. c:type:: v4l2_format
90
91.. tabularcolumns::  |p{1.2cm}|p{4.6cm}|p{3.0cm}|p{8.6cm}|
92
93.. flat-table:: struct v4l2_format
94    :header-rows:  0
95    :stub-columns: 0
96
97    * - __u32
98      - ``type``
99      - Type of the data stream, see :c:type:`v4l2_buf_type`.
100    * - union {
101      - ``fmt``
102    * - struct :c:type:`v4l2_pix_format`
103      - ``pix``
104      - Definition of an image format, see :ref:`pixfmt`, used by video
105	capture and output devices.
106    * - struct :c:type:`v4l2_pix_format_mplane`
107      - ``pix_mp``
108      - Definition of an image format, see :ref:`pixfmt`, used by video
109	capture and output devices that support the
110	:ref:`multi-planar version of the API <planar-apis>`.
111    * - struct :c:type:`v4l2_window`
112      - ``win``
113      - Definition of an overlaid image, see :ref:`overlay`, used by
114	video overlay devices.
115    * - struct :c:type:`v4l2_vbi_format`
116      - ``vbi``
117      - Raw VBI capture or output parameters. This is discussed in more
118	detail in :ref:`raw-vbi`. Used by raw VBI capture and output
119	devices.
120    * - struct :c:type:`v4l2_sliced_vbi_format`
121      - ``sliced``
122      - Sliced VBI capture or output parameters. See :ref:`sliced` for
123	details. Used by sliced VBI capture and output devices.
124    * - struct :c:type:`v4l2_sdr_format`
125      - ``sdr``
126      - Definition of a data format, see :ref:`pixfmt`, used by SDR
127	capture and output devices.
128    * - struct :c:type:`v4l2_meta_format`
129      - ``meta``
130      - Definition of a metadata format, see :ref:`meta-formats`, used by
131	metadata capture devices.
132    * - __u8
133      - ``raw_data``\ [200]
134      - Place holder for future extensions.
135    * - }
136      -
137
138
139Return Value
140============
141
142On success 0 is returned, on error -1 and the ``errno`` variable is set
143appropriately. The generic error codes are described at the
144:ref:`Generic Error Codes <gen-errors>` chapter.
145
146EINVAL
147    The struct :c:type:`v4l2_format` ``type`` field is
148    invalid or the requested buffer type not supported.
149
150EBUSY
151    The device is busy and cannot change the format. This could be
152    because or the device is streaming or buffers are allocated or
153    queued to the driver. Relevant for :ref:`VIDIOC_S_FMT
154    <VIDIOC_G_FMT>` only.
155