Interface to SAL3D Frame Grabber Drivers. More...

#include <FrameGrabber.hpp>

Inheritance diagram for sal3d::FrameGrabber:

Public Member Functions
	FrameGrabber (const std::string &fileName, const std::string &param)
	Constructor. Creates a frame grabber with the specified driver and parameters.
	FrameGrabber (const std::string &fileName)
	Constructor. Creates a frame grabber with the specified driver.
	FrameGrabber (const FrameGrabber &grabber)
	Copy constructor.
virtual	~FrameGrabber ()
	Destructor.
virtual Frame	frame ()
	Gets the next frame in the queue of grabbed frames.
virtual void	freeze ()
	Stops grabbing frames.
virtual void	grab ()
	Starts capturing continuous frames from the device.
virtual int	lostCount ()
	Get the number of lost frames since the last grab() was started.
FrameGrabber &	operator= (const FrameGrabber &rhs)
	Copy assignment operator.
virtual void	reconfig (const std::string &param)
void	setSize (int width, int height)
	Sets the capture window size for this frame grabber.
virtual void	wait (int timeout=-1)
	Waits for a frame to be available in the grabbed queue.
Protected Member Functions
void *	getDriverData ()
	Gets the internal driver data pointer.
void *	getFunctionPointer (const std::string &name)
	Gets the pointer to a user function of the FGD.

Detailed Description

Interface to SAL3D Frame Grabber Drivers.

This class requires linking with acquire.lib (import library for acquire.dll).

Frame grabber devices allow getting pictures from 2D cameras. Each Frame grabber vendor provides his own libraries for accessing the pictures grabbed, but that can slow down the development of any 3D processing application.

If the user is coding with the SAL3D SDK, he will be interested in grabbing pictures in Frame form for further 3D processing. In order to develope faster a final solution, SAL3D provides some Frame grabber drivers which use the vendors' libraries, unifying the use of those drivers through this FrameGrabber interface. You can see the provided drivers in SAL3D in Frame Grabber & Camera Drivers.

The FrameGrabber constructor asks for a driver filename (with extension fgd, Frame Grabber Driver). After a successful driver load, the resulting FrameGrabber object can be used to start grabbing (grab()), get acquired pictures (wait(), frame()), and stop grabbing (freeze()).

The simple FrameGrabber interface doesn't allow getting particular information from a particular frame grabber model, and the method of configuring the frame grabber acquisition is hardcoded in the driver itself (for example asking for a file configuration through a Windows dialog). If the SAL3D user wants more control over the frame grabber, he can use the driver's source code provided with SAL3D as a starting point to roll their own driver, or he may even choose not to use the FrameGrabber interface at all, grabbing with the frame grabber vendor libraries directly. Using the rest of SAL3D library this way only requires to provide the grabbed pictures wrapped in Frame objects.

The FrameGrabber copy constructor doesn't copy the internal driver structures. Instead, it maintains a reference counter, and destroys the FrameGrabber internal Driver structures (calling release(...), as seen below) only when the last copy of a FrameGrabber original object is destroyed.

Constructor & Destructor Documentation

sal3d::FrameGrabber::FrameGrabber	(	const std::string &	fileName,
		const std::string &	param
	)		`[inline, explicit]`

Constructor. Creates a frame grabber with the specified driver and parameters.

Loads a Frame Grabber Driver with the provided parameters and provides a FrameGrabber object to interface with it.

Parameters:

[in]	fileName	The file name of the Driver to load.
[in]	param	String with parameters for the driver. The options for each driver are detailed in Frame Grabber & Camera Drivers.

Exceptions:

sal3d::Error On error

sal3d::FrameGrabber::FrameGrabber ( const std::string & fileName ) [inline, explicit]

Constructor. Creates a frame grabber with the specified driver.

Loads a Frame Grabber Driver with the default parameters and provides a FrameGrabber object to interface with it. It's equivalent to FrameGrabber(fileName, "").

Parameters:

[in] fileName The file name of the Driver to load.

Exceptions:

sal3d::Error On error

sal3d::FrameGrabber::FrameGrabber ( const FrameGrabber & grabber ) [inline]

Copy constructor.

Parameters:

[in] grabber The frame grabber to copy from.

Member Function Documentation

virtual Frame sal3d::FrameGrabber::frame ( ) [inline, virtual]

Gets the next frame in the queue of grabbed frames.

Each driver holds internally a buffer of captured frames. With this function one can retrieve the first that was captured.

Warning:: Notice that this function is blocking, i.e., if there are no captured frames ready, it will wait until one is available. To avoid this, one can use the wait() function, which waits until a frame is ready or until an established timeout has passed.

Returns:: The oldest captured frame in the queue.

virtual void sal3d::FrameGrabber::freeze ( ) [inline, virtual]

Stops grabbing frames.

If no capture was started by calling grab(), then this function does nothing.

void* sal3d::FrameGrabber::getDriverData ( ) [inline, protected]

Gets the internal driver data pointer.

The user can write his own frame grabber driver files (FGD), which have the shape of DLLs. Those DLLs should include the minimum functions required by the sal3d::FrameGrabber API, but these can include additional functions.

For all the functions in an FGD to be able to distinguish the instance of sal3d::FrameGrabber in a process, their init() function should return a void pointer that will be passed to all other functions in the fgd, included those of the user. We name that void pointer the driver data.

This method allows retrieving the driver data void pointer.

For an FGD that has an additional function like "trigger_camera", the user can inherit sal3d::FrameGrabber and use this method to pass the driver data to that function:

 class MyFrameGrabber : public sal3d::FrameGrabber
 {
     public:
         MyFrameGrabber(const std::string &fileName, const std::string &param):
             FrameGrabber(fileName, param)
         {
             _driverData = getDriverData();
             _trigger_camera = reinterpret_cast<trigger_camera_t>(
                 getFunctionPointer("trigger_camera"));
         }

         int
         triggerCamera(int pulse_length)
         {
             return _trigger_camera(_driverData, pulse_length);
         }

     private:
         typedef int (cdecl *trigger_camera_t) (void *, int);
         trigger_camera_t _trigger_camera;
         void *_driverData;
 };

void* sal3d::FrameGrabber::getFunctionPointer ( const std::string & name ) [inline, protected]

Gets the pointer to a user function of the FGD.

As the user can include any function in a FGD driver file, this method allows getting a pointer to one of them. For an example of use of this function, check the documentation of getDriverData()

Referenced by sal3d::TOFFrameGrabber::TOFFrameGrabber().

virtual void sal3d::FrameGrabber::grab ( ) [inline, virtual]

Starts capturing continuous frames from the device.

This function puts the frame grabber in continuous grab. Once this function is called, the frame grabber will start grabbing frames from the device and putting them in the proper buffer.

If the grabbing has already been started, then this function does nothing.

Exceptions:

sal3d::Error On error

virtual int sal3d::FrameGrabber::lostCount ( ) [inline, virtual]

Get the number of lost frames since the last grab() was started.

Returns:: The number of lost frames.

Exceptions:

sal3d::Error On error

FrameGrabber& sal3d::FrameGrabber::operator= ( const FrameGrabber & rhs ) [inline]

Copy assignment operator.

Parameters:

[in] rhs The frame grabber to copy to this object.

Returns:: A reference to this object.

Exceptions:

sal3d::Error On error

void sal3d::FrameGrabber::setSize	(	int	width,
		int	height
	)		`[inline]`

Sets the capture window size for this frame grabber.

This function will try to set the capture window size to the specified values. As some frame grabbers require the width to be a multiple of 4 or 16, the width might be padded to comply with these requirements. The final window size programmed in the frame grabber can be checked when grabbing a new frame.

This function should NOT be called while grabbing frames, because it may imply reallocating the frame grabber memory buffers according to the new capture window size.

Parameters:

[in]	width	Minimum width of the capture window in pixels.
[in]	height	Minimum height of the capture window in pixels.

Exceptions:

sal3d::Error On error

virtual void sal3d::FrameGrabber::wait ( int timeout = -1 ) [inline, virtual]

Waits for a frame to be available in the grabbed queue.

This function can be used as a non-blocking way to wait for a frame to be available. Contrary to the frame() method, this one does not return a frame, but only waits for one to be ready. One has to call frame() afterwards to get the acquired frame. Moreover, a timeout can be passed as a parameter specifying how long it should wait for a frame before signaling an exception.

You must call this function after grab() and before freeze(), otherwise it will fail.

Parameters:

timeout The maximum time, in milliseconds, to wait for the next frame. If this parameter is 0<, then the timeout is not used, i.e., the function is blocked until a frame is ready.

Exceptions:

sal3d::Timeout	if the operation timed out.
sal3d::Error	On error

The documentation for this class was generated from the following file:

FrameGrabber.hpp

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation