Pileus Git - ~andy/gtk/blob - docs/reference/gdk/tmpl/rgb.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GdkRGB
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Renders RGB, grayscale, or indexed image data to a GdkDrawable
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8
   9 <para>
  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.
  16 </para>
  17
  18 <para>
  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.
  35 </para>
  36
  37 <para>
  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.
  42 </para>
  43
  44 <example>
  45 <title>A simple example program using GdkRGB</title>
  46 <programlisting>
  47 &num;include &lt;gtk/gtk.h&gt;
  48
  49 &num;define IMAGE_WIDTH 256
  50 &num;define IMAGE_HEIGHT        256
  51
  52 guchar rgbbuf[IMAGE_WIDTH * IMAGE_HEIGHT * 3];
  53
  54 gboolean on_darea_expose (GtkWidget *widget,
  55                           GdkEventExpose *event,
  56                           gpointer user_data);
  57
  58 int
  59 main (int argc, char *argv[])
  60 {
  61   GtkWidget *window, *darea;
  62   gint x, y;
  63   guchar *pos;
  64
  65   gtk_init (&amp;argc, &amp;argv);
  66
  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);
  74
  75   /* Set up the RGB buffer. */
  76   pos = rgbbuf;
  77   for (y = 0; y &lt; IMAGE_HEIGHT; y++)
  78     {
  79       for (x = 0; x &lt; IMAGE_WIDTH; x++)
  80         {
  81           *pos++ = x - x % 32;                  /* Red. */
  82           *pos++ = (x / 32) * 4 + y - y % 32;   /* Green. */
  83           *pos++ = y - y % 32;                  /* Blue. */
  84         }
  85     }
  86
  87   gtk_main (<!-- -->);
  88   return 0;
  89 }
  90
  91
  92 gboolean
  93 on_darea_expose (GtkWidget *widget,
  94                  GdkEventExpose *event,
  95                  gpointer user_data)
  96 {
  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);
 100
 101   return TRUE;
 102 }
 103 </programlisting>
 104 </example>
 105
 106 <!-- ##### SECTION See_Also ##### -->
 107 <para>
 108 <variablelist>
 109
 110 <varlistentry>
 111 <term>#GdkColor</term>
 112 <listitem><para>The underlying GDK mechanism for allocating
 113 colors.</para></listitem>
 114 </varlistentry>
 115
 116 <varlistentry>
 117 <term>#GdkPixbuf and gdk_draw_pixbuf()</term>
 118 <listitem><para>Higher-level image handling.</para></listitem>
 119 </varlistentry>
 120
 121 </variablelist>
 122
 123 </para>
 124
 125 <!-- ##### SECTION Stability_Level ##### -->
 126
 127
 128 <!-- ##### SECTION Image ##### -->
 129
 130
 131 <!-- ##### FUNCTION gdk_draw_rgb_image ##### -->
 132 <para>
 133 Draws an RGB image in the drawable. This is the core GdkRGB
 134 function, and likely the only one you will need to use.
 135 </para>
 136
 137 <para>
 138 The @rowstride parameter allows for lines to be aligned more flexibly.
 139 For example, lines may be allocated to begin on 32-bit boundaries,
 140 even if the width of the rectangle is odd. Rowstride is also useful
 141 when drawing a subrectangle of a larger image in memory. Finally, to
 142 replicate the same line a number of times, the trick of setting
 143 @rowstride to 0 is allowed.
 144 </para>
 145
 146 <para>
 147 In general, for 0 &lt;= i &lt; @width and 0 &lt;= j &lt; height,
 148 the pixel (x + i, y + j) is colored with red value @rgb_buf[@j *
 149 @rowstride + @i * 3], green value @rgb_buf[@j * @rowstride + @i * 3 +
 150 1], and blue value @rgb_buf[@j * @rowstride + @i * 3 + 2].
 151 </para>
 152
 153 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
 154 @gc: The graphics context (all GDK drawing operations require one; its
 155 contents are ignored).
 156 @x: The x coordinate of the top-left corner in the drawable.
 157 @y: The y coordinate of the top-left corner in the drawable.
 158 @width: The width of the rectangle to be drawn.
 159 @height: The height of the rectangle to be drawn.
 160 @dith: A #GdkRgbDither value, selecting the desired dither mode.
 161 @rgb_buf: The pixel data, represented as packed 24-bit data.
 162 @rowstride: The number of bytes from the start of one row in @rgb_buf to the
 163 start of the next.
 164
 165
 166 <!-- ##### FUNCTION gdk_draw_rgb_image_dithalign ##### -->
 167 <para>
 168 Draws an RGB image in the drawable, with an adjustment for dither alignment.
 169 </para>
 170
 171 <para>
 172 This function is useful when drawing dithered images into a window
 173 that may be scrolled. Pixel (x, y) will be drawn dithered as if its
 174 actual location is (x + @xdith, y + @ydith). Thus, if you draw an
 175 image into a window using zero dither alignment, then scroll up one
 176 pixel, subsequent draws to the window should have @ydith = 1.
 177 </para>
 178
 179 <para>
 180 Setting the dither alignment correctly allows updating of small parts
 181 of the screen while avoiding visible "seams" between the different
 182 dither textures.
 183 </para>
 184
 185 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
 186 @gc: The graphics context.
 187 @x: The x coordinate of the top-left corner in the drawable.
 188 @y: The y coordinate of the top-left corner in the drawable.
 189 @width: The width of the rectangle to be drawn.
 190 @height: The height of the rectangle to be drawn.
 191 @dith: A #GdkRgbDither value, selecting the desired dither mode.
 192 @rgb_buf: The pixel data, represented as packed 24-bit data.
 193 @rowstride: The number of bytes from the start of one row in @rgb_buf to the
 194 start of the next.
 195 @xdith: An x offset for dither alignment.
 196 @ydith: A y offset for dither alignment.
 197
 198
 199 <!-- ##### FUNCTION gdk_draw_indexed_image ##### -->
 200 <para>
 201 Draws an indexed image in the drawable, using a #GdkRgbCmap to assign
 202 actual colors to the color indices.
 203 </para>
 204
 205 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
 206 @gc: The graphics context.
 207 @x: The x coordinate of the top-left corner in the drawable.
 208 @y: The y coordinate of the top-left corner in the drawable.
 209 @width: The width of the rectangle to be drawn.
 210 @height: The height of the rectangle to be drawn.
 211 @dith: A #GdkRgbDither value, selecting the desired dither mode.
 212 @buf: The pixel data, represented as 8-bit color indices.
 213 @rowstride: The number of bytes from the start of one row in @buf to the
 214 start of the next.
 215 @cmap: The #GdkRgbCmap used to assign colors to the color indices.
 216
 217
 218 <!-- ##### FUNCTION gdk_draw_gray_image ##### -->
 219 <para>
 220 Draws a grayscale image in the drawable.
 221
 222 </para>
 223
 224 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
 225 @gc: The graphics context.
 226 @x: The x coordinate of the top-left corner in the drawable.
 227 @y: The y coordinate of the top-left corner in the drawable.
 228 @width: The width of the rectangle to be drawn.
 229 @height: The height of the rectangle to be drawn.
 230 @dith: A #GdkRgbDither value, selecting the desired dither mode.
 231 @buf: The pixel data, represented as 8-bit gray values.
 232 @rowstride: The number of bytes from the start of one row in @buf to the
 233 start of the next.
 234
 235
 236 <!-- ##### FUNCTION gdk_draw_rgb_32_image ##### -->
 237 <para>
 238 Draws a padded RGB image in the drawable. The image is stored as one
 239 pixel per 32-bit word. It is laid out as a red byte, a green byte, a
 240 blue byte, and a padding byte.
 241 </para>
 242
 243 <para>
 244 It's unlikely that this function will give significant performance
 245 gains in practice. In my experience, the performance gain from having
 246 pixels aligned to 32-bit boundaries is cancelled out by the increased
 247 memory bandwidth.
 248 </para>
 249
 250 @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
 251 @gc: The graphics context.
 252 @x: The x coordinate of the top-left corner in the drawable.
 253 @y: The y coordinate of the top-left corner in the drawable.
 254 @width: The width of the rectangle to be drawn.
 255 @height: The height of the rectangle to be drawn.
 256 @dith: A #GdkRgbDither value, selecting the desired dither mode.
 257 @buf: The pixel data, represented as padded 32-bit data.
 258 @rowstride: The number of bytes from the start of one row in @buf to the
 259 start of the next.
 260
 261
 262 <!-- ##### FUNCTION gdk_draw_rgb_32_image_dithalign ##### -->
 263 <para>
 264
 265 </para>
 266
 267 @drawable:
 268 @gc:
 269 @x:
 270 @y:
 271 @width:
 272 @height:
 273 @dith:
 274 @buf:
 275 @rowstride:
 276 @xdith:
 277 @ydith:
 278
 279
 280 <!-- ##### ENUM GdkRgbDither ##### -->
 281 <para>
 282 Selects whether or not GdkRGB applies dithering
 283 to the image on display.
 284 </para>
 285
 286 <para>
 287 Since GdkRGB currently only handles images with 8 bits per component,
 288 dithering on 24 bit per pixel displays is a moot point.
 289 </para>
 290
 291 @GDK_RGB_DITHER_NONE: Never use dithering.
 292 @GDK_RGB_DITHER_NORMAL: Use dithering in 8 bits per pixel (and below)
 293 only.
 294 @GDK_RGB_DITHER_MAX: Use dithering in 16 bits per pixel and below.
 295
 296 <!-- ##### FUNCTION gdk_rgb_cmap_new ##### -->
 297 <para>
 298 Creates a new #GdkRgbCmap structure. The cmap maps color indexes to
 299 RGB colors. If @n_colors is less than 256, then images containing
 300 color values greater than or equal to @n_colors will produce undefined
 301 results, including possibly segfaults.
 302 </para>
 303
 304 @colors: The colors, represented as 0xRRGGBB integer values.
 305 @n_colors: The number of colors in the cmap.
 306 @Returns: The newly created #GdkRgbCmap
 307
 308
 309 <!-- ##### FUNCTION gdk_rgb_cmap_free ##### -->
 310 <para>
 311 Frees the memory associated with a #GdkRgbCmap created by gdk_rgb_cmap_new().
 312 </para>
 313
 314 @cmap: The #GdkRgbCmap to free.
 315
 316
 317 <!-- ##### STRUCT GdkRgbCmap ##### -->
 318 <para>
 319 A private data structure which maps color indices to actual RGB
 320 colors. This is used only for gdk_draw_indexed_image().
 321 </para>
 322
 323 @colors: The colors, represented as 0xRRGGBB integer values.
 324 @n_colors: The number of colors in the cmap.
 325
 326 <!-- ##### FUNCTION gdk_rgb_find_color ##### -->
 327 <para>
 328
 329 </para>
 330
 331 @colormap:
 332 @color:
 333
 334
 335 <!-- ##### FUNCTION gdk_rgb_set_install ##### -->
 336 <para>
 337 If @install is %TRUE, directs GdkRGB to always install a new "private"
 338 colormap rather than trying to find a best fit with the colors already
 339 allocated. Ordinarily, GdkRGB will install a colormap only if a
 340 sufficient cube cannot be allocated.
 341 </para>
 342
 343 <para>
 344 A private colormap has more colors, leading to better quality display,
 345 but also leads to the dreaded "colormap flashing" effect.
 346 </para>
 347
 348 @install: %TRUE to set install mode.
 349
 350
 351 <!-- ##### FUNCTION gdk_rgb_set_min_colors ##### -->
 352 <para>
 353 Sets the minimum number of colors for the color cube. Generally,
 354 GdkRGB tries to allocate the largest color cube it can. If it can't
 355 allocate a color cube at least as large as @min_colors, it installs a
 356 private colormap.
 357 </para>
 358
 359 @min_colors: The minimum number of colors accepted.
 360
 361
 362 <!-- ##### FUNCTION gdk_rgb_get_visual ##### -->
 363 <para>
 364 </para>
 365
 366 @void:
 367 @Returns:
 368
 369
 370 <!-- ##### FUNCTION gdk_rgb_get_colormap ##### -->
 371 <para>
 372
 373 </para>
 374
 375 @void:
 376 @Returns:
 377
 378
 379 <!-- ##### FUNCTION gdk_rgb_ditherable ##### -->
 380 <para>
 381 Determines whether the preferred visual is ditherable. This function may be
 382 useful for presenting a user interface choice to the user about which
 383 dither mode is desired; if the display is not ditherable, it may make
 384 sense to gray out or hide the corresponding UI widget.
 385 </para>
 386
 387 @void:
 388 @Returns: %TRUE if the preferred visual is ditherable.
 389
 390
 391 <!-- ##### FUNCTION gdk_rgb_colormap_ditherable ##### -->
 392 <para>
 393 Determines whether the visual associated with @cmap is ditherable. This
 394 function may be useful for presenting a user interface choice to the user
 395 about which dither mode is desired; if the display is not ditherable, it may
 396 make sense to gray out or hide the corresponding UI widget.
 397 </para>
 398
 399 @cmap: a #GdkColormap
 400 @Returns: %TRUE if the visual associated with @cmap is ditherable.
 401
 402
 403 <!-- ##### FUNCTION gdk_rgb_set_verbose ##### -->
 404 <para>
 405 Sets the "verbose" flag. This is generally only useful for debugging.
 406 </para>
 407
 408 @verbose: %TRUE if verbose messages are desired.
 409
 410