Table of Contents

Class OverlayManagerBlock

Namespace
VisioForge.Core.MediaBlocks.VideoProcessing
Assembly
VisioForge.Core.dll

Overlay manager block for dynamic multi-layer video overlay composition and management. This block provides a centralized system for managing multiple overlay elements on video content, supporting various overlay types including images, text, shapes, and animated graphics. Features include layer ordering, opacity control, positioning, blending modes, and real-time overlay updates. Essential for broadcast graphics, live production, watermarking, subtitles, and any application requiring dynamic overlay composition with runtime management capabilities. Implements the VisioForge.Core.MediaBlocks.MediaBlock. Implements the VisioForge.Core.MediaBlocks.IMediaBlockInternals. Implements the IDisposable.

public class OverlayManagerBlock : MediaBlock, IMediaBlock, IDisposable, IMediaBlockInternals

Inheritance

Implements

Inherited Members

Extension Methods

Constructors

OverlayManagerBlock()

Initializes a new instance of the VisioForge.Core.MediaBlocks.VideoProcessing.OverlayManagerBlock class for managing multiple video overlays.

public OverlayManagerBlock()

Properties

Input

Gets the input.

public override MediaBlockPad Input { get; }

Property Value

MediaBlockPad

Inputs

Gets the inputs.

public override MediaBlockPad[] Inputs { get; }

Property Value

MediaBlockPad[]

Output

Gets the output.

public override MediaBlockPad Output { get; }

Property Value

MediaBlockPad

Outputs

Gets the outputs.

public override MediaBlockPad[] Outputs { get; }

Property Value

MediaBlockPad[]

Type

Gets the type.

public override MediaBlockType Type { get; }

Property Value

MediaBlockType

Methods

Build()

Constructs and initializes the overlay manager filter and its associated GStreamer elements. This method creates the filter, establishes input and output pads, and prepares the block for managing multiple overlay layers on video content.

public override bool Build()

Returns

bool

true if the filter was successfully built and configured; false if initialization failed.

CleanUp()

Releases all resources and performs cleanup operations for this overlay manager block. This method resets the build state but does not dispose of the GStreamer elements.

public void CleanUp()

Dispose(bool)

Releases unmanaged and - optionally - managed resources.

protected override void Dispose(bool disposing)

Parameters

disposing bool

true to release both managed and unmanaged resources; false to release only unmanaged resources.

GetCore()

Gets the core BaseElement wrapper that provides additional functionality around the GStreamer overlay manager filter element.

public BaseElement GetCore()

Returns

BaseElement

The BaseElement wrapper instance that encapsulates the GStreamer overlay manager filter.

GetElement()

Gets the underlying GStreamer element that performs the overlay management.

public Element GetElement()

Returns

Element

The GStreamer Element instance representing the overlay manager filter.

IsAvailable()

Determines whether this media block is available. Correct NuGet SDK redist should be included into your project.

public static bool IsAvailable()

Returns

bool

true if this media block is available; otherwise, false.

Video_Overlay_Add(IOverlayManagerElement)

Adds a new overlay element to the video composition. The overlay will be rendered on top of the video content according to its properties.

public void Video_Overlay_Add(IOverlayManagerElement overlay)

Parameters

overlay IOverlayManagerElement

The overlay element to add to the composition.

Video_Overlay_AddBackground(string, string)

Adds a background image that fills the entire frame. The image is drawn behind all other overlays (ZIndex = -1000).

public OverlayManagerImage Video_Overlay_AddBackground(string filename, string name = "Background")

Parameters

filename string

The image filename (full path).

name string

Optional name for the background image.

Returns

OverlayManagerImage

The created image element for later modification or removal.

Video_Overlay_AddFade(OverlayManagerFadeType, TimeSpan, TimeSpan, (byte R, byte G, byte B)?, OverlayManagerPanEasing, string)

Adds a custom fade effect with full control over parameters.

public OverlayManagerFade Video_Overlay_AddFade(OverlayManagerFadeType fadeType, TimeSpan startTime, TimeSpan endTime, (byte R, byte G, byte B)? fadeColor = null, OverlayManagerPanEasing easing = OverlayManagerPanEasing.Linear, string name = "Fade")

Parameters

fadeType OverlayManagerFadeType

The type of fade (FadeIn or FadeOut).

startTime TimeSpan

The fade start time.

endTime TimeSpan

The fade end time.

fadeColor (byte R, byte G, byte B)?

Optional fade color (default is black).

easing OverlayManagerPanEasing

The easing function for smooth animation.

name string

Optional name for the fade effect.

Returns

OverlayManagerFade

The created fade element for later modification or removal.

Video_Overlay_AddFadeIn(TimeSpan, TimeSpan?, OverlayManagerPanEasing, string)

Adds a fade-in effect from black (or specified color) to video.

public OverlayManagerFade Video_Overlay_AddFadeIn(TimeSpan duration, TimeSpan? startTime = null, OverlayManagerPanEasing easing = OverlayManagerPanEasing.Linear, string name = "FadeIn")

Parameters

duration TimeSpan

The duration of the fade-in effect.

startTime TimeSpan?

Optional start time (default is TimeSpan.Zero for immediate start).

easing OverlayManagerPanEasing

The easing function for smooth animation.

name string

Optional name for the fade effect.

Returns

OverlayManagerFade

The created fade element for later modification or removal.

Video_Overlay_AddFadeOut(TimeSpan, TimeSpan, OverlayManagerPanEasing, string)

Adds a fade-out effect from video to black (or specified color).

public OverlayManagerFade Video_Overlay_AddFadeOut(TimeSpan startTime, TimeSpan duration, OverlayManagerPanEasing easing = OverlayManagerPanEasing.Linear, string name = "FadeOut")

Parameters

startTime TimeSpan

The start time of the fade-out effect.

duration TimeSpan

The duration of the fade-out effect.

easing OverlayManagerPanEasing

The easing function for smooth animation.

name string

Optional name for the fade effect.

Returns

OverlayManagerFade

The created fade element for later modification or removal.

Video_Overlay_AddImage(string, int, int, int, int, string)

Adds an image overlay at the specified position.

public OverlayManagerImage Video_Overlay_AddImage(string filename, int x, int y, int width = 0, int height = 0, string name = "Image")

Parameters

filename string

The image filename (full path).

x int

The X position.

y int

The Y position.

width int

The width (0 for original size).

height int

The height (0 for original size).

name string

Optional name for the image overlay.

Returns

OverlayManagerImage

The created image element for later modification or removal.

Video_Overlay_AddPan(int, int, int, int, int, int, int, int, TimeSpan, TimeSpan, string) 

public OverlayManagerPan Video_Overlay_AddPan(int startX, int startY, int startWidth, int startHeight, int stopX, int stopY, int stopWidth, int stopHeight, TimeSpan startTime, TimeSpan endTime, string name = "Pan")

Parameters

startX int
startY int
startWidth int
startHeight int
stopX int
stopY int
stopWidth int

The stop rectangle width (0 for full width).

stopHeight int

The stop rectangle height (0 for full height).

startTime TimeSpan

The animation start time.

endTime TimeSpan

The animation end time.

name string

Optional name for the pan effect.

Returns

OverlayManagerPan

The created pan element for later modification or removal.

Video_Overlay_AddPan((int X, int Y, int Width, int Height), (int X, int Y, int Width, int Height), TimeSpan, TimeSpan, OverlayManagerPanEasing, string)

Adds a simple pan effect from one rectangle to another using the element's start/end time.

public OverlayManagerPan Video_Overlay_AddPan((int X, int Y, int Width, int Height) startRect, (int X, int Y, int Width, int Height) stopRect, TimeSpan startTime, TimeSpan endTime, OverlayManagerPanEasing easing = OverlayManagerPanEasing.Linear, string name = "Pan")

Parameters

startRect (int X, int Y, int Width, int Height)

The start rectangle (X, Y, Width, Height). Use 0 for width/height to use full video dimensions.

stopRect (int X, int Y, int Width, int Height)

The stop rectangle (X, Y, Width, Height). Use 0 for width/height to use full video dimensions.

startTime TimeSpan

The animation start time.

endTime TimeSpan

The animation end time.

easing OverlayManagerPanEasing

The easing function for smooth animation.

name string

Optional name for the pan effect.

Returns

OverlayManagerPan

The created pan element for later modification or removal.

Video_Overlay_AddSqueezeback(string, Rect, Rect, string)

Adds a squeezeback effect that scales the video to a custom rectangle and draws an overlay image on top with alpha transparency support. This creates the classic "squeezeback" effect used in broadcast where video is shown in a smaller area with graphics/branding surrounding it.

public OverlayManagerSqueezeback Video_Overlay_AddSqueezeback(string backgroundImageFilename, Rect videoRect, Rect backgroundRect = null, string name = "Squeezeback")

Parameters

backgroundImageFilename string

The overlay image filename (PNG with alpha recommended).

videoRect Rect

The video rectangle (position and size where video is scaled).

backgroundRect Rect

The overlay image rectangle (null for full frame).

name string

Optional name for the squeezeback element.

Returns

OverlayManagerSqueezeback

The created squeezeback element for later modification or removal.

Remarks

By default, the video is drawn first at the specified videoRect, then the overlay image is drawn on top. Use a PNG image with transparent areas where you want the scaled video to show through.

Video_Overlay_AddZoom(double, double, int, int, string)

Adds a zoom effect to the overlay manager. The zoom effect will scale and shift the video content.

public OverlayManagerZoom Video_Overlay_AddZoom(double zoomX, double zoomY, int shiftX = 0, int shiftY = 0, string name = "Zoom")

Parameters

zoomX double

The horizontal zoom ratio (1.0 = 100%).

zoomY double

The vertical zoom ratio (1.0 = 100%).

shiftX int

The horizontal shift in pixels.

shiftY int

The vertical shift in pixels.

name string

Optional name for the zoom effect.

Returns

OverlayManagerZoom

The created zoom element for later modification or removal.

Video_Overlay_AnimateImage(string, int, int, int, int, TimeSpan, TimeSpan, OverlayManagerPanEasing)

Starts an animation on an image overlay to move/resize it to a target rectangle.

public bool Video_Overlay_AnimateImage(string name, int targetX, int targetY, int targetWidth, int targetHeight, TimeSpan startTime, TimeSpan duration, OverlayManagerPanEasing easing = OverlayManagerPanEasing.Linear)

Parameters

name string

The name of the image overlay.

targetX int

The target X position.

targetY int

The target Y position.

targetWidth int

The target width (0 to keep current).

targetHeight int

The target height (0 to keep current).

startTime TimeSpan

The animation start time.

duration TimeSpan

The animation duration.

easing OverlayManagerPanEasing

The easing function.

Returns

bool

true if the image was found and animation started; otherwise, false.

Video_Overlay_BringToFront(string)

Brings an overlay element to the front (highest Z-Index).

public bool Video_Overlay_BringToFront(string name)

Parameters

name string

The name of the overlay.

Returns

bool

true if the overlay was found and updated; otherwise, false.

Video_Overlay_Clear()

Removes all overlay elements from the video composition.

public void Video_Overlay_Clear()

Video_Overlay_Count()

Gets the total number of overlays currently in the composition.

public int Video_Overlay_Count()

Returns

int

The number of overlay elements in the composition.

Video_Overlay_Get(int)

Gets the overlay element at the specified index in the overlay list.

public IOverlayManagerElement Video_Overlay_Get(int index)

Parameters

index int

The zero-based index of the overlay to retrieve.

Returns

IOverlayManagerElement

The overlay element at the specified index.

Exceptions

ArgumentOutOfRangeException

Thrown when index is out of range.

Video_Overlay_GetByName(string)

Gets an overlay element by its name.

public IOverlayManagerElement Video_Overlay_GetByName(string name)

Parameters

name string

The name of the overlay to find.

Returns

IOverlayManagerElement

The overlay element with the specified name, or null if not found.

Video_Overlay_ImageFadeIn(string, TimeSpan, TimeSpan, OverlayManagerPanEasing)

Starts a fade-in animation on an image overlay.

public bool Video_Overlay_ImageFadeIn(string name, TimeSpan startTime, TimeSpan duration, OverlayManagerPanEasing easing = OverlayManagerPanEasing.Linear)

Parameters

name string

The name of the image overlay.

startTime TimeSpan

The fade start time.

duration TimeSpan

The fade duration.

easing OverlayManagerPanEasing

The easing function.

Returns

bool

true if the image was found and fade started; otherwise, false.

Video_Overlay_ImageFadeOut(string, TimeSpan, TimeSpan, OverlayManagerPanEasing)

Starts a fade-out animation on an image overlay.

public bool Video_Overlay_ImageFadeOut(string name, TimeSpan startTime, TimeSpan duration, OverlayManagerPanEasing easing = OverlayManagerPanEasing.Linear)

Parameters

name string

The name of the image overlay.

startTime TimeSpan

The fade start time.

duration TimeSpan

The fade duration.

easing OverlayManagerPanEasing

The easing function.

Returns

bool

true if the image was found and fade started; otherwise, false.

Video_Overlay_Remove(IOverlayManagerElement)

Removes a specific overlay element from the video composition.

public void Video_Overlay_Remove(IOverlayManagerElement overlay)

Parameters

overlay IOverlayManagerElement

The overlay element to remove from the composition.

Video_Overlay_RemoveAt(int)

Removes an overlay element at the specified index in the overlay list.

public void Video_Overlay_RemoveAt(int index)

Parameters

index int

The zero-based index of the overlay to remove.

Video_Overlay_RemoveByName(string)

Removes an overlay element by its name.

public bool Video_Overlay_RemoveByName(string name)

Parameters

name string

The name of the overlay to remove.

Returns

bool

true if the overlay was found and removed; otherwise, false.

Video_Overlay_SendToBack(string)

Sends an overlay element to the back (lowest Z-Index).

public bool Video_Overlay_SendToBack(string name)

Parameters

name string

The name of the overlay.

Returns

bool

true if the overlay was found and updated; otherwise, false.

Video_Overlay_SetZIndex(string, int)

Sets the Z-Index of an overlay element.

public bool Video_Overlay_SetZIndex(string name, int zIndex)

Parameters

name string

The name of the overlay.

zIndex int

The new Z-Index value.

Returns

bool

true if the overlay was found and updated; otherwise, false.

Video_Overlay_Squeezeback_AnimateBackground(string, Rect, TimeSpan, TimeSpan, OverlayManagerPanEasing)

Starts an animation for the background rectangle of a squeezeback element.

public bool Video_Overlay_Squeezeback_AnimateBackground(string name, Rect targetRect, TimeSpan startTime, TimeSpan duration, OverlayManagerPanEasing easing = OverlayManagerPanEasing.Linear)

Parameters

name string

The name of the squeezeback element.

targetRect Rect

The target rectangle.

startTime TimeSpan

The animation start time.

duration TimeSpan

The animation duration.

easing OverlayManagerPanEasing

The easing function.

Returns

bool

true if the squeezeback was found and animation started; otherwise, false.

Video_Overlay_Squeezeback_AnimateVideo(string, Rect, TimeSpan, TimeSpan, OverlayManagerPanEasing)

Starts an animation for the video rectangle of a squeezeback element.

public bool Video_Overlay_Squeezeback_AnimateVideo(string name, Rect targetRect, TimeSpan startTime, TimeSpan duration, OverlayManagerPanEasing easing = OverlayManagerPanEasing.Linear)

Parameters

name string

The name of the squeezeback element.

targetRect Rect

The target rectangle.

startTime TimeSpan

The animation start time.

duration TimeSpan

The animation duration.

easing OverlayManagerPanEasing

The easing function.

Returns

bool

true if the squeezeback was found and animation started; otherwise, false.

Video_Overlay_Squeezeback_BackgroundFadeIn(string, TimeSpan, TimeSpan, OverlayManagerPanEasing)

Starts a fade-in animation for the background of a squeezeback element.

public bool Video_Overlay_Squeezeback_BackgroundFadeIn(string name, TimeSpan startTime, TimeSpan duration, OverlayManagerPanEasing easing = OverlayManagerPanEasing.Linear)

Parameters

name string

The name of the squeezeback element.

startTime TimeSpan

The fade start time.

duration TimeSpan

The fade duration.

easing OverlayManagerPanEasing

The easing function.

Returns

bool

true if the squeezeback was found and fade started; otherwise, false.

Video_Overlay_Squeezeback_BackgroundFadeOut(string, TimeSpan, TimeSpan, OverlayManagerPanEasing)

Starts a fade-out animation for the background of a squeezeback element.

public bool Video_Overlay_Squeezeback_BackgroundFadeOut(string name, TimeSpan startTime, TimeSpan duration, OverlayManagerPanEasing easing = OverlayManagerPanEasing.Linear)

Parameters

name string

The name of the squeezeback element.

startTime TimeSpan

The fade start time.

duration TimeSpan

The fade duration.

easing OverlayManagerPanEasing

The easing function.

Returns

bool

true if the squeezeback was found and fade started; otherwise, false.

Video_Overlay_Squeezeback_SetBackgroundOnTop(string)

Sets the background layer to be on top in a squeezeback element.

public bool Video_Overlay_Squeezeback_SetBackgroundOnTop(string name)

Parameters

name string

The name of the squeezeback element.

Returns

bool

true if the squeezeback was found and updated; otherwise, false.

Video_Overlay_Squeezeback_SetVideoOnTop(string)

Sets the video layer to be on top in a squeezeback element.

public bool Video_Overlay_Squeezeback_SetVideoOnTop(string name)

Parameters

name string

The name of the squeezeback element.

Returns

bool

true if the squeezeback was found and updated; otherwise, false.

Video_Overlay_Squeezeback_SwapLayers(string)

Swaps the layers in a squeezeback element (video on top / background on top).

public bool Video_Overlay_Squeezeback_SwapLayers(string name)

Parameters

name string

The name of the squeezeback element.

Returns

bool

true if the squeezeback was found and layers swapped; otherwise, false.

Video_Overlay_Squeezeback_UpdateBackgroundImage(string, string, Rect)

Updates the background image of a squeezeback element.

public bool Video_Overlay_Squeezeback_UpdateBackgroundImage(string name, string filename, Rect backgroundRect = null)

Parameters

name string

The name of the squeezeback element.

filename string

The new background image filename.

backgroundRect Rect

The new background rectangle (null to keep current).

Returns

bool

true if the squeezeback was found and updated; otherwise, false.

Video_Overlay_Squeezeback_UpdateVideoPosition(string, Rect)

Updates the video position of a squeezeback element.

public bool Video_Overlay_Squeezeback_UpdateVideoPosition(string name, Rect videoRect)

Parameters

name string

The name of the squeezeback element.

videoRect Rect

The new video rectangle.

Returns

bool

true if the squeezeback was found and updated; otherwise, false.

Video_Overlay_Squeezeback_VideoFadeIn(string, TimeSpan, TimeSpan, OverlayManagerPanEasing)

Starts a fade-in animation for the video of a squeezeback element.

public bool Video_Overlay_Squeezeback_VideoFadeIn(string name, TimeSpan startTime, TimeSpan duration, OverlayManagerPanEasing easing = OverlayManagerPanEasing.Linear)

Parameters

name string

The name of the squeezeback element.

startTime TimeSpan

The fade start time.

duration TimeSpan

The fade duration.

easing OverlayManagerPanEasing

The easing function.

Returns

bool

true if the squeezeback was found and fade started; otherwise, false.

Video_Overlay_Squeezeback_VideoFadeOut(string, TimeSpan, TimeSpan, OverlayManagerPanEasing)

Starts a fade-out animation for the video of a squeezeback element.

public bool Video_Overlay_Squeezeback_VideoFadeOut(string name, TimeSpan startTime, TimeSpan duration, OverlayManagerPanEasing easing = OverlayManagerPanEasing.Linear)

Parameters

name string

The name of the squeezeback element.

startTime TimeSpan

The fade start time.

duration TimeSpan

The fade duration.

easing OverlayManagerPanEasing

The easing function.

Returns

bool

true if the squeezeback was found and fade started; otherwise, false.

Video_Overlay_Update(IOverlayManagerElement)

Updates an existing overlay element by removing and re-adding it with new properties. This method is used to refresh an overlay after modifying its properties.

public void Video_Overlay_Update(IOverlayManagerElement overlay)

Parameters

overlay IOverlayManagerElement

The overlay element to update with its new properties.

Video_Overlay_UpdateImageFile(string, string)

Updates the filename of an image overlay.

public bool Video_Overlay_UpdateImageFile(string name, string newFilename)

Parameters

name string

The name of the image overlay.

newFilename string

The new image filename.

Returns

bool

true if the image was found and updated; otherwise, false.

Video_Overlay_UpdateImagePosition(string, int, int, int, int)

Updates the position of an image overlay.

public bool Video_Overlay_UpdateImagePosition(string name, int x, int y, int width = 0, int height = 0)

Parameters

name string

The name of the image overlay.

x int

The new X position.

y int

The new Y position.

width int

The new width (0 to keep current).

height int

The new height (0 to keep current).

Returns

bool

true if the image was found and updated; otherwise, false.

IMediaBlockInternals.SetContext(MediaBlocksPipeline)

Associates this overlay manager block with a pipeline and initializes its internal context. This method is called internally when the block is added to a pipeline.

void IMediaBlockInternals.SetContext(MediaBlocksPipeline pipeline)

Parameters

pipeline MediaBlocksPipeline

The MediaBlocksPipeline instance that will manage this block.

See Also