Mac Developer Library

Developer

MapKit Framework Reference MKOverlayRenderer Class Reference

Options
Deployment Target:

On This Page
Language:

MKOverlayRenderer

The MKOverlayRenderer class defines the basic behavior associated with all map-based overlays. An overlay renderer draws the visual representation of an overlay object—that is, an object that conforms to the MKOverlay protocol. This class defines the drawing infrastructure used by the map view. Subclasses are expected to override the drawMapRect:zoomScale:inContext: method to draw the contents of the overlay.

The Map Kit framework provides several concrete instances of overlay renderers. Specifically, it provides renderers for each of the concrete overlay objects. You can use one of these existing renderers or define your own subclasses if you want to draw the overlay contents differently.

Subclassing Notes

You can subclass MKOverlayRenderer to create overlays based on custom shapes, content, or drawing techniques. The only method subclasses are expected to override is the drawMapRect:zoomScale:inContext: method. However, if your class contains content that may not be ready for drawing right away, you should also override the canDrawMapRect:zoomScale: method and use it to report when your class is ready and able to draw.

The map view may tile large overlays and distribute the rendering of each tile to separate threads. Therefore, the implementation of your drawMapRect:zoomScale:inContext: method must be safe to run from background threads and from multiple threads simultaneously.

Conforms To


Import Statement


Swift

import MapKit

Objective-C

@import MapKit;

Availability


Available in OS X v10.9 and later.
  • init(overlay:) - initWithOverlay: Designated Initializer

    Initializes and returns the overlay renderer and associates it with the specified overlay object.

    Declaration

    Swift

    init!(overlay overlay: MKOverlay!)

    Objective-C

    - (instancetype)initWithOverlay:(id<MKOverlay>)overlay

    Parameters

    overlay

    The overlay object to use when drawing the overlay content on the map. This object provides the data needed to draw the overlay’s shape. The overlay renderer stores a strong reference to this object.

    Return Value

    An initialized overlay renderer object.

    Discussion

    Initially, the overlay renderer assumes that the overlay is fully opaque and that it has a content scale factor of 1.0. You can change these values as needed using the alpha and contentScaleFactor properties.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in OS X v10.9 and later.

  • overlay overlay Property

    The overlay object containing the data for drawing. (read-only)

    Declaration

    Swift

    var overlay: MKOverlay! { get }

    Objective-C

    @property(nonatomic, readonly) id< MKOverlay > overlay

    Discussion

    The overlay object contains the coordinate at which to draw the overlay and other information that your app provides.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in OS X v10.9 and later.

  • alpha alpha Property

    The amount of transparency to apply to the overlay.

    Declaration

    Swift

    var alpha: CGFloat

    Objective-C

    @property CGFloat alpha

    Discussion

    The value in this property can be in the range 0.0 to 1.0, where 0.0 represents total transparency and 1.0 represents total opacity. The default value of this property is 1.0.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in OS X v10.9 and later.

  • The scale factor used to draw the overlay’s content. (read-only)

    Declaration

    Swift

    var contentScaleFactor: CGFloat { get }

    Objective-C

    @property(readonly) CGFloat contentScaleFactor

    Discussion

    The scale factor determines how content is mapped from the logical coordinate space (measured in points) to the device coordinate space (measured in pixels). This value is typically either 1.0 or 2.0. Higher scale factors indicate that each point is represented by more than one pixel on the screen. For example, if the scale factor is 2.0 and the drawing rectangle size is 50 x 50 points, the size of the underlying area is 100 x 100 pixels.

    When drawing the content for your overlays, you can use this value to determine how best to render your content.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in OS X v10.9 and later.

  • Returns the point in the overlay renderer’s drawing area corresponding to the specified point on the map.

    Declaration

    Swift

    func pointForMapPoint(_ mapPoint: MKMapPoint) -> CGPoint

    Objective-C

    - (CGPoint)pointForMapPoint:(MKMapPoint)mapPoint

    Parameters

    mapPoint

    A point on the two-dimensional map projection. If you have a coordinate value (latitude and longitude), you can use the MKMapPointForCoordinate function to convert that coordinate to a map point.

    Return Value

    The point in the overlay’s drawing area that corresponds to the map point.

    Discussion

    You may call this method safely from your view’s drawMapRect:zoomScale:inContext: method.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in OS X v10.9 and later.

  • Returns the point on the map that corresponds to the specified point in the overlay renderer’s drawing area.

    Declaration

    Swift

    func mapPointForPoint(_ point: CGPoint) -> MKMapPoint

    Objective-C

    - (MKMapPoint)mapPointForPoint:(CGPoint)point

    Parameters

    point

    The point in the overlay’s drawing area that you want to convert.

    Return Value

    The point on the two-dimensional map projection corresponding to the specified point.

    Discussion

    You may call this method safely from your view’s drawMapRect:zoomScale:inContext: method.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in OS X v10.9 and later.

  • Returns the rectangle in the overlay renderer’s drawing area corresponding to the specified rectangle on the map.

    Declaration

    Swift

    func rectForMapRect(_ mapRect: MKMapRect) -> CGRect

    Objective-C

    - (CGRect)rectForMapRect:(MKMapRect)mapRect

    Parameters

    mapRect

    A rectangle on the two-dimensional map projection.

    Return Value

    The rectangle in the overlay’s drawing area that corresponds to the map rectangle.

    Discussion

    You may call this method safely from your view’s drawMapRect:zoomScale:inContext: method.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in OS X v10.9 and later.

  • Returns the rectangle on the map that corresponds to the specified rectangle in the overlay renderer’s drawing area.

    Declaration

    Swift

    func mapRectForRect(_ rect: CGRect) -> MKMapRect

    Objective-C

    - (MKMapRect)mapRectForRect:(CGRect)rect

    Parameters

    rect

    The rectangle in the overlay’s drawing area that you want to convert.

    Return Value

    The rectangle on the two-dimensional map projection corresponding to the specified rectangle.

    Discussion

    You may call this method safely from your view’s drawMapRect:zoomScale:inContext: method.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in OS X v10.9 and later.

  • Returns a Boolean value indicating whether the overlay view is ready to draw its content.

    Declaration

    Swift

    func canDrawMapRect(_ mapRect: MKMapRect, zoomScale zoomScale: MKZoomScale) -> Bool

    Objective-C

    - (BOOL)canDrawMapRect:(MKMapRect)mapRect zoomScale:(MKZoomScale)zoomScale

    Parameters

    mapRect

    The map rectangle that needs to be updated.

    zoomScale

    The current scale factor applied to the map.

    Return Value

    YEStrue if this overlay renderer is ready to draw its contents on the map or NOfalse if it is not.

    Discussion

    Overlay renderers can override this method in situations where they may depend on the availability of other information to draw their contents. For example, a renderer showing traffic information might want to delay drawing until it has all of the traffic data it needs. In such a case, it can return NOfalse from this method to indicate that it is not ready. An overlay renderer might also return NOfalse if it does not draw content in the specified rectangle.

    If you return NOfalse from this method, your application is responsible for calling the setNeedsDisplayInMapRect:zoomScale: method when the overlay renderer subsequently becomes ready to draw its contents.

    The default implementation of this method returns YEStrue.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in OS X v10.9 and later.

  • Draws the overlay’s contents at the specified location on the map.

    Declaration

    Swift

    func drawMapRect(_ mapRect: MKMapRect, zoomScale zoomScale: MKZoomScale, inContext context: CGContext!)

    Objective-C

    - (void)drawMapRect:(MKMapRect)mapRect zoomScale:(MKZoomScale)zoomScale inContext:(CGContextRef)context

    Parameters

    mapRect

    The map rectangle that needs to be updated. Your drawing code should avoid drawing outside of this rectangle.

    zoomScale

    The current zoom factor applied to the map content. You can use this value for configuring the stroke width of lines or other attributes that might be affected by the scale of the map’s contents.

    context

    The graphics context to use for drawing the overlay’s contents.

    Discussion

    The default implementation of this method does nothing. Subclasses are expected to override this method and use it to draw the overlay’s contents.

    When determining where to draw content, make your initial calculations relative to the map itself. In other words, compute the position and size of any overlay content using map points and map rectangles, convert those values to regular CGPoint and CGRect types using the methods of this class, and then pass the converted points to any drawing primitives.

    It is recommended that you use Core Graphics to draw any content for your overlays. If you choose to draw using UIKit classes and methods instead, you must push the specified graphics context onto the context stack (using the UIGraphicsPushContext function) before making any drawing calls. When you are done drawing, you must similarly pop the graphics context off the stack using the UIGraphicsPopContext. Overlay drawing typically occurs on background threads to improve performance, so do not manipulate UIKit views or other objects that can only be manipulated on the app’s main thread.

    To improve drawing performance, the map view may divide your overlay into multiple tiles and render each one on a separate thread. Your implementation of this method must therefore be capable of safely running from multiple threads simultaneously. In addition, you should avoid drawing the entire contents of the overlay each time this method is called. Instead, always take the mapRect parameter into consideration and avoid drawing content outside that rectangle.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in OS X v10.9 and later.

  • Invalidates the entire contents of the overlay for all zoom scales.

    Declaration

    Swift

    func setNeedsDisplay()

    Objective-C

    - (void)setNeedsDisplay

    Discussion

    This method causes the entire contents of the overlay to be redrawn during the next update cycle. This method invalidates the overlay regardless of the current zoom scale associated with the map.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in OS X v10.9 and later.

  • Invalidates the specified portion of the overlay at all zoom scales

    Declaration

    Swift

    func setNeedsDisplayInMapRect(_ mapRect: MKMapRect)

    Objective-C

    - (void)setNeedsDisplayInMapRect:(MKMapRect)mapRect

    Parameters

    mapRect

    The portion of the overlay to update. Specify this value using a map coordinates.

    Discussion

    Marking a rectangle as invalid causes that portion of the overlay to be redrawn during the next update cycle. This method invalidates the overlay regardless of the current zoom scale associated with the map.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in OS X v10.9 and later.

  • Invalidates the specified portion of the overlay but only at the specified zoom scale.

    Declaration

    Swift

    func setNeedsDisplayInMapRect(_ mapRect: MKMapRect, zoomScale zoomScale: MKZoomScale)

    Objective-C

    - (void)setNeedsDisplayInMapRect:(MKMapRect)mapRect zoomScale:(MKZoomScale)zoomScale

    Parameters

    mapRect

    The portion of the overlay to update. Specify this value using a map coordinates.

    zoomScale

    The zoom scale for which you want to invalidate the overlay.

    Discussion

    Marking a rectangle as invalid causes that portion of the overlay to be redrawn during the next update cycle. This method invalidates the overlay only at the specified zoom scale.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in OS X v10.9 and later.