Class RealmFrame

Namespace

Typhon.Protocol

Assembly

Typhon.Protocol.dll

The realm a session's positions are framed in (typhon.3, 12-realms § 5.2): what the REALM block carries, and what every realm-framed codec — pos2, pos3, the AGG grid — is quantized over and decoded with (SUB-30).

public sealed class RealmFrame : IEquatable<RealmFrame>

Inheritance

object

RealmFrame

Implements

IEquatable<RealmFrame>

Inherited Members

object.GetType()

object.ToString()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Remarks

REALM := u16 realmId | u16 generation | u8 flags [unless NONE: varu kindIdx | u32 appTag | u8 posBits | f64 cellM | f64 min[3] | f64 max[3]]. Always three axes: a flat realm has Deep clear and a pos2 uses axes 0 and 1.

Immutable: a decoded frame can be cached by (realmId, generation) and shared by every session in the realm.

Constructors

RealmFrame(ushort, ushort, int, uint, int, double, bool, ReadOnlySpan<double>, ReadOnlySpan<double>)

Builds a frame, validating it exactly as a decoder would.

public RealmFrame(ushort realmId, ushort generation, int kindIdx, uint appTag, int positionBits, double cellM, bool deep, ReadOnlySpan<double> min, ReadOnlySpan<double> max)

Parameters

realmId ushort

The realm.

generation ushort

The realm catalog's generation of that id.

kindIdx int

The realm kind's index in the catalog's realmKinds.

appTag uint

Opaque to the engine; the client picks its scene by it.

positionBits int

16, 24 or 32.

cellM double

The realm's replication cell, in metres.

deep bool

Whether the realm has a third axis.

min ReadOnlySpan<double>

Three lower bounds.

max ReadOnlySpan<double>

Three upper bounds.

Exceptions

ArgumentException

A value a decoder refuses (§ 5.2).

Fields

CommandPositionBits

Bits per axis of a realm-framed field a CLIENT sends (COMMANDS): always 32, whatever the realm's own width, because the transport parses a command without reading the session's realm (SUB-05) and so cannot know that width.

public const int CommandPositionBits = 32

Field Value

int

FlagDeep

Flags bit 1: the realm is three-dimensional.

public const byte FlagDeep = 2

Field Value

byte

FlagNone

Flags bit 0: the session is in no realm; nothing follows the flags.

public const byte FlagNone = 1

Field Value

byte

NoRealm

The realm id a REALM(NONE) carries.

public const ushort NoRealm = 65535

Field Value

ushort

Properties

AppTag

The application's tag for the realm, opaque to the engine.

public uint AppTag { get; }

Property Value

uint

CellM

The realm's replication cell side, in metres; an AGG tile is tileCells of them.

public double CellM { get; }

Property Value

double

Deep

Whether the realm is three-dimensional.

public bool Deep { get; }

Property Value

bool

ForCommands

This frame at CommandPositionBits: what a COMMANDS message's realm-framed fields are encoded and decoded over — the realm's bounds, at a width the transport knows without reading the realm.

public RealmFrame ForCommands { get; }

Property Value

RealmFrame

Generation

The realm catalog's generation of RealmId: a reused id is a new realm.

public ushort Generation { get; }

Property Value

ushort

KindIdx

The realm kind's index in the catalog's realmKinds.

public int KindIdx { get; }

Property Value

int

Max

The upper bounds, three axes.

public ReadOnlySpan<double> Max { get; }

Property Value

ReadOnlySpan<double>

Min

The lower bounds, three axes.

public ReadOnlySpan<double> Min { get; }

Property Value

ReadOnlySpan<double>

PositionBits

Bits per position axis: 16, 24 or 32.

public int PositionBits { get; }

Property Value

int

PositionBytes

Bytes per position axis.

public int PositionBytes { get; }

Property Value

int

RealmId

The realm.

public ushort RealmId { get; }

Property Value

ushort

Step

The position quantum per axis at PositionBits, exactly as QuantStep(double, double, int) computes it.

public ReadOnlySpan<double> Step { get; }

Property Value

ReadOnlySpan<double>

Methods

AggregateCellCount(int)

An AGG grid's cell count over all three axes, or MaxValue when it overflows.

public long AggregateCellCount(int tileCells)

Parameters

tileCells int

Returns

long

AggregateDim(int, int)

An AGG grid's cell count on axis: ⌈(max − min) / (tileCells · cellM)⌉, and 1 on axis 2 of a flat realm.

public int AggregateDim(int axis, int tileCells)

Parameters

axis int

0, 1 or 2.

tileCells int

The grid's tile, in replication cells.

Returns

int

The cell count, at least 1.

Equals(object)

public override bool Equals(object obj)

Parameters

obj object

Returns

bool

Equals(RealmFrame)

public bool Equals(RealmFrame other)

Parameters

other RealmFrame

Returns

bool

GetHashCode()

public override int GetHashCode()

Returns

int

Read(ref WireReader, int)

Decodes a REALM block's content.

public static RealmFrame Read(ref WireReader reader, int realmKindCount)

Parameters

reader WireReader

The block's reader.

realmKindCount int

How many kinds the catalog declares; a kindIdx at or past it is refused.

Returns

RealmFrame

The frame, or null for REALM(NONE).

Exceptions

WireFormatException

A value § 5.2 refuses (1007).

Write(ref WireWriter)

Encodes this frame as a REALM block's content.

public void Write(ref WireWriter writer)

Parameters

writer WireWriter

WriteNone(ref WireWriter)

Encodes REALM(NONE): the session is in no realm.

public static void WriteNone(ref WireWriter writer)

Parameters

writer WireWriter