An EGrabber object encapsulates a set of related GenTL modules (an interface, a device, a data stream, a remote device, and a number of buffers). More...

#include <EGrabber.h>

Inherits EGrabberBase, and EGrabberCallbacks.

Public Member Functions
Constructor
	EGrabber (EGenTL &gentl, int interfaceIndex=0, int deviceIndex=0, int dataStreamIndex=0, gc::DEVICE_ACCESS_FLAGS deviceOpenFlags=defaultDeviceOpenFlags)
	Create an EGrabber object. More...

Buffer manipulation
BufferIndexRange	reallocBuffers (size_t bufferCount, size_t bufferSize=0)
	Reallocates the buffers. More...

BufferIndexRange	announceAndQueue (const GenTLMemory &memory, size_t bufferCount=1)
	Allocate, announce and queue a memory buffer. More...

BufferIndexRange	announceAndQueue (const UserMemory &memory)
	Announce and queue a user-allocated memory buffer. More...

BufferIndexRange	announceAndQueue (const UserMemoryArray &memory)
	Announce and queue an array of contiguous buffers using a user-allocated memory buffer. More...

BufferIndexRange	announceAndQueue (const BusMemory &memory)
	Announce and queue a user-allocated bus-memory buffer. More...

void	flushBuffers (gc::ACQ_QUEUE_TYPE operation=gc::ACQ_QUEUE_ALL_TO_INPUT)
	Move buffers from/to specific data stream buffer queues (see ACQ_QUEUE_TYPE_LIST) More...

void	resetBufferQueue ()
	Reset the buffers queues. More...

void	resetBufferQueue (const BufferIndexRange &range)
	Reset and queue a range of announced buffers. More...

void	queue (const BufferIndexRange &range)
	Queue a range of announced buffers. More...

void	revoke (const BufferIndexRange &range)
	Revoke a range of announced buffers. More...

Acquisitions
void	start (uint64_t frameCount=GENTL_INFINITE, bool controlRemoteDevice=true)
	Start acquisitions. More...

void	stop ()
	Stop acquisitions. More...

Image format
size_t	getWidth ()
	Get the width (in pixels) of images produced by the grabber. More...

size_t	getHeight ()
	Get the height (in lines) of images produced by the grabber. More...

size_t	getPayloadSize ()
	Get the payload size of images produced by the grabber. More...

std::string	getPixelFormat ()
	Get the pixel format of images produced by the grabber. More...

GenTL get info
Working with GenTL Module info commands
template<typename M , typename T >
T	getInfo (int32_t cmd)
	Getting Module information. More...

template<typename T >
T	getBufferInfo (size_t bufferIndex, gc::BUFFER_INFO_CMD cmd)
	Get information of buffer at index bufferIndex. More...

NewBufferData	getBufferData (size_t bufferIndex)
	Get handle details of buffer at index bufferIndex. More...

GenTL port access
template<typename P >
void	gcReadPortData (uint64_t address, void *data, size_t size)
	Read data from port. More...

template<typename P >
void	gcWritePortData (uint64_t address, const void *data, size_t size)
	Write data to port. More...

template<typename P >
std::vector< char >	gcReadPort (uint64_t address, size_t size)
	Read size bytes from specified port at given address. More...

template<typename P >
void	gcWritePort (uint64_t address, const std::vector< char > &data)
	Write data.size() bytes to specified port at given address. More...

template<typename P , typename V >
V	gcReadPortValue (uint64_t address)
	Read a single value from specified port at given address. More...

template<typename P , typename V >
void	gcWritePortValue (uint64_t address, V value)
	Write a single value to specified port at given address. More...

template<typename P >
std::string	gcReadPortString (int64_t address, size_t size)
	Read size bytes as null-terminated string from specified port at given address. More...

GenApi functions
Working with GenApi Port Module features
template<typename P >
int64_t	getInteger (const std::string &feature)
	Get Integer (INT64) value of specified GenApi Port Module feature. More...

template<typename P >
double	getFloat (const std::string &feature)
	Get Float (DOUBLE) value of specified GenApi Port Module feature. More...

template<typename P >
std::string	getString (const std::string &feature)
	Get String value of specified GenApi Port Module feature. More...

template<typename P >
std::vector< std::string >	getStringList (const std::string &what)
	Get list of String values returned by some query on GenApi Port Module. More...

template<typename P >
void	setInteger (const std::string &feature, int64_t value)
	Set Integer (INT64) value of specified GenApi Port Module feature. More...

template<typename P >
void	setFloat (const std::string &feature, double value)
	Set Float (DOUBLE) value of specified GenApi Port Module feature. More...

template<typename P >
void	setString (const std::string &feature, const std::string &value)
	Set String value of specified GenApi Port Module feature. More...

template<typename P >
void	execute (const std::string &command)
	Execute specified GenApi Port Module command feature. More...

void	runScript (const std::string &script)
	Run a Euresys GenApi script. More...

Memento
void	memento (const std::string &text)
	Output text to Memento. More...

void	memento (unsigned char verbosity, unsigned char kind, const std::string &text)
	Output text to Memento with specified verbosity and user kind. More...

Events
template<typename DATA >
void	enableEvent ()
	Enable event handling for the specified event. More...

template<typename DATA >
void	disableEvent ()
	Disable event handling for the specified event. More...

template<typename DATA >
void	flushEvent ()
	Flush the event queue(s) More...

NewBufferData	pop (uint64_t timeout=GENTL_INFINITE)
	Return a NewBufferData structure (to be given to ScopedBuffer or Buffer) More...

void	cancelPop ()
	Cancel a waiting pop. More...

template<typename ANYDATA >
size_t	processEvent (uint64_t timeout=GENTL_INFINITE)
	Invoke the corresponding Event Callback(s) More...

template<typename ANYDATA >
void	cancelEvent ()
	Cancel a waiting processEvent<ANYDATA> the current processEvent<ANYDATA> will abort by throwing a gentl_error (GenTL::GC_ERR_ABORT) exception. More...

Event Callbacks
The following methods are overridable callbacks. They are invoked if their corresponding events are enabled with enableEvent<DATA> events do occur Note depending on the EGrabber callback configuration (Available Callback threading models), the callbacks are invoked at different timings and from different contexts
virtual void	onNewBufferEvent (const NewBufferData &data)

virtual void	onIoToolboxEvent (const IoToolboxData &data)

virtual void	onCicEvent (const CicData &data)

virtual void	onDataStreamEvent (const DataStreamData &data)

virtual void	onCxpInterfaceEvent (const CxpInterfaceData &data)

Detailed Description

template<typename CallbackModel = CallbackOnDemand>
class Euresys::EGrabber< CallbackModel >

An EGrabber object encapsulates a set of related GenTL modules (an interface, a device, a data stream, a remote device, and a number of buffers).

An InterfaceModule: the module that represents global (shared) frame grabber settings and features. This includes digital I/O control, PCIe and firmware status...
A DeviceModule (or local device, as opposed to remote device): the module that contains the frame grabber settings and features relating to the camera. This consists mainly of camera and illumination control features: strobes, triggers...
A StreamModule: the module that handles image buffers.
A RemoteModule: the CoaXPress camera.
A number of buffers.

Constructor & Destructor Documentation

EGrabber	(	EGenTL &	gentl,
		int	interfaceIndex = `0`,
		int	deviceIndex = `0`,
		int	dataStreamIndex = `0`,
		gc::DEVICE_ACCESS_FLAGS	deviceOpenFlags = `defaultDeviceOpenFlags`
	)

Create an EGrabber object.

Template Parameters

CallbackModel the EGrabber callback configuration to use (Available Callback threading models)

Parameters

gentl	EGenTL object
interfaceIndex	index of the InterfaceModule to use
deviceIndex	index of the DeviceModule to use
dataStreamIndex	index of the StreamModule to use
deviceOpenFlags	how the device is to be opened

Member Function Documentation

BufferIndexRange reallocBuffers	(	size_t	bufferCount,
		size_t	bufferSize = `0`
	)

Reallocates the buffers.

reallocBuffers performs the following operations:

revoke current buffers (if any)
allocate bufferCount buffers (if bufferSize is zero, the size is determined automatically)
announce the new buffers to the data stream
queue the new buffers to the data stream input fifo

Note: reallocBuffers invalidates all buffer indexes

BufferIndexRange announceAndQueue	(	const GenTLMemory &	memory,
		size_t	bufferCount = `1`
	)

Allocate, announce and queue a memory buffer.

BufferIndexRange announceAndQueue ( const UserMemory & memory )

Announce and queue a user-allocated memory buffer.

BufferIndexRange announceAndQueue ( const UserMemoryArray & memory )

Announce and queue an array of contiguous buffers using a user-allocated memory buffer.

BufferIndexRange announceAndQueue ( const BusMemory & memory )

Announce and queue a user-allocated bus-memory buffer.

void flushBuffers ( gc::ACQ_QUEUE_TYPE operation = gc::ACQ_QUEUE_ALL_TO_INPUT )

Move buffers from/to specific data stream buffer queues (see ACQ_QUEUE_TYPE_LIST)

void resetBufferQueue ( )

Reset the buffers queues.

resetBufferQueue performs the following operations:

discard pending buffers (if any)
queue all buffers to the data stream input fifo, in the initial order (i.e., the order in which they were announced with reallocBuffers or announceBuffer)

Note: the data stream must be idle when calling this function

void resetBufferQueue ( const BufferIndexRange & range )

Reset and queue a range of announced buffers.

resetBufferQueue performs the following operations:

discard pending buffers (if any)
queue the buffers of the given range to the data stream input fifo
Parameters

range range of announced buffers (returned by reallocBuffers or announceAndQueue)

Note
the data stream must be idle when calling this function

void queue ( const BufferIndexRange & range )

Queue a range of announced buffers.

queue a range of announced buffers

Parameters

range range of announced buffers (returned by reallocBuffers or announceAndQueue)

void revoke ( const BufferIndexRange & range )

Revoke a range of announced buffers.

Note: revoke does not invalidate other buffer indexes

void start	(	uint64_t	frameCount = `GENTL_INFINITE`,
		bool	controlRemoteDevice = `true`
	)

Start acquisitions.

Parameters

frameCount	the number of buffers to fill
controlRemoteDevice	defines whether or not to start and stop the remote device by automatically executing AcquisitionStart and AcquisitionStop commands

start performs the following operations:

if controlRemoteDevice is true, start the remote device by executing AcquisitionStart
start the data stream for frameCount buffers

Note: the data stream must be idle when calling this function; when frameCount buffers have been filled, the data stream automatically goes idle, but the remote device is not stopped; if controlRemoteDevice is true, AcquisitionStop will be exectuted in a subsequent call to stop (or in the EGrabber destructor)

void stop ( )

Stop acquisitions.

stop performs the following operations:

stop the data stream
stop the remote device

Note: this function will block until the data stream is idle

size_t getWidth ( )

Get the width (in pixels) of images produced by the grabber.

size_t getHeight ( )

Get the height (in lines) of images produced by the grabber.

Note: for line-scan cameras, the height is determined by the data stream feature "BufferHeight"

size_t getPayloadSize ( )

Get the payload size of images produced by the grabber.

std::string getPixelFormat ( )

Get the pixel format of images produced by the grabber.

Note: both the camera and the data stream influence this

T getInfo ( int32_t cmd )

Getting Module information.

Template Parameters

M	Module to query (Available GenTL/Port Modules)
T	The C++ type corresponding to the type (GenTL::INFO_DATATYPE_LIST) of data to get

Parameters

cmd

the info command to get, available values depend on the module M

if M is SystemModule: cmd values belong to GenTL::TL_INFO_CMD_LIST
if M is InterfaceModule: cmd values belong to GenTL::INTERFACE_INFO_CMD_LIST
if M is DeviceModule: cmd values belong to GenTL::DEVICE_INFO_CMD_LIST
if M is StreamModule: cmd values belong to GenTL::STREAM_INFO_CMD_LIST

Note: the template parameter M cannot be set to RemoteModule because the GenTL standard does not expose module information about the remote device

T getBufferInfo	(	size_t	bufferIndex,
		gc::BUFFER_INFO_CMD	cmd
	)

Get information of buffer at index bufferIndex.

Template Parameters

T	The C++ type corresponding to the type (GenTL::INFO_DATATYPE_LIST) of data to get

Parameters

bufferIndex	the index of the buffer to query (see BufferIndexRange)
cmd	cmd values belong to either GenTL::BUFFER_INFO_CMD_LIST or GenTL::EuresysCustomGenTL::BUFFER_INFO_CUSTOM_CMD_LIST

NewBufferData getBufferData ( size_t bufferIndex )

Get handle details of buffer at index bufferIndex.

Parameters

bufferIndex the index of the buffer to query (see BufferIndexRange)

void gcReadPortData	(	uint64_t	address,
		void *	data,
		size_t	size
	)

Read data from port.

Template Parameters

P	Port Module to use (Available GenTL/Port Modules)

Parameters

address	byte address to read from
data	output buffer
size	number of bytes to read

void gcWritePortData	(	uint64_t	address,
		const void *	data,
		size_t	size
	)

Write data to port.

Template Parameters

P	Port Module to use (Available GenTL/Port Modules)

Parameters

address	byte address to write to
data	input buffer containing the data to write
size	number of bytes to write

std::vector<char> gcReadPort	(	uint64_t	address,
		size_t	size
	)

Read size bytes from specified port at given address.

Template Parameters

P	Port Module to use (Available GenTL/Port Modules)

Parameters

address	byte address to read from
size	number of bytes to read

void gcWritePort	(	uint64_t	address,
		const std::vector< char > &	data
	)

Write data.size() bytes to specified port at given address.

Template Parameters

P	Port Module to use (Available GenTL/Port Modules)

Parameters

address	byte address to write to
data	input buffer containing the data to write

V gcReadPortValue ( uint64_t address )

Read a single value from specified port at given address.

Template Parameters

P	Port Module to use (Available GenTL/Port Modules)
V	The C++ type corresponding to the value to read

Parameters

address byte address to read from

void gcWritePortValue	(	uint64_t	address,
		V	value
	)

Write a single value to specified port at given address.

Template Parameters

P	Port Module to use (Available GenTL/Port Modules)
V	The C++ type corresponding to the value to write

Parameters

address	byte address to write to
value	value to write as a sequence of bytes

std::string gcReadPortString	(	int64_t	address,
		size_t	size
	)

Read size bytes as null-terminated string from specified port at given address.

Template Parameters

P	Port Module to use (Available GenTL/Port Modules)

Parameters

address	byte address to read from
size	number of bytes to read

Note: any trailing null character will be trimmed

int64_t getInteger ( const std::string & feature )

Get Integer (INT64) value of specified GenApi Port Module feature.

Template Parameters

P	GenApi Port Module to use (Available GenTL/Port Modules)

Parameters

feature name of feature to read (EGenTL::genapiGetInteger)

double getFloat ( const std::string & feature )

Get Float (DOUBLE) value of specified GenApi Port Module feature.

Template Parameters

P	GenApi Port Module to use (Available GenTL/Port Modules)

Parameters

feature name of feature to read (EGenTL::genapiGetFloat)

std::string getString ( const std::string & feature )

Get String value of specified GenApi Port Module feature.

Template Parameters

P	GenApi Port Module to use (Available GenTL/Port Modules)

Parameters

feature name of feature to read (EGenTL::genapiGetString)

std::vector<std::string> getStringList ( const std::string & what )

Get list of String values returned by some query on GenApi Port Module.

Template Parameters

P	GenApi Port Module to use (Available GenTL/Port Modules)

Parameters

what	Euresys specific query to perform, such queries are built using the helpers from Euresys::query

void setInteger	(	const std::string &	feature,
		int64_t	value
	)

Set Integer (INT64) value of specified GenApi Port Module feature.

Template Parameters

P	GenApi Port Module to use (Available GenTL/Port Modules)

Parameters

feature	name of feature to modify (EGenTL::genapiSetInteger)
value	value to write

void setFloat	(	const std::string &	feature,
		double	value
	)

Set Float (DOUBLE) value of specified GenApi Port Module feature.

Template Parameters

P	GenApi Port Module to use (Available GenTL/Port Modules)

Parameters

feature	name of feature to modify (EGenTL::genapiSetFloat)
value	value to write

void setString	(	const std::string &	feature,
		const std::string &	value
	)

Set String value of specified GenApi Port Module feature.

Template Parameters

P	GenApi Port Module to use (Available GenTL/Port Modules)

Parameters

feature	name of feature to modify (EGenTL::genapiSetString) or Euresys specific action to perform, such actions are built using the helpers from Euresys::action
value	value to write (or parameter of the action to perform)

void execute ( const std::string & command )

Execute specified GenApi Port Module command feature.

Template Parameters

P	GenApi Port Module to use (Available GenTL/Port Modules)

Parameters

command name of feature to execute (EGenTL::genapiExecuteCommand)

void runScript ( const std::string & script )

Run a Euresys GenApi script.

Parameters

script Euresys GenApi script to run, this can be either a location (path) or some actual script statements (EGenTL::genapiRunScript)

void memento ( const std::string & text )

Output text to Memento.

Note: text is inserted into the stream of Memento traces under the Kind "User0" with the verbosity MEMENTO_VERBOSITY_INFO

void memento	(	unsigned char	verbosity,
		unsigned char	kind,
		const std::string &	text
	)

Output text to Memento with specified verbosity and user kind.

Parameters

verbosity	MEMENTO_VERBOSITY_CRITICAL MEMENTO_VERBOSITY_ERROR MEMENTO_VERBOSITY_WARNING MEMENTO_VERBOSITY_NOTICE MEMENTO_VERBOSITY_INFO MEMENTO_VERBOSITY_DEBUG MEMENTO_VERBOSITY_VERBOSE
kind	user kind identifier, from 0 to 15 0 to output trace under the Kind "User0" 1 to output trace under the Kind "User1" ... 10 (0xA) to output trace under the Kind "UserA" 11 (0xB) to output trace under the Kind "UserB" 12 (0xC) to output trace under the Kind "UserC" 13 (0xD) to output trace under the Kind "UserD" 14 (0xE) to output trace under the Kind "UserE" 15 (0xF) to output trace under the Kind "UserF"
text	string to output

void enableEvent ( )

Enable event handling for the specified event.

Template Parameters

DATA	the event(s) to enable (Available Event DATA types to enable)

Note: by default NewBufferData is enabled; under the hood, this method registers the corresponding GenTL event(s) to the system.

void disableEvent ( )

Disable event handling for the specified event.

Template Parameters

DATA	the event(s) to disable (Available Event DATA types to enable)

Note: under the hood, this method unregisters the corresponding GenTL event(s) from the system.

void flushEvent ( )

Flush the event queue(s)

Template Parameters

DATA	the event(s) to flush (Available Event DATA types to enable)

NewBufferData pop ( uint64_t timeout = GENTL_INFINITE )

Return a NewBufferData structure (to be given to ScopedBuffer or Buffer)

Parameters

timeout timeout in milliseconds

Precondition: only available on EGrabber configuration CallbackOnDemand; NewBufferData event is enabled (this is the default); EGrabber is not already waiting for NewBufferData event in another thread

Note: only the most important exceptions are listed below

Exceptions

gentl_error	GenTL::GC_ERR_ABORT when cancelPop
gentl_error	GenTL::GC_ERR_INVALID_HANDLE when NewBufferData event is disabled
gentl_error	GenTL::GC_ERR_TIMEOUT when pop times out before an event occurs
client_error	with message "EGrabber is busy in another thread" if EGrabber is already waiting for NewBufferData event in another thread with either pop or processEvent
client_error	with message "EGrabber has no registered event for this filter" if NewBufferData event is not enabled

void cancelPop ( )

Cancel a waiting pop.

Note: any waiting pop will be aborted by throwing a gentl_error (GenTL::GC_ERR_ABORT) exception; cancelPop is equivalent to cancelEvent<NewBufferData>

size_t processEvent ( uint64_t timeout = GENTL_INFINITE )

Invoke the corresponding Event Callback(s)

Precondition: events are enabled (enableEvent<DATA>); events are available

Template Parameters

ANYDATA the set of events to process (Available Event DATA types to process)

Returns: the number of pending events when the callback returned

Precondition: only available with EGrabber configuration CallbackOnDemand; EGrabber is not already waiting for one of ANYDATA event in another thread

Note: only the most important exceptions are listed below

Exceptions

gentl_error	GenTL::GC_ERR_ABORT when cancelEvent
gentl_error	GenTL::GC_ERR_INVALID_HANDLE when corresponding event is disabled
gentl_error	GenTL::GC_ERR_TIMEOUT when processEvent times out before an event occurs
client_error	with message "EGrabber is busy in another thread" if EGrabber is already waiting for one of ANYDATA event in another thread with pop or processEvent
client_error	with message "EGrabber has no registered event for this filter" if none of ANYDATA event is enabled