Added a section on how to compute pixel offsets for

2004-01-06  Federico Mena Quintero  <federico@ximian.com>

* gdk-pixbuf/tmpl/gdk-pixbuf.sgml: Added a section on how to
compute pixel offsets for gdk_pixbuf_get_pixels().

2 files changed, 126 insertions, 0 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index f077eda35..0834d38e8 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -15,6 +15,11 @@ Wed Jan  7 01:26:07 2004  Matthias Clasen  <maclas@gmx.de>
 
 	* gdk-pixbuf/gdk-pixbuf-sections.txt: Add gdk_pixbuf_get_file_info.
 
+2004-01-06  Federico Mena Quintero  <federico@ximian.com>
+
+	* gdk-pixbuf/tmpl/gdk-pixbuf.sgml: Added a section on how to
+	compute pixel offsets for gdk_pixbuf_get_pixels().
+
 Mon Dec 29 01:40:20 2003  Matthias Clasen  <maclas@gmx.de>
 
 	* gtk/gtk-sections.txt: Add gtk_accel_map_{un,}lock_path.
diff --git a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml
index 728ae31d1..7cbef5a28 100644
--- a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml
+++ b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml
@@ -11,6 +11,81 @@ Information that describes an image.
     information that describes an image in memory.
   </para>
 
+  <section id="image-data">
+    <title>Image Data</title>
+
+    <para>
+      Image data in a pixbuf is stored in memory in uncompressed,
+      packed format.  Rows in the image are stored top to bottom, and
+      in each row pixels are stored from left to right.  There may be
+      padding at the end of a row.  The "rowstride" value of a pixbuf,
+      as returned by gdk_pixbuf_get_rowstride(), indicates the number
+      of bytes between rows.
+    </para>
+
+    <example id="put-pixel">
+      <title>put_pixel() example</title>
+
+      <para>
+	The following code illustrates a simple put_pixel() function
+	for RGB pixbufs with 8 bits per channel with an alpha channel.
+	It is not included in the gdk-pixbuf library for performance
+	reasons; rather than making several function calls for each
+	pixel, your own code can take shortcuts.
+      </para>
+
+      <programlisting>
+static void
+put_pixel (GdkPixbuf *pixbuf, int x, int y, guchar red, guchar green, guchar blue, guchar alpha)
+{
+  int width, height, rowstride, n_channels;
+  guchar *pixels, *p;
+
+  n_channels = gdk_pixbuf_get_n_channels (pixbuf);
+
+  g_assert (gdk_pixbuf_get_colorspace (pixbuf) == GDK_COLORSPACE_RGB);
+  g_assert (gdk_pixbuf_get_bits_per_sample (pixbuf) == 8);
+  g_assert (gdk_pixbuf_get_has_alpha (pixbuf));
+  g_assert (n_channels == 4);
+
+  width = gdk_pixbuf_get_width (pixbuf);
+  height = gdk_pixbuf_get_height (pixbuf);
+
+  g_assert (x &gt;= 0 && x < width);
+  g_assert (y &gt;= 0 && y < height);
+
+  rowstride = gdk_pixbuf_get_rowstride (pixbuf);
+  pixels = gdk_pixbuf_get_pixels (pixbuf);
+
+  p = pixels + y * rowstride + x * n_channels;
+  p[0] = red;
+  p[1] = green;
+  p[2] = blue;
+  p[3] = alpha;
+}
+      </programlisting>
+
+      <para>
+	This function will not work for pixbufs with images that are
+	other than 8 bits per sample or channel, but it will work for
+	most of the pixbufs that GTK+ uses.
+      </para>
+    </example>
+
+    <note>
+      <para>
+	If you are doing memcpy() of raw pixbuf data, note that the
+	last row in the pixbuf may not be as wide as the full
+	rowstride, but rather just as wide as the pixel data needs to
+	be.  That is, it is unsafe to do <literal>memcpy (dest,
+	pixels, rowstride * height)</literal> to copy a whole pixbuf.
+	Use gdk_pixbuf_copy() instead, or compute the width in bytes
+	of the last row as <literal>width * ((n_channels *
+	bits_per_sample + 7) / 8)</literal>.
+      </para>
+    </note>
+  </section>
+
 <!-- ##### SECTION See_Also ##### -->
   <para>
   </para>
@@ -76,6 +151,46 @@ In the future it will do full alpha compositing.
   </para>
 
 
+<!-- ##### ARG GdkPixbuf:bits-per-sample ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GdkPixbuf:colorspace ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GdkPixbuf:has-alpha ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GdkPixbuf:height ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GdkPixbuf:n-channels ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GdkPixbuf:pixels ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GdkPixbuf:rowstride ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GdkPixbuf:width ##### -->
+<para>
+
+</para>
+
 <!-- ##### FUNCTION gdk_pixbuf_get_colorspace ##### -->
 <para>
 
@@ -163,3 +278,9 @@ End:
 @Returns: 
 
 
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2")
+End:
+-->