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_Path * gf_path_new ()
 path constructor
void gf_path_del (GF_Path *gp)
 path destructor
void gf_path_reset (GF_Path *gp)
 path reset
GF_Path * gf_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_Path * gf_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_PathIterator * gf_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_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.

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:
gp the target path
void gf_path_reset ( GF_Path *  gp  ) 

Resets the 2D path object

Parameters:
gp the target path
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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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:
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_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
mat Matrix 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:
gp the target path
rc pointer 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:
gp the target path
rc pointer 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:
gp the target path
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
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.
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_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.
void gf_path_iterator_del ( GF_PathIterator *  it  ) 

Destructs the path iterator object

Parameters:
it the target path iterator
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
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:
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:
pts the points of the polygon
nb_pts number 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:
path the desired path to outline
pen the properties of the virtual pen used for outlining
Returns:
the outline of the path
Generated on 10 Sep 2015 for libgpac by  doxygen 1.6.1