FirePackage - intek

FirePackage©
Documentation FireGrab
V2.4.2
Oct 10, 2011
intek hard-&softwaretechnik
Adelungstr. 34
64283 Darmstadt
Distributed by:
intek hard- & softwaretechnik
adelungstr. 34
64283 darmstadt
Distributed by:
Contents
Contents...................................................................................................................................... 2
Introduction .................................................................................................................................. 5
Document history ....................................................................................................................... 5
What is FireGrab? ...................................................................................................................... 5
How to grab an image – the fastest way to success ............................................................................... 6
Basic structure of FireGrab .............................................................................................................. 8
Image transfer from camera to system memory .................................................................................. 10
Safety first - isochronous transfer error checking................................................................................. 12
Direct Memory Access (DMA) modes in detail .................................................................................... 13
DMA - Continuous Mode ............................................................................................................ 13
DMA - Replace Mode ................................................................................................................ 14
DMA - Limp Mode .................................................................................................................... 14
Basic variable types used in FireGrab .............................................................................................. 15
Debug utilities (LogUtil.dll) ............................................................................................................. 16
C-Style functions used in FireGrab .................................................................................................. 17
FGInitModule .......................................................................................................................... 18
Callback Function ................................................................................................................................ 19
FGExitModule ......................................................................................................................... 21
FGGetNodeList........................................................................................................................ 22
FGGetHostLicenseRequest ........................................................................................................ 24
FGGetLicenseInfo .................................................................................................................... 25
The class CFGCamera ................................................................................................................. 26
CFGCamera::Connect ............................................................................................................... 28
CFGCamera::Disconnect ........................................................................................................... 29
CFGCamera::SetParameter........................................................................................................ 30
CFGCamera::GetParameter ....................................................................................................... 31
CFGCamera::GetParameterInfo .................................................................................................. 32
CFGCamera::StartDevice .......................................................................................................... 35
CFGCamera::StopDevice ........................................................................................................... 36
CFGCamera::GetDeviceName .................................................................................................... 37
CFGCamera::GetContext ........................................................................................................... 38
CFGCamera::GetPtrDCam ......................................................................................................... 39
CFGCamera::WriteRegister ........................................................................................................ 40
CFGCamera::ReadRegister ........................................................................................................ 41
CFGCamera::WriteBlock ............................................................................................................ 42
CFGCamera::ReadBlock ........................................................................................................... 43
CFGCamera::GetLicenseRequest ................................................................................................ 44
CFGCamera::OpenCapture ........................................................................................................ 45
CFGCamera::CloseCapture ........................................................................................................ 46
CFGCamera::GetFrame ............................................................................................................ 47
CFGCamera::PutFrame ............................................................................................................. 49
CFGCamera::DiscardFrames ...................................................................................................... 51
CFGCamera::AssignUserBuffers ................................................................................................. 52
The class CBroadcast .................................................................................................................. 54
The class CFGIsoDma.................................................................................................................. 55
CFGIsoDma::OpenCapture ........................................................................................................ 56
CFGIsoDma::CloseCapture ........................................................................................................ 58
CFGIsoDma::GetFrame ............................................................................................................. 59
CFGIsoDma::PutFrame ............................................................................................................. 61
CFGIsoDma::DiscardFrames ...................................................................................................... 63
FirePackage© - Documentation FireGrab
Page 2
Distributed by:
CFGIsoDma::AssignUserBuffers .................................................................................................. 64
Parameter indices for Set/GetParameter ....................................................................................... 65
FGP_IMAGEFORMAT .............................................................................................................. 65
General image format ........................................................................................................................... 65
DCAM specification conform image format ................................................................................................ 67
FGP_ENUMIMAGEFORMAT ...................................................................................................... 68
FGP_BRIGHTNESS ................................................................................................................. 69
FGP_AUTOEXPOSURE ............................................................................................................ 70
FGP_SHARPNESS .................................................................................................................. 71
FGP_WHITEBALCB ................................................................................................................. 72
FGP_WHITEBALCR ................................................................................................................. 73
FGP_HUE .............................................................................................................................. 74
FGP_SATURATION ................................................................................................................. 75
FGP_GAMMA ......................................................................................................................... 76
FGP_SHUTTER ...................................................................................................................... 77
FGP_GAIN ............................................................................................................................. 78
FGP_IRIS ............................................................................................................................... 79
FGP_FOCUS .......................................................................................................................... 80
FGP_TEMPERATURE .............................................................................................................. 81
FGP_TRIGGER ....................................................................................................................... 82
FGP_TRIGGERDLY ................................................................................................................. 84
FGP_WHITESHD ..................................................................................................................... 85
FGP_FRAMERATE .................................................................................................................. 86
FGP_ZOOM............................................................................................................................ 87
FGP_PAN .............................................................................................................................. 88
FGP_TILT .............................................................................................................................. 89
FGP_OPTICALFILTER .............................................................................................................. 90
FGP_CAPTURESIZE ................................................................................................................ 91
FGP_CAPTUREQUALITY .......................................................................................................... 92
FGP_PHYSPEED .................................................................................................................... 93
FGP_XSIZE ............................................................................................................................ 94
FGP_YSIZE ............................................................................................................................ 95
FGP_XPOSITION .................................................................................................................... 96
FGP_YPOSITION .................................................................................................................... 97
FGP_PACKETSIZE .................................................................................................................. 98
FGP_DMAMODE ................................................................................................................... 100
FGP_BURSTCOUNT .............................................................................................................. 101
FGP_FRAMEBUFFERCOUNT .................................................................................................. 102
FGP_USEIRMFORBW ............................................................................................................ 103
FGP_ADJUSTPARAMETERS................................................................................................... 104
FGP_STARTIMMEDIATELY ..................................................................................................... 105
FGP_FRAMEMEMORYSIZE .................................................................................................... 106
FGP_COLORFORMAT ........................................................................................................... 107
FGP_IRMFREEBW ................................................................................................................ 108
FGP_DO_FASTTRIGGER ....................................................................................................... 109
FGP_DO_BUSTRIGGER ......................................................................................................... 110
FGP_RESIZE ........................................................................................................................ 111
FGP_USEIRMFORCHN .......................................................................................................... 112
FGP_CAMACCEPTDELAY ...................................................................................................... 113
FGP_ISOCHANNEL ............................................................................................................... 114
FGP_CYCLETIME ................................................................................................................. 115
FGP_DORESET .................................................................................................................... 116
FGP_DMAFLAGS .................................................................................................................. 117
FirePackage© - Documentation FireGrab
Page 3
Distributed by:
FGP_R0C ............................................................................................................................ 118
FGP_BUSADDRESS .............................................................................................................. 119
FGP_CMDTIMEOUT .............................................................................................................. 120
FGP_CARD .......................................................................................................................... 121
FGP_LICENSEINFO ............................................................................................................... 122
FGP_PACKETCOUNT ............................................................................................................ 123
FGP_DO_MULTIBUSTRIGGER ................................................................................................ 124
FGP_CARDRESET ................................................................................................................ 125
Error codes returned by functions .................................................................................................. 126
HALER_xxx codes ................................................................................................................. 126
FCE_xxx codes ..................................................................................................................... 127
Error flags in global error field ....................................................................................................... 128
HALERF_xxx ........................................................................................................................ 128
How licensing works ................................................................................................................... 130
Examples ............................................................................................................................. 130
FirePackage© - Documentation FireGrab
Page 4
Distributed by:
Introduction
Document history
Version
Date
Remarks
V2.0.0
01.08.2007
Reworked by native speaker
V2.0.1
23.11.2007
Style changes, various code snippet corrections
V2.1.0
28.02.2008
Additional features from FirePackage 2.25
V2.1.1
18.03.2008
Minor corrections
V2.2.0
29.09.2008
FGP_DO_CARDTRIGGER introduced
V2.3.0
03.09.2009
FGP_CARDRESET introduced, minor corrections
V2.4.0
17.11.2009
FGP_CARDRESET functionality extended
FGGetNodeList extended to enumerate cards
New DMA flags described
V2.4.1
21.4.2010
Ring0 Callgate description corrected
V2.4.2
10.10.2011
Minor changes
What is FireGrab?
Based on the already well-known and robust existing FirePackageTM FireGrab is a completely redesigned API (application programming interface) with a completely different approach: KEEP IT SIMPLE!
FireStack still is part of FirePackage and FireGrab just enhances the already existing interface.
When the FireStack API was created the main approach was to make all functions of the 1394 bus
public to an application. This lead to a very powerful programming tool but was too complex in many
cases for image processing programmers whose primary task was and is to handle and analyze images.
Only a small community really felt comfortable with handling Firewire bus resets, looking into register
tables of the DCAM specification and many other tricky tasks like that. Most of them did their job but
were happy when they got the first images and forgot all about Firewire.
What we learned from our customers during recent years: Many of our customers designed their own
wrapper around the basic FireStack functions – like inventing the wheel again and again.
So we tried to learn as much as we could from support and feedback and encapsulated all Firewire
specifics behind a C++ object that does all the work for you. The result is something that looks more
like a frame grabber interface than a Firewire camera API. Can you imagine: With only four lines of
code you can acquire images from a Firewire camera without learning the DCAM registers, without
handling threads or difficult programming structures.
So enjoy image processing with all the advantages of modern FireWire cameras without getting into
about the details of a complex API.
For all the users of FireStack: The traditional FireStack interface still exists and will be supported for
some years. Nothing will be changed and users can rely on the compatibility.
We hope that you enjoy the new features and the easy interface and would be happy if you would stay
with this product for some years to come! We welcome feedback and suggestions at any time.
FirePackage© - Documentation FireGrab
Page 5
Distributed by:
How to grab an image – the fastest way to success
Writing a programmers guide is a difficult task: Nearly every programmer is under time pressure and
hates to read hundreds of lines to understand how it works.
The best would be: Reading the first page already leads to ninety percent of the know-how you need
for further use of the package. Unfortunately our world grows in complexity all the time and we need to
transfer much more information that we had to some years ago to make the technical aspects of a
product transparent and understandable.
So we also will not be able to transfer all the known how on the first page – but we will show just some
lines of code that directly lead to a small loop that continuously reads images from a connected camera.
#include "stdafx.h"
#include <stdio.h>
#include <conio.h>
#include <fgcamera.h>
int main(int
{
CFGCamera
UINT32
FGNODEINFO
UINT32
FGFRAME
argc, char* argv[])
Camera;
Result;
NodeInfo[3];
NodeCnt;
Frame;
// Init module
Result=FGInitModule(NULL);
// Get list of connected nodes
if(Result==FCE_NOERROR)
Result=FGGetNodeList(NodeInfo,3,&NodeCnt);
// Connect with node
if(Result==FCE_NOERROR && NodeCnt)
Result=Camera.Connect(&NodeInfo[0].Guid);
// Start DMA logic
if(Result==FCE_NOERROR)
Result=Camera.OpenCapture();
// Start image device
if(Result==FCE_NOERROR)
Result=Camera.StartDevice();
// Loop ...
while(Result==FCE_NOERROR && !kbhit())
{
// Wait 5000 MilliSeconds for a frame
Result=Camera.GetFrame(&Frame,5000);
// ... Here you can processs image data in Frame.pData
if(Result==FCE_NOERROR)
printf("Frame received (%02X %02X %02X %02X ...)\n",
Frame.pData[0],Frame.pData[1],Frame.pData[2],Frame.pData[3]);
// Return frame to module
if(Result==FCE_NOERROR)
Result=Camera.PutFrame(&Frame);
}
// Stop the device
Camera.StopDevice();
// Close capture
Camera.CloseCapture();
FirePackage© - Documentation FireGrab
Page 6
Distributed by:
// Exit module
FGExitModule();
return 0;
}
FirePackage© - Documentation FireGrab
Page 7
Distributed by:
Basic structure of FireGrab
The following illustration shows the basic structure.
Every card in the system is reflected by a logical FireCard-Device. Using the „old‟ FCTLxxx calls (see
FireStack documentation) an application can connect directly with this FireCard-Device and use the
functionality of the Firewire bus. But this is not part of this documentation.
The newly introduced Node-Manager, that is part of the kernel mode driver <firedrv.sys>, connects to
all FireCard-Devices permanently and acts as a global manager for all cards and all devices connected to the system.
A FireCard-Device can be used either by the NodeManager or an application that uses FCTLxxx
calls.
The NodeManager keeps track of all events on all cards and manages a list of all connected devices.
The list and especially the FireWire address of each device is managed in the background and is always kept current. Applications can get a copy of this list at any time.
If an application wants to use a FireWire device connected to a bus (i.e. a FireWire camera) it creates
a C++ object called <CFGCamera> (or a derived object). This object reflects the whole functionality of
an image acquisition device. Primarily this object has nothing to do with FireWire, it‟s an abstract entity
of an image device. To get any connection to the „real‟ FireWire device this logical device can connect
to one of the FireWire devices kept by the node manager in its device list.
When the connection between the logical and the real device is established all function requests are
routed to the real device by the appropriate FireWire bus communication calls. Basically the requested
functions are mapped to register accesses for a DCAM (digital camera) compatible camera and these
register accesses are mapped to the device that is actually connected with the C++ object created by
the user.
From FirePackage versions 2.25 on multiple applications can connect to one physical camera
device by calling <CFGCamera::Connect>. The busy flag from the node list entry can be used
to determine whether the camera object is in use by another application or not.
FirePackage© - Documentation FireGrab
Page 8
Distributed by:
Device List
Camera1
Camera1
Camera2
Camera3
Camera4
Camera5
Camera6
Camera7
Camera8
Camera9
Logical
FireCard
(FCTLxxCalls)
N ode
M anager
Physical
FirewireCard
Camera2
Camera3
Camera4
Logical
FireCard
(FCTLxxCalls)
Physical
FirewireCard
Logical
FireCard
(FCTLxxCalls)
Physical
FirewireCard
Camera5
Camera6
Camera7
Camera8
Camera9
Kernel Mode Driver FireDrv.sys
FGCamera.dll
FctlMain.dll
CFGCamera
Object
CFGCamera
Object
CFGCamera
Object
FGCamera - Application
FCTLxxx Calls
(FireStack)
FireStack - Application
Figure 1 – Basic structure
FirePackage© - Documentation FireGrab
Page 9
Distributed by:
Image transfer from camera to system memory
When using FireGrab all of the FireWire specifics are hidden. For better understanding only we explain how images are transferred over the bus to the PCs system memory.
A FireWire camera is an imaging source that has to solve the problem of transferring an image across
the physical connection between the camera and a PC. On a FireWire connection this image transfer
is done with so called data packets. An image is divided into data packets and these packets are
transferred over the bus one after the other.
On a FireWire bus there are two kinds of packets: asynchronous and isochronous.
Asynchronous means a device is allowed to transmit data at any time but has to arbitrate for the bus in
competition with all other devices on the bus. The arbitration is allowed to fail and for this reason a
device never can guarantee to transfer a specific bandwidth on the bus with asynchronous packets.
Isochronous means the device transfers data within fixed time slots with guaranteed bus access.
These time slots on a FireWire bus have a distance of 125 Microseconds (us).
Image data for standard FireWire cameras is always transferred with isochronous packets.
For better understanding let‟s assume our connected camera wants to transfer an image that has a
size of 320x240 pixels and a color format of YUV422. Furthermore our camera uses 8 bits for the image components. This leads to a complete amount of data of 320 x 240 x 2 = 153.600 bytes that have
to be transferred for each image from the camera to the PC.
A FireWire camera allows you to control the number of bytes transferred by each packet. As we know
that images are transferred in isochronous mode and that in isochronous mode one packet can be
transferred each 125 us we get the following formula:
Framerate = ((BytesPerImage/Packetsize) * 125µs)-1
In our case we select a packet size of 640 bytes. This gives 240 packets for a complete image and a
transfer time of 240 x 125µs = 0.03s. So our camera could transfer approximately 30 frames per
second.
On the PC side all packets from each camera are reassembled to images by DMAs that reside on
each FireWire card. A FireWire card can contain up to 8 DMAs. Every time a complete image has
been reassembled the connected application is notified and can catch the frame for further image
processing.
To allow multiple cameras to send isochronous image data over the same FireWire bus simultaneously, each packet sent by a camera must contain information about which logical channel it belongs
to. For that reason FireWire supports up to 64 logical channels for isochronous data transfer. On the
receive side each DMA that is made active must be configured for a specific isochronous channel.
This leads to the situation that on the receive side each camera will find an assigned DMA with the
same isochronous channel as the camera uses for data transmission. The DMA receives all the packets from the assigned camera and reassembles a complete image from all received packets
The following illustration shows how it works.
FirePackage© - Documentation FireGrab
Page 10
Distributed by:
Iso Cycle 1
FireWire Bus
Packet Channel 1
Iso Cycle 2
Packet Channel 2
Packet Channel 3
Image Buffer
DMA-1
Channel 1
Packet Channel 1
Packet Channel 2
Image Buffer
DMA-2
Channel 2
Packet Channel 2
Packet Channel 3
Image Buffer
DMA-3
Channel 3
Packet Channel 3
Packet Channel 1
Receive Logic
Figure 2 – Packet receive logic
FirePackage© - Documentation FireGrab
Page 11
Distributed by:
Safety first - isochronous transfer error checking
One of the most critical drawbacks of isochronous data transfer is the missing handshake and acknowledge mechanism. Originally isochronous transfer was mainly thought to be used for MultiMedia
applications and within this area the real time characteristic of data makes error checking superfluous.
In a video conference nobody bothers about one missing frame. All of the Microsoft Windows DirectDraw components behave in this manner.
But for industrial applications it‟s definitely not acceptable to ignore errors within image transmission.
In a sequential transmission that relies on the order of received packets it‟s even worse: not only the
currently transmitted frame is disturbed, but also the destroyed packet is replaced by the next one and
the missing packet at the end of the frame is taken from the next frame. This means there are at least
two frames disturbed.
FireGrab/FirePackage and its underlying driver try to detect all errors by using the following mechanisms.
 For each received packet all flags within the packets status area are checked and verified.
 Each received header of every packet is stored in a separate area and checked after a frame
is complete. If there is more than one header with a sync field of b‟0001 an error is raised.
 For each packet the number of the isochronous cycle this packet was received in is stored.
The continuity of these numbers is checked after the reception of a whole frame. Every missing or disturbed packet is recognized.
Especially the last two actions guarantee to detect erroneous transfers.
Every image transfer starts with a packet that has an asserted sync field within its header. This packet
is detected by hardware and a new image is started. All packets following this first initial packet are
written to the images data area. After the specified number of packets is received the image is assumed to be complete and posted to the user.
This behavior is critical because missing packets lead to an incomplete image that is not posted to the
user. The next image transferred will finish the previous image. Without header checking this error
would not be detected. Header checking as used in FirePackage/FireGrab (especially sync field
checking) will detect this error. Furthermore the driver will notice that there is a discontinuity within the
isochronous cycle numbers that where used to build the image.
Be aware that it still might happen that the first packet of an image is destroyed. This will avoid the
image transfer entirely and will lead to no image being received. This is very similar to the error of a
missing trigger that typically should be checked in an industrial image acquisition application.
This circumstance can only be solved by timeout mechanisms or image time-stamping done by the
camera.
Errors that are detected during transfer are global errors. They are reflected within the global error flag
field as HALERFLG_ISORX and can be detected within the callback function.
Additionally erroneous frames are marked with the FGF_INVALID flag within their respective flags.
By default error checking is disabled for compatibility reasons. You must enable error checking by setting the parameter <FGP_DMAFLAGS>.
FirePackage© - Documentation FireGrab
Page 12
Distributed by:
Direct Memory Access (DMA) modes in detail
From the application‟s view the reception of images is simply filling up predefined memory regions with
image data. Processing images and receiving images are two different processes that normally run
asynchronously. And as we know from technical processes that run asynchronously we have to take
care of synchronization in the form of queues, fifo buffers, or something similar.
In order to solve the synchronization problem FireGrab internally manages three queues that can hold
image (or frame) buffers.
One queue is dedicated to the receive DMA and every buffer that is linked to this queue is ready and
prepared to receive an image coming over the FireWire bus. The user normally has no access to buffers linked to this so called „DMA queue‟. When an image buffer has been completely filled up with
image data it is removed from the „DMA queue‟ and put to the second queue, the „ready queue‟, which
holds all buffers that are ready for delivering to the application.
When the application has accepted the new frame notification it requests an image from the „ready
queue‟. At that point the image buffer is removed from the „ready queue‟ and put to the „standby
queue‟. Images buffers in the „standby queue‟ are inactive and cannot be used by FireGrab itself. They
are completely under control of the application and come into play again when the application returns
an image buffer to FireGrab.
The following picture shows the structure.
10
PutFrame
9
8
7
3
5
6
4
1
2
Receive
en
wh
DMA-Queue
e
fill
d
e
am
tF r
Ge
Ready-Queue
Standby-Queue
Figure 3 – Internally managed frame queues
The DMA modes we are talking about in this chapter determine how the image buffers are handled in
relationship to the above mentioned three queues.
DMA - Continuous Mode
When the DMA runs in continuous mode (which is the mode already supported by FireStack) all initially allocated frame buffers are linked to the „DMA queue‟. When a buffer is filled it is linked to the
„ready queue‟. This is done as long as there are buffers in the „DMA queue‟. If the „DMA queue‟ is
empty (that is the application is too slow to keep up catching buffers) the DMA is halted and the user is
notified. As long as the „DMA queue‟ is empty incoming buffers are discarded. When the application
reads retrieves an image buffer it is moved from the „ready queue‟ to the „standby queue‟. Every time a
buffer is returned this buffer is put back to the „DMA queue‟ again and, if the queue was empty, the
DMA is restarted.
For this mode we keep the following in mind: Whenever the application cannot keep up catching buffers the DMA is halted. The „ready queue‟ holds the images that have been received before halting the
FirePackage© - Documentation FireGrab
Page 13
Distributed by:
DMA. Without halting the DMA the DMA is always active (if it has not been halted) and we always
have load on the PCI-Bus.
DMA - Replace Mode
The replace is mode is very similar to the continuous mode, with the difference that when the „DMA
queue‟ becomes empty (that is there is only 1 buffer left in this queue) the oldest buffer from the „ready
queue‟ is stolen from this queue and put back to the „DMA queue‟. This means the DMA is never
halted and the „ready queue‟ always holds the most recent image buffers. The application can detect
„stolen‟ buffers as every image buffer that leaves the „DMA queue‟ is stamped with a unique identifier.
DMA - Limp Mode
This is something very special and very useful. When an image device is running and the DMA is active image data is always transferred over the PCI bus into system memory even when the application
is not interested in images at present. There is no way of controlling PCI bus load at all.
In limp mode all image buffers are initially put to the „standby queue‟ and the DMA is halted. Even if
the image device is transmitting image data the DMA is completely inactive. The application can determine at what moment in time a buffer is put from the „standby queue‟ to the „DMA queue‟ and image
receiving takes place. Several buffers can be „pushed‟ from the „standby queue‟ to the „DMA queue‟.
But every time a buffer is filled and successfully processed it is automatically put back to the „standby
queue‟. The application must take care for moving it back to the „DMA queue‟.
This mode can be compared to the OneShot mode on imaging devices. It is a perfect imitation of that
on the PC side.
FirePackage© - Documentation FireGrab
Page 14
Distributed by:
Basic variable types used in FireGrab
The whole library uses the following global types:
#define UINT32 unsigned long
#define SINT32 long
#define UINT16 unsigned short
#define SINT16 short
#define UINT8 unsigned char
#define SINT8 char
#define TRUE
1
#define FALSE
0
#define NULL 0
#define NIL
((void*)-1)
typedef struct
{
UINT32
UINT32
}UINT32HL;
Low;
High;
FirePackage© - Documentation FireGrab
Page 15
Distributed by:
Debug utilities (LogUtil.dll)
In order to let the user trace all calls of an application into the library <FGCamera.dll> a debug
mechanism exists within this DLL.
During the call of <FGInit> the DLL tries to find another DLL with the fixed name <LogUtil.dll>. If this
library exists in the path of <FGCamera.dll> it is loaded into memory and scanned for a function with
the name and calling convention:
void __stdcall LogMsg(char* pFormat,...);
If this function can be found, every function call into the library <FGCamera.dll> calls this log function
on entry and exit. The parameters for this function conform to the standard calling convention of printf.
The normal installation of FirePackage contains a <LogUtil.dll> (in its own sub directory) that by default creates a log file called <fgcamera.log> and writes all log messages to this file. If this DLL is copied to the directory of <FGCamera.dll> that is used for your application this created-by-default log file
contains all the log messages of your applications.
For some implementation errors this can be extremely helpful.
FirePackage© - Documentation FireGrab
Page 16
Distributed by:
C-Style functions used in FireGrab
The real functionality of FireGrab is implemented in the class <CFGCamera>.
But for start up and shutdown there are 2 global functions and one function for device enumeration.
These functions are explained beneath.
FirePackage© - Documentation FireGrab
Page 17
Distributed by:
FGInitModule
C-Syntax:
UINT32 FSPEC FGInitModule(FGINIT *pArg /* can be NULL */);
Description:
<FGInitModule> prepares the whole library for use. It MUST be called before any other function is
used.
Furthermore this function accepts one argument that determines the notification method for events.
Most programmers prefer a strictly synchronous API. This means: The interface only talks if it has
been asked. This makes programming easy and avoids any conflicts when sharing resources. But for
image acquisition it can be quite convenient to be notified when for example a new image has been
received. This avoids wasting time for polling. On the other hand some predefined interfaces to image
processing libraries do not allow any unexpected notification so it‟s senseless to notify.
The argument for <FGInitModule> mainly determines the way of how the application wishes to be
notified.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
Type
Name
IO
Description
FGINIT
pArg
In
Determines the notification behavior of the module.
If it is NULL no notification takes place.
if it is not NULL the member determines the notification behavior.
Specific types:
typedef struct
{
void*
hWnd;
UINT16
Msg;
FGCALLBACK
*pCallback;
void*
Context;
UINT32
Flags;
}FGINIT;
//
//
//
//
//
Window handle for notification
Message to send to window
Pointer to callback
Context for callback
Special flags
Type
Name
IO
Description
void*
hWnd
In
Window handle of the window that is to receive notification messages. Events are posted to this window. If it‟s NULL no notification messages are posted.
UINT16
Msg
In
Message number that is used for message posting. Only used if
<hWnd> is not NULL.
This value is used as the first parameter for PostMessage(Msg...)
and should be larger or equal to WM_USER.
FGCALLBACK
pCallback
In
Pointer to a callback function that is called whenever an event
occurs. If it‟s NULL no callback function is called.
void*
Context
In
Context that is given to the callback function whenever it‟s called.
FirePackage© - Documentation FireGrab
Page 18
Distributed by:
Type
Name
IO
Description
UINT32
Flags
In
Bitfield of flags that determine the behavior of the module:
FGIF_ISOCONTEXTISHWND
When an object <CFGCamera> connects to a real object you can
specify a context that is used for notification whenever an image is
received. If this flag is TRUE this context is interpreted as a window handle and a message is posted to this window.
typedef void (FGCALLBACK)(void* Context,UINT32 wParam,void* lParam);
Type definition for the applications callback function.
Remarks:
The definition of the function FGInitModule uses a type specifier define <FSPEC>. Normally this is
defined as
#define FSPEC __declspec(dllimport) __stdcall
Callback Function
When a notification takes place (that means an event has occurred before) the <wParam> argument
from the callback function or windows message determines the notification reason. This notification
reason also determines the meaning of <lParam>. The following notification reasons exist:
FirePackage© - Documentation FireGrab
Page 19
Distributed by:
wParam
lParam
Meaning
WPARAM_NODELISTCHANGED No Meaning
The node list has changed and a new device might have been added or a device
could have been removed. The application
should call <FGGetNodeList> for verification.
WPARAM_ERROR
A global error has occurred on one of the
cards within your system. Please see the
chapter ErrorFlags for a detailed description of the single flags.
UINT32 bit field that
contains all ORed
error flags of all cards
For each card another message of the
form
WPARAM_ERRORFLAGSCARDx
is sent
WPARAM_FRAMESREADY
void*
An image has been received. When the
IsoContext that has
flag <FGIF_ISOCONTEXTISHWND> is
been specified in
set this message is posted to a window.
CFGCamera::Connect
WPARAM_ERRORFLAGSCARD0 UINT32 bit field that
WPARAM_ERRORFLAGSCARD1 contains the errors
that have occurred on
WPARAM_ERRORFLAGSCARD2 the specific card
WPARAM_ERRORFLAGSCARD3
After WPARAM_ERROR has been sent
(which reports all ORed errors of all cards)
a card specific message is sent that lets
you find the cards that produced the errors.
WPARAM_ERRORFLAGSCARD4
WPARAM_ERRORFLAGSCARD5
WPARAM_ERRORFLAGSCARD6
WPARAM_ERRORFLAGSCARD7
WPARAM_ERRORFLAGSCARD8
WPARAM_ERRORFLAGSCARD9
WPARAM_BUSRESET
No Meaning
FirePackage© - Documentation FireGrab
Informs the application that a bus reset
has occurred (1394 specific) and a reconfiguration cycle has been performed on the
bus.
Page 20
Distributed by:
FGExitModule
C-Syntax:
void FSPEC FGExitModule();
Description:
Closes the module and cleans up everything including memory freeing.
Please always call this function on application exit to guarantee proper shutdown.
Return Value:
None.
Parameters:
None.
Specific types:
None.
Remarks:
None.
FirePackage© - Documentation FireGrab
Page 21
Distributed by:
FGGetNodeList
C-Syntax:
UINT32 FSPEC FGGetNodeList(FGNODEINFO *pInfo,UINT32 MaxCnt,UINT32 *pRealCnt);
Description:
Retrieves a list of all nodes currently connected to the system. All cards that are currently used by
FTCLxxx applications (applications that use FireStack) are not taken into account.
If MaxCnt has a value of (Cnt + 0x8000000) this function lists all 1394 cards present in your system.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
Type
Name
IO
Description
FGNODEINFO* pInfo
Out Pointer to an array of FGNODEINFOs that will contain the information on function return.
UINT32
In
MaxCnt
Maximum number of node infos that can be copied to the node info
array.
If set to (0x80000000 + Cnt) information about 1394 cards installed
within the system is listed.
UINT32*
pRealCnt Out Pointer to an UINT32 variable that will contain the real number of
node infos copied on function return.
Specific types:
typedef struct
{
UINT32HL
UINT8
UINT8
UINT8
}FGNODEINFO;
Type
Guid;
CardNumber;
NodeId;
Busy;
Name
IO
//
//
//
//
GUID of this device
Card number
Depends on bus topology
Actually busy
Description
UINT32HL Guid
Out Holds the 64-Bit GUID of a connected node. A GUID consists of a
32-Bit high part that holds the VendorId (Highest 24 Bits) and the
ChipIdHigh (8 Bits) and a 32-Bit low part that holds the ChipIdLow.
The GUID is unique for all FireWire devices on the world.
UINT8
CardNumber
Out Number of FireWire card this node resides on.
UINT8
NodeId
Out Node identifier that comes out of the SelfId packets sent over the
bus after a bus reset. Has an informational character.
UINT8
Busy
Out If this is TRUE this node is already used by another application and
a connect attempt will fail.
Remarks:
FirePackage© - Documentation FireGrab
Page 22
Distributed by:
None.
FirePackage© - Documentation FireGrab
Page 23
Distributed by:
FGGetHostLicenseRequest
C-Syntax:
UINT32 FSPEC FGGetHostLicenseRequest(char *pStr,UINT32 MaxLen);
Description:
Retrieves the license request string for the host the DLL runs on. This string must be posted to your
dealer to obtain a valid license for your PC.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
Type
Name
IO
Description
char*
pStr
Out Pointer to a string buffer that holds the zero terminated license request string.
UINT32
MaxLen
In
Size of buffer that shall hold the license request string.
Specific types:
None.
Remarks:
None.
FirePackage© - Documentation FireGrab
Page 24
Distributed by:
FGGetLicenseInfo
C-Syntax:
UINT32 FSPEC FGGetLicenseInfo(UINT8 *pLicenseType);
Description:
Queries the system for the current global license type. This is intended to be used when no cameras
are connected and the application wants to query the status of global licensing.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
Type
Name
IO
Description
UINT8*
pLicenseType Out Pointer to an UINT8 variable that hold the current license type. It can
be one of the following:
HALLT_NOLICENSE
HALLT_CARDGUID
HALLT_HARDDISK
HALLT_ETHERNET
HALLT_VENDOR
HALLT_DATELIMITED
HALLT_DEVICE
HALLT_FRAMELIMITED
0
1
2
3
4
5
6
7
/*
/*
/*
/*
/*
/*
/*
/*
No license */
Firewire card */
Hard disk */
Ethernet adapter */
Vendor global */
Expires with date */
Device specific */
Limited by frames */
Specific types:
None.
Remarks:
A function with the same name exists as a member of <CFGCamera>. This function also returns the
licensing information for that specific device if a device specific license exists.
FirePackage© - Documentation FireGrab
Page 25
Distributed by:
The class CFGCamera
As mentioned previously, FireGrab tries to hide all FireWire specifics and exports the whole functionality of an image device in form of a C++ object. This class of this object is called <CFGCamera>.
The structure of this object is declared in the header file <fgcamera.h> and the functionality is exported in form of a DLL called <fgcamera.dll>.
For each image device an application has to instantiate an object of <CFGCamera>. After calling the
connect function from the instantiated object successfully it can treat this object as an identical copy of
the outside camera.
<CFGCamera> is declared as follows:
class CSPEC CFGCamera
{
protected:
UINT8
void*
UINT8
CCamera
m_Speed;
m_Context;
m_Card;
*m_pDCam;
//
//
//
//
Selected speed
Context for user
Card parameter
Internal work class
public:
virtual
CFGCamera();
~CFGCamera();
virtual CCamera*
GetPtrDCam();
virtual UINT32
virtual UINT32
WriteRegister(UINT32 Address,UINT32 Value);
ReadRegister(UINT32 Address,UINT32 *pValue);
virtual UINT32
virtual UINT32
WriteBlock(UINT32 Address,UINT8 *pData,UINT32 Length);
ReadBlock(UINT32 Address,UINT8 *pData,UINT32 Length);
virtual UINT32
virtual UINT32
Connect(UINT32HL *pGuid,void* IsoContext=NULL);
Disconnect();
virtual UINT32
virtual UINT32
virtual UINT32
SetParameter(UINT16 Which,UINT32 Value);
GetParameter(UINT16 Which,UINT32 *pValue);
GetParameterInfo(UINT16 Which,FGPINFO *pInfo);
virtual UINT32
virtual UINT32
StartDevice();
StopDevice();
virtual UINT32
virtual UINT32
GetDeviceName(char *pAll,UINT32 MaxLength,char *pDev=NULL);
GetLicenseRequest(char *pStr,UINT32 MaxLen);
virtual void*
GetContext();
virtual UINT32
virtual UINT32
OpenCapture();
CloseCapture();
virtual UINT32
virtual UINT32
virtual UINT32
GetFrame(FGFRAME *pFrame,UINT32 TimeoutInMs=INFINITE);
PutFrame(FGFRAME *pFrame);
DiscardFrames();
virtual UINT32
AssignUserBuffers(UINT32 Cnt,UINT32 Size,void* *ppMemArray); };
The object‟s member variables are not for outside use. They are just available internally.
The pointer <m_pDCam> is a pointer to the real internal worker object and can be used to determine
whether the object is connected with a real outside camera (m_pDCam!=NULL) or not
(m_pDCam==NULL).
Each member function is explained in detail below.
Before you can use the DLLs functionality you MUST call <FGInitModule>.
On application termination you MUST call <FGExitModule> for proper cleanup.
FirePackage© - Documentation FireGrab
Page 26
Distributed by:
Please see the associated chapters.
FirePackage© - Documentation FireGrab
Page 27
Distributed by:
CFGCamera::Connect
C++-Syntax:
UINT32 Connect(UINT32HL *pGuid,void* IsoContext=NULL);
Description:
Connects this object with a real camera connected to the system via FireWire. The camera is selected
by a unique GUID. When starting image acquisition the application can activate a notification scheme
to be informed when new images have arrived.
To figure out which object has transferred an image an IsoContext can be specified (and retrieved).
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
Type
Name
IO Description
UINT32HL*
pGuid
In
Pointer to a GUID that contains the exact GUID of the real FireWire
camera this object shall be connected to.
void*
IsoContext In
On notification for a new frame this context is posted to the application.
If the function <FGInitModule> has been called with an argument
and the flags parameter of the argument contained an asserted bit
FGIF_ISOCONTEXTISHWND then the notification for a received
frame is posted to a window with the handle <IsoContext>.
Specific types:
None.
Remarks:
When a <CFGCamera> object is unconnected its member variable <m_pDCam> is NULL. After a
successful connection this variable contains a pointer to the working object that holds the connection
to the real outside camera.
When an application has connected itself with a camera this camera is busy and cannot be used by
any other application.
To change this behaviour you can add a registry entry called “MultiConnect” under the drivers parameters and set this DWORD value to 1. When the driver is restarted it allows multi connections from different FireGrab applications. The registry entry is:
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\firedrv\Parameters]
"MultiConnect"=dword:00000001
FirePackage© - Documentation FireGrab
Page 28
Distributed by:
CFGCamera::Disconnect
C++-Syntax:
UINT32 Disconnect();
Description:
Disconnect this object from an external camera and brings it back to its initial idle state.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
None.
Specific types:
None.
Remarks:
None.
FirePackage© - Documentation FireGrab
Page 29
Distributed by:
CFGCamera::SetParameter
C++-Syntax:
UINT32 SetParameter(UINT16 Which,UINT32 Value);
Description:
Changes a specific parameter of the camera object. Most of the parameters are written to the real
outside camera directly. Please also see chapter Camera Parameters.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
Type
Name
IO
Description
UINT16
Which
In
Determines which parameter shall be set. Please see the chapter
Camera Parameters for all possible values.
UINT32
Value
In
Value for this parameter. The meaning of this parameter definitely
depends on the selected parameter. If supported by the selected parameter some special predefines exist:
PVAL_OFF
This parameter is completely switched off (if supported).
PVAL_AUTO
This parameter is switched to automatic mode (if supported). Any
other value switches this parameter back to manual mode.
PVAL_ONESHOT
This parameter is automatically adjusted one time and can then be
controlled manually again (if supported).
Specific types:
None.
Remarks:
All settings of the logically connected camera are controlled via this function.
FirePackage© - Documentation FireGrab
Page 30
Distributed by:
CFGCamera::GetParameter
C++-Syntax:
UINT32 GetParameter(UINT16 Which,UINT32 *pValue);
Description:
Retrieves the actual state of a parameter. Please also see Camera Parameters.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
Type
Name
IO
Description
UINT16
Which
In
Determines which parameter shall be retrieved. Please see the
chapter Camera Parameters for all possible values.
UINT32*
pValue
In/Out
Pointer to 32 Bit variable that contains the parameter value on
function exit. There are three special predefines that can be returned:
PVAL_OFF
This parameter is completely switched off (if supported).
PVAL_AUTO
This parameter is switched to automatic mode (if supported) and is
controlled by the image device itself.
PVAL_ONESHOT
This parameter is automatically adjusted one time at present (if
supported) and can be adjusted manually again later.
Specific types:
None.
Remarks:
None.
FirePackage© - Documentation FireGrab
Page 31
Distributed by:
CFGCamera::GetParameterInfo
C++-Syntax:
UINT32 GetParameterInfo(UINT16 Which,FGPINFO *pInfo);
Description:
This function retrieves additional information about a specific parameter (such as value range, special
value structure etc.).
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
Type
Name
IO
Description
UINT16
Which
In
Determines for which parameter the extra information shall be
retrieved. Please see the chapter Camera Parameter for all possible values.
FGPINFO*
pInfo
In/Out
Pointer to a FGPINFO structure that contains the parameter information on function exit.
Specific types:
typedef struct
{
UINT32
UINT32
UINT32
UINT32
FGPSPECIFIC
}FGPINFO;
IsValue;
MinValue;
MaxValue;
Unit;
Specific;
//
//
//
//
//
Actual value
Parameters min. value
Parameters max. value
Parameters unit
Parameters specific
Type
Name
IO
Description
UINT32
IsValue
Out
Current value for this parameter (value that would be returned
when calling GetParameter).
UINT32
MinValue
Out
Minimum allowed value for this parameter.
UINT32
MaxValue
Out
Maximum allowed value for this parameter.
UINT32
Unit
Out
Unit used for this parameter to grow incrementally from MinValue to MaxValue (Value can be Value=(MinValue+n*Unit)
whereas n=0..N).
FGPSPECIFIC
Specific
Out
Additional information for a parameter that accepts special
values.
typedef struct
{
UINT8
union
{
Type;
FirePackage© - Documentation FireGrab
// Type, 0=invalid, no specific
Page 32
Distributed by:
FGPSFEATURE FeatureInfo;
FGPSTRIGGER TriggerInfo;
UINT32
ColorFormat;
// Type=1
// Type=2
// Type=3
}Data;
}FGSPECIFIC;
Type
Name
IO
Description
UINT8
Type
Out
Type specifier. Determines what type the data area contains. If type
is 0 then <Data> is invalid.
union
Data
Out
Data area that can hold different data types.
When <Type> is 1 then <Data> contains additional information about a so called camera feature (see
DCam specification). The single bits have the following meaning.
typedef struct
{
UINT8
UINT8
UINT8
UINT8
UINT8
UINT8
UINT8
}FGPSFEATURE;
ReadOutCap
OnOffCap
OnOffState
AutoCap
AutoState
OnePushCap
OnePushState
:
:
:
:
:
:
:
1;
1;
1;
1;
1;
1;
1;
//
//
//
//
//
//
//
Value can be read
Switchable
On-State
Auto mode capable
Auto state
One push capable
One push state
Type
Name
IO
Description
UINT8:1
ReadOutCap
Out
If set then this parameter can be read back from the camera.
UINT8:1
OnOffCap
Out
If set this parameter can be switched OFF or ON.
UINT8:1
OnOffState
Out
Actual ON/OFF state.
UINT8:1
AutoCap
Out
If set this parameter can be brought to an automatic mode (Self
adjusting).
UINT8:1
AutoState
Out
Actual state of the automatic mode.
UINT8:1
OnePushCap
Out
If set this parameter supports one time adjusting.
UINT8:1
OnePushState
Out
Current state of one time adjust.
When <Type> is 2 then <Data> contains additional information about the trigger capabilities of the
device.
A so-called camera feature (see DCam specification). The single bits have the following meaning.
typedef struct
{
UINT32
UINT32
UINT32
UINT32
UINT32
UINT32
UINT32
UINT32
UINT32
UINT32
UINT32
UINT32
}FGPSTRIGGER;
ReadOutCap
: 1;
OnOffCap
: 1;
OnOffState
: 1;
PolarityCap
: 1;
PolarityState : 1;
ReadInputCap : 1;
InputState
: 1;
TriggerSrcCap : 8;
TriggerSrc
: 4;
TriggerModeCap: 16;
TriggerMode
: 4;
TriggerParameter : 12;
FirePackage© - Documentation FireGrab
//
//
//
//
//
//
//
//
//
//
//
//
Value can be read
Switchable
On-State
Polarity capable
Polarity state
Input readable
Input state
Trigger source capabilities
Actual trigger source
Trigger mode capabilities
Actual Trigger mode
Actual trigger parameter
Page 33
Distributed by:
Type
Name
IO
Description
UINT32:1
ReadOutCap
Out
If set the trigger control register from the image device can be
read back.
UINT32:1
OnOffCap
Out
Trigger functionality can be switched OFF or ON.
UINT32:1
OnOffState
Out
Current state of trigger functionality (ON or OFF).
UINT32:1
PolarityCap
Out
If set then trigger polarity can be changed.
UINT32:1
PolarityState
Out
Current state of trigger polarity (0: low active, 1: high active).
UINT32:1
ReadInputCap
Out
If set then trigger input can be read back.
UINT32:1
InputState
Out
Current state of trigger input.
UINT32:8
TriggerSrcCap
Out
Bit field of trigger sources (every set bit from 0x80 to 0x01 tells
that the source 0...7 can be selected).
UINT32:4
TriggerSrc
Out
Currently selected trigger source.
UINT32:16
TriggerModeCap
Out
Bit field of trigger modes (every set bit from 0x8000 to 0x01
tells that the trigger mode 0...15 can be selected).
UINT32:4
TriggerMode
Out
Currently selected trigger mode.
UINT32:12
TriggerParameter
Out
Current trigger parameter.
Remarks:
None.
FirePackage© - Documentation FireGrab
Page 34
Distributed by:
CFGCamera::StartDevice
C++-Syntax:
UINT32 StartDevice();
Description:
Start the image device with all previously set parameters. After successful call the image device is
active.
If the burst count (that is the number of images the image device is active for) is not set to
BC_INFINITE then the image device stops after N images and this function must be called repeatedly.
When isochronous resources shall be allocated automatically this function does isochronous resource
allocation when called before <CFGCamera::OpenCapture>. When called after isochronous resources
are used from the allocation done by <CFGCamera::OpenCapture>.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
None.
Specific types:
None.
Remarks:
None.
FirePackage© - Documentation FireGrab
Page 35
Distributed by:
CFGCamera::StopDevice
C++-Syntax:
UINT32 StopDevice();
Description:
Stops the image device and brings it into an idle state.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
None.
Specific types:
None.
Remarks:
None.
FirePackage© - Documentation FireGrab
Page 36
Distributed by:
CFGCamera::GetDeviceName
C++-Syntax:
UINT32 GetDeviceName(char *pAll,UINT32 MaxLength, char *pDev=NULL);
Description:
Retrieves a clear text name with zero termination of the currently connected image device that consists of the vendor name and the model name as it is stored in the devices vendor/model leaf OR copies the vendor name to <pAll> and the model name to <pDev>.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
Type
Name
IO
Description
char*
pAll
In
Pointer to a buffer that will hold the complete name of the device
(vendor name in combination with model name). If <pDev> is unequal to NULL the vendor name will be copied to this buffer.
UINT32
MaxLength
In
Maximum size of either <pAll> or (if specified) <pAll> and <pBuf>.
char*
pDev
In
Optional parameter: If NULL then the vendor and model name will
be copied to <pAll>.
If unequal NULL then <pAll> will hold the vendor name and
<pDev> will hold the model name of the connected device.
Specific types:
None.
Remarks:
None.
FirePackage© - Documentation FireGrab
Page 37
Distributed by:
CFGCamera::GetContext
C++-Syntax:
void* GetContext();
Description:
Retrieves the context that has been specified when calling <Connect>.
Return Value:
Context that has been specified by the user when calling <Connect>.
Parameters:
None.
Specific types:
None.
Remarks:
None.
FirePackage© - Documentation FireGrab
Page 38
Distributed by:
CFGCamera::GetPtrDCam
C++-Syntax:
CCamera* GetPtrDCam();
Description:
Returns a pointer to the worker object CCamera. CCamera is by default unknown to the user and
should only be used by the well experienced programmer.
Return Value:
Pointer to CCamera object that does the internal work.
Parameters:
None.
Specific types:
None.
Remarks:
FirePackage© - Documentation FireGrab
Page 39
Distributed by:
CFGCamera::WriteRegister
C++-Syntax:
UINT32 WriteRegister(UINT32 Address,UINT32 Value);
Description:
This function allows you to write a 32-Bit value to one of the multiple camera registers. For detailed
information for camera registers and their functions see the Digital Camera Specification.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
Type
Name
IO
Description
UINT32
Address
In
32-Bit address of register that shall be written.
UINT32
Value
In
Value for register.
Specific types:
None.
Remarks:
None.
FirePackage© - Documentation FireGrab
Page 40
Distributed by:
CFGCamera::ReadRegister
C++-Syntax:
UINT32 WriteRegister(UINT32 Address,UINT32 *pValue);
Description:
This function allows you to read a 32-Bit value from one of the multiple camera registers. For detailed
information for camera registers and their functions see the Digital Camera Specification.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
Type
Name
IO
Description
UINT32
Address
In
32-Bit address of register that shall be written.
UINT32*
pValue
Out
Pointer to a 32-Bit value that contains new data on function exit.
Specific types:
None.
Remarks:
None.
FirePackage© - Documentation FireGrab
Page 41
Distributed by:
CFGCamera::WriteBlock
C++-Syntax:
UINT32 WriteBlock(UINT32 Address,UINT8 *pData,UINT32 Length);
Description:
This function allows you to write multiple 32-Bit values to the camera. For detailed information for
camera registers and their functions see the Digital Camera Specification.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
Type
Name
IO
Description
UINT32
Address
In
32-Bit start address.
UINT32*
pData
In
Pointer to data area that shall be written.
UINT32
Length
In
Length of data area that shall be written.
Specific types:
None.
Remarks:
None.
FirePackage© - Documentation FireGrab
Page 42
Distributed by:
CFGCamera::ReadBlock
C++-Syntax:
UINT32 ReadBlock(UINT32 Address,UINT8 *pData,UINT32 Length);
Description:
This function allows you to read multiple 32-Bit values from a camera. For detailed information for
camera registers and their functions see the Digital Camera Specification.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
Type
Name
IO
Description
UINT32
Address
In
32-Bit start address.
UINT32*
pData
In
Pointer to data area that shall be filled with camera data.
UINT32
Length
In
Length of data area that shall be read.
Specific types:
None.
Remarks:
None.
FirePackage© - Documentation FireGrab
Page 43
Distributed by:
CFGCamera::GetLicenseRequest
C++-Syntax:
UINT32 GetLicenseRequest(char *pStr,UINT32 MaxLen);
Description:
Retrieves the license request string for this camera. This string must be posted to your dealer to obtain
a valid license for this camera device.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
Type
Name
IO
Description
char*
pStr
Out Pointer to a string buffer that holds the zero terminated license request string.
UINT32
MaxLen
In
Size of buffer that shall hold the license request string.
Specific types:
None.
FirePackage© - Documentation FireGrab
Page 44
Distributed by:
CFGCamera::OpenCapture
C++-Syntax:
UINT32 OpenCapture();
Description:
Opens, prepares and activates the image capture logic on the PC side. It does not start the image
device, it just prepares the whole receive logic. All image buffers are allocated.
When isochronous resources shall be allocated automatically (see parameters FGP_USEIRMFORBW
and FGP_USEIRMFORCHN) this function does isochronous resource allocation when called before
<CFGCamera::StartDevice> (we need an isochronous channel for DMA setup). When called after
isochronous resources are used from the allocation done by <CFGCamera::StartDevice>.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
None.
Specific types:
None.
Remarks:
If FCE_PARTIAL is returned not all requested frame buffers could be allocated (is the case for large
images). You can change the number of frame buffers with FGP_FRAMEBUFFERCOUNT.
FirePackage© - Documentation FireGrab
Page 45
Distributed by:
CFGCamera::CloseCapture
C++-Syntax:
UINT32 CloseCapture();
Description:
Closes the capture logic on the PC side and frees all image buffers. All allocated resources on the
FireWire bus are freed also.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
None.
Specific types:
None.
Remarks:
None.
FirePackage© - Documentation FireGrab
Page 46
Distributed by:
CFGCamera::GetFrame
C++-Syntax:
UINT32 GetFrame(FGFRAME *pFrame,UINT32 TimeoutInMs=INFINITE);
Description:
After the capture logic has been opened and the image device has been started this function retrieves
images.
When calling with NULL for <pFrame> the actual status can be acquired.
This function catches one frame at a time.
Every successfully retrieved frame must be returned with <PutFrame>.
After an application has caught a frame it is completely under control of the application until it is returned with <PutFrame>.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
If the module runs without notification (FGINIT called with an argument of NULL), this function returns
HALER_DMAHALTED if the DMA has been halted. This is just informational. The next function call
will succeed.
Parameters:
Type
Name
IO
Description
FGFRAME*
pFrame
In
Pointer to a structure that is filled with frame information
(=image) on function return.
When this parameter is NULL the function returns the status of
the availability of frames: If frames are waiting then
FCE_NOERROR is returned, otherwise HALER_NODATA.
UINT32
TimeoutInMs
In
Timeout in Milliseconds (ms) this functions shall wait for a frame.
If this value is INFINITE this function waits for a frame infinitely
(not recommended).
If this value is zero it returns immediately.
Specific types:
typedef struct
{
void*
System;
UINT32
Flags;
UINT16
Id;
UINT8
*pData;
UINT32
Length;
UINT32HL
RxTime;
UINT32
BeginCycleTime;
UINT32
EndCycleTime;
UINT32
Reserved[2];
}FGFRAME;
FirePackage© - Documentation FireGrab
//
//
//
//
//
//
//
//
//
For system use only
Flags: Last, Invalid, no post etc...
Continuous ID
Data pointer
Buffers length
Receive time
Frame begin as bus time
Frame end as bus time
Reserved for future use
Page 47
Distributed by:
Type
Name
IO
Description
void*
System
Out
For system use only. Don‟t touch!
UINT32
Flags
Out/In
Field of single bit flags that hold additional information about
this frame:
FGF_INVALID
Data area may be corrupted or invalid.
FGF_LAST
This frame is the last in the „ready queue‟ (Next call to <GetFrame> will fail with FCE_NODATA or HALER_TIMEOUT).
FGF_DMAHALTED
Notifies the user that the DMA has been halted due to missing frame buffers before this frame has been caught by the
application.
FGF_FORCEPOST
See <PutFrame>.
UINT16
Id
Out
Identifier for this frame. Every time a frame is brought from
the „DMA queue‟ to the „ready queue‟ FireGrab stamps it with
a continuous identifier.
UINT8*
pData
Out
Pointer to image data.
This member is set to NULL when the driver sends a
frame start notification which can be enabled with the
parameter FGP_DMAFLAGS.
UINT32
Length
Out
Length of image data area in bytes.
UINT32HL
RxTime
Out
Receive time as 100ns ticks since 1.1.1601.
UINT32
BeginCycleTime
Out
When frame start events are active this is the bus time when
the frame start was detected (for bus time see remarks).
UINT32
EndCycleTime
Out
This is the bus time when the frame end was detected (for
bus time see remarks).
UINT32[2]
Reserved
---
Reserved.
Remarks:
Don‟t forget to return this frame after processing.
Under Windows the RxTime can be converted to actual time with standard Windows operating system
functions.
The 32 bit bus time has the following structure:
struct
{
UINT32
UINT32
UINT32
}BUSTIME;
CycleOffset : 12;
CycleCount : 13;
Second
: 7;
which is:
Bit[11..0] = Cycle Offset in parts of 1/3072 (=24.576 MHz)
Bit[24..12] = Cycle Count
Bit[31..25] = Second Count
FirePackage© - Documentation FireGrab
Page 48
Distributed by:
CFGCamera::PutFrame
C++-Syntax:
UINT32 PutFrame(FGFRAME *pFrame);
Description:
Returns a frame to the „DMA queue‟ and prepares it to receive new image data.
When the DMA is in limp mode this function when called with a NULL parameter pushes a
frame from the ‘standby queue’ to the ‘DMA queue’.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
Type
Name
IO
Description
FGFRAME*
pFrame
In
Pointer to a frame information structure that previously has been filled
up by calling <GetFrame>.
When the DMA is in limp mode this parameter can be NULL. If it‟s
NULL then one frame is moved from the „standby queue‟ to the „DMA
queue‟ and the DMA is started if it had entered halt state before.
Specific types:
typedef struct
{
void*
System;
UINT32
Flags;
UINT16
Id;
UINT8
*pData;
UINT32
Length;
UINT32
Reserved[6];
}FGFRAME;
FirePackage© - Documentation FireGrab
//
//
//
//
//
//
For system use only
Flags: Last, Invalid, no post etc...
Continous ID
Data pointer
Buffers length
Reserved for future use
Page 49
Distributed by:
Type
Name
IO
Description
void*
System
Out
For system use only. Don‟t touch!
UINT32
Flags
Out/In
Field of single bit flags that hold additional information about this
frame:
FGF_INVALID
Data area may be corrupted or invalid.
FGF_LAST
This frame is the last in the „ready queue‟ (Next call to <GetFrame> will fail> with FCE_NODATA or HALER_TIMEOUT).
FGF_FORCEPOST
When set and limp mode is active forces this frame to be returned directly to the „DMA queue‟ instead of the „standby
queue‟.
UINT16
Id
Out
Identifier of this frame. Every time a frame is brought from the
„DMA queue‟ to the „ready queue‟ FireGrab stamps it with a
continuous identifier.
UINT8*
pData
Out
Pointer to image data.
UINT32
Length
Out
Length of image data area in bytes.
UINT32[4]
Reserved
---
Reserved.
Remarks:
Every frame retrieved by calling <GetFrame> must be returned by calling <PutFrame>.
When the DMA is in limp mode a frame is put to the „standby queue‟ when calling <PutFrame>. You
must call <PutFrame> with a NULL argument to move a frame from the „standby queue‟ to the „DMA
queue‟.
Exception: You can force moving this frame directly to the „DMA queue‟ when limp mode is active by
asserting FGF_FORCEPOST in the Flags member of FGFRAME.
FirePackage© - Documentation FireGrab
Page 50
Distributed by:
CFGCamera::DiscardFrames
C++-Syntax:
UINT32 DiscardFrames();
Description:
Discards all received frames and brings the receive logic in the same state as it was when it was
opened.
When limp mode is inactive all frame buffers are brought to the „DMA queue‟ and are ready to receive
images.
When limp mode is active all frame buffers are brought to the „standby queue‟ and the DMA is halted.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
None.
Specific types:
None.
Remarks:
None.
FirePackage© - Documentation FireGrab
Page 51
Distributed by:
CFGCamera::AssignUserBuffers
C++-Syntax:
UINT32 AssignUserBuffers(UINT32 Cnt,UINT32 Size,void* *ppMemArray);
Description:
This function allows assignment of user allocated memory for image acquisition. This function must be
called before <OpenCapture> is called. After the capture mechanism is closed with <CloseCapture>
the pushed buffers must be removed from the object with a call of this function with all parameters set
to 0 (see section remarks on this side).
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
Type
Name
IO
Description
UINT32
Cnt
In
Number of valid frame buffers that are contained in the array
specified by <ppMemArray>.
If 0 is specified all previously specified buffers are removed.
UINT32
Size
In
Size in bytes of each buffer specified in <ppMemArray>.
void**
ppMemArray
In
Pointer to an array of void-pointers specifying user defined memory areas for image acquisition.
If NULL is specified all previously specified buffers are removed.
Specific types:
None.
Remarks:
Don‟t be confused with the type used for specifying the memory buffers. The following example helps
to understand the types:
void UserBufferExample()
{
void*
pMem[3];
CFGCamera Camera;
UINT32
FrameSize,i,Result;
// Get size of one image buffer
Result=Camera.GetParameter(FGP_FRAMEMEMORYSIZE,&FrameSize);
// Add padding data
Result=Camera.GetParameter(FGP_PACKETSIZE,&PacketSize);
if((Result== FCE_NOERROR) && (FrameSize%PacketSize))
FrameSize=((FrameSize-1)/PacketSize+1)*PacketSize;
// Allocate 3 buffers
for(i=0;i<3;i++)
pMem[i]=new UCHAR[FrameSize];
FirePackage© - Documentation FireGrab
Page 52
Distributed by:
// Give to camera
Result=Camera.AssignUserBuffers(3,FrameSize,pMem);
Result=Camera.OpenCapture();
Result=Camera.StartDevice();
// ... Do any image acquistion here
Result=Camera.StopDevice();
Result=Camera.CloseCapture();
// Remove buffers from camera object
Result=Camera.AssignUserBuffers(0,0,NULL);
// Free buffers
for(i=0;i<3;i++)
delete[] pMem[i];
}
FirePackage© - Documentation FireGrab
Page 53
Distributed by:
The class CBroadcast
In some situations it might be useful to write values to different cameras residing on the same bus all
at once. For this purpose a CBroadcast object can be associated with a camera and can then be used
to broadcast WriteRegister or WriteBlock commands. The class is declared as follows:
class CSPEC CBroadcast
{
protected:
CFGCamera
*m_pFGCamera;
void
*m_Handle;
public:
CBroadcast(CFGCamera *pFGCamera);
virtual UINT32
virtual UINT32
WriteRegister(UINT32 Address,UINT32 Value);
WriteBlock(UINT32 Address,UINT8 *pData,UINT32 Length);
};
The two functions <WriteRegister> and <WriteBlock> work like the appropriate functions from
<CFGCamera> (see description there) except that they broadcast their write commands to all devices
on the same bus.
When a <CBroadcast> object is created it must be associated with a CFGCamera object by calling the
constructor with a pointer to this object in order to specify a bus. Otherwise <WriteRegister> or
<WriteBlock> will not work properly.
The following code lines show how this object can be used:
… function_header()…
FGNODEINFO
UINT32
UINT32
CFGCamera
CBroadcast
Info[16];
InfoCnt;
Result;
Camera;
BC(&Camera);
Result=FGGetNodeList(Info,16,&InfoCnt);
// Connect with first camera
Result=Camera.Connect(&Info[0].Guid);
// Broadcast write command
Result=BC.WriteRegister(0xF0F00614,0x80000000);
FirePackage© - Documentation FireGrab
Page 54
Distributed by:
The class CFGIsoDma
Starting image acquisition on a PC consists of two actions: the camera itself must be started and the
local resources for automatic image transfer to system memory must be set up. The latter action is
related to the card internal DMA. In some cases it might be useful to have control over both actions
independent from each other. The <CFGCamera> object has different functions for each action (i.e.
<StartDevice>, <StopDevice> and <OpenCapture>, <CloseCapture>) but does not allow to start each
of these components with independent parameters.
The current version of FirePackage introduces an object which allows setting up a DMA without an
underlying camera device. This mainly should be used when one camera shall be received on different DMA channels on probably different systems.
The C++ object looks like this:
class CSPEC CFGIsoDma
{
protected:
CIsoDma
*m_pIsoDma;
// Worker object
public:
virtual
CFGIsoDma();
~CFGIsoDma();
virtual UINT32
virtual UINT32
Start(FGISODMAPARMS *pArg);
Stop();
virtual UINT32
virtual UINT32
virtual UINT32
GetFrame(FGFRAME *pFrame,UINT32 TimeoutInMs);
PutFrame(FGFRAME *pFrame);
DiscardFrames();
virtual UINT32
virtual UINT32
AssignUserBuffers(UINT32 Cnt,UINT32 Size,void* *ppMemArray);
Resize(UINT32 PktCnt,UINT32 PktSize);
};
All functions of this object are very similar to the appropriate functions from <CFGCamera> which in
fact also contains a hidden <CFGIsoDma> object. The main difference is that when a <CFGIsoDma>
object is activated by calling <CFGIsoDma::Start> all parameters that are normally contained in the
camera object must be set manually by filling the structure <FGISODMAPARMS>. But this task is
straight forward and for the experienced camera programmer all structure members are easy to understand.
The details of each function are explained within the next chapters.
FirePackage© - Documentation FireGrab
Page 55
Distributed by:
CFGIsoDma::OpenCapture
C++-Syntax:
UINT32 OpenCapture(FGISODMAPARMS *pParms);
Description:
Opens, prepares and activates the image capture logic on the PC side. All image buffers are allocated
when no user buffers are associated.
No isochronous resources are allocated as this task must be done by the connected <CFGCamera>
device that transmits images.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
Type
Name
IO
Description
FGISODMAPRAMS*
pParms
In/Out
Pointer to a FGISODMAPARMS structure that contains all
parameters for this DMA.
The member <RealBufCnt> is filled on successful function
return.
Specific types:
typedef struct
{
UINT8
UINT8
UINT16
UINT32
UINT16
UINT8
UINT8
void*
UINT32
}FGISODMAPARMS;
// Argument for CFGIsoDma::Start
CardNr;
IsoChn;
FrameCnt;
PktCnt;
PktSize;
DmaMode;
DmaFlags;
NotifyContext;
RealBufCnt;
//
//
//
//
//
//
//
//
//
On which card
Isochronous channel
Frames to allocate
Number of packets
Size of single packet (bytes)
DMA mode
DMA flags
Notification context
Allocated buffer count
Type
Name
IO
Description
UINT8
CardNr
In
Index of card that shall be used for this DMA. This value can be
achieved from <CFGCamera> via the FGP_CARD parameter or
from the array filled by <FGGetNodeList>.
UINT8
IsoChn
In
Isochronous channel that shall be used when the DMA start listening on the bus.
UINT16
FrameCnt
In
Number of frames to allocate when no user buffers are associated
with this object. When user buffers are used this parameter is ignored.
UINT32
PktCnt
In
Number of packets that make up a whole frame (one complete image).
FirePackage© - Documentation FireGrab
Page 56
Distributed by:
Type
Name
IO
Description
UINT16
PacketSize
In
Size of each packet a frame consists of.
UINT8
DmaMode
In
Determines the mode for this DMA. Can be one of the following
values:
DMA_CONTINOUS
DMA_LIMP
DMA_REPLACE
Please see chapter DMA modes for a detailed explanation.
UINT8
DmaFlags
In
Bit field that contains ORed combination of security flags that can be
used to make image transfer more secure. The following values can
be combined:
DMAF_CHECKSYNC - Check for double sync field
DMAF_CHECKCYCLE - Check for wrong cycle
DMAF_CHECKLENGTH - Check each packet length
DMAF_FRAMESTART - Create frame start events
DMAF_CONTEXTISEVT - If set „NotifyContext‟ specifies a Windows
event which is set in case of an event
DMAF_CONTEXTISCB - If set “NotifyContext” specifies a pointer to
a callback function which is called in case of an event
A more detailed explanation can be found under the description of
the parameter FGP_DMAFLAGS.
void*
NotifyContext
In
Notification context for all events of this DMA when the callback
function specified with <FGInitModule> is called.
UINT32
RealBufCnt
Out
Number of real allocated frames. Filled on function exit. When
memory is not scarce this parameter should reflect the value specified with <FrameCnt> on function entry.
Remarks:
If FCE_PARTIAL is returned not all requested frame buffers could be allocated. The member <RealBufCnt> reflects the number of actually allocated buffers.
FirePackage© - Documentation FireGrab
Page 57
Distributed by:
CFGIsoDma::CloseCapture
C++-Syntax:
UINT32 CloseCapture();
Description:
Closes the capture logic on the PC side and frees all image buffers.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
None.
Specific types:
None.
Remarks:
None.
FirePackage© - Documentation FireGrab
Page 58
Distributed by:
CFGIsoDma::GetFrame
C++-Syntax:
UINT32 GetFrame(FGFRAME *pFrame,UINT32 TimeoutInMs=INFINITE);
Description:
After the capture logic has been opened this function retrieves images.
When calling with NULL for <pFrame> the actual status can be queried.
This function catches one frame at a time.
Every successfully retrieved frame must be returned with <PutFrame>.
After an application has caught a frame it is completely under control of the application until it is returned with <PutFrame>.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
If the module runs without notification (<FGInitModule> called with an argument of NULL), this function
returns HALER_DMAHALTED if the DMA has been halted due to a lack of frame buffers. This is just
informational. The next function call will succeed.
Parameters:
Type
Name
IO
Description
FGFRAME*
pFrame
In
Pointer to a structure that is filled with frame information
(=image) on function return.
When this parameter is NULL the function returns the status of
the availability of frames: If frames are waiting then
FCE_NOERROR is returned, otherwise HALER_NODATA.
UINT32
TimeoutInMs
In
Timeout in Milliseconds (ms) this function shall wait for a frame.
If this value is INFINITE this function waits for a frame infinitely
(not recommended).
If this value is zero it returns immediately.
Specific types:
typedef struct
{
void*
System;
UINT32
Flags;
UINT16
Id;
UINT8
*pData;
UINT32
Length;
UINT32HL
RxTime;
UINT32
BeginCycleTime;
UINT32
EndCycleTime;
UINT32
Reserved[2];
}FGFRAME;
FirePackage© - Documentation FireGrab
//
//
//
//
//
//
//
//
//
For system use only
Flags: Last, Invalid, no post etc...
Continuous ID
Data pointer
Buffers length
Receive time
Frame begin as bus time
Frame end as bus time
Reserved for future use
Page 59
Distributed by:
Type
Name
IO
Description
void*
System
Out
For system use only. Don‟t touch!
UINT32
Flags
Out/In
Field of single bit flags that hold additional information about
this frame:
FGF_INVALID
Data area may be corrupted or invalid.
FGF_LAST
This frame is the last in the „ready queue‟ (Next call to <GetFrame> will fail with FCE_NODATA or HALER_TIMEOUT).
FGF_DMAHALTED
Notifies the user that the DMA has been halted due to missing frame buffers before this frame has been caught by the
application.
FGF_FORCEPOST
See <PutFrame>.
UINT16
Id
Out
Identifier for this frame. Every time a frame is brought from
the „DMA queue‟ to the „ready queue‟ FireGrab stamps it with
a continuous identifier.
UINT8*
pData
Out
Pointer to image data.
This member is set to NULL when the driver sends a
frame start notification which can be enabled with the
parameter FGP_DMAFLAGS.
UINT32
Length
Out
Length of image data area in bytes.
UINT32HL
RxTime
Out
Receive time as 100ns ticks since 1.1.1601.
UINT32
BeginCycleTime
Out
When frame start events are active this is the bus time when
the frame start was detected (for bus time see remarks).
UINT32
EndCycleTime
Out
This is the bus time when the frame end was detected (for
bus time see remarks).
UINT32[2]
Reserved
---
Reserved.
Remarks:
Don‟t forget to return this frame after processing.
Under Windows the RxTime can be converted to actual time with standard Windows operating system
functions.
The 32 bit bus time has the following structure:
struct
{
UINT32
UINT32
UINT32
}BUSTIME;
CycleOffset : 12;
CycleCount : 13;
Second
: 7;
which is:
Bit[11..0] = Cycle Offset in parts of 1/3072 (=24.576 MHz)
Bit[24..12] = Cycle Count
Bit[31..25] = Second Count
FirePackage© - Documentation FireGrab
Page 60
Distributed by:
CFGIsoDma::PutFrame
C++-Syntax:
UINT32 PutFrame(FGFRAME *pFrame);
Description:
Returns a frame to the „DMA queue‟ and prepares it to receive new image data.
When the DMA is in limp mode this function, when called with a NULL parameter, pushes a
frame from the ‘standby queue’ to the ‘DMA queue’.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
Type
Name
IO
Description
FGFRAME*
pFrame
In
Pointer to a frame information structure that previously has been filled
up by calling <GetFrame>.
When the DMA is in limp mode this parameter can be NULL. If it‟s
NULL then one frame is moved from the „standby queue‟ to the „DMA
queue‟ and the DMA is started if it had entered halt state before.
Specific types:
typedef struct
{
void*
System;
UINT32
Flags;
UINT16
Id;
UINT8
*pData;
UINT32
Length;
UINT32
Reserved[6];
}FGFRAME;
FirePackage© - Documentation FireGrab
//
//
//
//
//
//
For system use only
Flags: Last, Invalid, no post etc...
Continous ID
Data pointer
Buffers length
Reserved for future use
Page 61
Distributed by:
Type
Name
IO
Description
void*
System
Out
For system use only. Don‟t touch!
UINT32
Flags
Out/In
Field of single bit flags that hold additional information about this
frame:
FGF_INVALID
Data area may be corrupted or invalid.
FGF_LAST
This frame is the last in the „ready queue‟ (Next call to <GetFrame> will fail> with FCE_NODATA or HALER_TIMEOUT).
FGF_FORCEPOST
When set and limp mode is active forces this frame to be returned directly to the „DMA queue‟ instead of the „standby
queue‟.
UINT16
Id
Out
Identifier of this frame. Every time a frame is brought from the
„DMA queue‟ to the „ready queue‟ FireGrab stamps it with a
continuous identifier.
UINT8*
pData
Out
Pointer to image data.
UINT32
Length
Out
Length of image data area in bytes.
UINT32[4]
Reserved
---
Reserved.
Remarks:
Every frame retrieved by calling <GetFrame> must be returned by calling <PutFrame>.
When the DMA is in limp mode a frame is put to the „standby queue‟ when calling <PutFrame>. You
must call <PutFrame> with a NULL argument to move a frame from the „standby queue‟ to the „DMA
queue‟.
Exception: You can force moving this frame directly to the „DMA queue‟ when limp mode is active by
asserting FGF_FORCEPOST in the Flags member of FGFRAME.
FirePackage© - Documentation FireGrab
Page 62
Distributed by:
CFGIsoDma::DiscardFrames
C++-Syntax:
UINT32 DiscardFrames();
Description:
Discards all received frames and brings the receive logic in the same state as it was when it was
opened.
When limp mode is inactive all frame buffers are brought to the „DMA queue‟ and are ready to receive
images.
When limp mode is active all frame buffers are brought to the „standby queue‟ and the DMA is halted.
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
None.
Specific types:
None.
Remarks:
None.
FirePackage© - Documentation FireGrab
Page 63
Distributed by:
CFGIsoDma::AssignUserBuffers
C++-Syntax:
UINT32 AssignUserBuffers(UINT32 Cnt,UINT32 Size,void* *ppMemArray);
Description:
This function allows assignment of user allocated memory for image acquisition. This function must be
called before <OpenCapture> is called. After the capture mechanism is closed with <CloseCapture>
the pushed buffers must be removed from the object with a call of this function with all parameters set
to 0 (see section remarks on this side).
Return Value:
0 (FCE_NOERROR) on success, error code otherwise.
Parameters:
Type
Name
IO
Description
UINT32
Cnt
In
Number of valid frame buffers that are contained in the array
specified by <ppMemArray>.
If 0 is specified all previously specified buffers are removed.
UINT32
Size
In
Size in bytes of each buffer specified in <ppMemArray>.
void**
ppMemArray
In
Pointer to an array of void-pointers specifying user defined memory areas for image acquisition.
If NULL is specified all previously specified buffers are removed.
Specific types:
None.
Remarks:
The explanation from <CFGCamera::AssignUserBuffers> also helps to understand this function.
FirePackage© - Documentation FireGrab
Page 64
Distributed by:
Parameter indices for Set/GetParameter
The <CFGCamera> supports several parameters that can be requested or modified. Some parameters are device dependant and are not supported by all devices.
Every parameter has a unique identifier that must be specified when calling <SetParameter>, <GetParameter> or <GetParameterInfo>.
The following chapters describe each parameter in detail.
FGP_IMAGEFORMAT
32 Bit value that specifies the image format of the image device.
There are two different approaches to specify the image format: General or DCAM.
General image format
In a very general manner the image format of an image device consists of the
 Image resolution (horizontal size and vertical size of the image in pixels)
 The color format of the image (Gray values, RGB, YUV etc.)
 The frame rate (frames/images delivered per second)
In order to be device independent we have the following enumerations for these parameters:
// Enumeration for resolutions
enum FG_RESOLUTION
{
RES_160_120=0,
RES_320_240,
RES_640_480,
RES_800_600,
RES_1024_768,
RES_1280_960,
RES_1600_1200,
RES_SCALABLE,
RES_LAST
};
Constant
Meaning
RES_160_120
Resolution of 160 by 120 pixels.
RES_320_240
Resolution of 320 by 240 pixels.
RES_640_480
Resolution of 640 by 480 pixels.
RES_800_600
Resolution of 800 by 600 pixels.
RES_1024_768
Resolution of 1024 by 768 pixels.
RES_1280_960
Resolution of 1280 by 960 pixels.
RES_1600_1200
Resolution of 1600 by 1200 pixels.
RES_SCALABLE
Freely scalable resolution.
// Enumeration for color modes
enum FG_COLORMODE
{
CM_Y8=0,
CM_YUV411,
CM_YUV422,
CM_YUV444,
CM_RGB8,
FirePackage© - Documentation FireGrab
Page 65
Distributed by:
CM_Y16,
CM_RGB16,
CM_SY16,
CM_SRGB16,
CM_RAW8,
CM_RAW16,
CM_LAST
};
Constant
Meaning
CM_Y8
Color format 8 Bit gray scale (Data: Y0 Y1 Y2 Y3 ...).
CM_YUV411
Color format 8 Bit YUV 411 (Data: U0 Y0 Y1 V0 Y2 Y3 U4 Y4 Y5 V4 Y6 Y7...).
CM_YUV422
Color format 8 Bit YUV 422 (Data: U0 Y0 V0 Y1 U2 Y2 V2 Y3 ...).
CM_YUV444
Color format 8 Bit YUV 444 (Data: U0 Y0 V0 U1 Y1 V1 ...).
CM_RGB8
Color format 8 Bit RGB (Data: R0 G0 B0 R1 G1 B1 ...).
CM_Y16
Color format 16 Bit gray scale (Data: Y0 Y1 Y2 ...).
CM_RGB16
Color format 16 Bit RGB (Data: R0 G0 B0 R1 G1 B1 ...).
CM_SY16
Color format signed 16 Bit gray scale (Data: Y0 Y1 Y2 ...).
CM_SRGB16
Color format signed 16 Bit RGB (Data: R0 G0 B0 R1 G1 B1 ...).
CM_RAW8
Raw color format 8 Bit sensor dependant.
CM_RAW16
Raw color format 16 Bit sensor dependant.
// Enumeration for frame rates
enum FG_FRAMERATE
{
FR_1_875=0,
FR_3_75,
FR_7_5,
FR_15,
FR_30,
FR_60,
FR_120,
FR_240,
FR_LAST
};
Constant
Meaning
FR_1_875
Frame rate is 1.875 images per second.
FR_3_75
Frame rate is 3.75 images per second.
FR_7_5
Frame rate is 7.5 images per second.
FR_15
Frame rate is 15 images per second.
FR_30
Frame rate is 30 images per second.
FR_60
Frame rate is 60 images per second.
FR_120
Frame rate is 120 images per second.
FR_240
Frame rate is 240 images per second.
With these constants and the help of a macro you can specify an image format in this way:
MAKEIMAGEFORMAT(Resolution,ColorFormat,FrameRate)
which could look like this for a standard VGA mode:
FirePackage© - Documentation FireGrab
Page 66
Distributed by:
SetParameter(FGP_IMAGEFORMAT,MAKEIMAGEFORMAT(RES_640_480,CM_Y8,FR_15));
The return value of this function call determines whether this mode is supported by the image device.
When the resolution is set to RES_SCALABLE then the last parameter for the macro does not specify
the frame rate as the frame rate in this mode definitely depends on the chosen image size and on the
packet size which can be set separately. Furthermore it specifies the DCAM mode the camera shall
run with (DCAM format is here set to 7 always).
When RES_SCALABLE is selected the initial image size is set to the maximum the camera supports.
It can be changed by the appropriate parameter calls of FGP_XSIZE and FGP_YSIZE.
When reading back the image format the retrieved 32 Bit value can be split into resolution, color format and frame rate with the following macros:
Resolution=IMGRES(ImageFormat);
ColorFormat=IMGCOL(ImageFormat);
FrameRate=IMGRATE(ImageFormat);
DCAM specification conform image format
The working mode of the camera also can be set by using the DCAM specified formats and modes.
This is done by specifying format, mode and frame rate.
With the help of a macro this looks like:
MAKEDCAMFORMAT(Format,Mode,FrameRate)
which could look like this for a standard mode:
SetParameter(FGP_IMAGEFORMAT,MAKEDCAMFORMAT(0,2,FR_7_5));
Please look into the DCAM specification for the standard format and modes.
When a partial scan format is selected (Format=7) the last parameter specifies the color format instead of the frame rate.
When reading back the image format the retrieved 32 Bit value can be split into format, mode and
frame rate with the following macros:
if(ISDCAMFORMAT(ImageFormat))
{
Format=DCAMFORMAT(ImageFormat);
Mode=DCAMMODE(ImageFormat);
FrameRate=DCAMRATE(ImageFormat);
}
Per default the camera initiates itself always with a general image format.
DCAM image formats must be selected manually.
FirePackage© - Documentation FireGrab
Page 67
Distributed by:
FGP_ENUMIMAGEFORMAT
This parameter helps to determine the available image formats for the connected camera by calling
<GetParameter> repeatedly until an error code unequal to FCE_NOERROR is returned.
First of all you must call <SetParameter> with parameter type FGP_ENUMIMAGEFORMAT to reset
image format enumeration.
Next you call <GetParameter> with parameter type FG_ENUMIMAGEFORMAT until an error code is
returned. Every call will return a supported image format. Every resolution, every color format and
every frame rate (and their combinations) lead to a single image format.
When calling <SetParameter(FGP_ENUMIMAGEFORMAT,Value)> the value determines whether
general image formats or DCAM formats will be enumerated.
When value=0 the general formats are enumerated.
When value=0x80000000 then DCAM formats are enumerated.
A loop that enumerates all available general image formats looks like this:
UINT32 Result,ImageFormat;
Camera.SetParameter(FGP_ENUMIMAGEFORMAT,0);
do
{
Result=Camera.GetParameter(FGP_ENUMIMAGEFORMAT,&ImageFormat);
if(Result==FCE_NOERROR)
{
// Image format is valid here
}
}while(Result==FCE_NOERROR;
A loop that enumerates all available DCAM formats looks like this:
UINT32 Result,ImageFormat;
Camera.SetParameter(FGP_ENUMIMAGEFORMAT,0x80000000);
do
{
Result=Camera.GetParameter(FGP_ENUMIMAGEFORMAT,&ImageFormat);
if(Result==FCE_NOERROR)
{
// DCAM format is valid here
}
}while(Result==FCE_NOERROR;
FirePackage© - Documentation FireGrab
Page 68
Distributed by:
FGP_BRIGHTNESS
This parameter controls the brightness of the image.
It is controlled by calling <SetParameter> and can be read back (if supported) by calling <GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
If the image device supports extended functionality the following special values might be used:
PVAL_OFF
No control of this parameter allowed. Parameter is switched back to manufacturers default value.
PVAL_AUTO
Parameter is continuously controlled automatically by the image device itself. A normal value write
switches the automatic mode off.
PVAL_ONESHOT
Parameter is adjusted automatically one time and can then be controlled manually again by writing
new values.
FirePackage© - Documentation FireGrab
Page 69
Distributed by:
FGP_AUTOEXPOSURE
This parameter controls the automatic exposure characteristic of the image.
It is controlled by calling <SetParameter> and can be read back (if supported) by calling <GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
If the image device supports extended functionality the following special values might be used:
PVAL_OFF
No control of this parameter allowed. Parameter is switched back to manufacturers default value.
PVAL_AUTO
Parameter is continuously controlled automatically by the image device itself. A normal value write
switches the automatic mode off.
PVAL_ONESHOT
Parameter is adjusted automatically one time and can then be controlled manually again by writing
new values.
FirePackage© - Documentation FireGrab
Page 70
Distributed by:
FGP_SHARPNESS
This parameter controls the sharpness of the image.
It is controlled by calling <SetParameter> and can be read back (if supported) by calling <GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
If the image device supports extended functionality the following special values might be used:
PVAL_OFF
No control of this parameter allowed. Parameter is switched back to manufacturers default value.
PVAL_AUTO
Parameter is continuously controlled automatically by the image device itself. A normal value write
switches the automatic mode off.
PVAL_ONESHOT
Parameter is adjusted automatically one time and can then be controlled manually again by writing
new values.
FirePackage© - Documentation FireGrab
Page 71
Distributed by:
FGP_WHITEBALCB
This parameter controls the UB component of the white balance of the image.
It is controlled by calling <SetParameter> and can be read back (if supported) by calling <GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
If the image device supports extended functionality the following special values might be used:
PVAL_OFF
No control of this parameter allowed. Parameter is switched back to manufacturer‟s default value.
PVAL_AUTO
Parameter is continuously controlled automatically by the image device itself. A normal value write
switches the automatic mode off.
PVAL_ONESHOT
Parameter is adjusted automatically one time and can then be controlled manually again by writing
new values.
The different modes are linked with the parameter FGP_WHITEBALCR.
FirePackage© - Documentation FireGrab
Page 72
Distributed by:
FGP_WHITEBALCR
This parameter controls the VR component of the white balance of the image.
It is controlled by calling <SetParameter> and can be read back (if supported) by calling <GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
If the image device supports extended functionality the following special values might be used:
PVAL_OFF
No control of this parameter allowed. Parameter is switched back to manufacturer‟s default value.
PVAL_AUTO
Parameter is continuously controlled automatically by the image device itself. A normal value write
switches the automatic mode off.
PVAL_ONESHOT
Parameter is adjusted automatically one time and can then be controlled manually again by writing
new values.
The different modes are linked with the parameter FGP_WHITEBALCB.
FirePackage© - Documentation FireGrab
Page 73
Distributed by:
FGP_HUE
This parameter controls the hue of the image.
It is controlled by calling <SetParameter> and can be read back (if supported) by calling <GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
If the image device supports extended functionality the following special values might be used:
PVAL_OFF
No control of this parameter allowed. Parameter is switched back to manufacturer‟s default value.
PVAL_AUTO
Parameter is continuously controlled automatically by the image device itself. A normal value write
switches the automatic mode off.
PVAL_ONESHOT
Parameter is adjusted automatically one time and can then be controlled manually again by writing
new values.
FirePackage© - Documentation FireGrab
Page 74
Distributed by:
FGP_SATURATION
This parameter controls the color saturation of the image.
It is controlled by calling <SetParameter> and can be read back (if supported) by calling <GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
If the image device supports extended functionality the following special values might be used:
PVAL_OFF
No control of this parameter allowed. Parameter is switched back to manufacturer‟s default value.
PVAL_AUTO
Parameter is continuously controlled automatically by the image device itself. A normal value write
switches the automatic mode off.
PVAL_ONESHOT
Parameter is adjusted automatically one time and can then be controlled manually again by writing
new values.
FirePackage© - Documentation FireGrab
Page 75
Distributed by:
FGP_GAMMA
This parameter controls the gamma correction of the image.
It is controlled by calling <SetParameter> and can be read back (if supported) by calling <GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
If the image device supports extended functionality the following special values might be used:
PVAL_OFF
No control of this parameter allowed. Parameter is switched back to manufacturer‟s default value.
PVAL_AUTO
Parameter is continuously controlled automatically by the image device itself. A normal value write
switches the automatic mode off.
PVAL_ONESHOT
Parameter is adjusted automatically one time and can then be controlled manually again by writing
new values.
FirePackage© - Documentation FireGrab
Page 76
Distributed by:
FGP_SHUTTER
This parameter controls the actual shutter time of the image.
It is controlled by calling <SetParameter> and can be read back (if supported) by calling
<GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
If the image device supports extended functionality the following special values might be used:
PVAL_OFF
No control of this parameter allowed. Parameter is switched back to manufacturer‟s default value.
PVAL_AUTO
Parameter is continuously controlled automatically by the image device itself. A normal value write
switches the automatic mode off.
PVAL_ONESHOT
Parameter is adjusted automatically one time and can then be controlled manually again by writing
new values.
Be aware that different manufacturers assign different meanings to the shutter value. The relationship between the value written and the real shutter time can be highly non- linear.
Please consult your camera manual.
FirePackage© - Documentation FireGrab
Page 77
Distributed by:
FGP_GAIN
This parameter controls the image pre-amplifiers gain.
It is controlled by calling <SetParameter> and can be read back (if supported) by calling <GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
If the image device supports extended functionality the following special values might be used:
PVAL_OFF
No control of this parameter allowed. Parameter is switched back to manufacturer‟s default value.
PVAL_AUTO
Parameter is continuously controlled automatically by the image device itself. A normal value write
switches the automatic mode off.
PVAL_ONESHOT
Parameter is adjusted automatically one time and can then be controlled manually again by writing
new values.
Be aware that different manufacturers assign different meanings to the value. The relationship
between the value written and the real gain can be highly non-linear.
Please consult your camera manual.
FirePackage© - Documentation FireGrab
Page 78
Distributed by:
FGP_IRIS
For cameras with motorized lenses this parameter controls the iris of the lens.
It is controlled by calling <SetParameter> and can be read back (if supported) by calling
<GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
If the image device supports extended functionality the following special values might be used:
PVAL_OFF
No control of this parameter allowed. Parameter is switched back to manufacturer‟s default value.
PVAL_AUTO
Parameter is continuously controlled automatically by the image device itself. A normal value write
switches the automatic mode off.
PVAL_ONESHOT
Parameter is adjusted automatically one time and can then be controlled manually again by writing
new values.
FirePackage© - Documentation FireGrab
Page 79
Distributed by:
FGP_FOCUS
For cameras with motorized lenses this parameter controls the focus of the lens.
It is controlled by calling <SetParameter> and can be read back (if supported) by calling
<GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
If the image device supports extended functionality the following special values might be used:
PVAL_OFF
No control of this parameter allowed. Parameter is switched back to manufacturer‟s default value.
PVAL_AUTO
Parameter is continuously controlled automatically by the image device itself. A normal value write
switches the automatic mode off.
PVAL_ONESHOT
Parameter is adjusted automatically one time and can then be controlled manually again by writing
new values.
FirePackage© - Documentation FireGrab
Page 80
Distributed by:
FGP_TEMPERATURE
This parameter controls the color temperature of the image.
It is controlled by calling <SetParameter> and can be read back (if supported) by calling
<GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
If the image device supports extended functionality the following special values might be used:
PVAL_OFF
No control of this parameter allowed. Parameter is switched back to manufacturer‟s default value.
PVAL_AUTO
Parameter is continuously controlled automatically by the image device itself. A normal value write
switches the automatic mode off.
PVAL_ONESHOT
Parameter is adjusted automatically one time and can then be controlled manually again by writing
new values.
FirePackage© - Documentation FireGrab
Page 81
Distributed by:
FGP_TRIGGER
This parameter controls complete trigger functionality of the connected image device.
It is controlled by calling <SetParameter> and can be read back (if supported) by calling
<GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
When calling <GetParameterInfo> the specific data area tells you what part of the extended trigger
information is supported. The following table shows what information is returned:
typedef struct
{
UINT32
UINT32
UINT32
UINT32
UINT32
UINT32
UINT32
UINT32
UINT32
UINT32
UINT32
UINT32
}FGPSTRIGGER;
ReadOutCap
: 1;
OnOffCap
: 1;
OnOffState
: 1;
PolarityCap
: 1;
PolarityState : 1;
ReadInputCap : 1;
InputState
: 1;
TriggerSrcCap : 8;
TriggerSrc
: 4;
TriggerModeCap: 16;
TriggerMode
: 4;
TriggerParameter : 12;
//
//
//
//
//
//
//
//
//
//
//
//
Value can be read
Switchable
On-State
Polarity capable
Polarity state
Input readable
Input state
Trigger source capabilities
Actual trigger source
Trigger mode capabilities
Actual Trigger mode
Actual trigger parameter
Type
Name
IO
Description
UINT32:1
ReadOutCap
Out
If set the trigger control register from the image device can be
read back.
UINT32:1
OnOffCap
Out
Trigger functionality can be switched OFF or ON.
UINT32:1
OnOffState
Out
Current state of trigger functionality (ON or OFF).
UINT32:1
PolarityCap
Out
If set then trigger polarity can be changed.
UINT32:1
PolarityState
Out
State of trigger polarity (0:low active, 1: high active).
UINT32:1
ReadInputCap
Out
If set then trigger input can be read back.
UINT32:1
InputState
Out
State of trigger input.
UINT32:8
TriggerSrcCap
Out
Bit field of trigger sources (every set bit from 0x80 to 0x01 tells
that the source 0...7 can be selected).
UINT32:4
TriggerSrc
Out
Currently selected trigger source.
UINT32:16
TriggerModeCap
Out
Bit field of trigger modes (every set bit from 0x8000 to 0x01
tells that the trigger mode 0...15 can be selected).
UINT32:4
TriggerMode
Out
Currently selected trigger mode.
UINT32:12
TriggerParameter
Out
Current trigger parameter.
The following macro helps to set the trigger value as a 32 Bit value:
MAKETRIGGER(On,Pol,Src,Mode,Parm);
When the parameter is read back the following helper macros are useful:
UINT32 TriggerValue;
Camera.GetParameter(FGP_TRIGGER,&TriggerValue);
FirePackage© - Documentation FireGrab
Page 82
Distributed by:
TRGON(TriggerValue), TRGPOL(TriggerValue), TRGSRC(TriggerValue), TRGMODE(TriggerValue),
TRGPARM(TriggerValue)
Example:
UINT32 nOn=1;
// 0=ext. trigger off, 1=ext. trigger on
UINT32 nPolarity=0; // 0=low active input, 1=high active input
UINT32 nSrc=0;
// not currently applicable to AVT cameras, as of February 2008
- parameter inherited from IIDC/DCAM
UINT32 nMode=0;
// 0=edge mode, 1=level mode, 15=bulk mode
UINT32 nParm=0;
// not currently applicable to AVT cameras, as of February 2008
- parameter inherited from IIDC/DCAM
UINT32 TriggerValue;
// Enable ext. trigger, edge mode (0), falling edge
TriggerValue=MAKETRIGGER(nOn, nPolarity, nSrc, nMode, nParm);
Camera.SetParameter(FGP_TRIGGER,TriggerValue);
// Enable ext. trigger, level mode (1), high active
nMode=1;
nPolarity=1;
TriggerValue=MAKETRIGGER(nOn, nPolarity, nSrc, nMode, nParm);
Camera.SetParameter(FGP_TRIGGER,TriggerValue);
// Enable ext. trigger, bulk mode (15), rising edge, combined with MultiShot counter NMULTI
UINT32 nCnt=NMULTI; // multi shot counter
nMode=15;
nPolarity=1;
TriggerValue=MAKETRIGGER(nOn, nPolarity, nSrc, nMode, nParm);
Camera.SetParameter(FGP_TRIGGER,TriggerValue);
Camera.SetParameter(FGP_BURSTCOUNT,nCnt);
// Get current trigger mode
Camera.GetParameter(FGP_TRIGGER,&TriggerValue);
nOn=TRGON(TriggerValue);
nPolarity=TRGPOL(TriggerValue);
nSrc=TRGSRC(TriggerValue);
nMode=TRGMODE(TriggerValue);
nParm=TRGPARM(TriggerValue);
FirePackage© - Documentation FireGrab
Page 83
Distributed by:
FGP_TRIGGERDLY
This parameter controls the trigger delay (see DCAM specification).
It is controlled by calling <SetParameter> and can be read back (if supported) by calling <GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
If the image device supports extended functionality the following special values might be used:
PVAL_OFF
No control of this parameter allowed. Parameter is switched back to manufacturer‟s default value.
PVAL_AUTO
Parameter is continuously controlled automatically by the image device itself. A normal value write
switches the automatic mode off.
PVAL_ONESHOT
Parameter is adjusted automatically one time and can then be controlled manually again by writing
new values.
FirePackage© - Documentation FireGrab
Page 84
Distributed by:
FGP_WHITESHD
This parameter controls the white shade of the image (see DCAM specification).
It is controlled by calling <SetParameter> and can be read back (if supported) by calling
<GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
If the image device supports extended functionality the following special values might be used:
PVAL_OFF
No control of this parameter allowed. Parameter is switched back to manufacturer‟s default value.
PVAL_AUTO
Parameter is continuously controlled automatically by the image device itself. A normal value write
switches the automatic mode off.
PVAL_ONESHOT
Parameter is adjusted automatically one time and can then be controlled manually again by writing
new values.
FirePackage© - Documentation FireGrab
Page 85
Distributed by:
FGP_FRAMERATE
This parameter is DCAM compliant but normally does nothing (see DCAM specification).
It is controlled by calling <SetParameter> and can be read back (if supported) by calling
<GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
If the image device supports extended functionality the following special values might be used:
Normally the frame rate is controlled by FGP_IMAGEFORMAT and/or FGP_PACKETSIZE.
PVAL_OFF
No control of this parameter allowed. Parameter is switched back to manufacturer‟s default value.
PVAL_AUTO
Parameter is continuously controlled automatically by the image device itself. A normal value write
switches the automatic mode off.
PVAL_ONESHOT
Parameter is adjusted automatically one time and can then be controlled manually again by writing
new values.
FirePackage© - Documentation FireGrab
Page 86
Distributed by:
FGP_ZOOM
For cameras with motorized lenses this parameter controls the zoom of the lens.
It is controlled by calling <SetParameter> and can be read back (if supported) by calling <GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
If the image device supports extended functionality the following special values might be used:
PVAL_OFF
No control of this parameter allowed. Parameter is switched back to manufacturer‟s default value.
PVAL_AUTO
Parameter is continuously controlled automatically by the image device itself. A normal value write
switches the automatic mode off.
PVAL_ONESHOT
Parameter is adjusted automatically one time and can then be controlled manually again by writing
new values.
FirePackage© - Documentation FireGrab
Page 87
Distributed by:
FGP_PAN
When the sensor is larger than the current image size or a motorized lens is connected this parameter
controls the pan of the connected image device.
It is controlled by calling <SetParameter> and can be read back (if supported) by calling
<GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
If the image device supports extended functionality the following special values might be used:
PVAL_OFF
No control of this parameter allowed. Parameter is switched back to manufacturer‟s default value.
PVAL_AUTO
Parameter is continuously controlled automatically by the image device itself. A normal value write
switches the automatic mode off.
PVAL_ONESHOT
Parameter is adjusted automatically one time and can then be controlled manually again by writing
new values.
FirePackage© - Documentation FireGrab
Page 88
Distributed by:
FGP_TILT
When the sensor is larger than the current image size or a motor lens is connected this parameter
controls the tilt of the connected image device.
It is controlled by calling <SetParameter> and can be read back (if supported) by calling
<GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
If the image device supports extended functionality the following special values might be used:
PVAL_OFF
No control of this parameter allowed. Parameter is switched back to manufacturer‟s default value.
PVAL_AUTO
Parameter is continuously controlled automatically by the image device itself. A normal value write
switches the automatic mode off.
PVAL_ONESHOT
Parameter is adjusted automatically one time and can then be controlled manually again by writing
new values.
FirePackage© - Documentation FireGrab
Page 89
Distributed by:
FGP_OPTICALFILTER
This parameter controls an electronic or real optical filter connected to the image device.
It is controlled by calling <SetParameter> and can be read back (if supported) by calling
<GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
If the image device supports extended functionality the following special values might be used:
PVAL_OFF
No control of this parameter allowed. Parameter is switched back to manufacturer‟s default value.
PVAL_AUTO
Parameter is continuously controlled automatically by the image device itself. A normal value write
switches the automatic mode off.
PVAL_ONESHOT
Parameter is adjusted automatically one time and can then be controlled manually again by writing
new values.
FirePackage© - Documentation FireGrab
Page 90
Distributed by:
FGP_CAPTURESIZE
This parameter exists for DCAM compatibility but mostly has no meaning.
It is controlled by calling <SetParameter> and can be read back (if supported) by calling
<GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
If the image device supports extended functionality the following special values might be used:
PVAL_OFF
No control of this parameter allowed. Parameter is switched back to manufacturer‟s default value.
PVAL_AUTO
Parameter is continuously controlled automatically by the image device itself. A normal value write
switches the automatic mode off.
PVAL_ONESHOT
Parameter is adjusted automatically one time and can then be controlled manually again by writing
new values.
FirePackage© - Documentation FireGrab
Page 91
Distributed by:
FGP_CAPTUREQUALITY
This parameter exists for DCAM compatibility but mostly has no meaning.
It is controlled by calling <SetParameter> and can be read back (if supported) by calling
<GetParameter>.
Call <GetParameterInfo> to retrieve the allowed range and the stepping unit for this parameter.
Depending on the connected image device this parameter might be inaccessible or not supported.
If the image device supports extended functionality the following special values might be used:
PVAL_OFF
No control of this parameter allowed. Parameter is switched back to manufacturer‟s default value.
PVAL_AUTO
Parameter is continuously controlled automatically by the image device itself. A normal value write
switches the automatic mode off.
PVAL_ONESHOT
Parameter is adjusted automatically one time and can then be controlled manually again by writing
new values.
FirePackage© - Documentation FireGrab
Page 92
Distributed by:
FGP_PHYSPEED
This parameter controls the real physical speed that is used to talk with the connected image device,
asychronously and isochronically. Concerning isochronous transfers, it may be set any time before the
start.
Allowed values are:
SPEED100, SPEED200, SPEED400 and SPEED800.
Some constructions require long cables and therefore need to limit the communication speed between
the PC and the FireWire device. In this case, it is important to set this parameter before calling <Connect>. Otherwise the connect function will fail.
FirePackage© - Documentation FireGrab
Page 93
Distributed by:
FGP_XSIZE
This parameter is the horizontal image size in pixels.
When a scalable mode is selected (i.e. RES_SCALABLE or format 7 is part of the image format) the
horizontal size of the image transferred from the camera to the PC can be adjusted by changing the
value of this parameter.
The value of this parameter is always checked against the current limits given by the mode the camera is utilizing.
Use <GetParameterInfo> to get more information about minimum value, maximum value and stepping
size.
When the specified value is out of range the value for XSize and XPosition are adjusted to acceptable
values. Don't miss to adapt FGP_PACKETSIZE after setting this parameter.
To set an Area Of Interest keep this order:
Select RES_SCALABLE
Set FGP_XSIZE
Set FGP_YSIZE
Set FGP_PACKETSIZE
Call OpenCapture
FirePackage© - Documentation FireGrab
Page 94
Distributed by:
FGP_YSIZE
This parameter is the vertical image size in pixels.
When a scalable mode is selected (i.e. RES_SCALABLE or format 7 is part of the image format) the
vertical size of the image transferred from the camera to the PC can be adjusted by changing the
value of this parameter.
The value of this parameter is always checked against the current limits given by the mode the camera is utilizing.
Use <GetParameterInfo> to get more information about minimum value, maximum value and stepping
size.
When the specified value is out of range the value for YSize and YPosition are adjusted to acceptable
values. Don't miss to adapt FGP_PACKETSIZE after setting this parameter.
FirePackage© - Documentation FireGrab
Page 95
Distributed by:
FGP_XPOSITION
This parameter is the horizontal image position in pixels within the sensors image range.
When a scalable mode is selected (i.e. RES_SCALABLE or format 7 is part of the image format) the
horizontal position of the image transferred from the camera to the PC can be adjusted by changing
the value of this parameter.
The value of this parameter is always checked against the current limits given by the mode the camera is utilizing.
Use <GetParameterInfo> to get more information about minimum value, maximum value and stepping
size.
When the specified value is out of range the value for XSize and XPosition are adjusted to acceptable
values.
FirePackage© - Documentation FireGrab
Page 96
Distributed by:
FGP_YPOSITION
This parameter is the vertical image position in pixels within the sensors image range.
When a scalable mode is selected (i.e. RES_SCALABLE or format 7 is part of the image format) the
vertical position of the image transferred from the camera to the PC can be adjusted by changing the
value of this parameter.
The value of this parameter is always checked against the current limits given by the mode the camera is utilizing.
Use <GetParameterInfo> to get more information about minimum value, maximum value and stepping
size.
When the specified value is out of range the value for YSize and YPosition are adjusted to acceptable
values.
FirePackage© - Documentation FireGrab
Page 97
Distributed by:
FGP_PACKETSIZE
This parameter adjusts the size of the packets that are transferred from the camera to the PC every
125 µs (Isochronous cycle time, see also Image Transfer).
This parameter can only be changed if RES_SCALABLE or format 7 is part of the image format. Otherwise for each standard DCAM mode the packet size is a fixed parameter and can only be read back.
The packet size directly influences the frame rate in all scalable modes and also the bus load on the
FireWire bus.
Keep in mind, that one isochronous packet is transferred each 125 us and that there is only space for
approximately 4800 bytes of isochronous transmission per isochronous cycle.
If a scalable mode is selected the frame rate can directly be calculated by the number of bytes for an
image and the packet size.
BYTE_PER_PACKET = fps * AoiWidth * AoiHEIGHT * ByteDepth * 125μs
Example:
CFGCamera
FGPINFO
UINT32
Camera;
XSize, YSize, PacketSize;
Result, Value;
// Get ImageFormat
Result=Camera.GetParameter(FGP_IMAGEFORMAT,&Value);
Result=Camera.GetParameterInfo(FGP_XSIZE,&XSize);
Result=Camera.GetParameterInfo(FGP_YSIZE,&YSize);
// Change ImageFormat of the camera
if(IMGRES(Value)==RES_SCALABLE)
{
// Set XSize
do
{
printf("Set XSize %i...%i [%i]: ", XSize.MinValue, XSize.MaxValue, XSize.Unit);
scanf("%i", &XSize.IsValue);
Result=Camera.SetParameter(FGP_XSIZE, XSize.IsValue);
if(Result==FCE_ADJUSTED)
Result=FCE_NOERROR;
}while(Result!=FCE_NOERROR);
// Set YSize
do
{
printf("Set YSize %i...%i [%i]: ", YSize.MinValue, YSize.MaxValue, YSize.Unit);
scanf("%i", &YSize.IsValue);
Result=Camera.SetParameter(FGP_YSIZE, YSize.IsValue);
if(Result==FCE_ADJUSTED)
Result=FCE_NOERROR;
}while(Result!=FCE_NOERROR);
// Adapt PacketSize
do
{
// Get PacketSize range
Result=Camera.GetParameterInfo(FGP_PACKETSIZE,&PacketSize);
printf("Set PacketSize %i...%i [%i]: ",PacketSize.MinValue, PacketSize.MaxValue, PacketSize.Unit);
scanf("%i", &PacketSize.IsValue);
// Set PacketSize
Result=Camera.SetParameter(FGP_PACKETSIZE, PacketSize.IsValue);
if(Result==FCE_ADJUSTED)
Result=FCE_NOERROR;
}while(Result!=FCE_NOERROR);
// Get current AOI Settings
Result=Camera.GetParameterInfo(FGP_PACKETSIZE,&PacketSize);
Result=Camera.GetParameterInfo(FGP_XSIZE,&XSize);
FirePackage© - Documentation FireGrab
Page 98
Distributed by:
Result=Camera.GetParameterInfo(FGP_YSIZE,&YSize);
printf("%ix%i Packetsize %i %ifps\n", XSize.IsValue, YSize.IsValue, PacketSize.IsValue,
PacketSize.IsValue*8000/XSize.IsValue/YSize.IsValue);
}
// Start DMA logic
Result=Camera.OpenCapture();
FirePackage© - Documentation FireGrab
Page 99
Distributed by:
FGP_DMAMODE
This parameter changes the mode the capture logic on the PC side runs in. For a detailed explanation
also see DMA modes.
The default mode is DMA_CONTINOUS.
The DMA mode must be set before calling <OpenCapture>.
Three predefined values are allowed:
DMA_CONTINOUS
All initially allocated frames are prepared for reception. When a complete image has been received it
is put to a queue and waits for processing by the application. If all frames are used up the DMA is
halted and restarted again, when the application returns frame buffers.
DMA_LIMP
All initially allocated frames are in standby mode and not ready for reception. The application readies a
frame buffer by pushing it to the DMA (call <PutFrame> with a NULL pointer). When the frame buffer
is filled it is given to the application and the DMA is halted again.
DMA_REPLACE
This mode is very similar to DMA_CONTINOUS with the exception, that when the receive logic is out
of frame buffers it steals buffers from the buffer queue that wait for application processing. So the
DMA is never halted and the queue that keeps readied buffers always contains the most recent frame
buffers.
FirePackage© - Documentation FireGrab
Page 100
Distributed by:
FGP_BURSTCOUNT
This parameter determines the number of frames that are sent by the image device after the function
<StartDevice> has been called.
The default value is BC_INFINITE which means, the image device sends images continuously.
For one shot mode this must be set to 1.
For multi shot this must be set to N (N=number of images to receive).
Not all devices support one-shot or/and multi-shot.
FirePackage© - Documentation FireGrab
Page 101
Distributed by:
FGP_FRAMEBUFFERCOUNT
Number of frame buffers that shall be allocated when <OpenCapture> is called.
Per default this value is set to 16.
FirePackage© - Documentation FireGrab
Page 102
Distributed by:
FGP_USEIRMFORBW
This parameter determines whether the packet size used for image transfer shall be registered with
the isochronous resource manager.
This value is active by default (register bandwidth).
If this parameter is set to active (unequal to zero), <OpenCapture> registers the used packet size with
the isochronous resource manager. If there is not enough bandwidth left, this function fails.
If this parameter is set to zero, the used bandwidth is not registered.
FirePackage© - Documentation FireGrab
Page 103
Distributed by:
FGP_ADJUSTPARAMETERS
This parameter determines, whether parameters that are specified for some functions are internally
adjusted (Error FCE_ADJUSTED is returned) or just will fail without touching internal values.
Short example: If you specify an image width of 1000 having a camera that only supports 640 then this
parameter is adjusted to 640 when FGP_ADJUSTRPARAMETERS is active. Otherwise it will be
stopped and FCE_INPARMS is returned.
This value is active by default (parameters ARE adjusted).
The value is either 0 (not active) or 1 (active.
FirePackage© - Documentation FireGrab
Page 104
Distributed by:
FGP_STARTIMMEDIATELY
When the camera burst count parameter (that is how many images are transferred when a trigger has
occured) is not set to BC_INFINITE, this parameter determines whether a single call to <StartDevice>
triggers the camera immediately or at the second call (value is 1). The default is set to 1 so when calling <StartDevice> the device is triggered immediately.
This value is active by default.
The value range is either 0 (trigger camera at second call to <StartDevice>) or 1 (trigger also at first
call to <StartDevice>).
FirePackage© - Documentation FireGrab
Page 105
Distributed by:
FGP_FRAMEMEMORYSIZE
This is just an informational parameter and returns the size of one complete image in bytes. Setting
this parameter has no effect.
FirePackage© - Documentation FireGrab
Page 106
Distributed by:
FGP_COLORFORMAT
This is just an informational parameter and returns the currently selected color format as defined by
CM_xxx. Setting this parameter has no effect.
FirePackage© - Documentation FireGrab
Page 107
Distributed by:
FGP_IRMFREEBW
This is just an informational parameter and returns the remaining available bandwidth on the FireWire
bus as it is reported by the isochronous resource manager.
After a bus reset this resource is set to 4915 which is a multiple of 20 ns and stands for the maximum
time available for isochronous communication during one isochronous cycle (roughly
4915 x 20 ns = 98,3 µs). Every isochronous transmitter must register its used bandwidth at this register. This function returns the still available bandwidth on the bus this camera resides on.
If the parameter FGP_USEIRMFORBW the used bandwidth for a specific camera is registered when
the function <OpenCapture> is called.
FirePackage© - Documentation FireGrab
Page 108
Distributed by:
FGP_DO_FASTTRIGGER
This is an alternative call to <StartDevice> when <StartDevice> has already been called once and the
device is already started. It is much faster than <StartDevice> as it does not wait for the answer of the
camera (no ACK, no response detection). It is helpful for simultaneous trigger of several devices that
are not placed on the same bus.
FirePackage© - Documentation FireGrab
Page 109
Distributed by:
FGP_DO_BUSTRIGGER
This re-triggers all devices on the same bus. It is a broadcast command that writes to the cameras‟
one-shot/multi-shot register.
FirePackage© - Documentation FireGrab
Page 110
Distributed by:
FGP_RESIZE
This parameter starts (Value=1) and stops (Value=0) a resize operation.
When a camera runs in a scalable video mode it is often required to rescale the image without restarting the DMA or the camera. Resizing the image within the camera is just a matter of writing new parameters to the appropriate registers. Resizing the DMA (which means set another packet payload
and another number of packets per frame) is a little more complicated.
When calling with a value of 1 a resize process begins. After writing a 1 to this parameter the camera
and the DMA are still running normally and you can change one of the following parameters that are
stored in an intermediate buffer:





FGP_XPOSITION
FGP_XSIZE
FGP_YPOSITION
FGP_YSIZE
FGP_PACKETSIZE
After setting one ore more of these parameters you must set FGP_RESIZE to the value 0. This starts
the real resize process:
 the camera is halted (if running continuously)
 the DMA is resized (fast resize operation)
 the camera is started again
Remember: You can only resize in a manner that the packet size and the number of packets
transmitted per frame shrink in comparison to the packet size and the number of packets per
frame when the DMA was started (OpenCapture).
Example: If you run the camera with a packet size of 2048 bytes and 256 packets per frame you can
resize to 1800 bytes per packet and 254 packets but NOT to 2050 bytes per packet or 258 packets.
FirePackage© - Documentation FireGrab
Page 111
Distributed by:
FGP_USEIRMFORCHN
Determines whether to use the isochronous resource manager for allocating the isochronous channel
the camera runs on or to use the isochronous channel that was set with FGP_ISOCHANNEL.
FirePackage© - Documentation FireGrab
Page 112
Distributed by:
FGP_CAMACCEPTDELAY
After some register writes on camera registers the system wait and lets the camera device process
data. This time by default is set to 3 milliseconds. You can change this value by this function. The
value is given in milliseconds.
FirePackage© - Documentation FireGrab
Page 113
Distributed by:
FGP_ISOCHANNEL
This parameter sets the isochronous channel that shall be used by the camera. To make this parameter become effective you must set FGP_USEIRMFORCHN to 0.
FirePackage© - Documentation FireGrab
Page 114
Distributed by:
FGP_CYCLETIME
This parameter returns the actual bus time in the following format:
struct
{
UINT32
UINT32
UINT32
}BUSTIME;
CycleOffset : 12;
CycleCount : 13;
Second
: 7;
or also
Bit[11..0] = Cycle Offset in parts of 1/3072 (=24.576 MHz)
Bit[24..12] = Cycle Count
Bit[31..25] = Second Count
This parameter is read only.
FirePackage© - Documentation FireGrab
Page 115
Distributed by:
FGP_DORESET
If the camera supports hardware reset as specified for the standard CSR register set this parameter
does a hardware reset. Not all cameras support hardware reset.
FirePackage© - Documentation FireGrab
Page 116
Distributed by:
FGP_DMAFLAGS
To support individual settings especially for error checking for each isochronous receive DMA you can
call this function so set these flags. By default all flags are set to Zero.
When one of the check-flags are active, every packet header from each isochronous packet is written
to a separate memory area and is checked by CPU at the end of each completely received frame. Be
aware that this takes some processing power from your system and should be disabled on slow systems
The following flags exist:
DMAF_CHECKSYNC
When this flags is active every frame is checked for a second packet that has an active sync field. This
should never happen as long as there are no packets missing within one frame.
DMAF_CHECKCYCLE
When this flag is active the driver checks whether all isochronous packets of a frame have been received in continuous isochronous cycles. This reliably detects all dropped packets within one frame.
DMAF_CHECKLENGTH
When this flag is active the driver checks the length of each packet of a frame.
DMAF_FRAMESTART
When this flag is active the driver gives you a notification at the start of each frame. The notification
comes as a normal frame notification but when reading the frame with <CFGCamera::GetFrame> the
returned structure will have a <pData> member that is set to NULL.
The specified parameter value is 0 or a combination of these flags.
Since FirePackage2v33 two additional flags are supported:
DMAF_CONTEXTISEVT
If this flag is set when the OpenCapture function is called, the „NotifyContext‟ member of the open
argument specifies a Windows event which is set (SetEvent) when an event occurs on this DMA. This
allows independent DMA handling for each DMA instance.
DMAF_CONTEXTISCB
If this flag is set when the OpenCapture function is called, the „NotifyContext‟ member of the open
argument specifies a callback function which is called every time an event occurs on this DMA. This
allows independent DMA handling for each DMA instance.
FirePackage© - Documentation FireGrab
Page 117
Distributed by:
FGP_R0C
This parameter is used to install a fast write quadlet call gate for a firewire device. The call gate can be
called from another kernel mode driver on ring 0 and primarily serves to implement a fast software
trigger mechanism.
When the function <CCamera::GetParameterInfo> is called with this index (FGP_R0C) the function
returns the following structure within the FGPSPECIFIC part:
typedef struct
{
void*
void*
}FGPSR0C;
// Ring 0 call gate parameter
pF;
pN;
<pF> is a pointer to a function that is declared as follows:
UINT32 __stdcall WriteQuad(NODEDSC *pNode,UINT32 Addr,UINT32 Quad,UINT8 Speed);
<pN> is a context that must be give to the upper function as the first argument.
The function writes a quadlet to the camera device for which this function was called. <Speed> can be
either SPEED100, SPEED200, SPEED400, SPEED800 or AUTOSPEED (0xFF).
If you want to write a quadlet to a camera, <pF> can be casted as follows:
typedef UINT32 (__stdcall *PFCT)( NODEDSC *pNode,UINT32 Addr,UINT32 Quad,UINT8 Speed);
UINT32 Result;
Result=((PFCT)pF)(pN,0xF0000624,0x12345678);
The following steps must be taken to allow another kernel mode driver to call this call gate:
 An application opens the FireGrab interface as usual
 An object CCamera is created
 The object is connected with a real camera (CCamera::Connect)
 CCamera::GetParameterInfo must be called with FGP_R0C. The call returns:
- The address of a function (pF)
- A context that must be specified when the upper function is called (pN)
 As long as the CCamera object lives the call gate can be called, even when the outside camera is disconnected
 When the CCamera object is destroyed, the call gate becomes invalid
FirePackage© - Documentation FireGrab
Page 118
Distributed by:
FGP_BUSADDRESS
This parameter is read only and returns the PCI bus address of the card the object is currently connected to and also the firewire port to which the camera is connected. The returned UINT32 value is
split into several bits according to the following scheme:
Bit[7..0] = Firewire port (starting from 0)
Bit[15..8] = PCI function number
Bit[23..16] = PCI device address
Bit[31..24] = PCI bus address
Or in C-Style:
typedef union
{
struct
{
UINT32
UINT32
UINT32
UINT32
};
UINT32
}FGBUSADDRESS;
Port
PCIFunction
PCIDevice
PCIBus
:
:
:
:
8;
8;
8;
8;
AsUINT32;
FirePackage© - Documentation FireGrab
Page 119
Distributed by:
FGP_CMDTIMEOUT
This parameter specifies the communication timeout between PC and camera for all read/write accesses. The value is specified in multiples of milliseconds. By default this value is set to 2000 ms.
FirePackage© - Documentation FireGrab
Page 120
Distributed by:
FGP_CARD
This parameter specifies the card that shall be used to connect this object to a physical camera. Normally the camera will only be connected to one interface from your PC. But sometimes if high speed
communication is needed and one camera is connected to multiple cards it might be interesting to
specify the card number that shall be used.
This parameter must be set before CFGCamera::Connect is called otherwise it will be ignored. If not
set the library always uses the first card found having a connection to the specified camera.
If no card number shall be set this value must be specified as 0xFF.
FirePackage© - Documentation FireGrab
Page 121
Distributed by:
FGP_LICENSEINFO
This parameter is read only and returns the current licensing mode your application is using. The following defines exist and one of them is returned in *pValue:
#define
#define
#define
#define
#define
#define
#define
#define
HALLT_NOLICENSE
HALLT_CARDGUID
HALLT_HARDDISK
HALLT_ETHERNET
HALLT_VENDOR
HALLT_DATELIMITED
HALLT_DEVICE
HALLT_FRAMELIMITED
0
1
2
3
4
5
6
7
FirePackage© - Documentation FireGrab
/*
/*
/*
/*
/*
/*
/*
/*
No license */
Firewire card */
Hard disk */
Ethernet adapter */
Vendor global */
Expires with date */
Device specific */
Limited by frames */
Page 122
Distributed by:
FGP_PACKETCOUNT
This parameter is read only and returns the number of packets used for transmission of a single
frame.
Example: If your image is1024x1024 in size and uses RAW-8 as colour format and each packet sent
is 512 in size the packet count returned is 2048.
FirePackage© - Documentation FireGrab
Page 123
Distributed by:
FGP_DO_MULTIBUSTRIGGER
This parameter is write-only and sends a trigger command on all buses on all cards that are present
within the system.
The parameter value is a bit mask that determines which cards shall be included or excluded. Every
bit set with this mask includes the card with the index that corresponds to the bit number.
Example: SetParameter(FGP_DO_MULTIBUSTRIGGER,0x000000101) sends a trigger command to
card 0 and card 8.
The camera object used for this global trigger must be up and running. The kind of trigger sent is
specified by the acquisition mode the camera is in. If the camera is in continuous mode, a continuous
trigger command is sent. Otherwise a trigger command for a defined number of images is sent.
FirePackage© - Documentation FireGrab
Page 124
Distributed by:
FGP_CARDRESET
This write-only parameter re-initializes the 1394 chip of the Firewire adapter card (bus) to which the
camera is connected. The value parameter is ignored. This also causes a bus-reset and can change
device states for other connected 1394 devices.
If this parameter is set on a camera that is NOT connected to a physical camera this function performs
a BusReset on the card with the number specified by „value‟.
Example: SetParameter(FGP_CARDRESET,x) performs a bus reset on the bus the selected camera
object is connected to. In case of Firewire adapter cards with multiple buses other buses are not affected by this command.
FirePackage© - Documentation FireGrab
Page 125
Distributed by:
Error codes returned by functions
Every function returns a 32 Bit error code that contains additional information about the error.
The module differs between upper layer error codes (that start with FCE_xxx) and low level error
codes that start with (HALER_xxx).
The following two tables show the coding and describes each error.
HALER_xxx codes
Name
#
Meaning
HALER_NOERROR
0
No error.
HALER_NOCARD
1
No hardware found.
2
No logical device could be created for the card (memory problem).
HALER_NOMEM
3
Not enough memory for this operation.
HALER_MODE
4
Wrong mode for this operation.
HALER_TIMEOUT
5
Timeout occurred.
HALER_ALREADYSTARTED
6
Device was already started and cannot be started twice.
HALER_NOTSTARTED
7
Device was not started.
HALER_BUSY
8
Device is busy at present.
HALER_NORESOURCES
9
Not enough resources (no more interrupts, no threads etc.).
HALER_NODATA
10
There is no data to acquire.
HALER_NOACK
11
No acknowledge received from the target.
HALER_NOIRQ
12
Expected an interrupt but there was none.
HALER_NOBUSRESET
13
Expected a firewire bus reset but there was none.
HALER_NOLICENSE
14
No license to perform this action.
HALER_RCODEOTHER
15
Response code of target for actual requested subaction other
then RCODE_COMPLETE (response code is also returned).
HALER_PENDING
16
Something has been started and is in a pending state.
HALER_INPARMS
17
Error in input parameter (mostly range error).
HALER_CHIPVERSION
18
Wrong chip version for this function.
HALER_HARDWARE
19
Hardware error.
HALER_NOTIMPLEMENTED
20
Function is not implemented.
HALER_CANCELLED
21
A waiting function was cancelled by another user call.
HALER_NOTLOCKED
22
A device is unlocked and needs to be locked for this action.
HALER_GENERATIONCNT
23
A function for asynchronous communication was called after a
bus reset without having called <FCTLGetBusInfo> in order to
get the new addresses of all existing nodes.
HALER_NOISOMANAGER
24
Function requires an isochronous resource manager but there
is none.
HALER_NOBUSMANAGER
25
Function requires a bus manager but there is none.
HALER_UNEXPECTED
26
Internal processing error, unexpected value detected.
HALER_NONTDEVICE
FirePackage© - Documentation FireGrab
Page 126
Distributed by:
Name
#
Meaning
HALER_REMOVED
27
Target for command was removed.
HALER_NOBUSRESOURCES
28
Either no isochronous channel or isochronous bandwidth available.
HALER_DMAHALTED
29
An isochronous receive DMA has been halted.
FCE_xxx codes
Name
#
Description
FCE_NOERROR
0
No error
FCE_ALREADYOPENED
1001
Device is already open and cannot be opened twice.
FCE_NOTOPENED
1002
Device must be opened before.
FCE_NODETAILS
1003
No details for this error
FCE_DRVNOTINSTALLED
1004
Kernel mode driver not installed.
FCE_MISSINGBUFFERS
1005
Not enough buffers for the requested isochronous communication.
FCE_INPARMS
1006
Error in input parameters (mostly range error).
FCE_CREATEDEVICE
1007
Error creating a logical device to connect to the kernel mode
driver.
FCE_WINERROR
1008
Internal windows error.
FCE_IOCTL
1009
Error while calling kernel mode driver.
FCE_DRVRETURNLENGTH
1010
Data returned from kernel mode driver has wrong length (version problem).
FCE_INVALIDHANDLE
1011
Handle has invalid value.
FCE_NOTIMPLEMENTED
1012
Function is not implemented.
FCE_DRVRUNNING
1013
Kernel mode driver runs already.
FCE_STARTERROR
1014
Kernel mode driver could not be started.
FCE_INSTALLERROR
1015
Kernel mode driver could not be installed.
FCE_DRVVERSION
1016
Wrong version of kernel mode driver.
FCE_NODEADDRESS
1017
Error in node address specified.
FCE_PARTIAL
1018
User supplied buffer was only filled partially (buffer was too
small).
FCE_NOMEM
1019
Not enough memory for this request.
FCE_NOTAVAILABLE
1020
The requested function is not available.
FCE_NOTCONNECTED
1021
The object is not connected to a real target.
FCE_ADJUSTED
1022
One of the parameters had to be adjusted.
FirePackage© - Documentation FireGrab
Page 127
Distributed by:
Error flags in global error field
Error codes are returned when a function is called. Error flags are something different. During processing in the background there is a potential risk that an error occurs. This error can not be assigned
to any function. So these are handled by the error flags. One or more error flags are set when an error
occurs and are stored within a 32 Bit bit field.
When an application wants to be notified this bit field is posted to the application with an
WPARAM_ERROR message. In the 32 Bit bit field each bit has a specific meaning. The following
table shows the bit values and explains their meaning.
HALERF_xxx
Name
Value
Description
HALERF_RXHLTISO0
0x00000001
Isochronous RXDMA0 had to be stopped.
HALERF_RXHLTISO1
0x00000002
Isochronous RXDMA1 had to be stopped.
HALERF_RXHLTISO2
0x00000004
Isochronous RXDMA2 had to be stopped.
HALERF_RXHLTISO3
0x00000008
Isochronous RXDMA3 had to be stopped.
HALERF_RXHLTISO4
0x00000010
Isochronous RXDMA4 had to be stopped.
HALERF_RXHLTISO5
0x00000020
Isochronous RXDMA5 had to be stopped.
HALERF_RXHLTISO6
0x00000040
Isochronous RXDMA6 had to be stopped.
HALERF_RXHLTISO7
0x00000080
Isochronous RXDMA7 had to be stopped.
HALERF_ISORXACK
0x00000100
Isochronous DMA reported error in packet ACK
HALERF_ISORX
0x00004000
Unspecified isochronous receive error.
HALERF_TXRESPONSE
0x00008000
Could not send a response for a request (Read or
Write).
HALERF_ASYRX
0x00010000
Error during asynchronous reception.
HALERF_ASYTX
0x00020000
Error during asynchronous transmission.
HALERF_PHYTIMEOUT
0x00040000
The Phy took to long to transfer an information to
the Linklayer chip.
HALERF_HDRERROR
0x00080000
A packet with an unknown header was received.
HALERF_TCERROR
0x00100000
Packet with unknown TCode was received.
HALERF_ATSTUCK
0x00200000
Asynchronous transmit FIFO stucked.
HALERF_GRFOVERFLOW
0x00400000
General receive FIFO overflowed (access to PCI
bus too slow)
HALERF_ITFUNDERFLOW
0x00800000
Isochronous transmit FIFO underflow (access from
PCI bus too slow)
HALERF_ATFUNDERFLOW
0x01000000
Asynchronous transmit FIFO underflow (access
from PCI bus too slow)
HALERF_PCIERROR
0x02000000
Error while accessing PCI bus.
HALERF_ASYRXRESTART
0x04000000
Error in asynchronous transmit state machine.
Transmission had to be restarted.
HALERF_NOACCESSINFO
0x08000000
No access info could be allocated while an external
access occurred.
FirePackage© - Documentation FireGrab
Page 128
Distributed by:
Name
Value
Description
HALERF_SELFID
0x10000000
Error while receiving SelfIds.
HALERF_DMPORT
0x20000000
Error in data mover port (GP-Lynx only)
HALERF_ISOTX
0x40000000
Error in isochronous transmission.
FirePackage© - Documentation FireGrab
Page 129
Distributed by:
How licensing works
You need a license to run the FirePackage. This license is embedded in each AVT camera. It will be
read out with the help of the license file LICENSE.TXT.
Note

LICENSE.TXT and FCTLMAIN.DLL always have to be in the same directory.

By default the DLLs are used from the Windows System32 directory.

If FCTLMAIN.DLL is not in the Windows System32 directory, then FirePackage will look in the
directory where the Viewer (SmartView) is installed.
A typical license file for AVT cameras looks like this:
* FireControl License File
1EEAF9B450220075 Devicecontained Offset=F1000008 (AVT)
...
...
After the top line starting with *, each line contains one license. The line after the top line is exactly as
shown above.
The license file will be read from top to down until a valid license was found.
Note
For further information on licensing read the following manual:
<install dir>\Allied Vision Technologies\FirePackage\Doc\Licensing.pdf
or ask your local dealer.
From FirePackage 2v17 the position of the license file can also be defined by the registry.
Under the key HKEY_LOCAL_MACHINE/Software/intek/FirePackage a subkey of type string with the
name LicenseFile specifies the full path and name of the license file.
Examples

To use the default license file from \windows\system32 add the following subkey:
[HKEY_LOCAL_MACHINE\SOFTWARE\intek\FirePackage]
"LicenseFile"="%systemroot%\system32\license.txt"

To use a license file from c:\MyApplication\Keys add the following subkey:
[HKEY_LOCAL_MACHINE\SOFTWARE\intek\FirePackage]
"LicenseFile"="c:\MyApplication\Keys\license.txt"
Whenever you want to use FireGrab (consisting of <FGCamera.DLL> and <FIREDRV.SYS>) in a
professional application it must be licensed. Without licensing a frame limited demo mode is
establilshed by default.
The license information is contained in a file named <LICENSE.TXT> that must exist in the same
directory as the <FGCamera.DLL>. Always make sure that <FGCamera.DLL> and <LICENSE.TXT>
are in the same directory.
Be aware that by default the <FGCamera.DLL> is used from the Windows System32 directory. If you
do not know to what locations the <FGCamera.DLL> has been copied make a search for it on your
hard disk.
FirePackage© - Documentation FireGrab
Page 130
Distributed by:
If there is no license file found your FireGrab will not run.
Normally FireGrab is delivered with a license file that contains a demo license. A demo license allows
to acquire about 3000 images. You then have to reboot your system for proper operation.
A license file contains a header line and one license in each line following. Normally each device you
want to talk to must be licensed. A device can be licensed by starting FireDemo and selecting the
device menu entry <Others> <License Request>. The 16 character string shown here must be sent to
your local dealer in order to request a license. The 16 character string you receive from your dealer
must then be inserted into your license file.
A typical license file looks like this:
* FireControl License File
189889B1CAEEDFE1
877777117A3146F0 License for AVT Marlin F033
06AEABE8DF98FEDE You can insert comments after the license!
There are also other licensing mechanisms for professional users. Ask your local dealer.
FirePackage© - Documentation FireGrab
Page 131