Table of Contents

Class VisioForgeX

Namespace
VisioForge.Core
Assembly
VisioForge.Core.dll

Provides static methods for initializing, managing, and destroying the VisioForge SDK. This class serves as the main entry point for setting up the SDK environment and controlling its lifecycle.

public static class VisioForgeX

Inheritance

Inherited Members

Examples

// Initialize the SDK when your application starts.
VisioForgeX.InitSDK();

// Check if the SDK is initialized.
if (VisioForgeX.IsSDKInitialized)
{
    Console.WriteLine("VisioForge SDK is ready.");
}

// Perform media operations...

// Destroy the SDK when your application exits to release resources.
VisioForgeX.DestroySDK();

Remarks

Proper initialization and destruction of the SDK are crucial for resource management and application stability. The SDK relies on GStreamer, and this class handles the underlying GStreamer initialization and cleanup. Use VisioForge.Core.VisioForgeX.InitSDKAsync(VisioForge.Core.GStreamer.ContextX,System.Boolean) to avoid blocking the calling thread; it offloads VisioForge.Core.VisioForgeX.InitSDK(VisioForge.Core.GStreamer.ContextX,System.Boolean) to the thread pool, so if initialization must run on a specific thread call VisioForge.Core.VisioForgeX.InitSDK(VisioForge.Core.GStreamer.ContextX,System.Boolean) directly. Only the cross-platform X-engines (VideoCaptureCoreX, VideoEditCoreX, MediaPlayerCoreX, MediaBlocksPipeline) require this initialization; the Windows-only DirectShow cores (VideoCaptureCore, VideoEditCore, MediaPlayerCore) do not.

Properties

CacheFolder

Gets or sets the folder the SDK loads its GStreamer natives from on Windows.

public static string CacheFolder { get; set; }

Property Value

string

Remarks

The default is %PUBLIC%\.gstreamer\<sdk-version>-<native-set>\<arch>. On start-up the SDK mirrors the application's own <arch> output folder into it and runs from there. The point of that copy is the GStreamer plugin registry: it keys every cached plugin on the file's absolute path, so a single canonical folder lets every VisioForge application on the machine share one warm registry instead of each paying a full cold scan. The folder name carries both the SDK version and a stamp of the redistributable the application deployed, so applications on different natives do not share one.

Set this to the application's own native folder - Path.Combine(AppContext.BaseDirectory, "x64") - before calling VisioForge.Core.VisioForgeX.InitSDK(VisioForge.Core.GStreamer.ContextX,System.Boolean) to skip the shared cache and load exactly what the application deployed. That is the mode to use when verifying a redistributable is complete, because the shared cache can satisfy a missing dependency from another application's files. The cost is that the application no longer shares the machine-wide registry and pays its own cold scan.

DebugLevel

Gets or sets the debug level for GStreamer messages. This controls the verbosity of logging from the underlying GStreamer framework.

public static DebugLevel DebugLevel { get; set; }

Property Value

DebugLevel

IsSDKInitialized

Gets a value indicating whether the VisioForge SDK is currently initialized.

public static bool IsSDKInitialized { get; }

Property Value

bool

Methods

DestroySDK()

Destroys the VisioForge SDK, releasing all allocated resources. This method should be called when the application no longer needs the SDK to prevent resource leaks.

public static bool DestroySDK()

Returns

bool

true if the SDK was successfully destroyed; otherwise, false.

InitSDK(ContextX, bool)

Initializes the VisioForge SDK synchronously. This method performs the necessary setup for the SDK, including GStreamer initialization.

public static void InitSDK(ContextX context = null, bool editing = false)

Parameters

context ContextX

Optional. The VisioForge.Core.GStreamer.ContextX to use for initialization. If null, a default context is created.

editing bool

Optional. A boolean value indicating whether the SDK is initialized for editing purposes. Defaults to false.

InitSDKAsync(ContextX, bool)

Initializes the VisioForge SDK asynchronously. This method performs the necessary setup for the SDK, including GStreamer initialization.

public static Task InitSDKAsync(ContextX context = null, bool editing = false)

Parameters

context ContextX

Optional. The VisioForge.Core.GStreamer.ContextX to use for initialization. If null, a default context is created.

editing bool

Optional. A boolean value indicating whether the SDK is initialized for editing purposes. Defaults to false.

Returns

Task

A Task representing the asynchronous initialization operation.

Remarks

Threading semantics: This method offloads VisioForge.Core.VisioForgeX.InitSDK(VisioForge.Core.GStreamer.ContextX,System.Boolean) to the thread pool via Task.Run. InitSDK performs synchronous, potentially blocking work (GStreamer registry scan, plugin loading, native dependency resolution, optional SSL setup on macOS) that can take hundreds of milliseconds on cold starts, so running it on the calling thread would freeze UIs.

Side-effect to be aware of: GStreamer / GLib unhandled-exception handlers registered during InitSDK are bound to whichever thread first triggered initialization. Because that thread is now a thread-pool worker rather than the caller's thread, application code that relies on init being run on a specific thread (e.g., for thread-static GLib state) should call VisioForge.Core.VisioForgeX.InitSDK(VisioForge.Core.GStreamer.ContextX,System.Boolean) directly on that thread instead of using VisioForge.Core.VisioForgeX.InitSDKAsync(VisioForge.Core.GStreamer.ContextX,System.Boolean).

StopMainLoop()

Stops the GStreamer GLib main-loop background thread WITHOUT deinitializing GStreamer. Intended for hosts that reload the managed AppDomain in-process — most notably the Unity Editor on script recompile / assembly reload or on entering/leaving Play mode with Domain Reload enabled — where the un-abortable native main-loop thread would otherwise hang the reload. Unlike VisioForge.Core.VisioForgeX.DestroySDK this does NOT call gst_deinit or reset the init state.

Because the init state is left untouched, the main loop is recreated only after the initialization bookkeeping is reset from clean statics — i.e. when the AppDomain is reloaded in-process (the Unity Editor reload guard's intended use), so the next VisioForge.Core.VisioForgeX.InitSDK(VisioForge.Core.GStreamer.ContextX,System.Boolean) runs a full init and rebuilds the loop. A plain in-domain VisioForge.Core.VisioForgeX.InitSDK(VisioForge.Core.GStreamer.ContextX,System.Boolean) call after this method returns via its fast path (_initState stays initialized and GstInitializer.IsInitialized stays true) and will NOT recreate the loop. To tear down and rebuild GStreamer without a domain reload, call VisioForge.Core.VisioForgeX.DestroySDK instead. 

public static void StopMainLoop()