MaplyTileSource

@protocol MaplyTileSource

The protocol for a Maply Tile Source.

Fill out this protocol and you can pass in your own data tile by tile. This protocol is used by the MaplyQuadImageTilesLayer to pull in image data per tile. This can be one or more images, they can be local, remote or even generated on the fly. It’s up to the object itself to return suitable data as requested or indicate failure (by returning nil).

The tile source should know its coordinate system, which is handed to Maply separately.

See

MaplyQuadImageTilesLayer

See

MaplyMBTileSource

See

MaplyRemoteTileSource

  • Declaration

    Objective-C

    - (int)minZoom;

    Swift

    func minZoom() -> Int32

    Return Value

    Returns the minimum allowable zoom layer. Ideally, this is 0.

  • Declaration

    Objective-C

    - (int)maxZoom;

    Swift

    func maxZoom() -> Int32

    Return Value

    Returns the maximum allowable zoom layer. Typically no more than 18, but it depends on your implementation.

  • Number of pixels on the side of a single tile (e.g. 128, 256).

    We use this for screen space calculation, so you don’t have to return the exact number of pixels in the imageForTile calls. It’s easier if you do, though.

    Declaration

    Objective-C

    - (int)tileSize;

    Swift

    func tileSize() -> Int32

    Return Value

    Returns the number of pixels on a side for a single tile.

  • Can the given tile be fetched locally or do we need a network call?

    We may ask the tile source if the tile is local or needs to be fetched over the network. This is a hint for the loader. Don’t return true in error, though, that’ll hold up the paging.

    Declaration

    Objective-C

    - (_Bool)tileIsLocal:(MaplyTileID)tileID frame:(int)frame;

    Swift

    func tileIsLocal(_ tileID: MaplyTileID, frame: Int32) -> Bool

    Return Value

    Return true for local tile sources or if you have the tile cached.

  • The coordinate system the image pyramid is in.

    This is typically going to be MaplySphericalMercator with the web mercator extents. That’s what you’ll get from OpenStreetMap and, often, MapBox. In other cases it might be MaplyPlateCarree, which covers the whole earth. Sometimes it might even be something unique of your own.

    Declaration

    Objective-C

    - (nonnull MaplyCoordinateSystem *)coordSys;

    Swift

    func coordSys() -> MaplyCoordinateSystem

  • Called when the layer shuts down.

    This is called by the main layer when things are shut down. It’s optional.

    Declaration

    Objective-C

    - (void)clear;

    Swift

    optional func clear()

  • Check if we should even try to load a given tile.

    Tile pyramids can be sparse. If you know where your pyramid is sparse, you can short circuit the fetch and simply return false here.

    If this method isn’t filled in, everything defaults to true.

    tileID The tile we’re asking about.

    bbox The bounding box of the tile we’re asking about, for convenience.

    Declaration

    Objective-C

    - (_Bool)validTile:(MaplyTileID)tileID bbox:(MaplyBoundingBox)bbox;

    Swift

    optional func validTile(_ tileID: MaplyTileID, bbox: MaplyBoundingBox) -> Bool

    Return Value

    True if the tile is loadable, false if not.

  • For tiles of variable sizes, return the pixel size we’ll use to evaluate this particular tile.

    If you have tiles with variable sizes… first of all why? Seriously, why are you doing that? Stop it.

    But if you must do variable sized tiles (Why?) fill in this method to give the importance function some clue as to what you’re doing. This will be called per tile to figure out when to load things.

    Variable sized tiles will screw up other things. SO DON’T DO IT.

    Declaration

    Objective-C

    - (int)tileSizeForTile:(MaplyTileID)tileID;

    Swift

    optional func tileSize(forTile tileID: MaplyTileID) -> Int32

  • Fetch the image for a given tile.

    For this method, you can return either a full UIImage or a MaplyImageTile.

    If you fail to load the image, just return nil. At that point the paging won’t page in tiles below this image, assuming that image pyramid is truncated at that point.

    If you don’t have an image to load (because there isn’t one) and you want the layer to keep paging below that, you should pass in a MaplyImageTile set up as a placeholder. The visual tile will be blank, but you’ll have the opportunity to provide higher resolution tiles.

    Declaration

    Objective-C

    - (nullable id)imageForTile:(MaplyTileID)tileID;

    Swift

    optional func image(forTile tileID: MaplyTileID) -> Any?

    Return Value

    Return an NSData*.

  • Fetch the image for a given frame of a given tile. These are for animation.

    For this method, you can return either a full UIImage or a MaplyImageTile.

    If you fail to load the image, just return nil. At that point the paging won’t page in tiles below this image, assuming that image pyramid is truncated at that point.

    If you don’t have an image to load (because there isn’t one) and you want the layer to keep paging below that, you should pass in a MaplyImageTile set up as a placeholder. The visual tile will be blank, but you’ll have the opportunity to provide higher resolution tiles.

    Declaration

    Objective-C

    - (nullable id)imageForTile:(MaplyTileID)tileID frame:(int)frame;

    Swift

    optional func image(forTile tileID: MaplyTileID, frame: Int32) -> Any?

    Parameters

    tileID

    Tile to load.
    frame

    Frame of tile animation to load.

    Return Value

    Return an NSData*.

  • Start fetching the given tile, probably with your own threads.

    If this is filled in that means the layer is expecting you to do your own asynchronous fetch. You’ll be called on a random thread here, so act accordingly.

    If you’re using a MaplyQuadImageTilesLayer, when you’re done fetching (successful or otherwise) call loadedImagesForTile: with the results.

    Declaration

    Objective-C

    - (void)startFetchLayer:(id _Nonnull)layer tile:(MaplyTileID)tileID;

    Swift

    optional func startFetchLayer(_ layer: Any, tile tileID: MaplyTileID)

    Parameters

    layer

    This is probably a MaplyQuadImageTilesLayer, but others use this protocol as well. Your tile source should know.
    tileID

    The tile you should start fetching.

  • Start fetching the given tile, but just the given frame. This is for multi-frame tiles (e.g. animations).

    If this is filled in that means the layer is expecting you to do your own asynchronous fetch. You’ll be called on a random thread here, so act accordingly.

    If you’re using a MaplyQuadImageTilesLayer, when you’re done fetching (successful or otherwise) call loadedImagesForTile: with the results.

    Declaration

    Objective-C

    - (void)startFetchLayer:(id _Nonnull)layer
                   tile:(MaplyTileID)tileID
                  frame:(int)frame;

    Swift

    optional func startFetchLayer(_ layer: Any, tile tileID: MaplyTileID, frame: Int32)

    Parameters

    layer

    This is probably a MaplyQuadImageTilesLayer, but others use this protocol as well. Your tile source should know.
    tileID

    The tile you should start fetching.
    frame

    The individual frame (of an animation) to fetch.

  • Called when the tile is disabled by the renderer.

    Normally you won’t get called when an image or vector tile is disabled from display. If you set this, you will.

    You’re not required to do anything, but you can disable your own data if you like.

    You will be called on another thread, so act accordingly.

    Declaration

    Objective-C

    - (void)tileWasDisabled:(MaplyTileID)tileID;

    Swift

    optional func tileWasDisabled(_ tileID: MaplyTileID)

    Parameters

    tileID

    The tile tha that just got disabled.

  • Called when the tile is enabled by the renderer.

    Normally you won’t get called when an image or vector tile is enabled in display. If you set this, you will.

    You’re not required to do anything, but you can enable your own data if you like.

    You will be called on another thread, so act accordingly.

    Declaration

    Objective-C

    - (void)tileWasEnabled:(MaplyTileID)tileID;

    Swift

    optional func tileWasEnabled(_ tileID: MaplyTileID)

    Parameters

    tileID

    The tile tha that just got disabled.

  • Called when the tile is unloaded.

    Normally you won’t get called when an image or vector tile is unloaded from memory. If you set this, you will.

    You’re not required to do anything, but you can clean up data of your own if you like.

    You will be called on another thread, so act accordingly.

    Declaration

    Objective-C

    - (void)tileUnloaded:(MaplyTileID)tileID;

    Swift

    optional func tileUnloaded(_ tileID: MaplyTileID)

    Parameters

    tileID

    The tile tha that just got unloaded.