feat: add V4 field binding projection identities

include/mbgl/particle/field/field_binding.hpp

@@ -0,0 +1,121 @@
+#pragma once
+
+#include <mbgl/particle/field/field_runtime.hpp>
+
+#include <memory>
+#include <optional>
+#include <string>
+
+namespace mbgl::particle {
+
+// Host-owned binding intent. FieldPlaneKey identity is deliberately only its
+// semanticID/groupID pair; component is validated from the selected plane.
+struct ColorBinding {
+    std::string fieldKey;
+    FieldPlaneKey plane;
+    FieldValueClass expectedValueClass = FieldValueClass::Scalar;
+    uint16_t expectedUnitID = FieldUnitNone;
+
+    bool operator==(const ColorBinding&) const;
+};
+
+enum class ParticleBindingMode : uint8_t { VectorComponents, DirectionAngle };
+
+struct ParticleBinding {
+    ParticleBindingMode mode = ParticleBindingMode::VectorComponents;
+    std::string fieldKey;
+    FieldPlaneKey uPlane;
+    FieldPlaneKey vPlane;
+    FieldPlaneKey directionPlane;
+    uint16_t expectedUnitID = FieldUnitNone;
+
+    bool operator==(const ParticleBinding&) const;
+};
+
+struct FieldSampleState {
+    uint64_t requestedForecastTimeMs = 0;
+    float mix = 0.0f;
+};
+
+struct ColorProjectionContentIdentity {
+    ColorBinding binding;
+    FrameContentIdentity t0Frame;
+    FrameContentIdentity t1Frame;
+    std::string t0Plane;
+    std::string t1Plane;
+    std::string t0Validity;
+    std::string t1Validity;
+
+    bool operator==(const ColorProjectionContentIdentity&) const;
+};
+
+struct ParticleProjectionContentIdentity {
+    ParticleBinding binding;
+    FrameContentIdentity t0Frame;
+    FrameContentIdentity t1Frame;
+    std::string t0FirstPlane;
+    std::string t1FirstPlane;
+    std::string t0SecondPlane;
+    std::string t1SecondPlane;
+    std::string t0Validity;
+    std::string t1Validity;
+
+    bool operator==(const ParticleProjectionContentIdentity&) const;
+};
+
+struct ColorProjection {
+    ColorProjectionContentIdentity contentIdentity;
+    FieldSampleState sampleState;
+    std::shared_ptr<const DecodedFieldFrame> t0Frame;
+    std::shared_ptr<const DecodedFieldFrame> t1Frame;
+    std::shared_ptr<const std::vector<uint8_t>> t0PlaneStorage;
+    std::shared_ptr<const std::vector<uint8_t>> t1PlaneStorage;
+    std::shared_ptr<const std::vector<uint8_t>> t0ValidityStorage;
+    std::shared_ptr<const std::vector<uint8_t>> t1ValidityStorage;
+};
+
+struct ParticleProjection {
+    ParticleProjectionContentIdentity contentIdentity;
+    FieldSampleState sampleState;
+    std::shared_ptr<const DecodedFieldFrame> t0Frame;
+    std::shared_ptr<const DecodedFieldFrame> t1Frame;
+    std::shared_ptr<const std::vector<uint8_t>> t0FirstPlaneStorage;
+    std::shared_ptr<const std::vector<uint8_t>> t1FirstPlaneStorage;
+    std::shared_ptr<const std::vector<uint8_t>> t0SecondPlaneStorage;
+    std::shared_ptr<const std::vector<uint8_t>> t1SecondPlaneStorage;
+    std::shared_ptr<const std::vector<uint8_t>> t0ValidityStorage;
+    std::shared_ptr<const std::vector<uint8_t>> t1ValidityStorage;
+};
+
+enum class BindingProjectionError : uint8_t {
+    Accepted,
+    InvalidBinding,
+    FieldSeriesMissing,
+    WindowUnavailable,
+    PlaneMissing,
+    PlaneClassMismatch,
+    PlaneUnitMismatch,
+    PlaneComponentMismatch,
+    PlaneGroupMismatch,
+    InterpolationIncompatible,
+};
+
+struct ColorProjectionResult {
+    BindingProjectionError error = BindingProjectionError::InvalidBinding;
+    std::optional<ColorProjection> projection;
+    bool accepted() const { return error == BindingProjectionError::Accepted; }
+};
+
+struct ParticleProjectionResult {
+    BindingProjectionError error = BindingProjectionError::InvalidBinding;
+    std::optional<ParticleProjection> projection;
+    bool accepted() const { return error == BindingProjectionError::Accepted; }
+};
+
+class BindingProjectionResolver final {
+public:
+    static ColorProjectionResult resolve(const EncodedFieldStore&, const ColorBinding&, uint64_t requestedForecastTimeMs);
+    static ParticleProjectionResult resolve(const EncodedFieldStore&, const ParticleBinding&, uint64_t requestedForecastTimeMs);
+};
+
+} // namespace mbgl::particle