<refentry id="gdk-GdkRGB">
<refmeta>
<refentrytitle>GdkRGB</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GDK Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>GdkRGB</refname><refpurpose>renders RGB, grayscale, or indexed image data to a <link linkend="GdkDrawable">GdkDrawable</link></refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;gdk/gdk.h&gt;


void        <link linkend="gdk-rgb-init">gdk_rgb_init</link>                    (void);

void        <link linkend="gdk-draw-rgb-image">gdk_draw_rgb_image</link>              (<link linkend="GdkDrawable">GdkDrawable</link> *drawable,
                                             <link linkend="GdkGC">GdkGC</link> *gc,
                                             <link linkend="gint">gint</link> x,
                                             <link linkend="gint">gint</link> y,
                                             <link linkend="gint">gint</link> width,
                                             <link linkend="gint">gint</link> height,
                                             <link linkend="GdkRgbDither">GdkRgbDither</link> dith,
                                             <link linkend="guchar">guchar</link> *rgb_buf,
                                             <link linkend="gint">gint</link> rowstride);
void        <link linkend="gdk-draw-rgb-image-dithalign">gdk_draw_rgb_image_dithalign</link>    (<link linkend="GdkDrawable">GdkDrawable</link> *drawable,
                                             <link linkend="GdkGC">GdkGC</link> *gc,
                                             <link linkend="gint">gint</link> x,
                                             <link linkend="gint">gint</link> y,
                                             <link linkend="gint">gint</link> width,
                                             <link linkend="gint">gint</link> height,
                                             <link linkend="GdkRgbDither">GdkRgbDither</link> dith,
                                             <link linkend="guchar">guchar</link> *rgb_buf,
                                             <link linkend="gint">gint</link> rowstride,
                                             <link linkend="gint">gint</link> xdith,
                                             <link linkend="gint">gint</link> ydith);
void        <link linkend="gdk-draw-indexed-image">gdk_draw_indexed_image</link>          (<link linkend="GdkDrawable">GdkDrawable</link> *drawable,
                                             <link linkend="GdkGC">GdkGC</link> *gc,
                                             <link linkend="gint">gint</link> x,
                                             <link linkend="gint">gint</link> y,
                                             <link linkend="gint">gint</link> width,
                                             <link linkend="gint">gint</link> height,
                                             <link linkend="GdkRgbDither">GdkRgbDither</link> dith,
                                             <link linkend="guchar">guchar</link> *buf,
                                             <link linkend="gint">gint</link> rowstride,
                                             <link linkend="GdkRgbCmap">GdkRgbCmap</link> *cmap);
void        <link linkend="gdk-draw-gray-image">gdk_draw_gray_image</link>             (<link linkend="GdkDrawable">GdkDrawable</link> *drawable,
                                             <link linkend="GdkGC">GdkGC</link> *gc,
                                             <link linkend="gint">gint</link> x,
                                             <link linkend="gint">gint</link> y,
                                             <link linkend="gint">gint</link> width,
                                             <link linkend="gint">gint</link> height,
                                             <link linkend="GdkRgbDither">GdkRgbDither</link> dith,
                                             <link linkend="guchar">guchar</link> *buf,
                                             <link linkend="gint">gint</link> rowstride);
void        <link linkend="gdk-draw-rgb-32-image">gdk_draw_rgb_32_image</link>           (<link linkend="GdkDrawable">GdkDrawable</link> *drawable,
                                             <link linkend="GdkGC">GdkGC</link> *gc,
                                             <link linkend="gint">gint</link> x,
                                             <link linkend="gint">gint</link> y,
                                             <link linkend="gint">gint</link> width,
                                             <link linkend="gint">gint</link> height,
                                             <link linkend="GdkRgbDither">GdkRgbDither</link> dith,
                                             <link linkend="guchar">guchar</link> *buf,
                                             <link linkend="gint">gint</link> rowstride);
void        <link linkend="gdk-draw-rgb-32-image-dithalign">gdk_draw_rgb_32_image_dithalign</link> (<link linkend="GdkDrawable">GdkDrawable</link> *drawable,
                                             <link linkend="GdkGC">GdkGC</link> *gc,
                                             <link linkend="gint">gint</link> x,
                                             <link linkend="gint">gint</link> y,
                                             <link linkend="gint">gint</link> width,
                                             <link linkend="gint">gint</link> height,
                                             <link linkend="GdkRgbDither">GdkRgbDither</link> dith,
                                             <link linkend="guchar">guchar</link> *buf,
                                             <link linkend="gint">gint</link> rowstride,
                                             <link linkend="gint">gint</link> xdith,
                                             <link linkend="gint">gint</link> ydith);
enum        <link linkend="GdkRgbDither">GdkRgbDither</link>;

<link linkend="GdkRgbCmap">GdkRgbCmap</link>* <link linkend="gdk-rgb-cmap-new">gdk_rgb_cmap_new</link>                (<link linkend="guint32">guint32</link> *colors,
                                             <link linkend="gint">gint</link> n_colors);
void        <link linkend="gdk-rgb-cmap-free">gdk_rgb_cmap_free</link>               (<link linkend="GdkRgbCmap">GdkRgbCmap</link> *cmap);
struct      <link linkend="GdkRgbCmap">GdkRgbCmap</link>;

void        <link linkend="gdk-rgb-gc-set-foreground">gdk_rgb_gc_set_foreground</link>       (<link linkend="GdkGC">GdkGC</link> *gc,
                                             <link linkend="guint32">guint32</link> rgb);
void        <link linkend="gdk-rgb-gc-set-background">gdk_rgb_gc_set_background</link>       (<link linkend="GdkGC">GdkGC</link> *gc,
                                             <link linkend="guint32">guint32</link> rgb);
<link linkend="gulong">gulong</link>      <link linkend="gdk-rgb-xpixel-from-rgb">gdk_rgb_xpixel_from_rgb</link>         (<link linkend="guint32">guint32</link> rgb);
void        <link linkend="gdk-rgb-find-color">gdk_rgb_find_color</link>              (<link linkend="GdkColormap">GdkColormap</link> *colormap,
                                             <link linkend="GdkColor">GdkColor</link> *color);

void        <link linkend="gdk-rgb-set-install">gdk_rgb_set_install</link>             (<link linkend="gboolean">gboolean</link> install);
void        <link linkend="gdk-rgb-set-min-colors">gdk_rgb_set_min_colors</link>          (<link linkend="gint">gint</link> min_colors);
<link linkend="GdkVisual">GdkVisual</link>*  <link linkend="gdk-rgb-get-visual">gdk_rgb_get_visual</link>              (void);
<link linkend="GdkColormap">GdkColormap</link>* <link linkend="gdk-rgb-get-colormap">gdk_rgb_get_colormap</link>           (void);
#define     <link linkend="gdk-rgb-get-cmap">gdk_rgb_get_cmap</link>
<link linkend="gboolean">gboolean</link>    <link linkend="gdk-rgb-ditherable">gdk_rgb_ditherable</link>              (void);
void        <link linkend="gdk-rgb-set-verbose">gdk_rgb_set_verbose</link>             (<link linkend="gboolean">gboolean</link> verbose);

</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>

<para>
GdkRGB is a low-level module which renders RGB, grayscale, and indexed
colormap images to a <link linkend="GdkDrawable">GdkDrawable</link>. 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
<link linkend="GdkPixbuf">GdkPixbuf</link> features in place of this module; for example,
<link linkend="gdk-pixbuf-render-to-drawable">gdk_pixbuf_render_to_drawable</link>() uses GdkRGB in its implementation.
</para>

<para>
GdkRGB allocates a color cube to use when rendering images.  You can
set the threshold for installing colormaps with
<link linkend="gdk-rgb-set-min-colors">gdk_rgb_set_min_colors</link>(). The default is 5x5x5 (125). If a colorcube
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 
<literal>gdk_rgb_set_install(TRUE)</literal>.
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.
</para>

<example>
<title>A simple example program using GdkRGB.</title>
<programlisting>
<link linkend="include">include</link> &lt;gtk/gtk.h&gt;

<link linkend="define">define</link> IMAGE_WIDTH	256
<link linkend="define">define</link> 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);

  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  darea = gtk_drawing_area_new (<!>);
  gtk_widget_set_size_request (darea, IMAGE_WIDTH, IMAGE_HEIGHT);
  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);

  return TRUE;
}
</programlisting>
</example>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="gdk-rgb-init">gdk_rgb_init ()</title>
<programlisting>void        gdk_rgb_init                    (void);</programlisting>
<warning>
<para>
<literal>gdk_rgb_init</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
This function no longer does anything at all. It's completely useless
(and harmless).
</para></refsect2>
<refsect2>
<title><anchor id="gdk-draw-rgb-image">gdk_draw_rgb_image ()</title>
<programlisting>void        gdk_draw_rgb_image              (<link linkend="GdkDrawable">GdkDrawable</link> *drawable,
                                             <link linkend="GdkGC">GdkGC</link> *gc,
                                             <link linkend="gint">gint</link> x,
                                             <link linkend="gint">gint</link> y,
                                             <link linkend="gint">gint</link> width,
                                             <link linkend="gint">gint</link> height,
                                             <link linkend="GdkRgbDither">GdkRgbDither</link> dith,
                                             <link linkend="guchar">guchar</link> *rgb_buf,
                                             <link linkend="gint">gint</link> rowstride);</programlisting>
<para>
Draws an RGB image in the drawable. This is the core GdkRGB
function, and likely the only one you will need to use.
</para>

<para>
The <parameter>rowstride</parameter> 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
<parameter>rowstride</parameter> to 0 is allowed.
</para>

<para>
In general, for 0 &lt;= i &lt; <parameter>width</parameter> and 0 &lt;= j &lt; height,
the pixel (x + i, y + j) is colored with red value <parameter>rgb_buf</parameter>[<parameter>j</parameter> *
<parameter>rowstride</parameter> + <parameter>i</parameter> * 3], green value <parameter>rgb_buf</parameter>[<parameter>j</parameter> * <parameter>rowstride</parameter> + <parameter>i</parameter> * 3 +
1], and blue value <parameter>rgb_buf</parameter>[<parameter>j</parameter> * <parameter>rowstride</parameter> + <parameter>i</parameter> * 3 + 2].
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>drawable</parameter>&nbsp;:</entry>
<entry>The <link linkend="GdkDrawable">GdkDrawable</link> to draw in (usually a <link linkend="GdkWindow">GdkWindow</link>).
</entry></row>
<row><entry align="right"><parameter>gc</parameter>&nbsp;:</entry>
<entry>The graphics context (all GDK drawing operations require one; its
contents are ignored).
</entry></row>
<row><entry align="right"><parameter>x</parameter>&nbsp;:</entry>
<entry>The x coordinate of the top-left corner in the drawable.
</entry></row>
<row><entry align="right"><parameter>y</parameter>&nbsp;:</entry>
<entry>The y coordinate of the top-left corner in the drawable.
</entry></row>
<row><entry align="right"><parameter>width</parameter>&nbsp;:</entry>
<entry>The width of the rectangle to be drawn.
</entry></row>
<row><entry align="right"><parameter>height</parameter>&nbsp;:</entry>
<entry>The height of the rectangle to be drawn.
</entry></row>
<row><entry align="right"><parameter>dith</parameter>&nbsp;:</entry>
<entry>A <link linkend="GdkRgbDither">GdkRgbDither</link> value, selecting the desired dither mode.
</entry></row>
<row><entry align="right"><parameter>rgb_buf</parameter>&nbsp;:</entry>
<entry>The pixel data, represented as packed 24-bit data.
</entry></row>
<row><entry align="right"><parameter>rowstride</parameter>&nbsp;:</entry>
<entry>The number of bytes from the start of one row in <parameter>rgb_buf</parameter> to the
start of the next.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-draw-rgb-image-dithalign">gdk_draw_rgb_image_dithalign ()</title>
<programlisting>void        gdk_draw_rgb_image_dithalign    (<link linkend="GdkDrawable">GdkDrawable</link> *drawable,
                                             <link linkend="GdkGC">GdkGC</link> *gc,
                                             <link linkend="gint">gint</link> x,
                                             <link linkend="gint">gint</link> y,
                                             <link linkend="gint">gint</link> width,
                                             <link linkend="gint">gint</link> height,
                                             <link linkend="GdkRgbDither">GdkRgbDither</link> dith,
                                             <link linkend="guchar">guchar</link> *rgb_buf,
                                             <link linkend="gint">gint</link> rowstride,
                                             <link linkend="gint">gint</link> xdith,
                                             <link linkend="gint">gint</link> ydith);</programlisting>
<para>
Draws an RGB image in the drawable, with an adjustment for dither alignment.
</para>

<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 + <parameter>xdith</parameter>, y + <parameter>ydith</parameter>). 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 <parameter>ydith</parameter> = 1.
</para>

<para>
Setting the dither alignment correctly allows updating of small parts
of the screen while avoiding visible "seams" between the different
dither textures.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>drawable</parameter>&nbsp;:</entry>
<entry>The <link linkend="GdkDrawable">GdkDrawable</link> to draw in (usually a <link linkend="GdkWindow">GdkWindow</link>).
</entry></row>
<row><entry align="right"><parameter>gc</parameter>&nbsp;:</entry>
<entry>The graphics context.
</entry></row>
<row><entry align="right"><parameter>x</parameter>&nbsp;:</entry>
<entry>The x coordinate of the top-left corner in the drawable.
</entry></row>
<row><entry align="right"><parameter>y</parameter>&nbsp;:</entry>
<entry>The y coordinate of the top-left corner in the drawable.
</entry></row>
<row><entry align="right"><parameter>width</parameter>&nbsp;:</entry>
<entry>The width of the rectangle to be drawn.
</entry></row>
<row><entry align="right"><parameter>height</parameter>&nbsp;:</entry>
<entry>The height of the rectangle to be drawn.
</entry></row>
<row><entry align="right"><parameter>dith</parameter>&nbsp;:</entry>
<entry>A <link linkend="GdkRgbDither">GdkRgbDither</link> value, selecting the desired dither mode.
</entry></row>
<row><entry align="right"><parameter>rgb_buf</parameter>&nbsp;:</entry>
<entry>The pixel data, represented as packed 24-bit data.
</entry></row>
<row><entry align="right"><parameter>rowstride</parameter>&nbsp;:</entry>
<entry>The number of bytes from the start of one row in <parameter>rgb_buf</parameter> to the
start of the next.
</entry></row>
<row><entry align="right"><parameter>xdith</parameter>&nbsp;:</entry>
<entry>An x offset for dither alignment.
</entry></row>
<row><entry align="right"><parameter>ydith</parameter>&nbsp;:</entry>
<entry>A y offset for dither alignment.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-draw-indexed-image">gdk_draw_indexed_image ()</title>
<programlisting>void        gdk_draw_indexed_image          (<link linkend="GdkDrawable">GdkDrawable</link> *drawable,
                                             <link linkend="GdkGC">GdkGC</link> *gc,
                                             <link linkend="gint">gint</link> x,
                                             <link linkend="gint">gint</link> y,
                                             <link linkend="gint">gint</link> width,
                                             <link linkend="gint">gint</link> height,
                                             <link linkend="GdkRgbDither">GdkRgbDither</link> dith,
                                             <link linkend="guchar">guchar</link> *buf,
                                             <link linkend="gint">gint</link> rowstride,
                                             <link linkend="GdkRgbCmap">GdkRgbCmap</link> *cmap);</programlisting>
<para>
Draws an indexed image in the drawable, using a <link linkend="GdkRgbCmap">GdkRgbCmap</link> to assign
actual colors to the color indices.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>drawable</parameter>&nbsp;:</entry>
<entry>The <link linkend="GdkDrawable">GdkDrawable</link> to draw in (usually a <link linkend="GdkWindow">GdkWindow</link>).
</entry></row>
<row><entry align="right"><parameter>gc</parameter>&nbsp;:</entry>
<entry>The graphics context.
</entry></row>
<row><entry align="right"><parameter>x</parameter>&nbsp;:</entry>
<entry>The x coordinate of the top-left corner in the drawable.
</entry></row>
<row><entry align="right"><parameter>y</parameter>&nbsp;:</entry>
<entry>The y coordinate of the top-left corner in the drawable.
</entry></row>
<row><entry align="right"><parameter>width</parameter>&nbsp;:</entry>
<entry>The width of the rectangle to be drawn.
</entry></row>
<row><entry align="right"><parameter>height</parameter>&nbsp;:</entry>
<entry>The height of the rectangle to be drawn.
</entry></row>
<row><entry align="right"><parameter>dith</parameter>&nbsp;:</entry>
<entry>A <link linkend="GdkRgbDither">GdkRgbDither</link> value, selecting the desired dither mode.
</entry></row>
<row><entry align="right"><parameter>buf</parameter>&nbsp;:</entry>
<entry>The pixel data, represented as 8-bit color indices.
</entry></row>
<row><entry align="right"><parameter>rowstride</parameter>&nbsp;:</entry>
<entry>The number of bytes from the start of one row in <parameter>buf</parameter> to the
start of the next.
</entry></row>
<row><entry align="right"><parameter>cmap</parameter>&nbsp;:</entry>
<entry>The <link linkend="GdkRgbCmap">GdkRgbCmap</link> used to assign colors to the color indices.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-draw-gray-image">gdk_draw_gray_image ()</title>
<programlisting>void        gdk_draw_gray_image             (<link linkend="GdkDrawable">GdkDrawable</link> *drawable,
                                             <link linkend="GdkGC">GdkGC</link> *gc,
                                             <link linkend="gint">gint</link> x,
                                             <link linkend="gint">gint</link> y,
                                             <link linkend="gint">gint</link> width,
                                             <link linkend="gint">gint</link> height,
                                             <link linkend="GdkRgbDither">GdkRgbDither</link> dith,
                                             <link linkend="guchar">guchar</link> *buf,
                                             <link linkend="gint">gint</link> rowstride);</programlisting>
<para>
Draws a grayscale image in the drawable.

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>drawable</parameter>&nbsp;:</entry>
<entry>The <link linkend="GdkDrawable">GdkDrawable</link> to draw in (usually a <link linkend="GdkWindow">GdkWindow</link>).
</entry></row>
<row><entry align="right"><parameter>gc</parameter>&nbsp;:</entry>
<entry>The graphics context.
</entry></row>
<row><entry align="right"><parameter>x</parameter>&nbsp;:</entry>
<entry>The x coordinate of the top-left corner in the drawable.
</entry></row>
<row><entry align="right"><parameter>y</parameter>&nbsp;:</entry>
<entry>The y coordinate of the top-left corner in the drawable.
</entry></row>
<row><entry align="right"><parameter>width</parameter>&nbsp;:</entry>
<entry>The width of the rectangle to be drawn.
</entry></row>
<row><entry align="right"><parameter>height</parameter>&nbsp;:</entry>
<entry>The height of the rectangle to be drawn.
</entry></row>
<row><entry align="right"><parameter>dith</parameter>&nbsp;:</entry>
<entry>A <link linkend="GdkRgbDither">GdkRgbDither</link> value, selecting the desired dither mode.
</entry></row>
<row><entry align="right"><parameter>buf</parameter>&nbsp;:</entry>
<entry>The pixel data, represented as 8-bit gray values.
</entry></row>
<row><entry align="right"><parameter>rowstride</parameter>&nbsp;:</entry>
<entry>The number of bytes from the start of one row in <parameter>buf</parameter> to the
start of the next.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-draw-rgb-32-image">gdk_draw_rgb_32_image ()</title>
<programlisting>void        gdk_draw_rgb_32_image           (<link linkend="GdkDrawable">GdkDrawable</link> *drawable,
                                             <link linkend="GdkGC">GdkGC</link> *gc,
                                             <link linkend="gint">gint</link> x,
                                             <link linkend="gint">gint</link> y,
                                             <link linkend="gint">gint</link> width,
                                             <link linkend="gint">gint</link> height,
                                             <link linkend="GdkRgbDither">GdkRgbDither</link> dith,
                                             <link linkend="guchar">guchar</link> *buf,
                                             <link linkend="gint">gint</link> rowstride);</programlisting>
<para>
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>

<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.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>drawable</parameter>&nbsp;:</entry>
<entry>The <link linkend="GdkDrawable">GdkDrawable</link> to draw in (usually a <link linkend="GdkWindow">GdkWindow</link>).
</entry></row>
<row><entry align="right"><parameter>gc</parameter>&nbsp;:</entry>
<entry>The graphics context.
</entry></row>
<row><entry align="right"><parameter>x</parameter>&nbsp;:</entry>
<entry>The x coordinate of the top-left corner in the drawable.
</entry></row>
<row><entry align="right"><parameter>y</parameter>&nbsp;:</entry>
<entry>The y coordinate of the top-left corner in the drawable.
</entry></row>
<row><entry align="right"><parameter>width</parameter>&nbsp;:</entry>
<entry>The width of the rectangle to be drawn.
</entry></row>
<row><entry align="right"><parameter>height</parameter>&nbsp;:</entry>
<entry>The height of the rectangle to be drawn.
</entry></row>
<row><entry align="right"><parameter>dith</parameter>&nbsp;:</entry>
<entry>A <link linkend="GdkRgbDither">GdkRgbDither</link> value, selecting the desired dither mode.
</entry></row>
<row><entry align="right"><parameter>buf</parameter>&nbsp;:</entry>
<entry>The pixel data, represented as padded 32-bit data.
</entry></row>
<row><entry align="right"><parameter>rowstride</parameter>&nbsp;:</entry>
<entry>The number of bytes from the start of one row in <parameter>buf</parameter> to the
start of the next.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-draw-rgb-32-image-dithalign">gdk_draw_rgb_32_image_dithalign ()</title>
<programlisting>void        gdk_draw_rgb_32_image_dithalign (<link linkend="GdkDrawable">GdkDrawable</link> *drawable,
                                             <link linkend="GdkGC">GdkGC</link> *gc,
                                             <link linkend="gint">gint</link> x,
                                             <link linkend="gint">gint</link> y,
                                             <link linkend="gint">gint</link> width,
                                             <link linkend="gint">gint</link> height,
                                             <link linkend="GdkRgbDither">GdkRgbDither</link> dith,
                                             <link linkend="guchar">guchar</link> *buf,
                                             <link linkend="gint">gint</link> rowstride,
                                             <link linkend="gint">gint</link> xdith,
                                             <link linkend="gint">gint</link> ydith);</programlisting>
<para>
Like <link linkend="gdk-draw-rgb-32-image">gdk_draw_rgb_32_image</link>(), but allows you to specify the dither
offsets. See <link linkend="gdk-draw-rgb-image-dithalign">gdk_draw_rgb_image_dithalign</link>() for more details.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>drawable</parameter>&nbsp;:</entry>
<entry> a <link linkend="GdkDrawable">GdkDrawable</link>
</entry></row>
<row><entry align="right"><parameter>gc</parameter>&nbsp;:</entry>
<entry> a <link linkend="GdkGC">GdkGC</link>
</entry></row>
<row><entry align="right"><parameter>x</parameter>&nbsp;:</entry>
<entry> X coordinate on <parameter>drawable</parameter> where image should go
</entry></row>
<row><entry align="right"><parameter>y</parameter>&nbsp;:</entry>
<entry> Y coordinate on <parameter>drawable</parameter> where image should go
</entry></row>
<row><entry align="right"><parameter>width</parameter>&nbsp;:</entry>
<entry> width of area of image to draw
</entry></row>
<row><entry align="right"><parameter>height</parameter>&nbsp;:</entry>
<entry> height of area of image to draw
</entry></row>
<row><entry align="right"><parameter>dith</parameter>&nbsp;:</entry>
<entry> dithering mode
</entry></row>
<row><entry align="right"><parameter>buf</parameter>&nbsp;:</entry>
<entry> RGB image data
</entry></row>
<row><entry align="right"><parameter>rowstride</parameter>&nbsp;:</entry>
<entry> rowstride of RGB image data
</entry></row>
<row><entry align="right"><parameter>xdith</parameter>&nbsp;:</entry>
<entry> X dither offset
</entry></row>
<row><entry align="right"><parameter>ydith</parameter>&nbsp;:</entry>
<entry> Y dither offset
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GdkRgbDither">enum GdkRgbDither</title>
<programlisting>typedef enum
{
  GDK_RGB_DITHER_NONE,
  GDK_RGB_DITHER_NORMAL,
  GDK_RGB_DITHER_MAX
} GdkRgbDither;
</programlisting>
<para>
Selects whether or not GdkRGB applies dithering
to the image on display. There are three values:
</para>

<itemizedlist>

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

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

<listitem>
<para>
<literal>GDK_RGB_DITHER_MAX</literal>: 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.
</para></refsect2>
<refsect2>
<title><anchor id="gdk-rgb-cmap-new">gdk_rgb_cmap_new ()</title>
<programlisting><link linkend="GdkRgbCmap">GdkRgbCmap</link>* gdk_rgb_cmap_new                (<link linkend="guint32">guint32</link> *colors,
                                             <link linkend="gint">gint</link> n_colors);</programlisting>
<para>
Creates a new <link linkend="GdkRgbCmap">GdkRgbCmap</link> structure. The cmap maps color indexes to
RGB colors. If <parameter>n_colors</parameter> is less than 256, then images containing
color values greater than or equal to <parameter>n_colors</parameter> will produce undefined
results, including possibly segfaults.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>colors</parameter>&nbsp;:</entry>
<entry>The colors, represented as 0xRRGGBB integer values.
</entry></row>
<row><entry align="right"><parameter>n_colors</parameter>&nbsp;:</entry>
<entry>The number of colors in the cmap.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>The newly created <link linkend="GdkRgbCmap">GdkRgbCmap</link>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-rgb-cmap-free">gdk_rgb_cmap_free ()</title>
<programlisting>void        gdk_rgb_cmap_free               (<link linkend="GdkRgbCmap">GdkRgbCmap</link> *cmap);</programlisting>
<para>
Frees the memory associated with a <link linkend="GdkRgbCmap">GdkRgbCmap</link> created by <link linkend="gdk-rgb-cmap-new">gdk_rgb_cmap_new</link>().
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>cmap</parameter>&nbsp;:</entry>
<entry>The <link linkend="GdkRgbCmap">GdkRgbCmap</link> to free.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GdkRgbCmap">struct GdkRgbCmap</title>
<programlisting>struct GdkRgbCmap {
  guint32 colors[256];
  gint n_colors;

  /*&lt; private &gt;*/
  GSList *info_list;
};
</programlisting>
<para>
A private data structure which maps color indices to actual RGB
colors. This is used only for <link linkend="gdk-draw-indexed-image">gdk_draw_indexed_image</link>().
</para></refsect2>
<refsect2>
<title><anchor id="gdk-rgb-gc-set-foreground">gdk_rgb_gc_set_foreground ()</title>
<programlisting>void        gdk_rgb_gc_set_foreground       (<link linkend="GdkGC">GdkGC</link> *gc,
                                             <link linkend="guint32">guint32</link> rgb);</programlisting>
<warning>
<para>
<literal>gdk_rgb_gc_set_foreground</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
Sets the foreground color in <parameter>gc</parameter> to the specified color (or the
closest approximation, in the case of limited visuals).
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>gc</parameter>&nbsp;:</entry>
<entry>The <link linkend="GdkGC">GdkGC</link> to modify.
</entry></row>
<row><entry align="right"><parameter>rgb</parameter>&nbsp;:</entry>
<entry>The color, represented as a 0xRRGGBB integer value.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-rgb-gc-set-background">gdk_rgb_gc_set_background ()</title>
<programlisting>void        gdk_rgb_gc_set_background       (<link linkend="GdkGC">GdkGC</link> *gc,
                                             <link linkend="guint32">guint32</link> rgb);</programlisting>
<warning>
<para>
<literal>gdk_rgb_gc_set_background</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
Sets the background color in <parameter>gc</parameter> to the specified color (or the
closest approximation, in the case of limited visuals).
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>gc</parameter>&nbsp;:</entry>
<entry>The <link linkend="GdkGC">GdkGC</link> to modify.
</entry></row>
<row><entry align="right"><parameter>rgb</parameter>&nbsp;:</entry>
<entry>The color, represented as a 0xRRGGBB integer value.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-rgb-xpixel-from-rgb">gdk_rgb_xpixel_from_rgb ()</title>
<programlisting><link linkend="gulong">gulong</link>      gdk_rgb_xpixel_from_rgb         (<link linkend="guint32">guint32</link> rgb);</programlisting>
<warning>
<para>
<literal>gdk_rgb_xpixel_from_rgb</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
Finds the X pixel closest in color to the <parameter>rgb</parameter> color specified. This
value may be used to set the <structfield>pixel</structfield> field of
a <link linkend="GdkColor">GdkColor</link> struct.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>rgb</parameter>&nbsp;:</entry>
<entry>The color, represented as a 0xRRGGBB integer value.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>The X pixel value.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-rgb-find-color">gdk_rgb_find_color ()</title>
<programlisting>void        gdk_rgb_find_color              (<link linkend="GdkColormap">GdkColormap</link> *colormap,
                                             <link linkend="GdkColor">GdkColor</link> *color);</programlisting>
<para>
<parameter>colormap</parameter> should be the colormap for the graphics context and
drawable you're using to draw. If you're drawing to a <link linkend="GtkWidget">GtkWidget</link>,
call <link linkend="gtk-widget-get-colormap">gtk_widget_get_colormap</link>().
</para>
<para>
<parameter>color</parameter> should have its <literal>red</literal>, <literal>green</literal>, and <literal>blue</literal> fields initialized;
<link linkend="gdk-rgb-find-color">gdk_rgb_find_color</link>() will fill in the <literal>pixel</literal> field with the best
matching pixel from a color cube. The color is then ready to be
used for drawing, e.g. you can call <link linkend="gdk-gc-set-foreground">gdk_gc_set_foreground</link>() which
expects <literal>pixel</literal> to be initialized.
</para>
<para>
In many cases, you can avoid this whole issue by calling
<link linkend="gdk-gc-set-rgb-fg-color">gdk_gc_set_rgb_fg_color</link>() or <link linkend="gdk-gc-set-rgb-bg-color">gdk_gc_set_rgb_bg_color</link>(), which
do not expect <literal>pixel</literal> to be initialized in advance. If you use those
functions, there's no need for <link linkend="gdk-rgb-find-color">gdk_rgb_find_color</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>colormap</parameter>&nbsp;:</entry>
<entry> a <link linkend="GdkColormap">GdkColormap</link>
</entry></row>
<row><entry align="right"><parameter>color</parameter>&nbsp;:</entry>
<entry> a <link linkend="GdkColor">GdkColor</link>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-rgb-set-install">gdk_rgb_set_install ()</title>
<programlisting>void        gdk_rgb_set_install             (<link linkend="gboolean">gboolean</link> install);</programlisting>
<para>
If <parameter>install</parameter> is <literal>TRUE</literal>, 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>

<para>
A private colormap has more colors, leading to better quality display,
but also leads to the dreaded "colormap flashing" effect.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>install</parameter>&nbsp;:</entry>
<entry><literal>TRUE</literal> to set install mode.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-rgb-set-min-colors">gdk_rgb_set_min_colors ()</title>
<programlisting>void        gdk_rgb_set_min_colors          (<link linkend="gint">gint</link> min_colors);</programlisting>
<para>
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 <parameter>min_colors</parameter>, it installs a
private colormap.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>min_colors</parameter>&nbsp;:</entry>
<entry>The minimum number of colors accepted.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-rgb-get-visual">gdk_rgb_get_visual ()</title>
<programlisting><link linkend="GdkVisual">GdkVisual</link>*  gdk_rgb_get_visual              (void);</programlisting>
<para>
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.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>The <link linkend="GdkVisual">GdkVisual</link> chosen by GdkRGB.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-rgb-get-colormap">gdk_rgb_get_colormap ()</title>
<programlisting><link linkend="GdkColormap">GdkColormap</link>* gdk_rgb_get_colormap           (void);</programlisting>
<para>
Returns the preferred colormap for rendering image data.  Not a
very useful function; historically, GDK could only render RGB image
data to one colormap and visual, but in the current version it can
render to any colormap and visual. So there's no need to call this
function.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the preferred colormap
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-rgb-get-cmap">gdk_rgb_get_cmap</title>
<programlisting>#define gdk_rgb_get_cmap               gdk_rgb_get_colormap
</programlisting>
<warning>
<para>
<literal>gdk_rgb_get_cmap</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
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.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>The <link linkend="GdkColormap">GdkColormap</link> set by GdkRGB.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-rgb-ditherable">gdk_rgb_ditherable ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gdk_rgb_ditherable              (void);</programlisting>
<para>
Determines 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.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if the visual is ditherable.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-rgb-set-verbose">gdk_rgb_set_verbose ()</title>
<programlisting>void        gdk_rgb_set_verbose             (<link linkend="gboolean">gboolean</link> verbose);</programlisting>
<para>
Sets the "verbose" flag. This is generally only useful for debugging.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>verbose</parameter>&nbsp;:</entry>
<entry><literal>TRUE</literal> if verbose messages are desired.


</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>



<refsect1>
<title>See Also</title>
<para>
<variablelist>

<varlistentry>
<term><link linkend="GdkColor">GdkColor</link></term>
<listitem><para>The underlying GDK mechanism for allocating
colors.</para></listitem>
</varlistentry>

<varlistentry>
<term><link linkend="GdkPixbuf">GdkPixbuf</link> and <link linkend="gdk-pixbuf-render-to-drawable">gdk_pixbuf_render_to_drawable</link>()</term>
<listitem><para>Higher-level image handling.</para></listitem>
</varlistentry>

</variablelist>

</para>
</refsect1>

</refentry>
