Pileus Git - ~andy/gtk/blob - docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml

   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     The <structname>GdkPixbuf</structname> structure contains
  11     information that describes an image in memory.
  12   </para>
  13
  14   <section id="image-data">
  15     <title>Image Data</title>
  16
  17     <para>
  18       Image data in a pixbuf is stored in memory in uncompressed,
  19       packed format.  Rows in the image are stored top to bottom, and
  20       in each row pixels are stored from left to right.  There may be
  21       padding at the end of a row.  The "rowstride" value of a pixbuf,
  22       as returned by gdk_pixbuf_get_rowstride(), indicates the number
  23       of bytes between rows.
  24     </para>
  25
  26     <example id="put-pixel">
  27       <title>put_pixel(<!-- -->) example</title>
  28
  29       <para>
  30         The following code illustrates a simple put_pixel(<!-- -->)
  31         function for RGB pixbufs with 8 bits per channel with an alpha
  32         channel.  It is not included in the gdk-pixbuf library for
  33         performance reasons; rather than making several function calls
  34         for each pixel, your own code can take shortcuts.
  35       </para>
  36
  37       <programlisting>
  38 static void
  39 put_pixel (GdkPixbuf *pixbuf, int x, int y, guchar red, guchar green, guchar blue, guchar alpha)
  40 {
  41   int width, height, rowstride, n_channels;
  42   guchar *pixels, *p;
  43
  44   n_channels = gdk_pixbuf_get_n_channels (pixbuf);
  45
  46   g_assert (gdk_pixbuf_get_colorspace (pixbuf) == GDK_COLORSPACE_RGB);
  47   g_assert (gdk_pixbuf_get_bits_per_sample (pixbuf) == 8);
  48   g_assert (gdk_pixbuf_get_has_alpha (pixbuf));
  49   g_assert (n_channels == 4);
  50
  51   width = gdk_pixbuf_get_width (pixbuf);
  52   height = gdk_pixbuf_get_height (pixbuf);
  53
  54   g_assert (x &gt;= 0 &amp;&amp; x &lt; width);
  55   g_assert (y &gt;= 0 &amp;&amp; y &lt; height);
  56
  57   rowstride = gdk_pixbuf_get_rowstride (pixbuf);
  58   pixels = gdk_pixbuf_get_pixels (pixbuf);
  59
  60   p = pixels + y * rowstride + x * n_channels;
  61   p[0] = red;
  62   p[1] = green;
  63   p[2] = blue;
  64   p[3] = alpha;
  65 }
  66       </programlisting>
  67
  68       <para>
  69         This function will not work for pixbufs with images that are
  70         other than 8 bits per sample or channel, but it will work for
  71         most of the pixbufs that GTK+ uses.
  72       </para>
  73     </example>
  74
  75     <note>
  76       <para>
  77         If you are doing memcpy() of raw pixbuf data, note that the
  78         last row in the pixbuf may not be as wide as the full
  79         rowstride, but rather just as wide as the pixel data needs to
  80         be.  That is, it is unsafe to do <literal>memcpy (dest,
  81         pixels, rowstride * height)</literal> to copy a whole pixbuf.
  82         Use gdk_pixbuf_copy() instead, or compute the width in bytes
  83         of the last row as <literal>width * ((n_channels *
  84         bits_per_sample + 7) / 8)</literal>.
  85       </para>
  86     </note>
  87   </section>
  88
  89 <!-- ##### SECTION See_Also ##### -->
  90   <para>
  91   </para>
  92
  93 <!-- ##### SECTION Stability_Level ##### -->
  94
  95
  96 <!-- ##### ENUM GdkPixbufError ##### -->
  97 <para>
  98 An error code in the #GDK_PIXBUF_ERROR domain. Many &gdk-pixbuf;
  99 operations can cause errors in this domain, or in the #G_FILE_ERROR
 100 domain.
 101 </para>
 102
 103 @GDK_PIXBUF_ERROR_CORRUPT_IMAGE: An image file was broken somehow.
 104 @GDK_PIXBUF_ERROR_INSUFFICIENT_MEMORY: Not enough memory.
 105 @GDK_PIXBUF_ERROR_BAD_OPTION: A bad option was passed to a pixbuf save module.
 106 @GDK_PIXBUF_ERROR_UNKNOWN_TYPE: Unknown image type.
 107 @GDK_PIXBUF_ERROR_UNSUPPORTED_OPERATION: Don't know how to perform the
 108 given operation on the type of image at hand.
 109 @GDK_PIXBUF_ERROR_FAILED: Generic failure code, something went wrong.
 110
 111 <!-- ##### MACRO GDK_PIXBUF_ERROR ##### -->
 112 <para>
 113 Error domain used for pixbuf operations. Indicates that the error code
 114 will be in the #GdkPixbufError enumeration. See #GError for
 115 information on error domains and error codes.
 116 </para>
 117
 118
 119
 120 <!-- ##### ENUM GdkColorspace ##### -->
 121   <para>
 122     This enumeration defines the color spaces that are supported by
 123     the &gdk-pixbuf; library.  Currently only RGB is supported.
 124   </para>
 125
 126 @GDK_COLORSPACE_RGB: Indicates a red/green/blue additive color space.
 127
 128 <!-- ##### ENUM GdkPixbufAlphaMode ##### -->
 129   <para>
 130     This function can create a
 131     bilevel clipping mask (black and white) and use it while painting
 132     the image.  In the future, when the X Window System gets an alpha
 133     channel extension, it will be possible to do full alpha
 134     compositing onto arbitrary drawables.  For now both cases fall
 135     back to a bilevel clipping mask.
 136   </para>
 137
 138 @GDK_PIXBUF_ALPHA_BILEVEL: A bilevel clipping mask (black and white)
 139 will be created and used to draw the image.  Pixels below 0.5 opacity
 140 will be considered fully transparent, and all others will be
 141 considered fully opaque.
 142 @GDK_PIXBUF_ALPHA_FULL: For now falls back to #GDK_PIXBUF_ALPHA_BILEVEL.
 143 In the future it will do full alpha compositing.
 144
 145 <!-- ##### STRUCT GdkPixbuf ##### -->
 146   <para>
 147     This is the main structure in the &gdk-pixbuf; library.  It is
 148     used to represent images.  It contains information about the
 149     image's pixel data, its color space, bits per sample, width and
 150     height, and the rowstride (the number of bytes between the start of
 151     one row and the start of the next).
 152   </para>
 153
 154
 155 <!-- ##### ARG GdkPixbuf:bits-per-sample ##### -->
 156 <para>
 157
 158 </para>
 159
 160 <!-- ##### ARG GdkPixbuf:colorspace ##### -->
 161 <para>
 162
 163 </para>
 164
 165 <!-- ##### ARG GdkPixbuf:has-alpha ##### -->
 166 <para>
 167
 168 </para>
 169
 170 <!-- ##### ARG GdkPixbuf:height ##### -->
 171 <para>
 172
 173 </para>
 174
 175 <!-- ##### ARG GdkPixbuf:n-channels ##### -->
 176 <para>
 177
 178 </para>
 179
 180 <!-- ##### ARG GdkPixbuf:pixels ##### -->
 181 <para>
 182
 183 </para>
 184
 185 <!-- ##### ARG GdkPixbuf:rowstride ##### -->
 186 <para>
 187
 188 </para>
 189
 190 <!-- ##### ARG GdkPixbuf:width ##### -->
 191 <para>
 192
 193 </para>
 194
 195 <!-- ##### FUNCTION gdk_pixbuf_get_colorspace ##### -->
 196 <para>
 197
 198 </para>
 199
 200 @pixbuf:
 201 @Returns:
 202
 203
 204 <!-- ##### FUNCTION gdk_pixbuf_get_n_channels ##### -->
 205 <para>
 206
 207 </para>
 208
 209 @pixbuf:
 210 @Returns:
 211
 212
 213 <!-- ##### FUNCTION gdk_pixbuf_get_has_alpha ##### -->
 214 <para>
 215
 216 </para>
 217
 218 @pixbuf:
 219 @Returns:
 220
 221
 222 <!-- ##### FUNCTION gdk_pixbuf_get_bits_per_sample ##### -->
 223 <para>
 224
 225 </para>
 226
 227 @pixbuf:
 228 @Returns:
 229
 230
 231 <!-- ##### FUNCTION gdk_pixbuf_get_pixels ##### -->
 232 <para>
 233
 234 </para>
 235
 236 @pixbuf:
 237 @Returns:
 238
 239
 240 <!-- ##### FUNCTION gdk_pixbuf_get_width ##### -->
 241 <para>
 242
 243 </para>
 244
 245 @pixbuf:
 246 @Returns:
 247
 248
 249 <!-- ##### FUNCTION gdk_pixbuf_get_height ##### -->
 250 <para>
 251
 252 </para>
 253
 254 @pixbuf:
 255 @Returns:
 256
 257
 258 <!-- ##### FUNCTION gdk_pixbuf_get_rowstride ##### -->
 259 <para>
 260
 261 </para>
 262
 263 @pixbuf:
 264 @Returns: <!--
 265 Local variables:
 266 mode: sgml
 267 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
 268 End:
 269 -->
 270
 271
 272 <!-- ##### FUNCTION gdk_pixbuf_get_option ##### -->
 273 <para>
 274
 275 </para>
 276
 277 @pixbuf:
 278 @key:
 279 @Returns:
 280
 281
 282 <!--
 283 Local variables:
 284 mode: sgml
 285 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2")
 286 End:
 287 -->
 288
 289