Class SnapSink
The snap sink is a sink implementation that allows a program to capture single images or sequences of images on demand, while still having a display showing all images.
Implements
Inherited Members
Namespace: ic4
Assembly: ic4dotnet.dll
Syntax
public class SnapSink : Sink, IDisposableRemarks
To create a snap sink, use SnapSink(IEnumerable<PixelFormat>, SnapSinkAllocationStrategy, IBufferAllocator).
Pass the sink to StreamSetup(Sink, IDisplay, StreamSetupOption) or StreamSetup(Sink, StreamSetupOption) to feed images into the sink.
To grab a single image out of the stream, call SnapSingle(TimeSpan). To grab a sequence of images, call SnapSequence(int, TimeSpan).
The snap sink manages the buffers used for background image aquisition as well as for the grabbed images. During stream setup, a number of buffers is allocated depending on the configured allocation strategy. Additional buffers can be automatically created on demand, if the allocation strategy allows. Likewise, if there is a surplus of unused image buffers, unused buffers are reclaimed and released automatically.
Image buffers that were returned by one of the snap functions are owned by their respective caller through the reference to the ImageBuffer. To return the image buffer to the sink for reuse, call Dispose() on the image buffer.
Please note that if there are no buffers available in the sink when the device tries to deliver a frame, the frame will be dropped. Use StreamStatistics to find out whether a buffer underrun occurred.
By default, the sink uses buffers provided by the device driver or the implicitly created transformation filter. It is possible to use program-defined buffers be used by providing a IBufferAllocator to the sink constructor.
Constructors
SnapSink(IEnumerable<PixelFormat>, SnapSinkAllocationStrategy, IBufferAllocator)
Creates a new snap sink.
Declaration
public SnapSink(IEnumerable<PixelFormat> acceptedPixelFormats = null, SnapSinkAllocationStrategy strategy = null, IBufferAllocator customAllocator = null)Parameters
| Type | Name | Description |
|---|---|---|
| IEnumerable<PixelFormat> | acceptedPixelFormats | An optional list of pixel formats that restrict the input to this sink. This can be used to force an automatic conversion from the device's pixel format to a pixel format usable by the sink. |
| SnapSinkAllocationStrategy | strategy | An optional buffer allocation strategy for the sink.
If this is |
| IBufferAllocator | customAllocator | An optional custom buffer allocator |
Exceptions
| Type | Condition |
|---|---|
| ArgumentException | The buffer allocation strategy is invalid. |
| IC4Exception | Check ErrorCode and ToString() for details. |
SnapSink(PixelFormat, SnapSinkAllocationStrategy, IBufferAllocator)
Creates a new snap sink.
Declaration
public SnapSink(PixelFormat acceptedPixelFormat, SnapSinkAllocationStrategy strategy = null, IBufferAllocator customAllocator = null)Parameters
| Type | Name | Description |
|---|---|---|
| PixelFormat | acceptedPixelFormat | A pixel format that restricts the input to this sink. This can be used to force an automatic conversion from the device's pixel format to a pixel format usable by the sink. |
| SnapSinkAllocationStrategy | strategy | An optional buffer allocation strategy for the sink.
If this is |
| IBufferAllocator | customAllocator | An optional custom buffer allocator |
Exceptions
| Type | Condition |
|---|---|
| ArgumentException | The buffer allocation strategy is invalid. |
| IC4Exception | Check ErrorCode and ToString() for details. |
Properties
OutputImageType
The image type of the images the sink is configured to receive
Declaration
public ImageType OutputImageType { get; }Property Value
| Type | Description |
|---|---|
| ImageType | The image type of the images the sink is configured to receive |
Exceptions
| Type | Condition |
|---|---|
| IC4Exception | Check ErrorCode and ToString() for details. |
Type
The type of the sink.
For snap sinks, this always is SnapSink.
Declaration
public override SinkType Type { get; }Property Value
| Type | Description |
|---|---|
| SinkType | The type of the sink. |
Overrides
Methods
SnapSequence(int, TimeSpan)
Grabs a sequence of images out of the video stream received from the video capture device.
Declaration
public IReadOnlyList<ImageBuffer> SnapSequence(int count, TimeSpan timeout)Parameters
| Type | Name | Description |
|---|---|---|
| int | count | Number of images to grab |
| TimeSpan | timeout | Time to wait for all images to arrive |
Returns
| Type | Description |
|---|---|
| IReadOnlyList<ImageBuffer> | The list of grabbed images. If the timeout expires, the returned list contains the images grabbed until then. |
Remarks
This operation is only valid while the sink is connected to a device in a data stream.
After a successfull call, the program owns the image buffers through the ImageBuffer references. The image buffer objects must be disposed to put the image buffer into the sink's free queue for later reuse.
If the image buffer objects are not disposed, their finalizer will also return the image buffers to the sink. However, it is recommended to always manually dispose the image buffers for deterministic behavior.
Exceptions
| Type | Condition |
|---|---|
| TimeoutException | No images were received before the timeout elapsed. |
| IC4Exception | Check ErrorCode and ToString() for details. |
SnapSingle(TimeSpan)
Grabs a single image out of the video stream received from the video capture device.
Declaration
public ImageBuffer SnapSingle(TimeSpan timeout)Parameters
| Type | Name | Description |
|---|---|---|
| TimeSpan | timeout | Time to wait for a new image to arrive |
Returns
| Type | Description |
|---|---|
| ImageBuffer | A filled image buffer |
Remarks
This operation is only valid while the sink is connected to a device in a data stream.
After a successfull call, the program owns the image buffer through the ImageBuffer reference. The image buffer object must be disposed to put the image buffer into the sink's free queue for later reuse.
If the image buffer object is not disposed, their finalizer will also return the image buffer to the sink. However, it is recommended to always manually dispose the image buffer for deterministic behavior.
Exceptions
| Type | Condition |
|---|---|
| TimeoutException | No image was received before the timeout elapsed. |
| IC4Exception | Check ErrorCode and ToString() for details. |
TrySnapSingle(out ImageBuffer, TimeSpan)
Tries to grab a single image out of the video stream received from the video capture device.
In contrast to SnapSingle(TimeSpan), this function does not throw an exception in case of an error.
Declaration
public bool TrySnapSingle(out ImageBuffer buffer, TimeSpan timeout)Parameters
| Type | Name | Description |
|---|---|---|
| ImageBuffer | buffer | Output parameter receiving the grabber image buffer |
| TimeSpan | timeout | Time to wait for a new image to arrive |
Returns
| Type | Description |
|---|---|
| bool |
|
Remarks
This operation is only valid while the sink is connected to a device in a data stream.
After a successfull call, the program owns the image buffer through the ImageBuffer reference. The image buffer object must be disposed to put the image buffer into the sink's free queue for later reuse.
If the image buffer object is not disposed, their finalizer will also return the image buffer to the sink. However, it is recommended to always manually dispose the image buffer for deterministic behavior.