Table of Contents

Class GPUVideoEffectDarkness

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

GPU-accelerated darkness adjustment effect that controls overall video luminance with inverse brightness behavior using DirectX hardware acceleration.

public class GPUVideoEffectDarkness : GPUVideoEffect, IGPUVideoEffectDarkness, IGPUVideoEffect

Inheritance

Implements

Inherited Members

Remarks

Available in: VideoCaptureCore, MediaPlayerCore, VideoEditCore (Windows only)

GPU-accelerated version using DirectX. Significantly faster than CPU equivalent for real-time processing of high-resolution video streams.

The darkness effect uniformly adjusts the luminance of all pixels by subtracting or adding values from RGB color components. Unlike brightness which adds light (values above 128), darkness reduces luminance (values above 128 darken). This creates the inverse effect of brightness adjustment. The effect operates per-pixel using DirectX compute shaders, enabling real-time processing with minimal CPU overhead even at 4K resolutions. A value of 128 represents neutral (no change), values above 128 darken the image, and values below 128 lighten it.

Common use cases include: creating fade-to-black transitions, simulating night or low-light scenes, darkening overexposed footage, creating silhouette effects, mood adjustment for dramatic or horror scenes, compensating for overly bright source material, preparing footage for overlay compositing, and creating vignette effects when combined with masks. The effect is particularly useful for cinematic fade effects and day-to-night transitions.

Performance characteristics: GPU acceleration provides near-zero overhead, processing full 4K frames in under 1ms on modern GPUs. The operation is memory-bandwidth limited rather than compute-limited, making it one of the most efficient video effects. Can be combined with other effects without significant performance impact. Ideal for real-time fade effects during live streaming or playback.

Technical notes: The darkness formula is effectively the inverse of brightness: while brightness adds values to RGB components, darkness subtracts them. Extreme values may cause clipping where dark areas saturate to black (0) or light areas approach white, resulting in loss of detail in shadows. For animated fade effects, vary the darkness value over time. Often combined with contrast adjustment to maintain tonal separation while darkening. The effect operates in RGB space with uniform adjustment across all color channels.

Cross-reference to CPU equivalent: See VisioForge.Core.Types.VideoEffects.VideoEffectDarkness for CPU-based alternative with animation support via ValueStop property.

Constructors

GPUVideoEffectDarkness(bool, int, string, TimeSpan, TimeSpan)

Initializes a new instance of the VisioForge.Core.Types.VideoEffects.GPUVideoEffectDarkness class with specified parameters.

public GPUVideoEffectDarkness(bool enabled, int value, string name = "Darkness", TimeSpan startTime = default, TimeSpan stopTime = default)

Parameters

enabled bool

Whether the effect is enabled. Set to true to apply immediately, false to create in disabled state.

value int

Darkness adjustment value (0-255, neutral at 128). Values above 128 darken, below lighten. Values outside range are clamped.

name string

Optional effect name for identification and retrieval. Default is "Darkness".

startTime TimeSpan

Start time for timed effects. Default is zero (apply from beginning).

stopTime TimeSpan

Stop time for timed effects. Default is zero (apply until end).

Remarks

When both start and stop times are zero, the effect applies for the entire video duration. The effect type is automatically set to VisioForge.Core.Types.VideoEffects.GPUVideoEffectType.Darkness. Common fade-to-black: start at 128, end at 255. Fade-from-black: start at 255, end at 128.

Properties

Value

Gets or sets the darkness adjustment value (0-255, neutral at 128).

public int Value { get; set; }

Property Value

int

Remarks

Controls the luminance reduction or addition applied uniformly to all pixels. Value of 128 represents no change (neutral). Values above 128 darken the image by subtracting from RGB components, values below lighten by adding.

Value ranges: 0 = Maximum lightening (near white), 1-127 = Lightening, 128 = Neutral (no change), 129-255 = Darkening, 255 = Maximum darkening (near black). Higher values create stronger darkening effects.

Methods

GetEffectType()

Gets the specific type of this GPU video effect.

public GPUVideoEffectType GetEffectType()

Returns

GPUVideoEffectType

Returns VisioForge.Core.Types.VideoEffects.GPUVideoEffectType.Darkness to identify this as a GPU-accelerated darkness effect.

Remarks

Used by the video processing pipeline to select the appropriate DirectX shader for darkness adjustment processing.