diff --git a/CHANGELOG.md b/CHANGELOG.md index ac03ea2b..4c98cd04 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ - Remove the deprecated `SimplexNoise` class. - Optimized the `identity` constructors on the `Matrix` classes. +- Documented the public `Plane` and geometry filter APIs. ## 2.3.0 diff --git a/lib/src/vector_math/plane.dart b/lib/src/vector_math/plane.dart index dac6ebad..0fc40124 100644 --- a/lib/src/vector_math/plane.dart +++ b/lib/src/vector_math/plane.dart @@ -4,8 +4,11 @@ part of '../../vector_math.dart'; +/// Defines a plane with a [normal] vector and a [constant]. class Plane { final Vector3 _normal; + + /// The constant term in the plane equation. double constant; /// Find the intersection point between the three planes [a], [b] and [c] and @@ -33,35 +36,44 @@ class Plane { ..z = (v1.z + v2.z + v3.z) / f; } + /// The normal vector of this plane. Vector3 get normal => _normal; + /// Create a plane with a zero [normal] and zero [constant]. Plane() : _normal = Vector3.zero(), constant = 0.0; + /// Create a plane as a copy of [other]. Plane.copy(Plane other) : _normal = Vector3.copy(other._normal), constant = other.constant; + /// Create a plane from normal components and a [constant]. Plane.components(double x, double y, double z, this.constant) : _normal = Vector3(x, y, z); + /// Create a plane from a normal vector and a [constant]. Plane.normalconstant(Vector3 normal_, this.constant) : _normal = Vector3.copy(normal_); + /// Copy the [normal] and [constant] from [o] into this. void copyFrom(Plane o) { _normal.setFrom(o._normal); constant = o.constant; } + /// Set the normal components and constant term of this plane. void setFromComponents(double x, double y, double z, double w) { _normal.setValues(x, y, z); constant = w; } + /// Normalize this plane so that [normal] has unit length. void normalize() { final inverseLength = 1.0 / normal.length; _normal.scale(inverseLength); constant *= inverseLength; } + /// Return the signed distance from [point] to this plane. double distanceToVector3(Vector3 point) => _normal.dot(point) + constant; } diff --git a/lib/src/vector_math_64/plane.dart b/lib/src/vector_math_64/plane.dart index 70fece85..09ab8598 100644 --- a/lib/src/vector_math_64/plane.dart +++ b/lib/src/vector_math_64/plane.dart @@ -4,8 +4,11 @@ part of '../../vector_math_64.dart'; +/// Defines a plane with a [normal] vector and a [constant]. class Plane { final Vector3 _normal; + + /// The constant term in the plane equation. double constant; /// Find the intersection point between the three planes [a], [b] and [c] and @@ -33,35 +36,44 @@ class Plane { ..z = (v1.z + v2.z + v3.z) / f; } + /// The normal vector of this plane. Vector3 get normal => _normal; + /// Create a plane with a zero [normal] and zero [constant]. Plane() : _normal = Vector3.zero(), constant = 0.0; + /// Create a plane as a copy of [other]. Plane.copy(Plane other) : _normal = Vector3.copy(other._normal), constant = other.constant; + /// Create a plane from normal components and a [constant]. Plane.components(double x, double y, double z, this.constant) : _normal = Vector3(x, y, z); + /// Create a plane from a normal vector and a [constant]. Plane.normalconstant(Vector3 normal_, this.constant) : _normal = Vector3.copy(normal_); + /// Copy the [normal] and [constant] from [o] into this. void copyFrom(Plane o) { _normal.setFrom(o._normal); constant = o.constant; } + /// Set the normal components and constant term of this plane. void setFromComponents(double x, double y, double z, double w) { _normal.setValues(x, y, z); constant = w; } + /// Normalize this plane so that [normal] has unit length. void normalize() { final inverseLength = 1.0 / normal.length; _normal.scale(inverseLength); constant *= inverseLength; } + /// Return the signed distance from [point] to this plane. double distanceToVector3(Vector3 point) => _normal.dot(point) + constant; } diff --git a/lib/src/vector_math_geometry/filters/barycentric_filter.dart b/lib/src/vector_math_geometry/filters/barycentric_filter.dart index 34845f22..e6d91c67 100644 --- a/lib/src/vector_math_geometry/filters/barycentric_filter.dart +++ b/lib/src/vector_math_geometry/filters/barycentric_filter.dart @@ -4,6 +4,7 @@ part of '../../../vector_math_geometry.dart'; +/// Adds barycentric coordinates for each triangle vertex in a mesh. class BarycentricFilter extends GeometryFilter { @override List get generates => [ diff --git a/lib/src/vector_math_geometry/filters/color_filter.dart b/lib/src/vector_math_geometry/filters/color_filter.dart index cecd6f02..31d055d2 100644 --- a/lib/src/vector_math_geometry/filters/color_filter.dart +++ b/lib/src/vector_math_geometry/filters/color_filter.dart @@ -4,9 +4,12 @@ part of '../../../vector_math_geometry.dart'; +/// Assigns a single color to every vertex in a mesh. class ColorFilter extends GeometryFilter { + /// The color written to each output vertex. Vector4 color; + /// Creates a filter that writes [color] into the mesh `COLOR` attribute. ColorFilter(this.color); @override diff --git a/lib/src/vector_math_geometry/filters/flat_shade_filter.dart b/lib/src/vector_math_geometry/filters/flat_shade_filter.dart index 290fbce7..9b6bd86b 100644 --- a/lib/src/vector_math_geometry/filters/flat_shade_filter.dart +++ b/lib/src/vector_math_geometry/filters/flat_shade_filter.dart @@ -4,6 +4,7 @@ part of '../../../vector_math_geometry.dart'; +/// Expands a mesh to triangle vertices and generates flat-shaded normals. class FlatShadeFilter extends GeometryFilter { @override List get requires => [ diff --git a/lib/src/vector_math_geometry/filters/geometry_filter.dart b/lib/src/vector_math_geometry/filters/geometry_filter.dart index b028d450..6ab21688 100644 --- a/lib/src/vector_math_geometry/filters/geometry_filter.dart +++ b/lib/src/vector_math_geometry/filters/geometry_filter.dart @@ -4,15 +4,23 @@ part of '../../../vector_math_geometry.dart'; +/// A filter that produces a transformed copy of a [MeshGeometry]. abstract class GeometryFilter { + /// Whether this filter supports in-place modification of a mesh. bool get inplace => false; - List get requires => []; - List get generates => []; + + /// Vertex attributes that must be present on the input mesh. + List get requires => const []; + + /// Vertex attributes that this filter guarantees on the output mesh. + List get generates => const []; /// Returns a copy of the mesh with any filter transforms applied. MeshGeometry filter(MeshGeometry mesh); } +/// A [GeometryFilter] that can apply its transformation directly to a mesh +/// in-place. abstract class InplaceGeometryFilter extends GeometryFilter { @override bool get inplace => true; diff --git a/lib/src/vector_math_geometry/filters/invert_filter.dart b/lib/src/vector_math_geometry/filters/invert_filter.dart index 3d1ec158..715bc646 100644 --- a/lib/src/vector_math_geometry/filters/invert_filter.dart +++ b/lib/src/vector_math_geometry/filters/invert_filter.dart @@ -4,6 +4,7 @@ part of '../../../vector_math_geometry.dart'; +/// Reverses triangle winding and flips normals for a mesh. class InvertFilter extends InplaceGeometryFilter { @override void filterInplace(MeshGeometry mesh) { diff --git a/lib/src/vector_math_geometry/filters/transform_filter.dart b/lib/src/vector_math_geometry/filters/transform_filter.dart index ac3c6448..565790e1 100644 --- a/lib/src/vector_math_geometry/filters/transform_filter.dart +++ b/lib/src/vector_math_geometry/filters/transform_filter.dart @@ -4,9 +4,12 @@ part of '../../../vector_math_geometry.dart'; +/// Applies a matrix transform to each mesh position in-place. class TransformFilter extends InplaceGeometryFilter { + /// The transform applied to each position in the mesh. Matrix4 transform; + /// Creates a filter that transforms positions using [transform]. TransformFilter(this.transform); @override