source: eviacam/trunk/fuentes/creavision/libwebcam/libwebcam.h @ 567

Last change on this file since 567 was 567, checked in by mabarracus, 4 years ago

updated sources to version 2.0.3

File size: 8.5 KB
Line 
1/**
2 * \file
3 * Webcam library declarations.
4 *
5 * \ingroup libwebcam
6 */
7
8/*
9 * Copyright (c) 2006-2008 Logitech.
10 *
11 * This file is part of libwebcam.
12 *
13 * libwebcam is free software: you can redistribute it and/or modify
14 * it under the terms of the GNU Lesser General Public License as published
15 * by the Free Software Foundation, either version 3 of the License, or
16 * (at your option) any later version.
17 *
18 * libwebcam is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21 * GNU Lesser General Public License for more details.
22 *
23 * You should have received a copy of the GNU Lesser General Public License
24 * along with libwebcam.  If not, see <http://www.gnu.org/licenses/>.
25 */
26
27#ifndef C_LIBWEBCAM_H
28#define C_LIBWEBCAM_H
29
30
31#include <assert.h>
32
33
34/*
35 * Features
36 */
37
38/// Whether private controls of the Linux UVC driver should be used or not
39#define USE_UVCVIDEO
40#ifdef USE_UVCVIDEO
41
42        /// Whether to compile in support functions for the Linux UVC driver's dynamic
43        /// controls.
44        #define ENABLE_UVCVIDEO_DYNCTRL
45        #ifdef  ENABLE_UVCVIDEO_DYNCTRL
46
47                /// Whether to include the automatically generated Logitech dynamic controls
48                /// header file.
49                #define USE_LOGITECH_DYNCTRL
50
51                /// Whether to include support for raw controls.
52                /// Note that this requires V4L2_CTRL_TYPE_STRING to be available (i.e. V4L2 >= 2.6.32).
53                /// This is disabled by default but CMake enables it if it finds V4L2_CTRL_TYPE_STRING.
54                //#define ENABLE_RAW_CONTROLS
55
56        #endif
57
58#endif
59
60
61/*
62 * Constants
63 */
64
65/// Whether to use the V4L2_CTRL_FLAG_NEXT_CTRL flag when enumerating V4L2 controls
66#define ENABLE_V4L2_ADVANCED_CONTROL_ENUMERATION
67
68/// Ignore EEXIST errors for the UVCIOC_CTRL_ADD and UVCIOC_CTRL_MAP ioctls for
69/// all but the first device. This is required if the driver uses global controls
70/// instead of per-device controls.
71#define DYNCTRL_IGNORE_EEXIST_AFTER_PASS1
72
73/// The maximum number (plus 1) of handles libwebcam supports
74#define MAX_HANDLES                                             32
75
76/// Debug option to disable locking
77#define DISABLE_LOCKING                                 1
78/// Debug option to add verbosity to locking and unlocking
79#define DEBUG_LOCKING                                   1
80
81/// The name used for controls whose name could not be retrieved.
82#define UNKNOWN_CONTROL_NAME                    "Unknown control"
83/// Number of retries for failed V4L2 ioctl requests.
84/// This is a workaround for faulty devices.
85#define CONTROL_IO_ERROR_RETRIES                2
86
87/// Size of a GUID in bytes
88#define GUID_SIZE               16
89
90
91
92/*
93 * Macros
94 */
95
96/// Returns the given handle structure
97#define GET_HANDLE(handle)              (handle_list.handles[(handle)])
98/// Returns true if the given handle is open (valid or invalid)
99#define HANDLE_OPEN(handle)             ((handle) < MAX_HANDLES && GET_HANDLE(handle).open)
100/// Returns true if the given handle is open and valid
101#define HANDLE_VALID(handle)    (HANDLE_OPEN(handle) && GET_HANDLE(handle).device)
102
103/// Returns the maximum number of characters that a menu-type control choice
104/// can have in V4L2.
105#define V4L2_MENU_CTRL_MAX_NAME_SIZE    sizeof(((struct v4l2_querymenu *)NULL)->name)
106
107/// Converts the given characters into a FourCC code
108#define MAKE_FOURCC(c1,c2,c3,c4) \
109        (unsigned int)((long)c1 | (long)c2 << 8 | (long)c3 << 16 | (long)c4 << 24)
110
111/// Format string to print a GUID byte array with printf
112#define GUID_FORMAT             "%02x%02x%02x%02x-%02x%02x-%02x%02x-%02x%02x-%02x%02x%02x%02x%02x%02x"
113/// Argument macro to print a GUID byte array with printf
114#define GUID_ARGS(guid) \
115        (guid)[3],  (guid)[2],  (guid)[1],  (guid)[0], \
116        (guid)[5],  (guid)[4], \
117        (guid)[7],  (guid)[6], \
118        (guid)[8],  (guid)[9], \
119        (guid)[10], (guid)[11], (guid)[12], \
120        (guid)[13], (guid)[14], (guid)[15]
121
122
123
124/*
125 * Structures
126 */
127
128/**
129 * An internal control description associated with a device.
130 */
131typedef struct _Control {
132        /// Control description
133        CControl                control;
134        /// V4L2 ioctl mapping (non-0 for V4L2 controls)
135        int                             v4l2_control;
136        /// Pointer to the next control in the list
137        struct _Control * next;
138
139} Control;
140
141/**
142 * Base structure that contains a list of controls and associated data.
143 */
144typedef struct _ControlList {
145        /// The first control in the list
146        Control                 * first;
147        /// The last control in the list
148        Control         * last;
149        /// The mutex used to serialize access to the control list
150        pthread_mutex_t mutex;
151        /// The number of controls contained in the list
152        int                             count;
153
154} ControlList;
155
156/**
157 * Internal device information.
158 */
159typedef struct _Device {
160        /// Device information
161        CDevice                 device;
162        /// Short V4L2 device name (e.g. 'video0')
163        char                    v4l2_name[NAME_MAX];
164        /// Number of handles associated with this device
165        int                             handles;
166        /// List of controls supported by this device
167        ControlList             controls;
168        /// Boolean whether the device is still valid, i.e. exists in the system.
169        /// Devices marked as invalid will be cleared out by cleanup_device_list().
170        int                             valid;
171        /// File descriptor returned by open
172        int                             fd;
173        /// Next device in the global device list
174        struct _Device  * next;
175
176} Device;
177
178/**
179 * Base structure that contains a list of devices and associated data.
180 */
181typedef struct _DeviceList {
182        /// The first device in the list
183        Device                  * first;
184        /// The mutex used to serialize access to the device list
185        pthread_mutex_t mutex;
186        /// The number of devices contained in the list
187        int                             count;
188
189} DeviceList;
190
191/**
192 * Information associated with a device handle.
193 *
194 * Note that a handle can have three different states:
195 * - Closed/free: The device handle is not being used by an application.
196 * - Valid: The device handle is open by an application and points to a valid device.
197 * - Invalid: The device handle is open by an application but does not point to a
198 *     (valid) device anymore. This happens when a device is removed from the system
199 *     but there are still open handles around.
200 * An "open" handle can be both valid or invalid.
201 */
202typedef struct _Handle {
203        /// Pointer to the device structure associated with this handle
204        Device                  * device;
205        /// True if the handle is open (valid or invalid)
206        int                             open;
207        /// The number of the last system error (e.g. a V4L2 return value)
208        int                             last_system_error;
209       
210} Handle;
211
212/**
213 * Base structure that contains an array of device handles and associated data.
214 */
215typedef struct _HandleList {
216        /// The array of handles
217        Handle                  handles[MAX_HANDLES];
218        /// The mutex used to serialize access to the handle list
219        pthread_mutex_t mutex;
220        /// The index of the first free handle.
221        /// Zero if there are now free handles at this time.
222        int                             first_free;
223       
224} HandleList;
225
226
227
228/*
229 * Globals
230 */
231
232extern int initialized;
233extern HandleList handle_list;
234
235extern void print_error (char *format, ...);
236extern int open_v4l2_device(char *device_name);
237
238
239
240/*
241 * Helper functions
242 */
243
244/**
245 * Acquire a mutex.
246 *
247 * This function is identical to pthread_mutex_lock except that it has different
248 * return values and supports some debug flags.
249 *
250 * @return
251 *              C_SUCCESS if the mutex was successfully acquired
252 *              C_SYNC_ERROR if an error occured while trying to acquire the mutex
253 */
254static inline CResult lock_mutex (pthread_mutex_t *mutex)
255{
256#ifndef DISABLE_LOCKING
257#ifdef DEBUG_LOCKING
258        fprintf(stderr, "Acquiring mutex 0x%08x ...\n", (unsigned int)mutex);
259#endif
260        int ret = pthread_mutex_lock(mutex);
261#ifdef DEBUG_LOCKING
262        fprintf(stderr, "Acquisition of mutex 0x%08x %s.\n", (unsigned int)mutex,
263                        ret ? "failed" : "successful");
264#endif
265        assert(ret == 0);
266        return ret ? C_SYNC_ERROR : C_SUCCESS;
267#else
268        return C_SUCCESS;
269#endif
270}
271
272
273/**
274 * Release a mutex.
275 *
276 * This function is identical to pthread_mutex_unlock except that it has different
277 * return values and supports some debug flags.
278 *
279 * @return
280 *              C_SUCCESS if the mutex was successfully released
281 *              C_SYNC_ERROR if an error occured while trying to release the mutex
282 */
283static inline void unlock_mutex (pthread_mutex_t *mutex)
284{
285#ifndef DISABLE_LOCKING
286#ifdef DEBUG_LOCKING
287        fprintf(stderr, "Releasing mutex 0x%08x ...\n", (unsigned int)mutex);
288#endif
289        int ret = pthread_mutex_unlock(mutex);
290#ifdef DEBUG_LOCKING
291        fprintf(stderr, "Release of mutex 0x%08x %s.\n", (unsigned int)mutex,
292                        ret ? "failed" : "successful");
293#endif
294        assert(ret == 0);
295#endif
296}
297
298
299/**
300 * Copies a variable-length string to the part of an enumeration buffer that is
301 * reserved for dynamic data.
302 *
303 * This function is used by the enumeration functions.
304 */
305static inline void copy_string_to_buffer (char **target, char *source, void *buffer, unsigned int *offset)
306{
307        unsigned int length = strlen(source);
308        *target = (char *)buffer + *offset;
309        memcpy(*target, source, length + 1);
310        *offset += length + 1;
311}
312
313
314#endif /* C_LIBWEBCAM_H */
Note: See TracBrowser for help on using the repository browser.