rgb.sgml 13.2 KB
Newer Older
Owen Taylor's avatar
Owen Taylor committed
1 2 3 4
<!-- ##### SECTION Title ##### -->
GdkRGB

<!-- ##### SECTION Short_Description ##### -->
5
renders RGB, grayscale, or indexed image data to a #GdkDrawable
6

7
<!-- ##### SECTION Long_Description ##### -->
8 9

<para>
10 11 12 13 14 15
GdkRgb is a low-level module which renders RGB, grayscale, and indexed
colormap images to a #GdkDrawable. It does this as efficiently as
possible, handling issues such as colormaps, visuals, dithering,
temporary buffers, and so on. Most code should use the higher-level
#GdkPixbuf features in place of this module; for example,
gdk_pixbuf_render_to_drawable() uses GdkRGB in its implementation.
16 17 18
</para>

<para>
19 20 21
GdkRGB allocates a color cube to use when rendering images.  You can
set the threshold for installing colormaps with
gdk_rgb_set_min_colors(). The default is 5x5x5 (125). If a colorcube
22 23 24 25 26 27 28 29 30 31 32 33
of this size or larger can be allocated in the default colormap, then
that's done. Otherwise, GdkRgb creates its own private colormap.
Setting it to 0 means that it always tries to use the default
colormap, and setting it to 216 means that it always creates a private
one if it cannot allocate the 6x6x6 colormap in the default. If you
always want a private colormap (to avoid consuming too many colormap
entries for other apps, say), you can use gdk_rgb_set_install(TRUE).
Setting the value greater than 216 exercises a bug in older versions
of GdkRgb. Note, however, that setting it to 0 doesn't let you get
away with ignoring the colormap and visual - a colormap is always
created in grayscale and direct color modes, and the visual is changed
in cases where a "better" visual than the default is available.
Owen Taylor's avatar
Owen Taylor committed
34 35
</para>

36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57
<example>
<title>A simple example program using GdkRGB.</title>
<programlisting>
#include &lt;gtk/gtk.h&gt;

#define IMAGE_WIDTH	256
#define IMAGE_HEIGHT	256

guchar rgbbuf[IMAGE_WIDTH * IMAGE_HEIGHT * 3];

gboolean on_darea_expose (GtkWidget *widget,
			  GdkEventExpose *event,
			  gpointer user_data);

int
main (int argc, char *argv[])
{
  GtkWidget *window, *darea;
  gint x, y;
  guchar *pos;

  gtk_init (&amp;argc, &amp;argv);
58

59 60
  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  darea = gtk_drawing_area_new ();
61
  gtk_widget_set_usize (darea, IMAGE_WIDTH, IMAGE_HEIGHT);
62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95
  gtk_container_add (GTK_CONTAINER (window), darea);
  gtk_signal_connect (GTK_OBJECT (darea), "expose-event",
                      GTK_SIGNAL_FUNC (on_darea_expose), NULL);
  gtk_widget_show_all (window);

  /* Set up the RGB buffer. */
  pos = rgbbuf;
  for (y = 0; y < IMAGE_HEIGHT; y++)
    {
      for (x = 0; x < IMAGE_WIDTH; x++)
	{
	  *pos++ = x - x % 32;			/* Red. */
	  *pos++ = (x / 32) * 4 + y - y % 32;	/* Green. */
	  *pos++ = y - y % 32;			/* Blue. */
	}
    }

  gtk_main ();
  return 0;
}


gboolean
on_darea_expose (GtkWidget *widget,
		 GdkEventExpose *event,
		 gpointer user_data)
{
  gdk_draw_rgb_image (widget->window, widget->style->fg_gc[GTK_STATE_NORMAL],
		      0, 0, IMAGE_WIDTH, IMAGE_HEIGHT,
		      GDK_RGB_DITHER_MAX, rgbbuf, IMAGE_WIDTH * 3);
}
</programlisting>
</example>

Owen Taylor's avatar
Owen Taylor committed
96 97
<!-- ##### SECTION See_Also ##### -->
<para>
98 99 100 101 102 103 104 105
<variablelist>

<varlistentry>
<term>#GdkColor</term>
<listitem><para>The underlying Gdk mechanism for allocating
colors.</para></listitem>
</varlistentry>

106 107 108 109 110
<varlistentry>
<term>#GdkPixbuf and gdk_pixbuf_render_to_drawable()</term>
<listitem><para>Higher-level image handling.</para></listitem>
</varlistentry>

111
</variablelist>
Owen Taylor's avatar
Owen Taylor committed
112 113 114

</para>

115 116
<!-- ##### FUNCTION gdk_rgb_init ##### -->
<para>
117 118
This function no longer does anything at all. It's completely useless
(and harmless).
119
</para>
Owen Taylor's avatar
Owen Taylor committed
120 121 122 123


<!-- ##### FUNCTION gdk_draw_rgb_image ##### -->
<para>
124
Draws an RGB image in the drawable. This is the core GdkRgb
125
function, and likely the only one you will need to use.
126
</para>
127

128 129 130 131 132 133 134
<para>
The @rowstride parameter allows for lines to be aligned more flexibly.
For example, lines may be allocated to begin on 32-bit boundaries,
even if the width of the rectangle is odd. Rowstride is also useful
when drawing a subrectangle of a larger image in memory. Finally, to
replicate the same line a number of times, the trick of setting
@rowstride to 0 is allowed.
135
</para>
Owen Taylor's avatar
Owen Taylor committed
136

137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154
<para>
In general, for 0 &lt;= i &lt; @width and 0 &lt;= j &lt; height,
the pixel (x + i, y + j) is colored with red value @rgb_buf[@j *
@rowstride + @i * 3], green value @rgb_buf[@j * @rowstride + @i * 3 +
1], and blue value @rgb_buf[@j * @rowstride + @i * 3 + 2].
</para>

@drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
@gc: The graphics context (all Gdk drawing operations require one; its
contents are ignored).
@x: The x coordinate of the top-left corner in the drawable.
@y: The y coordinate of the top-left corner in the drawable.
@width: The width of the rectangle to be drawn.
@height: The height of the rectangle to be drawn.
@dith: A #GdkRgbDither value, selecting the desired dither mode.
@rgb_buf: The pixel data, represented as packed 24-bit data.
@rowstride: The number of bytes from the start of one row in @rgb_buf to the
start of the next.
Owen Taylor's avatar
Owen Taylor committed
155 156


Damon Chaplin's avatar
Damon Chaplin committed
157 158
<!-- ##### FUNCTION gdk_draw_rgb_image_dithalign ##### -->
<para>
159 160
Draws an RGB image in the drawable, with an adjustment for dither alignment.
</para>
Damon Chaplin's avatar
Damon Chaplin committed
161

162 163 164 165 166 167
<para>
This function is useful when drawing dithered images into a window
that may be scrolled. Pixel (x, y) will be drawn dithered as if its
actual location is (x + @xdith, y + @ydith). Thus, if you draw an
image into a window using zero dither alignment, then scroll up one
pixel, subsequent draws to the window should have @ydith = 1.
Damon Chaplin's avatar
Damon Chaplin committed
168 169
</para>

170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187
<para>
Setting the dither alignment correctly allows updating of small parts
of the screen while avoiding visible "seams" between the different
dither textures.
</para>

@drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
@gc: The graphics context.
@x: The x coordinate of the top-left corner in the drawable.
@y: The y coordinate of the top-left corner in the drawable.
@width: The width of the rectangle to be drawn.
@height: The height of the rectangle to be drawn.
@dith: A #GdkRgbDither value, selecting the desired dither mode.
@rgb_buf: The pixel data, represented as packed 24-bit data.
@rowstride: The number of bytes from the start of one row in @rgb_buf to the
start of the next.
@xdith: An x offset for dither alignment.
@ydith: A y offset for dither alignment.
Damon Chaplin's avatar
Damon Chaplin committed
188 189


Owen Taylor's avatar
Owen Taylor committed
190 191
<!-- ##### FUNCTION gdk_draw_indexed_image ##### -->
<para>
192 193
Draws an indexed image in the drawable, using a #GdkRgbCmap to assign
actual colors to the color indices.
Owen Taylor's avatar
Owen Taylor committed
194 195
</para>

196 197 198 199 200 201 202 203 204 205 206
@drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
@gc: The graphics context.
@x: The x coordinate of the top-left corner in the drawable.
@y: The y coordinate of the top-left corner in the drawable.
@width: The width of the rectangle to be drawn.
@height: The height of the rectangle to be drawn.
@dith: A #GdkRgbDither value, selecting the desired dither mode.
@buf: The pixel data, represented as 8-bit color indices.
@rowstride: The number of bytes from the start of one row in @buf to the
start of the next.
@cmap: The #GdkRgbCmap used to assign colors to the color indices.
Owen Taylor's avatar
Owen Taylor committed
207 208 209 210


<!-- ##### FUNCTION gdk_draw_gray_image ##### -->
<para>
211
Draws a grayscale image in the drawable.
Owen Taylor's avatar
Owen Taylor committed
212 213 214

</para>

215 216 217 218 219 220 221 222 223 224
@drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
@gc: The graphics context.
@x: The x coordinate of the top-left corner in the drawable.
@y: The y coordinate of the top-left corner in the drawable.
@width: The width of the rectangle to be drawn.
@height: The height of the rectangle to be drawn.
@dith: A #GdkRgbDither value, selecting the desired dither mode.
@buf: The pixel data, represented as 8-bit gray values.
@rowstride: The number of bytes from the start of one row in @buf to the
start of the next.
Owen Taylor's avatar
Owen Taylor committed
225 226 227 228


<!-- ##### FUNCTION gdk_draw_rgb_32_image ##### -->
<para>
229 230 231 232
Draws a padded RGB image in the drawable. The image is stored as one
pixel per 32-bit word. It is laid out as a red byte, a green byte, a
blue byte, and a padding byte.
</para>
Owen Taylor's avatar
Owen Taylor committed
233

234 235 236 237 238
<para>
It's unlikely that this function will give significant performance
gains in practice. In my experience, the performance gain from having
pixels aligned to 32-bit boundaries is cancelled out by the increased
memory bandwidth.
Owen Taylor's avatar
Owen Taylor committed
239 240
</para>

241 242 243 244 245 246 247 248 249 250
@drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
@gc: The graphics context.
@x: The x coordinate of the top-left corner in the drawable.
@y: The y coordinate of the top-left corner in the drawable.
@width: The width of the rectangle to be drawn.
@height: The height of the rectangle to be drawn.
@dith: A #GdkRgbDither value, selecting the desired dither mode.
@buf: The pixel data, represented as padded 32-bit data.
@rowstride: The number of bytes from the start of one row in @buf to the
start of the next.
Owen Taylor's avatar
Owen Taylor committed
251 252


253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270
<!-- ##### FUNCTION gdk_draw_rgb_32_image_dithalign ##### -->
<para>

</para>

@drawable: 
@gc: 
@x: 
@y: 
@width: 
@height: 
@dith: 
@buf: 
@rowstride: 
@xdith: 
@ydith: 


Damon Chaplin's avatar
Damon Chaplin committed
271
<!-- ##### ENUM GdkRgbDither ##### -->
Owen Taylor's avatar
Owen Taylor committed
272
<para>
Damon Chaplin's avatar
Damon Chaplin committed
273

274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303
Selects whether or not GdkRgb applies dithering
to the image on display. There are three values:
</para>

<itemizedlist>

<listitem>
<para>
%GDK_RGB_DITHER_NONE: Never use dithering.
</para>
</listitem>

<listitem>
<para>
%GDK_RGB_DITHER_NORMAL: Use dithering in 8 bits per pixel (and below)
only.
</para>
</listitem>

<listitem>
<para>
%GDK_RGB_DITHER_MAX: Use dithering in 16 bits per pixel and below.
</para>
</listitem>

</itemizedlist>

<para>
Since GdkRgb currently only handles images with 8 bits per component,
dithering on 24 bit per pixel displays is a moot point.
Owen Taylor's avatar
Owen Taylor committed
304 305
</para>

Damon Chaplin's avatar
Damon Chaplin committed
306 307 308 309 310 311
@GDK_RGB_DITHER_NONE: 
@GDK_RGB_DITHER_NORMAL: 
@GDK_RGB_DITHER_MAX: 

<!-- ##### FUNCTION gdk_rgb_cmap_new ##### -->
<para>
312 313 314 315
Creates a new #GdkRgbCmap structure. The cmap maps color indexes to
RGB colors. If @n_colors is less than 256, then images containing
color values greater than or equal to @n_colors will produce undefined
results, including possibly segfaults.
Damon Chaplin's avatar
Damon Chaplin committed
316 317
</para>

318 319 320
@colors: The colors, represented as 0xRRGGBB integer values.
@n_colors: The number of colors in the cmap.
@Returns: The newly created #GdkRgbCmap
Damon Chaplin's avatar
Damon Chaplin committed
321 322 323 324


<!-- ##### FUNCTION gdk_rgb_cmap_free ##### -->
<para>
325
Frees the memory associated with a #GdkRgbCmap created by gdk_rgb_cmap_new().
Damon Chaplin's avatar
Damon Chaplin committed
326 327
</para>

328
@cmap: The #GdkRgbCmap to free.
Damon Chaplin's avatar
Damon Chaplin committed
329 330 331 332


<!-- ##### STRUCT GdkRgbCmap ##### -->
<para>
333 334
A private data structure which maps color indices to actual RGB
colors. This is used only for gdk_draw_indexed_image().
Damon Chaplin's avatar
Damon Chaplin committed
335 336 337
</para>

@colors: 
338
@n_colors: 
Damon Chaplin's avatar
Damon Chaplin committed
339 340 341

<!-- ##### FUNCTION gdk_rgb_gc_set_foreground ##### -->
<para>
342 343
Sets the foreground color in @gc to the specified color (or the
closest approximation, in the case of limited visuals).
Damon Chaplin's avatar
Damon Chaplin committed
344 345
</para>

346 347
@gc: The #GdkGC to modify.
@rgb: The color, represented as a 0xRRGGBB integer value.
Owen Taylor's avatar
Owen Taylor committed
348 349


Damon Chaplin's avatar
Damon Chaplin committed
350
<!-- ##### FUNCTION gdk_rgb_gc_set_background ##### -->
Owen Taylor's avatar
Owen Taylor committed
351
<para>
352 353
Sets the background color in @gc to the specified color (or the
closest approximation, in the case of limited visuals).
Owen Taylor's avatar
Owen Taylor committed
354 355
</para>

356 357
@gc: The #GdkGC to modify.
@rgb: The color, represented as a 0xRRGGBB integer value.
Owen Taylor's avatar
Owen Taylor committed
358 359


Damon Chaplin's avatar
Damon Chaplin committed
360
<!-- ##### FUNCTION gdk_rgb_xpixel_from_rgb ##### -->
Owen Taylor's avatar
Owen Taylor committed
361
<para>
362 363 364
Finds the X pixel closest in color to the @rgb color specified. This
value may be used to set the <structfield>pixel</structfield> field of
a #GdkColor struct.
Owen Taylor's avatar
Owen Taylor committed
365 366
</para>

367 368
@rgb: The color, represented as a 0xRRGGBB integer value.
@Returns: The X pixel value.
Owen Taylor's avatar
Owen Taylor committed
369 370


371 372 373 374 375 376 377 378 379
<!-- ##### FUNCTION gdk_rgb_find_color ##### -->
<para>

</para>

@colormap: 
@color: 


Owen Taylor's avatar
Owen Taylor committed
380 381
<!-- ##### FUNCTION gdk_rgb_set_install ##### -->
<para>
382 383 384 385 386
If @install is TRUE, directs GdkRgb to always install a new "private"
colormap rather than trying to find a best fit with the colors already
allocated. Ordinarily, GdkRgb will install a colormap only if a
sufficient cube cannot be allocated.
</para>
Owen Taylor's avatar
Owen Taylor committed
387

388 389 390
<para>
A private colormap has more colors, leading to better quality display,
but also leads to the dreaded "colormap flashing" effect.
Owen Taylor's avatar
Owen Taylor committed
391 392
</para>

393
@install: TRUE to set install mode.
Owen Taylor's avatar
Owen Taylor committed
394 395 396 397


<!-- ##### FUNCTION gdk_rgb_set_min_colors ##### -->
<para>
398 399 400 401
Sets the minimum number of colors for the color cube. Generally,
GdkRgb tries to allocate the largest color cube it can. If it can't
allocate a color cube at least as large as @min_colors, it installs a
private colormap.
Owen Taylor's avatar
Owen Taylor committed
402 403
</para>

404
@min_colors: The minimum number of colors accepted.
Owen Taylor's avatar
Owen Taylor committed
405 406 407 408


<!-- ##### FUNCTION gdk_rgb_get_visual ##### -->
<para>
409 410 411 412 413
Gets a "preferred visual" chosen by GdkRgb. In previous versions of
GDK, this was the only visual GdkRgb could use for rendering. In
current versions, it's simply the visual GdkRgb would have chosen as 
the optimal one in those previous versions. GdkRgb can now render to 
drawables with any visual.
Owen Taylor's avatar
Owen Taylor committed
414 415
</para>

416
@Returns: The #GdkVisual chosen by GdkRgb.
Owen Taylor's avatar
Owen Taylor committed
417 418


419 420 421 422 423 424 425 426 427
<!-- ##### FUNCTION gdk_rgb_get_colormap ##### -->
<para>

</para>

@Returns: 


<!-- ##### MACRO gdk_rgb_get_cmap ##### -->
Owen Taylor's avatar
Owen Taylor committed
428
<para>
429 430
Gets the colormap set by GdkRgb. This colormap and the corresponding
visual should be used when creating windows that will be drawn in by GdkRgb.
Owen Taylor's avatar
Owen Taylor committed
431 432
</para>

433
@Returns: The #GdkColormap set by GdkRgb.
Damon Chaplin's avatar
Damon Chaplin committed
434 435 436 437


<!-- ##### FUNCTION gdk_rgb_ditherable ##### -->
<para>
438 439 440 441
Determine whether the visual is ditherable. This function may be
useful for presenting a user interface choice to the user about which
dither mode is desired; if the display is not ditherable, it may make
sense to gray out or hide the corresponding UI widget.
Damon Chaplin's avatar
Damon Chaplin committed
442 443
</para>

444
@Returns: TRUE if the visual is ditherable.
Damon Chaplin's avatar
Damon Chaplin committed
445 446 447 448


<!-- ##### FUNCTION gdk_rgb_set_verbose ##### -->
<para>
449
Sets the "verbose" flag. This is generally only useful for debugging.
Damon Chaplin's avatar
Damon Chaplin committed
450 451
</para>

452
@verbose: TRUE if verbose messages are desired.
Owen Taylor's avatar
Owen Taylor committed
453 454