A flexible particle system for effects like smoke, sparks, fire, or snow, implemented as a DirectDrawingBase. More...

Inheritance diagram for Gondwana.Drawing.Direct.Particles.ParticleSurface:

Public Member Functions
	ParticleSurface (RenderSurfaceHostBase renderSurfaceHost, SceneLayer sceneLayer, Rectangle? worldBounds, string? nickname=null, int maxParticles=2000, SKBitmap? particleSprite=null)
	Initializes a new instance of the ParticleSurface class for scene layer rendering with world-space coordinate bounds.
	ParticleSurface (RenderSurfaceHostBase renderSurfaceHost, View view, Rectangle? screenBounds, string? nickname=null, int maxParticles=2000, SKBitmap? particleSprite=null)
	Initializes a new instance of the ParticleSurface class for view-based rendering with screen-space coordinate bounds.
void	Burst (ParticleEmitter emitter, int count)
	Immediately spawns a fixed number of particles from the given emitter. Useful for explosions, impacts, or click/tap feedback.
override void	Update (long tick)
	Tick-driven update override. Computes delta internally and advances simulation.
Public Member Functions inherited from Gondwana.Drawing.Direct.DirectDrawingMovableBase
Vector2	GetPosition ()
	Gets the current position of this direct drawing in pixel coordinates.
void	SetPosition (Vector2 p)
	Sets the position of this direct drawing to the specified pixel coordinates.
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.

Public Attributes
readonly List< ParticleEmitter >	Emitters = new()
	Collection of particle emitters this system updates and renders. Add multiple emitters (e.g., sparks + smoke) to layer effects.

Protected Member Functions
override void	Dispose (bool disposing)
	Releases the particle array back to the pool and disposes managed resources.
override void	OnDraw (BackbufferBase backbuffer, RectangleF destRectScreen)
	Renders all live particles to the current backbuffer.
Protected Member Functions inherited from Gondwana.Drawing.Direct.DirectDrawingMovableBase
	DirectDrawingMovableBase (RenderSurfaceHostBase renderSurfaceHost, DirectDrawingMode mode, SceneLayer? sceneLayer, View? view, Rectangle? screenBounds, Rectangle? worldBounds, string? name=null)
	Initializes a new instance of the DirectDrawingMovableBase class with integrated movement capabilities.
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
int	ActiveParticleCount `[get]`
	Gets the current number of active (alive) particles being simulated.
float	GlobalEmitScale = 1f `[get, set]`
	Global multiplier applied to all emitter `EmitRate` values in this particle system. Acts like a master volume knob for particle density.
SKColor	GlobalColorTint = SKColors.White `[get, set]`
	Global tint color multiplied against every particle's own color during rendering.
float	GravityX = 0f `[get, set]`
	Gets or sets the horizontal component of gravity, measured in pixels per second squared. Default is 0 (no horizontal gravity).
float	GravityY = 400f `[get, set]`
	Gets or sets the gravitational acceleration along the Y-axis, measured in pixels per second squared. Default is 400 (downward).
float	CullingMarginX = 32f `[get, set]`
	Gets or sets the horizontal culling margin, in pixels, beyond the bounds of the viewport to keep elements active.
float	CullingMarginY = 32f `[get, set]`
	Gets or sets the vertical culling margin, in pixels, beyond the bounds of the viewport to keep elements active.
Properties inherited from Gondwana.Drawing.Direct.DirectDrawingMovableBase
MovementController	Movement `[get]`
	Gets the movement controller responsible for changing this direct drawing's position over time.
MovementSpace	PositionSpace `[get]`
	Gets the coordinate space in which this movable object's position is expressed.
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.
Properties inherited from Gondwana.Drawing.Direct.IDirectCompositeChild
SceneLayer?	SceneLayer `[get]`
	Gets the scene layer used by a scene-layer child, or `null` for a view child.
View?	View `[get]`
	Gets the view used by a view child, or `null` for a scene-layer child.

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

A flexible particle system for effects like smoke, sparks, fire, or snow, implemented as a DirectDrawingBase.

The particle system maintains a pool of particles that are updated and rendered each frame. Particles have a position, velocity, life span, size, and color. The system uses SkiaSharp to draw either simple circles or textured sprites.

Emission is controlled through one or more ParticleEmitter instances. Each emitter defines its own position, rate, life range, velocity ranges, size range, and base color. This allows you to layer effects (e.g., smoke plus sparks) within a single particle system.

Internally, the particle pool is compacted each update to avoid GC churn. Rendering uses Skia's SKBlendMode.Plus for additive blending, making it suitable for "glowy" effects such as fire, sparks, and magical auras.

The following demonstrates how to create a particle system with two emitters:

// Create a particle system covering the whole viewport
var particles = new DirectParticles(renderHost,
    new Rectangle(0, 0, viewportW, viewportH));
 
// Create a sparks emitter
var sparks = new ParticleEmitter
{
    Position = new PointF(400, 550),
    EmitRate = 400,
    LifeRange = (0.5f, 1.0f),
    VelocityRangeX = (-150f, 150f),
    VelocityRangeY = (-300f, -200f),
    SizeRange = (2f, 4f),
    Color = SKColors.OrangeRed
};
 
// Create a smoke emitter
var smoke = new ParticleEmitter
{
    Position = new PointF(400, 540),
    EmitRate = 120,
    LifeRange = (2.5f, 4.0f),
    VelocityRangeX = (-40f, 40f),
    VelocityRangeY = (-120f, -60f),
    SizeRange = (8f, 16f),
    Color = new SKColor(80, 80, 80, 200)
};
 
// Register emitters
particles.Emitters.Add(sparks);
particles.Emitters.Add(smoke);

Definition at line 75 of file ParticleSurface.cs.

Constructor & Destructor Documentation

◆ ParticleSurface() [1/2]

Gondwana.Drawing.Direct.Particles.ParticleSurface.ParticleSurface	(	RenderSurfaceHostBase	renderSurfaceHost,
		SceneLayer	sceneLayer,
		Rectangle?	worldBounds,
		string?	nickname = null,
		int	maxParticles = 2000,
		SKBitmap?	particleSprite = null )

Initializes a new instance of the ParticleSurface class for scene layer rendering with world-space coordinate bounds.

Parameters

renderSurfaceHost	The render surface host managing this particle system.
sceneLayer	The scene layer to render particles on.
worldBounds	The world-space bounds for the particle system, or `null` for unbounded.
nickname	An optional friendly name for debugging and identification.
maxParticles	The maximum number of particles this system can manage simultaneously. Default is 2000.
particleSprite	An optional bitmap texture to use for particles instead of circles.

Definition at line 210 of file ParticleSurface.cs.

◆ ParticleSurface() [2/2]

Gondwana.Drawing.Direct.Particles.ParticleSurface.ParticleSurface	(	RenderSurfaceHostBase	renderSurfaceHost,
		View	view,
		Rectangle?	screenBounds,
		string?	nickname = null,
		int	maxParticles = 2000,
		SKBitmap?	particleSprite = null )

Initializes a new instance of the ParticleSurface class for view-based rendering with screen-space coordinate bounds.

Parameters

renderSurfaceHost	The render surface host managing this particle system.
view	The view to render particles on.
screenBounds	The screen-space bounds for the particle system, or `null` for unbounded.
nickname	An optional friendly name for debugging and identification.
maxParticles	The maximum number of particles this system can manage simultaneously. Default is 2000.
particleSprite	An optional bitmap texture to use for particles instead of circles.

Definition at line 237 of file ParticleSurface.cs.

Member Function Documentation

◆ Burst()

void Gondwana.Drawing.Direct.Particles.ParticleSurface.Burst	(	ParticleEmitter	emitter,
		int	count )

Immediately spawns a fixed number of particles from the given emitter. Useful for explosions, impacts, or click/tap feedback.

Parameters

emitter	Configured emitter providing ranges and color.
count	Number of particles to spawn instantly.

// Explosion at point P
var boom = new ParticleEmitter {
    Position = P, EmitRate = 0,
    LifeRange = (0.3f, 0.7f),
    VelocityRangeX = (-600f, 600f),
    VelocityRangeY = (-600f, 600f),
    SizeRange = (3f, 6f), Color = SKColors.OrangeRed
};
particles.Burst(boom, 150);

◆ Dispose()

override void Gondwana.Drawing.Direct.Particles.ParticleSurface.Dispose ( bool disposing )

protectedvirtual

Releases the particle array back to the pool and disposes managed resources.

Parameters

disposing True if disposing managed resources; false if called from finalizer.

Reimplemented from Gondwana.Drawing.Direct.DirectDrawingBase.

Definition at line 279 of file ParticleSurface.cs.

◆ OnDraw()

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

protected

Renders all live particles to the current backbuffer.

Draws each particle as either a Skia circle or a textured quad (if a sprite is provided). Alpha fades with age. Uses additive blending (global::SkiaSharp.SKBlendMode.Plus) by default for bright/glowy effects.

Do not call this directly. Once the system is registered with DirectDrawingManager, the manager invokes Render() during the host's render pass.

// One-time setup
directDrawingManager.AddOrReplace(particles);
 
// In your render step (host-driven):
renderSurfaceHost.Render();   // manager calls Render() on each drawable
 
// If you must force an extra redraw (e.g., after a burst):
particles.Invalidate();       // mark dirty so the manager re-renders

Parameters

backbuffer	The backbuffer receiving the drawing commands.
destRectScreen	The destination rectangle in screen pixels.

Definition at line 407 of file ParticleSurface.cs.

◆ Update()

override void Gondwana.Drawing.Direct.Particles.ParticleSurface.Update ( long tick )

virtual

Tick-driven update override. Computes delta internally and advances simulation.

Parameters

tick	Current tick from HighResTimer.

Reimplemented from Gondwana.Drawing.Direct.DirectDrawingMovableBase.

Definition at line 295 of file ParticleSurface.cs.

Member Data Documentation

◆ Emitters

readonly List<ParticleEmitter> Gondwana.Drawing.Direct.Particles.ParticleSurface.Emitters = new()

Collection of particle emitters this system updates and renders. Add multiple emitters (e.g., sparks + smoke) to layer effects.

Definition at line 90 of file ParticleSurface.cs.

Property Documentation

◆ ActiveParticleCount

int Gondwana.Drawing.Direct.Particles.ParticleSurface.ActiveParticleCount

get

Gets the current number of active (alive) particles being simulated.

Definition at line 95 of file ParticleSurface.cs.

◆ CullingMarginX

float Gondwana.Drawing.Direct.Particles.ParticleSurface.CullingMarginX = 32f

getset

Gets or sets the horizontal culling margin, in pixels, beyond the bounds of the viewport to keep elements active.

Definition at line 178 of file ParticleSurface.cs.

◆ CullingMarginY

float Gondwana.Drawing.Direct.Particles.ParticleSurface.CullingMarginY = 32f

getset

Gets or sets the vertical culling margin, in pixels, beyond the bounds of the viewport to keep elements active.

Definition at line 183 of file ParticleSurface.cs.

◆ GlobalColorTint

SKColor Gondwana.Drawing.Direct.Particles.ParticleSurface.GlobalColorTint = SKColors.White

getset

Global tint color multiplied against every particle's own color during rendering.

Useful for quickly recoloring or fading an entire particle system without touching individual emitters.

Defaults to SKColors.White, which leaves particles unchanged. Setting alpha here provides an additional global fade, stacked with per-particle fading.

The following demonstrates how to apply a global tint:

var particles = new DirectParticles(renderHost, viewportBounds);
 
// Render all particles with a blue tint
particles.GlobalColorTint = new SKColor(128, 160, 255, 255);
 
// Fade entire system to transparent over time
particles.GlobalColorTint = particles.GlobalColorTint.WithAlpha(
    (byte)MathF.Max(0, particles.GlobalColorTint.Alpha - 200 * deltaTime));

Definition at line 160 of file ParticleSurface.cs.

◆ GlobalEmitScale

float Gondwana.Drawing.Direct.Particles.ParticleSurface.GlobalEmitScale = 1f

getset

Global multiplier applied to all emitter EmitRate values in this particle system. Acts like a master volume knob for particle density.

A value of 1.0 leaves emit rates unchanged.
Values greater than 1 increase overall particle output, while values between 0 and 1 reduce it.

Setting this to 0 effectively pauses emission without disabling or removing individual emitters.

The following demonstrates how to smoothly fade out an effect by reducing GlobalEmitScale over time:

// Particle system created and auto-registered by base class
var particles = new DirectParticles(renderHost, viewportBounds);
 
// Start at full intensity
particles.GlobalEmitScale = 1.0f;
 
// Later, during update (e.g., shutting down effect):
particles.GlobalEmitScale = MathF.Max(0f,
    particles.GlobalEmitScale - 0.5f * deltaTime); // fade out in ~2s

Definition at line 129 of file ParticleSurface.cs.

◆ GravityX

float Gondwana.Drawing.Direct.Particles.ParticleSurface.GravityX = 0f

getset

Gets or sets the horizontal component of gravity, measured in pixels per second squared. Default is 0 (no horizontal gravity).

Definition at line 166 of file ParticleSurface.cs.

◆ GravityY

float Gondwana.Drawing.Direct.Particles.ParticleSurface.GravityY = 400f

getset

Gets or sets the gravitational acceleration along the Y-axis, measured in pixels per second squared. Default is 400 (downward).

Definition at line 172 of file ParticleSurface.cs.

Public Member Functions

Public Attributes

Protected Member Functions

Properties

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ParticleSurface() [1/2]

◆ ParticleSurface() [2/2]

Member Function Documentation

◆ Burst()

◆ Dispose()

◆ OnDraw()

◆ Update()

Member Data Documentation

◆ Emitters

Property Documentation

◆ ActiveParticleCount

◆ CullingMarginX

◆ CullingMarginY

◆ GlobalColorTint

◆ GlobalEmitScale

◆ GravityX

◆ GravityY