From: Hans Verkuil <hverkuil@xs4all.nl>
To: Tomasz Figa <tfiga@chromium.org>
Cc: "Linux Media Mailing List" <linux-media@vger.kernel.org>,
"Linux Kernel Mailing List" <linux-kernel@vger.kernel.org>,
"Mauro Carvalho Chehab" <mchehab@kernel.org>,
"Pawel Osciak" <posciak@chromium.org>,
"Alexandre Courbot" <acourbot@chromium.org>,
"Kamil Debski" <kamil@wypas.org>,
"Andrzej Hajda" <a.hajda@samsung.com>,
"Kyungmin Park" <kyungmin.park@samsung.com>,
"Jeongtae Park" <jtp.park@samsung.com>,
"Philipp Zabel" <p.zabel@pengutronix.de>,
"Tiffany Lin (林慧珊)" <tiffany.lin@mediatek.com>,
"Andrew-CT Chen (陳智迪)" <andrew-ct.chen@mediatek.com>,
"Stanimir Varbanov" <stanimir.varbanov@linaro.org>,
"Todor Tomov" <todor.tomov@linaro.org>,
"Nicolas Dufresne" <nicolas@ndufresne.ca>,
"Paul Kocialkowski" <paul.kocialkowski@bootlin.com>,
"Laurent Pinchart" <laurent.pinchart@ideasonboard.com>,
dave.stevenson@raspberrypi.org,
"Ezequiel Garcia" <ezequiel@collabora.com>,
"Maxime Jourdan" <maxi.jourdan@wanadoo.fr>
Subject: Re: [PATCH v3 2/2] media: docs-rst: Document memory-to-memory video encoder interface
Date: Fri, 5 Apr 2019 09:09:11 +0200 [thread overview]
Message-ID: <9c06c93d-a5f1-2998-a031-d483a6b51c13@xs4all.nl> (raw)
In-Reply-To: <CAAFQd5Dd9s-+XmA-KhokarCGUH6qCbdY3qcYq3oSfW7oRmMtMg@mail.gmail.com>
On 4/5/19 7:53 AM, Tomasz Figa wrote:
> On Tue, Jan 29, 2019 at 10:53 PM Hans Verkuil <hverkuil@xs4all.nl> wrote:
>>
>> Hi Tomasz,
>>
>> Some comments below. Nothing major, so I think a v4 should be ready to be
>> merged.
>>
>> On 1/24/19 11:04 AM, Tomasz Figa wrote:
>>> Due to complexity of the video encoding process, the V4L2 drivers of
>>> stateful encoder hardware require specific sequences of V4L2 API calls
>>> to be followed. These include capability enumeration, initialization,
>>> encoding, encode parameters change, drain and reset.
>>>
>>> Specifics of the above have been discussed during Media Workshops at
>>> LinuxCon Europe 2012 in Barcelona and then later Embedded Linux
>>> Conference Europe 2014 in Düsseldorf. The de facto Codec API that
>>> originated at those events was later implemented by the drivers we already
>>> have merged in mainline, such as s5p-mfc or coda.
>>>
>>> The only thing missing was the real specification included as a part of
>>> Linux Media documentation. Fix it now and document the encoder part of
>>> the Codec API.
>>>
>>> Signed-off-by: Tomasz Figa <tfiga@chromium.org>
>>> ---
>>> Documentation/media/uapi/v4l/dev-encoder.rst | 586 ++++++++++++++++++
>>> Documentation/media/uapi/v4l/dev-mem2mem.rst | 1 +
>>> Documentation/media/uapi/v4l/pixfmt-v4l2.rst | 5 +
>>> Documentation/media/uapi/v4l/v4l2.rst | 2 +
>>> .../media/uapi/v4l/vidioc-encoder-cmd.rst | 38 +-
>>> 5 files changed, 617 insertions(+), 15 deletions(-)
>>> create mode 100644 Documentation/media/uapi/v4l/dev-encoder.rst
>>>
>>> diff --git a/Documentation/media/uapi/v4l/dev-encoder.rst b/Documentation/media/uapi/v4l/dev-encoder.rst
>>> new file mode 100644
>>> index 000000000000..fb8b05a132ee
>>> --- /dev/null
>>> +++ b/Documentation/media/uapi/v4l/dev-encoder.rst
>>> @@ -0,0 +1,586 @@
<snip>
>>> +Initialization
>>> +==============
>>> +
>>> +1. Set the coded format on the ``CAPTURE`` queue via :c:func:`VIDIOC_S_FMT`
>>> +
>>> + * **Required fields:**
>>> +
>>> + ``type``
>>> + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``
>>> +
>>> + ``pixelformat``
>>> + the coded format to be produced
>>> +
>>> + ``sizeimage``
>>> + desired size of ``CAPTURE`` buffers; the encoder may adjust it to
>>> + match hardware requirements
>>> +
>>> + ``width``, ``height``
>>> + ignored (always zero)
>>> +
>>> + other fields
>>> + follow standard semantics
>>> +
>>> + * **Return fields:**
>>> +
>>> + ``sizeimage``
>>> + adjusted size of ``CAPTURE`` buffers
>>> +
>>> + .. important::
>>> +
>>> + Changing the ``CAPTURE`` format may change the currently set ``OUTPUT``
>>> + format. The encoder will derive a new ``OUTPUT`` format from the
>>> + ``CAPTURE`` format being set, including resolution, colorimetry
>>> + parameters, etc. If the client needs a specific ``OUTPUT`` format, it
>>> + must adjust it afterwards.
>>
>> Hmm, "including resolution": if width and height are set to 0, what should the
>> OUTPUT resolution be? Up to the driver? I think this should be clarified since
>> at a first reading of this paragraph it appears to be contradictory.
>>
>
> Indeed, it's hard to derive some sensible resolution from 0...
>
> The intention here is to prevent the application from making any
> assumptions about the OUTPUT format, if it changes the CAPTURE format.
> Then, it shouldn't actually matter what's the new OUTPUT format, since
> the application needs to set it anyway.
>
> Maybe let's just remove the mention of deriving and say something
> along these lines?
>
> "How the new ``OUTPUT`` format is determined is unspecified and the client must
> ensure it matches its needs afterwards."
I would replace "unspecified" with "driver specific" or possibly "up to the driver".
Regards,
Hans
next prev parent reply other threads:[~2019-04-05 7:16 UTC|newest]
Thread overview: 48+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-01-24 10:04 [PATCH v3 0/2] Document memory-to-memory video codec interfaces Tomasz Figa
2019-01-24 10:04 ` [PATCH v3 1/2] media: docs-rst: Document memory-to-memory video decoder interface Tomasz Figa
2019-01-29 13:11 ` Hans Verkuil
2019-01-31 10:45 ` Hans Verkuil
2019-01-31 12:30 ` Hans Verkuil
2019-01-31 12:38 ` Hans Verkuil
2019-01-31 12:44 ` Philipp Zabel
2019-01-31 13:19 ` Hans Verkuil
2019-02-07 8:51 ` Tomasz Figa
2019-04-05 10:59 ` Philipp Zabel
2019-04-05 11:21 ` Hans Verkuil
2019-04-09 10:28 ` Tomasz Figa
2019-04-09 16:57 ` Philipp Zabel
2019-04-10 9:29 ` Hans Verkuil
2019-01-24 10:04 ` [PATCH v3 2/2] media: docs-rst: Document memory-to-memory video encoder interface Tomasz Figa
2019-01-29 13:52 ` Hans Verkuil
2019-03-14 13:57 ` Hans Verkuil
2019-04-05 8:12 ` Tomasz Figa
2019-04-05 10:03 ` Hans Verkuil
2019-04-08 9:23 ` Tomasz Figa
2019-04-08 11:11 ` Hans Verkuil
2019-04-09 9:35 ` Tomasz Figa
2019-04-10 8:50 ` Hans Verkuil
2019-04-10 16:05 ` Nicolas Dufresne
2019-04-15 8:56 ` Tomasz Figa
2019-04-15 12:30 ` Nicolas Dufresne
2019-04-05 5:53 ` Tomasz Figa
2019-04-05 7:09 ` Hans Verkuil [this message]
2019-03-21 10:10 ` Hans Verkuil
2019-04-08 6:59 ` Tomasz Figa
2019-04-08 7:43 ` Hans Verkuil
2019-04-08 9:35 ` Tomasz Figa
2019-03-25 13:12 ` Hans Verkuil
2019-03-25 16:33 ` Hans Verkuil
2019-04-08 8:40 ` Tomasz Figa
2019-04-08 8:36 ` Tomasz Figa
2019-04-08 8:43 ` Hans Verkuil
2019-04-09 7:11 ` Tomasz Figa
2019-04-09 9:37 ` Hans Verkuil
2019-04-09 9:43 ` Tomasz Figa
2019-05-22 8:43 ` Tomasz Figa
2019-05-22 8:51 ` Hans Verkuil
2019-05-22 14:16 ` Michael Tretter
2019-04-30 17:34 ` Michael Tretter
2019-05-14 8:12 ` Tomasz Figa
2019-05-16 8:37 ` Michael Tretter
2019-05-16 8:48 ` Tomasz Figa
2019-01-24 10:38 ` [PATCH v3 0/2] Document memory-to-memory video codec interfaces Hans Verkuil
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=9c06c93d-a5f1-2998-a031-d483a6b51c13@xs4all.nl \
--to=hverkuil@xs4all.nl \
--cc=a.hajda@samsung.com \
--cc=acourbot@chromium.org \
--cc=andrew-ct.chen@mediatek.com \
--cc=dave.stevenson@raspberrypi.org \
--cc=ezequiel@collabora.com \
--cc=jtp.park@samsung.com \
--cc=kamil@wypas.org \
--cc=kyungmin.park@samsung.com \
--cc=laurent.pinchart@ideasonboard.com \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-media@vger.kernel.org \
--cc=maxi.jourdan@wanadoo.fr \
--cc=mchehab@kernel.org \
--cc=nicolas@ndufresne.ca \
--cc=p.zabel@pengutronix.de \
--cc=paul.kocialkowski@bootlin.com \
--cc=posciak@chromium.org \
--cc=stanimir.varbanov@linaro.org \
--cc=tfiga@chromium.org \
--cc=tiffany.lin@mediatek.com \
--cc=todor.tomov@linaro.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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).