diff options
Diffstat (limited to 'Documentation/userspace-api/media/v4l/dev-decoder.rst')
| -rw-r--r-- | Documentation/userspace-api/media/v4l/dev-decoder.rst | 43 |
1 files changed, 34 insertions, 9 deletions
diff --git a/Documentation/userspace-api/media/v4l/dev-decoder.rst b/Documentation/userspace-api/media/v4l/dev-decoder.rst index 5b9b83feeceb..eb662ced0ab4 100644 --- a/Documentation/userspace-api/media/v4l/dev-decoder.rst +++ b/Documentation/userspace-api/media/v4l/dev-decoder.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 +.. c:namespace:: V4L .. _decoder: @@ -72,6 +73,12 @@ coded resolution coded width width for given coded resolution. +coding tree unit + processing unit of the HEVC codec (corresponds to macroblock units in + H.264, VP8, VP9), + can use block structures of up to 64×64 pixels. + Good at sub-partitioning the picture into variable sized structures. + decode order the order in which frames are decoded; may differ from display order if the coded format includes a feature of frame reordering; for decoders, @@ -104,7 +111,8 @@ keyframe macroblock a processing unit in image and video compression formats based on linear block transforms (e.g. H.264, VP8, VP9); codec-specific, but for most of - popular codecs the size is 16x16 samples (pixels). + popular codecs the size is 16x16 samples (pixels). The HEVC codec uses a + slightly more flexible processing unit called coding tree unit (CTU). OUTPUT the source buffer queue; for decoders, the queue of buffers containing @@ -270,7 +278,7 @@ Initialization other fields follow standard semantics. - * **Return fields:** + * **Returned fields:** ``sizeimage`` adjusted size of ``OUTPUT`` buffers. @@ -304,7 +312,7 @@ Initialization ``memory`` follows standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` the actual number of buffers allocated. @@ -332,7 +340,7 @@ Initialization ``format`` follows standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` adjusted to the number of allocated buffers. @@ -403,7 +411,7 @@ Capture Setup ``type`` a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. - * **Return fields:** + * **Returned fields:** ``width``, ``height`` frame buffer resolution for the decoded frames. @@ -436,7 +444,7 @@ Capture Setup ``target`` set to ``V4L2_SEL_TGT_COMPOSE``. - * **Return fields:** + * **Returned fields:** ``r.left``, ``r.top``, ``r.width``, ``r.height`` the visible rectangle; it must fit within the frame buffer resolution @@ -545,7 +553,7 @@ Capture Setup frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``; read-only on hardware without additional compose/scaling capabilities. - * **Return fields:** + * **Returned fields:** ``r.left``, ``r.top``, ``r.width``, ``r.height`` the visible rectangle; it must fit within the frame buffer resolution @@ -622,7 +630,7 @@ Capture Setup ``memory`` follows standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` actual number of buffers allocated. @@ -661,7 +669,7 @@ Capture Setup a format representing the maximum framebuffer resolution to be accommodated by newly allocated buffers. - * **Return fields:** + * **Returned fields:** ``count`` adjusted to the number of allocated buffers. @@ -752,6 +760,23 @@ available to dequeue. Specifically: buffers are out-of-order compared to the ``OUTPUT`` buffers): ``CAPTURE`` timestamps will not retain the order of ``OUTPUT`` timestamps. +.. note:: + + The backing memory of ``CAPTURE`` buffers that are used as reference frames + by the stream may be read by the hardware even after they are dequeued. + Consequently, the client should avoid writing into this memory while the + ``CAPTURE`` queue is streaming. Failure to observe this may result in + corruption of decoded frames. + + Similarly, when using a memory type other than ``V4L2_MEMORY_MMAP``, the + client should make sure that each ``CAPTURE`` buffer is always queued with + the same backing memory for as long as the ``CAPTURE`` queue is streaming. + The reason for this is that V4L2 buffer indices can be used by drivers to + identify frames. Thus, if the backing memory of a reference frame is + submitted under a different buffer ID, the driver may misidentify it and + decode a new frame into it while it is still in use, resulting in corruption + of the following frames. + During the decoding, the decoder may initiate one of the special sequences, as listed below. The sequences will result in the decoder returning all the ``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed |