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, see <http://www.gnu.org/licenses/>.
  20  */
  21
  22 #include "config.h"
  23
  24 #include "gdkvisualprivate.h"
  25 #include "gdkscreenprivate.h"
  26
  27
  28 /**
  29  * SECTION:visuals
  30  * @Short_description: Low-level display hardware information
  31  * @Title: Visuals
  32  *
  33  * A #GdkVisual describes a particular video hardware display format.
  34  * It includes information about the number of bits used for each color,
  35  * the way the bits are translated into an RGB value for display, and
  36  * the way the bits are stored in memory. For example, a piece of display
  37  * hardware might support 24-bit color, 16-bit color, or 8-bit color;
  38  * meaning 24/16/8-bit pixel sizes. For a given pixel size, pixels can
  39  * be in different formats; for example the "red" element of an RGB pixel
  40  * may be in the top 8 bits of the pixel, or may be in the lower 4 bits.
  41  *
  42  * There are several standard visuals. The visual returned by
  43  * gdk_screen_get_system_visual() is the system's default visual.
  44  *
  45  * A number of functions are provided for determining the "best" available
  46  * visual. For the purposes of making this determination, higher bit depths
  47  * are considered better, and for visuals of the same bit depth,
  48  * %GDK_VISUAL_PSEUDO_COLOR is preferred at 8bpp, otherwise, the visual
  49  * types are ranked in the order of(highest to lowest)
  50  * %GDK_VISUAL_DIRECT_COLOR, %GDK_VISUAL_TRUE_COLOR,
  51  * %GDK_VISUAL_PSEUDO_COLOR, %GDK_VISUAL_STATIC_COLOR,
  52  * %GDK_VISUAL_GRAYSCALE, then %GDK_VISUAL_STATIC_GRAY.
  53  */
  54
  55 G_DEFINE_TYPE (GdkVisual, gdk_visual, G_TYPE_OBJECT)
  56
  57 static void
  58 gdk_visual_init (GdkVisual *visual)
  59 {
  60 }
  61
  62 static void
  63 gdk_visual_finalize (GObject *object)
  64 {
  65   G_OBJECT_CLASS (gdk_visual_parent_class)->finalize (object);
  66 }
  67
  68 static void
  69 gdk_visual_class_init (GdkVisualClass *visual_class)
  70 {
  71   GObjectClass *object_class = G_OBJECT_CLASS (visual_class);
  72
  73   object_class->finalize = gdk_visual_finalize;
  74 }
  75
  76 /**
  77  * gdk_list_visuals:
  78  *
  79  * Lists the available visuals for the default screen.
  80  * (See gdk_screen_list_visuals())
  81  * A visual describes a hardware image data format.
  82  * For example, a visual might support 24-bit color, or 8-bit color,
  83  * and might expect pixels to be in a certain format.
  84  *
  85  * Call g_list_free() on the return value when you're finished with it.
  86  *
  87  * Return value: (transfer container) (element-type GdkVisual):
  88  *     a list of visuals; the list must be freed, but not its contents
  89  */
  90 GList*
  91 gdk_list_visuals (void)
  92 {
  93   return gdk_screen_list_visuals (gdk_screen_get_default ());
  94 }
  95
  96 /**
  97  * gdk_visual_get_system:
  98  *
  99  * Get the system's default visual for the default GDK screen.
 100  * This is the visual for the root window of the display.
 101  * The return value should not be freed.
 102  *
 103  * Return value: (transfer none): system visual
 104  */
 105 GdkVisual*
 106 gdk_visual_get_system (void)
 107 {
 108   return gdk_screen_get_system_visual (gdk_screen_get_default());
 109 }
 110
 111 /**
 112  * gdk_visual_get_best_depth:
 113  *
 114  * Get the best available depth for the default GDK screen.  "Best"
 115  * means "largest," i.e. 32 preferred over 24 preferred over 8 bits
 116  * per pixel.
 117  *
 118  * Return value: best available depth
 119  */
 120 gint
 121 gdk_visual_get_best_depth (void)
 122 {
 123   GdkScreen *screen = gdk_screen_get_default();
 124
 125   return GDK_SCREEN_GET_CLASS(screen)->visual_get_best_depth (screen);
 126 }
 127
 128 /**
 129  * gdk_visual_get_best_type:
 130  *
 131  * Return the best available visual type for the default GDK screen.
 132  *
 133  * Return value: best visual type
 134  */
 135 GdkVisualType
 136 gdk_visual_get_best_type (void)
 137 {
 138   GdkScreen *screen = gdk_screen_get_default();
 139
 140   return GDK_SCREEN_GET_CLASS(screen)->visual_get_best_type (screen);
 141 }
 142
 143 /**
 144  * gdk_visual_get_best:
 145  *
 146  * Get the visual with the most available colors for the default
 147  * GDK screen. The return value should not be freed.
 148  *
 149  * Return value: (transfer none): best visual
 150  */
 151 GdkVisual*
 152 gdk_visual_get_best (void)
 153 {
 154   GdkScreen *screen = gdk_screen_get_default();
 155
 156   return GDK_SCREEN_GET_CLASS(screen)->visual_get_best (screen);
 157 }
 158
 159 /**
 160  * gdk_visual_get_best_with_depth:
 161  * @depth: a bit depth
 162  *
 163  * Get the best visual with depth @depth for the default GDK screen.
 164  * Color visuals and visuals with mutable colormaps are preferred
 165  * over grayscale or fixed-colormap visuals. The return value should
 166  * not be freed. %NULL may be returned if no visual supports @depth.
 167  *
 168  * Return value: (transfer none): best visual for the given depth
 169  */
 170 GdkVisual*
 171 gdk_visual_get_best_with_depth (gint depth)
 172 {
 173   GdkScreen *screen = gdk_screen_get_default();
 174
 175   return GDK_SCREEN_GET_CLASS(screen)->visual_get_best_with_depth (screen, depth);
 176 }
 177
 178 /**
 179  * gdk_visual_get_best_with_type:
 180  * @visual_type: a visual type
 181  *
 182  * Get the best visual of the given @visual_type for the default GDK screen.
 183  * Visuals with higher color depths are considered better. The return value
 184  * should not be freed. %NULL may be returned if no visual has type
 185  * @visual_type.
 186  *
 187  * Return value: (transfer none): best visual of the given type
 188  */
 189 GdkVisual*
 190 gdk_visual_get_best_with_type (GdkVisualType visual_type)
 191 {
 192   GdkScreen *screen = gdk_screen_get_default();
 193
 194   return GDK_SCREEN_GET_CLASS(screen)->visual_get_best_with_type (screen,
 195                                                                   visual_type);
 196 }
 197
 198 /**
 199  * gdk_visual_get_best_with_both:
 200  * @depth: a bit depth
 201  * @visual_type: a visual type
 202  *
 203  * Combines gdk_visual_get_best_with_depth() and
 204  * 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 length=count) (transfer none): return
 221  *     location for available depths
 222  * @count: return location for number of available depths
 223  *
 224  * This function returns the available bit depths for the default
 225  * screen. It's equivalent to listing the visuals
 226  * (gdk_list_visuals()) and then looking at the depth field in each
 227  * visual, removing duplicates.
 228  *
 229  * The array returned by this function should not be freed.
 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: (out) (array length=count) (transfer none): return
 243  *     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 }