diff --git a/docs/reference/gdk/tmpl/.gitignore b/docs/reference/gdk/tmpl/.gitignore index 58d06212f0..4341431194 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/docs/reference/gdk/tmpl/visuals.sgml b/docs/reference/gdk/tmpl/visuals.sgml deleted file mode 100644 index 96d3bea3b4..0000000000 --- a/docs/reference/gdk/tmpl/visuals.sgml +++ /dev/null @@ -1,283 +0,0 @@ - -Visuals - - - -Low-level display hardware information - - - -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. - - - - - - - - - - - - - - - -The GdkVisual structure contains information about -a particular visual. - - - -Constructing a pixel value from components - -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); -} - - - -@parent_instance: inherited portion from #GObject - - - -A set of values that describe the manner in which the -pixel values for a visual are converted into RGB -values for display. - - -@GDK_VISUAL_STATIC_GRAY: Each pixel value indexes a grayscale value directly. -@GDK_VISUAL_GRAYSCALE: Each pixel is an index into a color map that maps pixel - values into grayscale values. The color map can be changed by an application. -@GDK_VISUAL_STATIC_COLOR: Each pixel value is an index into a predefined, - unmodifiable color map that maps pixel values into RGB values. -@GDK_VISUAL_PSEUDO_COLOR: Each pixel is an index into a color map that maps - pixel values into rgb values. The color map can be changed by an application. -@GDK_VISUAL_TRUE_COLOR: Each pixel value directly contains red, green, - and blue components. The red_mask, - green_mask, and - blue_mask fields of the #GdkVisual - structure describe how the components are assembled into a pixel value. -@GDK_VISUAL_DIRECT_COLOR: Each pixel value contains red, green, and blue - components as for %GDK_VISUAL_TRUE_COLOR, but the components are mapped via a - color table into the final output table instead of being converted directly. - - - -A set of values describing the possible byte-orders -for storing pixel values in memory. - - -@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. - - - - - - -@depths: -@count: - - - - - - - -@visual_types: -@count: - - - - - - - -@void: -@Returns: - - - - - - - -@visual: -@Returns: - - - - - - - -@visual: -@mask: -@shift: -@precision: - - - - - - - -@visual: -@Returns: - - - - - - - -@visual: -@Returns: - - - - - - - -@visual: -@Returns: - - - - - - - -@visual: -@mask: -@shift: -@precision: - - - - - - - -@visual: -@mask: -@shift: -@precision: - - - - - - - -@visual: -@Returns: - - - - - - - -@void: -@Returns: - - - - - - - -@void: -@Returns: - - - - - - - -@void: -@Returns: - - - - - - - -@void: -@Returns: - - - - - - - -@depth: -@Returns: - - - - - - - -@visual_type: -@Returns: - - - - - - - -@depth: -@visual_type: -@Returns: - - - - - - - -@visual: -@Returns: - - diff --git a/gdk/gdktypes.h b/gdk/gdktypes.h index 44efa3fa9c..4a18bd1bb5 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 ea4c07f268..cba4a7b3d3 100644 --- a/gdk/gdkvisual.c +++ b/gdk/gdkvisual.c @@ -28,6 +28,33 @@ #include "gdkscreen.h" +/** + * 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: * diff --git a/gdk/gdkvisual.h b/gdk/gdkvisual.h index 714a0e666c..5fa4ad919c 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. + * + * + * Constructing a pixel value from components + * + * 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); + * } + * + * */ 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);