Table of Contents

Class GmlPortrayalCatalogueBase

Namespace
EncDotNet.S100.Portrayals
Assembly
EncDotNet.S100.Portrayals.dll

Base class for XSLT-based GML portrayal catalogues. Provides all the shared infrastructure — palette loading, rule discovery, XSLT compilation with caching, symbol/line-style/area-fill asset loading, and the XML resolver for xsl:include resolution.

public abstract class GmlPortrayalCatalogueBase : IVectorPortrayalCatalogue, IPortrayalCatalogue, IXsltRuleSource, ILuaRuleSource, IPortrayalAssetSource
Inheritance
GmlPortrayalCatalogueBase
Implements
Derived
Inherited Members

Remarks

Subclasses typically only need to supply Spec and, where necessary, override CreateXmlResolver(IReadOnlyDictionary<string, byte[]>) (for specs whose XSLT includes reference unregistered sub-templates) or GetCompiledRuleAsync(string, CancellationToken) (for specs that inject an adapter rule).

Constructors

GmlPortrayalCatalogueBase(PortrayalCatalogueProvider)

Initializes a new GmlPortrayalCatalogueBase backed by the given provider.

protected GmlPortrayalCatalogueBase(PortrayalCatalogueProvider provider)

Parameters

provider PortrayalCatalogueProvider

Properties

ActivePalette

Gets the currently active color palette.

public ColorPalette ActivePalette { get; }

Property Value

ColorPalette

CatalogueRef

The identity (name + version) of the underlying portrayal catalogue XML, when populated. Used to surface mismatches between the dataset's declared Spec edition and the catalogue version actually resolved for it.

public CatalogueRef? CatalogueRef { get; }

Property Value

CatalogueRef?

ContextParameters

GML portrayal catalogues declare no Lua context parameters.

public IReadOnlyList<LuaContextParameter> ContextParameters { get; }

Property Value

IReadOnlyList<LuaContextParameter>

DisplayModes

Tracks the active S-100 Part 9 §11.7 display mode.

public DisplayModeController DisplayModes { get; }

Property Value

DisplayModeController

DisplayPlanes

Controls which S-100 Part 9 §11.6 display planes are visible.

public DisplayPlaneController DisplayPlanes { get; }

Property Value

DisplayPlaneController

Edition

Gets the edition of the portrayal catalogue.

public string Edition { get; }

Property Value

string

Provider

Gets the underlying portrayal catalogue provider.

protected PortrayalCatalogueProvider Provider { get; }

Property Value

PortrayalCatalogueProvider

Rules

Gets the ordered list of portrayal rules.

public IReadOnlyList<PortrayalRule> Rules { get; }

Property Value

IReadOnlyList<PortrayalRule>

Spec

The product specification (name + edition) this catalogue targets.

public abstract SpecRef Spec { get; }

Property Value

SpecRef

ViewingGroups

Gets the controller for viewing group visibility.

public ViewingGroupController ViewingGroups { get; }

Property Value

ViewingGroupController

Methods

BuildRules()

Builds the list of portrayal rules from the catalogue's rule files. Override to change rule selection (e.g. restrict to a single named rule).

protected virtual IReadOnlyList<PortrayalRule> BuildRules()

Returns

IReadOnlyList<PortrayalRule>

CacheCompiledRule(string, XslCompiledTransform)

Caches a compiled transform under the given rule name. Useful for subclasses that load adapter rules from embedded resources.

protected void CacheCompiledRule(string ruleName, XslCompiledTransform transform)

Parameters

ruleName string
transform XslCompiledTransform

CreateXmlResolver(IReadOnlyDictionary<string, byte[]>)

Creates an XmlResolver used to resolve xsl:include/xsl:import URIs during XSLT compilation.

protected virtual XmlResolver CreateXmlResolver(IReadOnlyDictionary<string, byte[]> registeredBytes)

Parameters

registeredBytes IReadOnlyDictionary<string, byte[]>

Returns

XmlResolver

Remarks

The default implementation resolves filenames against the pre-fetched rule-file bytes dictionary. Override to add fallback resolution strategies (e.g. FetchRuleAsync(string, CancellationToken) for specs whose sub-templates are not registered as rule files).

GetAreaFillAsync(string, CancellationToken)

Returns the area fill with the given name, loading and caching it on first access.

public ValueTask<AreaFill> GetAreaFillAsync(string name, CancellationToken cancellationToken = default)

Parameters

name string
cancellationToken CancellationToken

Returns

ValueTask<AreaFill>

Exceptions

PortrayalAssetNotFoundException

No such area fill in the catalogue.

GetCompiledRuleAsync(string, CancellationToken)

Returns the compiled XSLT transform for the given rule name, loading and caching it on first access. Override to intercept specific rules (e.g. inject an adapter transform).

public virtual ValueTask<XslCompiledTransform> GetCompiledRuleAsync(string ruleName, CancellationToken cancellationToken = default)

Parameters

ruleName string

The rule identifier.

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<XslCompiledTransform>

The compiled XSLT transform.

Exceptions

PortrayalAssetNotFoundException

No such rule in the catalogue.

GetLineStyleAsync(string, CancellationToken)

Returns the line style with the given name, loading and caching it on first access.

public ValueTask<LineStyle> GetLineStyleAsync(string name, CancellationToken cancellationToken = default)

Parameters

name string
cancellationToken CancellationToken

Returns

ValueTask<LineStyle>

Exceptions

PortrayalAssetNotFoundException

No such line style in the catalogue.

GetLuaSourceAsync(string, CancellationToken)

GML portrayal catalogues ship no Lua rules, so this always returns null (honouring the module loader's "missing module → null" contract).

public ValueTask<string?> GetLuaSourceAsync(string fileName, CancellationToken cancellationToken = default)

Parameters

fileName string
cancellationToken CancellationToken

Returns

ValueTask<string>

GetLuaSourceNamesAsync(CancellationToken)

GML portrayal catalogues use XSLT only and ship no Lua rules, so this always returns an empty list.

public ValueTask<IReadOnlyList<string>> GetLuaSourceNamesAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

ValueTask<IReadOnlyList<string>>

GetSymbolAsync(string, CancellationToken)

Returns the SVG symbol with the given name, loading and caching it on first access.

public ValueTask<SvgSymbol> GetSymbolAsync(string symbolName, CancellationToken cancellationToken = default)

Parameters

symbolName string
cancellationToken CancellationToken

Returns

ValueTask<SvgSymbol>

Exceptions

PortrayalAssetNotFoundException

No such symbol in the catalogue.

LoadAdapterXsltAsync(Stream, string, CancellationToken)

Compiles an adapter stylesheet that is not part of the catalogue against the catalogue's rule files, so the adapter can xsl:import or xsl:include them by file name (for example <xsl:import href="main.xsl"/>). Lets a subclass wrap an upstream rule without editing the bundled catalogue.

protected Task<XslCompiledTransform> LoadAdapterXsltAsync(Stream adapter, string adapterFileName, CancellationToken cancellationToken)

Parameters

adapter Stream

The adapter stylesheet.

adapterFileName string

The adapter's file name, used as its base URI; it must not collide with a catalogue rule file name.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<XslCompiledTransform>

The compiled adapter.

LoadPalettesAsync(Dictionary<PaletteType, ColorPalette>, CancellationToken)

Loads colour palettes from the catalogue's colour profiles. Override to change the palette loading strategy (e.g. skip the multi-palette-in-one-file fallback for specs that don't use it).

protected virtual Task LoadPalettesAsync(Dictionary<PaletteType, ColorPalette> palettes, CancellationToken cancellationToken)

Parameters

palettes Dictionary<PaletteType, ColorPalette>
cancellationToken CancellationToken

Returns

Task

LoadXsltRuleAsync(RuleFile, CancellationToken)

Loads and compiles an XSLT rule file with telemetry.

protected Task<XslCompiledTransform> LoadXsltRuleAsync(RuleFile ruleFile, CancellationToken cancellationToken)

Parameters

ruleFile RuleFile
cancellationToken CancellationToken

Returns

Task<XslCompiledTransform>

Remarks

Pre-fetches every registered rule file's bytes into a memory dict before invoking Load(XmlReader, XsltSettings, XmlResolver), because GetEntity(Uri, string, Type) is a synchronous .NET API contract during XSLT compile and we cannot await inside it. The pre-fetch is bounded to the (small) set of declared rule files; GmlPortrayalCatalogueBase.FetchRuleFallbackXmlResolver handles the unregistered-include case via a documented sync bridge.

SwitchPaletteAsync(PaletteType, CancellationToken)

Switches the active colour palette to type.

public ValueTask SwitchPaletteAsync(PaletteType type, CancellationToken cancellationToken = default)

Parameters

type PaletteType

The palette mood (Day, Dusk, or Night).

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask

Remarks

Asynchronous because catalogues that load palettes lazily from IAssetSource may need to fetch the colour profile XML on first access. Cached implementations complete synchronously through the ValueTask fast path. When the catalogue has no palette for type, implementations keep a usable palette active (the current one, or Day) rather than failing. Coverage catalogues also use this call to pre-load the assets their synchronous resolve methods need, so it must be awaited before those are called (see SwitchPaletteAsync(PaletteType, CancellationToken)).

Edit this page