libgpac  0.4.5
Classes | Typedefs | Enumerations | Functions
path2d
utils

Vectorial 2D Path manipulation functions. More...

Classes

struct  GF_Path
 2D Path Object More...
struct  GF_DashSettings
 Custom dash pattern. More...
struct  GF_PenSettings
 Pen properties. More...

Typedefs

typedef struct _path_iterator GF_PathIterator
 path iterator

Enumerations

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
void gf_path_del (GF_Path *gp)
 path destructor
void gf_path_reset (GF_Path *gp)
 path reset
GF_Pathgf_path_clone (GF_Path *gp)
 path copy constuctor
GF_Err gf_path_close (GF_Path *gp)
 path close
GF_Err gf_path_add_move_to (GF_Path *gp, Fixed x, Fixed y)
 path moveTo
GF_Err gf_path_add_move_to_vec (GF_Path *gp, GF_Point2D *pt)
 starts new contour
GF_Err gf_path_add_line_to (GF_Path *gp, Fixed x, Fixed y)
 adds line to path
GF_Err gf_path_add_line_to_vec (GF_Path *gp, GF_Point2D *pt)
 adds line to path
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
GF_Err gf_path_add_cubic_to_vec (GF_Path *gp, GF_Point2D *c1, GF_Point2D *c2, GF_Point2D *pt)
 adds cubic to path
GF_Err gf_path_add_quadratic_to (GF_Path *gp, Fixed c_x, Fixed c_y, Fixed x, Fixed y)
 adds quadratic to path
GF_Err gf_path_add_quadratic_to_vec (GF_Path *gp, GF_Point2D *c, GF_Point2D *pt)
 adds quadratic to path
GF_Err gf_path_add_rect_center (GF_Path *gp, Fixed cx, Fixed cy, Fixed w, Fixed h)
 adds rectangle to path
GF_Err gf_path_add_rect (GF_Path *gp, Fixed ox, Fixed oy, Fixed w, Fixed h)
 adds rectangle to path
GF_Err gf_path_add_ellipse (GF_Path *gp, Fixed cx, Fixed cy, Fixed a_axis, Fixed b_axis)
 adds ellipse to path
GF_Err gf_path_add_bezier (GF_Path *gp, GF_Point2D *pts, u32 nb_pts)
 adds N-bezier curve to path
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
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
GF_Err gf_path_add_arc (GF_Path *gp, Fixed radius, Fixed start_angle, Fixed end_angle, u32 close_type)
 adds arc to path
GF_Err gf_path_add_subpath (GF_Path *gp, GF_Path *subpath, GF_Matrix2D *mx)
 concatenates path
GF_Err gf_path_get_control_bounds (GF_Path *gp, GF_Rect *rc)
 gets path control bounds
GF_Err gf_path_get_bounds (GF_Path *gp, GF_Rect *rc)
 gets path bounds
void gf_path_flatten (GF_Path *gp)
 flattens path
GF_Pathgf_path_get_flatten (GF_Path *gp)
 gets flatten copy of path
Bool gf_path_point_over (GF_Path *gp, Fixed x, Fixed y)
 point over path testing
Bool gf_path_is_empty (GF_Path *gp)
 path init testing
GF_PathIteratorgf_path_iterator_new (GF_Path *gp)
 path iterator constructor
void gf_path_iterator_del (GF_PathIterator *it)
 path iterator destructor
Fixed gf_path_iterator_get_length (GF_PathIterator *it)
 get path length
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
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.


Typedef Documentation

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

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

*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

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

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

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

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

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* gf_path_new ( )

Constructs an empty 2D path object

Returns:
new path object
void gf_path_del ( GF_Path gp)

Destructs a 2D path object

Parameters:
gpthe target path
void gf_path_reset ( GF_Path gp)

Resets the 2D path object

Parameters:
gpthe target path
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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_Err gf_path_add_arc ( GF_Path gp,
Fixed  radius,
Fixed  start_angle,
Fixed  end_angle,
u32  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_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
matMatrix for subpath
Returns:
error code if any error, GF_OK otherwise
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_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
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* gf_path_get_flatten ( GF_Path gp)

Gets a flatten copy of the path.

Parameters:
gpthe target path
Returns:
the flatten path
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.
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_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.
void gf_path_iterator_del ( GF_PathIterator it)

Destructs the path iterator object

Parameters:
itthe target path iterator
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
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
   \return 1 if matrix has been updated, 0 otherwise, if failure or if point is out of path without tangent extension.
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* 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