TWAIN Programming Guide

Notes for Major Operations in EPSON TWAIN Driver

Container for MSG_SET


Use MSG_SET for a capability with TW_ONEVALUE container.
Restricting allowed value in TW_ENUMERATION is not acceptable.

Scanning Region


Specify Scanning Area

When specifying scanning region, using DG_IMAGE / DAT_IMAGELAYOUT / MSG_SET. ICAP_FRAME that has similar function is not supported.

In MSG_SET of DAT_IMAGELAYOUT, the data source refers to Frame field of TW_IMAGELAYOUT structure only. DocumentNumber, PageNumber, FrameNumber are ignored. Application should set –1 to DocumentNumber, PageNumber and FrameNumber fields. Measurement unit depends on current value of ICAP_UNITS. Only cm (TWUN_CENTIMETERS) or inches (TWUN_INCHES) are allowed for ICAP_UNITS.

Make sure to specify scanning region with DAT_IMAGELAYOUT after specifying which document source (document table, Auto document feeder, Multi Photo Feeder or Transparency unit) is used. The maximum size of scanning region depends on document source. Thus the setting of the scanning region is set to default correspondent to document source after document source is changed. In order to specify document source, use CAP_FEEDERENABLE for Auto document feeder or Multi Photo Feeder, and use ICAP_LIGHTPATH for transparency unit respectively. In addition, according to document source, the returned value of ICAP_PHYSICALWIDTH and ICAP_PHYSICALHEIGHT is the maximum size of the scanning region depending on document source.

Auto Size

Setting both of ICAP_UNDEFINEDIMAGESIZE and ICAP_AUTOMATICBORDERDETECTION works as Auto Size. Please make sure to set both capabilities to TRUE.
You can also use ICAP_AUTOSIZE.
Supported Scanners are GT-S80 / GT-S50 / GT-S85 / GT-S55 / DS-30 / DS-510 / DS-560 / DS-40 and DS-520.

Pixel Type and Bit Depth


Use ICAP_PIXELTYPE to specify pixel type – Color, Grayscale or Black & White. To specify 48 (42, 36)-bit color or 16 (14, 12)-bit grayscale, use ICAP_BITDEPTH.

Definition of the value of ICAP_BITDEPTH is different between data source versions.

Ver. 3.9.0.x or before / Ver.4.x
ICAP_BITDEPTH is to be specified based on value per channel even if ICAP_PIXELTYPE is TWPT_COLOR. Depending on scanner model, the allowed value for ICAP_BITDEPTH is different. To retrieve allowed value, use MSG_GET of ICAP_BITDEPTH. Contrary to TWAIN specs, there is no combination between ICAP_PIXELTYPE and ICAP_BITDEPTH. Do not specify 1 for ICAP_BITDEPTH if ICAP_PIXELTYPE is TWPT_COLOR or TWPT_GRAY.

Ver3.9.1.x / Ver.5.x or later
ICAP_BITDEPTH indicates total bit depth of each channel. For example, set ICAP_BITDEPTH = 24 for RGB color scanning. In addition, only available value is returned for each pixel types.

Available values are different between each scanners, you can get supported values via MSG_GET of ICAP_BITDEPTH.

Resolution


For X-axis and Y-axis, use ICAP_XRESOLUTION, ICAP_XSCALING, ICAP_YRESOLUTION and ICAP_YSCALING respectively. Different values can be specified for X-axis and Y-axis. (EPSON TWAIN Pro Ver.2.1 or before does not work with different settings between X and Y axis.) Scanning resolution is a product of ICAP_X(Y)RESOLUTION and ICAP_X(Y)SCALING.

Ex) If ICAP_XRESOLUTION is 300 and ICAP_XSCALING is 0.5, scanning resolution is 300 x 0.5 = 150 dpi

Image Adjustment


When controlling scanners with built-in GUI, the scanning condition follows the settings of GUI. Negotiation of capabilities in state 4, before GUI is displayed, is ignored. On the other hand, if scanner is operated with UI suppress mode, tone adjustment can be performed with the following capabilities that are defined in the TWAIN specifications.

  • If Image type is Color or Grayscale:
    ICAP_BRIGHTNESS
    ICAP_CONTRST
    ICAP_GAMMA
    Relationship among them is described in section of ICAP_BRIGHTNESS.
  • If Image type is Black and White:
    ICAP_THRESHOLD

In Ver3.66 or later version of Ver.3.6x, default gamma curve for UI suppress scanning is changed from linear to below chart.

Input 0-18 19 20 21 22 23 24 25 26 27 28 29 30 31
Output 0 2 4 7 9 11 13 15 17 19 20 22 24 26
32 33 34 35 36 37 38 39 40 41 42 43 44 45
27 29 31 32 34 35 37 38 40 42 43 45 46 47
46 47 48 49 50 51 52 53 54 55 56 57 58 59
49 50 52 53 55 56 58 59 60 62 63 64 66 67
60 61 62 63 64 65 66 67 68 69 70 71 72 73
69 70 71 73 74 75 77 78 79 81 82 83 84 86
74 75 76 77 78 79 80 81 82 83 84 85 86 87
87 88 90 91 92 93 95 96 97 98 100 101 102 103
88 89 90 91 92 93 94 95 96 97 98 99 100 101
105 106 107 108 110 111 112 113 114 116 117 118 119 120
102 103 104 105 106 107 108 109 110 111 112 113 114 115
122 123 124 125 126 128 129 130 131 132 133 135 136 137
116 117 118 119 120 121 122 123 124 125 126 127 128 129
138 139 140 142 143 144 145 146 147 148 150 151 152 153
130 131 132 133 134 135 136 137 138 139 140 141 142 143
154 155 156 157 159 160 161 162 163 164 165 166 168 169
144 145 146 147 148 149 150 151 152 153 154 155 156 157
170 171 172 173 174 175 176 177 179 180 181 182 183 184
158 159 160 161 162 163 164 165 166 167 168 169 170 171
185 186 187 188 189 191 192 193 194 195 196 197 198 199
172 173 174 175 176 177 178 179 180 181 182 183 184 185
200 201 202 203 204 206 207 208 209 210 211 212 213 214
186 187 188 189 190 191 192 193 194 195 196 197 198 199
215 216 217 218 219 220 221 222 223 224 225 227 228 229
200 201 202 203 204 205 206 207 208 209 210 211 212 213
230 231 232 233 234 235 236 237 238 239 240 241 242 243
214 215 216 217 218 219 220 221 222 223 224 225-255
244 245 246 247 248 249 250 251 252 253 254 255

Transfer Mode


Transfer mode can be set with CAP_XFERMECH capability. EPSON TWAIN driver supports Native mode (TWSX_NATIVE) and Buffered memory mode (TWSX_MEMORY) transfer. Since Native mode cannot be used if bit depth of image is 48 (42, 36) bit for color or 16 (14, 12) bit for grayscale, use buffered memory mode instead.

About file transfer: Ver. 3.9 or later and Ver3.6series after Ver3.64 supports file transfer (Windows only). For other versions, TWSX_FILE is appeared in allowed value of CAP_XFERMECH For application compatibility. However, do not set TWSX_FILE for CAP_XFERMECH.

User Interface for Setting


Application can show Sources built-in user interface for setting. Application can check if this user interface is supported or not by CAP_ENABLEDSUIONLY.

DG_CONTROL / DAT_USERINTERFACE / MSG_ENABLEDSUIONLY is used to show this user interface. When this triplet is called, setting user interface is displayed. It doesn’t have a scan button.

In addition, setting list of current value for all items can be gotten as text data using DG_CONTROL / DAT_CUSTOMDSDATA / MSG_GET. Application can save it internally. Application can specify scan setting using text data later using DG_CONTROL / DAT_CUSTOMDSDATA / MSG_SET.

Application need to just save text data or set text data, doesn’t need to understand the definition of the text data.

Setting Ordering


TWAIN Guideline

There is a guideline document how to specify TWAIN setting (White Paper: Capability Ordering). Please refer it for detail. It can be downloaded by TWAIN working group.

Cancellation During Scanning


If Cancel button on progress indicator dialog is clicked during scanning, scanning is terminated with any scanning transfer mode. When the progress indicator is suppressed, application can terminate scanning with the following steps. This is only available for buffered memory transfer mode.

During buffered memory transfer, after application sends DG_IMAGE / DAT_IMAGEMEMXFER / MSG_GET, TWRC_SUCCESS is returned from data source in every block image data transfer. In final block image, TWRC_XFERDONE is returned instead. Before transfer is completed, issuing DG_CONTROL / DAT_PENDIGNXFERS / MSG_ENDXFER terminates transfer of remaining block. After the triplet is sent, state is moved to State 6.

Scanning Using Auto Document Feeder


Auto Document Feeder Capability

To determine if a Source has a document feeder available, use a DG_CONTROL / DAT_CAPABILITY / MSG_GET operation for CAP_FEEDERENABLED. Return value indicates ability of auto document feeder. If TWRC_SUCCESS is returned, Auto document feeder is equipped. If TWRC_FAILURE / TWRC_BADCAP is returned, Auto document feeder is not equipped.

Enabling Auto Document Feeder

To scan using Auto document feeder, confirm Auto document feeder is equipped and then set both CAP_FEEDERENABLED and CAP_AUTOFEED to TRUE. Auto document feeder scanning may not work correctly if CAP_AUTOFEED is FALSE. CAP_FEEDPAGE and CAP_CLEARPAGE do not work for Auto document feeder.

Confirmation of Document on Auto Document Feeder Tray

To confirm whether a document is on the Auto document feeder tray, use MSG_SET for CAP_FEEDERLOADED.

Multiple Pages Scanning

Application should repeat state 6 and state 7 in image transfer to scan multiple pages. After completing a one page transfer, application has to invoke DG_CONTROL / DAT_PENDINGXFER / MSG_ENDXFER. Application should check value of TW_PENDINXFERS.Count to decide whether there is remaining document. If there is still a document, the value is –1. Otherwise, it is 0.

Cancellation during Multiple Page Scanning

If scanning is required to be cancelled in case document remains on the Auto document feeder tray, application should invoke DG_CONTROL / DAT_PENDINGXFER / MSG_ENDXFER and then send DG_CONTROL / DAT_PENDINGXFER / MSG_RESET. State will be turned to state 5.

Duplex Scanning

CAP_DUPLEX indicates whether duplex scanning is available. Data source that is working for A3 size scanner with ADF returns TWDX_2PASSDUPLEX. To enable duplex scanning, set CAP_FEEDERENABLED to TRUE and then set CAP_DUPLEXEENABLED to TRUE. If CAP_DUPLEXEENABLED is FALSE, only one side of document is scanned.

Features that are Available in A3 Size ADF Only

Automatic size detection is available in A3 size ADF or following scanners.

  • GT-S80 / GT-S50 / GT-S85 / GT-S55
  • DS-30 / DS-40
  • DS-50000 /DS-60000 / DS-7000
  • DS-5500 / DS-6500 / DS-7500
  • DS-510 / DS-560 / DS-520
  • DS-760 / DS-860

Automatic size detection feature in ADF scanning works as follows in UI suppress mode. In EPSON TWAIN Pro and EPSON Scan Ver.1.x, since the feature is always available, document is scanned with detected size. On the other hand, scanning region that was specified by application is ignored. In EPSON Scan Ver. 2.x (except 3.6) doesn’t support the feature, please specify the scanning size. In EPSON Scan Ver. 3.6x and Ver.5.x, Auto size detection is available using TWAIN command, see [Auto Size] for detail. In EPSON TWAIN HS, the feature does not work in UI suppress mode but works in UI mode. So, if scanning region is specified by application, the region is used for scanning. If no region is specified, whole scanning region is obtained.

When user use “Auto Detect” with UI mode, application must obtain actual size of image being transferred before each image transfer is started using DG_IMAGE / DAT_IMAGEINFO / MSG_GET regardless of transfer mode (Native/ Memory/ File).

Pre Scanning

Following scanners support pre scanning using CAP_AUTOSCAN. If this is set, the scanner scans paper continuously even if scanner doesn’t receive scan command of next paper (i.e. start continuous scanning with the scan command of 1st paper.)

  • GT-S80 / GT-S50 / GT-S85 / GT-S55
  • DS-50000 /DS-60000 / DS-7000
  • DS-5500 / DS-6500 / DS-7500
  • DS-510 / DS-560 / DS-520
  • DS-760 / DS-860

Scanning Using Multi Photo Feeder


Multi Photo Feeder Capability

Multi Photo Feeder can be controlled with capabilities for conventional Auto document feeder control. To determine if a Source has Multi Photo Feeder, use a DG_CONTROL / DAT_CAPABILITY / MSG_GET operation for CAP_FEEDERENABLED. Return value indicates ability of Multi Photo Feeder. If TWRC_SUCCESS is returned, Auto document feeder or Multi Photo Feeder is equipped. If TWRC_FAILURE / TWRC_BADCAP is returned, neither Auto document feeder nor Multi Photo Feeder is equipped.

Enabling Multi Photo Feeder

To scan using Multi Photo Feeder, confirm Multi Photo Feeder is equipped and then set CAP_FEEDERENABLED to TRUE.

Confirmation of Photo on Multi Photo Feeder Tray

To confirm whether a photo is on the Multi Photo Feeder tray, use MSG_SET for CAP_FEEDERLOADED.

Feeding and Ejecting Photo in Multi Photo Feeder

In Multi Photo Feeder, feeding and ejecting photo can be controlled individually. First, set CAP_AUTOFEED to FALSE. And then set CAP_FEEDPAGE to TRUE to feed next photo on the tray. If a photo was already loaded, it is ejected. Setting CAP_CLEARPAGE to TRUE makes current photo to be ejected.

If CAP_AUTOFEED is TRUE, feeding and ejecting cannot be controlled individually. In this case, photo is automatically loaded before scanning and after scanning is finished, the photo is ejected and next photo is loaded. Default value of CAP_AUTOFEED is TRUE.

Cropping Image from Background in Multi Photo Feeder

Scanning area can be specified using DG_IMAGE / DAT_IMAGELAYOUT / MSG_SET before scanning for Multi Photo Feeder also. The feature to crop image automatically from background is not supported.