Re: [PATCH/RFC v2 1/3] fbdev: Add FOURCC-based format configuration API

Hi Laurent,

My comments are mainly about the documentation of the "legacy" bits.

On Fri, Aug 19, 2011 at 11:37, Laurent Pinchart
[off-list ref] wrote:

+2. Types and visuals
+--------------------
+
+Pixels are stored in memory in hardware-dependent formats. Applications need
+to be aware of the pixel storage format in order to write image data to the
+frame buffer memory in the format expected by the hardware.
+
+Formats are described by frame buffer types and visuals. Some visuals require
+additional information, which are stored in the variable screen information
+bits_per_pixel, grayscale, fourcc, red, green, blue and transp fields.
+
+The following types and visuals are supported.
+
+- FB_TYPE_PACKED_PIXELS
+
+Color components (usually RGB or YUV) are packed together into macropixels
+that are stored in a single plane. The exact color components layout is
+described in a visual-dependent way.
+
+Frame buffer visuals that don't use multiple color components per pixel
+(such as monochrome and pseudo-color visuals) are reported as packed frame
+buffer types, even though they don't stricly speaking pack color components
+into macropixels.

That's because the "packing" is not about the color components, but about the
bits that represent a single pixel.

I.e. the bits that make up the pixel (the macropixel) are stored next
to each other
in memory.

+- FB_TYPE_PLANES
+
+Color components are stored in separate planes. Planes are located
+contiguously in memory.

The bits that make up a pixel are stored in separate planes. Planes are located
contiguously in memory.

- FB_TYPE_INTERLEAVED_PLANES

The bits that make up a pixel are stored in separate planes. Planes
are interleaved.
The interleave factor (the distance in bytes between the planes in
memory) is stored
in the type_aux field.

+- FB_VISUAL_MONO01
+
+Pixels are black or white and stored on one bit. A bit set to 1 represents a
+black pixel and a bit set to 0 a white pixel. Pixels are packed together in
+bytes with 8 pixels per byte.

Actually we do have drivers that use 8 bits per pixel for a monochrome visual.
Hence:

"Pixels are black or white. A black pixel is represented by all
(typically one) bits
set to ones, a white pixel by all bits set to zeroes."

+FB_VISUAL_MONO01 is used with FB_TYPE_PACKED_PIXELS only.

... so this may also not be true (but it is for all current drivers, IIRC).
There's a strict orthogonality between type (how is a pixel stored in memory)
and visual (how the bits that represent the pixel are interpreted and converted
to a color value).

Same comments for FB_VISUAL_MONO10

+- FB_VISUAL_TRUECOLOR
+
+Pixels are broken into red, green and blue components, and each component
+indexes a read-only lookup table for the corresponding value. Lookup tables
+are device-dependent, and provide linear or non-linear ramps.
+
+Each component is stored in memory according to the variable screen
+information red, green, blue and transp fields.

"Each component is stored in a macropixel according to the variable screen
information red, green, blue and transp fields."

Storage format in memory is determined by the FB_TYPE_* value.

+- FB_VISUAL_PSEUDOCOLOR and FB_VISUAL_STATIC_PSEUDOCOLOR
+
+Pixel values are encoded as indices into a colormap that stores red, green and
+blue components. The colormap is read-only for FB_VISUAL_STATIC_PSEUDOCOLOR
+and read-write for FB_VISUAL_PSEUDOCOLOR.
+
+Each pixel value is stored in the number of bits reported by the variable
+screen information bits_per_pixel field. Pixels are contiguous in memory.

Whether pixels are contiguous in memory or not is determined by the
FB_TYPE_* value.

+FB_VISUAL_PSEUDOCOLOR and FB_VISUAL_STATIC_PSEUDOCOLOR are used with
+FB_TYPE_PACKED_PIXELS only.

Not true. Several drivers use bit planes or interleaved bitplanes.

+- FB_VISUAL_DIRECTCOLOR
+
+Pixels are broken into red, green and blue components, and each component
+indexes a programmable lookup table for the corresponding value.
+
+Each component is stored in memory according to the variable screen
+information red, green, blue and transp fields.

"Each component is stored in a macropixel according to the variable screen
information red, green, blue and transp fields."

+- FB_VISUAL_FOURCC
+
+Pixels are stored in memory as described by the format FOURCC identifier
+stored in the variable screen information fourcc field.

... stored in memory and interpreted ...

+struct fb_var_screeninfo {
+       __u32 xres;                     /* visible resolution           */
+       __u32 yres;
+       __u32 xres_virtual;             /* virtual resolution           */
+       __u32 yres_virtual;
+       __u32 xoffset;                  /* offset from virtual to visible */
+       __u32 yoffset;                  /* resolution                   */
+
+       __u32 bits_per_pixel;           /* guess what                   */
+       union {
+               struct {                /* Legacy format API            */
+                       __u32 grayscale; /* != 0 Graylevels instead of colors */
+                       /* bitfields in fb mem if true color, else only */
+                       /* length is significant                        */
+                       struct fb_bitfield red;
+                       struct fb_bitfield green;
+                       struct fb_bitfield blue;
+                       struct fb_bitfield transp;      /* transparency */
+               };
+               struct {                /* FOURCC-based format API      */
+                       __u32 fourcc;           /* FOURCC format        */
+                       __u32 colorspace;
+                       __u32 reserved[11];
+               } format;
+       };
+
+       struct fb_bitfield red;         /* bitfield in fb mem if true color, */
+       struct fb_bitfield green;       /* else only length is significant */
+       struct fb_bitfield blue;
+       struct fb_bitfield transp;      /* transparency                 */

These four are duplicated, cfr. the union above.

+  Pixel values are bits_per_pixel wide and are split in non-overlapping red,
+  green, blue and alpha (transparency) components. Location and size of each
+  component in the pixel value are described by the fb_bitfield offset and
+  length fields. Offset are computed from the right.

                   Offsets

Gr{oetje,eeting}s,

                        Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds