Class MapsuiDatasetLayerSession

Namespace

EncDotNet.S100.Renderers.Mapsui

Assembly

EncDotNet.S100.Renderers.Mapsui.dll

Owns the ordinary lifecycle of processor-rendered dataset layers in a Mapsui map.

public sealed class MapsuiDatasetLayerSession : IDisposable

Inheritance

object

MapsuiDatasetLayerSession

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

The session owns generated layer replacement, removal, bottom-to-top order, dataset and sub-layer display state, S-98 cross-product ordering and suppression, whole-cell scale windows, and overlapping-cell suppression. Processor lifetime remains protected by the supplied DatasetProcessorOwner; every render uses a lease. Cross-product composition follows S-98 Edition 2.0.0 Main §9.2.1 and Annex A §8.4.1.

This is the innermost of three tiers, and the narrowest: it knows only about dataset layers. Above it, IS100MapSession composes this session with processor ownership, navigation, layer bands, and dynamic sources into the library's public entry point; above that, an application supplies its own host (e.g. the Viewer's MapsuiMapHost). Reach for this type directly only when you need dataset-layer lifecycle without the rest.

Rendering work runs on a worker thread. The continuation that installs layers must resume on the map-owning thread; UI hosts should call and await RenderAsync(MapDatasetId, MapPresentationState, CancellationToken) from that thread.

Constructors

MapsuiDatasetLayerSession(MapsuiLayerBands, DatasetProcessorOwner, MapsuiDatasetRenderer)

Creates a Mapsui dataset-layer session.

public MapsuiDatasetLayerSession(MapsuiLayerBands layerBands, DatasetProcessorOwner processorOwner, MapsuiDatasetRenderer renderer)

Parameters

layerBands MapsuiLayerBands

The map layer bands the session will mutate.

processorOwner DatasetProcessorOwner

The owner from which render leases are acquired.

renderer MapsuiDatasetRenderer

The processor-to-Mapsui renderer.

MapsuiDatasetLayerSession(MapsuiLayerBands, DatasetProcessorOwner, MapsuiDatasetRenderer, IInteroperabilityAuthorityProvider, Action?)

Creates a Mapsui dataset-layer session.

public MapsuiDatasetLayerSession(MapsuiLayerBands layerBands, DatasetProcessorOwner processorOwner, MapsuiDatasetRenderer renderer, IInteroperabilityAuthorityProvider authorityProvider, Action? redrawRequested = null)

Parameters

layerBands MapsuiLayerBands

The map layer bands the session will mutate.

processorOwner DatasetProcessorOwner

The owner from which render leases are acquired.

renderer MapsuiDatasetRenderer

The processor-to-Mapsui renderer.

authorityProvider IInteroperabilityAuthorityProvider

The runtime S-98 cross-product ordering and suppression authority.

redrawRequested Action

Optional per-session redraw action, invoked (possibly from a background thread) when a vector renderer publishes a settled cached / scene / tile image so the host can repaint the map. The session stamps it onto every dataset layer it installs. When null the renderers fall back to BaseLayer.DataHasChanged(). Typically invalidates the attached map (e.g. Map.RefreshGraphics()), optionally marshalled onto a UI thread.

Properties

Query

Reusable geographic query surface (feature / coverage picking) over the session's currently-shown datasets.

public IS100MapQuery Query { get; }

Property Value

IS100MapQuery

Methods

ClearLayers(MapDatasetId)

Removes generated layers while retaining dataset state and ordinary ordering for lazy reload.

public void ClearLayers(MapDatasetId datasetId)

Parameters

datasetId MapDatasetId

The dataset identity.

Dispose()

Removes every managed dataset layer and subscription.

public void Dispose()

GetDataset(MapDatasetId)

Gets a snapshot for one managed dataset.

public MapsuiMapDatasetSnapshot? GetDataset(MapDatasetId datasetId)

Parameters

datasetId MapDatasetId

The dataset identity.

Returns

MapsuiMapDatasetSnapshot

The snapshot, or null when unknown.

GetDatasets()

Gets all managed datasets in ordinary bottom-to-top paint order.

public IReadOnlyList<MapsuiMapDatasetSnapshot> GetDatasets()

Returns

IReadOnlyList<MapsuiMapDatasetSnapshot>

A materialized immutable snapshot.

GetLayerStackEntries()

Gets the complete S-98-ordered and suppression-applied layer stack, including entries from inactive datasets for inspection UI.

public IReadOnlyList<LayerStackEntry> GetLayerStackEntries()

Returns

IReadOnlyList<LayerStackEntry>

A materialized bottom-to-top snapshot.

GetStackedLayers()

Gets the active S-98-projected Mapsui dataset band.

public IReadOnlyList<ILayer> GetStackedLayers()

Returns

IReadOnlyList<ILayer>

A materialized bottom-to-top layer snapshot.

GetTimeSnapshot()

Gets the aggregate time state for all registered datasets.

public MapsuiMapTimeSnapshot GetTimeSnapshot()

Returns

MapsuiMapTimeSnapshot

An immutable materialized snapshot.

RefreshAsync(MapPresentationState, MRect?, CancellationToken)

Cancels the preceding full refresh and re-renders registered datasets while holding the render gate exclusively, preserving time gating.

public Task<bool> RefreshAsync(MapPresentationState presentation, MRect? viewport = null, CancellationToken cancellationToken = default)

Parameters

presentation MapPresentationState

The immutable map presentation used to construct product contexts.

viewport MRect

The current EPSG:3857 viewport, or null to re-portray every registered dataset (the legacy behaviour). When supplied, only cells whose extent intersects the viewport (grown by a margin) are re-portrayed now; off-view cells are marked stale and re-portrayed lazily by RefreshRevealedAsync(MRect, CancellationToken) when they scroll into view. This keeps a presentation change over a large exchange set proportional to the visible cell count rather than the loaded cell count.

cancellationToken CancellationToken

Cancels the requested refresh.

Returns

Task<bool>

A task that returns true when this refresh was applied, or false when a newer refresh superseded it.

RefreshDepthAdjustedAsync(MapPresentationState, MRect?, CancellationToken)

Applies presentation and re-renders only the datasets whose processor honours DepthAdjustment (IDepthAdjustableProcessor), for a change of the water level applied to charted depths. Cancels the preceding depth refresh. Off-view cells are deferred as RefreshAsync(MapPresentationState, MRect?, CancellationToken) defers them.

public Task<bool> RefreshDepthAdjustedAsync(MapPresentationState presentation, MRect? viewport = null, CancellationToken cancellationToken = default)

Parameters

presentation MapPresentationState

The presentation carrying the new adjustment.

viewport MRect

The current EPSG:3857 viewport, or null to re-render every such dataset.

cancellationToken CancellationToken

Cancels the requested refresh.

Returns

Task<bool>

true when this refresh was applied, or false when a newer depth refresh superseded it.

RefreshRevealedAsync(MRect, CancellationToken)

Re-portrays the cells that a prior viewport-gated RefreshAsync(MapPresentationState, MRect?, CancellationToken) deferred as off-view (EncDotNet.S100.Renderers.Mapsui.MapsuiDatasetLayerSession.Entry.NeedsRefresh) and that now intersect viewport, using the most recently applied presentation. A no-op when no presentation has been applied yet or no stale cell is in view. Intended to be driven (debounced) from the host's viewport-changed signal so a deferred cell refreshes as it scrolls in.

public Task<bool> RefreshRevealedAsync(MRect viewport, CancellationToken cancellationToken = default)

Parameters

viewport MRect

The current EPSG:3857 viewport.

cancellationToken CancellationToken

Cancels the requested refresh.

Returns

Task<bool>

true when the pass ran to completion, or false when it was cancelled/superseded.

RefreshTimeAsync(MapPresentationState, CancellationToken)

Coalesces rapid clock changes, cancels the preceding time refresh, and applies product-specific time gating while holding the render gate exclusively.

public Task RefreshTimeAsync(MapPresentationState presentation, CancellationToken cancellationToken = default)

Parameters

presentation MapPresentationState

The immutable map presentation used to construct product contexts.

cancellationToken CancellationToken

Cancels the requested refresh.

Returns

Task

A task that completes when the applied refresh finishes.

RemoveDataset(MapDatasetId, bool, bool)

Removes a dataset's generated layers and optionally its retained state.

public bool RemoveDataset(MapDatasetId datasetId, bool preserveState = false, bool removeProcessor = true)

Parameters

datasetId MapDatasetId

The dataset identity.

preserveState bool

Whether to retain renderer-neutral state and its order slot for a future lazy reload.

removeProcessor bool

Whether to retire the corresponding processor from the supplied owner.

Returns

bool

true when managed state existed.

RemoveDatasets(IReadOnlyCollection<MapDatasetId>, bool, bool)

Removes several datasets' generated layers, and optionally their retained state, recomposing the layer stack and the time state once for the whole set rather than once per dataset. Removing many cells at once (a lazy-load eviction pass) otherwise rebuilds the full S-98 stack for each of them.

public int RemoveDatasets(IReadOnlyCollection<MapDatasetId> datasetIds, bool preserveState = false, bool removeProcessor = true)

Parameters

datasetIds IReadOnlyCollection<MapDatasetId>

The dataset identities; unknown ones are skipped.

preserveState bool

Whether to retain renderer-neutral state and order slots for a future lazy reload.

removeProcessor bool

Whether to retire the corresponding processors from the supplied owner.

Returns

int

The number of datasets that had managed state.

Remarks

All or nothing: when recomposition fails, every dataset is restored and the exception propagates.

RenderAsync(MapDatasetId, MapPresentationState, CancellationToken)

Renders a registered processor through a safe lease and atomically replaces its generated layers.

public Task<MapsuiDatasetResult?> RenderAsync(MapDatasetId datasetId, MapPresentationState presentation, CancellationToken cancellationToken = default)

Parameters

datasetId MapDatasetId

The dataset identity.

presentation MapPresentationState

The immutable map presentation used to construct the product context.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<MapsuiDatasetResult>

The installed result, or null when the dataset was removed or its processor changed while rendering.

SetCurrentTime(DateTime)

Updates the global map clock without rendering. Hosts should then call RefreshTimeAsync(MapPresentationState, CancellationToken) to apply the new time to dataset layers. The clock is not clamped to the loaded range: it can sit in a gap or past all data (a live timeline after every forecast has ended), where each dataset's time policy hides it (#713).

public void SetCurrentTime(DateTime time)

Parameters

time DateTime

Requested global clock value; ignored while no dataset has time samples.

SetDataset(MapDataset, int?, int?)

Adds or updates renderer-neutral state for a dataset.

public void SetDataset(MapDataset dataset, int? minimumDisplayScale = null, int? maximumDisplayScale = null)

Parameters

dataset MapDataset

The authoritative host state.

minimumDisplayScale int?

Optional catalogue coarsest display-scale denominator.

maximumDisplayScale int?

Optional catalogue compilation-scale denominator.

SetIgnoreScaleMinimum(bool)

Enables or disables whole-cell scale minima and overlap suppression.

public void SetIgnoreScaleMinimum(bool ignoreScaleMinimum)

Parameters

ignoreScaleMinimum bool

true to ignore minimum-display-scale windows.

SetMarinerSettings(MarinerSettings)

Sets the mariner choices consumed by S-98 cross-product rules and dataset scale-window projection.

public void SetMarinerSettings(MarinerSettings mariner)

Parameters

mariner MarinerSettings

The current immutable mariner settings.

SetOrder(IReadOnlyList<MapDatasetId>)

Replaces ordinary dataset order.

public void SetOrder(IReadOnlyList<MapDatasetId> datasetIds)

Parameters

datasetIds IReadOnlyList<MapDatasetId>

Dataset identities in bottom-to-top paint order. Managed identities not supplied are retained after the supplied sequence.

Events

CurrentTimeChanged

Raised after the global map clock changes.

public event EventHandler<MapSessionCurrentTimeEventArgs>? CurrentTimeChanged

Event Type

EventHandler<MapSessionCurrentTimeEventArgs>

DatasetRenderCompleted

Raised after a successful render installs a registered dataset's generated layers. Not raised when the render throws, is cancelled, or is superseded/removed mid-flight — those leave a DatasetRenderStarted with no matching completion (a swallowed refresh failure instead raises DatasetRenderFailed).

public event EventHandler<MapSessionDatasetRenderEventArgs>? DatasetRenderCompleted

Event Type

EventHandler<MapSessionDatasetRenderEventArgs>

DatasetRenderFailed

Raised when one dataset fails during a coalesced time or presentation refresh. Other registered datasets continue refreshing. A single RenderAsync(MapDatasetId, MapPresentationState, CancellationToken) surfaces its error by throwing instead.

public event EventHandler<MapSessionDatasetRenderFailedEventArgs>? DatasetRenderFailed

Event Type

EventHandler<MapSessionDatasetRenderFailedEventArgs>

DatasetRenderStarted

Raised once a processor lease is held and a registered dataset is about to render, for single renders and each dataset of a coalesced refresh. A dataset removed or unregistered before its lease is acquired raises no lifecycle event.

public event EventHandler<MapSessionDatasetRenderEventArgs>? DatasetRenderStarted

Event Type

EventHandler<MapSessionDatasetRenderEventArgs>

LayersChanged

Raised after the final dataset-band projection changes.

public event EventHandler? LayersChanged

Event Type

EventHandler

TimeRangeChanged

Raised after the aggregate registered time range changes.

public event EventHandler? TimeRangeChanged

Event Type

EventHandler