Add kTimeSinceInputsFinished brush behavior sources

This allows for one-shot whole-stroke animations that occur after input is finished.

PiperOrigin-RevId: 621598492

Author: Ink Open Source

ink/brush/brush_behavior.cc

@@ -204,6 +204,8 @@ bool IsValidBehaviorSource(BrushBehavior::Source source) {
         kInputAccelerationForwardInCentimetersPerSecondSquared:
     case BrushBehavior::Source::
         kInputAccelerationLateralInCentimetersPerSecondSquared:
+    case BrushBehavior::Source::kTimeSinceInputsFinishedInSeconds:
+    case BrushBehavior::Source::kTimeSinceInputsFinishedInMillis:
       return true;
   }
   return false;
@@ -214,9 +216,11 @@ absl::Status ValidateSourceAndOutOfRangeCombination(
   switch (source) {
     case BrushBehavior::Source::kTimeSinceInputInSeconds:
     case BrushBehavior::Source::kTimeSinceInputInMillis:
+    case BrushBehavior::Source::kTimeSinceInputsFinishedInSeconds:
+    case BrushBehavior::Source::kTimeSinceInputsFinishedInMillis:
       if (out_of_range != BrushBehavior::OutOfRange::kClamp) {
         return absl::InvalidArgumentError(
-            "`Source::kTimeSinceInput*` must only be used with "
+            "`Source::kTimeSince*` must only be used with "
             "`source_out_of_range_behavior` of `kClamp`.");
       }
       break;
@@ -592,6 +596,10 @@ std::string ToFormattedString(BrushBehavior::Source source) {
     case BrushBehavior::Source::
         kInputAccelerationLateralInCentimetersPerSecondSquared:
       return "kInputAccelerationLateralInCentimetersPerSecondSquared";
+    case BrushBehavior::Source::kTimeSinceInputsFinishedInSeconds:
+      return "kTimeSinceInputsFinishedInSeconds";
+    case BrushBehavior::Source::kTimeSinceInputsFinishedInMillis:
+      return "kTimeSinceInputsFinishedInMillis";
   }
   return absl::StrCat("Source(", static_cast<int>(source), ")");
 }

ink/brush/brush_behavior.h

@@ -230,6 +230,13 @@ struct BrushBehavior {
     // Y-axis (and a negative value indicates acceleration along the negative
     // Y-axis).
     kInputAccelerationLateralInCentimetersPerSecondSquared,
+    // The amount of time that has elapsed since all stroke inputs have
+    // finished, or null if the stroke inputs aren't finished yet. This can be
+    // used to drive a final animation on the stroke geometry. These enumerators
+    // are only compatible with a `source_out_of_range_behavior` of `kClamp`, to
+    // ensure that the animation will eventually end.
+    kTimeSinceInputsFinishedInSeconds,
+    kTimeSinceInputsFinishedInMillis,
     // TODO: b/336565152 - Add kInputDistanceRemainingInCentimeters (this will
     // require some refactoring for the code that calculates
     // BrushTipModeler::distance_remaining_behavior_upper_bound_).

ink/brush/brush_behavior_test.cc

@@ -136,6 +136,12 @@ TEST(BrushBehaviorTest, StringifySource) {
       absl::StrCat(BrushBehavior::Source::
                        kInputAccelerationLateralInCentimetersPerSecondSquared),
       "kInputAccelerationLateralInCentimetersPerSecondSquared");
+  EXPECT_EQ(
+      absl::StrCat(BrushBehavior::Source::kTimeSinceInputsFinishedInSeconds),
+      "kTimeSinceInputsFinishedInSeconds");
+  EXPECT_EQ(
+      absl::StrCat(BrushBehavior::Source::kTimeSinceInputsFinishedInMillis),
+      "kTimeSinceInputsFinishedInMillis");
   EXPECT_EQ(absl::StrCat(static_cast<BrushBehavior::Source>(123)),
             "Source(123)");
 }
@@ -562,7 +568,7 @@ TEST(BrushBehaviorTest, ValidateSourceNode) {
   });
   EXPECT_EQ(status.code(), absl::StatusCode::kInvalidArgument);
   EXPECT_THAT(status.message(),
-              HasSubstr("kTimeSinceInput*` must only be used with "
+              HasSubstr("kTimeSince*` must only be used with "
                         "`source_out_of_range_behavior` of `kClamp"));
 
   status = brush_internal::ValidateBrushBehaviorNode(BrushBehavior::SourceNode{

ink/brush/brush_family_test.cc

@@ -568,7 +568,7 @@ TEST(BrushFamilyTest, CreateWithInvalidBehaviorSourceAndOutOfRangeBehavior) {
   absl::Status status = BrushFamily::Create(brush_tip, BrushPaint{}).status();
   EXPECT_EQ(status.code(), kInvalidArgument);
   EXPECT_THAT(status.message(),
-              HasSubstr("kTimeSinceInput*` must only be used with "
+              HasSubstr("kTimeSince*` must only be used with "
                         "`source_out_of_range_behavior` of `kClamp"));
 
   source_node->source = BrushBehavior::Source::kTimeSinceInputInMillis;
@@ -577,7 +577,7 @@ TEST(BrushFamilyTest, CreateWithInvalidBehaviorSourceAndOutOfRangeBehavior) {
   status = BrushFamily::Create(brush_tip, BrushPaint{}).status();
   EXPECT_EQ(status.code(), kInvalidArgument);
   EXPECT_THAT(status.message(),
-              HasSubstr("kTimeSinceInput*` must only be used with "
+              HasSubstr("kTimeSince*` must only be used with "
                         "`source_out_of_range_behavior` of `kClamp"));
 }
 

ink/brush/fuzz_domains.cc

@@ -159,6 +159,8 @@ Domain<BrushBehavior::OutOfRange> ValidBrushBehaviorOutOfRangeForSource(
   switch (source) {
     case BrushBehavior::Source::kTimeSinceInputInSeconds:
     case BrushBehavior::Source::kTimeSinceInputInMillis:
+    case BrushBehavior::Source::kTimeSinceInputsFinishedInSeconds:
+    case BrushBehavior::Source::kTimeSinceInputsFinishedInMillis:
       return Just(BrushBehavior::OutOfRange::kClamp);
     default:
       return ArbitraryBrushBehaviorOutOfRange();
@@ -213,6 +215,8 @@ Domain<BrushBehavior::Source> ArbitraryBrushBehaviorSource() {
           kInputAccelerationForwardInCentimetersPerSecondSquared,
       BrushBehavior::Source::
           kInputAccelerationLateralInCentimetersPerSecondSquared,
+      BrushBehavior::Source::kTimeSinceInputsFinishedInSeconds,
+      BrushBehavior::Source::kTimeSinceInputsFinishedInMillis,
   });
 }
 // LINT.ThenChange(brush_behavior.h:source)

ink/strokes/in_progress_stroke.cc

@@ -129,6 +129,9 @@ absl::Status InProgressStroke::UpdateShape(Duration32 current_elapsed_time) {
   for (uint32_t i = 0; i < num_coats; ++i) {
     StrokeShapeUpdate update = shape_builders_[i].ExtendStroke(
         queued_real_inputs_, queued_predicted_inputs_, current_elapsed_time);
+    if (inputs_are_finished_) {
+      shape_builders_[i].FinishStrokeInputs();
+    }
 
     updated_region_.Add(update.region);
     // TODO: b/286547863 - Pass `update.first_vertex_offset` and

ink/strokes/internal/brush_tip_modeler.cc

@@ -139,6 +139,8 @@ float DistanceRemainingUpperBound(const BrushBehavior::SourceNode& node,
         kInputAccelerationForwardInCentimetersPerSecondSquared:
     case BrushBehavior::Source::
         kInputAccelerationLateralInCentimetersPerSecondSquared:
+    case BrushBehavior::Source::kTimeSinceInputsFinishedInSeconds:
+    case BrushBehavior::Source::kTimeSinceInputsFinishedInMillis:
       return 0;
   }
   ABSL_LOG(FATAL)
@@ -149,8 +151,10 @@ float DistanceRemainingUpperBound(const BrushBehavior::SourceNode& node,
 Duration32 TimeRemainingUpperBound(const BrushBehavior::SourceNode& node) {
   switch (node.source) {
     case BrushBehavior::Source::kTimeSinceInputInSeconds:
+    case BrushBehavior::Source::kTimeSinceInputsFinishedInSeconds:
       return Duration32::Seconds(SourceValueUpperBound(node));
     case BrushBehavior::Source::kTimeSinceInputInMillis:
+    case BrushBehavior::Source::kTimeSinceInputsFinishedInMillis:
       return Duration32::Millis(SourceValueUpperBound(node));
     case BrushBehavior::Source::kNormalizedPressure:
     case BrushBehavior::Source::kTiltInRadians:

ink/strokes/internal/brush_tip_modeler_helpers.cc

@@ -231,6 +231,16 @@ std::optional<float> GetSourceValue(
       return Vec::DotProduct(input.acceleration,
                              input.velocity.AsUnitVec().Orthogonal()) *
              input_modeler_state.stroke_unit_length->ToCentimeters();
+    case BrushBehavior::Source::kTimeSinceInputsFinishedInSeconds:
+      if (!input_modeler_state.inputs_are_finished) break;
+      return (input_modeler_state.complete_elapsed_time -
+              input_modeler_state.total_real_elapsed_time)
+          .ToSeconds();
+    case BrushBehavior::Source::kTimeSinceInputsFinishedInMillis:
+      if (!input_modeler_state.inputs_are_finished) break;
+      return (input_modeler_state.complete_elapsed_time -
+              input_modeler_state.total_real_elapsed_time)
+          .ToMillis();
   }
   return std::nullopt;
 }

ink/strokes/internal/brush_tip_modeler_helpers_test.cc

@@ -782,6 +782,48 @@ TEST_F(ProcessBehaviorNodeTest,
   EXPECT_THAT(stack_, ElementsAre(NullNodeValueMatcher()));
 }
 
+TEST_F(ProcessBehaviorNodeTest, SourceNodeTimeSinceInputsFinishedInSeconds) {
+  BrushBehavior::SourceNode source_node = {
+      .source = BrushBehavior::Source::kTimeSinceInputsFinishedInSeconds,
+      .source_value_range = {0, 10},
+  };
+
+  // If `inputs_are_finished` is still `false`, the source node emits a null
+  // value.
+  input_modeler_state_.total_real_elapsed_time = Duration32::Seconds(3);
+  input_modeler_state_.complete_elapsed_time = Duration32::Seconds(5);
+  input_modeler_state_.inputs_are_finished = false;
+  ProcessBehaviorNode(source_node, context_);
+  EXPECT_THAT(stack_, ElementsAre(NullNodeValueMatcher()));
+
+  // Once `inputs_are_finished` is `true`, the source node emits its value.
+  stack_.clear();
+  input_modeler_state_.inputs_are_finished = true;
+  ProcessBehaviorNode(source_node, context_);
+  EXPECT_THAT(stack_, ElementsAre(0.2f));
+}
+
+TEST_F(ProcessBehaviorNodeTest, SourceNodeTimeSinceInputsFinishedInMillis) {
+  BrushBehavior::SourceNode source_node = {
+      .source = BrushBehavior::Source::kTimeSinceInputsFinishedInMillis,
+      .source_value_range = {0, 10000},
+  };
+
+  // If `inputs_are_finished` is still `false`, the source node emits a null
+  // value.
+  input_modeler_state_.total_real_elapsed_time = Duration32::Seconds(3);
+  input_modeler_state_.complete_elapsed_time = Duration32::Seconds(5);
+  input_modeler_state_.inputs_are_finished = false;
+  ProcessBehaviorNode(source_node, context_);
+  EXPECT_THAT(stack_, ElementsAre(NullNodeValueMatcher()));
+
+  // Once `inputs_are_finished` is `true`, the source node emits its value.
+  stack_.clear();
+  input_modeler_state_.inputs_are_finished = true;
+  ProcessBehaviorNode(source_node, context_);
+  EXPECT_THAT(stack_, ElementsAre(0.2f));
+}
+
 TEST_F(ProcessBehaviorNodeTest, SourceNodeOutOfRangeClamp) {
   BrushBehavior::SourceNode source_node = {
       .source = BrushBehavior::Source::kNormalizedPressure,

ink/strokes/internal/stroke_input_modeler.cc

@@ -134,6 +134,9 @@ void StrokeInputModeler::ExtendStroke(const StrokeInputBatch& real_inputs,
                                       const StrokeInputBatch& predicted_inputs,
                                       Duration32 current_elapsed_time) {
   ABSL_CHECK_GT(brush_epsilon_, 0) << "`StartStroke()` has not been called.";
+  ABSL_CHECK(!state_.inputs_are_finished ||
+             (real_inputs.IsEmpty() && predicted_inputs.IsEmpty()))
+      << "Can't add more inputs after calling `FinishStrokeInputs()`.";
 
   absl::Cleanup update_time_and_distance = [&]() {
     UpdateStateTimeAndDistance(current_elapsed_time);

ink/strokes/internal/stroke_input_modeler.h

@@ -122,6 +122,9 @@ class StrokeInputModeler {
     // of this member variable will be non-decreasing over the course of a
     // single stroke.
     size_t real_input_count = 0;
+    // True if inputs are finished for this stroke (in which case, no more real
+    // or predicted inputs will be added).
+    bool inputs_are_finished = false;
   };
 
   StrokeInputModeler() = default;
@@ -148,11 +151,17 @@ class StrokeInputModeler {
   //
   // This always clears any previously generated unstable modeled inputs. Either
   // or both of `real_inputs` and `predicted_inputs` may be empty. CHECK-fails
-  // if `StartStroke()` has not been called at least once.
+  // if `StartStroke()` has not been called at least once, or if
+  // `FinishStrokeInputs()` has been called for this stroke and `real_inputs`
+  // and `predicted_inputs` aren't both empty.
   void ExtendStroke(const StrokeInputBatch& real_inputs,
                     const StrokeInputBatch& predicted_inputs,
                     Duration32 current_elapsed_time);
 
+  // Indicates that the inputs for the current stroke are finished. This method
+  // is idempotent.
+  void FinishStrokeInputs();
+
   const State& GetState() const { return state_; }
   absl::Span<const ModeledStrokeInput> GetModeledInputs() const {
     return modeled_inputs_;
@@ -184,6 +193,10 @@ class StrokeInputModeler {
   State state_;
 };
 
+inline void StrokeInputModeler::FinishStrokeInputs() {
+  state_.inputs_are_finished = true;
+}
+
 }  // namespace ink::strokes_internal
 
 #endif  // INK_STROKES_INTERNAL_STROKE_INPUT_MODELER_H_

ink/strokes/internal/stroke_shape_builder.h

@@ -80,6 +80,9 @@ class StrokeShapeBuilder {
   // The `current_elapsed_time` should be the duration from the start of the
   // stroke until "now". The `elapsed_time` of inputs may be "in the future"
   // relative to this duration.
+  //
+  // CHECK-fails if `FinishStrokeInputs()` has been called for this stroke and
+  // either `real_inputs` or `predicted_inputs` is non-empty.
   StrokeShapeUpdate ExtendStroke(const StrokeInputBatch& real_inputs,
                                  const StrokeInputBatch& predicted_inputs,
                                  Duration32 current_elapsed_time);
@@ -89,6 +92,10 @@ class StrokeShapeBuilder {
   // time (even in the absence of any new inputs).
   bool HasUnfinishedTimeBehaviors() const;
 
+  // Indicates that the inputs for the current stroke are finished. This method
+  // is idempotent.
+  void FinishStrokeInputs();
+
   const MutableMesh& GetMesh() const;
 
   const Envelope& GetMeshBounds() const;
@@ -128,6 +135,10 @@ class StrokeShapeBuilder {
 inline StrokeShapeBuilder::StrokeShapeBuilder()
     : mesh_(StrokeVertex::FullMeshFormat()) {}
 
+inline void StrokeShapeBuilder::FinishStrokeInputs() {
+  input_modeler_.FinishStrokeInputs();
+}
+
 inline const MutableMesh& StrokeShapeBuilder::GetMesh() const { return mesh_; }
 
 inline const Envelope& StrokeShapeBuilder::GetMeshBounds() const {

ink/strokes/internal/stroke_shape_builder_test.cc

@@ -191,5 +191,22 @@ TEST(StrokeShapeBuilderDeathTest, ExtendWithoutStart) {
                             "");
 }
 
+TEST(StrokeShapeBuilderDeathTest, ExtendInputsAfterInputsFinished) {
+  absl::StatusOr<StrokeInputBatch> inputs = StrokeInputBatch::Create({
+      {.position = {5, 7}, .elapsed_time = Duration32::Zero()},
+  });
+  ASSERT_EQ(inputs.status(), absl::OkStatus());
+
+  StrokeShapeBuilder builder;
+  std::vector<BrushTip> brush_tips = {BrushTip()};
+  builder.StartStroke(BrushFamily::DefaultInputModel(), brush_tips, 1, 0.1);
+  builder.ExtendStroke(*inputs, {}, Duration32::Zero());
+  builder.FinishStrokeInputs();
+
+  EXPECT_DEATH_IF_SUPPORTED(
+      builder.ExtendStroke(*inputs, {}, Duration32::Zero()),
+      "Can't add more inputs");
+}
+
 }  // namespace
 }  // namespace ink::strokes_internal