Table of Contents

Class MarkerLabelLayer

Namespace
LansMap.Markers.Labels

Renders text labels for markers.

public sealed class MarkerLabelLayer : IDisposable
Inheritance
object
MarkerLabelLayer
Implements

Constructors

MarkerLabelLayer(MarkerStore, Font)

Creates a label layer over store. Pass a font or the built-in LegacyRuntime face is used.

public MarkerLabelLayer(MarkerStore store, Font customFont = null)

Parameters

store MarkerStore

Marker store whose ids the captions attach to.

customFont Font

Optional Unity Font; null uses LegacyRuntime.ttf.

Fields

Anchor

Where the caption sits relative to the marker: above the marker size, or centered on the anchor.

public LabelAnchor Anchor

Field Value

LabelAnchor

FontSizePx

Base caption size in screen px; variants scale off this.

public int FontSizePx

Field Value

int

HaloColor

Halo/outline color for readability over busy tiles; alpha 0 disables.

public Color HaloColor

Field Value

Color

HaloWidthPx

Halo/outline width in screen px.

public float HaloWidthPx

Field Value

float

LabelFadeSeconds

Seconds to ramp opacity toward a collision win or loss. 0 (default) jumps instantly.

public double LabelFadeSeconds

Field Value

double

LastAboveGapPxForTests

Last placed Above-anchor label's screen-px gap above its marker, for tests.

public float LastAboveGapPxForTests

Field Value

float

LastAnchorOriginForTests

Last placed label's anchor origin in screen px, for tests.

public Vector2 LastAnchorOriginForTests

Field Value

Vector2

MaxPerspectiveRatio

Culls labels whose perspective w exceeds this ratio of the view center's. 0 disables (flat-marker default).

public double MaxPerspectiveRatio

Field Value

double

MaxVisibleLabels

Maximum labels drawn after declutter, count.

public int MaxVisibleLabels

Field Value

int

NowOverrideForTests

Optional clock in seconds since startup; tests set this, production leaves it null.

public double? NowOverrideForTests

Field Value

double?

OrderMode

Declutter winner policy: Priority keeps rank order, NearestToCenter favors the view center.

public LabelOrderMode OrderMode

Field Value

LabelOrderMode

UseSdf

When true (default), glyphs bake into a distance-field atlas. False uses the legacy bitmap path.

public bool UseSdf

Field Value

bool

Visible

When false, this layer is not drawn. Clustering hides labels together with their markers.

public bool Visible

Field Value

bool

Properties

LabelColor

Caption fill color.

public Color32 LabelColor { get; set; }

Property Value

Color32

LabelCount

Labels currently held, for leak gates.

public int LabelCount { get; }

Property Value

int

LabelFont

Unity Font asset (imported TTF/OTF or Font.CreateDynamicFontFromOSFont). Takes effect next rebuild.

public Font LabelFont { get; set; }

Property Value

Font

LastRebuildProjectionCount

How many labeled markers the most recent Rebuild(MapViewTransform) projected, for diagnostics.

public int LastRebuildProjectionCount { get; }

Property Value

int

NeedsRebuild

True when labels, font, size, or a fade animation require Rebuild(MapViewTransform) even on a static view.

public bool NeedsRebuild { get; }

Property Value

bool

SdfSnapValueForTests

SDF material snap-gate value for tests, or -1 when SDF is off.

public float SdfSnapValueForTests { get; }

Property Value

float

VisibleGlyphCount

Glyph instances submitted by the last Rebuild(MapViewTransform).

public int VisibleGlyphCount { get; }

Property Value

int

Methods

ClearLabels()

Drops every caption. Call this when freeing all markers; ids are not reused, so leftover entries grow without bound.

public void ClearLabels()

Dispose()

Releases GPU buffers, font-rebuild subscription, and both materials.

public void Dispose()

FillCommandBuffer(CommandBuffer)

Records the prepared label draw into cb. The glyph buffer binds through a per-draw property block: command buffers do not snapshot material buffer state.

public void FillCommandBuffer(CommandBuffer cb)

Parameters

cb CommandBuffer

Command buffer already bound to the camera target.

NotifyMarkerMoved(int)

Marks a labeled marker's projected position stale after a move that did not go through add/remove/style.

public void NotifyMarkerMoved(int markerId)

Parameters

markerId int

MarkerStore id (slot plus generation), not a slot index.

Remarks

Rebuild only runs on view change or NeedsRebuild. A marker dragged under a still camera is neither, so the mover must call this. Unlabeled markers are a no-op.

PrepareDraw(MapViewTransform)

Rebuilds dirty glyphs and stashes uniforms for view. Call from the game thread before FillCommandBuffer(CommandBuffer).

public void PrepareDraw(MapViewTransform view)

Parameters

view MapViewTransform

Current map view.

Rebuild(MapViewTransform)

Runs collision and rebuilds the glyph buffer. Call when the view moved meaningfully or NeedsRebuild is true.

public void Rebuild(MapViewTransform view)

Parameters

view MapViewTransform

Current map view.

RemoveLabel(int)

Removes the caption for markerId if one is held.

public void RemoveLabel(int markerId)

Parameters

markerId int

MarkerStore id (slot plus generation), not a slot index.

Render(MapViewTransform)

Draws visible glyphs for this view. Call Rebuild(MapViewTransform) first when NeedsRebuild is true.

public void Render(MapViewTransform view)

Parameters

view MapViewTransform

Current map view.

SetFontSize(int)

Sets FontSizePx in screen px. Values below 6 are ignored.

public void SetFontSize(int px)

Parameters

px int

New base size in screen px.

SetLabel(int, string, LabelVariant, int, LabelWeight?)

Attaches or replaces the caption on a marker, sized from FontSizePx and variant.

public void SetLabel(int markerId, string text, LabelVariant variant = LabelVariant.Body, int priority = -2147483648, LabelWeight? weight = null)

Parameters

markerId int

MarkerStore id (slot plus generation), not a slot index.

text string

Caption to draw.

variant LabelVariant

Scale relative to the layer base size (h1 = 2x through body = 1x).

priority int

Lower wins declutter; omit for insertion order.

weight LabelWeight?

Optional weight; headings default bold, body normal.

Remarks

Convert a picker or loop index with MarkerStore.HandleOf first. Passing a slot index looks up the wrong occupant after reuse.

SetLabelCustomSize(int, string, int, LabelWeight)

Attaches or replaces the caption at an exact size in screen px, ignoring FontSizePx and variants.

public void SetLabelCustomSize(int markerId, string text, int sizePx, LabelWeight weight = LabelWeight.Normal)

Parameters

markerId int

MarkerStore id (slot plus generation), not a slot index.

text string

Caption to draw.

sizePx int

Glyph size in screen px.

weight LabelWeight

Glyph weight; bitmap fallback ignores this.

SetLabelStyle(int, Color32?, Color?)

Sets or clears per-marker text and halo color overrides for an existing caption.

public bool SetLabelStyle(int markerId, Color32? textColor, Color? haloColor)

Parameters

markerId int

MarkerStore id (slot plus generation), not a slot index.

textColor Color32?

Per-marker text color, or null to inherit LabelColor.

haloColor Color?

Per-marker halo color, or null to inherit HaloColor. Alpha 0 disables the halo for this marker only.

Returns

bool

False when no caption exists for markerId; the call is then a no-op.

Remarks

Null-means-inherit matches WorldMarkerInstance.CaptionTextColorOverride's convention on the 3D marker tier. Style survives SetLabel re-labeling the same as priority does.

StepFade(float, float, float, float)

Linear opacity ramp toward target at 1/fadeSeconds per second.

public static float StepFade(float current, float target, float dt, float fadeSeconds)

Parameters

current float

Current opacity, 0..1.

target float

Target opacity, 0 or 1.

dt float

Elapsed time in seconds. Values <= 0 leave current unchanged.

fadeSeconds float

Ramp duration in seconds.

Returns

float

Next opacity, 0..1, snapped to target within 1e-4.

TryGetLabel(int, out string)

Reads the caption currently held for markerId.

public bool TryGetLabel(int markerId, out string text)

Parameters

markerId int

MarkerStore id (slot plus generation), not a slot index.

text string

Caption text when found, otherwise the default string.

Returns

bool

True when this layer holds a caption for that id.