UbiquitousOS
/
OpenCloudOS-Kernel
mirror of https://gitee.com/OpenCloudOS/OpenCloudOS-Kernel.git
11
0
Fork 0
Code Issues Projects Releases Wiki Activity

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.

Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
Acked-by: Tomasz Figa <tfiga@chromium.org>
Reviewed-by: Michael Tretter <m.tretter@pengutronix.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
This commit is contained in:
Hans Verkuil 2020-05-20 11:42:23 +02:00 committed by Mauro Carvalho Chehab
parent 9ec656cf57
commit aa2e479fd0
1 changed files with 32 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
Documentation/userspace-api/media/v4l/vidioc-g-parm.rst
View File

@ -42,12 +42,13 @@ Arguments
Description Description
=========== ===========
The current video standard determines a nominal number of frames per Applications can request a different frame interval. The capture or
second. If less than this number of frames is to be captured or output, output device will be reconfigured to support the requested frame
applications can request frame skipping or duplicating on the driver interval if possible. Optionally drivers may choose to skip or
side. This is especially useful when using the :ref:`read() <func-read>` or repeat frames to achieve the requested frame interval.
:ref:`write() <func-write>`, which are not augmented by timestamps or sequence
counters, and to avoid unnecessary data copying. For stateful encoders (see :ref:`encoder`) this represents the
frame interval that is typically embedded in the encoded video stream.
Changing the frame interval shall never change the format. Changing the Changing the frame interval shall never change the format. Changing the
format, on the other hand, may change the frame interval. 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
section discussing the :ref:`read() <func-read>` function. section discussing the :ref:`read() <func-read>` function.
To get and set the streaming parameters applications call the To get and set the streaming parameters applications call the
:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and
:ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a
pointer to a struct :c:type:`v4l2_streamparm` which contains a pointer to a struct :c:type:`v4l2_streamparm` which contains a
union holding separate parameters for input and output devices. union holding separate parameters for input and output devices.
@ -113,14 +115,21 @@ union holding separate parameters for input and output devices.
* - struct :c:type:`v4l2_fract` * - struct :c:type:`v4l2_fract`
- ``timeperframe`` - ``timeperframe``
- This is the desired period between successive frames captured by - This is the desired period between successive frames captured by
the driver, in seconds. The field is intended to skip frames on the driver, in seconds.
the driver side, saving I/O bandwidth. * - :cspan:`2`
This will configure the speed at which the video source (e.g. a sensor)
generates video frames. If the speed is fixed, then the driver may
choose to skip or repeat frames in order to achieve the requested
frame rate.
For stateful encoders (see :ref:`encoder`) this represents the
frame interval that is typically embedded in the encoded video stream.
Applications store here the desired frame period, drivers return Applications store here the desired frame period, drivers return
the actual frame period, which must be greater or equal to the the actual frame period.
nominal frame period determined by the current video standard
(struct :c:type:`v4l2_standard` ``frameperiod`` Changing the video standard (also implicitly by switching
field). Changing the video standard (also implicitly by switching
the video input) may reset this parameter to the nominal frame the video input) may reset this parameter to the nominal frame
period. To reset manually applications can just set this field to period. To reset manually applications can just set this field to
zero. zero.
@ -173,11 +182,15 @@ union holding separate parameters for input and output devices.
:ref:`write() <func-write>` mode (in streaming mode timestamps :ref:`write() <func-write>` mode (in streaming mode timestamps
can be used to throttle the output), saving I/O bandwidth. can be used to throttle the output), saving I/O bandwidth.
For stateful encoders (see :ref:`encoder`) this represents the
frame interval that is typically embedded in the encoded video stream
and it provides a hint to the encoder of the speed at which raw
frames are queued up to the encoder.
Applications store here the desired frame period, drivers return Applications store here the desired frame period, drivers return
the actual frame period, which must be greater or equal to the the actual frame period.
nominal frame period determined by the current video standard
(struct :c:type:`v4l2_standard` ``frameperiod`` Changing the video standard (also implicitly by switching
field). Changing the video standard (also implicitly by switching
the video output) may reset this parameter to the nominal frame the video output) may reset this parameter to the nominal frame
period. To reset manually applications can just set this field to period. To reset manually applications can just set this field to
zero. zero.
@ -216,8 +229,8 @@ union holding separate parameters for input and output devices.
* - ``V4L2_CAP_TIMEPERFRAME`` * - ``V4L2_CAP_TIMEPERFRAME``
- 0x1000 - 0x1000
- The frame skipping/repeating controlled by the ``timeperframe`` - The frame period can be modified by setting the ``timeperframe``
field is supported. field.