MaplyQuadPagingLayer

@interface MaplyQuadPagingLayer : MaplyViewControllerLayer

The Quad Paging Layer is for loading things like vector tile sets.

The Maply Quad Paging Layer implements a general purpose paging interface for quad tree based data sources. This is different from the MaplyQuadImageTilesLayer in that it’s meant for paging things like vector tiles, or really any other features that are not images.

You set up an object that implements the MaplyPagingDelegate protocol, create the MaplyQuadPagingLayer and respond to the startFetchForTile:forLayer: method.

Once you’ve fetched your data for a given tile, you’ll need to call tileDidLoad: or tileFailedToLoad:. Then you’ll want to create the visual objects in the MaplyViewController or WhirlyGlobeViewController and pass them in to addData:forTile:

This is how the paging layer keeps track of which objects you’ve created for a given tile and can then remove them when the time comes.

Objects must be created with @enable set to @(NO) in the description dictionary. Tiles are paged before they are needed for dipslay and so the paging layer must have control over when data is displayed. It uses the enable/disable options for the various Maply objects in the view controllers.

  • Number of fetches allowed at once.

    Change the number of fetches allowed at once. This means you’ll have at most numSimultaneousFetches dispatch queues going.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) int numSimultaneousFetches;

    Swift

    var numSimultaneousFetches: Int32 { get set }

  • The importance cutoff below which we won’t bother to page a tile.

    The paging layer will evaluate tiles based on screen space they take up. This is the cutoff we use to evaluate when a tile is worth paging in. It’s the number of pixels a given tile would take up on the screen.

    Typical values would be on the order of 256*256.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) float importance;

    Swift

    var importance: Float { get set }

  • Control how tiles are indexed, either from the lower left or the upper left.

    If set, we’ll use the OSM approach (also Google Maps) to y indexing. This is off by default.

    Strictly speaking, TMS addressing (the standard) is flipped the other way. So if youre tile source looks odd, try setting this to false.

    Default value is false.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) _Bool flipY;

    Swift

    var flipY: Bool { get set }

  • The view controller this paging layer is associated with.

    This view controller is the one you should create visual objects in.

    Declaration

    Objective-C

    @property (readonly, nonatomic, nullable) MaplyBaseViewController *viewC;

    Swift

    weak var viewC: MaplyBaseViewController? { get }

  • Initialize with coordinate system and delegate for paging.

    This initializer takes the coordinate system we’re working in and the MaplyPagingDelegate object. Fill out that to do the real work.

    Declaration

    Objective-C

    - (nullable instancetype)
initWithCoordSystem:(MaplyCoordinateSystem *_Nonnull)coordSys
           delegate:(NSObject<MaplyPagingDelegate> *_Nonnull)tileSource;

    Swift

    init?(coordSystem coordSys: MaplyCoordinateSystem, delegate tileSource: NSObjectProtocol

    Parameters

    coordSys

    The coordinate system we’re working in.
    tileSource

    The tile source that will fetch data and create visible objects.

    Return Value

    Returns a MaplyViewControllerLayer that can be added to the MaplyBaseViewController.

  • Use the target zoom level shortcut when possible.

    This turns on the target zoom level shortcut as described in targetZoomLevel. When on we’ll calculate tile importance that way, that is based on a target zoom level rather than the more complex screen space calculations.

    It’s on by default and will activate only when this layer’s coordinate system is the same as the display system and there’s no view matrix (e.g. tilt) set.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) _Bool useTargetZoomLevel;

    Swift

    var useTargetZoomLevel: Bool { get set }

  • Only load a single level at a time.

    When set, we’ll only load one level of tiles at once. This is very efficient for memory and fast for loading, but you’ll see flashing as you move between levels.

    This mode only works with flat maps and is off by default.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) _Bool singleLevelLoading;

    Swift

    var singleLevelLoading: Bool { get set }

  • The target zoom level for this layer given the current view settings.

    Calculates the target zoom level for the middle of the screen.

    This only makes sense for flat maps that use the same coordinate system we’re using in this tile source. In addition, the viewer can’t have a tilt or any non-2D transform in the view matrix. If it does, this is meaningless, but it’ll return a number anyway.

    If all those conditions are met then we can say we’re only displaying a single zoom level and this is that.

    Declaration

    Objective-C

    - (int)targetZoomLevel;

    Swift

    func targetZoomLevel() -> Int32

  • Modify how the importance (screen space) is calculated for any given tile.

    This is set by default and when set we use the parent’s bounding box to calculate importance for a given tile.

    This has the effect of forcing all four children to load at once. If you don’t need that, if you’re doing additive geometry, for instance, then you can set this to false.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) _Bool useParentTileBounds;

    Swift

    var useParentTileBounds: Bool { get set }

  • This controls how the importance of tiles is calculated. Either individually (false) or with the parent (true),

    This is a low level laoding control parameter. Don’t change unless you know why.

    By default this is true.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) _Bool groupChildrenWithParent;

    Swift

    var groupChildrenWithParent: Bool { get set }

  • You call this from your MaplyPagingDelegate with an array of data you’ve created for a tile.

    This method is called by your MaplyPagingDelegate to add MaplyComponentObject’s to the data for a given tile. Please create them disabled by putting @enable: @(NO) in the description dictionary. The paging layer will then be responsible for cleaning them up when needed as well as turning them on and off as the user moves around.

    The call is thread safe.

    Declaration

    Objective-C

    - (void)addData:(NSArray *_Nonnull)dataObjects forTile:(MaplyTileID)tileID;

    Swift

    func addData(_ dataObjects: [Any], forTile tileID: MaplyTileID)

    Parameters

    dataObjects

    An NSArray of MaplyComponentObject objects.
    tileID

    The tile ID for the data we’re handing over.

  • You call this from your MaplyPagingDelegate with an array of data you’ve created for a tile.

    This method is called by your MaplyPagingDelegate to add MaplyComponentObject’s to the data for a given tile. Please create them disabled by putting @enable: @(NO) in the description dictionary. The paging layer will then be responsible for cleaning them up when needed as well as turning them on and off as the user moves around.

    The call is thread safe.

    Declaration

    Objective-C

    - (void)addData:(NSArray *_Nonnull)dataObjects
        forTile:(MaplyTileID)tileID
          style:(MaplyQuadPagingDataStyle)dataStyle;

    Swift

    func addData(_ dataObjects: [Any], forTile tileID: MaplyTileID, style dataStyle: MaplyQuadPagingDataStyle)

    Parameters

    dataObjects

    An NSArray of MaplyComponentObject objects.
    tileID

    The tile ID for the data we’re handing over.
    dataStyle

    If set to MaplyDataStyleReplace the data at this level will replace data at lower levels. This is the default. If set to MaplyDataStyleAdd then the data at this level adds to data above and below this level.

  • Called from your MaplyPagingDelegate when a tile fails to load.

    If you fail to load your tile data in your MaplyPagingDelegate, you need to let the paging layer know with this call. Otherwise the paging layer assumes the tile is still loading.

    Declaration

    Objective-C

    - (void)tileFailedToLoad:(MaplyTileID)tileID;

    Swift

    func tileFailed(toLoad tileID: MaplyTileID)

  • Called from your MaplyPagingDelegate when a tile loads.

    When you’ve finished loading the data for a tile in your MaplyPagingDelegate, but before you’ve called addData:forTile: call this method to let the paging layer know you succeeded in loading the tile.

    Declaration

    Objective-C

    - (void)tileDidLoad:(MaplyTileID)tileID;

    Swift

    func tileDidLoad(_ tileID: MaplyTileID)

  • If you’re loading a number of parts of a tile from different sources, tell the layer about it.

    Rather than a single tileDidLoad: call, you can break it up into the number of parts you’re actually loading. This is convenient if you’re fetching data from multiple sources.

    Declaration

    Objective-C

    - (void)tile:(MaplyTileID)tileID hasNumParts:(int)numParts;

    Swift

    func tile(_ tileID: MaplyTileID, hasNumParts numParts: Int32)

  • If you’re loading your tile in parts, let the layer know which part just got loaded.

    If you’ve set the number of parts with tile:hasNumParts: this is how you let the layer know which parts you’ve loaded.

    Declaration

    Objective-C

    - (void)tileDidLoad:(MaplyTileID)tileID part:(int)whichPart;

    Swift

    func tileDidLoad(_ tileID: MaplyTileID, part whichPart: Int32)

  • Calculate the bounding box for a single tile in geographic.

    This is a utility method for calculating the extents of a given tile in geographic (e.g. lon/lat).

    Declaration

    Objective-C

    - (MaplyBoundingBox)geoBoundsForTile:(MaplyTileID)tileID;

    Swift

    func geoBounds(forTile tileID: MaplyTileID) -> MaplyBoundingBox

    Parameters

    tileID

    The ID for the tile we’re interested in.

    Return Value

    The lower left and upper right corner of the tile in geographic coordinates. Returns kMaplyNullBoundingBox in case of error

  • Calculate the bounding box for a single tile in geographic.

    This is a utility method for calculating the extents of a given tile in geographic (e.g. lon/lat).

    Declaration

    Objective-C

    - (void)geoBoundsforTile:(MaplyTileID)tileID
                      ll:(MaplyCoordinate *_Nonnull)ll
                      ur:(MaplyCoordinate *_Nonnull)ur;

    Swift

    func geoBoundsforTile(_ tileID: MaplyTileID, ll: UnsafeMutablePointer

    Parameters

    tileID

    The ID for the tile we’re interested in.
    ll

    The lower left corner of the tile in geographic coordinates.
    ur

    The upper right corner of the tile in geographic coordinates.

  • Calculate the bounding box for a single tile in geographic using doubles.

    This is a utility method for calculating the extents of a given tile in geographic (e.g. lon/lat).

    Declaration

    Objective-C

    - (MaplyBoundingBoxD)geoBoundsForTileD:(MaplyTileID)tileID;

    Swift

    func geoBounds(for tileID: MaplyTileID) -> MaplyBoundingBoxD

    Parameters

    tileID

    The ID for the tile we’re interested in.

    Return Value

    The lower left and upper right corner of the tile in geographic coordinates. Returns kMaplyNullBoundingBoxD in case of error

  • Calculate the bounding box for a single tile in geographic using doubles.

    This is a utility method for calculating the extents of a given tile in geographic (e.g. lon/lat).

    Declaration

    Objective-C

    - (void)geoBoundsForTileD:(MaplyTileID)tileID
                       ll:(MaplyCoordinateD *_Nonnull)ll
                       ur:(MaplyCoordinateD *_Nonnull)ur;

    Swift

    func geoBounds(for tileID: MaplyTileID, ll: UnsafeMutablePointer

    Parameters

    tileID

    The ID for the tile we’re interested in.
    ll

    The lower left corner of the tile in geographic coordinates.
    ur

    The upper right corner of the tile in geographic coordinates.

  • Calculate the bounding box for a single tile in the local coordinate system.

    This utility method calculates the bounding box for a tile in the coordinate system used for the layer.

    Declaration

    Objective-C

    - (MaplyBoundingBox)boundsForTile:(MaplyTileID)tileID;

    Swift

    func bounds(forTile tileID: MaplyTileID) -> MaplyBoundingBox

    Parameters

    tileID

    The ID for the tile we’re interested in.

    Return Value

    The lower left and upper right corner of the tile in geographic coordinates.

  • Calculate the bounding box for a single tile in the local coordinate system.

    This utility method calculates the bounding box for a tile in the coordinate system used for the layer.

    Declaration

    Objective-C

    - (void)boundsforTile:(MaplyTileID)tileID
                   ll:(MaplyCoordinate *_Nonnull)ll
                   ur:(MaplyCoordinate *_Nonnull)ur;

    Swift

    func boundsforTile(_ tileID: MaplyTileID, ll: UnsafeMutablePointer

    Parameters

    tileID

    The ID for the tile we’re interested in.
    ll

    The lower left corner of the tile in local coordinates.
    ur

    The upper right corner of the tile in local coordinates.

  • Return the center of the tile in display coordinates.

    Declaration

    Objective-C

    - (MaplyCoordinate3d)displayCenterForTile:(MaplyTileID)tileID;

    Swift

    func displayCenter(forTile tileID: MaplyTileID) -> MaplyCoordinate3d

    Parameters

    tileID

    The ID for the tile we’re interested in.

    Return Value

    Return the center in display space for the given tile.

  • Maximum number of tiles to load in at once.

    This is the maximum number of tiles the pager will have loaded into memory at once. The default is 256 and that’s generally good enough. However, if your tile size is small, you may want to load in more.

    Tile loading can get out of control when using elevation data. The toolkit calculates potential sceen coverage for each tile so elevation data makes all tiles more important. As a result the system will happily page in way more data than you may want. The limit becomes important in elevation mode, so leave it at 128 unless you need to change it.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) int maxTiles;

    Swift

    var maxTiles: Int32 { get set }

  • Set the minimum tile height (0.0 by default).

    When paging tiles containing 3D geometry it’s helpful to know the min and max height. This is the minimum height and defaults to 0.0.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) float minTileHeight;

    Swift

    var minTileHeight: Float { get set }

  • Set the maximum tile height (0.0 off by default)

    When paging tiles containing 3D geometry it’s helpful to know the min and max height. This is the maximum height and it defaults to 0.0. When min and max are the same, they are ignored.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) float maxTileHeight;

    Swift

    var maxTileHeight: Float { get set }

  • Reload the paging layer contents.

    This asks the paging layer to clean out its current data and reload everything from scratch.

    Declaration

    Objective-C

    - (void)reload;

    Swift

    func reload()

  • Request a reload of the paging layer within the given bounding box.

    Figures out which tiles overlap the given bounding box and asks for a refresh on those.

    Declaration

    Objective-C

    - (void)reload:(MaplyBoundingBox)bounds;

    Swift

    func reload(_ bounds: MaplyBoundingBox)

  • True if the layer is active. False if it’s been shut down.

    Declaration

    Objective-C

    @property (readonly, atomic) _Bool valid;

    Swift

    var valid: Bool { get }

  • Undocumented

    Declaration

    Objective-C

    @interface MaplyQuadPagingLayer : MaplyViewControllerLayer