External Surfaces
With the MapKit SDK, you can render a map onto multiple Android Surfaces. Rendering one map onto multiple Surfaces instead of rendering multiple MapViews decreases the device's memory consumption and helps reduce the load on the CPU and GPU.
Warning
Rendering to a Surface allows you to duplicate a section of the map instead of drawing a separate map on each Surface. This means that the map displayed on a Surface matches the styles, tiles, and other characteristics of MapWindow. At the same time, it's impossible to control the map via the Surface.
Wrapper over Surface
In the MapKit SDK, Android Surface is passed wrapped in a Surface.
Such a Surface is created using SurfaceFactory.from(android.view.Surface).
val androidSurface = layout.surfaceView.holder.surface
val surface = SurfaceFactory.from(androidSurface)
Working with a Surface
Adding a Surface to MapView
To add a Surface to MapView, use the method MapWindow.addSurface(Surface). To remove the Surface, use MapWindow.removeSurface(Surface).
Adding a Surface to OffscreenMapWindow
Sometimes, you don't need to display a MapView to display a map on a Surface, or displaying on all Surfaces may require a MapView that's too large to fit on any screen. For such cases, use OffscreenMapWindow.
Like MapView, OffscreenMapWindow contains a MapWindow, which makes it possible for you to work with a Surface. However, OffscreenMapWindow is not a View element, which is why it's rendered only on the Surface.
To create an OffscreenMapWindow, use the method MapKit.createOffscreenMapWindow.
Map placement on a Surface
To reposition the focus point of the map within a Surface, use the method Surface.setAnchorPoint(android.graphics.PointF). The area that will be displayed is taken as the minimum of the size of the map and the size of the Surface itself. By default, the anchor coincides with the map's focus point, so it's located in the center of the Surface.
The anchor is set within the range of [0, 1] for each axis and indicates the point on the Surface where the focus point of the map will be. The map's focus point will always be visible on the Surface, and the anchor range shifts so that the intersection of the Surface and the map never extends beyond the map. For example, an anchor equal to {0, 0} shifts the focus point of the map to the bottom-left corner of the Surface, while an anchor equal to {1, 1} shifts it to the top-right corner.
Example of how anchors work on two Surfaces:
The map itself:
Two equally sized Surfaces with anchors specified for them (anchors are assigned next to the corresponding Surface):
Note
Rendering on a Surface that's equal to or larger than the map itself will always draw the entire map and stretch it across the entire Surface. You can't change the position of the map on this Surface.