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 <!-- ##### SECTION Image ##### -->
  97
  98
  99 <!-- ##### ENUM GdkPixbufError ##### -->
 100 <para>
 101 An error code in the #GDK_PIXBUF_ERROR domain. Many &gdk-pixbuf;
 102 operations can cause errors in this domain, or in the #G_FILE_ERROR
 103 domain.
 104 </para>
 105
 106 @GDK_PIXBUF_ERROR_CORRUPT_IMAGE: An image file was broken somehow.
 107 @GDK_PIXBUF_ERROR_INSUFFICIENT_MEMORY: Not enough memory.
 108 @GDK_PIXBUF_ERROR_BAD_OPTION: A bad option was passed to a pixbuf save module.
 109 @GDK_PIXBUF_ERROR_UNKNOWN_TYPE: Unknown image type.
 110 @GDK_PIXBUF_ERROR_UNSUPPORTED_OPERATION: Don't know how to perform the
 111 given operation on the type of image at hand.
 112 @GDK_PIXBUF_ERROR_FAILED: Generic failure code, something went wrong.
 113
 114 <!-- ##### MACRO GDK_PIXBUF_ERROR ##### -->
 115 <para>
 116 Error domain used for pixbuf operations. Indicates that the error code
 117 will be in the #GdkPixbufError enumeration. See #GError for
 118 information on error domains and error codes.
 119 </para>
 120
 121
 122
 123 <!-- ##### ENUM GdkColorspace ##### -->
 124   <para>
 125     This enumeration defines the color spaces that are supported by
 126     the &gdk-pixbuf; library.  Currently only RGB is supported.
 127   </para>
 128
 129 @GDK_COLORSPACE_RGB: Indicates a red/green/blue additive color space.
 130
 131 <!-- ##### ENUM GdkPixbufAlphaMode ##### -->
 132   <para>
 133     This function can create a
 134     bilevel clipping mask (black and white) and use it while painting
 135     the image.  In the future, when the X Window System gets an alpha
 136     channel extension, it will be possible to do full alpha
 137     compositing onto arbitrary drawables.  For now both cases fall
 138     back to a bilevel clipping mask.
 139   </para>
 140
 141 @GDK_PIXBUF_ALPHA_BILEVEL: A bilevel clipping mask (black and white)
 142 will be created and used to draw the image.  Pixels below 0.5 opacity
 143 will be considered fully transparent, and all others will be
 144 considered fully opaque.
 145 @GDK_PIXBUF_ALPHA_FULL: For now falls back to #GDK_PIXBUF_ALPHA_BILEVEL.
 146 In the future it will do full alpha compositing.
 147
 148 <!-- ##### STRUCT GdkPixbuf ##### -->
 149   <para>
 150     This is the main structure in the &gdk-pixbuf; library.  It is
 151     used to represent images.  It contains information about the
 152     image's pixel data, its color space, bits per sample, width and
 153     height, and the rowstride (the number of bytes between the start of
 154     one row and the start of the next).
 155   </para>
 156
 157
 158 <!-- ##### ARG GdkPixbuf:bits-per-sample ##### -->
 159 <para>
 160
 161 </para>
 162
 163 <!-- ##### ARG GdkPixbuf:colorspace ##### -->
 164 <para>
 165
 166 </para>
 167
 168 <!-- ##### ARG GdkPixbuf:has-alpha ##### -->
 169 <para>
 170
 171 </para>
 172
 173 <!-- ##### ARG GdkPixbuf:height ##### -->
 174 <para>
 175
 176 </para>
 177
 178 <!-- ##### ARG GdkPixbuf:n-channels ##### -->
 179 <para>
 180
 181 </para>
 182
 183 <!-- ##### ARG GdkPixbuf:pixels ##### -->
 184 <para>
 185
 186 </para>
 187
 188 <!-- ##### ARG GdkPixbuf:rowstride ##### -->
 189 <para>
 190
 191 </para>
 192
 193 <!-- ##### ARG GdkPixbuf:width ##### -->
 194 <para>
 195
 196 </para>
 197
 198 <!-- ##### FUNCTION gdk_pixbuf_get_colorspace ##### -->
 199 <para>
 200
 201 </para>
 202
 203 @pixbuf:
 204 @Returns:
 205
 206
 207 <!-- ##### FUNCTION gdk_pixbuf_get_n_channels ##### -->
 208 <para>
 209
 210 </para>
 211
 212 @pixbuf:
 213 @Returns:
 214
 215
 216 <!-- ##### FUNCTION gdk_pixbuf_get_has_alpha ##### -->
 217 <para>
 218
 219 </para>
 220
 221 @pixbuf:
 222 @Returns:
 223
 224
 225 <!-- ##### FUNCTION gdk_pixbuf_get_bits_per_sample ##### -->
 226 <para>
 227
 228 </para>
 229
 230 @pixbuf:
 231 @Returns:
 232
 233
 234 <!-- ##### FUNCTION gdk_pixbuf_get_pixels ##### -->
 235 <para>
 236
 237 </para>
 238
 239 @pixbuf:
 240 @Returns:
 241
 242
 243 <!-- ##### FUNCTION gdk_pixbuf_get_width ##### -->
 244 <para>
 245
 246 </para>
 247
 248 @pixbuf:
 249 @Returns:
 250
 251
 252 <!-- ##### FUNCTION gdk_pixbuf_get_height ##### -->
 253 <para>
 254
 255 </para>
 256
 257 @pixbuf:
 258 @Returns:
 259
 260
 261 <!-- ##### FUNCTION gdk_pixbuf_get_rowstride ##### -->
 262 <para>
 263
 264 </para>
 265
 266 @pixbuf:
 267 @Returns: <!--
 268 Local variables:
 269 mode: sgml
 270 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
 271 End:
 272 -->
 273
 274
 275 <!-- ##### FUNCTION gdk_pixbuf_get_option ##### -->
 276 <para>
 277
 278 </para>
 279
 280 @pixbuf:
 281 @key:
 282 @Returns:
 283
 284
 285 <!--
 286 Local variables:
 287 mode: sgml
 288 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2")
 289 End:
 290 -->
 291
 292