diff options
author | Fabian Guerra Soto <fabian.guerra@mapbox.com> | 2017-10-04 10:03:03 -0400 |
---|---|---|
committer | GitHub <noreply@github.com> | 2017-10-04 10:03:03 -0400 |
commit | f01588cac78b5e5411385faa451080a74320500b (patch) | |
tree | 1f0540cf5c71475f0ae6714d70b909338fed9b5f /platform/darwin/src/MGLMapSnapshotter.h | |
parent | 6a846ce5a8ff1d62f4eafa3ef5bd0427096ca9e6 (diff) | |
download | qtlocation-mapboxgl-f01588cac78b5e5411385faa451080a74320500b.tar.gz |
[ios, macos] Improve snap shotter documentation. (#10020)
* [ios, macos] Improve snap shotter documentation.
* [macos] Save snapshots in correct format
* [macos] Renamed snapshot item to Export Image
* [ios, macos] Clarify Snapshotter documentation.
* [ios] Fix snapshot scale
* [macOS] Fix snapshotter 4x scaling.
* [ios] Fix snapshotter final image scale.
* [ios, macos] Update snapshotter size documentation.
* [ios, macos] Throw an exception when the snapshotter has already started.
* [ios, macos] Add snapshotter header example.
* [ios, macos] Use one of the predefined Foundation's exception names.
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; |