Table of Contents

Class RealSenseSourceBlock

Namespace
VisioForge.Core.MediaBlocks.Sources
Assembly
VisioForge.Core.dll

Intel RealSense depth camera source (D400 family and later) over librealsense: synchronized colour, depth and infrared outputs, depth optionally aligned to colour and colorized for display, and the distance at a pixel.

public class RealSenseSourceBlock : SourceMediaBlock, IMediaBlock, IDisposable, IMediaBlockInternals

Inheritance

Implements

Inherited Members

Extension Methods

Remarks

Needs realsense2.dll, which the VisioForge.CrossPlatform.RealSense.Windows.x64 package carries. No RealSense driver is needed on Windows 10 and 11. Every output is one stream of the same librealsense frameset; an output the caller does not connect is discarded.

Constructors

RealSenseSourceBlock(RealSenseSourceSettings)

Initializes a new instance of the VisioForge.Core.MediaBlocks.Sources.RealSenseSourceBlock class.

public RealSenseSourceBlock(RealSenseSourceSettings settings)

Parameters

settings RealSenseSourceSettings

The settings.

Properties

ColorOutput

Gets the colour output (RGB). Null when VisioForge.Core.Types.X.Sources.RealSenseSourceSettings.Color is not set.

public MediaBlockPad ColorOutput { get; }

Property Value

MediaBlockPad

DepthOutput

Gets the depth output: RGB when VisioForge.Core.Types.X.Sources.RealSenseSourceSettings.DepthMode is VisioForge.Core.Types.X.Sources.RealSenseDepthMode.Colorized, GRAY16_LE when it is VisioForge.Core.Types.X.Sources.RealSenseDepthMode.Raw. Null when VisioForge.Core.Types.X.Sources.RealSenseSourceSettings.Depth is not set.

public MediaBlockPad DepthOutput { get; }

Property Value

MediaBlockPad

DepthScale

Gets the depth scale of the camera: metres per unit of a raw depth value. Zero until the block is built with depth enabled.

public float DepthScale { get; }

Property Value

float

InfraredOutput

Gets the infrared output (GRAY8). Null when VisioForge.Core.Types.X.Sources.RealSenseSourceSettings.Infrared is not set.

public MediaBlockPad InfraredOutput { get; }

Property Value

MediaBlockPad

Input

Gets the primary input pad for this media block.

public override MediaBlockPad Input { get; }

Property Value

MediaBlockPad

Inputs

Gets the collection of input pads for this media block.

public override MediaBlockPad[] Inputs { get; }

Property Value

MediaBlockPad[]

Output

Gets the first enabled output: colour, else depth, else infrared.

public override MediaBlockPad Output { get; }

Property Value

MediaBlockPad

Outputs

Gets the outputs of the enabled streams, in the order colour, depth, infrared.

public override MediaBlockPad[] Outputs { get; }

Property Value

MediaBlockPad[]

Settings

Gets the settings.

public RealSenseSourceSettings Settings { get; }

Property Value

RealSenseSourceSettings

Type

Gets or sets the functional type of this media block (source, sink, effect, encoder, etc.). This property must be overridden in derived classes to specify the block's role in the pipeline.

public override MediaBlockType Type { get; }

Property Value

MediaBlockType

Exceptions

NotImplementedException

Thrown when the derived class has not implemented this property.

NotImplementedException

Thrown when the derived class has not implemented the setter.

Methods

Build()

Opens the camera with the configured streams and builds one appsrc per stream, its caps taken from the stream's mode in VisioForge.Core.MediaBlocks.Sources.RealSenseSourceBlock.Settings, which the camera was started in.

public override bool Build()

Returns

bool

true if the camera started and the elements were built; otherwise, false.

CleanUp()

Stops the camera and releases the elements; the next build creates them again.

public void CleanUp()

Dispose(bool)

Releases unmanaged and - optionally - managed resources. Override this method in derived classes to implement block-specific cleanup logic.

protected override void Dispose(bool disposing)

Parameters

disposing bool

true to release both managed and unmanaged resources; false to release only unmanaged resources.

Remarks

An override must call its CleanUp() only under disposing. VisioForge.Core.MediaBlocks.MediaBlock.Finalize reaches this method with false, and a block's CleanUp() releases GstSharp wrappers - which takes GStreamer locks and can block - on the finalizer thread, which must never do either. A block that is never disposed leaves its elements to the pipeline that owns them; that is what their toggle refs are for. base.Dispose(disposing) stays outside the guard, because the latch below has to be set on both paths. The one carve-out is a block holding a resource nothing else can release - a device handle, say, which no pipeline owns and no toggle ref reclaims; such a block may run its CleanUp() on the finalizer path, guarded against throwing, and has to say why at the call site (see AndroidUVCSourceBlock). GitHub issue #958.

EnumerateDevicesAsync()

Lists the connected RealSense cameras and the colour, depth and infrared modes each one reports.

public static Task<RealSenseDeviceInfo[]> EnumerateDevicesAsync()

Returns

Task<RealSenseDeviceInfo[]>

The cameras; empty when none is connected.

Exceptions

RealSenseException

librealsense reported an error.

DllNotFoundException

realsense2 is not available.

GetCore()

Retrieves the core BaseElement wrapper that provides additional functionality around the GStreamer element. This wrapper adds VisioForge-specific features and simplifies common operations on the underlying GStreamer element.

public BaseElement GetCore()

Returns

BaseElement

The BaseElement wrapper instance that encapsulates the GStreamer element.

GetDistance(int, int)

Gets the distance, in metres, to the point at a pixel of the last depth frame. With VisioForge.Core.Types.X.Sources.RealSenseSourceSettings.AlignDepthToColor the coordinates are colour-image coordinates.

public float GetDistance(int x, int y)

Parameters

x int

The column.

y int

The row.

Returns

float

The distance in metres; 0 when the camera has no depth for that pixel, or no depth frame has arrived yet.

Exceptions

ArgumentOutOfRangeException

The pixel is outside the depth frame.

GetElement()

Retrieves the primary GStreamer element that represents this MediaBlock in the pipeline. This element is the main component that performs the actual media processing and is connected to other elements in the GStreamer pipeline.

public Element GetElement()

Returns

Element

The GStreamer Element instance, or null if the block hasn't been built yet.

IsAvailable()

Determines whether librealsense can be loaded.

public static bool IsAvailable()

Returns

bool

true if realsense2 loads; otherwise, false.

Stop()

Stops the capture, waits for the capture thread to finish, stops the camera and ends every output.

public override bool Stop()

Returns

bool

true.

IMediaBlockInternals.SetContext(MediaBlocksPipeline)

Associates this MediaBlock with a pipeline and initializes its internal context. This method is called automatically when the block is added to a pipeline, providing access to shared resources and pipeline-wide configuration.

void IMediaBlockInternals.SetContext(MediaBlocksPipeline pipeline)

Parameters

pipeline MediaBlocksPipeline

The MediaBlocksPipeline instance that will manage this block.