[gtk+/treeview-refactor: 243/257] docs: Move documentation to inline comments: gdkvisual

[Tristan Van Berkom <tvb src gnome org>]

commit 4593df1ef5a440577f0add13e86e623b3854eb6e
Author: Javier Jardón <jjardon gnome org>
Date:   Mon Nov 15 17:05:05 2010 +0100

    docs: Move documentation to inline comments: gdkvisual

 docs/reference/gdk/tmpl/.gitignore   |    1 +
 docs/reference/gdk/tmpl/visuals.sgml |  283 ----------------------------------
 gdk/gdktypes.h                       |   12 ++
 gdk/gdkvisual.c                      |   27 ++++
 gdk/gdkvisual.h                      |   47 ++++--
 5 files changed, 71 insertions(+), 299 deletions(-)
---
diff --git a/docs/reference/gdk/tmpl/.gitignore b/docs/reference/gdk/tmpl/.gitignore
index 58d0621..4341431 100644
--- a/docs/reference/gdk/tmpl/.gitignore
+++ b/docs/reference/gdk/tmpl/.gitignore
@@ -12,4 +12,5 @@ keys.sgml
 pango_interaction.sgml
 pixbufs.sgml
 regions.sgml
+visuals.sgml
 windows.sgml
diff --git a/gdk/gdktypes.h b/gdk/gdktypes.h
index 44efa3f..4a18bd1 100644
--- a/gdk/gdktypes.h
+++ b/gdk/gdktypes.h
@@ -111,6 +111,18 @@ typedef struct _GdkDrawable           GdkWindow;
 typedef struct _GdkDisplay	      GdkDisplay;
 typedef struct _GdkScreen	      GdkScreen;
 
+/**
+ * GdkByteOrder:
+ * @GDK_LSB_FIRST: The values are stored with the least-significant byte
+ *   first. For instance, the 32-bit value 0xffeecc would be stored
+ *   in memory as 0xcc, 0xee, 0xff, 0x00.
+ * @GDK_MSB_FIRST: The values are stored with the most-significant byte
+ *   first. For instance, the 32-bit value 0xffeecc would be stored
+ *   in memory as 0x00, 0xcc, 0xee, 0xff.
+ *
+ * A set of values describing the possible byte-orders
+ * for storing pixel values in memory.
+ */
 typedef enum
 {
   GDK_LSB_FIRST,
diff --git a/gdk/gdkvisual.c b/gdk/gdkvisual.c
index ea4c07f..cba4a7b 100644
--- a/gdk/gdkvisual.c
+++ b/gdk/gdkvisual.c
@@ -29,6 +29,33 @@
 
 
 /**
+ * SECTION:visuals
+ * @Short_description: Low-level display hardware information
+ * @Title: Visuals
+ *
+ * A #GdkVisual describes a particular video hardware display format. It includes
+ * information about the number of bits used for each color, the way the bits are
+ * translated into an RGB value for display, and the way the bits are stored in
+ * memory. For example, a piece of display hardware might support 24-bit color,
+ * 16-bit color, or 8-bit color; meaning 24/16/8-bit pixel sizes. For a given
+ * pixel size, pixels can be in different formats; for example the "red" element
+ * of an RGB pixel may be in the top 8 bits of the pixel, or may be in the lower
+ * 4 bits.
+ *
+ * There are several standard visuals. The visual returned by
+ * gdk_screen_get_system_visual() is the system's default visual.
+ *
+ * A number of functions are provided for determining the "best" available visual.
+ * For the purposes of making this determination, higher bit depths are considered
+ * better, and for visuals of the same bit depth, %GDK_VISUAL_PSEUDO_COLOR is
+ * preferred at 8bpp, otherwise, the visual types are ranked in the order of
+ * (highest to lowest) %GDK_VISUAL_DIRECT_COLOR, %GDK_VISUAL_TRUE_COLOR,
+ * %GDK_VISUAL_PSEUDO_COLOR, %GDK_VISUAL_STATIC_COLOR, %GDK_VISUAL_GRAYSCALE,
+ * then %GDK_VISUAL_STATIC_GRAY.
+ */
+
+
+/**
  * gdk_list_visuals:
  * 
  * Lists the available visuals for the default screen.
diff --git a/gdk/gdkvisual.h b/gdk/gdkvisual.h
index 714a0e6..5fa4ad9 100644
--- a/gdk/gdkvisual.h
+++ b/gdk/gdkvisual.h
@@ -79,29 +79,44 @@ typedef enum
   GDK_VISUAL_DIRECT_COLOR
 } GdkVisualType;
 
-/* The visual type.
- *   "type" is the type of visual this is (PseudoColor, TrueColor, etc).
- *   "depth" is the bit depth of this visual.
- *   "colormap_size" is the size of a colormap for this visual.
- *   "bits_per_rgb" is the number of significant bits per red, green and blue.
- *  The red, green and blue masks, shifts and precisions refer
- *   to value needed to calculate pixel values in TrueColor and DirectColor
- *   visuals. The "mask" is the significant bits within the pixel. The
- *   "shift" is the number of bits left we must shift a primary for it
- *   to be in position (according to the "mask"). "prec" refers to how
- *   much precision the pixel value contains for a particular primary.
+/**
+ * GdkVisual:
+ *
+ * The #GdkVisual structure contains information about
+ * a particular visual.
+ *
+ * <example id="rgbmask">
+ * <title>Constructing a pixel value from components</title>
+ * <programlisting>
+ * guint
+ * pixel_from_rgb (GdkVisual *visual,
+ *                 guchar r, guchar b, guchar g)
+ * {
+ *   return ((r >> (16 - visual->red_prec))   << visual->red_shift) |
+ *          ((g >> (16 - visual->green_prec)) << visual->green_shift) |
+ *          ((r >> (16 - visual->blue_prec))  << visual->blue_shift);
+ * }
+ * </programlisting>
+ * </example>
  */
 struct _GdkVisual
 {
+  /*< private >*/
   GObject parent_instance;
 
-  /*< private >*/
-  GdkVisualType GSEAL (type);
-  gint GSEAL (depth);
+  GdkVisualType GSEAL (type);      /* Type of visual this is (PseudoColor, TrueColor, etc) */
+  gint GSEAL (depth);              /* Bit depth of this visual */
   GdkByteOrder GSEAL (byte_order);
-  gint GSEAL (colormap_size);
-  gint GSEAL (bits_per_rgb);
-
+  gint GSEAL (colormap_size);      /* Size of a colormap for this visual */
+  gint GSEAL (bits_per_rgb);       /* Number of significant bits per red, green and blue. */
+
+  /* The red, green and blue masks, shifts and precisions refer
+   * to value needed to calculate pixel values in TrueColor and DirectColor
+   * visuals. The "mask" is the significant bits within the pixel. The
+   * "shift" is the number of bits left we must shift a primary for it
+   * to be in position (according to the "mask"). "prec" refers to how
+   * much precision the pixel value contains for a particular primary.
+   */
   guint32 GSEAL (red_mask);
   gint GSEAL (red_shift);
   gint GSEAL (red_prec);