/camera/camlib

To get this branch, use:
bzr branch http://darksoft.org/webbzr/camera/camlib

« back to all changes in this revision

Viewing changes to include/pfGrab.h

  • Committer: Suren A. Chilingaryan
  • Date: 2011-02-13 01:33:37 UTC
  • Revision ID: csa@dside.dyndns.org-20110213013337-ibm4w4n5a3hu4k7u
Initial import

Show diffs side-by-side

added added

removed removed

Lines of Context:
include/pfGrab.h
 
1
/** \file pfGrab.h
 
2
  */
 
3
 
 
4
 
 
5
/*!
 
6
 * \mainpage pfGrab DLL Documentation
 
7
 * \version 1.0
 
8
 * \author Photonfocus AG
 
9
 * \date 01/2010
 
10
 *
 
11
 * \section Intro   Introduction
 
12
 * In order to ease the acquisition of frames suitable to be used with 3rd party 
 
13
 * application we offer a range of frame grabber drivers along with our Pflib SDK
 
14
 * or alternative the PFConfig  library. Each frame grabber driver file is an 
 
15
 * ordinary shared library called DLL file in Windows. That exposes a known 
 
16
 * C interface in order to use a vendor-specific grabber SDK or API.
 
17
 *
 
18
 * There are examples available about how to use the pfGrab DLL.
 
19
 *
 
20
 *
 
21
 */
 
22
 
 
23
#ifndef PFGRAB_H
 
24
#define PFGRAB_H
 
25
 
 
26
#ifdef PFGRAB_EXPORTS
 
27
#ifdef __cplusplus
 
28
extern "C"
 
29
#define PFGRAB_API  extern "C" __declspec(dllexport)
 
30
#else
 
31
#define PFGRAB_API __declspec(dllexport)
 
32
#endif
 
33
 
 
34
#else
 
35
#ifdef __cplusplus
 
36
#define PFGRAB_API extern "C" __declspec(dllimport)
 
37
#else
 
38
#define PFGRAB_API __declspec(dllimport)
 
39
#endif
 
40
#endif
 
41
 
 
42
#include <stdio.h>
 
43
#include <string>
 
44
 
 
45
enum PFGRAB_ERROR
 
46
{
 
47
    /* No error. */
 
48
    PFGRAB_ERROR_OK = 0,
 
49
 
 
50
    /* Unknown error. */
 
51
    PFGRAB_ERROR_UNKNOWN = -1,
 
52
 
 
53
    /* Memory allocation. */
 
54
    PFGRAB_ERROR_MEMORY = -2,
 
55
 
 
56
    /* The file is not found or an invalid format. */
 
57
    PFGRAB_ERROR_INVALID_FILE = -5,
 
58
 
 
59
    /* The frame grabber has not being started to grab yet. */
 
60
    PFGRAB_ERROR_FRAME_GRABBER_NOT_STARTED = -8,
 
61
 
 
62
    /* The frame grabber has been stopped while waiting for a frame. */
 
63
    PFGRAB_ERROR_FRAME_GRABBER_STOPPED = -9,
 
64
 
 
65
    /* The area is invalid. */
 
66
    PFGRAB_ERROR_INVALID_AREA = -10,
 
67
 
 
68
    /* There was a timeout performing the operation. */
 
69
    PFGRAB_ERROR_TIMEOUT = -16,
 
70
 
 
71
    /* A frame grabber driver reported some error unknown to the PFGRAB API. */
 
72
    PFGRAB_ERROR_FRAME_GRABBER_UNKNOWN = -18,
 
73
};
 
74
 
 
75
 
 
76
using namespace std;
 
77
 
 
78
///
 
79
/// \brief Initializes the frame grabber driver. 
 
80
/// 
 
81
/// \param[in] The string parameter is a free-form string to create a new pfGrab object.
 
82
/// It will be used to specify the frame grabber's configuration file,
 
83
/// the port to use or even which ones of the system installed frame grabbers to use. 
 
84
/// This string is driver-specific and is documented for every frame grabber driver,
 
85
/// even if it gets ignored by the driver.
 
86
///
 
87
/// \return The return value is the pointer to the driverData. 
 
88
/// This pointer is later passed as a void pointer to all other functions
 
89
/// in order to operate on the correct data. If there was an error in the initialization 
 
90
/// of the frame grabber driver the return value is NULL.
 
91
///
 
92
PFGRAB_API void* pfGrab_InitFG (int port, const char *fgName, const char *param);
 
93
 
 
94
///
 
95
/// \brief Most frame grabbers, for performance reasons, can be configured with a 
 
96
/// region of interest (ROI) that specifies which part of the whole image we are 
 
97
/// interested and the grabber device will only transfer the data of that region.
 
98
/// Normally the region of interest is specified in the configuration file for the
 
99
/// frame grabber but some applications require change the size of the ROI.
 
100
///  If the new region of interest's size could be set successful the function returns 
 
101
/// PFGRAB_ERROR_OK=0. If the given width or height is not allowed the function corrects
 
102
/// the value and returns the new value. Keep in mind that the user is instructed to never
 
103
/// change the region of interest while grabbing images.
 
104
///
 
105
/// \param[in] driverData The pointer to the driverData.
 
106
/// \param[in] width Image width to set
 
107
/// \param[in] height Image height to set
 
108
///
 
109
/// \return PFGRAB_ERROR_OK if successful otherwise error code.
 
110
///
 
111
PFGRAB_API long pfGrab_SetSize (void *driverData, long *width, long *height);
 
112
 
 
113
///
 
114
/// \brief The function pfGrab_StartGrab instructs the frame grabber driver
 
115
/// to start grabbing new frames. This function initialize the FG callbacks,
 
116
/// queues, and any other data structure given by the grabber device's vendor.
 
117
///     
 
118
/// \param[in] driverData The pointer to the driverData.
 
119
///
 
120
/// \return Return PFGRAB_ERROR_OK if there was no error starting
 
121
/// to acquire new frames.
 
122
///
 
123
PFGRAB_API long pfGrab_StartGrab (void * driverData);
 
124
 
 
125
///
 
126
/// \brief A call to pfGrab_Wait means that pfGrab is waiting 
 
127
/// for the frame grabber driver to acquire a new frame. 
 
128
/// From the point of view of pfGrab a new frame is whatever 
 
129
/// the grabber device acquired since the last call to pfGrab_StartGrab 
 
130
/// or pfGrab_Wait. That means that if since the last call to wait
 
131
/// three new frames have been acquired then the next call to wait won't 
 
132
/// need to wait to acquire the next frame, it is already available. 
 
133
///
 
134
/// \param[in] driverData The pointer to the driverData.
 
135
/// \param[in] timeout The parameter expressed in milliseconds that sets
 
136
/// the maximum number of milliseconds to wait for the next frame. 
 
137
/// If the driver wasn't able to acquire a new frame in the specified 
 
138
/// number of milliseconds then it returns PFGRAB_ERROR_TIMEOUT.
 
139
/// Take into account that a negative number of milliseconds as timeout
 
140
/// means that the driver must ignore the timeout and just wait 
 
141
/// until there's a frame available.
 
142
///
 
143
/// \return Return PFGRAB_ERROR_OK if a new image is available.
 
144
///
 
145
PFGRAB_API long pfGrab_Wait (void * driverData, long timeout);
 
146
 
 
147
 
 
148
///
 
149
/// \brief The function pfGrab_GetImage is called by the application
 
150
/// when there was a successful call to pfGrab_Wait. The purposes 
 
151
/// of this function if to get the pointer to the frame object 
 
152
/// that was created while waiting for an acquisition.
 
153
///
 
154
/// \param[in] driverData The pointer to the driverData.
 
155
/// \param[in] buffer Passing an optional buffer address for copying
 
156
/// the image data to the destination of the buffer address. If the
 
157
/// buffer address is NULL, the parameter is ignored.
 
158
/// \param[in] size In the case a buffer address is passed, the
 
159
/// function copies  the number of bytes defined in size to the
 
160
/// buffer destination.
 
161
/// 
 
162
/// \return The pointer to the frame object that was created 
 
163
/// while waiting for an acquisition.
 
164
///
 
165
PFGRAB_API void* pfGrab_GetImage (void * driverData, void* buffer, long* bufferSize);
 
166
 
 
167
 
 
168
///
 
169
/// \brief The function pfGrab_StopGrab is called when the user is not 
 
170
/// interested in receiving more frames. The driver tells the hardware to 
 
171
/// stop acquiring frames and, if it kept a queue, to clean up the 
 
172
/// acquired frames that weren't returned to the user.
 
173
/// 
 
174
/// \param[in] driverData The pointer to the driverData.
 
175
///
 
176
/// \return Return PFGRAB_ERROR_OK if there was no error starting 
 
177
/// to acquire new frames.
 
178
///
 
179
PFGRAB_API long pfGrab_StopGrab(void *driverData);
 
180
 
 
181
 
 
182
///
 
183
/// \brief When pfGrab no longer needs to keep the driver around because
 
184
/// no one is using it anymore the driver must clean up its own resources. 
 
185
/// The application should call the release function when the driver
 
186
/// must clean up itself
 
187
///
 
188
/// \param[in] driverData The pointer to the driverData.
 
189
///
 
190
///
 
191
PFGRAB_API void pfGrab_ReleaseFG (void * driverData);
 
192
 
 
193
#endif