****************************************************************************
*                          -- WARNING --                                   *
* This document file (adi42.doc, v.001) is an ASCII image of the printed   *
* ADI 4.2 publication # 100750-01. The process of converting the document  *
* files to ASCII produced tables that can be confusing (they are generated *
* tab-delimited). If you find a table is difficult to understand, please   *
* refer to the same table in the printed documentation.                    *
****************************************************************************



    ********************************************************
    *                                                      *
    *                                                      *
    *                                                      *
    *                                                      *
    *                                                      *
    *             Autodesk Device Interface(TM)            *
    *              Driver Development ToolKit              *
    *                                                      *
    *                                                      *
    *                  Graphics Displays                   *
    *                  Rendering Devices                   *
    *                      Digitizers                      *
    *                       Plotters                       *
    *                   Printer/Plotters                   *
    *                                                      *
    *                                                      *
    *                                                      *
    *                      ADI 4.2                         *
    *                       v.001                          *
    *                                                      *
    *                                                      *
    *  Autodesk, Inc.                                      *
    *  --------------------------------------------------  *
    *  Publication 100750-01         September 10, 1992    *
    *                                                      *
    ********************************************************


$cb ***********************************************************************
* Copyright(C) 1990, 1991, 1992 Autodesk, Inc.        All Rights Reserved *
* ========================================================================*
* Permission to use, copy, modify, and distribute this software and its   *
* documentation for the purpose of creating device drivers or applications*
* for use in conjunction with Autodesk products, is hereby granted in     *
* accordance with the terms of the License Agreement accompanying this    *
* product.                                                                *
*                                                                         *
* AUTODESK, INC. MAKES NO WARRANTY, EITHER EXPRESSED OR IMPLIED, INCLUDING*
* BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS *
* FOR A PARTICULAR PURPOSE, REGARDING THESE MATERIALS AND MAKES SUCH      *
* MATERIALS AVAILABLE SOLELY ON AN "AS-IS" BASIS.                         *
*                                                                         *
* IN NO EVENT SHALL AUTODESK, INC. BE LIABLE TO ANYONE FOR SPECIAL,       *
* COLLATERAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES IN CONNECTION WITH OR  *
* ARISING OUT OF PURCHASE OR USE OF THESE MATERIALS. THE SOLE AND         *
* EXCLUSIVE LIABILITY TO AUTODESK, INC., REGARDLESS OF THE FORM OF ACTION,*
* SHALL NOT EXCEED THE PURCHASE PRICE OF THE MATERIALS DESCRIBED HEREIN.  *
*                                                                         *
* For conditions of use and permission to use these materials for         *
* publication in other than the English language, contact Autodesk, Inc.  *
*                                                                         *
* Autodesk, Inc. reserves the right to revise and improve its products as *
* it sees fit. This publication describes the state of this product at the*
* time of its publication, and may not reflect the product at all times in*
* the future.                                                             *
*                                                                         *
* Autodesk Trademarks                                                     *
* -------------------                                                     *
* The following trademarks are registered trademarks of Autodesk, Inc.:   *
* ADI, AME, ATC, Advanced Modeling Extension, Autodesk, Autodesk Animator,* 
* the Autodesk logo, AutoCAD, AutoCAD Training Center, AutoLISP,          *
* AutoShade, AutoSketch, AutoSolid, James Gleick's CHAOS: The Software,   *
* and 3D Studio.                                                          *
*                                                                         *
* The following are trademarks of Autodesk, Inc.: ACAD, Advanced User     *
* Interface, AME Link, Animator Pro, Animator Pro Player, Animation       *
* Player, ATLAST, AUI, AutoCAD Development System, AutoCAD Simulator,     *
* AutoCAD SQL Extension, AutoCAD SQL Interface, Autodesk Animator Clips,  *
* Autodesk Animator Theatre, Autodesk Device Interface, Autodesk          *
* Multimedia Training Center, Autodesk Software Developer's Kit, Autodesk *
* Training Center, AutoFlix, CA Lab, Cyberized, ContourView, cyberParts,  *
* DXF, FLI, HyperChem, MTC, Multimedia Explorer, SketchTools, SmartCursor,*
* Syntage, and World-Creating Toolkit.                                    *
*                                                                         *
* The following are service marks of Autodesk, Inc.: Autodesk Strategic   *
* Developer, Autodesk Strategic Developer logo, Autodesk Registered       *
* Developer, Autodesk Registered Developer logo, and TinkerTech.          *
*                                                                         *
* Third-Party Trademarks                                                  *
* ----------------------                                                  *
* RenderMan is a registered trademark of Pixar used by Autodesk under     *
* license from Pixar.                                                     *
*                                                                         *
* All other brand and product names are trademarks or registered          *
* trademarks of their respective holders.                                 *
*                                                                         *
* GOVERNMENT USE                                                          *
* --------------                                                          *
* Use, duplication, or disclosure by the U.S. Government is subject to    *
* restrictions as set forth in FAR 52.227-19 (Commercial Computer         *
* Software--Restricted Rights) and DFAR 252.227-7013(c)(1)(ii) (Rights in *
* Technical Data and Computer Software), as applicable.                   *
*                                                                         *
* Program Credits                                                         *
* ---------------                                                         *
* Some ADI drivers incorporate licensed, run-time versions of             *
* 386|DOS-Extender and 386|VMM from Phar Lap Software, Inc., Cambridge,   *
* Massachusetts.                                                          *
*                                                                         *
* SPARC Trademarks                                                        *
* ----------------                                                        *
* SPARCstation is a trademark of SPARC International, Inc., licensed      *
* exclusively to Sun Microsystems, Inc.                                   *
*                                                                         *
$ce ************************************************* adi v.005 7/29/92 ***



-*/                    |=======================|
                       |                       |
                       |   Table of Contents   |
                       |                       |
                       |=======================|


Chapter 1.................... line #760

1.1 ADI Driver Development ToolKit
1.2 Sample Source Code Media
  1.2.1 Filename Changes
  1.2.2 EOL Conventions
  1.2.3 ADI 4.2 ADIKITs Included
  1.2.4 Pre-4.2 ADIKITs Included
1.3 Developer's Responsibilities
1.4 Reporting Bugs
1.5 Contacting Autodesk
1.6 Locating ADI Documents
1.7 Manual Organization
1.8 Terminology
1.9 Typographical Conventions

Chapter 2.................... line #1181

2.1 Introduction
2.2 ToolKit Directory Organization
2.3 How to Build Sample Drivers
  2.3.1 UNIX Platforms
    2.3.1.1 SPARC Build Procedures
  2.3.2 Phar Lap DOS Extender
    2.3.2.1 Quick Start
    2.3.2.2 Tools and Environment Variables
    2.3.2.3 Makefiles
    2.3.2.4 Compiler Startup Code
    2.3.2.5 Floating-point Emulation
    2.3.2.6 MetaWare High C
    2.3.2.7 WATCOM Library Files
    2.3.2.8 WATCOM C 386 Version 7.0
    2.3.2.9 WATCOM C/386 Version 8.5
    2.3.2.10 WATCOM C/386 Version 9.0
    2.3.2.11 Environment Variables
    2.3.2.12 Path Length Warning
  2.3.3 Real-Mode DOS
  2.3.4 MAC ADI 4.1
    2.3.4.1 Build Environment
    2.3.4.2 Sample Drivers
    2.3.4.3 Driver Build Steps
  2.3.5 Windows ADI 4.1
    2.3.5.1 Required Tools
    2.3.5.2 Optional Tools
    2.3.5.3 Environment Variables
    2.3.5.4 Testing the Environment
2.4 Debugging P386 Drivers
  2.4.1 Symbol Table Loading
  2.4.2 Segment Selector Relocation
  2.4.3 AutoCAD Exception Handlers Offset Patch
  2.4.4 Debugging Using 386|VMM
  2.4.5 Debugging Level
2.5 High C malloc() Usage
2.6 Phar Lap 4.1 DOS Extender and Privilege Levels

Chapter 3.................... line #1876

3.1 Introduction
3.2 General Design
3.3 Packets
3.4 Dispatcher
3.5 Platform Overview
  3.5.1 Extended DOS (P386)
  3.5.2 UNIX
  3.5.3 Windows ADI 4.1
  3.5.4 Macintosh ADI 4.1
3.6 Transport Layers
  3.6.1 Real-modeDOS Transport Layer
  3.6.2 P386 ADI Transport Layer
  3.6.3 UNIX ADI Transport Layer
  3.6.4 OS/2 ADI 4.0 Transport Layer
  3.6.5 Windows ADI 4.1 Transport Layer
    3.6.5.1 Windows ADI 4.1 Display Drivers
    3.6.5.2 Transport Layer for Windows Digitizer and Plotter ADI
  3.6.6 MAC ADI 4.1 Transport Layer
    3.6.6.1 Driver Entry Points
3.7 Driver Selection
  3.7.1 AutoCAD Release 12
    3.7.1.1 ACADDRV Environment Variable
    3.7.1.2 Using Pre-ADI 4.2 Drivers with AutoCAD Release 12
    3.7.1.3 ADI Driver Validation
  3.7.2 Products Other Than AutoCAD Release 12
  3.7.3 Product ID, Serial Number, and Version number
  3.7.4 Driver Level Numbering Scheme
3.8 Driver Loading and Initial Invoke
  3.8.1 The edevent Structure
3.9 Establishing Communication
  3.9.1 P386
  3.9.2 UNIX
  3.9.1 acalls()
  3.9.2 P386 xxadicfg() and xxadixqt()
3.10 Driver Configuration
3.11 Driver Execution

Chapter 4.................... line #3327

4.1 Introduction
4.2 New or Improved Services
  4.2.1 Reentrancy
    4.2.1.1 Windows ADI 4.1 and (Transport Layer) Reentrance
  4.2.2 Ctype Functions
4.3 Dispatcher Functions
  4.3.1 adi_evalch
  4.3.2 adi_isalnum
  4.3.3 adi_isalnum_7bit
  4.3.4 adi_isalpha
  4.3.5 adi_isascii
  4.3.6 adi_iscntrl
  4.3.7 adi_isdigit
  4.3.8 adi_isgraph
  4.3.9 adi_islower
  4.3.10 adi_isprint
  4.3.11 adi_ispunct
  4.3.12 adi_isspace
  4.3.13 adi_isupper
  4.3.14 adi_isxdigit
  4.3.15 adi_rqctype
  4.3.16 adi_toascii
  4.3.17 adi_tolower
  4.3.18 adi_toupper
  4.3.19 cancel
  4.3.20 ciotype
  4.3.21 dispterm
  4.3.22 distpar
  4.3.23 errbeep
  4.3.24 getcdname
  4.3.25 getplrec
  4.3.26 getrec
  4.3.27 intpar
  4.3.28 intparl
  4.3.29 invrsp
  4.3.30 ior
  4.3.31 iorm
  4.3.32 iormrc
  4.3.33 iormt
  4.3.34 iow
  4.3.35 mgerr
  4.3.36 mgetch
  4.3.37 more
  4.3.38 mprintf
  4.3.39 mscani
  4.3.40 mscanr
  4.3.41 mscans
  4.3.42 msysint32
  4.3.43 nomore
  4.3.44 nultrm
  4.3.45 plflush
  4.3.46 plseek
  4.3.47 plsend
  4.3.48 pltell
  4.3.49 ppsend
  4.3.50 recfgport
  4.3.51 rhsend
  4.3.52 saveplrec
  4.3.53 saverec
  4.3.54 setpltmout
  4.3.55 usrbrk
  4.3.56 yorn
4.4 Obsolete Dispatcher File I/O Functions
  4.4.1 alert (obsolete)
  4.4.2 dlfname (obsolete)
  4.4.3 printfcd (obsolete)
  4.4.4 ffopenasc (obsolete)
  4.4.5 ffopenbin (obsolete)
  4.4.6 ffopendxb (obsolete)
  4.4.7 strcpycd (obsolete)
  4.4.8 getdat0 (obsolete)
  4.4.9 mfprintf (obsolete)
  4.4.10 mfclose (obsolete)
  4.4.11 mfwrite (obsolete)
  4.4.12 fncasetb (obsolete)
  4.4.13 funlink (obsolete)

Chapter 5.................... line #6558

5.1 Introduction
5.2 P386 ADS->ADI Link Transport Layer
  5.2.1 ADS Application Talking to an AutoCAD-Loaded Driver
  5.2.2 ADS Application Loads an ADI Driver Directly
5.3 UNIX display ADS->ADI Link Transport Layer
5.4 Overview of ADS->ADI Display Interaction
  5.4.1 Palette Maintenance
5.5 New ADS Requests
  5.5.1 ADS_ADIINFO
  5.5.2 ADS_ADISTART
  5.5.3 ADS_DSCFG and ADS_DSXQT
  5.5.4 ADS_ADIEND
  5.5.5 ADS_RECFGPORT
  5.5.6 ADS_DISPT
5.6 Third-Party Applications and AutoCAD Release 12

Chapter 6.................... line #7642

6.1 Introduction
  6.1.1 Display Driver Modes of Operation (Driver's Point of View)
  6.1.2 Display ADI History
6.2 From a Controlling Application's Point of View
  6.2.1 Preferred Packets
  6.2.2 Logical Versus Pixel Coordinates
  6.2.3 Packet Sequences
  6.2.4 Forming Packets (P386)
6.3 Required Features of an ADI 4.2 DEV_DS Driver
6.4 Interface Level
  6.4.1 New Display ADIPKTLEVEL Constants
  6.4.2 Which Interface Level do I Use?
  6.4.3 Pixel Aligned Text Mandatory
6.5 Display List (BS) Driver Issues
  6.5.1 31-bit Regen Space for Displays
  6.5.2 (Almost) Everything Logical
6.6 Optional Text Window on P386 Graphic Screen
6.7 Natural and Biased Coordinates
6.8 Screen Size
6.9 Tilemode and Multiple Viewports
6.10 Working with DESQview
6.11 Shell Command Notification
6.12 Developing and Testing Your Driver
6.13 Configuration
6.14 Packet Sequence
6.15 FASTDRAW (Fast Vector Mode)
  6.15.1 XOR Vectors
  6.15.2 Enabling FASTDRAW
  6.15.3 AutoCAD To Driver Communication
  6.15.4 Argument Determination (AutoCAD for Windows)
  6.15.5 Argument Determination (AutoCAD 386)
  6.15.6 Vectors Via PVEC And PLINE
  6.15.7 Calling Sequence
  6.15.8 Argument Descriptions
  6.15.9 Vector Coordinate Systems
  6.15.10 Register Values On Entry To FASTDRAW
  6.15.11 Example
6.16 ADI Display Packets
  6.16.1 Packets Used Only by AutoCAD
6.17 Display Packet Descriptions
  6.17.1 BPLINE
  6.17.2 PASHELL
  6.17.3 PBATCHVEC
  6.17.4 PBDRAG
  6.17.5 PBFILL
  6.17.6 PBIGBLIT
  6.17.7 PBIGVEC
  6.17.8 PBITBLT
  6.17.9 PBMARK
  6.17.10 PBOXCLR
  6.17.11 PBOXPOP
  6.17.12 PBOXPUSH
  6.17.13 PBSHELL
  6.17.14 PBVIEWPORT
  6.17.15 PCBMARK
  6.17.16 PCCURS
  6.17.17 PCFGREC
  6.17.18 PCHAR
  6.17.19 PCHGCFG
  6.17.20 PCLEAR
  6.17.21 PCLOSEVP
  6.17.22 PCLVP
  6.17.23 PCMARK
  6.17.24 PCOMMAND
  6.17.25 PCOORDLINE
  6.17.26 PDCURS
  6.17.27 PDHLITE
  6.17.28 PDIGTIZE
  6.17.29 PDIGTIZE_42
  6.17.30 PDINFO
  6.17.31 PDLFNAME
  6.17.32 PDLDIR
  6.17.33 PDOT
  6.17.34 PDRAG
  6.17.35 PECHAR
  6.17.36 PEVENT
  6.17.37 PFILL
  6.17.38 PFLUSHCHAR
  6.17.39 PGOGRAPH
  6.17.40 PGOTEXT
  6.17.41 PGOTEXTU
  6.17.42 PHLITE
  6.17.43 PINIT
  6.17.44 PKBZOOM
  6.17.45 PKILL
  6.17.46 PKZOOM
  6.17.47 PLANG
  6.17.48 PLINE
  6.17.49 PLOPEN
  6.17.50 PMARK
  6.17.51 PMAXVP
  6.17.52 PMNUCURS
  6.17.53 PMENUFCN
  6.17.54 PMENUGET
  6.17.55 PMENUSET
  6.17.56 PMENUSHOW
  6.17.57 PMODELINE
  6.17.58 PMODEMSG
  6.17.59 PMSGBOX
  6.17.60 PNEWCFG
  6.17.61 PNOP
  6.17.62 PNOTIFY
  6.17.63 POPENBVP
  6.17.64 POPENVP
  6.17.65 PPAL
  6.17.66 PQPLOT
  6.17.67 PRCMAP
  6.17.68 PREDRAW
  6.17.69 PREINIT
  6.17.70 PREVEC
  6.17.71 PROPENVP
  6.17.72 PROW
  6.17.73 PRPEN
  6.17.74 PRPEN_42
  6.17.75 PSHOWCFG
  6.17.76 PSTRING
  6.17.77 PSYNC
  6.17.78 PTABCFG
  6.17.79 PTABCFG_42
  6.17.80 PTERM
  6.17.81 PTEXT
  6.17.82 PTPROMPT
  6.17.83 PTXTCLR
  6.17.84 PTXTCHAR
  6.17.85 PTXTSHOW
  6.17.86 PVEC
  6.17.87 PVIEWPORT
  6.17.88 PVPAGE
  6.17.89 PWHO
  6.17.90 PWINRESTORE
  6.17.91 PWINSAVE
  6.17.92 PWRSPLIT
  6.17.93 PXPCOMD

Chapter 7.................... line #18790

7.1 Combined Rendering and Display (DEV_RC) Drivers
7.2 Multiple Display Modes
7.3 Fake Big-Screen Drivers
  7.3.1 Extended DEV_RC Specification
7.4 Required Features for Display Mode
7.5 Required Features for Full-Screen Rendering Mode
7.6 Required Features for Rendering in a Viewport
7.7 Typical Operation Scenarios
  7.7.1 Rendering in a Viewport
  7.7.2 Full-Screen Rendering
  7.7.3 Nondrawing Vectors to a Viewport
  7.7.4 Nondrawing Vectors to the Full Screen

Chapter 8.................... line #19152

8.1 Introduction
  8.1.1 Polygons Versus Scanline Data
  8.1.2 Continuous-Color Devices
  8.1.3 General Rendering Notes
  8.1.4 3D Rendering
8.2 Autodesk Products Capable of Rendering
4.2 DEV_RC driver by sharing it with AutoCAD, it uses of the ADS->ADI link
8.3 Configuration
  8.3.1 AutoShade Version 2 Logical Colors
  8.3.2 Scanline Output for Autodesk RenderMan
  8.3.3 TGA and TIFF Files
8.4 Rendering Hardcopy
  8.4.1 P386 Transport Layer
  8.4.2 UNIX Transport Layer
  8.4.3 I/O Port Management
8.5 Rendering Driver Packets
  8.5.1 Packets Added in ADI 4.2
  8.5.2 Packet Usage Tables
  8.5.3 Color Models
  8.5.4 Modes
  8.5.5 Coordinate System
8.6 2D Rendering Packets
  8.6.1 RDCLEAR
  8.6.2 RDCMAP
  8.6.3 RDCMAPB
  8.6.4 RDCMAPE
  8.6.5 RDCPOLY
  8.6.6 RDCRANGE
  8.6.7 RDEND
  8.6.8 RDETAIL
  8.6.9 RD_FGRAB
  8.6.10 RDFNAME
  8.6.11 RD_INFO
  8.6.12 RDINIT
  8.6.13 RDLANG
  8.6.14 RDPOLY
  8.6.15 RDRCMAP
  8.6.16 RDRHOPEN
  8.6.17 RDRSLINE
  8.6.18 RDSTART
  8.6.19 RDTERM
  8.6.20 RDWHO
  8.6.21 RDWSLINE
  8.6.22 RPCFGREC
  8.6.23 RPCHGCFG
  8.6.24 RPNEWCFG
  8.6.25 RPSHOWCFG
8.7 3D Rendering Interface
  8.7.1 Color Notes
  8.7.2 Rendering Styles Supported
  8.7.3 Typical 3D Operating Scenarios
    8.7.3.1 Cyberspace Scenario
    8.7.3.2 Scenario for AVE Render Running Single Screen
8.8 3D Rendering Packet Descriptions
  8.8.1 PVIEW
  8.8.2 PORTHO
  8.8.3 PPERSP
  8.8.4 POSEG
  8.8.5 PDSEG
  8.8.6 PCSEG
  8.8.7 PBPOLY3
  8.8.8 PPOLY3
  8.8.9 PNPOLY3
  8.8.10 PCPOLY3
  8.8.11 PVEC3
  8.8.12 PLIGHT
  8.8.13 PDLIGHT
  8.8.14 PSETCOLOR
  8.8.15 PSETMATL
  8.8.16 PMODEL
  8.8.17 PDRAWSEG
  8.8.18 P3D

Chapter 9.................... line #23953

9.1 Introduction
9.2 Historical Summary
9.3 New Features in ADI 4.2
  9.3.1 Mandatory Digitizer DRAGG Mode Support
  9.3.2 32-bit Digitizer Space
  9.3.3 3D and 6DF Digitizer Data
9.4 Modes of Digitizer Operation (Stream, Polled, and Interrupt)
  9.4.1 Sharing the Same Serial Port
  9.4.2 Relative Mode for ADI 4.2 Digitizers
  9.4.3 Mole Mode for Digitizers
9.5 ADI 4.2 Interface Level
9.6 ADI 4.2 Digitizer Driver Loading
9.7 Sample ADI Digitizer Drivers
9.8 ADI 4.2 P386 Digitizer Implementation
  9.8.1 Implementing P386 Interrupt Mode
  9.8.2 Implementing UNIX Interrupt Mode
9.9 ADI 4.0 OS/2 Digitizer Implementation
  9.9.1 OS/2 Mole Tablet Driver
    9.9.1.1 OS/2 Configuration Time
    9.9.1.2 OS/2 Incremental Mode
9.10 ADI 4.1 Windows Digitizer Implementation
  9.10.1 Interrupt Handling
  9.10.2 Windows ADI I/O Error Codes
9.11 UNIX Digitizer Implementation
  9.11.1 Linking and I/O
  9.11.2 Hardware Handshaking
  9.11.3 Digitizer Sharing
9.12 UNIX Digitizer Modes of Operation
  9.12.1 SCO UNIX ADI 4.1 Implementation
    9.12.1.1 SCO UNIX ADI 4.1 Digitizer Drivers
9.13 ADI Digitizer Test Procedures
9.15 Configuration-Time Packet Descriptions
  9.15.1 CINFO
  9.15.2 CINIT
  9.15.3 CURSOR
  9.15.4 DETAIL
  9.15.5 DETAIL_42
  9.15.6 MODEL
  9.15.7 NCONN
  9.15.8 PLANG
  9.15.9 PWHO
9.16 Execution-Time Packet Descriptions
  9.16.1 ACTIVATE
  9.16.2 ASHELL
  9.16.3 BSHELL
  9.16.4 DGSENSE
  9.16.5 DGSENSE_42
  9.16.6 DGTERM
  9.16.7 EINIT
  9.16.8 EINFO
  9.16.9 INFO
  9.16.10 MOUSEMODE
  9.16.11 PLANG
  9.16.12 PWHO

Chapter 10.................... line #26885

10.1 Introduction
  10.1.1 Historical Summary
    10.1.1.1 ADI 4.2 Changes
  10.1.2 Sample ADI Plotter Drivers
10.2 Modes of Plotter Driver Operation
10.3 Configuration
  10.3.1 Printer Plotters
10.4 General Concepts
  10.4.1 P386 ADI 4.2 Implementation
  10.4.2 UNIX ADI 4.2 Implementation
  10.4.3 OS/2 ADI 4.0 Implementation
  10.4.4 Windows ADI 4.1 Implementation
    10.4.4.1 Windows System Printer Driver
    10.4.4.2 Windows ADI I/O Error Handling
  10.4.5 ADI Plotter Test Procedures
10.5 Plotter Packet Usage
10.6 Plotter Configuration-Time Packets
10.7 Configuration-Time Packet Descriptions
  10.7.1 PWHO
  10.7.2 PLANG
  10.7.3 CINIT
  10.7.4 MODEL
  10.7.5 DETAIL
  10.7.6 COLORTSPEED
  10.7.7 COLORTLTYPE
  10.7.8 PLWIDS
  10.7.9 PLWIDS_42
  10.7.10 PLPENS
  10.7.11 CPREGENERIC
  10.7.12 GENERIC
  10.7.13 GENERIC_42
  10.7.14 ENDPLOT
10.8 Execution-Time Configuration Packet Descriptions
  10.8.1 PWHO
  10.8.2 PLANG
  10.8.3 EINIT
  10.8.4 SPECIFIC
  10.8.5 SPECIFICPENS
  10.8.6 SPECIFICSPEED
  10.8.7 SPECIFICLTYPE
  10.8.8 SPECIFICWIDS
  10.8.9 SPECIFIC_42
  10.8.10 EPRECONF
  10.8.11 EPRECONF_42
  10.8.12 ESHOW
  10.8.13 LEGEND
  10.8.14 ECHGCONF
  10.8.15 ECHGCONF_42
  10.8.16 PMGEN
  10.8.17 PMFILE
  10.8.18 PMDEVMODE
  10.8.19 GENERIC
  10.8.20 GENERIC_42
  10.8.21 PLOTSIZE
  10.8.22 EPOSTCONF
  10.8.23 ABORTPLOT
  10.8.24 DRAW
  10.8.25 ENDPLOT
  10.8.26 MOVE
  10.8.27 NEWLTYPE
  10.8.28 NEWPEN
  10.8.29 NEWSPEED
  10.8.30 NEWPENWID
  10.8.31 PENRAISE
  10.8.32 PLFILL
  10.8.33 PMFILE

Appendix A.................... line #30892

  A.1 Color Assignments
      A.1.1 256-Color Devices
      A.1.2 Generating RGB Values
  A.2 Logical Display Color Assignments
      A.2.1 Recommended Modifications
      A.2.2 16-Color Display Example
      A.2.3 256-Color Display Example
  A.3 256-Color Hardcopy Devices

Appendix B.................... line #31436

  B.1 ADI Historical Overview
  B.2 ADI Version 4.1 (November, 1990)
  B.3 ADI Version 4.0 (September 1988)
  B.4 Display ADI Version 3.1 (November 1987)
  B.5 Display ADI Version 3.0 (September 1987)
  B.6 Display ADI Version 2.1 (December 1986)
  B.7 ADI Display Version 2.0 (October 1986)

Appendix C.................... line #31557

  C.1 Graphic Display Environments
  C.2 AutoCAD
      C.2.1 Dual-Screen and Single-Screen Displays
      C.2.2 Menu and Dialogue Box Support
      C.2.3 AutoCAD Coordinate Systems
          C.2.3.1 Single-Screen and Dual-Screen AutoCAD Drivers
  C.3 AutoShade
      C.3.1 AutoShade Version 2 with Autodesk RenderMan
  C.4 Autodesk 3D Studio
      C.4.1 Module Requirements
      C.4.2 Partial ADI 4.2 Support

Appendix D.................... line #31932

  D.1 Extended DOS Information
  D.2 AutoCAD 386 Release 10
  D.3 AutoCAD 386 Release 11
      D.3.1 386|DOS-Extender 2.6
      D.3.2 386|DOS-Extender Upgrade from 2.6 to 3.0 and 4.0
  D.4 AutoCAD 386 Release 12
      D.4.1 Phar Lap 386|DOS-Extender
      D.4.2 386|DOS-Extender Switches
      D.4.3 386|DOS-Extender Switches
          D.4.3.1 386|DOS-Extender Compatibility
          D.4.3.2 Direct Extended Memory Allocation
          D.4.3.3 Address Line 20 Enabling
          D.4.3.4 RAM Disks and Disk Cache Programs
          D.4.3.5 386/387 Paging Errata Work-around
      D.4.4 Important Differences Between AutoCAD Release 11 and Release 12
  D.5 Debugging Information
  D.6 Running under Windows
  D.7 Summary of Differences Between Phar Lap 4.0 and 4.1
      D.7.1 Modified System Calls
          D.7.1.1 Memory Allocator Adjustments in 386|DOS-Extender 4.1
          D.7.1.2 INT 21h Func 2520h, Get Memory Statistics
  D.8 386|DOS-Extender Manual Changes
      D.8.1 Windows 3.x Support
      D.8.2 Interrupt Handlers Under Windows 3.x

Appendix E.................... line #32564

  E.1 Topics for Developers Under Nondisclosure
  E.2 ADI Development Historical Notes
      E.2.1 ADI Version 4.1 (November 1990)
          E.2.1.1 AutoCAD Release 11 Third Restricted Release (September 1990)
          E.2.1.2 AutoCAD Release 11 Second Restricted Release (July 1990)
          E.2.1.3 AutoShade 2.0 First Restricted Release (June, 1990)
          E.2.1.4 AutoCAD Release 11 First Restricted Release (May 1990)
  E.3 Known Bugs
      E.3.1 Cursor Alignment Problems With AutoCAD
      E.3.2 AutoCAD 386
      E.3.3 Autodesk 3D Studio Version 1.0
  E.4 ADI Questions and Answers
      E.4.1 March 1992 Developer Days Road Tour
  E.5 Resolved Bugs Since the Q021 Restricted Release
  E.6 Resolved Bugs Since the Q033 Restricted Release
  E.7 Frequent Errors in ADI 4.2 DEV_RC Drivers

/*+   


        |====================================|
        |                                    |
        |              Chapter 1             |
        |                                    |
        |   ADI Driver Development ToolKit   |
        |                                    |
        |====================================|



1.1 ADI Driver Development ToolKit
==================================

The Autodesk Device Interface (ADI) allows manufacturers, dealers, and
users to develop customized drivers for peripheral devices that will work
with AutoCAD, AutoShade, Autodesk 3D Studio, AutoSketch, and other Autodesk
products.

ADI is implemented across several operating systems and architectures.
Peripheral device categories supported through ADI are:

  * Displays

  * Plotters

  * Printers

  * Rendering devices

  * Digitizers and pointing devices

  * Video transport controllers

The ADI Driver Development ToolKit contains C and assembly language source
code, scripts, library files, sample installation guide text, and debugging
aids. The sample source code, or any portion thereof, can be used in your
ADI driver implementation without any royalties or additional fees paid to
Autodesk.

This release of ADI 4.2 supports 386 and SPARC. We discuss the other
platforms (e.g., Windows and Macintosh) in the context of ADI 4.1. Later
releases of the ADI 4.2 ToolKit will include ADI 4.2 code and documentation
for more platforms, as AutoCAD ships on each platform.


1.2 Sample Source Code Media
==============================

The CDROM that ships with this production release of ADI 4.2 contains
sample source code. It contains most previous ADIKITs for most platforms in
addition to the most recent ADI 4.2 release.

The old (pre-4.2) ToolKits are provided for developers who need to write
drivers for an early version of an Autodesk product. The best plan is to
write a driver which detects the revision level of the Autodesk product and
adapts to it dynamically. You will find the pre-4.2 ADIKITs a good source
of example code for use when an old product is detected, but of course your
driver will also need to respond with ADI 4.2 behavior to new products.

In some cases, e.g., ADI 4.1 for P386, there are several versions of the
ADIKIT, with different names (41phrlp, 41b386 and 41c386). In such cases,
use the latest version (e.g., 41c386) of the kit. It will contain the most
recent bugfixes. The earlier versions are included for historical interest.

Most of the directories on the CDROM also have readme.doc files which are
important. Please read these last-minute notes and warnings.

1.2.1 Filename Changes
======================

The ISO standard for CDROM files has forced us to rename some of our
ToolKit files. Files on CDROM are required to have a file extension
(minimally a period). They are not allowed to contain dashes (-). We have
appended a period to the file names which did not have extensions. This
affects all UNIX executable files and some UNIX make scripts. You can
either rename these files when you copy them to writable media, or you can
remember that the names have changed from those in our documentation.
Likewise, files whose names included dashes have been changed so that they
now include underlines. This affects many real-mode DOS make filenames.

1.2.2 EOL Conventions
=====================

The UNIX ADI ToolKit files are in UNIX EOL. The DOS ADI ToolKit files are
in DOS EOL. The Macintosh ADI ToolKit is in Macintosh EOL. Remember that
EOL conversion will damage binary files such as libraries, object, and
executable files.

1.2.3 ADI 4.2 ADIKITs Included
==============================

This initial release of ADI 4.2 is for P386 and SPARC. More ADI 4.2
platforms will be released later.

42_386            Initial P386 ADI 4.2 production release

42sparc           Initial SPARC ADI 4.2 production release

42bonus           Initial Bonus disk

adi42.doc         This document in ASCII

1.2.4 Pre-4.2 ADIKITs Included
==============================

ADI 3.0-3.1 was for AutoCAD Release 9

ADI 4.0 was for AutoCAD Release 10 and AutoShade v1.0

ADI 4.1 was for AutoCAD Release 11, AutoShade v2, and 3D Studio v1.0

Directory name Description
--------------------------
20adi             ADI 2.0 real-mode DOS ADIKIT

303adi            ADI 3.03 real-mode DOS ADIKIT

306adi            ADI 3.06 real-mode DOS ADIKIT update

30386i            ADI 3.0 Sun 386i ADIKIT

30apollo          ADI 3.0 Apollo ADIKIT

31dos             ADI 3.1 real-mode DOS ADIKIT

40dos             ADI 4.0 real-mode DOS ADIKIT

401dos            ADI 4.01 real-mode DOS ADIKIT update

40v386            ADI 4.0 P386 protected-mode ADIKIT

40os2             ADI 4.0 OS/2 digitizer and plotter ADIKIT

40sparc           ADI 4.0 SPARC ADIKIT

40386i            ADI 4.0 Sun 386I ADIKIT

40apollo          ADI 4.0 Apollo ADIKIT

40dec31           ADI 4.0 DEC 3100 ADIKIT

40sun3            ADI 4.0 Sun 3 ADIKIT

40xnx             ADI 4.0 for SCO XENIX

Note: one file, adi_display, had a eleven-character filename. This was
changed to adi_vga. to fit the 8-character ISO filename limit. Also note
that a period was appended, as with all names lacking extensions.

40adi.doc         ADI 4.0 ASCII ADI document

Use the files in the 41unix directory of the CDROM for Sun 3, Sun 386i,
SPARC and DECstation platforms. Use the 41bunix directory of the CDROM for
SGI IRIS, HP-UX, and the SCO UNIX platforms. Use the files from the 41c386
directory of the CDROM for P386 development.

The supporting sample code and libraries for the P386 ToolKit (in the
41c386 directory of the CDROM) includes WATCOM C/386 support files that fix
a serious bug in our WATCOM version 8.5 support code. The WATCOM support
files for the TEE and TESTKIT bonus programs (in the 41bbonus directory of
the CDROM) also include this bugfix. Support for WATCOM C/386 version 9.0
has also been added to the ToolKit.

The UNIX sample code includes support for Sun 3, Sun 386i, SPARC,
DECstation, SCO UNIX, SGI and HP. There are separate adikit.doc and
readme.doc files for each of these platforms.

41phrlp     ADI 4.1 P386 protected-mode ADIKIT

41rlmd      ADI 4.1 real-mode DOS ADIKIT

41bonus     ADI 4.1 Bonus disk (TEE and TESTKIT)

41unix      ADI 4.1 for SPARC, Sun 3, Sun 386i and DECstation

40vmsap     ADI "4.1" apollo and vms ADIKITs - unchanged since ADI 4.0

10anipro    First release of Animator Professional driver kit.

vtc10       First release of Multimedia Video Tape ADI.

41b386      ADI 4.1b P386 protected-mode ADIKIT update.

41bunix     ADI 4.1b for SCO UNIX, HP/UX and SGI.

            This is the last group of 3 UNIX platforms released for
            AutoCAD Release 11. See 41bunix\adikit.doc and 
            41bunix\readme.doc for more details on these platforms.

41mac       ADI 4.1 for Macintosh.

            This was the first release of a display ADIKIT for Macintosh. 
            It supports AutoCAD Release 11. See 41mac\macadi.doc,
            41mac\readme.doc and 41mac\adikit.doc for more details on this
            ADIKIT. Note that some filenames which contained a mixture of 
            upper and lowercase letters on the MAC were forced to uniform 
            lowercase for the CD distribution. The CDROM distribution of MAC 
            ADI does not include the executable files which are described in
            the documentation -- there were too many complications involved 
            in moving MAC executable files to and from a DOS CDROM.

41win       ADI 4.1 for Windows. This was the first release of an ADIKIT for
            AutoCAD for Windows. It includes digitizer, plotter and display
            ADI.

41brlmd     ADI 4.1 real-mode ADIKIT which contains a corrected DSTEST (the 
            r11.lsp file was corrupted in the earlier 4.1 release).

41bbonus    ADI 4.1b Bonus disk.

41c386      ADI 4.1c P386 ADIKIT update. Use this version for ADI 4.1
            development. It contains all of the bugfixes accumulated from
            earlier P386 4.1 ADIKITs.

41cbonus    ADI 4.1c Bonus disk. Use this for ADI 4.1 development.


1.3 Developer's Responsibilities
================================

ADI drivers that you develop are distributed and supported by your company,
not by Autodesk. It is your responsibility to inform users how to install
and configure the ADI driver and peripheral device, and to provide user
support. User calls concerning an ADI driver will be directed to your
support representative.

If you are a peripheral manufacturer and intend to market an ADI-based
product, your company should consider joining Autodesk's Registered ADI
Developer Program. To join the program send a written request for an
application to ADI Program, at the address listed below.

The importance of testing your finished ADI driver cannot be emphasized
enough. Testing is critical to the success of your driver, and thorough
testing can reduce the volume of user support calls generated by a
malfunctioning driver.

Distribution of your ADI driver is up to you. You may want to ship it on a
disk included with your product, or make it available to your dealers.

Autodesk will make every attempt to design future ADI enhancements that are
upwardly compatible so that your driver should continue to work with new
releases of Autodesk software products without any changes to your driver.
However, we cannot guarantee compatible operation in all cases and new
features that are added to the ADI specification may require that you
update your driver if you want to take advantage of them.


1.4 Reporting Bugs
==================

In the course of developing your driver, you may believe that you have
found a bug in one or more Autodesk products. Please try to reproduce the
problem with one of our sample drivers. If your driver uses an optional ADI
feature not exercised by our sample code, try to modify our sample driver
to make it behave in a manner similar to yours. If you can reproduce the
problem behavior with our sample code, you probably have found a bug and we
would like to hear about it. Please fill out an Autodesk bug report form
(found in the installation guide for each product), and mail or FAX it to
Autodesk.

If you report a bug, but don't tell us how to reproduce it with one of our
sample drivers, it is much less likely that the bug will be quickly
verified and fixed.


1.5 Contacting Autodesk
=======================

Autodesk does not offer technical assistance for ADI driver development
activities, and ADI ToolKit users are expected to have sufficient technical
skills to implement their drivers without assistance from Autodesk.

Autodesk maintains and publishes a list of hardware manufacturers and other
developers known to have completed ADI device drivers. This list is
distributed to dealers and registered members of the ADI Program. To be
included in this list, send a copy of your completed ADI driver on disk,
and all user documentation to:

ADI Program Autodesk, Inc.
2320 Marinship Way
Sausalito, CA 94965

Developers are invited to submit to Autodesk comments or "wishlist" items,
or exchange information regarding the ADI specification to Autodesk. You
can use the Autodesk Forum on CompuServe, or mail your comments to the ADI
Program. If a bug or deficiency is discovered in the ADI ToolKit,
developers will be notified via the Autodesk Forum on CompuServe. To enter
the CompuServe Autodesk Forum, type GO ADESK when you log onto CompuServe.


1.6 Locating ADI Documents
==========================

Documents common to most platforms are on the ADIKIT DOC disk. Most
platforms also have some platform-specific information in a file named
adikit.doc, in the /<platform> subdirectory of that platform's directory.
For example, information specific to SUN 4 (SPARC) systems is in the UNIX
ADIKIT disks, in the file /sparc/adikit.doc. The platform-specific document
for the Phar Lap extended DOS (P386) platform is the file
\pharlap\adikit.doc on one of the P386 ADIKIT disks.

The information in these platform-specific files includes listing the
contents of the ADIKIT for that platform.


1.7 Manual Organization
=======================

This manual describes the ADI 4.2 specification, and contains cross-
platform specification details. With the exception of implementation
information, most platform-specific information is provided in the ASCII
document file, adikit.doc, in the platform's directory in the ADI ToolKit.

The organization of this manual is a departure from the way ADI was
previously documented. We are attempting to improve the ease of use of the
ADI documentation, as well as reduce the volume. Still, ADI is a complex
specification, with many factors influencing driver development, including
the Autodesk host products, the development platform, the device type, and
the ADI version (and version compatibility).

Rather than documenting the changes from one version to the next, or
documenting the differences between platforms, we are placing as much
information as possible in one cross-platform document, with chapters
detailing the various device types or services. After the introductory and
general driver development material, the manual contains chapters covering
the dispatcher and device types. Each device type chapter contains packet
descriptions for all supported platforms, with application-side notes and
historical information whenever possible.

ADI documents are typically distributed in two formats: electronic and
printed. The electronic documents are in ASCII file format and therefore do
not contain any extraneous formatting. Documents in ASCII file format are
not indexed or paginated.

We keep the electronic and printed documents identical whenever possible.
However, electronic documents are typically updated more frequently. You
should always check the dates listed in the beginning of the documents you
are working with to assure that you are using the most recent
documentation.


1.8 Terminology
===============

The abbreviation "P386" refers to the extended DOS platform.

ADIKIT refers to the ADI Driver Development ToolKit.

We use the terms "primary application" and "secondary application"
throughout ADI documentation. Generally the application that loads and
configures the ADI driver is considered to be the primary application, and
an application that communicates with an ADI driver through the primary
application is considered to be the secondary application. For example,
under P386 the following application structure could exist:

$cb
  (DEV_DS ADI driver)--tee--(AutoCAD)---(ads app)
                        |                  |
               (other application) (DEV_RH ADI driver)
$ce
Figure 1-1. Possible P386 application structure

In this example, AutoCAD is the primary application to the DEV_DS ADI
driver, and the ADS application is a secondary application to the DEV_DS
ADI driver, but the primary application to the DEV_RH ADI driver. The
"other application," shown here hooked in through the TEE driver, would be
a secondary application.

An interesting twist on this occurs when AVE Render, as an ADS application,
configures a DEV_RC driver that AutoCAD has loaded for full screen
rendering. In this case, although AutoCAD loaded the driver, AVE Render
configures the full-screen-rendering part of the driver and hence is
primary application for the rendering operations.


1.9 Typographical Conventions
===============================

ADI documentation is released in both electronic and printed (book) form.
The electronic format documentation is in ASCII text file format. Following
are the conventions used in both the electronic and printed formats of ADI
documentation:

  * Case sensitivity and syntax similar to the C language are followed
where appropriate. Function names are followed by parentheses and symbolic
constants are listed as they appear in the source code.

  * Keyboard characters are enclosed in angle brackets, using industry
standard abbreviations. For example, the Control-C key combination is
written <Ctrl-C>.

  * Operating system pathnames are indicated with appropriate slash marks.

  * Filenames and commands are in lower-case except when case sensitivity
is important. UNIX commands are written in their proper case.

As described later in this document, ADI "packets" are made up of C
language structures. Structure members may be represented in the discussion
in one of several ways:

  * The member may be referred to in a "stand-alone" manner, where the
context of the discussion makes it clear what is being referred to.

  * The member may be separated from the packet name by a period,
indicating more clearly which packet is being discussed; for example,
PKTNAME.member.

  * Finally, the member may be identified by preceding it with the actual
structure name, rather than the packet name. For example, the packet
PKTNAME might consist of a structure named pkt_name. Thus, using the
example from above, pkt_name.member would refer to the same member as
PKTNAME.member.

Electronic documentation may have embedded delimiters for Autodesk internal
use. The delimiters are lines beginning with a $ character followed by a
short character string. These are designed to be as unobtrusive as possible
and should be ignored.




           |=====================================|
           |                                     |
           |             Chapter 2               |
           |                                     |
           |       ADI Driver Development        |
           |                                     |
           |=====================================|



2.1 Introduction
================

ADI drivers provide device-dependent services for Autodesk products. ADI
drivers are usually organized as packet processing machines. The Autodesk
product sends a packet (a data structure containing a request code and
often other request data) to the driver. The driver examines the request
code and performs the indicated operation, possibly in return requesting
some services from the Autodesk product; but eventually returning to a
quiescent state after it completes handling the packet request and
returning to AutoCAD.

Many ADI packets are optional and are identified as such in this document.
Optional packets may be ignored by drivers which are uninterested in them.
They exist to allow driver authors to implement various value-added
features to their drivers.

The details of how packets are transported, how and when drivers are loaded
are somewhat platform dependent and device-type dependent. You will find
these issues discussed for each device type and platform in later chapters.

The ADI ToolKit consists of the specification and a collection of example
drivers. Many of the example drivers are the same drivers shipped with
AutoCAD Release 12. You will find it helpful to examine the code in these
drivers.

The rest of this chapter discusses the general development environment and
requirements for developing ADI drivers. Basically, the two main
requirements are that your development tools (compiler, linker, etc.) and
your platform's environment variables are correctly established.


2.2 ToolKit Directory Organization
==================================

The ADI 4.1 ToolKit used a different directory organization than the one we
use for development at Autodesk. This caused some confusion and
complications, especially with makefiles. The ADI 4.2 ToolKit directory
organization is identical to the one we use at Autodesk, with a single
exception. In our environment we have two different include directories,
one for ADI include files and one for AutoCAD include files. In your
ToolKit these have been combined into a single \include directory.


2.3 How to Build Sample Drivers
===============================

2.3.1 UNIX Platforms
====================

ADI uses the operating system resident compiler on most supported UNIX
platforms. Refer to the platform-specific (adikit.doc) file for information
regarding environment variables and ADIKIT files.

On the SPARC platforms, we use the Sun C 1.1 development package. Using an
earlier development package will result in the library routine ceil() being
unresolved for some plotter drivers. This can be corrected by including the
math library (-lm) on the cc command line.

2.3.1.1 SPARC Build Procedures
------------------------------

The purpose of this section is to outline the procedures necessary to get a
sample driver built on the SPARC platform. This document endeavors to get
you building sample drivers with minimal impact on your existing
environment and minimal changes to the directory structure of the ADIKIT as
it is shipped to you. We have made the ADIKIT build environment essentially
identical to the environment we use internally at Autodesk (in contrast to
earlier ADIKIT distributions were it was different) - this should simplify
your use of our make files without modification.

Building a driver on the SPARC:

1) Set adikit environment variable to point to the root of your ADIKIT. 
   Assuming you have an ADIKIT mounted on /usr/bob/adikit, for the csh
   you would type:

     %setenv adikit "/usr/bob/adikit"

2) Set the machine environment variable to sun4.

3) Invoke the script file mkall42. This will build all of the sample
   drivers.

4) If you only wish to compile a single driver, invoke the dmake
   script in the driver's directory.

2.3.2 Phar Lap DOS Extender
===========================

Extended DOS (protected-mode) ADI drivers use the DOS extender bound into
Autodesk, the Phar Lap DOS-Extender. We modify the startup code for two 32-
bit compilers, MetaWare High C and WATCOM C/386. This startup code must be
linked to your ADI driver in order to establish communication with the host
product and provide dispatcher services. Therefore, you must use either
MetaWare High C 386 or WATCOM C/386 for ADI driver development, and you
must use the Phar Lap 386|ASM/LINK assembler for your assembly code
modules.

2.3.2.1 Quick Start
-------------------

If you are already familiar with the concepts and implementation of P386
ADI, then you can simply copy the ADI development stream to your
development environment, set your environment variables, and build the
sample drivers to test your environment. See the "Tools and Environment
Variables" section below for required variable settings and the assumptions
we use in our makefiles.

Because the ADIKIT development stream is now shipped matching our own ADI
development stream, there should be no modification of the sample makefiles
or directory structure as once was required with previous ADIKIT
distributions. You can build the sample drivers using either phar42.bat (in
the \pharlap directory), which builds all the P386 sample drivers, or using
the amake.bat file in the directory of the individual sample driver you
want to build.

2.3.2.2 Tools and Environment Variables
-----------------------------------------

The tools required to build each driver are:

  * MetaWare High C (hc386p) protected-mode C compiler (V1.5 - 1.71);
    optionally with Microsoft Make or Opus Make.

  * WATCOM C/386 (V7.0, V8.5 or V9.0); optionally with WATCOM WMAKE.

  * Phar Lap 386|DOS-EXTENDER.

  * Phar Lap 386|ASM/LINK assembler.

  * Phar Lap 386|DEBUG

  * Phar Lap 386|VMM (optional).

Note: "fastlink" was renamed 386linkp for our sample drivers. This was done
so that both the Phar Lap assembler and linker have names which clearly
identify them as 386-specific. 386|VMM is recommended for debugging if you
have less than about 6 MB RAM or if your driver uses the malloc() function.

Naturally, our make files assume that you have placed these tools on your
DOS path (the Phar Lap tools and either WATCOM with Wmake or MetaWare with
Opus Make).

We have sometimes experienced a problem with the Phar Lap assembler failing
in various odd ways when trying to assemble the ASM files located in
\common. If you have problems with these files, copy them from \common into
the driver's directory.

See appendix D for a history of the various Phar Lap DOS extender versions
used with AutoCAD 386 Release 10, 11 and 12. There are significant
differences between the various Phar Lap versions. We used version 2.2d of
these tools for AutoCAD 386 Release 10 development and we are using version
4.1 of the Phar Lap tools for AutoCAD 386 Release 12 development.

Note that our internal development is still done with MetaWare, so our
WATCOM support has not been nearly as well exercised as our MetaWare
support. We used version 1.5 of MetaWare High C 386 for release 10 and
release 11 development, and we are using version 1.71 for AutoCAD Release
12 development.

2.3.2.3 Makefiles
-----------------

We provide makefiles for Opus Make, Microsoft Make, and WATCOM Make. You
may, of course, create your own makefiles with whatever tool you choose.

Most of the makefiles provided in this release assume the following tools:
MetaWare High C 386 v1.7, Opus Make, and version 4.1 of all the Phar Lap
tools listed above.

We have placed a batch file, phar42.bat, in the \pharlap directory which
will build all of the drivers in the kit for you.

2.3.2.4 Compiler Startup Code
-----------------------------

The ADI ToolKit includes two versions of the startup code for each of the
supported compilers, for either math coprocessor support or floating-point
emulation. These .lib files must be linked with your driver as the FIRST
library in the link command line. There must not be a -lib command to the
left of it. Examine the sample make files to see examples of this.

When we modify a C compiler's startup code, several things are done: we add
our own main() which initializes data structures, negotiates dispatcher
revision levels, and calls your driver's acalls(). We also link in the
dispatcher service library. We modify the compiler's exit() handler to
return to AutoCAD in most cases, to allow AutoCAD to save the user's
drawing in the event of an error.

Autodesk 3D Studio allows users to have either an Intel or a Weitek math
coprocessor, both present, or neither. Thus, if you wish your driver to
work with 3D Studio, on all supported system configurations, you should not
assume the presence of either math chip.

2.3.2.5 Floating-point Emulation
--------------------------------

Our sample drivers are compiled to use floating-point emulation. To link in
math coprocessor support, you should modify the driver's makefile as
follows:

When compiling, define ADIEM for emulation, and do not define it for math
coprocessor support. For example, the following line from a makefile calls
the High C compiler with emulation turned on:

-@hc386p $< $(CFLAGS) -def ADIEM -re -noansi -pr \
    padi.pro -ob $(OBJ)\$* >& $*.err

Removing the "-def ADIEM" would cause math coprocessor support code to be
generated. You then must make sure the correct library is linked (they are
listed below). For example, linking in p386lib.lib for coprocessor support
versus p386elib.lib for floating-point emulation.

2.3.2.6 MetaWare High C
-----------------------

Library files:

p386lib.lib (MetaWare High C, math coprocessor)

p386elib.lib (MetaWare High C, emulation)

The libraries supplied for High C use startup code from v1.62. They will
work with versions of High C from 1.5 up to and including 1.71.

If you use MetaWare High C 386 v1.73, you will have to use MetaWare's
FIXLIB utility on our libraries.

2.3.2.7 WATCOM Library Files
----------------------------

WATCOM C version 8.5 and 9.0 puts the math coprocessor into a state which
compromises the numerical accuracy of AutoCAD. Earlier versions of our
libraries for WATCOM versions 8.5 and 9.0 were shipped that did not account
for this. Our library code and xxface.asm files have been modified to save
the floating-point environment on entry to the ADI driver and restore it on
return to the calling product, when WATCOM C/386 is used.

AutoCAD doesn't save the state of the coprocessor before calling a program
of unknown compilation (i.e., an ADI driver). It is the driver's
responsibility to control the state of the coprocessor chip. You should use
our library files dated after June 4, 1992.

2.3.2.8 WATCOM C 386 Version 7.0
--------------------------------

Library files:

wc386lib.lib (math coprocessor)

w386elib.lib (emulation)

Note: WATCOM C/386 Version 7.0 does not run in protected mode and requires
all the conventional memory that you can spare. If there is not enough
conventional memory available, the compiler will not be able to optimize
some of the procedures. (Version 8.5 and newer versions can run in
protected mode.)

2.3.2.9 WATCOM C/386 Version 8.5
--------------------------------

In order to use WATCOM C/386 Version 8.5 for ADI 4.2 drivers, you must use
the provided startup modules for WATCOM v8.5. These modules are provided in
the \pharlap\wcobj directory of the ADIKIT.

For Intel 80387 coprocessor support, the modules are:

w85.lib

adif85.obj

For emulated floating point routines, the modules are:

w85e.lib

adie85.obj

w85.lib and w85e.lib are ADI driver libraries. adif85.obj and adie85.obj
are the WATCOM compiler startup modules for ADI drivers.

To see an example of how these modules are linked to create an ADI 4.2
driver, examine the makefile makedgms.w85 in the sample Microsoft Mouse
driver (\adikit\pharlap\dgpms).

For information on using WATCOM 8.5 with the Bonus Disk material, see the
readme files on the Bonus Disk.

2.3.2.10 WATCOM C/386 Version 9.0
---------------------------------

Use of WATCOM C/386 Version 9.0 for ADI 4.2 drivers is essentially
identical to the use of WATCOM v8.5 as described above, except that you
must use the following files, provided in this ADIKIT:

For Intel 80387 coprocessor support, the modules are:

w90.lib

adif90.obj

For emulated floating point routines, the modules are:

w90e.lib

adie90.obj

w90.lib and w90e.lib are ADI driver libraries. adif90.obj and adie90.obj
are the WATCOM compiler startup modules for ADI drivers.

2.3.2.11 Environment Variables
------------------------------

The following environment variables must be set:

ADIKIT            Points to the root directory of the ADI 4.2 kit on your
                  hard drive. Use a trailing backslash.

ACINC             Points to the ADIKIT \include directory. Do not use a
                  trailing backslash.

HIGHC             Points to the High C 386 compiler's root directory. Use a
trailing backslash.

IPATH             Points to the High C 386 compiler's include directory
followed by the adikit \include directory. Use trailing backslashes.

WATCOM            Points to the WATCOM C 386 compiler's root directory.

386INC            Points to the WATCOM C 386 compiler's include files.

386LIB            Points to the WATCOM C 386 library files.

HIGHC is required only if you are using the High C compiler. WATCOM,
386INC, and 386LIB are required only if you are using WATCOM C 386. Here is
an example of environment variable settings used for MetaWare:

set acinc=e:\a\include\
set adikit=d:\a
set highc=e:\q\hc386\
set IPATH=e:\q\hc386\inc\;d:\a\include\

2.3.2.12 Path Length Warning
----------------------------

The make files supplied in this ADIKIT come very close to exceeding the DOS
command line length limit. To avoid problems with this, it is important to
load the ADIKIT so that the path to the root of the kit is very short,
preferably only one or two characters long (e.g., f:\a\).

2.3.3 Real-Mode DOS
===================

Autodesk has no plans to extend real-mode ADI for ADI 4.2. Even though it
is possible to use an older real-mode ADI driver with Autodesk products
that previously had that capability, it is strongly suggested that any DOS
ADI driver development be done in extended DOS. For example, it is
impossible to write a real-mode ADI driver that supports all of the AutoCAD
Release 12 features, for any device type.

You will find documents and sample drivers for real-mode ADI 4.1 on the
ADIKIT CDROM in the 41brlmd directory. Refer to adi41.doc for information
on real-mode driver development.

2.3.4 MAC ADI 4.1
=================

MAC ADI drivers may be built with any Macintosh development environment
(e.g., MPW, Think C, Think Pascal) which will build stand-alone code
resources. It is possible to use languages other than C as long as they
accommodate the C calling convention used by AutoCAD.

MAC ADI driver development is helped by running with a MAC debugger which
supports debugging of stand-alone code resources. AutoCAD has been verified
to run under SADE, Macsbug, TMON, and Jasik's Debugger, all of which
provide some support for stand-alone code resources. Check with the
manufacturer of your debugger to see whether it supports source debugging
of stand alone code resources.

2.3.4.1 Build Environment
-------------------------

There are several environment variables that you need set for the makefiles
to work properly. These environment variables are case sensitive.

ADI               The directory of the driver you are building.

ADIMac            The directory where your driver object modules will
reside (our makefiles use the directory pointed to by the ADI environment
variable).

Mac               The directory where the AutoCAD executable resides.

For example, assuming your build environment resides on the internal hard
drive called "Macintosh HD," and the ADI drivers are in a subfolder called
"adi," and your AutoCAD executables are in a subfolder called "acad," the
following commands would set the required environment variables:

set ADI "Macintosh HD:adi:dspmac41:"
export ADI
set ADIMac "{ADI}"
export ADIMac
set Mac "Macintosh HD:acad:"
export Mac

2.3.4.2 Sample Drivers
------------------------

There are two sample display drivers supplied with MAC ADI kit 4.1; a
display list driver, and a non-display list driver. We refer to the non-
display list driver simply as the "display driver" in our MAC ADI
documents.

They are written to be built using the MPW 3.2 development environment, but
a developer should find it fairly easy to convert this code to Think C or a
different version of MPW. Autodesk does not supply any special libraries to
link with MAC ADI drivers.

The sample display list driver (dspmac41) was developed from the P386
sample display list driver (dspega41). These are non-production quality
display list drivers (MAC and P386). They were developed to test display
list packets sent and received by AutoCAD and the ADI driver. Your display
list driver should use more intelligent display list handling than our
sample drivers.

The sample ADI non-display list driver (macadi) is similar to the internal
display driver that is shipped with AutoCAD for Macintosh Release 11. This
driver implements the small cross hair cursor that the internal display
driver does not.

2.3.4.3 Driver Build Steps
--------------------------

After setting up an MPW 3.2 ADI build environment, the steps to build the
sample drivers are:

1)  Copy the contents of the MAC ADI ToolKit disk onto your
    development machine.

2)  Launch MPW.

3)  Change your current working directory in MPW to either dspmac41
    or macadi (the directory of the driver you are building).

4)  Open the file envir.set, modify the pathnames to conform to your
    environment, copy it to your WorkSheet, and execute it (highlight
    the text, then press enter).

5)  Modify the COptions flag in makeadi.mpw to point to your ADI
    include directory.

6)  Type "buildadi.mpw" into the MPW Worksheet on a line by itself,
and press the enter key (not return). This will invoke an MPW script which
builds the sample driver with full Macsbug and symbolic debugger symbols,
as well as a map file.

Note: If you don't set "Mac" to the directory that the AutoCAD executable
resides in you'll get error messages when trying to duplicate the driver,
but this is not fatal.

2.3.5 Windows ADI 4.1
=====================

Because Windows ADI drivers are Windows Dynamic Link Libraries (DLLs), the
programming environment for a Windows ADI driver is the same as for any
Windows development environment. Currently, ADI supports only the Microsoft
tools listed below, because the object modules that are supplied with the
ADI ToolKit (which must be linked to the ADI driver DLL) are created using
Microsoft C (adidisp.obj, libentry.obj, and mindll.obj).

2.3.5.1 Required Tools
----------------------

  * Microsoft C Optimizing Compiler, Version 6.00AX or newer.

  * Microsoft Segmented Executable Linker, Version 5.10 or newer.

  * MASM, Version 5.00A or newer.

2.3.5.2 Optional Tools
----------------------

  * OPUS Make utility. You can use other make utilities, but you might have
    to modify the makefiles.

2.3.5.3 Environment Variables
-----------------------------

The makefiles provided with this kit require that you set the following
environment variables:

P386              Set to WIN.

ACINC             Set to the include directory of the ADI ToolKit.

ACEXE             Set to the directory where the ADI executables should be
placed.

ACOBJ    Set to the directory where the ADI object modules should be placed.

ACDRV    Set to the current directory (".").

LIB      Set to the Microsoft C library directories.

INCLUDE  Set to the Microsoft C include directories.

CL       Compiler options.

PATH     Make sure your MSC binaries and make utility are on your path.


The following batch file commands would set the environment variables
listed above, assuming that the ADIKIT has been loaded in c:\adikit; the
Microsoft compiler, linker, and assembler are located in either c:\msc\bin
or c:\msc\binb; and Opus Make is located in c:\opus.

SET P386=WIN
SET ACINC=C:\ADIKIT\INCLUDE
SET ACEXE=C:\ADIKIT\BIN
SET ACOBJ=C:\ADIKIT\OBJ
SET ACDRV=.
SET LIB=C:\MSC\WLIB;C:\MSC\LIB
SET INCLUDE=C:\MSC\WINC;C:\MSC\INCLUDE
SET CL=-c -EM -AL -Zp -G2s -FPi87
SET PATH=C:\MSC\BIN;C:\MSC\BINB;C:\OPUS;%PATH%

2.3.5.4 Testing the Environment
-------------------------------

You can test your development environment by building the sample drivers
provided with the ADIKIT. Building a sample driver has three steps:

1)  Copy the ADIKIT to your development environment, retaining the
    directory and file structure that the kit is shipped with.

2)  Set the environment variables (listed above).

3)  Change directory to the driver you want to build (so the driver's
    directory is the system's current directory) and execute the amake.bat
    file.

The sample display driver is in the \ds\win directory. Sample plotter
drivers are each in a subdirectory under the \pl directory; sample
digitizer drivers are each in a subdirectory under the \dg directory.


2.4 Debugging P386 Drivers
===========================

We use Phar Lap 386|DEBUG for most of our ADI debugging. Thus, most of the
following discussion assumes you are using 386|DEBUG. However, you will
find some useful information about MetaWare MBD and WATCOM WVIDEO in
appendix D.

You should refer to the Phar Lap documentation for a full discussion on
debugging your P386 ADI driver. Following are some brief hints to help.

2.4.1 Symbol Table Loading
==========================

Phar Lap 386|DEBUG has a command line switch which causes the debugger to
load its symbol table out of a different .exp file. The switch is -symfile
and it takes a single argument which is the name of a non-bound .exp file
which has a symbol table at the end of it. The following command line would
load the executable file acad.exe with the symbol table from foo.exp:

386debug -symfile foo.exp acad.exe

You must set the environment variable EXPDEBUG to PADI, and you must reset
the debugger's segment selectors before your driver's symbol table will be
usable.

2.4.2 Segment Selector Relocation
=================================

The XR command relocates the segment selector values of symbols which
appear in the symbol table. The syntax is: XR <oldsel> <newsel>. For
example, these commands would relocate the code and data selectors to 6c
and 64, respectively:

XR c 6c
XR 14 64

You can use the XS command to see the current segment selector values which
are used for code and data symbols.

After the code gets loaded, if the environment variable EXPDEBUG is set to
PADI, then debugger() will be called from within acalls() in module padi.c.
The debugger() routine consists simply of an INT 3 and RET. It stops the
execution of AutoCAD in the debugger just prior to setting up a packet
buffer and making a call to the protected-mode ADI driver's C runtime
initialization code.

To get past the INT 3, do a "R EIP EIP+1" command. The code and data
selector for the ADI driver will be printed out and can be used with the
following commands in order to execute into the ADI driver and break at the
ADI symbol:

XR <AutoCAD's code selector = c> <ADI's code selector>
XR <AutoCAD's data selector = 14> <ADI's data selector>
G <ADI's code selector>:<ADI symbol>

Once you are inside the driver you don't need to prepend the break point
with the ADI selector.

If your driver is not the first ADI driver to load, you will need to issue
these commands to get past the first breakpoint and then follow the
procedure outlined above at the second breakpoint:

R EIP EIP+1    ( get past breakpoint )
G              ( continue execution )

2.4.3 AutoCAD Exception Handlers Offset Patch
=============================================

You can patch acad.exe to prevent AutoCAD from installing certain exception
handlers to help in your debugging. You should change the 2 bytes at 2a30
to 90 90, and the 1 byte at 2956 to c3. This will prevent acad.exe from
installing handlers for the following exceptions: bounds checking, invalid
opcode, stack exception, general protection exception, and alternate page
fault handler (i.e., invalid memory references).

The following shows the commands to do this patch using the dxdebug
debugger:

dxdebug acad.exe
-e 2a30 90 90
-e 2956 c3
2.4.4 Debugging Using 386|VMM
=============================

If your driver uses the malloc() function or if you have fewer than 8 MB of
memory, you will probably need to load 386|VMM when you load 386|DEBUG.
Running under the debugger disables the copy of 386|VMM which is bound with
AutoCAD. The use of malloc() in your driver can lead to erratic behavior if
386|VMM is not loaded.

The 386|DEBUG -vm vmmdrv switch loads 386|VMM. For example:

386debug -vm vmmdrv -symfile foo.exp acad.exp

2.4.5 Debugging Level
=====================

The debugger level is established by setting the DOSX environment variable
to DEBUG y, where y is a number from 1 to 5, with 5 being the most verbose.
Refer to the 386|DEBUG documentation for descriptions of the debugger level
settings.

Note that 386|DEBUG supports the use of a serial terminal for debugging.
This is very helpful when debugging display and digitizer drivers.


2.5 High C malloc() Usage
==========================

If you are using High C and you implement FASTDRAW, using malloc() from
your FASTDRAW assembly code will not work unless you set up a local stack
in your data segment. You must do this so that you can make registers SS,
DS, and ES all equal to the local data segment. The High C malloc()
function assumes these registers are equal and they are normally not equal
upon entry to FASTDRAW. We have not used the malloc() function in our
sample FASTDRAW code; this advice is being passed on from other developers.


2.6 Phar Lap 4.1 DOS Extender and Privilege Levels
==================================================

AutoCAD 386 Release 12 is bound with a modified Phar Lap 4.1 DOS Extender.
Unlike earlier versions of AutoCAD 386, it is shipped to run unprivileged
by default. This makes it possible for AutoCAD 386 to run as a full-screen
DOS application under Windows 3.1 (sometimes). The major consequence for
ADI drivers is the need to adapt dynamically to the privilege level AutoCAD
is running at, modifying the base value of any hard-wired segment selectors
by ORing in the low 2 bits of AutoCAD's DS or CS. See appendix D for a much
more detailed discussion of Phar Lap DOS extender issues.

Also note that when debugging, you will have to make all of the programs
involved in your debugging session run at the same privilege level. Thus,
you will have to either make AutoCAD privileged or make the debugger
unprivileged. You can do this with cfig386.





                    |================================|
                    |                                |
                    |           Chapter 3            |
                    |                                |
                    |       ADI Implementation       |
                    |                                |
                    |================================|




3.1 Introduction
================

This chapter discusses the implementation methods used in ADI. We have
attempted to maintain consistency in the implementation of ADI across the
various supported platforms, despite the architectural differences in many
of them. Information regarding ADI history and working with known bugs are
located in the appendices of this document.

Following is an overview of the implementation design, followed by specific
design issues, such as loading the ADI driver and driver initialization.


3.2 General Design
==================

The ADI driver forms a link in the chain of communication between the
Autodesk product and the peripheral device. Simply put, the Autodesk "host"
product sends "task" requests to the ADI driver for the supported device.
For example, the host product could ask an ADI plotter driver for some
information or ask the ADI plotter driver to have the device draw a vector.
The ADI driver can also request some services from the Autodesk host
product as well, through our dispatcher services library. It is very
important for drivers to use dispatcher services for configuration. This
allows AutoCAD scripts and standard AutoCAD <Ctrl-C> and error handling to
work.

Your driver communicates with the Autodesk host product by following the
ADI specifications established by Autodesk. Developing your ADI driver
under this standard allows for compatibility with various Autodesk products
as well as allowing your driver to utilize various services provided by the
Autodesk host product.
$cb

 |==================|     |============|     |===================|
 |                  |     |            |     |                   |
 | Autodesk product |<--->| ADI driver |<--->| Peripheral device |
 |                  |     |            |     |                   |
 |==================|     |============|     |===================|

$ce
Figure 3-1. ADI driver chain of communication


3.3 Packets
===========

Once the Autodesk product has located and loaded your ADI driver, a method
of communication called "packet mode" is established between the
controlling product and your driver. Packets are sent back and forth
between the Autodesk host product and the ADI driver using protocols
established for the platform's ADI transport layer. A packet, as used in
the ADI specification, is a predefined data structure (usually a struct in
the C language).

ADI drivers are normally written in C, and usually contain a huge switch
statement (switching on the packet code) with a case for each packet which
the driver handles. Most drivers ignore some or all of the many optional
packets by allowing them to be handled by a do-nothing default case in this
switch statement. Drivers must provide handlers for the packets which are
not specified as optional.

Some packets are one-way, i.e., the controlling application doesn't examine
the return packet. On some platforms, one way packets aren't even returned
to the Autodesk product (e.g., UNIX). Some packets are round-trip; the ADI
driver modifies one or more packet members, and the controlling application
uses this information.


3.4 Dispatcher
==============

The dispatcher allows an ADI driver to request services from the host
product. In general, the host product calls your driver when it needs
something such as a digitizer sample, display update information, or the
user requested a plot, and so forth. Some services, such as having the host
product perform some types of error handling or user dialogs, are requested
by the driver through the dispatcher. Dispatcher services (or functions)
are invoked simply by calling the particular function from the dispatcher
library that is linked to your driver. Refer to chapter 4, The Dispatcher
Library, for a complete discussion of these services.


3.5 Platform Overview
=====================

3.5.1 Extended DOS (P386)
=========================

P386 ADI drivers are compiled as stand-alone .exp programs. The operating
system does not directly load or execute P386 ADI drivers. ADI drivers are
loaded by the Autodesk host program. P386 ADI drivers run in native 32-bit
mode, and the DOS extender handles memory and paging requirements (the
driver remains in protected mode unless a real mode interrupt is
generated).

There is a very important distinction that must be made between executing
your protected-mode ADI driver as a completely distinct stand-alone program
(having the operating system load the program) and your driver being loaded
by the Autodesk host program's driver loader. Generally, it is impossible
for P386 ADI drivers to run as stand-alone programs -- they do not contain
the DOS extender which is bound into AutoCAD and they are not designed to
run in isolation.

Although both the host product and your driver run in protected mode,
allowing 4 GB of addressable memory, the product and your driver still
execute in separate segments. This is because of the way the DOS extender
handles its memory management for ".exp" executables.

Phar Lap's 386|DOS-Extender uses demand paging virtual memory management
(VMM) and alias selectors. Autodesk products that used the Phar Lap 2.2d
DOS Extender (AutoCAD 386 Release 10, for example) maintain a linked list
of alias selectors whenever code is loaded (i.e., a new driver). If the VMM
pages out some code, it is possible that the segment descriptors may
change. The Autodesk host product's linked list makes it possible to keep
the aliased segment descriptors current. This is not done for any code not
loaded by the Autodesk product's driver loader.

Therefore, your driver can open, close, read and write data files, but you
may not load and execute code when running under the 2.2d DOS Extender.

Some users of AutoCAD 386 Release 11 upgraded to the Phar Lap 2.6 DOS
Extender by running newdx. This added new system calls, including a call to
load an .exp file into memory. (Actually, the following system calls were
added as early as 2.3: 2513h, Alias Segment; 2526h, Get Config Info; 2529h,
Load EXP or REX File; 252Dh, Close VMM Handle; 252Eh, Get/Set VMM Params;
and 2530h, Set DOS data buffer size.) Drivers running under Phar Lap v2.6
and later can load code by using these new Phar Lap system calls.

3.5.2 UNIX
==========

UNIX ADI drivers execute as separate processes which communicate with
AutoCAD via pipes. This method of implementation is hidden from the ADI
driver and is subject to change. Our intent is to provide a platform-
independent environment for driver development with as much compatibility
as possible between releases of ADI.

There is no published display ADI specification for most UNIX windowing
systems. A display ADI driver is used by AutoCAD for these platforms, but
the source code is available only under a special non-disclosure agreement.
Contact the ADI Marketing Manager if you are interested in obtaining this.

If a published display ADI specification exists for a UNIX platform, it
will be covered in that platform's adikit.doc file. An example is the file
sparc/adikit.doc.

3.5.3 Windows ADI 4.1
=====================

A Windows ADI driver is implemented as a dynamic-link library (DLL), and
links with AutoCAD at run time. An application, such as AutoCAD, calls
functions within the DLL in much the same way as a static-linked library
(when the application executable is linked) and follows the ADI
specification. DLLs allow for efficient memory usage through the sharing of
code, data, or hardware.

For more information about DLL concepts and development, refer to your
Windows SDK documentation. Chapter 20 in the "Microsoft Windows Guide to
Programming" book thoroughly discusses dynamic-link libraries.

3.5.4 Macintosh ADI 4.1
=======================

The only Autodesk product that MAC ADI 4.1 supports is AutoCAD Release 11
for Macintosh, and it supports only display devices. Plotters are handled
by the MAC system printer interface with a few internal plotter drivers
provided in AutoCAD; digitizers for AutoCAD are handled through the Apple
Desktop Bus (ADB) interface.

AutoCAD for Macintosh supports display list drivers. In the P386
documentation, you can find general display initialization information and
discussions of how display list drivers behave.

Macintosh ADI drivers are implemented as stand-alone code resources. Even
though it links with AutoCAD at run time, AutoCAD calls the functions in
your driver in much the same way as a static-linked library. The functions
in your ADI driver follow the ADI specification.


3.6 Transport Layers
====================

3.6.1 Real-modeDOS Transport Layer
==================================

Some Autodesk products running in real-modeDOS use the obsolete "INT mode"
ADI interface. The INT mode interface communicates between the host product
and the ADI real-mode driver via the CPU registers. AutoCAD Release 12
continues to have limited INT mode support. Since no improvements have been
made to the INT mode interface since ADI 3.1, many new release 11 and 12
features will not work with old INT mode drivers.

A packet interface for real-mode ADI was introduced in ADI 3.1. This
replaced INT mode as the preferred real-mode ADI interface. In packet mode,
a single INT mode request is made at start-up time to establish a far-call
linkage for directly passing packets between the Autodesk product and real-
mode ADI drivers.

Real-mode ADI drivers do not have access to ADI dispatcher services and the
configuration of these drivers is not integrated with the Autodesk
product's configuration. Furthermore, real-modedrivers are very limited in
their use of memory because they are TSR (Terminate and Stay Resident)
programs. Due to these and other disadvantages, enhancements to real-mode
ADI discontinued in ADI 4.0. Further real-modedriver development is
discouraged. Real mode drivers do not have access to all AutoCAD Release 11
and release 12 features, for example. Furthermore, real-modedrivers are
simply not supported by Autodesk RenderMan, AVE Render and Autodesk 3D
Studio -- these products all require protected-mode(P386) ADI drivers.

For more information on real-mode ADI, look in the 41brlmd directory on the
ADIKIT CDROM. The ASCII document file, adi41.doc, is the most recent real-
mode ADI specification.

3.6.2 P386 ADI Transport Layer
================================

The P386 ADI interface uses two common memory buffers for the exchange of
regular ADI packets and dispatcher packets with Autodesk products.

A packet is copied into a common buffer area that both the controlling
product and your driver know about. The packet may contain information that
the driver needs to perform a request (as well as initiating the request
itself) and the driver can send information back to the controlling product
in the same manner. Each packet contains a code ("packet function code")
that is in a known location (relative to the common buffer), which
essentially tells the recipient about the rest of the structure. Thus, a
service can be requested or information passed in an efficient manner.

$cb

                          |----------|
      |--------------|    |adi packet|    |--------------|
      |              |--->|  common  |--->|              |
      |              |<---|  buffer  |<---|              |
      |  AUTODESK    |    |----------|    |              |
      |              |                    |  ADI DRIVER  |
      |  PRODUCT     |    |----------|    |              |
      |              |<---|dispatcher|<---|              |
      |              |    | service  |    |              |
      |              |--->| module   |--->|              |
      |--------------|    |common mem|    |--------------|
                          |----------|

$ce
Figure 3-2. Communication with ADI driver

As shown above, packets are passed through the common buffer, declared as
char *cbufadr. This buffer is declared in the library file containing your
compiler-specific startup code and is declared as external in your driver.
This library file also contains code that manages the communication between
your driver and the Autodesk product.

For AutoShade 386 and Autodesk 3D Studio, an additional common buffer,
offset by a fixed amount from the common buffer's address, is used for
passing scanline data to and from the Autodesk product. Your driver will be
given a relative offset from *cbufadr to the start of this second buffer
whenever it is required (for example, in packet RD_SLINE).

With the advent of dispatcher reentrancy (see chapter 4, Dispatcher
Services), it is now more important that driver authors remain aware of the
fact that P386 ADI's transport layer (communication between the host and
driver) shares a single common memory buffer for use by all ADI driver
types. Thus display, plotter, digitizer, and other ADI packet types all use
the same memory buffer. Since DOS is single-threaded, this is not usually a
problem. But if a driver of one type makes a dispatcher request which might
result in a call to an ADI driver of another type, the original packet
buffer contents will be destroyed during the dispatcher service. If AutoCAD
will be examining the return packet from the original request, the original
driver must restore the contents of the packet buffer.

3.6.3 UNIX ADI Transport Layer
================================

UNIX plotter and digitizer drivers are loaded by AutoCAD as child
processes. They communicate with AutoCAD via a single pair of pipes (or
sockets on some UNIX platforms) which are used to transport both regular
ADI packets and dispatcher packets. The opening, closing, reading and
writing of these pipes is handled by our library code which you link with
your UNIX driver.


$cb

|----------|                    |----------|
|          |                    |          |
| digitizer|---- read pipe----->|          |
|    or    |<--- write pipe-----| AutoCAD  |
| plotter  |                    |          |
| driver   |                    |          |
|          |                    |          |
|----------|                    |----------|

$ce
Figure 3-3. UNIX DG and PL communication


3.6.4 OS/2 ADI 4.0 Transport Layer
====================================

All AutoCAD drivers written to run under OS/2 are implemented as Dynamic
Link Libraries (DLL's) using the ADI specification. All OS/2 drivers
contain at least three functions: xxadi(), xxdllcfg() and xxdllxqt(), where
xx is replaced by dg for digitizers and pl for plotters. xxadi() is the
only entry point exported by the driver. Large model is assumed everywhere.
The entry point is called by AutoCAD during the configuration process and
also at the beginning of the execution time code. The public entry points
to the DLL are declared as _loadds to force the compiler to load the DS
register on entry. The call is of the form:

ADIENTRY *(*xxadi)(entry);

Where entry is the vector to the AutoCAD service routine function. The
driver should initialize a global function pointer of the form:

int (*entvec)(struct genpkt *)

for use by the linked driver service module.

The call into xxadi returns a pointer to a quadruple, the devent structure:

struct devent {
   struct devname *devname; /* link to first name */
   int (*cfgentry)();       /* CFG-time entry point */
   int (*xqtentry)();       /* XQT-time entry point */
   short devflags;          /* device flags */
};

The member devflags aids AutoCAD's configuration process by identifying the
type of driver. AutoCAD will refuse to load a driver that doesn't set
devflags correctly.

Table 3-1. Values for devent.devflag

Mnemonic          Value  Description

DEV_NULL          0x01   Null device

DEV_PM            0x02   PM display driver

DEV_PL            0x04   Plotter driver

DEV_DG            0x08   Digitizer

DEV_SYSPR         0x10   System printer driver

DEV_DS            0x20   Display driver

Note: The DEV_DS flag has been added for consistency across platforms and
isn't used by these ADI drivers.

Thus, the ADI DLL driver returns to AutoCAD a pointer to a structure that
contains a pointer to the device name list, the configuration time entry
point, the execution time entry point, and the type of driver. It is
possible for the configuration and execution entry points to be the same.

struct devname {
    struct devname *devname;   /* Link to next name or NULL*/
    char dev_aliasid;            /* Alias flag */
    char dev_name[DEVNAMSZ+1] ;  /* Driver config menu name */
};

The device name structure, shown above, allows the ADI programmer to define
the menu string that will be printed by AutoCAD when the user is doing
configuration and making a choice amongst several drivers. Since some
drivers may incorporate code for multiple hardware devices, the dev_aliasid
indicates to the driver which device the user actually selected.

The character string in dev_name[] must include both the name of the device
supported by the driver and the name of the author of the driver. Thus, the
sample drivers supplied with the PMADI kit all have " - by Autodesk"
appended to the device name string. This vendor identification makes it
easier for users to know who is responsible for supporting each ADI driver.

Once a driver has been selected by the user and its name stored in
AutoCAD's configuration file, the configuration and execution time
functions in the driver can be called by AutoCAD as required. Both the
configuration and execution functions use a packet mode calling scheme and
are called with a pointer to a structure/packet.

Generally, a driver's cfgentry() and xqtentry() functions should process
packets sent to them, usually modifying the packet received or replacing
the packet with one of another type, and usually returning (in a packet
member, usually member status) 0 on failure or 1 on success.

3.6.5 Windows ADI 4.1 Transport Layer
=======================================

Windows ADI 4.1 drivers are implemented as Dynamic Link Libraries (DLLs)
using the ADI specification.

3.6.5.1 Windows ADI 4.1 Display Drivers
---------------------------------------

Your ADI driver must be named dsacad.dll, replacing our sample ADI display
driver, and must be available to Windows following the guidelines which
Windows uses to locate DLLs.

AutoCAD Extension for Windows Release 11 contains an interesting internal
design feature which affects ADI. AutoCAD core code sends ADI display
packets via a common memory buffer to a private DLL (acadwin.dll) which in
turn makes calls to three public entry points in the actual ADI display
driver, another DLL named dsacad.dll. You will see some references to the
common memory buffer in the display ADI header files. Your driver should
not attempt to access the common memory buffer.

AutoCAD Extension for Windows Release 11 handles the pull-down menus,
dialogues, alerts, and so forth. AutoCAD uses standard Windows calls to do
this, and these calls are not passed to the ADI driver.

The ADI driver, dsacad.dll, handles the client area of the graphic screen,
but does not manage pull down menus, dialogues, or the text screen. This
simplifies the ADI driver. The private DLL (acadwin.dll) handles the ADI
packets relating to dialogues and menus and only passes selected ADI
packets on to the ADI driver. These are passed through one of the DLL entry
points.

AutoCAD doesn't pass the entire internal common memory buffer out to the
DLL. Instead, we make individual ADI packet calls. This is because passing
the common memory buffer to the DLL would make the DLL AutoCAD specific.
Using packet calls allows the DLL to be used by other Autodesk products.

In addition, passing the common buffer would slow down our version of the
ADI driver (DLL) that we ship with the product. If we did pass the entire
common buffer, the DLL would have to read the buffer and pick out the calls
to the client area. Then the AutoCAD Windows code would have to read the
common buffer and pick out everything not in the client area. Any client
area calls generated by the AutoCAD Windows code, such as the tool bar,
would have to be placed in the common buffer and passed back again to the
DLL. Since our DLL uses standard Windows GDI calls, all this is
unnecessary.

It's much simpler to have the AutoCAD Windows code read the common memory
buffer and make calls to the DLL for the client area.

If FASTDRAW is enabled, vectors bypass the common buffer and are sent
directly to the ADI driver (DLL) via the dsfast_vector() entry point.

Driver Entry Points
-------------------
The DLL entry points for display ADI drivers are hard coded into AutoCAD
core. This is done to eliminate an extra layer of indirection that would
otherwise be required for function calls. There are normally three entry
points for the display ADI driver DLL, but additional entry points are
possible.

Two of the entry points are mandatory, and must be named dscfg() for the
driver configuration-time entry point, and dsxqt() for the driver execution-
time entry point. The third entry point is optional, depending on whether
or not FASTDRAW is implemented. If FASTDRAW is supported, the FASTDRAW
entry point must be named dsfast_vector().

To summarize, here is how the three DLL entry points for a display ADI
driver would be declared:

BOOL FAR PASCAL dsxqt(FARWIND, void far *);
BOOL FAR PASCAL dscfg(FARWIND, void far *);
BOOL FAR PASCAL dsfast_vector(FARWIND, LPPOINT,
                              short, short, short);

The FARWIND Structure
---------------------
All three entry points in Windows display ADI also have a FARWIND pointer
to the "window" structure, as well as the pointer to the packet, as one the
parameters. This structure provides information about the current state of
the display environment. The structure and the pointer to it are declared
in winacad.h:

typedef window far * FARWIND

The "window" structure was inherited from the OS/2 ADI interface. Some of
the concepts in PM OS/2 have like concepts with different names in Windows.
The names of the members in the window (FARWIND) structure have not been
changed to match Windows terminology.

Look at the type definition to find the equivalent windows concept. For
example, in OS/2 the graphics area is a presentation space (ps), and in
Windows the most like concept is the device context (dc). Also in OS/2 the
window frame has a separate handle, while this is not true in Windows where
the frame and window are the same.

Here is the "window" structure:

/* AutoCAD window definition */

typedef struct _window {
   HDC     ps;                    /* Current DC (hdc or bmap_ps) */
  /* It's set to the bmap_ps only while the gfx screen is iconic */
   HDC     bmap_ps;                                /* Bit map DC */
   HBITMAP hbitmap;                             /* Bitmap handle */
   HDC     hdc;                /* Graphics screen device context */
   HWND    frame;                      /* Graphics window handle */
   HWND    wnd;                        /* Graphics window handle */
   HWND    menu;                                  /* Menu handle */
   RECT    rect;               /* Position rectangle for window */
   FARPROC wndproc;           /* 'Full service' window procedure */
   FARPROC subclasswndproc;       /* Subclassed-window procedure */
   char    *wndclass;            /* Pointer to class-name string */
   HPEN    hpen;                 /* Current pen selected into DC */
   HFONT   hfont;           /* Current font selected into window */
   HANDLE  hPal;                    /* Handle to logical palette */
   DWORD   fgcolor;                          /* Foreground color */
   DWORD   bgcolor;                          /* Background color */
   HBRUSH  bgbrush;                          /* Background color */
   DWORD   textcolor;                              /* Text color */
   DWORD   textbgcolor;                 /* Text background color */
   HBRUSH  scrollbrush;          /* Text background scroll brush */
   LINEBUNDLE lb;                  /* Linebundle for this window */
   CHARBUNDLE cb;                 /* Character bundle for window */
   short   lhilight;
   short   lcolor;
   LONG    setpat;                     /* Pattern for path fills */
   short   xbias;                             /* xbias for mouse */
   short   ybias;                             /* ybias for mouse */
   short   xsize;                                 /* Window size */
   short   ysize;
   short   chars;                /* Number of horiz chars in win */
   short   lines;                             /* Number of lines */
   short   charwid;                        /* Current font width */
   short   charhgt;                       /* Current font height */
   short   chardcn;           /* Current font character descent  */
   short   xpos;                      /* Current text x position */
   short   ypos;                      /* Current text y position */
   short   type;                                  /* Window type */
   short   notxt;                          /* Notext window flag */
   short   cmdpop;        /* Unused - popup command entry window */
   short   split;               /* 0 - 3 scroll line prompt area */
   short   nomnu;                        /* No sidebar menu flag */
   short   cline;           /* No status line (toolbar included) */
   short   ldbreturn;            /* Last character CR no LF flag */
   short   xdrawmode;     /* Current drawing mode, XOR or normal */
   char    prevlayer[9];     /* Toolbar needs to know last layer */
   short   tbitmap;          /* TRUE if bitmaps are in toolbar   */
   short   xclinec;                        /* Start of coordline */
   short   xmlinec;                         /* Start of modeline */
   short   rd_restore;         /* Bitmap or redraw screen repair */
   int    (FAR PASCAL *entvec)(struct genpkt far *); /* NOT USED */
                      /* NOT USED--dispatcher entry point vector */
   short   tbarsize;           /* Toolbar bitmap size in pixels  */
   int     wTbPacket;     /* System tablet packet message number */
   /* The 4 tablet members are not functional in Windows ADI 4.1 */
   HANDLE  hRgn;                  /* System tablet region handle */
   FARPROC lpTabletRegionStack;       /* System tablet function. */
   FARPROC lpTabletEnable;            /* System tablet function. */
   short   win_on_screen;           /* Flags the on screen state */
                                      /* Iconic, full screen etc */
   WINFLAGS flags;                                  /* See below */
   short   cxFrame;       /* System window frame width in pixels */
   short   cyFrame;
   short   fastdraw;         /* If clear, write to bitmap always */
   RECT    *pcolorrect;   /* Pointer to the color box on Toolbar */
} window;

typedef struct {
    unsigned write_bitmap : 1; /* True if must update bitmap too */
    unsigned has_focus : 1;           /* Set if window has focus */
    unsigned mouse_out : 1;                         /* NOT VALID */
    unsigned mouse_captured : 1;                    /* NOT VALID */
    unsigned in_dwg_editor : 1;/* Set when drawing editor active */
} WINFLAGS;

The CHARBUNDLE and LINEBUNDLE are not kept current during AutoCAD
execution. CHARBUNDLE is used during the Environment Dialog Font selection
and during the initial loading of the screen fonts. It DOES NOT contain the
current drawing character attributes. LINEBUNDLE is used during clipboard
and metafile functions it is not used consistently during the regular
AutoCAD drawing session. Following are the CHARBUNDLE and LINEBUNDLE
declarations:

/* Drawing attributes from OS/2 - redefine the following structs */
/* line bundle for GpiSetAttributes and GpiQueryAttributes */

typedef struct _LINEBUNDLE {   /* lbnd */
    short   lColor;
    short   fillColor;
    LONG    lReserved;
    USHORT  usMixMode;
    USHORT  usReserved;
    LONG    fxWidth;
    LONG    lGeomWidth;
    USHORT  usType;
    USHORT  usEnd;
    USHORT  usJoin;
} LINEBUNDLE;

/* character bundle for GpiSetAttrs and GpiQueryAttrs */
typedef struct _CHARBUNDLE {          /* cbnd */
    DWORD     lColor;
    DWORD     lBackColor;
    USHORT    usMixMode;
    USHORT    usBackMixMode;
    USHORT    usSet;
    USHORT    usPrecision;
    SIZEF     sizfxCell;
    POINTL    ptlAngle;
    POINTL    ptlShear;
    USHORT    usDirection;
} CHARBUNDLE;

Additional DLL Entry Points
---------------------------
You may create additional entry points to your ADI driver (DLL) for custom
features using standard Windows programming techniques.

3.6.5.2 Transport Layer for Windows Digitizer and Plotter ADI
-------------------------------------------------------------

The transport layer for ADI digitizers and plotters is different than that
of ADI display drivers. The driver's CFG and XQT entry points are called
with a pointer to the packet to be processed.

The Windows ADI specification differs from the P386 specification in that
it uses the devent structure rather than the edevent structure to establish
communications between AutoCAD and the Windows ADI driver. The devent
structure (in ADI 4.1) contains some members which were not added to the
edevent structure until ADI 4.2 (the members sentinel, platform, options
and stream). The other difference is that the devent structure contains a
pointer to a linked list of devname structures, each containing a single
dev_name[] string, while the edevent structure simply contains 5 dev_name[]
strings.

In order to generate a list of devices during ADI device driver selection
time, each driver is in turn loaded, queried and released by AutoCAD. Upon
successful loading, AutoCAD stores the alias and the name of the device in
a table to be displayed to the user. Upon obtaining this information, the
driver is released to the operating system so the next one can be loaded.

Once a driver has been selected by the user and its name stored in
AutoCAD's configuration file, the configuration and execution time
functions in the driver can be called by AutoCAD as required. Both the
configuration and execution functions use a packet mode calling scheme and
are called with a pointer to a structure/packet. Generally, a driver's
cfgentry() and xqtentry() functions should process packets sent to them,
usually modifying the packet received or replacing the packet with one of
another type, and usually returning (in a packet member, usually member
status) 0 on failure or 1 on success.

If a configuration file already exists, the entry point function for the
specified driver is called at AutoCAD startup time in order to load the
pointers to the driver's configuration and execution time functions.

The acalls() entry point is optional in Windows ADI 4.1 drivers.

The public entry points to the ADI driver DLL need to be declared as
_loadds to force the compiler to load the DS register on entry. The public
entry points are the optional acalls() function, the ADI driver's
configuration time entry point, and the driver's execution time entry
point.

The devent structure is defined in p386adi.h. Refer to the sample drivers
source code to examples on the use of this structure.

struct devent {
    struct devname *devname;      /* Link to first name */
    int (_loadds *cfgentry)();    /* CFG-time entry point */
    int (_loadds *xqtentry)();    /* XQT-time entry point */
    short devflags;               /* Device flags */
    short adiversion;             /* ADI revision level */
    char sentinel[SENTINLEN];
    char platform[PLATFORMLEN];
    short options;
    char stream[SENTINLEN];     /* Internal source stream */
};
#define PLATFORMLEN 32               /* Defined in path.h */
#define SENTINELEN  15               /* Defined in path.h */
#define PLATFORM "Microsoft Windows" /* platform.h */

The devent structure uses the devname structure to maintain a linked list
of alias driver names (so that a single driver may support several devices,
each with a configuration menu entry). Most drivers will have only a single
device name and hence only one devname structure. The devname structure is
defined in p386adi.h as follows:

struct devname {
    struct devname *devname;   /* Link to next name */
    char dev_aliasid;          /* Alias flag */
    char dev_name[DEVNAMSZ+1]; /* Driver config menu name */
};

The cfgentry and xqtentry members declare the drivers configuration and
execution entry points. It is possible for a driver to set both of these
members to the same value. Refer to sample driver code to see examples of
how these members should be set in the devent structure.

The member devflags aids AutoCAD's configuration process by identifying the
type of driver. AutoCAD will refuse to load a driver that doesn't set
devflags correctly. The possible values are:

Table 3-2. Values for devent.devflags

Mnemonic          Value   Meaning

DEV_NULL          0x01    Null device

DEV_PM            0x02    PM display driver

DEV_PL            0x04    Plotter driver

DEV_DG            0x08    Digitizer

DEV_SYSPR         0x10    System printer driver

DEV_DS            0x20    Display driver


AutoCAD uses the adiversion member to determine the ADI drivers
capabilities. Windows ADI drivers should set this field to the ADIPKTLEVEL
constants defined in dgp.h or plp.h.

The sentinel[] member is a string which has the following values in ADI
4.2:

DEV_DS: "$ACADDSNAME$"
DEV_RC: "$ACADRCNAME$"
DEV_RD: "$ACADRDNAME$"
DEV_RH: "$ACADRHNAME$"
DEV_PL: "$ACADPLNAME$"
DEV_DG: "$ACADDIGNAME$"
DEV_VT: "$ACADVTNAME$"

Windows ADI 4.1 drivers should set this member to the NULL string: "".

The member platform identifies the machine as P386, Sun4, Sun3, Sun386i,
and so forth. Refer to platform.h for a complete listing of supported
platforms. This member allows AutoCAD to identify executables for the wrong
platform, and a warning message is displayed if a UNIX driver for the wrong
platform is detected. Note that the listing of a platform in platform.h is
not a commitment by Autodesk that it will be supported by AutoCAD Release
12. Windows ADI 4.1 drivers assign member platform the string "Microsoft
Windows".

The member options will allow a driver to pass essential option flags
before execution progresses very far. A Windows 4.1 ADI driver should set
this member to 0.

The stream member was added to allow users to identify the code stream from
which a driver was built. This is a text string. Internally at Autodesk we
use it like this:

static struct devname
    plname = {NULL, ' ',"System Printer ADI 4.1 - by Autodesk."};
struct devent plpdev = {&plname,
pladicfg1,
pladixqt1,
                        DEV_PL | DEV_SYSPR,
ADIPKTLEVEL,
"",
PLATFORM,
                        0,
#include "adid.h"
};

where the contents of adid.h looks like this:

"(A.D.87)"

In other words, adid.h contains the code stream revision number for this
build of the driver. ADI developers may choose to put a revision number
here. The contents of the stream member will be displayed to the user at
configuration time, making it easier to identify the exact driver in use.

3.6.6 MAC ADI 4.1 Transport Layer
===================================

From AutoCAD's perspective, a display ADI driver is a stand-alone code
resource of type 'DADI' residing in a file of type 'BOBm'. Drivers must use
resource ID 0 for their DADI resource. An actual driver system could
consist of more than this; for example, it's likely that third-party
drivers will talk to a system-level device driver or code residing on an
accelerator board.

Even though it links with AutoCAD at run time, AutoCAD calls the functions
in your driver in much the same way as a static-linked library. The
functions in your ADI driver follow the ADI specification.

Your ADI driver must contain at least two functions:

1)        An initialization/termination routine. This is called when the
driver is loaded into memory, or unloaded from memory.

2)        An ADI packet handler.

3.6.6.1 Driver Entry Points
---------------------------

When AutoCAD first launches, it opens the ADI driver's resource file and
loads and HLocks the stand-alone code resource. It then calls the
instruction at the beginning of the resource, which is expected to be the
dual-purpose function for initialization or termination (or a jump to it).
This declaration must be of the form:

ProcPtr InitTermADI(InitRec *theInitRec)

where this is the InitRec structure:

typedef struct InitTermRec{
    short pfunc;                 /* MINIT or MTERM */
    char *idString;
    short interfaceVersion;
} InitRec;

AutoCAD calls InitTermRec() upon entry to the drawing editor with the
member pfunc set to MINIT to load the driver. It calls InitTermRec() with
the member pfunc set to MTERM either at the end of the AutoCAD session or
upon a change in the display configuration.

When this is called as an initialization routine, the value of pfunc is set
to MINIT. You should copy an identification string of up to 255 characters
to idString; this will appear in the AutoCAD's About... dialogue box.

The interfaceVersion member is currently used for development. Your driver
should return MAC_ADI_VERSION in this member.

The return value from this function should be the address of your driver's
packet handler routine. If the ADI driver cannot run correctly at this
point (e.g., it can't allocate memory for display lists, can't find its
accelerator card, etc.), it should return NULL. AutoCAD does not try to
diagnose or correct the problem, but tries to use its internal display
driver.

During normal execution, AutoCAD calls the packet handler, which is
expected to be of the form:

void MacDisplay(struct pkfonly *apk)

When AutoCAD exits (as an application, not just the drawing editor), after
sending its final PTERM packet, it calls the initialization or termination
routine with member pfunc set to MTERM. This routine should do necessary
cleanup, release dynamically allocated memory, and so forth. Following
this, AutoCAD releases the driver's code resource and closes the driver's
resource file.

AutoCAD does not change the ADI resource, does not mark it as changed, does
not make an explicit attempt to write it back out to disk, and does not
check for success when closing the resource file makes an implicit attempt
to do such a write. Your driver can perform all these steps, and the
termADI routine might be a good place for performing them.


3.7 Driver Selection
====================

3.7.1 AutoCAD Release 12
========================

Almost all of the drivers in AutoCAD Release 12 are ADI drivers (ADI 4.2).
The method of driver location and loading has been changed in Release 12
386. See p386adi.doc and 3.7.2 in this document for a discussion of how
drivers were loaded in earlier ADI versions.

3.7.1.1 ACADDRV Environment Variable
--------------------------------------

A new environment variable has been defined: ACADDRV. This can be set to a
list of directories, separated by semicolons. It tells AutoCAD where to
search for ADI drivers. Drivers should be installed into one of the
directories on the ACADDRV path. AutoCAD will search all of the directories
on this path, even if it finds drivers of the desired type before reaching
the end of the path.

If the ACADDRV environment variable is not set, or if no drivers of the
desired type are found on the ACADDRV path, then AutoCAD searches in: the
default directory, the ACADCFG directory, the system and execution
directories. If none of these directories has any drivers of the desired
type, the DOS path is searched. The UNIX path is not searched because the
search is too slow.

It is important to note that once the ACADDRV search fails, AutoCAD will
stop searching in the first directory where a driver of the desired type is
found. It will not continue searching (as it does while looking along
ACADDRV). The only way to make multiple drivers of the same type, but
located in different directories, appear in AutoCAD's configuration menu is
to list the directories on the ACADDRV path. It is very desirable for
drivers to be installed in directories on ACADDRV.

3.7.1.2 Using Pre-ADI 4.2 Drivers with AutoCAD Release 12
---------------------------------------------------------

The AutoCAD configuration menu picks for P386 ADI 4.0, P386 ADI 4.1, or
UNIX ADI 4.1 no longer show up in the configuration menu because of a new
method of finding ADI drivers. Instead, AutoCAD searches for ADI drivers
and puts their names into the configuration menu. For this new feature to
work, two conditions must be met:

1)        The ADI driver must be on AutoCAD's driver search path (described
above).

2) The driver must be named so that AutoCAD recognizes it as an ADI
   driver of the correct type:

   * Display drivers must have names starting with ds.

   * Combined rendering and display drivers must start with

   * Plotter drivers must start with pl.

   * Digitizer drivers must have names starting with dg.

   * Rendering hard copy drivers must start with rh.


Some pre-ADI 4.2 drivers will not run unprivileged. See chapter 2, section
2.6 for a discussion of this issue.

The IGNORE_BIG_SCREEN environment variable may be set to force AutoCAD
Release 12 into 31-bit regen space despite the use of a 15-bit display list
driver. See chapter 6. section 6.5.1.

3.7.1.3 ADI Driver Validation
-----------------------------

When AutoCAD finds a file with the name of a prospective ADI driver, it
scans the file looking for the edevent sentinel string defined for that
driver type. Note that the sentinel string must match the driver name
prefix or else the driver will be rejected as invalid. For example a file
with a "ds" prefix and the $ACADRCNAME$ sentinel will not appear in the
configuration menu. Since AutoCAD scans the file without executing it, the
edevent structure must be completed at compile-time and not at run-time.

Since AutoCAD starts its search at the start of the .exp file, the search
will be speeded up if the edevent structure is as close as possible to the
start of the file. If you use MetaWare High C 386 v1.7, this can be done by
not declaring the structure as static. If the proper sentinel is found,
then this must be an ADI 4.2 P386 driver or an ADI 4.1 or 4.2 UNIX driver.
The edevent structure is examined to verify the device type and platform.
Then the driver name strings are added to the configuration menu. If, on
the other hand, no sentinel is found, this is an older (pre-ADI 4.2 P386)
driver. AutoCAD searches for a fragment of binary code (part of our library
code) which is linked into every valid driver. If this is found, the driver
is executed to get its edevent structure and name strings, then it is
unloaded. If the "magic" code fragment isn't found, the file is not a valid
ADI driver (perhaps it is an ADS application) and it is not executed. Thus,
it is not listed in the menu.

AutoCAD Release 12 no longer uses the environment variables or magic
filenames that were previously used to locate ADI drivers. Other products,
such as AutoShade Version 2 and 3D Studio V1.0 and V2.0 continue to use
these. To load an ADI driver for these products, simply set the appropriate
environment variable or use the magic filename.

3.7.2 Products Other Than AutoCAD Release 12
============================================

AutoShade 386 v2.0 only searches for magic filenames in the current
directory. Also, AutoShade 386 v2.0 does not know about the environment
variable RCPADI or the magic file name adirc.exp. In order for AutoShade
386 v2.0 to use a DEV_RC driver as a display driver, you should set the
environment variable DSPADI to your DEV_RC driver. To use a DEV_RC driver
as an AutoShade rendering driver, set the environment variable RDPADI. Or,
to use a DEV_RC driver for both a display and rendering driver, set both
environment variables.

While AutoShade 386 v2.0 doesn't recognize the RCPADI environment variable,
it does detect that the same driver name is supplied for DSPADI and RDPADI
and loads the DEV_RC driver. 3D Studio v1.0, however, loads and unloads the
driver for each of its subprograms, thus making it impossible to depend on
passing variables between the rendering and display sections of a DEV_RC
driver.

For products other than AutoCAD Release 12, here are the magic filenames
and environment variables:

Table 3-3. ADI environment variable and magic file names

Type of driver  Environment variable name    Magic filename

DEV_DG          DGPADI            adidig.exp

DEV_DS          DSPADI            adidisp.exp

DEV_PL          PLPADI            adiplot.exp

DEV_RD          RDPADI            adirend.exp

DEV_RH          RHPADI            adirndhc.exp

DEV_RC          RCPADI            adirc.exp


3.7.3 Product ID, Serial Number, and Version number
===================================================

Although it is true that in theory all Autodesk products should treat ADI
drivers identically, in reality there are substantial differences in how
different products behave. A new packet, PWHO, has been added for all
device types (except rendering drivers which get RDWHO) in ADI 4.2. This
packet serves a number of purposes: it identifies the product, version, and
(for some products) serial number of the product currently in control. It
also provides the full path name by which the ADI driver was invoked, and
on UNIX platforms it provides the PID of the controlling application.
Additional members in PWHO provide for ADS->ADI link handshaking with
display and rendering drivers (see chapter 5).

The product serial number enables vendors who wish to protect their
software to key it during installation to a single Autodesk serial number,
much as we key UNIX AutoCAD to a single workstation serial number.

In AutoCAD Release 12, ADS applications such as AVE Render will be allowed
to take control of ADI drivers in some circumstances. It is desirable for
ADI drivers to know what application is taking control. It is essential for
the application to be able to specify whether it is taking over the whole
screen or just a viewport, and how it wants the palette handled. It is also
necessary for the driver to be able to ask AutoCAD to provide some cleanup
(repaint) services after the ADS application is done and for normal
operation to resume.

3.7.4 Driver Level Numbering Scheme
===================================

There are two ADI interface level numbering schemes: the old one and the
new one. The old scheme used INTLEVEL, while the new scheme uses
ADIPKTLEVEL as the tag for the current interface level. A few old packets
still use the old INTLEVEL scheme, but all new packets use the ADIPKTLEVEL
numbering system. Read each packet or structure's specification carefully
to be sure you understand which numbering scheme is used.

ADI driver compatibility with the host product is determined by the ADI
interface level. All Autodesk products supply an ADI level indicator to ADI
drivers during driver initialization. The interface level value is usually
different for various device types (DEV_DG, DEV_PL, etc.) and should be
checked by every driver.

We have supplied some convenient #defines to make it easy to test
ADIPKTLEVEL values for various device types and interface levels. These
follow the form: DG_LEVEL_41, where the first 2 letters indicate the driver
type and the last 2 digits indicate the ADI version. These are defined in
adi.h as follows:

#define DG_LEVEL_42     4
#define DG_LEVEL_41     3
#define DG_LEVEL_40     1
#define PL_LEVEL_42     3
#define PL_LEVEL_41     2
#define PL_LEVEL_40     1
#define DS_LEVEL_42     1
#define DS_LEVEL_41     0
#define RD_LEVEL_42     3
#define RD_LEVEL_41     2
#define RD_LEVEL_40     1


3.8 Driver Loading and Initial Invoke
=====================================

As an ADI driver is loaded and initialized, Autodesk host products and the
driver pass information about the features they require and support. These
mechanisms allow a driver to determine whether or not it is compatible with
a particular Autodesk product. Drivers must safely and quietly ignore host
packet requests they do not understand, need, or support. This allows older
drivers to work with newer Autodesk products even though they may suffer
limited functionality from not supporting newly implemented features in the
host product.

3.8.1 The edevent Structure
===========================

History
-------
The devent structure was introduced in OS/2 ADI 4.0. The edevent structure,
a slight modification of the devent structure, was introduced in P386 ADI
4.0. Additional members have been added to the structure with each
subsequent ADI revision. The edevent structure is used in P386 and UNIX
ADI, while the devent structure continues to be used in OS/2 and Windows
ADI.

Purpose
-------
Most essential initialization data is passed or established by the edevent
structure. The edevent structure is located by the host product using the
methods described above. Once the edevent structure is located, the driver
type, version and name are extracted. If the driver is of the proper type
and version, it is displayed in the configuration menu.

Declaration
-----------
struct edevent {
    char dev_name[MAX_DEV][DEVNAMSZ + 1];
                               /* driver config menu name */
    void (*cfgentry)();      /* configuration entry point */
    void (*xqtentry)();          /* execution entry point */
    short devflags;                  /* device type flags */
    struct eadient adientp;   /* adientry connection data */
    short adilevel;                 /* adi revision level */
    char sentinel[SENTINLEN];
    char platform[PLATFORMLEN];/* what CPU & o/s do we
                                                  run on? */
    short options;                      /* driver options */
    char stream[SENTINLEN];     /* code stream or version */
};
struct eadient {
    unsigned long savesp;          /* Offset to saved SS:ESP
                                          on AutoCAD side */
    unsigned short cs;                    /* AutoCAD's CS */
    unsigned short ds;                    /* AutoCAD's DS */
    long (*adientry)(); /* Offset to AutoCAD's adientry() */
                                          /* (dispatcher) */
};
#define PLATFORMLEN 32               /* defined in path.h */
#define SENTINELEN  15      /* likewise defined in path.h */
#define MAX_DEV 5          /*we don't plan to change this */

Description
-----------
AutoCAD Release 12 scans driver files before loading them, looking for the
edevent struct. Hence, the structure must be filled in at compile time and
not at execution time.

Once the edevent structure is located, the driver type, version and name
are extracted. If the driver is of the proper type and version, it is
displayed in the configuration menu.

The dev_name string must include the name of the company or person who is
responsible for providing support for the driver. Drivers written by and/or
for Autodesk say "- by Autodesk". It is highly improper for third party
drivers to use this string.

The sentinel member is used by Release 12 AutoCAD on all platforms to
validate potential drivers during the driver search process. The sentinel
value must match the driver type. For example, a DEV_DS with the
$ACADRCNAME$ sentinel will be considered an invalid driver and will not be
loaded. The sentinel member is a string which takes on the following
values:

DEV_DS: "$ACADDSNAME$"
DEV_RC: "$ACADRCNAME$"
DEV_RD: "$ACADRDNAME$"
DEV_RH: "$ACADRHNAME$"
DEV_PL: "$ACADPLNAME$"
DEV_DG: "$ACADDIGNAME$"
DEV_VT: "$ACADVTNAME$"

The member adilevel should contain the driver's ADIPKTLEVEL for all device
types except DEV_DS and DEV_RC, which use the old display INTLEVEL
numbering scheme for adilevel.

The member platform will identify P386, Sun4, Sun3, Sun386i, etc. to allow
AutoCAD to identify executables for the wrong platform. A warning message
is displayed if a UNIX driver for the wrong platform is detected. These
values are defined in the header file platform.h. The listing of a platform
in platform.h is not a commitment that it is or will be supported by
AutoCAD Release 12!

The following list shows the strings that can be assigned to the #define
PLATFORM (from platform.h):

#define PLATFORM "Sun 386i"
#define PLATFORM "Sun 3"
#define PLATFORM "Sun4/SPARCstation"
#define PLATFORM "DECstation"
#define PLATFORM "IRIS"            /* SGI */
#define PLATFORM "UNIX System V/386"
#define PLATFORM "IBM RS/6000"
#define PLATFORM "UNIX"           /* other UNIX platforms */
#define PLATFORM "XENIX"
#define PLATFORM "Macintosh"
#define PLATFORM "OS/2"
#define PLATFORM "Microsoft Windows"
#define PLATFORM "Phar Lap"

The member options will allow a driver to pass essential option flags
before execution progresses very far.

The first option is to not demand load for P386:

#define NO_DEMAND_LOAD  0x1  /* Don't demand load for P386 */

This flag was added for use by any driver which can't work with demand
loading at CFG or XQT time.

The stream member was added to allow users to identify the code stream from
which a driver was built. This is a text string. Internally at Autodesk we
use it like this:

struct edevent dscev =
    {{"Logitech 3-D mouse ADI 4.2 - by Autodesk",
     "", "", "", ""}, dgadiproc, 0,
     DEV_DG, {0}, ADIPKTLEVEL, "$ACADDIGNAME$",
     PLATFORM, 0,
#include "adid.h"
        };

where the contents of adid.h look like this:

"(A.0.79)"

In other words, id.h contains the code stream revision number for this
build of the driver. ADI developers may choose to put a revision number
here. The contents of the stream member will be displayed to the user at
configuration-time, making it easier for product support to identify the
exact driver in use.

32-bit ADI 4.1 and 4.2 digitizer, plotter and display drivers work with
this scheme.

The device type is also returned in the edevent structure, as defined in
the following table. These mnemonics are defined in p386adi.h.

Table 3-4. ADI device driver types

Mnemonic       Value                     Device driver type

DEV_PL         0x04                      Plotter device driver

DEV_DG         0x08                      Digitizer device driver

DEV_DS         0x20                      Display device driver

DEV_RD         0x40                      Rendering (to display) device
driver

DEV_RC         0x60                      Combined display and rendering
driver

DEV_RH         0x80                      Rendering hardcopy device driver

DEV_VT         0x100                     Video Transport Recording device

DEV_BI         0x200                     Bitmap Input


Note that printer plotters are not directly supported by ADI 4.2 drivers,
but they can be implemented through the DEV_PL driver specification.


3.9 Establishing Communication
==============================

3.9.1 P386
==========

P386 ADI drivers contain 3 functions which establish communication between
the Autodesk host product and ADI driver. These functions provide the host
product with the driver's configuration-time and execution-time entry
points, establish the common buffer and hook your driver to the dispatcher.
These 3 functions are acalls(), CFG(), and XQT(), where CFG() is the
configuration entry point, and XQT() is the execution entry point whose
addresses are supplied in the edevent structure members cfgentry() and
xqtentry().

3.9.2 UNIX
==========

UNIX ADI drivers communicate between themselves and the host product via
pipes or sockets. This transport layeris handled by library code which you
must link with your driver. The library code also takes care of the
initialization work which is done by acalls() for P386 drivers. Thus UNIX
drivers only use 2 of the 3 functions that P386 drivers do: xxadicfg() and
xxadixqt(). Internally, AutoCAD spawns the driver file as a child process.

To simplify driver structure and the design of the system that supports ADI
drivers, UNIX digitizer drivers use a single entry point for both
configuration and execution time. This entry point is placed by the driver
in (*cfgentry)() within the edevent structure. The (*xqtentry)() member is
ignored and may be set to 0.

Two entry points are supported for UNIX plotter drivers. You must supply
entry points for both the (*cfgentry)() and (*xqtentry)() members in the
edevent structure. It is possible for both entry points to be the same.

The structure of the sample driver has changed in two ways. First, we now
call the driver's entry points with a pointer to the packet. For
compatibility with this UNIX convention, the P386 sample code was also
modified to pass the packet as the parameter to the execution and
configuration entry points. To provide a familiar environment for existing
drivers, the external symbol cbufadr still also points to the packet.
Second, and as a result of the first change, drivers are no longer required
to reference cbufadr.

If you wish to have your driver compile for both P386 and UNIX, you should
employ some special techniques:

  * Organize digitizer drivers to use a single entry point.

  * The P386 implementation should use the latest version of plface.asm or
    dguface.asm. Note that dguface.asm forces both configuration and execution
    time packets to be processed by the same entry point.

The following will help you write more portable drivers:

1)  P386 drivers still need to fill in both the cfgentry() and
    xqtentry() members of the edevent structure.

2)  UNIX digitizer drivers must fill in at least the cfgentry()
    member. This is the single entry point that will be used for both
    configuration and execution packet processing.

3)  UNIX plotter drivers must fill in both cfgentry() and xqtentry()
    members of the edevent structure.

4)  Obtain the packet address from the parameter rather than
    referencing cbufadr.

3.9.1 acalls()
==============

On 386 platforms, the function acalls() is called by the main() which is
part of our library code (linked to your driver), whenever the driver is
first loaded. The call is of the form:

struct edevent *(*acalls)(entry);

where entry is a function pointer to the host's service routine dispatcher.

In order to tell the dispatcher library code how to make calls back to the
Autodesk product, your driver must declare a global pointer as follows:

int (*entvec)(struct genpkt *);

and set it to the value of the parameter to acalls(), such as

entvec = entry;

The function acalls() returns to the host a pointer to the edevent
str