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::kAnimationFrameOffset:
     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::kAnimationFrameOffset:
+      return "kAnimationFrameOffset";
     case BrushBehavior::Target::kHueOffsetInRadians:
       return "kHueOffsetInRadians";
     case BrushBehavior::Target::kSaturationMultiplier:

ink/brush/brush_behavior.h

@@ -286,6 +286,11 @@ 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 animation frame number of the
+    // current particle (which is relevant only for strokes with an animated
+    // texture). The final frame number offset will be rounded to the nearest
+    // integer after all behaviors have been applied.
+    kAnimationFrameOffset,
 
     // 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,22 @@ 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::kAnimationFrameOffset),
+            "kAnimationFrameOffset");
   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::kAnimationFrameOffset,
       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::kAnimationFrameOffset:
+      return proto::BrushBehavior::TARGET_ANIMATION_FRAME_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_ANIMATION_FRAME_OFFSET:
+      return BrushBehavior::Target::kAnimationFrameOffset;
     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_ANIMATION_FRAME_OFFSET = 17;
   }
   // LINT.ThenChange(../../brush/brush_behavior.h:target)
 

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.animation_frame_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::kAnimationFrameOffset:
     case BrushBehavior::Target::kHueOffsetInRadians:
     case BrushBehavior::Target::kLuminosity:
       return 0.f;

ink/strokes/internal/brush_tip_modeler_helpers.cc

@@ -539,6 +539,7 @@ struct BrushTipStateModifiers {
   float corner_rounding_offset = 0;
   Angle rotation_offset;
   float pinch_offset = 0;
+  int animation_frame_offset = 0;
   Angle hue_offset;
   float saturation_multiplier = 1;
   float luminosity = 0;
@@ -597,6 +598,9 @@ void ApplyModifierToTarget(float modifier, BrushBehavior::Target target,
                                            modifier * brush_size);
       }
       break;
+    case BrushBehavior::Target::kAnimationFrameOffset:
+      tip_state_modifiers.animation_frame_offset += modifier;
+      break;
     case BrushBehavior::Target::kHueOffsetInRadians:
       tip_state_modifiers.hue_offset += Angle::Radians(modifier);
       break;
@@ -637,6 +641,7 @@ void ApplyModifiersToTipState(const BrushTipStateModifiers& modifiers,
     tip_state.percent_radius = std::clamp(
         tip_state.percent_radius + modifiers.corner_rounding_offset, 0.f, 1.f);
   }
+  tip_state.animation_frame_offset += modifiers.animation_frame_offset;
   if (modifiers.hue_offset != Angle()) {
     tip_state.hue_offset_in_full_turns =
         modifiers.hue_offset.Normalized() / kFullTurn;

ink/strokes/internal/brush_tip_modeler_helpers_test.cc

@@ -1535,6 +1535,17 @@ TEST(CreateTipStateTest, WithBehaviorTargetingCornerRounding) {
                          {clamp_offset});
   EXPECT_FLOAT_EQ(state.percent_radius, /**clamped to 0*/ 0);
 }
+
+TEST(CreateTipStateTest, WithBehaviorTargetingAnimationFrame) {
+  BrushTip brush_tip = MakeBaseBrushTip();
+  float brush_size = 2.5f;
+  float animation_frame_offset = 3;
+  BrushTipState state = CreateTipState(
+      {0, 0}, Angle(), brush_tip, brush_size,
+      {BrushBehavior::Target::kAnimationFrameOffset}, {animation_frame_offset});
+  EXPECT_FLOAT_EQ(state.animation_frame_offset, animation_frame_offset);
+}
+
 TEST(CreateTipStateTest, WithBehaviorTargetingHue) {
   BrushTip brush_tip = MakeBaseBrushTip();
   float brush_size = 2.5f;