webcam.h

Go to the documentation of this file.

/*
 * Copyright (c) 2006-2007 Logitech.
 *
 * This file is part of libwebcam.
 * 
 * libwebcam is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published
 * by the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * libwebcam is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public License
 * along with libwebcam.  If not, see <http://www.gnu.org/licenses/>.
 */

#ifndef C_WEBCAM_H
#define C_WEBCAM_H


/*
 * Basic type definitions
 */

typedef unsigned int CHandle;
typedef unsigned int CResult;



/*
 * Enums
 */

enum _CResults {
    C_SUCCESS               = 0,    
    C_NOT_IMPLEMENTED,      
    C_INIT_ERROR,           
    C_INVALID_ARG,          
    C_INVALID_HANDLE,       
    C_INVALID_DEVICE,       
    C_NOT_EXIST,            
    C_NOT_FOUND,            
    C_BUFFER_TOO_SMALL,     
    C_SYNC_ERROR,           
    C_NO_MEMORY,            
    C_NO_HANDLES,           
    C_V4L2_ERROR,           
    C_SYSFS_ERROR,          
    C_PARSE_ERROR,          
    C_CANNOT_WRITE,         
    C_CANNOT_READ,          
};


typedef enum _CControlId {
    // UVC: Basic image control
    CC_BRIGHTNESS       = 1,            
    CC_CONTRAST,                        
    CC_GAIN,                            
    CC_SATURATION,                      
    CC_HUE,                             
    CC_GAMMA,                           
    CC_SHARPNESS,                       

    // UVC: Advanced image control
    CC_WHITE_BALANCE_TEMPERATURE,
    CC_AUTO_WHITE_BALANCE_TEMPERATURE,
    CC_WHITE_BALANCE_COMPONENT,
    CC_AUTO_WHITE_BALANCE_COMPONENT,
    CC_BACKLIGHT_COMPENSATION,
    CC_POWER_LINE_FREQUENCY,
    CC_AUTO_HUE,
    CC_AUTO_EXPOSURE_MODE,
    CC_AUTO_EXPOSURE_PRIORITY,
    CC_EXPOSURE_TIME_ABSOLUTE,
    CC_EXPOSURE_TIME_RELATIVE,

    // UVC: Optics control
    CC_AUTO_FOCUS,
    CC_FOCUS_ABSOLUTE,
    CC_FOCUS_RELATIVE,
    CC_IRIS_ABSOLUTE,
    CC_IRIS_RELATIVE,
    CC_ZOOM_ABSOLUTE,
    CC_ZOOM_RELATIVE,
    CC_DIGITAL_ZOOM,

    // UVC: Motion control
    CC_PAN_ABSOLUTE,
    CC_PAN_RELATIVE,
    CC_TILT_ABSOLUTE,
    CC_TILT_RELATIVE,
    CC_ROLL_ABSOLUTE,
    CC_ROLL_RELATIVE,

    // UVC: Misc
    CC_PRIVACY,

    // V4L2: Motion control (new since 2.6.26)
    CC_PAN_RESET,
    CC_TILT_RESET,

    // V4L2: Unknown controls
    CC_V4L2_BASE                = 0x1000,
    CC_V4L2_CUSTOM_BASE         = 0x2000,
    CC_V4L2_MPEG_BASE           = 0x3000,
    CC_V4L2_CAMERA_CLASS_BASE   = 0x4000,

    // Logitech (USB vendor ID: 0x046d)
    CC_LOGITECH_BASE = 0x046d0000,
    CC_LOGITECH_PANTILT_RELATIVE,
    CC_LOGITECH_PANTILT_RESET,
    // Illumination mode of the first LED.
    CC_LOGITECH_LED1_MODE,
    // Blinking frequency of the first LED.
    CC_LOGITECH_LED1_FREQUENCY,
    // Disable video processing (enable raw mode)
    CC_LOGITECH_DISABLE_PROCESSING,
    // Bits per pixel for raw (Bayer) mode
    CC_LOGITECH_RAW_BITS_PER_PIXEL,


} CControlId;


typedef enum _CControlFlags {
    CC_CAN_READ             = 1 << 0,
    CC_CAN_WRITE            = 1 << 1,
    CC_CAN_NOTIFY           = 1 << 2,

    // The control is a custom vendor control and not standardized in V4L2 or UVC.
    CC_IS_CUSTOM            = 1 << 8,
    // Set values are interpreted as being relative to the current value.
    CC_IS_RELATIVE          = 1 << 9,
    // The control triggers an action.
    CC_IS_ACTION            = 1 << 10,

} CControlFlags;


typedef enum _CControlType {
    CC_TYPE_RAW             = 1,
    CC_TYPE_BOOLEAN,
    CC_TYPE_CHOICE,
    CC_TYPE_BYTE,
    CC_TYPE_WORD,
    CC_TYPE_DWORD,

} CControlType;


typedef enum _CEventId {
    CE_CONTROL_INVALID      = 0,

} CEventId;


typedef enum _CEventFlags {
    CE_INVALID              = 0,

} CEventFlags;


typedef enum _CFrameSizeTypes {
    CF_SIZE_DISCRETE        = 1,
    CF_SIZE_CONTINUOUS,
    CF_SIZE_STEPWISE,

} CFrameSizeTypes;


typedef enum _CFrameIntervalTypes {
    CF_INTERVAL_DISCRETE        = 1,
    CF_INTERVAL_CONTINUOUS,
    CF_INTERVAL_STEPWISE,

} CFrameIntervalTypes;


typedef enum _CDynctrlFlags {
    CD_DONT_VALIDATE        = 1 << 0,
    CD_REPORT_ERRORS        = 1 << 1,
    CD_RETRIEVE_META_INFO   = 1 << 2,

} CDynctrlFlags;


typedef enum _CDynctrlMessageSeverity {
    CD_SEVERITY_ERROR       = 2,        
    CD_SEVERITY_WARNING     = 3,        
    CD_SEVERITY_INFO        = 4,        

} CDynctrlMessageSeverity;



/*
 * Structs
 */

typedef struct _CUSBInfo {
    unsigned short  vendor;
    unsigned short  product;
    unsigned short  release;

} CUSBInfo;


typedef struct _CDevice {
    char            * shortName;
    
    char            * name;

    char            * driver;

    char            * location;

    CUSBInfo        usb;

} CDevice;


typedef struct _CControlRawValue {
    void            * data;
    unsigned int    size;

} CControlRawValue;


typedef struct _CControlValue {
    CControlType    type;

    union {
        int             value;

        CControlRawValue    raw;
    };

} CControlValue;


typedef struct _CControlChoice {
    int             index;

    char            * name;

} CControlChoice;


typedef struct _CControl {
    CControlId      id;
    char            * name;
    CControlType    type;
    CControlFlags   flags;

    CControlValue   value;
    CControlValue   def;

    union {
        struct {
            CControlValue   min;
            CControlValue   max;
            CControlValue   step;
        };

        struct {
            unsigned int    count;
            CControlChoice  * list;
            
            char            * names;

        } choices;
    };

} CControl;


typedef struct _CPixelFormat {
    char            fourcc[5];

    char            * name;

    char            * mimeType;

} CPixelFormat;


typedef struct _CFrameSize {
    CFrameSizeTypes type;
    
    union {
        struct {
            unsigned int    width;
            unsigned int    height;
        };

        struct {
            unsigned int    min_width;
            unsigned int    max_width;
            unsigned int    step_width;
            unsigned int    min_height;
            unsigned int    max_height;
            unsigned int    step_height;
        };
    };

} CFrameSize;


typedef struct _CFrameInterval {
    CFrameIntervalTypes type;

    union {
        struct {
            unsigned int    n;
            unsigned int    d;
        };

        struct {
            unsigned int    min_n;
            unsigned int    min_d;
            unsigned int    max_n;
            unsigned int    max_d;
            unsigned int    step_n;
            unsigned int    step_d;
        };
    };

} CFrameInterval;


typedef struct _CEvent {
    CEventId        id;

    char            * name;

    CEventFlags     flags;

} CEvent;


typedef struct _CDynctrlMessage {
    int             line;

    int             col;

    CDynctrlMessageSeverity severity;

    char            * text;

} CDynctrlMessage;


typedef struct _CVersionNumber {
    unsigned int    major;

    unsigned int    minor;

} CVersionNumber;


typedef struct _CDynctrlInfoListStats {
    unsigned int    successful;

    unsigned int    failed;

} CDynctrlInfoListStats;


typedef struct _CDynctrlInfo {
    CDynctrlFlags   flags;

    struct {
        CDynctrlInfoListStats   constants;

        CDynctrlInfoListStats   controls;

        CDynctrlInfoListStats   mappings;

    }               stats;

    struct {
        CVersionNumber  version;

        char            * author;

        char            * contact;

        char            * copyright;

        CVersionNumber  revision;

    }               meta;

    unsigned int    message_count;

    CDynctrlMessage * messages;

} CDynctrlInfo;



/*
 * Type definitions
 */

typedef void (*CEventHandler)(CHandle hDevice, CEventId event_id, void *context);



/*
 * Functions
 */

#ifdef __cplusplus
extern "C" {
#endif

extern CResult      c_init (void);
extern void         c_cleanup (void);

extern CHandle      c_open_device (const char *device_name);
extern void         c_close_device (CHandle hDevice);

extern CResult      c_enum_devices (CDevice *devices, unsigned int *size, unsigned int *count);
extern CResult      c_get_device_info (CHandle hDevice, const char *device_name, CDevice *info, unsigned int *size);

extern CResult      c_enum_pixel_formats (CHandle hDevice, CPixelFormat *formats, unsigned int *size, unsigned int *count);
extern CResult      c_enum_frame_sizes (CHandle hDevice, const CPixelFormat *pixelformat, CFrameSize *sizes, unsigned int *size, unsigned int *count);
extern CResult      c_enum_frame_intervals (CHandle hDevice, const CPixelFormat *pixelformat, const CFrameSize *framesize, CFrameInterval *intervals, unsigned int *size, unsigned int *count);

extern CResult      c_enum_controls (CHandle hDevice, CControl *controls, unsigned int *size, unsigned int *count);
extern CResult      c_set_control (CHandle hDevice, CControlId control_id, const CControlValue *value);
extern CResult      c_get_control (CHandle hDevice, CControlId control_id, CControlValue *value);

extern CResult      c_enum_events (CHandle hDevice, CEvent *events, unsigned int *size, unsigned int *count);
extern CResult      c_subscribe_event (CHandle hDevice, CEventId event_id, CEventHandler handler, void *context);
extern CResult      c_unsubscribe_event (CHandle hDevice, CEventId event_id);

#ifndef DISABLE_UVCVIDEO_DYNCTRL
extern CResult      c_add_control_mappings_from_file (const char *file_name, CDynctrlInfo *info);
#endif

extern char         *c_get_error_text (CResult error);
extern char         *c_get_handle_error_text (CHandle hDevice, CResult error);

#ifdef __cplusplus
}
#endif


#endif /* C_WEBCAM_H */