IndexGeometriesBLPath

BLPath Class Reference [¶]

2D vector path [C++ API].

Classes

Member Functions

Construction & Destruction
Overloaded Operators
Common Functionality
Accessors
Path Construction
Adding Multiple Segments

Adding multiple segments API was designed to provide high-performance path building in case that the user knows the segments that will be added to the path in advance.

Adding Figures

Adding a figure means starting with a move-to segment. For example add_box() would start a new figure by adding BL_PATH_CMD_MOVE_TO segment, and then by adding 3 lines, and finally a close command.

Adding Paths
Manipulation
Transformations
Equality & Comparison
Path Information
Hit Testing

Additional Inherited Members

Public Attributes inherited from BLObjectCore

bool BLPath::is_empty() constnodiscardnoexcept[¶]

Tests whether the path is empty, which means its size equals to zero.

size_t BLPath::size() constnodiscardnoexcept[¶]

Returns path size (count of vertices used).

size_t BLPath::capacity() constnodiscardnoexcept[¶]

Returns path capacity (count of allocated vertices).

const BLPoint* BLPath::vertex_data() constnodiscardnoexcept[¶]

Returns path's vertex data (read-only).

const BLPoint* BLPath::vertex_data_end() constnodiscardnoexcept[¶]

Returns the end of path's vertex data (read-only).

const uint8_t* BLPath::command_data() constnodiscardnoexcept[¶]

Returns path's command data (read-only).

const uint8_t* BLPath::command_data_end() constnodiscardnoexcept[¶]

Returns the end of path's command data (read-only).

BLPathView BLPath::view() constnodiscardnoexcept[¶]

Returns a read-only path data as BLPathView.

BLResult BLPath::clear()noexcept[¶]

Clears the content of the path.

BLResult BLPath::shrink()noexcept[¶]

Shrinks the capacity of the path to fit the current usage.

BLResult BLPath::reserve(
size_t n
)noexcept[¶]

Reserves the capacity of the path for at least n vertices and commands.

BLResult BLPath::set_vertex_at(
size_t index,
uint32_t cmd,
const BLPoint& pt
)noexcept[1/2][¶]

Sets vertex at index to cmd and pt.

Pass BL_PATH_CMD_PRESERVE in cmd to preserve the current command.

BLResult BLPath::set_vertex_at(
size_t index,
uint32_t cmd,
double x,
double y
)noexcept[2/2][¶]

Sets vertex at index to cmd and [x, y].

Pass BL_PATH_CMD_PRESERVE in cmd to preserve the current command.

BLResult BLPath::move_to(
const BLPoint& p0
)noexcept[1/2][¶]

Moves to p0.

Appends BL_PATH_CMD_MOVE[p0] command to the path.

BLResult BLPath::move_to(
double x0,
double y0
)noexcept[2/2][¶]

Moves to [x0, y0].

Appends BL_PATH_CMD_MOVE[x0, y0] command to the path.

BLResult BLPath::line_to(
const BLPoint& p1
)noexcept[1/2][¶]

Adds line to p1.

Appends BL_PATH_CMD_ON[p1] command to the path.

BLResult BLPath::line_to(
double x1,
double y1
)noexcept[2/2][¶]

Adds line to [x1, y1].

Appends BL_PATH_CMD_ON[x1, y1] command to the path.

BLResult BLPath::poly_to(
const BLPoint* poly,
size_t count
)noexcept[¶]

Adds a polyline (LineTo) of the given poly array of size count.

Appends multiple BL_PATH_CMD_ON[x[i], y[i]] commands to the path depending on count parameter.

BLResult BLPath::quad_to(
const BLPoint& p1,
const BLPoint& p2
)noexcept[1/2][¶]

Adds a quadratic curve to p1 and p2.

Appends the following commands to the path:

  • BL_PATH_CMD_QUAD[p1]
  • BL_PATH_CMD_ON[p2]

Matches SVG 'Q' path command:

BLResult BLPath::quad_to(
double x1,
double y1,
double x2,
double y2
)noexcept[2/2][¶]

Adds a quadratic curve to [x1, y1] and [x2, y2].

Appends the following commands to the path:

  • BL_PATH_CMD_QUAD[x1, y1]
  • BL_PATH_CMD_ON[x2, y2]

Matches SVG 'Q' path command:

BLResult BLPath::cubic_to(
const BLPoint& p1,
const BLPoint& p2,
const BLPoint& p3
)noexcept[1/2][¶]

Adds a cubic curve to p1, p2, p3.

Appends the following commands to the path:

  • BL_PATH_CMD_CUBIC[p1]
  • BL_PATH_CMD_CUBIC[p2]
  • BL_PATH_CMD_ON[p3]

Matches SVG 'C' path command:

BLResult BLPath::cubic_to(
double x1,
double y1,
double x2,
double y2,
double x3,
double y3
)noexcept[2/2][¶]

Adds a cubic curve to [x1, y1], [x2, y2], and [x3, y3].

Appends the following commands to the path:

  • BL_PATH_CMD_CUBIC[x1, y1]
  • BL_PATH_CMD_CUBIC[x2, y2]
  • BL_PATH_CMD_ON[x3, y3]

Matches SVG 'C' path command:

BLResult BLPath::smooth_quad_to(
const BLPoint& p2
)noexcept[1/2][¶]

Adds a smooth quadratic curve to p2, calculating p1 from last points.

Appends the following commands to the path:

  • BL_PATH_CMD_QUAD[calculated]
  • BL_PATH_CMD_ON[p2]

Matches SVG 'T' path command:

BLResult BLPath::smooth_quad_to(
double x2,
double y2
)noexcept[2/2][¶]

Adds a smooth quadratic curve to [x2, y2], calculating [x1, y1] from last points.

Appends the following commands to the path:

  • BL_PATH_CMD_QUAD[calculated]
  • BL_PATH_CMD_ON[x2, y2]

Matches SVG 'T' path command:

BLResult BLPath::smooth_cubic_to(
const BLPoint& p2,
const BLPoint& p3
)noexcept[1/2][¶]

Adds a smooth cubic curve to p2 and p3, calculating p1 from last points.

Appends the following commands to the path:

  • BL_PATH_CMD_CUBIC[calculated]
  • BL_PATH_CMD_CUBIC[p2]
  • BL_PATH_CMD_ON[p3]

Matches SVG 'S' path command:

BLResult BLPath::smooth_cubic_to(
double x2,
double y2,
double x3,
double y3
)noexcept[2/2][¶]

Adds a smooth cubic curve to [x2, y2] and [x3, y3], calculating [x1, y1] from last points.

Appends the following commands to the path:

  • BL_PATH_CMD_CUBIC[calculated]
  • BL_PATH_CMD_CUBIC[x2, y2]
  • BL_PATH_CMD_ON[x3, y3]

Matches SVG 'S' path command:

BLResult BLPath::arc_to(
const BLPoint& c,
const BLPoint& r,
double start,
double sweep,
bool force_move_to = false
)noexcept[1/2][¶]

Adds an arc to the path.

The center of the arc is specified by c and radius by r. Both start and sweep angles are in radians. If the last vertex doesn't match the start of the arc then a line_to() would be emitted before adding the arc. Pass true in force_move_to to always emit move_to() at the beginning of the arc, which starts a new figure.

BLResult BLPath::arc_to(
double cx,
double cy,
double rx,
double ry,
double start,
double sweep,
bool force_move_to = false
)noexcept[2/2][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::arc_quadrant_to(
const BLPoint& p1,
const BLPoint& p2
)noexcept[1/2][¶]

Adds an arc quadrant (90deg) to the path. The first point p1 specifies the quadrant corner and the last point p2 specifies the end point.

BLResult BLPath::arc_quadrant_to(
double x1,
double y1,
double x2,
double y2
)noexcept[2/2][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::elliptic_arc_to(
const BLPoint& rp,
double xAxisRotation,
bool large_arc_flag,
bool sweep_flag,
const BLPoint& p1
)noexcept[1/2][¶]

Adds an elliptic arc to the path that follows the SVG specification.

Matches SVG 'A' path command:

BLResult BLPath::elliptic_arc_to(
double rx,
double ry,
double xAxisRotation,
bool large_arc_flag,
bool sweep_flag,
double x1,
double y1
)noexcept[2/2][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::close()noexcept[¶]

Closes the current figure.

Appends BL_PATH_CMD_CLOSE to the path.

Matches SVG 'Z' path command:

BLResult BLPath::add_box(
const BLBoxI& box,
)noexcept[1/3][¶]

Adds a closed rectangle to the path specified by box.

BLResult BLPath::add_box(
const BLBox& box,
)noexcept[2/3][¶]

Adds a closed rectangle to the path specified by box.

BLResult BLPath::add_box(
double x0,
double y0,
double x1,
double y1,
)noexcept[3/3][¶]

Adds a closed rectangle to the path specified by [x0, y0, x1, y1].

BLResult BLPath::add_rect(
const BLRectI& rect,
)noexcept[1/3][¶]

Adds a closed rectangle to the path specified by rect.

BLResult BLPath::add_rect(
const BLRect& rect,
)noexcept[2/3][¶]

Adds a closed rectangle to the path specified by rect.

BLResult BLPath::add_rect(
double x,
double y,
double w,
double h,
)noexcept[3/3][¶]

Adds a closed rectangle to the path specified by [x, y, w, h].

BLResult BLPath::add_geometry(
BLGeometryType geometry_type,
const void* geometry_data,
const BLMatrix2D* m = nullptr,
)noexcept[¶]

Adds a geometry to the path.

BLResult BLPath::add_circle(
const BLCircle& circle,
)noexcept[1/2][¶]

Adds a closed circle to the path.

BLResult BLPath::add_circle(
const BLCircle& circle,
const BLMatrix2D& transform,
)noexcept[2/2][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_ellipse(
const BLEllipse& ellipse,
)noexcept[1/2][¶]

Adds a closed ellipse to the path.

BLResult BLPath::add_ellipse(
const BLEllipse& ellipse,
const BLMatrix2D& transform,
)noexcept[2/2][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_round_rect(
const BLRoundRect& rr,
)noexcept[1/2][¶]

Adds a closed rounded rectangle to the path.

BLResult BLPath::add_round_rect(
const BLRoundRect& rr,
const BLMatrix2D& transform,
)noexcept[2/2][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_arc(
const BLArc& arc,
)noexcept[1/2][¶]

Adds an unclosed arc to the path.

BLResult BLPath::add_arc(
const BLArc& arc,
const BLMatrix2D& transform,
)noexcept[2/2][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_chord(
const BLArc& chord,
)noexcept[1/2][¶]

Adds a closed chord to the path.

BLResult BLPath::add_chord(
const BLArc& chord,
const BLMatrix2D& transform,
)noexcept[2/2][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_pie(
const BLArc& pie,
)noexcept[1/2][¶]

Adds a closed pie to the path.

BLResult BLPath::add_pie(
const BLArc& pie,
const BLMatrix2D& transform,
)noexcept[2/2][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_line(
const BLLine& line,
)noexcept[1/2][¶]

Adds an unclosed line to the path.

BLResult BLPath::add_line(
const BLLine& line,
const BLMatrix2D& transform,
)noexcept[2/2][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_triangle(
const BLTriangle& triangle,
)noexcept[1/2][¶]

Adds a closed triangle.

BLResult BLPath::add_triangle(
const BLTriangle& triangle,
const BLMatrix2D& transform,
)noexcept[2/2][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_polyline(
const BLArrayView<BLPointI>& poly,
)noexcept[1/8][¶]

Adds a polyline.

BLResult BLPath::add_polyline(
const BLArrayView<BLPointI>& poly,
const BLMatrix2D& transform,
)noexcept[2/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_polyline(
const BLPointI* poly,
size_t n,
)noexcept[3/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_polyline(
const BLPointI* poly,
size_t n,
const BLMatrix2D& transform,
)noexcept[4/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_polyline(
const BLArrayView<BLPoint>& poly,
)noexcept[5/8][¶]

Adds a polyline.

BLResult BLPath::add_polyline(
const BLArrayView<BLPoint>& poly,
const BLMatrix2D& transform,
)[6/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_polyline(
const BLPoint* poly,
size_t n,
)noexcept[7/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_polyline(
const BLPoint* poly,
size_t n,
const BLMatrix2D& transform,
)[8/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_polygon(
const BLArrayView<BLPointI>& poly,
)noexcept[1/8][¶]

Adds a polygon.

BLResult BLPath::add_polygon(
const BLArrayView<BLPointI>& poly,
const BLMatrix2D& transform,
)noexcept[2/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_polygon(
const BLPointI* poly,
size_t n,
)noexcept[3/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_polygon(
const BLPointI* poly,
size_t n,
const BLMatrix2D& transform,
)noexcept[4/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_polygon(
const BLArrayView<BLPoint>& poly,
)noexcept[5/8][¶]

Adds a polygon.

BLResult BLPath::add_polygon(
const BLArrayView<BLPoint>& poly,
const BLMatrix2D& transform,
)noexcept[6/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_polygon(
const BLPoint* poly,
size_t n,
)noexcept[7/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_polygon(
const BLPoint* poly,
size_t n,
const BLMatrix2D& transform,
)noexcept[8/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_box_array(
const BLArrayView<BLBoxI>& array,
)noexcept[1/8][¶]

Adds an array of closed boxes.

BLResult BLPath::add_box_array(
const BLArrayView<BLBoxI>& array,
const BLMatrix2D& transform,
)noexcept[2/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_box_array(
const BLBoxI* data,
size_t n,
)noexcept[3/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_box_array(
const BLBoxI* data,
size_t n,
const BLMatrix2D& transform,
)noexcept[4/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_box_array(
const BLArrayView<BLBox>& array,
)noexcept[5/8][¶]

Adds an array of closed boxes.

BLResult BLPath::add_box_array(
const BLArrayView<BLBox>& array,
const BLMatrix2D& transform,
)noexcept[6/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_box_array(
const BLBox* data,
size_t n,
)noexcept[7/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_box_array(
const BLBox* data,
size_t n,
const BLMatrix2D& transform,
)noexcept[8/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_rect_array(
const BLArrayView<BLRectI>& array,
)noexcept[1/8][¶]

Adds an array of closed rectangles.

BLResult BLPath::add_rect_array(
const BLArrayView<BLRectI>& array,
const BLMatrix2D& transform,
)noexcept[2/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_rect_array(
const BLRectI* data,
size_t n,
)noexcept[3/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_rect_array(
const BLRectI* data,
size_t n,
const BLMatrix2D& transform,
)noexcept[4/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_rect_array(
const BLArrayView<BLRect>& array,
)noexcept[5/8][¶]

Adds an array of closed rectangles.

BLResult BLPath::add_rect_array(
const BLArrayView<BLRect>& array,
const BLMatrix2D& transform,
)noexcept[6/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_rect_array(
const BLRect* data,
size_t n,
)noexcept[7/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_rect_array(
const BLRect* data,
size_t n,
const BLMatrix2D& transform,
)noexcept[8/8][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::add_path(
const BLPath& path
)noexcept[1/6][¶]

Adds other path to this path.

BLResult BLPath::add_path(
const BLPath& path,
const BLRange& range
)noexcept[2/6][¶]

Adds other path sliced by the given range to this path.

BLResult BLPath::add_path(
const BLPath& path,
const BLPoint& p
)noexcept[3/6][¶]

Adds other path translated by p to this path.

BLResult BLPath::add_path(
const BLPath& path,
const BLRange& range,
const BLPoint& p
)noexcept[4/6][¶]

Adds other path translated by p and sliced by the given range to this path.

BLResult BLPath::add_path(
const BLPath& path,
const BLMatrix2D& transform
)noexcept[5/6][¶]

Adds other path transformed by m to this path.

BLResult BLPath::add_path(
const BLPath& path,
const BLRange& range,
const BLMatrix2D& transform
)noexcept[6/6][¶]

Adds other path transformed by m and sliced by the given range to this path.

BLResult BLPath::add_reversed_path(
const BLPath& path,
BLPathReverseMode reverse_mode
)noexcept[1/2][¶]

Adds other path, but reversed.

BLResult BLPath::add_reversed_path(
const BLPath& path,
const BLRange& range,
BLPathReverseMode reverse_mode
)noexcept[2/2][¶]

Adds other path, but reversed.

BLResult BLPath::add_stroked_path(
const BLPath& path,
const BLStrokeOptionsCore& stroke_options,
const BLApproximationOptions& approximation_options
)noexcept[1/2][¶]

Adds a stroke of path to this path.

BLResult BLPath::add_stroked_path(
const BLPath& path,
const BLRange& range,
const BLStrokeOptionsCore& stroke_options,
const BLApproximationOptions& approximation_options
)noexcept[2/2][¶]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

BLResult BLPath::translate(
const BLPoint& p
)noexcept[1/2][¶]

Translates the whole path by p.

BLResult BLPath::translate(
const BLRange& range,
const BLPoint& p
)noexcept[2/2][¶]

Translates a part of the path specified by the given range by p.

BLResult BLPath::transform(
const BLMatrix2D& m
)noexcept[1/2][¶]

Transforms the whole path by matrix m.

BLResult BLPath::transform(
const BLRange& range,
const BLMatrix2D& m
)noexcept[2/2][¶]

Transforms a part of the path specified by the given range by matrix m.

BLResult BLPath::fit_to(
const BLRect& rect,
uint32_t fit_flags
)noexcept[1/2][¶]

Fits the whole path into the given rect by taking into account fit flags passed by fit_flags.

BLResult BLPath::fit_to(
const BLRange& range,
const BLRect& rect,
uint32_t fit_flags
)noexcept[2/2][¶]

Fits a path of the path specified by the given range into the given rect by taking into account fit flags passed by fit_flags.

bool BLPath::equals(
const BLPath& other
) constnodiscardnoexcept[¶]

Tests whether this path and the other path are equal.

The equality check is deep. The data of both paths is examined and binary compared (thus a slight difference like -0 and +0 would make the equality check to fail).

BLResult BLPath::get_info_flags(
uint32_t* flags_out
) constnoexcept[¶]

Update a path information if necessary.

BLResult BLPath::get_control_box(
BLBox* box_out
) constnoexcept[¶]

Stores a bounding box of all vertices and control points to box_out.

Control box is simply bounds of all vertices the path has without further processing. It contains both on-path and off-path points. Consider using get_bounding_box() if you need a visual bounding box.

BLResult BLPath::get_bounding_box(
BLBox* box_out
) constnoexcept[¶]

Stores a bounding box of all on-path vertices and curve extrema to box_out.

The bounding box stored to box_out could be smaller than a bounding box obtained by get_control_box() as it's calculated by merging only start/end points and curves at their extrema (not control points). The resulting bounding box represents a visual bounds of the path.

BLResult BLPath::get_figure_range(
size_t index,
BLRange* range_out
) constnoexcept[¶]

Returns the range describing a figure at the given index.

BLResult BLPath::get_last_vertex(
BLPoint* vtx_out
) constnoexcept[¶]

Returns the last vertex of the path and stores it to vtx_out. If the very last command of the path is BL_PATH_CMD_CLOSE then the path will be iterated in reverse order to match the initial vertex of the last figure.

BLHitTest BLPath::hit_test(
const BLPoint& p,
BLFillRule fill_rule
) constnodiscardnoexcept[¶]

Hit tests the given point p by respecting the given fill_rule.