diff options
Diffstat (limited to 'docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml')
| -rw-r--r-- | docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml | 121 |
1 files changed, 121 insertions, 0 deletions
diff --git a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml index 728ae31d1b..7cbef5a28d 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 >= 0 && x < width); + g_assert (y >= 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: +--> |