Provides an abstract base class for direct drawings that support physics-based movement. More...

Inheritance diagram for Gondwana.Drawing.Direct.DirectDrawingMovableBase:

Public Member Functions
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.
override void	Update (long tick)
	Advances this direct drawing's movement using the elapsed time since its previous update, then performs the standard direct-drawing update logic.
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
	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.
virtual void	Dispose (bool disposing)
	Releases resources used by this DirectDrawingBase instance.

Properties
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

Provides an abstract base class for direct drawings that support physics-based movement.

DirectDrawingMovableBase extends DirectDrawingBase with integrated movement capabilities via the MovementController. It implements IMovable to participate in the engine's movement, enabling direct drawings to move smoothly, respond to forces, and interact with other movable objects.

Key features:

Fixed-timestep physics integration at 240 Hz for stable, deterministic movement.
Automatic position synchronization between the movement controller and drawing bounds.
Support for both world-space (scene-layer mode) and screen-space (view mode) movement.
Frame-rate independent physics with accumulator and substep clamping to prevent spiral of death.

The class uses a fixed-timestep update loop (240 Hz / ~4.16ms per step) to advance movement physics, ensuring consistent behavior regardless of the application frame rate. Each frame's variable delta time is accumulated and subdivided into fixed steps, with a maximum substep limit to prevent performance degradation during frame rate drops.

Derived classes must implement DirectDrawingBase.OnDraw to perform the actual rendering. The base class handles position updates and ensures drawing bounds remain synchronized with the Movement controller's position.

Thread safety: This class is not thread-safe. All operations should be performed on the UI thread.

Definition at line 45 of file DirectDrawingMovableBase.cs.

Constructor & Destructor Documentation

◆ DirectDrawingMovableBase()

Gondwana.Drawing.Direct.DirectDrawingMovableBase.DirectDrawingMovableBase	(	RenderSurfaceHostBase	renderSurfaceHost,
		DirectDrawingMode	mode,
		SceneLayer?	sceneLayer,
		View?	view,
		Rectangle?	screenBounds,
		Rectangle?	worldBounds,
		string?	name = null )

protected

Initializes a new instance of the DirectDrawingMovableBase class with integrated movement capabilities.

Parameters

renderSurfaceHost	The render surface host that manages rendering for this direct drawing. Must not be `null`.
mode	The drawing mode determining how this object is positioned and transformed.
sceneLayer	The scene layer to which this drawing is attached (required if mode is DirectDrawingMode.SceneLayer).
view	The view to which this drawing is attached (required if mode is DirectDrawingMode.View).
screenBounds	The screen-space bounds in pixels (required if mode is DirectDrawingMode.View).
worldBounds	The world-space bounds in pixels (required if mode is DirectDrawingMode.SceneLayer).
name	An optional human-readable name for this direct drawing, useful for debugging and identification.

Exceptions

ArgumentNullException	Thrown when renderSurfaceHost is `null`.
ArgumentException	Thrown when required parameters for the specified mode are `null`. See DirectDrawingBase constructor documentation for details.

The constructor initializes the Movement controller with the drawing's initial position extracted from the provided bounds (either worldBounds or screenBounds depending on the mode). The movement controller is configured for pixel-space movement matching the drawing's coordinate system.

After construction, use the Movement property to configure velocity, acceleration, friction, and other movement parameters. The drawing's position will automatically update each frame based on the movement controller's physics simulation.

Definition at line 77 of file DirectDrawingMovableBase.cs.

Member Function Documentation

◆ GetPosition()

Vector2 Gondwana.Drawing.Direct.DirectDrawingMovableBase.GetPosition ( )

Gets the current position of this direct drawing in pixel coordinates.

Returns: A Vector2 representing the top-left corner position. For scene-layer mode, this is the world-space position. For view mode, this is the screen-space position.

This method is part of the IMovable interface contract and is used by the MovementController to query the current position during physics integration.

The position corresponds to the X and Y coordinates of the drawing's bounding rectangle (DirectDrawingBase.WorldBounds for scene-layer mode or DirectDrawingBase.ScreenBounds for view mode).

Implements Gondwana.Physics.Movement.IMovable.

◆ SetPosition()

void Gondwana.Drawing.Direct.DirectDrawingMovableBase.SetPosition ( Vector2 p )

Sets the position of this direct drawing to the specified pixel coordinates.

Parameters

p	The new position as a Vector2. The X and Y components specify the top-left corner. For scene-layer mode, this is the world-space position. For view mode, this is the screen-space position.

This method is part of the IMovable interface contract and is used by the MovementController to apply position changes resulting from physics integration.

The method performs the following operations:

Marks the current position as dirty (via DirectDrawingBase.ForceRefresh).
Rounds the vector components to the nearest integer to maintain pixel-aligned positioning.
Updates the appropriate bounds rectangle (world or screen) with the new position while preserving width and height.
Marks the new position as dirty to ensure rendering occurs at the updated location.

Calling this method directly (outside of movement controller integration) will move the drawing but may not update the movement controller's internal state. To manually reposition a movable drawing, consider setting Movement.State.Position instead.

Implements Gondwana.Physics.Movement.IMovable.

Definition at line 201 of file DirectDrawingMovableBase.cs.

◆ Update()

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

virtual

Advances this direct drawing's movement using the elapsed time since its previous update, then performs the standard direct-drawing update logic.

Parameters

tick	The current engine tick value supplied by the direct-drawing update cycle.

Movement is advanced once per engine update using the actual elapsed duration calculated from DirectDrawingBase._lastTick and tick .

The base implementation is called afterward to advance inherited behavior, including fade and reveal animations, and to record the current tick.

Reimplemented from Gondwana.Drawing.Direct.DirectDrawingBase.

Reimplemented in Gondwana.Drawing.Direct.DirectRectangle, Gondwana.Drawing.Direct.DirectVideo, Gondwana.Drawing.Direct.ImageLayer.ImageInstanceLayer, Gondwana.Drawing.Direct.Particles.ParticleSurface, and Gondwana.Drawing.Direct.TextBlock.

Definition at line 267 of file DirectDrawingMovableBase.cs.

Property Documentation

◆ Movement

MovementController Gondwana.Drawing.Direct.DirectDrawingMovableBase.Movement

get

Gets the movement controller responsible for changing this direct drawing's position over time.

A MovementController configured to move this drawing in MovementSpace.Pixel.

The controller supports follow, scripted, and integrated movement:

Follow movement continuously tracks a live pixel-space or grid-space target.
Scripted movement performs authored operations such as MoveTo, MoveBy, and MoveToward.
Integrated movement advances velocity, acceleration, maximum-speed limits, and linear damping over time.

Movement coordinates represent the drawing's upper-left position. For DirectDrawingMode.SceneLayer drawings, they are world pixels. For DirectDrawingMode.View drawings, they are absolute screen pixels.

The controller is advanced automatically by Update(long) once per engine update using the actual elapsed duration. Game code should configure movement through this property rather than calling AdvanceMovement directly.

Definition at line 137 of file DirectDrawingMovableBase.cs.

◆ PositionSpace

MovementSpace Gondwana.Drawing.Direct.DirectDrawingMovableBase.PositionSpace

get

Gets the coordinate space in which this movable object's position is expressed.

Always returns MovementSpace.Pixel, indicating that position values are in pixel coordinates.

This property is part of the IMovable interface contract. Direct drawings always use pixel-space positioning, regardless of whether they are in scene-layer mode (world pixels) or view mode (screen pixels).

Implements Gondwana.Physics.Movement.IMovable.

Definition at line 150 of file DirectDrawingMovableBase.cs.

Public Member Functions

Protected Member Functions

Properties

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ DirectDrawingMovableBase()

Member Function Documentation

◆ GetPosition()

◆ SetPosition()

◆ Update()

Property Documentation

◆ Movement

◆ PositionSpace