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