MGLMapSnapshotter

@interface MGLMapSnapshotter : NSObject <MGLStylable>

An MGLMapSnapshotter generates static raster images of the map. Each snapshot image depicts a portion of a map defined by an MGLMapSnapshotOptions object you provide. The snapshotter generates an MGLMapSnapshot object asynchronously, calling MGLMapSnapshotterDelegate methods if defined, then passing it into a completion handler once tiles and other resources needed for the snapshot are finished loading.

You can change the snapshotter’s options at any time and reuse the snapshotter for multiple distinct snapshots; however, the snapshotter can only generate one snapshot at a time. If you need to generate multiple snapshots concurrently, create multiple snapshotter objects.

For an interactive map, use the MGLMapView class. Both MGLMapSnapshotter and MGLMapView are compatible with offline packs managed by the MGLOfflineStorage class.

From a snapshot, you can obtain an image and convert geographic coordinates to the image’s coordinate space in order to superimpose markers and overlays. If you do not need offline map functionality, you can use the Snapshot class in MapboxStatic.swift to generate static map images with overlays.

Example

let camera = MGLMapCamera(lookingAtCenter: CLLocationCoordinate2D(latitude: 37.7184, longitude: -122.4365), altitude: 100, pitch: 20, heading: 0)

let options = MGLMapSnapshotOptions(styleURL: MGLStyle.satelliteStreetsStyleURL, camera: camera, size: CGSize(width: 320, height: 480))
options.zoomLevel = 10

let snapshotter = MGLMapSnapshotter(options: options)
snapshotter.start { (snapshot, error) in
if let error = error {
    fatalError(error.localizedDescription)
}

image = snapshot?.image
}

-initWithOptions:

Initializes and returns a map snapshotter object that produces snapshots according to the given options.

Declaration

Objective-C

- (nonnull instancetype)initWithOptions:
(nonnull MGLMapSnapshotOptions *)options;

Swift

init(options: MGLMapSnapshotOptions)

Parameters

options

The options to use when generating a map snapshot.

Return Value

An initialized map snapshotter.

-startWithCompletionHandler:

Starts the snapshot creation and executes the specified block with the result.

Declaration

Objective-C

- (void)startWithCompletionHandler:
(nonnull MGLMapSnapshotCompletionHandler)completionHandler;

Swift

func start(completionHandler: @escaping MGLMapSnapshotCompletionHandler)

Parameters

completionHandler

The block to call with a finished snapshot. The block is executed on the main queue.

-startWithQueue:completionHandler:

Starts the snapshot creation and executes the specified block with the result on the specified queue.

Declaration

Objective-C

- (void)startWithQueue:(nonnull dispatch_queue_t)queue
 completionHandler:
     (nonnull MGLMapSnapshotCompletionHandler)completionHandler;

Swift

func start(with queue: DispatchQueue, completionHandler: @escaping MGLMapSnapshotCompletionHandler)

Parameters

queue

The queue on which to call the block specified in the completionHandler parameter.

completionHandler

The block to call with a finished snapshot. The block is executed on the queue specified in the queue parameter.

-startWithOverlayHandler:completionHandler:

Starts the snapshot creation and executes the specified blocks with the result on the specified queue. Use this option if you want to add custom drawing on top of the resulting MGLMapSnapshot.

Declaration

Objective-C

- (void)startWithOverlayHandler:
        (nonnull MGLMapSnapshotOverlayHandler)overlayHandler
          completionHandler:
              (nonnull MGLMapSnapshotCompletionHandler)completionHandler;

Swift

func start(overlayHandler: @escaping MGLMapSnapshotOverlayHandler, completionHandler: @escaping MGLMapSnapshotCompletionHandler)

Parameters

overlayHandler

The block to call after the base map finishes drawing but before certain built-in overlays draw. The block can use Core Graphics to draw custom content directly over the base map. The block is executed on a background queue.

completionHandler

The block to call with a finished snapshot. The block is executed on the main queue.

-cancel

Cancels the snapshot creation request, if any.

Once you call this method, you cannot resume the snapshot. In order to obtain the snapshot, create a new MGLMapSnapshotter object.

Declaration

Objective-C

- (void)cancel;

Swift

func cancel()

options

The options to use when generating a map snapshot.

Declaration

Objective-C

@property (nonatomic, assign, unsafe_unretained, readwrite)
MGLMapSnapshotOptions *_Nonnull options;

Swift

var options: MGLMapSnapshotOptions { get set }

loading

Indicates whether a snapshot is currently being generated.

Declaration

Objective-C

@property (nonatomic, readonly, getter=isLoading) BOOL loading;

Swift

var isLoading: Bool { get }

delegate

The snapshotter’s delegate.

The delegate is responsible for responding to significant changes during the snapshotting process, such as the style loading. Implement a delegate to customize the style that is depicted by the snapshot.

You set the delegate after initializing the snapshotter but before receiving the snapshot, typically before starting the snapshot. The snapshotter keeps a weak reference to its delegate, so you must keep a strong reference to it to ensure that your style customizations apply.

Declaration

Objective-C

@property (nonatomic, weak, readwrite)
id<MGLMapSnapshotterDelegate> _Nullable delegate;

Swift

weak var delegate: MGLMapSnapshotterDelegate? { get set }

style

The style displayed in the resulting snapshot.

Unlike the MGLMapSnapshotOptions.styleURL property, this property is set to an object that allows you to manipulate every aspect of the style locally.

This property is set to nil until the style finishes loading. If the style has failed to load, this property is set to nil. Because the style loads asynchronously, you should manipulate it in the -[MGLMapSnapshotterDelegate mapSnapshotter:didFinishLoadingStyle:] method. It is not possible to manipulate the style before it has finished loading.

Note

The default styles provided by MapTiler contain sources and layers with identifiers that will change over time. Applications that use APIs that manipulate a style’s sources and layers must first set the style URL to an explicitly versioned style using a convenience method like +[MGLStyle outdoorsStyleURLWithVersion:] or a manually constructed NSURL.

Declaration

Objective-C

@property (nonatomic, readonly, nullable) MGLStyle *style;

Swift

var style: MGLStyle? { get }