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 "gdkvisualprivate.h"
  27 #include "gdkscreenprivate.h"
  28
  29
  30 /**
  31  * SECTION:visuals
  32  * @Short_description: Low-level display hardware information
  33  * @Title: Visuals
  34  *
  35  * A #GdkVisual describes a particular video hardware display format.
  36  * It includes information about the number of bits used for each color,
  37  * the way the bits are translated into an RGB value for display, and
  38  * the way the bits are stored in memory. For example, a piece of display
  39  * hardware might support 24-bit color, 16-bit color, or 8-bit color;
  40  * meaning 24/16/8-bit pixel sizes. For a given pixel size, pixels can
  41  * be in different formats; for example the "red" element of an RGB pixel
  42  * may be in the top 8 bits of the pixel, or may be in the lower 4 bits.
  43  *
  44  * There are several standard visuals. The visual returned by
  45  * gdk_screen_get_system_visual() is the system's default visual.
  46  *
  47  * A number of functions are provided for determining the "best" available
  48  * visual. For the purposes of making this determination, higher bit depths
  49  * are considered better, and for visuals of the same bit depth,
  50  * %GDK_VISUAL_PSEUDO_COLOR is preferred at 8bpp, otherwise, the visual
  51  * types are ranked in the order of(highest to lowest)
  52  * %GDK_VISUAL_DIRECT_COLOR, %GDK_VISUAL_TRUE_COLOR,
  53  * %GDK_VISUAL_PSEUDO_COLOR, %GDK_VISUAL_STATIC_COLOR,
  54  * %GDK_VISUAL_GRAYSCALE, then %GDK_VISUAL_STATIC_GRAY.
  55  */
  56
  57 G_DEFINE_TYPE (GdkVisual, gdk_visual, G_TYPE_OBJECT)
  58
  59 static void
  60 gdk_visual_init (GdkVisual *visual)
  61 {
  62 }
  63
  64 static void
  65 gdk_visual_finalize (GObject *object)
  66 {
  67   G_OBJECT_CLASS (gdk_visual_parent_class)->finalize (object);
  68 }
  69
  70 static void
  71 gdk_visual_class_init (GdkVisualClass *visual_class)
  72 {
  73   GObjectClass *object_class = G_OBJECT_CLASS (visual_class);
  74
  75   object_class->finalize = gdk_visual_finalize;
  76 }
  77
  78 /**
  79  * gdk_list_visuals:
  80  *
  81  * Lists the available visuals for the default screen.
  82  * (See gdk_screen_list_visuals())
  83  * A visual describes a hardware image data format.
  84  * For example, a visual might support 24-bit color, or 8-bit color,
  85  * and might expect pixels to be in a certain format.
  86  *
  87  * Call g_list_free() on the return value when you're finished with it.
  88  *
  89  * Return value: (transfer container) (element-type GdkVisual):
  90  *     a list of visuals; the list must be freed, but not its contents
  91  */
  92 GList*
  93 gdk_list_visuals (void)
  94 {
  95   return gdk_screen_list_visuals (gdk_screen_get_default ());
  96 }
  97
  98 /**
  99  * gdk_visual_get_system:
 100  *
 101  * Get the system's default visual for the default GDK screen.
 102  * This is the visual for the root window of the display.
 103  * The return value should not be freed.
 104  *
 105  * Return value: (transfer none): system visual
 106  */
 107 GdkVisual*
 108 gdk_visual_get_system (void)
 109 {
 110   return gdk_screen_get_system_visual (gdk_screen_get_default());
 111 }
 112
 113 /**
 114  * gdk_visual_get_best_depth:
 115  *
 116  * Get the best available depth for the default GDK screen.  "Best"
 117  * means "largest," i.e. 32 preferred over 24 preferred over 8 bits
 118  * per pixel.
 119  *
 120  * Return value: best available depth
 121  */
 122 gint
 123 gdk_visual_get_best_depth (void)
 124 {
 125   GdkScreen *screen = gdk_screen_get_default();
 126
 127   return GDK_SCREEN_GET_CLASS(screen)->visual_get_best_depth (screen);
 128 }
 129
 130 /**
 131  * gdk_visual_get_best_type:
 132  *
 133  * Return the best available visual type for the default GDK screen.
 134  *
 135  * Return value: best visual type
 136  */
 137 GdkVisualType
 138 gdk_visual_get_best_type (void)
 139 {
 140   GdkScreen *screen = gdk_screen_get_default();
 141
 142   return GDK_SCREEN_GET_CLASS(screen)->visual_get_best_type (screen);
 143 }
 144
 145 /**
 146  * gdk_visual_get_best:
 147  *
 148  * Get the visual with the most available colors for the default
 149  * GDK screen. The return value should not be freed.
 150  *
 151  * Return value: (transfer none): best visual
 152  */
 153 GdkVisual*
 154 gdk_visual_get_best (void)
 155 {
 156   GdkScreen *screen = gdk_screen_get_default();
 157
 158   return GDK_SCREEN_GET_CLASS(screen)->visual_get_best (screen);
 159 }
 160
 161 /**
 162  * gdk_visual_get_best_with_depth:
 163  * @depth: a bit depth
 164  *
 165  * Get the best visual with depth @depth for the default GDK screen.
 166  * Color visuals and visuals with mutable colormaps are preferred
 167  * over grayscale or fixed-colormap visuals. The return value should
 168  * not be freed. %NULL may be returned if no visual supports @depth.
 169  *
 170  * Return value: (transfer none): best visual for the given depth
 171  */
 172 GdkVisual*
 173 gdk_visual_get_best_with_depth (gint depth)
 174 {
 175   GdkScreen *screen = gdk_screen_get_default();
 176
 177   return GDK_SCREEN_GET_CLASS(screen)->visual_get_best_with_depth (screen, depth);
 178 }
 179
 180 /**
 181  * gdk_visual_get_best_with_type:
 182  * @visual_type: a visual type
 183  *
 184  * Get the best visual of the given @visual_type for the default GDK screen.
 185  * Visuals with higher color depths are considered better. The return value
 186  * should not be freed. %NULL may be returned if no visual has type
 187  * @visual_type.
 188  *
 189  * Return value: (transfer none): best visual of the given type
 190  */
 191 GdkVisual*
 192 gdk_visual_get_best_with_type (GdkVisualType visual_type)
 193 {
 194   GdkScreen *screen = gdk_screen_get_default();
 195
 196   return GDK_SCREEN_GET_CLASS(screen)->visual_get_best_with_type (screen,
 197                                                                   visual_type);
 198 }
 199
 200 /**
 201  * gdk_visual_get_best_with_both:
 202  * @depth: a bit depth
 203  * @visual_type: a visual type
 204  *
 205  * Combines gdk_visual_get_best_with_depth() and
 206  * gdk_visual_get_best_with_type().
 207  *
 208  * Return value: (transfer none): best visual with both @depth and
 209  *     @visual_type, or %NULL if none
 210  */
 211 GdkVisual*
 212 gdk_visual_get_best_with_both (gint          depth,
 213                                GdkVisualType visual_type)
 214 {
 215   GdkScreen *screen = gdk_screen_get_default();
 216
 217   return GDK_SCREEN_GET_CLASS(screen)->visual_get_best_with_both (screen, depth, visual_type);
 218 }
 219
 220 /**
 221  * gdk_query_depths:
 222  * @depths: (out) (array): return location for available depths
 223  * @count: (out): return location for number of available depths
 224  *
 225  * This function returns the available bit depths for the default
 226  * screen. It's equivalent to listing the visuals
 227  * (gdk_list_visuals()) and then looking at the depth field in each
 228  * visual, removing duplicates.
 229  *
 230  * The array returned by this function should not be freed.
 231  */
 232 void
 233 gdk_query_depths (gint **depths,
 234                   gint  *count)
 235 {
 236   GdkScreen *screen = gdk_screen_get_default();
 237
 238   GDK_SCREEN_GET_CLASS(screen)->query_depths (screen, depths, count);
 239 }
 240
 241 /**
 242  * gdk_query_visual_types:
 243  * @visual_types: return location for the available visual types
 244  * @count: return location for the number of available visual types
 245  *
 246  * This function returns the available visual types for the default
 247  * screen. It's equivalent to listing the visuals
 248  * (gdk_list_visuals()) and then looking at the type field in each
 249  * visual, removing duplicates.
 250  *
 251  * The array returned by this function should not be freed.
 252  */
 253 void
 254 gdk_query_visual_types (GdkVisualType **visual_types,
 255                         gint           *count)
 256 {
 257   GdkScreen *screen = gdk_screen_get_default();
 258
 259   GDK_SCREEN_GET_CLASS(screen)->query_visual_types (screen, visual_types, count);
 260 }
 261
 262 /**
 263  * gdk_visual_get_visual_type:
 264  * @visual: A #GdkVisual.
 265  *
 266  * Returns the type of visual this is (PseudoColor, TrueColor, etc).
 267  *
 268  * Return value: A #GdkVisualType stating the type of @visual.
 269  *
 270  * Since: 2.22
 271  */
 272 GdkVisualType
 273 gdk_visual_get_visual_type (GdkVisual *visual)
 274 {
 275   g_return_val_if_fail (GDK_IS_VISUAL (visual), 0);
 276
 277   return visual->type;
 278 }
 279
 280 /**
 281  * gdk_visual_get_depth:
 282  * @visual: A #GdkVisual.
 283  *
 284  * Returns the bit depth of this visual.
 285  *
 286  * Return value: The bit depth of this visual.
 287  *
 288  * Since: 2.22
 289  */
 290 gint
 291 gdk_visual_get_depth (GdkVisual *visual)
 292 {
 293   g_return_val_if_fail (GDK_IS_VISUAL (visual), 0);
 294
 295   return visual->depth;
 296 }
 297
 298 /**
 299  * gdk_visual_get_byte_order:
 300  * @visual: A #GdkVisual.
 301  *
 302  * Returns the byte order of this visual.
 303  *
 304  * Return value: A #GdkByteOrder stating the byte order of @visual.
 305  *
 306  * Since: 2.22
 307  */
 308 GdkByteOrder
 309 gdk_visual_get_byte_order (GdkVisual *visual)
 310 {
 311   g_return_val_if_fail (GDK_IS_VISUAL (visual), 0);
 312
 313   return visual->byte_order;
 314 }
 315
 316 /**
 317  * gdk_visual_get_colormap_size:
 318  * @visual: A #GdkVisual.
 319  *
 320  * Returns the size of a colormap for this visual.
 321  *
 322  * Return value: The size of a colormap that is suitable for @visual.
 323  *
 324  * Since: 2.22
 325  */
 326 gint
 327 gdk_visual_get_colormap_size (GdkVisual *visual)
 328 {
 329   g_return_val_if_fail (GDK_IS_VISUAL (visual), 0);
 330
 331   return visual->colormap_size;
 332 }
 333
 334 /**
 335  * gdk_visual_get_bits_per_rgb:
 336  * @visual: a #GdkVisual
 337  *
 338  * Returns the number of significant bits per red, green and blue value.
 339  *
 340  * Return value: The number of significant bits per color value for @visual.
 341  *
 342  * Since: 2.22
 343  */
 344 gint
 345 gdk_visual_get_bits_per_rgb (GdkVisual *visual)
 346 {
 347   g_return_val_if_fail (GDK_IS_VISUAL (visual), 0);
 348
 349   return visual->bits_per_rgb;
 350 }
 351
 352 /**
 353  * gdk_visual_get_red_pixel_details:
 354  * @visual: A #GdkVisual
 355  * @mask: (out) (allow-none): A pointer to a #guint32 to be filled in, or %NULL
 356  * @shift: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
 357  * @precision: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
 358  *
 359  * Obtains values that are needed to calculate red pixel values in TrueColor
 360  * and DirectColor. The "mask" is the significant bits within the pixel.
 361  * The "shift" is the number of bits left we must shift a primary for it
 362  * to be in position (according to the "mask"). Finally, "precision" refers
 363  * to how much precision the pixel value contains for a particular primary.
 364  *
 365  * Since: 2.22
 366  */
 367 void
 368 gdk_visual_get_red_pixel_details (GdkVisual *visual,
 369                                   guint32   *mask,
 370                                   gint      *shift,
 371                                   gint      *precision)
 372 {
 373   g_return_if_fail (GDK_IS_VISUAL (visual));
 374
 375   if (mask)
 376     *mask = visual->red_mask;
 377
 378   if (shift)
 379     *shift = visual->red_shift;
 380
 381   if (precision)
 382     *precision = visual->red_prec;
 383 }
 384
 385 /**
 386  * gdk_visual_get_green_pixel_details:
 387  * @visual: a #GdkVisual
 388  * @mask: (out) (allow-none): A pointer to a #guint32 to be filled in, or %NULL
 389  * @shift: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
 390  * @precision: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
 391  *
 392  * Obtains values that are needed to calculate green pixel values in TrueColor
 393  * and DirectColor. The "mask" is the significant bits within the pixel.
 394  * The "shift" is the number of bits left we must shift a primary for it
 395  * to be in position (according to the "mask"). Finally, "precision" refers
 396  * to how much precision the pixel value contains for a particular primary.
 397  *
 398  * Since: 2.22
 399  */
 400 void
 401 gdk_visual_get_green_pixel_details (GdkVisual *visual,
 402                                     guint32   *mask,
 403                                     gint      *shift,
 404                                     gint      *precision)
 405 {
 406   g_return_if_fail (GDK_IS_VISUAL (visual));
 407
 408   if (mask)
 409     *mask = visual->green_mask;
 410
 411   if (shift)
 412     *shift = visual->green_shift;
 413
 414   if (precision)
 415     *precision = visual->green_prec;
 416 }
 417
 418 /**
 419  * gdk_visual_get_blue_pixel_details:
 420  * @visual: a #GdkVisual
 421  * @mask: (out) (allow-none): A pointer to a #guint32 to be filled in, or %NULL
 422  * @shift: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
 423  * @precision: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
 424  *
 425  * Obtains values that are needed to calculate blue pixel values in TrueColor
 426  * and DirectColor. The "mask" is the significant bits within the pixel.
 427  * The "shift" is the number of bits left we must shift a primary for it
 428  * to be in position (according to the "mask"). Finally, "precision" refers
 429  * to how much precision the pixel value contains for a particular primary.
 430  *
 431  * Since: 2.22
 432  */
 433 void
 434 gdk_visual_get_blue_pixel_details (GdkVisual *visual,
 435                                    guint32   *mask,
 436                                    gint      *shift,
 437                                    gint      *precision)
 438 {
 439   g_return_if_fail (GDK_IS_VISUAL (visual));
 440
 441   if (mask)
 442     *mask = visual->blue_mask;
 443
 444   if (shift)
 445     *shift = visual->blue_shift;
 446
 447   if (precision)
 448     *precision = visual->blue_prec;
 449 }
 450
 451 /**
 452  * gdk_visual_get_screen:
 453  * @visual: a #GdkVisual
 454  *
 455  * Gets the screen to which this visual belongs
 456  *
 457  * Return value: (transfer none): the screen to which this visual belongs.
 458  *
 459  * Since: 2.2
 460  */
 461 GdkScreen *
 462 gdk_visual_get_screen (GdkVisual *visual)
 463 {
 464   g_return_val_if_fail (GDK_IS_VISUAL (visual), NULL);
 465
 466   return visual->screen;
 467 }