Stroke
public final class Stroke
An immutable object comprised of a StrokeInputBatch that represents a user-drawn (or sometimes synthetic) path, a Brush that contains information on how that path should be converted into a geometric shape and rendered on screen, and a PartitionedMesh which is the geometric shape calculated from the combination of the StrokeInputBatch and the Brush.
This can be constructed directly from a StrokeInputBatch that has already been completed. To construct a stroke incrementally and render it as input events are received in real time, use androidx.ink.authoring.InProgressStrokesView or InProgressStroke, which will ultimately return a Stroke when input is completed.
Summary
Public constructors |
|---|
Stroke(@NonNull Brush brush, @NonNull StrokeInputBatch inputs)Construct a |
Stroke(Construct a |
Public methods |
|
|---|---|
final @NonNull Stroke |
Returns a |
final @NonNull Brush |
getBrush()Contains information on how the |
final @NonNull ImmutableStrokeInputBatch |
The user-drawn (or perhaps synthetically generated) path that this |
final @NonNull PartitionedMesh |
getShape()The geometric shape of the |
final @NonNull Set<@NonNull Stroke> |
@<error>Splits this stroke into a set of spatially disconnected |
final @NonNull Stroke |
@<error>Subtracts |
@NonNull String |
toString() |
Public constructors
Stroke
public Stroke(@NonNull Brush brush, @NonNull StrokeInputBatch inputs)
Construct a Stroke given a Brush and a StrokeInputBatch, generating its shape.
Stroke
public Stroke(
@NonNull Brush brush,
@NonNull StrokeInputBatch inputs,
@NonNull PartitionedMesh shape
)
Construct a Stroke given a Brush, a StrokeInputBatch, and a PartitionedMesh.
Note that this does not do any validation that brush and inputs together would produce shape. This constructor is primarily intended for deserialization, in cases where the PartitionedMesh is being stored in addition to the Brush and StrokeInputBatch.
Public methods
copy
public final @NonNull Stroke copy(@NonNull Brush brush)
Returns a Stroke with the brush replaced. This may or may not affect the shape, but will not change the inputs.
getBrush
public final @NonNull Brush getBrush()
Contains information on how the inputs should be used to calculate the shape and how that shape should be drawn on screen.
getInputs
public final @NonNull ImmutableStrokeInputBatch getInputs()
The user-drawn (or perhaps synthetically generated) path that this Stroke takes.
getShape
public final @NonNull PartitionedMesh getShape()
The geometric shape of the Stroke, which can be used to render it on screen and to perform geometric calculations. This PartitionedMesh will have one render group per brush coat in brush.
split
@<error>
public final @NonNull Set<@NonNull Stroke> split(@NonNull AffineTransform strokeToWorldTransform, float tolerance)
Splits this stroke into a set of spatially disconnected Strokes.
Two regions of the stroke are considered disconnected if they are further than tolerance distance apart, applying the given strokeToWorldTransform.
The tolerance parameter is useful to prevent the over-splitting of strokes. This helps maintain continuity in strokes that inherently contain geometric gaps (such as particle brushes), or in solid strokes where minor unintentional gaps are introduced (for example by glancing erases). For splitting a stroke that has been partially erased (with subtract) by eraser strokes, it may be natural to set tolerance to the size of the eraser brush.
Each resulting stroke has a new shape representing its portion, but retains the original inputs and brush. Each returned stroke can have its brush color updated (with brush copy), but modifying other properties (like brush size) will revert the stroke to the shape of the original stroke.
Note that split can be a computationally expensive geometric operation, and should generally be performed on a background (worker) thread to avoid blocking the UI thread.
| Parameters | |
|---|---|
@NonNull AffineTransform strokeToWorldTransform |
The |
float tolerance |
The maximum distance in world coordinates between two points to consider them connected. |
subtract
@<error>
public final @NonNull Stroke subtract(
@NonNull PartitionedMesh maskShape,
@NonNull AffineTransform maskToWorldTransform,
@NonNull AffineTransform strokeToWorldTransform
)
Subtracts maskShape from this stroke and returns the remaining portion as a new Stroke.
The returned stroke has a newly computed shape representing the shape after subtraction, but retains the original inputs and brush. The stroke can have its brush color updated (with copy), but modifying other properties (like brush size) will revert the stroke to its original shape and undo the subtraction. The stroke may be empty or contain disconnected geometry -- to separate disconnected regions into independent Stroke instances, call split.
Note that subtract can be a computationally expensive geometric operation, and should generally be performed on a background (worker) thread to avoid blocking the UI thread.
| Parameters | |
|---|---|
@NonNull PartitionedMesh maskShape |
A |
@NonNull AffineTransform maskToWorldTransform |
The |
@NonNull AffineTransform strokeToWorldTransform |
The |