libgpac
Documentation of the core library of GPAC
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_BBOX_DIRTY = 2, GF_PATH_FLATTENED = 4 }
 
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_Pathgf_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_Pathgf_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_Pathgf_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_PathIteratorgf_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_Pathgf_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

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_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
gpthe target path

◆ gf_path_reset()

void gf_path_reset ( GF_Path gp)

Resets the 2D path object

Parameters
gpthe target path

◆ gf_path_clone()

GF_Path* gf_path_clone ( GF_Path gp)

Resets a copy of a 2D path object

Parameters
gpthe target path
Returns
new path copy

◆ gf_path_close()

GF_Err gf_path_close ( GF_Path gp)

Closes current path contour

Parameters
gpthe 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
gpthe target path
xx-coordinate of the new point
yy-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
gpthe target path
ptpointer 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
gpthe target path
xx-coordinate of the line end
yy-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
gpthe target path
ptline 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
gpthe target path
c1_xx-coordinate of the first control point of the cubic curve
c1_yy-coordinate of the first control point of the cubic curve
c2_xx-coordinate of the second control point of the cubic curve
c2_yy-coordinate of the second control point of the cubic curve
xx-coordinate of the end point of the cubic curve
yy-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
gpthe target path
c1first control point of the cubic curve
c2second control point of the cubic curve
ptend 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
gpthe target path
c_xx-coordinate of the control point of the quadratic curve
c_yy-coordinate of the control point of the quadratic curve
xx-coordinate of the end point of the cubic quadratic
yy-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
gpthe target path
ccontrol point of the quadratic curve
ptend 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
gpthe target path
cxx-coordinate of the rectangle center
cyy-coordinate of the rectangle center
wwidth of the rectangle
hheight 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
gpthe target path
oxleft-most coordinate of the rectangle
oytop-most coordinate of the rectangle
wwidth of the rectangle
hheight 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
gpthe target path
cxx-coordinate of the ellipse center
cyy-coordinate of the ellipse center
a_axislength of the horizontal ellipse axis
b_axislength 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
gpthe target path
ptspoints used to define the curve
nb_ptsnumber 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
gpthe target path
end_xx-coordinate of the arc end point
end_yy-coordinate of the arc end point
fa_xx-coordinate of the arc first focal point
fa_yy-coordinate of the arc first focal point
fb_xx-coordinate of the arc second focal point
fb_yy-coordinate of the arc second focal point
cwif 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
gpthe target path
end_xx-coordinate of the arc end point
end_yy-coordinate of the arc end point
r_xx-axis radius
r_yy-axis radius
x_axis_rotationangle for the x-axis
large_arc_flaglarge or short arc selection
sweep_flagif 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
gpthe target path
radiusradius of the arc
start_anglestart angle of the arc in radians
end_angleend angle of the arc in radians
close_typeclosing 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
gpthe target path
subpaththe path to add
mxMatrix 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
gpthe target path
rcpointer 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
gpthe target path
rcpointer 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
gpthe target path

◆ gf_path_get_flatten()

GF_Path* gf_path_get_flatten ( GF_Path gp)

Gets a flatten copy of the path.

Parameters
gpthe 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
gpthe target path
xx-coordinate of the point to check
yy-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
gpthe 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
gpthe 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
itthe 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
itthe 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
itthe target path iterator
offsetlength on the path in local system unit
follow_tangentindicates 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.
matmatrix to be transformed (transformation shall be appended) - the matrix shall not be initialized
smooth_edgesindicates if discontinuities shall be smoothed. If not set, the rotation angle THETA is the slope (DX/DY) of the current segment found.
length_after_pointif 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
ptsthe points of the polygon
nb_ptsnumber 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
paththe desired path to outline
penthe properties of the virtual pen used for outlining
Returns
the outline of the path