AnnotationManagerImpl cleanup images on delete (#11010)

https://mapbox.atlassian.net/browse/MAPSAND-2595

## Changes

### `AnnotationManagerImpl` ref-counted style image tracking

Added a `StyleImages` inner class that tracks a reference count per
style image ID. Each annotation that holds an `_iconImage` starting with
`ICON_DEFAULT_NAME_PREFIX` increments the counter on creation and
decrements it on deletion. The style image is removed from the map only
when the count reaches zero.

The manager-level `iconImageBitmap` setter calls `addStyleImage()` →
`styleImages.put(imageId)`, contributing its own ref-count entry. That
entry is released by `deleteAll()` / manager teardown, but not by
deleting individual annotations that don't carry an explicit
`iconImage`.

### `PointAnnotation._iconImage` internal property + deprecation
The existing public `iconImage` property now delegates to `_iconImage`
and its getter is marked `@Deprecated`

## Tests for style image reference count

| Test | Scenario |
|------|----------|
| `delete annotation with unique bitmap removes style image` | Single
annotation deleted → image removed |
| `deleteAll removes all unique style images` | Two unique bitmaps,
deleteAll → both removed |
| `deleting first of two shared-bitmap annotations preserves style
image` | Same bitmap, delete one → image stays |
| `deleting both shared-bitmap annotations removes style image` | Same
bitmap, delete both → image removed |
| `deleting source annotation preserves style image when cached-id
annotation is alive` | A+B share id string, delete A → image stays;
delete B → image removed |
| `deleting individual annotation does not remove manager-level style
image` | `manager.iconImageBitmap` set, delete annotation without
explicit iconImage → image stays |
| `deleteAll removes manager-level style image` |
`manager.iconImageBitmap` set, deleteAll → image removed |
| `creating annotation with previously deleted image re-adds style
image` | Delete A (image removed), create B with same bitmap → image
re-uploaded |
| `creating string-id annotation after source annotation deleted does
not re-add style image` | Delete A (image removed), create B with cached
ID string only → image absent from style, B not shown |

## Caveats

1. If a user caches the image ID string from one annotation, deletes
that annotation (which removes the image from the style), and then
creates a new annotation with the cached ID via `withIconImage(String)`.
The new annotation will not be rendered because no bitmap is available
to re-upload the image.
2. Annotations sharing the same bitmap (same `hashCode`) share the same
image ID and ref-count entry. Each creation increments and each deletion
decrements the shared counter. Ticket
https://mapbox.atlassian.net/browse/MAPSAND-2593

cc @mapbox/maps-android
cc @mapbox/sdk-platform

GitOrigin-RevId: 12b93934af2b15dba6849d02388e3be4b48af5b1

Author: kediarov

CHANGELOG.md

@@ -5,7 +5,11 @@ Mapbox welcomes participation and contributions from everyone.
 > **16 KB Page Size Support:** Starting with version 11.7.0 and 10.19.0, **NDK 27 is supported** with dedicated artifacts that include [support for 16 KB page sizes](https://developer.android.com/guide/practices/page-sizes). If your app does not require 16 KB page size support, you can keep using our default artifacts without `-ndk27` suffix. For more information about our NDK support, see https://docs.mapbox.com/android/maps/guides/#ndk-support
 
 # main
+## Features ✨ and improvements 🏁
+* Deprecate `PointAnnotation.iconImage` getter. Reading this property exposes an internally generated image ID managed by the annotation manager. If you need a stable, reusable image ID, register the image in the style yourself via the Style API and pass the ID explicitly via `PointAnnotationOptions.withIconImage(String)`. In that case you are responsible for the image's lifecycle and must remove it from the style when no longer needed.
+
 ## Bug fixes 🐞
+* Fix native memory leak in `AnnotationManager` where bitmap style images were not removed when annotations were deleted.
 * Fix feature ID format mismatch in JNI marshaling where whole-number `double` feature IDs (e.g. `12345.0`) were incorrectly serialized as `"12345.000000"` instead of `"12345"`, causing `setFeatureState` to fail when using IDs obtained from `queryRenderedFeatures`.
 
 # 11.21.0-rc.1 March 23, 2026

app/src/main/java/com/mapbox/maps/testapp/examples/markersandcallouts/viewannotation/ViewAnnotationWithPointAnnotationActivity.kt

@@ -67,7 +67,7 @@ class ViewAnnotationWithPointAnnotationActivity : AppCompatActivity() {
       }
       // show / hide view annotation based on marker visibility
       binding.fabStyleToggle.setOnClickListener {
-        if (pointAnnotation.iconImage == null) {
+        if (pointAnnotation.iconImageBitmap == null) {
           pointAnnotation.iconImageBitmap = bitmapFromDrawableRes(R.drawable.ic_blue_marker)
           viewAnnotation.isVisible = true
         } else {

plugin-annotation/api/Release/metalava.txt

@@ -348,7 +348,7 @@ package com.mapbox.maps.plugin.annotation.generated {
     method public String? getIconHaloColorString();
     method public String? getIconHaloColorUseTheme();
     method public Double? getIconHaloWidth();
-    method public String? getIconImage();
+    method @Deprecated public String? getIconImage();
     method public android.graphics.Bitmap? getIconImageBitmap();
     method @Deprecated public Double? getIconImageCrossFade();
     method public Double? getIconOcclusionOpacity();
@@ -441,7 +441,7 @@ package com.mapbox.maps.plugin.annotation.generated {
     property public final String? iconHaloColorString;
     property public final String? iconHaloColorUseTheme;
     property public final Double? iconHaloWidth;
-    property public final String? iconImage;
+    property @Deprecated public final String? iconImage;
     property public final android.graphics.Bitmap? iconImageBitmap;
     property @Deprecated public final Double? iconImageCrossFade;
     property public final Double? iconOcclusionOpacity;

plugin-annotation/src/main/java/com/mapbox/maps/plugin/annotation/AnnotationManagerImpl.kt

@@ -82,6 +82,7 @@ internal constructor(
   private var draggingAnnotation: T? = null
   private val annotationMap = LinkedHashMap<String, T>()
   private val dragAnnotationMap = LinkedHashMap<String, T>()
+  private val styleImages = StyleImages()
   internal val dataDrivenPropertyDefaultValues: JsonObject = JsonObject()
 
   private val interactionsCancelableSet = mutableSetOf<Cancelable>()
@@ -546,6 +547,7 @@ internal constructor(
   override fun create(option: S): T {
     return option.build(UUID.randomUUID().toString(), this).also {
       annotationMap[it.id] = it
+      styleImages.put(it)
       updateSource()
     }
   }
@@ -557,6 +559,7 @@ internal constructor(
     val list = options.map { option ->
       option.build(UUID.randomUUID().toString(), this).also {
         annotationMap[it.id] = it
+        styleImages.put(it)
       }
     }
     updateSource()
@@ -568,8 +571,10 @@ internal constructor(
    */
   override fun delete(annotation: T) {
     if (annotationMap.remove(annotation.id) != null) {
+      styleImages.remove(annotation)
       updateSource()
     } else if (dragAnnotationMap.remove(annotation.id) != null) {
+      styleImages.remove(annotation)
       updateDragSource()
     } else {
       logW(
@@ -587,8 +592,10 @@ internal constructor(
     var needUpdateDragSource = false
     annotations.forEach {
       if (annotationMap.remove(it.id) != null) {
+        styleImages.remove(it)
         needUpdateSource = true
       } else if (dragAnnotationMap.remove(it.id) != null) {
+        styleImages.remove(it)
         needUpdateDragSource = true
       }
     }
@@ -612,6 +619,7 @@ internal constructor(
       dragAnnotationMap.clear()
       updateDragSource()
     }
+    styleImages.clear()
   }
 
   private fun updateDragSource() {
@@ -645,26 +653,15 @@ internal constructor(
   // Add a bitmap to the style.
   internal fun addStyleImage(imageId: String, bitmap: Bitmap) {
     delegateProvider.mapStyleManagerDelegate.addImage(image(imageId, bitmap))
-  }
-
-  private fun removeIconsFromStyle(style: MapboxStyleManager, annotations: Collection<T>) {
-    annotations.forEach { removeIconFromStyle(style, it) }
-  }
-
-  private fun removeIconFromStyle(style: MapboxStyleManager, annotation: T) {
-    val symbol = annotation as? PointAnnotation ?: return
-    val imageId = symbol.iconImage ?: return
-    if (!imageId.startsWith(PointAnnotation.ICON_DEFAULT_NAME_PREFIX)) return
-    if (!style.hasStyleImage(imageId)) return
-    style.removeStyleImage(imageId)
+    styleImages.put(imageId)
   }
 
   // Add icons to style from PointAnnotation.
   private fun addIconToStyle(style: MapboxStyleManager, annotations: Collection<T>) {
     // Add icon image bitmap from point annotation
     annotations.forEach { annotation ->
       (annotation as? PointAnnotation)?.let { symbol ->
-        symbol.iconImage?.let { imageId ->
+        symbol.iconImageInternal?.let { imageId ->
           if (imageId.startsWith(PointAnnotation.ICON_DEFAULT_NAME_PREFIX)) {
             /*
              * Basically if an image with the `imageId` already exists we don't add it again. The
@@ -774,7 +771,7 @@ internal constructor(
         style.removeStyleSource(it)
       }
     }
-    removeIconsFromStyle(style, annotations)
+    styleImages.clear()
 
     unregisterInteractions()
     annotationMap.clear()
@@ -1001,6 +998,46 @@ internal constructor(
     return properties.optBoolean("cluster", false)
   }
 
+  private inner class StyleImages() {
+
+    private val images: MutableMap<String, Int> = mutableMapOf()
+    private val style get() = delegateProvider.mapStyleManagerDelegate
+
+    fun put(annotation: T) {
+      val imageId = (annotation as? PointAnnotation)?.iconImageInternal ?: return
+      if (!imageId.startsWith(PointAnnotation.ICON_DEFAULT_NAME_PREFIX)) return
+      put(imageId)
+    }
+
+    fun put(imageId: String) {
+      images[imageId] = (images[imageId] ?: 0) + 1
+    }
+
+    fun remove(annotation: T) {
+      val imageId = (annotation as? PointAnnotation)?.iconImageInternal ?: return
+      if (!imageId.startsWith(PointAnnotation.ICON_DEFAULT_NAME_PREFIX)) return
+      val newCount = (images[imageId] ?: return) - 1
+      if (newCount <= 0) {
+        images.remove(imageId)
+        if (style.hasStyleImage(imageId)) {
+          style.removeStyleImage(imageId)
+        }
+      } else {
+        images[imageId] = newCount
+      }
+    }
+
+    fun clear() {
+      val style = style
+      images.keys.forEach { imageId ->
+        if (style.hasStyleImage(imageId)) {
+          style.removeStyleImage(imageId)
+        }
+      }
+      images.clear()
+    }
+  }
+
   /**
    * Static variables and methods.
    */