HERE iOS SDK Developer's Guide

<NMAMapTileLayerDataSource>

Protocol Summary

protocol <NMAMapTileLayerDataSource>

Derived from: <NSObject>

An interface for providing tile bitmap data to an NMAMapTileLayer instance.

Include: NMAKit.framework/headers/NMAMapTileLayer.h

Inheritance Diagrams

Figure 1. Public inheritance diagram for <NMAMapTileLayerDataSource> – <NMAMapTileLayerDataSource>

[For complete information, see the section Protocol Details]

Instance Method Summary

Table 1. Instance Methods
Instance Method Summary

- @optional (BOOL) mapTileLayer:( NMAMapTileLayer *) mapTileLayer hasTileAtX:(NSUInteger) x y:(NSUInteger) y zoomLevel:(NSUInteger) zoomLevel

Indicates if the specified tile should be rendered.

- @optional (NSData *) mapTileLayer:( NMAMapTileLayer *) mapTileLayer requestDataForTileAtX:(NSUInteger) x y:(NSUInteger) y zoomLevel:(NSUInteger) zoomLevel

Return raw tile bitmap data for the specified tile.

- @optional (void) mapTileLayer:( NMAMapTileLayer *) mapTileLayer requestDataForTileAtX:(NSUInteger) x y:(NSUInteger) y zoomLevel:(NSUInteger) zoomLevel tileRequest:( NMAMapTileRequest *) tileRequest

Requests raw tile bitmap data for the specified tile.

- @optional (NSString *) mapTileLayer:( NMAMapTileLayer *) mapTileLayer urlForTileAtX:(NSUInteger) x y:(NSUInteger) y zoomLevel:(NSUInteger) zoomLevel

Returns a URL from which the tile bitmap can be downloaded.

Protocol Details

An interface for providing tile bitmap data to an NMAMapTileLayer instance.

Note:

The methods of this protocol will be called on an internal NMA map rendering queue. Blocking this queue for extended periods of time will adversely effect map rendering performance.

Instance Method Details

- @optional (BOOL) mapTileLayer:( NMAMapTileLayer *) mapTileLayer hasTileAtX:(NSUInteger) x y:(NSUInteger) y zoomLevel:(NSUInteger) zoomLevel

Indicates if the specified tile should be rendered.

If this method returns NO then a further call to request tile bitmap data or tile URL will not be made. Not implementing this protocol method is equivalent to returning YES.

At each zoomLevel the framework expects the "world" to be rendered on (2^zoomLevel)^2 tiles.

The x and y parameters indicate which tile is being requested for the given zoom level:
  • At zoom level 0 the framework will ask you for 1 x 1 tiles
  • At zoom level 1 the framework will ask you for 2 x 2 tiles
  • At zoom level 2 the framework will ask you for 4 x 4 tiles
  • At zoom level 3 the framework will ask you for 8 x 8 tiles
  • At zoom level 4 the framework will ask you for 16 x 16 tiles
  • ...
  • The maximum zoom level depends on the NMAMapTileLayer::tileSize property. At tileSize 256 the maximum zoom level will be 20, at tileSize 128 the maximum zoom level will be 21 in order to supple enough pixels to render the entire map. At tile size 512 the maximum zoom level would be 19, and so on.
Note:

This method is called on an internal NMA map rendering queue. Blocking for extended periods of time will impact map rendering performance.

Parameters:

  • mapTileLayer

    NMAMapTileLayer instance that is requesting the tile.

  • x

    X coordinate of the tile being requested in the range 1..(2^zoomLevel).

  • y

    Y coordinate of the tile being requested in the range 1..(2^zoomLevel).

  • zoomLevel

    Zoom level of the tile being requested in the range NMAMapViewMinimumZoomLevel.NMAMapViewMaximumZoomLevel. The zoomLevel parameter value may NOT have the same value as the zoomLevel property of the NMAMapView to which the NMAMapTileLayer has been added. The relationship between these two zoom levels depends on the NMAMapTileLayer::tileSize property.

Returns:

YES if the requested tile should be rendered, NO otherwise.

- @optional (NSData *) mapTileLayer:( NMAMapTileLayer *) mapTileLayer requestDataForTileAtX:(NSUInteger) x y:(NSUInteger) y zoomLevel:(NSUInteger) zoomLevel

Return raw tile bitmap data for the specified tile.

Implement this method if you wish to supply raw tile bitmap data. This method will be called whenever the map view needs bitmap data to render the specified tile.

Return tile bitmap data in NSData and it's NMAMapTileRequest status will be set to NMARasterTileRequestComplete if NSData is valid or NMARasterTileRequestFailed if NSData is nil. Be aware that performing lengthy operations within this method will impact the performance of the map rendering.

If the tile bitmap data is not available and it's NMAMapTileReuqest status is set to NMAMapTileRequestStatusFailed the framework will repeatedly ask for tile data again via NMAMapTileLayerDataSource::mapTileLayer:requestDataForTileAtX: until the request is completed with NMAMapTileRequestStatusComplete. If the tile bitmap data cannot be made available then return NO from NMAMapTileLayerDataSource::mapTileLayer:hasTileAtX: to avoid endless callbacks.

The bitmap data you provide MUST corresponds to the tileSize, pixelFormat and transparent properties of mapTileLayer.

See mapTileLayer:hasTileAtX:y:zoomLevel: for a detailed description of the x, y and zoomLevel parameters.

Implementing this method will prevent mapTileLayer:urlForTileAtX:y:zoomLevel: and mapTileLayer:requestTileAtX:y:zoomLevel:tileRequest from being called.

Note:

This method is called on an internal NMA map rendering queue. Blocking for extended periods of time will impact map rendering performance.

Parameters:

  • mapTileLayer

    NMAMapTileLayer instance that is requesting the tile bitmap.

  • x

    X coordinate of the tile being requested in the range 1..(2^zoomLevel).

  • y

    Y coordinate of the tile being requested in the range 1..(2^zoomLevel).

  • zoomLevel

    Zoom level of the tile being requested in the range NMAMapViewMinimumZoomLevel..NMAMapViewMaximumZoomLevel. The zoomLevel parameter value may NOT have the same value as the zoomLevel property of the NMAMapView to which the NMAMapTileLayer has been added. The relationship between these two zoom levels depends on the NMAMapTileLayer::tileSize property.

Returns:

Raw tile bitmap data.

- @optional (void) mapTileLayer:( NMAMapTileLayer *) mapTileLayer requestDataForTileAtX:(NSUInteger) x y:(NSUInteger) y zoomLevel:(NSUInteger) zoomLevel tileRequest:( NMAMapTileRequest *) tileRequest

Requests raw tile bitmap data for the specified tile.

Implement this method if you wish to supply raw tile bitmap data. This method will be called whenever the map view needs bitmap data to render the specified tile.

To return bitmap data synchronously write data to the NMAMapTileRequest instance and set it's status to NMARasterTileRequestComplete or NMARasterTileRequestFailed. Be aware that performing lengthy operations within this method will impact the performance of the map rendering.

To return bitmap asynchronously retain the NMAMapTileRequest and return. Write data to the NMAMapTileRequest and set it completion status when the request is complete.

NMAMapTileRequest may be accessed from any thread or GCD queue. Ensure the data is written before setting the request status to NMAMapTileRequestStatusComplete.

The bitmap data you write to the NMAMapTileRequest MUST corresponds to the tileSize, pixelFormat and transparent properties of mapTileLayer.

Implementing this method will prevent mapTileLayer:urlForTileAtX:y:zoomLevel: from being called.

See also mapTileLayer:hasTileAtX:y:zoomLevel: for a detailed description of the x, y and zoomLevel parameters.

Note:

This method is called on an internal NMA map rendering queue. Blocking for extended periods of time will impact map rendering performance.

Parameters:

  • mapTileLayer

    NMAMapTileLayer instance that is requesting the tile bitmap.

  • x

    X coordinate of the tile being requested in the range 1..(2^zoomLevel).

  • y

    Y coordinate of the tile being requested in the range 1..(2^zoomLevel).

  • zoomLevel

    Zoom level of the tile being requested in the range NMAMapViewMinimumZoomLevel..NMAMapViewMaximumZoomLevel. The zoomLevel parameter value may NOT have the same value as the zoomLevel property of the NMAMapView to which the NMAMapTileLayer has been added. The relationship between these two zoom levels depends on the NMAMapTileLayer::tileSize property.

  • tileRequest

    NMAMapTileRequest instance used to write the bitmap data and complete the request

- @optional (NSString *) mapTileLayer:( NMAMapTileLayer *) mapTileLayer urlForTileAtX:(NSUInteger) x y:(NSUInteger) y zoomLevel:(NSUInteger) zoomLevel

Returns a URL from which the tile bitmap can be downloaded.

Implement this method if you wish to have the framework download tile bitmap data from a URL you provide. This method will be called whenever the map view needs bitmap data to render the specified tile.

This method is provided as a convenience for the common case of downloading bitmaps tiles from a URL. The data returned from the URL must be in either png and jpg format.

The framework will convert the png/jpg data downloadeded to the value specified by the pixelFormat property of the mapTileLayer instance. The size and transparency of the downloaded data must match the tileSize and transparent properties of the mapTileLayer instance. If the size (width and height), of the downloaded image does not match the tileSize property the tile will not be rendered.

This method will not be called if you also implement mapTileLayer:requestTileAtX:y:zoomLevel:tileRequest or mapTileLayer:requestTileAtX:y:zoomLevel

See mapTileLayer:hasTileAtX:y:zoomLevel: for a detailed description of the x, y and zoomLevel parameters.

Note:

This method is called on an internal NMA map rendering queue. Blocking for extended periods of time will impact map rendering performance.

Parameters:

  • mapTileLayer

    NMAMapTileLayer instance that is requesting the tile URL.

  • x

    X coordinate of the tile being requested in the range 1..(2^zoomLevel).

  • y

    Y coordinate of the tile being requested in the range 1..(2^zoomLevel).

  • zoomLevel

    Zoom level of the tile being requested in the range NMAMapViewMinimumZoomLevel..NMAMapViewMaximumZoomLevel. The zoomLevel parameter value may NOT have the same value as the zoomLevel property of the NMAMapView to which the NMAMapTileLayer has been added. The relationship between these two zoom levels depends on the NMAMapTileLayer::tileSize property.

Returns:

URL to fetch the requested tile from.