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

Showing the changes to Documentation/userspace-api (1 of 1 file). Show all

Unified · Split

Documentation/userspace-api/media/v4l/vidioc-g-parm.rst+32−19
@@ -42,12 +42,13 @@ Arguments · 41 unmodified lines
4242 Description
4343 ===========
4444
45−The current video standard determines a nominal number of frames per
46−second. If less than this number of frames is to be captured or output,
47−applications can request frame skipping or duplicating on the driver
48−side. This is especially useful when using the :ref:`read() <func-read>` or
49−:ref:`write() <func-write>`, which are not augmented by timestamps or sequence
50−counters, and to avoid unnecessary data copying.
45+Applications can request a different frame interval. The capture or
46+output device will be reconfigured to support the requested frame
47+interval if possible. Optionally drivers may choose to skip or
48+repeat frames to achieve the requested frame interval.
49+
50+For stateful encoders (see :ref:`encoder`) this represents the
51+frame interval that is typically embedded in the encoded video stream.
5152
5253 Changing the frame interval shall never change the format. Changing the
5354 format, 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
5758 section discussing the :ref:`read() <func-read>` function.
5859
5960 To 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 a
61+:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and
62+:ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a
6163 pointer to a struct :c:type:`v4l2_streamparm` which contains a
6264 union holding separate parameters for input and output devices.
6365
@@ -113,14 +115,21 @@ union holding separate parameters for input and output devices. · 49 unmodified lines
113115 * - struct :c:type:`v4l2_fract`
114116 - ``timeperframe``
115117 - This is the desired period between successive frames captured by
116− the driver, in seconds. The field is intended to skip frames on
117− the driver side, saving I/O bandwidth.
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.
118128
119129 Applications store here the desired frame period, drivers return
120− the actual frame period, which must be greater or equal to the
121− nominal frame period determined by the current video standard
122− (struct :c:type:`v4l2_standard` ``frameperiod``
123− field). Changing the video standard (also implicitly by switching
130+ the actual frame period.
131+
132+ Changing the video standard (also implicitly by switching
124133 the video input) may reset this parameter to the nominal frame
125134 period. To reset manually applications can just set this field to
126135 zero.
@@ -173,11 +182,15 @@ union holding separate parameters for input and output devices. · 46 unmodified lines
173182 :ref:`write() <func-write>` mode (in streaming mode timestamps
174183 can be used to throttle the output), saving I/O bandwidth.
175184
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+
176190 Applications store here the desired frame period, drivers return
177− the actual frame period, which must be greater or equal to the
178− nominal frame period determined by the current video standard
179− (struct :c:type:`v4l2_standard` ``frameperiod``
180− field). Changing the video standard (also implicitly by switching
191+ the actual frame period.
192+
193+ Changing the video standard (also implicitly by switching
181194 the video output) may reset this parameter to the nominal frame
182195 period. To reset manually applications can just set this field to
183196 zero.
@@ -216,8 +229,8 @@ union holding separate parameters for input and output devices. · 32 unmodified lines
216229
217230 * - ``V4L2_CAP_TIMEPERFRAME``
218231 - 0x1000
219− - The frame skipping/repeating controlled by the ``timeperframe``
220− field is supported.
232+ - The frame period can be modified by setting the ``timeperframe``
233+ field.
221234
222235
223236

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