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_G_PARM:
11
12**********************************
13ioctl VIDIOC_G_PARM, VIDIOC_S_PARM
14**********************************
15
16Name
17====
18
19VIDIOC_G_PARM - VIDIOC_S_PARM - Get or set streaming parameters
20
21
22Synopsis
23========
24
25.. c:function:: int ioctl( int fd, VIDIOC_G_PARM, v4l2_streamparm *argp )
26    :name: VIDIOC_G_PARM
27
28.. c:function:: int ioctl( int fd, VIDIOC_S_PARM, v4l2_streamparm *argp )
29    :name: VIDIOC_S_PARM
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_streamparm`.
40
41
42Description
43===========
44
45Applications can request a different frame interval. The capture or
46output device will be reconfigured to support the requested frame
47interval if possible. Optionally drivers may choose to skip or
48repeat frames to achieve the requested frame interval.
49
50For stateful encoders (see :ref:`encoder`) this represents the
51frame interval that is typically embedded in the encoded video stream.
52
53Changing the frame interval shall never change the format. Changing the
54format, on the other hand, may change the frame interval.
55
56Further these ioctls can be used to determine the number of buffers used
57internally by a driver in read/write mode. For implications see the
58section discussing the :ref:`read() <func-read>` function.
59
60To get and set the streaming parameters applications call the
61:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and
62:ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a
63pointer to a struct :c:type:`v4l2_streamparm` which contains a
64union holding separate parameters for input and output devices.
65
66
67.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
68
69.. c:type:: v4l2_streamparm
70
71.. flat-table:: struct v4l2_streamparm
72    :header-rows:  0
73    :stub-columns: 0
74    :widths:       1 1 2
75
76    * - __u32
77      - ``type``
78      - The buffer (stream) type, same as struct
79	:c:type:`v4l2_format` ``type``, set by the
80	application. See :c:type:`v4l2_buf_type`.
81    * - union {
82      - ``parm``
83    * - struct :c:type:`v4l2_captureparm`
84      - ``capture``
85      - Parameters for capture devices, used when ``type`` is
86	``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
87	``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``.
88    * - struct :c:type:`v4l2_outputparm`
89      - ``output``
90      - Parameters for output devices, used when ``type`` is
91	``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``.
92    * - __u8
93      - ``raw_data``\ [200]
94      - A place holder for future extensions.
95    * - }
96      -
97
98
99
100.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
101
102.. c:type:: v4l2_captureparm
103
104.. flat-table:: struct v4l2_captureparm
105    :header-rows:  0
106    :stub-columns: 0
107    :widths:       1 1 2
108
109    * - __u32
110      - ``capability``
111      - See :ref:`parm-caps`.
112    * - __u32
113      - ``capturemode``
114      - Set by drivers and applications, see :ref:`parm-flags`.
115    * - struct :c:type:`v4l2_fract`
116      - ``timeperframe``
117      - This is the desired period between successive frames captured by
118	the driver, in seconds.
119    * - :cspan:`2`
120
121	This will configure the speed at which the video source (e.g. a sensor)
122	generates video frames. If the speed is fixed, then the driver may
123	choose to skip or repeat frames in order to achieve the requested
124	frame rate.
125
126	For stateful encoders (see :ref:`encoder`) this represents the
127	frame interval that is typically embedded in the encoded video stream.
128
129	Applications store here the desired frame period, drivers return
130	the actual frame period.
131
132	Changing the video standard (also implicitly by switching
133	the video input) may reset this parameter to the nominal frame
134	period. To reset manually applications can just set this field to
135	zero.
136
137	Drivers support this function only when they set the
138	``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
139    * - __u32
140      - ``extendedmode``
141      - Custom (driver specific) streaming parameters. When unused,
142	applications and drivers must set this field to zero. Applications
143	using this field should check the driver name and version, see
144	:ref:`querycap`.
145    * - __u32
146      - ``readbuffers``
147      - Applications set this field to the desired number of buffers used
148	internally by the driver in :ref:`read() <func-read>` mode.
149	Drivers return the actual number of buffers. When an application
150	requests zero buffers, drivers should just return the current
151	setting rather than the minimum or an error code. For details see
152	:ref:`rw`.
153    * - __u32
154      - ``reserved``\ [4]
155      - Reserved for future extensions. Drivers and applications must set
156	the array to zero.
157
158
159
160.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
161
162.. c:type:: v4l2_outputparm
163
164.. flat-table:: struct v4l2_outputparm
165    :header-rows:  0
166    :stub-columns: 0
167    :widths:       1 1 2
168
169    * - __u32
170      - ``capability``
171      - See :ref:`parm-caps`.
172    * - __u32
173      - ``outputmode``
174      - Set by drivers and applications, see :ref:`parm-flags`.
175    * - struct :c:type:`v4l2_fract`
176      - ``timeperframe``
177      - This is the desired period between successive frames output by the
178	driver, in seconds.
179    * - :cspan:`2`
180
181	The field is intended to repeat frames on the driver side in
182	:ref:`write() <func-write>` mode (in streaming mode timestamps
183	can be used to throttle the output), saving I/O bandwidth.
184
185	For stateful encoders (see :ref:`encoder`) this represents the
186	frame interval that is typically embedded in the encoded video stream
187	and it provides a hint to the encoder of the speed at which raw
188	frames are queued up to the encoder.
189
190	Applications store here the desired frame period, drivers return
191	the actual frame period.
192
193	Changing the video standard (also implicitly by switching
194	the video output) may reset this parameter to the nominal frame
195	period. To reset manually applications can just set this field to
196	zero.
197
198	Drivers support this function only when they set the
199	``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
200    * - __u32
201      - ``extendedmode``
202      - Custom (driver specific) streaming parameters. When unused,
203	applications and drivers must set this field to zero. Applications
204	using this field should check the driver name and version, see
205	:ref:`querycap`.
206    * - __u32
207      - ``writebuffers``
208      - Applications set this field to the desired number of buffers used
209	internally by the driver in :ref:`write() <func-write>` mode. Drivers
210	return the actual number of buffers. When an application requests
211	zero buffers, drivers should just return the current setting
212	rather than the minimum or an error code. For details see
213	:ref:`rw`.
214    * - __u32
215      - ``reserved``\ [4]
216      - Reserved for future extensions. Drivers and applications must set
217	the array to zero.
218
219
220
221.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
222
223.. _parm-caps:
224
225.. flat-table:: Streaming Parameters Capabilities
226    :header-rows:  0
227    :stub-columns: 0
228    :widths:       3 1 4
229
230    * - ``V4L2_CAP_TIMEPERFRAME``
231      - 0x1000
232      - The frame period can be modified by setting the ``timeperframe``
233	field.
234
235
236
237.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
238
239.. _parm-flags:
240
241.. flat-table:: Capture Parameters Flags
242    :header-rows:  0
243    :stub-columns: 0
244    :widths:       3 1 4
245
246    * - ``V4L2_MODE_HIGHQUALITY``
247      - 0x0001
248      - High quality imaging mode. High quality mode is intended for still
249	imaging applications. The idea is to get the best possible image
250	quality that the hardware can deliver. It is not defined how the
251	driver writer may achieve that; it will depend on the hardware and
252	the ingenuity of the driver writer. High quality mode is a
253	different mode from the regular motion video capture modes. In
254	high quality mode:
255
256	-  The driver may be able to capture higher resolutions than for
257	   motion capture.
258
259	-  The driver may support fewer pixel formats than motion capture
260	   (eg; true color).
261
262	-  The driver may capture and arithmetically combine multiple
263	   successive fields or frames to remove color edge artifacts and
264	   reduce the noise in the video data.
265
266	-  The driver may capture images in slices like a scanner in order
267	   to handle larger format images than would otherwise be
268	   possible.
269
270	-  An image capture operation may be significantly slower than
271	   motion capture.
272
273	-  Moving objects in the image might have excessive motion blur.
274
275	-  Capture might only work through the :ref:`read() <func-read>` call.
276
277
278Return Value
279============
280
281On success 0 is returned, on error -1 and the ``errno`` variable is set
282appropriately. The generic error codes are described at the
283:ref:`Generic Error Codes <gen-errors>` chapter.
284