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