1 /* sane - Scanner Access Now Easy. 2 3 pieusb_scancmd.h 4 5 Copyright (C) 2012-2015 Jan Vleeshouwers, Michael Rickmann, Klaus Kaempf 6 7 This file is part of the SANE package. 8 9 This program is free software; you can redistribute it and/or 10 modify it under the terms of the GNU General Public License as 11 published by the Free Software Foundation; either version 2 of the 12 License, or (at your option) any later version. 13 14 This program is distributed in the hope that it will be useful, but 15 WITHOUT ANY WARRANTY; without even the implied warranty of 16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 17 General Public License for more details. 18 19 You should have received a copy of the GNU General Public License 20 along with this program. If not, see <https://www.gnu.org/licenses/>. 21 22 As a special exception, the authors of SANE give permission for 23 additional uses of the libraries contained in this release of SANE. 24 25 The exception is that, if you link a SANE library with other files 26 to produce an executable, this does not by itself cause the 27 resulting executable to be covered by the GNU General Public 28 License. Your use of that executable is in no way restricted on 29 account of linking the SANE library code into it. 30 31 This exception does not, however, invalidate any other reasons why 32 the executable file might be covered by the GNU General Public 33 License. 34 35 If you submit changes to SANE to the maintainers to be included in 36 a subsequent release, you agree by submitting the changes that 37 those changes may be distributed with this exception intact. 38 39 If you write modifications of your own for SANE, it is your choice 40 whether to permit this exception to apply to your modifications. 41 If you do not wish that, delete this exception notice. */ 42 43 #ifndef PIEUSB_SCANCMD_H 44 #define PIEUSB_SCANCMD_H 45 46 #include "../include/sane/sane.h" 47 48 /* ========================================================================= 49 * 50 * Data-structures used by scanner commands 51 * 52 * For SENSE descriptions, see SCSI-2 p158, table 67 (p469 ASC/Q alphabetically) 53 * For the INQUIRY command, see SCSI-2 p141 table 45, 46, 47 54 * 55 * 2-byte short ints are represented by 4-byte SANE_Int types 56 * 57 * ========================================================================= */ 58 59 struct Pieusb_Scanner_Properties { 60 SANE_Byte deviceType; /* 0x06 = scanner */ 61 SANE_Byte additionalLength; /* including this byte: 0xb4 = 180, so total structure 184 bytes */ 62 SANE_Char vendor[9]; /* actually 8 bytes, not null-terminated ...PIE ... */ 63 SANE_Char product[17]; /* actually 16 bytes, null-terminated ...SF Scanner... */ 64 SANE_Char productRevision[5]; /* actually 4 bytes, not null-terminated ...1.70... */ 65 /* 1st Vendor-specific block, 20 bytes, see pie_get_inquiry_values(), partially: */ 66 SANE_Int maxResolutionX; /* 7200 maximum scan resolution in x direction */ 67 SANE_Int maxResolutionY; /* 7200 maximum scan resolution in y direction */ 68 SANE_Int maxScanWidth; /* 10680 flatbed_max_scan_width (& calibration block size) */ 69 SANE_Int maxScanHeight; /* 6888 flatbed_max_scan_height */ 70 SANE_Byte filters; /* 0x9e = 10011110 ?-0-0-OnePassColor-B-G-R-N => additional infrared? */ 71 SANE_Byte colorDepths; /* 0x35 = 00110101 0-0-16-12-10-8-4-1 */ 72 SANE_Byte colorFormat; /* 0x07 = 00000111 0-0-0-0-0-Index-Line-Pixel */ 73 SANE_Byte imageFormat; /* 0x09 = 00001001 0-0-0-0-OKLine-BlkOne-Motorola-Intel */ 74 SANE_Byte scanCapability; 75 /* 0x4b = 01001011 PowerSave-ExtCal-0-FastPreview-DisableCal-[CalSpeeds=3] 76 * PowerSave: no 77 * ExtCal: yes => 78 * FastPreview: no 79 * DisableCal: yes => can calibration be disabled? 80 * CalSpeeds: 3 => 1 line, 13 lines, 31 lines */ 81 SANE_Byte optionalDevices; 82 /* 0x61 = 01100001 MultiPageLoad-?-?-0-0-TransModule1-TransModule-AutoDocFeeder => additional? 83 * MultiPageLoad: no 84 * ?: yes 85 * ?: yes 86 * TransModule1: no 87 * TransModule: no 88 * AutoDocFeeder: yes */ 89 SANE_Byte enhancements; /* 0x02 = no info in pie.c */ 90 SANE_Byte gammaBits; /* 0x0c = 00001100 = 12 ? used when downloading gamma table ... does not happen */ 91 SANE_Byte lastFilter; /* 0x00 = ? no info in pie.c, not used */ 92 SANE_Int previewScanResolution; /* 0x2c01 = 300 fast preview scan resolution */ 93 /* Reserved (56-95) */ 94 /* SANE_Byte div_56[40]; */ 95 /* 2nd vendor specific block (36 bytes at offset 96) */ 96 SANE_Char firmwareVersion[5]; /* actually 4 bytes, not null terminated "1.05" */ 97 SANE_Byte halftones; /* 0x08 = halftones (4 LSbits) = 00001000 ? */ 98 SANE_Byte minumumHighlight; /* 0x64 = 100 */ 99 SANE_Byte maximumShadow; /* 0x64 = 100 */ 100 SANE_Byte calibrationEquation; /* 0x01 ? see pie_perform_cal() */ 101 SANE_Int maximumExposure; /* 0xc409 = 2500 (units?) */ 102 SANE_Int minimumExposure; /* 0x6400 = 100 (units?) */ 103 SANE_Int x0; /* 0xd002 = 720 transparency top left x */ 104 SANE_Int y0; /* 0x8604 = 1158 transparency top left y */ 105 SANE_Int x1; /* 0xbc10 = 4284 transparency bottom right x */ 106 SANE_Int y1; /* 0xc015 = 5568 transparency bottom right y */ 107 SANE_Int model; /* 0x3000 => model number */ 108 /* SANE_Int div_118; 0x0000 meaning? */ 109 SANE_Char production[4]; /* null terminated */ 110 SANE_Char timestamp[20]; /* null terminated */ 111 SANE_Byte signature[40]; /* null terminated */ 112 }; 113 114 struct Pieusb_Sense { 115 /* 14 bytes according to SCSI-2 p158, table 67 (p469 ASC/Q alphabetically) */ 116 SANE_Byte errorCode; /* 0x70 or 0x71 */ 117 SANE_Byte segment; 118 SANE_Byte senseKey; /* sense key is actually this value & 0x0F - table 69 */ 119 SANE_Byte info[4]; 120 SANE_Byte addLength; /* should be 0x07 (remaining struct length including this byte) */ 121 SANE_Byte cmdInfo[4]; /* command specific information */ 122 SANE_Byte senseCode; /* abbreviated ASC - table 71 */ 123 SANE_Byte senseQualifier; /* abbreviated ASCQ - table 71 */ 124 }; 125 126 struct Pieusb_Scanner_State { 127 SANE_Byte buttonPushed; /* 0x01 if pushed */ 128 SANE_Byte warmingUp; /* 0x01 if warming up, 0x00 if not */ 129 SANE_Byte scanning; /* bit 6 set if SCAN active, bit 7 motor direction inverted (not analysed in detail) */ 130 }; 131 132 struct Pieusb_Scan_Parameters { 133 SANE_Int width; /* Number of pixels on a scan line */ 134 SANE_Int lines; /* Number of lines in the scan. Value depends on color format, see Pieusb_Mode. */ 135 SANE_Int bytes; /* Number of bytes on a scan line. Value depends on color format. */ 136 SANE_Byte filterOffset1; /* 0x08 in the logs, but may also be set to 0x16, they seem to be used in “line”-format only. */ 137 SANE_Byte filterOffset2; /* 0x08 in the logs, but may also be set to 0x16, they seem to be used in “line”-format only. */ 138 SANE_Int period; /* Seems to be unused */ 139 SANE_Int scsiTransferRate; /* Don't use, values cannot be trusted */ 140 SANE_Int availableLines; /* The number of currently available scanned lines. Value depends on color format. Returns a value >0 if PARAM is called while scanning is in progress */ 141 SANE_Byte motor; /* Motor direction in bit 0 */ 142 }; 143 144 struct Pieusb_Mode { 145 /* SANE_Byte size; of remaining data, not useful */ 146 SANE_Int resolution; /* in dpi */ 147 SANE_Byte passes; 148 /* 0x80 = One pass color; 0x90 = One pass RGBI; 149 * bit 7 : one-pass-color bit (equivalent to RGB all set?) 150 * bit 6 & 5: unused 151 * bit 4 : Infrared 152 * bit 3 : Blue 153 * bit 2 : Green 154 * bit 1 : Red 155 * bit 0: Neutral (not supported, ignored) */ 156 SANE_Byte colorDepth; 157 /* 0x04 = 8, 0x20 = 16 bit 158 * bit 7 & 6 : 0 (unused) 159 * bit 5 : 16 bit 160 * bit 4 : 12 bit 161 * bit 3 : 10 bit 162 * bit 2 : 8 bit 163 * bit 1 : 4 bit 164 * bit 0 : 1 bit */ 165 SANE_Byte colorFormat; 166 /* 0x04 = index, cf. INQUIRY 167 * bit 7-3 : 0 (unused) 168 * bit 2 : Index = scanned data are lines preceded by a two-byte index, 'RR', 'GG', 'BB', or 'II' 169 * bit 1 : Line = scanned data are (probably) lines in RGBI order (needs testing) 170 * bit 0 : Pixel = scanned data are always RGB-pixels, i.e. 3x2 bytes at depth = 16 bits, 3 bytes 171 * at depth = 8 bits, and 3 packed bytes at depth = 1. This is also the case in 172 * a single color or gray scale scan; in these cases only the first pixel contains 173 * valid data. */ 174 SANE_Byte byteOrder; /* 0x01 = Intel; only bit 0 used */ 175 SANE_Bool sharpen; /* byte 9 bit 1 */ 176 SANE_Bool skipShadingAnalysis; /* byte 9 bit 3 */ 177 SANE_Bool fastInfrared; /* byte 9 bit 7 */ 178 /* bit 7 : “fast infrared” flag 179 * bit 6,5,4 : 0 (unused) 180 * bit 3 : “skip calibration” flag (skip collecting shading information) 181 * bit 2 : 0 (unused) 182 * bit 1 : “sharpen” flag (only effective with fastInfrared off, one-pass-color and no extra BADF-entries) 183 * bit 0 : 0 (unused) */ 184 SANE_Byte halftonePattern; /* 0x00 = no halftone pattern */ 185 SANE_Byte lineThreshold; /* 0xFF = 100% */ 186 }; 187 188 struct Pieusb_Settings { 189 SANE_Int saturationLevel[3]; 190 /* The average pixel values for the three colors Red, Green and Blue, 191 * which are the result of optimizing the Timer 1 counts so that Red and 192 * Blue values are least 90% of full scale (58981) and the Green value is 193 * at least 80% (52428). These levels are only determined during warming up. */ 194 SANE_Int exposureTime[4]; 195 /* Optimized exposure times for Red, Green and Blue. The exposure times are 196 * Timer 1 counts which define when Timer 1 interrupts. These values are 197 * only determined at startup. 198 * Exposure time for Infrared. The value is optimized and set at startup 199 * with the other exposure times. Quite often, it is subsequently reset to 200 * a default value (0x0B79). */ 201 SANE_Word offset[4]; 202 /* Optimized offsets for Red, Green and Blue. See above. These values are 203 * also updated before outputting the CCD-mask. 204 * Element 4 is offset for Infrared. */ 205 SANE_Word gain[4]; 206 /* Optimized gains for Red, Green and Blue. See the remark for 207 * exposureTime above. Element 4 is gain for Infrared. */ 208 SANE_Byte light; 209 /* Current light level. The stability of the light source is tested during 210 * warming up. The check starts with a light value 7 or 6, and decrements 211 * it when the light warms up. At a light value of 4, the scanner produces 212 * stable scans (i.e. successive “white” scan values don't differ more 213 * than 0x200). */ 214 SANE_Int minimumExposureTime; 215 /* Fixed value: 0x0b79 (2937) */ 216 SANE_Byte extraEntries; 217 SANE_Byte doubleTimes; 218 /* Originally 20 unused bytes (uninitialized memory) 219 * To complete the mapping to the Pieusb_Settings_Condensed struct, 220 * the last two bytes are given an explicit meaning. */ 221 /* SANE_Int exposureTimeIR; */ 222 /* SANE_Byte offsetIR; */ 223 /* SANE_Byte gainIR; */ 224 }; 225 226 /* Not used, Pieusb_Settings contains the same fields (after a bit of juggling) */ 227 struct Pieusb_Settings_Condensed { 228 SANE_Int exposureTime[4]; /* => Pieusb_Settings.exposureTime */ 229 SANE_Byte offset[4]; /* => Pieusb_Settings.offset */ 230 SANE_Byte gain[4]; /* => Pieusb_Settings.gain */ 231 SANE_Byte light; /* => Pieusb_Settings.light */ 232 SANE_Byte extraEntries; /* => Pieusb_Settings.extraEntries */ 233 SANE_Byte doubleTimes; /* => Pieusb_Settings.doubleTimes */ 234 }; 235 236 struct Pieusb_Halftone_Pattern { 237 SANE_Int code; /* 0x91 */ 238 /*TODO */ 239 }; 240 241 struct Pieusb_Scan_Frame { 242 SANE_Int index; /* scan frame index (0-7) */ 243 SANE_Int x0; /* top left, is origin */ 244 SANE_Int y0; 245 SANE_Int x1; /* bottom right */ 246 SANE_Int y1; 247 }; 248 249 struct Pieusb_Exposure_Time_Color { 250 SANE_Int filter; /* color mask 0x02, 0x04 or 0x08 for R, G, B */ 251 SANE_Int value; /* relative exposure time 0 - 100 */ 252 }; 253 254 struct Pieusb_Exposure_Time { 255 SANE_Int code; /* 0x93 */ 256 SANE_Int size; /* number of bytes in rest of structure */ 257 struct Pieusb_Exposure_Time_Color color[3]; /* not all elements may actually be used */ 258 }; 259 260 struct Pieusb_Highlight_Shadow_Color { 261 SANE_Int filter; /* color mask 0x02, 0x04 or 0x08 for R, G, B */ 262 SANE_Int value; /* 0-100 */ 263 }; 264 265 struct Pieusb_Highlight_Shadow { 266 SANE_Int code; /* 0x94 */ 267 SANE_Int size; /* number of bytes in rest of structure */ 268 struct Pieusb_Highlight_Shadow_Color color[3]; 269 }; 270 271 struct Pieusb_Shading_Parameters_Info { 272 SANE_Byte type; /* 0x00, 0x08, 0x10, 0x20; RGBI(?) */ 273 SANE_Byte sendBits; /* 0x10 = 16 */ 274 SANE_Byte recieveBits; /* 0x10 = 16 */ 275 SANE_Byte nLines; /* 0x2D = 45 */ 276 SANE_Int pixelsPerLine; /* 0x14dc = 5340 */ 277 }; 278 279 #define SHADING_PARAMETERS_INFO_COUNT 4 280 struct Pieusb_Shading_Parameters { 281 SANE_Byte code; /* 0x95 */ 282 SANE_Int size; /* number of bytes in rest of structure (0x1c=28) */ 283 SANE_Byte calInfoCount; /* number of individual info structures (=0x04) */ 284 SANE_Byte calInfoSize; /* size of individual info structure (=0x06) */ 285 SANE_Int div_6; /* 0x0004, meaning not clear */ 286 struct Pieusb_Shading_Parameters_Info cal[SHADING_PARAMETERS_INFO_COUNT]; 287 }; 288 289 typedef enum { 290 PIEUSB_STATUS_GOOD = 0, /* 0 everything A-OK */ 291 PIEUSB_STATUS_UNSUPPORTED, /* 1 operation is not supported */ 292 PIEUSB_STATUS_CANCELLED, /* 2 operation was cancelled */ 293 PIEUSB_STATUS_DEVICE_BUSY, /* 3 device is busy; try again later */ 294 PIEUSB_STATUS_INVAL, /* 4 data is invalid (includes no dev at open) */ 295 PIEUSB_STATUS_EOF, /* 5 no more data available (end-of-file) */ 296 PIEUSB_STATUS_JAMMED, /* 6 document feeder jammed */ 297 PIEUSB_STATUS_NO_DOCS, /* 7 document feeder out of documents */ 298 PIEUSB_STATUS_COVER_OPEN, /* 8 scanner cover is open */ 299 PIEUSB_STATUS_IO_ERROR, /* 9 error during device I/O */ 300 PIEUSB_STATUS_NO_MEM, /* 10 out of memory */ 301 PIEUSB_STATUS_ACCESS_DENIED, /* 11 access to resource has been denied */ 302 PIEUSB_STATUS_WARMING_UP, /* 12 lamp not ready, please retry */ 303 PIEUSB_STATUS_HW_LOCKED, /* 13 scanner mechanism locked for transport */ 304 PIEUSB_STATUS_MUST_CALIBRATE /* 14 */ 305 } PIEUSB_Status; 306 307 /* Structures used by the USB functions */ 308 309 struct Pieusb_Command_Status { 310 PIEUSB_Status pieusb_status; 311 SANE_Byte senseKey; /* sense key: see Pieusb_Sense */ 312 SANE_Byte senseCode; /* sense code */ 313 SANE_Byte senseQualifier; /* sense code qualifier */ 314 }; 315 316 typedef struct Pieusb_Scanner_Properties Pieusb_Scanner_Properties; 317 318 typedef enum { 319 SLIDE_NEXT = 0x04, SLIDE_PREV = 0x05, SLIDE_INIT = 0x10, SLIDE_RELOAD = 0x40 320 } slide_action; 321 322 void sanei_pieusb_cmd_slide(SANE_Int device_number, slide_action action, struct Pieusb_Command_Status *status); 323 324 /* Scanner commands */ 325 326 void sanei_pieusb_cmd_test_unit_ready(SANE_Int device_number, struct Pieusb_Command_Status *status); 327 328 void sanei_pieusb_cmd_get_sense(SANE_Int device_number, struct Pieusb_Sense* sense, struct Pieusb_Command_Status *status, PIEUSB_Status *ret); 329 330 void sanei_pieusb_cmd_get_halftone_pattern(SANE_Int device_number, SANE_Int index, struct Pieusb_Halftone_Pattern* pattern, struct Pieusb_Command_Status *status); 331 void sanei_pieusb_cmd_set_halftone_pattern(SANE_Int device_number, SANE_Int index, struct Pieusb_Halftone_Pattern* pattern, struct Pieusb_Command_Status *status); 332 333 void sanei_pieusb_cmd_get_scan_frame(SANE_Int device_number, SANE_Int index, struct Pieusb_Scan_Frame* frame, struct Pieusb_Command_Status *status); 334 void sanei_pieusb_cmd_set_scan_frame(SANE_Int device_number, SANE_Int index, struct Pieusb_Scan_Frame* frame, struct Pieusb_Command_Status *status); 335 336 void sanei_pieusb_cmd_17(SANE_Int device_number, SANE_Int value, struct Pieusb_Command_Status *status); 337 338 void sanei_pieusb_cmd_get_exposure_time(SANE_Int device_number, SANE_Int colorbits, struct Pieusb_Exposure_Time* time, struct Pieusb_Command_Status *status); 339 void sanei_pieusb_cmd_set_exposure_time(SANE_Int device_number, struct Pieusb_Exposure_Time* time, struct Pieusb_Command_Status *status); 340 341 void sanei_pieusb_cmd_get_highlight_shadow(SANE_Int device_number, SANE_Int colorbits, struct Pieusb_Highlight_Shadow* hgltshdw, struct Pieusb_Command_Status *status); 342 void sanei_pieusb_cmd_set_highlight_shadow(SANE_Int device_number, struct Pieusb_Highlight_Shadow* hgltshdw, struct Pieusb_Command_Status *status); 343 344 void sanei_pieusb_cmd_get_shading_parms(SANE_Int device_number, struct Pieusb_Shading_Parameters_Info* shading, struct Pieusb_Command_Status *status); 345 void sanei_pieusb_cmd_get_scanned_lines(SANE_Int device_number, SANE_Byte* data, SANE_Int lines, SANE_Int size, struct Pieusb_Command_Status *status); 346 347 void sanei_pieusb_cmd_get_ccd_mask(SANE_Int device_number, SANE_Byte* mask, SANE_Int mask_size, struct Pieusb_Command_Status *status); 348 void sanei_pieusb_cmd_set_ccd_mask(SANE_Int device_number, SANE_Byte colorbits, SANE_Byte* mask, SANE_Int mask_size, struct Pieusb_Command_Status *status); 349 350 /* 351 void cmdPrepareHalftonePattern(SANE_Int device_number, SANE_Int index, struct Pieusb_Command_Status *status); 352 void cmdPrepareScanFrame(SANE_Int device_number, SANE_Int index, struct Pieusb_Command_Status *status); 353 void cmdPrepareRelativeExposureTime(SANE_Int device_number, SANE_Int colorbits, struct Pieusb_Command_Status *status); 354 void cmdPrepareHighlightShadow(SANE_Int device_number, SANE_Int colorbits, struct Pieusb_Command_Status *status); 355 void cmdPrepareShadingParameters(SANE_Int device_number, struct Pieusb_Command_Status *status); 356 */ 357 358 void sanei_pieusb_cmd_get_parameters(SANE_Int device_number, struct Pieusb_Scan_Parameters* parameters, struct Pieusb_Command_Status *status); 359 360 void sanei_pieusb_cmd_inquiry(SANE_Int device_number, struct Pieusb_Scanner_Properties* inq, SANE_Byte size, struct Pieusb_Command_Status *status); 361 362 void sanei_pieusb_cmd_get_mode(SANE_Int device_number, struct Pieusb_Mode* mode, struct Pieusb_Command_Status *status); 363 void sanei_pieusb_cmd_set_mode(SANE_Int device_number, struct Pieusb_Mode* mode, struct Pieusb_Command_Status *status); 364 365 void sanei_pieusb_cmd_start_scan(SANE_Int device_number, struct Pieusb_Command_Status *status); 366 void sanei_pieusb_cmd_stop_scan(SANE_Int device_number, struct Pieusb_Command_Status *status); 367 368 void sanei_pieusb_cmd_set_scan_head(SANE_Int device_number, SANE_Int mode, SANE_Int steps, struct Pieusb_Command_Status *status); 369 370 void sanei_pieusb_cmd_get_gain_offset(SANE_Int device_number, struct Pieusb_Settings* settings, struct Pieusb_Command_Status *status); 371 372 void sanei_pieusb_cmd_set_gain_offset(SANE_Int device_number, struct Pieusb_Settings* settings, struct Pieusb_Command_Status *status); 373 374 void sanei_pieusb_cmd_read_state(SANE_Int device_number, struct Pieusb_Scanner_State* state, struct Pieusb_Command_Status *status); 375 376 #endif /* PIEUSB_SCANCMD_H */ 377