On Tue, May 26, 2020 at 12:09:29PM +0200, Hans Verkuil wrote: > 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@xxxxxxxxx> > Acked-by: Tomasz Figa <tfiga@xxxxxxxxxxxx> > --- > .../userspace-api/media/v4l/vidioc-g-parm.rst | 51 ++++++++++++------- > 1 file changed, 32 insertions(+), 19 deletions(-) > > diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst b/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst > index 42e9f6ee7a59..af3c5863bb87 100644 > --- a/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst > +++ b/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst [snip] > @@ -113,14 +115,21 @@ union holding separate parameters for input and output devices. > * - struct :c:type:`v4l2_fract` > - ``timeperframe`` > - This is the desired period between successive frames captured by > - the driver, in seconds. The field is intended to skip frames on > - the driver side, saving I/O bandwidth. > + the driver, in seconds. > + * - :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 Spaces instead of tab. > + frame interval that is typically embedded in the encoded video stream. > > Applications store here the desired frame period, drivers return > - the actual frame period, which must be greater or equal to the > - nominal frame period determined by the current video standard > - (struct :c:type:`v4l2_standard` ``frameperiod`` > - field). Changing the video standard (also implicitly by switching > + the actual frame period. > + > + Changing the video standard (also implicitly by switching > the video input) may reset this parameter to the nominal frame > period. To reset manually applications can just set this field to > zero. > @@ -173,11 +182,15 @@ union holding separate parameters for input and output devices. > :ref:`write() <func-write>` mode (in streaming mode timestamps > can be used to throttle the output), saving I/O bandwidth. > > + For stateful encoders (see :ref:`encoder`) this represents the Spaces instead of tab. Michael > + 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 > - the actual frame period, which must be greater or equal to the > - nominal frame period determined by the current video standard > - (struct :c:type:`v4l2_standard` ``frameperiod`` > - field). Changing the video standard (also implicitly by switching > + the actual frame period. > + > + Changing the video standard (also implicitly by switching > the video output) may reset this parameter to the nominal frame > period. To reset manually applications can just set this field to > zero. > @@ -216,8 +229,8 @@ union holding separate parameters for input and output devices. > > * - ``V4L2_CAP_TIMEPERFRAME`` > - 0x1000 > - - The frame skipping/repeating controlled by the ``timeperframe`` > - field is supported. > + - The frame period can be modified by setting the ``timeperframe`` > + field. > > > > -- > 2.25.1 > >
