GooCanvas Reference Manual |
---|

## Coordinate Spaces and LimitsCoordinate Spaces and Limits — how coordinates are used. |

## Coordinate Spaces

Items in the canvas typically have a number of properties specifying their location and size. For example the GooCanvasRect item has "x", "y", "width" and "height" properties.

However, items can also have a transformation matrix (e.g. the "transform" property). Transformation matrices modify the item's coordinate space in some way. Modifications include translation (moving the origin), rotation, scaling, and skewing, or combinations of these. Thus the final position of the item on the canvas can be altered dramatically.

The simple animation features in GooCanvas are accomplished by
modifying the item's transformation matrix over time.
(See `goo_canvas_item_animate()`

.)

Since items are in a hierarchy it is possible to move or rotate an entire group of items by simply changing the transformation matrix of the group containing them.

The coordinate space used within the item itself (e.g. where the "x" and "y" properties of a GooCanvasRect are specified) is referred to as "Item Space". The coordinate space used by the entire canvas is referred to as "Canvas Space" (or "Device Space"). "Item Space" and "Canvas Space" may or may not be the same, depending on whether the item or any of its ancestors have a transformation matrix set. (Note that the entire canvas may also be scrolled and/or zoomed, which means that there may be additional transformations above "Canvas Space".)

Functions are provided to convert between coordinate spaces,
e.g. `goo_canvas_convert_to_item_space()`

and
`goo_canvas_convert_from_item_space()`

convert canvas space coordinates
to item space and vice versa.

### Coordinate Limits

GooCanvas uses the Cairo graphics library to render canvas items. For performance reasons Cairo uses 32-bit fixed point integers internally when rendering graphics, with 24 bits used for the integer part of values and 8 bits used for the fractional part. This means that values are limited to roughly +/- 8,388,608. (Prior to Cairo 1.6 16 bits were used for the integer part and 16 bits for the fractional part, meaning values were limited to +/- 32,768.)

GooCanvas includes code to work around the Cairo limits to some extent. Subclasses of GooCanvasItemSimple (including all builtin items) can use any desired translation using a transformation matrix. But item space coordinates (modified by any scale, rotation or skew) must be within the Cairo limits.

It is possible to create new canvas items that avoid the Cairo limits completely. For an example of this see the "Large Items" page in the GooCanvas demo application, and the corresponding code.