Renders a view-space darkness / fog overlay with optional world-space reveal sources. More...

Inheritance diagram for Gondwana.Drawing.Direct.DirectDarknessOverlay:

Classes
class	RevealSource
	Represents a single world-space reveal source used by a DirectDarknessOverlay. More...

Public Member Functions

DirectDarknessOverlay (RenderSurfaceHostBase renderSurfaceHost, View view, SceneLayer projectionLayer, string? nickname=null)

Initializes a new darkness/fog overlay that covers a specific view.

RevealSource AddRevealSource (PointF centerWorldPx, float radiusWorldPx, string? nickname=null)

Adds a new manually controlled reveal source in world-space.

RevealSource TrackLight (DirectRadialLight light, float radiusScale=1f, float intensityScale=1f, bool trackIntensity=true, string? nickname=null)

Adds a reveal source that automatically tracks a DirectRadialLight.

void TrackLightLayer (DirectLightLayer lightLayer, float radiusScale=1f, float intensityScale=1f, bool trackIntensity=true)

Tracks every current and future light in a DirectLightLayer.

bool UntrackLight (DirectRadialLight light)

Stops tracking a specific light and removes its reveal source.

bool RemoveRevealSource (RevealSource source)

Removes a reveal source from this overlay.

void ClearRevealSources ()

Removes all reveal sources and stops all automatic tracking.

DirectDarknessOverlay SetDarknessColor (Color color)

Fluent helper to set the darkness tint.

DirectDarknessOverlay SetDarknessOpacity (byte opacity)

Fluent helper to set the darkness opacity.

DirectDarknessOverlay SetInnerClearRadiusRatio (float ratio)

Fluent helper to set the fully-revealed radius ratio.

DirectDarknessOverlay SetMidpointRadiusRatio (float ratio)

Fluent helper to set the midpoint radius ratio.

DirectDarknessOverlay SetMidpointStrength (float strength)

Fluent helper to set the midpoint reveal strength.

override void Update (long tick)

Performs per-frame update logic for this direct drawing, including fade and reveal animations.

Parameters

tick	The current engine tick value from HighResTimer.

This method is called automatically by the DirectDrawingManager each frame. The base implementation advances active fade and reveal animations. Override this method in derived classes to add custom per-frame logic (such as animation or physics updates).

Public Member Functions inherited from Gondwana.Drawing.Direct.DirectDrawingBase

RectangleF GetDrawLocationScreen (View view)

Gets the screen-space drawing location for this direct drawing as seen from the specified view.

void Draw (BackbufferBase backbuffer, RectangleF destRectScreen)

Renders this direct drawing to the backbuffer at the specified screen location.

DirectDrawingBase SetOpacity (float opacity)

Instantly sets the opacity to the specified value without animation.

DirectDrawingBase FadeTo (float targetOpacity, float durationSec)

Initiates a smooth fade transition to the specified target opacity over the given duration.

DirectDrawingBase FadeIn (float durationSec)

Fades this direct drawing from its current opacity to fully opaque over the specified duration.

DirectDrawingBase FadeOut (float durationSec)

Fades this direct drawing from its current opacity to fully transparent over the specified duration.

DirectDrawingBase CancelFade ()

Cancels any active fade transition, leaving the opacity at its current value.

DirectDrawingBase SetReveal (float t01)

Instantly sets the reveal progress to the specified value without animation.

DirectDrawingBase SetRevealDirection (RevealDirection dir)

Sets the direction from which the reveal animation progresses.

DirectDrawingBase RevealTo (float t01, float durationSec, Func< float, float >? easing=null)

Initiates a smooth reveal animation to the specified target progress over the given duration, optionally using a custom easing function.

DirectDrawingBase CancelReveal ()

Stops an active reveal animation at its current progress.

int CompareTo (DirectDrawingBase? other)

Compares this direct drawing to another for sorting by ZOrder.

void Dispose ()

Releases all resources used by this DirectDrawingBase instance.

override bool Equals (object? obj)

Determines whether the specified object is equal to the current direct drawing.

override int GetHashCode ()

Returns a hash code for this direct drawing.

Protected Member Functions

override void OnDraw (BackbufferBase backbuffer, RectangleF destRectScreen)

override void Dispose (bool disposing)

Releases resources used by this DirectDrawingBase instance.

Parameters

disposing true to release both managed and unmanaged resources; false to release only unmanaged resources (called from finalizer).

When disposing is true, this method:

Marks affected regions as dirty by calling ForceRefresh.
Raises the Disposing event.
Clears all event handlers to prevent memory leaks.

Protected Member Functions inherited from Gondwana.Drawing.Direct.DirectDrawingBase

void OnDraw (BackbufferBase backbuffer, RectangleF destRectScreen)

Performs the concrete drawing for this direct drawing to the backbuffer.

DirectDrawingBase (RenderSurfaceHostBase renderSurfaceHost, DirectDrawingMode mode, SceneLayer? sceneLayer, View? view, Rectangle? screenBounds, Rectangle? worldBounds, string? nickname=null)

Initializes a new instance of the DirectDrawingBase class.

Properties
SceneLayer	ProjectionLayer `[get]`
	Gets the scene layer used to project reveal source world positions into screen coordinates.
IReadOnlyList< RevealSource >	RevealSources `[get]`
	Gets a live, ordered list of reveal sources used by this overlay.
Color	DarknessColor `[get, set]`
	Gets or sets the tint color of the overlay.
byte	DarknessOpacity `[get, set]`
	Gets or sets the opacity of the darkness overlay.
float	InnerClearRadiusRatio `[get, set]`
	Gets or sets the radius ratio that remains fully revealed before falloff begins.
float	MidpointRadiusRatio `[get, set]`
	Gets or sets the radius ratio of the midpoint alpha stop used for reveal falloff.
float	MidpointStrength `[get, set]`
	Gets or sets the removal strength at the midpoint stop.
Properties inherited from Gondwana.Drawing.Direct.DirectDrawingBase
bool	HideWhenFullyTransparent = true `[get, set]`
	Gets or sets a value indicating whether this direct drawing should be automatically hidden when its opacity reaches zero during fade transitions.
RenderSurfaceHostBase	RenderSurfaceHost `[get]`
	Gets the render surface host that manages this direct drawing's rendering pipeline.
DirectDrawingMode	Mode `[get]`
	Gets the drawing mode that determines how this direct drawing is positioned and transformed.
SceneLayer?	SceneLayer `[get]`
	Gets the scene layer to which this direct drawing is attached, or `null` if the drawing is in view mode.
View?	View `[get]`
	Gets the view to which this direct drawing is attached, or `null` if the drawing is in scene-layer mode.
Rectangle	ScreenBounds `[get, set]`
	Gets or sets the screen-space bounds of this direct drawing in pixels.
Rectangle	WorldBounds `[get, set]`
	Gets or sets the world-space bounds of this direct drawing in pixels.
TypedValueBag	ValueBag = new() `[get]`
	Gets the extensible value bag for storing arbitrary key-value data associated with this direct drawing.
Guid	Id = Guid.NewGuid() `[get]`
	Gets the unique identifier for this direct drawing.
string?	Nickname `[get]`
	Gets the optional human-readable name for this direct drawing.
int	ZOrder `[get, set]`
	Gets or sets the Z-order (depth) used for sorting this direct drawing relative to other drawables.
bool	Visible `[get, set]`
	Gets or sets a value indicating whether this direct drawing is visible and should be rendered.
float	Opacity `[get, set]`
	Gets or sets the current opacity of this direct drawing.

Additional Inherited Members
Public Types inherited from Gondwana.Drawing.Direct.DirectDrawingBase
enum	RevealDirection { LeftToRight , RightToLeft , TopToBottom , BottomToTop }
	Defines the direction from which a reveal animation progressively displays the direct drawing. More...
Static Public Member Functions inherited from Gondwana.Drawing.Direct.DirectDrawingBase
static bool	operator== (DirectDrawingBase? left, DirectDrawingBase? right)
	Determines whether two direct drawing instances are equal using reference equality.
static bool	operator!= (DirectDrawingBase? left, DirectDrawingBase? right)
	Determines whether two direct drawing instances are not equal using reference equality.
static bool	operator< (DirectDrawingBase? left, DirectDrawingBase? right)
	Determines whether the Z-order of the left direct drawing is less than the right.
static bool	operator<= (DirectDrawingBase? left, DirectDrawingBase? right)
	Determines whether the Z-order of the left direct drawing is less than or equal to the right.
static bool	operator> (DirectDrawingBase? left, DirectDrawingBase? right)
	Determines whether the Z-order of the left direct drawing is greater than the right.
static bool	operator>= (DirectDrawingBase? left, DirectDrawingBase? right)
	Determines whether the Z-order of the left direct drawing is greater than or equal to the right.
Protected Attributes inherited from Gondwana.Drawing.Direct.DirectDrawingBase
readonly RenderSurfaceHostBase	_renderSurfaceHost
	The render surface host that manages this direct drawing's rendering pipeline.
Rectangle	_screenBounds
	The current screen-space bounds for view-mode direct drawings, in pixels.
Rectangle	_worldBounds
	The current world-space bounds for scene-layer-mode direct drawings, in pixels.
int	_zOrder
	The Z-order used for draw sorting. Higher values draw later (on top).
bool	_visible
	Indicates whether this direct drawing is currently visible and should be rendered.
long	_lastTick = HighResTimer.GetCurrentTick()
	The last engine tick value used for delta-time calculations in Update.
Events inherited from Gondwana.Drawing.Direct.DirectDrawingBase
EventHandler< IDirectDrawable >?	Disposing
	Occurs when this direct drawing is being disposed.
EventHandler< DirectDrawingBase >?	FadeToCompleted
	Occurs when a fade transition initiated by FadeTo, FadeIn, or FadeOut completes.
Events inherited from Gondwana.Drawing.Direct.IDirectDrawable
EventHandler< IDirectDrawable >?	Disposing
	Occurs when the object is being disposed.

Detailed Description

Renders a view-space darkness / fog overlay with optional world-space reveal sources.

DirectDarknessOverlay is the "other half" of a localized lighting setup. It draws a semi-transparent darkness layer over an entire View, then carves out soft reveal regions based on one or more world-space RevealSource instances.

This is intentionally implemented as a DirectDrawingBase in DirectDrawingMode.View so it remains modular and take-it-or-leave-it: no renderer-wide lighting system is required.

Reveal sources can be controlled manually, can track individual DirectRadialLight instances, or can track every light in a DirectLightLayer. Tracking is optional; manual reveal sources remain useful for player vision, stealth cones, magic sight, and scripted fog.

Dirty-rectangle behavior: because this is a full-view overlay, any visible change typically refreshes the full viewport. That is expected for this style of effect and keeps the feature self-contained.

var lights = new DirectLightLayer(renderSurfaceHost, dungeonLayer);
var torch = lights.AddTorchLight(new PointF(520, 320), 110f, nickname: "torch-01");
 
var darkness = new DirectDarknessOverlay(renderSurfaceHost, mainView, dungeonLayer, "dungeon-darkness")
    .SetDarknessColor(Color.Black)
    .SetDarknessOpacity(190);
 
darkness.TrackLight(torch);
 
// Later during gameplay:
torch.MoveTo(playerWorldCenterPx);
// The torch glow and darkness reveal now move together.

Definition at line 52 of file DirectDarknessOverlay.cs.

Constructor & Destructor Documentation

◆ DirectDarknessOverlay()

Gondwana.Drawing.Direct.DirectDarknessOverlay.DirectDarknessOverlay	(	RenderSurfaceHostBase	renderSurfaceHost,
		View	view,
		SceneLayer	projectionLayer,
		string?	nickname = null )

Initializes a new darkness/fog overlay that covers a specific view.

Parameters

renderSurfaceHost	The render surface host that owns the target scene and view.
view	The target view whose viewport will receive the overlay.
projectionLayer	The scene layer used to project world-space reveal sources into screen-space. In most games this should be the main gameplay/world layer.
nickname	Optional friendly name for debugging and lookup.

Definition at line 81 of file DirectDarknessOverlay.cs.

Member Function Documentation

◆ AddRevealSource()

RevealSource Gondwana.Drawing.Direct.DirectDarknessOverlay.AddRevealSource	(	PointF	centerWorldPx,
		float	radiusWorldPx,
		string?	nickname = null )

Adds a new manually controlled reveal source in world-space.

Parameters

centerWorldPx	The center in world pixels.
radiusWorldPx	The radius in world pixels.
nickname	An optional name used to identify the object.

Returns: The reveal source added to this overlay.

Definition at line 212 of file DirectDarknessOverlay.cs.

◆ ClearRevealSources()

void Gondwana.Drawing.Direct.DirectDarknessOverlay.ClearRevealSources ( )

Removes all reveal sources and stops all automatic tracking.

Definition at line 347 of file DirectDarknessOverlay.cs.

◆ Dispose()

override void Gondwana.Drawing.Direct.DirectDarknessOverlay.Dispose ( bool disposing )

protectedvirtual

Releases resources used by this DirectDrawingBase instance.

Parameters

disposing true to release both managed and unmanaged resources; false to release only unmanaged resources (called from finalizer).

When disposing is true, this method:

Marks affected regions as dirty by calling ForceRefresh.
Raises the Disposing event.
Clears all event handlers to prevent memory leaks.

Reimplemented from Gondwana.Drawing.Direct.DirectDrawingBase.

Definition at line 559 of file DirectDarknessOverlay.cs.

◆ OnDraw()

override void Gondwana.Drawing.Direct.DirectDarknessOverlay.OnDraw	(	BackbufferBase	backbuffer,
		RectangleF	destRectScreen )

protected

Definition at line 434 of file DirectDarknessOverlay.cs.

◆ RemoveRevealSource()

bool Gondwana.Drawing.Direct.DirectDarknessOverlay.RemoveRevealSource ( RevealSource source )

Removes a reveal source from this overlay.

Parameters

source The source.

Returns: true if the entry was found and removed; otherwise, false.

Definition at line 328 of file DirectDarknessOverlay.cs.

◆ SetDarknessColor()

DirectDarknessOverlay Gondwana.Drawing.Direct.DirectDarknessOverlay.SetDarknessColor ( Color color )

Fluent helper to set the darkness tint.

Parameters

color The color to apply.

Returns: This instance for fluent chaining.

Definition at line 372 of file DirectDarknessOverlay.cs.

◆ SetDarknessOpacity()

DirectDarknessOverlay Gondwana.Drawing.Direct.DirectDarknessOverlay.SetDarknessOpacity ( byte opacity )

Fluent helper to set the darkness opacity.

Parameters

opacity The opacity, from zero (transparent) to one (opaque).

Returns: This instance for fluent chaining.

Definition at line 383 of file DirectDarknessOverlay.cs.

◆ SetInnerClearRadiusRatio()

DirectDarknessOverlay Gondwana.Drawing.Direct.DirectDarknessOverlay.SetInnerClearRadiusRatio ( float ratio )

Fluent helper to set the fully-revealed radius ratio.

Parameters

ratio The ratio.

Returns: This instance for fluent chaining.

Definition at line 394 of file DirectDarknessOverlay.cs.

◆ SetMidpointRadiusRatio()

DirectDarknessOverlay Gondwana.Drawing.Direct.DirectDarknessOverlay.SetMidpointRadiusRatio ( float ratio )

Fluent helper to set the midpoint radius ratio.

Parameters

ratio The ratio.

Returns: This instance for fluent chaining.

Definition at line 405 of file DirectDarknessOverlay.cs.

◆ SetMidpointStrength()

DirectDarknessOverlay Gondwana.Drawing.Direct.DirectDarknessOverlay.SetMidpointStrength ( float strength )

Fluent helper to set the midpoint reveal strength.

Parameters

strength The strength.

Returns: This instance for fluent chaining.

Definition at line 416 of file DirectDarknessOverlay.cs.

◆ TrackLight()

RevealSource Gondwana.Drawing.Direct.DirectDarknessOverlay.TrackLight	(	DirectRadialLight	light,
		float	radiusScale = 1f,
		float	intensityScale = 1f,
		bool	trackIntensity = true,
		string?	nickname = null )

Adds a reveal source that automatically tracks a DirectRadialLight.

Parameters

light	The light whose center/radius/intensity should drive the reveal.
radiusScale	Multiplier applied to the light radius when calculating reveal radius.
intensityScale	Multiplier applied to the light intensity when calculating reveal intensity.
trackIntensity	When true, the reveal intensity follows DirectRadialLight.EffectiveIntensity. When false, the reveal uses intensityScale as a constant intensity.
nickname	Optional friendly name for the reveal source.

Tracking is idempotent per light. If this overlay already tracks light , this method returns the existing RevealSource and leaves the existing radiusScale , intensityScale , and trackIntensity settings unchanged. To change those settings, call UntrackLight and then call TrackLight again.

Returns: The reveal source linked to the supplied light.

Definition at line 239 of file DirectDarknessOverlay.cs.

◆ TrackLightLayer()

void Gondwana.Drawing.Direct.DirectDarknessOverlay.TrackLightLayer	(	DirectLightLayer	lightLayer,
		float	radiusScale = 1f,
		float	intensityScale = 1f,
		bool	trackIntensity = true )

Tracks every current and future light in a DirectLightLayer.

This is a convenience wrapper for games that want one logical light owner and one darkness overlay. Existing lights are tracked immediately. Lights added to the layer later are tracked automatically.

Tracking is idempotent per light layer. Calling this method again for the same layer leaves the original tracking options in place.

Parameters

lightLayer	The light layer.
radiusScale	The multiplier applied to the reveal radius.
intensityScale	The multiplier applied to the reveal intensity.
trackIntensity	Whether reveal intensity follows the light intensity.

Definition at line 282 of file DirectDarknessOverlay.cs.

◆ UntrackLight()

bool Gondwana.Drawing.Direct.DirectDarknessOverlay.UntrackLight ( DirectRadialLight light )

Stops tracking a specific light and removes its reveal source.

Parameters

light The light.

Returns: true if the light was being tracked and was removed; otherwise, false.

Definition at line 313 of file DirectDarknessOverlay.cs.

◆ Update()

override void Gondwana.Drawing.Direct.DirectDarknessOverlay.Update ( long tick )

virtual

Performs per-frame update logic for this direct drawing, including fade and reveal animations.

Parameters

tick	The current engine tick value from HighResTimer.

This method is called automatically by the DirectDrawingManager each frame. The base implementation advances active fade and reveal animations. Override this method in derived classes to add custom per-frame logic (such as animation or physics updates).

Reimplemented from Gondwana.Drawing.Direct.DirectDrawingBase.

Definition at line 423 of file DirectDarknessOverlay.cs.

Property Documentation

◆ DarknessColor

Color Gondwana.Drawing.Direct.DirectDarknessOverlay.DarknessColor

getset

Gets or sets the tint color of the overlay.

Definition at line 111 of file DirectDarknessOverlay.cs.

◆ DarknessOpacity

byte Gondwana.Drawing.Direct.DirectDarknessOverlay.DarknessOpacity

getset

Gets or sets the opacity of the darkness overlay.

Definition at line 128 of file DirectDarknessOverlay.cs.

◆ InnerClearRadiusRatio

float Gondwana.Drawing.Direct.DirectDarknessOverlay.InnerClearRadiusRatio

getset

Gets or sets the radius ratio that remains fully revealed before falloff begins.

A value of 0 means reveal falloff begins immediately from the center. A value near 1 means most of the reveal radius remains fully visible before fading.

Definition at line 149 of file DirectDarknessOverlay.cs.

◆ MidpointRadiusRatio

float Gondwana.Drawing.Direct.DirectDarknessOverlay.MidpointRadiusRatio

getset

Gets or sets the radius ratio of the midpoint alpha stop used for reveal falloff.

Definition at line 169 of file DirectDarknessOverlay.cs.

◆ MidpointStrength

float Gondwana.Drawing.Direct.DirectDarknessOverlay.MidpointStrength

getset

Gets or sets the removal strength at the midpoint stop.

1.0 keeps the reveal strong deep into the radius; lower values produce a faster falloff.

Definition at line 191 of file DirectDarknessOverlay.cs.

◆ ProjectionLayer

SceneLayer Gondwana.Drawing.Direct.DirectDarknessOverlay.ProjectionLayer

get

Gets the scene layer used to project reveal source world positions into screen coordinates.

Definition at line 101 of file DirectDarknessOverlay.cs.

◆ RevealSources

IReadOnlyList<RevealSource> Gondwana.Drawing.Direct.DirectDarknessOverlay.RevealSources

get

Gets a live, ordered list of reveal sources used by this overlay.

Definition at line 106 of file DirectDarknessOverlay.cs.

Classes

Public Member Functions

Protected Member Functions

Properties

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ DirectDarknessOverlay()

Member Function Documentation

◆ AddRevealSource()

◆ ClearRevealSources()

◆ Dispose()

◆ OnDraw()

◆ RemoveRevealSource()

◆ SetDarknessColor()

◆ SetDarknessOpacity()

◆ SetInnerClearRadiusRatio()

◆ SetMidpointRadiusRatio()

◆ SetMidpointStrength()

◆ TrackLight()

◆ TrackLightLayer()

◆ UntrackLight()

◆ Update()

Property Documentation

◆ DarknessColor

◆ DarknessOpacity

◆ InnerClearRadiusRatio

◆ MidpointRadiusRatio

◆ MidpointStrength

◆ ProjectionLayer

◆ RevealSources