gdkvisual.c 15.4 KB
Newer Older
Cody Russell's avatar
Cody Russell committed
1
/* GDK - The GIMP Drawing Kit
2
 * gdkvisual.c
Matthias Clasen's avatar
Matthias Clasen committed
3
4
 *
 * Copyright 2001 Sun Microsystems Inc.
5
6
7
8
9
10
11
12
13
14
15
16
17
18
 *
 * Erwann Chenede <erwann.chenede@sun.com>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
Javier Jardón's avatar
Javier Jardón committed
19
 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
20
21
 */

22
#include "config.h"
23

24
25
#include "gdkvisualprivate.h"
#include "gdkscreenprivate.h"
26

27

28
29
30
31
32
/**
 * SECTION:visuals
 * @Short_description: Low-level display hardware information
 * @Title: Visuals
 *
Matthias Clasen's avatar
Matthias Clasen committed
33
34
35
36
37
38
 * A #GdkVisual describes a particular video hardware display format.
 * It includes information about the number of bits used for each color,
 * the way the bits are translated into an RGB value for display, and
 * the way the bits are stored in memory. For example, a piece of display
 * hardware might support 24-bit color, 16-bit color, or 8-bit color;
 * meaning 24/16/8-bit pixel sizes. For a given pixel size, pixels can
William Jon McCann's avatar
William Jon McCann committed
39
 * be in different formats; for example the “red” element of an RGB pixel
Matthias Clasen's avatar
Matthias Clasen committed
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
Matthias Clasen's avatar
Matthias Clasen committed
43
44
45
 * gdk_screen_get_system_visual() is the system’s default visual, and
 * the visual returned by gdk_screen_get_rgba_visual() should be used for
 * creating windows with an alpha channel.
46
 *
William Jon McCann's avatar
William Jon McCann committed
47
 * A number of functions are provided for determining the “best” available
Matthias Clasen's avatar
Matthias Clasen committed
48
49
50
51
52
53
54
 * visual. For the purposes of making this determination, higher bit depths
 * are considered better, and for visuals of the same bit depth,
 * %GDK_VISUAL_PSEUDO_COLOR is preferred at 8bpp, otherwise, the visual
 * types are ranked in the order of(highest to lowest)
 * %GDK_VISUAL_DIRECT_COLOR, %GDK_VISUAL_TRUE_COLOR,
 * %GDK_VISUAL_PSEUDO_COLOR, %GDK_VISUAL_STATIC_COLOR,
 * %GDK_VISUAL_GRAYSCALE, then %GDK_VISUAL_STATIC_GRAY.
55
56
 */

57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
G_DEFINE_TYPE (GdkVisual, gdk_visual, G_TYPE_OBJECT)

static void
gdk_visual_init (GdkVisual *visual)
{
}

static void
gdk_visual_finalize (GObject *object)
{
  G_OBJECT_CLASS (gdk_visual_parent_class)->finalize (object);
}

static void
gdk_visual_class_init (GdkVisualClass *visual_class)
{
  GObjectClass *object_class = G_OBJECT_CLASS (visual_class);

  object_class->finalize = gdk_visual_finalize;
}
77

78
79
/**
 * gdk_list_visuals:
Matthias Clasen's avatar
Matthias Clasen committed
80
 *
81
82
83
84
85
86
 * Lists the available visuals for the default screen.
 * (See gdk_screen_list_visuals())
 * A visual describes a hardware image data format.
 * For example, a visual might support 24-bit color, or 8-bit color,
 * and might expect pixels to be in a certain format.
 *
87
 * Call g_list_free() on the return value when you’re finished with it.
Matthias Clasen's avatar
Matthias Clasen committed
88
 *
89
 * Returns: (transfer container) (element-type GdkVisual):
Matthias Clasen's avatar
Matthias Clasen committed
90
 *     a list of visuals; the list must be freed, but not its contents
91
92
 * 
 * Deprecated: 3.22: Use gdk_screen_list_visuals (gdk_screen_get_default ()).
Matthias Clasen's avatar
Matthias Clasen committed
93
 */
94
95
96
GList*
gdk_list_visuals (void)
{
Owen Taylor's avatar
Owen Taylor committed
97
  return gdk_screen_list_visuals (gdk_screen_get_default ());
98
99
100
101
}

/**
 * gdk_visual_get_system:
Matthias Clasen's avatar
Matthias Clasen committed
102
 *
103
 * Get the system’s default visual for the default GDK screen.
104
105
 * This is the visual for the root window of the display.
 * The return value should not be freed.
Matthias Clasen's avatar
Matthias Clasen committed
106
 *
107
 * Returns: (transfer none): system visual
108
109
 *
 * Deprecated: 3.22: Use gdk_screen_get_system_visual (gdk_screen_get_default ()).
Matthias Clasen's avatar
Matthias Clasen committed
110
 */
111
112
113
GdkVisual*
gdk_visual_get_system (void)
{
Owen Taylor's avatar
Owen Taylor committed
114
  return gdk_screen_get_system_visual (gdk_screen_get_default());
115
}
116

117
118
119
/**
 * gdk_visual_get_best_depth:
 *
William Jon McCann's avatar
William Jon McCann committed
120
121
 * Get the best available depth for the default GDK screen.  “Best”
 * means “largest,” i.e. 32 preferred over 24 preferred over 8 bits
122
123
 * per pixel.
 *
124
 * Returns: best available depth
125
126
127
 *
 * Deprecated: 3.22: Visual selection should be done using
 *     gdk_screen_get_system_visual() and gdk_screen_get_rgba_visual()
Matthias Clasen's avatar
Matthias Clasen committed
128
 */
129
130
131
132
133
134
135
136
137
138
139
140
141
gint
gdk_visual_get_best_depth (void)
{
  GdkScreen *screen = gdk_screen_get_default();

  return GDK_SCREEN_GET_CLASS(screen)->visual_get_best_depth (screen);
}

/**
 * gdk_visual_get_best_type:
 *
 * Return the best available visual type for the default GDK screen.
 *
142
 * Returns: best visual type
143
144
145
 *
 * Deprecated: 3.22: Visual selection should be done using
 *     gdk_screen_get_system_visual() and gdk_screen_get_rgba_visual()
Matthias Clasen's avatar
Matthias Clasen committed
146
 */
147
148
149
150
151
152
153
154
155
156
157
158
159
160
GdkVisualType
gdk_visual_get_best_type (void)
{
  GdkScreen *screen = gdk_screen_get_default();

  return GDK_SCREEN_GET_CLASS(screen)->visual_get_best_type (screen);
}

/**
 * gdk_visual_get_best:
 *
 * Get the visual with the most available colors for the default
 * GDK screen. The return value should not be freed.
 *
161
 * Returns: (transfer none): best visual
162
163
164
 *
 * Deprecated: 3.22: Visual selection should be done using
 *     gdk_screen_get_system_visual() and gdk_screen_get_rgba_visual()
Matthias Clasen's avatar
Matthias Clasen committed
165
 */
166
167
168
169
170
171
172
173
174
175
176
177
178
179
GdkVisual*
gdk_visual_get_best (void)
{
  GdkScreen *screen = gdk_screen_get_default();

  return GDK_SCREEN_GET_CLASS(screen)->visual_get_best (screen);
}

/**
 * gdk_visual_get_best_with_depth:
 * @depth: a bit depth
 *
 * Get the best visual with depth @depth for the default GDK screen.
 * Color visuals and visuals with mutable colormaps are preferred
Matthias Clasen's avatar
Matthias Clasen committed
180
181
 * over grayscale or fixed-colormap visuals. The return value should
 * not be freed. %NULL may be returned if no visual supports @depth.
182
 *
183
 * Returns: (transfer none): best visual for the given depth
184
185
186
 *
 * Deprecated: 3.22: Visual selection should be done using
 *     gdk_screen_get_system_visual() and gdk_screen_get_rgba_visual()
Matthias Clasen's avatar
Matthias Clasen committed
187
 */
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
GdkVisual*
gdk_visual_get_best_with_depth (gint depth)
{
  GdkScreen *screen = gdk_screen_get_default();

  return GDK_SCREEN_GET_CLASS(screen)->visual_get_best_with_depth (screen, depth);
}

/**
 * gdk_visual_get_best_with_type:
 * @visual_type: a visual type
 *
 * Get the best visual of the given @visual_type for the default GDK screen.
 * Visuals with higher color depths are considered better. The return value
 * should not be freed. %NULL may be returned if no visual has type
 * @visual_type.
 *
205
 * Returns: (transfer none): best visual of the given type
206
207
208
 *
 * Deprecated: 3.22: Visual selection should be done using
 *     gdk_screen_get_system_visual() and gdk_screen_get_rgba_visual()
Matthias Clasen's avatar
Matthias Clasen committed
209
 */
210
211
212
213
214
215
GdkVisual*
gdk_visual_get_best_with_type (GdkVisualType visual_type)
{
  GdkScreen *screen = gdk_screen_get_default();

  return GDK_SCREEN_GET_CLASS(screen)->visual_get_best_with_type (screen,
Matthias Clasen's avatar
Matthias Clasen committed
216
                                                                  visual_type);
217
218
219
220
221
222
223
}

/**
 * gdk_visual_get_best_with_both:
 * @depth: a bit depth
 * @visual_type: a visual type
 *
Matthias Clasen's avatar
Matthias Clasen committed
224
225
 * Combines gdk_visual_get_best_with_depth() and
 * gdk_visual_get_best_with_type().
226
 *
227
228
 * Returns: (nullable) (transfer none): best visual with both @depth
 *     and @visual_type, or %NULL if none
229
230
231
 *
 * Deprecated: 3.22: Visual selection should be done using
 *     gdk_screen_get_system_visual() and gdk_screen_get_rgba_visual()
Matthias Clasen's avatar
Matthias Clasen committed
232
 */
233
234
235
236
237
238
239
240
241
242
243
GdkVisual*
gdk_visual_get_best_with_both (gint          depth,
			       GdkVisualType visual_type)
{
  GdkScreen *screen = gdk_screen_get_default();

  return GDK_SCREEN_GET_CLASS(screen)->visual_get_best_with_both (screen, depth, visual_type);
}

/**
 * gdk_query_depths:
244
245
246
 * @depths: (out) (array length=count) (transfer none): return
 *     location for available depths
 * @count: return location for number of available depths
247
248
 *
 * This function returns the available bit depths for the default
249
 * screen. It’s equivalent to listing the visuals
250
251
252
253
 * (gdk_list_visuals()) and then looking at the depth field in each
 * visual, removing duplicates.
 *
 * The array returned by this function should not be freed.
254
255
256
 *
 * Deprecated: 3.22: Visual selection should be done using
 *     gdk_screen_get_system_visual() and gdk_screen_get_rgba_visual()
Matthias Clasen's avatar
Matthias Clasen committed
257
 */
258
void
Matthias Clasen's avatar
Matthias Clasen committed
259
260
gdk_query_depths (gint **depths,
                  gint  *count)
261
262
263
264
265
266
267
268
{
  GdkScreen *screen = gdk_screen_get_default();

  GDK_SCREEN_GET_CLASS(screen)->query_depths (screen, depths, count);
}

/**
 * gdk_query_visual_types:
269
270
 * @visual_types: (out) (array length=count) (transfer none): return
 *     location for the available visual types
271
272
273
 * @count: return location for the number of available visual types
 *
 * This function returns the available visual types for the default
274
 * screen. It’s equivalent to listing the visuals
275
276
277
278
 * (gdk_list_visuals()) and then looking at the type field in each
 * visual, removing duplicates.
 *
 * The array returned by this function should not be freed.
279
280
281
 *
 * Deprecated: 3.22: Visual selection should be done using
 *     gdk_screen_get_system_visual() and gdk_screen_get_rgba_visual()
Matthias Clasen's avatar
Matthias Clasen committed
282
 */
283
284
void
gdk_query_visual_types (GdkVisualType **visual_types,
Matthias Clasen's avatar
Matthias Clasen committed
285
                        gint           *count)
286
287
288
289
290
291
{
  GdkScreen *screen = gdk_screen_get_default();

  GDK_SCREEN_GET_CLASS(screen)->query_visual_types (screen, visual_types, count);
}

Matthias Clasen's avatar
Matthias Clasen committed
292
293
294
295
296
297
/**
 * gdk_visual_get_visual_type:
 * @visual: A #GdkVisual.
 *
 * Returns the type of visual this is (PseudoColor, TrueColor, etc).
 *
298
 * Returns: A #GdkVisualType stating the type of @visual.
Matthias Clasen's avatar
Matthias Clasen committed
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
 *
 * Since: 2.22
 */
GdkVisualType
gdk_visual_get_visual_type (GdkVisual *visual)
{
  g_return_val_if_fail (GDK_IS_VISUAL (visual), 0);

  return visual->type;
}

/**
 * gdk_visual_get_depth:
 * @visual: A #GdkVisual.
 *
 * Returns the bit depth of this visual.
 *
316
 * Returns: The bit depth of this visual.
Matthias Clasen's avatar
Matthias Clasen committed
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
 *
 * Since: 2.22
 */
gint
gdk_visual_get_depth (GdkVisual *visual)
{
  g_return_val_if_fail (GDK_IS_VISUAL (visual), 0);

  return visual->depth;
}

/**
 * gdk_visual_get_byte_order:
 * @visual: A #GdkVisual.
 *
 * Returns the byte order of this visual.
333
 *
334
335
336
 * The information returned by this function is only relevant
 * when working with XImages, and not all backends return
 * meaningful information for this.
Matthias Clasen's avatar
Matthias Clasen committed
337
 *
338
 * Returns: A #GdkByteOrder stating the byte order of @visual.
Matthias Clasen's avatar
Matthias Clasen committed
339
340
 *
 * Since: 2.22
341
342
 *
 * Deprecated: 3.22: This information is not useful
Matthias Clasen's avatar
Matthias Clasen committed
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
 */
GdkByteOrder
gdk_visual_get_byte_order (GdkVisual *visual)
{
  g_return_val_if_fail (GDK_IS_VISUAL (visual), 0);

  return visual->byte_order;
}

/**
 * gdk_visual_get_colormap_size:
 * @visual: A #GdkVisual.
 *
 * Returns the size of a colormap for this visual.
 *
358
359
 * You have to use platform-specific APIs to manipulate colormaps.
 *
360
 * Returns: The size of a colormap that is suitable for @visual.
Matthias Clasen's avatar
Matthias Clasen committed
361
362
 *
 * Since: 2.22
363
364
365
 *
 * Deprecated: 3.22: This information is not useful, since GDK does not
 *     provide APIs to operate on colormaps.
Matthias Clasen's avatar
Matthias Clasen committed
366
367
368
369
370
371
372
373
374
375
376
377
378
379
 */
gint
gdk_visual_get_colormap_size (GdkVisual *visual)
{
  g_return_val_if_fail (GDK_IS_VISUAL (visual), 0);

  return visual->colormap_size;
}

/**
 * gdk_visual_get_bits_per_rgb:
 * @visual: a #GdkVisual
 *
 * Returns the number of significant bits per red, green and blue value.
380
 *
381
 * Not all GDK backend provide a meaningful value for this function.
Matthias Clasen's avatar
Matthias Clasen committed
382
 *
383
 * Returns: The number of significant bits per color value for @visual.
Matthias Clasen's avatar
Matthias Clasen committed
384
385
 *
 * Since: 2.22
386
 *
387
388
 * Deprecated: 3.22. Use gdk_visual_get_red_pixel_details() and its variants to
 *     learn about the pixel layout of TrueColor and DirectColor visuals
Matthias Clasen's avatar
Matthias Clasen committed
389
390
391
392
393
394
395
396
397
 */
gint
gdk_visual_get_bits_per_rgb (GdkVisual *visual)
{
  g_return_val_if_fail (GDK_IS_VISUAL (visual), 0);

  return visual->bits_per_rgb;
}

398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
static void
gdk_visual_get_pixel_details (GdkVisual *visual,
                              gulong     pixel_mask,
                              guint32   *mask,
                              gint      *shift,
                              gint      *precision)
{
  gulong m = 0;
  gint s = 0;
  gint p = 0;

  if (pixel_mask != 0)
    {
      m = pixel_mask;
      while (!(m & 0x1))
        {
          s++;
          m >>= 1;
        }

      while (m & 0x1)
        {
          p++;
          m >>= 1;
        }
    }

  if (mask)
    *mask = pixel_mask;

  if (shift)
    *shift = s;

  if (precision)
    *precision = p;
}

Matthias Clasen's avatar
Matthias Clasen committed
435
436
/**
 * gdk_visual_get_red_pixel_details:
Matthias Clasen's avatar
Matthias Clasen committed
437
438
439
440
 * @visual: A #GdkVisual
 * @mask: (out) (allow-none): A pointer to a #guint32 to be filled in, or %NULL
 * @shift: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
 * @precision: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
Matthias Clasen's avatar
Matthias Clasen committed
441
442
 *
 * Obtains values that are needed to calculate red pixel values in TrueColor
William Jon McCann's avatar
William Jon McCann committed
443
444
 * and DirectColor. The “mask” is the significant bits within the pixel.
 * The “shift” is the number of bits left we must shift a primary for it
Matthias Clasen's avatar
Matthias Clasen committed
445
 * to be in position (according to the "mask"). Finally, "precision" refers
Matthias Clasen's avatar
Matthias Clasen committed
446
447
448
449
450
451
452
453
454
455
456
457
 * to how much precision the pixel value contains for a particular primary.
 *
 * Since: 2.22
 */
void
gdk_visual_get_red_pixel_details (GdkVisual *visual,
                                  guint32   *mask,
                                  gint      *shift,
                                  gint      *precision)
{
  g_return_if_fail (GDK_IS_VISUAL (visual));

458
  gdk_visual_get_pixel_details (visual, visual->red_mask, mask, shift, precision);
Matthias Clasen's avatar
Matthias Clasen committed
459
460
461
462
463
}

/**
 * gdk_visual_get_green_pixel_details:
 * @visual: a #GdkVisual
Matthias Clasen's avatar
Matthias Clasen committed
464
465
466
 * @mask: (out) (allow-none): A pointer to a #guint32 to be filled in, or %NULL
 * @shift: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
 * @precision: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
Matthias Clasen's avatar
Matthias Clasen committed
467
468
 *
 * Obtains values that are needed to calculate green pixel values in TrueColor
William Jon McCann's avatar
William Jon McCann committed
469
470
 * and DirectColor. The “mask” is the significant bits within the pixel.
 * The “shift” is the number of bits left we must shift a primary for it
Matthias Clasen's avatar
Matthias Clasen committed
471
 * to be in position (according to the "mask"). Finally, "precision" refers
Matthias Clasen's avatar
Matthias Clasen committed
472
473
474
475
476
477
478
479
480
481
482
483
 * to how much precision the pixel value contains for a particular primary.
 *
 * Since: 2.22
 */
void
gdk_visual_get_green_pixel_details (GdkVisual *visual,
                                    guint32   *mask,
                                    gint      *shift,
                                    gint      *precision)
{
  g_return_if_fail (GDK_IS_VISUAL (visual));

484
  gdk_visual_get_pixel_details (visual, visual->green_mask, mask, shift, precision);
Matthias Clasen's avatar
Matthias Clasen committed
485
486
487
488
489
}

/**
 * gdk_visual_get_blue_pixel_details:
 * @visual: a #GdkVisual
Matthias Clasen's avatar
Matthias Clasen committed
490
491
492
 * @mask: (out) (allow-none): A pointer to a #guint32 to be filled in, or %NULL
 * @shift: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
 * @precision: (out) (allow-none): A pointer to a #gint to be filled in, or %NULL
Matthias Clasen's avatar
Matthias Clasen committed
493
494
 *
 * Obtains values that are needed to calculate blue pixel values in TrueColor
William Jon McCann's avatar
William Jon McCann committed
495
496
 * and DirectColor. The “mask” is the significant bits within the pixel.
 * The “shift” is the number of bits left we must shift a primary for it
Matthias Clasen's avatar
Matthias Clasen committed
497
 * to be in position (according to the "mask"). Finally, "precision" refers
Matthias Clasen's avatar
Matthias Clasen committed
498
499
500
501
502
503
504
505
506
507
508
509
 * to how much precision the pixel value contains for a particular primary.
 *
 * Since: 2.22
 */
void
gdk_visual_get_blue_pixel_details (GdkVisual *visual,
                                   guint32   *mask,
                                   gint      *shift,
                                   gint      *precision)
{
  g_return_if_fail (GDK_IS_VISUAL (visual));

510
  gdk_visual_get_pixel_details (visual, visual->blue_mask, mask, shift, precision);
Matthias Clasen's avatar
Matthias Clasen committed
511
}
512
513
514
515
516
517
518

/**
 * gdk_visual_get_screen:
 * @visual: a #GdkVisual
 *
 * Gets the screen to which this visual belongs
 *
519
 * Returns: (transfer none): the screen to which this visual belongs.
520
521
522
523
524
525
526
527
528
529
 *
 * Since: 2.2
 */
GdkScreen *
gdk_visual_get_screen (GdkVisual *visual)
{
  g_return_val_if_fail (GDK_IS_VISUAL (visual), NULL);

  return visual->screen;
}