From: Hans Verkuil <hverkuil-cisco@xs4all.nl> To: linux-media@vger.kernel.org Cc: Nicolas Dufresne <nicolas@ndufresne.ca>, Tomasz Figa <tfiga@chromium.org>, Michael Tretter <m.tretter@pengutronix.de>, Hans Verkuil <hverkuil-cisco@xs4all.nl> Subject: [PATCHv3 2/5] vidioc-g-parm.rst: update the VIDIOC_G/S_PARM documentation Date: Tue, 26 May 2020 12:09:29 +0200 Message-ID: <20200526100932.2626420-3-hverkuil-cisco@xs4all.nl> (raw) In-Reply-To: <20200526100932.2626420-1-hverkuil-cisco@xs4all.nl> 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> --- .../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 @@ -42,12 +42,13 @@ Arguments Description =========== -The current video standard determines a nominal number of frames per -second. If less than this number of frames is to be captured or output, -applications can request frame skipping or duplicating on the driver -side. This is especially useful when using the :ref:`read() <func-read>` or -:ref:`write() <func-write>`, which are not augmented by timestamps or sequence -counters, and to avoid unnecessary data copying. +Applications can request a different frame interval. The capture or +output device will be reconfigured to support the requested frame +interval if possible. Optionally drivers may choose to skip or +repeat frames to achieve the requested frame interval. + +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 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. 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 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` - ``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 + 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 + 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
next prev parent reply other threads:[~2020-05-26 10:09 UTC|newest] Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top 2020-05-26 10:09 [PATCHv3 0/5] Stateful Encoding: final bits Hans Verkuil 2020-05-26 10:09 ` [PATCHv3 1/5] media: docs-rst: Document memory-to-memory video encoder interface Hans Verkuil 2020-05-29 9:57 ` Stanimir Varbanov 2020-05-29 10:17 ` Stanimir Varbanov 2020-05-29 12:21 ` Tomasz Figa 2020-06-05 7:19 ` Stanimir Varbanov 2020-06-05 21:24 ` Nicolas Dufresne 2020-06-06 7:58 ` Stanimir Varbanov 2020-06-07 0:27 ` Nicolas Dufresne 2020-06-10 12:28 ` Tomasz Figa 2020-06-10 13:08 ` Nicolas Dufresne 2020-06-10 13:55 ` Tomasz Figa 2020-06-10 13:58 ` Tomasz Figa 2020-06-23 10:36 ` Hans Verkuil 2020-06-23 11:47 ` Tomasz Figa 2020-06-23 10:47 ` Mauro Carvalho Chehab 2020-05-26 10:09 ` Hans Verkuil [this message] 2020-05-28 7:54 ` [PATCHv3 2/5] vidioc-g-parm.rst: update the VIDIOC_G/S_PARM documentation Michael Tretter 2020-05-26 10:09 ` [PATCHv3 3/5] dev-decoder.rst: small fixes Hans Verkuil 2020-05-26 10:09 ` [PATCHv3 4/5] videodev2.h: add V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL flag Hans Verkuil 2020-05-26 10:09 ` [PATCHv3 5/5] dev-encoder.rst: add reference to V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL Hans Verkuil 2020-05-28 7:58 ` [PATCHv3 0/5] Stateful Encoding: final bits Michael Tretter 2020-06-02 9:01 ` Tomasz Figa
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20200526100932.2626420-3-hverkuil-cisco@xs4all.nl \ --to=hverkuil-cisco@xs4all.nl \ --cc=linux-media@vger.kernel.org \ --cc=m.tretter@pengutronix.de \ --cc=nicolas@ndufresne.ca \ --cc=tfiga@chromium.org \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
Unnamed repository; edit this file 'description' to name the repository. This inbox may be cloned and mirrored by anyone: git clone --mirror http://archive.lwn.net:8080/linux-media/0 linux-media/git/0.git # If you have public-inbox 1.1+ installed, you may # initialize and index your mirror using the following commands: public-inbox-init -V2 linux-media linux-media/ http://archive.lwn.net:8080/linux-media \ linux-media@vger.kernel.org lwn-linux-media@archive.lwn.net public-inbox-index linux-media Example config snippet for mirrors. Newsgroup available over NNTP: nntp://archive.lwn.net/lwn.kernel.linux-media AGPL code for this site: git clone https://public-inbox.org/public-inbox.git