47
52
/* ------------------------------------------------- */
53
/* aprox. debug level guide:
55
1,2 Applications, internal errors
56
2,3 High level instrument drivers
57
4,5 High level instrument communications
58
6,7 High level serial/USB communications
59
8,9 Low level serial/USB communications
63
/* ------------------------------------------------- */
48
64
/* Structure for holding an instrument patch reading */
50
66
#define ICOM_MAX_LOC_LEN 10
68
/* Type of measurement result */
69
typedef enum { /* XYZ units, spectral units */
70
inst_mrt_none = 0, /* Not set */
71
inst_mrt_emission = 1, /* cd/m^2, mW/m^2/nm */
72
inst_mrt_ambient = 2, /* Lux/3.1415926 ?? */
73
inst_mrt_emission_flash = 3, /* cd/m^2.s, mW/m^2/nm.s*/
74
inst_mrt_ambient_flash = 4, /* Lux/3.1415926/s ?? */
75
inst_mrt_reflective = 5, /* %, %/nm */
76
inst_mrt_transmissive = 6 /* %, %/nm */
53
80
char loc[ICOM_MAX_LOC_LEN]; /* patch location */
55
int XYZ_v; /* XYZ valid */
56
double XYZ[3]; /* XYZ values, 0.0 .. 100.0% */
58
int aXYZ_v; /* Absolute XYZ valid */
59
double aXYZ[3]; /* XYZ values in cd/m^2 or Lux/PI */
60
/* or cd/m^2 seconds for flash. */
62
int Lab_v; /* Lab valid */
63
double Lab[3]; /* Lab value */
82
inst_meas_type mtype; /* Measurement type */
84
int XYZ_v; /* XYZ valid */
85
double XYZ[3]; /* XYZ values */
65
87
xspect sp; /* Spectrum. sp.spec_n > 0 if valid */
66
88
/* Reflectance/Transmittance 0.0 .. 100.0%, norm = 100.0 */
67
/* or mW/nm/m^2, norm = 1.0 */
89
/* or mW/nm/m^2, norm = 1.0, etc. */
69
91
double duration; /* Apparent total duration in seconds (flash measurement) */
92
/* Typicall limited to sampling rate of instrument. */
71
94
}; typedef struct _ipatch ipatch;
107
128
inst_imask = 0x00ff /* instrument specific mask value */
110
/* Instrument capabilities */
111
/* (Some instrument capabilities may be mode dependent) */
113
inst_unknown = 0x00000000, /* Capabilities can't be determined */
115
inst_ref_spot = 0x00000001, /* Capable of reflection spot measurement */
116
inst_ref_strip = 0x00000002, /* Capable of reflection strip measurement */
117
inst_ref_xy = 0x00000004, /* Capable of reflection X-Y page measurement */
118
inst_ref_chart = 0x00000008, /* Capable of reflection chart measurement */
119
inst_reflection = 0x0000000F, /* Capable of general reflection measurements */
121
inst_s_ref_spot = 0x00000010, /* Capable of saved reflection spot measurement */
122
inst_s_ref_strip = 0x00000020, /* Capable of saved reflection strip measurement */
123
inst_s_ref_xy = 0x00000040, /* Capable of saved reflection X-Y page measurement */
124
inst_s_ref_chart = 0x00000080, /* Capable of saved reflection chart measurement */
125
inst_s_reflection = 0x000000F0, /* Capable of general saved reflection measurements */
127
inst_trans_spot = 0x00000100, /* Capable of transmission spot measurement */
128
inst_trans_strip = 0x00000200, /* Capable of transmission strip measurement */
129
inst_trans_xy = 0x00000400, /* Capable of transmission X-Y measurement */
130
inst_trans_chart = 0x00000800, /* Capable of transmission chart measurement */
131
inst_transmission = 0x00000F00, /* Capable of general transmission measurements */
133
inst_emis_spot = 0x00001000, /* Capable of emission spot measurement */
134
inst_emis_strip = 0x00002000, /* Capable of emission strip measurement */
135
inst_emis_disp = 0x00004000, /* Capable of display emission measurement */
136
inst_emis_proj = 0x00008000, /* Capable of projector emission measurement */
137
inst_emis_disptype = 0x00010000, /* Has a display type selector */
138
inst_emis_disptypem = 0x00020000, /* Setting display type is mandatory */
139
inst_emis_tele = 0x00040000, /* Capable of telephoto emission measurement */
140
inst_emis_ambient = 0x00080000, /* Capable of ambient measurement */
141
inst_emis_ambient_flash = 0x00100000, /* Capable of ambient flash measurement */
142
inst_emis_ambient_mono = 0x00200000, /* The ambient measurement is monochrome */
143
inst_emission = 0x003FF000, /* Capable of general emission measurements */
145
inst_colorimeter = 0x01000000, /* Colorimetric capability */
146
inst_spectral = 0x02000000, /* Spectral capability */
147
inst_highres = 0x04000000, /* High Resolution Spectral mode */
148
inst_ccmx = 0x08000000, /* Colorimeter Correction Matrix capability */
149
inst_ccss = 0x10000000 /* Colorimeter Calibration Spectral Set capability */
153
/* Instrument capabilities 2 */
155
inst2_unknown = 0x00000000, /* Capabilities can't be determined */
157
inst2_xy_holdrel = 0x00000001, /* Needs paper hold/release between each sheet */
158
inst2_xy_locate = 0x00000002, /* Needs user to locate patch locations */
159
inst2_xy_position = 0x00000004, /* Can be positioned at a given location */
161
inst2_cal_ref_white = 0x00000010, /* Uses a reflective white/dark calibration */
162
inst2_cal_ref_dark = 0x00000020, /* Uses a reflective dark calibration */
163
inst2_cal_trans_white = 0x00000040, /* Uses a transmissive white reference calibration */
164
inst2_cal_trans_dark = 0x00000080, /* Uses a transmissive dark reference calibration */
165
inst2_cal_disp_offset = 0x00000100, /* Uses a display offset/black calibration */
166
inst2_cal_disp_ratio = 0x00000200, /* Uses a display ratio calibration */
167
inst2_cal_disp_int_time = 0x00000400, /* Uses a display integration time calibration */
168
inst2_cal_proj_offset = 0x00000800, /* Uses a display offset/black calibration */
169
inst2_cal_proj_ratio = 0x00001000, /* Uses a display ratio calibration */
170
inst2_cal_proj_int_time = 0x00002000, /* Uses a display integration time calibration */
171
inst2_cal_crt_freq = 0x00004000, /* Uses a refresh display calibration */
173
inst2_prog_trig = 0x00010000, /* Progromatic trigger measure capability */
174
inst2_keyb_trig = 0x00020000, /* Keyboard trigger measure capability */
175
inst2_switch_trig = 0x00040000, /* Inst. switch trigger measure capability */
176
inst2_keyb_switch_trig = 0x00080000, /* keyboard or switch trigger measure capability */
178
inst2_bidi_scan = 0x00100000, /* Try and recognise patches scanned from either dir. */
179
inst2_cal_using_switch = 0x00200000, /* DTP22 special - use switch triggered calibration */
180
inst2_has_scan_toll = 0x00400000, /* Instrument will honour modified scan tollerance */
181
inst2_no_feedback = 0x00800000, /* Instrument doesn't give any user feedback */
183
inst2_has_leds = 0x01000000, /* Instrument has some user viewable indicator LEDs */
184
inst2_has_sensmode = 0x02000000, /* Instrument can report it's sensors mode */
186
inst2_has_battery = 0x04000000 /* Instrument is battery powered */
191
/* Instrument status commands for get_opt_details() */
193
inst_optdet_unknown = 0x0000, /* Option detail type not specified */
195
inst_optdet_disptypesel = 0x0001 /* Return array of display type selectors */
196
/* [args: int *no_selectors,inst_disptypesel **sels] */
199
/* Structure used to return display type selection information */
200
typedef struct _inst_disptypesel {
201
int ix; /* Selection index */
202
char sel[10]; /* String of selector characters */
203
char desc[100]; /* Textural description */
204
int ref; /* Refresh mode flag */
208
/* Instrument measurement modes and sub-modes */
209
/* We assume that there can only be one measurement mode at a time */
211
inst_mode_unknown = 0x0000, /* Mode not specified */
213
/* Sub modes that compose operating modes: */
131
/* Instrument capabilities & modes */
132
/* Note that due to the binary combinations, capabilities is not definititive */
133
/* as to valid modes. check_mode() is definitive. */
135
inst_mode_none = 0x00000000, /* No capability or mode */
215
137
/* Mode of light measurement */
216
inst_mode_reflection = 0x0001, /* General reflection mode */
217
inst_mode_s_reflection = 0x0002, /* General saved reflection mode */
218
inst_mode_transmission = 0x0003, /* General transmission mode */
219
inst_mode_emission = 0x0004, /* General emission mode */
220
inst_mode_illum_mask = 0x000f, /* Mask of sample illumination sub mode */
138
inst_mode_reflection = 0x00000001, /* General reflection mode */
139
inst_mode_s_reflection = 0x00000002, /* General saved reflection mode */
140
inst_mode_transmission = 0x00000004, /* General transmission mode */
141
inst_mode_emission = 0x00000008, /* General emission mode */
142
inst_mode_illum_mask = 0x0000000f, /* Mask of sample illumination sub mode */
222
144
/* Access mode of measurement */
223
inst_mode_spot = 0x0010, /* General spot measurement mode */
224
inst_mode_strip = 0x0020, /* General strip measurement mode */
225
inst_mode_xy = 0x0030, /* General X-Y measurement mode */
226
inst_mode_chart = 0x0040, /* General chart measurement mode */
227
inst_mode_ambient = 0x0050, /* General ambient measurement mode */
228
inst_mode_ambient_flash = 0x0060, /* General ambient flash measurement mode */
229
inst_mode_tele = 0x0070, /* General telephoto measurement mode */
230
inst_mode_sub_mask = 0x00f0, /* Mask of sub-mode */
232
/* Measurement modifiers */
233
inst_mode_disp = 0x0100, /* Display device (non-adaptive/refresh) mode */
234
inst_mode_mod_mask = 0x0f00, /* Mask of measurement modifiers */
145
inst_mode_spot = 0x00000010, /* General spot measurement mode */
146
inst_mode_strip = 0x00000020, /* General strip measurement mode */
147
inst_mode_xy = 0x00000040, /* General X-Y measurement mode */
148
inst_mode_chart = 0x00000080, /* General chart measurement mode */
149
inst_mode_ambient = 0x00000100, /* General ambient measurement mode */
150
inst_mode_ambient_flash = 0x00000200, /* General ambient flash measurement mode */
151
inst_mode_tele = 0x00000400, /* General telephoto measurement mode */
152
// Hmm. Should there be a tele_flash mode ????
153
inst_mode_sub_mask = 0x000007f0, /* Mask of sub-mode */
156
inst_mode_basic_mask = inst_mode_illum_mask | inst_mode_sub_mask,
161
Do the reflective measurement with UV rather than normal illuminant
162
[ Should this be reflectivity against 'A', or absolute ?? ]
163
(ie. spot, strip, xy or chart). inst_mode_ref_uv
165
Do a white & UV measurement at the start of each strip reading.
166
Return result with special call after each strip read.
167
inst_mode_ref_uv_strip_1
169
Do a dual white & UV measurement
170
[ Can do in one hit for spot, but how should two strip passes be handled ?
171
ie. two separate strip reads of phase 1 & then 2 ? ]
172
(ie. spot, strip, xy or chart). inst_mode_ref_uv_2pass
174
Get normal illuminant spectrum.
178
get_meas_illum_spectrum(mode);
181
/* Extra dependent modes */
182
inst_mode_emis_nonadaptive = 0x00000800, /* Emissom Non-adaptive mode */
183
inst_mode_ref_uv = 0x00001000, /* Ultra Violet measurement mode */
184
inst_mode_emis_refresh_ovd = 0x00002000, /* Emissom Refresh mode override */
185
inst_mode_emis_norefresh_ovd = 0x00006000, /* Emissom Non-refresh mode override */
186
inst_mode_dep_extra_mask = 0x00007800, /* Mask of measurement modifiers */
188
/* Extra independent modes */
189
inst_mode_colorimeter = 0x00004000, /* Colorimetric mode */
190
inst_mode_spectral = 0x00008000, /* Spectral mode */
191
inst_mode_highres = 0x00010000, /* High Resolution Spectral mode */
192
inst_mode_extra_mask = 0x0001c000, /* Mask of extra modes */
194
/* Configured for calibration & capable of returning it from inst_mode_calibration */
195
inst_mode_calibration = 0x80000000, /* Configured for calibration */
236
197
/* Combined operating modes (from above): */
198
/* These mode capabilities are also use to set the mode */
199
/* Test for a mode should be IMODETST(flags, mode) */
237
200
inst_mode_ref_spot = inst_mode_spot /* Reflection spot measurement mode */
238
201
| inst_mode_reflection,
239
202
inst_mode_ref_strip = inst_mode_strip /* Reflection strip measurement mode */
278
233
inst_mode_emis_ambient_flash = inst_mode_ambient_flash /* Ambient emission flash measurement */
279
234
| inst_mode_emission,
281
inst_mode_measurement_mask = inst_mode_mod_mask /* Mask of exclusive measurement modes */
236
inst_mode_emis_strip = inst_mode_strip /* Strip emission measurement mode */
237
| inst_mode_emission,
239
inst_mode_measurement_mask = inst_mode_illum_mask /* Mask of exclusive measurement modes */
282
240
| inst_mode_sub_mask
283
| inst_mode_illum_mask,
285
/* Independent extra modes */
286
inst_mode_colorimeter = 0x1000, /* Colorimetric mode */
287
inst_mode_spectral = 0x2000 /* Spectral mode */
241
| inst_mode_dep_extra_mask
291
/* Instrument options for set_opt_mode() */
244
/* Test for a specific mode */
245
#define IMODETST(mbits, mode) (((mbits) & (mode)) == (mode))
247
/* Test for a specific mode in capability and mode */
248
#define IMODETST2(mcap, mbits, mode) (IMODETST(mcap, mode) && IMODETST(mbits, mode))
250
/* Instrument capabilities 2 */
251
/* (Available capabilities may be mode dependent) */
253
inst2_none = 0x00000000, /* No capabilities */
255
inst2_xy_holdrel = 0x00000001, /* Needs paper hold/release between each sheet */
256
inst2_xy_locate = 0x00000002, /* Needs user to locate patch locations */
257
inst2_xy_position = 0x00000004, /* Can be positioned at a given location */
259
inst2_meas_disp_update = 0x00000010, /* Is able to measure display update delay */
260
inst2_refresh_rate = 0x00000020, /* Is able to retrieve the calibrated refresh rate */
262
inst2_prog_trig = 0x00000100, /* Progromatic trigger measure capability */
263
inst2_user_trig = 0x00000200, /* User trigger measure capability */
264
inst2_switch_trig = 0x00000400, /* Inst. switch trigger measure capability */
265
inst2_user_switch_trig = 0x00000800, /* User or switch trigger measure capability */
267
inst2_bidi_scan = 0x00001000, /* Try and recognise patches scanned from either dir. */
268
inst2_cal_using_switch = 0x00002000, /* DTP22 special - use switch triggered calibration */
269
inst2_has_scan_toll = 0x00004000, /* Instrument will honour modified scan tollerance */
270
inst2_no_feedback = 0x00008000, /* Instrument doesn't give any user feedback */
272
inst2_has_leds = 0x00200000, /* Instrument has some user viewable indicator LEDs */
273
inst2_has_sensmode = 0x00400000, /* Instrument can report it's sensors mode */
275
inst2_has_battery = 0x00800000, /* Instrument is battery powered */
277
inst2_disptype = 0x01000000, /* Has a display type selector */
278
inst2_ccmx = 0x02000000, /* Colorimeter Correction Matrix capability */
279
inst2_ccss = 0x04000000, /* Colorimeter Cal. Spectral Set capability */
281
inst2_ambient_mono = 0x08000000, /* The ambient measurement is monochrome */
283
inst2_emis_refr_meas = 0x10000000, /* Has an emissive refresh rate measurement func. */
287
/* Instrument capabilities 3 (room for expansion) */
288
/* (Available capabilities may be mode dependent) */
290
inst3_none = 0x00000000, /* No capabilities */
295
inst_dtflags_none = 0x0000, /* no flags */
296
inst_dtflags_default = 0x0001, /* default display type */
297
inst_dtflags_ccss = 0x0002, /* ccss */
298
inst_dtflags_ccmx = 0x0004, /* ccmx */
299
inst_dtflags_end = 0x8000 /* end marker */
303
#define INST_DTYPE_SEL_LEN 10
304
#define INST_DTYPE_DESC_LEN 100
306
/* Structure used to return display type selection information */
307
typedef struct _inst_disptypesel {
310
inst_dtflags flags; /* Attribute flags */
311
int cbid; /* Calibration base ID. NZ if valid ccmx calibration base. */
312
/* Should remain constant between releases */
313
char sel[INST_DTYPE_SEL_LEN]; /* String of selector characters */
314
char desc[INST_DTYPE_DESC_LEN]; /* Textural description */
315
int refr; /* Refresh mode flag */
318
int ix; /* Internal index, */
320
// Stuff for ccss & ccmx
321
char *path; /* Path to ccss or ccmx */
322
double mat[3][3]; /* ccmx matrix */
323
xspect *sets; /* ccss set of sample spectra */
324
int no_sets; /* ccs number of sets */
328
/* Instrument options for get_set_opt() */
293
330
inst_opt_unknown = 0x0000, /* Option not specified */
295
inst_opt_autocalib = 0x0001, /* Enable auto calibration (default) [No args] */
296
inst_opt_noautocalib = 0x0002, /* Disable auto calibration [No args] */
298
inst_opt_disp_type = 0x0003, /* Set display type by inst_disptypesel index [int] */
299
/* 0 sets to default, if not inst_emis_disptypem */
301
inst_opt_set_filter = 0x0007, /* Set a filter configuration */
302
/* [1 argument type inst_opt_filter] */
304
inst_opt_trig_prog = 0x0008, /* Trigger progromatically [No args] */
305
inst_opt_trig_keyb = 0x0009, /* Trigger from keyboard (default) [No args] */
306
inst_opt_trig_switch = 0x000A, /* Trigger using instrument switch [No args] */
307
inst_opt_trig_keyb_switch = 0x000B, /* Trigger using keyboard or switch (def) [No args] */
309
inst_opt_trig_return = 0x000C, /* Hack - emit "\n" after switch/kbd trigger [No args] */
310
inst_opt_trig_no_return = 0x000D, /* Hack - don't emit "\n" after trigger (def) [No args] */
312
inst_opt_highres = 0x000E, /* Enable high resolution spectral mode */
313
inst_opt_stdres = 0x000F, /* Revert to standard resolution spectral mode */
315
inst_opt_scan_toll = 0x0010, /* Modify the patch scan recognition tollnce [double] */
317
inst_opt_get_gen_ledmask = 0x0011, /* Get the bitmask for general indication LEDs [*int] */
318
/* (More specialized indicator masks go here) */
319
inst_opt_set_led_state = 0x0012, /* Set the current LED state. 0 = off, 1 == on [int] */
320
inst_opt_get_led_state = 0x0013, /* Get the current LED state. 0 = off, 1 == on [*int] */
322
inst_opt_get_pulse_ledmask = 0x0014, /* Get the bitmask for pulseable ind. LEDs [*int] */
323
inst_opt_set_led_pulse_state= 0x0015, /* Set the current LED state. [double period_in_secs, */
324
/* double on_time_prop, double trans_time_prop] */
325
inst_opt_get_led_pulse_state= 0x0016 /* Get the current pulse LED state. [*double period, */
329
/* Instrument status commands for get_status() */
331
inst_stat_unknown = 0x0000, /* Status type not specified */
333
332
inst_stat_saved_readings = 0x0001, /* Return status of saved reading values */
334
333
/* [1 argument type *inst_stat_savdrd] */
335
334
inst_stat_s_spot = 0x0002, /* Return number of saved spot readings */
348
347
inst_stat_battery = 0x0006, /* Return charged status of battery */
349
348
/* [1 argument type *double : range 0.0 - 1.0 ] */
351
inst_stat_sensmode = 0x0007, /* Return sensor mode */
352
/* [1 argument type *inst_stat_smode ] */
354
inst_stat_get_filter = 0x0008 /* Set a filter configuration */
350
inst_stat_get_filter = 0x0007, /* Get a filter configuration */
355
351
/* [1 argument type *inst_opt_filter ] */
353
inst_opt_initcalib = 0x0008, /* Enable initial calibration (default) [No args] */
354
inst_opt_noinitcalib = 0x0009, /* Disable initial calibration if < losecs since last */ /* opened, or losecs == 0 [int losecs] */
356
inst_opt_set_ccss_obs = 0x000A, /* Set the observer used with ccss device types */
357
/* Only takes effect after inst_opt_set_disp_type */
358
/* or col_cal_spec_set() */
359
/* [args: icxObserverType obType,*/
360
/* xspect custObserver[3] */
362
inst_opt_get_dtinfo = 0x000C, /* Get current display type information */
363
/* [args: int *refrmode,*/
366
inst_opt_set_filter = 0x000D, /* Set a filter configuration */
367
/* [1 argument type inst_opt_filter] */
369
inst_opt_trig_prog = 0x000E, /* Trigger progromatically [No args] */
370
inst_opt_trig_user = 0x000F, /* Trigger from user via uicallback [No args] */
371
inst_opt_trig_switch = 0x0010, /* Trigger using instrument switch [No args] */
372
inst_opt_trig_user_switch = 0x0011, /* Trigger from user via uicallback or switch (def) [No args] */
374
inst_opt_highres = 0x0012, /* Enable high resolution spectral mode */
375
inst_opt_stdres = 0x0013, /* Revert to standard resolution spectral mode */
377
inst_opt_scan_toll = 0x0014, /* Modify the patch scan recognition tollnce [double] */
379
inst_opt_get_gen_ledmask = 0x0015, /* Get the bitmask for general indication LEDs [*int] */
380
/* (More specialized indicator masks go here) */
381
inst_opt_set_led_state = 0x0016, /* Set the current LED state. 0 = off, 1 == on [int] */
382
inst_opt_get_led_state = 0x0017, /* Get the current LED state. 0 = off, 1 == on [*int] */
383
inst_opt_get_pulse_ledmask = 0x0018, /* Get the bitmask for pulseable ind. LEDs [*int] */
384
inst_opt_set_led_pulse_state= 0x0019, /* Set the current LED state. [double period_in_secs, */
385
/* double on_time_prop, double trans_time_prop] */
386
inst_opt_get_led_pulse_state= 0x001A /* Get the current pulse LED state. [*double period, */
359
390
/* Optional filter fitted to instrument (for inst_opt_set_filter) */
375
406
inst_stat_savdrd_chart = 0x08 /* There are saved chart readings available */
376
407
} inst_stat_savdrd;
378
/* Sensor mode/position (status) */
379
/* Note that this is a mask, as the same position may be suitable */
380
/* for several different types of measurement. */
382
inst_stat_smode_unknown = 0x00, /* Unknown mode */
383
inst_stat_smode_calib = 0x01, /* Calibration tile */
384
inst_stat_smode_ref = 0x02, /* Reflective */
385
inst_stat_smode_disp = 0x04, /* Display */
386
inst_stat_smode_proj = 0x08, /* Projector */
387
inst_stat_smode_amb = 0x10 /* Ambient */
390
/* Type of user interaction */
392
inst_verb = 0x00, /* verbose message */
393
inst_question = 0x01 /* A question requiring answers */
396
/* Type of calibration needed/requested - corresponds to capabilities */
409
/* Type of calibration needed/available/requested - corresponds to capabilities */
410
/* [ inst_calt_trans_vwhite is "variable" white transmission calibration, needed */
411
/* where transmission mode is being emulated. ] */
398
413
/* Response to needs_calibration() */
399
inst_calt_unknown = 0x00, /* Unknown whether calibration is needed */
400
inst_calt_none = 0x01, /* No callibration is needed */
402
/* Type to prompt all needed calibrations */
403
inst_calt_all = 0x10, /* All applicable calibrations */
405
/* Specific type of calibration - corresponds to capabilities */
406
inst_calt_ref_white = 0x20, /* Reflective white/emissive dark calibration */
407
inst_calt_ref_dark = 0x30, /* Reflective dark calibration (in dark) */
408
inst_calt_disp_offset = 0x40, /* Display offset/black calibration (dark surface) */
409
inst_calt_disp_ratio = 0x50, /* Display ratio calibration */
410
inst_calt_proj_offset = 0x60, /* Display offset/black calibration (dark surface) */
411
inst_calt_proj_ratio = 0x70, /* Display ratio calibration */
412
inst_calt_crt_freq = 0x80, /* Display CRT scan frequency calibration */
413
inst_calt_disp_int_time = 0x90, /* Display integration time */
414
inst_calt_proj_int_time = 0xA0, /* Display integration time */
415
inst_calt_em_dark = 0xB0, /* Emissive dark calibration (in dark) */
416
inst_calt_trans_white = 0xC0, /* Transmissive white reference calibration */
417
inst_calt_trans_dark = 0xD0, /* Transmissive dark reference calibration */
419
inst_calt_needs_cal_mask = 0xF0 /* One of the calibrations in needed */
414
inst_calt_none = 0x00000000, /* No calibration or unknown */
416
/* Psudo-calibration types */
417
inst_calt_all = 0x00000001, /* Do required non-deferable cals for mode, but also */
418
/* do all possible calibrations for all other modes */
419
/* using the calibration conditions. This may be slow */
420
/* Hmm. We don't have an "calt_all_needed" - do all needed cals of all possible modes. */
421
/* This might be more useful than inst_calt_all ? */
422
inst_calt_needed = 0x00000002, /* Do all required non-deferable cals for c.m. */
423
inst_calt_available = 0x00000003, /* Do all available non-deferable cals for c.m. */
425
/* Specific type of calibration - corresponds to capabilities */
426
inst_calt_wavelength = 0x00000010, /* Wavelength calibration using refl. cal. surface */
427
inst_calt_ref_white = 0x00000020, /* Reflective white/emissive dark calibration */
428
inst_calt_ref_dark = 0x00000040, /* Reflective dark calibration (in dark) */
429
inst_calt_emis_offset = 0x00000080, /* Emissive offset/black calibration (dark surface) */
430
inst_calt_emis_ratio = 0x00000100, /* Emissive ratio calibration */
431
inst_calt_em_dark = 0x00000200, /* Emissive dark calibration (in dark) */
432
inst_calt_trans_white = 0x00000400, /* Transmissive white reference calibration */
433
inst_calt_trans_vwhite = 0x00000800, /* Transmissive variable white reference calibration */
434
inst_calt_trans_dark = 0x00001000, /* Transmissive dark reference calibration */
436
inst_calt_n_dfrble_mask = 0x0000fff0, /* Mask of non-deferrable calibrations */
438
/* Calibrations that might be deferred until measurement */
439
inst_calt_emis_int_time = 0x00100000, /* Emissive measurement range (integration time) */
440
inst_calt_ref_freq = 0x00200000, /* Display refresh frequency calibration */
442
inst_calt_dfrble_mask = 0x00f00000, /* Mask of deferrable calibrations */
444
inst_calt_all_mask = 0x00f0fff0, /* Mask of all specific calibrations */
446
inst_calt_ap_flag = 0x80000000 /* Implementation flag indicating do all possible */
423
450
/* Calibration conditions. */
424
451
/* This is how the instrument communicates to the calling program */
425
/* about how to facilitate a calibration */
452
/* about how to facilitate a calibration, or what it's current measurement */
453
/* configuration provides. */
454
/* [There is no provission for explictly indicating calibrations that can be */
455
/* performed automatically and transparently by the instrument - for instance */
456
/* in the case of the spectroscan, since the required condition can be obtained */
457
/* without the users interaction. ] */
427
inst_calc_none = 0x00000000, /* No particular calibration setup, or unknown */
459
inst_calc_none = 0x00000000, /* Not suitable for calibration */
460
inst_calc_unknown = 0xffffffff, /* Unknown calibration setup */
462
/* uop means that user has to trigger the within instrument */
463
/* calibration using its "front panel" or other direct keys */
429
464
inst_calc_uop_ref_white = 0x00000001, /* user operated reflective white calibration */
430
465
inst_calc_uop_trans_white = 0x00000002, /* user operated tranmissive white calibration */
431
466
inst_calc_uop_trans_dark = 0x00000003, /* user operated tranmissive dark calibration */
432
467
inst_calc_uop_mask = 0x0000000F, /* user operated calibration mask */
469
/* Man means that the user has to manualy configure the instrument */
470
/* to be on the correct reference for the software triggered cal. */
434
471
inst_calc_man_ref_white = 0x00000010, /* place instrument on reflective white reference */
435
472
inst_calc_man_ref_whitek = 0x00000020, /* click instrument on reflective white reference */
436
473
inst_calc_man_ref_dark = 0x00000030, /* place instrument in dark, not close to anything */
437
474
inst_calc_man_em_dark = 0x00000040, /* place cap on instrument, put on dark surface or white ref. */
438
inst_calc_man_cal_smode = 0x00000050, /* Put instrument sensor in calibration position */
475
inst_calc_man_am_dark = 0x00000050, /* Place cap over ambient sensor (wl calib capable) */
476
inst_calc_man_cal_smode = 0x00000060, /* Put instrument sensor in calibration position */
440
inst_calc_man_trans_white = 0x00000060, /* place instrument on transmissive white reference */
441
inst_calc_man_trans_dark = 0x00000070, /* place instrument on transmissive dark reference */
478
inst_calc_man_trans_white = 0x00000070, /* place instrument on transmissive white reference */
479
inst_calc_man_trans_dark = 0x00000080, /* place instrument on transmissive dark reference */
442
480
inst_calc_man_man_mask = 0x000000F0, /* user configured calibration mask */
444
inst_calc_disp_white = 0x00000100, /* Provide a white display test patch */
445
inst_calc_disp_grey = 0x00000200, /* Provide a grey display test patch */
446
inst_calc_disp_grey_darker = 0x00000300, /* Provide a darker grey display test patch */
447
inst_calc_disp_grey_ligher = 0x00000400, /* Provide a darker grey display test patch */
448
inst_calc_disp_mask = 0x00000F00, /* Display provided reference patch */
450
inst_calc_proj_white = 0x00001000, /* Provide a white projector test patch */
451
inst_calc_proj_grey = 0x00002000, /* Provide a grey projector test patch */
452
inst_calc_proj_grey_darker = 0x00003000, /* Provide a darker grey projector test patch */
453
inst_calc_proj_grey_ligher = 0x00004000, /* Provide a darker grey projector test patch */
454
inst_calc_proj_mask = 0x0000F000, /* Projector provided reference patch */
482
inst_calc_emis_white = 0x00000100, /* Provide a white test patch */
483
inst_calc_emis_grey = 0x00000200, /* Provide a grey test patch */
484
inst_calc_emis_grey_darker = 0x00000300, /* Provide a darker grey test patch */
485
inst_calc_emis_grey_ligher = 0x00000400, /* Provide a darker grey test patch */
486
inst_calc_emis_mask = 0x00000F00, /* Emmissive/display provided reference patch */
456
488
inst_calc_change_filter = 0x00010000, /* Filter needs changing on device - see id[] */
457
489
inst_calc_message = 0x00020000 /* Issue a message. - see id[] */
494
instNoClamp = 0, /* Don't clamp XYZ/Lab to +ve */
495
instClamp = 1, /* Clamp XYZ/Lab to +ve */
498
/* User interaction callback function purpose */
500
inst_negcoms, /* Negotiating communications */
501
inst_triggered, /* Measurement has been triggered by switch or user (not progromatic) */
502
inst_armed, /* Armed and waiting for a measurement trigger */
503
inst_measuring /* Busy measuring */
506
/* Asynchronous event callback type */
508
inst_event_switch, /* Instrument measure/calibrate switch pressed */
509
inst_event_mconf /* Change in measurement configuration (ie. sensor position) */
512
/* Instrument configuration/sensor position*/
518
inst_conf_calibration,
522
/* Off-line pending readings available (status) */
460
523
#define CALIDLEN 200 /* Maxumum length of calibration tile ID string */
462
525
/* Color instrument interface base object */
496
561
instType (*get_itype)( \
497
562
struct _inst *p); \
499
/* Return the instrument capabilities. */ \
564
/* Return the instrument serial number. */ \
565
/* (This will be an empty string if there is no serial no) */ \
566
char *(*get_serial_no)( \
569
/* Return the avilable instrument modes and capabilities. */ \
500
570
/* Can be called before init, but may be different to */ \
501
571
/* what's returned after initilisation. */ \
502
572
/* Note that these may change with the mode. */ \
503
inst_capability (*capabilities)(struct _inst *p); \
504
inst2_capability (*capabilities2)(struct _inst *p); \
506
/* Get mode and option details */ \
507
inst_code (*get_opt_details)( \
573
/* Arguments may be NULL */ \
574
void (*capabilities)(struct _inst *p, \
576
inst2_capability *cap2, \
577
inst3_capability *cap3); \
579
/* Return current or given configuration available measurement modes. */ \
580
/* Most instruments have only one detectable configuration. */ \
581
/* If conf_ix == NULL or *conf_ix is an invalid configuration index, */ \
582
/* then the current configuration modes are returned. */ \
583
/* Otherwise the given configuration index is returned. */ \
584
/* The i1d3 has 2, the Munki has 4, one being calibration. */ \
585
/* *cconds is valid if *mmodes = inst_mode_calibration */ \
586
inst_code (*meas_config)(struct _inst *p, \
587
inst_mode *mmodes, /* Return all the valid measurement modes */ \
588
/* for the current configuration */ \
589
inst_cal_cond *cconds, /* Return the valid calibration conditions */ \
590
int *conf_ix); /* Request mode for given configuration, and */ \
591
/* return the index of the configuration returned */ \
593
/* Check that the particular device measurement mode is valid, */ \
594
/* since it's not possible to be 100% sure from capabilities */ \
595
inst_code (*check_mode)( \
508
596
struct _inst *p, \
509
inst_optdet_type m, /* Requested option detail type */ \
510
...); /* Parameters */ \
512
/* Return the instrument serial number. */ \
513
/* (This will be an empty string if there is no serial no) */ \
514
char *(*get_serial_no)( \
597
inst_mode m); /* Requested mode */ \
517
599
/* Set the device measurement mode */ \
518
600
/* Note that this may change the capabilities. */ \
626
719
/* Obeys the trigger mode set, and may return user trigger code */ \
627
720
/* Values are in XYZ 0..100 for reflective transmissive, */ \
628
721
/* aXYZ in cd/m^2 for emissive, amd Lux/3.1415926 for ambient. */ \
629
/* Spectral will be analogous to the XYZ/aXYZ. */ \
722
/* Spectral will be analogous to the XYZ. */ \
723
/* By default values may be -ve due to noise (depending on instrument) */ \
630
724
/* Return the inst error code */ \
631
725
inst_code (*read_sample)( \
632
726
struct _inst *p, \
633
char *name, /* Patch identifier (up to 7 chars) */ \
634
ipatch *val); /* Pointer to value to be returned */ \
636
/* Determine if a calibration is needed. Returns inst_calt_none if not, */ \
637
/* inst_calt_unknown if it is unknown, or inst_calt_XXX if needs calibration, */ \
638
/* and the first type of calibration needed. */ \
727
char *name, /* Patch identifier (up to 7 chars) */ \
728
ipatch *val, /* Pointer to value to be returned */ \
729
instClamping clamp); /* NZ to clamp XYZ to be +ve */ \
731
/* Measure the emissive refresh rate in Hz. */ \
732
/* (Available if cap2 & inst2_emis_refr_meas) */ \
734
/* inst_unsupported - if this instrument doesn't suport this measuremet */ \
735
/* or not in an emissive measurement mode */ \
736
/* inst_misread - if no refresh rate could be determined */ \
737
/* inst_ok - on returning a valid reading */ \
738
inst_code (*read_refrate)( \
740
double *ref_rate); /* Return the Hz */ \
742
/* Determine if a calibration is needed. Returns inst_calt_none if not */ \
743
/* or unknown, or a mask of the needed calibrations. */ \
744
/* This call checks if calibrations are invalid or have timed out. */ \
745
/* With the exception of instruments with automated calibration */ \
746
/* (ie. SpectroScan), an instrument will typically */ \
747
/* not check for calibration timout any other way. */ \
748
/* [What's returned is the same as get_n_a_cals() [ needed_calibrations.] */\
639
749
inst_cal_type (*needs_calibration)( \
640
750
struct _inst *p); \
752
/* Return combined mask of needed and available inst_cal_type's */ \
753
/* for the current mode. */ \
754
inst_code (*get_n_a_cals)( \
756
inst_cal_type *needed_calibrations, \
757
inst_cal_type *available_calibrations); \
642
759
/* Request an instrument calibration. */ \
643
760
/* This is use if the user decides they want to do a calibration */ \
644
761
/* in anticipation of a calibration (needs_calibration()) to avoid */ \
645
762
/* requiring one during measurement, or in response to measuring */ \
646
/* returning inst_needs_cal, before retrying the measurement. */ \
763
/* returning inst_needs_cal before retrying the measurement, */ \
764
/* or to do one or more re-calibrations. */ \
648
/* An initial inst_cal_cond of inst_calc_none may be used to do the */ \
649
/* default or necessary calibration, or a specific calibration supported */ \
650
/* by the instrument may be chosen. */ \
766
/* *calt should contain the mask of calibrations to be performed, */ \
767
/* with *calc set to the current calibration condition. */ \
768
/* Alternately, one of the psudo-calibration types inst_calt_all, */ \
769
/* inst_calt_needed or inst_calt_available can be used, */ \
770
/* and/or the *calc of inst_calc_none to get calibrate() */ \
771
/* to determine the required calibration types and conditions. */ \
772
/* (The corresponding calibration types will be used & returned. */ \
652
774
/* If no error is returned to the first call to calibrate() with */ \
653
/* inst_calc_none, then the instrument was capable of calibrating */ \
654
/* without user or application intervention. If on the other hand */ \
655
/* calibrate() returns inst_cal_setup, then the appropriate action */ \
656
/* indicated by the value returned in *calc should be taken by the */ \
657
/* user or application, before retrying calibration() with the */ \
658
/* current setup indicated by *calc. If several different calibrations */ \
659
/* are being performed, then several retries may be needed with */ \
660
/* different setups, untill calibrate() returns inst_ok. */ \
775
/* then the instrument was capable of calibrating without user or */ \
776
/* application intervention. If on the other hand calibrate() returns */ \
777
/* inst_cal_setup, then the appropriate action indicated by the value */ \
778
/* returned in *calc should be taken by the user or application, */ \
779
/* before retrying calibration() with the current setup indicated */ \
780
/* by *calc. If more than one calibration type is requested, then */ \
781
/* several retries may be needed with different calibration conditions. */ \
782
/* Each call to calibrate() will update *calt to reflect the remaining */ \
783
/* calibration to be performed. calibrate() returns inst_ok when no */ \
784
/* more calibrations remain. */ \
662
786
/* DOESN'T use the trigger mode */ \
663
/* Return inst_unsupported if calibration type is not appropriate. */ \
787
/* Return inst_unsupported if *calt is not appropriate, */ \
788
/* inst_cal_setup if *calc is not appropriate. */ \
664
789
inst_code (*calibrate)( \
665
790
struct _inst *p, \
666
inst_cal_type calt, /* Calibration type. inst_calt_all for all neeeded */ \
791
inst_cal_type *calt, /* Calibration type to do/remaining */ \
667
792
inst_cal_cond *calc, /* Current condition/desired condition */ \
668
char id[CALIDLEN]); /* Condition identifier (ie. white reference ID, */ \
793
char id[CALIDLEN]); /* Condition identifier (ie. white */ \
794
/* reference ID, filter ID) */ \
796
/* Measure a display update delay. It is assumed that a */ \
797
/* White to black change has been made to the displayed color, */ \
798
/* and this will measure the time it took for the update to */ \
799
/* be noticed by the instrument, up to 1.0 seconds. */ \
800
/* inst_misread will be returned on failure to find a transition to black. */ \
801
inst_code (*meas_delay)( \
803
int *msecdelay); /* Return the number of msec */ \
805
/* Return the last calibrated refresh rate in Hz. Returns: */ \
806
/* inst_unsupported - if this instrument doesn't suport a refresh mode */ \
807
/* or is unable to retrieve the refresh rate */ \
808
/* inst_needs_cal - if the refresh rate value is not valid */ \
809
/* inst_misread - if no refresh rate could be determined */ \
810
/* inst_ok - on returning a valid reading */ \
811
inst_code (*get_refr_rate)( \
813
double *ref_rate); /* Return the Hz */ \
815
/* Set the calibrated refresh rate in Hz. */ \
816
/* Set refresh rate to 0.0 to mark it as invalid */ \
817
/* Rates outside the range 5.0 to 150.0 Hz will return an error */ \
818
/* Note that not all instruments that can return a refresh rate, */ \
819
/* will permit one to be set (ie., DTP92) */ \
820
inst_code (*set_refr_rate)( \
822
double ref_rate); /* Rate in Hz */ \
671
824
/* Insert a compensation filter in the instrument readings */ \
672
825
/* This is typically needed if an adapter is being used, that alters */ \
686
841
/* Use a Colorimeter Calibration Spectral Set (ccss) to set the */ \
687
842
/* instrumen calibration. This will affect emissive readings. */ \
688
843
/* An alternate observer may also be set, and this will affect both */ \
689
/* emmissive and ambient readings. */ \
844
/* emissive and ambient readings. */ \
690
845
/* This is only valid for colorimetric instruments. */ \
691
846
/* To set calibration back to default, pass NULL for sets, and */ \
692
847
/* icxOT_default for the observer. */ \
693
848
inst_code (*col_cal_spec_set)( \
694
849
struct _inst *p, \
695
icxObserverType obType, /* Observer */ \
696
xspect custObserver[3], /* Optional custom observer */ \
697
850
xspect *sets, /* Set of sample spectra */ \
698
851
int no_sets); /* Number on set */ \
700
/* Send a message to the user. */ \
701
inst_code (*message_user)(struct _inst *p, char *fmt, ...); \
853
/* Supply a user interaction callback function. \
854
* This is called for one of three different purposes: \
855
* To signal that the instrument measurement has been triggered. \
856
* To poll for a abort while waiting to trigger. \
857
* To poll for a user abort during measurement. \
859
* The callback function will have the purpose paramater appropriately. \
861
* For inst_negcoms, the return value of inst_user_abort \
862
* will abort the communication negotiation \
864
* For inst_triggered, the return value of the callback is ignored. \
866
* For inst_armed return value should be one of: \
867
* inst_ok to do nothing, inst_user_abort to abort the measurement, \
868
* or inst_user_trig to trigger the measurement. \
870
* For inst_measuring the return value should be one of: \
871
* inst_ok to do nothing, inst_user_abort to abort the measurement. \
873
* NULL can be set to disable the callback. \
875
void (*set_uicallback)(struct _inst *p, \
876
inst_code (*uicallback)(void *cntx, inst_ui_purp purp), \
703
/* Poll for a user abort, terminate, trigger or command. */ \
704
/* Wait for a key rather than polling, if wait != 0 */ \
706
/* inst_ok if no key has been hit, */ \
707
/* inst_user_abort if User abort has been hit, */ \
708
/* inst_user_term if User terminate has been hit. */ \
709
/* inst_user_trig if User trigger has been hit */ \
710
/* inst_user_cmnd if User command has been hit */ \
711
inst_code (*poll_user)(struct _inst *p, int wait); \
879
/* Supply an aynchronous event callback function. \
880
* This is called from a thread with the following possible events: \
882
* inst_event_switch: Instrument measure/calibrate switch pressed \
883
* inst_event_mconf: The measurement configuration has changed (ie. sensor position) \
885
* NULL can be set to disable the callback. \
887
void (*set_event_callback)(struct _inst *p, \
888
void (*eventcallback)(void *cntx, inst_event_type event), \
713
891
/* Generic inst error codes interpretation */ \
714
892
char * (*inst_interp_error)(struct _inst *p, inst_code ec); \
730
912
/* Virtual constructor. */
731
913
/* Return NULL for unknown instrument, */
732
914
/* or serial instrument if nocoms == 0. */
915
/* (Doesn't copy icompaths log!) */
916
/* If uicallback is provided, it will be set in the resulting inst */
733
917
extern inst *new_inst(
734
int comport, /* icom communication port number */
918
icompath *path, /* Device path this instrument */
735
919
int nocoms, /* Don't open if communications are needed to establish inst type */
736
int debug, /* Debug level, 0 = off */
737
int verb /* Verbose level, 0 = off */
740
/* ======================================================================= */
742
/* Opaque type as far as inst.h is concerned. */
743
typedef struct _disp_win_info disp_win_info;
745
/* A default calibration user interaction handler using the console. */
746
/* This handles both normal and display based calibration interaction */
747
/* with the instrument, if a disp_setup function and pointer to disp_win_info */
749
inst_code inst_handle_calibrate(
751
inst_cal_type calt, /* type of calibration to do. inst_calt_all for all */
752
inst_cal_cond calc, /* Current condition. inst_calc_none for not setup */
753
inst_code (*disp_setup) (inst *p, inst_cal_cond calc, disp_win_info *dwi),
754
/* Callback for handling a display calibration - May be NULL */
755
disp_win_info *dwi /* Information to be able to open a display test patch - May be NULL */
758
/* ============================================================================= */
760
/* A helper function to display -y flag usage for each instrument type available */
761
/* Return accumulated capabilities of all the instruments */
762
inst_capability inst_show_disptype_options(FILE *fp, char *oline, icoms *icom);
764
/* A helper function to turn a -y flag into a selection index */
765
/* Return 0 on error */
766
int inst_get_disptype_index(inst *it, int c);
920
a1log *log, /* Log to use */
921
inst_code (*uicallback)(void *cntx, inst_ui_purp purp), /* optional uicallback */
922
void *cntx /* Context for callback */
925
/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
926
/* Implementation functions used by drivers */
928
/* Get a status or set or get an option (default implementation) */
929
inst_code inst_get_set_opt_def(
931
inst_opt_type m, /* Option type */
932
va_list args); /* Option parameters */
934
/* - - - - - - - - - - - - - - - - - - -- */
936
/* Create the display type list */
937
inst_code inst_creat_disptype_list(inst *p,
938
int *pndtlist, /* Number in returned list */
939
inst_disptypesel **pdtlist, /* Returned list */
940
inst_disptypesel *sdtlist, /* Static list */
941
int doccss, /* Add installed ccss files */
942
int doccmx /* Add matching installed ccmx files */
945
/* Free a display type list */
946
void inst_del_disptype_list(inst_disptypesel *list, int no);
949
/* - - - - - - - - - - - - - - - - - - -- */
953
char *path; /* Path to the file */
954
char *desc; /* Technology + display description */
955
int cbid; /* Calibration display type base ID */
956
int refr; /* Refresh mode flag */
957
char *sel; /* UI selector characters (may be NULL) */
958
double mat[3][3]; /* The matrix values */
961
/* return a list of installed ccmx files. */
962
/* if inst != NULL, return those that match the given instrument. */
963
/* The list is sorted by description and terminated by a NULL entry. */
964
/* If no is != NULL, return the number in the list */
965
/* Return NULL and -1 if there is a malloc error */
966
iccmx *list_iccmx(char *inst, int *no);
968
/* Free up a iccmx list */
969
void free_iccmx(iccmx *list);
971
/* - - - - - - - - - - - - - - - - - - -- */
975
char *path; /* Path to the file */
976
char *desc; /* Technology + display description */
977
int refr; /* Refresh mode flag */
978
char *sel; /* UI selector characters (may be NULL) */
979
xspect *sets; /* Set of sample spectra */
980
int no_sets; /* Number on set */
983
/* return a list of installed ccss files. */
984
/* The list is sorted by description and terminated by a NULL entry. */
985
/* If no is != NULL, return the number in the list */
986
/* Return NULL and -1 if there is a malloc error */
987
iccss *list_iccss(int *no);
989
/* Free up a iccss list */
990
void free_iccss(iccss *list);
992
/* - - - - - - - - - - - - - - - - - - -- */
768
994
#ifdef __cplusplus
added
removed
spectro/inst.h
