z132.html

GTK+_ Gnome Application Development

          </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>