History

media: vidioc-g-parm.rst: update the VIDIOC_G/S_PARM documentation

This documentation is very outdated. In particular, it is not obvious at all that this is used to change the framerate of sensors. Fix it, and include references to the stateful encoder API where this works slightly different.

Hans Verkuil committed 6 years ago

Commit aa2e4791 parent 9ec656c1 file · +32 −19Browse files

Unified · Split

Documentation/userspace-api/media/v4l/vidioc-g-parm.rst+32−19
@@ -42,12 +42,13 @@ Arguments · 41 unmodified lines
42Description42Description
43===========43===========
44 44
45The current video standard determines a nominal number of frames per45Applications can request a different frame interval. The capture or
46second. If less than this number of frames is to be captured or output,46output device will be reconfigured to support the requested frame
47applications can request frame skipping or duplicating on the driver47interval if possible. Optionally drivers may choose to skip or
48side. This is especially useful when using the :ref:`read() <func-read>` or48repeat frames to achieve the requested frame interval.
49:ref:`write() <func-write>`, which are not augmented by timestamps or sequence49
50counters, and to avoid unnecessary data copying.50For stateful encoders (see :ref:`encoder`) this represents the
51frame interval that is typically embedded in the encoded video stream.
51 52
52Changing the frame interval shall never change the format. Changing the53Changing the frame interval shall never change the format. Changing the
53format, on the other hand, may change the frame interval.54format, on the other hand, may change the frame interval.
@@ -57,7 +58,8 @@ internally by a driver in read/write mode. For implications see the · 3 unmodified lines
57section discussing the :ref:`read() <func-read>` function.58section discussing the :ref:`read() <func-read>` function.
58 59
59To get and set the streaming parameters applications call the60To get and set the streaming parameters applications call the
60:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a61:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and
62:ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a
61pointer to a struct :c:type:`v4l2_streamparm` which contains a63pointer to a struct :c:type:`v4l2_streamparm` which contains a
62union holding separate parameters for input and output devices.64union holding separate parameters for input and output devices.
63 65
@@ -113,14 +115,21 @@ union holding separate parameters for input and output devices. · 49 unmodified lines
113 * - struct :c:type:`v4l2_fract`115 * - struct :c:type:`v4l2_fract`
114 - ``timeperframe``116 - ``timeperframe``
115 - This is the desired period between successive frames captured by117 - This is the desired period between successive frames captured by
116 the driver, in seconds. The field is intended to skip frames on118 the driver, in seconds.
117 the driver side, saving I/O bandwidth.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.
118 128
119 Applications store here the desired frame period, drivers return129 Applications store here the desired frame period, drivers return
120 the actual frame period, which must be greater or equal to the130 the actual frame period.
121 nominal frame period determined by the current video standard131
122 (struct :c:type:`v4l2_standard` ``frameperiod``132 Changing the video standard (also implicitly by switching
123 field). Changing the video standard (also implicitly by switching
124 the video input) may reset this parameter to the nominal frame133 the video input) may reset this parameter to the nominal frame
125 period. To reset manually applications can just set this field to134 period. To reset manually applications can just set this field to
126 zero.135 zero.
@@ -173,11 +182,15 @@ union holding separate parameters for input and output devices. · 46 unmodified lines
173 :ref:`write() <func-write>` mode (in streaming mode timestamps182 :ref:`write() <func-write>` mode (in streaming mode timestamps
174 can be used to throttle the output), saving I/O bandwidth.183 can be used to throttle the output), saving I/O bandwidth.
175 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
176 Applications store here the desired frame period, drivers return190 Applications store here the desired frame period, drivers return
177 the actual frame period, which must be greater or equal to the191 the actual frame period.
178 nominal frame period determined by the current video standard192
179 (struct :c:type:`v4l2_standard` ``frameperiod``193 Changing the video standard (also implicitly by switching
180 field). Changing the video standard (also implicitly by switching
181 the video output) may reset this parameter to the nominal frame194 the video output) may reset this parameter to the nominal frame
182 period. To reset manually applications can just set this field to195 period. To reset manually applications can just set this field to
183 zero.196 zero.
@@ -216,8 +229,8 @@ union holding separate parameters for input and output devices. · 32 unmodified lines
216 229
217 * - ``V4L2_CAP_TIMEPERFRAME``230 * - ``V4L2_CAP_TIMEPERFRAME``
218 - 0x1000231 - 0x1000
219 - The frame skipping/repeating controlled by the ``timeperframe``232 - The frame period can be modified by setting the ``timeperframe``
220 field is supported.233 field.
221 234
222 235
223 236

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t