Skip to content

Commit c249b70

Browse files
dnfieldHixie
authored andcommitted
Path metrics/getBounds/combinations again (flutter#4957)
* add path measure * fix typo * getBound and addPathWithMatrix * Add myself to Authors, add PathOps * fix linting issues * update licenses_flutter to add new files * Use matrix4 instead of matrix3 for consistency/interop * put pubspec back * fix bug in getSegment * fix typo * Add return value for PathOp * refactoring from review * refactoring from review - still TBD on computeMetrics() * add doc * lint issue * fix computeMetrics, add Path.from * add missing wireup for clone * change PathMetrics to iterable, fix bug with angle on Tangent * prefer std::make_unique * cleanup docs * add path measure * fix typo * getBound and addPathWithMatrix * Add myself to Authors, add PathOps * fix linting issues * update licenses_flutter to add new files * Use matrix4 instead of matrix3 for consistency/interop * put pubspec back * fix bug in getSegment * fix typo * Add return value for PathOp * refactoring from review * refactoring from review - still TBD on computeMetrics() * add doc * lint issue * fix computeMetrics, add Path.from * add missing wireup for clone * change PathMetrics to iterable, fix bug with angle on Tangent * prefer std::make_unique * cleanup docs * fix iterator bug * remove unnecessary clone for computeMetrics * fix some doc issues * fix PathMeasure iterator, extendWithPath, isClosed, and pubspec.lock * get rid of orElse; use StateException * StateError, not StateException * doc improvements and nits * add unit tests, fix bugs found during testing * fix two uncommited doc changes * one more * change sign of tangent angle, update docs * update unit tests for inverted angle * update tangent to include vector * Doc fixes * Fix MSVC compilation and unit test
1 parent df255b8 commit c249b70

11 files changed

Lines changed: 739 additions & 11 deletions

File tree

‎lib/ui/BUILD.gn‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,8 @@ source_set("ui") {
3636
"painting/paint.h",
3737
"painting/path.cc",
3838
"painting/path.h",
39+
"painting/path_measure.cc",
40+
"painting/path_measure.h",
3941
"painting/picture.cc",
4042
"painting/picture.h",
4143
"painting/picture_recorder.cc",

‎lib/ui/dart_ui.cc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
#include "flutter/lib/ui/painting/image_filter.h"
1616
#include "flutter/lib/ui/painting/image_shader.h"
1717
#include "flutter/lib/ui/painting/path.h"
18+
#include "flutter/lib/ui/painting/path_measure.h"
1819
#include "flutter/lib/ui/painting/picture.h"
1920
#include "flutter/lib/ui/painting/picture_recorder.h"
2021
#include "flutter/lib/ui/painting/vertices.h"
@@ -53,6 +54,7 @@ void DartUI::InitForGlobal() {
5354
CanvasGradient::RegisterNatives(g_natives);
5455
CanvasImage::RegisterNatives(g_natives);
5556
CanvasPath::RegisterNatives(g_natives);
57+
CanvasPathMeasure::RegisterNatives(g_natives);
5658
Codec::RegisterNatives(g_natives);
5759
DartRuntimeHooks::RegisterNatives(g_natives);
5860
FrameInfo::RegisterNatives(g_natives);

‎lib/ui/painting.dart‎

Lines changed: 296 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,12 @@ bool _offsetIsValid(Offset offset) {
3939
return true;
4040
}
4141

42+
bool _matrix4IsValid(Float64List matrix4) {
43+
assert(matrix4 != null, 'Matrix4 argument was null.');
44+
assert(matrix4.length == 16, 'Matrix4 must have 16 entries.');
45+
return true;
46+
}
47+
4248
bool _radiusIsValid(Radius radius) {
4349
assert(radius != null, 'Radius argument was null.');
4450
assert(!radius.x.isNaN && !radius.y.isNaN, 'Radius argument contained a NaN value.');
@@ -1390,6 +1396,62 @@ enum PathFillType {
13901396
evenOdd,
13911397
}
13921398

1399+
/// Strategies for combining paths.
1400+
///
1401+
/// See also:
1402+
///
1403+
/// * [Path.combine], which uses this enum to decide how to combine two paths.
1404+
// Must be kept in sync with SkPathOp
1405+
enum PathOperation {
1406+
/// Subtract the second path from the first path.
1407+
///
1408+
/// For example, if the two paths are overlapping circles of equal diameter
1409+
/// but differing centers, the result would be a crescent portion of the
1410+
/// first circle that was not overlapped by the second circle.
1411+
///
1412+
/// See also:
1413+
///
1414+
/// * [reverseDifference], which is the same but subtracting the first path
1415+
/// from the second.
1416+
difference,
1417+
/// Create a new path that is the intersection of the two paths, leaving the
1418+
/// overlapping pieces of the path.
1419+
///
1420+
/// For example, if the two paths are overlapping circles of equal diameter
1421+
/// but differing centers, the result would be only the overlapping portion
1422+
/// of the two circles.
1423+
///
1424+
/// See also:
1425+
/// * [xor], which is the inverse of this operation
1426+
intersect,
1427+
/// Create a new path that is the union (inclusive-or) of the two paths.
1428+
///
1429+
/// For example, if the two paths are overlapping circles of equal diameter
1430+
/// but differing centers, the result would be a figure-eight like shape
1431+
/// matching the outter boundaries of both circles.
1432+
union,
1433+
/// Create a new path that is the exclusive-or of the two paths, leaving
1434+
/// everything but the overlapping pieces of the path.
1435+
///
1436+
/// For example, if the two paths are overlapping circles of equal diameter
1437+
/// but differing centers, the figure-eight like shape less the overlapping parts
1438+
///
1439+
/// See also:
1440+
/// * [intersect], which is the inverse of this operation
1441+
xor,
1442+
/// Subtract the first path from the second path.
1443+
///
1444+
/// For example, if the two paths are overlapping circles of equal diameter
1445+
/// but differing centers, the result would be a crescent portion of the
1446+
/// second circle that was not overlapped by the first circle.
1447+
///
1448+
/// See also:
1449+
///
1450+
/// * [difference], which is the same but subtracting the second path
1451+
/// from the frist.
1452+
reverseDifference,
1453+
}
1454+
13931455
/// A complex, one-dimensional subset of a plane.
13941456
///
13951457
/// A path consists of a number of subpaths, and a _current point_.
@@ -1412,6 +1474,15 @@ class Path extends NativeFieldWrapperClass2 {
14121474
Path() { _constructor(); }
14131475
void _constructor() native 'Path_constructor';
14141476

1477+
/// Creates a copy of another [Path].
1478+
///
1479+
/// This copy is fast and does not require additional memory unless either
1480+
/// the `source` path or the path returned by this constructor are modified.
1481+
factory Path.from(Path source) {
1482+
return source._clone();
1483+
}
1484+
Path _clone() native 'Path_clone';
1485+
14151486
/// Determines how the interior of this path is calculated.
14161487
///
14171488
/// Defaults to the non-zero winding rule, [PathFillType.nonZero].
@@ -1609,23 +1680,43 @@ class Path extends NativeFieldWrapperClass2 {
16091680
}
16101681
void _addRRect(Float32List rrect) native 'Path_addRRect';
16111682

1612-
/// Adds a new subpath that consists of the given path offset by the given
1613-
/// offset.
1614-
void addPath(Path path, Offset offset) {
1683+
/// Adds a new subpath that consists of the given `path` offset by the given
1684+
/// `offset`.
1685+
///
1686+
/// If `matrix4` is specified, the path will be transformed by this matrix
1687+
/// after the matrix is translated by the given offset. The matrix is a 4x4
1688+
/// matrix stored in column major order.
1689+
void addPath(Path path, Offset offset, {Float64List matrix4}) {
16151690
assert(path != null); // path is checked on the engine side
16161691
assert(_offsetIsValid(offset));
1617-
_addPath(path, offset.dx, offset.dy);
1692+
if (matrix4 != null) {
1693+
assert(_matrix4IsValid(matrix4));
1694+
_addPathWithMatrix(path, offset.dx, offset.dy, matrix4);
1695+
} else {
1696+
_addPath(path, offset.dx, offset.dy);
1697+
}
16181698
}
16191699
void _addPath(Path path, double dx, double dy) native 'Path_addPath';
1620-
1700+
void _addPathWithMatrix(Path path, double dx, double dy, Float64List matrix) native 'Path_addPathWithMatrix';
1701+
16211702
/// Adds the given path to this path by extending the current segment of this
16221703
/// path with the the first segment of the given path.
1623-
void extendWithPath(Path path, Offset offset) {
1704+
///
1705+
/// If `matrix4` is specified, the path will be transformed by this matrix
1706+
/// after the matrix is translated by the given `offset`. The matrix is a 4x4
1707+
/// matrix stored in column major order.
1708+
void extendWithPath(Path path, Offset offset, {Float64List matrix4}) {
16241709
assert(path != null); // path is checked on the engine side
16251710
assert(_offsetIsValid(offset));
1626-
_extendWithPath(path, offset.dx, offset.dy);
1711+
if (matrix4 != null) {
1712+
assert(_matrix4IsValid(matrix4));
1713+
_extendWithPathAndMatrix(path, offset.dx, offset.dy, matrix4);
1714+
} else {
1715+
_extendWithPath(path, offset.dx, offset.dy);
1716+
}
16271717
}
16281718
void _extendWithPath(Path path, double dx, double dy) native 'Path_extendWithPath';
1719+
void _extendWithPathAndMatrix(Path path, double dx, double dy, Float64List matrix) native 'Path_extendWithPathAndMatrix';
16291720

16301721
/// Closes the last subpath, as if a straight line had been drawn
16311722
/// from the current point to the first point of the subpath.
@@ -1660,12 +1751,207 @@ class Path extends NativeFieldWrapperClass2 {
16601751
/// Returns a copy of the path with all the segments of every
16611752
/// subpath transformed by the given matrix.
16621753
Path transform(Float64List matrix4) {
1663-
assert(matrix4 != null);
1664-
if (matrix4.length != 16)
1665-
throw new ArgumentError('"matrix4" must have 16 entries.');
1754+
assert(_matrix4IsValid(matrix4));
16661755
return _transform(matrix4);
16671756
}
16681757
Path _transform(Float64List matrix4) native 'Path_transform';
1758+
1759+
/// Computes the bounding rectangle for this path.
1760+
Rect getBounds() {
1761+
final Float32List rect = _getBounds();
1762+
return new Rect.fromLTRB(rect[0], rect[1], rect[2], rect[3]);
1763+
}
1764+
Float32List _getBounds() native 'Path_getBounds';
1765+
1766+
/// Combines the two paths according to the manner specified by the given
1767+
/// `operation`.
1768+
///
1769+
/// The resulting path will be constructed from non-overlapping contours. The
1770+
/// curve order is reduced where possible so that cubics may be turned into
1771+
/// quadratics, and quadratics maybe turned into lines.
1772+
static Path combine(PathOperation operation, Path path1, Path path2) {
1773+
assert(path1 != null);
1774+
assert(path2 != null);
1775+
final Path path = new Path();
1776+
if (path._op(path1, path2, operation.index)) {
1777+
return path;
1778+
}
1779+
throw new StateError('Path.combine() failed. This may be due an invalid path; in particular, check for NaN values.');
1780+
}
1781+
bool _op(Path path1, Path path2, int operation) native 'Path_op';
1782+
1783+
/// Creates a [PathMetrics] object for this path.
1784+
///
1785+
/// If `forceClosed` is set to true, the contours of the path will be measured
1786+
/// as if they had been closed, even if they were not explicitly closed.
1787+
PathMetrics computeMetrics({bool forceClosed: false}) {
1788+
return new PathMetrics._(this, forceClosed);
1789+
}
1790+
}
1791+
1792+
/// The geometric description of a tangent: the angle at a point.
1793+
///
1794+
/// See also:
1795+
/// * [PathMetric.getTangentForOffset], which returns the tangent of an offset along a path.
1796+
class Tangent {
1797+
/// Creates a [Tangent] with the given values.
1798+
///
1799+
/// The arguments must not be null.
1800+
const Tangent(this.position, this.vector)
1801+
: assert(position != null),
1802+
assert(vector != null);
1803+
1804+
/// Creates a [Tangent] based on the angle rather than the vector.
1805+
///
1806+
/// The [vector] is computed to be the unit vector at the given angle, interpreted
1807+
/// as clockwise radians from the x axis.
1808+
factory Tangent.fromAngle(Offset position, double angle) {
1809+
return new Tangent(position, new Offset(math.cos(angle), math.sin(angle)));
1810+
}
1811+
1812+
/// Position of the tangent.
1813+
///
1814+
/// When used with [PathMetric.getTangentForOffset], this represents the precise
1815+
/// position that the given offset along the path corresponds to.
1816+
final Offset position;
1817+
1818+
/// The vector of the curve at [position].
1819+
///
1820+
/// When used with [PathMetric.getTangentForOffset], this is the vector of the
1821+
/// curve that is at the given offset along the path (i.e. the direction of the
1822+
/// curve at [position]).
1823+
final Offset vector;
1824+
1825+
/// The direction of the curve at [position].
1826+
///
1827+
/// When used with [PathMetric.getTangentForOffset], this is the angle of the
1828+
/// curve that is the given offset along the path (i.e. the direction of the
1829+
/// curve at [position]).
1830+
///
1831+
/// This value is in radians, with 0.0 meaning pointing along the x axis in
1832+
/// the positive x-axis direction, positive numbers pointing downward toward
1833+
/// the negative y-axis, i.e. in a clockwise direction, and negative numbers
1834+
/// pointing upward toward the positive y-axis, i.e. in a counter-clockwise
1835+
/// direction.
1836+
// flip the sign to be consistent with [Path.arcTo]'s `sweepAngle`
1837+
double get angle => -math.atan2(vector.dy, vector.dx);
1838+
}
1839+
1840+
/// An iterable collection of [PathMetric] objects describing a [Path].
1841+
///
1842+
/// A [PathMetrics] object is created by using the [Path.computeMetrics] method,
1843+
/// and represents the path as it stood at the time of the call. Subsequent
1844+
/// modifications of the path do not affect the [PathMetrics] object.
1845+
///
1846+
/// Each path metric corresponds to a segment, or contour, of a path.
1847+
///
1848+
/// For example, a path consisting of a [Path.lineTo], a [Path.moveTo], and
1849+
/// another [Path.lineTo] will contain two contours and thus be represented by
1850+
/// two [PathMetric] objects.
1851+
///
1852+
/// When iterating across a [PathMetrics]' contours, the [PathMetric] objects are only
1853+
/// valid until the next one is obtained.
1854+
class PathMetrics extends collection.IterableBase<PathMetric> {
1855+
PathMetrics._(Path path, bool forceClosed) :
1856+
_iterator = new PathMetricIterator._(new PathMetric._(path, forceClosed));
1857+
1858+
final Iterator<PathMetric> _iterator;
1859+
1860+
@override
1861+
Iterator<PathMetric> get iterator => _iterator;
1862+
}
1863+
1864+
/// Tracks iteration from one segment of a path to the next for measurement.
1865+
class PathMetricIterator implements Iterator<PathMetric> {
1866+
PathMetricIterator._(this._pathMetric);
1867+
1868+
PathMetric _pathMetric;
1869+
bool _firstTime = true;
1870+
1871+
@override
1872+
PathMetric get current => _firstTime ? null : _pathMetric;
1873+
1874+
@override
1875+
bool moveNext() {
1876+
// PathMetric isn't a normal iterable - it's already initialized to its
1877+
// first Path. Should only call _moveNext when done with the first one.
1878+
if (_firstTime == true) {
1879+
_firstTime = false;
1880+
return true;
1881+
} else if (_pathMetric?._moveNext() == true) {
1882+
return true;
1883+
}
1884+
_pathMetric = null;
1885+
return false;
1886+
}
1887+
}
1888+
1889+
/// Utilities for measuring a [Path] and extracting subpaths.
1890+
///
1891+
/// Iterate over the object returned by [Path.computeMetrics] to obtain
1892+
/// [PathMetric] objects.
1893+
///
1894+
/// Once created, metrics will only be valid while the iterator is at the given
1895+
/// contour. When the next contour's [PathMetric] is obtained, this object
1896+
/// becomes invalid.
1897+
class PathMetric extends NativeFieldWrapperClass2 {
1898+
/// Create a new empty [Path] object.
1899+
PathMetric._(Path path, bool forceClosed) { _constructor(path, forceClosed); }
1900+
void _constructor(Path path, bool forceClosed) native 'PathMeasure_constructor';
1901+
1902+
/// Return the total length of the current contour.
1903+
double get length native 'PathMeasure_getLength';
1904+
1905+
/// Computes the position of hte current contour at the given offset, and the
1906+
/// angle of the path at that point.
1907+
///
1908+
/// For example, calling this method with a distance of 1.41 for a line from
1909+
/// 0.0,0.0 to 2.0,2.0 would give a point 1.0,1.0 and the angle 45 degrees
1910+
/// (but in radians).
1911+
///
1912+
/// Returns null if the contour has zero [length].
1913+
///
1914+
/// The distance is clamped to the [length] of the current contour.
1915+
Tangent getTangentForOffset(double distance) {
1916+
final Float32List posTan = _getPosTan(distance);
1917+
// first entry == 0 indicates that Skia returned false
1918+
if (posTan[0] == 0.0) {
1919+
return null;
1920+
} else {
1921+
return new Tangent(
1922+
new Offset(posTan[1], posTan[2]),
1923+
new Offset(posTan[3], posTan[4])
1924+
);
1925+
}
1926+
}
1927+
Float32List _getPosTan(double distance) native 'PathMeasure_getPosTan';
1928+
1929+
/// Given a start and stop distance, return the intervening segment(s).
1930+
///
1931+
/// `start` and `end` are pinned to legal values (0..[length])
1932+
/// Returns null if the segment is 0 length or `start` > `stop`.
1933+
/// Begin the segment with a moveTo if `startWithMoveTo` is true.
1934+
Path extractPath(double start, double end, {bool startWithMoveTo: true}) native 'PathMeasure_getSegment';
1935+
1936+
/// Whether the contour is closed.
1937+
///
1938+
/// Returns true if the contour ends with a call to [Path.close] (which may
1939+
/// have been implied when using [Path.addRect]) or if `forceClosed` was
1940+
/// specified as true in the call to [Path.computeMetrics]. Returns false
1941+
/// otherwise.
1942+
bool get isClosed native 'PathMeasure_isClosed';
1943+
1944+
// Move to the next contour in the path.
1945+
//
1946+
// A path can have a next contour if [Path.moveTo] was called after drawing began.
1947+
// Return true if one exists, or false.
1948+
//
1949+
// This is not exactly congruent with a regular [Iterator.moveNext].
1950+
// Typically, [Iterator.moveNext] should be called before accessing the
1951+
// [Iterator.current]. In this case, the [PathMetric] is valid before
1952+
// calling `_moveNext` - `_moveNext` should be called after the first
1953+
// iteration is done instead of before.
1954+
bool _moveNext() native 'PathMeasure_nextContour';
16691955
}
16701956

16711957
/// Styles to use for blurs in [MaskFilter] objects.

0 commit comments

Comments
 (0)