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 <!-- ##### FUNCTION gdk_rgb_init ##### -->
120 This function no longer does anything at all. It's completely useless
126 <!-- ##### FUNCTION gdk_draw_rgb_image ##### -->
128 Draws an RGB image in the drawable. This is the core GdkRGB
129 function, and likely the only one you will need to use.
133 The @rowstride parameter allows for lines to be aligned more flexibly.
134 For example, lines may be allocated to begin on 32-bit boundaries,
135 even if the width of the rectangle is odd. Rowstride is also useful
136 when drawing a subrectangle of a larger image in memory. Finally, to
137 replicate the same line a number of times, the trick of setting
138 @rowstride to 0 is allowed.
142 In general, for 0 <= i < @width and 0 <= j < height,
143 the pixel (x + i, y + j) is colored with red value @rgb_buf[@j *
144 @rowstride + @i * 3], green value @rgb_buf[@j * @rowstride + @i * 3 +
145 1], and blue value @rgb_buf[@j * @rowstride + @i * 3 + 2].
148 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
149 @gc: The graphics context (all GDK drawing operations require one; its
150 contents are ignored).
151 @x: The x coordinate of the top-left corner in the drawable.
152 @y: The y coordinate of the top-left corner in the drawable.
153 @width: The width of the rectangle to be drawn.
154 @height: The height of the rectangle to be drawn.
155 @dith: A #GdkRgbDither value, selecting the desired dither mode.
156 @rgb_buf: The pixel data, represented as packed 24-bit data.
157 @rowstride: The number of bytes from the start of one row in @rgb_buf to the
161 <!-- ##### FUNCTION gdk_draw_rgb_image_dithalign ##### -->
163 Draws an RGB image in the drawable, with an adjustment for dither alignment.
167 This function is useful when drawing dithered images into a window
168 that may be scrolled. Pixel (x, y) will be drawn dithered as if its
169 actual location is (x + @xdith, y + @ydith). Thus, if you draw an
170 image into a window using zero dither alignment, then scroll up one
171 pixel, subsequent draws to the window should have @ydith = 1.
175 Setting the dither alignment correctly allows updating of small parts
176 of the screen while avoiding visible "seams" between the different
180 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
181 @gc: The graphics context.
182 @x: The x coordinate of the top-left corner in the drawable.
183 @y: The y coordinate of the top-left corner in the drawable.
184 @width: The width of the rectangle to be drawn.
185 @height: The height of the rectangle to be drawn.
186 @dith: A #GdkRgbDither value, selecting the desired dither mode.
187 @rgb_buf: The pixel data, represented as packed 24-bit data.
188 @rowstride: The number of bytes from the start of one row in @rgb_buf to the
190 @xdith: An x offset for dither alignment.
191 @ydith: A y offset for dither alignment.
194 <!-- ##### FUNCTION gdk_draw_indexed_image ##### -->
196 Draws an indexed image in the drawable, using a #GdkRgbCmap to assign
197 actual colors to the color indices.
200 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
201 @gc: The graphics context.
202 @x: The x coordinate of the top-left corner in the drawable.
203 @y: The y coordinate of the top-left corner in the drawable.
204 @width: The width of the rectangle to be drawn.
205 @height: The height of the rectangle to be drawn.
206 @dith: A #GdkRgbDither value, selecting the desired dither mode.
207 @buf: The pixel data, represented as 8-bit color indices.
208 @rowstride: The number of bytes from the start of one row in @buf to the
210 @cmap: The #GdkRgbCmap used to assign colors to the color indices.
213 <!-- ##### FUNCTION gdk_draw_gray_image ##### -->
215 Draws a grayscale image in the drawable.
219 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
220 @gc: The graphics context.
221 @x: The x coordinate of the top-left corner in the drawable.
222 @y: The y coordinate of the top-left corner in the drawable.
223 @width: The width of the rectangle to be drawn.
224 @height: The height of the rectangle to be drawn.
225 @dith: A #GdkRgbDither value, selecting the desired dither mode.
226 @buf: The pixel data, represented as 8-bit gray values.
227 @rowstride: The number of bytes from the start of one row in @buf to the
231 <!-- ##### FUNCTION gdk_draw_rgb_32_image ##### -->
233 Draws a padded RGB image in the drawable. The image is stored as one
234 pixel per 32-bit word. It is laid out as a red byte, a green byte, a
235 blue byte, and a padding byte.
239 It's unlikely that this function will give significant performance
240 gains in practice. In my experience, the performance gain from having
241 pixels aligned to 32-bit boundaries is cancelled out by the increased
245 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
246 @gc: The graphics context.
247 @x: The x coordinate of the top-left corner in the drawable.
248 @y: The y coordinate of the top-left corner in the drawable.
249 @width: The width of the rectangle to be drawn.
250 @height: The height of the rectangle to be drawn.
251 @dith: A #GdkRgbDither value, selecting the desired dither mode.
252 @buf: The pixel data, represented as padded 32-bit data.
253 @rowstride: The number of bytes from the start of one row in @buf to the
257 <!-- ##### FUNCTION gdk_draw_rgb_32_image_dithalign ##### -->
275 <!-- ##### ENUM GdkRgbDither ##### -->
277 Selects whether or not GdkRGB applies dithering
278 to the image on display. There are three values:
285 %GDK_RGB_DITHER_NONE: Never use dithering.
291 %GDK_RGB_DITHER_NORMAL: Use dithering in 8 bits per pixel (and below)
298 %GDK_RGB_DITHER_MAX: Use dithering in 16 bits per pixel and below.
305 Since GdkRGB currently only handles images with 8 bits per component,
306 dithering on 24 bit per pixel displays is a moot point.
309 @GDK_RGB_DITHER_NONE:
310 @GDK_RGB_DITHER_NORMAL:
313 <!-- ##### FUNCTION gdk_rgb_cmap_new ##### -->
315 Creates a new #GdkRgbCmap structure. The cmap maps color indexes to
316 RGB colors. If @n_colors is less than 256, then images containing
317 color values greater than or equal to @n_colors will produce undefined
318 results, including possibly segfaults.
321 @colors: The colors, represented as 0xRRGGBB integer values.
322 @n_colors: The number of colors in the cmap.
323 @Returns: The newly created #GdkRgbCmap
326 <!-- ##### FUNCTION gdk_rgb_cmap_free ##### -->
328 Frees the memory associated with a #GdkRgbCmap created by gdk_rgb_cmap_new().
331 @cmap: The #GdkRgbCmap to free.
334 <!-- ##### STRUCT GdkRgbCmap ##### -->
336 A private data structure which maps color indices to actual RGB
337 colors. This is used only for gdk_draw_indexed_image().
343 <!-- ##### FUNCTION gdk_rgb_gc_set_foreground ##### -->
345 Sets the foreground color in @gc to the specified color (or the
346 closest approximation, in the case of limited visuals).
349 @gc: The #GdkGC to modify.
350 @rgb: The color, represented as a 0xRRGGBB integer value.
353 <!-- ##### FUNCTION gdk_rgb_gc_set_background ##### -->
355 Sets the background color in @gc to the specified color (or the
356 closest approximation, in the case of limited visuals).
359 @gc: The #GdkGC to modify.
360 @rgb: The color, represented as a 0xRRGGBB integer value.
363 <!-- ##### FUNCTION gdk_rgb_xpixel_from_rgb ##### -->
365 Finds the X pixel closest in color to the @rgb color specified. This
366 value may be used to set the <structfield>pixel</structfield> field of
370 @rgb: The color, represented as a 0xRRGGBB integer value.
371 @Returns: The X pixel value.
374 <!-- ##### FUNCTION gdk_rgb_find_color ##### -->
383 <!-- ##### FUNCTION gdk_rgb_set_install ##### -->
385 If @install is %TRUE, directs GdkRGB to always install a new "private"
386 colormap rather than trying to find a best fit with the colors already
387 allocated. Ordinarily, GdkRGB will install a colormap only if a
388 sufficient cube cannot be allocated.
392 A private colormap has more colors, leading to better quality display,
393 but also leads to the dreaded "colormap flashing" effect.
396 @install: %TRUE to set install mode.
399 <!-- ##### FUNCTION gdk_rgb_set_min_colors ##### -->
401 Sets the minimum number of colors for the color cube. Generally,
402 GdkRGB tries to allocate the largest color cube it can. If it can't
403 allocate a color cube at least as large as @min_colors, it installs a
407 @min_colors: The minimum number of colors accepted.
410 <!-- ##### FUNCTION gdk_rgb_get_visual ##### -->
417 <!-- ##### FUNCTION gdk_rgb_get_colormap ##### -->
425 <!-- ##### MACRO gdk_rgb_get_cmap ##### -->
427 Gets the colormap set by GdkRGB. This colormap and the corresponding
428 visual should be used when creating windows that will be drawn in by GdkRGB.
431 @Returns: The #GdkColormap set by GdkRGB.
434 <!-- ##### FUNCTION gdk_rgb_ditherable ##### -->
436 Determines whether the visual is ditherable. This function may be
437 useful for presenting a user interface choice to the user about which
438 dither mode is desired; if the display is not ditherable, it may make
439 sense to gray out or hide the corresponding UI widget.
442 @Returns: %TRUE if the visual is ditherable.
445 <!-- ##### FUNCTION gdk_rgb_set_verbose ##### -->
447 Sets the "verbose" flag. This is generally only useful for debugging.
450 @verbose: %TRUE if verbose messages are desired.