Overlay Manager Block usage guide¶

Overview¶

The OverlayManagerBlock is a powerful MediaBlocks component that provides dynamic multi-layer video overlay composition and management. It allows you to add various overlay elements (images, text, shapes, animations) on top of video content with real-time updates, layer management, and advanced features like shadows, rotation, and opacity control.

Key Features¶

Multiple Overlay Types: Text, scrolling text, images, GIFs, SVG, shapes (rectangles, circles, triangles, stars, lines), live video (NDI, Decklink)
Layer Management: Z-index ordering for proper overlay stacking
Advanced Effects: Shadows, rotation, opacity, custom positioning
Real-time Updates: Dynamic overlay modification during playback
Time-based Display: Show/hide overlays at specific timestamps
Custom Drawing: Callback support for custom Cairo drawing operations
Live Video Sources: Support for NDI network sources and Decklink capture cards
Cross-platform: Works on Windows, Linux, macOS, iOS, and Android

Class Reference¶

OverlayManagerBlock¶

Namespace: VisioForge.Core.MediaBlocks.VideoProcessing

public class OverlayManagerBlock : MediaBlock, IMediaBlockInternals

Properties¶

Property	Type	Description
`Type`	`MediaBlockType`	Returns `MediaBlockType.OverlayManager`
`Input`	`MediaBlockPad`	Video input pad
`Output`	`MediaBlockPad`	Video output pad with overlays

Methods¶

Static Methods¶

public static bool IsAvailable()

Checks if the overlay manager is available in the current environment (requires Cairo overlay support).

Instance Methods¶

public void Video_Overlay_Add(IOverlayManagerElement overlay)

Adds a new overlay element to the video composition.

public void Video_Overlay_Remove(IOverlayManagerElement overlay)

Removes a specific overlay element.

public void Video_Overlay_RemoveAt(int index)

Removes an overlay at the specified index.

public void Video_Overlay_Clear()

Removes all overlay elements.

public void Video_Overlay_Update(IOverlayManagerElement overlay)

Updates an existing overlay (removes and re-adds with new properties).

Overlay Element Types¶

Common Properties (IOverlayManagerElement)¶

All overlay elements implement the IOverlayManagerElement interface with these common properties:

Property	Type	Default	Description
`Name`	`string`	-	Optional name for identification
`Enabled`	`bool`	`true`	Enable/disable the overlay
`StartTime`	`TimeSpan`	`Zero`	When to start showing (optional)
`EndTime`	`TimeSpan`	`Zero`	When to stop showing (optional)
`Opacity`	`double`	`1.0`	Transparency (0.0-1.0)
`Rotation`	`double`	`0.0`	Rotation angle in degrees (0-360)
`ZIndex`	`int`	`0`	Layer order (higher = on top)
`Shadow`	`OverlayManagerShadowSettings`	-	Shadow configuration

OverlayManagerText¶

Displays text with optional background and formatting.

public class OverlayManagerText : IOverlayManagerElement

Property	Type	Default	Description
`Text`	`string`	"Hello!!!"	Text to display
`X`	`int`	`100`	X position
`Y`	`int`	`100`	Y position
`Font`	`FontSettings`	System default	Font configuration
`Color`	`SKColor`	`Red`	Text color
`Background`	`IOverlayManagerBackground`	`null`	Optional background
`CustomWidth`	`int`	`0`	Custom bounding width (0 = auto)
`CustomHeight`	`int`	`0`	Custom bounding height (0 = auto)

Example:

var text = new OverlayManagerText("Hello World!", 100, 100);
text.Color = SKColors.White;
text.Font.Size = 48;
text.Font.Name = "Arial";
text.Shadow = new OverlayManagerShadowSettings(true, depth: 5, direction: 45);
overlayManager.Video_Overlay_Add(text);

OverlayManagerImage¶

Displays static images with stretch modes.

public class OverlayManagerImage : IOverlayManagerElement, IDisposable

Property	Type	Default	Description
`X`	`int`	-	X position
`Y`	`int`	-	Y position
`Width`	`int`	-	Display width (0 = original)
`Height`	`int`	-	Display height (0 = original)
`StretchMode`	`OverlayManagerImageStretchMode`	`None`	Image scaling mode

Stretch Modes:

None - Original size
Stretch - Fill target area (may distort)
Letterbox - Fit within area (maintain aspect ratio)
CropToFill - Fill area by cropping (maintain aspect ratio)

Constructors:

// From file
new OverlayManagerImage(string filename, int x, int y, double alpha = 1.0)

// From SkiaSharp bitmap
new OverlayManagerImage(SKBitmap image, int x, int y, double alpha = 1.0)

// From System.Drawing.Bitmap (Windows only)
new OverlayManagerImage(System.Drawing.Bitmap image, int x, int y, double alpha = 1.0)

Example:

var image = new OverlayManagerImage("logo.png", 10, 10);
image.StretchMode = OverlayManagerImageStretchMode.Letterbox;
image.Width = 200;
image.Height = 100;
overlayManager.Video_Overlay_Add(image);

OverlayManagerGIF¶

Displays animated GIF images.

public class OverlayManagerGIF : IOverlayManagerElement, IDisposable

Property	Type	Description
`Position`	`SKPoint`	Position of the GIF
`AnimationLength`	`TimeSpan`	Total animation duration

Example:

var gif = new OverlayManagerGIF("animation.gif", new SKPoint(150, 150));
overlayManager.Video_Overlay_Add(gif);

OverlayManagerDateTime¶

Displays current date/time with custom formatting.

public class OverlayManagerDateTime : IOverlayManagerElement

Property	Type	Default	Description
`Text`	`string`	"[DATETIME]"	Text template
`Format`	`string`	"MM/dd/yyyy HHss"	DateTime format
`X`	`int`	`100`	X position
`Y`	`int`	`100`	Y position
`Font`	`FontSettings`	System default	Font configuration
`Color`	`SKColor`	`Red`	Text color

Example:

var dateTime = new OverlayManagerDateTime();
dateTime.Format = "yyyy-MM-dd HH:mm:ss";
dateTime.X = 10;
dateTime.Y = 30;
overlayManager.Video_Overlay_Add(dateTime);

OverlayManagerScrollingText¶

Displays scrolling text that moves across the video in a specified direction.

public class OverlayManagerScrollingText : IOverlayManagerElement

Property	Type	Default	Description
`Text`	`string`	"Scrolling Text"	Text to display
`X`	`int`	`0`	X position of the scrolling area
`Y`	`int`	`100`	Y position of the scrolling area
`Width`	`int`	`0`	Width of scrolling area (0 = uses DefaultWidth)
`Height`	`int`	`0`	Height of scrolling area (0 = auto based on font)
`DefaultWidth`	`int`	`1920`	Default width when Width is 0 (set to video width)
`DefaultHeight`	`int`	`1080`	Default height when Height is 0 for vertical scroll
`Speed`	`int`	`5`	Scrolling speed in pixels per frame
`Direction`	`ScrollDirection`	`RightToLeft`	Scroll direction
`Font`	`FontSettings`	System default	Font configuration
`Color`	`SKColor`	`White`	Text color
`BackgroundTransparent`	`bool`	`true`	Whether background is transparent
`BackgroundColor`	`SKColor`	`Black`	Background color (when not transparent)
`Infinite`	`bool`	`true`	Loop scrolling infinitely
`TextRestarted`	`EventHandler`	`null`	Called when text loops back to start

ScrollDirection Enum:

LeftToRight - Text scrolls from left to right
RightToLeft - Text scrolls from right to left
BottomToTop - Text scrolls from bottom to top
TopToBottom - Text scrolls from top to bottom

Example:

// Create a news ticker style scrolling text
var scrollingText = new OverlayManagerScrollingText(
    "Breaking News: VisioForge Media Framework now supports scrolling text overlays!",
    x: 0,
    y: 50,
    speed: 3,
    direction: ScrollDirection.RightToLeft);

scrollingText.Font.Size = 24;
scrollingText.Color = SKColors.Yellow;
scrollingText.BackgroundTransparent = false;
scrollingText.BackgroundColor = SKColors.DarkBlue;

// Set the default width to match your video resolution
// This is used when Width is not explicitly set
scrollingText.DefaultWidth = 1920; // Full HD width

// Or set Width directly for a specific scrolling area width
// scrollingText.Width = 1920;

// Add event handler for when text loops
scrollingText.TextRestarted += (sender, e) => {
    Console.WriteLine("Scrolling text restarted");
};

overlayManager.Video_Overlay_Add(scrollingText);

// To reset scrolling position
scrollingText.Reset();

// To update after changing text or font
scrollingText.Text = "Updated news text...";
scrollingText.Update();

Live Video Overlays¶

The Overlay Manager supports live video sources as overlays, allowing you to composite real-time video from Decklink capture cards or NDI network sources.

OverlayManagerDecklinkVideo¶

Captures and displays video from Blackmagic Decklink capture cards.

public class OverlayManagerDecklinkVideo : IOverlayManagerElement

Property	Type	Default	Description
`DecklinkSettings`	`DecklinkVideoSourceSettings`	-	Decklink device configuration
`X`	`int`	-	X position
`Y`	`int`	-	Y position
`Width`	`int`	-	Overlay width
`Height`	`int`	-	Overlay height
`StretchMode`	`OverlayManagerImageStretchMode`	`Letterbox`	How to fit video
`VideoView`	`IVideoView`	`null`	Optional video preview
`VideoRendererSettings`	`VideoRendererSettingsX`	`null`	Renderer settings

Example:

// Get Decklink devices
var devices = await DecklinkVideoSourceBlock.GetDevicesAsync();
var decklinkSettings = new DecklinkVideoSourceSettings(devices[0]);
decklinkSettings.Mode = DecklinkMode.HD1080p2997;

// Create Decklink overlay
var decklinkOverlay = new OverlayManagerDecklinkVideo(
    decklinkSettings, 
    x: 10, 
    y: 10, 
    width: 640, 
    height: 360);

// Initialize and add to overlay manager
if (decklinkOverlay.Initialize(autoStart: true))
{
    overlayManager.Video_Overlay_Add(decklinkOverlay);
}

// Clean up when done
decklinkOverlay.Stop();
decklinkOverlay.Dispose();

OverlayManagerNDIVideo¶

Captures and displays video from NDI (Network Device Interface) sources.

public class OverlayManagerNDIVideo : IOverlayManagerElement

Property	Type	Default	Description
`NDISettings`	`NDISourceSettings`	-	NDI source configuration
`X`	`int`	-	X position
`Y`	`int`	-	Y position
`Width`	`int`	-	Overlay width
`Height`	`int`	-	Overlay height
`StretchMode`	`OverlayManagerImageStretchMode`	`Letterbox`	How to fit video
`VideoView`	`IVideoView`	`null`	Optional video preview
`VideoRendererSettings`	`VideoRendererSettingsX`	`null`	Renderer settings

Example:

// Discover NDI sources on the network
var ndiSources = await DeviceEnumerator.Shared.NDISourcesAsync();
var ndiSettings = await NDISourceSettings.CreateAsync(
    null, 
    ndiSources[0].Name, 
    ndiSources[0].URL);

// Create NDI overlay
var ndiOverlay = new OverlayManagerNDIVideo(
    ndiSettings, 
    x: 10, 
    y: 10, 
    width: 640, 
    height: 360);

// Initialize and add to overlay manager
if (ndiOverlay.Initialize(autoStart: true))
{
    overlayManager.Video_Overlay_Add(ndiOverlay);
}

// Clean up when done
ndiOverlay.Stop();
ndiOverlay.Dispose();

Common Methods for Live Video Overlays:

Initialize(bool autoStart) - Initialize the video capture pipeline
Play() - Start or resume video capture
Pause() - Pause video capture
Stop() - Stop video capture
Dispose() - Clean up resources

Shape Overlays¶

OverlayManagerLine¶

public class OverlayManagerLine : IOverlayManagerElement

Property	Type	Description
`Start`	`SKPoint`	Line start point
`End`	`SKPoint`	Line end point
`Color`	`SKColor`	Line color

OverlayManagerRectangle¶

public class OverlayManagerRectangle : IOverlayManagerElement

Property	Type	Description
`Rectangle`	`SKRect`	Rectangle bounds
`Color`	`SKColor`	Fill/stroke color
`Fill`	`bool`	Fill or stroke only

OverlayManagerCircle¶

public class OverlayManagerCircle : IOverlayManagerElement

Property	Type	Description
`Center`	`SKPoint`	Circle center
`Radius`	`double`	Circle radius
`Color`	`SKColor`	Fill/stroke color
`Fill`	`bool`	Fill or stroke only

OverlayManagerTriangle¶

public class OverlayManagerTriangle : IOverlayManagerElement

Property	Type	Description
`Point1`	`SKPoint`	First vertex
`Point2`	`SKPoint`	Second vertex
`Point3`	`SKPoint`	Third vertex
`Color`	`SKColor`	Fill/stroke color
`Fill`	`bool`	Fill or stroke only

OverlayManagerStar¶

public class OverlayManagerStar : IOverlayManagerElement

Property	Type	Description
`Center`	`SKPoint`	Star center
`OuterRadius`	`double`	Outer points radius
`InnerRadius`	`double`	Inner points radius
`StrokeColor`	`SKColor`	Stroke color
`FillColor`	`SKColor`	Fill color

OverlayManagerSVG¶

Displays SVG vector graphics.

public class OverlayManagerSVG : IOverlayManagerElement, IDisposable

Property	Type	Description
`X`	`int`	X position
`Y`	`int`	Y position
`Width`	`int`	Display width
`Height`	`int`	Display height

OverlayManagerCallback¶

Custom drawing using Cairo graphics.

public class OverlayManagerCallback : IOverlayManagerElement

Event:

public event EventHandler<OverlayManagerCallbackEventArgs> OnDraw;

Example:

var callback = new OverlayManagerCallback();
callback.OnDraw += (sender, e) => {
    var ctx = e.Context;
    ctx.SetSourceRGB(1, 0, 0);
    ctx.Arc(200, 200, 50, 0, 2 * Math.PI);
    ctx.Fill();
};
overlayManager.Video_Overlay_Add(callback);

Shadow Settings¶

Configure drop shadows for overlay elements:

public class OverlayManagerShadowSettings

Property	Type	Range	Default	Description
`Enabled`	`bool`	-	`false`	Enable shadows
`Depth`	`double`	0-30	`5.0`	Shadow offset distance
`Direction`	`double`	0-360°	`45.0`	Shadow direction
`Opacity`	`double`	0-1	`0.5`	Shadow transparency
`BlurRadius`	`double`	0-10	`2.0`	Shadow blur amount
`Color`	`SKColor`	-	`Black`	Shadow color

Direction Reference:

0° = Right
90° = Down
180° = Left
270° = Up

Text Backgrounds¶

Text overlays can have various background shapes:

OverlayManagerBackgroundRectangle¶

var text = new OverlayManagerText("Info", 100, 100);
text.Background = new OverlayManagerBackgroundRectangle {
    Color = SKColors.Black.WithAlpha(128),
    Fill = true,
    Margin = new Thickness(5, 3, 5, 3)
};

OverlayManagerBackgroundSquare¶

Similar to rectangle but maintains square aspect ratio.

OverlayManagerBackgroundImage¶

Uses an image as text background with stretch modes.

OverlayManagerBackgroundTriangle/Star¶

Custom shaped backgrounds for text.

Font Settings¶

Configure text appearance:

public class FontSettings

Property	Type	Description
`Name`	`string`	Font family name
`Size`	`int`	Font size in points
`Style`	`FontStyle`	Normal, Italic, Oblique
`Weight`	`FontWeight`	Normal, Bold, Light, etc.

Complete Example¶

// Create pipeline and blocks
var pipeline = new MediaBlocksPipeline();
var fileSource = new UniversalSourceBlock(await UniversalSourceSettings.CreateAsync(videoUri));
var overlayManager = new OverlayManagerBlock();
var videoRenderer = new VideoRendererBlock(pipeline, videoView);

// Connect pipeline
pipeline.Connect(fileSource.VideoOutput, overlayManager.Input);
pipeline.Connect(overlayManager.Output, videoRenderer.Input);

// Add logo watermark
var logo = new OverlayManagerImage("logo.png", 10, 10);
logo.Opacity = 0.5;
logo.ZIndex = 10; // On top
overlayManager.Video_Overlay_Add(logo);

// Add timestamp
var timestamp = new OverlayManagerDateTime();
timestamp.X = 10;
timestamp.Y = pipeline.Height - 30;
timestamp.Font.Size = 16;
timestamp.Color = SKColors.White;
timestamp.Shadow = new OverlayManagerShadowSettings(true);
overlayManager.Video_Overlay_Add(timestamp);

// Add animated title (appears after 5 seconds)
var title = new OverlayManagerText("Welcome!", 100, 100);
title.Font.Size = 72;
title.Color = SKColors.Yellow;
title.StartTime = TimeSpan.FromSeconds(5);
title.EndTime = TimeSpan.FromSeconds(10);
title.Rotation = -10; // Slight tilt
title.Background = new OverlayManagerBackgroundRectangle {
    Color = SKColors.DarkBlue,
    Fill = true
};
overlayManager.Video_Overlay_Add(title);

// Start playback
await pipeline.StartAsync();

// Update overlays dynamically
title.Text = "Updated Text!";
overlayManager.Video_Overlay_Update(title);

Performance Considerations¶

Z-Index Ordering: Elements are sorted by Z-index before rendering. Use appropriate values to minimize sorting overhead.
Image Formats: Use RGBA8888 format images when possible to avoid color conversion.
Shadow Effects: Shadows with blur are computationally expensive. Use sparingly for real-time applications.
Updates: Use Video_Overlay_Update() for existing elements rather than remove/add operations.
Resource Management: Dispose image and GIF overlays when no longer needed to free memory.

Platform Notes¶

Windows: Supports System.Drawing.Bitmap in addition to SkiaSharp
iOS: Font defaults to "System-ui"
Android: Font defaults to "System-ui"
Linux/macOS: Enumerates available fonts at runtime

Thread Safety¶

The overlay manager uses internal locking for thread-safe operations. You can safely add, remove, or update overlays from any thread.

Troubleshooting¶

Overlay not visible: Check Enabled property, StartTime/EndTime, and ZIndex ordering.
Text appears blurry: Ensure font size is appropriate for video resolution.
Memory usage: Dispose unused image/GIF overlays and use appropriate image sizes.