Table of Contents

Class EgamiContext

Namespace
Egami
Assembly
Egami.dll

Every setting that is not specific to one call: where memory comes from, how many threads an operation may use, and the safety limits. Contexts are immutable and safe to share. Change one with a with expression.

public sealed record EgamiContext : IEquatable<EgamiContext>
Inheritance
EgamiContext
Implements
Inherited Members
Extension Methods

Examples

var context = EgamiContext.Default with
{
    Limits = SafetyLimits.Default with { MaxPixels = 100_000_000 },
    MaxParallelism = 4,
};

Properties

Default

Gets the context used when a call passes none. The first read fixes it: SetDefault(EgamiContext) works only before that.

public static EgamiContext Default { get; }

Property Value

EgamiContext

DiagnosticLevel

Gets the lowest level Diagnostics receives. Defaults to Warning; events below it are never built.

public DiagnosticLevel DiagnosticLevel { get; init; }

Property Value

DiagnosticLevel

Exceptions

ArgumentOutOfRangeException

The value set is not a defined level.

Diagnostics

Gets the handler that receives Egami's warnings and notable decisions, or null (the default) for none, which costs nothing. It runs inline, possibly on several decode threads at once, so it must be quick and thread-safe. An exception it throws fails the call, which turns warnings into errors. Warnings a load raises arrive in Warnings order as the call ends; Info and Debug events arrive as they happen. One id is delivered at most 10 times per call, then once more as a count of the rest.

public Action<EgamiDiagnostic>? Diagnostics { get; init; }

Property Value

Action<EgamiDiagnostic>

Examples

// With Microsoft.Extensions.Logging: one line at startup sends every call's warnings to the app's log, with the id as
// a property to filter and count on. Egami itself has no logging dependency.
EgamiContext.SetDefault(new EgamiContext
{
    Diagnostics = d => logger.Log(d.Level.ToLogLevel(), "{Source} {Id} at {Offset}: {Message}", d.Source, d.Id, d.Offset, d.Message),
});

Formats

Gets the registered formats, in detection order. Defaults to PNG, JPEG, GIF, WebP, BMP, QOI, PNM, TIFF, JBIG2, JPEG 2000 and TGA.

public IReadOnlyList<FormatInfo> Formats { get; init; }

Property Value

IReadOnlyList<FormatInfo>

Limits

Gets the safety limits applied when reading. Defaults to Default.

public SafetyLimits Limits { get; init; }

Property Value

SafetyLimits

Exceptions

ArgumentNullException

The value set is null.

MaxParallelism

Gets the most threads one operation may use. 1 means fully sequential. Defaults to the processor count.

public int MaxParallelism { get; init; }

Property Value

int

Exceptions

ArgumentOutOfRangeException

The value set is less than 1.

Memory

Gets the source of all pixel memory. Defaults to Shared.

public IPixelMemorySource Memory { get; init; }

Property Value

IPixelMemorySource

Exceptions

ArgumentNullException

The value set is null.

Methods

SetDefault(EgamiContext)

Replaces Default, once, at startup, so that format plugins, memory sources and limits apply to every call that passes no context.

public static void SetDefault(EgamiContext context)

Parameters

context EgamiContext

The context to use as the default.

Exceptions

InvalidOperationException

Default was already read or set.

StartDiagnostics()

Starts reporting for one call outside Egami's own loads and saves, such as a video decode or a plug-in's own entry point, with the same DiagnosticLevel filter and per-id cap. Dispose it when the call ends.

public DiagnosticReporter StartDiagnostics()

Returns

DiagnosticReporter

A reporter for the call; a shared one that does nothing when Diagnostics is null.

Examples

// A decoder outside Egami (a video demuxer, a format plug-in's own entry point) reports through the same handler, with the
// same level filter and the same cap of 10 per id per call. Dispose the reporter when the call ends.
using (DiagnosticReporter diagnostics = context.StartDiagnostics())
{
    if (diagnostics.IsEnabled(DiagnosticLevel.Warning))
    {
        diagnostics.Report(DiagnosticLevel.Warning, "Avi.IndexRebuilt", "The index was missing; it was rebuilt from the frames.", offset: 4096);
    }

    diagnostics.Report(DiagnosticLevel.Info, "Mjpeg.DhtInserted", "Frames have no Huffman tables; the standard ones were used.");
}

WithFormat(FormatInfo)

Returns a copy of this context with format registered. A format with the same name is replaced in place; otherwise the new format is detected last.

public EgamiContext WithFormat(FormatInfo format)

Parameters

format FormatInfo

The format to add.

Returns

EgamiContext

The new context.

Edit this page