diff mbox series

[v2,3/5] docs: uapi: media: Add common documentation of tiled NV15

Message ID 20230914150651.3114134-4-nicolas.dufresne@collabora.com
State New
Headers show
Series [v2,1/5] docs: uapi: media: Properly locate NV12MT diagram | expand

Commit Message

Nicolas Dufresne Sept. 14, 2023, 3:06 p.m. UTC 
This way we don't have to repeat over and over how the pixels are
packed in NV15.

Signed-off-by: Nicolas Dufresne <nicolas.dufresne@collabora.com>
---
 .../media/v4l/pixfmt-yuv-planar.rst           | 144 ++++++++++++++++--
 1 file changed, 131 insertions(+), 13 deletions(-)

Comments

Jonas Karlman Nov. 9, 2023, 4:06 p.m. UTC | #1 
On 2023-09-14 17:06, Nicolas Dufresne wrote:
> This way we don't have to repeat over and over how the pixels are
> packed in NV15.
> 
> Signed-off-by: Nicolas Dufresne <nicolas.dufresne@collabora.com>
> ---
>  .../media/v4l/pixfmt-yuv-planar.rst           | 144 ++++++++++++++++--
>  1 file changed, 131 insertions(+), 13 deletions(-)
> 
> diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
> index 1d43532095c07..2f0e0c97870b2 100644
> --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
> +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
> @@ -373,25 +373,143 @@ two non-contiguous planes.
>  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).
> +Semi-planar 10-bit YUV 4:2:0 formats. All components are packed
> +without any padding between each other. Each components group occupy 15

Each component (Y, Cb and Cr) is 10 bits in this format, the effective
bits per pixel is however 15 bits when number of pixels is aligned to 8.

For a 4x2 image:
8Y + 2Cb + 2Cr = 80 + 20 + 20 = 120 bits (15 bytes) => 15 bits per pixel

The 'Bits per component' in the table 'Overview of Semi-Planar YUV
Formats' is also showing 15, should be 10.

Regards,
Jonas

> +bits and are usually stored in group of 4 components stored over 5 bytes
> +(YYYY or UVUV = 4 * 10 bits = 40 bits = 5 bytes) or partitioned into
> +upper 8 bit and lower 2 bits. The final arrangement will vary depending if
> +the hardware operated in little or big endian.
> +

[...]
diff mbox series

Patch

diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
index 1d43532095c07..2f0e0c97870b2 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
@@ -373,25 +373,143 @@  two non-contiguous planes.
 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).
+Semi-planar 10-bit YUV 4:2:0 formats. All components are packed
+without any padding between each other. Each components group occupy 15
+bits and are usually stored in group of 4 components stored over 5 bytes
+(YYYY or UVUV = 4 * 10 bits = 40 bits = 5 bytes) or partitioned into
+upper 8 bit and lower 2 bits. The final arrangement will vary depending if
+the hardware operated in little or big endian.
+
+.. flat-table:: Little endian sample of 4 NV15 luma pixels
+    :header-rows:  1
+    :stub-columns: 1
+
+    * - Bit
+      - 7
+      - 6
+      - 5
+      - 4
+      - 3
+      - 2
+      - 1
+      - 0
+    * - Byte 0
+      - Y'\ :sub:`0:7`
+      - Y'\ :sub:`0:6`
+      - Y'\ :sub:`0:5`
+      - Y'\ :sub:`0:4`
+      - Y'\ :sub:`0:3`
+      - Y'\ :sub:`0:2`
+      - Y'\ :sub:`0:1`
+      - Y'\ :sub:`0:0`
+    * - Byte 1
+      - Y'\ :sub:`1:5`
+      - Y'\ :sub:`1:4`
+      - Y'\ :sub:`1:3`
+      - Y'\ :sub:`1:2`
+      - Y'\ :sub:`1:1`
+      - Y'\ :sub:`1:0`
+      - Y'\ :sub:`0:9`
+      - Y'\ :sub:`0:8`
+    * - Byte 2
+      - Y'\ :sub:`2:3`
+      - Y'\ :sub:`2:2`
+      - Y'\ :sub:`2:1`
+      - Y'\ :sub:`2:0`
+      - Y'\ :sub:`1:9`
+      - Y'\ :sub:`1:8`
+      - Y'\ :sub:`1:7`
+      - Y'\ :sub:`1:6`
+    * - Byte 3
+      - Y'\ :sub:`3:1`
+      - Y'\ :sub:`3:0`
+      - Y'\ :sub:`2:9`
+      - Y'\ :sub:`2:8`
+      - Y'\ :sub:`2:7`
+      - Y'\ :sub:`2:6`
+      - Y'\ :sub:`2:5`
+      - Y'\ :sub:`2:4`
+    * - Byte 4
+      - Y'\ :sub:`3:9`
+      - Y'\ :sub:`3:8`
+      - Y'\ :sub:`3:7`
+      - Y'\ :sub:`3:6`
+      - Y'\ :sub:`3:5`
+      - Y'\ :sub:`3:4`
+      - Y'\ :sub:`3:3`
+      - Y'\ :sub:`3:2`
+
+.. flat-table:: Big endian sample of 4 NV15 luma pixels
+    :header-rows:  1
+    :stub-columns: 1
+
+    * - Bit
+      - 7
+      - 6
+      - 5
+      - 4
+      - 3
+      - 2
+      - 1
+      - 0
+    * - Byte 0
+      - Y'\ :sub:`0:9`
+      - Y'\ :sub:`0:8`
+      - Y'\ :sub:`0:7`
+      - Y'\ :sub:`0:6`
+      - Y'\ :sub:`0:5`
+      - Y'\ :sub:`0:4`
+      - Y'\ :sub:`0:3`
+      - Y'\ :sub:`0:2`
+    * - Byte 1
+      - Y'\ :sub:`0:1`
+      - Y'\ :sub:`0:0`
+      - Y'\ :sub:`1:9`
+      - Y'\ :sub:`1:8`
+      - Y'\ :sub:`1:7`
+      - Y'\ :sub:`1:6`
+      - Y'\ :sub:`1:5`
+      - Y'\ :sub:`1:4`
+    * - Byte 2
+      - Y'\ :sub:`1:3`
+      - Y'\ :sub:`1:2`
+      - Y'\ :sub:`1:1`
+      - Y'\ :sub:`1:0`
+      - Y'\ :sub:`2:9`
+      - Y'\ :sub:`2:8`
+      - Y'\ :sub:`2:7`
+      - Y'\ :sub:`2:6`
+    * - Byte 3
+      - Y'\ :sub:`2:5`
+      - Y'\ :sub:`2:4`
+      - Y'\ :sub:`2:3`
+      - Y'\ :sub:`2:2`
+      - Y'\ :sub:`2:1`
+      - Y'\ :sub:`2:0`
+      - Y'\ :sub:`3:9`
+      - Y'\ :sub:`3:8`
+    * - Byte 4
+      - Y'\ :sub:`3:7`
+      - Y'\ :sub:`3:6`
+      - Y'\ :sub:`3:5`
+      - Y'\ :sub:`3:4`
+      - Y'\ :sub:`3:3`
+      - Y'\ :sub:`3:2`
+      - Y'\ :sub:`3:1`
+      - Y'\ :sub:`3:0`
+
+``V4L2_PIX_FMT_NV15_4L4`` stores pixels in 4x4 tiles, and stores tiles linearly
+in memory. The tiles contains little endian NV15 data.
 
 ``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)
+Note the tile size is 8 bytes multiplied by 128 bytes,
+it means that the low bits and high bits of one pixel may
+be in different tiles.
 
 ``V4L2_PIX_FMT_NV12_10BE_8L128`` is similar to ``V4L2_PIX_FMT_NV12M_10BE_8L128`` but stores
 two planes in one memory.