SnapSink Class Referencefinal
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. More...
Inheritance diagram for SnapSink:
![](common/img/classic4_snap_sink.png)
Classes
struct | Config The SnapSink configuration structure. More... |
struct | CustomAllocationStrategy Specifies a custom allocation strategy. More... |
Public Types
enum class | AllocationStrategy { Default = ic4::c_interface::IC4_SNAPSINK_ALLOCATION_STRATEGY_DEFAULT
, Custom = ic4::c_interface::IC4_SNAPSINK_ALLOCATION_STRATEGY_CUSTOM
} The buffer allocation strategy defines how many buffers are pre-allocated, when additional buffers are created, and when excess buffers are reclaimed. More... |
![]() | |
enum class | SinkMode { Run = c_interface::IC4_SINK_MODE_RUN
, Pause = c_interface::IC4_SINK_MODE_PAUSE
} Defines the possible sink modes. More... |
Public Member Functions
ImageType | outputImageType (Error &err=Error::Default()) const Queries the image type of the images the sink is configured to receive. |
std::shared_ptr< ImageBuffer > | snapSingle (std::chrono::milliseconds timeout, Error &err=Error::Default()) Grabs a single image out of the video stream received from the video capture device. |
std::shared_ptr< ImageBuffer > | snapSingle (int64_t timeout_ms, Error &err=Error::Default()) Grabs a single image out of the video stream received from the video capture device. |
std::vector< std::shared_ptr< ImageBuffer > > | snapSequence (size_t count, std::chrono::milliseconds timeout, Error &err=Error::Default()) Grabs a sequence of images out of the video stream received from the video capture device. |
std::vector< std::shared_ptr< ImageBuffer > > | snapSequence (size_t count, int64_t timeout_ms, Error &err=Error::Default()) Grabs a sequence of images out of the video stream received from the video capture device. |
SinkType | sinkType () const noexcept final Returns the type of this sink. |
![]() | |
bool | setSinkMode (SinkMode mode, Error &err=Error::Default()) noexcept Sets the sink mode for a sink. |
SinkMode | sinkMode () const noexcept Gets the current sink mode of a sink. |
bool | isAttached () const noexcept Checks whether a sink is currently attached to a Grabber as part of a data stream. |
Static Public Member Functions
static std::shared_ptr< SnapSink > | create (Error &err=Error::Default()) Creates a SnapSink using the default configuration. |
static std::shared_ptr< SnapSink > | create (const CustomAllocationStrategy &strategy, Error &err=Error::Default()) Creates a SnapSink using a customized buffer allocation strategy. |
static std::shared_ptr< SnapSink > | create (const std::shared_ptr< BufferAllocator > &allocator, Error &err=Error::Default()) Creates a SnapSink using a custom buffer allocator. |
static std::shared_ptr< SnapSink > | create (const std::vector< PixelFormat > &acceptedPixelFormats, Error &err=Error::Default()) Creates a SnapSink specifying a list of accepted image types. |
static std::shared_ptr< SnapSink > | create (PixelFormat acceptedPixelFormat, Error &err=Error::Default()) Creates a SnapSink specifying an accepted image type. |
static std::shared_ptr< SnapSink > | create (const Config &config, Error &err=Error::Default()) Creates a SnapSink using a configuration structure. |
Detailed Description
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.
To create a snap sink, call SnapSink::create().
To grab a single image out of the stream, call SnapSink::snapSingle(). To grab a sequence of images, call SnapSink::snapSequence().
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 a std::shared_ptr
. Once all std::shared_ptr
pointers are reset, they are automatically returned to the snap sink for reuse.
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 Grabber::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 BufferAllocator to the sink creation function.
Member Enumeration Documentation
◆ AllocationStrategy
|
strong |
The buffer allocation strategy defines how many buffers are pre-allocated, when additional buffers are created, and when excess buffers are reclaimed.
Enumerator | |
---|---|
Default | Use the default strategy. This strategy pre-allocates an automatically selected number of buffers depending on the requirements of the data stream and the image size. The Config::customAllocationStrategy setting is ignored. |
Custom | Custom allocation strategy. The CustomAllocationStrategy::num_buffers_allocate_on_connect, CustomAllocationStrategy::num_buffers_allocation_threshold CustomAllocationStrategy::num_buffers_free_threshold and CustomAllocationStrategy::num_buffers_max parameters determine the sink's allocation behavior. |
Member Function Documentation
◆ create() [1/6]
|
inlinestatic |
Creates a SnapSink using a configuration structure.
This generic overload allows specifying a combination of configuration options like allocation strategy, buffer allocator and accepted frame types.
- Parameters
-
[in] config A configuration structure specifying sink behavior [out] err Reference to an error handler. See Error Handling for details.
- Returns
- A
std::shared_ptr
to the new sink, ornullptr
if an error occurred.
Check the err output parameter for error code and error message.
◆ create() [2/6]
|
inlinestatic |
Creates a SnapSink using a customized buffer allocation strategy.
- Parameters
-
[in] strategy A custom buffer allocation strategy [out] err Reference to an error handler. See Error Handling for details.
- Returns
- A
std::shared_ptr
to the new sink, ornullptr
if an error occurred.
Check the err output parameter for error code and error message.
- See also
- create(const Config&, Error&)
◆ create() [3/6]
|
inlinestatic |
Creates a SnapSink using a custom buffer allocator.
- Parameters
-
[in] allocator A custom buffer allocator [out] err Reference to an error handler. See Error Handling for details.
- Returns
- A
std::shared_ptr
to the new sink, ornullptr
if an error occurred.
Check the err output parameter for error code and error message.
- See also
- create(const Config&, Error&)
◆ create() [4/6]
|
inlinestatic |
Creates a SnapSink specifying a list of accepted image types.
- Parameters
-
[in] acceptedPixelFormats A std::vector
containing the accepted pixel formats.[out] err Reference to an error handler. See Error Handling for details.
- Returns
- A
std::shared_ptr
to the new sink, ornullptr
if an error occurred.
Check the err output parameter for error code and error message.
- See also
- create(const Config&, Error&)
◆ create() [5/6]
|
inlinestatic |
Creates a SnapSink using the default configuration.
- Parameters
-
[out] err Reference to an error handler. See Error Handling for details.
- Returns
- A
std::shared_ptr
to the new sink, ornullptr
if an error occurred.
Check the err output parameter for error code and error message.
- See also
- create(const Config&, Error&)
◆ create() [6/6]
|
inlinestatic |
Creates a SnapSink specifying an accepted image type.
- Parameters
-
[in] acceptedPixelFormat The pixel format accepted by the sink. [out] err Reference to an error handler. See Error Handling for details.
- Returns
- A
std::shared_ptr
to the new sink, ornullptr
if an error occurred.
Check the err output parameter for error code and error message.
- See also
- create(const Config&, Error&)
◆ outputImageType()
|
inline |
Queries the image type of the images the sink is configured to receive.
- Parameters
-
[out] err Reference to an error handler. See Error Handling for details.
- Returns
- The image type the sink is configured for. If the function fails, the image type's pixel format is PixelFormat::Invalid. Check the err output parameter for error code and error message.
◆ sinkType()
|
inlinefinalvirtualnoexcept |
◆ snapSequence() [1/2]
|
inline |
Grabs a sequence of images out of the video stream received from the video capture device.
This function waits until count images have been grabbed, or the timeout has expired. If the timeout expires, the function returns the number of images grabber and the error value is set to ErrorCode::Timeout.
- Parameters
-
count Number of images to grab timeout_ms Time to wait for all images to arrive [out] err Reference to an error handler. See Error Handling for details.
- Returns
- A
std::vector
ofstd::shared_ptr
to image buffers.
If an error occurred, the vector's size is smaller than count.
Check the err output parameter for error code and error message.
- Precondition
- This operation is only valid while the sink is connected to a device in a data stream.
- Note
- After a successfull call, the returned
std::shared_ptr
s own the image buffers.
All pointers have to be reset to return the image buffers to the sink for reuse.
◆ snapSequence() [2/2]
|
inline |
Grabs a sequence of images out of the video stream received from the video capture device.
This function waits until count images have been grabbed, or the timeout has expired. If the timeout expires, the function returns the number of images grabber and the error value is set to ErrorCode::Timeout.
- Parameters
-
count Number of images to grab timeout Time to wait for all images to arrive [out] err Reference to an error handler. See Error Handling for details.
- Returns
- A
std::vector
ofstd::shared_ptr
to image buffers.
If an error occurred, the vector's size is smaller than count.
Check the err output parameter for error code and error message.
- Precondition
- This operation is only valid while the sink is connected to a device in a data stream.
- Note
- After a successfull call, the returned
std::shared_ptr
s own the image buffers.
All pointers have to be reset to return the image buffers to the sink for reuse.
◆ snapSingle() [1/2]
|
inline |
Grabs a single image out of the video stream received from the video capture device.
- Parameters
-
timeout_ms Time to wait for a new image to arrive [out] err Reference to an error handler. See Error Handling for details.
- Returns
- A
std::shared_ptr
to the filled image buffer, ornullptr
in case of an error.
Check the err output parameter for error code and error message.
- Precondition
- This operation is only valid while the sink is connected to a device in a data stream.
- Note
- After a successfull call, the returned
std::shared_ptr
owns the image buffer.
The pointer has to be reset to return the image buffer to the sink for reuse.
◆ snapSingle() [2/2]
|
inline |
Grabs a single image out of the video stream received from the video capture device.
- Parameters
-
timeout Time to wait for a new image to arrive [out] err Reference to an error handler. See Error Handling for details.
- Returns
- A
std::shared_ptr
to the filled image buffer, ornullptr
in case of an error.
Check the err output parameter for error code and error message.
- Precondition
- This operation is only valid while the sink is connected to a device in a data stream.
- Note
- After a successfull call, the returned
std::shared_ptr
owns the image buffer.
The pointer has to be reset to return the image buffer to the sink for reuse.