1.. Permission is granted to copy, distribute and/or modify this
2.. document under the terms of the GNU Free Documentation License,
3.. Version 1.1 or any later version published by the Free Software
4.. Foundation, with no Invariant Sections, no Front-Cover Texts
5.. and no Back-Cover Texts. A copy of the license is included at
6.. Documentation/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _VIDIOC_SUBDEV_G_FMT:
11
12**********************************************
13ioctl VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT
14**********************************************
15
16Name
17====
18
19VIDIOC_SUBDEV_G_FMT - VIDIOC_SUBDEV_S_FMT - Get or set the data format on a subdev pad
20
21
22Synopsis
23========
24
25.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_FMT, struct v4l2_subdev_format *argp )
26    :name: VIDIOC_SUBDEV_G_FMT
27
28.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_FMT, struct v4l2_subdev_format *argp )
29    :name: VIDIOC_SUBDEV_S_FMT
30
31
32Arguments
33=========
34
35``fd``
36    File descriptor returned by :ref:`open() <func-open>`.
37
38``argp``
39    Pointer to struct :c:type:`v4l2_subdev_format`.
40
41
42Description
43===========
44
45These ioctls are used to negotiate the frame format at specific subdev
46pads in the image pipeline.
47
48To retrieve the current format applications set the ``pad`` field of a
49struct :c:type:`v4l2_subdev_format` to the desired
50pad number as reported by the media API and the ``which`` field to
51``V4L2_SUBDEV_FORMAT_ACTIVE``. When they call the
52``VIDIOC_SUBDEV_G_FMT`` ioctl with a pointer to this structure the
53driver fills the members of the ``format`` field.
54
55To change the current format applications set both the ``pad`` and
56``which`` fields and all members of the ``format`` field. When they call
57the ``VIDIOC_SUBDEV_S_FMT`` ioctl with a pointer to this structure the
58driver verifies the requested format, adjusts it based on the hardware
59capabilities and configures the device. Upon return the struct
60:c:type:`v4l2_subdev_format` contains the current
61format as would be returned by a ``VIDIOC_SUBDEV_G_FMT`` call.
62
63Applications can query the device capabilities by setting the ``which``
64to ``V4L2_SUBDEV_FORMAT_TRY``. When set, 'try' formats are not applied
65to the device by the driver, but are changed exactly as active formats
66and stored in the sub-device file handle. Two applications querying the
67same sub-device would thus not interact with each other.
68
69For instance, to try a format at the output pad of a sub-device,
70applications would first set the try format at the sub-device input with
71the ``VIDIOC_SUBDEV_S_FMT`` ioctl. They would then either retrieve the
72default format at the output pad with the ``VIDIOC_SUBDEV_G_FMT`` ioctl,
73or set the desired output pad format with the ``VIDIOC_SUBDEV_S_FMT``
74ioctl and check the returned value.
75
76Try formats do not depend on active formats, but can depend on the
77current links configuration or sub-device controls value. For instance,
78a low-pass noise filter might crop pixels at the frame boundaries,
79modifying its output frame size.
80
81If the subdev device node has been registered in read-only mode, calls to
82``VIDIOC_SUBDEV_S_FMT`` are only valid if the ``which`` field is set to
83``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
84variable is set to ``-EPERM``.
85
86Drivers must not return an error solely because the requested format
87doesn't match the device capabilities. They must instead modify the
88format to match what the hardware can provide. The modified format
89should be as close as possible to the original request.
90
91
92.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
93
94.. c:type:: v4l2_subdev_format
95
96.. flat-table:: struct v4l2_subdev_format
97    :header-rows:  0
98    :stub-columns: 0
99    :widths:       1 1 2
100
101    * - __u32
102      - ``pad``
103      - Pad number as reported by the media controller API.
104    * - __u32
105      - ``which``
106      - Format to modified, from enum
107	:ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
108    * - struct :c:type:`v4l2_mbus_framefmt`
109      - ``format``
110      - Definition of an image format, see :c:type:`v4l2_mbus_framefmt` for
111	details.
112    * - __u32
113      - ``reserved``\ [8]
114      - Reserved for future extensions. Applications and drivers must set
115	the array to zero.
116
117
118
119.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
120
121.. _v4l2-subdev-format-whence:
122
123.. flat-table:: enum v4l2_subdev_format_whence
124    :header-rows:  0
125    :stub-columns: 0
126    :widths:       3 1 4
127
128    * - V4L2_SUBDEV_FORMAT_TRY
129      - 0
130      - Try formats, used for querying device capabilities.
131    * - V4L2_SUBDEV_FORMAT_ACTIVE
132      - 1
133      - Active formats, applied to the hardware.
134
135
136Return Value
137============
138
139On success 0 is returned, on error -1 and the ``errno`` variable is set
140appropriately. The generic error codes are described at the
141:ref:`Generic Error Codes <gen-errors>` chapter.
142
143EBUSY
144    The format can't be changed because the pad is currently busy. This
145    can be caused, for instance, by an active video stream on the pad.
146    The ioctl must not be retried without performing another action to
147    fix the problem first. Only returned by ``VIDIOC_SUBDEV_S_FMT``
148
149EINVAL
150    The struct :c:type:`v4l2_subdev_format`
151    ``pad`` references a non-existing pad, or the ``which`` field
152    references a non-existing format.
153
154EPERM
155    The ``VIDIOC_SUBDEV_S_FMT`` ioctl has been called on a read-only subdevice
156    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
157
158============
159
160On success 0 is returned, on error -1 and the ``errno`` variable is set
161appropriately. The generic error codes are described at the
162:ref:`Generic Error Codes <gen-errors>` chapter.
163