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