1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 Renders RGB, grayscale, or indexed image data to a GdkDrawable
7 <!-- ##### SECTION Long_Description ##### -->
10 GdkRGB is a low-level module which renders RGB, grayscale, and indexed
11 colormap images to a #GdkDrawable. It does this as efficiently as
12 possible, handling issues such as colormaps, visuals, dithering,
13 temporary buffers, and so on. Most code should use the higher-level
14 #GdkPixbuf features in place of this module; for example,
15 gdk_pixbuf_render_to_drawable() uses GdkRGB in its implementation.
19 GdkRGB allocates a color cube to use when rendering images. You can
20 set the threshold for installing colormaps with
21 gdk_rgb_set_min_colors(). The default is 5x5x5 (125). If a colorcube
22 of this size or larger can be allocated in the default colormap, then
23 that's done. Otherwise, GdkRGB creates its own private colormap.
24 Setting it to 0 means that it always tries to use the default
25 colormap, and setting it to 216 means that it always creates a private
26 one if it cannot allocate the 6x6x6 colormap in the default. If you
27 always want a private colormap (to avoid consuming too many colormap
28 entries for other apps, say), you can use
29 <literal>gdk_rgb_set_install(TRUE)</literal>.
30 Setting the value greater than 216 exercises a bug in older versions
31 of GdkRGB. Note, however, that setting it to 0 doesn't let you get
32 away with ignoring the colormap and visual - a colormap is always
33 created in grayscale and direct color modes, and the visual is changed
34 in cases where a "better" visual than the default is available.
38 <title>A simple example program using GdkRGB</title>
40 #include <gtk/gtk.h>
42 #define IMAGE_WIDTH 256
43 #define IMAGE_HEIGHT 256
45 guchar rgbbuf[IMAGE_WIDTH * IMAGE_HEIGHT * 3];
47 gboolean on_darea_expose (GtkWidget *widget,
48 GdkEventExpose *event,
52 main (int argc, char *argv[])
54 GtkWidget *window, *darea;
58 gtk_init (&argc, &argv);
60 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
61 darea = gtk_drawing_area_new (<!-- -->);
62 gtk_widget_set_size_request (darea, IMAGE_WIDTH, IMAGE_HEIGHT);
63 gtk_container_add (GTK_CONTAINER (window), darea);
64 gtk_signal_connect (GTK_OBJECT (darea), "expose-event",
65 GTK_SIGNAL_FUNC (on_darea_expose), NULL);
66 gtk_widget_show_all (window);
68 /* Set up the RGB buffer. */
70 for (y = 0; y < IMAGE_HEIGHT; y++)
72 for (x = 0; x < IMAGE_WIDTH; x++)
74 *pos++ = x - x % 32; /* Red. */
75 *pos++ = (x / 32) * 4 + y - y % 32; /* Green. */
76 *pos++ = y - y % 32; /* Blue. */
86 on_darea_expose (GtkWidget *widget,
87 GdkEventExpose *event,
90 gdk_draw_rgb_image (widget->window, widget->style->fg_gc[GTK_STATE_NORMAL],
91 0, 0, IMAGE_WIDTH, IMAGE_HEIGHT,
92 GDK_RGB_DITHER_MAX, rgbbuf, IMAGE_WIDTH * 3);
99 <!-- ##### SECTION See_Also ##### -->
104 <term>#GdkColor</term>
105 <listitem><para>The underlying GDK mechanism for allocating
106 colors.</para></listitem>
110 <term>#GdkPixbuf and gdk_pixbuf_render_to_drawable()</term>
111 <listitem><para>Higher-level image handling.</para></listitem>
118 <!-- ##### SECTION Stability_Level ##### -->
121 <!-- ##### FUNCTION gdk_rgb_init ##### -->
123 This function no longer does anything at all. It's completely useless
129 <!-- ##### FUNCTION gdk_draw_rgb_image ##### -->
131 Draws an RGB image in the drawable. This is the core GdkRGB
132 function, and likely the only one you will need to use.
136 The @rowstride parameter allows for lines to be aligned more flexibly.
137 For example, lines may be allocated to begin on 32-bit boundaries,
138 even if the width of the rectangle is odd. Rowstride is also useful
139 when drawing a subrectangle of a larger image in memory. Finally, to
140 replicate the same line a number of times, the trick of setting
141 @rowstride to 0 is allowed.
145 In general, for 0 <= i < @width and 0 <= j < height,
146 the pixel (x + i, y + j) is colored with red value @rgb_buf[@j *
147 @rowstride + @i * 3], green value @rgb_buf[@j * @rowstride + @i * 3 +
148 1], and blue value @rgb_buf[@j * @rowstride + @i * 3 + 2].
151 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
152 @gc: The graphics context (all GDK drawing operations require one; its
153 contents are ignored).
154 @x: The x coordinate of the top-left corner in the drawable.
155 @y: The y coordinate of the top-left corner in the drawable.
156 @width: The width of the rectangle to be drawn.
157 @height: The height of the rectangle to be drawn.
158 @dith: A #GdkRgbDither value, selecting the desired dither mode.
159 @rgb_buf: The pixel data, represented as packed 24-bit data.
160 @rowstride: The number of bytes from the start of one row in @rgb_buf to the
164 <!-- ##### FUNCTION gdk_draw_rgb_image_dithalign ##### -->
166 Draws an RGB image in the drawable, with an adjustment for dither alignment.
170 This function is useful when drawing dithered images into a window
171 that may be scrolled. Pixel (x, y) will be drawn dithered as if its
172 actual location is (x + @xdith, y + @ydith). Thus, if you draw an
173 image into a window using zero dither alignment, then scroll up one
174 pixel, subsequent draws to the window should have @ydith = 1.
178 Setting the dither alignment correctly allows updating of small parts
179 of the screen while avoiding visible "seams" between the different
183 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
184 @gc: The graphics context.
185 @x: The x coordinate of the top-left corner in the drawable.
186 @y: The y coordinate of the top-left corner in the drawable.
187 @width: The width of the rectangle to be drawn.
188 @height: The height of the rectangle to be drawn.
189 @dith: A #GdkRgbDither value, selecting the desired dither mode.
190 @rgb_buf: The pixel data, represented as packed 24-bit data.
191 @rowstride: The number of bytes from the start of one row in @rgb_buf to the
193 @xdith: An x offset for dither alignment.
194 @ydith: A y offset for dither alignment.
197 <!-- ##### FUNCTION gdk_draw_indexed_image ##### -->
199 Draws an indexed image in the drawable, using a #GdkRgbCmap to assign
200 actual colors to the color indices.
203 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
204 @gc: The graphics context.
205 @x: The x coordinate of the top-left corner in the drawable.
206 @y: The y coordinate of the top-left corner in the drawable.
207 @width: The width of the rectangle to be drawn.
208 @height: The height of the rectangle to be drawn.
209 @dith: A #GdkRgbDither value, selecting the desired dither mode.
210 @buf: The pixel data, represented as 8-bit color indices.
211 @rowstride: The number of bytes from the start of one row in @buf to the
213 @cmap: The #GdkRgbCmap used to assign colors to the color indices.
216 <!-- ##### FUNCTION gdk_draw_gray_image ##### -->
218 Draws a grayscale image in the drawable.
222 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
223 @gc: The graphics context.
224 @x: The x coordinate of the top-left corner in the drawable.
225 @y: The y coordinate of the top-left corner in the drawable.
226 @width: The width of the rectangle to be drawn.
227 @height: The height of the rectangle to be drawn.
228 @dith: A #GdkRgbDither value, selecting the desired dither mode.
229 @buf: The pixel data, represented as 8-bit gray values.
230 @rowstride: The number of bytes from the start of one row in @buf to the
234 <!-- ##### FUNCTION gdk_draw_rgb_32_image ##### -->
236 Draws a padded RGB image in the drawable. The image is stored as one
237 pixel per 32-bit word. It is laid out as a red byte, a green byte, a
238 blue byte, and a padding byte.
242 It's unlikely that this function will give significant performance
243 gains in practice. In my experience, the performance gain from having
244 pixels aligned to 32-bit boundaries is cancelled out by the increased
248 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
249 @gc: The graphics context.
250 @x: The x coordinate of the top-left corner in the drawable.
251 @y: The y coordinate of the top-left corner in the drawable.
252 @width: The width of the rectangle to be drawn.
253 @height: The height of the rectangle to be drawn.
254 @dith: A #GdkRgbDither value, selecting the desired dither mode.
255 @buf: The pixel data, represented as padded 32-bit data.
256 @rowstride: The number of bytes from the start of one row in @buf to the
260 <!-- ##### FUNCTION gdk_draw_rgb_32_image_dithalign ##### -->
278 <!-- ##### ENUM GdkRgbDither ##### -->
280 Selects whether or not GdkRGB applies dithering
281 to the image on display. There are three values:
288 %GDK_RGB_DITHER_NONE: Never use dithering.
294 %GDK_RGB_DITHER_NORMAL: Use dithering in 8 bits per pixel (and below)
301 %GDK_RGB_DITHER_MAX: Use dithering in 16 bits per pixel and below.
308 Since GdkRGB currently only handles images with 8 bits per component,
309 dithering on 24 bit per pixel displays is a moot point.
312 @GDK_RGB_DITHER_NONE:
313 @GDK_RGB_DITHER_NORMAL:
316 <!-- ##### FUNCTION gdk_rgb_cmap_new ##### -->
318 Creates a new #GdkRgbCmap structure. The cmap maps color indexes to
319 RGB colors. If @n_colors is less than 256, then images containing
320 color values greater than or equal to @n_colors will produce undefined
321 results, including possibly segfaults.
324 @colors: The colors, represented as 0xRRGGBB integer values.
325 @n_colors: The number of colors in the cmap.
326 @Returns: The newly created #GdkRgbCmap
329 <!-- ##### FUNCTION gdk_rgb_cmap_free ##### -->
331 Frees the memory associated with a #GdkRgbCmap created by gdk_rgb_cmap_new().
334 @cmap: The #GdkRgbCmap to free.
337 <!-- ##### STRUCT GdkRgbCmap ##### -->
339 A private data structure which maps color indices to actual RGB
340 colors. This is used only for gdk_draw_indexed_image().
346 <!-- ##### FUNCTION gdk_rgb_gc_set_foreground ##### -->
348 Sets the foreground color in @gc to the specified color (or the
349 closest approximation, in the case of limited visuals).
352 @gc: The #GdkGC to modify.
353 @rgb: The color, represented as a 0xRRGGBB integer value.
356 <!-- ##### FUNCTION gdk_rgb_gc_set_background ##### -->
358 Sets the background color in @gc to the specified color (or the
359 closest approximation, in the case of limited visuals).
362 @gc: The #GdkGC to modify.
363 @rgb: The color, represented as a 0xRRGGBB integer value.
366 <!-- ##### FUNCTION gdk_rgb_xpixel_from_rgb ##### -->
368 Finds the X pixel closest in color to the @rgb color specified. This
369 value may be used to set the <structfield>pixel</structfield> field of
373 @rgb: The color, represented as a 0xRRGGBB integer value.
374 @Returns: The X pixel value.
377 <!-- ##### FUNCTION gdk_rgb_find_color ##### -->
386 <!-- ##### FUNCTION gdk_rgb_set_install ##### -->
388 If @install is %TRUE, directs GdkRGB to always install a new "private"
389 colormap rather than trying to find a best fit with the colors already
390 allocated. Ordinarily, GdkRGB will install a colormap only if a
391 sufficient cube cannot be allocated.
395 A private colormap has more colors, leading to better quality display,
396 but also leads to the dreaded "colormap flashing" effect.
399 @install: %TRUE to set install mode.
402 <!-- ##### FUNCTION gdk_rgb_set_min_colors ##### -->
404 Sets the minimum number of colors for the color cube. Generally,
405 GdkRGB tries to allocate the largest color cube it can. If it can't
406 allocate a color cube at least as large as @min_colors, it installs a
410 @min_colors: The minimum number of colors accepted.
413 <!-- ##### FUNCTION gdk_rgb_get_visual ##### -->
420 <!-- ##### FUNCTION gdk_rgb_get_colormap ##### -->
428 <!-- ##### MACRO gdk_rgb_get_cmap ##### -->
430 Gets the colormap set by GdkRGB. This colormap and the corresponding
431 visual should be used when creating windows that will be drawn in by GdkRGB.
434 @Returns: The #GdkColormap set by GdkRGB.
437 <!-- ##### FUNCTION gdk_rgb_ditherable ##### -->
439 Determines whether the preferred visual is ditherable. This function may be
440 useful for presenting a user interface choice to the user about which
441 dither mode is desired; if the display is not ditherable, it may make
442 sense to gray out or hide the corresponding UI widget.
445 @Returns: %TRUE if the preferred visual is ditherable.
448 <!-- ##### FUNCTION gdk_rgb_colormap_ditherable ##### -->
450 Determines whether the visual associated with @cmap is ditherable. This
451 function may be useful for presenting a user interface choice to the user
452 about which dither mode is desired; if the display is not ditherable, it may
453 make sense to gray out or hide the corresponding UI widget.
456 @cmap: a #GdkColormap
457 @Returns: %TRUE if the visual associated with @cmap is ditherable.
460 <!-- ##### FUNCTION gdk_rgb_set_verbose ##### -->
462 Sets the "verbose" flag. This is generally only useful for debugging.
465 @verbose: %TRUE if verbose messages are desired.