clarify semantics of the true colour formats

[Bart Veer <bartv at ecoscentric dot com>]

There was some confusion in the docs about the exact meaning of the
true colour formats, e.g. whether 565 represented the actual layout of
the colours in a word or just the number of bits for each colour. This
patch should eliminate the confusion.

Bart

2009-02-09  Bart Veer  <bartv@ecoscentric.com>

	* doc/framebuf.sgml: clarify the meaning of the true colour
	formats.

Index: doc/framebuf.sgml
===================================================================
RCS file: /cvs/ecos/ecos/packages/io/framebuf/current/doc/framebuf.sgml,v
retrieving revision 1.2
diff -u -p -r1.2 framebuf.sgml
--- doc/framebuf.sgml	29 Jan 2009 17:49:46 -0000	1.2
+++ doc/framebuf.sgml	9 Feb 2009 21:22:04 -0000
@@ -1390,36 +1390,40 @@ at the same time. The palette may be rea
       <varlistentry>
         <term><literal>CYG_FB_FORMAT_8BPP_TRUE_332</literal></term>
         <listitem><para>
-an 8bpp true colour display. Bits 0 and 1 of each pixel value control
-four levels of blue intensity, bits 2 to 4 control eight levels of
-green, and bits 5 to 7 control eight levels of red.
+an 8bpp true colour display, with three bits (eight levels) of red and
+green intensity and two bits (four levels) of blue intensity.
         </para></listitem>
       </varlistentry>
       <varlistentry>
         <term><literal>CYG_FB_FORMAT_16BPP_TRUE_565</literal></term>
         <listitem><para>
-a 16bpp true colour display. Bits 0 to 4 of each pixel value control
-the blue intensity, bits 5 to 10 the green intensity, and bits 11 to
-15 the red intensity.
+a 16bpp true colour display with 5 bits each for red and blue and 6
+bits for green.
         </para></listitem>
       </varlistentry>
       <varlistentry>
         <term><literal>CYG_FB_FORMAT_16BPP_TRUE_555</literal></term>
         <listitem><para>
-a 16bpp true colour display, with the top bit unused. Bits 0 to 4 of
-each pixel value control the blue intensity, bits 5 to 9 the green
-intensity, and bits 10 to 14 the red intensity.
+a 16bpp true colour display with five bits each for red, green and
+blue, and one unused bit.
         </para></listitem>
       </varlistentry>
       <varlistentry>
         <term><literal>CYG_FB_FORMAT_32BPP_TRUE_0888</literal></term>
         <listitem><para>
-a 32bpp true colour display, with the top byte unused. Bits 0 to 7 of
-each pixel value control the blue intensity, bits 8 to 15 the green
-intensity, and bits 16 to 23 the red intensity.
+a 32bpp true colour display with eight bits each for red, green and
+blue and eight bits unused.
         </para></listitem>
       </varlistentry>
     </variablelist>
+    <para>
+For the true colour formats the format does not define exactly which
+bits in the pixel are used for which colour. Instead the
+<function>cyg_fb_make_colour</function>
+and <function>cyg_fb_break_colour</function> functions or the
+equivalent macros should be used to construct or decompose pixel
+values.
+    </para>
   </refsect1>
 
   <refsect1 id="framebuf-colour-palette">
@@ -1514,10 +1518,9 @@ offers the same colour intensities but r
 and four times the bandwidth.
     </para>
     <para>
-There are two ways of determining a <type>cyg_fb_colour</type> pixel
-value for a given colour. The first is to decode the colour format,
-for example <literal>CYG_FB_FORMAT_16BPP_TRUE_565</literal>, and
-perform the appropriate arithmetic. The second is to use the supplied
+Exactly how the colour bits are organized in
+a <type>cyg_fb_colour</type> pixel value is not
+defined by the colour format. Instead code should use the
 <function>cyg_fb_make_colour</function> or
 <function>CYG_FB_MAKE_COLOUR</function> primitives. These take 8-bit
 intensity levels for red, green and blue, and return the corresponding
@@ -2640,6 +2643,13 @@ default definitions of the true colour p
     CYG_MACRO_END
         </programlisting>
         <para>
+These default definitions assume the most common layout of colours
+within a pixel value, so for
+example <function>CYG_FB_MAKE_COLOUR_16BPP_TRUE_565</function> assumes
+bits 0 to 4 hold the blue intensity, bits 5 to 10 the green, and bits
+11 to 15 the red.
+        </para>
+        <para>
 If the hardware does not implement a linear framebuffer then obviously
 writing the device driver will be significantly more work. The macros
 will have to perform the operations themselves instead of relying on
@@ -2796,7 +2806,8 @@ device driver does not implement non-cor
 As with the macros there are default implementations of the true
 colour primitives for <literal>8bpp_true_332</literal>,
 <literal>16bpp_true_565</literal>, <literal>16bpp_true_555</literal>
-and <literal>32bpp_true_0888</literal>. There are also default
+and <literal>32bpp_true_0888</literal>, assuming the most common
+layout for these colour modes. There are also default
 implementations of the drawing primitives for linear framebuffers,
 with variants for the common display depths and layouts. Obviously
 non-linear framebuffers will need rather more work.