source: eviacam/trunk/fuentes/creavision/libwebcam/webcam.h @ 29

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

added eviacam content

File size: 19.9 KB
Line 
1/**
2 * \file
3 * Webcam library interface definition.
4 *
5 * \ingroup libwebcam
6 */
7
8/*
9 * Copyright (c) 2006-2007 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_WEBCAM_H
28#define C_WEBCAM_H
29
30
31/*
32 * Basic type definitions
33 */
34
35/// Device handle for libwebcam
36typedef unsigned int CHandle;
37/// Function return type for libwebcam
38typedef unsigned int CResult;
39
40
41
42/*
43 * Enums
44 */
45
46/**
47 * Return values for libwebcam functions.
48 */
49enum _CResults {
50        C_SUCCESS                               = 0,    ///< Success
51        C_NOT_IMPLEMENTED,              ///< The function is not implemented
52        C_INIT_ERROR,                   ///< Error during initialization or library not initialized
53        C_INVALID_ARG,                  ///< Invalid argument
54        C_INVALID_HANDLE,               ///< Invalid handle
55        C_INVALID_DEVICE,               ///< Invalid device or device cannot be opened
56        C_NOT_EXIST,                    ///< The device to which the handle points no longer exists
57        C_NOT_FOUND,                    ///< Object not found
58        C_BUFFER_TOO_SMALL,             ///< Buffer too small
59        C_SYNC_ERROR,                   ///< Error during data synchronization
60        C_NO_MEMORY,                    ///< Out of memory
61        C_NO_HANDLES,                   ///< Out of handles
62        C_V4L2_ERROR,                   ///< A Video4Linux2 API call returned an unexpected error
63        C_SYSFS_ERROR,                  ///< A sysfs file access returned an error
64        C_PARSE_ERROR,                  ///< A control could not be parsed
65        C_CANNOT_WRITE,                 ///< Writing not possible (e.g. read-only control)
66        C_CANNOT_READ,                  ///< Reading not possible (e.g. write-only control)
67};
68
69
70/**
71 * Control identifiers.
72 * This is an exhaustive list of all controls supported by libwebcam. As new
73 * controls appear, these should be added to this list.
74 */
75typedef enum _CControlId {
76        // UVC: Basic image control
77        CC_BRIGHTNESS           = 1,                    ///< Image brightness
78        CC_CONTRAST,                                            ///< Image contrast
79        CC_GAIN,                                                        ///< Gain control
80        CC_SATURATION,                                          ///< Image color saturation
81        CC_HUE,                                                         ///< Hue
82        CC_GAMMA,                                                       ///< Gamma correction
83        CC_SHARPNESS,                                           ///< Image sharpness
84
85        // UVC: Advanced image control
86        /// White balance color temperature
87        CC_WHITE_BALANCE_TEMPERATURE,
88        /// Enable/disable automatic while balance color temperature selection
89        CC_AUTO_WHITE_BALANCE_TEMPERATURE,
90        /// White balance color component control (red, blue)
91        CC_WHITE_BALANCE_COMPONENT,
92        /// Enable/disable automatic white balance color component selection
93        CC_AUTO_WHITE_BALANCE_COMPONENT,
94        /// Backlight compensation mode
95        CC_BACKLIGHT_COMPENSATION,
96        /// Local power line frequency for anti-flicker processing
97        CC_POWER_LINE_FREQUENCY,
98        /// Enable/disable automatic hue control
99        CC_AUTO_HUE,
100        /// Mode for automatic exposure control
101        CC_AUTO_EXPOSURE_MODE,
102        /// Constraints for automatic exposure control (e.g. adaptive vs. constant frame rate)
103        CC_AUTO_EXPOSURE_PRIORITY,
104        /// Length of exposure (electronic shutter speed)
105        CC_EXPOSURE_TIME_ABSOLUTE,
106        /// Relative change to the current length of exposure
107        CC_EXPOSURE_TIME_RELATIVE,
108
109        // UVC: Optics control
110        /// Enable/disable automatic focus adjustment
111        CC_AUTO_FOCUS,
112        /// Distance to optimally focused target
113        CC_FOCUS_ABSOLUTE,
114        /// Relative change in distance to currently focused target
115        CC_FOCUS_RELATIVE,
116        /// Aperture setting
117        CC_IRIS_ABSOLUTE,
118        /// Relative change to the current aperture setting
119        CC_IRIS_RELATIVE,
120        /// Objective lens focal length
121        CC_ZOOM_ABSOLUTE,
122        /// Relative change to the current objective lens focal length
123        CC_ZOOM_RELATIVE,
124        /// Digital zoom multiplier applied to the optical image
125        CC_DIGITAL_ZOOM,
126
127        // UVC: Motion control
128        /// Pan angle (rotation on a vertical axis)
129        CC_PAN_ABSOLUTE,
130        /// Relative change to the current pan angle
131        CC_PAN_RELATIVE,
132        /// Tilt angle (rotation in a vertical plane)
133        CC_TILT_ABSOLUTE,
134        /// Relative change to the current tilt angle
135        CC_TILT_RELATIVE,
136        /// Roll angle (rotation along the image viewing axis)
137        CC_ROLL_ABSOLUTE,
138        /// Relative change to the current roll angle
139        CC_ROLL_RELATIVE,
140
141        // UVC: Misc
142        /// Temporarily prevent image from being acquired
143        CC_PRIVACY,
144
145        // V4L2: Motion control (new since 2.6.26)
146        /// Reset pan angle to a safe default value.
147        CC_PAN_RESET,
148        /// Reset tilt angle to a safe default value.
149        CC_TILT_RESET,
150
151        // V4L2: Unknown controls
152        /// Base for unknown V4L2 controls
153        CC_V4L2_BASE                            = 0x1000,
154        /// Base for custom V4L2 driver controls
155        CC_V4L2_CUSTOM_BASE                     = 0x2000,
156        /// Base for unknown V4L2 MPEG controls
157        CC_V4L2_MPEG_BASE                       = 0x3000,
158        /// Base for unknown V4L2 camera class controls
159        CC_V4L2_CAMERA_CLASS_BASE       = 0x4000,
160
161        // Logitech (USB vendor ID: 0x046d)
162        CC_LOGITECH_BASE = 0x046d0000,
163        /// Relative change to the current pan and tilt angles.
164        /// This control is specific to Logitech cameras that support panning and
165        /// tilting such as the QuickCam Orbit series.
166        CC_LOGITECH_PANTILT_RELATIVE,
167        /// Reset pan and tilt angles to a safe default value.
168        /// This control is specific to Logitech cameras that support panning and
169        /// tilting such as the QuickCam Orbit series.
170        CC_LOGITECH_PANTILT_RESET,
171        // Illumination mode of the first LED.
172        CC_LOGITECH_LED1_MODE,
173        // Blinking frequency of the first LED.
174        CC_LOGITECH_LED1_FREQUENCY,
175        // Disable video processing (enable raw mode)
176        CC_LOGITECH_DISABLE_PROCESSING,
177        // Bits per pixel for raw (Bayer) mode
178        CC_LOGITECH_RAW_BITS_PER_PIXEL,
179
180
181} CControlId;
182
183
184/**
185 * Flags specifying control properties and capabilities.
186 */
187typedef enum _CControlFlags {
188        /// The control can be read, i.e. its current value can be queried.
189        /// This flag is usually not set for action controls.
190        CC_CAN_READ                             = 1 << 0,
191        /// The control can be changed, i.e. it can be set to a new value.
192        /// Note that this flag does not imply CC_CAN_READ. Action controls accept
193        /// values but cannot necessarily be queried.
194        CC_CAN_WRITE                    = 1 << 1,
195        /// The control supports value change notification.
196        CC_CAN_NOTIFY                   = 1 << 2,
197
198        // The control is a custom vendor control and not standardized in V4L2 or UVC.
199        CC_IS_CUSTOM                    = 1 << 8,
200        // Set values are interpreted as being relative to the current value.
201        CC_IS_RELATIVE                  = 1 << 9,
202        // The control triggers an action.
203        CC_IS_ACTION                    = 1 << 10,
204    //The control needs to be set (used for save/restore)
205    CC_NEED_SET             = 1 << 11,
206
207} CControlFlags;
208
209
210/**
211 * Types for controls.
212 * These types give both hints to graphical user interfaces on how to display
213 * the control to the user as well as to the implementation in terms of data
214 * length required to store control values.
215 */
216typedef enum _CControlType {
217        /// The control uses raw binary data.
218        /// Usually (but not necessarily) this includes values that cannot be easily
219        /// mapped to simple data types.
220        CC_TYPE_RAW                             = 1,
221        /// The control knows only one enabled/disabled state.
222        /// Controls of this type are typically displayed as checkboxes.
223        CC_TYPE_BOOLEAN,
224        /// The control accepts a defined list of values.
225        /// Controls of this type are typically displayed as combo boxes or lists.
226        CC_TYPE_CHOICE,
227        /// The control accepts 8-bit integer values.
228        CC_TYPE_BYTE,
229        /// The control accepts 16-bit integer values.
230        CC_TYPE_WORD,
231        /// The control accepts 32-bit integer values.
232        CC_TYPE_DWORD,
233        /// The control accepts 32-bit unsigned values.
234        CC_TYPE_BUTTON,
235
236} CControlType;
237
238
239/**
240 * Event identifiers.
241 */
242typedef enum _CEventId {
243        CE_CONTROL_INVALID              = 0,
244
245} CEventId;
246
247
248/**
249 * Flags specifying properties of events.
250 */
251typedef enum _CEventFlags {
252        CE_INVALID                              = 0,
253
254} CEventFlags;
255
256
257/**
258 * Types of frame size specifications.
259 */
260typedef enum _CFrameSizeTypes {
261        /// One discrete width/height combination.
262        CF_SIZE_DISCRETE                = 1,
263        /// Minimum and maximum values for both width and height.
264        CF_SIZE_CONTINUOUS,
265        /// Minimum, maximum, and step values for both width and height.
266        CF_SIZE_STEPWISE,
267
268} CFrameSizeTypes;
269
270
271/**
272 * Types of frame interval specification.
273 */
274typedef enum _CFrameIntervalTypes {
275        /// One discrete time interval.
276        CF_INTERVAL_DISCRETE            = 1,
277        /// Minimum and maximum values for the time interval.
278        CF_INTERVAL_CONTINUOUS,
279        /// Minimum, maximum, and step values for the time interval.
280        CF_INTERVAL_STEPWISE,
281
282} CFrameIntervalTypes;
283
284
285/**
286 * Flags specifying control properties and capabilities.
287 */
288typedef enum _CDynctrlFlags {
289        /// Disable XML schema validation.
290        CD_DONT_VALIDATE                = 1 << 0,
291        /// Collect errors and warnings during the process
292        CD_REPORT_ERRORS                = 1 << 1,
293        /// Return meta data during the XML parsing process
294        CD_RETRIEVE_META_INFO   = 1 << 2,
295
296} CDynctrlFlags;
297
298
299/**
300 * Severity levels for messages returned by the dynamic control functions
301 */
302typedef enum _CDynctrlMessageSeverity {
303        CD_SEVERITY_ERROR               = 2,            ///< Error
304        CD_SEVERITY_WARNING             = 3,            ///< Warning
305        CD_SEVERITY_INFO                = 4,            ///< Informational
306
307} CDynctrlMessageSeverity;
308
309
310
311/*
312 * Structs
313 */
314
315/**
316 * USB specific information about a device.
317 */
318typedef struct _CUSBInfo {
319        /// The vendor ID.
320        unsigned short  vendor;
321        /// The product ID.
322        unsigned short  product;
323        /// The product revision number.
324        unsigned short  release;
325
326} CUSBInfo;
327
328
329/**
330 * Webcam device information.
331 */
332typedef struct _CDevice {
333        /// A unique short name.
334        /// For V4L2 devices this is the name of the device file. For example, if
335        /// a device appears as '/dev/video0', the short name is 'video0'.
336        /// This member is never NULL.
337        char                    * shortName;
338       
339        /// The human-readable name of the device.
340        /// This member is never NULL.
341        char                    * name;
342
343        /// The name of the driver providing the camera interface.
344        /// This member is never NULL.
345        char                    * driver;
346
347        /// The location of the camera.
348        /// This string is dependent on the implementation that provides the device.
349        /// It could either be a string provided by the driver or a device name.
350        /// This member is never NULL.
351        char                    * location;
352
353        /// USB related information about the camera.
354        CUSBInfo                usb;
355
356} CDevice;
357
358
359/**
360 * A raw control value.
361 */
362typedef struct _CControlRawValue {
363        /// Pointer to the raw data.
364        void                    * data;
365        /// Size of the raw data.
366        unsigned int    size;
367
368} CControlRawValue;
369
370
371/**
372 * A value of a control.
373 */
374typedef struct _CControlValue {
375        /// The type of the control to which the value belongs.
376        /// This member is used to determine which of the members of the union are
377        /// valid. The type is a duplicate of the corresponding CControl#type value.
378        CControlType    type;
379
380        union {
381                /// The value of the control for number based controls.
382                /// This member is valid for the following control types:
383                /// #CC_TYPE_BOOLEAN, #CC_TYPE_CHOICE, #CC_TYPE_BYTE,
384                /// #CC_TYPE_WORD, #CC_TYPE_DWORD #CC_TYPE_BUTTON
385                int                             value;
386
387                /// The value of the control for raw cntrols.
388                /// This member is valid only for control type #CC_TYPE_RAW.
389                CControlRawValue        raw;
390        };
391
392} CControlValue;
393
394
395/**
396 * A list of choices for a choice type of control.
397 * @see CC_TYPE_CHOICE
398 */
399typedef struct _CControlChoice {
400        /// The index of the choice within the list of choices.
401        /// Note that this index is not necessarily zero-based and can therefore @a not
402        /// be used as an index into CControl#choices#list[].
403        int                             index;
404        int                     id;
405
406        /// The name of the choice.
407        /// This member is never NULL.
408        char                    name[32];
409
410} CControlChoice;
411
412
413/**
414 * A description of a camera control.
415 */
416typedef struct _CControl {
417        /// The identifier of the control
418        CControlId              id;
419        /// The human-readable name of the control
420        char                    * name;
421        /// The type of the control
422        CControlType    type;
423        /// Flags describing properties and capabilities of the control
424        CControlFlags   flags;
425
426        /// The current value of the control
427        CControlValue   value;
428        /// The default value of the control
429        CControlValue   def;
430
431        union {
432                /// Additional control attributes for non-choice controls.
433                /// The members of this struct are only valid for control types other
434                /// than #CC_TYPE_CHOICE.
435                struct {
436                        /// The minimum value of the control
437                        CControlValue   min;
438                        /// The maximum value of the control
439                        CControlValue   max;
440                        /// The resolution of the control values
441                        CControlValue   step;
442                };
443
444                /// List of the possible choices that this control allows.
445                /// The members of this struct are only valid if the type is #CC_TYPE_CHOICE.
446                struct {
447                        /// The number of choices in the list
448                        unsigned int    count;
449                        /// The list of choice values
450                        CControlChoice  * list;
451                       
452                        /// A buffer that contains the names of the #CControlChoice items.
453                        /// The @a name fields of the items point to strings within this buffer,
454                        /// so there is no need to work with this member directly except
455                        /// freeing the buffer if the control is disposed of.
456                        //char                  * names;
457
458                } choices;
459        };
460
461} CControl;
462
463
464/**
465 * A description of a pixel format.
466 */
467typedef struct _CPixelFormat {
468        /// A FourCC code identifying the pixel format.
469        /// Note that this member contains an extra byte which will contain a \\0
470        /// character when returned by c_enum_pixel_formats(). This allows the field
471        /// to be treated like a NUL terminated string.
472        char                    fourcc[5];
473
474        /// A human-readable description of the pixel format.
475        char                    * name;
476
477        /// The MIME type corresponding to the pixel format.
478        /// This member can be NULL.
479        char                    * mimeType;
480
481} CPixelFormat;
482
483
484/**
485 * A description of one or multiple frame sizes.
486 */
487typedef struct _CFrameSize {
488        /// Type of the frame size(s) described (discrete, continuous, step-wise)
489        CFrameSizeTypes type;
490       
491        union {
492                /// Discrete frame size.
493                /// This member is only valid if @a type is #CF_SIZE_DISCRETE.
494                struct {
495                        /// Width
496                        unsigned int    width;
497                        /// Height
498                        unsigned int    height;
499                };
500
501                /// Continuous or step-wise frame size.
502                /// This member is only valid if @a type is #CF_SIZE_CONTINUOUS or
503                /// #CF_SIZE_STEPWISE.
504                struct {
505                        /// Minimum width
506                        unsigned int    min_width;
507                        /// Maximum width
508                        unsigned int    max_width;
509                        /// Step size for the width (usually 1 if @a type is #CF_SIZE_CONTINUOUS)
510                        unsigned int    step_width;
511                        /// Minimum height
512                        unsigned int    min_height;
513                        /// Maximum height
514                        unsigned int    max_height;
515                        /// Step size for the height (usually 1 if @a type is #CF_SIZE_CONTINUOUS)
516                        unsigned int    step_height;
517                };
518        };
519
520} CFrameSize;
521
522
523/**
524 * A description of one or multiple frame intervals.
525 * Each frame interval is described as a fraction of a second.
526 */
527typedef struct _CFrameInterval {
528        /// Type of the frame interval(s) described (discrete, continuous, step-wise)
529        CFrameIntervalTypes     type;
530
531        union {
532                /// Discrete frame interval.
533                /// This member is only valid if @a type is #CF_INTERVAL_DISCRETE.
534                struct {
535                        /// Numerator of the frame interval
536                        unsigned int    n;
537                        /// Denominator of the frame interval
538                        unsigned int    d;
539                };
540
541                /// Continuous or step-wise frame interval.
542                /// This member is only valid if @a type is #CF_INTERVAL_CONTINUOUS or
543                /// #CF_INTERVAL_STEPWISE.
544                struct {
545                        /// Numerator of the minimum frame interval
546                        unsigned int    min_n;
547                        /// Denominator of the minimum frame interval
548                        unsigned int    min_d;
549                        /// Numerator of the maximum frame interval
550                        unsigned int    max_n;
551                        /// Denominator of the maximum frame interval
552                        unsigned int    max_d;
553                        /// Numerator of the frame interval step size (usually 1 if @a type is #CF_INTERVAL_CONTINUOUS
554                        unsigned int    step_n;
555                        /// Denominator of the frame interval step size (usually 1 if @a type is #CF_INTERVAL_CONTINUOUS
556                        unsigned int    step_d;
557                };
558        };
559
560} CFrameInterval;
561
562
563/**
564 * An event descriptor.
565 */
566typedef struct _CEvent {
567        /// Unique identifier of the event
568        CEventId                id;
569
570        /// Human-readable name of the event
571        char                    * name;
572
573        /// Flags descripting properties of the event
574        CEventFlags             flags;
575
576} CEvent;
577
578
579/**
580 * Message returned by the dynamic control configuration parser.
581 */
582typedef struct _CDynctrlMessage {
583        /// Line number that the message concerns
584        int                             line;
585
586        /// Column that the message concerns
587        int                             col;
588
589        /// Severity level
590        CDynctrlMessageSeverity severity;
591
592        /// Pointer to the message text
593        char                    * text;
594
595} CDynctrlMessage;
596
597
598/**
599 * Version number in the "major.minor" format.
600 */
601typedef struct _CVersionNumber {
602        /// Major version number
603        unsigned int    major;
604
605        /// Minor version number
606        unsigned int    minor;
607
608} CVersionNumber;
609
610
611/**
612 * Statistics on the number of list elements that were processed.
613 */
614typedef struct _CDynctrlInfoListStats {
615        /// Number of elements in the list that were processed successfully
616        unsigned int    successful;
617
618        /// Number of elements in the list that could not be processed successfully
619        unsigned int    failed;
620
621} CDynctrlInfoListStats;
622
623
624/**
625 * Input flags and output data used/returned by the control configuration parser.
626 */
627typedef struct _CDynctrlInfo {
628        /// Flags controlling operations related to dynamic controls
629        CDynctrlFlags   flags;
630
631        /// Processing statistics
632        struct {
633                /// Statistics on the constants that were processed
634                CDynctrlInfoListStats   constants;
635
636                /// Statistics on the controls that were processed
637                CDynctrlInfoListStats   controls;
638
639                /// Statistics on the mappings that were processed
640                CDynctrlInfoListStats   mappings;
641
642        }                               stats;
643
644        /// Meta information about the XML control configuration
645        struct {
646                /// File format version
647                CVersionNumber  version;
648
649                /// Name of the configuration author
650                char                    * author;
651
652                /// Contact information of the configuration author (e.g. e-mail address)
653                char                    * contact;
654
655                /// Copyright information about the configuration file
656                char                    * copyright;
657
658                /// Revision number of the configuration file (configuration version)
659                CVersionNumber  revision;
660
661        }                               meta;
662
663        /// Number of messages in the @a messages array
664        unsigned int    message_count;
665
666        /// Pointer to the array with the messages concerning the operation
667        CDynctrlMessage * messages;
668
669} CDynctrlInfo;
670
671
672
673/*
674 * Type definitions
675 */
676
677/**
678 * Prototype for event handlers
679 */
680typedef void (*CEventHandler)(CHandle hDevice, CEventId event_id, void *context);
681
682
683
684/*
685 * Functions
686 */
687
688#ifdef __cplusplus
689extern "C" {
690#endif
691
692extern CResult          c_init (void);
693extern void                     c_cleanup (void);
694
695extern CHandle          c_open_device (const char *device_name);
696extern void                     c_close_device (CHandle hDevice);
697extern int              c_get_file_descriptor (CHandle hDevice);
698
699extern CResult          c_enum_devices (CDevice *devices, unsigned int *size, unsigned int *count);
700extern CResult          c_get_device_info (CHandle hDevice, const char *device_name, CDevice *info, unsigned int *size);
701
702extern CResult          c_enum_pixel_formats (CHandle hDevice, CPixelFormat *formats, unsigned int *size, unsigned int *count);
703extern CResult          c_enum_frame_sizes (CHandle hDevice, const CPixelFormat *pixelformat, CFrameSize *sizes, unsigned int *size, unsigned int *count);
704extern CResult          c_enum_frame_intervals (CHandle hDevice, const CPixelFormat *pixelformat, const CFrameSize *framesize, CFrameInterval *intervals, unsigned int *size, unsigned int *count);
705
706extern CResult          c_enum_controls (CHandle hDevice, CControl *controls, unsigned int *size, unsigned int *count);
707extern CResult          c_set_control (CHandle hDevice, CControlId control_id, const CControlValue *value);
708extern CResult          c_get_control (CHandle hDevice, CControlId control_id, CControlValue *value);
709
710extern CResult          c_save_controls (CHandle hDevice, const char *filename);
711extern CResult          c_load_controls (CHandle hDevice, const char *filename);
712
713extern CResult          c_enum_events (CHandle hDevice, CEvent *events, unsigned int *size, unsigned int *count);
714extern CResult          c_subscribe_event (CHandle hDevice, CEventId event_id, CEventHandler handler, void *context);
715extern CResult          c_unsubscribe_event (CHandle hDevice, CEventId event_id);
716
717#ifndef DISABLE_UVCVIDEO_DYNCTRL
718extern CResult          c_add_control_mappings_from_file (const char *file_name, CDynctrlInfo *info);
719extern CResult          c_add_control_mappings (CHandle handle, const char *file_name, CDynctrlInfo *info);
720#endif
721
722extern char                     *c_get_error_text (CResult error);
723extern char                     *c_get_handle_error_text (CHandle hDevice, CResult error);
724
725#ifdef __cplusplus
726}
727#endif
728
729
730#endif /* C_WEBCAM_H */
Note: See TracBrowser for help on using the repository browser.