Populate min_version BrushFamily proto field.

Introduces code to calculate the minimum required version of Ink for a BrushFamily (and each part of a BrushFamily). The code is used during serialization to compute the value to store in the `min_version` field. During deserialization, the `min_version` field is used to determine if a BrushFamily is compatible with the current version of Ink (<= max supported version); if it isn't, decoding it is aborted.

All future features added to custom brushes must be associated with a version number in the proto, and that same number must associated with that feature in the appropriate part of `CalculateMinimumRequiredVersion`. There are two options when selecting a version for a new feature:
* `Version::kMaxSupported() + 1`. This will create a new version level and cement the new feature as part of the custom brush API that the Ink team will support. If this option is chosen, `kMaxSupported` itself must be incremented, and a new version accessor static method should be added to `Version`.
* `Version::kDevelopment()`. This value is a sentinel (represented under the hood with `int32 max()`) to hold features which aren't ready to be released yet. Brushes containing features associated with `kDevelopment` will fail to be deserialized under normal circumstances (an optional argument to `DecodeBrush/BrushFamily()` controls this). This is WAI, since `kDevelopment > kMaxSupported`. Features associated with `kDevelopment` are unstable, so Ink makes no guarantees they will be supported by future versions. Serializing them is risky, and deserializing them is especially risky. Brushes with the version `kDevelopment` may contain features no longer supported, or whose interfaces have changed. These features are available for the purposes of prototyping and research, and deserializing them is only provided as an option for the purpose of convenience. Deserializing a brush with a `min_version` of `kDevelopment` may lead to unexpected behavior.

To ensure the code in the web of `CalculateMinimumRequiredVersion` functions lines up with expectations, protobuf options are used to build consistency check tests. `CalculateMinimumRequiredVersion` serves as the enforcement of the expectations set in the protobuf itself. These tests are designed to automagically ensure new features are thoughtfully assigned a version. It does so by verifying that new fields/messages/enum values in proto have a version assigned, and that the version descriptor for each field/message/enum value in the proto for a brush family is consistent with whatever `CalculateMinimumRequiredVersion` spits out for the same brush family. IOW, a CL which adds a new serializable feature will not be able to pass TAP until that feature is assigned a version. The tests are:
* A fuzz test to generate valid brush families and serialize them. Then, it checks the value in `min_version` against all the options set for the fields, messages, and enum values, to ensure it is equal to the highest value set for the relevant options. This ensures `CalculateMinimumRequiredVersion` is consistent with the protobuf options.
* A test to iterate over all the messages, fields, and enum values in `brush_family.proto`, starting at the top-level `BrushFamily` message, and verify that they all have a relevant `field_min_version`, `message_min_version`, or `enum_value_min_version` set, and that this value set is less than or equal to the maximum compatible version (`kMaxSupported`) or is equal to `kDevelopment`.
* A test to verify that decoding a `min_version` out of the acceptable range (higher than `kMaxSupported`) will fail.
* A test to verify that decoding a `proto::BrushFamily` with no value set for its `min_version` field will ***not*** fail, to ensure older brushes are still able to be loaded.
* Tests to verify that `DecodeBrush()` and `DecodeBrushFamily()` will accept brushes with the version `kDevelopment` if passed the appropriate argument.

A more direct implementation, using reflection to examine the descriptors of the protobuf directly during serialization, was considered, but ultimately rejected. It would have required both static and runtime reflection, and increased `libink.so` size by ~2%.

PiperOrigin-RevId: 886568015

Author: maxmmitchell

MODULE.bazel

@@ -64,7 +64,7 @@ git_repository(
 bazel_dep(name = "protobuf", version = "31.1")
 bazel_dep(name = "rules_android", version = "0.6.0")
 bazel_dep(name = "rules_jni", version = "0.11.1")
-bazel_dep(name = "rules_proto", version = "7.1.0")
+bazel_dep(name = "rules_proto", version = "6.0.2")
 
 git_repository(
     name = "skia",

ink/brush/BUILD.bazel

@@ -82,9 +82,9 @@ cc_library(
     srcs = ["brush_coat.cc"],
     hdrs = ["brush_coat.h"],
     deps = [
-        ":brush_behavior",
         ":brush_paint",
         ":brush_tip",
+        ":version",
         "//ink/geometry:mesh_format",
         "@com_google_absl//absl/container:flat_hash_set",
         "@com_google_absl//absl/container:inlined_vector",
@@ -120,6 +120,7 @@ cc_library(
         ":brush_coat",
         ":brush_paint",
         ":brush_tip",
+        ":version",
         "//ink/types:duration",
         "@com_google_absl//absl/status",
         "@com_google_absl//absl/status:statusor",
@@ -160,11 +161,11 @@ cc_library(
     hdrs = ["brush_tip.h"],
     deps = [
         ":brush_behavior",
+        ":version",
         "//ink/geometry:angle",
         "//ink/geometry:mesh_format",
         "//ink/geometry:vec",
         "//ink/types:duration",
-        "@com_google_absl//absl/base:core_headers",
         "@com_google_absl//absl/container:flat_hash_set",
         "@com_google_absl//absl/status",
         "@com_google_absl//absl/strings",
@@ -190,6 +191,7 @@ cc_library(
     srcs = ["color_function.cc"],
     hdrs = ["color_function.h"],
     deps = [
+        ":version",
         "//ink/color",
         "@com_google_absl//absl/status",
         "@com_google_absl//absl/strings",
@@ -219,6 +221,7 @@ cc_library(
     srcs = ["easing_function.cc"],
     hdrs = ["easing_function.h"],
     deps = [
+        ":version",
         "//ink/geometry:point",
         "@com_google_absl//absl/status",
         "@com_google_absl//absl/strings",
@@ -245,6 +248,7 @@ cc_library(
     hdrs = ["brush_behavior.h"],
     deps = [
         ":easing_function",
+        ":version",
         "@com_google_absl//absl/status",
         "@com_google_absl//absl/strings",
         "@com_google_absl//absl/strings:str_format",
@@ -273,6 +277,7 @@ cc_library(
     hdrs = ["brush_paint.h"],
     deps = [
         ":color_function",
+        ":version",
         "//ink/geometry:angle",
         "//ink/geometry:mesh_format",
         "//ink/geometry:vec",
@@ -365,6 +370,15 @@ cc_library(
     ],
 )
 
+cc_library(
+    name = "version",
+    hdrs = ["version.h"],
+    deps = [
+        "@com_google_absl//absl/log:absl_check",
+        "@com_google_absl//absl/strings",
+    ],
+)
+
 cc_test(
     name = "stock_brushes_test",
     srcs = ["stock_brushes_test.cc"],

ink/brush/brush_behavior.cc

@@ -14,6 +14,7 @@
 
 #include "ink/brush/brush_behavior.h"
 
+#include <algorithm>
 #include <array>
 #include <cmath>
 #include <cstddef>
@@ -25,6 +26,7 @@
 #include "absl/strings/str_format.h"
 #include "absl/strings/str_join.h"
 #include "ink/brush/easing_function.h"
+#include "ink/brush/version.h"
 
 namespace ink {
 
@@ -454,6 +456,207 @@ absl::Status ValidateBrushBehavior(const BrushBehavior& behavior) {
   return absl::OkStatus();
 }
 
+namespace {
+
+Version CalculateMinimumRequiredVersion(BrushBehavior::Source source) {
+  switch (source) {
+    case BrushBehavior::Source::kNormalizedPressure:
+    case BrushBehavior::Source::kTiltInRadians:
+    case BrushBehavior::Source::kTiltXInRadians:
+    case BrushBehavior::Source::kTiltYInRadians:
+    case BrushBehavior::Source::kOrientationInRadians:
+    case BrushBehavior::Source::kOrientationAboutZeroInRadians:
+    case BrushBehavior::Source::kSpeedInMultiplesOfBrushSizePerSecond:
+    case BrushBehavior::Source::kVelocityXInMultiplesOfBrushSizePerSecond:
+    case BrushBehavior::Source::kVelocityYInMultiplesOfBrushSizePerSecond:
+    case BrushBehavior::Source::kDirectionInRadians:
+    case BrushBehavior::Source::kDirectionAboutZeroInRadians:
+    case BrushBehavior::Source::kNormalizedDirectionX:
+    case BrushBehavior::Source::kNormalizedDirectionY:
+    case BrushBehavior::Source::kDistanceTraveledInMultiplesOfBrushSize:
+    case BrushBehavior::Source::kTimeOfInputInSeconds:
+    case BrushBehavior::Source::
+        kPredictedDistanceTraveledInMultiplesOfBrushSize:
+    case BrushBehavior::Source::kPredictedTimeElapsedInSeconds:
+    case BrushBehavior::Source::kDistanceRemainingInMultiplesOfBrushSize:
+    case BrushBehavior::Source::kTimeSinceInputInSeconds:
+    case BrushBehavior::Source::
+        kAccelerationInMultiplesOfBrushSizePerSecondSquared:
+    case BrushBehavior::Source::
+        kAccelerationXInMultiplesOfBrushSizePerSecondSquared:
+    case BrushBehavior::Source::
+        kAccelerationYInMultiplesOfBrushSizePerSecondSquared:
+    case BrushBehavior::Source::
+        kAccelerationForwardInMultiplesOfBrushSizePerSecondSquared:
+    case BrushBehavior::Source::
+        kAccelerationLateralInMultiplesOfBrushSizePerSecondSquared:
+    case BrushBehavior::Source::kSpeedInCentimetersPerSecond:
+    case BrushBehavior::Source::kVelocityXInCentimetersPerSecond:
+    case BrushBehavior::Source::kVelocityYInCentimetersPerSecond:
+    case BrushBehavior::Source::kDistanceTraveledInCentimeters:
+    case BrushBehavior::Source::kPredictedDistanceTraveledInCentimeters:
+    case BrushBehavior::Source::kAccelerationInCentimetersPerSecondSquared:
+    case BrushBehavior::Source::kAccelerationXInCentimetersPerSecondSquared:
+    case BrushBehavior::Source::kAccelerationYInCentimetersPerSecondSquared:
+    case BrushBehavior::Source::
+        kAccelerationForwardInCentimetersPerSecondSquared:
+    case BrushBehavior::Source::
+        kAccelerationLateralInCentimetersPerSecondSquared:
+    case BrushBehavior::Source::kDistanceRemainingAsFractionOfStrokeLength:
+      return Version::k0Jetpack1_0_0();
+    case BrushBehavior::Source::kTimeSinceStrokeEndInSeconds:
+      return Version::k1Jetpack1_1_0Alpha01();
+    case BrushBehavior::Source::kTimeFromInputToStrokeEndInSeconds:
+      return Version::kDevelopment();
+  }
+}
+
+Version CalculateMinimumRequiredVersion(BrushBehavior::Target target) {
+  switch (target) {
+    case BrushBehavior::Target::kWidthMultiplier:
+    case BrushBehavior::Target::kHeightMultiplier:
+    case BrushBehavior::Target::kSizeMultiplier:
+    case BrushBehavior::Target::kSlantOffsetInRadians:
+    case BrushBehavior::Target::kPinchOffset:
+    case BrushBehavior::Target::kRotationOffsetInRadians:
+    case BrushBehavior::Target::kCornerRoundingOffset:
+    case BrushBehavior::Target::kPositionOffsetXInMultiplesOfBrushSize:
+    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::kLuminosityOffset:
+    case BrushBehavior::Target::kOpacityMultiplier:
+      return Version::k0Jetpack1_0_0();
+  }
+}
+
+Version CalculateMinimumRequiredVersion(BrushBehavior::PolarTarget target) {
+  switch (target) {
+    case BrushBehavior::PolarTarget::
+        kPositionOffsetAbsoluteInRadiansAndMultiplesOfBrushSize:
+    case BrushBehavior::PolarTarget::
+        kPositionOffsetRelativeInRadiansAndMultiplesOfBrushSize:
+      return Version::k0Jetpack1_0_0();
+  }
+}
+
+Version CalculateMinimumRequiredVersion(
+    BrushBehavior::OutOfRange out_of_range) {
+  switch (out_of_range) {
+    case BrushBehavior::OutOfRange::kClamp:
+    case BrushBehavior::OutOfRange::kMirror:
+    case BrushBehavior::OutOfRange::kRepeat:
+      return Version::k0Jetpack1_0_0();
+  }
+}
+
+Version CalculateMinimumRequiredVersion(
+    BrushBehavior::EnabledToolTypes enabled) {
+  return Version::k0Jetpack1_0_0();
+}
+
+Version CalculateMinimumRequiredVersion(BrushBehavior::BinaryOp operation) {
+  switch (operation) {
+    case BrushBehavior::BinaryOp::kProduct:
+    case BrushBehavior::BinaryOp::kSum:
+      return Version::k0Jetpack1_0_0();
+    case BrushBehavior::BinaryOp::kMin:
+    case BrushBehavior::BinaryOp::kMax:
+    case BrushBehavior::BinaryOp::kAndThen:
+    case BrushBehavior::BinaryOp::kOrElse:
+    case BrushBehavior::BinaryOp::kXorElse:
+      return Version::k1Jetpack1_1_0Alpha01();
+  }
+}
+
+Version CalculateMinimumRequiredVersion(
+    BrushBehavior::ProgressDomain progress_domain) {
+  switch (progress_domain) {
+    case BrushBehavior::ProgressDomain::kDistanceInCentimeters:
+    case BrushBehavior::ProgressDomain::kDistanceInMultiplesOfBrushSize:
+    case BrushBehavior::ProgressDomain::kTimeInSeconds:
+      return Version::k0Jetpack1_0_0();
+  }
+}
+
+Version CalculateMinimumRequiredVersion(
+    BrushBehavior::Interpolation interpolation) {
+  switch (interpolation) {
+    case BrushBehavior::Interpolation::kLerp:
+    case BrushBehavior::Interpolation::kInverseLerp:
+      return Version::k0Jetpack1_0_0();
+  }
+}
+
+Version CalculateMinimumRequiredVersion(BrushBehavior::SourceNode node) {
+  return std::max(
+      CalculateMinimumRequiredVersion(node.source_out_of_range_behavior),
+      CalculateMinimumRequiredVersion(node.source));
+}
+
+Version CalculateMinimumRequiredVersion(BrushBehavior::ConstantNode node) {
+  return Version::k0Jetpack1_0_0();
+}
+
+Version CalculateMinimumRequiredVersion(BrushBehavior::NoiseNode node) {
+  return CalculateMinimumRequiredVersion(node.vary_over);
+}
+
+Version CalculateMinimumRequiredVersion(
+    BrushBehavior::ToolTypeFilterNode node) {
+  return CalculateMinimumRequiredVersion(node.enabled_tool_types);
+}
+
+Version CalculateMinimumRequiredVersion(BrushBehavior::DampingNode node) {
+  return CalculateMinimumRequiredVersion(node.damping_source);
+}
+
+Version CalculateMinimumRequiredVersion(BrushBehavior::ResponseNode node) {
+  return brush_internal::CalculateMinimumRequiredVersion(node.response_curve);
+}
+
+Version CalculateMinimumRequiredVersion(BrushBehavior::IntegralNode node) {
+  return std::max(
+      {Version::k1Jetpack1_1_0Alpha01(),
+       CalculateMinimumRequiredVersion(node.integrate_over),
+       CalculateMinimumRequiredVersion(node.integral_out_of_range_behavior)});
+}
+
+Version CalculateMinimumRequiredVersion(BrushBehavior::BinaryOpNode node) {
+  return CalculateMinimumRequiredVersion(node.operation);
+}
+
+Version CalculateMinimumRequiredVersion(BrushBehavior::InterpolationNode node) {
+  return CalculateMinimumRequiredVersion(node.interpolation);
+}
+
+Version CalculateMinimumRequiredVersion(BrushBehavior::TargetNode node) {
+  return CalculateMinimumRequiredVersion(node.target);
+}
+
+Version CalculateMinimumRequiredVersion(BrushBehavior::PolarTargetNode node) {
+  return CalculateMinimumRequiredVersion(node.target);
+}
+
+Version CalculateMinimumRequiredVersion(const BrushBehavior::Node& node) {
+  return std::visit(
+      [](const auto& node) { return CalculateMinimumRequiredVersion(node); },
+      node);
+}
+
+}  // namespace
+
+Version CalculateMinimumRequiredVersion(const BrushBehavior& behavior) {
+  Version max_version = Version::k0Jetpack1_0_0();
+  for (const auto& node : behavior.nodes) {
+    max_version = std::max(max_version, CalculateMinimumRequiredVersion(node));
+  }
+  return max_version;
+}
+
 std::string ToFormattedString(BrushBehavior::Source source) {
   switch (source) {
     case BrushBehavior::Source::kNormalizedPressure:

ink/brush/brush_behavior.h

@@ -16,13 +16,13 @@
 #define INK_STROKES_BRUSH_BRUSH_BEHAVIOR_H_
 
 #include <array>
-#include <cstdint>
 #include <string>
 #include <variant>
 #include <vector>
 
 #include "absl/status/status.h"
 #include "ink/brush/easing_function.h"
+#include "ink/brush/version.h"
 
 namespace ink {
 
@@ -679,6 +679,10 @@ absl::Status ValidateBrushBehaviorTopLevel(const BrushBehavior& behavior);
 
 absl::Status ValidateBrushBehaviorNode(const BrushBehavior::Node& node);
 
+// Calculates the minimum version of the Ink library that is required to use
+// this brush behavior.
+Version CalculateMinimumRequiredVersion(const BrushBehavior& behavior);
+
 std::string ToFormattedString(BrushBehavior::Source source);
 std::string ToFormattedString(BrushBehavior::Target target);
 std::string ToFormattedString(BrushBehavior::PolarTarget target);

ink/brush/brush_coat.cc

@@ -14,16 +14,17 @@
 
 #include "ink/brush/brush_coat.h"
 
+#include <algorithm>
 #include <string>
 
 #include "absl/container/flat_hash_set.h"
 #include "absl/status/status.h"
 #include "absl/strings/str_cat.h"
 #include "absl/strings/str_format.h"
 #include "absl/strings/str_join.h"
-#include "ink/brush/brush_behavior.h"
 #include "ink/brush/brush_paint.h"
 #include "ink/brush/brush_tip.h"
+#include "ink/brush/version.h"
 #include "ink/geometry/mesh_format.h"
 
 namespace ink {
@@ -45,6 +46,14 @@ absl::Status ValidateBrushCoat(const BrushCoat& coat) {
   return absl::OkStatus();
 }
 
+Version CalculateMinimumRequiredVersion(const BrushCoat& coat) {
+  Version max_version = CalculateMinimumRequiredVersion(coat.tip);
+  for (const auto& paint : coat.paint_preferences) {
+    max_version = std::max(max_version, CalculateMinimumRequiredVersion(paint));
+  }
+  return max_version;
+}
+
 void AddAttributeIdsRequiredByCoat(
     const BrushCoat& coat,
     absl::flat_hash_set<MeshFormat::AttributeId>& attribute_ids) {

ink/brush/brush_coat.h

@@ -22,6 +22,7 @@
 #include "absl/status/status.h"
 #include "ink/brush/brush_paint.h"
 #include "ink/brush/brush_tip.h"
+#include "ink/brush/version.h"
 #include "ink/geometry/mesh_format.h"
 
 namespace ink {
@@ -46,6 +47,10 @@ namespace brush_internal {
 // BrushFamily, and returns an error if not.
 absl::Status ValidateBrushCoat(const BrushCoat& coat);
 
+// Calculates the minimum version of the Ink library that is required to use
+// this brush coat.
+Version CalculateMinimumRequiredVersion(const BrushCoat& coat);
+
 // Adds the mesh attribute IDs that are required to properly render a mesh
 // made with this brush coat to the given `attribute_ids` set. This will always
 // include `kPosition` and certain other attribute IDs (`kSideDerivative`,