Users Manual for the Wacom - Digitizerdriver for the Amiga Abstract The program enables you to use a pressure sensitive digitizertablet from Wacom with your Amiga. The tablet can be used together with the mouse (or without it) as direct input medium. Therefore the dri- ver can be used together with (nearly) every software. Furthermore the (pressuresensitive) data provided by the tablet can be exported in custom applications using documented softwareinterfaces. Under AmigaOS 3.0 or better the pen data is also directly used by Intui- tion and passed to every window where an application can use the tabletdata. (c) 1993-1996 Roland Schwingel 1. Introduction and legal stuff The Program enables you to use a pressure sensitive digitizertablet from Wacom with your Amiga. The amigamousepointer is controlled by the driver for providing compatibility to nearly every program. The digitizertablet can be used either in pressure or in normal mode. Nearly all the (pressuresensitive) data provided by the tablet can be exported in custom applications using documented softwareinterfaces. Under AmigaOS 3.0 or better the pen data is also directly used by Intuition and passed to every window where an application can use the tabletdata. 1.1 Legal stuff The Wacom Driver is Shareware. If you want to use the program you should send - after you have tested the program for about 14 days - the registration fee ($20.00 or more) together with the filled registration form to the author. With your registration fee you are helping to develop (more good) software for the Amiga. The version you are holding in your hand is not crippled in any way. The programs in the Develop drawer are not Shareware. They are serving as examples for communicating with the driver in own applications. Together with their source they are Freeware. The software and all principles described here were developed strictly using the Amiga Developer Guidelines. The package was extensively tested and is considered to be free of errors. But there is nobody on earth who is perfect. Therfore I MUST write the following lines. Read them carefully. +-----------------------------------------------------+ | ATTENTION: | | | | YOU ARE USING THE WACOM DRIVER ENTIRELY AND ONLY | | ON YOUR OWN RISK. THE AUTHOR IS NOT LIABLE AND CAN | | NOT BE PUNISHED IN ANY WAY FOR PROPABLY OCCURING | | DAMAGES ON YOUR HARD- OR SOFTWARE OR OTHER DAMA- | | GES OR ERROS WHICH MAY RESULT FROM USING THE SOFT- | | WARE OR ITS DOCUMENTATION. THIS PACKAGE IS PROVIDED | | "AS IS", AND THERE IS NO WARRANTY. | +-----------------------------------------------------+ Your are allowed to give the package to another party at any time if you consider the following terms: o The Wacom package may only be given away to another party in complete and unchanged form. You are not allowed to delete files nor to modify one or more files nor to add files to the package if you want to give it away. Compression of the package is allowed as long as all informations are remaining completely intact when de- crompessing. o The package may not be published on PD-Disks with a price greater than $5 (US). Exceptions are PD-CD-roms, their price may be higher. o Commercial use or trade of the package is only allowed after given permission by the author. The Wacom Company is allowed to accomplish and distribute their tablets together with this package. This circumstance frees the person or company which buys the digitizer together with the package not from paying the Shareware fee. 1.2 Registering and the address of the author If you want to use this program you must register it. The amount of the Shareware fee is 20.00 US$ (or 25.00 DM). Please do not send any other currencies. If you want to send the money via bank order you should mention your name and address on the bank order form. The directory of this document contains a registration form with the filename "Register-E.Txt". Please print it, fill it and send it to- gether with the Shareware fee to: Roland Schwingel Lilienthalstrasse 9 92421 Schwandorf GERMANY If there are any questions or problems concerning the package you can reach the author also through Email and telephone: Email: roland.schwingel@extern.uni-regensburg.de Phone: +49-(0)9431-5779 1.3 Updates The registrationfee also contains the mailing of the actual Version on disk. When there is a new version in preparation I will wait with sen- ding until the new Version is finished. Updates are sent via Email for free. If you like an update via disk you should send US$8 (or 10DM) to the above adress for covering the costs for shipping and handling. The actual version can also be obtained via anonymous FTP from various Aminet sites and will also be published on PD-Disk series. 2 System requirements and Installation 2.1 System requirements If you want to use the Wacom driver you will need at least Kickstart and Workbench 2.04. The package contains also a german catalog file which you can use on a WB2.1 and up system and enables you to receive all texts which are printed by the program in german. And at least you need a Wacom tablet. These are the tablets which are currently supported by the driver: o SD-013 o SD-113 o SD-210 o SD-310 SD-311 SD-312 o SD-320 SD-321 SD-322 o SD-420 SD-421 SD-422 o SD-510 o all digitizers of the UD-Series eg. ArtZ, UD-1212, ... o all digitizers of the KT-Series eg. ArtPad The digitizer should be configured as delivered by Wacom. The driverprogramm runs with any CPU which is currently used with the Amiga. If you want to use the driver, a faster CPU is recommended because if you are running on 68000 the mousepointer is a little bit slow. The memoryusage of the driver is very low (about 48KB), it can therefore be used together with any other programm. Together with some mouse accelerators or "Sun Mouse" tools the mousepointer reacts a little bit wild. If you got problems steering the mousepointer with the tablet deactivate those tools. 2.2 Installation Installation is very simple. The driverprogram should be copied to- gether with its Icon in the WBStartup drawer on your bootpartition (or in the WBStartup Drawer in the rootdirectory of your boootdisk). There the program will automatically be activated every time you boot. The absolute path for installing the driver should be: SYS:WBStartup If you are running under Workbench 2.1 or 3.x you can install the german catalogfile if your workbenchlanguage is "Deutsch". Just copy catalogs/deutsch/Wacom.catalog to LOCALE:catalogs/deutsch/Wacom.catalog. To make installation easier there is a SHELL-Skript, wich performs all these actions mentioned above. Just start "Install" from SHELL or Workbench. The tablet must be connected to the serial port of your Amiga. If you got a Multi-IO board with serial ports you can also connect the tablet there. A scheme for a connector cable for the SD-series tablet is sup- ported in the directory of this document for the reason that you are having no suitable cable. It is an IFF-ILBM picture called "Wacom-SD.ilbm". The scheme shows a cable for Amiga500/2000. The cable should also be suitable for A3000/4000/600/1200. Only A1000 Users have to modify the cable due to a different serial port connector. If you got an UD- or KT-tablet you have to use the delivered cable which also suits perfectly. (UD/KT-series digitizers are having the powerstrips inside the datacable.) 3 Usage and Configuration of the Driver The Wacom Driver is a so called Commodity. Commodities are linked in the input data stream of the Amiga and are sending/filtering Input- events. The Driverporgram was developed for the WBStartup drawer of the WB (WB = Workbench). There it is started whenever the Workbench is loaded. The driver can only be started once. When it is started for the second time and the first program is still active in memory the first program opens its configurationwindow and the second one quits immediately and silent. The driver can also be started from any other drawer from the Shell or from the WB. The program takes a couple of parameters from the user when it is started. If you start it from WB the so called TOOLTYPES are used. These tooltypes are stored in the icon of the program. 3.1 The Icon Tooltypes In most cases you need not change the tooltypes of the Wacom driver because it saves its settings on its own in the Tooltypes (look later chapters for more details). The following Tooltypes are used: CX_PRIORITY (Default: 0) The priority of the commodity. Normally the default value of 0 is no subject of change. CX_POPUP (Default: yes) If this tooltype is set to yes the configurationwindow is opened every time the program is started and you can easily configure the driver before the tablet is initialized. If the tooltype is set to no the driver will immediatley be started using the settings saved in the tooltypes. The configurationwindow can easily be opened via hotkey even if the driver is running. CX_POPKEY (Default: lalt w) Here is the keycombination stored which is used as hotkey for opening the window when the commodity is active. Defaulted to left Alt key together with the key w. APPICON (Default: no) The window can also be opened when the commodity is deactivated. If APPICON = yes there will be a wacomappicon displayed on the WB. If a doubleclick is performed on this appicon the confi- gurationwindow opens. APPMENU (Default: no) In the "Tools" menu on the WB an entry is created which opens the window everytime it is selected. (APPMENU must be set to yes) BEEPER (Default: off) This field contains the state of the tabletbuzzer^1. If set to on the buzzer will be enabled for a short time whenever a button on an input device is pressed. MODE (Default: normal) Setting whether the tablet should be in pressure mode or not. If MODE = pressure the pressure sensitive mode is selected. You can use the so called "pressure stylus" in this mode. If MODE = normal the "standard stylus" or the cursor can be used for input. This Tooltype is only necessary for SD-Tablets and for UD-Tablets which are driven with the Wacom II-S Commandset. LMB_EMULATION (Default: off) If the tablet is used in pressure mode there can no buttonstatus be transmitted to the driver. Only pressure data is supplied in this mode. Therefore it is normally impossible to hit any icons or gadgets with this pen. The driverprogram is able to emulate a click to the left mousebutton when a certain pressure limit is reached. If you want to use this feature you must set this tooltype to on. Only relevant when MODE=pressure and Wacom II-S commands are used. LMB_LIMIT (Default: 15) That is the limit which must be reached in pressure mode to emulate a LMB hit. Set MODE = pressure and LMB_EMULATION = on. Values for the limit must be between -30 and +30. This tooltype is also only necessary for SD-Tablets and for UD-Tablets in Wacom II-S mode. DEVICE (Default: serial.device) Here is the name of the systems devicedriver stored which is used to com- municate with the Wacom tablet. If the tablet is connected to a MultiIO board you must insert the name of the Multi-IO driver. If connected to the normal serial port this place should be filled with serial.device. (Please refer also to your MultiIO oard documentation.) UNIT (Default: 0) The default value must only be changed when the digitizer is connected to a MultiIO-Board. Insert the number of the MultiIO-Board's serial port to which you have connected the tablet. (Please refer also to your MultiIO Board documentation.) MOUSE (Default: FULL) The driverprogram enables the user to control the mousepointer with the digitizer. With help of this tooltype you can define which parts of the mouse will be emulated. There are 3 independent settings: +-----------+-------------------------------------+ | FULL | The mousepointer and the 2 mousebut-| | | tons will be set by_the_program | +-----------+-------------------------------------+ | POINTER | Only the mouspointer will be set by | | | the tablet. | +-----------+-------------------------------------+ | NONE | No mousemulation. The data send by | | | the tablet are | | | only provided to the softwareinter- | | | face. | +-----------+-------------------------------------+ COMMANDSET (Default: WACOM_IV) This tooltype is used to define which commandset is used for communication with the tablet. You can choose^2 between WACOM_IV and WACOM_II-S. AREA (Default: BLANK) Determines size and location of the working area on the tablet. +-----------+-------------------------------------+ | FULL | The whole working area on the tablet| | | can be used for input. | +-----------+-------------------------------------+ | BLANK | The same as FULL with the difference| | | that there is a 4 millimeter sized | | | border around the working area to | | | make it easier to reach the border | | | of a screen with the tablet. This | | | border is also used to initiate the | | | scrolling of an so called | | | Autoscroll-Screen. | +-----------+-------------------------------------+ | CUSTOM | A selfdefined working area is used | | | for data input. Also look at the | | | CUSTOM_AREA-Tooltypes. | +-----------+-------------------------------------+ MULTIMODE (Default: OFF) The Wacom IV commandset offers the capability of using 2 inputdevices^3 at the same time. You can switch this on or off using this tool- type. If you want to use multimode you must also use the Wacom IV commandset. MULTI_MOUSE (Default: PEN) Because you can use two inputdevices at the same time when in multimode, you must determin which device is used as mouse. You can select between PEN and DIGITIZER. This has only an effect when the mouseemulation is also switched on. CUSTOM_AREA_LEFT (Default: 0) CUSTOM_AREA_TOP (Default: 0) CUSTOM_AREA_RIGHT (Default: 15239) CUSTOM_AREA_BOTTOM (Default: 15239) These 4 Tooltypes are de- scribing the borders of the custom working area. Everything inside can be accessed. These Tooltypes are only used when AREA = CUSTOM. The marked Area must have at least a size of 1000 on 1000 points. INPUT_EVENT (Default: TABLET) This Tooltype selects the Inputevents^4 that are used to set the mousepointer. You got two choices: At first there is TABLET. All data is sent over an inputeventsubclass to the OS^5 as an inputevent from a digitizer. This also enables sending of pressure data. Under AmigaOS 2.0 this tabletinterface is not completely implemented. This solution is not very fast and the pressure is currently not used inside the OS. Furthermore there are problems with autoscrolling screens. When running AmigaOS 3.0 or better there is a different much better tabletinterface. The tablet data like the pressure are taken by the operating system and sent to every intuition window. All what the application has to do is to take the datas. Dependend on your current OS Version the correct routines are choosen automatically. The other possibility is PIXEL. The data will be send as a kind of mousedata to the OS. This solution is faster, but has also some disadvantages. There are problems with screendragging and a recalculating from tabletcoordinates to screencoordinates is necessary inside of the driver. Additionally there is no way to send pressuredata. You should try out both settings and then choose the one you like most. DONOTWAIT This tooltype is not used by the tabletdriver. It is used by the WB if you start from the WBStartup drawer. The Wacom driver sets this tooltype auto- matically. Once again I have to mention that you need not change the contents of the tooltypes manually. All settings can be made from the configurationwindows. Your settings are saved here inside the tool- types by the program automatically. ____________________________ ^1: The buzzer is only available to tablets of the SD series. ^2: Attention: SD series tablets can not be driven in Wacom IV ! ^3: Pen and Cursor. You need two different devices ^4: Inputevents: Commands which are sent to the operating system (more exactly here: "input.device") for all kinds of input (eg. mouse, keyboard) in order to start the desired action. ^5: OS = operating system 3.2 Start from the SHELL If you are starting the driver from the SHELL the icon tooltypes are not read and passed to the program. You must therefore give all parameters to the program by writing them separated by spaces behind the program's name. If a parameter is equivalent to the default value you need not write it in the commandline. Example for a SHELL start: Wacom MOUSE=POINTER 3.3 Differences between the tablets The Wacom driver supports three different kinds of tablets. First there are the tablets of the SD series and on the other hand there are the UD and KT-series digitizers. The last one can do every- thing that SD tablets can do - with two exceptions. The UD series tablets are having no buzzer and no extra reset knob^6. ____________________________ ^6: Isn't so necessary, because UD tablets are configured with help of a menubar and if a Reset is necessary the tablet will do so automatically. 3.3.1 The SD Series tablets For these digitizers there are existing 3 different kinds of input devices: o Standard Stylus: This pen has two switches (one in the tip and one on the side) and is designed for drawing. There is no pressure transmission. o Pressure Stylus: This pen has directly no switches, but a "soft" tip. Designed for transmitting pressure. o Cross hair cursor: Designed for precise digitizing. It has 4 Buttons and transmitts no pressure. Beside of third party tabletemulations this tablet features the Wacom II-S commandset. 3.3.2 The UD Series tablets This digitizer uses only 2 different kinds of input devices: o Stylus: This pen also has two switches (one in the tip and one on the side). The tip switch also sends pressuredata, therefore there is no need for an extra pressure pen. Recently, additional pens are also available with a different number of switches and different characteristics. o Cross hair cursor: There are two different kinds. One with 4 and one with 16 Buttons. These devices are also sending no pressure. Beside of third party tabletemulations the Wacom II-S and the Wacom IV commandsets can be used. The Wacom IV commandset has some significant improvements: o Greater pressure range: Wacom II-S Commandset features 60 steps. Wacom IV features 120 or 256^7 steps of pressure. o Multimode: It is possible to use 2 (different) input devices at same time. o Macrokeys: The UD tablets are having so called "Macro Buttons" outside the sensitive area. They can be used from software for own funtions. o Pressure characteritics can be changed^8. o Many expansions that are making it easier for the programmer. Among these there is a more compact data representation which makes it faster to transform the received data. Additionally Wacom IV always works in pressure mode and button information is supplied at the same time. ____________________________ ^7: with Romversion 1.2 and up. You have also double density with these roms. ^8: You choose between two settings. 3.3.3 The KT Series tablets Currently there is only one tablet of this series available (ArtPad), so this section describes this tablet. These tablets can do everything what UD series tablets can do, but with some limitations. o This tablet can operate with Wacom II-S and Wacom IV commands. o Like UD series tablets with a romversion 1.2 and up it has a double resolution^9 and a double pressurerange^10 compared to UD series tablets with a romversion lower than 1.2. o There is no menubar. o The only inputdevice available for this tablet is the pen. There is no digitizer, and therefore no multimode. ____________________________ ^9: up to 2540 lpi. ^10: 256 steps 3.4 Controlling the mousepointer with the tablet With activated driver the mousepointer can be controlled either with the mouse or the tablet (if mouseemulation is active). The whole selected working area on the tablet represents the area on your monitor which can be reached by the mouse. The top left edge corres- ponds to the top left edge on your monitor. The bottom right edge corresponds to the bottom right edge on the monitor. The buttons of the tablet's input devices are connected to following functions: Standard Stylus: A click with the tip is equivalent to a click on the left mousebutton. The switch on the side of the pen reacts like the right mousebutton. This is also TRUE for the combined pen of the UD/KT series tablet in Wacom IV mode. Pressure Stylus^11: This pen can only be used when in pressure mode. The pen transmits the valid pressure between -30 and +30. You can, if you like to, enable the drivers LMB emulation capability. When this option is switched on a hit to the left mousebutton is emulated when a certain pressure is reached. Cursor: This device has four buttons. Two of these buttons (the top button in the middle and the bottom button in the middle) are for free usage in own app- lications. The left and the right button are having the same functions like your mouse. If you got a 16 buttoned cursor the mouse funtions are mapped to the buttons 2 and 4. ____________________________ ^11: only available with SD tablets. 3.5 The Mainwindow The mainwindow will appear when at least one of these events occur: o When the program is started and the tooltype CX_POPUP is set to yes. o The Commodities Exchange^12 programm has sent an "appear" message to the driver. o The hotkey was preesed. (only when Commodity is active) o The appicon was doubleclicked. (only when the appicon option is enabled) o The Wacom AppMenuItem was selected from the WB's "Tools" menu. (only when the appmenu option is enabled) o The program was started again even it was still active in memory. The window is devided in four areas. For description the english localization is used. Most of the driverfuntions can also be accessed from keyboard too by hiting the corresponding underlined letter. _______________________________ ^12: Commodities Exchange is a part of your Workbench disk. 3.5.1 Info The type and the romversion of the tablet are displayed here when the driver was activated succesfully. 3.5.2 Commodity Preferences Here you can enter all commodity relevant data. Hotkey Using this stringgadget you can enter the keycom- bination for the hotkey which opens the closed window when the commodity is activated. If you don't like the default hotkey just enter a new one. It will be activated immediately after you have entered it. For valid keyexpressions look into your Workbench manual in the commodities chapter. Popup This cyclebutton determins whether the window should be opened upon program start or not. Pri Priority of the commodity. Normally the default value (0) needn't be changed. Commodity Only when the commodity is activated the mousepointer can be positionated using the tablet. Also opening the window using the hotkey is only available when the commodity is active. Everytime the cyclebutton switches from deactivated to activated the tablet is completely new initialized. AppIcon If this checkbox is selected the window can also be opened using an appicon on the Workbench. Just doubleclick it and the window will open. The image for the appicon will be taken from the driver's icon. If there is no icon a build in one is used. AppMenu When this gadget is selected the window can be opened selecting the WacomII-S/IV Driver: Popup menuitem from the workbench's toolsmenu. 3.5.3 Mouse Emulation In this Area you can select the mouse emulation which should be used. With Tablet selected, the AmigaOS tablet interface will be used. Intuition gets tablet data like pressure and tilt supplied. When Pixel is selected, a pure mouse is emulated. Intuition can not be supplied with pressure or tilt. Applications which are using one of the other software interfaces will still be supplied with this data by these interfaces. This mode is suggested, when you are using tools which depend on native mouse events and are getting confused, when they receive tablet events. Examples are some screenblankers and other mouse tools. 3.5.4 Digitizer Preferences All settings concerning the tablet can be made here. Device This stringgadget contains the name of the device which is used to communicate with the tablet. If you have connected the tablet to a multi-IO board you need to enter the name of the device for this board. If the tablet is connected to the normal serial port of the Amiga the name of the device should be serial.device (A change of this setting will only be applied to the tablet after the next initialization). Unit The default value (0) must also be changed when the tablet is connected to a multi-IO board. You have to enter the unitnumber of the serial port you have the tablet connected to. Please refer to the boards manual (A change of this setting will only be applied to the tablet after the next initialization). Commandset Selects the commandset which is used to communicate with the tablet. You can choose between WACOM II-S and WACOM IV. Wacom IV is only available with the UD/KT series and should be used if you got one. If you got a SD series tablet and want to run Wacom IV this will be detected while the initialization phase of the tablet and you will be notified to correct it. Multimode The Wacom IV commandset enables you to use two different inputdevices at the same time. If you want to have this switch this on. Buzzer If activated the internal tablet buzzer sounds when a button on an input device is pressed. Remember, only SD series tablets are having a buzzer (A change of this setting will only be applied to the tablet after the next initialization). Set Mouse Determins which parts of a normal mouse will be emu- lated by the driver. You can choose Pointer+Buttons, only Pointer and None. If None is selected the incoming data from the tablet will only be available through the softwareinterface. Multi-Mouse When multimode and mouseemulation are active you must have determined which of the two inputdevices should serve as mouse. Pressure-Mode If this gadget is selected the tablet is put to pressuresensitive mode during the next initiali- zation. You have to use the so called pressure pen in this mode if you are using a SD series tablet. If Wacom IV commandset is selected the tablet is auto- matically working pressuresensitve. Emulate LMB When selected a hit to the left mousebutton is emu- lated when a certain pressure is reached if you are working with Wacom II commandset. When Wacom IV is used the parallel transmitted state of the buttons is used for mousebuttons. Therefore you can't select this in Wacom IV mode. Limit for LMB Pressure which is at least needed to emulate a hit to the left mouse button. (value must be between -30 and +30.) Only selectable if Wacom II is active and LMB emulation is switched to on. Set Working Area If selected a window is opened. Inside this window you can choose the customize the tablet's working area. 3.5.5 Controlsection With these 3 gadgets the driver can either be quited or the window can be closed or the settings of the tablet can be saved to disk. Hide Hitting this gadget closes all windows. If the tablet must be new initialized due to modified settings this is done here, too. The driver is not quited. Save Causes the program to save the settings in the tool- array of its icon. If there is no icon an icon is generated. If the tablet must be new initialized due to modified settings this is done here, too. Quit After verification of your choice the driver is re- moved and quited. 3.5.6 The Menus With Version 1.16 the Wacom driver also has menus. About ... Opens a little window with some informations con- cerning the driver. Save Save the current settings to the icon. Hide Closes the commodity window and initializes the tablet if necessary. Quit Quits the program after request. 3.6 The Area Window This window is used to define which parts of the sensitive tabletarea should be used for input. This window is structured in two areas. 3.6.1 Working Area There are 3 possibilities: Full Tablet The whole sensitive area of the tablet is used for input. Full Tablet, Borderblanking Once again the whole sensitive area is used, but there will be a little (4 millimeters wide) border on each side of the tablet which is not directly used. This has two advantages: 1. It is easier to access the edges of a screen. 2. The border is used to initiate the scrolling of Autoscroll screens. Custom Area A self defined workingarea is used for input. If this gadget is selected the gadgets for the custom area are enabled. If you leave again a few milli- meters wide border the scrolling of autoscrollscreens can be initiated. 3.6.2 Customized Area A custom area can be selected by defining the top left and the bottom right edge of the area. You can do this by entering the coordinates by hand or you can directly read them from tablet. The last method is working even with activated and deactivated driver. The selected area must have at least a size of 1000 points in both directions. Reading of the coordinates from tablet can be finished by pressing a key on the tablet's inputdevice and aborted by pressing the escape key on the keyboard. 4 General notes o After each initialization a buzzer sound from the tablet is heared. This is normal and shows the end of this process. (only digitizers of the SD-Series) o Following changes of the settings are making it neccesarry to re- configure the tablet: - Device - Unit - Buzzer - Pressure-Mode - Multimode - Every change within the definition of the working area. o Together with some mouse accelerators or "Sun Mouse"-tools the mousepointer reacts a little bit wild. If you got problems steering the mousepointer with the tablet deactivate those tools. This pro- blem occurs because some tools are not expecting inputevents from a tablet. When you got problems with these programs switch them off, or change the mouseemulation to Pixel. o Due to tolerances in the production of the pens some pressure pens could have a little bit greater range. o After accidently hitting on the resetknob on the back of the tablet, it must be reinitialized. The same must be done after changing the configuration of UD series tablets with help of the menubar of the tablet. o You are advised not to make changes to the configurationwindow using the tablet, because the data sets which are sent by the tablet while moving the pen or cursor can disturb the reconfiguration of the tablet. I have tried to avoid this possibility as good as possible (and in more than 99% of all cases you can operate the driver with the tablet without any problems), but you can never know. o You mustn't configure your tablet to the commandset or other set- tings you want to run the driver with. All tabletconfiguration (commandset, pressure etc.) are made by the driver. No setting which you have saved to the tablet will be changed in tabletmemory. Only the current working mode is temporarily changed by the driver. 5 How to get tablet data in own programs You want to write a paintprogram and you want to control the size of your tools according to the pressure the pen applies to the tablet? Then you should read this chapter because the Wacom driver supports comfort interfaces to custom applications for direct data export. This chapter only describes the builtin softwareinterfaces. The OS 3.0 tabletinterface is described in the Amiga's developers kit. Furthermore there is a program with sourcecode in the drawer Devlop of the package that shows the usage of the OS 3.0 tabletinterface. It must be possible even for novice programmers to implement this interface. 5.1 Communication between tabletdriver and application The Amiga operating system 2.0 offers only small support for pressure tablets. Therefore I had to find an own way to support these (pressure) data to custom applications. The Wacom driver uses the Amiga messageports for export. Due to the fact that the driver is setting the mouse (if you like) you only have to take care for pressure or tilt data, even the software- interface offers much more than this. Upon start the driver creates a public messageport which is used for data export. The Wacom driver package contains a drawer named Develop. There you can find the C-sourcecodes and the compiled versions of some demo programs, which are using the softwareinterfaces of the driver in order to get the data. Among these files there is one called "Wacom.h" a C headerfile which you can use in own applications. This file contains all defines and structures you need for receiving the data from the driver. Before you include "Wacom.h" you should include ""^13. You can get the adress of the public messageport in the following way: struct MsgPort *Wacom_data_Port; ... /* The portname is also defined as WACOM_PORT_NAME in Wacom.h */ Wacom_data_Port=FindPort("Wacom DataPort"); ... Now you have to create an own messageport and an own WacomMsg. struct IntuitionBase *IntuitionBase struct MsgPort *Our_Port; struct WacomMSG WMess; /* look Wacom.h */ ... if(Our_Port=CreateMsgPort()) { WMess.Mess.mn_Node.ln_Type=NT_MESSAGE; WMess.Mess.mn_Length=sizeof(struct WacomMSG); WMess.Mess.mn_ReplyPort=Our_Port; WMess.Command=WCMD_POLL_PASSIVE; WMess.Param=WACFLG_ALLOWSCREENEVENTS; WMess.AppScreen=IntuitionBase->ActiveScreen; } ... Now you can send the request for data to the Wacom driver: (This is an example for the passive API of the driver.) if(Wacom_data_Port) { /* send request */ PutMsg(Wacom_data_Port,(struct Message *)&WMess); /* Wait for answer */ WaitPort(Our_Port); /* better Wait(1L<mp_SigBit); */ if(GetMsg(Our_Port)) { printf("Current X-Coordinate:%ld"n",WMess.WacomInfo.Tablett_X); ... } } Before you can quit your program you have to free all used resources. ____________________________ ^13: exec/exec.h is a part of your C development package. 5.2 The different API's Besides of the AmigaOS API there are a passive and an active API, with which you can correspond directly with the driver. The way of using the APIs is nearly identically. 5.2.1 The passive API This interface is called passive, because when an application wants to get data from the driver it has to ask the driver every time for the data. The driver is not sending automatically some data to the client application, when some values have changed. If you want to get tablet data you must send a WacomMSG to the drivers data port every time. Look at the end of the preceding chapter. With this API it is necessary that the field Command of the WacomMsg structure is set to WCMD_POLL_PASSIVE. Generally it is recommended to study the PassiveAPIDemo program. 5.2.2 The active API In opposition to the passive API the driver is automatically sending messages to the client applications, whenever something has changed on the tablet. Therefore every application has to register, and unregister, itself at the driver. After registering the driver begins immediately to send messages to the application, whenever a data package from the tablet is received. The messages are sent to the ReplyPort, which is supplied in the WacomMSG structure. Registering at the API: Therefore you are sending a WacomMSG with Command=WCMD_START_ACTIVE to the data port of the driver. For the Param field you are having the choice between WACFLG_ALLOWSCREENEVENTS and WACFLG_FORBIDSCREENEVENTS. With these values you can switch off the mouse emulation for the screen of the client (which is set in AppScreen). This is useful if you want to do this on your own (eg. on a custom 24Bit screen). When the client opens on a screen which is also shared to other applications you must not use WACFLG_FORBDSCREENEVENTS. In AppScreen you must set the adress of the screen, even when you are not using the FORBIDSCREENEVENTS Feature. Because the client is only receiving messages from the driver, when AppScreen ist the current active screen. When you set AppScreen to NULL, all events will be sent to the client, even those which are not belonging to him. ... WMess.Command=WCMD_START_ACTIVE; WMess.Param=WACFLG_ALLOWSCREENEVENTS; WMess.AppScreen=IntuitionBase->ActiveScreen; PutMsg(Wacom_data_Port,(struct Message *)&WMess); /* Wait for Reply */ WaitPort(Our_Port); /* Get response from driver */ GetMsg(Our_Port); if(WMess.Command==WCMD_OK) { ... /* everything ok */ } ... Data exchange with the driver: After registering at the drivers data port the message port which is delivered in the Replyport field of the WCMD_START_ACTIVE message will receive messages as soon as the user is doing something on the tablet. You should reply these messages as fast as possible. It would be best if you copy the message and reply it. And then interpret the data of the copied message. You may never write to received messages, neither before nor after replying them ! There are two different kinds of messages, which are sent from the driver to the client application. They can be differented by the Command field. When it is set to WCMD_DATA_TRANS you got a normal data package from the driver. You can use this data now. The other possibility is WCMD_MSG. When you receive such a message, you must look at the Param field. It can contain the following pos- sibilites: +------------------------+-------------------------------------------+ |Value |Description | +------------------------+-------------------------------------------+ |WACMSG_DRIVER_DEACTIVE |The driver was deativated | | |(temporarely). From now own you will | | |not receive any tablet data. | +------------------------+-------------------------------------------+ |WACMSG_DRIVER_ACTIVE |The driver was reactivated. From | | |now, you can receive data again. | +------------------------+-------------------------------------------+ |WACMSG_DRIVER_QUIT |The driver was quited by the user. | | |Now you may never access the data | | |port of the driver. Even a | | |WCMD_STOP_ACTIVE may not | | |be sent! | +------------------------+-------------------------------------------+ If you receive a WCMD_ERROR message there can be the following values in the Param field: +------------------------+-------------------------------------------+ |Value |Desription | +------------------------+-------------------------------------------+ |WACERR_REPLY_UNDERFLOW |Reply Error of the client | +------------------------+-------------------------------------------+ |WACERR_API_INSTALL |Error installaing active API | +------------------------+-------------------------------------------+ |WACERR_API_UNINSTALL |Error removing active API | +------------------------+-------------------------------------------+ |WACERR_INVALID_COMMAND |driver received illegal command | +------------------------+-------------------------------------------+ Unregistering from the active API: Unregistering is similar to registering. If the FORBIDSCREENEVENTS feature was on when registering, events will be generated again for this screen. ... WMess.Command=WCMD_STOP_ACTIVE; WMess.Param=WACFLG_ALLOWSCREENEVENTS; WMess.AppScreen=IntuitionBase->ActiveScreen; /* Look if port is still valid */ if(FindPort(WACOM_PORT_NAME)) { PutMsg(Wacom_data_Port,(struct Message *)&WMess); /* Wait for reply */ WaitPort(Our_Port); /* get response from driver */ GetMsg(Our_Port); ... } ... General Hints: There are still a few things which must be considered: o Only send commands to the driver, when there are no messages left, which you have to reply. o Don't close the screen of the client, before you have unregistered from the API. o Never nest drivercommands. This is strictly prohibited: WCMD_START_ACTIVE WCMD_START_ACTIVE WCMD_STOP_ACTIVE WCMD_STOP_ACTIVE Overview of the Command field: +------------------------+-------------------------------------------+ |Value |Description | +------------------------+-------------------------------------------+ |WCMD_POLL_PASSIVE |Passive API Request | | |(the "old" API) | +------------------------+-------------------------------------------+ |WCMD_START_ACTIVE |register at the active API | +------------------------+-------------------------------------------+ |WCMD_STOP_ACTIVE |unregister from the active API | +------------------------+-------------------------------------------+ |WCMD_PAUSE_ACTIVE |Temporarely pause the API for this client | | |(other clients are not bothered) | +------------------------+-------------------------------------------+ |WCMD_RESTART_ACTIVE |resume pausing | +------------------------+-------------------------------------------+ When you have sent a message to the driver, you will receive in the Command field of the reply message, whether the command was succesful. +------------------------+-------------------------------------------+ |Value |Description | +------------------------+-------------------------------------------+ |WCMD_OK |Command executed succesfully | +------------------------+-------------------------------------------+ |WCMD_ERROR |An error has occured | +------------------------+-------------------------------------------+ |WCMD_MSG |The driver has something to tell | +------------------------+-------------------------------------------+ When you get WCMD_ERROR or WCMD_MSG there is a description in Param available (as mentioned above). Additionally I suggest the study of two demo programs. They are called ActiveAPIDemo and AvoidScreenDemo. 5.3 The datastructures The WacomInfo structure (which is part of the WacomMSG structure) containes beside of the pressure much more data. For detailed do- cumentation look into "Wacom.h"^14. ____________________________ ^14: The file is printed in appendix A. 5.3 The fields of the WacomInfo structure o Sync BOOL The presence of this field has only compatibility reasons. In version 1.0 this field was used to determin whether the mousepointer is already positioned at the moment the data package is transmited to the application. In Version 1.10 and up the data package will be transmitted to you after mousepositioning. Therefore this field can be ignored and has always FALSE. o Driver_running BOOL Shows whether the driver is running or not. If this field is TRUE the driver is active. o Wacom_Series UBYTE This field contains the used tablettype. +-------+-------------------+ | Value |Tablettype | +-------+-------------------+ | 0 |SD series tablet | +-------+-------------------+ | 1 |UD/KT series tablet| +-------+-------------------+ o Beeper BOOL If this field is set to TRUE the internal tabletbuzzer of SD tablets will be activated for a very short period whenever a button on a tablet's input device is pressed. o Mode BOOL Is set to TRUE when the tablet is working pressuresensitive. If Wacom IV commandset is used the tablet is working automatically in pressure mode. If running Wacom II-S pressure mode must be selected manually. o MB_Emu BOOL If running Wacom II-S in pressure mode, there is no button trans- mission of the pen possible. You can't hit any gadget or anything else with the tablet. Therefore a hit to the left mouse button is emulated when a certain pressure is reached and this field is set to TRUE. (only when mouse emulation is switched on). If running Wacom IV the parrallel transmitted button state is used for mouse- buttons and this field contains FALSE. o Pressure_Limit integer Contains the limit which must be reached by the pressure to cause a click to the left mousebutton. Holds a value between -30 and +30 when in pressuresensitive Wacom II-S mode and MB_Emu=TRUE. Other- wise it contains NO_PRESS. o Pressure WORD Contains the actual pressure when the tablet is working pressure- sensitive. Otherwiese contains NO_PRESS. o input_device UBYTE Shows the actually used input device (When in multimode shows the actual moved device). +-----+---------------------------------+ | Bit |Inputdevice when set | +-----+---------------------------------+ | 0 |Standard_Stylus | +-----+---------------------------------+ | 1 |Pressure Stylus (only SD tablets)| +-----+---------------------------------+ | 2 |Cursor | +-----+---------------------------------+ o Buttons UBYTE In dependency of the actual used input devices this field contains the number of the pressed button at that moment. When there is no button pressed this field contains 0. If running in multimode it always shows the state of the pen's buttons, because the cursor has his own field when in multimode. +------------------+-------------------------+ | input device |Button Value | +------------------+-------------------------+ | Standard Stylus |tip switch 1 | | |barrel switch 2 | | |both switches 3 | +------------------+-------------------------+ | Eraser |in proximity 4 | | |on the tablet 5 | +------------------+-------------------------+ | Crosshaircursor |top button 1 | | (4 Buttons) |left button 2 | | |bottom button 3 | | |right button 4 | +------------------+-------------------------+ | Crosshaircursor |one of those | +------------------+-------------------------+ o Tablett_Max_X ULONG o Tablett_Max_Y ULONG These fields are containing the maximum tabletresolution. But these values are depending on the selected working area. The selection and presentation is completly transparent. If you have selected a 6000 on 7000 points wide area for instance on a tablet with a physical resolution of 15420 points in both directions these fields are con- taining 6000 and 7000. If the working area is the whole tablet you will see here the physical tabletresolution. o Tablett_X long o Tablett_Y long Here you will see the actual position of the input device on the tablet. When in multimode you can find here the coordinates of the pen. The coordinates of the cursor are kept in own fields. The co- ordinates displayed here are in respect of the location and size of the selected working area. The origin is on the top left. o Set_Mouse UBYTE Shows which parts of the mouse will be emulated by the mouse. +-------+------------------------------+ | Value |Emulation | +-------+------------------------------+ | 0 |no mouseemulation | +-------+------------------------------+ | 1 |mousepointer and mousebuttons | +-------+------------------------------+ | 2 |only mousepointer | +-------+------------------------------+ Please remember, MB_Emu also depends upon this setting. o Commandset UBYTE Shows which commandset is used to communicate with the tablet. +-------+-----------------------------------------+ | Value |Commanset | +-------+-----------------------------------------+ | 0 |Wacom IV (not available with SD tablets) | +-------+-----------------------------------------+ | 1 |Wacom II-S | +-------+-----------------------------------------+ o Multi_Mode BOOL In multimode you can use two different input devices at the same time. Only available with Wacom IV commandset. When multimode is switched on this field contains TRUE. o Multi_Mouse UBYTE When mouseemulation and multimode are switched on you will see here the input device which is used as mouse. +-------+--------+ | Value |Mouse | +-------+--------+ | 0 |Pen | +-------+--------+ | 1 |Cursor | +-------+--------+ o Macrokey UBYTE UD series tablets are having so called macro buttons which can be used for custom functions. When Wacom IV is used you will see here the number of macro button which is actually pressed (if there is one pressed) otherwise these field will contain 0. o MM_Dig_Buttons UBYTE In multimode this field contains the currently pressed buttons on the cursor^15. o MM_Dig_X ULONG o MM_Dig_Y ULONG In multimode are the actual coordinates of the cursor stored inside here^16. o Proximity UBYTE Shows whether the inputdevice of the tablet is in proximity. You should only read data from this softwareinterface when this field contains 1. o MM_Dig_Proximity UBYTE The same as Proximity, but only for the digitizer in multimode. o Min_Pressure WORD o Max_Pressure WORD The minimum/maximum values for the pressure of the used tablet are stored here. o Tilt_X WORD o Tilt_Y WORD With newer tablets the tilt of the stylus is reflected here. The range of the tilt value goes from -64 to +63. The interactions and dependencies between the fields inside the WacomInfo structure can also be seen when you are running one of the Programms in the Develop Drawer parallel with the driver. ____________________________ ^15: also look at field Buttons. ^16: also look at the Tablet_X and Tablet_Y fields. A Wacom.h Here are the contents of "Wacom.h". /***********************************************************************/ /* WACOM Digitizerdriver (C) 1993-1996 by ROLAND SCHWINGEL */ /***********************************************************************/ /* Headerfile for receiving tabletdata from the driver */ /* Revision 2.0 */ /***********************************************************************/ /* DEFINES *******************************/ #define WACOM_PORT_NAME "Wacom DataPort" /* Name of the DataPort */ /* The NO_PRESS define is for compatibility reasons to older versions */ /* Use the Proximity field instead with driverversion 1.12 and up ! */ #define NO_PRESS -64; /* No valid Pressure */ /* Available Commands for sending to the driver */ #define WCMD_POLL_PASSIVE 0 /* Passive API Request */ #define WCMD_START_ACTIVE 1 /* Start active API */ #define WCMD_STOP_ACTIVE 2 /* Stop Message stream of active API */ #define WCMD_PAUSE_ACTIVE 3 /* Pause sending of active API */ #define WCMD_RESTART_ACTIVE 4 /* Resume sening after WCMD_PAUSE_ACTIVE */ /* the following defines can be found in the command field of WacomMSG */ /* when _RECEIVING_ a message from the driver! Do not set by hand ! */ /* Only valid with active API ! */ #define WCMD_ERROR 5 /* Something went wrong. */ /* Check Param field for informations */ #define WCMD_MSG 6 /* Also check Param field now! */ #define WCMD_OK 42 /* Everything went ok */ #define WCMD_DATA_TRANS 99 /* A Data Package from the driver. */ /* Do not set by hand ! */ /* Possible values for Param field */ #define WACFLG_ALLOWSCREENEVENTS 0 /* Allow Tabletevents for your screen */ /* Use only with WCMD_START_ACTIVE */ #define WACFLG_FORBIDSCREENEVENTS 1 /* No Eventposting for your screen */ /* Use only with WCMD_START_ACTIVE */ #define WACERR_REPLY_UNDERFLOW 2 /* To few Replymessages received ! */ #define WACERR_API_INSTALL 3 /* Error adding client to active API */ #define WACERR_API_UNINSTALL 4 /* Error removing client from active API */ #define WACERR_INVALID_COMMAND 5 /* Invalid command was sent to API */ #define WACMSG_DRIVER_DEACTIVE 6 /* Driver was deactivated */ #define WACMSG_DRIVER_ACTIVE 7 /* Driver was reactivated */ #define WACMSG_DRIVER_QUIT 8 /* Driver quits NOW ! */ /* Structures ****************************/ struct Wacom { UBYTE Sync; /* Synchronisation with subprocess */ /* (internal must be 0)*/ UBYTE Driver_running; /* Driver active or not */ /* 0 = inactive */ /* 1 = active */ UBYTE Wacom_Series; /* 0 = SD-Series */ /* 1 = UD/KT-Series */ UBYTE Beeper; /* State of the Beeper */ /* 0 = off */ /* 1 = on */ UBYTE Mode; /* Pressure or "normal" Mode */ /* 0 = normal */ /* 1 = pressure */ UBYTE MB_Emu; /* Mousebuttonemulation in Pressure Mode */ /* 0 = inactive */ /* 1 = active */ int Pressure_Limit; /* Limit for LMB-Emulation (-30 ... 30) */ WORD Pressure; /* current Pressure when in Pressure Mode */ /* WacomII-S: -30 ... 30 */ /* WacomIV: -60 ... 60 */ /* -128 ... 127 (Rom 1.2 and up) */ UBYTE input_device; /* Type of current Stylus/Digitzer */ /* 1 = standard Stylus */ /* 2 = pressure Stylus */ /* 4 = Digitizer */ UBYTE Buttons; /* State of the current input_device Buttons */ /* Standard Stylus: 1 = Frontbutton */ /* 2 = Sidebutton */ /* 3 = both */ /* Digitizer: 1 = middle Button top */ /* 2 = left Button */ /* 3 = middle Button bottom */ /* 4 = right Button */ ULONG Tablett_Max_X; /* Maximum X-Value on the Digitizer */ ULONG Tablett_Max_Y; /* Maximum Y-Value on the Digitizer */ long Tablett_X; /* current X-Coordinate */ /* when in WacomIV and Multimode: */ /* X-Coordinate of the pen */ long Tablett_Y; /* current Y-Coordinate */ /* when in WacomIV and Multimode: */ /* Y-Coordinate of the pen */ /* Additions: 10.02.1994 */ UBYTE Set_Mouse; /* Mouseemulation */ /* 0 = off */ /* 1 = Mousepointer and Buttons */ /* 2 = only Mousepointer */ UBYTE Commandset; /* Commandset actually used */ /* 0 = Wacom IV */ /* 1 = Wacom II-S */ UBYTE Multi_Mode; /* Multimode on/off (only Wacom IV) */ /* 0 = off */ /* 1 = on */ UBYTE Multi_Mouse; /* inputdevice used as mouse when in */ /* Multi_Mode (only WacomIV) */ /* 0 = pen */ /* 1 = Digitizer */ UBYTE Macrokey; /* pressed Macrobutton (only Wacom IV) */ UBYTE MM_Dig_Buttons; /* pressed cursorbuttons in Multimode */ /* (only Wacom IV) */ ULONG MM_Dig_X; /* X-Coordinate of the cursor in Multimode */ /* (only Wacom IV) */ ULONG MM_Dig_Y; /* Y-Coordinate of the cursor in Multimode */ /* (only Wacom IV) */ /* Additions: 20.03.1994 */ UBYTE Proximity; /* shows proximitiy of the pointing device */ /* 0 = not in proximity*/ /* 1 = in proximity */ UBYTE MM_Dig_Proximity;/* shows digitizers proximity in multimode */ /* 0 = not in proximity */ /* 1 = in proximity */ /* Additions: 27.12.1994 */ WORD Min_Pressure; /* Bottom limit of pressure */ WORD Max_Pressure; /* top limit of pressure */ /* Additions: 13.01.1996 */ WORD Tilt_X; /* Tilt of stylus on X axis -64 ... +63 */ WORD Tilt_Y; /* Tilt of stylus on Y axis -64 ... +63 */ /* These two are only valid when stylus is */ /* in use ! */ UBYTE reserved[104]; /* for future Expansions */ }; /* Message Structure for getting the above for use with PutMsg() */ struct WacomMSG { struct Message Mess; struct Wacom WacomInfo; ULONG Command; /* Command for API */ ULONG Param; /* Parameters for the API command */ struct Screen *AppScreen; /* The screen of the client Application */ UBYTE reserved[20]; /* For future Expansions */ }; B History These are the changes made to the driver in his history. Version 1.50 (14. February 1996) o UD/KT tablets with a rom version of 1.4 and above are having an extended commandset (Wacom Ive) and an extended data format. These tablets are also supporting pen tilt now. The driver supports these new features now, too. o Besides of the passive API there is now also an active one. Besides of this, the APIs are also extended now (eg. support pen tilt) o The tooltype INPUT_EVENT which was only accessible by the icon, can now also be accessed from within the GUI. o The AmigaOS API pressure is now normalized according to the Includes. o Adapted to the actual Wacom IV/IVe specification. o Reworked and extended Demo Applications for the APIs. o Some optimizations and structural changes. o New compiled with SAS/C V6.55. Version 1.17 (26. December 1994) o Modified priority of the API message port. o Corrected a little bug when opening the serial device. If the device couldn't be opended this was recognized and an error requester was opened, but afterwards the program continued like on success. This could have leaded to a crash in some rare cases. Sorry. Version 1.16 (07. November 1994) o Now also supports the new KT series. (eg. ArtPad) o UD tablets with a romversion 1.2 or greater can be driven with double resolution and double pressure range. This is also supported now. o The mainwindow now also has menus. o The cycle- and buttongadgets with keyboard access are highlited now when the corresponding key is pressed. o The layout of checkboxgadget has changed. When running AmigaOS3.0 or better they are looking much better with bigger fonts. o The requester which appears when the tablet is not switched on now has a retry-button for much easier reinitialising. o Revised tabletrecognition. It is now more flexible when some of the internal tabletsettings (DIP-switches or memory settings) are not set to factory settings. But please set your tablet to factory de- faults! o Revised SD-510C handling. There have been problems with a certain ROM-version of this tablet. Version 1.12 (07. May 1994) o Implementation of the Kickstart 3.0 tablethandling. Every Intuitionwindow can now receive pressure data directly from Intuition. This is only used when AmigaOS 3.0 or better is available in the system. o Adapted to the actual Wacom IV specification from april 1994. o simplified serial communication in order to improve compatibility to MultiIO cards that are having not the full commandset implemen- ted. o minor optimizations in the whole program. o exampleprogram with source included to show usage of the AmigaOS 3.0 tablethandling. o new compiled with SAS/C V6.51. Version 1.10 (21. February 1994): o direct and complete support of the Wacom IV commandset including ma- cro buttons, multimode and greater pressure range. o second window for defining the working area. o editable mouseemulation (includes switching off). o enabled scrolling of autoscroll screens. o multiselect with shift keys down is working now. o expanded softwareinterface. o optimized for lower cpu load. o complete second mouseemulation. Version 1.0 (12. October 1993): o Creation of the first version. C Trademarks Amiga(c), Kickstart(c), Workbench(c) are trademarks of Amiga Technologies respectively Commodore-Amiga, Inc. Wacom(c), Wacom II-S(c), Wacom IV(c) are trademarks of Wacom Co., Ltd.