Add QFormatOrFloatingPoint proto.

  - In the future, we can use this at the proto level for fields that would read better as floating point (b/391851526).
  - Named `q7_dot8` to comply with [proto style on underscores](https://protobuf.dev/programming-guides/style/).

PiperOrigin-RevId: 856764867

Author: jwcullen

iamf/cli/proto/BUILD

@@ -99,6 +99,11 @@ proto_library(
     srcs = ["test_vector_metadata.proto"],
 )
 
+proto_library(
+    name = "types_proto",
+    srcs = ["types.proto"],
+)
+
 proto_library(
     name = "user_metadata_proto",
     srcs = ["user_metadata.proto"],
@@ -186,6 +191,11 @@ cc_proto_library(
     deps = [":test_vector_metadata_proto"],
 )
 
+cc_proto_library(
+    name = "types_cc_proto",
+    deps = [":types_proto"],
+)
+
 cc_proto_library(
     name = "user_metadata_cc_proto",
     deps = [":user_metadata_proto"],

iamf/cli/proto/types.proto

@@ -0,0 +1,27 @@
+
+// Copyright (c) 2026, Alliance for Open Media. All rights reserved
+//
+// This source code is subject to the terms of the BSD 3-Clause Clear License
+// and the Alliance for Open Media Patent License 1.0. If the BSD 3-Clause Clear
+// License was not distributed with this source code in the LICENSE file, you
+// can obtain it at www.aomedia.org/license/software-license/bsd-3-c-c. If the
+// Alliance for Open Media Patent License 1.0 was not distributed with this
+// source code in the PATENTS file, you can obtain it at
+// www.aomedia.org/license/patent.
+
+edition = "2023";
+
+package iamf_tools_cli_proto;
+
+option java_outer_classname = "Types";
+option java_multiple_files = true;
+
+// For use when it could be convenient to represent the same logical field as
+// either floating point or Q-format in different contexts.
+message QFormatOrFloatingPoint {
+  oneof value {
+    float floating_point = 1;
+    int32 q7_dot8 = 2;
+    // TODO: b/391851526 - Add Q8.0 format.
+  }
+}

iamf/cli/proto_conversion/BUILD

@@ -130,7 +130,9 @@ cc_library(
         "//iamf/cli/proto:param_definitions_cc_proto",
         "//iamf/cli/proto:parameter_data_cc_proto",
         "//iamf/cli/proto:test_vector_metadata_cc_proto",
+        "//iamf/cli/proto:types_cc_proto",
         "//iamf/common:leb_generator",
+        "//iamf/common:q_format_or_floating_point",
         "//iamf/common/utils:macros",
         "//iamf/common/utils:map_utils",
         "//iamf/common/utils:numeric_utils",
@@ -140,6 +142,7 @@ cc_library(
         "//iamf/obu/param_definitions:param_definition_base",
         "@abseil-cpp//absl/log:absl_log",
         "@abseil-cpp//absl/status",
+        "@abseil-cpp//absl/status:statusor",
         "@abseil-cpp//absl/strings:string_view",
     ],
 )

iamf/cli/proto_conversion/proto_utils.cc

@@ -20,12 +20,15 @@
 
 #include "absl/log/absl_log.h"
 #include "absl/status/status.h"
+#include "absl/status/statusor.h"
 #include "absl/strings/string_view.h"
 #include "iamf/cli/proto/obu_header.pb.h"
 #include "iamf/cli/proto/param_definitions.pb.h"
 #include "iamf/cli/proto/parameter_data.pb.h"
+#include "iamf/cli/proto/types.pb.h"
 #include "iamf/cli/proto_conversion/lookup_tables.h"
 #include "iamf/common/leb_generator.h"
+#include "iamf/common/q_format_or_floating_point.h"
 #include "iamf/common/utils/macros.h"
 #include "iamf/common/utils/map_utils.h"
 #include "iamf/common/utils/numeric_utils.h"
@@ -36,6 +39,24 @@
 
 namespace iamf_tools {
 
+absl::StatusOr<QFormatOrFloatingPoint> ProtoToQFormatOrFloatingPoint(
+    const iamf_tools_cli_proto::QFormatOrFloatingPoint&
+        input_q_format_or_floating_point) {
+  if (input_q_format_or_floating_point.has_q7_dot8()) {
+    int16_t q7_8_int16;
+    RETURN_IF_NOT_OK(StaticCastIfInRange(
+        "QFormatOrFloatingPoint.q7_dot8",
+        input_q_format_or_floating_point.q7_dot8(), q7_8_int16));
+    return QFormatOrFloatingPoint::MakeFromQ7_8(q7_8_int16);
+  } else if (input_q_format_or_floating_point.has_floating_point()) {
+    return QFormatOrFloatingPoint::CreateFromFloatingPoint(
+        input_q_format_or_floating_point.floating_point());
+  } else {
+    // By default, return a safe 0.
+    return QFormatOrFloatingPoint::MakeFromQ7_8(0);
+  }
+}
+
 absl::Status CopyParamDefinition(
     const iamf_tools_cli_proto::ParamDefinition& input_param_definition,
     ParamDefinition& param_definition) {

iamf/cli/proto_conversion/proto_utils.h

@@ -16,17 +16,30 @@
 #include <memory>
 
 #include "absl/status/status.h"
+#include "absl/status/statusor.h"
 #include "iamf/cli/proto/obu_header.pb.h"
 #include "iamf/cli/proto/param_definitions.pb.h"
 #include "iamf/cli/proto/parameter_data.pb.h"
 #include "iamf/cli/proto/test_vector_metadata.pb.h"
+#include "iamf/cli/proto/types.pb.h"
 #include "iamf/common/leb_generator.h"
+#include "iamf/common/q_format_or_floating_point.h"
 #include "iamf/obu/demixing_info_parameter_data.h"
 #include "iamf/obu/obu_header.h"
 #include "iamf/obu/param_definitions/param_definition_base.h"
 
 namespace iamf_tools {
 
+/*!\brief Converts to the internal representation of the input protocol buffer.
+ *
+ * \param q_format_or_floating_point Input protocol buffer.
+ * \return Internal representation of a `QFormatOrFloatingPoint` on success. A
+ *     specific status on failure.
+ */
+absl::StatusOr<QFormatOrFloatingPoint> ProtoToQFormatOrFloatingPoint(
+    const iamf_tools_cli_proto::QFormatOrFloatingPoint&
+        input_q_format_or_floating_point);
+
 /*!\brief Copies param definitions from the corresponding protocol buffer.
  *
  * \param input_param_definition Input protocol buffer.

iamf/cli/proto_conversion/tests/BUILD

@@ -69,13 +69,13 @@ cc_test(
     srcs = ["proto_utils_test.cc"],
     deps = [
         "//iamf/cli/proto:obu_header_cc_proto",
+        "//iamf/cli/proto:param_definitions_cc_proto",
         "//iamf/cli/proto:parameter_data_cc_proto",
         "//iamf/cli/proto_conversion:proto_utils",
         "//iamf/common:leb_generator",
         "//iamf/obu:obu_header",
         "//iamf/obu:parameter_data",
         "//iamf/obu/param_definitions:mix_gain_param_definition",
-        "@abseil-cpp//absl/status:status_matchers",
         "@com_google_googletest//:gtest_main",
         "@com_google_protobuf//:protobuf",
     ],

iamf/cli/proto_conversion/tests/proto_utils_test.cc

@@ -15,10 +15,10 @@
 #include <memory>
 #include <vector>
 
-#include "absl/status/status_matchers.h"
 #include "gmock/gmock.h"
 #include "gtest/gtest.h"
 #include "iamf/cli/proto/obu_header.pb.h"
+#include "iamf/cli/proto/param_definitions.pb.h"
 #include "iamf/cli/proto/parameter_data.pb.h"
 #include "iamf/common/leb_generator.h"
 #include "iamf/obu/demixing_info_parameter_data.h"
@@ -30,6 +30,51 @@ namespace iamf_tools {
 namespace {
 
 using ::absl_testing::IsOk;
+using ::testing::FloatNear;
+using ::testing::Not;
+
+TEST(GetQ7_8FromProto, Q7_8) {
+  iamf_tools_cli_proto::QFormatOrFloatingPoint q_format_or_floating_point;
+  q_format_or_floating_point.set_q7_dot8(256);
+  auto converted = ProtoToQFormatOrFloatingPoint(q_format_or_floating_point);
+
+  ASSERT_THAT(converted, IsOk());
+  EXPECT_EQ(converted->GetQ7_8(), 256);
+}
+
+TEST(GetQ7_8FromProto, Float) {
+  iamf_tools_cli_proto::QFormatOrFloatingPoint q_format_or_floating_point;
+  q_format_or_floating_point.set_floating_point(1.5);
+  auto converted = ProtoToQFormatOrFloatingPoint(q_format_or_floating_point);
+
+  ASSERT_THAT(converted, IsOk());
+  EXPECT_THAT(converted->GetFloatingPoint(), FloatNear(1.5, 1e-6));
+}
+
+TEST(GetQ7_8FromProto, NeitherSetDefaultsToZero) {
+  iamf_tools_cli_proto::QFormatOrFloatingPoint q_format_or_floating_point;
+
+  auto converted = ProtoToQFormatOrFloatingPoint(q_format_or_floating_point);
+
+  ASSERT_THAT(converted, IsOk());
+  EXPECT_EQ(converted->GetQ7_8(), 0);
+}
+
+TEST(GetQ7_8FromProto, Q7_8OutOfRangeReturnsError) {
+  iamf_tools_cli_proto::QFormatOrFloatingPoint q_format_or_floating_point;
+  q_format_or_floating_point.set_q7_dot8(65536);
+
+  EXPECT_THAT(ProtoToQFormatOrFloatingPoint(q_format_or_floating_point),
+              Not(IsOk()));
+}
+
+TEST(GetQ7_8FromProto, FloatOutOfRangeReturnsError) {
+  iamf_tools_cli_proto::QFormatOrFloatingPoint q_format_or_floating_point;
+  q_format_or_floating_point.set_floating_point(1000.0);
+
+  EXPECT_THAT(ProtoToQFormatOrFloatingPoint(q_format_or_floating_point),
+              Not(IsOk()));
+}
 
 TEST(CopyDemixingInfoParameterData, Basic) {
   iamf_tools_cli_proto::DemixingInfoParameterData

iamf/common/q_format_or_floating_point.cc

@@ -31,8 +31,8 @@ QFormatOrFloatingPoint::CreateFromFloatingPoint(float value) {
   return QFormatOrFloatingPoint(q7_8);
 }
 
-QFormatOrFloatingPoint QFormatOrFloatingPoint::MakeFromQ7_8(int16_t q78) {
-  return QFormatOrFloatingPoint(q78);
+QFormatOrFloatingPoint QFormatOrFloatingPoint::MakeFromQ7_8(int16_t q7_8) {
+  return QFormatOrFloatingPoint(q7_8);
 }
 
 QFormatOrFloatingPoint::QFormatOrFloatingPoint(int16_t q7_8)

iamf/common/q_format_or_floating_point.h

@@ -32,10 +32,10 @@ class QFormatOrFloatingPoint {
  public:
   /*!\brief Creates an instance from a Q7.8 value.
    *
-   * \param q78 Q7.8 value to initialize from.
-   * \return `QFormatOrFloatingPoint` created from `q78`.
+   * \param q7_8 Q7.8 value to initialize from.
+   * \return `QFormatOrFloatingPoint` created from `q7_8`.
    */
-  static QFormatOrFloatingPoint MakeFromQ7_8(int16_t q78);
+  static QFormatOrFloatingPoint MakeFromQ7_8(int16_t q7_8);
 
   /*!\brief Creates an instance from a floating point value.
    *