Represents a lightweight image-instance layer that manages and renders a collection of independently moving bitmap instances. More...

Inheritance diagram for Gondwana.Drawing.Direct.ImageLayer.ImageInstanceLayer:

Public Member Functions
	ImageInstanceLayer (RenderSurfaceHostBase renderSurfaceHost, View view, Rectangle screenBounds, string? nickname=null)
	Initializes a new instance of the ImageInstanceLayer class.
	ImageInstanceLayer (RenderSurfaceHostBase renderSurfaceHost, SceneLayer sceneLayer, Rectangle worldBounds, string? nickname=null)
	Initializes a new instance of the ImageInstanceLayer class for scene-layer rendering.
	ImageInstanceLayer (RenderSurfaceHostBase renderSurfaceHost, View view, Rectangle screenBounds, Func< Rectangle, Random, IEnumerable< ImageInstance > >? initializer, Func< ImageInstance, Rectangle, bool >? shouldRecycle=null, Func< ImageInstance, Rectangle, Random, ImageInstance >? recycleInstance=null, Action< ImageInstance, float >? updateInstance=null, string? nickname=null)
	Initializes a new instance of the ImageInstanceLayer class and assigns optional hooks.
	ImageInstanceLayer (RenderSurfaceHostBase renderSurfaceHost, SceneLayer sceneLayer, Rectangle worldBounds, Func< Rectangle, Random, IEnumerable< ImageInstance > >? initializer, Func< ImageInstance, Rectangle, bool >? shouldRecycle=null, Func< ImageInstance, Rectangle, Random, ImageInstance >? recycleInstance=null, Action< ImageInstance, float >? updateInstance=null, string? nickname=null)
	Initializes a new instance of the ImageInstanceLayer class for scene-layer rendering and assigns optional hooks.
void	InitializeInstances ()
	Clears the current instance collection and rebuilds it using Initializer, if one is assigned.
override void	Update (long tick)
	Updates all instances, applying built-in motion, optional custom updates, and optional recycling behavior.
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.

Protected Member Functions
override void	OnDraw (BackbufferBase backbuffer, RectangleF destRectScreen)
	Renders all image instances to the backbuffer.
override void	Dispose (bool disposing)
	Disposes managed resources.
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
List< ImageInstance >	Instances = new() `[get]`
	Gets the collection of image instances managed by this layer.
Func< Rectangle, Random, IEnumerable< ImageInstance > >?	Initializer `[get, set]`
	Gets or sets an optional callback used to populate the initial set of instances.
Func< ImageInstance, Rectangle, bool >?	ShouldRecycle `[get, set]`
	Gets or sets an optional callback used to determine whether an instance should be recycled.
Func< ImageInstance, Rectangle, Random, ImageInstance >?	RecycleInstance `[get, set]`
	Gets or sets an optional callback used to create a replacement instance when recycling occurs.
Action< ImageInstance, float >?	UpdateInstance `[get, set]`
	Gets or sets an optional callback invoked after the built-in motion update for each instance.
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

Represents a lightweight image-instance layer that manages and renders a collection of independently moving bitmap instances.

This class is intended for effects composed of relatively few, larger visual elements, such as drifting clouds, fog patches, leaves, embers, or other ambient visuals.

Unlike particle-style systems that are optimized for very large numbers of tiny, short-lived particles, this layer is designed for persistent, individually managed image instances.

Each instance tracks its own position, velocity, rotation, and tint. The layer updates instance state over time and marks the affected regions as dirty for redraw.

This class may be used in two styles:

Manual mode: callers add and manage Instances directly and optionally provide recycle logic.
Delegate-assisted mode: callers provide optional hooks for initial population, per-instance update customization, and recycle behavior.

Manual usage:

var layer = new ImageInstanceLayer(renderHost, view, bounds);
 
layer.Instances.Add(new ImageInstance
{
    Bitmap = bmp,
    Bounds = new RectangleF(100, 50, 200, 120),
    VelocityX = -10f,
    Tint = new SKColor(255, 255, 255, 140)
});
 
layer.ShouldRecycle = (instance, area) => instance.Bounds.Right < area.Left;
 
layer.RecycleInstance = (old, area, rng) => new ImageInstance
{
    Bitmap = old.Bitmap,
    Bounds = new RectangleF(area.Right + 40, old.Bounds.Y, old.Bounds.Width, old.Bounds.Height),
    VelocityX = old.VelocityX,
    Tint = old.Tint
};

Delegate-assisted usage:

var layer = new ImageInstanceLayer(
    renderHost,
    view,
    bounds,
    initializer: (area, rng) =>
    {
        var list = new List<ImageInstance>();
 
        for (int i = 0; i < 8; i++)
        {
            list.Add(new ImageInstance
            {
                Bitmap = variants[rng.Next(variants.Length)],
                Bounds = new RectangleF(
                    area.Left + (float)rng.NextDouble() * area.Width,
                    area.Top + (float)rng.NextDouble() * area.Height,
                    180f,
                    90f),
                VelocityX = -12f,
                Tint = new SKColor(255, 255, 255, (byte)rng.Next(70, 141))
            });
        }
 
        return list;
    },
    shouldRecycle: (instance, area) => instance.Bounds.Right < area.Left,
    recycleInstance: (old, area, rng) =>
    {
        old.Bounds = new RectangleF(area.Right + 40, old.Bounds.Y, old.Bounds.Width, old.Bounds.Height);
        return old;
    });

Definition at line 107 of file ImageInstanceLayer.cs.

Constructor & Destructor Documentation

◆ ImageInstanceLayer() [1/4]

Gondwana.Drawing.Direct.ImageLayer.ImageInstanceLayer.ImageInstanceLayer	(	RenderSurfaceHostBase	renderSurfaceHost,
		View	view,
		Rectangle	screenBounds,
		string?	nickname = null )

Initializes a new instance of the ImageInstanceLayer class.

Parameters

renderSurfaceHost	The render surface host managing this layer.
view	The view to render into.
screenBounds	The screen-space bounds for this layer.
nickname	Optional friendly name for debugging.

Definition at line 234 of file ImageInstanceLayer.cs.

◆ ImageInstanceLayer() [2/4]

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

Initializes a new instance of the ImageInstanceLayer class for scene-layer rendering.

Parameters

renderSurfaceHost	The render surface host managing this layer.
sceneLayer	The scene layer to render into.
worldBounds	The world-space bounds for this layer.
nickname	Optional friendly name for debugging.

Definition at line 255 of file ImageInstanceLayer.cs.

◆ ImageInstanceLayer() [3/4]

Gondwana.Drawing.Direct.ImageLayer.ImageInstanceLayer.ImageInstanceLayer	(	RenderSurfaceHostBase	renderSurfaceHost,
		View	view,
		Rectangle	screenBounds,
		Func< Rectangle, Random, IEnumerable< ImageInstance > >?	initializer,
		Func< ImageInstance, Rectangle, bool >?	shouldRecycle = null,
		Func< ImageInstance, Rectangle, Random, ImageInstance >?	recycleInstance = null,
		Action< ImageInstance, float >?	updateInstance = null,
		string?	nickname = null )

Initializes a new instance of the ImageInstanceLayer class and assigns optional hooks.

Parameters

renderSurfaceHost	The render surface host managing this layer.
view	The view to render into.
screenBounds	The screen-space bounds for this layer.
initializer	Optional callback used to create the initial set of instances.
shouldRecycle	Optional callback used to determine whether an instance should be recycled.
recycleInstance	Optional callback used to create a replacement instance when recycling occurs.
updateInstance	Optional callback invoked after the built-in motion update for each instance.
nickname	Optional friendly name for debugging.

Definition at line 280 of file ImageInstanceLayer.cs.

◆ ImageInstanceLayer() [4/4]

Gondwana.Drawing.Direct.ImageLayer.ImageInstanceLayer.ImageInstanceLayer	(	RenderSurfaceHostBase	renderSurfaceHost,
		SceneLayer	sceneLayer,
		Rectangle	worldBounds,
		Func< Rectangle, Random, IEnumerable< ImageInstance > >?	initializer,
		Func< ImageInstance, Rectangle, bool >?	shouldRecycle = null,
		Func< ImageInstance, Rectangle, Random, ImageInstance >?	recycleInstance = null,
		Action< ImageInstance, float >?	updateInstance = null,
		string?	nickname = null )

Initializes a new instance of the ImageInstanceLayer class for scene-layer rendering and assigns optional hooks.

Parameters

renderSurfaceHost	The render surface host managing this layer.
sceneLayer	The scene layer to render into.
worldBounds	The world-space bounds for this layer.
initializer	Optional callback used to create the initial set of instances.
shouldRecycle	Optional callback used to determine whether an instance should be recycled.
recycleInstance	Optional callback used to create a replacement instance when recycling occurs.
updateInstance	Optional callback invoked after the built-in motion update for each instance.
nickname	Optional friendly name for debugging.

Definition at line 310 of file ImageInstanceLayer.cs.

Member Function Documentation

◆ Dispose()

override void Gondwana.Drawing.Direct.ImageLayer.ImageInstanceLayer.Dispose ( bool disposing )

protectedvirtual

Disposes managed resources.

Parameters

disposing Whether managed resources should also be released.

Reimplemented from Gondwana.Drawing.Direct.DirectDrawingBase.

Definition at line 464 of file ImageInstanceLayer.cs.

◆ InitializeInstances()

void Gondwana.Drawing.Direct.ImageLayer.ImageInstanceLayer.InitializeInstances ( )

Clears the current instance collection and rebuilds it using Initializer, if one is assigned.

Definition at line 331 of file ImageInstanceLayer.cs.

◆ OnDraw()

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

protected

Renders all image instances to the backbuffer.

Parameters

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

Definition at line 412 of file ImageInstanceLayer.cs.

◆ Update()

override void Gondwana.Drawing.Direct.ImageLayer.ImageInstanceLayer.Update ( long tick )

virtual

Updates all instances, applying built-in motion, optional custom updates, and optional recycling behavior.

Parameters

tick	Current tick from HighResTimer.

Reimplemented from Gondwana.Drawing.Direct.DirectDrawingMovableBase.

Definition at line 350 of file ImageInstanceLayer.cs.

Property Documentation

◆ Initializer

Func<Rectangle, Random, IEnumerable<ImageInstance> >? Gondwana.Drawing.Direct.ImageLayer.ImageInstanceLayer.Initializer

getset

Gets or sets an optional callback used to populate the initial set of instances.

If assigned before calling InitializeInstances, the callback will be invoked to create the starting set of image instances.

The following demonstrates how to populate the layer with an initial set of instances:

layer.Initializer = (bounds, rng) =>
{
    var instances = new List<ImageInstance>();
 
    for (int i = 0; i < 8; i++)
    {
        instances.Add(new ImageInstance
        {
            Bitmap = variants[rng.Next(variants.Length)],
            Bounds = new RectangleF(
                bounds.Left + (float)rng.NextDouble() * bounds.Width,
                bounds.Top + (float)rng.NextDouble() * bounds.Height,
                180f,
                90f),
            VelocityX = -12f,
            Tint = new SKColor(255, 255, 255, (byte)rng.Next(70, 141))
        });
    }
 
    return instances;
};
 
layer.InitializeInstances();

Definition at line 160 of file ImageInstanceLayer.cs.

◆ Instances

List<ImageInstance> Gondwana.Drawing.Direct.ImageLayer.ImageInstanceLayer.Instances = new()

get

Gets the collection of image instances managed by this layer.

Definition at line 121 of file ImageInstanceLayer.cs.

◆ RecycleInstance

Func<ImageInstance, Rectangle, Random, ImageInstance>? Gondwana.Drawing.Direct.ImageLayer.ImageInstanceLayer.RecycleInstance

getset

Gets or sets an optional callback used to create a replacement instance when recycling occurs.

The following demonstrates how to recycle instances that move off-screen by repositioning them on the opposite side:

layer.ShouldRecycle = (instance, bounds) =>
    instance.Bounds.Right < bounds.Left;
 
layer.RecycleInstance = (old, bounds, rng) =>
{
    return new ImageInstance
    {
        Bitmap = old.Bitmap,
        Bounds = new RectangleF(
            bounds.Right + (float)rng.NextDouble() * 100f,
            old.Bounds.Y,
            old.Bounds.Width,
            old.Bounds.Height),
        VelocityX = old.VelocityX,
        Tint = old.Tint
    };
};

Definition at line 201 of file ImageInstanceLayer.cs.

◆ ShouldRecycle

Func<ImageInstance, Rectangle, bool>? Gondwana.Drawing.Direct.ImageLayer.ImageInstanceLayer.ShouldRecycle

getset

Gets or sets an optional callback used to determine whether an instance should be recycled.

layer.ShouldRecycle = (instance, bounds) =>

instance.Bounds.Right < bounds.Left;

Definition at line 171 of file ImageInstanceLayer.cs.

◆ UpdateInstance

Action<ImageInstance, float>? Gondwana.Drawing.Direct.ImageLayer.ImageInstanceLayer.UpdateInstance

getset

Gets or sets an optional callback invoked after the built-in motion update for each instance.

The following demonstrates how to apply a custom per-instance update, such as a gentle vertical oscillation:

layer.UpdateInstance = (instance, dt) =>
{
    float amplitude = 10f;
    float speed = 2f;
 
    instance.Bounds = new RectangleF(
        instance.Bounds.X,
        instance.Bounds.Y + MathF.Sin(instance.Bounds.X * 0.01f * speed) * amplitude * dt,
        instance.Bounds.Width,
        instance.Bounds.Height);
};

Definition at line 225 of file ImageInstanceLayer.cs.

Public Member Functions

Protected Member Functions

Properties

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ImageInstanceLayer() [1/4]

◆ ImageInstanceLayer() [2/4]

◆ ImageInstanceLayer() [3/4]

◆ ImageInstanceLayer() [4/4]

Member Function Documentation

◆ Dispose()

◆ InitializeInstances()

◆ OnDraw()

◆ Update()

Property Documentation

◆ Initializer

◆ Instances

◆ RecycleInstance

◆ ShouldRecycle

◆ UpdateInstance