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

   1 <!-- ##### SECTION ./tmpl/from-drawables.sgml:Long_Description ##### -->
   2   <para>
   3     The functions in this section allow you to take the image data
   4     from a GDK drawable and dump it into a #GdkPixbuf.  This can be
   5     used for screenshots and other special effects.  Note that these
   6     operations can be expensive, since the image data has to be
   7     transferred from the X server to the client program and converted.
   8   </para>
   9
  10
  11 <!-- ##### SECTION ./tmpl/from-drawables.sgml:Short_Description ##### -->
  12 Getting parts of a drawable's image data into a pixbuf.
  13
  14
  15 <!-- ##### SECTION ./tmpl/from-drawables.sgml:Title ##### -->
  16 Drawables to Pixbufs
  17
  18
  19 <!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Long_Description ##### -->
  20   <para>
  21     This canvas item displays #GdkPixbuf images.  It handles full
  22     affine transformations in both GDK and antialiased modes, and also
  23     supports the <ulink url="http://www.w3.org">W3C</ulink>'s <ulink
  24     url="http://www.w3.org/Graphics/SVG/">SVG</ulink>-like scaling and
  25     translation semantics for absolute pixel values.
  26   </para>
  27
  28   <para>
  29     #GdkPixbuf structures may be shared among different pixbuf canvas
  30     items; the pixbuf item uses #GdkPixbuf's reference counting
  31     functions for this.
  32   </para>
  33
  34   <refsect2>
  35     <title>Custom Scaling and Translation</title>
  36
  37     <para>
  38       In addition to the normal affine transformations supported by
  39       canvas items, the #GnomeCanvasPixbuf item supports independent
  40       object arguments for scaling and translation.  This is useful
  41       for explicitly setting a size to which the pixbuf's image will
  42       be scaled, and for specifying translation offsets that take
  43       place in the item's local coordinate system.
  44     </para>
  45
  46     <para>
  47       By default, the pixbuf canvas item will attain the size in units
  48       of the #GdkPixbuf it contains.  If a #GnomeCanvasPixbuf is
  49       configured to use a #GdkPixbuf that has a size of 300 by 200
  50       pixels, then the pixbuf item will automatically obtain a size of
  51       300 by 200 units in the item's local coordinate system.  If the
  52       item is transformed with a scaling transformation of (0.5, 2.0),
  53       then the final image size will be of 150 by 400 pixels.
  54     </para>
  55
  56     <para>
  57       To set custom width and height values, you must set the <link
  58       linkend="GnomeCanvasPixbuf--width-set">width_set</link> or <link
  59       linkend="GnomeCanvasPixbuf--height-set">height_set</link>
  60       arguments to %TRUE, and then set the <link
  61       linkend="GnomeCanvasPixbuf--width">width</link> or <link
  62       linkend="GnomeCanvasPixbuf--height">height</link> arguments to
  63       the desired values.  The former two arguments control whether
  64       the latter two are used when computing the final image's size;
  65       they are both %FALSE by default so that the pixbuf item will
  66       attain a size in units equal to the size in pixels of the
  67       #GdkPixbuf that the item contains.
  68     </para>
  69
  70     <para>
  71       The custom translation offsets are controlled by the <link
  72       linkend="GnomeCanvasPixbuf--x">x</link> and <link
  73       linkend="GnomeCanvasPixbuf--y">y</link> arguments.  The logical
  74       upper-left vertex of the image will be translated by the
  75       specified distance, aligned with the item's local coordinate
  76       system.
  77     </para>
  78   </refsect2>
  79
  80   <refsect2>
  81     <title>Absolute Pixel Scaling and Translation</title>
  82
  83     <para>
  84       The <ulink url="http://www.w3.org/Graphics/SVG/">Scalable Vector
  85       Graphics</ulink> specification (SVG) of the <ulink
  86       url="http://www.w3.org">World Wide Web Consortium</ulink> also
  87       allows images to be translated and scaled by absolute pixel
  88       values that are independent of an item's normal affine
  89       transformation.
  90     </para>
  91
  92     <para>
  93       Normally, the pixbuf item's translation and scaling arguments
  94       are interpreted in units, so they will be modified by the item's
  95       affine transformation.  The <link
  96       linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>,
  97       <link
  98       linkend="GnomeCanvasPixbuf--height-in-pixels">height_in_pixels</link>,
  99       <link
 100       linkend="GnomeCanvasPixbuf--x-in-pixels">x_in_pixels</link>, and
 101       <link
 102       linkend="GnomeCanvasPixbuf--y-in-pixels">y_in_pixels</link>
 103       object arguments can be used to modify this behavior.  If one of
 104       these arguments is %TRUE, then the corresponding scaling or
 105       translation value will not be affected lengthwise by the pixbuf
 106       item's affine transformation.
 107     </para>
 108
 109     <para>
 110       For example, consider a pixbuf item whose size is (300, 200).
 111       If the item is modified with a scaling transformation of (0.5,
 112       2.0) but the <link
 113       linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
 114       is set to %TRUE, then the item will appear to be (300, 400)
 115       pixels in size.  This means that in this case the item's affine
 116       transformation only applies to the height value, while the width
 117       value is kept in absolute pixels.
 118     </para>
 119
 120     <para>
 121       Likewise, consider a pixbuf item whose (<link
 122       linkend="GnomeCanvasPixbuf--x">x</link>, <link
 123       linkend="GnomeCanvasPixbuf--y">y</link>) arguments are set to
 124       (30, 40).  If the item is then modified by the same scaling
 125       transformation of (0.5, 2.0) but the <link
 126       linkend="GnomeCanvasPixbuf--y-in-pixels">y_in_pixels</link>
 127       argument is set to %TRUE, then the image's upper-left corner
 128       will appear to be at position (15, 40).  In this case, the
 129       affine transformation is applied only to the x offset, while the
 130       y offset is kept in absolute pixels.
 131     </para>
 132
 133     <para>
 134       In short, these arguments control whether a particular dimension
 135       of a pixbuf item is scaled or not in the normal way by the
 136       item's affine transformation.
 137     </para>
 138   </refsect2>
 139
 140   <refsect2>
 141     <title>Resource Management</title>
 142
 143     <para>
 144       When you set the #GdkPixbuf structure that a #GnomeCanvasPixbuf
 145       item will use by setting the <link
 146       linkend="GnomeCanvasPixbuf--pixbuf">pixbuf</link> argument, a
 147       reference count will be added to that #GdkPixbuf structure.
 148       When the pixbuf item no longer needs the #GdkPixbuf structure,
 149       such as when the item is destroyed or when a new pixbuf
 150       structure is passed to it, then the old #GdkPixbuf structure
 151       will be automatically unreferenced.
 152     </para>
 153
 154     <para>
 155       This means that if an application just needs to load a pixbuf
 156       image and set it into a pixbuf canvas item, it can do the
 157       following to &lsquo;forget&rsquo; about the pixbuf structure:
 158
 159       <programlisting>
 160         GdkPixbuf *pixbuf;
 161         GnomeCanvasItem *item;
 162
 163         pixbuf = gdk_pixbuf_new_from_file ("foo.png");
 164         g_assert (pixbuf != NULL);
 165
 166         item = gnome_canvas_item_new (gnome_canvas_root (my_canvas),
 167                                       gnome_canvas_pixbuf_get_type (),
 168                                       "pixbuf", pixbuf,
 169                                       NULL);
 170         gdk_pixbuf_unref (pixbuf);
 171       </programlisting>
 172     </para>
 173
 174     <para>
 175       After this happens, the reference count of the pixbuf structure
 176       will be 1:  the gdk_pixbuf_new_from_file() function creates it
 177       with a reference count of 1, then setting the <link
 178       linkend="GnomeCanvasPixbuf--pixbuf">pixbuf</link> argument of
 179       the #GnomeCanvasPixbuf item increases it to 2, and then it is
 180       decremented to 1 by the call to gdk_pixbuf_unref().  When the
 181       canvas item is destroyed, it will automatically unreference the
 182       pixbuf structure again, causing its reference count to drop to
 183       zero and thus be freed.
 184     </para>
 185   </refsect2>
 186
 187
 188 <!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:See_Also ##### -->
 189   <para>
 190     #GnomeCanvas, #GdkPixbuf
 191   </para>
 192
 193
 194 <!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Short_Description ##### -->
 195 Canvas item to display #GdkPixbuf images.
 196
 197
 198 <!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Title ##### -->
 199 GnomeCanvasPixbuf
 200
 201
 202 <!-- ##### SECTION ./tmpl/rendering.sgml:Long_Description ##### -->
 203   <para>
 204     The &gdk-pixbuf; library provides several convenience functions to
 205     render pixbufs to GDK drawables.  It uses the GdkRGB to render the
 206     image data.
 207   </para>
 208
 209   <para>
 210     At this point there is not a standard alpha channel extension for
 211     the X Window System, so it is not possible to use full opacity
 212     information when painting images to arbitrary drawables.  The
 213     &gdk-pixbuf; convenience functions will threshold the opacity
 214     information to create a bi-level clipping mask (black and white),
 215     and use that to draw the image onto a drawable.
 216   </para>
 217
 218
 219 <!-- ##### SECTION ./tmpl/rendering.sgml:See_Also ##### -->
 220   <para>
 221     GdkRGB
 222   </para>
 223
 224
 225 <!-- ##### SECTION ./tmpl/rendering.sgml:Short_Description ##### -->
 226 Rendering a pixbuf to a GDK drawable.
 227
 228
 229 <!-- ##### SECTION ./tmpl/rendering.sgml:Title ##### -->
 230 Rendering
 231
 232
 233 <!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:Long_Description ##### -->
 234   <para>
 235     The functions in this section allow you to take the image data
 236     from an X drawable and dump it into a #GdkPixbuf.  This can be
 237     used for screenshots and other special effects.  Note that these
 238     operations can be expensive, since the image data has to be
 239     transferred from the X server to the client program and converted.
 240   </para>
 241
 242   <para>
 243     These functions are analogous to those for the Gdk version of
 244     &gdk-pixbuf;.
 245   </para>
 246
 247
 248 <!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:See_Also ##### -->
 249 <para>
 250
 251 </para>
 252
 253
 254 <!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:Short_Description ##### -->
 255 Getting parts of an X drawable's image data into a pixbuf.
 256
 257
 258 <!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:Title ##### -->
 259 X Drawables to Pixbufs
 260
 261
 262 <!-- ##### SECTION ./tmpl/xlib-init.sgml:Long_Description ##### -->
 263   <para>
 264     In addition to the normal Gdk-specific functions, the &gdk-pixbuf;
 265     package provides a small library that lets Xlib-only applications
 266     use #GdkPixbuf structures and render them to X drawables.  The
 267     functions in this section are used to initialize the &gdk-pixbuf;
 268     Xlib library.  This library must be initialized near the beginning
 269     or the program or before calling any of the other &gdk-pixbuf;
 270     Xlib functions; it cannot be initialized automatically since
 271     Xlib-only applications do not call gdk_rgb_init() like GNOME
 272     applications do.
 273   </para>
 274
 275
 276 <!-- ##### SECTION ./tmpl/xlib-init.sgml:See_Also ##### -->
 277   <para>
 278     XlibRGB
 279   </para>
 280
 281
 282 <!-- ##### SECTION ./tmpl/xlib-init.sgml:Short_Description ##### -->
 283 Initializing the &gdk-pixbuf; Xlib library.
 284
 285
 286 <!-- ##### SECTION ./tmpl/xlib-init.sgml:Title ##### -->
 287 &gdk-pixbuf; Xlib initialization
 288
 289
 290 <!-- ##### SECTION ./tmpl/xlib-rendering.sgml:Long_Description ##### -->
 291   <para>
 292     The &gdk-pixbuf; Xlib library provides several convenience
 293     functions to render pixbufs to X drawables.  It uses XlibRGB to
 294     render the image data.
 295   </para>
 296
 297   <para>
 298     These functions are analogous to those for the Gdk version of
 299     &gdk-pixbuf;.
 300   </para>
 301
 302
 303 <!-- ##### SECTION ./tmpl/xlib-rendering.sgml:See_Also ##### -->
 304 <para>
 305
 306 </para>
 307
 308
 309 <!-- ##### SECTION ./tmpl/xlib-rendering.sgml:Short_Description ##### -->
 310 Rendering a pixbuf to an X drawable.
 311
 312
 313 <!-- ##### SECTION ./tmpl/xlib-rendering.sgml:Title ##### -->
 314 Xlib Rendering
 315
 316
 317 <!-- ##### SECTION ./tmpl/xlib-rgb.sgml:Long_Description ##### -->
 318   <para>
 319     The XlibRGB set of functions is a port of the GdkRGB library to
 320     use plain Xlib and X drawables.  You can use these functions to
 321     render RGB buffers into drawables very quickly with high-quality
 322     dithering.
 323   </para>
 324
 325
 326 <!-- ##### SECTION ./tmpl/xlib-rgb.sgml:See_Also ##### -->
 327   <para>
 328     GdkRGB
 329   </para>
 330
 331
 332 <!-- ##### SECTION ./tmpl/xlib-rgb.sgml:Short_Description ##### -->
 333 Functions for rendering RGB buffers to X drawables.
 334
 335
 336 <!-- ##### SECTION ./tmpl/xlib-rgb.sgml:Title ##### -->
 337 XlibRGB
 338
 339
 340 <!-- ##### MACRO GDK_PIXBUF_LOADER ##### -->
 341   <para>
 342     Casts a #GtkObject to a #GdkPixbufLoader.
 343   </para>
 344
 345 @obj: A GTK+ object.
 346
 347 <!-- ##### MACRO GNOME_CANVAS_PIXBUF ##### -->
 348   <para>
 349     Casts a #GtkOjbect to a #GnomeCanvasPixbuf.
 350   </para>
 351
 352 @obj: A GTK+ object.
 353
 354 <!-- ##### STRUCT GdkPixbufFrame ##### -->
 355 <para>
 356  This object describes an individual frame of an animation.
 357 </para>
 358
 359
 360 <!-- ##### ENUM GdkPixbufFrameAction ##### -->
 361 <para>
 362
 363 </para>
 364
 365 @GDK_PIXBUF_FRAME_RETAIN:
 366 @GDK_PIXBUF_FRAME_DISPOSE:
 367 @GDK_PIXBUF_FRAME_REVERT:
 368
 369 <!-- ##### USER_FUNCTION GdkPixbufLastUnref ##### -->
 370   <para>
 371     A function of this type can be used to override the default
 372     operation when a pixbuf loses its last reference, i.e. when
 373     gdk_pixbuf_unref() is called on a #GdkPixbuf structure that has a
 374     reference count of 1.  This function should determine whether to
 375     finalize the pixbuf by calling gdk_pixbuf_finalize(), or whether
 376     to just resume normal execution.  The last unref handler for a
 377     #GdkPixbuf can be set using the
 378     gdk_pixbuf_set_last_unref_handler() function.  By default, pixbufs
 379     will be finalized automatically if no last unref handler has been
 380     defined.
 381   </para>
 382
 383 @pixbuf: The pixbuf that is losing its last reference.
 384 @data: User closure data.
 385
 386 <!-- ##### ARG GnomeCanvasPixbuf:height ##### -->
 387   <para>
 388     Indicates the height the pixbuf will be scaled to.  This argument
 389     will only be used if the <link
 390     linkend="GnomeCanvasPixbuf--height-set">height_set</link> argument
 391     is %TRUE.  Works in the same way as the <link
 392     linkend="GnomeCanvasPixbuf--width">width</link> argument.
 393   </para>
 394
 395
 396 <!-- ##### ARG GnomeCanvasPixbuf:height-in-pixels ##### -->
 397   <para>
 398     Works in the same way as the <link
 399     linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
 400     argument.  The default is %FALSE.
 401   </para>
 402
 403
 404 <!-- ##### ARG GnomeCanvasPixbuf:height-pixels ##### -->
 405 <para>
 406
 407 </para>
 408
 409
 410 <!-- ##### ARG GnomeCanvasPixbuf:height-set ##### -->
 411   <para>
 412     Determines whether the <link
 413     linkend="GnomeCanvasPixbuf--height">height</link> argument is
 414     taken into account when scaling the pixbuf item.  Works in the
 415     same way as the <link
 416     linkend="GnomeCanvasPixbuf--width-set">width_set</link> argument.
 417     The default is %FALSE.
 418   </para>
 419
 420
 421 <!-- ##### ARG GnomeCanvasPixbuf:pixbuf ##### -->
 422   <para>
 423     Contains a pointer to a #GdkPixbuf structure that will be used by
 424     the pixbuf canvas item as an image source.  When a pixbuf is set
 425     its reference count is incremented; if the pixbuf item kept a
 426     pointer to another #GdkPixbuf structure, the reference count of
 427     this structure will be decremented.  Also, the GdkPixbuf's
 428     reference count will automatically be decremented when the
 429     #GnomeCanvasPixbuf item is destroyed.  When a pixbuf is queried, a
 430     reference count will not be added to the return value; you must do
 431     this yourself if you intend to keep the pixbuf structure around.
 432   </para>
 433
 434
 435 <!-- ##### ARG GnomeCanvasPixbuf:width ##### -->
 436   <para>
 437     Indicates the width the pixbuf will be scaled to.  This argument
 438     will only be used if the <link
 439     linkend="GnomeCanvasPixbuf--width-set">width_set</link> argument
 440     is %TRUE.  If the <link
 441     linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
 442     argument is %FALSE, the width will be taken to be in canvas units,
 443     and thus will be scaled along with the canvas item's affine
 444     transformation.  If width_in_pixels is %TRUE, the width will be
 445     taken to be in pixels, and will visually remain a constant size
 446     even if the item's affine transformation changes.
 447   </para>
 448
 449
 450 <!-- ##### ARG GnomeCanvasPixbuf:width-in-pixels ##### -->
 451   <para>
 452     If this argument is %TRUE, then the width of the pixbuf will be
 453     considered to be in pixels, that is, it will not be visually
 454     scaled even if the item's affine transformation changes.  If this
 455     is %FALSE, then the width of the pixbuf will be considered to be
 456     in canvas units, and so will be scaled normally by affine
 457     transformations.  The default is %FALSE.
 458   </para>
 459
 460
 461 <!-- ##### ARG GnomeCanvasPixbuf:width-pixels ##### -->
 462 <para>
 463
 464 </para>
 465
 466
 467 <!-- ##### ARG GnomeCanvasPixbuf:width-set ##### -->
 468   <para>
 469     Determines whether the <link
 470     linkend="GnomeCanvasPixbuf--width">width</link> argument is taken
 471     into account when scaling the pixbuf item.  If this argument is
 472     %FALSE, then the width value of the pixbuf will be used instead.
 473     This argument is %FALSE by default.
 474   </para>
 475
 476
 477 <!-- ##### ARG GnomeCanvasPixbuf:x ##### -->
 478   <para>
 479     Indicates the horizontal translation offset of the pixbuf item's
 480     image.  This offset may not actually appear horizontal, since it
 481     will be affected by the item's affine transformation.  The default
 482     is 0.0.
 483   </para>
 484
 485
 486 <!-- ##### ARG GnomeCanvasPixbuf:x-in-pixels ##### -->
 487   <para>
 488     If this argument is %TRUE, the pixbuf's translation with respect
 489     to its logical origin in item-relative coordinates will be in
 490     pixels, that is, the visible offset will not change even if the
 491     item's affine transformation changes.  If it is %FALSE, the
 492     pixbuf's translation will be taken to be in canvas units, and thus
 493     will change along with the item's affine transformation.  The
 494     default is %FALSE.
 495   </para>
 496
 497
 498 <!-- ##### ARG GnomeCanvasPixbuf:x-pixels ##### -->
 499 <para>
 500
 501 </para>
 502
 503
 504 <!-- ##### ARG GnomeCanvasPixbuf:x-set ##### -->
 505   <para>
 506     Determines whether the <link
 507     linkend="GnomeCanvasPixbuf--x">x</link> argument is used to
 508     translate the pixbuf from its logical origin in item-relative
 509     coordinates.
 510   </para>
 511
 512
 513 <!-- ##### ARG GnomeCanvasPixbuf:y ##### -->
 514   <para>
 515     Indicates the vertical translation offset of the pixbuf item's
 516     image.  Works in the same way as the <link
 517     linkend="GnomeCanvasPixbuf--x">x</link> argument.  The default is
 518     0.0.
 519   </para>
 520
 521
 522 <!-- ##### ARG GnomeCanvasPixbuf:y-in-pixels ##### -->
 523   <para>
 524     Works in the same way as the <link
 525     linkend="GnomeCanvasPixbuf--x-in-pixels">x_in_pixels</link>
 526     argument, but controls whether the <link
 527     linkend="GnomeCanvasPixbuf--y">y</link> translation offset is
 528     scaled or not.  The default is %FALSE.
 529   </para>
 530
 531 <!--
 532 Local variables:
 533 mode: sgml
 534 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
 535 End:
 536 -->
 537
 538
 539 <!-- ##### ARG GnomeCanvasPixbuf:y-pixels ##### -->
 540 <para>
 541
 542 </para>
 543
 544
 545 <!-- ##### ARG GnomeCanvasPixbuf:y-set ##### -->
 546   <para>
 547     Determines whether the <link
 548     linkend="GnomeCanvasPixbuf--y">y</link> argument is used to
 549     translate the pixbuf from its logical origin in item-relative
 550     coordinates.  Works in the same way as the <link
 551     linkend="GnomeCanvasPixbuf--x-set">x_set</link> argument.  The
 552     default is %FALSE.
 553   </para>
 554
 555
 556 <!-- ##### FUNCTION gdk_pixbuf_animation_ref ##### -->
 557 <para>
 558
 559 </para>
 560
 561 @animation:
 562 @Returns:
 563
 564 <!-- ##### FUNCTION gdk_pixbuf_animation_unref ##### -->
 565 <para>
 566
 567 </para>
 568
 569 @animation:
 570
 571 <!-- ##### FUNCTION gdk_pixbuf_ref ##### -->
 572   <para>
 573
 574   </para>
 575
 576 @pixbuf:
 577 @Returns:
 578
 579 <!-- ##### FUNCTION gdk_pixbuf_unref ##### -->
 580 <para>
 581
 582 </para>
 583
 584 @pixbuf:
 585