From 094535c010320967639e8e86f974d878e80baa72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Frings-F=C3=BCrst?= Date: Fri, 1 May 2015 16:13:57 +0200 Subject: Imported Upstream version 1.7.0 --- spectro/inst.h | 218 +++++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 158 insertions(+), 60 deletions(-) (limited to 'spectro/inst.h') diff --git a/spectro/inst.h b/spectro/inst.h index d69a37f..a4184d4 100644 --- a/spectro/inst.h +++ b/spectro/inst.h @@ -42,6 +42,7 @@ */ #include "insttypes.h" /* libinst Includes this functionality */ +#include "disptechs.h" /* libinst Includes this functionality */ #include "icoms.h" /* libinst Includes this functionality */ #include "conv.h" @@ -70,8 +71,8 @@ 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_emission_flash = 3, /* cd.s/m^2, mW.s/(m^2.sr.nm) */ + inst_mrt_ambient_flash = 4, /* Lux.s mW.s/(m^2.nm) */ inst_mrt_reflective = 5, /* %, %/nm */ inst_mrt_transmissive = 6, /* %, %/nm */ inst_mrt_frequency = 7 /* Hz */ @@ -123,77 +124,100 @@ typedef enum { 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_system_error = 0x170000, /* System call (ie malloc) fail */ + inst_bad_parameter = 0x180000, /* Bad parameter value */ + inst_other_error = 0x190000, /* Some other error */ inst_mask = 0xff0000, /* inst_code mask value */ inst_imask = 0x00ffff /* instrument specific mask value */ } inst_code; + +/* + 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); + */ + /* Instrument capabilities & modes */ /* Note that due to the binary combinations, capabilities is not definititive */ /* as to valid modes. check_mode() is definitive. */ +/* #defines are for saving modes in a version independent way. */ +/* Note :- update inst_mode_sym[] table in inst.c if anything here is changed. */ typedef enum { inst_mode_none = 0x00000000, /* No capability or mode */ /* Mode of light measurement */ inst_mode_reflection = 0x00000001, /* General reflection mode */ +# define inst_mode_reflection_sym "REFL" inst_mode_s_reflection = 0x00000002, /* General saved reflection mode */ +# define inst_mode_s_reflection_sym "SRFL" inst_mode_transmission = 0x00000004, /* General transmission mode */ +# define inst_mode_transmission_sym "TRAN" inst_mode_emission = 0x00000008, /* General emission mode */ +# define inst_mode_emission_sym "EMIS" inst_mode_illum_mask = 0x0000000f, /* Mask of sample illumination sub mode */ /* Access mode of measurement */ inst_mode_spot = 0x00000010, /* General spot measurement mode */ +# define inst_mode_spot_sym "SPOT" inst_mode_strip = 0x00000020, /* General strip measurement mode */ +# define inst_mode_strip_sym "STRP" inst_mode_xy = 0x00000040, /* General X-Y measurement mode */ +# define inst_mode_xy_sym "CHXY" inst_mode_chart = 0x00000080, /* General chart measurement mode */ +# define inst_mode_chart_sym "CHRT" inst_mode_ambient = 0x00000100, /* General ambient measurement mode */ +# define inst_mode_ambient_sym "AMBI" inst_mode_ambient_flash = 0x00000200, /* General ambient flash measurement mode */ +# define inst_mode_ambient_flash_sym "ABFL" inst_mode_tele = 0x00000400, /* General telephoto measurement mode */ +# define inst_mode_tele_sym "TELE" // 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 */ +# define inst_mode_emis_nonadaptive_sys "EMNA" inst_mode_ref_uv = 0x00001000, /* Ultra Violet measurement mode */ +# define inst_mode_ref_uv_sym "REUV" inst_mode_emis_refresh_ovd = 0x00002000, /* Emissom Refresh mode override */ +# define inst_mode_emis_refresh_ovd_sym "EMRO" inst_mode_emis_norefresh_ovd = 0x00006000, /* Emissom Non-refresh mode override */ +# define inst_mode_emis_norefresh_ovd_sym "ENRO" inst_mode_dep_extra_mask = 0x00007800, /* Mask of measurement modifiers */ /* Extra independent modes */ inst_mode_colorimeter = 0x00004000, /* Colorimetric mode */ +# define inst_mode_colorimeter_sym "COLI" inst_mode_spectral = 0x00008000, /* Spectral mode */ +# define inst_mode_spectral_sym "SPEC" inst_mode_highres = 0x00010000, /* High Resolution Spectral mode */ +# define inst_mode_highres_sym "HIRZ" 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 */ +# define inst_mode_calibration_sym "CALB" /* Combined operating modes (from above): */ /* These mode capabilities are also use to set the mode */ @@ -248,6 +272,16 @@ typedef enum { /* Test for a specific mode in capability and mode */ #define IMODETST2(mcap, mbits, mode) (IMODETST(mcap, mode) && IMODETST(mbits, mode)) +#define MAX_INST_MODE_SYM_SZ (32 * (4 + 1)) /* Each bit sym is 4 chars */ + +/* Return a string with a symbolic encoding of the mode flags */ +void inst_mode_to_sym(char sym[MAX_INST_MODE_SYM_SZ], inst_mode mode); + +/* Return a set of mode flags that correspondf to the symbolic encoding */ +/* Return nz if a symbol wasn't recognized */ +int sym_to_inst_mode(inst_mode *mode, const char *sym); + + /* Instrument capabilities 2 */ /* (Available capabilities may be mode dependent) */ typedef enum { @@ -281,6 +315,8 @@ typedef enum { inst2_has_battery = 0x01000000, /* Instrument is battery powered */ inst2_disptype = 0x02000000, /* Has a display type selector */ + /* (ie. get_disptypesel(), set_disptype */ + inst2_ccmx = 0x04000000, /* Colorimeter Correction Matrix capability */ inst2_ccss = 0x08000000, /* Colorimeter Cal. Spectral Set capability */ @@ -300,18 +336,43 @@ typedef enum { } inst3_capability; +/* - - - - - - - - - - - - - - - - - - - */ + +/* API ideas for supporting calibration management: + + functions to: + + return number of used and free builtin slots, + password required flag. + + write builtin calibration or ccss/ccmx file + + write builtin calibration or ccss/ccmx file + + delete builtin calibration or ccss/ccmx file + + Things to be allowed for: + + optional password + configuration specific calibrations. How are they marked ? +*/ + 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_none = 0x0000, /* no flags - assume builtin calibration */ + inst_dtflags_mtx = 0x0001, /* matrix read from instrument */ + inst_dtflags_ccss = 0x0002, /* ccss file */ + inst_dtflags_ccmx = 0x0004, /* ccmx file */ + inst_dtflags_wr = 0x0010, /* Writable slot */ + inst_dtflags_ld = 0x0020, /* mtx/ccss/ccmx is loaded */ + inst_dtflags_default = 0x1000, /* Dafault calibration to use */ 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 */ +/* Structure used to return display type selection information. */ +/* Calibrations may be implicit (based on ix and driver code), or */ +/* explicit mtx/ccss/ccmx information contained in structure. */ typedef struct _inst_disptypesel { /* Public: */ @@ -322,17 +383,22 @@ typedef struct _inst_disptypesel { char desc[INST_DTYPE_DESC_LEN]; /* Textural description */ int refr; /* Refresh mode flag */ + disptech dtech; /* display techology */ + /* Private: */ int ix; /* Internal index, */ // Stuff for ccss & ccmx - char *path; /* Path to ccss or ccmx */ + char *path; /* Path to ccss or ccmx. NULL if not valid */ + int cc_cbid; /* cbid that matrix requires */ double mat[3][3]; /* ccmx matrix */ - xspect *sets; /* ccss set of sample spectra */ - int no_sets; /* ccs number of sets */ + xspect *sets; /* ccss set of sample spectra. NULL if not valid */ + int no_sets; /* ccs number of sets. 0 if not valid */ } inst_disptypesel; +/* - - - - - - - - - - - - - - - - - - - */ + /* Instrument options for get_set_opt() */ typedef enum { inst_opt_unknown = 0x0000, /* Option not specified */ @@ -361,15 +427,16 @@ typedef enum { 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 - */ + inst_opt_askcalib = 0x000A, /* Ask before proceeding with calibration (default) */ + /* [ No args] */ + inst_opt_noaskcalib = 0x000B, /* Proceed with calibration immediately if possible */ + /* [ No args] */ + + inst_opt_set_ccss_obs = 0x000C, /* 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] */ @@ -391,10 +458,11 @@ typedef enum { 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_target_state = 0x001B, /* Get the aiming target state 0 = off, 1 == on [*int] */ + inst_opt_set_target_state = 0x001C, /* 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_get_min_int_time = 0x001D, /* Get the minimum integration time [*double time] */ + inst_opt_set_min_int_time = 0x001E /* Set the minimum integration time [double time] */ } inst_opt_type; @@ -624,11 +692,22 @@ typedef enum { 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() */ \ + /* returned by get_disptypesel(). clears col_cor_mat() and */ \ + /* col_cal_spec_set(). */ \ inst_code (*set_disptype)( \ struct _inst *p, \ int index); \ \ + /* Get the disptech and other corresponding info for the current */ \ + /* selected display type. Returns disptype_unknown by default. */ \ + /* Because refrmode can be overridden, it may not match the refrmode */ \ + /* of the dtech. (Pointers may be NULL if not needed) */ \ + inst_code (*get_disptechi)( \ + struct _inst *p, \ + disptech *dtech, \ + int *refrmode, \ + int *cbid); \ + \ /* Get a status or get or set an option */ \ /* option state. */ \ /* Some options can be set before init */ \ @@ -806,14 +885,27 @@ typedef enum { 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. */ \ + /* Measure a display update, and instrument reaction time. It is */ \ + /* assumed that a white to black change will be made to the */ \ + /* displayed color during this call, and this is used to measure */ \ + /* the time it took for the update to be noticed by the instrument, */ \ + /* up to 1.0 second. */ \ + /* The instrument reaction time accounts for the time between */ \ + /* when the measure function is called and the samples actually being */ \ + /* taken. This value may be negative if there is a filter delay. */ \ + /* The method white_change() should be called with init=1 before */ \ + /* calling meas_delay, and then with init=0 during the meas_delay() */ \ + /* call to timestamp the transition. */ \ + /* Note that a default instmsec will be returned even on error. */ \ inst_code (*meas_delay)( \ struct _inst *p, \ - int *msecdelay); /* Return the number of msec */ \ + int *dispmsec, /* Return display update delay in msec */ \ + int *instmsec); /* Return instrument reaction time in msec */ \ + \ + /* Call used by other thread to timestamp the patch transition. */ \ + inst_code (*white_change)( \ + struct _inst *p, \ + int init); /* nz to init time stamp, z to mark transition */ \ \ /* Return the last calibrated refresh rate in Hz. Returns: */ \ /* (Available if cap2 & inst2_get_refresh_rate) */ \ @@ -852,7 +944,9 @@ typedef enum { /* To clear the matrix, pass NULL for the matrix */ \ inst_code (*col_cor_mat)( \ struct _inst *p, \ - double mtx[3][3]); /* XYZ matrix */ \ + disptech dtech, /* Use disptech_unknown if not known */ \ + int cbid, /* Calibration display type base ID, needed 1 if unknown */\ + double mtx[3][3]); /* XYZ matrix */ \ \ /* Use a Colorimeter Calibration Spectral Set (ccss) to set the */ \ /* instrumen calibration. This will affect emissive readings. */ \ @@ -863,19 +957,20 @@ typedef enum { /* 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 */ \ + disptech dtech, /* Use disptech_unknown if not known */ \ + 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 an 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 \ + * will abort the communication negotiation. \ * \ * For inst_triggered, the return value of the callback is ignored. \ * \ @@ -963,33 +1058,35 @@ void inst_del_disptype_list(inst_disptypesel *list, int no); /* - - - - - - - - - - - - - - - - - - -- */ -/* CCMX support */ +/* CCMX support - ccmx instrument proxy */ typedef struct { char *path; /* Path to the file */ char *desc; /* Technology + display description */ - int cbid; /* Calibration display type base ID */ + disptech dtech; /* Display Technology enumeration (optional if disp) */ + int cc_cbid; /* Calibration display type base ID required */ 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. */ +/* if itype != instUnknown, 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); +iccmx *list_iccmx(instType itype, int *no); /* Free up a iccmx list */ void free_iccmx(iccmx *list); /* - - - - - - - - - - - - - - - - - - -- */ -/* CCSS support */ +/* CCSS support - ccss instrument proxy */ typedef struct { char *path; /* Path to the file */ char *desc; /* Technology + display description */ + disptech dtech; /* Display Technology enumeration (optional if disp) */ int refr; /* Refresh mode flag */ char *sel; /* UI selector characters (may be NULL) */ xspect *sets; /* Set of sample spectra */ @@ -1011,5 +1108,6 @@ void free_iccss(iccss *list); } #endif + #define INST_H #endif /* INST_H */ -- cgit v1.2.3