Renders a world-bounded darkness/fog overlay as a scene-layer direct drawing. More...

Inheritance diagram for Gondwana.Drawing.Direct.DirectSceneLayerDarknessOverlay:

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

Public Member Functions
	DirectSceneLayerDarknessOverlay (RenderSurfaceHostBase renderSurfaceHost, SceneLayer sceneLayer, Rectangle worldBounds, string? nickname=null)
	Initializes a new scene-layer darkness/fog overlay.
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 on this same SceneLayer.
void	TrackLightLayer (DirectLightLayer lightLayer, float radiusScale=1f, float intensityScale=1f, bool trackIntensity=true)
	Tracks every current and future light in a DirectLightLayer attached to this same SceneLayer.
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.
DirectSceneLayerDarknessOverlay	SetDarknessWorldBounds (Rectangle worldBounds)
	Fluent helper to set the darkness/fog world bounds.
DirectSceneLayerDarknessOverlay	SetDarknessColor (Color color)
	Fluent helper to set the darkness tint.
DirectSceneLayerDarknessOverlay	SetDarknessOpacity (byte opacity)
	Fluent helper to set the darkness opacity.
DirectSceneLayerDarknessOverlay	SetInnerClearRadiusRatio (float ratio)
	Fluent helper to set the fully-revealed radius ratio.
DirectSceneLayerDarknessOverlay	SetMidpointRadiusRatio (float ratio)
	Fluent helper to set the midpoint radius ratio.
DirectSceneLayerDarknessOverlay	SetMidpointStrength (float strength)
	Fluent helper to set the midpoint reveal strength.
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.
virtual void	Update (long tick)
	Performs per-frame update logic for this direct drawing, including fade and reveal animations.
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
IReadOnlyList< RevealSource >	RevealSources `[get]`
	Gets a live, ordered list of reveal sources used by this overlay.
Rectangle	DarknessWorldBounds `[get, set]`
	Gets or sets the world-space region affected by the darkness/fog.
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 world-bounded darkness/fog overlay as a scene-layer direct drawing.

DirectSceneLayerDarknessOverlay is the SceneLayer-bound sibling of DirectDarknessOverlay. Use it for darkness, mist, smoke, or fog that physically belongs to a specific SceneLayer instead of to a player/view.

The overlay darkens only its own DirectDrawingBase.WorldBounds and only participates in the render pass of its own SceneLayer. It can track DirectRadialLight instances from that same layer, but it intentionally refuses lights from other layers. That keeps this helper modular and avoids introducing cross-layer light spill, shadows, or bouncing.

This class is useful for world effects such as swamp fog, dust clouds, magical darkness regions, poison haze, room-local darkness, and other atmosphere that should be visible to every view that can see that part of the layer.

Definition at line 31 of file DirectSceneLayerDarknessOverlay.cs.

Constructor & Destructor Documentation

◆ DirectSceneLayerDarknessOverlay()

Gondwana.Drawing.Direct.DirectSceneLayerDarknessOverlay.DirectSceneLayerDarknessOverlay	(	RenderSurfaceHostBase	renderSurfaceHost,
		SceneLayer	sceneLayer,
		Rectangle	worldBounds,
		string?	nickname = null )

Initializes a new scene-layer darkness/fog overlay.

Parameters

renderSurfaceHost	The render surface host that owns the drawing.
sceneLayer	The layer this darkness/fog belongs to.
worldBounds	The world-space region affected by the darkness/fog.
nickname	Optional friendly name for debugging and lookup.

Definition at line 57 of file DirectSceneLayerDarknessOverlay.cs.

Member Function Documentation

◆ AddRevealSource()

RevealSource Gondwana.Drawing.Direct.DirectSceneLayerDarknessOverlay.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 184 of file DirectSceneLayerDarknessOverlay.cs.

◆ ClearRevealSources()

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

Removes all reveal sources and stops all automatic tracking.

Definition at line 314 of file DirectSceneLayerDarknessOverlay.cs.

◆ Dispose()

override void Gondwana.Drawing.Direct.DirectSceneLayerDarknessOverlay.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 553 of file DirectSceneLayerDarknessOverlay.cs.

◆ OnDraw()

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

protected

Definition at line 401 of file DirectSceneLayerDarknessOverlay.cs.

◆ RemoveRevealSource()

bool Gondwana.Drawing.Direct.DirectSceneLayerDarknessOverlay.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 295 of file DirectSceneLayerDarknessOverlay.cs.

◆ SetDarknessColor()

DirectSceneLayerDarknessOverlay Gondwana.Drawing.Direct.DirectSceneLayerDarknessOverlay.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 350 of file DirectSceneLayerDarknessOverlay.cs.

◆ SetDarknessOpacity()

DirectSceneLayerDarknessOverlay Gondwana.Drawing.Direct.DirectSceneLayerDarknessOverlay.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 361 of file DirectSceneLayerDarknessOverlay.cs.

◆ SetDarknessWorldBounds()

DirectSceneLayerDarknessOverlay Gondwana.Drawing.Direct.DirectSceneLayerDarknessOverlay.SetDarknessWorldBounds ( Rectangle worldBounds )

Fluent helper to set the darkness/fog world bounds.

Parameters

worldBounds The bounds in world pixels.

Returns: This instance for fluent chaining.

Definition at line 339 of file DirectSceneLayerDarknessOverlay.cs.

◆ SetInnerClearRadiusRatio()

DirectSceneLayerDarknessOverlay Gondwana.Drawing.Direct.DirectSceneLayerDarknessOverlay.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 372 of file DirectSceneLayerDarknessOverlay.cs.

◆ SetMidpointRadiusRatio()

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

Fluent helper to set the midpoint radius ratio.

Parameters

ratio The ratio.

Returns: This instance for fluent chaining.

Definition at line 383 of file DirectSceneLayerDarknessOverlay.cs.

◆ SetMidpointStrength()

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

Fluent helper to set the midpoint reveal strength.

Parameters

strength The strength.

Returns: This instance for fluent chaining.

Definition at line 394 of file DirectSceneLayerDarknessOverlay.cs.

◆ TrackLight()

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

Adds a reveal source that automatically tracks a DirectRadialLight on this same SceneLayer.

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

Parameters

light	The light.
radiusScale	The multiplier applied to the reveal radius.
intensityScale	The multiplier applied to the reveal intensity.
trackIntensity	Whether reveal intensity follows the light intensity.
nickname	An optional name used to identify the object.

Returns: The reveal source linked to the supplied light.

Definition at line 207 of file DirectSceneLayerDarknessOverlay.cs.

◆ TrackLightLayer()

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

Tracks every current and future light in a DirectLightLayer attached to this same SceneLayer.

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 246 of file DirectSceneLayerDarknessOverlay.cs.

◆ UntrackLight()

bool Gondwana.Drawing.Direct.DirectSceneLayerDarknessOverlay.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 280 of file DirectSceneLayerDarknessOverlay.cs.

Property Documentation

◆ DarknessColor

Color Gondwana.Drawing.Direct.DirectSceneLayerDarknessOverlay.DarknessColor

getset

Gets or sets the tint color of the overlay.

Definition at line 90 of file DirectSceneLayerDarknessOverlay.cs.

◆ DarknessOpacity

byte Gondwana.Drawing.Direct.DirectSceneLayerDarknessOverlay.DarknessOpacity

getset

Gets or sets the opacity of the darkness overlay.

Definition at line 107 of file DirectSceneLayerDarknessOverlay.cs.

◆ DarknessWorldBounds

Rectangle Gondwana.Drawing.Direct.DirectSceneLayerDarknessOverlay.DarknessWorldBounds

getset

Gets or sets the world-space region affected by the darkness/fog.

Definition at line 81 of file DirectSceneLayerDarknessOverlay.cs.

◆ InnerClearRadiusRatio

float Gondwana.Drawing.Direct.DirectSceneLayerDarknessOverlay.InnerClearRadiusRatio

getset

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

Definition at line 124 of file DirectSceneLayerDarknessOverlay.cs.

◆ MidpointRadiusRatio

float Gondwana.Drawing.Direct.DirectSceneLayerDarknessOverlay.MidpointRadiusRatio

getset

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

Definition at line 144 of file DirectSceneLayerDarknessOverlay.cs.

◆ MidpointStrength

float Gondwana.Drawing.Direct.DirectSceneLayerDarknessOverlay.MidpointStrength

getset

Gets or sets the removal strength at the midpoint stop.

Definition at line 163 of file DirectSceneLayerDarknessOverlay.cs.

◆ RevealSources

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

get

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

Definition at line 76 of file DirectSceneLayerDarknessOverlay.cs.

Classes

Public Member Functions

Protected Member Functions

Properties

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ DirectSceneLayerDarknessOverlay()

Member Function Documentation

◆ AddRevealSource()

◆ ClearRevealSources()

◆ Dispose()

◆ OnDraw()

◆ RemoveRevealSource()

◆ SetDarknessColor()

◆ SetDarknessOpacity()

◆ SetDarknessWorldBounds()

◆ SetInnerClearRadiusRatio()

◆ SetMidpointRadiusRatio()

◆ SetMidpointStrength()

◆ TrackLight()

◆ TrackLightLayer()

◆ UntrackLight()

Property Documentation

◆ DarknessColor

◆ DarknessOpacity

◆ DarknessWorldBounds

◆ InnerClearRadiusRatio

◆ MidpointRadiusRatio

◆ MidpointStrength

◆ RevealSources