From ed353f24bf4088a01aa479fc625966d6a6cb8780 Mon Sep 17 00:00:00 2001
From: Ian Wagner <ian.wagner@stadiamaps.com>
Date: Fri, 8 Nov 2024 09:48:30 +0900
Subject: [PATCH] Clarify padding order in the Java API (#2990)

---
 .../src/main/java/org/maplibre/android/maps/MapLibreMap.java  | 4 ++--
 .../src/main/java/org/maplibre/android/maps/NativeMap.java    | 1 +
 .../main/java/org/maplibre/android/maps/NativeMapView.java    | 2 ++
 3 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/MapLibreMap.java b/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/MapLibreMap.java
index d870a76a335..2074b152447 100644
--- a/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/MapLibreMap.java
+++ b/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/MapLibreMap.java
@@ -1546,7 +1546,7 @@ public CameraPosition getCameraForLatLngBounds(@NonNull LatLngBounds latLngBound
    * Get a camera position that fits a provided bounds and padding and the current camera tilt and bearing.
    *
    * @param latLngBounds the bounds to set the map with
-   * @param padding      the padding to apply to the bounds
+   * @param padding      the padding to apply to the bounds (in left, top, right, bottom order)
    * @return the camera position that fits the bounds and padding
    */
   @Nullable
@@ -1579,7 +1579,7 @@ public CameraPosition getCameraForLatLngBounds(@NonNull LatLngBounds latLngBound
    * Get a camera position that fits a provided bounds, padding, bearing and tilt.
    *
    * @param latLngBounds the bounds to set the map with
-   * @param padding      the padding to apply to the bounds
+   * @param padding      the padding to apply to the bounds (in left, top, right, bottom order)
    * @param bearing      the bearing to transform the camera position with
    * @param tilt         to transform the camera position with
    * @return the camera position that fits the bounds, bearing and tilt
diff --git a/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMap.java b/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMap.java
index 21ee9397732..a0435c5779f 100644
--- a/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMap.java
+++ b/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMap.java
@@ -55,6 +55,7 @@ void easeTo(@NonNull LatLng center, double zoom, double bearing, double pitch, d
   @NonNull
   CameraPosition getCameraPosition();
 
+  // Note for implementors: the ordering of the padding is left, top, right, bottom
   CameraPosition getCameraForLatLngBounds(@NonNull LatLngBounds bounds, int[] padding, double bearing, double pitch);
 
   CameraPosition getCameraForGeometry(@NonNull Geometry geometry, int[] padding, double bearing, double pitch);
diff --git a/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMapView.java b/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMapView.java
index 09797905eb4..4ed013c50dc 100755
--- a/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMapView.java
+++ b/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMapView.java
@@ -284,6 +284,8 @@ public CameraPosition getCameraForLatLngBounds(
     if (checkState("getCameraForLatLngBounds")) {
       return null;
     }
+    // Note that we have to juggle things a bit to match the ordering of arguments
+    // to match the NativeMapView C++ interface.
     return nativeGetCameraForLatLngBounds(
       bounds,
       padding[1] / pixelRatio,