Preventing crashes

Unfortunately there are one or two incompatibility issues between MapLibre/Ramani and the Android emulator, which have only come to light due to the wide range of PCs used by you all in this module. These are described here along with solutions.

Style.Builder crashes and unexpected behaviour

Recreating Style.Builder objects (objects used to specify and build the map style) when a composable recomposes can sometimes lead to unpredictable behaviour including crashes, or the map's location and zoom level not being set correctly. This can be avoided by ensuring that you declare your Style.Builder as an attribute of your activity, so that it's initialised only once, rather than on every recompose. For example:

class MyActivity: ComponentActivity() {
    val styleBuilder = Style.Builder().fromUri("https://tiles.openfreemap.org/styles/bright")
    // ....
}

You can then pass styleBuilder into any composable which needs it, as a parameter of type Style.Builder.

OpenGL Related crashes

Separate to the above issue, unfortunately on some machines the emulator appears to crash when displaying MapLibre maps (whether standard MapLibre or Ramani Maps). This appears to be a problem with the low-level code to render the map using OpenGL (graphics rendering library). See below, the highlighted parts show the key symptoms of this crash:

This only appears to happen on certain devices and is likely to be due to graphics card incompatibilities with the OpenGL rendering system running on the virtual device. The following appear to resolve the problem, so try all these:

1. Ensure your virtual device is running at least API level 30 (Android 11). For example, the crash above occurred on a device running API level 28. To minimise memory requirements, I would recommend you use an emulator with exactly API level 30, rather than higher. The crash is most likely to happen on either older API levels (below 30) or recent API levels (34 or 35).
2. If that doesn't work, you can change the OpenGL settings. Open the Extended Controls of the emulator by clicking on the three dots (...) at the top of the controls of the virtual device. Then select Settings. In Settings, you should change the OpenGL ES API level to Renderer maximum. As indicated, you then need to shutdown the device and re-launch it again.
   
3. Try running on a real Android device. You need to enable Developer settings for the device. Please see the Android documentation for full details.
4. Hopefully one or other of these will work for you. If they do not, please see the information below about osmdroid.

If all else fails

In all cases I have seen so far, one or more of the above measures has been enough to get Ramani Maps working on an emulator. However in case it still does not work, you can use osmdroid as an alternative. Please see here for more details.