# 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, images, GIFs, SVG, shapes (rectangles, circles, triangles, stars, lines)
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
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 HH:mm:ss"	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);

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