</p>        </div>      </div>      <div class="SECT2">        <h2 class="SECT2">          <a name="SEC-GDKRGB">RGB Buffers</a>        </h2>        <p>          GDK's GdkRGB module allows you to copy a client-side          buffer of image data to a drawable. If you need to          manipulate images extensively, or copy image data to the          server, this is the correct way to do it. You can't          directly manipulate a <span class="STRUCTNAME">          GdkPixmap</span> because a pixmap is a server-side          object. Copying image data to the server with <tt class=           "FUNCTION">gdk_draw_point()</tt> would be unbelievably          slow, since each point would require a server request          (probably more than one, since you will need to change          the GC for each point).        </p>        <p>          Internally, GdkRGB uses an object called <span class=           "STRUCTNAME">GdkImage</span> to rapidly copy image data          to the server in a single request. This is still somewhat          slow---sizeable data does have to be copied---but GdkRGB          is highly tuned and uses shared memory if the client and          server happen to be on the same machine. So it's the          fastest way to perform this task, given the X          architecture. It will also handle some tricky issues for          you (such as adapting to the colormaps and visuals          available on a given X server).        </p>        <p>          The GdkRGB functions are in a separate header, <tt class=           "FILENAME">gdk/gdkrgb.h</tt>. Before using any GdkRGB          functions, you must initialize the module with <tt class=           "FUNCTION">gdk_rgb_init()</tt> (<a href=           "z132.html#FL-GDKRGB">Figure 24</a>); this sets up the          visual and colormap GdkRGB will use, and some internal          data structures.        </p>        <p>          The drawable you intend to copy the RGB buffer to must          use GdkRGB's visual and colormap. If the drawable is a          part of a widget, the easiest way to ensure this is to          push the GdkRGB visual and colormap when you create the          widget:        </p>        <table border="0" bgcolor="#E0E0E0" width="100%">          <tr>            <td><pre class="PROGRAMLISTING">&#13;  GtkWidget* widget;  gtk_widget_push_visual(gdk_rgb_get_visual());  gtk_widget_push_colormap(gdk_rgb_get_cmap());  widget = gtk_whatever_new();  gtk_widget_pop_visual();  gtk_widget_pop_colormap();&#13;</pre>            </td>          </tr>        </table>        <p>          The current version of GTK+ will be better-behaved if you          do this when creating the toplevel window containing the          drawable, instead of when creating the drawable itself.          However, in principle you can do it for only the          drawable.        </p>        <p>          GdkRGB understands several kinds of image data, including          24- and 32-bit RGB data, 8-bit grayscale, and 8-bit          indexes into an array of RGB values (a client-side <span          class="STRUCTNAME">GdkRgbCmap</span>). This section          describes only the simplest, 24-bit RGB data; this kind          of buffer is rendered with <tt class="FUNCTION">          gdk_draw_rgb_image()</tt>. There are separate functions          to render the other buffer types, but all of them work in          essentially the same way.        </p>        <p>          A 24-bit RGB buffer is a one-dimensional array of bytes;          every byte triplet makes up a pixel (byte 0 is red, byte          1 is green, byte 2 is blue). Three numbers describe the          size of the array and the location of bytes within it:        </p>        <ul>          <li>            <p>              The <i class="FIRSTTERM">width</i> is the number of              pixels (byte triplets) per row of the image.&#13;            </p>          </li>          <li>            <p>              The <i class="FIRSTTERM">height</i> is the number of              rows in the image.&#13;            </p>          </li>          <li>            <p>              The <i class="FIRSTTERM">rowstride</i> is the number              of bytes between rows. That is, for a buffer with              rowstride <i class="EMPHASIS">r</i>, if row <i class=               "EMPHASIS">n</i> starts at array index <i class=               "EMPHASIS">i</i> row <i class="EMPHASIS">n+1</i>              starts at array index <i class="EMPHASIS">i+r</i>.              The rowstride is not necessarily three times the              buffer's width; GdkRGB is faster if both the source              pointer and the rowstride are aligned to a 4-byte              boundary. Specifying a rowstride allows you to use              padding to achieve this.&#13;            </p>          </li>        </ul>        <p>          The <span class="STRUCTNAME">x</span>, <span class=           "STRUCTNAME">y</span>, <span class="STRUCTNAME">          width</span>, and <span class="STRUCTNAME">height</span>          arguments to <tt class="FUNCTION">          gdk_rgb_draw_image()</tt> define a region of the target          drawable to copy the RGB buffer to. The RGB buffer must          have at least <span class="STRUCTNAME">width</span>          columns and <span class="STRUCTNAME">height</span> rows.          Row 0, column 0 of the RGB buffer will be copied to point          (<span class="STRUCTNAME">x</span>, <span class=           "STRUCTNAME">y</span>) on the drawable.        </p>        <p>          Dithering simulates a larger number of colors on displays          with a limited palette. Dithering only matters on 8- and          16-bit displays; 24-bit displays do not have a limited          palette. The <span class="STRUCTNAME">dither</span>          argument is an enumerated type; it has three possible          values:        </p>        <ul>          <li>            <p>              <span class="STRUCTNAME">GDK_RGB_DITHER_NONE</span>              specifies that no dithering will be done. It's              appropriate for text or line drawings with few              colors, but inappropriate for photographic images.              &#13;            </p>          </li>          <li>            <p>              <span class="STRUCTNAME">GDK_RGB_DITHER_NORMAL</span>              specifies dithering on 8-bit displays, but not 16-bit              displays. This is usually the best              quality/performance tradeoff. &#13;            </p>          </li>          <li>            <p>              <span class="STRUCTNAME">GDK_RGB_DITHER_MAX</span>              specifies that dithering will always be done on 8-              and 16-bit displays. The quality gain on 16-bit              displays is probably not worth the speed              penalty.&#13;            </p>          </li>        </ul>        <p>          The <span class="STRUCTNAME">gc</span> argument to <tt          class="FUNCTION">gdk_draw_rgb_image()</tt> is simply          passed through to <tt class="FUNCTION">          gdk_draw_image()</tt> (recall that GdkRGB uses <span          class="STRUCTNAME">GdkImage</span> internally). The <span          class="STRUCTNAME">gc</span> components that make sense          are used (such as the clip mask, drawing function, and          subwindow mode).        </p>        <div class="FIGURE">          <a name="FL-GDKRGB"></a>          <div class="FUNCSYNOPSIS">            <a name="FL-GDKRGB.SYNOPSIS"></a>            <table border="0" bgcolor="#E0E0E0" width="100%">              <tr>                <td><pre class="FUNCSYNOPSISINFO">#include &lt;gdk/gdkrgb.h&gt;</pre>                </td>              </tr>            </table>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">gdk_rgb_init</tt></code>(void);</code>            </p>            <p>              <code><code class="FUNCDEF">GdkColormap* <tt class=               "FUNCTION">gdk_rgb_get_cmap</tt></code>(void);</code>            </p>            <p>              <code><code class="FUNCDEF">GdkVisual* <tt class=               "FUNCTION">              gdk_rgb_get_visual</tt></code>(void);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gdk_draw_rgb_image</tt></code>(GdkDrawable* <tt              class="PARAMETER"><i>drawable</i></tt>, GdkGC* <tt              class="PARAMETER"><i>gc</i></tt>, gint <tt class=               "PARAMETER"><i>x</i></tt>, gint <tt class=              "PARAMETER"><i>y</i></tt>, gint <tt class=              "PARAMETER"><i>width</i></tt>, gint <tt class=               "PARAMETER"><i>height</i></tt>, GdkRGBDither <tt              class="PARAMETER"><i>dither</i></tt>, guchar* <tt              class="PARAMETER"><i>rgb_buf</i></tt>, gint <tt              class="PARAMETER"><i>rowstride</i></tt>);</code>            </p>          </div>          <p>            <b>Figure 24. GdkRGB</b>          </p>        </div>      </div>    </div>    <div class="NAVFOOTER">      <br>      <br>      <table width="100%" border="0" bgcolor="#ffffff" cellpadding=       "1" cellspacing="0">        <tr>          <td width="25%" bgcolor="#ffffff" align="left">            <a href="sec-gc.html"><font color="#0000ff" size="2">            <b>&lt;&lt;&lt; Previous</b></font></a>          </td>          <td width="25%" colspan="2" bgcolor="#ffffff" align=           "center">            <font color="#0000ff" size="2"><b><a href="ggad.html">            <font color="#0000ff" size="2"><b>            Home</b></font></a></b></font>          </td>          <td width="25%" bgcolor="#ffffff" align="right">            <a href="sec-gdkresourcemgmt.html"><font color=            "#0000ff" size="2"><b>Next &gt;&gt;&gt;</b></font></a>          </td>        </tr>        <tr>          <td colspan="2" align="left">            <font color="#000000" size="2"><b>Graphics            Contexts</b></font>          </td>          <td colspan="2" align="right">            <font color="#000000" size="2"><b>GDK Resource            Management</b></font>          </td>        </tr>      </table>    </div>  </body></html>