Table of Contents

Class TileLayerCache

Namespace
LansMap.Core.TileCache

Least-recently-used map from packed tile keys to Texture2DArray layer indices, with a pinned set that eviction never takes. The pipeline uses this; most apps never call it.

public sealed class TileLayerCache
Inheritance
object
TileLayerCache

Remarks

Not thread-safe; call from the main thread. Zero allocation per frame after construction; Grow(int) allocates on that call only. TryGetLayer(long, out int) moves the key to most-recent; use Peek(long, out int) when sampling must not change eviction order.

Constructors

TileLayerCache(int)

Builds an empty cache of capacity layers.

public TileLayerCache(int capacity)

Parameters

capacity int

Layer count; must be positive.

Properties

Capacity

Layer count this cache was constructed or grown to.

public int Capacity { get; }

Property Value

int

PinnedKeyCount

Number of keys in the pinned set. May exceed Capacity.

public int PinnedKeyCount { get; }

Property Value

int

UsedLayers

Highest layer index that has ever been handed out, plus one.

public int UsedLayers { get; }

Property Value

int

Methods

FittingFloorPinZoom(int, int, int, int)

Deepest full-world floor that fits in capacity layers after leaving room for the visible footprint and reserve.

public static int FittingFloorPinZoom(int capacity, int reserve, int worstCaseFootprint, int requestedMaxZoom)

Parameters

capacity int

Texture array layer count.

reserve int

Layers the pin budget always keeps evictable.

worstCaseFootprint int

Worst-case visible footprint size, in tiles; used with capacity and reserve to leave room.

requestedMaxZoom int

Configured floor depth ceiling, integer tile zoom.

Returns

int

Integer tile zoom of the floor to pin, or -1 when not even zoom 0 fits. Never exceeds requestedMaxZoom.

FloorPinLayerRequirement(int, int, int)

Smallest layer capacity at which FittingFloorPinZoom(int, int, int, int) returns the full requested floor depth.

public static int FloorPinLayerRequirement(int pinMaxZoom, int reserve, int worstCaseFootprint)

Parameters

pinMaxZoom int

Requested floor depth, integer tile zoom; negative requests no floor.

reserve int

Layers the pin budget always keeps evictable.

worstCaseFootprint int

Worst-case visible footprint size, in tiles; used with floor tile count and reserve to size layer capacity.

Returns

int

Required layer count, or 0 when no floor is requested.

FloorTileCount(int)

Number of tiles in a full-world floor from zoom 0 through floorMaxZoom inclusive.

public static long FloorTileCount(int floorMaxZoom)

Parameters

floorMaxZoom int

Deepest integer tile zoom in the floor; negative means no floor and returns 0. Values above 30 throw rather than wrap.

Returns

long

Sum of 4^z for z in 0..floorMaxZoom, or 0 when the depth is negative.

Grow(int)

Extends capacity in place. Existing layer indices, keys, and LRU order do not move.

public void Grow(int newCapacity)

Parameters

newCapacity int

New layer count; must be strictly greater than Capacity.

Remarks

Shrinking is not supported. New slots are unused until TryInsert(long, out int, out long, out bool) hands them out, before any resident layer is evicted.

Insert(long)

Assigns a layer to key, evicting the least-recent unpinned layer when full.

public int Insert(long key)

Parameters

key long

Packed tile key.

Returns

int

Layer index assigned to the key.

Remarks

Throws when every layer is pinned. Prefer TryInsert(long, out int, out long, out bool) on the frame path.

Insert(long, out long, out bool)

Assigns a layer to key, reporting any eviction.

public int Insert(long key, out long evictedKey, out bool evicted)

Parameters

key long

Packed tile key.

evictedKey long

Packed key that left the cache when evicted is true.

evicted bool

True when an unpinned layer was taken to make room.

Returns

int

Layer index assigned to the key.

Remarks

Throws when every layer is pinned. Prefer TryInsert(long, out int, out long, out bool) on the frame path.

IsPinned(int)

True when layer is currently pinned against eviction.

public bool IsPinned(int layer)

Parameters

layer int

Layer index in 0 .. Capacity - 1.

Returns

bool

True when that layer's resident key is in the pinned set.

Peek(long, out int)

Looks up key without changing eviction order.

public bool Peek(long key, out int layer)

Parameters

key long

Packed tile key.

layer int

Layer index on success.

Returns

bool

True when the key is resident.

Remove(long)

Forgets key and returns its layer to the free pool.

public bool Remove(long key)

Parameters

key long

Packed tile key.

Returns

bool

True when the key was resident and the reservation was rolled back.

Remarks

Use this when TryInsert(long, out int, out long, out bool) reserved a layer and the GPU write then failed, so the cache does not serve uninitialized memory.

SetPinned(long[], int)

Replaces the pinned set. Applies to layers already cached and to keys inserted later while still pinned.

public void SetPinned(long[] newPinnedKeys, int count)

Parameters

newPinnedKeys long[]

Packed tile keys that eviction must not take.

count int

Number of keys at the front of newPinnedKeys to apply.

TryGetLayer(long, out int)

Looks up key and marks it most-recently used.

public bool TryGetLayer(long key, out int layer)

Parameters

key long

Packed tile key.

layer int

Layer index on success.

Returns

bool

True when the key is resident.

TryInsert(long, out int, out long, out bool)

Assigns a layer to key without throwing.

public bool TryInsert(long key, out int layer, out long evictedKey, out bool evicted)

Parameters

key long

Packed tile key.

layer int

Assigned layer index on success.

evictedKey long

Packed key that left the cache when evicted is true.

evicted bool

True when an unpinned layer was taken to make room.

Returns

bool

False when every layer is pinned, so this upload should be skipped.