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_draw_pixbuf() 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 If GDK is built with the Sun mediaLib library, the GdkRGB functions are
39 accelerated using mediaLib, which provides hardware acceleration on Intel,
40 AMD, and Sparc chipsets. If desired, mediaLib support can be turned off
41 by setting the GDK_DISABLE_MEDIALIB environment variable.
45 <title>A simple example program using GdkRGB</title>
47 #include <gtk/gtk.h>
49 #define IMAGE_WIDTH 256
50 #define IMAGE_HEIGHT 256
52 guchar rgbbuf[IMAGE_WIDTH * IMAGE_HEIGHT * 3];
54 gboolean on_darea_expose (GtkWidget *widget,
55 GdkEventExpose *event,
59 main (int argc, char *argv[])
61 GtkWidget *window, *darea;
65 gtk_init (&argc, &argv);
67 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
68 darea = gtk_drawing_area_new (<!-- -->);
69 gtk_widget_set_size_request (darea, IMAGE_WIDTH, IMAGE_HEIGHT);
70 gtk_container_add (GTK_CONTAINER (window), darea);
71 gtk_signal_connect (GTK_OBJECT (darea), "expose-event",
72 GTK_SIGNAL_FUNC (on_darea_expose), NULL);
73 gtk_widget_show_all (window);
75 /* Set up the RGB buffer. */
77 for (y = 0; y < IMAGE_HEIGHT; y++)
79 for (x = 0; x < IMAGE_WIDTH; x++)
81 *pos++ = x - x % 32; /* Red. */
82 *pos++ = (x / 32) * 4 + y - y % 32; /* Green. */
83 *pos++ = y - y % 32; /* Blue. */
93 on_darea_expose (GtkWidget *widget,
94 GdkEventExpose *event,
97 gdk_draw_rgb_image (widget->window, widget->style->fg_gc[GTK_STATE_NORMAL],
98 0, 0, IMAGE_WIDTH, IMAGE_HEIGHT,
99 GDK_RGB_DITHER_MAX, rgbbuf, IMAGE_WIDTH * 3);
106 <!-- ##### SECTION See_Also ##### -->
111 <term>#GdkColor</term>
112 <listitem><para>The underlying GDK mechanism for allocating
113 colors.</para></listitem>
117 <term>#GdkPixbuf and gdk_draw_pixbuf()</term>
118 <listitem><para>Higher-level image handling.</para></listitem>
125 <!-- ##### SECTION Stability_Level ##### -->
128 <!-- ##### FUNCTION gdk_draw_rgb_image ##### -->
130 Draws an RGB image in the drawable. This is the core GdkRGB
131 function, and likely the only one you will need to use.
135 The @rowstride parameter allows for lines to be aligned more flexibly.
136 For example, lines may be allocated to begin on 32-bit boundaries,
137 even if the width of the rectangle is odd. Rowstride is also useful
138 when drawing a subrectangle of a larger image in memory. Finally, to
139 replicate the same line a number of times, the trick of setting
140 @rowstride to 0 is allowed.
144 In general, for 0 <= i < @width and 0 <= j < height,
145 the pixel (x + i, y + j) is colored with red value @rgb_buf[@j *
146 @rowstride + @i * 3], green value @rgb_buf[@j * @rowstride + @i * 3 +
147 1], and blue value @rgb_buf[@j * @rowstride + @i * 3 + 2].
150 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
151 @gc: The graphics context (all GDK drawing operations require one; its
152 contents are ignored).
153 @x: The x coordinate of the top-left corner in the drawable.
154 @y: The y coordinate of the top-left corner in the drawable.
155 @width: The width of the rectangle to be drawn.
156 @height: The height of the rectangle to be drawn.
157 @dith: A #GdkRgbDither value, selecting the desired dither mode.
158 @rgb_buf: The pixel data, represented as packed 24-bit data.
159 @rowstride: The number of bytes from the start of one row in @rgb_buf to the
163 <!-- ##### FUNCTION gdk_draw_rgb_image_dithalign ##### -->
165 Draws an RGB image in the drawable, with an adjustment for dither alignment.
169 This function is useful when drawing dithered images into a window
170 that may be scrolled. Pixel (x, y) will be drawn dithered as if its
171 actual location is (x + @xdith, y + @ydith). Thus, if you draw an
172 image into a window using zero dither alignment, then scroll up one
173 pixel, subsequent draws to the window should have @ydith = 1.
177 Setting the dither alignment correctly allows updating of small parts
178 of the screen while avoiding visible "seams" between the different
182 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
183 @gc: The graphics context.
184 @x: The x coordinate of the top-left corner in the drawable.
185 @y: The y coordinate of the top-left corner in the drawable.
186 @width: The width of the rectangle to be drawn.
187 @height: The height of the rectangle to be drawn.
188 @dith: A #GdkRgbDither value, selecting the desired dither mode.
189 @rgb_buf: The pixel data, represented as packed 24-bit data.
190 @rowstride: The number of bytes from the start of one row in @rgb_buf to the
192 @xdith: An x offset for dither alignment.
193 @ydith: A y offset for dither alignment.
196 <!-- ##### FUNCTION gdk_draw_indexed_image ##### -->
198 Draws an indexed image in the drawable, using a #GdkRgbCmap to assign
199 actual colors to the color indices.
202 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
203 @gc: The graphics context.
204 @x: The x coordinate of the top-left corner in the drawable.
205 @y: The y coordinate of the top-left corner in the drawable.
206 @width: The width of the rectangle to be drawn.
207 @height: The height of the rectangle to be drawn.
208 @dith: A #GdkRgbDither value, selecting the desired dither mode.
209 @buf: The pixel data, represented as 8-bit color indices.
210 @rowstride: The number of bytes from the start of one row in @buf to the
212 @cmap: The #GdkRgbCmap used to assign colors to the color indices.
215 <!-- ##### FUNCTION gdk_draw_gray_image ##### -->
217 Draws a grayscale image in the drawable.
221 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
222 @gc: The graphics context.
223 @x: The x coordinate of the top-left corner in the drawable.
224 @y: The y coordinate of the top-left corner in the drawable.
225 @width: The width of the rectangle to be drawn.
226 @height: The height of the rectangle to be drawn.
227 @dith: A #GdkRgbDither value, selecting the desired dither mode.
228 @buf: The pixel data, represented as 8-bit gray values.
229 @rowstride: The number of bytes from the start of one row in @buf to the
233 <!-- ##### FUNCTION gdk_draw_rgb_32_image ##### -->
235 Draws a padded RGB image in the drawable. The image is stored as one
236 pixel per 32-bit word. It is laid out as a red byte, a green byte, a
237 blue byte, and a padding byte.
241 It's unlikely that this function will give significant performance
242 gains in practice. In my experience, the performance gain from having
243 pixels aligned to 32-bit boundaries is cancelled out by the increased
247 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
248 @gc: The graphics context.
249 @x: The x coordinate of the top-left corner in the drawable.
250 @y: The y coordinate of the top-left corner in the drawable.
251 @width: The width of the rectangle to be drawn.
252 @height: The height of the rectangle to be drawn.
253 @dith: A #GdkRgbDither value, selecting the desired dither mode.
254 @buf: The pixel data, represented as padded 32-bit data.
255 @rowstride: The number of bytes from the start of one row in @buf to the
259 <!-- ##### FUNCTION gdk_draw_rgb_32_image_dithalign ##### -->
277 <!-- ##### ENUM GdkRgbDither ##### -->
279 Selects whether or not GdkRGB applies dithering
280 to the image on display.
284 Since GdkRGB currently only handles images with 8 bits per component,
285 dithering on 24 bit per pixel displays is a moot point.
288 @GDK_RGB_DITHER_NONE: Never use dithering.
289 @GDK_RGB_DITHER_NORMAL: Use dithering in 8 bits per pixel (and below)
291 @GDK_RGB_DITHER_MAX: Use dithering in 16 bits per pixel and below.
293 <!-- ##### FUNCTION gdk_rgb_cmap_new ##### -->
295 Creates a new #GdkRgbCmap structure. The cmap maps color indexes to
296 RGB colors. If @n_colors is less than 256, then images containing
297 color values greater than or equal to @n_colors will produce undefined
298 results, including possibly segfaults.
301 @colors: The colors, represented as 0xRRGGBB integer values.
302 @n_colors: The number of colors in the cmap.
303 @Returns: The newly created #GdkRgbCmap
306 <!-- ##### FUNCTION gdk_rgb_cmap_free ##### -->
308 Frees the memory associated with a #GdkRgbCmap created by gdk_rgb_cmap_new().
311 @cmap: The #GdkRgbCmap to free.
314 <!-- ##### STRUCT GdkRgbCmap ##### -->
316 A private data structure which maps color indices to actual RGB
317 colors. This is used only for gdk_draw_indexed_image().
320 @colors: The colors, represented as 0xRRGGBB integer values.
321 @n_colors: The number of colors in the cmap.
323 <!-- ##### FUNCTION gdk_rgb_find_color ##### -->
332 <!-- ##### FUNCTION gdk_rgb_set_install ##### -->
334 If @install is %TRUE, directs GdkRGB to always install a new "private"
335 colormap rather than trying to find a best fit with the colors already
336 allocated. Ordinarily, GdkRGB will install a colormap only if a
337 sufficient cube cannot be allocated.
341 A private colormap has more colors, leading to better quality display,
342 but also leads to the dreaded "colormap flashing" effect.
345 @install: %TRUE to set install mode.
348 <!-- ##### FUNCTION gdk_rgb_set_min_colors ##### -->
350 Sets the minimum number of colors for the color cube. Generally,
351 GdkRGB tries to allocate the largest color cube it can. If it can't
352 allocate a color cube at least as large as @min_colors, it installs a
356 @min_colors: The minimum number of colors accepted.
359 <!-- ##### FUNCTION gdk_rgb_get_visual ##### -->
366 <!-- ##### FUNCTION gdk_rgb_get_colormap ##### -->
374 <!-- ##### MACRO gdk_rgb_get_cmap ##### -->
376 Gets the colormap set by GdkRGB. This colormap and the corresponding
377 visual should be used when creating windows that will be drawn in by GdkRGB.
380 @Returns: The #GdkColormap set by GdkRGB.
383 <!-- ##### FUNCTION gdk_rgb_ditherable ##### -->
385 Determines whether the preferred visual is ditherable. This function may be
386 useful for presenting a user interface choice to the user about which
387 dither mode is desired; if the display is not ditherable, it may make
388 sense to gray out or hide the corresponding UI widget.
391 @Returns: %TRUE if the preferred visual is ditherable.
394 <!-- ##### FUNCTION gdk_rgb_colormap_ditherable ##### -->
396 Determines whether the visual associated with @cmap is ditherable. This
397 function may be useful for presenting a user interface choice to the user
398 about which dither mode is desired; if the display is not ditherable, it may
399 make sense to gray out or hide the corresponding UI widget.
402 @cmap: a #GdkColormap
403 @Returns: %TRUE if the visual associated with @cmap is ditherable.
406 <!-- ##### FUNCTION gdk_rgb_set_verbose ##### -->
408 Sets the "verbose" flag. This is generally only useful for debugging.
411 @verbose: %TRUE if verbose messages are desired.