libwebcam0-dev 0.2.4-1.1 / usr / include / webcam.h

/**
 * \file
 * Webcam library interface definition.
 *
 * \ingroup libwebcam
 */

/*
 * 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

#include <inttypes.h>
#include <sys/types.h>
#include "dynctrl-logitech.h"
/*
 * Basic type definitions
 */

/// Device handle for libwebcam
typedef unsigned int CHandle;
/// Function return type for libwebcam
typedef unsigned int CResult;



/*
 * Enums
 */

/**
 * Return values for libwebcam functions.
 */
enum _CResults {
	C_SUCCESS				= 0,	///< Success
	C_NOT_IMPLEMENTED,		///< The function is not implemented
	C_INIT_ERROR,			///< Error during initialization or library not initialized
	C_INVALID_ARG,			///< Invalid argument
	C_INVALID_HANDLE,		///< Invalid handle
	C_INVALID_DEVICE,		///< Invalid device or device cannot be opened
	C_NOT_EXIST,			///< The device to which the handle points no longer exists
	C_NOT_FOUND,			///< Object not found
	C_BUFFER_TOO_SMALL,		///< Buffer too small
	C_SYNC_ERROR,			///< Error during data synchronization
	// 10:
	C_NO_MEMORY,			///< Out of memory
	C_NO_HANDLES,			///< Out of handles
	C_V4L2_ERROR,			///< A Video4Linux2 API call returned an unexpected error
	C_SYSFS_ERROR,			///< A sysfs file access returned an error
	C_PARSE_ERROR,			///< A control could not be parsed
	C_CANNOT_WRITE,			///< Writing not possible (e.g. read-only control)
	C_CANNOT_READ,			///< Reading not possible (e.g. write-only control)
	C_INVALID_XU_CONTROL,	///< Invalid XU control has been encountered
	C_SYSTEM_ERROR,			///< An system call returned an unexpected error
	C_DEVICE_BUSY,			///< The device is busy
	// 20:
	C_WRONG_STATE,			///< The requested operation is invalid at this point
	C_INVALID_FORMAT,		///< The requested format is not available or not supported
	C_CONVERSION_ERROR,		///< The format conversion failed (invalid format, buffer size, etc.)
};


/**
 * Control identifiers.
 * This is an exhaustive list of all controls supported by libwebcam. As new
 * controls appear, these should be added to this list.
 */
typedef enum _CControlId {
	// UVC: Basic image control
	CC_BRIGHTNESS		= 1,			///< Image brightness
	CC_CONTRAST,						///< Image contrast
	CC_GAIN,							///< Gain control
	CC_SATURATION,						///< Image color saturation
	CC_HUE,								///< Hue
	CC_GAMMA,							///< Gamma correction
	CC_SHARPNESS,						///< Image sharpness

	// UVC: Advanced image control
	/// White balance color temperature
	CC_WHITE_BALANCE_TEMPERATURE,
	/// Enable/disable automatic while balance color temperature selection
	CC_AUTO_WHITE_BALANCE_TEMPERATURE,
	/// White balance color component control (red, blue)
	CC_WHITE_BALANCE_COMPONENT,
	/// Enable/disable automatic white balance color component selection
	CC_AUTO_WHITE_BALANCE_COMPONENT,
	/// Backlight compensation mode
	CC_BACKLIGHT_COMPENSATION,
	/// Local power line frequency for anti-flicker processing
	CC_POWER_LINE_FREQUENCY,
	/// Enable/disable automatic hue control
	CC_AUTO_HUE,
	/// Mode for automatic exposure control
	CC_AUTO_EXPOSURE_MODE,
	/// Constraints for automatic exposure control (e.g. adaptive vs. constant frame rate)
	CC_AUTO_EXPOSURE_PRIORITY,
	/// Length of exposure (electronic shutter speed)
	CC_EXPOSURE_TIME_ABSOLUTE,
	/// Relative change to the current length of exposure
	CC_EXPOSURE_TIME_RELATIVE,
	/// Auto brightness
	CC_AUTO_BRIGHTNESS,

	// UVC: Optics control
	/// Enable/disable automatic focus adjustment
	CC_AUTO_FOCUS,
	/// Distance to optimally focused target
	CC_FOCUS_ABSOLUTE,
	/// Relative change in distance to currently focused target
	CC_FOCUS_RELATIVE,
	/// Aperture setting
	CC_IRIS_ABSOLUTE,
	/// Relative change to the current aperture setting
	CC_IRIS_RELATIVE,
	/// Objective lens focal length
	CC_ZOOM_ABSOLUTE,
	/// Relative change to the current objective lens focal length
	CC_ZOOM_RELATIVE,
	/// Digital zoom multiplier applied to the optical image
	CC_DIGITAL_ZOOM,

	// UVC: Motion control
	/// Pan angle (rotation on a vertical axis)
	CC_PAN_ABSOLUTE,
	/// Relative change to the current pan angle
	CC_PAN_RELATIVE,
	/// Tilt angle (rotation in a vertical plane)
	CC_TILT_ABSOLUTE,
	/// Relative change to the current tilt angle
	CC_TILT_RELATIVE,
	/// Roll angle (rotation along the image viewing axis)
	CC_ROLL_ABSOLUTE,
	/// Relative change to the current roll angle
	CC_ROLL_RELATIVE,

	// UVC: Misc
	/// Temporarily prevent image from being acquired
	CC_PRIVACY,

	// V4L2: Motion control (new since 2.6.26)
	/// Reset pan angle to a safe default value.
	CC_PAN_RESET,
	/// Reset tilt angle to a safe default value.
	CC_TILT_RESET,

	// V4L2: Unknown controls
	/// Base for unknown V4L2 controls
	CC_V4L2_BASE				= 0x1000,
	/// Base for custom V4L2 driver controls
	CC_V4L2_CUSTOM_BASE			= 0x2000,
	/// Base for unknown V4L2 MPEG controls
	CC_V4L2_MPEG_BASE			= 0x3000,
	/// Base for unknown V4L2 camera class controls
	CC_V4L2_CAMERA_CLASS_BASE	= 0x4000,

	// Logitech (USB vendor ID: 0x046d)
	CC_LOGITECH_BASE = 0x046d0000,
	/// Relative change to the current pan and tilt angles.
	/// This control is specific to Logitech cameras that support panning and
	/// tilting such as the QuickCam Orbit series.
	CC_LOGITECH_PANTILT_RELATIVE,
	/// Reset pan and tilt angles to a safe default value.
	/// This control is specific to Logitech cameras that support panning and
	/// tilting such as the QuickCam Orbit series.
	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,
	//
	CC_LOGITECH_USB_VID,
	//
	CC_LOGITECH_USB_PID,
	//
	CC_LOGITECH_USB_BCD,

	/// Base for raw UVC controls
	CC_UVC_XU_BASE	= 0xFFFF0000,

} CControlId;


/**
 * Flags specifying control properties and capabilities.
 */
typedef enum _CControlFlags {
	/// The control can be read, i.e. its current value can be queried.
	/// This flag is usually not set for action controls.
	CC_CAN_READ				= 1 << 0,
	/// The control can be changed, i.e. it can be set to a new value.
	/// Note that this flag does not imply CC_CAN_READ. Action controls accept
	/// values but cannot necessarily be queried.
	CC_CAN_WRITE			= 1 << 1,
	/// The control supports value change notification.
	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,
    //The control needs to be set (used for save/restore)
    CC_NEED_SET             = 1 << 11,

} CControlFlags;


/**
 * Types for controls.
 * These types give both hints to graphical user interfaces on how to display
 * the control to the user as well as to the implementation in terms of data
 * length required to store control values.
 */
typedef enum _CControlType {
	/// The control uses raw binary data.
	/// Usually (but not necessarily) this includes values that cannot be easily
	/// mapped to simple data types.
	CC_TYPE_RAW				= 1,
	/// The control knows only one enabled/disabled state.
	/// Controls of this type are typically displayed as checkboxes.
	CC_TYPE_BOOLEAN,
	/// The control accepts a defined list of values.
	/// Controls of this type are typically displayed as combo boxes or lists.
	CC_TYPE_CHOICE,
	/// The control accepts 8-bit integer values.
	CC_TYPE_BYTE,
	/// The control accepts 16-bit integer values.
	CC_TYPE_WORD,
	/// The control accepts 32-bit integer values.
	CC_TYPE_DWORD,
	/// The control accepts 32-bit unsigned values.
	CC_TYPE_BUTTON,

} CControlType;


/**
 * Event identifiers.
 */
typedef enum _CEventId {
	CE_CONTROL_INVALID		= 0,

} CEventId;


/**
 * Flags specifying properties of events.
 */
typedef enum _CEventFlags {
	CE_INVALID				= 0,

} CEventFlags;


/**
 * Types of frame size specifications.
 */
typedef enum _CFrameSizeTypes {
	/// One discrete width/height combination.
	CF_SIZE_DISCRETE		= 1,
	/// Minimum and maximum values for both width and height.
	CF_SIZE_CONTINUOUS,
	/// Minimum, maximum, and step values for both width and height.
	CF_SIZE_STEPWISE,

} CFrameSizeTypes;


/**
 * Types of frame interval specification.
 */
typedef enum _CFrameIntervalTypes {
	/// One discrete time interval.
	CF_INTERVAL_DISCRETE		= 1,
	/// Minimum and maximum values for the time interval.
	CF_INTERVAL_CONTINUOUS,
	/// Minimum, maximum, and step values for the time interval.
	CF_INTERVAL_STEPWISE,

} CFrameIntervalTypes;


/**
 * Flags specifying control properties and capabilities.
 */
typedef enum _CDynctrlFlags {
	/// Disable XML schema validation.
	CD_DONT_VALIDATE		= 1 << 0,
	/// Collect errors and warnings during the process
	CD_REPORT_ERRORS		= 1 << 1,
	/// Return meta data during the XML parsing process
	CD_RETRIEVE_META_INFO	= 1 << 2,

} CDynctrlFlags;


/**
 * Severity levels for messages returned by the dynamic control functions
 */
typedef enum _CDynctrlMessageSeverity {
	CD_SEVERITY_ERROR		= 2,		///< Error
	CD_SEVERITY_WARNING		= 3,		///< Warning
	CD_SEVERITY_INFO		= 4,		///< Informational

} CDynctrlMessageSeverity;



/*
 * Structs
 */

/**
 * USB specific information about a device.
 */
typedef struct _CUSBInfo {
	/// The vendor ID.
	unsigned short	vendor;
	/// The product ID.
	unsigned short	product;
	/// The product revision number.
	unsigned short	release;

} CUSBInfo;


/**
 * Webcam device information.
 */
typedef struct _CDevice {
	/// A unique short name.
	/// For V4L2 devices this is the name of the device file. For example, if
	/// a device appears as '/dev/video0', the short name is 'video0'.
	/// This member is never NULL.
	char			* shortName;

	/// The human-readable name of the device.
	/// This member is never NULL.
	char			* name;

	/// The name of the driver providing the camera interface.
	/// This member is never NULL.
	char			* driver;

	/// The location of the camera.
	/// This string is dependent on the implementation that provides the device.
	/// It could either be a string provided by the driver or a device name.
	/// This member is never NULL.
	char			* location;

	/// USB related information about the camera.
	CUSBInfo		usb;

} CDevice;


/**
 * A raw control value.
 */
typedef struct _CControlRawValue {
	/// Pointer to the raw data.
	/// Note: Callers must allocate and free this buffer by themselves.
	void			* data;
	/// Size of the raw data.
	/// For controls of type #CC_TYPE_RAW this size must be at least as big as
	/// the CControl.max.raw.size value of the control in question.
	/// For controls of type #CC_TYPE_STRING this size minus one must be between the
	/// the CControl.string.min_length and CControl.string.max_length values
	/// and must be a multiple of the CControl.string.length_step value.
	unsigned int	size;

} CControlRawValue;


/**
 * A value of a control.
 */
typedef struct _CControlValue {
	/// The type of the control to which the value belongs.
	/// This member is used to determine which of the members of the union are
	/// valid. The type is a duplicate of the corresponding CControl#type value.
	CControlType	type;

	union {
		/// The value of the control for number based controls.
		/// This member is valid for the following control types:
		/// #CC_TYPE_BOOLEAN, #CC_TYPE_CHOICE, #CC_TYPE_BYTE,
		/// #CC_TYPE_WORD, #CC_TYPE_DWORD #CC_TYPE_BUTTON
		int				value;

		/// The value of the control for raw cntrols.
		/// This member is valid only for control type #CC_TYPE_RAW.
		CControlRawValue	raw;

		/// The value of the control for string controls.
		/// This member is valid only for control type #CC_TYPE_STRING.
		CControlRawValue	string;
	};

} CControlValue;


/**
 * A list of choices for a choice type of control.
 * @see CC_TYPE_CHOICE
 */
typedef struct _CControlChoice {
	/// The index of the choice within the list of choices.
	/// Note that this index is not necessarily zero-based and can therefore @a not
	/// be used as an index into CControl#choices#list[].
	int				index;
	int 			id;

	/// The name of the choice.
	/// This member is never NULL.
	char			name[32];

} CControlChoice;


/**
 * A description of a camera control.
 */
typedef struct _CControl {
	/// The identifier of the control
	CControlId		id;
	/// The human-readable name of the control
	char			* name;
	/// The type of the control
	CControlType	type;
	/// Flags describing properties and capabilities of the control
	CControlFlags	flags;

	/// The current value of the control
	CControlValue	value;
	/// The default value of the control
	CControlValue	def;

	union {
		/// Additional control attributes for non-choice controls.
		/// The members of this struct are only valid for control types other
		/// than #CC_TYPE_CHOICE.
		struct {
			/// The minimum value of the control
			CControlValue	min;
			/// The maximum value of the control
			CControlValue	max;
			/// The resolution of the control values
			CControlValue	step;
		};

		/// List of the possible choices that this control allows.
		/// The members of this struct are only valid if the type is #CC_TYPE_CHOICE.
		struct {
			/// The number of choices in the list
			unsigned int	count;
			/// The list of choice values
			CControlChoice	* list;

			/// A buffer that contains the names of the #CControlChoice items.
			/// The @a name fields of the items point to strings within this buffer,
			/// so there is no need to work with this member directly except
			/// freeing the buffer if the control is disposed of.
			//char			* names;

		} choices;

		/// Attributes for string controls.
		/// The members of this struct are only valid if the type is #CC_TYPE_STRING.
		/// Note that the length values do not include the terminating null byte.
		struct {
			/// The minimum number of characters required
			unsigned int	min_length;
			/// The maximum number of characters allowed
			unsigned int	max_length;
			/// The value of which the string length has to be a multiple
			unsigned int	length_step;

		} string;
	};

} CControl;


/**
 * A description of a pixel format.
 */
typedef struct _CPixelFormat {
	/// A FourCC code identifying the pixel format.
	/// Note that this member contains an extra byte which will contain a \\0
	/// character when returned by c_enum_pixel_formats(). This allows the field
	/// to be treated like a NUL terminated string.
	char			fourcc[5];

	/// A human-readable description of the pixel format.
	char			* name;

	/// The MIME type corresponding to the pixel format.
	/// This member can be NULL.
	char			* mimeType;

} CPixelFormat;


/**
 * A description of one or multiple frame sizes.
 */
typedef struct _CFrameSize {
	/// Type of the frame size(s) described (discrete, continuous, step-wise)
	CFrameSizeTypes	type;

	union {
		/// Discrete frame size.
		/// This member is only valid if @a type is #CF_SIZE_DISCRETE.
		struct {
			/// Width
			unsigned int	width;
			/// Height
			unsigned int	height;
		};

		/// Continuous or step-wise frame size.
		/// This member is only valid if @a type is #CF_SIZE_CONTINUOUS or
		/// #CF_SIZE_STEPWISE.
		struct {
			/// Minimum width
			unsigned int	min_width;
			/// Maximum width
			unsigned int	max_width;
			/// Step size for the width (usually 1 if @a type is #CF_SIZE_CONTINUOUS)
			unsigned int	step_width;
			/// Minimum height
			unsigned int	min_height;
			/// Maximum height
			unsigned int	max_height;
			/// Step size for the height (usually 1 if @a type is #CF_SIZE_CONTINUOUS)
			unsigned int	step_height;
		};
	};

} CFrameSize;


/**
 * A description of one or multiple frame intervals.
 * Each frame interval is described as a fraction of a second.
 */
typedef struct _CFrameInterval {
	/// Type of the frame interval(s) described (discrete, continuous, step-wise)
	CFrameIntervalTypes	type;

	union {
		/// Discrete frame interval.
		/// This member is only valid if @a type is #CF_INTERVAL_DISCRETE.
		struct {
			/// Numerator of the frame interval
			unsigned int	n;
			/// Denominator of the frame interval
			unsigned int	d;
		};

		/// Continuous or step-wise frame interval.
		/// This member is only valid if @a type is #CF_INTERVAL_CONTINUOUS or
		/// #CF_INTERVAL_STEPWISE.
		struct {
			/// Numerator of the minimum frame interval
			unsigned int	min_n;
			/// Denominator of the minimum frame interval
			unsigned int	min_d;
			/// Numerator of the maximum frame interval
			unsigned int	max_n;
			/// Denominator of the maximum frame interval
			unsigned int	max_d;
			/// Numerator of the frame interval step size (usually 1 if @a type is #CF_INTERVAL_CONTINUOUS
			unsigned int	step_n;
			/// Denominator of the frame interval step size (usually 1 if @a type is #CF_INTERVAL_CONTINUOUS
			unsigned int	step_d;
		};
	};

} CFrameInterval;


/**
 * An event descriptor.
 */
typedef struct _CEvent {
	/// Unique identifier of the event
	CEventId		id;

	/// Human-readable name of the event
	char			* name;

	/// Flags descripting properties of the event
	CEventFlags		flags;

} CEvent;


/**
 * Message returned by the dynamic control configuration parser.
 */
typedef struct _CDynctrlMessage {
	/// Line number that the message concerns
	int				line;

	/// Column that the message concerns
	int				col;

	/// Severity level
	CDynctrlMessageSeverity	severity;

	/// Pointer to the message text
	char			* text;

} CDynctrlMessage;


/**
 * Version number in the "major.minor" format.
 */
typedef struct _CVersionNumber {
	/// Major version number
	unsigned int	major;

	/// Minor version number
	unsigned int	minor;

} CVersionNumber;


/**
 * Statistics on the number of list elements that were processed.
 */
typedef struct _CDynctrlInfoListStats {
	/// Number of elements in the list that were processed successfully
	unsigned int	successful;

	/// Number of elements in the list that could not be processed successfully
	unsigned int	failed;

} CDynctrlInfoListStats;


/**
 * Input flags and output data used/returned by the control configuration parser.
 */
typedef struct _CDynctrlInfo {
	/// Flags controlling operations related to dynamic controls
	CDynctrlFlags	flags;

	/// Processing statistics
	struct {
		/// Statistics on the constants that were processed
		CDynctrlInfoListStats	constants;

		/// Statistics on the controls that were processed
		CDynctrlInfoListStats	controls;

		/// Statistics on the mappings that were processed
		CDynctrlInfoListStats	mappings;

	}				stats;

	/// Meta information about the XML control configuration
	struct {
		/// File format version
		CVersionNumber	version;

		/// Name of the configuration author
		char			* author;

		/// Contact information of the configuration author (e.g. e-mail address)
		char			* contact;

		/// Copyright information about the configuration file
		char			* copyright;

		/// Revision number of the configuration file (configuration version)
		CVersionNumber	revision;

	}				meta;

	/// Number of messages in the @a messages array
	unsigned int	message_count;

	/// Pointer to the array with the messages concerning the operation
	CDynctrlMessage	* messages;

} CDynctrlInfo;



/*
 * Type definitions
 */

/**
 * Prototype for event handlers
 */
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_save_controls (CHandle hDevice, const char *filename);
extern CResult		c_load_controls (CHandle hDevice, const char *filename);

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);
extern CResult		c_add_control_mappings (CHandle handle, const char *file_name, CDynctrlInfo *info);
extern CResult 		c_read_xu_control(CHandle hDevice, unsigned char entity[], uint16_t unit_id, unsigned char selector, CControlValue *value);
extern CResult 		c_write_xu_control(CHandle hDevice, unsigned char entity[], uint16_t unit_id, unsigned char selector, CControlValue *value);
#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 */