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/geometry/BUILD.bazel

@@ -58,6 +58,7 @@ cc_library(
     hdrs = ["angle.h"],
     visibility = ["//visibility:public"],
     deps = [
+        "//ink/geometry/internal:modulo",
         "//ink/types:numbers",
         "@com_google_absl//absl/strings:str_format",
     ],

ink/geometry/angle.cc

@@ -22,25 +22,6 @@
 
 namespace ink {
 
-Angle Angle::Normalized() const {
-  float radians =
-      std::fmod(ValueInRadians(), static_cast<float>(2.0 * numbers::kPi));
-  // fmod always matches the sign of the first argument, so fmod(angle, 2π)
-  // returns a value in the range (-2π, 2π).  We want [0, 2π), so wrap negative
-  // values back to positive.
-  if (radians < 0.f) {
-    radians += static_cast<float>(2.0 * numbers::kPi);
-    // If fmod returned a sufficiently small negative number, then adding 2π
-    // will give us a result exactly equal to 2π, due to float rounding.
-    // However, Angle::Normalized() promises to return a value strictly less
-    // than 2π, so we should normalize to zero in this case.
-    if (radians == static_cast<float>(2.0 * numbers::kPi)) {
-      radians = 0.f;
-    }
-  }
-  return Angle::Radians(radians);
-}
-
 Angle Angle::NormalizedAboutZero() const {
   float radians =
       std::fmod(ValueInRadians(), static_cast<float>(2.0 * numbers::kPi));

ink/geometry/angle.h

@@ -19,6 +19,7 @@
 #include <cstdlib>
 #include <string>
 
+#include "ink/geometry/internal/modulo.h"
 #include "ink/types/numbers.h"
 
 namespace ink {
@@ -197,6 +198,11 @@ inline Angle& operator/=(Angle& lhs, float rhs) {
   return lhs;
 }
 
+inline Angle Angle::Normalized() const {
+  return Angle::Radians(geometry_internal::FloatModulo(
+      ValueInRadians(), static_cast<float>(2.0 * numbers::kPi)));
+}
+
 }  // namespace ink
 
 #endif  // INK_GEOMETRY_ANGLE_H_

ink/geometry/internal/BUILD.bazel

@@ -133,6 +133,25 @@ cc_test(
     ],
 )
 
+cc_library(
+    name = "modulo",
+    srcs = ["modulo.cc"],
+    hdrs = ["modulo.h"],
+    deps = [
+        "@com_google_absl//absl/log:absl_check",
+    ],
+)
+
+cc_test(
+    name = "modulo_test",
+    srcs = ["modulo_test.cc"],
+    deps = [
+        ":modulo",
+        "@com_google_fuzztest//fuzztest",
+        "@com_google_fuzztest//fuzztest:fuzztest_gtest_main",
+    ],
+)
+
 cc_library(
     name = "circle",
     srcs = ["circle.cc"],

ink/geometry/internal/modulo.cc

@@ -0,0 +1,42 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "ink/geometry/internal/modulo.h"
+
+#include <cmath>
+
+#include "absl/log/absl_check.h"
+
+namespace ink::geometry_internal {
+
+float FloatModulo(float a, float b) {
+  ABSL_DCHECK(std::isfinite(b) && b > 0.f);
+  float result = std::fmodf(a, b);
+  // `fmodf` always matches the sign of the first argument, so `fmodf(a, b)`
+  // returns a value in the range (-b, b).  We want [0, b), so wrap negative
+  // values back to positive.
+  if (result < 0.f) {
+    result += b;
+    // If `fmodf` returned a sufficiently small negative number, then adding `b`
+    // will give us a result exactly equal to `b`, due to float rounding.
+    // However, `FloatModulo` promises to return a value strictly less than `b`,
+    // so we should return zero in this case.
+    if (result == b) {
+      result = 0.f;
+    }
+  }
+  return result;
+}
+
+}  // namespace ink::geometry_internal

ink/geometry/internal/modulo.h

@@ -0,0 +1,28 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef INK_GEOMETRY_INTERNAL_MODULO_H_
+#define INK_GEOMETRY_INTERNAL_MODULO_H_
+
+namespace ink::geometry_internal {
+
+// Returns `a` mod `b`, with the result being in the range [0, `b`). This is
+// different from `std::fmodf`, which returns a negative result if `a` is
+// negative. `b` must be finite and strictly greater than zero. Returns NaN if
+// `a` is infinite or NaN.
+float FloatModulo(float a, float b);
+
+}  // namespace ink::geometry_internal
+
+#endif  // INK_GEOMETRY_INTERNAL_MODULO_H_