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; 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::kMax + 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, `kMax` itself must be incremented as well.
* `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 > kMax`. 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 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. 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 (`version::kMax`).
* A test to verify that decoding a `proto::Version` out of the acceptable range (higher than `version::kMax`, lower than `version::kMin`) 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: 872916698

Author: maxmmitchell

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,6 +161,7 @@ cc_library(
     hdrs = ["brush_tip.h"],
     deps = [
         ":brush_behavior",
+        ":version",
         "//ink/geometry:angle",
         "//ink/geometry:mesh_format",
         "//ink/geometry:vec",
@@ -190,6 +192,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 +222,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 +249,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 +278,7 @@ cc_library(
     hdrs = ["brush_paint.h"],
     deps = [
         ":color_function",
+        ":version",
         "//ink/geometry:angle",
         "//ink/geometry:mesh_format",
         "//ink/geometry:vec",
@@ -365,6 +371,16 @@ cc_library(
     ],
 )
 
+cc_library(
+    name = "version",
+    hdrs = ["version.h"],
+    deps = [
+        "@com_google_absl//absl/base:no_destructor",
+        "@com_google_absl//absl/status",
+        "@com_google_absl//absl/strings",
+    ],
+)
+
 cc_test(
     name = "stock_brushes_test",
     srcs = ["stock_brushes_test.cc"],

ink/brush/brush_behavior.cc

@@ -14,9 +14,11 @@
 
 #include "ink/brush/brush_behavior.h"
 
+#include <algorithm>
 #include <array>
 #include <cmath>
 #include <cstddef>
+#include <cstdint>
 #include <string>
 #include <variant>
 
@@ -454,6 +456,206 @@ absl::Status ValidateBrushBehavior(const BrushBehavior& behavior) {
   return absl::OkStatus();
 }
 
+namespace {
+
+int32_t 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 0;
+    case BrushBehavior::Source::kTimeSinceStrokeEndInSeconds:
+      return 1;
+    case BrushBehavior::Source::kTimeFromInputToStrokeEndInSeconds:
+      return 2;
+  }
+}
+
+int32_t 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 0;
+  }
+}
+
+int32_t CalculateMinimumRequiredVersion(BrushBehavior::PolarTarget target) {
+  switch (target) {
+    case BrushBehavior::PolarTarget::
+        kPositionOffsetAbsoluteInRadiansAndMultiplesOfBrushSize:
+    case BrushBehavior::PolarTarget::
+        kPositionOffsetRelativeInRadiansAndMultiplesOfBrushSize:
+      return 0;
+  }
+}
+
+int32_t CalculateMinimumRequiredVersion(
+    BrushBehavior::OutOfRange out_of_range) {
+  switch (out_of_range) {
+    case BrushBehavior::OutOfRange::kClamp:
+    case BrushBehavior::OutOfRange::kMirror:
+    case BrushBehavior::OutOfRange::kRepeat:
+      return 0;
+  }
+}
+
+int32_t CalculateMinimumRequiredVersion(
+    BrushBehavior::EnabledToolTypes enabled) {
+  return 0;
+}
+
+int32_t CalculateMinimumRequiredVersion(BrushBehavior::BinaryOp operation) {
+  switch (operation) {
+    case BrushBehavior::BinaryOp::kProduct:
+    case BrushBehavior::BinaryOp::kSum:
+      return 0;
+    case BrushBehavior::BinaryOp::kMin:
+    case BrushBehavior::BinaryOp::kMax:
+    case BrushBehavior::BinaryOp::kAndThen:
+    case BrushBehavior::BinaryOp::kOrElse:
+    case BrushBehavior::BinaryOp::kXorElse:
+      return 1;
+  }
+}
+
+int32_t CalculateMinimumRequiredVersion(
+    BrushBehavior::ProgressDomain progress_domain) {
+  switch (progress_domain) {
+    case BrushBehavior::ProgressDomain::kDistanceInCentimeters:
+    case BrushBehavior::ProgressDomain::kDistanceInMultiplesOfBrushSize:
+    case BrushBehavior::ProgressDomain::kTimeInSeconds:
+      return 0;
+  }
+}
+
+int32_t CalculateMinimumRequiredVersion(
+    BrushBehavior::Interpolation interpolation) {
+  switch (interpolation) {
+    case BrushBehavior::Interpolation::kLerp:
+    case BrushBehavior::Interpolation::kInverseLerp:
+      return 0;
+  }
+}
+
+int32_t CalculateMinimumRequiredVersion(BrushBehavior::SourceNode node) {
+  return std::max(
+      CalculateMinimumRequiredVersion(node.source_out_of_range_behavior),
+      CalculateMinimumRequiredVersion(node.source));
+}
+
+int32_t CalculateMinimumRequiredVersion(BrushBehavior::ConstantNode node) {
+  return 0;
+}
+
+int32_t CalculateMinimumRequiredVersion(BrushBehavior::NoiseNode node) {
+  return CalculateMinimumRequiredVersion(node.vary_over);
+}
+
+int32_t CalculateMinimumRequiredVersion(
+    BrushBehavior::ToolTypeFilterNode node) {
+  return CalculateMinimumRequiredVersion(node.enabled_tool_types);
+}
+
+int32_t CalculateMinimumRequiredVersion(BrushBehavior::DampingNode node) {
+  return CalculateMinimumRequiredVersion(node.damping_source);
+}
+
+int32_t CalculateMinimumRequiredVersion(BrushBehavior::ResponseNode node) {
+  return brush_internal::CalculateMinimumRequiredVersion(node.response_curve);
+}
+
+int32_t CalculateMinimumRequiredVersion(BrushBehavior::IntegralNode node) {
+  return std::max(
+      {1, CalculateMinimumRequiredVersion(node.integrate_over),
+       CalculateMinimumRequiredVersion(node.integral_out_of_range_behavior)});
+}
+
+int32_t CalculateMinimumRequiredVersion(BrushBehavior::BinaryOpNode node) {
+  return CalculateMinimumRequiredVersion(node.operation);
+}
+
+int32_t CalculateMinimumRequiredVersion(BrushBehavior::InterpolationNode node) {
+  return CalculateMinimumRequiredVersion(node.interpolation);
+}
+
+int32_t CalculateMinimumRequiredVersion(BrushBehavior::TargetNode node) {
+  return CalculateMinimumRequiredVersion(node.target);
+}
+
+int32_t CalculateMinimumRequiredVersion(BrushBehavior::PolarTargetNode node) {
+  return CalculateMinimumRequiredVersion(node.target);
+}
+
+int32_t CalculateMinimumRequiredVersion(const BrushBehavior::Node& node) {
+  return std::visit(
+      [](const auto& node) { return CalculateMinimumRequiredVersion(node); },
+      node);
+}
+
+}  // namespace
+
+int32_t CalculateMinimumRequiredVersion(const BrushBehavior& behavior) {
+  int32_t max_version = 0;
+  for (const BrushBehavior::Node& 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

@@ -23,6 +23,7 @@
 
 #include "absl/status/status.h"
 #include "ink/brush/easing_function.h"
+#include "ink/brush/version.h"
 
 namespace ink {
 
@@ -671,6 +672,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.
+int32_t 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,14 +14,15 @@
 
 #include "ink/brush/brush_coat.h"
 
+#include <algorithm>
+#include <cstdint>
 #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/geometry/mesh_format.h"
@@ -45,6 +46,14 @@ absl::Status ValidateBrushCoat(const BrushCoat& coat) {
   return absl::OkStatus();
 }
 
+int32_t CalculateMinimumRequiredVersion(const BrushCoat& coat) {
+  int32_t max_version = CalculateMinimumRequiredVersion(coat.tip);
+  for (const BrushPaint& 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

@@ -15,6 +15,7 @@
 #ifndef INK_STROKES_BRUSH_BRUSH_COAT_H_
 #define INK_STROKES_BRUSH_BRUSH_COAT_H_
 
+#include <cstdint>
 #include <string>
 
 #include "absl/container/flat_hash_set.h"
@@ -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.
+int32_t 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`,

ink/brush/brush_family.cc

@@ -14,6 +14,7 @@
 
 #include "ink/brush/brush_family.h"
 
+#include <algorithm>
 #include <cstdint>
 #include <string>
 #include <variant>
@@ -94,6 +95,15 @@ std::string BrushFamily::ToFormattedString() const {
   return formatted;
 }
 
+int32_t BrushFamily::CalculateMinimumRequiredVersion() const {
+  int32_t max_version = 0;
+  for (const BrushCoat& coat : coats_) {
+    max_version = std::max(
+        max_version, brush_internal::CalculateMinimumRequiredVersion(coat));
+  }
+  return max_version;
+}
+
 namespace brush_internal {
 namespace {
 

ink/brush/brush_family.h

@@ -152,6 +152,10 @@ class BrushFamily {
   // otherwise used internally by Ink.
   const Metadata& GetMetadata() const;
 
+  // Calculates the minimum version of the Ink library that is required to use
+  // this brush family.
+  int32_t CalculateMinimumRequiredVersion() const;
+
   template <typename Sink>
   friend void AbslStringify(Sink& sink, const BrushFamily& family) {
     sink.Append(family.ToFormattedString());