Represents one acquisition stream of a Device. More...

Inherits IStream, IAcquisition, IObservable< StreamImage >, and IDisposable.

Public Member Functions
void	Dispose ()
	IDisposable implementation. More...

virtual StreamImage	GetSnapshot ()
	Acquires a single image and returns it. More...

virtual StreamImage	GetTimedSnapshot (UsTimeSpan timeSpan)
	Acquires a single image and returns it. More...

virtual StreamImage	GetTimedSnapshot (UsTimeSpan timeSpan, out WaitStatus status)
	As GetTimedSnapshot(UsTimeSpan), but does not throw on timeout. More...

void	Start ()
	Starts the acquisition.

virtual StreamImage	Wait ()
	Waits for indefinitely for the next acquired image and returns it. More...

virtual StreamImage	Wait (out WaitStatus status)
	Waits for indefinitely for the next acquired image and returns it. More...

virtual StreamImage	WaitFor (UsTimeSpan timeSpan)
	Waits for the given timeSpan for the next acquired image. More...

virtual StreamImage	WaitFor (UsTimeSpan timeSpan, out WaitStatus status)
	As WaitFor(UsTimeSpan), but does not throw on timeout. More...

void	Stop ()
	Stops the acquisition. More...

virtual bool	TryStop ()
	Tries to stop the acquisition of images. More...

void	Abort ()
	Stops the acquisition of images immediately. More...

virtual bool	TryAbort ()
	Tries to stop the acquisition of images immediately. More...

virtual IDisposable	Subscribe (IObserver< StreamImage > observer)
	Notifies this stream that the given observer is to receive new image notifications. More...

void	Start ()
	Start the acquisition.

void	Stop ()
	Stops the acquisition.

void	Abort ()
	Stops the acquisition of images immediately.

StreamImage	GetSnapshot ()
	Acquires a single image and returns it. More...

StreamImage	GetTimedSnapshot (UsTimeSpan timeSpan)
	Acquires a single image and returns it. More...

StreamImage	GetTimedSnapshot (UsTimeSpan timeSpan, out WaitStatus status)
	Acquires a single image and returns it. More...

void	Start ()
	Starts the acquisition of images.

StreamImage	Wait ()
	Waits infinitely for the next acquired image and returns it. More...

StreamImage	Wait (out WaitStatus status)
	Waits infinitely for the next acquired image and returns it. More...

StreamImage	WaitFor (UsTimeSpan timeSpan)
	Waits for the given timeSpan for the next acquired image. More...

StreamImage	WaitFor (UsTimeSpan timeSpan, out WaitStatus status)
	Waits for the given timeSpan for the next acquired image. More...

void	Stop ()
	Stops the acquisition of images. More...

bool	TryStop ()
	Tries to stop the acquisition of images. More...

void	Abort ()
	Stops the acquisition of images immediately. More...

bool	TryAbort ()
	Tries to stop the acquisition of images immediately. More...

Static Public Attributes
static readonly UsTimeSpan	MaxTimeoutValue = UsTimeSpan.FromMilliseconds(int.MaxValue)
	Gets the maximal timeout a device normally supports.

Protected Member Functions
virtual void	Dispose (bool disposing)
	IDispose helper function. More...

abstract StreamImage	MakeStreamImage (IntPtr handle)
	Factory function for creating the returned image from the acquisition engine. More...

abstract StreamImage	MakeSnapshotImage (IntPtr handle)
	Factory function for creating the returned image from the acquisition engine. More...

virtual void	ObservableAcquisitionLoop ()
	This is the acquisition loop for Subscribe(IObserver<StreamImage>)d observers. More...

void	SendCompleteToObservers ()
	Calls IObserver<T>.OnCompleted on all subscribed observers. More...

void	SendErrorToObservers (Exception error)
	Calls IObserver<T>.OnError(Exception) on all subscribed observers. More...

void	SendImageToObservers (StreamImage image)
	Calls IObserver<T>.OnNext(T) with the given image . More...

Properties
AcquisitionInterface	AcquisitionInterface `[get, set]`
	Gets or sets the acquisition interface to use on this stream. More...

Device	Parent `[get]`
	Gets the parent Device.

virtual bool	IsIndexed `[get]`
	Gets whether this stream is an IndexedStream.

abstract StreamStatistics	Statistics `[get]`
	Gets the available device statistics

bool	IsRunning `[get]`
	Gets whether the acquisition is currently active. More...

abstract IRingBuffer	RingBuffer `[get]`
	Gets the `IRingBuffer` interface object if present. More...

Properties inherited from IStream
AcquisitionInterface	AcquisitionInterface `[get]`
	Gets or sets the acquisition interface to use on this stream.

bool	IsIndexed `[get]`
	Gets if this stream is indexed (has a fixed amount of data).

Properties inherited from IAcquisition
bool	IsRunning `[get]`
	Gets whether the acquisition is currently active. More...

Properties inherited from IDeviceInterface
Device	Parent `[get]`
	The Device this interface works on.

Detailed Description

Represents one acquisition stream of a Device.

Member Function Documentation

◆ Abort()

void Abort ( )

Stops the acquisition of images immediately.

This stops the acquisition as fast as possible interrupting the ongoing operation. This might result in partially acquired images.

If the underlying driver does not support this, this call behaves as if Stop had been called.

Implements IAcquisition.

◆ Dispose() [1/2]

void Dispose ( )

IDisposable implementation.

Call this method to release the resources allocated by this stream immediately. Remember that after calling Dispose, any subsequent access to references to this image will result in an ObjectDisposedException.

◆ Dispose() [2/2]

virtual void Dispose ( bool disposing )

protectedvirtual

IDispose helper function.

Parameters

disposing true when called via IDisposable.Dispose, false when called by the finalizer.

◆ GetSnapshot()

virtual StreamImage GetSnapshot ( )

virtual

Acquires a single image and returns it.

Attention: it is generally not possible to call this method while the acquisition has been started by Start or if an observer is Subscribe(IObserver<StreamImage>)ed.

Dispose the returned Image when not needed anymore!

By default the returned image content is only guaranteed to stay unchanged until the next call to this method; afterwards the returned image is normally disposed. Thus it is normally not save to use this image in a display.

Returns: Grabbed image.

Implements IAcquisition.

◆ GetTimedSnapshot() [1/2]

virtual StreamImage GetTimedSnapshot ( UsTimeSpan timeSpan )

virtual

Acquires a single image and returns it.

Waits for the given timeSpan for the image to be taken.

Attention: it is generally not possible to call this method while the acquisition has been started by Start.

Dispose the returned Image when not needed anymore!

By default the returned image content is only guaranteed to stay unchanged until the next call to this method; afterwards the returned image is normally disposed. Thus it is normally not save to use this image in a display.

Parameters

timeSpan Time span to wait for (millisecond granularity).

Returns: Grabbed image.

Exceptions

System.TimeoutException Most common exception: timeSpan elapsed without receiving new image.

Implements IAcquisition.

◆ GetTimedSnapshot() [2/2]

virtual StreamImage GetTimedSnapshot	(	UsTimeSpan	timeSpan,
		out WaitStatus	status
	)

virtual

As GetTimedSnapshot(UsTimeSpan), but does not throw on timeout.

Parameters

timeSpan	Time span to wait for (millisecond granularity).
status	Either WaitStatus.Ok or WaitStatus.Timeout if timeSpan was exceeded.

Returns: Acquired image if status is WaitStatus.Ok.

Implements IAcquisition.

◆ MakeSnapshotImage()

abstract StreamImage MakeSnapshotImage ( IntPtr handle )

protectedpure virtual

Factory function for creating the returned image from the acquisition engine.

Parameters

handle Acquired image handle; IntPtr.Zero for non (i.e. the device handle points to the newly synced image.

Returns: Acquired image.

◆ MakeStreamImage()

abstract StreamImage MakeStreamImage ( IntPtr handle )

protectedpure virtual

Factory function for creating the returned image from the acquisition engine.

Parameters

handle Acquired image handle; IntPtr.Zero for non (i.e. the device handle points to the newly synced image.

Returns: Acquired image.

◆ ObservableAcquisitionLoop()

virtual void ObservableAcquisitionLoop ( )

protectedvirtual

This is the acquisition loop for Subscribe(IObserver<StreamImage>)d observers.

This method is executed in a long-running task scheduled on the default scheduler.

Reimplemented in IndexedStream.

◆ SendCompleteToObservers()

void SendCompleteToObservers ( )

protected

Calls IObserver<T>.OnCompleted on all subscribed observers.

It will not unsubscribe them; this is the job of the observers themselves.

◆ SendErrorToObservers()

void SendErrorToObservers ( Exception error )

protected

Calls IObserver<T>.OnError(Exception) on all subscribed observers.

Parameters

error Exception that occured while Wait()ing on next image.

◆ SendImageToObservers()

void SendImageToObservers ( StreamImage image )

protected

Calls IObserver<T>.OnNext(T) with the given image .

Parameters

image Image to send to all subscribed observers.

◆ Stop()

void Stop ( )

Stops the acquisition.

This stops the acquisition gracefully letting the ongoing operation finish. The disadvantage may be that this call lasts until the timeout time of the last Wait() call.

Implements IAcquisition.

◆ Subscribe()

virtual IDisposable Subscribe ( IObserver< StreamImage > observer )

virtual

Notifies this stream that the given observer is to receive new image notifications.

When subscribing to a stream which is not running (see IsRunning), this stream is Started. If this stream IsIndexed it runs by default until all images are delivered once. For endless streams it keeps running until all subscribed observer s are unsubscribed via the returned IDisposable object or Stop/Abort is called. If one of these two functions is called or this stream IsIndexed, all subscribed observer s receive the IObserver<T>.OnCompleted notification.

If you wish to automatically loop IndexedStreams, you need to set IndexedStream.LoopObservers to true.

The stream is kept running even if IObserver<T>.OnError(Exception) is called. Note, though, that if you use the reactive extensions (System.Reactive), they will unsubscribe in this case and you need to resetup your application. Thus if you use your own IObserver<T> implementation you can handle it as you wish.

The acquisition loop is run in a long running Task and using Wait(). Thus there are no timeouts. Unsubscribing all observer s will result in Abort being called.

Manually calling Wait() or WaitFor(UsTimeSpan) is forbidden as long as there is at least one subscribed observer .

Parameters

observer Observer to receive image notifications.

Returns: Reference to an interface to allow stop receiving notifications (unsubscribe).

◆ TryAbort()

virtual bool TryAbort ( )

virtual

Tries to stop the acquisition of images immediately.

Like Abort it stops as fast as possible with the same implications. This variant does not throw exceptions exception ObjectDisposedExceptions.

Returns: true on success; false on error.

Implements IAcquisition.

◆ TryStop()

virtual bool TryStop ( )

virtual

Tries to stop the acquisition of images.

Like Stop it tries to halt gracefully with the same implications. This variant does not throw exceptions exception ObjectDisposedExceptions.

Returns: true on success; false on error.

Implements IAcquisition.

◆ Wait() [1/2]

virtual StreamImage Wait ( )

virtual

Waits for indefinitely for the next acquired image and returns it.

Dispose the returned Image when not needed anymore!

By default the returned image content is only guaranteed to stay unchanged until the next call to this method; afterwards the returned image is normally disposed. Thus it is normally not save to use this image in a display.

The returned image is not necessary the newest. If more images where acquired since the last call to this method, the content is the oldest not collected image buffer by default.

You can also Abort this wait call.

Returns: Grabbed image.

Exceptions

OperationCanceledException This operation has been aborted via Abort or TryAbort.

Implements IAcquisition.

◆ Wait() [2/2]

virtual StreamImage Wait ( out WaitStatus status )

virtual

Waits for indefinitely for the next acquired image and returns it.

Dispose the returned Image when not needed anymore!

By default the returned image content is only guaranteed to stay unchanged until the next call to this method; afterwards the returned image is normally disposed. Thus it is normally not save to use this image in a display.

The returned image is not necessary the newest. If more images where acquired since the last call to this method, the content is the oldest not collected image buffer by default.

You can also Abort this wait call which results in status being WaitStatus.Abort.

Parameters

status Either WaitStatus.Ok or WaitStatus.Abort if opperation was Aborted.

Returns: Grabbed image.

Implements IAcquisition.

◆ WaitFor() [1/2]

virtual StreamImage WaitFor ( UsTimeSpan timeSpan )

virtual

Waits for the given timeSpan for the next acquired image.

Attention: it is generally not safe to call the wait method from different threads on the same object!

Dispose the returned Image when not needed anymore!

By default the returned image content is only guaranteed to stay unchanged until the next call to this method; afterwards the returned image is normally disposed. Thus it is normally not save to use this image in a display.

The returned image is not necessary the newest. If more images where acquired since the last call to this method, the content is the oldest not collected image buffer by default.

Parameters

timeSpan Time span to wait for (millisecond granularity).

Returns: Grabbed image.

Exceptions

TimeoutException	Most common exception: timeSpan elapsed without receiving new image.
OperationCanceledException	This operation has been aborted via Abort or TryAbort.

Implements IAcquisition.

◆ WaitFor() [2/2]

virtual StreamImage WaitFor	(	UsTimeSpan	timeSpan,
		out WaitStatus	status
	)

virtual

As WaitFor(UsTimeSpan), but does not throw on timeout.

Still throws exceptions on other errors.

Parameters

timeSpan	Time span to wait for (millisecond granularity).
status	Either WaitStatus.Ok; WaitStatus.Timeout if timeSpan was exceeded; WaitStatus.Abort if Abort or TryAbort was successfully called.>

Returns: Acquired image if status is WaitStatus.Ok.

Implements IAcquisition.

Property Documentation

◆ AcquisitionInterface

AcquisitionInterface AcquisitionInterface

getset

Gets or sets the acquisition interface to use on this stream.

When set the underlying acquisition interface is changed.

The currently used acquisition engine. By default the best acquisition engine is chosen (e.g. Driver.AcquisitionInterface.Grab2 before Driver.AcquisitionInterface.Grabber.

Exceptions

InvalidOperationException	Changing the acquisition interface while grabbing is not allowed.
NotImplementedException	The desired acquisition interface is not supported on the device.

Implements IStream.

◆ IsRunning

bool IsRunning

get

Gets whether the acquisition is currently active.

true if the underlying device is acquiring data; false if it is idle.

Implements IAcquisition.

◆ RingBuffer

abstract IRingBuffer RingBuffer

get

Gets the IRingBuffer interface object if present.

Object for accessing the interface; null if not available.

Public Member Functions

Static Public Attributes

Protected Member Functions

Properties

Detailed Description

Member Function Documentation

◆ Abort()

◆ Dispose() [1/2]

◆ Dispose() [2/2]

◆ GetSnapshot()

◆ GetTimedSnapshot() [1/2]

◆ GetTimedSnapshot() [2/2]

◆ MakeSnapshotImage()

◆ MakeStreamImage()

◆ ObservableAcquisitionLoop()

◆ SendCompleteToObservers()

◆ SendErrorToObservers()

◆ SendImageToObservers()

◆ Stop()

◆ Subscribe()

◆ TryAbort()

◆ TryStop()

◆ Wait() [1/2]

◆ Wait() [2/2]

◆ WaitFor() [1/2]

◆ WaitFor() [2/2]

Property Documentation

◆ AcquisitionInterface

◆ IsRunning

◆ RingBuffer