Struct CellMask

Assigns every cell in a region a value between 0 and 1 describing how early the effect reaches it.

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Scylla.TextMode

Assembly: ScyllaTextMode.dll

Syntax

public readonly struct CellMask

Remarks

This is the piece that makes one effect produce many looks. A reveal uses the ordering to stagger its cells, so the same fade becomes a sweep, a sparkle or a burn depending only on the mask. A transition uses it as a threshold, swapping each cell to the new content as progress passes that cell's value, which is what turns one effect into wipes, irises, blinds and dissolves.

Values are always normalized after generation, so the earliest cell is exactly 0 and the latest exactly 1. That is what guarantees an effect both starts moving immediately and actually finishes, whatever shape the pattern produced.

Build one with the static helpers rather than the constructor:

effect.SetMask(CellMask.Wipe(TextEffectDirection.LeftToRight));
effect.SetMask(CellMask.Iris(inward: true));
effect.SetMask(CellMask.Dissolve());

Constructors

CellMask(TextEffectMaskPattern, TextEffectDirection, bool, int, float, Func<int, int, int, int, float>)

Creates a mask directly. Prefer the named helpers, which are clearer at the call site.

Declaration

public CellMask(TextEffectMaskPattern pattern, TextEffectDirection direction = TextEffectDirection.LeftToRight, bool inverted = false, int bands = 8, float noiseScale = 0.12, Func<int, int, int, int, float> evaluator = null)

Parameters

Type	Name	Description
TextEffectMaskPattern	pattern	The shape to trace.
TextEffectDirection	direction	Direction of travel, for patterns that have one.
bool	inverted	Whether the pattern runs the other way.
int	bands	Band count or block size, for the patterns that use one.
float	noiseScale	Feature size for the noise pattern.
Func<int, int, int, int, float>	evaluator	Evaluator for the custom pattern, taking row, column, rows and columns.

Fields

Bands

Number of bands for Blinds, or block size for Checkerboard.

Declaration

public readonly int Bands

Field Value

Type	Description
int

Direction

The direction the pattern travels, for the patterns that have one.

Declaration

public readonly TextEffectDirection Direction

Field Value

Type	Description
TextEffectDirection

Inverted

Reverses the pattern: an iris closes instead of opening, a clock runs anticlockwise, barn doors shut instead of parting.

Declaration

public readonly bool Inverted

Field Value

Type	Description
bool

NoiseScale

Feature size for Noise. Larger values break the field into smaller, busier patches.

Declaration

public readonly float NoiseScale

Field Value

Type	Description
float

Pattern

The shape this mask traces.

Declaration

public readonly TextEffectMaskPattern Pattern

Field Value

Type	Description
TextEffectMaskPattern

Methods

BarnDoor(bool, bool)

Parts the region into two halves that open away from the center line, or close onto it.

Declaration

public static CellMask BarnDoor(bool horizontal = true, bool close = false)

Parameters

Type	Name	Description
bool	horizontal	True for doors that part left and right, false for up and down.
bool	close	True to close onto the center instead of opening away from it.

Returns

Type	Description
CellMask	A barn door mask.

Blinds(int, bool)

Fills parallel bands in turn.

Declaration

public static CellMask Blinds(int bands = 6, bool horizontal = true)

Parameters

Type	Name	Description
int	bands	How many bands to divide the region into.
bool	horizontal	True for bands running across the region, false for bands running down it.

Returns

Type	Description
CellMask	A blinds mask.

Remarks

A band needs a few cells of depth to open smoothly, so asking for more bands than the region can carry gives fewer and deeper ones rather than a row of hard stripes.

Box(bool)

Grows a rectangle out from the center, or shrinks one onto it.

Declaration

public static CellMask Box(bool inward = false)

Parameters

Type	Name	Description
bool	inward	True to close in on the center instead of growing outward.

Returns

Type	Description
CellMask	A box mask.

Checkerboard(int)

Fills alternating blocks in a checker layout.

Declaration

public static CellMask Checkerboard(int size = 2)

Parameters

Type	Name	Description
int	size	Block size in cells.

Returns

Type	Description
CellMask	A checkerboard mask.

Clock(bool)

Sweeps a hand around the center.

Declaration

public static CellMask Clock(bool clockwise = true)

Parameters

Type	Name	Description
bool	clockwise	False to sweep the other way.

Returns

Type	Description
CellMask	A clock mask.

Custom(Func<int, int, int, int, float>)

Orders cells by a function of your own.

Declaration

public static CellMask Custom(Func<int, int, int, int, float> evaluator)

Parameters

Type	Name	Description
Func<int, int, int, int, float>	evaluator	Takes the cell's row and column within the region, plus the region's row and column counts, and returns its ordering value.

Returns

Type	Description
CellMask	A custom mask.

Remarks

The result is normalized afterwards, so the function's output does not need to be in any particular range. Only the relative ordering matters.

Diagonal(TextEffectDirection)

Sweeps corner to corner.

Declaration

public static CellMask Diagonal(TextEffectDirection direction)

Parameters

Type	Name	Description
TextEffectDirection	direction	Which way the diagonal leans, taken from the horizontal or vertical bias of this direction.

Returns

Type	Description
CellMask	A diagonal mask.

Dissolve()

Reaches cells in a random order, reproducible for a given seed.

Declaration

public static CellMask Dissolve()

Returns

Type	Description
CellMask	A dissolve mask.

Fill(float[], in CellRect, int, float)

Fills an array with this mask's value for every cell of a region, in row-major order.

Declaration

public void Fill(float[] destination, in CellRect region, int seed, float cellAspect)

Parameters

Type	Name	Description
float[]	destination	Array to fill. Must hold at least as many entries as the region has cells.
CellRect	region	The region being covered.
int	seed	Seed for the patterns that make random choices.
float	cellAspect	Cell width divided by cell height, used to keep round shapes round.

Remarks

Computed once when an effect starts rather than per cell per frame, which is why this fills an array instead of evaluating one cell at a time.

Iris(bool)

Grows a circle out from the center, or shrinks one onto it.

Declaration

public static CellMask Iris(bool inward = false)

Parameters

Type	Name	Description
bool	inward	True to close in on the center instead of growing outward.

Returns

Type	Description
CellMask	A radial mask.

Noise(float)

Reaches cells in the order of a noise field, giving a blotchy spread rather than an even scatter.

Declaration

public static CellMask Noise(float scale = 0.12)

Parameters

Type	Name	Description
float	scale	Feature size. Larger values produce smaller, busier patches.

Returns

Type	Description
CellMask	A noise mask.

Sequential()

Reaches cells in reading order, left to right and then down. The natural ordering for text.

Declaration

public static CellMask Sequential()

Returns

Type	Description
CellMask	A sequential mask.

Uniform()

Reaches every cell at once, so an effect using it does not stagger.

Declaration

public static CellMask Uniform()

Returns

Type	Description
CellMask	A uniform mask.

Wipe(TextEffectDirection)

Sweeps straight across the region.

Declaration

public static CellMask Wipe(TextEffectDirection direction)

Parameters

Type	Name	Description
TextEffectDirection	direction	The direction to sweep in.

Returns

Type	Description
CellMask	A linear mask.