IStreamGrabber Interface#

Provides convenient access to the StreamGrabber.

Syntax#

C#

public interface IStreamGrabber

VB

Public Interface IStreamGrabber

The IStreamGrabber type exposes the following members.

Properties#

	Name	Description
	BufferFactory	Sets an alternative buffer factory that is used for buffer allocation.
	GrabResultWaitHandle	Provides access to a wait handle object indicating available grab results.
	GrabStopWaitHandle	Provides access to a wait handle object indicating that the grabbing has stopped.
	IsGrabbing	Indicates if the camera object is grabbing.
	UserData	Sets user data that is attached to each grab result of the stream whenever RetrieveResult(Int32, TimeoutHandling) is called.

Methods#

	Name	Description
	GrabOne(Int32)	Grabs one image.
	GrabOne(Int32, TimeoutHandling)	Grabs one image.
	RetrieveResult	Retrieves a grab result according to the grab strategy. Waits if the grab result is not yet available.
	Start()	Starts the grabbing of images.
	Start(Int64)	Starts the grabbing for a maximum number of images.
	Start(GrabStrategy, GrabLoop)	Starts the grabbing of images using a specific grab strategy and a specific grab loop type.
	Start(Int64, GrabStrategy, GrabLoop)	Starts the grabbing for a maximum number of images using a specific grab strategy and a specific grab loop type.
	Stop	Stops the grabbing of images.

Events#

	Name	Description
	GrabStarted	Occurs after a grab session has been started.
	GrabStarting	Occurs before a grab session is started.
	GrabStopped	Occurs after a grab session has been stopped.
	GrabStopping	Occurs before a grab session is stopped.
	ImageGrabbed	Occurs when an image has been grabbed.

IStreamGrabber.GrabStarted Event#

Occurs after a grab session has been started.

Syntax#

C#

event EventHandler<EventArgs> GrabStarted

VB

Event GrabStarted As EventHandler(Of EventArgs)

Value#

Type: System.EventHandler(EventArgs)

Remarks#

Thread Safety:
This event handler is synchronized with the camera.

Error Safety:
Exceptions from this call will propagate through. The notification of event handlers stops when an exception is triggered.

IStreamGrabber.GrabStarting Event#

Occurs before a grab session is started.

Syntax#

C#

event EventHandler<EventArgs> GrabStarting

VB

Event GrabStarting As EventHandler(Of EventArgs)

Value#

Type: System.EventHandler(EventArgs)

Remarks#

To avoid infinite recursion, IStreamGrabber.Start must not be called from here or from subsequent calls.

Thread Safety:
This handler is synchronized with the camera.

Error Safety:
Exceptions from this call will propagate through. The notification of event handlers stops when an exception is triggered.

IStreamGrabber.GrabStopped Event#

Occurs after a grab session has been stopped.

Syntax#

C#

event EventHandler<GrabStopEventArgs> GrabStopped

VB

Event GrabStopped As EventHandler(Of GrabStopEventArgs)

Value#

Type: System.EventHandler(GrabStopEventArgs)

Remarks#

Thread Safety:
This event handler is synchronized with the camera.

Error Safety:
Exceptions from this call will be caught and ignored. All event handlers are notified.

IStreamGrabber.GrabStopping Event#

Occurs before a grab session is stopped.

Syntax#

C#

event EventHandler<GrabStopEventArgs> GrabStopping

VB

Event GrabStopping As EventHandler(Of GrabStopEventArgs)

Value#

Type: System.EventHandler(GrabStopEventArgs)

Remarks#

To avoid infinite recursion, IStreamGrabber.Stop must not be called from here or from subsequent calls.

Thread Safety:
This event handler is synchronized with the camera.

Error Safety:
Exceptions from this call will be caught and ignored. All event handlers are notified.

IStreamGrabber.ImageGrabbed Event#

Occurs when an image has been grabbed.

Syntax#

C#

event EventHandler<ImageGrabbedEventArgs> ImageGrabbed

VB

Event ImageGrabbed As EventHandler(Of ImageGrabbedEventArgs)

Value#

Type: System.EventHandler(ImageGrabbedEventArgs)

Remarks#

The grab result passed can be evaluated here. It will be disposed when the call returns. If you want to keep the grab result, you must save it using the Clone() method. For more information, see IGrabResult.

Thread Safety:
This event handler is synchronized with the camera.

Error Safety:
Exceptions from this call will propagate through. The notification of event handlers stops when an exception is triggered.

IStreamGrabber.GrabOne Method (Int32)#

Grabs one image.

Syntax#

C#

IGrabResult GrabOne(
    int timeoutMs
)

VB

Function GrabOne ( 
    timeoutMs As Integer
) As IGrabResult

Parameters#

timeoutMs: Type: System.Int32
The timeout period in milliseconds for waiting for a grab result. Alternatively, the Infinite value can be set.

Return Value#

Type: IGrabResult
Returns the grab result.

Remarks#

This method throws exceptions on timeout TimeoutHandling.

Grabbing single images using a software trigger (see SoftwareTrigger(Object, EventArgs)) is recommended if you want to maximize frame rate. This is because the overhead per grabbed image is reduced compared to single frame acquisition (see AcquireSingleFrame(Object, EventArgs)). The grabbing can be started using Start(GrabStrategy, GrabLoop). Images are grabbed using the WaitForFrameTriggerReady(Int32, TimeoutHandling), ExecuteSoftwareTrigger(), and RetrieveResult(Int32, TimeoutHandling) methods instead of using GrabOne(Int32). Grabbing can be stopped using Stop() when done.

Preconditions:

The camera instance is opened.
The grabbing is stopped.

Postconditions:

The grabbing is stopped.
Grab specific parameters of the camera instance are unlocked, e.g. MaxNumBuffer.

Error Safety: The camera instance is still valid after an error. See Start(GrabStrategy, GrabLoop), RetrieveResult(Int32, TimeoutHandling), and Stop(). If exceptions are thrown after Start(GrabStrategy, GrabLoop), grabbing is stopped using Stop().

IStreamGrabber.GrabOne Method (Int32, TimeoutHandling)#

Grabs one image.

Syntax#

C#

IGrabResult GrabOne(
    int timeoutMs,
    TimeoutHandling timeoutHandling
)

VB

Function GrabOne ( 
    timeoutMs As Integer,
    timeoutHandling As TimeoutHandling
) As IGrabResult

Parameters#

timeoutMs: Type: System.Int32
The timeout period in milliseconds for waiting for a grab result. Alternatively, the Infinite value can be set.
timeoutHandling: Type: Basler.Pylon.TimeoutHandling
The action to perform when the functions exits with a timeout. If set to ThrowException, a timeout exception is thrown on timeout.

Return Value#

Type: IGrabResult
Returns the grab result or null on timeout.

Remarks#

The following code shows a simplified version of what is done (happy path scenario):

//grab one image
camera.StreamGrabber.Start(1, GrabStrategy.OneByOne, GrabLoop.ProvidedByUser);

//grab is stopped automatically due to maxImages = 1
return camera.StreamGrabber.RetrieveResult( timeoutMs, timeoutHandling);

This method can be used with the configuration AcquireSingleFrame AcquireSingleFrame(Object, EventArgs)).

Grabbing single images using a software trigger (see SoftwareTrigger(Object, EventArgs)) is recommended if you want to maximize frame rate. This is because the overhead per grabbed image is reduced compared to single frame acquisition (see AcquireSingleFrame(Object, EventArgs)). The grabbing can be started using Start(GrabStrategy, GrabLoop). Images are grabbed using the WaitForFrameTriggerReady(Int32, TimeoutHandling), ExecuteSoftwareTrigger(), and RetrieveResult(Int32, TimeoutHandling) methods instead of using GrabOne(Int32). Grabbing can be stopped using Stop() when done.

Preconditions:

The camera is opened.
The grabbing is stopped.

Postconditions:

The grabbing is stopped.
Grab specific parameters of the camera object are unlocked, e.g. MaxNumBuffer.

Error Safety:
The camera object is still valid after an error. See Start(GrabStrategy, GrabLoop), RetrieveResult(Int32, TimeoutHandling), and Stop(). If exceptions are thrown after Start(GrabStrategy, GrabLoop), grabbing is stopped using Stop().

IStreamGrabber.RetrieveResult Method#

Retrieves a grab result according to the grab strategy. Waits if the grab result is not yet available.

Syntax#

C#

IGrabResult RetrieveResult(
    int timeoutMs,
    TimeoutHandling timeoutHandling
)

VB

Function RetrieveResult ( 
    timeoutMs As Integer,
    timeoutHandling As TimeoutHandling
) As IGrabResult

Parameters#

timeoutMs: Type: System.Int32
The timeout period in milliseconds for waiting for a grab result. Alternatively, the Infinite value can be set.
timeoutHandling: Type: Basler.Pylon.TimeoutHandling
The action to perform when the functions exits with a timeout. If set to ThrowException, a timeout exception is thrown on timeout.

Return Value#

Type: IGrabResult
Returns the grab result.

Remarks#

Waits for a grab result if it is not yet available. Camera events are handled.
One grab result is retrieved per call (OneByOne grab strategy is applied).
If chunk mode is used, chunk data parsing is performed. The grab result data is updated using chunk data.
If a grab result becomes available, the image event ImageGrabbed is fired. The notification of event handlers stops when an event call triggers an exception.
If the maximum number of images has been grabbed, the grabbing is stopped by calling Stop().

You must check whether the grab represented by the grab result has been successful. For more information, see GrabSucceeded.

Preconditions:

There is no other thread waiting for a result.

Postconditions:

If no grab result has been retrieved, an empty grab result is returned in the grabResult parameter.
If the maximum number of images has been grabbed, grabbing is stopped.
If camera event handling is enabled and camera events were received, at least one or more camera event messages have been processed.

Thread Safety:
This method is synchronized with the camera.

Error Safety:
The camera object is still valid after an error. The grabbing is stopped if an exception is thrown.

IStreamGrabber.Start Method#

Starts the grabbing of images.

Syntax#

C#

void Start()

VB

Sub Start

Remarks#

The configuration event GrabStarting is fired. The notification of event handlers stops when an event call triggers an exception.
Grab-specific parameters of the camera object are locked, e.g. MaxNumBuffer.
If the camera device parameter ChunkModeActive is enabled, the chunk parsing support is initialized.
If the parameter GrabCameraEvents is enabled, the event grabbing support is initialized.
The AcquisitionStart command of the camera device is executed.
If the grabbing has been started successfully, the configuration event GrabStarted is fired. The notification of event handlers stops when an event call triggers an exception.

Preconditions:

The grabbing is stopped.

Postconditions:

The grabbing is started.
Grab-specific parameters of the camera object are locked, e.g. MaxNumBuffer.

Thread Safety:
This method is synchronized with the camera.

Error Safety:
The StreamGrabber is still valid after an error. Configuration event calls may throw exceptions. The grab implementation may throw exceptions. If the GrabStarted event call triggers an exception, the grabbing is stopped with Stop().

IStreamGrabber.Start Method (GrabStrategy, GrabLoop)#

Starts the grabbing of images using a specific grab strategy and a specific grab loop type.

Syntax#

C#

void Start(
    GrabStrategy strategy,
    GrabLoop grabLoopType
)

VB

Sub Start ( 
    strategy As GrabStrategy,
    grabLoopType As GrabLoop
)

Parameters#

strategy: Type: Basler.Pylon.GrabStrategy
The grab strategy. For more information, see GrabStrategy.
grabLoopType: Type: Basler.Pylon.GrabLoop
If grabLoopType is set to GrabLoop::ProvidedByStreamGrabber", an additional grab loop thread is used to run the grab loop.

Remarks#

If a grab loop thread has been used in the last grab session, the grab loop thread context is joined with the context of the caller.
The configuration event GrabStarting is fired. The notification of event handlers stops when an event call triggers an exception.
Grab-specific parameters of the camera object are locked, e.g. MaxNumBuffer.
If the camera device parameter ChunkModeActive is enabled, the chunk parsing support is initialized.
If the parameter GrabCameraEvents is enabled, the event grabbing support is initialized.
The AcquisitionStart command of the camera device is executed.
If the grabbing has been started successfully, the configuration event GrabStarted is fired. The notification of event handlers stops when an event call triggers an exception.
If grabLoopType is set to ProvidedByStreamGrabber, an additional grab loop thread is started that calls RetrieveResult(Int32, TimeoutHandling) in a loop.

Preconditions:

The grabbing is stopped.

Postconditions:

The grabbing is started.
Grab-specific parameters of the camera object are locked, e.g. MaxNumBuffer.
If grabLoopType is set to ProvidedByStreamGrabber, an additional grab loop thread is running that calls RetrieveResult(Int32, TimeoutHandling) in a loop. Images are processed by registered image event handlers.

Thread Safety:This method is synchronized with the camera.

Error Safety: The StreamGrabber is still valid after an error. Configuration event calls may throw exceptions. The grab implementation may throw exceptions. If the GrabStarted event call triggers an exception, the grabbing is stopped with Stop().

IStreamGrabber.Start Method (Int64)#

Starts the grabbing for a maximum number of images.

Syntax#

C#

void Start(
    long maxImages
)

VB

Sub Start ( 
    maxImages As Long
)

Parameters#

maxImages: Type: System.Int64
The number of images to grab. This value must be larger than zero.

Remarks#

Grabbing is started using the OneByOne grab strategy and the ProvidedByUser grab loop method. For each grabbed image, RetrieveResult(Int32, TimeoutHandling) must be called.

The configuration event GrabStarting is fired. The notification of event handlers stops when an event call triggers an exception.
Grab-specific parameters of the camera object are locked, e.g. MaxNumBuffer.
If the camera device parameter ChunkModeActive is enabled, the chunk parsing support is initialized.
If the parameter GrabCameraEvents is enabled, the event grabbing support is initialized.
The AcquisitionStart command of the camera device is executed.
If the grabbing has been started successfully, the configuration event GrabStarted is fired. The notification of event handlers stops when an event call triggers an exception.

Preconditions:

The grabbing is stopped.

Postconditions:

The grabbing is started.
Grab-specific parameters of the camera object are locked, e.g. MaxNumBuffer.

Thread Safety:
This method is synchronized with the camera.

Error Safety:
The StreamGrabber is still valid after an error. Configuration event calls may throw exceptions. The grab implementation may throw exceptions. If the GrabStarted event call triggers an exception, the grabbing is stopped with Stop().

IStreamGrabber.Start Method (Int64, GrabStrategy, GrabLoop)#

Starts the grabbing for a maximum number of images using a specific grab strategy and a specific grab loop type.

Syntax#

C#

void Start(
    long maxImages,
    GrabStrategy strategy,
    GrabLoop grabLoopType
)

VB

Sub Start ( 
    maxImages As Long,
    strategy As GrabStrategy,
    grabLoopType As GrabLoop
)

Parameters#

maxImages: Type: System.Int64
The number of images to grab. This value must be larger than zero.
strategy: Type: Basler.Pylon.GrabStrategy
The grab strategy. For more information, see GrabStrategy.
grabLoopType: Type: Basler.Pylon.GrabLoop
If grabLoopType is set to GrabLoop::ProvidedByStreamGrabber", an additional grab loop thread is used to run the grab loop.

Remarks#

Extends the Start(GrabStrategy, GrabLoop) method call by a number of images to grab. If the given number of images has been reached, StopGrabbing is called automatically. The images are counted according to the grab strategy. Skipped images are not taken into account.

If a grab loop thread has been used in the last grab session, the grab loop thread context is joined with the context of the caller.
The configuration event GrabStarting is fired. The notification of event handlers stops when an event call triggers an exception.
Grab-specific parameters of the camera object are locked, e.g. MaxNumBuffer.
If the camera device parameter ChunkModeActive is enabled, the chunk parsing support is initialized.
If the parameter GrabCameraEvents is enabled, the event grabbing support is initialized.
The AcquisitionStart command of the camera device is executed.
If the grabbing has been started successfully, the configuration event GrabStarted is fired. The notification of event handlers stops when an event call triggers an exception.
If grabLoopType is set to ProvidedByStreamGrabber, an additional grab loop thread is started that calls RetrieveResult(Int32, TimeoutHandling) in a loop.

Preconditions:

The grabbing is stopped.

Postconditions:

The grabbing is started.
Grab-specific parameters of the camera object are locked, e.g. MaxNumBuffer.
If grabLoopType is set to ProvidedByStreamGrabber, an additional grab loop thread is started that calls RetrieveResult(Int32, TimeoutHandling) in a loop. Images are processed by registered image event handlers.

Thread Safety:This method is synchronized with the camera.

Error Safety: The StreamGrabber is still valid after an error. Configuration event calls may throw exceptions. The grab implementation may throw exceptions. If the GrabStarted event call triggers an exception, the grabbing is stopped with Stop().

IStreamGrabber.Stop Method#

Stops the grabbing of images.

Syntax#

C#

void Stop()

VB

Sub Stop

Remarks#

If the camera object not currently grabbing, nothing is done.
The configuration event GrabStopping is fired. Possible exceptions from event calls are caught and ignored. All event handlers are notified.
The AcquisitionStop command of the camera device is executed.
The grabbing is stopped.
All buffer queues are cleared.
If the grabbing has been stopped successfully, the GrabStopped configuration event is fired. Possible exceptions from event calls are caught and ignored. All event handlers are notified.

Postconditions:

The grabbing is stopped.
Grab specific parameters of the camera object are unlocked, e.g. MaxNumBuffer.

Thread Safety:
This method is synchronized with the camera.

Error Safety:
Does not throw exceptions.

IStreamGrabber.GrabOne Method#

Overload List#

	Name	Description
	GrabOne(Int32)	Grabs one image.
	GrabOne(Int32, TimeoutHandling)	Grabs one image.

IStreamGrabber.Start Method#

Overload List#

	Name	Description
	Start()	Starts the grabbing of images.
	Start(Int64)	Starts the grabbing for a maximum number of images.
	Start(GrabStrategy, GrabLoop)	Starts the grabbing of images using a specific grab strategy and a specific grab loop type.
	Start(Int64, GrabStrategy, GrabLoop)	Starts the grabbing for a maximum number of images using a specific grab strategy and a specific grab loop type.

IStreamGrabber.BufferFactory Property#

Sets an alternative buffer factory that is used for buffer allocation.

Syntax#

C#

IBufferFactory BufferFactory { get; set; }

VB

Property BufferFactory As IBufferFactory
    Get
    Set

Property Value#

Type: IBufferFactory

Remarks#

The use of this property is optional and intended for advanced use cases only. If nullptr is passed as buffer factory then the default buffer factory is used. Buffers are allocated when Start(GrabStrategy, GrabLoop) is called. A buffer factory must not be disposed while it is attached to the stream grabber object and it must not be disposed until the last buffer is freed. To free all buffers the grab needs to be stopped and all grab results must be released or destroyed.

Thread Safety:
This property is synchronized with the camera.

Error Safety:
Does not throw exceptions.

IStreamGrabber.GrabResultWaitHandle Property#

Provides access to a wait handle object indicating available grab results.

Syntax#

C#

WaitHandle GrabResultWaitHandle { get; }

VB

ReadOnly Property GrabResultWaitHandle As WaitHandle
    Get

Return Value#

Type: WaitHandle
Returns a wait handle object indicating available grab results.

Remarks#

Thread Safety:
This method is synchronized with the camera.

Error Safety:
Does not throw exceptions.

IStreamGrabber.GrabStopWaitHandle Property#

Provides access to a wait handle object indicating that the grabbing has stopped.

Syntax#

C#

WaitHandle GrabStopWaitHandle { get; }

VB

ReadOnly Property GrabStopWaitHandle As WaitHandle
    Get

Return Value#

Type: WaitHandle
Returns a wait handle object indicating that the grabbing has stopped.

Remarks#

Thread Safety:
This method is synchronized with the camera.

Error Safety:
Does not throw exceptions.

IStreamGrabber.IsGrabbing Property#

Indicates if the camera object is grabbing.

Syntax#

C#

bool IsGrabbing { get; }

VB

ReadOnly Property IsGrabbing As Boolean
    Get

Return Value#

Type: Boolean
Returns true if the camera object is still grabbing.

Remarks#

After a successful call to Start(GrabStrategy, GrabLoop), the camera object is grabbing until Stop() is called.

Thread Safety:
This method is synchronized with the camera.

Error Safety:
Does not throw exceptions.

IStreamGrabber.UserData Property#

Sets user data that is attached to each grab result of the stream whenever RetrieveResult(Int32, TimeoutHandling) is called.

Syntax#

C#

Object UserData { get; set; }

VB

Property UserData As Object
    Get
    Set

Property Value#

Type: Object

Remarks#

This is useful when handling multiple cameras.

Thread Safety:This method is synchronized with the camera.

Error Safety:Does not throw exceptions.