diff options
Diffstat (limited to 'Documentation/userspace-api/media/v4l')
257 files changed, 13137 insertions, 9267 deletions
diff --git a/Documentation/userspace-api/media/v4l/app-pri.rst b/Documentation/userspace-api/media/v4l/app-pri.rst index 5018ede2706f..626a42f2e138 100644 --- a/Documentation/userspace-api/media/v4l/app-pri.rst +++ b/Documentation/userspace-api/media/v4l/app-pri.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _app-pri: diff --git a/Documentation/userspace-api/media/v4l/async.rst b/Documentation/userspace-api/media/v4l/async.rst deleted file mode 100644 index 8bc4a726c95e..000000000000 --- a/Documentation/userspace-api/media/v4l/async.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _async: - -**************** -Asynchronous I/O -**************** - -This method is not defined yet. diff --git a/Documentation/userspace-api/media/v4l/audio.rst b/Documentation/userspace-api/media/v4l/audio.rst index d6bb85092e02..17f0b1c89908 100644 --- a/Documentation/userspace-api/media/v4l/audio.rst +++ b/Documentation/userspace-api/media/v4l/audio.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _audio: diff --git a/Documentation/userspace-api/media/v4l/bayer.svg b/Documentation/userspace-api/media/v4l/bayer.svg index 82e805c68c1f..c500a28f0817 100644 --- a/Documentation/userspace-api/media/v4l/bayer.svg +++ b/Documentation/userspace-api/media/v4l/bayer.svg @@ -1,31 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<!-- - This file is dual-licensed: you can use it either under the terms - of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this - dual licensing only applies to this file, and not this project as a - whole. - - a) This file is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License as - published by the Free Software Foundation version 2 of - the License. - - This file is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - Or, alternatively, - - b) Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later --> <svg id="svg2" width="164.15mm" height="46.771mm" fill-rule="evenodd" stroke-linejoin="round" stroke-width="28.222" preserveAspectRatio="xMidYMid" version="1.2" viewBox="0 0 16415.333 4677.1107" xml:space="preserve" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><metadata id="metadata652"><rdf:RDF><cc:Work rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/><dc:title/></cc:Work></rdf:RDF></metadata><g id="g186" class="com.sun.star.drawing.CustomShape" transform="translate(-3285.9 -3185.9)"><g id="id6"><rect id="rect189" class="BoundingBox" x="3299" y="3199" width="1303" height="1203" fill="none"/><path id="path191" d="m3950 4400h-650v-1200h1300v1200h-650z" fill="#00f"/><path id="path193" d="m3950 4400h-650v-1200h1300v1200h-650z" fill="none" stroke="#3465a4"/><text id="text195" class="TextShape"><tspan id="tspan197" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan199" class="TextPosition" x="3739" y="4021"><tspan id="tspan201" fill="#ffffff">B</tspan></tspan></tspan></text> </g></g><g id="g203" class="com.sun.star.drawing.CustomShape" transform="translate(-3285.9 -3185.9)"><g id="id7"><rect id="rect206" class="BoundingBox" x="4599" y="3199" width="1303" height="1203" fill="none"/><path id="path208" d="m5250 4400h-650v-1200h1300v1200h-650z" fill="#0c0"/><path id="path210" d="m5250 4400h-650v-1200h1300v1200h-650z" fill="none" stroke="#3465a4"/><text id="text212" class="TextShape"><tspan id="tspan214" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan216" class="TextPosition" x="5003" y="4021"><tspan id="tspan218" fill="#ffffff">G</tspan></tspan></tspan></text> diff --git a/Documentation/userspace-api/media/v4l/biblio.rst b/Documentation/userspace-api/media/v4l/biblio.rst index 3c9634173e82..35674eeae20d 100644 --- a/Documentation/userspace-api/media/v4l/biblio.rst +++ b/Documentation/userspace-api/media/v4l/biblio.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later ********** References @@ -58,7 +51,7 @@ ISO 13818-1 =========== -:title: ITU-T Rec. H.222.0 | ISO/IEC 13818-1 "Information technology — Generic coding of moving pictures and associated audio information: Systems" +:title: ITU-T Rec. H.222.0 | ISO/IEC 13818-1 "Information technology --- Generic coding of moving pictures and associated audio information: Systems" :author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch) @@ -68,7 +61,7 @@ ISO 13818-2 =========== -:title: ITU-T Rec. H.262 | ISO/IEC 13818-2 "Information technology — Generic coding of moving pictures and associated audio information: Video" +:title: ITU-T Rec. H.262 | ISO/IEC 13818-2 "Information technology --- Generic coding of moving pictures and associated audio information: Video" :author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch) @@ -157,7 +150,7 @@ ITU-T.81 ======== -:title: ITU-T Recommendation T.81 "Information Technology — Digital Compression and Coding of Continous-Tone Still Images — Requirements and Guidelines" +:title: ITU-T Recommendation T.81 "Information Technology --- Digital Compression and Coding of Continous-Tone Still Images --- Requirements and Guidelines" :author: International Telecommunication Union (http://www.itu.int) @@ -277,7 +270,17 @@ EBU Tech 3213 ============= -:title: E.B.U. Standard for Chromaticity Tolerances for Studio Monitors" +:title: E.B.U. Standard for Chromaticity Tolerances for Studio Monitors + +:author: European Broadcast Union (http://www.ebu.ch) + +.. _tech3321: + +EBU Tech 3321 +============= + + +:title: E.B.U. guidelines for Consumer Flat Panel Displays (FPDs) :author: European Broadcast Union (http://www.ebu.ch) @@ -307,7 +310,7 @@ ISO 12232:2006 ============== -:title: Photography — Digital still cameras — Determination of exposure index, ISO speed ratings, standard output sensitivity, and recommended exposure index +:title: Photography --- Digital still cameras --- Determination of exposure index, ISO speed ratings, standard output sensitivity, and recommended exposure index :author: International Organization for Standardization (http://www.iso.org) @@ -331,6 +334,17 @@ VESA DMT :author: Video Electronics Standards Association (http://www.vesa.org) +.. _vesaeddc: + +E-DDC +===== + + +:title: VESA Enhanced Display Data Channel (E-DDC) Standard +:subtitle: Version 1.3 + +:author: Video Electronics Standards Association (http://www.vesa.org) + .. _vesaedid: EDID @@ -414,3 +428,22 @@ VP8 :title: RFC 6386: "VP8 Data Format and Decoding Guide" :author: J. Bankoski et al. + +.. _vp9: + +VP9 +=== + + +:title: VP9 Bitstream & Decoding Process Specification + +:author: Adrian Grange (Google), Peter de Rivaz (Argon Design), Jonathan Hunt (Argon Design) + +.. _av1: + +AV1 +=== + +:title: AV1 Bitstream & Decoding Process Specification + +:author: Peter de Rivaz, Argon Design Ltd, Jack Haughton, Argon Design Ltd diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst index 951ae1ed485f..856874341882 100644 --- a/Documentation/userspace-api/media/v4l/buffer.rst +++ b/Documentation/userspace-api/media/v4l/buffer.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _buffer: @@ -23,8 +17,8 @@ argument to the :ref:`VIDIOC_QUERYBUF`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. In the multi-planar API, some plane-specific members of struct :c:type:`v4l2_buffer`, -such as pointers and sizes for each plane, are stored in struct -struct :c:type:`v4l2_plane` instead. In that case, struct +such as pointers and sizes for each plane, are stored in +struct :c:type:`v4l2_plane` instead. In that case, struct :c:type:`v4l2_buffer` contains an array of plane structures. Dequeued video buffers come with timestamps. The driver decides at which @@ -40,7 +34,6 @@ mem-to-mem devices is an exception to the rule: the timestamp source flags are copied from the OUTPUT video buffer to the CAPTURE video buffer. - Interactions between formats, controls and buffers ================================================== @@ -159,13 +152,12 @@ based on the queried sizes (for instance by allocating a set of buffers large enough for all the desired formats and controls, or by allocating separate set of appropriately sized buffers for each use case). - .. c:type:: v4l2_buffer struct v4l2_buffer ================== -.. tabularcolumns:: |p{2.8cm}|p{2.5cm}|p{1.6cm}|p{10.2cm}| +.. tabularcolumns:: |p{2.9cm}|p{2.4cm}|p{12.0cm}| .. cssclass:: longtable @@ -195,10 +187,8 @@ struct v4l2_buffer on the negotiated data format and may change with each buffer for compressed variable size data like JPEG images. Drivers must set this field when ``type`` refers to a capture stream, applications - when it refers to an output stream. If the application sets this - to 0 for an output stream, then ``bytesused`` will be set to the - size of the buffer (see the ``length`` field of this struct) by - the driver. For multiplanar formats this field is ignored and the + when it refers to an output stream. For multiplanar formats this field + is ignored and the ``planes`` pointer is used instead. * - __u32 - ``flags`` @@ -264,7 +254,7 @@ struct v4l2_buffer ``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the start of the device memory. The value is returned by the driver and apart of serving as parameter to the - :ref:`mmap() <func-mmap>` function not useful for applications. + :c:func:`mmap()` function not useful for applications. See :ref:`mmap` for details * - unsigned long - ``userptr`` @@ -317,13 +307,12 @@ struct v4l2_buffer given, then ``EINVAL`` will be returned. - .. c:type:: v4l2_plane struct v4l2_plane ================= -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{10.3cm}| .. cssclass:: longtable @@ -336,10 +325,7 @@ struct v4l2_plane - ``bytesused`` - The number of bytes occupied by data in the plane (its payload). Drivers must set this field when ``type`` refers to a capture - stream, applications when it refers to an output stream. If the - application sets this to 0 for an output stream, then - ``bytesused`` will be set to the size of the plane (see the - ``length`` field of this struct) by the driver. + stream, applications when it refers to an output stream. .. note:: @@ -357,7 +343,7 @@ struct v4l2_plane - ``mem_offset`` - When the memory type in the containing struct :c:type:`v4l2_buffer` is ``V4L2_MEMORY_MMAP``, this - is the value that should be passed to :ref:`mmap() <func-mmap>`, + is the value that should be passed to :c:func:`mmap()`, similar to the ``offset`` field in struct :c:type:`v4l2_buffer`. * - unsigned long @@ -391,7 +377,6 @@ struct v4l2_plane applications. - .. c:type:: v4l2_buf_type enum v4l2_buf_type @@ -399,7 +384,7 @@ enum v4l2_buf_type .. cssclass:: longtable -.. tabularcolumns:: |p{7.8cm}|p{0.6cm}|p{9.1cm}| +.. tabularcolumns:: |p{7.8cm}|p{0.6cm}|p{8.9cm}| .. flat-table:: :header-rows: 0 @@ -455,7 +440,6 @@ enum v4l2_buf_type - Buffer for metadata output, see :ref:`metadata`. - .. _buffer-flags: Buffer Flags @@ -463,16 +447,16 @@ Buffer Flags .. raw:: latex - \small + \footnotesize -.. tabularcolumns:: |p{7.0cm}|p{2.1cm}|p{8.4cm}| +.. tabularcolumns:: |p{6.5cm}|p{1.8cm}|p{9.0cm}| .. cssclass:: longtable .. flat-table:: :header-rows: 0 :stub-columns: 0 - :widths: 3 1 4 + :widths: 65 18 70 * .. _`V4L2-BUF-FLAG-MAPPED`: @@ -565,9 +549,9 @@ Buffer Flags - 0x00000400 - The buffer has been prepared for I/O and can be queued by the application. Drivers set or clear this flag when the - :ref:`VIDIOC_QUERYBUF`, + :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`, :ref:`VIDIOC_PREPARE_BUF <VIDIOC_QBUF>`, - :ref:`VIDIOC_QBUF` or + :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` or :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. * .. _`V4L2-BUF-FLAG-NO-CACHE-INVALIDATE`: @@ -577,7 +561,10 @@ Buffer Flags applications shall use this flag if the data captured in the buffer is not going to be touched by the CPU, instead the buffer will, probably, be passed on to a DMA-capable hardware unit for - further processing or output. + further processing or output. This flag is ignored unless the + queue is used for :ref:`memory mapping <mmap>` streaming I/O and + reports :ref:`V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS + <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability. * .. _`V4L2-BUF-FLAG-NO-CACHE-CLEAN`: - ``V4L2_BUF_FLAG_NO_CACHE_CLEAN`` @@ -585,12 +572,15 @@ Buffer Flags - Caches do not have to be cleaned for this buffer. Typically applications shall use this flag for output buffers if the data in this buffer has not been created by the CPU but by some - DMA-capable unit, in which case caches have not been used. + DMA-capable unit, in which case caches have not been used. This flag + is ignored unless the queue is used for :ref:`memory mapping <mmap>` + streaming I/O and reports :ref:`V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS + <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability. * .. _`V4L2-BUF-FLAG-M2M-HOLD-CAPTURE-BUF`: - ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF`` - 0x00000200 - - Only valid if ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` is + - Only valid if struct :c:type:`v4l2_requestbuffers` flag ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` is set. It is typically used with stateless decoders where multiple output buffers each decode to a slice of the decoded frame. Applications can set this flag when queueing the output buffer @@ -609,7 +599,7 @@ Buffer Flags :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Due to hardware limitations, the last buffer may be empty. In this case the driver will set the ``bytesused`` field to 0, regardless of - the format. Any Any subsequent call to the + the format. Any subsequent call to the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore, but return an ``EPIPE`` error code. * .. _`V4L2-BUF-FLAG-REQUEST-FD`: @@ -681,13 +671,10 @@ Buffer Flags \normalsize - -.. c:type:: v4l2_memory - enum v4l2_memory ================ -.. tabularcolumns:: |p{5.0cm}|p{0.8cm}|p{11.7cm}| +.. tabularcolumns:: |p{5.0cm}|p{0.8cm}|p{11.5cm}| .. flat-table:: :header-rows: 0 @@ -707,7 +694,9 @@ enum v4l2_memory - 4 - The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O. +.. raw:: latex + \normalsize Timecodes ========= @@ -717,13 +706,12 @@ The :c:type:`v4l2_buffer_timecode` structure is designed to hold a (struct :c:type:`timeval` timestamps are stored in the struct :c:type:`v4l2_buffer` ``timestamp`` field.) - .. c:type:: v4l2_timecode struct v4l2_timecode -------------------- -.. tabularcolumns:: |p{1.4cm}|p{2.8cm}|p{12.3cm}| +.. tabularcolumns:: |p{1.4cm}|p{2.8cm}|p{13.1cm}| .. flat-table:: :header-rows: 0 @@ -754,14 +742,11 @@ struct v4l2_timecode - The "user group" bits from the timecode. - .. _timecode-type: Timecode Types -------------- -.. tabularcolumns:: |p{5.6cm}|p{0.8cm}|p{11.1cm}| - .. flat-table:: :header-rows: 0 :stub-columns: 0 @@ -784,13 +769,12 @@ Timecode Types - - .. _timecode-flags: Timecode Flags -------------- -.. tabularcolumns:: |p{6.6cm}|p{1.4cm}|p{9.5cm}| +.. tabularcolumns:: |p{6.6cm}|p{1.4cm}|p{9.3cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/capture-example.rst b/Documentation/userspace-api/media/v4l/capture-example.rst index 6aa67c5aff8f..25891320b7ad 100644 --- a/Documentation/userspace-api/media/v4l/capture-example.rst +++ b/Documentation/userspace-api/media/v4l/capture-example.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _capture-example: diff --git a/Documentation/userspace-api/media/v4l/capture.c.rst b/Documentation/userspace-api/media/v4l/capture.c.rst index 30f7c816e858..349541b1dac0 100644 --- a/Documentation/userspace-api/media/v4l/capture.c.rst +++ b/Documentation/userspace-api/media/v4l/capture.c.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later file: media/v4l/capture.c ========================= @@ -63,7 +56,7 @@ file: media/v4l/capture.c static void errno_exit(const char *s) { - fprintf(stderr, "%s error %d, %s\\n", s, errno, strerror(errno)); + fprintf(stderr, "%s error %d, %s\n", s, errno, strerror(errno)); exit(EXIT_FAILURE); } @@ -208,7 +201,7 @@ file: media/v4l/capture.c } if (0 == r) { - fprintf(stderr, "select timeout\\n"); + fprintf(stderr, "select timeout\n"); exit(EXIT_FAILURE); } @@ -314,7 +307,7 @@ file: media/v4l/capture.c buffers = calloc(1, sizeof(*buffers)); if (!buffers) { - fprintf(stderr, "Out of memory\\n"); + fprintf(stderr, "Out of memory\n"); exit(EXIT_FAILURE); } @@ -322,7 +315,7 @@ file: media/v4l/capture.c buffers[0].start = malloc(buffer_size); if (!buffers[0].start) { - fprintf(stderr, "Out of memory\\n"); + fprintf(stderr, "Out of memory\n"); exit(EXIT_FAILURE); } } @@ -340,7 +333,7 @@ file: media/v4l/capture.c if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) { if (EINVAL == errno) { fprintf(stderr, "%s does not support " - "memory mappingn", dev_name); + "memory mapping\n", dev_name); exit(EXIT_FAILURE); } else { errno_exit("VIDIOC_REQBUFS"); @@ -348,7 +341,7 @@ file: media/v4l/capture.c } if (req.count < 2) { - fprintf(stderr, "Insufficient buffer memory on %s\\n", + fprintf(stderr, "Insufficient buffer memory on %s\n", dev_name); exit(EXIT_FAILURE); } @@ -356,7 +349,7 @@ file: media/v4l/capture.c buffers = calloc(req.count, sizeof(*buffers)); if (!buffers) { - fprintf(stderr, "Out of memory\\n"); + fprintf(stderr, "Out of memory\n"); exit(EXIT_FAILURE); } @@ -398,7 +391,7 @@ file: media/v4l/capture.c if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) { if (EINVAL == errno) { fprintf(stderr, "%s does not support " - "user pointer i/on", dev_name); + "user pointer i/o\n", dev_name); exit(EXIT_FAILURE); } else { errno_exit("VIDIOC_REQBUFS"); @@ -408,7 +401,7 @@ file: media/v4l/capture.c buffers = calloc(4, sizeof(*buffers)); if (!buffers) { - fprintf(stderr, "Out of memory\\n"); + fprintf(stderr, "Out of memory\n"); exit(EXIT_FAILURE); } @@ -417,7 +410,7 @@ file: media/v4l/capture.c buffers[n_buffers].start = malloc(buffer_size); if (!buffers[n_buffers].start) { - fprintf(stderr, "Out of memory\\n"); + fprintf(stderr, "Out of memory\n"); exit(EXIT_FAILURE); } } @@ -433,7 +426,7 @@ file: media/v4l/capture.c if (-1 == xioctl(fd, VIDIOC_QUERYCAP, &cap)) { if (EINVAL == errno) { - fprintf(stderr, "%s is no V4L2 device\\n", + fprintf(stderr, "%s is no V4L2 device\n", dev_name); exit(EXIT_FAILURE); } else { @@ -442,7 +435,7 @@ file: media/v4l/capture.c } if (!(cap.capabilities & V4L2_CAP_VIDEO_CAPTURE)) { - fprintf(stderr, "%s is no video capture device\\n", + fprintf(stderr, "%s is no video capture device\n", dev_name); exit(EXIT_FAILURE); } @@ -450,7 +443,7 @@ file: media/v4l/capture.c switch (io) { case IO_METHOD_READ: if (!(cap.capabilities & V4L2_CAP_READWRITE)) { - fprintf(stderr, "%s does not support read i/o\\n", + fprintf(stderr, "%s does not support read i/o\n", dev_name); exit(EXIT_FAILURE); } @@ -459,7 +452,7 @@ file: media/v4l/capture.c case IO_METHOD_MMAP: case IO_METHOD_USERPTR: if (!(cap.capabilities & V4L2_CAP_STREAMING)) { - fprintf(stderr, "%s does not support streaming i/o\\n", + fprintf(stderr, "%s does not support streaming i/o\n", dev_name); exit(EXIT_FAILURE); } @@ -548,20 +541,20 @@ file: media/v4l/capture.c struct stat st; if (-1 == stat(dev_name, &st)) { - fprintf(stderr, "Cannot identify '%s': %d, %s\\n", + fprintf(stderr, "Cannot identify '%s': %d, %s\n", dev_name, errno, strerror(errno)); exit(EXIT_FAILURE); } if (!S_ISCHR(st.st_mode)) { - fprintf(stderr, "%s is no devicen", dev_name); + fprintf(stderr, "%s is no device\n", dev_name); exit(EXIT_FAILURE); } fd = open(dev_name, O_RDWR /* required */ | O_NONBLOCK, 0); if (-1 == fd) { - fprintf(stderr, "Cannot open '%s': %d, %s\\n", + fprintf(stderr, "Cannot open '%s': %d, %s\n", dev_name, errno, strerror(errno)); exit(EXIT_FAILURE); } @@ -570,17 +563,17 @@ file: media/v4l/capture.c static void usage(FILE *fp, int argc, char **argv) { fprintf(fp, - "Usage: %s [options]\\n\\n" - "Version 1.3\\n" - "Options:\\n" - "-d | --device name Video device name [%s]n" - "-h | --help Print this messagen" - "-m | --mmap Use memory mapped buffers [default]n" - "-r | --read Use read() callsn" - "-u | --userp Use application allocated buffersn" - "-o | --output Outputs stream to stdoutn" - "-f | --format Force format to 640x480 YUYVn" - "-c | --count Number of frames to grab [%i]n" + "Usage: %s [options]\n\n" + "Version 1.3\n" + "Options:\n" + "-d | --device name Video device name [%s]\n" + "-h | --help Print this message\n" + "-m | --mmap Use memory mapped buffers [default]\n" + "-r | --read Use read() calls\n" + "-u | --userp Use application allocated buffers\n" + "-o | --output Outputs stream to stdout\n" + "-f | --format Force format to 640x480 YUYV\n" + "-c | --count Number of frames to grab [%i]\n" "", argv[0], dev_name, frame_count); } @@ -666,6 +659,6 @@ file: media/v4l/capture.c stop_capturing(); uninit_device(); close_device(); - fprintf(stderr, "\\n"); + fprintf(stderr, "\n"); return 0; } diff --git a/Documentation/userspace-api/media/v4l/colorspaces-defs.rst b/Documentation/userspace-api/media/v4l/colorspaces-defs.rst index 01404e1f609a..fe9f8aa8ab9d 100644 --- a/Documentation/userspace-api/media/v4l/colorspaces-defs.rst +++ b/Documentation/userspace-api/media/v4l/colorspaces-defs.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later **************************** Defining Colorspaces in V4L2 @@ -36,8 +29,7 @@ whole range, 0-255, dividing the angular value by 1.41. The enum :c:type:`v4l2_hsv_encoding` specifies which encoding is used. .. note:: The default R'G'B' quantization is full range for all - colorspaces except for BT.2020 which uses limited range R'G'B' - quantization. + colorspaces. HSV formats are always full range. .. tabularcolumns:: |p{6.7cm}|p{10.8cm}| @@ -169,8 +161,8 @@ whole range, 0-255, dividing the angular value by 1.41. The enum - Details * - ``V4L2_QUANTIZATION_DEFAULT`` - Use the default quantization encoding as defined by the - colorspace. This is always full range for R'G'B' (except for the - BT.2020 colorspace) and HSV. It is usually limited range for Y'CbCr. + colorspace. This is always full range for R'G'B' and HSV. + It is usually limited range for Y'CbCr. * - ``V4L2_QUANTIZATION_FULL_RANGE`` - Use the full range quantization encoding. I.e. the range [0…1] is mapped to [0…255] (with possible clipping to [1…254] to avoid the @@ -180,4 +172,4 @@ whole range, 0-255, dividing the angular value by 1.41. The enum * - ``V4L2_QUANTIZATION_LIM_RANGE`` - Use the limited range quantization encoding. I.e. the range [0…1] is mapped to [16…235]. Cb and Cr are mapped from [-0.5…0.5] to - [16…240]. + [16…240]. Limited Range cannot be used with HSV. diff --git a/Documentation/userspace-api/media/v4l/colorspaces-details.rst b/Documentation/userspace-api/media/v4l/colorspaces-details.rst index 79ed6f4f76eb..26a4ace42ca5 100644 --- a/Documentation/userspace-api/media/v4l/colorspaces-details.rst +++ b/Documentation/userspace-api/media/v4l/colorspaces-details.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later ******************************** Detailed Colorspace Descriptions @@ -24,10 +17,6 @@ PAL and by SDTV in general. The default transfer function is range. The chromaticities of the primary colors and the white reference are: - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: SMPTE 170M Chromaticities :header-rows: 1 :stub-columns: 0 @@ -105,10 +94,6 @@ default Y'CbCr encoding is ``V4L2_YCBCR_ENC_709``. The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and the white reference are: - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: Rec. 709 Chromaticities :header-rows: 1 :stub-columns: 0 @@ -232,10 +217,6 @@ would break how applications interpret the quantization range. The chromaticities of the primary colors and the white reference are: - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: sRGB Chromaticities :header-rows: 1 :stub-columns: 0 @@ -315,9 +296,6 @@ would break how applications interpret the quantization range. The chromaticities of the primary colors and the white reference are: - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: opRGB Chromaticities :header-rows: 1 :stub-columns: 0 @@ -377,13 +355,8 @@ Colorspace BT.2020 (V4L2_COLORSPACE_BT2020) The :ref:`itu2020` standard defines the colorspace used by Ultra-high definition television (UHDTV). The default transfer function is ``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is -``V4L2_YCBCR_ENC_BT2020``. The default R'G'B' quantization is limited -range (!), and so is the default Y'CbCr quantization. The chromaticities -of the primary colors and the white reference are: - - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +``V4L2_YCBCR_ENC_BT2020``. The default Y'CbCr quantization is limited range. +The chromaticities of the primary colors and the white reference are: .. flat-table:: BT.2020 Chromaticities :header-rows: 1 @@ -486,9 +459,6 @@ is ``V4L2_XFER_FUNC_DCI_P3``. The default Y'CbCr encoding is The chromaticities of the primary colors and the white reference are: - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: DCI-P3 Chromaticities :header-rows: 1 :stub-columns: 0 @@ -540,9 +510,6 @@ quantization is limited range. The chromaticities of the primary colors and the white reference are: - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: SMPTE 240M Chromaticities :header-rows: 1 :stub-columns: 0 @@ -611,9 +578,6 @@ limited range. The chromaticities of the primary colors and the white reference are: - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: NTSC 1953 Chromaticities :header-rows: 1 :stub-columns: 0 @@ -682,17 +646,15 @@ Colorspace EBU Tech. 3213 (V4L2_COLORSPACE_470_SYSTEM_BG) ========================================================= The :ref:`tech3213` standard defines the colorspace used by PAL/SECAM -in 1975. In practice this colorspace is obsolete and SMPTE 170M should -be used instead. The default transfer function is +in 1975. Note that this colorspace is not supported by the HDMI interface. +Instead :ref:`tech3321` recommends that Rec. 709 is used instead for HDMI. +The default transfer function is ``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is ``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and the white reference are: - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: EBU Tech. 3213 Chromaticities :header-rows: 1 :stub-columns: 0 @@ -767,8 +729,8 @@ scaled to [-128…128] and then clipped to [-128…127]. information. So if something other than sRGB is used, then the driver will have to set that information explicitly. Effectively ``V4L2_COLORSPACE_JPEG`` can be considered to be an abbreviation for - ``V4L2_COLORSPACE_SRGB``, ``V4L2_YCBCR_ENC_601`` and - ``V4L2_QUANTIZATION_FULL_RANGE``. + ``V4L2_COLORSPACE_SRGB``, ``V4L2_XFER_FUNC_SRGB``, ``V4L2_YCBCR_ENC_601`` + and ``V4L2_QUANTIZATION_FULL_RANGE``. *************************************** Detailed Transfer Function Descriptions diff --git a/Documentation/userspace-api/media/v4l/colorspaces.rst b/Documentation/userspace-api/media/v4l/colorspaces.rst index 0846df9066c5..2aa0dda4fd01 100644 --- a/Documentation/userspace-api/media/v4l/colorspaces.rst +++ b/Documentation/userspace-api/media/v4l/colorspaces.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _colorspaces: diff --git a/Documentation/userspace-api/media/v4l/common-defs.rst b/Documentation/userspace-api/media/v4l/common-defs.rst index 370a1e364a51..6ae42ac7ddb7 100644 --- a/Documentation/userspace-api/media/v4l/common-defs.rst +++ b/Documentation/userspace-api/media/v4l/common-defs.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _common-defs: diff --git a/Documentation/userspace-api/media/v4l/common.rst b/Documentation/userspace-api/media/v4l/common.rst index 7d81c58a13cd..ea0435182e44 100644 --- a/Documentation/userspace-api/media/v4l/common.rst +++ b/Documentation/userspace-api/media/v4l/common.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _common: @@ -51,12 +44,14 @@ applicable to all devices. ext-ctrls-image-source ext-ctrls-image-process ext-ctrls-codec + ext-ctrls-codec-stateless ext-ctrls-jpeg ext-ctrls-dv ext-ctrls-rf-tuner ext-ctrls-fm-tx ext-ctrls-fm-rx ext-ctrls-detect + ext-ctrls-colorimetry fourcc format planar-apis diff --git a/Documentation/userspace-api/media/v4l/compat.rst b/Documentation/userspace-api/media/v4l/compat.rst index 055286b86e9b..b63b8392dec6 100644 --- a/Documentation/userspace-api/media/v4l/compat.rst +++ b/Documentation/userspace-api/media/v4l/compat.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _compat: diff --git a/Documentation/userspace-api/media/v4l/constraints.svg b/Documentation/userspace-api/media/v4l/constraints.svg index 1dfe51a9839d..ac5f82bc6d1a 100644 --- a/Documentation/userspace-api/media/v4l/constraints.svg +++ b/Documentation/userspace-api/media/v4l/constraints.svg @@ -1,31 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<!-- - This file is dual-licensed: you can use it either under the terms - of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this - dual licensing only applies to this file, and not this project as a - whole. - - a) This file is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License as - published by the Free Software Foundation version 2 of - the License. - - This file is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - Or, alternatively, - - b) Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later --> <svg id="svg2" width="249.01mm" height="143.01mm" fill-rule="evenodd" stroke-linejoin="round" stroke-width="28.222" preserveAspectRatio="xMidYMid" version="1.2" viewBox="0 0 24900.998 14300.999" xml:space="preserve" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><metadata id="metadata325"><rdf:RDF><cc:Work rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/><dc:title/></cc:Work></rdf:RDF></metadata><defs id="defs4" class="ClipPathGroup"><marker id="marker6261" overflow="visible" orient="auto"><path id="path6263" transform="matrix(-.4 0 0 -.4 -4 0)" d="m0 0 5-5-17.5 5 17.5 5-5-5z" fill="#f00" fill-rule="evenodd" stroke="#f00" stroke-width="1pt"/></marker><marker id="marker6125" overflow="visible" orient="auto"><path id="path6127" transform="matrix(-.4 0 0 -.4 -4 0)" d="m0 0 5-5-17.5 5 17.5 5-5-5z" fill="#f00" fill-rule="evenodd" stroke="#f00" stroke-width="1pt"/></marker><marker id="marker6001" overflow="visible" orient="auto"><path id="path6003" transform="matrix(-.4 0 0 -.4 -4 0)" d="m0 0 5-5-17.5 5 17.5 5-5-5z" fill="#f00" fill-rule="evenodd" stroke="#f00" stroke-width="1pt"/></marker><marker id="marker5693" overflow="visible" orient="auto"><path id="path5695" transform="matrix(-.4 0 0 -.4 -4 0)" d="m0 0 5-5-17.5 5 17.5 5-5-5z" fill="#f00" fill-rule="evenodd" stroke="#f00" stroke-width="1pt"/></marker><marker id="marker5575" overflow="visible" orient="auto"><path id="path5577" transform="matrix(-.4 0 0 -.4 -4 0)" d="m0 0 5-5-17.5 5 17.5 5-5-5z" fill="#000080" fill-rule="evenodd" stroke="#000080" stroke-width="1pt"/></marker><marker id="marker5469" overflow="visible" orient="auto"><path id="path5471" transform="matrix(-.4 0 0 -.4 -4 0)" d="m0 0 5-5-17.5 5 17.5 5-5-5z" fill="#000080" fill-rule="evenodd" stroke="#000080" stroke-width="1pt"/></marker><marker id="marker5259" overflow="visible" orient="auto"><path id="path5261" transform="matrix(-.4 0 0 -.4 -4 0)" d="m0 0 5-5-17.5 5 17.5 5-5-5z" fill="#000080" fill-rule="evenodd" stroke="#000080" stroke-width="1pt"/></marker><marker id="Arrow2Mend" overflow="visible" orient="auto"><path id="path4241" transform="scale(-.6)" d="m8.7186 4.0337-10.926-4.0177 10.926-4.0177c-1.7455 2.3721-1.7354 5.6175-6e-7 8.0354z" fill="#000080" fill-rule="evenodd" stroke="#000080" stroke-linejoin="round" stroke-width=".625"/></marker></defs><g id="g204" class="com.sun.star.drawing.CustomShape" transform="translate(-1350,-3250)"><g id="id6"><rect id="rect207" class="BoundingBox" x="1350" y="3250" width="24901" height="14301" diff --git a/Documentation/userspace-api/media/v4l/control.rst b/Documentation/userspace-api/media/v4l/control.rst index 3e991c1f7a12..9253cc946f02 100644 --- a/Documentation/userspace-api/media/v4l/control.rst +++ b/Documentation/userspace-api/media/v4l/control.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _control: @@ -150,9 +143,13 @@ Control IDs recognise the difference between digital and analogue gain use controls ``V4L2_CID_DIGITAL_GAIN`` and ``V4L2_CID_ANALOGUE_GAIN``. +.. _v4l2-cid-hflip: + ``V4L2_CID_HFLIP`` ``(boolean)`` Mirror the picture horizontally. +.. _v4l2-cid-vflip: + ``V4L2_CID_VFLIP`` ``(boolean)`` Mirror the picture vertically. @@ -161,10 +158,13 @@ Control IDs ``V4L2_CID_POWER_LINE_FREQUENCY`` ``(enum)`` Enables a power line frequency filter to avoid flicker. Possible values for ``enum v4l2_power_line_frequency`` are: - ``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` (0), - ``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` (1), - ``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` (2) and - ``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` (3). + + ========================================== == + ``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` 0 + ``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` 1 + ``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` 2 + ``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` 3 + ========================================== == ``V4L2_CID_HUE_AUTO`` ``(boolean)`` Enables automatic hue control by the device. The effect of setting @@ -204,7 +204,7 @@ Control IDs -.. tabularcolumns:: |p{5.5cm}|p{12cm}| +.. tabularcolumns:: |p{5.7cm}|p{11.8cm}| .. flat-table:: :header-rows: 0 @@ -246,8 +246,17 @@ Control IDs * - ``V4L2_COLORFX_SET_CBCR`` - The Cb and Cr chroma components are replaced by fixed coefficients determined by ``V4L2_CID_COLORFX_CBCR`` control. + * - ``V4L2_COLORFX_SET_RGB`` + - The RGB components are replaced by the fixed RGB components determined + by ``V4L2_CID_COLORFX_RGB`` control. +``V4L2_CID_COLORFX_RGB`` ``(integer)`` + Determines the Red, Green, and Blue coefficients for + ``V4L2_COLORFX_SET_RGB`` color effect. + Bits [7:0] of the supplied 32 bit value are interpreted as Blue component, + bits [15:8] as Green component, bits [23:16] as Red component, and + bits [31:24] must be zero. ``V4L2_CID_COLORFX_CBCR`` ``(integer)`` Determines the Cb and Cr coefficients for ``V4L2_COLORFX_SET_CBCR`` @@ -281,13 +290,15 @@ Control IDs This is a read-only control that can be read by the application and used as a hint to determine the number of CAPTURE buffers to pass to REQBUFS. The value is the minimum number of CAPTURE buffers that is - necessary for hardware to work. + necessary for hardware to work. This control is required for stateful + decoders. ``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT`` ``(integer)`` This is a read-only control that can be read by the application and used as a hint to determine the number of OUTPUT buffers to pass to REQBUFS. The value is the minimum number of OUTPUT buffers that is - necessary for hardware to work. + necessary for hardware to work. This control is required for stateful + encoders. .. _v4l2-alpha-component: @@ -456,10 +467,10 @@ Example: Changing controls perror("VIDIOC_QUERYCTRL"); exit(EXIT_FAILURE); } else { - printf("V4L2_CID_BRIGHTNESS is not supportedn"); + printf("V4L2_CID_BRIGHTNESS is not supported\n"); } } else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) { - printf("V4L2_CID_BRIGHTNESS is not supportedn"); + printf("V4L2_CID_BRIGHTNESS is not supported\n"); } else { memset(&control, 0, sizeof (control)); control.id = V4L2_CID_BRIGHTNESS; diff --git a/Documentation/userspace-api/media/v4l/crop.rst b/Documentation/userspace-api/media/v4l/crop.rst index cb7e2341aedf..3fe185e25ccf 100644 --- a/Documentation/userspace-api/media/v4l/crop.rst +++ b/Documentation/userspace-api/media/v4l/crop.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _crop: diff --git a/Documentation/userspace-api/media/v4l/crop.svg b/Documentation/userspace-api/media/v4l/crop.svg index 4cd47f98e7c8..5483227757e7 100644 --- a/Documentation/userspace-api/media/v4l/crop.svg +++ b/Documentation/userspace-api/media/v4l/crop.svg @@ -1,14 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" diff --git a/Documentation/userspace-api/media/v4l/depth-formats.rst b/Documentation/userspace-api/media/v4l/depth-formats.rst index 6742486a83b5..b4f3fc229c85 100644 --- a/Documentation/userspace-api/media/v4l/depth-formats.rst +++ b/Documentation/userspace-api/media/v4l/depth-formats.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _depth-formats: diff --git a/Documentation/userspace-api/media/v4l/dev-capture.rst b/Documentation/userspace-api/media/v4l/dev-capture.rst index 44d3094093ab..fe58fd450e2f 100644 --- a/Documentation/userspace-api/media/v4l/dev-capture.rst +++ b/Documentation/userspace-api/media/v4l/dev-capture.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _capture: @@ -26,7 +20,6 @@ device. .. note:: The same device file names are used for video output devices. - Querying Capabilities ===================== @@ -41,7 +34,6 @@ functions they may also support the :ref:`video overlay <overlay>` streaming I/O methods must be supported. Tuners and audio inputs are optional. - Supplemental Functions ====================== @@ -52,7 +44,6 @@ Video capture devices shall support :ref:`audio input <audio>`, :ref:`video input <video>` ioctls must be supported by all video capture devices. - Image Format Negotiation ======================== @@ -62,7 +53,7 @@ capture, the latter how images are stored in memory, i. e. in RGB or YUV format, the number of bits per pixel or width and height. Together they also define how images are scaled in the process. -As usual these parameters are *not* reset at :ref:`open() <func-open>` +As usual these parameters are *not* reset at :c:func:`open()` time to permit Unix tool chains, programming a device and then reading from it as if it was a plain file. Well written V4L2 applications ensure they really get what they want, including cropping and scaling. @@ -102,7 +93,6 @@ and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. - Reading Images ============== diff --git a/Documentation/userspace-api/media/v4l/dev-decoder.rst b/Documentation/userspace-api/media/v4l/dev-decoder.rst index 606b54947e10..ef8e8cf31f90 100644 --- a/Documentation/userspace-api/media/v4l/dev-decoder.rst +++ b/Documentation/userspace-api/media/v4l/dev-decoder.rst @@ -38,7 +38,7 @@ Conventions and Notations Used in This Document 6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i = [0..2]: i = 0, 1, 2. -7. Given an ``OUTPUT`` buffer A, then A’ represents a buffer on the ``CAPTURE`` +7. Given an ``OUTPUT`` buffer A, then A' represents a buffer on the ``CAPTURE`` queue containing data that resulted from processing buffer A. .. _decoder-glossary: @@ -72,6 +72,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 +110,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 @@ -247,7 +254,7 @@ Querying Capabilities Initialization ============== -1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT` +1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT`. * **Required fields:** @@ -270,7 +277,7 @@ Initialization other fields follow standard semantics. - * **Return fields:** + * **Returned fields:** ``sizeimage`` adjusted size of ``OUTPUT`` buffers. @@ -288,7 +295,7 @@ Initialization Changing the ``OUTPUT`` format may change the currently set ``CAPTURE`` format. How the new ``CAPTURE`` format is determined is up to the decoder - and the client must ensure it matches its needs afterwards. + and the client must ensure it matches its needs afterwards. 2. Allocate source (bytestream) buffers via :c:func:`VIDIOC_REQBUFS` on ``OUTPUT``. @@ -304,7 +311,7 @@ Initialization ``memory`` follows standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` the actual number of buffers allocated. @@ -332,7 +339,7 @@ Initialization ``format`` follows standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` adjusted to the number of allocated buffers. @@ -403,7 +410,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 +443,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 +552,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 +629,7 @@ Capture Setup ``memory`` follows standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` actual number of buffers allocated. @@ -661,7 +668,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 +759,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 @@ -803,7 +827,7 @@ it may be affected as per normal decoder operation. * The decoder will drop all the pending ``OUTPUT`` buffers and they must be treated as returned to the client (following standard semantics). -2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON` +2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`. * **Required fields:** @@ -874,7 +898,7 @@ it may be affected as per normal decoder operation. any of the following results on the ``CAPTURE`` queue is allowed: - {A’, B’, G’, H’}, {A’, G’, H’}, {G’, H’}. + {A', B', G', H'}, {A', G', H'}, {G', H'}. To determine the CAPTURE buffer containing the first decoded frame after the seek, the client may observe the timestamps to match the CAPTURE and OUTPUT @@ -906,7 +930,9 @@ reflected by corresponding queries): * visible resolution (selection rectangles), -* the minimum number of buffers needed for decoding. +* the minimum number of buffers needed for decoding, + +* bit-depth of the bitstream has been changed. Whenever that happens, the decoder must proceed as follows: @@ -1059,7 +1085,7 @@ sequence was started. ``V4L2_DEC_CMD_STOP`` again while the drain sequence is in progress and they will fail with -EBUSY error code if attempted. - Although mandatory, the availability of decoder commands may be queried + Although not mandatory, the availability of decoder commands may be queried using :c:func:`VIDIOC_TRY_DECODER_CMD`. End of Stream diff --git a/Documentation/userspace-api/media/v4l/dev-encoder.rst b/Documentation/userspace-api/media/v4l/dev-encoder.rst new file mode 100644 index 000000000000..6c523c69bdce --- /dev/null +++ b/Documentation/userspace-api/media/v4l/dev-encoder.rst @@ -0,0 +1,729 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later + +.. _encoder: + +************************************************* +Memory-to-Memory Stateful Video Encoder Interface +************************************************* + +A stateful video encoder takes raw video frames in display order and encodes +them into a bytestream. It generates complete chunks of the bytestream, including +all metadata, headers, etc. The resulting bytestream does not require any +further post-processing by the client. + +Performing software stream processing, header generation etc. in the driver +in order to support this interface is strongly discouraged. In case such +operations are needed, use of the Stateless Video Encoder Interface (in +development) is strongly advised. + +Conventions and Notations Used in This Document +=============================================== + +1. The general V4L2 API rules apply if not specified in this document + otherwise. + +2. The meaning of words "must", "may", "should", etc. is as per `RFC + 2119 <https://tools.ietf.org/html/rfc2119>`_. + +3. All steps not marked "optional" are required. + +4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`VIDIOC_S_EXT_CTRLS` may be used + interchangeably with :c:func:`VIDIOC_G_CTRL` and :c:func:`VIDIOC_S_CTRL`, + unless specified otherwise. + +5. Single-planar API (see :ref:`planar-apis`) and applicable structures may be + used interchangeably with multi-planar API, unless specified otherwise, + depending on encoder capabilities and following the general V4L2 guidelines. + +6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i = + [0..2]: i = 0, 1, 2. + +7. Given an ``OUTPUT`` buffer A, then A' represents a buffer on the ``CAPTURE`` + queue containing data that resulted from processing buffer A. + +Glossary +======== + +Refer to :ref:`decoder-glossary`. + +State Machine +============= + +.. kernel-render:: DOT + :alt: DOT digraph of encoder state machine + :caption: Encoder State Machine + + digraph encoder_state_machine { + node [shape = doublecircle, label="Encoding"] Encoding; + + node [shape = circle, label="Initialization"] Initialization; + node [shape = circle, label="Stopped"] Stopped; + node [shape = circle, label="Drain"] Drain; + node [shape = circle, label="Reset"] Reset; + + node [shape = point]; qi + qi -> Initialization [ label = "open()" ]; + + Initialization -> Encoding [ label = "Both queues streaming" ]; + + Encoding -> Drain [ label = "V4L2_ENC_CMD_STOP" ]; + Encoding -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ]; + Encoding -> Stopped [ label = "VIDIOC_STREAMOFF(OUTPUT)" ]; + Encoding -> Encoding; + + Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(OUTPUT)" ]; + Drain -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ]; + + Reset -> Encoding [ label = "VIDIOC_STREAMON(CAPTURE)" ]; + Reset -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ]; + + Stopped -> Encoding [ label = "V4L2_ENC_CMD_START\nor\nVIDIOC_STREAMON(OUTPUT)" ]; + Stopped -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ]; + } + +Querying Capabilities +===================== + +1. To enumerate the set of coded formats supported by the encoder, the + client may call :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``. + + * The full set of supported formats will be returned, regardless of the + format set on ``OUTPUT``. + +2. To enumerate the set of supported raw formats, the client may call + :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``. + + * Only the formats supported for the format currently active on ``CAPTURE`` + will be returned. + + * In order to enumerate raw formats supported by a given coded format, + the client must first set that coded format on ``CAPTURE`` and then + enumerate the formats on ``OUTPUT``. + +3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported + resolutions for a given format, passing the desired pixel format in + :c:type:`v4l2_frmsizeenum` ``pixel_format``. + + * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a coded pixel + format will include all possible coded resolutions supported by the + encoder for the given coded pixel format. + + * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a raw pixel format + will include all possible frame buffer resolutions supported by the + encoder for the given raw pixel format and coded format currently set on + ``CAPTURE``. + +4. The client may use :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` to detect supported + frame intervals for a given format and resolution, passing the desired pixel + format in :c:type:`v4l2_frmivalenum` ``pixel_format`` and the resolution + in :c:type:`v4l2_frmivalenum` ``width`` and :c:type:`v4l2_frmivalenum` + ``height``. + + * Values returned by :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` for a coded pixel + format and coded resolution will include all possible frame intervals + supported by the encoder for the given coded pixel format and resolution. + + * Values returned by :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` for a raw pixel + format and resolution will include all possible frame intervals supported + by the encoder for the given raw pixel format and resolution and for the + coded format, coded resolution and coded frame interval currently set on + ``CAPTURE``. + + * Support for :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` is optional. If it is + not implemented, then there are no special restrictions other than the + limits of the codec itself. + +5. Supported profiles and levels for the coded format currently set on + ``CAPTURE``, if applicable, may be queried using their respective controls + via :c:func:`VIDIOC_QUERYCTRL`. + +6. Any additional encoder capabilities may be discovered by querying + their respective controls. + +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 (read-only). + + other fields + follow standard semantics. + + * **Returned fields:** + + ``sizeimage`` + adjusted size of ``CAPTURE`` buffers. + + ``width``, ``height`` + the coded size selected by the encoder based on current state, e.g. + ``OUTPUT`` format, selection rectangles, etc. (read-only). + + .. important:: + + Changing the ``CAPTURE`` format may change the currently set ``OUTPUT`` + format. How the new ``OUTPUT`` format is determined is up to the encoder + and the client must ensure it matches its needs afterwards. + +2. **Optional.** Enumerate supported ``OUTPUT`` formats (raw formats for + source) for the selected coded format via :c:func:`VIDIOC_ENUM_FMT`. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + other fields + follow standard semantics. + + * **Returned fields:** + + ``pixelformat`` + raw format supported for the coded format currently selected on + the ``CAPTURE`` queue. + + other fields + follow standard semantics. + +3. Set the raw source format on the ``OUTPUT`` queue via + :c:func:`VIDIOC_S_FMT`. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + ``pixelformat`` + raw format of the source. + + ``width``, ``height`` + source resolution. + + other fields + follow standard semantics. + + * **Returned fields:** + + ``width``, ``height`` + may be adjusted to match encoder minimums, maximums and alignment + requirements, as required by the currently selected formats, as + reported by :c:func:`VIDIOC_ENUM_FRAMESIZES`. + + other fields + follow standard semantics. + + * Setting the ``OUTPUT`` format will reset the selection rectangles to their + default values, based on the new resolution, as described in the next + step. + +4. Set the raw frame interval on the ``OUTPUT`` queue via + :c:func:`VIDIOC_S_PARM`. This also sets the coded frame interval on the + ``CAPTURE`` queue to the same value. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + ``parm.output`` + set all fields except ``parm.output.timeperframe`` to 0. + + ``parm.output.timeperframe`` + the desired frame interval; the encoder may adjust it to + match hardware requirements. + + * **Returned fields:** + + ``parm.output.timeperframe`` + the adjusted frame interval. + + .. important:: + + Changing the ``OUTPUT`` frame interval *also* sets the framerate that + the encoder uses to encode the video. So setting the frame interval + to 1/24 (or 24 frames per second) will produce a coded video stream + that can be played back at that speed. The frame interval for the + ``OUTPUT`` queue is just a hint, the application may provide raw + frames at a different rate. It can be used by the driver to help + schedule multiple encoders running in parallel. + + In the next step the ``CAPTURE`` frame interval can optionally be + changed to a different value. This is useful for off-line encoding + were the coded frame interval can be different from the rate at + which raw frames are supplied. + + .. important:: + + ``timeperframe`` deals with *frames*, not fields. So for interlaced + formats this is the time per two fields, since a frame consists of + a top and a bottom field. + + .. note:: + + It is due to historical reasons that changing the ``OUTPUT`` frame + interval also changes the coded frame interval on the ``CAPTURE`` + queue. Ideally these would be independent settings, but that would + break the existing API. + +5. **Optional** Set the coded frame interval on the ``CAPTURE`` queue via + :c:func:`VIDIOC_S_PARM`. This is only necessary if the coded frame + interval is different from the raw frame interval, which is typically + the case for off-line encoding. Support for this feature is signalled + by the :ref:`V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL <fmtdesc-flags>` format flag. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. + + ``parm.capture`` + set all fields except ``parm.capture.timeperframe`` to 0. + + ``parm.capture.timeperframe`` + the desired coded frame interval; the encoder may adjust it to + match hardware requirements. + + * **Returned fields:** + + ``parm.capture.timeperframe`` + the adjusted frame interval. + + .. important:: + + Changing the ``CAPTURE`` frame interval sets the framerate for the + coded video. It does *not* set the rate at which buffers arrive on the + ``CAPTURE`` queue, that depends on how fast the encoder is and how + fast raw frames are queued on the ``OUTPUT`` queue. + + .. important:: + + ``timeperframe`` deals with *frames*, not fields. So for interlaced + formats this is the time per two fields, since a frame consists of + a top and a bottom field. + + .. note:: + + Not all drivers support this functionality, in that case just set + the desired coded frame interval for the ``OUTPUT`` queue. + + However, drivers that can schedule multiple encoders based on the + ``OUTPUT`` frame interval must support this optional feature. + +6. **Optional.** Set the visible resolution for the stream metadata via + :c:func:`VIDIOC_S_SELECTION` on the ``OUTPUT`` queue if it is desired + to be different than the full OUTPUT resolution. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + ``target`` + set to ``V4L2_SEL_TGT_CROP``. + + ``r.left``, ``r.top``, ``r.width``, ``r.height`` + visible rectangle; this must fit within the `V4L2_SEL_TGT_CROP_BOUNDS` + rectangle and may be subject to adjustment to match codec and + hardware constraints. + + * **Returned fields:** + + ``r.left``, ``r.top``, ``r.width``, ``r.height`` + visible rectangle adjusted by the encoder. + + * The following selection targets are supported on ``OUTPUT``: + + ``V4L2_SEL_TGT_CROP_BOUNDS`` + equal to the full source frame, matching the active ``OUTPUT`` + format. + + ``V4L2_SEL_TGT_CROP_DEFAULT`` + equal to ``V4L2_SEL_TGT_CROP_BOUNDS``. + + ``V4L2_SEL_TGT_CROP`` + rectangle within the source buffer to be encoded into the + ``CAPTURE`` stream; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``. + + .. note:: + + A common use case for this selection target is encoding a source + video with a resolution that is not a multiple of a macroblock, + e.g. the common 1920x1080 resolution may require the source + buffers to be aligned to 1920x1088 for codecs with 16x16 macroblock + size. To avoid encoding the padding, the client needs to explicitly + configure this selection target to 1920x1080. + + .. warning:: + + The encoder may adjust the crop/compose rectangles to the nearest + supported ones to meet codec and hardware requirements. The client needs + to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`. + +7. Allocate buffers for both ``OUTPUT`` and ``CAPTURE`` via + :c:func:`VIDIOC_REQBUFS`. This may be performed in any order. + + * **Required fields:** + + ``count`` + requested number of buffers to allocate; greater than zero. + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT`` or + ``CAPTURE``. + + other fields + follow standard semantics. + + * **Returned fields:** + + ``count`` + actual number of buffers allocated. + + .. warning:: + + The actual number of allocated buffers may differ from the ``count`` + given. The client must check the updated value of ``count`` after the + call returns. + + .. note:: + + To allocate more than the minimum number of OUTPUT buffers (for pipeline + depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT`` + control to get the minimum number of buffers required, and pass the + obtained value plus the number of additional buffers needed in the + ``count`` field to :c:func:`VIDIOC_REQBUFS`. + + Alternatively, :c:func:`VIDIOC_CREATE_BUFS` can be used to have more + control over buffer allocation. + + * **Required fields:** + + ``count`` + requested number of buffers to allocate; greater than zero. + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + other fields + follow standard semantics. + + * **Returned fields:** + + ``count`` + adjusted to the number of allocated buffers. + +8. Begin streaming on both ``OUTPUT`` and ``CAPTURE`` queues via + :c:func:`VIDIOC_STREAMON`. This may be performed in any order. The actual + encoding process starts when both queues start streaming. + +.. note:: + + If the client stops the ``CAPTURE`` queue during the encode process and then + restarts it again, the encoder will begin generating a stream independent + from the stream generated before the stop. The exact constraints depend + on the coded format, but may include the following implications: + + * encoded frames produced after the restart must not reference any + frames produced before the stop, e.g. no long term references for + H.264/HEVC, + + * any headers that must be included in a standalone stream must be + produced again, e.g. SPS and PPS for H.264/HEVC. + +Encoding +======== + +This state is reached after the `Initialization` sequence finishes +successfully. In this state, the client queues and dequeues buffers to both +queues via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the +standard semantics. + +The content of encoded ``CAPTURE`` buffers depends on the active coded pixel +format and may be affected by codec-specific extended controls, as stated +in the documentation of each format. + +Both queues operate independently, following standard behavior of V4L2 buffer +queues and memory-to-memory devices. In addition, the order of encoded frames +dequeued from the ``CAPTURE`` queue may differ from the order of queuing raw +frames to the ``OUTPUT`` queue, due to properties of the selected coded format, +e.g. frame reordering. + +The client must not assume any direct relationship between ``CAPTURE`` and +``OUTPUT`` buffers and any specific timing of buffers becoming +available to dequeue. Specifically: + +* a buffer queued to ``OUTPUT`` may result in more than one buffer produced on + ``CAPTURE`` (for example, if returning an encoded frame allowed the encoder + to return a frame that preceded it in display, but succeeded it in the decode + order; however, there may be other reasons for this as well), + +* a buffer queued to ``OUTPUT`` may result in a buffer being produced on + ``CAPTURE`` later into encode process, and/or after processing further + ``OUTPUT`` buffers, or be returned out of order, e.g. if display + reordering is used, + +* buffers may become available on the ``CAPTURE`` queue without additional + buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the + ``OUTPUT`` buffers queued in the past whose encoding results are only + available at later time, due to specifics of the encoding process, + +* buffers queued to ``OUTPUT`` may not become available to dequeue instantly + after being encoded into a corresponding ``CAPTURE`` buffer, e.g. if the + encoder needs to use the frame as a reference for encoding further frames. + +.. note:: + + To allow matching encoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they + originated from, the client can set the ``timestamp`` field of the + :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The + ``CAPTURE`` buffer(s), which resulted from encoding that ``OUTPUT`` buffer + will have their ``timestamp`` field set to the same value when dequeued. + + In addition to the straightforward case of one ``OUTPUT`` buffer producing + one ``CAPTURE`` buffer, the following cases are defined: + + * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same + ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers, + + * the encoding order differs from the presentation order (i.e. the + ``CAPTURE`` buffers are out-of-order compared to the ``OUTPUT`` buffers): + ``CAPTURE`` timestamps will not retain the order of ``OUTPUT`` timestamps. + +.. note:: + + To let the client distinguish between frame types (keyframes, intermediate + frames; the exact list of types depends on the coded format), the + ``CAPTURE`` buffers will have corresponding flag bits set in their + :c:type:`v4l2_buffer` struct when dequeued. See the documentation of + :c:type:`v4l2_buffer` and each coded pixel format for exact list of flags + and their meanings. + +Should an encoding error occur, it will be reported to the client with the level +of details depending on the encoder capabilities. Specifically: + +* the ``CAPTURE`` buffer (if any) that contains the results of the failed encode + operation will be returned with the ``V4L2_BUF_FLAG_ERROR`` flag set, + +* if the encoder is able to precisely report the ``OUTPUT`` buffer(s) that triggered + the error, such buffer(s) will be returned with the ``V4L2_BUF_FLAG_ERROR`` flag + set. + +.. note:: + + If a ``CAPTURE`` buffer is too small then it is just returned with the + ``V4L2_BUF_FLAG_ERROR`` flag set. More work is needed to detect that this + error occurred because the buffer was too small, and to provide support to + free existing buffers that were too small. + +In case of a fatal failure that does not allow the encoding to continue, any +further operations on corresponding encoder file handle will return the -EIO +error code. The client may close the file handle and open a new one, or +alternatively reinitialize the instance by stopping streaming on both queues, +releasing all buffers and performing the Initialization sequence again. + +Encoding Parameter Changes +========================== + +The client is allowed to use :c:func:`VIDIOC_S_CTRL` to change encoder +parameters at any time. The availability of parameters is encoder-specific +and the client must query the encoder to find the set of available controls. + +The ability to change each parameter during encoding is encoder-specific, as +per the standard semantics of the V4L2 control interface. The client may +attempt to set a control during encoding and if the operation fails with the +-EBUSY error code, the ``CAPTURE`` queue needs to be stopped for the +configuration change to be allowed. To do this, it may follow the `Drain` +sequence to avoid losing the already queued/encoded frames. + +The timing of parameter updates is encoder-specific, as per the standard +semantics of the V4L2 control interface. If the client needs to apply the +parameters exactly at specific frame, using the Request API +(:ref:`media-request-api`) should be considered, if supported by the encoder. + +Drain +===== + +To ensure that all the queued ``OUTPUT`` buffers have been processed and the +related ``CAPTURE`` buffers are given to the client, the client must follow the +drain sequence described below. After the drain sequence ends, the client has +received all encoded frames for all ``OUTPUT`` buffers queued before the +sequence was started. + +1. Begin the drain sequence by issuing :c:func:`VIDIOC_ENCODER_CMD`. + + * **Required fields:** + + ``cmd`` + set to ``V4L2_ENC_CMD_STOP``. + + ``flags`` + set to 0. + + ``pts`` + set to 0. + + .. warning:: + + The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE`` + queues are streaming. For compatibility reasons, the call to + :c:func:`VIDIOC_ENCODER_CMD` will not fail even if any of the queues is + not streaming, but at the same time it will not initiate the `Drain` + sequence and so the steps described below would not be applicable. + +2. Any ``OUTPUT`` buffers queued by the client before the + :c:func:`VIDIOC_ENCODER_CMD` was issued will be processed and encoded as + normal. The client must continue to handle both queues independently, + similarly to normal encode operation. This includes: + + * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the + ``V4L2_BUF_FLAG_LAST`` flag is dequeued, + + .. warning:: + + The last buffer may be empty (with :c:type:`v4l2_buffer` + ``bytesused`` = 0) and in that case it must be ignored by the client, + as it does not contain an encoded frame. + + .. note:: + + Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer + marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from + :c:func:`VIDIOC_DQBUF`. + + * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued + before the ``V4L2_ENC_CMD_STOP`` command are dequeued, + + * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribes to it. + + .. note:: + + For backwards compatibility, the encoder will signal a ``V4L2_EVENT_EOS`` + event when the last frame has been encoded and all frames are ready to be + dequeued. It is deprecated behavior and the client must not rely on it. + The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead. + +3. Once all ``OUTPUT`` buffers queued before the ``V4L2_ENC_CMD_STOP`` call are + dequeued and the last ``CAPTURE`` buffer is dequeued, the encoder is stopped + and it will accept, but not process any newly queued ``OUTPUT`` buffers + until the client issues any of the following operations: + + * ``V4L2_ENC_CMD_START`` - the encoder will not be reset and will resume + operation normally, with all the state from before the drain, + + * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the + ``CAPTURE`` queue - the encoder will be reset (see the `Reset` sequence) + and then resume encoding, + + * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the + ``OUTPUT`` queue - the encoder will resume operation normally, however any + source frames queued to the ``OUTPUT`` queue between ``V4L2_ENC_CMD_STOP`` + and :c:func:`VIDIOC_STREAMOFF` will be discarded. + +.. note:: + + Once the drain sequence is initiated, the client needs to drive it to + completion, as described by the steps above, unless it aborts the process by + issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE`` + queues. The client is not allowed to issue ``V4L2_ENC_CMD_START`` or + ``V4L2_ENC_CMD_STOP`` again while the drain sequence is in progress and they + will fail with -EBUSY error code if attempted. + + For reference, handling of various corner cases is described below: + + * In case of no buffer in the ``OUTPUT`` queue at the time the + ``V4L2_ENC_CMD_STOP`` command was issued, the drain sequence completes + immediately and the encoder returns an empty ``CAPTURE`` buffer with the + ``V4L2_BUF_FLAG_LAST`` flag set. + + * In case of no buffer in the ``CAPTURE`` queue at the time the drain + sequence completes, the next time the client queues a ``CAPTURE`` buffer + it is returned at once as an empty buffer with the ``V4L2_BUF_FLAG_LAST`` + flag set. + + * If :c:func:`VIDIOC_STREAMOFF` is called on the ``CAPTURE`` queue in the + middle of the drain sequence, the drain sequence is canceled and all + ``CAPTURE`` buffers are implicitly returned to the client. + + * If :c:func:`VIDIOC_STREAMOFF` is called on the ``OUTPUT`` queue in the + middle of the drain sequence, the drain sequence completes immediately and + next ``CAPTURE`` buffer will be returned empty with the + ``V4L2_BUF_FLAG_LAST`` flag set. + + Although not mandatory, the availability of encoder commands may be queried + using :c:func:`VIDIOC_TRY_ENCODER_CMD`. + +Reset +===== + +The client may want to request the encoder to reinitialize the encoding, so +that the following stream data becomes independent from the stream data +generated before. Depending on the coded format, that may imply that: + +* encoded frames produced after the restart must not reference any frames + produced before the stop, e.g. no long term references for H.264/HEVC, + +* any headers that must be included in a standalone stream must be produced + again, e.g. SPS and PPS for H.264/HEVC. + +This can be achieved by performing the reset sequence. + +1. Perform the `Drain` sequence to ensure all the in-flight encoding finishes + and respective buffers are dequeued. + +2. Stop streaming on the ``CAPTURE`` queue via :c:func:`VIDIOC_STREAMOFF`. This + will return all currently queued ``CAPTURE`` buffers to the client, without + valid frame data. + +3. Start streaming on the ``CAPTURE`` queue via :c:func:`VIDIOC_STREAMON` and + continue with regular encoding sequence. The encoded frames produced into + ``CAPTURE`` buffers from now on will contain a standalone stream that can be + decoded without the need for frames encoded before the reset sequence, + starting at the first ``OUTPUT`` buffer queued after issuing the + `V4L2_ENC_CMD_STOP` of the `Drain` sequence. + +This sequence may be also used to change encoding parameters for encoders +without the ability to change the parameters on the fly. + +Commit Points +============= + +Setting formats and allocating buffers triggers changes in the behavior of the +encoder. + +1. Setting the format on the ``CAPTURE`` queue may change the set of formats + supported/advertised on the ``OUTPUT`` queue. In particular, it also means + that the ``OUTPUT`` format may be reset and the client must not rely on the + previously set format being preserved. + +2. Enumerating formats on the ``OUTPUT`` queue always returns only formats + supported for the current ``CAPTURE`` format. + +3. Setting the format on the ``OUTPUT`` queue does not change the list of + formats available on the ``CAPTURE`` queue. An attempt to set the ``OUTPUT`` + format that is not supported for the currently selected ``CAPTURE`` format + will result in the encoder adjusting the requested ``OUTPUT`` format to a + supported one. + +4. Enumerating formats on the ``CAPTURE`` queue always returns the full set of + supported coded formats, irrespective of the current ``OUTPUT`` format. + +5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues, + the client must not change the format on the ``CAPTURE`` queue. Drivers will + return the -EBUSY error code for any such format change attempt. + +To summarize, setting formats and allocation must always start with the +``CAPTURE`` queue and the ``CAPTURE`` queue is the master that governs the +set of supported formats for the ``OUTPUT`` queue. diff --git a/Documentation/userspace-api/media/v4l/dev-event.rst b/Documentation/userspace-api/media/v4l/dev-event.rst index d09034fd680a..f34f9cf6ce6c 100644 --- a/Documentation/userspace-api/media/v4l/dev-event.rst +++ b/Documentation/userspace-api/media/v4l/dev-event.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _event: diff --git a/Documentation/userspace-api/media/v4l/dev-mem2mem.rst b/Documentation/userspace-api/media/v4l/dev-mem2mem.rst index 9279d87c08a1..7041bb3d5b8d 100644 --- a/Documentation/userspace-api/media/v4l/dev-mem2mem.rst +++ b/Documentation/userspace-api/media/v4l/dev-mem2mem.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _mem2mem: @@ -39,11 +32,12 @@ file handle is visible through another file handle). One of the most common memory-to-memory device is the codec. Codecs are more complicated than most and require additional setup for their codec parameters. This is done through codec controls. -See :ref:`mpeg-controls`. More details on how to use codec memory-to-memory +See :ref:`codec-controls`. More details on how to use codec memory-to-memory devices are given in the following sections. .. toctree:: :maxdepth: 1 dev-decoder + dev-encoder dev-stateless-decoder diff --git a/Documentation/userspace-api/media/v4l/dev-meta.rst b/Documentation/userspace-api/media/v4l/dev-meta.rst index 6d2c5a79b370..5eee9ab60395 100644 --- a/Documentation/userspace-api/media/v4l/dev-meta.rst +++ b/Documentation/userspace-api/media/v4l/dev-meta.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _metadata: @@ -54,9 +47,15 @@ member of the ``fmt`` union as needed per the desired operation. Both drivers and applications must set the remainder of the :c:type:`v4l2_format` structure to 0. +Devices that capture metadata by line have the struct v4l2_fmtdesc +``V4L2_FMT_FLAG_META_LINE_BASED`` flag set for :c:func:`VIDIOC_ENUM_FMT`. Such +devices can typically also :ref:`capture image data <capture>`. This primarily +involves devices that receive the data from a different devices such as a camera +sensor. + .. c:type:: v4l2_meta_format -.. tabularcolumns:: |p{1.4cm}|p{2.2cm}|p{13.9cm}| +.. tabularcolumns:: |p{1.4cm}|p{2.4cm}|p{13.5cm}| .. flat-table:: struct v4l2_meta_format :header-rows: 0 @@ -72,3 +71,18 @@ to 0. - ``buffersize`` - Maximum buffer size in bytes required for data. The value is set by the driver. + * - __u32 + - ``width`` + - Width of a line of metadata in Data Units. Valid when + :c:type`v4l2_fmtdesc` flag ``V4L2_FMT_FLAG_META_LINE_BASED`` is set, + otherwise zero. See :c:func:`VIDIOC_ENUM_FMT`. + * - __u32 + - ``height`` + - Number of rows of metadata. Valid when :c:type`v4l2_fmtdesc` flag + ``V4L2_FMT_FLAG_META_LINE_BASED`` is set, otherwise zero. See + :c:func:`VIDIOC_ENUM_FMT`. + * - __u32 + - ``bytesperline`` + - Offset in bytes between the beginning of two consecutive lines. Valid + when :c:type`v4l2_fmtdesc` flag ``V4L2_FMT_FLAG_META_LINE_BASED`` is + set, otherwise zero. See :c:func:`VIDIOC_ENUM_FMT`. diff --git a/Documentation/userspace-api/media/v4l/dev-osd.rst b/Documentation/userspace-api/media/v4l/dev-osd.rst index 67dc46373a91..8e4be9129e75 100644 --- a/Documentation/userspace-api/media/v4l/dev-osd.rst +++ b/Documentation/userspace-api/media/v4l/dev-osd.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _osd: @@ -51,7 +44,7 @@ other information, the physical address of the framebuffer in the ``base`` field of struct :c:type:`v4l2_framebuffer`. The framebuffer device ioctl ``FBIOGET_FSCREENINFO`` returns the same address in the ``smem_start`` field of struct -struct :c:type:`fb_fix_screeninfo`. The ``FBIOGET_FSCREENINFO`` +:c:type:`fb_fix_screeninfo`. The ``FBIOGET_FSCREENINFO`` ioctl and struct :c:type:`fb_fix_screeninfo` are defined in the ``linux/fb.h`` header file. diff --git a/Documentation/userspace-api/media/v4l/dev-output.rst b/Documentation/userspace-api/media/v4l/dev-output.rst index e4f2a1d8b0fc..eadcb4aa813b 100644 --- a/Documentation/userspace-api/media/v4l/dev-output.rst +++ b/Documentation/userspace-api/media/v4l/dev-output.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _output: @@ -25,7 +19,6 @@ device. .. note:: The same device file names are used also for video capture devices. - Querying Capabilities ===================== @@ -39,7 +32,6 @@ functions they may also support the :ref:`raw VBI output <raw-vbi>` streaming I/O methods must be supported. Modulators and audio outputs are optional. - Supplemental Functions ====================== @@ -50,7 +42,6 @@ Video output devices shall support :ref:`audio output <audio>`, :ref:`video output <video>` ioctls must be supported by all video output devices. - Image Format Negotiation ======================== @@ -60,7 +51,7 @@ the latter how images are stored in memory, i. e. in RGB or YUV format, the number of bits per pixel or width and height. Together they also define how images are scaled in the process. -As usual these parameters are *not* reset at :ref:`open() <func-open>` +As usual these parameters are *not* reset at :c:func:`open()` time to permit Unix tool chains, programming a device and then writing to it as if it was a plain file. Well written V4L2 applications ensure they really get what they want, including cropping and scaling. @@ -99,7 +90,6 @@ and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. - Writing Images ============== diff --git a/Documentation/userspace-api/media/v4l/dev-overlay.rst b/Documentation/userspace-api/media/v4l/dev-overlay.rst index 7246d560173d..d52977120b41 100644 --- a/Documentation/userspace-api/media/v4l/dev-overlay.rst +++ b/Documentation/userspace-api/media/v4l/dev-overlay.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _overlay: @@ -44,6 +37,10 @@ capturing and overlay. Optionally these drivers may also permit capturing and overlay with a single file descriptor for compatibility with V4L and earlier versions of V4L2. [#f1]_ +A common application of two file descriptors is the X11 +:ref:`Xv/V4L <xvideo>` interface driver and a V4L2 application. +While the X server controls video overlay, the application can take +advantage of memory mapping and DMA. Querying Capabilities ===================== @@ -70,6 +67,7 @@ ioctls must be supported by all video overlay devices. Setup ===== +*Note: support for this has been removed.* Before overlay can commence applications must program the driver with frame buffer parameters, namely the address and size of the frame buffer and the image format, for example RGB 5:6:5. The @@ -95,11 +93,13 @@ A driver may support any (or none) of five clipping/blending methods: 1. Chroma-keying displays the overlaid image only where pixels in the primary graphics surface assume a certain color. -2. A bitmap can be specified where each bit corresponds to a pixel in +2. *Note: support for this has been removed.* + A bitmap can be specified where each bit corresponds to a pixel in the overlaid image. When the bit is set, the corresponding video pixel is displayed, otherwise a pixel of the graphics surface. -3. A list of clipping rectangles can be specified. In these regions *no* +3. *Note: support for this has been removed.* + A list of clipping rectangles can be specified. In these regions *no* video is displayed, so the graphics surface can be seen here. 4. The framebuffer has an alpha channel that can be used to clip or @@ -188,6 +188,7 @@ struct v4l2_window be 0xRRGGBB on a little endian, 0xBBGGRR on a big endian host. ``struct v4l2_clip * clips`` + *Note: support for this has been removed.* When chroma-keying has *not* been negotiated and :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability, applications can set this field to point to an array of clipping @@ -204,6 +205,7 @@ struct v4l2_window are undefined. ``__u32 clipcount`` + *Note: support for this has been removed.* When the application set the ``clips`` field, this field must contain the number of clipping rectangles in the list. When clip lists are not supported the driver ignores this field, its contents @@ -211,6 +213,7 @@ struct v4l2_window supported but no clipping is desired this field must be set to zero. ``void * bitmap`` + *Note: support for this has been removed.* When chroma-keying has *not* been negotiated and :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability, applications can set this field to point to a clipping bit mask. @@ -296,11 +299,6 @@ To start or stop the frame buffer overlay applications call the :ref:`VIDIOC_OVERLAY` ioctl. .. [#f1] - A common application of two file descriptors is the XFree86 - :ref:`Xv/V4L <xvideo>` interface driver and a V4L2 application. - While the X server controls video overlay, the application can take - advantage of memory mapping and DMA. - In the opinion of the designers of this API, no driver writer taking the efforts to support simultaneous capturing and overlay will restrict this ability by requiring a single file descriptor, as in diff --git a/Documentation/userspace-api/media/v4l/dev-radio.rst b/Documentation/userspace-api/media/v4l/dev-radio.rst index c0edd7b7d201..284ce96a1637 100644 --- a/Documentation/userspace-api/media/v4l/dev-radio.rst +++ b/Documentation/userspace-api/media/v4l/dev-radio.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _radio: diff --git a/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst b/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst index 0307d44e17cb..2bec20d87928 100644 --- a/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst +++ b/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _raw-vbi: @@ -39,7 +33,6 @@ applications must call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Accessed as ``/dev/vbi``, raw VBI capturing or output is the default device function. - Querying Capabilities ===================== @@ -48,10 +41,9 @@ Devices supporting the raw VBI capturing or output API set the in the ``capabilities`` field of struct :c:type:`v4l2_capability` returned by the :ref:`VIDIOC_QUERYCAP` ioctl. At least one of the -read/write, streaming or asynchronous I/O methods must be supported. VBI +read/write or streaming I/O methods must be supported. VBI devices may or may not have a tuner or modulator. - Supplemental Functions ====================== @@ -60,7 +52,6 @@ VBI devices shall support :ref:`video input or output <video>`, ioctls as needed. The :ref:`video standard <standard>` ioctls provide information vital to program a VBI device, therefore must be supported. - Raw VBI Format Negotiation ========================== @@ -69,7 +60,7 @@ frequency. To properly interpret the data V4L2 specifies an ioctl to query the sampling parameters. Moreover, to allow for some flexibility applications can also suggest different parameters. -As usual these parameters are *not* reset at :ref:`open() <func-open>` +As usual these parameters are *not* reset at :c:func:`open()` time to permit Unix tool chains, programming a device and then reading from it as if it was a plain file. Well written V4L2 applications should always ensure they really get what they want, requesting reasonable @@ -98,15 +89,15 @@ happen for instance when the video and VBI areas to capture would overlap, or when the driver supports multiple opens and another process already requested VBI capturing or output. Anyway, applications must expect other resource allocation points which may return ``EBUSY``, at the -:ref:`VIDIOC_STREAMON` ioctl and the first :ref:`read() <func-read>` -, :ref:`write() <func-write>` and :ref:`select() <func-select>` calls. +:ref:`VIDIOC_STREAMON` ioctl and the first :c:func:`read()` +, :c:func:`write()` and :c:func:`select()` calls. VBI devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. -.. tabularcolumns:: |p{1.6cm}|p{4.2cm}|p{11.7cm}| +.. tabularcolumns:: |p{1.6cm}|p{4.2cm}|p{11.5cm}| .. c:type:: v4l2_vbi_format @@ -189,8 +180,7 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does - This array is reserved for future extensions. Drivers and applications must set it to zero. - -.. tabularcolumns:: |p{4.4cm}|p{1.5cm}|p{11.6cm}| +.. tabularcolumns:: |p{4.4cm}|p{1.5cm}|p{11.4cm}| .. _vbifmt-flags: @@ -225,7 +215,6 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does non-zero. - .. _vbi-hsync: .. kernel-figure:: vbi_hsync.svg @@ -234,7 +223,6 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does **Figure 4.1. Line synchronization** - .. _vbi-525: .. kernel-figure:: vbi_525.svg @@ -258,7 +246,6 @@ negotiation, or after switching the video standard which may invalidate the negotiated VBI parameters, should be refused by the driver. A format change during active I/O is not permitted. - Reading and writing VBI images ============================== @@ -268,7 +255,6 @@ consisting of two fields of VBI images immediately following in memory. The total size of a frame computes as follows: - .. code-block:: c (count[0] + count[1]) * samples_per_line * sample size in bytes @@ -283,8 +269,8 @@ The latter bears the possibility of synchronizing video and VBI data by using buffer timestamps. Remember the :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` ioctl and the -first :ref:`read() <func-read>`, :ref:`write() <func-write>` and -:ref:`select() <func-select>` call can be resource allocation +first :c:func:`read()`, :c:func:`write()` and +:c:func:`select()` call can be resource allocation points returning an ``EBUSY`` error code if the required hardware resources are temporarily unavailable, for example the device is already in use by another process. diff --git a/Documentation/userspace-api/media/v4l/dev-rds.rst b/Documentation/userspace-api/media/v4l/dev-rds.rst index 13dba4a4180c..b1dadc24561f 100644 --- a/Documentation/userspace-api/media/v4l/dev-rds.rst +++ b/Documentation/userspace-api/media/v4l/dev-rds.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _rds: @@ -35,7 +29,6 @@ The RDS interface does not support this format. Should support for MMBS the linux-media mailing list: `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. - Querying Capabilities ===================== @@ -75,35 +68,29 @@ like program identification codes and radio text, the flag :ref:`Writing RDS data <writing-rds-data>` and :ref:`FM Transmitter Control Reference <fm-tx-controls>`. - .. _reading-rds-data: Reading RDS data ================ RDS data can be read from the radio device with the -:ref:`read() <func-read>` function. The data is packed in groups of +:c:func:`read()` function. The data is packed in groups of three bytes. - .. _writing-rds-data: Writing RDS data ================ RDS data can be written to the radio device with the -:ref:`write() <func-write>` function. The data is packed in groups of +:c:func:`write()` function. The data is packed in groups of three bytes, as follows: - RDS datastructures ================== - .. c:type:: v4l2_rds_data -.. tabularcolumns:: |p{2.5cm}|p{2.5cm}|p{12.5cm}| - .. flat-table:: struct v4l2_rds_data :header-rows: 0 :stub-columns: 0 @@ -120,7 +107,6 @@ RDS datastructures - Block description - .. _v4l2-rds-block: .. tabularcolumns:: |p{2.9cm}|p{14.6cm}| @@ -143,10 +129,9 @@ RDS datastructures reception of this block. - .. _v4l2-rds-block-codes: -.. tabularcolumns:: |p{6.4cm}|p{2.0cm}|p{1.2cm}|p{7.9cm}| +.. tabularcolumns:: |p{6.4cm}|p{2.0cm}|p{1.2cm}|p{7.0cm}| .. flat-table:: Block defines :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/dev-sdr.rst b/Documentation/userspace-api/media/v4l/dev-sdr.rst index c9563bca444e..dfdeddbca41f 100644 --- a/Documentation/userspace-api/media/v4l/dev-sdr.rst +++ b/Documentation/userspace-api/media/v4l/dev-sdr.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _sdr: @@ -41,7 +34,7 @@ Devices supporting the SDR transmitter interface set the device has an Digital to Analog Converter (DAC), which is a mandatory element for the SDR transmitter. -At least one of the read/write, streaming or asynchronous I/O methods +At least one of the read/write or streaming I/O methods must be supported. @@ -78,7 +71,7 @@ field of a struct :c:type:`v4l2_format` to ``V4L2_BUF_TYPE_SDR_CAPTURE`` or ``V4L2_BUF_TYPE_SDR_OUTPUT`` and use the struct :c:type:`v4l2_sdr_format` ``sdr`` member of the ``fmt`` union as needed per the desired operation. Currently -there is two fields, ``pixelformat`` and ``buffersize``, of struct +there are two fields, ``pixelformat`` and ``buffersize``, of struct :c:type:`v4l2_sdr_format` which are used. Content of the ``pixelformat`` is V4L2 FourCC code of the data format. The ``buffersize`` field is maximum buffer size in bytes required for @@ -87,7 +80,7 @@ data transfer, set by the driver in order to inform application. .. c:type:: v4l2_sdr_format -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_sdr_format :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst index dd0b6646beb5..42cdb0a9f786 100644 --- a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst +++ b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _sliced: @@ -34,7 +28,6 @@ however the default function here is video capturing or output. Different file descriptors must be used to pass raw and sliced VBI data simultaneously, if this is supported by the driver. - Querying Capabilities ===================== @@ -43,10 +36,9 @@ Devices supporting the sliced VBI capturing or output API set the respectively, in the ``capabilities`` field of struct :c:type:`v4l2_capability` returned by the :ref:`VIDIOC_QUERYCAP` ioctl. At least one of the -read/write, streaming or asynchronous :ref:`I/O methods <io>` must be +read/write or streaming :ref:`I/O methods <io>` must be supported. Sliced VBI devices may have a tuner or modulator. - Supplemental Functions ====================== @@ -56,7 +48,6 @@ capabilities, and they may support :ref:`control` ioctls. The :ref:`video standard <standard>` ioctls provide information vital to program a sliced VBI device, therefore must be supported. - .. _sliced-vbi-format-negotitation: Sliced VBI Format Negotiation @@ -103,9 +94,8 @@ at this point, it may return an ``EBUSY`` error code if the required resources are temporarily unavailable. Other resource allocation points which may return ``EBUSY`` can be the :ref:`VIDIOC_STREAMON` ioctl and the first -:ref:`read() <func-read>`, :ref:`write() <func-write>` and -:ref:`select() <func-select>` call. - +:c:func:`read()`, :c:func:`write()` and +:c:func:`select()` call. .. c:type:: v4l2_sliced_vbi_format @@ -118,7 +108,7 @@ struct v4l2_sliced_vbi_format \scriptsize \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{.85cm}|p{3.3cm}|p{4.4cm}|p{4.4cm}|p{4.4cm}| +.. tabularcolumns:: |p{.85cm}|p{3.3cm}|p{4.45cm}|p{4.45cm}|p{4.45cm}| .. cssclass:: longtable @@ -127,7 +117,7 @@ struct v4l2_sliced_vbi_format :stub-columns: 0 :widths: 3 3 2 2 2 - * - __u32 + * - __u16 - ``service_set`` - :cspan:`2` @@ -198,7 +188,7 @@ struct v4l2_sliced_vbi_format * - __u32 - ``io_size`` - :cspan:`2` Maximum number of bytes passed by one - :ref:`read() <func-read>` or :ref:`write() <func-write>` call, + :c:func:`read()` or :c:func:`write()` call, and the buffer size in bytes for the :ref:`VIDIOC_QBUF` and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. Drivers set this field @@ -223,9 +213,9 @@ Sliced VBI services .. raw:: latex - \scriptsize + \footnotesize -.. tabularcolumns:: |p{4.1cm}|p{1.1cm}|p{2.4cm}|p{2.0cm}|p{7.3cm}| +.. tabularcolumns:: |p{4.2cm}|p{1.1cm}|p{2.1cm}|p{2.0cm}|p{6.5cm}| .. flat-table:: :header-rows: 1 @@ -263,13 +253,7 @@ Sliced VBI services :ref:`en300294` - PAL/SECAM line 23 - - - - :: - - Byte 0 1 - msb lsb msb lsb - Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9 + - See :ref:`v4l2-sliced-wss-625-payload` below. * - ``V4L2_SLICED_VBI_525`` - 0x1000 - :cspan:`2` Set of services applicable to 525 line systems. @@ -281,7 +265,6 @@ Sliced VBI services \normalsize - Drivers may return an ``EINVAL`` error code when applications attempt to read or write data without prior format negotiation, after switching the video standard (which may invalidate the negotiated VBI parameters) and @@ -291,13 +274,27 @@ return an ``EBUSY`` error code when applications attempt to change the format while i/o is in progress (between a :ref:`VIDIOC_STREAMON` and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call, and after the first -:ref:`read() <func-read>` or :ref:`write() <func-write>` call). +:c:func:`read()` or :c:func:`write()` call). + +.. _v4l2-sliced-wss-625-payload: + +V4L2_SLICED_WSS_625 payload +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The payload for ``V4L2_SLICED_WSS_625`` is: + +-----+------------------+-----------------------+ + |Byte | 0 | 1 | + +-----+--------+---------+-----------+-----------+ + | | msb | lsb | msb | lsb | + | +-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+ + | Bit |7|6|5|4 | 3|2|1|0 | x|x|13|12 | 11|10|9|8 | + +-----+-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+ Reading and writing sliced VBI data =================================== -A single :ref:`read() <func-read>` or :ref:`write() <func-write>` +A single :c:func:`read()` or :c:func:`write()` call must pass all data belonging to one video frame. That is an array of struct :c:type:`v4l2_sliced_vbi_data` structures with one or more elements and a total size not exceeding ``io_size`` bytes. Likewise @@ -305,13 +302,12 @@ in streaming I/O mode one buffer of ``io_size`` bytes must contain data of one video frame. The ``id`` of unused struct :c:type:`v4l2_sliced_vbi_data` elements must be zero. - .. c:type:: v4l2_sliced_vbi_data struct v4l2_sliced_vbi_data --------------------------- -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{1.2cm}|p{2.2cm}|p{13.9cm}| .. flat-table:: :header-rows: 0 @@ -351,9 +347,8 @@ struct v4l2_sliced_vbi_data bytes at the end of this array are undefined, drivers and applications shall ignore them. - Packets are always passed in ascending line number order, without -duplicate line numbers. The :ref:`write() <func-write>` function and +duplicate line numbers. The :c:func:`write()` function and the :ref:`VIDIOC_QBUF` ioctl must return an ``EINVAL`` error code when applications violate this rule. They must also return an EINVAL error code when applications pass an incorrect field or line @@ -377,7 +372,6 @@ streaming (:ref:`memory mapping <mmap>` and/or :ref:`user pointer <userp>`) I/O. The latter bears the possibility of synchronizing video and VBI data by using buffer timestamps. - Sliced VBI Data in MPEG Streams =============================== @@ -412,7 +406,6 @@ data insertion is not supported by the device. The following subsections specify the format of the embedded sliced VBI data. - MPEG Stream Embedded, Sliced VBI Data Format: NONE -------------------------------------------------- @@ -424,7 +417,6 @@ nor driver shall insert "empty" embedded sliced VBI data packets in the MPEG stream when this format is set. No MPEG stream data structures are specified for this format. - MPEG Stream Embedded, Sliced VBI Data Format: IVTV -------------------------------------------------- @@ -467,13 +459,12 @@ the end with unspecified fill bytes to align the end of the payload to a with 18 lines/field with 43 bytes of data/line and a 4 byte magic number). - .. c:type:: v4l2_mpeg_vbi_fmt_ivtv struct v4l2_mpeg_vbi_fmt_ivtv ----------------------------- -.. tabularcolumns:: |p{1.0cm}|p{3.8cm}|p{1.0cm}|p{11.2cm}| +.. tabularcolumns:: |p{4.2cm}|p{2.0cm}|p{11.1cm}| .. flat-table:: :header-rows: 0 @@ -499,7 +490,7 @@ struct v4l2_mpeg_vbi_fmt_ivtv - An alternate form of the sliced VBI data payload used when 36 lines of sliced VBI data are present. No line masks are provided in this form of the payload; all valid line mask bits are - implcitly set. + implicitly set. * - } - @@ -508,7 +499,7 @@ struct v4l2_mpeg_vbi_fmt_ivtv Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field ------------------------------------------------------------- -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. flat-table:: :header-rows: 1 @@ -530,7 +521,6 @@ Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field valid and that 36 lines of sliced VBI data are present. - .. c:type:: v4l2_mpeg_vbi_itv0 .. c:type:: v4l2_mpeg_vbi_ITV0 @@ -538,7 +528,11 @@ Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0 ------------------------------------------------- -.. tabularcolumns:: |p{5.2cm}|p{2.4cm}|p{9.9cm}| +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{4.6cm}|p{2.0cm}|p{10.7cm}| .. flat-table:: :header-rows: 0 @@ -555,7 +549,6 @@ structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0 value: - :: linemask[0] b0: line 6 first field @@ -580,14 +573,16 @@ structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0 one line of unspecified data that should be ignored by applications. +.. raw:: latex + \normalsize .. _v4l2-mpeg-vbi-itv0-1: struct v4l2_mpeg_vbi_ITV0 ------------------------- -.. tabularcolumns:: |p{5.2cm}|p{2.4cm}|p{9.9cm}| +.. tabularcolumns:: |p{5.2cm}|p{2.4cm}|p{9.7cm}| .. flat-table:: :header-rows: 0 @@ -603,13 +598,12 @@ struct v4l2_mpeg_vbi_ITV0 lines 6 through 23 of the second field. - .. c:type:: v4l2_mpeg_vbi_itv0_line struct v4l2_mpeg_vbi_itv0_line ------------------------------ -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: :header-rows: 0 @@ -626,13 +620,12 @@ struct v4l2_mpeg_vbi_itv0_line - The sliced VBI data for the line. - .. _ITV0-Line-Identifier-Constants: Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field ------------------------------------------------------------ -.. tabularcolumns:: |p{7.0cm}|p{1.8cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.0cm}|p{1.8cm}|p{8.5cm}| .. flat-table:: :header-rows: 1 @@ -660,7 +653,6 @@ Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field description of the line payload. - .. [#f1] According to :ref:`ETS 300 706 <ets300706>` lines 6-22 of the first field and lines 5-22 of the second field may carry Teletext data. diff --git a/Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst b/Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst index 4a26646eeec5..35ed05f2695e 100644 --- a/Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst +++ b/Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst @@ -180,7 +180,7 @@ Initialization ``memory`` follows standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` actual number of buffers allocated. @@ -208,7 +208,7 @@ Initialization follows standard semantics. ``V4L2_MEMORY_USERPTR`` is not supported for ``CAPTURE`` buffers. - * **Return fields:** + * **Returned fields:** ``count`` adjusted to allocated number of buffers, in case the codec requires diff --git a/Documentation/userspace-api/media/v4l/dev-subdev.rst b/Documentation/userspace-api/media/v4l/dev-subdev.rst index 134d2fb909fa..161b43f1ce66 100644 --- a/Documentation/userspace-api/media/v4l/dev-subdev.rst +++ b/Documentation/userspace-api/media/v4l/dev-subdev.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _subdev: @@ -36,6 +29,8 @@ will feature a character device node on which ioctls can be called to - negotiate image formats on individual pads +- inspect and modify internal data routing between pads of the same entity + Sub-device character device nodes, conventionally named ``/dev/v4l-subdev*``, use major number 81. @@ -216,9 +211,11 @@ list entity names and pad numbers). .. raw:: latex + \begingroup \scriptsize + \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{2.0cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}| +.. tabularcolumns:: |p{2.0cm}|p{2.1cm}|p{2.1cm}|p{2.1cm}|p{2.1cm}|p{2.1cm}|p{2.1cm}| .. _sample-pipeline-config: @@ -305,7 +302,7 @@ list entity names and pad numbers). .. raw:: latex - \normalsize + \endgroup 1. Initial state. The sensor source pad format is set to its native 3MP size and V4L2_MBUS_FMT_SGRBG8_1X8 media bus code. Formats on the @@ -409,6 +406,8 @@ pixel array is not rectangular but cross-shaped or round. The maximum size may also be smaller than the BOUNDS rectangle. +.. _format-propagation: + Order of configuration and format propagation --------------------------------------------- @@ -506,3 +505,189 @@ source pads. :maxdepth: 1 subdev-formats + +.. _subdev-routing: + +Streams, multiplexed media pads and internal routing +---------------------------------------------------- + +Simple V4L2 sub-devices do not support multiple, unrelated video streams, +and only a single stream can pass through a media link and a media pad. +Thus each pad contains a format and selection configuration for that +single stream. A subdev can do stream processing and split a stream into +two or compose two streams into one, but the inputs and outputs for the +subdev are still a single stream per pad. + +Some hardware, e.g. MIPI CSI-2, support multiplexed streams, that is, multiple +data streams are transmitted on the same bus, which is represented by a media +link connecting a transmitter source pad with a sink pad on the receiver. For +example, a camera sensor can produce two distinct streams, a pixel stream and a +metadata stream, which are transmitted on the multiplexed data bus, represented +by a media link which connects the single sensor's source pad with the receiver +sink pad. The stream-aware receiver will de-multiplex the streams received on +the its sink pad and allows to route them individually to one of its source +pads. + +Subdevice drivers that support multiplexed streams are compatible with +non-multiplexed subdev drivers. However, if the driver at the sink end of a link +does not support streams, then only stream 0 of source end may be captured. +There may be additional limitations specific to the sink device. + +Understanding streams +^^^^^^^^^^^^^^^^^^^^^ + +A stream is a stream of content (e.g. pixel data or metadata) flowing through +the media pipeline from a source (e.g. a sensor) towards the final sink (e.g. a +receiver and demultiplexer in a SoC). Each media link carries all the enabled +streams from one end of the link to the other, and sub-devices have routing +tables which describe how the incoming streams from sink pads are routed to the +source pads. + +A stream ID is a media pad-local identifier for a stream. Streams IDs of +the same stream must be equal on both ends of a link. In other words, +a particular stream ID must exist on both sides of a media +link, but another stream ID can be used for the same stream at the other side +of the sub-device. + +A stream at a specific point in the media pipeline is identified by the +sub-device and a (pad, stream) pair. For sub-devices that do not support +multiplexed streams the 'stream' field is always 0. + +Interaction between routes, streams, formats and selections +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The addition of streams to the V4L2 sub-device interface moves the sub-device +formats and selections from pads to (pad, stream) pairs. Besides the +usual pad, also the stream ID needs to be provided for setting formats and +selections. The order of configuring formats and selections along a stream is +the same as without streams (see :ref:`format-propagation`). + +Instead of the sub-device wide merging of streams from all sink pads +towards all source pads, data flows for each route are separate from each +other. Any number of routes from streams on sink pads towards streams on +source pads is allowed, to the extent supported by drivers. For every +stream on a source pad, however, only a single route is allowed. + +Any configurations of a stream within a pad, such as format or selections, +are independent of similar configurations on other streams. This is +subject to change in the future. + +Device types and routing setup +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Different kinds of sub-devices have differing behaviour for route activation, +depending on the hardware. In all cases, however, only routes that have the +``V4L2_SUBDEV_STREAM_FL_ACTIVE`` flag set are active. + +Devices generating the streams may allow enabling and disabling some of the +routes or have a fixed routing configuration. If the routes can be disabled, not +declaring the routes (or declaring them without +``V4L2_SUBDEV_STREAM_FL_ACTIVE`` flag set) in ``VIDIOC_SUBDEV_S_ROUTING`` will +disable the routes. ``VIDIOC_SUBDEV_S_ROUTING`` will still return such routes +back to the user in the routes array, with the ``V4L2_SUBDEV_STREAM_FL_ACTIVE`` +flag unset. + +Devices transporting the streams almost always have more configurability with +respect to routing. Typically any route between the sub-device's sink and source +pads is possible, and multiple routes (usually up to certain limited number) may +be active simultaneously. For such devices, no routes are created by the driver +and user-created routes are fully replaced when ``VIDIOC_SUBDEV_S_ROUTING`` is +called on the sub-device. Such newly created routes have the device's default +configuration for format and selection rectangles. + +Configuring streams +^^^^^^^^^^^^^^^^^^^ + +The configuration of the streams is done individually for each sub-device and +the validity of the streams between sub-devices is validated when the pipeline +is started. + +There are three steps in configuring the streams: + +1. Set up links. Connect the pads between sub-devices using the + :ref:`Media Controller API <media_controller>` + +2. Streams. Streams are declared and their routing is configured by setting the + routing table for the sub-device using :ref:`VIDIOC_SUBDEV_S_ROUTING + <VIDIOC_SUBDEV_G_ROUTING>` ioctl. Note that setting the routing table will + reset formats and selections in the sub-device to default values. + +3. Configure formats and selections. Formats and selections of each stream are + configured separately as documented for plain sub-devices in + :ref:`format-propagation`. The stream ID is set to the same stream ID + associated with either sink or source pads of routes configured using the + :ref:`VIDIOC_SUBDEV_S_ROUTING <VIDIOC_SUBDEV_G_ROUTING>` ioctl. + +Multiplexed streams setup example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A simple example of a multiplexed stream setup might be as follows: + +- Two identical sensors (Sensor A and Sensor B). Each sensor has a single source + pad (pad 0) which carries a pixel data stream. + +- Multiplexer bridge (Bridge). The bridge has two sink pads, connected to the + sensors (pads 0, 1), and one source pad (pad 2), which outputs two streams. + +- Receiver in the SoC (Receiver). The receiver has a single sink pad (pad 0), + connected to the bridge, and two source pads (pads 1-2), going to the DMA + engine. The receiver demultiplexes the incoming streams to the source pads. + +- DMA Engines in the SoC (DMA Engine), one for each stream. Each DMA engine is + connected to a single source pad in the receiver. + +The sensors, the bridge and the receiver are modeled as V4L2 sub-devices, +exposed to userspace via /dev/v4l-subdevX device nodes. The DMA engines are +modeled as V4L2 devices, exposed to userspace via /dev/videoX nodes. + +To configure this pipeline, the userspace must take the following steps: + +1. Set up media links between entities: connect the sensors to the bridge, + bridge to the receiver, and the receiver to the DMA engines. This step does + not differ from normal non-multiplexed media controller setup. + +2. Configure routing + +.. flat-table:: Bridge routing table + :header-rows: 1 + + * - Sink Pad/Stream + - Source Pad/Stream + - Routing Flags + - Comments + * - 0/0 + - 2/0 + - V4L2_SUBDEV_ROUTE_FL_ACTIVE + - Pixel data stream from Sensor A + * - 1/0 + - 2/1 + - V4L2_SUBDEV_ROUTE_FL_ACTIVE + - Pixel data stream from Sensor B + +.. flat-table:: Receiver routing table + :header-rows: 1 + + * - Sink Pad/Stream + - Source Pad/Stream + - Routing Flags + - Comments + * - 0/0 + - 1/0 + - V4L2_SUBDEV_ROUTE_FL_ACTIVE + - Pixel data stream from Sensor A + * - 0/1 + - 2/0 + - V4L2_SUBDEV_ROUTE_FL_ACTIVE + - Pixel data stream from Sensor B + +3. Configure formats and selections + + After configuring routing, the next step is configuring the formats and + selections for the streams. This is similar to performing this step without + streams, with just one exception: the ``stream`` field needs to be assigned + to the value of the stream ID. + + A common way to accomplish this is to start from the sensors and propagate + the configurations along the stream towards the receiver, using + :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctls to configure each + stream endpoint in each sub-device. diff --git a/Documentation/userspace-api/media/v4l/dev-touch.rst b/Documentation/userspace-api/media/v4l/dev-touch.rst index c1ce446274f2..a71b9def5d58 100644 --- a/Documentation/userspace-api/media/v4l/dev-touch.rst +++ b/Documentation/userspace-api/media/v4l/dev-touch.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _touch: diff --git a/Documentation/userspace-api/media/v4l/devices.rst b/Documentation/userspace-api/media/v4l/devices.rst index 47ffe90753dd..8bfbad65a9d4 100644 --- a/Documentation/userspace-api/media/v4l/devices.rst +++ b/Documentation/userspace-api/media/v4l/devices.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _devices: diff --git a/Documentation/userspace-api/media/v4l/diff-v4l.rst b/Documentation/userspace-api/media/v4l/diff-v4l.rst index 37644d26c4ae..33243ecb5033 100644 --- a/Documentation/userspace-api/media/v4l/diff-v4l.rst +++ b/Documentation/userspace-api/media/v4l/diff-v4l.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _diff-v4l: @@ -20,7 +14,6 @@ the much improved V4L2 API replaces the V4L API. The support for the old V4L calls were removed from Kernel, but the library :ref:`libv4l` supports the conversion of a V4L API system call into a V4L2 one. - Opening and Closing Devices =========================== @@ -39,7 +32,6 @@ recommend that V4L2 drivers by default register devices with the same numbers, but the system administrator can assign arbitrary minor numbers using driver module options. The major device number remains 81. - .. _v4l-dev: .. flat-table:: V4L Device Types, Names and Numbers @@ -60,14 +52,12 @@ using driver module options. The major device number remains 81. - ``/dev/vbi``, ``/dev/vbi0`` to ``/dev/vbi31`` - 224-255 - V4L prohibits (or used to prohibit) multiple opens of a device file. V4L2 drivers *may* support multiple opens, see :ref:`open` for details and consequences. V4L drivers respond to V4L2 ioctls with an ``EINVAL`` error code. - Querying Capabilities ===================== @@ -82,7 +72,11 @@ and radio devices supporting a set of related functions like video capturing, video overlay and VBI capturing. See :ref:`open` for an introduction. -.. tabularcolumns:: |p{5.5cm}|p{6.5cm}|p{5.5cm} +.. raw:: latex + + \small + +.. tabularcolumns:: |p{5.3cm}|p{6.7cm}|p{5.3cm}| .. cssclass:: longtable @@ -158,6 +152,9 @@ introduction. - ``-`` - See above. +.. raw:: latex + + \normalsize The ``audios`` field was replaced by ``capabilities`` flag ``V4L2_CAP_AUDIO``, indicating *if* the device has any audio inputs or @@ -171,7 +168,6 @@ were removed. Calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or dimensions returns the closest size possible, taking into account the current video standard, cropping and scaling limitations. - Video Sources ============= @@ -187,7 +183,6 @@ The ``channel`` field counting inputs was renamed to ``index``, the video input types were renamed as follows: - .. flat-table:: :header-rows: 1 :stub-columns: 0 @@ -199,7 +194,6 @@ video input types were renamed as follows: * - ``VIDEO_TYPE_CAMERA`` - ``V4L2_INPUT_TYPE_CAMERA`` - Unlike the ``tuners`` field expressing the number of tuners of this input, V4L2 assumes each video input is connected to at most one tuner. However a tuner can have more than one input, i. e. RF connectors, and a @@ -223,7 +217,6 @@ addition together with the ``norm`` field and has been removed in the meantime. V4L2 has a similar, albeit more comprehensive approach to video standards, see :ref:`standard` for more information. - Tuning ====== @@ -267,7 +260,6 @@ frequency where renamed to to a struct :c:type:`v4l2_frequency` instead of an unsigned long integer. - .. _v4l-image-properties: Image Properties @@ -281,7 +273,6 @@ replaced by V4L2 controls accessible with the :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls: - .. flat-table:: :header-rows: 1 :stub-columns: 0 @@ -299,7 +290,6 @@ replaced by V4L2 controls accessible with the * - ``whiteness`` - ``V4L2_CID_WHITENESS`` - The V4L picture controls are assumed to range from 0 to 65535 with no particular reset value. The V4L2 API permits arbitrary limits and defaults which can be queried with the @@ -313,7 +303,6 @@ of the image depth and others need not know. The ``palette`` field moved into the struct :c:type:`v4l2_pix_format`: - .. flat-table:: :header-rows: 1 :stub-columns: 0 @@ -353,11 +342,9 @@ into the struct :c:type:`v4l2_pix_format`: * - ``VIDEO_PALETTE_YUV410P`` - :ref:`V4L2_PIX_FMT_YVU410 <V4L2-PIX-FMT-YVU410>` - V4L2 image formats are defined in :ref:`pixfmt`. The image format can be selected with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. - Audio ===== @@ -391,7 +378,6 @@ The following fields where replaced by V4L2 controls accessible with the :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls: - .. flat-table:: :header-rows: 1 :stub-columns: 0 @@ -407,7 +393,6 @@ The following fields where replaced by V4L2 controls accessible with the * - ``balance`` - ``V4L2_CID_AUDIO_BALANCE`` - To determine which of these controls are supported by a driver V4L provides the ``flags`` ``VIDEO_AUDIO_VOLUME``, ``VIDEO_AUDIO_BASS``, ``VIDEO_AUDIO_TREBLE`` and ``VIDEO_AUDIO_BALANCE``. In the V4L2 API the @@ -423,7 +408,6 @@ V4L2 API permits arbitrary limits and defaults which can be queried with the :ref:`VIDIOC_QUERYCTRL` ioctl. For general information about controls see :ref:`control`. - Frame Buffer Overlay ==================== @@ -470,7 +454,6 @@ size is determined by ``w.width`` and ``w.height``. The ``VIDIOCCAPTURE`` ioctl to enable or disable overlay was renamed to :ref:`VIDIOC_OVERLAY`. - Cropping ======== @@ -497,21 +480,19 @@ struct :c:type:`v4l2_window`. These structures are used to select a capture or overlay format with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. - Reading Images, Memory Mapping ============================== - Capturing using the read method ------------------------------- There is no essential difference between reading images from a V4L or -V4L2 device using the :ref:`read() <func-read>` function, however V4L2 +V4L2 device using the :c:func:`read()` function, however V4L2 drivers are not required to support this I/O method. Applications can determine if the function is available with the :ref:`VIDIOC_QUERYCAP` ioctl. All V4L2 devices exchanging data with applications must support the -:ref:`select() <func-select>` and :ref:`poll() <func-poll>` +:c:func:`select()` and :c:func:`poll()` functions. To select an image format and size, V4L provides the ``VIDIOCSPICT`` and @@ -524,7 +505,6 @@ negotiation ioctls :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and For more information about the V4L2 read interface see :ref:`rw`. - Capturing using memory mapping ------------------------------ @@ -535,7 +515,6 @@ read method. V4L2 supports memory mapping as well, with a few differences. - .. flat-table:: :header-rows: 1 :stub-columns: 0 @@ -557,7 +536,7 @@ differences. ``VIDIOCGMBUF`` ioctl is available to query the number of buffers, the offset of each buffer from the start of the virtual file, and the overall amount of memory used, which can be used as arguments - for the :ref:`mmap() <func-mmap>` function. + for the :c:func:`mmap()` function. - Buffers are individually mapped. The offset and size of each buffer can be determined with the :ref:`VIDIOC_QUERYBUF` ioctl. @@ -575,7 +554,7 @@ differences. the incoming queue. Filled buffers are dequeued from the outgoing queue with the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. To wait until filled buffers become available this function, - :ref:`select() <func-select>` or :ref:`poll() <func-poll>` can + :c:func:`select()` or :c:func:`poll()` can be used. The :ref:`VIDIOC_STREAMON` ioctl must be called once after enqueuing one or more buffers to start capturing. Its counterpart @@ -584,11 +563,9 @@ differences. signal status, if known, with the :ref:`VIDIOC_ENUMINPUT` ioctl. - For a more in-depth discussion of memory mapping and examples, see :ref:`mmap`. - Reading Raw VBI Data ==================== @@ -599,7 +576,6 @@ the V4L VBI interface. Reading from the device yields a raw VBI image with the following parameters: - .. flat-table:: :header-rows: 1 :stub-columns: 0 @@ -623,7 +599,6 @@ with the following parameters: * - flags - 0 - Undocumented in the V4L specification, in Linux 2.3 the ``VIDIOCGVBIFMT`` and ``VIDIOCSVBIFMT`` ioctls using struct ``vbi_format`` were added to determine the VBI image @@ -637,11 +612,10 @@ remaining fields are probably equivalent to struct Apparently only the Zoran (ZR 36120) driver implements these ioctls. The semantics differ from those specified for V4L2 in two ways. The -parameters are reset on :ref:`open() <func-open>` and +parameters are reset on :c:func:`open()` and ``VIDIOCSVBIFMT`` always returns an ``EINVAL`` error code if the parameters are invalid. - Miscellaneous ============= diff --git a/Documentation/userspace-api/media/v4l/dmabuf.rst b/Documentation/userspace-api/media/v4l/dmabuf.rst index 342421ff9497..50fba11c2477 100644 --- a/Documentation/userspace-api/media/v4l/dmabuf.rst +++ b/Documentation/userspace-api/media/v4l/dmabuf.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _dmabuf: @@ -43,7 +37,6 @@ are passed in struct :c:type:`v4l2_buffer` (or in struct driver must be switched into DMABUF I/O mode by calling the :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>` with the desired buffer type. - Example: Initiating streaming I/O with DMABUF file descriptors ============================================================== @@ -142,10 +135,10 @@ buffers it must wait until an empty buffer can be dequeued and reused. Two methods exist to suspend execution of the application until one or more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the -``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` function, +``O_NONBLOCK`` flag was given to the :c:func:`open()` function, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN`` error code when no buffer is available. The -:ref:`select() <func-select>` and :ref:`poll() <func-poll>` +:c:func:`select()` and :c:func:`poll()` functions are always available. To start and stop capturing or displaying applications call the @@ -165,5 +158,5 @@ Drivers implementing DMABUF importing I/O must support the :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, -and the :ref:`select() <func-select>` and :ref:`poll() <func-poll>` +and the :c:func:`select()` and :c:func:`poll()` functions. diff --git a/Documentation/userspace-api/media/v4l/dv-timings.rst b/Documentation/userspace-api/media/v4l/dv-timings.rst index e216aa9edef0..4b19bcb4bd80 100644 --- a/Documentation/userspace-api/media/v4l/dv-timings.rst +++ b/Documentation/userspace-api/media/v4l/dv-timings.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _dv-timings: @@ -40,6 +33,27 @@ current DV timings they use the the DV timings as seen by the video receiver applications use the :ref:`VIDIOC_QUERY_DV_TIMINGS` ioctl. +When the hardware detects a video source change (e.g. the video +signal appears or disappears, or the video resolution changes), then +it will issue a `V4L2_EVENT_SOURCE_CHANGE` event. Use the +:ref:`ioctl VIDIOC_SUBSCRIBE_EVENT <VIDIOC_SUBSCRIBE_EVENT>` and the +:ref:`VIDIOC_DQEVENT` to check if this event was reported. + +If the video signal changed, then the application has to stop +streaming, free all buffers, and call the :ref:`VIDIOC_QUERY_DV_TIMINGS` +to obtain the new video timings, and if they are valid, it can set +those by calling the :ref:`ioctl VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>`. +This will also update the format, so use the :ref:`ioctl VIDIOC_G_FMT <VIDIOC_G_FMT>` +to obtain the new format. Now the application can allocate new buffers +and start streaming again. + +The :ref:`VIDIOC_QUERY_DV_TIMINGS` will just report what the +hardware detects, it will never change the configuration. If the +currently set timings and the actually detected timings differ, then +typically this will mean that you will not be able to capture any +video. The correct approach is to rely on the `V4L2_EVENT_SOURCE_CHANGE` +event so you know when something changed. + Applications can make use of the :ref:`input-capabilities` and :ref:`output-capabilities` flags to determine whether the digital video ioctls can be used with the given input or output. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst index d9a117f75c9c..cdc515c60468 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _camera-controls: @@ -39,6 +32,7 @@ enum v4l2_exposure_auto_type - should ignore such requests. Possible values are: +.. tabularcolumns:: |p{7.1cm}|p{10.4cm}| .. flat-table:: :header-rows: 0 @@ -88,7 +82,7 @@ enum v4l2_exposure_metering - Determines how the camera measures the amount of light available for the frame exposure. Possible values are: -.. tabularcolumns:: |p{8.7cm}|p{8.8cm}| +.. tabularcolumns:: |p{8.7cm}|p{8.7cm}| .. flat-table:: :header-rows: 0 @@ -180,7 +174,7 @@ enum v4l2_exposure_metering - control may stop updates of the ``V4L2_CID_AUTO_FOCUS_STATUS`` control value. -.. tabularcolumns:: |p{6.7cm}|p{10.8cm}| +.. tabularcolumns:: |p{6.8cm}|p{10.7cm}| .. flat-table:: :header-rows: 0 @@ -206,7 +200,7 @@ enum v4l2_exposure_metering - enum v4l2_auto_focus_range - Determines auto focus distance range for which lens may be adjusted. -.. tabularcolumns:: |p{6.8cm}|p{10.7cm}| +.. tabularcolumns:: |p{6.9cm}|p{10.6cm}| .. flat-table:: :header-rows: 0 @@ -281,7 +275,7 @@ enum v4l2_auto_n_preset_white_balance - representation. The following white balance presets are listed in order of increasing color temperature. -.. tabularcolumns:: |p{7.2 cm}|p{10.3cm}| +.. tabularcolumns:: |p{7.4cm}|p{10.1cm}| .. flat-table:: :header-rows: 0 @@ -391,7 +385,9 @@ enum v4l2_scene_mode - \small -.. tabularcolumns:: |p{5.9cm}|p{11.5cm}| +.. tabularcolumns:: |p{5.9cm}|p{11.6cm}| + +.. cssclass:: longtable .. flat-table:: :header-rows: 0 @@ -510,6 +506,8 @@ enum v4l2_scene_mode - value down. A value of zero stops the motion if one is in progress and has no effect otherwise. +.. _v4l2-camera-sensor-orientation: + ``V4L2_CID_CAMERA_ORIENTATION (menu)`` This read-only control describes the camera orientation by reporting its mounting position on the device where the camera is installed. The control @@ -526,6 +524,7 @@ enum v4l2_scene_mode - have the ``V4L2_CAMERA_ORIENTATION_EXTERNAL`` orientation. +.. tabularcolumns:: |p{7.7cm}|p{9.8cm}| .. flat-table:: :header-rows: 0 @@ -539,6 +538,7 @@ enum v4l2_scene_mode - - The camera is not directly attached to the device and is freely movable. +.. _v4l2-camera-sensor-rotation: ``V4L2_CID_CAMERA_SENSOR_ROTATION (integer)`` This read-only control describes the rotation correction in degrees in the @@ -664,3 +664,11 @@ enum v4l2_scene_mode - .. [#f1] This control may be changed to a menu control in the future, if more options are required. + +``V4L2_CID_HDR_SENSOR_MODE (menu)`` + Change the sensor HDR mode. A HDR picture is obtained by merging two + captures of the same scene using two different exposure periods. HDR mode + describes the way these two captures are merged in the sensor. + + As modes differ for each sensor, menu items are not standardized by this + control and are left to the programmer. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst new file mode 100644 index 000000000000..0da635691fdc --- /dev/null +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst @@ -0,0 +1,4168 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _codec-stateless-controls: + +********************************* +Stateless Codec Control Reference +********************************* + +The Stateless Codec control class is intended to support +stateless decoder and encoders (i.e. hardware accelerators). + +These drivers are typically supported by the :ref:`stateless_decoder`, +and deal with parsed pixel formats such as V4L2_PIX_FMT_H264_SLICE. + +Stateless Codec Control ID +========================== + +.. _codec-stateless-control-id: + +``V4L2_CID_CODEC_STATELESS_CLASS (class)`` + The Stateless Codec class descriptor. + +.. _v4l2-codec-stateless-h264: + +``V4L2_CID_STATELESS_H264_SPS (struct)`` + Specifies the sequence parameter set (as extracted from the + bitstream) for the associated H264 slice data. This includes the + necessary parameters for configuring a stateless hardware decoding + pipeline for H264. The bitstream parameters are defined according + to :ref:`h264`, section 7.4.2.1.1 "Sequence Parameter Set Data + Semantics". For further documentation, refer to the above + specification, unless there is an explicit comment stating + otherwise. + +.. c:type:: v4l2_ctrl_h264_sps + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.2cm}|p{8.6cm}|p{7.5cm}| + +.. flat-table:: struct v4l2_ctrl_h264_sps + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``profile_idc`` + - + * - __u8 + - ``constraint_set_flags`` + - See :ref:`Sequence Parameter Set Constraints Set Flags <h264_sps_constraints_set_flags>` + * - __u8 + - ``level_idc`` + - + * - __u8 + - ``seq_parameter_set_id`` + - + * - __u8 + - ``chroma_format_idc`` + - + * - __u8 + - ``bit_depth_luma_minus8`` + - + * - __u8 + - ``bit_depth_chroma_minus8`` + - + * - __u8 + - ``log2_max_frame_num_minus4`` + - + * - __u8 + - ``pic_order_cnt_type`` + - + * - __u8 + - ``log2_max_pic_order_cnt_lsb_minus4`` + - + * - __u8 + - ``max_num_ref_frames`` + - + * - __u8 + - ``num_ref_frames_in_pic_order_cnt_cycle`` + - + * - __s32 + - ``offset_for_ref_frame[255]`` + - + * - __s32 + - ``offset_for_non_ref_pic`` + - + * - __s32 + - ``offset_for_top_to_bottom_field`` + - + * - __u16 + - ``pic_width_in_mbs_minus1`` + - + * - __u16 + - ``pic_height_in_map_units_minus1`` + - + * - __u32 + - ``flags`` + - See :ref:`Sequence Parameter Set Flags <h264_sps_flags>` + +.. raw:: latex + + \normalsize + +.. _h264_sps_constraints_set_flags: + +``Sequence Parameter Set Constraints Set Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_SPS_CONSTRAINT_SET0_FLAG`` + - 0x00000001 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET1_FLAG`` + - 0x00000002 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET2_FLAG`` + - 0x00000004 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET3_FLAG`` + - 0x00000008 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET4_FLAG`` + - 0x00000010 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET5_FLAG`` + - 0x00000020 + - + +.. _h264_sps_flags: + +``Sequence Parameter Set Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_SPS_FLAG_SEPARATE_COLOUR_PLANE`` + - 0x00000001 + - + * - ``V4L2_H264_SPS_FLAG_QPPRIME_Y_ZERO_TRANSFORM_BYPASS`` + - 0x00000002 + - + * - ``V4L2_H264_SPS_FLAG_DELTA_PIC_ORDER_ALWAYS_ZERO`` + - 0x00000004 + - + * - ``V4L2_H264_SPS_FLAG_GAPS_IN_FRAME_NUM_VALUE_ALLOWED`` + - 0x00000008 + - + * - ``V4L2_H264_SPS_FLAG_FRAME_MBS_ONLY`` + - 0x00000010 + - + * - ``V4L2_H264_SPS_FLAG_MB_ADAPTIVE_FRAME_FIELD`` + - 0x00000020 + - + * - ``V4L2_H264_SPS_FLAG_DIRECT_8X8_INFERENCE`` + - 0x00000040 + - + +``V4L2_CID_STATELESS_H264_PPS (struct)`` + Specifies the picture parameter set (as extracted from the + bitstream) for the associated H264 slice data. This includes the + necessary parameters for configuring a stateless hardware decoding + pipeline for H264. The bitstream parameters are defined according + to :ref:`h264`, section 7.4.2.2 "Picture Parameter Set RBSP + Semantics". For further documentation, refer to the above + specification, unless there is an explicit comment stating + otherwise. + +.. c:type:: v4l2_ctrl_h264_pps + +.. raw:: latex + + \small + +.. flat-table:: struct v4l2_ctrl_h264_pps + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``pic_parameter_set_id`` + - + * - __u8 + - ``seq_parameter_set_id`` + - + * - __u8 + - ``num_slice_groups_minus1`` + - + * - __u8 + - ``num_ref_idx_l0_default_active_minus1`` + - + * - __u8 + - ``num_ref_idx_l1_default_active_minus1`` + - + * - __u8 + - ``weighted_bipred_idc`` + - + * - __s8 + - ``pic_init_qp_minus26`` + - + * - __s8 + - ``pic_init_qs_minus26`` + - + * - __s8 + - ``chroma_qp_index_offset`` + - + * - __s8 + - ``second_chroma_qp_index_offset`` + - + * - __u16 + - ``flags`` + - See :ref:`Picture Parameter Set Flags <h264_pps_flags>` + +.. raw:: latex + + \normalsize + +.. _h264_pps_flags: + +``Picture Parameter Set Flags`` + +.. raw:: latex + + \begingroup + \scriptsize + \setlength{\tabcolsep}{2pt} + +.. tabularcolumns:: |p{9.8cm}|p{1.0cm}|p{6.5cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 10 1 4 + + * - ``V4L2_H264_PPS_FLAG_ENTROPY_CODING_MODE`` + - 0x0001 + - + * - ``V4L2_H264_PPS_FLAG_BOTTOM_FIELD_PIC_ORDER_IN_FRAME_PRESENT`` + - 0x0002 + - + * - ``V4L2_H264_PPS_FLAG_WEIGHTED_PRED`` + - 0x0004 + - + * - ``V4L2_H264_PPS_FLAG_DEBLOCKING_FILTER_CONTROL_PRESENT`` + - 0x0008 + - + * - ``V4L2_H264_PPS_FLAG_CONSTRAINED_INTRA_PRED`` + - 0x0010 + - + * - ``V4L2_H264_PPS_FLAG_REDUNDANT_PIC_CNT_PRESENT`` + - 0x0020 + - + * - ``V4L2_H264_PPS_FLAG_TRANSFORM_8X8_MODE`` + - 0x0040 + - + * - ``V4L2_H264_PPS_FLAG_SCALING_MATRIX_PRESENT`` + - 0x0080 + - ``V4L2_CID_STATELESS_H264_SCALING_MATRIX`` + must be used for this picture. + +.. raw:: latex + + \endgroup + +``V4L2_CID_STATELESS_H264_SCALING_MATRIX (struct)`` + Specifies the scaling matrix (as extracted from the bitstream) for + the associated H264 slice data. The bitstream parameters are + defined according to :ref:`h264`, section 7.4.2.1.1.1 "Scaling + List Semantics". For further documentation, refer to the above + specification, unless there is an explicit comment stating + otherwise. + +.. c:type:: v4l2_ctrl_h264_scaling_matrix + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{0.6cm}|p{4.8cm}|p{11.9cm}| + +.. flat-table:: struct v4l2_ctrl_h264_scaling_matrix + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``scaling_list_4x4[6][16]`` + - Scaling matrix after applying the inverse scanning process. + Expected list order is Intra Y, Intra Cb, Intra Cr, Inter Y, + Inter Cb, Inter Cr. The values on each scaling list are + expected in raster scan order. + * - __u8 + - ``scaling_list_8x8[6][64]`` + - Scaling matrix after applying the inverse scanning process. + Expected list order is Intra Y, Inter Y, Intra Cb, Inter Cb, + Intra Cr, Inter Cr. The values on each scaling list are + expected in raster scan order. + +``V4L2_CID_STATELESS_H264_SLICE_PARAMS (struct)`` + Specifies the slice parameters (as extracted from the bitstream) + for the associated H264 slice data. This includes the necessary + parameters for configuring a stateless hardware decoding pipeline + for H264. The bitstream parameters are defined according to + :ref:`h264`, section 7.4.3 "Slice Header Semantics". For further + documentation, refer to the above specification, unless there is + an explicit comment stating otherwise. + +.. c:type:: v4l2_ctrl_h264_slice_params + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{4.0cm}|p{5.9cm}|p{7.4cm}| + +.. flat-table:: struct v4l2_ctrl_h264_slice_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``header_bit_size`` + - Offset in bits to slice_data() from the beginning of this slice. + * - __u32 + - ``first_mb_in_slice`` + - + * - __u8 + - ``slice_type`` + - + * - __u8 + - ``colour_plane_id`` + - + * - __u8 + - ``redundant_pic_cnt`` + - + * - __u8 + - ``cabac_init_idc`` + - + * - __s8 + - ``slice_qp_delta`` + - + * - __s8 + - ``slice_qs_delta`` + - + * - __u8 + - ``disable_deblocking_filter_idc`` + - + * - __s8 + - ``slice_alpha_c0_offset_div2`` + - + * - __s8 + - ``slice_beta_offset_div2`` + - + * - __u8 + - ``num_ref_idx_l0_active_minus1`` + - If num_ref_idx_active_override_flag is not set, this field must be + set to the value of num_ref_idx_l0_default_active_minus1 + * - __u8 + - ``num_ref_idx_l1_active_minus1`` + - If num_ref_idx_active_override_flag is not set, this field must be + set to the value of num_ref_idx_l1_default_active_minus1 + * - __u8 + - ``reserved`` + - Applications and drivers must set this to zero. + * - struct :c:type:`v4l2_h264_reference` + - ``ref_pic_list0[32]`` + - Reference picture list after applying the per-slice modifications + * - struct :c:type:`v4l2_h264_reference` + - ``ref_pic_list1[32]`` + - Reference picture list after applying the per-slice modifications + * - __u32 + - ``flags`` + - See :ref:`Slice Parameter Flags <h264_slice_flags>` + +.. raw:: latex + + \normalsize + +.. _h264_slice_flags: + +``Slice Parameter Set Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_SLICE_FLAG_DIRECT_SPATIAL_MV_PRED`` + - 0x00000001 + - + * - ``V4L2_H264_SLICE_FLAG_SP_FOR_SWITCH`` + - 0x00000002 + - + +``V4L2_CID_STATELESS_H264_PRED_WEIGHTS (struct)`` + Prediction weight table defined according to :ref:`h264`, + section 7.4.3.2 "Prediction Weight Table Semantics". + The prediction weight table must be passed by applications + under the conditions explained in section 7.3.3 "Slice header + syntax". + +.. c:type:: v4l2_ctrl_h264_pred_weights + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{4.9cm}|p{4.9cm}|p{7.5cm}| + +.. flat-table:: struct v4l2_ctrl_h264_pred_weights + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u16 + - ``luma_log2_weight_denom`` + - + * - __u16 + - ``chroma_log2_weight_denom`` + - + * - struct :c:type:`v4l2_h264_weight_factors` + - ``weight_factors[2]`` + - The weight factors at index 0 are the weight factors for the reference + list 0, the one at index 1 for the reference list 1. + +.. raw:: latex + + \normalsize + +.. c:type:: v4l2_h264_weight_factors + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.0cm}|p{4.5cm}|p{11.8cm}| + +.. flat-table:: struct v4l2_h264_weight_factors + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s16 + - ``luma_weight[32]`` + - + * - __s16 + - ``luma_offset[32]`` + - + * - __s16 + - ``chroma_weight[32][2]`` + - + * - __s16 + - ``chroma_offset[32][2]`` + - + +.. raw:: latex + + \normalsize + +``Picture Reference`` + +.. c:type:: v4l2_h264_reference + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_h264_reference + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``fields`` + - Specifies how the picture is referenced. See :ref:`Reference Fields <h264_ref_fields>` + * - __u8 + - ``index`` + - Index into the :c:type:`v4l2_ctrl_h264_decode_params`.dpb array. + +.. _h264_ref_fields: + +``Reference Fields`` + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{5.4cm}|p{0.8cm}|p{11.1cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_TOP_FIELD_REF`` + - 0x1 + - The top field in field pair is used for short-term reference. + * - ``V4L2_H264_BOTTOM_FIELD_REF`` + - 0x2 + - The bottom field in field pair is used for short-term reference. + * - ``V4L2_H264_FRAME_REF`` + - 0x3 + - The frame (or the top/bottom fields, if it's a field pair) + is used for short-term reference. + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_H264_DECODE_PARAMS (struct)`` + Specifies the decode parameters (as extracted from the bitstream) + for the associated H264 slice data. This includes the necessary + parameters for configuring a stateless hardware decoding pipeline + for H264. The bitstream parameters are defined according to + :ref:`h264`. For further documentation, refer to the above + specification, unless there is an explicit comment stating + otherwise. + +.. c:type:: v4l2_ctrl_h264_decode_params + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{4.0cm}|p{5.9cm}|p{7.4cm}| + +.. flat-table:: struct v4l2_ctrl_h264_decode_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - struct :c:type:`v4l2_h264_dpb_entry` + - ``dpb[16]`` + - + * - __u16 + - ``nal_ref_idc`` + - NAL reference ID value coming from the NAL Unit header + * - __u16 + - ``frame_num`` + - + * - __s32 + - ``top_field_order_cnt`` + - Picture Order Count for the coded top field + * - __s32 + - ``bottom_field_order_cnt`` + - Picture Order Count for the coded bottom field + * - __u16 + - ``idr_pic_id`` + - + * - __u16 + - ``pic_order_cnt_lsb`` + - + * - __s32 + - ``delta_pic_order_cnt_bottom`` + - + * - __s32 + - ``delta_pic_order_cnt0`` + - + * - __s32 + - ``delta_pic_order_cnt1`` + - + * - __u32 + - ``dec_ref_pic_marking_bit_size`` + - Size in bits of the dec_ref_pic_marking() syntax element. + * - __u32 + - ``pic_order_cnt_bit_size`` + - Combined size in bits of the picture order count related syntax + elements: pic_order_cnt_lsb, delta_pic_order_cnt_bottom, + delta_pic_order_cnt0, and delta_pic_order_cnt1. + * - __u32 + - ``slice_group_change_cycle`` + - + * - __u32 + - ``reserved`` + - Applications and drivers must set this to zero. + * - __u32 + - ``flags`` + - See :ref:`Decode Parameters Flags <h264_decode_params_flags>` + +.. raw:: latex + + \normalsize + +.. _h264_decode_params_flags: + +``Decode Parameters Flags`` + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{8.3cm}|p{2.1cm}|p{6.9cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_DECODE_PARAM_FLAG_IDR_PIC`` + - 0x00000001 + - That picture is an IDR picture + * - ``V4L2_H264_DECODE_PARAM_FLAG_FIELD_PIC`` + - 0x00000002 + - + * - ``V4L2_H264_DECODE_PARAM_FLAG_BOTTOM_FIELD`` + - 0x00000004 + - + * - ``V4L2_H264_DECODE_PARAM_FLAG_PFRAME`` + - 0x00000008 + - + * - ``V4L2_H264_DECODE_PARAM_FLAG_BFRAME`` + - 0x00000010 + - + +.. raw:: latex + + \normalsize + +.. c:type:: v4l2_h264_dpb_entry + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.0cm}|p{4.9cm}|p{11.4cm}| + +.. flat-table:: struct v4l2_h264_dpb_entry + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u64 + - ``reference_ts`` + - Timestamp of the V4L2 capture buffer to use as reference, used + with B-coded and P-coded frames. The timestamp refers to the + ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the + :c:func:`v4l2_timeval_to_ns()` function to convert the struct + :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. + * - __u32 + - ``pic_num`` + - For short term references, this must match the derived value PicNum + (8-28) and for long term references it must match the derived value + LongTermPicNum (8-29). When decoding frames (as opposed to fields) + pic_num is the same as FrameNumWrap. + * - __u16 + - ``frame_num`` + - For short term references, this must match the frame_num value from + the slice header syntax (the driver will wrap the value if needed). For + long term references, this must be set to the value of + long_term_frame_idx described in the dec_ref_pic_marking() syntax. + * - __u8 + - ``fields`` + - Specifies how the DPB entry is referenced. See :ref:`Reference Fields <h264_ref_fields>` + * - __u8 + - ``reserved[5]`` + - Applications and drivers must set this to zero. + * - __s32 + - ``top_field_order_cnt`` + - + * - __s32 + - ``bottom_field_order_cnt`` + - + * - __u32 + - ``flags`` + - See :ref:`DPB Entry Flags <h264_dpb_flags>` + +.. raw:: latex + + \normalsize + +.. _h264_dpb_flags: + +``DPB Entries Flags`` + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{7.7cm}|p{2.1cm}|p{7.5cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_DPB_ENTRY_FLAG_VALID`` + - 0x00000001 + - The DPB entry is valid (non-empty) and should be considered. + * - ``V4L2_H264_DPB_ENTRY_FLAG_ACTIVE`` + - 0x00000002 + - The DPB entry is used for reference. + * - ``V4L2_H264_DPB_ENTRY_FLAG_LONG_TERM`` + - 0x00000004 + - The DPB entry is used for long-term reference. + * - ``V4L2_H264_DPB_ENTRY_FLAG_FIELD`` + - 0x00000008 + - The DPB entry is a single field or a complementary field pair. + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_H264_DECODE_MODE (enum)`` + Specifies the decoding mode to use. Currently exposes slice-based and + frame-based decoding but new modes might be added later on. + This control is used as a modifier for V4L2_PIX_FMT_H264_SLICE + pixel format. Applications that support V4L2_PIX_FMT_H264_SLICE + are required to set this control in order to specify the decoding mode + that is expected for the buffer. + Drivers may expose a single or multiple decoding modes, depending + on what they can support. + +.. c:type:: v4l2_stateless_h264_decode_mode + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_STATELESS_H264_DECODE_MODE_SLICE_BASED`` + - 0 + - Decoding is done at the slice granularity. + The OUTPUT buffer must contain a single slice. + When this mode is selected, the ``V4L2_CID_STATELESS_H264_SLICE_PARAMS`` + control shall be set. When multiple slices compose a frame, + use of ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` flag + is required. + * - ``V4L2_STATELESS_H264_DECODE_MODE_FRAME_BASED`` + - 1 + - Decoding is done at the frame granularity, + The OUTPUT buffer must contain all slices needed to decode the + frame. The OUTPUT buffer must also contain both fields. + This mode will be supported by devices that + parse the slice(s) header(s) in hardware. When this mode is + selected, the ``V4L2_CID_STATELESS_H264_SLICE_PARAMS`` + control shall not be set. + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_H264_START_CODE (enum)`` + Specifies the H264 slice start code expected for each slice. + This control is used as a modifier for V4L2_PIX_FMT_H264_SLICE + pixel format. Applications that support V4L2_PIX_FMT_H264_SLICE + are required to set this control in order to specify the start code + that is expected for the buffer. + Drivers may expose a single or multiple start codes, depending + on what they can support. + +.. c:type:: v4l2_stateless_h264_start_code + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{7.9cm}|p{0.4cm}|p{9.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 4 1 4 + + * - ``V4L2_STATELESS_H264_START_CODE_NONE`` + - 0 + - Selecting this value specifies that H264 slices are passed + to the driver without any start code. The bitstream data should be + according to :ref:`h264` 7.3.1 NAL unit syntax, hence contains + emulation prevention bytes when required. + * - ``V4L2_STATELESS_H264_START_CODE_ANNEX_B`` + - 1 + - Selecting this value specifies that H264 slices are expected + to be prefixed by Annex B start codes. According to :ref:`h264` + valid start codes can be 3-bytes 0x000001 or 4-bytes 0x00000001. + +.. raw:: latex + + \normalsize + +.. _codec-stateless-fwht: + +``V4L2_CID_STATELESS_FWHT_PARAMS (struct)`` + Specifies the FWHT (Fast Walsh Hadamard Transform) parameters (as extracted + from the bitstream) for the associated FWHT data. This includes the necessary + parameters for configuring a stateless hardware decoding pipeline for FWHT. + This codec is specific to the vicodec test driver. + +.. c:type:: v4l2_ctrl_fwht_params + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.4cm}|p{3.9cm}|p{12.0cm}| + +.. flat-table:: struct v4l2_ctrl_fwht_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u64 + - ``backward_ref_ts`` + - Timestamp of the V4L2 capture buffer to use as backward reference, used + with P-coded frames. The timestamp refers to the + ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the + :c:func:`v4l2_timeval_to_ns()` function to convert the struct + :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. + * - __u32 + - ``version`` + - The version of the codec. Set to ``V4L2_FWHT_VERSION``. + * - __u32 + - ``width`` + - The width of the frame. + * - __u32 + - ``height`` + - The height of the frame. + * - __u32 + - ``flags`` + - The flags of the frame, see :ref:`fwht-flags`. + * - __u32 + - ``colorspace`` + - The colorspace of the frame, from enum :c:type:`v4l2_colorspace`. + * - __u32 + - ``xfer_func`` + - The transfer function, from enum :c:type:`v4l2_xfer_func`. + * - __u32 + - ``ycbcr_enc`` + - The Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`. + * - __u32 + - ``quantization`` + - The quantization range, from enum :c:type:`v4l2_quantization`. + +.. raw:: latex + + \normalsize + +.. _fwht-flags: + +FWHT Flags +========== + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{7.0cm}|p{2.3cm}|p{8.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - ``V4L2_FWHT_FL_IS_INTERLACED`` + - 0x00000001 + - Set if this is an interlaced format. + * - ``V4L2_FWHT_FL_IS_BOTTOM_FIRST`` + - 0x00000002 + - Set if this is a bottom-first (NTSC) interlaced format. + * - ``V4L2_FWHT_FL_IS_ALTERNATE`` + - 0x00000004 + - Set if each 'frame' contains just one field. + * - ``V4L2_FWHT_FL_IS_BOTTOM_FIELD`` + - 0x00000008 + - If V4L2_FWHT_FL_IS_ALTERNATE was set, then this is set if this 'frame' is the + bottom field, else it is the top field. + * - ``V4L2_FWHT_FL_LUMA_IS_UNCOMPRESSED`` + - 0x00000010 + - Set if the Y' (luma) plane is uncompressed. + * - ``V4L2_FWHT_FL_CB_IS_UNCOMPRESSED`` + - 0x00000020 + - Set if the Cb plane is uncompressed. + * - ``V4L2_FWHT_FL_CR_IS_UNCOMPRESSED`` + - 0x00000040 + - Set if the Cr plane is uncompressed. + * - ``V4L2_FWHT_FL_CHROMA_FULL_HEIGHT`` + - 0x00000080 + - Set if the chroma plane has the same height as the luma plane, + else the chroma plane is half the height of the luma plane. + * - ``V4L2_FWHT_FL_CHROMA_FULL_WIDTH`` + - 0x00000100 + - Set if the chroma plane has the same width as the luma plane, + else the chroma plane is half the width of the luma plane. + * - ``V4L2_FWHT_FL_ALPHA_IS_UNCOMPRESSED`` + - 0x00000200 + - Set if the alpha plane is uncompressed. + * - ``V4L2_FWHT_FL_I_FRAME`` + - 0x00000400 + - Set if this is an I-frame. + * - ``V4L2_FWHT_FL_COMPONENTS_NUM_MSK`` + - 0x00070000 + - The number of color components minus one. + * - ``V4L2_FWHT_FL_PIXENC_MSK`` + - 0x00180000 + - The mask for the pixel encoding. + * - ``V4L2_FWHT_FL_PIXENC_YUV`` + - 0x00080000 + - Set if the pixel encoding is YUV. + * - ``V4L2_FWHT_FL_PIXENC_RGB`` + - 0x00100000 + - Set if the pixel encoding is RGB. + * - ``V4L2_FWHT_FL_PIXENC_HSV`` + - 0x00180000 + - Set if the pixel encoding is HSV. + +.. raw:: latex + + \normalsize + +.. _v4l2-codec-stateless-vp8: + +``V4L2_CID_STATELESS_VP8_FRAME (struct)`` + Specifies the frame parameters for the associated VP8 parsed frame data. + This includes the necessary parameters for + configuring a stateless hardware decoding pipeline for VP8. + The bitstream parameters are defined according to :ref:`vp8`. + +.. c:type:: v4l2_ctrl_vp8_frame + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{7.0cm}|p{4.6cm}|p{5.7cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_vp8_frame + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - struct :c:type:`v4l2_vp8_segment` + - ``segment`` + - Structure with segment-based adjustments metadata. + * - struct :c:type:`v4l2_vp8_loop_filter` + - ``lf`` + - Structure with loop filter level adjustments metadata. + * - struct :c:type:`v4l2_vp8_quantization` + - ``quant`` + - Structure with VP8 dequantization indices metadata. + * - struct :c:type:`v4l2_vp8_entropy` + - ``entropy`` + - Structure with VP8 entropy coder probabilities metadata. + * - struct :c:type:`v4l2_vp8_entropy_coder_state` + - ``coder_state`` + - Structure with VP8 entropy coder state. + * - __u16 + - ``width`` + - The width of the frame. Must be set for all frames. + * - __u16 + - ``height`` + - The height of the frame. Must be set for all frames. + * - __u8 + - ``horizontal_scale`` + - Horizontal scaling factor. + * - __u8 + - ``vertical_scale`` + - Vertical scaling factor. + * - __u8 + - ``version`` + - Bitstream version. + * - __u8 + - ``prob_skip_false`` + - Indicates the probability that the macroblock is not skipped. + * - __u8 + - ``prob_intra`` + - Indicates the probability that a macroblock is intra-predicted. + * - __u8 + - ``prob_last`` + - Indicates the probability that the last reference frame is used + for inter-prediction + * - __u8 + - ``prob_gf`` + - Indicates the probability that the golden reference frame is used + for inter-prediction + * - __u8 + - ``num_dct_parts`` + - Number of DCT coefficients partitions. Must be one of: 1, 2, 4, or 8. + * - __u32 + - ``first_part_size`` + - Size of the first partition, i.e. the control partition. + * - __u32 + - ``first_part_header_bits`` + - Size in bits of the first partition header portion. + * - __u32 + - ``dct_part_sizes[8]`` + - DCT coefficients sizes. + * - __u64 + - ``last_frame_ts`` + - Timestamp for the V4L2 capture buffer to use as last reference frame, used + with inter-coded frames. The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u64 + - ``golden_frame_ts`` + - Timestamp for the V4L2 capture buffer to use as last reference frame, used + with inter-coded frames. The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u64 + - ``alt_frame_ts`` + - Timestamp for the V4L2 capture buffer to use as alternate reference frame, used + with inter-coded frames. The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u64 + - ``flags`` + - See :ref:`Frame Flags <vp8_frame_flags>` + +.. raw:: latex + + \normalsize + +.. _vp8_frame_flags: + +``Frame Flags`` + +.. tabularcolumns:: |p{9.8cm}|p{0.8cm}|p{6.7cm}| + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP8_FRAME_FLAG_KEY_FRAME`` + - 0x01 + - Indicates if the frame is a key frame. + * - ``V4L2_VP8_FRAME_FLAG_EXPERIMENTAL`` + - 0x02 + - Experimental bitstream. + * - ``V4L2_VP8_FRAME_FLAG_SHOW_FRAME`` + - 0x04 + - Show frame flag, indicates if the frame is for display. + * - ``V4L2_VP8_FRAME_FLAG_MB_NO_SKIP_COEFF`` + - 0x08 + - Enable/disable skipping of macroblocks with no non-zero coefficients. + * - ``V4L2_VP8_FRAME_FLAG_SIGN_BIAS_GOLDEN`` + - 0x10 + - Sign of motion vectors when the golden frame is referenced. + * - ``V4L2_VP8_FRAME_FLAG_SIGN_BIAS_ALT`` + - 0x20 + - Sign of motion vectors when the alt frame is referenced. + +.. c:type:: v4l2_vp8_entropy_coder_state + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.3cm}| + +.. flat-table:: struct v4l2_vp8_entropy_coder_state + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``range`` + - coder state value for "Range" + * - __u8 + - ``value`` + - coder state value for "Value"- + * - __u8 + - ``bit_count`` + - number of bits left. + * - __u8 + - ``padding`` + - Applications and drivers must set this to zero. + +.. c:type:: v4l2_vp8_segment + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.2cm}|p{4.0cm}|p{12.1cm}| + +.. flat-table:: struct v4l2_vp8_segment + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s8 + - ``quant_update[4]`` + - Signed quantizer value update. + * - __s8 + - ``lf_update[4]`` + - Signed loop filter level value update. + * - __u8 + - ``segment_probs[3]`` + - Segment probabilities. + * - __u8 + - ``padding`` + - Applications and drivers must set this to zero. + * - __u32 + - ``flags`` + - See :ref:`Segment Flags <vp8_segment_flags>` + +.. _vp8_segment_flags: + +``Segment Flags`` + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{10cm}|p{1.0cm}|p{6.3cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP8_SEGMENT_FLAG_ENABLED`` + - 0x01 + - Enable/disable segment-based adjustments. + * - ``V4L2_VP8_SEGMENT_FLAG_UPDATE_MAP`` + - 0x02 + - Indicates if the macroblock segmentation map is updated in this frame. + * - ``V4L2_VP8_SEGMENT_FLAG_UPDATE_FEATURE_DATA`` + - 0x04 + - Indicates if the segment feature data is updated in this frame. + * - ``V4L2_VP8_SEGMENT_FLAG_DELTA_VALUE_MODE`` + - 0x08 + - If is set, the segment feature data mode is delta-value. + If cleared, it's absolute-value. + +.. raw:: latex + + \normalsize + +.. c:type:: v4l2_vp8_loop_filter + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{3.9cm}|p{11.9cm}| + +.. flat-table:: struct v4l2_vp8_loop_filter + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s8 + - ``ref_frm_delta[4]`` + - Reference adjustment (signed) delta value. + * - __s8 + - ``mb_mode_delta[4]`` + - Macroblock prediction mode adjustment (signed) delta value. + * - __u8 + - ``sharpness_level`` + - Sharpness level + * - __u8 + - ``level`` + - Filter level + * - __u16 + - ``padding`` + - Applications and drivers must set this to zero. + * - __u32 + - ``flags`` + - See :ref:`Loop Filter Flags <vp8_loop_filter_flags>` + +.. _vp8_loop_filter_flags: + +``Loop Filter Flags`` + +.. tabularcolumns:: |p{7.0cm}|p{1.2cm}|p{9.1cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP8_LF_ADJ_ENABLE`` + - 0x01 + - Enable/disable macroblock-level loop filter adjustment. + * - ``V4L2_VP8_LF_DELTA_UPDATE`` + - 0x02 + - Indicates if the delta values used in an adjustment are updated. + * - ``V4L2_VP8_LF_FILTER_TYPE_SIMPLE`` + - 0x04 + - If set, indicates the filter type is simple. + If cleared, the filter type is normal. + +.. c:type:: v4l2_vp8_quantization + +.. tabularcolumns:: |p{1.5cm}|p{3.5cm}|p{12.3cm}| + +.. flat-table:: struct v4l2_vp8_quantization + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``y_ac_qi`` + - Luma AC coefficient table index. + * - __s8 + - ``y_dc_delta`` + - Luma DC delta value. + * - __s8 + - ``y2_dc_delta`` + - Y2 block DC delta value. + * - __s8 + - ``y2_ac_delta`` + - Y2 block AC delta value. + * - __s8 + - ``uv_dc_delta`` + - Chroma DC delta value. + * - __s8 + - ``uv_ac_delta`` + - Chroma AC delta value. + * - __u16 + - ``padding`` + - Applications and drivers must set this to zero. + +.. c:type:: v4l2_vp8_entropy + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_vp8_entropy + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``coeff_probs[4][8][3][11]`` + - Coefficient update probabilities. + * - __u8 + - ``y_mode_probs[4]`` + - Luma mode update probabilities. + * - __u8 + - ``uv_mode_probs[3]`` + - Chroma mode update probabilities. + * - __u8 + - ``mv_probs[2][19]`` + - MV decoding update probabilities. + * - __u8 + - ``padding[3]`` + - Applications and drivers must set this to zero. + +.. _v4l2-codec-stateless-mpeg2: + +``V4L2_CID_STATELESS_MPEG2_SEQUENCE (struct)`` + Specifies the sequence parameters (as extracted from the bitstream) for the + associated MPEG-2 slice data. This includes fields matching the syntax + elements from the sequence header and sequence extension parts of the + bitstream as specified by :ref:`mpeg2part2`. + +.. c:type:: v4l2_ctrl_mpeg2_sequence + +.. raw:: latex + + \small + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.4cm}|p{6.5cm}|p{9.4cm}| + +.. flat-table:: struct v4l2_ctrl_mpeg2_sequence + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u16 + - ``horizontal_size`` + - The width of the displayable part of the frame's luminance component. + * - __u16 + - ``vertical_size`` + - The height of the displayable part of the frame's luminance component. + * - __u32 + - ``vbv_buffer_size`` + - Used to calculate the required size of the video buffering verifier, + defined (in bits) as: 16 * 1024 * vbv_buffer_size. + * - __u16 + - ``profile_and_level_indication`` + - The current profile and level indication as extracted from the + bitstream. + * - __u8 + - ``chroma_format`` + - The chrominance sub-sampling format (1: 4:2:0, 2: 4:2:2, 3: 4:4:4). + * - __u8 + - ``flags`` + - See :ref:`MPEG-2 Sequence Flags <mpeg2_sequence_flags>`. + +.. _mpeg2_sequence_flags: + +``MPEG-2 Sequence Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_MPEG2_SEQ_FLAG_PROGRESSIVE`` + - 0x01 + - Indication that all the frames for the sequence are progressive instead + of interlaced. + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_MPEG2_PICTURE (struct)`` + Specifies the picture parameters (as extracted from the bitstream) for the + associated MPEG-2 slice data. This includes fields matching the syntax + elements from the picture header and picture coding extension parts of the + bitstream as specified by :ref:`mpeg2part2`. + +.. c:type:: v4l2_ctrl_mpeg2_picture + +.. raw:: latex + + \small + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.0cm}|p{5.6cm}|p{10.7cm}| + +.. flat-table:: struct v4l2_ctrl_mpeg2_picture + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u64 + - ``backward_ref_ts`` + - Timestamp of the V4L2 capture buffer to use as backward reference, used + with B-coded and P-coded frames. The timestamp refers to the + ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the + :c:func:`v4l2_timeval_to_ns()` function to convert the struct + :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. + * - __u64 + - ``forward_ref_ts`` + - Timestamp for the V4L2 capture buffer to use as forward reference, used + with B-coded frames. The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u32 + - ``flags`` + - See :ref:`MPEG-2 Picture Flags <mpeg2_picture_flags>`. + * - __u8 + - ``f_code[2][2]`` + - Motion vector codes. + * - __u8 + - ``picture_coding_type`` + - Picture coding type for the frame covered by the current slice + (V4L2_MPEG2_PIC_CODING_TYPE_I, V4L2_MPEG2_PIC_CODING_TYPE_P or + V4L2_MPEG2_PIC_CODING_TYPE_B). + * - __u8 + - ``picture_structure`` + - Picture structure (1: interlaced top field, 2: interlaced bottom field, + 3: progressive frame). + * - __u8 + - ``intra_dc_precision`` + - Precision of Discrete Cosine transform (0: 8 bits precision, + 1: 9 bits precision, 2: 10 bits precision, 3: 11 bits precision). + * - __u8 + - ``reserved[5]`` + - Applications and drivers must set this to zero. + +.. _mpeg2_picture_flags: + +``MPEG-2 Picture Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_MPEG2_PIC_FLAG_TOP_FIELD_FIRST`` + - 0x00000001 + - If set and it's an interlaced stream, top field is output first. + * - ``V4L2_MPEG2_PIC_FLAG_FRAME_PRED_DCT`` + - 0x00000002 + - If set only frame-DCT and frame prediction are used. + * - ``V4L2_MPEG2_PIC_FLAG_CONCEALMENT_MV`` + - 0x00000004 + - If set motion vectors are coded for intra macroblocks. + * - ``V4L2_MPEG2_PIC_FLAG_Q_SCALE_TYPE`` + - 0x00000008 + - This flag affects the inverse quantization process. + * - ``V4L2_MPEG2_PIC_FLAG_INTRA_VLC`` + - 0x00000010 + - This flag affects the decoding of transform coefficient data. + * - ``V4L2_MPEG2_PIC_FLAG_ALT_SCAN`` + - 0x00000020 + - This flag affects the decoding of transform coefficient data. + * - ``V4L2_MPEG2_PIC_FLAG_REPEAT_FIRST`` + - 0x00000040 + - This flag affects the decoding process of progressive frames. + * - ``V4L2_MPEG2_PIC_FLAG_PROGRESSIVE`` + - 0x00000080 + - Indicates whether the current frame is progressive. + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_MPEG2_QUANTISATION (struct)`` + Specifies quantisation matrices, in zigzag scanning order, for the + associated MPEG-2 slice data. This control is initialized by the kernel + to the matrices default values. If a bitstream transmits a user-defined + quantisation matrices load, applications are expected to use this control. + Applications are also expected to set the control loading the default + values, if the quantisation matrices need to be reset, for instance on a + sequence header. This process is specified by section 6.3.7. + "Quant matrix extension" of the specification. + +.. c:type:: v4l2_ctrl_mpeg2_quantisation + +.. tabularcolumns:: |p{0.8cm}|p{8.0cm}|p{8.5cm}| + +.. cssclass:: longtable + +.. raw:: latex + + \small + +.. flat-table:: struct v4l2_ctrl_mpeg2_quantisation + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``intra_quantiser_matrix[64]`` + - The quantisation matrix coefficients for intra-coded frames, in zigzag + scanning order. It is relevant for both luma and chroma components, + although it can be superseded by the chroma-specific matrix for + non-4:2:0 YUV formats. + * - __u8 + - ``non_intra_quantiser_matrix[64]`` + - The quantisation matrix coefficients for non-intra-coded frames, in + zigzag scanning order. It is relevant for both luma and chroma + components, although it can be superseded by the chroma-specific matrix + for non-4:2:0 YUV formats. + * - __u8 + - ``chroma_intra_quantiser_matrix[64]`` + - The quantisation matrix coefficients for the chominance component of + intra-coded frames, in zigzag scanning order. Only relevant for + non-4:2:0 YUV formats. + * - __u8 + - ``chroma_non_intra_quantiser_matrix[64]`` + - The quantisation matrix coefficients for the chrominance component of + non-intra-coded frames, in zigzag scanning order. Only relevant for + non-4:2:0 YUV formats. + +.. raw:: latex + + \normalsize + +.. _v4l2-codec-stateless-vp9: + +``V4L2_CID_STATELESS_VP9_COMPRESSED_HDR (struct)`` + Stores VP9 probabilities updates as parsed from the current compressed frame + header. A value of zero in an array element means no update of the relevant + probability. Motion vector-related updates contain a new value or zero. All + other updates contain values translated with inv_map_table[] (see 6.3.5 in + :ref:`vp9`). + +.. c:type:: v4l2_ctrl_vp9_compressed_hdr + +.. tabularcolumns:: |p{1cm}|p{4.8cm}|p{11.4cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_vp9_compressed_hdr + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``tx_mode`` + - Specifies the TX mode. See :ref:`TX Mode <vp9_tx_mode>` for more details. + * - __u8 + - ``tx8[2][1]`` + - TX 8x8 probabilities delta. + * - __u8 + - ``tx16[2][2]`` + - TX 16x16 probabilities delta. + * - __u8 + - ``tx32[2][3]`` + - TX 32x32 probabilities delta. + * - __u8 + - ``coef[4][2][2][6][6][3]`` + - Coefficient probabilities delta. + * - __u8 + - ``skip[3]`` + - Skip probabilities delta. + * - __u8 + - ``inter_mode[7][3]`` + - Inter prediction mode probabilities delta. + * - __u8 + - ``interp_filter[4][2]`` + - Interpolation filter probabilities delta. + * - __u8 + - ``is_inter[4]`` + - Is inter-block probabilities delta. + * - __u8 + - ``comp_mode[5]`` + - Compound prediction mode probabilities delta. + * - __u8 + - ``single_ref[5][2]`` + - Single reference probabilities delta. + * - __u8 + - ``comp_ref[5]`` + - Compound reference probabilities delta. + * - __u8 + - ``y_mode[4][9]`` + - Y prediction mode probabilities delta. + * - __u8 + - ``uv_mode[10][9]`` + - UV prediction mode probabilities delta. + * - __u8 + - ``partition[16][3]`` + - Partition probabilities delta. + * - __u8 + - ``mv.joint[3]`` + - Motion vector joint probabilities delta. + * - __u8 + - ``mv.sign[2]`` + - Motion vector sign probabilities delta. + * - __u8 + - ``mv.classes[2][10]`` + - Motion vector class probabilities delta. + * - __u8 + - ``mv.class0_bit[2]`` + - Motion vector class0 bit probabilities delta. + * - __u8 + - ``mv.bits[2][10]`` + - Motion vector bits probabilities delta. + * - __u8 + - ``mv.class0_fr[2][2][3]`` + - Motion vector class0 fractional bit probabilities delta. + * - __u8 + - ``mv.fr[2][3]`` + - Motion vector fractional bit probabilities delta. + * - __u8 + - ``mv.class0_hp[2]`` + - Motion vector class0 high precision fractional bit probabilities delta. + * - __u8 + - ``mv.hp[2]`` + - Motion vector high precision fractional bit probabilities delta. + +.. _vp9_tx_mode: + +``TX Mode`` + +.. tabularcolumns:: |p{6.5cm}|p{0.5cm}|p{10.3cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_TX_MODE_ONLY_4X4`` + - 0 + - Transform size is 4x4. + * - ``V4L2_VP9_TX_MODE_ALLOW_8X8`` + - 1 + - Transform size can be up to 8x8. + * - ``V4L2_VP9_TX_MODE_ALLOW_16X16`` + - 2 + - Transform size can be up to 16x16. + * - ``V4L2_VP9_TX_MODE_ALLOW_32X32`` + - 3 + - transform size can be up to 32x32. + * - ``V4L2_VP9_TX_MODE_SELECT`` + - 4 + - Bitstream contains the transform size for each block. + +See section '7.3.1 Tx mode semantics' of the :ref:`vp9` specification for more details. + +``V4L2_CID_STATELESS_VP9_FRAME (struct)`` + Specifies the frame parameters for the associated VP9 frame decode request. + This includes the necessary parameters for configuring a stateless hardware + decoding pipeline for VP9. The bitstream parameters are defined according + to :ref:`vp9`. + +.. c:type:: v4l2_ctrl_vp9_frame + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{4.7cm}|p{5.5cm}|p{7.1cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_vp9_frame + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - struct :c:type:`v4l2_vp9_loop_filter` + - ``lf`` + - Loop filter parameters. See struct :c:type:`v4l2_vp9_loop_filter` for more details. + * - struct :c:type:`v4l2_vp9_quantization` + - ``quant`` + - Quantization parameters. See :c:type:`v4l2_vp9_quantization` for more details. + * - struct :c:type:`v4l2_vp9_segmentation` + - ``seg`` + - Segmentation parameters. See :c:type:`v4l2_vp9_segmentation` for more details. + * - __u32 + - ``flags`` + - Combination of V4L2_VP9_FRAME_FLAG_* flags. See :ref:`Frame Flags<vp9_frame_flags>`. + * - __u16 + - ``compressed_header_size`` + - Compressed header size in bytes. + * - __u16 + - ``uncompressed_header_size`` + - Uncompressed header size in bytes. + * - __u16 + - ``frame_width_minus_1`` + - Add 1 to get the frame width expressed in pixels. See section 7.2.3 in :ref:`vp9`. + * - __u16 + - ``frame_height_minus_1`` + - Add 1 to get the frame height expressed in pixels. See section 7.2.3 in :ref:`vp9`. + * - __u16 + - ``render_width_minus_1`` + - Add 1 to get the expected render width expressed in pixels. This is + not used during the decoding process but might be used by HW scalers to + prepare a frame that's ready for scanout. See section 7.2.4 in :ref:`vp9`. + * - __u16 + - render_height_minus_1 + - Add 1 to get the expected render height expressed in pixels. This is + not used during the decoding process but might be used by HW scalers to + prepare a frame that's ready for scanout. See section 7.2.4 in :ref:`vp9`. + * - __u64 + - ``last_frame_ts`` + - "last" reference buffer timestamp. + The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u64 + - ``golden_frame_ts`` + - "golden" reference buffer timestamp. + The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u64 + - ``alt_frame_ts`` + - "alt" reference buffer timestamp. + The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u8 + - ``ref_frame_sign_bias`` + - a bitfield specifying whether the sign bias is set for a given + reference frame. See :ref:`Reference Frame Sign Bias<vp9_ref_frame_sign_bias>` + for more details. + * - __u8 + - ``reset_frame_context`` + - specifies whether the frame context should be reset to default values. See + :ref:`Reset Frame Context<vp9_reset_frame_context>` for more details. + * - __u8 + - ``frame_context_idx`` + - Frame context that should be used/updated. + * - __u8 + - ``profile`` + - VP9 profile. Can be 0, 1, 2 or 3. + * - __u8 + - ``bit_depth`` + - Component depth in bits. Can be 8, 10 or 12. Note that not all profiles + support 10 and/or 12 bits depths. + * - __u8 + - ``interpolation_filter`` + - Specifies the filter selection used for performing inter prediction. See + :ref:`Interpolation Filter<vp9_interpolation_filter>` for more details. + * - __u8 + - ``tile_cols_log2`` + - Specifies the base 2 logarithm of the width of each tile (where the + width is measured in units of 8x8 blocks). Shall be less than or equal + to 6. + * - __u8 + - ``tile_rows_log2`` + - Specifies the base 2 logarithm of the height of each tile (where the + height is measured in units of 8x8 blocks). + * - __u8 + - ``reference_mode`` + - Specifies the type of inter prediction to be used. See + :ref:`Reference Mode<vp9_reference_mode>` for more details. Note that + this is derived as part of the compressed header parsing process and + for this reason should have been part of + :c:type: `v4l2_ctrl_vp9_compressed_hdr` optional control. It is safe to + set this value to zero if the driver does not require compressed + headers. + * - __u8 + - ``reserved[7]`` + - Applications and drivers must set this to zero. + +.. raw:: latex + + \normalsize + +.. _vp9_frame_flags: + +``Frame Flags`` + +.. tabularcolumns:: |p{10.0cm}|p{1.2cm}|p{6.1cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_FRAME_FLAG_KEY_FRAME`` + - 0x001 + - The frame is a key frame. + * - ``V4L2_VP9_FRAME_FLAG_SHOW_FRAME`` + - 0x002 + - The frame should be displayed. + * - ``V4L2_VP9_FRAME_FLAG_ERROR_RESILIENT`` + - 0x004 + - The decoding should be error resilient. + * - ``V4L2_VP9_FRAME_FLAG_INTRA_ONLY`` + - 0x008 + - The frame does not reference other frames. + * - ``V4L2_VP9_FRAME_FLAG_ALLOW_HIGH_PREC_MV`` + - 0x010 + - The frame can use high precision motion vectors. + * - ``V4L2_VP9_FRAME_FLAG_REFRESH_FRAME_CTX`` + - 0x020 + - Frame context should be updated after decoding. + * - ``V4L2_VP9_FRAME_FLAG_PARALLEL_DEC_MODE`` + - 0x040 + - Parallel decoding is used. + * - ``V4L2_VP9_FRAME_FLAG_X_SUBSAMPLING`` + - 0x080 + - Vertical subsampling is enabled. + * - ``V4L2_VP9_FRAME_FLAG_Y_SUBSAMPLING`` + - 0x100 + - Horizontal subsampling is enabled. + * - ``V4L2_VP9_FRAME_FLAG_COLOR_RANGE_FULL_SWING`` + - 0x200 + - The full UV range is used. + +.. _vp9_ref_frame_sign_bias: + +``Reference Frame Sign Bias`` + +.. tabularcolumns:: |p{7.0cm}|p{1.2cm}|p{9.1cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_SIGN_BIAS_LAST`` + - 0x1 + - Sign bias is set for the last reference frame. + * - ``V4L2_VP9_SIGN_BIAS_GOLDEN`` + - 0x2 + - Sign bias is set for the golden reference frame. + * - ``V4L2_VP9_SIGN_BIAS_ALT`` + - 0x2 + - Sign bias is set for the alt reference frame. + +.. _vp9_reset_frame_context: + +``Reset Frame Context`` + +.. tabularcolumns:: |p{7.0cm}|p{1.2cm}|p{9.1cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_RESET_FRAME_CTX_NONE`` + - 0 + - Do not reset any frame context. + * - ``V4L2_VP9_RESET_FRAME_CTX_SPEC`` + - 1 + - Reset the frame context pointed to by + :c:type:`v4l2_ctrl_vp9_frame`.frame_context_idx. + * - ``V4L2_VP9_RESET_FRAME_CTX_ALL`` + - 2 + - Reset all frame contexts. + +See section '7.2 Uncompressed header semantics' of the :ref:`vp9` specification +for more details. + +.. _vp9_interpolation_filter: + +``Interpolation Filter`` + +.. tabularcolumns:: |p{9.0cm}|p{1.2cm}|p{7.1cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_INTERP_FILTER_EIGHTTAP`` + - 0 + - Eight tap filter. + * - ``V4L2_VP9_INTERP_FILTER_EIGHTTAP_SMOOTH`` + - 1 + - Eight tap smooth filter. + * - ``V4L2_VP9_INTERP_FILTER_EIGHTTAP_SHARP`` + - 2 + - Eeight tap sharp filter. + * - ``V4L2_VP9_INTERP_FILTER_BILINEAR`` + - 3 + - Bilinear filter. + * - ``V4L2_VP9_INTERP_FILTER_SWITCHABLE`` + - 4 + - Filter selection is signaled at the block level. + +See section '7.2.7 Interpolation filter semantics' of the :ref:`vp9` specification +for more details. + +.. _vp9_reference_mode: + +``Reference Mode`` + +.. tabularcolumns:: |p{9.6cm}|p{0.5cm}|p{7.2cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_REFERENCE_MODE_SINGLE_REFERENCE`` + - 0 + - Indicates that all the inter blocks use only a single reference frame + to generate motion compensated prediction. + * - ``V4L2_VP9_REFERENCE_MODE_COMPOUND_REFERENCE`` + - 1 + - Requires all the inter blocks to use compound mode. Single reference + frame prediction is not allowed. + * - ``V4L2_VP9_REFERENCE_MODE_SELECT`` + - 2 + - Allows each individual inter block to select between single and + compound prediction modes. + +See section '7.3.6 Frame reference mode semantics' of the :ref:`vp9` specification for more details. + +.. c:type:: v4l2_vp9_segmentation + +Encodes the quantization parameters. See section '7.2.10 Segmentation +params syntax' of the :ref:`vp9` specification for more details. + +.. tabularcolumns:: |p{0.8cm}|p{5cm}|p{11.4cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_vp9_segmentation + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``feature_data[8][4]`` + - Data attached to each feature. Data entry is only valid if the feature + is enabled. The array shall be indexed with segment number as the first dimension + (0..7) and one of V4L2_VP9_SEG_* as the second dimension. + See :ref:`Segment Feature IDs<vp9_segment_feature>`. + * - __u8 + - ``feature_enabled[8]`` + - Bitmask defining which features are enabled in each segment. The value for each + segment is a combination of V4L2_VP9_SEGMENT_FEATURE_ENABLED(id) values where id is + one of V4L2_VP9_SEG_*. See :ref:`Segment Feature IDs<vp9_segment_feature>`. + * - __u8 + - ``tree_probs[7]`` + - Specifies the probability values to be used when decoding a Segment-ID. + See '5.15 Segmentation map' section of :ref:`vp9` for more details. + * - __u8 + - ``pred_probs[3]`` + - Specifies the probability values to be used when decoding a + Predicted-Segment-ID. See '6.4.14 Get segment id syntax' + section of :ref:`vp9` for more details. + * - __u8 + - ``flags`` + - Combination of V4L2_VP9_SEGMENTATION_FLAG_* flags. See + :ref:`Segmentation Flags<vp9_segmentation_flags>`. + * - __u8 + - ``reserved[5]`` + - Applications and drivers must set this to zero. + +.. _vp9_segment_feature: + +``Segment feature IDs`` + +.. tabularcolumns:: |p{6.0cm}|p{1cm}|p{10.3cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_SEG_LVL_ALT_Q`` + - 0 + - Quantizer segment feature. + * - ``V4L2_VP9_SEG_LVL_ALT_L`` + - 1 + - Loop filter segment feature. + * - ``V4L2_VP9_SEG_LVL_REF_FRAME`` + - 2 + - Reference frame segment feature. + * - ``V4L2_VP9_SEG_LVL_SKIP`` + - 3 + - Skip segment feature. + * - ``V4L2_VP9_SEG_LVL_MAX`` + - 4 + - Number of segment features. + +.. _vp9_segmentation_flags: + +``Segmentation Flags`` + +.. tabularcolumns:: |p{10.6cm}|p{0.8cm}|p{5.9cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_SEGMENTATION_FLAG_ENABLED`` + - 0x01 + - Indicates that this frame makes use of the segmentation tool. + * - ``V4L2_VP9_SEGMENTATION_FLAG_UPDATE_MAP`` + - 0x02 + - Indicates that the segmentation map should be updated during the + decoding of this frame. + * - ``V4L2_VP9_SEGMENTATION_FLAG_TEMPORAL_UPDATE`` + - 0x04 + - Indicates that the updates to the segmentation map are coded + relative to the existing segmentation map. + * - ``V4L2_VP9_SEGMENTATION_FLAG_UPDATE_DATA`` + - 0x08 + - Indicates that new parameters are about to be specified for each + segment. + * - ``V4L2_VP9_SEGMENTATION_FLAG_ABS_OR_DELTA_UPDATE`` + - 0x10 + - Indicates that the segmentation parameters represent the actual values + to be used. + +.. c:type:: v4l2_vp9_quantization + +Encodes the quantization parameters. See section '7.2.9 Quantization params +syntax' of the VP9 specification for more details. + +.. tabularcolumns:: |p{0.8cm}|p{4cm}|p{12.4cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_vp9_quantization + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``base_q_idx`` + - Indicates the base frame qindex. + * - __s8 + - ``delta_q_y_dc`` + - Indicates the Y DC quantizer relative to base_q_idx. + * - __s8 + - ``delta_q_uv_dc`` + - Indicates the UV DC quantizer relative to base_q_idx. + * - __s8 + - ``delta_q_uv_ac`` + - Indicates the UV AC quantizer relative to base_q_idx. + * - __u8 + - ``reserved[4]`` + - Applications and drivers must set this to zero. + +.. c:type:: v4l2_vp9_loop_filter + +This structure contains all loop filter related parameters. See sections +'7.2.8 Loop filter semantics' of the :ref:`vp9` specification for more details. + +.. tabularcolumns:: |p{0.8cm}|p{4cm}|p{12.4cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_vp9_loop_filter + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s8 + - ``ref_deltas[4]`` + - Contains the adjustment needed for the filter level based on the chosen + reference frame. + * - __s8 + - ``mode_deltas[2]`` + - Contains the adjustment needed for the filter level based on the chosen + mode. + * - __u8 + - ``level`` + - Indicates the loop filter strength. + * - __u8 + - ``sharpness`` + - Indicates the sharpness level. + * - __u8 + - ``flags`` + - Combination of V4L2_VP9_LOOP_FILTER_FLAG_* flags. + See :ref:`Loop Filter Flags <vp9_loop_filter_flags>`. + * - __u8 + - ``reserved[7]`` + - Applications and drivers must set this to zero. + + +.. _vp9_loop_filter_flags: + +``Loop Filter Flags`` + +.. tabularcolumns:: |p{9.6cm}|p{0.5cm}|p{7.2cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_LOOP_FILTER_FLAG_DELTA_ENABLED`` + - 0x1 + - When set, the filter level depends on the mode and reference frame used + to predict a block. + * - ``V4L2_VP9_LOOP_FILTER_FLAG_DELTA_UPDATE`` + - 0x2 + - When set, the bitstream contains additional syntax elements that + specify which mode and reference frame deltas are to be updated. + +.. _v4l2-codec-stateless-hevc: + +``V4L2_CID_STATELESS_HEVC_SPS (struct)`` + Specifies the Sequence Parameter Set fields (as extracted from the + bitstream) for the associated HEVC slice data. + These bitstream parameters are defined according to :ref:`hevc`. + They are described in section 7.4.3.2 "Sequence parameter set RBSP + semantics" of the specification. + +.. c:type:: v4l2_ctrl_hevc_sps + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.2cm}|p{9.2cm}|p{6.9cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hevc_sps + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``video_parameter_set_id`` + - Specifies the value of the vps_video_parameter_set_id of the active VPS + as described in section "7.4.3.2.1 General sequence parameter set RBSP semantics" + of H.265 specifications. + * - __u8 + - ``seq_parameter_set_id`` + - Provides an identifier for the SPS for reference by other syntax elements + as described in section "7.4.3.2.1 General sequence parameter set RBSP semantics" + of H.265 specifications. + * - __u16 + - ``pic_width_in_luma_samples`` + - Specifies the width of each decoded picture in units of luma samples. + * - __u16 + - ``pic_height_in_luma_samples`` + - Specifies the height of each decoded picture in units of luma samples. + * - __u8 + - ``bit_depth_luma_minus8`` + - This value plus 8 specifies the bit depth of the samples of the luma array. + * - __u8 + - ``bit_depth_chroma_minus8`` + - This value plus 8 specifies the bit depth of the samples of the chroma arrays. + * - __u8 + - ``log2_max_pic_order_cnt_lsb_minus4`` + - Specifies the value of the variable MaxPicOrderCntLsb. + * - __u8 + - ``sps_max_dec_pic_buffering_minus1`` + - This value plus 1 specifies the maximum required size of the decoded picture buffer for + the coded video sequence (CVS). + * - __u8 + - ``sps_max_num_reorder_pics`` + - Indicates the maximum allowed number of pictures. + * - __u8 + - ``sps_max_latency_increase_plus1`` + - Used to signal MaxLatencyPictures, which indicates the maximum number of + pictures that can precede any picture in output order and follow that + picture in decoding order. + * - __u8 + - ``log2_min_luma_coding_block_size_minus3`` + - This value plus 3 specifies the minimum luma coding block size. + * - __u8 + - ``log2_diff_max_min_luma_coding_block_size`` + - Specifies the difference between the maximum and minimum luma coding block size. + * - __u8 + - ``log2_min_luma_transform_block_size_minus2`` + - This value plus 2 specifies the minimum luma transform block size. + * - __u8 + - ``log2_diff_max_min_luma_transform_block_size`` + - Specifies the difference between the maximum and minimum luma transform block size. + * - __u8 + - ``max_transform_hierarchy_depth_inter`` + - Specifies the maximum hierarchy depth for transform units of coding units coded + in inter prediction mode. + * - __u8 + - ``max_transform_hierarchy_depth_intra`` + - Specifies the maximum hierarchy depth for transform units of coding units coded in + intra prediction mode. + * - __u8 + - ``pcm_sample_bit_depth_luma_minus1`` + - This value plus 1 specifies the number of bits used to represent each of PCM sample values of the + luma component. + * - __u8 + - ``pcm_sample_bit_depth_chroma_minus1`` + - Specifies the number of bits used to represent each of PCM sample values of + the chroma components. + * - __u8 + - ``log2_min_pcm_luma_coding_block_size_minus3`` + - Plus 3 specifies the minimum size of coding blocks. + * - __u8 + - ``log2_diff_max_min_pcm_luma_coding_block_size`` + - Specifies the difference between the maximum and minimum size of coding blocks. + * - __u8 + - ``num_short_term_ref_pic_sets`` + - Specifies the number of st_ref_pic_set() syntax structures included in the SPS. + * - __u8 + - ``num_long_term_ref_pics_sps`` + - Specifies the number of candidate long-term reference pictures that are + specified in the SPS. + * - __u8 + - ``chroma_format_idc`` + - Specifies the chroma sampling. + * - __u8 + - ``sps_max_sub_layers_minus1`` + - This value plus 1 specifies the maximum number of temporal sub-layers. + * - __u64 + - ``flags`` + - See :ref:`Sequence Parameter Set Flags <hevc_sps_flags>` + +.. raw:: latex + + \normalsize + +.. _hevc_sps_flags: + +``Sequence Parameter Set Flags`` + +.. raw:: latex + + \small + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_HEVC_SPS_FLAG_SEPARATE_COLOUR_PLANE`` + - 0x00000001 + - + * - ``V4L2_HEVC_SPS_FLAG_SCALING_LIST_ENABLED`` + - 0x00000002 + - + * - ``V4L2_HEVC_SPS_FLAG_AMP_ENABLED`` + - 0x00000004 + - + * - ``V4L2_HEVC_SPS_FLAG_SAMPLE_ADAPTIVE_OFFSET`` + - 0x00000008 + - + * - ``V4L2_HEVC_SPS_FLAG_PCM_ENABLED`` + - 0x00000010 + - + * - ``V4L2_HEVC_SPS_FLAG_PCM_LOOP_FILTER_DISABLED`` + - 0x00000020 + - + * - ``V4L2_HEVC_SPS_FLAG_LONG_TERM_REF_PICS_PRESENT`` + - 0x00000040 + - + * - ``V4L2_HEVC_SPS_FLAG_SPS_TEMPORAL_MVP_ENABLED`` + - 0x00000080 + - + * - ``V4L2_HEVC_SPS_FLAG_STRONG_INTRA_SMOOTHING_ENABLED`` + - 0x00000100 + - + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_HEVC_PPS (struct)`` + Specifies the Picture Parameter Set fields (as extracted from the + bitstream) for the associated HEVC slice data. + These bitstream parameters are defined according to :ref:`hevc`. + They are described in section 7.4.3.3 "Picture parameter set RBSP + semantics" of the specification. + +.. c:type:: v4l2_ctrl_hevc_pps + +.. tabularcolumns:: |p{1.2cm}|p{8.6cm}|p{7.5cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hevc_pps + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``pic_parameter_set_id`` + - Identifies the PPS for reference by other syntax elements. + * - __u8 + - ``num_extra_slice_header_bits`` + - Specifies the number of extra slice header bits that are present + in the slice header RBSP for coded pictures referring to the PPS. + * - __u8 + - ``num_ref_idx_l0_default_active_minus1`` + - This value plus 1 specifies the inferred value of num_ref_idx_l0_active_minus1. + * - __u8 + - ``num_ref_idx_l1_default_active_minus1`` + - This value plus 1 specifies the inferred value of num_ref_idx_l1_active_minus1. + * - __s8 + - ``init_qp_minus26`` + - This value plus 26 specifies the initial value of SliceQp Y for each slice + referring to the PPS. + * - __u8 + - ``diff_cu_qp_delta_depth`` + - Specifies the difference between the luma coding tree block size + and the minimum luma coding block size of coding units that + convey cu_qp_delta_abs and cu_qp_delta_sign_flag. + * - __s8 + - ``pps_cb_qp_offset`` + - Specifies the offsets to the luma quantization parameter Cb. + * - __s8 + - ``pps_cr_qp_offset`` + - Specifies the offsets to the luma quantization parameter Cr. + * - __u8 + - ``num_tile_columns_minus1`` + - This value plus 1 specifies the number of tile columns partitioning the picture. + * - __u8 + - ``num_tile_rows_minus1`` + - This value plus 1 specifies the number of tile rows partitioning the picture. + * - __u8 + - ``column_width_minus1[20]`` + - This value plus 1 specifies the width of the i-th tile column in units of + coding tree blocks. + * - __u8 + - ``row_height_minus1[22]`` + - This value plus 1 specifies the height of the i-th tile row in units of coding + tree blocks. + * - __s8 + - ``pps_beta_offset_div2`` + - Specifies the default deblocking parameter offsets for beta divided by 2. + * - __s8 + - ``pps_tc_offset_div2`` + - Specifies the default deblocking parameter offsets for tC divided by 2. + * - __u8 + - ``log2_parallel_merge_level_minus2`` + - This value plus 2 specifies the value of the variable Log2ParMrgLevel. + * - __u8 + - ``padding[4]`` + - Applications and drivers must set this to zero. + * - __u64 + - ``flags`` + - See :ref:`Picture Parameter Set Flags <hevc_pps_flags>` + +.. _hevc_pps_flags: + +``Picture Parameter Set Flags`` + +.. raw:: latex + + \small + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_HEVC_PPS_FLAG_DEPENDENT_SLICE_SEGMENT_ENABLED`` + - 0x00000001 + - + * - ``V4L2_HEVC_PPS_FLAG_OUTPUT_FLAG_PRESENT`` + - 0x00000002 + - + * - ``V4L2_HEVC_PPS_FLAG_SIGN_DATA_HIDING_ENABLED`` + - 0x00000004 + - + * - ``V4L2_HEVC_PPS_FLAG_CABAC_INIT_PRESENT`` + - 0x00000008 + - + * - ``V4L2_HEVC_PPS_FLAG_CONSTRAINED_INTRA_PRED`` + - 0x00000010 + - + * - ``V4L2_HEVC_PPS_FLAG_TRANSFORM_SKIP_ENABLED`` + - 0x00000020 + - + * - ``V4L2_HEVC_PPS_FLAG_CU_QP_DELTA_ENABLED`` + - 0x00000040 + - + * - ``V4L2_HEVC_PPS_FLAG_PPS_SLICE_CHROMA_QP_OFFSETS_PRESENT`` + - 0x00000080 + - + * - ``V4L2_HEVC_PPS_FLAG_WEIGHTED_PRED`` + - 0x00000100 + - + * - ``V4L2_HEVC_PPS_FLAG_WEIGHTED_BIPRED`` + - 0x00000200 + - + * - ``V4L2_HEVC_PPS_FLAG_TRANSQUANT_BYPASS_ENABLED`` + - 0x00000400 + - + * - ``V4L2_HEVC_PPS_FLAG_TILES_ENABLED`` + - 0x00000800 + - + * - ``V4L2_HEVC_PPS_FLAG_ENTROPY_CODING_SYNC_ENABLED`` + - 0x00001000 + - + * - ``V4L2_HEVC_PPS_FLAG_LOOP_FILTER_ACROSS_TILES_ENABLED`` + - 0x00002000 + - + * - ``V4L2_HEVC_PPS_FLAG_PPS_LOOP_FILTER_ACROSS_SLICES_ENABLED`` + - 0x00004000 + - + * - ``V4L2_HEVC_PPS_FLAG_DEBLOCKING_FILTER_OVERRIDE_ENABLED`` + - 0x00008000 + - + * - ``V4L2_HEVC_PPS_FLAG_PPS_DISABLE_DEBLOCKING_FILTER`` + - 0x00010000 + - + * - ``V4L2_HEVC_PPS_FLAG_LISTS_MODIFICATION_PRESENT`` + - 0x00020000 + - + * - ``V4L2_HEVC_PPS_FLAG_SLICE_SEGMENT_HEADER_EXTENSION_PRESENT`` + - 0x00040000 + - + * - ``V4L2_HEVC_PPS_FLAG_DEBLOCKING_FILTER_CONTROL_PRESENT`` + - 0x00080000 + - Specifies the presence of deblocking filter control syntax elements in + the PPS + * - ``V4L2_HEVC_PPS_FLAG_UNIFORM_SPACING`` + - 0x00100000 + - Specifies that tile column boundaries and likewise tile row boundaries + are distributed uniformly across the picture + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_HEVC_SLICE_PARAMS (struct)`` + Specifies various slice-specific parameters, especially from the NAL unit + header, general slice segment header and weighted prediction parameter + parts of the bitstream. + These bitstream parameters are defined according to :ref:`hevc`. + They are described in section 7.4.7 "General slice segment header + semantics" of the specification. + This control is a dynamically sized 1-dimensional array, + V4L2_CTRL_FLAG_DYNAMIC_ARRAY flag must be set when using it. + +.. c:type:: v4l2_ctrl_hevc_slice_params + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{5.4cm}|p{6.8cm}|p{5.1cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hevc_slice_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``bit_size`` + - Size (in bits) of the current slice data. + * - __u32 + - ``data_byte_offset`` + - Offset (in byte) to the video data in the current slice data. + * - __u32 + - ``num_entry_point_offsets`` + - Specifies the number of entry point offset syntax elements in the slice header. + When the driver supports it, the ``V4L2_CID_STATELESS_HEVC_ENTRY_POINT_OFFSETS`` + must be set. + * - __u8 + - ``nal_unit_type`` + - Specifies the coding type of the slice (B, P or I). + * - __u8 + - ``nuh_temporal_id_plus1`` + - Minus 1 specifies a temporal identifier for the NAL unit. + * - __u8 + - ``slice_type`` + - + (V4L2_HEVC_SLICE_TYPE_I, V4L2_HEVC_SLICE_TYPE_P or + V4L2_HEVC_SLICE_TYPE_B). + * - __u8 + - ``colour_plane_id`` + - Specifies the colour plane associated with the current slice. + * - __s32 + - ``slice_pic_order_cnt`` + - Specifies the picture order count. + * - __u8 + - ``num_ref_idx_l0_active_minus1`` + - This value plus 1 specifies the maximum reference index for reference picture list 0 + that may be used to decode the slice. + * - __u8 + - ``num_ref_idx_l1_active_minus1`` + - This value plus 1 specifies the maximum reference index for reference picture list 1 + that may be used to decode the slice. + * - __u8 + - ``collocated_ref_idx`` + - Specifies the reference index of the collocated picture used for + temporal motion vector prediction. + * - __u8 + - ``five_minus_max_num_merge_cand`` + - Specifies the maximum number of merging motion vector prediction + candidates supported in the slice subtracted from 5. + * - __s8 + - ``slice_qp_delta`` + - Specifies the initial value of QpY to be used for the coding blocks in the slice. + * - __s8 + - ``slice_cb_qp_offset`` + - Specifies a difference to be added to the value of pps_cb_qp_offset. + * - __s8 + - ``slice_cr_qp_offset`` + - Specifies a difference to be added to the value of pps_cr_qp_offset. + * - __s8 + - ``slice_act_y_qp_offset`` + - Specifies the offset to the luma of quantization parameter qP derived in section 8.6.2 + * - __s8 + - ``slice_act_cb_qp_offset`` + - Specifies the offset to the cb of quantization parameter qP derived in section 8.6.2 + * - __s8 + - ``slice_act_cr_qp_offset`` + - Specifies the offset to the cr of quantization parameter qP derived in section 8.6.2 + * - __s8 + - ``slice_beta_offset_div2`` + - Specifies the deblocking parameter offsets for beta divided by 2. + * - __s8 + - ``slice_tc_offset_div2`` + - Specifies the deblocking parameter offsets for tC divided by 2. + * - __u8 + - ``pic_struct`` + - Indicates whether a picture should be displayed as a frame or as one or more fields. + * - __u32 + - ``slice_segment_addr`` + - Specifies the address of the first coding tree block in the slice segment. + * - __u8 + - ``ref_idx_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The list of L0 reference elements as indices in the DPB. + * - __u8 + - ``ref_idx_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The list of L1 reference elements as indices in the DPB. + * - __u16 + - ``short_term_ref_pic_set_size`` + - Specifies the size, in bits, of the short-term reference picture set, described as st_ref_pic_set() + in the specification, included in the slice header or SPS (section 7.3.6.1). + * - __u16 + - ``long_term_ref_pic_set_size`` + - Specifies the size, in bits, of the long-term reference picture set include in the slice header + or SPS. It is the number of bits in the conditional block if(long_term_ref_pics_present_flag) + in section 7.3.6.1 of the specification. + * - __u8 + - ``padding`` + - Applications and drivers must set this to zero. + * - struct :c:type:`v4l2_hevc_pred_weight_table` + - ``pred_weight_table`` + - The prediction weight coefficients for inter-picture prediction. + * - __u64 + - ``flags`` + - See :ref:`Slice Parameters Flags <hevc_slice_params_flags>` + +.. raw:: latex + + \normalsize + +.. _hevc_slice_params_flags: + +``Slice Parameters Flags`` + +.. raw:: latex + + \scriptsize + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_SAO_LUMA`` + - 0x00000001 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_SAO_CHROMA`` + - 0x00000002 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_TEMPORAL_MVP_ENABLED`` + - 0x00000004 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_MVD_L1_ZERO`` + - 0x00000008 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_CABAC_INIT`` + - 0x00000010 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_COLLOCATED_FROM_L0`` + - 0x00000020 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_USE_INTEGER_MV`` + - 0x00000040 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_DEBLOCKING_FILTER_DISABLED`` + - 0x00000080 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_LOOP_FILTER_ACROSS_SLICES_ENABLED`` + - 0x00000100 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_DEPENDENT_SLICE_SEGMENT`` + - 0x00000200 + - + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_HEVC_ENTRY_POINT_OFFSETS (integer)`` + Specifies entry point offsets in bytes. + This control is a dynamically sized array. The number of entry point + offsets is reported by the ``elems`` field. + This bitstream parameter is defined according to :ref:`hevc`. + They are described in section 7.4.7.1 "General slice segment header + semantics" of the specification. + When multiple slices are submitted in a request, the length of + this array must be the sum of num_entry_point_offsets of all the + slices in the request. + +``V4L2_CID_STATELESS_HEVC_SCALING_MATRIX (struct)`` + Specifies the HEVC scaling matrix parameters used for the scaling process + for transform coefficients. + These matrix and parameters are defined according to :ref:`hevc`. + They are described in section 7.4.5 "Scaling list data semantics" of + the specification. + +.. c:type:: v4l2_ctrl_hevc_scaling_matrix + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{5.4cm}|p{6.8cm}|p{5.1cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hevc_scaling_matrix + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``scaling_list_4x4[6][16]`` + - Scaling list is used for the scaling process for transform + coefficients. The values on each scaling list are expected + in raster scan order. + * - __u8 + - ``scaling_list_8x8[6][64]`` + - Scaling list is used for the scaling process for transform + coefficients. The values on each scaling list are expected + in raster scan order. + * - __u8 + - ``scaling_list_16x16[6][64]`` + - Scaling list is used for the scaling process for transform + coefficients. The values on each scaling list are expected + in raster scan order. + * - __u8 + - ``scaling_list_32x32[2][64]`` + - Scaling list is used for the scaling process for transform + coefficients. The values on each scaling list are expected + in raster scan order. + * - __u8 + - ``scaling_list_dc_coef_16x16[6]`` + - Scaling list is used for the scaling process for transform + coefficients. The values on each scaling list are expected + in raster scan order. + * - __u8 + - ``scaling_list_dc_coef_32x32[2]`` + - Scaling list is used for the scaling process for transform + coefficients. The values on each scaling list are expected + in raster scan order. + +.. raw:: latex + + \normalsize + +.. c:type:: v4l2_hevc_dpb_entry + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.0cm}|p{4.2cm}|p{12.1cm}| + +.. flat-table:: struct v4l2_hevc_dpb_entry + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u64 + - ``timestamp`` + - Timestamp of the V4L2 capture buffer to use as reference, used + with B-coded and P-coded frames. The timestamp refers to the + ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the + :c:func:`v4l2_timeval_to_ns()` function to convert the struct + :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. + * - __u8 + - ``flags`` + - Long term flag for the reference frame + (V4L2_HEVC_DPB_ENTRY_LONG_TERM_REFERENCE). The flag is set as + described in the ITU HEVC specification chapter "8.3.2 Decoding + process for reference picture set". + * - __u8 + - ``field_pic`` + - Whether the reference is a field picture or a frame. + See :ref:`HEVC dpb field pic Flags <hevc_dpb_field_pic_flags>` + * - __s32 + - ``pic_order_cnt_val`` + - The picture order count of the current picture. + * - __u8 + - ``padding[2]`` + - Applications and drivers must set this to zero. + +.. raw:: latex + + \normalsize + +.. _hevc_dpb_field_pic_flags: + +``HEVC dpb field pic Flags`` + +.. raw:: latex + + \scriptsize + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_HEVC_SEI_PIC_STRUCT_FRAME`` + - 0 + - (progressive) Frame + * - ``V4L2_HEVC_SEI_PIC_STRUCT_TOP_FIELD`` + - 1 + - Top field + * - ``V4L2_HEVC_SEI_PIC_STRUCT_BOTTOM_FIELD`` + - 2 + - Bottom field + * - ``V4L2_HEVC_SEI_PIC_STRUCT_TOP_BOTTOM`` + - 3 + - Top field, bottom field, in that order + * - ``V4L2_HEVC_SEI_PIC_STRUCT_BOTTOM_TOP`` + - 4 + - Bottom field, top field, in that order + * - ``V4L2_HEVC_SEI_PIC_STRUCT_TOP_BOTTOM_TOP`` + - 5 + - Top field, bottom field, top field repeated, in that order + * - ``V4L2_HEVC_SEI_PIC_STRUCT_BOTTOM_TOP_BOTTOM`` + - 6 + - Bottom field, top field, bottom field repeated, in that order + * - ``V4L2_HEVC_SEI_PIC_STRUCT_FRAME_DOUBLING`` + - 7 + - Frame doubling + * - ``V4L2_HEVC_SEI_PIC_STRUCT_FRAME_TRIPLING`` + - 8 + - Frame tripling + * - ``V4L2_HEVC_SEI_PIC_STRUCT_TOP_PAIRED_PREVIOUS_BOTTOM`` + - 9 + - Top field paired with previous bottom field in output order + * - ``V4L2_HEVC_SEI_PIC_STRUCT_BOTTOM_PAIRED_PREVIOUS_TOP`` + - 10 + - Bottom field paired with previous top field in output order + * - ``V4L2_HEVC_SEI_PIC_STRUCT_TOP_PAIRED_NEXT_BOTTOM`` + - 11 + - Top field paired with next bottom field in output order + * - ``V4L2_HEVC_SEI_PIC_STRUCT_BOTTOM_PAIRED_NEXT_TOP`` + - 12 + - Bottom field paired with next top field in output order + +.. c:type:: v4l2_hevc_pred_weight_table + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{0.8cm}|p{10.6cm}|p{5.9cm}| + +.. flat-table:: struct v4l2_hevc_pred_weight_table + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s8 + - ``delta_luma_weight_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The difference of the weighting factor applied to the luma + prediction value for list 0. + * - __s8 + - ``luma_offset_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The additive offset applied to the luma prediction value for list 0. + * - __s8 + - ``delta_chroma_weight_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` + - The difference of the weighting factor applied to the chroma + prediction value for list 0. + * - __s8 + - ``chroma_offset_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` + - The difference of the additive offset applied to the chroma + prediction values for list 0. + * - __s8 + - ``delta_luma_weight_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The difference of the weighting factor applied to the luma + prediction value for list 1. + * - __s8 + - ``luma_offset_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The additive offset applied to the luma prediction value for list 1. + * - __s8 + - ``delta_chroma_weight_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` + - The difference of the weighting factor applied to the chroma + prediction value for list 1. + * - __s8 + - ``chroma_offset_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` + - The difference of the additive offset applied to the chroma + prediction values for list 1. + * - __u8 + - ``luma_log2_weight_denom`` + - The base 2 logarithm of the denominator for all luma weighting + factors. + * - __s8 + - ``delta_chroma_log2_weight_denom`` + - The difference of the base 2 logarithm of the denominator for + all chroma weighting factors. + * - __u8 + - ``padding[6]`` + - Applications and drivers must set this to zero. + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_HEVC_DECODE_MODE (enum)`` + Specifies the decoding mode to use. Currently exposes slice-based and + frame-based decoding but new modes might be added later on. + This control is used as a modifier for V4L2_PIX_FMT_HEVC_SLICE + pixel format. Applications that support V4L2_PIX_FMT_HEVC_SLICE + are required to set this control in order to specify the decoding mode + that is expected for the buffer. + Drivers may expose a single or multiple decoding modes, depending + on what they can support. + +.. c:type:: v4l2_stateless_hevc_decode_mode + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{9.4cm}|p{0.6cm}|p{7.3cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_STATELESS_HEVC_DECODE_MODE_SLICE_BASED`` + - 0 + - Decoding is done at the slice granularity. + The OUTPUT buffer must contain a single slice. + * - ``V4L2_STATELESS_HEVC_DECODE_MODE_FRAME_BASED`` + - 1 + - Decoding is done at the frame granularity. + The OUTPUT buffer must contain all slices needed to decode the + frame. + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_HEVC_START_CODE (enum)`` + Specifies the HEVC slice start code expected for each slice. + This control is used as a modifier for V4L2_PIX_FMT_HEVC_SLICE + pixel format. Applications that support V4L2_PIX_FMT_HEVC_SLICE + are required to set this control in order to specify the start code + that is expected for the buffer. + Drivers may expose a single or multiple start codes, depending + on what they can support. + +.. c:type:: v4l2_stateless_hevc_start_code + +.. tabularcolumns:: |p{9.2cm}|p{0.6cm}|p{7.5cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_STATELESS_HEVC_START_CODE_NONE`` + - 0 + - Selecting this value specifies that HEVC slices are passed + to the driver without any start code. The bitstream data should be + according to :ref:`hevc` 7.3.1.1 General NAL unit syntax, hence + contains emulation prevention bytes when required. + * - ``V4L2_STATELESS_HEVC_START_CODE_ANNEX_B`` + - 1 + - Selecting this value specifies that HEVC slices are expected + to be prefixed by Annex B start codes. According to :ref:`hevc` + valid start codes can be 3-bytes 0x000001 or 4-bytes 0x00000001. + +.. raw:: latex + + \normalsize + +``V4L2_CID_MPEG_VIDEO_BASELAYER_PRIORITY_ID (integer)`` + Specifies a priority identifier for the NAL unit, which will be applied to + the base layer. By default this value is set to 0 for the base layer, + and the next layer will have the priority ID assigned as 1, 2, 3 and so on. + The video encoder can't decide the priority id to be applied to a layer, + so this has to come from client. + This is applicable to H264 and valid Range is from 0 to 63. + Source Rec. ITU-T H.264 (06/2019); G.7.4.1.1, G.8.8.1. + +``V4L2_CID_MPEG_VIDEO_LTR_COUNT (integer)`` + Specifies the maximum number of Long Term Reference (LTR) frames at any + given time that the encoder can keep. + This is applicable to the H264 and HEVC encoders. + +``V4L2_CID_MPEG_VIDEO_FRAME_LTR_INDEX (integer)`` + After setting this control the frame that will be queued next + will be marked as a Long Term Reference (LTR) frame + and given this LTR index which ranges from 0 to LTR_COUNT-1. + This is applicable to the H264 and HEVC encoders. + Source Rec. ITU-T H.264 (06/2019); Table 7.9 + +``V4L2_CID_MPEG_VIDEO_USE_LTR_FRAMES (bitmask)`` + Specifies the Long Term Reference (LTR) frame(s) to be used for + encoding the next frame queued after setting this control. + This provides a bitmask which consists of bits [0, LTR_COUNT-1]. + This is applicable to the H264 and HEVC encoders. + +``V4L2_CID_STATELESS_HEVC_DECODE_PARAMS (struct)`` + Specifies various decode parameters, especially the references picture order + count (POC) for all the lists (short, long, before, current, after) and the + number of entries for each of them. + These parameters are defined according to :ref:`hevc`. + They are described in section 8.3 "Slice decoding process" of the + specification. + +.. c:type:: v4l2_ctrl_hevc_decode_params + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hevc_decode_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s32 + - ``pic_order_cnt_val`` + - PicOrderCntVal as described in section 8.3.1 "Decoding process + for picture order count" of the specification. + * - __u16 + - ``short_term_ref_pic_set_size`` + - Specifies the size, in bits, of the short-term reference picture set, of the first slice + described as st_ref_pic_set() in the specification, included in the slice header + or SPS (section 7.3.6.1). + * - __u16 + - ``long_term_ref_pic_set_size`` + - Specifies the size, in bits, of the long-term reference picture set, of the first slice + included in the slice header or SPS. It is the number of bits in the conditional block + if(long_term_ref_pics_present_flag) in section 7.3.6.1 of the specification. + * - __u8 + - ``num_active_dpb_entries`` + - The number of entries in ``dpb``. + * - __u8 + - ``num_poc_st_curr_before`` + - The number of reference pictures in the short-term set that come before + the current frame. + * - __u8 + - ``num_poc_st_curr_after`` + - The number of reference pictures in the short-term set that come after + the current frame. + * - __u8 + - ``num_poc_lt_curr`` + - The number of reference pictures in the long-term set. + * - __u8 + - ``poc_st_curr_before[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - PocStCurrBefore as described in section 8.3.2 "Decoding process for reference + picture set": provides the index of the short term before references in DPB array. + * - __u8 + - ``poc_st_curr_after[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - PocStCurrAfter as described in section 8.3.2 "Decoding process for reference + picture set": provides the index of the short term after references in DPB array. + * - __u8 + - ``poc_lt_curr[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - PocLtCurr as described in section 8.3.2 "Decoding process for reference + picture set": provides the index of the long term references in DPB array. + * - __u8 + - ``num_delta_pocs_of_ref_rps_idx`` + - When the short_term_ref_pic_set_sps_flag in the slice header is equal to 0, + it is the same as the derived value NumDeltaPocs[RefRpsIdx]. It can be used to parse + the RPS data in slice headers instead of skipping it with @short_term_ref_pic_set_size. + When the value of short_term_ref_pic_set_sps_flag in the slice header is + equal to 1, num_delta_pocs_of_ref_rps_idx shall be set to 0. + * - struct :c:type:`v4l2_hevc_dpb_entry` + - ``dpb[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The decoded picture buffer, for meta-data about reference frames. + * - __u64 + - ``flags`` + - See :ref:`Decode Parameters Flags <hevc_decode_params_flags>` + +.. _hevc_decode_params_flags: + +``Decode Parameters Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_HEVC_DECODE_PARAM_FLAG_IRAP_PIC`` + - 0x00000001 + - + * - ``V4L2_HEVC_DECODE_PARAM_FLAG_IDR_PIC`` + - 0x00000002 + - + * - ``V4L2_HEVC_DECODE_PARAM_FLAG_NO_OUTPUT_OF_PRIOR`` + - 0x00000004 + - + +.. _v4l2-codec-stateless-av1: + +``V4L2_CID_STATELESS_AV1_SEQUENCE (struct)`` + Represents an AV1 Sequence OBU (Open Bitstream Unit). See section 5.5 + "Sequence header OBU syntax" in :ref:`av1` for more details. + +.. c:type:: v4l2_ctrl_av1_sequence + +.. cssclass:: longtable + +.. tabularcolumns:: |p{5.8cm}|p{4.8cm}|p{6.6cm}| + +.. flat-table:: struct v4l2_ctrl_av1_sequence + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``flags`` + - See :ref:`AV1 Sequence Flags <av1_sequence_flags>`. + * - __u8 + - ``seq_profile`` + - Specifies the features that can be used in the coded video sequence. + * - __u8 + - ``order_hint_bits`` + - Specifies the number of bits used for the order_hint field at each frame. + * - __u8 + - ``bit_depth`` + - the bit depth to use for the sequence as described in section 5.5.2 + "Color config syntax" in :ref:`av1` for more details. + * - __u8 + - ``reserved`` + - Applications and drivers must set this to zero. + * - __u16 + - ``max_frame_width_minus_1`` + - Specifies the maximum frame width minus 1 for the frames represented by + this sequence header. + * - __u16 + - ``max_frame_height_minus_1`` + - Specifies the maximum frame height minus 1 for the frames represented by + this sequence header. + +.. _av1_sequence_flags: + +``AV1 Sequence Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_SEQUENCE_FLAG_STILL_PICTURE`` + - 0x00000001 + - If set, specifies that the coded video sequence contains only one coded + frame. If not set, specifies that the coded video sequence contains one + or more coded frames. + * - ``V4L2_AV1_SEQUENCE_FLAG_USE_128X128_SUPERBLOCK`` + - 0x00000002 + - If set, indicates that superblocks contain 128x128 luma samples. + When equal to 0, it indicates that superblocks contain 64x64 luma + samples. The number of contained chroma samples depends on + subsampling_x and subsampling_y. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_FILTER_INTRA`` + - 0x00000004 + - If set, specifies that the use_filter_intra syntax element may be + present. If not set, specifies that the use_filter_intra syntax element + will not be present. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_INTRA_EDGE_FILTER`` + - 0x00000008 + - Specifies whether the intra edge filtering process should be enabled. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_INTERINTRA_COMPOUND`` + - 0x00000010 + - If set, specifies that the mode info for inter blocks may contain the + syntax element interintra. If not set, specifies that the syntax element + interintra will not be present. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_MASKED_COMPOUND`` + - 0x00000020 + - If set, specifies that the mode info for inter blocks may contain the + syntax element compound_type. If not set, specifies that the syntax + element compound_type will not be present. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_WARPED_MOTION`` + - 0x00000040 + - If set, indicates that the allow_warped_motion syntax element may be + present. If not set, indicates that the allow_warped_motion syntax + element will not be present. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_DUAL_FILTER`` + - 0x00000080 + - If set, indicates that the inter prediction filter type may be specified + independently in the horizontal and vertical directions. If the flag is + equal to 0, only one filter type may be specified, which is then used in + both directions. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_ORDER_HINT`` + - 0x00000100 + - If set, indicates that tools based on the values of order hints may be + used. If not set, indicates that tools based on order hints are + disabled. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_JNT_COMP`` + - 0x00000200 + - If set, indicates that the distance weights process may be used for + inter prediction. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_REF_FRAME_MVS`` + - 0x00000400 + - If set, indicates that the use_ref_frame_mvs syntax element may be + present. If not set, indicates that the use_ref_frame_mvs syntax element + will not be present. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_SUPERRES`` + - 0x00000800 + - If set, specifies that the use_superres syntax element will be present + in the uncompressed header. If not set, specifies that the use_superres + syntax element will not be present (instead use_superres will be set to + 0 in the uncompressed header without being read). + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_CDEF`` + - 0x00001000 + - If set, specifies that cdef filtering may be enabled. If not set, + specifies that cdef filtering is disabled. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_RESTORATION`` + - 0x00002000 + - If set, specifies that loop restoration filtering may be enabled. If not + set, specifies that loop restoration filtering is disabled. + * - ``V4L2_AV1_SEQUENCE_FLAG_MONO_CHROME`` + - 0x00004000 + - If set, indicates that the video does not contain U and V color planes. + If not set, indicates that the video contains Y, U, and V color planes. + * - ``V4L2_AV1_SEQUENCE_FLAG_COLOR_RANGE`` + - 0x00008000 + - If set, signals full swing representation, i.e. "Full Range + Quantization". If not set, signals studio swing representation, i.e. + "Limited Range Quantization". + * - ``V4L2_AV1_SEQUENCE_FLAG_SUBSAMPLING_X`` + - 0x00010000 + - Specify the chroma subsampling format. + * - ``V4L2_AV1_SEQUENCE_FLAG_SUBSAMPLING_Y`` + - 0x00020000 + - Specify the chroma subsampling format. + * - ``V4L2_AV1_SEQUENCE_FLAG_FILM_GRAIN_PARAMS_PRESENT`` + - 0x00040000 + - Specifies whether film grain parameters are present in the coded video + sequence. + * - ``V4L2_AV1_SEQUENCE_FLAG_SEPARATE_UV_DELTA_Q`` + - 0x00080000 + - If set, indicates that the U and V planes may have separate delta + quantizer values. If not set, indicates that the U and V planes will share + the same delta quantizer value. + +``V4L2_CID_STATELESS_AV1_TILE_GROUP_ENTRY (struct)`` + Represents a single AV1 tile inside an AV1 Tile Group. Note that MiRowStart, + MiRowEnd, MiColStart and MiColEnd can be retrieved from struct + v4l2_av1_tile_info in struct v4l2_ctrl_av1_frame using tile_row and + tile_col. See section 6.10.1 "General tile group OBU semantics" in + :ref:`av1` for more details. + +.. c:type:: v4l2_ctrl_av1_tile_group_entry + +.. cssclass:: longtable + +.. tabularcolumns:: |p{5.8cm}|p{4.8cm}|p{6.6cm}| + +.. flat-table:: struct v4l2_ctrl_av1_tile_group_entry + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``tile_offset`` + - Offset from the OBU data, i.e. where the coded tile data actually starts. + * - __u32 + - ``tile_size`` + - Specifies the size in bytes of the coded tile. Equivalent to "TileSize" + in :ref:`av1`. + * - __u32 + - ``tile_row`` + - Specifies the row of the current tile. Equivalent to "TileRow" in + :ref:`av1`. + * - __u32 + - ``tile_col`` + - Specifies the column of the current tile. Equivalent to "TileColumn" in + :ref:`av1`. + +.. c:type:: v4l2_av1_warp_model + + AV1 Warp Model as described in section 3 "Symbols and abbreviated terms" of + :ref:`av1`. + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_WARP_MODEL_IDENTITY`` + - 0 + - Warp model is just an identity transform. + * - ``V4L2_AV1_WARP_MODEL_TRANSLATION`` + - 1 + - Warp model is a pure translation. + * - ``V4L2_AV1_WARP_MODEL_ROTZOOM`` + - 2 + - Warp model is a rotation + symmetric zoom + translation. + * - ``V4L2_AV1_WARP_MODEL_AFFINE`` + - 3 + - Warp model is a general affine transform. + +.. c:type:: v4l2_av1_reference_frame + +AV1 Reference Frames as described in section 6.10.24 "Ref frames semantics" +of :ref:`av1`. + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_REF_INTRA_FRAME`` + - 0 + - Intra Frame Reference. + * - ``V4L2_AV1_REF_LAST_FRAME`` + - 1 + - Last Frame Reference. + * - ``V4L2_AV1_REF_LAST2_FRAME`` + - 2 + - Last2 Frame Reference. + * - ``V4L2_AV1_REF_LAST3_FRAME`` + - 3 + - Last3 Frame Reference. + * - ``V4L2_AV1_REF_GOLDEN_FRAME`` + - 4 + - Golden Frame Reference. + * - ``V4L2_AV1_REF_BWDREF_FRAME`` + - 5 + - BWD Frame Reference. + * - ``V4L2_AV1_REF_ALTREF2_FRAME`` + - 6 + - ALTREF2 Frame Reference. + * - ``V4L2_AV1_REF_ALTREF_FRAME`` + - 7 + - ALTREF Frame Reference. + +.. c:type:: v4l2_av1_global_motion + +AV1 Global Motion parameters as described in section 6.8.17 +"Global motion params semantics" of :ref:`av1`. + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_av1_global_motion + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``flags[V4L2_AV1_TOTAL_REFS_PER_FRAME]`` + - A bitfield containing the flags per reference frame. See + :ref:`AV1 Global Motion Flags <av1_global_motion_flags>` for more + details. + * - enum :c:type:`v4l2_av1_warp_model` + - ``type[V4L2_AV1_TOTAL_REFS_PER_FRAME]`` + - The type of global motion transform used. + * - __s32 + - ``params[V4L2_AV1_TOTAL_REFS_PER_FRAME][6]`` + - This field has the same meaning as "gm_params" in :ref:`av1`. + * - __u8 + - ``invalid`` + - Bitfield indicating whether the global motion params are invalid for a + given reference frame. See section 7.11.3.6 Setup shear process and the + variable "warpValid". Use V4L2_AV1_GLOBAL_MOTION_IS_INVALID(ref) to + create a suitable mask. + * - __u8 + - ``reserved[3]`` + - Applications and drivers must set this to zero. + +.. _av1_global_motion_flags: + +``AV1 Global Motion Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_GLOBAL_MOTION_FLAG_IS_GLOBAL`` + - 0x00000001 + - Specifies whether global motion parameters are present for a particular + reference frame. + * - ``V4L2_AV1_GLOBAL_MOTION_FLAG_IS_ROT_ZOOM`` + - 0x00000002 + - Specifies whether a particular reference frame uses rotation and zoom + global motion. + * - ``V4L2_AV1_GLOBAL_MOTION_FLAG_IS_TRANSLATION`` + - 0x00000004 + - Specifies whether a particular reference frame uses translation global + motion + +.. c:type:: v4l2_av1_frame_restoration_type + +AV1 Frame Restoration Type. + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_FRAME_RESTORE_NONE`` + - 0 + - No filtering is applied. + * - ``V4L2_AV1_FRAME_RESTORE_WIENER`` + - 1 + - Wiener filter process is invoked. + * - ``V4L2_AV1_FRAME_RESTORE_SGRPROJ`` + - 2 + - Self guided filter process is invoked. + * - ``V4L2_AV1_FRAME_RESTORE_SWITCHABLE`` + - 3 + - Restoration filter is swichtable. + +.. c:type:: v4l2_av1_loop_restoration + +AV1 Loop Restoration as described in section 6.10.15 "Loop restoration params +semantics" of :ref:`av1`. + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_av1_loop_restoration + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``flags`` + - See :ref:`AV1 Loop Restoration Flags <av1_loop_restoration_flags>`. + * - __u8 + - ``lr_unit_shift`` + - Specifies if the luma restoration size should be halved. + * - __u8 + - ``lr_uv_shift`` + - Specifies if the chroma size should be half the luma size. + * - __u8 + - ``reserved`` + - Applications and drivers must set this to zero. + * - :c:type:`v4l2_av1_frame_restoration_type` + - ``frame_restoration_type[V4L2_AV1_NUM_PLANES_MAX]`` + - Specifies the type of restoration used for each plane. + * - __u8 + - ``loop_restoration_size[V4L2_AV1_MAX_NUM_PLANES]`` + - Specifies the size of loop restoration units in units of samples in the + current plane. + +.. _av1_loop_restoration_flags: + +``AV1 Loop Restoration Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_LOOP_RESTORATION_FLAG_USES_LR`` + - 0x00000001 + - Retains the same meaning as UsesLr in :ref:`av1`. + * - ``V4L2_AV1_LOOP_RESTORATION_FLAG_USES_CHROMA_LR`` + - 0x00000002 + - Retains the same meaning as UsesChromaLr in :ref:`av1`. + +.. c:type:: v4l2_av1_cdef + +AV1 CDEF params semantics as described in section 6.10.14 "CDEF params +semantics" of :ref:`av1`. + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_av1_cdef + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``damping_minus_3`` + - Controls the amount of damping in the deringing filter. + * - __u8 + - ``bits`` + - Specifies the number of bits needed to specify which CDEF filter to + apply. + * - __u8 + - ``y_pri_strength[V4L2_AV1_CDEF_MAX]`` + - Specifies the strength of the primary filter. + * - __u8 + - ``y_sec_strength[V4L2_AV1_CDEF_MAX]`` + - Specifies the strength of the secondary filter. + * - __u8 + - ``uv_pri_strength[V4L2_AV1_CDEF_MAX]`` + - Specifies the strength of the primary filter. + * - __u8 + - ``uv_sec_strength[V4L2_AV1_CDEF_MAX]`` + - Specifies the strength of the secondary filter. + +.. c:type:: v4l2_av1_segment_feature + +AV1 segment features as described in section 3 "Symbols and abbreviated terms" +of :ref:`av1`. + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_SEG_LVL_ALT_Q`` + - 0 + - Index for quantizer segment feature. + * - ``V4L2_AV1_SEG_LVL_ALT_LF_Y_V`` + - 1 + - Index for vertical luma loop filter segment feature. + * - ``V4L2_AV1_SEG_LVL_REF_FRAME`` + - 5 + - Index for reference frame segment feature. + * - ``V4L2_AV1_SEG_LVL_REF_SKIP`` + - 6 + - Index for skip segment feature. + * - ``V4L2_AV1_SEG_LVL_REF_GLOBALMV`` + - 7 + - Index for global mv feature. + * - ``V4L2_AV1_SEG_LVL_MAX`` + - 8 + - Number of segment features. + +.. c:type:: v4l2_av1_segmentation + +AV1 Segmentation params as defined in section 6.8.13 "Segmentation params +semantics" of :ref:`av1`. + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_av1_segmentation + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``flags`` + - See :ref:`AV1 Segmentation Flags <av1_segmentation_flags>` + * - __u8 + - ``last_active_seg_id`` + - Indicates the highest numbered segment id that has some + enabled feature. This is used when decoding the segment id to only decode + choices corresponding to used segments. + * - __u8 + - ``feature_enabled[V4L2_AV1_MAX_SEGMENTS]`` + - Bitmask defining which features are enabled in each segment. Use + V4L2_AV1_SEGMENT_FEATURE_ENABLED to build a suitable mask. + * - __u16 + - ``feature_data[V4L2_AV1_MAX_SEGMENTS][V4L2_AV1_SEG_LVL_MAX]`` + - Data attached to each feature. Data entry is only valid if the feature + is enabled. + +.. _av1_segmentation_flags: + +``AV1 Segmentation Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_SEGMENTATION_FLAG_ENABLED`` + - 0x00000001 + - If set, indicates that this frame makes use of the segmentation tool. If + not set, indicates that the frame does not use segmentation. + * - ``V4L2_AV1_SEGMENTATION_FLAG_UPDATE_MAP`` + - 0x00000002 + - If set, indicates that the segmentation map are updated during the + decoding of this frame. If not set, indicates that the segmentation map + from the previous frame is used. + * - ``V4L2_AV1_SEGMENTATION_FLAG_TEMPORAL_UPDATE`` + - 0x00000004 + - If set, indicates that the updates to the segmentation map are coded + relative to the existing segmentation map. If not set, indicates that + the new segmentation map is coded without reference to the existing + segmentation map. + * - ``V4L2_AV1_SEGMENTATION_FLAG_UPDATE_DATA`` + - 0x00000008 + - If set, indicates that the updates to the segmentation map are coded + relative to the existing segmentation map. If not set, indicates that + the new segmentation map is coded without reference to the existing + segmentation map. + * - ``V4L2_AV1_SEGMENTATION_FLAG_SEG_ID_PRE_SKIP`` + - 0x00000010 + - If set, indicates that the segment id will be read before the skip + syntax element. If not set, indicates that the skip syntax element will + be read first. + +.. c:type:: v4l2_av1_loop_filter + +AV1 Loop filter params as defined in section 6.8.10 "Loop filter semantics" of +:ref:`av1`. + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_av1_loop_filter + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``flags`` + - See + :ref:`AV1 Loop Filter flags <av1_loop_filter_flags>` for more details. + * - __u8 + - ``level[4]`` + - An array containing loop filter strength values. Different loop + filter strength values from the array are used depending on the image + plane being filtered, and the edge direction (vertical or horizontal) + being filtered. + * - __u8 + - ``sharpness`` + - indicates the sharpness level. The loop_filter_level and + loop_filter_sharpness together determine when a block edge is filtered, + and by how much the filtering can change the sample values. The loop + filter process is described in section 7.14 of :ref:`av1`. + * - __u8 + - ``ref_deltas[V4L2_AV1_TOTAL_REFS_PER_FRAME]`` + - contains the adjustment needed for the filter level based on the + chosen reference frame. If this syntax element is not present, it + maintains its previous value. + * - __u8 + - ``mode_deltas[2]`` + - contains the adjustment needed for the filter level based on + the chosen mode. If this syntax element is not present, it maintains its + previous value. + * - __u8 + - ``delta_lf_res`` + - specifies the left shift which should be applied to decoded loop filter + delta values. + +.. _av1_loop_filter_flags: + +``AV1 Loop Filter Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_LOOP_FILTER_FLAG_DELTA_ENABLED`` + - 0x00000001 + - If set, means that the filter level depends on the mode and reference + frame used to predict a block. If not set, means that the filter level + does not depend on the mode and reference frame. + * - ``V4L2_AV1_LOOP_FILTER_FLAG_DELTA_UPDATE`` + - 0x00000002 + - If set, means that additional syntax elements are present that specify + which mode and reference frame deltas are to be updated. If not set, + means that these syntax elements are not present. + * - ``V4L2_AV1_LOOP_FILTER_FLAG_DELTA_LF_PRESENT`` + - 0x00000004 + - Specifies whether loop filter delta values are present + * - ``V4L2_AV1_LOOP_FILTER_FLAG_DELTA_LF_MULTI`` + - 0x00000008 + - A value equal to 1 specifies that separate loop filter + deltas are sent for horizontal luma edges, vertical luma edges, + the U edges, and the V edges. A value of delta_lf_multi equal to 0 + specifies that the same loop filter delta is used for all edges. + +.. c:type:: v4l2_av1_quantization + +AV1 Quantization params as defined in section 6.8.11 "Quantization params +semantics" of :ref:`av1`. + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_av1_quantization + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``flags`` + - See + :ref:`AV1 Loop Filter flags <av1_quantization_flags>` for more details. + * - __u8 + - ``base_q_idx`` + - Indicates the base frame qindex. This is used for Y AC coefficients and + as the base value for the other quantizers. + * - __u8 + - ``delta_q_y_dc`` + - Indicates the Y DC quantizer relative to base_q_idx. + * - __u8 + - ``delta_q_u_dc`` + - Indicates the U DC quantizer relative to base_q_idx. + * - __u8 + - ``delta_q_u_ac`` + - Indicates the U AC quantizer relative to base_q_idx. + * - __u8 + - ``delta_q_v_dc`` + - Indicates the V DC quantizer relative to base_q_idx. + * - __u8 + - ``delta_q_v_ac`` + - Indicates the V AC quantizer relative to base_q_idx. + * - __u8 + - ``qm_y`` + - Specifies the level in the quantizer matrix that should be used for + luma plane decoding. + * - __u8 + - ``qm_u`` + - Specifies the level in the quantizer matrix that should be used for + chroma U plane decoding. + * - __u8 + - ``qm_v`` + - Specifies the level in the quantizer matrix that should be used for + chroma V plane decoding. + * - __u8 + - ``delta_q_res`` + - Specifies the left shift which should be applied to decoded quantizer + index delta values. + +.. _av1_quantization_flags: + +``AV1 Quantization Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_QUANTIZATION_FLAG_DIFF_UV_DELTA`` + - 0x00000001 + - If set, indicates that the U and V delta quantizer values are coded + separately. If not set, indicates that the U and V delta quantizer + values share a common value. + * - ``V4L2_AV1_QUANTIZATION_FLAG_USING_QMATRIX`` + - 0x00000002 + - If set, specifies that the quantizer matrix will be used to compute + quantizers. + * - ``V4L2_AV1_QUANTIZATION_FLAG_DELTA_Q_PRESENT`` + - 0x00000004 + - Specifies whether quantizer index delta values are present. + +.. c:type:: v4l2_av1_tile_info + +AV1 Tile info as defined in section 6.8.14 "Tile info semantics" of ref:`av1`. + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_av1_tile_info + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``flags`` + - See + :ref:`AV1 Tile Info flags <av1_tile_info_flags>` for more details. + * - __u8 + - ``context_update_tile_id`` + - Specifies which tile to use for the CDF update. + * - __u8 + - ``tile_cols`` + - Specifies the number of tiles across the frame. + * - __u8 + - ``tile_rows`` + - Specifies the number of tiles down the frame. + * - __u32 + - ``mi_col_starts[V4L2_AV1_MAX_TILE_COLS + 1]`` + - An array specifying the start column (in units of 4x4 luma + samples) for each tile across the image. + * - __u32 + - ``mi_row_starts[V4L2_AV1_MAX_TILE_ROWS + 1]`` + - An array specifying the start row (in units of 4x4 luma + samples) for each tile across the image. + * - __u32 + - ``width_in_sbs_minus_1[V4L2_AV1_MAX_TILE_COLS]`` + - Specifies the width of a tile minus 1 in units of superblocks. + * - __u32 + - ``height_in_sbs_minus_1[V4L2_AV1_MAX_TILE_ROWS]`` + - Specifies the height of a tile minus 1 in units of superblocks. + * - __u8 + - ``tile_size_bytes`` + - Specifies the number of bytes needed to code each tile size. + * - __u8 + - ``reserved[3]`` + - Applications and drivers must set this to zero. + +.. _av1_tile_info_flags: + +``AV1 Tile Info Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_TILE_INFO_FLAG_UNIFORM_TILE_SPACING`` + - 0x00000001 + - If set, means that the tiles are uniformly spaced across the frame. (In + other words, all tiles are the same size except for the ones at the + right and bottom edge which can be smaller). If not set means that the + tile sizes are coded. + +.. c:type:: v4l2_av1_frame_type + +AV1 Frame Type + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_KEY_FRAME`` + - 0 + - Key frame. + * - ``V4L2_AV1_INTER_FRAME`` + - 1 + - Inter frame. + * - ``V4L2_AV1_INTRA_ONLY_FRAME`` + - 2 + - Intra-only frame. + * - ``V4L2_AV1_SWITCH_FRAME`` + - 3 + - Switch frame. + +.. c:type:: v4l2_av1_interpolation_filter + +AV1 Interpolation Filter + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_INTERPOLATION_FILTER_EIGHTTAP`` + - 0 + - Eight tap filter. + * - ``V4L2_AV1_INTERPOLATION_FILTER_EIGHTTAP_SMOOTH`` + - 1 + - Eight tap smooth filter. + * - ``V4L2_AV1_INTERPOLATION_FILTER_EIGHTTAP_SHARP`` + - 2 + - Eight tap sharp filter. + * - ``V4L2_AV1_INTERPOLATION_FILTER_BILINEAR`` + - 3 + - Bilinear filter. + * - ``V4L2_AV1_INTERPOLATION_FILTER_SWITCHABLE`` + - 4 + - Filter selection is signaled at the block level. + +.. c:type:: v4l2_av1_tx_mode + +AV1 Tx mode as described in section 6.8.21 "TX mode semantics" of :ref:`av1`. + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_TX_MODE_ONLY_4X4`` + - 0 + - The inverse transform will use only 4x4 transforms. + * - ``V4L2_AV1_TX_MODE_LARGEST`` + - 1 + - The inverse transform will use the largest transform size that fits + inside the block. + * - ``V4L2_AV1_TX_MODE_SELECT`` + - 2 + - The choice of transform size is specified explicitly for each block. + +``V4L2_CID_STATELESS_AV1_FRAME (struct)`` + Represents a Frame Header OBU. See 6.8 "Frame Header OBU semantics" of + :ref:`av1` for more details. + +.. c:type:: v4l2_ctrl_av1_frame + +.. cssclass:: longtable + +.. tabularcolumns:: |p{5.8cm}|p{4.8cm}|p{6.6cm}| + +.. flat-table:: struct v4l2_ctrl_av1_frame + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - struct :c:type:`v4l2_av1_tile_info` + - ``tile_info`` + - Tile info + * - struct :c:type:`v4l2_av1_quantization` + - ``quantization`` + - Quantization parameters. + * - __u8 + - ``superres_denom`` + - The denominator for the upscaling ratio. + * - struct :c:type:`v4l2_av1_segmentation` + - ``segmentation`` + - Segmentation parameters. + * - struct :c:type:`v4l2_av1_loop_filter` + - ``loop_filter`` + - Loop filter params + * - struct :c:type:`v4l2_av1_cdef` + - ``cdef`` + - CDEF params + * - __u8 + - ``skip_mode_frame[2]`` + - Specifies the frames to use for compound prediction when skip_mode is + equal to 1. + * - __u8 + - ``primary_ref_frame`` + - Specifies which reference frame contains the CDF values and other state + that should be loaded at the start of the frame. + * - struct :c:type:`v4l2_av1_loop_restoration` + - ``loop_restoration`` + - Loop restoration parameters. + * - struct :c:type:`v4l2_av1_global_motion` + - ``global_motion`` + - Global motion parameters. + * - __u32 + - ``flags`` + - See + :ref:`AV1 Frame flags <av1_frame_flags>` for more details. + * - enum :c:type:`v4l2_av1_frame_type` + - ``frame_type`` + - Specifies the AV1 frame type + * - __u32 + - ``order_hint`` + - Specifies OrderHintBits least significant bits of the expected output + order for this frame. + * - __u32 + - ``upscaled_width`` + - The upscaled width. + * - enum :c:type:`v4l2_av1_interpolation_filter` + - ``interpolation_filter`` + - Specifies the filter selection used for performing inter prediction. + * - enum :c:type:`v4l2_av1_tx_mode` + - ``tx_mode`` + - Specifies how the transform size is determined. + * - __u32 + - ``frame_width_minus_1`` + - Add 1 to get the frame's width. + * - __u32 + - ``frame_height_minus_1`` + - Add 1 to get the frame's height. + * - __u16 + - ``render_width_minus_1`` + - Add 1 to get the render width of the frame in luma samples. + * - __u16 + - ``render_height_minus_1`` + - Add 1 to get the render height of the frame in luma samples. + * - __u32 + - ``current_frame_id`` + - Specifies the frame id number for the current frame. Frame + id numbers are additional information that do not affect the decoding + process, but provide decoders with a way of detecting missing reference + frames so that appropriate action can be taken. + * - __u8 + - ``buffer_removal_time[V4L2_AV1_MAX_OPERATING_POINTS]`` + - Specifies the frame removal time in units of DecCT clock ticks counted + from the removal time of the last random access point for operating point + opNum. + * - __u8 + - ``reserved[4]`` + - Applications and drivers must set this to zero. + * - __u32 + - ``order_hints[V4L2_AV1_TOTAL_REFS_PER_FRAME]`` + - Specifies the expected output order hint for each reference frame. + This field corresponds to the OrderHints variable from the specification + (section 5.9.2 "Uncompressed header syntax"). As such, this is only + used for non-intra frames and ignored otherwise. order_hints[0] is + always ignored. + * - __u64 + - ``reference_frame_ts[V4L2_AV1_TOTAL_REFS_PER_FRAME]`` + - The V4L2 timestamp for each of the reference frames enumerated in + enum :c:type:`v4l2_av1_reference_frame` starting at + ``V4L2_AV1_REF_LAST_FRAME``. This represents the state of reference + slot as described in the spec and updated by userland through the + "Reference frame update process" in section 7.20 The timestamp refers + to the ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the + :c:func:`v4l2_timeval_to_ns()` function to convert the struct + :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. + * - __s8 + - ``ref_frame_idx[V4L2_AV1_REFS_PER_FRAME]`` + - An index into ``reference_frame_ts`` representing the ordered list of + references used by inter-frame. Matches the bitstream syntax + element of the same name. + * - __u8 + - ``refresh_frame_flags`` + - Contains a bitmask that specifies which reference frame slots will be + updated with the current frame after it is decoded. + +.. _av1_frame_flags: + +``AV1 Frame Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_FRAME_FLAG_SHOW_FRAME`` + - 0x00000001 + - If set, specifies that this frame should be immediately output once + decoded. If not set, specifies that this frame should not be immediately + output; it may be output later if a later uncompressed header uses + show_existing_frame equal to 1. + * - ``V4L2_AV1_FRAME_FLAG_SHOWABLE_FRAME`` + - 0x00000002 + - If set, specifies that the frame may be output using the + show_existing_frame mechanism. If not set, specifies that this frame + will not be output using the show_existing_frame mechanism. + * - ``V4L2_AV1_FRAME_FLAG_ERROR_RESILIENT_MODE`` + - 0x00000004 + - Specifies whether error resilient mode is enabled. + * - ``V4L2_AV1_FRAME_FLAG_DISABLE_CDF_UPDATE`` + - 0x00000008 + - Specifies whether the CDF update in the symbol decoding process should + be disabled. + * - ``V4L2_AV1_FRAME_FLAG_ALLOW_SCREEN_CONTENT_TOOLS`` + - 0x00000010 + - If set, indicates that intra blocks may use palette encoding. If not + set, indicates that palette encoding is never used. + * - ``V4L2_AV1_FRAME_FLAG_FORCE_INTEGER_MV`` + - 0x00000020 + - If set, specifies that motion vectors will always be integers. If not + set, specifies that motion vectors can contain fractional bits. + * - ``V4L2_AV1_FRAME_FLAG_ALLOW_INTRABC`` + - 0x00000040 + - If set, indicates that intra block copy may be used in this frame. If + not set, indicates that intra block copy is not allowed in this frame. + * - ``V4L2_AV1_FRAME_FLAG_USE_SUPERRES`` + - 0x00000080 + - If set, indicates that upscaling is needed. + * - ``V4L2_AV1_FRAME_FLAG_ALLOW_HIGH_PRECISION_MV`` + - 0x00000100 + - If set, specifies that motion vectors are specified to eighth pel + precision. If not set, specifies that motion vectors are specified to + quarter pel precision; + * - ``V4L2_AV1_FRAME_FLAG_IS_MOTION_MODE_SWITCHABLE`` + - 0x00000200 + - If not set, specifies that only the SIMPLE motion mode will be used. + * - ``V4L2_AV1_FRAME_FLAG_USE_REF_FRAME_MVS`` + - 0x00000400 + - If set specifies that motion vector information from a previous frame + can be used when decoding the current frame. If not set, specifies that + this information will not be used. + * - ``V4L2_AV1_FRAME_FLAG_DISABLE_FRAME_END_UPDATE_CDF`` + - 0x00000800 + - If set indicates that the end of frame CDF update is disabled. If not + set, indicates that the end of frame CDF update is enabled + * - ``V4L2_AV1_FRAME_FLAG_ALLOW_WARPED_MOTION`` + - 0x00001000 + - If set, indicates that the syntax element motion_mode may be present, if + not set, indicates that the syntax element motion_mode will not be + present. + * - ``V4L2_AV1_FRAME_FLAG_REFERENCE_SELECT`` + - 0x00002000 + - If set, specifies that the mode info for inter blocks contains the + syntax element comp_mode that indicates whether to use single or + compound reference prediction. If not set, specifies that all inter + blocks will use single prediction. + * - ``V4L2_AV1_FRAME_FLAG_REDUCED_TX_SET`` + - 0x00004000 + - If set, specifies that the frame is restricted to a reduced subset of + the full set of transform types. + * - ``V4L2_AV1_FRAME_FLAG_SKIP_MODE_ALLOWED`` + - 0x00008000 + - This flag retains the same meaning as SkipModeAllowed in :ref:`av1`. + * - ``V4L2_AV1_FRAME_FLAG_SKIP_MODE_PRESENT`` + - 0x00010000 + - If set, specifies that the syntax element skip_mode will be present, if + not set, specifies that skip_mode will not be used for this frame. + * - ``V4L2_AV1_FRAME_FLAG_FRAME_SIZE_OVERRIDE`` + - 0x00020000 + - If set, specifies that the frame size will either be specified as the + size of one of the reference frames, or computed from the + frame_width_minus_1 and frame_height_minus_1 syntax elements. If not + set, specifies that the frame size is equal to the size in the sequence + header. + * - ``V4L2_AV1_FRAME_FLAG_BUFFER_REMOVAL_TIME_PRESENT`` + - 0x00040000 + - If set, specifies that buffer_removal_time is present. If not set, + specifies that buffer_removal_time is not present. + * - ``V4L2_AV1_FRAME_FLAG_FRAME_REFS_SHORT_SIGNALING`` + - 0x00080000 + - If set, indicates that only two reference frames are explicitly + signaled. If not set, indicates that all reference frames are explicitly + signaled. + +``V4L2_CID_STATELESS_AV1_FILM_GRAIN (struct)`` + Represents the optional film grain parameters. See section + 6.8.20 "Film grain params semantics" of :ref:`av1` for more details. + +.. c:type:: v4l2_ctrl_av1_film_grain + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_ctrl_av1_film_grain + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``flags`` + - See :ref:`AV1 Film Grain Flags <av1_film_grain_flags>`. + * - __u8 + - ``cr_mult`` + - Represents a multiplier for the cr component used in derivation of the + input index to the cr component scaling function. + * - __u16 + - ``grain_seed`` + - Specifies the starting value for the pseudo-random numbers used during + film grain synthesis. + * - __u8 + - ``film_grain_params_ref_idx`` + - Indicates which reference frame contains the film grain parameters to be + used for this frame. + * - __u8 + - ``num_y_points`` + - Specifies the number of points for the piece-wise linear scaling + function of the luma component. + * - __u8 + - ``point_y_value[V4L2_AV1_MAX_NUM_Y_POINTS]`` + - Represents the x (luma value) coordinate for the i-th point + of the piecewise linear scaling function for luma component. The values + are signaled on the scale of 0..255. In case of 10 bit video, these + values correspond to luma values divided by 4. In case of 12 bit video, + these values correspond to luma values divided by 16. + * - __u8 + - ``point_y_scaling[V4L2_AV1_MAX_NUM_Y_POINTS]`` + - Represents the scaling (output) value for the i-th point + of the piecewise linear scaling function for luma component. + * - __u8 + - ``num_cb_points`` + - Specifies the number of points for the piece-wise linear scaling + function of the cb component. + * - __u8 + - ``point_cb_value[V4L2_AV1_MAX_NUM_CB_POINTS]`` + - Represents the x coordinate for the i-th point of the + piece-wise linear scaling function for cb component. The values are + signaled on the scale of 0..255. + * - __u8 + - ``point_cb_scaling[V4L2_AV1_MAX_NUM_CB_POINTS]`` + - Represents the scaling (output) value for the i-th point of the + piecewise linear scaling function for cb component. + * - __u8 + - ``num_cr_points`` + - Represents the number of points for the piece-wise + linear scaling function of the cr component. + * - __u8 + - ``point_cr_value[V4L2_AV1_MAX_NUM_CR_POINTS]`` + - Represents the x coordinate for the i-th point of the + piece-wise linear scaling function for cr component. The values are + signaled on the scale of 0..255. + * - __u8 + - ``point_cr_scaling[V4L2_AV1_MAX_NUM_CR_POINTS]`` + - Represents the scaling (output) value for the i-th point of the + piecewise linear scaling function for cr component. + * - __u8 + - ``grain_scaling_minus_8`` + - Represents the shift - 8 applied to the values of the chroma component. + The grain_scaling_minus_8 can take values of 0..3 and determines the + range and quantization step of the standard deviation of film grain. + * - __u8 + - ``ar_coeff_lag`` + - Specifies the number of auto-regressive coefficients for luma and + chroma. + * - __u8 + - ``ar_coeffs_y_plus_128[V4L2_AV1_AR_COEFFS_SIZE]`` + - Specifies auto-regressive coefficients used for the Y plane. + * - __u8 + - ``ar_coeffs_cb_plus_128[V4L2_AV1_AR_COEFFS_SIZE]`` + - Specifies auto-regressive coefficients used for the U plane. + * - __u8 + - ``ar_coeffs_cr_plus_128[V4L2_AV1_AR_COEFFS_SIZE]`` + - Specifies auto-regressive coefficients used for the V plane. + * - __u8 + - ``ar_coeff_shift_minus_6`` + - Specifies the range of the auto-regressive coefficients. Values of 0, + 1, 2, and 3 correspond to the ranges for auto-regressive coefficients of + [-2, 2), [-1, 1), [-0.5, 0.5) and [-0.25, 0.25) respectively. + * - __u8 + - ``grain_scale_shift`` + - Specifies how much the Gaussian random numbers should be scaled down + during the grain synthesis process. + * - __u8 + - ``cb_mult`` + - Represents a multiplier for the cb component used in derivation of the + input index to the cb component scaling function. + * - __u8 + - ``cb_luma_mult`` + - Represents a multiplier for the average luma component used in + derivation of the input index to the cb component scaling function.. + * - __u8 + - ``cr_luma_mult`` + - Represents a multiplier for the average luma component used in + derivation of the input index to the cr component scaling function. + * - __u16 + - ``cb_offset`` + - Represents an offset used in derivation of the input index to the + cb component scaling function. + * - __u16 + - ``cr_offset`` + - Represents an offset used in derivation of the input index to the + cr component scaling function. + * - __u8 + - ``reserved[4]`` + - Applications and drivers must set this to zero. + +.. _av1_film_grain_flags: + +``AV1 Film Grain Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_FILM_GRAIN_FLAG_APPLY_GRAIN`` + - 0x00000001 + - If set, specifies that film grain should be added to this frame. If not + set, specifies that film grain should not be added. + * - ``V4L2_AV1_FILM_GRAIN_FLAG_UPDATE_GRAIN`` + - 0x00000002 + - If set, means that a new set of parameters should be sent. If not set, + specifies that the previous set of parameters should be used. + * - ``V4L2_AV1_FILM_GRAIN_FLAG_CHROMA_SCALING_FROM_LUMA`` + - 0x00000004 + - If set, specifies that the chroma scaling is inferred from the luma + scaling. + * - ``V4L2_AV1_FILM_GRAIN_FLAG_OVERLAP`` + - 0x00000008 + - If set, indicates that the overlap between film grain blocks shall be + applied. If not set, indicates that the overlap between film grain blocks + shall not be applied. + * - ``V4L2_AV1_FILM_GRAIN_FLAG_CLIP_TO_RESTRICTED_RANGE`` + - 0x00000010 + - If set, indicates that clipping to the restricted (studio, i.e. limited) + range shall be applied to the sample values after adding the film grain + (see the semantics for color_range for an explanation of studio swing). + If not set, indicates that clipping to the full range shall be applied + to the sample values after adding the film grain. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst index d0d506a444b1..4a379bd9e3fb 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst @@ -1,13 +1,6 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later -.. _mpeg-controls: +.. _codec-controls: *********************** Codec Control Reference @@ -33,7 +26,7 @@ Generic Codec Controls Codec Control IDs ----------------- -``V4L2_CID_MPEG_CLASS (class)`` +``V4L2_CID_CODEC_CLASS (class)`` The Codec class descriptor. Calling :ref:`VIDIOC_QUERYCTRL` for this control will return a description of this control class. This description can be @@ -399,7 +392,7 @@ enum v4l2_mpeg_audio_mode_extension - which subbands are in intensity stereo. All other subbands are coded in stereo. Layer III is not (yet) supported. Possible values are: - +.. tabularcolumns:: |p{9.1cm}|p{8.4cm}| .. flat-table:: :header-rows: 0 @@ -581,17 +574,61 @@ enum v4l2_mpeg_video_bitrate_mode - - Variable bitrate * - ``V4L2_MPEG_VIDEO_BITRATE_MODE_CBR`` - Constant bitrate + * - ``V4L2_MPEG_VIDEO_BITRATE_MODE_CQ`` + - Constant quality ``V4L2_CID_MPEG_VIDEO_BITRATE (integer)`` - Video bitrate in bits per second. + Average video bitrate in bits per second. ``V4L2_CID_MPEG_VIDEO_BITRATE_PEAK (integer)`` Peak video bitrate in bits per second. Must be larger or equal to the average video bitrate. It is ignored if the video bitrate mode is set to constant bitrate. +``V4L2_CID_MPEG_VIDEO_CONSTANT_QUALITY (integer)`` + Constant quality level control. This control is applicable when + ``V4L2_CID_MPEG_VIDEO_BITRATE_MODE`` value is + ``V4L2_MPEG_VIDEO_BITRATE_MODE_CQ``. Valid range is 1 to 100 + where 1 indicates lowest quality and 100 indicates highest quality. + Encoder will decide the appropriate quantization parameter and + bitrate to produce requested frame quality. + + +``V4L2_CID_MPEG_VIDEO_FRAME_SKIP_MODE (enum)`` + +enum v4l2_mpeg_video_frame_skip_mode - + Indicates in what conditions the encoder should skip frames. If + encoding a frame would cause the encoded stream to be larger then a + chosen data limit then the frame will be skipped. Possible values + are: + + +.. tabularcolumns:: |p{8.2cm}|p{9.3cm}| + +.. raw:: latex + + \small + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_FRAME_SKIP_MODE_DISABLED`` + - Frame skip mode is disabled. + * - ``V4L2_MPEG_VIDEO_FRAME_SKIP_MODE_LEVEL_LIMIT`` + - Frame skip mode enabled and buffer limit is set by the chosen + level and is defined by the standard. + * - ``V4L2_MPEG_VIDEO_FRAME_SKIP_MODE_BUF_LIMIT`` + - Frame skip mode enabled and buffer limit is set by the + :ref:`VBV (MPEG1/2/4) <v4l2-mpeg-video-vbv-size>` or + :ref:`CPB (H264) buffer size <v4l2-mpeg-video-h264-cpb-size>` control. + +.. raw:: latex + + \normalsize + ``V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION (integer)`` For every captured frame, skip this many subsequent frames (default 0). @@ -637,11 +674,64 @@ enum v4l2_mpeg_video_bitrate_mode - is currently displayed (decoded). This value is reset to 0 whenever the decoder is started. +``V4L2_CID_MPEG_VIDEO_DEC_CONCEAL_COLOR (integer64)`` + This control sets the conceal color in YUV color space. It describes + the client preference of the error conceal color in case of an error + where the reference frame is missing. The decoder should fill the + reference buffer with the preferred color and use it for future + decoding. The control is using 16 bits per channel. + Applicable to decoders. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - + - 8bit format + - 10bit format + - 12bit format + * - Y luminance + - Bit 0:7 + - Bit 0:9 + - Bit 0:11 + * - Cb chrominance + - Bit 16:23 + - Bit 16:25 + - Bit 16:27 + * - Cr chrominance + - Bit 32:39 + - Bit 32:41 + - Bit 32:43 + * - Must be zero + - Bit 48:63 + - Bit 48:63 + - Bit 48:63 + ``V4L2_CID_MPEG_VIDEO_DECODER_SLICE_INTERFACE (boolean)`` If enabled the decoder expects to receive a single slice per buffer, otherwise the decoder expects a single frame in per buffer. Applicable to the decoder, all codecs. +``V4L2_CID_MPEG_VIDEO_DEC_DISPLAY_DELAY_ENABLE (boolean)`` + If the display delay is enabled then the decoder is forced to return + a CAPTURE buffer (decoded frame) after processing a certain number + of OUTPUT buffers. The delay can be set through + ``V4L2_CID_MPEG_VIDEO_DEC_DISPLAY_DELAY``. This + feature can be used for example for generating thumbnails of videos. + Applicable to the decoder. + +``V4L2_CID_MPEG_VIDEO_DEC_DISPLAY_DELAY (integer)`` + Display delay value for decoder. The decoder is forced to + return a decoded frame after the set 'display delay' number of + frames. If this number is low it may result in frames returned out + of display order, in addition the hardware may still be using the + returned buffer as a reference picture for subsequent frames. + +``V4L2_CID_MPEG_VIDEO_AU_DELIMITER (boolean)`` + If enabled then, AUD (Access Unit Delimiter) NALUs will be generated. + That could be useful to find the start of a frame without having to + fully parse each NALU. Applicable to the H264 and HEVC encoders. + ``V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_ENABLE (boolean)`` Enable writing sample aspect ratio in the Video Usability Information. Applicable to the H264 encoder. @@ -836,7 +926,11 @@ enum v4l2_mpeg_video_h264_profile - The profile information for H264. Applicable to the H264 encoder. Possible values are: +.. raw:: latex + + \small +.. tabularcolumns:: |p{10.2cm}|p{7.3cm}| .. flat-table:: :header-rows: 0 @@ -879,7 +973,9 @@ enum v4l2_mpeg_video_h264_profile - * - ``V4L2_MPEG_VIDEO_H264_PROFILE_CONSTRAINED_HIGH`` - Constrained High profile +.. raw:: latex + \normalsize .. _v4l2-mpeg-video-mpeg2-profile: @@ -890,7 +986,11 @@ enum v4l2_mpeg_video_mpeg2_profile - The profile information for MPEG2. Applicable to MPEG2 codecs. Possible values are: +.. raw:: latex + + \small +.. tabularcolumns:: |p{10.2cm}|p{7.3cm}| .. flat-table:: :header-rows: 0 @@ -910,6 +1010,9 @@ enum v4l2_mpeg_video_mpeg2_profile - - Multi-view profile (MVP) +.. raw:: latex + + \normalsize .. _v4l2-mpeg-video-mpeg4-profile: @@ -920,7 +1023,11 @@ enum v4l2_mpeg_video_mpeg4_profile - The profile information for MPEG4. Applicable to the MPEG4 encoder. Possible values are: +.. raw:: latex + + \small +.. tabularcolumns:: |p{11.8cm}|p{5.7cm}| .. flat-table:: :header-rows: 0 @@ -935,9 +1042,11 @@ enum v4l2_mpeg_video_mpeg4_profile - * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_SIMPLE_SCALABLE`` - Simple Scalable profile * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_ADVANCED_CODING_EFFICIENCY`` - - + - Advanced Coding Efficiency profile +.. raw:: latex + \normalsize ``V4L2_CID_MPEG_VIDEO_MAX_REF_PIC (integer)`` The maximum number of reference pictures used for encoding. @@ -993,7 +1102,7 @@ enum v4l2_mpeg_video_h264_loop_filter_mode - \small -.. tabularcolumns:: |p{13.6cm}|p{3.9cm}| +.. tabularcolumns:: |p{13.5cm}|p{4.0cm}| .. flat-table:: :header-rows: 0 @@ -1065,7 +1174,46 @@ enum v4l2_mpeg_video_h264_entropy_mode - Cyclic intra macroblock refresh. This is the number of continuous macroblocks refreshed every frame. Each frame a successive set of macroblocks is refreshed until the cycle completes and starts from - the top of the frame. Applicable to H264, H263 and MPEG4 encoder. + the top of the frame. Setting this control to zero means that + macroblocks will not be refreshed. Note that this control will not + take effect when ``V4L2_CID_MPEG_VIDEO_INTRA_REFRESH_PERIOD`` control + is set to non zero value. + Applicable to H264, H263 and MPEG4 encoder. + +``V4L2_CID_MPEG_VIDEO_INTRA_REFRESH_PERIOD_TYPE (enum)`` + +enum v4l2_mpeg_video_intra_refresh_period_type - + Sets the type of intra refresh. The period to refresh + the whole frame is specified by V4L2_CID_MPEG_VIDEO_INTRA_REFRESH_PERIOD. + Note that if this control is not present, then it is undefined what + refresh type is used and it is up to the driver to decide. + Applicable to H264 and HEVC encoders. Possible values are: + +.. tabularcolumns:: |p{9.6cm}|p{7.9cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_INTRA_REFRESH_PERIOD_TYPE_RANDOM`` + - The whole frame is completely refreshed randomly + after the specified period. + * - ``V4L2_MPEG_VIDEO_INTRA_REFRESH_PERIOD_TYPE_CYCLIC`` + - The whole frame MBs are completely refreshed in cyclic order + after the specified period. + +``V4L2_CID_MPEG_VIDEO_INTRA_REFRESH_PERIOD (integer)`` + Intra macroblock refresh period. This sets the period to refresh + the whole frame. In other words, this defines the number of frames + for which the whole frame will be intra-refreshed. An example: + setting period to 1 means that the whole frame will be refreshed, + setting period to 2 means that the half of macroblocks will be + intra-refreshed on frameX and the other half of macroblocks + will be refreshed in frameX + 1 and so on. Setting the period to + zero means no period is specified. + Note that if the client sets this control to non zero value the + ``V4L2_CID_MPEG_VIDEO_CYCLIC_INTRA_REFRESH_MB`` control shall be + ignored. Applicable to H264 and HEVC encoders. ``V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE (boolean)`` Frame level rate control enable. If this control is disabled then @@ -1145,6 +1293,18 @@ enum v4l2_mpeg_video_h264_entropy_mode - V4L2_CID_MPEG_VIDEO_H264_MAX_QP is also set, the quantization parameter should be chosen to meet both requirements. +``V4L2_CID_MPEG_VIDEO_H264_B_FRAME_MIN_QP (integer)`` + Minimum quantization parameter for the H264 B frame to limit B frame + quality to a range. Valid range: from 0 to 51. If + V4L2_CID_MPEG_VIDEO_H264_MIN_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_H264_B_FRAME_MAX_QP (integer)`` + Maximum quantization parameter for the H264 B frame to limit B frame + quality to a range. Valid range: from 0 to 51. If + V4L2_CID_MPEG_VIDEO_H264_MAX_QP is also set, the quantization parameter + should be chosen to meet both requirements. + ``V4L2_CID_MPEG_VIDEO_MPEG4_I_FRAME_QP (integer)`` Quantization parameter for an I frame for MPEG4. Valid range: from 1 to 31. @@ -1163,6 +1323,8 @@ enum v4l2_mpeg_video_h264_entropy_mode - Quantization parameter for an B frame for MPEG4. Valid range: from 1 to 31. +.. _v4l2-mpeg-video-vbv-size: + ``V4L2_CID_MPEG_VIDEO_VBV_SIZE (integer)`` The Video Buffer Verifier size in kilobytes, it is used as a limitation of frame skip. The VBV is defined in the standard as a @@ -1200,6 +1362,8 @@ enum v4l2_mpeg_video_h264_entropy_mode - Force a key frame for the next queued buffer. Applicable to encoders. This is a general, codec-agnostic keyframe control. +.. _v4l2-mpeg-video-h264-cpb-size: + ``V4L2_CID_MPEG_VIDEO_H264_CPB_SIZE (integer)`` The Coded Picture Buffer size in kilobytes, it is used as a limitation of frame skip. The CPB is defined in the H264 standard as @@ -1372,7 +1536,7 @@ enum v4l2_mpeg_video_h264_fmo_change_dir - Specifies a direction of the slice group change for raster and wipe maps. Applicable to the H264 encoder. Possible values are: - +.. tabularcolumns:: |p{9.6cm}|p{7.9cm}| .. flat-table:: :header-rows: 0 @@ -1460,882 +1624,26 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - * - Bit 16:32 - Layer number +``V4L2_CID_MPEG_VIDEO_H264_HIER_CODING_L0_BR (integer)`` + Indicates bit rate (bps) for hierarchical coding layer 0 for H264 encoder. -.. _v4l2-mpeg-h264: - -``V4L2_CID_MPEG_VIDEO_H264_SPS (struct)`` - Specifies the sequence parameter set (as extracted from the - bitstream) for the associated H264 slice data. This includes the - necessary parameters for configuring a stateless hardware decoding - pipeline for H264. The bitstream parameters are defined according - to :ref:`h264`, section 7.4.2.1.1 "Sequence Parameter Set Data - Semantics". For further documentation, refer to the above - specification, unless there is an explicit comment stating - otherwise. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_h264_sps - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_h264_sps - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``profile_idc`` - - - * - __u8 - - ``constraint_set_flags`` - - See :ref:`Sequence Parameter Set Constraints Set Flags <h264_sps_constraints_set_flags>` - * - __u8 - - ``level_idc`` - - - * - __u8 - - ``seq_parameter_set_id`` - - - * - __u8 - - ``chroma_format_idc`` - - - * - __u8 - - ``bit_depth_luma_minus8`` - - - * - __u8 - - ``bit_depth_chroma_minus8`` - - - * - __u8 - - ``log2_max_frame_num_minus4`` - - - * - __u8 - - ``pic_order_cnt_type`` - - - * - __u8 - - ``log2_max_pic_order_cnt_lsb_minus4`` - - - * - __u8 - - ``max_num_ref_frames`` - - - * - __u8 - - ``num_ref_frames_in_pic_order_cnt_cycle`` - - - * - __s32 - - ``offset_for_ref_frame[255]`` - - - * - __s32 - - ``offset_for_non_ref_pic`` - - - * - __s32 - - ``offset_for_top_to_bottom_field`` - - - * - __u16 - - ``pic_width_in_mbs_minus1`` - - - * - __u16 - - ``pic_height_in_map_units_minus1`` - - - * - __u32 - - ``flags`` - - See :ref:`Sequence Parameter Set Flags <h264_sps_flags>` - -.. _h264_sps_constraints_set_flags: - -``Sequence Parameter Set Constraints Set Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_H264_SPS_CONSTRAINT_SET0_FLAG`` - - 0x00000001 - - - * - ``V4L2_H264_SPS_CONSTRAINT_SET1_FLAG`` - - 0x00000002 - - - * - ``V4L2_H264_SPS_CONSTRAINT_SET2_FLAG`` - - 0x00000004 - - - * - ``V4L2_H264_SPS_CONSTRAINT_SET3_FLAG`` - - 0x00000008 - - - * - ``V4L2_H264_SPS_CONSTRAINT_SET4_FLAG`` - - 0x00000010 - - - * - ``V4L2_H264_SPS_CONSTRAINT_SET5_FLAG`` - - 0x00000020 - - - -.. _h264_sps_flags: - -``Sequence Parameter Set Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_H264_SPS_FLAG_SEPARATE_COLOUR_PLANE`` - - 0x00000001 - - - * - ``V4L2_H264_SPS_FLAG_QPPRIME_Y_ZERO_TRANSFORM_BYPASS`` - - 0x00000002 - - - * - ``V4L2_H264_SPS_FLAG_DELTA_PIC_ORDER_ALWAYS_ZERO`` - - 0x00000004 - - - * - ``V4L2_H264_SPS_FLAG_GAPS_IN_FRAME_NUM_VALUE_ALLOWED`` - - 0x00000008 - - - * - ``V4L2_H264_SPS_FLAG_FRAME_MBS_ONLY`` - - 0x00000010 - - - * - ``V4L2_H264_SPS_FLAG_MB_ADAPTIVE_FRAME_FIELD`` - - 0x00000020 - - - * - ``V4L2_H264_SPS_FLAG_DIRECT_8X8_INFERENCE`` - - 0x00000040 - - - -``V4L2_CID_MPEG_VIDEO_H264_PPS (struct)`` - Specifies the picture parameter set (as extracted from the - bitstream) for the associated H264 slice data. This includes the - necessary parameters for configuring a stateless hardware decoding - pipeline for H264. The bitstream parameters are defined according - to :ref:`h264`, section 7.4.2.2 "Picture Parameter Set RBSP - Semantics". For further documentation, refer to the above - specification, unless there is an explicit comment stating - otherwise. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_h264_pps - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_h264_pps - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``pic_parameter_set_id`` - - - * - __u8 - - ``seq_parameter_set_id`` - - - * - __u8 - - ``num_slice_groups_minus1`` - - - * - __u8 - - ``num_ref_idx_l0_default_active_minus1`` - - - * - __u8 - - ``num_ref_idx_l1_default_active_minus1`` - - - * - __u8 - - ``weighted_bipred_idc`` - - - * - __s8 - - ``pic_init_qp_minus26`` - - - * - __s8 - - ``pic_init_qs_minus26`` - - - * - __s8 - - ``chroma_qp_index_offset`` - - - * - __s8 - - ``second_chroma_qp_index_offset`` - - - * - __u16 - - ``flags`` - - See :ref:`Picture Parameter Set Flags <h264_pps_flags>` - -.. _h264_pps_flags: - -``Picture Parameter Set Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_H264_PPS_FLAG_ENTROPY_CODING_MODE`` - - 0x00000001 - - - * - ``V4L2_H264_PPS_FLAG_BOTTOM_FIELD_PIC_ORDER_IN_FRAME_PRESENT`` - - 0x00000002 - - - * - ``V4L2_H264_PPS_FLAG_WEIGHTED_PRED`` - - 0x00000004 - - - * - ``V4L2_H264_PPS_FLAG_DEBLOCKING_FILTER_CONTROL_PRESENT`` - - 0x00000008 - - - * - ``V4L2_H264_PPS_FLAG_CONSTRAINED_INTRA_PRED`` - - 0x00000010 - - - * - ``V4L2_H264_PPS_FLAG_REDUNDANT_PIC_CNT_PRESENT`` - - 0x00000020 - - - * - ``V4L2_H264_PPS_FLAG_TRANSFORM_8X8_MODE`` - - 0x00000040 - - - * - ``V4L2_H264_PPS_FLAG_PIC_SCALING_MATRIX_PRESENT`` - - 0x00000080 - - - -``V4L2_CID_MPEG_VIDEO_H264_SCALING_MATRIX (struct)`` - Specifies the scaling matrix (as extracted from the bitstream) for - the associated H264 slice data. The bitstream parameters are - defined according to :ref:`h264`, section 7.4.2.1.1.1 "Scaling - List Semantics". For further documentation, refer to the above - specification, unless there is an explicit comment stating - otherwise. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_h264_scaling_matrix - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_h264_scaling_matrix - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``scaling_list_4x4[6][16]`` - - Scaling matrix after applying the inverse scanning process. - Expected list order is Intra Y, Intra Cb, Intra Cr, Inter Y, - Inter Cb, Inter Cr. - * - __u8 - - ``scaling_list_8x8[6][64]`` - - Scaling matrix after applying the inverse scanning process. - Expected list order is Intra Y, Inter Y, Intra Cb, Inter Cb, - Intra Cr, Inter Cr. - -``V4L2_CID_MPEG_VIDEO_H264_SLICE_PARAMS (struct)`` - Specifies the slice parameters (as extracted from the bitstream) - for the associated H264 slice data. This includes the necessary - parameters for configuring a stateless hardware decoding pipeline - for H264. The bitstream parameters are defined according to - :ref:`h264`, section 7.4.3 "Slice Header Semantics". For further - documentation, refer to the above specification, unless there is - an explicit comment stating otherwise. - - .. note:: - - This compound control is not yet part of the public kernel API - and it is expected to change. - - This structure is expected to be passed as an array, with one - entry for each slice included in the bitstream buffer. - -.. c:type:: v4l2_ctrl_h264_slice_params - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_h264_slice_params - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u32 - - ``size`` - - - * - __u32 - - ``start_byte_offset`` - Offset (in bytes) from the beginning of the OUTPUT buffer to the start - of the slice. If the slice starts with a start code, then this is the - offset to such start code. When operating in slice-based decoding mode - (see :c:type:`v4l2_mpeg_video_h264_decode_mode`), this field should - be set to 0. When operating in frame-based decoding mode, this field - should be 0 for the first slice. - * - __u32 - - ``header_bit_size`` - - - * - __u16 - - ``first_mb_in_slice`` - - - * - __u8 - - ``slice_type`` - - - * - __u8 - - ``pic_parameter_set_id`` - - - * - __u8 - - ``colour_plane_id`` - - - * - __u8 - - ``redundant_pic_cnt`` - - - * - __u16 - - ``frame_num`` - - - * - __u16 - - ``idr_pic_id`` - - - * - __u16 - - ``pic_order_cnt_lsb`` - - - * - __s32 - - ``delta_pic_order_cnt_bottom`` - - - * - __s32 - - ``delta_pic_order_cnt0`` - - - * - __s32 - - ``delta_pic_order_cnt1`` - - - * - struct :c:type:`v4l2_h264_pred_weight_table` - - ``pred_weight_table`` - - - * - __u32 - - ``dec_ref_pic_marking_bit_size`` - - Size in bits of the dec_ref_pic_marking() syntax element. - * - __u32 - - ``pic_order_cnt_bit_size`` - - - * - __u8 - - ``cabac_init_idc`` - - - * - __s8 - - ``slice_qp_delta`` - - - * - __s8 - - ``slice_qs_delta`` - - - * - __u8 - - ``disable_deblocking_filter_idc`` - - - * - __s8 - - ``slice_alpha_c0_offset_div2`` - - - * - __s8 - - ``slice_beta_offset_div2`` - - - * - __u8 - - ``num_ref_idx_l0_active_minus1`` - - If num_ref_idx_active_override_flag is not set, this field must be - set to the value of num_ref_idx_l0_default_active_minus1. - * - __u8 - - ``num_ref_idx_l1_active_minus1`` - - If num_ref_idx_active_override_flag is not set, this field must be - set to the value of num_ref_idx_l1_default_active_minus1. - * - __u32 - - ``slice_group_change_cycle`` - - - * - __u8 - - ``ref_pic_list0[32]`` - - Reference picture list after applying the per-slice modifications - * - __u8 - - ``ref_pic_list1[32]`` - - Reference picture list after applying the per-slice modifications - * - __u32 - - ``flags`` - - See :ref:`Slice Parameter Flags <h264_slice_flags>` - -.. _h264_slice_flags: - -``Slice Parameter Set Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_H264_SLICE_FLAG_FIELD_PIC`` - - 0x00000001 - - - * - ``V4L2_H264_SLICE_FLAG_BOTTOM_FIELD`` - - 0x00000002 - - - * - ``V4L2_H264_SLICE_FLAG_DIRECT_SPATIAL_MV_PRED`` - - 0x00000004 - - - * - ``V4L2_H264_SLICE_FLAG_SP_FOR_SWITCH`` - - 0x00000008 - - - -``Prediction Weight Table`` - - The bitstream parameters are defined according to :ref:`h264`, - section 7.4.3.2 "Prediction Weight Table Semantics". For further - documentation, refer to the above specification, unless there is - an explicit comment stating otherwise. +``V4L2_CID_MPEG_VIDEO_H264_HIER_CODING_L1_BR (integer)`` + Indicates bit rate (bps) for hierarchical coding layer 1 for H264 encoder. -.. c:type:: v4l2_h264_pred_weight_table +``V4L2_CID_MPEG_VIDEO_H264_HIER_CODING_L2_BR (integer)`` + Indicates bit rate (bps) for hierarchical coding layer 2 for H264 encoder. -.. cssclass:: longtable +``V4L2_CID_MPEG_VIDEO_H264_HIER_CODING_L3_BR (integer)`` + Indicates bit rate (bps) for hierarchical coding layer 3 for H264 encoder. -.. flat-table:: struct v4l2_h264_pred_weight_table - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u16 - - ``luma_log2_weight_denom`` - - - * - __u16 - - ``chroma_log2_weight_denom`` - - - * - struct :c:type:`v4l2_h264_weight_factors` - - ``weight_factors[2]`` - - The weight factors at index 0 are the weight factors for the reference - list 0, the one at index 1 for the reference list 1. - -.. c:type:: v4l2_h264_weight_factors - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_h264_weight_factors - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __s16 - - ``luma_weight[32]`` - - - * - __s16 - - ``luma_offset[32]`` - - - * - __s16 - - ``chroma_weight[32][2]`` - - - * - __s16 - - ``chroma_offset[32][2]`` - - - -``V4L2_CID_MPEG_VIDEO_H264_DECODE_PARAMS (struct)`` - Specifies the decode parameters (as extracted from the bitstream) - for the associated H264 slice data. This includes the necessary - parameters for configuring a stateless hardware decoding pipeline - for H264. The bitstream parameters are defined according to - :ref:`h264`. For further documentation, refer to the above - specification, unless there is an explicit comment stating - otherwise. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_h264_decode_params - -.. cssclass:: longtable +``V4L2_CID_MPEG_VIDEO_H264_HIER_CODING_L4_BR (integer)`` + Indicates bit rate (bps) for hierarchical coding layer 4 for H264 encoder. -.. flat-table:: struct v4l2_ctrl_h264_decode_params - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - struct :c:type:`v4l2_h264_dpb_entry` - - ``dpb[16]`` - - - * - __u16 - - ``num_slices`` - - Number of slices needed to decode the current frame/field. When - operating in slice-based decoding mode (see - :c:type:`v4l2_mpeg_video_h264_decode_mode`), this field - should always be set to one. - * - __u16 - - ``nal_ref_idc`` - - NAL reference ID value coming from the NAL Unit header - * - __s32 - - ``top_field_order_cnt`` - - Picture Order Count for the coded top field - * - __s32 - - ``bottom_field_order_cnt`` - - Picture Order Count for the coded bottom field - * - __u32 - - ``flags`` - - See :ref:`Decode Parameters Flags <h264_decode_params_flags>` - -.. _h264_decode_params_flags: - -``Decode Parameters Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_H264_DECODE_PARAM_FLAG_IDR_PIC`` - - 0x00000001 - - That picture is an IDR picture +``V4L2_CID_MPEG_VIDEO_H264_HIER_CODING_L5_BR (integer)`` + Indicates bit rate (bps) for hierarchical coding layer 5 for H264 encoder. -.. c:type:: v4l2_h264_dpb_entry - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_h264_dpb_entry - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u64 - - ``reference_ts`` - - Timestamp of the V4L2 capture buffer to use as reference, used - with B-coded and P-coded frames. The timestamp refers to the - ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the - :c:func:`v4l2_timeval_to_ns()` function to convert the struct - :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. - * - __u16 - - ``frame_num`` - - - * - __u16 - - ``pic_num`` - - - * - __s32 - - ``top_field_order_cnt`` - - - * - __s32 - - ``bottom_field_order_cnt`` - - - * - __u32 - - ``flags`` - - See :ref:`DPB Entry Flags <h264_dpb_flags>` - -.. _h264_dpb_flags: - -``DPB Entries Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_H264_DPB_ENTRY_FLAG_VALID`` - - 0x00000001 - - The DPB entry is valid and should be considered - * - ``V4L2_H264_DPB_ENTRY_FLAG_ACTIVE`` - - 0x00000002 - - The DPB entry is currently being used as a reference frame - * - ``V4L2_H264_DPB_ENTRY_FLAG_LONG_TERM`` - - 0x00000004 - - The DPB entry is a long term reference frame - * - ``V4L2_H264_DPB_ENTRY_FLAG_FIELD`` - - 0x00000008 - - The DPB entry is a field reference, which means only one of the field - will be used when decoding the new frame/field. When not set the DPB - entry is a frame reference (both fields will be used). Note that this - flag does not say anything about the number of fields contained in the - reference frame, it just describes the one used to decode the new - field/frame - * - ``V4L2_H264_DPB_ENTRY_FLAG_BOTTOM_FIELD`` - - 0x00000010 - - The DPB entry is a bottom field reference (only the bottom field of the - reference frame is needed to decode the new frame/field). Only valid if - V4L2_H264_DPB_ENTRY_FLAG_FIELD is set. When - V4L2_H264_DPB_ENTRY_FLAG_FIELD is set but - V4L2_H264_DPB_ENTRY_FLAG_BOTTOM_FIELD is not, that means the - DPB entry is a top field reference - -``V4L2_CID_MPEG_VIDEO_H264_DECODE_MODE (enum)`` - Specifies the decoding mode to use. Currently exposes slice-based and - frame-based decoding but new modes might be added later on. - This control is used as a modifier for V4L2_PIX_FMT_H264_SLICE - pixel format. Applications that support V4L2_PIX_FMT_H264_SLICE - are required to set this control in order to specify the decoding mode - that is expected for the buffer. - Drivers may expose a single or multiple decoding modes, depending - on what they can support. - - .. note:: - - This menu control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_mpeg_video_h264_decode_mode - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_MPEG_VIDEO_H264_DECODE_MODE_SLICE_BASED`` - - 0 - - Decoding is done at the slice granularity. - In this mode, ``num_slices`` field in struct - :c:type:`v4l2_ctrl_h264_decode_params` should be set to 1, - and ``start_byte_offset`` in struct - :c:type:`v4l2_ctrl_h264_slice_params` should be set to 0. - The OUTPUT buffer must contain a single slice. - * - ``V4L2_MPEG_VIDEO_H264_DECODE_MODE_FRAME_BASED`` - - 1 - - Decoding is done at the frame granularity. - In this mode, ``num_slices`` field in struct - :c:type:`v4l2_ctrl_h264_decode_params` should be set to the number - of slices in the frame, and ``start_byte_offset`` in struct - :c:type:`v4l2_ctrl_h264_slice_params` should be set accordingly - for each slice. For the first slice, ``start_byte_offset`` should - be zero. - The OUTPUT buffer must contain all slices needed to decode the - frame. The OUTPUT buffer must also contain both fields. - -``V4L2_CID_MPEG_VIDEO_H264_START_CODE (enum)`` - Specifies the H264 slice start code expected for each slice. - This control is used as a modifier for V4L2_PIX_FMT_H264_SLICE - pixel format. Applications that support V4L2_PIX_FMT_H264_SLICE - are required to set this control in order to specify the start code - that is expected for the buffer. - Drivers may expose a single or multiple start codes, depending - on what they can support. - - .. note:: - - This menu control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_mpeg_video_h264_start_code - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_MPEG_VIDEO_H264_START_CODE_NONE`` - - 0 - - Selecting this value specifies that H264 slices are passed - to the driver without any start code. - * - ``V4L2_MPEG_VIDEO_H264_START_CODE_ANNEX_B`` - - 1 - - Selecting this value specifies that H264 slices are expected - to be prefixed by Annex B start codes. According to :ref:`h264` - valid start codes can be 3-bytes 0x000001 or 4-bytes 0x00000001. - -.. _v4l2-mpeg-mpeg2: - -``V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS (struct)`` - Specifies the slice parameters (as extracted from the bitstream) for the - associated MPEG-2 slice data. This includes the necessary parameters for - configuring a stateless hardware decoding pipeline for MPEG-2. - The bitstream parameters are defined according to :ref:`mpeg2part2`. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_mpeg2_slice_params - -.. cssclass:: longtable - -.. tabularcolumns:: |p{5.8cm}|p{4.8cm}|p{6.6cm}| - -.. flat-table:: struct v4l2_ctrl_mpeg2_slice_params - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u32 - - ``bit_size`` - - Size (in bits) of the current slice data. - * - __u32 - - ``data_bit_offset`` - - Offset (in bits) to the video data in the current slice data. - * - struct :c:type:`v4l2_mpeg2_sequence` - - ``sequence`` - - Structure with MPEG-2 sequence metadata, merging relevant fields from - the sequence header and sequence extension parts of the bitstream. - * - struct :c:type:`v4l2_mpeg2_picture` - - ``picture`` - - Structure with MPEG-2 picture metadata, merging relevant fields from - the picture header and picture coding extension parts of the bitstream. - * - __u64 - - ``backward_ref_ts`` - - Timestamp of the V4L2 capture buffer to use as backward reference, used - with B-coded and P-coded frames. The timestamp refers to the - ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the - :c:func:`v4l2_timeval_to_ns()` function to convert the struct - :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. - * - __u64 - - ``forward_ref_ts`` - - Timestamp for the V4L2 capture buffer to use as forward reference, used - with B-coded frames. The timestamp refers to the ``timestamp`` field in - struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` - function to convert the struct :c:type:`timeval` in struct - :c:type:`v4l2_buffer` to a __u64. - * - __u32 - - ``quantiser_scale_code`` - - Code used to determine the quantization scale to use for the IDCT. - -.. c:type:: v4l2_mpeg2_sequence - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_mpeg2_sequence - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u16 - - ``horizontal_size`` - - The width of the displayable part of the frame's luminance component. - * - __u16 - - ``vertical_size`` - - The height of the displayable part of the frame's luminance component. - * - __u32 - - ``vbv_buffer_size`` - - Used to calculate the required size of the video buffering verifier, - defined (in bits) as: 16 * 1024 * vbv_buffer_size. - * - __u16 - - ``profile_and_level_indication`` - - The current profile and level indication as extracted from the - bitstream. - * - __u8 - - ``progressive_sequence`` - - Indication that all the frames for the sequence are progressive instead - of interlaced. - * - __u8 - - ``chroma_format`` - - The chrominance sub-sampling format (1: 4:2:0, 2: 4:2:2, 3: 4:4:4). - -.. c:type:: v4l2_mpeg2_picture - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_mpeg2_picture - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``picture_coding_type`` - - Picture coding type for the frame covered by the current slice - (V4L2_MPEG2_PICTURE_CODING_TYPE_I, V4L2_MPEG2_PICTURE_CODING_TYPE_P or - V4L2_MPEG2_PICTURE_CODING_TYPE_B). - * - __u8 - - ``f_code[2][2]`` - - Motion vector codes. - * - __u8 - - ``intra_dc_precision`` - - Precision of Discrete Cosine transform (0: 8 bits precision, - 1: 9 bits precision, 2: 10 bits precision, 3: 11 bits precision). - * - __u8 - - ``picture_structure`` - - Picture structure (1: interlaced top field, 2: interlaced bottom field, - 3: progressive frame). - * - __u8 - - ``top_field_first`` - - If set to 1 and interlaced stream, top field is output first. - * - __u8 - - ``frame_pred_frame_dct`` - - If set to 1, only frame-DCT and frame prediction are used. - * - __u8 - - ``concealment_motion_vectors`` - - If set to 1, motion vectors are coded for intra macroblocks. - * - __u8 - - ``q_scale_type`` - - This flag affects the inverse quantization process. - * - __u8 - - ``intra_vlc_format`` - - This flag affects the decoding of transform coefficient data. - * - __u8 - - ``alternate_scan`` - - This flag affects the decoding of transform coefficient data. - * - __u8 - - ``repeat_first_field`` - - This flag affects the decoding process of progressive frames. - * - __u16 - - ``progressive_frame`` - - Indicates whether the current frame is progressive. - -``V4L2_CID_MPEG_VIDEO_MPEG2_QUANTIZATION (struct)`` - Specifies quantization matrices (as extracted from the bitstream) for the - associated MPEG-2 slice data. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_mpeg2_quantization - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.2cm}|p{8.0cm}|p{7.4cm}| - -.. raw:: latex - - \small - -.. flat-table:: struct v4l2_ctrl_mpeg2_quantization - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``load_intra_quantiser_matrix`` - - One bit to indicate whether to load the ``intra_quantiser_matrix`` data. - * - __u8 - - ``load_non_intra_quantiser_matrix`` - - One bit to indicate whether to load the ``non_intra_quantiser_matrix`` - data. - * - __u8 - - ``load_chroma_intra_quantiser_matrix`` - - One bit to indicate whether to load the - ``chroma_intra_quantiser_matrix`` data, only relevant for non-4:2:0 YUV - formats. - * - __u8 - - ``load_chroma_non_intra_quantiser_matrix`` - - One bit to indicate whether to load the - ``chroma_non_intra_quantiser_matrix`` data, only relevant for non-4:2:0 - YUV formats. - * - __u8 - - ``intra_quantiser_matrix[64]`` - - The quantization matrix coefficients for intra-coded frames, in zigzag - scanning order. It is relevant for both luma and chroma components, - although it can be superseded by the chroma-specific matrix for - non-4:2:0 YUV formats. - * - __u8 - - ``non_intra_quantiser_matrix[64]`` - - The quantization matrix coefficients for non-intra-coded frames, in - zigzag scanning order. It is relevant for both luma and chroma - components, although it can be superseded by the chroma-specific matrix - for non-4:2:0 YUV formats. - * - __u8 - - ``chroma_intra_quantiser_matrix[64]`` - - The quantization matrix coefficients for the chominance component of - intra-coded frames, in zigzag scanning order. Only relevant for - non-4:2:0 YUV formats. - * - __u8 - - ``chroma_non_intra_quantiser_matrix[64]`` - - The quantization matrix coefficients for the chrominance component of - non-intra-coded frames, in zigzag scanning order. Only relevant for - non-4:2:0 YUV formats. +``V4L2_CID_MPEG_VIDEO_H264_HIER_CODING_L6_BR (integer)`` + Indicates bit rate (bps) for hierarchical coding layer 6 for H264 encoder. ``V4L2_CID_FWHT_I_FRAME_QP (integer)`` Quantization parameter for an I frame for FWHT. Valid range: from 1 @@ -2345,328 +1653,19 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - Quantization parameter for a P frame for FWHT. Valid range: from 1 to 31. -.. _v4l2-mpeg-vp8: - -``V4L2_CID_MPEG_VIDEO_VP8_FRAME_HEADER (struct)`` - Specifies the frame parameters for the associated VP8 parsed frame data. - This includes the necessary parameters for - configuring a stateless hardware decoding pipeline for VP8. - The bitstream parameters are defined according to :ref:`vp8`. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_vp8_frame_header - -.. cssclass:: longtable - -.. tabularcolumns:: |p{5.8cm}|p{4.8cm}|p{6.6cm}| - -.. flat-table:: struct v4l2_ctrl_vp8_frame_header - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - struct :c:type:`v4l2_vp8_segment_header` - - ``segment_header`` - - Structure with segment-based adjustments metadata. - * - struct :c:type:`v4l2_vp8_loopfilter_header` - - ``loopfilter_header`` - - Structure with loop filter level adjustments metadata. - * - struct :c:type:`v4l2_vp8_quantization_header` - - ``quant_header`` - - Structure with VP8 dequantization indices metadata. - * - struct :c:type:`v4l2_vp8_entropy_header` - - ``entropy_header`` - - Structure with VP8 entropy coder probabilities metadata. - * - struct :c:type:`v4l2_vp8_entropy_coder_state` - - ``coder_state`` - - Structure with VP8 entropy coder state. - * - __u16 - - ``width`` - - The width of the frame. Must be set for all frames. - * - __u16 - - ``height`` - - The height of the frame. Must be set for all frames. - * - __u8 - - ``horizontal_scale`` - - Horizontal scaling factor. - * - __u8 - - ``vertical_scaling factor`` - - Vertical scale. - * - __u8 - - ``version`` - - Bitstream version. - * - __u8 - - ``prob_skip_false`` - - Indicates the probability that the macroblock is not skipped. - * - __u8 - - ``prob_intra`` - - Indicates the probability that a macroblock is intra-predicted. - * - __u8 - - ``prob_last`` - - Indicates the probability that the last reference frame is used - for inter-prediction - * - __u8 - - ``prob_gf`` - - Indicates the probability that the golden reference frame is used - for inter-prediction - * - __u8 - - ``num_dct_parts`` - - Number of DCT coefficients partitions. Must be one of: 1, 2, 4, or 8. - * - __u32 - - ``first_part_size`` - - Size of the first partition, i.e. the control partition. - * - __u32 - - ``first_part_header_bits`` - - Size in bits of the first partition header portion. - * - __u32 - - ``dct_part_sizes[8]`` - - DCT coefficients sizes. - * - __u64 - - ``last_frame_ts`` - - Timestamp for the V4L2 capture buffer to use as last reference frame, used - with inter-coded frames. The timestamp refers to the ``timestamp`` field in - struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` - function to convert the struct :c:type:`timeval` in struct - :c:type:`v4l2_buffer` to a __u64. - * - __u64 - - ``golden_frame_ts`` - - Timestamp for the V4L2 capture buffer to use as last reference frame, used - with inter-coded frames. The timestamp refers to the ``timestamp`` field in - struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` - function to convert the struct :c:type:`timeval` in struct - :c:type:`v4l2_buffer` to a __u64. - * - __u64 - - ``alt_frame_ts`` - - Timestamp for the V4L2 capture buffer to use as alternate reference frame, used - with inter-coded frames. The timestamp refers to the ``timestamp`` field in - struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` - function to convert the struct :c:type:`timeval` in struct - :c:type:`v4l2_buffer` to a __u64. - * - __u64 - - ``flags`` - - See :ref:`Frame Header Flags <vp8_frame_header_flags>` - -.. _vp8_frame_header_flags: - -``Frame Header Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_VP8_FRAME_HEADER_FLAG_KEY_FRAME`` - - 0x01 - - Indicates if the frame is a key frame. - * - ``V4L2_VP8_FRAME_HEADER_FLAG_EXPERIMENTAL`` - - 0x02 - - Experimental bitstream. - * - ``V4L2_VP8_FRAME_HEADER_FLAG_SHOW_FRAME`` - - 0x04 - - Show frame flag, indicates if the frame is for display. - * - ``V4L2_VP8_FRAME_HEADER_FLAG_MB_NO_SKIP_COEFF`` - - 0x08 - - Enable/disable skipping of macroblocks with no non-zero coefficients. - * - ``V4L2_VP8_FRAME_HEADER_FLAG_SIGN_BIAS_GOLDEN`` - - 0x10 - - Sign of motion vectors when the golden frame is referenced. - * - ``V4L2_VP8_FRAME_HEADER_FLAG_SIGN_BIAS_ALT`` - - 0x20 - - Sign of motion vectors when the alt frame is referenced. - -.. c:type:: v4l2_vp8_entropy_coder_state - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_vp8_entropy_coder_state - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``range`` - - - * - __u8 - - ``value`` - - - * - __u8 - - ``bit_count`` - - - * - __u8 - - ``padding`` - - Applications and drivers must set this to zero. - -.. c:type:: v4l2_vp8_segment_header - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_vp8_segment_header - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __s8 - - ``quant_update[4]`` - - Signed quantizer value update. - * - __s8 - - ``lf_update[4]`` - - Signed loop filter level value update. - * - __u8 - - ``segment_probs[3]`` - - Segment probabilities. - * - __u8 - - ``padding`` - - Applications and drivers must set this to zero. - * - __u32 - - ``flags`` - - See :ref:`Segment Header Flags <vp8_segment_header_flags>` - -.. _vp8_segment_header_flags: - -``Segment Header Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_ENABLED`` - - 0x01 - - Enable/disable segment-based adjustments. - * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_UPDATE_MAP`` - - 0x02 - - Indicates if the macroblock segmentation map is updated in this frame. - * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_UPDATE_FEATURE_DATA`` - - 0x04 - - Indicates if the segment feature data is updated in this frame. - * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_DELTA_VALUE_MODE`` - - 0x08 - - If is set, the segment feature data mode is delta-value. - If cleared, it's absolute-value. - -.. c:type:: v4l2_vp8_loopfilter_header - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_vp8_loopfilter_header - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __s8 - - ``ref_frm_delta[4]`` - - Reference adjustment (signed) delta value. - * - __s8 - - ``mb_mode_delta[4]`` - - Macroblock prediction mode adjustment (signed) delta value. - * - __u8 - - ``sharpness_level`` - - Sharpness level - * - __u8 - - ``level`` - - Filter level - * - __u16 - - ``padding`` - - Applications and drivers must set this to zero. - * - __u32 - - ``flags`` - - See :ref:`Loopfilter Header Flags <vp8_loopfilter_header_flags>` - -.. _vp8_loopfilter_header_flags: - -``Loopfilter Header Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_VP8_LF_HEADER_ADJ_ENABLE`` - - 0x01 - - Enable/disable macroblock-level loop filter adjustment. - * - ``V4L2_VP8_LF_HEADER_DELTA_UPDATE`` - - 0x02 - - Indicates if the delta values used in an adjustment are updated. - * - ``V4L2_VP8_LF_FILTER_TYPE_SIMPLE`` - - 0x04 - - If set, indicates the filter type is simple. - If cleared, the filter type is normal. - -.. c:type:: v4l2_vp8_quantization_header - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_vp8_quantization_header - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``y_ac_qi`` - - Luma AC coefficient table index. - * - __s8 - - ``y_dc_delta`` - - Luma DC delta vaue. - * - __s8 - - ``y2_dc_delta`` - - Y2 block DC delta value. - * - __s8 - - ``y2_ac_delta`` - - Y2 block AC delta value. - * - __s8 - - ``uv_dc_delta`` - - Chroma DC delta value. - * - __s8 - - ``uv_ac_delta`` - - Chroma AC delta value. - * - __u16 - - ``padding`` - - Applications and drivers must set this to zero. - -.. c:type:: v4l2_vp8_entropy_header - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_vp8_entropy_header - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``coeff_probs[4][8][3][11]`` - - Coefficient update probabilities. - * - __u8 - - ``y_mode_probs[4]`` - - Luma mode update probabilities. - * - __u8 - - ``uv_mode_probs[3]`` - - Chroma mode update probabilities. - * - __u8 - - ``mv_probs[2][19]`` - - MV decoding update probabilities. - * - __u8 - - ``padding[3]`` - - Applications and drivers must set this to zero. +``V4L2_CID_MPEG_VIDEO_AVERAGE_QP (integer)`` + This read-only control returns the average QP value of the currently + encoded frame. The value applies to the last dequeued capture buffer + (VIDIOC_DQBUF). Its valid range depends on the encoding format and parameters. + For H264, its valid range is from 0 to 51. + For HEVC, its valid range is from 0 to 51 for 8 bit and + from 0 to 63 for 10 bit. + For H263 and MPEG4, its valid range is from 1 to 31. + For VP8, its valid range is from 0 to 127. + For VP9, its valid range is from 0 to 255. + If the codec's MIN_QP and MAX_QP are set, then the QP will meet both requirements. + Codecs need to always use the specified range, rather then a HW custom range. + Applicable to encoders .. raw:: latex @@ -2694,6 +1693,11 @@ MFC 5.1 Control IDs feature can be used for example for generating thumbnails of videos. Applicable to the H264 decoder. + .. note:: + + This control is deprecated. Use the standard + ``V4L2_CID_MPEG_VIDEO_DEC_DISPLAY_DELAY_ENABLE`` control instead. + ``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY (integer)`` Display delay value for H264 decoder. The decoder is forced to return a decoded frame after the set 'display delay' number of @@ -2701,6 +1705,11 @@ MFC 5.1 Control IDs of display order, in addition the hardware may still be using the returned buffer as a reference picture for subsequent frames. + .. note:: + + This control is deprecated. Use the standard + ``V4L2_CID_MPEG_VIDEO_DEC_DISPLAY_DELAY`` control instead. + ``V4L2_CID_MPEG_MFC51_VIDEO_H264_NUM_REF_PIC_FOR_P (integer)`` The number of reference pictures used for encoding a P picture. Applicable to the H264 encoder. @@ -2773,6 +1782,11 @@ MFC 5.1 Control IDs ``V4L2_CID_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE`` (enum) + .. note:: + + This control is deprecated. Use the standard + ``V4L2_CID_MPEG_VIDEO_FRAME_SKIP_MODE`` control instead. + enum v4l2_mpeg_mfc51_video_frame_skip_mode - Indicates in what conditions the encoder should skip frames. If encoding a frame would cause the encoded stream to be larger then a @@ -2780,7 +1794,7 @@ enum v4l2_mpeg_mfc51_video_frame_skip_mode - are: -.. tabularcolumns:: |p{9.2cm}|p{8.3cm}| +.. tabularcolumns:: |p{9.4cm}|p{8.1cm}| .. raw:: latex @@ -2790,12 +1804,12 @@ enum v4l2_mpeg_mfc51_video_frame_skip_mode - :header-rows: 0 :stub-columns: 0 - * - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_DISABLED`` + * - ``V4L2_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE_DISABLED`` - Frame skip mode is disabled. - * - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_LEVEL_LIMIT`` + * - ``V4L2_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE_LEVEL_LIMIT`` - Frame skip mode enabled and buffer limit is set by the chosen level and is defined by the standard. - * - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_BUF_LIMIT`` + * - ``V4L2_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE_BUF_LIMIT`` - Frame skip mode enabled and buffer limit is set by the VBV (MPEG1/2/4) or CPB (H264) buffer size control. @@ -2824,7 +1838,7 @@ enum v4l2_mpeg_mfc51_video_force_frame_type - Force a frame type for the next queued buffer. Applicable to encoders. Possible values are: -.. tabularcolumns:: |p{9.5cm}|p{8.0cm}| +.. tabularcolumns:: |p{9.9cm}|p{7.6cm}| .. flat-table:: :header-rows: 0 @@ -2838,127 +1852,6 @@ enum v4l2_mpeg_mfc51_video_force_frame_type - - Force a non-coded frame. -.. _v4l2-mpeg-fwht: - -``V4L2_CID_MPEG_VIDEO_FWHT_PARAMS (struct)`` - Specifies the fwht parameters (as extracted from the bitstream) for the - associated FWHT data. This includes the necessary parameters for - configuring a stateless hardware decoding pipeline for FWHT. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_fwht_params - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.4cm}|p{4.3cm}|p{11.8cm}| - -.. flat-table:: struct v4l2_ctrl_fwht_params - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u64 - - ``backward_ref_ts`` - - Timestamp of the V4L2 capture buffer to use as backward reference, used - with P-coded frames. The timestamp refers to the - ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the - :c:func:`v4l2_timeval_to_ns()` function to convert the struct - :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. - * - __u32 - - ``version`` - - The version of the codec - * - __u32 - - ``width`` - - The width of the frame - * - __u32 - - ``height`` - - The height of the frame - * - __u32 - - ``flags`` - - The flags of the frame, see :ref:`fwht-flags`. - * - __u32 - - ``colorspace`` - - The colorspace of the frame, from enum :c:type:`v4l2_colorspace`. - * - __u32 - - ``xfer_func`` - - The transfer function, from enum :c:type:`v4l2_xfer_func`. - * - __u32 - - ``ycbcr_enc`` - - The Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`. - * - __u32 - - ``quantization`` - - The quantization range, from enum :c:type:`v4l2_quantization`. - - - -.. _fwht-flags: - -FWHT Flags -============ - -.. cssclass:: longtable - -.. tabularcolumns:: |p{6.8cm}|p{2.4cm}|p{8.3cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * - ``FWHT_FL_IS_INTERLACED`` - - 0x00000001 - - Set if this is an interlaced format - * - ``FWHT_FL_IS_BOTTOM_FIRST`` - - 0x00000002 - - Set if this is a bottom-first (NTSC) interlaced format - * - ``FWHT_FL_IS_ALTERNATE`` - - 0x00000004 - - Set if each 'frame' contains just one field - * - ``FWHT_FL_IS_BOTTOM_FIELD`` - - 0x00000008 - - If FWHT_FL_IS_ALTERNATE was set, then this is set if this 'frame' is the - bottom field, else it is the top field. - * - ``FWHT_FL_LUMA_IS_UNCOMPRESSED`` - - 0x00000010 - - Set if the luma plane is uncompressed - * - ``FWHT_FL_CB_IS_UNCOMPRESSED`` - - 0x00000020 - - Set if the cb plane is uncompressed - * - ``FWHT_FL_CR_IS_UNCOMPRESSED`` - - 0x00000040 - - Set if the cr plane is uncompressed - * - ``FWHT_FL_CHROMA_FULL_HEIGHT`` - - 0x00000080 - - Set if the chroma plane has the same height as the luma plane, - else the chroma plane is half the height of the luma plane - * - ``FWHT_FL_CHROMA_FULL_WIDTH`` - - 0x00000100 - - Set if the chroma plane has the same width as the luma plane, - else the chroma plane is half the width of the luma plane - * - ``FWHT_FL_ALPHA_IS_UNCOMPRESSED`` - - 0x00000200 - - Set if the alpha plane is uncompressed - * - ``FWHT_FL_I_FRAME`` - - 0x00000400 - - Set if this is an I-frame - * - ``FWHT_FL_COMPONENTS_NUM_MSK`` - - 0x00070000 - - A 4-values flag - the number of components - 1 - * - ``FWHT_FL_PIXENC_YUV`` - - 0x00080000 - - Set if the pixel encoding is YUV - * - ``FWHT_FL_PIXENC_RGB`` - - 0x00100000 - - Set if the pixel encoding is RGB - * - ``FWHT_FL_PIXENC_HSV`` - - 0x00180000 - - Set if the pixel encoding is HSV - - CX2341x MPEG Controls ===================== @@ -2981,6 +1874,7 @@ enum v4l2_mpeg_cx2341x_video_spatial_filter_mode - are: +.. tabularcolumns:: |p{11.5cm}|p{6.0cm}| .. flat-table:: :header-rows: 0 @@ -3006,11 +1900,11 @@ enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type - Select the algorithm to use for the Luma Spatial Filter (default ``1D_HOR``). Possible values: -.. tabularcolumns:: |p{14.5cm}|p{3.0cm}| +.. tabularcolumns:: |p{13.1cm}|p{4.4cm}| .. raw:: latex - \small + \footnotesize .. flat-table:: :header-rows: 0 @@ -3031,8 +1925,6 @@ enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type - \normalsize - - .. _chroma-spatial-filter-type: ``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE`` @@ -3042,8 +1934,11 @@ enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type - Select the algorithm for the Chroma Spatial Filter (default ``1D_HOR``). Possible values are: +.. raw:: latex -.. tabularcolumns:: |p{14.0cm}|p{3.5cm}| + \footnotesize + +.. tabularcolumns:: |p{11.0cm}|p{6.5cm}| .. flat-table:: :header-rows: 0 @@ -3054,7 +1949,9 @@ enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type - * - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR`` - One-dimensional horizontal +.. raw:: latex + \normalsize .. _v4l2-mpeg-cx2341x-video-temporal-filter-mode: @@ -3065,7 +1962,9 @@ enum v4l2_mpeg_cx2341x_video_temporal_filter_mode - Sets the Temporal Filter mode (default ``MANUAL``). Possible values are: +.. raw:: latex + \footnotesize .. flat-table:: :header-rows: 0 @@ -3076,7 +1975,9 @@ enum v4l2_mpeg_cx2341x_video_temporal_filter_mode - * - ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO`` - Choose the filter automatically +.. raw:: latex + \normalsize ``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER (integer (0-31))`` The setting for the Temporal Filter. 0 = off, 31 = maximum. (Default @@ -3091,6 +1992,11 @@ enum v4l2_mpeg_cx2341x_video_median_filter_type - Median Filter Type (default ``OFF``). Possible values are: +.. raw:: latex + + \small + +.. tabularcolumns:: |p{11.0cm}|p{6.5cm}| .. flat-table:: :header-rows: 0 @@ -3107,7 +2013,9 @@ enum v4l2_mpeg_cx2341x_video_median_filter_type - * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG`` - Diagonal filter +.. raw:: latex + \normalsize ``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM (integer (0-255))`` Threshold above which the luminance median filter is enabled @@ -3184,7 +2092,7 @@ enum v4l2_vp8_num_ref_frames - The number of reference pictures for encoding P frames. Possible values are: -.. tabularcolumns:: |p{7.9cm}|p{9.6cm}| +.. tabularcolumns:: |p{7.5cm}|p{7.5cm}| .. raw:: latex @@ -3239,7 +2147,7 @@ enum v4l2_vp8_golden_frame_sel - \scriptsize -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| +.. tabularcolumns:: |p{8.6cm}|p{8.9cm}| .. flat-table:: :header-rows: 0 @@ -3316,6 +2224,49 @@ enum v4l2_mpeg_video_vp9_profile - * - ``V4L2_MPEG_VIDEO_VP9_PROFILE_3`` - Profile 3 +.. _v4l2-mpeg-video-vp9-level: + +``V4L2_CID_MPEG_VIDEO_VP9_LEVEL (enum)`` + +enum v4l2_mpeg_video_vp9_level - + This control allows selecting the level for VP9 encoder. + This is also used to enumerate supported levels by VP9 encoder or decoder. + More information can be found at + `webmproject <https://www.webmproject.org/vp9/levels/>`__. Possible values are: + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_1_0`` + - Level 1 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_1_1`` + - Level 1.1 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_2_0`` + - Level 2 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_2_1`` + - Level 2.1 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_3_0`` + - Level 3 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_3_1`` + - Level 3.1 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_4_0`` + - Level 4 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_4_1`` + - Level 4.1 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_5_0`` + - Level 5 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_5_1`` + - Level 5.1 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_5_2`` + - Level 5.2 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_6_0`` + - Level 6 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_6_1`` + - Level 6.1 + * - ``V4L2_MPEG_VIDEO_VP9_LEVEL_6_2`` + - Level 6.2 + High Efficiency Video Coding (HEVC/H.265) Control Reference =========================================================== @@ -3331,11 +2282,11 @@ HEVC/H.265 Control IDs ``V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP (integer)`` Minimum quantization parameter for HEVC. - Valid range: from 0 to 51. + Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. ``V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP (integer)`` Maximum quantization parameter for HEVC. - Valid range: from 0 to 51. + Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. ``V4L2_CID_MPEG_VIDEO_HEVC_I_FRAME_QP (integer)`` Quantization parameter for an I frame for HEVC. @@ -3352,6 +2303,42 @@ HEVC/H.265 Control IDs Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. +``V4L2_CID_MPEG_VIDEO_HEVC_I_FRAME_MIN_QP (integer)`` + Minimum quantization parameter for the HEVC I frame to limit I frame + quality to a range. Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. + If V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_HEVC_I_FRAME_MAX_QP (integer)`` + Maximum quantization parameter for the HEVC I frame to limit I frame + quality to a range. Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. + If V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_HEVC_P_FRAME_MIN_QP (integer)`` + Minimum quantization parameter for the HEVC P frame to limit P frame + quality to a range. Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. + If V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_HEVC_P_FRAME_MAX_QP (integer)`` + Maximum quantization parameter for the HEVC P frame to limit P frame + quality to a range. Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. + If V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_HEVC_B_FRAME_MIN_QP (integer)`` + Minimum quantization parameter for the HEVC B frame to limit B frame + quality to a range. Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. + If V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_HEVC_B_FRAME_MAX_QP (integer)`` + Maximum quantization parameter for the HEVC B frame to limit B frame + quality to a range. Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. + If V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP is also set, the quantization parameter + should be chosen to meet both requirements. + ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_QP (boolean)`` HIERARCHICAL_QP allows the host to specify the quantization parameter values for each temporal layer through HIERARCHICAL_QP_LAYER. This is @@ -3370,7 +2357,7 @@ enum v4l2_mpeg_video_hevc_hier_coding_type - \footnotesize -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| +.. tabularcolumns:: |p{8.2cm}|p{9.3cm}| .. flat-table:: :header-rows: 0 @@ -3439,7 +2426,7 @@ enum v4l2_mpeg_video_hevc_profile - \footnotesize -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| +.. tabularcolumns:: |p{9.0cm}|p{8.5cm}| .. flat-table:: :header-rows: 0 @@ -3465,47 +2452,21 @@ enum v4l2_mpeg_video_hevc_profile - enum v4l2_mpeg_video_hevc_level - Selects the desired level for HEVC encoder. -.. raw:: latex - - \footnotesize - -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_1`` - - Level 1.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_2`` - - Level 2.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_2_1`` - - Level 2.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_3`` - - Level 3.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_3_1`` - - Level 3.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_4`` - - Level 4.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_4_1`` - - Level 4.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5`` - - Level 5.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_1`` - - Level 5.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_2`` - - Level 5.2 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6`` - - Level 6.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_1`` - - Level 6.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_2`` - - Level 6.2 - -.. raw:: latex - - \normalsize - +================================== ========= +``V4L2_MPEG_VIDEO_HEVC_LEVEL_1`` Level 1.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_2`` Level 2.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_2_1`` Level 2.1 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_3`` Level 3.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_3_1`` Level 3.1 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_4`` Level 4.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_4_1`` Level 4.1 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_5`` Level 5.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_1`` Level 5.1 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_2`` Level 5.2 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_6`` Level 6.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_1`` Level 6.1 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_2`` Level 6.2 +================================== ========= ``V4L2_CID_MPEG_VIDEO_HEVC_FRAME_RATE_RESOLUTION (integer)`` Indicates the number of evenly spaced subintervals, called ticks, within @@ -3524,24 +2485,10 @@ enum v4l2_mpeg_video_hevc_tier - this flag to 1 indicates High tier. High tier is for applications requiring high bit rates. -.. raw:: latex - - \footnotesize - -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_HEVC_TIER_MAIN`` - - Main tier. - * - ``V4L2_MPEG_VIDEO_HEVC_TIER_HIGH`` - - High tier. - -.. raw:: latex - - \normalsize +================================== ========== +``V4L2_MPEG_VIDEO_HEVC_TIER_MAIN`` Main tier. +``V4L2_MPEG_VIDEO_HEVC_TIER_HIGH`` High tier. +================================== ========== ``V4L2_CID_MPEG_VIDEO_HEVC_MAX_PARTITION_DEPTH (integer)`` @@ -3597,7 +2544,7 @@ enum v4l2_mpeg_video_hevc_hier_refresh_type - \footnotesize -.. tabularcolumns:: |p{8.0cm}|p{9.0cm}| +.. tabularcolumns:: |p{6.2cm}|p{11.3cm}| .. flat-table:: :header-rows: 0 @@ -3677,7 +2624,7 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - \footnotesize -.. tabularcolumns:: |p{6.0cm}|p{11.0cm}| +.. tabularcolumns:: |p{5.5cm}|p{12.0cm}| .. flat-table:: :header-rows: 0 @@ -3725,550 +2672,3 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - Indicates whether to generate SPS and PPS at every IDR. Setting it to 0 disables generating SPS and PPS at every IDR. Setting it to one enables generating SPS and PPS at every IDR. - -.. _v4l2-mpeg-hevc: - -``V4L2_CID_MPEG_VIDEO_HEVC_SPS (struct)`` - Specifies the Sequence Parameter Set fields (as extracted from the - bitstream) for the associated HEVC slice data. - These bitstream parameters are defined according to :ref:`hevc`. - They are described in section 7.4.3.2 "Sequence parameter set RBSP - semantics" of the specification. - -.. c:type:: v4l2_ctrl_hevc_sps - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_hevc_sps - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u16 - - ``pic_width_in_luma_samples`` - - - * - __u16 - - ``pic_height_in_luma_samples`` - - - * - __u8 - - ``bit_depth_luma_minus8`` - - - * - __u8 - - ``bit_depth_chroma_minus8`` - - - * - __u8 - - ``log2_max_pic_order_cnt_lsb_minus4`` - - - * - __u8 - - ``sps_max_dec_pic_buffering_minus1`` - - - * - __u8 - - ``sps_max_num_reorder_pics`` - - - * - __u8 - - ``sps_max_latency_increase_plus1`` - - - * - __u8 - - ``log2_min_luma_coding_block_size_minus3`` - - - * - __u8 - - ``log2_diff_max_min_luma_coding_block_size`` - - - * - __u8 - - ``log2_min_luma_transform_block_size_minus2`` - - - * - __u8 - - ``log2_diff_max_min_luma_transform_block_size`` - - - * - __u8 - - ``max_transform_hierarchy_depth_inter`` - - - * - __u8 - - ``max_transform_hierarchy_depth_intra`` - - - * - __u8 - - ``pcm_sample_bit_depth_luma_minus1`` - - - * - __u8 - - ``pcm_sample_bit_depth_chroma_minus1`` - - - * - __u8 - - ``log2_min_pcm_luma_coding_block_size_minus3`` - - - * - __u8 - - ``log2_diff_max_min_pcm_luma_coding_block_size`` - - - * - __u8 - - ``num_short_term_ref_pic_sets`` - - - * - __u8 - - ``num_long_term_ref_pics_sps`` - - - * - __u8 - - ``chroma_format_idc`` - - - * - __u64 - - ``flags`` - - See :ref:`Sequence Parameter Set Flags <hevc_sps_flags>` - -.. _hevc_sps_flags: - -``Sequence Parameter Set Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_HEVC_SPS_FLAG_SEPARATE_COLOUR_PLANE`` - - 0x00000001 - - - * - ``V4L2_HEVC_SPS_FLAG_SCALING_LIST_ENABLED`` - - 0x00000002 - - - * - ``V4L2_HEVC_SPS_FLAG_AMP_ENABLED`` - - 0x00000004 - - - * - ``V4L2_HEVC_SPS_FLAG_SAMPLE_ADAPTIVE_OFFSET`` - - 0x00000008 - - - * - ``V4L2_HEVC_SPS_FLAG_PCM_ENABLED`` - - 0x00000010 - - - * - ``V4L2_HEVC_SPS_FLAG_PCM_LOOP_FILTER_DISABLED`` - - 0x00000020 - - - * - ``V4L2_HEVC_SPS_FLAG_LONG_TERM_REF_PICS_PRESENT`` - - 0x00000040 - - - * - ``V4L2_HEVC_SPS_FLAG_SPS_TEMPORAL_MVP_ENABLED`` - - 0x00000080 - - - * - ``V4L2_HEVC_SPS_FLAG_STRONG_INTRA_SMOOTHING_ENABLED`` - - 0x00000100 - - - -``V4L2_CID_MPEG_VIDEO_HEVC_PPS (struct)`` - Specifies the Picture Parameter Set fields (as extracted from the - bitstream) for the associated HEVC slice data. - These bitstream parameters are defined according to :ref:`hevc`. - They are described in section 7.4.3.3 "Picture parameter set RBSP - semantics" of the specification. - -.. c:type:: v4l2_ctrl_hevc_pps - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_hevc_pps - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``num_extra_slice_header_bits`` - - - * - __s8 - - ``init_qp_minus26`` - - - * - __u8 - - ``diff_cu_qp_delta_depth`` - - - * - __s8 - - ``pps_cb_qp_offset`` - - - * - __s8 - - ``pps_cr_qp_offset`` - - - * - __u8 - - ``num_tile_columns_minus1`` - - - * - __u8 - - ``num_tile_rows_minus1`` - - - * - __u8 - - ``column_width_minus1[20]`` - - - * - __u8 - - ``row_height_minus1[22]`` - - - * - __s8 - - ``pps_beta_offset_div2`` - - - * - __s8 - - ``pps_tc_offset_div2`` - - - * - __u8 - - ``log2_parallel_merge_level_minus2`` - - - * - __u8 - - ``padding[4]`` - - Applications and drivers must set this to zero. - * - __u64 - - ``flags`` - - See :ref:`Picture Parameter Set Flags <hevc_pps_flags>` - -.. _hevc_pps_flags: - -``Picture Parameter Set Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_HEVC_PPS_FLAG_DEPENDENT_SLICE_SEGMENT`` - - 0x00000001 - - - * - ``V4L2_HEVC_PPS_FLAG_OUTPUT_FLAG_PRESENT`` - - 0x00000002 - - - * - ``V4L2_HEVC_PPS_FLAG_SIGN_DATA_HIDING_ENABLED`` - - 0x00000004 - - - * - ``V4L2_HEVC_PPS_FLAG_CABAC_INIT_PRESENT`` - - 0x00000008 - - - * - ``V4L2_HEVC_PPS_FLAG_CONSTRAINED_INTRA_PRED`` - - 0x00000010 - - - * - ``V4L2_HEVC_PPS_FLAG_TRANSFORM_SKIP_ENABLED`` - - 0x00000020 - - - * - ``V4L2_HEVC_PPS_FLAG_CU_QP_DELTA_ENABLED`` - - 0x00000040 - - - * - ``V4L2_HEVC_PPS_FLAG_PPS_SLICE_CHROMA_QP_OFFSETS_PRESENT`` - - 0x00000080 - - - * - ``V4L2_HEVC_PPS_FLAG_WEIGHTED_PRED`` - - 0x00000100 - - - * - ``V4L2_HEVC_PPS_FLAG_WEIGHTED_BIPRED`` - - 0x00000200 - - - * - ``V4L2_HEVC_PPS_FLAG_TRANSQUANT_BYPASS_ENABLED`` - - 0x00000400 - - - * - ``V4L2_HEVC_PPS_FLAG_TILES_ENABLED`` - - 0x00000800 - - - * - ``V4L2_HEVC_PPS_FLAG_ENTROPY_CODING_SYNC_ENABLED`` - - 0x00001000 - - - * - ``V4L2_HEVC_PPS_FLAG_LOOP_FILTER_ACROSS_TILES_ENABLED`` - - 0x00002000 - - - * - ``V4L2_HEVC_PPS_FLAG_PPS_LOOP_FILTER_ACROSS_SLICES_ENABLED`` - - 0x00004000 - - - * - ``V4L2_HEVC_PPS_FLAG_DEBLOCKING_FILTER_OVERRIDE_ENABLED`` - - 0x00008000 - - - * - ``V4L2_HEVC_PPS_FLAG_PPS_DISABLE_DEBLOCKING_FILTER`` - - 0x00010000 - - - * - ``V4L2_HEVC_PPS_FLAG_LISTS_MODIFICATION_PRESENT`` - - 0x00020000 - - - * - ``V4L2_HEVC_PPS_FLAG_SLICE_SEGMENT_HEADER_EXTENSION_PRESENT`` - - 0x00040000 - - - -``V4L2_CID_MPEG_VIDEO_HEVC_SLICE_PARAMS (struct)`` - Specifies various slice-specific parameters, especially from the NAL unit - header, general slice segment header and weighted prediction parameter - parts of the bitstream. - These bitstream parameters are defined according to :ref:`hevc`. - They are described in section 7.4.7 "General slice segment header - semantics" of the specification. - -.. c:type:: v4l2_ctrl_hevc_slice_params - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_hevc_slice_params - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u32 - - ``bit_size`` - - Size (in bits) of the current slice data. - * - __u32 - - ``data_bit_offset`` - - Offset (in bits) to the video data in the current slice data. - * - __u8 - - ``nal_unit_type`` - - - * - __u8 - - ``nuh_temporal_id_plus1`` - - - * - __u8 - - ``slice_type`` - - - (V4L2_HEVC_SLICE_TYPE_I, V4L2_HEVC_SLICE_TYPE_P or - V4L2_HEVC_SLICE_TYPE_B). - * - __u8 - - ``colour_plane_id`` - - - * - __u16 - - ``slice_pic_order_cnt`` - - - * - __u8 - - ``num_ref_idx_l0_active_minus1`` - - - * - __u8 - - ``num_ref_idx_l1_active_minus1`` - - - * - __u8 - - ``collocated_ref_idx`` - - - * - __u8 - - ``five_minus_max_num_merge_cand`` - - - * - __s8 - - ``slice_qp_delta`` - - - * - __s8 - - ``slice_cb_qp_offset`` - - - * - __s8 - - ``slice_cr_qp_offset`` - - - * - __s8 - - ``slice_act_y_qp_offset`` - - - * - __s8 - - ``slice_act_cb_qp_offset`` - - - * - __s8 - - ``slice_act_cr_qp_offset`` - - - * - __s8 - - ``slice_beta_offset_div2`` - - - * - __s8 - - ``slice_tc_offset_div2`` - - - * - __u8 - - ``pic_struct`` - - - * - __u8 - - ``num_active_dpb_entries`` - - The number of entries in ``dpb``. - * - __u8 - - ``ref_idx_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - The list of L0 reference elements as indices in the DPB. - * - __u8 - - ``ref_idx_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - The list of L1 reference elements as indices in the DPB. - * - __u8 - - ``num_rps_poc_st_curr_before`` - - The number of reference pictures in the short-term set that come before - the current frame. - * - __u8 - - ``num_rps_poc_st_curr_after`` - - The number of reference pictures in the short-term set that come after - the current frame. - * - __u8 - - ``num_rps_poc_lt_curr`` - - The number of reference pictures in the long-term set. - * - __u8 - - ``padding[7]`` - - Applications and drivers must set this to zero. - * - struct :c:type:`v4l2_hevc_dpb_entry` - - ``dpb[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - The decoded picture buffer, for meta-data about reference frames. - * - struct :c:type:`v4l2_hevc_pred_weight_table` - - ``pred_weight_table`` - - The prediction weight coefficients for inter-picture prediction. - * - __u64 - - ``flags`` - - See :ref:`Slice Parameters Flags <hevc_slice_params_flags>` - -.. _hevc_slice_params_flags: - -``Slice Parameters Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_SAO_LUMA`` - - 0x00000001 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_SAO_CHROMA`` - - 0x00000002 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_TEMPORAL_MVP_ENABLED`` - - 0x00000004 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_MVD_L1_ZERO`` - - 0x00000008 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_CABAC_INIT`` - - 0x00000010 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_COLLOCATED_FROM_L0`` - - 0x00000020 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_USE_INTEGER_MV`` - - 0x00000040 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_DEBLOCKING_FILTER_DISABLED`` - - 0x00000080 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_LOOP_FILTER_ACROSS_SLICES_ENABLED`` - - 0x00000100 - - - -.. c:type:: v4l2_hevc_dpb_entry - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_hevc_dpb_entry - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u64 - - ``timestamp`` - - Timestamp of the V4L2 capture buffer to use as reference, used - with B-coded and P-coded frames. The timestamp refers to the - ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the - :c:func:`v4l2_timeval_to_ns()` function to convert the struct - :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. - * - __u8 - - ``rps`` - - The reference set for the reference frame - (V4L2_HEVC_DPB_ENTRY_RPS_ST_CURR_BEFORE, - V4L2_HEVC_DPB_ENTRY_RPS_ST_CURR_AFTER or - V4L2_HEVC_DPB_ENTRY_RPS_LT_CURR) - * - __u8 - - ``field_pic`` - - Whether the reference is a field picture or a frame. - * - __u16 - - ``pic_order_cnt[2]`` - - The picture order count of the reference. Only the first element of the - array is used for frame pictures, while the first element identifies the - top field and the second the bottom field in field-coded pictures. - * - __u8 - - ``padding[2]`` - - Applications and drivers must set this to zero. - -.. c:type:: v4l2_hevc_pred_weight_table - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_hevc_pred_weight_table - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``luma_log2_weight_denom`` - - - * - __s8 - - ``delta_chroma_log2_weight_denom`` - - - * - __s8 - - ``delta_luma_weight_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - - * - __s8 - - ``luma_offset_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - - * - __s8 - - ``delta_chroma_weight_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` - - - * - __s8 - - ``chroma_offset_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` - - - * - __s8 - - ``delta_luma_weight_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - - * - __s8 - - ``luma_offset_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - - * - __s8 - - ``delta_chroma_weight_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` - - - * - __s8 - - ``chroma_offset_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` - - - * - __u8 - - ``padding[6]`` - - Applications and drivers must set this to zero. - -``V4L2_CID_MPEG_VIDEO_HEVC_DECODE_MODE (enum)`` - Specifies the decoding mode to use. Currently exposes slice-based and - frame-based decoding but new modes might be added later on. - This control is used as a modifier for V4L2_PIX_FMT_HEVC_SLICE - pixel format. Applications that support V4L2_PIX_FMT_HEVC_SLICE - are required to set this control in order to specify the decoding mode - that is expected for the buffer. - Drivers may expose a single or multiple decoding modes, depending - on what they can support. - - .. note:: - - This menu control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_mpeg_video_hevc_decode_mode - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_MPEG_VIDEO_HEVC_DECODE_MODE_SLICE_BASED`` - - 0 - - Decoding is done at the slice granularity. - The OUTPUT buffer must contain a single slice. - * - ``V4L2_MPEG_VIDEO_HEVC_DECODE_MODE_FRAME_BASED`` - - 1 - - Decoding is done at the frame granularity. - The OUTPUT buffer must contain all slices needed to decode the - frame. The OUTPUT buffer must also contain both fields. - -``V4L2_CID_MPEG_VIDEO_HEVC_START_CODE (enum)`` - Specifies the HEVC slice start code expected for each slice. - This control is used as a modifier for V4L2_PIX_FMT_HEVC_SLICE - pixel format. Applications that support V4L2_PIX_FMT_HEVC_SLICE - are required to set this control in order to specify the start code - that is expected for the buffer. - Drivers may expose a single or multiple start codes, depending - on what they can support. - - .. note:: - - This menu control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_mpeg_video_hevc_start_code - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_MPEG_VIDEO_HEVC_START_CODE_NONE`` - - 0 - - Selecting this value specifies that HEVC slices are passed - to the driver without any start code. - * - ``V4L2_MPEG_VIDEO_HEVC_START_CODE_ANNEX_B`` - - 1 - - Selecting this value specifies that HEVC slices are expected - to be prefixed by Annex B start codes. According to :ref:`hevc` - valid start codes can be 3-bytes 0x000001 or 4-bytes 0x00000001. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-colorimetry.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-colorimetry.rst new file mode 100644 index 000000000000..1e7265155715 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-colorimetry.rst @@ -0,0 +1,93 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _colorimetry-controls: + +***************************** +Colorimetry Control Reference +***************************** + +The Colorimetry class includes controls for High Dynamic Range +imaging for representing colors in digital images and video. The +controls should be used for video and image encoding and decoding +as well as in HDMI receivers and transmitters. + +Colorimetry Control IDs +----------------------- + +.. _colorimetry-control-id: + +``V4L2_CID_COLORIMETRY_CLASS (class)`` + The Colorimetry class descriptor. Calling + :ref:`VIDIOC_QUERYCTRL` for this control will + return a description of this control class. + +``V4L2_CID_COLORIMETRY_HDR10_CLL_INFO (struct)`` + The Content Light Level defines upper bounds for the nominal target + brightness light level of the pictures. + +.. c:type:: v4l2_ctrl_hdr10_cll_info + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hdr10_cll_info + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u16 + - ``max_content_light_level`` + - The upper bound for the maximum light level among all individual + samples for the pictures of a video sequence, cd/m\ :sup:`2`. + When equal to 0 no such upper bound is present. + * - __u16 + - ``max_pic_average_light_level`` + - The upper bound for the maximum average light level among the + samples for any individual picture of a video sequence, + cd/m\ :sup:`2`. When equal to 0 no such upper bound is present. + +``V4L2_CID_COLORIMETRY_HDR10_MASTERING_DISPLAY (struct)`` + The mastering display defines the color volume (the color primaries, + white point and luminance range) of a display considered to be the + mastering display for the current video content. + +.. c:type:: v4l2_ctrl_hdr10_mastering_display + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hdr10_mastering_display + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u16 + - ``display_primaries_x[3]`` + - Specifies the normalized x chromaticity coordinate of the color + primary component c of the mastering display in increments of 0.00002. + For describing the mastering display that uses Red, Green and Blue + color primaries, index value c equal to 0 corresponds to the Green + primary, c equal to 1 corresponds to Blue primary and c equal to 2 + corresponds to the Red color primary. + * - __u16 + - ``display_primaries_y[3]`` + - Specifies the normalized y chromaticity coordinate of the color + primary component c of the mastering display in increments of 0.00002. + For describing the mastering display that uses Red, Green and Blue + color primaries, index value c equal to 0 corresponds to the Green + primary, c equal to 1 corresponds to Blue primary and c equal to 2 + corresponds to Red color primary. + * - __u16 + - ``white_point_x`` + - Specifies the normalized x chromaticity coordinate of the white + point of the mastering display in increments of 0.00002. + * - __u16 + - ``white_point_y`` + - Specifies the normalized y chromaticity coordinate of the white + point of the mastering display in increments of 0.00002. + * - __u32 + - ``max_luminance`` + - Specifies the nominal maximum display luminance of the mastering + display in units of 0.0001 cd/m\ :sup:`2`. + * - __u32 + - ``min_luminance`` + - specifies the nominal minimum display luminance of the mastering + display in units of 0.0001 cd/m\ :sup:`2`. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-detect.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-detect.rst index 77a4992f26bd..312c4fa94dc3 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-detect.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-detect.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _detect-controls: diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst index c572b65dc772..d2794e03ac6d 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _dv-controls: @@ -106,7 +99,7 @@ enum v4l2_dv_it_content_type - or an analog source. The enum v4l2_dv_it_content_type defines the possible content types: -.. tabularcolumns:: |p{7.3cm}|p{10.4cm}| +.. tabularcolumns:: |p{7.3cm}|p{10.2cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst index 5053a380f7de..d22c5efb806a 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _flash-controls: @@ -70,6 +63,7 @@ Flash Control IDs presence of some faults. See V4L2_CID_FLASH_FAULT. +.. tabularcolumns:: |p{5.7cm}|p{11.8cm}| .. flat-table:: :header-rows: 0 @@ -80,14 +74,16 @@ Flash Control IDs * - ``V4L2_FLASH_LED_MODE_FLASH`` - Flash mode. * - ``V4L2_FLASH_LED_MODE_TORCH`` - - Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY. + - Torch mode. + + See V4L2_CID_FLASH_TORCH_INTENSITY. ``V4L2_CID_FLASH_STROBE_SOURCE (menu)`` Defines the source of the flash LED strobe. -.. tabularcolumns:: |p{7.5cm}|p{10.0cm}| +.. tabularcolumns:: |p{7.5cm}|p{7.5cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst index 69197bbe23dd..b6cfc0e823d2 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _fm-rx-controls: diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst index c13ec0a6af3a..04c997c9a4c3 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _fm-tx-controls: diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst index bb9d484c25e4..27803dca8d3e 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _image-process-controls: @@ -27,25 +20,26 @@ Image Process Control IDs ``V4L2_CID_IMAGE_PROC_CLASS (class)`` The IMAGE_PROC class descriptor. +.. _v4l2-cid-link-freq: + ``V4L2_CID_LINK_FREQ (integer menu)`` - Data bus frequency. Together with the media bus pixel code, bus type - (clock cycles per sample), the data bus frequency defines the pixel - rate (``V4L2_CID_PIXEL_RATE``) in the pixel array (or possibly - elsewhere, if the device is not an image sensor). The frame rate can - be calculated from the pixel clock, image width and height and - horizontal and vertical blanking. While the pixel rate control may - be defined elsewhere than in the subdev containing the pixel array, - the frame rate cannot be obtained from that information. This is - because only on the pixel array it can be assumed that the vertical - and horizontal blanking information is exact: no other blanking is - allowed in the pixel array. The selection of frame rate is performed - by selecting the desired horizontal and vertical blanking. The unit - of this control is Hz. + The frequency of the data bus (e.g. parallel or CSI-2). + +.. _v4l2-cid-pixel-rate: ``V4L2_CID_PIXEL_RATE (64-bit integer)`` - Pixel rate in the source pads of the subdev. This control is + Pixel sampling rate in the device's pixel array. This control is read-only and its unit is pixels / second. + Some devices use horizontal and vertical blanking to configure the frame + rate. The frame rate can be calculated from the pixel rate, analogue crop + rectangle as well as horizontal and vertical blanking. The pixel rate + control may be present in a different sub-device than the blanking controls + and the analogue crop rectangle configuration. + + The configuration of the frame rate is performed by selecting the desired + horizontal and vertical blanking. The unit of this control is Hz. + ``V4L2_CID_TEST_PATTERN (menu)`` Some capture/display/sensor devices have the capability to generate test pattern images. These hardware specific test patterns can be diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst index 7b75158aca4d..71f23f131f97 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _image-source-controls: @@ -65,3 +58,37 @@ Image Source Control IDs The unit cell consists of the whole area of the pixel, sensitive and non-sensitive. This control is required for automatic calibration of sensors/cameras. + +.. c:type:: v4l2_area + +.. flat-table:: struct v4l2_area + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``width`` + - Width of the area. + * - __u32 + - ``height`` + - Height of the area. + +``V4L2_CID_NOTIFY_GAINS (integer array)`` + The sensor is notified what gains will be applied to the different + colour channels by subsequent processing (such as by an ISP). The + sensor is merely informed of these values in case it performs + processing that requires them, but it does not apply them itself to + the output pixels. + + Currently it is defined only for Bayer sensors, and is an array + control taking 4 gain values, being the gains for each of the + Bayer channels. The gains are always in the order B, Gb, Gr and R, + irrespective of the exact Bayer order of the sensor itself. + + The use of an array allows this control to be extended to sensors + with, for example, non-Bayer CFAs (colour filter arrays). + + The units for the gain values are linear, with the default value + representing a gain of exactly 1.0. For example, if this default value + is reported as being (say) 128, then a value of 192 would represent + a gain of exactly 1.5. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst index 5ea69978f3ea..522095c08469 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _jpeg-controls: @@ -15,7 +8,7 @@ JPEG Control Reference The JPEG class includes controls for common features of JPEG encoders and decoders. Currently it includes features for codecs implementing -progressive baseline DCT compression process with Huffman entrophy +progressive baseline DCT compression process with Huffman entropy coding. @@ -71,13 +64,12 @@ JPEG Control IDs .. _jpeg-quality-control: ``V4L2_CID_JPEG_COMPRESSION_QUALITY (integer)`` - ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control determines trade-off - between image quality and size. It provides simpler method for - applications to control image quality, without a need for direct - reconfiguration of luminance and chrominance quantization tables. In - cases where a driver uses quantization tables configured directly by - an application, using interfaces defined elsewhere, - ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control should be set by + Determines trade-off between image quality and size. + It provides simpler method for applications to control image quality, + without a need for direct reconfiguration of luminance and chrominance + quantization tables. In cases where a driver uses quantization tables + configured directly by an application, using interfaces defined + elsewhere, ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control should be set by driver to 0. The value range of this control is driver-specific. Only positive, diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-rf-tuner.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-rf-tuner.rst index 5277138fce67..8a6f9f0373ff 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-rf-tuner.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-rf-tuner.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _rf-tuner-controls: diff --git a/Documentation/userspace-api/media/v4l/extended-controls.rst b/Documentation/userspace-api/media/v4l/extended-controls.rst index 9aa352ac5ea4..44fcd67f20bf 100644 --- a/Documentation/userspace-api/media/v4l/extended-controls.rst +++ b/Documentation/userspace-api/media/v4l/extended-controls.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _extended-controls: @@ -62,8 +55,8 @@ controls in that array and a control class. Control classes are used to group similar controls into a single class. For example, control class ``V4L2_CTRL_CLASS_USER`` contains all user controls (i. e. all controls that can also be set using the old :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` -ioctl). Control class ``V4L2_CTRL_CLASS_MPEG`` contains all controls -relating to MPEG encoding, etc. +ioctl). Control class ``V4L2_CTRL_CLASS_CODEC`` contains controls +relating to codecs. All controls in the control array must belong to the specified control class. An error is returned if this is not the case. @@ -137,9 +130,9 @@ control class is found: .. code-block:: c - qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL; + qctrl.id = V4L2_CTRL_CLASS_CODEC | V4L2_CTRL_FLAG_NEXT_CTRL; while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &qctrl)) { - if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_MPEG) + if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_CODEC) break; /* ... */ qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; diff --git a/Documentation/userspace-api/media/v4l/field-order.rst b/Documentation/userspace-api/media/v4l/field-order.rst index 04e9a6932dc5..9a0ed8fc550f 100644 --- a/Documentation/userspace-api/media/v4l/field-order.rst +++ b/Documentation/userspace-api/media/v4l/field-order.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _field-order: @@ -69,7 +62,7 @@ enum v4l2_field .. c:type:: v4l2_field -.. tabularcolumns:: |p{5.8cm}|p{0.6cm}|p{11.1cm}| +.. tabularcolumns:: |p{5.8cm}|p{0.6cm}|p{10.9cm}| .. cssclass:: longtable diff --git a/Documentation/userspace-api/media/v4l/fieldseq_bt.svg b/Documentation/userspace-api/media/v4l/fieldseq_bt.svg index b663f6fcb70b..91ac2813b454 100644 --- a/Documentation/userspace-api/media/v4l/fieldseq_bt.svg +++ b/Documentation/userspace-api/media/v4l/fieldseq_bt.svg @@ -1,14 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" diff --git a/Documentation/userspace-api/media/v4l/fieldseq_tb.svg b/Documentation/userspace-api/media/v4l/fieldseq_tb.svg index f8b440a1cb60..7b4f8fb33757 100644 --- a/Documentation/userspace-api/media/v4l/fieldseq_tb.svg +++ b/Documentation/userspace-api/media/v4l/fieldseq_tb.svg @@ -1,14 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" diff --git a/Documentation/userspace-api/media/v4l/format.rst b/Documentation/userspace-api/media/v4l/format.rst index e47fc0505727..35bbb2fea46e 100644 --- a/Documentation/userspace-api/media/v4l/format.rst +++ b/Documentation/userspace-api/media/v4l/format.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _format: @@ -13,7 +7,6 @@ Data Formats ************ - Data Format Negotiation ======================= @@ -60,8 +53,8 @@ image size. When applications omit the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl its locking side effects are implied by the next step, the selection of an I/O method with the :ref:`VIDIOC_REQBUFS` ioctl or implicit -with the first :ref:`read() <func-read>` or -:ref:`write() <func-write>` call. +with the first :c:func:`read()` or +:c:func:`write()` call. Generally only one logical stream can be assigned to a file descriptor, the exception being drivers permitting simultaneous video capturing and @@ -74,7 +67,6 @@ All drivers exchanging data with applications must support the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional. - Image Format Enumeration ======================== diff --git a/Documentation/userspace-api/media/v4l/func-close.rst b/Documentation/userspace-api/media/v4l/func-close.rst index 37a64dae56b0..dba3263fd1b9 100644 --- a/Documentation/userspace-api/media/v4l/func-close.rst +++ b/Documentation/userspace-api/media/v4l/func-close.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-close: @@ -18,7 +12,6 @@ Name v4l2-close - Close a V4L2 device - Synopsis ======== @@ -26,16 +19,13 @@ Synopsis #include <unistd.h> - .. c:function:: int close( int fd ) - :name: v4l2-close Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. - + File descriptor returned by :c:func:`open()`. Description =========== @@ -45,7 +35,6 @@ associated with the file descriptor are freed. However data format parameters, current input or output, control values or other properties remain unchanged. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/func-ioctl.rst b/Documentation/userspace-api/media/v4l/func-ioctl.rst index 4e69f303636b..f3b005094334 100644 --- a/Documentation/userspace-api/media/v4l/func-ioctl.rst +++ b/Documentation/userspace-api/media/v4l/func-ioctl.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-ioctl: @@ -18,7 +12,6 @@ Name v4l2-ioctl - Program a V4L2 device - Synopsis ======== @@ -26,15 +19,13 @@ Synopsis #include <sys/ioctl.h> - -.. c:function:: int ioctl( int fd, int request, void *argp ) - :name: v4l2-ioctl +``int ioctl(int fd, int request, void *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``request`` V4L2 ioctl request code as defined in the ``videodev2.h`` header @@ -43,7 +34,6 @@ Arguments ``argp`` Pointer to a function parameter, usually a structure. - Description =========== @@ -57,7 +47,6 @@ include the version in the kernel sources on the system they compile on. All V4L2 ioctl requests, their respective function and parameters are specified in :ref:`user-func`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/func-mmap.rst b/Documentation/userspace-api/media/v4l/func-mmap.rst index f9c77bdce434..e3e5e64ebe7e 100644 --- a/Documentation/userspace-api/media/v4l/func-mmap.rst +++ b/Documentation/userspace-api/media/v4l/func-mmap.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-mmap: @@ -18,7 +12,6 @@ Name v4l2-mmap - Map device memory into application address space - Synopsis ======== @@ -27,9 +20,7 @@ Synopsis #include <unistd.h> #include <sys/mman.h> - .. c:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset ) - :name: v4l2-mmap Arguments ========= @@ -61,7 +52,7 @@ Arguments #. The Linux ``videobuf`` kernel module, which is used by some drivers supports only ``PROT_READ`` | ``PROT_WRITE``. When the driver does not support the desired protection, the - :ref:`mmap() <func-mmap>` function fails. + :c:func:`mmap()` function fails. #. Device memory accesses (e. g. the memory on a graphics card with video capturing hardware) may incur a performance penalty @@ -77,7 +68,7 @@ Arguments ``MAP_FIXED`` requests that the driver selects no other address than the one specified. If the specified address cannot be used, - :ref:`mmap() <func-mmap>` will fail. If ``MAP_FIXED`` is specified, + :c:func:`mmap()` will fail. If ``MAP_FIXED`` is specified, ``start`` must be a multiple of the pagesize. Use of this option is discouraged. @@ -94,7 +85,7 @@ Arguments flags. ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``offset`` Offset of the buffer in device memory. This must be the same value @@ -104,11 +95,10 @@ Arguments in the struct :c:type:`v4l2_plane` ``m`` union ``mem_offset`` field for the multi-planar API. - Description =========== -The :ref:`mmap() <func-mmap>` function asks to map ``length`` bytes starting at +The :c:func:`mmap()` function asks to map ``length`` bytes starting at ``offset`` in the memory of the device specified by ``fd`` into the application address space, preferably at address ``start``. This latter address is a hint only, and is usually specified as 0. @@ -118,13 +108,12 @@ Suitable length and offset parameters are queried with the allocated with the :ref:`VIDIOC_REQBUFS` ioctl before they can be queried. -To unmap buffers the :ref:`munmap() <func-munmap>` function is used. - +To unmap buffers the :c:func:`munmap()` function is used. Return Value ============ -On success :ref:`mmap() <func-mmap>` returns a pointer to the mapped buffer. On +On success :c:func:`mmap()` returns a pointer to the mapped buffer. On error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set appropriately. Possible error codes are: diff --git a/Documentation/userspace-api/media/v4l/func-munmap.rst b/Documentation/userspace-api/media/v4l/func-munmap.rst index 18a9941b47ab..077d58333904 100644 --- a/Documentation/userspace-api/media/v4l/func-munmap.rst +++ b/Documentation/userspace-api/media/v4l/func-munmap.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-munmap: @@ -18,7 +12,6 @@ Name v4l2-munmap - Unmap device memory - Synopsis ======== @@ -27,37 +20,33 @@ Synopsis #include <unistd.h> #include <sys/mman.h> - .. c:function:: int munmap( void *start, size_t length ) - :name: v4l2-munmap Arguments ========= ``start`` Address of the mapped buffer as returned by the - :ref:`mmap() <func-mmap>` function. + :c:func:`mmap()` function. ``length`` Length of the mapped buffer. This must be the same value as given to - :ref:`mmap() <func-mmap>` and returned by the driver in the struct + :c:func:`mmap()` and returned by the driver in the struct :c:type:`v4l2_buffer` ``length`` field for the single-planar API and in the struct :c:type:`v4l2_plane` ``length`` field for the multi-planar API. - Description =========== -Unmaps a previously with the :ref:`mmap() <func-mmap>` function mapped +Unmaps a previously with the :c:func:`mmap()` function mapped buffer and frees it, if possible. - Return Value ============ -On success :ref:`munmap() <func-munmap>` returns 0, on failure -1 and the +On success :c:func:`munmap()` returns 0, on failure -1 and the ``errno`` variable is set appropriately: EINVAL diff --git a/Documentation/userspace-api/media/v4l/func-open.rst b/Documentation/userspace-api/media/v4l/func-open.rst index 8bcdec8ab387..be3808cbf876 100644 --- a/Documentation/userspace-api/media/v4l/func-open.rst +++ b/Documentation/userspace-api/media/v4l/func-open.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-open: @@ -18,7 +12,6 @@ Name v4l2-open - Open a V4L2 device - Synopsis ======== @@ -26,9 +19,7 @@ Synopsis #include <fcntl.h> - .. c:function:: int open( const char *device_name, int flags ) - :name: v4l2-open Arguments ========= @@ -41,7 +32,7 @@ Arguments technicality, input devices still support only reading and output devices only writing. - When the ``O_NONBLOCK`` flag is given, the :ref:`read() <func-read>` + When the ``O_NONBLOCK`` flag is given, the :c:func:`read()` function and the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will return the ``EAGAIN`` error code when no data is available or no buffer is in the driver outgoing queue, otherwise these functions @@ -50,22 +41,20 @@ Arguments Other flags have no effect. - Description =========== -To open a V4L2 device applications call :ref:`open() <func-open>` with the +To open a V4L2 device applications call :c:func:`open()` with the desired device name. This function has no side effects; all data format parameters, current input or output, control values or other properties -remain unchanged. At the first :ref:`open() <func-open>` call after loading the +remain unchanged. At the first :c:func:`open()` call after loading the driver they will be reset to default values, drivers are never in an undefined state. - Return Value ============ -On success :ref:`open() <func-open>` returns the new file descriptor. On error +On success :c:func:`open()` returns the new file descriptor. On error -1 is returned, and the ``errno`` variable is set appropriately. Possible error codes are: @@ -76,8 +65,8 @@ EBUSY The driver does not support multiple opens and the device is already in use. -ENXIO - No device corresponding to this device special file exists. +ENODEV + Device not found or was removed. ENOMEM Not enough kernel memory was available to complete the request. diff --git a/Documentation/userspace-api/media/v4l/func-poll.rst b/Documentation/userspace-api/media/v4l/func-poll.rst index 2c6704c1fab7..cbf4a0a10ae2 100644 --- a/Documentation/userspace-api/media/v4l/func-poll.rst +++ b/Documentation/userspace-api/media/v4l/func-poll.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-poll: @@ -18,7 +12,6 @@ Name v4l2-poll - Wait for some event on a file descriptor - Synopsis ======== @@ -26,19 +19,16 @@ Synopsis #include <sys/poll.h> - .. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout ) - :name: v4l2-poll Arguments ========= - Description =========== -With the :ref:`poll() <func-poll>` function applications can suspend execution +With the :c:func:`poll()` function applications can suspend execution until the driver has captured data or is ready to accept data for output. @@ -51,57 +41,56 @@ display. When buffers are already in the outgoing queue of the driver (capture) or the incoming queue isn't full (display) the function returns immediately. -On success :ref:`poll() <func-poll>` returns the number of file descriptors +On success :c:func:`poll()` returns the number of file descriptors that have been selected (that is, file descriptors for which the -``revents`` field of the respective :c:func:`struct pollfd` structure +``revents`` field of the respective ``struct pollfd`` structure is non-zero). Capture devices set the ``POLLIN`` and ``POLLRDNORM`` flags in the ``revents`` field, output devices the ``POLLOUT`` and ``POLLWRNORM`` flags. When the function timed out it returns a value of zero, on failure it returns -1 and the ``errno`` variable is set appropriately. When the application did not call -:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` the :ref:`poll() <func-poll>` +:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` the :c:func:`poll()` function succeeds, but sets the ``POLLERR`` flag in the ``revents`` field. When the application has called :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` for a capture device but hasn't yet called :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, the -:ref:`poll() <func-poll>` function succeeds and sets the ``POLLERR`` flag in +:c:func:`poll()` function succeeds and sets the ``POLLERR`` flag in the ``revents`` field. For output devices this same situation will cause -:ref:`poll() <func-poll>` to succeed as well, but it sets the ``POLLOUT`` and +:c:func:`poll()` to succeed as well, but it sets the ``POLLOUT`` and ``POLLWRNORM`` flags in the ``revents`` field. If an event occurred (see :ref:`VIDIOC_DQEVENT`) then ``POLLPRI`` will be set in the ``revents`` field and -:ref:`poll() <func-poll>` will return. +:c:func:`poll()` will return. -When use of the :ref:`read() <func-read>` function has been negotiated and the -driver does not capture yet, the :ref:`poll() <func-poll>` function starts +When use of the :c:func:`read()` function has been negotiated and the +driver does not capture yet, the :c:func:`poll()` function starts capturing. When that fails it returns a ``POLLERR`` as above. Otherwise it waits until data has been captured and can be read. When the driver captures continuously (as opposed to, for example, still images) the function may return immediately. -When use of the :ref:`write() <func-write>` function has been negotiated and the -driver does not stream yet, the :ref:`poll() <func-poll>` function starts +When use of the :c:func:`write()` function has been negotiated and the +driver does not stream yet, the :c:func:`poll()` function starts streaming. When that fails it returns a ``POLLERR`` as above. Otherwise it waits until the driver is ready for a non-blocking -:ref:`write() <func-write>` call. +:c:func:`write()` call. If the caller is only interested in events (just ``POLLPRI`` is set in -the ``events`` field), then :ref:`poll() <func-poll>` will *not* start +the ``events`` field), then :c:func:`poll()` will *not* start streaming if the driver does not stream yet. This makes it possible to just poll for events and not for buffers. -All drivers implementing the :ref:`read() <func-read>` or :ref:`write() <func-write>` -function or streaming I/O must also support the :ref:`poll() <func-poll>` +All drivers implementing the :c:func:`read()` or :c:func:`write()` +function or streaming I/O must also support the :c:func:`poll()` function. -For more details see the :ref:`poll() <func-poll>` manual page. - +For more details see the :c:func:`poll()` manual page. Return Value ============ -On success, :ref:`poll() <func-poll>` returns the number structures which have +On success, :c:func:`poll()` returns the number structures which have non-zero ``revents`` fields, or zero if the call timed out. On error -1 is returned, and the ``errno`` variable is set appropriately: diff --git a/Documentation/userspace-api/media/v4l/func-read.rst b/Documentation/userspace-api/media/v4l/func-read.rst index 1728aa5d8313..e6f6ac4bed77 100644 --- a/Documentation/userspace-api/media/v4l/func-read.rst +++ b/Documentation/userspace-api/media/v4l/func-read.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-read: @@ -18,7 +12,6 @@ Name v4l2-read - Read from a V4L2 device - Synopsis ======== @@ -26,15 +19,13 @@ Synopsis #include <unistd.h> - .. c:function:: ssize_t read( int fd, void *buf, size_t count ) - :name: v4l2-read Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``buf`` Buffer to be filled @@ -45,48 +36,48 @@ Arguments Description =========== -:ref:`read() <func-read>` attempts to read up to ``count`` bytes from file +:c:func:`read()` attempts to read up to ``count`` bytes from file descriptor ``fd`` into the buffer starting at ``buf``. The layout of the data in the buffer is discussed in the respective device interface -section, see ##. If ``count`` is zero, :ref:`read() <func-read>` returns zero +section, see ##. If ``count`` is zero, :c:func:`read()` returns zero and has no other results. If ``count`` is greater than ``SSIZE_MAX``, the result is unspecified. Regardless of the ``count`` value each -:ref:`read() <func-read>` call will provide at most one frame (two fields) +:c:func:`read()` call will provide at most one frame (two fields) worth of data. -By default :ref:`read() <func-read>` blocks until data becomes available. When -the ``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` +By default :c:func:`read()` blocks until data becomes available. When +the ``O_NONBLOCK`` flag was given to the :c:func:`open()` function it returns immediately with an ``EAGAIN`` error code when no data -is available. The :ref:`select() <func-select>` or -:ref:`poll() <func-poll>` functions can always be used to suspend +is available. The :c:func:`select()` or +:c:func:`poll()` functions can always be used to suspend execution until data becomes available. All drivers supporting the -:ref:`read() <func-read>` function must also support :ref:`select() <func-select>` and -:ref:`poll() <func-poll>`. +:c:func:`read()` function must also support :c:func:`select()` and +:c:func:`poll()`. Drivers can implement read functionality in different ways, using a single or multiple buffers and discarding the oldest or newest frames once the internal buffers are filled. -:ref:`read() <func-read>` never returns a "snapshot" of a buffer being filled. +:c:func:`read()` never returns a "snapshot" of a buffer being filled. Using a single buffer the driver will stop capturing when the application starts reading the buffer until the read is finished. Thus only the period of the vertical blanking interval is available for reading, or the capture rate must fall below the nominal frame rate of the video standard. -The behavior of :ref:`read() <func-read>` when called during the active picture +The behavior of :c:func:`read()` when called during the active picture period or the vertical blanking separating the top and bottom field depends on the discarding policy. A driver discarding the oldest frames keeps capturing into an internal buffer, continuously overwriting the previously, not read frame, and returns the frame being received at the -time of the :ref:`read() <func-read>` call as soon as it is complete. +time of the :c:func:`read()` call as soon as it is complete. A driver discarding the newest frames stops capturing until the next -:ref:`read() <func-read>` call. The frame being received at :ref:`read() <func-read>` +:c:func:`read()` call. The frame being received at :c:func:`read()` time is discarded, returning the following frame instead. Again this implies a reduction of the capture rate to one half or less of the nominal frame rate. An example of this model is the video read mode of -the bttv driver, initiating a DMA to user memory when :ref:`read() <func-read>` +the bttv driver, initiating a DMA to user memory when :c:func:`read()` is called and returning when the DMA finished. In the multiple buffer model drivers maintain a ring of internal @@ -101,14 +92,13 @@ the driver with the :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and however. The discarding policy is not reported and cannot be changed. For minimum requirements see :ref:`devices`. - Return Value ============ On success, the number of bytes read is returned. It is not an error if this number is smaller than the number of bytes requested, or the amount of data required for one frame. This may happen for example because -:ref:`read() <func-read>` was interrupted by a signal. On error, -1 is +:c:func:`read()` was interrupted by a signal. On error, -1 is returned, and the ``errno`` variable is set appropriately. In this case the next read will start at the beginning of a new frame. Possible error codes are: @@ -136,5 +126,5 @@ EIO communicate with a remote device (USB camera etc.). EINVAL - The :ref:`read() <func-read>` function is not supported by this driver, not + The :c:func:`read()` function is not supported by this driver, not on this device, or generally not on this type of device. diff --git a/Documentation/userspace-api/media/v4l/func-select.rst b/Documentation/userspace-api/media/v4l/func-select.rst index 6aca8a290c1f..ba1879c728f0 100644 --- a/Documentation/userspace-api/media/v4l/func-select.rst +++ b/Documentation/userspace-api/media/v4l/func-select.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-select: @@ -18,7 +12,6 @@ Name v4l2-select - Synchronous I/O multiplexing - Synopsis ======== @@ -28,9 +21,7 @@ Synopsis #include <sys/types.h> #include <unistd.h> - .. c:function:: int select( int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout ) - :name: v4l2-select Arguments ========= @@ -50,11 +41,10 @@ Arguments ``timeout`` Maximum time to wait. - Description =========== -With the :ref:`select() <func-select>` function applications can suspend +With the :c:func:`select()` function applications can suspend execution until the driver has captured data or is ready to accept data for output. @@ -63,40 +53,39 @@ buffer has been filled or displayed and can be dequeued with the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. When buffers are already in the outgoing queue of the driver the function returns immediately. -On success :ref:`select() <func-select>` returns the total number of bits set in -:c:func:`struct fd_set`. When the function timed out it returns +On success :c:func:`select()` returns the total number of bits set in +``fd_set``. When the function timed out it returns a value of zero. On failure it returns -1 and the ``errno`` variable is set appropriately. When the application did not call :ref:`VIDIOC_QBUF` or -:ref:`VIDIOC_STREAMON` yet the :ref:`select() <func-select>` +:ref:`VIDIOC_STREAMON` yet the :c:func:`select()` function succeeds, setting the bit of the file descriptor in ``readfds`` or ``writefds``, but subsequent :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` calls will fail. [#f1]_ -When use of the :ref:`read() <func-read>` function has been negotiated and the -driver does not capture yet, the :ref:`select() <func-select>` function starts -capturing. When that fails, :ref:`select() <func-select>` returns successful and -a subsequent :ref:`read() <func-read>` call, which also attempts to start +When use of the :c:func:`read()` function has been negotiated and the +driver does not capture yet, the :c:func:`select()` function starts +capturing. When that fails, :c:func:`select()` returns successful and +a subsequent :c:func:`read()` call, which also attempts to start capturing, will return an appropriate error code. When the driver captures continuously (as opposed to, for example, still images) and -data is already available the :ref:`select() <func-select>` function returns +data is already available the :c:func:`select()` function returns immediately. -When use of the :ref:`write() <func-write>` function has been negotiated the -:ref:`select() <func-select>` function just waits until the driver is ready for a -non-blocking :ref:`write() <func-write>` call. +When use of the :c:func:`write()` function has been negotiated the +:c:func:`select()` function just waits until the driver is ready for a +non-blocking :c:func:`write()` call. -All drivers implementing the :ref:`read() <func-read>` or :ref:`write() <func-write>` -function or streaming I/O must also support the :ref:`select() <func-select>` +All drivers implementing the :c:func:`read()` or :c:func:`write()` +function or streaming I/O must also support the :c:func:`select()` function. -For more details see the :ref:`select() <func-select>` manual page. - +For more details see the :c:func:`select()` manual page. Return Value ============ -On success, :ref:`select() <func-select>` returns the number of descriptors +On success, :c:func:`select()` returns the number of descriptors contained in the three returned descriptor sets, which will be zero if the timeout expired. On error -1 is returned, and the ``errno`` variable is set appropriately; the sets and ``timeout`` are undefined. Possible @@ -122,6 +111,6 @@ EINVAL ``FD_SETSIZE``. .. [#f1] - The Linux kernel implements :ref:`select() <func-select>` like the - :ref:`poll() <func-poll>` function, but :ref:`select() <func-select>` cannot + The Linux kernel implements :c:func:`select()` like the + :c:func:`poll()` function, but :c:func:`select()` cannot return a ``POLLERR``. diff --git a/Documentation/userspace-api/media/v4l/func-write.rst b/Documentation/userspace-api/media/v4l/func-write.rst index fb1955f70f0f..49f5a0f4275f 100644 --- a/Documentation/userspace-api/media/v4l/func-write.rst +++ b/Documentation/userspace-api/media/v4l/func-write.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _func-write: @@ -18,7 +12,6 @@ Name v4l2-write - Write to a V4L2 device - Synopsis ======== @@ -26,15 +19,13 @@ Synopsis #include <unistd.h> - .. c:function:: ssize_t write( int fd, void *buf, size_t count ) - :name: v4l2-write Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``buf`` Buffer with data to be written @@ -45,10 +36,10 @@ Arguments Description =========== -:ref:`write() <func-write>` writes up to ``count`` bytes to the device +:c:func:`write()` writes up to ``count`` bytes to the device referenced by the file descriptor ``fd`` from the buffer starting at ``buf``. When the hardware outputs are not active yet, this function -enables them. When ``count`` is zero, :ref:`write() <func-write>` returns 0 +enables them. When ``count`` is zero, :c:func:`write()` returns 0 without any other effect. When the application does not provide more data in time, the previous @@ -56,7 +47,6 @@ video frame, raw VBI image, sliced VPS or WSS data is displayed again. Sliced Teletext or Closed Caption data is not repeated, the driver inserts a blank line instead. - Return Value ============ @@ -87,5 +77,5 @@ EIO I/O error. This indicates some hardware problem. EINVAL - The :ref:`write() <func-write>` function is not supported by this driver, + The :c:func:`write()` function is not supported by this driver, not on this device, or generally not on this type of device. diff --git a/Documentation/userspace-api/media/v4l/hist-v4l2.rst b/Documentation/userspace-api/media/v4l/hist-v4l2.rst index 7913d017cd33..cdc11e9a0f32 100644 --- a/Documentation/userspace-api/media/v4l/hist-v4l2.rst +++ b/Documentation/userspace-api/media/v4l/hist-v4l2.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _hist-v4l2: @@ -21,18 +15,17 @@ not just an extension but a replacement for the V4L API. However it took another four years and two stable kernel releases until the new API was finally accepted for inclusion into the kernel in its present form. - Early Versions ============== 1998-08-20: First version. -1998-08-27: The :ref:`select() <func-select>` function was introduced. +1998-08-27: The :c:func:`select()` function was introduced. 1998-09-10: New video standard interface. 1998-09-18: The ``VIDIOC_NONCAP`` ioctl was replaced by the otherwise -meaningless ``O_TRUNC`` :ref:`open() <func-open>` flag, and the +meaningless ``O_TRUNC`` :c:func:`open()` flag, and the aliases ``O_NONCAP`` and ``O_NOIO`` were defined. Applications can set this flag if they intend to access controls only, as opposed to capture applications which need exclusive access. The ``VIDEO_STD_XXX`` @@ -43,7 +36,7 @@ transmission arguments. 1998-09-28: Revamped video standard. Made video controls individually enumerable. -1998-10-02: The ``id`` field was removed from struct +1998-10-02: The ``id`` field was removed from struct ``video_standard`` and the color subcarrier fields were renamed. The :ref:`VIDIOC_QUERYSTD` ioctl was renamed to :ref:`VIDIOC_ENUMSTD`, @@ -52,9 +45,9 @@ renamed to :ref:`VIDIOC_ENUMSTD`, Codec API was released. 1998-11-08: Many minor changes. Most symbols have been renamed. Some -material changes to struct :c:type:`v4l2_capability`. +material changes to struct v4l2_capability. -1998-11-12: The read/write directon of some ioctls was misdefined. +1998-11-12: The read/write direction of some ioctls was misdefined. 1998-11-14: ``V4L2_PIX_FMT_RGB24`` changed to ``V4L2_PIX_FMT_BGR24``, and ``V4L2_PIX_FMT_RGB32`` changed to ``V4L2_PIX_FMT_BGR32``. Audio @@ -72,7 +65,6 @@ output devices were added. 1999-01-19: The ``VIDIOC_NEXTBUF`` ioctl was removed. - V4L2 Version 0.16 1999-01-31 ============================ @@ -80,7 +72,6 @@ V4L2 Version 0.16 1999-01-31 are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added digital zoom (cropping) controls. - V4L2 Version 0.18 1999-03-16 ============================ @@ -88,7 +79,6 @@ Added a v4l to V4L2 ioctl compatibility layer to videodev.c. Driver writers, this changes how you implement your ioctl handler. See the Driver Writer's Guide. Added some more control id codes. - V4L2 Version 0.19 1999-06-05 ============================ @@ -114,7 +104,6 @@ malfunction of this ioctl. 1999-06-05: Changed the value of V4L2_CID_WHITENESS. - V4L2 Version 0.20 (1999-09-10) ============================== @@ -123,9 +112,8 @@ compatible* with 0.19 and earlier versions. Purpose of these changes was to simplify the API, while making it more extensible and following common Linux driver API conventions. -1. Some typos in ``V4L2_FMT_FLAG`` symbols were fixed. struct - :c:type:`v4l2_clip` was changed for compatibility with - v4l. (1999-08-30) +1. Some typos in ``V4L2_FMT_FLAG`` symbols were fixed. struct v4l2_clip + was changed for compatibility with v4l. (1999-08-30) 2. ``V4L2_TUNER_SUB_LANG1`` was added. (1999-09-05) @@ -136,14 +124,12 @@ common Linux driver API conventions. VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ, VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example - .. code-block:: c err = ioctl (fd, VIDIOC_XXX, V4L2_XXX); becomes - .. code-block:: c int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &a); @@ -158,16 +144,14 @@ common Linux driver API conventions. This change obsoletes the following ioctls: ``VIDIOC_S_INFMT``, ``VIDIOC_G_INFMT``, ``VIDIOC_S_OUTFMT``, ``VIDIOC_G_OUTFMT``, ``VIDIOC_S_VBIFMT`` and ``VIDIOC_G_VBIFMT``. The image format - structure struct :c:type:`v4l2_format` was renamed to struct - :c:type:`v4l2_pix_format`, while struct - :c:type:`v4l2_format` is now the envelopping structure + struct v4l2_format was renamed to struct v4l2_pix_format, while + struct v4l2_format is now the enveloping structure for all format negotiations. 5. Similar to the changes above, the ``VIDIOC_G_PARM`` and ``VIDIOC_S_PARM`` ioctls were merged with ``VIDIOC_G_OUTPARM`` and - ``VIDIOC_S_OUTPARM``. A ``type`` field in the new struct - :c:type:`v4l2_streamparm` selects the respective - union member. + ``VIDIOC_S_OUTPARM``. A ``type`` field in the new struct v4l2_streamparm + selects the respective union member. This change obsoletes the ``VIDIOC_G_OUTPARM`` and ``VIDIOC_S_OUTPARM`` ioctls. @@ -185,7 +169,7 @@ common Linux driver API conventions. categories might have a greater separation, or may even appear in separate windows. -7. The struct :c:type:`v4l2_buffer` ``timestamp`` was +7. The struct v4l2_buffer ``timestamp`` was changed to a 64 bit integer, containing the sampling or output time of the frame in nanoseconds. Additionally timestamps will be in absolute system time, not starting from zero at the beginning of a @@ -208,16 +192,14 @@ common Linux driver API conventions. v4l2_masterclock_gettime() function (used only by drivers) to return a 64-bit integer. -8. A ``sequence`` field was added to struct - :c:type:`v4l2_buffer`. The ``sequence`` field counts - captured frames, it is ignored by output devices. When a capture - driver drops a frame, the sequence number of that frame is skipped. - +8. A ``sequence`` field was added to struct v4l2_buffer. The ``sequence`` + field counts captured frames, it is ignored by output devices. When a + capture driver drops a frame, the sequence number of that frame is skipped. V4L2 Version 0.20 incremental changes ===================================== -1999-12-23: In struct :c:type:`v4l2_vbi_format` the +1999-12-23: In struct v4l2_vbi_format the ``reserved1`` field became ``offset``. Previously drivers were required to clear the ``reserved1`` field. @@ -260,12 +242,11 @@ multiple tuners into account.) 2000-09-18: ``V4L2_BUF_TYPE_VBI`` was added. This may *break compatibility* as the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and -:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls may fail now if the struct +:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls may fail now if the struct ``v4l2_fmt`` ``type`` field does not contain -``V4L2_BUF_TYPE_VBI``. In the documentation of the struct -:c:type:`v4l2_vbi_format` ``offset`` field the -ambiguous phrase "rising edge" was changed to "leading edge". - +``V4L2_BUF_TYPE_VBI``. In the documentation of the struct v4l2_vbi_format`, +the ``offset`` field the ambiguous phrase "rising edge" was changed to +"leading edge". V4L2 Version 0.20 2000-11-23 ============================ @@ -302,13 +283,11 @@ A number of changes were made to the raw VBI interface. were added. The former is an alias for the old ``V4L2_TYPE_VBI``, the latter was missing in the ``videodev.h`` file. - V4L2 Version 0.20 2002-07-25 ============================ Added sliced VBI interface proposal. - V4L2 in Linux 2.5.46, 2002-10 ============================= @@ -319,7 +298,7 @@ This unnamed version was finally merged into Linux 2.5.46. 1. As specified in :ref:`related`, drivers must make related device functions available under all minor device numbers. -2. The :ref:`open() <func-open>` function requires access mode +2. The :c:func:`open()` function requires access mode ``O_RDWR`` regardless of the device type. All V4L2 drivers exchanging data with applications must support the ``O_NONBLOCK`` flag. The ``O_NOIO`` flag, a V4L2 symbol which aliased the @@ -328,7 +307,7 @@ This unnamed version was finally merged into Linux 2.5.46. until the application attempts to initiate a data exchange, see :ref:`open`. -3. The struct :c:type:`v4l2_capability` changed +3. The struct v4l2_capability changed dramatically. Note that also the size of the structure changed, which is encoded in the ioctl request code, thus older V4L2 devices will respond with an ``EINVAL`` error code to the new @@ -337,7 +316,7 @@ This unnamed version was finally merged into Linux 2.5.46. There are new fields to identify the driver, a new RDS device function ``V4L2_CAP_RDS_CAPTURE``, the ``V4L2_CAP_AUDIO`` flag indicates if the device has any audio connectors, another I/O - capability ``V4L2_CAP_ASYNCIO`` can be flagged. In response to these + capability V4L2_CAP_ASYNCIO can be flagged. In response to these changes the ``type`` field became a bit set and was merged into the ``flags`` field. ``V4L2_FLAG_TUNER`` was renamed to ``V4L2_CAP_TUNER``, ``V4L2_CAP_VIDEO_OVERLAY`` replaced @@ -361,7 +340,7 @@ This unnamed version was finally merged into Linux 2.5.46. ``V4L2_FLAG_MONOCHROME`` flag was removed, this information is available as described in :ref:`format`. -4. In struct :c:type:`v4l2_input` the ``assoc_audio`` +4. In struct v4l2_input the ``assoc_audio`` field and the ``capability`` field and its only flag ``V4L2_INPUT_CAP_AUDIO`` was replaced by the new ``audioset`` field. Instead of linking one video input to one audio input this field @@ -370,11 +349,11 @@ This unnamed version was finally merged into Linux 2.5.46. New fields are ``tuner`` (reversing the former link from tuners to video inputs), ``std`` and ``status``. - Accordingly struct :c:type:`v4l2_output` lost its + Accordingly struct v4l2_output lost its ``capability`` and ``assoc_audio`` fields. ``audioset``, ``modulator`` and ``std`` where added instead. -5. The struct :c:type:`v4l2_audio` field ``audio`` was +5. The struct v4l2_audio field ``audio`` was renamed to ``index``, for consistency with other structures. A new capability flag ``V4L2_AUDCAP_STEREO`` was added to indicated if the audio input in question supports stereo sound. @@ -382,21 +361,20 @@ This unnamed version was finally merged into Linux 2.5.46. where removed. This can be easily implemented using controls. (However the same applies to AVL which is still there.) - Again for consistency the struct - :c:type:`v4l2_audioout` field ``audio`` was renamed + Again for consistency the struct v4l2_audioout field ``audio`` was renamed to ``index``. -6. The struct :c:type:`v4l2_tuner` ``input`` field was +6. The struct v4l2_tuner ``input`` field was replaced by an ``index`` field, permitting devices with multiple tuners. The link between video inputs and tuners is now reversed, inputs point to their tuner. The ``std`` substructure became a - simple set (more about this below) and moved into struct - :c:type:`v4l2_input`. A ``type`` field was added. + simple set (more about this below) and moved into struct v4l2_input. + A ``type`` field was added. - Accordingly in struct :c:type:`v4l2_modulator` the + Accordingly in struct v4l2_modulator the ``output`` was replaced by an ``index`` field. - In struct :c:type:`v4l2_frequency` the ``port`` + In struct v4l2_frequency the ``port`` field was replaced by a ``tuner`` field containing the respective tuner or modulator index number. A tuner ``type`` field was added and the ``reserved`` field became larger for future extensions @@ -412,7 +390,7 @@ This unnamed version was finally merged into Linux 2.5.46. :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` now take a pointer to this type as argument. :ref:`VIDIOC_QUERYSTD` was added to autodetect the received standard, if the hardware has this - capability. In struct :c:type:`v4l2_standard` an + capability. In struct v4l2_standard an ``index`` field was added for :ref:`VIDIOC_ENUMSTD`. A :ref:`v4l2_std_id <v4l2-std-id>` field named ``id`` was added as @@ -424,10 +402,10 @@ This unnamed version was finally merged into Linux 2.5.46. Struct ``v4l2_enumstd`` ceased to be. :ref:`VIDIOC_ENUMSTD` now takes a pointer to a - struct :c:type:`v4l2_standard` directly. The + struct v4l2_standard directly. The information which standards are supported by a particular video - input or output moved into struct :c:type:`v4l2_input` - and struct :c:type:`v4l2_output` fields named ``std``, + input or output moved into struct v4l2_input + and struct v4l2_output fields named ``std``, respectively. 8. The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` fields @@ -439,15 +417,13 @@ This unnamed version was finally merged into Linux 2.5.46. :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, but without the overhead of programming the hardware and regardless of I/O in progress. - In struct :c:type:`v4l2_format` the ``fmt`` union was - extended to contain struct :c:type:`v4l2_window`. All + In struct v4l2_format the ``fmt`` union was + extended to contain struct v4l2_window. All image format negotiations are now possible with ``VIDIOC_G_FMT``, ``VIDIOC_S_FMT`` and ``VIDIOC_TRY_FMT``; ioctl. The ``VIDIOC_G_WIN`` and ``VIDIOC_S_WIN`` ioctls to prepare for a video overlay were - removed. The ``type`` field changed to type enum - :c:type:`v4l2_buf_type` and the buffer type names - changed as follows. - + removed. The ``type`` field changed to type enum v4l2_buf_type and + the buffer type names changed as follows. .. flat-table:: @@ -455,7 +431,7 @@ This unnamed version was finally merged into Linux 2.5.46. :stub-columns: 0 * - Old defines - - enum :c:type:`v4l2_buf_type` + - enum v4l2_buf_type * - ``V4L2_BUF_TYPE_CAPTURE`` - ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` * - ``V4L2_BUF_TYPE_CODECIN`` @@ -483,16 +459,12 @@ This unnamed version was finally merged into Linux 2.5.46. * - ``V4L2_BUF_TYPE_PRIVATE_BASE`` - ``V4L2_BUF_TYPE_PRIVATE`` (but this is deprecated) +10. In struct v4l2_fmtdesc a enum v4l2_buf_type field named ``type`` was + added as in struct v4l2_format. The ``VIDIOC_ENUM_FBUFFMT`` ioctl is no + longer needed and was removed. These calls can be replaced by + :ref:`VIDIOC_ENUM_FMT` with type ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. -10. In struct :c:type:`v4l2_fmtdesc` a enum - :c:type:`v4l2_buf_type` field named ``type`` was - added as in struct :c:type:`v4l2_format`. The - ``VIDIOC_ENUM_FBUFFMT`` ioctl is no longer needed and was removed. - These calls can be replaced by - :ref:`VIDIOC_ENUM_FMT` with type - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. - -11. In struct :c:type:`v4l2_pix_format` the ``depth`` +11. In struct v4l2_pix_format the ``depth`` field was removed, assuming applications which recognize the format by its four-character-code already know the color depth, and others do not care about it. The same rationale lead to the removal of the @@ -505,18 +477,15 @@ This unnamed version was finally merged into Linux 2.5.46. Since the remaining flags were replaced as well, the ``flags`` field itself was removed. - The interlace flags were replaced by a enum - :c:type:`v4l2_field` value in a newly added ``field`` - field. - - + The interlace flags were replaced by a enum v4l2_field value in a + newly added ``field`` field. .. flat-table:: :header-rows: 1 :stub-columns: 0 * - Old flag - - enum :c:type:`v4l2_field` + - enum v4l2_field * - ``V4L2_FMT_FLAG_NOT_INTERLACED`` - ? * - ``V4L2_FMT_FLAG_INTERLACED`` = ``V4L2_FMT_FLAG_COMBINED`` @@ -532,33 +501,31 @@ This unnamed version was finally merged into Linux 2.5.46. * - ``-`` - ``V4L2_FIELD_ALTERNATE`` - - The color space flags were replaced by a enum - :c:type:`v4l2_colorspace` value in a newly added - ``colorspace`` field, where one of ``V4L2_COLORSPACE_SMPTE170M``, - ``V4L2_COLORSPACE_BT878``, ``V4L2_COLORSPACE_470_SYSTEM_M`` or + The color space flags were replaced by a enum v4l2_colorspace value in + a newly added ``colorspace`` field, where one of + ``V4L2_COLORSPACE_SMPTE170M``, ``V4L2_COLORSPACE_BT878``, + ``V4L2_COLORSPACE_470_SYSTEM_M`` or ``V4L2_COLORSPACE_470_SYSTEM_BG`` replaces ``V4L2_FMT_CS_601YUV``. -12. In struct :c:type:`v4l2_requestbuffers` the - ``type`` field was properly defined as enum - :c:type:`v4l2_buf_type`. Buffer types changed as - mentioned above. A new ``memory`` field of type enum - :c:type:`v4l2_memory` was added to distinguish between +12. In struct v4l2_requestbuffers the + ``type`` field was properly defined as enum v4l2_buf_type. Buffer types + changed as mentioned above. A new ``memory`` field of type + enum v4l2_memory was added to distinguish between I/O methods using buffers allocated by the driver or the application. See :ref:`io` for details. -13. In struct :c:type:`v4l2_buffer` the ``type`` field was - properly defined as enum :c:type:`v4l2_buf_type`. +13. In struct v4l2_buffer the ``type`` field was + properly defined as enum v4l2_buf_type. Buffer types changed as mentioned above. A ``field`` field of type - enum :c:type:`v4l2_field` was added to indicate if a + enum v4l2_field was added to indicate if a buffer contains a top or bottom field. The old field flags were removed. Since no unadjusted system time clock was added to the kernel as planned, the ``timestamp`` field changed back from type stamp_t, an unsigned 64 bit integer expressing the sample time in - nanoseconds, to struct :c:type:`timeval`. With the addition + nanoseconds, to struct timeval. With the addition of a second memory mapping method the ``offset`` field moved into - union ``m``, and a new ``memory`` field of type enum - :c:type:`v4l2_memory` was added to distinguish between + union ``m``, and a new ``memory`` field of type enum v4l2_memory + was added to distinguish between I/O methods. See :ref:`io` for details. The ``V4L2_BUF_REQ_CONTIG`` flag was used by the V4L compatibility @@ -567,7 +534,7 @@ This unnamed version was finally merged into Linux 2.5.46. indeed allocated in device memory rather than DMA-able system memory. It was barely useful and so was removed. -14. In struct :c:type:`v4l2_framebuffer` the +14. In struct v4l2_framebuffer the ``base[3]`` array anticipating double- and triple-buffering in off-screen video memory, however without defining a synchronization mechanism, was replaced by a single pointer. The @@ -578,40 +545,38 @@ This unnamed version was finally merged into Linux 2.5.46. ``V4L2_FBUF_CAP_LIST_CLIPPING`` and ``V4L2_FBUF_CAP_BITMAP_CLIPPING``. -15. In struct :c:type:`v4l2_clip` the ``x``, ``y``, +15. In struct v4l2_clip the ``x``, ``y``, ``width`` and ``height`` field moved into a ``c`` substructure of - type struct :c:type:`v4l2_rect`. The ``x`` and ``y`` + type struct v4l2_rect. The ``x`` and ``y`` fields were renamed to ``left`` and ``top``, i. e. offsets to a context dependent origin. -16. In struct :c:type:`v4l2_window` the ``x``, ``y``, +16. In struct v4l2_window the ``x``, ``y``, ``width`` and ``height`` field moved into a ``w`` substructure as - above. A ``field`` field of type :c:type:`v4l2_field` was added to + above. A ``field`` field of type enum v4l2_field was added to distinguish between field and frame (interlaced) overlay. -17. The digital zoom interface, including struct - struct ``v4l2_zoomcap``, struct +17. The digital zoom interface, including struct ``v4l2_zoomcap``, struct ``v4l2_zoom``, ``V4L2_ZOOM_NONCAP`` and ``V4L2_ZOOM_WHILESTREAMING`` was replaced by a new cropping and - scaling interface. The previously unused struct - struct :c:type:`v4l2_cropcap` and struct :c:type:`v4l2_crop` + scaling interface. The previously unused + struct v4l2_cropcap and struct v4l2_crop where redefined for this purpose. See :ref:`crop` for details. -18. In struct :c:type:`v4l2_vbi_format` the +18. In struct v4l2_vbi_format the ``SAMPLE_FORMAT`` field now contains a four-character-code as used to identify video image formats and ``V4L2_PIX_FMT_GREY`` replaces the ``V4L2_VBI_SF_UBYTE`` define. The ``reserved`` field was extended. -19. In struct :c:type:`v4l2_captureparm` the type of - the ``timeperframe`` field changed from unsigned long to struct - :c:type:`v4l2_fract`. This allows the accurate +19. In struct v4l2_captureparm the type of + the ``timeperframe`` field changed from unsigned long to + struct v4l2_fract. This allows the accurate expression of multiples of the NTSC-M frame rate 30000 / 1001. A new field ``readbuffers`` was added to control the driver behaviour in read I/O mode. - Similar changes were made to struct - :c:type:`v4l2_outputparm`. + Similar changes were made to struct v4l2_outputparm. 20. The struct ``v4l2_performance`` and ``VIDIOC_G_PERF`` ioctl were dropped. Except when using the @@ -622,7 +587,6 @@ This unnamed version was finally merged into Linux 2.5.46. V4L2 documentation was inaccurate, this has been corrected in :ref:`pixfmt`. - V4L2 2003-06-19 =============== @@ -673,7 +637,6 @@ V4L2 2003-06-19 Kernel 2.6.39. Drivers and applications assuming a constant parameter need an update. - V4L2 2003-11-05 =============== @@ -682,7 +645,6 @@ V4L2 2003-11-05 refer to bytes in memory, in ascending address order. - .. flat-table:: :header-rows: 1 :stub-columns: 0 @@ -703,7 +665,6 @@ V4L2 2003-11-05 - R, G, B, X - B, G, R, X - The ``V4L2_PIX_FMT_BGR24`` example was always correct. In :ref:`v4l-image-properties` the mapping of the V4L @@ -714,7 +675,6 @@ V4L2 2003-11-05 RGB pixel formats differently. These issues have yet to be addressed, for details see :ref:`pixfmt-rgb`. - V4L2 in Linux 2.6.6, 2004-05-09 =============================== @@ -723,18 +683,16 @@ V4L2 in Linux 2.6.6, 2004-05-09 ioctl, while the read-only version was renamed to ``VIDIOC_CROPCAP_OLD``. The old ioctl was removed on Kernel 2.6.39. - V4L2 in Linux 2.6.8 =================== 1. A new field ``input`` (former ``reserved[0]``) was added to the - struct :c:type:`v4l2_buffer` structure. Purpose of this + struct v4l2_buffer. Purpose of this field is to alternate between video inputs (e. g. cameras) in step with the video capturing process. This function must be enabled with the new ``V4L2_BUF_FLAG_INPUT`` flag. The ``flags`` field is no longer read-only. - V4L2 spec erratum 2004-08-01 ============================ @@ -748,11 +706,10 @@ V4L2 spec erratum 2004-08-01 4. The documentation of the :ref:`VIDIOC_QBUF` and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctls did not mention the - struct :c:type:`v4l2_buffer` ``memory`` field. It was + struct v4l2_buffer ``memory`` field. It was also missing from examples. Also on the ``VIDIOC_DQBUF`` page the ``EIO`` error code was not documented. - V4L2 in Linux 2.6.14 ==================== @@ -760,7 +717,6 @@ V4L2 in Linux 2.6.14 :ref:`sliced` and replaces the interface first proposed in V4L2 specification 0.8. - V4L2 in Linux 2.6.15 ==================== @@ -780,7 +736,6 @@ V4L2 in Linux 2.6.15 ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls where removed in Linux 2.6.25.) - V4L2 spec erratum 2005-11-27 ============================ @@ -790,37 +745,31 @@ cropping is supported. In the video standard selection example in :ref:`standard` the :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` call used the wrong argument type. - V4L2 spec erratum 2006-01-10 ============================ -1. The ``V4L2_IN_ST_COLOR_KILL`` flag in struct - :c:type:`v4l2_input` not only indicates if the color - killer is enabled, but also if it is active. (The color killer - disables color decoding when it detects no color in the video signal - to improve the image quality.) +1. The ``V4L2_IN_ST_COLOR_KILL`` flag in struct v4l2_input not only + indicates if the color killer is enabled, but also if it is active. + (The color killer disables color decoding when it detects no color + in the video signal to improve the image quality.) 2. :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` is a write-read ioctl, not write-only as stated on its reference page. The ioctl changed in 2003 as noted above. - V4L2 spec erratum 2006-02-03 ============================ -1. In struct :c:type:`v4l2_captureparm` and struct - :c:type:`v4l2_outputparm` the ``timeperframe`` +1. In struct v4l2_captureparm and struct v4l2_outputparm the ``timeperframe`` field gives the time in seconds, not microseconds. - V4L2 spec erratum 2006-02-04 ============================ -1. The ``clips`` field in struct :c:type:`v4l2_window` - must point to an array of struct :c:type:`v4l2_clip`, not - a linked list, because drivers ignore the struct - struct :c:type:`v4l2_clip`. ``next`` pointer. - +1. The ``clips`` field in struct v4l2_window + must point to an array of struct v4l2_clip, not + a linked list, because drivers ignore the + struct v4l2_clip. ``next`` pointer. V4L2 in Linux 2.6.17 ==================== @@ -836,7 +785,6 @@ V4L2 in Linux 2.6.17 ``V4L2_TUNER_MODE_STEREO`` for this purpose is deprecated now. See the :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` section for details. - V4L2 spec erratum 2006-09-23 (Draft 0.15) ========================================= @@ -844,19 +792,18 @@ V4L2 spec erratum 2006-09-23 (Draft 0.15) ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` of the sliced VBI interface were not mentioned along with other buffer types. -2. In :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` it was clarified that the struct - :c:type:`v4l2_audio` ``mode`` field is a flags field. +2. In :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` it was clarified that the + struct v4l2_audio ``mode`` field is a flags field. 3. :ref:`VIDIOC_QUERYCAP` did not mention the sliced VBI and radio capability flags. -4. In :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` it was clarified that applications - must initialize the tuner ``type`` field of struct - :c:type:`v4l2_frequency` before calling +4. In :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` it was clarified that + applications must initialize the tuner ``type`` field of + struct v4l2_frequency before calling :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>`. -5. The ``reserved`` array in struct - :c:type:`v4l2_requestbuffers` has 2 elements, +5. The ``reserved`` array in struct v4l2_requestbuffers has 2 elements, not 32. 6. In :ref:`output` and :ref:`raw-vbi` the device file names @@ -866,7 +813,6 @@ V4L2 spec erratum 2006-09-23 (Draft 0.15) extended from 224-239 to 224-255. Accordingly device file names ``/dev/vbi0`` to ``/dev/vbi31`` are possible now. - V4L2 in Linux 2.6.18 ==================== @@ -876,16 +822,15 @@ V4L2 in Linux 2.6.18 flag to skip unsupported controls with :ref:`VIDIOC_QUERYCTRL`, new control types ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_TYPE_CTRL_CLASS`` - (:c:type:`v4l2_ctrl_type`), and new control flags + (enum v4l2_ctrl_type), and new control flags ``V4L2_CTRL_FLAG_READ_ONLY``, ``V4L2_CTRL_FLAG_UPDATE``, ``V4L2_CTRL_FLAG_INACTIVE`` and ``V4L2_CTRL_FLAG_SLIDER`` (:ref:`control-flags`). See :ref:`extended-controls` for details. - V4L2 in Linux 2.6.19 ==================== -1. In struct :c:type:`v4l2_sliced_vbi_cap` a +1. In struct v4l2_sliced_vbi_cap a buffer type field was added replacing a reserved field. Note on architectures where the size of enum types differs from int types the size of the structure changed. The @@ -903,14 +848,12 @@ V4L2 in Linux 2.6.19 3. A new pixel format ``V4L2_PIX_FMT_RGB444`` (:ref:`pixfmt-rgb`) was added. - V4L2 spec erratum 2006-10-12 (Draft 0.17) ========================================= 1. ``V4L2_PIX_FMT_HM12`` (:ref:`reserved-formats`) is a YUV 4:2:0, not 4:2:2 format. - V4L2 in Linux 2.6.21 ==================== @@ -918,12 +861,11 @@ V4L2 in Linux 2.6.21 General Public License version two or later, and under a 3-clause BSD-style license. - V4L2 in Linux 2.6.22 ==================== 1. Two new field orders ``V4L2_FIELD_INTERLACED_TB`` and - ``V4L2_FIELD_INTERLACED_BT`` were added. See :c:type:`v4l2_field` for + ``V4L2_FIELD_INTERLACED_BT`` were added. See enum v4l2_field for details. 2. Three new clipping/blending methods with a global or straight or @@ -931,20 +873,17 @@ V4L2 in Linux 2.6.22 See the description of the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctls for details. - A new ``global_alpha`` field was added to - :c:type:`v4l2_window`, extending the structure. This - may *break compatibility* with applications using a struct - struct :c:type:`v4l2_window` directly. However the + A new ``global_alpha`` field was added to struct v4l2_window, + extending the structure. This may **break compatibility** with + applications using a struct v4l2_window directly. However the :ref:`VIDIOC_G/S/TRY_FMT <VIDIOC_G_FMT>` ioctls, which take a - pointer to a :c:type:`v4l2_format` parent structure + pointer to a struct v4l2_format parent structure with padding bytes at the end, are not affected. -3. The format of the ``chromakey`` field in struct - :c:type:`v4l2_window` changed from "host order RGB32" - to a pixel value in the same format as the framebuffer. This may - *break compatibility* with existing applications. Drivers supporting - the "host order RGB32" format are not known. - +3. The format of the ``chromakey`` field in struct v4l2_window changed from + "host order RGB32" to a pixel value in the same format as the framebuffer. + This may **break compatibility** with existing applications. Drivers + supporting the "host order RGB32" format are not known. V4L2 in Linux 2.6.24 ==================== @@ -953,7 +892,6 @@ V4L2 in Linux 2.6.24 ``V4L2_PIX_FMT_YUV555``, ``V4L2_PIX_FMT_YUV565`` and ``V4L2_PIX_FMT_YUV32`` were added. - V4L2 in Linux 2.6.25 ==================== @@ -980,7 +918,6 @@ V4L2 in Linux 2.6.25 interface in Linux 2.6.18, where finally removed from the ``videodev2.h`` header file. - V4L2 in Linux 2.6.26 ==================== @@ -990,7 +927,6 @@ V4L2 in Linux 2.6.26 2. Added user controls ``V4L2_CID_CHROMA_AGC`` and ``V4L2_CID_COLOR_KILLER``. - V4L2 in Linux 2.6.27 ==================== @@ -1002,7 +938,6 @@ V4L2 in Linux 2.6.27 ``V4L2_PIX_FMT_PCA561``, ``V4L2_PIX_FMT_SGBRG8``, ``V4L2_PIX_FMT_PAC207`` and ``V4L2_PIX_FMT_PJPG`` were added. - V4L2 in Linux 2.6.28 ==================== @@ -1014,14 +949,12 @@ V4L2 in Linux 2.6.28 3. The pixel formats ``V4L2_PIX_FMT_SGRBG10`` and ``V4L2_PIX_FMT_SGRBG10DPCM8`` were added. - V4L2 in Linux 2.6.29 ==================== 1. The ``VIDIOC_G_CHIP_IDENT`` ioctl was renamed to ``VIDIOC_G_CHIP_IDENT_OLD`` and ``VIDIOC_DBG_G_CHIP_IDENT`` was - introduced in its place. The old struct - struct ``v4l2_chip_ident`` was renamed to + introduced in its place. The old struct ``v4l2_chip_ident`` was renamed to struct ``v4l2_chip_ident_old``. 2. The pixel formats ``V4L2_PIX_FMT_VYUY``, ``V4L2_PIX_FMT_NV16`` and @@ -1031,7 +964,6 @@ V4L2 in Linux 2.6.29 ``V4L2_CID_ZOOM_RELATIVE``, ``V4L2_CID_ZOOM_CONTINUOUS`` and ``V4L2_CID_PRIVACY``. - V4L2 in Linux 2.6.30 ==================== @@ -1039,7 +971,6 @@ V4L2 in Linux 2.6.30 2. New control ``V4L2_CID_COLORFX`` was added. - V4L2 in Linux 2.6.32 ==================== @@ -1066,21 +997,18 @@ V4L2 in Linux 2.6.32 9. Added Remote Controller chapter, describing the default Remote Controller mapping for media devices. - V4L2 in Linux 2.6.33 ==================== 1. Added support for Digital Video timings in order to support HDTV receivers and transmitters. - V4L2 in Linux 2.6.34 ==================== 1. Added ``V4L2_CID_IRIS_ABSOLUTE`` and ``V4L2_CID_IRIS_RELATIVE`` controls to the :ref:`Camera controls class <camera-controls>`. - V4L2 in Linux 2.6.37 ==================== @@ -1089,7 +1017,6 @@ V4L2 in Linux 2.6.37 applications found that used it. It was originally scheduled for removal in 2.6.35. - V4L2 in Linux 2.6.39 ==================== @@ -1099,7 +1026,6 @@ V4L2 in Linux 2.6.39 drivers and applications. See :ref:`multi-planar API <planar-apis>` for details. - V4L2 in Linux 3.1 ================= @@ -1110,7 +1036,6 @@ V4L2 in Linux 3.1 Added V4L2_CTRL_TYPE_BITMASK. - V4L2 in Linux 3.2 ================= @@ -1121,7 +1046,6 @@ V4L2 in Linux 3.2 Does not affect the compatibility of current drivers and applications. See :ref:`selection API <selection-api>` for details. - V4L2 in Linux 3.3 ================= @@ -1131,7 +1055,6 @@ V4L2 in Linux 3.3 2. Added the device_caps field to struct v4l2_capabilities and added the new V4L2_CAP_DEVICE_CAPS capability. - V4L2 in Linux 3.4 ================= @@ -1142,7 +1065,6 @@ V4L2 in Linux 3.4 :ref:`VIDIOC_QUERY_DV_TIMINGS` and :ref:`VIDIOC_DV_TIMINGS_CAP`. - V4L2 in Linux 3.5 ================= @@ -1169,11 +1091,10 @@ V4L2 in Linux 3.5 ``V4L2_CID_AUTO_FOCUS_START``, ``V4L2_CID_AUTO_FOCUS_STOP``, ``V4L2_CID_AUTO_FOCUS_STATUS`` and ``V4L2_CID_AUTO_FOCUS_RANGE``. - V4L2 in Linux 3.6 ================= -1. Replaced ``input`` in struct :c:type:`v4l2_buffer` by +1. Replaced ``input`` in struct v4l2_buffer by ``reserved2`` and removed ``V4L2_BUF_FLAG_INPUT``. 2. Added V4L2_CAP_VIDEO_M2M and V4L2_CAP_VIDEO_M2M_MPLANE @@ -1182,17 +1103,15 @@ V4L2 in Linux 3.6 3. Added support for frequency band enumerations: :ref:`VIDIOC_ENUM_FREQ_BANDS`. - V4L2 in Linux 3.9 ================= 1. Added timestamp types to ``flags`` field in - struct :c:type:`v4l2_buffer`. See :ref:`buffer-flags`. + struct v4l2_buffer. See :ref:`buffer-flags`. 2. Added ``V4L2_EVENT_CTRL_CH_RANGE`` control event changes flag. See :ref:`ctrl-changes-flags`. - V4L2 in Linux 3.10 ================== @@ -1204,59 +1123,48 @@ V4L2 in Linux 3.10 2. Added new debugging ioctl :ref:`VIDIOC_DBG_G_CHIP_INFO`. - V4L2 in Linux 3.11 ================== 1. Remove obsolete ``VIDIOC_DBG_G_CHIP_IDENT`` ioctl. - V4L2 in Linux 3.14 ================== -1. In struct :c:type:`v4l2_rect`, the type of ``width`` and +1. In struct v4l2_rect, the type of ``width`` and ``height`` fields changed from _s32 to _u32. - V4L2 in Linux 3.15 ================== 1. Added Software Defined Radio (SDR) Interface. - V4L2 in Linux 3.16 ================== 1. Added event V4L2_EVENT_SOURCE_CHANGE. - V4L2 in Linux 3.17 ================== -1. Extended struct :c:type:`v4l2_pix_format`. Added +1. Extended struct v4l2_pix_format. Added format flags. 2. Added compound control types and :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`. - V4L2 in Linux 3.18 ================== 1. Added ``V4L2_CID_PAN_SPEED`` and ``V4L2_CID_TILT_SPEED`` camera controls. - V4L2 in Linux 3.19 ================== -1. Rewrote Colorspace chapter, added new enum - :c:type:`v4l2_ycbcr_encoding` and enum - :c:type:`v4l2_quantization` fields to struct - :c:type:`v4l2_pix_format`, struct - :c:type:`v4l2_pix_format_mplane` and - struct :c:type:`v4l2_mbus_framefmt`. - +1. Rewrote Colorspace chapter, added new enum v4l2_ycbcr_encoding + and enum v4l2_quantization fields to struct v4l2_pix_format, + struct v4l2_pix_format_mplane and struct v4l2_mbus_framefmt. V4L2 in Linux 4.4 ================= @@ -1268,13 +1176,11 @@ V4L2 in Linux 4.4 3. Added transmitter support for Software Defined Radio (SDR) Interface. - .. _other: Relation of V4L2 to other Linux multimedia APIs =============================================== - .. _xvideo: X Video Extension @@ -1320,7 +1226,6 @@ YUV to RGB conversion and scaling for faster video playback, and added an interface to MPEG-2 decoding hardware. This API is useful to display images captured with V4L2 devices. - Digital Video ------------- @@ -1330,13 +1235,11 @@ homepage at `https://linuxtv.org <https://linuxtv.org>`__. The Linux DVB API has no connection to the V4L2 API except that drivers for hybrid hardware may support both. - Audio Interfaces ---------------- [to do - OSS/ALSA] - .. _experimental: Experimental API Elements @@ -1350,7 +1253,6 @@ change in the future. - :ref:`VIDIOC_DBG_G_CHIP_INFO` ioctl. - .. _obsolete: Obsolete API Elements diff --git a/Documentation/userspace-api/media/v4l/hsv-formats.rst b/Documentation/userspace-api/media/v4l/hsv-formats.rst index 4906f7e0d80d..d810c914b673 100644 --- a/Documentation/userspace-api/media/v4l/hsv-formats.rst +++ b/Documentation/userspace-api/media/v4l/hsv-formats.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _hsv-formats: diff --git a/Documentation/userspace-api/media/v4l/io.rst b/Documentation/userspace-api/media/v4l/io.rst index de0e2f529268..4b1964df9d73 100644 --- a/Documentation/userspace-api/media/v4l/io.rst +++ b/Documentation/userspace-api/media/v4l/io.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _io: @@ -16,15 +10,14 @@ The V4L2 API defines several different methods to read from or write to a device. All drivers exchanging data with applications must support at least one of them. -The classic I/O method using the :ref:`read() <func-read>` and -:ref:`write() <func-write>` function is automatically selected after opening a +The classic I/O method using the :c:func:`read()` and +:c:func:`write()` function is automatically selected after opening a V4L2 device. When the driver does not support this method attempts to read or write will fail at any time. Other methods must be negotiated. To select the streaming I/O method with memory mapped or user buffers applications call the -:ref:`VIDIOC_REQBUFS` ioctl. The asynchronous I/O -method is not defined yet. +:ref:`VIDIOC_REQBUFS` ioctl. Video overlay can be considered another I/O method, although the application does not directly receive the image data. It is selected by @@ -45,7 +38,6 @@ closing and reopening the device. The following sections describe the various I/O methods in more detail. - .. toctree:: :maxdepth: 1 @@ -53,6 +45,5 @@ The following sections describe the various I/O methods in more detail. mmap userp dmabuf - async buffer field-order diff --git a/Documentation/userspace-api/media/v4l/libv4l-introduction.rst b/Documentation/userspace-api/media/v4l/libv4l-introduction.rst index 95f3127b4749..7c8bf160e1c6 100644 --- a/Documentation/userspace-api/media/v4l/libv4l-introduction.rst +++ b/Documentation/userspace-api/media/v4l/libv4l-introduction.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _libv4l-introduction: @@ -24,7 +18,6 @@ An example of using libv4l is provided by libv4l consists of 3 different libraries: - libv4lconvert ============= @@ -33,7 +26,7 @@ found in V4L2 drivers into a few common RGB and YUY formats. It currently accepts the following V4L2 driver formats: :ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR24>`, -:ref:`V4L2_PIX_FMT_HM12 <V4L2-PIX-FMT-HM12>`, +:ref:`V4L2_PIX_FMT_NV12_16L16 <V4L2-PIX-FMT-NV12-16L16>`, :ref:`V4L2_PIX_FMT_JPEG <V4L2-PIX-FMT-JPEG>`, :ref:`V4L2_PIX_FMT_MJPEG <V4L2-PIX-FMT-MJPEG>`, :ref:`V4L2_PIX_FMT_MR97310A <V4L2-PIX-FMT-MR97310A>`, @@ -72,7 +65,6 @@ libv4lconvert/processing. These controls are stored application wide libv4lconvert/processing offers the actual video processing functionality. - libv4l1 ======= @@ -85,7 +77,6 @@ just pass calls through. Since those functions are emulations of the old V4L1 API, it shouldn't be used for new applications. - libv4l2 ======= @@ -112,7 +103,6 @@ available in the driver. :ref:`VIDIOC_ENUM_FMT <VIDIOC_ENUM_FMT>` keeps enumerating the hardware supported formats, plus the emulated formats offered by libv4l at the end. - .. _libv4l-ops: Libv4l device control functions @@ -122,17 +112,17 @@ The common file operation methods are provided by libv4l. Those functions operate just like the gcc function ``dup()`` and V4L2 functions -:c:func:`open() <v4l2-open>`, :c:func:`close() <v4l2-close>`, -:c:func:`ioctl() <v4l2-ioctl>`, :c:func:`read() <v4l2-read>`, -:c:func:`mmap() <v4l2-mmap>` and :c:func:`munmap() <v4l2-munmap>`: +:c:func:`open()`, :c:func:`close()`, +:c:func:`ioctl()`, :c:func:`read()`, +:c:func:`mmap()` and :c:func:`munmap()`: .. c:function:: int v4l2_open(const char *file, int oflag, ...) - operates like the :c:func:`open() <v4l2-open>` function. + operates like the :c:func:`open()` function. .. c:function:: int v4l2_close(int fd) - operates like the :c:func:`close() <v4l2-close>` function. + operates like the :c:func:`close()` function. .. c:function:: int v4l2_dup(int fd) @@ -140,19 +130,19 @@ V4L2 functions .. c:function:: int v4l2_ioctl (int fd, unsigned long int request, ...) - operates like the :c:func:`ioctl() <v4l2-ioctl>` function. + operates like the :c:func:`ioctl()` function. .. c:function:: int v4l2_read (int fd, void* buffer, size_t n) - operates like the :c:func:`read() <v4l2-read>` function. + operates like the :c:func:`read()` function. -.. c:function:: void v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset); +.. c:function:: void *v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset); - operates like the :c:func:`munmap() <v4l2-munmap>` function. + operates like the :c:func:`mmap()` function. .. c:function:: int v4l2_munmap(void *_start, size_t length); - operates like the :c:func:`munmap() <v4l2-munmap>` function. + operates like the :c:func:`munmap()` function. Those functions provide additional control: @@ -175,14 +165,13 @@ Those functions provide additional control: of the given v4l control id. when the cid does not exist, could not be accessed for some reason, or some error occurred 0 is returned. - v4l1compat.so wrapper library ============================= This library intercepts calls to -:c:func:`open() <v4l2-open>`, :c:func:`close() <v4l2-close>`, -:c:func:`ioctl() <v4l2-ioctl>`, :c:func:`mmap() <v4l2-mmap>` and -:c:func:`munmap() <v4l2-munmap>` +:c:func:`open()`, :c:func:`close()`, +:c:func:`ioctl()`, :c:func:`mmap()` and +:c:func:`munmap()` operations and redirects them to the libv4l counterparts, by using ``LD_PRELOAD=/usr/lib/v4l1compat.so``. It also emulates V4L1 calls via V4L2 API. diff --git a/Documentation/userspace-api/media/v4l/libv4l.rst b/Documentation/userspace-api/media/v4l/libv4l.rst index 5ea2016cac65..f446dd2d01ac 100644 --- a/Documentation/userspace-api/media/v4l/libv4l.rst +++ b/Documentation/userspace-api/media/v4l/libv4l.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _libv4l: diff --git a/Documentation/userspace-api/media/v4l/meta-formats.rst b/Documentation/userspace-api/media/v4l/meta-formats.rst index 7dcc4bacbb0c..bb6876cfc271 100644 --- a/Documentation/userspace-api/media/v4l/meta-formats.rst +++ b/Documentation/userspace-api/media/v4l/meta-formats.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _meta-formats: @@ -19,9 +12,14 @@ These formats are used for the :ref:`metadata` interface only. .. toctree:: :maxdepth: 1 - pixfmt-meta-d4xx - pixfmt-meta-intel-ipu3 - pixfmt-meta-uvc - pixfmt-meta-vsp1-hgo - pixfmt-meta-vsp1-hgt - pixfmt-meta-vivid + metafmt-c3-isp + metafmt-d4xx + metafmt-generic + metafmt-intel-ipu3 + metafmt-pisp-be + metafmt-pisp-fe + metafmt-rkisp1 + metafmt-uvc + metafmt-vivid + metafmt-vsp1-hgo + metafmt-vsp1-hgt diff --git a/Documentation/userspace-api/media/v4l/metafmt-c3-isp.rst b/Documentation/userspace-api/media/v4l/metafmt-c3-isp.rst new file mode 100644 index 000000000000..449b45c2ec24 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/metafmt-c3-isp.rst @@ -0,0 +1,86 @@ +.. SPDX-License-Identifier: (GPL-2.0-only OR MIT) + +.. _v4l2-meta-fmt-c3isp-stats: +.. _v4l2-meta-fmt-c3isp-params: + +*********************************************************************** +V4L2_META_FMT_C3ISP_STATS ('C3ST'), V4L2_META_FMT_C3ISP_PARAMS ('C3PM') +*********************************************************************** + +.. c3_isp_stats_info + +3A Statistics +============= + +The C3 ISP can collect different statistics over an input Bayer frame. +Those statistics are obtained from the "c3-isp-stats" metadata capture video nodes, +using the :c:type:`v4l2_meta_format` interface. +They are formatted as described by the :c:type:`c3_isp_stats_info` structure. + +The statistics collected are Auto-white balance, +Auto-exposure and Auto-focus information. + +.. c3_isp_params_cfg + +Configuration Parameters +======================== + +The configuration parameters are passed to the c3-isp-params metadata output video node, +using the :c:type:`v4l2_meta_format` interface. Rather than a single struct containing +sub-structs for each configurable area of the ISP, parameters for the C3-ISP +are defined as distinct structs or "blocks" which may be added to the data +member of :c:type:`c3_isp_params_cfg`. Userspace is responsible for +populating the data member with the blocks that need to be configured by the driver, but +need not populate it with **all** the blocks, or indeed with any at all if there +are no configuration changes to make. Populated blocks **must** be consecutive +in the buffer. To assist both userspace and the driver in identifying the +blocks each block-specific struct embeds +:c:type:`c3_isp_params_block_header` as its first member and userspace +must populate the type member with a value from +:c:type:`c3_isp_params_block_type`. Once the blocks have been populated +into the data buffer, the combined size of all populated blocks shall be set in +the data_size member of :c:type:`c3_isp_params_cfg`. For example: + +.. code-block:: c + + struct c3_isp_params_cfg *params = + (struct c3_isp_params_cfg *)buffer; + + params->version = C3_ISP_PARAM_BUFFER_V0; + params->data_size = 0; + + void *data = (void *)params->data; + + struct c3_isp_params_awb_gains *gains = + (struct c3_isp_params_awb_gains *)data; + + gains->header.type = C3_ISP_PARAMS_BLOCK_AWB_GAINS; + gains->header.flags = C3_ISP_PARAMS_BLOCK_FL_ENABLE; + gains->header.size = sizeof(struct c3_isp_params_awb_gains); + + gains->gr_gain = 256; + gains->r_gain = 256; + gains->b_gain = 256; + gains->gb_gain = 256; + + data += sizeof(struct c3_isp__params_awb_gains); + params->data_size += sizeof(struct c3_isp_params_awb_gains); + + struct c3_isp_params_awb_config *awb_cfg = + (struct c3_isp_params_awb_config *)data; + + awb_cfg->header.type = C3_ISP_PARAMS_BLOCK_AWB_CONFIG; + awb_cfg->header.flags = C3_ISP_PARAMS_BLOCK_FL_ENABLE; + awb_cfg->header.size = sizeof(struct c3_isp_params_awb_config); + + awb_cfg->tap_point = C3_ISP_AWB_STATS_TAP_BEFORE_WB; + awb_cfg->satur = 1; + awb_cfg->horiz_zones_num = 32; + awb_cfg->vert_zones_num = 24; + + params->data_size += sizeof(struct c3_isp_params_awb_config); + +Amlogic C3 ISP uAPI data types +=============================== + +.. kernel-doc:: include/uapi/linux/media/amlogic/c3-isp-config.h diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst b/Documentation/userspace-api/media/v4l/metafmt-d4xx.rst index 4eaf2f9086a9..0686413b16b2 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-d4xx.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2-meta-fmt-d4xx: @@ -19,7 +12,7 @@ Intel D4xx UVC Cameras Metadata Description =========== -Intel D4xx (D435 and other) cameras include per-frame metadata in their UVC +Intel D4xx (D435, D455 and others) cameras include per-frame metadata in their UVC payload headers, following the Microsoft(R) UVC extension proposal [1_]. That means, that the private D4XX metadata, following the standard UVC header, is organised in blocks. D4XX cameras implement several standard block types, @@ -33,6 +26,8 @@ V4L2_META_FMT_UVC with the only difference, that it also includes proprietary payload header data. D4xx cameras use bulk transfers and only send one payload per frame, therefore their headers cannot be larger than 255 bytes. +This document implements Intel Configuration version 3 [9_]. + Below are proprietary Microsoft style metadata types, used by D4xx cameras, where all fields are in little endian order: @@ -50,10 +45,10 @@ where all fields are in little endian order: * - __u32 ID - 0x80000000 * - __u32 Size - - Size in bytes (currently 56) + - Size in bytes, include ID (all protocol versions: 60) * - __u32 Version - - Version of this structure. The documentation herein corresponds to - version xxx. The version number will be incremented when new fields are + - Version of this structure. The documentation herein covers versions 1, + 2 and 3. The version number will be incremented when new fields are added. * - __u32 Flags - A bitmask of flags: see [2_] below @@ -79,13 +74,17 @@ where all fields are in little endian order: - Bottom border of the AE Region of Interest * - __u32 Preset - Preset selector value, default: 0, unless changed by the user - * - __u32 Laser mode - - 0: off, 1: on + * - __u8 Emitter mode (v3 only) (__u32 Laser mode for v1) [8_] + - 0: off, 1: on, same as __u32 Laser mode for v1 + * - __u8 RFU byte (v3 only) + - Spare byte for future use + * - __u16 LED Power (v3 only) + - Led power value 0-360 (F416 SKU) * - :cspan:`1` *Capture Timing* * - __u32 ID - 0x80000001 * - __u32 Size - - Size in bytes (currently 40) + - Size in bytes, include ID (all protocol versions: 40) * - __u32 Version - Version of this structure. The documentation herein corresponds to version xxx. The version number will be incremented when new fields are @@ -108,7 +107,7 @@ where all fields are in little endian order: * - __u32 ID - 0x80000002 * - __u32 Size - - Size in bytes (currently 40) + - Size in bytes, include ID (v1:36, v3:40) * - __u32 Version - Version of this structure. The documentation herein corresponds to version xxx. The version number will be incremented when new fields are @@ -131,6 +130,14 @@ where all fields are in little endian order: - Requested frame rate per second * - __u16 Trigger - Byte 0: bit 0: depth and RGB are synchronised, bit 1: external trigger + * - __u16 Calibration count (v3 only) + - Calibration counter, see [4_] below + * - __u8 GPIO input data (v3 only) + - GPIO readout, see [4_] below (Supported from FW 5.12.7.0) + * - __u32 Sub-preset info (v3 only) + - Sub-preset choice information, see [4_] below + * - __u8 reserved (v3 only) + - RFU byte. .. _1: @@ -147,6 +154,8 @@ where all fields are in little endian order: 0x00000010 Exposure priority 0x00000020 AE ROI 0x00000040 Preset + 0x00000080 Emitter mode + 0x00000100 LED Power .. _3: @@ -172,6 +181,8 @@ where all fields are in little endian order: 0x00000040 Framerate 0x00000080 Trigger 0x00000100 Cal count + 0x00000200 GPIO Input Data + 0x00000400 Sub-preset Info .. _5: @@ -218,3 +229,24 @@ Left sensor: :: Fish Eye sensor: :: 1 RAW8 + +.. _8: + +[8] The "Laser mode" has been replaced in version 3 by three different fields. +"Laser" has been renamed to "Emitter" as there are multiple technologies for +camera projectors. As we have another field for "Laser Power" we introduced +"LED Power" for extra emitter. + +The "Laser mode" __u32 fields has been split into: :: + 1 __u8 Emitter mode + 2 __u8 RFU byte + 3 __u16 LED Power + +This is a change between versions 1 and 3. All versions 1, 2 and 3 are backward +compatible with the same data format and they are supported. See [2_] for which +attributes are valid. + +.. _9: + +[9] LibRealSense SDK metadata source: +https://github.com/IntelRealSense/librealsense/blob/master/src/metadata.h diff --git a/Documentation/userspace-api/media/v4l/metafmt-generic.rst b/Documentation/userspace-api/media/v4l/metafmt-generic.rst new file mode 100644 index 000000000000..78ab56b21682 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/metafmt-generic.rst @@ -0,0 +1,340 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later + +******************************************************************************************************************************************************************************************************************************************************************************** +V4L2_META_FMT_GENERIC_8 ('MET8'), V4L2_META_FMT_GENERIC_CSI2_10 ('MC1A'), V4L2_META_FMT_GENERIC_CSI2_12 ('MC1C'), V4L2_META_FMT_GENERIC_CSI2_14 ('MC1E'), V4L2_META_FMT_GENERIC_CSI2_16 ('MC1G'), V4L2_META_FMT_GENERIC_CSI2_20 ('MC1K'), V4L2_META_FMT_GENERIC_CSI2_24 ('MC1O') +******************************************************************************************************************************************************************************************************************************************************************************** + + +Generic line-based metadata formats + + +Description +=========== + +These generic line-based metadata formats define the memory layout of the data +without defining the format or meaning of the metadata itself. + +.. _v4l2-meta-fmt-generic-8: + +V4L2_META_FMT_GENERIC_8 +----------------------- + +The V4L2_META_FMT_GENERIC_8 format is a plain 8-bit metadata format. This format +is used on CSI-2 for 8 bits per :term:`Data Unit`. + +Additionally it is used for 16 bits per Data Unit when two bytes of metadata are +packed into one 16-bit Data Unit. Otherwise the 16 bits per pixel dataformat is +:ref:`V4L2_META_FMT_GENERIC_CSI2_16 <v4l2-meta-fmt-generic-csi2-16>`. + +**Byte Order Of V4L2_META_FMT_GENERIC_8.** +Each cell is one byte. "M" denotes a byte of metadata. + +.. tabularcolumns:: |p{2.4cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}| + +.. flat-table:: Sample 4x2 Metadata Frame + :header-rows: 0 + :stub-columns: 0 + :widths: 12 8 8 8 8 + + * - start + 0: + - M\ :sub:`00` + - M\ :sub:`10` + - M\ :sub:`20` + - M\ :sub:`30` + * - start + 4: + - M\ :sub:`01` + - M\ :sub:`11` + - M\ :sub:`21` + - M\ :sub:`31` + +.. _v4l2-meta-fmt-generic-csi2-10: + +V4L2_META_FMT_GENERIC_CSI2_10 +----------------------------- + +V4L2_META_FMT_GENERIC_CSI2_10 contains 8-bit generic metadata packed in 10-bit +Data Units, with one padding byte after every four bytes of metadata. This +format is typically used by CSI-2 receivers with a source that transmits +MEDIA_BUS_FMT_META_10 and the CSI-2 receiver writes the received data to memory +as-is. + +The packing of the data follows the MIPI CSI-2 specification and the padding of +the data is defined in the MIPI CCS specification. + +This format is also used in conjunction with 20 bits per :term:`Data Unit` +formats that pack two bytes of metadata into one Data Unit. Otherwise the +20 bits per pixel dataformat is :ref:`V4L2_META_FMT_GENERIC_CSI2_20 +<v4l2-meta-fmt-generic-csi2-20>`. + +This format is little endian. + +**Byte Order Of V4L2_META_FMT_GENERIC_CSI2_10.** +Each cell is one byte. "M" denotes a byte of metadata and "x" a byte of padding. + +.. tabularcolumns:: |p{2.4cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|p{.8cm}| + +.. flat-table:: Sample 4x2 Metadata Frame + :header-rows: 0 + :stub-columns: 0 + :widths: 12 8 8 8 8 8 + + * - start + 0: + - M\ :sub:`00` + - M\ :sub:`10` + - M\ :sub:`20` + - M\ :sub:`30` + - x + * - start + 5: + - M\ :sub:`01` + - M\ :sub:`11` + - M\ :sub:`21` + - M\ :sub:`31` + - x + +.. _v4l2-meta-fmt-generic-csi2-12: + +V4L2_META_FMT_GENERIC_CSI2_12 +----------------------------- + +V4L2_META_FMT_GENERIC_CSI2_12 contains 8-bit generic metadata packed in 12-bit +Data Units, with one padding byte after every two bytes of metadata. This format +is typically used by CSI-2 receivers with a source that transmits +MEDIA_BUS_FMT_META_12 and the CSI-2 receiver writes the received data to memory +as-is. + +The packing of the data follows the MIPI CSI-2 specification and the padding of +the data is defined in the MIPI CCS specification. + +This format is also used in conjunction with 24 bits per :term:`Data Unit` +formats that pack two bytes of metadata into one Data Unit. Otherwise the +24 bits per pixel dataformat is :ref:`V4L2_META_FMT_GENERIC_CSI2_24 +<v4l2-meta-fmt-generic-csi2-24>`. + +This format is little endian. + +**Byte Order Of V4L2_META_FMT_GENERIC_CSI2_12.** +Each cell is one byte. "M" denotes a byte of metadata and "x" a byte of padding. + +.. tabularcolumns:: |p{2.4cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|p{.8cm}|p{.8cm}| + +.. flat-table:: Sample 4x2 Metadata Frame + :header-rows: 0 + :stub-columns: 0 + :widths: 12 8 8 8 8 8 8 + + * - start + 0: + - M\ :sub:`00` + - M\ :sub:`10` + - x + - M\ :sub:`20` + - M\ :sub:`30` + - x + * - start + 6: + - M\ :sub:`01` + - M\ :sub:`11` + - x + - M\ :sub:`21` + - M\ :sub:`31` + - x + +.. _v4l2-meta-fmt-generic-csi2-14: + +V4L2_META_FMT_GENERIC_CSI2_14 +----------------------------- + +V4L2_META_FMT_GENERIC_CSI2_14 contains 8-bit generic metadata packed in 14-bit +Data Units, with three padding bytes after every four bytes of metadata. This +format is typically used by CSI-2 receivers with a source that transmits +MEDIA_BUS_FMT_META_14 and the CSI-2 receiver writes the received data to memory +as-is. + +The packing of the data follows the MIPI CSI-2 specification and the padding of +the data is defined in the MIPI CCS specification. + +This format is little endian. + +**Byte Order Of V4L2_META_FMT_GENERIC_CSI2_14.** +Each cell is one byte. "M" denotes a byte of metadata and "x" a byte of padding. + +.. tabularcolumns:: |p{2.4cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|p{.8cm}|p{.8cm}|p{.8cm}| + +.. flat-table:: Sample 4x2 Metadata Frame + :header-rows: 0 + :stub-columns: 0 + :widths: 12 8 8 8 8 8 8 8 + + * - start + 0: + - M\ :sub:`00` + - M\ :sub:`10` + - M\ :sub:`20` + - M\ :sub:`30` + - x + - x + - x + * - start + 7: + - M\ :sub:`01` + - M\ :sub:`11` + - M\ :sub:`21` + - M\ :sub:`31` + - x + - x + - x + +.. _v4l2-meta-fmt-generic-csi2-16: + +V4L2_META_FMT_GENERIC_CSI2_16 +----------------------------- + +V4L2_META_FMT_GENERIC_CSI2_16 contains 8-bit generic metadata packed in 16-bit +Data Units, with one padding byte after every byte of metadata. This format is +typically used by CSI-2 receivers with a source that transmits +MEDIA_BUS_FMT_META_16 and the CSI-2 receiver writes the received data to memory +as-is. + +The packing of the data follows the MIPI CSI-2 specification and the padding of +the data is defined in the MIPI CCS specification. + +Some devices support more efficient packing of metadata in conjunction with +16-bit image data. In that case the dataformat is +:ref:`V4L2_META_FMT_GENERIC_8 <v4l2-meta-fmt-generic-8>`. + +This format is little endian. + +**Byte Order Of V4L2_META_FMT_GENERIC_CSI2_16.** +Each cell is one byte. "M" denotes a byte of metadata and "x" a byte of padding. + +.. tabularcolumns:: |p{2.4cm}|p{1.2cm}|p{.8cm}|p{1.2cm}|p{.8cm}|p{1.2cm}|p{.8cm}|p{1.2cm}|p{.8cm}| + +.. flat-table:: Sample 4x2 Metadata Frame + :header-rows: 0 + :stub-columns: 0 + :widths: 12 8 8 8 8 8 8 8 8 + + * - start + 0: + - M\ :sub:`00` + - x + - M\ :sub:`10` + - x + - M\ :sub:`20` + - x + - M\ :sub:`30` + - x + * - start + 8: + - M\ :sub:`01` + - x + - M\ :sub:`11` + - x + - M\ :sub:`21` + - x + - M\ :sub:`31` + - x + +.. _v4l2-meta-fmt-generic-csi2-20: + +V4L2_META_FMT_GENERIC_CSI2_20 +----------------------------- + +V4L2_META_FMT_GENERIC_CSI2_20 contains 8-bit generic metadata packed in 20-bit +Data Units, with alternating one or two padding bytes after every byte of +metadata. This format is typically used by CSI-2 receivers with a source that +transmits MEDIA_BUS_FMT_META_20 and the CSI-2 receiver writes the received data +to memory as-is. + +The packing of the data follows the MIPI CSI-2 specification and the padding of +the data is defined in the MIPI CCS specification. + +Some devices support more efficient packing of metadata in conjunction with +16-bit image data. In that case the dataformat is +:ref:`V4L2_META_FMT_GENERIC_CSI2_10 <v4l2-meta-fmt-generic-csi2-10>`. + +This format is little endian. + +**Byte Order Of V4L2_META_FMT_GENERIC_CSI2_20.** +Each cell is one byte. "M" denotes a byte of metadata and "x" a byte of padding. + +.. tabularcolumns:: |p{2.4cm}|p{1.2cm}|p{.8cm}|p{1.2cm}|p{.8cm}|p{.8cm}|p{1.2cm}|p{.8cm}|p{1.2cm}|p{.8cm}|p{.8cm}| + +.. flat-table:: Sample 4x2 Metadata Frame + :header-rows: 0 + :stub-columns: 0 + :widths: 12 8 8 8 8 8 8 8 8 8 8 + + * - start + 0: + - M\ :sub:`00` + - x + - M\ :sub:`10` + - x + - x + - M\ :sub:`20` + - x + - M\ :sub:`30` + - x + - x + * - start + 10: + - M\ :sub:`01` + - x + - M\ :sub:`11` + - x + - x + - M\ :sub:`21` + - x + - M\ :sub:`31` + - x + - x + +.. _v4l2-meta-fmt-generic-csi2-24: + +V4L2_META_FMT_GENERIC_CSI2_24 +----------------------------- + +V4L2_META_FMT_GENERIC_CSI2_24 contains 8-bit generic metadata packed in 24-bit +Data Units, with two padding bytes after every byte of metadata. This format is +typically used by CSI-2 receivers with a source that transmits +MEDIA_BUS_FMT_META_24 and the CSI-2 receiver writes the received data to memory +as-is. + +The packing of the data follows the MIPI CSI-2 specification and the padding of +the data is defined in the MIPI CCS specification. + +Some devices support more efficient packing of metadata in conjunction with +16-bit image data. In that case the dataformat is +:ref:`V4L2_META_FMT_GENERIC_CSI2_12 <v4l2-meta-fmt-generic-csi2-12>`. + +This format is little endian. + +**Byte Order Of V4L2_META_FMT_GENERIC_CSI2_24.** +Each cell is one byte. "M" denotes a byte of metadata and "x" a byte of padding. + +.. tabularcolumns:: |p{2.4cm}|p{1.2cm}|p{.8cm}|p{.8cm}|p{1.2cm}|p{.8cm}|p{.8cm}|p{1.2cm}|p{.8cm}|p{.8cm}|p{1.2cm}|p{.8cm}|p{.8cm}| + +.. flat-table:: Sample 4x2 Metadata Frame + :header-rows: 0 + :stub-columns: 0 + :widths: 12 8 8 8 8 8 8 8 8 8 8 8 8 + + * - start + 0: + - M\ :sub:`00` + - x + - x + - M\ :sub:`10` + - x + - x + - M\ :sub:`20` + - x + - x + - M\ :sub:`30` + - x + - x + * - start + 12: + - M\ :sub:`01` + - x + - x + - M\ :sub:`11` + - x + - x + - M\ :sub:`21` + - x + - x + - M\ :sub:`31` + - x + - x diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-intel-ipu3.rst b/Documentation/userspace-api/media/v4l/metafmt-intel-ipu3.rst index 97a9a2925671..84d81dd7a7b5 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-meta-intel-ipu3.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-intel-ipu3.rst @@ -1,27 +1,4 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file is free software; you can redistribute it and/or -.. modify it under the terms of the GNU General Public License version -.. 2.0 as published by the Free Software Foundation. -.. -.. This file is distributed in the hope that it will be useful, -.. but WITHOUT ANY WARRANTY; without even the implied warranty of -.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.. GNU General Public License version 2.0 for more details. -.. -.. Or, alternatively, -.. -.. b) Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _v4l2-meta-fmt-params: .. _v4l2-meta-fmt-stat-3a: @@ -101,4 +78,4 @@ hardware and algorithm details. Intel IPU3 ImgU uAPI data types =============================== -.. kernel-doc:: drivers/staging/media/ipu3/include/intel-ipu3.h +.. kernel-doc:: drivers/staging/media/ipu3/include/uapi/intel-ipu3.h diff --git a/Documentation/userspace-api/media/v4l/metafmt-pisp-be.rst b/Documentation/userspace-api/media/v4l/metafmt-pisp-be.rst new file mode 100644 index 000000000000..3281fe366c86 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/metafmt-pisp-be.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _v4l2-meta-fmt-rpi-be-cfg: + +************************ +V4L2_META_FMT_RPI_BE_CFG +************************ + +Raspberry Pi PiSP Back End configuration format +=============================================== + +The Raspberry Pi PiSP Back End memory-to-memory image signal processor is +configured by userspace by providing a buffer of configuration parameters +to the `pispbe-config` output video device node using the +:c:type:`v4l2_meta_format` interface. + +The PiSP Back End processes images in tiles, and its configuration requires +specifying two different sets of parameters by populating the members of +:c:type:`pisp_be_tiles_config` defined in the ``pisp_be_config.h`` header file. + +The `Raspberry Pi PiSP technical specification +<https://datasheets.raspberrypi.com/camera/raspberry-pi-image-signal-processor-specification.pdf>`_ +provide detailed description of the ISP back end configuration and programming +model. + +Global configuration data +------------------------- + +The global configuration data describe how the pixels in a particular image are +to be processed and is therefore shared across all the tiles of the image. So +for example, LSC (Lens Shading Correction) or Denoise parameters would be common +across all tiles from the same frame. + +Global configuration data are passed to the ISP by populating the member of +:c:type:`pisp_be_config`. + +Tile parameters +--------------- + +As the ISP processes images in tiles, each set of tiles parameters describe how +a single tile in an image is going to be processed. A single set of tile +parameters consist of 160 bytes of data and to process a batch of tiles several +sets of tiles parameters are required. + +Tiles parameters are passed to the ISP by populating the member of +``pisp_tile`` and the ``num_tiles`` fields of :c:type:`pisp_be_tiles_config`. + +Raspberry Pi PiSP Back End uAPI data types +========================================== + +This section describes the data types exposed to userspace by the Raspberry Pi +PiSP Back End. The section is informative only, for a detailed description of +each field refer to the `Raspberry Pi PiSP technical specification +<https://datasheets.raspberrypi.com/camera/raspberry-pi-image-signal-processor-specification.pdf>`_. + +.. kernel-doc:: include/uapi/linux/media/raspberrypi/pisp_be_config.h diff --git a/Documentation/userspace-api/media/v4l/metafmt-pisp-fe.rst b/Documentation/userspace-api/media/v4l/metafmt-pisp-fe.rst new file mode 100644 index 000000000000..fddeada83e4a --- /dev/null +++ b/Documentation/userspace-api/media/v4l/metafmt-pisp-fe.rst @@ -0,0 +1,39 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _v4l2-meta-fmt-rpi-fe-cfg: + +************************ +V4L2_META_FMT_RPI_FE_CFG +************************ + +Raspberry Pi PiSP Front End configuration format +================================================ + +The Raspberry Pi PiSP Front End image signal processor is configured by +userspace by providing a buffer of configuration parameters to the +`rp1-cfe-fe-config` output video device node using the +:c:type:`v4l2_meta_format` interface. + +The `Raspberry Pi PiSP technical specification +<https://datasheets.raspberrypi.com/camera/raspberry-pi-image-signal-processor-specification.pdf>`_ +provide detailed description of the Front End configuration and programming +model. + +.. _v4l2-meta-fmt-rpi-fe-stats: + +************************** +V4L2_META_FMT_RPI_FE_STATS +************************** + +Raspberry Pi PiSP Front End statistics format +============================================= + +The Raspberry Pi PiSP Front End image signal processor provides statistics data +by writing to a buffer provided via the `rp1-cfe-fe-stats` capture video device +node using the +:c:type:`v4l2_meta_format` interface. + +The `Raspberry Pi PiSP technical specification +<https://datasheets.raspberrypi.com/camera/raspberry-pi-image-signal-processor-specification.pdf>`_ +provide detailed description of the Front End configuration and programming +model. diff --git a/Documentation/userspace-api/media/v4l/metafmt-rkisp1.rst b/Documentation/userspace-api/media/v4l/metafmt-rkisp1.rst new file mode 100644 index 000000000000..959f6bde8695 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/metafmt-rkisp1.rst @@ -0,0 +1,89 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _v4l2-meta-fmt-rk-isp1-stat-3a: + +************************************************************************************************************************ +V4L2_META_FMT_RK_ISP1_PARAMS ('rk1p'), V4L2_META_FMT_RK_ISP1_STAT_3A ('rk1s'), V4L2_META_FMT_RK_ISP1_EXT_PARAMS ('rk1e') +************************************************************************************************************************ + +======================== +Configuration parameters +======================== + +The configuration of the RkISP1 ISP is performed by userspace by providing +parameters for the ISP to the driver using the :c:type:`v4l2_meta_format` +interface. + +There are two methods that allow to configure the ISP, the `fixed parameters` +configuration format and the `extensible parameters` configuration +format. + +.. _v4l2-meta-fmt-rk-isp1-params: + +Fixed parameters configuration format +===================================== + +When using the fixed configuration format, parameters are passed to the +:ref:`rkisp1_params <rkisp1_params>` metadata output video node, using +the `V4L2_META_FMT_RK_ISP1_PARAMS` meta format. + +The buffer contains a single instance of the C structure +:c:type:`rkisp1_params_cfg` defined in ``rkisp1-config.h``. So the structure can +be obtained from the buffer by: + +.. code-block:: c + + struct rkisp1_params_cfg *params = (struct rkisp1_params_cfg*) buffer; + +This method supports a subset of the ISP features only, new applications should +use the extensible parameters method. + +.. _v4l2-meta-fmt-rk-isp1-ext-params: + +Extensible parameters configuration format +========================================== + +When using the extensible configuration format, parameters are passed to the +:ref:`rkisp1_params <rkisp1_params>` metadata output video node, using +the `V4L2_META_FMT_RK_ISP1_EXT_PARAMS` meta format. + +The buffer contains a single instance of the C structure +:c:type:`rkisp1_ext_params_cfg` defined in ``rkisp1-config.h``. The +:c:type:`rkisp1_ext_params_cfg` structure is designed to allow userspace to +populate the data buffer with only the configuration data for the ISP blocks it +intends to configure. The extensible parameters format design allows developers +to define new block types to support new configuration parameters, and defines a +versioning scheme so that it can be extended and versioned without breaking +compatibility with existing applications. + +For these reasons, this configuration method is preferred over the `fixed +parameters` format alternative. + +.. rkisp1_stat_buffer + +=========================== +3A and histogram statistics +=========================== + +The ISP1 device collects different statistics over an input Bayer frame. +Those statistics are obtained from the :ref:`rkisp1_stats <rkisp1_stats>` +metadata capture video node, +using the :c:type:`v4l2_meta_format` interface. The buffer contains a single +instance of the C structure :c:type:`rkisp1_stat_buffer` defined in +``rkisp1-config.h``. So the structure can be obtained from the buffer by: + +.. code-block:: c + + struct rkisp1_stat_buffer *stats = (struct rkisp1_stat_buffer*) buffer; + +The statistics collected are Exposure, AWB (Auto-white balance), Histogram and +AF (Auto-focus). See :c:type:`rkisp1_stat_buffer` for details of the statistics. + +The 3A statistics and configuration parameters described here are usually +consumed and produced by dedicated user space libraries that comprise the +important tuning tools using software control loop. + +rkisp1 uAPI data types +====================== + +.. kernel-doc:: include/uapi/linux/rkisp1-config.h diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-uvc.rst b/Documentation/userspace-api/media/v4l/metafmt-uvc.rst index debc50285a25..784346d14bbd 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-meta-uvc.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-uvc.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2-meta-fmt-uvc: diff --git a/Documentation/userspace-api/media/v4l/metafmt-vivid.rst b/Documentation/userspace-api/media/v4l/metafmt-vivid.rst new file mode 100644 index 000000000000..7173e2c3e245 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/metafmt-vivid.rst @@ -0,0 +1,36 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later + +.. _v4l2-meta-fmt-vivid: + +******************************* +V4L2_META_FMT_VIVID ('VIVD') +******************************* + +VIVID Metadata Format + + +Description +=========== + +This describes metadata format used by the vivid driver. + +It sets Brightness, Saturation, Contrast and Hue, each of which maps to +corresponding controls of the vivid driver with respect to the range and default values. + +It contains the following fields: + +.. flat-table:: VIVID Metadata + :widths: 1 4 + :header-rows: 1 + :stub-columns: 0 + + * - Field + - Description + * - u16 brightness; + - Image brightness, the value is in the range 0 to 255, with the default value as 128. + * - u16 contrast; + - Image contrast, the value is in the range 0 to 255, with the default value as 128. + * - u16 saturation; + - Image color saturation, the value is in the range 0 to 255, with the default value as 128. + * - s16 hue; + - Image color balance, the value is in the range -128 to 128, with the default value as 0. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-vsp1-hgo.rst b/Documentation/userspace-api/media/v4l/metafmt-vsp1-hgo.rst index b780e447dd4b..8d886feb180c 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-meta-vsp1-hgo.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-vsp1-hgo.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2-meta-fmt-vsp1-hgo: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-vsp1-hgt.rst b/Documentation/userspace-api/media/v4l/metafmt-vsp1-hgt.rst index e165320cc1ff..d8830ff605de 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-meta-vsp1-hgt.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-vsp1-hgt.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2-meta-fmt-vsp1-hgt: diff --git a/Documentation/userspace-api/media/v4l/mmap.rst b/Documentation/userspace-api/media/v4l/mmap.rst index 9c44d05ebc3f..1a48c3cbda17 100644 --- a/Documentation/userspace-api/media/v4l/mmap.rst +++ b/Documentation/userspace-api/media/v4l/mmap.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _mmap: @@ -42,22 +36,22 @@ This ioctl can also be used to change the number of buffers or to free the allocated memory, provided none of the buffers are still mapped. Before applications can access the buffers they must map them into their -address space with the :ref:`mmap() <func-mmap>` function. The +address space with the :c:func:`mmap()` function. The location of the buffers in device memory can be determined with the :ref:`VIDIOC_QUERYBUF` ioctl. In the single-planar API case, the ``m.offset`` and ``length`` returned in a struct :c:type:`v4l2_buffer` are passed as sixth and second -parameter to the :ref:`mmap() <func-mmap>` function. When using the +parameter to the :c:func:`mmap()` function. When using the multi-planar API, struct :c:type:`v4l2_buffer` contains an array of struct :c:type:`v4l2_plane` structures, each containing its own ``m.offset`` and ``length``. When using the multi-planar API, every plane of every buffer has to be mapped -separately, so the number of calls to :ref:`mmap() <func-mmap>` should +separately, so the number of calls to :c:func:`mmap()` should be equal to number of buffers times number of planes in each buffer. The offset and length values must not be modified. Remember, the buffers are allocated in physical memory, as opposed to virtual memory, which can be swapped out to disk. Applications should free the buffers as soon as -possible with the :ref:`munmap() <func-munmap>` function. +possible with the :c:func:`munmap()` function. Example: Mapping buffers in the single-planar API ================================================= @@ -129,7 +123,6 @@ Example: Mapping buffers in the single-planar API for (i = 0; i < reqbuf.count; i++) munmap(buffers[i].start, buffers[i].length); - Example: Mapping buffers in the multi-planar API ================================================ @@ -195,7 +188,7 @@ Example: Mapping buffers in the multi-planar API buffers[i].start[j] = mmap(NULL, buffer.m.planes[j].length, PROT_READ | PROT_WRITE, /* recommended */ MAP_SHARED, /* recommended */ - fd, buffer.m.planes[j].m.offset); + fd, buffer.m.planes[j].m.mem_offset); if (MAP_FAILED == buffers[i].start[j]) { /* If you do not exit here you should unmap() and free() @@ -239,16 +232,16 @@ In the write loop, when the application runs out of free buffers, it must wait until an empty buffer can be dequeued and reused. To enqueue and dequeue a buffer applications use the -:ref:`VIVIOC_QBUF <VIDIOC_QBUF>` and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` +:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The status of a buffer being mapped, enqueued, full or empty can be determined at any time using the :ref:`VIDIOC_QUERYBUF` ioctl. Two methods exist to suspend execution of the application until one or more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the ``O_NONBLOCK`` -flag was given to the :ref:`open() <func-open>` function, +flag was given to the :c:func:`open()` function, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN`` -error code when no buffer is available. The :ref:`select() <func-select>` -or :ref:`poll() <func-poll>` functions are always available. +error code when no buffer is available. The :c:func:`select()` +or :c:func:`poll()` functions are always available. To start and stop capturing or output applications call the :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF @@ -266,15 +259,15 @@ Drivers implementing memory mapping I/O must support the <VIDIOC_QUERYBUF>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the :ref:`mmap() -<func-mmap>`, :ref:`munmap() <func-munmap>`, :ref:`select() -<func-select>` and :ref:`poll() <func-poll>` function. [#f3]_ +<func-mmap>`, :c:func:`munmap()`, :ref:`select() +<func-select>` and :c:func:`poll()` function. [#f3]_ [capture example] .. [#f1] One could use one file descriptor and set the buffer type field accordingly when calling :ref:`VIDIOC_QBUF` etc., - but it makes the :ref:`select() <func-select>` function ambiguous. We also + but it makes the :c:func:`select()` function ambiguous. We also like the clean approach of one file descriptor per logical stream. Video overlay for example is also a logical stream, although the CPU is not needed for continuous operation. @@ -287,6 +280,6 @@ and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the :ref:`mmap() scatter-gather lists and the like. .. [#f3] - At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are - the same, and :ref:`select() <func-select>` is too important to be optional. + At the driver level :c:func:`select()` and :c:func:`poll()` are + the same, and :c:func:`select()` is too important to be optional. The rest should be evident. diff --git a/Documentation/userspace-api/media/v4l/mt2110t.svg b/Documentation/userspace-api/media/v4l/mt2110t.svg new file mode 100644 index 000000000000..a6e82f2c73df --- /dev/null +++ b/Documentation/userspace-api/media/v4l/mt2110t.svg @@ -0,0 +1,315 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later --> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<svg version="1.2" width="140mm" height="220mm" viewBox="0 0 14000 22000" preserveAspectRatio="xMidYMid" fill-rule="evenodd" stroke-width="28.222" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg" xmlns:ooo="http://xml.openoffice.org/svg/export" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:presentation="http://sun.com/xmlns/staroffice/presentation" xmlns:smil="http://www.w3.org/2001/SMIL20/" xmlns:anim="urn:oasis:names:tc:opendocument:xmlns:animation:1.0" xmlns:svg="urn:oasis:names:tc:opendocument:xmlns:svg-compatible:1.0" xml:space="preserve"> + <defs class="ClipPathGroup"> + <clipPath id="presentation_clip_path" clipPathUnits="userSpaceOnUse"> + <rect x="0" y="0" width="14000" height="22000"/> + </clipPath> + <clipPath id="presentation_clip_path_shrink" clipPathUnits="userSpaceOnUse"> + <rect x="14" y="22" width="13972" height="21956"/> + </clipPath> + </defs> + <defs> + <font id="EmbeddedFont_1" horiz-adv-x="2048"> + <font-face font-family="Liberation Sans embedded" units-per-em="2048" font-weight="normal" font-style="normal" ascent="1852" descent="423"/> + <missing-glyph horiz-adv-x="2048" d="M 0,0 L 2047,0 2047,2047 0,2047 0,0 Z"/> + <glyph unicode="y" horiz-adv-x="1033" d="M 191,-425 C 142,-425 100,-421 67,-414 L 67,-279 C 92,-283 120,-285 151,-285 263,-285 352,-203 417,-38 L 434,5 5,1082 197,1082 425,484 C 428,475 432,464 437,451 442,438 457,394 482,320 507,246 521,205 523,196 L 593,393 830,1082 1020,1082 604,0 C 559,-115 518,-201 479,-258 440,-314 398,-356 351,-384 304,-411 250,-425 191,-425 Z"/> + <glyph unicode="x" horiz-adv-x="1006" d="M 801,0 L 510,444 217,0 23,0 408,556 41,1082 240,1082 510,661 778,1082 979,1082 612,558 1002,0 801,0 Z"/> + <glyph unicode="w" horiz-adv-x="1509" d="M 1174,0 L 965,0 776,765 740,934 C 734,904 725,861 712,805 699,748 631,480 508,0 L 300,0 -3,1082 175,1082 358,347 C 363,331 377,265 401,149 L 418,223 644,1082 837,1082 1026,339 1072,149 1103,288 1308,1082 1484,1082 1174,0 Z"/> + <glyph unicode="u" horiz-adv-x="874" d="M 314,1082 L 314,396 C 314,325 321,269 335,230 349,191 371,162 402,145 433,128 478,119 537,119 624,119 692,149 742,208 792,267 817,350 817,455 L 817,1082 997,1082 997,231 C 997,105 999,28 1003,0 L 833,0 C 832,3 832,12 831,27 830,42 830,59 829,78 828,97 826,132 825,185 L 822,185 C 781,110 733,58 679,27 624,-4 557,-20 476,-20 357,-20 271,10 216,69 161,128 133,225 133,361 L 133,1082 314,1082 Z"/> + <glyph unicode="t" horiz-adv-x="531" d="M 554,8 C 495,-8 434,-16 372,-16 228,-16 156,66 156,229 L 156,951 31,951 31,1082 163,1082 216,1324 336,1324 336,1082 536,1082 536,951 336,951 336,268 C 336,216 345,180 362,159 379,138 408,127 450,127 474,127 509,132 554,141 L 554,8 Z"/> + <glyph unicode="s" horiz-adv-x="901" d="M 950,299 C 950,197 912,118 835,63 758,8 650,-20 511,-20 376,-20 273,2 200,47 127,91 79,160 57,254 L 216,285 C 231,227 263,185 311,158 359,131 426,117 511,117 602,117 669,131 712,159 754,187 775,229 775,285 775,328 760,362 731,389 702,416 654,438 589,455 L 460,489 C 357,516 283,542 240,568 196,593 162,624 137,661 112,698 100,743 100,796 100,895 135,970 206,1022 276,1073 378,1099 513,1099 632,1099 727,1078 798,1036 868,994 912,927 931,834 L 769,814 C 759,862 732,899 689,925 645,950 586,963 513,963 432,963 372,951 333,926 294,901 275,864 275,814 275,783 283,758 299,738 315,718 339,701 370,687 401,673 467,654 568,629 663,605 732,583 774,563 816,542 849,520 874,495 898,470 917,442 930,410 943,377 950,340 950,299 Z"/> + <glyph unicode="r" horiz-adv-x="530" d="M 142,0 L 142,830 C 142,906 140,990 136,1082 L 306,1082 C 311,959 314,886 314,861 L 318,861 C 347,954 380,1017 417,1051 454,1085 507,1102 575,1102 599,1102 623,1099 648,1092 L 648,927 C 624,934 592,937 552,937 477,937 420,905 381,841 342,776 322,684 322,564 L 322,0 142,0 Z"/> + <glyph unicode="p" horiz-adv-x="953" d="M 1053,546 C 1053,169 920,-20 655,-20 488,-20 376,43 319,168 L 314,168 C 317,163 318,106 318,-2 L 318,-425 138,-425 138,861 C 138,972 136,1046 132,1082 L 306,1082 C 307,1079 308,1070 309,1054 310,1037 312,1012 314,978 315,944 316,921 316,908 L 320,908 C 352,975 394,1024 447,1055 500,1086 569,1101 655,1101 788,1101 888,1056 954,967 1020,878 1053,737 1053,546 Z M 864,542 C 864,693 844,800 803,865 762,930 698,962 609,962 538,962 482,947 442,917 401,887 371,840 350,777 329,713 318,630 318,528 318,386 341,281 386,214 431,147 505,113 607,113 696,113 762,146 803,212 844,277 864,387 864,542 Z"/> + <glyph unicode="o" horiz-adv-x="980" d="M 1053,542 C 1053,353 1011,212 928,119 845,26 724,-20 565,-20 407,-20 288,28 207,125 126,221 86,360 86,542 86,915 248,1102 571,1102 736,1102 858,1057 936,966 1014,875 1053,733 1053,542 Z M 864,542 C 864,691 842,800 798,868 753,935 679,969 574,969 469,969 393,935 346,866 299,797 275,689 275,542 275,399 298,292 345,221 391,149 464,113 563,113 671,113 748,148 795,217 841,286 864,395 864,542 Z"/> + <glyph unicode="l" horiz-adv-x="187" d="M 138,0 L 138,1484 318,1484 318,0 138,0 Z"/> + <glyph unicode="i" horiz-adv-x="187" d="M 137,1312 L 137,1484 317,1484 317,1312 137,1312 Z M 137,0 L 137,1082 317,1082 317,0 137,0 Z"/> + <glyph unicode="f" horiz-adv-x="557" d="M 361,951 L 361,0 181,0 181,951 29,951 29,1082 181,1082 181,1204 C 181,1303 203,1374 246,1417 289,1460 356,1482 445,1482 495,1482 537,1478 572,1470 L 572,1333 C 542,1338 515,1341 492,1341 446,1341 413,1329 392,1306 371,1283 361,1240 361,1179 L 361,1082 572,1082 572,951 361,951 Z"/> + <glyph unicode="e" horiz-adv-x="980" d="M 276,503 C 276,379 302,283 353,216 404,149 479,115 578,115 656,115 719,131 766,162 813,193 844,233 861,281 L 1019,236 C 954,65 807,-20 578,-20 418,-20 296,28 213,123 129,218 87,360 87,548 87,727 129,864 213,959 296,1054 416,1102 571,1102 889,1102 1048,910 1048,527 L 1048,503 276,503 Z M 862,641 C 852,755 823,838 775,891 727,943 658,969 568,969 481,969 412,940 361,882 310,823 282,743 278,641 L 862,641 Z"/> + <glyph unicode="b" horiz-adv-x="953" d="M 1053,546 C 1053,169 920,-20 655,-20 573,-20 505,-5 451,25 396,54 352,102 318,168 L 316,168 C 316,147 315,116 312,74 309,31 307,7 306,0 L 132,0 C 136,36 138,110 138,223 L 138,1484 318,1484 318,1061 C 318,1018 317,967 314,908 L 318,908 C 351,977 396,1027 451,1057 506,1087 574,1102 655,1102 792,1102 892,1056 957,964 1021,872 1053,733 1053,546 Z M 864,540 C 864,691 844,800 804,865 764,930 699,963 609,963 508,963 434,928 388,859 341,790 318,680 318,529 318,387 341,282 386,215 431,147 505,113 607,113 698,113 763,147 804,214 844,281 864,389 864,540 Z"/> + <glyph unicode="8" horiz-adv-x="980" d="M 1050,393 C 1050,263 1009,162 926,89 843,16 725,-20 570,-20 419,-20 302,16 217,87 132,158 89,260 89,391 89,483 115,560 168,623 221,686 288,724 370,737 L 370,741 C 293,759 233,798 189,858 144,918 122,988 122,1069 122,1176 162,1263 243,1330 323,1397 431,1430 566,1430 705,1430 814,1397 895,1332 975,1267 1015,1178 1015,1067 1015,986 993,916 948,856 903,796 842,758 765,743 L 765,739 C 855,724 925,686 975,625 1025,563 1050,486 1050,393 Z M 828,1057 C 828,1216 741,1296 566,1296 481,1296 417,1276 373,1236 328,1196 306,1136 306,1057 306,976 329,915 375,873 420,830 485,809 568,809 653,809 717,829 762,868 806,907 828,970 828,1057 Z M 863,410 C 863,497 837,563 785,608 733,652 660,674 566,674 475,674 403,650 352,603 301,555 275,489 275,406 275,212 374,115 572,115 670,115 743,139 791,186 839,233 863,307 863,410 Z"/> + <glyph unicode="6" horiz-adv-x="980" d="M 1049,461 C 1049,312 1009,195 928,109 847,23 736,-20 594,-20 435,-20 314,39 230,157 146,275 104,447 104,672 104,916 148,1103 235,1234 322,1365 447,1430 608,1430 821,1430 955,1334 1010,1143 L 838,1112 C 803,1227 725,1284 606,1284 503,1284 424,1236 368,1141 311,1045 283,906 283,725 316,786 362,832 421,864 480,895 548,911 625,911 755,911 858,870 935,789 1011,708 1049,598 1049,461 Z M 866,453 C 866,555 841,634 791,689 741,744 671,772 582,772 498,772 430,748 379,699 327,650 301,582 301,496 301,387 328,298 382,229 435,160 504,125 588,125 675,125 743,154 792,213 841,271 866,351 866,453 Z"/> + <glyph unicode="4" horiz-adv-x="1060" d="M 881,319 L 881,0 711,0 711,319 47,319 47,459 692,1409 881,1409 881,461 1079,461 1079,319 881,319 Z M 711,1206 C 710,1202 700,1184 683,1153 666,1122 653,1100 644,1087 L 283,555 229,481 213,461 711,461 711,1206 Z"/> + <glyph unicode="3" horiz-adv-x="1006" d="M 1049,389 C 1049,259 1008,158 925,87 842,16 724,-20 571,-20 428,-20 315,12 230,77 145,141 94,236 78,362 L 264,379 C 288,212 390,129 571,129 662,129 733,151 785,196 836,241 862,307 862,395 862,472 833,532 774,575 715,618 629,639 518,639 L 416,639 416,795 514,795 C 613,795 689,817 744,860 798,903 825,962 825,1038 825,1113 803,1173 759,1217 714,1260 648,1282 561,1282 482,1282 418,1262 369,1221 320,1180 291,1123 283,1049 L 102,1063 C 115,1178 163,1268 246,1333 328,1398 434,1430 563,1430 704,1430 814,1397 893,1332 971,1266 1010,1174 1010,1057 1010,967 985,894 935,838 884,781 811,743 715,723 L 715,719 C 820,708 902,672 961,613 1020,554 1049,479 1049,389 Z"/> + <glyph unicode="2" horiz-adv-x="954" d="M 103,0 L 103,127 C 137,205 179,274 228,334 277,393 328,447 382,496 436,544 490,589 543,630 596,671 643,713 686,754 729,795 763,839 790,884 816,929 829,981 829,1038 829,1115 806,1175 761,1218 716,1261 653,1282 572,1282 495,1282 432,1261 383,1220 333,1178 304,1119 295,1044 L 111,1061 C 124,1174 172,1263 255,1330 337,1397 443,1430 572,1430 714,1430 823,1397 900,1330 976,1263 1014,1167 1014,1044 1014,989 1002,935 977,881 952,827 914,773 865,719 816,665 721,581 582,468 505,405 444,349 399,299 354,248 321,200 301,153 L 1036,153 1036,0 103,0 Z"/> + <glyph unicode="1" horiz-adv-x="927" d="M 156,0 L 156,153 515,153 515,1237 197,1010 197,1180 530,1409 696,1409 696,153 1039,153 1039,0 156,0 Z"/> + <glyph unicode=" " horiz-adv-x="556"/> + </font> + </defs> + <defs class="TextShapeIndex"> + <g ooo:slide="id1" ooo:id-list="id3 id4 id5 id6 id7 id8 id9 id10 id11 id12 id13 id14 id15 id16 id17 id18 id19 id20 id21 id22 id23 id24 id25 id26 id27 id28 id29 id30"/> + </defs> + <defs class="EmbeddedBulletChars"> + <g id="bullet-char-template-57356" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 580,1141 L 1163,571 580,0 -4,571 580,1141 Z"/> + </g> + <g id="bullet-char-template-57354" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 8,1128 L 1137,1128 1137,0 8,0 8,1128 Z"/> + </g> + <g id="bullet-char-template-10146" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 174,0 L 602,739 174,1481 1456,739 174,0 Z M 1358,739 L 309,1346 659,739 1358,739 Z"/> + </g> + <g id="bullet-char-template-10132" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 2015,739 L 1276,0 717,0 1260,543 174,543 174,936 1260,936 717,1481 1274,1481 2015,739 Z"/> + </g> + <g id="bullet-char-template-10007" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 0,-2 C -7,14 -16,27 -25,37 L 356,567 C 262,823 215,952 215,954 215,979 228,992 255,992 264,992 276,990 289,987 310,991 331,999 354,1012 L 381,999 492,748 772,1049 836,1024 860,1049 C 881,1039 901,1025 922,1006 886,937 835,863 770,784 769,783 710,716 594,584 L 774,223 C 774,196 753,168 711,139 L 727,119 C 717,90 699,76 672,76 641,76 570,178 457,381 L 164,-76 C 142,-110 111,-127 72,-127 30,-127 9,-110 8,-76 1,-67 -2,-52 -2,-32 -2,-23 -1,-13 0,-2 Z"/> + </g> + <g id="bullet-char-template-10004" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 285,-33 C 182,-33 111,30 74,156 52,228 41,333 41,471 41,549 55,616 82,672 116,743 169,778 240,778 293,778 328,747 346,684 L 369,508 C 377,444 397,411 428,410 L 1163,1116 C 1174,1127 1196,1133 1229,1133 1271,1133 1292,1118 1292,1087 L 1292,965 C 1292,929 1282,901 1262,881 L 442,47 C 390,-6 338,-33 285,-33 Z"/> + </g> + <g id="bullet-char-template-9679" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 813,0 C 632,0 489,54 383,161 276,268 223,411 223,592 223,773 276,916 383,1023 489,1130 632,1184 813,1184 992,1184 1136,1130 1245,1023 1353,916 1407,772 1407,592 1407,412 1353,268 1245,161 1136,54 992,0 813,0 Z"/> + </g> + <g id="bullet-char-template-8226" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 346,457 C 273,457 209,483 155,535 101,586 74,649 74,723 74,796 101,859 155,911 209,963 273,989 346,989 419,989 480,963 531,910 582,859 608,796 608,723 608,648 583,586 532,535 482,483 420,457 346,457 Z"/> + </g> + <g id="bullet-char-template-8211" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M -4,459 L 1135,459 1135,606 -4,606 -4,459 Z"/> + </g> + <g id="bullet-char-template-61548" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 173,740 C 173,903 231,1043 346,1159 462,1274 601,1332 765,1332 928,1332 1067,1274 1183,1159 1299,1043 1357,903 1357,740 1357,577 1299,437 1183,322 1067,206 928,148 765,148 601,148 462,206 346,322 231,437 173,577 173,740 Z"/> + </g> + </defs> + <g> + <g id="id2" class="Master_Slide"> + <g id="bg-id2" class="Background"/> + <g id="bo-id2" class="BackgroundObjects"/> + </g> + </g> + <g class="SlideGroup"> + <g> + <g id="container-id1"> + <g id="id1" class="Slide" clip-path="url(#presentation_clip_path)"> + <g class="Page"> + <g class="com.sun.star.drawing.MeasureShape"> + <g id="id3"> + <rect class="BoundingBox" stroke="none" fill="none" x="1749" y="325" width="10003" height="15477"/> + <path fill="none" stroke="rgb(0,0,0)" d="M 2037,950 L 11463,950"/> + <path fill="rgb(0,0,0)" stroke="none" d="M 1750,950 L 2050,1050 2050,850 1750,950 Z"/> + <path fill="rgb(0,0,0)" stroke="none" d="M 11750,950 L 11450,850 11450,1050 11750,950 Z"/> + <path fill="none" stroke="rgb(0,0,0)" d="M 1750,15800 L 1750,750"/> + <path fill="none" stroke="rgb(0,0,0)" d="M 11750,1650 L 11750,750"/> + <text class="SVGTextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="5953" y="768"><tspan fill="rgb(0,0,0)" stroke="none" style="white-space: pre">16 px</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.MeasureShape"> + <g id="id4"> + <rect class="BoundingBox" stroke="none" fill="none" x="11795" y="1649" width="1853" height="19913"/> + <path fill="none" stroke="rgb(0,0,0)" d="M 13446,1937 L 13446,21273"/> + <path fill="rgb(0,0,0)" stroke="none" d="M 13446,1650 L 13346,1950 13546,1950 13446,1650 Z"/> + <path fill="rgb(0,0,0)" stroke="none" d="M 13446,21560 L 13546,21260 13346,21260 13446,21560 Z"/> + <path fill="none" stroke="rgb(0,0,0)" d="M 11796,1650 L 13646,1650"/> + <path fill="none" stroke="rgb(0,0,0)" d="M 11796,21560 L 13646,21560"/> + <text class="SVGTextShape" transform="rotate(-90 13395 12369)"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="13395" y="12369"><tspan fill="rgb(0,0,0)" stroke="none" style="white-space: pre">32 px</tspan></tspan></tspan></text> + </g> + </g> + <g class="Group"> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id5"> + <rect class="BoundingBox" stroke="none" fill="none" x="1749" y="2449" width="10003" height="1753"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 6750,4200 L 1750,4200 1750,2450 11750,2450 11750,4200 6750,4200 Z"/> + <text class="SVGTextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="3718" y="3545"><tspan fill="rgb(0,0,0)" stroke="none" style="white-space: pre">4 rows of upper 8 bits</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id6"> + <rect class="BoundingBox" stroke="none" fill="none" x="1749" y="1699" width="10003" height="753"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 6750,2450 L 1750,2450 1750,1700 11750,1700 11750,2450 6750,2450 Z"/> + <text class="SVGTextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="3860" y="2295"><tspan fill="rgb(0,0,0)" stroke="none" style="white-space: pre">4 rows of lower 2bits</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id7"> + <rect class="BoundingBox" stroke="none" fill="none" x="1709" y="1609" width="10083" height="2583"/> + <path fill="none" stroke="rgb(52,101,164)" stroke-width="81" stroke-linejoin="round" d="M 6750,4150 L 1750,4150 1750,1650 11750,1650 11750,4150 6750,4150 Z"/> + </g> + </g> + </g> + <g class="com.sun.star.drawing.MeasureShape"> + <g id="id8"> + <rect class="BoundingBox" stroke="none" fill="none" x="385" y="1199" width="1294" height="3971"/> + <path fill="none" stroke="rgb(0,0,0)" d="M 1027,5079 L 1027,2737"/> + <path fill="rgb(0,0,0)" stroke="none" d="M 1027,2450 L 927,2750 1127,2750 1027,2450 Z"/> + <path fill="none" stroke="rgb(0,0,0)" d="M 1027,1413 L 1027,1200"/> + <path fill="rgb(0,0,0)" stroke="none" d="M 1027,1700 L 1127,1400 927,1400 1027,1700 Z"/> + <path fill="none" stroke="rgb(0,0,0)" d="M 1027,2450 L 1027,1700"/> + <path fill="none" stroke="rgb(0,0,0)" d="M 1677,2450 L 827,2450"/> + <path fill="none" stroke="rgb(0,0,0)" d="M 1677,1700 L 827,1700"/> + <text class="SVGTextShape" transform="rotate(-90 845 5217)"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="845" y="5217"><tspan fill="rgb(0,0,0)" stroke="none" style="white-space: pre">16 bytes</tspan></tspan></tspan></text> + </g> + </g> + <g class="Group"> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id9"> + <rect class="BoundingBox" stroke="none" fill="none" x="1749" y="4929" width="10003" height="1753"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 6750,6680 L 1750,6680 1750,4930 11750,4930 11750,6680 6750,6680 Z"/> + <text class="SVGTextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="3718" y="6025"><tspan fill="rgb(0,0,0)" stroke="none" style="white-space: pre">4 rows of upper 8 bits</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id10"> + <rect class="BoundingBox" stroke="none" fill="none" x="1749" y="4179" width="10003" height="753"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 6750,4930 L 1750,4930 1750,4180 11750,4180 11750,4930 6750,4930 Z"/> + <text class="SVGTextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="3771" y="4775"><tspan fill="rgb(0,0,0)" stroke="none" style="white-space: pre">4 rows of lower 2 bits</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id11"> + <rect class="BoundingBox" stroke="none" fill="none" x="1709" y="4089" width="10083" height="2583"/> + <path fill="none" stroke="rgb(52,101,164)" stroke-width="81" stroke-linejoin="round" d="M 6750,6630 L 1750,6630 1750,4130 11750,4130 11750,6630 6750,6630 Z"/> + </g> + </g> + </g> + <g class="Group"> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id12"> + <rect class="BoundingBox" stroke="none" fill="none" x="1749" y="7409" width="10003" height="1753"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 6750,9160 L 1750,9160 1750,7410 11750,7410 11750,9160 6750,9160 Z"/> + <text class="SVGTextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="3718" y="8505"><tspan fill="rgb(0,0,0)" stroke="none" style="white-space: pre">4 rows of upper 8 bits</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id13"> + <rect class="BoundingBox" stroke="none" fill="none" x="1749" y="6659" width="10003" height="753"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 6750,7410 L 1750,7410 1750,6660 11750,6660 11750,7410 6750,7410 Z"/> + <text class="SVGTextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="3771" y="7255"><tspan fill="rgb(0,0,0)" stroke="none" style="white-space: pre">4 rows of lower 2 bits</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id14"> + <rect class="BoundingBox" stroke="none" fill="none" x="1709" y="6569" width="10083" height="2583"/> + <path fill="none" stroke="rgb(52,101,164)" stroke-width="81" stroke-linejoin="round" d="M 6750,9110 L 1750,9110 1750,6610 11750,6610 11750,9110 6750,9110 Z"/> + </g> + </g> + </g> + <g class="Group"> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id15"> + <rect class="BoundingBox" stroke="none" fill="none" x="1749" y="9889" width="10003" height="1753"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 6750,11640 L 1750,11640 1750,9890 11750,9890 11750,11640 6750,11640 Z"/> + <text class="SVGTextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="3718" y="10985"><tspan fill="rgb(0,0,0)" stroke="none" style="white-space: pre">4 rows of upper 8 bits</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id16"> + <rect class="BoundingBox" stroke="none" fill="none" x="1749" y="9139" width="10003" height="753"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 6750,9890 L 1750,9890 1750,9140 11750,9140 11750,9890 6750,9890 Z"/> + <text class="SVGTextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="3771" y="9735"><tspan fill="rgb(0,0,0)" stroke="none" style="white-space: pre">4 rows of lower 2 bits</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id17"> + <rect class="BoundingBox" stroke="none" fill="none" x="1709" y="9049" width="10083" height="2583"/> + <path fill="none" stroke="rgb(52,101,164)" stroke-width="81" stroke-linejoin="round" d="M 6750,11590 L 1750,11590 1750,9090 11750,9090 11750,11590 6750,11590 Z"/> + </g> + </g> + </g> + <g class="Group"> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id18"> + <rect class="BoundingBox" stroke="none" fill="none" x="1749" y="12369" width="10003" height="1753"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 6750,14120 L 1750,14120 1750,12370 11750,12370 11750,14120 6750,14120 Z"/> + <text class="SVGTextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="3718" y="13465"><tspan fill="rgb(0,0,0)" stroke="none" style="white-space: pre">4 rows of upper 8 bits</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id19"> + <rect class="BoundingBox" stroke="none" fill="none" x="1749" y="11619" width="10003" height="753"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 6750,12370 L 1750,12370 1750,11620 11750,11620 11750,12370 6750,12370 Z"/> + <text class="SVGTextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="3771" y="12215"><tspan fill="rgb(0,0,0)" stroke="none" style="white-space: pre">4 rows of lower 2 bits</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id20"> + <rect class="BoundingBox" stroke="none" fill="none" x="1709" y="11529" width="10083" height="2583"/> + <path fill="none" stroke="rgb(52,101,164)" stroke-width="81" stroke-linejoin="round" d="M 6750,14070 L 1750,14070 1750,11570 11750,11570 11750,14070 6750,14070 Z"/> + </g> + </g> + </g> + <g class="Group"> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id21"> + <rect class="BoundingBox" stroke="none" fill="none" x="1749" y="14849" width="10003" height="1753"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 6750,16600 L 1750,16600 1750,14850 11750,14850 11750,16600 6750,16600 Z"/> + <text class="SVGTextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="3718" y="15945"><tspan fill="rgb(0,0,0)" stroke="none" style="white-space: pre">4 rows of upper 8 bits</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id22"> + <rect class="BoundingBox" stroke="none" fill="none" x="1749" y="14099" width="10003" height="753"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 6750,14850 L 1750,14850 1750,14100 11750,14100 11750,14850 6750,14850 Z"/> + <text class="SVGTextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="3771" y="14695"><tspan fill="rgb(0,0,0)" stroke="none" style="white-space: pre">4 rows of lower 2 bits</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id23"> + <rect class="BoundingBox" stroke="none" fill="none" x="1709" y="14009" width="10083" height="2583"/> + <path fill="none" stroke="rgb(52,101,164)" stroke-width="81" stroke-linejoin="round" d="M 6750,16550 L 1750,16550 1750,14050 11750,14050 11750,16550 6750,16550 Z"/> + </g> + </g> + </g> + <g class="Group"> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id24"> + <rect class="BoundingBox" stroke="none" fill="none" x="1749" y="17329" width="10003" height="1753"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 6750,19080 L 1750,19080 1750,17330 11750,17330 11750,19080 6750,19080 Z"/> + <text class="SVGTextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="3718" y="18425"><tspan fill="rgb(0,0,0)" stroke="none" style="white-space: pre">4 rows of upper 8 bits</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id25"> + <rect class="BoundingBox" stroke="none" fill="none" x="1749" y="16579" width="10003" height="753"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 6750,17330 L 1750,17330 1750,16580 11750,16580 11750,17330 6750,17330 Z"/> + <text class="SVGTextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="3771" y="17175"><tspan fill="rgb(0,0,0)" stroke="none" style="white-space: pre">4 rows of lower 2 bits</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id26"> + <rect class="BoundingBox" stroke="none" fill="none" x="1709" y="16489" width="10083" height="2583"/> + <path fill="none" stroke="rgb(52,101,164)" stroke-width="81" stroke-linejoin="round" d="M 6750,19030 L 1750,19030 1750,16530 11750,16530 11750,19030 6750,19030 Z"/> + </g> + </g> + </g> + <g class="Group"> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id27"> + <rect class="BoundingBox" stroke="none" fill="none" x="1749" y="19809" width="10003" height="1753"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 6750,21560 L 1750,21560 1750,19810 11750,19810 11750,21560 6750,21560 Z"/> + <text class="SVGTextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="3718" y="20905"><tspan fill="rgb(0,0,0)" stroke="none" style="white-space: pre">4 rows of upper 8 bits</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id28"> + <rect class="BoundingBox" stroke="none" fill="none" x="1749" y="19059" width="10003" height="753"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 6750,19810 L 1750,19810 1750,19060 11750,19060 11750,19810 6750,19810 Z"/> + <text class="SVGTextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="3771" y="19655"><tspan fill="rgb(0,0,0)" stroke="none" style="white-space: pre">4 rows of lower 2 bits</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id29"> + <rect class="BoundingBox" stroke="none" fill="none" x="1709" y="18969" width="10083" height="2583"/> + <path fill="none" stroke="rgb(52,101,164)" stroke-width="81" stroke-linejoin="round" d="M 6750,21510 L 1750,21510 1750,19010 11750,19010 11750,21510 6750,21510 Z"/> + </g> + </g> + </g> + <g class="com.sun.star.drawing.MeasureShape"> + <g id="id30"> + <rect class="BoundingBox" stroke="none" fill="none" x="11849" y="1949" width="1237" height="4987"/> + <path fill="none" stroke="rgb(0,0,0)" d="M 12443,6845 L 12443,4487"/> + <path fill="rgb(0,0,0)" stroke="none" d="M 12443,4200 L 12343,4500 12543,4500 12443,4200 Z"/> + <path fill="none" stroke="rgb(0,0,0)" d="M 12443,2163 L 12443,1950"/> + <path fill="rgb(0,0,0)" stroke="none" d="M 12443,2450 L 12543,2150 12343,2150 12443,2450 Z"/> + <path fill="none" stroke="rgb(0,0,0)" d="M 12443,4200 L 12443,2450"/> + <path fill="none" stroke="rgb(0,0,0)" d="M 11850,4200 L 12643,4200"/> + <path fill="none" stroke="rgb(0,0,0)" d="M 11850,2450 L 12643,2450"/> + <text class="SVGTextShape" transform="rotate(-90 12953 6967)"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="12953" y="6967"><tspan fill="rgb(0,0,0)" stroke="none" style="white-space: pre">64 bytes</tspan></tspan></tspan></text> + </g> + </g> + </g> + </g> + </g> + </g> + </g> +</svg> diff --git a/Documentation/userspace-api/media/v4l/nv12mt.svg b/Documentation/userspace-api/media/v4l/nv12mt.svg index d4bb4eb83f6a..30a15b5470be 100644 --- a/Documentation/userspace-api/media/v4l/nv12mt.svg +++ b/Documentation/userspace-api/media/v4l/nv12mt.svg @@ -1,31 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- - This file is dual-licensed: you can use it either under the terms - of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this - dual licensing only applies to this file, and not this project as a - whole. - - a) This file is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License as - published by the Free Software Foundation version 2 of - the License. - - This file is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - Or, alternatively, - - b) Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" diff --git a/Documentation/userspace-api/media/v4l/nv12mt_example.svg b/Documentation/userspace-api/media/v4l/nv12mt_example.svg index e5075af9f45a..d1e2023f4973 100644 --- a/Documentation/userspace-api/media/v4l/nv12mt_example.svg +++ b/Documentation/userspace-api/media/v4l/nv12mt_example.svg @@ -1,31 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- - This file is dual-licensed: you can use it either under the terms - of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this - dual licensing only applies to this file, and not this project as a - whole. - - a) This file is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License as - published by the Free Software Foundation version 2 of - the License. - - This file is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - Or, alternatively, - - b) Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" diff --git a/Documentation/userspace-api/media/v4l/open.rst b/Documentation/userspace-api/media/v4l/open.rst index 38046ef20141..18bfb9b8137d 100644 --- a/Documentation/userspace-api/media/v4l/open.rst +++ b/Documentation/userspace-api/media/v4l/open.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _open: @@ -13,22 +7,105 @@ Opening and Closing Devices *************************** +.. _v4l2_hardware_control: -Device Naming -============= +Controlling a hardware peripheral via V4L2 +========================================== + +Hardware that is supported using the V4L2 uAPI often consists of multiple +devices or peripherals, each of which have their own driver. + +The bridge driver exposes one or more V4L2 device nodes +(see :ref:`v4l2_device_naming`). + +There are other drivers providing support for other components of +the hardware, which may also expose device nodes, called V4L2 sub-devices. + +When such V4L2 sub-devices are exposed, they allow controlling those +other hardware components - usually connected via a serial bus (like +I²C, SMBus or SPI). Depending on the bridge driver, those sub-devices +can be controlled indirectly via the bridge driver or explicitly via +the :ref:`Media Controller <media_controller>` and via the +:ref:`V4L2 sub-devices <subdev>`. + +The devices that require the use of the +:ref:`Media Controller <media_controller>` are called **MC-centric** +devices. The devices that are fully controlled via V4L2 device nodes +are called **video-node-centric**. + +Userspace can check if a V4L2 hardware peripheral is MC-centric by +calling :ref:`VIDIOC_QUERYCAP` and checking the +:ref:`device_caps field <device-capabilities>`. + +If the device returns ``V4L2_CAP_IO_MC`` flag at ``device_caps``, +then it is MC-centric, otherwise, it is video-node-centric. + +It is required for MC-centric drivers to identify the V4L2 +sub-devices and to configure the pipelines via the +:ref:`media controller API <media_controller>` before using the peripheral. +Also, the sub-devices' configuration shall be controlled via the +:ref:`sub-device API <subdev>`. + +.. note:: + + A video-node-centric may still provide media-controller and + sub-device interfaces as well. + + However, in that case the media-controller and the sub-device + interfaces are read-only and just provide information about the + device. The actual configuration is done via the video nodes. + +.. _v4l2_device_naming: + +V4L2 Device Node Naming +======================= V4L2 drivers are implemented as kernel modules, loaded manually by the system administrator or automatically when a device is first discovered. -The driver modules plug into the "videodev" kernel module. It provides +The driver modules plug into the ``videodev`` kernel module. It provides helper functions and a common application interface specified in this document. Each driver thus loaded registers one or more device nodes with major -number 81 and a minor number between 0 and 255. Minor numbers are -allocated dynamically unless the kernel is compiled with the kernel -option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers -are allocated in ranges depending on the device node type (video, radio, -etc.). +number 81. Minor numbers are allocated dynamically unless the kernel +is compiled with the kernel option CONFIG_VIDEO_FIXED_MINOR_RANGES. +In that case minor numbers are allocated in ranges depending on the +device node type. + +The device nodes supported by the Video4Linux subsystem are: + +======================== ==================================================== +Default device node name Usage +======================== ==================================================== +``/dev/videoX`` Video and metadata for capture/output devices +``/dev/vbiX`` Vertical blank data (i.e. closed captions, teletext) +``/dev/radioX`` Radio tuners and modulators +``/dev/swradioX`` Software Defined Radio tuners and modulators +``/dev/v4l-touchX`` Touch sensors +``/dev/v4l-subdevX`` Video sub-devices (used by sensors and other + components of the hardware peripheral)\ [#]_ +======================== ==================================================== + +Where ``X`` is a non-negative integer. + +.. note:: + + 1. The actual device node name is system-dependent, as udev rules may apply. + 2. There is no guarantee that ``X`` will remain the same for the same + device, as the number depends on the device driver's probe order. + If you need an unique name, udev default rules produce + ``/dev/v4l/by-id/`` and ``/dev/v4l/by-path/`` directories containing + links that can be used uniquely to identify a V4L2 device node:: + + $ tree /dev/v4l + /dev/v4l + ├── by-id + │  └── usb-OmniVision._USB_Camera-B4.04.27.1-video-index0 -> ../../video0 + └── by-path + └── pci-0000:00:14.0-usb-0:2:1.0-video-index0 -> ../../video0 + +.. [#] **V4L2 sub-device nodes** (e. g. ``/dev/v4l-subdevX``) use a different + set of system calls, as covered at :ref:`subdev`. Many drivers support "video_nr", "radio_nr" or "vbi_nr" module options to select specific video/radio/vbi node numbers. This allows the @@ -64,7 +141,6 @@ means applications cannot *reliably* scan for loaded or installed drivers. The user must enter a device name, or the application can try the conventional device names. - .. _related: Related Devices @@ -73,7 +149,7 @@ Related Devices Devices can support several functions. For example video capturing, VBI capturing and radio support. -The V4L2 API creates different nodes for each of these functions. +The V4L2 API creates different V4L2 device nodes for each of these functions. The V4L2 API was designed with the idea that one device node could support all functions. However, in practice this never worked: this @@ -81,19 +157,19 @@ support all functions. However, in practice this never worked: this support it and if they did it was certainly never tested. In addition, switching a device node between different functions only works when using the streaming I/O API, not with the -:ref:`read() <func-read>`/\ :ref:`write() <func-write>` API. +:c:func:`read()`/\ :c:func:`write()` API. -Today each device node supports just one function. +Today each V4L2 device node supports just one function. Besides video input or output the hardware may also support audio sampling or playback. If so, these functions are implemented as ALSA PCM devices with optional ALSA audio mixer devices. One problem with all these devices is that the V4L2 API makes no -provisions to find these related devices. Some really complex devices -use the Media Controller (see :ref:`media_controller`) which can be -used for this purpose. But most drivers do not use it, and while some -code exists that uses sysfs to discover related devices (see +provisions to find these related V4L2 device nodes. Some really complex +hardware use the Media Controller (see :ref:`media_controller`) which can +be used for this purpose. But several drivers do not use it, and while some +code exists that uses sysfs to discover related V4L2 device nodes (see libmedia_dev in the `v4l-utils <http://git.linuxtv.org/cgit.cgi/v4l-utils.git/>`__ git repository), there is no library yet that can provide a single API @@ -102,7 +178,6 @@ the Media Controller. If you want to work on this please write to the linux-media mailing list: `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. - Multiple Opens ============== @@ -116,8 +191,8 @@ device should not change the state of the device. [#f2]_ Once an application has allocated the memory buffers needed for streaming data (by calling the :ref:`VIDIOC_REQBUFS` or :ref:`VIDIOC_CREATE_BUFS` ioctls, or -implicitly by calling the :ref:`read() <func-read>` or -:ref:`write() <func-write>` functions) that application (filehandle) +implicitly by calling the :c:func:`read()` or +:c:func:`write()` functions) that application (filehandle) becomes the owner of the device. It is no longer allowed to make changes that would affect the buffer sizes (e.g. by calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl) and other applications are @@ -130,7 +205,6 @@ requested type of data, and to change related properties, to this file descriptor. Applications can request additional access privileges using the priority mechanism described in :ref:`app-pri`. - Shared Data Streams =================== @@ -139,12 +213,11 @@ the same data stream on a device by copying buffers, time multiplexing or similar means. This is better handled by a proxy application in user space. - Functions ========= To open and close V4L2 devices applications use the -:ref:`open() <func-open>` and :ref:`close() <func-close>` function, +:c:func:`open()` and :c:func:`close()` function, respectively. Devices are programmed using the :ref:`ioctl() <func-ioctl>` function as explained in the following sections. @@ -152,7 +225,7 @@ sections. .. [#f1] There are still some old and obscure drivers that have not been updated to allow for multiple opens. This implies that for such - drivers :ref:`open() <func-open>` can return an ``EBUSY`` error code + drivers :c:func:`open()` can return an ``EBUSY`` error code when the device is already in use. .. [#f2] diff --git a/Documentation/userspace-api/media/v4l/pixfmt-bayer.rst b/Documentation/userspace-api/media/v4l/pixfmt-bayer.rst index be9a8385ebc1..ed3eb432967d 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-bayer.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-bayer.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _pixfmt-bayer: @@ -27,6 +20,7 @@ orders. See also `the Wikipedia article on Bayer filter :maxdepth: 1 pixfmt-srggb8 + pixfmt-srggb8-pisp-comp pixfmt-srggb10 pixfmt-srggb10p pixfmt-srggb10alaw8 diff --git a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst index 3828bb79225d..806ed73ac474 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later ****************** Compressed Formats @@ -14,7 +7,13 @@ Compressed Formats .. _compressed-formats: -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. raw:: latex + + \small + +.. tabularcolumns:: |p{5.8cm}|p{1.2cm}|p{10.3cm}| + +.. cssclass:: longtable .. flat-table:: Compressed Image Formats :header-rows: 1 @@ -64,18 +63,18 @@ Compressed Formats - H264 parsed slice data, including slice headers, either with or without the start code, as extracted from the H264 bitstream. This format is adapted for stateless video decoders that implement an - H264 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`). + H264 pipeline with the :ref:`stateless_decoder`. This pixelformat has two modifiers that must be set at least once - through the ``V4L2_CID_MPEG_VIDEO_H264_DECODE_MODE`` - and ``V4L2_CID_MPEG_VIDEO_H264_START_CODE`` controls. + through the ``V4L2_CID_STATELESS_H264_DECODE_MODE`` + and ``V4L2_CID_STATELESS_H264_START_CODE`` controls. In addition, metadata associated with the frame to decode are - required to be passed through the ``V4L2_CID_MPEG_VIDEO_H264_SPS``, - ``V4L2_CID_MPEG_VIDEO_H264_PPS``, - ``V4L2_CID_MPEG_VIDEO_H264_SCALING_MATRIX``, - ``V4L2_CID_MPEG_VIDEO_H264_SLICE_PARAMS`` and - ``V4L2_CID_MPEG_VIDEO_H264_DECODE_PARAMS`` controls. See the - :ref:`associated Codec Control IDs <v4l2-mpeg-h264>`. Exactly - one output and one capture buffer must be provided for use + required to be passed through the ``V4L2_CID_STATELESS_H264_SPS``, + ``V4L2_CID_STATELESS_H264_PPS``, + ``V4L2_CID_STATELESS_H264_SCALING_MATRIX``, + ``V4L2_CID_STATELESS_H264_SLICE_PARAMS`` and + ``V4L2_CID_STATELESS_H264_DECODE_PARAMS`` controls. See the + :ref:`associated Codec Control IDs <v4l2-codec-stateless-h264>`. + Exactly one output and one capture buffer must be provided for use with this pixel format. The output buffer must contain the appropriate number of macroblocks to decode a full corresponding frame to the matching capture buffer. @@ -84,16 +83,16 @@ Compressed Formats 7.3.2.8 "Slice layer without partitioning RBSP syntax" and the following sections. - .. note:: - - This format is not yet part of the public kernel API and it - is expected to change. - * .. _V4L2-PIX-FMT-H263: - ``V4L2_PIX_FMT_H263`` - 'H263' - H263 video elementary stream. + * .. _V4L2-PIX-FMT-SPK: + + - ``V4L2_PIX_FMT_SPK`` + - 'SPK0' + - Sorenson Spark is an implementation of H.263 for use in Flash Video and Adobe Flash files * .. _V4L2-PIX-FMT-MPEG1: - ``V4L2_PIX_FMT_MPEG1`` @@ -118,12 +117,13 @@ Compressed Formats - 'MG2S' - MPEG-2 parsed slice data, as extracted from the MPEG-2 bitstream. This format is adapted for stateless video decoders that implement a - MPEG-2 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`). + MPEG-2 pipeline with the :ref:`stateless_decoder`. Metadata associated with the frame to decode is required to be passed - through the ``V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS`` control and - quantization matrices can optionally be specified through the - ``V4L2_CID_MPEG_VIDEO_MPEG2_QUANTIZATION`` control. - See the :ref:`associated Codec Control IDs <v4l2-mpeg-mpeg2>`. + through the ``V4L2_CID_STATELESS_MPEG2_SEQUENCE`` and + ``V4L2_CID_STATELESS_MPEG2_PICTURE`` controls. + Quantisation matrices can optionally be specified through the + ``V4L2_CID_STATELESS_MPEG2_QUANTISATION`` control. + See the :ref:`associated Codec Control IDs <v4l2-codec-stateless-mpeg2>`. Exactly one output and one capture buffer must be provided for use with this pixel format. The output buffer must contain the appropriate number of macroblocks to decode a full corresponding frame to the matching @@ -159,22 +159,17 @@ Compressed Formats - ``V4L2_PIX_FMT_VP8_FRAME`` - 'VP8F' - - VP8 parsed frame, as extracted from the container. - This format is adapted for stateless video decoders that implement a - VP8 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`). + - VP8 parsed frame, including the frame header, as extracted from the container. + This format is adapted for stateless video decoders that implement an + VP8 pipeline with the :ref:`stateless_decoder`. Metadata associated with the frame to decode is required to be passed - through the ``V4L2_CID_MPEG_VIDEO_VP8_FRAME_HEADER`` control. - See the :ref:`associated Codec Control IDs <v4l2-mpeg-vp8>`. + through the ``V4L2_CID_STATELESS_VP8_FRAME`` control. + See the :ref:`associated Codec Control IDs <v4l2-codec-stateless-vp8>`. Exactly one output and one capture buffer must be provided for use with this pixel format. The output buffer must contain the appropriate number of macroblocks to decode a full corresponding frame to the matching capture buffer. - .. note:: - - This format is not yet part of the public kernel API and it - is expected to change. - * .. _V4L2-PIX-FMT-VP9: - ``V4L2_PIX_FMT_VP9`` @@ -182,6 +177,21 @@ Compressed Formats - VP9 compressed video frame. The encoder generates one compressed frame per buffer, and the decoder requires one compressed frame per buffer. + * .. _V4L2-PIX-FMT-VP9-FRAME: + + - ``V4L2_PIX_FMT_VP9_FRAME`` + - 'VP9F' + - VP9 parsed frame, including the frame header, as extracted from the container. + This format is adapted for stateless video decoders that implement a + VP9 pipeline with the :ref:`stateless_decoder`. + Metadata associated with the frame to decode is required to be passed + through the ``V4L2_CID_STATELESS_VP9_FRAME`` and + the ``V4L2_CID_STATELESS_VP9_COMPRESSED_HDR`` controls. + See the :ref:`associated Codec Control IDs <v4l2-codec-stateless-vp9>`. + Exactly one output and one capture buffer must be provided for use with + this pixel format. The output buffer must contain the appropriate number + of macroblocks to decode a full corresponding frame to the matching + capture buffer. * .. _V4L2-PIX-FMT-HEVC: - ``V4L2_PIX_FMT_HEVC`` @@ -203,18 +213,13 @@ Compressed Formats through the ``V4L2_CID_MPEG_VIDEO_HEVC_DECODE_MODE`` and ``V4L2_CID_MPEG_VIDEO_HEVC_START_CODE`` controls. Metadata associated with the frame to decode is required to be passed - through the following controls : - * ``V4L2_CID_MPEG_VIDEO_HEVC_SPS`` - * ``V4L2_CID_MPEG_VIDEO_HEVC_PPS`` - * ``V4L2_CID_MPEG_VIDEO_HEVC_SLICE_PARAMS`` - See the :ref:`associated Codec Control IDs <v4l2-mpeg-hevc>`. + through the following controls: + ``V4L2_CID_MPEG_VIDEO_HEVC_SPS``, + ``V4L2_CID_MPEG_VIDEO_HEVC_PPS``, and + ``V4L2_CID_MPEG_VIDEO_HEVC_SLICE_PARAMS``. + See the :ref:`associated Codec Control IDs <v4l2-codec-stateless-hevc>`. Buffers associated with this pixel format must contain the appropriate number of macroblocks to decode a full corresponding frame. - - .. note:: - - This format is not yet part of the public kernel API and it - is expected to change. * .. _V4L2-PIX-FMT-FWHT: - ``V4L2_PIX_FMT_FWHT`` @@ -229,4 +234,46 @@ Compressed Formats - ``V4L2_PIX_FMT_FWHT_STATELESS`` - 'SFWH' - Same format as V4L2_PIX_FMT_FWHT but requires stateless codec implementation. - See the :ref:`associated Codec Control IDs <v4l2-mpeg-fwht>`. + Metadata associated with the frame to decode is required to be passed + through the ``V4L2_CID_STATELESS_FWHT_PARAMS`` control. + See the :ref:`associated Codec Control ID <codec-stateless-fwht>`. + * .. _V4L2-PIX-FMT-RV30: + + - ``V4L2_PIX_FMT_RV30`` + - 'RV30' + - RealVideo, or also spelled as Real Video, is a suite of + proprietary video compression formats developed by + RealNetworks - the specific format changes with the version. + RealVideo codecs are identified by four-character codes. + RV30 corresponds to RealVideo 8, suspected to be based + largely on an early draft of H.264 + * .. _V4L2-PIX-FMT-RV40: + + - ``V4L2_PIX_FMT_RV40`` + - 'RV40' + - RV40 represents RealVideo 9 and RealVideo 10. + RealVideo 9, suspected to be based on H.264. + RealVideo 10, aka RV9 EHQ, This refers to an improved encoder + for the RV9 format that is fully backwards compatible with + RV9 players - the format and decoder did not change, only + the encoder did. As a result, it uses the same FourCC. + + * .. _V4L2-PIX-FMT-AV1-FRAME: + + - ``V4L2_PIX_FMT_AV1_FRAME`` + - 'AV1F' + - AV1 parsed frame, including the frame header, as extracted from the container. + This format is adapted for stateless video decoders that implement a AV1 + pipeline with the :ref:`stateless_decoder`. Metadata associated with the + frame to decode is required to be passed through the + ``V4L2_CID_STATELESS_AV1_SEQUENCE``, ``V4L2_CID_STATELESS_AV1_FRAME``, + and ``V4L2_CID_STATELESS_AV1_TILE_GROUP_ENTRY`` controls. + See the :ref:`associated Codec Control IDs <v4l2-codec-stateless-av1>`. + Exactly one output and one capture buffer must be provided for use with + this pixel format. The output buffer must contain the appropriate number + of macroblocks to decode a full corresponding frame to the matching + capture buffer. + +.. raw:: latex + + \normalsize diff --git a/Documentation/userspace-api/media/v4l/pixfmt-grey.rst b/Documentation/userspace-api/media/v4l/pixfmt-grey.rst deleted file mode 100644 index 7b03db3393be..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-grey.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-GREY: - -************************** -V4L2_PIX_FMT_GREY ('GREY') -************************** - -Grey-scale image - - -Description -=========== - -This is a grey-scale image. It is really a degenerate Y'CbCr format -which simply contains no Cb or Cr data. - -**Byte Order.** -Each cell is one byte. - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-indexed.rst b/Documentation/userspace-api/media/v4l/pixfmt-indexed.rst index d0d46ed27260..5bd4a47c5854 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-indexed.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-indexed.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _pixfmt-indexed: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-intro.rst b/Documentation/userspace-api/media/v4l/pixfmt-intro.rst index af870895f653..14239ee826bf 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-intro.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-intro.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later ********************** Standard Image Formats diff --git a/Documentation/userspace-api/media/v4l/pixfmt-inzi.rst b/Documentation/userspace-api/media/v4l/pixfmt-inzi.rst index f85cccb71741..3115c8f6a842 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-inzi.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-inzi.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-INZI: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-m420.rst b/Documentation/userspace-api/media/v4l/pixfmt-m420.rst index 5180bbe16c6e..c01a949e7c11 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-m420.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-m420.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-M420: @@ -74,60 +67,5 @@ Each cell is one byte. **Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 1 - - Y - - - - Y - - Y - - - - Y - * - - * - 2 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 3 - - Y - - - - Y - - Y - - - - Y +Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` +horizontally and vertically. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-vivid.rst b/Documentation/userspace-api/media/v4l/pixfmt-meta-vivid.rst deleted file mode 100644 index 34a2382ef91c..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-meta-vivid.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file is free software; you can redistribute it and/or -.. modify it under the terms of the GNU General Public License as -.. published by the Free Software Foundation version 2 of -.. the License. -.. -.. This file is distributed in the hope that it will be useful, -.. but WITHOUT ANY WARRANTY; without even the implied warranty of -.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.. GNU General Public License for more details. -.. -.. Or, alternatively, -.. -.. b) Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections - -.. _v4l2-meta-fmt-vivid: - -******************************* -V4L2_META_FMT_VIVID ('VIVD') -******************************* - -VIVID Metadata Format - - -Description -=========== - -This describes metadata format used by the vivid driver. - -It sets Brightness, Saturation, Contrast and Hue, each of which maps to -corresponding controls of the vivid driver with respect to the range and default values. - -It contains the following fields: - -.. flat-table:: VIVID Metadata - :widths: 1 4 - :header-rows: 1 - :stub-columns: 0 - - * - Field - - Description - * - u16 brightness; - - Image brightness, the value is in the range 0 to 255, with the default value as 128. - * - u16 contrast; - - Image contrast, the value is in the range 0 to 255, with the default value as 128. - * - u16 saturation; - - Image color saturation, the value is in the range 0 to 255, with the default value as 128. - * - s16 hue; - - Image color balance, the value is in the range -128 to 128, with the default value as 0. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv12.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv12.rst deleted file mode 100644 index 19d47b38e02a..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv12.rst +++ /dev/null @@ -1,136 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-NV12: -.. _V4L2-PIX-FMT-NV21: - -****************************************************** -V4L2_PIX_FMT_NV12 ('NV12'), V4L2_PIX_FMT_NV21 ('NV21') -****************************************************** - - -V4L2_PIX_FMT_NV21 -Formats with ½ horizontal and vertical chroma resolution, also known as -YUV 4:2:0. One luminance and one chrominance plane with alternating -chroma samples as opposed to ``V4L2_PIX_FMT_YVU420`` - - -Description -=========== - -These are two-plane versions of the YUV 4:2:0 format. The three -components are separated into two sub-images or planes. The Y plane is -first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_NV12``, a -combined CbCr plane immediately follows the Y plane in memory. The CbCr -plane is the same width, in bytes, as the Y plane (and of the image), -but is half as tall in pixels. Each CbCr pair belongs to four pixels. -For example, Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, -Y'\ :sub:`01`, Y'\ :sub:`10`, Y'\ :sub:`11`. ``V4L2_PIX_FMT_NV21`` is -the same except the Cb and Cr bytes are swapped, the CrCb plane starts -with a Cr byte. - -If the Y plane has pad bytes after each row, then the CbCr plane has as -many pad bytes after its rows. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cb\ :sub:`00` - - Cr\ :sub:`00` - - Cb\ :sub:`01` - - Cr\ :sub:`01` - * - start + 20: - - Cb\ :sub:`10` - - Cr\ :sub:`10` - - Cb\ :sub:`11` - - Cr\ :sub:`11` - - -**Color Sample Location:** - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 1 - - Y - - - - Y - - Y - - - - Y - * - - * - 2 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 3 - - Y - - - - Y - - Y - - - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv12m.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv12m.rst deleted file mode 100644 index 115ea603c13f..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv12m.rst +++ /dev/null @@ -1,151 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-NV12M: -.. _v4l2-pix-fmt-nv12mt-16x16: -.. _V4L2-PIX-FMT-NV21M: - -*********************************************************************************** -V4L2_PIX_FMT_NV12M ('NM12'), V4L2_PIX_FMT_NV21M ('NM21'), V4L2_PIX_FMT_NV12MT_16X16 -*********************************************************************************** - - -V4L2_PIX_FMT_NV21M -V4L2_PIX_FMT_NV12MT_16X16 -Variation of ``V4L2_PIX_FMT_NV12`` and ``V4L2_PIX_FMT_NV21`` with planes -non contiguous in memory. - - -Description -=========== - -This is a multi-planar, two-plane version of the YUV 4:2:0 format. The -three components are separated into two sub-images or planes. -``V4L2_PIX_FMT_NV12M`` differs from ``V4L2_PIX_FMT_NV12`` in that the -two planes are non-contiguous in memory, i.e. the chroma plane do not -necessarily immediately follows the luma plane. The luminance data -occupies the first plane. The Y plane has one byte per pixel. In the -second plane there is a chrominance data with alternating chroma -samples. The CbCr plane is the same width, in bytes, as the Y plane (and -of the image), but is half as tall in pixels. Each CbCr pair belongs to -four pixels. For example, Cb\ :sub:`0`/Cr\ :sub:`0` belongs to -Y'\ :sub:`00`, Y'\ :sub:`01`, Y'\ :sub:`10`, Y'\ :sub:`11`. -``V4L2_PIX_FMT_NV12MT_16X16`` is the tiled version of -``V4L2_PIX_FMT_NV12M`` with 16x16 macroblock tiles. Here pixels are -arranged in 16x16 2D tiles and tiles are arranged in linear order in -memory. ``V4L2_PIX_FMT_NV21M`` is the same as ``V4L2_PIX_FMT_NV12M`` -except the Cb and Cr bytes are swapped, the CrCb plane starts with a Cr -byte. - -``V4L2_PIX_FMT_NV12M`` is intended to be used only in drivers and -applications that support the multi-planar API, described in -:ref:`planar-apis`. - -If the Y plane has pad bytes after each row, then the CbCr plane has as -many pad bytes after its rows. - -**Byte Order.** -Each cell is one byte. - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start0 + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start0 + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start0 + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start0 + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - - * - start1 + 0: - - Cb\ :sub:`00` - - Cr\ :sub:`00` - - Cb\ :sub:`01` - - Cr\ :sub:`01` - * - start1 + 4: - - Cb\ :sub:`10` - - Cr\ :sub:`10` - - Cb\ :sub:`11` - - Cr\ :sub:`11` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 1 - - Y - - - - Y - - Y - - - - Y - * - - * - 2 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - - - C - - - * - 3 - - Y - - - - Y - - Y - - - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv12mt.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv12mt.rst deleted file mode 100644 index daac1c16d4f2..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv12mt.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-NV12MT: - -**************************** -V4L2_PIX_FMT_NV12MT ('TM12') -**************************** - -Formats with ½ horizontal and vertical chroma resolution. This format -has two planes - one for luminance and one for chrominance. Chroma -samples are interleaved. The difference to ``V4L2_PIX_FMT_NV12`` is the -memory layout. Pixels are grouped in macroblocks of 64x32 size. The -order of macroblocks in memory is also not standard. - - -Description -=========== - -This is the two-plane versions of the YUV 4:2:0 format where data is -grouped into 64x32 macroblocks. The three components are separated into -two sub-images or planes. The Y plane has one byte per pixel and pixels -are grouped into 64x32 macroblocks. The CbCr plane has the same width, -in bytes, as the Y plane (and the image), but is half as tall in pixels. -The chroma plane is also grouped into 64x32 macroblocks. - -Width of the buffer has to be aligned to the multiple of 128, and height -alignment is 32. Every four adjacent buffers - two horizontally and two -vertically are grouped together and are located in memory in Z or -flipped Z order. - -Layout of macroblocks in memory is presented in the following figure. - - -.. _nv12mt: - -.. kernel-figure:: nv12mt.svg - :alt: nv12mt.svg - :align: center - - V4L2_PIX_FMT_NV12MT macroblock Z shape memory layout - -The requirement that width is multiple of 128 is implemented because, -the Z shape cannot be cut in half horizontally. In case the vertical -resolution of macroblocks is odd then the last row of macroblocks is -arranged in a linear order. - -In case of chroma the layout is identical. Cb and Cr samples are -interleaved. Height of the buffer is aligned to 32. - - -.. _nv12mt_ex: - -.. kernel-figure:: nv12mt_example.svg - :alt: nv12mt_example.svg - :align: center - - Example V4L2_PIX_FMT_NV12MT memory layout of macroblocks - -Memory layout of macroblocks of ``V4L2_PIX_FMT_NV12MT`` format in most -extreme case. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv16.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv16.rst deleted file mode 100644 index 977636fc98d6..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv16.rst +++ /dev/null @@ -1,160 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-NV16: -.. _V4L2-PIX-FMT-NV61: - -****************************************************** -V4L2_PIX_FMT_NV16 ('NV16'), V4L2_PIX_FMT_NV61 ('NV61') -****************************************************** - -V4L2_PIX_FMT_NV61 -Formats with ½ horizontal chroma resolution, also known as YUV 4:2:2. -One luminance and one chrominance plane with alternating chroma samples -as opposed to ``V4L2_PIX_FMT_YVU420`` - - -Description -=========== - -These are two-plane versions of the YUV 4:2:2 format. The three -components are separated into two sub-images or planes. The Y plane is -first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_NV16``, a -combined CbCr plane immediately follows the Y plane in memory. The CbCr -plane is the same width and height, in bytes, as the Y plane (and of the -image). Each CbCr pair belongs to two pixels. For example, -Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`. -``V4L2_PIX_FMT_NV61`` is the same except the Cb and Cr bytes are -swapped, the CrCb plane starts with a Cr byte. - -If the Y plane has pad bytes after each row, then the CbCr plane has as -many pad bytes after its rows. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cb\ :sub:`00` - - Cr\ :sub:`00` - - Cb\ :sub:`01` - - Cr\ :sub:`01` - * - start + 20: - - Cb\ :sub:`10` - - Cr\ :sub:`10` - - Cb\ :sub:`11` - - Cr\ :sub:`11` - * - start + 24: - - Cb\ :sub:`20` - - Cr\ :sub:`20` - - Cb\ :sub:`21` - - Cr\ :sub:`21` - * - start + 28: - - Cb\ :sub:`30` - - Cr\ :sub:`30` - - Cb\ :sub:`31` - - Cr\ :sub:`31` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 1 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - - * - 2 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 3 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst deleted file mode 100644 index cf33942d942d..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst +++ /dev/null @@ -1,164 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-NV16M: -.. _v4l2-pix-fmt-nv61m: - -******************************************************** -V4L2_PIX_FMT_NV16M ('NM16'), V4L2_PIX_FMT_NV61M ('NM61') -******************************************************** - -V4L2_PIX_FMT_NV61M -Variation of ``V4L2_PIX_FMT_NV16`` and ``V4L2_PIX_FMT_NV61`` with planes -non contiguous in memory. - - -Description -=========== - -This is a multi-planar, two-plane version of the YUV 4:2:2 format. The -three components are separated into two sub-images or planes. -``V4L2_PIX_FMT_NV16M`` differs from ``V4L2_PIX_FMT_NV16`` in that the -two planes are non-contiguous in memory, i.e. the chroma plane does not -necessarily immediately follow the luma plane. The luminance data -occupies the first plane. The Y plane has one byte per pixel. In the -second plane there is chrominance data with alternating chroma samples. -The CbCr plane is the same width and height, in bytes, as the Y plane. -Each CbCr pair belongs to two pixels. For example, -Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`. -``V4L2_PIX_FMT_NV61M`` is the same as ``V4L2_PIX_FMT_NV16M`` except the -Cb and Cr bytes are swapped, the CrCb plane starts with a Cr byte. - -``V4L2_PIX_FMT_NV16M`` and ``V4L2_PIX_FMT_NV61M`` are intended to be -used only in drivers and applications that support the multi-planar API, -described in :ref:`planar-apis`. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start0 + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start0 + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start0 + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start0 + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - - * - start1 + 0: - - Cb\ :sub:`00` - - Cr\ :sub:`00` - - Cb\ :sub:`02` - - Cr\ :sub:`02` - * - start1 + 4: - - Cb\ :sub:`10` - - Cr\ :sub:`10` - - Cb\ :sub:`12` - - Cr\ :sub:`12` - * - start1 + 8: - - Cb\ :sub:`20` - - Cr\ :sub:`20` - - Cb\ :sub:`22` - - Cr\ :sub:`22` - * - start1 + 12: - - Cb\ :sub:`30` - - Cr\ :sub:`30` - - Cb\ :sub:`32` - - Cr\ :sub:`32` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 1 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - - * - 2 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 3 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv24.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv24.rst deleted file mode 100644 index c6fb97bd0472..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv24.rst +++ /dev/null @@ -1,102 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-NV24: -.. _V4L2-PIX-FMT-NV42: - -****************************************************** -V4L2_PIX_FMT_NV24 ('NV24'), V4L2_PIX_FMT_NV42 ('NV42') -****************************************************** - -V4L2_PIX_FMT_NV42 -Formats with full horizontal and vertical chroma resolutions, also known -as YUV 4:4:4. One luminance and one chrominance plane with alternating -chroma samples as opposed to ``V4L2_PIX_FMT_YVU420`` - - -Description -=========== - -These are two-plane versions of the YUV 4:4:4 format. The three -components are separated into two sub-images or planes. The Y plane is -first, with each Y sample stored in one byte per pixel. For -``V4L2_PIX_FMT_NV24``, a combined CbCr plane immediately follows the Y -plane in memory. The CbCr plane has the same width and height, in -pixels, as the Y plane (and the image). Each line contains one CbCr pair -per pixel, with each Cb and Cr sample stored in one byte. -``V4L2_PIX_FMT_NV42`` is the same except that the Cb and Cr samples are -swapped, the CrCb plane starts with a Cr sample. - -If the Y plane has pad bytes after each row, then the CbCr plane has -twice as many pad bytes after its rows. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cb\ :sub:`00` - - Cr\ :sub:`00` - - Cb\ :sub:`01` - - Cr\ :sub:`01` - - Cb\ :sub:`02` - - Cr\ :sub:`02` - - Cb\ :sub:`03` - - Cr\ :sub:`03` - * - start + 24: - - Cb\ :sub:`10` - - Cr\ :sub:`10` - - Cb\ :sub:`11` - - Cr\ :sub:`11` - - Cb\ :sub:`12` - - Cr\ :sub:`12` - - Cb\ :sub:`13` - - Cr\ :sub:`13` - * - start + 32: - - Cb\ :sub:`20` - - Cr\ :sub:`20` - - Cb\ :sub:`21` - - Cr\ :sub:`21` - - Cb\ :sub:`22` - - Cr\ :sub:`22` - - Cb\ :sub:`23` - - Cr\ :sub:`23` - * - start + 40: - - Cb\ :sub:`30` - - Cr\ :sub:`30` - - Cb\ :sub:`31` - - Cr\ :sub:`31` - - Cb\ :sub:`32` - - Cr\ :sub:`32` - - Cb\ :sub:`33` - - Cr\ :sub:`33` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-hsv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-hsv.rst index b8c9b0225eea..dd89860f50e0 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-packed-hsv.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-hsv.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _packed-hsv: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst index bbd4bd094deb..9f111ed594d2 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _packed-yuv: @@ -13,24 +6,42 @@ Packed YUV formats ****************** -Description -=========== +Similarly to the packed RGB formats, the packed YUV formats store the Y, Cb and +Cr components consecutively in memory. They may apply subsampling to the chroma +components and thus differ in how they interlave the three components. -Similar to the packed RGB formats these formats store the Y, Cb and Cr -component of each pixel in one 16 or 32 bit word. +.. note:: + + - In all the tables that follow, bit 7 is the most significant bit in a byte. + - 'Y', 'Cb' and 'Cr' denote bits of the luma, blue chroma (also known as + 'U') and red chroma (also known as 'V') components respectively. 'A' + denotes bits of the alpha component (if supported by the format), and 'X' + denotes padding bits. + + +4:4:4 Subsampling +================= + +These formats do not subsample the chroma components and store each pixels as a +full triplet of Y, Cb and Cr values. +The next table lists the packed YUV 4:4:4 formats with less than 8 bits per +component. They are named based on the order of the Y, Cb and Cr components as +seen in a 16-bit word, which is then stored in memory in little endian byte +order, and on the number of bits for each component. For instance the YUV565 +format stores a pixel in a 16-bit word [15:0] laid out at as [Y'\ :sub:`4-0` +Cb\ :sub:`5-0` Cr\ :sub:`4-0`], and stored in memory in two bytes, +[Cb\ :sub:`2-0` Cr\ :sub:`4-0`] followed by [Y'\ :sub:`4-0` Cb\ :sub:`5-3`]. .. raw:: latex \begingroup - \tiny + \scriptsize \setlength{\tabcolsep}{2pt} -.. _packed-yuv-formats: +.. tabularcolumns:: |p{3.5cm}|p{0.96cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}| -.. tabularcolumns:: |p{2.5cm}|p{0.69cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}| - -.. flat-table:: Packed YUV Image Formats +.. flat-table:: Packed YUV 4:4:4 Image Formats (less than 8bpc) :header-rows: 2 :stub-columns: 0 @@ -41,10 +52,6 @@ component of each pixel in one 16 or 32 bit word. - :cspan:`7` Byte 1 - - :cspan:`7` Byte 2 - - - :cspan:`7` Byte 3 - * - - - 7 @@ -65,24 +72,6 @@ component of each pixel in one 16 or 32 bit word. - 1 - 0 - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - * .. _V4L2-PIX-FMT-YUV444: - ``V4L2_PIX_FMT_YUV444`` @@ -106,8 +95,6 @@ component of each pixel in one 16 or 32 bit word. - Y'\ :sub:`1` - Y'\ :sub:`0` - - :cspan:`15` - * .. _V4L2-PIX-FMT-YUV555: - ``V4L2_PIX_FMT_YUV555`` @@ -131,7 +118,6 @@ component of each pixel in one 16 or 32 bit word. - Cb\ :sub:`4` - Cb\ :sub:`3` - - :cspan:`15` * .. _V4L2-PIX-FMT-YUV565: - ``V4L2_PIX_FMT_YUV565`` @@ -155,226 +141,342 @@ component of each pixel in one 16 or 32 bit word. - Cb\ :sub:`4` - Cb\ :sub:`3` - - :cspan:`15` +.. raw:: latex - * .. _V4L2-PIX-FMT-YUV32: + \endgroup - - ``V4L2_PIX_FMT_YUV32`` - - 'YUV4' +.. note:: - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` + For the YUV444 and YUV555 formats, the value of alpha bits is undefined + when reading from the driver, ignored when writing to the driver, except + when alpha blending has been negotiated for a :ref:`Video Overlay + <overlay>` or :ref:`Video Output Overlay <osd>`. - - Y'\ :sub:`7` - - Y'\ :sub:`6` - - Y'\ :sub:`5` - - Y'\ :sub:`4` - - Y'\ :sub:`3` - - Y'\ :sub:`2` - - Y'\ :sub:`1` - - Y'\ :sub:`0` - - Cb\ :sub:`7` - - Cb\ :sub:`6` - - Cb\ :sub:`5` - - Cb\ :sub:`4` - - Cb\ :sub:`3` - - Cb\ :sub:`2` - - Cb\ :sub:`1` - - Cb\ :sub:`0` +The next table lists the packed YUV 4:4:4 formats with 8 bits per component. +They are named based on the order of the Y, Cb and Cr components as stored in +memory, and on the total number of bits per pixel. For instance, the VUYX32 +format stores a pixel with Cr\ :sub:`7-0` in the first byte, Cb\ :sub:`7-0` in +the second byte and Y'\ :sub:`7-0` in the third byte. - - Cr\ :sub:`7` - - Cr\ :sub:`6` - - Cr\ :sub:`5` - - Cr\ :sub:`4` - - Cr\ :sub:`3` - - Cr\ :sub:`2` - - Cr\ :sub:`1` - - Cr\ :sub:`0` +.. flat-table:: Packed YUV Image Formats (8bpc) + :header-rows: 1 + :stub-columns: 0 - * .. _V4L2-PIX-FMT-AYUV32: + * - Identifier + - Code + - Byte 0 + - Byte 1 + - Byte 2 + - Byte 3 - - ``V4L2_PIX_FMT_AYUV32`` - - 'AYUV' + * .. _V4L2-PIX-FMT-YUV32: - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` + - ``V4L2_PIX_FMT_YUV32`` + - 'YUV4' - - Y'\ :sub:`7` - - Y'\ :sub:`6` - - Y'\ :sub:`5` - - Y'\ :sub:`4` - - Y'\ :sub:`3` - - Y'\ :sub:`2` - - Y'\ :sub:`1` - - Y'\ :sub:`0` + - A\ :sub:`7-0` + - Y'\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Cr\ :sub:`7-0` - - Cb\ :sub:`7` - - Cb\ :sub:`6` - - Cb\ :sub:`5` - - Cb\ :sub:`4` - - Cb\ :sub:`3` - - Cb\ :sub:`2` - - Cb\ :sub:`1` - - Cb\ :sub:`0` + * .. _V4L2-PIX-FMT-AYUV32: - - Cr\ :sub:`7` - - Cr\ :sub:`6` - - Cr\ :sub:`5` - - Cr\ :sub:`4` - - Cr\ :sub:`3` - - Cr\ :sub:`2` - - Cr\ :sub:`1` - - Cr\ :sub:`0` + - ``V4L2_PIX_FMT_AYUV32`` + - 'AYUV' + + - A\ :sub:`7-0` + - Y'\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Cr\ :sub:`7-0` * .. _V4L2-PIX-FMT-XYUV32: - ``V4L2_PIX_FMT_XYUV32`` - 'XYUV' - - - - - - - - - - - - - - - - - - - Y'\ :sub:`7` - - Y'\ :sub:`6` - - Y'\ :sub:`5` - - Y'\ :sub:`4` - - Y'\ :sub:`3` - - Y'\ :sub:`2` - - Y'\ :sub:`1` - - Y'\ :sub:`0` - - - Cb\ :sub:`7` - - Cb\ :sub:`6` - - Cb\ :sub:`5` - - Cb\ :sub:`4` - - Cb\ :sub:`3` - - Cb\ :sub:`2` - - Cb\ :sub:`1` - - Cb\ :sub:`0` - - - Cr\ :sub:`7` - - Cr\ :sub:`6` - - Cr\ :sub:`5` - - Cr\ :sub:`4` - - Cr\ :sub:`3` - - Cr\ :sub:`2` - - Cr\ :sub:`1` - - Cr\ :sub:`0` + - X\ :sub:`7-0` + - Y'\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Cr\ :sub:`7-0` * .. _V4L2-PIX-FMT-VUYA32: - ``V4L2_PIX_FMT_VUYA32`` - 'VUYA' - - Cr\ :sub:`7` - - Cr\ :sub:`6` - - Cr\ :sub:`5` - - Cr\ :sub:`4` - - Cr\ :sub:`3` - - Cr\ :sub:`2` - - Cr\ :sub:`1` - - Cr\ :sub:`0` - - - Cb\ :sub:`7` - - Cb\ :sub:`6` - - Cb\ :sub:`5` - - Cb\ :sub:`4` - - Cb\ :sub:`3` - - Cb\ :sub:`2` - - Cb\ :sub:`1` - - Cb\ :sub:`0` - - - Y'\ :sub:`7` - - Y'\ :sub:`6` - - Y'\ :sub:`5` - - Y'\ :sub:`4` - - Y'\ :sub:`3` - - Y'\ :sub:`2` - - Y'\ :sub:`1` - - Y'\ :sub:`0` - - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` + - Cr\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Y'\ :sub:`7-0` + - A\ :sub:`7-0` * .. _V4L2-PIX-FMT-VUYX32: - ``V4L2_PIX_FMT_VUYX32`` - 'VUYX' - - Cr\ :sub:`7` - - Cr\ :sub:`6` - - Cr\ :sub:`5` - - Cr\ :sub:`4` - - Cr\ :sub:`3` - - Cr\ :sub:`2` - - Cr\ :sub:`1` - - Cr\ :sub:`0` + - Cr\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Y'\ :sub:`7-0` + - X\ :sub:`7-0` - - Cb\ :sub:`7` - - Cb\ :sub:`6` - - Cb\ :sub:`5` - - Cb\ :sub:`4` - - Cb\ :sub:`3` - - Cb\ :sub:`2` - - Cb\ :sub:`1` + * .. _V4L2-PIX-FMT-YUVA32: + + - ``V4L2_PIX_FMT_YUVA32`` + - 'YUVA' + + - Y'\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Cr\ :sub:`7-0` + - A\ :sub:`7-0` + + * .. _V4L2-PIX-FMT-YUVX32: + + - ``V4L2_PIX_FMT_YUVX32`` + - 'YUVX' + + - Y'\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Cr\ :sub:`7-0` + - X\ :sub:`7-0` + + * .. _V4L2-PIX-FMT-YUV24: + + - ``V4L2_PIX_FMT_YUV24`` + - 'YUV3' + + - Y'\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Cr\ :sub:`7-0` + - -\ + +.. note:: + + - The alpha component is expected to contain a meaningful value that can be + used by drivers and applications. + - The padding bits contain undefined values that must be ignored by all + applications and drivers. + +The next table lists the packed YUV 4:4:4 formats with 12 bits per component. +Expand the bits per component to 16 bits, data in the high bits, zeros in the low bits, +arranged in little endian order, storing 1 pixel in 6 bytes. + +.. flat-table:: Packed YUV 4:4:4 Image Formats (12bpc) + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Byte 1-0 + - Byte 3-2 + - Byte 5-4 + - Byte 7-6 + - Byte 9-8 + - Byte 11-10 + + * .. _V4L2-PIX-FMT-YUV48-12: + + - ``V4L2_PIX_FMT_YUV48_12`` + - 'Y312' + + - Y'\ :sub:`0` - Cb\ :sub:`0` + - Cr\ :sub:`0` + - Y'\ :sub:`1` + - Cb\ :sub:`1` + - Cr\ :sub:`1` - - Y'\ :sub:`7` - - Y'\ :sub:`6` - - Y'\ :sub:`5` - - Y'\ :sub:`4` +4:2:2 Subsampling +================= + +These formats, commonly referred to as YUYV or YUY2, subsample the chroma +components horizontally by 2, storing 2 pixels in a container. The container +is 32-bits for 8-bit formats, and 64-bits for 10+-bit formats. + +The packed YUYV formats with more than 8 bits per component are stored as four +16-bit little-endian words. Each word's most significant bits contain one +component, and the least significant bits are zero padding. + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{3.4cm}|p{1.2cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}| + +.. flat-table:: Packed YUV 4:2:2 Formats in 32-bit container + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Byte 0 + - Byte 1 + - Byte 2 + - Byte 3 + - Byte 4 + - Byte 5 + - Byte 6 + - Byte 7 + * .. _V4L2-PIX-FMT-UYVY: + + - ``V4L2_PIX_FMT_UYVY`` + - 'UYVY' + + - Cb\ :sub:`0` + - Y'\ :sub:`0` + - Cr\ :sub:`0` + - Y'\ :sub:`1` + - Cb\ :sub:`2` + - Y'\ :sub:`2` + - Cr\ :sub:`2` - Y'\ :sub:`3` + * .. _V4L2-PIX-FMT-VYUY: + + - ``V4L2_PIX_FMT_VYUY`` + - 'VYUY' + + - Cr\ :sub:`0` + - Y'\ :sub:`0` + - Cb\ :sub:`0` + - Y'\ :sub:`1` + - Cr\ :sub:`2` - Y'\ :sub:`2` + - Cb\ :sub:`2` + - Y'\ :sub:`3` + * .. _V4L2-PIX-FMT-YUYV: + + - ``V4L2_PIX_FMT_YUYV`` + - 'YUYV' + + - Y'\ :sub:`0` + - Cb\ :sub:`0` - Y'\ :sub:`1` + - Cr\ :sub:`0` + - Y'\ :sub:`2` + - Cb\ :sub:`2` + - Y'\ :sub:`3` + - Cr\ :sub:`2` + * .. _V4L2-PIX-FMT-YVYU: + + - ``V4L2_PIX_FMT_YVYU`` + - 'YVYU' + - Y'\ :sub:`0` + - Cr\ :sub:`0` + - Y'\ :sub:`1` + - Cb\ :sub:`0` + - Y'\ :sub:`2` + - Cr\ :sub:`2` + - Y'\ :sub:`3` + - Cb\ :sub:`2` - - - - - - - - - - - - - - - - +.. tabularcolumns:: |p{3.4cm}|p{1.2cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}| + +.. flat-table:: Packed YUV 4:2:2 Formats in 64-bit container + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Word 0 + - Word 1 + - Word 2 + - Word 3 + * .. _V4L2-PIX-FMT-Y210: + + - ``V4L2_PIX_FMT_Y210`` + - 'Y210' + + - Y'\ :sub:`0` (bits 15-6) + - Cb\ :sub:`0` (bits 15-6) + - Y'\ :sub:`1` (bits 15-6) + - Cr\ :sub:`0` (bits 15-6) + * .. _V4L2-PIX-FMT-Y212: + + - ``V4L2_PIX_FMT_Y212`` + - 'Y212' + + - Y'\ :sub:`0` (bits 15-4) + - Cb\ :sub:`0` (bits 15-4) + - Y'\ :sub:`1` (bits 15-4) + - Cr\ :sub:`0` (bits 15-4) + * .. _V4L2-PIX-FMT-Y216: + + - ``V4L2_PIX_FMT_Y216`` + - 'Y216' + + - Y'\ :sub:`0` (bits 15-0) + - Cb\ :sub:`0` (bits 15-0) + - Y'\ :sub:`1` (bits 15-0) + - Cr\ :sub:`0` (bits 15-0) .. raw:: latex - \endgroup + \normalsize + +**Color Sample Location:** +Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` +horizontally. + + +4:1:1 Subsampling +================= + +This format subsamples the chroma components horizontally by 4, storing 8 +pixels in 12 bytes. + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{2.9cm}|p{0.8cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}| + +.. flat-table:: Packed YUV 4:1:1 Formats + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Byte 0 + - Byte 1 + - Byte 2 + - Byte 3 + - Byte 4 + - Byte 5 + - Byte 6 + - Byte 7 + - Byte 8 + - Byte 9 + - Byte 10 + - Byte 11 + * .. _V4L2-PIX-FMT-Y41P: + + - ``V4L2_PIX_FMT_Y41P`` + - 'Y41P' + + - Cb\ :sub:`0` + - Y'\ :sub:`0` + - Cr\ :sub:`0` + - Y'\ :sub:`1` + - Cb\ :sub:`4` + - Y'\ :sub:`2` + - Cr\ :sub:`4` + - Y'\ :sub:`3` + - Y'\ :sub:`4` + - Y'\ :sub:`5` + - Y'\ :sub:`6` + - Y'\ :sub:`7` + +.. raw:: latex + + \normalsize .. note:: - #) Bit 7 is the most significant bit; + Do not confuse ``V4L2_PIX_FMT_Y41P`` with + :ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>`. Y41P is derived from + "YUV 4:1:1 **packed**", while YUV411P stands for "YUV 4:1:1 **planar**". - #) The value of a = alpha bits is undefined when reading from the driver, - ignored when writing to the driver, except when alpha blending has - been negotiated for a :ref:`Video Overlay <overlay>` or - :ref:`Video Output Overlay <osd>` for the formats Y444, YUV555 and - YUV4. However, for formats AYUV32 and VUYA32, the alpha component is - expected to contain a meaningful value that can be used by drivers - and applications. And, the formats XYUV32 and VUYX32 contain undefined - alpha values that must be ignored by all applications and drivers. +**Color Sample Location:** +Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` +horizontally. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst b/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst index 59b9e7238f90..ac52485252d9 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _pixfmt-reserved: @@ -24,7 +17,11 @@ you think your format should be listed in a standard format section please make a proposal on the linux-media mailing list. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| + +.. raw:: latex + + \small .. _reserved-formats: @@ -51,14 +48,6 @@ please make a proposal on the linux-media mailing list. - ``V4L2_PIX_FMT_HI240`` - 'HI24' - 8 bit RGB format used by the BTTV driver. - * .. _V4L2-PIX-FMT-HM12: - - - ``V4L2_PIX_FMT_HM12`` - - 'HM12' - - YUV 4:2:0 format used by the IVTV driver. - - The format is documented in the kernel sources in the file - ``Documentation/userspace-api/media/drivers/cx2341x-uapi.rst`` * .. _V4L2-PIX-FMT-CPIA1: - ``V4L2_PIX_FMT_CPIA1`` @@ -244,39 +233,55 @@ please make a proposal on the linux-media mailing list. - ``V4L2_PIX_FMT_MT21C`` - 'MT21' - - Compressed two-planar YVU420 format used by Mediatek MT8173. - The compression is lossless. - It is an opaque intermediate format and the MDP hardware must be + - Compressed two-planar YVU420 format used by Mediatek MT8173, MT8192, + MT8195 and more. The compression is lossless. This format have + similitude with ``V4L2_PIX_FMT_MM21`` in term of alignment and tiling. + It remains an opaque intermediate format and the MDP hardware must be used to convert ``V4L2_PIX_FMT_MT21C`` to ``V4L2_PIX_FMT_NV12M``, ``V4L2_PIX_FMT_YUV420M`` or ``V4L2_PIX_FMT_YVU420``. - * .. _V4L2-PIX-FMT-SUNXI-TILED-NV12: - - - ``V4L2_PIX_FMT_SUNXI_TILED_NV12`` - - 'ST12' - - Two-planar NV12-based format used by the video engine found on Allwinner - (codenamed sunxi) platforms, with 32x32 tiles for the luminance plane - and 32x64 tiles for the chrominance plane. The data in each tile is - stored in linear order, within the tile bounds. Each tile follows the - previous one linearly in memory (from left to right, top to bottom). - - The associated buffer dimensions are aligned to match an integer number - of tiles, resulting in 32-aligned resolutions for the luminance plane - and 16-aligned resolutions for the chrominance plane (with 2x2 - subsampling). - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| - -.. _format-flags: - -.. flat-table:: Format Flags - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * - ``V4L2_PIX_FMT_FLAG_PREMUL_ALPHA`` - - 0x00000001 - - The color values are premultiplied by the alpha channel value. For - example, if a light blue pixel with 50% transparency was described - by RGBA values (128, 192, 255, 128), the same pixel described with - premultiplied colors would be described by RGBA values (64, 96, - 128, 128) + * .. _V4L2-PIX-FMT-QC08C: + + - ``V4L2_PIX_FMT_QC08C`` + - 'QC08C' + - Compressed Macro-tile 8-Bit YUV420 format used by Qualcomm platforms. + It is an opaque intermediate format. The used compression is lossless + and it is used by various multimedia hardware blocks like GPU, display + controllers, ISP and video accelerators. + It contains four planes for progressive video and eight planes for + interlaced video. + * .. _V4L2-PIX-FMT-QC10C: + + - ``V4L2_PIX_FMT_QC10C`` + - 'QC10C' + - Compressed Macro-tile 10-Bit YUV420 format used by Qualcomm platforms. + It is an opaque intermediate format. The used compression is lossless + and it is used by various multimedia hardware blocks like GPU, display + controllers, ISP and video accelerators. + It contains four planes for progressive video. + * .. _V4L2-PIX-FMT-AJPG: + + - ``V4L2_PIX_FMT_AJPG`` + - 'AJPG' + - ASPEED JPEG format used by the aspeed-video driver on Aspeed platforms, + which is generally adapted for remote KVM. + On each frame compression, I will compare the new frame with previous + one to decide which macroblock's data is changed, and only the changed + macroblocks will be compressed. + + The implementation is based on AST2600 A3 datasheet, revision 0.9, which + is not publicly available. Or you can reference Video stream data format + – ASPEED mode compression of SDK_User_Guide which available on + `github <https://github.com/AspeedTech-BMC/openbmc/releases/>`__. + + Decoder's implementation can be found here, + `aspeed_codec <https://github.com/AspeedTech-BMC/aspeed_codec/>`__ + * .. _V4L2-PIX-FMT-HEXTILE: + + - ``V4L2_PIX_FMT_HEXTILE`` + - 'HXTL' + - Compressed format used by Nuvoton NPCM video driver. This format is + defined in Remote Framebuffer Protocol (RFC 6143, chapter 7.7.4 Hextile + Encoding). +.. raw:: latex + + \normalsize diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst index 89cc2a37b285..5ed4d62df909 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _pixfmt-rgb: @@ -13,13 +6,62 @@ RGB Formats *********** -Description -=========== - -These formats are designed to match the pixel formats of typical PC -graphics frame buffers. They occupy 8, 16, 24 or 32 bits per pixel. -These are all packed-pixel formats, meaning all the data for a pixel lie -next to each other in memory. +These formats encode each pixel as a triplet of RGB values. They are packed +formats, meaning that the RGB values for one pixel are stored consecutively in +memory and each pixel consumes an integer number of bytes. When the number of +bits required to store a pixel is not aligned to a byte boundary, the data is +padded with additional bits to fill the remaining byte. + +The formats differ by the number of bits per RGB component (typically but not +always the same for all components), the order of components in memory, and the +presence of an alpha component or additional padding bits. + +The usage and value of the alpha bits in formats that support them (named ARGB +or a permutation thereof, collectively referred to as alpha formats) depend on +the device type and hardware operation. :ref:`Capture <capture>` devices +(including capture queues of mem-to-mem devices) fill the alpha component in +memory. When the device captures an alpha channel the alpha component will have +a meaningful value. Otherwise, when the device doesn't capture an alpha channel +but can set the alpha bit to a user-configurable value, the +:ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control is used to +specify that alpha value, and the alpha component of all pixels will be set to +the value specified by that control. Otherwise a corresponding format without +an alpha component (XRGB or XBGR) must be used instead of an alpha format. + +:ref:`Output <output>` devices (including output queues of mem-to-mem devices +and :ref:`video output overlay <osd>` devices) read the alpha component from +memory. When the device processes the alpha channel the alpha component must be +filled with meaningful values by applications. Otherwise a corresponding format +without an alpha component (XRGB or XBGR) must be used instead of an alpha +format. + +Formats that contain padding bits are named XRGB (or a permutation thereof). +The padding bits contain undefined values and must be ignored by applications, +devices and drivers, for both :ref:`capture` and :ref:`output` devices. + +.. note:: + + - In all the tables that follow, bit 7 is the most significant bit in a byte. + - 'r', 'g' and 'b' denote bits of the red, green and blue components + respectively. 'a' denotes bits of the alpha component (if supported by the + format), and 'x' denotes padding bits. + + +Less Than 8 Bits Per Component +============================== + +These formats store an RGB triplet in one, two or four bytes. They are named +based on the order of the RGB components as seen in a 8-, 16- or 32-bit word, +which is then stored in memory in little endian byte order (unless otherwise +noted by the presence of bit 31 in the 4CC value), and on the number of bits +for each component. For instance, the RGB565 format stores a pixel in a 16-bit +word [15:0] laid out at as [R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1` +R\ :sub:`0` G\ :sub:`5` G\ :sub:`4` G\ :sub:`3` G\ :sub:`2` G\ :sub:`1` +G\ :sub:`0` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` B\ :sub:`1` B\ :sub:`0`], and +stored in memory in two bytes, [R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1` +R\ :sub:`0` G\ :sub:`5` G\ :sub:`4` G\ :sub:`3`] followed by [G\ :sub:`2` +G\ :sub:`1` G\ :sub:`0` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` B\ :sub:`1` +B\ :sub:`0`]. .. raw:: latex @@ -30,7 +72,7 @@ next to each other in memory. .. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| -.. flat-table:: RGB Image Formats +.. flat-table:: RGB Formats With Less Than 8 Bits Per Component :header-rows: 2 :stub-columns: 0 @@ -128,10 +170,10 @@ next to each other in memory. - b\ :sub:`1` - b\ :sub:`0` - - `-` - - `-` - - `-` - - `-` + - x + - x + - x + - x - r\ :sub:`3` - r\ :sub:`2` - r\ :sub:`1` @@ -169,10 +211,10 @@ next to each other in memory. - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` - - `-` - - `-` - - `-` - - `-` + - x + - x + - x + - x - r\ :sub:`3` - r\ :sub:`2` @@ -220,10 +262,10 @@ next to each other in memory. - r\ :sub:`1` - r\ :sub:`0` - - `-` - - `-` - - `-` - - `-` + - x + - x + - x + - x - b\ :sub:`3` - b\ :sub:`2` - b\ :sub:`1` @@ -261,10 +303,10 @@ next to each other in memory. - r\ :sub:`2` - r\ :sub:`1` - r\ :sub:`0` - - `-` - - `-` - - `-` - - `-` + - x + - x + - x + - x - b\ :sub:`3` - b\ :sub:`2` @@ -312,7 +354,7 @@ next to each other in memory. - b\ :sub:`1` - b\ :sub:`0` - - `-` + - x - r\ :sub:`4` - r\ :sub:`3` - r\ :sub:`2` @@ -356,7 +398,7 @@ next to each other in memory. - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` - - `-` + - x - r\ :sub:`4` - r\ :sub:`3` @@ -404,7 +446,7 @@ next to each other in memory. - r\ :sub:`1` - r\ :sub:`0` - - `-` + - x - b\ :sub:`4` - b\ :sub:`3` - b\ :sub:`2` @@ -448,7 +490,7 @@ next to each other in memory. - r\ :sub:`2` - r\ :sub:`1` - r\ :sub:`0` - - `-` + - x - b\ :sub:`4` - b\ :sub:`3` @@ -510,7 +552,7 @@ next to each other in memory. - ``V4L2_PIX_FMT_XRGB555X`` - 'XR15' | (1 << 31) - - `-` + - x - r\ :sub:`4` - r\ :sub:`3` - r\ :sub:`2` @@ -551,74 +593,245 @@ next to each other in memory. - b\ :sub:`1` - b\ :sub:`0` - - * .. _V4L2-PIX-FMT-BGR24: + * .. _V4L2-PIX-FMT-BGR666: - - ``V4L2_PIX_FMT_BGR24`` - - 'BGR3' + - ``V4L2_PIX_FMT_BGR666`` + - 'BGRH' - - b\ :sub:`7` - - b\ :sub:`6` - b\ :sub:`5` - b\ :sub:`4` - b\ :sub:`3` - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - g\ :sub:`5` - g\ :sub:`4` + - g\ :sub:`3` - g\ :sub:`2` - g\ :sub:`1` - g\ :sub:`0` - - - r\ :sub:`7` - - r\ :sub:`6` - r\ :sub:`5` - r\ :sub:`4` - r\ :sub:`3` - r\ :sub:`2` + - r\ :sub:`1` - r\ :sub:`0` + - x + - x + - x + - x + - x + - x + + - x + - x + - x + - x + - x + - x + - x + - x + +.. raw:: latex + + \endgroup + + +8 Bits Per Component +==================== + +These formats store an RGB triplet in three or four bytes. They are named based +on the order of the RGB components as stored in memory, and on the total number +of bits per pixel. For instance, RGB24 format stores a pixel with [R\ :sub:`7` +R\ :sub:`6` R\ :sub:`5` R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1` +R\ :sub:`0`] in the first byte, [G\ :sub:`7` G\ :sub:`6` G\ :sub:`5` G\ :sub:`4` +G\ :sub:`3` G\ :sub:`2` G\ :sub:`1` G\ :sub:`0`] in the second byte and +[B\ :sub:`7` B\ :sub:`6` B\ :sub:`5` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` +B\ :sub:`1` B\ :sub:`0`] in the third byte. This differs from the DRM format +nomenclature that instead use the order of components as seen in a 24- or +32-bit little endian word. + +.. raw:: latex + + \small + +.. flat-table:: RGB Formats With 8 Bits Per Component + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Byte 0 in memory + - Byte 1 + - Byte 2 + - Byte 3 + * .. _V4L2-PIX-FMT-BGR24: + + - ``V4L2_PIX_FMT_BGR24`` + - 'BGR3' + + - B\ :sub:`7-0` + - G\ :sub:`7-0` + - R\ :sub:`7-0` - * .. _V4L2-PIX-FMT-RGB24: - ``V4L2_PIX_FMT_RGB24`` - 'RGB3' - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` + - R\ :sub:`7-0` + - G\ :sub:`7-0` + - B\ :sub:`7-0` + - + * .. _V4L2-PIX-FMT-ABGR32: - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` + - ``V4L2_PIX_FMT_ABGR32`` + - 'AR24' - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` + - B\ :sub:`7-0` + - G\ :sub:`7-0` + - R\ :sub:`7-0` + - A\ :sub:`7-0` + * .. _V4L2-PIX-FMT-XBGR32: + + - ``V4L2_PIX_FMT_XBGR32`` + - 'XR24' + + - B\ :sub:`7-0` + - G\ :sub:`7-0` + - R\ :sub:`7-0` + - X\ :sub:`7-0` + * .. _V4L2-PIX-FMT-BGRA32: + + - ``V4L2_PIX_FMT_BGRA32`` + - 'RA24' + + - A\ :sub:`7-0` + - B\ :sub:`7-0` + - G\ :sub:`7-0` + - R\ :sub:`7-0` + * .. _V4L2-PIX-FMT-BGRX32: + + - ``V4L2_PIX_FMT_BGRX32`` + - 'RX24' + + - X\ :sub:`7-0` + - B\ :sub:`7-0` + - G\ :sub:`7-0` + - R\ :sub:`7-0` + * .. _V4L2-PIX-FMT-RGBA32: + + - ``V4L2_PIX_FMT_RGBA32`` + - 'AB24' + + - R\ :sub:`7-0` + - G\ :sub:`7-0` + - B\ :sub:`7-0` + - A\ :sub:`7-0` + * .. _V4L2-PIX-FMT-RGBX32: + + - ``V4L2_PIX_FMT_RGBX32`` + - 'XB24' + + - R\ :sub:`7-0` + - G\ :sub:`7-0` + - B\ :sub:`7-0` + - X\ :sub:`7-0` + * .. _V4L2-PIX-FMT-ARGB32: + + - ``V4L2_PIX_FMT_ARGB32`` + - 'BA24' + + - A\ :sub:`7-0` + - R\ :sub:`7-0` + - G\ :sub:`7-0` + - B\ :sub:`7-0` + * .. _V4L2-PIX-FMT-XRGB32: + + - ``V4L2_PIX_FMT_XRGB32`` + - 'BX24' + + - X\ :sub:`7-0` + - R\ :sub:`7-0` + - G\ :sub:`7-0` + - B\ :sub:`7-0` + +.. raw:: latex + + \normalsize + + +10 Bits Per Component +===================== + +These formats store a 30-bit RGB triplet with an optional 2 bit alpha in four +bytes. They are named based on the order of the RGB components as seen in a +32-bit word, which is then stored in memory in little endian byte order +(unless otherwise noted by the presence of bit 31 in the 4CC value), and on the +number of bits for each component. + +.. raw:: latex + + \begingroup + \tiny + \setlength{\tabcolsep}{2pt} + +.. tabularcolumns:: |p{3.2cm}|p{0.8cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| + + +.. flat-table:: RGB Formats 10 Bits Per Color Component + :header-rows: 2 + :stub-columns: 0 + + * - Identifier + - Code + - :cspan:`7` Byte 0 in memory + - :cspan:`7` Byte 1 + - :cspan:`7` Byte 2 + - :cspan:`7` Byte 3 + * - - - * .. _V4L2-PIX-FMT-BGR666: + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 - - ``V4L2_PIX_FMT_BGR666`` - - 'BGRH' + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + * .. _V4L2-PIX-FMT-RGBX1010102: + + - ``V4L2_PIX_FMT_RGBX1010102`` + - 'RX30' - b\ :sub:`5` - b\ :sub:`4` @@ -626,168 +839,79 @@ next to each other in memory. - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` - - g\ :sub:`5` - - g\ :sub:`4` + - x + - x - g\ :sub:`3` - g\ :sub:`2` - g\ :sub:`1` - g\ :sub:`0` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - - r\ :sub:`1` - - r\ :sub:`0` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - * .. _V4L2-PIX-FMT-ABGR32: - - - ``V4L2_PIX_FMT_ABGR32`` - - 'AR24' - + - b\ :sub:`9` + - b\ :sub:`8` - b\ :sub:`7` - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`9` + - g\ :sub:`8` - g\ :sub:`7` - g\ :sub:`6` - g\ :sub:`5` - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` + - r\ :sub:`9` + - r\ :sub:`8` - r\ :sub:`7` - r\ :sub:`6` - r\ :sub:`5` - r\ :sub:`4` - r\ :sub:`3` - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - * .. _V4L2-PIX-FMT-XBGR32: + * .. _V4L2-PIX-FMT-RGBA1010102: - - ``V4L2_PIX_FMT_XBGR32`` - - 'XR24' + - ``V4L2_PIX_FMT_RGBA1010102`` + - 'RA30' - - b\ :sub:`7` - - b\ :sub:`6` - b\ :sub:`5` - b\ :sub:`4` - b\ :sub:`3` - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` + - a\ :sub:`1` + - a\ :sub:`0` - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - g\ :sub:`3` - g\ :sub:`2` - g\ :sub:`1` - g\ :sub:`0` - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - * .. _V4L2-PIX-FMT-BGRA32: - - - ``V4L2_PIX_FMT_BGRA32`` - - 'RA24' - - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - + - b\ :sub:`9` + - b\ :sub:`8` - b\ :sub:`7` - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`9` + - g\ :sub:`8` - g\ :sub:`7` - g\ :sub:`6` - g\ :sub:`5` - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` + - r\ :sub:`9` + - r\ :sub:`8` - r\ :sub:`7` - r\ :sub:`6` - r\ :sub:`5` - r\ :sub:`4` - r\ :sub:`3` - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - * .. _V4L2-PIX-FMT-BGRX32: + * .. _V4L2-PIX-FMT-ARGB2101010: - - ``V4L2_PIX_FMT_BGRX32`` - - 'RX24' - - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` + - ``V4L2_PIX_FMT_ARGB2101010`` + - 'AR30' - b\ :sub:`7` - b\ :sub:`6` @@ -798,291 +922,141 @@ next to each other in memory. - b\ :sub:`1` - b\ :sub:`0` - - g\ :sub:`7` - - g\ :sub:`6` - g\ :sub:`5` - g\ :sub:`4` - g\ :sub:`3` - g\ :sub:`2` - g\ :sub:`1` - g\ :sub:`0` + - b\ :sub:`9` + - b\ :sub:`8` - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - r\ :sub:`3` - r\ :sub:`2` - r\ :sub:`1` - r\ :sub:`0` - * .. _V4L2-PIX-FMT-RGBA32: - - - ``V4L2_PIX_FMT_RGBA32`` - - 'AB24' - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - + - g\ :sub:`9` + - g\ :sub:`8` - g\ :sub:`7` - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - a\ :sub:`1` - a\ :sub:`0` - * .. _V4L2-PIX-FMT-RGBX32: - - - ``V4L2_PIX_FMT_RGBX32`` - - 'XB24' - + - r\ :sub:`9` + - r\ :sub:`8` - r\ :sub:`7` - r\ :sub:`6` - r\ :sub:`5` - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` +.. raw:: latex - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - * .. _V4L2-PIX-FMT-ARGB32: + \endgroup - - ``V4L2_PIX_FMT_ARGB32`` - - 'BA24' +12 Bits Per Component +============================== - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` +These formats store an RGB triplet in six or eight bytes, with 12 bits per component. +Expand the bits per component to 16 bits, data in the high bits, zeros in the low bits, +arranged in little endian order. - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` +.. raw:: latex - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` + \small - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - * .. _V4L2-PIX-FMT-XRGB32: +.. flat-table:: RGB Formats With 12 Bits Per Component + :header-rows: 1 - - ``V4L2_PIX_FMT_XRGB32`` - - 'BX24' + * - Identifier + - Code + - Byte 1-0 + - Byte 3-2 + - Byte 5-4 + - Byte 7-6 + * .. _V4L2-PIX-FMT-BGR48-12: + + - ``V4L2_PIX_FMT_BGR48_12`` + - 'B312' + + - B\ :sub:`15-4` + - G\ :sub:`15-4` + - R\ :sub:`15-4` + - + * .. _V4L2-PIX-FMT-ABGR64-12: - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` + - ``V4L2_PIX_FMT_ABGR64_12`` + - 'B412' - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` + - B\ :sub:`15-4` + - G\ :sub:`15-4` + - R\ :sub:`15-4` + - A\ :sub:`15-4` - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` +.. raw:: latex - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` + \normalsize -.. raw:: latex +16 Bits Per Component +===================== - \endgroup +These formats store an RGB triplet in six bytes, with 16 bits per component +stored in memory in little endian byte order. They are named based on the order +of the RGB components as stored in memory. For instance, RGB48 stores R\ +:sub:`7:0` and R\ :sub:`15:8` in bytes 0 and 1 respectively. This differs from +the DRM format nomenclature that instead uses the order of components as seen in +the 48-bits little endian word. -.. note:: Bit 7 is the most significant bit. +.. raw:: latex -The usage and value of the alpha bits (a) in the ARGB and ABGR formats -(collectively referred to as alpha formats) depend on the device type -and hardware operation. :ref:`Capture <capture>` devices (including -capture queues of mem-to-mem devices) fill the alpha component in -memory. When the device outputs an alpha channel the alpha component -will have a meaningful value. Otherwise, when the device doesn't output -an alpha channel but can set the alpha bit to a user-configurable value, -the :ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control -is used to specify that alpha value, and the alpha component of all -pixels will be set to the value specified by that control. Otherwise a -corresponding format without an alpha component (XRGB or XBGR) must be -used instead of an alpha format. + \small -:ref:`Output <output>` devices (including output queues of mem-to-mem -devices and :ref:`video output overlay <osd>` devices) read the alpha -component from memory. When the device processes the alpha channel the -alpha component must be filled with meaningful values by applications. -Otherwise a corresponding format without an alpha component (XRGB or -XBGR) must be used instead of an alpha format. +.. flat-table:: RGB Formats With 16 Bits Per Component + :header-rows: 1 -The XRGB and XBGR formats contain undefined bits (-). Applications, -devices and drivers must ignore those bits, for both -:ref:`capture` and :ref:`output` devices. + * - Identifier + - Code + - Byte 0 + - Byte 1 + - Byte 2 + - Byte 3 + - Byte 4 + - Byte 5 -**Byte Order.** -Each cell is one byte. + * .. _V4L2-PIX-FMT-BGR48: + - ``V4L2_PIX_FMT_BGR48`` + - 'BGR6' -.. raw:: latex + - B\ :sub:`7-0` + - B\ :sub:`15-8` + - G\ :sub:`7-0` + - G\ :sub:`15-8` + - R\ :sub:`7-0` + - R\ :sub:`15-8` - \small + * .. _V4L2-PIX-FMT-RGB48: -.. tabularcolumns:: |p{3.1cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}| + - ``V4L2_PIX_FMT_RGB48`` + - 'RGB6' -.. flat-table:: RGB byte order - :header-rows: 0 - :stub-columns: 0 - :widths: 11 3 3 3 3 3 3 3 3 3 3 3 3 - - * - start + 0: - - B\ :sub:`00` - - G\ :sub:`00` - - R\ :sub:`00` - - B\ :sub:`01` - - G\ :sub:`01` - - R\ :sub:`01` - - B\ :sub:`02` - - G\ :sub:`02` - - R\ :sub:`02` - - B\ :sub:`03` - - G\ :sub:`03` - - R\ :sub:`03` - * - start + 12: - - B\ :sub:`10` - - G\ :sub:`10` - - R\ :sub:`10` - - B\ :sub:`11` - - G\ :sub:`11` - - R\ :sub:`11` - - B\ :sub:`12` - - G\ :sub:`12` - - R\ :sub:`12` - - B\ :sub:`13` - - G\ :sub:`13` - - R\ :sub:`13` - * - start + 24: - - B\ :sub:`20` - - G\ :sub:`20` - - R\ :sub:`20` - - B\ :sub:`21` - - G\ :sub:`21` - - R\ :sub:`21` - - B\ :sub:`22` - - G\ :sub:`22` - - R\ :sub:`22` - - B\ :sub:`23` - - G\ :sub:`23` - - R\ :sub:`23` - * - start + 36: - - B\ :sub:`30` - - G\ :sub:`30` - - R\ :sub:`30` - - B\ :sub:`31` - - G\ :sub:`31` - - R\ :sub:`31` - - B\ :sub:`32` - - G\ :sub:`32` - - R\ :sub:`32` - - B\ :sub:`33` - - G\ :sub:`33` - - R\ :sub:`33` + - R\ :sub:`7-0` + - R\ :sub:`15-8` + - G\ :sub:`7-0` + - G\ :sub:`15-8` + - B\ :sub:`7-0` + - B\ :sub:`15-8` .. raw:: latex \normalsize -Formats defined in :ref:`pixfmt-rgb-deprecated` are deprecated and -must not be used by new drivers. They are documented here for reference. -The meaning of their alpha bits ``(a)`` are ill-defined and interpreted as in -either the corresponding ARGB or XRGB format, depending on the driver. +Deprecated RGB Formats +====================== +Formats defined in :ref:`pixfmt-rgb-deprecated` are deprecated and must not be +used by new drivers. They are documented here for reference. The meaning of +their alpha bits ``(a)`` is ill-defined and they are interpreted as in either +the corresponding ARGB or XRGB format, depending on the driver. .. raw:: latex diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs08.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs08.rst index 13f3908d162a..bd6ee6111de4 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs08.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs08.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2-sdr-fmt-cs8: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs14le.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs14le.rst index 41e5b990d499..ea21b288d357 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs14le.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs14le.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-SDR-FMT-CS14LE: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu08.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu08.rst index 1085b5ad8eb7..45fce09d85ff 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu08.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu08.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2-sdr-fmt-cu8: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu16le.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu16le.rst index 9772b30bda95..7f4242f8da6f 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu16le.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu16le.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-SDR-FMT-CU16LE: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu16be.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu16be.rst index 53a0a862f33a..a4d4b70ece63 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu16be.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu16be.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-SDR-FMT-PCU16BE: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu18be.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu18be.rst index 7f2d2545fb04..3db690bd683a 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu18be.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu18be.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-SDR-FMT-PCU18BE: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu20be.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu20be.rst index 9f3d67b4e94c..485343cdf150 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu20be.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu20be.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-SDR-FMT-PCU20BE: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-ru12le.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-ru12le.rst index c9cde8d425f7..2ad4706bfc7a 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-ru12le.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-ru12le.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-SDR-FMT-RU12LE: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst index 5afa02a66698..3322b0600f1d 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2-pix-fmt-ipu3-sbggr10: .. _v4l2-pix-fmt-ipu3-sgbrg10: @@ -16,7 +9,9 @@ V4L2_PIX_FMT_IPU3_SBGGR10 ('ip3b'), V4L2_PIX_FMT_IPU3_SGBRG10 ('ip3g'), V4L2_PIX_FMT_IPU3_SGRBG10 ('ip3G'), V4L2_PIX_FMT_IPU3_SRGGB10 ('ip3r') ********************************************************************************************************************************************** +==================== 10-bit Bayer formats +==================== Description =========== @@ -32,7 +27,11 @@ Below is an example of a small image in V4L2_PIX_FMT_IPU3_SBGGR10 format. **Byte Order.** Each cell is one byte. -.. tabularcolumns:: |p{0.8cm}|p{4.0cm}|p{4.0cm}|p{4.0cm}|p{4.0cm}| +.. raw:: latex + + \small + +.. tabularcolumns:: |p{0.8cm}|p{3.3cm}|p{3.3cm}|p{3.3cm}|p{3.3cm}| .. flat-table:: @@ -340,3 +339,7 @@ Each cell is one byte. - R\ :sub:`0323high` - G\ :sub:`0324low` - G\ :sub:`0324high`\ (bits 1--0) + +.. raw:: latex + + \normalsize diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb10.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb10.rst index 37cc1bb8241f..a66414ab4291 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb10.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb10.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-SRGGB10: .. _v4l2-pix-fmt-sbggr10: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb10alaw8.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb10alaw8.rst index f1b8627f0141..a5ae1f099e68 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb10alaw8.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb10alaw8.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-SBGGR10ALAW8: .. _v4l2-pix-fmt-sgbrg10alaw8: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb10dpcm8.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb10dpcm8.rst index 9814c4ffac68..f0544c6f4580 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb10dpcm8.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb10dpcm8.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-SBGGR10DPCM8: .. _v4l2-pix-fmt-sgbrg10dpcm8: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst index 76a4d278e640..fd5feb415531 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-SRGGB10P: .. _v4l2-pix-fmt-sbggr10p: @@ -40,7 +33,7 @@ of a small V4L2_PIX_FMT_SBGGR10P image: **Byte Order.** Each cell is one byte. -.. tabularcolumns:: |p{2.4cm}|p{1.4cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|p{6.4cm}| +.. tabularcolumns:: |p{2.4cm}|p{1.4cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|p{9.3cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb12.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb12.rst index 98ae80b968ae..15c34e1e4835 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb12.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb12.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-SRGGB12: .. _v4l2-pix-fmt-sbggr12: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst index 7309dd7fa60f..7c3810ff783c 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-SRGGB12P: .. _v4l2-pix-fmt-sbggr12p: @@ -38,7 +31,7 @@ Below is an example of a small V4L2_PIX_FMT_SBGGR12P image: **Byte Order.** Each cell is one byte. -.. tabularcolumns:: |p{2.2cm}|p{1.2cm}|p{1.2cm}|p{3.1cm}|p{1.2cm}|p{1.2cm}|p{3.1cm}| +.. tabularcolumns:: |p{2.2cm}|p{1.2cm}|p{1.2cm}|p{3.1cm}|p{1.2cm}|p{1.2cm}|p{6.4cm}| .. flat-table:: @@ -67,7 +60,7 @@ Each cell is one byte. G\ :sub:`10low`\ (bits 3--0) - G\ :sub:`12high` - R\ :sub:`13high` - - R\ :sub:`13low`\ (bits 3--2) + - R\ :sub:`13low`\ (bits 7--4) G\ :sub:`12low`\ (bits 3--0) - - start + 12: @@ -89,6 +82,6 @@ Each cell is one byte. G\ :sub:`30low`\ (bits 3--0) - G\ :sub:`32high` - R\ :sub:`33high` - - R\ :sub:`33low`\ (bits 3--2) + - R\ :sub:`33low`\ (bits 7--4) G\ :sub:`32low`\ (bits 3--0) diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst index a4c7a392fe7f..4f5120a6c678 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-SRGGB14: .. _v4l2-pix-fmt-sbggr14: @@ -18,7 +11,9 @@ V4L2_PIX_FMT_SRGGB14 ('RG14'), V4L2_PIX_FMT_SGRBG14 ('GR14'), V4L2_PIX_FMT_SGBRG *************************************************************************************************************************** +======================================== 14-bit Bayer formats expanded to 16 bits +======================================== Description diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst index ec1239ada316..3572e42adb22 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-SRGGB14P: .. _v4l2-pix-fmt-sbggr14p: @@ -43,9 +36,11 @@ Each cell is one byte. .. raw:: latex + \begingroup \footnotesize + \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{1.8cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{1.1cm}|p{3.3cm}|p{3.3cm}|p{3.3cm}| +.. tabularcolumns:: |p{1.6cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{3.5cm}|p{3.5cm}|p{3.5cm}| .. flat-table:: :header-rows: 0 @@ -69,37 +64,37 @@ Each cell is one byte. B\ :sub:`00low bits 5--0`\ (bits 5--0) - - R\ :sub:`02low bits 3--0`\ (bits 7--4) + - B\ :sub:`02low bits 3--0`\ (bits 7--4) G\ :sub:`01low bits 5--2`\ (bits 3--0) - G\ :sub:`03low bits 5--0`\ (bits 7--2) - R\ :sub:`02low bits 5--4`\ (bits 1--0) + B\ :sub:`02low bits 5--4`\ (bits 1--0) - .. row 2 - start + 7 - - G\ :sub:`00high` + - G\ :sub:`10high` - - R\ :sub:`01high` + - R\ :sub:`11high` - - G\ :sub:`02high` + - G\ :sub:`12high` - - R\ :sub:`03high` + - R\ :sub:`13high` - - R\ :sub:`01low bits 1--0`\ (bits 7--6) + - R\ :sub:`11low bits 1--0`\ (bits 7--6) - G\ :sub:`00low bits 5--0`\ (bits 5--0) + G\ :sub:`10low bits 5--0`\ (bits 5--0) - - G\ :sub:`02low bits 3--0`\ (bits 7--4) + - G\ :sub:`12low bits 3--0`\ (bits 7--4) - R\ :sub:`01low bits 5--2`\ (bits 3--0) + R\ :sub:`11low bits 5--2`\ (bits 3--0) - - R\ :sub:`03low bits 5--0`\ (bits 7--2) + - R\ :sub:`13low bits 5--0`\ (bits 7--2) - G\ :sub:`02low bits 5--4`\ (bits 1--0) + G\ :sub:`12low bits 5--4`\ (bits 1--0) - .. row 3 @@ -117,13 +112,13 @@ Each cell is one byte. B\ :sub:`20low bits 5--0`\ (bits 5--0) - - R\ :sub:`22low bits 3--0`\ (bits 7--4) + - B\ :sub:`22low bits 3--0`\ (bits 7--4) G\ :sub:`21low bits 5--2`\ (bits 3--0) - G\ :sub:`23low bits 5--0`\ (bits 7--2) - R\ :sub:`22low bits 5--4`\ (bits 1--0) + B\ :sub:`22low bits 5--4`\ (bits 1--0) - .. row 4 @@ -148,5 +143,5 @@ Each cell is one byte. .. raw:: latex - \normalsize + \endgroup diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst index 885f0d1f331d..2f2f1ef430d9 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-SRGGB16: .. _v4l2-pix-fmt-sbggr16: @@ -18,7 +11,9 @@ V4L2_PIX_FMT_SRGGB16 ('RG16'), V4L2_PIX_FMT_SGRBG16 ('GR16'), V4L2_PIX_FMT_SGBRG *************************************************************************************************************************** +==================== 16-bit Bayer formats +==================== Description diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb8-pisp-comp.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb8-pisp-comp.rst new file mode 100644 index 000000000000..5a82a15559d6 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb8-pisp-comp.rst @@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _v4l2-pix-fmt-pisp-comp1-rggb: +.. _v4l2-pix-fmt-pisp-comp1-grbg: +.. _v4l2-pix-fmt-pisp-comp1-gbrg: +.. _v4l2-pix-fmt-pisp-comp1-bggr: +.. _v4l2-pix-fmt-pisp-comp1-mono: +.. _v4l2-pix-fmt-pisp-comp2-rggb: +.. _v4l2-pix-fmt-pisp-comp2-grbg: +.. _v4l2-pix-fmt-pisp-comp2-gbrg: +.. _v4l2-pix-fmt-pisp-comp2-bggr: +.. _v4l2-pix-fmt-pisp-comp2-mono: + +************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************** +V4L2_PIX_FMT_PISP_COMP1_RGGB ('PC1R'), V4L2_PIX_FMT_PISP_COMP1_GRBG ('PC1G'), V4L2_PIX_FMT_PISP_COMP1_GBRG ('PC1g'), V4L2_PIX_FMT_PISP_COMP1_BGGR ('PC1B), V4L2_PIX_FMT_PISP_COMP1_MONO ('PC1M'), V4L2_PIX_FMT_PISP_COMP2_RGGB ('PC2R'), V4L2_PIX_FMT_PISP_COMP2_GRBG ('PC2G'), V4L2_PIX_FMT_PISP_COMP2_GBRG ('PC2g'), V4L2_PIX_FMT_PISP_COMP2_BGGR ('PC2B), V4L2_PIX_FMT_PISP_COMP2_MONO ('PC2M') +************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************** + +================================================ +Raspberry Pi PiSP compressed 8-bit Bayer formats +================================================ + +Description +=========== + +The Raspberry Pi ISP (PiSP) uses a family of three fixed-rate compressed Bayer +formats. A black-level offset may be subtracted to improve compression +efficiency; the nominal black level and amount of offset must be signalled out +of band. Each scanline is padded to a multiple of 8 pixels wide, and each block +of 8 horizontally-contiguous pixels is coded using 8 bytes. + +Mode 1 uses a quantization and delta-based coding scheme which preserves up to +12 significant bits. Mode 2 is a simple sqrt-like companding scheme with 6 PWL +chords, preserving up to 12 significant bits. Mode 3 combines both companding +(with 4 chords) and the delta scheme, preserving up to 14 significant bits. + +The remainder of this description applies to Modes 1 and 3. + +Each block of 8 pixels is separated into even and odd phases of 4 pixels, +coded independently by 32-bit words at successive locations in memory. +The two LS bits of each 32-bit word give its "quantization mode". + +In quantization mode 0, the lowest 321 quantization levels are multiples of +FSD/4096 and the remaining levels are successive multiples of FSD/2048. +Quantization modes 1 and 2 use linear quantization with step sizes of +FSD/1024 and FSD/512 respectively. Each of the four pixels is quantized +independently, with rounding to the nearest level. +In quantization mode 2 where the middle two samples have quantized values +(q1,q2) both in the range [384..511], they are coded using 9 bits for q1 +followed by 7 bits for (q2 & 127). Otherwise, for quantization modes +0, 1 and 2: a 9-bit field encodes MIN(q1,q2) which must be in the range +[0..511] and a 7-bit field encodes (q2-q1+64) which must be in [0..127]. + +Each of the outer samples (q0,q3) is encoded using a 7-bit field based +on its inner neighbour q1 or q2. In quantization mode 2 where the inner +sample has a quantized value in the range [448..511], the field value is +(q0-384). Otherwise for quantization modes 0, 1 and 2: The outer sample +is encoded as (q0-MAX(0,q1-64)). q3 is likewise coded based on q2. +Each of these values must be in the range [0..127]. All these fields +of 2, 9, 7, 7, 7 bits respectively are packed in little-endian order +to give a 32-bit word with LE byte order. + +Quantization mode 3 has a "7.5-bit" escape, used when none of the above +encodings will fit. Each pixel value is quantized to the nearest of 176 +levels, where the lowest 95 levels are multiples of FSD/256 and the +remaining levels are multiples of FSD/128 (level 175 represents values +very close to FSD and may require saturating arithmetic to decode). + +Each pair of quantized pixels (q0,q1) or (q2,q3) is jointly coded +by a 15-bit field: 2816*(q0>>4) + 16*q1 + (q0&15). +Three fields of 2, 15, 15 bits are packed in LE order {15,15,2}. + +An implementation of a software decoder of compressed formats is available +in `Raspberry Pi camera applications code base +<https://github.com/raspberrypi/rpicam-apps/blob/main/image/dng.cpp>`_. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst index c275e6ef09f9..02061c5a9778 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-SRGGB8: .. _v4l2-pix-fmt-sbggr8: @@ -17,8 +10,9 @@ V4L2_PIX_FMT_SRGGB8 ('RGGB'), V4L2_PIX_FMT_SGRBG8 ('GRBG'), V4L2_PIX_FMT_SGBRG8 *************************************************************************************************************************** +=================== 8-bit Bayer formats - +=================== Description =========== diff --git a/Documentation/userspace-api/media/v4l/pixfmt-tch-td08.rst b/Documentation/userspace-api/media/v4l/pixfmt-tch-td08.rst index 165c9be2bfc5..ec89f43c60ec 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-tch-td08.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-tch-td08.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-TCH-FMT-DELTA-TD08: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-tch-td16.rst b/Documentation/userspace-api/media/v4l/pixfmt-tch-td16.rst index 6dca01182175..7b59a6424243 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-tch-td16.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-tch-td16.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-TCH-FMT-DELTA-TD16: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-tch-tu08.rst b/Documentation/userspace-api/media/v4l/pixfmt-tch-tu08.rst index f1380b72977f..63c5264b8668 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-tch-tu08.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-tch-tu08.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-TCH-FMT-TU08: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-tch-tu16.rst b/Documentation/userspace-api/media/v4l/pixfmt-tch-tu16.rst index 2b9e1b15abcf..ade618a037a8 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-tch-tu16.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-tch-tu16.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-TCH-FMT-TU16: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-uv8.rst b/Documentation/userspace-api/media/v4l/pixfmt-uv8.rst index a36c1a4d64a4..ff1d73ef5dba 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-uv8.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-uv8.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-UV8: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst b/Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst deleted file mode 100644 index 776cb37f76f1..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst +++ /dev/null @@ -1,117 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-UYVY: - -************************** -V4L2_PIX_FMT_UYVY ('UYVY') -************************** - - -Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in -memory - - -Description -=========== - -In this format each four bytes is two pixels. Each four bytes is two -Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr -belong to both pixels. As you can see, the Cr and Cb components have -half the horizontal resolution of the Y component. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Cb\ :sub:`00` - - Y'\ :sub:`00` - - Cr\ :sub:`00` - - Y'\ :sub:`01` - - Cb\ :sub:`01` - - Y'\ :sub:`02` - - Cr\ :sub:`01` - - Y'\ :sub:`03` - * - start + 8: - - Cb\ :sub:`10` - - Y'\ :sub:`10` - - Cr\ :sub:`10` - - Y'\ :sub:`11` - - Cb\ :sub:`11` - - Y'\ :sub:`12` - - Cr\ :sub:`11` - - Y'\ :sub:`13` - * - start + 16: - - Cb\ :sub:`20` - - Y'\ :sub:`20` - - Cr\ :sub:`20` - - Y'\ :sub:`21` - - Cb\ :sub:`21` - - Y'\ :sub:`22` - - Cr\ :sub:`21` - - Y'\ :sub:`23` - * - start + 24: - - Cb\ :sub:`30` - - Y'\ :sub:`30` - - Cr\ :sub:`30` - - Y'\ :sub:`31` - - Cb\ :sub:`31` - - Y'\ :sub:`32` - - Cr\ :sub:`31` - - Y'\ :sub:`33` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - C - - Y - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst b/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst index 444b4082684c..ad4da988c3a3 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later ****************************** Multi-planar format structures @@ -20,7 +13,7 @@ describing all planes of that format. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{1.4cm}|p{4.0cm}|p{11.9cm}| .. c:type:: v4l2_plane_pix_format @@ -59,7 +52,7 @@ describing all planes of that format. \small -.. tabularcolumns:: |p{4.4cm}|p{5.6cm}|p{7.5cm}| +.. tabularcolumns:: |p{4.4cm}|p{5.6cm}|p{7.3cm}| .. c:type:: v4l2_pix_format_mplane @@ -105,29 +98,21 @@ describing all planes of that format. * - __u8 - ``ycbcr_enc`` - Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`. - This information supplements the ``colorspace`` and must be set by - the driver for capture streams and by the application for output - streams, see :ref:`colorspaces`. + See struct :c:type:`v4l2_pix_format`. * - __u8 - ``hsv_enc`` - HSV encoding, from enum :c:type:`v4l2_hsv_encoding`. - This information supplements the ``colorspace`` and must be set by - the driver for capture streams and by the application for output - streams, see :ref:`colorspaces`. + See struct :c:type:`v4l2_pix_format`. * - } - * - __u8 - ``quantization`` - Quantization range, from enum :c:type:`v4l2_quantization`. - This information supplements the ``colorspace`` and must be set by - the driver for capture streams and by the application for output - streams, see :ref:`colorspaces`. + See struct :c:type:`v4l2_pix_format`. * - __u8 - ``xfer_func`` - Transfer function, from enum :c:type:`v4l2_xfer_func`. - This information supplements the ``colorspace`` and must be set by - the driver for capture streams and by the application for output - streams, see :ref:`colorspaces`. + See struct :c:type:`v4l2_pix_format`. * - __u8 - ``reserved[7]`` - Reserved for future extensions. Should be zeroed by drivers and diff --git a/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst b/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst index 759420a872d6..9c423ffe02f9 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst @@ -1,17 +1,10 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later ****************************** Single-planar format structure ****************************** -.. tabularcolumns:: |p{4.0cm}|p{2.5cm}|p{11.0cm}| +.. tabularcolumns:: |p{4.0cm}|p{2.6cm}|p{10.7cm}| .. c:type:: v4l2_pix_format @@ -44,6 +37,11 @@ Single-planar format structure inside the stream, when fed to a stateful mem2mem decoder, the fields may be zero to rely on the decoder to detect the right values. For more details see :ref:`decoder` and format descriptions. + + For compressed formats on the CAPTURE side of a stateful mem2mem + encoder, the fields must be zero, since the coded size is expected to + be calculated internally by the encoder itself, based on the OUTPUT + side. For more details see :ref:`encoder` and format descriptions. * - __u32 - ``pixelformat`` - The pixel format or type of compression, set by the application. @@ -111,7 +109,14 @@ Single-planar format structure - Image colorspace, from enum :c:type:`v4l2_colorspace`. This information supplements the ``pixelformat`` and must be set by the driver for capture streams and by the application for - output streams, see :ref:`colorspaces`. + output streams, see :ref:`colorspaces`. If the application sets the + flag ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set + this field for a capture stream to request a specific colorspace + for the captured image data. If the driver cannot handle requested + conversion, it will return another supported colorspace. + The driver indicates that colorspace conversion is supported by setting + the flag V4L2_FMT_FLAG_CSC_COLORSPACE in the corresponding struct + :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`. * - __u32 - ``priv`` - This field indicates whether the remaining fields of the @@ -148,13 +153,29 @@ Single-planar format structure - Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`. This information supplements the ``colorspace`` and must be set by the driver for capture streams and by the application for output - streams, see :ref:`colorspaces`. + streams, see :ref:`colorspaces`. If the application sets the + flag ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set + this field for a capture stream to request a specific Y'CbCr encoding + for the captured image data. If the driver cannot handle requested + conversion, it will return another supported encoding. + This field is ignored for HSV pixelformats. The driver indicates that + ycbcr_enc conversion is supported by setting the flag + V4L2_FMT_FLAG_CSC_YCBCR_ENC in the corresponding struct + :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`. * - __u32 - ``hsv_enc`` - HSV encoding, from enum :c:type:`v4l2_hsv_encoding`. This information supplements the ``colorspace`` and must be set by the driver for capture streams and by the application for output - streams, see :ref:`colorspaces`. + streams, see :ref:`colorspaces`. If the application sets the flag + ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set this + field for a capture stream to request a specific HSV encoding for the + captured image data. If the driver cannot handle requested + conversion, it will return another supported encoding. + This field is ignored for non-HSV pixelformats. The driver indicates + that hsv_enc conversion is supported by setting the flag + V4L2_FMT_FLAG_CSC_HSV_ENC in the corresponding struct + :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`. * - } - * - __u32 @@ -162,10 +183,58 @@ Single-planar format structure - Quantization range, from enum :c:type:`v4l2_quantization`. This information supplements the ``colorspace`` and must be set by the driver for capture streams and by the application for output - streams, see :ref:`colorspaces`. + streams, see :ref:`colorspaces`. If the application sets the flag + ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set + this field for a capture stream to request a specific quantization + range for the captured image data. If the driver cannot handle requested + conversion, it will return another supported quantization. + The driver indicates that quantization conversion is supported by setting + the flag V4L2_FMT_FLAG_CSC_QUANTIZATION in the corresponding struct + :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`. * - __u32 - ``xfer_func`` - Transfer function, from enum :c:type:`v4l2_xfer_func`. This information supplements the ``colorspace`` and must be set by the driver for capture streams and by the application for output - streams, see :ref:`colorspaces`. + streams, see :ref:`colorspaces`. If the application sets the flag + ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set + this field for a capture stream to request a specific transfer function + for the captured image data. If the driver cannot handle requested + conversion, it will return another supported transfer function. + The driver indicates that xfer_func conversion is supported by setting + the flag V4L2_FMT_FLAG_CSC_XFER_FUNC in the corresponding struct + :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`. + +.. tabularcolumns:: |p{6.8cm}|p{2.3cm}|p{8.2cm}| + +.. _format-flags: + +.. flat-table:: Format Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - ``V4L2_PIX_FMT_FLAG_PREMUL_ALPHA`` + - 0x00000001 + - The color values are premultiplied by the alpha channel value. For + example, if a light blue pixel with 50% transparency was described + by RGBA values (128, 192, 255, 128), the same pixel described with + premultiplied colors would be described by RGBA values (64, 96, + 128, 128) + * .. _`v4l2-pix-fmt-flag-set-csc`: + + - ``V4L2_PIX_FMT_FLAG_SET_CSC`` + - 0x00000002 + - Set by the application. It is only used for capture and is + ignored for output streams. If set, then request the device to do + colorspace conversion from the received colorspace to the requested + colorspace values. If the colorimetry field (``colorspace``, ``xfer_func``, + ``ycbcr_enc``, ``hsv_enc`` or ``quantization``) is set to ``*_DEFAULT``, + then that colorimetry setting will remain unchanged from what was received. + So in order to change the quantization, only the ``quantization`` field shall + be set to non default value (``V4L2_QUANTIZATION_FULL_RANGE`` or + ``V4L2_QUANTIZATION_LIM_RANGE``) and all other colorimetry fields shall + be set to ``*_DEFAULT``. + + To check which conversions are supported by the hardware for the current + pixel format, see :ref:`fmtdesc-flags`. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst b/Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst deleted file mode 100644 index 6cd574e78e4c..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst +++ /dev/null @@ -1,115 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-VYUY: - -************************** -V4L2_PIX_FMT_VYUY ('VYUY') -************************** - - -Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in -memory - - -Description -=========== - -In this format each four bytes is two pixels. Each four bytes is two -Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr -belong to both pixels. As you can see, the Cr and Cb components have -half the horizontal resolution of the Y component. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Cr\ :sub:`00` - - Y'\ :sub:`00` - - Cb\ :sub:`00` - - Y'\ :sub:`01` - - Cr\ :sub:`01` - - Y'\ :sub:`02` - - Cb\ :sub:`01` - - Y'\ :sub:`03` - * - start + 8: - - Cr\ :sub:`10` - - Y'\ :sub:`10` - - Cb\ :sub:`10` - - Y'\ :sub:`11` - - Cr\ :sub:`11` - - Y'\ :sub:`12` - - Cb\ :sub:`11` - - Y'\ :sub:`13` - * - start + 16: - - Cr\ :sub:`20` - - Y'\ :sub:`20` - - Cb\ :sub:`20` - - Y'\ :sub:`21` - - Cr\ :sub:`21` - - Y'\ :sub:`22` - - Cb\ :sub:`21` - - Y'\ :sub:`23` - * - start + 24: - - Cr\ :sub:`30` - - Y'\ :sub:`30` - - Cb\ :sub:`30` - - Y'\ :sub:`31` - - Cr\ :sub:`31` - - Y'\ :sub:`32` - - Cb\ :sub:`31` - - Y'\ :sub:`33` - - -**Color Sample Location:** - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - - - 2 - - 3 - * - 0 - - Y - - C - - Y - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y10.rst b/Documentation/userspace-api/media/v4l/pixfmt-y10.rst deleted file mode 100644 index dfb352ae6784..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y10.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-Y10: - -************************* -V4L2_PIX_FMT_Y10 ('Y10 ') -************************* - - -Grey-scale image - - -Description -=========== - -This is a grey-scale image with a depth of 10 bits per pixel. Pixels are -stored in 16-bit words with unused high bits padded with 0. The least -significant byte is stored at lower memory addresses (little-endian). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00low` - - Y'\ :sub:`00high` - - Y'\ :sub:`01low` - - Y'\ :sub:`01high` - - Y'\ :sub:`02low` - - Y'\ :sub:`02high` - - Y'\ :sub:`03low` - - Y'\ :sub:`03high` - * - start + 8: - - Y'\ :sub:`10low` - - Y'\ :sub:`10high` - - Y'\ :sub:`11low` - - Y'\ :sub:`11high` - - Y'\ :sub:`12low` - - Y'\ :sub:`12high` - - Y'\ :sub:`13low` - - Y'\ :sub:`13high` - * - start + 16: - - Y'\ :sub:`20low` - - Y'\ :sub:`20high` - - Y'\ :sub:`21low` - - Y'\ :sub:`21high` - - Y'\ :sub:`22low` - - Y'\ :sub:`22high` - - Y'\ :sub:`23low` - - Y'\ :sub:`23high` - * - start + 24: - - Y'\ :sub:`30low` - - Y'\ :sub:`30high` - - Y'\ :sub:`31low` - - Y'\ :sub:`31high` - - Y'\ :sub:`32low` - - Y'\ :sub:`32high` - - Y'\ :sub:`33low` - - Y'\ :sub:`33high` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y10b.rst b/Documentation/userspace-api/media/v4l/pixfmt-y10b.rst deleted file mode 100644 index b5d89d6d5c52..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y10b.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-Y10BPACK: - -****************************** -V4L2_PIX_FMT_Y10BPACK ('Y10B') -****************************** - -Grey-scale image as a bit-packed array - - -Description -=========== - -This is a packed grey-scale image format with a depth of 10 bits per -pixel. Pixels are stored in a bit-packed array of 10bit bits per pixel, -with no padding between them and with the most significant bits coming -first from the left. - -**Bit-packed representation.** - -pixels cross the byte boundary and have a ratio of 5 bytes for each 4 -pixels. - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - Y'\ :sub:`00[9:2]` - - Y'\ :sub:`00[1:0]`\ Y'\ :sub:`01[9:4]` - - Y'\ :sub:`01[3:0]`\ Y'\ :sub:`02[9:6]` - - Y'\ :sub:`02[5:0]`\ Y'\ :sub:`03[9:8]` - - Y'\ :sub:`03[7:0]` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y10p.rst b/Documentation/userspace-api/media/v4l/pixfmt-y10p.rst deleted file mode 100644 index ffb6e1631b78..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y10p.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-Y10P: - -****************************** -V4L2_PIX_FMT_Y10P ('Y10P') -****************************** - -Grey-scale image as a MIPI RAW10 packed array - - -Description -=========== - -This is a packed grey-scale image format with a depth of 10 bits per -pixel. Every four consecutive pixels are packed into 5 bytes. Each of -the first 4 bytes contain the 8 high order bits of the pixels, and -the 5th byte contains the 2 least significants bits of each pixel, -in the same order. - -**Bit-packed representation.** - -.. raw:: latex - - \small - -.. tabularcolumns:: |p{1.2cm}||p{1.2cm}||p{1.2cm}||p{1.2cm}|p{3.2cm}|p{3.2cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 8 8 8 8 64 - - * - Y'\ :sub:`00[9:2]` - - Y'\ :sub:`01[9:2]` - - Y'\ :sub:`02[9:2]` - - Y'\ :sub:`03[9:2]` - - Y'\ :sub:`03[1:0]`\ (bits 7--6) Y'\ :sub:`02[1:0]`\ (bits 5--4) - Y'\ :sub:`01[1:0]`\ (bits 3--2) Y'\ :sub:`00[1:0]`\ (bits 1--0) - -.. raw:: latex - - \normalsize diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y12.rst b/Documentation/userspace-api/media/v4l/pixfmt-y12.rst deleted file mode 100644 index 4226c49232de..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y12.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-Y12: - -************************* -V4L2_PIX_FMT_Y12 ('Y12 ') -************************* - - -Grey-scale image - - -Description -=========== - -This is a grey-scale image with a depth of 12 bits per pixel. Pixels are -stored in 16-bit words with unused high bits padded with 0. The least -significant byte is stored at lower memory addresses (little-endian). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00low` - - Y'\ :sub:`00high` - - Y'\ :sub:`01low` - - Y'\ :sub:`01high` - - Y'\ :sub:`02low` - - Y'\ :sub:`02high` - - Y'\ :sub:`03low` - - Y'\ :sub:`03high` - * - start + 8: - - Y'\ :sub:`10low` - - Y'\ :sub:`10high` - - Y'\ :sub:`11low` - - Y'\ :sub:`11high` - - Y'\ :sub:`12low` - - Y'\ :sub:`12high` - - Y'\ :sub:`13low` - - Y'\ :sub:`13high` - * - start + 16: - - Y'\ :sub:`20low` - - Y'\ :sub:`20high` - - Y'\ :sub:`21low` - - Y'\ :sub:`21high` - - Y'\ :sub:`22low` - - Y'\ :sub:`22high` - - Y'\ :sub:`23low` - - Y'\ :sub:`23high` - * - start + 24: - - Y'\ :sub:`30low` - - Y'\ :sub:`30high` - - Y'\ :sub:`31low` - - Y'\ :sub:`31high` - - Y'\ :sub:`32low` - - Y'\ :sub:`32high` - - Y'\ :sub:`33low` - - Y'\ :sub:`33high` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y12i.rst b/Documentation/userspace-api/media/v4l/pixfmt-y12i.rst index b4752754337b..d9b539381d74 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-y12i.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-y12i.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-Y12I: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y14.rst b/Documentation/userspace-api/media/v4l/pixfmt-y14.rst deleted file mode 100644 index d702b6549160..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y14.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-Y14: - -************************* -V4L2_PIX_FMT_Y14 ('Y14 ') -************************* - - -Grey-scale image - - -Description -=========== - -This is a grey-scale image with a depth of 14 bits per pixel. Pixels are -stored in 16-bit words with unused high bits padded with 0. The least -significant byte is stored at lower memory addresses (little-endian). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00low` - - Y'\ :sub:`00high` - - Y'\ :sub:`01low` - - Y'\ :sub:`01high` - - Y'\ :sub:`02low` - - Y'\ :sub:`02high` - - Y'\ :sub:`03low` - - Y'\ :sub:`03high` - * - start + 8: - - Y'\ :sub:`10low` - - Y'\ :sub:`10high` - - Y'\ :sub:`11low` - - Y'\ :sub:`11high` - - Y'\ :sub:`12low` - - Y'\ :sub:`12high` - - Y'\ :sub:`13low` - - Y'\ :sub:`13high` - * - start + 16: - - Y'\ :sub:`20low` - - Y'\ :sub:`20high` - - Y'\ :sub:`21low` - - Y'\ :sub:`21high` - - Y'\ :sub:`22low` - - Y'\ :sub:`22high` - - Y'\ :sub:`23low` - - Y'\ :sub:`23high` - * - start + 24: - - Y'\ :sub:`30low` - - Y'\ :sub:`30high` - - Y'\ :sub:`31low` - - Y'\ :sub:`31high` - - Y'\ :sub:`32low` - - Y'\ :sub:`32high` - - Y'\ :sub:`33low` - - Y'\ :sub:`33high` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y16-be.rst b/Documentation/userspace-api/media/v4l/pixfmt-y16-be.rst deleted file mode 100644 index f4eda7b95b51..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y16-be.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-Y16-BE: - -**************************************** -V4L2_PIX_FMT_Y16_BE ('Y16 ' | (1 << 31)) -**************************************** - - -Grey-scale image - - -Description -=========== - -This is a grey-scale image with a depth of 16 bits per pixel. The most -significant byte is stored at lower memory addresses (big-endian). - -.. note:: - - The actual sampling precision may be lower than 16 bits, for - example 10 bits per pixel with values in range 0 to 1023. - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00high` - - Y'\ :sub:`00low` - - Y'\ :sub:`01high` - - Y'\ :sub:`01low` - - Y'\ :sub:`02high` - - Y'\ :sub:`02low` - - Y'\ :sub:`03high` - - Y'\ :sub:`03low` - * - start + 8: - - Y'\ :sub:`10high` - - Y'\ :sub:`10low` - - Y'\ :sub:`11high` - - Y'\ :sub:`11low` - - Y'\ :sub:`12high` - - Y'\ :sub:`12low` - - Y'\ :sub:`13high` - - Y'\ :sub:`13low` - * - start + 16: - - Y'\ :sub:`20high` - - Y'\ :sub:`20low` - - Y'\ :sub:`21high` - - Y'\ :sub:`21low` - - Y'\ :sub:`22high` - - Y'\ :sub:`22low` - - Y'\ :sub:`23high` - - Y'\ :sub:`23low` - * - start + 24: - - Y'\ :sub:`30high` - - Y'\ :sub:`30low` - - Y'\ :sub:`31high` - - Y'\ :sub:`31low` - - Y'\ :sub:`32high` - - Y'\ :sub:`32low` - - Y'\ :sub:`33high` - - Y'\ :sub:`33low` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y16.rst b/Documentation/userspace-api/media/v4l/pixfmt-y16.rst deleted file mode 100644 index a092b0a5ff12..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y16.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-Y16: - -************************* -V4L2_PIX_FMT_Y16 ('Y16 ') -************************* - - -Grey-scale image - - -Description -=========== - -This is a grey-scale image with a depth of 16 bits per pixel. The least -significant byte is stored at lower memory addresses (little-endian). - -.. note:: - - The actual sampling precision may be lower than 16 bits, for - example 10 bits per pixel with values in range 0 to 1023. - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00low` - - Y'\ :sub:`00high` - - Y'\ :sub:`01low` - - Y'\ :sub:`01high` - - Y'\ :sub:`02low` - - Y'\ :sub:`02high` - - Y'\ :sub:`03low` - - Y'\ :sub:`03high` - * - start + 8: - - Y'\ :sub:`10low` - - Y'\ :sub:`10high` - - Y'\ :sub:`11low` - - Y'\ :sub:`11high` - - Y'\ :sub:`12low` - - Y'\ :sub:`12high` - - Y'\ :sub:`13low` - - Y'\ :sub:`13high` - * - start + 16: - - Y'\ :sub:`20low` - - Y'\ :sub:`20high` - - Y'\ :sub:`21low` - - Y'\ :sub:`21high` - - Y'\ :sub:`22low` - - Y'\ :sub:`22high` - - Y'\ :sub:`23low` - - Y'\ :sub:`23high` - * - start + 24: - - Y'\ :sub:`30low` - - Y'\ :sub:`30high` - - Y'\ :sub:`31low` - - Y'\ :sub:`31high` - - Y'\ :sub:`32low` - - Y'\ :sub:`32high` - - Y'\ :sub:`33low` - - Y'\ :sub:`33high` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y16i.rst b/Documentation/userspace-api/media/v4l/pixfmt-y16i.rst new file mode 100644 index 000000000000..74ba9e910a38 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/pixfmt-y16i.rst @@ -0,0 +1,73 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _V4L2-PIX-FMT-Y16I: + +************************** +V4L2_PIX_FMT_Y16I ('Y16I') +************************** + +Interleaved grey-scale image, e.g. from a stereo-pair + + +Description +=========== + +This is a grey-scale image with a depth of 16 bits per pixel, but with pixels +from 2 sources interleaved and unpacked. Each pixel is stored in a 16-bit word +in the little-endian order. The first pixel is from the left source. + +**Pixel unpacked representation.** +Left/Right pixels 16-bit unpacked - 16-bit for each interleaved pixel. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - Y'\ :sub:`0L[7:0]` + - Y'\ :sub:`0L[15:8]` + - Y'\ :sub:`0R[7:0]` + - Y'\ :sub:`0R[15:8]` + +**Byte Order.** +Each cell is one byte. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00Llow` + - Y'\ :sub:`00Lhigh` + - Y'\ :sub:`00Rlow` + - Y'\ :sub:`00Rhigh` + - Y'\ :sub:`01Llow` + - Y'\ :sub:`01Lhigh` + - Y'\ :sub:`01Rlow` + - Y'\ :sub:`01Rhigh` + * - start + 8: + - Y'\ :sub:`10Llow` + - Y'\ :sub:`10Lhigh` + - Y'\ :sub:`10Rlow` + - Y'\ :sub:`10Rhigh` + - Y'\ :sub:`11Llow` + - Y'\ :sub:`11Lhigh` + - Y'\ :sub:`11Rlow` + - Y'\ :sub:`11Rhigh` + * - start + 16: + - Y'\ :sub:`20Llow` + - Y'\ :sub:`20Lhigh` + - Y'\ :sub:`20Rlow` + - Y'\ :sub:`20Rhigh` + - Y'\ :sub:`21Llow` + - Y'\ :sub:`21Lhigh` + - Y'\ :sub:`21Rlow` + - Y'\ :sub:`21Rhigh` + * - start + 24: + - Y'\ :sub:`30Llow` + - Y'\ :sub:`30Lhigh` + - Y'\ :sub:`30Rlow` + - Y'\ :sub:`30Rhigh` + - Y'\ :sub:`31Llow` + - Y'\ :sub:`31Lhigh` + - Y'\ :sub:`31Rlow` + - Y'\ :sub:`31Rhigh` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y41p.rst b/Documentation/userspace-api/media/v4l/pixfmt-y41p.rst deleted file mode 100644 index 211afd7593cc..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y41p.rst +++ /dev/null @@ -1,158 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-Y41P: - -************************** -V4L2_PIX_FMT_Y41P ('Y41P') -************************** - - -Format with ¼ horizontal chroma resolution, also known as YUV 4:1:1 - - -Description -=========== - -In this format each 12 bytes is eight pixels. In the twelve bytes are -two CbCr pairs and eight Y's. The first CbCr pair goes with the first -four Y's, and the second CbCr pair goes with the other four Y's. The Cb -and Cr components have one fourth the horizontal resolution of the Y -component. - -Do not confuse this format with -:ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>`. Y41P is derived -from "YUV 4:1:1 *packed*", while YUV411P stands for "YUV 4:1:1 -*planar*". - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Cb\ :sub:`00` - - Y'\ :sub:`00` - - Cr\ :sub:`00` - - Y'\ :sub:`01` - - Cb\ :sub:`01` - - Y'\ :sub:`02` - - Cr\ :sub:`01` - - Y'\ :sub:`03` - - Y'\ :sub:`04` - - Y'\ :sub:`05` - - Y'\ :sub:`06` - - Y'\ :sub:`07` - * - start + 12: - - Cb\ :sub:`10` - - Y'\ :sub:`10` - - Cr\ :sub:`10` - - Y'\ :sub:`11` - - Cb\ :sub:`11` - - Y'\ :sub:`12` - - Cr\ :sub:`11` - - Y'\ :sub:`13` - - Y'\ :sub:`14` - - Y'\ :sub:`15` - - Y'\ :sub:`16` - - Y'\ :sub:`17` - * - start + 24: - - Cb\ :sub:`20` - - Y'\ :sub:`20` - - Cr\ :sub:`20` - - Y'\ :sub:`21` - - Cb\ :sub:`21` - - Y'\ :sub:`22` - - Cr\ :sub:`21` - - Y'\ :sub:`23` - - Y'\ :sub:`24` - - Y'\ :sub:`25` - - Y'\ :sub:`26` - - Y'\ :sub:`27` - * - start + 36: - - Cb\ :sub:`30` - - Y'\ :sub:`30` - - Cr\ :sub:`30` - - Y'\ :sub:`31` - - Cb\ :sub:`31` - - Y'\ :sub:`32` - - Cr\ :sub:`31` - - Y'\ :sub:`33` - - Y'\ :sub:`34` - - Y'\ :sub:`35` - - Y'\ :sub:`36` - - Y'\ :sub:`37` - - -**Color Sample Location:** - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - 1 - - - - 2 - - 3 - - 4 - - 5 - - - - 6 - - 7 - * - 0 - - Y - - Y - - C - - Y - - Y - - Y - - Y - - C - - Y - - Y - * - 1 - - Y - - Y - - C - - Y - - Y - - Y - - Y - - C - - Y - - Y - * - 2 - - Y - - Y - - C - - Y - - Y - - Y - - Y - - C - - Y - - Y - * - 3 - - Y - - Y - - C - - Y - - Y - - Y - - Y - - C - - Y - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y8i.rst b/Documentation/userspace-api/media/v4l/pixfmt-y8i.rst index 4248c6f735b7..770ed4749c14 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-y8i.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-y8i.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-Y8I: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst new file mode 100644 index 000000000000..74df19be91f6 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst @@ -0,0 +1,215 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _yuv-luma-only: + +***************** +Luma-Only Formats +***************** + +This family of formats only store the luma component of a Y'CbCr image. They +are often referred to as greyscale formats. + +.. note:: + + - In all the tables that follow, bit 7 is the most significant bit in a byte. + - Formats are described with the minimum number of pixels needed to create a + byte-aligned repeating pattern. `...` indicates repetition of the pattern. + - Y'\ :sub:`x`\ [9:2] denotes bits 9 to 2 of the Y' value for pixel at column + `x`. + - `0` denotes padding bits set to 0. + + +.. raw:: latex + + \tiny + +.. tabularcolumns:: |p{3.6cm}|p{2.4cm}|p{1.3cm}|p{1.3cm}|p{1.3cm}|p{1.3cm}|p{1.3cm}|p{1.3cm}|p{1.3cm}| + +.. flat-table:: Luma-Only Image Formats + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Byte 0 + - Byte 1 + - Byte 2 + - Byte 3 + - Byte 4 + - Byte 5 + - Byte 6 + + * .. _V4L2-PIX-FMT-GREY: + + - ``V4L2_PIX_FMT_GREY`` + - 'GREY' + + - Y'\ :sub:`0`\ [7:0] + - ... + - ... + - ... + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-IPU3-Y10: + + - ``V4L2_PIX_FMT_IPU3_Y10`` + - 'ip3y' + + - Y'\ :sub:`0`\ [7:0] + - Y'\ :sub:`1`\ [5:0] Y'\ :sub:`0`\ [9:8] + - Y'\ :sub:`2`\ [3:0] Y'\ :sub:`1`\ [9:6] + - Y'\ :sub:`3`\ [1:0] Y'\ :sub:`2`\ [9:4] + - Y'\ :sub:`3`\ [9:2] + - ... + - ... + + * .. _V4L2-PIX-FMT-Y10: + + - ``V4L2_PIX_FMT_Y10`` + - 'Y10 ' + + - Y'\ :sub:`0`\ [7:0] + - `000000` Y'\ :sub:`0`\ [9:8] + - ... + - ... + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-Y10BPACK: + + - ``V4L2_PIX_FMT_Y10BPACK`` + - 'Y10B' + + - Y'\ :sub:`0`\ [9:2] + - Y'\ :sub:`0`\ [1:0] Y'\ :sub:`1`\ [9:4] + - Y'\ :sub:`1`\ [3:0] Y'\ :sub:`2`\ [9:6] + - Y'\ :sub:`2`\ [5:0] Y'\ :sub:`3`\ [9:8] + - Y'\ :sub:`3`\ [7:0] + - ... + - ... + + * .. _V4L2-PIX-FMT-Y10P: + + - ``V4L2_PIX_FMT_Y10P`` + - 'Y10P' + + - Y'\ :sub:`0`\ [9:2] + - Y'\ :sub:`1`\ [9:2] + - Y'\ :sub:`2`\ [9:2] + - Y'\ :sub:`3`\ [9:2] + - Y'\ :sub:`3`\ [1:0] Y'\ :sub:`2`\ [1:0] Y'\ :sub:`1`\ [1:0] Y'\ :sub:`0`\ [1:0] + - ... + - ... + + * .. _V4L2-PIX-FMT-Y12: + + - ``V4L2_PIX_FMT_Y12`` + - 'Y12 ' + + - Y'\ :sub:`0`\ [7:0] + - `0000` Y'\ :sub:`0`\ [11:8] + - ... + - ... + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-Y012: + + - ``V4L2_PIX_FMT_Y012`` + - 'Y012' + + - Y'\ :sub:`0`\ [3:0] `0000` + - Y'\ :sub:`0`\ [11:4] + - ... + - ... + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-Y12P: + + - ``V4L2_PIX_FMT_Y12P`` + - 'Y12P' + + - Y'\ :sub:`0`\ [11:4] + - Y'\ :sub:`1`\ [11:4] + - Y'\ :sub:`1`\ [3:0] Y'\ :sub:`0`\ [3:0] + - ... + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-Y14: + + - ``V4L2_PIX_FMT_Y14`` + - 'Y14 ' + + - Y'\ :sub:`0`\ [7:0] + - `00` Y'\ :sub:`0`\ [13:8] + - ... + - ... + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-Y14P: + + - ``V4L2_PIX_FMT_Y14P`` + - 'Y14P' + + - Y'\ :sub:`0`\ [13:6] + - Y'\ :sub:`1`\ [13:6] + - Y'\ :sub:`2`\ [13:6] + - Y'\ :sub:`3`\ [13:6] + - Y'\ :sub:`1`\ [1:0] Y'\ :sub:`0`\ [5:0] + - Y'\ :sub:`2`\ [3:0] Y'\ :sub:`1`\ [5:2] + - Y'\ :sub:`3`\ [5:0] Y'\ :sub:`2`\ [5:4] + + * .. _V4L2-PIX-FMT-Y16: + + - ``V4L2_PIX_FMT_Y16`` + - 'Y16 ' + + - Y'\ :sub:`0`\ [7:0] + - Y'\ :sub:`0`\ [15:8] + - ... + - ... + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-Y16-BE: + + - ``V4L2_PIX_FMT_Y16_BE`` + - 'Y16 ' | (1U << 31) + + - Y'\ :sub:`0`\ [15:8] + - Y'\ :sub:`0`\ [7:0] + - ... + - ... + - ... + - ... + - ... + +.. raw:: latex + + \normalsize + +.. note:: + + For the Y16 and Y16_BE formats, the actual sampling precision may be lower + than 16 bits. For example, 10 bits per pixel uses values in the range 0 to + 1023. For the IPU3_Y10 format 25 pixels are packed into 32 bytes, which + leaves the 6 most significant bits of the last byte padded with 0. + + For Y012 and Y12 formats, Y012 places its data in the 12 high bits, with + padding zeros in the 4 low bits, in contrast to the Y12 format, which has + its padding located in the most significant bits of the 16 bit word. + + The 'P' variations of the Y10, Y12 and Y14 formats are packed according to + the RAW10, RAW12 and RAW14 packing scheme as defined by the MIPI CSI-2 + specification. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst new file mode 100644 index 000000000000..6e4f399f1f88 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst @@ -0,0 +1,1455 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. planar-yuv: + +****************** +Planar YUV formats +****************** + +Planar formats split luma and chroma data in separate memory regions. They +exist in two variants: + +- Semi-planar formats use two planes. The first plane is the luma plane and + stores the Y components. The second plane is the chroma plane and stores the + Cb and Cr components interleaved. + +- Fully planar formats use three planes to store the Y, Cb and Cr components + separately. + +Within a plane, components are stored in pixel order, which may be linear or +tiled. Padding may be supported at the end of the lines, and the line stride of +the chroma planes may be constrained by the line stride of the luma plane. + +Some planar formats allow planes to be placed in independent memory locations. +They are identified by an 'M' suffix in their name (such as in +``V4L2_PIX_FMT_NV12M``). Those formats are intended to be used only in drivers +and applications that support the multi-planar API, described in +:ref:`planar-apis`. Unless explicitly documented as supporting non-contiguous +planes, formats require the planes to follow each other immediately in memory. + + +Semi-Planar YUV Formats +======================= + +These formats are commonly referred to as NV formats (NV12, NV16, ...). They +use two planes, and store the luma components in the first plane and the chroma +components in the second plane. The Cb and Cr components are interleaved in the +chroma plane, with Cb and Cr always stored in pairs. The chroma order is +exposed as different formats. + +For memory contiguous formats, the number of padding pixels at the end of the +chroma lines is identical to the padding of the luma lines. Without horizontal +subsampling, the chroma line stride (in bytes) is thus equal to twice the luma +line stride. With horizontal subsampling by 2, the chroma line stride is equal +to the luma line stride. Vertical subsampling doesn't affect the line stride. + +For non-contiguous formats, no constraints are enforced by the format on the +relationship between the luma and chroma line padding and stride. + +All components are stored with the same number of bits per component. + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{5.2cm}|p{1.0cm}|p{1.5cm}|p{1.9cm}|p{1.2cm}|p{1.8cm}|p{2.7cm}| + +.. flat-table:: Overview of Semi-Planar YUV Formats + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Bits per component + - Subsampling + - Chroma order [1]_ + - Contiguous [2]_ + - Tiling [3]_ + * - V4L2_PIX_FMT_NV12 + - 'NV12' + - 8 + - 4:2:0 + - Cb, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_NV21 + - 'NV21' + - 8 + - 4:2:0 + - Cr, Cb + - Yes + - Linear + * - V4L2_PIX_FMT_NV12M + - 'NM12' + - 8 + - 4:2:0 + - Cb, Cr + - No + - Linear + * - V4L2_PIX_FMT_NV21M + - 'NM21' + - 8 + - 4:2:0 + - Cr, Cb + - No + - Linear + * - V4L2_PIX_FMT_NV12MT + - 'TM12' + - 8 + - 4:2:0 + - Cb, Cr + - No + - 64x32 tiles + + Horizontal Z order + * - V4L2_PIX_FMT_NV12MT_16X16 + - 'VM12' + - 8 + - 4:2:2 + - Cb, Cr + - No + - 16x16 tiles + * - V4L2_PIX_FMT_P010 + - 'P010' + - 10 + - 4:2:0 + - Cb, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_P010_4L4 + - 'T010' + - 10 + - 4:2:0 + - Cb, Cr + - Yes + - 4x4 tiles + * - V4L2_PIX_FMT_P012 + - 'P012' + - 12 + - 4:2:0 + - Cb, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_P012M + - 'PM12' + - 12 + - 4:2:0 + - Cb, Cr + - No + - Linear + * - V4L2_PIX_FMT_NV15 + - 'NV15' + - 10 + - 4:2:0 + - Cb, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_NV15_4L4 + - 'VT15' + - 15 + - 4:2:0 + - Cb, Cr + - Yes + - 4x4 tiles + * - V4L2_PIX_FMT_MT2110T + - 'MT2T' + - 15 + - 4:2:0 + - Cb, Cr + - No + - 16x32 / 16x16 tiles tiled low bits + * - V4L2_PIX_FMT_MT2110R + - 'MT2R' + - 15 + - 4:2:0 + - Cb, Cr + - No + - 16x32 / 16x16 tiles raster low bits + * - V4L2_PIX_FMT_NV16 + - 'NV16' + - 8 + - 4:2:2 + - Cb, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_NV61 + - 'NV61' + - 8 + - 4:2:2 + - Cr, Cb + - Yes + - Linear + * - V4L2_PIX_FMT_NV16M + - 'NM16' + - 8 + - 4:2:2 + - Cb, Cr + - No + - Linear + * - V4L2_PIX_FMT_NV61M + - 'NM61' + - 8 + - 4:2:2 + - Cr, Cb + - No + - Linear + * - V4L2_PIX_FMT_NV20 + - 'NV20' + - 10 + - 4:2:2 + - Cb, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_NV24 + - 'NV24' + - 8 + - 4:4:4 + - Cb, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_NV42 + - 'NV42' + - 8 + - 4:4:4 + - Cr, Cb + - Yes + - Linear + +.. raw:: latex + + \normalsize + +.. [1] Order of chroma samples in the second plane +.. [2] Indicates if planes have to be contiguous in memory or can be + disjoint +.. [3] Macroblock size in pixels + + +**Color Sample Location:** +Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` +horizontally. + + +.. _V4L2-PIX-FMT-NV12: +.. _V4L2-PIX-FMT-NV21: +.. _V4L2-PIX-FMT-NV12M: +.. _V4L2-PIX-FMT-NV21M: +.. _V4L2-PIX-FMT-P010: + +NV12, NV21, NV12M and NV21M +--------------------------- + +Semi-planar YUV 4:2:0 formats. The chroma plane is subsampled by 2 in each +direction. Chroma lines contain half the number of pixels and the same number +of bytes as luma lines, and the chroma plane contains half the number of lines +of the luma plane. + +.. flat-table:: Sample 4x4 NV12 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + * - start + 20: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + +.. flat-table:: Sample 4x4 NV12M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + * - start1 + 4: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + + +.. _V4L2-PIX-FMT-NV15: + +NV15 +---- + +Semi-planar 10-bit YUV 4:2:0 format similar to NV12, using 10-bit components +with no padding between each component. A group of 4 components are stored over +5 bytes in little endian order. + +.. flat-table:: Sample 4x4 NV15 Image (1 byte per cell) + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00[7:0]` + - Y'\ :sub:`01[5:0]`\ Y'\ :sub:`00[9:8]` + - Y'\ :sub:`02[3:0]`\ Y'\ :sub:`01[9:6]` + - Y'\ :sub:`03[1:0]`\ Y'\ :sub:`02[9:4]` + - Y'\ :sub:`03[9:2]` + * - start + 5: + - Y'\ :sub:`10[7:0]` + - Y'\ :sub:`11[5:0]`\ Y'\ :sub:`10[9:8]` + - Y'\ :sub:`12[3:0]`\ Y'\ :sub:`11[9:6]` + - Y'\ :sub:`13[1:0]`\ Y'\ :sub:`12[9:4]` + - Y'\ :sub:`13[9:2]` + * - start + 10: + - Y'\ :sub:`20[7:0]` + - Y'\ :sub:`21[5:0]`\ Y'\ :sub:`20[9:8]` + - Y'\ :sub:`22[3:0]`\ Y'\ :sub:`21[9:6]` + - Y'\ :sub:`23[1:0]`\ Y'\ :sub:`22[9:4]` + - Y'\ :sub:`23[9:2]` + * - start + 15: + - Y'\ :sub:`30[7:0]` + - Y'\ :sub:`31[5:0]`\ Y'\ :sub:`30[9:8]` + - Y'\ :sub:`32[3:0]`\ Y'\ :sub:`31[9:6]` + - Y'\ :sub:`33[1:0]`\ Y'\ :sub:`32[9:4]` + - Y'\ :sub:`33[9:2]` + * - start + 20: + - Cb\ :sub:`00[7:0]` + - Cr\ :sub:`00[5:0]`\ Cb\ :sub:`00[9:8]` + - Cb\ :sub:`01[3:0]`\ Cr\ :sub:`00[9:6]` + - Cr\ :sub:`01[1:0]`\ Cb\ :sub:`01[9:4]` + - Cr\ :sub:`01[9:2]` + * - start + 25: + - Cb\ :sub:`10[7:0]` + - Cr\ :sub:`10[5:0]`\ Cb\ :sub:`10[9:8]` + - Cb\ :sub:`11[3:0]`\ Cr\ :sub:`10[9:6]` + - Cr\ :sub:`11[1:0]`\ Cb\ :sub:`11[9:4]` + - Cr\ :sub:`11[9:2]` + + +.. _V4L2-PIX-FMT-NV12MT: +.. _V4L2-PIX-FMT-NV12MT-16X16: +.. _V4L2-PIX-FMT-NV12-4L4: +.. _V4L2-PIX-FMT-NV12-16L16: +.. _V4L2-PIX-FMT-NV12-32L32: +.. _V4L2-PIX-FMT-NV12M-8L128: +.. _V4L2-PIX-FMT-NV12-8L128: +.. _V4L2-PIX-FMT-MM21: + +Tiled NV12 +---------- + +Semi-planar YUV 4:2:0 formats, using macroblock tiling. The chroma plane is +subsampled by 2 in each direction. Chroma lines contain half the number of +pixels and the same number of bytes as luma lines, and the chroma plane +contains half the number of lines of the luma plane. Each tile follows the +previous one linearly in memory (from left to right, top to bottom). + +``V4L2_PIX_FMT_NV12MT_16X16`` is similar to ``V4L2_PIX_FMT_NV12M`` but stores +pixels in 2D 16x16 tiles, and stores tiles linearly in memory. +The line stride and image height must be aligned to a multiple of 16. +The layouts of the luma and chroma planes are identical. + +``V4L2_PIX_FMT_NV12MT`` is similar to ``V4L2_PIX_FMT_NV12M`` but stores +pixels in 2D 64x32 tiles, and stores 2x2 groups of tiles in +Z-order in memory, alternating Z and mirrored Z shapes horizontally. +The line stride must be a multiple of 128 pixels to ensure an +integer number of Z shapes. The image height must be a multiple of 32 pixels. +If the vertical resolution is an odd number of tiles, the last row of +tiles is stored in linear order. The layouts of the luma and chroma +planes are identical. + +.. _nv12mt: + +.. kernel-figure:: nv12mt.svg + :alt: nv12mt.svg + :align: center + + V4L2_PIX_FMT_NV12MT macroblock Z shape memory layout + +.. _nv12mt_ex: + +.. kernel-figure:: nv12mt_example.svg + :alt: nv12mt_example.svg + :align: center + + Example V4L2_PIX_FMT_NV12MT memory layout of tiles + +``V4L2_PIX_FMT_NV12_4L4`` stores pixels in 4x4 tiles, and stores +tiles linearly in memory. The line stride and image height must be +aligned to a multiple of 4. The layouts of the luma and chroma planes are +identical. + +``V4L2_PIX_FMT_NV12_16L16`` stores pixels in 16x16 tiles, and stores +tiles linearly in memory. The line stride and image height must be +aligned to a multiple of 16. The layouts of the luma and chroma planes are +identical. + +``V4L2_PIX_FMT_NV12_32L32`` stores pixels in 32x32 tiles, and stores +tiles linearly in memory. The line stride and image height must be +aligned to a multiple of 32. The layouts of the luma and chroma planes are +identical. + +``V4L2_PIX_FMT_NV12M_8L128`` is similar to ``V4L2_PIX_FMT_NV12M`` but stores +pixels in 2D 8x128 tiles, and stores tiles linearly in memory. +The image height must be aligned to a multiple of 128. +The layouts of the luma and chroma planes are identical. + +``V4L2_PIX_FMT_NV12_8L128`` is similar to ``V4L2_PIX_FMT_NV12M_8L128`` but stores +two planes in one memory. + +``V4L2_PIX_FMT_MM21`` store luma pixel in 16x32 tiles, and chroma pixels +in 16x16 tiles. The line stride must be aligned to a multiple of 16 and the +image height must be aligned to a multiple of 32. The number of luma and chroma +tiles are identical, even though the tile size differ. The image is formed of +two non-contiguous planes. + + +.. _V4L2-PIX-FMT-NV15-4L4: +.. _V4L2-PIX-FMT-NV12M-10BE-8L128: +.. _V4L2-PIX-FMT-NV12-10BE-8L128: +.. _V4L2-PIX-FMT-MT2110T: +.. _V4L2-PIX-FMT-MT2110R: + +Tiled NV15 +---------- + +``V4L2_PIX_FMT_NV15_4L4`` Semi-planar 10-bit YUV 4:2:0 formats, using 4x4 tiling. +All components are packed without any padding between each other. +As a side-effect, each group of 4 components are stored over 5 bytes +(YYYY or UVUV = 4 * 10 bits = 40 bits = 5 bytes). + +``V4L2_PIX_FMT_NV12M_10BE_8L128`` is similar to ``V4L2_PIX_FMT_NV12M`` but stores +10 bits pixels in 2D 8x128 tiles, and stores tiles linearly in memory. +the data is arranged in big endian order. +The image height must be aligned to a multiple of 128. +The layouts of the luma and chroma planes are identical. +Note the tile size is 8bytes multiplied by 128 bytes, +it means that the low bits and high bits of one pixel may be in different tiles. +The 10 bit pixels are packed, so 5 bytes contain 4 10-bit pixels layout like +this (for luma): +byte 0: Y0(bits 9-2) +byte 1: Y0(bits 1-0) Y1(bits 9-4) +byte 2: Y1(bits 3-0) Y2(bits 9-6) +byte 3: Y2(bits 5-0) Y3(bits 9-8) +byte 4: Y3(bits 7-0) + +``V4L2_PIX_FMT_NV12_10BE_8L128`` is similar to ``V4L2_PIX_FMT_NV12M_10BE_8L128`` but stores +two planes in one memory. + +``V4L2_PIX_FMT_MT2110T`` is one of Mediatek packed 10bit YUV 4:2:0 formats. +It is fully packed 10bit 4:2:0 format like NV15 (15 bits per pixel), except +that the lower two bits data is stored in separate partitions. The format is +composed of 16x32 luma tiles, and 16x16 chroma tiles. Each tiles is 640 bytes +long, divided into 8 partitions of 80 bytes. The first 16 bytes of the +partition represent the 2 least significant bits of pixel data. The remaining +64 bytes represent the 8 most significant bits of pixel data. + +.. kernel-figure:: mt2110t.svg + :alt: mt2110t.svg + :align: center + + Layout of MT2110T Chroma Tile + +Filtering out the upper part of each partitions results in a valid +``V4L2_PIX_FMT_MM21`` frame. A partition is a sub-tile of size 16 x 4. The +lower two bits is said to be tiled since each bytes contains the lower two +bits of the column of for pixel matching the same index. The chroma tiles +only have 4 partitions. + +.. flat-table:: MT2110T LSB bits layout + :header-rows: 1 + :stub-columns: 1 + + * - + - start + 0: + - start + 1: + - . . . + - start\ +\ 15: + * - Bits 1:0 + - Y'\ :sub:`0:0` + - Y'\ :sub:`0:1` + - . . . + - Y'\ :sub:`0:15` + * - Bit 3:2 + - Y'\ :sub:`1:0` + - Y'\ :sub:`1:1` + - . . . + - Y'\ :sub:`1:15` + * - Bits 5:4 + - Y'\ :sub:`2:0` + - Y'\ :sub:`2:1` + - . . . + - Y'\ :sub:`2:15` + * - Bits 7:6 + - Y'\ :sub:`3:0` + - Y'\ :sub:`3:1` + - . . . + - Y'\ :sub:`3:15` + +``V4L2_PIX_FMT_MT2110R`` is identical to ``V4L2_PIX_FMT_MT2110T`` except that +the least significant two bits layout is in raster order. This means the first byte +contains 4 pixels of the first row, with 4 bytes per line. + +.. flat-table:: MT2110R LSB bits layout + :header-rows: 2 + :stub-columns: 1 + + * - + - :cspan:`3` Byte 0 + - ... + - :cspan:`3` Byte 3 + * - + - 7:6 + - 5:4 + - 3:2 + - 1:0 + - ... + - 7:6 + - 5:4 + - 3:2 + - 1:0 + * - start + 0: + - Y'\ :sub:`0:3` + - Y'\ :sub:`0:2` + - Y'\ :sub:`0:1` + - Y'\ :sub:`0:0` + - ... + - Y'\ :sub:`0:15` + - Y'\ :sub:`0:14` + - Y'\ :sub:`0:13` + - Y'\ :sub:`0:12` + * - start + 4: + - Y'\ :sub:`1:3` + - Y'\ :sub:`1:2` + - Y'\ :sub:`1:1` + - Y'\ :sub:`1:0` + - ... + - Y'\ :sub:`1:15` + - Y'\ :sub:`1:14` + - Y'\ :sub:`1:13` + - Y'\ :sub:`1:12` + * - start + 8: + - Y'\ :sub:`2:3` + - Y'\ :sub:`2:2` + - Y'\ :sub:`2:1` + - Y'\ :sub:`2:0` + - ... + - Y'\ :sub:`2:15` + - Y'\ :sub:`2:14` + - Y'\ :sub:`2:13` + - Y'\ :sub:`2:12` + * - start\ +\ 12: + - Y'\ :sub:`3:3` + - Y'\ :sub:`3:2` + - Y'\ :sub:`3:1` + - Y'\ :sub:`3:0` + - ... + - Y'\ :sub:`3:15` + - Y'\ :sub:`3:14` + - Y'\ :sub:`3:13` + - Y'\ :sub:`3:12` + + +.. _V4L2-PIX-FMT-NV16: +.. _V4L2-PIX-FMT-NV61: +.. _V4L2-PIX-FMT-NV16M: +.. _V4L2-PIX-FMT-NV61M: + +NV16, NV61, NV16M and NV61M +--------------------------- + +Semi-planar YUV 4:2:2 formats. The chroma plane is subsampled by 2 in the +horizontal direction. Chroma lines contain half the number of pixels and the +same number of bytes as luma lines, and the chroma plane contains the same +number of lines as the luma plane. + +.. flat-table:: Sample 4x4 NV16 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + * - start + 20: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + * - start + 24: + - Cb\ :sub:`20` + - Cr\ :sub:`20` + - Cb\ :sub:`21` + - Cr\ :sub:`21` + * - start + 28: + - Cb\ :sub:`30` + - Cr\ :sub:`30` + - Cb\ :sub:`31` + - Cr\ :sub:`31` + +.. flat-table:: Sample 4x4 NV16M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`02` + - Cr\ :sub:`02` + * - start1 + 4: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`12` + - Cr\ :sub:`12` + * - start1 + 8: + - Cb\ :sub:`20` + - Cr\ :sub:`20` + - Cb\ :sub:`22` + - Cr\ :sub:`22` + * - start1 + 12: + - Cb\ :sub:`30` + - Cr\ :sub:`30` + - Cb\ :sub:`32` + - Cr\ :sub:`32` + + +.. _V4L2-PIX-FMT-NV20: + +NV20 +---- + +Semi-planar 10-bit YUV 4:2:2 format similar to NV16, using 10-bit components +with no padding between each component. A group of 4 components are stored over +5 bytes in little endian order. + +.. flat-table:: Sample 4x4 NV20 Image (1 byte per cell) + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00[7:0]` + - Y'\ :sub:`01[5:0]`\ Y'\ :sub:`00[9:8]` + - Y'\ :sub:`02[3:0]`\ Y'\ :sub:`01[9:6]` + - Y'\ :sub:`03[1:0]`\ Y'\ :sub:`02[9:4]` + - Y'\ :sub:`03[9:2]` + * - start + 5: + - Y'\ :sub:`10[7:0]` + - Y'\ :sub:`11[5:0]`\ Y'\ :sub:`10[9:8]` + - Y'\ :sub:`12[3:0]`\ Y'\ :sub:`11[9:6]` + - Y'\ :sub:`13[1:0]`\ Y'\ :sub:`12[9:4]` + - Y'\ :sub:`13[9:2]` + * - start + 10: + - Y'\ :sub:`20[7:0]` + - Y'\ :sub:`21[5:0]`\ Y'\ :sub:`20[9:8]` + - Y'\ :sub:`22[3:0]`\ Y'\ :sub:`21[9:6]` + - Y'\ :sub:`23[1:0]`\ Y'\ :sub:`22[9:4]` + - Y'\ :sub:`23[9:2]` + * - start + 15: + - Y'\ :sub:`30[7:0]` + - Y'\ :sub:`31[5:0]`\ Y'\ :sub:`30[9:8]` + - Y'\ :sub:`32[3:0]`\ Y'\ :sub:`31[9:6]` + - Y'\ :sub:`33[1:0]`\ Y'\ :sub:`32[9:4]` + - Y'\ :sub:`33[9:2]` + * - start + 20: + - Cb\ :sub:`00[7:0]` + - Cr\ :sub:`00[5:0]`\ Cb\ :sub:`00[9:8]` + - Cb\ :sub:`01[3:0]`\ Cr\ :sub:`00[9:6]` + - Cr\ :sub:`01[1:0]`\ Cb\ :sub:`01[9:4]` + - Cr\ :sub:`01[9:2]` + * - start + 25: + - Cb\ :sub:`10[7:0]` + - Cr\ :sub:`10[5:0]`\ Cb\ :sub:`10[9:8]` + - Cb\ :sub:`11[3:0]`\ Cr\ :sub:`10[9:6]` + - Cr\ :sub:`11[1:0]`\ Cb\ :sub:`11[9:4]` + - Cr\ :sub:`11[9:2]` + * - start + 30: + - Cb\ :sub:`20[7:0]` + - Cr\ :sub:`20[5:0]`\ Cb\ :sub:`20[9:8]` + - Cb\ :sub:`21[3:0]`\ Cr\ :sub:`20[9:6]` + - Cr\ :sub:`21[1:0]`\ Cb\ :sub:`21[9:4]` + - Cr\ :sub:`21[9:2]` + * - start + 35: + - Cb\ :sub:`30[7:0]` + - Cr\ :sub:`30[5:0]`\ Cb\ :sub:`30[9:8]` + - Cb\ :sub:`31[3:0]`\ Cr\ :sub:`30[9:6]` + - Cr\ :sub:`31[1:0]`\ Cb\ :sub:`31[9:4]` + - Cr\ :sub:`31[9:2]` + + +.. _V4L2-PIX-FMT-NV24: +.. _V4L2-PIX-FMT-NV42: + +NV24 and NV42 +------------- + +Semi-planar YUV 4:4:4 formats. The chroma plane is not subsampled. +Chroma lines contain the same number of pixels and twice the +number of bytes as luma lines, and the chroma plane contains the same +number of lines as the luma plane. + +.. flat-table:: Sample 4x4 NV24 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + - Cb\ :sub:`02` + - Cr\ :sub:`02` + - Cb\ :sub:`03` + - Cr\ :sub:`03` + * - start + 24: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + - Cb\ :sub:`12` + - Cr\ :sub:`12` + - Cb\ :sub:`13` + - Cr\ :sub:`13` + * - start + 32: + - Cb\ :sub:`20` + - Cr\ :sub:`20` + - Cb\ :sub:`21` + - Cr\ :sub:`21` + - Cb\ :sub:`22` + - Cr\ :sub:`22` + - Cb\ :sub:`23` + - Cr\ :sub:`23` + * - start + 40: + - Cb\ :sub:`30` + - Cr\ :sub:`30` + - Cb\ :sub:`31` + - Cr\ :sub:`31` + - Cb\ :sub:`32` + - Cr\ :sub:`32` + - Cb\ :sub:`33` + - Cr\ :sub:`33` + +.. _V4L2_PIX_FMT_P010: +.. _V4L2-PIX-FMT-P010-4L4: + +P010 and tiled P010 +------------------- + +P010 is like NV12 with 10 bits per component, expanded to 16 bits. +Data in the 10 high bits, zeros in the 6 low bits, arranged in little endian order. + +.. flat-table:: Sample 4x4 P010 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 8: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 16: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 24: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 32: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + * - start + 40: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + +.. _V4L2-PIX-FMT-P012: +.. _V4L2-PIX-FMT-P012M: + +P012 and P012M +-------------- + +P012 is like NV12 with 12 bits per component, expanded to 16 bits. +Data in the 12 high bits, zeros in the 4 low bits, arranged in little endian order. + +.. flat-table:: Sample 4x4 P012 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 8: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 16: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 24: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 32: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + * - start + 40: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + +.. flat-table:: Sample 4x4 P012M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 8: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 16: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 24: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + * - start1 + 8: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + + +Fully Planar YUV Formats +======================== + +These formats store the Y, Cb and Cr components in three separate planes. The +luma plane comes first, and the order of the two chroma planes varies between +formats. The two chroma planes always use the same subsampling. + +For memory contiguous formats, the number of padding pixels at the end of the +chroma lines is identical to the padding of the luma lines. The chroma line +stride (in bytes) is thus equal to the luma line stride divided by the +horizontal subsampling factor. Vertical subsampling doesn't affect the line +stride. + +For non-contiguous formats, no constraints are enforced by the format on the +relationship between the luma and chroma line padding and stride. + +All components are stored with the same number of bits per component. + +``V4L2_PIX_FMT_P010_4L4`` stores pixels in 4x4 tiles, and stores tiles linearly +in memory. The line stride must be aligned to multiple of 8 and image height to +a multiple of 4. The layouts of the luma and chroma planes are identical. + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{5.0cm}|p{1.1cm}|p{1.5cm}|p{2.2cm}|p{1.2cm}|p{3.7cm}| + +.. flat-table:: Overview of Fully Planar YUV Formats + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Bits per component + - Subsampling + - Planes order [4]_ + - Contiguous [5]_ + + * - V4L2_PIX_FMT_YUV410 + - 'YUV9' + - 8 + - 4:1:0 + - Y, Cb, Cr + - Yes + * - V4L2_PIX_FMT_YVU410 + - 'YVU9' + - 8 + - 4:1:0 + - Y, Cr, Cb + - Yes + * - V4L2_PIX_FMT_YUV411P + - '411P' + - 8 + - 4:1:1 + - Y, Cb, Cr + - Yes + * - V4L2_PIX_FMT_YUV420M + - 'YM12' + - 8 + - 4:2:0 + - Y, Cb, Cr + - No + * - V4L2_PIX_FMT_YVU420M + - 'YM21' + - 8 + - 4:2:0 + - Y, Cr, Cb + - No + * - V4L2_PIX_FMT_YUV420 + - 'YU12' + - 8 + - 4:2:0 + - Y, Cb, Cr + - Yes + * - V4L2_PIX_FMT_YVU420 + - 'YV12' + - 8 + - 4:2:0 + - Y, Cr, Cb + - Yes + * - V4L2_PIX_FMT_YUV422P + - '422P' + - 8 + - 4:2:2 + - Y, Cb, Cr + - Yes + * - V4L2_PIX_FMT_YUV422M + - 'YM16' + - 8 + - 4:2:2 + - Y, Cb, Cr + - No + * - V4L2_PIX_FMT_YVU422M + - 'YM61' + - 8 + - 4:2:2 + - Y, Cr, Cb + - No + * - V4L2_PIX_FMT_YUV444M + - 'YM24' + - 8 + - 4:4:4 + - Y, Cb, Cr + - No + * - V4L2_PIX_FMT_YVU444M + - 'YM42' + - 8 + - 4:4:4 + - Y, Cr, Cb + - No + +.. raw:: latex + + \normalsize + +.. [4] Order of luma and chroma planes +.. [5] Indicates if planes have to be contiguous in memory or can be + disjoint + + +**Color Sample Location:** +Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` +horizontally. + +.. _V4L2-PIX-FMT-YUV410: +.. _V4L2-PIX-FMT-YVU410: + +YUV410 and YVU410 +----------------- + +Planar YUV 4:1:0 formats. The chroma planes are subsampled by 4 in each +direction. Chroma lines contain a quarter of the number of pixels and bytes of +the luma lines, and the chroma planes contain a quarter of the number of lines +of the luma plane. + +.. flat-table:: Sample 4x4 YUV410 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cr\ :sub:`00` + * - start + 17: + - Cb\ :sub:`00` + + +.. _V4L2-PIX-FMT-YUV411P: + +YUV411P +------- + +Planar YUV 4:1:1 formats. The chroma planes are subsampled by 4 in the +horizontal direction. Chroma lines contain a quarter of the number of pixels +and bytes of the luma lines, and the chroma planes contain the same number of +lines as the luma plane. + +.. flat-table:: Sample 4x4 YUV411P Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cb\ :sub:`00` + * - start + 17: + - Cb\ :sub:`10` + * - start + 18: + - Cb\ :sub:`20` + * - start + 19: + - Cb\ :sub:`30` + * - start + 20: + - Cr\ :sub:`00` + * - start + 21: + - Cr\ :sub:`10` + * - start + 22: + - Cr\ :sub:`20` + * - start + 23: + - Cr\ :sub:`30` + + +.. _V4L2-PIX-FMT-YUV420: +.. _V4L2-PIX-FMT-YVU420: +.. _V4L2-PIX-FMT-YUV420M: +.. _V4L2-PIX-FMT-YVU420M: + +YUV420, YVU420, YUV420M and YVU420M +----------------------------------- + +Planar YUV 4:2:0 formats. The chroma planes are subsampled by 2 in each +direction. Chroma lines contain half of the number of pixels and bytes of the +luma lines, and the chroma planes contain half of the number of lines of the +luma plane. + +.. flat-table:: Sample 4x4 YUV420 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cr\ :sub:`00` + - Cr\ :sub:`01` + * - start + 18: + - Cr\ :sub:`10` + - Cr\ :sub:`11` + * - start + 20: + - Cb\ :sub:`00` + - Cb\ :sub:`01` + * - start + 22: + - Cb\ :sub:`10` + - Cb\ :sub:`11` + +.. flat-table:: Sample 4x4 YUV420M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cb\ :sub:`01` + * - start1 + 2: + - Cb\ :sub:`10` + - Cb\ :sub:`11` + * - + * - start2 + 0: + - Cr\ :sub:`00` + - Cr\ :sub:`01` + * - start2 + 2: + - Cr\ :sub:`10` + - Cr\ :sub:`11` + + +.. _V4L2-PIX-FMT-YUV422P: +.. _V4L2-PIX-FMT-YUV422M: +.. _V4L2-PIX-FMT-YVU422M: + +YUV422P, YUV422M and YVU422M +---------------------------- + +Planar YUV 4:2:2 formats. The chroma planes are subsampled by 2 in the +horizontal direction. Chroma lines contain half of the number of pixels and +bytes of the luma lines, and the chroma planes contain the same number of lines +as the luma plane. + +.. flat-table:: Sample 4x4 YUV422P Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cb\ :sub:`00` + - Cb\ :sub:`01` + * - start + 18: + - Cb\ :sub:`10` + - Cb\ :sub:`11` + * - start + 20: + - Cb\ :sub:`20` + - Cb\ :sub:`21` + * - start + 22: + - Cb\ :sub:`30` + - Cb\ :sub:`31` + * - start + 24: + - Cr\ :sub:`00` + - Cr\ :sub:`01` + * - start + 26: + - Cr\ :sub:`10` + - Cr\ :sub:`11` + * - start + 28: + - Cr\ :sub:`20` + - Cr\ :sub:`21` + * - start + 30: + - Cr\ :sub:`30` + - Cr\ :sub:`31` + +.. flat-table:: Sample 4x4 YUV422M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cb\ :sub:`01` + * - start1 + 2: + - Cb\ :sub:`10` + - Cb\ :sub:`11` + * - start1 + 4: + - Cb\ :sub:`20` + - Cb\ :sub:`21` + * - start1 + 6: + - Cb\ :sub:`30` + - Cb\ :sub:`31` + * - + * - start2 + 0: + - Cr\ :sub:`00` + - Cr\ :sub:`01` + * - start2 + 2: + - Cr\ :sub:`10` + - Cr\ :sub:`11` + * - start2 + 4: + - Cr\ :sub:`20` + - Cr\ :sub:`21` + * - start2 + 6: + - Cr\ :sub:`30` + - Cr\ :sub:`31` + + +.. _V4L2-PIX-FMT-YUV444M: +.. _V4L2-PIX-FMT-YVU444M: + +YUV444M and YVU444M +------------------- + +Planar YUV 4:4:4 formats. The chroma planes are no subsampled. Chroma lines +contain the same number of pixels and bytes of the luma lines, and the chroma +planes contain the same number of lines as the luma plane. + +.. flat-table:: Sample 4x4 YUV444M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cb\ :sub:`01` + - Cb\ :sub:`02` + - Cb\ :sub:`03` + * - start1 + 4: + - Cb\ :sub:`10` + - Cb\ :sub:`11` + - Cb\ :sub:`12` + - Cb\ :sub:`13` + * - start1 + 8: + - Cb\ :sub:`20` + - Cb\ :sub:`21` + - Cb\ :sub:`22` + - Cb\ :sub:`23` + * - start1 + 12: + - Cb\ :sub:`20` + - Cb\ :sub:`21` + - Cb\ :sub:`32` + - Cb\ :sub:`33` + * - + * - start2 + 0: + - Cr\ :sub:`00` + - Cr\ :sub:`01` + - Cr\ :sub:`02` + - Cr\ :sub:`03` + * - start2 + 4: + - Cr\ :sub:`10` + - Cr\ :sub:`11` + - Cr\ :sub:`12` + - Cr\ :sub:`13` + * - start2 + 8: + - Cr\ :sub:`20` + - Cr\ :sub:`21` + - Cr\ :sub:`22` + - Cr\ :sub:`23` + * - start2 + 12: + - Cr\ :sub:`30` + - Cr\ :sub:`31` + - Cr\ :sub:`32` + - Cr\ :sub:`33` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst deleted file mode 100644 index 1d20115f2b1d..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst +++ /dev/null @@ -1,134 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-YVU410: -.. _v4l2-pix-fmt-yuv410: - -********************************************************** -V4L2_PIX_FMT_YVU410 ('YVU9'), V4L2_PIX_FMT_YUV410 ('YUV9') -********************************************************** - - -V4L2_PIX_FMT_YUV410 -Planar formats with ¼ horizontal and vertical chroma resolution, also -known as YUV 4:1:0 - - -Description -=========== - -These are planar formats, as opposed to a packed format. The three -components are separated into three sub-images or planes. The Y plane is -first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_YVU410``, -the Cr plane immediately follows the Y plane in memory. The Cr plane is -¼ the width and ¼ the height of the Y plane (and of the image). Each Cr -belongs to 16 pixels, a four-by-four square of the image. Following the -Cr plane is the Cb plane, just like the Cr plane. -``V4L2_PIX_FMT_YUV410`` is the same, except the Cb plane comes first, -then the Cr plane. - -If the Y plane has pad bytes after each row, then the Cr and Cb planes -have ¼ as many pad bytes after their rows. In other words, four Cx rows -(including padding) are exactly as long as one Y row (including -padding). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cr\ :sub:`00` - * - start + 17: - - Cb\ :sub:`00` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - - - Y - - - - Y - * - - * - 1 - - Y - - - - Y - - - - Y - - - - Y - * - - - - - - - - - C - - - - - - - * - 2 - - Y - - - - Y - - - - Y - - - - Y - * - - * - 3 - - Y - - - - Y - - - - Y - - - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv411p.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv411p.rst deleted file mode 100644 index 967ba7ce41a2..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv411p.rst +++ /dev/null @@ -1,122 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-YUV411P: - -***************************** -V4L2_PIX_FMT_YUV411P ('411P') -***************************** - - -Format with ¼ horizontal chroma resolution, also known as YUV 4:1:1. -Planar layout as opposed to ``V4L2_PIX_FMT_Y41P`` - - -Description -=========== - -This format is not commonly used. This is a planar format similar to the -4:2:2 planar format except with half as many chroma. The three -components are separated into three sub-images or planes. The Y plane is -first. The Y plane has one byte per pixel. The Cb plane immediately -follows the Y plane in memory. The Cb plane is ¼ the width of the Y -plane (and of the image). Each Cb belongs to 4 pixels all on the same -row. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`, -Y'\ :sub:`02` and Y'\ :sub:`03`. Following the Cb plane is the Cr plane, -just like the Cb plane. - -If the Y plane has pad bytes after each row, then the Cr and Cb planes -have ¼ as many pad bytes after their rows. In other words, four C x rows -(including padding) is exactly as long as one Y row (including padding). - -**Byte Order.** -Each cell is one byte. - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cb\ :sub:`00` - * - start + 17: - - Cb\ :sub:`10` - * - start + 18: - - Cb\ :sub:`20` - * - start + 19: - - Cb\ :sub:`30` - * - start + 20: - - Cr\ :sub:`00` - * - start + 21: - - Cr\ :sub:`10` - * - start + 22: - - Cr\ :sub:`20` - * - start + 23: - - Cr\ :sub:`30` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - 1 - - - - 2 - - 3 - * - 0 - - Y - - Y - - C - - Y - - Y - * - 1 - - Y - - Y - - C - - Y - - Y - * - 2 - - Y - - Y - - C - - Y - - Y - * - 3 - - Y - - Y - - C - - Y - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv420.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv420.rst deleted file mode 100644 index 7cb685cc8289..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv420.rst +++ /dev/null @@ -1,150 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-YVU420: -.. _V4L2-PIX-FMT-YUV420: - -********************************************************** -V4L2_PIX_FMT_YVU420 ('YV12'), V4L2_PIX_FMT_YUV420 ('YU12') -********************************************************** - - -V4L2_PIX_FMT_YUV420 -Planar formats with ½ horizontal and vertical chroma resolution, also -known as YUV 4:2:0 - - -Description -=========== - -These are planar formats, as opposed to a packed format. The three -components are separated into three sub- images or planes. The Y plane -is first. The Y plane has one byte per pixel. For -``V4L2_PIX_FMT_YVU420``, the Cr plane immediately follows the Y plane in -memory. The Cr plane is half the width and half the height of the Y -plane (and of the image). Each Cr belongs to four pixels, a two-by-two -square of the image. For example, Cr\ :sub:`0` belongs to Y'\ :sub:`00`, -Y'\ :sub:`01`, Y'\ :sub:`10`, and Y'\ :sub:`11`. Following the Cr plane -is the Cb plane, just like the Cr plane. ``V4L2_PIX_FMT_YUV420`` is the -same except the Cb plane comes first, then the Cr plane. - -If the Y plane has pad bytes after each row, then the Cr and Cb planes -have half as many pad bytes after their rows. In other words, two Cx -rows (including padding) is exactly as long as one Y row (including -padding). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cr\ :sub:`00` - - Cr\ :sub:`01` - * - start + 18: - - Cr\ :sub:`10` - - Cr\ :sub:`11` - * - start + 20: - - Cb\ :sub:`00` - - Cb\ :sub:`01` - * - start + 22: - - Cb\ :sub:`10` - - Cb\ :sub:`11` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - - - Y - - - - Y - * - - - - - C - - - - - - - - C - - - * - 1 - - Y - - - - Y - - - - Y - - - - Y - * - - * - 2 - - Y - - - - Y - - - - Y - - - - Y - * - - - - - C - - - - - - - - C - - - * - 3 - - Y - - - - Y - - - - Y - - - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv420m.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv420m.rst deleted file mode 100644 index 80c14d4f5acb..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv420m.rst +++ /dev/null @@ -1,159 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-YUV420M: -.. _v4l2-pix-fmt-yvu420m: - -************************************************************ -V4L2_PIX_FMT_YUV420M ('YM12'), V4L2_PIX_FMT_YVU420M ('YM21') -************************************************************ - - -V4L2_PIX_FMT_YVU420M -Variation of ``V4L2_PIX_FMT_YUV420`` and ``V4L2_PIX_FMT_YVU420`` with -planes non contiguous in memory. - - -Description -=========== - -This is a multi-planar format, as opposed to a packed format. The three -components are separated into three sub-images or planes. - -The Y plane is first. The Y plane has one byte per pixel. For -``V4L2_PIX_FMT_YUV420M`` the Cb data constitutes the second plane which -is half the width and half the height of the Y plane (and of the image). -Each Cb belongs to four pixels, a two-by-two square of the image. For -example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`, -Y'\ :sub:`10`, and Y'\ :sub:`11`. The Cr data, just like the Cb plane, -is in the third plane. - -``V4L2_PIX_FMT_YVU420M`` is the same except the Cr data is stored in the -second plane and the Cb data in the third plane. - -If the Y plane has pad bytes after each row, then the Cb and Cr planes -have half as many pad bytes after their rows. In other words, two Cx -rows (including padding) is exactly as long as one Y row (including -padding). - -``V4L2_PIX_FMT_YUV420M`` and ``V4L2_PIX_FMT_YVU420M`` are intended to be -used only in drivers and applications that support the multi-planar API, -described in :ref:`planar-apis`. - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start0 + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start0 + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start0 + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start0 + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - - * - start1 + 0: - - Cb\ :sub:`00` - - Cb\ :sub:`01` - * - start1 + 2: - - Cb\ :sub:`10` - - Cb\ :sub:`11` - * - - * - start2 + 0: - - Cr\ :sub:`00` - - Cr\ :sub:`01` - * - start2 + 2: - - Cr\ :sub:`10` - - Cr\ :sub:`11` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - - - Y - - - - Y - * - - - - - C - - - - - - - - C - - - * - 1 - - Y - - - - Y - - - - Y - - - - Y - * - - * - 2 - - Y - - - - Y - - - - Y - - - - Y - * - - - - - C - - - - - - - - C - - - * - 3 - - Y - - - - Y - - - - Y - - - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv422m.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv422m.rst deleted file mode 100644 index 29b78480ccad..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv422m.rst +++ /dev/null @@ -1,148 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-YUV422M: -.. _v4l2-pix-fmt-yvu422m: - -************************************************************ -V4L2_PIX_FMT_YUV422M ('YM16'), V4L2_PIX_FMT_YVU422M ('YM61') -************************************************************ - - -V4L2_PIX_FMT_YVU422M -Planar formats with ½ horizontal resolution, also known as YUV and YVU -4:2:2 - - -Description -=========== - -This is a multi-planar format, as opposed to a packed format. The three -components are separated into three sub-images or planes. - -The Y plane is first. The Y plane has one byte per pixel. For -``V4L2_PIX_FMT_YUV422M`` the Cb data constitutes the second plane which -is half the width of the Y plane (and of the image). Each Cb belongs to -two pixels. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, -Y'\ :sub:`01`. The Cr data, just like the Cb plane, is in the third -plane. - -``V4L2_PIX_FMT_YVU422M`` is the same except the Cr data is stored in the -second plane and the Cb data in the third plane. - -If the Y plane has pad bytes after each row, then the Cb and Cr planes -have half as many pad bytes after their rows. In other words, two Cx -rows (including padding) is exactly as long as one Y row (including -padding). - -``V4L2_PIX_FMT_YUV422M`` and ``V4L2_PIX_FMT_YVU422M`` are intended to be -used only in drivers and applications that support the multi-planar API, -described in :ref:`planar-apis`. - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start0 + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start0 + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start0 + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start0 + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - - * - start1 + 0: - - Cb\ :sub:`00` - - Cb\ :sub:`01` - * - start1 + 2: - - Cb\ :sub:`10` - - Cb\ :sub:`11` - * - start1 + 4: - - Cb\ :sub:`20` - - Cb\ :sub:`21` - * - start1 + 6: - - Cb\ :sub:`30` - - Cb\ :sub:`31` - * - - * - start2 + 0: - - Cr\ :sub:`00` - - Cr\ :sub:`01` - * - start2 + 2: - - Cr\ :sub:`10` - - Cr\ :sub:`11` - * - start2 + 4: - - Cr\ :sub:`20` - - Cr\ :sub:`21` - * - start2 + 6: - - Cr\ :sub:`30` - - Cr\ :sub:`31` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - C - - Y - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv422p.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv422p.rst deleted file mode 100644 index 73fde222d820..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv422p.rst +++ /dev/null @@ -1,136 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-YUV422P: - -***************************** -V4L2_PIX_FMT_YUV422P ('422P') -***************************** - - -Format with ½ horizontal chroma resolution, also known as YUV 4:2:2. -Planar layout as opposed to ``V4L2_PIX_FMT_YUYV`` - - -Description -=========== - -This format is not commonly used. This is a planar version of the YUYV -format. The three components are separated into three sub-images or -planes. The Y plane is first. The Y plane has one byte per pixel. The Cb -plane immediately follows the Y plane in memory. The Cb plane is half -the width of the Y plane (and of the image). Each Cb belongs to two -pixels. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, -Y'\ :sub:`01`. Following the Cb plane is the Cr plane, just like the Cb -plane. - -If the Y plane has pad bytes after each row, then the Cr and Cb planes -have half as many pad bytes after their rows. In other words, two Cx -rows (including padding) is exactly as long as one Y row (including -padding). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cb\ :sub:`00` - - Cb\ :sub:`01` - * - start + 18: - - Cb\ :sub:`10` - - Cb\ :sub:`11` - * - start + 20: - - Cb\ :sub:`20` - - Cb\ :sub:`21` - * - start + 22: - - Cb\ :sub:`30` - - Cb\ :sub:`31` - * - start + 24: - - Cr\ :sub:`00` - - Cr\ :sub:`01` - * - start + 26: - - Cr\ :sub:`10` - - Cr\ :sub:`11` - * - start + 28: - - Cr\ :sub:`20` - - Cr\ :sub:`21` - * - start + 30: - - Cr\ :sub:`30` - - Cr\ :sub:`31` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - C - - Y - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv444m.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv444m.rst deleted file mode 100644 index 7073ac7f842d..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv444m.rst +++ /dev/null @@ -1,148 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-YUV444M: -.. _v4l2-pix-fmt-yvu444m: - -************************************************************ -V4L2_PIX_FMT_YUV444M ('YM24'), V4L2_PIX_FMT_YVU444M ('YM42') -************************************************************ - - -V4L2_PIX_FMT_YVU444M -Planar formats with full horizontal resolution, also known as YUV and -YVU 4:4:4 - - -Description -=========== - -This is a multi-planar format, as opposed to a packed format. The three -components are separated into three sub-images or planes. - -The Y plane is first. The Y plane has one byte per pixel. For -``V4L2_PIX_FMT_YUV444M`` the Cb data constitutes the second plane which -is the same width and height as the Y plane (and as the image). The Cr -data, just like the Cb plane, is in the third plane. - -``V4L2_PIX_FMT_YVU444M`` is the same except the Cr data is stored in the -second plane and the Cb data in the third plane. - -If the Y plane has pad bytes after each row, then the Cb and Cr planes -have the same number of pad bytes after their rows. - -``V4L2_PIX_FMT_YUV444M`` and ``V4L2_PIX_FMT_YUV444M`` are intended to be -used only in drivers and applications that support the multi-planar API, -described in :ref:`planar-apis`. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start0 + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start0 + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start0 + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start0 + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - - * - start1 + 0: - - Cb\ :sub:`00` - - Cb\ :sub:`01` - - Cb\ :sub:`02` - - Cb\ :sub:`03` - * - start1 + 4: - - Cb\ :sub:`10` - - Cb\ :sub:`11` - - Cb\ :sub:`12` - - Cb\ :sub:`13` - * - start1 + 8: - - Cb\ :sub:`20` - - Cb\ :sub:`21` - - Cb\ :sub:`22` - - Cb\ :sub:`23` - * - start1 + 12: - - Cb\ :sub:`20` - - Cb\ :sub:`21` - - Cb\ :sub:`32` - - Cb\ :sub:`33` - * - - * - start2 + 0: - - Cr\ :sub:`00` - - Cr\ :sub:`01` - - Cr\ :sub:`02` - - Cr\ :sub:`03` - * - start2 + 4: - - Cr\ :sub:`10` - - Cr\ :sub:`11` - - Cr\ :sub:`12` - - Cr\ :sub:`13` - * - start2 + 8: - - Cr\ :sub:`20` - - Cr\ :sub:`21` - - Cr\ :sub:`22` - - Cr\ :sub:`23` - * - start2 + 12: - - Cr\ :sub:`30` - - Cr\ :sub:`31` - - Cr\ :sub:`32` - - Cr\ :sub:`33` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - 1 - - 2 - - 3 - * - 0 - - YC - - YC - - YC - - YC - * - 1 - - YC - - YC - - YC - - YC - * - 2 - - YC - - YC - - YC - - YC - * - 3 - - YC - - YC - - YC - - YC diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst deleted file mode 100644 index fe70e007787d..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst +++ /dev/null @@ -1,125 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-YUYV: - -************************** -V4L2_PIX_FMT_YUYV ('YUYV') -************************** - - -Packed format with ½ horizontal chroma resolution, also known as YUV -4:2:2 - - -Description -=========== - -In this format each four bytes is two pixels. Each four bytes is two -Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr -belong to both pixels. As you can see, the Cr and Cb components have -half the horizontal resolution of the Y component. ``V4L2_PIX_FMT_YUYV`` -is known in the Windows environment as YUY2. - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Cb\ :sub:`00` - - Y'\ :sub:`01` - - Cr\ :sub:`00` - - Y'\ :sub:`02` - - Cb\ :sub:`01` - - Y'\ :sub:`03` - - Cr\ :sub:`01` - * - start + 8: - - Y'\ :sub:`10` - - Cb\ :sub:`10` - - Y'\ :sub:`11` - - Cr\ :sub:`10` - - Y'\ :sub:`12` - - Cb\ :sub:`11` - - Y'\ :sub:`13` - - Cr\ :sub:`11` - * - start + 16: - - Y'\ :sub:`20` - - Cb\ :sub:`20` - - Y'\ :sub:`21` - - Cr\ :sub:`20` - - Y'\ :sub:`22` - - Cb\ :sub:`21` - - Y'\ :sub:`23` - - Cr\ :sub:`21` - * - start + 24: - - Y'\ :sub:`30` - - Cb\ :sub:`30` - - Y'\ :sub:`31` - - Cr\ :sub:`30` - - Y'\ :sub:`32` - - Cb\ :sub:`31` - - Y'\ :sub:`33` - - Cr\ :sub:`31` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - - - 2 - - - - 3 - * - 0 - - Y - - C - - Y - - - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst b/Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst deleted file mode 100644 index 96c1b537d5a0..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst +++ /dev/null @@ -1,115 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _V4L2-PIX-FMT-YVYU: - -************************** -V4L2_PIX_FMT_YVYU ('YVYU') -************************** - - -Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in -memory - - -Description -=========== - -In this format each four bytes is two pixels. Each four bytes is two -Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr -belong to both pixels. As you can see, the Cr and Cb components have -half the horizontal resolution of the Y component. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Cr\ :sub:`00` - - Y'\ :sub:`01` - - Cb\ :sub:`00` - - Y'\ :sub:`02` - - Cr\ :sub:`01` - - Y'\ :sub:`03` - - Cb\ :sub:`01` - * - start + 8: - - Y'\ :sub:`10` - - Cr\ :sub:`10` - - Y'\ :sub:`11` - - Cb\ :sub:`10` - - Y'\ :sub:`12` - - Cr\ :sub:`11` - - Y'\ :sub:`13` - - Cb\ :sub:`11` - * - start + 16: - - Y'\ :sub:`20` - - Cr\ :sub:`20` - - Y'\ :sub:`21` - - Cb\ :sub:`20` - - Y'\ :sub:`22` - - Cr\ :sub:`21` - - Y'\ :sub:`23` - - Cb\ :sub:`21` - * - start + 24: - - Y'\ :sub:`30` - - Cr\ :sub:`30` - - Y'\ :sub:`31` - - Cb\ :sub:`30` - - Y'\ :sub:`32` - - Cr\ :sub:`31` - - Y'\ :sub:`33` - - Cb\ :sub:`31` - - -**Color Sample Location:** - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - C - - Y - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-z16.rst b/Documentation/userspace-api/media/v4l/pixfmt-z16.rst index fe2fb21edeea..54a8cd723d1a 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-z16.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-z16.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _V4L2-PIX-FMT-Z16: diff --git a/Documentation/userspace-api/media/v4l/pixfmt.rst b/Documentation/userspace-api/media/v4l/pixfmt.rst index 70ca3a5c2cf1..11dab4a90630 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _pixfmt: diff --git a/Documentation/userspace-api/media/v4l/planar-apis.rst b/Documentation/userspace-api/media/v4l/planar-apis.rst index 6247b0c4ab4d..9207ce4283df 100644 --- a/Documentation/userspace-api/media/v4l/planar-apis.rst +++ b/Documentation/userspace-api/media/v4l/planar-apis.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _planar-apis: diff --git a/Documentation/userspace-api/media/v4l/querycap.rst b/Documentation/userspace-api/media/v4l/querycap.rst index 35fba2a9e09b..15a90271af45 100644 --- a/Documentation/userspace-api/media/v4l/querycap.rst +++ b/Documentation/userspace-api/media/v4l/querycap.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _querycap: diff --git a/Documentation/userspace-api/media/v4l/rw.rst b/Documentation/userspace-api/media/v4l/rw.rst index ce2768c994d0..64b85fb2a328 100644 --- a/Documentation/userspace-api/media/v4l/rw.rst +++ b/Documentation/userspace-api/media/v4l/rw.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _rw: @@ -13,8 +7,8 @@ Read/Write ********** -Input and output devices support the :ref:`read() <func-read>` and -:ref:`write() <func-write>` function, respectively, when the +Input and output devices support the :c:func:`read()` and +:c:func:`write()` function, respectively, when the ``V4L2_CAP_READWRITE`` flag in the ``capabilities`` field of struct :c:type:`v4l2_capability` returned by the :ref:`VIDIOC_QUERYCAP` ioctl is set. @@ -29,18 +23,17 @@ However this is also the simplest I/O method, requiring little or no setup to exchange data. It permits command line stunts like this (the vidctrl tool is fictitious): - .. code-block:: none $ vidctrl /dev/video --input=0 --format=YUYV --size=352x288 $ dd if=/dev/video of=myimage.422 bs=202752 count=1 -To read from the device applications use the :ref:`read() <func-read>` -function, to write the :ref:`write() <func-write>` function. Drivers +To read from the device applications use the :c:func:`read()` +function, to write the :c:func:`write()` function. Drivers must implement one I/O method if they exchange data with applications, but it need not be this. [#f1]_ When reading or writing is supported, the -driver must also support the :ref:`select() <func-select>` and -:ref:`poll() <func-poll>` function. [#f2]_ +driver must also support the :c:func:`select()` and +:c:func:`poll()` function. [#f2]_ .. [#f1] It would be desirable if applications could depend on drivers @@ -50,5 +43,5 @@ driver must also support the :ref:`select() <func-select>` and capturing still images. .. [#f2] - At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are - the same, and :ref:`select() <func-select>` is too important to be optional. + At the driver level :c:func:`select()` and :c:func:`poll()` are + the same, and :c:func:`select()` is too important to be optional. diff --git a/Documentation/userspace-api/media/v4l/sdr-formats.rst b/Documentation/userspace-api/media/v4l/sdr-formats.rst index b7a1be75251f..d8bdfdb56911 100644 --- a/Documentation/userspace-api/media/v4l/sdr-formats.rst +++ b/Documentation/userspace-api/media/v4l/sdr-formats.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _sdr-formats: diff --git a/Documentation/userspace-api/media/v4l/selection-api-configuration.rst b/Documentation/userspace-api/media/v4l/selection-api-configuration.rst index 67ff67fd734e..fee49bf1a1c0 100644 --- a/Documentation/userspace-api/media/v4l/selection-api-configuration.rst +++ b/Documentation/userspace-api/media/v4l/selection-api-configuration.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later ************* Configuration @@ -101,7 +94,7 @@ specified using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. The top left corner, width and height of the source rectangle, that is the area from which image date are processed by the hardware, is given -by the ``V4L2_SEL_TGT_CROP``. Its coordinates are expressed in in the +by the ``V4L2_SEL_TGT_CROP``. Its coordinates are expressed in the same coordinate system as the bounds rectangle. The active cropping area must lie completely inside the crop boundaries and the driver may further adjust the requested size and/or position according to hardware diff --git a/Documentation/userspace-api/media/v4l/selection-api-examples.rst b/Documentation/userspace-api/media/v4l/selection-api-examples.rst index 2f4027211129..5f8e8a1f59d7 100644 --- a/Documentation/userspace-api/media/v4l/selection-api-examples.rst +++ b/Documentation/userspace-api/media/v4l/selection-api-examples.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later ******** Examples diff --git a/Documentation/userspace-api/media/v4l/selection-api-intro.rst b/Documentation/userspace-api/media/v4l/selection-api-intro.rst index 0994ca25be5e..6534854ae9f7 100644 --- a/Documentation/userspace-api/media/v4l/selection-api-intro.rst +++ b/Documentation/userspace-api/media/v4l/selection-api-intro.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later ************ Introduction diff --git a/Documentation/userspace-api/media/v4l/selection-api-targets.rst b/Documentation/userspace-api/media/v4l/selection-api-targets.rst index 56eab969c9d8..50fdadd5b307 100644 --- a/Documentation/userspace-api/media/v4l/selection-api-targets.rst +++ b/Documentation/userspace-api/media/v4l/selection-api-targets.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later ***************** Selection targets diff --git a/Documentation/userspace-api/media/v4l/selection-api-vs-crop-api.rst b/Documentation/userspace-api/media/v4l/selection-api-vs-crop-api.rst index a9360a000022..f57b9180012c 100644 --- a/Documentation/userspace-api/media/v4l/selection-api-vs-crop-api.rst +++ b/Documentation/userspace-api/media/v4l/selection-api-vs-crop-api.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _selection-vs-crop: diff --git a/Documentation/userspace-api/media/v4l/selection-api.rst b/Documentation/userspace-api/media/v4l/selection-api.rst index b86e387721df..0360743746dc 100644 --- a/Documentation/userspace-api/media/v4l/selection-api.rst +++ b/Documentation/userspace-api/media/v4l/selection-api.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _selection-api: diff --git a/Documentation/userspace-api/media/v4l/selection.svg b/Documentation/userspace-api/media/v4l/selection.svg index c0e00ab2ae6b..6305b53b8e54 100644 --- a/Documentation/userspace-api/media/v4l/selection.svg +++ b/Documentation/userspace-api/media/v4l/selection.svg @@ -1,31 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<!-- - This file is dual-licensed: you can use it either under the terms - of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this - dual licensing only applies to this file, and not this project as a - whole. - - a) This file is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License as - published by the Free Software Foundation version 2 of - the License. - - This file is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - Or, alternatively, - - b) Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later --> <svg enable-background="new" version="1" viewBox="0 0 4226.3 1686.8" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> <defs> <pattern id="ig" xlink:href="#ka" patternTransform="matrix(5.4432 0 0 10.1 1722.4 161.06)"/> diff --git a/Documentation/userspace-api/media/v4l/selections-common.rst b/Documentation/userspace-api/media/v4l/selections-common.rst index d5ea05869a61..322b39cf0eba 100644 --- a/Documentation/userspace-api/media/v4l/selections-common.rst +++ b/Documentation/userspace-api/media/v4l/selections-common.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2-selections-common: diff --git a/Documentation/userspace-api/media/v4l/standard.rst b/Documentation/userspace-api/media/v4l/standard.rst index 61c341508eb3..1f6678325da9 100644 --- a/Documentation/userspace-api/media/v4l/standard.rst +++ b/Documentation/userspace-api/media/v4l/standard.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _standard: diff --git a/Documentation/userspace-api/media/v4l/streaming-par.rst b/Documentation/userspace-api/media/v4l/streaming-par.rst index 6d1a1b93ac8b..806cbfdad0f1 100644 --- a/Documentation/userspace-api/media/v4l/streaming-par.rst +++ b/Documentation/userspace-api/media/v4l/streaming-par.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _streaming-par: @@ -21,13 +15,13 @@ 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 +:c:func:`read()` or :c:func:`write()`, which are not augmented by timestamps or sequence counters, and to avoid unnecessary data copying. Finally these ioctls can be used to determine the number of buffers used internally by a driver in read/write mode. For implications see the -section discussing the :ref:`read() <func-read>` function. +section discussing the :c:func:`read()` function. To get and set the streaming parameters applications call the :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and diff --git a/Documentation/userspace-api/media/v4l/subdev-formats.rst b/Documentation/userspace-api/media/v4l/subdev-formats.rst index 9a4d61b0d76f..2a94371448dc 100644 --- a/Documentation/userspace-api/media/v4l/subdev-formats.rst +++ b/Documentation/userspace-api/media/v4l/subdev-formats.rst @@ -1,21 +1,16 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2-mbus-format: Media Bus Formats ================= -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. c:type:: v4l2_mbus_framefmt +.. tabularcolumns:: |p{2.0cm}|p{4.0cm}|p{11.3cm}| + +.. cssclass:: longtable + .. flat-table:: struct v4l2_mbus_framefmt :header-rows: 0 :stub-columns: 0 @@ -38,35 +33,113 @@ Media Bus Formats * - __u32 - ``field`` - Field order, from enum :c:type:`v4l2_field`. See - :ref:`field-order` for details. + :ref:`field-order` for details. Zero for metadata mbus codes. * - __u32 - ``colorspace`` - - Image colorspace, from enum - :c:type:`v4l2_colorspace`. See - :ref:`colorspaces` for details. + - Image colorspace, from enum :c:type:`v4l2_colorspace`. + Must be set by the driver for subdevices. If the application sets the + flag ``V4L2_MBUS_FRAMEFMT_SET_CSC`` then the application can set this + field on the source pad to request a specific colorspace for the media + bus data. If the driver cannot handle the requested conversion, it will + return another supported colorspace. The driver indicates that colorspace + conversion is supported by setting the flag + V4L2_SUBDEV_MBUS_CODE_CSC_COLORSPACE in the corresponding struct + :c:type:`v4l2_subdev_mbus_code_enum` during enumeration. + See :ref:`v4l2-subdev-mbus-code-flags`. Zero for metadata mbus codes. + * - union { + - (anonymous) * - __u16 - ``ycbcr_enc`` - Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`. This information supplements the ``colorspace`` and must be set by - the driver for capture streams and by the application for output - streams, see :ref:`colorspaces`. + the driver for subdevices, see :ref:`colorspaces`. If the application + sets the flag ``V4L2_MBUS_FRAMEFMT_SET_CSC`` then the application can set + this field on a source pad to request a specific Y'CbCr encoding + for the media bus data. If the driver cannot handle the requested + conversion, it will return another supported encoding. + This field is ignored for HSV media bus formats. The driver indicates + that ycbcr_enc conversion is supported by setting the flag + V4L2_SUBDEV_MBUS_CODE_CSC_YCBCR_ENC in the corresponding struct + :c:type:`v4l2_subdev_mbus_code_enum` during enumeration. + See :ref:`v4l2-subdev-mbus-code-flags`. Zero for metadata mbus codes. + * - __u16 + - ``hsv_enc`` + - HSV encoding, from enum :c:type:`v4l2_hsv_encoding`. + This information supplements the ``colorspace`` and must be set by + the driver for subdevices, see :ref:`colorspaces`. If the application + sets the flag ``V4L2_MBUS_FRAMEFMT_SET_CSC`` then the application can set + this field on a source pad to request a specific HSV encoding + for the media bus data. If the driver cannot handle the requested + conversion, it will return another supported encoding. + This field is ignored for Y'CbCr media bus formats. The driver indicates + that hsv_enc conversion is supported by setting the flag + V4L2_SUBDEV_MBUS_CODE_CSC_HSV_ENC in the corresponding struct + :c:type:`v4l2_subdev_mbus_code_enum` during enumeration. + See :ref:`v4l2-subdev-mbus-code-flags`. Zero for metadata mbus codes. + * - } + - * - __u16 - ``quantization`` - Quantization range, from enum :c:type:`v4l2_quantization`. This information supplements the ``colorspace`` and must be set by - the driver for capture streams and by the application for output - streams, see :ref:`colorspaces`. + the driver for subdevices, see :ref:`colorspaces`. If the application + sets the flag ``V4L2_MBUS_FRAMEFMT_SET_CSC`` then the application can set + this field on a source pad to request a specific quantization + for the media bus data. If the driver cannot handle the requested + conversion, it will return another supported quantization. + The driver indicates that quantization conversion is supported by + setting the flag V4L2_SUBDEV_MBUS_CODE_CSC_QUANTIZATION in the + corresponding struct :c:type:`v4l2_subdev_mbus_code_enum` + during enumeration. See :ref:`v4l2-subdev-mbus-code-flags`. Zero for + metadata mbus codes. * - __u16 - ``xfer_func`` - Transfer function, from enum :c:type:`v4l2_xfer_func`. This information supplements the ``colorspace`` and must be set by - the driver for capture streams and by the application for output - streams, see :ref:`colorspaces`. + the driver for subdevices, see :ref:`colorspaces`. If the application + sets the flag ``V4L2_MBUS_FRAMEFMT_SET_CSC`` then the application can set + this field on a source pad to request a specific transfer + function for the media bus data. If the driver cannot handle the requested + conversion, it will return another supported transfer function. + The driver indicates that the transfer function conversion is supported by + setting the flag V4L2_SUBDEV_MBUS_CODE_CSC_XFER_FUNC in the + corresponding struct :c:type:`v4l2_subdev_mbus_code_enum` + during enumeration. See :ref:`v4l2-subdev-mbus-code-flags`. Zero for + metadata mbus codes. * - __u16 - - ``reserved``\ [11] + - ``flags`` + - flags See: :ref:v4l2-mbus-framefmt-flags + * - __u16 + - ``reserved``\ [10] - Reserved for future extensions. Applications and drivers must set the array to zero. +.. _v4l2-mbus-framefmt-flags: + +.. tabularcolumns:: |p{6.5cm}|p{1.6cm}|p{9.2cm}| + +.. flat-table:: v4l2_mbus_framefmt Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * .. _`mbus-framefmt-set-csc`: + + - ``V4L2_MBUS_FRAMEFMT_SET_CSC`` + - 0x0001 + - Set by the application. It is only used for source pads and is + ignored for sink pads. If set, then request the subdevice to do + colorspace conversion from the received colorspace to the requested + colorspace values. If the colorimetry field (``colorspace``, ``xfer_func``, + ``ycbcr_enc``, ``hsv_enc`` or ``quantization``) is set to ``*_DEFAULT``, + then that colorimetry setting will remain unchanged from what was received. + So in order to change the quantization, only the ``quantization`` field shall + be set to non default value (``V4L2_QUANTIZATION_FULL_RANGE`` or + ``V4L2_QUANTIZATION_LIM_RANGE``) and all other colorimetry fields shall + be set to ``*_DEFAULT``. + + To check which conversions are supported by the hardware for the current + media bus frame format, see :ref:`v4l2-subdev-mbus-code-flags`. .. _v4l2-mbus-pixelcode: @@ -136,7 +209,7 @@ The following tables list existing packed RGB formats. .. it switches to long table, and there's no way to override it. -.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{5.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _v4l2-mbus-pixelcode-rgb: @@ -877,6 +950,115 @@ The following tables list existing packed RGB formats. - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` + * .. _MEDIA-BUS-FMT-RGB666-2X9-BE: + + - MEDIA_BUS_FMT_RGB666_2X9_BE + - 0x1025 + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + * - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + * .. _MEDIA-BUS-FMT-BGR666-1X18: + + - MEDIA_BUS_FMT_BGR666_1X18 + - 0x1023 + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` * .. _MEDIA-BUS-FMT-RBG888-1X24: - MEDIA_BUS_FMT_RBG888_1X24 @@ -951,6 +1133,80 @@ The following tables list existing packed RGB formats. - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` + * .. _MEDIA-BUS-FMT-BGR666-1X24_CPADHI: + + - MEDIA_BUS_FMT_BGR666_1X24_CPADHI + - 0x1024 + - + - + - + - + - + - + - + - + - + - 0 + - 0 + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - 0 + - 0 + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - 0 + - 0 + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + * .. _MEDIA-BUS-FMT-RGB565-1X24_CPADHI: + + - MEDIA_BUS_FMT_RGB565_1X24_CPADHI + - 0x1022 + - + - + - + - + - + - + - + - + - + - 0 + - 0 + - 0 + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - 0 + - 0 + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - 0 + - 0 + - 0 + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` * .. _MEDIA-BUS-FMT-BGR888-1X24: - MEDIA_BUS_FMT_BGR888_1X24 @@ -1420,6 +1676,80 @@ The following tables list existing packed RGB formats. - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` + * .. _MEDIA-BUS-FMT-RGB666-1X30-CPADLO: + + - MEDIA_BUS_FMT_RGB666_1X30-CPADLO + - 0x101e + - + - + - + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + * .. _MEDIA-BUS-FMT-RGB888-1X30-CPADLO: + + - MEDIA_BUS_FMT_RGB888_1X30-CPADLO + - 0x101f + - + - + - + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - 0 + - 0 + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - 0 + - 0 + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - 0 + - 0 * .. _MEDIA-BUS-FMT-ARGB888-1X32: - MEDIA_BUS_FMT_ARGB888_1X32 @@ -1499,8 +1829,8 @@ The following tables list existing packed RGB formats. - MEDIA_BUS_FMT_RGB101010_1X30 - 0x1018 - - - 0 - - 0 + - + - - r\ :sub:`9` - r\ :sub:`8` - r\ :sub:`7` @@ -1597,6 +1927,88 @@ The following table list existing packed 36bit wide RGB formats. - 2 - 1 - 0 + * .. _MEDIA-BUS-FMT-RGB666-1X36-CPADLO: + + - MEDIA_BUS_FMT_RGB666_1X36_CPADLO + - 0x1020 + - + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + * .. _MEDIA-BUS-FMT-RGB888-1X36-CPADLO: + + - MEDIA_BUS_FMT_RGB888_1X36_CPADLO + - 0x1021 + - + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - 0 + - 0 + - 0 + - 0 * .. _MEDIA-BUS-FMT-RGB121212-1X36: - MEDIA_BUS_FMT_RGB121212_1X36 @@ -1813,7 +2225,7 @@ The following table list existing packed 48bit wide RGB formats. \endgroup On LVDS buses, usually each sample is transferred serialized in seven -time slots per pixel clock, on three (18-bit) or four (24-bit) +time slots per pixel clock, on three (18-bit) or four (24-bit) or five (30-bit) differential data pairs at the same time. The remaining bits are used for control signals as defined by SPWG/PSWG/VESA or JEIDA standards. The 24-bit RGB format serialized in seven time slots on four lanes using @@ -1822,7 +2234,7 @@ JEIDA defined bit mapping will be named .. raw:: latex - \tiny + \small .. _v4l2-mbus-pixelcode-rgb-lvds: @@ -1834,11 +2246,12 @@ JEIDA defined bit mapping will be named - Code - - - - :cspan:`3` Data organization + - :cspan:`4` Data organization * - - - Timeslot - Lane + - 4 - 3 - 2 - 1 @@ -1850,6 +2263,7 @@ JEIDA defined bit mapping will be named - 0 - - + - - d - b\ :sub:`1` - g\ :sub:`0` @@ -1858,6 +2272,7 @@ JEIDA defined bit mapping will be named - 1 - - + - - d - b\ :sub:`0` - r\ :sub:`5` @@ -1866,6 +2281,7 @@ JEIDA defined bit mapping will be named - 2 - - + - - d - g\ :sub:`5` - r\ :sub:`4` @@ -1874,6 +2290,7 @@ JEIDA defined bit mapping will be named - 3 - - + - - b\ :sub:`5` - g\ :sub:`4` - r\ :sub:`3` @@ -1882,6 +2299,7 @@ JEIDA defined bit mapping will be named - 4 - - + - - b\ :sub:`4` - g\ :sub:`3` - r\ :sub:`2` @@ -1890,6 +2308,7 @@ JEIDA defined bit mapping will be named - 5 - - + - - b\ :sub:`3` - g\ :sub:`2` - r\ :sub:`1` @@ -1898,6 +2317,7 @@ JEIDA defined bit mapping will be named - 6 - - + - - b\ :sub:`2` - g\ :sub:`1` - r\ :sub:`0` @@ -1907,6 +2327,7 @@ JEIDA defined bit mapping will be named - 0x1011 - 0 - + - - d - d - b\ :sub:`1` @@ -1915,6 +2336,7 @@ JEIDA defined bit mapping will be named - - 1 - + - - b\ :sub:`7` - d - b\ :sub:`0` @@ -1923,6 +2345,7 @@ JEIDA defined bit mapping will be named - - 2 - + - - b\ :sub:`6` - d - g\ :sub:`5` @@ -1931,6 +2354,7 @@ JEIDA defined bit mapping will be named - - 3 - + - - g\ :sub:`7` - b\ :sub:`5` - g\ :sub:`4` @@ -1939,6 +2363,7 @@ JEIDA defined bit mapping will be named - - 4 - + - - g\ :sub:`6` - b\ :sub:`4` - g\ :sub:`3` @@ -1947,6 +2372,7 @@ JEIDA defined bit mapping will be named - - 5 - + - - r\ :sub:`7` - b\ :sub:`3` - g\ :sub:`2` @@ -1955,6 +2381,7 @@ JEIDA defined bit mapping will be named - - 6 - + - - r\ :sub:`6` - b\ :sub:`2` - g\ :sub:`1` @@ -1965,6 +2392,7 @@ JEIDA defined bit mapping will be named - 0x1012 - 0 - + - - d - d - b\ :sub:`3` @@ -1973,6 +2401,7 @@ JEIDA defined bit mapping will be named - - 1 - + - - b\ :sub:`1` - d - b\ :sub:`2` @@ -1981,6 +2410,7 @@ JEIDA defined bit mapping will be named - - 2 - + - - b\ :sub:`0` - d - g\ :sub:`7` @@ -1989,6 +2419,7 @@ JEIDA defined bit mapping will be named - - 3 - + - - g\ :sub:`1` - b\ :sub:`7` - g\ :sub:`6` @@ -1997,6 +2428,7 @@ JEIDA defined bit mapping will be named - - 4 - + - - g\ :sub:`0` - b\ :sub:`6` - g\ :sub:`5` @@ -2005,6 +2437,7 @@ JEIDA defined bit mapping will be named - - 5 - + - - r\ :sub:`1` - b\ :sub:`5` - g\ :sub:`4` @@ -2013,10 +2446,141 @@ JEIDA defined bit mapping will be named - - 6 - + - + - r\ :sub:`0` + - b\ :sub:`4` + - g\ :sub:`3` + - r\ :sub:`2` + * .. _MEDIA-BUS-FMT-RGB101010-1X7X5-SPWG: + + - MEDIA_BUS_FMT_RGB101010_1X7X5_SPWG + - 0x1026 + - 0 + - + - d + - d + - d + - b\ :sub:`1` + - g\ :sub:`0` + * - + - + - 1 + - + - b\ :sub:`9` + - b\ :sub:`7` + - d + - b\ :sub:`0` + - r\ :sub:`5` + * - + - + - 2 + - + - b\ :sub:`8` + - b\ :sub:`6` + - d + - g\ :sub:`5` + - r\ :sub:`4` + * - + - + - 3 + - + - g\ :sub:`9` + - g\ :sub:`7` + - b\ :sub:`5` + - g\ :sub:`4` + - r\ :sub:`3` + * - + - + - 4 + - + - g\ :sub:`8` + - g\ :sub:`6` + - b\ :sub:`4` + - g\ :sub:`3` + - r\ :sub:`2` + * - + - + - 5 + - + - r\ :sub:`9` + - r\ :sub:`7` + - b\ :sub:`3` + - g\ :sub:`2` + - r\ :sub:`1` + * - + - + - 6 + - + - r\ :sub:`8` + - r\ :sub:`6` + - b\ :sub:`2` + - g\ :sub:`1` - r\ :sub:`0` + * .. _MEDIA-BUS-FMT-RGB101010-1X7X5-JEIDA: + + - MEDIA_BUS_FMT_RGB101010_1X7X5_JEIDA + - 0x1027 + - 0 + - + - d + - d + - d + - b\ :sub:`5` + - g\ :sub:`4` + * - + - + - 1 + - + - b\ :sub:`1` + - b\ :sub:`3` + - d - b\ :sub:`4` + - r\ :sub:`9` + * - + - + - 2 + - + - b\ :sub:`0` + - b\ :sub:`2` + - d + - g\ :sub:`9` + - r\ :sub:`8` + * - + - + - 3 + - + - g\ :sub:`1` - g\ :sub:`3` + - b\ :sub:`9` + - g\ :sub:`8` + - r\ :sub:`7` + * - + - + - 4 + - + - g\ :sub:`0` + - g\ :sub:`2` + - b\ :sub:`8` + - g\ :sub:`7` + - r\ :sub:`6` + * - + - + - 5 + - + - r\ :sub:`1` + - r\ :sub:`3` + - b\ :sub:`7` + - g\ :sub:`6` + - r\ :sub:`5` + * - + - + - 6 + - + - r\ :sub:`0` - r\ :sub:`2` + - b\ :sub:`6` + - g\ :sub:`5` + - r\ :sub:`4` .. raw:: latex @@ -2084,7 +2648,7 @@ organization is given as an example for the first pixel only. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.3cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{6.0cm}|p{0.7cm}|p{0.3cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _v4l2-mbus-pixelcode-bayer: @@ -2937,7 +3501,7 @@ the following codes. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{5.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _v4l2-mbus-pixelcode-yuv8: @@ -5829,6 +6393,43 @@ the following codes. - y\ :sub:`2` - y\ :sub:`1` - y\ :sub:`0` + * .. _MEDIA-BUS-FMT-Y16-1X16: + + - MEDIA_BUS_FMT_Y16_1X16 + - 0x202e + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - y\ :sub:`15` + - y\ :sub:`14` + - y\ :sub:`13` + - y\ :sub:`12` + - y\ :sub:`11` + - y\ :sub:`10` + - y\ :sub:`9` + - y\ :sub:`8` + - y\ :sub:`7` + - y\ :sub:`6` + - y\ :sub:`5` + - y\ :sub:`4` + - y\ :sub:`3` + - y\ :sub:`2` + - y\ :sub:`1` + - y\ :sub:`0` * .. _MEDIA-BUS-FMT-UYVY8-1X16: - MEDIA_BUS_FMT_UYVY8_1X16 @@ -7142,7 +7743,7 @@ The following table list existing packed 36bit wide YUV formats. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{4.1cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _v4l2-mbus-pixelcode-yuv8-36bit: @@ -7330,7 +7931,7 @@ The following table list existing packed 48bit wide YUV formats. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{5.6cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _v4l2-mbus-pixelcode-yuv8-48bit: @@ -7761,7 +8362,7 @@ The following table lists existing HSV/HSL formats. .. raw:: latex - \normalsize + \endgroup JPEG Compressed Formats @@ -7783,7 +8384,7 @@ The following table lists existing JPEG compressed formats. .. _v4l2-mbus-pixelcode-jpeg: -.. tabularcolumns:: |p{6.0cm}|p{1.4cm}|p{10.1cm}| +.. tabularcolumns:: |p{6.0cm}|p{1.4cm}|p{9.9cm}| .. flat-table:: JPEG Formats :header-rows: 1 @@ -7816,7 +8417,7 @@ formats. .. _v4l2-mbus-pixelcode-vendor-specific: -.. tabularcolumns:: |p{8.0cm}|p{1.4cm}|p{7.7cm}| +.. tabularcolumns:: |p{8.0cm}|p{1.4cm}|p{7.9cm}| .. flat-table:: Vendor and device specific formats :header-rows: 1 @@ -7831,3 +8432,284 @@ formats. - 0x5001 - Interleaved raw UYVY and JPEG image format with embedded meta-data used by Samsung S3C73MX camera sensors. + +.. _v4l2-mbus-metadata-fmts: + +Metadata Formats +^^^^^^^^^^^^^^^^ + +This section lists all metadata formats. + +The following table lists the existing metadata formats. + +.. tabularcolumns:: |p{8.0cm}|p{1.4cm}|p{7.9cm}| + +.. flat-table:: Metadata formats + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Comments + * .. _MEDIA-BUS-FMT-METADATA-FIXED: + + - MEDIA_BUS_FMT_METADATA_FIXED + - 0x7001 + - This format should be used when the same driver handles + both sides of the link and the bus format is a fixed + metadata format that is not configurable from userspace. + Width and height will be set to 0 for this format. + +Generic Serial Metadata Formats +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Generic serial metadata formats are used on serial buses where the actual data +content is more or less device specific but the data is transmitted and received +by multiple devices that do not process the data in any way, simply writing +it to system memory for processing in software at the end of the pipeline. + +"b" in an array cell signifies a byte of data, followed by the number of the bit +and finally the bit number in subscript. "x" indicates a padding bit. + +.. _media-bus-format-generic-meta: + +.. cssclass: longtable + +.. flat-table:: Generic Serial Metadata Formats + :header-rows: 2 + :stub-columns: 0 + + * - Identifier + - Code + - + - :cspan:`23` Data organization within bus :term:`Data Unit` + * - + - + - Bit + - 23 + - 22 + - 21 + - 20 + - 19 + - 18 + - 17 + - 16 + - 15 + - 14 + - 13 + - 12 + - 11 + - 10 + - 9 + - 8 + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + * .. _MEDIA-BUS-FMT-META-8: + + - MEDIA_BUS_FMT_META_8 + - 0x8001 + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - b0\ :sub:`7` + - b0\ :sub:`6` + - b0\ :sub:`5` + - b0\ :sub:`4` + - b0\ :sub:`3` + - b0\ :sub:`2` + - b0\ :sub:`1` + - b0\ :sub:`0` + * .. _MEDIA-BUS-FMT-META-10: + + - MEDIA_BUS_FMT_META_10 + - 0x8002 + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - b0\ :sub:`7` + - b0\ :sub:`6` + - b0\ :sub:`5` + - b0\ :sub:`4` + - b0\ :sub:`3` + - b0\ :sub:`2` + - b0\ :sub:`1` + - b0\ :sub:`0` + - x + - x + * .. _MEDIA-BUS-FMT-META-12: + + - MEDIA_BUS_FMT_META_12 + - 0x8003 + - + - + - + - + - + - + - + - + - + - + - + - + - + - b0\ :sub:`7` + - b0\ :sub:`6` + - b0\ :sub:`5` + - b0\ :sub:`4` + - b0\ :sub:`3` + - b0\ :sub:`2` + - b0\ :sub:`1` + - b0\ :sub:`0` + - x + - x + - x + - x + * .. _MEDIA-BUS-FMT-META-14: + + - MEDIA_BUS_FMT_META_14 + - 0x8004 + - + - + - + - + - + - + - + - + - + - + - + - b0\ :sub:`7` + - b0\ :sub:`6` + - b0\ :sub:`5` + - b0\ :sub:`4` + - b0\ :sub:`3` + - b0\ :sub:`2` + - b0\ :sub:`1` + - b0\ :sub:`0` + - x + - x + - x + - x + - x + - x + * .. _MEDIA-BUS-FMT-META-16: + + - MEDIA_BUS_FMT_META_16 + - 0x8005 + - + - + - + - + - + - + - + - + - + - b0\ :sub:`7` + - b0\ :sub:`6` + - b0\ :sub:`5` + - b0\ :sub:`4` + - b0\ :sub:`3` + - b0\ :sub:`2` + - b0\ :sub:`1` + - b0\ :sub:`0` + - x + - x + - x + - x + - x + - x + - x + - x + * .. _MEDIA-BUS-FMT-META-20: + + - MEDIA_BUS_FMT_META_20 + - 0x8006 + - + - + - + - + - + - b0\ :sub:`7` + - b0\ :sub:`6` + - b0\ :sub:`5` + - b0\ :sub:`4` + - b0\ :sub:`3` + - b0\ :sub:`2` + - b0\ :sub:`1` + - b0\ :sub:`0` + - x + - x + - x + - x + - x + - x + - x + - x + - x + - x + - x + - x + * .. _MEDIA-BUS-FMT-META-24: + + - MEDIA_BUS_FMT_META_24 + - 0x8007 + - + - b0\ :sub:`7` + - b0\ :sub:`6` + - b0\ :sub:`5` + - b0\ :sub:`4` + - b0\ :sub:`3` + - b0\ :sub:`2` + - b0\ :sub:`1` + - b0\ :sub:`0` + - x + - x + - x + - x + - x + - x + - x + - x + - x + - x + - x + - x + - x + - x + - x + - x diff --git a/Documentation/userspace-api/media/v4l/subdev-image-processing-crop.svg b/Documentation/userspace-api/media/v4l/subdev-image-processing-crop.svg index 109bbcebd3b4..d92311281e01 100644 --- a/Documentation/userspace-api/media/v4l/subdev-image-processing-crop.svg +++ b/Documentation/userspace-api/media/v4l/subdev-image-processing-crop.svg @@ -1,14 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" diff --git a/Documentation/userspace-api/media/v4l/subdev-image-processing-full.svg b/Documentation/userspace-api/media/v4l/subdev-image-processing-full.svg index cfdb7532d5b6..864a594ff8d0 100644 --- a/Documentation/userspace-api/media/v4l/subdev-image-processing-full.svg +++ b/Documentation/userspace-api/media/v4l/subdev-image-processing-full.svg @@ -1,14 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" diff --git a/Documentation/userspace-api/media/v4l/subdev-image-processing-scaling-multi-source.svg b/Documentation/userspace-api/media/v4l/subdev-image-processing-scaling-multi-source.svg index f7f1379d30a6..b75755d31f15 100644 --- a/Documentation/userspace-api/media/v4l/subdev-image-processing-scaling-multi-source.svg +++ b/Documentation/userspace-api/media/v4l/subdev-image-processing-scaling-multi-source.svg @@ -1,14 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" diff --git a/Documentation/userspace-api/media/v4l/tch-formats.rst b/Documentation/userspace-api/media/v4l/tch-formats.rst index f83aec85fd76..8c941ff9e200 100644 --- a/Documentation/userspace-api/media/v4l/tch-formats.rst +++ b/Documentation/userspace-api/media/v4l/tch-formats.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _tch-formats: diff --git a/Documentation/userspace-api/media/v4l/tuner.rst b/Documentation/userspace-api/media/v4l/tuner.rst index 02a396eb6613..e2c53c3abdc6 100644 --- a/Documentation/userspace-api/media/v4l/tuner.rst +++ b/Documentation/userspace-api/media/v4l/tuner.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _tuner: diff --git a/Documentation/userspace-api/media/v4l/user-func.rst b/Documentation/userspace-api/media/v4l/user-func.rst index bf77c842718e..6f661138801c 100644 --- a/Documentation/userspace-api/media/v4l/user-func.rst +++ b/Documentation/userspace-api/media/v4l/user-func.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _user-func: @@ -69,6 +62,7 @@ Function Reference vidioc-query-dv-timings vidioc-querystd vidioc-reqbufs + vidioc-remove-bufs vidioc-s-hw-freq-seek vidioc-streamon vidioc-subdev-enum-frame-interval @@ -77,7 +71,9 @@ Function Reference vidioc-subdev-g-crop vidioc-subdev-g-fmt vidioc-subdev-g-frame-interval + vidioc-subdev-g-routing vidioc-subdev-g-selection + vidioc-subdev-g-client-cap vidioc-subdev-querycap vidioc-subscribe-event func-mmap diff --git a/Documentation/userspace-api/media/v4l/userp.rst b/Documentation/userspace-api/media/v4l/userp.rst index 2d0fa7353066..db224f9b611e 100644 --- a/Documentation/userspace-api/media/v4l/userp.rst +++ b/Documentation/userspace-api/media/v4l/userp.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _userp: @@ -85,10 +79,10 @@ buffers it must wait until an empty buffer can be dequeued and reused. Two methods exist to suspend execution of the application until one or more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the -``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` function, +``O_NONBLOCK`` flag was given to the :c:func:`open()` function, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN`` error code when no buffer is available. The :ref:`select() -<func-select>` or :ref:`poll() <func-poll>` function are always +<func-select>` or :c:func:`poll()` function are always available. To start and stop capturing or output applications call the @@ -108,7 +102,7 @@ Drivers implementing user pointer I/O must support the :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the -:ref:`select() <func-select>` and :ref:`poll() <func-poll>` function. [#f2]_ +:c:func:`select()` and :c:func:`poll()` function. [#f2]_ .. [#f1] We expect that frequently used buffers are typically not swapped out. @@ -123,6 +117,6 @@ and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the because an application may share them with other processes. .. [#f2] - At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are - the same, and :ref:`select() <func-select>` is too important to be optional. + At the driver level :c:func:`select()` and :c:func:`poll()` are + the same, and :c:func:`select()` is too important to be optional. The rest should be evident. diff --git a/Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst b/Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst index 5c6f351b2443..1cb1531c1e52 100644 --- a/Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst +++ b/Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2-selection-flags: @@ -13,10 +6,16 @@ Selection flags *************** -.. tabularcolumns:: |p{5.2cm}|p{2.0cm}|p{6.5cm}|p{1.2cm}|p{1.6cm}| - .. _v4l2-selection-flags-table: +.. raw:: latex + + \small + +.. tabularcolumns:: |p{5.6cm}|p{2.0cm}|p{6.5cm}|p{1.2cm}|p{1.2cm}| + +.. cssclass:: longtable + .. flat-table:: Selection flag definitions :header-rows: 1 :stub-columns: 0 @@ -49,3 +48,7 @@ Selection flags inside the subdevice to all further processing steps. - No - Yes + +.. raw:: latex + + \normalsize diff --git a/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst b/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst index 69f500093aa2..b46bae984f35 100644 --- a/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst +++ b/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2-selection-targets: @@ -19,7 +12,13 @@ of the two interfaces they are used. .. _v4l2-selection-targets-table: -.. tabularcolumns:: |p{6.0cm}|p{1.4cm}|p{7.4cm}|p{1.2cm}|p{1.4cm}| +.. raw:: latex + + \small + +.. tabularcolumns:: |p{6.2cm}|p{1.4cm}|p{7.3cm}|p{1.2cm}|p{0.8cm}| + +.. cssclass:: longtable .. flat-table:: Selection target definitions :header-rows: 1 @@ -76,3 +75,7 @@ of the two interfaces they are used. modified by hardware. - Yes - No + +.. raw:: latex + + \normalsize diff --git a/Documentation/userspace-api/media/v4l/v4l2.rst b/Documentation/userspace-api/media/v4l/v4l2.rst index ab7c97c39b97..cf8ae56a008c 100644 --- a/Documentation/userspace-api/media/v4l/v4l2.rst +++ b/Documentation/userspace-api/media/v4l/v4l2.rst @@ -1,13 +1,6 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. include:: <isonum.txt> + .. _v4l2spec: ############################ @@ -18,13 +11,8 @@ This part describes the Video for Linux API version 2 (V4L2 API) specification. **Revision 4.5** -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :numbered: :maxdepth: 5 @@ -63,6 +51,7 @@ Authors, in alphabetical order: - Figa, Tomasz <tfiga@chromium.org> - Documented the memory-to-memory decoder interface. + - Documented the memory-to-memory encoder interface. - H Schimek, Michael <mschimek@gmx.at> @@ -75,6 +64,7 @@ Authors, in alphabetical order: - Osciak, Pawel <posciak@chromium.org> - Documented the memory-to-memory decoder interface. + - Documented the memory-to-memory encoder interface. - Osciak, Pawel <pawel@osciak.com> diff --git a/Documentation/userspace-api/media/v4l/v4l2grab-example.rst b/Documentation/userspace-api/media/v4l/v4l2grab-example.rst index 270738876f72..b323be42c580 100644 --- a/Documentation/userspace-api/media/v4l/v4l2grab-example.rst +++ b/Documentation/userspace-api/media/v4l/v4l2grab-example.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _v4l2grab-example: diff --git a/Documentation/userspace-api/media/v4l/v4l2grab.c.rst b/Documentation/userspace-api/media/v4l/v4l2grab.c.rst index a21ff357a830..1a55e3617ea8 100644 --- a/Documentation/userspace-api/media/v4l/v4l2grab.c.rst +++ b/Documentation/userspace-api/media/v4l/v4l2grab.c.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later file: media/v4l/v4l2grab.c ========================== @@ -53,7 +46,7 @@ file: media/v4l/v4l2grab.c } while (r == -1 && ((errno == EINTR) || (errno == EAGAIN))); if (r == -1) { - fprintf(stderr, "error %d, %s\\n", errno, strerror(errno)); + fprintf(stderr, "error %d, %s\n", errno, strerror(errno)); exit(EXIT_FAILURE); } } @@ -87,11 +80,11 @@ file: media/v4l/v4l2grab.c fmt.fmt.pix.field = V4L2_FIELD_INTERLACED; xioctl(fd, VIDIOC_S_FMT, &fmt); if (fmt.fmt.pix.pixelformat != V4L2_PIX_FMT_RGB24) { - printf("Libv4l didn't accept RGB24 format. Can't proceed.\\n"); + printf("Libv4l didn't accept RGB24 format. Can't proceed.\n"); exit(EXIT_FAILURE); } if ((fmt.fmt.pix.width != 640) || (fmt.fmt.pix.height != 480)) - printf("Warning: driver is sending image at %dx%d\\n", + printf("Warning: driver is sending image at %dx%d\n", fmt.fmt.pix.width, fmt.fmt.pix.height); CLEAR(req); @@ -141,7 +134,7 @@ file: media/v4l/v4l2grab.c tv.tv_usec = 0; r = select(fd + 1, &fds, NULL, NULL, &tv); - } while ((r == -1 && (errno = EINTR))); + } while ((r == -1 && (errno == EINTR))); if (r == -1) { perror("select"); return errno; @@ -158,7 +151,7 @@ file: media/v4l/v4l2grab.c perror("Cannot open image"); exit(EXIT_FAILURE); } - fprintf(fout, "P6\\n%d %d 255\\n", + fprintf(fout, "P6\n%d %d 255\n", fmt.fmt.pix.width, fmt.fmt.pix.height); fwrite(buffers[buf.index].start, buf.bytesused, 1, fout); fclose(fout); diff --git a/Documentation/userspace-api/media/v4l/vbi_525.svg b/Documentation/userspace-api/media/v4l/vbi_525.svg index b7d09057617e..1951de29a111 100644 --- a/Documentation/userspace-api/media/v4l/vbi_525.svg +++ b/Documentation/userspace-api/media/v4l/vbi_525.svg @@ -1,14 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" @@ -23,7 +14,7 @@ xml:space="preserve" width="208.73068mm" height="51.395489mm" - viewBox="0 0 739.59691 182.11" + viewBox="0 0 788.90338 194.25067" sodipodi:docname="vbi_525.svg"><sodipodi:namedview pagecolor="#ffffff" bordercolor="#666666" @@ -34,7 +25,7 @@ inkscape:pageopacity="0" inkscape:pageshadow="2" inkscape:window-width="1920" - inkscape:window-height="997" + inkscape:window-height="1000" id="namedview4" showgrid="false" fit-margin-top="0" diff --git a/Documentation/userspace-api/media/v4l/vbi_625.svg b/Documentation/userspace-api/media/v4l/vbi_625.svg index e1f5e8552c37..21f524de3aed 100644 --- a/Documentation/userspace-api/media/v4l/vbi_625.svg +++ b/Documentation/userspace-api/media/v4l/vbi_625.svg @@ -1,14 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" @@ -23,7 +14,7 @@ xml:space="preserve" width="209.46608mm" height="51.576824mm" - viewBox="0 0 742.20265 182.75252" + viewBox="0 0 791.6828 194.93604" sodipodi:docname="vbi_625.svg"><sodipodi:namedview pagecolor="#ffffff" bordercolor="#666666" @@ -34,7 +25,7 @@ inkscape:pageopacity="0" inkscape:pageshadow="2" inkscape:window-width="1920" - inkscape:window-height="997" + inkscape:window-height="1000" id="namedview4" showgrid="false" fit-margin-top="0" diff --git a/Documentation/userspace-api/media/v4l/vbi_hsync.svg b/Documentation/userspace-api/media/v4l/vbi_hsync.svg index 77606a7b00a4..d360251e5f20 100644 --- a/Documentation/userspace-api/media/v4l/vbi_hsync.svg +++ b/Documentation/userspace-api/media/v4l/vbi_hsync.svg @@ -1,14 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation, with no Invariant Sections, no Front-Cover Texts - and no Back-Cover Texts. A copy of the license is included at - Documentation/userspace-api/media/fdl-appendix.rst. - - TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ---> +<!-- SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" @@ -23,7 +14,7 @@ xml:space="preserve" width="192.39857mm" height="146.83536mm" - viewBox="0 0 681.72724 520.28277" + viewBox="0 0 727.17572 554.96826" sodipodi:docname="vbi_hsync.svg"><sodipodi:namedview pagecolor="#ffffff" bordercolor="#666666" @@ -34,7 +25,7 @@ inkscape:pageopacity="0" inkscape:pageshadow="2" inkscape:window-width="1920" - inkscape:window-height="997" + inkscape:window-height="1000" id="namedview4" showgrid="false" inkscape:zoom="1.5350601" diff --git a/Documentation/userspace-api/media/v4l/video.rst b/Documentation/userspace-api/media/v4l/video.rst index 9b73dba0eb8d..f8f69a57602c 100644 --- a/Documentation/userspace-api/media/v4l/video.rst +++ b/Documentation/userspace-api/media/v4l/video.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _video: diff --git a/Documentation/userspace-api/media/v4l/videodev.rst b/Documentation/userspace-api/media/v4l/videodev.rst index c8244b895802..c866fec417eb 100644 --- a/Documentation/userspace-api/media/v4l/videodev.rst +++ b/Documentation/userspace-api/media/v4l/videodev.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _videodev: diff --git a/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst b/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst index e1afc5b504c2..49232c9006c2 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_CREATE_BUFS: @@ -18,24 +12,22 @@ Name VIDIOC_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_CREATE_BUFS, struct v4l2_create_buffers *argp ) - :name: VIDIOC_CREATE_BUFS +.. c:macro:: VIDIOC_CREATE_BUFS +``int ioctl(int fd, VIDIOC_CREATE_BUFS, struct v4l2_create_buffers *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_create_buffers`. - Description =========== @@ -78,10 +70,9 @@ the actual number allocated and the starting index in the ``count`` and the ``index`` fields respectively. On return ``count`` can be smaller than the number requested. - .. c:type:: v4l2_create_buffers -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_create_buffers :header-rows: 0 @@ -120,12 +111,21 @@ than the number requested. If you want to just query the capabilities without making any other changes, then set ``count`` to 0, ``memory`` to ``V4L2_MEMORY_MMAP`` and ``format.type`` to the buffer type. + * - __u32 - - ``reserved``\ [7] + - ``flags`` + - Specifies additional buffer management attributes. + See :ref:`memory-flags`. + * - __u32 + - ``max_num_buffers`` + - If the V4L2_BUF_CAP_SUPPORTS_MAX_NUM_BUFFERS capability flag is set + this field indicates the maximum possible number of buffers + for this queue. + * - __u32 + - ``reserved``\ [5] - A place holder for future extensions. Drivers and applications must set the array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst b/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst index 035ed9d577ae..7f10f0bbcfd3 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_CROPCAP: @@ -18,24 +12,22 @@ Name VIDIOC_CROPCAP - Information about the video cropping and scaling abilities - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_CROPCAP, struct v4l2_cropcap *argp ) - :name: VIDIOC_CROPCAP +.. c:macro:: VIDIOC_CROPCAP +``int ioctl(int fd, VIDIOC_CROPCAP, struct v4l2_cropcap *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_cropcap`. - Description =========== @@ -53,7 +45,7 @@ overlay devices. .. c:type:: v4l2_cropcap -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_cropcap :header-rows: 0 @@ -79,7 +71,7 @@ overlay devices. - Default cropping rectangle, it shall cover the "whole picture". Assuming pixel aspect 1/1 this could be for example a 640 × 480 rectangle for NTSC, a 768 × 576 rectangle for PAL and SECAM - centered over the active picture area. The same co-ordinate system + centered over the active picture area. The same coordinate system as for ``bounds`` is used. * - struct :c:type:`v4l2_fract` - ``pixelaspect`` @@ -102,10 +94,9 @@ overlay devices. Starting with kernel 4.13 both variations are allowed. - .. _v4l2-rect-crop: -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_rect :header-rows: 0 @@ -127,7 +118,6 @@ overlay devices. - ``height`` - Height of the rectangle, in pixels. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst index 16078a2d3e3d..1a1e093936f1 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_DBG_G_CHIP_INFO: @@ -18,24 +12,22 @@ Name VIDIOC_DBG_G_CHIP_INFO - Identify the chips on a TV card - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_DBG_G_CHIP_INFO, struct v4l2_dbg_chip_info *argp ) - :name: VIDIOC_DBG_G_CHIP_INFO +.. c:macro:: VIDIOC_DBG_G_CHIP_INFO +``int ioctl(int fd, VIDIOC_DBG_G_CHIP_INFO, struct v4l2_dbg_chip_info *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_dbg_chip_info`. - Description =========== @@ -83,8 +75,7 @@ is available from the LinuxTV v4l-dvb repository; see `https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access instructions. - -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{6.6cm}| .. _name-v4l2-dbg-match: @@ -110,8 +101,7 @@ instructions. - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_dbg_chip_info @@ -137,8 +127,7 @@ instructions. - Reserved fields, both application and driver must set these to 0. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _name-chip-match-types: @@ -155,7 +144,6 @@ instructions. - 4 - Match the nth sub-device. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst index 6311a63278a5..53f10c7319b2 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_DBG_G_REGISTER: @@ -18,27 +12,26 @@ Name VIDIOC_DBG_G_REGISTER - VIDIOC_DBG_S_REGISTER - Read or write hardware registers - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_DBG_G_REGISTER, struct v4l2_dbg_register *argp ) - :name: VIDIOC_DBG_G_REGISTER +.. c:macro:: VIDIOC_DBG_G_REGISTER + +``int ioctl(int fd, VIDIOC_DBG_G_REGISTER, struct v4l2_dbg_register *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_DBG_S_REGISTER, const struct v4l2_dbg_register *argp ) - :name: VIDIOC_DBG_S_REGISTER +.. c:macro:: VIDIOC_DBG_S_REGISTER +``int ioctl(int fd, VIDIOC_DBG_S_REGISTER, const struct v4l2_dbg_register *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_dbg_register`. - Description =========== @@ -92,8 +85,7 @@ It is available from the LinuxTV v4l-dvb repository; see `https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access instructions. - -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{6.6cm}| .. c:type:: v4l2_dbg_match @@ -119,7 +111,6 @@ instructions. - - .. c:type:: v4l2_dbg_register .. flat-table:: struct v4l2_dbg_register @@ -140,8 +131,7 @@ instructions. - The value read from, or to be written into the register. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _chip-match-types: @@ -158,7 +148,6 @@ instructions. - 4 - Match the nth sub-device. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst b/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst index 7986a248bff9..7ccae3b91616 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_DECODER_CMD: @@ -18,28 +12,26 @@ Name VIDIOC_DECODER_CMD - VIDIOC_TRY_DECODER_CMD - Execute an decoder command - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_DECODER_CMD, struct v4l2_decoder_cmd *argp ) - :name: VIDIOC_DECODER_CMD +.. c:macro:: VIDIOC_DECODER_CMD +``int ioctl(int fd, VIDIOC_DECODER_CMD, struct v4l2_decoder_cmd *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_TRY_DECODER_CMD, struct v4l2_decoder_cmd *argp ) - :name: VIDIOC_TRY_DECODER_CMD +.. c:macro:: VIDIOC_TRY_DECODER_CMD +``int ioctl(int fd, VIDIOC_TRY_DECODER_CMD, struct v4l2_decoder_cmd *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` pointer to struct :c:type:`v4l2_decoder_cmd`. - Description =========== @@ -54,11 +46,11 @@ this structure. The ``cmd`` field must contain the command code. Some commands use the ``flags`` field for additional information. -A :ref:`write() <func-write>` or :ref:`VIDIOC_STREAMON` +A :c:func:`write()` or :ref:`VIDIOC_STREAMON` call sends an implicit START command to the decoder if it has not been started yet. Applies to both queues of mem2mem decoders. -A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` +A :c:func:`close()` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call of a streaming file descriptor sends an implicit immediate STOP command to the decoder, and all buffered data is discarded. Applies to both queues of mem2mem decoders. @@ -67,8 +59,7 @@ In principle, these ioctls are optional, not all drivers may support them. They introduced in Linux 3.3. They are, however, mandatory for stateful mem2mem decoders (as further documented in :ref:`decoder`). - -.. tabularcolumns:: |p{1.1cm}|p{2.4cm}|p{1.2cm}|p{1.6cm}|p{10.6cm}| +.. tabularcolumns:: |p{2.0cm}|p{1.1cm}|p{2.2cm}|p{11.8cm}| .. c:type:: v4l2_decoder_cmd @@ -138,8 +129,9 @@ introduced in Linux 3.3. They are, however, mandatory for stateful mem2mem decod - +.. tabularcolumns:: |p{5.6cm}|p{0.6cm}|p{11.1cm}| -.. tabularcolumns:: |p{5.6cm}|p{0.6cm}|p{11.3cm}| +.. cssclass:: longtable .. _decoder-cmds: diff --git a/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst b/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst index a9a176d5256d..8db103760930 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_DQEVENT: @@ -18,24 +12,22 @@ Name VIDIOC_DQEVENT - Dequeue event - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_DQEVENT, struct v4l2_event *argp ) - :name: VIDIOC_DQEVENT +.. c:macro:: VIDIOC_DQEVENT +``int ioctl(int fd, VIDIOC_DQEVENT, struct v4l2_event *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_event`. - Description =========== @@ -45,12 +37,10 @@ structure are filled by the driver. The file handle will also receive exceptions which the application may get by e.g. using the select system call. - -.. tabularcolumns:: |p{3.0cm}|p{4.4cm}|p{2.4cm}|p{7.7cm}| - .. c:type:: v4l2_event -.. cssclass: longtable +.. tabularcolumns:: |p{3.0cm}|p{3.4cm}|p{10.9cm}| + .. flat-table:: struct v4l2_event :header-rows: 0 @@ -107,8 +97,7 @@ call. zero. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.2cm}|p{2.6cm}|p{8.5cm}| .. cssclass:: longtable @@ -198,8 +187,7 @@ call. - Base event number for driver-private events. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_event_vsync @@ -213,8 +201,7 @@ call. - The upcoming field. See enum :c:type:`v4l2_field`. - -.. tabularcolumns:: |p{3.5cm}|p{3.0cm}|p{1.8cm}|p{8.5cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.0cm}|p{10.8cm}| .. c:type:: v4l2_event_ctrl @@ -260,12 +247,11 @@ call. :ref:`v4l2_queryctrl <v4l2-queryctrl>`. * - __s32 - ``default_value`` - - The default value value of the control. See struct + - The default value of the control. See struct :ref:`v4l2_queryctrl <v4l2-queryctrl>`. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_event_frame_sync @@ -279,8 +265,7 @@ call. - The sequence number of the frame being received. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_event_src_change @@ -295,8 +280,7 @@ call. :ref:`src-changes-flags`. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_event_motion_det @@ -325,8 +309,7 @@ call. automatically assigned to the default region 0. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _ctrl-changes-flags: @@ -349,10 +332,14 @@ call. - 0x0004 - This control event was triggered because the minimum, maximum, step or the default value of the control changed. + * - ``V4L2_EVENT_CTRL_CH_DIMENSIONS`` + - 0x0008 + - This control event was triggered because the dimensions of the + control changed. Note that the number of dimensions remains the + same. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _src-changes-flags: @@ -382,7 +369,6 @@ call. loss of signal and so restarting streaming I/O is required in order for the hardware to synchronize to the video signal. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst b/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst index 60730c32bfe4..8ced100bb156 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_DV_TIMINGS_CAP: @@ -18,27 +12,26 @@ Name VIDIOC_DV_TIMINGS_CAP - VIDIOC_SUBDEV_DV_TIMINGS_CAP - The capabilities of the Digital Video receiver/transmitter - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_DV_TIMINGS_CAP, struct v4l2_dv_timings_cap *argp ) - :name: VIDIOC_DV_TIMINGS_CAP +.. c:macro:: VIDIOC_DV_TIMINGS_CAP + +``int ioctl(int fd, VIDIOC_DV_TIMINGS_CAP, struct v4l2_dv_timings_cap *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_DV_TIMINGS_CAP, struct v4l2_dv_timings_cap *argp ) - :name: VIDIOC_SUBDEV_DV_TIMINGS_CAP +.. c:macro:: VIDIOC_SUBDEV_DV_TIMINGS_CAP +``int ioctl(int fd, VIDIOC_SUBDEV_DV_TIMINGS_CAP, struct v4l2_dv_timings_cap *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_dv_timings_cap`. - Description =========== @@ -62,8 +55,7 @@ the desired pad number in the struct zero the ``reserved`` array. Attempts to query capabilities on a pad that doesn't support them will return an ``EINVAL`` error code. - -.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.3cm}| +.. tabularcolumns:: |p{1.2cm}|p{3.2cm}|p{12.9cm}| .. c:type:: v4l2_bt_timings_cap @@ -104,8 +96,7 @@ that doesn't support them will return an ``EINVAL`` error code. Drivers must set the array to zero. - -.. tabularcolumns:: |p{1.0cm}|p{4.0cm}|p{3.5cm}|p{9.2cm}| +.. tabularcolumns:: |p{4.4cm}|p{3.6cm}|p{9.3cm}| .. c:type:: v4l2_dv_timings_cap @@ -137,7 +128,7 @@ that doesn't support them will return an ``EINVAL`` error code. * - } - -.. tabularcolumns:: |p{7.0cm}|p{10.5cm}| +.. tabularcolumns:: |p{7.2cm}|p{10.3cm}| .. _dv-bt-cap-capabilities: @@ -160,7 +151,6 @@ that doesn't support them will return an ``EINVAL`` error code. - Can support non-standard timings, i.e. timings not belonging to the standards set in the ``standards`` field. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst b/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst index 16269b3b1715..2b5867a68b31 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENCODER_CMD: @@ -18,22 +12,22 @@ Name VIDIOC_ENCODER_CMD - VIDIOC_TRY_ENCODER_CMD - Execute an encoder command - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENCODER_CMD, struct v4l2_encoder_cmd *argp ) - :name: VIDIOC_ENCODER_CMD +.. c:macro:: VIDIOC_ENCODER_CMD + +``int ioctl(int fd, VIDIOC_ENCODER_CMD, struct v4l2_encoder_cmd *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_TRY_ENCODER_CMD, struct v4l2_encoder_cmd *argp ) - :name: VIDIOC_TRY_ENCODER_CMD +.. c:macro:: VIDIOC_TRY_ENCODER_CMD +``int ioctl(int fd, VIDIOC_TRY_ENCODER_CMD, struct v4l2_encoder_cmd *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_encoder_cmd`. @@ -51,28 +45,28 @@ To send a command applications must initialize all fields of a struct ``VIDIOC_ENCODER_CMD`` or ``VIDIOC_TRY_ENCODER_CMD`` with a pointer to this structure. -The ``cmd`` field must contain the command code. The ``flags`` field is -currently only used by the STOP command and contains one bit: If the -``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag is set, encoding will continue -until the end of the current *Group Of Pictures*, otherwise it will stop -immediately. +The ``cmd`` field must contain the command code. Some commands use the +``flags`` field for additional information. -A :ref:`read() <func-read>` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` -call sends an implicit START command to the encoder if it has not been -started yet. After a STOP command, :ref:`read() <func-read>` calls will read +After a STOP command, :c:func:`read()` calls will read the remaining data buffered by the driver. When the buffer is empty, -:ref:`read() <func-read>` will return zero and the next :ref:`read() <func-read>` +:c:func:`read()` will return zero and the next :c:func:`read()` call will restart the encoder. -A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` +A :c:func:`read()` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` +call sends an implicit START command to the encoder if it has not been +started yet. Applies to both queues of mem2mem encoders. + +A :c:func:`close()` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call of a streaming file descriptor sends an implicit immediate STOP to -the encoder, and all buffered data is discarded. +the encoder, and all buffered data is discarded. Applies to both queues of +mem2mem encoders. These ioctls are optional, not all drivers may support them. They were -introduced in Linux 2.6.21. - +introduced in Linux 2.6.21. They are, however, mandatory for stateful mem2mem +encoders (as further documented in :ref:`encoder`). -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_encoder_cmd @@ -95,8 +89,7 @@ introduced in Linux 2.6.21. the array to zero. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _encoder-cmds: @@ -109,21 +102,24 @@ introduced in Linux 2.6.21. - 0 - Start the encoder. When the encoder is already running or paused, this command does nothing. No flags are defined for this command. + + For a device implementing the :ref:`encoder`, once the drain sequence + is initiated with the ``V4L2_ENC_CMD_STOP`` command, it must be driven + to completion before this command can be invoked. Any attempt to + invoke the command while the drain sequence is in progress will trigger + an ``EBUSY`` error code. See :ref:`encoder` for more details. * - ``V4L2_ENC_CMD_STOP`` - 1 - Stop the encoder. When the ``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag is set, encoding will continue until the end of the current *Group Of Pictures*, otherwise encoding will stop immediately. When the - encoder is already stopped, this command does nothing. mem2mem - encoders will send a ``V4L2_EVENT_EOS`` event when the last frame - has been encoded and all frames are ready to be dequeued and will - set the ``V4L2_BUF_FLAG_LAST`` buffer flag on the last buffer of - the capture queue to indicate there will be no new buffers - produced to dequeue. This buffer may be empty, indicated by the - driver setting the ``bytesused`` field to 0. Once the - ``V4L2_BUF_FLAG_LAST`` flag was set, the - :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore, - but return an ``EPIPE`` error code. + encoder is already stopped, this command does nothing. + + For a device implementing the :ref:`encoder`, the command will initiate + the drain sequence as documented in :ref:`encoder`. No flags or other + arguments are accepted in this case. Any attempt to invoke the command + again before the sequence completes will trigger an ``EBUSY`` error + code. * - ``V4L2_ENC_CMD_PAUSE`` - 2 - Pause the encoder. When the encoder has not been started yet, the @@ -137,8 +133,7 @@ introduced in Linux 2.6.21. the encoder is already running, this command does nothing. No flags are defined for this command. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _encoder-flags: @@ -152,6 +147,7 @@ introduced in Linux 2.6.21. - Stop encoding at the end of the current *Group Of Pictures*, rather than immediately. + Does not apply to :ref:`encoder`. Return Value ============ @@ -160,6 +156,11 @@ On success 0 is returned, on error -1 and the ``errno`` variable is set appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. +EBUSY + A drain sequence of a device implementing the :ref:`encoder` is still in + progress. It is not allowed to issue another encoder command until it + completes. + EINVAL The ``cmd`` field is invalid. diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst index 89d6b860193a..a91c1a3f0e32 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUM_DV_TIMINGS: @@ -18,27 +12,26 @@ Name VIDIOC_ENUM_DV_TIMINGS - VIDIOC_SUBDEV_ENUM_DV_TIMINGS - Enumerate supported Digital Video timings - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUM_DV_TIMINGS, struct v4l2_enum_dv_timings *argp ) - :name: VIDIOC_ENUM_DV_TIMINGS +.. c:macro:: VIDIOC_ENUM_DV_TIMINGS + +``int ioctl(int fd, VIDIOC_ENUM_DV_TIMINGS, struct v4l2_enum_dv_timings *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUM_DV_TIMINGS, struct v4l2_enum_dv_timings *argp ) - :name: VIDIOC_SUBDEV_ENUM_DV_TIMINGS +.. c:macro:: VIDIOC_SUBDEV_ENUM_DV_TIMINGS +``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_DV_TIMINGS, struct v4l2_enum_dv_timings *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_enum_dv_timings`. - Description =========== @@ -72,10 +65,9 @@ pad number in the struct Attempts to enumerate timings on a pad that doesn't support them will return an ``EINVAL`` error code. - .. c:type:: v4l2_enum_dv_timings -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_enum_dv_timings :header-rows: 0 @@ -98,7 +90,6 @@ return an ``EINVAL`` error code. - ``timings`` - The timings. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst index a53dd3d7f7e2..0f69aa04607f 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUM_FMT: @@ -18,24 +12,22 @@ Name VIDIOC_ENUM_FMT - Enumerate image formats - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUM_FMT, struct v4l2_fmtdesc *argp ) - :name: VIDIOC_ENUM_FMT +.. c:macro:: VIDIOC_ENUM_FMT +``int ioctl(int fd, VIDIOC_ENUM_FMT, struct v4l2_fmtdesc *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_fmtdesc`. - Description =========== @@ -79,10 +71,11 @@ the ``mbus_code`` field is handled differently: formats shall not depend on the active configuration of the video device or device pipeline. +.. c:type:: v4l2_fmtdesc -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. cssclass:: longtable -.. c:type:: v4l2_fmtdesc +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_fmtdesc :header-rows: 0 @@ -92,7 +85,17 @@ the ``mbus_code`` field is handled differently: * - __u32 - ``index`` - Number of the format in the enumeration, set by the application. - This is in no way related to the ``pixelformat`` field. + This is in no way related to the ``pixelformat`` field. + When the index is ORed with ``V4L2_FMTDESC_FLAG_ENUM_ALL`` the + driver clears the flag and enumerates all the possible formats, + ignoring any limitations from the current configuration. Drivers + which do not support this flag always return an ``EINVAL`` + error code without clearing this flag. + Formats enumerated when using ``V4L2_FMTDESC_FLAG_ENUM_ALL`` flag + shouldn't be used when calling :c:func:`VIDIOC_ENUM_FRAMESIZES` + or :c:func:`VIDIOC_ENUM_FRAMEINTERVALS`. + ``V4L2_FMTDESC_FLAG_ENUM_ALL`` should only be used by drivers that + can return different format list depending on this flag. * - __u32 - ``type`` - Type of the data stream, set by the application. Only these types @@ -144,8 +147,9 @@ the ``mbus_code`` field is handled differently: zero. +.. tabularcolumns:: |p{8.4cm}|p{1.8cm}|p{7.1cm}| -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. cssclass:: longtable .. _fmtdesc-flags: @@ -167,18 +171,85 @@ the ``mbus_code`` field is handled differently: - The hardware decoder for this compressed bytestream format (aka coded format) is capable of parsing a continuous bytestream. Applications do not need to parse the bytestream themselves to find the boundaries - between frames/fields. This flag can only be used in combination with - the ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to compressed + between frames/fields. + + This flag can only be used in combination with the + ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to compressed formats only. This flag is valid for stateful decoders only. * - ``V4L2_FMT_FLAG_DYN_RESOLUTION`` - 0x0008 - Dynamic resolution switching is supported by the device for this compressed bytestream format (aka coded format). It will notify the user via the event ``V4L2_EVENT_SOURCE_CHANGE`` when changes in the video - parameters are detected. This flag can only be used in combination - with the ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to - compressed formats only. It is also only applies to stateful codecs. - + parameters are detected. + + This flag can only be used in combination with the + ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to + compressed formats only. This flag is valid for stateful codecs only. + * - ``V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL`` + - 0x0010 + - The hardware encoder supports setting the ``CAPTURE`` coded frame + interval separately from the ``OUTPUT`` raw frame interval. + Setting the ``OUTPUT`` raw frame interval with :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` + also sets the ``CAPTURE`` coded frame interval to the same value. + If this flag is set, then the ``CAPTURE`` coded frame interval can be + set to a different value afterwards. This is typically used for + offline encoding where the ``OUTPUT`` raw frame interval is used as + a hint for reserving hardware encoder resources and the ``CAPTURE`` coded + frame interval is the actual frame rate embedded in the encoded video + stream. + + This flag can only be used in combination with the + ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to + compressed formats only. This flag is valid for stateful encoders only. + * - ``V4L2_FMT_FLAG_CSC_COLORSPACE`` + - 0x0020 + - The driver allows the application to try to change the default + colorspace. This flag is relevant only for capture devices. + The application can ask to configure the colorspace of the capture device + when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with + :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set. + * - ``V4L2_FMT_FLAG_CSC_XFER_FUNC`` + - 0x0040 + - The driver allows the application to try to change the default + transfer function. This flag is relevant only for capture devices. + The application can ask to configure the transfer function of the capture + device when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with + :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set. + * - ``V4L2_FMT_FLAG_CSC_YCBCR_ENC`` + - 0x0080 + - The driver allows the application to try to change the default + Y'CbCr encoding. This flag is relevant only for capture devices. + The application can ask to configure the Y'CbCr encoding of the capture device + when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with + :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set. + * - ``V4L2_FMT_FLAG_CSC_HSV_ENC`` + - 0x0080 + - The driver allows the application to try to change the default + HSV encoding. This flag is relevant only for capture devices. + The application can ask to configure the HSV encoding of the capture device + when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with + :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set. + * - ``V4L2_FMT_FLAG_CSC_QUANTIZATION`` + - 0x0100 + - The driver allows the application to try to change the default + quantization. This flag is relevant only for capture devices. + The application can ask to configure the quantization of the capture + device when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with + :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set. + * - ``V4L2_FMT_FLAG_META_LINE_BASED`` + - 0x0200 + - The metadata format is line-based. In this case the ``width``, + ``height`` and ``bytesperline`` fields of :c:type:`v4l2_meta_format` are + valid. The buffer consists of ``height`` lines, each having ``width`` + Data Units of data and the offset (in bytes) between the beginning of + each two consecutive lines is ``bytesperline``. + * - ``V4L2_FMTDESC_FLAG_ENUM_ALL`` + - 0x80000000 + - When the applications ORs ``index`` with ``V4L2_FMTDESC_FLAG_ENUM_ALL`` flag + the driver enumerates all the possible pixel formats without taking care + of any already set configuration. Drivers which do not support this flag, + always return ``EINVAL`` without clearing this flag. Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst index 0e3db737371f..34cd39feaeaa 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUM_FRAMEINTERVALS: @@ -18,25 +12,23 @@ Name VIDIOC_ENUM_FRAMEINTERVALS - Enumerate frame intervals - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUM_FRAMEINTERVALS, struct v4l2_frmivalenum *argp ) - :name: VIDIOC_ENUM_FRAMEINTERVALS +.. c:macro:: VIDIOC_ENUM_FRAMEINTERVALS +``int ioctl(int fd, VIDIOC_ENUM_FRAMEINTERVALS, struct v4l2_frmivalenum *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_frmivalenum` that contains a pixel format and size and receives a frame interval. - Description =========== @@ -98,7 +90,6 @@ other ioctl calls while it runs the frame interval enumeration. frame_rate = 1 / frame_interval - Structs ======= @@ -106,11 +97,8 @@ In the structs below, *IN* denotes a value that has to be filled in by the application, *OUT* denotes values that the driver fills in. The application should zero out all members except for the *IN* fields. - .. c:type:: v4l2_frmival_stepwise -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: struct v4l2_frmival_stepwise :header-rows: 0 :stub-columns: 0 @@ -127,10 +115,9 @@ application should zero out all members except for the *IN* fields. - Frame interval step size [s]. - .. c:type:: v4l2_frmivalenum -.. tabularcolumns:: |p{1.8cm}|p{4.4cm}|p{2.4cm}|p{8.9cm}| +.. tabularcolumns:: |p{4.9cm}|p{3.3cm}|p{9.1cm}| .. flat-table:: struct v4l2_frmivalenum :header-rows: 0 @@ -165,19 +152,16 @@ application should zero out all members except for the *IN* fields. - * - __u32 - ``reserved[2]`` - - - Reserved space for future use. Must be zeroed by drivers and applications. - Enums ===== - .. c:type:: v4l2_frmivaltypes -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. flat-table:: enum v4l2_frmivaltypes :header-rows: 0 @@ -194,7 +178,6 @@ Enums - 3 - Step-wise defined frame interval. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst index 1934d7da9743..7271fe37ce3f 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUM_FRAMESIZES: @@ -18,26 +12,24 @@ Name VIDIOC_ENUM_FRAMESIZES - Enumerate frame sizes - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUM_FRAMESIZES, struct v4l2_frmsizeenum *argp ) - :name: VIDIOC_ENUM_FRAMESIZES +.. c:macro:: VIDIOC_ENUM_FRAMESIZES +``int ioctl(int fd, VIDIOC_ENUM_FRAMESIZES, struct v4l2_frmsizeenum *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_frmsizeenum` that contains an index and pixel format and receives a frame width and height. - Description =========== @@ -88,7 +80,6 @@ without any interaction from the application itself. This means that the enumeration data is consistent if the application does not perform any other ioctl calls while it runs the frame size enumeration. - Structs ======= @@ -96,11 +87,8 @@ In the structs below, *IN* denotes a value that has to be filled in by the application, *OUT* denotes values that the driver fills in. The application should zero out all members except for the *IN* fields. - .. c:type:: v4l2_frmsize_discrete -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: struct v4l2_frmsize_discrete :header-rows: 0 :stub-columns: 0 @@ -114,11 +102,8 @@ application should zero out all members except for the *IN* fields. - Height of the frame [pixel]. - .. c:type:: v4l2_frmsize_stepwise -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: struct v4l2_frmsize_stepwise :header-rows: 0 :stub-columns: 0 @@ -144,10 +129,9 @@ application should zero out all members except for the *IN* fields. - Frame height step size [pixel]. - .. c:type:: v4l2_frmsizeenum -.. tabularcolumns:: |p{1.4cm}|p{5.9cm}|p{2.3cm}|p{8.0cm}| +.. tabularcolumns:: |p{6.4cm}|p{2.8cm}|p{8.1cm}| .. flat-table:: struct v4l2_frmsizeenum :header-rows: 0 @@ -180,14 +164,12 @@ application should zero out all members except for the *IN* fields. applications. - Enums ===== - .. c:type:: v4l2_frmsizetypes -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. flat-table:: enum v4l2_frmsizetypes :header-rows: 0 @@ -204,7 +186,6 @@ Enums - 3 - Step-wise defined frame size. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst index ee3ba67601fa..e385929bed62 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUM_FREQ_BANDS: @@ -18,24 +12,22 @@ Name VIDIOC_ENUM_FREQ_BANDS - Enumerate supported frequency bands - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUM_FREQ_BANDS, struct v4l2_frequency_band *argp ) - :name: VIDIOC_ENUM_FREQ_BANDS +.. c:macro:: VIDIOC_ENUM_FREQ_BANDS +``int ioctl(int fd, VIDIOC_ENUM_FREQ_BANDS, struct v4l2_frequency_band *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_frequency_band`. - Description =========== @@ -48,8 +40,7 @@ fields, and zero out the ``reserved`` array of a struct This ioctl is supported if the ``V4L2_TUNER_CAP_FREQ_BANDS`` capability of the corresponding tuner/modulator is set. - -.. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{3.0cm}| +.. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{2.4cm}| .. c:type:: v4l2_frequency_band @@ -117,8 +108,7 @@ of the corresponding tuner/modulator is set. Applications and drivers must set the array to zero. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _band-modulation: @@ -137,7 +127,6 @@ of the corresponding tuner/modulator is set. - 0x08 - Amplitude Modulation, commonly used for analog radio. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enumaudio.rst b/Documentation/userspace-api/media/v4l/vidioc-enumaudio.rst index afe4821e5863..7873e5434d3e 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enumaudio.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enumaudio.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUMAUDIO: @@ -18,24 +12,22 @@ Name VIDIOC_ENUMAUDIO - Enumerate audio inputs - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUMAUDIO, struct v4l2_audio *argp ) - :name: VIDIOC_ENUMAUDIO +.. c:macro:: VIDIOC_ENUMAUDIO +``int ioctl(int fd, VIDIOC_ENUMAUDIO, struct v4l2_audio *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_audio`. - Description =========== @@ -50,7 +42,6 @@ zero, incrementing by one until the driver returns ``EINVAL``. See :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` for a description of struct :c:type:`v4l2_audio`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enumaudioout.rst b/Documentation/userspace-api/media/v4l/vidioc-enumaudioout.rst index 31c2ae460e2d..d4c3ba320834 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enumaudioout.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enumaudioout.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUMAUDOUT: @@ -18,24 +12,22 @@ Name VIDIOC_ENUMAUDOUT - Enumerate audio outputs - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUMAUDOUT, struct v4l2_audioout *argp ) - :name: VIDIOC_ENUMAUDOUT +.. c:macro:: VIDIOC_ENUMAUDOUT +``int ioctl(int fd, VIDIOC_ENUMAUDOUT, struct v4l2_audioout *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_audioout`. - Description =========== @@ -55,7 +47,6 @@ zero, incrementing by one until the driver returns ``EINVAL``. See :ref:`VIDIOC_G_AUDIOout <VIDIOC_G_AUDOUT>` for a description of struct :c:type:`v4l2_audioout`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst b/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst index 510670bff3de..d5f0535bd866 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUMINPUT: @@ -18,24 +12,22 @@ Name VIDIOC_ENUMINPUT - Enumerate video inputs - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUMINPUT, struct v4l2_input *argp ) - :name: VIDIOC_ENUMINPUT +.. c:macro:: VIDIOC_ENUMINPUT +``int ioctl(int fd, VIDIOC_ENUMINPUT, struct v4l2_input *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_input`. - Description =========== @@ -46,8 +38,7 @@ fill the rest of the structure or return an ``EINVAL`` error code when the index is out of bounds. To enumerate all inputs applications shall begin at index zero, incrementing by one until the driver returns ``EINVAL``. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{3.0cm}|p{3.5cm}|p{10.8cm}| .. c:type:: v4l2_input @@ -110,8 +101,7 @@ at index zero, incrementing by one until the driver returns ``EINVAL``. zero. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{1.0cm}|p{9.7cm}| .. _input-type: @@ -133,8 +123,7 @@ at index zero, incrementing by one until the driver returns ``EINVAL``. - This input is a touch device for capturing raw touch data. - -.. tabularcolumns:: |p{4.8cm}|p{2.6cm}|p{10.1cm}| +.. tabularcolumns:: |p{5.6cm}|p{2.6cm}|p{9.1cm}| .. _input-status: @@ -205,8 +194,7 @@ at index zero, incrementing by one until the driver returns ``EINVAL``. - VTR time constant. [?] - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.4cm}|p{8.3cm}| .. _input-capabilities: @@ -229,7 +217,6 @@ at index zero, incrementing by one until the driver returns ``EINVAL``. ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see :ref:`v4l2-selections-common`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst b/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst index 591a99cf8000..06ee8386ae86 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUMOUTPUT: @@ -18,24 +12,22 @@ Name VIDIOC_ENUMOUTPUT - Enumerate video outputs - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUMOUTPUT, struct v4l2_output *argp ) - :name: VIDIOC_ENUMOUTPUT +.. c:macro:: VIDIOC_ENUMOUTPUT +``int ioctl(int fd, VIDIOC_ENUMOUTPUT, struct v4l2_output *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_output`. - Description =========== @@ -47,8 +39,7 @@ when the index is out of bounds. To enumerate all outputs applications shall begin at index zero, incrementing by one until the driver returns ``EINVAL``. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_output @@ -105,8 +96,7 @@ shall begin at index zero, incrementing by one until the driver returns zero. - -.. tabularcolumns:: |p{7.0cm}|p{1.8cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.5cm}|p{0.6cm}|p{9.2cm}| .. _output-type: @@ -128,8 +118,7 @@ shall begin at index zero, incrementing by one until the driver returns - The video output will be copied to a :ref:`video overlay <overlay>`. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.4cm}|p{2.4cm}|p{8.5cm}| .. _output-capabilities: @@ -152,7 +141,6 @@ shall begin at index zero, incrementing by one until the driver returns ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see :ref:`v4l2-selections-common`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst b/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst index 8a0508536c13..6af71b74d42e 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_ENUMSTD: @@ -18,27 +12,26 @@ Name VIDIOC_ENUMSTD - VIDIOC_SUBDEV_ENUMSTD - Enumerate supported video standards - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_ENUMSTD, struct v4l2_standard *argp ) - :name: VIDIOC_ENUMSTD +.. c:macro:: VIDIOC_ENUMSTD + +``int ioctl(int fd, VIDIOC_ENUMSTD, struct v4l2_standard *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUMSTD, struct v4l2_standard *argp ) - :name: VIDIOC_SUBDEV_ENUMSTD +.. c:macro:: VIDIOC_SUBDEV_ENUMSTD +``int ioctl(int fd, VIDIOC_SUBDEV_ENUMSTD, struct v4l2_standard *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_standard`. - Description =========== @@ -52,10 +45,9 @@ zero, incrementing by one until the driver returns ``EINVAL``. Drivers may enumerate a different set of standards after switching the video input or output. [#f1]_ - .. c:type:: v4l2_standard -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_standard :header-rows: 0 @@ -92,10 +84,9 @@ or output. [#f1]_ zero. - .. c:type:: v4l2_fract -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_fract :header-rows: 0 @@ -109,8 +100,7 @@ or output. [#f1]_ - ``denominator`` - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. _v4l2-std-id: @@ -127,7 +117,6 @@ or output. [#f1]_ standards. - .. code-block:: c #define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001) @@ -149,7 +138,6 @@ rate, and PAL color modulation with a 4.43 MHz color subcarrier. Some PAL video recorders can play back NTSC tapes in this mode for display on a 50/60 Hz agnostic PAL TV. - .. code-block:: c #define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000) @@ -159,7 +147,6 @@ a 50/60 Hz agnostic PAL TV. ``V4L2_STD_NTSC_443`` is a hybrid standard with 525 lines, 60 Hz refresh rate, and NTSC color modulation with a 4.43 MHz color subcarrier. - .. code-block:: c #define V4L2_STD_NTSC_M_KR ((v4l2_std_id)0x00008000) @@ -182,7 +169,6 @@ terrestrial digital TV standards. Presently the V4L2 API does not support digital TV. See also the Linux DVB API at `https://linuxtv.org <https://linuxtv.org>`__. - .. code-block:: c #define V4L2_STD_PAL_BG (V4L2_STD_PAL_B | @@ -235,7 +221,6 @@ support digital TV. See also the Linux DVB API at #define V4L2_STD_ALL (V4L2_STD_525_60 | V4L2_STD_625_50) - .. raw:: latex \begingroup @@ -310,7 +295,6 @@ support digital TV. See also the Linux DVB API at \endgroup - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst index 384a9be9eba0..982e8bcd9c47 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_EXPBUF: @@ -18,24 +12,22 @@ Name VIDIOC_EXPBUF - Export a buffer as a DMABUF file descriptor. - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_EXPBUF, struct v4l2_exportbuffer *argp ) - :name: VIDIOC_EXPBUF +.. c:macro:: VIDIOC_EXPBUF +``int ioctl(int fd, VIDIOC_EXPBUF, struct v4l2_exportbuffer *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_exportbuffer`. - Description =========== @@ -70,11 +62,9 @@ for details about importing DMABUF files into V4L2 nodes. It is recommended to close a DMABUF file when it is no longer used to allow the associated memory to be reclaimed. - Examples ======== - .. code-block:: c int buffer_export(int v4lfd, enum v4l2_buf_type bt, int index, int *dmafd) @@ -94,7 +84,6 @@ Examples return 0; } - .. code-block:: c int buffer_export_mp(int v4lfd, enum v4l2_buf_type bt, int index, @@ -121,10 +110,9 @@ Examples return 0; } - .. c:type:: v4l2_exportbuffer -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_exportbuffer :header-rows: 0 @@ -162,7 +150,6 @@ Examples - Reserved field for future use. Drivers and applications must set the array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst b/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst index 68531bcb62ab..bf61db04d12e 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_AUDIO: @@ -18,27 +12,26 @@ Name VIDIOC_G_AUDIO - VIDIOC_S_AUDIO - Query or select the current audio input and its attributes - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_AUDIO, struct v4l2_audio *argp ) - :name: VIDIOC_G_AUDIO +.. c:macro:: VIDIOC_G_AUDIO + +``int ioctl(int fd, VIDIOC_G_AUDIO, struct v4l2_audio *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_AUDIO, const struct v4l2_audio *argp ) - :name: VIDIOC_S_AUDIO +.. c:macro:: VIDIOC_S_AUDIO +``int ioctl(int fd, VIDIOC_S_AUDIO, const struct v4l2_audio *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_audio`. - Description =========== @@ -56,8 +49,7 @@ ioctl. Drivers may switch to a different audio mode if the request cannot be satisfied. However, this is a write-only ioctl, it does not return the actual new audio mode. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_audio @@ -87,8 +79,7 @@ return the actual new audio mode. the array to zero. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _audio-capability: @@ -108,8 +99,7 @@ return the actual new audio mode. - Automatic Volume Level mode is supported. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _audio-mode: @@ -122,7 +112,6 @@ return the actual new audio mode. - 0x00001 - AVL mode is on. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst b/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst index e13b74bf5ce3..9ab15add2911 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_AUDOUT: @@ -18,27 +12,26 @@ Name VIDIOC_G_AUDOUT - VIDIOC_S_AUDOUT - Query or select the current audio output - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_AUDOUT, struct v4l2_audioout *argp ) - :name: VIDIOC_G_AUDOUT +.. c:macro:: VIDIOC_G_AUDOUT + +``int ioctl(int fd, VIDIOC_G_AUDOUT, struct v4l2_audioout *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_AUDOUT, const struct v4l2_audioout *argp ) - :name: VIDIOC_S_AUDOUT +.. c:macro:: VIDIOC_S_AUDOUT +``int ioctl(int fd, VIDIOC_S_AUDOUT, const struct v4l2_audioout *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_audioout`. - Description =========== @@ -63,10 +56,9 @@ as ``VIDIOC_G_AUDOUT`` does. Connectors on a TV card to loop back the received audio signal to a sound card are not audio outputs in this sense. - .. c:type:: v4l2_audioout -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_audioout :header-rows: 0 @@ -94,7 +86,6 @@ as ``VIDIOC_G_AUDOUT`` does. - Reserved for future extensions. Drivers and applications must set the array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst b/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst index 10e086be55d5..570d98308dc4 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_CROP: @@ -18,27 +12,26 @@ Name VIDIOC_G_CROP - VIDIOC_S_CROP - Get or set the current cropping rectangle - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_CROP, struct v4l2_crop *argp ) - :name: VIDIOC_G_CROP +.. c:macro:: VIDIOC_G_CROP + +``int ioctl(int fd, VIDIOC_G_CROP, struct v4l2_crop *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_CROP, const struct v4l2_crop *argp ) - :name: VIDIOC_S_CROP +.. c:macro:: VIDIOC_S_CROP +``int ioctl(int fd, VIDIOC_S_CROP, const struct v4l2_crop *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_crop`. - Description =========== @@ -76,10 +69,9 @@ been negotiated. When cropping is not supported then no parameters are changed and :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` returns the ``EINVAL`` error code. - .. c:type:: v4l2_crop -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_crop :header-rows: 0 @@ -107,7 +99,6 @@ When cropping is not supported then no parameters are changed and Starting with kernel 4.13 both variations are allowed. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst index 9831b7514028..fd09677f64f8 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_CTRL: @@ -18,27 +12,26 @@ Name VIDIOC_G_CTRL - VIDIOC_S_CTRL - Get or set the value of a control - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_CTRL, struct v4l2_control *argp ) - :name: VIDIOC_G_CTRL +.. c:macro:: VIDIOC_G_CTRL + +``int ioctl(int fd, VIDIOC_G_CTRL, struct v4l2_control *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_CTRL, struct v4l2_control *argp ) - :name: VIDIOC_S_CTRL +.. c:macro:: VIDIOC_S_CTRL +``int ioctl(int fd, VIDIOC_S_CTRL, struct v4l2_control *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_control`. - Description =========== @@ -62,10 +55,9 @@ These ioctls work only with user controls. For other control classes the :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` or :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` must be used. - .. c:type:: v4l2_control -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_control :header-rows: 0 @@ -79,7 +71,6 @@ These ioctls work only with user controls. For other control classes the - ``value`` - New value or current value. - Return Value ============ @@ -104,3 +95,6 @@ EBUSY EACCES Attempt to set a read-only control or to get a write-only control. + + Or if there is an attempt to set an inactive control and the driver is + not capable of caching the new value until the control is active again. diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst b/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst index 9a035a4ea0f0..6518d857c131 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_DV_TIMINGS: @@ -18,33 +12,34 @@ Name VIDIOC_G_DV_TIMINGS - VIDIOC_S_DV_TIMINGS - VIDIOC_SUBDEV_G_DV_TIMINGS - VIDIOC_SUBDEV_S_DV_TIMINGS - Get or set DV timings for input or output - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_DV_TIMINGS, struct v4l2_dv_timings *argp ) - :name: VIDIOC_G_DV_TIMINGS +.. c:macro:: VIDIOC_G_DV_TIMINGS + +``int ioctl(int fd, VIDIOC_G_DV_TIMINGS, struct v4l2_dv_timings *argp)`` + +.. c:macro:: VIDIOC_S_DV_TIMINGS -.. c:function:: int ioctl( int fd, VIDIOC_S_DV_TIMINGS, struct v4l2_dv_timings *argp ) - :name: VIDIOC_S_DV_TIMINGS +``int ioctl(int fd, VIDIOC_S_DV_TIMINGS, struct v4l2_dv_timings *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_DV_TIMINGS, struct v4l2_dv_timings *argp ) - :name: VIDIOC_SUBDEV_G_DV_TIMINGS +.. c:macro:: VIDIOC_SUBDEV_G_DV_TIMINGS -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_DV_TIMINGS, struct v4l2_dv_timings *argp ) - :name: VIDIOC_SUBDEV_S_DV_TIMINGS +``int ioctl(int fd, VIDIOC_SUBDEV_G_DV_TIMINGS, struct v4l2_dv_timings *argp)`` +.. c:macro:: VIDIOC_SUBDEV_S_DV_TIMINGS + +``int ioctl(int fd, VIDIOC_SUBDEV_S_DV_TIMINGS, struct v4l2_dv_timings *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_dv_timings`. - Description =========== @@ -67,7 +62,6 @@ the current input or output does not support DV timings (e.g. if :ref:`VIDIOC_ENUMINPUT` does not set the ``V4L2_IN_CAP_DV_TIMINGS`` flag), then ``ENODATA`` error code is returned. - Return Value ============ @@ -88,10 +82,12 @@ EBUSY EPERM ``VIDIOC_SUBDEV_S_DV_TIMINGS`` has been called on a read-only subdevice. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. c:type:: v4l2_bt_timings +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| + +.. cssclass:: longtable + .. flat-table:: struct v4l2_bt_timings :header-rows: 0 :stub-columns: 0 @@ -177,8 +173,7 @@ EPERM - Reserved for future extensions. Drivers and applications must set the array to zero. - -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{7.0cm}|p{3.5cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{7.0cm}|p{3.1cm}| .. c:type:: v4l2_dv_timings @@ -201,7 +196,7 @@ EPERM * - } - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. _dv-timing-types: @@ -220,7 +215,9 @@ EPERM - 0 - BT.656/1120 timings -.. tabularcolumns:: |p{4.5cm}|p{12.8cm}| +.. tabularcolumns:: |p{6.5cm}|p{11.0cm}| + +.. cssclass:: longtable .. _dv-bt-standards: @@ -243,7 +240,9 @@ EPERM There are no horizontal syncs/porches at all in this format. Total blanking timings must be set in hsync or vsync fields only. -.. tabularcolumns:: |p{7.0cm}|p{10.5cm}| +.. tabularcolumns:: |p{7.7cm}|p{9.8cm}| + +.. cssclass:: longtable .. _dv-bt-flags: diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst b/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst index 0620f4cbbcbd..fc5535c50d61 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_EDID: @@ -18,34 +12,34 @@ Name VIDIOC_G_EDID - VIDIOC_S_EDID - VIDIOC_SUBDEV_G_EDID - VIDIOC_SUBDEV_S_EDID - Get or set the EDID of a video receiver/transmitter - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_EDID, struct v4l2_edid *argp ) - :name: VIDIOC_G_EDID +.. c:macro:: VIDIOC_G_EDID + +``int ioctl(int fd, VIDIOC_G_EDID, struct v4l2_edid *argp)`` + +.. c:macro:: VIDIOC_S_EDID -.. c:function:: int ioctl( int fd, VIDIOC_S_EDID, struct v4l2_edid *argp ) - :name: VIDIOC_S_EDID +``int ioctl(int fd, VIDIOC_S_EDID, struct v4l2_edid *argp)`` +.. c:macro:: VIDIOC_SUBDEV_G_EDID -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_EDID, struct v4l2_edid *argp ) - :name: VIDIOC_SUBDEV_G_EDID +``int ioctl(int fd, VIDIOC_SUBDEV_G_EDID, struct v4l2_edid *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_EDID, struct v4l2_edid *argp ) - :name: VIDIOC_SUBDEV_S_EDID +.. c:macro:: VIDIOC_SUBDEV_S_EDID +``int ioctl(int fd, VIDIOC_SUBDEV_S_EDID, struct v4l2_edid *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_edid`. - Description =========== @@ -104,10 +98,9 @@ this will drive the hotplug pin low and/or block the source from reading the EDID data in some way. In any case, the end result is the same: the EDID is no longer available. - .. c:type:: v4l2_edid -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_edid :header-rows: 0 @@ -139,7 +132,6 @@ EDID is no longer available. - Pointer to memory that contains the EDID. The minimum size is ``blocks`` * 128. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst b/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst index 8aad30a7c6c3..c6792bbe3d04 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_ENC_INDEX: @@ -18,24 +12,22 @@ Name VIDIOC_G_ENC_INDEX - Get meta data about a compressed video stream - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_ENC_INDEX, struct v4l2_enc_idx *argp ) - :name: VIDIOC_G_ENC_INDEX +.. c:macro:: VIDIOC_G_ENC_INDEX +``int ioctl(int fd, VIDIOC_G_ENC_INDEX, struct v4l2_enc_idx *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_enc_idx`. - Description =========== @@ -62,8 +54,7 @@ will be zero. Currently this ioctl is only defined for MPEG-2 program streams and video elementary streams. - -.. tabularcolumns:: |p{3.8cm}|p{5.6cm}|p{8.1cm}| +.. tabularcolumns:: |p{4.2cm}|p{6.2cm}|p{6.9cm}| .. c:type:: v4l2_enc_idx @@ -90,8 +81,7 @@ video elementary streams. their ``offset``. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_enc_idx_entry @@ -123,8 +113,7 @@ video elementary streams. - Reserved for future extensions. Drivers must set the array to zero. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _enc-idx-flags: @@ -147,7 +136,6 @@ video elementary streams. - *AND* the flags field with this mask to obtain the picture coding type. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst index add17c9204cb..b8698b85bd80 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_EXT_CTRLS: @@ -18,32 +12,30 @@ Name VIDIOC_G_EXT_CTRLS - VIDIOC_S_EXT_CTRLS - VIDIOC_TRY_EXT_CTRLS - Get or set the value of several controls, try control values - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_EXT_CTRLS, struct v4l2_ext_controls *argp ) - :name: VIDIOC_G_EXT_CTRLS +.. c:macro:: VIDIOC_G_EXT_CTRLS +``int ioctl(int fd, VIDIOC_G_EXT_CTRLS, struct v4l2_ext_controls *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_EXT_CTRLS, struct v4l2_ext_controls *argp ) - :name: VIDIOC_S_EXT_CTRLS +.. c:macro:: VIDIOC_S_EXT_CTRLS +``int ioctl(int fd, VIDIOC_S_EXT_CTRLS, struct v4l2_ext_controls *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_TRY_EXT_CTRLS, struct v4l2_ext_controls *argp ) - :name: VIDIOC_TRY_EXT_CTRLS +.. c:macro:: VIDIOC_TRY_EXT_CTRLS +``int ioctl(int fd, VIDIOC_TRY_EXT_CTRLS, struct v4l2_ext_controls *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_ext_controls`. - Description =========== @@ -61,7 +53,7 @@ by the ``controls`` fields. To get the current value of a set of controls applications initialize the ``id``, ``size`` and ``reserved2`` fields of each struct :c:type:`v4l2_ext_control` and call the -:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. String controls controls must also set the +:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. String controls must also set the ``string`` field. Controls of compound types (``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set) must set the ``ptr`` field. @@ -126,12 +118,15 @@ correct. This prevents the situation where only some of the controls were set/get. Only low-level errors (e. g. a failed i2c command) can still cause this situation. - -.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{1.5cm}|p{11.8cm}| +.. tabularcolumns:: |p{6.8cm}|p{4.0cm}|p{6.5cm}| .. c:type:: v4l2_ext_control -.. cssclass: longtable +.. raw:: latex + + \footnotesize + +.. cssclass:: longtable .. flat-table:: struct v4l2_ext_control :header-rows: 0 @@ -143,11 +138,12 @@ still cause this situation. - Identifies the control, set by the application. * - __u32 - ``size`` - - The total size in bytes of the payload of this control. This is - normally 0, but for pointer controls this should be set to the - size of the memory containing the payload, or that will receive - the payload. If :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` finds that this value is - less than is required to store the payload result, then it is set + - The total size in bytes of the payload of this control. + * - :cspan:`2` The ``size`` field is normally 0, but for pointer + controls this should be set to the size of the memory that contains + the payload or that will receive the payload. + If :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` finds that this value + is less than is required to store the payload result, then it is set to a value large enough to store the payload result and ``ENOSPC`` is returned. @@ -189,10 +185,128 @@ still cause this situation. - ``p_u32`` - A pointer to a matrix control of unsigned 32-bit values. Valid if this control is of type ``V4L2_CTRL_TYPE_U32``. - * - :c:type:`v4l2_area` * + * - __s32 * + - ``p_s32`` + - A pointer to a matrix control of signed 32-bit values. Valid if + this control is of type ``V4L2_CTRL_TYPE_INTEGER`` and + ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set. + * - __s64 * + - ``p_s64`` + - A pointer to a matrix control of signed 64-bit values. Valid if + this control is of type ``V4L2_CTRL_TYPE_INTEGER64`` and + ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set. + * - struct :c:type:`v4l2_area` * - ``p_area`` - A pointer to a struct :c:type:`v4l2_area`. Valid if this control is of type ``V4L2_CTRL_TYPE_AREA``. + * - struct :c:type:`v4l2_rect` * + - ``p_rect`` + - A pointer to a struct :c:type:`v4l2_rect`. Valid if this control is + of type ``V4L2_CTRL_TYPE_RECT``. + * - struct :c:type:`v4l2_ctrl_h264_sps` * + - ``p_h264_sps`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_sps`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_SPS``. + * - struct :c:type:`v4l2_ctrl_h264_pps` * + - ``p_h264_pps`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_pps`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_PPS``. + * - struct :c:type:`v4l2_ctrl_h264_scaling_matrix` * + - ``p_h264_scaling_matrix`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_scaling_matrix`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_SCALING_MATRIX``. + * - struct :c:type:`v4l2_ctrl_h264_pred_weights` * + - ``p_h264_pred_weights`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_pred_weights`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_PRED_WEIGHTS``. + * - struct :c:type:`v4l2_ctrl_h264_slice_params` * + - ``p_h264_slice_params`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_slice_params`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_SLICE_PARAMS``. + * - struct :c:type:`v4l2_ctrl_h264_decode_params` * + - ``p_h264_decode_params`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_decode_params`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_DECODE_PARAMS``. + * - struct :c:type:`v4l2_ctrl_fwht_params` * + - ``p_fwht_params`` + - A pointer to a struct :c:type:`v4l2_ctrl_fwht_params`. Valid if this control is + of type ``V4L2_CTRL_TYPE_FWHT_PARAMS``. + * - struct :c:type:`v4l2_ctrl_vp8_frame` * + - ``p_vp8_frame`` + - A pointer to a struct :c:type:`v4l2_ctrl_vp8_frame`. Valid if this control is + of type ``V4L2_CTRL_TYPE_VP8_FRAME``. + * - struct :c:type:`v4l2_ctrl_mpeg2_sequence` * + - ``p_mpeg2_sequence`` + - A pointer to a struct :c:type:`v4l2_ctrl_mpeg2_sequence`. Valid if this control is + of type ``V4L2_CTRL_TYPE_MPEG2_SEQUENCE``. + * - struct :c:type:`v4l2_ctrl_mpeg2_picture` * + - ``p_mpeg2_picture`` + - A pointer to a struct :c:type:`v4l2_ctrl_mpeg2_picture`. Valid if this control is + of type ``V4L2_CTRL_TYPE_MPEG2_PICTURE``. + * - struct :c:type:`v4l2_ctrl_mpeg2_quantisation` * + - ``p_mpeg2_quantisation`` + - A pointer to a struct :c:type:`v4l2_ctrl_mpeg2_quantisation`. Valid if this control is + of type ``V4L2_CTRL_TYPE_MPEG2_QUANTISATION``. + * - struct :c:type:`v4l2_ctrl_vp9_compressed_hdr` * + - ``p_vp9_compressed_hdr_probs`` + - A pointer to a struct :c:type:`v4l2_ctrl_vp9_compressed_hdr`. Valid if this + control is of type ``V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR``. + * - struct :c:type:`v4l2_ctrl_vp9_frame` * + - ``p_vp9_frame`` + - A pointer to a struct :c:type:`v4l2_ctrl_vp9_frame`. Valid if this + control is of type ``V4L2_CTRL_TYPE_VP9_FRAME``. + * - struct :c:type:`v4l2_ctrl_hdr10_cll_info` * + - ``p_hdr10_cll`` + - A pointer to a struct :c:type:`v4l2_ctrl_hdr10_cll_info`. Valid if this control is + of type ``V4L2_CTRL_TYPE_HDR10_CLL_INFO``. + * - struct :c:type:`v4l2_ctrl_hdr10_mastering_display` * + - ``p_hdr10_mastering`` + - A pointer to a struct :c:type:`v4l2_ctrl_hdr10_mastering_display`. Valid if this control is + of type ``V4L2_CTRL_TYPE_HDR10_MASTERING_DISPLAY``. + * - struct :c:type:`v4l2_ctrl_hevc_sps` * + - ``p_hevc_sps`` + - A pointer to a struct :c:type:`v4l2_ctrl_hevc_sps`. Valid if this + control is of type ``V4L2_CTRL_TYPE_HEVC_SPS``. + * - struct :c:type:`v4l2_ctrl_hevc_pps` * + - ``p_hevc_pps`` + - A pointer to a struct :c:type:`v4l2_ctrl_hevc_pps`. Valid if this + control is of type ``V4L2_CTRL_TYPE_HEVC_PPS``. + * - struct :c:type:`v4l2_ctrl_hevc_slice_params` * + - ``p_hevc_slice_params`` + - A pointer to a struct :c:type:`v4l2_ctrl_hevc_slice_params`. Valid if this + control is of type ``V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS``. + * - struct :c:type:`v4l2_ctrl_hevc_scaling_matrix` * + - ``p_hevc_scaling_matrix`` + - A pointer to a struct :c:type:`v4l2_ctrl_hevc_scaling_matrix`. Valid if this + control is of type ``V4L2_CTRL_TYPE_HEVC_SCALING_MATRIX``. + * - struct :c:type:`v4l2_ctrl_hevc_decode_params` * + - ``p_hevc_decode_params`` + - A pointer to a struct :c:type:`v4l2_ctrl_hevc_decode_params`. Valid if this + control is of type ``V4L2_CTRL_TYPE_HEVC_DECODE_PARAMS``. + * - struct :c:type:`v4l2_ctrl_av1_sequence` * + - ``p_av1_sequence`` + - A pointer to a struct :c:type:`v4l2_ctrl_av1_sequence`. Valid if this control is + of type ``V4L2_CTRL_TYPE_AV1_SEQUENCE``. + * - struct :c:type:`v4l2_ctrl_av1_tile_group_entry` * + - ``p_av1_tile_group_entry`` + - A pointer to a struct :c:type:`v4l2_ctrl_av1_tile_group_entry`. Valid if this control is + of type ``V4L2_CTRL_TYPE_AV1_TILE_GROUP_ENTRY``. + * - struct :c:type:`v4l2_ctrl_av1_frame` * + - ``p_av1_frame`` + - A pointer to a struct :c:type:`v4l2_ctrl_av1_frame`. Valid if this control is + of type ``V4L2_CTRL_TYPE_AV1_FRAME``. + * - struct :c:type:`v4l2_ctrl_av1_film_grain` * + - ``p_av1_film_grain`` + - A pointer to a struct :c:type:`v4l2_ctrl_av1_film_grain`. Valid if this control is + of type ``V4L2_CTRL_TYPE_AV1_FILM_GRAIN``. + * - struct :c:type:`v4l2_ctrl_hdr10_cll_info` * + - ``p_hdr10_cll_info`` + - A pointer to a struct :c:type:`v4l2_ctrl_hdr10_cll_info`. Valid if this control is + of type ``V4L2_CTRL_TYPE_HDR10_CLL_INFO``. + * - struct :c:type:`v4l2_ctrl_hdr10_mastering_display` * + - ``p_hdr10_mastering_display`` + - A pointer to a struct :c:type:`v4l2_ctrl_hdr10_mastering_display`. Valid if this control is + of type ``V4L2_CTRL_TYPE_HDR10_MASTERING_DISPLAY``. * - void * - ``ptr`` - A pointer to a compound type which can be an N-dimensional array @@ -202,8 +316,11 @@ still cause this situation. * - } - +.. raw:: latex -.. tabularcolumns:: |p{4.0cm}|p{2.2cm}|p{2.1cm}|p{8.2cm}| + \normalsize + +.. tabularcolumns:: |p{4.0cm}|p{2.5cm}|p{10.8cm}| .. c:type:: v4l2_ext_controls @@ -217,29 +334,30 @@ still cause this situation. * - union { - (anonymous) * - __u32 - - ``ctrl_class`` - - The control class to which all controls belong, see - :ref:`ctrl-class`. Drivers that use a kernel framework for - handling controls will also accept a value of 0 here, meaning that - the controls can belong to any control class. Whether drivers - support this can be tested by setting ``ctrl_class`` to 0 and - calling :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` with a ``count`` of 0. If that - succeeds, then the driver supports this feature. - * - __u32 - ``which`` - Which value of the control to get/set/try. - ``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of the - control, ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default - value of the control and ``V4L2_CTRL_WHICH_REQUEST_VAL`` indicates that - these controls have to be retrieved from a request or tried/set for - a request. In the latter case the ``request_fd`` field contains the + * - :cspan:`2` ``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of + the control, ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default + value of the control, ``V4L2_CTRL_WHICH_MIN_VAL`` will return the minimum + value of the control, and ``V4L2_CTRL_WHICH_MAX_VAL`` will return the maximum + value of the control. ``V4L2_CTRL_WHICH_REQUEST_VAL`` indicates that + the control value has to be retrieved from a request or tried/set for + a request. In that case the ``request_fd`` field contains the file descriptor of the request that should be used. If the device does not support requests, then ``EACCES`` will be returned. - .. note:: + When using ``V4L2_CTRL_WHICH_DEF_VAL``, ``V4L2_CTRL_WHICH_MIN_VAL`` + or ``V4L2_CTRL_WHICH_MAX_VAL`` be aware that you can only get the + default/minimum/maximum value of the control, you cannot set or try it. - When using ``V4L2_CTRL_WHICH_DEF_VAL`` be aware that you can only - get the default value of the control, you cannot set or try it. + Whether a control supports querying the minimum and maximum values using + ``V4L2_CTRL_WHICH_MIN_VAL`` and ``V4L2_CTRL_WHICH_MAX_VAL`` is indicated + by the ``V4L2_CTRL_FLAG_HAS_WHICH_MIN_MAX`` flag. Most non-compound + control types support this. For controls with compound types, the + definition of minimum/maximum values are provided by + the control documentation. If a compound control does not document the + meaning of minimum/maximum value, then querying the minimum or maximum + value will result in the error code -EINVAL. For backwards compatibility you can also use a control class here (see :ref:`ctrl-class`). In that case all controls have to @@ -247,9 +365,12 @@ still cause this situation. just use ``V4L2_CTRL_WHICH_CUR_VAL``. There are some very old drivers that do not yet support ``V4L2_CTRL_WHICH_CUR_VAL`` and that require a control class here. You can test for such drivers - by setting ctrl_class to ``V4L2_CTRL_WHICH_CUR_VAL`` and calling - VIDIOC_TRY_EXT_CTRLS with a count of 0. If that fails, then the - driver does not support ``V4L2_CTRL_WHICH_CUR_VAL``. + by setting ``which`` to ``V4L2_CTRL_WHICH_CUR_VAL`` and calling + :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` with a count of 0. + If that fails, then the driver does not support ``V4L2_CTRL_WHICH_CUR_VAL``. + * - __u32 + - ``ctrl_class`` + - Deprecated name kept for backwards compatibility. Use ``which`` instead. * - } - * - __u32 @@ -257,7 +378,8 @@ still cause this situation. - The number of controls in the controls array. May also be zero. * - __u32 - ``error_idx`` - - Set by the driver in case of an error. If the error is associated + - Index of the failing control. Set by the driver in case of an error. + * - :cspan:`2` If the error is associated with a particular control, then ``error_idx`` is set to the index of that control. If the error is not related to a specific control, or the validation step failed (see below), then @@ -316,8 +438,9 @@ still cause this situation. Ignored if ``count`` equals zero. +.. tabularcolumns:: |p{7.3cm}|p{2.0cm}|p{8.0cm}| -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. cssclass:: longtable .. _ctrl-class: @@ -333,10 +456,10 @@ still cause this situation. :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` and :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl belong to this class. - * - ``V4L2_CTRL_CLASS_MPEG`` + * - ``V4L2_CTRL_CLASS_CODEC`` - 0x990000 - - The class containing MPEG compression controls. These controls are - described in :ref:`mpeg-controls`. + - The class containing stateful codec controls. These controls are + described in :ref:`codec-controls`. * - ``V4L2_CTRL_CLASS_CAMERA`` - 0x9a0000 - The class containing camera controls. These controls are described @@ -369,7 +492,18 @@ still cause this situation. - 0xa20000 - The class containing RF tuner controls. These controls are described in :ref:`rf-tuner-controls`. - + * - ``V4L2_CTRL_CLASS_DETECT`` + - 0xa30000 + - The class containing motion or object detection controls. These controls + are described in :ref:`detect-controls`. + * - ``V4L2_CTRL_CLASS_CODEC_STATELESS`` + - 0xa40000 + - The class containing stateless codec controls. These controls are + described in :ref:`codec-stateless-controls`. + * - ``V4L2_CTRL_CLASS_COLORIMETRY`` + - 0xa50000 + - The class containing colorimetry controls. These controls are + described in :ref:`colorimetry-controls`. Return Value ============ @@ -414,3 +548,6 @@ EACCES Or the ``which`` field was set to ``V4L2_CTRL_WHICH_REQUEST_VAL`` but the device does not support requests. + + Or if there is an attempt to set an inactive control and the driver is + not capable of caching the new value until the control is active again. diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst index 0124444419ae..b651e53643dd 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_FBUF: @@ -18,27 +12,26 @@ Name VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set frame buffer overlay parameters - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_FBUF, struct v4l2_framebuffer *argp ) - :name: VIDIOC_G_FBUF +.. c:macro:: VIDIOC_G_FBUF + +``int ioctl(int fd, VIDIOC_G_FBUF, struct v4l2_framebuffer *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_FBUF, const struct v4l2_framebuffer *argp ) - :name: VIDIOC_S_FBUF +.. c:macro:: VIDIOC_S_FBUF +``int ioctl(int fd, VIDIOC_S_FBUF, const struct v4l2_framebuffer *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_framebuffer`. - Description =========== @@ -56,6 +49,9 @@ of a graphics card. A non-destructive overlay blends video images into a VGA signal or graphics into a video signal. *Video Output Overlays* are always non-destructive. +Destructive overlay support has been removed: with modern GPUs and CPUs +this is no longer needed, and it was always a very dangerous feature. + To get the current parameters applications call the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` ioctl with a pointer to a struct :c:type:`v4l2_framebuffer` structure. The driver fills all fields of the structure or returns an @@ -70,20 +66,13 @@ this structure, the driver prepares for the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error code. -To set the parameters for a *non-destructive Video Overlay*, +To set the parameters for a *Video Capture Overlay* applications must initialize the ``flags`` field, the ``fmt`` substructure, and call :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. Again the driver prepares for the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error code. -For a *destructive Video Overlay* applications must additionally provide -a ``base`` address. Setting up a DMA to a random memory location can -jeopardize the system security, its stability or even damage the -hardware, therefore only the superuser can set the parameters for a -destructive video overlay. - - -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{6.6cm}| .. c:type:: v4l2_framebuffer @@ -108,17 +97,14 @@ destructive video overlay. - ``base`` - - Physical base address of the framebuffer, that is the address of - the pixel in the top left corner of the framebuffer. [#f1]_ - * - - - - - - - This field is irrelevant to *non-destructive Video Overlays*. For - *destructive Video Overlays* applications must provide a base - address. The driver may accept only base addresses which are a - multiple of two, four or eight bytes. For *Video Output Overlays* - the driver must return a valid base address, so applications can + the pixel in the top left corner of the framebuffer. + For :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` this field is no longer supported + and the kernel will always set this to NULL. + For *Video Output Overlays* + the driver will return a valid base address, so applications can find the corresponding Linux framebuffer device (see - :ref:`osd`). + :ref:`osd`). For *Video Capture Overlays* this field will always be + NULL. * - struct - ``fmt`` - @@ -144,8 +130,7 @@ destructive video overlay. * - - - - - For *destructive Video Overlays* applications must initialize this - field. For *Video Output Overlays* the driver must return a valid + - For *Video Output Overlays* the driver must return a valid format. * - - @@ -173,13 +158,6 @@ destructive video overlay. This field is irrelevant to *non-destructive Video Overlays*. - For *destructive Video Overlays* both applications and drivers can - set this field to request padding bytes at the end of each line. - Drivers however may ignore the requested value, returning - ``width`` times bytes-per-pixel or a larger value required by the - hardware. That implies applications can just set this field to - zero to get a reasonable default. - For *Video Output Overlays* the driver must return a valid value. Video hardware may access padding bytes, therefore they must @@ -198,9 +176,8 @@ destructive video overlay. * - - __u32 - ``sizeimage`` - - This field is irrelevant to *non-destructive Video Overlays*. For - *destructive Video Overlays* applications must initialize this - field. For *Video Output Overlays* the driver must return a valid + - This field is irrelevant to *non-destructive Video Overlays*. + For *Video Output Overlays* the driver must return a valid format. Together with ``base`` it defines the framebuffer memory @@ -215,8 +192,7 @@ destructive video overlay. - ``priv`` - Reserved. Drivers and applications must set this field to zero. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.4cm}|p{1.6cm}|p{8.3cm}| .. _framebuffer-cap: @@ -241,9 +217,11 @@ destructive video overlay. * - ``V4L2_FBUF_CAP_LIST_CLIPPING`` - 0x0004 - The device supports clipping using a list of clip rectangles. + Note that this is no longer supported. * - ``V4L2_FBUF_CAP_BITMAP_CLIPPING`` - 0x0008 - The device supports clipping using a bit mask. + Note that this is no longer supported. * - ``V4L2_FBUF_CAP_LOCAL_ALPHA`` - 0x0010 - The device supports clipping/blending using the alpha channel of @@ -264,8 +242,7 @@ destructive video overlay. chroma-key colors are replaced by framebuffer pixels, which is exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY`` - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.4cm}|p{1.6cm}|p{8.3cm}| .. _framebuffer-flags: @@ -339,7 +316,6 @@ destructive video overlay. other, so same ``chromakey`` field of struct :c:type:`v4l2_window` is being used. - Return Value ============ @@ -353,10 +329,3 @@ EPERM EINVAL The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` parameters are unsuitable. - -.. [#f1] - A physical base address may not suit all platforms. GK notes in - theory we should pass something like PCI device + memory region + - offset instead. If you encounter problems please discuss on the - linux-media mailing list: - `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst index 88bb69ec07e2..675c385e5aca 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_FMT: @@ -18,29 +12,30 @@ Name VIDIOC_G_FMT - VIDIOC_S_FMT - VIDIOC_TRY_FMT - Get or set the data format, try a format - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_FMT, struct v4l2_format *argp ) - :name: VIDIOC_G_FMT +.. c:macro:: VIDIOC_G_FMT + +``int ioctl(int fd, VIDIOC_G_FMT, struct v4l2_format *argp)`` + +.. c:macro:: VIDIOC_S_FMT + +``int ioctl(int fd, VIDIOC_S_FMT, struct v4l2_format *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_FMT, struct v4l2_format *argp ) - :name: VIDIOC_S_FMT +.. c:macro:: VIDIOC_TRY_FMT -.. c:function:: int ioctl( int fd, VIDIOC_TRY_FMT, struct v4l2_format *argp ) - :name: VIDIOC_TRY_FMT +``int ioctl(int fd, VIDIOC_TRY_FMT, struct v4l2_format *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_format`. - Description =========== @@ -92,10 +87,9 @@ recommended drivers are not required to implement this ioctl. The format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical to what :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` returns for the same input or output. - .. c:type:: v4l2_format -.. tabularcolumns:: |p{1.2cm}|p{4.6cm}|p{3.0cm}|p{8.6cm}| +.. tabularcolumns:: |p{7.4cm}|p{4.4cm}|p{5.5cm}| .. flat-table:: struct v4l2_format :header-rows: 0 @@ -142,7 +136,6 @@ The format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical * - } - - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst b/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst index 26300e0258a3..0d037665a89e 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_FREQUENCY: @@ -18,27 +12,26 @@ Name VIDIOC_G_FREQUENCY - VIDIOC_S_FREQUENCY - Get or set tuner or modulator radio frequency - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_FREQUENCY, struct v4l2_frequency *argp ) - :name: VIDIOC_G_FREQUENCY +.. c:macro:: VIDIOC_G_FREQUENCY + +``int ioctl(int fd, VIDIOC_G_FREQUENCY, struct v4l2_frequency *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_FREQUENCY, const struct v4l2_frequency *argp ) - :name: VIDIOC_S_FREQUENCY +.. c:macro:: VIDIOC_S_FREQUENCY +``int ioctl(int fd, VIDIOC_S_FREQUENCY, const struct v4l2_frequency *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_frequency`. - Description =========== @@ -58,8 +51,7 @@ structure. When the requested frequency is not possible the driver assumes the closest possible value. However :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` is a write-only ioctl, it does not return the actual new frequency. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_frequency @@ -96,7 +88,6 @@ write-only ioctl, it does not return the actual new frequency. - Reserved for future extensions. Drivers and applications must set the array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-input.rst b/Documentation/userspace-api/media/v4l/vidioc-g-input.rst index 294e346678c1..eee9ce51c797 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-input.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-input.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_INPUT: @@ -18,27 +12,26 @@ Name VIDIOC_G_INPUT - VIDIOC_S_INPUT - Query or select the current video input - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_INPUT, int *argp ) - :name: VIDIOC_G_INPUT +.. c:macro:: VIDIOC_G_INPUT + +``int ioctl(int fd, VIDIOC_G_INPUT, int *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_INPUT, int *argp ) - :name: VIDIOC_S_INPUT +.. c:macro:: VIDIOC_S_INPUT +``int ioctl(int fd, VIDIOC_S_INPUT, int *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer an integer with input index. - Description =========== @@ -59,7 +52,6 @@ other parameters. Information about video inputs is available using the :ref:`VIDIOC_ENUMINPUT` ioctl. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst b/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst index 3b9981dcb8e0..d4565d2cc1f5 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_JPEGCOMP: @@ -18,27 +12,26 @@ Name VIDIOC_G_JPEGCOMP - VIDIOC_S_JPEGCOMP - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_JPEGCOMP, v4l2_jpegcompression *argp ) - :name: VIDIOC_G_JPEGCOMP +.. c:macro:: VIDIOC_G_JPEGCOMP + +``int ioctl(int fd, VIDIOC_G_JPEGCOMP, v4l2_jpegcompression *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_JPEGCOMP, const v4l2_jpegcompression *argp ) - :name: VIDIOC_S_JPEGCOMP +.. c:macro:: VIDIOC_S_JPEGCOMP +``int ioctl(int fd, VIDIOC_S_JPEGCOMP, const v4l2_jpegcompression *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_jpegcompression`. - Description =========== @@ -61,8 +54,7 @@ stored in the JPEG-encoded fields. These define how the JPEG field is encoded. If you omit them, applications assume you've used standard encoding. You usually do want to add them. - -.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.3cm}| +.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.1cm}| .. c:type:: v4l2_jpegcompression @@ -99,8 +91,7 @@ encoding. You usually do want to add them. control is exposed by a driver applications should use it instead and ignore this field. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _jpeg-markers: @@ -125,7 +116,6 @@ encoding. You usually do want to add them. - (1<<7) - App segment, driver will always use APP0 - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst b/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst index c2072f6e8756..6bdf925f9a4a 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_MODULATOR: @@ -18,27 +12,26 @@ Name VIDIOC_G_MODULATOR - VIDIOC_S_MODULATOR - Get or set modulator attributes - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_MODULATOR, struct v4l2_modulator *argp ) - :name: VIDIOC_G_MODULATOR +.. c:macro:: VIDIOC_G_MODULATOR + +``int ioctl(int fd, VIDIOC_G_MODULATOR, struct v4l2_modulator *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_MODULATOR, const struct v4l2_modulator *argp ) - :name: VIDIOC_S_MODULATOR +.. c:macro:: VIDIOC_S_MODULATOR +``int ioctl(int fd, VIDIOC_S_MODULATOR, const struct v4l2_modulator *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_modulator`. - Description =========== @@ -67,8 +60,7 @@ context. To change the radio frequency the :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available. - -.. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{3.0cm}| +.. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{2.4cm}| .. c:type:: v4l2_modulator @@ -127,9 +119,9 @@ To change the radio frequency the Drivers and applications must set the array to zero. +.. tabularcolumns:: |p{6.0cm}|p{2.0cm}|p{9.3cm}| - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. cssclass:: longtable .. _modulator-txsubchans: @@ -189,7 +181,6 @@ To change the radio frequency the - 0x0010 - Enable the RDS encoder for a radio FM transmitter. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-output.rst b/Documentation/userspace-api/media/v4l/vidioc-g-output.rst index cad477420fd7..dbcdd51dd2a8 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-output.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-output.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_OUTPUT: @@ -18,27 +12,26 @@ Name VIDIOC_G_OUTPUT - VIDIOC_S_OUTPUT - Query or select the current video output - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_OUTPUT, int *argp ) - :name: VIDIOC_G_OUTPUT +.. c:macro:: VIDIOC_G_OUTPUT + +``int ioctl(int fd, VIDIOC_G_OUTPUT, int *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_OUTPUT, int *argp ) - :name: VIDIOC_S_OUTPUT +.. c:macro:: VIDIOC_S_OUTPUT +``int ioctl(int fd, VIDIOC_S_OUTPUT, int *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to an integer with output index. - Description =========== @@ -53,14 +46,13 @@ To select a video output applications store the number of the desired output in an integer and call the :ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` ioctl with a pointer to this integer. Side effects are possible. For example outputs may support different video standards, so the driver may implicitly -switch the current standard. standard. Because of these possible side +switch the current standard. Because of these possible side effects applications must select an output before querying or negotiating any other parameters. Information about video outputs is available using the :ref:`VIDIOC_ENUMOUTPUT` ioctl. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst b/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst index 42e9f6ee7a59..8b5600fbf013 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_PARM: @@ -18,51 +12,51 @@ Name VIDIOC_G_PARM - VIDIOC_S_PARM - Get or set streaming parameters - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_PARM, v4l2_streamparm *argp ) - :name: VIDIOC_G_PARM +.. c:macro:: VIDIOC_G_PARM + +``int ioctl(int fd, VIDIOC_G_PARM, v4l2_streamparm *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_PARM, v4l2_streamparm *argp ) - :name: VIDIOC_S_PARM +.. c:macro:: VIDIOC_S_PARM +``int ioctl(int fd, VIDIOC_S_PARM, v4l2_streamparm *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_streamparm`. - 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. Further these ioctls can be used to determine the number of buffers used internally by a driver in read/write mode. For implications see the -section discussing the :ref:`read() <func-read>` function. +section discussing the :c: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. - -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| +.. tabularcolumns:: |p{3.7cm}|p{3.5cm}|p{10.1cm}| .. c:type:: v4l2_streamparm @@ -91,11 +85,9 @@ union holding separate parameters for input and output devices. - ``raw_data``\ [200] - A place holder for future extensions. * - } - - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_captureparm @@ -113,14 +105,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. @@ -136,7 +135,7 @@ union holding separate parameters for input and output devices. * - __u32 - ``readbuffers`` - Applications set this field to the desired number of buffers used - internally by the driver in :ref:`read() <func-read>` mode. + internally by the driver in :c:func:`read()` mode. Drivers return the actual number of buffers. When an application requests zero buffers, drivers should just return the current setting rather than the minimum or an error code. For details see @@ -147,8 +146,7 @@ union holding separate parameters for input and output devices. the array to zero. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_outputparm @@ -170,14 +168,18 @@ union holding separate parameters for input and output devices. * - :cspan:`2` The field is intended to repeat frames on the driver side in - :ref:`write() <func-write>` mode (in streaming mode timestamps + :c: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. @@ -193,7 +195,7 @@ union holding separate parameters for input and output devices. * - __u32 - ``writebuffers`` - Applications set this field to the desired number of buffers used - internally by the driver in :ref:`write() <func-write>` mode. Drivers + internally by the driver in :c:func:`write()` mode. Drivers return the actual number of buffers. When an application requests zero buffers, drivers should just return the current setting rather than the minimum or an error code. For details see @@ -204,8 +206,7 @@ union holding separate parameters for input and output devices. the array to zero. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _parm-caps: @@ -216,12 +217,11 @@ 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. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _parm-flags: @@ -259,8 +259,7 @@ union holding separate parameters for input and output devices. - Moving objects in the image might have excessive motion blur. - - Capture might only work through the :ref:`read() <func-read>` call. - + - Capture might only work through the :c:func:`read()` call. Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst b/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst index c8add130c7a4..3031256159c3 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_PRIORITY: @@ -18,27 +12,26 @@ Name VIDIOC_G_PRIORITY - VIDIOC_S_PRIORITY - Query or request the access priority associated with a file descriptor - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_PRIORITY, enum v4l2_priority *argp ) - :name: VIDIOC_G_PRIORITY +.. c:macro:: VIDIOC_G_PRIORITY + +``int ioctl(int fd, VIDIOC_G_PRIORITY, enum v4l2_priority *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_PRIORITY, const enum v4l2_priority *argp ) - :name: VIDIOC_S_PRIORITY +.. c:macro:: VIDIOC_S_PRIORITY +``int ioctl(int fd, VIDIOC_S_PRIORITY, const enum v4l2_priority *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to an enum :c:type:`v4l2_priority` type. - Description =========== @@ -50,10 +43,9 @@ To request an access priority applications store the desired priority in an enum v4l2_priority variable and call :ref:`VIDIOC_S_PRIORITY <VIDIOC_G_PRIORITY>` ioctl with a pointer to this variable. - .. c:type:: v4l2_priority -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. flat-table:: enum v4l2_priority :header-rows: 0 @@ -85,7 +77,6 @@ with a pointer to this variable. it blocks any other fd from changing device properties. Usually applications which must not be interrupted, like video recording. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst b/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst index faab0454b1e4..2b5b27260741 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_SELECTION: @@ -18,23 +12,22 @@ Name VIDIOC_G_SELECTION - VIDIOC_S_SELECTION - Get or set one of the selection rectangles - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_SELECTION, struct v4l2_selection *argp ) - :name: VIDIOC_G_SELECTION +.. c:macro:: VIDIOC_G_SELECTION +``int ioctl(int fd, VIDIOC_G_SELECTION, struct v4l2_selection *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_SELECTION, struct v4l2_selection *argp ) - :name: VIDIOC_S_SELECTION +.. c:macro:: VIDIOC_S_SELECTION +``int ioctl(int fd, VIDIOC_S_SELECTION, struct v4l2_selection *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_selection`. @@ -122,7 +115,6 @@ constraints. Selection targets and flags are documented in :ref:`v4l2-selections-common`. - .. _sel-const-adjust: .. kernel-figure:: constraints.svg @@ -135,10 +127,9 @@ Selection targets and flags are documented in - .. c:type:: v4l2_selection -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_selection :header-rows: 0 @@ -175,7 +166,6 @@ Selection targets and flags are documented in Starting with kernel 4.13 both variations are allowed. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst b/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst index 7a62c4f4e37f..90d40f6af57b 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_SLICED_VBI_CAP: @@ -18,24 +12,22 @@ Name VIDIOC_G_SLICED_VBI_CAP - Query sliced VBI capabilities - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_SLICED_VBI_CAP, struct v4l2_sliced_vbi_cap *argp ) - :name: VIDIOC_G_SLICED_VBI_CAP +.. c:macro:: VIDIOC_G_SLICED_VBI_CAP +``int ioctl(int fd, VIDIOC_G_SLICED_VBI_CAP, struct v4l2_sliced_vbi_cap *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_sliced_vbi_cap`. - Description =========== @@ -51,10 +43,9 @@ the sliced VBI API is unsupported or ``type`` is invalid. The ``type`` field was added, and the ioctl changed from read-only to write-read, in Linux 2.6.19. - .. c:type:: v4l2_sliced_vbi_cap -.. tabularcolumns:: |p{1.2cm}|p{4.2cm}|p{4.1cm}|p{4.0cm}|p{4.0cm}| +.. tabularcolumns:: |p{1.4cm}|p{4.4cm}|p{4.5cm}|p{3.6cm}|p{3.6cm}| .. flat-table:: struct v4l2_sliced_vbi_cap :header-rows: 0 @@ -127,12 +118,11 @@ the sliced VBI API is unsupported or ``type`` is invalid. See also :ref:`vbi-525` and :ref:`vbi-625`. - .. raw:: latex \scriptsize -.. tabularcolumns:: |p{3.5cm}|p{1.0cm}|p{2.0cm}|p{2.0cm}|p{8.0cm}| +.. tabularcolumns:: |p{3.9cm}|p{1.0cm}|p{2.0cm}|p{3.0cm}|p{7.0cm}| .. _vbi-services: @@ -172,13 +162,7 @@ the sliced VBI API is unsupported or ``type`` is invalid. :ref:`itu1119` - PAL/SECAM line 23 - - - - :: - - Byte 0 1 - msb lsb msb lsb - Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9 + - See :ref:`v4l2-sliced-vbi-cap-wss-625-payload` below. * - ``V4L2_SLICED_VBI_525`` - 0x1000 - :cspan:`2` Set of services applicable to 525 line systems. @@ -186,10 +170,26 @@ the sliced VBI API is unsupported or ``type`` is invalid. - 0x4401 - :cspan:`2` Set of services applicable to 625 line systems. + .. raw:: latex \normalsize +.. _v4l2-sliced-vbi-cap-wss-625-payload: + +V4L2_SLICED_VBI_CAP WSS_625 payload +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The payload for ``V4L2_SLICED_WSS_625`` is: + + +-----+------------------+-----------------------+ + |Byte | 0 | 1 | + +-----+--------+---------+-----------+-----------+ + | | msb | lsb | msb | lsb | + | +-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+ + | Bit |7|6|5|4 | 3|2|1|0 | x|x|13|12 | 11|10|9|8 | + +-----+-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+ + Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-std.rst b/Documentation/userspace-api/media/v4l/vidioc-g-std.rst index 6d8cb7f29ac6..da91fe07d9e0 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-std.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-std.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_STD: @@ -18,33 +12,34 @@ Name VIDIOC_G_STD - VIDIOC_S_STD - VIDIOC_SUBDEV_G_STD - VIDIOC_SUBDEV_S_STD - Query or select the video standard of the current input - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_STD, v4l2_std_id *argp ) - :name: VIDIOC_G_STD +.. c:macro:: VIDIOC_G_STD + +``int ioctl(int fd, VIDIOC_G_STD, v4l2_std_id *argp)`` + +.. c:macro:: VIDIOC_S_STD -.. c:function:: int ioctl( int fd, VIDIOC_S_STD, const v4l2_std_id *argp ) - :name: VIDIOC_S_STD +``int ioctl(int fd, VIDIOC_S_STD, const v4l2_std_id *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_STD, v4l2_std_id *argp ) - :name: VIDIOC_SUBDEV_G_STD +.. c:macro:: VIDIOC_SUBDEV_G_STD -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_STD, const v4l2_std_id *argp ) - :name: VIDIOC_SUBDEV_S_STD +``int ioctl(int fd, VIDIOC_SUBDEV_G_STD, v4l2_std_id *argp)`` +.. c:macro:: VIDIOC_SUBDEV_S_STD + +``int ioctl(int fd, VIDIOC_SUBDEV_S_STD, const v4l2_std_id *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to :c:type:`v4l2_std_id`. - Description =========== diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst b/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst index 40bff6f0a88d..b0522f1ff7a4 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_G_TUNER: @@ -18,27 +12,26 @@ Name VIDIOC_G_TUNER - VIDIOC_S_TUNER - Get or set tuner attributes - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_G_TUNER, struct v4l2_tuner *argp ) - :name: VIDIOC_G_TUNER +.. c:macro:: VIDIOC_G_TUNER + +``int ioctl(int fd, VIDIOC_G_TUNER, struct v4l2_tuner *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_S_TUNER, const struct v4l2_tuner *argp ) - :name: VIDIOC_S_TUNER +.. c:macro:: VIDIOC_S_TUNER +``int ioctl(int fd, VIDIOC_S_TUNER, const struct v4l2_tuner *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_tuner`. - Description =========== @@ -66,8 +59,7 @@ to zero. The term 'tuner' means SDR receiver in this context. To change the radio frequency the :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available. - - .. tabularcolumns:: |p{1.3cm}|p{3.0cm}|p{6.6cm}|p{6.6cm}| + .. tabularcolumns:: |p{1.3cm}|p{3.0cm}|p{7.0cm}|p{5.8cm}| .. c:type:: v4l2_tuner @@ -190,8 +182,7 @@ To change the radio frequency the Drivers and applications must set the array to zero. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. c:type:: v4l2_tuner_type @@ -214,8 +205,7 @@ To change the radio frequency the - 5 - Tuner controls the RF part of a Software Digital Radio (SDR) - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.0cm}|p{2.2cm}|p{8.1cm}| .. _tuner-capability: @@ -306,8 +296,7 @@ To change the radio frequency the instead of 62.5 kHz. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _tuner-rxsubchans: @@ -345,8 +334,7 @@ To change the radio frequency the - The tuner receives an RDS channel. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _tuner-audmode: diff --git a/Documentation/userspace-api/media/v4l/vidioc-log-status.rst b/Documentation/userspace-api/media/v4l/vidioc-log-status.rst index 64c06fa72b9c..c218747be762 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-log-status.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-log-status.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_LOG_STATUS: @@ -18,20 +12,18 @@ Name VIDIOC_LOG_STATUS - Log driver status information - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_LOG_STATUS) - :name: VIDIOC_LOG_STATUS +.. c:macro:: VIDIOC_LOG_STATUS +``int ioctl(int fd, VIDIOC_LOG_STATUS)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. - + File descriptor returned by :c:func:`open()`. Description =========== @@ -47,7 +39,6 @@ Mismatches may give an indication where the problem is. This ioctl is optional and not all drivers support it. It was introduced in Linux 2.6.15. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-overlay.rst b/Documentation/userspace-api/media/v4l/vidioc-overlay.rst index 74310ff486ba..f2efaaba24c0 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-overlay.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-overlay.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_OVERLAY: @@ -18,24 +12,22 @@ Name VIDIOC_OVERLAY - Start or stop video overlay - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_OVERLAY, const int *argp ) - :name: VIDIOC_OVERLAY +.. c:macro:: VIDIOC_OVERLAY +``int ioctl(int fd, VIDIOC_OVERLAY, const int *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to an integer. - Description =========== @@ -48,7 +40,6 @@ Drivers do not support :ref:`VIDIOC_STREAMON` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` with ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-prepare-buf.rst b/Documentation/userspace-api/media/v4l/vidioc-prepare-buf.rst index b6c09d5b128f..45bb1eab2c2d 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-prepare-buf.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-prepare-buf.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_PREPARE_BUF: @@ -18,24 +12,22 @@ Name VIDIOC_PREPARE_BUF - Prepare a buffer for I/O - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_PREPARE_BUF, struct v4l2_buffer *argp ) - :name: VIDIOC_PREPARE_BUF +.. c:macro:: VIDIOC_PREPARE_BUF +``int ioctl(int fd, VIDIOC_PREPARE_BUF, struct v4l2_buffer *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_buffer`. - Description =========== @@ -48,7 +40,6 @@ in advance saves time during the actual I/O. The struct :c:type:`v4l2_buffer` structure is specified in :ref:`buffer`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst index ec0a54fbeb43..e4b3d9beb9ab 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_QBUF: @@ -18,27 +12,26 @@ Name VIDIOC_QBUF - VIDIOC_DQBUF - Exchange a buffer with the driver - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_QBUF, struct v4l2_buffer *argp ) - :name: VIDIOC_QBUF +.. c:macro:: VIDIOC_QBUF + +``int ioctl(int fd, VIDIOC_QBUF, struct v4l2_buffer *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_DQBUF, struct v4l2_buffer *argp ) - :name: VIDIOC_DQBUF +.. c:macro:: VIDIOC_DQBUF +``int ioctl(int fd, VIDIOC_DQBUF, struct v4l2_buffer *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_buffer`. - Description =========== @@ -132,7 +125,7 @@ Applications call the ``VIDIOC_DQBUF`` ioctl to dequeue a filled queue. They just set the ``type``, ``memory`` and ``reserved`` fields of a struct :c:type:`v4l2_buffer` as above, when ``VIDIOC_DQBUF`` is called with a pointer to this structure the driver -fills the remaining fields or returns an error code. The driver may also +fills all remaining fields or returns an error code. The driver may also set ``V4L2_BUF_FLAG_ERROR`` in the ``flags`` field. It indicates a non-critical (recoverable) streaming error. In such case the application may continue as normal, but should be aware that data in the dequeued @@ -149,13 +142,12 @@ API is used the ``m.fd`` fields of the passed array of struct By default ``VIDIOC_DQBUF`` blocks when no buffer is in the outgoing queue. When the ``O_NONBLOCK`` flag was given to the -:ref:`open() <func-open>` function, ``VIDIOC_DQBUF`` returns +:c:func:`open()` function, ``VIDIOC_DQBUF`` returns immediately with an ``EAGAIN`` error code when no buffer is available. The struct :c:type:`v4l2_buffer` structure is specified in :ref:`buffer`. - Return Value ============ @@ -171,7 +163,7 @@ EINVAL The buffer ``type`` is not supported, or the ``index`` is out of bounds, or no buffers have been allocated yet, or the ``userptr`` or ``length`` are invalid, or the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was - set but the the given ``request_fd`` was invalid, or ``m.fd`` was + set but the given ``request_fd`` was invalid, or ``m.fd`` was an invalid DMABUF file descriptor. EIO diff --git a/Documentation/userspace-api/media/v4l/vidioc-query-dv-timings.rst b/Documentation/userspace-api/media/v4l/vidioc-query-dv-timings.rst index ab86408446f3..5afdc4b4dc2d 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-query-dv-timings.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-query-dv-timings.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_QUERY_DV_TIMINGS: @@ -18,27 +12,26 @@ Name VIDIOC_QUERY_DV_TIMINGS - VIDIOC_SUBDEV_QUERY_DV_TIMINGS - Sense the DV preset received by the current input - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp ) - :name: VIDIOC_QUERY_DV_TIMINGS +.. c:macro:: VIDIOC_QUERY_DV_TIMINGS + +``int ioctl(int fd, VIDIOC_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp ) - :name: VIDIOC_SUBDEV_QUERY_DV_TIMINGS +.. c:macro:: VIDIOC_SUBDEV_QUERY_DV_TIMINGS +``int ioctl(int fd, VIDIOC_SUBDEV_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_dv_timings`. - Description =========== @@ -72,7 +65,6 @@ and returns ``ERANGE``. In that case the application can call found timings with the hardware's capabilities in order to give more precise feedback to the user. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-querybuf.rst b/Documentation/userspace-api/media/v4l/vidioc-querybuf.rst index 646f91140ccf..6c615e893866 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-querybuf.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-querybuf.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_QUERYBUF: @@ -18,24 +12,22 @@ Name VIDIOC_QUERYBUF - Query the status of a buffer - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_QUERYBUF, struct v4l2_buffer *argp ) - :name: VIDIOC_QUERYBUF +.. c:macro:: VIDIOC_QUERYBUF +``int ioctl(int fd, VIDIOC_QUERYBUF, struct v4l2_buffer *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_buffer`. - Description =========== @@ -74,7 +66,6 @@ flags, they are meaningless in this context. The struct :c:type:`v4l2_buffer` structure is specified in :ref:`buffer`. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-querycap.rst b/Documentation/userspace-api/media/v4l/vidioc-querycap.rst index 666ac4d42051..3d11d86d9cbf 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-querycap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-querycap.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_QUERYCAP: @@ -18,24 +12,22 @@ Name VIDIOC_QUERYCAP - Query device capabilities - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_QUERYCAP, struct v4l2_capability *argp ) - :name: VIDIOC_QUERYCAP +.. c:macro:: VIDIOC_QUERYCAP +``int ioctl(int fd, VIDIOC_QUERYCAP, struct v4l2_capability *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_capability`. - Description =========== @@ -46,10 +38,11 @@ pointer to a struct :c:type:`v4l2_capability` which is filled by the driver. When the driver is not compatible with this specification the ioctl returns an ``EINVAL`` error code. +.. c:type:: v4l2_capability -.. tabularcolumns:: |p{1.5cm}|p{2.5cm}|p{13cm}| +.. tabularcolumns:: |p{1.4cm}|p{2.8cm}|p{13.1cm}| -.. c:type:: v4l2_capability +.. cssclass:: longtable .. flat-table:: struct v4l2_capability :header-rows: 0 @@ -139,8 +132,7 @@ specification the ioctl returns an ``EINVAL`` error code. zero. - -.. tabularcolumns:: |p{6.1cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.0cm}|p{2.6cm}|p{7.7cm}| .. _device-capabilities: @@ -168,11 +160,11 @@ specification the ioctl returns an ``EINVAL`` error code. - The device supports the :ref:`multi-planar API <planar-apis>` through the :ref:`Video Output <output>` interface. * - ``V4L2_CAP_VIDEO_M2M`` - - 0x00004000 + - 0x00008000 - The device supports the single-planar API through the Video Memory-To-Memory interface. * - ``V4L2_CAP_VIDEO_M2M_MPLANE`` - - 0x00008000 + - 0x00004000 - The device supports the :ref:`multi-planar API <planar-apis>` through the Video Memory-To-Memory interface. * - ``V4L2_CAP_VIDEO_OVERLAY`` @@ -250,11 +242,19 @@ specification the ioctl returns an ``EINVAL`` error code. - The device supports the :ref:`metadata` capture interface. * - ``V4L2_CAP_READWRITE`` - 0x01000000 - - The device supports the :ref:`read() <rw>` and/or - :ref:`write() <rw>` I/O methods. - * - ``V4L2_CAP_ASYNCIO`` + - The device supports the :c:func:`read()` and/or + :c:func:`write()` I/O methods. + * - ``V4L2_CAP_EDID`` - 0x02000000 - - The device supports the :ref:`asynchronous <async>` I/O methods. + - The device stores the EDID for a video input, or retrieves the EDID for a video + output. It is a standalone EDID device, so no video streaming etc. will take place. + + For a video input this is typically an eeprom that supports the + :ref:`VESA Enhanced Display Data Channel Standard <vesaeddc>`. It can be something + else as well, for example a micro controller. + + For a video output this is typically read from an external device such as an + HDMI splitter accessed by a serial port. * - ``V4L2_CAP_STREAMING`` - 0x04000000 - The device supports the :ref:`streaming <mmap>` I/O method. @@ -276,7 +276,6 @@ specification the ioctl returns an ``EINVAL`` error code. only appear in the ``capabilities`` field and never in the ``device_caps`` field. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst index fbb0038d86bf..3549417c7feb 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_QUERYCTRL: @@ -18,31 +12,29 @@ Name VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items - Synopsis ======== -.. c:function:: int ioctl( int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp ) - :name: VIDIOC_QUERYCTRL +``int ioctl(int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp)`` + +.. c:macro:: VIDIOC_QUERY_EXT_CTRL -.. c:function:: int ioctl( int fd, VIDIOC_QUERY_EXT_CTRL, struct v4l2_query_ext_ctrl *argp ) - :name: VIDIOC_QUERY_EXT_CTRL +``int ioctl(int fd, VIDIOC_QUERY_EXT_CTRL, struct v4l2_query_ext_ctrl *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_QUERYMENU, struct v4l2_querymenu *argp ) - :name: VIDIOC_QUERYMENU +.. c:macro:: VIDIOC_QUERYMENU +``int ioctl(int fd, VIDIOC_QUERYMENU, struct v4l2_querymenu *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_queryctrl`, :c:type:`v4l2_query_ext_ctrl` or :c:type:`v4l2_querymenu` (depending on the ioctl). - Description =========== @@ -102,8 +94,7 @@ inclusive. See also the examples in :ref:`control`. - -.. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.7cm}| +.. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.5cm}| .. _v4l2-queryctrl: @@ -181,8 +172,7 @@ See also the examples in :ref:`control`. zero. - -.. tabularcolumns:: |p{1.2cm}|p{5.0cm}|p{11.3cm}| +.. tabularcolumns:: |p{1.2cm}|p{5.5cm}|p{10.6cm}| .. _v4l2-query-ext-ctrl: @@ -282,8 +272,7 @@ See also the examples in :ref:`control`. the array to zero. - -.. tabularcolumns:: |p{1.2cm}|p{1.0cm}|p{1.7cm}|p{13.0cm}| +.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.1cm}| .. _v4l2-querymenu: @@ -317,11 +306,13 @@ See also the examples in :ref:`control`. - Reserved for future extensions. Drivers must set the array to zero. +.. c:type:: v4l2_ctrl_type +.. raw:: latex -.. tabularcolumns:: |p{5.8cm}|p{1.4cm}|p{1.0cm}|p{1.4cm}|p{6.9cm}| + \footnotesize -.. c:type:: v4l2_ctrl_type +.. tabularcolumns:: |p{6.5cm}|p{1.5cm}|p{1.1cm}|p{1.5cm}|p{6.8cm}| .. cssclass:: longtable @@ -426,24 +417,40 @@ See also the examples in :ref:`control`. - any - An unsigned 32-bit valued control ranging from minimum to maximum inclusive. The step value indicates the increment between values. - * - ``V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS`` + * - ``V4L2_CTRL_TYPE_MPEG2_QUANTISATION`` - n/a - n/a - n/a - - A struct :c:type:`v4l2_ctrl_mpeg2_slice_params`, containing MPEG-2 - slice parameters for stateless video decoders. - * - ``V4L2_CTRL_TYPE_MPEG2_QUANTIZATION`` + - A struct :c:type:`v4l2_ctrl_mpeg2_quantisation`, containing MPEG-2 + quantisation matrices for stateless video decoders. + * - ``V4L2_CTRL_TYPE_MPEG2_SEQUENCE`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_mpeg2_sequence`, containing MPEG-2 + sequence parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_MPEG2_PICTURE`` - n/a - n/a - n/a - - A struct :c:type:`v4l2_ctrl_mpeg2_quantization`, containing MPEG-2 - quantization matrices for stateless video decoders. + - A struct :c:type:`v4l2_ctrl_mpeg2_picture`, containing MPEG-2 + picture parameters for stateless video decoders. * - ``V4L2_CTRL_TYPE_AREA`` - n/a - n/a - n/a - A struct :c:type:`v4l2_area`, containing the width and the height of a rectangular area. Units depend on the use case. + * - ``V4L2_CTRL_TYPE_RECT`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_rect`, containing a rectangle described by + the position of its top-left corner, the width and the height. Units + depend on the use case. Support for ``V4L2_CTRL_WHICH_MIN_VAL`` and + ``V4L2_CTRL_WHICH_MAX_VAL`` is optional and depends on the + ``V4L2_CTRL_FLAG_HAS_WHICH_MIN_MAX`` flag. See the documentation of + the specific control on how to interpret the minimum and maximum values. * - ``V4L2_CTRL_TYPE_H264_SPS`` - n/a - n/a @@ -474,6 +481,12 @@ See also the examples in :ref:`control`. - n/a - A struct :c:type:`v4l2_ctrl_h264_decode_params`, containing H264 decode parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_FWHT_PARAMS`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_fwht_params`, containing FWHT + parameters for stateless video decoders. * - ``V4L2_CTRL_TYPE_HEVC_SPS`` - n/a - n/a @@ -492,13 +505,71 @@ See also the examples in :ref:`control`. - n/a - A struct :c:type:`v4l2_ctrl_hevc_slice_params`, containing HEVC slice parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_HEVC_SCALING_MATRIX`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_hevc_scaling_matrix`, containing HEVC + scaling matrix for stateless video decoders. + * - ``V4L2_CTRL_TYPE_VP8_FRAME`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_vp8_frame`, containing VP8 + frame parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_HEVC_DECODE_PARAMS`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_hevc_decode_params`, containing HEVC + decoding parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_vp9_compressed_hdr`, containing VP9 + probabilities updates for stateless video decoders. + * - ``V4L2_CTRL_TYPE_VP9_FRAME`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_vp9_frame`, containing VP9 + frame decode parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_AV1_SEQUENCE`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_av1_sequence`, containing AV1 Sequence OBU + decoding parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_AV1_TILE_GROUP_ENTRY`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_av1_tile_group_entry`, containing AV1 Tile Group + OBU decoding parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_AV1_FRAME`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_av1_frame`, containing AV1 Frame/Frame + Header OBU decoding parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_AV1_FILM_GRAIN`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_av1_film_grain`, containing AV1 Film Grain + parameters for stateless video decoders. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. raw:: latex -.. _control-flags: + \normalsize + +.. tabularcolumns:: |p{7.3cm}|p{1.8cm}|p{8.2cm}| .. cssclass:: longtable +.. _control-flags: + .. flat-table:: Control Flags :header-rows: 0 :stub-columns: 0 @@ -588,7 +659,18 @@ See also the examples in :ref:`control`. ``V4L2_CTRL_FLAG_GRABBED`` flag when buffers are allocated or streaming is in progress since most drivers do not support changing the format in that case. - + * - ``V4L2_CTRL_FLAG_DYNAMIC_ARRAY`` + - 0x0800 + - This control is a dynamically sized 1-dimensional array. It + behaves the same as a regular array, except that the number + of elements as reported by the ``elems`` field is between 1 and + ``dims[0]``. So setting the control with a differently sized + array will change the ``elems`` field when the control is + queried afterwards. + * - ``V4L2_CTRL_FLAG_HAS_WHICH_MIN_MAX`` + - 0x1000 + - This control supports getting minimum and maximum values using + vidioc_g_ext_ctrls with V4L2_CTRL_WHICH_MIN/MAX_VAL. Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-querystd.rst b/Documentation/userspace-api/media/v4l/vidioc-querystd.rst index 899f0ef6eefe..4a88287d8f61 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-querystd.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-querystd.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_QUERYSTD: @@ -18,27 +12,26 @@ Name VIDIOC_QUERYSTD - VIDIOC_SUBDEV_QUERYSTD - Sense the video standard received by the current input - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_QUERYSTD, v4l2_std_id *argp ) - :name: VIDIOC_QUERYSTD +.. c:macro:: VIDIOC_QUERYSTD + +``int ioctl(int fd, VIDIOC_QUERYSTD, v4l2_std_id *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_QUERYSTD, v4l2_std_id *argp ) - :name: VIDIOC_SUBDEV_QUERYSTD +.. c:macro:: VIDIOC_SUBDEV_QUERYSTD +``int ioctl(int fd, VIDIOC_SUBDEV_QUERYSTD, v4l2_std_id *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to :c:type:`v4l2_std_id`. - Description =========== @@ -65,7 +58,6 @@ or output. standard is valid they will have to stop streaming, set the new standard, allocate new buffers and start streaming again. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-remove-bufs.rst b/Documentation/userspace-api/media/v4l/vidioc-remove-bufs.rst new file mode 100644 index 000000000000..1995b39af9ba --- /dev/null +++ b/Documentation/userspace-api/media/v4l/vidioc-remove-bufs.rst @@ -0,0 +1,86 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L + +.. _VIDIOC_REMOVE_BUFS: + +************************ +ioctl VIDIOC_REMOVE_BUFS +************************ + +Name +==== + +VIDIOC_REMOVE_BUFS - Removes buffers from a queue + +Synopsis +======== + +.. c:macro:: VIDIOC_REMOVE_BUFS + +``int ioctl(int fd, VIDIOC_REMOVE_BUFS, struct v4l2_remove_buffers *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + Pointer to struct :c:type:`v4l2_remove_buffers`. + +Description +=========== + +Applications can optionally call the :ref:`VIDIOC_REMOVE_BUFS` ioctl to +remove buffers from a queue. +:ref:`VIDIOC_CREATE_BUFS` ioctl support is mandatory to enable :ref:`VIDIOC_REMOVE_BUFS`. +This ioctl is available if the ``V4L2_BUF_CAP_SUPPORTS_REMOVE_BUFS`` capability +is set on the queue when :c:func:`VIDIOC_REQBUFS` or :c:func:`VIDIOC_CREATE_BUFS` +are invoked. + +.. c:type:: v4l2_remove_buffers + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| + +.. flat-table:: struct v4l2_remove_buffers + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``index`` + - The starting buffer index to remove. This field is ignored if count == 0. + * - __u32 + - ``count`` + - The number of buffers to be removed with indices 'index' until 'index + count - 1'. + All buffers in this range must be valid and in DEQUEUED state. + :ref:`VIDIOC_REMOVE_BUFS` will always check the validity of ``type`, if it is + invalid it returns ``EINVAL`` error code. + If count is set to 0 :ref:`VIDIOC_REMOVE_BUFS` will do nothing and return 0. + * - __u32 + - ``type`` + - Type of the stream or buffers, this is the same as the struct + :c:type:`v4l2_format` ``type`` field. See + :c:type:`v4l2_buf_type` for valid values. + * - __u32 + - ``reserved``\ [13] + - A place holder for future extensions. Drivers and applications + must set the array to zero. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. If an error occurs, no +buffers will be freed and one of the error codes below will be returned: + +EBUSY + File I/O is in progress. + One or more of the buffers in the range ``index`` to ``index + count - 1`` are not + in DEQUEUED state. + +EINVAL + One or more of the buffers in the range ``index`` to ``index + count - 1`` do not + exist in the queue. + The buffer type (``type`` field) is not valid. diff --git a/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst b/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst index b6d52083707b..daf9a6621b50 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_REQBUFS: @@ -18,19 +12,18 @@ Name VIDIOC_REQBUFS - Initiate Memory Mapping, User Pointer I/O or DMA buffer I/O - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_REQBUFS, struct v4l2_requestbuffers *argp ) - :name: VIDIOC_REQBUFS +.. c:macro:: VIDIOC_REQBUFS +``int ioctl(int fd, VIDIOC_REQBUFS, struct v4l2_requestbuffers *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_requestbuffers`. @@ -76,10 +69,11 @@ fds are closed. A ``count`` value of zero frees or orphans all buffers, after aborting or finishing any DMA in progress, an implicit :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`. - .. c:type:: v4l2_requestbuffers -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| + +.. cssclass:: longtable .. flat-table:: struct v4l2_requestbuffers :header-rows: 0 @@ -112,12 +106,13 @@ aborting or finishing any DMA in progress, an implicit ``V4L2_MEMORY_MMAP`` and ``type`` set to the buffer type. This will free any previously allocated buffers, so this is typically something that will be done at the start of the application. - * - __u32 - - ``reserved``\ [1] - - A place holder for future extensions. Drivers and applications - must set the array to zero. - -.. tabularcolumns:: |p{6.1cm}|p{2.2cm}|p{8.7cm}| + * - __u8 + - ``flags`` + - Specifies additional buffer management attributes. + See :ref:`memory-flags`. + * - __u8 + - ``reserved``\ [3] + - Reserved for future extensions. .. _v4l2-buf-capabilities: .. _V4L2-BUF-CAP-SUPPORTS-MMAP: @@ -126,8 +121,9 @@ aborting or finishing any DMA in progress, an implicit .. _V4L2-BUF-CAP-SUPPORTS-REQUESTS: .. _V4L2-BUF-CAP-SUPPORTS-ORPHANED-BUFS: .. _V4L2-BUF-CAP-SUPPORTS-M2M-HOLD-CAPTURE-BUF: - -.. cssclass:: longtable +.. _V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS: +.. _V4L2-BUF-CAP-SUPPORTS-MAX-NUM-BUFFERS: +.. _V4L2-BUF-CAP-SUPPORTS-REMOVE-BUFS: .. flat-table:: V4L2 Buffer Capabilities Flags :header-rows: 0 @@ -156,6 +152,48 @@ aborting or finishing any DMA in progress, an implicit - Only valid for stateless decoders. If set, then userspace can set the ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF`` flag to hold off on returning the capture buffer until the OUTPUT timestamp changes. + * - ``V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS`` + - 0x00000040 + - This capability is set by the driver to indicate that the queue supports + cache and memory management hints. However, it's only valid when the + queue is used for :ref:`memory mapping <mmap>` streaming I/O. See + :ref:`V4L2_BUF_FLAG_NO_CACHE_INVALIDATE <V4L2-BUF-FLAG-NO-CACHE-INVALIDATE>`, + :ref:`V4L2_BUF_FLAG_NO_CACHE_CLEAN <V4L2-BUF-FLAG-NO-CACHE-CLEAN>` and + :ref:`V4L2_MEMORY_FLAG_NON_COHERENT <V4L2-MEMORY-FLAG-NON-COHERENT>`. + * - ``V4L2_BUF_CAP_SUPPORTS_MAX_NUM_BUFFERS`` + - 0x00000080 + - If set, then the ``max_num_buffers`` field in ``struct v4l2_create_buffers`` + is valid. If not set, then the maximum is ``VIDEO_MAX_FRAME`` buffers. + * - ``V4L2_BUF_CAP_SUPPORTS_REMOVE_BUFS`` + - 0x00000100 + - If set, then ``VIDIOC_REMOVE_BUFS`` is supported. + +.. _memory-flags: +.. _V4L2-MEMORY-FLAG-NON-COHERENT: + +.. flat-table:: Memory Consistency Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - ``V4L2_MEMORY_FLAG_NON_COHERENT`` + - 0x00000001 + - A buffer is allocated either in coherent (it will be automatically + coherent between the CPU and the bus) or non-coherent memory. The + latter can provide performance gains, for instance the CPU cache + sync/flush operations can be avoided if the buffer is accessed by the + corresponding device only and the CPU does not read/write to/from that + buffer. However, this requires extra care from the driver -- it must + guarantee memory consistency by issuing a cache flush/sync when + consistency is needed. If this flag is set V4L2 will attempt to + allocate the buffer in non-coherent memory. The flag takes effect + only if the buffer is used for :ref:`memory mapping <mmap>` I/O and the + queue reports the :ref:`V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS + <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability. + +.. raw:: latex + + \normalsize Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst b/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst index 4c16e7e89cfa..ed10f380579a 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_S_HW_FREQ_SEEK: @@ -18,24 +12,22 @@ Name VIDIOC_S_HW_FREQ_SEEK - Perform a hardware frequency seek - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_S_HW_FREQ_SEEK, struct v4l2_hw_freq_seek *argp ) - :name: VIDIOC_S_HW_FREQ_SEEK +.. c:macro:: VIDIOC_S_HW_FREQ_SEEK +``int ioctl(int fd, VIDIOC_S_HW_FREQ_SEEK, struct v4l2_hw_freq_seek *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_hw_freq_seek`. - Description =========== @@ -66,8 +58,7 @@ set. If this ioctl is called from a non-blocking filehandle, then ``EAGAIN`` error code is returned and no seek takes place. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_hw_freq_seek @@ -123,7 +114,6 @@ error code is returned and no seek takes place. - Reserved for future extensions. Applications must set the array to zero. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-streamon.rst b/Documentation/userspace-api/media/v4l/vidioc-streamon.rst index 13e0136d5c25..1a79313a29fa 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-streamon.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-streamon.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_STREAMON: @@ -18,22 +12,22 @@ Name VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_STREAMON, const int *argp ) - :name: VIDIOC_STREAMON +.. c:macro:: VIDIOC_STREAMON + +``int ioctl(int fd, VIDIOC_STREAMON, const int *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_STREAMOFF, const int *argp ) - :name: VIDIOC_STREAMOFF +.. c:macro:: VIDIOC_STREAMOFF +``int ioctl(int fd, VIDIOC_STREAMOFF, const int *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to an integer. @@ -49,8 +43,7 @@ the capture or output process during streaming Capture hardware is disabled and no input buffers are filled (if there are any empty buffers in the incoming queue) until ``VIDIOC_STREAMON`` has been called. Output hardware is disabled and no video signal is -produced until ``VIDIOC_STREAMON`` has been called. The ioctl will -succeed when at least one output buffer is in the incoming queue. +produced until ``VIDIOC_STREAMON`` has been called. Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has been called for both the capture and output stream types. @@ -91,7 +84,6 @@ state as mentioned above. no notion of starting or stopping "now". Buffer timestamps can be used to synchronize with other events. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst index 3527745935c7..c935bacc3bc2 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL: @@ -18,24 +12,22 @@ Name VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL - Enumerate frame intervals - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL, struct v4l2_subdev_frame_interval_enum * argp ) - :name: VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL +.. c:macro:: VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL +``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL, struct v4l2_subdev_frame_interval_enum * argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_frame_interval_enum`. - Description =========== @@ -69,7 +61,7 @@ multiple pads of the same sub-device is not defined. .. c:type:: v4l2_subdev_frame_interval_enum -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_frame_interval_enum :header-rows: 0 @@ -100,11 +92,13 @@ multiple pads of the same sub-device is not defined. - Frame intervals to be enumerated, from enum :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. * - __u32 - - ``reserved``\ [8] + - ``stream`` + - Stream identifier. + * - __u32 + - ``reserved``\ [7] - Reserved for future extensions. Applications and drivers must set the array to zero. - Return Value ============ @@ -113,8 +107,7 @@ appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. EINVAL - The struct - :c:type:`v4l2_subdev_frame_interval_enum` - ``pad`` references a non-existing pad, one of the ``code``, - ``width`` or ``height`` fields are invalid for the given pad or the - ``index`` field is out of bounds. + The struct :c:type:`v4l2_subdev_frame_interval_enum` ``pad`` references a + non-existing pad, the ``which`` field has an unsupported value, one of the + ``code``, ``width`` or ``height`` fields are invalid for the given pad, or + the ``index`` field is out of bounds. diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst index eb7401991d02..65f0cfeca973 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_ENUM_FRAME_SIZE: @@ -18,39 +12,49 @@ Name VIDIOC_SUBDEV_ENUM_FRAME_SIZE - Enumerate media bus frame sizes - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUM_FRAME_SIZE, struct v4l2_subdev_frame_size_enum * argp ) - :name: VIDIOC_SUBDEV_ENUM_FRAME_SIZE +.. c:macro:: VIDIOC_SUBDEV_ENUM_FRAME_SIZE +``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_FRAME_SIZE, struct v4l2_subdev_frame_size_enum * argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_frame_size_enum`. - Description =========== -This ioctl allows applications to enumerate all frame sizes supported by -a sub-device on the given pad for the given media bus format. Supported -formats can be retrieved with the +This ioctl allows applications to access the enumeration of frame sizes +supported by a sub-device on the specified pad +for the specified media bus format. +Supported formats can be retrieved with the :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE` ioctl. -To enumerate frame sizes applications initialize the ``pad``, ``which`` -, ``code`` and ``index`` fields of the struct -:c:type:`v4l2_subdev_mbus_code_enum` and -call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_SIZE` ioctl with a pointer to the -structure. Drivers fill the minimum and maximum frame sizes or return an -EINVAL error code if one of the input parameters is invalid. +The enumerations are defined by the driver, and indexed using the ``index`` field +of the struct :c:type:`v4l2_subdev_frame_size_enum`. +Each pair of ``pad`` and ``code`` correspond to a separate enumeration. +Each enumeration starts with the ``index`` of 0, and +the lowest invalid index marks the end of the enumeration. + +Therefore, to enumerate frame sizes allowed on the specified pad +and using the specified mbus format, initialize the +``pad``, ``which``, and ``code`` fields to desired values, +and set ``index`` to 0. +Then call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_SIZE` ioctl with a pointer to the +structure. + +A successful call will return with minimum and maximum frame sizes filled in. +Repeat with increasing ``index`` until ``EINVAL`` is received. +``EINVAL`` means that either no more entries are available in the enumeration, +or that an input parameter was invalid. Sub-devices that only support discrete frame sizes (such as most sensors) will return one or more frame sizes with identical minimum and @@ -69,10 +73,9 @@ current values of V4L2 controls. See :ref:`VIDIOC_SUBDEV_G_FMT` for more information about try formats. - .. c:type:: v4l2_subdev_frame_size_enum -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_frame_size_enum :header-rows: 0 @@ -81,36 +84,40 @@ information about try formats. * - __u32 - ``index`` - - Number of the format in the enumeration, set by the application. + - Index of the frame size in the enumeration belonging to the given pad + and format. Filled in by the application. * - __u32 - ``pad`` - Pad number as reported by the media controller API. + Filled in by the application. * - __u32 - ``code`` - The media bus format code, as defined in - :ref:`v4l2-mbus-format`. + :ref:`v4l2-mbus-format`. Filled in by the application. * - __u32 - ``min_width`` - - Minimum frame width, in pixels. + - Minimum frame width, in pixels. Filled in by the driver. * - __u32 - ``max_width`` - - Maximum frame width, in pixels. + - Maximum frame width, in pixels. Filled in by the driver. * - __u32 - ``min_height`` - - Minimum frame height, in pixels. + - Minimum frame height, in pixels. Filled in by the driver. * - __u32 - ``max_height`` - - Maximum frame height, in pixels. + - Maximum frame height, in pixels. Filled in by the driver. * - __u32 - ``which`` - Frame sizes to be enumerated, from enum :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. * - __u32 - - ``reserved``\ [8] + - ``stream`` + - Stream identifier. + * - __u32 + - ``reserved``\ [7] - Reserved for future extensions. Applications and drivers must set the array to zero. - Return Value ============ @@ -119,7 +126,6 @@ appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. EINVAL - The struct - :c:type:`v4l2_subdev_frame_size_enum` - ``pad`` references a non-existing pad, the ``code`` is invalid for - the given pad or the ``index`` field is out of bounds. + The struct :c:type:`v4l2_subdev_frame_size_enum` ``pad`` references a + non-existing pad, the ``which`` field has an unsupported value, the ``code`` + is invalid for the given pad, or the ``index`` field is out of bounds. diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst index 35b8607203a4..3050966b199f 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_ENUM_MBUS_CODE: @@ -18,46 +12,56 @@ Name VIDIOC_SUBDEV_ENUM_MBUS_CODE - Enumerate media bus formats - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUM_MBUS_CODE, struct v4l2_subdev_mbus_code_enum * argp ) - :name: VIDIOC_SUBDEV_ENUM_MBUS_CODE +.. c:macro:: VIDIOC_SUBDEV_ENUM_MBUS_CODE +``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_MBUS_CODE, struct v4l2_subdev_mbus_code_enum * argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_mbus_code_enum`. - Description =========== -To enumerate media bus formats available at a given sub-device pad -applications initialize the ``pad``, ``which`` and ``index`` fields of -struct -:c:type:`v4l2_subdev_mbus_code_enum` and -call the :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE` ioctl with a pointer to this -structure. Drivers fill the rest of the structure or return an ``EINVAL`` -error code if either the ``pad`` or ``index`` are invalid. All media bus -formats are enumerable by beginning at index zero and incrementing by -one until ``EINVAL`` is returned. +This call is used by the application to access the enumeration +of media bus formats for the selected pad. + +The enumerations are defined by the driver, and indexed using the ``index`` field +of struct :c:type:`v4l2_subdev_mbus_code_enum`. +Each enumeration starts with the ``index`` of 0, and +the lowest invalid index marks the end of enumeration. + +Therefore, to enumerate media bus formats available at a given sub-device pad, +initialize the ``pad``, and ``which`` fields to desired values, +and set ``index`` to 0. +Then call the :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE` ioctl +with a pointer to this structure. + +A successful call will return with the ``code`` field filled in +with a mbus code value. +Repeat with increasing ``index`` until ``EINVAL`` is received. +``EINVAL`` means that either ``pad`` is invalid, +or that there are no more codes available at this pad. + +The driver must not return the same value of ``code`` for different indices +at the same pad. Available media bus formats may depend on the current 'try' formats at other pads of the sub-device, as well as on the current active links. See :ref:`VIDIOC_SUBDEV_G_FMT` for more information about the try formats. - .. c:type:: v4l2_subdev_mbus_code_enum -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_mbus_code_enum :header-rows: 0 @@ -66,24 +70,86 @@ information about the try formats. * - __u32 - ``pad`` - - Pad number as reported by the media controller API. + - Pad number as reported by the media controller API. Filled in by the + application. * - __u32 - ``index`` - - Number of the format in the enumeration, set by the application. + - Index of the mbus code in the enumeration belonging to the given pad. + Filled in by the application. * - __u32 - ``code`` - The media bus format code, as defined in - :ref:`v4l2-mbus-format`. + :ref:`v4l2-mbus-format`. Filled in by the driver. * - __u32 - ``which`` - Media bus format codes to be enumerated, from enum :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. * - __u32 - - ``reserved``\ [8] + - ``flags`` + - See :ref:`v4l2-subdev-mbus-code-flags` + * - __u32 + - ``stream`` + - Stream identifier. + * - __u32 + - ``reserved``\ [6] - Reserved for future extensions. Applications and drivers must set the array to zero. + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{8.8cm}|p{2.2cm}|p{6.3cm}| + +.. _v4l2-subdev-mbus-code-flags: + +.. flat-table:: Subdev Media Bus Code Enumerate Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - V4L2_SUBDEV_MBUS_CODE_CSC_COLORSPACE + - 0x00000001 + - The driver allows the application to try to change the default colorspace + encoding. The application can ask to configure the colorspace of the + subdevice when calling the :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` + ioctl with :ref:`V4L2_MBUS_FRAMEFMT_SET_CSC <mbus-framefmt-set-csc>` set. + See :ref:`v4l2-mbus-format` on how to do this. + * - V4L2_SUBDEV_MBUS_CODE_CSC_XFER_FUNC + - 0x00000002 + - The driver allows the application to try to change the default transform function. + The application can ask to configure the transform function of + the subdevice when calling the :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` + ioctl with :ref:`V4L2_MBUS_FRAMEFMT_SET_CSC <mbus-framefmt-set-csc>` set. + See :ref:`v4l2-mbus-format` on how to do this. + * - V4L2_SUBDEV_MBUS_CODE_CSC_YCBCR_ENC + - 0x00000004 + - The driver allows the application to try to change the default Y'CbCr + encoding. The application can ask to configure the Y'CbCr encoding of the + subdevice when calling the :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` + ioctl with :ref:`V4L2_MBUS_FRAMEFMT_SET_CSC <mbus-framefmt-set-csc>` set. + See :ref:`v4l2-mbus-format` on how to do this. + * - V4L2_SUBDEV_MBUS_CODE_CSC_HSV_ENC + - 0x00000004 + - The driver allows the application to try to change the default HSV + encoding. The application can ask to configure the HSV encoding of the + subdevice when calling the :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` + ioctl with :ref:`V4L2_MBUS_FRAMEFMT_SET_CSC <mbus-framefmt-set-csc>` set. + See :ref:`v4l2-mbus-format` on how to do this. + * - V4L2_SUBDEV_MBUS_CODE_CSC_QUANTIZATION + - 0x00000008 + - The driver allows the application to try to change the default + quantization. The application can ask to configure the quantization of + the subdevice when calling the :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` + ioctl with :ref:`V4L2_MBUS_FRAMEFMT_SET_CSC <mbus-framefmt-set-csc>` set. + See :ref:`v4l2-mbus-format` on how to do this. + +.. raw:: latex + + \normalsize + Return Value ============ @@ -92,7 +158,6 @@ appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. EINVAL - The struct - :c:type:`v4l2_subdev_mbus_code_enum` - ``pad`` references a non-existing pad, or the ``index`` field is out - of bounds. + The struct :c:type:`v4l2_subdev_mbus_code_enum` ``pad`` references a + non-existing pad, the ``which`` field has an unsupported value, or the + ``index`` field is out of bounds. diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-client-cap.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-client-cap.rst new file mode 100644 index 000000000000..da4a358ce762 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-client-cap.rst @@ -0,0 +1,103 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L + +.. _VIDIOC_SUBDEV_G_CLIENT_CAP: + +************************************************************ +ioctl VIDIOC_SUBDEV_G_CLIENT_CAP, VIDIOC_SUBDEV_S_CLIENT_CAP +************************************************************ + +Name +==== + +VIDIOC_SUBDEV_G_CLIENT_CAP - VIDIOC_SUBDEV_S_CLIENT_CAP - Get or set client +capabilities. + +Synopsis +======== + +.. c:macro:: VIDIOC_SUBDEV_G_CLIENT_CAP + +``int ioctl(int fd, VIDIOC_SUBDEV_G_CLIENT_CAP, struct v4l2_subdev_client_capability *argp)`` + +.. c:macro:: VIDIOC_SUBDEV_S_CLIENT_CAP + +``int ioctl(int fd, VIDIOC_SUBDEV_S_CLIENT_CAP, struct v4l2_subdev_client_capability *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``argp`` + Pointer to struct :c:type:`v4l2_subdev_client_capability`. + +Description +=========== + +These ioctls are used to get and set the client (the application using the +subdevice ioctls) capabilities. The client capabilities are stored in the file +handle of the opened subdev device node, and the client must set the +capabilities for each opened subdev separately. + +By default no client capabilities are set when a subdev device node is opened. + +The purpose of the client capabilities are to inform the kernel of the behavior +of the client, mainly related to maintaining compatibility with different +kernel and userspace versions. + +The ``VIDIOC_SUBDEV_G_CLIENT_CAP`` ioctl returns the current client capabilities +associated with the file handle ``fd``. + +The ``VIDIOC_SUBDEV_S_CLIENT_CAP`` ioctl sets client capabilities for the file +handle ``fd``. The new capabilities fully replace the current capabilities, the +ioctl can therefore also be used to remove capabilities that have previously +been set. + +``VIDIOC_SUBDEV_S_CLIENT_CAP`` modifies the struct +:c:type:`v4l2_subdev_client_capability` to reflect the capabilities that have +been accepted. A common case for the kernel not accepting a capability is that +the kernel is older than the headers the userspace uses, and thus the capability +is unknown to the kernel. + +.. tabularcolumns:: |p{1.5cm}|p{2.9cm}|p{12.9cm}| + +.. c:type:: v4l2_subdev_client_capability + +.. flat-table:: struct v4l2_subdev_client_capability + :header-rows: 0 + :stub-columns: 0 + :widths: 3 4 20 + + * - __u64 + - ``capabilities`` + - Sub-device client capabilities of the opened device. + +.. tabularcolumns:: |p{6.8cm}|p{2.4cm}|p{8.1cm}| + +.. flat-table:: Client Capabilities + :header-rows: 1 + + * - Capability + - Description + * - ``V4L2_SUBDEV_CLIENT_CAP_STREAMS`` + - The client is aware of streams. Setting this flag enables the use + of 'stream' fields (referring to the stream number) with various + ioctls. If this is not set (which is the default), the 'stream' fields + will be forced to 0 by the kernel. + * - ``V4L2_SUBDEV_CLIENT_CAP_INTERVAL_USES_WHICH`` + - The client is aware of the :c:type:`v4l2_subdev_frame_interval` + ``which`` field. If this is not set (which is the default), the + ``which`` field is forced to ``V4L2_SUBDEV_FORMAT_ACTIVE`` by the + kernel. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +ENOIOCTLCMD + The kernel does not support this ioctl. diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst index 615e3efdf935..88a748103a71 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_G_CROP: @@ -18,35 +12,34 @@ Name VIDIOC_SUBDEV_G_CROP - VIDIOC_SUBDEV_S_CROP - Get or set the crop rectangle on a subdev pad - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_CROP, struct v4l2_subdev_crop *argp ) - :name: VIDIOC_SUBDEV_G_CROP +.. c:macro:: VIDIOC_SUBDEV_G_CROP + +``int ioctl(int fd, VIDIOC_SUBDEV_G_CROP, struct v4l2_subdev_crop *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_CROP, const struct v4l2_subdev_crop *argp ) - :name: VIDIOC_SUBDEV_S_CROP +.. c:macro:: VIDIOC_SUBDEV_S_CROP +``int ioctl(int fd, VIDIOC_SUBDEV_S_CROP, const struct v4l2_subdev_crop *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_crop`. - Description =========== .. note:: - This is an :ref:`obsolete` interface and may be removed - in the future. It is superseded by - :ref:`the selection API <VIDIOC_SUBDEV_G_SELECTION>`. + This is an :ref:`obsolete` interface and may be removed in the future. It is + superseded by :ref:`the selection API <VIDIOC_SUBDEV_G_SELECTION>`. No new + extensions to the :c:type:`v4l2_subdev_crop` structure will be accepted. To retrieve the current crop rectangle applications set the ``pad`` field of a struct :c:type:`v4l2_subdev_crop` to the @@ -83,10 +76,9 @@ rectangle doesn't match the device capabilities. They must instead modify the rectangle to match what the hardware can provide. The modified format should be as close as possible to the original request. - .. c:type:: v4l2_subdev_crop -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_crop :header-rows: 0 @@ -104,11 +96,13 @@ modified format should be as close as possible to the original request. - ``rect`` - Crop rectangle boundaries, in pixels. * - __u32 - - ``reserved``\ [8] + - ``stream`` + - Stream identifier. + * - __u32 + - ``reserved``\ [7] - Reserved for future extensions. Applications and drivers must set the array to zero. - Return Value ============ @@ -124,10 +118,9 @@ EBUSY ``VIDIOC_SUBDEV_S_CROP`` EINVAL - The struct :c:type:`v4l2_subdev_crop` ``pad`` - references a non-existing pad, the ``which`` field references a - non-existing format, or cropping is not supported on the given - subdev pad. + The struct :c:type:`v4l2_subdev_crop` ``pad`` references a non-existing pad, + the ``which`` field has an unsupported value, or cropping is not supported + on the given subdev pad. EPERM The ``VIDIOC_SUBDEV_S_CROP`` ioctl has been called on a read-only subdevice diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst index 909ee9f90867..4a2b4e4f0152 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_G_FMT: @@ -18,27 +12,26 @@ Name VIDIOC_SUBDEV_G_FMT - VIDIOC_SUBDEV_S_FMT - Get or set the data format on a subdev pad - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_FMT, struct v4l2_subdev_format *argp ) - :name: VIDIOC_SUBDEV_G_FMT +.. c:macro:: VIDIOC_SUBDEV_G_FMT + +``int ioctl(int fd, VIDIOC_SUBDEV_G_FMT, struct v4l2_subdev_format *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_FMT, struct v4l2_subdev_format *argp ) - :name: VIDIOC_SUBDEV_S_FMT +.. c:macro:: VIDIOC_SUBDEV_S_FMT +``int ioctl(int fd, VIDIOC_SUBDEV_S_FMT, struct v4l2_subdev_format *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_format`. - Description =========== @@ -88,8 +81,7 @@ doesn't match the device capabilities. They must instead modify the format to match what the hardware can provide. The modified format should be as close as possible to the original request. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_subdev_format @@ -110,13 +102,15 @@ should be as close as possible to the original request. - Definition of an image format, see :c:type:`v4l2_mbus_framefmt` for details. * - __u32 - - ``reserved``\ [8] + - ``stream`` + - Stream identifier. + * - __u32 + - ``reserved``\ [7] - Reserved for future extensions. Applications and drivers must set the array to zero. - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _v4l2-subdev-format-whence: @@ -132,7 +126,6 @@ should be as close as possible to the original request. - 1 - Active formats, applied to the hardware. - Return Value ============ @@ -147,9 +140,8 @@ EBUSY fix the problem first. Only returned by ``VIDIOC_SUBDEV_S_FMT`` EINVAL - The struct :c:type:`v4l2_subdev_format` - ``pad`` references a non-existing pad, or the ``which`` field - references a non-existing format. + The struct :c:type:`v4l2_subdev_format` ``pad`` references a non-existing + pad, or the ``which`` field has an unsupported value. EPERM The ``VIDIOC_SUBDEV_S_FMT`` ioctl has been called on a read-only subdevice diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst index 51e1bff797f0..c8022809ac35 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_G_FRAME_INTERVAL: @@ -18,27 +12,26 @@ Name VIDIOC_SUBDEV_G_FRAME_INTERVAL - VIDIOC_SUBDEV_S_FRAME_INTERVAL - Get or set the frame interval on a subdev pad - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_FRAME_INTERVAL, struct v4l2_subdev_frame_interval *argp ) - :name: VIDIOC_SUBDEV_G_FRAME_INTERVAL +.. c:macro:: VIDIOC_SUBDEV_G_FRAME_INTERVAL + +``int ioctl(int fd, VIDIOC_SUBDEV_G_FRAME_INTERVAL, struct v4l2_subdev_frame_interval *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_FRAME_INTERVAL, struct v4l2_subdev_frame_interval *argp ) - :name: VIDIOC_SUBDEV_S_FRAME_INTERVAL +.. c:macro:: VIDIOC_SUBDEV_S_FRAME_INTERVAL +``int ioctl(int fd, VIDIOC_SUBDEV_S_FRAME_INTERVAL, struct v4l2_subdev_frame_interval *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_frame_interval`. - Description =========== @@ -65,8 +58,9 @@ struct contains the current frame interval as would be returned by a ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call. -Calling ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` on a subdev device node that has been -registered in read-only mode is not allowed. An error is returned and the errno +If the subdev device node has been registered in read-only mode, calls to +``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` are only valid if the ``which`` field is set +to ``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno variable is set to ``-EPERM``. Drivers must not return an error solely because the requested interval @@ -81,10 +75,9 @@ Sub-devices that support the frame interval ioctls should implement them on a single pad only. Their behaviour when supported on multiple pads of the same sub-device is not defined. - .. c:type:: v4l2_subdev_frame_interval -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_frame_interval :header-rows: 0 @@ -98,11 +91,17 @@ the same sub-device is not defined. - ``interval`` - Period, in seconds, between consecutive video frames. * - __u32 - - ``reserved``\ [9] + - ``stream`` + - Stream identifier. + * - __u32 + - ``which`` + - Active or try frame interval, from enum + :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. + * - __u32 + - ``reserved``\ [7] - Reserved for future extensions. Applications and drivers must set the array to zero. - Return Value ============ @@ -118,11 +117,10 @@ EBUSY ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` EINVAL - The struct - :c:type:`v4l2_subdev_frame_interval` - ``pad`` references a non-existing pad, or the pad doesn't support - frame intervals. + The struct :c:type:`v4l2_subdev_frame_interval` ``pad`` references a + non-existing pad, the ``which`` field has an unsupported value, or the pad + doesn't support frame intervals. EPERM The ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl has been called on a read-only - subdevice. + subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``. diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-routing.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-routing.rst new file mode 100644 index 000000000000..1cf795480602 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-routing.rst @@ -0,0 +1,164 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L + +.. _VIDIOC_SUBDEV_G_ROUTING: + +****************************************************** +ioctl VIDIOC_SUBDEV_G_ROUTING, VIDIOC_SUBDEV_S_ROUTING +****************************************************** + +Name +==== + +VIDIOC_SUBDEV_G_ROUTING - VIDIOC_SUBDEV_S_ROUTING - Get or set routing between streams of media pads in a media entity. + + +Synopsis +======== + +.. c:macro:: VIDIOC_SUBDEV_G_ROUTING + +``int ioctl(int fd, VIDIOC_SUBDEV_G_ROUTING, struct v4l2_subdev_routing *argp)`` + +.. c:macro:: VIDIOC_SUBDEV_S_ROUTING + +``int ioctl(int fd, VIDIOC_SUBDEV_S_ROUTING, struct v4l2_subdev_routing *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``argp`` + Pointer to struct :c:type:`v4l2_subdev_routing`. + + +Description +=========== + +These ioctls are used to get and set the routing in a media entity. +The routing configuration determines the flows of data inside an entity. + +Drivers report their current routing tables using the +``VIDIOC_SUBDEV_G_ROUTING`` ioctl and application may enable or disable routes +with the ``VIDIOC_SUBDEV_S_ROUTING`` ioctl, by adding or removing routes and +setting or clearing flags of the ``flags`` field of a struct +:c:type:`v4l2_subdev_route`. Similarly to ``VIDIOC_SUBDEV_G_ROUTING``, also +``VIDIOC_SUBDEV_S_ROUTING`` returns the routes back to the user. + +All stream configurations are reset when ``VIDIOC_SUBDEV_S_ROUTING`` is called. +This means that the userspace must reconfigure all stream formats and selections +after calling the ioctl with e.g. ``VIDIOC_SUBDEV_S_FMT``. + +Only subdevices which have both sink and source pads can support routing. + +The ``len_routes`` field indicates the number of routes that can fit in the +``routes`` array allocated by userspace. It is set by applications for both +ioctls to indicate how many routes the kernel can return, and is never modified +by the kernel. + +The ``num_routes`` field indicates the number of routes in the routing +table. For ``VIDIOC_SUBDEV_S_ROUTING``, it is set by userspace to the number of +routes that the application stored in the ``routes`` array. For both ioctls, it +is returned by the kernel and indicates how many routes are stored in the +subdevice routing table. This may be smaller or larger than the value of +``num_routes`` set by the application for ``VIDIOC_SUBDEV_S_ROUTING``, as +drivers may adjust the requested routing table. + +The kernel can return a ``num_routes`` value larger than ``len_routes`` from +both ioctls. This indicates thare are more routes in the routing table than fits +the ``routes`` array. In this case, the ``routes`` array is filled by the kernel +with the first ``len_routes`` entries of the subdevice routing table. This is +not considered to be an error, and the ioctl call succeeds. If the applications +wants to retrieve the missing routes, it can issue a new +``VIDIOC_SUBDEV_G_ROUTING`` call with a large enough ``routes`` array. + +``VIDIOC_SUBDEV_S_ROUTING`` may return more routes than the user provided in +``num_routes`` field due to e.g. hardware properties. + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| + +.. c:type:: v4l2_subdev_routing + +.. flat-table:: struct v4l2_subdev_routing + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``which`` + - Routing table to be accessed, from enum + :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. + * - __u32 + - ``len_routes`` + - The length of the array (as in memory reserved for the array) + * - struct :c:type:`v4l2_subdev_route` + - ``routes[]`` + - Array of struct :c:type:`v4l2_subdev_route` entries + * - __u32 + - ``num_routes`` + - Number of entries of the routes array + * - __u32 + - ``reserved``\ [11] + - Reserved for future extensions. Applications and drivers must set + the array to zero. + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| + +.. c:type:: v4l2_subdev_route + +.. flat-table:: struct v4l2_subdev_route + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``sink_pad`` + - Sink pad number. + * - __u32 + - ``sink_stream`` + - Sink pad stream number. + * - __u32 + - ``source_pad`` + - Source pad number. + * - __u32 + - ``source_stream`` + - Source pad stream number. + * - __u32 + - ``flags`` + - Route enable/disable flags + :ref:`v4l2_subdev_routing_flags <v4l2-subdev-routing-flags>`. + * - __u32 + - ``reserved``\ [5] + - Reserved for future extensions. Applications and drivers must set + the array to zero. + +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| + +.. _v4l2-subdev-routing-flags: + +.. flat-table:: enum v4l2_subdev_routing_flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - V4L2_SUBDEV_ROUTE_FL_ACTIVE + - 0x0001 + - The route is enabled. Set by applications. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The sink or source pad identifiers reference a non-existing pad or reference + pads of different types (ie. the sink_pad identifiers refers to a source + pad), or the ``which`` field has an unsupported value. + +E2BIG + The application provided ``num_routes`` for ``VIDIOC_SUBDEV_S_ROUTING`` is + larger than the number of routes the driver can handle. diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst index 06c9553ac48f..19e6c3e9c06d 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_G_SELECTION: @@ -18,27 +12,26 @@ Name VIDIOC_SUBDEV_G_SELECTION - VIDIOC_SUBDEV_S_SELECTION - Get or set selection rectangles on a subdev pad - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_SELECTION, struct v4l2_subdev_selection *argp ) - :name: VIDIOC_SUBDEV_G_SELECTION +.. c:macro:: VIDIOC_SUBDEV_G_SELECTION + +``int ioctl(int fd, VIDIOC_SUBDEV_G_SELECTION, struct v4l2_subdev_selection *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_SELECTION, struct v4l2_subdev_selection *argp ) - :name: VIDIOC_SUBDEV_S_SELECTION +.. c:macro:: VIDIOC_SUBDEV_S_SELECTION +``int ioctl(int fd, VIDIOC_SUBDEV_S_SELECTION, struct v4l2_subdev_selection *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_selection`. - Description =========== @@ -65,7 +58,6 @@ There are two types of selection targets: actual and bounds. The actual targets are the targets which configure the hardware. The BOUNDS target will return a rectangle that contain all possible actual rectangles. - Discovering supported features ------------------------------ @@ -76,10 +68,9 @@ return ``EINVAL``. Selection targets and flags are documented in :ref:`v4l2-selections-common`. - .. c:type:: v4l2_subdev_selection -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_selection :header-rows: 0 @@ -103,11 +94,13 @@ Selection targets and flags are documented in - ``r`` - Selection rectangle, in pixels. * - __u32 - - ``reserved``\ [8] + - ``stream`` + - Stream identifier. + * - __u32 + - ``reserved``\ [7] - Reserved for future extensions. Applications and drivers must set the array to zero. - Return Value ============ @@ -123,10 +116,9 @@ EBUSY ``VIDIOC_SUBDEV_S_SELECTION`` EINVAL - The struct :c:type:`v4l2_subdev_selection` - ``pad`` references a non-existing pad, the ``which`` field - references a non-existing format, or the selection target is not - supported on the given subdev pad. + The struct :c:type:`v4l2_subdev_selection` ``pad`` references a + non-existing pad, the ``which`` field has an unsupported value, or the + selection target is not supported on the given subdev pad. EPERM The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst index 0371a76321af..9b8d8644ec0f 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBDEV_QUERYCAP: @@ -18,24 +12,22 @@ Name VIDIOC_SUBDEV_QUERYCAP - Query sub-device capabilities - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_QUERYCAP, struct v4l2_subdev_capability *argp ) - :name: VIDIOC_SUBDEV_QUERYCAP +.. c:macro:: VIDIOC_SUBDEV_QUERYCAP +``int ioctl(int fd, VIDIOC_SUBDEV_QUERYCAP, struct v4l2_subdev_capability *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_subdev_capability`. - Description =========== @@ -46,7 +38,7 @@ a struct :c:type:`v4l2_subdev_capability` which is filled by the driver. When the driver is not compatible with this specification the ioctl returns ``ENOTTY`` error code. -.. tabularcolumns:: |p{1.5cm}|p{2.5cm}|p{13cm}| +.. tabularcolumns:: |p{1.5cm}|p{2.9cm}|p{12.9cm}| .. c:type:: v4l2_subdev_capability @@ -83,7 +75,7 @@ the driver is not compatible with this specification the ioctl returns - ``reserved``\ [14] - Reserved for future extensions. Set to 0 by the V4L2 core. -.. tabularcolumns:: |p{6cm}|p{2.2cm}|p{8.8cm}| +.. tabularcolumns:: |p{6.8cm}|p{2.4cm}|p{8.1cm}| .. _subdevice-capabilities: diff --git a/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst b/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst index ae3ed73c0a9e..a6fc3c5fe99d 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst @@ -1,11 +1,5 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _VIDIOC_SUBSCRIBE_EVENT: .. _VIDIOC_UNSUBSCRIBE_EVENT: @@ -19,35 +13,33 @@ Name VIDIOC_SUBSCRIBE_EVENT - VIDIOC_UNSUBSCRIBE_EVENT - Subscribe or unsubscribe event - Synopsis ======== -.. c:function:: int ioctl( int fd, VIDIOC_SUBSCRIBE_EVENT, struct v4l2_event_subscription *argp ) - :name: VIDIOC_SUBSCRIBE_EVENT +.. c:macro:: VIDIOC_SUBSCRIBE_EVENT + +``int ioctl(int fd, VIDIOC_SUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)`` -.. c:function:: int ioctl( int fd, VIDIOC_UNSUBSCRIBE_EVENT, struct v4l2_event_subscription *argp ) - :name: VIDIOC_UNSUBSCRIBE_EVENT +.. c:macro:: VIDIOC_UNSUBSCRIBE_EVENT +``int ioctl(int fd, VIDIOC_UNSUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)`` Arguments ========= ``fd`` - File descriptor returned by :ref:`open() <func-open>`. + File descriptor returned by :c:func:`open()`. ``argp`` Pointer to struct :c:type:`v4l2_event_subscription`. - Description =========== Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by using the :ref:`VIDIOC_DQEVENT` ioctl. - -.. tabularcolumns:: |p{4.6cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{2.6cm}|p{4.4cm}|p{10.3cm}| .. c:type:: v4l2_event_subscription @@ -79,8 +71,7 @@ using the :ref:`VIDIOC_DQEVENT` ioctl. the array to zero. - -.. tabularcolumns:: |p{6.8cm}|p{2.2cm}|p{8.5cm}| +.. tabularcolumns:: |p{7.5cm}|p{2.0cm}|p{7.8cm}| .. _event-flags: @@ -114,7 +105,6 @@ using the :ref:`VIDIOC_DQEVENT` ioctl. Think carefully when you set this flag so you won't get into situations like that. - Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/yuv-formats.rst b/Documentation/userspace-api/media/v4l/yuv-formats.rst index 8ee92d0cd769..78ee406d7647 100644 --- a/Documentation/userspace-api/media/v4l/yuv-formats.rst +++ b/Documentation/userspace-api/media/v4l/yuv-formats.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _yuv-formats: @@ -21,44 +14,261 @@ reconstructed by subtracting from the brightness component. See :ref:`colorspaces` for conversion examples. YUV was chosen because early television would only transmit brightness information. To add color in a way compatible with existing receivers a new signal carrier -was added to transmit the color difference signals. Secondary in the YUV -format the U and V components usually have lower resolution than the Y -component. This is an analog video compression technique taking -advantage of a property of the human visual system, being more sensitive -to brightness information. +was added to transmit the color difference signals. + + +Subsampling +=========== + +YUV formats commonly encode images with a lower resolution for the chroma +components than for the luma component. This compression technique, taking +advantage of the human eye being more sensitive to luminance than color +differences, is called chroma subsampling. + +While many combinations of subsampling factors in the horizontal and vertical +direction are possible, common factors are 1 (no subsampling), 2 and 4, with +horizontal subsampling always larger than or equal to vertical subsampling. +Common combinations are named as follows. + +- `4:4:4`: No subsampling +- `4:2:2`: Horizontal subsampling by 2, no vertical subsampling +- `4:2:0`: Horizontal subsampling by 2, vertical subsampling by 2 +- `4:1:1`: Horizontal subsampling by 4, no vertical subsampling +- `4:1:0`: Horizontal subsampling by 4, vertical subsampling by 4 + +Subsampling the chroma component effectively creates chroma values that can be +located in different spatial locations: + +- .. _yuv-chroma-centered: + + The subsampled chroma value may be calculated by simply averaging the chroma + value of two consecutive pixels. It effectively models the chroma of a pixel + sited between the two original pixels. This is referred to as centered or + interstitially sited chroma. + +- .. _yuv-chroma-cosited: + + The other option is to subsample chroma values in a way that place them in + the same spatial sites as the pixels. This may be performed by skipping every + other chroma sample (creating aliasing artifacts), or with filters using an + odd number of taps. This is referred to as co-sited chroma. + +The following examples show different combination of chroma siting in a 4x4 +image. + +.. flat-table:: 4:2:2 subsampling, interstitially sited + :header-rows: 1 + :stub-columns: 1 + + * - + - 0 + - + - 1 + - + - 2 + - + - 3 + * - 0 + - Y + - C + - Y + - + - Y + - C + - Y + * - 1 + - Y + - C + - Y + - + - Y + - C + - Y + * - 2 + - Y + - C + - Y + - + - Y + - C + - Y + * - 3 + - Y + - C + - Y + - + - Y + - C + - Y + +.. flat-table:: 4:2:2 subsampling, co-sited + :header-rows: 1 + :stub-columns: 1 + + * - + - 0 + - + - 1 + - + - 2 + - + - 3 + * - 0 + - Y/C + - + - Y + - + - Y/C + - + - Y + * - 1 + - Y/C + - + - Y + - + - Y/C + - + - Y + * - 2 + - Y/C + - + - Y + - + - Y/C + - + - Y + * - 3 + - Y/C + - + - Y + - + - Y/C + - + - Y + +.. flat-table:: 4:2:0 subsampling, horizontally interstitially sited, vertically co-sited + :header-rows: 1 + :stub-columns: 1 + + * - + - 0 + - + - 1 + - + - 2 + - + - 3 + * - 0 + - Y + - C + - Y + - + - Y + - C + - Y + * - 1 + - Y + - + - Y + - + - Y + - + - Y + * - 2 + - Y + - C + - Y + - + - Y + - C + - Y + * - 3 + - Y + - + - Y + - + - Y + - + - Y + +.. flat-table:: 4:1:0 subsampling, horizontally and vertically interstitially sited + :header-rows: 1 + :stub-columns: 1 + + * - + - 0 + - + - 1 + - + - 2 + - + - 3 + * - 0 + - Y + - + - Y + - + - Y + - + - Y + * - + - + - + - + - + - + - + - + * - 1 + - Y + - + - Y + - + - Y + - + - Y + * - + - + - + - + - C + - + - + - + * - 2 + - Y + - + - Y + - + - Y + - + - Y + * - + - + - + - + - + - + - + - + * - 3 + - Y + - + - Y + - + - Y + - + - Y .. toctree:: :maxdepth: 1 pixfmt-packed-yuv - pixfmt-grey - pixfmt-y10 - pixfmt-y12 - pixfmt-y14 - pixfmt-y10b - pixfmt-y10p - pixfmt-y16 - pixfmt-y16-be + pixfmt-yuv-planar + pixfmt-yuv-luma pixfmt-y8i pixfmt-y12i + pixfmt-y16i pixfmt-uv8 - pixfmt-yuyv - pixfmt-uyvy - pixfmt-yvyu - pixfmt-vyuy - pixfmt-y41p - pixfmt-yuv420 - pixfmt-yuv420m - pixfmt-yuv422m - pixfmt-yuv444m - pixfmt-yuv410 - pixfmt-yuv422p - pixfmt-yuv411p - pixfmt-nv12 - pixfmt-nv12m - pixfmt-nv12mt - pixfmt-nv16 - pixfmt-nv16m - pixfmt-nv24 pixfmt-m420 |
