[ios, macos] Clarify Snapshotter documentation.

2 files changed, 31 insertions, 21 deletions

diff --git a/platform/darwin/src/MGLMapSnapshotter.h b/platform/darwin/src/MGLMapSnapshotter.h
index d39b252b51..1b43f9fc1e 100644
--- a/platform/darwin/src/MGLMapSnapshotter.h
+++ b/platform/darwin/src/MGLMapSnapshotter.h
@@ -15,34 +15,41 @@ MGL_EXPORT
  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.
+ 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:(nullable NSURL*)styleURL camera:(MGLMapCamera*)camera size:(CGSize)size;
+- (instancetype)initWithStyleURL:(nullable NSURL *)styleURL camera:(MGLMapCamera *)camera size:(CGSize)size;
 
 #pragma mark - Configuring the Map
 
 /**
- 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.
+ URL of the map style to snapshot.
  */
 @property (nonatomic, readonly) NSURL *styleURL;
 
 /**
- The default zoom level is 0. Overrides the altitude in the mapCamera options if set.
+ 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 zoomLevel;
 
 /**
  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;
 
 /**
- The cooordinate rectangle that encompasses the bounds 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 coordinateBounds;
 
@@ -68,7 +75,7 @@ MGL_EXPORT
  A block to processes the result or error of a snapshot request.
  
  @param snapshot The `UIImage` that was generated or `nil` if an error occurred.
- @param error The error that occured or `nil` when succesful.
+ @param error The error that occured or `nil` when successful.
  */
 typedef void (^MGLMapSnapshotCompletionHandler)(UIImage* _Nullable snapshot, NSError* _Nullable error);
 #else
diff --git a/platform/darwin/src/MGLMapSnapshotter.mm b/platform/darwin/src/MGLMapSnapshotter.mm
index b1254b5d3b..3dbebf1f08 100644
--- a/platform/darwin/src/MGLMapSnapshotter.mm
+++ b/platform/darwin/src/MGLMapSnapshotter.mm
@@ -22,6 +22,7 @@
 #endif
 
 const CGPoint MGLLogoImagePosition = CGPointMake(8, 8);
+const CGFloat MGLSnapshotterMinimumPixelSize = 64;
 
 @implementation MGLMapSnapshotOptions
 
@@ -50,9 +51,9 @@ const CGPoint MGLLogoImagePosition = CGPointMake(8, 8);
 
 @implementation MGLMapSnapshotter {
     
-    std::shared_ptr<mbgl::ThreadPool> mbglThreadPool;
-    std::unique_ptr<mbgl::MapSnapshotter> mbglMapSnapshotter;
-    std::unique_ptr<mbgl::Actor<mbgl::MapSnapshotter::Callback>> snapshotCallback;
+    std::shared_ptr<mbgl::ThreadPool> _mbglThreadPool;
+    std::unique_ptr<mbgl::MapSnapshotter> _mbglMapSnapshotter;
+    std::unique_ptr<mbgl::Actor<mbgl::MapSnapshotter::Callback>> _snapshotCallback;
 }
 
 - (instancetype)initWithOptions:(MGLMapSnapshotOptions*)options;
@@ -62,14 +63,16 @@ const CGPoint MGLLogoImagePosition = CGPointMake(8, 8);
         _loading = false;
         
         mbgl::DefaultFileSource *mbglFileSource = [MGLOfflineStorage sharedOfflineStorage].mbglFileSource;
-        mbglThreadPool = mbgl::sharedThreadPool();
+        _mbglThreadPool = mbgl::sharedThreadPool();
         
         std::string styleURL = std::string([options.styleURL.absoluteString UTF8String]);
         
         // Size; taking into account the minimum texture size for OpenGL ES
+        // For non retina screens the ratio is 1:1 MGLSnapshotterMinimumPixelSize
+        
         mbgl::Size size = {
-            static_cast<uint32_t>(MAX(options.size.width, 64)),
-            static_cast<uint32_t>(MAX(options.size.height, 64))
+            static_cast<uint32_t>(MAX(options.size.width, MGLSnapshotterMinimumPixelSize/options.scale)),
+            static_cast<uint32_t>(MAX(options.size.height, MGLSnapshotterMinimumPixelSize/options.scale))
         };
         
         float pixelRatio = MAX(options.scale, 1);
@@ -90,7 +93,7 @@ const CGPoint MGLLogoImagePosition = CGPointMake(8, 8);
         }
         
         // Create the snapshotter
-        mbglMapSnapshotter = std::make_unique<mbgl::MapSnapshotter>(*mbglFileSource, *mbglThreadPool, styleURL, size, pixelRatio, cameraOptions, coordinateBounds);
+        _mbglMapSnapshotter = std::make_unique<mbgl::MapSnapshotter>(*mbglFileSource, *_mbglThreadPool, styleURL, size, pixelRatio, cameraOptions, coordinateBounds);
     }
     return self;
 }
@@ -115,7 +118,7 @@ const CGPoint MGLLogoImagePosition = CGPointMake(8, 8);
     _loading = true;
     
     dispatch_async(queue, ^{
-        snapshotCallback = std::make_unique<mbgl::Actor<mbgl::MapSnapshotter::Callback>>(*mbgl::Scheduler::GetCurrent(), [=](std::exception_ptr mbglError, mbgl::PremultipliedImage image) {
+        _snapshotCallback = std::make_unique<mbgl::Actor<mbgl::MapSnapshotter::Callback>>(*mbgl::Scheduler::GetCurrent(), [=](std::exception_ptr mbglError, mbgl::PremultipliedImage image) {
             _loading = false;
             if (mbglError) {
                 NSString *description = @(mbgl::util::toString(mbglError).c_str());
@@ -158,14 +161,14 @@ const CGPoint MGLLogoImagePosition = CGPointMake(8, 8);
                 });
             }
         });
-        mbglMapSnapshotter->snapshot(snapshotCallback->self());
+        _mbglMapSnapshotter->snapshot(_snapshotCallback->self());
     });
 }
 
 - (void)cancel;
 {
-    snapshotCallback.reset();
-    mbglMapSnapshotter.reset();
+    _snapshotCallback.reset();
+    _mbglMapSnapshotter.reset();
 }
 
 @end