Table of Contents

Class VideoView

Namespace
VisioForge.Core.UI.WinUI
Assembly
VisioForge.Core.UI.WinUI.dll

Provides a high-performance video rendering control for WinUI 3 applications using Win2D CanvasControl.

[WinRTRuntimeClassName("Windows.Foundation.IClosable")]
[WinRTExposedType(typeof(VisioForge_Core_UI_WinUI_VideoViewWinRTTypeDetails))]
public class VideoView : IDisposable, INotifyPropertyChanged, IVideoView, IVideoViewPushFrame

Inheritance

Implements

IVideoView
IVideoViewPushFrame

Inherited Members

Remarks

This control renders video frames using Microsoft's Win2D library with hardware-accelerated DirectX rendering. It provides optimal performance for Windows applications through native WinUI 3 integration.

Key features:

  • DirectX-accelerated rendering via Win2D CanvasControl
  • Automatic aspect ratio preservation with letterboxing
  • Frame queue management to handle varying frame rates
  • Support for RGBA and BGRA pixel formats
  • Automatic colorspace conversion for RGB/BGR formats
  • Mouse/pointer and keyboard event handling
  • Thread-safe frame delivery via DispatcherQueue

The control implements VisioForge.Core.Types.IVideoView for integration with VisioForge media engines and VisioForge.Core.Types.IVideoViewPushFrame for receiving video frames.

Rendering pipeline:

  1. Frames arrive via VisioForge.Core.UI.WinUI.VideoView.PushFrame(VisioForge.Core.Types.VideoFrame) (typically on background thread)
  2. Frames are queued (max 5 frames to prevent memory buildup)
  3. Canvas invalidation triggers VisioForge.Core.UI.WinUI.VideoView.Canvas_Draw(Microsoft.Graphics.Canvas.UI.Xaml.CanvasControl,Microsoft.Graphics.Canvas.UI.Xaml.CanvasDrawEventArgs) on UI thread
  4. Frame is dequeued, converted to CanvasBitmap, and drawn with aspect ratio preservation
  5. Frame resources are freed after rendering

Constructors

VideoView(CanvasControl)

Initializes a new instance of the VisioForge.Core.UI.WinUI.VideoView class.

public VideoView(CanvasControl canvas)

Parameters

canvas CanvasControl

The Microsoft.Graphics.Canvas.UI.Xaml.CanvasControl used for hardware-accelerated rendering. Must not be null.

Remarks

The constructor attaches a draw handler to the provided CanvasControl for rendering video frames. The canvas should be properly initialized and added to the visual tree before video playback begins.

The control uses the CanvasControl's DirectX rendering surface for optimal performance with hardware acceleration. Frame rendering occurs during the Draw event with automatic invalidation when new frames arrive.

Exceptions

ArgumentNullException

Thrown when canvas is null.

Properties

StatusOverlay

Gets or sets the status overlay displayed during the connection phase before video streaming begins.

public IStatusOverlay StatusOverlay { get; set; }

Property Value

IStatusOverlay

Remarks

The status overlay is particularly useful for IP camera and streaming scenarios where there may be a delay between starting playback and receiving the first video frame. It provides visual feedback to users during the connection establishment phase.

The overlay is automatically shown after calling VisioForge.Core.UI.WinUI.VideoView.InvokeStart and hidden once video frames begin arriving or if an error occurs.

Use VisioForge.Core.Types.TextStatusOverlay as a convenient implementation for text-based overlays.

Video_Renderer

Gets the video renderer settings used for displaying video.

public VideoRendererSettings Video_Renderer { get; }

Property Value

VideoRendererSettings

Remarks

This property provides read-only access to the video renderer configuration from the attached media engine. The settings control aspects like stretch mode, rotation, and rendering technology.

The property returns null in the following cases:

  • No parent media engine is attached via VisioForge.Core.UI.WinUI.VideoView.Attach(VisioForge.Core.Types.IMPVCVECore)
  • The parent's Video_Renderer property is null

Changes to renderer settings should be made through the parent media engine, not directly.

Methods

Attach(IMPVCVECore)

Attaches a media engine core to this video view for video frame delivery.

public void Attach(IMPVCVECore parent)

Parameters

parent IMPVCVECore

The VisioForge.Core.Types.IMPVCVECore instance to attach. Must not be null.

Remarks

This method establishes the connection between the video view and the media engine:

  • Stores the parent reference
  • Subscribes to OnVideoFrameBufferWPF event for frame delivery

Once attached, the media engine will deliver video frames to this control via the OnVideoFrameBufferWPF event, which internally calls VisioForge.Core.UI.WinUI.VideoView.Core_OnVideoFrameBufferWPF(System.Object,VisioForge.Core.Types.Events.VideoFrameBufferEventArgs).

Call VisioForge.Core.UI.WinUI.VideoView.Detach(VisioForge.Core.Types.IMPVCVECore) before disposing the parent or switching to a different engine.

Exceptions

ArgumentNullException

Thrown when parent is null.

CallInvoke(Delegate, params object[])

Calls the invoke.

public void CallInvoke(Delegate method, params object[] args)

Parameters

method Delegate

The method.

args object[]

The arguments.

CallRefresh()

Calls the refresh.

public void CallRefresh()

ClearUI()

Clears the UI.

public void ClearUI()

Detach(IMPVCVECore)

Detaches the currently attached media engine from this video view.

public void Detach(IMPVCVECore parent)

Parameters

parent IMPVCVECore

The VisioForge.Core.Types.IMPVCVECore instance to detach. Should match the currently attached parent.

Remarks

This method cleans up the connection to the media engine:

  • Unsubscribes from OnVideoFrameBufferWPF event
  • Clears the parent reference

After detaching, the control will no longer receive frames from the media engine. It is safe to call this method when no parent is attached.

The parent parameter should match the instance passed to VisioForge.Core.UI.WinUI.VideoView.Attach(VisioForge.Core.Types.IMPVCVECore), though the method will proceed with cleanup regardless.

Dispose()

Dispose.

public void Dispose()

Dispose(bool)

Dispose.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

Disposing parameter.

~VideoView()

Finalizes an instance of the VisioForge.Core.UI.WinUI.VideoView class.

protected ~VideoView()

GetBackgroundColor()

Gets the background color of the video view.

public SKColor GetBackgroundColor()

Returns

SKColor

Always returns SkiaSharp.SKColors.Black for WinUI implementation.

Remarks

The WinUI video view always uses a black background, which is the standard appearance for video playback controls. Black fills any areas not covered by video content (letterboxing/pillarboxing) and is displayed when no video is playing.

The commented-out implementation in the code suggests future support for reading the actual background brush, but the current implementation always returns black for consistency and simplicity.

GetHandle()

Gets window handle.

public nint GetHandle()

Returns

nint

Returns IntPtr.

GetInvokeRequired()

Gets the invoke required.

public bool GetInvokeRequired()

Returns

bool

true if the invoke is required, false otherwise.

GetIsHandleCreated()

Gets the is handle created.

public bool GetIsHandleCreated()

Returns

bool

true if the handle is created, false otherwise.

GetSize()

Gets the actual size of the canvas control in pixels.

public Size GetSize()

Returns

Size

A VisioForge.Core.Types.Size structure containing the width and height of the canvas in pixels.

Remarks

This method returns the canvas's ActualWidth and ActualHeight, which represent the control's rendered size after layout. These values are used by the media engine to determine appropriate video scaling and aspect ratio calculations.

The size is retrieved from the CanvasControl's ActualWidth and ActualHeight properties, which reflect the control's size after XAML layout completes.

GetUIEngine()

Gets the UI engine type used by this video view.

public VideoViewUIEngine GetUIEngine()

Returns

VideoViewUIEngine

Always returns VisioForge.Core.Types.VideoViewUIEngine.WinUI for this WinUI 3 implementation.

Remarks

This method identifies the rendering technology used by the video view. For WinUI VideoView, it always returns WinUI to indicate Win2D/CanvasControl-based rendering.

This information is used by media engines to optimize frame delivery and select appropriate rendering paths.

InvokeStart()

Initiates video playback and prepares the rendering pipeline.

public void InvokeStart()

Remarks

This method is called internally when video playback starts. It performs the following:

  • Resets the frame stopped flag to allow rendering
  • Clears any stale frames from previous playback sessions
  • Attaches UI event handlers for pointer, mouse, and keyboard interaction

The frame queue is cleared to ensure no old frames from a previous session are displayed. This method must be called before video frames can be pushed and rendered.

InvokeStartComplete()

Invokes Start/Play.

public void InvokeStartComplete()

InvokeStop()

Stops video playback and releases all rendering resources.

public void InvokeStop()

Remarks

This method performs comprehensive cleanup of the rendering pipeline:

  • Sets the frame stopped flag to prevent further rendering
  • Clears the frame queue and frees all pending frames
  • Releases temporary frame buffers used for colorspace conversion
  • Frees native memory allocated for RGB/BGR to RGBA/BGRA conversion
  • Resets video dimensions
  • Forces canvas to redraw (clearing to black)

After calling this method, the canvas will display a black screen and the control is ready to start playback again via VisioForge.Core.UI.WinUI.VideoView.InvokeStart.

All memory cleanup is performed immediately to prevent resource leaks.

InvokeVideoRendererUpdate()

Updates the screen settings.

public void InvokeVideoRendererUpdate()

LogDialogClear()

Clears logs dialog.

public void LogDialogClear()

LogDialogClose()

Closes logs dialog.

public void LogDialogClose()

LogDialogError(string)

Logs the error in dialog.

public void LogDialogError(string msg)

Parameters

msg string

The message.

OnPropertyChanged(string)

OnPropertyChanged API.

protected virtual void OnPropertyChanged(string propertyName = null)

Parameters

propertyName string

Property name.

PictureBoxCreate(int, int)

Create the PictureBox.

public void PictureBoxCreate(int width, int height)

Parameters

width int

The width.

height int

The height.

PictureBoxDestroy()

Destroys the PictureBox.

public void PictureBoxDestroy()

PictureBoxExists()

Is the PictureBox exists.

public bool PictureBoxExists()

Returns

bool

true if exists, false otherwise.

PictureBoxGetImage()

Gets the PictureBox image.

public Bitmap PictureBoxGetImage()

Returns

Bitmap

Bitmap.

PictureBoxSetImage(Bitmap)

Set the image on PictureBox.

public void PictureBoxSetImage(Bitmap image)

Parameters

image Bitmap

The image.

PushFrame(VideoFrame)

Pushes a video frame to the rendering queue for display.

public void PushFrame(VideoFrame frame)

Parameters

frame VideoFrame

The VisioForge.Core.Types.VideoFrame to render. The frame is cloned before queueing.

Remarks

This method handles incoming video frames from the media engine:

  • Checks if rendering is stopped and ignores frames if so
  • Updates cached video dimensions from the frame
  • Manages queue size (max 5 frames) to prevent memory buildup
  • Clones the frame before queueing to prevent external modifications
  • Triggers canvas invalidation to render the frame

If the queue is full (>5 frames), the oldest frame is dequeued and freed before proceeding. This prevents memory issues but may result in frame drops during high frame rate scenarios.

The frame is processed asynchronously - it's queued and rendered on the next canvas draw cycle. The invalidation is performed via DispatcherQueue to ensure thread-safe UI updates.

PushFrame(VideoFrameX)

Pushes a video frame to the rendering queue for display.

public void PushFrame(VideoFrameX frame)

Parameters

frame VideoFrameX

The VisioForge.Core.Types.X.VideoFrameX to render. It will be converted to VisioForge.Core.Types.VideoFrame internally.

PushMouseButtonDown(int, int, MouseButton)

Pushes the mouse button down.

public void PushMouseButtonDown(int x, int y, MouseButton button)

Parameters

x int

The x.

y int

The y.

button MouseButton

The button.

PushMouseButtonUp(int, int, MouseButton)

Pushes the mouse button up.

public void PushMouseButtonUp(int x, int y, MouseButton button)

Parameters

x int

The x.

y int

The y.

button MouseButton

The button.

PushMouseMove(int, int)

Pushes the mouse move.

public void PushMouseMove(int x, int y)

Parameters

x int

The x.

y int

The y.

ResizeRoundTo(int)

Resizes the VideoView round to value.

public void ResizeRoundTo(int round)

Parameters

round int

The value.

SetHandle(nint)

Sets the handle. Not implemented.

public void SetHandle(nint handle)

Parameters

handle nint

The handle.

ShowMessage(string)

Shows the message.

public MessageBoxResult ShowMessage(string message)

Parameters

message string

The message.

Returns

MessageBoxResult

MessageBoxResult.

ShowMessageEx(string, string, MessageBoxDialogButtons)

Shows the message.

public MessageBoxResult ShowMessageEx(string message, string caption, MessageBoxDialogButtons buttons)

Parameters

message string

The message.

caption string

The caption.

buttons MessageBoxDialogButtons

The buttons.

Returns

MessageBoxResult

MessageBoxResult.

OnMouseButtonDown

Occurs when mouse button down.

public event EventHandler<MouseButtonEventArgs> OnMouseButtonDown

Event Type

EventHandler<MouseButtonEventArgs>

OnMouseButtonUp

Occurs when mouse button up.

public event EventHandler<MouseButtonEventArgs> OnMouseButtonUp

Event Type

EventHandler<MouseButtonEventArgs>

OnMouseMoved

Occurs when mouse moved.

public event EventHandler<MouseMoveEventArgs> OnMouseMoved

Event Type

EventHandler<MouseMoveEventArgs>

PropertyChanged

Property changed event.

public event PropertyChangedEventHandler PropertyChanged

Event Type

PropertyChangedEventHandler