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