gdk-pixbuf-unused.sgml 20.4 KB
Newer Older
1 2 3 4
<!-- ##### SECTION ./tmpl/from-drawables.sgml:Title ##### -->
Drawables to Pixbufs


5 6 7 8 9 10 11 12 13 14 15 16 17
<!-- ##### USER_FUNCTION GdkPixbufLastUnref ##### -->
  <para>
    A function of this type can be used to override the default
    operation when a pixbuf loses its last reference, i.e. when
    gdk_pixbuf_unref() is called on a #GdkPixbuf structure that has a
    reference count of 1.  This function should determine whether to
    finalize the pixbuf by calling gdk_pixbuf_finalize(), or whether
    to just resume normal execution.  The last unref handler for a
    #GdkPixbuf can be set using the
    gdk_pixbuf_set_last_unref_handler() function.  By default, pixbufs
    will be finalized automatically if no last unref handler has been
    defined.
  </para>
18

19 20
@pixbuf: The pixbuf that is losing its last reference.
@data: User closure data.
21

22
<!-- ##### ARG GnomeCanvasPixbuf:height_pixels ##### -->
23 24 25 26 27
<para>

</para>


28
<!-- ##### SECTION ./tmpl/rendering.sgml:See_Also ##### -->
29
  <para>
30
    GdkRGB
31 32 33
  </para>


Havoc Pennington's avatar
Havoc Pennington committed
34 35 36 37
<!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:Title ##### -->
X Drawables to Pixbufs


38
<!-- ##### FUNCTION gdk_pixbuf_render_pixmap_and_mask ##### -->
39 40 41 42 43
<para>

</para>

@pixbuf: 
44 45 46 47 48 49 50 51 52
@pixmap_return: 
@mask_return: 
@alpha_threshold: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->

Havoc Pennington's avatar
Havoc Pennington committed
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67
<!-- ##### ARG GnomeCanvasPixbuf:width ##### -->
  <para>
    Indicates the width the pixbuf will be scaled to.  This argument
    will only be used if the <link
    linkend="GnomeCanvasPixbuf--width-set">width_set</link> argument
    is %TRUE.  If the <link
    linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
    argument is %FALSE, the width will be taken to be in canvas units,
    and thus will be scaled along with the canvas item's affine
    transformation.  If width_in_pixels is %TRUE, the width will be
    taken to be in pixels, and will visually remain a constant size
    even if the item's affine transformation changes.
  </para>


68
<!-- ##### FUNCTION gdk_pixbuf_render_to_drawable ##### -->
69 70 71 72
<para>

</para>

73 74 75 76 77 78 79 80 81 82 83 84
@pixbuf: 
@drawable: 
@gc: 
@src_x: 
@src_y: 
@dest_x: 
@dest_y: 
@width: 
@height: 
@dither: 
@x_dither: 
@y_dither: 
85

86
<!-- ##### FUNCTION gdk_pixbuf_get_from_drawable ##### -->
87 88 89 90
<para>

</para>

91 92 93 94 95 96 97 98 99 100 101 102 103 104 105
@dest: 
@src: 
@cmap: 
@src_x: 
@src_y: 
@dest_x: 
@dest_y: 
@width: 
@height: 
@Returns: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->
106

Havoc Pennington's avatar
Havoc Pennington committed
107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143
<!-- ##### ARG GnomeCanvasPixbuf:x ##### -->
  <para>
    Indicates the horizontal translation offset of the pixbuf item's
    image.  This offset may not actually appear horizontal, since it
    will be affected by the item's affine transformation.  The default
    is 0.0.
  </para>


<!-- ##### ARG GnomeCanvasPixbuf:y ##### -->
  <para>
    Indicates the vertical translation offset of the pixbuf item's
    image.  Works in the same way as the <link
    linkend="GnomeCanvasPixbuf--x">x</link> argument.  The default is
    0.0.
  </para>


<!-- ##### SECTION ./tmpl/xlib-init.sgml:Short_Description ##### -->
Initializing the &gdk-pixbuf; Xlib library.


<!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:Long_Description ##### -->
  <para>
    The functions in this section allow you to take the image data
    from an X drawable and dump it into a #GdkPixbuf.  This can be
    used for screenshots and other special effects.  Note that these
    operations can be expensive, since the image data has to be
    transferred from the X server to the client program and converted.
  </para>

  <para>
    These functions are analogous to those for the Gdk version of
    &gdk-pixbuf;.
  </para>


144 145 146 147 148 149 150 151
<!-- ##### FUNCTION gdk_pixbuf_new_from_art_pixbuf ##### -->
<para>

</para>

@art_pixbuf: 
@Returns: 

Havoc Pennington's avatar
Havoc Pennington committed
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
<!-- ##### SECTION ./tmpl/xlib-init.sgml:See_Also ##### -->
  <para>
    XlibRGB
  </para>


<!-- ##### ARG GnomeCanvasPixbuf:y_in_pixels ##### -->
  <para>
    Works in the same way as the <link
    linkend="GnomeCanvasPixbuf--x-in-pixels">x_in_pixels</link>
    argument, but controls whether the <link
    linkend="GnomeCanvasPixbuf--y">y</link> translation offset is
    scaled or not.  The default is %FALSE.
  </para>

<!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->


<!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:See_Also ##### -->
  <para>
    #GnomeCanvas, #GdkPixbuf
  </para>


<!-- ##### ARG GnomeCanvasPixbuf:pixbuf ##### -->
  <para>
    Contains a pointer to a #GdkPixbuf structure that will be used by
    the pixbuf canvas item as an image source.  When a pixbuf is set
    its reference count is incremented; if the pixbuf item kept a
    pointer to another #GdkPixbuf structure, the reference count of
    this structure will be decremented.  Also, the GdkPixbuf's
    reference count will automatically be decremented when the
    #GnomeCanvasPixbuf item is destroyed.  When a pixbuf is queried, a
    reference count will not be added to the return value; you must do
    this yourself if you intend to keep the pixbuf structure around.
  </para>


195
<!-- ##### ARG GnomeCanvasPixbuf:y_pixels ##### -->
196 197 198 199 200
<para>

</para>


Havoc Pennington's avatar
Havoc Pennington committed
201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219
<!-- ##### SECTION ./tmpl/xlib-rgb.sgml:See_Also ##### -->
  <para>
    GdkRGB
  </para>


<!-- ##### SECTION ./tmpl/xlib-rendering.sgml:Long_Description ##### -->
  <para>
    The &gdk-pixbuf; Xlib library provides several convenience
    functions to render pixbufs to X drawables.  It uses XlibRGB to
    render the image data.
  </para>

  <para>
    These functions are analogous to those for the Gdk version of
    &gdk-pixbuf;.
  </para>


220 221 222 223
<!-- ##### SECTION ./tmpl/gdk-pixbuf-io.sgml:Short_Description ##### -->



Havoc Pennington's avatar
Havoc Pennington committed
224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239
<!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Short_Description ##### -->
Canvas item to display #GdkPixbuf images.


<!-- ##### ARG GnomeCanvasPixbuf:x_in_pixels ##### -->
  <para>
    If this argument is %TRUE, the pixbuf's translation with respect
    to its logical origin in item-relative coordinates will be in
    pixels, that is, the visible offset will not change even if the
    item's affine transformation changes.  If it is %FALSE, the
    pixbuf's translation will be taken to be in canvas units, and thus
    will change along with the item's affine transformation.  The
    default is %FALSE.
  </para>


240 241 242 243 244 245 246 247 248 249
<!-- ##### SECTION ./tmpl/from-drawables.sgml:Long_Description ##### -->
  <para>
    The functions in this section allow you to take the image data
    from a GDK drawable and dump it into a #GdkPixbuf.  This can be
    used for screenshots and other special effects.  Note that these
    operations can be expensive, since the image data has to be
    transferred from the X server to the client program and converted.
  </para>


Havoc Pennington's avatar
Havoc Pennington committed
250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269
<!-- ##### SECTION ./tmpl/xlib-rgb.sgml:Long_Description ##### -->
  <para>
    The XlibRGB set of functions is a port of the GdkRGB library to
    use plain Xlib and X drawables.  You can use these functions to
    render RGB buffers into drawables very quickly with high-quality
    dithering.
  </para>


<!-- ##### SECTION ./tmpl/xlib-rgb.sgml:Short_Description ##### -->
Functions for rendering RGB buffers to X drawables.


<!-- ##### MACRO GNOME_CANVAS_PIXBUF ##### -->
  <para>
    Casts a #GtkOjbect to a #GnomeCanvasPixbuf.
  </para>

@obj: A GTK+ object.

270
<!-- ##### SECTION ./tmpl/gdk-pixbuf-io.sgml:See_Also ##### -->
271
<para>
272

273
</para>
274 275


Havoc Pennington's avatar
Havoc Pennington committed
276 277 278 279
<!-- ##### SECTION ./tmpl/xlib-rendering.sgml:Short_Description ##### -->
Rendering a pixbuf to an X drawable.


280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296
<!-- ##### FUNCTION gdk_pixbuf_finalize ##### -->
<para>

</para>

@pixbuf: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->

<!-- ##### SECTION ./tmpl/rendering.sgml:Short_Description ##### -->
Rendering a pixbuf to a GDK drawable.


<!-- ##### FUNCTION gdk_pixbuf_set_last_unref_handler ##### -->
297 298 299 300
<para>

</para>

301 302 303
@pixbuf: 
@last_unref_fn: 
@last_unref_fn_data: 
304

305 306 307 308 309 310 311 312 313
<!-- ##### ARG GnomeCanvasPixbuf:x_set ##### -->
  <para>
    Determines whether the <link
    linkend="GnomeCanvasPixbuf--x">x</link> argument is used to
    translate the pixbuf from its logical origin in item-relative
    coordinates.
  </para>


Havoc Pennington's avatar
Havoc Pennington committed
314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338
<!-- ##### ARG GnomeCanvasPixbuf:width_in_pixels ##### -->
  <para>
    If this argument is %TRUE, then the width of the pixbuf will be
    considered to be in pixels, that is, it will not be visually
    scaled even if the item's affine transformation changes.  If this
    is %FALSE, then the width of the pixbuf will be considered to be
    in canvas units, and so will be scaled normally by affine
    transformations.  The default is %FALSE.
  </para>


<!-- ##### SECTION ./tmpl/xlib-init.sgml:Long_Description ##### -->
  <para>
    In addition to the normal Gdk-specific functions, the &gdk-pixbuf;
    package provides a small library that lets Xlib-only applications
    use #GdkPixbuf structures and render them to X drawables.  The
    functions in this section are used to initialize the &gdk-pixbuf;
    Xlib library.  This library must be initialized near the beginning
    or the program or before calling any of the other &gdk-pixbuf;
    Xlib functions; it cannot be initialized automatically since
    Xlib-only applications do not call gdk_rgb_init() like GNOME
    applications do.
  </para>


339
<!-- ##### FUNCTION gdk_pixbuf_get_format ##### -->
340 341 342 343 344
<para>

</para>

@pixbuf: 
345 346
@Returns: 

Havoc Pennington's avatar
Havoc Pennington committed
347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370
<!-- ##### ARG GnomeCanvasPixbuf:height_in_pixels ##### -->
  <para>
    Works in the same way as the <link
    linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
    argument.  The default is %FALSE.
  </para>


<!-- ##### SECTION ./tmpl/xlib-rendering.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### ARG GnomeCanvasPixbuf:width_set ##### -->
  <para>
    Determines whether the <link
    linkend="GnomeCanvasPixbuf--width">width</link> argument is taken
    into account when scaling the pixbuf item.  If this argument is
    %FALSE, then the width value of the pixbuf will be used instead.
    This argument is %FALSE by default.
  </para>


371 372 373 374 375 376 377 378 379 380 381
<!-- ##### FUNCTION gdk_pixbuf_render_to_drawable_alpha ##### -->
<para>

</para>

@pixbuf: 
@drawable: 
@src_x: 
@src_y: 
@dest_x: 
@dest_y: 
382 383
@width: 
@height: 
384 385 386 387 388
@alpha_mode: 
@alpha_threshold: 
@dither: 
@x_dither: 
@y_dither: 
389

Havoc Pennington's avatar
Havoc Pennington committed
390 391 392 393 394 395 396 397 398 399 400 401
<!-- ##### SECTION ./tmpl/xlib-init.sgml:Title ##### -->
&gdk-pixbuf; Xlib initialization


<!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:Short_Description ##### -->
Getting parts of an X drawable's image data into a pixbuf.


<!-- ##### SECTION ./tmpl/xlib-rgb.sgml:Title ##### -->
XlibRGB


402 403 404 405
<!-- ##### ARG GnomeCanvasPixbuf:x_pixels ##### -->
<para>

</para>
406 407


Havoc Pennington's avatar
Havoc Pennington committed
408 409 410 411 412 413 414 415 416 417
<!-- ##### ARG GnomeCanvasPixbuf:height ##### -->
  <para>
    Indicates the height the pixbuf will be scaled to.  This argument
    will only be used if the <link
    linkend="GnomeCanvasPixbuf--height-set">height_set</link> argument
    is %TRUE.  Works in the same way as the <link
    linkend="GnomeCanvasPixbuf--width">width</link> argument.
  </para>


418 419 420 421 422 423
<!-- ##### SECTION ./tmpl/from-drawables.sgml:See_Also ##### -->
  <para>
    gdk_image_get().
  </para>


424 425 426 427 428 429
<!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:See_Also ##### -->
<para>

</para>


Havoc Pennington's avatar
Havoc Pennington committed
430
<!-- ##### STRUCT GdkPixbufAnimationClass ##### -->
Havoc Pennington's avatar
Havoc Pennington committed
431 432 433 434 435
<para>

</para>


436 437 438 439
<!-- ##### SECTION ./tmpl/rendering.sgml:Title ##### -->
Rendering


Havoc Pennington's avatar
Havoc Pennington committed
440 441 442 443
<!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Title ##### -->
GnomeCanvasPixbuf


444 445 446 447 448 449 450
<!-- ##### MACRO GDK_PIXBUF_LOADER ##### -->
  <para>
    Casts a #GtkObject to a #GdkPixbufLoader.
  </para>

@obj: A GTK+ object.

451 452 453 454 455 456 457 458 459 460 461
<!-- ##### ARG GnomeCanvasPixbuf:y_set ##### -->
  <para>
    Determines whether the <link
    linkend="GnomeCanvasPixbuf--y">y</link> argument is used to
    translate the pixbuf from its logical origin in item-relative
    coordinates.  Works in the same way as the <link
    linkend="GnomeCanvasPixbuf--x-set">x_set</link> argument.  The
    default is %FALSE.
  </para>


462 463
<!-- ##### SECTION ./tmpl/rendering.sgml:Long_Description ##### -->
  <para>
Havoc Pennington's avatar
Havoc Pennington committed
464 465 466
    The &gdk-pixbuf; library provides several convenience functions to
    render pixbufs to GDK drawables.  It uses the GdkRGB to render the
    image data.
467
  </para>
468

469 470 471 472
  <para>
    At this point there is not a standard alpha channel extension for
    the X Window System, so it is not possible to use full opacity
    information when painting images to arbitrary drawables.  The
Havoc Pennington's avatar
Havoc Pennington committed
473 474 475
    &gdk-pixbuf; convenience functions will threshold the opacity
    information to create a bi-level clipping mask (black and white),
    and use that to draw the image onto a drawable.
476
  </para>
477

478 479 480 481 482 483 484
  <important>
    <para>
      Since these functions use GdkRGB for rendering, you must
      initialize GdkRGB before using any of them.  You can do this by
      calling gdk_rgb_init() near the beginning of your program.
    </para>
  </important>
485

486 487 488 489 490 491

<!-- ##### SECTION ./tmpl/from-drawables.sgml:Short_Description ##### -->
Getting parts of a drawable's image data into a pixbuf.


<!-- ##### FUNCTION gdk_pixbuf_render_threshold_alpha ##### -->
492 493 494 495
<para>

</para>

496
@pixbuf: 
497 498 499 500 501 502 503 504
@bitmap: 
@src_x: 
@src_y: 
@dest_x: 
@dest_y: 
@width: 
@height: 
@alpha_threshold: 
505

506 507 508 509
<!-- ##### ARG GnomeCanvasPixbuf:width_pixels ##### -->
<para>

</para>
510 511


Havoc Pennington's avatar
Havoc Pennington committed
512
<!-- ##### STRUCT GdkPixbufClass ##### -->
513 514 515 516 517
<para>

</para>


518 519 520 521 522 523
<!-- ##### SECTION ./tmpl/gdk-pixbuf-io.sgml:Long_Description ##### -->
<para>

</para>


Havoc Pennington's avatar
Havoc Pennington committed
524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707
<!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Long_Description ##### -->
  <para>
    This canvas item displays #GdkPixbuf images.  It handles full
    affine transformations in both GDK and antialiased modes, and also
    supports the <ulink url="http://www.w3.org">W3C</ulink>'s <ulink
    url="http://www.w3.org/Graphics/SVG/">SVG</ulink>-like scaling and
    translation semantics for absolute pixel values.
  </para>

  <para>
    #GdkPixbuf structures may be shared among different pixbuf canvas
    items; the pixbuf item uses #GdkPixbuf's reference counting
    functions for this.
  </para>

  <refsect2>
    <title>Custom Scaling and Translation</title>

    <para>
      In addition to the normal affine transformations supported by
      canvas items, the #GnomeCanvasPixbuf item supports independent
      object arguments for scaling and translation.  This is useful
      for explicitly setting a size to which the pixbuf's image will
      be scaled, and for specifying translation offsets that take
      place in the item's local coordinate system.
    </para>

    <para>
      By default, the pixbuf canvas item will attain the size in units
      of the #GdkPixbuf it contains.  If a #GnomeCanvasPixbuf is
      configured to use a #GdkPixbuf that has a size of 300 by 200
      pixels, then the pixbuf item will automatically obtain a size of
      300 by 200 units in the item's local coordinate system.  If the
      item is transformed with a scaling transformation of (0.5, 2.0),
      then the final image size will be of 150 by 400 pixels.
    </para>

    <para>
      To set custom width and height values, you must set the <link
      linkend="GnomeCanvasPixbuf--width-set">width_set</link> or <link
      linkend="GnomeCanvasPixbuf--height-set">height_set</link>
      arguments to %TRUE, and then set the <link
      linkend="GnomeCanvasPixbuf--width">width</link> or <link
      linkend="GnomeCanvasPixbuf--height">height</link> arguments to
      the desired values.  The former two arguments control whether
      the latter two are used when computing the final image's size;
      they are both %FALSE by default so that the pixbuf item will
      attain a size in units equal to the size in pixels of the
      #GdkPixbuf that the item contains.
    </para>

    <para>
      The custom translation offsets are controlled by the <link
      linkend="GnomeCanvasPixbuf--x">x</link> and <link
      linkend="GnomeCanvasPixbuf--y">y</link> arguments.  The logical
      upper-left vertex of the image will be translated by the
      specified distance, aligned with the item's local coordinate
      system.
    </para>
  </refsect2>

  <refsect2>
    <title>Absolute Pixel Scaling and Translation</title>

    <para>
      The <ulink url="http://www.w3.org/Graphics/SVG/">Scalable Vector
      Graphics</ulink> specification (SVG) of the <ulink
      url="http://www.w3.org">World Wide Web Consortium</ulink> also
      allows images to be translated and scaled by absolute pixel
      values that are independent of an item's normal affine
      transformation.
    </para>

    <para>
      Normally, the pixbuf item's translation and scaling arguments
      are interpreted in units, so they will be modified by the item's
      affine transformation.  The <link
      linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>,
      <link
      linkend="GnomeCanvasPixbuf--height-in-pixels">height_in_pixels</link>,
      <link
      linkend="GnomeCanvasPixbuf--x-in-pixels">x_in_pixels</link>, and
      <link
      linkend="GnomeCanvasPixbuf--y-in-pixels">y_in_pixels</link>
      object arguments can be used to modify this behavior.  If one of
      these arguments is %TRUE, then the corresponding scaling or
      translation value will not be affected lengthwise by the pixbuf
      item's affine transformation.
    </para>

    <para>
      For example, consider a pixbuf item whose size is (300, 200).
      If the item is modified with a scaling transformation of (0.5,
      2.0) but the <link
      linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
      is set to %TRUE, then the item will appear to be (300, 400)
      pixels in size.  This means that in this case the item's affine
      transformation only applies to the height value, while the width
      value is kept in absolute pixels.
    </para>

    <para>
      Likewise, consider a pixbuf item whose (<link
      linkend="GnomeCanvasPixbuf--x">x</link>, <link
      linkend="GnomeCanvasPixbuf--y">y</link>) arguments are set to
      (30, 40).  If the item is then modified by the same scaling
      transformation of (0.5, 2.0) but the <link
      linkend="GnomeCanvasPixbuf--y-in-pixels">y_in_pixels</link>
      argument is set to %TRUE, then the image's upper-left corner
      will appear to be at position (15, 40).  In this case, the
      affine transformation is applied only to the x offset, while the
      y offset is kept in absolute pixels.
    </para>

    <para>
      In short, these arguments control whether a particular dimension
      of a pixbuf item is scaled or not in the normal way by the
      item's affine transformation.
    </para>
  </refsect2>

  <refsect2>
    <title>Resource Management</title>

    <para>
      When you set the #GdkPixbuf structure that a #GnomeCanvasPixbuf
      item will use by setting the <link
      linkend="GnomeCanvasPixbuf--pixbuf">pixbuf</link> argument, a
      reference count will be added to that #GdkPixbuf structure.
      When the pixbuf item no longer needs the #GdkPixbuf structure,
      such as when the item is destroyed or when a new pixbuf
      structure is passed to it, then the old #GdkPixbuf structure
      will be automatically unreferenced.
    </para>

    <para>
      This means that if an application just needs to load a pixbuf
      image and set it into a pixbuf canvas item, it can do the
      following to &lsquo;forget&rsquo; about the pixbuf structure:

      <programlisting>
	GdkPixbuf *pixbuf;
	GnomeCanvasItem *item;

	pixbuf = gdk_pixbuf_new_from_file ("foo.png");
	g_assert (pixbuf != NULL);

	item = gnome_canvas_item_new (gnome_canvas_root (my_canvas),
				      gnome_canvas_pixbuf_get_type (),
				      "pixbuf", pixbuf,
				      NULL);
	gdk_pixbuf_unref (pixbuf);
      </programlisting>
    </para>

    <para>
      After this happens, the reference count of the pixbuf structure
      will be 1:  the gdk_pixbuf_new_from_file() function creates it
      with a reference count of 1, then setting the <link
      linkend="GnomeCanvasPixbuf--pixbuf">pixbuf</link> argument of
      the #GnomeCanvasPixbuf item increases it to 2, and then it is
      decremented to 1 by the call to gdk_pixbuf_unref().  When the
      canvas item is destroyed, it will automatically unreference the
      pixbuf structure again, causing its reference count to drop to
      zero and thus be freed.
    </para>
  </refsect2>


<!-- ##### SECTION ./tmpl/xlib-rendering.sgml:Title ##### -->
Xlib Rendering


<!-- ##### ARG GnomeCanvasPixbuf:height_set ##### -->
  <para>
    Determines whether the <link
    linkend="GnomeCanvasPixbuf--height">height</link> argument is
    taken into account when scaling the pixbuf item.  Works in the
    same way as the <link
    linkend="GnomeCanvasPixbuf--width-set">width_set</link> argument.
    The default is %FALSE.
  </para>


708 709 710 711
<!-- ##### SECTION ./tmpl/gdk-pixbuf-io.sgml:Title ##### -->
gdk-pixbuf-io