Users Manual for the Wacom - Digitizerdriver for the Commodore Amiga Abstract The Program enables you to use a pressure sensitive digitizertablet from Wacom with your Commodore Amiga. The tablet can be used to- gether with the mouse (or without it) as direct_input medium. Therefore the driver can be used together with (nearly) every software. Furthermore the (pressuresensitive) data provided by the tablet can be exported in custom applications using a docu- mented softwareinterface. (c) 1993 Roland Schwingel 1 Introduction and legal stuff The Program enables you to use a pressure sensitive digitizertablet from Wacom with your Commodore Amiga. The amigamousepointer is con- trolled 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 a documented softwareinterface. 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 program Get_Pressure in the Develop drawer is not Shareware. It serves as an example for communicating with the driver in own applications. Get_Pressure and its source are Freeware. The software and all principles described here were developed strictly using the Commodore 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 WACOMII-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 DAMAGES 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 WacomII package may only be given away to another party in com- plete 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 remain completely intact when decrompessing. 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 should consider to become registrated. 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 together 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: roland.schwingel@rrzc1.rz.uni-regensburg.de 2 System requirements and Installation 2.1 System requirements If you want to use the WacomII 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 or Kickstart/WB3.x 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 new UD-Series 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 25KB), 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 together 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 locale/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 is supported in the directory of this document. It is an IFF-ILBM picture called "Wacom-SD.ilbm". The scheme shows a cable for Amiga500/2000. The cable must also be suitable for A3000/4000/600/2000. Only A100 Users have to modify the cable due to a different serial port connector. If you got an UD-tablet you have to use the delivered cable which also suits perfectly. (UD-series digitizers are having the power- strips inside the datacable.) 3 Usage and Configuration of the Driver The WacomII Driver is a so called Commodity. Commodities are linked in the input data stream of the Amiga and are sending/filtering Inputevents. The Driverporgram was developed for the WBStartup drawer of the WB (WB = Workbench). There it is started whenever the Work- bench 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 WacomII driver because it saves its settings on its own in the Tooltypes (look later chapters for more details). 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 double- click is performed to this appicon the configuration- window 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 status of the internal tabletbuzzer. 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 digitizer can be used for input. 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. 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. DEVICE (Default: serial.device) Here is the name of the systems devicedriver stored which is used to com- municate with the WacomII-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 the MultiIO board 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 the MultiIO board documentation) DONOTWAIT This tooltype is not used by the tabletdriver. It is used by the WB if you start from the WBStartup drawer. The WacomII driver sets this tooltype automatically. Once again I have to mention that you need_not_change the contents of the tooltypes manually. All settings can be made from the config- urationwindow. Your settings are saved here by the program auto- matically. 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 LMB_LIMIT=5 3.3 Controlling the mousepointer with the tablet With activated driver the mousepointer can be controlled either with the mouse or the tablet. The whole sensitive area of the tablet represents the area on your monitor which can be reached by the mouse. The top left edge corresponds 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 con- nected 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 mouse- button. pressure stylus: 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. digitizer: This device has four buttons. Two of these but- tons (the top button in the middle and the bot- tom button in the middle) are for free usage in own applications. The left and the right button are having the same functions like your mouse. 3.4 The Configurationwindow The configurationwindow will appear when at least one of these events occur: o When you start the program the tooltype CX_POPUP was set to yes. o The Commodities Exchange programm has sent an "appear" message to the driver. (Commodities Exchange is a part of your Workbench disk) 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. All driverfuntions can be accessed from keyboard too by hiting the corresponding underlined letter. 3.4.1 Info The type and the romversion of the tablet are displayed here when the driver was activated succesfully. 3.4.2 Commodity Preferences Here you can enter all commodity relevant data. Hotkey Using this stringadget you can enter the keycombination 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 key- expressions look into your Workbench Manual in the commodities chapter. Popup This cyclebutton determins whether the window should be opened or not upon program start. Pri Priority of the commodity. Normally the default value (0) needn't to 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 double- click 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 "Wacom II Driver: Popup" menuitem from the workbench's toolsmenu. 3.4.3 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 afer 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 afer the next initialization) Buzzer If activated the internal tablet buzzer sounds when a button on an input device is pressed. (A change of this setting will only be applied to the tablet afer the next initialization) Use Pressure-Pen If this gadget is selected the tablet is put to pressuresensitive mode during the next initialization. You have to use the so called pressure pen in this mode. Emulate LMB When selected a hit to the left mousebutton is emulated when a certain pressure is reached. 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) 3.4.4 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 the window. 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 removed and quited. 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 - Use Pressure-Pen o Until now it is not possible to cause a scrolling of autoscroll screens by direct use of the tablet. This will be possible in one of the future versions. 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 problem occurs because some tools are not expecting inputevents from a tablet. o Due to tolerances in the production of the pens some pressure pens could have a range between -35 and +35. o After accidently hitting of the resetknob on the back of the tablet, it must be reinitialized. 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 digitizer can disturb the reconfig- uration of the tablet. o UD-Series digitizers ar currently used in WacomII Mode. The special abilities of these tablets (like Mulitmode and Macro Buttons) are not supported right now. This is planed to become reality in a future version of the driver. o The "pressure stylus" and the "standard stylus" are combined in one pen by Wacom if you got an UD-series tablet. The buttons of the new 16-button-digitizer are connecte like this: Button 2 is LMB and Button 4 is RMB the others are for own applications. 5 How to get pressure 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 WacomII driver supports a comfort interface to custom applications for direct data export. The Amiga operating system offers only small support for pressure tablets. Therefore I had to find a way to support these (pressure) data to custom applications. The WacomII driver uses the Amiga mes- sageports for export. Due to the fact that the driver is setting the mouse you only have to take care for pressure data, even the softwareinterface offers much more than this. Upon start the driver creates a public messageport which is used for data export. The WacomII driver package contains a drawer named "Develop". There you can find the C-sourcode and the compiled version of program called "get_pressure" which uses the softwareinterface 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 "". (exec/exec.h is a part of your C develop- mentpackage). 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 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; } ... Now you can send the request for data to the WacomII 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. The WacomInfo structure (which is part of the WacomMSG structure) containes beside of the pressure much more data. For detailed documentation look into "Wacom.h". In the current version it is not possible to send commands to the WacomII driver using the messageport. This will propably be possible in a future version. Therefore the WacomInfo and the WacomMSG structure are containing some bytes wich are reserved for future use in order to preserve compatibility.