mapsforge · devemux86 · Oct 23, 2025 · Oct 23, 2025
diff --git a/docs/Changelog.md b/docs/Changelog.md
@@ -2,6 +2,7 @@
 
 ## Next version
 
+- Render themes: `map-background-outside` [#1262](https://github.com/mapsforge/vtm/pull/1262)
 - `ThemeCallback.getColor` method [#1251](https://github.com/mapsforge/vtm/pull/1251)
 - Map theme improvements
 - Minor improvements and bug fixes

diff --git a/docs/Rendertheme.md b/docs/Rendertheme.md
@@ -76,13 +76,14 @@ At the moment, the following rendering instructions are available:
 
 The following header elements can be used:
  - `map-background`: a color value to set the color of a blank tile. This should not be used to set the color of the sea or land. Default is `#FFFFFF`.
+ - `map-background-outside`: a color value to set the color of the background of a map outside the map area. Effectively everything outside the map area will be overwritten by this color. For transparent layers, the color value will be ignored, but the outside area will be erased to transparent.
  - `base-stroke-width`: set the basic width of strokes. Default is `1`.
  - `base-text-scale`: set the overall text scale. Default is `1`.
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <rendertheme xmlns="http://opensciencemap.org/rendertheme" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xsi:schemaLocation="http://opensciencemap.org/rendertheme https://raw.githubusercontent.com/mapsforge/vtm/master/resources/rendertheme.xsd" version="1" map-background="#FFFCFA">
+    xsi:schemaLocation="http://opensciencemap.org/rendertheme https://raw.githubusercontent.com/mapsforge/vtm/master/resources/rendertheme.xsd" version="1" map-background="#FFFCFA" map-background-outside="#DDDDDD">
     …
 </rendertheme>
 ```

diff --git a/resources/rendertheme.xsd b/resources/rendertheme.xsd
@@ -354,6 +354,8 @@
         </xs:sequence>
         <xs:attribute name="version" type="xs:positiveInteger" use="required" />
         <xs:attribute name="map-background" default="#ffffff" type="tns:color" use="optional" />
+        <xs:attribute name="map-background-outside" default="#ffffff" type="tns:color"
+            use="optional" />
         <xs:attribute name="base-stroke-width" default="1" type="tns:nonNegativeFloat"
             use="optional" />
         <xs:attribute name="base-text-scale" default="1" type="tns:nonNegativeFloat"

diff --git a/vtm-playground/src/org/oscim/test/DebugTheme.java b/vtm-playground/src/org/oscim/test/DebugTheme.java
@@ -38,6 +38,11 @@ public int getMapBackground() {
         return 0;
     }
 
+    @Override
+    public int getMapBackgroundOutside() {
+        return 0;
+    }
+
     @Override
     public boolean isMapsforgeTheme() {
         return false;

diff --git a/vtm-playground/src/org/oscim/test/ThemeBuilder.java b/vtm-playground/src/org/oscim/test/ThemeBuilder.java
@@ -22,6 +22,7 @@ public class ThemeBuilder {
 
     protected int mLevels = 0;
     protected int mMapBackground = 0xffffffff;
+    protected int mMapBackgroundOutside = 0xffffffff;
     protected float mBaseTextSize = 1;
 
     protected RuleBuilder mCurrentRule;
@@ -33,7 +34,7 @@ public RenderTheme build() {
         for (int i = 0, n = rules.length; i < n; i++)
             rules[i] = mRulesList.get(i).onComplete(layer);
 
-        RenderTheme theme = new RenderTheme(mMapBackground, mBaseTextSize, rules, mLevels);
+        RenderTheme theme = new RenderTheme(mMapBackground, mMapBackgroundOutside, mBaseTextSize, rules, mLevels);
 
         mRulesList.clear();
         mRuleStack.clear();

diff --git a/vtm-themes/resources/assets/vtm/biker.xml b/vtm-themes/resources/assets/vtm/biker.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <rendertheme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" map-background="#e8eae1"
-    version="1" xmlns="http://opensciencemap.org/rendertheme"
+    map-background-outside="#DDDDDD" version="1" xmlns="http://opensciencemap.org/rendertheme"
     xsi:schemaLocation="http://opensciencemap.org/rendertheme https://raw.githubusercontent.com/mapsforge/vtm/master/resources/rendertheme.xsd">
 
     <!-- This is the 2nd generation OpenGL/VTM "Biker" theme -->

diff --git a/vtm-themes/resources/assets/vtm/dark.xml b/vtm-themes/resources/assets/vtm/dark.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <rendertheme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" map-background="#262626"
-    version="1" xmlns="http://opensciencemap.org/rendertheme"
+    map-background-outside="#222222" version="1" xmlns="http://opensciencemap.org/rendertheme"
     xsi:schemaLocation="http://opensciencemap.org/rendertheme https://raw.githubusercontent.com/mapsforge/vtm/master/resources/rendertheme.xsd">
 
     <!-- This is the 2nd generation OpenGL/VTM "dark" theme based on the Biker map theme -->

diff --git a/vtm-themes/resources/assets/vtm/default.xml b/vtm-themes/resources/assets/vtm/default.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <rendertheme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" map-background="#fffcfa"
-    version="1" xmlns="http://opensciencemap.org/rendertheme"
+    map-background-outside="#DDDDDD" version="1" xmlns="http://opensciencemap.org/rendertheme"
     xsi:schemaLocation="http://opensciencemap.org/rendertheme https://raw.githubusercontent.com/mapsforge/vtm/master/resources/rendertheme.xsd">
 
     <!--###### TRANSFORM tags ######-->

diff --git a/vtm-themes/resources/assets/vtm/indigo.xml b/vtm-themes/resources/assets/vtm/indigo.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <rendertheme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" map-background="#0d1a26"
-    version="1" xmlns="http://opensciencemap.org/rendertheme"
+    map-background-outside="#222222" version="1" xmlns="http://opensciencemap.org/rendertheme"
     xsi:schemaLocation="http://opensciencemap.org/rendertheme https://raw.githubusercontent.com/mapsforge/vtm/master/resources/rendertheme.xsd">
 
     <!-- This is the OpenGL/VTM "Indigo" theme based on the Biker map theme -->

diff --git a/vtm-themes/resources/assets/vtm/mapzen.xml b/vtm-themes/resources/assets/vtm/mapzen.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <rendertheme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" map-background="#fffcfa"
-    version="1" xmlns="http://opensciencemap.org/rendertheme"
+    map-background-outside="#DDDDDD" version="1" xmlns="http://opensciencemap.org/rendertheme"
     xsi:schemaLocation="http://opensciencemap.org/rendertheme https://raw.githubusercontent.com/mapsforge/vtm/master/resources/rendertheme.xsd">
 
     <!--<tag-transform k="kind" v="building" k-lib="building" v-lib="yes" />-->

diff --git a/vtm-themes/resources/assets/vtm/motorider.xml b/vtm-themes/resources/assets/vtm/motorider.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <rendertheme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" map-background="#FFFFFF"
-    version="1" xmlns="http://opensciencemap.org/rendertheme"
+    map-background-outside="#DDDDDD" version="1" xmlns="http://opensciencemap.org/rendertheme"
     xsi:schemaLocation="http://opensciencemap.org/rendertheme https://raw.githubusercontent.com/mapsforge/vtm/master/resources/rendertheme.xsd">
 
     <!-- This is the 2nd generation OpenGL/VTM "light" theme based on the Biker map theme-->

diff --git a/vtm-themes/resources/assets/vtm/newtron.xml b/vtm-themes/resources/assets/vtm/newtron.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <rendertheme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" map-background="#000000"
-    version="1" xmlns="http://opensciencemap.org/rendertheme"
+    map-background-outside="#222222" version="1" xmlns="http://opensciencemap.org/rendertheme"
     xsi:schemaLocation="http://opensciencemap.org/rendertheme https://raw.githubusercontent.com/mapsforge/vtm/master/resources/rendertheme.xsd">
 
     <!--###### TEXT styles ######-->

diff --git a/vtm-themes/resources/assets/vtm/openmaptiles.xml b/vtm-themes/resources/assets/vtm/openmaptiles.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<rendertheme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" base-stroke-width="0.7"
-    map-background="#d8dbcb" version="1" xmlns="http://opensciencemap.org/rendertheme"
+<rendertheme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" map-background="#d8dbcb"
+    map-background-outside="#DDDDDD" base-stroke-width="0.7" version="1" xmlns="http://opensciencemap.org/rendertheme"
     xsi:schemaLocation="http://opensciencemap.org/rendertheme https://raw.githubusercontent.com/mapsforge/vtm/master/resources/rendertheme.xsd">
 
     <tag-transform k="render_height" k-lib="height" />

diff --git a/vtm-themes/resources/assets/vtm/osmarender.xml b/vtm-themes/resources/assets/vtm/osmarender.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <rendertheme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" map-background="#fffcfa"
-    version="1" xmlns="http://opensciencemap.org/rendertheme"
+    map-background-outside="#DDDDDD" version="1" xmlns="http://opensciencemap.org/rendertheme"
     xsi:schemaLocation="http://opensciencemap.org/rendertheme https://raw.githubusercontent.com/mapsforge/vtm/master/resources/rendertheme.xsd">
 
     <!--###### TEXT styles ######-->

diff --git a/vtm-themes/resources/assets/vtm/tronrender.xml b/vtm-themes/resources/assets/vtm/tronrender.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <rendertheme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" map-background="#050508"
-    version="1" xmlns="http://opensciencemap.org/rendertheme"
+    map-background-outside="#222222" version="1" xmlns="http://opensciencemap.org/rendertheme"
     xsi:schemaLocation="http://opensciencemap.org/rendertheme https://raw.githubusercontent.com/mapsforge/vtm/master/resources/rendertheme.xsd">
 
     <!--###### TEXT styles ######-->

diff --git a/vtm/src/org/oscim/map/Map.java b/vtm/src/org/oscim/map/Map.java
@@ -222,7 +222,7 @@ public void setTheme(IRenderTheme theme, boolean allLayers) {
             throw new IllegalStateException();
         }
 
-        MapRenderer.setBackgroundColor(theme.getMapBackground());
+        MapRenderer.setBackgroundColor(theme.getMapBackgroundOutside());
 
         clearMap();
     }

diff --git a/vtm/src/org/oscim/theme/AtlasRenderTheme.java b/vtm/src/org/oscim/theme/AtlasRenderTheme.java
@@ -27,14 +27,14 @@ public class AtlasRenderTheme extends RenderTheme {
     private final Map<Object, TextureRegion> textureRegionMap;
     private final List<TextureAtlas> atlasList;
 
-    public AtlasRenderTheme(int mapBackground, float baseTextSize, Rule[] rules, int levels,
+    public AtlasRenderTheme(int mapBackground, int mapBackgroundOutside, float baseTextSize, Rule[] rules, int levels,
                             Map<Object, TextureRegion> textureRegionMap, List<TextureAtlas> atlasList) {
-        this(mapBackground, baseTextSize, rules, levels, false, textureRegionMap, atlasList);
+        this(mapBackground, mapBackgroundOutside, baseTextSize, rules, levels, false, textureRegionMap, atlasList);
     }
 
-    public AtlasRenderTheme(int mapBackground, float baseTextSize, Rule[] rules, int levels, boolean mapsforgeTheme,
+    public AtlasRenderTheme(int mapBackground, int mapBackgroundOutside, float baseTextSize, Rule[] rules, int levels, boolean mapsforgeTheme,
                             Map<Object, TextureRegion> textureRegionMap, List<TextureAtlas> atlasList) {
-        super(mapBackground, baseTextSize, rules, levels, mapsforgeTheme);
+        super(mapBackground, mapBackgroundOutside, baseTextSize, rules, levels, mapsforgeTheme);
         this.textureRegionMap = textureRegionMap;
         this.atlasList = atlasList;
     }

diff --git a/vtm/src/org/oscim/theme/IRenderTheme.java b/vtm/src/org/oscim/theme/IRenderTheme.java
@@ -51,6 +51,11 @@ public interface IRenderTheme {
      */
     int getMapBackground();
 
+    /**
+     * @return the map background outside color of this RenderTheme.
+     */
+    int getMapBackgroundOutside();
+
     /**
      * Is Mapsforge or VTM theme.
      */

diff --git a/vtm/src/org/oscim/theme/RenderTheme.java b/vtm/src/org/oscim/theme/RenderTheme.java
@@ -42,6 +42,7 @@ public class RenderTheme implements IRenderTheme {
 
     private final float mBaseTextSize;
     private final int mMapBackground;
+    private final int mMapBackgroundOutside;
 
     private final int mLevels;
     private final Rule[] mRules;
@@ -81,25 +82,26 @@ static class RenderStyleItem {
 
     private final RenderStyleCache[] mStyleCache;
 
-    public RenderTheme(int mapBackground, float baseTextSize, Rule[] rules, int levels) {
-        this(mapBackground, baseTextSize, rules, levels, false);
+    public RenderTheme(int mapBackground, int mapBackgroundOutside, float baseTextSize, Rule[] rules, int levels) {
+        this(mapBackground, mapBackgroundOutside, baseTextSize, rules, levels, false);
     }
 
-    public RenderTheme(int mapBackground, float baseTextSize, Rule[] rules, int levels,
+    public RenderTheme(int mapBackground, int mapBackgroundOutside, float baseTextSize, Rule[] rules, int levels,
                        Map<String, String> transformKeyMap, Map<Tag, Tag> transformTagMap) {
-        this(mapBackground, baseTextSize, rules, levels, transformKeyMap, transformTagMap, false);
+        this(mapBackground, mapBackgroundOutside, baseTextSize, rules, levels, transformKeyMap, transformTagMap, false);
     }
 
-    public RenderTheme(int mapBackground, float baseTextSize, Rule[] rules, int levels, boolean mapsforgeTheme) {
-        this(mapBackground, baseTextSize, rules, levels, null, null, mapsforgeTheme);
+    public RenderTheme(int mapBackground, int mapBackgroundOutside, float baseTextSize, Rule[] rules, int levels, boolean mapsforgeTheme) {
+        this(mapBackground, mapBackgroundOutside, baseTextSize, rules, levels, null, null, mapsforgeTheme);
     }
 
-    public RenderTheme(int mapBackground, float baseTextSize, Rule[] rules, int levels,
+    public RenderTheme(int mapBackground, int mapBackgroundOutside, float baseTextSize, Rule[] rules, int levels,
                        Map<String, String> transformKeyMap, Map<Tag, Tag> transformTagMap, boolean mapsforgeTheme) {
         if (rules == null)
             throw new IllegalArgumentException("rules missing");
 
         mMapBackground = mapBackground;
+        mMapBackgroundOutside = mapBackgroundOutside;
         mBaseTextSize = baseTextSize;
         mLevels = levels;
         mRules = rules;
@@ -136,6 +138,11 @@ public int getMapBackground() {
         return mMapBackground;
     }
 
+    @Override
+    public int getMapBackgroundOutside() {
+        return mMapBackgroundOutside;
+    }
+
     Rule[] getRules() {
         return mRules;
     }

diff --git a/vtm/src/org/oscim/theme/XmlAtlasThemeBuilder.java b/vtm/src/org/oscim/theme/XmlAtlasThemeBuilder.java
@@ -117,7 +117,7 @@ public XmlAtlasThemeBuilder(ThemeFile theme, XmlPullParser pullParser, ThemeCall
 
     @Override
     RenderTheme createTheme(Rule[] rules) {
-        return new AtlasRenderTheme(mMapBackground, mTextScale, rules, mLevels, mTheme.isMapsforgeTheme(), regionMap, atlasList);
+        return new AtlasRenderTheme(mMapBackground, mMapBackgroundOutside, mTextScale, rules, mLevels, mTheme.isMapsforgeTheme(), regionMap, atlasList);
     }
 
     @Override

diff --git a/vtm/src/org/oscim/theme/XmlThemeBuilder.java b/vtm/src/org/oscim/theme/XmlThemeBuilder.java
@@ -166,6 +166,7 @@ private static void logUnknownAttribute(String element, String name, String valu
 
     int mLevels = 0;
     int mMapBackground = 0xffffffff;
+    int mMapBackgroundOutside = 0xffffffff;
     private float mStrokeScale = 1;
     float mTextScale = 1;
 
@@ -235,7 +236,7 @@ public void endDocument() {
     }
 
     RenderTheme createTheme(Rule[] rules) {
-        return new RenderTheme(mMapBackground, mTextScale, rules, mLevels, mTransformKeyMap, mTransformTagMap, mTheme.isMapsforgeTheme());
+        return new RenderTheme(mMapBackground, mMapBackgroundOutside, mTextScale, rules, mLevels, mTransformKeyMap, mTransformTagMap, mTheme.isMapsforgeTheme());
     }
 
     public void endElement() {
@@ -976,6 +977,7 @@ private void checkState(String elementName, Element element) throws XmlPullParse
     private void createRenderTheme(String elementName) {
         Integer version = null;
         int mapBackground = Color.WHITE;
+        int mapBackgroundOutside = Color.WHITE;
         float baseStrokeWidth = 1;
         float baseTextScale = 1;
 
@@ -1005,10 +1007,12 @@ else if ("map-background".equals(name)) {
             else if ("base-text-scale".equals(name) || "base-text-size".equals(name))
                 baseTextScale = Float.parseFloat(value);
 
-            else if ("map-background-outside".equals(name))
-                ; // no-op
+            else if ("map-background-outside".equals(name)) {
+                mapBackgroundOutside = Color.parseColor(value);
+                if (mThemeCallback != null)
+                    mapBackgroundOutside = mThemeCallback.getColor(null, mapBackgroundOutside);
 
-            else
+            } else
                 logUnknownAttribute(elementName, name, value, i);
 
         }
@@ -1023,6 +1027,7 @@ else if ("map-background-outside".equals(name))
         validateNonNegative("base-text-scale", baseTextScale);
 
         mMapBackground = mapBackground;
+        mMapBackgroundOutside = mapBackgroundOutside;
         mStrokeScale = baseStrokeWidth;
         mTextScale = baseTextScale;
     }