Table of Contents

Class VideoEffectImageLogo

Namespace
VisioForge.Core.Types.VideoEffects
Assembly
VisioForge.Core.dll

Overlays static or animated images (including GIF animations) onto video frames with positioning, scaling, transparency, and color key support.

public class VideoEffectImageLogo : VideoEffect, IVideoEffectImageLogo, IVideoEffect, IDisposable

Inheritance

Implements

Inherited Members

Remarks

SDK Availability:

  • VideoCaptureCore SDK - Windows only
  • MediaPlayerCore SDK - Windows only
  • VideoEditCore SDK - Windows only

Platform Support: Windows only (requires GDI+ for image processing)

Effect Behavior:

The VideoEffectImageLogo effect composites image overlays onto video frames, supporting both static images (PNG, JPG, BMP, etc.) and animated GIF images. It provides comprehensive control over positioning, scaling, transparency, and chroma keying (color key transparency) for professional watermarking and branding applications.

Key Features:

  • Multiple Image Sources: Load from file path (VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Filename) or memory (VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.MemoryBitmap)
  • Animated GIF Support: Automatically detects and plays animated GIF images with proper frame timing
  • Flexible Positioning: Absolute pixel positioning or automatic alignment (top/center/bottom, left/center/right)
  • Scaling Modes: Stretch, letterbox, crop, or original size with VisioForge.Core.Types.VideoEffectStretchMode options
  • Transparency Control: Global alpha transparency level from 0-255
  • Color Key (Chroma Key): Make specific colors transparent for clean overlay compositing
  • Performance Optimized: Efficient bitmap caching and GPU-accelerated compositing
  • Dynamic Updates: Change images during playback using the VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Update method

Use Cases:

  • Corporate logo watermarking on video content
  • Channel branding for broadcast or streaming
  • Copyright protection watermarks
  • Network/station bugs (persistent logo in corner)
  • Animated GIF overlays for promotional content
  • Social media platform logos and handles
  • Sponsor logos in live events or sports broadcasting
  • Picture-in-picture effects with image borders
  • Lower-thirds graphics and title cards

Technical Details:

The effect loads images from either a file path or a System.Drawing.Bitmap object in memory. For animated GIFs, the effect automatically extracts all frames and plays them with proper timing stored in the GIF metadata. Animation can be enabled or disabled via the VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.AnimationEnabled property.

Images are stored in an internal bitmap buffer (VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Bitmap) with configurable bit depth (VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.BitmapDepth: 3 for RGB24, 4 for RGB32). The effect supports both RGB24 and RGB32 pixel formats for maximum compatibility with different video formats.

Transparency Options:

The effect provides two methods for transparency:

  1. Alpha Transparency: Use PNG images with alpha channel or set VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.TransparencyLevel (0-255) for global opacity
  2. Color Key (Chroma Key): Enable VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.UseColorKey and specify a VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.ColorKey color to make that color fully transparent
Color key is particularly useful for images that don't have alpha channels (JPG, BMP) or for removing specific background colors.

Positioning and Alignment:

The effect supports two positioning modes:

  • Custom positioning: Set VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.HorizontalAlignment and VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.VerticalAlignment to Custom, then use VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Left and VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Top for precise pixel placement
  • Automatic alignment: Use alignment properties (Left/Center/Right, Top/Center/Bottom) for standard positions that adapt to video resolution
Automatic alignment is recommended for logos that should maintain relative position across different video resolutions.

Scaling and Stretch Modes:

The VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.StretchMode property controls how the image is scaled:

  • VisioForge.Core.Types.VideoEffectStretchMode.None - Original image size (no scaling)
  • VisioForge.Core.Types.VideoEffectStretchMode.Stretch - Stretch to fill specified area (may distort aspect ratio)
  • VisioForge.Core.Types.VideoEffectStretchMode.Letterbox - Scale to fit while preserving aspect ratio (adds padding)
  • VisioForge.Core.Types.VideoEffectStretchMode.Crop - Scale to fill while preserving aspect ratio (may crop edges)

For dynamic image updates during playback, change the VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Filename or VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.MemoryBitmap property and call VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Update to reload and display the new image.

Constructors

VideoEffectImageLogo(bool, string, TimeSpan, TimeSpan)

Initializes a new instance of the VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo class with default settings.

public VideoEffectImageLogo(bool enabled, string name = "ImageLogo", TimeSpan startTime = default, TimeSpan stopTime = default)

Parameters

enabled bool

true to enable the image overlay effect immediately; false to create the effect in a disabled state. The effect can be enabled later by setting VisioForge.Core.Types.VideoEffects.VideoEffect.Enabled to true.

name string

A unique name for this effect instance. This name can be used to retrieve the effect interface for dynamic control during playback. Default is "ImageLogo".

startTime TimeSpan

The playback position at which this image overlay should begin displaying. Use Zero (default) to display the effect from the beginning of the video. The effect will not be visible before this time even if enabled is true.

stopTime TimeSpan

The playback position at which this image overlay should stop displaying. Use Zero (default) to display the effect until the end of the video. When set to a specific time, the effect will automatically hide after that playback position is reached.

Remarks

The constructor initializes the effect with sensible defaults optimized for logo/watermark overlays:

  • Stretch mode: None (original image size)
  • Animation: Enabled (animated GIFs will play automatically)
  • Transparency: 0 (fully opaque)
  • Color key: Disabled
  • Alignment: Custom (use VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Left and VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Top coordinates)
  • Position: (0, 0) top-left corner

After construction, set either VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Filename (to load from file) or VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.MemoryBitmap (to use an in-memory image). Configure positioning using either custom coordinates (VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Left, VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Top) or alignment properties (VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.HorizontalAlignment, VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.VerticalAlignment).

All visual properties can be modified after construction. Call VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Update after making changes to apply them during playback.

Properties

Animated

Gets or sets a value indicating whether the currently loaded image contains animation frames.

public bool Animated { get; set; }

Property Value

bool

Remarks

This property is automatically set by the effect when an image is loaded:

  • Set to true when a multi-frame animated GIF is detected
  • Set to false for all static image formats (PNG, JPG, BMP, single-frame GIF)

This is a read-only indicator of the image's animation capability. To control whether animation actually plays, use the VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.AnimationEnabled property.

You can check this property after loading an image to determine if animation controls should be shown in your UI.

AnimationEnabled

Gets or sets a value indicating whether animation should be enabled for animated image formats.

public bool AnimationEnabled { get; set; }

Property Value

bool

Remarks

This property controls whether animated image formats (primarily GIF) are played back with animation or displayed as static images.

When enabled (true):

  • Animated GIF images play their full animation sequence
  • Frame timing is read from the GIF metadata and respected during playback
  • Animation loops continuously throughout the video duration
  • The VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Animated property is automatically set to true when an animated image is detected

When disabled (false):

  • Only the first frame of animated GIFs is displayed
  • Reduces CPU usage for static displays
  • Useful when you want consistent static branding

Note: This property only affects animated image formats. Static images (PNG, JPG, BMP) are unaffected.

Bitmap

Gets or sets bitmap buffer.

public nint Bitmap { get; set; }

Property Value

nint

BitmapDepth

Gets or sets bitmap depth. 3 for RGB24, 4 for RGB32.

public int BitmapDepth { get; set; }

Property Value

int

BitmapHeight

Gets or sets bitmap height.

public int BitmapHeight { get; set; }

Property Value

int

BitmapWidth

Gets or sets bitmap width.

public int BitmapWidth { get; set; }

Property Value

int

ColorKey

Gets or sets the specific color that should be rendered as fully transparent (chroma key color).

public Color ColorKey { get; set; }

Property Value

Color

Remarks

When VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.UseColorKey is enabled, any pixels in the image matching this exact color are rendered as fully transparent. This is known as chroma keying or color keying, commonly used in video production.

Common color key choices:

  • Green: Color.Lime or Color.FromArgb(0, 255, 0) - Most common for chroma keying
  • Blue: Color.Blue - Alternative chroma key color
  • Magenta: Color.Magenta - Used when both green and blue are in the subject
  • White: Color.White - For removing white backgrounds
  • Black: Color.Black - For removing black backgrounds

Color key is most effective with solid, uniform background colors. For complex backgrounds or gradients, use PNG images with alpha channels instead.

The color matching is exact (RGB values must match precisely), so images with JPEG compression artifacts or anti-aliased edges may not key cleanly.

Filename

Gets or sets the file path to the image to be overlaid.

public string Filename { get; set; }

Property Value

string

Remarks

Specify the path to an image file to load and display as an overlay. The effect supports all standard image formats:

  • PNG - Recommended for logos with transparency (alpha channel)
  • GIF - Supports static and animated GIFs (animation controlled by VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.AnimationEnabled)
  • JPG/JPEG - Good for photographic overlays (no transparency support)
  • BMP - Uncompressed format (larger file size)
The path can be absolute or relative to the application working directory. Alternatively, use VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.MemoryBitmap to provide an image from memory instead of a file. If both VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Filename and VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.MemoryBitmap are set, VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.MemoryBitmap takes precedence.

GIFImage

Gets or sets GIF image object.

public object GIFImage { get; set; }

Property Value

object

HorizontalAlignment

Gets or sets the horizontal alignment of the image overlay within the video frame.

public ImageLogoHorizontalAlignment HorizontalAlignment { get; set; }

Property Value

ImageLogoHorizontalAlignment

Remarks

Controls automatic horizontal positioning of the image overlay. Available options:

  • VisioForge.Core.Types.VideoEffects.ImageLogoHorizontalAlignment.Custom - Use the explicit VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Left coordinate for precise positioning
  • VisioForge.Core.Types.VideoEffects.ImageLogoHorizontalAlignment.Left - Align to the left edge of the video frame
  • VisioForge.Core.Types.VideoEffects.ImageLogoHorizontalAlignment.Center - Center horizontally in the video frame
  • VisioForge.Core.Types.VideoEffects.ImageLogoHorizontalAlignment.Right - Align to the right edge of the video frame
When set to anything other than Custom, the VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Left property is ignored and the image is automatically positioned.

Common alignment combinations for logos:

  • Top-Right: Common for channel bugs/watermarks (like TV networks)
  • Bottom-Right: Popular for YouTube/streaming watermarks
  • Bottom-Left: Traditional watermark position
  • Center-Center: For prominent branding or title cards

Left

Gets or sets the X coordinate (horizontal position) of the image overlay in pixels from the left edge of the video frame.

public uint Left { get; set; }

Property Value

uint

Remarks

When using automatic horizontal alignment (VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.HorizontalAlignment set to Left, Center, or Right), this property is ignored. The position applies to the top-left corner of the image overlay. For typical logo placement, common positions include:

  • 0 or small value (10-20): Left edge logos
  • Video width - image width - margin: Right edge logos

MemoryBitmap

Gets or sets a bitmap image from memory to use as the overlay instead of loading from a file.

public Bitmap MemoryBitmap { get; set; }

Property Value

Bitmap

Remarks

This property allows you to provide an image from memory (e.g., generated programmatically, downloaded, or loaded from resources) instead of loading from a file using VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Filename.

When to use MemoryBitmap:

  • Programmatically generated logos or watermarks
  • Images loaded from embedded resources
  • Downloaded images from web services
  • Images processed by other components before overlay
  • Dynamic image generation based on runtime data

If both VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Filename and VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.MemoryBitmap are set, VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.MemoryBitmap takes precedence.

Memory management:

The effect maintains its own copy of the bitmap, so the original bitmap can be disposed after setting this property. When the effect is disposed, the internal bitmap copy is automatically cleaned up.

For animated images from memory, consider using the VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Filename approach or manually handling frame timing, as VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.MemoryBitmap works best with static images.

StretchMode

Gets or sets the scaling mode that controls how the image is sized and fitted within the overlay area.

public VideoEffectStretchMode StretchMode { get; set; }

Property Value

VideoEffectStretchMode

Remarks

Controls how the image is scaled when overlaid on the video:

  • VisioForge.Core.Types.VideoEffectStretchMode.None - Display image at original size without scaling
  • VisioForge.Core.Types.VideoEffectStretchMode.Stretch - Stretch to fill the target area (may distort aspect ratio)
  • VisioForge.Core.Types.VideoEffectStretchMode.Letterbox - Scale to fit while maintaining aspect ratio (adds transparent padding if needed)
  • VisioForge.Core.Types.VideoEffectStretchMode.Crop - Scale to fill while maintaining aspect ratio (may crop edges)
For logos and watermarks, VisioForge.Core.Types.VideoEffectStretchMode.None is typically preferred to maintain original quality and proportions. Letterbox mode is useful when you need the image to fit within a specific area while preserving its aspect ratio.

Top

Gets or sets the Y coordinate (vertical position) of the image overlay in pixels from the top edge of the video frame.

public uint Top { get; set; }

Property Value

uint

Remarks

When using automatic vertical alignment (VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.VerticalAlignment set to Top, Center, or Bottom), this property is ignored. The position applies to the top-left corner of the image overlay. For typical logo placement, common positions include:

  • 0 or small value (10-20): Top edge logos (channel bugs)
  • Video height - image height - margin: Bottom edge logos

TransparencyLevel

Gets or sets the global transparency level (alpha channel value) applied to the entire image overlay.

public int TransparencyLevel { get; set; }

Property Value

int

Remarks

This transparency level is applied globally to the entire image overlay, including areas that may already have alpha transparency (e.g., PNG images).

  • 0 (default): No additional transparency, image displays at full opacity
  • 1-128: Subtle to moderate transparency, allows video to show through slightly
  • 129-254: High transparency, creates a ghost/watermark effect
  • 255: Completely invisible (fully transparent)

This is useful for creating subtle watermarks that don't distract from the video content. Typical watermark transparency values range from 30-100 for visible but unobtrusive logos.

If the source image already has an alpha channel (e.g., PNG), this transparency level is multiplied with the existing alpha, making partially transparent areas even more transparent.

UseColorKey

Gets or sets a value indicating whether color key transparency is enabled.

public bool UseColorKey { get; set; }

Property Value

bool

Remarks

When enabled, all pixels in the image that match the VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.ColorKey color exactly are rendered as fully transparent. This allows you to remove specific background colors from images that don't have an alpha channel (JPG, BMP).

Color key transparency is applied before VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.TransparencyLevel, so you can combine both for partial transparency of non-keyed areas.

Disable this when:

  • Using PNG images with proper alpha channels
  • The VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.ColorKey color appears in the desired visible areas of the image
  • No background removal is needed

VerticalAlignment

Gets or sets the vertical alignment of the image overlay within the video frame.

public ImageLogoVerticalAlignment VerticalAlignment { get; set; }

Property Value

ImageLogoVerticalAlignment

Remarks

Controls automatic vertical positioning of the image overlay. Available options:

  • VisioForge.Core.Types.VideoEffects.ImageLogoVerticalAlignment.Custom - Use the explicit VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Top coordinate for precise positioning
  • VisioForge.Core.Types.VideoEffects.ImageLogoVerticalAlignment.Top - Align to the top edge of the video frame
  • VisioForge.Core.Types.VideoEffects.ImageLogoVerticalAlignment.Center - Center vertically in the video frame
  • VisioForge.Core.Types.VideoEffects.ImageLogoVerticalAlignment.Bottom - Align to the bottom edge of the video frame
When set to anything other than Custom, the VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Top property is ignored and the image is automatically positioned.

Automatic alignment is particularly useful for maintaining consistent logo placement across videos of different resolutions. For example, a bottom-right corner logo will remain in the bottom-right regardless of whether the video is 1080p or 4K.

Methods

Dispose(bool)

The dispose.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

The disposing.

Dispose()

The dispose.

public void Dispose()

~VideoEffectImageLogo()

Finalizes an instance of the VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo class.

protected ~VideoEffectImageLogo()

GetEffectType()

Gets the effect type identifier for this video effect.

public VideoEffectType GetEffectType()

Returns

VideoEffectType

VisioForge.Core.Types.VideoEffects.VideoEffectType.ImageLogo identifying this as an image overlay effect.

Remarks

This method is used internally by the SDK to identify and process different types of video effects.

Update()

Signals that effect properties have been modified and the image overlay should be reloaded and re-rendered.

public void Update()

Remarks

Call this method after modifying any properties of the effect (filename, position, transparency, color key, alignment, etc.) to trigger a reload and re-render of the image overlay. This is necessary for dynamic updates during playback.

The method sets an internal flag that causes the effect to reload the image and regenerate its internal bitmap on the next video frame. This is thread-safe and can be called from any thread.

Common scenarios requiring VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Update:

  • Changing the image file (VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Filename) to display a different logo
  • Updating the VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.MemoryBitmap with a new image
  • Modifying position or alignment to move the logo
  • Changing transparency level or color key settings
  • Enabling or disabling animation for animated GIFs
  • Changing the stretch mode

For image file changes, the new image is loaded from disk (or memory) when VisioForge.Core.Types.VideoEffects.VideoEffectImageLogo.Update triggers the reload, so ensure the file exists and is accessible before calling this method.

See Also