Pileus Git - ~andy/gtk/blob - gdk/gdkvisual.c

   1 /* GDK - The GIMP Drawing Kit
   2  * gdkvisual.c
   3  *
   4  * Copyright 2001 Sun Microsystems Inc.
   5  *
   6  * Erwann Chenede <erwann.chenede@sun.com>
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Library General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Library General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Library General Public
  19  * License along with this library; if not, write to the
  20  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  21  * Boston, MA 02111-1307, USA.
  22  */
  23
  24 #include "config.h"
  25
  26 #include "gdkvisual.h"
  27
  28 #include "gdkscreen.h"
  29
  30
  31 /**
  32  * SECTION:visuals
  33  * @Short_description: Low-level display hardware information
  34  * @Title: Visuals
  35  *
  36  * A #GdkVisual describes a particular video hardware display format. It includes
  37  * information about the number of bits used for each color, the way the bits are
  38  * translated into an RGB value for display, and the way the bits are stored in
  39  * memory. For example, a piece of display hardware might support 24-bit color,
  40  * 16-bit color, or 8-bit color; meaning 24/16/8-bit pixel sizes. For a given
  41  * pixel size, pixels can be in different formats; for example the "red" element
  42  * of an RGB pixel may be in the top 8 bits of the pixel, or may be in the lower
  43  * 4 bits.
  44  *
  45  * There are several standard visuals. The visual returned by
  46  * gdk_screen_get_system_visual() is the system's default visual.
  47  *
  48  * A number of functions are provided for determining the "best" available visual.
  49  * For the purposes of making this determination, higher bit depths are considered
  50  * better, and for visuals of the same bit depth, %GDK_VISUAL_PSEUDO_COLOR is
  51  * preferred at 8bpp, otherwise, the visual types are ranked in the order of
  52  * (highest to lowest) %GDK_VISUAL_DIRECT_COLOR, %GDK_VISUAL_TRUE_COLOR,
  53  * %GDK_VISUAL_PSEUDO_COLOR, %GDK_VISUAL_STATIC_COLOR, %GDK_VISUAL_GRAYSCALE,
  54  * then %GDK_VISUAL_STATIC_GRAY.
  55  */
  56
  57
  58 /**
  59  * gdk_list_visuals:
  60  *
  61  * Lists the available visuals for the default screen.
  62  * (See gdk_screen_list_visuals())
  63  * A visual describes a hardware image data format.
  64  * For example, a visual might support 24-bit color, or 8-bit color,
  65  * and might expect pixels to be in a certain format.
  66  *
  67  * Call g_list_free() on the return value when you're finished with it.
  68  *
  69  * Return value: (transfer container) (element-type GdkVisual):
  70  *     a list of visuals; the list must be freed, but not its contents
  71  **/
  72 GList*
  73 gdk_list_visuals (void)
  74 {
  75   return gdk_screen_list_visuals (gdk_screen_get_default ());
  76 }
  77
  78 /**
  79  * gdk_visual_get_system:
  80  *
  81  * Get the system's default visual for the default GDK screen.
  82  * This is the visual for the root window of the display.
  83  * The return value should not be freed.
  84  *
  85  * Return value: (transfer none): system visual
  86  **/
  87 GdkVisual*
  88 gdk_visual_get_system (void)
  89 {
  90   return gdk_screen_get_system_visual (gdk_screen_get_default());
  91 }
  92
  93 /**
  94  * gdk_visual_get_visual_type:
  95  * @visual: A #GdkVisual.
  96  *
  97  * Returns the type of visual this is (PseudoColor, TrueColor, etc).
  98  *
  99  * Return value: A #GdkVisualType stating the type of @visual.
 100  *
 101  * Since: 2.22
 102  */
 103 GdkVisualType
 104 gdk_visual_get_visual_type (GdkVisual *visual)
 105 {
 106   g_return_val_if_fail (GDK_IS_VISUAL (visual), 0);
 107
 108   return visual->type;
 109 }
 110
 111 /**
 112  * gdk_visual_get_depth:
 113  * @visual: A #GdkVisual.
 114  *
 115  * Returns the bit depth of this visual.
 116  *
 117  * Return value: The bit depth of this visual.
 118  *
 119  * Since: 2.22
 120  */
 121 gint
 122 gdk_visual_get_depth (GdkVisual *visual)
 123 {
 124   g_return_val_if_fail (GDK_IS_VISUAL (visual), 0);
 125
 126   return visual->depth;
 127 }
 128
 129 /**
 130  * gdk_visual_get_byte_order:
 131  * @visual: A #GdkVisual.
 132  *
 133  * Returns the byte order of this visual.
 134  *
 135  * Return value: A #GdkByteOrder stating the byte order of @visual.
 136  *
 137  * Since: 2.22
 138  */
 139 GdkByteOrder
 140 gdk_visual_get_byte_order (GdkVisual *visual)
 141 {
 142   g_return_val_if_fail (GDK_IS_VISUAL (visual), 0);
 143
 144   return visual->byte_order;
 145 }
 146
 147 /**
 148  * gdk_visual_get_colormap_size:
 149  * @visual: A #GdkVisual.
 150  *
 151  * Returns the size of a colormap for this visual.
 152  *
 153  * Return value: The size of a colormap that is suitable for @visual.
 154  *
 155  * Since: 2.22
 156  */
 157 gint
 158 gdk_visual_get_colormap_size (GdkVisual *visual)
 159 {
 160   g_return_val_if_fail (GDK_IS_VISUAL (visual), 0);
 161
 162   return visual->colormap_size;
 163 }
 164
 165 /**
 166  * gdk_visual_get_bits_per_rgb:
 167  * @visual: a #GdkVisual
 168  *
 169  * Returns the number of significant bits per red, green and blue value.
 170  *
 171  * Return value: The number of significant bits per color value for @visual.
 172  *
 173  * Since: 2.22
 174  */
 175 gint
 176 gdk_visual_get_bits_per_rgb (GdkVisual *visual)
 177 {
 178   g_return_val_if_fail (GDK_IS_VISUAL (visual), 0);
 179
 180   return visual->bits_per_rgb;
 181 }
 182
 183 /**
 184  * gdk_visual_get_red_pixel_details:
 185  * @visual: A #GdkVisual.
 186  * @mask: (out) (allow-none): A pointer to a #guint32 to be filled in, or %NULL.
 187  * @shift: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL.
 188  * @precision: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL.
 189  *
 190  * Obtains values that are needed to calculate red pixel values in TrueColor
 191  * and DirectColor.  The "mask" is the significant bits within the pixel.
 192  * The "shift" is the number of bits left we must shift a primary for it
 193  * to be in position (according to the "mask").  Finally, "precision" refers
 194  * to how much precision the pixel value contains for a particular primary.
 195  *
 196  * Since: 2.22
 197  */
 198 void
 199 gdk_visual_get_red_pixel_details (GdkVisual *visual,
 200                                   guint32   *mask,
 201                                   gint      *shift,
 202                                   gint      *precision)
 203 {
 204   g_return_if_fail (GDK_IS_VISUAL (visual));
 205
 206   if (mask)
 207     *mask = visual->red_mask;
 208
 209   if (shift)
 210     *shift = visual->red_shift;
 211
 212   if (precision)
 213     *precision = visual->red_prec;
 214 }
 215
 216 /**
 217  * gdk_visual_get_green_pixel_details:
 218  * @visual: a #GdkVisual
 219  * @mask: (out) (allow-none): A pointer to a #guint32 to be filled in, or %NULL.
 220  * @shift: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL.
 221  * @precision: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL.
 222  *
 223  * Obtains values that are needed to calculate green pixel values in TrueColor
 224  * and DirectColor.  The "mask" is the significant bits within the pixel.
 225  * The "shift" is the number of bits left we must shift a primary for it
 226  * to be in position (according to the "mask").  Finally, "precision" refers
 227  * to how much precision the pixel value contains for a particular primary.
 228  *
 229  * Since: 2.22
 230  */
 231 void
 232 gdk_visual_get_green_pixel_details (GdkVisual *visual,
 233                                     guint32   *mask,
 234                                     gint      *shift,
 235                                     gint      *precision)
 236 {
 237   g_return_if_fail (GDK_IS_VISUAL (visual));
 238
 239   if (mask)
 240     *mask = visual->green_mask;
 241
 242   if (shift)
 243     *shift = visual->green_shift;
 244
 245   if (precision)
 246     *precision = visual->green_prec;
 247 }
 248
 249 /**
 250  * gdk_visual_get_blue_pixel_details:
 251  * @visual: a #GdkVisual
 252  * @mask: (out) (allow-none): A pointer to a #guint32 to be filled in, or %NULL.
 253  * @shift: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL.
 254  * @precision: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL.
 255  *
 256  * Obtains values that are needed to calculate blue pixel values in TrueColor
 257  * and DirectColor.  The "mask" is the significant bits within the pixel.
 258  * The "shift" is the number of bits left we must shift a primary for it
 259  * to be in position (according to the "mask").  Finally, "precision" refers
 260  * to how much precision the pixel value contains for a particular primary.
 261  *
 262  * Since: 2.22
 263  */
 264 void
 265 gdk_visual_get_blue_pixel_details (GdkVisual *visual,
 266                                    guint32   *mask,
 267                                    gint      *shift,
 268                                    gint      *precision)
 269 {
 270   g_return_if_fail (GDK_IS_VISUAL (visual));
 271
 272   if (mask)
 273     *mask = visual->blue_mask;
 274
 275   if (shift)
 276     *shift = visual->blue_shift;
 277
 278   if (precision)
 279     *precision = visual->blue_prec;
 280 }