InProgressStroke

public final class InProgressStroke

Use an InProgressStroke to efficiently build a stroke over multiple rendering frames with incremental inputs.

To use an InProgressStroke, you would typically:

  1. Begin a stroke by calling start with a chosen Brush.

  2. Repeatedly update the stroke:

    1. Call enqueueInputs with any new real and predicted stroke inputs.

    2. Call updateShape when needsUpdate is true and new geometry is needed for rendering.

    3. Render the current stroke mesh or outlines, either via a provided renderer that accepts an InProgressStroke or by using the various getters on this type with a custom renderer.

  3. Call finishInput once there are no more inputs for this stroke (e.g. the user lifts the stylus from the screen).

  4. Continue to call updateShape and render after finishInput until getNeedsUpdate returns false (to allow any lingering brush animations to complete).

  5. Extract the completed stroke by calling toImmutable.

  6. For best performance, reuse this object and go back to step 1 rather than allocating a new instance.

Summary

Public constructors

Public methods
final @NonNull Result<Unit>
enqueueInputs(
    @NonNull StrokeInputBatch realInputs,
    @NonNull StrokeInputBatch predictedInputs
)

Enqueues the incremental realInputs and sets the prediction to predictedInputs, overwriting any previous prediction.
final void
enqueueInputsOrThrow(
    @NonNull StrokeInputBatch realInputs,
    @NonNull StrokeInputBatch predictedInputs
)
final void

Indicates that the inputs for the current stroke are finished.
final Brush

The Brush currently being used to generate the stroke content.
final @IntRange(from = 0) int

Returns the number of BrushCoats for the current brush, or zero if start has not been called.
final @IntRange(from = 0) int

Returns the number of StrokeInputs in the stroke so far.
final boolean

Returns true if calling updateShape would have any effect on the stroke (and should thus be called before the next render), or false if no calls to updateShape are currently needed.
final @IntRange(from = 0) int
getOutlineCount(@IntRange(from = 0) int coatIndex)

Returns the number of outlines for the specified brush coat.
final @IntRange(from = 0) int
getOutlineVertexCount(
    @IntRange(from = 0) int coatIndex,
    @IntRange(from = 0) int outlineIndex
)

Returns the number of outline points for the specified outline and brush coat.
final @IntRange(from = 0) int

Returns the number of inputs in the current stroke prediction.
final @IntRange(from = 0) int
final boolean

Returns true if finishInput has been called since the last call to start, or if start hasn't been called yet.
final @NonNull StrokeInput
populateInput(@NonNull StrokeInput out, @IntRange(from = 0) int index)

Gets the value of the i-th input and overwrites out.
final @NonNull MutableStrokeInputBatch
populateInputs(
    @NonNull MutableStrokeInputBatch out,
    @IntRange(from = 0) int from,
    @IntRange(from = 0) int to
)

Add the specified range of inputs from this stroke to the output MutableStrokeInputBatch.
final @NonNull BoxAccumulator
populateMeshBounds(
    @IntRange(from = 0) int coatIndex,
    @NonNull BoxAccumulator outBoxAccumulator
)

Writes to outBoxAccumulator the bounding box of the vertex positions of the mesh for brush coat coatIndex.
final void
populateOutlinePosition(
    @IntRange(from = 0) int coatIndex,
    @IntRange(from = 0) int outlineIndex,
    @IntRange(from = 0) int outlineVertexIndex,
    @NonNull MutableVec outPosition
)

Fills outPosition with the x- and y- coordinates of the specified outline vertex.
final @NonNull BoxAccumulator

Returns the bounding rectangle of mesh positions added, modified, or removed by calls to updateShape since the most recent call to start or resetUpdatedRegion.
final void

Call after making use of a value from populateUpdatedRegion to reset the accumulation.
final void

Clears and starts a new stroke with the given brush.
final @NonNull Stroke

Copies the current input, brush, and geometry as of the last call to start or updateShape to a new Stroke.
final @NonNull Result<Unit>
updateShape(long currentElapsedTimeMillis)

Updates the stroke geometry up to the given duration since the start of the stroke.
final void
updateShapeOrThrow(long currentElapsedTimeMillis)

Protected methods
final void

Public constructors

InProgressStroke

Added in 1.0.0-alpha02
public InProgressStroke()

Public methods

enqueueInputs

Added in 1.0.0-alpha02
public final @NonNull Result<Unit> enqueueInputs(
    @NonNull StrokeInputBatch realInputs,
    @NonNull StrokeInputBatch predictedInputs
)

Enqueues the incremental realInputs and sets the prediction to predictedInputs, overwriting any previous prediction. Queued inputs will be processed on the next call to updateShape.

This method requires that:

If the above requirements are not satisfied, the Result will be a failure and this object is left in the state it had prior to the call.

Either one or both of realInputs and predictedInputs may be empty.

enqueueInputsOrThrow

Added in 1.0.0-alpha02
public final void enqueueInputsOrThrow(
    @NonNull StrokeInputBatch realInputs,
    @NonNull StrokeInputBatch predictedInputs
)
See also
enqueueInputs

finishInput

Added in 1.0.0-alpha02
public final void finishInput()

Indicates that the inputs for the current stroke are finished. After calling this, it is an error to call enqueueInputs until start is called again to start a new stroke. This method is idempotent; it has no effect if start was never called, or if this method has already been called since the last call to start.

getBrush

Added in 1.0.0-alpha02
public final Brush getBrush()

The Brush currently being used to generate the stroke content. To set this, call start.

getBrushCoatCount

Added in 1.0.0-alpha02
public final @IntRange(from = 0) int getBrushCoatCount()

Returns the number of BrushCoats for the current brush, or zero if start has not been called.

getInputCount

Added in 1.0.0-alpha02
public final @IntRange(from = 0) int getInputCount()

Returns the number of StrokeInputs in the stroke so far. This counts all of the real inputs and the most-recently-processed sequence of predicted inputs.

getNeedsUpdate

Added in 1.0.0-alpha02
public final boolean getNeedsUpdate()

Returns true if calling updateShape would have any effect on the stroke (and should thus be called before the next render), or false if no calls to updateShape are currently needed. Specifically:

  • If the brush has one or more timed animation behavior that are still active (which can be true even after inputs are finished), returns true.

  • If there are no active animation behaviors, but there are pending inputs from an enqueueInputs call that have not yet been consumed by a call to updateShape, returns true.

  • Otherwise, returns false.

Once isInputFinished returns true and this method returns false, the stroke is considered "dry", and will not change any further until the next call to start.

getOutlineCount

Added in 1.0.0-alpha02
public final @IntRange(from = 0) int getOutlineCount(@IntRange(from = 0) int coatIndex)

Returns the number of outlines for the specified brush coat. Calls to functions that accept an outlineIndex must treat the result of this function as an upper bound.

Parameters
@IntRange(from = 0) int coatIndex

Must be between 0 (inclusive) and the result of getBrushCoatCount (exclusive).

getOutlineVertexCount

Added in 1.0.0-alpha02
public final @IntRange(from = 0) int getOutlineVertexCount(
    @IntRange(from = 0) int coatIndex,
    @IntRange(from = 0) int outlineIndex
)

Returns the number of outline points for the specified outline and brush coat. populateOutlinePosition must treat the result of this as the upper bound of its outlineVertexIndex parameter.

Parameters
@IntRange(from = 0) int coatIndex

Must be between 0 (inclusive) and the result of getBrushCoatCount (exclusive).
@IntRange(from = 0) int outlineIndex

Must be between 0 (inclusive) and the result of getOutlineCount for the same coatIndex (exclusive).

getPredictedInputCount

Added in 1.0.0-alpha02
public final @IntRange(from = 0) int getPredictedInputCount()

Returns the number of inputs in the current stroke prediction.

getRealInputCount

Added in 1.0.0-alpha02
public final @IntRange(from = 0) int getRealInputCount()

isInputFinished

Added in 1.0.0-alpha02
public final boolean isInputFinished()

Returns true if finishInput has been called since the last call to start, or if start hasn't been called yet. If this returns true, it is an error to call enqueueInputs.

populateInput

Added in 1.0.0-alpha02
public final @NonNull StrokeInput populateInput(@NonNull StrokeInput out, @IntRange(from = 0) int index)

Gets the value of the i-th input and overwrites out. Requires that index is positive and less than getInputCount.

Returns
@NonNull StrokeInput

out

populateInputs

Added in 1.0.0-alpha02
public final @NonNull MutableStrokeInputBatch populateInputs(
    @NonNull MutableStrokeInputBatch out,
    @IntRange(from = 0) int from,
    @IntRange(from = 0) int to
)

Add the specified range of inputs from this stroke to the output MutableStrokeInputBatch.

Returns
@NonNull MutableStrokeInputBatch

out

populateMeshBounds

Added in 1.0.0-alpha02
public final @NonNull BoxAccumulator populateMeshBounds(
    @IntRange(from = 0) int coatIndex,
    @NonNull BoxAccumulator outBoxAccumulator
)

Writes to outBoxAccumulator the bounding box of the vertex positions of the mesh for brush coat coatIndex.

Parameters
@IntRange(from = 0) int coatIndex

The index of the coat to obtain the bounding box from.
@NonNull BoxAccumulator outBoxAccumulator

The pre-allocated BoxAccumulator to be filled with the result.
Returns
@NonNull BoxAccumulator

outBoxAccumulator

populateOutlinePosition

Added in 1.0.0-alpha02
public final void populateOutlinePosition(
    @IntRange(from = 0) int coatIndex,
    @IntRange(from = 0) int outlineIndex,
    @IntRange(from = 0) int outlineVertexIndex,
    @NonNull MutableVec outPosition
)

Fills outPosition with the x- and y- coordinates of the specified outline vertex.

Parameters
@IntRange(from = 0) int coatIndex

Must be between 0 (inclusive) and the result of getBrushCoatCount (exclusive).
@IntRange(from = 0) int outlineIndex

Must be between 0 (inclusive) and the result of getOutlineCount (exclusive) for the same coatIndex.
@IntRange(from = 0) int outlineVertexIndex

Must be between 0 (inclusive) and the result of getOutlineVertexCount (exclusive) for the same coatIndex and outlineIndex.
@NonNull MutableVec outPosition

the pre-allocated MutableVec to be filled with the result.

populateUpdatedRegion

Added in 1.0.0-alpha02
public final @NonNull BoxAccumulator populateUpdatedRegion(@NonNull BoxAccumulator outBoxAccumulator)

Returns the bounding rectangle of mesh positions added, modified, or removed by calls to updateShape since the most recent call to start or resetUpdatedRegion.

Parameters
@NonNull BoxAccumulator outBoxAccumulator

The pre-allocated BoxAccumulator to be filled with the result.
Returns
@NonNull BoxAccumulator

outBoxAccumulator

resetUpdatedRegion

Added in 1.0.0-alpha02
public final void resetUpdatedRegion()

Call after making use of a value from populateUpdatedRegion to reset the accumulation.

start

Added in 1.0.0-alpha02
public final void start(@NonNull Brush brush)

Clears and starts a new stroke with the given brush.

This includes clearing or resetting any existing inputs, mesh data, and updated region. This method must be called at least once after construction before starting to call enqueueInputs or updateShape.

toImmutable

Added in 1.0.0-alpha02
public final @NonNull Stroke toImmutable()

Copies the current input, brush, and geometry as of the last call to start or updateShape to a new Stroke.

The resulting Stroke will not be modified if further inputs are added to this InProgressStroke, and a Stroke created by another call to this method will not modify or be connected in any way to the prior Stroke.

updateShape

Added in 1.0.0-alpha02
public final @NonNull Result<Unit> updateShape(long currentElapsedTimeMillis)

Updates the stroke geometry up to the given duration since the start of the stroke. This will will consume any inputs queued up by calls to enqueueInputs, and cause brush animations (if any) to progress up to the specified time. Any stroke geometry resulting from previously-predicted input from before the previous call to this method will be cleared.

This method requires that:

  • start has been previously called to set the current brush.

  • The value of currentElapsedTimeMillis passed into this method over the course of a single stroke must be non-decreasing and non-negative. Its default value causes all ongoing stroke animations to be completed immediately. To have animations progress at their intended rate, pass in values for this field that are in the same time base as the StrokeInput.elapsedTimeMillis values being passed to enqueueInputs, repeatedly until isInputFinished returns true.

If the above requirements are not satisfied, the Result will be a failure and this object is left in the state it had prior to the call.

updateShapeOrThrow

Added in 1.0.0-alpha02
public final void updateShapeOrThrow(long currentElapsedTimeMillis)
See also
updateShape

Protected methods

finalize

Added in 1.0.0-alpha02
protected final void finalize()