






                            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>". (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<<Our_Port->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.

