gdk-pixbuf.sgml 6.17 KB
Newer Older
1
<!-- ##### SECTION Title ##### -->
2
The GdkPixbuf Structure
3 4

<!-- ##### SECTION Short_Description ##### -->
5
Information that describes an image.
6 7

<!-- ##### SECTION Long_Description ##### -->
8

9
  <para>
10 11 12
    The <structname>GdkPixbuf</structname> structure contains
    information that describes an image in memory.
  </para>
13

14 15 16 17 18 19 20 21 22 23 24 25 26
  <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">
27
      <title>put_pixel(<!-- -->) example</title>
28 29

      <para>
30 31 32 33 34
	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.
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53
      </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);

54 55
  g_assert (x &gt;= 0 &amp;&amp; x &lt; width);
  g_assert (y &gt;= 0 &amp;&amp; y &lt; height);
56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88

  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>

89
<!-- ##### SECTION See_Also ##### -->
90 91
  <para>
  </para>
92

93 94
<!-- ##### ENUM GdkPixbufError ##### -->
<para>
95 96 97
An error code in the #GDK_PIXBUF_ERROR domain. Many &gdk-pixbuf;
operations can cause errors in this domain, or in the #G_FILE_ERROR
domain.
98 99
</para>

100 101
@GDK_PIXBUF_ERROR_CORRUPT_IMAGE: An image file was broken somehow.
@GDK_PIXBUF_ERROR_INSUFFICIENT_MEMORY: Not enough memory.
102
@GDK_PIXBUF_ERROR_BAD_OPTION: A bad option was passed to a pixbuf save module.
103 104 105 106
@GDK_PIXBUF_ERROR_UNKNOWN_TYPE: Unknown image type.
@GDK_PIXBUF_ERROR_UNSUPPORTED_OPERATION: Don't know how to perform the
given operation on the type of image at hand.
@GDK_PIXBUF_ERROR_FAILED: Generic failure code, something went wrong.
107 108 109

<!-- ##### MACRO GDK_PIXBUF_ERROR ##### -->
<para>
110 111 112
Error domain used for pixbuf operations. Indicates that the error code
will be in the #GdkPixbufError enumeration. See #GError for
information on error domains and error codes.
113 114 115 116 117
</para>



<!-- ##### ENUM GdkColorspace ##### -->
118 119 120 121
  <para>
    This enumeration defines the color spaces that are supported by
    the &gdk-pixbuf; library.  Currently only RGB is supported.
  </para>
122

123
@GDK_COLORSPACE_RGB: Indicates a red/green/blue additive color space.
124 125

<!-- ##### ENUM GdkPixbufAlphaMode ##### -->
126 127 128
  <para>
    These values can be passed to
    gdk_pixbuf_render_to_drawable_alpha() to control how the alpha
Matthias Clasen's avatar
Matthias Clasen committed
129
    channel of an image should be handled.  This function can create a
130 131 132 133 134 135 136 137 138 139 140 141 142
    bilevel clipping mask (black and white) and use it while painting
    the image.  In the future, when the X Window System gets an alpha
    channel extension, it will be possible to do full alpha
    compositing onto arbitrary drawables.  For now both cases fall
    back to a bilevel clipping mask.
  </para>

@GDK_PIXBUF_ALPHA_BILEVEL: A bilevel clipping mask (black and white)
will be created and used to draw the image.  Pixels below 0.5 opacity
will be considered fully transparent, and all others will be
considered fully opaque.
@GDK_PIXBUF_ALPHA_FULL: For now falls back to #GDK_PIXBUF_ALPHA_BILEVEL.
In the future it will do full alpha compositing.
143 144

<!-- ##### STRUCT GdkPixbuf ##### -->
145 146 147 148
  <para>
    This is the main structure in the &gdk-pixbuf; library.  It is
    used to represent images.  It contains information about the
    image's pixel data, its color space, bits per sample, width and
149 150
    height, and the rowstride (the number of bytes between the start of
    one row and the start of the next). 
151
  </para>
152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222


<!-- ##### FUNCTION gdk_pixbuf_get_colorspace ##### -->
<para>

</para>

@pixbuf: 
@Returns: 


<!-- ##### FUNCTION gdk_pixbuf_get_n_channels ##### -->
<para>

</para>

@pixbuf: 
@Returns: 


<!-- ##### FUNCTION gdk_pixbuf_get_has_alpha ##### -->
<para>

</para>

@pixbuf: 
@Returns: 


<!-- ##### FUNCTION gdk_pixbuf_get_bits_per_sample ##### -->
<para>

</para>

@pixbuf: 
@Returns: 


<!-- ##### FUNCTION gdk_pixbuf_get_pixels ##### -->
<para>

</para>

@pixbuf: 
@Returns: 


<!-- ##### FUNCTION gdk_pixbuf_get_width ##### -->
<para>

</para>

@pixbuf: 
@Returns: 


<!-- ##### FUNCTION gdk_pixbuf_get_height ##### -->
<para>

</para>

@pixbuf: 
@Returns: 


<!-- ##### FUNCTION gdk_pixbuf_get_rowstride ##### -->
<para>

</para>

@pixbuf: 
223 224 225 226 227 228
@Returns: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->
229 230


231 232 233 234 235 236 237 238 239 240
<!-- ##### FUNCTION gdk_pixbuf_get_option ##### -->
<para>

</para>

@pixbuf: 
@key: 
@Returns: 


241 242 243 244 245 246
<!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2")
End:
-->
247 248