CrBlit

CrBlit — A grouping item to improve performance by caching complex item trees off-screen.

Synopsis

                    CrBlit;
CrItem*             cr_blit_new                         (CrItem *parent,
                                                         const gchar *first_arg_name,
                                                         ...);

Object Hierarchy

  GObject
   +----CrItem
         +----CrBlit

Properties

  "canvas"                   CrCanvas*             : Read / Write
  "device-height"            gdouble               : Read / Write
  "device-width"             gdouble               : Read / Write
  "scale-factor"             gdouble               : Read / Write
  "test-image"               gboolean              : Read / Write

Description

The Blit item is used to group any arbitrary item tree into an offscreen memory surface. The memory surface is then painted to the screen in a single operation. It should be used in cases where the CPU time needed to paint the item tree to the screen is greater than then frequency at which the tree needs to be repainted.

To use the item, either set a fixed memory size by setting the "device_width" and "device_height" properties explicitly, or allow it to automatically determine the best memory size by setting the "canvas" and "scale-factor" properties. When using fixed memory sizing, the image will often look blurry. When using automatic sizing, the image will be re-built each time the canvas is zoomed or panned.

One example use is a detailed vector map with a moving animation over it. As the animation moves rapidly over the map, there is no need to redraw the map vectors for each movement of the animation. The Blit item can be used to rasterize the map so that only a single image will be repainted with each movement of the animation.

Another example use is a very complex item tree that needs to be scaled or panned. The operation may be sluggish if the amount of time required to render the vector graphics is greater than 0.1 seconds. Because rendering an image is generally faster, using CrBlit during the scaling or panning operation will make the operation happen smoothly.

(BUGS: On some hardware, this item does not work properly and in some cases causes the window manager to crash. On other hardware it works perfectly. Suspect problem is in cairo library -- still investigating.)

Details

CrBlit

typedef struct _CrBlit CrBlit;


cr_blit_new ()

CrItem*             cr_blit_new                         (CrItem *parent,
                                                         const gchar *first_arg_name,
                                                         ...);

A convenience routine for creating a cr-blit item and adding it to an item group in one step.

parent :

The parent canvas item.

first_arg_name :

... :

Returns :

A reference to a new CrItem. You must call g_object_ref if you intend to use this reference outside the local scope.

Property Details

The "canvas" property

  "canvas"                   CrCanvas*             : Read / Write

Reference to CrCanvas widget which can be used in lieu of setting device-width/height explicitly. Setting the canvas property will cause the blitted image to get periodically recalculated as the scale and size of the referenced canvas changes. In the event that the blitted image is added to the item tree of multiple canvasses, the recalulation will obviously only be triggered by changes to the canvas referenced here.


The "device-height" property

  "device-height"            gdouble               : Read / Write

The pixel height dedicated to the blit surface. This property will get set automatically if the canvas property is set.

Allowed values: >= 0

Default value: 0


The "device-width" property

  "device-width"             gdouble               : Read / Write

The pixel width dedicated to the blit surface. This property will get set automatically if the canvas property is set.

Allowed values: >= 0

Default value: 0


The "scale-factor" property

  "scale-factor"             gdouble               : Read / Write

A ratio that defines the maximum amount of memory that can be used to define the blit device-width and height when the canvas property is set. i.e., If canvas is zoomed in to show only 10x10 user coordinates and the scale-factor=2, but the blitted image is 100x100 in user corrdinates, only a 20x20 fraction of the image will be stored. This property has no-effect when the canvas property is not set.

Allowed values: >= 0

Default value: 2


The "test-image" property

  "test-image"               gboolean              : Read / Write

If only the image should be tested rather than the individual child items. For very complex item trees, this property will save cpu usage. Set this to FALSE if you need to distinguish which part of the image is selected.

Default value: TRUE