Hi Tomasz, On 10/22/2018 05:48 PM, Tomasz Figa wrote: > Due to complexity of the video decoding process, the V4L2 drivers of > stateful decoder hardware require specific sequences of V4L2 API calls > to be followed. These include capability enumeration, initialization, > decoding, seek, pause, dynamic resolution change, drain and end of > stream. > > 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 decoder part of > the Codec API. > > Signed-off-by: Tomasz Figa <tfiga@xxxxxxxxxxxx> > --- > Documentation/media/uapi/v4l/dev-decoder.rst | 1082 +++++++++++++++++ > Documentation/media/uapi/v4l/devices.rst | 1 + > Documentation/media/uapi/v4l/pixfmt-v4l2.rst | 5 + > Documentation/media/uapi/v4l/v4l2.rst | 10 +- > .../media/uapi/v4l/vidioc-decoder-cmd.rst | 40 +- > Documentation/media/uapi/v4l/vidioc-g-fmt.rst | 14 + > 6 files changed, 1137 insertions(+), 15 deletions(-) > create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst > > diff --git a/Documentation/media/uapi/v4l/dev-decoder.rst b/Documentation/media/uapi/v4l/dev-decoder.rst > new file mode 100644 > index 000000000000..09c7a6621b8e > --- /dev/null > +++ b/Documentation/media/uapi/v4l/dev-decoder.rst <cut> > +Capture setup > +============= > + <cut> > + > +2. **Optional.** Acquire the visible resolution via > + :c:func:`VIDIOC_G_SELECTION`. > + > + * **Required fields:** > + > + ``type`` > + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE`` > + > + ``target`` > + set to ``V4L2_SEL_TGT_COMPOSE`` > + > + * **Return fields:** > + > + ``r.left``, ``r.top``, ``r.width``, ``r.height`` > + the visible rectangle; it must fit within the frame buffer resolution > + returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``. > + > + * The following selection targets are supported on ``CAPTURE``: > + > + ``V4L2_SEL_TGT_CROP_BOUNDS`` > + corresponds to the coded resolution of the stream > + > + ``V4L2_SEL_TGT_CROP_DEFAULT`` > + the rectangle covering the part of the ``CAPTURE`` buffer that > + contains meaningful picture data (visible area); width and height > + will be equal to the visible resolution of the stream > + > + ``V4L2_SEL_TGT_CROP`` > + the rectangle within the coded resolution to be output to > + ``CAPTURE``; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``; read-only on > + hardware without additional compose/scaling capabilities Hans should correct me if I'm wrong but V4L2_SEL_TGT_CROP_xxx are applicable over OUTPUT queue type? > + > + ``V4L2_SEL_TGT_COMPOSE_BOUNDS`` > + the maximum rectangle within a ``CAPTURE`` buffer, which the cropped > + frame can be output into; equal to ``V4L2_SEL_TGT_CROP`` if the > + hardware does not support compose/scaling > + > + ``V4L2_SEL_TGT_COMPOSE_DEFAULT`` > + equal to ``V4L2_SEL_TGT_CROP`` > + > + ``V4L2_SEL_TGT_COMPOSE`` > + the rectangle inside a ``CAPTURE`` buffer into which the cropped > + frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``; > + read-only on hardware without additional compose/scaling capabilities > + > + ``V4L2_SEL_TGT_COMPOSE_PADDED`` > + the rectangle inside a ``CAPTURE`` buffer which is overwritten by the > + hardware; equal to ``V4L2_SEL_TGT_COMPOSE`` if the hardware does not > + write padding pixels > + > + .. warning:: > + > + The values are guaranteed to be meaningful only after the decoder > + successfully parses the stream metadata. The client must not rely on the > + query before that happens. > + -- regards, Stan
