White Paper:

TWAIN Mandatory Features

The TWAIN Working Group

March 29, 1999

Contributors:

Jon Harju, JFL Peripheral Solutions

Mark McLaughlin, Eastman Kodak Corporation

Rob Pope, Ricoh Corporation


The TWAIN Working Group, 13090 Hwy 9, Suite 3, Boulder Creek, CA 95006

www.twain.org

2

White Paper:

TWAIN Mandatory Features

The TWAIN Working Group

March 29, 1999

Mandatory and Optional Features

This paper is a guide for Data Source developers, trying to sort through the myriad of

TWAIN Mandatory and Optional features, to determine which ones should be

implemented.

The key to this document is a clear definition of Mandatory and Optional Features. If a

feature is Mandatory, then it has been deemed absolutely necessary for proper operation

of any imaging device. Mandatory features are an absolute must on the implementation

list. Optional features are those that have been deemed useful, but not necessarily

relevant to all imaging devices. That is not to say that an optional capability is not

necessary for a particular imaging device to function properly. Because these optional

features were defined to serve one particular niche or another, it is impossible to set a

standard where they are all strictly mandatory. It is possible, however, to say that if the

device serves a particular niche then there are certain optional capabilities that become

‘Mandatory’ in order to meet the requirements of that niche.

In this document, several niches will be identified and all the relevant features indicated.

The following sections will be dealt with in order: Basic Single Image Devices, Basic

Document Feeder Type Devices, Production Quality High Speed/Volume Type

Scanners, Permanent Storage/Retrieval Devices, and Portable Capture Devices.

The following recommendations are based on the statement from Page 5.126 of the

published TWAIN 1.8 Specification:

“All Sources must implement the advertised features supported by their devices. They

must make these features available to applications via the TWAIN protocol.”

Basic Single Image Devices

To achieve the most basic image transfer and meet the minimum TWAIN 1.6

Compliance requirements (note: 1.6 was the last version of the TWAIN specification to

dictate any new Mandatory Operations or Capabilities), a TWAIN Data Source is

required to be capable of transferring to at least one single image. The following is

basically an exact copy of what is find in the Data Source requirements for a TWAIN

Data Source found in Chapter 5 Page 126 of the published 1.8 TWAIN Specification.


The TWAIN Working Group, 13090 Hwy 9, Suite 3, Boulder Creek, CA 95006

www.twain.org

3

There has been an attempt to improve the layout by putting these features in the logical

order of execution. An example of the most basic scanning device would be a flatbed

scanner.

OPERATIONS

DG_CONTROL / DAT_STATUS / MSG_GET

DG_CONTROL / DAT_XFERGROUP / MSG_GET

DG_CONTROL / DAT_IDENTITY / MSG_GET

DG_CONTROL / DAT_IDENTITY / MSG_OPENDS

DG_CONTROL / DAT_IDENTITY / MSG_CLOSEDS

DG_CONTROL / DAT_CAPABILITY / MSG_GET

DG_CONTROL / DAT_CAPABILITY / MSG_GETCURRENT

DG_CONTROL / DAT_CAPABILITY / MSG_GETDEFAULT

DG_CONTROL / DAT_CAPABILITY / MSG_RESET

DG_CONTROL / DAT_CAPABILITY / MSG_SET

DG_CONTROL / DAT_CAPABILITY / MSG_QUERYSUPPORT

DG_IMAGE / DAT_IMAGELAYOUT / MSG_GET

DG_IMAGE / DAT_IMAGELAYOUT / MSG_GETDEFAULT

DG_IMAGE / DAT_IMAGELAYOUT / MSG_RESET

DG_IMAGE / DAT_IMAGELAYOUT / MSG_SET

DG_CONTROL / DAT_USERINTERFACE / MSG_ENABLEDS

DG_CONTROL / DAT_USERINTERFACE / MSG_DISABLEDS

DG_CONTROL / DAT_EVENT / MSG_PROCESSEVENT

DG_CONTROL / DAT_SETUPMEMXFER / MSG_GET

DG_IMAGE / DAT_IMAGEINFO / MSG_GET

DG_IMAGE / DAT_IMAGEMEMXFER / MSG_GET

DG_IMAGE / DAT_IMAGENATIVEXFER / MSG_GET

DG_CONTROL / DAT_PENDINGXFERS / MSG_ENDXFER

DG_CONTROL / DAT_PENDINGXFERS / MSG_GET

DG_CONTROL / DAT_PENDINGXFERS / MSG_RESET


The TWAIN Working Group, 13090 Hwy 9, Suite 3, Boulder Creek, CA 95006

www.twain.org

4

CAPABILITIES

Every Source must support all five DG_CONTROL / DAT_CAPABILITY operations

on:

CAP_XFERCOUNT

Every Source must support DG_CONTROL / DAT_CAPABILITY MSG_GET on:

CAP_SUPPORTEDCAPS

CAP_UICONTROLLABLE

CAP_DEVICEONLINE

Sources that supply image information must support DG_CONTROL

DAT_CAPABILITY /

MSG_GET, MSG_GETCURRENT, MSG_GETDEFAULT on:

ICAP_PHYSICALHEIGHT

ICAP_PHYSICALWIDTH

ICAP_COMPRESSION

ICAP_PLANARCHUNKY *Note: Applicable to color only

ICAP_PIXELFLAVOR *Note: Applicable to bi-tonal and grayscale only

Sources that supply image information must support DG_CONTROL /

DAT_CAPABILITY /

MSG_GET, MSG_GETCURRENT, MSG_GETDEFAULT, MSG_RESET and

MSG_SET on:

ICAP_BITORDER

ICAP_XFERMECH

ICAP_UNITS

ICAP_XRESOLUTION

ICAP_YRESOLUTION

ICAP_PIXELTYPE

ICAP_BITDEPTH

Further to these requirements, the following behavior is highly recommended:

If a Source supports TWPT_BW for ICAP_PIXELTYPE, the Sources must support

DG_CONTROL / DAT_CAPABILITY, MSG_GET, MSG_GETCURRENT,

MSG_GETDEFAULT, MSG_RESET and MSG_SET on:

ICAP_BITDEPTHREDUCTION

ICAP_PIXELFLAVOR

If a Source supports ICAP_BITDEPTHREDUCTION and a value of

TWBR_HALFTONE then it must respond to DG_CONTROL / DAT_CAPABILITY,


The TWAIN Working Group, 13090 Hwy 9, Suite 3, Boulder Creek, CA 95006

www.twain.org

5

MSG_GET, MSG_GETCURRENT, MSG_GETDEFAULT, MSG_RESET and

MSG_SET on:

ICAP_HALFTONES

If a Source supports ICAP_BITDEPTHREDUCTION and a value of

TWBR_CUSTHALFTONE then it must respond to DG_CONTROL /

DAT_CAPABILITY, MSG_GET, MSG_GETCURRENT, MSG_GETDEFAULT,

MSG_RESET and MSG_SET on:

ICAP_CUSTHALFTONE

If a Source supports ICAP_BITDEPTHREDUCTION and a value of

TWBR_THRESHOLD, and the threshold values are adjustable, then it must respond to

DG_CONTROL / DAT_CAPABILITY, MSG_GET, MSG_GETCURRENT,

MSG_GETDEFAULT, MSG_RESET and MSG_SET on:

ICAP_THRESHOLD

The following operations and capabilities are trivial to implement and highly

recommended for all scanners:

DG_CONTROL / DAT_SETUPFILEXFER / MSG_GET, MSG_SET

DG_IMAGE / DAT_IMAGEFILEXFER / MSG_GET

CAP_INDICATORS

CAP_LANGUAGE

CAP_REAQUIREALLOWED

CAP_DEVICETIMEDATE

CAP_SERIALNUMBER

ICAP_IMAGEFILEFORMAT

ICAP_MAXFRAMES

ICAP_FRAMES

ICAP_SUPPORTEDSIZES

ICAP_MINIMUMHEIGHT

ICAP_MINIMUMWIDTH

ICAP_XNATIVERESOLUTION

ICAP_YNATIVERESOLUTION

ICAP_XSCALING

ICAP_YSCALING

ICAP_UNDEFINEDIMAGESIZE

ICAP_TILES

ICAP_LAMPSTATE

ICAP_LIGHTPATH

ICAP_LIGHTSOURCE

ICAP_NOISEFILTER

ICAP_AUTOBRIGHT


The TWAIN Working Group, 13090 Hwy 9, Suite 3, Boulder Creek, CA 95006

www.twain.org

6

ICAP_BRIGHTNESS

ICAP_CONTRAST

ICAP_HIGHLIGHT

ICAP_SHADOW

ICAP_ROTATION

ICAP_GAMMA

ICAP_FILTER

Basic Document Feeder Type Devices

Basic document feeder devices are those that have paper trays to hold one or more

documents for transfer. Unique aspects of a document feeder include the ability to

transfer more than one image, the typical inability to re-scan the same page twice, and the

fact that if there is no paper loaded, it is usually impossible to scan.

If the Source has a document feeder attachment then the Source must respond to

DG_CONTROL / DAT_CAPABILITY / MSG_GET, MSG_GETCURRENT,

MSG_GETDEFAULT on the following capabilities:

CAP_FEEDERENABLED

CAP_PAPERDETECTABLE

CAP_AUTOFEED

If the Source reports TRUE to CAP_PAPERDETECTABLE then it must respond to

DG_CONTROL / DAT_CAPABILITY / MSG_GET, MSG_GETCURRENT,

MSG_GETDEFAULT on the following capabilities:

CAP_FEEDERLOADED

If the Source allows FALSE for CAP_AUTOFEED then it must provide advanced paper

handling support though the following capabilities:

CAP_FEEDPAGE

CAP_CLEARPAGE

CAP_REWINDPAGE

Support for the advanced paper handling capabilities implies that MSG_SET can be

called during states other than 4 and therefore the advanced handling capabilities must be

listed in the following capability:

CAP_EXTENDEDCAPS

The following capabilities are highly recommended for these types of devices:

CAP_FEEDERALIGNMENT

CAP_FEEDERORDER

CAP_PAPERBINDING

CAP_REAQCUIREALLOWED


The TWAIN Working Group, 13090 Hwy 9, Suite 3, Boulder Creek, CA 95006

www.twain.org

7

The following capabilities are recommended for any document fed device that can fit

standard paper sizes in any input orientation (cap – orientation refers to the input

orientation of paper):

CAP_SUPPORTEDSIZES

CAP_ORIENTATION

Production Quality High Speed/Volume Type Scanners

Production Quality High Speed/Volume scanners have greater demands on TWAIN.

With diverse features like bar code reading, imprinting and compressions, they require

much more attention to detail. Production drivers should be prepared to serve

applications that wish to achieve complete programmatic control of all typical and

custom features and this requires a VERY robust TWAIN implementation.

If the Data Source has internal image buffering to allow transfer of multiple images ahead

of retrieval, then it must respond to DG_CONTROL / DAT_CAPABILITY / MSG_GET,

MSG_GETCURRENT, MSG_GETDEFAULT, MSG_RESET and MSG_SET on the

following capabilities:

CAP_AUTOSCAN

CAP_MAXBATCHBUFFERS

CAP_CLEARBUFFERS

If the Data Source supports any kind of internal re-orientation or automatic sizing then it

must respond to DG_CONTROL / DAT_CAPABILITY / MSG_GET,

MSG_GETCURRENT, MSG_GETDEFAULT, MSG_RESET and MSG_SET on the

following capability:

ICAP_UNDEFINEDIMAGESIZE

If ICAP_UNDEFINEDIMAGESIZE can be set to TRUE then it must respond to

DG_CONTROL / DAT_CAPABILITY / MSG_GET, MSG_GETCURRENT,

MSG_GETDEFAULT, MSG_RESET and MSG_SET on the following appropriate

capabilities:

ICAP_AUTOMATICBORDERDETECTION

ICAP_AUTOMATICDESKEW

ICAP_AUTOMATICROTATE

ICAP_FLIPROTATION

ICAP_OVERSCAN

If ICAP_UNDEFINEDIMAGESIZE can be set to TRUE while ICAP_XFERMECH is

set to TWSX_MEMORY, the Data Source must also support the following operation in

State 7 after receiving TWRC_XFERDONE:

DG_IMAGE / DAT_IMAGEINFO / MSG_GET


The TWAIN Working Group, 13090 Hwy 9, Suite 3, Boulder Creek, CA 95006

www.twain.org

8

If the Data Source has any control over a Printer or Endorser type device, it must respond

to DG_CONTROL / DAT_CAPABILITY / MSG_GET, MSG_GETCURRENT,

MSG_GETDEFAULT, MSG_RESET and MSG_SET on the following capability:

ICAP_PRINTERENABLED

ICAP_PRINTER

If the Data Source has control over what is printed through any of the TWAIN defined

Printer Modes, it must respond DG_CONTROL / DAT_CAPABILITY / MSG_GET,

MSG_GETCURRENT, MSG_GETDEFAULT, MSG_RESET and MSG_SET on the

following capability:

ICAP_PRINTERMODE

Depending on what ICAP_PRINTERMODE values are supported, the source must

respond to DG_CONTROL / DAT_CAPABILITY / MSG_GET, MSG_GETCURRENT,

MSG_GETDEFAULT, MSG_RESET and MSG_SET on the following appropriate

capabilities:

CAP_PRINTERINDEX

CAP_PRINTERSTRING

CAP_PRINTERSUFFIX

If the Data Source supports internal image compression, it must respond to

DG_CONTROL / DAT_CAPABILITY / MSG_GET, MSG_GETCURRENT,

MSG_GETDEFAULT, MSG_RESET and MSG_SET on the following capability:

ICAP_COMPRESSION

If the Data Source supports ICAP_COMPRESSION and the value TWCP_JPEG, it must

respond to DG_CONTROL / DAT_CAPABILITY / MSG_GET, MSG_GETCURRENT,

MSG_GETDEFAULT, MSG_RESET and MSG_SET on the following capability:

ICAP_JPEGPIXELTYPE

If the Data Source supports ICAP_COMPRESSION and one of the CCITT values such

as: TWCP_GROUP31D, TWCP_GROUP31DEOL, TWCP_GROUP32D, or

TWCP_GROUP4, it must respond to DG_CONTROL / DAT_CAPABILITY /

MSG_GET, MSG_GETCURRENT, MSG_GETDEFAULT, MSG_RESET and

MSG_SET on the following appropriate capabilities:

ICAP_BITORDERCODES

ICAP_CCITTKFACTOR (only relevant to TWCP_GROUP32D)

ICAP_PIXELFLAVORCODES

ICAP_TIMEFILL

If a Data Source supports any of the following Extended Image attributes, it must respond

to DG_CONTROL / DAT_EXTIMAGEINFO / MSG_GET during State 7, after

successful return of TWRC_XFERDONE by filling in the appropriate supported

TWEI_X values.


The TWAIN Working Group, 13090 Hwy 9, Suite 3, Boulder Creek, CA 95006

www.twain.org

9

If a Data Source supports control over Patch Code detection, it must respond to

DG_CONTROL / DAT_CAPABILITY / MSG_GET, MSG_GETCURRENT,

MSG_GETDEFAULT, MSG_RESET and MSG_SET on the following capabilities:

ICAP_PATCHCODEDETECTIONENABLED

ICAP_SUPPORTEDPATCHCODETYPES

CAP_JOBCONTROL

*Note: Source must also fill in the extended EOJ field of the TW_PENDINGXFERS

structure when CAP_JOBCONTROL is enabled. See DG_CONTROL /

DAT_PENDINGXFERS / MSG_ENDXFER

If a Data Source supports refinement of any Patch Code search parameters, it must

respond DG_CONTROL / DAT_CAPABILITY / MSG_GET, MSG_GETCURRENT,

MSG_GETDEFAULT, MSG_RESET and MSG_SET for the following appropriate

capabilities:

ICAP_PATCHCODESEARCHPRIORITIES

ICAP_PATCHCODEMAXRETRIES

ICAP_PATCHCODETIMEOUT

ICAP_PATCHCODESEARCHMODE

If a Data Source supports control over Bar Code detection, it must respond to

DG_CONTROL / DAT_CAPABILITY / MSG_GET, MSG_GETCURRENT,

MSG_GETDEFAULT, MSG_RESET and MSG_SET on the following capabilities:

ICAP_BARCODEDETECTIONENABLED

ICAP_SUPPORTEDBARCODETYPES

If a Data Source supports refinement of any Bar Code search parameters, it must respond

DG_CONTROL / DAT_CAPABILITY / MSG_GET, MSG_GETCURRENT,

MSG_GETDEFAULT, MSG_RESET and MSG_SET for the applicable following

capabilities:

ICAP_BARCODESEARCHPRIORITIES

ICAP_BARCODEMAXRETRIES

ICAP_BARCODETIMEOUT

ICAP_BARCODESEARCHMODE

If a Data Source supports control of audible alarms, it must respond DG_CONTROL /

DAT_CAPABILITY / MSG_GET, MSG_GETCURRENT, MSG_GETDEFAULT,

MSG_RESET and MSG_SET for the applicable following capability:

CAP_ALARMS

If a Data Source supports audible alarms and has control over the volume, it must

respond to DG_CONTROL / DAT_CAPABILITY / MSG_GET, MSG_GETCURRENT,

MSG_GETDEFAULT, MSG_RESET and MSG_SET for the following capability:

CAP_ALARMVOLUME


The TWAIN Working Group, 13090 Hwy 9, Suite 3, Boulder Creek, CA 95006

www.twain.org

10

The following Operations and Capabilities are highly recommended for this class of Data

Source:

DG_CONTROL / DAT_CAPABILITY / MSG_GET - CAP_ENABLEDSUIONLY

DG_CONTROL / DAT_CAPABILITY / MSG_GET - CAP_CUSTOMDSDATA

DG_CONTROL / DAT_USERINTERFACE / MSG_ENABLEDSUIONLY

DG_CONTROL / DAT_CUSTOMDSDATA / MSG_GET

DG_CONTROL / DAT_CUSTOMDSDATA / MSG_SET

DG_CONTROL / DAT_EVENT / MSG_CLOSEDSOK – (output triplet)

Note: see ‘Permanent Storage/Retrieval Devices’, a Data Source may want to implement

DAT_FILESYSTEM in order to allow applications to index particular camera’s within a

production scanner.

Permanent Storage/Retrieval Devices

Permanent storage/retrieval devices are unique in that more than one image is stored and

the dimensions and bit depth may vary from image to image. These devices could be just

a database of images, or a PCMCIA card from a Digital Camera. Such devices need

features for browsing the available images, retrieve properties and select sets of images

for transfer.

If a Data Source supports Permanent Storage/Retrieval of Images, it must respond to the

appropriate operations and capabilities:

DG_CONTROL / DAT_FILESYSTEM / MSG_COPY, MSG_DELETE,

MSG_CREATEDIRECTORY, MSG_AUTOMATICCAPTURED,

MSG_FORMATMEDIA, MSG_GETFIRSTFILE, MSG_GETINFO,

MSG_GETNEXTFILE, MSG_RENAME

DG_CONTROL/DAT_CAPABILITY/ MSG_GET, MSG_GETCURRENT,

MSG_GETDEFAULT, MSG_RESET and MSG_SET for the following appropriate

capabilities:

ICAP_IMAGEDATASET

If a Data Source supports some Annotation about the Images stored in permanent storage,

it must respond to DG_CONTROL / DAT_CAPABILITY / MSG_GET,

MSG_GETDEFAULT, MSG_GETCURRENT, MSG_SET, MSG_RESET for the

following appropriate capabilities:

CAP_AUTHOR

CAP_CAPTION

CAP_TIMEDATE


The TWAIN Working Group, 13090 Hwy 9, Suite 3, Boulder Creek, CA 95006

www.twain.org

11

If a Data Source supports a flash, it must respond to DG_CONTROL /

DAT_CAPABILITY / MSG_GET, MSG_GETDEFAULT, MSG_GETCURRENT,

MSG_SET, MSG_RESET for the following capability:

ICAP_FLASHUSED2 – Note: replaces ICAP_FLASHUSED with more functionality.

If the Data Source supports Audio Snippets to be associated with an image, it must

respond to DG_CONTROL / DAT_CAPABILITY / MSG_GET, MSG_GETDEFAULT,

MSG_GETCURRENT, MSG_SET, MSG_RESET for the following capabilities:

ACAP_XFERMECH

ACAP_AUDIOFILEFORMAT

If the Data Source supports transfer of Audio snippets, it must also support

DG_CONTROL / DAT_XFERGROUP / MSG_SET with a value of DG_AUDIO and the

following operations:

DG_AUDIO/DAT_AUDIOFILEXFER/MSG_GET

DG_AUDIO/DAT_AUDIONATIVEXFER/MSG_GET

Portable Capture Devices

Portable capture devices are very similar to permanent storage and retrieval devices in

that they typically store a number of images, however they differ in that they often have

real time capture opportunities and limitations related to battery life and lenses.

Examples of such devices would be Digital Camera’s and Camcorders.

If a Data Source supports Power Management, it must respond to DG_CONTROL /

DAT_CAPABILITY / MSG_GET, MSG_GETCURRENT, MSG_GETDEFAULT,

MSG_RESET and MSG_SET for the following appropriate capabilities:

CAP_BATTERYMINUTES

CAP_BATTERYPERCENTAGE

CAP_POWERSAVETIME

CAP_POWERSUPPLY

If a Data Source supports Asynchronous Device Events, it must respond to

DG_CONTROL / DAT_CAPABILITY / MSG_GET, MSG_GETCURRENT,

MSG_GETDEFAULT, MSG_RESET and MSG_SET for the following capability:

CAP_DEVICEEVENT

If the Data Source supports a Stream of Images for implementing a Live Preview, it must

respond to DG_CONTROL / DAT_CAPABILITY / MSG_GET, MSG_GETCURRENT,

MSG_GETDEFAULT for the following capability:

CAP_CAMERAPREVIEWUI


The TWAIN Working Group, 13090 Hwy 9, Suite 3, Boulder Creek, CA 95006

www.twain.org

12

If the Data Source supports Automatic Capture, it must respond to DAT_CAPABILITY /

MSG_GET, MSG_GETCURRENT, MSG_GETDEFAULT, MSG_RESET and

MSG_SET for the following appropriate capabilities:

CAP_AUTOMATICCAPTURE

CAP_TIMEBEFOREFIRSTCAPTURE

CAP_TIMEBETWEENCAPTURES

Further Specific Considerations

Finally, there are a few specifics about implementation that must be addressed. Different

kinds of scanners provide their own unique problems, and leave the developer with more

confusing decisions to make. Consider a Digital Camera, Video Camera, or Capture

Card. It is tempting to call these devices ‘dimensionless’.

Before making that decision, first consider the burden this puts on the calling application.

Not only does it have to be ready to negotiate with conventional scanners, it now must

consider a scanner that has no conventional features. It is highly recommended that all

Data Sources provide reasonable dimensions, considering the intended output and design

of the device. Digital Cameras can consider mapping to classic photograph sizes, or

perform some calculation based on the aperture size.

For example: Microfilm scanners work on tiny frames, but it would completely useless to

map the physical attributes of the TWAIN Data Source to such a small size. If the

intended output or the original data was 11x17, then 11x17 is the actual

ICAP_PHYSICALWIDTH and ICAP_PHYSICALHEIGHT reported for that TWAIN

Data Source.

* The TWAIN name, logo and phrase "TWAIN- Linking Images with Applications'

are trademarks of the TWAIN Working Group. All rights reserved.