Guía de Uso del Bloque Overlay Manager¶

Descripción General¶

El OverlayManagerBlock es un componente poderoso de MediaBlocks que proporciona composición dinámica de superposiciones de video multicapa y gestión. Te permite agregar varios elementos de superposición (imágenes, texto, formas, animaciones) sobre el contenido de video con actualizaciones en tiempo real, gestión de capas y características avanzadas como sombras, rotación y control de opacidad.

Características Principales¶

Múltiples Tipos de Superposición: Texto, imágenes, GIFs, SVG, formas (rectángulos, círculos, triángulos, estrellas, líneas), video en vivo (NDI, Decklink)
Gestión de Capas: Ordenamiento por z-index para apilamiento correcto de superposiciones
Efectos Avanzados: Sombras, rotación, opacidad, posicionamiento personalizado
Actualizaciones en Tiempo Real: Modificación dinámica de superposiciones durante la reproducción
Visualización Basada en Tiempo: Mostrar/ocultar superposiciones en marcas de tiempo específicas
Dibujo Personalizado: Soporte de callback para operaciones de dibujo Cairo personalizadas
Fuentes de Video en Vivo: Soporte para fuentes de red NDI y tarjetas de captura Decklink
Multiplataforma: Funciona en Windows, Linux, macOS, iOS y Android

Referencia de Clase¶

OverlayManagerBlock¶

Namespace: VisioForge.Core.MediaBlocks.VideoProcessing

public class OverlayManagerBlock : MediaBlock, IMediaBlockInternals

Propiedades¶

Propiedad	Tipo	Descripción
`Type`	`MediaBlockType`	Retorna `MediaBlockType.OverlayManager`
`Input`	`MediaBlockPad`	Pad de entrada de video
`Output`	`MediaBlockPad`	Pad de salida de video con superposiciones

Métodos¶

Métodos Estáticos¶

public static bool IsAvailable()

Verifica si el overlay manager está disponible en el entorno actual (requiere soporte de overlay Cairo).

Métodos de Instancia¶

public void Video_Overlay_Add(IOverlayManagerElement overlay)

Agrega un nuevo elemento de superposición a la composición de video.

public void Video_Overlay_Remove(IOverlayManagerElement overlay)

Elimina un elemento de superposición específico.

public void Video_Overlay_RemoveAt(int index)

Elimina una superposición en el índice especificado.

public void Video_Overlay_Clear()

Elimina todos los elementos de superposición.

public void Video_Overlay_Update(IOverlayManagerElement overlay)

Actualiza una superposición existente (elimina y re-agrega con nuevas propiedades).

Tipos de Elementos de Superposición¶

Propiedades Comunes (IOverlayManagerElement)¶

Todos los elementos de superposición implementan la interfaz IOverlayManagerElement con estas propiedades comunes:

Propiedad	Tipo	Predeterminado	Descripción
`Name`	`string`	-	Nombre opcional para identificación
`Enabled`	`bool`	`true`	Habilitar/deshabilitar la superposición
`StartTime`	`TimeSpan`	`Zero`	Cuándo comenzar a mostrar (opcional)
`EndTime`	`TimeSpan`	`Zero`	Cuándo dejar de mostrar (opcional)
`Opacity`	`double`	`1.0`	Transparencia (0.0-1.0)
`Rotation`	`double`	`0.0`	Ángulo de rotación en grados (0-360)
`ZIndex`	`int`	`0`	Orden de capa (mayor = encima)
`Shadow`	`OverlayManagerShadowSettings`	-	Configuración de sombra

OverlayManagerText¶

Muestra texto con fondo y formato opcionales.

public class OverlayManagerText : IOverlayManagerElement

Propiedad	Tipo	Predeterminado	Descripción
`Text`	`string`	"Hello!!!"	Texto a mostrar
`X`	`int`	`100`	Posición X
`Y`	`int`	`100`	Posición Y
`Font`	`FontSettings`	Predeterminado del sistema	Configuración de fuente
`Color`	`SKColor`	`Red`	Color del texto
`Background`	`IOverlayManagerBackground`	`null`	Fondo opcional
`CustomWidth`	`int`	`0`	Ancho de límite personalizado (0 = auto)
`CustomHeight`	`int`	`0`	Alto de límite personalizado (0 = auto)

Ejemplo:

var text = new OverlayManagerText("¡Hola Mundo!", 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¶

Muestra imágenes estáticas con modos de estiramiento.

public class OverlayManagerImage : IOverlayManagerElement, IDisposable

Propiedad	Tipo	Predeterminado	Descripción
`X`	`int`	-	Posición X
`Y`	`int`	-	Posición Y
`Width`	`int`	-	Ancho de visualización (0 = original)
`Height`	`int`	-	Alto de visualización (0 = original)
`StretchMode`	`OverlayManagerImageStretchMode`	`None`	Modo de escalado de imagen

Modos de Estiramiento:

None - Tamaño original
Stretch - Llenar área objetivo (puede distorsionar)
Letterbox - Ajustar dentro del área (mantener relación de aspecto)
CropToFill - Llenar área recortando (mantener relación de aspecto)

Constructores:

// Desde archivo
new OverlayManagerImage(string filename, int x, int y, double alpha = 1.0)

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

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

Ejemplo:

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

OverlayManagerGIF¶

Muestra imágenes GIF animadas.

public class OverlayManagerGIF : IOverlayManagerElement, IDisposable

Propiedad	Tipo	Descripción
`Position`	`SKPoint`	Posición del GIF
`AnimationLength`	`TimeSpan`	Duración total de la animación

Ejemplo:

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

OverlayManagerDateTime¶

Muestra fecha/hora actual con formato personalizado.

public class OverlayManagerDateTime : IOverlayManagerElement

Propiedad	Tipo	Predeterminado	Descripción
`Text`	`string`	"[DATETIME]"	Plantilla de texto
`Format`	`string`	"MM/dd/yyyy HHss"	Formato de DateTime
`X`	`int`	`100`	Posición X
`Y`	`int`	`100`	Posición Y
`Font`	`FontSettings`	Predeterminado del sistema	Configuración de fuente
`Color`	`SKColor`	`Red`	Color del texto

Ejemplo:

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

Superposiciones de Video en Vivo¶

El Overlay Manager soporta fuentes de video en vivo como superposiciones, permitiéndote componer video en tiempo real desde tarjetas de captura Decklink o fuentes de red NDI.

OverlayManagerDecklinkVideo¶

Captura y muestra video de tarjetas de captura Blackmagic Decklink.

public class OverlayManagerDecklinkVideo : IOverlayManagerElement

Propiedad	Tipo	Predeterminado	Descripción
`DecklinkSettings`	`DecklinkVideoSourceSettings`	-	Configuración del dispositivo Decklink
`X`	`int`	-	Posición X
`Y`	`int`	-	Posición Y
`Width`	`int`	-	Ancho de superposición
`Height`	`int`	-	Alto de superposición
`StretchMode`	`OverlayManagerImageStretchMode`	`Letterbox`	Cómo ajustar el video
`VideoView`	`IVideoView`	`null`	Vista previa de video opcional
`VideoRendererSettings`	`VideoRendererSettingsX`	`null`	Configuración del renderizador

Ejemplo:

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

// Crear superposición Decklink
var decklinkOverlay = new OverlayManagerDecklinkVideo(
    decklinkSettings, 
    x: 10, 
    y: 10, 
    width: 640, 
    height: 360);

// Inicializar y agregar al overlay manager
if (decklinkOverlay.Initialize(autoStart: true))
{
    overlayManager.Video_Overlay_Add(decklinkOverlay);
}

// Limpiar cuando termine
decklinkOverlay.Stop();
decklinkOverlay.Dispose();

OverlayManagerNDIVideo¶

Captura y muestra video de fuentes NDI (Network Device Interface).

public class OverlayManagerNDIVideo : IOverlayManagerElement

Propiedad	Tipo	Predeterminado	Descripción
`NDISettings`	`NDISourceSettings`	-	Configuración de fuente NDI
`X`	`int`	-	Posición X
`Y`	`int`	-	Posición Y
`Width`	`int`	-	Ancho de superposición
`Height`	`int`	-	Alto de superposición
`StretchMode`	`OverlayManagerImageStretchMode`	`Letterbox`	Cómo ajustar el video
`VideoView`	`IVideoView`	`null`	Vista previa de video opcional
`VideoRendererSettings`	`VideoRendererSettingsX`	`null`	Configuración del renderizador

Ejemplo:

// Descubrir fuentes NDI en la red
var ndiSources = await DeviceEnumerator.Shared.NDISourcesAsync();
var ndiSettings = await NDISourceSettings.CreateAsync(
    null, 
    ndiSources[0].Name, 
    ndiSources[0].URL);

// Crear superposición NDI
var ndiOverlay = new OverlayManagerNDIVideo(
    ndiSettings, 
    x: 10, 
    y: 10, 
    width: 640, 
    height: 360);

// Inicializar y agregar al overlay manager
if (ndiOverlay.Initialize(autoStart: true))
{
    overlayManager.Video_Overlay_Add(ndiOverlay);
}

// Limpiar cuando termine
ndiOverlay.Stop();
ndiOverlay.Dispose();

Métodos Comunes para Superposiciones de Video en Vivo:

Initialize(bool autoStart) - Inicializar el pipeline de captura de video
Play() - Iniciar o reanudar captura de video
Pause() - Pausar captura de video
Stop() - Detener captura de video
Dispose() - Limpiar recursos

Superposiciones de Formas¶

OverlayManagerLine¶

public class OverlayManagerLine : IOverlayManagerElement

Propiedad	Tipo	Descripción
`Start`	`SKPoint`	Punto de inicio de línea
`End`	`SKPoint`	Punto de fin de línea
`Color`	`SKColor`	Color de línea

OverlayManagerRectangle¶

public class OverlayManagerRectangle : IOverlayManagerElement

Propiedad	Tipo	Descripción
`Rectangle`	`SKRect`	Límites del rectángulo
`Color`	`SKColor`	Color de relleno/trazo
`Fill`	`bool`	Rellenar o solo trazo

OverlayManagerCircle¶

public class OverlayManagerCircle : IOverlayManagerElement

Propiedad	Tipo	Descripción
`Center`	`SKPoint`	Centro del círculo
`Radius`	`double`	Radio del círculo
`Color`	`SKColor`	Color de relleno/trazo
`Fill`	`bool`	Rellenar o solo trazo

OverlayManagerTriangle¶

public class OverlayManagerTriangle : IOverlayManagerElement

Propiedad	Tipo	Descripción
`Point1`	`SKPoint`	Primer vértice
`Point2`	`SKPoint`	Segundo vértice
`Point3`	`SKPoint`	Tercer vértice
`Color`	`SKColor`	Color de relleno/trazo
`Fill`	`bool`	Rellenar o solo trazo

OverlayManagerStar¶

public class OverlayManagerStar : IOverlayManagerElement

Propiedad	Tipo	Descripción
`Center`	`SKPoint`	Centro de la estrella
`OuterRadius`	`double`	Radio de puntas externas
`InnerRadius`	`double`	Radio de puntas internas
`StrokeColor`	`SKColor`	Color de trazo
`FillColor`	`SKColor`	Color de relleno

OverlayManagerSVG¶

Muestra gráficos vectoriales SVG.

public class OverlayManagerSVG : IOverlayManagerElement, IDisposable

Propiedad	Tipo	Descripción
`X`	`int`	Posición X
`Y`	`int`	Posición Y
`Width`	`int`	Ancho de visualización
`Height`	`int`	Alto de visualización

OverlayManagerCallback¶

Dibujo personalizado usando gráficos Cairo.

public class OverlayManagerCallback : IOverlayManagerElement

Evento:

public event EventHandler<OverlayManagerCallbackEventArgs> OnDraw;

Ejemplo:

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

Configuración de Sombras¶

Configura sombras paralelas para elementos de superposición:

public class OverlayManagerShadowSettings

Propiedad	Tipo	Rango	Predeterminado	Descripción
`Enabled`	`bool`	-	`false`	Habilitar sombras
`Depth`	`double`	0-30	`5.0`	Distancia de desplazamiento de sombra
`Direction`	`double`	0-360°	`45.0`	Dirección de sombra
`Opacity`	`double`	0-1	`0.5`	Transparencia de sombra
`BlurRadius`	`double`	0-10	`2.0`	Cantidad de desenfoque de sombra
`Color`	`SKColor`	-	`Black`	Color de sombra

Referencia de Dirección:

0° = Derecha
90° = Abajo
180° = Izquierda
270° = Arriba

Fondos de Texto¶

Las superposiciones de texto pueden tener varias formas de fondo:

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 a rectángulo pero mantiene relación de aspecto cuadrada.

OverlayManagerBackgroundImage¶

Usa una imagen como fondo de texto con modos de estiramiento.

OverlayManagerBackgroundTriangle/Star¶

Fondos de forma personalizada para texto.

Configuración de Fuente¶

Configura la apariencia del texto:

public class FontSettings

Propiedad	Tipo	Descripción
`Name`	`string`	Nombre de familia de fuente
`Size`	`int`	Tamaño de fuente en puntos
`Style`	`FontStyle`	Normal, Italic, Oblique
`Weight`	`FontWeight`	Normal, Bold, Light, etc.

Ejemplo Completo¶

// Crear pipeline y bloques
var pipeline = new MediaBlocksPipeline();
var fileSource = new UniversalSourceBlock(await UniversalSourceSettings.CreateAsync(videoUri));
var overlayManager = new OverlayManagerBlock();
var videoRenderer = new VideoRendererBlock(pipeline, videoView);

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

// Agregar marca de agua con logo
var logo = new OverlayManagerImage("logo.png", 10, 10);
logo.Opacity = 0.5;
logo.ZIndex = 10; // Encima
overlayManager.Video_Overlay_Add(logo);

// Agregar marca de tiempo
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);

// Agregar título animado (aparece después de 5 segundos)
var title = new OverlayManagerText("¡Bienvenido!", 100, 100);
title.Font.Size = 72;
title.Color = SKColors.Yellow;
title.StartTime = TimeSpan.FromSeconds(5);
title.EndTime = TimeSpan.FromSeconds(10);
title.Rotation = -10; // Ligera inclinación
title.Background = new OverlayManagerBackgroundRectangle {
    Color = SKColors.DarkBlue,
    Fill = true
};
overlayManager.Video_Overlay_Add(title);

// Iniciar reproducción
await pipeline.StartAsync();

// Actualizar superposiciones dinámicamente
title.Text = "¡Texto Actualizado!";
overlayManager.Video_Overlay_Update(title);

Consideraciones de Rendimiento¶

Ordenamiento Z-Index: Los elementos se ordenan por Z-index antes del renderizado. Usa valores apropiados para minimizar sobrecarga de ordenamiento.
Formatos de Imagen: Usa imágenes formato RGBA8888 cuando sea posible para evitar conversión de color.
Efectos de Sombra: Las sombras con desenfoque son computacionalmente costosas. Úsalas con moderación para aplicaciones en tiempo real.
Actualizaciones: Usa Video_Overlay_Update() para elementos existentes en lugar de operaciones de eliminar/agregar.
Gestión de Recursos: Libera superposiciones de imagen y GIF cuando ya no se necesiten para liberar memoria.

Notas de Plataforma¶

Windows: Soporta System.Drawing.Bitmap además de SkiaSharp
iOS: La fuente predeterminada es "System-ui"
Android: La fuente predeterminada es "System-ui"
Linux/macOS: Enumera fuentes disponibles en tiempo de ejecución

Seguridad de Hilos¶

El overlay manager usa bloqueo interno para operaciones seguras entre hilos. Puedes agregar, eliminar o actualizar superposiciones de forma segura desde cualquier hilo.

Solución de Problemas¶

Superposición no visible: Verifica la propiedad Enabled, StartTime/EndTime y ordenamiento ZIndex.
El texto aparece borroso: Asegura que el tamaño de fuente sea apropiado para la resolución del video.
Uso de memoria: Libera superposiciones de imagen/GIF no usadas y usa tamaños de imagen apropiados.