Table of Contents

Class ColorspaceConverterX

Namespace
VisioForge.Core.FastImageProcessingX
Assembly
VisioForge.Core.dll

Provides high-performance colorspace conversion for video frames using GStreamer.

public class ColorspaceConverterX : IDisposable

Inheritance

Implements

Inherited Members

Remarks

The ColorspaceConverterX class leverages GStreamer's videoconvert element to perform efficient colorspace transformations between different video formats. It supports: - Multiple input and output video formats (RGB, BGR, YUV, etc.) - Hardware-accelerated conversions when available - Thread-safe operation with internal synchronization - Configurable timeout for conversion operations

The converter uses an internal GStreamer pipeline with appsrc and appsink elements to process frames in real-time. Each conversion operation is synchronized using an AutoResetEvent to ensure proper buffer handling.

This class implements IDisposable and must be properly disposed to release GStreamer resources and native memory.

Constructors

ColorspaceConverterX(BaseContext, VideoFormatX, VideoFormatX, int, int)

Initializes a new instance of the VisioForge.Core.FastImageProcessingX.ColorspaceConverterX class.

public ColorspaceConverterX(BaseContext context, VideoFormatX inputFormat, VideoFormatX outputFormat, int width, int height)

Parameters

context BaseContext

The base context for logging and error reporting. Can be null if logging is not required.

inputFormat VideoFormatX

The video format of the input frames (e.g., RGB, BGR, YUV).

outputFormat VideoFormatX

The desired video format for the output frames.

width int

The width of the video frames in pixels.

height int

The height of the video frames in pixels.

Remarks

This constructor creates and configures a GStreamer pipeline with the following elements: - appsrc: Receives input frames - capsfilter (input): Enforces input format constraints - videoconvert: Performs the actual colorspace conversion - capsfilter (output): Enforces output format constraints - appsink: Provides converted output frames

The pipeline is automatically started during construction. If initialization fails, all allocated resources are cleaned up and an exception is thrown.

Exceptions

InvalidOperationException

Thrown if GStreamer elements cannot be created or linked.

Methods

Convert(VideoFrameX, VideoFrameX, int)

Converts a video frame from the input colorspace to the output colorspace.

public void Convert(VideoFrameX inFrame, VideoFrameX outFrame, int timeoutMs = 1000)

Parameters

inFrame VideoFrameX

The input video frame containing the source data.

outFrame VideoFrameX

The output video frame that will receive the converted data.

timeoutMs int

The maximum time to wait for conversion completion, in milliseconds. Default is 1000ms.

Remarks

This is a convenience overload that extracts the data pointers and sizes from the VisioForge.Core.Types.X.VideoFrameX objects and calls the main conversion method.

Exceptions

ObjectDisposedException

Thrown if the converter has been disposed.

Convert(nint, int, nint, int, int)

Converts video frame data from the input colorspace to the output colorspace.

public void Convert(nint inFrameData, int inFrameDataSize, nint outFrameData, int outFrameDataSize, int timeoutMs = 1000)

Parameters

inFrameData nint

A pointer to the input frame data buffer.

inFrameDataSize int

The size of the input frame data in bytes.

outFrameData nint

A pointer to the output frame data buffer that will receive the converted data.

outFrameDataSize int

The size of the output frame data buffer in bytes.

timeoutMs int

The maximum time to wait for conversion completion, in milliseconds. Default is 1000ms.

Remarks

This method performs a synchronous colorspace conversion operation: 1. Creates a GStreamer buffer from the input data 2. Pushes the buffer through the conversion pipeline 3. Waits for the converted output (with timeout) 4. Copies the result to the output buffer

The operation is thread-safe and uses internal locking to ensure only one conversion happens at a time. If the pipeline is not started, it will be started automatically.

If the conversion times out, no data is written to the output buffer and an error is logged.

Exceptions

ObjectDisposedException

Thrown if the converter has been disposed.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

Remarks

This method stops the GStreamer pipeline, disconnects event handlers, and releases all native resources including GStreamer elements and allocated memory buffers.

After calling Dispose, the converter instance cannot be reused. Consider using a 'using' statement to ensure proper disposal.

Dispose(bool)

Releases the unmanaged and optionally the managed resources used by the VisioForge.Core.FastImageProcessingX.ColorspaceConverterX class.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

If set to true, releases both managed and unmanaged resources; if false, releases only unmanaged resources.

Remarks

When called from Dispose (disposing = true), this method: - Disposes the buffer processed event - Frees allocated native memory for output buffers

Regardless of the disposing parameter, it always: - Stops the GStreamer pipeline - Disconnects event handlers to prevent callbacks after disposal - Disposes all GStreamer objects (bin, caps)

~ColorspaceConverterX()

Finalizes an instance of the VisioForge.Core.FastImageProcessingX.ColorspaceConverterX class and releases unmanaged resources.

protected ~ColorspaceConverterX()

Remarks

This destructor ensures that native resources are released even if Dispose is not called explicitly. For better performance and deterministic cleanup, always call Dispose explicitly.

Reset()

Resets the colorspace converter pipeline and clears internal buffers.

public void Reset()

Remarks

This method stops the GStreamer pipeline, restarts it, and releases all cached output buffers. Use this method if you need to recover from errors or clear the pipeline state.

After reset, the converter is ready to process new frames.