2D Vector Path

Vectorial 2D Path manipulation. More...

Collaboration diagram for 2D Vector Path:

Data Structures
struct	GF_Path
	2D Path Object More...
struct	GF_DashSettings
	Custom dash pattern The custom dash pattern object is used to specify custom dashes when outlining a path. More...
struct	GF_PenSettings
	Pen properties. More...

Typedefs
typedef struct _path_iterator	GF_PathIterator
	path iterator More...

Enumerations
enum	GF_Path2DArcCloseType { GF_PATH2D_ARC_OPEN =0 , GF_PATH2D_ARC_CLOSE , GF_PATH2D_ARC_PIE }
enum	{ GF_PATH_CURVE_ON = 1 , GF_PATH_CLOSE = 5 , GF_PATH_CURVE_CONIC = 0 , GF_PATH_CURVE_CUBIC = 2 }
enum	{ GF_PATH_FILL_ZERO_NONZERO = 1 , GF_PATH_FILL_EVEN = 1<<1 , GF_PATH_BBOX_DIRTY = 1<<2 , GF_PATH_FLATTENED = 1<<3 }
enum	{   GF_POLYGON_COMPLEX , GF_POLYGON_COMPLEX_CCW , GF_POLYGON_COMPLEX_CW , GF_POLYGON_CONVEX_CCW ,   GF_POLYGON_CONVEX_CW , GF_POLYGON_CONVEX_LINE }
enum	{ GF_PATH_LINE_CENTER = 0 , GF_PATH_LINE_INSIDE , GF_PATH_LINE_OUTSIDE }
enum	{ GF_LINE_CAP_FLAT = 0 , GF_LINE_CAP_ROUND , GF_LINE_CAP_SQUARE , GF_LINE_CAP_TRIANGLE }
enum	{ GF_LINE_JOIN_MITER = 0 , GF_LINE_JOIN_ROUND , GF_LINE_JOIN_BEVEL , GF_LINE_JOIN_MITER_SVG }
enum	{   GF_DASH_STYLE_PLAIN = 0 , GF_DASH_STYLE_DASH , GF_DASH_STYLE_DOT , GF_DASH_STYLE_DASH_DOT ,   GF_DASH_STYLE_DASH_DASH_DOT , GF_DASH_STYLE_DASH_DOT_DOT , GF_DASH_STYLE_CUSTOM , GF_DASH_STYLE_SVG }

Functions
GF_Path *	gf_path_new ()
	path constructor More...
void	gf_path_del (GF_Path *gp)
	path destructor More...
void	gf_path_reset (GF_Path *gp)
	path reset More...
GF_Path *	gf_path_clone (GF_Path *gp)
	path copy constuctor More...
GF_Err	gf_path_close (GF_Path *gp)
	path close More...
GF_Err	gf_path_add_move_to (GF_Path *gp, Fixed x, Fixed y)
	path moveTo More...
GF_Err	gf_path_add_move_to_vec (GF_Path *gp, GF_Point2D *pt)
	starts new contour More...
GF_Err	gf_path_add_line_to (GF_Path *gp, Fixed x, Fixed y)
	adds line to path More...
GF_Err	gf_path_add_line_to_vec (GF_Path *gp, GF_Point2D *pt)
	adds line to path More...
GF_Err	gf_path_add_cubic_to (GF_Path *gp, Fixed c1_x, Fixed c1_y, Fixed c2_x, Fixed c2_y, Fixed x, Fixed y)
	adds cubic to path More...
GF_Err	gf_path_add_cubic_to_vec (GF_Path *gp, GF_Point2D *c1, GF_Point2D *c2, GF_Point2D *pt)
	adds cubic to path More...
GF_Err	gf_path_add_quadratic_to (GF_Path *gp, Fixed c_x, Fixed c_y, Fixed x, Fixed y)
	adds quadratic to path More...
GF_Err	gf_path_add_quadratic_to_vec (GF_Path *gp, GF_Point2D *c, GF_Point2D *pt)
	adds quadratic to path More...
GF_Err	gf_path_add_rect_center (GF_Path *gp, Fixed cx, Fixed cy, Fixed w, Fixed h)
	adds rectangle to path More...
GF_Err	gf_path_add_rect (GF_Path *gp, Fixed ox, Fixed oy, Fixed w, Fixed h)
	adds rectangle to path More...
GF_Err	gf_path_add_ellipse (GF_Path *gp, Fixed cx, Fixed cy, Fixed a_axis, Fixed b_axis)
	adds ellipse to path More...
GF_Err	gf_path_add_bezier (GF_Path *gp, GF_Point2D *pts, u32 nb_pts)
	adds N-1 bezier curve to path More...
GF_Err	gf_path_add_arc_to (GF_Path *gp, Fixed end_x, Fixed end_y, Fixed fa_x, Fixed fa_y, Fixed fb_x, Fixed fb_y, Bool cw)
	adds arc as described in MPEG-4 BIFS to path More...
GF_Err	gf_path_add_svg_arc_to (GF_Path *gp, Fixed end_x, Fixed end_y, Fixed r_x, Fixed r_y, Fixed x_axis_rotation, Bool large_arc_flag, Bool sweep_flag)
	adds arc as described in SVG to path More...
GF_Err	gf_path_add_arc (GF_Path *gp, Fixed radius, Fixed start_angle, Fixed end_angle, GF_Path2DArcCloseType close_type)
	adds arc to path More...
GF_Err	gf_path_add_subpath (GF_Path *gp, GF_Path *subpath, GF_Matrix2D *mx)
	concatenates path More...
GF_Err	gf_path_get_control_bounds (GF_Path *gp, GF_Rect *rc)
	gets path control bounds More...
GF_Err	gf_path_get_bounds (GF_Path *gp, GF_Rect *rc)
	gets path bounds More...
void	gf_path_flatten (GF_Path *gp)
	flattens path More...
GF_Path *	gf_path_get_flatten (GF_Path *gp)
	gets flatten copy of path More...
Bool	gf_path_point_over (GF_Path *gp, Fixed x, Fixed y)
	point over path testing More...
Bool	gf_path_is_empty (GF_Path *gp)
	path init testing More...
GF_PathIterator *	gf_path_iterator_new (GF_Path *gp)
	path iterator constructor More...
void	gf_path_iterator_del (GF_PathIterator *it)
	path iterator destructor More...
Fixed	gf_path_iterator_get_length (GF_PathIterator *it)
	get path length More...
Bool	gf_path_iterator_get_transform (GF_PathIterator *it, Fixed offset, Bool follow_tangent, GF_Matrix2D *mat, Bool smooth_edges, Fixed length_after_point)
	gets transformation matrix at given point on path More...
u32	gf_polygone2d_get_convexity (GF_Point2D *pts, u32 nb_pts)
GF_Path *	gf_path_get_outline (GF_Path *path, GF_PenSettings pen)

Detailed Description

This section documents the 2D path object used in the GPAC framework.

---

Data Structure Documentation

GF_Path

struct GF_Path

The 2D path object is used to construct complex 2D shapes for later drawing or outlining.

Collaboration diagram for GF_Path:

Data Fields
u32	n_contours	number of contours in path
u32	n_points	number of points in path and alloc size
u32	n_alloc_points
GF_Point2D *	points	path points
u8 *	tags	point tags (one per point)
u32 *	contours	contour end points
GF_Rect	bbox	path bbox - NEVER USE WITHOUT FIRST CALLING gf_path_get_bounds
s32	flags	path flags
Fixed	fineness	fineness to use whenever flattening the path - default is FIX_ONE

GF_DashSettings

struct GF_DashSettings

Data Fields
u32	num_dash	Number of dashes in the pattern
Fixed *	dashes	Value of the pattern dashes. Unit depends on the dash type

GF_PenSettings

struct GF_PenSettings

The pen properties object is used to specify several parameters used when building the vectorial outline of a path.

Collaboration diagram for GF_PenSettings:

Data Fields
Fixed	width	The width of the outline
u8	cap	The style of the lines ends
u8	join	The style of the lines joins
u8	align	The alignment of the outline with regard to the path
u8	dash	The dash style of the line
Fixed	miterLimit	The miter limit of the line joins
Fixed	dash_offset	The initial dash offset in the outline. All points before this offset will be ignored when building the outline
GF_DashSettings *	dash_set	The dash pattern used for custom dashing
Fixed	path_length	The author-specified path length. Ignored if <= 0

Typedef Documentation

GF_PathIterator

typedef struct _path_iterator GF_PathIterator

The path iterator object is used to compute the length of a given path as well as transformation matrices along this path.

Enumeration Type Documentation

GF_Path2DArcCloseType

enum GF_Path2DArcCloseType

Close type for arc

Enumerator
GF_PATH2D_ARC_OPEN	Arc is left open
GF_PATH2D_ARC_CLOSE	Arc is closed to its starting point
GF_PATH2D_ARC_PIE	Arc is closed as a pie centered on arc center

anonymous enum

anonymous enum

2D Path point tags

Enumerator
GF_PATH_CLOSE	Point is a contour close
GF_PATH_CURVE_CONIC	Point is a quadratic control point
GF_PATH_CURVE_CUBIC	Point is a cubic control point

anonymous enum

anonymous enum

2D Path flags

Enumerator
GF_PATH_FILL_ZERO_NONZERO	Path is filled using the zero-nonzero rule. If not set, filling uses odd/even rule
GF_PATH_FILL_EVEN	Path is filled using the odd-even rule but only even surface is filled
GF_PATH_BBOX_DIRTY	When set bbox must be recomputed. Note Read only, used to avoid wasting time on bounds calculation
GF_PATH_FLATTENED	Indicates the path is flattened flattened Note Read only, used to avoid wasting time on flattening

anonymous enum

anonymous enum

2D Polygon convexity type

Enumerator
GF_POLYGON_COMPLEX	Polygon is either complex or unknown
GF_POLYGON_COMPLEX_CCW	Polygon is complex, starting in counter-clockwise order
GF_POLYGON_COMPLEX_CW	Polygon is complex, starting in clockwise order
GF_POLYGON_CONVEX_CCW	Polygon is a counter-clockwise convex polygon
GF_POLYGON_CONVEX_CW	Polygon is a clockwise convex polygon
GF_POLYGON_CONVEX_LINE	Polygon is a convex line (degenerated path with all segments aligned)

anonymous enum

anonymous enum

Stencil alignment type for outlining

Enumerator
GF_PATH_LINE_CENTER	outline is centered on the path (default)
GF_PATH_LINE_INSIDE	outline is inside the path
GF_PATH_LINE_OUTSIDE	outline is outside the path

anonymous enum

anonymous enum

Line cap type for outlining

Enumerator
GF_LINE_CAP_FLAT	End of line is flat (default)
GF_LINE_CAP_ROUND	End of line is round
GF_LINE_CAP_SQUARE	End of line is square
GF_LINE_CAP_TRIANGLE	End of line is triangle

anonymous enum

anonymous enum

Line join type for outlining

Enumerator
GF_LINE_JOIN_MITER	Line join is a miter join (default)
GF_LINE_JOIN_ROUND	Line join is a round join
GF_LINE_JOIN_BEVEL	Line join is a bevel join
GF_LINE_JOIN_MITER_SVG	Line join is a miter then bevel join

anonymous enum

anonymous enum

Dash types for outlining

Enumerator
GF_DASH_STYLE_PLAIN	No dashing is used (default)
GF_DASH_STYLE_DASH	Predefined dash pattern is used
GF_DASH_STYLE_DOT	Predefined dot pattern is used
GF_DASH_STYLE_DASH_DOT	Predefined dash-dot pattern is used
GF_DASH_STYLE_DASH_DASH_DOT	Predefined dash-dash-dot pattern is used
GF_DASH_STYLE_DASH_DOT_DOT	Predefined dash-dot-dot pattern is used
GF_DASH_STYLE_CUSTOM	Custom pattern is used. Dash lengths are given in percentage of the pen width
GF_DASH_STYLE_SVG	SVG pattern is used. Dash lengths are given in the same unit as the pen width and dash offset follows SVG specs (offset in dash pattern)

Function Documentation

gf_path_new()

GF_Path* gf_path_new

(

)

Constructs an empty 2D path object

Returns

new path object

gf_path_del()

void gf_path_del

(

GF_Path *

gp

)

Destructs a 2D path object

Parameters

gp	the target path

gf_path_reset()

void gf_path_reset

(

GF_Path *

gp

)

Resets the 2D path object

Parameters

gp	the target path

gf_path_clone()

GF_Path* gf_path_clone

(

GF_Path *

gp

)

Resets a copy of a 2D path object

Parameters

gp	the target path

Returns

new path copy

gf_path_close()

GF_Err gf_path_close

(

GF_Path *

gp

)

Closes current path contour

Parameters

gp	the target path

Returns

error code if any error, GF_OK otherwise

gf_path_add_move_to()

GF_Err gf_path_add_move_to	(	GF_Path *	gp,
		Fixed	x,
		Fixed	y
	)

Starts a new contour from the specified point

Parameters

gp	the target path
x	x-coordinate of the new point
y	y-coordinate of the new point

Returns

error code if any error, GF_OK otherwise

gf_path_add_move_to_vec()

GF_Err gf_path_add_move_to_vec	(	GF_Path *	gp,
		GF_Point2D *	pt
	)

Starts a new contour from the specified point

Parameters

gp	the target path
pt	pointer to the new start point

Returns

error code if any error, GF_OK otherwise

gf_path_add_line_to()

GF_Err gf_path_add_line_to	(	GF_Path *	gp,
		Fixed	x,
		Fixed	y
	)

Adds a line from the current point in path to the specified point

Parameters

gp	the target path
x	x-coordinate of the line end
y	y-coordinate of the line end

Returns

error code if any error, GF_OK otherwise

gf_path_add_line_to_vec()

GF_Err gf_path_add_line_to_vec	(	GF_Path *	gp,
		GF_Point2D *	pt
	)

Adds a line from the current point in path to the specified point

Parameters

gp	the target path
pt	line end

Returns

error code if any error, GF_OK otherwise

gf_path_add_cubic_to()

GF_Err gf_path_add_cubic_to	(	GF_Path *	gp,
		Fixed	c1_x,
		Fixed	c1_y,
		Fixed	c2_x,
		Fixed	c2_y,
		Fixed	x,
		Fixed	y
	)

Adds a cubic bezier curve to the current contour, starting from the current path point

Parameters

gp	the target path
c1_x	x-coordinate of the first control point of the cubic curve
c1_y	y-coordinate of the first control point of the cubic curve
c2_x	x-coordinate of the second control point of the cubic curve
c2_y	y-coordinate of the second control point of the cubic curve
x	x-coordinate of the end point of the cubic curve
y	y-coordinate of the end point of the cubic curve

Returns

error code if any error, GF_OK otherwise

gf_path_add_cubic_to_vec()

GF_Err gf_path_add_cubic_to_vec	(	GF_Path *	gp,
		GF_Point2D *	c1,
		GF_Point2D *	c2,
		GF_Point2D *	pt
	)

Adds a cubic bezier curve to the current contour, starting from the current path point

Parameters

gp	the target path
c1	first control point of the cubic curve
c2	second control point of the cubic curve
pt	end point of the cubic curve

Returns

error code if any error, GF_OK otherwise

gf_path_add_quadratic_to()

GF_Err gf_path_add_quadratic_to	(	GF_Path *	gp,
		Fixed	c_x,
		Fixed	c_y,
		Fixed	x,
		Fixed	y
	)

Adds a quadratic bezier curve to the current contour, starting from the current path point

Parameters

gp	the target path
c_x	x-coordinate of the control point of the quadratic curve
c_y	y-coordinate of the control point of the quadratic curve
x	x-coordinate of the end point of the cubic quadratic
y	y-coordinate of the end point of the cubic quadratic

Returns

error code if any error, GF_OK otherwise

gf_path_add_quadratic_to_vec()

GF_Err gf_path_add_quadratic_to_vec	(	GF_Path *	gp,
		GF_Point2D *	c,
		GF_Point2D *	pt
	)

Adds a quadratic bezier curve to the current contour, starting from the current path point

Parameters

gp	the target path
c	control point of the quadratic curve
pt	end point of the cubic quadratic

Returns

error code if any error, GF_OK otherwise

gf_path_add_rect_center()

GF_Err gf_path_add_rect_center	(	GF_Path *	gp,
		Fixed	cx,
		Fixed	cy,
		Fixed	w,
		Fixed	h
	)

Adds a rectangle contour to the path

Parameters

gp	the target path
cx	x-coordinate of the rectangle center
cy	y-coordinate of the rectangle center
w	width of the rectangle
h	height of the rectangle

Returns

error code if any error, GF_OK otherwise

gf_path_add_rect()

GF_Err gf_path_add_rect	(	GF_Path *	gp,
		Fixed	ox,
		Fixed	oy,
		Fixed	w,
		Fixed	h
	)

Adds a rectangle contour to the path

Parameters

gp	the target path
ox	left-most coordinate of the rectangle
oy	top-most coordinate of the rectangle
w	width of the rectangle
h	height of the rectangle

Returns

error code if any error, GF_OK otherwise

gf_path_add_ellipse()

GF_Err gf_path_add_ellipse	(	GF_Path *	gp,
		Fixed	cx,
		Fixed	cy,
		Fixed	a_axis,
		Fixed	b_axis
	)

Adds an ellipse contour to the path

Parameters

gp	the target path
cx	x-coordinate of the ellipse center
cy	y-coordinate of the ellipse center
a_axis	length of the horizontal ellipse axis
b_axis	length of the vertical ellipse axis

Returns

error code if any error, GF_OK otherwise

gf_path_add_bezier()

GF_Err gf_path_add_bezier	(	GF_Path *	gp,
		GF_Point2D *	pts,
		u32	nb_pts
	)

Adds an N-degree bezier curve to the path, starting from the current point

Parameters

gp	the target path
pts	points used to define the curve
nb_pts	number of points used to define the curve. The degree of the curve is therefore (nb_pts-1).

Returns

error code if any error, GF_OK otherwise

Note

the fineness of the path must be set before calling this function.

gf_path_add_arc_to()

GF_Err gf_path_add_arc_to	(	GF_Path *	gp,
		Fixed	end_x,
		Fixed	end_y,
		Fixed	fa_x,
		Fixed	fa_y,
		Fixed	fb_x,
		Fixed	fb_y,
		Bool	cw
	)

Adds an arc contour to the path from focal and end points.

Parameters

gp	the target path
end_x	x-coordinate of the arc end point
end_y	y-coordinate of the arc end point
fa_x	x-coordinate of the arc first focal point
fa_y	y-coordinate of the arc first focal point
fb_x	x-coordinate of the arc second focal point
fb_y	y-coordinate of the arc second focal point
cw	if 1, the arc will be clockwise, otherwise counter-clockwise.

Returns

error code if any error, GF_OK otherwise

gf_path_add_svg_arc_to()

GF_Err gf_path_add_svg_arc_to	(	GF_Path *	gp,
		Fixed	end_x,
		Fixed	end_y,
		Fixed	r_x,
		Fixed	r_y,
		Fixed	x_axis_rotation,
		Bool	large_arc_flag,
		Bool	sweep_flag
	)

Adds an arc contour to the path from end point, radii and 3 parameters.

Parameters

gp	the target path
end_x	x-coordinate of the arc end point
end_y	y-coordinate of the arc end point
r_x	x-axis radius
r_y	y-axis radius
x_axis_rotation	angle for the x-axis
large_arc_flag	large or short arc selection
sweep_flag	if 1, the arc will be clockwise, otherwise counter-clockwise.

Returns

error code if any error, GF_OK otherwise

gf_path_add_arc()

GF_Err gf_path_add_arc	(	GF_Path *	gp,
		Fixed	radius,
		Fixed	start_angle,
		Fixed	end_angle,
		GF_Path2DArcCloseType	close_type
	)

Adds an arc contour to the path.

Parameters

gp	the target path
radius	radius of the arc
start_angle	start angle of the arc in radians
end_angle	end angle of the arc in radians
close_type	closing type: 0 for open arc, 1 for close arc, 2 for pie

Returns

error code if any error, GF_OK otherwise

gf_path_add_subpath()

GF_Err gf_path_add_subpath	(	GF_Path *	gp,
		GF_Path *	subpath,
		GF_Matrix2D *	mx
	)

Adds a sub-path to the path with a given transform.

Parameters

gp	the target path
subpath	the path to add
mx	Matrix for subpath

Returns

error code if any error, GF_OK otherwise

gf_path_get_control_bounds()

GF_Err gf_path_get_control_bounds	(	GF_Path *	gp,
		GF_Rect *	rc
	)

Gets the path control bounds, i.e. the rectangle covering all lineTo and bezier control points.

Parameters

gp	the target path
rc	pointer to rectangle receiving the control rectangle

Returns

error code if any error, GF_OK otherwise

gf_path_get_bounds()

GF_Err gf_path_get_bounds	(	GF_Path *	gp,
		GF_Rect *	rc
	)

Gets the path bounds, i.e. the rectangle covering all points in path except bezier control points.

Parameters

gp	the target path
rc	pointer to rectangle receiving the control rectangle

Returns

error code if any error, GF_OK otherwise

gf_path_flatten()

void gf_path_flatten

(

GF_Path *

gp

)

Flattens the path, i.e. transform all bezier curves to lines according to the path flatness.

Parameters

gp	the target path

gf_path_get_flatten()

GF_Path* gf_path_get_flatten

(

GF_Path *

gp

)

Gets a flatten copy of the path.

Parameters

gp	the target path

Returns

the flatten path

gf_path_point_over()

Bool gf_path_point_over	(	GF_Path *	gp,
		Fixed	x,
		Fixed	y
	)

Tests if a point is over a path or not, according to the path filling rule.

Parameters

gp	the target path
x	x-coordinate of the point to check
y	y-coordinate of the point to check

Returns

1 if the point is over the path, 0 otherwise.

gf_path_is_empty()

Bool gf_path_is_empty

(

GF_Path *

gp

)

Tests if the path is empty or not.

Parameters

gp	the target path

Returns

1 if the path is empty, 0 otherwise.

gf_path_iterator_new()

GF_PathIterator* gf_path_iterator_new

(

GF_Path *

gp

)

Creates a new path iterator from a given path

Parameters

gp	the target path

Returns

the path iterator object.

gf_path_iterator_del()

void gf_path_iterator_del

(

GF_PathIterator *

it

)

Destructs the path iterator object

Parameters

it	the target path iterator

gf_path_iterator_get_length()

Fixed gf_path_iterator_get_length

(

GF_PathIterator *

it

)

Gets a path length from its iterator

Parameters

it	the target path iterator

Returns

the length of the path

gf_path_iterator_get_transform()

Bool gf_path_iterator_get_transform	(	GF_PathIterator *	it,
		Fixed	offset,
		Bool	follow_tangent,
		GF_Matrix2D *	mat,
		Bool	smooth_edges,
		Fixed	length_after_point
	)

Gets the transformation of a given point on the path, given by offset from origin. The transform is so that a local system is translated to the given point, its x-axis tangent to the path and in the same direction. The path direction is from first point to last point of the path.

Parameters

it	the target path iterator
offset	length on the path in local system unit
follow_tangent	indicates if transformation shall be computed if offset indicates a point outside the path (<0 or >path_length). In which case the path shall be virtually extended by the tangent at origin (offset <0) or at end (offset>path_length). Otherwise the transformation is not computed and 0 is returned.
mat	matrix to be transformed (transformation shall be appended) - the matrix shall not be initialized
smooth_edges	indicates if discontinuities shall be smoothed. If not set, the rotation angle THETA is the slope (DX/DY) of the current segment found.
length_after_point	if set and smooth_edges is set, the amount of the object that lies on next segment shall be computed according to length_after_point.

Let:
      len_last: length of current checked segment
      len1: length of all previous segments so that len1 + len_last >= offset then if (offset + length_after_point > len1 + len_last) {
      ratio = (len1 + len_last - offset) / length_after_point;
      then THETA = ratio * slope(L1) + (1-ratio) * slope(L2)
 
Of course care must be taken for PI/2 angles and similar situations

Returns

GF_TRUE if matrix has been updated, GF_FALSE otherwise, if failure or if point is out of path without tangent extension.

gf_polygone2d_get_convexity()

u32 gf_polygone2d_get_convexity	(	GF_Point2D *	pts,
		u32	nb_pts
	)

brief gets convexity type for a 2D polygon Gets the convexity type of the given 2D polygon

Parameters

pts	the points of the polygon
nb_pts	number of points in the polygon

Returns

the convexity type of the polygon

gf_path_get_outline()

GF_Path* gf_path_get_outline	(	GF_Path *	path,
		GF_PenSettings	pen
	)

brief builds the vectorial outline of a path

Builds the vectorial outline of a path for the given settings. The outline of a path is a path.

Parameters

path	the desired path to outline
pen	the properties of the virtual pen used for outlining

Returns

the outline of the path