InProgressShape

abstract void cancel()

Indicates that this shape should will longer be drawn. It will not receive any further calls to enqueueInputs or update, and it will never receive a call to finishInput. A call to this function should be reflected in the next call to getUpdatedRegion - the updated region of a canceled shape must include the entire shape's bounding box, along with the locations of any other content that had been removed before cancellation but after the last call to resetUpdatedRegion. After resetUpdatedRegion has been called following cancel, then further calls to getUpdatedRegion must return null.

abstract boolean changesWithTime()

Whether calls to update with new timestamp values may cause changes to getUpdatedRegion, even when there haven't been calls to enqueueInputs.

abstract void enqueueInputs(
    @NonNull StrokeInputBatch realInputs,
    @NonNull StrokeInputBatch predictedInputs
)

Append the incremental realInputs and set the prediction to predictedInputs, replacing any previous prediction. Queued inputs must not be processed right away - they can only be processed on the next call to update.

Implementations of this function can assume that:

• start has been called to set the current ShapeSpecT on this instance.

• finishInput has not been called since then, and neither has prepareToRecycle.

• realInputs and predictedInputs form a valid stroke input sequence together with previously added real input. In particular, this means that the first input in realInputs must be valid following the last input in previously added real inputs, and the first input in predictedInputs must be valid following the last input in realInputs: They have the same androidx.ink.brush.InputToolType, their androidx.ink.strokes.StrokeInput.elapsedTimeMillis values are monotonically non-decreasing, and they do not duplicate the previous input.

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

The realInputs and predictedInputs instances will be recycled and cannot be retained - implementations must copy the necessary data from them before this function returns.

abstract void finishInput()

Indicate that no new calls to enqueueInputs will be made.

This occurs after the final call to enqueueInputs and before any corresponding call to update.

abstract void forceCompletion()

If this is called, a subsequent call to getCompletedShape must return a non-null CompletedShape. This can only ever be called after finishInput and update.

abstract CompletedShapeT getCompletedShape()

Get the CompletedShapeT if this shape has been completed, or null otherwise. This can only be called after:

1. The final call to enqueueInputs.

2. The call to finishInput to indicate that the previous call to enqueueInputs was the final one.

3. A call to update.

In most circumstances, this will return a non-null value the first time it is called. But some shapes involve time-based effects after all inputs have been received, which may cause this to return null for a little while longer, in which time more calls to update will occur.

If those effects are finite and prevent the shape from being considered completed, then this function may return null until the time passed to update progresses enough. Some examples of this include a shape "settling", e.g. to simulate motion coming to rest or the physical process of ink absorbing or "bleeding" into paper.

This must not return a non-null value until the CompletedShapeT instance returned by this function will no longer change. Once it returns a non-null value, InProgressShapesView will not call this function again until this instance is reused for a new shape. Note that may still be before all calls to update are completed. For example, if changesWithTime returns true, there may be more calls to update to increment an animation progress value which is expected to be continued after the shape has been handed off via InProgressShapesCompletedListener.

This function should not modify, reset, or clear any internal state, even once it begins returning a non-null value, as the InProgressShape is still used for rendering until prepareToRecycle is called.

abstract Box getUpdatedRegion()

Returns an axis-aligned bounding rectangle of parts of the shape added, removed, or changed since the last call to resetUpdatedRegion. The primary way that these changes would occur is through calls to update, but calls to cancel should also be reflected here by including the most recent bounding box of the entire shape. The resulting Box should be in the same coordinate system as the inputs supplied to enqueueInputs. If no changes have occurred since the last call to resetUpdatedRegion, then this must return null.

default void prepareToRecycle()

The optional inverse of start, where some state can be cleaned up when this instance is not currently needed but may be used again in the future. Do not actually release underlying resources that would have to be reallocated on another future call to start, as performing that allocation each time can hurt performance.

abstract void resetUpdatedRegion()

Reset the calculation of getUpdatedRegion so that if it is called again after this without calling update or cancel first, then the result will be null to represent no changes.

abstract void start(@NonNull ShapeSpecT shapeSpec, long systemElapsedTimeMillis)

Prepare for this instance to be used for shape creation, by receiving inputs through enqueueInputs, applying those inputs during update, and being rendered according to ShapeWorkflow.inProgressShapeRenderer. The shape specified by these parameters will be valid until prepareToReycle is called.

abstract void update(long shapeDurationMillis)

Update internal state of this shape based on the provided timestamps as well as any inputs passed to enqueueInputs since the last call to update.