Expose new experimental modelElevationReference property

Author: persidskiy

Sources/Examples/SwiftUI Examples/Testing Examples/PuckPlayground.swift

@@ -1,5 +1,5 @@
 import SwiftUI
-import MapboxMaps
+@_spi(Experimental) import MapboxMaps
 
 struct PuckPlayground: View {
     enum PuckType: String, CaseIterable, CustomStringConvertible {
@@ -45,6 +45,7 @@ struct PuckPlayground: View {
                     .modelScale(x: scale, y: scale, z: scale)
                     .modelOpacity(opacity)
                     .modelEmissiveStrength(puck3dSettings.emission)
+                    .modelElevationReference(puck3dSettings.elevationReference)
                     .slot(slot)
             }
         }
@@ -85,6 +86,7 @@ struct PuckPlayground: View {
                 SliderSettingView(title: "Light emission", value: $puck3dSettings.emission, range: 0...2, step: 0.1)
                 RadioButtonSettingView(title: "Bearing", value: $bearingType)
                 SliderSettingView(title: "Opacity", value: $opacity, range: 0...1, step: 0.1)
+                RadioButtonSettingView(title: "Elevation Reference", value: $puck3dSettings.elevationReference)
                 slotSettings
             case .none:
                 EmptyView()
@@ -177,6 +179,7 @@ private struct Puck3DSettings {
     var scale = 1.0
     var modelType = ModelType.sportcar
     var emission = 1.0
+    var elevationReference = ModelElevationReference.ground
 }
 
 private struct Puck2DSettings {
@@ -223,6 +226,13 @@ extension PuckBearing: CaseIterable {
     public static var allCases: [PuckBearing] = [.course, .heading]
 }
 
+extension ModelElevationReference: CaseIterable, CustomStringConvertible {
+    public static var allCases: [ModelElevationReference] = [.ground, .sea]
+    public var description: String {
+        return rawValue
+    }
+}
+
 private extension Model {
     static let sportcar = Model(
         uri: Bundle.main.url(forResource: "sportcar", withExtension: "glb"),

Sources/MapboxMaps/ContentBuilders/MapContent/Puck3D.swift

@@ -54,6 +54,14 @@ public struct Puck3D: MapContent, PrimitiveMapContent {
         copyAssigned(self, \.configuration.modelScaleMode, .constant(modelScaleMode))
     }
 
+    /// Selects the base of the model. Some modes might require precomputed elevation data in the tileset.
+    /// Default value: "ground".
+    @_documentation(visibility: public)
+    @_spi(Experimental)
+    public func modelElevationReference(_ value: ModelElevationReference) -> Puck3D {
+        copyAssigned(self, \.configuration.modelElevationReference, .constant(value))
+    }
+
     /// Strength of the emission.
     ///
     /// There is no emission for value 0. For value 1.0, only emissive component (no shading) is displayed and values above 1.0 produce light contribution to surrounding area, for some of the parts (e.g. windows).

Sources/MapboxMaps/Documentation.docc/API Catalogs/Layer Property Values.md

@@ -48,6 +48,7 @@
 - ``FillElevationReference``
 - ``LineElevationReference``
 - ``LineWidthUnit``
+- ``ModelElevationReference``
 
 <!-- Next two are arguable regarding it's category -->
 - ``ImageContent``

Sources/MapboxMaps/Location/Puck/Puck3DRenderer.swift

@@ -88,6 +88,7 @@ final class Puck3DRenderer: PuckRenderer {
         modelLayer.modelReceiveShadows = newConfiguration.modelReceiveShadows
         modelLayer.modelScaleMode = newConfiguration.modelScaleMode
         modelLayer.modelEmissiveStrength = newConfiguration.modelEmissiveStrength
+        modelLayer.modelElevationReference = newConfiguration.modelElevationReference
         modelLayer.slot = newConfiguration.slot
 
         do {

Sources/MapboxMaps/Location/Puck/PuckType.swift

@@ -170,15 +170,24 @@ public struct Puck3DConfiguration: Equatable, Sendable {
     ///
     ///  - Note: Shadows may impose extra performance costs and lead to extra rendering.
     @_documentation(visibility: public)
-    @_spi(Experimental) public var modelCastShadows: Value<Bool>?
+    @_spi(Experimental)
+    public var modelCastShadows: Value<Bool>?
 
     /// Enable/disable shadow receiving for the puck model
     @_documentation(visibility: public)
-    @_spi(Experimental) public var modelReceiveShadows: Value<Bool>?
+    @_spi(Experimental)
+    public var modelReceiveShadows: Value<Bool>?
 
     /// Defines scaling mode. Only applies to location-indicator type layers. Default to ``ModelScaleMode/viewport``.
     @_documentation(visibility: public)
-    @_spi(Experimental) public var modelScaleMode: Value<ModelScaleMode>?
+    @_spi(Experimental)
+    public var modelScaleMode: Value<ModelScaleMode>?
+
+    /// Selects the base of the model. Some modes might require precomputed elevation data in the tileset.
+    /// Default value: "ground".
+    @_documentation(visibility: public)
+    @_spi(Experimental)
+    public var modelElevationReference: Value<ModelElevationReference>?
 
     /// Strength of the emission.
     ///

Sources/MapboxMaps/Style/Generated/Layers/ModelLayer.swift

@@ -148,6 +148,7 @@ final class Puck3DRendererTests: XCTestCase {
         XCTAssertEqual(actualLayer.modelCastShadows, configuration.modelCastShadows)
         XCTAssertEqual(actualLayer.modelReceiveShadows, configuration.modelReceiveShadows)
         XCTAssertEqual(actualLayer.modelEmissiveStrength, configuration.modelEmissiveStrength)
+        XCTAssertEqual(actualLayer.modelElevationReference, configuration.modelElevationReference)
         XCTAssertEqual(actualLayer.slot, configuration.slot)
     }