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 length=count) (transfer none): return
 223  *     location for available depths
 224  * @count: return location for number of available depths
 225  *
 226  * This function returns the available bit depths for the default
 227  * screen. It's equivalent to listing the visuals
 228  * (gdk_list_visuals()) and then looking at the depth field in each
 229  * visual, removing duplicates.
 230  *
 231  * The array returned by this function should not be freed.
 232  */
 233 void
 234 gdk_query_depths (gint **depths,
 235                   gint  *count)
 236 {
 237   GdkScreen *screen = gdk_screen_get_default();
 238
 239   GDK_SCREEN_GET_CLASS(screen)->query_depths (screen, depths, count);
 240 }
 241
 242 /**
 243  * gdk_query_visual_types:
 244  * @visual_types: (out) (array length=count) (transfer none): return
 245  *     location for the available visual types
 246  * @count: return location for the number of available visual types
 247  *
 248  * This function returns the available visual types for the default
 249  * screen. It's equivalent to listing the visuals
 250  * (gdk_list_visuals()) and then looking at the type field in each
 251  * visual, removing duplicates.
 252  *
 253  * The array returned by this function should not be freed.
 254  */
 255 void
 256 gdk_query_visual_types (GdkVisualType **visual_types,
 257                         gint           *count)
 258 {
 259   GdkScreen *screen = gdk_screen_get_default();
 260
 261   GDK_SCREEN_GET_CLASS(screen)->query_visual_types (screen, visual_types, count);
 262 }
 263
 264 /**
 265  * gdk_visual_get_visual_type:
 266  * @visual: A #GdkVisual.
 267  *
 268  * Returns the type of visual this is (PseudoColor, TrueColor, etc).
 269  *
 270  * Return value: A #GdkVisualType stating the type of @visual.
 271  *
 272  * Since: 2.22
 273  */
 274 GdkVisualType
 275 gdk_visual_get_visual_type (GdkVisual *visual)
 276 {
 277   g_return_val_if_fail (GDK_IS_VISUAL (visual), 0);
 278
 279   return visual->type;
 280 }
 281
 282 /**
 283  * gdk_visual_get_depth:
 284  * @visual: A #GdkVisual.
 285  *
 286  * Returns the bit depth of this visual.
 287  *
 288  * Return value: The bit depth of this visual.
 289  *
 290  * Since: 2.22
 291  */
 292 gint
 293 gdk_visual_get_depth (GdkVisual *visual)
 294 {
 295   g_return_val_if_fail (GDK_IS_VISUAL (visual), 0);
 296
 297   return visual->depth;
 298 }
 299
 300 /**
 301  * gdk_visual_get_byte_order:
 302  * @visual: A #GdkVisual.
 303  *
 304  * Returns the byte order of this visual.
 305  *
 306  * Return value: A #GdkByteOrder stating the byte order of @visual.
 307  *
 308  * Since: 2.22
 309  */
 310 GdkByteOrder
 311 gdk_visual_get_byte_order (GdkVisual *visual)
 312 {
 313   g_return_val_if_fail (GDK_IS_VISUAL (visual), 0);
 314
 315   return visual->byte_order;
 316 }
 317
 318 /**
 319  * gdk_visual_get_colormap_size:
 320  * @visual: A #GdkVisual.
 321  *
 322  * Returns the size of a colormap for this visual.
 323  *
 324  * Return value: The size of a colormap that is suitable for @visual.
 325  *
 326  * Since: 2.22
 327  */
 328 gint
 329 gdk_visual_get_colormap_size (GdkVisual *visual)
 330 {
 331   g_return_val_if_fail (GDK_IS_VISUAL (visual), 0);
 332
 333   return visual->colormap_size;
 334 }
 335
 336 /**
 337  * gdk_visual_get_bits_per_rgb:
 338  * @visual: a #GdkVisual
 339  *
 340  * Returns the number of significant bits per red, green and blue value.
 341  *
 342  * Return value: The number of significant bits per color value for @visual.
 343  *
 344  * Since: 2.22
 345  */
 346 gint
 347 gdk_visual_get_bits_per_rgb (GdkVisual *visual)
 348 {
 349   g_return_val_if_fail (GDK_IS_VISUAL (visual), 0);
 350
 351   return visual->bits_per_rgb;
 352 }
 353
 354 /**
 355  * gdk_visual_get_red_pixel_details:
 356  * @visual: A #GdkVisual
 357  * @mask: (out) (allow-none): A pointer to a #guint32 to be filled in, or %NULL
 358  * @shift: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
 359  * @precision: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
 360  *
 361  * Obtains values that are needed to calculate red pixel values in TrueColor
 362  * and DirectColor. The "mask" is the significant bits within the pixel.
 363  * The "shift" is the number of bits left we must shift a primary for it
 364  * to be in position (according to the "mask"). Finally, "precision" refers
 365  * to how much precision the pixel value contains for a particular primary.
 366  *
 367  * Since: 2.22
 368  */
 369 void
 370 gdk_visual_get_red_pixel_details (GdkVisual *visual,
 371                                   guint32   *mask,
 372                                   gint      *shift,
 373                                   gint      *precision)
 374 {
 375   g_return_if_fail (GDK_IS_VISUAL (visual));
 376
 377   if (mask)
 378     *mask = visual->red_mask;
 379
 380   if (shift)
 381     *shift = visual->red_shift;
 382
 383   if (precision)
 384     *precision = visual->red_prec;
 385 }
 386
 387 /**
 388  * gdk_visual_get_green_pixel_details:
 389  * @visual: a #GdkVisual
 390  * @mask: (out) (allow-none): A pointer to a #guint32 to be filled in, or %NULL
 391  * @shift: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
 392  * @precision: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
 393  *
 394  * Obtains values that are needed to calculate green pixel values in TrueColor
 395  * and DirectColor. The "mask" is the significant bits within the pixel.
 396  * The "shift" is the number of bits left we must shift a primary for it
 397  * to be in position (according to the "mask"). Finally, "precision" refers
 398  * to how much precision the pixel value contains for a particular primary.
 399  *
 400  * Since: 2.22
 401  */
 402 void
 403 gdk_visual_get_green_pixel_details (GdkVisual *visual,
 404                                     guint32   *mask,
 405                                     gint      *shift,
 406                                     gint      *precision)
 407 {
 408   g_return_if_fail (GDK_IS_VISUAL (visual));
 409
 410   if (mask)
 411     *mask = visual->green_mask;
 412
 413   if (shift)
 414     *shift = visual->green_shift;
 415
 416   if (precision)
 417     *precision = visual->green_prec;
 418 }
 419
 420 /**
 421  * gdk_visual_get_blue_pixel_details:
 422  * @visual: a #GdkVisual
 423  * @mask: (out) (allow-none): A pointer to a #guint32 to be filled in, or %NULL
 424  * @shift: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
 425  * @precision: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
 426  *
 427  * Obtains values that are needed to calculate blue pixel values in TrueColor
 428  * and DirectColor. The "mask" is the significant bits within the pixel.
 429  * The "shift" is the number of bits left we must shift a primary for it
 430  * to be in position (according to the "mask"). Finally, "precision" refers
 431  * to how much precision the pixel value contains for a particular primary.
 432  *
 433  * Since: 2.22
 434  */
 435 void
 436 gdk_visual_get_blue_pixel_details (GdkVisual *visual,
 437                                    guint32   *mask,
 438                                    gint      *shift,
 439                                    gint      *precision)
 440 {
 441   g_return_if_fail (GDK_IS_VISUAL (visual));
 442
 443   if (mask)
 444     *mask = visual->blue_mask;
 445
 446   if (shift)
 447     *shift = visual->blue_shift;
 448
 449   if (precision)
 450     *precision = visual->blue_prec;
 451 }
 452
 453 /**
 454  * gdk_visual_get_screen:
 455  * @visual: a #GdkVisual
 456  *
 457  * Gets the screen to which this visual belongs
 458  *
 459  * Return value: (transfer none): the screen to which this visual belongs.
 460  *
 461  * Since: 2.2
 462  */
 463 GdkScreen *
 464 gdk_visual_get_screen (GdkVisual *visual)
 465 {
 466   g_return_val_if_fail (GDK_IS_VISUAL (visual), NULL);
 467
 468   return visual->screen;
 469 }