Class AmbientEffectBase
Base class for effects that decorate whatever is already on screen and keep going, rather than moving a region from one state to another and finishing.
Inheritance
Inherited Members
Namespace: Scylla.TextMode
Assembly: ScyllaTextMode.dll
Syntax
public abstract class AmbientEffectBase : TextEffectBase, ITextEffect, IDisposableRemarks
An ambient effect captures its region when it starts and then draws a modified version of that capture every frame. The original is never lost, so the effect can put it back when it stops, which is what lets a glitch or a flicker be switched off without the screen underneath having to be redrawn.
These effects repeat without end by default, so nothing chained to their completion will run. That is deliberate: an ambient effect is meant to carry on until whatever it is decorating goes away. Give one a loop count if it should stop on its own.
Because they run for a long time, the rule that an effect owns its region matters more here than anywhere else. An ambient effect keeps drawing from the copy it took at the start, so content drawn into the region afterwards is liable to be overwritten. Call Refresh() right after redrawing to bring the effect up to date.
Do not rely on that overwrite happening promptly, or at all. Only the effects that rewrite the whole region every tick reclaim it on the next frame. The ones that skip redundant writes reclaim a cell whenever they next happen to touch it, which for a flicker or a glitch is the next time its timer fires, and for a twinkle is whenever a point lands on that cell, possibly never. Foreign content can therefore sit in the region indefinitely, looking as though it were part of the effect.
Constructors
AmbientEffectBase()
Creates an ambient effect, which repeats without end until it is given a loop count.
Declaration
protected AmbientEffectBase()Properties
Content
Gets the untouched region the effect decorates. Valid from OnAmbientStart() onward.
Declaration
protected CellBuffer Content { get; }Property Value
| Type | Description |
|---|---|
| CellBuffer |
RestoreOnFinish
Gets or sets whether the region is put back the way it was when the effect stops.
Declaration
public bool RestoreOnFinish { get; set; }Property Value
| Type | Description |
|---|---|
| bool |
Remarks
On by default, because an ambient effect is a decoration and switching it off should leave no trace. Turn it off when the caller is going to redraw the region anyway, to save a pass over it.
Methods
OnAmbientFinish(bool)
Called when the effect stops, before the untouched content is put back.
Declaration
protected virtual void OnAmbientFinish(bool completed)Parameters
| Type | Name | Description |
|---|---|---|
| bool | completed | True when the effect ran out its loops rather than being stopped. |
OnAmbientRefresh()
Called when the region is captured again through Refresh().
Declaration
protected virtual void OnAmbientRefresh()OnAmbientStart()
Called when the effect starts, after the region has been captured.
Declaration
protected virtual void OnAmbientStart()OnEffectFinish(bool)
Called when the effect finishes, whether it completed, was skipped or was stopped.
Declaration
protected override sealed void OnEffectFinish(bool completed)Parameters
| Type | Name | Description |
|---|---|---|
| bool | completed | True when the effect reached its final state. |
Overrides
Remarks
The default implementation does nothing. Override it to restore state an effect borrowed, which is what a corrupting effect needs so the grid is not left damaged.
OnEffectRelease()
Called when the effect is disposed. Return anything rented from the context here.
Declaration
protected override void OnEffectRelease()Overrides
OnEffectStart()
Called when the effect starts, after the region is resolved and before any tick. Capture whatever the effect needs from the grid here.
Declaration
protected override sealed void OnEffectStart()Overrides
Refresh()
Takes a fresh copy of the region, so the effect decorates what is on screen now.
Declaration
public void Refresh()Remarks
Call this immediately after redrawing a region an ambient effect is running on, and not at any other time. The screen normally shows the decorated version, so refreshing at any other moment captures the decoration and bakes it in.