path: root/spectro/inst.h

#ifndef INST_H

 /* instlib API definition. */

 /* See spotread.c, chartread.c, illumread.c & ccxxmake.c for examples of */
 /* the API usage. */

 /* Abstract base class for common color instrument interface */
 /* and other common instrument stuff.                        */

/* 
 * Argyll Color Correction System
 *
 * Author: Graeme W. Gill
 * Date:   15/3/2001
 *
 * Copyright 2001 - 2013 Graeme W. Gill
 * All rights reserved.
 *
 * This material is licenced under the GNU GENERAL PUBLIC LICENSE Version 2 or later :-
 * see the License2.txt file for licencing details.
 *
 */

/* 
   If you make use of the instrument driver code here, please note
   that it is the author(s) of the code who take responsibility
   for its operation. Any problems or queries regarding driving
   instruments with the Argyll drivers, should be directed to
   the Argyll's author(s), and not to any other party.

   If there is some instrument feature or function that you
   would like supported here, it is recommended that you
   contact Argyll's author(s) first, rather than attempt to
   modify the software yourself, if you don't have firm knowledge
   of the instrument communicate protocols. There is a chance
   that an instrument could be damaged by an incautious command
   sequence, and the instrument companies generally cannot and
   will not support developers that they have not qualified
   and agreed to support.
 */

#include "insttypes.h"		/* libinst Includes this functionality */
#include "icoms.h"			/* libinst Includes this functionality */
#include "conv.h"

#ifdef __cplusplus
	extern "C" {
#endif

/* ------------------------------------------------- */
/* aprox. debug level guide:

	1,2  Applications, internal errors
	2,3  High level instrument drivers
	4,5  High level instrument communications
	6,7  High level serial/USB communications
	8,9  Low level serial/USB communications

*/

/* ------------------------------------------------- */
/* Structure for holding an instrument patch reading */

#define ICOM_MAX_LOC_LEN 10

/* Type of measurement result */
typedef enum {						/* XYZ units,      Spectral units */
	inst_mrt_none           = 0,	/* Not set */
	inst_mrt_emission       = 1,	/* cd/m^2,         mW/(m^2.sr.nm) */
	inst_mrt_ambient        = 2,	/* Lux             mW/(m^2.nm) */
	inst_mrt_emission_flash = 3,	/* cd/(m^2.s),     mW/(m^2.sr.nm.s) */
	inst_mrt_ambient_flash  = 4,	/* Lux/s           mW/(m^2.nm.s) */
	inst_mrt_reflective     = 5,	/* %,              %/nm */
	inst_mrt_transmissive   = 6,	/* %,              %/nm */
	inst_mrt_frequency      = 7		/* Hz */
} inst_meas_type;

struct _ipatch {
	char loc[ICOM_MAX_LOC_LEN];	/* patch location */

	inst_meas_type mtype;	/* Measurement type */
	
	int XYZ_v;				/* XYZ valid */
	double XYZ[3];			/* XYZ values */

	xspect sp;			/* Spectrum. sp.spec_n > 0 if valid */
						/* Reflectance/Transmittance 0.0 .. 100.0%, norm = 100.0 */
						/* or mW/nm/m^2, norm = 1.0, etc.  */

	double duration;	/* Apparent total duration in seconds (flash measurement) */
						/* Typicall limited to sampling rate of instrument. */

}; typedef struct _ipatch ipatch;

/* ---------------------------------------- */
/* Instrument interface abstract base class */

/* Abstract return codes in ms byte. */
/* Instrument dependant codes in ls byte. */
/* Note :- update inst_interp_error() in inst.c if anything here is changed. */
/* and also check all the instrument specific XXX_interp_code() routines too. */
typedef enum {
	inst_ok                = 0x000000,
	inst_notify            = 0x010000,	/* A Notification */
	inst_warning           = 0x020000,	/* A Warning */
	inst_no_coms           = 0x030000,	/* init_coms() hasn't been called yet */
	inst_no_init           = 0x040000,	/* init_inst() hasn't been called yet */
	inst_unsupported       = 0x050000,	/* Unsupported function */
	inst_internal_error    = 0x060000,	/* Internal software error */
	inst_coms_fail         = 0x070000,	/* Communication failure */
	inst_unknown_model     = 0x080000,	/* Not the expected instrument */
	inst_protocol_error    = 0x090000, 	/* Read or Write protocol error */
	inst_user_abort        = 0x0A0000,	/* User hit escape */
	inst_user_trig         = 0x0C0000,	/* User hit trigger key */
	inst_misread           = 0x0E0000,	/* Bad reading, or strip misread */
	inst_nonesaved         = 0x0F0000,	/* No saved data to read */
	inst_nochmatch         = 0x100000,	/* Chart doesn't match */
	inst_needs_cal         = 0x110000,	/* Instrument needs calibration, and read retried */
	inst_cal_setup         = 0x120000,	/* Calibration retry with correct setup is needed */
	inst_wrong_config      = 0x130000,	/* Retry with correct inst. config./sensor posn. needed */
	inst_unexpected_reply  = 0x140000,	/* Unexpected Reply */
	inst_wrong_setup       = 0x150000,	/* Setup is wrong or conflicting */
	inst_hardware_fail     = 0x160000,	/* Hardware failure */
	inst_bad_parameter     = 0x170000,	/* Bad parameter value */
	inst_other_error       = 0x180000,	/* Some other error */
	inst_mask              = 0xff0000,	/* inst_code mask value */
	inst_imask             = 0x00ffff	/* instrument specific mask value */
} inst_code;

/* Instrument capabilities & modes */
/* Note that due to the binary combinations, capabilities is not definititive */
/* as to valid modes. check_mode() is definitive. */
typedef enum {
	inst_mode_none               = 0x00000000, /* No capability or mode */

	/* Mode of light measurement */
	inst_mode_reflection         = 0x00000001,	/* General reflection mode */
	inst_mode_s_reflection       = 0x00000002,	/* General saved reflection mode */
	inst_mode_transmission       = 0x00000004,	/* General transmission mode */
	inst_mode_emission           = 0x00000008,	/* General emission mode */
	inst_mode_illum_mask         = 0x0000000f,	/* Mask of sample illumination sub mode */

	/* Access mode of measurement */
	inst_mode_spot               = 0x00000010,	/* General spot measurement mode */
	inst_mode_strip              = 0x00000020,	/* General strip measurement mode */
	inst_mode_xy                 = 0x00000040,	/* General X-Y measurement mode */
	inst_mode_chart              = 0x00000080,	/* General chart measurement mode */
	inst_mode_ambient            = 0x00000100,	/* General ambient measurement mode */
	inst_mode_ambient_flash      = 0x00000200,	/* General ambient flash measurement mode */
	inst_mode_tele               = 0x00000400,	/* General telephoto measurement mode */
	// Hmm. Should there be a tele_flash mode ????
	inst_mode_sub_mask           = 0x000007f0,	/* Mask of sub-mode */

	/* Basic mode */
	inst_mode_basic_mask         = inst_mode_illum_mask | inst_mode_sub_mask,

/*
	possible UV modes:

	Do the reflective measurement with UV rather than normal illuminant
	[ Should this be reflectivity against 'A', or absolute ?? ]
	(ie. spot, strip, xy or chart). inst_mode_ref_uv

	Do a white & UV measurement at the start of each strip reading.
	Return result with special call after each strip read.
	                                inst_mode_ref_uv_strip_1

	Do a dual white & UV measurement
	[ Can do in one hit for spot, but how should two strip passes be handled ?
	  ie. two separate strip reads of phase 1 & then 2 ? ]
	(ie. spot, strip, xy or chart). inst_mode_ref_uv_2pass 

	Get normal illuminant spectrum.
	
	Get UV spectrum.

	                                get_meas_illum_spectrum(mode);
 */

	/* Extra dependent modes */
	inst_mode_emis_nonadaptive   = 0x00000800,	/* Emissom Non-adaptive mode */
	inst_mode_ref_uv             = 0x00001000,	/* Ultra Violet measurement mode */
	inst_mode_emis_refresh_ovd   = 0x00002000,	/* Emissom Refresh mode override */
	inst_mode_emis_norefresh_ovd = 0x00006000,	/* Emissom Non-refresh mode override */
	inst_mode_dep_extra_mask     = 0x00007800,	/* Mask of measurement modifiers */

	/* Extra independent modes */
	inst_mode_colorimeter        = 0x00004000,	/* Colorimetric mode */
	inst_mode_spectral           = 0x00008000,	/* Spectral mode */
	inst_mode_highres            = 0x00010000,	/* High Resolution Spectral mode */
	inst_mode_extra_mask         = 0x0001c000,	/* Mask of extra modes */

	/* Configured for calibration & capable of returning it from inst_mode_calibration */
	inst_mode_calibration        = 0x80000000,	/* Configured for calibration */

	/* Combined operating modes (from above): */
	/* These mode capabilities are also use to set the mode */
	/* Test for a mode should be IMODETST(flags, mode) */
	inst_mode_ref_spot           = inst_mode_spot	/* Reflection spot measurement mode */
	                             | inst_mode_reflection,
	inst_mode_ref_strip          = inst_mode_strip	/* Reflection strip measurement mode */
	                             | inst_mode_reflection,
	inst_mode_ref_xy             = inst_mode_xy		/* Reflection X-Y measurement mode */
	                             | inst_mode_reflection,
	inst_mode_ref_chart          = inst_mode_chart	/* Reflection Chart measurement mode */
	                             | inst_mode_reflection,

	inst_mode_s_ref_spot         = inst_mode_spot	/* Saved reflection spot measurement mode */
	                             | inst_mode_s_reflection,
	inst_mode_s_ref_strip        = inst_mode_strip	/* Saved reflection strip measurement mode */
	                             | inst_mode_s_reflection,
	inst_mode_s_ref_xy           = inst_mode_xy		/* Saved reflection X-Y measurement mode */
	                             | inst_mode_s_reflection,
	inst_mode_s_ref_chart        = inst_mode_chart	/* Saved reflection Chart measurement mode */
	                             | inst_mode_s_reflection,

	inst_mode_trans_spot         = inst_mode_spot	/* Transmission spot measurement mode */
	                             | inst_mode_transmission, 
	inst_mode_trans_strip        = inst_mode_strip	/* Transmission strip measurement mode */
	                             | inst_mode_transmission, 
	inst_mode_trans_xy           = inst_mode_xy		/* Transmission X-Y measurement mode */
	                             | inst_mode_transmission, 
	inst_mode_trans_chart        = inst_mode_chart	/* Transmission chart measurement mode */
	                             | inst_mode_transmission, 

	inst_mode_emis_spot          = inst_mode_spot	/* Spot emission measurement mode */
	                             | inst_mode_emission,
	inst_mode_emis_tele          = inst_mode_tele	/* Telephoto emission measurement mode */
	                             | inst_mode_emission,
	inst_mode_emis_ambient       = inst_mode_ambient	/* Ambient emission measurement mode */
	                             | inst_mode_emission,
	inst_mode_emis_ambient_flash = inst_mode_ambient_flash	/* Ambient emission flash measurement */
	                             | inst_mode_emission,

	inst_mode_emis_strip         = inst_mode_strip	/* Strip emission measurement mode */
	                             | inst_mode_emission,

	inst_mode_measurement_mask   = inst_mode_illum_mask	/* Mask of exclusive measurement modes */
	                             | inst_mode_sub_mask
	                             | inst_mode_dep_extra_mask
} inst_mode;

/* Test for a specific mode */
#define IMODETST(mbits, mode) (((mbits) & (mode)) == (mode))

/* Test for a specific mode in capability and mode */
#define IMODETST2(mcap, mbits, mode) (IMODETST(mcap, mode) && IMODETST(mbits, mode))

/* Instrument capabilities 2 */
/* (Available capabilities may be mode dependent) */
typedef enum {
	inst2_none              = 0x00000000, /* No capabilities */

	inst2_xy_holdrel        = 0x00000001, /* Needs paper hold/release between each sheet */
	inst2_xy_locate         = 0x00000002, /* Needs user to locate patch locations */
	inst2_xy_position       = 0x00000004, /* Can be positioned at a given location */

	inst2_meas_disp_update  = 0x00000010, /* Is able to measure display update delay */

	inst2_get_refresh_rate  = 0x00000020, /* Is able to get the calibrated refresh rate */
	inst2_set_refresh_rate  = 0x00000040, /* Is able to set the calibrated refresh rate */

	inst2_emis_refr_meas    = 0x00000080, /* Has an emissive refresh rate measurement func. */

	inst2_prog_trig         = 0x00000100, /* Progromatic trigger measure capability */
	inst2_user_trig         = 0x00000200, /* User trigger measure capability */
	inst2_switch_trig       = 0x00000400, /* Inst. switch trigger measure capability */
	inst2_user_switch_trig  = 0x00000800, /* User or switch trigger measure capability */

	inst2_bidi_scan         = 0x00001000, /* Try and recognise patches scanned from either dir. */
	inst2_cal_using_switch  = 0x00002000, /* DTP22 special - use switch triggered calibration */
	inst2_has_scan_toll     = 0x00004000, /* Instrument will honour modified scan tollerance */
	inst2_no_feedback       = 0x00008000, /* Instrument doesn't give any user feedback */

	inst2_has_leds          = 0x00200000, /* Instrument has some user viewable indicator LEDs */
	inst2_has_target        = 0x00400000, /* Instrument has aiming target */
	inst2_has_sensmode      = 0x00800000, /* Instrument can report it's sensors mode */

	inst2_has_battery       = 0x01000000, /* Instrument is battery powered */

	inst2_disptype          = 0x02000000, /* Has a display type selector */
	inst2_ccmx              = 0x04000000, /* Colorimeter Correction Matrix capability */
	inst2_ccss              = 0x08000000, /* Colorimeter Cal. Spectral Set capability */

	inst2_ambient_mono      = 0x10000000, /* The ambient measurement is monochrome */

	inst2_ambient_cardioid  = 0x20000000, /* The ambient measurement has a cardioid response */

	inst2_get_min_int_time  = 0x40000000, /* Is able to get the minimum integration time */
	inst2_set_min_int_time  = 0x80000000  /* Is able to set the minimum integration time */

} inst2_capability;

/* Instrument capabilities 3 (room for expansion) */
/* (Available capabilities may be mode dependent) */
typedef enum {
	inst3_none              = 0x00000000, /* No capabilities */

} inst3_capability;

typedef enum {
	inst_dtflags_none    = 0x0000,			/* no flags */
	inst_dtflags_default = 0x0001,			/* default display type */
	inst_dtflags_ccss    = 0x0002,			/* ccss */
	inst_dtflags_ccmx    = 0x0004,			/* ccmx */
	inst_dtflags_end     = 0x8000			/* end marker */
} inst_dtflags;

#define INST_DTYPE_SEL_LEN 10
#define INST_DTYPE_DESC_LEN 100

/* Structure used to return display type selection information */
typedef struct _inst_disptypesel {

  /* Public: */
	inst_dtflags flags;		/* Attribute flags */
	int cbid;				/* Calibration base ID. NZ if valid ccmx calibration base. */
							/* Should remain constant between releases */
	char sel[INST_DTYPE_SEL_LEN];	/* String of selector character aliases */
	char desc[INST_DTYPE_DESC_LEN];	/* Textural description */
	int  refr;				/* Refresh mode flag */

  /* Private: */
	int ix;					/* Internal index,  */

	// Stuff for ccss & ccmx
	char *path;				/* Path to ccss or ccmx */
	double mat[3][3];		/* ccmx matrix */
	xspect *sets;   		/* ccss set of sample spectra */
	int no_sets;    		/* ccs number of sets */

} inst_disptypesel;

/* Instrument options for get_set_opt() */
typedef enum {
	inst_opt_unknown            = 0x0000,	/* Option not specified */

	inst_stat_saved_readings    = 0x0001,	/* Return status of saved reading values */ 
											/* [1 argument type *inst_stat_savdrd] */
	inst_stat_s_spot            = 0x0002,	/* Return number of saved spot readings */ 
											/* [1 argument type *int] */
	inst_stat_s_strip           = 0x0003,	/* Return saved strip details */
											/* [args: int *no_patches, int *no_rows */
	                                        /*        int *pat_per_row] */
	inst_stat_s_xy              = 0x0004,	/* Return saved strip details */
											/* [args: int *no_sheets, int *no_patches, */
	                                        /*        int *no_rows, int *pat_per_row] */
	inst_stat_s_chart           = 0x0005,	/* Return number saved chart details */
											/* [args: int *no_patches, int *no_rows    */
	                                        /*        int *pat_per_row, int *chart_id, */
											/*        int *missing_row ]               */

	inst_stat_battery           = 0x0006,	/* Return charged status of battery */
											/* [1 argument type *double : range 0.0 - 1.0 ] */

	inst_stat_get_filter        = 0x0007,	/* Get a filter configuration */
											/* [1 argument type *inst_opt_filter ] */

	inst_opt_initcalib          = 0x0008,	/* Enable initial calibration (default) [No args] */
	inst_opt_noinitcalib        = 0x0009,	/* Disable initial calibration if < losecs since last */											/* opened, or losecs == 0 [int losecs] */

	inst_opt_set_ccss_obs       = 0x000A,	/* Set the observer used with ccss device types - */
											/* Not applicable to any other type of instrument. */
											/* [args: icxObserverType obType,*/
	                                        /*        xspect custObserver[3] */

	inst_opt_get_dtinfo         = 0x000C,	/* Get current display type information */
											/* [args: int *refrmode,*/
	                                        /*        int *cbid] */

	inst_opt_set_filter         = 0x000D,	/* Set a filter configuration */
											/* [1 argument type inst_opt_filter] */

	inst_opt_trig_prog          = 0x000E,	/* Trigger progromatically [No args] */
	inst_opt_trig_user          = 0x000F,	/* Trigger from user via uicallback [No args] */
	inst_opt_trig_switch        = 0x0010,	/* Trigger using instrument switch [No args] */
	inst_opt_trig_user_switch   = 0x0011,	/* Trigger from user via uicallback or switch (def) [No args] */

	inst_opt_highres            = 0x0012,	/* Enable high res spectral mode indep. of set_mode() */
	inst_opt_stdres             = 0x0013,	/* Revert to standard resolution spectral mode */

	inst_opt_scan_toll          = 0x0014,	/* Modify the patch scan recognition tollnce [double] */

	inst_opt_get_gen_ledmask    = 0x0015,	/* Get the bitmask for general indication LEDs [*int] */
											/* (More specialized indicator masks go here) */
	inst_opt_set_led_state      = 0x0016,	/* Set the current LED state. 0 = off, 1 == on [int] */
	inst_opt_get_led_state      = 0x0017,	/* Get the current LED state. 0 = off, 1 == on [*int] */
	inst_opt_get_pulse_ledmask  = 0x0018,	/* Get the bitmask for pulseable ind. LEDs [*int] */
	inst_opt_set_led_pulse_state= 0x0019,	/* Set the current LED state. [double period_in_secs, */
	                                        /* double on_time_prop, double trans_time_prop] */
	inst_opt_get_led_pulse_state= 0x001A,	/* Get the current pulse LED state. [*double period] */
	inst_opt_set_target_state   = 0x001B,	/* Set the aiming target state 0 = off, 1 == on, 2 = toggle [int] */

	inst_opt_get_min_int_time   = 0x001C,	/* Get the minimum integration time [*double time] */
	inst_opt_set_min_int_time   = 0x001D	/* Set the minimum integration time [double time] */

} inst_opt_type;

/* Optional filter fitted to instrument (for inst_opt_set_filter) */
typedef enum {
	inst_opt_filter_unknown  = 0xffff,	/* Unspecified filter */
	inst_opt_filter_none     = 0x0000,	/* No filters fitted */
	inst_opt_filter_pol      = 0x0001,	/* Polarising filter */ 
	inst_opt_filter_D65      = 0x0002,	/* D65 Illuminant filter */
	inst_opt_filter_UVCut    = 0x0004,	/* U.V. Cut filter */
	inst_opt_filter_Custom   = 0x0008	/* Custom Filter */
} inst_opt_filter;

/* Off-line pending readings available (status) */
typedef enum {
	inst_stat_savdrd_none    = 0x00,		/* No saved readings */
	inst_stat_savdrd_spot    = 0x01,		/* There are saved spot readings available */
	inst_stat_savdrd_strip   = 0x02,		/* There are saved strip readings available */
	inst_stat_savdrd_xy      = 0x04,		/* There are saved page readings available */
	inst_stat_savdrd_chart   = 0x08			/* There are saved chart readings available */
} inst_stat_savdrd;

/* Type of calibration needed/available/requested - corresponds to capabilities */
/* [ inst_calt_trans_vwhite is "variable" white transmission calibration, needed */
/*   where transmission mode is being emulated. ] */
typedef enum {
	/* Response to needs_calibration() */
	inst_calt_none           = 0x00000000, 	/* No calibration or unknown */

	/* Psudo-calibration types */
	inst_calt_all            = 0x00000001, 	/* Do required non-deferable cals for mode, but also */
										    /* do all possible calibrations for all other modes */
										    /* using the calibration conditions. This may be slow */
	/* Hmm. We don't have an "calt_all_needed" - do all needed cals of all possible modes. */
	/* This might be more useful than inst_calt_all ? */
	inst_calt_needed         = 0x00000002, 	/* Do all required non-deferable cals for c.m. */
	inst_calt_available      = 0x00000003, 	/* Do all available non-deferable cals for c.m. */

	/* Specific type of calibration - corresponds to capabilities  */
	inst_calt_wavelength     = 0x00000010, 	/* Wavelength calibration using refl. cal. surface */ 
	inst_calt_ref_white      = 0x00000020, 	/* Reflective white/emissive dark calibration */
	inst_calt_ref_dark       = 0x00000040, 	/* Reflective dark calibration (in dark) */
	inst_calt_emis_offset    = 0x00000080, 	/* Emissive offset/black calibration (dark surface) */
	inst_calt_emis_ratio     = 0x00000100, 	/* Emissive ratio calibration */
	inst_calt_em_dark        = 0x00000200, 	/* Emissive dark calibration (in dark) */
	inst_calt_trans_white    = 0x00000400,	/* Transmissive white reference calibration */
	inst_calt_trans_vwhite   = 0x00000800,	/* Transmissive variable white reference calibration */
	inst_calt_trans_dark     = 0x00001000,	/* Transmissive dark reference calibration */

	inst_calt_n_dfrble_mask  = 0x0000fff0,	/* Mask of non-deferrable calibrations */

	/* Calibrations that might be deferred until measurement */
	inst_calt_emis_int_time  = 0x00100000, 	/* Emissive measurement range (integration time) */
	inst_calt_ref_freq       = 0x00200000, 	/* Display refresh frequency calibration */

	inst_calt_dfrble_mask    = 0x00f00000, 	/* Mask of deferrable calibrations */

	inst_calt_all_mask       = 0x00f0fff0, 	/* Mask of all specific calibrations */

	inst_calt_ap_flag        = 0x80000000	/* Implementation flag indicating do all possible */

} inst_cal_type;

/* Calibration conditions. */
/* This is how the instrument communicates to the calling program */
/* about how to facilitate a calibration, or what it's current measurement */
/* configuration provides. */
/* [There is no provission for explictly indicating calibrations that can be */
/* performed automatically and transparently by the instrument - for instance */
/* in the case of the spectroscan, since the required condition can be obtained */
/* without the users interaction. ] */
typedef enum {
	inst_calc_none             = 0x00000000, /* Not suitable for calibration */
	inst_calc_unknown          = 0xffffffff, /* Unknown calibration setup */

							/* uop means that user has to trigger the within instrument */
							/* calibration using its "front panel" or other direct keys */
	inst_calc_uop_ref_white    = 0x00000001, /* user operated reflective white calibration */
	inst_calc_uop_trans_white  = 0x00000002, /* user operated tranmissive white calibration */
	inst_calc_uop_trans_dark   = 0x00000003, /* user operated tranmissive dark calibration */
	inst_calc_uop_mask         = 0x0000000F, /* user operated calibration mask */

							/* Man means that the user has to manualy configure the instrument */
							/* to be on the correct reference for the software triggered cal. */
	inst_calc_man_ref_white    = 0x00000010, /* place instrument on reflective white reference */
	inst_calc_man_ref_whitek   = 0x00000020, /* click instrument on reflective white reference */
	inst_calc_man_ref_dark     = 0x00000030, /* place instrument in dark, not close to anything */
	inst_calc_man_em_dark      = 0x00000040, /* place cap on instrument, put on dark surface or white ref. */
	inst_calc_man_am_dark      = 0x00000050, /* Place cap over ambient sensor (wl calib capable) */
	inst_calc_man_cal_smode    = 0x00000060, /* Put instrument sensor in calibration position */

	inst_calc_man_trans_white  = 0x00000070, /* place instrument on transmissive white reference */
	inst_calc_man_trans_dark   = 0x00000080, /* place instrument on transmissive dark reference */
	inst_calc_man_man_mask     = 0x000000F0, /* user configured calibration mask */ 

	inst_calc_emis_white       = 0x00000100, /* Provide a white test patch */
	inst_calc_emis_80pc        = 0x00000200, /* Provide an 80% white test patch */
	inst_calc_emis_grey        = 0x00000300, /* Provide a grey test patch */
	inst_calc_emis_grey_darker = 0x00000400, /* Provide a darker grey test patch */
	inst_calc_emis_grey_ligher = 0x00000500, /* Provide a darker grey test patch */

	inst_calc_emis_mask        = 0x00000F00, /* Emmissive/display provided reference patch */

	inst_calc_change_filter    = 0x00010000, /* Filter needs changing on device - see id[] */
	inst_calc_message          = 0x00020000  /* Issue a message. - see id[] */
} inst_cal_cond;

/* Clamping state */
typedef enum {
    instNoClamp			= 0,	/* Don't clamp XYZ/Lab to +ve */
    instClamp			= 1,	/* Clamp XYZ/Lab to +ve */
} instClamping;

/* User interaction callback function purpose */
typedef enum {
    inst_negcoms,		/* Negotiating communications */
    inst_triggered,		/* Measurement has been triggered by switch or user (not progromatic) */
    inst_armed,			/* Armed and waiting for a measurement trigger */
    inst_measuring		/* Busy measuring */
} inst_ui_purp;

/* Asynchronous event callback type */
typedef enum {
    inst_event_switch,	/* Instrument measure/calibrate switch pressed */
    inst_event_mconf	/* Change in measurement configuration (ie. sensor position) */
} inst_event_type;

/* Instrument configuration/sensor position*/
typedef enum {
    inst_conf_unknown,
    inst_conf_projector,
    inst_conf_surface,	
    inst_conf_emission,	
	inst_conf_calibration,
	inst_conf_ambient
} inst_config;

/* Off-line pending readings available (status) */
#define CALIDLEN 200	/* Maxumum length of calibration tile ID string */

/* Color instrument interface base object */
/* Note that some methods work after creation, while many */
/* will return an error if communications hasn't been established and */
/* the instrument initialised. Some may change their response before and */
/* after initialisation. */
#define INST_OBJ_BASE															\
																				\
	a1log *log;			/* Pointer to debug & error logging class */			\
	instType  itype;	/* Instrument type determined by driver */				\
	icoms *icom;		/* Instrument coms object */							\
	int gotcoms;		/* Coms established flag */                             \
	int inited;			/* Instrument open and initialized flag */              \
	double cal_gy_level; /* Display calibration test window state */			\
	int cal_gy_count;	/* Display calibration test window state */				\
	inst_code (*uicallback)(void *cntx, inst_ui_purp purp);						\
	void *uic_cntx;		/* User interaction callback function */				\
	void (*eventcallback)(void *cntx, inst_event_type event);					\
	void *event_cntx;	/* Event callback function */							\
																				\
	/* Establish communications at the indicated baud rate. */					\
	/* (Serial parameters are ignored for USB instrument) */					\
	/* Timout in to seconds, and return non-zero error code */					\
	inst_code (*init_coms)(														\
        struct _inst *p,														\
        baud_rate br,		/* Baud rate */										\
        flow_control fc,	/* Flow control */									\
        double tout);		/* Timeout */										\
																				\
	/* Initialise or re-initialise the INST */									\
	/* return non-zero on an error, with inst error code */						\
	inst_code (*init_inst)(  													\
        struct _inst *p);														\
																				\
	/* Return the instrument type */											\
	/* (this could concievably change after init_inst()) */						\
	/* Can be called before init */												\
	instType (*get_itype)(  													\
        struct _inst *p);														\
																				\
	/* Return the instrument serial number. */									\
	/* (This will be an empty string if there is no serial no) */               \
	char *(*get_serial_no)(  													\
        struct _inst *p);														\
																				\
	/* Return the avilable instrument modes and capabilities. */				\
	/* Can be called before init, but may be different to */					\
	/* what's returned after initilisation. */									\
	/* Note that these may change with the mode. */								\
	/* Arguments may be NULL */													\
	void (*capabilities)(struct _inst *p,										\
	        inst_mode *cap1,													\
	        inst2_capability *cap2,												\
	        inst3_capability *cap3);											\
																				\
	/* Return current or given configuration available measurement modes. */	\
	/* Most instruments have only one detectable configuration. */				\
	/* If conf_ix == NULL or *conf_ix is an invalid configuration index, */		\
	/* then the current configuration modes are returned. */					\
	/* Otherwise the given configuration index is returned. */					\
	/* The i1d3 has 2, the Munki has 4, one being calibration. */				\
	/* *cconds is valid if *mmodes = inst_mode_calibration */					\
	inst_code (*meas_config)(struct _inst *p,									\
			inst_mode *mmodes,	/* Return all the valid measurement modes */	\
								/* for the current configuration */				\
			inst_cal_cond *cconds,	/* Return the valid calibration conditions */		\
			int *conf_ix);		/* Request mode for given configuration, and */			\
	                            /* return the index of the configuration returned */	\
																				\
    /* Check that the particular device measurement mode is valid, */           \
	/* since it's not possible to be 100% sure from capabilities */				\
    inst_code (*check_mode)(													\
        struct _inst *p,														\
        inst_mode m);		/* Requested mode */								\
																				\
    /* Set the device measurement mode */                                       \
	/* Note that this may change the capabilities. */							\
    inst_code (*set_mode)(														\
        struct _inst *p,														\
        inst_mode m);		/* Requested mode */								\
																				\
	/* Return array of display type selectors */								\
	inst_code (*get_disptypesel)(												\
        struct _inst *p,														\
		int *no_selectors,		/* Return number of display types */			\
		inst_disptypesel **sels,/* Return the array of display types */			\
		int allconfig,			/* nz to return list for all configs, not just current. */	\
		int recreate);			/* nz to re-check for new ccmx & ccss files */	\
																				\
	/* Set the display type. index is into the inst_disptypesel[] returned */   \
	/* returned by get_disptypesel(). clears col_cor_mat() */					\
	inst_code (*set_disptype)(													\
        struct _inst *p,														\
		int index);                                                             \
	                                                                            \
    /* Get a status or get or set an option */                                  \
	/* option state. */															\
	/* Some options can be set before init */									\
	/* See inst_opt_type typedef for list of mode types */						\
    inst_code (*get_set_opt)(													\
        struct _inst *p,														\
        inst_opt_type m,	/* Requested option mode */							\
		...);				/* Option parameters */                             \
																				\
	/* Read a full test chart composed of multiple sheets */					\
	/* DOESN'T use the trigger mode */											\
	/* Return the inst error code */											\
	inst_code (*read_chart)(													\
		struct _inst *p,														\
		int npatch,			/* Total patches/values in chart */					\
		int pich,			/* Passes (rows) in chart */						\
		int sip,			/* Steps in each pass (patches in each row) */		\
		int *pis,			/* Passes in each strip (rows in each sheet) */		\
		int chid,			/* Chart ID number */								\
		ipatch *vals);		/* Pointer to array of values */					\
																				\
																				\
	/* For an xy instrument, release the paper */								\
	/* (if cap has inst_xy_holdrel) */											\
	/* Return the inst error code */											\
	inst_code (*xy_sheet_release)(												\
		struct _inst *p);														\
																				\
	/* For an xy instrument, hold the paper */									\
	/* (if cap has inst_xy_holdrel) */											\
	/* Return the inst error code */											\
	inst_code (*xy_sheet_hold)(													\
		struct _inst *p);														\
																				\
	/* For an xy instrument, allow the user to locate a point */				\
	/* (if cap has inst_xy_locate) */											\
	/* Return the inst error code */											\
	inst_code (*xy_locate_start)(												\
		struct _inst *p);														\
																				\
	/* For an xy instrument, read back the location */							\
	/* (if cap has inst_xy_locate) */											\
	/* Return the inst error code */											\
	inst_code (*xy_get_location)(												\
		struct _inst *p,														\
		double *x, double *y);													\
																				\
	/* For an xy instrument, end allowing the user to locate a point */			\
	/* (if cap has inst_xy_locate) */											\
	/* Return the inst error code */											\
	inst_code (*xy_locate_end)(													\
		struct _inst *p);														\
																				\
	/* For an xy instrument, move the measurement point */						\
	/* (if cap has inst_xy_position) */											\
	/* Return the inst error code */											\
	inst_code (*xy_position)(													\
		struct _inst *p,														\
		int measure,	/* nz for measure point, z for locate point */	        \
		double x, double y);													\
																				\
	/* For an xy instrument, try and clear the table after an abort */			\
	/* Return the inst error code */											\
	inst_code (*xy_clear)(														\
		struct _inst *p);														\
																				\
	/* Read a sheet full of patches using xy mode */							\
	/* DOESN'T use the trigger mode */											\
	/* Return the inst error code */											\
	inst_code (*read_xy)(														\
		struct _inst *p,														\
		int pis,			/* Passes in strips (letters in sheet) */			\
		int sip,			/* Steps in pass (numbers in sheet) */				\
		int npatch,			/* Total patches in strip (skip in last pass) */	\
		char *pname,		/* Starting pass name (' A' to 'ZZ') */             \
		char *sname,		/* Starting step name (' 1' to '99') */             \
		double ox, double oy,	/* Origin of first patch */						\
		double ax, double ay,	/* pass increment */							\
		double aax, double aay,	/* pass offset for odd patches */				\
		double px, double py,	/* step/patch increment */						\
		ipatch *vals);		/* Pointer to array of values */					\
																				\
																				\
	/* Read a set of strips (applicable to strip reader) */						\
	/* Obeys the trigger mode set, and may return user trigger code */			\
	/* (to hint that a user command may be available) */						\
	/* Return the inst error code */											\
	inst_code (*read_strip)(													\
		struct _inst *p,														\
		char *name,			/* Strip name (up to 7 chars) */					\
		int npatch,			/* Number of patches in each pass */				\
		char *pname,		/* Pass name (3 chars) */							\
		int sguide,			/* Guide number (decrements by 5) */				\
		double pwid,		/* Patch width in mm (For DTP20/DTP41) */			\
		double gwid,		/* Gap width in mm  (For DTP20/DTP41) */			\
		double twid,		/* Trailer width in mm  (For DTP41T) */				\
		ipatch *vals);		/* Pointer to array of values */					\
																				\
																				\
	/* Read a single sample (applicable to spot instruments) */					\
	/* Obeys the trigger mode set, and may return user trigger code */			\
	/* Values are in XYZ 0..100 for reflective transmissive, */					\
	/* aXYZ in cd/m^2 for emissive, amd Lux/3.1415926 for ambient. */			\
	/* Spectral will be analogous to the XYZ. */								\
	/* By default values may be -ve due to noise (depending on instrument) */	\
	/* Return the inst error code */											\
	inst_code (*read_sample)(													\
		struct _inst *p,														\
		char *name,				/* Patch identifier (up to 7 chars) */			\
		ipatch *val,			/* Pointer to value to be returned */			\
		instClamping clamp);	/* NZ to clamp XYZ to be +ve */					\
																				\
	/* Measure the emissive refresh rate in Hz. */								\
	/* (Available if cap2 & inst2_emis_refr_meas) */ 							\
	/* Returns: */																\
	/* inst_unsupported - if this instrument doesn't suport this measuremet */	\
	/*                    or not in an emissive measurement mode */				\
	/* inst_misread     - if no refresh rate could be determined */				\
	/* inst_ok          - on returning a valid reading */						\
	inst_code (*read_refrate)(											        \
		struct _inst *p,														\
		double *ref_rate);		/* Return the Hz */								\
																				\
	/* Determine if a calibration is needed. Returns inst_calt_none if not */	\
	/* or unknown, or a mask of the needed calibrations. */						\
	/* This call checks if calibrations are invalid or have timed out. */		\
	/* With the exception of instruments with automated calibration */			\
	/* (ie. SpectroScan), an instrument will typically */						\
	/* not check for calibration timout any other way. */						\
	/* [What's returned is the same as get_n_a_cals() [ needed_calibrations.] */\
	inst_cal_type (*needs_calibration)(											\
		struct _inst *p);														\
																				\
	/* Return combined mask of needed and available inst_cal_type's */			\
	/* for the current mode. */													\
	inst_code (*get_n_a_cals)(													\
		struct _inst *p,														\
		inst_cal_type *needed_calibrations,										\
		inst_cal_type *available_calibrations);									\
																				\
	/* Request an instrument calibration. */									\
	/* This is use if the user decides they want to do a calibration */			\
	/* in anticipation of a calibration (needs_calibration()) to avoid */		\
	/* requiring one during measurement, or in response to measuring */			\
	/* returning inst_needs_cal before retrying the measurement, */				\
	/* or to do one or more re-calibrations. */									\
																				\
	/* *calt should contain the mask of calibrations to be performed, */		\
	/* with *calc set to the current calibration condition. */					\
	/* Alternately, one of the psudo-calibration types inst_calt_all, */		\
	/* inst_calt_needed or inst_calt_available can be used, */			\
	/* and/or the *calc of inst_calc_none to get calibrate() */					\
	/* to determine the required calibration types and conditions. */			\
	/* (The corresponding calibration types will be used & returned. */			\
																				\
	/* If no error is returned to the first call to calibrate() with */			\
	/* then the instrument was capable of calibrating without user or */		\
	/* application intervention. If on the other hand calibrate() returns */	\
	/* inst_cal_setup, then the appropriate action indicated by the value */	\
	/* returned in *calc should be taken by the user or application, */			\
	/* before retrying calibration() with the current setup indicated */		\
	/* by *calc. If more than one calibration type is requested, then */		\
	/* several retries may be needed with different calibration conditions. */	\
 	/* Each call to calibrate() will update *calt to reflect the remaining */	\
	/* calibration to be performed.  calibrate() returns inst_ok when no */		\
	/* more calibrations remain. */												\
																				\
	/* DOESN'T use the trigger mode */											\
	/* Return inst_unsupported if *calt is not appropriate, */					\
	/* inst_cal_setup if *calc is not appropriate. */							\
	inst_code (*calibrate)(														\
		struct _inst *p,														\
		inst_cal_type *calt,	/* Calibration type to do/remaining */			\
		inst_cal_cond *calc,	/* Current condition/desired condition */		\
		char id[CALIDLEN]);		/* Condition identifier (ie. white */			\
								/* reference ID, filter ID) */					\
																				\
	/* Measure a display update delay. It is assumed that a */  				\
	/* White to black change has been made to the displayed color, */     		\
	/* and this will measure the time it took for the update to */              \
	/* be noticed by the instrument, up to 1.0 seconds. */               		\
	/* inst_misread will be returned on failure to find a transition to black. */ \
	inst_code (*meas_delay)(											        \
		struct _inst *p,														\
		int *msecdelay);		/* Return the number of msec */					\
																				\
	/* Return the last calibrated refresh rate in Hz. Returns: */				\
	/* (Available if cap2 & inst2_get_refresh_rate) */ 							\
	/* inst_unsupported - if this instrument doesn't suport a refresh mode */	\
	/*                    or is unable to retrieve the refresh rate */			\
	/* inst_needs_cal   - if the refresh rate value is not valid */				\
	/* inst_misread     - if no refresh rate could be determined */				\
	/* inst_ok          - on returning a valid reading */						\
	inst_code (*get_refr_rate)(											        \
		struct _inst *p,														\
		double *ref_rate);		/* Return the Hz */								\
																				\
	/* Set the calibrated refresh rate in Hz. */								\
	/* (Available if cap2 & inst2_set_refresh_rate) */ 							\
	/* Set refresh rate to 0.0 to mark it as invalid */							\
	/* Rates outside the range 5.0 to 150.0 Hz will return an error */			\
	/* Note that not all instruments that can return a refresh rate, */			\
	/* will permit one to be set (ie., DTP92) */								\
	inst_code (*set_refr_rate)(											        \
		struct _inst *p,														\
		double ref_rate);		/* Rate in Hz */								\
																				\
	/* Insert a compensation filter in the instrument readings */				\
	/* This is typically needed if an adapter is being used, that alters */     \
	/* the spectrum of the light reaching the instrument */                     \
	/* Not fully implemented across all instrument types (spectrolino only ?) */ \
	/* To remove the filter, pass NULL for the filter filename */               \
	inst_code (*comp_filter)(											        \
		struct _inst *p,														\
		char *filtername);		/* File containing compensating filter */		\
																				\
	/* Insert a colorimetric correction matrix in the instrument XYZ readings */ \
	/* This is only valid for colorimetric instruments, and can only be */		\
	/* applied over a base calibration display type. Setting a display */		\
	/* type will clear the matrix. */											\
	/* To clear the matrix, pass NULL for the matrix */							\
	inst_code (*col_cor_mat)(											        \
		struct _inst *p,														\
		double mtx[3][3]);		/* XYZ matrix */								\
																				\
	/* Use a Colorimeter Calibration Spectral Set (ccss) to set the */			\
	/* instrumen calibration. This will affect emissive readings. */			\
	/* An alternate observer may also be set, and this will affect both */		\
	/* emissive and ambient readings. */										\
	/* This is only valid for colorimetric instruments. */						\
	/* To set calibration back to default, pass NULL for sets, and */			\
	/* icxOT_default for the observer. */										\
	inst_code (*col_cal_spec_set)(												\
		struct _inst *p,														\
		xspect *sets,			/* Set of sample spectra */						\
		int no_sets);	 		/* Number on set */								\
																				\
	/* Supply a user interaction callback function.								\
	 * This is called for one of three different purposes:						\
	 *	To signal that the instrument measurement has been triggered.			\
	 *	To poll for a abort while waiting to trigger.							\
	 *	To poll for a user abort during measurement.							\
	 *																			\
	 * The callback function will have the purpose paramater appropriately.		\
	 *																			\
     * For inst_negcoms, the return value of inst_user_abort					\
	 * will abort the communication negotiation									\
	 *																			\
	 * For inst_triggered, the return value of the callback is ignored.			\
	 *																			\
	 * For inst_armed return value should be one of: 							\
	 * inst_ok to do nothing, inst_user_abort to abort the measurement,			\
	 * or inst_user_trig to trigger the measurement.							\
	 *																			\
	 * For inst_measuring the return value should be one of:					\
	 * inst_ok to do nothing, inst_user_abort to abort the measurement.			\
	 *																			\
	 * NULL can be set to disable the callback.									\
	 */																			\
	void (*set_uicallback)(struct _inst *p,										\
		inst_code (*uicallback)(void *cntx, inst_ui_purp purp), 				\
		void *cntx);															\
																				\
	/* Supply an aynchronous event callback function.							\
	 * This is called from a thread with the following possible events:			\
	 *																			\
	 * inst_event_switch: Instrument measure/calibrate switch pressed 			\
	 * inst_event_mconf: The measurement configuration has changed (ie. sensor position)	\
	 *																			\
	 * NULL can be set to disable the callback.									\
	 */																			\
	void (*set_event_callback)(struct _inst *p,									\
		void (*eventcallback)(void *cntx, inst_event_type event),				\
		void *cntx);															\
																				\
	/* Generic inst error codes interpretation */								\
	char * (*inst_interp_error)(struct _inst *p, inst_code ec);					\
																				\
	/* Instrument specific error codes interpretation */						\
	char * (*interp_error)(struct _inst *p, int ec);							\
																				\
	/* Convert instrument specific inst_wrong_config error to inst_config enum */	\
	inst_config (*config_enum)(struct _inst *p, int ec);							\
																				\
	/* Return the last serial communication error code */						\
	/* (This is used for deciding fallback/retry strategies) */					\
	int (*last_scomerr)(struct _inst *p);										\
																				\
	/* Destroy ourselves */														\
	void (*del)(struct _inst *p);												\

/* The base object type */
struct _inst {
	INST_OBJ_BASE
	}; typedef struct _inst inst;

/* Virtual constructor. */
/* Return NULL for unknown instrument, */
/* or serial instrument if nocoms == 0. */
/* (Doesn't copy icompaths log!) */
/* If uicallback is provided, it will be set in the resulting inst */
extern inst *new_inst(
	icompath *path,		/* Device path this instrument */
	int nocoms,			/* Don't open if communications are needed to establish inst type */
	a1log *log,			/* Log to use */
	inst_code (*uicallback)(void *cntx, inst_ui_purp purp),		/* optional uicallback */
	void *cntx			/* Context for callback */
);

/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
/* Implementation functions used by drivers */

/* Get a status or set or get an option (default implementation) */
inst_code inst_get_set_opt_def(
inst *p,
inst_opt_type m,	/* Option type */
va_list args);		/* Option parameters */                             

/* - - - - - - - - - - - - - - - - - - -- */

/* Create the display type list */
inst_code inst_creat_disptype_list(inst *p,
int *pndtlist,					/* Number in returned list */
inst_disptypesel **pdtlist,		/* Returned list */
inst_disptypesel *sdtlist,		/* Static list */
int doccss,						/* Add installed ccss files */
int doccmx						/* Add matching installed ccmx files */
);

/* Free a display type list */
void inst_del_disptype_list(inst_disptypesel *list, int no);


/* - - - - - - - - - - - - - - - - - - -- */
/* CCMX support */

typedef struct {
	char *path;			/* Path to the file */
	char *desc;			/* Technology + display description */
	int cbid;       	/* Calibration display type base ID */
	int  refr;			/* Refresh mode flag */
	char *sel;			/* UI selector characters (may be NULL) */
	double mat[3][3];	/* The matrix values */
} iccmx;

/* return a list of installed ccmx files. */
/* if inst != NULL, return those that match the given instrument. */
/* The list is sorted by description and terminated by a NULL entry. */
/* If no is != NULL, return the number in the list */
/* Return NULL and -1 if there is a malloc error */
iccmx *list_iccmx(char *inst, int *no);

/* Free up a iccmx list */
void free_iccmx(iccmx *list);

/* - - - - - - - - - - - - - - - - - - -- */
/* CCSS support */

typedef struct {
	char *path;			/* Path to the file */
	char *desc;			/* Technology + display description */
	int  refr;			/* Refresh mode flag */
	char *sel;			/* UI selector characters (may be NULL) */
	xspect *sets;		/* Set of sample spectra */
	int no_sets;		/* Number on set */
} iccss;

/* return a list of installed ccss files. */
/* The list is sorted by description and terminated by a NULL entry. */
/* If no is != NULL, return the number in the list */
/* Return NULL and -1 if there is a malloc error */
iccss *list_iccss(int *no);

/* Free up a iccss list */
void free_iccss(iccss *list);

/* - - - - - - - - - - - - - - - - - - -- */

#ifdef __cplusplus
	}
#endif

#define INST_H
#endif /* INST_H */