Added feature to mask the primary route line in order to give the appearance the active leg is above the inactive legs for multi-leg routes.

Author: Seth Bourget

CHANGELOG.md

@@ -10,6 +10,7 @@ Mapbox welcomes participation and contributions from everyone.
 - Fixed approaches list update in `RouteOptionsUpdater`(uses for reroute). It was putting to the origin approach corresponding approach from legacy approach list. [#6540](https://github.com/mapbox/mapbox-navigation-android/pull/6540)
 - Updated the `MapboxRestAreaApi` logic to load a SAPA map only if the upcoming rest stop is at the current step of the route leg. [#6695](https://github.com/mapbox/mapbox-navigation-android/pull/6695)
 - Fixed an issue where `MapboxRerouteController` could deliver a delayed interruption state notifications. Now, the interruption state is always delivered synchronously, as soon as it's available. [#6718](https://github.com/mapbox/mapbox-navigation-android/pull/6718)
+- Modified the route line implementation so that for multi-leg routes the active route appears above inactive route legs. [#6742](https://github.com/mapbox/mapbox-navigation-android/pull/6742)
 
 ## Mapbox Navigation SDK 2.9.5 - 13 December, 2022
 ### Changelog

libnavui-maps/src/main/java/com/mapbox/navigation/ui/maps/internal/route/line/MapboxRouteLineUtils.kt

@@ -93,6 +93,7 @@ internal object MapboxRouteLineUtils {
     val layerGroup2SourceKey = RouteLineSourceKey(RouteLayerConstants.LAYER_GROUP_2_SOURCE_ID)
     val layerGroup3SourceKey = RouteLineSourceKey(RouteLayerConstants.LAYER_GROUP_3_SOURCE_ID)
 
+    // ordering is important
     val layerGroup1SourceLayerIds = setOf(
         RouteLayerConstants.LAYER_GROUP_1_TRAIL_CASING,
         RouteLayerConstants.LAYER_GROUP_1_TRAIL,
@@ -101,6 +102,8 @@ internal object MapboxRouteLineUtils {
         RouteLayerConstants.LAYER_GROUP_1_TRAFFIC,
         RouteLayerConstants.LAYER_GROUP_1_RESTRICTED
     )
+
+    // ordering is important
     val layerGroup2SourceLayerIds = setOf(
         RouteLayerConstants.LAYER_GROUP_2_TRAIL_CASING,
         RouteLayerConstants.LAYER_GROUP_2_TRAIL,
@@ -109,6 +112,8 @@ internal object MapboxRouteLineUtils {
         RouteLayerConstants.LAYER_GROUP_2_TRAFFIC,
         RouteLayerConstants.LAYER_GROUP_2_RESTRICTED
     )
+
+    // ordering is important
     val layerGroup3SourceLayerIds = setOf(
         RouteLayerConstants.LAYER_GROUP_3_TRAIL_CASING,
         RouteLayerConstants.LAYER_GROUP_3_TRAIL,
@@ -118,6 +123,15 @@ internal object MapboxRouteLineUtils {
         RouteLayerConstants.LAYER_GROUP_3_RESTRICTED
     )
 
+    // ordering is important
+    val maskingLayerIds = setOf(
+        RouteLayerConstants.MASKING_LAYER_TRAIL_CASING,
+        RouteLayerConstants.MASKING_LAYER_TRAIL,
+        RouteLayerConstants.MASKING_LAYER_CASING,
+        RouteLayerConstants.MASKING_LAYER_MAIN,
+        RouteLayerConstants.MASKING_LAYER_TRAFFIC
+    )
+
     val sourceLayerMap = mapOf<RouteLineSourceKey, Set<String>>(
         Pair(layerGroup1SourceKey, layerGroup1SourceLayerIds),
         Pair(layerGroup2SourceKey, layerGroup2SourceLayerIds),
@@ -524,8 +538,7 @@ internal object MapboxRouteLineUtils {
 
     /**
      * Extracts data from the [DirectionsRoute] and removes items that are deemed duplicates based
-     * on factors such as traffic congestion and/or road class. The results are cached for
-     * performance reasons.
+     * on factors such as traffic congestion and/or road class.
      */
     internal val extractRouteDataWithTrafficAndRoadClassDeDuped: (
         route: NavigationRoute,
@@ -1353,6 +1366,68 @@ internal object MapboxRouteLineUtils {
                     style.addPersistentLayer(this, LayerPosition(null, belowLayerIdToUse, null))
                 }
         }
+
+        if (!style.styleLayerExists(RouteLayerConstants.MASKING_LAYER_TRAIL_CASING)) {
+            LineLayer(
+                RouteLayerConstants.MASKING_LAYER_TRAIL_CASING,
+                RouteLayerConstants.LAYER_GROUP_1_SOURCE_ID
+            )
+                .lineCap(LineCap.ROUND)
+                .lineJoin(LineJoin.ROUND)
+                .lineWidth(options.resourceProvider.routeCasingLineScaleExpression)
+                .lineColor(Color.GRAY).apply {
+                    style.addPersistentLayer(this, LayerPosition(null, belowLayerIdToUse, null))
+                }
+        }
+        if (!style.styleLayerExists(RouteLayerConstants.MASKING_LAYER_TRAIL)) {
+            LineLayer(
+                RouteLayerConstants.MASKING_LAYER_TRAIL,
+                RouteLayerConstants.LAYER_GROUP_1_SOURCE_ID
+            )
+                .lineCap(LineCap.ROUND)
+                .lineJoin(LineJoin.ROUND)
+                .lineWidth(options.resourceProvider.routeLineScaleExpression)
+                .lineColor(Color.GRAY).apply {
+                    style.addPersistentLayer(this, LayerPosition(null, belowLayerIdToUse, null))
+                }
+        }
+        if (!style.styleLayerExists(RouteLayerConstants.MASKING_LAYER_CASING)) {
+            LineLayer(
+                RouteLayerConstants.MASKING_LAYER_CASING,
+                RouteLayerConstants.LAYER_GROUP_1_SOURCE_ID
+            )
+                .lineCap(LineCap.ROUND)
+                .lineJoin(LineJoin.ROUND)
+                .lineWidth(options.resourceProvider.routeCasingLineScaleExpression)
+                .lineColor(Color.GRAY).apply {
+                    style.addPersistentLayer(this, LayerPosition(null, belowLayerIdToUse, null))
+                }
+        }
+        if (!style.styleLayerExists(RouteLayerConstants.MASKING_LAYER_MAIN)) {
+            LineLayer(
+                RouteLayerConstants.MASKING_LAYER_MAIN,
+                RouteLayerConstants.LAYER_GROUP_1_SOURCE_ID
+            )
+                .lineCap(LineCap.ROUND)
+                .lineJoin(LineJoin.ROUND)
+                .lineWidth(options.resourceProvider.routeLineScaleExpression)
+                .lineColor(Color.GRAY).apply {
+                    style.addPersistentLayer(this, LayerPosition(null, belowLayerIdToUse, null))
+                }
+        }
+        if (!style.styleLayerExists(RouteLayerConstants.MASKING_LAYER_TRAFFIC)) {
+            LineLayer(
+                RouteLayerConstants.MASKING_LAYER_TRAFFIC,
+                RouteLayerConstants.LAYER_GROUP_1_SOURCE_ID
+            )
+                .lineCap(LineCap.ROUND)
+                .lineJoin(LineJoin.ROUND)
+                .lineWidth(options.resourceProvider.routeTrafficLineScaleExpression)
+                .lineColor(Color.GRAY).apply {
+                    style.addPersistentLayer(this, LayerPosition(null, belowLayerIdToUse, null))
+                }
+        }
+
         if (options.displayRestrictedRoadSections) {
             if (!style.styleLayerExists(RouteLayerConstants.LAYER_GROUP_1_RESTRICTED)) {
                 LineLayer(
@@ -1413,6 +1488,11 @@ internal object MapboxRouteLineUtils {
             style.styleLayerExists(RouteLayerConstants.LAYER_GROUP_3_CASING) &&
             style.styleLayerExists(RouteLayerConstants.LAYER_GROUP_3_MAIN) &&
             style.styleLayerExists(RouteLayerConstants.LAYER_GROUP_3_TRAFFIC) &&
+            style.styleLayerExists(RouteLayerConstants.MASKING_LAYER_TRAIL_CASING) &&
+            style.styleLayerExists(RouteLayerConstants.MASKING_LAYER_TRAIL) &&
+            style.styleLayerExists(RouteLayerConstants.MASKING_LAYER_CASING) &&
+            style.styleLayerExists(RouteLayerConstants.MASKING_LAYER_MAIN) &&
+            style.styleLayerExists(RouteLayerConstants.MASKING_LAYER_TRAFFIC) &&
             if (options.displayRestrictedRoadSections) {
                 style.styleLayerExists(RouteLayerConstants.LAYER_GROUP_1_RESTRICTED) &&
                     style.styleLayerExists(RouteLayerConstants.LAYER_GROUP_2_RESTRICTED) &&

libnavui-maps/src/main/java/com/mapbox/navigation/ui/maps/route/RouteLayerConstants.kt

@@ -206,4 +206,24 @@ object RouteLayerConstants {
     internal const val LAYER_GROUP_3_MAIN = "mapbox-layerGroup-3-main"
     internal const val LAYER_GROUP_3_TRAFFIC = "mapbox-layerGroup-3-traffic"
     internal const val LAYER_GROUP_3_RESTRICTED = "mapbox-layerGroup-3-restricted"
+
+    /*
+    When a line on the map overlaps itself it appears as though the later part of the line
+    is on top of the earlier part of the line. For multi-leg routes this gives the appearance
+    the inactive leg(s) appearing on top of the active leg.  Customer feedback indicated this
+    was unsatisfactory. The masking layers were created to address this issue and give the
+    opposite of the default appearance. The end result is the active route leg appears
+    above inactive leg(s) when a route overlaps itself.
+
+    The masking layers share the same source as the primary route line. They are placed above
+    the primary route line layers except for the restricted line which appears above all other
+    primary route layers.  The implementation will set the inactive route legs to transparent
+    so the primary route line layers are visible.  The active leg section of the masking layers
+    are opaque thus masking the the primary route line layers beneath.
+     */
+    internal const val MASKING_LAYER_TRAIL_CASING = "mapbox-masking-layer-trailCasing"
+    internal const val MASKING_LAYER_TRAIL = "mapbox-masking-layer-trail"
+    internal const val MASKING_LAYER_CASING = "mapbox-masking-layer-casing"
+    internal const val MASKING_LAYER_MAIN = "mapbox-masking-layer-main"
+    internal const val MASKING_LAYER_TRAFFIC = "mapbox-masking-layer-traffic"
 }