mate-canvas-util

mate-canvas-util — Canvas utility functions

Synopsis

#include <libmatecanvas/libmatecanvas.h>

struct              MateCanvasPoints;
MateCanvasPoints *  mate_canvas_points_new              (int num_points);
MateCanvasPoints *  mate_canvas_points_ref              (MateCanvasPoints *points);
#define             mate_canvas_points_unref
void                mate_canvas_points_free             (MateCanvasPoints *points);
int                 mate_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                mate_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              mate_canvas_polygon_to_point        (double *poly,
                                                         int num_points,
                                                         double x,
                                                         double y);
void                mate_canvas_render_svp              (MateCanvasBuf *buf,
                                                         ArtSVP *svp,
                                                         guint32 rgba);
void                mate_canvas_update_svp              (MateCanvas *canvas,
                                                         ArtSVP **p_svp,
                                                         ArtSVP *new_svp);
void                mate_canvas_update_svp_clip         (MateCanvas *canvas,
                                                         ArtSVP **p_svp,
                                                         ArtSVP *new_svp,
                                                         ArtSVP *clip_svp);
void                mate_canvas_item_reset_bounds       (MateCanvasItem *item);
void                mate_canvas_item_update_svp         (MateCanvasItem *item,
                                                         ArtSVP **p_svp,
                                                         ArtSVP *new_svp);
void                mate_canvas_item_update_svp_clip    (MateCanvasItem *item,
                                                         ArtSVP **p_svp,
                                                         ArtSVP *new_svp,
                                                         ArtSVP *clip_svp);
void                mate_canvas_item_request_redraw_svp (MateCanvasItem *item,
                                                         const ArtSVP *svp);
void                mate_canvas_update_bbox             (MateCanvasItem *item,
                                                         int x1,
                                                         int y1,
                                                         int x2,
                                                         int y2);
void                mate_canvas_buf_ensure_buf          (MateCanvasBuf *buf);
ArtPathStrokeJoinType mate_canvas_join_gdk_to_art       (GdkJoinStyle gdk_join);
ArtPathStrokeCapType mate_canvas_cap_gdk_to_art         (GdkCapStyle gdk_cap);

Object Hierarchy

  GBoxed
   +----MateCanvasPoints

Description

Some useful canvas utility functions.

The MateCanvasPoints structure manages an array of points (X and Y coordinates) and is used by MateCanvasLine and MateCanvasPolygon canvas items.

To create a MateCanvasPoints structure call mate_canvas_points_new() and when finished using it call mate_canvas_points_free().

Of note is that the MateCanvasPoints 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 mate_canvas_points_ref() and to decrement it call mate_canvas_points_unref().

Details

struct MateCanvasPoints

struct MateCanvasPoints {
	double *coords;
	int num_points;
	int ref_count;
};

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

mate_canvas_points_new ()

MateCanvasPoints *  mate_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.

mate_canvas_points_ref ()

MateCanvasPoints *  mate_canvas_points_ref              (MateCanvasPoints *points);

Increases the reference count of the specified points structure.

points :

A canvas points structure.

Returns :

The canvas points structure itself.

mate_canvas_points_unref

#define mate_canvas_points_unref mate_canvas_points_free

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


mate_canvas_points_free ()

void                mate_canvas_points_free             (MateCanvasPoints *points);

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

points :

A canvas points structure.

mate_canvas_get_miter_points ()

int                 mate_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.

mate_canvas_get_butt_points ()

void                mate_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

mate_canvas_polygon_to_point ()

double              mate_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.

mate_canvas_render_svp ()

void                mate_canvas_render_svp              (MateCanvasBuf *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

mate_canvas_update_svp ()

void                mate_canvas_update_svp              (MateCanvas *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

mate_canvas_update_svp_clip ()

void                mate_canvas_update_svp_clip         (MateCanvas *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

mate_canvas_item_reset_bounds ()

void                mate_canvas_item_reset_bounds       (MateCanvasItem *item);

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

item :

A canvas item

mate_canvas_item_update_svp ()

void                mate_canvas_item_update_svp         (MateCanvasItem *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

mate_canvas_item_update_svp_clip ()

void                mate_canvas_item_update_svp_clip    (MateCanvasItem *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

mate_canvas_item_request_redraw_svp ()

void                mate_canvas_item_request_redraw_svp (MateCanvasItem *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

mate_canvas_update_bbox ()

void                mate_canvas_update_bbox             (MateCanvasItem *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

mate_canvas_buf_ensure_buf ()

void                mate_canvas_buf_ensure_buf          (MateCanvasBuf *buf);

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

buf :

the buf that needs to be represened in RGB format

mate_canvas_join_gdk_to_art ()

ArtPathStrokeJoinType mate_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.

mate_canvas_cap_gdk_to_art ()

ArtPathStrokeCapType mate_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.