Draws video frames provided by IVideoPlayer onto the backbuffer. Audio is handled by the IVideoPlayer implementation (e.g., VLC system output on desktop). More...

Inheritance diagram for Gondwana.Drawing.Direct.DirectVideo:

Public Member Functions
	DirectVideo (IVideoPlayer player, Uri source, RenderSurfaceHostBase renderSurfaceHost, SceneLayer sceneLayer, Rectangle? worldBounds, string? name=null)
	Initializes a new instance of the DirectVideo class that renders to a specific SceneLayer using world coordinates.
	DirectVideo (IVideoPlayer player, Uri source, RenderSurfaceHostBase renderSurfaceHost, View view, Rectangle? screenBounds, string? name=null)
	Initializes a new instance of the DirectVideo class that renders to a specific View using screen coordinates.
	DirectVideo (Func< IVideoPlayer > playerFactory, Uri source, RenderSurfaceHostBase renderSurfaceHost, SceneLayer sceneLayer, Rectangle? worldBounds, string? name=null)
	Initializes a new instance of the DirectVideo class using a factory to create the player, rendering to a specific SceneLayer using world coordinates.
	DirectVideo (Func< IVideoPlayer > playerFactory, Uri source, RenderSurfaceHostBase renderSurfaceHost, View view, Rectangle? screenBounds, string? name=null)
	Initializes a new instance of the DirectVideo class using a factory to create the player, rendering to a specific View using screen coordinates.
void	Play ()
	Starts or resumes video playback.
void	Pause ()
	Pauses video playback at the current position.
void	Stop ()
	Stops video playback and resets the playback position to the beginning.
void	Seek (TimeSpan position)
	Seeks to a specific position in the video timeline.
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.
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.
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
StretchMode	Stretch = StretchMode.Fill `[get, set]`
	Gets or sets the stretch mode that determines how the video frame is scaled to fit within the destination bounds.
float	Opacity `[get, set]`
	Gets or sets the opacity level of the video overlay.
double	PlaybackRate `[get, set]`
	Gets or sets the playback speed multiplier.
bool	Loop `[get, set]`
	Gets or sets a value indicating whether the video should automatically restart from the beginning when it reaches the end.
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

Draws video frames provided by IVideoPlayer onto the backbuffer. Audio is handled by the IVideoPlayer implementation (e.g., VLC system output on desktop).

*** Basic Playback (fixed size in a HUD corner): var clip = new DirectVideo(surface, new Rectangle(64, 64, 640, 360), playerFactory: () => videoPlayerFactory.Create(), source: new Uri("file:///C:/media/intro.mp4")) { ZOrder = 100, // above tiles/UI as needed Stretch = StretchMode.Uniform, // preserve aspect, fit inside box Loop = false };

*** Full-bleed Cutscene (cover viewport, crop overflow): var cutscene = new DirectVideo(surface, viewportBounds, () => videoPlayerFactory.Create(), new Uri("file:///C:/media/cutscene.mkv")) { ZOrder = 1000, Stretch = StretchMode.UniformToFill, // cover the whole bounds Opacity = 1.0f, Loop = false };

*** Faded Picture-in-Picture (overlay, semi-transparent): var pip = new DirectVideo(surface, new Rectangle(20, 20, 320, 180), () => videoPlayerFactory.Create(), new Uri("file:///C:/media/camfeed.webm")) { ZOrder = 500, Stretch = StretchMode.Fill, // ignore AR, fill the box Opacity = 0.75f, Loop = true };

*** Playback Control (pause/seek/rate) during your update tick: // Pause on a modal if (ui.ShowingModal) pip.Pause();

// Resume when modal closes if (!ui.ShowingModal && !pipIsPlaying) pip.Play();

// Jump to 10s (for scrubbing thumbnails or replays) pip.Seek(TimeSpan.FromSeconds(10));

// Slow-mo or fast-forward pip.PlaybackRate = 0.5; // half-speed // pip.PlaybackRate = 1.25; // 25% faster

*** Swap Source (re-use the same player instance path): var trailer = new DirectVideo(surface, new Rectangle(80, 80, 960, 540), myExistingIVideoPlayerInstance, new Uri("file:///C:/media/trailer.mp4")) { Stretch = StretchMode.Uniform, Opacity = 1.0f };

*** Animated Slide-in (using your engine's movement/scrolling): // Start off-screen, then slide into position over 0.4s cutscene.ScrollToSourceGridPoint(0.4, new Rectangle(0, 0, viewportBounds.Width, viewportBounds.Height));

Constructor & Destructor Documentation

◆ DirectVideo() [1/4]

Gondwana.Drawing.Direct.DirectVideo.DirectVideo	(	IVideoPlayer	player,
		Uri	source,
		RenderSurfaceHostBase	renderSurfaceHost,
		SceneLayer	sceneLayer,
		Rectangle?	worldBounds,
		string?	name = null )

Initializes a new instance of the DirectVideo class that renders to a specific SceneLayer using world coordinates.

Parameters

player	The video player instance responsible for decoding and providing frames.
source	The URI of the video source to play.
renderSurfaceHost	The render surface host that will display the video.
sceneLayer	The scene layer to which this video will be attached.
worldBounds	The rectangular bounds in world coordinates where the video will be rendered. If `null`, the video's natural size will be used.
name	An optional name for this video instance, useful for debugging or identification.

Exceptions

ArgumentNullException Thrown if player is null.

The video begins playing automatically after initialization.

◆ DirectVideo() [2/4]

Gondwana.Drawing.Direct.DirectVideo.DirectVideo	(	IVideoPlayer	player,
		Uri	source,
		RenderSurfaceHostBase	renderSurfaceHost,
		View	view,
		Rectangle?	screenBounds,
		string?	name = null )

Initializes a new instance of the DirectVideo class that renders to a specific View using screen coordinates.

Parameters

player	The video player instance responsible for decoding and providing frames.
source	The URI of the video source to play.
renderSurfaceHost	The render surface host that will display the video.
view	The view to which this video will be attached.
screenBounds	The rectangular bounds in screen coordinates where the video will be rendered. If `null`, the video's natural size will be used.
name	An optional name for this video instance, useful for debugging or identification.

Exceptions

ArgumentNullException Thrown if player is null.

This constructor is useful for HUD overlays, menus, or other UI-aligned video elements. The video begins playing automatically after initialization.

◆ DirectVideo() [3/4]

Gondwana.Drawing.Direct.DirectVideo.DirectVideo	(	Func< IVideoPlayer >	playerFactory,
		Uri	source,
		RenderSurfaceHostBase	renderSurfaceHost,
		SceneLayer	sceneLayer,
		Rectangle?	worldBounds,
		string?	name = null )

Initializes a new instance of the DirectVideo class using a factory to create the player, rendering to a specific SceneLayer using world coordinates.

Parameters

playerFactory	A factory function that creates and returns an IVideoPlayer instance. This allows for platform-specific player implementations or dependency injection patterns.
source	The URI of the video source to play.
renderSurfaceHost	The render surface host that will display the video.
sceneLayer	The scene layer to which this video will be attached.
worldBounds	The rectangular bounds in world coordinates where the video will be rendered. If `null`, the video's natural size will be used.
name	An optional name for this video instance, useful for debugging or identification.

Exceptions

ArgumentNullException Thrown if playerFactory is null.

The factory pattern is useful when the player implementation varies by platform (e.g., VLC on desktop, HTML5 on web). The video begins playing automatically after initialization.

◆ DirectVideo() [4/4]

Gondwana.Drawing.Direct.DirectVideo.DirectVideo	(	Func< IVideoPlayer >	playerFactory,
		Uri	source,
		RenderSurfaceHostBase	renderSurfaceHost,
		View	view,
		Rectangle?	screenBounds,
		string?	name = null )

Initializes a new instance of the DirectVideo class using a factory to create the player, rendering to a specific View using screen coordinates.

Parameters

playerFactory	A factory function that creates and returns an IVideoPlayer instance. This allows for platform-specific player implementations or dependency injection patterns.
source	The URI of the video source to play.
renderSurfaceHost	The render surface host that will display the video.
view	The view to which this video will be attached.
screenBounds	The rectangular bounds in screen coordinates where the video will be rendered. If `null`, the video's natural size will be used.
name	An optional name for this video instance, useful for debugging or identification.

Exceptions

ArgumentNullException Thrown if playerFactory is null.

This constructor is useful for HUD overlays, menus, or other UI-aligned video elements. The factory pattern allows for platform-specific implementations. The video begins playing automatically after initialization.

Member Function Documentation

◆ Dispose()

override void Gondwana.Drawing.Direct.DirectVideo.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.

Override this method in derived classes to release additional resources. Always call base.Dispose(disposing) to ensure proper cleanup of the base class.

Reimplemented from Gondwana.Drawing.Direct.DirectDrawingBase.

◆ OnDraw()

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

protected

◆ Pause()

void Gondwana.Drawing.Direct.DirectVideo.Pause ( )

Pauses video playback at the current position.

While paused, the current frame remains visible on screen. Call Play to resume playback from the paused position.

◆ Play()

void Gondwana.Drawing.Direct.DirectVideo.Play ( )

Starts or resumes video playback.

If the video is paused, this method resumes playback from the current position. If the video has not yet started, this method begins playback from the beginning. This method is called automatically during initialization.

◆ Seek()

void Gondwana.Drawing.Direct.DirectVideo.Seek ( TimeSpan position )

Seeks to a specific position in the video timeline.

Parameters

position The target position to seek to, specified as a TimeSpan from the beginning of the video.

Seeking may not be frame-accurate depending on the video codec and player implementation. Most players will seek to the nearest keyframe before or at the specified position.

This method can be called while the video is playing or paused.

// Seek to 30 seconds into the video
video.Seek(TimeSpan.FromSeconds(30));
 
// Seek to 2 minutes and 15 seconds
video.Seek(new TimeSpan(0, 2, 15));

◆ Stop()

void Gondwana.Drawing.Direct.DirectVideo.Stop ( )

Stops video playback and resets the playback position to the beginning.

After calling this method, the video will return to its first frame. Call Play to start playback again from the beginning.

Property Documentation

◆ Loop

bool Gondwana.Drawing.Direct.DirectVideo.Loop

getset

Gets or sets a value indicating whether the video should automatically restart from the beginning when it reaches the end.

When set to true, the video will continuously play in a loop. When set to false, playback stops when the video reaches its end.

true to enable looping; otherwise, false.

◆ Opacity

float Gondwana.Drawing.Direct.DirectVideo.Opacity

getset

Gets or sets the opacity level of the video overlay.

This value controls the alpha transparency applied to the entire video frame during rendering. Values are automatically clamped to the valid range.

A floating-point value between 0.0 (fully transparent) and 1.0 (fully opaque). The default value is 1.0.

◆ PlaybackRate

double Gondwana.Drawing.Direct.DirectVideo.PlaybackRate

getset

Gets or sets the playback speed multiplier.

This property controls the rate at which the video plays relative to its normal speed. Setting this value updates the underlying IVideoPlayer immediately.

Common values:

0.5 - Half speed (slow motion)
1.0 - Normal speed
1.5 - 50% faster
2.0 - Double speed

A multiplier for playback speed. The default value is 1.0 (normal speed).

◆ Stretch

StretchMode Gondwana.Drawing.Direct.DirectVideo.Stretch = StretchMode.Fill

getset

Gets or sets the stretch mode that determines how the video frame is scaled to fit within the destination bounds.

StretchMode.None - Video displays at its native resolution.
StretchMode.Fill - Video fills the entire bounds, ignoring aspect ratio.
StretchMode.Uniform - Video scales to fit inside bounds while preserving aspect ratio (letterboxing/pillarboxing as needed).
StretchMode.UniformToFill - Video scales to fill the entire bounds while preserving aspect ratio (cropping as needed).

The default value is StretchMode.Fill.

Public Member Functions

Protected Member Functions

Properties

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ DirectVideo() [1/4]

◆ DirectVideo() [2/4]

◆ DirectVideo() [3/4]

◆ DirectVideo() [4/4]

Member Function Documentation

◆ Dispose()

◆ OnDraw()

◆ Pause()

◆ Play()

◆ Seek()

◆ Stop()

Property Documentation

◆ Loop

◆ Opacity

◆ PlaybackRate

◆ Stretch