Fading groups

The fading groups allow to fade in / fade out, in a synchronized way, the main video, the audio and a set of text/image overlays.

A fading group is created with FadingGroup_Create, which returns the group identifier used by all the other functions. Text and image overlays are then assigned to the group with FadingGroup_AssignTextOverlay and FadingGroup_AssignImageOverlay. A given overlay belongs to at most one group.

By default a group fades only its assigned overlays. To fade the main video as well (to a solid color, black by default), enable FadingGroup_IncludeMainVideo and optionally set the color with FadingGroup_SetFadeColor.

The audio can be included in the fade as well with FadingGroup_IncludeAudio: the audio then fades to silence (and back) in synchronization with the visuals, following the same duration and easing curve. When several groups include the audio, their gains are combined.

Level semantics: 0% = fully visible, 100% = fully faded out. The reached level is held until the next trigger.

The fade is started with FadingGroup_FadeOut or FadingGroup_FadeIn, runs asynchronously over the duration set by FadingGroup_SetDuration, and follows the easing curve selected by FadingGroup_SetCurve (smoothstep by default, or linear). The transitions are interruptible: a trigger received while a transition is in progress reverses or redirects the fade seamlessly from the current level.

FadingGroup_FadeToLevelPercent animates the group from its current level to any intermediate level and holds it there: FadeIn and FadeOut are the 0 and 100 special cases, so e.g. a value of 50 dims the group half way. Two groups can be cross-faded with FadingGroup_CrossFade; the incoming group is expected to be at level 100% (previously faded out, or preset with FadingGroup_SetLevelPercent).

The completion of a transition is notified by the OnFadingCompleted event, whose FadedOut parameter returns true after a complete fade out (level 100%), false otherwise (fade in or partial fade).

The current level can be set immediately (without animation) with FadingGroup_SetLevelPercent, typically to hide an incoming scene before a cross-fade, and polled with FadingGroup_GetLevelPercent and FadingGroup_IsFading, which return silent defaults (-1 / false) for unknown group identifiers (no error logging, so they can be polled freely from a timer).

The other functions validate their parameters: an unknown or deleted group identifier, an out-of-range overlay index or an out-of-range value raises an LERROR log entry naming the offending function and parameter, then the call is ignored.

Deleting a group with FadingGroup_Delete is thread-safe: if a fade is in progress the deletion is deferred until the current rendering step completes.

Sample code:

// Create a 1500 ms fading group, fading the main video to black
FadingGroupId := VideoGrabber.FadingGroup_Create (1500);
VideoGrabber.FadingGroup_IncludeMainVideo (FadingGroupId, true);
VideoGrabber.FadingGroup_IncludeAudio (FadingGroupId, true); // also fade the audio to silence
VideoGrabber.FadingGroup_SetCurve (FadingGroupId, fcv_SmoothStep);
VideoGrabber.FadingGroup_AssignTextOverlay (FadingGroupId, TextOverlayIndex);

// Fade everything out, then later back in
VideoGrabber.FadingGroup_FadeOut (FadingGroupId);
...
VideoGrabber.FadingGroup_FadeIn (FadingGroupId);

// Or dim the group to 50% and hold it there
VideoGrabber.FadingGroup_FadeToLevelPercent (FadingGroupId, 50);