Add BrushBehavior::Target::kAnimationFrameOffset

This CL adds the necessary boilerplate and plumbing for a new brush behavior target for controlling the starting animation frame of animated particles.  Such a target can be wired up to e.g. a noise node to make particles start on a random frame, or a distance-traveled source to make a series of particles that cycle through starting frames in order, or whatever else is desired.

The actual extruder change to use the new field in the `BrushTipState` to alter the particle's texture UV coordinates is left as a TODO for the next CL.

PiperOrigin-RevId: 720180903

Author: Ink Open Source

ink/brush/brush_behavior.cc

@@ -296,6 +296,7 @@ bool IsValidBehaviorTarget(BrushBehavior::Target target) {
     case BrushBehavior::Target::kPositionOffsetYInMultiplesOfBrushSize:
     case BrushBehavior::Target::kPositionOffsetForwardInMultiplesOfBrushSize:
     case BrushBehavior::Target::kPositionOffsetLateralInMultiplesOfBrushSize:
+    case BrushBehavior::Target::kTextureAnimationProgressOffset:
     case BrushBehavior::Target::kHueOffsetInRadians:
     case BrushBehavior::Target::kSaturationMultiplier:
     case BrushBehavior::Target::kLuminosity:
@@ -650,6 +651,8 @@ std::string ToFormattedString(BrushBehavior::Target target) {
       return "kPositionOffsetForwardInMultiplesOfBrushSize";
     case BrushBehavior::Target::kPositionOffsetLateralInMultiplesOfBrushSize:
       return "kPositionOffsetLateralInMultiplesOfBrushSize";
+    case BrushBehavior::Target::kTextureAnimationProgressOffset:
+      return "kTextureAnimationProgressOffset";
     case BrushBehavior::Target::kHueOffsetInRadians:
       return "kHueOffsetInRadians";
     case BrushBehavior::Target::kSaturationMultiplier:

ink/brush/brush_behavior.h

@@ -286,6 +286,12 @@ struct BrushBehavior {
     // Y-axis (and a negative value moves the brush tip center towards the
     // negative Y-axis).
     kPositionOffsetLateralInMultiplesOfBrushSize,
+    // Adds the target modifier to the initial texture animation progress value
+    // of the current particle (which is relevant only for strokes with an
+    // animated texture). The final progress offset is not clamped, but is
+    // effectively normalized (mod 1). If multiple behaviors have this target,
+    // they stack additively.
+    kTextureAnimationProgressOffset,
 
     // The following are targets for tip color adjustments, including opacity.
     // Renderers can apply them to the brush color when a stroke is drawn to

ink/brush/brush_behavior_test.cc

@@ -161,6 +161,23 @@ TEST(BrushBehaviorTest, StringifyTarget) {
             "kRotationOffsetInRadians");
   EXPECT_EQ(absl::StrCat(BrushBehavior::Target::kCornerRoundingOffset),
             "kCornerRoundingOffset");
+  EXPECT_EQ(absl::StrCat(
+                BrushBehavior::Target::kPositionOffsetXInMultiplesOfBrushSize),
+            "kPositionOffsetXInMultiplesOfBrushSize");
+  EXPECT_EQ(absl::StrCat(
+                BrushBehavior::Target::kPositionOffsetYInMultiplesOfBrushSize),
+            "kPositionOffsetYInMultiplesOfBrushSize");
+  EXPECT_EQ(
+      absl::StrCat(
+          BrushBehavior::Target::kPositionOffsetForwardInMultiplesOfBrushSize),
+      "kPositionOffsetForwardInMultiplesOfBrushSize");
+  EXPECT_EQ(
+      absl::StrCat(
+          BrushBehavior::Target::kPositionOffsetLateralInMultiplesOfBrushSize),
+      "kPositionOffsetLateralInMultiplesOfBrushSize");
+  EXPECT_EQ(
+      absl::StrCat(BrushBehavior::Target::kTextureAnimationProgressOffset),
+      "kTextureAnimationProgressOffset");
   EXPECT_EQ(absl::StrCat(BrushBehavior::Target::kHueOffsetInRadians),
             "kHueOffsetInRadians");
   EXPECT_EQ(absl::StrCat(BrushBehavior::Target::kSaturationMultiplier),

ink/brush/fuzz_domains.cc

@@ -232,6 +232,7 @@ Domain<BrushBehavior::Target> ArbitraryBrushBehaviorTarget() {
       BrushBehavior::Target::kPositionOffsetYInMultiplesOfBrushSize,
       BrushBehavior::Target::kPositionOffsetForwardInMultiplesOfBrushSize,
       BrushBehavior::Target::kPositionOffsetLateralInMultiplesOfBrushSize,
+      BrushBehavior::Target::kTextureAnimationProgressOffset,
       BrushBehavior::Target::kHueOffsetInRadians,
       BrushBehavior::Target::kSaturationMultiplier,
       BrushBehavior::Target::kLuminosity,

ink/storage/brush.cc

@@ -389,6 +389,8 @@ proto::BrushBehavior::Target EncodeBrushBehaviorTarget(
     case BrushBehavior::Target::kPositionOffsetLateralInMultiplesOfBrushSize:
       return proto::BrushBehavior::
           TARGET_POSITION_OFFSET_LATERAL_IN_MULTIPLES_OF_BRUSH_SIZE;
+    case BrushBehavior::Target::kTextureAnimationProgressOffset:
+      return proto::BrushBehavior::TARGET_TEXTURE_ANIMATION_PROGRESS_OFFSET;
     case BrushBehavior::Target::kHueOffsetInRadians:
       return proto::BrushBehavior::TARGET_HUE_OFFSET_IN_RADIANS;
     case BrushBehavior::Target::kSaturationMultiplier:
@@ -440,6 +442,8 @@ absl::StatusOr<BrushBehavior::Target> DecodeBrushBehaviorTarget(
         TARGET_POSITION_OFFSET_LATERAL_IN_MULTIPLES_OF_BRUSH_SIZE:
       return BrushBehavior::Target::
           kPositionOffsetLateralInMultiplesOfBrushSize;
+    case proto::BrushBehavior::TARGET_TEXTURE_ANIMATION_PROGRESS_OFFSET:
+      return BrushBehavior::Target::kTextureAnimationProgressOffset;
     default:
       return absl::InvalidArgumentError(absl::StrCat(
           "invalid ink.proto.BrushBehavior.Target value: ", target_proto));

ink/storage/proto/brush.proto

@@ -293,6 +293,7 @@ message BrushBehavior {
     TARGET_POSITION_OFFSET_FORWARD_IN_MULTIPLES_OF_BRUSH_SIZE = 14;
     TARGET_POSITION_OFFSET_LATERAL_IN_MULTIPLES_OF_BRUSH_SIZE = 15;
     reserved 16;
+    TARGET_TEXTURE_ANIMATION_PROGRESS_OFFSET = 17;
   }
   // LINT.ThenChange(../../brush/brush_behavior.h:target)
 

ink/strokes/internal/BUILD.bazel

@@ -117,6 +117,7 @@ cc_library(
         "//ink/geometry:point",
         "//ink/geometry:vec",
         "//ink/geometry/internal:algorithms",
+        "//ink/geometry/internal:modulo",
         "//ink/strokes/input:stroke_input",
         "//ink/types:duration",
         "//ink/types:physical_distance",

ink/strokes/internal/brush_tip_extruder.cc

@@ -388,6 +388,7 @@ AffineTransform ComputeParticleSurfaceUvTransform(
     const BrushTipState& tip_state) {
   // This transform takes tip size, position, and rotation into account, but
   // deliberately ignores tip slant, pinch, and corner rounding.
+  // TODO: b/373651450 - Use `tip_state.texture_animation_progress_offset` here.
   return AffineTransform::Translate({0.5, 0.5}) *
          AffineTransform::Scale(1.0f / tip_state.width,
                                 1.0f / tip_state.height) *

ink/strokes/internal/brush_tip_modeler.cc

@@ -55,6 +55,7 @@ float InitialTargetModifierValue(BrushBehavior::Target target) {
     case BrushBehavior::Target::kPositionOffsetYInMultiplesOfBrushSize:
     case BrushBehavior::Target::kPositionOffsetForwardInMultiplesOfBrushSize:
     case BrushBehavior::Target::kPositionOffsetLateralInMultiplesOfBrushSize:
+    case BrushBehavior::Target::kTextureAnimationProgressOffset:
     case BrushBehavior::Target::kHueOffsetInRadians:
     case BrushBehavior::Target::kLuminosity:
       return 0.f;

ink/strokes/internal/brush_tip_modeler_helpers.cc

@@ -28,6 +28,7 @@
 #include "ink/brush/brush_tip.h"
 #include "ink/geometry/angle.h"
 #include "ink/geometry/internal/algorithms.h"
+#include "ink/geometry/internal/modulo.h"
 #include "ink/geometry/point.h"
 #include "ink/geometry/vec.h"
 #include "ink/strokes/input/stroke_input.h"
@@ -539,6 +540,7 @@ struct BrushTipStateModifiers {
   float corner_rounding_offset = 0;
   Angle rotation_offset;
   float pinch_offset = 0;
+  float texture_animation_progress_offset = 0;
   Angle hue_offset;
   float saturation_multiplier = 1;
   float luminosity = 0;
@@ -597,6 +599,9 @@ void ApplyModifierToTarget(float modifier, BrushBehavior::Target target,
                                            modifier * brush_size);
       }
       break;
+    case BrushBehavior::Target::kTextureAnimationProgressOffset:
+      tip_state_modifiers.texture_animation_progress_offset += modifier;
+      break;
     case BrushBehavior::Target::kHueOffsetInRadians:
       tip_state_modifiers.hue_offset += Angle::Radians(modifier);
       break;
@@ -637,6 +642,13 @@ void ApplyModifiersToTipState(const BrushTipStateModifiers& modifiers,
     tip_state.percent_radius = std::clamp(
         tip_state.percent_radius + modifiers.corner_rounding_offset, 0.f, 1.f);
   }
+  if (modifiers.texture_animation_progress_offset != 0) {
+    tip_state.texture_animation_progress_offset =
+        geometry_internal::FloatModulo(
+            tip_state.texture_animation_progress_offset +
+                modifiers.texture_animation_progress_offset,
+            1);
+  }
   if (modifiers.hue_offset != Angle()) {
     tip_state.hue_offset_in_full_turns =
         modifiers.hue_offset.Normalized() / kFullTurn;