## gnome-canvas-util

gnome-canvas-util — Canvas utility functions

## Synopsis

    #include <libgnomecanvas/libgnomecanvas.h>

                        GnomeCanvasPoints;
    GnomeCanvasPoints*  gnome_canvas_points_new             (int num_points);
    GnomeCanvasPoints*  gnome_canvas_points_ref             (GnomeCanvasPoints *points);
    #define             gnome_canvas_points_unref
    void                gnome_canvas_points_free            (GnomeCanvasPoints *points);
    int                 gnome_canvas_get_miter_points       (double x1,
                                                             double y1,
                                                             double x2,
                                                             double y2,
                                                             double x3,
                                                             double y3,
                                                             double width,
                                                             double *mx1,
                                                             double *my1,
                                                             double *mx2,
                                                             double *my2);
    void                gnome_canvas_get_butt_points        (double x1,
                                                             double y1,
                                                             double x2,
                                                             double y2,
                                                             double width,
                                                             int project,
                                                             double *bx1,
                                                             double *by1,
                                                             double *bx2,
                                                             double *by2);
    double              gnome_canvas_polygon_to_point       (double *poly,
                                                             int num_points,
                                                             double x,
                                                             double y);
    void                gnome_canvas_render_svp             (GnomeCanvasBuf *buf,
                                                             ArtSVP *svp,
                                                             guint32 rgba);
    void                gnome_canvas_update_svp             (GnomeCanvas *canvas,
                                                             ArtSVP **p_svp,
                                                             ArtSVP *new_svp);
    void                gnome_canvas_update_svp_clip        (GnomeCanvas *canvas,
                                                             ArtSVP **p_svp,
                                                             ArtSVP *new_svp,
                                                             ArtSVP *clip_svp);
    void                gnome_canvas_item_reset_bounds      (GnomeCanvasItem *item);
    void                gnome_canvas_item_update_svp        (GnomeCanvasItem *item,
                                                             ArtSVP **p_svp,
                                                             ArtSVP *new_svp);
    void                gnome_canvas_item_update_svp_clip   (GnomeCanvasItem *item,
                                                             ArtSVP **p_svp,
                                                             ArtSVP *new_svp,
                                                             ArtSVP *clip_svp);
    void                gnome_canvas_item_request_redraw_svp
                                                            (GnomeCanvasItem *item,
                                                             const ArtSVP *svp);
    void                gnome_canvas_update_bbox            (GnomeCanvasItem *item,
                                                             int x1,
                                                             int y1,
                                                             int x2,
                                                             int y2);
    void                gnome_canvas_buf_ensure_buf         (GnomeCanvasBuf *buf);
    ArtPathStrokeJoinType gnome_canvas_join_gdk_to_art      (GdkJoinStyle gdk_join);
    ArtPathStrokeCapType gnome_canvas_cap_gdk_to_art        (GdkCapStyle gdk_cap);

## Description

Some useful canvas utility functions.

The GnomeCanvasPoints structure manages an array of points (X and Y coordinates) and is used by GnomeCanvasLine and GnomeCanvasPolygon canvas items.

To create a GnomeCanvasPoints structure call `gnome_canvas_points_new()` and when finished using it call `gnome_canvas_points_free()`.

Of note is that the GnomeCanvasPoints structure is actually managed by a reference count, so it won't be freed until this count reaches 0. To increment its reference count call `gnome_canvas_points_ref()` and to decrement it call `gnome_canvas_points_unref()`.

## Details

### GnomeCanvasPoints

    typedef struct {
    	double *coords;
    	int num_points;
    	int ref_count;
    } GnomeCanvasPoints;

A structure to manage an array of points (X and Y coordinates). The memory management of this structure is handled with functions below, but the point coordinates are meant to be written directly into the array pointed to by the `coords` field.

double *`coords`; | Array of coordinates (num_points * 2 in size), X coordinates are stored in the even-numbered indices, and Y coordinates are stored in the odd-numbered indices.
int `num_points`; | Read-only - Number of points in this array.
int `ref_count`; | Read-only - Count of references to this array of points

### gnome_canvas_points_new ()

    GnomeCanvasPoints*  gnome_canvas_points_new             (int num_points);

Creates a structure that should be used to pass an array of points to items.

`num_points` : | The number of points to allocate space for in the array.
Returns : | A newly-created array of points. It should be filled in by the user.

### gnome_canvas_points_ref ()

    GnomeCanvasPoints*  gnome_canvas_points_ref             (GnomeCanvasPoints *points);

Increases the reference count of the specified points structure.

`points` : | A canvas points structure.
Returns : | The canvas points structure itself.

### gnome_canvas_points_unref

    #define             gnome_canvas_points_unref

A synonym for `gnome_canvas_points_free()`. It decrements a GnomeCanvasPoints reference by 1 and frees it when there are no more references.

### gnome_canvas_points_free ()

    void                gnome_canvas_points_free            (GnomeCanvasPoints *points);

Decreases the reference count of the specified points structure. If it reaches zero, then the structure is freed.

`points` : | A canvas points structure.

### gnome_canvas_get_miter_points ()

    int                 gnome_canvas_get_miter_points       (double x1,
                                                             double y1,
                                                             double x2,
                                                             double y2,
                                                             double x3,
                                                             double y3,
                                                             double width,
                                                             double *mx1,
                                                             double *my1,
                                                             double *mx2,
                                                             double *my2);

Given three points forming an angle, computes the coordinates of the inside and outside points of the mitered corner formed by a line of a given width at that angle.

`x1` : | X coordinate of the first point
`y1` : | Y coordinate of the first point
`x2` : | X coordinate of the second (angle) point
`y2` : | Y coordinate of the second (angle) point
`x3` : | X coordinate of the third point
`y3` : | Y coordinate of the third point
`width` : | Width of the line
`mx1` : | The X coordinate of the first miter point is returned here.
`my1` : | The Y coordinate of the first miter point is returned here.
`mx2` : | The X coordinate of the second miter point is returned here.
`my2` : | The Y coordinate of the second miter point is returned here.
Returns : | FALSE if the angle is less than 11 degrees (this is the same threshold as X uses. If this occurs, the return points are not modified. Otherwise, returns TRUE.

### gnome_canvas_get_butt_points ()

    void                gnome_canvas_get_butt_points        (double x1,
                                                             double y1,
                                                             double x2,
                                                             double y2,
                                                             double width,
                                                             int project,
                                                             double *bx1,
                                                             double *by1,
                                                             double *bx2,
                                                             double *by2);

Computes the butt points of a line segment.

`x1` : | X coordinate of first point in the line
`y1` : | Y cooordinate of first point in the line
`x2` : | X coordinate of second point (endpoint) of the line
`y2` : | Y coordinate of second point (endpoint) of the line
`width` : | Width of the line
`project` : | Whether the butt points should project out by width/2 distance
`bx1` : | X coordinate of first butt point is returned here
`by1` : | Y coordinate of first butt point is returned here
`bx2` : | X coordinate of second butt point is returned here
`by2` : | Y coordinate of second butt point is returned here

### gnome_canvas_polygon_to_point ()

    double              gnome_canvas_polygon_to_point       (double *poly,
                                                             int num_points,
                                                             double x,
                                                             double y);

Computes the distance between a point and a polygon.

`poly` : | Vertices of the polygon. X coordinates are in the even indices, and Y coordinates are in the odd indices
`num_points` : | Number of points in the polygon
`x` : | X coordinate of the point
`y` : | Y coordinate of the point
Returns : | The distance from the point to the polygon, or zero if the point is inside the polygon.

### gnome_canvas_render_svp ()

    void                gnome_canvas_render_svp             (GnomeCanvasBuf *buf,
                                                             ArtSVP *svp,
                                                             guint32 rgba);

Render the svp over the buf.

`buf` : | the canvas buffer to render over
`svp` : | the vector path to render
`rgba` : | the rgba color to render

### gnome_canvas_update_svp ()

    void                gnome_canvas_update_svp             (GnomeCanvas *canvas,
                                                             ArtSVP **p_svp,
                                                             ArtSVP *new_svp);

Sets the svp to the new value, requesting repaint on what's changed. This function takes responsibility for freeing new_svp.

`canvas` : | the canvas containing the svp that needs updating.
`p_svp` : | a pointer to the existing svp
`new_svp` : | the new svp

### gnome_canvas_update_svp_clip ()

    void                gnome_canvas_update_svp_clip        (GnomeCanvas *canvas,
                                                             ArtSVP **p_svp,
                                                             ArtSVP *new_svp,
                                                             ArtSVP *clip_svp);

Sets the svp to the new value, clipping if necessary, and requesting repaint on what's changed. This function takes responsibility for freeing new_svp.

`canvas` : | the canvas containing the svp that needs updating.
`p_svp` : | a pointer to the existing svp
`new_svp` : | the new svp
`clip_svp` : | a clip path, if non-null

### gnome_canvas_item_reset_bounds ()

    void                gnome_canvas_item_reset_bounds      (GnomeCanvasItem *item);

Resets the bounding box of a canvas item to an empty rectangle.

`item` : | A canvas item

### gnome_canvas_item_update_svp ()

    void                gnome_canvas_item_update_svp        (GnomeCanvasItem *item,
                                                             ArtSVP **p_svp,
                                                             ArtSVP *new_svp);

Sets the svp to the new value, requesting repaint on what's changed. This function takes responsibility for freeing new_svp. This routine also adds the svp's bbox to the item's.

`item` : | the canvas item containing the svp that needs updating.
`p_svp` : | a pointer to the existing svp
`new_svp` : | the new svp

### gnome_canvas_item_update_svp_clip ()

    void                gnome_canvas_item_update_svp_clip   (GnomeCanvasItem *item,
                                                             ArtSVP **p_svp,
                                                             ArtSVP *new_svp,
                                                             ArtSVP *clip_svp);

Sets the svp to the new value, clipping if necessary, and requesting repaint on what's changed. This function takes responsibility for freeing new_svp.

`item` : | the canvas item containing the svp that needs updating.
`p_svp` : | a pointer to the existing svp
`new_svp` : | the new svp
`clip_svp` : | a clip path, if non-null

### gnome_canvas_item_request_redraw_svp ()

    void                gnome_canvas_item_request_redraw_svp
                                                            (GnomeCanvasItem *item,
                                                             const ArtSVP *svp);

Request redraw of the svp if in aa mode, or the entire item in in xlib mode.

`item` : | the item containing the svp
`svp` : | the svp that needs to be redrawn

### gnome_canvas_update_bbox ()

    void                gnome_canvas_update_bbox            (GnomeCanvasItem *item,
                                                             int x1,
                                                             int y1,
                                                             int x2,
                                                             int y2);

Sets the bbox to the new value, requesting full repaint.

`item` : | the canvas item needing update
`x1` : | Left coordinate of the new bounding box
`y1` : | Top coordinate of the new bounding box
`x2` : | Right coordinate of the new bounding box
`y2` : | Bottom coordinate of the new bounding box

### gnome_canvas_buf_ensure_buf ()

    void                gnome_canvas_buf_ensure_buf         (GnomeCanvasBuf *buf);

Ensure that the buffer is in RGB format, suitable for compositing.

`buf` : | the buf that needs to be represened in RGB format

### gnome_canvas_join_gdk_to_art ()

    ArtPathStrokeJoinType gnome_canvas_join_gdk_to_art      (GdkJoinStyle gdk_join);

Convert from GDK line join specifier to libart.

`gdk_join` : | a join type, represented in GDK format
Returns : | The line join specifier in libart format.

### gnome_canvas_cap_gdk_to_art ()

    ArtPathStrokeCapType gnome_canvas_cap_gdk_to_art        (GdkCapStyle gdk_cap);

Convert from GDK line cap specifier to libart.

`gdk_cap` : | a cap type, represented in GDK format
Returns : | The line cap specifier in libart format.