feat: extract android UserLocation FPS

CHANGELOG.md

@@ -6,6 +6,8 @@ PR Title ([#123](link to my pr))
 
 ```
 
+feat: [feat: extract android UserLocation FPS]([#428](https://github.com/maplibre/maplibre-react-native/pull/428))
+
 ## 10.0.0-alpha.11
 
 Chore: [bump maplibre native ios to 6.5.4](https://github.com/maplibre/maplibre-react-native/pull/437)

android/rctmln/src/main/java/com/maplibre/rctmln/components/location/LocationComponentManager.java

@@ -67,6 +67,15 @@ public void setRenderMode(@RenderMode.Mode int renderMode) {
         }
     }
 
+    public void setPreferredFramesPerSecond(int preferredFramesPerSecond) {
+       if(preferredFramesPerSecond <= 0) {
+            return;
+       }
+
+        mLocationComponent.setMaxAnimationFps(preferredFramesPerSecond);
+    }
+
+
     public void addOnCameraTrackingChangedListener(OnCameraTrackingChangedListener onCameraTrackingChangedListener) {
         mLocationComponent.addOnCameraTrackingChangedListener(onCameraTrackingChangedListener);
     }

android/rctmln/src/main/java/com/maplibre/rctmln/components/location/RCTMLNNativeUserLocation.java

@@ -17,6 +17,7 @@ public class RCTMLNNativeUserLocation extends AbstractMapFeature implements OnMa
     private MapLibreMap mMap;
     private RCTMLNMapView mMapView;
     private @RenderMode.Mode int mRenderMode = RenderMode.COMPASS;
+    private int mPreferredFramesPerSecond;
 
     public RCTMLNNativeUserLocation(Context context) {
         super(context);
@@ -28,6 +29,7 @@ public void addToMap(RCTMLNMapView mapView) {
         mMapView = mapView;
         mapView.getMapAsync(this);
         setRenderMode(mRenderMode);
+        setPreferredFramesPerSecond(mPreferredFramesPerSecond);
     }
 
     @Override
@@ -63,4 +65,12 @@ public void setRenderMode(@RenderMode.Mode int renderMode) {
             locationComponent.setRenderMode(renderMode);
         }
     }
+
+    public void setPreferredFramesPerSecond(int framesPerSecond) {
+        mPreferredFramesPerSecond = framesPerSecond;
+        if (mMapView != null) {
+            LocationComponentManager locationComponent = mMapView.getLocationComponentManager();
+            locationComponent.setPreferredFramesPerSecond(framesPerSecond);
+        }
+    }
 }

android/rctmln/src/main/java/com/maplibre/rctmln/components/location/RCTMLNNativeUserLocationManager.java

@@ -27,6 +27,11 @@ public void setAndroidRenderMode(RCTMLNNativeUserLocation userLocation, String m
        }
     }
 
+    @ReactProp(name="androidPreferredFramesPerSecond")
+    public void setPreferredFramesPerSecond(RCTMLNNativeUserLocation userLocation, int preferredFramesPerSecond) {
+       userLocation.setPreferredFramesPerSecond(preferredFramesPerSecond);
+    }
+
     @Nonnull
     @Override
     protected RCTMLNNativeUserLocation createViewInstance(@Nonnull ThemedReactContext reactContext) {

docs/NativeUserLocation.md

@@ -7,5 +7,6 @@
 | ---- | :--: | :-----: | :------: | :----------: |
 | androidRenderMode | `"normal" \| "compass" \| "gps"` | `none` | `false` | Android render mode.<br/><br/> - normal: just a circle<br/> - compass: triangle with heading<br/> - gps: large arrow<br/><br/>@platform android |
 | iosShowsUserHeadingIndicator | `boolean` | `none` | `false` | iOS only. A Boolean value indicating whether the user location annotation may display a permanent heading indicator.<br/><br/>@platform ios |
+| androidPreferredFramesPerSecond | `number` | `none` | `false` | Android only. Set max FPS at which location animators can output updates. Use this setting to limit animation rate of the location puck on higher zoom levels to decrease the stress on the device's CPU which can directly improve battery life, without sacrificing UX. |
 
 

docs/UserLocation.md

@@ -11,6 +11,7 @@
 | visible | `boolean` | `true` | `false` | Whether location icon is visible |
 | showsUserHeadingIndicator | `boolean` | `false` | `false` | Show or hide small arrow which indicates direction the device is pointing relative to north. |
 | minDisplacement | `number` | `0` | `false` | Minimum amount of movement before GPS location is updated in meters |
+| androidPreferredFramesPerSecond | `number` | `none` | `false` | Android only. Set max FPS at which location animators can output updates. Use this setting to limit animation rate of the location puck on higher zoom levels to decrease the stress on the device's CPU which can directly improve battery life, without sacrificing UX.<br/><br/>@platform android |
 | children | `ReactElement \| ReactElement[]` | `none` | `false` | Custom location icon of type mapbox-gl-native components<br/><br/>NOTE: Forking maintainer does not understand the above comment. |
 
 ### methods

docs/docs.json

@@ -2659,6 +2659,13 @@
         "type": "boolean",
         "default": "none",
         "description": "iOS only. A Boolean value indicating whether the user location annotation may display a permanent heading indicator.\n\n@platform ios"
+      },
+      {
+        "name": "androidPreferredFramesPerSecond",
+        "required": false,
+        "type": "number",
+        "default": "none",
+        "description": "Android only. Set max FPS at which location animators can output updates. Use this setting to limit animation rate of the location puck on higher zoom levels to decrease the stress on the device's CPU which can directly improve battery life, without sacrificing UX."
       }
     ],
     "fileNameWithExt": "NativeUserLocation.tsx",
@@ -4843,6 +4850,13 @@
         "default": "0",
         "description": "Minimum amount of movement before GPS location is updated in meters"
       },
+      {
+        "name": "androidPreferredFramesPerSecond",
+        "required": false,
+        "type": "number",
+        "default": "none",
+        "description": "Android only. Set max FPS at which location animators can output updates. Use this setting to limit animation rate of the location puck on higher zoom levels to decrease the stress on the device's CPU which can directly improve battery life, without sacrificing UX.\n\n@platform android"
+      },
       {
         "name": "children",
         "required": false,

example/src/examples/UserLocation/SetAndroidPreferredFramesPerSecond.tsx

@@ -0,0 +1,48 @@
+import MapLibreGL from "@maplibre/maplibre-react-native";
+import React from "react";
+
+import sheet from "../../styles/sheet";
+import TabBarPage from "../common/TabBarPage";
+
+const FPS = [5, 10, 15];
+const OPTIONS = [{ label: "5 fps" }, { label: "10 fps" }, { label: "15 fps" }];
+
+class SetAndroidPreferredFramesPerSecond extends React.Component {
+  state = { androidPreferredFramesPerSecond: FPS[0] };
+
+  componentDidMount() {
+    MapLibreGL.locationManager.start();
+  }
+
+  componentWillUnmount() {
+    MapLibreGL.locationManager.stop();
+  }
+
+  onFramesPerSecondChange = (index: number) => {
+    this.setState({ androidPreferredFramesPerSecond: FPS[index] });
+  };
+
+  render() {
+    return (
+      <TabBarPage
+        {...this.props}
+        options={OPTIONS}
+        onOptionPress={this.onFramesPerSecondChange}
+      >
+        <MapLibreGL.MapView style={sheet.matchParent}>
+          <MapLibreGL.Camera followZoomLevel={16} followUserLocation />
+
+          <MapLibreGL.UserLocation
+            animated
+            renderMode="native"
+            androidPreferredFramesPerSecond={
+              this.state.androidPreferredFramesPerSecond
+            }
+          />
+        </MapLibreGL.MapView>
+      </TabBarPage>
+    );
+  }
+}
+
+export default SetAndroidPreferredFramesPerSecond;

example/src/scenes/Examples.js

@@ -63,6 +63,7 @@ import SetTintColor from '../examples/UserLocation/SetTintColor';
 import SetUserLocationRenderMode from '../examples/UserLocation/SetUserLocationRenderMode';
 import SetUserLocationVerticalAlignment from '../examples/UserLocation/SetUserLocationVerticalAlignment';
 import UserLocationChange from '../examples/UserLocation/UserLocationChange';
+import SetAndroidPreferredFramesPerSecond from '../examples/UserLocation/SetAndroidPreferredFramesPerSecond';
 // MISC
 import BugReportPage from '../examples/BugReportPage';
 import CacheManagement from '../examples/CacheManagement';
@@ -144,6 +145,7 @@ const Examples = new ExampleGroup(
         'Set User Location Render Mode',
         SetUserLocationRenderMode,
       ),
+      new ExampleItem('Set Preferred Frames Per Second (Android only)', SetAndroidPreferredFramesPerSecond),
     ]),
     new ExampleGroup('Symbol/CircleLayer', [
       new ExampleItem('Custom Icon', CustomIcon),

javascript/components/NativeUserLocation.tsx

@@ -20,6 +20,10 @@ interface NativeUserLocationProps {
    * @platform ios
    */
   iosShowsUserHeadingIndicator?: boolean;
+  /**
+   * Android only. Set max FPS at which location animators can output updates. Use this setting to limit animation rate of the location puck on higher zoom levels to decrease the stress on the device's CPU which can directly improve battery life, without sacrificing UX.
+   */
+  androidPreferredFramesPerSecond?: number;
 }
 
 const NativeUserLocation = (props: NativeUserLocationProps): ReactElement => {

javascript/components/UserLocation.tsx

@@ -93,6 +93,12 @@ interface UserLocationProps {
    * Minimum amount of movement before GPS location is updated in meters
    */
   minDisplacement?: number;
+  /**
+   * Android only. Set max FPS at which location animators can output updates. Use this setting to limit animation rate of the location puck on higher zoom levels to decrease the stress on the device's CPU which can directly improve battery life, without sacrificing UX.
+   *
+   * @platform android
+   */
+  androidPreferredFramesPerSecond?: number;
   /**
    * Custom location icon of type mapbox-gl-native components
    *
@@ -128,6 +134,7 @@ const UserLocation = React.memo(
         minDisplacement = 0,
         renderMode = "normal",
         androidRenderMode,
+        androidPreferredFramesPerSecond,
         children,
         onUpdate,
         onPress,
@@ -259,6 +266,7 @@ const UserLocation = React.memo(
         const props = {
           androidRenderMode,
           iosShowsUserHeadingIndicator: showsUserHeadingIndicator,
+          androidPreferredFramesPerSecond,
         };
 
         return <NativeUserLocation {...props} />;