Table of Contents

Class VideoView

Namespace
VisioForge.Core.UI.WPF
Assembly
VisioForge.Core.dll

High-performance video view control for WPF applications providing multiple rendering modes and comprehensive video display capabilities. Supports software rendering via WriteableBitmap, hardware-accelerated rendering via Direct2D/EVR, and native rendering for optimal performance. This control handles video frame display, UI event forwarding, background image management, status overlays, and video transformations.

Key features:

  • Multiple rendering modes: FrameCallback (software), Direct2D, EVR, MadVR, and native rendering
  • Hardware acceleration support for GPU decoding and high-resolution video (4K/8K)
  • Thread-safe frame delivery with efficient pixel format handling
  • Video rotation and transformation capabilities
  • Status overlay system for connection progress and custom notifications
  • Comprehensive mouse and keyboard event handling
  • Background image support with stretch modes
  • Picture-in-picture overlay functionality
  • DPI awareness for high-DPI displays
  • Memory-efficient frame buffering with automatic cleanup

Threading considerations:

  • Frame rendering is performed on the UI thread via Dispatcher.BeginInvoke for thread safety
  • All UI operations are properly marshaled to the UI thread
  • Event handlers are invoked on the UI thread
  • Native rendering components require proper disposal to prevent memory leaks
  • Window minimize/restore events are handled with proper synchronization to prevent race conditions

Performance optimizations:

  • WriteableBitmap reuse to minimize memory allocations
  • Efficient pixel format detection and stride calculation
  • Hardware-accelerated rendering paths for supported configurations
  • Frame dropping capability to maintain smooth playback
public class VideoView : Grid, IAnimatable, ISupportInitialize, IFrameworkInputElement, IInputElement, IQueryAmbient, IAddChild, IDisposable, INotifyPropertyChanged, IVideoView, IVideoViewPushFrame, IVideoViewNativeRendering

Inheritance

Implements

Inherited Members

Constructors

VideoView()

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

Sets up the video view with default configuration:

  • Black background for professional video display
  • Automatic size change handling for responsive layout
  • Event handlers for UI component resizing
  • Thread-safe operations using exception handling

The constructor prepares the control for video rendering but does not create the actual rendering surface until a parent component is attached and a rendering mode is specified.

Thread safety: Must be called from the UI thread as it initializes WPF controls.

public VideoView()

Properties

BackgroundImage_Source

Gets or sets background image.

public BitmapSource BackgroundImage_Source { get; set; }

Property Value

BitmapSource

BackgroundImage_Stretch

Gets or sets background image stretch.

public Stretch BackgroundImage_Stretch { get; set; }

Property Value

Stretch

Context

SDK logging context. Set by the engine via VisioForge.Core.Helpers.ContextPropagator when the view is attached. When null, render/lifecycle exceptions fall back to Trace.

public BaseContext Context { get; set; }

Property Value

BaseContext

RotateCrop

Gets or sets a value indicating whether video rotation should crop the image to fill the view.

This property controls the scaling behavior when rotation is applied:

  • When true: The rotated video is scaled to fill the entire view area, which may result in cropping the edges. This is useful when you want to maintain a filled view without black bars.
  • When false: The rotated video is scaled to fit entirely within the view without cropping. This ensures the entire video content is visible but may show black bars.

This property only affects 90-degree and 270-degree rotations where the aspect ratio changes. 180-degree rotation is not affected as the aspect ratio remains the same.

Performance: Uses WPF's GPU-accelerated transforms for efficient rendering. Thread safety: Can be set from any thread; UI updates are marshaled to the UI thread.

Note: This property only affects WPF software rendering (FrameCallback mode).

public bool RotateCrop { get; set; }

Property Value

bool

RotationAngle

Gets or sets the video rotation angle in degrees for WPF software rendering.

Applies geometric transformations to rotate video frames by any angle. Uses WPF's RenderTransform system for efficient GPU-accelerated rotation. Automatically adjusts scaling based on the RotateCrop property.

Supported values:

  • 0: No rotation applied (default)
  • Positive values: Clockwise rotation (e.g., 90, 120, 180, 270)
  • Negative values: Counter-clockwise rotation (e.g., -90, -45)
  • Any decimal value is supported (e.g., 73.5, 120.25)

Examples:

  • 90: 90-degree clockwise rotation
  • 180: Upside down
  • 270 or -90: 90-degree counter-clockwise rotation
  • 73: 73-degree clockwise rotation
  • -45.5: 45.5-degree counter-clockwise rotation

Performance: Rotation is hardware-accelerated when possible and has minimal impact on rendering performance. Thread safety: Can be set from any thread; UI updates are marshaled to the UI thread.

Note: This property only affects WPF software rendering (FrameCallback mode). Native rendering modes handle rotation through the video renderer configuration.

public double RotationAngle { get; set; }

Property Value

double

RotationStretch

Gets or sets the stretch mode to use when video rotation is applied.

This property controls how the video content is stretched within the Image control before rotation:

  • Stretch.Fill: Video fills the entire Image bounds, may distort aspect ratio (default for rotation)
  • Stretch.Uniform: Video maintains aspect ratio, may show letterboxing (black bars)
  • Stretch.UniformToFill: Video maintains aspect ratio and fills bounds, may crop content

When RotationAngle is 0 (no rotation), this property is ignored and the Video_Renderer.StretchMode is used. When RotationAngle is non-zero, this property determines the stretch behavior before rotation transform.

Common scenarios:

  • Stretch.Fill: Best for videos that match the view aspect ratio or when distortion is acceptable
  • Stretch.Uniform: Best for maintaining video aspect ratio during rotation (shows black bars)
  • Stretch.UniformToFill: Best for filling the view while maintaining aspect ratio

Performance: Stretch mode is a WPF property and has minimal performance impact. Thread safety: Can be set from any thread; UI updates are marshaled to the UI thread.

Note: This property only affects WPF software rendering (FrameCallback mode) when rotation is active.

public Stretch RotationStretch { get; set; }

Property Value

Stretch

StatusOverlay

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

This overlay is particularly useful for IP cameras, network streams, and other sources that require connection negotiation time. The overlay appears immediately after Start/StartAsync is called and remains visible until the first video frame is received or an error occurs.

Use VisioForge.Core.Types.TextStatusOverlay for text-based overlays with customizable fonts, colors, positioning, and alignment. Custom overlay implementations can provide progress bars, animations, or other visual feedback.

Thread safety: This property can be set from any thread, but the overlay rendering occurs on the UI thread.

Performance: Overlay rendering is lightweight and does not impact video performance once streaming begins.

public IStatusOverlay StatusOverlay { get; set; }

Property Value

IStatusOverlay

Video_Renderer

Gets the video renderer configuration used for displaying video content.

This property provides access to the video rendering settings that control how video frames are displayed, including rendering mode, stretch behavior, and hardware acceleration options.

For native rendering mode, returns a fixed EVR configuration. For standard mode, returns the parent component's renderer settings and automatically synchronizes WPF stretch modes with the renderer configuration.

Supported stretch mode mappings:

  • Letterbox → Stretch.Uniform (maintains aspect ratio)
  • Stretch → Stretch.Fill (fills entire area)
  • LetterboxToFill → Stretch.UniformToFill (maintains aspect ratio, may crop)

Thread safety: Can be accessed from any thread, but WPF property updates are automatically marshaled to the UI thread.

public VideoRendererSettings Video_Renderer { get; }

Property Value

VideoRendererSettings

Methods

Attach(IMPVCVECore)

Attaches a parent media core component to this video view.

This method establishes the connection between the video view and a media processing component (MediaPlayer, VideoCapture, or VideoEdit). The parent component provides video frames and controls the rendering pipeline.

The attachment process:

  1. Stores the parent reference for renderer access
  2. The parent will later call InvokeStart to begin rendering
  3. Frame delivery events are established based on rendering mode
  4. Error and stop events are connected for proper cleanup

Thread safety: Can be called from any thread.

public void Attach(IMPVCVECore parent)

Parameters

parent IMPVCVECore

The media core component to attach.

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()

ColorConv(Color)

Converts color from WPF to WinForms.

public static Color ColorConv(Color color)

Parameters

color Color

Source color.

Returns

Color

Returns WinForms color.

ColorConv(Color)

Converts color from WinForms to WPF.

public static Color ColorConv(Color color)

Parameters

color Color

Source color.

Returns

Color

Returns WPF color.

Detach(IMPVCVECore)

Detaches the parent media core component from this video view.

This method safely disconnects the video view from its parent component, ensuring proper cleanup of event handlers and resources. Should be called before disposing the parent component or switching to a new parent.

Cleanup operations:

  1. Disconnects video frame buffer events
  2. Clears the parent reference
  3. Stops frame delivery and rendering
  4. Maintains UI state for potential reattachment

Thread safety: Can be called from any thread.

public void Detach(IMPVCVECore parent)

Parameters

parent IMPVCVECore

The parent component to detach (should match current parent).

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.WPF.VideoView class.

protected ~VideoView()

GetBackgroundColor()

Gets the color of the background.

public SKColor GetBackgroundColor()

Returns

SKColor

SKColor.

GetHandle()

Gets window handle.

public nint GetHandle()

Returns

nint

Returns IntPtr.

GetImageLayer()

Gets the primary image layer used for WPF software rendering.

This method provides access to the underlying WPF Image control that displays video frames in FrameCallback rendering mode. The returned Image control can be used to apply custom WPF transforms, animations, or effects.

Common use cases:

  • Applying custom RenderTransform animations
  • Setting opacity or visibility effects
  • Accessing ActualWidth/ActualHeight for measurements
  • Adding custom attached properties

Thread safety: Must be called from the UI thread.

Note: Returns null if native rendering is enabled or if the control hasn't been initialized with a software rendering mode.

public Image GetImageLayer()

Returns

Image

The WPF Image control used for video display, or null if not available.

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 size.

public Size GetSize()

Returns

Size

Return VisioForge.Core.Types.Size.

GetSurfaceProvider()

When the view runs in VisioForge.Core.Types.VideoRendererMode.D3D11Composable, returns the underlying VisioForge.Core.UI.WPF.IVideoSurfaceProvider so consumer code can grab the GPU-resident shared texture and run custom shaders or overlays per frame. Returns null in every other render mode.

public IVideoSurfaceProvider GetSurfaceProvider()

Returns

IVideoSurfaceProvider

GetUIEngine()

Gets UI engine.

public VideoViewUIEngine GetUIEngine()

Returns

VideoViewUIEngine

Returns VisioForge.Core.Types.VideoViewUIEngine.

InvokeStart()

Invokes Start/Play.

public void InvokeStart()

InvokeStartComplete()

Invokes Start/Play.

public void InvokeStartComplete()

InvokeStop()

Invokes Stop.

public void InvokeStop()

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 a custom dialog.

public void LogDialogError(string msg)

Parameters

msg string

The MSG.

OnMouseRightButtonUp(MouseButtonEventArgs)

Invoked when an unhandled MouseRightButtonUp routed event reaches an element in its route that is derived from this class. Implement this method to add class handling for this event.

protected override void OnMouseRightButtonUp(MouseButtonEventArgs e)

Parameters

e MouseButtonEventArgs

The MouseButtonEventArgs that contains the event data. The event data reports that the right mouse button was released.

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 for display through the external frame delivery interface.

This method is part of the IVideoViewPushFrame interface and provides external components with the ability to deliver video frames directly to the video view. It handles both Direct2D managed rendering and WPF software rendering modes.

Frame delivery process:

  1. Checks rendering mode (Direct2D managed vs WPF software)
  2. For Direct2D: Pushes frame directly to Direct2DPanel
  3. For WPF: Creates Image control if needed and marshals to UI thread
  4. Handles thread safety and error conditions gracefully

Performance considerations:

  • Direct2D rendering provides hardware acceleration
  • WPF rendering uses efficient WriteableBitmap operations
  • Frame delivery is asynchronous to prevent blocking
  • Error handling prevents pipeline failures

Thread safety: Can be called from any thread, automatically marshals UI operations.

public void PushFrame(VideoFrame frame)

Parameters

frame VideoFrame

The video frame to display.

PushFrame(VideoFrameX)

Pushes a video frame using the extended frame format for display.

This overload accepts VideoFrameX format and converts it to the standard VideoFrame format before processing. VideoFrameX provides additional metadata and format information that may be useful for advanced rendering scenarios.

Thread safety: Can be called from any thread, automatically marshals UI operations.

public void PushFrame(VideoFrameX frame)

Parameters

frame VideoFrameX

The extended video frame to display.

PushMouseButtonDown(int, int, MouseButton)

Pushes a mouse button down event to external event handlers.

This method forwards mouse button press events to external components that need to track mouse interactions with the video display.

Thread safety: Can be called from any thread, event handlers are invoked on the calling thread.

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

Parameters

x int

The horizontal mouse position in control coordinates.

y int

The vertical mouse position in control coordinates.

button MouseButton

The mouse button that was pressed.

PushMouseButtonUp(int, int, MouseButton)

Pushes a mouse button up event to external event handlers.

This method forwards mouse button release events to external components that need to track mouse interactions with the video display.

Thread safety: Can be called from any thread, event handlers are invoked on the calling thread.

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

Parameters

x int

The horizontal mouse position in control coordinates.

y int

The vertical mouse position in control coordinates.

button MouseButton

The mouse button that was released.

PushMouseMove(int, int)

Pushes a mouse movement event to external event handlers.

This method is part of the mouse event forwarding system that allows external components to receive mouse events from the video view. Useful for implementing video overlays, click tracking, or custom interactions.

Thread safety: Can be called from any thread, event handlers are invoked on the calling thread.

public void PushMouseMove(int x, int y)

Parameters

x int

The horizontal mouse position in control coordinates.

y int

The vertical mouse position in control coordinates.

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.

SetNativeRendering(bool)

Enables or disables native rendering mode for optimal video performance.

Native rendering bypasses WPF's software rendering pipeline and provides direct access to hardware-accelerated video renderers. This mode is recommended for:

  • GPU-accelerated video decoding
  • High-resolution video (4K/8K)
  • Performance-critical applications
  • Multiple concurrent video streams

When enabled:

  • Uses native window handles for Direct2D, EVR, or MadVR rendering
  • Provides maximum performance with minimal CPU usage
  • Reduces memory usage compared to software rendering
  • Enables hardware deinterlacing and post-processing

When disabled:

  • Uses WPF WriteableBitmap for software rendering
  • Provides full WPF integration and transformation support
  • Enables custom overlays and effects
  • Works on systems without hardware acceleration

Thread safety: Can be called from any thread, but should be set before attaching a parent component for consistent behavior.

public void SetNativeRendering(bool native)

Parameters

native bool

True to enable native rendering, false for WPF software rendering.

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 static MessageBoxResult ShowMessageEx(string message, string caption, MessageBoxDialogButtons buttons)

Parameters

message string

The message.

caption string

The caption.

buttons MessageBoxDialogButtons

The buttons.

Returns

MessageBoxResult

MessageBoxResult.

UseD3D11ComposableRenderer()

Enables the Direct3D 11 composable rendering path on this view, independent of any attached engine. Call this before starting playback. Works with every supported backend:

  • MediaPlayerCore / VideoCaptureCore / VideoEditCore (DirectShow) — frames arrive via OnVideoFrameBufferWPF and are routed to the D3D11 panel; the engine is automatically switched to VisioForge.Core.Types.VideoRendererMode.FrameCallback on its renderer settings.
  • MediaPlayerCoreX / VideoCaptureCoreX / VideoEditCoreX (GStreamer) — frames arrive via IVideoViewPushFrame.PushFrame and are routed to the D3D11 panel. 
public void UseD3D11ComposableRenderer()

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