MKOverlayRenderer Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/MapKit.framework
Availability
Available in iOS 7.0 and later.
Declared in
MKOverlayRenderer.h

Overview

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.

Tasks

Initializing an Overlay View

Attributes of the Overlay

Converting Points on the Map

Drawing the Overlay

Properties

alpha

The amount of transparency to apply to the overlay.

@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.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKOverlayRenderer.h

contentScaleFactor

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

@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.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKOverlayRenderer.h

overlay

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

@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.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKOverlayRenderer.h

Instance Methods

canDrawMapRect:zoomScale:

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

- (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

YES if this overlay renderer is ready to draw its contents on the map or NO 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 NO from this method to indicate that it is not ready. An overlay renderer might also return NO if it does not draw content in the specified rectangle.

If you return NO 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 YES.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKOverlayRenderer.h

drawMapRect:zoomScale:inContext:

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

- (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.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKOverlayRenderer.h

initWithOverlay:

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

- (id)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.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKOverlayRenderer.h

mapPointForPoint:

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

- (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.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKOverlayRenderer.h

mapRectForRect:

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

- (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.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKOverlayRenderer.h

pointForMapPoint:

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

- (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.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKOverlayRenderer.h

rectForMapRect:

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

- (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.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKOverlayRenderer.h

setNeedsDisplay

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

- (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.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKOverlayRenderer.h

setNeedsDisplayInMapRect:

Invalidates the specified portion of the overlay at all zoom scales

- (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.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKOverlayRenderer.h

setNeedsDisplayInMapRect:zoomScale:

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

- (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.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKOverlayRenderer.h