HERE SDK Android — multiple maps on same screen show black areas or rendering conflicts (SurfaceView overlap fix)

Summary

When displaying multiple HERE map views (fragments) on the same Android screen, maps may render as black rectangles, flicker, or overlap incorrectly. This is caused by Android's SurfaceView compositing limitation. The fix is to switch to texture render mode by setting MapRenderMode.TEXTURE in MapViewOptions.

Answer

To display multiple HERE maps on the same Android screen without rendering conflicts, initialize each MapView with MapViewOptions and set renderMode to MapRenderMode.TEXTURE. This replaces the default SurfaceView rendering with TextureView, which supports proper compositing of overlapping views. This applies to HERE SDK for Android (Navigate/Explore) version 4.x.

Symptoms

You may need this article if you experience any of the following:

Multiple map fragments on the same screen display as black rectangles or blank areas
Maps flicker or show z-order rendering artifacts when overlapping
One map renders correctly but the second map appears behind other UI elements
SurfaceView overlap causes visual glitches — maps "punch through" other views
Logcat shows rendering warnings related to multiple SurfaceView instances
Map views work individually but break when placed side-by-side or stacked in the same Activity/Fragment
You are using ViewPager, split-screen layouts, or picture-in-picture with multiple maps

Root Cause

By default, the HERE SDK renders maps using Android's SurfaceView. The SurfaceView is composited in a separate hardware layer below the app's view hierarchy. Android does not support overlapping or stacking multiple SurfaceView instances reliably — this is a known Android platform limitation, not a HERE SDK bug.

When two or more SurfaceView-based maps are placed on the same screen:

The Android compositor cannot determine correct z-ordering
One or both views may render as black rectangles
Flickering occurs as the compositor alternates between surfaces

The solution is to use TextureView rendering (texture mode), which composites within the normal view hierarchy and supports overlapping, animations, and transparency.

Solution

Option 1 — Programmatic (all versions 4.x)

Initialize MapView with MapViewOptions and set the render mode to TEXTURE:

MapViewOptions mapViewOptions = new MapViewOptions();

mapViewOptions.renderMode = MapRenderMode.TEXTURE;

MapView mapView = new MapView(context, mapViewOptions);

Apply this to every MapView instance on the screen — not just one.

Option 2 — XML Layout (version 4.14.5 or later)

Set the render mode directly in your XML layout file:

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"

xmlns:mapViewOptions="http://schemas.android.com/apk/res-auto" android:orientation="vertical" android:layout_width="match_parent" android:layout_height="match_parent">

<com.here.sdk.mapview.MapView android:id="@+id/map_view_1" android:layout_width="match_parent" android:layout_height="0dp" android:layout_weight="1" android:tag="@string/tag_harp_map_view" mapViewOptions:render_mode="texture"/>

<com.here.sdk.mapview.MapView android:id="@+id/map_view_2" android:layout_width="match_parent" android:layout_height="0dp" android:layout_weight="1" android:tag="@string/tag_harp_map_view" mapViewOptions:render_mode="texture"/>

LinearLayout>

Note the mapViewOptions:render_mode="texture" attribute on each MapView.

Important Notes

TextureView (texture mode) has a slight performance overhead compared to SurfaceView — this is negligible for most use cases but may be noticeable on low-end devices with complex map scenes
Both map views must use texture mode — mixing SurfaceView and TextureView maps on the same screen will still cause conflicts
This approach works with ViewPager, FragmentTransaction, split-screen layouts, and any scenario involving multiple simultaneous map instances

Troubleshooting

| Scenario | Likely Cause | Fix |
| --- | --- | --- |
| Black rectangle on one map | Only one MapView set to TEXTURE mode | Set renderMode = TEXTURE on ALL MapView instances |
| Flickering between maps | Mixed render modes (one SURFACE, one TEXTURE) | Ensure all maps use TEXTURE mode |
| XML render_mode attribute not recognized | SDK version below 4.14.5 | Upgrade SDK or use programmatic approach |
| Performance drop with texture mode | Expected on low-end devices | Reduce map scene complexity or limit simultaneous map instances |

Applies To

HERE SDK for Android — Navigate Edition 4.x
HERE SDK for Android — Explore Edition 4.x
Android API level 21+ (Lollipop and above)
XML layout support: version 4.14.5 or later

Related Information

MapViewOptions API Reference:
https://www.here.com/docs/bundle/sdk-for-android-navigate-api-reference/page/com/here/sdk/mapview/MapViewOptions.html#renderMode
* HERE SDK for Android Developer Guide:
https://www.here.com/docs/bundle/sdk-for-android-navigate-developer-guide/page/README.html

Keywords

multiple maps same screen Android, black rectangle map view, SurfaceView overlap, map flickering Android, two maps one activity, MapView fragments overlapping, TextureView HERE SDK, render mode texture, MapRenderMode TEXTURE, MapViewOptions, split screen map, ViewPager map, multiple map fragments, SurfaceView conflict, map not rendering, black map Android, HERE SDK 4.x Android, overlapping map views