diff options
Diffstat (limited to 'platform/darwin/src/MGLMapSnapshotter.h')
-rw-r--r-- | platform/darwin/src/MGLMapSnapshotter.h | 85 |
1 files changed, 64 insertions, 21 deletions
diff --git a/platform/darwin/src/MGLMapSnapshotter.h b/platform/darwin/src/MGLMapSnapshotter.h index a2a4f1b331..615d39bee4 100644 --- a/platform/darwin/src/MGLMapSnapshotter.h +++ b/platform/darwin/src/MGLMapSnapshotter.h @@ -12,40 +12,52 @@ MGL_EXPORT @interface MGLMapSnapshotOptions : NSObject /** - Creates a set of options with the minimum required information - @param styleURL the style url to use - @param camera the camera settings - @param size the image size + Creates a set of options with the minimum required information. + + @param styleURL URL of the map style to snapshot. The URL may be a full HTTP or HTTPS URL, + a Mapbox URL indicating the style’s map ID (`mapbox://styles/{user}/{style`}), or a path + to a local file relative to the application’s resource path. Specify `nil` for the default style. + @param size The image size. */ -- (instancetype)initWithStyleURL:(NSURL*)styleURL camera:(MGLMapCamera*)camera size:(CGSize)size; +- (instancetype)initWithStyleURL:(nullable NSURL *)styleURL camera:(MGLMapCamera *)camera size:(CGSize)size; -#pragma mark - Configuring the map +#pragma mark - Configuring the Map /** - The style URL for these options. + URL of the map style to snapshot. */ -@property (nonatomic, readonly) NSURL* styleURL; +@property (nonatomic, readonly) NSURL *styleURL; /** - The zoom. Default is 0. + The zoom level. + + The default zoom level is 0. If this property is non-zero and the camera property + is non-nil, the camera’s altitude is ignored in favor of this property’s value. */ -@property (nonatomic) double zoom; +@property (nonatomic) double zoomLevel; /** - The `MGLMapcamera` options to use. + A camera representing the viewport visible in the snapshot. + + If this property is non-nil and the `coordinateBounds` property is set to a non-empty + coordinate bounds, the camera’s center coordinate and altitude are ignored in favor + of the `coordinateBounds` property. */ -@property (nonatomic) MGLMapCamera* camera; +@property (nonatomic) MGLMapCamera *camera; /** - A region to capture. Overrides the center coordinate - in the mapCamera options if set + The cooordinate rectangle that encompasses the bounds to capture. + + If this property is non-empty and the camera property is non-nil, the camera’s + center coordinate and altitude are ignored in favor of this property’s value. */ -@property (nonatomic) MGLCoordinateBounds region; +@property (nonatomic) MGLCoordinateBounds coordinateBounds; -#pragma mark - Configuring the image +#pragma mark - Configuring the Image /** - The size of the output image. Minimum is 64x64 + The size of the output image, measured in points. + */ @property (nonatomic, readonly) CGSize size; @@ -57,18 +69,46 @@ MGL_EXPORT @end +#if TARGET_OS_IPHONE /** A block to processes the result or error of a snapshot request. - The result will be either an `MGLImage` or a `NSError` + @param snapshot The `UIImage` that was generated or `nil` if an error occurred. + @param error The error that occured or `nil` when successful. + */ +typedef void (^MGLMapSnapshotCompletionHandler)(UIImage* _Nullable snapshot, NSError* _Nullable error); +#else +/** + A block to processes the result or error of a snapshot request. - @param snapshot The image that was generated or `nil` if an error occurred. + @param snapshot The `NSImage` that was generated or `nil` if an error occurred. @param error The eror that occured or `nil` when succesful. */ -typedef void (^MGLMapSnapshotCompletionHandler)(MGLImage* _Nullable snapshot, NSError* _Nullable error); +typedef void (^MGLMapSnapshotCompletionHandler)(NSImage* _Nullable snapshot, NSError* _Nullable error); +#endif /** - A utility object for capturing map-based images. + An immutable utility object for capturing map-based images. + + ### Example + + ```swift + var camera = MGLMapCamera() + camera.centerCoordinate = CLLocationCoordinate2D(latitude: 37.7184, longitude: -122.4365) + camera.pitch = 20 + + var options = MGLMapSnapshotOptions(styleURL: MGLStyle.satelliteStreetsStyleURL(), camera: camera, size: CGSize(width: 320, height: 480)) + options.zoomLevel = 10 + + var snapshotter = MGLMapSnapshotter(options: options) + snapshotter.start { (image, error) in + if error { + // error handler + } else { + // image handler + } + } + ``` */ MGL_EXPORT @interface MGLMapSnapshotter : NSObject @@ -92,6 +132,9 @@ MGL_EXPORT /** 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. */ - (void)cancel; |