1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 displays RGB images (as well as grayscale and colormapped) to
8 <!-- ##### SECTION Long_Description ##### -->
11 GdkRgb converts RGB, grayscale, and colormapped images into the native
12 window pixel format and displays them. It takes care of colormaps,
13 visuals, dithering, and management of the temporary buffers.
18 You must call gdk_rgb_init() before using any GdkRgb functionality. If
19 you fail to do so, expect coredumps. All Gtk+ widgets that use GdkRgb
20 (including #GtkPreview) call gdk_rgb_init() in their class_init method.
21 Thus, if you use GdkRgb only indirectly, you don't need to worry
26 GdkRgb tries to use the system default visual and colormap, but
27 doesn't always succeed. Thus, you have to be prepared to install the
28 visual and colormap generated by GdkRgb. The following code sequence
29 (before any widgets are created) should work in most applications:
36 gtk_widget_set_default_colormap (gdk_rgb_get_cmap ());
37 gtk_widget_set_default_visual (gdk_rgb_get_visual ());
42 You can also push the colormap and visual, but in general it doesn't
43 work unless the push wraps the window creation call. If you wrap the
44 push around a widget which is embedded in a window without the GdkRgb
45 colormap and visual, it probably won't work, and is likely to cause
46 colormap flashing, as well.
50 On 8-bit systems, the colormaps used by Imlib and GdkRgb may
51 conflict. There is no good general solution to this other than phasing
52 out the dependence on Imlib.
56 You can set the threshold for installing colormaps with
57 gdk_rgb_set_min_colors (). The default is 5x5x5 (125). If a colorcube
58 of this size or larger can be allocated in the default colormap, then
59 that's done. Otherwise, GdkRgb creates its own private colormap.
60 Setting it to 0 means that it always tries to use the default
61 colormap, and setting it to 216 means that it always creates a private
62 one if it cannot allocate the 6x6x6 colormap in the default. If you
63 always want a private colormap (to avoid consuming too many colormap
64 entries for other apps, say), you can use gdk_rgb_set_install(TRUE).
65 Setting the value greater than 216 exercises a bug in older versions
66 of GdkRgb. Note, however, that setting it to 0 doesn't let you get
67 away with ignoring the colormap and visual - a colormap is always
68 created in grayscale and direct color modes, and the visual is changed
69 in cases where a "better" visual than the default is available.
73 <title>A simple example program using GdkRGB.</title>
75 #include <gtk/gtk.h>
77 #define IMAGE_WIDTH 256
78 #define IMAGE_HEIGHT 256
80 guchar rgbbuf[IMAGE_WIDTH * IMAGE_HEIGHT * 3];
82 gboolean on_darea_expose (GtkWidget *widget,
83 GdkEventExpose *event,
87 main (int argc, char *argv[])
89 GtkWidget *window, *darea;
93 gtk_init (&argc, &argv);
95 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
96 darea = gtk_drawing_area_new ();
97 gtk_drawing_area_size (GTK_DRAWING_AREA (darea), IMAGE_WIDTH, IMAGE_HEIGHT);
98 gtk_container_add (GTK_CONTAINER (window), darea);
99 gtk_signal_connect (GTK_OBJECT (darea), "expose-event",
100 GTK_SIGNAL_FUNC (on_darea_expose), NULL);
101 gtk_widget_show_all (window);
103 /* Set up the RGB buffer. */
105 for (y = 0; y < IMAGE_HEIGHT; y++)
107 for (x = 0; x < IMAGE_WIDTH; x++)
109 *pos++ = x - x % 32; /* Red. */
110 *pos++ = (x / 32) * 4 + y - y % 32; /* Green. */
111 *pos++ = y - y % 32; /* Blue. */
121 on_darea_expose (GtkWidget *widget,
122 GdkEventExpose *event,
125 gdk_draw_rgb_image (widget->window, widget->style->fg_gc[GTK_STATE_NORMAL],
126 0, 0, IMAGE_WIDTH, IMAGE_HEIGHT,
127 GDK_RGB_DITHER_MAX, rgbbuf, IMAGE_WIDTH * 3);
132 <!-- ##### SECTION See_Also ##### -->
137 <term>#GdkColor</term>
138 <listitem><para>The underlying Gdk mechanism for allocating
139 colors.</para></listitem>
146 <!-- ##### FUNCTION gdk_rgb_init ##### -->
148 Initializes GdkRgb statically. It may be called more than once with no
149 ill effects. It must, however, be called before any other GdkRgb
150 operations are performed.
154 The GdkRgb "context" is allocated statically. Thus, GdkRgb may be used
155 to drive only one visual in any given application. GdkRgb
156 automatically selects a best visual and sets its own colormap, if
157 necessary. gdk_rgb_get_visual() and gdk_rgb_get_cmap () retrieve
158 the chosen visual and colormap, respectively.
163 <!-- ##### FUNCTION gdk_draw_rgb_image ##### -->
165 Draws an RGB image in the drawable. This is the core GdkRgb
166 function, and likely the only one you will need to use other than the
167 initialization stuff.
171 The @rowstride parameter allows for lines to be aligned more flexibly.
172 For example, lines may be allocated to begin on 32-bit boundaries,
173 even if the width of the rectangle is odd. Rowstride is also useful
174 when drawing a subrectangle of a larger image in memory. Finally, to
175 replicate the same line a number of times, the trick of setting
176 @rowstride to 0 is allowed.
180 In general, for 0 <= i < @width and 0 <= j < height,
181 the pixel (x + i, y + j) is colored with red value @rgb_buf[@j *
182 @rowstride + @i * 3], green value @rgb_buf[@j * @rowstride + @i * 3 +
183 1], and blue value @rgb_buf[@j * @rowstride + @i * 3 + 2].
186 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
187 @gc: The graphics context (all Gdk drawing operations require one; its
188 contents are ignored).
189 @x: The x coordinate of the top-left corner in the drawable.
190 @y: The y coordinate of the top-left corner in the drawable.
191 @width: The width of the rectangle to be drawn.
192 @height: The height of the rectangle to be drawn.
193 @dith: A #GdkRgbDither value, selecting the desired dither mode.
194 @rgb_buf: The pixel data, represented as packed 24-bit data.
195 @rowstride: The number of bytes from the start of one row in @rgb_buf to the
199 <!-- ##### FUNCTION gdk_draw_rgb_image_dithalign ##### -->
201 Draws an RGB image in the drawable, with an adjustment for dither alignment.
205 This function is useful when drawing dithered images into a window
206 that may be scrolled. Pixel (x, y) will be drawn dithered as if its
207 actual location is (x + @xdith, y + @ydith). Thus, if you draw an
208 image into a window using zero dither alignment, then scroll up one
209 pixel, subsequent draws to the window should have @ydith = 1.
213 Setting the dither alignment correctly allows updating of small parts
214 of the screen while avoiding visible "seams" between the different
218 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
219 @gc: The graphics context.
220 @x: The x coordinate of the top-left corner in the drawable.
221 @y: The y coordinate of the top-left corner in the drawable.
222 @width: The width of the rectangle to be drawn.
223 @height: The height of the rectangle to be drawn.
224 @dith: A #GdkRgbDither value, selecting the desired dither mode.
225 @rgb_buf: The pixel data, represented as packed 24-bit data.
226 @rowstride: The number of bytes from the start of one row in @rgb_buf to the
228 @xdith: An x offset for dither alignment.
229 @ydith: A y offset for dither alignment.
232 <!-- ##### FUNCTION gdk_draw_indexed_image ##### -->
234 Draws an indexed image in the drawable, using a #GdkRgbCmap to assign
235 actual colors to the color indices.
238 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
239 @gc: The graphics context.
240 @x: The x coordinate of the top-left corner in the drawable.
241 @y: The y coordinate of the top-left corner in the drawable.
242 @width: The width of the rectangle to be drawn.
243 @height: The height of the rectangle to be drawn.
244 @dith: A #GdkRgbDither value, selecting the desired dither mode.
245 @buf: The pixel data, represented as 8-bit color indices.
246 @rowstride: The number of bytes from the start of one row in @buf to the
248 @cmap: The #GdkRgbCmap used to assign colors to the color indices.
251 <!-- ##### FUNCTION gdk_draw_gray_image ##### -->
253 Draws a grayscale image in the drawable.
257 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
258 @gc: The graphics context.
259 @x: The x coordinate of the top-left corner in the drawable.
260 @y: The y coordinate of the top-left corner in the drawable.
261 @width: The width of the rectangle to be drawn.
262 @height: The height of the rectangle to be drawn.
263 @dith: A #GdkRgbDither value, selecting the desired dither mode.
264 @buf: The pixel data, represented as 8-bit gray values.
265 @rowstride: The number of bytes from the start of one row in @buf to the
269 <!-- ##### FUNCTION gdk_draw_rgb_32_image ##### -->
271 Draws a padded RGB image in the drawable. The image is stored as one
272 pixel per 32-bit word. It is laid out as a red byte, a green byte, a
273 blue byte, and a padding byte.
277 It's unlikely that this function will give significant performance
278 gains in practice. In my experience, the performance gain from having
279 pixels aligned to 32-bit boundaries is cancelled out by the increased
283 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
284 @gc: The graphics context.
285 @x: The x coordinate of the top-left corner in the drawable.
286 @y: The y coordinate of the top-left corner in the drawable.
287 @width: The width of the rectangle to be drawn.
288 @height: The height of the rectangle to be drawn.
289 @dith: A #GdkRgbDither value, selecting the desired dither mode.
290 @buf: The pixel data, represented as padded 32-bit data.
291 @rowstride: The number of bytes from the start of one row in @buf to the
295 <!-- ##### ENUM GdkRgbDither ##### -->
298 Selects whether or not GdkRgb applies dithering
299 to the image on display. There are three values:
306 %GDK_RGB_DITHER_NONE: Never use dithering.
312 %GDK_RGB_DITHER_NORMAL: Use dithering in 8 bits per pixel (and below)
319 %GDK_RGB_DITHER_MAX: Use dithering in 16 bits per pixel and below.
326 Since GdkRgb currently only handles images with 8 bits per component,
327 dithering on 24 bit per pixel displays is a moot point.
330 @GDK_RGB_DITHER_NONE:
331 @GDK_RGB_DITHER_NORMAL:
334 <!-- ##### FUNCTION gdk_rgb_cmap_new ##### -->
336 Creates a new #GdkRgbCmap structure. The cmap maps color indexes to
337 RGB colors. If @n_colors is less than 256, then images containing
338 color values greater than or equal to @n_colors will produce undefined
339 results, including possibly segfaults.
342 @colors: The colors, represented as 0xRRGGBB integer values.
343 @n_colors: The number of colors in the cmap.
344 @Returns: The newly created #GdkRgbCmap
347 <!-- ##### FUNCTION gdk_rgb_cmap_free ##### -->
349 Frees the memory associated with a #GdkRgbCmap created by gdk_rgb_cmap_new().
352 @cmap: The #GdkRgbCmap to free.
355 <!-- ##### STRUCT GdkRgbCmap ##### -->
357 A private data structure which maps color indices to actual RGB
358 colors. This is used only for gdk_draw_indexed_image().
364 <!-- ##### FUNCTION gdk_rgb_gc_set_foreground ##### -->
366 Sets the foreground color in @gc to the specified color (or the
367 closest approximation, in the case of limited visuals).
370 @gc: The #GdkGC to modify.
371 @rgb: The color, represented as a 0xRRGGBB integer value.
374 <!-- ##### FUNCTION gdk_rgb_gc_set_background ##### -->
376 Sets the background color in @gc to the specified color (or the
377 closest approximation, in the case of limited visuals).
380 @gc: The #GdkGC to modify.
381 @rgb: The color, represented as a 0xRRGGBB integer value.
384 <!-- ##### FUNCTION gdk_rgb_xpixel_from_rgb ##### -->
386 Finds the X pixel closest in color to the @rgb color specified. This
387 value may be used to set the <structfield>pixel</structfield> field of
391 @rgb: The color, represented as a 0xRRGGBB integer value.
392 @Returns: The X pixel value.
395 <!-- ##### FUNCTION gdk_rgb_set_install ##### -->
397 If @install is TRUE, directs GdkRgb to always install a new "private"
398 colormap rather than trying to find a best fit with the colors already
399 allocated. Ordinarily, GdkRgb will install a colormap only if a
400 sufficient cube cannot be allocated.
404 A private colormap has more colors, leading to better quality display,
405 but also leads to the dreaded "colormap flashing" effect.
408 @install: TRUE to set install mode.
411 <!-- ##### FUNCTION gdk_rgb_set_min_colors ##### -->
413 Sets the minimum number of colors for the color cube. Generally,
414 GdkRgb tries to allocate the largest color cube it can. If it can't
415 allocate a color cube at least as large as @min_colors, it installs a
419 @min_colors: The minimum number of colors accepted.
422 <!-- ##### FUNCTION gdk_rgb_get_visual ##### -->
424 Gets the visual chosen by GdkRgb. This visual and the corresponding
425 colormap should be used when creating windows that will be drawn in by GdkRgb.
428 @Returns: The #GdkVisual chosen by GdkRgb.
431 <!-- ##### FUNCTION gdk_rgb_get_cmap ##### -->
433 Gets the colormap set by GdkRgb. This colormap and the corresponding
434 visual should be used when creating windows that will be drawn in by GdkRgb.
437 @Returns: The #GdkColormap set by GdkRgb.
440 <!-- ##### FUNCTION gdk_rgb_ditherable ##### -->
442 Determine whether the visual is ditherable. This function may be
443 useful for presenting a user interface choice to the user about which
444 dither mode is desired; if the display is not ditherable, it may make
445 sense to gray out or hide the corresponding UI widget.
448 @Returns: TRUE if the visual is ditherable.
451 <!-- ##### FUNCTION gdk_rgb_set_verbose ##### -->
453 Sets the "verbose" flag. This is generally only useful for debugging.
456 @verbose: TRUE if verbose messages are desired.