[ios, macos] Improve snap shotter documentation.

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

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 @@ - (instancetype _Nonnull)initWithStyleURL:(nullable NSURL*)styleURL camera:(MGLM
 
 @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 @@ - (instancetype)initWithOptions:(MGLMapSnapshotOptions*)options;
  _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 @@ - (instancetype)initWithOptions:(MGLMapSnapshotOptions*)options;
  }
 
  // 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 @@ - (void)startWithQueue:(dispatch_queue_t)queue completionHandler:(MGLMapSnapshot
  _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 @@ - (void)startWithQueue:(dispatch_queue_t)queue completionHandler:(MGLMapSnapshot
  });
  }
  });
- mbglMapSnapshotter->snapshot(snapshotCallback->self());
+ _mbglMapSnapshotter->snapshot(_snapshotCallback->self());
  });
 }
 
 - (void)cancel;
 {
- snapshotCallback.reset();
- mbglMapSnapshotter.reset();
+ _snapshotCallback.reset();
+ _mbglMapSnapshotter.reset();
 }
 
 @end