****************************************************************************
*                          -- 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
structure, described above.

On OS/2 platforms, the function acalls() is called by the host product
whenever the driver is first loaded, during the configuration process and
also at the beginning of execution-time.

On UNIX platforms, our library code (linked with your driver) calls
acalls() and establishes communication links between its internal pipe
handling code and your driver's entry points. This scheme minimizes the
platform dependencies in digitizer and plotter drivers.

3.9.2 P386 xxadicfg() and xxadixqt()
====================================

The calls which the host product makes to your P386 (*xxadicfg)() and
(*xxadixqt)() entry points are far calls. In the sample drivers, we have
used small assembly modules plpface.asm, dgpface.asm and dspface.asm to
redirect these into near calls to functions in the main driver C code for
plotters, digitizers and displays. Refer to the sample driver code to see
examples of how these functions are implemented.

Although the edevent structure declares these two entry points as returning
void, some early Autodesk products (e.g., 3D Studio v1.0 and AutoShade 386
v2.0) will fail if 1 is not returned. To make these older products happy,
the assembly modules dspface.asm, rcpface.asm, etc., all stuff 1 into the
EAX register just before returning.


3.10 Driver Configuration
===========================

It is very desirable for your driver to use dispatcher services at
configuration-time for any user interaction. This will allow scripts to
work, and it also may allow your driver to continue working with future
versions of our products, which may use a dialogue interface for some parts
of configuration, in a manner similar to how AutoCAD Release 12 handles
execution-time plot configuration.

The ADI specification makes a provision for your ADI driver to support
several devices with different names (dev_name[] in the initialization
packet structure) and several models of each device (mname[] in the
initialization packet structure). The dev_name[] entries appear in
AutoCAD's configuration menu. In other words, if your driver is for a
digitizer and has three dev_name[] entries, the three dev_name[] strings
will appear in AutoCAD's digitizer configuration menu. The mname[] strings
are displayed only after the user has picked a menu item corresponding to
one of the dev_name[] entries in your driver.

The dev_name[] string may be up to DEVNAMSZ in length for each device name
supported (DEVNAMSZ is defined in p386adi.h). The dev_name[] string should
include the device name and the identity of the driver's author. For
example, "Hitachi HICOMSCAN HDG Series, by Autodesk". The mname[] string
should identify a particular model number (e.g., "Model 1111"). Unused
members of the dev_name[] array should be null strings. It is wrong for
third party drivers to use the "by Autodesk" string in dev_name[].

It is generally desirable for drivers to have only a single dev_name[]
entry and multiple mname[] entries, unless the various devices supported by
your driver fall into groups which are so different that the use of
multiple dev_name[] entries is justified.

In current releases of Autodesk products that run in protected mode under
DOS, such as AutoCAD 386 Release 12, up to five device names for each
device driver will be recognized. These are the five dev_name[] entries in
the edevent structure. Most Autodesk drivers which support multiple devices
do not use this method of providing multiple configuration choices because
it can rapidly make the configuration menu too long for easy use. Most of
our drivers resort to the use of a submenu of model names instead. We
suggest that your drivers do the same.

Successful loading of your driver entails the Autodesk product being able
to locate and communicate (exchange information) with it. If not already
performed by a configuration file, your ADI driver must be configured
immediately upon successful loading. Your driver is sent configuration-time
packets which make it easy for you to integrate your driver's configuration
with AutoCAD's. It is very desirable for you to do this instead of using a
stand-alone configuration utility.

A mechanism is provided for storing some driver-specific data in the
Autodesk product's configuration record for most device types. If the space
provided for this purpose is not sufficient, you may choose to open an
additional driver-specific configuration file for the storage of additional
data. It is a good idea to store this file in the directory pointed to by
ACADCFG when running under AutoCAD; this will simplify network operations.

Once a driver has been selected by the user and its name stored in the host
product's configuration file, the configuration-time and execution-time
functions in the driver can be called by the host product as required. It
is important that your ADI driver documentation cover the configuration
process for each of the Autodesk products your driver supports.

The PWHO packet lets ADI drivers know which application is executing them.
It can also let secondary applications know what ADI driver is currently
running. PWHO is available for every device type. Refer to the PWHO packet
descriptions for full details. Note that each device type (DS, PL, DG,
etc.) uses a different value for the PWHO packet code, but an otherwise
identical packet structure.

The PLANG packet is also supplied for every device type. PLANG allows your
driver to know the language and code page in use before AutoCAD starts
sending configuration or execution packets to your driver. This should
simplify internationalization of your drivers. Note that each device type
(DS, PL, DG, etc.) uses a different value for the PLANG packet code, but an
otherwise identical packet structure.


3.11 Driver Execution
=====================

Autodesk products generally have two modes of operation: configuration-time
and execution-time.

At configuration time the user establishes a new configuration or modifies
an existing configuration, selecting the devices to be used for display,
rendering, digitizing, and so forth. Autodesk products save configuration
information in a file which is consulted on startup.

Execution time refers to the normal use of the product, for example, in
AutoCAD's drawing editor. The ADI interface includes packets used
exclusively at configuration-time and other packets used exclusively at
execution-time. A few packets are used at both configuration and execution
times. Some device types (e.g., plotters) allow some execution- time
configuration, for which there are special execution-time configuration
packets.




                    |================================|
                    |                                |
                    |           Chapter 4            |
                    |                                |
                    |        ADI Dispatcher          |
                    |                                |
                    |================================|



4.1 Introduction
================

This chapter contains a detailed description of each of the dispatcher
service module functions. The dispatcher service module is part of the
provided library file that you should link to your driver.

It is important for your driver to use dispatcher services instead of C
library or O/S services. Here are some of the reasons:

  * At configuration time, scripts will work if you use dispatcher services
for all keyboard input.

  * Standard AutoCAD user interface rules and <Ctrl-C> handling are
available

  * If you allow AutoCAD to handle I/O instead of writing directly to the
hardware, you gain the benefits of AutoCAD error handling, port conflict
resolution, and (in the case of hard copy devices) graceful redirection to
a user-specified file.

  * When we make enhancements to the user interface (such as the execution-
time plot dialogues in release 12) it is more likely that your driver will
work with the new AutoCAD.

Most of the information passed between the Autodesk controlling product and
your ADI driver is done by exchanging data packets (packet mode was
discussed in chapter 3). These exchanges are generally initiated by the
controlling product. Sometimes, however, a driver would like to request a
service from the product. Typically drivers will make such requests in
order to avoid duplicating code that is already performed effectively by
the Autodesk product and to take advantage of the product's error handling.
To service these requests, Autodesk products export a certain number of
functions for use by ADI drivers.

In order to call a service function, a driver issues a function call as if
the driver were linked with the Autodesk product. The function's parameter
data is converted by our library code into a stream of packets which are
exchanged with the controlling product. The details of parameter passing
are taken care of in the service module linked with the driver.

From your driver's point of view, this provides a package of functions
which it can call. The dispatcher service module takes care of turning your
service request into packets which are sent to the controlling product's
core code. Your only concern in this matter is to provide a global function
pointer entvec to the entry point supplied by the product's call to
acalls(). You may refer to the sample driver source code file dgphit.c for
an example of the acalls() function.

ADI 4.2 allows your driver to be configured during the Autodesk product's
normal configuration process. It is desirable for your driver's
configuration dialogue with the user to be done entirely with the
dispatcher service functions. This is because use of the dispatcher service
functions would enable your driver's configuration dialogue to be
integrated into any future enhancements to an Autodesk product's
configuration process.

ADI drivers should exercise care in using dispatcher services; trouble
might result if a new driver running under an old product requests a
service which the old product doesn't provide. Most products will silently
ignore unrecognized dispatcher requests.


4.2 New or Improved Services
============================

Here is a list of improvements or additions to the dispatcher services
since ADI 4.1:

Made dispatcher reentrant

ctype functions

getcdname()

getplrec()

plseek()

pltell()

saveplrec()

iormc()

iormt()

setpltmout()

recfgport()

mgetch()

more()

nomore()

Changes in plsend(), ppsend(), and iow()

rhsend()

ciotype()


Note that most of these new services are only provided by AutoCAD Release
12. Check each dispatcher function description for a discussion of products
which support the function.

4.2.1 Reentrancy
==================

Before ADI 4.2, the dispatcher was not reentrant.

Currently, dispatcher calls are nested in two cases. One is during
configuration with the release 12 plotter dialogue and another is when
RenderMan is using a ADI hard copy driver.

The dispatcher has been modified so it is reentrant with respect to calls
to different services from different drivers. Most services will not be
reentrant with respect to calls to themselves; the reentrant dispatcher
will allow a digitizer driver to call iorm() while in the middle of a
plotter intparl() dispatcher service, but will not allow a second iorm()
call while in the middle of an iorm() call.

With the advent of dispatcher reentrancy, it now more important that driver
authors remain aware that P386 ADI's transport layer 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.

For example, suppose that AutoCAD 386 Release 12 is configured for an ADI
display, an ADI digitizer and an ADI plotter. During execution time the
user selects the PLOT command. Packets flow to the plotter driver for
execution-time configuration. Most of these packets are examined by AutoCAD
when they return from the plotter driver. If the plotter driver calls
dispatcher functions during execution-time configuration (see plep, for
example), these will stimulate both digitizer and display packets as the
plot configuration dialogue operates to service the dispatcher requests. On
return to the plotter driver, the original request packet in the common
memory buffer has been overwritten by display and digitizer packets. If the
plotter driver hadn't saved the original request packet before making the
dispatcher request and restored it afterwards, AutoCAD's plot configuration
data would have been corrupted.

Here is a code fragment from a plotter driver illustrating this:

case ECHGCONF_42:
#define PT plbxpl42cfg
    foo = *P;           /* Save packet data */
    /* This makes dispatcher requests: */
    xqtrecfg(&foo.pl_xmax, &foo.pl_plymax);
    if (cancel) {
        P->plcode = BAD;
        return;
    }
    *P = foo;   /* Restore modified packet to buffer */
    P->plcode = UPCFGREC;
#undef PT
    break;


The moral of this story is that ADI drivers which make dispatcher requests
while processing packets whose contents will be examined by AutoCAD must be
careful to save and restore the packet data.

4.2.1.1 Windows ADI 4.1 and (Transport Layer) Reentrance
--------------------------------------------------------

On most platforms, reentrant calls to ADI display drivers will be
tolerated, if you heed the warning regarding round-trip packets. Windows
ADI 4.1 for AutoCAD Release 11 is an exception. The transport layer for
display ADI 4.1 for Windows is not reentrant under any circumstance. For
this reason, the dispatcher is, by default, not linked into the sample
Windows display driver. Although you can link it in, you must never use a
dispatcher service which will trigger a reentrant call into the display
driver.

4.2.2 Ctype Functions
=====================

We have added ctype functions to the ADI library in ADI 4.2. AutoCAD
Release 12 is currently the only Autodesk product that supports these
functions. The ctype functions have the same basic name and purpose as
their standard C language counterparts, except that we have prepended
"adi_" to the name and have enhanced them for language localization.

All of the ctype functions except adi_isalnum_7bit() operate off an 8-bit
language definition table. adi_isalnum_7bit() is hard-coded to operate on
ASCII characters.

The 8-bit language definition table used by the ctype functions is
localized by Autodesk for each version of AutoCAD. The language definition
table is used so that functions such as adi_isalnum() will work correctly
for versions of AutoCAD localized for different languages.


4.3 Dispatcher Functions
========================

Following are descriptions for all the dispatcher functions, listed in
alphabetical order. Unless otherwise indicated on the function's title
line, the function is available for both P386 and UNIX platforms.


4.3.1 adi_evalch
==================

Function
--------
Evaluates the sorting weight of a character.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in AutoCAD Release 12 and ADI 4.2.

Syntax
------
int adi_evalch(c)
    int c;


Description
-----------
This routine evaluates a character to its true relative position in the
alphabet, and can be used for sorting.

adi_rqctype() must be called once before the first use of this function.

Return Value
------------
Returns the sorting weight of c.

See Also
--------
adi_rqctype()


4.3.2 adi_isalnum
===================

Function
--------
Determines if a value represents an alphanumeric character.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in AutoCAD Release 12 and ADI 4.2.

Syntax
------
int adi_isalnum(c)
    int c;


Description
-----------
This routine uses the language definition table to determine if c is an
alphanumeric character.

adi_rqctype() must be called once before the first use of this function.

Return Value
------------
Returns a nonzero value if c is the code for an alphanumeric character.
Otherwise the returned value is zero.

See Also
--------
adi_rqctype()


4.3.3 adi_isalnum_7bit
========================

Function
--------
Determines if a value is an alphanumeric ASCII character.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in AutoCAD Release 12 and ADI 4.2.

Syntax
------
int adi_isalnum_7bit(c)
    int c;


Description
-----------
This routine determines if c is the code for a ASCII alphanumeric
character; that is, one of the following:

0 1 2 3 4 5 6 7 8 9

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

a b c d e f g h i j k l m n o p q r s t u v w x y z


adi_rqctype() must be called once before the first use of this function.

Return Value
------------
Returns a nonzero value if c is the code for an alphanumeric ASCII
character. Otherwise the returned value is zero.

See Also
--------
adi_rqctype()


4.3.4 adi_isalpha
===================

Function
--------
Determines if a value represents an alphabetic character.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in AutoCAD Release 12 and ADI 4.2.

Syntax
------
int adi_isalpha(c)
    int c;


Description
-----------
This routine uses the language definition table to determine if c is an
alphabetic character.

adi_rqctype() must be called once before the first use of this function.

Return Value
------------
Returns a nonzero value if c is the code for an alphabetic character.
Otherwise the returned value is zero.

See Also
--------
adi_rqctype()


4.3.5 adi_isascii
===================

Function
--------
Determines if a value represents an ASCII character.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in AutoCAD Release 12 and ADI 4.2.

Syntax
------
int adi_isascii(c)
    int c;


Description
-----------
This routine tests c to see if its value is in the range of 0 to 127, the
range of the standard ASCII character set.

adi_rqctype() must be called once before the first use of this function.

Return Value
------------
Returns a nonzero value if c is the code for an ASCII character. Otherwise
the returned value is zero.

See Also
--------
adi_rqctype()


4.3.6 adi_iscntrl
===================

Function
--------
Determines if a value represents a control character.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in AutoCAD Release 12 and ADI 4.2.

Syntax
------
int adi_iscntrl(c)
    int c;


Description
-----------
This routine uses the language definition table to determine if c is a
control character.

adi_rqctype() must be called once before the first use of this function.

Return Value
------------
Returns a nonzero value if c is the code for a control character. Otherwise
the returned value is zero.

See Also
--------
adi_rqctype()


4.3.7 adi_isdigit
===================

Function
--------
Determines if a value represents a decimal digit.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in AutoCAD Release 12 and ADI 4.2.

Syntax
------
int adi_isdigit(c)
    int c;


Description
-----------
This routine uses the language definition table to determine if c is a
decimal digit.

adi_rqctype() must be called once before the first use of this function.

Return Value
------------
Returns a nonzero value if c is the code for a decimal digit. Otherwise the
returned value is zero.

See Also
--------
adi_rqctype()


4.3.8 adi_isgraph
=================

Function
--------
Determines if a value represents a graphic character.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in AutoCAD Release 12 and ADI 4.2.

Syntax
------
int adi_isgraph(c)
    int c;


Description
-----------
This routine uses the language definition table to determine if c is a
graphic character. A graphic character is any printing character other than
a blank.

adi_rqctype() must be called once before the first use of this function.

Return Value
------------
Returns a nonzero value if c is the code for a graphic character. Otherwise
the returned value is zero.

See Also
--------
adi_rqctype()


4.3.9 adi_islower
=================

Function
--------
Determines if a value represents a lower case character.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in AutoCAD Release 12 and ADI 4.2.

Syntax
------
int adi_islower(c)
    int c;


Description
-----------
This routine uses the language definition table to determine if c is a
lower case character.

adi_rqctype() must be called once before the first use of this function.

Return Value
------------
Returns a nonzero value if c is the code for a lower case character.
Otherwise the returned value is zero.

See Also
--------
adi_rqctype()


4.3.10 adi_isprint
====================

Function
--------
Determines if a value represents a printable character.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in AutoCAD Release 12 and ADI 4.2.

Syntax
------
int adi_isprint(c)
    int c;


Description
-----------
This routine uses the language definition table to determine if c is a
printable character.

adi_rqctype() must be called once before the first use of this function.

A blank (space) is considered a printable character.

Return Value
------------
Returns a nonzero value if c is the code for a printable character.
Otherwise the returned value is zero.

See Also
--------
adi_rqctype(), adi_isgraph()


4.3.11 adi_ispunct
====================

Function
--------
Determines if a value represents a punctuation character.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in AutoCAD Release 12 and ADI 4.2.

Syntax
------
int adi_ispunct(c)
    int c;


Description
-----------
This routine uses the language definition table to determine if c is a
punctuation character.

adi_rqctype() must be called once before the first use of this function.

Return Value
------------
Returns a nonzero value if c is the code for a punctuation character.
Otherwise the returned value is zero.

See Also
--------
adi_rqctype()


4.3.12 adi_isspace
====================

Function
--------
Determines if a value represents a whitespace character.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in AutoCAD Release 12 and ADI 4.2.

Syntax
------
int adi_isspace(c)
    int c;


Description
-----------
This routine uses the language definition table to determine if c is a
whitespace character.

adi_rqctype() must be called once before the first use of this function.

Return Value
------------
Returns a nonzero value if c a code for a whitespace character. Otherwise,
the returned value is zero.

See Also
--------
adi_rqctype()


4.3.13 adi_isupper
====================

Function
--------
Determines if a value represents an upper case character.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in AutoCAD Release 12 and ADI 4.2.

Syntax
------
int adi_isupper(c)
    int c;


Description
-----------
This routine uses the language definition table to determine if c is an
upper case character.

adi_rqctype() must be called once before the first use of this function.

Return Value
------------
Returns a nonzero value if c is the code for an upper case character.
Otherwise the returned value is zero.

See Also
--------
adi_rqctype()


4.3.14 adi_isxdigit
=====================

Function
--------
Determines if a value represents a hexadecimal digit.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in AutoCAD Release 12 and ADI 4.2.

Syntax
------
int adi_isxdigit(c)
    int c;


Description
-----------
This routine uses the language definition table to determine if c is a
hexadecimal digit. adi_isxdigit() is case insensitive.

adi_rqctype() must be called once before the first use of this function.

Return Value
------------
Returns a nonzero value if c is the code for a hexadecimal digit. Otherwise
the returned value is zero.

See Also
--------
adi_rqctype()


4.3.15 adi_rqctype
====================

Function
--------
Loads the current language definition table.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in AutoCAD Release 12 and ADI 4.2.

Syntax
------
int adi_rqctype()


Description
-----------
This routine loads an internal language definition table. The language
definition table is used to correctly internationalize CTYPE functions.

adi_rqctype() should be called before any of the CTYPE functions listed
below are used.

adi_rqctype() is new to ADI 4.2.

Return Value
------------
Returns 0 if the new table was loaded, 1 otherwise.

See Also
--------
adi_evalch(), adi_isalnum(), adi_isalpha(), adi_iscntrl(), adi_isdigit(),
adi_isgraph(), adi_islower(), adi_isprint(), adi_ispunct(), adi_isspace(),
adi_isupper(), adi_isxdigit(), adi_tolower(), adi_toupper()


4.3.16 adi_toascii
====================

Function
--------
Converts a character to ASCII.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in AutoCAD Release 12 and ADI 4.2.

Syntax
------
int adi_toascii(c)
    int c;


Description
-----------
This routine accepts any integer value and reduces it to the range of valid
ASCII characters.

adi_rqctype() must be called once before the first use of this function.

Return Value
------------
Returns c if c is already a valid ASCII code. Otherwise the value returned
discards all but the lower seven bits of c.

See Also
--------
adi_rqctype()


4.3.17 adi_tolower
====================

Function
--------
Converts a character to lower case.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in AutoCAD Release 12 and ADI 4.2.

Syntax
------
int adi_tolower(c)
    int c;


Description
-----------
This routine uses the language definition table to convert a character to
lower case.

adi_tolower() and adi_toupper() are nondestructive of already lower-case or
upper-case characters, in accordance with the ANSI C standard. This is
worth noting because some C implementations of tolower() and toupper() only
work correctly when the argument is a character of the proper case. This is
not a problem with adi_toupper() and adi_tolower().

adi_rqctype() must be called once before the first use of this function.

Return Value
------------
Returns the lower case value for c if c is a upper case letter. Otherwise c
is returned unchanged.

See Also
--------
adi_rqctype()


4.3.18 adi_toupper
====================

Function
--------
Converts a character to upper case.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in AutoCAD Release 12 and ADI 4.2.

Syntax
------
int adi_toupper(c)
    int c;


Description
-----------
This routine uses the language definition table to convert a character to
upper case.

adi_tolower() and adi_toupper() are nondestructive of already lower-case or
upper-case characters, in accordance with the ANSI C standard. This is
worth noting because some C implementations of tolower() and toupper() only
work correctly when the argument is a character of the proper case. This is
not a problem with adi_toupper() and adi_tolower().

adi_rqctype() must be called once before the first use of this function.

Return Value
------------
Returns the upper case value for c if c is a lower case letter. Otherwise c
is returned unchanged.

See Also
--------
adi_rqctype()


4.3.19 cancel
===============

Function
--------
Checks for <Ctrl-C>

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10 AutoCAD 386.

Syntax
------
int cancel()


Description
-----------
This routine is called after user input to check if a <Ctrl-C> was entered.
You may call cancel() after user input functions like yorn(), intpar(),
intparl(), or distpar() to see if <Ctrl-C> was entered.

Typically, if a <Ctrl-C> is detected during reconfiguration, the driver
should leave the old configuration intact.

Return Value
------------
Returns 1 if <Ctrl-C> was entered, returns 0 otherwise.

See Also
--------
usrbrk()


4.3.20 ciotype
================

Function
--------
Gets AutoCAD I/O port configuration. Used by plotter drivers and ADI 4.2
rendering hard copy drivers.

Limitations
-----------
Not supported in 3D Studio v1.0.

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10. Not supported by SCO
XENIX ADI 4.0. Supported by P386 ADI 4.0 and later.

Syntax
------
int ciotype(dname, iotype, iobits)
    char *dname;
    int iotype, iobits;


Description
-----------
I/O port configuration is handled by AutoCAD's internal generic plotter
configuration code. Your driver should call ciotype() to find out which
type of I/O port AutoCAD will be using.

Your driver supplies the parameters: dname, iotype, and iobits.

dname
-----
Device name string to be used in a solicitation message.

iotype
------
Default device type.

Table 4-1. Values for iotype and return values for ciotype

Mnemonic        Value  Meaning

SERIAL          1      RS-232 I/O

PARALLEL        2      Centronics parallel I/O

HPIB            4      HPIB I/O



iobits
------
Device types that can be used by the driver. The following table shows
these values:

Table 4-2. Values for iobits

Mnemonic          Value   Meaning

SERIN             0x0001  RS-232 input

SEROUT            0x0002  RS-232 output

PARIN             0x0004  Centronics parallel input

PAROUT            0x0008  Centronics parallel output

HPIBIN            0x0010  HPIB input

HPIBOUT           0x0020  HPIB output



Plotter drivers use this dispatcher function to find out which physical I/O
port the user has selected.

ADI 4.2 DEV_RH drivers must use ciotype() when being controlled by AVE
Render. However, you don't need to use ciotype() for DEV_RH devices
controlled by AutoShade or 3D Studio because these products will ask I/O
configuration questions after you return the RDETAIL packet at
configuration-time.

Likewise, you don't need to call ciotype() for P386 digitizer drivers; the
Autodesk product will ask these questions without action by your driver
(other than filling in the DETAIL packet).

Devices not supported by the user's machine will be ignored. AutoCAD will
ask the user which port the device is connected to with questions of the
form "Is your 'dname' connected to a ---- port?"

AutoCAD will take care of sending the output or fetching the input from the
proper device. Your driver should not have to talk directly to the
hardware. It should use ior(), iow(), plsend(), rhsend() and ppsend().

Return Value
------------
Returns 0 if the user canceled (<Ctrl-C>); otherwise the selected iotype.

See Also
--------
ior(), iorm(), iow(), plsend() and ppsend()


4.3.21 dispterm
=================

Function
--------
Terminates dispatcher usage.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Introduced in P386 ADI 4.1, modified in UNIX ADI 4.1 for plotters to add an
implied plflush().

Syntax
------
int dispterm()


Description
-----------
This function frees allocated buffers in the dispatcher in preparation for
termination. We recommend that dispterm() be called when a driver is told
by the Autodesk product to terminate. For example, when display drivers
receive PTERM.

The dispterm() service for UNIX plotter ADI drivers does a plflush(), frees
buffers allocated by the ADI library, writes twice on the communication
pipe, and terminates the driver with exit(0). dispterm() should be the last
function called in processing the ENDPLOT packet.

UNIX digitizer ADI drivers should call dispterm() when processing the
DGTERM packet. However, the ADI library will decide if the driver should
really exit. This is because it is possible that more than one AutoCAD may
be using the driver. The ADI library will not allow the driver to exit
until the last AutoCAD has sent DGTERM.

Return Value
------------
None.


4.3.22 distpar
================

Function
--------
Solicits a real number (often a distance in a plotter driver) from the
user.

Limitations
-----------
Not supported in 3D Studio v1.0.

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10.

Syntax
------
int distpar(real *rp; char *solmsg)


Description
-----------
This routine solicits a new value for the distance pointed to by rp with
the prompt pointed to by solmsg. The value must be >= 0.

Because distpar() solicits a distance, the prompt displayed will vary
depending on the user's selection of Units. If you need to solicit a
decimal real number unaffected by Units, use mscanr() instead.

Return Value
------------
The result is in rp, the return value is always OK and can be ignored.

See Also
--------
intpar(), intparl(), mscanr()


4.3.23 errbeep
================

Function
--------
Sounds bell on error.

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10. Not supported in XENIX
ADI 4.0. Supported in P386 ADI 4.0 and later

Syntax
------
int errbeep()


Description
-----------
Errbeep sounds the console bell if the audible alarm option is on.

Return Value
------------
Errbeep() always returns 0.


4.3.24 getcdname
==================

Function
--------
Returns the current drawing name.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10. Not supported in XENIX
ADI 4.0, P386 ADI 4.1 or UNIX ADI 4.1. Supported ADI 4.2 on all platforms.

Syntax
------
int getcdname(drawname)
    char *drawname;


Description
-----------
Returns a pointer to a string containing the current drawing name in
drawname. The null-terminated string's length will be less than 256
characters.

Return Value
------------
Returns OK if successful, return ERR otherwise


4.3.25 getplrec
=================

Function
--------
Gets a stored, customizable plotter configuration record.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in ADI 4.2.

Syntax
------
int getplrec(len, rec)
    int len;
    char *rec;


Description
-----------
Your plotter driver may store and retrieve any customizable parameters with
saveplrec() and getplrec(). These data are stored in acad.cfg with the
plotter device-specific record. The record may be up to 50 bytes long.

It is not reasonable to call getplrec() if your driver has not stored a
record of the correct length with saveplrec().

Return Value
------------
Returns OK on success, ERR otherwise.

See Also
--------
saveplrec()


4.3.26 getrec
===============

Function
--------
Gets a stored customizable digitizer configuration record.

Limitations
-----------
This service is provided only for digitizer drivers. Display and rendering
drivers are sent packets which accomplish a similar purpose. Plotter
drivers use getplrec(). The contents of this configuration record are
meaningless to AutoCAD.

Not supported by 3D Studio v1.0

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10.

Syntax
------
int getrec(len, rec)
    int len;
    char *rec;


Description
-----------
Your digitizer driver may store and retrieve any customizable parameters
with saverec() and getrec(). It is saved in acad.cfg in the digitizer
device-specific record.

This routine asks AutoCAD to retrieve the configuration record for this
device, of length len and put it into a buffer pointed to by rec.

Although your driver can call getrec() at any time, often it is not obvious
whether the driver should get its information from default values stored in
the driver or from the configuration record stored by AutoCAD.

For example, if the user had previously configured for another make of
digitizer and then wanted to configure for your device, it would be unwise
to load the configuration record of your competitor's driver.

Even though none of the information packets tell you whether it is new or
not, there is a subtle way to determine whether the contents of the driver
definable configuration record belongs to you. To do this, check the return
value from getrec(). A return value of ERR means that there was no
previously stored configuration information. A return value of OK means
that the driver has retrieved information it stored previously.

To explain this a bit more, whenever a new digitizer is configured (as
distinct from reconfiguring the existing model), a flag is cleared in
AutoCAD's internal configuration record to indicate that any record saved
with saverec() is no longer valid. Then, if you do a getrec() for a newly
configured device before doing saverec(), you will get a return value of
ERR to warn you that no record has been stored yet.

Return Value
------------
Returns OK is a valid record was retrieved, otherwise returns ERR.

See Also
--------
saverec()


4.3.27 intpar
===============

Function
--------
Solicits an integer value from the user.

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10.

Syntax
------
int intpar(solmsg, nump, ulim)
    char *solmsg;
    int *nump, ulim;


Description
-----------
The intpar() function solicits a new value for the integer parameter
pointed to by nump with the prompt message pointed to by solmsg. The value
must be greater than or equal to zero and less than or equal to ulim. If
<Ctrl-C> is hit, nump is unmodified. You should call cancel() after
intpar() to detect <Ctrl-C>.

Return Value
------------
The result is in *nump, the function's return value is always OK and isn't
meaningful.

See Also
--------
cancel(), distpar(), intparl()


4.3.28 intparl
================

Function
--------
Solicits an integer value from the user.

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10.

Syntax
------
int intparl(solmsg, llim, ulim, nump)
    char *solmsg;
    int llim, ulim, *nump;


Description
-----------
Solicits a new value for integer parameter "*nump" with solmsg. Value must
be >= llim and <= ulim. If <Ctrl-C> is hit, nump is unmodified. You should
call cancel() after intparl() to detect <Ctrl-C>.

Notice the only difference between intpar() and intparl() is the value must
be greater than or equal to 0 for intpar() and greater than or equal to
llim for intparl().

Return Value
------------
The result is in *nump, the function's return value is always OK and isn't
meaningful.

See Also
--------
cancel(), distpar(), intpar()


4.3.29 invrsp
===============

Function
--------
Solicits a general purpose error message.

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10.

Syntax
------
int invrsp()


Description
-----------
This routine displays the general purpose error message: "Invalid
response."


4.3.30 ior
============

Function
--------
Reads a byte from the plotter or digitizer I/O port.

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10. Not supported for SCO
XENIX ADI 4.0. Supported by P386 ADI 4.0 and later.

Syntax
------
int ior(port, timeout)
    char port;
    int timeout;    /* timeout in milliseconds */

Description
-----------
ior() reads a byte from the port or returns if timeout occurs. You specify
either the digitizer or plotter port by the code in the port parameter. The
possible values for port are #defined in plp.h and dgp.h as the tags DG or
PL (the driver can be either a DEV_DG or DEV_PL).

A timeout value of zero implies reading the port once and returning with no
retry. On a slow CPU, multiple ior() calls can produce incomplete samples;
iorm() should be used instead for multibyte samples.

Because of platform inconsistencies in reading input from parallel ports,
ior() is not supported for devices configured for a parallel port.

See the discussion of the DETAIL packet for digitizers and plotters for a
discussion of how handshaking is handled on various platforms.

Return Value
------------
ior() returns the byte read or -1 if no data is read within the time
specified by timeout.


4.3.31 iorm
=============

Function
--------
Requests multibyte input from the digitizer device.

History
-------
Introduced in P386 ADI 4.0 for AutoCAD Release 10 386. Support for UNIX
platforms was added in ADI 4.2.

Syntax
------
int iorm(timeout, len, data)
    int timeout, len;
    char *data;


Description
-----------
iorm() requests a multibyte input string of length len from the digitizer
device. An iorm() request is faster than multiple ior() requests.

The timeout value in this function represents the timeout that will be
applied to each character, not the entire multibyte string. Thus, if each
character takes nearly timeout milliseconds to arrive, iorm() will not
return until nearly (timeout * len) milliseconds have elapsed.

If the correct number of characters are collected with no timeout, the data
are placed in the location specified by *data. If a timeout occurs on any
byte of the requested string, the operation is terminated and the string is
not copied.

See the DETAIL packet for digitizers and plotters for information on how
handshaking is handled.

Return Value
------------
The iorm() function returns OK upon success and ERR if the routine is
unsuccessful.


4.3.32 iormrc
===============

Function
--------
Requests the contents of the Windows serial buffer which is used for
digitizer input.

Limitations
-----------
This service is only available on Windows.

History
-------
Introduced in Windows ADI 4.1 for AutoCAD Release 11.

Syntax
------
int iormrc (timeout, len, data)
    int timeout;    /* timeout in milliseconds */
    int len;        /* maximum number of bytes to read */
    char *data;


Description
-----------
This routine reads characters from the Windows serial buffer which is used
for digitizer input. It returns the number of character read, up to a
maximum of toread characters. If the Windows serial buffer is empty, the
function will wait for timeout milliseconds before giving up. A return
value of -1 indicates timeout with nothing read. The characters read are
copied into the buffer data.

This service was added to improve Windows performance with streaming mode
digitizers. It allows Windows ADI drivers to perform local buffering to
minimize dispatcher/Windows requests.

Return Value
------------
If timeout occurs, -1 is returned; otherwise the number of characters that
were copied into the data parameter is returned.


4.3.33 iormt
==============

Function
--------
Reads multiple bytes from a digitizer or plotter.

Limitations
-----------
Not supported in 3D Studio v1.0 or v2.0.

History
-------
Added in ADI 4.2.

Syntax
------
int iormt(port, timeout, length, buffer)
    char port;    /* DG or PL */
    int timeout;  /* timeout in milliseconds */
    int len;      /* maximum number of bytes to read */
    char *buffer;

Description
-----------
iormt() requests a multibyte input string of up to length len from a
digitizer or plotter. iormt() returns upon timeout or after len bytes are
read, depending upon which occurs first. Unlike iorm(), the partial result
string is returned if fewer than len bytes are read. The timeout value is
the timeout applied for each individual character read.

A timeout value of 0, can be used to disable the timeout mechanism. If
disabled, iormt() returns as soon as len bytes are read or there are no
more characters available from the port.

iormt() is faster than multiple ior() requests. On slow CPU's, this can
help prevent dropping characters when multiple bytes need to be read.

Return Value
------------
Returns the number of bytes read.


4.3.34 iow
============

Function
--------
Writes to the I/O port.

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10. Not supported for SCO
XENIX ADI 4.0. Supported by P386 ADI 4.0 and later. setpltmout() was added
in ADI 4.2.

Syntax
------
int iow(port, data)
    char port, data;


Description
-----------
iow() sends data to the port, which may be DG, PL or PLF. PLF is useful for
binary plot-to-file. The tags PL, DG and PLF are #defined in dgp.h and
plp.h.

This is a logical subset of ppsend(). In the UNIX plotter ADI library,
iow() is simply redirected through ppsend().

Use of this function on UNIX platforms is not recommended. It will not be
supported in future versions of UNIX plotter ADI. Use ppsend() instead.

See the discussion of the DETAIL packet for digitizers and plotters for a
discussion of how handshaking is handled on various platforms.

Return Value
------------
The iow() function returns -1 on error.

See Also
--------
plsend(), ppsend(), setpltmout()


4.3.35 mgerr
==============

Function
--------
Calls errbeep() and terminates active script.

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10.

Syntax
------
int mgerr()


Description
-----------
This routine calls errbeep() and then terminates any active AutoCAD script.


4.3.36 mgetch
===============

Function
--------
Reads keyboard input one character at a time.

Limitations
-----------
Not supported in 3D Studio v1.0 or v2.0. mgetch() is not usable during the
AutoCAD Release 12 plot dialogue. mgetch() does not check for <Ctrl-C>. If
the user pressed <Ctrl-C>, mgetch() will return <Ctrl-C>. In other words,
you can't use cancel() or usrbrk() to learn if <Ctrl-C> was set in response
to mgetch(), your code must check the return value from mgetch() instead.

History
-------
Added in ADI 4.2

Syntax
------
int mgetch()


Description
-----------
Allows an ADI driver to read keyboard input one keystroke at a time without
waiting for a carriage return.

Returns the character read or 0 if a plot dialogue box is active.

On the P386 platform, if an extended character is read, the lower eight
bits of the return value will contain a null character and bits 8 - 15 will
contain the extended key code. For example, if a user pressed the left
arrow key, the lower 8 bits of the return value would contain a null
character and bits 8 - 15 would contain 0x4B.

mgetch() does not check for <Ctrl-C>. If the user pressed <Ctrl-C>,
mgetch() will return <Ctrl-C>. In other words, you can't use cancel() or
usrbrk() to learn if <Ctrl-C> was set in response to mgetch(), your code
must check the return value from mgetch() instead.

On P386 platforms, the mgetch() return value corresponds to the value
returned from INT 21h function 6. Refer to a MS-DOS or IBM-PC reference
manual for more information on the PC's extended characters. Also, please
note that mgetch() will never return <Ctrl-Q> (0x11) to the caller. AutoCAD
uses <Ctrl-Q> internally.

Here is a sample of some the extended key codes mgetch() returns in bits 8
- 15 on the P386 platform.

Table 4-3. mgetch() extended keycodes (bits 8-15)

Key                Decimal Code

Home               71

Up Arrow           72

PgUp               73

Left Arrow         75

Right Arrow        77

End                79

Down Arrow         80

PgDn               81

Ins                82

Del                83

F1                 59

F2                 60

F3                 61

F4                 62

F5                 63

F6                 64

F7                 65

F8                 66

F9                 67

F10                68



On the SPARC platforms mgetch() will return the following codes in the
lower 8 bits of the return value for these extended keys.

Table 4-4. mgetch() extended keycodes (bits 0-7)

Key                Decimal Code

Home               135

Up Arrow           133

PgUp               137

Left Arrow         131

Right Arrow        132

End                136

Down Arrow         134

PgDn               138

Ins                139

Del                8

F2                 4

F3                 7

F4                 15

F5                 2

F6                 20

F7                 5

F8                 11

F9                 14



Return Value
------------
Returns the character read or 0 if a plot dialogue box is active.


4.3.37 more
=============

Function
--------
Enables AutoCAD's more mode.

Limitations
-----------
Not supported in 3D Studio v1.0 or v2.0.

History
-------
Added in ADI 4.2.

Syntax
------
int more(nLines)
    int nLines;


Description
-----------
Allows an ADI driver to configure AutoCAD's more mode. When AutoCAD is in
more mode, it prompts the user to press return after nLines of text have
been printed.

ADI drivers should disable more mode by calling nomore() when the driver no
longer needs more mode enabled.

Return Value
------------
Returns AutoCAD's current more setting.

See Also
--------
nomore()


4.3.38 mprintf
================

Function
--------
Minimal printf().

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10.

Syntax
------
int mprintf(fmt, ...)
    char *fmt;


Description
-----------
This routine is a minimal printf(), useful for putting messages onto the
screen (especially at configuration time). This mprintf() is a subset of
the familiar C language printf(). It recognizes only the following formats:
%d, %u, %s, and %ld. Only one format specification will be honored in each
mprintf() request.


4.3.39 mscani
===============

Function
--------
Reads user input and looks for an integer.

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10.

Syntax
------
int mscani(num)
     int *num;


Description
-----------
This routine accepts user input and scans for a base 10 integer. If an
integer is found, it is returned in *num.

Return Value
------------
Returns 1 if a decimal integer is found, 0 otherwise.


4.3.40 mscanr
===============

Function
--------
Reads user input and looks for a real number.

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10.

Syntax
------
int mscanr(num)
    real *num;


Description
-----------
This routine accepts user input and scans for a real number. If a real
number is found, the number is returned in *num.

Return Value
------------
Returns 1 if a real number is found, 0 otherwise.


4.3.41 mscans
===============

Function
--------
Accepts user input and looks for a string.

Limitations
-----------
The is a bug in AutoCAD Release 12 which makes mscans() useless during plot
dialogues. Not supported in 3D Studio v1.0. cancel() cannot be used to
detect <Ctrl-C> after mscans(). You must examine the string returned by
mscans() to see if <Ctrl-C> was struck.

History
-------
Introduced in P386 ADI 4.1.

Syntax
------
int mscans(buf)
    char *buf;


Description
-----------
This routine accepts user input and looks for a string. Strings are
terminated by a carriage return (<CR>) or the space bar.

The string, if any, is returned in "*buf". The string's length can not
exceed 256 characters.

Return Value
------------
Returns 1 if OK, 0 otherwise.

See Also
--------
mgetch()


4.3.42 msysint32
==================

Function
--------
System call. Available on 386 platforms only.

History
-------
Introduced in P386 ADI 4.1.

Syntax
------
int msysint32(sysint, regsin, regsout)
    int sysint;      /* interrupt number */
    mregs *regsin;   /* reg values on entry */
    mregs *regsout;  /* reg values on exit  */


Description
-----------
This routine performs the system call specified by sysint, which contains
the interrupt number to be called. Any parameters to be passed to the
system function should be placed in *regsin. Any return data from the
system function will be returned in *regsout.

Both *regsin and *regsout are pointers to a structure, mregs, which is
defined as follows:

typedef struct mregs {
    union {
        unsigned char half[2]; /* to store al and ah */
        unsigned int x;        /* or store ax or eax */
   } a, b, c, d;                /* declare registers */
    unsigned int esi;
    unsigned int edi;
    unsigned int ds;
    unsigned int es;
};


Although the mregs struct has members for ds and es, msysint32() actually
only passes eax, ebx, ecx, edx, esi and edi into the INT request. All of
these registers and es and ds are returned as results. INT 25h and INT 26h
are not supported.

It is desirable to use msysint32() instead of directly calling DOS
functions because msysint32() takes care of critical error handling and
other housekeeping.

The mregs struct is defined in msysregs.h.


4.3.43 nomore
===============

Function
--------
Disables AutoCAD's more mode.

Limitations
-----------
Not supported in 3D Studio v1.0 or v2.0.

History
-------
Added in ADI 4.2

Syntax
------
int nomore()


Description
-----------
Allows an ADI driver to disable AutoCAD's more mode.

ADI drivers should disable more mode by calling nomore() when the driver no
longer needs more mode enabled.

For example:

more(5);           /* prompt user every 5 lines */

mprintf();

mprintf();
...

nomore();


Return Value
------------
Always returns 0.

See Also
--------
more()


4.3.44 nultrm
===============

Function
--------
Detects a zero length input response from the user, i.e., the user pressed
RETURN to accept the default value offered.

Limitations
-----------
Not supported in 3D Studio v1.0.

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10.

Syntax
------
int nultrm()


Description
-----------
This routine detects a null term: len(inputbuffer) == 0 and line not
canceled. The user is presumed to be taking some default action.

nultrm() is useful after functions like yorn(), intpar(), intparl(), or
distpar(). A prerelease version of the P386 ADI ToolKit for AutoCAD Release
10 documented a similar function, eos(). eos() was removed from both the
service module library and the documentation since nultrm() serves the same
purpose.

Return Value
------------
Returns 1 if the user accepts the default, returns 0 otherwise.


4.3.45 plflush
================

Function
--------
Forces buffered plotter output to be sent to the plotter.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in UNIX ADI 4.1 for AutoCAD Release 11.

Syntax
------
void plflush()


Description
-----------
This service flushes data buffered by the ppsend() command in UNIX ADI. You
should call plflush() whenever you want to be sure that data sent through
ppsend() has actually been sent. The size of the buffer is platform-
dependent and subject to change. Do not develop code that expects any
particular data buffer size.

For ADI 4.2 DEV_RH drivers, plflush() also flushes any buffered rendering
hardcopy output data. dispterm(), plseek(), and pltell() do an implied
plflush() for UNIX plotter ADI. In P386 ADI, plflush() does nothing.

Return Value
------------
There is no return value.

See Also
--------
ppsend() plseek() pltell() rhsend() dispterm()


4.3.46 plseek
===============

Function
--------
Moves the file pointer of the currently open plot file to a specified
offset within the file.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in ADI 4.2.

Syntax
------
int plseek(offset)
    long offset;

Description
-----------
Allows an ADI plotter driver that is plotting to file (via plsend() or
ppsend()) to position the file pointer. An example of this function's use
would be writing data in the header of a file after the body of the file
has been written (see plpost.c for another example)

If offset is negative, the file pointer is positioned (offset+1) bytes
relative to the end of the file. For example, a plseek(-1L) positions the
file pointer at the end of the file, and a plseek(-10L) positions the file
pointer 9 bytes from the end of the file.

For ADI 4.2 DEV_RH drivers which output to a file, plseek() changes the
position of the currently open "render-to-file" output file pointer.

plseek() does an implied plflush().

Return Value
------------
plseek() passes on the return value of the underlying fseek(), 0 if
successful, non-zero if not.

See Also
--------
pltell()


4.3.47 plsend
===============

Function
--------
Sends character string to a port or file.

Limitations
-----------
Use of this function on UNIX platforms is not recommended. It will not be
supported in future versions of UNIX plotter ADI. This function is not
supported by 3D Studio. You should use ppsend() instead.

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10. Modified for UNIX
platforms in ADI 4.1 by redirection through ppsend(). setpltmout() was
added in ADI 4.2

Syntax
------
int plsend(c)
    char *c;


Description
-----------
This routine sends a null-terminated character string to the plotter.
AutoCAD redirects output to a file if the user requests it.

This is a logical subset of ppsend(). In the UNIX plotter ADI library,
plsend() is simply redirected through ppsend().

See the discussion of the DETAIL packet for digitizers and plotters for a
discussion of how handshaking is handled on various platforms.

See Also
--------
ppsend(), iow(), setpltmout()


4.3.48 pltell
===============

Function
--------
Returns the current position of the file pointer of the currently open plot
file.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in ADI 4.2.

Syntax
------
long pltell()


Description
-----------
This function returns the position of the file pointer for the currently
open "plot-to-file" output file, while plseek() moves the file pointer to a
specified position in the plot-to-file output file.

For ADI 4.2 DEV_RH drivers which output to a file, pltell() provides the
position of the currently open "render-to-file" output file.

pltell() does an implied plflush().

The sample driver plpost uses plseek() and pltell().

Return Value
------------
Returns the position of the file pointer.

See Also
--------
plseek()


4.3.49 ppsend
===============

Function
--------
Sends binary data to port or file.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Introduced in ADI 4.1. In ADI 4.2 support was added for the XON/XOFF flow
control option. A related function, setpltmout() was added to allow drivers
to change the timeout value and to modify the application's behavior on
timeout.

Syntax
------
int ppsend(numbytes, buf)
    int numbytes;
    char * buf;


Description
-----------
This routine accepts binary data and sends it to the currently configured
plotter (or printer) port. If the user has selected plot-to-file, the data
from ppsend() will be redirected to the file selected by the user. If you
allowed the user to select either a serial or parallel interface, ppsend()
will direct the output to the proper port.

A fatal error occurs if no printer port has been configured.

The ppsend() function will display an error message if the device is off-
line, out of paper, etc., and will offer the user a choice of retrying or
aborting.

If 0 is returned by ppsend(), your driver should return to the Autodesk
product as soon as possible-- there was a fatal printer error or no printer
port was configured. Don't bother to retry, just clean up for exit and
return.

Under Phar Lap (but not UNIX), prior to ADI 4.2 any drivers calling
ppsend() automatically had hardware handshaking imposed on their flow
control. In other words, a Phar Lap plotter driver being controlled by a
pre-ADI 4.2 product will get hardware handshaking with this function
regardless of the value set in the handshake element of the DETAIL packet.
In ADI 4.2 support for the XON/XOFF flow control option was added.

Hardware handshaking is accomplished under Phar Lap by monitoring the
voltage on pin #6 (DSR). When that pin is asserted, data will flow out the
transmit pin from AutoCAD to the hardware device. When DSR is not asserted,
data flow will cease.

Unlike P386 hardware flow control which monitors pin number 6 (DSR), UNIX
flow control monitors pin number 5 (CTS). When CTS is asserted (a positive
voltage) the serial port will send data out the transmit pin. Otherwise, a
negative voltage stops data transmission.

Unfortunately, not all UNIX serial I/O hardware and software supports
hardware handshaking. Therefore Autodesk cannot guarantee hardware
handshaking for ADI on all UNIX platforms. The sample code for hardware
handshaking was tested on a Sun SPARC 1+ with a Zilog 8530 SCC chip.

See sample source code files plep.c and plpoki.c for example usage of
ppsend().

Return Value
------------
Returns 1 if successful, 0 otherwise.

See Also
--------
setpltmout(), plsend(), iow()


4.3.50 recfgport
==================

Function
--------
Allows execution-time reconfiguration of a serial port.

History
-------
Introduced in ADI 4.2.

Limitations
-----------
recfgport() is not available on Windows, and not supported by 3D Studio.

Syntax
------
int recfgport(idvc, iotype, baudrate, parity,
          databits, stopbits, hhflag)

int idvc, iotype, baudrate, parity,
          databits, stopbits, hhflag;


Description
-----------
This service allows the I/O parameters for a digitizer or plotter to be
reconfigured at XQT time. The arguments of recfgport are similar to those
used in the DETAIL packet:

Table 4-5. recfgport() parameters

Parameter      Arguments

idvc           Device type: DG or PL

iotype         SERIAL or PARALLEL

baudrate       Literal baud rate e.g., 9600, 1200, etc.

parity         NONE, ODD, EVEN, MARK or SPACE

databits       Number of data bits e.g., 7

stopbits       Number of stop bits e.g., 1 or 2

hhflag         0 for Xon/Xoff, 1 for hardware handshaking



4.3.51 rhsend
===============

Function
--------
Sends binary rendering hardcopy data to port or file.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Introduced in ADI 4.2.

Syntax
------
int rhsend(idvc, numbytes, buf)
    int idvc;
    int numbytes;
    char *buf;


Description
-----------
This routine accepts binary data and sends it to the rendering hardcopy
port associated with idvc. The driver gets this idvc value in a RDRHOPEN
packet. If the user has selected render-to-file, the data from rhsend()
will be directed to the file selected by the user. If you allowed the user
to select either a serial or parallel interface, rhsend() will direct the
output to the proper port.

A fatal error occurs if no rendering hardcopy port has been configured.

The rhsend() request may be made only between a set of RDRHOPEN and RDEND
bookend packets. Outside these times, rhsend will fail.

The rhsend() function will display an error message if the device is off-
line, out of paper, etc., and will offer the user a choice of retrying or
aborting.

The timeout value for giving up on retries of a busy port is modifiable by
setpltmout().

On UNIX platforms, rhsend() is buffered just like plsend(). plflush() will
flush the rhsend() buffer. In fact, rhsend() and plsend() use the same data
buffer. Thus, if rhsend() calls have been made and a plsend call is made,
the dispatcher library code will flush all of the rhsend() data and start
collecting plsend() data. Likewise, if plsend() has been recently used and
rhsend() is invoked, this does an implied plflush() so that the plotter
data can be sent off to the correct port and rhsend() data may be
accumulated for transmission to the configured rendering hardcopy port.

The services plseek() and pltell() will operate on rhsend() output to a
file.

If 0 is returned by rhsend(), your driver should return to the Autodesk
product as soon as possible-- there was a fatal printer error or no printer
port was configured. Don't bother to retry, just clean up for exit and
return.

rhsend() uses the flow control method specified by the driver in RDETAIL.
Both XON/XOFF and hardware handshaking are supported.

Hardware handshaking is accomplished under Phar Lap by monitoring the
voltage on pin #6 (DSR). When that pin is asserted, data will flow out the
transmit pin from AutoCAD to the hardware device. When DSR is not asserted,
data flow will cease.

Unlike P386 hardware flow control which monitors pin number 6 (DSR), UNIX
flow control monitors pin number 5 (CTS). When CTS is asserted (a positive
voltage) the serial port will send data out the transmit pin. Otherwise, a
negative voltage stops data transmission.

Unfortunately, not all UNIX serial I/O hardware and software supports
hardware handshaking. Therefore Autodesk cannot guarantee hardware
handshaking for ADI on all UNIX platforms. The sample code for hardware
handshaking was tested on a Sun SPARC 1+ with a Zilog 8530 SCC chip.

See sample source code file rhppj.c for example usage of rhsend().

Return Value
------------
Returns 1 if successful, 0 otherwise.

See Also
--------
setpltmout(), plflush(), pltell() and plseek()


4.3.52 saveplrec
==================

Function
--------
Stores a customizable plotter configuration record.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Added in ADI 4.2.

Syntax
------
int saveplrec(lev, rec)
    int len;
    char *rec;


Description
-----------
saveplrec allows a plotter driver to save a driver-unique configuration
record of up to 50 bytes at any point during CFG-time configuration or
during execution-time configuration up until the time when AutoCAD writes
out the configuration record to acad.cfg.

Return Value
------------
Returns OK if successful, ERR otherwise.

See Also
--------
getplrec()


4.3.53 saverec
================

Function
--------
Stores a customizable digitizer configuration record.

Limitations
-----------
This service is provided only for digitizer drivers. Display, rendering and
plotter drivers are sent packets which accomplish a similar purpose. The
saverec() function may be safely used only at configuration time. Writing
into the configuration record at execution time may fail.

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10.

Syntax
------
int saverec(len, rec)
    int len;
    char *rec;


Description
-----------
Your digitizer driver may store and retrieve any information with saverec()
and getrec(). These two routines access the digitizer device-specific
record.

This routine asks the controlling product to access the configuration
record for this device, of length len, using a buffer pointed to by rec.

This configuration record must be 450 bytes or less.

See Also
--------
getrec()


4.3.54 setpltmout
===================

Function
--------
Sets the timeout value used by ppsend(), plsend(), rhsend(), and iow().

History
-------
Added in AutoCAD Release 12 and ADI 4.2.

Syntax
------
int setpltmout(timeout, prompt)
    int timeout;
    int prompt;

Description
-----------
A driver can use the function to change the default timeout used by AutoCAD
when it executes the ppsend(), rhsend(), plsend(), and iow(), functions.
This may be useful for devices that need additional time to process
AutoCAD's output.

The values for the timeout and prompt parameters that your driver supplies
are listed in the following tables:

Table 4-6. setpltmout() timeout parameter

Value        Meaning

> 0          Sets a new timeout value

= 0          Sets an infinite timeout period

< 0          timeout value is not changed



The timeout value set by this function will not affect iow() calls for
digitizers. A driver should save the original timeout value so that it can
be restored after the plot is complete.

Table 4-7. prompt parameter

Value       Meaning

> 0         AutoCAD prompts user in the event of a timeout. User given a
chance to abort the plot.

= 0         AutoCAD will not prompt the user on timeout. AutoCAD cancels
the plot.



Return Value
------------
Returns the previous timeout value.

See Also
--------
ppsend(), plsend(), and iow().


4.3.55 usrbrk
===============

Function
--------
Checks keyboard buffer for <Ctrl-C>.

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10. Not supported for SCO
XENIX ADI 4.0 or P386 ADI 4.0. Supported by all ADI 4.1 platforms and
later.

Syntax
------
int usrbrk()


Description
-----------
Usrbrk checks the keyboard buffer to see if <Ctrl-C> has been entered.

Unlike cancel(), it does not have to be called right after you
intentionally solicit input. usrbrk() is useful for detecting panic exits
during hardcopy output.

Return Value
------------
Returns TRUE (1) if <Ctrl-C> was detected, FALSE (0) if not.

See Also
--------
cancel()


4.3.56 yorn
=============

Function
--------
Gets yes or no response.

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10.

Syntax
------
int yorn(question, dfltans)
    char *question;
    int dfltans;         /* default answer */


Description
-----------
This routine solicits a yes or no answer to a question.

char *question
--------------
Pointer to the question string. The Autodesk product supplies the question
mark.

int dfltans
-----------
This value determines the behavior of the question:

Table 4-8. yorn() dfltans parameter

Value       Meaning

1           Default yes answer

0           Default no answer

-1          No default answer



Return Value
------------
Returns TRUE (1) for yes, FALSE (0) for no. Returns FALSE if <Ctrl-C> is
entered in response.


4.4 Obsolete Dispatcher File I/O Functions
==========================================

This section contains dispatcher functions which you should not need to use
for any new driver development, and may eventually become unsupported by
the ADI specification. They were originally plot-to-file support functions
and have been replaced by plsend(), ppsend(), iow(), and ior(). The
descriptions are provided for compatibility with existing ADI drivers.

4.4.1 alert (obsolete)
======================

Function
--------
Puts up an alert box.

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10. Used in Windows ADI 4.1.
Not supported in any later ADI version or on any other platform.

Syntax
------
int alert(message)
    char *message;


Description
-----------
Puts up an alert box with the message. Returns after the user acknowledges
the alert.

On unsupported platforms (e.g., 386 and SPARC), this will put up an alert
box but will disable the mouse while the alert is up - use on these
platforms is not recommended.

Return Value
------------
none (always returns 0)


4.4.2 dlfname (obsolete)
========================

Function
--------
Displays a dialogue box for getting a file name.

Limitations
-----------
Not supported in 3D Studio v1.0 or v2.0.

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10. Used in Windows ADI 4.1.
Not supported by any later ADI version or platform.

Syntax
------
int dlfname(title, default, type, flags)
    char *title, *default, *type;
    int flags;


Description
-----------
This function will put up a dialogue box to solicit a file name for you.
See dlldefs.h for more details.

These are the parameters that you must supply:

char *title
-----------
This is the prompt string (e.g., "Select file name").

char *default
-------------
This is the default file name (often cdname).

char *type
----------
This is the file type (three letter extension), such as DWG, PLT, etc.

int flags
---------
The value supplied in flags indicates the following:

Table 4-9. Values for flags parameter

Mnemonic        Value                   Meaning

DLFPUT          0x1   New file

DLFDWG          0x2   Want a dwg file

DLFINSIST       0x4   Don't allow default or cancel

DLFANYEXT       0x20  Accept any extension



Here is an example of dlfname() usage:

getcdname(cdname);                /* establish default */

i = dlfname("Select file name",cdname,"DAT",DLFPUT);

if (i == UDS_DISMISS) {
  put your code here to prompt user directly for file name (no dialogue
box)
  (probably using printfcd())
}


Return Value
------------
If dialogue successfully selects a file, it stuffs its expanded name into
tbfr. The return values are shown in the following table:

Table 4-10. Return values for dlfname()

Mnemonic         Value                         Meaning

UDS_NORMAL       0    A filename is returned in ptext[]

UDS_NULL         -1   Null response

UDS_CANCEL       -4   User canceled dialogue, no filename returned

UDS_DISMISS      -10  User dismissed dialogue



4.4.3 printfcd (obsolete)
=========================

Function
--------
Prints default filename.

Limitations
-----------
This function should only be used if you can't use plsend() or iow(), and
it may be dropped in a future version of P386 ADI. This function is not
supported by 3D Studio.

History
-------
Introduced in OS/2 ADI 4.0.

Syntax
------
int printfcd(c)
    char *c


Description
-----------
This routine is a support function for a plot-to-file. It prints a string,
substituting the current default filename for %s. Thus, if the current
default filename is blarg.plt, the statement

printcd("Enter filename for plot <%s>:");


displays:

Enter filename for plot
<blarg.plt>:.


Autodesk convention puts the current default value for a parameter in angle
brackets.

See Also
--------
plsend(), iow()


4.4.4 ffopenasc (obsolete)
==========================

Function
--------
Opens a file for ASCII plot-to-file.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Introduced in OS/2 ADI 4.0.

Syntax
------
int ffopenasc()


Description
-----------
This routine is a support function for a plot-to-file. It opens a file with
the filename in tbfr plus the extension .plt for ASCII output ("w").

Use this function only if you can't use plsend() or iow(). This function
may be dropped in a future version of P386 ADI.

Return Value
------------
Returns 0 on success.

See Also
--------
plsend(), iow()


4.4.5 ffopenbin (obsolete)
==========================

Function
--------
Opens a file for binary plot-to-file.

Limitations
-----------
Not supported in 3D Studio v1.0 or v2.0.

History
-------
Introduced in OS/2 ADI 4.0

Syntax
------
int ffopenbin()


Description
-----------
This routine is a support function for a plot-to-file. It opens a file with
the filename in tbfr plus the extension .plt for binary output ("wb").

Use this function only if you can't use plsend() or iow(). This function
may be dropped in a future version of P386 ADI.

Return Value
------------
Returns 0 on success.

See Also
--------
plsend(), iow()


4.4.6 ffopendxb (obsolete)
==========================

Function
--------
Opens a file for dxb format plot-to-file.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Introduced in OS/2 ADI 4.0.

Syntax
------
int ffopendxb()


Description
-----------
This routine is a support function for a plot-to-file. It opens a file with
the filename in tbfr plus the extension .dxb for binary output ("wb").

Use this function only if you can't use plsend() or iow(). This function
may be dropped in a future version of P386 ADI.

Return Value
------------
Returns 0 on success.

See Also
--------
plsend(), iow()


4.4.7 strcpycd (obsolete)
=========================

Function
--------
Copies default filename to buffer.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Introduced in OS/2 ADI 4.0.

Syntax
------
int strcpycd()


Description
-----------
This routine is a plot-to-file support function. It copies cdname (current
default filename) into the AutoCAD local buffer, tbfr.

Use this function only if you can't use plsend() or iow(). This function
may be dropped in a future version of P386 ADI.

Return Value
------------
There is no return value (always 0).


4.4.8 getdat0 (obsolete)
========================

Function
--------
Gets input string and places into local buffer.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Introduced in OS/2 ADI 4.0.

Syntax
------
int getdat0()


Description
-----------
This routine is a plot-to-file support function. It reads an input string
from the user and places it in the AutoCAD local buffer tbfr.

Use this function only if you can't use plsend() or iow(). This function
may be dropped in a future version of P386 ADI.

Return Value
------------
There is no return value (always 0).


4.4.9 mfprintf (obsolete)
=========================

Function
--------
Sends output to a file.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Introduced in OS/2 ADI 4.0.

Syntax
------
int mfprintf(fmt, ...)
    char *fmt;


Description
-----------
This routine is a plot-to-file support function. It is used in ASCII plot-
to-file and works like mprintf(), but sends its output to the currently
open file, which was opened with ffopenasc().

Use this function only if you can't use plsend() or iow(). This function
may be dropped in a future version of P386 ADI.

Return Value
------------
There is no return value.


4.4.10 mfclose (obsolete)
=========================

Function
--------
Closes a file opened with one of the ffopen() commands.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Introduced in OS/2 ADI 4.0.

Syntax
------
int mfclose()


Description
-----------
This routine is a plot-to-file support function. It closes the file opened
with one of the ffopen commands listed in the obsolete dispatcher functions
listing.

Use this function only if you can't use plsend() or iow(). This function
may be dropped in a future version of P386 ADI.

Return Value
------------
There is no return value.


4.4.11 mfwrite (obsolete)
=========================

Function
--------
Writes from a buffer to the current open file.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Introduced in OS/2 ADI 4.0.

Syntax
------
int mfwrite(&buf, size)


Description
-----------
This routine is a plot-to-file support function, used for binary format
plot-to-file writes. It writes size bytes from buffer buf to the currently
open file, which was opened with one of the ffopen() commands listed in
this section.

Use this function only if you can't use plsend() or iow(). This function
may be dropped in a future version of P386 ADI.


4.4.12 fncasetb (obsolete)
==========================

Function
--------
Converts a filename to the correct case for the operating system.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Introduced in OS/2 ADI 4.0.

Syntax
------
int fncasetb()


Description
-----------
This routine converts the filename in tbfr to the correct case for the
operating system in use. For MS-DOS, this converts the filename to upper
case.

You should not have to use this function. This function may be dropped in a
future version of P386 ADI.

Return Value
------------
There is no return value.


4.4.13 funlink (obsolete)
=========================

Function
--------
Deletes a currently open file.

Limitations
-----------
Not supported by 3D Studio v1.0 or v2.0.

History
-------
Introduced in OS/2 ADI 4.0.

Syntax
------
int funlink()


Description
-----------
This routine deletes a currently open file that was opened with one of the
ffopen() commands listed in this section.

You should not have to use this function. This function may be dropped in a
future version of P386 ADI.

Return Value
------------
There is no return value.


                  |================================|
                  |                                |
                  |           Chapter 5            |
                  |                                |
                  |        ADS to ADI Link         |
                  |                                |
                  |================================|



5.1 Introduction
================

The ADS->ADI link design was driven by the needs of AVE Render as an ADS
application, but has been generalized where possible to accommodate other
ADS applications. Work to date has been mostly on the combined rendering
and display interface.

The use of the ADS->ADI link requires a thorough understanding of both ADI
driver development and ADS application development. This is not a task to
take lightly! Don't think this is a simple way to implement a new user-
interface widget, for example. Also, keep in mind that ADI drivers,
especially old ones, vary in their behavior.

One goal of the design is to have drivers behave as similarly as possible
in processing packets, regardless of the product in control. Another goal
is to provide drivers with enough information about the controlling product
(or application) so that products or applications which fail to meet the
first goal can still be correctly handled by drivers (as a special case).

Another design goal is to minimize the overloading of packets; to make
explicit requests for actions by the driver instead of implied requests
(i.e., to reduce the state dependencies in packet handling).

Only one application at a time is "in control" of a driver, though in the
case of the display, applications may leave images behind on the screen
after giving up control. Each time an ADS application takes over a driver,
the episode is surrounded with "bookend" packets and core actions. The core
actions are intended to force the driver into a known and more or less
stable state (unless AutoCAD's state is too unstable to allow a takeover,
in which case it will be refused). The bookend packets (PWHO) are intended
to inform the driver as unambiguously as possible about the state of the
controlling product. See the "Extended DEV_RC Specification" section, later
in this document, for sample pseudo-code which makes a typical ADS->ADI
interaction clearer.


5.2 P386 ADS->ADI Link Transport Layer
======================================

The link transport layer occurs in two cases: in one case, an ADS
application takes over a driver loaded by AutoCAD; in the second case, the
ADS application loads an ADI driver directly. At the moment, AVE Render is
the only ADS application that can load ADI drivers directly.

$cb

 ----<-------------<------------------------------
|            |            adi packets            |
|  -->-------|----->---------------------------\/ ^
| |          \/  ^                           ----------
| |  |-----------|--|   |--------------|    |adi packet|    |------------|
| |  |              |   |              |--->|  common  |--->|            |
| |  |              |   |              |<---|  buffer  |<---|            |
| |  |  ADS APP     |-->|  AUTODESK    |    |----------|    |            |
| |  |              |   |              |                    | ADI DRIVER |
| |  |e.g., AVE     |<--|  PRODUCT     |    |----------|    |            |
| |  |    Render    |   |              |<---|dispatcher|<---|(DEV_RC or  |
| |  |              |   |              |    | service  |    |   DEV_DS)  |
| |  |              |   |              |--->| module   |--->|            |
| |  |--------------|   |--------------|    |common mem|    |------------|
| |     ^    |                              ------------
| |     |    |                                ^  \/
| |     |   \/                                |  |
| |  |--------------|                         |  |
| |  |              |>-------------------------  |
| |-<|              |                            |
|    |              |                            |
|    |  ADI DRIVER  |<----------------------------
|--->|              |      dispatcher packets
     | (DEV_RH or   |
     |    DEV_RD)   |
     |              |
     |--------------|
$ce
Figure 5-1. Code flow for transport layers

5.2.1 ADS Application Talking to an AutoCAD-Loaded Driver
=========================================================

In the current Phar Lap implementation, the ADS application is responsible
for constructing a properly formed ADI packet in the common memory buffer
before calling the ads_dscfg() and ads_dsxqt() entry points.

For AutoCAD 386, ADS applications can gain access to the same common memory
buffer used by AutoCAD for communication with protected mode ADI drivers.
ADS applications can fill the packet buffer with a packet and then call
either ads_dscfg() or ads_dsxqt(). These are ADS requests which call into
AutoCAD core where packet throttling takes place (to block illegal packet
codes). AutoCAD core then calls the ADI driver's CFG or XQT entry point,
eventually returning to the ADS application, leaving the reply packet (if
any) in the common memory buffer. AutoCAD core still handles dispatcher
services normally.

5.2.2 ADS Application Loads an ADI Driver Directly
==================================================

AVE Render loads a DEV_RH ADI 4.2 driver. This is done with the old
environment variable (RHPADI) or magic file name (adirndhc.exp). In other
words, AVE Render does not currently have access to AutoCAD's driver search
code; it still uses the old methods of driver location and loading. The ADI
driver makes its dispatcher requests normally, putting dispatcher packets
into the dispatcher common memory buffer and calling AVE Render for service
through adientry(). AVE Render leaves the dispatcher packet in the common
memory buffer (it is common to ADI, ADS and AutoCAD) and makes an ADS
request to AutoCAD for dispatcher service (ads_dispt()). AutoCAD satisfies
the request and returns to AVE Render which then returns to the ADI driver.


5.3 UNIX display ADS->ADI Link Transport Layer
==============================================

The UNIX display ADS->ADI link transport layer uses separate pipes for
display/rendering packets and dispatcher services. This transport layer is
hidden inside library code which ADS developers can link to their ADS
applications. The library code also handles packet throttling.

Note that AVE Render can also load rendering hard copy drivers. These are
given dispatcher services from AutoCAD core.

$cb

                              -------------
                              |dispatcher |
                         |--->|packets    |
                         |    |           |
                         | |-<|           |
                         | |  | DEV_RD or |
                         | |  | DEV_RH    |
                         | |  |           |
                         | |  |           |
                         | |  |rendering  |<------------------
                         | |  |packets    |                  |
                         | |  |           |->--------------- |
                         | |  |           |                | |
                         | |  -------------                | |
                         | |                               | |
rendering                | |                               | |
and display              | |                               | |
ADI driver:              | |                               | |
 acadd                   | |      AutoCAD                  | |
|----------|             | |    ------------               | |
|          |             | |    |          |               | |
|          |             | ---->|dispatcher|               | |
|          |             -------|packets   |               | |
|          |                    |          |               | |
|keyboard  |                    |          |               | |
|& mouse   |                    |input     |             -------------
|events->  |---- read pipe----->|events    | ADS         |AVE Render |
|          |                    |          |<----------->|           |
|rendering |---- read pipe----->|display   | comm link   |           |
|& display |<-|- write pipe-----|packets   |             |ADS App    |
|packets   || |                 |----------|             |           |
-----------|| |                                          |-----------|
          | -------------- read pipe --------------->----| |
          -------------- write pipe ------------------<-----

$ce
Figure 5-2. Rendering hard copy ADI driver

This design separates the input events from the rendering & display
packets. This eliminates any ambiguity as to who should read from the
rendering/display pipe.

The rendering/display pipes are shared between AutoCAD and the ADS
application. This is done by making the pipe FDs public and sending them in
the dsinfo structure. There is no ambiguity as to who should read from the
pipe: whoever sends a packet to the driver is the one who reads the reply.

The dispatcher uses separate pipes. These are also made public and the pipe
FDs are exported through the dsinfo structure. We are not yet supporting
dispatcher services for UNIX display drivers.


5.4 Overview of ADS->ADI Display Interaction
============================================

Since AutoCAD is not aware of the contents of the packets sent by an ADS
application to an ADI display driver, these packets should not include
"drawing" vectors. ADS applications should send only nondrawing vectors and
polygons in via the ADS->ADI link. If an application wants to add "drawing"
vectors or polygons to the AutoCAD drawing, this should be done through
normal ADS requests (such as ads_entmake()).

An ADS application is able to take over the currently configured ADI
display driver (providing it is ADI 4.2), if no other application has
control at the moment and if AutoCAD is not in an unstable state. The first
step toward gaining control is to establish communication with an
ads_adiinfo() request. This is allowed at any time. The application may
then intermittently take control of the display and relinquish control.
Each time the application takes over, it sends ads_adistart() and each time
it relinquishes control it sends ads_adiend(). AutoCAD might refuse an
ads_adistart() if another application has control of the display at the
moment or if AutoCAD is in an unstable state. It is the application's
responsibility to send packets to the display driver telling it to save and
restore regions of the screen which may be damaged, palettes, etc.

5.4.1 Palette Maintenance
=========================

The ADS application might change a paletted display driver's color map
values for the upper (pkdinfo.ncolours - 16) colors, but must always leave
the lowest 16 colors alone when operating in display mode (e.g. rendering
in a viewport). If an application changes the display driver's display mode
color map, it must follow the guidelines described later under "palette
maintenance". An ADS application may freely change the palette in rendering
mode.

A new system variable PHANDLE has been added. This holds the palette handle
for the current viewport. AutoCAD initializes PHANDLE to zero for every
viewport. If an ADS application takes over the display driver, changes the
palette in the current viewport and wants that palette to be restored
whenever that viewport is made current, the application should use PPAL to
instruct the display driver to save the new palette and then should change
the value of PHANDLE to the handle value returned to PPAL. This should be
accomplished just before the application yields control of the display
driver with a WHO_PAUSE action.

AutoCAD keeps track of the current viewport's palette handle. Whenever the
current viewport changes, AutoCAD compares the current palette's handle
with the value in the new viewport's PHANDLE system variable. If they are
not equal, AutoCAD issues a PPAL packet to restore the palette whose handle
is in PHANDLE. If the operation fails, AutoCAD issues another PPAL
restoring the AutoCAD default palette and sets PHANDLE to 0.

If an ADS application repeatedly sends palettes to a viewport, it should
send a matching PAL_FORGET for each PAL_SAVE before issuing the next
PAL_SAVE for that viewport (there is usually no point having two saved
palettes for a single viewport).

Each ADS application should issue PPAL packets with PAL_FORGET to release
its saved palette(s) before terminating with WHO_END. The application
should restore the default AutoCAD palette and reset PHANDLE to 0.

AutoCAD resets PHANDLE to 0 and makes a PPAL request to the display driver
to reset the palette to the AutoCAD default whenever it refreshes the image
in a viewport. Thus, commands such as Redraw, Regen, Pan, Zoom, etc., not
only wipe out any image left by an ADS application, they also reestablish
the AutoCAD default palette. An ADS application can notice that its
rendering has been erased by examining PHANDLE. The application can choose
between refreshing the rendered image (using PPAL to restore the palette)
or releasing the stored palette with PPAL PAL_FORGET.

In the following discussion of palettes and color folding, frequent
reference is made to the upper 240 colors. These are the colors available
to ADS applications on P386 platforms if a 256-color paletted device is in
use. ADS applications should pay attention to the PDINFO.ncolour. On SPARC,
the available palette is smaller due to color indices reserved for use by
the operating system and other applications.

Reading and writing the palette in display mode is fairly simple on DOS
systems. The palette entries from 0 to 15 are treated as read-only by AVE
Render, while the entries from 16 to ncolours - 1 are treated as
read/write. This reserves the first 16 colors as fixed AutoCAD display
colors. The palette indices from (-2) to MINLCOLOR are also read-only and
are used to allow applications to find out how the display driver's logical
colors are defined.

On UNIX windowing systems, life is not so simple. AutoCAD still needs to
reserve 16 palette entries for its fixed display colors, but an additional
32 palette entries are reserved for system use, leaving only ncolours - 48
read/write palette entries, typically 208 in a 256 color system.

There are additional complications. AutoCAD assumes that it owns palette
indices from 0 upward, while in fact the windowing system doesn't have its
physical palette organized like that at all. Thus the display driver does
translation of the requested AutoCAD Color Index (ACI) to the correct index
in the windowing system's color map.

In our current implementation, there are two different translation tables
which are used at different times. Let's call them table A and table B.

Table A translates AutoCAD colors from 0 to 255 into windowing system
colors. There are no entries in this table which provide access to the 32
system colors. The 256 AutoCAD colors are collapsed down to use only 128
windowing system colors. This was the table used in AutoCAD Release 11 UNIX
systems.

Table B translates colors from 0 to 31 into the system colors, 32 to 47
into the fixed AutoCAD colors, and 48 to 255 into the read/write colors
which corresponded to colors 16 to ncolours - 32 in table A.

On startup and whenever a PPAL restore ACAD_DEFAULT is done, table A is
activated. This allows AVE Render to read the AutoCAD default color map,
and it allows normal AutoCAD vector drawing to proceed.

Whenever a RDCMAP/RDCMAPE sequence is received, table B is activated. This
lets AVE Render read the windowing system colors so it can make use of them
in its renderings, even though it can't change them. This table remains
active until the next PPAL operation which restores the AutoCAD default
palette.

When either table A or table B is active, RDRCMAP returns logical color
values for indices from 2 to MINLCOLOR.



5.5 New ADS Requests
====================

The structures for these new ADS requests are defined in ads.h (supplied
with AutoCAD), and adsadi.h (in the ADI 4.2 ToolKit).

The following list shows the functions currently defined in ads.h. The
return values for some of these might change in the future (i.e., for
signaling if a packet was throttled or not).

void ads_adiinfo  _((void *dsinfoptr));
void ads_dscfg    _((void *dspktptr));
void ads_dsxqt    _((void *dspktptr));
void ads_dispt    _((void *dspktptr));
void ads_adistart _((void *dsactptr));
void ads_adiend   _((void *dsactptr));

5.5.1 ADS_ADIINFO
=================

Purpose
-------
This function allows an ADS application to learn about AutoCAD's currently
configured display driver.

The ADS application allocates a dsinfo structure with the rdevflags member
filled in with the desired device type (e.g., DEV_RC) before calling
ads_adiinfo() with a pointer to the allocated structure.

Syntax
------
void ads_adiinfo(struct dsinfoptr *)

Description
-----------
This function returns from AutoCAD with the dsinfo structure filled in by
AutoCAD, with the driver's device type flags (e.g. DEV_RC), the ADI
revision level of the driver, the physical address and size of the packet
buffer, and the scanline buffer.

On the P386 platform, we don't copy the entire dsinfo struct over to ADS,
due to buffer size limits. It is truncated just after member adilevel in
the nested edevent struct. In other words, we do not copy over the
sentinel, platform, options, or stream members.

The dsinfo struct provides ADS applications with more information than they
need for using the ADS->ADI link. The driver device type, revision level,
packet buffer address and size are really all that are required.
Specifically, ADS applications should NOT try to use the REGS values to
call directly into the ADI driver -- this was an early plan of ours and it
fails miserably because of complications related to providing dispatcher
services. Use the new ADS requests described below, instead.

#ifdef P386
struct dsinfo {
    unsigned radipkt;       /* physaddr of cbufadr (ADI
                               packet buffer) */
    unsigned racadpkt;      /* offset from cbufadr to
                               dispatcher buffer* /
    unsigned rrealbuf;      /* offset from cbufadr to
                               scanline buffer */
    int realbufsize;        /* size of scanline buffer */
    unsigned rdevflags;     /* devflags */
    REGS rregst;            /* driver regs struct */
    struct pdevent rdspcad; /* driver edevent struct */
};
#endif /* P386 */
typedef unsigned short USHORT;  /* unsigned 16-bit value */
typedef unsigned long ULONG;    /* unsigned 32-bit value */
typedef int BOOL;               /* Boolean value */

typedef struct              /* Register structure */
{
    ULONG eax;
    ULONG ebx;
    ULONG ecx;
    ULONG edx;
    ULONG esi;
    ULONG edi;
    ULONG ebp;
    ULONG esp;
    USHORT cs;
    USHORT ds;
    USHORT es;
    USHORT fs;
    USHORT gs;
    USHORT ss;
    ULONG eip;
    ULONG eflags;
} REGS;

struct edevent {
    char dev_name[MAX_DEV][DEVNAMSZ+1];     /* Menu name */
    void (*cfgentry)();               /* CFG entry point */
    void (*xqtentry)();               /* XQT entry point */
    short devflags;                 /* Device type flags */
    struct eadient adientp;  /* adientry connection data */
    short adilevel;                /* ADI revision level */
    char sentinel[SENTINLEN];
    char platform[PLATFORMLEN];
    short options;
    char stream[SENTINLEN];    /* Internal source stream */
};

#define EDEVENTSIZE (sizeof(struct edevent))
#ifdef uadi
struct dsinfo {
  int acadinpipe;
  int acadoutpipe;
  int realbufsize;
  unsigned rdevflags;
  int dispinpipe;
  int dispoutpipe;
};
#endif /* uadi */



5.5.2 ADS_ADISTART
==================

Purpose
-------
This function is the start "bookend" ADS driver call.

Syntax
------
void ads_adistart(void *dsactptr)

Description
-----------
Parameter dsactptr must point to an allocated adi_action structure. This
function is called to inform AutoCAD that use of the AutoCAD-loaded ADI
driver might be starting or resuming. AutoCAD sends a PWHO packet to the
selected device followed by a PSYNC to update the display information. All
members of the adi_action structure (except status) must be filled in by
the application with valid values.

struct adi_action {
    short dev_type;                        /* device type */
    short status;          /* AutoCAD returns status here */
    short product;                     /* product ID code */
    short prod_version;         /* product revision level */
    short adipktlevel;           /* product's adipktlevel */
    short action;                /* requested action bits */
    short screen;                /* requested screen mode */
    char  serial[WHO_SERIAL_SIZE];
    char  regapp_name[32];
    short folding;         /* Color folding request flags */
};

This adi_action structure is used by AutoCAD to construct a PWHO or RDWHO
packet to send to its installed DEV_DS or DEV_RC driver. See the
description of PWHO in chapter 6 for more information on some of the
members and flags used in PWHO.

The member adipktlevel is a one way field, filled in only by the
application and not revised by the ADI driver. Applications use the
ADIPKTLEVEL version scheme, not the older INTLEVEL scheme.

The action member indicates whether this is an initial startup or a
resumption of activity after a PAUSE. Action takes on the values WHO_START
or WHO_RESUME (see who.h).

Note that it is incorrect for an application to send WHO_START twice
without an intervening WHO_END. It is also an error to send WHO_RESUME
twice without an intervening WHO_PAUSE.

Applications without a serial number put EOS in member serial. Otherwise it
is filled with the application's ASCII serial number. All applications fill
in the regapp_name member.

All applications fill in product and prod_version members. New Autodesk
products or versions will add their #defines to the header file who.h.

The member folding is the control flag used by ADS applications to change
the color folding state.

Table 5-1. Values for adi_action.folding

Mnemonic     Value Meaning

FOLD_UNCHANGED   0 Don't change the color folding status

FOLD_ON          1 Turn on color folding

FOLD_OFF         2 Turn off color folding


Note that although FOLD_ON always has the expected effect, FOLD_OFF only
decrements the number of applications wanting folding, but won't
necessarily turn it off if another application still has it on.

Also note that this works only if each application only makes ONE request
with FOLD_ON and ONE request with FOLD_OFF. Multiple FOLD_ON requests
without matching FOLD_OFF requests will cause problems, as will multiple
FOLD_OFF requests without matching FOLD_ON requests.

The screen member is WHO_CURRENT_VP for applications which operate only in
the current viewport (e.g., shading in a viewport). WHO_CURRENT_VP is not
set if the display may be reinitialized, the graphic mode changed and/or
the whole screen damaged (as in full screen rendering by AVE Render).

In either case, the product saves the current vpnumber for packet
throttling purposes. Between a pair of WHO_START/WHO_END bookends, the
application is allowed to operate only in a single viewport if it has
initialized with WHO_CURRENT_VP.

The following table shows the screen bits that an ADS application can set:

Table 5-2. Screen bits ADS applications can set

Mnemonic             Value Meaning

WHO_CURRENT_VP       0x1   If application operates only in current viewport

WHO_240              0x4   If application is using only the upper 240
                           colors


Note that it is improper for an ADS application to set WHO_FOLDED; this is
an informational bit set in PWHO by AutoCAD if color folding is active. ADS
applications request changes in the color folding state by use of
adi_action.folding.

AVE Render offers the user three options for palette handling if a paletted
DEV_RC has been configured for rendering in a display viewport:

1)      Use AutoCAD's palette unchanged (WHO_240 is clear).

2)      Freely remap the upper 240 colors for rendering, leave AutoCAD's
        colors unfolded. This will change the color of wireframe images which use
        colors above 15 (WHO_240 is set).

3)      Freely remap the upper 240 colors for rendering and fold
        AutoCAD's colors down to the lower 16 (WHO_240 is set and "folded"),
        FOLD_ON request has been made.

Note that WHO_240 and WHO_FOLDED are a informational flags from a driver's
point of view, no driver action is required. AutoCAD handles color folding
internally and AVE Render is responsible for sending the ADI driver any
necessary palette mapping packets.

AutoCAD checks for error conditions first, returning with an error code in
member status if necessary. An unstable state is an error condition (e.g.,
if the current viewport were in DVIEW). If another application is in
control of this device (i.e., between a pair of WHO_START/WHO_END
bookends), AutoCAD also treats this as an error.

The member status can take on these values:

Table 5-3. Values for adi_action.status

Mnemonic          Value  Meaning

GOOD              0      OK, you have control now

ADI_BUSY          1      Another application has control

ADI_UNSTABLE      2      AutoCAD is unstable

ADI_NULL          4      This is not an ADI driver or it is a null device

ADI_ERROR         8      Driver reports an error

ADI_BAD_TYPE      0x10   Unsupported DEV_type


Assuming no error conditions, WHO_START or WHO_RESUME force AutoCAD into a
nearly quiescent state:

  * No dragging

  * No cursors on screen

  * No dialogues up

  * Nothing highlighted on the menu

  * Be sure we are on the graphic screen (e.g. gograph())

The general idea is to get AutoCAD's view of the display into a known state
which can be restored at the next WHO_PAUSE or WHO_END. Then we must inform
the driver which application is taking over and notify the display of the
current viewport.

This triggers a PWHO packet indicating to the ADI driver that this is a
secondary application starting up. PWHO passes on the regapp name, product
ID code, serial number, action, and screen arguments. The driver will
probably soon be requested to save the current screen or viewport state
with PBIGBLIT and PPAL so it can be asked to restore it later. The PWHO
will be followed by PSYNC. PSYNC will flush any buffers and or display
lists onto the screen and identify the currently active viewport. AutoCAD
also sends a PDINFO packet to find out if the display has a mapped palette.
If there is a mapped palette, and if folding has been requested by any
active ADS application, AutoCAD turns on color folding so that its upper
240 colors are folded into the lowest 16 by mapping the high color indices
to the most closely matching color from 1-7. The work of color folding is
handled in AutoCAD code - display drivers can behave normally.

Note that color folding is not done for drivers which use true color for
"display rendering" because AutoCAD's color map isn't modified by the
rendering process.

If the application is taking over the display, it probably will then issue
a PDINFO packet to get the current state of the display. The application is
responsible for issuing packets to instruct the driver to save and restore
the screen (or viewport) and palette states.



5.5.3 ADS_DSCFG and ADS_DSXQT
=============================

Purpose
-------
These functions call the AutoCAD display driver, asking it to process a
packet request which the calling ADS application has already placed in the
common memory packet buffer.

Syntax
------
void ads_dscfg(void *dspktptr)
void ads_dsxqt(void *dspktptr)

Description
-----------
Parameter dspktptr must be passed as a NULL pointer. You already know where
the packet buffer is from ads_adiinfo(). The ads_dscfg() and ads_dsxqt()
functions are defined for P386-only ADS libraries; we talk directly to the
pipes for UNIX. We assume that P386 developers will write into the shared
memory space for ADI drivers. The ADI packet buffer address is passed in
ads_adiinfo(). Future development will use the pointer location to access a
structure which provides a length and address of data to put in the ADI
shared memory or onto the UNIX pipes.

Both of these functions are called after the ADS application has filled the
ADI packet buffer (and possibly the scanline buffer) with a packet.

The functions call a packet throttle function which either sends the packet
onward to the driver's configuration or execution entry point or returns
without sending it. If the throttle stops the packet, an error value is
returned (RTERROR). If the packet is sent to the driver, RTNORM is returned
from AutoCAD when the driver returns. (In the current implementation, ADS
applications won't see these return values--we plan to fix this later.)

Following is a list of packets allowed at configuration-time:

PWHO

RDWHO

RDLANG

RPCHGCFG

RPNEWCFG

RPSHOWCFG


Following is a list of packets allowed at execution-time (including all 3D
packets):

PWHO
PINIT
PBOXCLR
PBOXPUSH
PBOXPOP
PCFGREC
PCHAR
PCLEAR
PCLVP
PDOT
PDRAG
PECHAR
PFILL
PQPLOT
PREDRAW
PSYNC
PTEXT
PVEC
PBIGBLIT
PDINFO
PDCURS
PCCURS
PMARK
PBMARK
PCMARK
PCBMARK
PHLITE
PDHLITE
PCOORDLINE
PMODELINE
PMNUCURS
PTPROMPT
PWRSPLIT
PGOGRAPH
PGOTEXT
PGOTEXTU
PRPEN
PRPEN_42
PPAL
RDCMAP
RDWHO
RDCLEAR
RDCMAPB
RDCMAPE
RDCPOLY
RDCRANGE
RDEND
RDFNAME
RD_FGRAB
RD_INFO
RDINIT
RDPOLY
RDRCMAP
RDRSLINE
RDSTART
RDWSLINE
RPCFGREC
PVIEW
PORTHO
PPERSP
POSEG
PCSEG
PDSEG
PPOLY3
PNPOLY3
PCPOLY3
PVEC3
PLIGHT
PDLIGHT
PSETCOLOR
PSETMATL
PMODEL
PDRAWSEG
P3D
PBPOLY3


Following is a list of packets that we do NOT allow at execution-time. You
should also note that the default is to NOT allow any packet that is not on
the list of allowed packets!

POPENVP

POPENBVP
PCLOSEVP
PVIEWPORT
PBVIEWPORT
PLOPEN
PKZOOM
PKBZOOM
PREVEC
PROPENVP
PLANG
PMAXVP
PNEWCFG
PSHOWCFG
PTABCFG
PCOMMAND
PSTRING
PTERM
RDETAIL
RDTERM
RPCHGCFG
RPNEWCFG
RPSHOWCFG



5.5.4 ADS_ADIEND
================

Purpose
-------
This function is the end "bookend" ADS driver call.

Syntax
------
void ads_adiend(void *dsactptr)

Description
-----------
Parameter dsactptr must point to an allocated structure adi_action. This
function is called to inform AutoCAD that use of the AutoCAD-loaded ADI
driver might be pausing or ending. AutoCAD sends a PWHO packet to the
selected device followed by a PSYNC to update the display information.

This call is made when the ADS application is ready to yield control of the
display driver back to AutoCAD. If WHO_240 was set at ads_adistart time,
the ADS application must resolve the palette state just before calling
ads_adiend. There are three possible resolutions:

1)      If the palette which existed at start time was not this
        application's, restore the palette which existed in the viewport at
        ads_adistart time. An ADS application which plans to do this should save
        the value of PHANDLE at start time and use PPAL to restore it just before
        ads_adiend. The value of PHANDLE should match the handle of the final
        palette. This may be done for either WHO_PAUSE or WHO_END.

2)      Save the modified palette with PPAL and set PHANDLE to the handle
        of the saved palette. This may be done only for WHO_PAUSE.

3)      Restore AutoCAD's default palette and set PHANDLE to 0. Use PPAL
        PAL_FORGET to release any palettes stored by this application for this
        viewport. This may be done for either WHO_PAUSE or WHO_END.

The ADS application is responsible for assuring that the display is back in
a known state at this time:

  * No dragging

  * No cursors on screen

  * No dialogues up

  * Nothing highlighted on the menu

  * Be sure we are on the graphic screen (e.g. gograph())

The action member may be WHO_END or WHO_PAUSE. WHO_END indicates that this
ADS application is completely done, while WHO_PAUSE indicates a temporary
end to activity.

If the action is WHO_END, it lets AutoCAD know we can turn off packet
throttles, and so forth, if this was the last ADS application which hooked
the display.

In any case, it is a signal for AutoCAD to send PWHO to the ADI driver and
resume operations normally.



5.5.5 ADS_RECFGPORT
-------------------

Purpose
-------
ads_recfgport gives ADI drivers loaded by ADS applications access to
AutoCAD's I/O port configuration and arbitration services.

Limitations
-----------
Since our initial public ADS library for release 12 doesn't include code
for loading ADI drivers, ads_recfgport() is only of academic interest at
the moment. But we do have plans to expand the ADS library code in the
future.

Syntax
------
void ads_recfgport(int *idvc, int iotype, int baudrate,
                   int parity, int databits, int stopbits,
                   int hhflag, char *devname);

Description
-----------
The ADI driver wants to send output to a port but can't use the usual iow()
or plsend() dispatcher calls because it is not directly linked to AutoCAD.
Unless the ADI driver wants to talk directly to a port using its own code,
it should use AutoCAD's I/O port functions. To that end, the ADS
application can call ads_recfgport() at configuration time and let AutoCAD
prompt the user for a port.

At execution time the ADS application again calls AutoCAD with the port
name supplied at configuration time. In exchange, AutoCAD returns a handle
(idvc) that, when passed to the ADI driver, can be used to direct AutoCAD
to send data out a specified port. Currently the only ADI dispatcher
function that accepts this handle is rhsend(). That function is typically
used by rendering hardcopy drivers (type DEV_RH).

Note that ads_recfgport() must not be called if the ADI driver has returned
NODEVICE in RDETAIL.type.

The ads_recfgport() call returns RTNORM if things proceed normally. The
devname string can be up to MAXPATHLEN in size (see path.h).

The iotype argument contains two bit-fields; one specifies a port and the
other an action to be performed on that port. When calling ads_recfgport()
only one action bit and only one port bit should be set. The action and
port bits are listed in the following tables:

Table 5-4. Action bit values for the iotype parameter

Mnemonic       Value  Meaning

IORC           0x0010                 I/O reconfiguration

IOCN           0x0020                 I/O configure new device

IOXN           0x0040                 I/O execute new device

IORD           0x0080                 I/O release device


Table 5-5. Port bit values for the iotype parameter

Mnemonic        Value                          Meaning

SERIAL          0x0001                         Serial hardware port

PARALLEL        0x0002                         Parallel hardware port

HPIB            0x0004                         HPIB hardware port (not
currently supported)

FILEOUTPUT      0x0100                         File output (not a hardware
port)


During the initial call at configuration time, the IOCN bit should be ORed
with the port bit in iotype. The other members are filled in from the ADI
driver's RDETAIL packet. AutoCAD returns the port name in devname. The ADS
application must store the devname string for use in later requests. This
initial operation does not actually open the port or file for usage.

At execution time, when the ADS application wants to open the port or file
for output, it makes another ads_recfgport() request, this time filling in
the iotype field with the port bit and the IOXN action bit. Every other
argument except idvc is filled in with the values which were obtained from
the DEV_RH at configuration time in RDETAIL. The idvc field is filled in
with zero and devname points to the device name supplied at configuration
time or to a file name solicited from the user by the ADS application.
AutoCAD opens the port, warning the user to switch if AutoCAD sees that the
port is shared with another device. On return to the ADS application,
AutoCAD will have filled in ads_recfgport() with idvc. The ADS application
then sends an RDRHOPEN packet to the DEV_RH driver. This serves two
purposes - it tells the driver it is okay to start making rhsend()
dispatcher requests, and it also supplies the driver with the idvc handle
to use in rhsend() requests.

If the driver requested file output at configuration time by setting the
FILEOUTPUT bit, the ADS application's execution time request should have
the IOXN and FILEOUPUT bits set in the iotype field. The ADS application
supplies a file name solicited from the user. AutoCAD opens the requested
file and returns with an idvc value for the driver to use in rhsend().
Because the ADS application, not AutoCAD, solicits the user for a file name
when file output is requested, it is not actually necessary to call
ads_recfgport() at configuration time with the IOCN and FILEOUTPUT bits in
iotype. Doing so just causes a return from ads_recfgport(). This
functionality is provided to keep the bit field requests consistent rather
than making an exception for file output.

Note, however, that in all cases the value of idvc should be checked upon
return. A value of -1 in idvc indicates that an error occurred. It is the
responsibility of the ADS application to issue an appropriate error message
and to handle recovery from the error (usually by aborting the rendering).

After the ADS application is done rendering, it sends an RDEND packet to
the ADI driver. When the driver has completed processing RDEND and returned
to the ADS application, the idvc value sent at RDRHOPEN is invalidated by a
final ads_recfgport() request, this one made with the IORD action bit set.
This tells AutoCAD it is time to close the file or port. If a port was used
and it was shared with another device, AutoCAD tells the user to switch
devices and then reinitializes the port for the original device.

The IORC bit is a special case and is used to reinitialize a port. It is
usually used by ADI drivers which call the recfgport() dispatcher function
to re-configure either a digitizer or plotter port. However, it can also be
used to reconfigure a port acquired using the ads_recfgport() function.

Example
-------
1)  ADS gets port information from ADI driver through RDETAIL.

2)  ADS makes the following call to AutoCAD at configuration time:

int idvc;
char devname[MAXPATHLEN];
ads_recfgport(&idvc, IOCN | SERIAL, 9600, PARITY_NONE,
              7, 1, HANDSHAKE_HARDWARE, devname);

3)  ADS stores away the port parameters from the ADI driver and the
    devname string returned from AutoCAD.

4)  ADS makes the following call (perhaps after the application has
    been shut down and restarted) at execution time:

FILL_IN_DEVNAME_WITH_STRING_FROM_CONFIGURATION(devname);
ads_recfgport(&idvc, IOXN | SERIAL, 9600, PARITY_NONE,
              7, 1, HANDSHAKE_HARDWARE, devname);

5)  ADS sends value of 'idvc' to ADI driver through RDRHOPEN.

6)  ADI driver issues rhsend(idvc, numbytes, string) calls.

7)  ADS sends RDEND to ADI driver and issues the following call to
    AutoCAD when the driver returns from RDEND:

ads_recfgport(&idvc, IORD | SERIAL, 9600, PARITY_NONE,
              7, 1, HANDSHAKE_HARDWARE, devname);

Notes
-----
  * Always check the return value in idvc; -1 indicates error.

  * Calling ads_recfgport() with IOCN | FILEOUTPUT in iotype is a do-
    nothing call.

  * When the IORD bit is set, the only other parameter that is used is
    idvc. The ads_recfgport() doesn't care if you set the port parameters
    (including SERIAL, PARALLEL etc.) upon releasing a device.

  * When calling ads_recfgport() with either IOCN or IOXN set in iotype,
    the value passed down in idvc is disregarded. Be careful: if you set idvc =
    -1 and then call with IOCN, you will get back -1 in idvc and may think this
    is an error, when in fact the function is only passing back what it
    received.

  * If an IOXN call returns a -1 in idvc there is no need to release the
    device with an IORD call. The -1 at IOXN time indicates that the device was
    never acquired.



5.5.6 ADS_DISPT
===============

Purpose
-------
This function allows an ADS application which has loaded an ADI driver to
pass on dispatcher requests made by the ADI driver to AutoCAD core for
processing.

Limitations
-----------
Since our initial public ADS library for AutoCAD Release 12 doesn't include
code for loading ADI drivers, ads_dispt() is only of academic interest at
the moment. But we do have plans to expand the library code in the future.

Syntax
------
void ads_dispt(void *dspktptr)

Description
-----------
Parameter dspktptr must be passed as a NULL pointer. This packet is defined
for P386-only ADS libraries. We talk directly to the pipes for UNIX. P386
ADI drivers loaded by an ADS application such as AVE Render are able to
make dispatcher requests normally. The library code linked with the ADI
driver forms a dispatcher packet and places it in the common memory buffer.
The library code then calls the entry point passed to the driver at startup
time. This entry point calls into the ADS application which in turn uses
ads_dispt() to forward the request to AutoCAD, leaving the dispatcher
packet untouched in the common memory buffer. AutoCAD services the request
and returns to the ADS application which in turn returns to the ADI driver,
leaving the result packet in the common memory buffer. The library code
linked with the driver examines the result packet and forms a return value
to the public part of the ADI driver.


5.6 Third-Party Applications and AutoCAD Release 12
===================================================

This section describes what is and is not available to third-party
applications in AutoCAD Release 12.

We have been unable to complete adding support for loading ADI drivers in
ADS.LIB for the initial release of AutoCAD Release 12. Thus, ADS
applications will generally not be able to load ADI drivers (e.g., DEV_RD
or DEV_RH).

Although the support for using a DEV_DS or DEV_RC driver loaded by AutoCAD
is in release 12, this support is minimal. We don't have any sample code to
offer showing how this is done. The ADS functions for sending packets don't
yet have return values so your application won't know if a packet was
throttled.

There is no support in AutoCAD Release 12 for ADS applications controlling
any device types except DEV_DS and DEV_RC. Only ADI 4.2 drivers can be
controlled (because the link depends on PWHO and PDINFO which are ADI 4.2
packets).




                    |================================|
                    |                                |
                    |           Chapter 6            |
                    |                                |
                    |          Display ADI           |
                    |                                |
                    |================================|


6.1 Introduction
================

Most Autodesk products require display drivers. The DEV_DS driver is the
simplest type of display driver, handling only display operations. These
drivers can range from a very simple driver with no display list and no
advanced options to a sophisticated display list driver with icon menus and
other value-added features implemented through driver-local commands.

This chapter describes the ADI specification for display devices. Drivers
for display only (DEV_DS), versus drivers that support both display and
rendering, are becoming obsolete. If your video board supports a reasonable
color or gray-scale depth, we recommend you write a combined display and
rendering driver (DEV_RC) as either a display list (BS, or Big Screen)
driver or at least as a FAKE_BS driver (one which processes most of the BS
packets and thus is aware of viewport sizes and locations). See chapter 7,
Combined Display and Rendering ADI, for more information on the DEV_RC
specification.

AutoCAD is currently the only Autodesk product that makes use of display
lists, driver-local commands, and most other advanced features.

You should be familiar with the Autodesk products you are writing a driver
for, including screen layouts and terminology used by the products. We
recommend you first experiment with the product's features as they relate
to the display, using a display driver that is already supported. Some of
the details presented in this chapter may be further clarified by examining
the sample display drivers provided in the ADI ToolKit. For a discussion
about Autodesk product graphic display environments, see appendix C.

6.1.1 Display Driver Modes of Operation (Driver's Point of View)
================================================================

ADI display drivers have two modes of operation: CFG-time (configuration
time) and XQT-time (execution time). Configuration of display drivers takes
place in text mode, unless your driver chooses to put itself into a graphic
mode for user-interface purposes. At Configuration time, your driver is
sent a series of packets which notify it that this is configuration time,
that this is a new configuration or a reconfiguration, and if it is a
reconfiguration, you are sent the results of the last successful
configuration to use as a starting point in your dialogue with the user.
You are then able to ask the user questions to solicit her choices for any
configurable options in your driver, e.g., graphic mode resolution, color
depth, display list features, color correction, logical color assignments
or whatever else you like. The Autodesk product stores a configuration
record for you, regurgitating it at Execution time. You leave Configuration
time in text mode, just as you entered it.

It is very desirable for your driver to use dispatcher services for all
user interaction during configuration. This is because use of the
dispatcher service functions would enable your driver's configuration
dialogue to be integrated into any future enhancements to an Autodesk
product's configuration process.

See chapter 4 for a discussion of the dispatcher.

Although your display driver is always configured sometime before it is
executed, configuration happens much less often than execution. Normally,
users start up the already-configured product, and your driver is started
up in execution-time mode immediately. This means that your driver gets
loaded and starts receiving a series of packet requests from the Autodesk
product. For ADI 4.2-compatible products, the first packet you see is PWHO.
Shortly thereafter, you get PCFGREC to return your private configuration
record to you. And shortly after that, you receive PINIT. This tells you to
do a device presence test, initialize your device, and enter the currently
configured graphic mode.

Once running at execution time, your driver has to be able to satisfy many
different packet requests which ask your device to switch video modes, draw
vectors, text and polygons, save and restore screen regions, etc.

The display ADI specification contains a long list of display packets. Your
driver probably does not need to be able to handle all of these packets.
There are packet usage tables in section 6.16 which show which packets are
used by various Autodesk products. Some packets are optional depending on
features you may choose to add to your driver, such as a display list, a
drag display list, driver local commands, etc. Your driver can tell
Autodesk products which optional packets it can handle by setting
capability flags in PINIT and PDINFO.

6.1.2 Display ADI History
=========================

The display ADI interface has been elaborated and extended in each new ADI
version, both by adding new packets and by adding support for new products
and platforms. Some of the history of each display packet is summarized in
the "History" section of each packet description, below. For more detail on
earlier ADI specifications, refer to the CDROM ADIKIT files.


6.2 From a Controlling Application's Point of View
==================================================

This release of the ADI specification includes new information about ADI
packets -- each packet is discussed from the controlling application's
point of view as well as from the ADI driver's point of view. The
application section for each packet is titled "Limitations."

There can be two types of controlling applications: primary or secondary.
The primary application is in charge of loading and unloading the driver
and normally is also in control of configuring it. In many cases, drivers
are controlled only by primary applications (e.g., AutoCAD or AutoShade).
But application developers are also using various tricks to let secondary
applications take over control of ADI drivers under some circumstances.

AVE Render, an Autodesk ADS application which is shipped with AutoCAD
Release 12, is an example of a secondary application which can take over
ADI drivers. See chapter 7 for a discussion of DEV_RC drivers and AVE
Render.

ADI 4.1 developers are limited to using TEE drivers to take over control of
ADI drivers. See the Bonus disk documentation for a discussion of TEE
drivers. ADI 4.2 developers have the ADS->ADI link, an easier and more
stable mechanism. Nevertheless, writing a secondary application to take
control of AutoCAD's display driver is by no means simple and should not be
attempted casually.

This document is also used by developers at Autodesk who are developing
primary applications which use an ADI driver. For this reason, you will see
some discussion of what is expected from primary products.

Applications that want to take control of an ADI display or rendering
driver must be careful to send only properly formed, legal packets to the
driver. ADI drivers are used to being controlled by Autodesk products which
do not send illegal values. It is easy to produce a memory protection
violation by writing outside the display memory area, or to leave garbage
in areas of the screen such as the status line, menu or scrolling text
area.

Note that not every driver supports every packet. The Limitations section
of the packet descriptions below explain how you can tell whether a driver
supports a particular packet request.

6.2.1 Preferred Packets
=======================

There are many ADI packets, but a small subset of them are suggested as
preferred for use by secondary applications. Here is a short list:

  * vector drawing: PVEC or PLINE

Note: PLINE should be restricted to user interface widgets such as
dialogues. Also note that programmable dialogue boxes are a much easier
method than direct ADI control for putting up dialogues!

  * clearing an area of the screen: PBOXCLR

  * saving a screen region: PBOXPUSH

  * text on the graphic screen: PTEXT

  * filling polygons: PFILL (if DEV_DS), RDPOLY or RDCPOLY (if DEV_RC)

  * raster data (for a DEV_RC): RDWSLINE or PBITBLIT

6.2.2 Logical Versus Pixel Coordinates
======================================

AutoCAD is presently the only Autodesk product using logical coordinates,
all other products currently use pixel coordinates. AutoCAD Release 12 uses
two different logical coordinate systems: 31-bit (BIGVEC) and 15-bit. You
can tell if logical coordinates are in use and the size of the current
logical space by looking at the reply from a PDINFO packet. The member
PDINFO.lgxdots and PDINFO.lgydots are the size of the logical space, if the
driver is Big Screen (BS). The flag DI_NOW_BS is set in PDINFO.iflags if
the current viewport is BS.

BS (display list) ADI drivers normally process all "drawing" vectors in
logical coordinates. If the driver runs low on display list memory, it may
choose to handle some viewports as NO_BS, in which case drawing vectors are
sent from AutoCAD in pixel coordinates. Secondary applications should be
careful to send only "nondrawing" vectors and to send them in the same
coordinate system used by AutoCAD for sending "drawing" vectors. The same
rule applies to polygons sent to PFILL. Rendering polygon packets (RDPOLY
and RDCPOLY) only accept pixel coordinates.

BS drivers which support FASTDRAW will get only 15 bit logical drawing
vectors through FASTDRAW. BIGVEC BS drivers will get only 32 bit logical
drawing vectors through PBATCHVEC. Nondisplay list drivers can get pixel
vectors through FASTDRAW.

6.2.3 Packet Sequences
======================

For most purposes, it is useful to consider configuration time and
execution time as totally separate environments. The primary product should
handle configuration for most ADI drivers.

ADI driver authors have been warned not to count on specific packet
sequences and to ignore unrecognized packets. Nevertheless, there are some
unavoidable packet sequence requirements. For example, it is impossible to
do graphic operations on the text screen. Likewise, many driver functions
are not available until the driver has been initialized. The Limitations
sections of the packet descriptions below explain some essential packet
sequence requirements.

6.2.4 Forming Packets (P386)
============================

The P386 ADI interface uses a common memory buffer to pass packets to ADI
drivers. TEE drivers and ADS applications have access to this buffer and
thus can assemble packets. It is important that packets be properly formed,
i.e., they must conform to the structures in the header files listed below.
Notice that rendering packets are actually composed of two nested
structures while display packets are a single structure.

  * 4.1 rendering:     rdadi.h

  * 4.1 display:       dsadic.h

  * 4.2 rendering:     rdadi42.h

  * 4.2 display:       dsadic42.h

  * 4.2 3D:            rcadi3d.h

Although the common memory buffer is a 4K page, only the first 500 bytes is
used for ADI packets. Writing outside this area (with an oversize packet,
for example) causes serious problems and is forbidden.

The structure members which make up each packet have limited ranges for
legal values. Inserting an illegal value in a packet member could crash the
driver or AutoCAD. Most ADI drivers do not test the values sent to them in
packets for legality.

Rendering and display packets are somewhat state dependent. Thus, packets
which may be legal at one time may be illegal at another. For example, many
display packets may be sent only when in display mode and the graphic
screen. Sending them while on the text screen may crash the system.

A discussion of the range limits for each member and any state dependencies
which drivers are likely to expect are discussed in the packet descriptions
later in this chapter.

Some packets carry with them implied obligations to service requests made
by the ADI driver (e.g., PCLEAR expects the controlling application to be
able to provide repaint services). Such obligations are also discussed
below, in each packet's description.

In the "History" section of many packet descriptions, you'll find that
changes were made for all PASS_DATA platforms. These are defined in the C
header files supplied with the ADIKIT, and are: XENIX (after ADI 4.0),
OS/2, P386, UNIX, Mac and Windows.

Note that, in the case of display list drivers, it is not a good idea for a
secondary application to send "drawing" vectors or polygons. The primary
application is not aware of these additions to the display list. Stick to
"nondrawing" vectors and polygons.


6.3 Required Features of an ADI 4.2 DEV_DS Driver
=================================================

The following features must be supported by all ADI 4.2 DEV_DS drivers:

  * The AutoCAD display functions, including AUI support

  * The TAPIXEL and TAXPARENT attributes for PTEXT

  * PBITBLT

  * PBIGBLIT

  * PDINFO

  * PWHO

  * PLANG

  * PKILL

  * PVPAGE (if more than one page is available)

  * DR_DASHED (dashed lines)

  * PRCMAP (return color map values to AutoCAD on request)

  * BS drivers must support PROW

  * BS drivers must support logical cursors

  * BS drivers must provide minimal support for PSYNC

ADI 4.2 DEV_DS packets are defined in dsadic42.h. Some of the packets have
been modified and reorganized from previous versions of ADI. We strongly
suggest you compare your code with the defined packet structures,
especially if you are modifying an ADI driver based on an older version of
ADI.

dsadic42.h is #ifdef'd across platforms. P386 drivers must make sure that
the MSDOS tag is not defined and that the P386 tag is defined before
including dsadic42.h (MSDOS is defined in padi.pro). This is so the correct
packet definitions are compiled.


6.4 Interface Level
===================

We are in the process of changing the scheme for identifying the ADI
revision level of Autodesk products and ADI drivers. To maintain
compatibility with existing software, old packets and structures continue
to use the old INTLEVEL numbering scheme, but new packets and structures
use the new ADIPKTLEVEL scheme.

ADIPKTLEVEL for AutoCAD Release 12 is 2.

INTLEVEL for AutoCAD Release 12 is 8.

The table below outlines the ADI versions, display ADI interface levels,
and supporting Autodesk product versions that were returned in the constant
INTLEVEL.

Table 6-1. ADI display interface level INTLEVEL values

Product version     ADI version            DS interface level

AutoCAD 2.18        ADI 1.0  1

AutoCAD 2.5x, 2.6x  ADI 2.0  2

                    ADI 2.1  3

AutoCAD Release 9   ADI 3.0  4

                    ADI 3.1  5

AutoCAD Release 10  ADI 4.0  6

AutoCAD Release 11  ADI 4.1  7

AutoCAD Release 12  ADI 4.2  8

3D Studio V1.0      ADI 4.1  7

3D Studio V2.0      ADI 4.2*               

AutoShade V1.1      ADI 4.0  6

AutoShade V2 (DOS)  ADI 4.1  7

AutoShade V2 (386)  ADI 4.1  7


  * Note: 3D Studio v2.0 is only partly ADI 4.2.

6.4.1 New Display ADIPKTLEVEL Constants
=======================================

#define DS_LEVEL_41  0
#define DS_LEVEL_42  1

6.4.2 Which Interface Level do I Use?
=====================================

Refer to the documentation for each packet and structure to confirm which
interface level constant should be used. These old packets and structures
use INTLEVEL: PINIT and the edevent structure (for DEV_DS or DEV_RC). These
new packets and structures use ADIPKTLEVEL: the edevent structure for all
other device types, the adi_action structure, PDINFO and PWHO.

6.4.3 Pixel Aligned Text Mandatory
==================================

All ADI 4.2 DEV_DS and DEV_RC drivers must support pixel-aligned text and
must set EF_PTEXT.


6.5 Display List (BS) Driver Issues
===================================

6.5.1 31-bit Regen Space for Displays
=====================================

Prior to Release 12, AutoCAD has maintained a 15-bit internal logical space
(0-0x7ffd). AutoCAD Release 12 defaults to using a 31-bit internal logical
space (0-0x7ffffffd). This increases the zoom depth without Regen by a
factor of thousands (we Regen zoomed into limits or extents by a factor of
10 or so, so you wouldn't get the full 31-bit depth). Regens are few and
far between in 2D drafting. Removing erased (color 0) vectors from your
display lists (either via smart data management or in the background)
becomes essential.

Two new capability flags have been defined for use in PINIT and PDINFO:

For pconfig; indicating the product has 31-bit logical capability:

#define CF_BIGVEC  0x80

For pefmodes; indicating the driver has 31-bit logical capability:

#define EF_BIGVEC  0x40000

ADI drivers are able to specify at PINIT time if they want 31-bit logical
vectors by setting EF_BIGVEC. This allows the user to turn on or off big
vectors at configuration time (in case they want to trade speed for
memory). It is very desirable for display list drivers to offer this
configuration choice to users.

The current implementation has three modes of operation, depending on the
state of EF_BIGVEC (in PINIT.pefmodes) and on the state of a new
environment variable, IGNORE_BIG_SCREEN.

1)  If EF_BIGVEC is not set and IGNORE_BIG_SCREEN is not set, AutoCAD
    shrinks its logical space to fit 15-bit BS drivers. This effectively
    disables the 31-bit logical space, but allows old BS drivers to continue to
    work. In this case, the old 15-bit display packets are sent and the new 31-
    bit packets are not seen.

2)  If EF_BIGVEC is set and IGNORE_BIG_SCREEN is not set, then AutoCAD's
    logical space is 31 bits and so is the driver's. In this case, the new 31-
    bit display packets are sent. The following old 15-bit packets are not
    seen: PMARK, PCMARK, PDRAG, POPENVP, PVIEWPORT and PKZOOM.

3)  If EF_BIGVEC is not set and IGNORE_BIG_SCREEN is set, then AutoCAD's
    logical space is 31 bits, but the ADI driver is treated as non-BS, always
    being sent pixel coordinate vectors. In this case, no BS packets are sent.

Table 6-2. Regen space bit setting actions

IGNORE_ 
BIG_ 
SCREEN       EF_BS EF_BIGVEC EF_FDRAW    Resulting behavior
-------------------------------------------------------------------------
no            yes  yes      yes      31 bit drawing vectors in PBATCHVEC,
                                     31 bit nondrawing vectors in PBIGVEC, 
                                     pixel non-drawing vectors in PVEC

no            yes  yes      no       31 bit drawing vectors in PBIGVEC, 31
                                     bit non-drawing vectors in PBIGVEC, 
                                     pixel non-drawing vectors in PVEC

no            yes  no       yes      15 bit drawing vectors in FDRAW, 
                                     15 bit non-drawing vectors in PVEC, 
                                     pixel non-drawing vectors in PVEC

no            yes  no       no       15 bit drawing vectors in PVEC, 
                                     15 bit non-drawing vectors in PVEC, 
                                     pixel non-drawing vectors in PVEC

yes           yes  yes      yes      pixel vectors in PVEC

yes           yes  yes      no       pixel vectors in PVEC

yes           yes  no       yes      pixel vectors in PVEC

yes           yes  no       no       pixel vectors in PVEC

yes or no     no   yes      yes      invalid

yes or no     no   yes      no       invalid

yes or no     no   no       yes      pixel vectors in FDRAW, both solid and
                                     dashed pixel vectors in PVEC

yes or no     no   no       no       pixel vectors in PVEC


It is highly recommended that ADI 4.2 display list drivers offer their
users configuration-time options to turn on and off the display list
features (EF_BS) and the 31-bit feature (EF_BIGVEC) so that the user can
make tradeoffs of speed for memory. This means that your BS driver should
have code to support both FASTDRAW and PBATCHVEC (only BIGVEC drivers
receive PBATCHVEC).

FAKE_BS drivers should set EF_BIGVEC and should provide support for the
BIGVEC packets: POPENBVP, PBVIEWPORT, PBMARK, PCBMARK, PBFILL.

If a FAKE_BS driver fails to set EF_BIGVEC, it needlessly forces AutoCAD
into 15-bit mode.

FAKE_BS drivers will not see any input from FASTDRAW or PBATCHVEC because
these only supply drawing vectors to drivers which leave the NO_BS bit
clear in PBVIEWPORT..

6.5.2 (Almost) Everything Logical
=================================

Any ADI driver which identifies itself as a BS driver and as ADI 4.2 or
newer gets "(almost) everything logical". In all viewports, all drawing and
nondrawing vectors, cursors and grid dots are in the same coordinate system
(except for AUI cursors, AUI vectors and viewport borders, which are always
in viewport independent pixel coordinates). Note that there are two
possible logical coordinate systems in AutoCAD Release 12: BIGVEC and the
old 15-bit logical space.

FAKE_BS and non-BS drivers still get everything in pixel coordinates. BS
drivers which have some NO_BS viewports get everything in pixel coordinates
in the NO_BS viewports and everything logical in BS viewports.

Sending all of the vectors in each viewport in the same coordinate system
helps eliminate pixel-off-by-one errors. However, there is still one
problem area remaining in AutoCAD. Internally, AutoCAD computes digitizer
coordinates in pixel coordinates. These are converted into logical
coordinates for BS drivers, with a procedure which computes the logical
center of the pixel in question. Grid and snap values are initially
computed in floating point display space and are then converted to logical
coordinates. It is still possible for there to be a fraction of a pixel
misalignment between Snap and cursor coordinates.

Note that some Autodesk products do not make use of display list features
and thus do not send logical vectors. These products send everything in
pixel (viewport 0) vectors. Most older products which do not support
display lists also do not bother to send viewport numbers in packets -- you
can't count on getting vpnumber = 0; thus, display list drivers should
notice which product is running and disable all display list features if
AutoCAD is not present.


6.6 Optional Text Window on P386 Graphic Screen
===============================================

If a P386 ADI driver returns DM_GROKE, text screen output is sent through
PCHAR instead of through DOS (unless the user has used the Shell command,
which really switches console output to DOS). The driver is responsible for
opening a text window on receipt of PGOTEXT or PGOTEXTU and writes PCHAR
characters to the text window until the next PGOGRAPH. Unlike the other
uses of PCHAR, each character must be written to the screen immediately,
without waiting for PECHAR. Drivers which support this feature need to set
EF_SHELL to get Shell command notifications so they can switch to the real
text screen for Shell operations.

The sample driver rcpvesa2 supports this feature for testing purposes.


6.7 Natural and Biased Coordinates
==================================

For most display boards, natural Y (also known as "ULS") pixel coordinates
have their origin at the upper left corner of the screen. Autodesk products
also use biased Y coordinates ("LLG" coordinates) that place the origin at
the lower left corner of the drawing area (which may not be the lower left
corner of the screen due to the possible presence of the text-scrolling
area below the graphics area).

Generally, ADI requests used in an actual drawing are in biased Y
coordinates. ADI requests involving the Advanced User Interface use natural
Y coordinates. Thus, natural Y coordinates are used in displaying the menu
bar and the line under it, in creating pull-down menus, dialogue boxes, and
in displaying the arrow cursor that is part of the advanced user interface.

The following ADI commands are used only as part of the Advanced User
Interface and use natural Y (ULS) coordinates:

PBOXSIZE
PBOXPUSH
PBOXPOP
PLINE
PDCURS
PCCURS

The following commands use biased Y (LLG) coordinates:

PDOT
PVEC
PFILL
PMARK
PCMARK
FASTDRAW


6.8 Screen Size
===============

To enable the Autodesk product to calculate proper display aspect ratios
for your device, your driver must supply the Autodesk product your device's
screen pixel size data, usually at configuration time. Two structure
members, pixwid and pixhgt are found in several initialization packet
structures depending on the type of device your driver supports. (See the
PINIT and RDINIT packets.)

The pixwid member is the screen pixel width and the pixhgt member is the
screen pixel height. The ratio between these two values your driver
provides allows the Autodesk product to calculate the correct aspect ratio.

To find the physical screen size, either use a ruler to measure the actual
size, or use the display's specified aspect ratio as screen size, then
compute the actual size of a pixel (screen size/# of pixels) and reduce to
as small an integer as practical, maintaining proportion between X and Y.

Some common video monitor aspect ratios (width:height) are as follows:

VGA             4:3
EGA             4:3
IBM monochrome  3:2

The following equations calculate pixwid and pixhgt for the VGA (high-
resolution mode) and EGA displays.

EGA example calculation:

(4 / 640) / (3 / 400) =
(4 * 400) / (3 * 640) =
          1600 / 1920 = 5 / 6

Thus, pixwid = 5 and pixhgt = 6.

High-resolution VGA example calculation:

(4 / 640) / (3 / 480) =
(4 * 480) / (3 * 640) =
          1920 / 1920 =
          1

Thus, pixwid = 1 and pixhgt = 1.

Monochrome Hercules Graphics Card using an IBM monochrome display:

(3 / 720) / (2 / 350) =
(3 * 350) / (2 * 720) =
          1050 / 1440 = 35 / 48

Thus, pixwid = 35 and pixhgt = 48. Note that we use 350 for the number of
scanlines, even though the Hercules Graphics Card supports only 348. We
used the 350 figure because the 3:2 aspect ratio is defined for 350.


6.9 Tilemode and Multiple Viewports
===================================

A feature introduced in AutoCAD Release 11, Multiple Viewport Plotting, has
impact on display list (BS) ADI drivers. Before AutoCAD Release 11,
viewports were tiled (they did not overlap). It is now possible for the
user to turn TILEMODE off, allowing the viewports to be moved so they
overlap.

You should think of the viewports in AutoCAD Release 11 as transparent,
unlike the windows in many operating systems. When several viewports
overlap, the user should be able to see all of the contents of all of the
viewports. There is no concept of a "top" and "bottom" viewport.

ADI drivers which clear viewports without AutoCAD's knowledge do not work
well when TILEMODE is off. Several enhancements have been made to the ADI
interface to encourage you to inform AutoCAD of all of your driver's
actions (so that future changes in AutoCAD will be less likely to break ADI
drivers).

When a viewport is redrawn with TILEMODE off, it may overlap parts of other
viewports. Provision has been made for partial viewport Redraw requests
which speed up the repair of damage caused by such operations. Viewports
can be moved and resized by the user. An ADI packet is provided to allow a
viewport to be "reopened" with a new size and/or location so that your
driver can reuse its existing display list whenever possible.

If you are developing a BS (display list) driver, you must return EF_MV,
EF_PROVP and EF_BS in the PINIT packet. Your driver must handle the PREDRAW
RE_XXX flags. If you use the PSTRING packet, you must use the pknstring
structure that makes up the PSTRING packet instead of the older pkstring
structure. And your driver must handle the PROPENVP packet and must return
the PMAXVP packet. You can use PKZOOM and the new PSYNC packet features if
the EF_SYNC flag is returned in the PINIT packet.

Other packets that were modified from ADI 4.0 include PLOPEN, PKZOOM, and
PREVEC. You should review every packet used in your driver when updating or
modifying an existing ADI driver. Refer to the packet descriptions for
detailed information on each packet.


6.10 Working with DESQview
==========================

It is possible to run AutoCAD 386 under DESQview. You can check to see if
DESQview is running by using INT 21 function 0x28, subfunction 0x01,
setting the date to "DESQ." If DESQview is not installed, an error flag
(0xff) is returned in the AL register. If DESQview is installed, a version
number is returned in the same register.

If you would like your driver to work under DESQview, here are some
considerations:

  * If DESQview is installed, you cannot use any extra memory present in
any video card recognized by DESQview to store data for flip screens or box
pushes. You must allocate memory with the malloc() function instead.

  * Use DOS BIOS calls to set the video mode if at all possible, since this
keeps DESQview informed. However, note that the "don't wipe" bit is not
effective under DESQview.

These two restrictions (using extra video card memory and using BIOS calls
to set video modes) may be lifted in a later version of DESQview. Also, be
sure to test your driver under DESQview.


6.11 Shell Command Notification
===============================

Notification that AutoCAD is executing a Shell command is essential for ADI
display drivers that are subject to having their graphics area or
controller state altered by a Shell program. Notification is accomplished
through the BSHELL (before shell) and ASHELL (after shell) requests.

It is also common practice to set a flag that results in repainting the
screen on the next PGOGRAPH request if there is danger that the Shell
program may have altered the screen buffer contents.

AutoShade does not use the ASHELL or BSHELL packets, because it does not
shell out.


6.12 Developing and Testing Your Driver
=======================================

We suggest that you develop your ADI driver in stages. You might start off
by modifying one of the provided sample drivers. For example, implementing
and debugging a stripped-down driver and adding features one at a time.

For example, these steps might be appropriate to implement a display list
driver:

1)        Implement and debug a non-display list ADI driver without
          FASTDRAW, using a sample P386 ADI as a guide.

2)        Implement and debug FASTDRAW and/or PBATCHVEC.

3)        Implement and debug your display list.

4)        Implement and debug optional features.

A set of files for testing graphics display drivers is included in the
ADIKIT. These files use the AutoLISP LISP interpreter built into AutoCAD.
You can find ASCII documentation of the ADI 4.0 display tests starting at
line 5016 of 40adi.doc on the CDROM. ADI 4.1 display testing (dststr11)
documentation is in dstest.doc in the \41brlmd\dststr11 directory.

We expect to release dststr12 in the future. Look on CompuServe for this
software.

6.13 Configuration
==================

Chapter 3, ADI Implementation, describes how drivers are located and
loaded. See table 3-1 for environment variable and magic filenames, and the
"Driver Selection" section for a discussion on how AutoCAD Release 12
selects drivers (improved from AutoCAD Release 11).


6.14 Packet Sequence
====================

You should not write a driver that relies on receiving packets in a
specific sequence from the host product. The sequence can vary greatly
depending on the state of the host, as well as the sequences are likely to
change as the host products and ADI are revised. Since new drivers are
never updated as rapidly as Autodesk products are, it is very desirable for
old drivers to be able to work with new products.

For most purposes, it is useful to consider configuration time and
execution time as totally separate environments. The packet descriptions
indicate whether the packet is a configuration-time or execution-time
packet.

It is likely that new packets will be added to this and other sequences.
This is why it is important that drivers silently ignore unrecognized
packets. The guarantee is that PCFGREC happens before PINIT, and PLANG, if
present, also happens before PINIT. The sequence of packets following PINIT
varies so much depending on your driver's responses in PINIT and depending
on AutoCAD's state, that it is not useful to try to predict. You can
examine typical packet sequences by making packet traces to a log file with
the sample display drivers and the TEE driver.

AutoCAD Release 12 contains two new commands which affect PINIT and PTERM:
Config and Reinit. When Config is invoked, an ADI display driver gets
PTERM, PKILL and is unloaded. If Rconfig is invoked from AVE Render, a
DEV_RC driver receives RDTERM, PTERM, PKILL and is unloaded. After
configuration, the driver is reloaded and completely reinitialized.


6.15 FASTDRAW (Fast Vector Mode)
================================

Limitations
-----------
FASTDRAW is not a packet. In any case, secondary applications should not
use FASTDRAW if talking to a BS driver because secondary applications
should not send "drawing" vectors to a display list driver. Use PVEC or
PLINE instead, sending non-drawing vectors.

History
-------
FASTDRAW was introduced in ADI 3.0. It is replaced by PBATCHVEC for ADI 4.2
BIGVEC drivers.

Discussion
----------
We strongly recommend that all ADI 4.2 BS drivers be user configurable as
15-bit or BIGVEC. This means your BS driver should have code to support
both FASTDRAW and PBATCHVEC.

AutoCAD is the only Autodesk product to make use of FASTDRAW at this time.

The PBATCHVEC packet replaces the FASTDRAW feature for BIGVEC drivers (only
BIGVEC drivers receive PBATCHVEC).

FASTDRAW passes time-critical vector information from AutoCAD to your
driver in an extremely efficient manner to allow your display driver to
draw vectors faster than would be possible under normal ADI packet mode
interface operation. FASTDRAW is also referred to as Fast Vector Mode.

Because FASTDRAW is used only for time-critical vectors, your FASTDRAW
routine does not completely replace any existing ADI packets. All of the
code for handling packets in your driver continues to be used by AutoCAD.
We recommend that you first develop and thoroughly test your driver in
packet mode before you upgrade your driver to using FASTDRAW.

Your driver's FASTDRAW vector drawing routine must be coded in assembly
language, and it is essential that your code conform precisely to these
specifications, or unreliable and possible random crashes of AutoCAD can
occur.

6.15.1 XOR Vectors
==================

FASTDRAW is not used for XOR vectors, except in the case of AutoCAD for
Windows Release 11, (XOR vectors are handled by PVEC). You can usually
realize a significant increase in the speed of your FASTDRAW routine by
leaving out XOR vector handling code. In fact, your FASTDRAW routine is an
excellent place for optimization, where how well you optimize your code can
directly correlate to the fastest draw times possible.

6.15.2 Enabling FASTDRAW
========================

With FASTDRAW enabled, drawing vectors are sent directly from AutoCAD to
your driver's FASTDRAW vector drawing routine, bypassing the AutoCAD core-
side ADI driver and your driver's packet handler. FASTDRAW is turned on by
setting the EF_FDRAW flag in the PINIT reply packet. Recall that when you
enable FASTDRAW, you must also return the address of your FASTDRAW routine
in the PINIT reply packet (in the pfdraw member). Please see the PINIT
packet description.

6.15.3 AutoCAD To Driver Communication
======================================

AutoCAD calls your FASTDRAW vector drawing routine by pushing the arguments
for the vector onto the stack, calling an internal local function, and then
calling your driver's routine. You should take careful notice of the vector
arguments positions in the stack when your driver's routine gains control.

Before sending vectors to your driver via FASTDRAW, AutoCAD determines the
arguments to be passed and the type of vectors to be sent in PVEC.

AutoCAD Release 11 for Windows uses a hard-coded entry point for FASTDRAW.
This is named dsfast_vector().

On other platforms, the FASTDRAW entry point is a far address passed in
PINIT.

6.15.4 Argument Determination (AutoCAD for Windows)
===================================================

AutoCAD Release 11 for Windows calls dsfast_vector with the following
arguments:

extern window gfx;
POINT pVect[2];
short color, hilight, nodraw;
dsfast_vector(&gfx, pVect, color, hilight, nodraw);

6.15.5 Argument Determination (AutoCAD 386)
===========================================

The arguments pushed onto the stack for each vector passed via FASTDRAW
follow a calling sequence which is described below. The first argument
pushed by AutoCAD onto the stack can be either a flag indicating the vector
is a nondrawing vector, or the viewport number. All the other arguments are
always pushed in the same order.

AutoCAD determines the first argument by checking the EF_BS bit flag which
was returned in the PINIT reply packet. See the PINIT packet description
for details about the EF_BS bit flag.

If EF_BS was returned clear, the non_drawing_flag argument is pushed
instead of vpnumber. For display-list drivers, the non_drawing_flag
identifies vectors which should not be saved on the local display list.

If EF_BS was set, the first argument pushed is the viewport number
(vpnumber). In this case, FASTDRAW sends only drawing vectors to your
FASTDRAW routine and nondrawing vectors via PVEC and PLINE.

6.15.6 Vectors Via PVEC And PLINE
=================================

As mentioned above, FASTDRAW does not completely replace the use of packets
to send vectors to your driver. Only drawing vectors are sent via FASTDRAW.
The PVEC and PLINE packets handle vectors which are not sent through
FASTDRAW.

The PLINE packet handles nondrawing AUI vectors, the same as if FASTDRAW
were not enabled.

The type of vectors sent via PVEC depend on whether the viewport being
drawn has the NO_BS flag (in the PVIEWPORT packet) set. Please refer to the
PVIEWPORT packet description for information about the NO_BS flag.

If NO_BS is clear, drawing vectors arrive via FASTDRAW and are the only
vectors that should be saved on your local display list; PVEC and PLINE
receive nondrawing vectors.

If NO_BS is set, drawing vectors for the NO_BS viewport are sent via PVEC,
not FASTDRAW. Drawing vectors arriving through PVEC do not get added to
your local display list, if you have one.

To summarize, whenever FASTDRAW is enabled, drawing vectors are sent via
FASTDRAW, with PVEC and PLINE receiving only nondrawing vectors. The only
exception is for NO_BS viewports, in which case PVEC receives "drawing"
vectors which are scaled in pixel coordinates, tagged as non-drawing and
are not saved in a display list.

6.15.7 Calling Sequence
=======================

AutoCAD uses a different calling sequence for calling protected-mode ADI
drivers than for calling real-mode ADI drivers. The calling sequence
described here is for protected-mode ADI drivers. Refer to the real-mode
ADI specification (adi41.doc) for the details of the FASTDRAW calling
sequence.

Every argument pushed onto the stack occupies 4 bytes. Note that most
arguments are really only shorts, so there are two bytes of uninitialized
data pushed onto the stack for the high 2 bytes of these arguments. AutoCAD
uses the following instruction sequence to call your driver's FASTDRAW
routine (shown here is pseudocode affecting the state of the stack):

push  [vpnumber]               ;push arguments onto stack
push  [hilight]
push [color]
push [to_y]
push [to_x]
push [from_y]
push  [from_x]
call  tofdraw                  ;call AutoCAD's local function
...                            ;code not affecting the stack
tofdraw proc near              ;AutoCAD's procedure
push  edi
...                            ;code not affecting the stack
mov   edi, (driver's DS)       ;load DI with driver's DS value
call far [pfdraw]              ;call the driver's FASTDRAW routine

The state of the stack upon entry to your driver's FASTDRAW routine is
important. Before you push EBP (assuming you follow the standard convention
of saving the stack frame pointer), the first argument is 16 bytes up the
stack upon entry into your FASTDRAW routine. Saving the stack frame pointer
increases this to 20 bytes.

The following code fragment continues the pseudocode sequence from above,
only now viewed from the ADI driver's side:

pfdraw proc far
    push ebp                   ;save frame pointer
    mov  ebp, esp
    ...                        ;your driver's FASTDRAW routine

This would be the state of the stack upon entry to your driver's FASTDRAW
routine: assuming you saved the stack frame pointer as shown above:

    --- STACK ---
Contents         Bytes
    (top)   ...                ;arguments
from_x            4            ;first argument
retadr offset     4            ;AutoCAD's local call of tofdraw
edi               4            ;pushed by ACAD's tofdraw function
retadr selector   4            ;AutoCAD's far call to your driver
retadr offset     4            ;the far call to your driver
ebp               4            ;frame pointer (driver pushed)

If you want to use "args" (defined in p386.mac as [ebp+8]) to point to the
first argument, you can either do an "add ebp,12" and "args" will then
point to the first argument, or you can merely use "args+12" to point to
the first argument.

6.15.8 Argument Descriptions
============================

[non_drawing_flag] (short)
--------------------------
Pushed if EF_BS was returned clear in the PINIT reply packet. The
non_drawing_flag is 1 if TRUE and 0 if FALSE. This flag is used to identify
vectors which should NOT be saved in a local display list.

[vpnumber] (short)
------------------
Pushed if EF_BS was returned set in the PINIT reply packet. The vpnumber
argument is always nonzero.

[hilight] (short)
-----------------
The hilight argument is 1 if TRUE and 0 if FALSE. If hilight is TRUE, the
vector should be highlighted (usually by drawing it with a dashed line
font).

[color] (short)
---------------
The color argument is 0 to erase a vector or a positive value to specify
one of the standard color numbers used by Autodesk products (see appendix
A).

[to_x], [to_y], [from_x], [from_y] (short or int)
-------------------------------------------------
These are shorts or ints depending upon the platform. Your driver should
draw a vector from (from_x,from_y) to (to_x,to_y) in the color specified by
the color argument.

6.15.9 Vector Coordinate Systems
================================

FASTDRAW
--------
If EF_BS was set, and EF_BIGVEC was not set, vectors sent via FASTDRAW are
in 15 bit logical viewport-relative coordinates. You must perform any
necessary clipping and scaling. If EF_BS was not set, vectors sent via
FASTDRAW are in LLG viewport-independent coordinates.

PVEC
----
When FASTDRAW is temporarily disabled for a NO_BS viewport, both drawing
and nondrawing vectors are be sent via PVEC in LLG viewport-independent
coordinates. When FASTDRAW is enabled and functioning, most nondrawing
vectors sent via PVEC are in logical viewport-relative coordinates.
Viewport borders are sent in pixel coordinates.

PLINE
-----
Vectors sent via PLINE are in ULS "Natural Y" coordinates.

6.15.10 Register Values On Entry To FASTDRAW
============================================

When AutoCAD makes the far call to your FASTDRAW routine, every register is
set to AutoCAD's values except the CS and DI registers. The CS register
contains your code segment selector. The DI register contains your data
segment selector, which you must copy into DS so you can access your data.
You must preserve and restore all other registers that you change.

Do NOT assume that DS, ES, and/or SS are equal upon entry to your FASTDRAW
routine! DS and ES are undefined. Some compilers may make this assumption
and can cause serious problems. For example, the MetaWare High C malloc()
function assumes that DS, ES, and SS are equal. If you develop with High C,
and use the malloc() function from your FASTDRAW assembly code, you should
set up a local stack in your data segment to make DS, ES, and SS equal to
your local data segment. We have not used malloc() in our sample FASTDRAW
routine.

6.15.11 Example
===============

A sample FASTDRAW routine is implemented in the fdraw procedure in the
DSPGAA42.ASM module which is part of the DSPEGA42 sample driver.


6.16 ADI Display Packets
========================

The following packets have been added in ADI 4.2:

PVPAGE          Selects video pages
PDINFO          Provides display mode driver information
PBIGBLIT        Saves & restores bitmap image
PDIGTIZE_42     Monitors or alters digitizer samples
PRPEN_42        Reads screen-pointing device (replaces PRPEN)
PTABCFG_42      Coords of digitizer screen-pointing area &
                driver info
PKILL           Notification that AutoCAD is terminating
PCBMARK         Clears cursor at 31-bit logical coordinates
PBVIEWPORT      Specifies visible portion of viewport's 31-
                bit logical space
PBATCHVEC       Replaces FASTDRAW for 31-bit vectors
PBDRAG          31-bit drag vectors
PBFILL          31-bit polygon fills
PBIGVEC         31-bit logical vector
PBMARK          Draws 31-bit logical cursor
PKBZOOM         Requests Pan/Zoom in 31 bit integer coords
POPENBVP        Opens a BIGVEC viewport
PROW            Draws 1 row of grid dots using XOR
PPAL            Saves or restores a palette

The following two tables show ADI display packet usage. The first table
shows packet usage for AutoCAD, across platforms for releases 11 and 12.
The second table shows packet usage for the other applicable Autodesk
products, AutoShade and 3D Studio. For a very brief description of what
each packet does, see the "Comments" column in the second table; the
packets are listed identically in both tables. The key to the symbols used
in the following two tables is in the table following these packet usage
tables.

Table 6-3. AutoCAD display packet usage

Packet            386  SPARC  386  SPARC  Win  Mac
                  R12   R12   R11   R11
---------------------------------------------------
BPLINE            -     -     -     -     x      -
PASHELL           o     o     o     o     o      o
PBATCHVEC         o BS  o BS  -     -     -      -
PBDRAG            o BS  o BS  -     -     -      -
PBFILL            o BS  o BS  -     -     -      -
PBIGBLIT          x     x     -     -     -      -
PBIGVEC           BS    BS    -     -     -      -
PBITBLT           x     x     o     o     -      -
PBMARK            BS    BS    -     -     -      -
PBOXCLR           x     x     x     x     -      -
PBOXPOP           x     x     x     x     -      -
PBOXPUSH          x     x     x     x     -      -
PBSHELL           o     o     o     o     o      o
PBVIEWPORT        BS    BS    -     -     -      -
PCBMARK           BS    BS    -     -     -      -
PCCURS            x     x     x     x     -      -
PCFGREC           x     x     x     x     x      x
PCHAR             x     x     x     x     x      x
PCHGCFG           x     x     x     x     x      x
PCLEAR            x     x     x     x     x      x
PCLOSEVP          bs BS bs BS bs    bs    bs     bs
PCLVP             nobs  nobs  nobs  nobs  nobs   nobs
PCMARK            x     x     x     x     -      -
PCOMMAND          o     o     o     o     o      o
PCOORDLINE        x     x     x     x     x      x
PDCURS            x     x     x     x     -      -
PDHLITE           x     x     x     x     x      -
PDIGTIZE          -     -     o     o     o      o
PDIGTIZE_42       o     o     -     -     -      -
PDINFO            x     x     -     -     -      -
PDLFNAME          -     -     -     x     -      -
PDLDIR            -     -     -     x     -      -
PDOT              x     x     x     x     x      x
PDRAG             o     o     o     o     o      o
PECHAR            x     x     x     x     x      x
PEVENT            -     x     -     x     -      -
PFILL             o     o     o     o     o      o
PFLUSHCHAR        -     -     -     -     x      -
PGOGRAPH          x     x     x     x     x      x
PGOTEXT           x     x     x     x     x      -
PGOTEXTU          x     x     x     x     x      -
PHLITE            x     x     x     x     x      -
PINIT             x     x     x     x     x      x
PKBZOOM           o BS  o BS  -     -     -      -
PKILL             x     x     -     x     -      -
PKZOOM            o bs  o bs  o bs  o bs  o bs   o bs
PLANG             x     x     -     -     -      -
PLINE             x     x     x     x     x      -
PLOPEN            bs    bs    bs    bs    bs     bs
PMARK             x     x     x     x     -      -
PMAXVP            bs BS       bs BS       bs     bs   bs    bs
PMNUCURS          x     x     x     x     x      -
PMENUFCN          -     x     -     x     -      -
PMENUGET          -     x     -     -     -      -
PMENUSET          -     x     -     -     -      -
PMENUSHOW         -     x     -     x     -      -
PMODELINE         x     x     x     x     x      -
PMODEMSG          -     x     -     x     -      -
PMSGBOX           -     x     -     x     -      -
PNEWCFG           x     x     x     x     x      x
PNOP              -     -     -     -     -      -
PNOTIFY           -     x     -     x     -      x
POPENBVP          BS    BS    -     -     -      -
POPENVP           bs    bs    bs    bs    bs     bs
PPAL              x     x     -     -     -      -
PQPLOT            o     o     o     o     o      o
PRCMAP            x     x     -     -     -      -
PREDRAW           bs BS       bs BS       bs     bs   bs    bs
PREINIT           -     x     -     x     x      x
PREVEC            bs BS       bs BS       bs     bs   bs    bs
PROPENVP          bs BS bs BS bs    bs    bs     bs
PROW              BS    BS    -     -     -      -
PRPEN             -     -     o     o     -      x
PRPEN_42          o     o     -     -     -      -
PSHOWCFG          x     x     x     x     x      x
PSTRING           o     o     o     o     x      x
PSYNC             o     o     o     o     o      o
PTABCFG           -     -     o     o     o      o
PTABCFG_42        o     o     -     -     -      -
PTERM             x     x     x     x     x      x
PTEXT             x     x     x     x     -      -
PTPROMPT          o     o     o     o     -      -
PTXTCLR           -     -     -     -     -      -
PTXTCHAR          -     x     -     x     x      -
PTXTSHOW          -     -     -     -     -      -
PVEC              x     x     x     x     x      x
PVIEWPORT         bs    bs    bs    bs    bs     bs
PVPAGE            o     o     o     o     -      -
PWHO              x     x     -     -     -      -
PWINRESTORE       -     -     -     -     x      -
PWINSAVE          -     -     -     -     x      -
PWRSPLIT          x     x     x     x     x      x
PXPCOMD           o     o     o     o     o      o


The following table shows ADI display packet usage for Autodesk products
other than AutoCAD: AutoShade and 3D Studio. The entries in the 3D Studio
column indicate which version of 3D Studio the packet is supported in.

Table 6-4. Display packet usage

Packet        SHADE   3DS version   Comments
-------------------------------------------------------------
BPLINE           -     -        Send polyline
PASHELL          -     2        Shell command complete
PBATCHVEC        -     -        Replaces FASTDRAW for 31-bit vectors
PBDRAG           -     -        31-bit drag vectors
PBFILL           -     -        31-bit polygon fills
PBIGBLIT         -     -        Saves & restores bitmap image
PBIGVEC          -     -        31-bit logical vector
PBITBLT          -     1,2      Draw bit-mapped image on graphic screen
PBMARK           -     -        Draws 31-bit logical cursor
PBOXCLR          d     1,2      AUI-clear box to specified color
PBOXPOP          d     1,2      AUI-pop box from stack
PBOXPUSH         d     1,2      AUI-save box on stack
PBSHELL          -     2        Shell command starting
PBVIEWPORT       -     -        Visible portion of viewport (31-bit)
PCBMARK          -     -        Clears cursor at 31-bit logical coords
PCCURS           d     1,2      Clear raster cursor
PCFGREC          x     1,2      Configuration record
PCHAR            -     -        Draw text char at text cursor position
PCHGCFG          x     2        Change config record
PCLEAR           d     1,2      Clear graphics screen
PCLOSEVP         -     -        Close viewport
PCLVP            -     -        Fast clearscreen
PCMARK           d     -        Clear graphics cursor
PCOMMAND         -     -        Execute driver-implemented command
PCOORDLINE       -     -        Move text cursor to coordinate line
PDCURS           d     1,2      Draw raster cursor
PDHLITE          -     -        Dehighlight screen menu box
PDIGTIZE         -     -        Digitizer input
PDIGTIZE_42      -     -        Monitors or alters digitizer samples
PDINFO           -     -        Provides display mode driver information
PDLFNAME         -     -        Display a get file dialogue box
PDLDIR           -     -        Display a get directory dialogue box
PDOT             d     -        Grid dots
PDRAG            -     -        Manipulate drag lists
PECHAR           -     -        End of text
PEVENT           -     -        Mouse & keyboard events
PFILL            d     -        Solid fill; smart devices only
PFLUSHCHAR       -     -        Display buffered characters
PGOGRAPH         d     1,2      Flip to graphic screen
PGOTEXT          -     1,2      Flip to text screen, clear
PGOTEXTU         -     -        Flip to hidden text screen, display text
PHLITE           -     -        Highlight screen menu box
PINIT            d     1,2      Initialization
PKBZOOM          -     -        Request Pan/Zoom (31-bit)
PKILL            -     2        Notification that AutoCAD is terminating
PKZOOM           -     -        Request Pan/Zoom in integer coordinates
PLANG            -     2        Language
PLINE            -     1        AUI-draw line
PLOPEN           -     -        Specify viewport in floating-point space
PMARK            d     -        Draw graphics cursor
PMAXVP           -     -        Set max open viewports
PMNUCURS         -     -        Move text cursor to screen menu box
PMENUFCN         -     -        Construct a screen menu
PMENUGET         -     -        Gets screen menu item attributes
PMENUSET         -     -        Sets screen menu item attributes
PMENUSHOW        -     -        Display screen menu
PMODELINE        -     -        Move text cursor to status line
PMODEMSG         -     -        Write string to graphic window title bar
PMSGBOX          -     -        Display dialogue or alert box
PNEWCFG          x     1,2      New configuration record
PNOP             -     -        Place holder in common memory buffer
PNOTIFY          -     -        Driver notification of events
POPENBVP         -     -        Opens a BIGVEC viewport
POPENVP          -     -        Open viewport
PPAL             -     -        Saves or restores a palette
PQPLOT           -     -        Dump graphics screen to printer
PRCMAP           -     -        Reads color map
PREDRAW          -     -        Redraw graphics screen
PREINIT          -     -        Reinitialization
PREVEC           -     -        Change viewport from BS to NOT_BS
PROPENVP         -     -        Reopen a viewport
PROW             -     -        Draws 1 row of grid dots using XOR
PRPEN            -     -        Read light pen
PRPEN_42         -     -        Read screen-pointing device
PSHOWCFG         -     2        Show configuration record
PSTRING          -     -        Driver-submitted commands
PSYNC            -     -        Sync local display list with product
PTABCFG          -     -        Supply coords of screen pointing area
PTABCFG_42       -     -        Supply coords of screen pointing area
PTERM            d     1,2      Terminate
PTEXT            dru   1        AUI-draw raster text
PTPROMPT         -     -        Move cursor to prompt line (dual screen)
PTXTCLR          -     -        Clear the text screen
PTXTCHAR         -     -        Text-mode display characters
PTXTSHOW         -     -        Show or hide the text screen
PVEC             dru   1,2      Draws vectors, arrow cursor in AUI
PVIEWPORT        -     -        Respecify viewport in logical space
PVPAGE           -     -        Selects video pages
PWHO             x     2        ID controlling product
PWINRESTORE      -     -        Restore graphic screen
PWINSAVE         -     -        Save graphic screen
PWRSPLIT         -     -        Write text char to text scrolling area
PXPCOMD          -     -        <Ctrl-L> initiated transparent operation


Table 6-4c. Display packets table key
-------------------------------------
Code          Definition

-             Not used

bs            Indicates usage by Big Screen drivers only

x              Indicates usage by all drivers

o             Indicates optional usage

BS            31 bit BS

nobs          Only used by non-display list drivers

d             Display screen (AutoShade)

r              Rendering screen (AutoShade)

u              Display driver command that may be sent during rendering
(after RDSTART)


6.16.1 Packets Used Only by AutoCAD
===================================

At the moment, AutoCAD is the only Autodesk product that makes use of
display lists. There are quite a few packets, mostly display list packets,
which are only sent by AutoCAD and not by other products. Here is a list:

PBATCHVEC
PBFILL
PBMARK
PBVIEWPORT
PCBMARK
PCLOSEVP
PCOMMAND
PCOORDLINE
PDIGTIZE
PDIGTIZE_42
PDRAG
PHLITE
PKBZOOM
PKZOOM
PLOPEN
PMAXVP
PMODELINE
POPENBVP
POPENVP
PQPLOT
PREDRAW
PREVEC
PROW
PTABCFG
PTABCFG_42
PTPROMPT
PVIEWPORT
PWRSPLIT
PXPCOMD

6.17 Display Packet Descriptions
================================

This section provides full descriptions of the ADI display packets.

6.17.1 BPLINE
===============

Purpose
-------
BPLINE is used to speed up vector drawing by sending a polyline.

Limitations
-----------
BPLINE is a display packet supported by Windows ADI 4.1 DEV_DS and DEV_RC
drivers in display mode.

This is a display packet. It can be sent only to DEV_DS or DEV_RC drivers.
It can be sent only in graphic mode after PINIT.

All the fields in this packet are filled in by AutoCAD. The driver treats
this as a read-only packet.

History
-------
This packet was introduced in ADI 4.1 for Windows.

Declaration
-----------
#define BPLINE  133                   /* Draw polyline */

packed struct bpkline {
    short pfunc;                       /* Function code */
    short vpnumber;
    short pcolour;                             /* Color */
    short pdrawm;                      /* Drawing modes */
    short npoints;                  /* Number of points */
    POINT points[2];        /* Start with 2 point array */
};

Description
-----------
AutoCAD for Windows Release 11 makes an attempt to batch up vectors which
are destined for the same viewport, which share the same color and pdrawm
value, and which form a connected polyline. The result is a BPLINE packet.

It is possible for pixel or logical, drawing or nondrawing vectors to
arrive here.

If vpnumber is non-zero, the vectors are viewport-specific logical.
Otherwise they are LLG pixel vectors. If pdrawm has the DR_NORDRW bit set,
these are non-drawing vectors.

The member npoints indicates the number of vertices in this polyline.



6.17.2 PASHELL
================

Purpose
-------
PASHELL is an optional packet which notifies the driver that a SHELL
command has completed.

Limitations
-----------
PASHELL is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. Drivers indicate support for this packet by returning
EF_SHELL in PINIT.pefmodes and PDINFO.pefmodes.

Secondary applications should not have to send this packet because they
should not shell out (unless they use a facility of the primary product to
shell out, in which case the primary product takes care of sending PBSHELL
and PASHELL).

Primary products should send PBSHELL and PASHELL to any driver which
requests it by setting EF_SHELL. Existing products which don't send shell
packets also don't shell out.

All of the fields in this packet are filled in by AutoCAD. The driver
treats this as a read-only packet.

History
-------
PASHELL was added in ADI 3.1 to support Release 9 AutoCAD. There was a
variant of this packet in ADI 4.0 for SCO XENIX which added a repaint
member. The repaint member was later dropped.

Declaration
-----------
#define PASHELL  36

struct pkfonly {
    short  pfunc;          /* PASHELL */
};

Description
-----------
The PASHELL request is issued when a Shell command has completed, if
EF_SHELL (bit 8) was set in the member pefmodes field of the PINIT reply
packet to let the Autodesk product know that the driver wants to be
informed of Shell commands.

Any system resources that the user may have changed during the shell out
should be assumed to have been corrupted, and your driver should restore
the proper settings.

For example, LIM-EMS page mappings, video mode settings, and values stored
in the registers should be retained and restored if the driver utilizes
those resources.

Note that it is not a good idea for a secondary product to shell out on its
own. You should use AutoCAD's command throat to let AutoCAD do the work of
shelling out - AutoCAD takes care of notifying drivers and other cleanup
actions.

Drivers doing DM_GROKE (DOS text window on the graphic screen) have the
option of returning to the DOS window on the graphic screen at this time
(copying the contents of the real text screen to the DOS window) or
remaining on the real text screen until the next PGOGRAPH (in which case
PCHAR requests must be forwarded to DOS between PASHELL and PGOGRAPH).

See Also
--------
PBSHELL



6.17.3 PBATCHVEC
==================

Purpose
-------
This optional packet replaces FASTDRAW for 31-bit vectors.

Limitations
-----------
PBATCHVEC is used only to send drawing vectors and can be sent only to ADI
4.2 BIGVEC DEV_DS or DEV_RC drivers while the driver is in display mode and
on the graphic screen. This is an optional packet and is supported only by
BIGVEC drivers which request "FASTDRAW", i.e., drivers which set
PINIT.pefmodes EF_BIGVEC and EF_FDRAW.

Secondary applications should not use this packet because they should not
send drawing vectors.

All the fields in this packet are filled in by AutoCAD. The driver treats
this as a read-only packet.

History
-------
Added in ADI 4.2.

Declaration
-----------
#define PBATCHVEC 97     /* batches 31-bit vectors */
#define VBATCH 22        /* max # vectors in one batch */

struct vecspec {
    short color;         /* vector color */
    short pdrawm;        /* drawing modes */
    long fx,fy;
    long tx,ty;
    short vpnumber;
};

struct pkbatchvec {
    short pfunc;
    short psize;
    short nvecs;
    struct vecspec vectors[VBATCH];
};

Description
-----------
PBATCHVEC replaces FASTDRAW if EF_BIGVEC is on. Only 31 bit logical drawing
vectors arrive here. Except for the vector scaling, the handling of each
vecspec structure is the same as for PVEC.

Table 6-5. PINIT.pefmodes flags affect on vector drawing

EF_BS   EF_BIGVEC EF_FDRAW      Resulting behavior
--------------------------------------------------
yes         yes     yes     Logical drawing vectors in PBATCHVEC,
                            logical nondrawing vectors in PBIGVEC,
                            pixel nondrawing vectors in PVEC

yes         yes     no      Logical drawing vectors in PBIGVEC,
                            logical non-drawing vectors in PBIGVEC,
                            pixel non-drawing vectors in PVEC

yes         no      yes     Logical drawing vectors in FDRAW,
                            logical non-drawing vectors in PVEC,
                            pixel non-drawing vectors in PVEC

yes         no      no      Logical drawing vectors in PVEC,
                            logical non-drawing vectors in PVEC,
                            pixel non-drawing vectors in PVEC

no          yes     yes     Invalid

no          yes     no      Invalid

no          no      yes     Pixel vectors in FDRAW,
                            both solid and dashed pixel vectors in PVEC

no          no      no      Pixel vectors in PVEC


Table 6-5a. PINIT.pefmodes flags when IGNORE_BIG_SCREEN is set

EF_BS       EF_BIGVEC       EF_FDRAW               Resulting behavior

yes         yes     yes     Pixel vectors in PVEC

yes         yes     no      Pixel vectors in PVEC

yes         no      yes     Pixel vectors in PVEC

yes         no      no      Pixel vectors in PVEC

no          yes     yes     Invalid

no          yes     no      Invalid

no          no      yes     Pixel vectors in FDRAW,
                            both solid and dashed pixel vectors in PVEC

no          no      no      Pixel vectors in PVEC


NOTE: when IGNORE_BIG_SCREEN is set, PMARK and PCMARK are not sent.


The driver draws nvecs vectors from (vectors.fx[n], vectors.fy[n]) to
(vectors.tx[n], vectors.ty[n]).

The driver scales, clips and draws the vector in the viewport indicated in
member vpnumber. The driver obtains the required scaling and clipping
information from PLOPEN, PBVIEWPORT and POPENBVP.

The pcolour member may be less than negative one (-1), indicating a logical
color number. When the driver receives a logical color number in pcolour,
it substitutes the appropriate physical color corresponding to the
requested logical color. If pcolour is neither zero nor negative one, that
color is used to draw the vector. Refer to appendix A for color assignment
information.

If pcolour is zero, the vector is erased (preserving the background color
if it is something other than black).

XOR vectors (pcolour == -1) are not sent through PBATCHVEC.

The bit flags in pdrawm are either instructional (a directive) or
informational in nature, as shown in the following tables:

Table 6-6. Values for PVEC.pdrawm (informational)

Mnemonic        Value       Meaning
-------------------------------------
DR_BORDER       0x0010      Viewport border

DR_CURSOR       0x0020      Part of cursor

DR_AXIS         0x0040      AXIS tick mark

DR_LISP         0x0080      Drawn by LISP app

DR_ICONS        0x0100      Icons, vpoint and dview

DR_MARK         0x0200      Blips, pedit mark, etc.

DR_VECA         0x0400      Drawing aligned - drag, 3d
                            face, sketch, etc.

DR_SLIDE        0x0800      Slide

DR_DHILIT       0x1000      Dehighlighting vector

DR_ZOOMD        0x2000      Zoom dynamic

DR_PLPRE        0x4000      Plot preview


Table 6-7. Values for PVEC.pdrawm (directives)

Mnemonic        Value       Meaning
-------------------------------------
DR_HILITE       0x0001      Highlighted

DR_NORDRW       0x0002      Vector is not part of drawing

DR_PHYSCY       0x0004      Obsolete unbiased coordinate
system

DR_DASHED       0x0008      Real dashed lines


DR_HILITE
---------
If the driver implements highlighting, pcolour is greater than zero, and
the DR_HILITE flag is set, the vector is drawn highlighted (preferably in a
dashed-line font, but it may use other forms of highlighting if they are
more effective). Otherwise, a solid vector is drawn.

DR_NORDRAW
----------
The DR_NORDRW flag marks vectors that are not part of any drawing entity,
but are simply screen artifacts (e.g., the two lines forming a marker
blip). This is provided for BS drivers that use the PREDRAW packet.
DR_NORDRAW is not set in vectors sent through PBATCHVEC.

DR_DASHED
-----------
When PVEC or PLINE see this option flag (which is never seen together with
DR_HILITE), a highlighted vector should be drawn with gaps between the
visible segments. This is in contrast to DR_HILITE which erases to screen
background between visible segments. Support for this attribute is required
for all ADI DEV_RC 4.2 drivers.

Note that it is not unusual for some graphics controllers to draw a
different set of pixels depending on the direction the vector is drawn. If
garbage is left on the screen after erasing a polyline or solid, you might
try sorting the coordinates before drawing the vector.

See Also
--------
PBIGVEC, PVEC



6.17.4 PBDRAG
===============

Purpose
-------
This optional packet replaces PDRAG for 31-bit vectors.

Limitations
-----------
PBDRAG is used to send 31-bit drag vectors and may be sent only to ADI 4.2
BIGVEC DEV_DS or DEV_RC drivers in display mode and on the graphic screen.
BIGVEC drivers set PINIT or PDINFO.pefmodes EF_BIGVEC. This is an optional
packet and is sent only to drivers which set PINIT or PDINFO.pefmodes
EF_DRAG, indicating support for smart dragging.

If you choose to use PBDRAG, your application must provide some very
complex services for the ADI driver.

You must always keep information on hand to send erasing vectors in case
the ADI driver's drag display list overflows.

AutoCAD fills in every member of this packet. The ADI driver may modify the
value of dmode by returning 0 to indicate failure, in which case AutoCAD
performs the operation with PVEC calls.

History
-------
Added in ADI 4.2.

Declaration
-----------
#define PBDRAG 100          /* 31-bit drag vectors */

struct pkbdrag {
    short   pfunc;          /* PBDRAG */
    long    pfx, pfy;
    long    ptx, pty;
    short   ptcolor;
    short   dmode;
    short   vpnumber;
};

Description
-----------
This packet is sent to drivers which set PINIT.pefmodes EF_BIGVEC and
PINIT.pefmodes EF_DRAG.

The action for the driver to take depends on the value passed in member
dmode. The packet field dmode can have five possible values, 0 - 4,
discussed below.

The structure members pfx, pfy, ptx, and pty are in viewport-relative 31-
bit logical (L) coordinates or in viewport independent pixel (LLG)
coordinates.

The driver scales, clips and draws logical drag vectors in the viewport
indicated in vpnumber. The driver obtains the required scaling and clipping
information from PLOPEN, PBVIEWPORT and POPENBVP.

There are several states a viewport may be in with respect to drag vectors
(typically represented by a local flag, dstate). In addition, if the driver
has used up its local memory, it should set an overflow flag. (See the
sample display driver dspega42.c for examples.)

Table 6-8. Viewport states with respect to drag vectors

dmode  dstate Overflow  Coord Type   Add to drag list
-------------------------------------------------------
1      0        No       LLG            Yes

1      1        Yes      LLG            No

2      2        No       L              Yes

2      3        Yes      L              No

4      4        No       LLG            Redrawing moved image

4      6        No       L              Redrawing moved image


Table 6-9. Key for viewport states table

Code        Definition

LLG         Absolute pixel (viewport-independent) vectors

L           Logical (viewport-relative) vectors


Actions Based on PBDRAG.dmode Value
-----------------------------------
dmode = 0
---------
Add the vector to the drag list for the specified viewport and display it,
even if the display list has overflowed. The driver must remember
information sent to it by dmode 1 or 2 to know if vectors sent for this
viewport are pixel or logical, and handle them accordingly.

Return value: none

dmode = 1
---------
Initialization call. The driver should forget any existing drag list for
the viewport in member vpnumber. Future vectors sent with dmode 0 for this
viewport are absolute pixel vectors. This call precedes the vector list
associated with AutoCAD operations such as Rotate where a simple
displacement of the drag list is not useful. The next movement in a drag
sequence instructs the driver to erase the drag image. It is not necessary
to scale or clip any vectors sent with a viewport initialized with dmode =
1.

Return value: none

dmode = 2
---------
Initialization call. The driver should forget any existing drag list for
the viewport in vpnumber. Future vectors sent through dmode 0 for this
viewport are logical vectors.

This call precedes the vector list associated with AutoCAD operations such
as Move, where a simple displacement of the drag list is useful. The next
movement in a drag sequence will probably instruct the driver to erase and
redraw the drag image after applying a displacement to it (this requires
the driver to scale and clip the vectors to the current viewport).

Return value: none

dmode = 3
---------
Instructs the driver to erase anything already drawn from the drag list. If
the driver buffers vectors and has not drawn all of them, it should erase
the ones already drawn and flush the rest from the buffer.

If this packet is sent when a movable drag image is partly redrawn in its
new position (because of fresh user input), the driver should erase what
has been drawn and stop that Redraw sequence (you probably soon get a fresh
dmode = 4 call). If the driver is able to erase any drag vectors already
drawn, it should return dmode = 1 to signal success.

If the driver cannot do the erase (because the drag list space overflowed
as vectors came in), it should not erase anything, and return dmode = 0 to
tell AutoCAD. AutoCAD sends XOR vectors through dmode = 0 to erase it. Any
vectors sent to this viewport through dmode = 0 should be drawn (which
erases) until you get a fresh initialization for this viewport's drag mode.

Table 6-10. Return values in PBDRAG.dmode (3)

Value        Meaning

0            Driver was unable to perform the requested operation

1            Successful erase operation


dmode = 4
---------
Instructs the driver to displace (move) all of the vectors in the drag list
by the specified amount. The driver is responsible for redrawing the
vectors in the new position. (This is preceded by a dmode = 3 call to erase
the old image.)

If there are many vectors to redraw, the driver should not do them all at
once. After about 100 milliseconds, the driver should return with dmode set
to 1 to indicate that more redraw is required. After AutoCAD checks for
input from the user, the driver is called again with dmode set to 4 to let
the driver continue the Redraw. It is your driver's responsibility to
remember where to continue redrawing.

Table 6-11. Return values in PBDRAG.dmode (4)

Value       Meaning

0           Driver was unable to perform the requested operation

1           Part way through redraw operation

2           Successful completion of redraw operation


If the driver cannot perform the requested displacement (because the
display list overflowed, for example), it should return dmode = 0. AutoCAD
handles erasing and redrawing the image by sending vectors through the drag
vector facility. The driver should leave the overflow flag set so the
vector facility knows to just draw and not add the vectors to a drag list.

If the driver can perform the requested displacement, it should return with
dmode = 2 when the image has been completely redrawn.

Fill mode is off during drag sequences; filled shapes are sent as outlines.

See Also
--------
PDRAG



6.17.5 PBFILL
===============

Purpose
-------
This optional packet replaces PFILL for 31-bit logical polygons.

Limitations
-----------
PBFILL is used to send 31-bit polygons and may be sent only to ADI 4.2
BIGVEC DEV_DS or DEV_RC drivers which set PINIT.hwfill to 2, while they are
in display mode on the graphic screen. BIGVEC drivers set PDINFO and
PINIT.pefmodes EF_BIGVEC. This is an optional packet and is sent only to
drivers which support polygon fill.

PBFILL may be sent both 31-bit logical drawing polygons and 31 bit logical
non-drawing polygons. It may not be sent pixel scaled polygons.

Secondary applications should send only non-drawing polygons. You should
always set DR_NORDRAW in pdrawm. If you want highlighted polygons, you may
also set DR_HILITE.

You can use PBFILL if talking to a BIGVEC BS ADI driver, in a BS viewport.
In this case, you must use a valid viewport number (i.e., for a viewport
which is currently open). Then the vertices in pvert[] must be in viewport-
relative 31-bit logical coordinates. You can expect the ADI driver to scale
and clip the polygons to fit the specified viewport. Logical non-drawing
polygons should be used to send polygons which must align exactly with
drawing entities (which are sent in logical coordinates to a BS driver).

All the fields in this packet are filled in by AutoCAD. The driver treats
this as a read-only packet.

History
-------
Added in ADI 4.2.

Declaration
-----------
#define PBFILL 101        /* 31-bit polygon fills */

struct pkbfill {
    short   pfunc;        /* PBFILL */
    short   pcolour;
    short   pdrawm;
    short   pnvert;
    long    pvert[12][2];
    short   vpnumber;
};

Description
-----------
We take this opportunity to send logical and pixel polygons through
separate packets - using the old PFILL for pixel polygons or 15-bit logical
polygons and PBFILL for logical 31-bit polygons.

The driver scales, clips and draws the polygon in the viewport indicated in
member vpnumber. The driver obtains the required scaling and clipping
information from PLOPEN, PBVIEWPORT and POPENBVP.

Only 31-bit logical filled polygons are sent to PBFILL. Pixel scaled
polygons are sent through PFILL with vpnumber = 0. If pdrawm has the
DR_NORDRW bit set, the polygon is non-drawing and should not be added to
your display list. Otherwise, if DR_NORDRW is not set, the polygon must be
added to your display list.

Table 6-12. Values for PBFILL.pdrawm

Mnemonic       Value                                  Meaning

DR_HILITE      0x1  If set, draw using highlighting. If clear, do not use
highlighting.

DR_NORDRW      0x2  If set, vector is not part of drawing entity. If clear,
the vector is a part of drawing entity.


If your ADI driver does not do its own fills, AutoCAD sends vectors for
filled shapes through the normal drawing vector packets (PBIGVEC or
PBATCHVEC).

PBFILL must be able to do XOR fills, and is required to handle non-drawing
fills with member pcolour equal to negative 1 as XOR.

Because AUI must be supported in ADI 4.2 drivers, pcolour may be less than
-1, indicating a logical color number. In this case, the driver should
substitute the appropriate physical color corresponding to the requested
logical color.

If the (possibly adjusted) color value passed in pcolour is neither 0 nor -
1, that color should be used to draw the filled area.

If pcolour is 0, the area should be erased, preserving the background color
if it is something other than black.

If your driver implements highlighting, pcolour is greater than 0, and the
DR_HILITE (pdrawm bit 0) is set, the filled area should be highlighted
(usually done by highlighting every fifth line of the fill). We also draw a
highlighted vector around the outlines of the polygon. This makes the
highlighting of thin polylines work.

The polygon to be drawn is made up of pnvert vertices, which are defined in
a two-dimensional table, pvert. This table contains 12 columns representing
up to 12 vertices, and two rows representing X and Y coordinates. Valid
column subscript values must be within the range 0 to (pnvert - 1). Valid
row subscripts are 0 for X coordinates, and 1 for Y coordinates. Although
12 vertices can be represented, AutoCAD never passes a polygon with more
than 10 vertices to PBFILL. You probably should also be conservative.

Note that fills performed by AutoCAD for a BS driver are very slow, since
many logical fill vectors map to a single displayed vector. One work-around
is to suggest that users turn FILL off in AutoCAD. Implementing PBFILL is
the best solution.

Refer to appendix A for information on color numbers.

See Also
--------
PFILL



6.17.6 PBIGBLIT
=================

Purpose
-------
To save and restore a bitmapped image, possibly multiple times, to
arbitrary screen destinations. Clips image to fit on the screen.

Limitations
-----------
PBIGBLIT may be sent only to ADI 4.2 DEV_DS or DEV_RC drivers in display
mode on the graphic screen.

Applications which use PBIGBLIT should be careful to free any saved blits
before termination.

The controlling application should fill in every member except status. The
ADI driver fills in status to report on its success or failure at servicing
the request and, for some requests, returns a new value in member handle.

History
-------
Added in ADI 4.2. All ADI 4.2 drivers are required to support this packet.

Declaration
-----------
#define PBIGBLIT 74          /* save/restore/forget images */

struct pkbigblit {
    short   pfunc;                             /* PBIGBLIT */
    short   x, y;         /* ULS coords of image rectangle */
    short   width, height;             /* saved-image size */
    short   action;                      /* action request */
    long    handle;                    /* image identifier */
    short   status;                       /* return status */
};

Description
-----------
ADI 4.2 display drivers are required to support an arbitrary number of
pkbigblit packets. Drivers must be prepared to resort to host or virtual
memory when on-board memory runs out.

The table below shows the values for the action member, filled in by the
controlling application:

Table 6-13. Values for PBIGBLIT.action

Mnemonic        Value                  Meaning

BB_SAVE         1   Save area, return handle

BB_RESTORE      2   Restore area from handle supplied

BB_FORGET       4   Forget contents of handle


The table below shows the values returned by the driver in the status
member:

Table 6-14. Values for PBIGBLIT.status

Mnemonic         Value                 Meaning

BB_OK            0    Success

BB_BADHANDLE     1    Defective handle

BB_BADCOORD      2    Bad coordinates

BB_TOOBIG        4    Too big a block; can't handle it


On receipt of action BB_SAVE, the driver attempts to malloc() enough memory
to save the screen contents defined by a rectangle whose upper left corner
is at x,y (in ULS pixel coordinates) and which is width, height pixels in
size. If the driver fails, it returns status BB_TOOBIG. If the malloc()
succeeds, the driver saves the screen area and returns the offset of the
malloc'd buffer in handle and BB_OK in status. If the coordinates given for
BB_SAVE are not on screen, the driver returns BB_BADCOORD.

The driver saves and restores the full color depth of the screen image (all
bitplanes).

The purpose of the member handle is to provide a unique identifier for the
saved blit. It is not intended to give the controlling application a
pointer to use for modifying the saved image.

On receipt of BB_RESTORE, the driver checks to see if handle is a valid
address for a saved blit. If it isn't, the driver returns BB_BADHANDLE. If
it is OK, the driver restores the blit to the position in x,y. The x,y
coordinates are signed, to allow placement of the lower left corner of the
restore operation off-screen. The driver clips the restore operation to the
graphics area of the screen.

If the BB_FORGET bit is set along with BB_RESTORE, then the malloc'd memory
should be freed after the restore operation. After a successful restore
and/or forget operation, the driver should return BB_OK.

When the driver receives BB_FORGET, it should check to be sure this is a
valid handle, then free it if it is. If it is invalid, the driver should
return BB_BADHANDLE.

If off-screen coordinates are given for a BB_SAVE (the entire box to be
saved must be on screen), or if a BB_RESTORE gets coordinates so far off-
screen that nothing may be restored (at least some of the box must be on
screen for a restore), the driver returns BB_BADCOORD.

Although applications are required to release any saved blits before
terminating, drivers should double check at PKILL time and free any blits
which might be remaining.



6.17.7 PBIGVEC
================

Purpose
-------
This optional packet replaces PVEC for 31-bit logical vectors.

Limitations
-----------
PBIGVEC is used only to send 31-bit logical vectors and may be sent only to
ADI 4.2 BIGVEC DEV_DS or DEV_RC drivers in display mode and on the graphic
screen. BIGVEC drivers set PDINFO and PINIT.pefmodes EF_BIGVEC.

Secondary applications should not use this packet to send drawing vectors.
They should send only nondrawing vectors.

Both logical drawing and logical non-drawing vectors may be sent by primary
applications through PBIGVEC.

All the fields in this packet are filled in by AutoCAD. The driver treats
this as a read-only packet.

History
-------
Added in ADI 4.2.

Declaration
-----------
#define PBIGVEC 96          /* 31-bit logical vector */

struct vecspec {
    short color;            /* vector color */
    short pdrawm;           /* drawing modes */
    long fx,fy;
    long tx,ty;
    short vpnumber;
};

struct pkbigvec {
    short pfunc;            /* PBIGVEG packet code */
    short size;            /* packet size */
    struct vecspec vector;
};

Description
-----------
We take this opportunity to send logical and pixel vectors through separate
packets; using the old PVEC for pixel vectors and PBIGVEC or PBATCHVEC for
logical 31-bit vectors.

The driver draws a vector from (fx,fy) to (tx,ty).

The driver scales, clips, and draws the vector in the viewport indicated in
member vpnumber. The driver obtains the required scaling and clipping
information from PLOPEN, PBVIEWPORT and POPENBVP.

The pcolour member can be less than negative one (-1), indicating a logical
color number. When the driver receives a logical color number in pcolour,
it substitutes the appropriate physical color corresponding to the
requested logical color. If pcolour is neither zero nor negative one, that
color is used to draw the vector. Refer to appendix A for color assignment
information.

If pcolour is zero, the vector is erased (preserving the background color
if it is something other than black).

If pcolour is negative one, the vector is XOReed with the background color
in all image planes. Drivers should check to see if CF_STUDIO is set. If
so, they only XOR with the low 4 bits of the color palette.

The bit flags in pdrawm are either instructional (a directive) or
informational in nature, as shown in the following tables:

Table 6-15. Values for PVEC.pdrawm (directives)

Mnemonic        Value                     Meaning

DR_HILITE       0x0001                    Highlighted

DR_NORDRW       0x0002                    Vector is not part of drawing

DR_PHYSCY       0x0004                    Obsolete unbiased coordinate
system

DR_DASHED       0x0008                    Real dashed lines


Table 6-16. Values for PVEC.pdrawm (informational)

Mnemonic        Value      Meaning
---------------------------------------------
DR_BORDER       0x0010     Viewport border

DR_CURSOR       0x0020     Part of cursor

DR_AXIS         0x0040     AXIS tick mark

DR_LISP         0x0080     Drawn by LISP app

DR_ICONS        0x0100     Icons, vpoint and dview

DR_MARK         0x0200     Blips, pedit mark, etc.

DR_VECA         0x0400     Drawing aligned - drag, 3d
                           face, sketch, etc.

DR_SLIDE        0x0800     Slide

DR_DHILIT       0x1000     Dehighlighting vector

DR_ZOOMD        0x2000     Zoom dynamic

DR_PLPRE        0x4000     Plot preview


DR_HILITE
-----------
If the driver implements highlighting, pcolour is greater than zero, and
the DR_HILITE flag is set, the vector is drawn highlighted (preferably in a
dashed-line font, but it may use other forms of highlighting if they are
more effective). Otherwise, a solid vector is drawn.

Drivers must be capable of drawing a highlighted line in either normal
drawing mode (pcolour greater than zero) or XOR mode (pcolour equal to
negative one (-1)). This must be a reversible operation, implying leaving
the gaps untouched. Thus if the color is XOR, DR_HILITE and DR_DASHED
perform the same operation.

DR_NORDRAW
------------
The DR_NORDRW flag marks vectors that are not part of any drawing entity,
but are simply screen artifacts (e.g., the two lines forming a marker
blip). Non-drawing vectors should not be added to your display list.

DR_DASHED
-----------
When PVEC or PLINE see this option flag (which is never seen together with
DR_HILITE), a highlighted vector should be drawn with gaps between the
visible segments. This is in contrast to DR_HILITE which erases to screen
background between visible segments. Support for this attribute is required
for all ADI DEV_RC 4.2 drivers.

Note that it is not unusual for some graphics controllers to draw a
different set of pixels depending on the direction the vector is drawn. If
garbage is left on the screen after erasing a polyline or solid, you might
try sorting the coordinates before drawing the vector.

AutoShade sends AUI vectors through the PVEC packet instead of the PLINE
packet.



6.17.8 PBITBLT
================

Purpose
-------
PBITBLT is used to draw a one-bit-deep bit-mapped image such as an icon on
the graphic screen.

Limitations
-----------
PBITBLIT is a display packet supported by some DEV_DS and all DEV_RC
drivers in display mode. Support for PBITBLT is indicated by setting
EF_PTEXT in pefmodes in PINIT and PDINFO.

This is a display packet. It can be sent only to DEV_DS or DEV_RC drivers.
It can be sent only in graphic mode after PINIT.

  * MINLCOLOR <= pfgcolor <= 255.

  * MINLCOLOR <= pbgcolor <= 255.

Values for member pattr are defined in colours.h.

  * 0 <= px <= PINIT.ixdots in ULS pixel coordinates

  * 0 <= py <= PINIT.iydots in ULS pixel coordinates

In addition to px and py being limited to on-screen values, the entire
image must be on screen. Do not assume the driver will clip the image to
the screen.

pbits[] must be 400 bytes or less in size.

pbytes is the size in bytes of pbits[] divided by pheight.

All the fields in this packet are filled in by AutoCAD. The driver treats
this as a read-only packet.

History
-------
This packet was introduced in ADI 4.1, initially to support 3D Studio. It
was required for ADI 4.1 DEV_RC drivers but optional for ADI 4.1 DEV_DS
drivers. Support for it is required for all ADI 4.2 DEV_DS and DEV_RC
drivers.

Declaration
-----------
#define PBITBLT  69   /* draw bit-map on graphic screen */

struct pkbitblt {
    short pfunc;                             /* PBITBLT */
    short pbytes;        /* bytes per row of definition */
    short px,py;         /* upper left corner in pixels */
    short pwidth;                     /* pixels per row */
    short pheight;                    /* number of rows */
    short attr;                           /* attributes */
    short pfgcolor, pbgcolor;          /* fg, bg colors */
    unsigned char pbits[1];      /* binary data to blit */
};

Description
-----------
pfgcolor is the color of the '1' bits in the bitmap.

pbgcolor is the color of the '0' bits in the bitmap. If attr = TAXPARENT,
background pixels should remain unchanged. Values for pattr are defined in
the C header file colours.h.

Member pbits[] is a single-plane bitmapped image that is byte-aligned on
the left. Extra bits on the right of an image that is not a multiple of
eight pixels wide are unused. For example, a simple 10 by 10 pixel image of
an open box would consist of the following data:

0xFF,0xC0, 0x80,0x40, 0x80,0x40, 0x80,0x40, 0x80,0x40,
0x80,0x40, 0x80,0x40, 0x80,0x40, 0x80,0x40, 0xFF,0xC0.

The length of the image data is calculated by the formula:
((width+7)/8)*height.

There is a limit of 400 bytes on the size of pbits[] (so it can fit into
the packet buffer in P386 ADI).

Note that if your driver returns EF_PTEXT in member pefmodes at PINIT time,
it must support PBITBLT. AutoCAD Release 12 requires support of EF_PTEXT.

Autodesk 3D Studio also uses this packet.



6.17.9 PBMARK
===============

Purpose
-------
This optional packet replaces PMARK for BIGVEC drivers.

Limitations
-----------
PBMARK is used to notify the driver that a cursor is to be drawn and may be
sent only to ADI 4.2 BIGVEC DEV_DS or DEV_RC drivers in display mode on the
graphic screen. BIGVEC drivers set PINIT and PDINFO.pefmodes EF_BIGVEC.

If you are controlling a display driver through a TEE driver, remember that
you must leave the cursor in the state AutoCAD expects it to be in. At a
minimum, on letting AutoCAD resume control, you must leave a cursor on
screen if AutoCAD had one on screen before you intervened, and you must not
have a cursor on screen if AutoCAD didn't.

If you are an ADS application, AutoCAD always removes any cursors from the
screen before giving control of the screen to you. You are required to
remove any cursors you put on the screen before you return control to
AutoCAD or before you switch modes (e.g., GOTEXT or RDSTART).

Vpnumber may be non-zero (but must be a valid, currently open viewport) and
the driver can be expected to clip the cursor to the specified viewport.

ADI drivers only know how to draw a simple orthogonal cursor (cursel types
0 and 3). But drivers expect to be notified of all cursors, including those
they can't draw.

For all values of member pcursel other than 0 or 3, the driver simply
returns with pstat set to zero. This tells you (the controlling
application) to do the work.

ADI drivers expect to get a PBMARK packet just before each PDCURS packet.
The driver will fail the PBMARK request. Some drivers use the PBMARK packet
(which contains coordinates) to manage value-added driver features.

If the driver draws the cursor, it returns a value of 1 in member pstat.
Otherwise, it returns with pstat set to zero, instructing you to draw the
cursor yourself.

The coordinates supplied in px and py are LLG pixel coordinates or 31-bit
logical coordinates and must be for a point inside the specified viewport
(remember that viewport 0 is the entire graphic area of the screen). Most
ADI drivers use the same XOR cursor routine to draw and erase types 0 and 3
cursors.

AutoCAD fills in all the members of this packet. The ADI driver fills in
pstat to return its status.

History
-------
Added in ADI 4.2.

Declaration
-----------
#define PBMARK 98     /* draw BIGVEC cursor */

struct pkbmark {
    short   pfunc;    /* PBMARK */
    short   pstat;
    long    px, py;
    short   pcursel;
    short   vpnumber;
    short   logical;
};

Description
-----------
Draw a cursor. If member logical is true, use 31-bit logical coordinates.
Member logical is true in any viewport where logical drawing vectors are
used.

PBMARK instructs the driver to draw a cursor of type pcursel at screen
coordinates (px,py).

For all values of pcursel other than 0 or 3, the driver should simply
return a value of 0 in pstat, and the Autodesk product draws the cursor
itself.

pcursel values of 0 and 3 specify simple orthogonal crosshairs, and the
display driver may choose to draw these with optimized code. Autodesk
products normally draw a full- screen crosshair, but the driver can draw it
smaller (or allow the size to be configured by the user) if desired.

If member logical is false, the coordinates passed in px and py are
viewport-independent pixel coordinates. For all cursor types except 10 and
11, the origin for pixel coordinates is LLG. For cursor types 10 and 11,
the origin for pixel coordinates is ULS. If member logical is true, the
coordinates are 31-bit logical viewport relative. In either case, it is the
driver's responsibility to clip the cursor to the specified viewport.

If the driver draws the cursor, it should return a value of 1 in pstat.
Otherwise, it should return with pstat set to zero, instructing the
Autodesk product to draw the cursor.

ADI 4.1 and later drivers check to see if CF_STUDIO is set. If so, they
only XOR with the low 4 bits of the color palette.

See Also
--------
PCBMARK, PMARK, PCMARK



6.17.10 PBOXCLR
=================

Purpose
-------
PBOXCLR instructs the driver to clear a rectangle to a specified color.

Limitations
-----------
The PBOXCLR request may be issued only if AUI has been enabled by setting
the EF_NEWI flag in the PINIT.pefmodes and PDINFO.

This is a display packet. It can be sent only to DEV_DS or DEV_RC drivers.
It can be sent only in graphic mode after PINIT.

All ADI 4.1 and later drivers must handle this packet.

MINLCOLOR <= pcolour <= 255.

The entire box to be cleared must be on the graphic screen - you can't
expect the ADI driver to clip the box to the screen. The box is specified
in ULS pixel coordinates:

  * 0 <= pxl < pxh < XSIZE

  * 0 <= pyl < pyh < YSIZE

All the fields in this packet are filled in by AutoCAD. The driver treats
this as a read-only packet.

History
-------
This packet was added as part of the AUI in ADI 3.0 to support Release 9.
AUI support was optional until ADI 4.1 and Release 11.

In Release 11, AutoCAD started using XOR (color -1) PBOXCLR requests. Some
older drivers (pre-ADI 4.1) fail to handle XOR PBOXCLR requests properly.

Declaration
-----------
#define PBOXCLR  27

struct pkboxclr {
    short pfunc;              /* PBOXCLR */
    short pxl, pyl, pxh, pyh;
    short pcolour;
};

Description
-----------
PBOXCLR instructs the driver to clear the rectangle inclusively delimited
by the points (pxl,pyl) and (pxh,pyh) (ULS pixel coordinates) to the color
specified by pcolour.

PBOXCLR must be able to handle XOR fills (pcolour member equal to negative
1).

ADI 4.1 and later drivers check to see if CF_STUDIO is set. If so, they
only XOR with the low 4 bits of the color palette.



6.17.11 PBOXPOP
=================

Purpose
-------
PBOXPOP "pops" the contents of a screen rectangle that was saved ("pushed")
by PBOXPUSH.

Limitations
-----------
The PBOXPOP request may be issued only if AUI has been enabled by setting
EF_NEWI in PINIT.pefmodes and PDINFO.

This is a display packet. It can be sent only to DEV_DS or DEV_RC drivers.
It can be sent only in graphic mode after PINIT.

You must never ask a driver to POP boxes which have not been PUSHED. You
must always POP any PUSHED boxes before returning control to the primary
application or before switching graphic modes (e.g., GOTEXT or RDSTART).

If you choose to use PBOXPUSH and PBOXPOP, your application must provide
some fairly complex services for the ADI driver. PBIGBLIT is a simpler
alternative to consider.

Real-mode ADI drivers still expect the controlling product to be able to
provide memory for saving pushed boxes if the driver runs out of memory.
The other platforms have virtual memory and assume that the driver provides
all necessary memory (though not necessarily in one chunk).

PBOXPOP must POP the box to the same screen location it was PUSHED from.
The entire box must fit on screen -- the ADI driver does not clip it to
fit. LLG pixel coordinates are used. Boxes must be popped in the reverse
order that they were pushed.

The value of the pyh field is always equal to: (pyl + pheight - 1).

The value of the plocate member in the PBOXPOP packet is the same value the
ADI driver sent to you when this box was pushed.

In single-screen systems, everything that has been pushed must be popped
prior to a request to flip to AutoCAD's text screen or AutoShade's
rendering screen.

All the fields in this packet are filled in by AutoCAD. The driver treats
this as a read-only packet.

The related packet, PBOXSIZE, used in real-mode ADI to warn the driver of
an impending PBOXPUSH, is no longer used in P386, XENIX or UNIX ADI. It is
still used in real-mode DOS display ADI.

History
-------
This packet was added as part of the AUI in ADI 3.0 to support Release 9.
AUI support was optional until ADI 4.1 and Release 11.

The packet has been reorganized twice. Once for XENIX ADI 4.0 for structure
alignment purposes. Then for P386 and OS/2 ADI 4.0 and all subsequent
"PASS_DATA" platforms, pbufaddr was eliminated.

Declaration
-----------
/*  Packet for PBOXPUSH and PBOXPOP requests */
#define PBOXPOP  30

struct pkboxsave {
    short pfunc;              /* PBOXPOP */
    short pheight;            /* Height actually saved */
    short pxl, pyl, pxh, pyh; /* Box corners */
    long plocate;             /* Passed back in PBOXPOP */
};
Description
-----------
PBOXPOP instructs the driver to restore the screen rectangle inclusively
defined by the points (pxl,pyl) and (pxh,pyh). This must always be the
screen rectangle most recently saved with PBOXPUSH.

The value of the pyh field is always equal to (pyl+pheight-1).

The value of the plocate member in the PBOXPOP packet is the same value
your driver sent to AutoCAD when this box was pushed. Typically, your
driver will have allocated memory (using malloc()) to save the box and will
use plocate to save the address of the allocated buffer.

In single-screen systems, everything that has been pushed is popped prior
to a request to flip to AutoCAD's text screen or AutoShade's rendering
screen.

In AutoCAD Release 12, due to Proteus dialogues, there is no limit to how
many nested PBOXPUSH packets an ADI driver may receive. Drivers must be
prepared to resort to the use of virtual memory if on-board memory runs
out.

See Also
--------
PBOXPUSH, PINIT



6.17.12 PBOXPUSH
==================

Purpose
-------
PBOXPUSH instructs the driver to save the contents of a screen rectangle.

Limitations
-----------
The PBOXPUSH request may be issued only if the Advanced User Interface
(AUI) has been enabled by setting the EF_NEWI (bit 4) flag in the pefmodes
member of PINIT and PDINFO.

This is a display packet. It can be sent only to DEV_DS or DEV_RC drivers.
It can be sent only in graphic mode after PINIT.

You must always POP any PUSHED boxes before returning control to the
primary application or before switching graphic modes (e.g., GOTEXT or
RDSTART).

If you choose to use PBOXPUSH and PBOXPOP, your application must provide
some fairly complex services for the ADI driver. For ADI 4.2 drivers,
PBIGBLIT is a simpler service to request.

0 <= pxl < pxh < PXSIZE
0 <= pyl < pyh < PYSIZE

PBOXPUSH instructs the driver to save the contents of the screen rectangle
inclusively delimited by the points (pxl,pyl) and (pxh,pyh). The entire box
must be inside the graphic screen - the ADI driver does not clip it to fit.
LLG pixel coordinates are used.

The ADI driver returns pheight as the number of pixel rows the driver was
able to save in the space available. Thus, if the entire rectangle was
saved, this would be (pyh - pyl + 1). Your application needs to maintain a
linked list of structures remembering every pushed box's size, location and
plocate handle. If your original request wasn't satisfied completely in the
first PBOXPUSH, you will have to repeat the request, adjusting the
coordinates to reflect the remaining box to be pushed, until the driver has
either saved the entire box or failed to save more. The driver saves an
integral number of complete scan lines in your requested box, starting from
the bottom with each pass.

Real-mode ADI drivers still expect the controlling product to be able to
provide memory for saving pushed boxes if the driver runs out of memory.
The other platforms have virtual memory and assume that the driver provides
all necessary memory (though not necessarily in one chunk).

AutoCAD fills in all the members of this packet except plocate. The ADI
driver fills in pheight with the height actually saved and plocate with an
optional handle to the saved box.

The related packet, PBOXSIZE, used in real-mode ADI to warn the driver of
an impending PBOXPUSH, is no longer used in P386, XENIX or UNIX ADI. It is
still used in real-mode DOS display ADI.

History
-------
This packet was added as part of the AUI in ADI 3.0 to support Release 9.
AUI support was optional until ADI 4.1 and Release 11.

The packet has been reorganized twice: once for XENIX ADI 4.0 for structure
alignment purposes, and once for P386 and OS/2 ADI 4.0 and all subsequent
"PASS_DATA" platforms, when pbufaddr was eliminated.

Declaration
-----------
/*  Packet for PBOXPUSH and PBOXPOP requests */
#define PBOXPUSH 29

struct pkboxsave {
    short pfunc;               /* PBOXPUSH */
    short pheight;             /* Height actually saved */
    short pxl, pyl, pxh, pyh;  /* Box corners */
    long plocate;              /* Passed back in PBOXPOP */
};

Description
-----------
The PBOXPUSH request is issued only if the Advanced User Interface (AUI)
has been enabled by setting the EF_NEWI (bit 4) flag in the pefmodes member
of the PINIT reply packet.

PBOXPUSH instructs the driver to save the contents of the screen rectangle
inclusively delimited by the points (pxl,pyl) and (pxh,pyh) (ULS pixel
coordinates).

Upon return, pheight must be set to the number of pixel rows the driver was
able to save, starting from the bottom, in the space available. Thus, if
the entire rectangle was saved, this would be (pyh - pyl + 1).

If your driver was unable to save the entire box in a single operation,
AutoCAD sends another PBOXPUSH asking you to save the rest. This allows
your driver to use more than one strategy for saving boxes (e.g., on-board
memory and malloc()) while still taking advantage of the AutoCAD service
plocate to help you keep track of where each box was stored.

The member plocate is for the driver's convenience and can be used to
identify where in local memory the screen rectangle has been saved. The
value assigned to plocate is passed as an argument to the matching PBOXPOP
request.

In ADI 4.2, it is assumed that your driver has access to virtual memory and
can save an unlimited number of box pushes. If you use on-board video
memory, be sure to provide a fall-back routine which uses malloc() when on-
board memory runs out. Release 12 AutoCAD, with Proteus dialogues, allows
much deeper nesting of dialogues on screen.

See Also
--------
PBOXPOP, PINIT



6.17.13 PBSHELL
=================

Purpose
-------
This is an optional packet. PBSHELL notifies the driver when a Shell
command is about to begin.

Limitations
-----------
PBSHELL is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. Drivers indicate a desire for this packet by returning
EF_SHELL in pefmodes at PINIT and PDINFO time. Secondary applications
should not have to send this packet because they should not shell out.

This is a display packet. It can be sent only to DEV_DS or DEV_RC drivers.
It can be sent only in display mode after PINIT. It may be sent only on the
text screen.

Primary products should send PBSHELL and PASHELL to any driver which
requests it by setting EF_SHELL. Existing products which don't send shell
packets also don't shell out.

All the fields in this packet are filled in by AutoCAD. The driver treats
this as a read-only packet.

History
-------
PBSHELL was added in ADI 3.1 to support Release 9 AutoCAD.

Declaration
-----------
#define PBSHELL  35

struct pkfonly {
    short pfunc;    /* PBSHELL */
};

Description
-----------
This request is issued when a Shell command is about to begin, if EF_SHELL
(bit 8) was set in the pefmodes member of the PINIT reply packet to let the
Autodesk product know that the driver wants to be informed of Shell
commands.

If your driver supports the DOS window on the graphic screen feature
(setting DM_GROK and DM_GROKE at PINIT time), this packet signals the time
when your driver must switch to a real DOS text screen.

See Also
--------
PASHELL



6.17.14 PBVIEWPORT
====================

Purpose
-------
This optional packet specifies the visible portion of a viewport's logical
space.

Limitations
-----------
PBVIEWPORT is a display packet and can be sent to DEV_DS and DEV_RC BIGVEC
BS drivers in display mode. Support for this packet is optional and is
indicated by setting EF_BIGVEC and EF_BS in pefmodes in PDINFO and PINIT.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

Use of this packet by secondary applications is not recommended - secondary
applications should not change view parameters without AutoCAD's knowledge.

AutoCAD fills in all the members of this packet. The ADI driver may return
status in member vflags.

History
-------
This packet was added in ADI 4.2 to support BIGVEC viewports for display
list drivers.

Declaration
-----------
#define PBVIEWPORT 103

struct pkbview {
    short   pfunc;       /* PBVIEWPORT */
    short   vpnumber;
    long    lgxl, lgyl;
    long    lgxh, lgyh;
    short   master;
    char    vflags;
};

Description
-----------
The PBVIEWPORT packet indicates what portion of a BIGVEC viewport's 31-bit
logical space is visible. It is not a Redraw or clear screen request.

The members lgxl, lgyl, lgxh, and lgyh are in viewport-relative logical
coordinates.

The master member is ignored because the master/slave feature was
discontinued after AutoCAD Release 10.

The PBVIEWPORT packet is usually followed either by a Redraw request (an
AutoCAD Pan or Zoom) or by an entirely new set of vectors (an AutoCAD
Regen).

If a BS driver is unable to handle this viewport in BS mode (perhaps due to
lack of display list memory), it may set the NO_BS bit flag in member
vflags to let AutoCAD know. The logical size of the viewport is reduced to
the viewport size and the driver is passed viewport-independent pixel
coordinates (through PVEC) for display directly on the screen. (Vectors
passed to the driver for a NO_BS viewport are all tagged for viewport
zero).

Table 6-17. Values for PBVIEWPORT.vflags

Mnemonic       Value Bit  Meaning if Set

NO_VEC         0x1   0    No longer used

NO_BS          0x2   1    This is not a BS viewport


See Also
--------
PVIEWPORT



6.17.15 PCBMARK
=================

Purpose
-------
This optional packet instructs driver to clear the cursor at a 31-bit
logical screen location.

Limitations
-----------
PCBMARK is a display packet and can be sent to DEV_DS and DEV_RC BIGVEC BS
drivers in display mode. Only BS BIGVEC DEV_DS and DEV_RC drivers support
this packet.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

If you are controlling a display driver through a TEE driver, remember that
you must leave the cursor in the state AutoCAD expects it to be in. At a
minimum, on letting AutoCAD resume control, you must leave a cursor on
screen if AutoCAD had one on screen before you intervened, and you must not
have a cursor on screen if AutoCAD didn't.

ADI drivers only know how to draw a simple orthogonal cursor (cursel types
0 and 3). But drivers expect to be notified of all cursors, including those
they can't draw.

For all values of pcursel other than 0 or 3, the driver simply returns with
pstat set to zero. This tells you to do the work.

If the driver clears the cursor, it returns a value of 1 in pstat.
Otherwise, it returns with pstat set to zero, instructing you to clear the
cursor yourself.

The coordinates supplied in members px and py must be for a point inside
the specified viewport (remember that viewport 0 is the entire graphic area
of the screen). A cursor of the specified type must exist at the specified
location so that the driver can erase it. Most ADI drivers use the same XOR
cursor routine to draw and erase types 0 and 3 cursors.

Note that ADI drivers expect to get a PCBMARK packet just before each
PCCURS packet. The driver will fail the PCBMARK request. Some drivers use
the PCBMARK packet (which contains coordinates) to manage value-added
driver features.

You must never ask a driver to erase a non-existent cursor.

If you are an ADS application, AutoCAD always removes any cursors from the
screen before giving control of the screen to you. You are required to
remove cursors you put on the screen before you return control to AutoCAD
or before you switch modes (e.g., GOTEXT or RDSTART).

AutoCAD fills in every member of PCBMARK. The ADI driver may return status
in member pstat.

History
-------
In ADI 4.2, the cursor coordinates in PBMARK and PCBMARK, for BIGVEC BS
drivers in viewports where logical space is active, have been changed from
the pixel coordinates previously used in PMARK and PCMARK to 31-bit logical
coordinates. This was done to support 31-bit regens and to eliminate pixel-
off-by-one errors.

Declaration
-----------
#define PCBMARK 99    /* erase 31-bit logical cursor */

struct pkbmark {
    short   pfunc;    /* PCBMARK */
    short   pstat;
    long    px, py;
    short   pcursel;
    short   vpnumber;
    short   logical;
};
Description
-----------
PCBMARK instructs the driver to clear a cursor of type pcursel at
coordinates (px,py). If member logical is TRUE, the cursor coordinates are
31-bit logical, otherwise they are pixel coordinates. All cursor types
except 10 and 11 have LLG as the origin when pixel coordinates are used.
Types 10 and 11 use ULS coordinates. Member logical is true in any viewport
where logical drawing vectors are used. It is the driver's responsibility
to clip the cursor to the specified viewport.

For all values of pcursel other than 0 or 3, the driver should simply
return with pstat set to zero. This tells the Autodesk product to do the
work.

If the driver clears the cursor, it should return a value of 1 in member
pstat. Otherwise, it should return with pstat set to zero, instructing the
Autodesk product to clear the cursor itself.

ADI 4.1 and later drivers check to see if CF_STUDIO is set. If so, they
only XOR with the low 4 bits of the color palette.

See Also
--------
PBMARK, PCMARK, PMARK, PDCURS, PCCURS



6.17.16 PCCURS
================

Purpose
-------
Restores screen contents saved by the most recent PDCURS (i.e., removes the
raster cursor from the screen and repaints whatever was under it).

Limitations
-----------
PCCURS is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. Drivers indicate support for this packet by returning EF_CURS
in pefmodes at PINIT and PDINFO time. All ADI 4.2 drivers are required to
support this packet.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

If you are an ADS application, AutoCAD always removes any cursors from the
screen before giving control of the screen to you. You are required to
remove any cursors you put on the screen before you return control to
AutoCAD or before you switch modes (e.g., GOTEXT or RDSTART).

If you are controlling a display driver through a TEE driver, remember that
you must leave the cursor in the state AutoCAD expects it to be in. At a
minimum, on letting AutoCAD resume control, you must leave a cursor on
screen if AutoCAD had one on screen before you intervened, and you must not
have a cursor on screen if AutoCAD didn't.

Note that ADI drivers expect to get a PCMARK or PCBMARK packet just before
each PCCURS packet. The driver will fail the PCMARK or PCBMARK request.
Some drivers use the PCMARK or PCBMARK packet (which contains coordinates)
to manage value-added driver features.

You must never ask a driver to erase a non-existent cursor. You must never
change the screen contents under a raster cursor while it is up - when the
cursor is erased, the driver restores the old screen contents under the
cursor!

All the fields in this packet are filled in by AutoCAD. The driver treats
this as a read-only packet.

History
-------
This packet was added as part of the AUI in ADI 3.0 to support Release 9.
AUI support was optional until ADI 4.1 and Release 11.

Declaration
-----------
#define PCCURS  34

struct pkfonly {
    short pfunc;    /* PCCURS */
};

Description
-----------
PCCURS instructs the driver to restore the screen contents saved by the
most recent PDCURS request.

The PCCURS request is issued only if the driver set the EF_CURS bit in the
pefmodes member of the PINIT reply packet. PDCURS and PCCURS requests are
always made in pairs and are never nested, so only one save buffer is
required within the driver.

If an ADI driver is to work with AutoCAD Release 11 and later, or
AutoShade, it must support raster cursor requests.

See Also
--------
PDCURS



6.17.17 PCFGREC
=================

Purpose
-------
Configuration record returned to driver at execution time, before PINIT.

Limitations
-----------
PCFGREC is a display packet which can be emitted only by the primary
controlling product. The same product must handle all of the other display
configuration packets: PNEWCFG, PCHGCFG, and PSHOWCFG, including providing
support for them by creating a configuration file.

If the ADI driver stored a configuration record at configuration time, it
must be returned to it at execution time in this packet, before PINIT (and
after PLANG for ADI 4.2).

The alias id, paliasid, was not implemented for display ADI 4.1. It has
been implemented in ADI 4.2.

This is an execution-time configuration packet. Primary products must
support configuration packets.

All the fields in this packet are filled in by AutoCAD. The driver treats
this as a read-only packet.

History
-------
PCFGREC was added in ADI 4.0 for some platforms (XENIX, P386 and OS/2) and
in ADI 4.1 for all platforms except real-mode DOS. The paliasid member was
implemented in ADI 4.2.

Declaration
-----------
#define PCFGREC 59   /* execution time config record */

struct pkcfgrec {    /* executor portion of adi driver */
    short pfunc;     /* PCFGREC */
    short preclen;   /* configuration record length */
    char paliasid;   /* alias id */
    char pcfgrec[1];
};

Description
-----------
Your driver should check the data returned by PCFGREC for validity. An
incomplete configuration by the user might result in garbage in this
record.

If your driver stored a configuration record at configuration time, it is
returned to you at execution time in this packet.

The alias id, paliasid, was not yet implemented for display ADI 4.1. In ADI
4.2, the display driver's alias id index is returned in this member. If the
driver has no alias names, this member is zero.

3D Studio
---------
If your driver is a full DEV_RC driver, 3D Studio v1.0 sends only the
PNEWCFG packet. The pcfgrec member of this packet is returned later to your
driver through the execution-time PCFGREC and RPCFGREC packets. A bug in 3D
Studio version 1.0 limits pcfgrec[] to 100 bytes.

If your driver is NOT a full DEV_RC driver (a DEV_DS or DEV_RD), then 3D
Studio sends the PNEWCFG packet for DEV_DS drivers and the RPNEWCFG packet
for DEV_RD drivers.

See Also
--------
PINIT, PNEWCFG, PCHGCFG, and PSHOWCFG



6.17.18 PCHAR
===============

Purpose
-------
Draws a character on the graphics screen.

Limitations
-----------
PCHAR is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. All DEV_DS and DEV_RC drivers support this packet.

This is a display packet. It can be sent only to DEV_DS or DEV_RC drivers.
It can be sent only in graphic mode after PINIT.

ADI 4.2 P386 drivers which set DM_GROK and DM_GROKE in PINIT.pmodes also
expect to receive this packet while in text mode. Such drivers maintain a
second text position pointer to keep track of the current position on the
text screen.

Any pending sequence of PCHAR packets on the graphic screen must be
terminated by a PECHAR before changing graphic modes (RDSTART) or returning
control to the primary product.

The one exception to this rule is when a driver sets DM_GROKE in
PINIT.pefmodes and PDINFO.pefmodes. Such drivers get PHAR packets for text
intended for the text screen. These must be echoed to the text-on-graphic
screen immediately and are not followed by PECHAR.

Note that if a secondary application writes text into the screen menu by
using PCHAR, AutoCAD wipes it out when it next refreshes the screen menu.

All the fields in this packet are filled in by AutoCAD. The driver treats
this as a read-only packet.

History
-------
PCHAR was introduced in ADI 3.0 with the packet mode interface. It was
originally used to send characters to the status line (coordline and
modeline) and screen menu. As ADI packets have been converted to PASS_DATA
on most platforms, the use of PCHAR for the status line functions has been
dropped on those platforms (the text is sent as a string in PMODELINE and
PCOORDLINE instead). Likewise, PHLITE and PDHLITE on PASS_DATA platforms
include the menu string. On all platforms PCHAR is still used to send menu
items initially (after PMNUCURS).

In ADI 4.2 and Release 12, it is possible to configure AutoCAD to send
PCHAR packets instead of making DOS calls for text screen text.

Declaration
-----------
#define PCHAR  9

struct pkchar {
    short   pfunc;    /* PCHAR */
    short   pchar;
};

Description
-----------
PCHAR instructs the driver to draw the character specified by member pchar
on the graphics screen at the current text position. The current text
position is then be moved one character to the right by the driver.

PCHAR must be able to handle the following control characters: \t, \b, \n,
and \r.

Don't advance the text cursor for other non-printing characters. A new line
(\n) implies carriage return (\r). Carriage return does not imply new line.

A sequence of PCHAR requests (on the graphic screen) should be prefaced by
a text cursor positioning packet (PMNUCURS).

A sequence of PCHAR requests is always terminated by a PECHAR request
(unless operating in text-on-graphic screen mode), so drivers can buffer
the characters and process them when the PECHAR request is received if they
so choose.

In ADI 4.2, some displays use PCHAR to write text on the graphic screen.
Such drivers get PHAR packets for text intended for the text screen. These
must be echoed to the text-on-graphic screen immediately and are not
followed by PECHAR. These special PCHAR packets are sent only while in
"text mode", i.e., after PGOTEXT or PGOTEXTU and before PGOGRAPH.

See the following packet requests that set the current text position.

See Also
--------
PECHAR, PHLITE, PDHLITE, PMNUCURS, PTPROMPT



6.17.19 PCHGCFG
=================

Purpose
-------
This packet is sent at configuration time if the user elects to change the
existing video configuration.

Limitations
-----------
PCHGCFG is a display packet which can be emitted only by the primary
controlling product. The same product must handle all of the other display
configuration packets: PNEWCFG, PCFGREC, and PSHOWCFG, including providing
support for them by creating a configuration file.

For ADI 4.2, these packets should follow PWHO and PLANG.

This is a configuration-time packet. Primary products must support
configuration packets for all platforms except real-mode DOS ADI. A 490
byte configuration record should be supported for display drivers.

Typically the configuration record is a structure. The ADI driver may use
dispatcher services (see chapter 4) to conduct a dialogue with the user.
The primary application must support dispatcher services on all platforms
except real-mode DOS.

PCHGCFG, PNEWCFG and PSHOWCFG all share a single packet structure. They are
all used at configuration time. If the driver is being called for first-
time configuration, PNEWCFG should be sent and you must store any private
configuration record returned by the driver in a configuration file. Refer
to the PNEWCFG packet description.

If the driver has already been configured, then you might send the PCHGCFG
packet. This indicates that the user wants a chance to go back through the
configuration dialogue, possibly answering differently.

The driver is responsible for asking any questions of the user, collecting
and validating answers and constructing the configuration record.

AutoCAD sends this packet with all of the fields filled in. The ADI driver
modifies members preclen and pcfgrec.

Recall that you are limited to less than 490 bytes for your configuration
record (stored here). Typically your configuration record is a structure.
You may use the Autodesk product dispatcher services described earlier to
conduct your dialogue with the user.

A bug in Autodesk 3D Studio V1.0 limits the size of PCFGREC for 3D Studio
to the range from 1 - 100 bytes and a second bug causes Autodesk 3D Studio
to crash if you fail to supply a value for PRECLEN from 1 - 100 because the
default value supplied by Autodesk 3D Studio is invalid.

History
-------
PCHGCFG was added in ADI 4.0 for some platforms (XENIX, P386 and OS/2) and
in ADI 4.1 for the rest (DOS and UNIX).

Declaration
-----------
#define PCHGCFG  61       /* change configuration record */
/* PNEWCFG, PCHGCFG and PSHOWCFG all use this struct */

struct pkconfig {         /* config portion of adi driver */
    short pfunc;          /* PCHGCFG */
    short preclen;        /* configuration record length */
    char  pcfgrec[1];
};

Description
-----------
PCHGCFG, PNEWCFG and PSHOWCFG all share a single packet structure. They are
all used at configuration time. If your driver is being called for first-
time configuration, PNEWCFG is sent and you should return any private
configuration record. Refer to the PNEWCFG packet description.

If your driver has already been configured, then you might receive the
PCHGCFG packet. This indicates that the user wants a chance to go back
through the configuration dialogue, possibly answering differently.

Your driver is responsible for asking any questions of the user, collecting
and validating answers and constructing the configuration record.

See Also
--------
PCFGREC, PNEWCFG, PSHOWCFG



6.17.20 PCLEAR
================

Purpose
-------
Clears the entire graphics portion of the screen or a single viewport on
the graphic screen.

Limitations
-----------
PCLEAR is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. All DEV_DS and DEV_RC drivers support this packet. This
packet can be sent only after PINIT while in graphic mode (as opposed to
text or rendering modes).

If vpnumber is non-zero, it must be a valid viewport number for a viewport
which is currently open, and the ADI driver must be a BS or FAKE_BS driver.

Note that ADI drivers expect PCLEAR to support repaint requests. Secondary
applications should not use this packet if they care about the integrity of
the status line, scrolling text area or screen menu area, unless the
secondary application provides some means for restoring those areas (e.g.,
PBIGBLIT or PBOXPUSH).

AutoCAD fills in all of the fields of this packet. The ADI driver fills in
member prepaint.

History
-------
PCLEAR was added in ADI 3.0 with the packet mode interface. PCLEAR was
extended by adding the vpnumber member in ADI 4.0 to support multiple
viewports in Release 10. The repaint bit RP_BS was added in ADI 4.1.

Declaration
-----------
#define PCLEAR  3

struct pkclear {
    short  pfunc;     /* PCLEAR */
    short  prepaint;
    short  vpnumber;
};

Description
-----------
PCLEAR instructs the driver to clear the graphics portion of the screen. If
possible, the screen menu area, scrolling area, and status line are not
disturbed.

If vpnumber is 0, or if EF_BS is not set in pefmodes at PINIT time, the
driver clears the entire graphics screen (all viewports). Otherwise, the
driver clears only the specified viewport, without disturbing its borders.

The prepaint member is a bit-coded field used to determine which screen
areas, if any, should be repainted following the PCLEAR request. If the
driver is capable of clearing only the graphics portion of the screen
without disturbing the screen menu area, text scrolling area, and status
line, prepaint is assigned the value zero. Otherwise, the following bits in
prepaint are set depending on which areas of the screen must be redrawn by
the controlling application:

Table 6-18. Bit flag values for pkclear.prepaint

Mnemonic         Value Bit Meaning if Set

RP_STAT          0x1   0   Status line should be redrawn

RP_MENU          0x2   1   Screen menu area should be redrawn

RP_SCROLL        0x4   2   Text scrolling area should be redrawn

RP_GRAPH         0x8   3   Graphics area should be redrawn

RP_BS            0x20  5   Ask BS driver to Redraw


If the driver draws borders (not viewport borders) on the screen and they
are destroyed by clearing the screen, PCLEAR instructs the driver to
replace them.

In Windows ADI 4.1, winacad.dll hammers prepaint to what it believes to be
the correct value. Anything returned by a Windows ADI driver is ignored.



6.17.21 PCLOSEVP
==================

Purpose
-------
This optional packet closes a viewport.

Limitations
-----------
PCLOSEVP is a display packet and can be sent to DEV_DS and DEV_RC drivers
in display mode. Only BS DEV_DS and DEV_RC drivers support this packet, and
it can be sent only after PINIT.

Only the primary application (normally AutoCAD) may send this packet. If a
secondary application closes a viewport by sending this packet, AutoCAD and
the ADI driver will be out of synchronization -- AutoCAD will think the
viewport is open while the driver has already closed it.

The viewport to be closed must be open before the PCLOSEVP request is sent.
AutoCAD Release 11 occasionally violates this rule and closes viewport #1
(the paperspace viewport) twice without an intervening open. This is a bug.

All the fields in this packet are filled in by AutoCAD. The driver treats
this as a read-only packet.

History
-------
PCLOSEVP was added in ADI 4.0 to support multiple viewports in Release 10.

Declaration
-----------
#define PCLOSEVP 39

struct pkcvp {
    short   pfunc;    /* PCLOSEVP */
    short   vpnumber;
};

Description
-----------
PCLOSEVP is sent if EF_BS was set in PINIT.pefmodes. The driver discards
any display list data associated with the viewport and removes it from the
list of open viewports.

Note: Although it is a bug if an application closes an already closed
viewport, a prudent driver will nevertheless protect itself from such
misbehavior by ignoring the redundant request.



6.17.22 PCLVP
===============

Purpose
-------
PCLVP allows fast clearing of viewports for non-BS drivers.

Limitations
-----------
PCLVP is supported by all ADI 4.1 and later DEV_DS and DEV_RC drivers (they
set EF_MV in PINIT.pefmodes) which are not BS drivers. BS drivers are sent
the PCLEAR packet with member vpnumber non-zero instead of being sent the
PCLVP packet.

PCLVP may be sent only while the driver is in display mode and operating on
the graphic screen. Applications must insure that the coordinates supplied
in this packet are actually the corners of a valid viewport.

All the fields in this packet are filled in by AutoCAD. The driver treats
this as a read-only packet.

History
-------
Added in ADI 4.0 for AutoCAD Release 10 multiple viewport support.

Declaration
-----------
#define PCLVP  45

struct pkclvp {
    short pfunc;           /* PCLVP */
    short vpxmin, vpymin;
    short vpxmax, vpymax;
};
Description
-----------
This packet allows fast clearing of a viewport for non-BS drivers if EF_MV
was set and EF_BS was cleared in PINIT.pefmodes. BS drivers are sent the
PCLEAR packet with vpnumber instead of this packet.

The members vpxmin, vpymin, vpxmax and vpymax are expressed in LLG pixel
coordinates. These coordinates are sent because non-BS drivers have no
other way of knowing where the corners of a viewport are.

Your driver should quickly clear the specified rectangle to the currently
configured screen background color.



6.17.23 PCMARK
================

Purpose
-------
Instructs driver to clear the cursor at a screen location.

Limitations
-----------
PCMARK is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. All DEV_DS and DEV_RC drivers, except those which set
EF_BIGVEC in PINIT and PDINFO.pefmodes, support this packet. PCBMARK should
be used instead for ADI 4.2 drivers which set PDINFO and PINIT.pefmodes
EF_BIGVEC.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

If you are controlling a display driver through a TEE driver, remember that
you must leave the cursor in the state AutoCAD expects it to be in. At a
minimum, on letting AutoCAD resume control, you must leave a cursor on
screen if AutoCAD had one on screen before you intervened, and you must not
have a cursor on screen if AutoCAD didn't.

Note that ADI drivers expect to get a PCMARK packet just before each PCCURS
packet. The driver will fail the PCMARK request. Some drivers use the
PCMARK packet (which contains coordinates) to manage value-added driver
features.

If you are an ADS application, AutoCAD always removes any cursors from the
screen before giving control of the screen to you. You are required to
remove any cursors you put on the screen before you return control to
AutoCAD or before you switch modes (e.g., GOTEXT or RDSTART).

In ADI 4.2, BIGVEC drivers (those setting EF_BIGVEC in PINIT.pefmodes)
expect PCBMARK with 31-bit logical cursor coordinates. PCMARK may not be
sent to BIGVEC drivers, including FAKE_BS drivers. PCMARK uses 15-bit
logical coordinates for viewport relative cursors sent to ADI 4.2 BS
drivers. If the ADI driver is BS, vpnumber may be non-zero (but must be a
valid, currently open viewport) and the driver can be expected to clip the
cursor to the specified viewport.

ADI drivers only know how to draw a simple orthogonal cursor (cursel types
0 and 3). But drivers expect to be notified of all cursors, including those
they can't draw.

For all values of pcursel other than 0 or 3, the driver simply returns with
pstat set to zero. This tells you to do the work.

If the driver clears the cursor, it returns a value of 1 in pstat.
Otherwise, it returns with pstat set to zero, instructing you to clear the
cursor yourself.

The coordinates supplied in px and py must be for a point inside the
specified viewport (remember that viewport 0 is the entire graphic area of
the screen). A cursor of the specified type must exist at the specified
location so that the driver can erase it. Most ADI drivers use the same XOR
cursor routine to draw and erase types 0 and 3 cursors.

AutoCAD sets pstat to zero so that drivers which don't handle PCMARK will
have the cursor handled correctly by AutoCAD.

AutoCAD fills in all of the fields of this packet. The ADI driver fills in
member pstat.

History
-------
PCMARK was introduced in ADI 3.0 with the packet mode interface. It was
extended by the addition of member vpnumber in ADI 4.0 to support multiple
viewports in Release 10. It was further extended by the addition of the
member logical in ADI 4.2.

In ADI 4.2, the cursor coordinates in PMARK and PCMARK, for BS drivers and
viewport relative cursors in viewports where AutoCAD's logical space is
active, have been changed from pixel coordinates to 15-bit logical
coordinates and the logical flag set. This was done to eliminate pixel-off-
by-one errors.

Declaration
-----------
#define PCMARK  8

struct pkmark {
    short   pfunc;    /* PCMARK */
    short   pstat;
    short   px, py;
    short   pcursel;
    short   vpnumber;
    short   logical;
};

Description
-----------
PMARK instructs the driver to draw a cursor of type pcursel at screen
coordinates (px,py).

In ADI 4.2, BIGVEC drivers (those setting EF_BIGVEC in PINIT.pefmodes)
expect PCBMARK with 31-bit logical cursor coordinates. PCMARK is not sent
to drivers in BIGVEC mode (regardless of the BS status of the viewport in
question).

In ADI 4.2, PCMARK uses 15-bit logical coordinates for viewport-relative
cursors for ADI 4.2 BS drivers, if AutoCAD is using logical coordinates for
drawing in the viewport. It uses pixel coordinates for all viewport-
independent cursors, all pre-ADI 4.2 drivers, viewports where logical
coordinates are not active (e.g., in paperspace) and all non-BS ADI 4.2
drivers. A new member, logical, has been appended to pkmark for ADI 4.2.
This is FALSE if the coordinates are pixel and TRUE if they are logical.
All cursor types except 10 and 11 have LLG as the origin when pixel
coordinates are used. Types 10 and 11 use ULS coordinates.

For all values of pcursel other than 0 or 3, the driver should simply
return a value of 0 in "pstat", and the Autodesk product draws the cursor
itself.

pcursel values of 0 and 3 specify simple orthogonal crosshairs, and the
display driver may choose to draw these with optimized code. Autodesk
products normally draw a full- screen crosshair, but the driver can draw it
smaller (or allow the size to be configured by the user) if desired.

If the member logical is TRUE, the coordinates passed in px and py are
viewport relative logical coordinates. If the member logical is FALSE, the
coordinates are viewport independent pixel (LLG) coordinates. It is the
driver's responsibility to clip the cursor to the specified viewport.

If the driver draws the cursor, it should return a value of 1 in pstat.
Otherwise, it should return with pstat set to zero, instructing the
Autodesk product to draw the cursor.

ADI 4.1 and later drivers check to see if CF_STUDIO is set. If so, they
only XOR with the low 4 bits of the bitmap.

See Also
--------
PMARK



6.17.24 PCOMMAND
==================

Purpose
-------
This is an optional packet. PCOMMAND passes command strings not recognized
by AutoCAD core to the display driver as candidates for display driver
commands. Commands not recognized by the display driver are further passed
on to other places (e.g., pigpen commands).

Limitations
-----------
This packet is recognized by DEV_DS and DEV_RC drivers in display mode if
they set EF_CMD in member pefmodes in PINIT. It is used by AutoCAD to allow
display drivers to process commands unrecognized by AutoCAD. Since these
commands are, by definition, not official Autodesk commands, they vary
unpredictably from ADI driver to ADI driver. Unless a secondary application
is intended to work with only a limited number of specific drivers with
known commands, it makes no sense to try to use driver-local commands.

Most secondary applications will not use this packet.

AutoCAD fills in all the members of this packet. The ADI driver fills in
member pstat.

AutoCAD is currently the only product using PCOMMAND.

History
-------
PCOMMAND was introduced in ADI 3.0 with the packet mode interface. At that
time, a pointer to the command string was passed in the packet. In ADI 4.0
for XENIX, P386 and OS/2, PCOMMAND was modified to pass the string in the
packet. Starting with ADI 4.1, all platforms except real-mode DOS support
the pass-data form of PCOMMAND.

Declaration
-----------
#define PCOMMAND  25

struct pkcommand {
    short pfunc;           /*  PCOMMAND  */
    short pstat;           /* was command recognized? */
    short pstrlen;         /* Command length */
    char pcommand[1];      /* command string */
};

Description
-----------
PCOMMAND allows the driver to examine all input commands that are not
recognized by AutoCAD. It is sent only to drivers which set EF_CMD in
PINIT.pefmodes.

Your driver receives unrecognized "transparent" commands (those prefaced by
" ' ", such as 'Zoom) in addition to unrecognized regular commands. The
strings passed from such commands are "raw"; that is, no case conversion
takes place and the leading apostrophe (') is still present.

Transparent commands are sent to the driver only from AutoCAD Release 10 or
later versions.

The command string is passed as a null-terminated string in pcommand[],
with the string length in pstrlen.

If the driver returns 0 in pstat, it did not recognize the command or was
unable to execute it. Otherwise, the host assumes that the string has been
recognized and processed by the driver.

In AutoCAD Release 12, commands prefaced with a leading underscore have a
special meaning. Their English form is always recognized by AutoCAD (if the
command is recognized at all) even if the AutoCAD is otherwise a non-
English version. Furthermore, the leading underscore is stripped from
unrecognized commands before passing them to the display driver in
PCOMMAND.



6.17.25 PCOORDLINE
====================

Purpose
-------
Passes a null-terminated string for display on the coordinate line.

Limitations
-----------
PCOORDLINE is a display packet and can be sent to DEV_DS and DEV_RC drivers
in display mode. All DEV_DS and DEV_RC drivers support this packet.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen. It can be sent only to drivers which have
been told to maintain a status line; the primary application does this by
setting CF_STATUS in PINIT.pconfig.

ADS applications can determine whether this is enabled by examining
PDINFO.pconfig (this is read-only).

ADS applications can also write into the coordline area with the
conventional ADS function ads_grtext().

All the fields in this packet are filled in by AutoCAD. The driver treats
this as a read-only packet.

History
-------
PCOORDLINE was introduced in ADI 3.0 with the packet interface. At that
time, it did not pass the string ptext. In ADI 4.0 for XENIX, OS/2 and
P386, the packet was expanded to include ptext. Starting in ADI 4.1, all
platforms support the pass-data form of PCOORDLINE.

In ADI 4.2, we changed the suggested start of coordline from (pmodelinl +
1) to (pmodelinl + 2).

Declaration
-----------
#define PCOORDLINE 22

struct pkcoordline {
    short pfunc;           /* PCOORDLINE */
    short pnchars;         /* Number of characters in line */
    char ptext[1];         /* coord string */
};

Description
-----------
PCOORDLINE instructs the driver to set the current text position to the
start of the coordinate-status line, usually (pmodelinl + 2), and to write
the text string in ptext to the screen. Note that AutoCAD typically writes
25 characters to the coordinate-status line.

The value of member pmodelinl is returned in the PINIT reply packet.

The string to be displayed is passed to the driver as a null-terminated
string in ptext[]. This packet is the only notification of the need to
write a string to the coordinate area of the status line.

ADI drivers clip the string sent in ptext to the right edge of the status
line.

Your driver is expected to correctly handle the control characters \t and
\b.

Currently only AutoCAD uses the PCOORDLINE packet.



6.17.26 PDCURS
================

Purpose
-------
Instructs the driver to draw a raster cursor at a screen location, saving
the bitmap under the cursor.

Limitations
-----------
PDCURS is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. Drivers indicate support for this packet by returning EF_CURS
in pefmodes at PINIT and PDINFO time.

Support of this packet is required for 3D Studio, AutoShade, or AutoSketch.
It is also required for AutoCAD since Release 10.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

If you are an ADS application, AutoCAD always removes any cursors from the
screen before giving control of the screen to you. You are required to
remove any cursors you put on the screen before you return control to
AutoCAD or before you switch modes (e.g., GOTEXT or RDSTART).

If you are controlling a display driver through a TEE driver, remember that
you must leave the cursor in the state AutoCAD expects it to be in. At a
minimum, on letting AutoCAD resume control, you must leave a cursor on
screen if AutoCAD had one on screen before you intervened, and you must not
have a cursor on screen if AutoCAD didn't.

Note that ADI drivers expect to get a PMARK or PBMARK packet just before
each PDCURS packet. The driver will fail the PMARK or PBMARK request. Some
drivers use the PMARK or PBMARK packet (which contains coordinates) to
manage value-added driver features.

Note that the ADI driver saves the screen contents under the raster cursor
before drawing it and restores the screen on erasing it. It is crucial that
applications not change the screen contents while the raster cursor is on
screen, otherwise the driver damages the screen when it restores the old
screen contents.

You must set new_pat TRUE whenever a new pattern is sent to the display
driver.

All the fields in this packet are filled in by AutoCAD. The driver treats
this as a read-only packet.

History
-------
This packet was added as part of the AUI in ADI 3.0 to support Release 9.
AUI support was optional until ADI 4.1 and Release 11. The initial form of
PDCURS passed a pointer to the structure rcursor. In ADI 4.0 for XENIX,
OS/2 and P386, PDCURS was modified to pass the structure rcursor in the
packet. In ADI 4.1, all platforms supported the pass-data form of PDCURS.
In ADI 4.2 the member new_pat was added.

Declaration
-----------
/*  Raster cursor definition  */
struct rcursor {
    short curx, cury;           /* Overlap point */
    unsigned short curand[16];  /* Mask to AND w/ bitmap */
    unsigned short curxor[16];  /* Mask to XOR w/ bitmap */
};

/*  Packet for PDCURS */
#define PDCURS  33

struct pkdcurs {
    short pfunc;               /* PDCURS */
    short px, py;              /* Cursor draw location */
    struct rcursor pcursor;
    short new_pat;
};

Description
-----------
Starting in ADI 4.2, the member new_pat is sent as TRUE if this packet
contains a new raster cursor definition in the structure pcursor. Drivers
which have hardware-assisted raster cursors should reload the cursor
definition when new_pat is TRUE.

The cursor to be drawn is described in the rcursor structure by two 16 by
16 bit masks. The first mask, curand, is logically ANDed with the contents
of the screen. The second mask, curxor, is then XOR'ed with the screen
contents.

On a display with multiple bit planes, the AND and XOR operations are
usually performed in all bit planes.

Two members in the rcursor structure, curx and cury, specify the bit and
word number, respectively, of the bit in the cursor that overlays the
screen coordinates given by (px,py) in the PDCURS request packet (this is
often called the cursor's hot spot).

If members curx and cury are both zero, the upper leftmost point of the
cursor aligns with the screen coordinates. If curx and cury are both 8, the
cursor is centered around the screen point.

px and py specify the natural (ULS pixel) screen coordinates over which the
cursor alignment point should be positioned. These coordinates are always
viewport independent and can be any valid screen coordinates (i.e.,
anywhere on the graphic screen, status line, or screen menu area). It is
the responsibility of the driver to properly clip the cursor at the screen
edges.

The original screen area overlaid by the cursor is saved in a buffer so
that it can be restored by the PCCURS request.

High resolution display drivers may choose to do pixel multiplication to
make the raster cursor larger on the screen.

ADI 4.1 and later drivers check to see if CF_STUDIO is set. If so, they
only XOR with the low 4 bits of the color palette.

See Also
--------
PCCURS, PMARK, PBMARK, PCBMARK and PCMARK



6.17.27 PDHLITE
=================

Purpose
-------
Passes a null-terminated string (for menu dehighlighting).

Limitations
-----------
PDHLITE is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. All DEV_DS and DEV_RC drivers support this packet.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen. It can be sent only to drivers which have
been told to maintain a screen menu - the primary application does this by
setting CF_MENU in PINIT.pconfig.

Secondary applications can determine if this is enabled by examining
PDINFO.pconfig (this is read-only).

AutoCAD sends PMNUCURS to set the text cursor to the desired menu box
before sending PDHLITE.

The member pnchars is the number of characters in the menu box. 0 <=
pnchars <= 8.

The text that was in the menu box must be passed to the ADI driver in
pchars[].

The member pstat is ignored.

All the fields in this packet are filled in by AutoCAD. The driver treats
this as a read-only packet.

AutoCAD is currently the only product using PDHLITE.

History
-------
PDHLITE was introduced in ADI 3.0 with the packet interface. At that time,
it did not pass the string pchars. In ADI 4.0 for XENIX, OS/2 and P386, the
packet was expanded to include pchars. In ADI 4.1, all platforms except
real-mode DOS supported the pass-data form of PDHLITE.

Declaration
-----------
#define PDHLITE 12
/*  Packet for PHLITE and PDHLITE requests */

struct pkhlite {
    short pfunc;     /* PDHLITE */
    short pstat;     /* Status: send characters? */
    short pnchars;   /* Number of chars to dehighlight */
    char pchars[1];  /* Char string */
};

Description
-----------
PDHLITE instructs the driver to dehighlight the menu box specified by the
current text position.

This packet passes the driver a null-terminated string in pchars[]. This
packet is its only notification (apart from PMNUCURS) of the need to
dehighlight a menu item.

The member pnchars is the number of characters in the menu box.

The member pstat is ignored by AutoCAD. It is left over from earlier ADI
versions which did not include pchars.

See Also
--------
PHLITE



6.17.28 PDIGTIZE
==================

Purpose
-------
This is an optional packet. PDIGTIZE permits the display driver to monitor
and/or alter digitizer samples.

Limitations
-----------
PDIGTIZE is a display packet and can be sent to DEV_DS and DEV_RC drivers
in display mode. Drivers indicate support for this packet by returning
EF_DIGTIZ in pefmodes at PINIT and PDINFO time.

A primary application indicates that it can support PDIGTIZE by setting
CF_DIGTIZE in PINIT.pconfig. This indicates that the application has
control of both the screen and digitizer and can provide the translation
services involved in supporting PDIGTIZE. It is unlikely that secondary
applications will be able to do this.

An ADI driver indicates that it wants PDIGTIZE services by setting
EF_DIGTIZ in PINIT.pefmodes.

AutoCAD fills in all the members of PDIGTIZE. The ADI driver may modify any
member except pfunc.

Currently, only AutoCAD supports the PDIGTIZE request.

History
-------
This packet was introduced in ADI 3.1 to improve display list driver
support for Release 9. It has been replaced by PDIGTIZE_42 in ADI 4.2.

Declaration
-----------
#define PDIGTIZE 37

struct pkrpen {
    short   pfunc;    /* PDIGTIZE */
    short   pstat;
    short   px, py;
};

Description
-----------
PDIGTIZE is sent by pre-AutoCAD Release 12 to ADI drivers that request it
by setting EF_DIGTIZ in PDINFO and PINIT.pefmodes.

The PDIGTIZE request is issued whenever a digitizer sample is obtained from
the configured digitizer, and permits the display driver to intercept
and/or alter digitizer samples.

When a digitizer sample has been passed with this request, the ADI driver
can take several actions. It can do nothing, change the sample, request
another sample, or request that some digitizer coordinates be mapped to
screen coordinates. The filtered coordinates are then returned to the host
product.

The interface provided by this request is similar to an ADI digitizer
driver DGSENSE packet (although some of the encodings vary slightly). Each
PDIGTIZE request passes in a status, an X and a Y. The ADI driver returns
the same fields having possibly altered the values.

Except for packets with a pstat value of 1, the px and py values are in
digitizer space with (0,0) as the bottom left corner of the digitizer and
(20480,20480) as the upper right corner. Not all of the digitizer surface
is necessarily part of the screen pointing area and some digitizers may
(inappropriately) return coordinates all the way up to 32767.

Table 6-19. Values for PDIGTIZE.pstat

Value      Meaning

0          No sample available (px and py are meaningless)

1          px and py are the requested screen equivalents of the px and py
values most recently passed back from the ADI driver (see status 1 returned
by the ADI driver, below). px is between 0 and ymenumax or iydots
(whichever is greater). This status value is only returned immediately
following a previous PDIGTIZE request to which the driver replied with a
status of 1.

2          px and py are a tracking coordinate

3          px and py are a pick coordinate

-n         Button number n was pressed. px and py are the coordinates at
which this occurred, or are both -1 i no coordinates were returned by the
digitizer. For example, if pstat holds a -1, it means button number 1 was
pressed, -2 means button number 2 was pressed, and so on.


The ADI driver can return any of the preceding status values (except 1)
with the corresponding px and py coordinates, and the Autodesk product
performs the appropriate action.

The ADI driver can return a status of 1 or 4 to request special action. For
these two returned pstat values, the immediately following packet request
is another PDIGTIZE. No user keyboard input (not even <Ctrl-C>) is
permitted before the next request.

Table 6-20. Special action request values for PDIGTIZE.pstat

Value        Meaning

1            Convert the returned px and py values to screen coordinates
and call the ADI driver immediately with the converted values of px and py.

4            Do not use the returned px and py values. Instead, immediately
request another digitizer sample and return it in the next PDIGTIZE
request.


Before ADI 4.1, AutoCAD's digitizer interface did not permit tracking
coordinates to be returned while a pick button is depressed, nor did it
distinguish a short button click from a long one. Some P386 ADI 4.1
digitizers, all UNIX ADI 4.1 digitizers and all ADI 4.2 digitizers support
"DRAGG mode" (see chapter 9). Release 11 AutoCAD did not request DRAGG
mode, AutoCAD Release 12 does.

Some pre-ADI 4.2 display drivers have been using PDIGTIZE to detect double
click and long click mouse events. These drivers will have problems running
under Release 12 if the currently configured digitizer driver supports the
DRAGG option because Release 12 will enable it. When DRAGG is enabled, most
old driver's method of detecting long and double clicks fails. If the DOS
environment variable IGNORE_DRAGG is set to a non-null value (e.g., "yes"),
then Release 12 will not ask the digitizer driver to operate in DRAGG mode.
This is a work-around which disables some Release 12 features.



6.17.29 PDIGTIZE_42
=====================

Purpose
-------
This is an optional packet. PDIGTIZE_42 permits the display driver to
monitor and/or alter digitizer samples.

Limitations
-----------
PDIGTIZE_42 is a display packet and can be sent to DEV_DS and DEV_RC ADI
4.2 drivers in display mode. Drivers indicate support for this packet by
returning EF_DIGTIZ in pefmodes at PINIT and PDINFO time.

A primary application indicates that it can support PDIGTIZE_42 by setting
CF_DIGTIZE in PINIT.pconfig. This indicates that the application has
control of both the screen and digitizer and can provide the translation
services involved in supporting PDIGTIZE_42. It is unlikely that secondary
applications will be able to do this.

An ADI driver indicates that it wants PDIGTIZE_42 services by setting
EF_DIGTIZ in PINIT.pefmodes.

AutoCAD fills in all the members of PDIGTIZE_42. The ADI driver may modify
any member except pfunc.

History
-------
This packet was introduced in ADI 4.2 to provide services similar to the
old PDIGTIZE packet for new drivers. It has been expanded to accommodate
the added data sent by ADI 4.2 digitizer drivers.

Declaration
-----------
#define PDIGTIZE_42 105

packed struct pkrpen_42 {
    short pfunc;          /* Function code */
    short pstat;          /* Status: pen result */
    long px, py, pz;      /* Pen coordinates */
    long pix, piy, piz;   /* Pen roll, pitch and yaw */
    short pressure;
    short buttn;
    long pmodkey;         /* Modifier keys */
};

Description
-----------
ADI 4.2 display drivers which set EF_DIGTIZ receive PDIGTIZE_42 packets
from AutoCAD Release 12. An ADI 4.2 driver running with an older AutoCAD
receives PDIGTIZE instead. The content of the packet varies depending on
the revision level and capabilities of the currently configured digitizer
driver. ADI 4.2 display drivers can learn the revision level and other
characteristics of the currently configured digitizer by examining the
PTABCFG_42 packet. Note that AutoCAD now requests digitizer drivers to
operate in DRAGG mode (see chapter 9). Some ADI 4.1 digitizer drivers
supported this (then optional, now required) mode. Such old drivers and all
ADI 4.2 digitizer drivers now return valid coordinates while the pick
button is depressed and returns button-up events.

The PDIGTIZE_42 request is issued whenever a digitizer sample is obtained
from the configured digitizer, and permits the display driver to intercept
and/or alter digitizer samples. This request is only issued if the
CF_DIGTIZE and EF_DIGTIZE bit flags were set in the PINIT packet members
pconfig and pefmodes respectively.

When a digitizer sample has been passed with this request, the ADI display
driver can take several actions. It can do nothing, change the sample,
request another sample, or request that some digitizer coordinates be
mapped to screen coordinates. The filtered coordinates are finally returned
to the Autodesk product.

Table 6-21. Values for PDIGTIZE_42.pstat on initial PDIGTIZE_42 call

Mnemonic       Value                                      Meaning

P_NONE         0    No sample available (px and py are meaningless)

P_COORD        2    px and py are a tracking coordinate. If DRAGG mode is
active and a button is down, buttn holds the button number.

P_POINT        3    px and py are a pick coordinate

P_BUTTP        5    Indicates that a button was pressed, buttn holds the
button number, and if DRAGG mode is active, px and py hold valid
coordinates.

P_POINTUP      7    If DRAGG mode is active, this is returned when the pick
button is released. px and py are valid coordinates.

P_BUTTPUP      8    If DRAGG mode is active, this is returned when any
other button is released. px and py are valid coordinates.


After the initial PDIGTIZE_42 call, the ADI display driver can alter any of
the values in the pkrpen_42 structure, and AutoCAD responds as if they came
directly from the digitizer.

There are two special values, P_DIGTSC and P_NEXT, that the ADI display
driver can assign to member pstat that cause another PDIGTIZE_42 packet to
be immediately reissued to the display driver. No user keyboard input (not
even <Ctrl-C>) is permitted before the next request.

Table 6-22. Special action request values for PDIGTIZE_42.pstat

Mnemonic      Value                                       Meaning

P_DIGTSC      9    Convert the returned px and py values to screen
coordinates and call the ADI driver immediately with the converted values
of px and py.

P_NEXT        10   Do not use the returned px and py values. Instead,
immediately request another digitizer sample and return it in the next
PDIGTIZE_42 request.


There are two special pstat values that are not normally returned from
digitizers, they are P_DIGTSC and P_NEXT. The element pstat is equal to
P_DIGTSC (DIGitizer To SCreen) only if the display driver set it to this
value on a previous call. AutoCAD converts the previous packet members'
digitizer coordinates to screen coordinates and continues to do so until
the display driver sets pstat to another value. Currently the routine that
converts digitizer coordinates to screen coordinates only converts px and
py. After conversion from digitizer to screen coordinates, px is between 0
and member ymenumax or member iydots, whichever is greater.

The ADI display driver can also set pstat to P_NEXT if it wants to
immediately get another value from the digitizer. The next call to PDIGTIZE
will then set pstat to a valid digitizer status (i.e. P_NONE, P_COORD
etc.). The ADI display driver can alter any of the values, and AutoCAD
responds as if they came directly from the digitizer. However, if you
assign pstat an illegal value it disables the digitizer for the rest of the
editing session. For example, unlike the 4.1 version of PDIGTIZE, never
return a value of P_BUTTN in pstat to indicate a button pressed. Rather,
use P_BUTTP to return both the button and coordinates at the same time.
P_BUTTN is now an illegal return value which disables the digitizer. The
old request for coordinate transformation, 1, is also now illegal and
disables the digitizer. Note, however, that if the user issues a "REINIT"
command from the keyboard, the digitizer can be brought back to life.

Note that buttons are zero based. In other words the first button is a 0,
the second is 1 etc. Further information on digitizer drivers can be found
in chapter 9.

Note, PDIGTIZE_42 only gets sent while in the drawing editor proper. With
the advent of Proteus and in particular Tarnhelm on the Phar Lap version,
though the display driver is running when the main menu dialogue box is up,
no PDIGTIZE_42 sample is sent to the display driver. This is because the
Proteus digitizer input loop is separate from AutoCAD's.

There are three situations an ADI 4.2 display driver can encounter with
respect to digitizer drivers: pre-ADI 4.2 drivers which do not support
DRAGG mode, ADI 4.1 digitizers which do support DRAGG mode, and ADI 4.2
digitizer drivers. Your driver must examine PTABCFG_42 to learn which type
of digitizer is active.

For Old Digitizer Drivers without DRAGG Mode Support
----------------------------------------------------
The interface provided by this request is similar to an ADI digitizer
driver DGSENSE packet (although some of the encodings vary slightly). Each
PDIGTIZE_42 request passes in a status, an X and a Y. The ADI driver
returns the same fields having possibly altered the values.

Except for packets with a member pstat value of P_DIGTSC, the px and py
values are in digitizer space with (0,0) as the bottom left corner of the
digitizer and (20480,20480) as the upper right corner. Not all of the
digitizer surface is necessarily part of the screen pointing area and some
digitizers can (inappropriately) return coordinates all the way up to
32767.

AutoCAD's digitizer interface used to not permit tracking coordinates to be
returned while a pick button is depressed, nor did it distinguish a short
button click from a long one. All ADI 4.0 and earlier drivers fit this
description, as do those ADI 4.1 drivers which did not support DRAGG mode.

The possible return values for pkrpen.pstat from these old drivers are:
P_NONE, P_COORD, P_POINT, P_DIGTSC or P_BUTTP. Coordinates are returned
only in P_COORD (which is returned only when no buttons are pressed) and in
P_POINT or P_BUTTP at the initial instant when a button is pressed. P_NONE
is returned while any button is down or if the puck is not in contact with
the tablet.

The other members of pkrpen_42 (pix, piy, piz, pressure and pmodkey) are
not filled in for pre-ADI 4.2 digitizer drivers.

For Old Digitizer Drivers That Support DRAGG Mode
-------------------------------------------------
These are the same as old digitizers which don't support DRAGG mode, except
that these ADI 4.1 digitizers return tracking coordinates while any button
is down and return button up events as well.

The possible return values for pkrpen.pstat from these old drivers are:
P_NONE, P_COORD, P_POINT, P_DIGTSC, P_BUTTP, P_BUTTPUP and P_POINTUP.
Coordinates are returned in all except P_NONE. At the instant when a button
is pressed, P_POINT or P_BUTTP is returned once to report the button down
event. Then tracking coordinates are returned in P_COORD while the button
is down. When the button is released, a single B_BUTTPUP or B_POINTUP is
emitted, with valid coordinates.

The other members of pkrpen_42 (pix, piy, piz, pressure and pmodkey) are
not filled in for pre-ADI 4.2 digitizer drivers.

For ADI 4.2 Digitizer Drivers
-----------------------------
The ADI display is passed PX, PY, PZ, PIX, PIY, PIZ, pressure, and button
status. Unlike pre-ADI 4.2 digitizers, ADI 4.2 devices return these values
with the full range of natural coordinates, up to 32 bits wide. The values
are not scaled to 20480 in the digitizer driver. Thus, a display driver
must examine the range values passed in PTABCFG_42 to know how to interpret
the raw values passed in PDIGTIZE_42. The new packet member pmodkey may be
ignored on the 386 platform - it has meaning in windowing operating
systems.

Of course, many ADI 4.2 digitizers are only 2D and do not report the
optional 3D or pressure data. You must examine PTABCFG_42 to find out about
these capabilities. The ranges for unsupported degrees of freedom are zero.

Like the ADI 4.1 version of PDIGTIZE, the 4.2 version requires the ADI
display driver to set the EF_DIGTIZE bit flag in the pefmodes member of the
PINIT packet. Assuming that AutoCAD returns CF_DIGTIZE in the pconfig
member of PINIT, it sends pkrpen_42 packets to the ADI display driver.
These packets contain the full 6D (x, y, z and roll, pitch, yaw) digitizer
information as well as stylus pressure and button information. The pstat
element contains one of the following: P_NONE, P_COORD, P_POINT, P_POINTUP,
P_BUTTP, P_BUTTPUP, P_OUT, or P_DIGTSC.

P_NONE means that there is no valid sample from the digitizer. A value of
P_COORD is issued when the user is just moving the digitizer. P_COORD is
also issued between button down and button up events. A pick point is noted
by P_POINT and a release of the pick button is P_POINTUP. Likewise, the
first button on the digitizer would be noted by a P_BUTTP with buttn equal
to 0. A P_BUTTPUP with buttn equal to 0 would be issued when the user
released the first button.

Currently, only AutoCAD supports the PDIGTIZE_42 request.

Be careful if you issue two P_DIGTSC calls in a row from the ADI display
driver. The first P_DIGTSC correctly converts the x and y coordinates from
digitizer to screen coordinates. The second P_DIGTSC also converts what are
now screen coordinates (although AutoCAD interprets them as digitizer
coordinates) into another pair of screen coordinates.

When issuing a P_NEXT code in the ADI display driver, keep in mind that
digitizer drivers running under UNIX do not issue a new set of coordinates
if there is no change in the digitizer's state from the last reading. In
other words, if the digitizer hasn't moved from the last time the ADI
display driver got a PDIGTIZE_42, a P_NEXT may result in a pstat value of
P_NONE.

The value of 10 is used for P_NEXT, rather than 4 used in the ADI 4.1
PDIGTIZE packet, because the number 4 also stands for P_BUTTN. To avoid any
confusion, a new numbering scheme was chosen.

See Also
--------
PTABCFG_42, PRPEN_42, PDIGTIZE, PTABCFG, PRPEN



6.17.30 PDINFO
================

Purpose
-------
PDINFO allows secondary applications to inquire about display capabilities
any time a driver is in display mode. It also gives AutoCAD information
about color handling which is not available in any other display packet.

Limitations
-----------
PDINFO is a display packet and can be sent to ADI 4.2 DEV_DS and DEV_RC
drivers in display mode (after PCFGREC).

Applications should fill in pfunc and psize. The ADI driver fills in the
other fields.

PDINFO may be sent repeatedly.

History
-------
This packet was introduced in ADI 4.2 as a mandatory packet for display
drivers. It was modified several times during ADI 4.2 development by the
addition of new structure members.

Declaration
-----------
#define PDINFO 75                /* display info request */

struct pkdinfo {
    short pfunc;                  /* PDINFO, packet code */
    short psize;               /* Sizeof(struct pkdinfo) */
    short ixdots, iydots;         /* Display screen size */
    short pconfig;          /* Screen configuration bits */
    long  pefmodes;                 /* Options supported */
    long  iflags;                   /* Information flags */
    short adipktlevel;       /* ADI driver revision info */
    short devflags;              /* DEV_RC, DEV_RD, etc. */
    short ybias;         /* Conversion factor ULS to LLG */
    short hwfill;                       /* Polygon fill? */
    short dither_depth;       /* Bits of dithering depth */
    short ddepth;            /* Real display color depth */
    short ncolour;         /* Number of rendering colors */
    short maxintens;          /* Maximum color intensity */
    short nshades;   /* Number of shades per color (gun) */
    short alpha_depth;            /* Alpha channel depth */
    short pnuxdots, pnuydots;         /* AUI screen size */
    short pnuxbpc, pnuybpc;       /* AUI character sizes */
    short pnuxchars, pnuychars;       /* AUI screen size */
    short pxsize,pysize;            /* Total screen size */
    short pixwid, pixhgt;        /* Display aspect ratio */
    short vpnumber;         /* Currently active viewport */
    short vxdots, vydots;    /* Size of current viewport */
    short vxmin, vymin; /* LL corner of current viewport */
    short splithgt;        /* Scrolling text area height */
    long  lgxdots, lgydots;   /* Logical size of vp (BS) */
    long flags_3d;       /* Optional 3d capability flags */
    short npages;    /* # of display pages for this mode */
    short nlights;  /* Number of lights supported for 3D */
    short pmin, pmax;          /* Pressure sensing range */
    long x_max, y_max, z_max;            /* Linear range */
    long ix_max, iy_max, iz_max;     /* Rotational range */
    short buttons;      /* Number of "light pen" buttons */
};
#define PDINFOSIZE (sizeof(struct pkdinfo))

Description
-----------
This packet may be sent by a secondary application or by AutoCAD.

This packet is filled in by the ADI driver to inform an application of the
ADI driver's capabilities in display mode. The application sends the packet
with members pcode and psize filled in; the driver fills in the rest of the
fields.

The members ixdots, iydots, pconfig, pefmodes, ybias, pnuxdots, pnuxchars,
pnuychars, pnuydots, pnuxbpc, pnuybpc, and hwfill have the meanings defined
for PINIT. The member devflags has the meaning defined for the edevent
struct. The adipktlevel member is filled in by the driver with the
ADIPKTLEVEL it supports. An ADI 4.2 driver returns DS_LEVEL_42 in
adipktlevel.

The splithgt member is the difference in Y coordinate between the bottom of
the screen and the bottom of the graphic area on the screen. This is useful
for converting LLG values to a coordinate system based at the lower left
corner of the whole screen.

The members vxdots and vydots are used to return the size of the current
viewport, in pixels, or zero if there is an error. The members vxmin and
vymin are filled in by the driver with the LLG pixel coordinates of the
lower left corner of the current viewport, or zero if there is an error.
Our drivers keep track of the current viewport by use of a variable
"current_viewport" which is updated at each PSYNC. Note that Release 12
sends a PDINFO right after PINIT, before any PSYNC packets, so the
current_viewport variable should be initialized to 0 at PINIT time.

The member ybias is the difference in Y coordinate between the top of the
screen and the bottom of the graphic area, useful for converting from LLG
to ULS coordinates.

The iflags member reports the capabilities this driver has in display mode
(RDINIT and RD_INFO report on rendering mode capabilities).

Table 6-23. Values for PDINFO.iflags

Mnemonic          Value  Meaning

DI_MAPPED         0x1    supports a hardware mapped palette

DI_VGA_VSYNC      0x2    vsync available on std vga port

DI_R8BIT          0x4    8 bit raster capability

DI_R24BIT         0x8    24 bit raster capability

DI_R32BIT         0x10   32 bit raster capability

DI_SMOOTHPOLY     0x20   can draw smooth shaded polygons

DI_FLATPOLY       0x40   can fill flat shaded polygons

DI_CPOLY          0x80   accepts continuous color polygons

DI_BRESENHAM      0x100  uses Bresenham fills

DI_FAKE_BS        0x800  driver only pretends to be BS

DI_NOW_BS         0x1000                      the current viewport is BS

DI_NO_RPEN        0x2000                      don't send PRPEN_42 packets

DI_NO_STRINGS     0x4000                      don't send PSTRING packets

DI_CCECH_TEXT     0x8000                      don't echo <Ctrl-C> to text
screen

DI_TABCFG         0x10000                     send PTABCFG_42 packets


The iflags bit DI_MAPPED is set only if the driver actually uses a hardware
palette in display mode. Drivers which set this bit are expected to be
capable of palette animation. DEV_RC drivers which leave this bit clear can
still be sent palette mapping packets from old primary applications such as
3D Studio v1.0. ADS applications may briefly modify the AutoCAD default
palette by sending color mapping packets to drivers which leave DI_MAPPED
clear (e.g., AVE Render in its materials dialogue). ADS applications do not
use such modified palettes extensively -- this allows AutoCAD to use its
256 color indices without folding them down to the lower 16 colors.
Applications shouldn't expect palette animation to be possible if the
DI_MAPPED bit is clear.

Remember that DEV_RC drivers are required to support scanline reading and
writing in display mode. Thus, setting DI_R8BIT, for example, implies
support for both reading and writing 8 bit scanlines.

Note that only one of the three flags DI_R8BIT, DI_R24BIT or DI_R32BIT may
be set. Drivers that handle polygons (RDPOLY or RDCPOLY) must handle the
same color depth for both scanlines and polygons. For example, a driver
that reports DI_R24BIT must be able to handle RDCPOLY packets (if it
accepts polygons at all).

Some combinations of flag bits are illegal, for example:

  * DI_R8BIT and DI_SMOOTHPOLY -- smooth shading requires 24 or 32 bit
color

  * DI_R8BIT and DI_CPOLY -- continuous color implies 24 or 32 bit color

Drivers which set DI_SMOOTHPOLY must also set DI_CPOLY since continuous
color capability is a requirement for smooth shading.

If the driver sets neither DI_SMOOTHPOLY or DI_FLATPOLY, it is not able to
do polygon fill in this mode. If it doesn't set one of the three scanline
bits (DI_R8BIT, DI_R24BIT or DI_R32BIT, it doesn't handle scanlines in this
mode. Drivers that set DI_CPOLY may be sent RDCPOLY requests, and all
drivers that set DI_FLATPOLY may be sent RDPOLY requests. Drivers that set
DI_CPOLY and DI_SMOOTHPOLY may be sent shading factors at the vertices of
RDCPOLY packets.

The RF_BRESENHAM bit flag is set if your driver uses same fill algorithm
for rendering polygons (RDPOLY or RDCPOLY) in display mode as AutoShade
(Bresenham algorithm). Refer to the sample RDPTARGA Targa rendering driver
file, rdptarga.c, for an example of setting the RF_BRESENHAM flag and the
use of AutoShade's fill algorithm. Some of our other sample drivers do not
use AutoShade's fill algorithm and hence do not set RF_BRESENHAM.

The DI_FAKE_BS bit allows drivers that set EF_BS in pefmodes to "'fess up"
that they are only pretending to be BS drivers (if this is the case). Real
display list drivers leave this bit clear.

The DI_NOW_BS bit reports that the current viewport is BS and is accepting
logical vectors. Real display list drivers turn this off only for NO_BS
viewports. FAKE_BS drivers never turn this bit on.

The DI_NO_RPEN flag is set if your driver does not want to receive PRPEN_42
packets. The DI_NO_STRINGS flag is set if your drivers does not want to
receive PSTRING packets.

Drivers that don't want <Ctrl-C> echoed to the TEXT screen, e.g., those
that put the text window on the graphic screen, can set DI_CCECH_TEXT.

The DI_TABCFG request bit allows drivers to request PTABCFG_42 packets
independently of the PINIT request EF_DIGTIZ, which also turns on
PDIGTIZE_42 packets. This is used by display drivers that don't want to
look at digitizer data but do want to know what digitizer is configured
(our ADI 4.2 UNIX DEV_RC drivers do this to find out if the system mouse or
an ADI digitizer is configured).

The ddepth member specifies the display mode color depth in bits. A VGA in
16-color mode would report ddepth = 4, while a super VGA in 256-color mode
would report 8 bits per pixel. A true color device might return 16 or 24
here. This is informational and does not affect the behavior of AVE Render.

The dither_depth member reports the number of bits of dithering which is
added to the ddepth color value. For example, a standard VGA with 4 bit
ddepth might do 4x4 dithering to add 4 bits of dither_depth. Display modes
with no dithering report zero for dither_depth. This is informational and
does not affect the behavior of AVE Render, for example.

The members ncolours, nshades and maxintens are used by AVE Render to
determine what color model the driver will use in display mode. 3D Studio
v1.0 (which predates PDINFO) always assumes a mapped palette and sends
palette data scaled to a 6 bit depth for R, G and B.

DEV_DS drivers must also fill in member ncolours, maxintens and nshades.
Note that PRCMAP's reports on color values are scaled to fit the range
defined by maxintens.

The ncolour field specifies the total number of entries in the color lookup
table (LUT) and determines the number of colors that can be simultaneously
displayed on the screen. Values used to index into the color lookup table
(i.e., the value assigned to the code variable in the RDCMAP request) are
within the range zero to (member ncolour minus one). A driver with 4 bits
of hardware color and 4 bits of dithered color would report 256 colors in
ncolours.

AVE Render reserves the high bit of the ncolour field for internal use and
masks it off from the value returned by the driver. Although the valid
range of values for ncolour is from 0 to 32767, it is generally not useful
to report values greater than 256. Although your driver might be sent some
color map entries above 255, AVE couldn't use these in 8 bit scanline data,
for example. Generally, drivers are advised to report ncolours as zero if
they wish to make use of more than 256 colors.

If the driver returns ncolour equal to zero, AVE Render treats the device
as a continuous-color device for rendering purposes, but still sends
RDRCMAP, RDCMAPB, RDCMAP and RDCMAPE packets to query and temporarily
modify AutoCAD's palette for Proteus dialogues. RDPOLY packets are never
sent to continuous-color drivers. Instead, the RDCRANGE request is issued
at the start of a rendering and RDCPOLY packets are sent. Since the
paletted model can only support 256 colors, it is common for devices with
more than 256 colors to report ncolour as 0 and operate as continuous
color.

The maxintens field is no longer ignored if ncolour is 0. It is meaningful
both for paletted devices reporting 0 < ncolour <= 32768 and for continuous
color devices. Continuous-color devices need to report the depth of their
fake palette (probably implemented by a lookup table) because AVE Render
needs to be able to modify AutoCAD's palette temporarily for Proteus
dialogues.

The maxintens field specifies the maximum value that can be assigned to the
red, green, or blue components of a color lookup entry. For example, the
values assigned to the red, green, and blue variables passed to the driver
via the RDCMAP packet are within the range zero to maxintens. Similarly,
AVE Render stretches the color palette RGB values for all three guns (R, G
and B) to fit the range zero to maxintens. Drivers which have different map
depths for different guns usually return the largest map depth here and
choose to internally scale the color values for the gun(s) with smaller
color ranges.

The nshades field is ignored if ncolour is 0. It is meaningful only for
paletted devices reporting 0 < ncolour < 32768. For continuous- color
devices, AVE Render assumes nshades = maxintens + 1.

The nshades field specifies the number of shades available per color, which
in turn determines the permissible number of intensity values for a single
RGB gun.

For most devices, nshades equals (maxintens plus one). However, some
devices allow a smaller number of shades per RGB gun than the value
assigned to maxintens. The nshades member may also be expressed as nshades
equals two raised to the n power (2^n), where n is the number of bits in a
color lookup entry. Thus a 6-bit device would report nshades as 64 and an 8
bit device would report 256.

The alpha_depth member reports how many bits of alpha channel this mode
supports. The value is 0 if there is no alpha channel. It might be 1 if
there is just an overlay bit. Some devices support 8 bits of alpha channel.

The flags_3d member reports on optional capabilities for processing 3d
floating point polygon data. AVE Render examines these flags, drivers
without 3D capabilities must be sure to set flags_3d to zero.

Table 6-24. Values for PDINFO.flags_3d

Mnemonic            Value                                Meaning

D3_VP               0x2  Can do 3D operations in a viewport (display only)

D3_WIRE             0x4  3D wireframes with hidden line removal

D3_FLAT             0x8  Can do flat shading

D3_GOURAUD_NORM     0x10                                 Color
interpolation for PNPOLY3s

D3_GOURAUD_COL      0x20                                 Color
interpolation for PCPOLY3s

D3_AMBIENT          0x40                                 Ambient light type
supported

D3_DIRECTED         0x80                                 Directed light
type supported

D3_POINT            0x100                                Point light type
without shadows

D3_SPOT             0x200                                Spotlight type
supported

D3_MATL             0x400                                Understands
material properties

D3_MIXED            0x800                                Can mix rendering
modes

D3_PHONG            0x1000                               Normal
interpolation for PNPOLY3s

D3_OVFLAT           0x2000                               Can override
between single-normal & normal/vertex shading

D3_OVWIRE           0x4000                               Can override
between solid shading and wireframes

D3_OVNORMS          0x8000                               Can override
between normal/vertex shading models

D3_SEGMENTS         0x10000                              Can maintain a 3D
segmented display list


The npages member reports the number of pages of display memory available
in this video mode. If a driver supports more than one display mode in the
current configuration (e.g., both 3D and 2D), and if the different modes
have different numbers of pages available, the value reported in npages is
the smallest number available in any mode for this configuration. Drivers
that report npages > 1 must support PVPAGES. Drivers which do not support
multiple pages should report npages = 1.

The nlights member specifies the number of light sources the driver can
support when doing 3D rendering.

The members pmin, pmax, x_max, y_max, z_max, ix_max, iy_max, iz_max and
buttons are all information about the "light pen" supported by your display
driver. If you handle PRPEN_42 packets, the device which provides this
input is considered by AutoCAD to be a "light pen". AutoCAD assumes that
this device reports in screen pixels (LLG, viewport independent
coordinates). Your driver should fill in the members x_max, y_max and z_max
with the largest values your device sends to AutoCAD for each coordinate
axis. If your device does not support Z, for example, it should return
z_max as zero. The members pmin and pmax report the minimum and maximum
values of stylus pressure your device can return (if any). The values
ix_max, iy_max and iz_max report the maximum values your device returns for
roll, pitch and yaw angles of 360 degrees, which are defined as follows:

The angles ix, iy and iz specify rotations about the x, y and z axes in 3-
space. If you picture an airplane with its x-axis parallel to the fuselage
and its y-axis parallel to the wings, then 'ix' is roll or rotation about
the x-axis; 'iy' is pitch or rotation about the y-axis; and 'iz' is yaw or
rotation about the z-axis. Since the order in which you apply these
rotations can produce different orientations, we propose here that the
order of rotations be applied in the order x, y then z. The direction of
rotation about an axis is defined by the right-hand rule. In other words,
if you are looking down the x-axis from a point in the positive x direction
towards the origin, the rotation would be applied counter- clockwise. A
reference point from which to apply the rotation (i.e. from where to
measure 0 degrees) is defined as any point on the positive z-axis for an x
rotation, any point on the positive x-axis for a y rotation, and any point
on the positive y-axis for a z rotation. The number of degrees to apply to
a rotation is defined as (ix * (360 / (ix_max + 1))), where ix <= ix_max.



6.17.31 PDLFNAME
==================

Purpose
-------
Put up a get file dialogue box.

Limitations
-----------
PDLFNAME is a display packet used only on platforms with windowing
operating systems. It may be sent to DEV_DS and DEV_RC drivers in display
mode. All DEV_DS and DEV_RC drivers on windowing platforms (UNIX, OS/2 and
Windows, but not Mac) support this packet.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

AutoCAD fills in all the members of this packet. The ADI driver may modify
members pstat and ptext.

History
-------
PDLFNAME was introduced in OS/2 ADI 4.0. It has also been used in ADI 4.1
for UNIX and Windows display drivers. The use of PDLFNAME has been replaced
by Proteus dialogues on most ADI 4.2 platforms.

Declaration
-----------
#define PDLFNAME 55     /* GetFileDialogue packet. */

struct pkdlfname {
    short pfunc;        /* PDLFNAME code */
    short pstat;        /* returned status */
    short pflags;       /* flags */
    char ptext[1];      /* Dialog title */
                        /* prefix or path */
                        /* default filename */
                        /* extension */
                        /* returned filename */
};

Description
-----------
This packet was handled by OS/2 ADI 4.0 and UNIX ADI 4.1 display drivers.
For Windows ADI 4.1, this packet was intercepted by AutoCAD code and was
not sent to the display driver, AutoCAD took care of creating the necessary
dialogue. ADI 4.2 drivers do not see this packet (Proteus operations
replace this).

Four null-terminated strings are concatenated in ptext[] when it arrives in
this packet from AutoCAD. They are:

  * the dialogue title

  * the file prefix or path

  * the default filename

  * the extension desired.

One null terminated string is returned to AutoCAD in ptext[], the string
contains the returned filename.

Table 6-25. Values for PDLFNAME.pkstat

Mnemonic        Value Meaning

UDS_NORMAL      0     A filename is returned in ptext[]

UDS_CANCEL      -4    User canceled dialogue, no filename returned


Table 6-26. Values for PDLFNAME.pflags

Mnemonic        Value                 Meaning

DLFPUT          0x1   New file

DLFINSIST       0x4   Don't allow default or cancel




6.17.32 PDLDIR
================

Purpose
-------
Put up a get directory dialogue box.

Limitations
-----------
PDLDIR is a display packet used only on platforms with windowing operating
systems. It may be sent to DEV_DS and DEV_RC drivers in display mode. All
DEV_DS and DEV_RC drivers on windowing platforms (UNIX, OS/2 and Windows,
but not Mac) support this packet.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

AutoCAD fills in all the members of this packet. The ADI driver may modify
members pstat and ptext.

History
-------
PDLDIR was introduced in OS/2 ADI 4.0. It has also been used in ADI 4.1 for
UNIX and Windows display drivers. The use of PDLDIR has been replaced by
Proteus dialogues on most ADI 4.2 platforms.

Declaration
-----------
#define PDLDIR    56  /* Dialogue box to get directory */
      /* GetDirDialogue packet.  Packet for requesting
                       directory name from the driver. */
struct pkdldir {
    short pfunc;                        /* PDLDIR code */
    short pstat;                    /* returned status */
    short pflags;                             /* flags */
    char ptext[1];                   /* Dialogue title */
                                  /* default directory */
                                 /* returned directory */
};

Description
-----------
This packet was handled by OS/2 ADI 4.0 and UNIX ADI 4.1 display drivers.
For Windows ADI 4.1, this packet was intercepted by AutoCAD code and was
not sent to the display driver - AutoCAD took care of creating the
necessary dialogue. ADI 4.2 drivers do not see this packet (Proteus
operations replace this).

Two null-terminated strings are concatenated in ptext[] when it arrives
from AutoCAD. The first is the dialogue title and the second is the default
directory. One null-terminated string is sent back to AutoCAD in ptext[].
This is the returned directory string.

Table 6-27. Values for PDLDIR.pkstat (driver fills this in)

Mnemonic        Value                           Meaning

UDS_NORMAL      0    A directory name is returned in ptext[]

UDS_CANCEL      -4   User canceled dialogue, no directory name returned


Table 6-28. Values for PDLDIR.pflags (AutoCAD fills this in)

Mnemonic        Value                   Meaning

DLFINSIST       0x4  Don't allow default or cancel




6.17.33 PDOT
==============

Purpose
-------
To XOR the dot (pixel) at a screen location.

Limitations
-----------
PDOT is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. All DEV_DS and DEV_RC drivers support this packet.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

ADI drivers usually do not test the dot coordinates for validity, off-
screen values can crash the system. It is the controlling application's
responsibility to clip the grid dots to the current viewport.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
This packet was introduced in ADI 3.0 with the packet mode interface.
Replaced by PROW for ADI 4.2 BS drivers. Note: during the early stages of
ADI 4.2 development, pkdot had a new member: vpnumber. This has been
dropped and the original structure readopted.

Declaration
-----------
#define PDOT  4

struct pkdot {
    short   pfunc;    /* PDOT */
    short   px, py;
};

Description
-----------
PDOT instructs the driver to XOR the dot at the location given by (px,py).
If the device is a multi-plane color display, the dot is usually XOR'ed in
all planes.

The members px and py and in LLG pixel coordinates and must be limited to
the graphic area of the screen.

Although ADI 4.2 BS drivers should expect PROW instead of PDOT for BS
viewports, such drivers must still be able to handle PDOT for viewports
where logical coordinates are not used (e.g. in paperspace or DVIEW).

This packet is currently used by the Grid command in AutoCAD and may be
tested by using that command.



6.17.34 PDRAG
===============

Purpose
-------
This is an optional packet. An AutoCAD display driver may choose to
maintain a local drag display list to speed up dragging operations. Display
list (BS) and non-display list drivers can choose to maintain drag lists
(they are separate features).

Limitations
-----------
PDRAG is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. Drivers indicate support for this packet by returning EF_DRAG
in pefmodes at PINIT and PDINFO time.

If you choose to use PDRAG, your application must provide some very complex
services for the ADI driver.

You must always keep information on hand to send erasing vectors in case
the ADI driver's drag display list overflows.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

This packet may not be sent to BS drivers in BIGVEC mode - use PBDRAG
instead.

If you are an ADS application, you should remove any drag vectors from the
screen before taking control of the screen. You are required to remove any
drag vectors you put on the screen before you return control to AutoCAD or
before you switch modes (e.g. GOTEXT or RDSTART).

AutoCAD fills in all the members of this packet. The ADI driver modifies
dmode to report on its status. The rest of the fields are read-only.

AutoCAD is currently the only product using PDRAG.

History
-------
PDRAG was introduced in ADI 4.0 to support Release 10. It is replaced by
PBDRAG for ADI 4.2 BIGVEC drivers.

Declaration
-----------
#define PDRAG  43

struct pkdrag {
    short   pfunc;      /* PDRAG */
    short   pfx, pfy;
    short   ptx, pty;
    short   ptcolor;
    short   dmode;
    short   vpnumber;
};

Description
-----------
The action for the driver to take depends on the value passed in member
dmode. The packet field dmode can have five possible values, 0 - 4,
discussed below.

The structure members pfx, pfy, ptx, and pty are in viewport-relative
logical coordinates.

There are several states a viewport can be in with respect to drag vectors
(typically represented by a local flag, dstate). In addition, if the driver
has used up its local memory, it should set an overflow flag. (See the
sample display driver dspega42.c for examples.)

Table 6-30. Viewport states with respect to drag vectors

dmode       dstate      Overflow    Coordinate Type    Add to drag list

1           0    No     LLG         Yes

1           1    Yes    LLG         No

2           2    No     L           Yes

2           3    Yes    L           No

4           4    No     LLG         Redrawing moved image

4           6    No     L           Redrawing moved image


Table 6-31. Key for viewport states table

Code       Definition

LLG        Absolute pixel (viewport-independent) vectors

L          Logical (viewport-relative) vectors


Actions Based on PDRAG.dmode Values
-----------------------------------
dmode = 0
---------
Add the vector to the drag list for the specified viewport and display it,
even if the display list has overflowed. The driver must remember
information sent to it by dmode 1 or 2 to know if vectors sent for this
viewport are pixel or logical, and handle them accordingly.

return value: none

dmode = 1
---------
Initialization call. The driver should forget any existing drag list for
the viewport in member vpnumber. Future vectors sent with dmode 0 for this
viewport will be absolute pixel vectors. This call precedes the vector list
associated with AutoCAD operations such as Rotate where a simple
displacement of the drag list is not useful. The next movement in a drag
sequence will instruct the driver to erase the drag image. It is not
necessary to scale or clip any vectors sent with a viewport initialized
with dmode = 1.

return value: none

dmode = 2
---------
Initialization call. The driver should forget any existing drag list for
the viewport in member vpnumber. Future vectors sent through dmode 0 for
this viewport will be logical vectors.

This call precedes the vector list associated with AutoCAD operations such
as Move, where a simple displacement of the drag list is useful. The next
movement in a drag sequence will probably instruct the driver to erase and
redraw the drag image after applying a displacement to it (this requires
the driver to scale and clip the vectors to the current viewport).

return value: none

dmode = 3
---------
Instructs the driver to erase anything already drawn from the drag list. If
the driver buffers vectors and has not drawn all of them, it should erase
the ones already drawn and flush the rest from the buffer.

If this packet is sent when a movable drag image is partly redrawn in its
new position (because of fresh user input), the driver should erase what
has been drawn and stop that Redraw sequence (you will probably soon get a
fresh dmode = 4 call). If the driver is able to erase any drag vectors
already drawn, it should return dmode = 1 to signal success.

If the driver cannot do the erase (because the drag list space overflowed
as vectors came in), it should not erase anything, and return dmode = 0 to
tell AutoCAD. AutoCAD sends XOR vectors through dmode = 0 to erase it. Any
vectors sent to this viewport through dmode = 0 should be drawn (which
erases) until you get a fresh initialization for this viewport's drag mode.

Table 6-32. Return values in PDRAG.dmode (3)

Value        Meaning

0            Driver was unable to perform the requested operation

1            Successful erase operation


dmode = 4
---------
Instructs the driver to displace (move) all of the vectors in the drag list
by the specified amount. The driver is responsible for redrawing the
vectors in the new position. (This is preceded by a dmode = 3 call to erase
the old image.)

If there are many vectors to redraw, the driver should not do them all at
once. After about 100 milliseconds, the driver should return with dmode set
to 1 to indicate that more redraw is required. After AutoCAD checks for
input from the user, the driver is called again with dmode set to 4 to let
the driver continue the Redraw. It is your driver's responsibility to
remember where to continue redrawing.

Table 6-33. Return values in PDRAG.dmode (4)

Value        Meaning

0            Driver was unable to perform the requested operation

1            Partway through redraw operation

2            Successful completion of redraw operation


If the driver cannot perform the requested displacement (i.e., the display
list overflowed), it should return dmode = 0. AutoCAD handles erasing and
redrawing the image by sending vectors through the drag vector facility.
The driver should leave the overflow flag set so the vector facility will
know to just draw and not add the vectors to a drag list.

The driver should return with dmode = 2 when the image has been completely
redrawn.

Fill mode is off during drag sequences; filled shapes are sent as outlines.



6.17.35 PECHAR
================

Purpose
-------
Indicates the end of a string.

Limitations
-----------
PECHAR is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. All DEV_DS and DEV_RC drivers support this packet.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

Any pending sequence of PCHAR packets on the graphic screen must be
terminated by a PECHAR before changing graphic modes (e.g., PGOTEXT or
RDSTART) or returning control to the primary product.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PECHAR was introduced in ADI 3.0 with the packet mode interface.

Declaration
-----------
#define PECHAR  10

struct pkfonly {
    short  pfunc;    /* PECHAR */
};

Description
-----------
PECHAR indicates the end of a string of characters sent by a sequence of
PCHAR requests. If your driver has been buffering characters, display them
now.



6.17.36 PEVENT
================

Purpose
-------
Reports mouse and keyboard events to AutoCAD.

Limitations
-----------
PEVENT is a display packet and is sent from DEV_DS and DEV_RC drivers to
AutoCAD on some UNIX windowing systems.

The ADI driver fills in all of the members of this packet. AutoCAD treats
this as a read-only packet.

History
-------
PEVENT was introduced in ADI 4.1 for Sun UNIX.

Declaration
-----------
#define PEVENT 63

struct pkevent {
    short pfunc;
    short pevid;       /* event code (see below) */
    dcoord px, py;     /* device coordinates--nonkeyboard */
    short pcode;       /* key/button code */
    long modify_keys;  /* up/down state of modifier keys */
};

Description
-----------
PEVENT is used on platforms where the display driver handles keyboard and
mouse input. It is sent from the display driver to AutoCAD with the pevid
code filled in to indicate the type of event reported. The px and py fields
are filled in only for mouse events. The member pcode contains either a
mouse button code or a character returned from the keyboard. The
modify_keys member is filled in only for mouse events, it reports on the
state of the modifier keys: shift and control.

Table 6-34. Event code values for PEVENT.pevid

Mnemonic        Value                Meaning

EVTNULL         0    Null tracking coordinate

EVTCOORD        1    Tracking coordinate

EVTBUTTON       2    Mouse/menu button press

EVTKEY          3    Keyboard character

EVTREDRAW       4    Redraw required

EVTREGEN        5    Regen required

EVTGRSIZE       6    Graphics window resize

EVTTXSIZE       7    Text window resize

EVTRDSIZE       8    Render window resize

EVTUP           9    Button up events

EVTLEAVE        10   Cursor leaving window


See modkeys.h for more information regarding the following table:

Table 6-35. Modifier key values for PEVENT.modify_keys

Mnemonic                Value

MODKEY_SHIFT            0x00000001

MODKEY_CTRL             0x00000002

MODKEY_ALT              0x00000004

MODKEY_CAPS_LOCK        0x00000008

MODKEY_NUM_LOCK         0x00000010

MODKEY_SCROLL_LOCK      0x00000020

MODKEY_INSERT           0x00000040




6.17.37 PFILL
===============

Purpose
-------
This is an optional packet. PFILL instructs the driver to draw a filled
polygon.

Limitations
-----------
PFILL is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. Drivers indicate support for this packet by returning 2 in
PINIT.phwfill or in PDINFO.hwfill.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

This packet should not be sent to BS viewports of display drivers in BIGVEC
mode (those which set EF_BIGVEC in PINIT.pefmodes and PDINFO.pefmodes).
BIGVEC drivers should be sent PBFILL instead for BS viewports.

If you set vpnumber to 0, the vertices in pvert[] must be in LLG pixel
coordinates. In this case, the entire polygon must be inside the graphic
screen - the ADI driver does not clip it for you.

You can set vpnumber to a non-zero value only if talking to a BS ADI driver
in a BS viewport. In this case, you must use a valid viewport number (i.e.,
for a viewport which is currently open). Then the vertices in pvert[] must
be in viewport-relative 15-bit logical coordinates. You can expect the ADI
driver to scale and clip the polygons to fit the specified viewport.
Logical nondrawing polygons should be used to display polygons which must
align exactly with drawing entities (which are sent in logical coordinates
to a BS driver).

Secondary applications should always set DR_NORDRAW in pdrawm - only
primary applications may send "drawing" polygons. If you want highlighted
polygons, you can also set DR_HILITE.

MINLCOLOR <= pcolour <= 255.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PFILL was introduced in ADI 3.0 with the packet mode interface. It was
extended in ADI 4.0 by the addition of member vpnumber to support multiple
viewports in Release 10.

Declaration
-----------
#define PFILL 6

struct pkfille {
    short   pfunc;        /* PFILL */
    short   pcolour;
    short   pdrawm;
    short   pnvert;
    short   pvert[12][2];
    short   vpnumber;
};

Description
-----------
If the ADI driver does not do its own fills, AutoCAD sends vectors for
filled shapes through the normal drawing vector packets (PVEC or FASTDRAW).

If EF_BS in member pefmodes is set in the PINIT reply packet, the vertex
coordinates passed in pvert[][] are viewport- relative 15-bit logical
coordinates. If EF_BS was not set (in PINIT) member vpnumber should be
ignored.

If the phwfill member in the PINIT reply packet is assigned the value 2 (1
is not used), PFILL will be sent when AutoCAD wants your driver to draw a
filled polygon.

Your PFILL handler must be able to do XOR fills, and is required to handle
non-drawing fills with pcolour equal to negative 1 as XOR.

Because AUI must be supported in ADI 4.2 drivers, pcolour may be less than
-1, indicating a logical color number. In this case, the driver should
substitute the appropriate physical color corresponding to the requested
logical color.

If the (possibly adjusted) color value passed in pcolour is neither 0 nor -
1, that color should be used to draw the filled area.

If pcolour is 0, the area should be erased, preserving the background color
if it is something other than black.

If your driver implements highlighting, pcolour is greater than 0, and the
DR_HILITE (pdrawm bit 0) is set, the filled area should be highlighted
(usually done by highlighting every fifth line of the fill). Our drivers
also draw a highlighted vector around the outlines of the polygon. This
makes the highlighting of thin polylines work.

The polygon to be drawn is made up of member pnvert vertices, which are
defined in a two-dimensional table, pvert. This table contains 12 columns
representing up to 12 vertices, and two rows representing X and Y
coordinates. Valid column subscript values must be within the range 0 to
(pnvert - 1). Valid row subscripts are 0 for X coordinates, and 1 for Y
coordinates. Although 12 vertices can be represented, AutoCAD never passes
a polygon with more than 10 vertices to PFILL. You probably should also be
conservative.

Refer to appendix A for information on color numbers.



6.17.38 PFLUSHCHAR
====================

Purpose
-------
Flush (display) buffered characters for the graphic window scrolling text
area.

Limitations
-----------
PFLUSHCHAR is a display packet and can be sent to AutoCAD for Windows ADI
4.1 DEV_DS and DEV_RC drivers in display mode.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
This packet was introduced in ADI 4.1 for AutoCAD for Windows Release 11.

Declaration
-----------
#define PFLUSHCHAR  134

struct pkflushchar {
    short pfunc;       /* PFLUSHCHAR */
    short really;      /* if TRUE do CR, else leave cursor */
};

Description
-----------
Flushes buffered characters for the graphic window scrolling text area.
These will have previously arrived via PTXTCHAR. This improves performance.



6.17.39 PGOGRAPH
==================

Purpose
-------
Switches a single-screen system to the graphics screen (from the text
screen).

Limitations
-----------
PGOGRAPH is a display packet and can be sent to DEV_DS and DEV_RC drivers
in display mode. All single screen DEV_DS and DEV_RC drivers support this
packet.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

Note that ADI drivers expect PGOGRAPH to support repaint requests.
Secondary applications should not use this packet if they care about the
integrity of the status line, scrolling text area or screen menu area,
unless the secondary application provides some means for restoring those
areas (e.g., PBIGBLIT or PBOXPUSH).

AutoCAD fills in all the members of this packet. The ADI driver can modify
the prepaint member.

History
-------
This packet was introduced in ADI 3.0 with the packet mode interface. The
repaint flag RP_BS was added in ADI 4.0 for PASS_DATA platforms and in ADI
4.1 for real-mode DOS.

Declaration
-----------
#define PGOGRAPH  19

struct pkgograph {
    short   pfunc;     /* PGOGRAPH */
    short   prepaint;
};

Description
-----------
PGOGRAPH instructs the driver to switch to the graphics screen. This
request is issued only on single-screen systems, indicated by the DM_GROK
bit flag (bit 2) set in the pmodes member of the PINIT reply packet.

Ideally, this operation should be nondestructive, displaying the picture,
status line, and screen menu area exactly as they were when the display was
switched to the text screen. The text scrolling area should reflect the
last few lines of the text screen, if possible.

The prepaint member is a bit-coded field identifying the screen areas, if
any, that should be repainted by requests from the Autodesk product
following the PGOGRAPH request.

If the driver can nondestructively switch to the graphics screen, it
returns prepaint equal to 0. Otherwise, the following bits in prepaint are
set, depending on which areas of the screen must be redrawn:

Table 6-36. Values for PGOGRAPH.prepaint

Mnemonic        Value Meaning if set

RP_STAT         0x1   Repaint status line.

RP_MENU         0x2   Repaint status line.

RP_SCROLL       0x4   Repaint scroll area.

RP_GRAPH        0x8   Redraw picture (non-BS).

RP_TEXT         0x10  Redraw from hidden text screen.

RP_BS           0x20  Ask BS driver to Redraw graphics.

RP_DIALOG       0x40  Redraw a dialogue box.

RP_MLOAD        0x80  Reload menu.


A BS driver can request RP_BS when it wants the graphic screen refreshed.
This would trigger a Redraw request which sends nondrawing vectors from
AutoCAD but gives the BS driver a chance to redraw from its local display
list. Thus, for a BS driver, RP_BS is preferred to RP_GRAPH, which sends a
fresh display list. RP_BS works for both real mode and protected-mode ADI
4.1 and later drivers.

If RP_GRAPH (prepaint bit 3) is set, requiring the Autodesk product to
redraw the picture, the Redraw process issues the PCLEAR request packet. If
the PCLEAR request in turn uses its prepaint member to restore the screen
menu area, text scrolling area, or status line, there is no need to request
restoration of these screen areas in the prepaint member returned by the
PGOGRAPH request packet.

The Autodesk product cannot redraw the text scrolling area if the driver
maintains its own hidden text screen (as indicated by zero values for the
phidlines and phidcols members returned in the PINIT reply packet).

If the driver draws borders (or other information not known to the Autodesk
product) that are destroyed by switching to the text screen and back to the
graphics screen, it is the responsibility of the driver to restore these on
receipt of PGOGRAPH.

The bit flags RP_TEXT, RP_DIALOG and RP_MLOAD are for windowing systems and
can be ignored in P386 and DOS ADI drivers.

See Also
--------
PINIT, PGOTEXT, PGOTEXTU



6.17.40 PGOTEXT
=================

Purpose
-------
Switches single-screen system to the text screen and clears it.

Limitations
-----------
PGOTEXT is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. All DEV_DS and DEV_RC drivers support this packet. This
packet can be sent only while the driver is in display mode and operating
on the graphic screen.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
This packet was introduced in ADI 3.0 with the packet mode interface. The
text-on-graphic screen, DM_GROKE feature is new in ADI 4.2.

Declaration
-----------
#define PGOTEXT 17

struct pkfonly {
    short   pfunc;    /* PGOTEXT */
};
Description
-----------
PGOTEXT instructs the driver to switch to the text screen, clearing it and
leaving the cursor in the upper left corner.

The PGOTEXT request is issued only on single-screen systems, indicated by
the DM_GROK flag (bit 2) set in the pmodes member of the PINIT reply
packet.

Subsequent to this call, the Autodesk product uses regular O/S I/O to write
to the text screen, unless the ADI driver also sets the DM_GROKE flag in
PINIT.pmodes, in which case PCHAR packets are sent to the driver, allowing
it to maintain a text window on the graphic screen.

See Also
--------
PINIT, PGOTEXTU, PGOGRAPH



6.17.41 PGOTEXTU
==================

Purpose
-------
Switches single-screen system to the text screen and displays the stored
hidden text information.

Limitations
-----------
PGOTEXTU is a display packet and can be sent to DEV_DS and DEV_RC drivers
in display mode. All DEV_DS and DEV_RC drivers support this packet.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
This packet was introduced in ADI 3.0 with the packet mode interface. The
text-on-graphic screen, DM_GROKE feature is new in ADI 4.2.

Declaration
-----------
#define PGOTEXTU 18

struct pkfonly {
    short   pfunc;    /* PGOTEXTU */
};

Description
-----------
PGOTEXTU instructs the driver to switch to the text screen, displaying
hidden screen information.

The PGOTEXTU request is issued only on single-screen systems, indicated by
the DM_GROK flag (bit 2) set in the pmodes member of the PINIT reply
packet.

If your driver maintains its own hidden screen (indicated by returning both
phidlines and phidcols equal to 0 in the PINIT reply packet), it should
switch to the text screen, display the hidden screen information, and
restore the cursor to its previous position on the text screen.

If the hidden screen is maintained by the Autodesk product (indicated by
nonzero values returned in members phidlines and phidcols in the PINIT
reply packet), your driver should switch to the text screen, clear it, and
leave the cursor at the top. The Autodesk product automatically rewrites
the hidden screen.

Subsequent to this call, the Autodesk product uses regular O/S I/O to write
to the text screen, unless the ADI driver also set the DM_GROKE flag in
PINIT.pmodes, in which case PCHAR packets are sent to the driver, allowing
it to maintain a text window on the graphic screen.

See Also
--------
PGOGRAPH, PGOTEXT, PINIT



6.17.42 PHLITE
================

Purpose
-------
Highlights the menu box at the current text position.

Limitations
-----------
PHLITE is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. All DEV_DS and DEV_RC drivers support this packet.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen. It can be sent only to drivers which have
been told to maintain a screen menu; the primary application does this by
setting CF_MENU in PINIT.pconfig.

Secondary applications can determine if this is enabled by examining
PDINFO.pconfig (this is read-only).

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PHLITE was introduced in ADI 3.0 with the packet interface. At that time,
it did not pass the string pchars. In ADI 4.0 for XENIX, OS/2 and P386, the
packet was expanded to include pchars. In ADI 4.1, all platforms supported
the pass-data form of PHLITE.

Declaration
-----------
#define PHLITE  11

struct pkhlite {
    short pfunc;       /*  PHLITE  */
    short pstat;       /* Status: send characters? */
    short pnchars;     /* # of characters to highlight */
    char pchars[1];    /* char string */
};

Description
-----------
PHLITE instructs the driver to highlight the menu box specified by the
current text position. This can be done either by transforming the pixels
already displayed at the specified location or by redisplaying with the
string supplied in pchars.

The member pnchars contains the number of characters in the menu box.

This packet passes a null-terminated string in member pchars[]. This packet
is your only notification (apart from PMNUCURS) of the need to highlight a
menu item.

The member pstat is left over from earlier ADI versions which did not
include pchars. It is ignored by AutoCAD.

AutoCAD is currently the only product using PHLITE.

See Also
--------
PDHLITE



6.17.43 PINIT
===============

Purpose
-------
Initializes the driver.

Limitations
-----------
PINIT is a display packet supported by all DEV_RC and DEV_DS drivers. It is
normally sent only by primary applications. If a secondary application
sends PINIT (not recommended), it must send the same pconfig flags which
the primary product used (or at least it must send PINIT again with the
same pconfig values just before giving control back to the primary
application).

PINIT and PREINIT are not allowed between RDINIT and RDEND.

Secondary applications wanting to know about a DEV_DS or DEV_RC driver's
capabilities can use PDINFO for ADI 4.2 and later.

AutoCAD fills in members pfunc, pconfig and pintlev. On windowing platforms
it also fills in cdname. The ADI driver fills in all of the other fields
and modifies pintlev.

History
-------
PINIT was introduced in ADI 3.0 with the packet mode interface. It was
extended by the addition of member ybias in ADI 4.0. New bit fields have
been defined for pefmodes with every ADI revision. EF_SHELL and EF_DIGTIZE
were added in ADI 3.1. EF_MV, EF_DRAG and EF_BS were added in ADI 4.0.
EF_PROVP and EF_PTEXT were added in ADI 4.1. New bit fields were also added
to pconfig. In ADI 4.1, CF_STUDIO was added to support 3D Studio.

The use of pmodes DM_GROK and DM_GROKE to signal support for a DOS window
on the text screen was added in P386 ADI 4.2.

The flags CF_BIGVEC and EF_BIGVEC were added in ADI 4.2.

In ADI 4.1 drivers were first required to return their interface level in
pintlev - before ADI 4.1 this was not required.

The member cdname[] was added for some ADI 4.0 platforms.

Declaration
-----------
#define PINIT  1

struct pkinit {
    short pfunc;            /* PINIT */
    short pstat;            /* Status */
    long pefmodes;          /* Extended function modes */
    short pconfig;          /* Screen configuration bits */
    short pintlev;          /* Interface level */
    short pixdots;          /* Screen component sizes */
    short piydots;          /* Screen component sizes */
    short pixdotsm;         /* Screen component sizes */
    short pmodelinl;        /* Mode line length */
    short pmnuchars;        /* Menu box size in chars */
    short pmaxboxes;        /* Maximum menu size */
    short pmodes;           /* Display modes */
    char psplit;            /* Lines in scrolling ares */
    char phwfill;           /* Hardware fill mode */
    short pixwid, pixhgt;   /* Pixel width & height (ratio)*/
    char phidlines;         /* Hidden screen lines */
    char phidcols;          /* Hidden screen columns */
    short pymenumax;        /* Screen menu height in pixels*/
    short pnuxdots;         /* AUI screen size in dots */
    short pnuydots;         /* AUI screen size in dots */
    short pnuxchars;        /* AUI screen size in chars */
    short pnuychars;        /* AUI screen size in chars */
    short pnuxbpc, pnuybpc; /* Bits per character */
    short ybias;            /* ULS - LLG y coord */
    long (*pfdraw)();       /* FASTDRAW routine */
    char cdname[1];         /* Current drawing name */
};

Description
-----------
PINIT is called sometime after PWHO, PLANG and PCFGREC. Not all Autodesk
controlling products send PLANG or PWHO.

EF_PTEXT (PINIT.pefmodes) must be supported by all ADI 4.2 DEV_DS and
DEV_RC drivers.

When PINIT is called, the members pfunc, pconfig and pintlev, are
initialized by the Autodesk product. On some platforms, member cdname is
also initialized by the Autodesk product. All the other fields in the
packet should be filled in by the driver and returned to the Autodesk
product.

The primary purpose of PINIT is for the Autodesk product and the display
driver to exchange initializing information about each other. The
controlling product tells the driver its ADI interface level and product ID
and passes on some user- configured options (in member pconfig).

BS drivers must return EF_MV, EF_PROVP, EF_REDRAW and EF_BS at PINIT time.

short pfunc
-----------
Sent by the Autodesk product containing the packet code PINIT (#define
PINIT 1).

short pstat
-----------
The ADI specification has always required that the driver return member
pstat as 1 on successful initialization. DOS AutoCAD did not enforce this
requirement, but AutoCAD 386 does. Also, note that if your driver fails to
initialize and returns 0 in pstat, single-screen systems should be sure to
put the display in text mode for proper error handling.

Invalid configuration data are possible if your driver requires information
from a local configuration record passed to it in PCFGREC at execution
time, and if the original configuration process was not properly completed
(e.g., if the driver was not found at configuration time, the user
corrected this at execution time but failed to go back and complete
configuration).

The sample driver dspega42 checks to see if the configuration data passed
to it is valid before completing PINIT handling, prints an error message
and returns 0 in PINIT.pstat if the data are not valid.

long pefmodes
-------------
The pefmodes member is a 32-bit, bit-coded options field. The status of a
bit in this field specifies the presence or absence in the driver of a
handler for an extended request. The currently defined bits, and the
requests they represent, are listed in the following table:

Table 6-37. Extended request options for PINIT.pefmodes

Mnemonic       Value                                      Meaning if set

EF_SYNC        0x1   Use PSYNC to synchronize the display with the local
display list or to request special functions.

EF_REDRAW      0x2   Use PREDRAW to Redraw from the local display list.
Post-ADI 3.1 drivers that set this bit should also set EF_BS and EF_MV in
PINIT, and must support BS features. ADI 4.1 BS drivers must also set
EF_PROVP.

EF_CMD         0x4   Use PCOMMAND to process unrecognized commands.

EF_XPCMD       0x8   Use PXPCOMD to process transparent command characters.

EF_NEWI        0x10  Driver supports AUI requests.

EF_SAVEB       0x20  Not used in P386 ADI drivers. Was used by DOS drivers
to ask for help storing PBOXPUSH data.

EF_FDRAW       0x40  FASTDRAW or PBATCHVEC routine is supplied in the
pfdraw member.

EF_CURS        0x80  Raster cursor requests supported.

EF_SHELL       0x100                                      Shell command
notification desired.

EF_DIGTIZ      0x200                                      Use PDIGTIZE(_42)
to filter digitizer input.

EF_MV          0x400                                      If clear, driver
is pre-ADI 4.0 and there is no support for multiple viewports. If set,
there is some support for multiple viewports.

EF_DRAG        0x800                                      Driver supports
drag lists.

EF_BS          0x1000                                     Driver is a BS
(Big Screen) device.

EF_NOCURS      0x4000                                     No cursor packets
desired.

EF_SYMENU      0x8000                                     Enable system
menu bar.

EF_PROVP       0x10000                                    Driver is a BS
driver and supports ADI 4.1 features.

EF_PTEXT       0x20000                                    Driver supports
TAPIXEL, TAXPARENT and PBITBLT. Required for 3D Studio.

EF_BIGVEC      0x40000                                    Driver uses 31-
bit logical vectors.


Support of the Advanced User Interface (AUI) is no longer optional as it
was prior to AutoCAD Release 11. Thus, your driver should set the EF_NEWI
flag (member pefmodes bit 4) and initialize the following fields: pnuxdots,
pnuydots, pnuxchars, pnuychars, pnuxbpc, and pnuybpc. Clearing EF_NEWI and
setting the fields listed to zero disables AUI support.

In supporting AUI, the driver must be capable of saving a screen rectangle
and subsequently restoring it. AutoCAD 386 does not provide space for box
push requests. P386 and UNIX drivers have direct access to virtual memory
instead.

EF_SAVEB (member pefmodes bit 5) is not used in P386 ADI. It was used
previously to have AutoCAD provide screen-save buffers for real mode
drivers.

If EF_FDRAW (member pefmodes bit 6) is set, the driver supports a fast
vector draw or PBATCHVEC routine (see the FAST VECTOR MODE section and the
PBATCHVEC section in this chapter).

If your driver supports viewport-specific clearing, PCLVP, and is not a big-
screen driver, it should set EV_MV, but not EF_BS. Older drivers which do
not set EF_MV are sent a large, filled polygon to clear a viewport; this
process is quite slow for most drivers (especially if they don't support
PFILL).

Setting EF_DRAG indicates that the driver supports the smart dragging
abilities introduced in ADI 4.0. If this bit is set, the driver receives
PDRAG (or PBDRAG if EF_BIGVEC is also set) packets. PDRAG sends colored
vectors (instead of XOR vectors through PVEC) for the entities to be
dragged. When the driver has been given a list of vectors to drag it may
then be given a displacement to apply to the list. Another packet tells you
to forget the vectors you have been dragging. Your driver does not have to
be a BS driver to use PDRAG. Implementing color XOR is optional; regular
XOR also works as long as you are consistent.

If the driver sets EF_BS, a new structure member, vpnumber, is added (only
by AutoCAD) to the end of several ADI packet structures and several new
packets are activated. When this new member vpnumber is 0, the driver
receives information which is viewport-independent; coordinates are passed
in the LLG system. If vpnumber is nonzero, your driver must handle a
viewport-specific operation in the specified viewport. Coordinates are
passed in the logical system for the specified viewport. If EF_BS is set,
EF_MV should also be set.

If you set EF_PROVP in member pefmodes, you are claiming to be a BS driver
which supports ADI 4.1 features. In addition to handling the ADI 4.0 BS
packets, your driver should do the following:

  * Return EF_MV, EF_REDRAW and EF_BS and be a display list driver.

  * Handle the new PREDRAW RE_XXX flags.

  * May use PKZOOM (or it may not).

  * Must handle PROPENVP.

  * Must return PMAXVP.

  * May use NO_BS in PREVEC (or it may not).

  * Must use pknstring instead of pkstring if it uses PSTRING.

  * May use the new PSYNC features if it sets EF_SYNC.

  * May use the new "zoomable" flag in PLOPEN.

We assume that your driver development is occurring in the protected-mode
environment. However, for your information, if your driver is a real-mode
ADI 4.1 driver and sets EF_PROVP, it also:

  * must use PSTRING instead of PCONIN

  * may use RP_BS as a repaint request in PGOGRAPH.

EF_NOCURS is used on some UNIX platforms to indicate that the driver never
attempts to draw cursors and is uninterested in the PMARK, PBMARK, PCMARK,
PCBMARK, PDCURS and PCCURS packets.

EF_SYMENU is used on some UNIX platforms to enable the system menu bar.

EF_PTEXT is set by drivers which support pixel aligned text (TAPIXEL), the
transparent attribute (TAXPARENT) and the PBITBLIT packet. Such support was
optional in Release 11 AutoCAD and is required by both AutoCAD Release 12
and 3D Studio.

EF_BIGVEC is set by drivers which want 31-bit logical vectors. ADI 4.2 BS
drivers should be user-configurable so that the user can turn on or off
EF_BIGVEC to choose between saving memory or having fewer regens. Drivers
which set EF_BIGVEC must also set EF_BS and EF_REDRAW. Such drivers are
sent POPENBVP, PBVIEWPORT, PBIGVEC, PBMARK, PCBMARK and other BIGVEC
packets in place of the 15-bit versions.

The remaining bits in pefmodes are currently unused and should be
explicitly cleared by your driver to avoid incompatibilities with future
versions of ADI.

short pconfig
-------------
The pconfig member is a 16-bit, bit-coded field for passing information
from the Autodesk product to the driver. It specifies the driver features
supported by the product or required by the particular Autodesk product in
use, and describes the screen configuration defined by the user during
configuration. The following table describes the current bit settings:

The following table shows the Autodesk product supported or required
feature bit flags for PINIT.pconfig:

Table 6-38. Values for PINIT.pconfig

Mnemonic        Value    Bit             Meaning if Set

CF_TEXT         1    0   Text scrolling area defined

CF_MENU         2    1   Screen menu area defined

CF_CURS         8    3   Raster cursor required

CF_DIGTIZE      16   4   Digitizer filtering supported

CF_ZOUT         32   5   Initial display is Zoomed out

CF_SYNC         64   6   SYNC request supported

CF_BIGVEC       128  7   BIGVEC requests supported

CF_STUDIO       2048     11              Product is 3D Studio

CF_SHADE        8192     13              Product is AutoShade

CF_SKETCH       16384    14              Product is AutoSketch

CF_ACAD         32768    15              Product is AutoCAD


The CF_CURS bit, if set, indicates a requirement for raster cursors (must
support PDCURS and PCCURS). AutoCAD does not require raster cursor support
and therefore does not set this bit when PINIT is called. However,
AutoShade and AutoSketch do require raster cursor support. Thus, CF_CURS is
set if they are the Autodesk product being used. If CF_CURS is set and your
driver does not support raster cursors, it should indicate initialization
failure by returning member pstat equal to zero.

If an ADI driver is to work with AutoSketch or AutoShade, it must support
raster cursor requests (PDCURS and PCCURS) and respond by setting both the
CF_CURS bit in the pconfig member and the EF_CURS bit in the pefmodes
member. (Autodesk products that do not require raster cursor support can
use raster cursors if the driver sets the EF_CURS bit in pefmodes.)

The flags CF_ZOUT, CF_SYNC, and the product identification bits (CF_STUDIO,
CF_SHADE, CF_SKETCH and CF_ACAD) are only meaningful for an ADI interface
level of 5 or greater (passed in member pintlev).

short pintlev
-------------
The host product sends its ADI display driver interface level to your
driver in pintlev, using constants defined in dsadic42.h. Your driver must
return its own interface level in pintlev back to the host for upward
compatibility with future versions of ADI. This is one of the few places
where the old interface numbering scheme "INTLEVEL" is still used.

If your driver requires an interface level other than that specified by
member pintlev, or features not indicated as present by pconfig, it should
return with pstat set to zero to indicate initialization failure.

The value for pintlev for ADI 4.2 is 8.

short pixdots, piydots, pixdotsm
--------------------------------
Your driver should set member pixdots to one less than the horizontal size
of the graphics area (minus the screen menu area) and member piydots to one
less than the vertical size of the graphics area (minus the text scrolling
area and status line). (AutoCAD only)

AutoShade uses member pnuydots instead of member piydots to determine
graphic screen size, thus for AutoShade your graphic screen (and piydots)
must be an exact multiple of characters high (see discussion of pnuydots
below). AutoCAD can make use of "left over" pixels if your screen is not an
exact number of character cells high. AutoShade misaligns text and vectors
in AUI if you violate this restriction.

member pixdotsm is the maximum horizontal pixel number (including screen
menu area) beginning at zero. The total number of pixels in the X direction
is (pixdotsm + 1). (AutoCAD only)

short pmodelinl
---------------
pmodelinl is the number of characters available for the status line.
pmodelinl must be at least 37 to avoid an abbreviated status line in the
English language version of AutoCAD, other languages typically require more
room to display the standard status line data. Modern displays should be
able to provide at least 45 characters of pmodelinl. The count does not
include characters available for the coordinate display. (AutoCAD only)

It is desirable for pmodelinl to be as long as possible, while still
allowing space for coordline and the screen menu (if configured). Since the
coordinate line area is 25 characters, the screen menu is 8 characters wide
and a character of space is required between modeline and coordline, on a
typical 80 column screen, pmodelinl can be 45 or so.

If your driver is configurable for different font sizes or graphic
resolutions, you should adjust the value of pmodelinl for each different
configuration.

Pmodelinl is clipped in Release 12 AutoCAD core to a "sane" value. Negative
values are clipped to 0 and large positive values are clipped to 240

Note that there are features in AutoCAD Release 12 (e.g., modemacro) which
allow users to put much more text into the status line than in previous
AutoCAD versions.

short pmnuchars, pmaxboxes
--------------------------
member pmnuchars is the number of characters available for screen menu
items and member pmaxboxes is the number of screen menu boxes on the screen
(zero if no screen menu is configured). See the CF_MENU bit flag of the
pconfig member. (AutoCAD only)

AutoCAD defaults to expecting 8 characters for menu items. The AutoCAD menu
has to be recompiled to change this value.

short pmodes
------------
The pmodes member is a bit-coded field that specifies modes pertaining to
the operation of the display device.

Table 6-39. Values for PINIT.pmodes

Mnemonic       Value Meaning if Set

DM_CCECH       0x1   Suppress echo of <Ctrl-C>

DM_HLEN        0x2   Driver can do highlighting

DM_GROK        0x4   Driver is single screen

DM_GROKE       0x8   Driver is dual screen*

DM_ASCIIBM     0x80  Driver supports 8 bit fonts


GROK and GROKE are actually a 2-bit field which maps into a screen
configuration switch as follows:

Table 6-40. GROK and GROKE configuration

Value      Meaning

0x0        Dual-screen system, no graphics/text mode switching

0x1        Single-screen system, no graphics while in text mode

0x2        Dual-screen, display driver does not handle text output, but
wants notification of graphics/text mode switches (Apollo model)

0x3        Dual-screen, like 2, but driver handles text (Sun model or new
P386 text-on-graphic screen)


The DM_CCECH flag (member pmodes bit 0) indicates that echoing a <Ctrl-C>
to the screen while in graphics mode destroys the display, and that <Ctrl-
C> should therefore be suppressed. This bit should be set only for single-
screen displays that lack separate image planes for text and graphics.
Setting this bit inhibits a <Ctrl-C> that is typed ahead (follows other, as
yet unprocessed keyboard input) from taking effect immediately.

Note that ADI 4.2 drivers have another flag, DI_CCECH_TEXT in PDINFO, which
can be used to also suppress <Ctrl-C> echoing while on the text screen.

The DM_HLEN flag (pmodes bit 1) should be set if the display implements
highlighting for selected objects (preferably by drawing them with dashed
lines).

The DM_GROK flag (pmodes bit 2) should be set for single-screen operations
which require the driver to switch between a text screen and a graphics
screen. DM_GROK should be cleared if a separate graphics screen is used. A
driver that supports both single- and dual-screen modes must find out for
itself whether a second screen is present (i.e., check the equipment byte,
etc.) and then set DM_GROK accordingly.

A new feature has been added to AutoCAD Release 12 386 for ADI 4.2 drivers.
If both DM_GROK and DM_GROKE are turned on, AutoCAD 386 assumes that the
driver is maintaining a text window on the graphic screen. On PGOTEXT or
PGOTEXTU, AutoCAD sends PCHAR packets to the driver instead of making DOS
calls to write to the DOS text screen.

Drivers that support this new feature have some extra work to do:

  * Be sure to set DM_GROKE only if the currently configured screen
resolution and font size allow an 80x25 text screen comfortably inside the
graphic screen.

  * Be sure to set DM_GROKE only if the controlling product is AutoCAD
Release 12 or later.

  * Provide at least minimal ANSI escape sequence support (see rcpvesa2.c).

  * Pass unrecognized ANSI escape sequences to DOS to allow things like
keyboard redefinition to work.

  * Really switch back to DOS text mode on PGOTEXT after PBSHELL and back
to graphic mode on PASHELL or the next PGOGRAPH after PASHELL.

This extra work avoids the long resynchronizing time of some multisync
monitors when switching between text and graphic mode. This should be a
user-configurable option if it is implemented. Scrolling can be very slow
on high resolution screens.

If your driver supports DM_GROKE, we recommend you copy the contents of the
real DOS screen at PASHELL time into the DM_GROKE DOS window when switching
back to it. Otherwise, the last screenfull of text might be lost. This is
because AutoCAD intercepts and performs some DOS commands (like dir) when
shelled out, instead of having DOS perform the command. On these
intercepted commands, AutoCAD sends PASHELL immediately upon completion of
the command. If the command is not handled by AutoCAD, then PASHELL doesn't
get sent until after the user enters "exit." Copying the real DOS screen
text into the DOS window solves this problem. The rcpvesa2 sample driver
does this.

An alternative to copying the DOS screen into the DM_GROKE DOS window is to
remain in the real DOS screen at PASHELL until the next PGOGRAPH. This
avoids the copying, but leaves the user in the real DOS screen. Some
hardware might make it difficult to do this.

char psplit
-----------
If DM_GROK is set in the pmodes member (specifying single-screen
operation), member psplit should return the number of lines of text that
appear in the text scrolling area (normally three). Otherwise for dual-
screen operation, the driver should set psplit to zero.

char phwfill
------------
The phwfill member should be assigned the value zero for devices without
hardware fill, or 2 for devices with polygon fill (1 is not used).

short pixwid, pixhgt
--------------------
The pixwid member specifies the horizontal physical spacing between pixels
and pixhgt specifies the vertical physical spacing between pixels.

The ratio of pixwid to pixhgt is used to correct the aspect ratio so the
horizontal and vertical measurements of objects drawn on the screen are
equal. On a device with square pixels, pixwid and pixhgt should both be
assigned the value 1. For devices with different X and Y scales, pixwid and
pixhgt should be assigned a value based on the physical screen measurement
in each direction divided by the number of pixels on that axis. Only the
ratio of pixwid to pixhgt is significant, so any desired units may be used.
However, the values must be greater than 0 and less than 32767, and should
be made as accurate as possible, since changes in the second decimal place
of the ratio can result in visible changes on the screen.

See the section "Screen Size" earlier in this chapter for more information
and example calculations.

char phidlines, phidcols
------------------------
The values assigned to members phidlines and phidcols (normally 25 and 80,
respectively) specify the number of lines and characters to be used for the
hidden screen (AutoCAD only).

If your display "autowraps" when the end of a line is reached, and if you
want AutoCAD to maintain the hidden text screen, you should return
phidlines and phidcols as negative numbers. This causes AutoCAD to omit
newlines when they would cause extra blank lines on your screen.

If the driver does not require the Autodesk product to maintain a hidden
screen, both these values should be assigned the value 0.

Refer to the PGOTEXTU packet description for details. Note that AutoCAD
Release 10 (unlike earlier versions of AutoCAD) used a temporary file to
store the hidden text screen; this can slow performance. If possible,
display drivers should handle the text screen themselves.

short pymenumax
---------------
The pymenumax member returns the maximum screen menu height in pixels. This
is the maximum number of vertical pixels assigned to the screen menu area.
It is normally equal to the value assigned to piydots, can may be assigned
another value if the screen menu area has a height different from the
graphics portion of the screen.

If no status line is configured, member pymenumax must be set to piydots.
Assigning a smaller value limits the range of motion of AutoCAD's cursor.
(AutoCAD only)

short pnuxdots, pnuydots
------------------------
These return the size of the physical screen in pixels, with pnuxdots
returning the number of pixels in the X (horizontal) direction and pnuydots
returning the number of pixels in the Y (vertical) direction. Note that
these are the total physical dimensions, not the highest numbered pixel.

AutoSketch and AutoShade require that the screen size reported in pnuxdots,
pnuydots be an exact number of characters of size pnuxbpc by pnuybpc. This
requirement forces some display drivers to leave a few pixels on the screen
unused. However, failure to observe this requirement produces a
misalignment of text and vectors in the AUI user interface (pull down
menus). AutoCAD does not have this strict requirement, but it is advisable
to write display drivers that can work with all appropriate Autodesk
products.

The following code fragment from rcpvga41.c shows member pnuxdots and
pnuydots being assigned values that are exact multiples of the character
cell size:

P->pnuxbpc = CHARWID;
P->pnuybpc = CHARHGT;
P->pnuxchars = XSIZE/P->pnuxbpc;
P->pnuychars = ds_cfr.ysize/P->pnuybpc;
P->pnuxdots = P->pnuxbpc * P->pnuxchars;
P->pnuydots = P->pnuybpc * P->pnuychars;

short pnuxchars, pnuychars
--------------------------
The physical screen size in characters, with member pnuxchars returning the
number of characters in the Y (horizontal) direction and member pnuychars
returning the number of characters in the Y (vertical) direction.

short pnuxbpc, pnuybpc
----------------------
The members pnuxbpc and pnuybpc return the number of bits per character in
the X (horizontal) and Y (vertical) directions, respectively.

short ybias
-----------
This is the value from which a ULS Y coordinate must be subtracted to
convert it to an LLG coordinate. It is typically close to iydots but may be
corrected if member pnuydots is not equal to member iydots.

The following code fragment from rcpvga41.c shows the calculation and
assignment of the ybias value. Note that knowing the controlling product is
important. AutoCAD does not require Y bias correction, but AutoShade and
AutoSketch do. This assignment is done after member pnuydots and basic
aybias is calculated.

if (!(pconfig & CF_ACAD)) {
    aybias -= ds_cfr.ysize - P->pnuydots;
}
P->ybias = aybias;

int (*pfdraw)()
---------------
If your driver implements fast vector mode (FASTDRAW), indicated by setting
the EF_FDRAW flag in member pefmodes in PINIT, this member is set to the 32-
bit offset of your assembly language vector draw routine.

FASTDRAW is supported in P386 ADI somewhat differently than in DOS ADI. See
the "FAST VECTOR MODE" section in this chapter for more information.

BIGVEC drivers which set EF_FDRAW get PBATCHVEC packets instead of FASTDRAW
calls and the value in pfdraw is ignored.

char cdname[]
-------------
The cdname[] member contains the current drawing name only on windowing
operating systems (i.e., OS/2, SunView, X, etc.) and is zero on non-
windowing systems (i.e., Phar Lap). A dispatcher service (getcdname()) is
available in ADI 4.2 which will return the current drawing name. Since
release 12 no longer leaves the drawing editor and reinitializes with PINIT
on opening a new .dwg file, getcdname() is now the preferred method of
learning the current drawing name.

MAC ADI 4.1 Notes
-----------------
The PINIT packet is sent when a new graphics window is created, while a
PREINIT packet is sent when the size of the graphics window changes. Both
packet types must be implemented by Mac ADI drivers.

When a Mac ADI display driver receives a PINIT or PREINIT packet, the
pfdraw field actually contains a pointer to a special parameter block.

The ADI driver must fill in values for the following fields: pstat, pmodes,
phwfill, pefmodes, pfdraw. On a PREINIT, the driver should fill in the same
values for these fields as it did for the PINIT which created the window;
AutoCAD may not pay attention to all of these fields on a PREINIT, so set
what you want when you get a PINIT, and don't change horses in the middle
of a stream.

The rest of the fields of the pkinit structure deal with the size of
various parts of the graphics "screen". Since Mac AutoCAD's graphics
"screen" is really a window which is outside the control of the ADI driver,
AutoCAD fills in these fields before the packet is sent to the ADI driver.
The driver may look at values of these fields, but must not change them.

Fields to which Mac ADI drivers must pay attention are pixdots and piydots,
which define the size of the graphics area.



6.17.44 PKBZOOM
=================

Purpose
-------
This is an optional packet. PKBZOOM allows the driver to request a Pan/Zoom
in integer coordinates and receive certain warnings.

Limitations
-----------
PKBZOOM is a display packet and can be sent to ADI 4.2 or later DEV_DS and
DEV_RC BIGVEC drivers in display mode. BIGVEC drivers set EF_BIGVEC in
PINIT.pefmodes and in PDINFO.pefmodes.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen. It is only sent to BS drivers when the
driver has requested a PKBZOOM packet by setting a flag in PSTRING.

It doesn't make sense for a secondary application to send PKBZOOM. It is a
bad idea for secondary applications to change the view in any viewport
because the primary application does not know of the change. And, secondary
applications would be hard pressed to provide all of the support which
PKBZOOM promises to BS drivers (regen warnings, regens, etc.).

AutoCAD fills in all of the fields in this packet. The ADI driver may
modify every field except pfunc and zflags.

History
-------
PKBZOOM was added in ADI 4.2 to support Release 12 BIGVEC drivers.

Two more secret AutoCAD commands were added in Release 12: ZOOM $1 and ZOOM
$2.

Declaration
-----------
#define PKBZOOM     104

struct pkbzoom {
    short pfunc;     /* PKBZOOM */
    short zflags;    /* Flags from AutoCAD to driver */
    short dflags;    /* Flags from driver to AutoCAD */
    long  xl;        /* New viewport position in integer */
    long  yl;        /* Logical space */
    long  xh;
    long  yh;
    short vpnumber;  /* Which vp to Pan or Zoom */
};

Description
-----------
PKBZOOM handles 31-bit pans and zooms. Except for the logical space size,
this packet is handled just like PKZOOM.

This packet is sent to the driver after a request is made in the PSTRING
packet. It allows the driver to request Pan or Zoom operations in integer
coordinates and receive warnings of impending regens, etc.

Warnings are sent from AutoCAD to the driver in the zflags member as
follows:

Table 6-41. Pan/Zoom warnings sent in PKBZOOM.zflags

Mnemonic          Value                   Meaning if set

REGEN_WARNING     0x01                    This Pan/Zoom will need a Regen

UNABLE_REGEN      0x02                    AutoCAD cannot Regen now

BADVP             0x04                    Viewport number is invalid

BADCOORD          0x08                    Coordinates are invalid

ABORT             0x10                    No Pan/Zoom is now possible


If AutoCAD cannot do ANY Pan or Zoom operation at that time, the ABORT flag
is set in member zflags. You can try again later. AutoCAD ignores the
packet you send back.

The dflags member is used to send AutoCAD requests:

Table 6-42. Pan/Zoom Requests from driver to AutoCAD

Mnemonic          Value  Meaning if Set

CANCEL            0x1    Forget the Pan/Zoom

DO_REGEN          0x2    Go ahead and Regen

WAY_IN            0x4    regen, zoomed all the way in

WAY_OUT           0x8    regen, zoomed all the way out


If you want AutoCAD to do the requested Pan or Zoom even if it triggers a
Regen, set the DO_REGEN bit in dflags.

Two new dflags control bits have been added for PKZOOM and PKBZOOM in
Release 12: WAY_IN and WAY_OUT. WAY_IN forces a regen with the view fully
zoomed in, so that logical and physical pixels are the same size, leaving
the largest possible range for zooming out before forcing a regen. WAY_OUT
forces a regen while zoomed out as far as possible, leaving as much range
for zooming in as possible.

The same effect as WAY_IN and WAY_OUT can be achieved through PSTRING. Two
new display driver Zoom commands, zoom $1 and zoom $2 have been added in
Release 12. These work like zoom $0 in that they accept floating point
corners for a Zoom box. Zoom $2 forces a regen with the view zoomed fully
in, so that logical and physical pixels are the same size, leaving the
largest possible range for zooming out before forcing another regen. Zoom
$1 forces a regen while zoomed as far out as possible, leaving as much
range for zooming in as possible.

You may fill in the integer coordinates to which you want viewport vpnumber
Panned or Zoomed (within the logical space of viewport vpnumber). If you
want to Pan or Zoom outside a viewport's logical space, you'll have to use
PSTRING to send Zoom $0, $1 or $2. Member vpnumber does not have to be the
currently active viewport, but it does have to be a valid viewport.

AutoCAD uses your coordinates to compute the center of the Zoom and the
scale factor. It then checks to see if this can be done without causing a
Regen, considering the aspect ratio of the viewport.

If your Zoom request is made with Tilemode = 0 and the viewport in question
is clipped, due to being partly off-screen, the unclipped viewport is
zoomed, with the clipped result displayed. In other words, AutoCAD computes
the magnification change you are requesting and then applies that to the
unclipped viewport, displacing the center of the unclipped viewport by the
amount your request tried to displace the center of the clipped viewport.

If AutoCAD can do the requested operation, it proceeds, sending you a
PBVIEWPORT packet and either a Redraw or Regen.

If AutoCAD cannot do the requested operation without a Regen, and if you
did not already authorize a Regen with DO_REGEN, you will get a second
PKBZOOM with REGEN_WARNING set in member zflags. You may change the
coordinates, CANCEL the request (by setting CANCEL in dflags) or authorize
the Regen by setting DO_REGEN in dflags.

If AutoCAD cannot do a Regen at the time of the request, the UNABLE_REGEN
bit is set in member zflags. AutoCAD ignores any return values you send in
the packet. If you want to try again with fresh coordinates, request a new
PBKZOOM packet through PSTRING. AutoCAD doesn't allow a Regen during the
operation of another command.

If you sent illegal coordinates or an illegal viewport number, AutoCAD
returns an error flag (BADCOORD or BADVP). You can correct the problem and
return the packet for another try, or you can set CANCEL in dflags to
terminate the request.

It is possible for you to loop repeatedly, feeding AutoCAD new coordinates
for Pan/Zoom until you stop getting a REGEN_WARNING, but a limit has been
set on how many iterations are allowed (to stop a bug from hanging AutoCAD
in an infinite loop). You can only loop through 10 PKBZOOM packets. If you
want to try again after that, you are forced to make a fresh ZOOMRQ in
PSTRING.

See Also
--------
PKZOOM



6.17.45 PKILL
===============

Purpose
-------
Notifies the driver that AutoCAD is terminating and exiting to the
operating system. This is the time to free malloc'd memory and otherwise
clean up.

Limitations
-----------
PKILL is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode.

Use of this packet by secondary applications is not permitted - secondary
applications should not terminate the display driver without AutoCAD's
knowledge.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PKILL was added in ADI 4.2. It is supported by AutoCAD Release 12 and 3D
Studio v2.0.

Declaration
-----------
#define PKILL 64   /* Kill display driver process */

struct pkfonly {
    short pfunc;   /* PKILL */
};

Description
-----------
The PKILL packet indicates that the Autodesk product is either exiting to
the operating system or configuring a different display driver. This is a
truly final termination of this display driver. This packet was added in
ADI 4.2 to help drivers minimize heap fragmentation. Instead of freeing up
allocated memory at PTERM-time, ADI 4.2 drivers can wait until PKILL. PTERM
merely indicates a return to AutoCAD's main menu, while PKILL truly signals
that the controlling application is done with this driver.

Although PKILL is not sent at configuration time in Release 12 386, it is
likely that PKILL will be sent at configuration time for later versions and
on other platforms, e.g., if the user starts to configure your driver and
then changes her mind.

PKILL is also received during the execution of the AutoCAD Config and
Reinit commands (at both times the driver is unloaded and reloaded). In
both cases, a DEV_RC driver may not receive RDTERM before PKILL. For this
reason, your PKILL handler should conditionally free any resources which
are normally released on receipt of RDTERM.

P386 drivers should NOT exit to DOS on receipt of PKILL. The controlling
product takes care of actually terminating and unloading your driver. A
driver running under AutoCAD which exits to DOS on receipt of PKILL does
not give AutoCAD a chance to save the user's drawing file.

See Also
--------
PTERM



6.17.46 PKZOOM
================

Purpose
-------
This is an optional packet. PKZOOM allows the driver to request a Pan/Zoom
in integer coordinates and receive certain warnings.

Limitations
-----------
PKZOOM is a display packet and can be sent to ADI 4.1 or later DEV_DS and
DEV_RC drivers in display mode.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen. It is only sent to BS drivers when the
driver has requested a PKZOOM packet by setting a flag in PSTRING.

PKZOOM should not be sent to BIGVEC drivers - they expect PKBZOOM.

It doesn't make sense for a secondary application to send PKZOOM. It is a
bad idea for secondary applications to change the view in any viewport
because the primary application does not know of the change. And, secondary
applications would be hard pressed to provide all of the support which
PKZOOM promises to BS drivers (regen warnings, regens, etc.).

AutoCAD fills in all the members of this packet. The ADI driver may modify
every member except pfunc and zflags.

History
-------
PKZOOM was added in ADI 4.1 to support Release 11. New control flags WAY_IN
and WAY_OUT were added in ADI 4.2.

Declaration
-----------
#define PKZOOM  65  /* integer local Pan/Zoom */

struct pkzoom {
    short pfunc;    /* PKZOOM */
    short zflags;   /* Flags from AutoCAD to driver */
    short dflags;   /* Flags from driver to AutoCAD */
    short xl;       /* New viewport position (integer) */
    short yl;       /* Logical space */
    short xh;
    short yh;
    short vpnumber; /* Which vp to Pan or Zoom */
};

Description
-----------
15-bit BS drivers receive PKZOOM if they return ZOOMRQ in PSTRING. BIGVEC
drivers get PKBZOOM instead.

This packet is sent to the driver after a request is made in the PSTRING
packet. It allows the driver to request Pan or Zoom operations in integer
coordinates and receive warnings of impending regens, etc.

Warnings are sent from AutoCAD to the driver in the zflags member as
follows:

Table 6-43. Pan/Zoom warnings sent in PKZOOM.zflags

Mnemonic           Value                   Meaning if set

REGEN_WARNING      0x01                    This Pan/Zoom will need a Regen

UNABLE_REGEN       0x02                    AutoCAD cannot Regen now

BADVP              0x04                    Viewport number is invalid

BADCOORD           0x08                    Coordinates are invalid

ABORT              0x10                    No Pan/Zoom is now possible


If AutoCAD cannot do ANY Pan or Zoom operation at that time, the ABORT flag
is set in member zflags. You can try again later. AutoCAD ignores the
packet you send back.

The dflags member is used to send AutoCAD requests:

Table 6-44. Values for PKZOOM.dflags

Mnemonic        Value                Meaning if Set

CANCEL          0x1  Forget the Pan/Zoom

DO_REGEN        0x2  Go ahead and Regen

WAY_IN          0x4  Regen, zoomed all the way in

WAY_OUT         0x8  Regen, zoomed all the way out


If you want AutoCAD to do the requested Pan or Zoom even if it triggers a
Regen, set the DO_REGEN bit in dflags.

Two new dflags control bits have been added for PKZOOM and PKBZOOM in
Release 12: WAY_IN and WAY_OUT. WAY_IN forces a regen with the view fully
zoomed in, so that logical and physical pixels are the same size, leaving
the largest possible range for zooming out before forcing a regen. WAY_OUT
forces a regen while zoomed out as far as possible, leaving as much range
for zooming in as possible.

The same effect as WAY_IN and WAY_OUT can be achieved through PSTRING. Two
new display driver Zoom commands, zoom $1 and zoom $2 have been added in
Release 12. These work like zoom $0 in that they accept floating point
corners for a Zoom box. Zoom $2 forces a regen with the view zoomed fully
in, so that logical and physical pixels are the same size, leaving the
largest possible range for zooming out before forcing another regen. Zoom
$1 forces a regen while zoomed as far out as possible, leaving as much
range for zooming in as possible.

You may fill in the integer coordinates to which you want viewport member
vpnumber Panned or Zoomed (within the logical space of viewport vpnumber).
If you want to Pan or Zoom outside a viewport's logical space, you'll have
to use PSTRING to send Zoom $0, $1 or $2. vpnumber does not have to be the
currently active viewport, but it does have to be a valid viewport.

AutoCAD uses your coordinates to compute the center of the Zoom and the
scale factor. It then checks to see if this can be done without causing a
Regen, considering the aspect ratio of the viewport.

If your Zoom request is made with Tilemode = 0 and the viewport in question
is clipped, due to being partly off-screen, the unclipped viewport is
zoomed, with the clipped result displayed. In other words, AutoCAD computes
the magnification change you are requesting and then applies that to the
unclipped viewport, displacing the center of the unclipped viewport by the
amount your request tried to displace the center of the clipped viewport.

If AutoCAD can do the requested operation, it proceeds, sending you a
PVIEWPORT packet and either a Redraw or Regen.

If AutoCAD cannot do the requested operation without a Regen, and if you
did not already authorize a Regen with DO_REGEN, you will get a second
PKZOOM with REGEN_WARNING set in member zflags. You may change the
coordinates, CANCEL the request (by setting CANCEL in dflags) or authorize
the Regen by setting DO_REGEN in dflags.

If AutoCAD cannot do a Regen at the time of the request, the UNABLE_REGEN
bit is set in member zflags. AutoCAD ignores any return values you send in
the packet. If you want to try again with fresh coordinates, request a new
PKZOOM packet through PSTRING. AutoCAD doesn't allow a Regen during the
operation of another command.

If you sent illegal coordinates or an illegal viewport number, AutoCAD
returns an error flag (BADCOORD or BADVP). You can correct the problem and
return the packet for another try, or you can set CANCEL in member dflags
to terminate the request.

It is possible for you to loop repeatedly, feeding AutoCAD new coordinates
for Pan/Zoom until you stop getting a REGEN_WARNING, but a limit has been
set on how many iterations are allowed (to stop a bug from hanging AutoCAD
in an infinite loop). You can only loop through 10 PKZOOM packets. If you
want to try again after that, you will be forced to make a fresh ZOOMRQ.



6.17.47 PLANG
===============

Purpose
-------
Allows AutoCAD and a display driver to agree on the handling of the check
mark character and characters with codes greater than 128.

Limitations
-----------
PLANG is a display packet supported by ADI 4.1 and later DEV_DS and DEV_RC
drivers. It is sent only by the primary application and should not be used
by secondary applications.

PLANG should be the second packet sent to ADI 4.2 drivers at CFG time and
at XQT time, immediately following PWHO.

ADI 4.1 drivers expect to get PLANG only once, at execution time, after
PCFGREC and before PINIT.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PLANG was added in ADI 4.1 to support Release 11. The packet was expanded
in ADI 4.2 with the addition of the new members lang and code_page.

Declaration
-----------
#define PLANG  68

struct pklang {
    short pfunc;         /* PLANG for DEV_DS and DEV_RC */
    short cchar;                    /* Check mark value */
    short options;                  /* Option flag bits */
    short maxchar;        /* Highest numbered char code */
    char  lang[MAX_LAN + 1];      /* Language ID string */
    char  code_page[MAX_COP + 1];     /* Code page name */
};
#define MAX_LAN 8                  /* Defined in path.h */
#define MAX_COP 20

Description
-----------
Note that in ADI 4.2, PLANG is sent to all device types. Each type of
device (DEV_DS, DEV_PL and DEV_DG) has a different #define for the PLANG
packet code.

The ADI interface was originally designed to handle only 128 ASCII
characters, with character 128 having the special meaning of a check mark
for dialogue boxes. As overseas editions of AutoCAD have begun to use ADI
drivers, it has become necessary to extend the range of characters sent to
display drivers. Due to conflicts with some countries' character definition
conventions, these "8 bit font" versions of AutoCAD redefine the check mark
character to another value, often 255.

A new driver mode bit, DM_ASCIIBM was added to member pmodes in the PINIT
packet, to allow a driver to indicate to AutoCAD that the driver is 8-bit-
font aware. However, some versions of AutoCAD are not 8-bit-font aware,
either. For 8-bit font handling to work, it is necessary that both AutoCAD
and the ADI driver agree on supporting it.

Thus, PLANG is sent to ADI 4.1 and later display drivers before PINIT.
AutoCAD fills in the options member. If the flag FF_8BIT is set, that
version of AutoCAD is 8-bit font aware. In that case, member cchar holds
the value which is used to represent the check mark in dialogue boxes if
your driver returns DM_ASCIIBM in member pmodes in the PINIT reply packet.

Prior to release 12, AutoCAD used check marks in its internal dialogues to
indicate selected items. In AutoCAD Release 12 the check mark is used less
often because Proteus dialogues have replaced internal dialogues. Check
marks can be displayed in Release 12 pull-down menu items. If you type this
command:

(menucmd "p2.1=!.")

the first item in the second pull-down menu should become checked. In the
standard release 12 menu - this is Assist - the first item, "Help!", should
have a leading check mark.

The field maxchar holds the highest numbered character which AutoCAD
expects to send if DM_ASCIIBM is returned in PINIT.

If your driver does not return DM_ASCIIBM in pmode at PINIT time, even an 8-
bit font version of AutoCAD still sends the check mark as 128.

Table 6-45. Values for PLANG.options

Mnemonic        Value Meaning if Set

FF_8BIT         0x1   FONT8BIT is active.

FF_SYSMENU      0x2   System has a menu bar.


The FF_SYSMENU option bit is used on some windowing platforms to inform a
display driver that a system menu bar is supported.

The PLANG.lang and PLANG.code_page members were introduced in ADI 4.2. They
inform the driver of the command language and code page that AutoCAD
believes are currently in use. These are derived from the software
environment and not from polling the keyboard or other hardware. See the
tables at the end of this description section for language and code page
values.

Ctype Functions
---------------
We have added new dispatcher functions to export ctype functions that have
been correctly internationalized. See chapter 4, ADI Dispatcher, for
complete information on ctype functions.

Command String Language Over-ride
---------------------------------
A feature of AutoCAD Release 12 will help display driver authors to use
PSTRING effectively with foreign language versions of AutoCAD. Adding a
leading underscore "_" to a command string causes it to be interpreted as
US English, regardless of the language otherwise in use. Thus "_line" is
recognized as the line command. The underscore must be the first character
in the command. Transparent commands should be entered with the apostrophe
following the underscore, e.g., "_'line". If you want to make sure that
command redefinition doesn't take precedence in interpretation of a
command, the period may be used as before, e.g. "_.line". Note that you
should not define any driver-local commands beginning with a leading
underscore because AutoCAD strips the underscore in its command processing.

The following tables show the values for PLANG.lang and PLANG.code_page.
PLANG.lang values are from ISO 639, and are not all used yet.

Table 6-46. Values for PLANG.lang

Symbol       Language name      Symbol      Language name

aa           Afar        lv     Latvian, Lettish

ab           Abkhazian   mg     Malagasy

af           Afrikaans   mi     Maori

am           Amharic     mk     Macedonian

ar           Arabic      ml     Malayalam

as           Assamese    mn     Mongolian

ay           Aymara      mo     Moldavian

az           Azerbaijani        mr          Marathi

ba           Bashkir     ms     Malay

be           Byelorussian       mt          Maltese

bg           Bulgarian   my     Burmese

bh           Bihari      na     Nauru

bi           Bislama     ne     Nepali

bn           Bengali, Bangla    nl          Dutch

bo           Tibetan     no     Norwegian

br           Breton      oc     Occitan

ca           Catalan     om     (Afan) Oromo

co           Corsican    or     Oriya

cs           Czech       pa     Punjabi

cy           Welsh       pl     Polish

da           Danish      ps     Pashto, Pushto

de           German      pt     Portuguese

dz           Bhutani     qu     Quechua

el           Greek       rm     Rhaeto-Romance

en           English     rn     Kirundi

eo           Esperanto   ro     Romanian

es           Spanish     ru     Russian

et           Estonian    rw     Kinyarwanda

eu           Basque      sa     Sanskrit

fa           Persian     sd     Sindhi

fi           Finnish     sg     Sangro

Table 6-46a. Values for PLANG.lang (continued)

Symbol       Language name      Symbol      Language name

fj           Fiji        sh     Serbo-Croatian

fo           Faeroese    si     Singhalese

fr           French      sk     Slovak

fy           Frisian     sl     Slovenian

ga           Irish       sm     Samoan

gd           Scots Gaelic       sn          Shona

gl           Galician    so     Somali

gn           Guarani     sq     Albanian

gu           Gujarati    sr     Serbian

ha           Hausa       ss     Siswati

hi           Hindi       st     Sesotho

hr           Croatian    su     Sudanese

hu           Hungarian   sv     Swedish

hy           Armenian    sw     Swahili

ia           Interlingua        ta          Tamil

ie           Interlingue        te          Tegulu

ik           Inupiak     tg     Tajik

in           Indonesian  th     Thai

is           Icelandic   ti     Tigrinya

it           Italian     tk     Turkmen

iw           Hebrew      tl     Tagalog

ja           Japanese    tn     Setswana

ji           Yiddish     to     Tonga

jw           Javanese    tr     Turkish

ka           Georgian    ts     Tsonga

kk           Kazakh      tt     Tatar

kl           Greenlandic        tw          Twi

km           Cambodian   uk     Ukrainian

kn           Kannada     ur     Urdu

ko           Korean      uz     Uzbek

ks           Kashmiri    vi     Vietnamese

ku           Kurdish     vo     Volapuk

ky           Kirghiz     wo     Wolof

Table 6-46b. Values for PLANG.lang (continued)

Symbol       Language name      Symbol      Language name

la           Latin       xh     Xhosa

ln           Lingala     yo     Yoruba

lo           Laothian    zh     Chinese

lt           Lithuanian  zu     Zulu


Table 6-47. Values for PLANG.code_page

Code page         Meaning

ascii             ASCII (7-bit)

dos437            DOS 437 (United States)

dos850            DOS 850 (Multilingual)

dos852            DOS 852 (Slavic)

dos855            DOS 855 (Cyrillic)

dos857            DOS 857

dos860            DOS 860 (Portugal)

dos861            DOS 861

dos863            DOS 863 (Canada-French)

dos864            DOS 864 (Arabic)

dos865            DOS 865 (Norway)

dos869            DOS 869 (Modern Greek)

iso8859-1         ISO 8859-1 (Latin I)

iso8859-2         ISO 8859-2 (Latin II)

iso8859-3         ISO 8859-3

iso8859-4         ISO 8859-4

iso8859-5         ISO 8859-5

iso8859-6         ISO 8859-6

iso8859-7         ISO 8859-7

iso8859-8         ISO 8859-8

iso8859-9         ISO 8859-9

mac-roman         Macintosh (Roman)




6.17.48 PLINE
===============

Purpose
-------
Instructs the driver to draw a vector. Used for non-drawing vectors in the
AUI.

Limitations
-----------
PLINE is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. All ADI 4.1 and later DEV_DS and DEV_RC drivers support this
packet. Earlier DEV_DS drivers indicate support for this packet by setting
EF_NEWI in PINIT.pefmodes.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

MINLCOLOR <= pcolour <= 255. Note that pre-ADI 4.1 drivers may fail to
support color -1 (XOR).

The coordinates passed to the driver are in the natural Y coordinate system
(ULS) with (0,0) representing the upper left corner of the display. The
coordinates must be within the range from 0,0 to XDOTS,YDOTS.

A vector drawn with the PLINE request can't be highlighted or be part of a
drawing entity and therefore is never saved in a local display list. In
other words, pdrawm should always be DR_NORDRW and vpnumber should always
be 0.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

While AutoCAD uses PLINE correctly for AUI vectors, AutoShade incorrectly
sends AUI vectors through the PVEC packet instead of PLINE.

Warning: In AutoCAD for Windows Release 11, PLINE uses the same coordinate
system as PVEC. That is, PLINE uses the lower left corner of the screen as
the origin, instead of the upper left corner as it does for all other
AutoCAD platforms.

History
-------
This packet was added as part of the AUI in ADI 3.0 to support Release 9.
AUI support was optional until ADI 4.1 and Release 11. The packet was
extended in ADI 4.0 with the addition of member vpnumber (ignored for PLINE
but added for consistency with PVEC) to support multiple viewports in
Release 10.

Declaration
-----------
#define PLINE  32      /* Draw line in natural coordinates */
/*  Packet for PVEC and PLINE requests */

packed pstruct kvec {
    short pfunc;       /* PLINE */
    short pfx, pfy;    /* From point */
    short ptx, pty;    /* To point */
    short pcolour;     /* Color */
    short pdrawm;      /* Drawing modes */
    short vpnumber;
};

Description
-----------
PLINE instructs the driver to draw a vector from (pfx, pfy) to (ptx, pty)
in the color specified by member pcolour. The coordinates are in the
natural Y coordinate system (ULS) with (0,0) representing the upper left
corner of the display.

ADI 4.1 and later drivers check to see if CF_STUDIO is set. If so, they
only XOR with the low 4 bits of the color palette.

PVEC and PLINE both use the same structure definition. For compatibility
between PVEC and PLINE, the following bits are set in the pdrawm field, and
are either instructional (a directive) or informational in nature, as shown
in the following tables:

Table 6-48. Values for PVEC.pdrawm (directives)

Mnemonic        Value  Meaning

DR_HILITE       0x0001                     Highlighted

DR_NORDRW       0x0002                     Vector is not part of drawing

DR_PHYSCY       0x0004                     Obsolete unbiased coordinate
system

DR_DASHED       0x0008                     Real dashed lines


Table 6-49. Values for PVEC.pdrawm (informational)

Mnemonic         Value                        Meaning

DR_BORDER        0x0010                       Viewport border

DR_CURSOR        0x0020                       Part of cursor

DR_AXIS          0x0040                       AXIS tick mark

DR_LISP          0x0080                       Drawn by LISP app

DR_ICONS         0x0100                       Icons, vpoint and dview

DR_MARK          0x0200                       Blips, pedit mark, etc.

DR_VECA          0x0400                       Drawing aligned - drag, 3d
face, sketch, etc.

DR_SLIDE         0x0800                       Slide

DR_DHILIT        0x1000                       Dehighlighting vector

DR_ZOOMD         0x2000                       Zoom dynamic

DR_PLPRE         0x4000                       Plot preview


DR_HILITE
---------
If this bit is set, the vector should be highlighted. If both XOR and
highlighting are requested, XOR only the foreground segments of the vector,
making the highlighting reversible.

DR_NORDRW
---------
If this bit is set, the vector is not part of a drawing entity. DR_NORDRW
is always set in PLINE.

DR_DASHED
---------
When PVEC or PLINE see this option flag (which is never seen together with
DR_HILITE), a highlighted vector should be drawn with gaps between the
visible segments. This is in contrast to DR_HILITE which erases to screen
background between visible segments. Support for this attribute is required
for all ADI 4.2 DEV_RC drivers.

See Also
--------
PVEC



6.17.49 PLOPEN
================

Purpose
-------
Notifies a BS driver of the position of its integer logical space's corners
in AutoCAD's floating-point space. This packet is eventually followed by a
fresh vector list.

Limitations
-----------
This is a display packet sent only to DEV_DS and DEV_RC BS drivers (those
which set EF_BS in pefmodes at PINIT time).

It can be sent only to a primary application - secondary applications can't
change the view associated with a viewport without confusing the primary
application.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen. It can only be sent to a viewport which
has already been opened with POPENVP or POPENBVP.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PLOPEN was added in ADI 4.0 to support multiple viewports in Release 10.
The projid member was forced to unique values for every viewport in ADI
4.1, when support for slave viewports was dropped from Release 11 AutoCAD.
The newpid member was added in ADI 4.2.

Declaration
-----------
#define PLOPEN  44

struct pklopen {
    short pfunc;       /* PLOPEN */
    short vpnumber;    /* which viewport? */
    short projid;      /* projection id # */
    short zoomable;    /* TRUE if zoomable */
    double rxl, ryl;   /* lower left corner */
    double rxh, ryh;   /* upper right corner */
    short newpid;      /* new projection id */
};

Description
-----------
This packet is sent whenever an action (such as a REGEN) is performed which
could move a viewport's logical space or change its projection id.

Because the master/slave viewport feature of Release 10 ADI 4.0 has been
removed, the projid member is always a unique value to keep ADI 4.0 drivers
fooled.

The new member newpid is a non-sequentially assigned projection ID.
Viewports which share the same projection will have the same value for
newpid. This is NOT intended for master-slave viewport implementation. The
code for master-slave viewports is completely disabled. The newpid
information is provided for bird's-eye control.

PLOPEN provides real coordinates for the corners of the viewport's logical
space in floating-point space. This is useful for composing Zoom $0
commands to implement local Pans and Zooms which require Regens. Note that
the data supplied in PLOPEN refers to the corners of the entire logical
space, not just the portion visible on the screen.

Fields rxl, ryl, rxh, and ryh are in floating-point space coordinates.

The zoomable member is FALSE if Pans and Zooms are not allowed in the
specified viewport, and TRUE if Pans and Zooms are possible. A perspective
view is one example of a non-zoomable viewport.

Your driver may use this information in deciding if it wants to handle the
viewport as BS or NO_BS.

In PSPACE, although viewports are not zoomable with BS packets, there is a
performance gain from display list REDRAW which may still make BS handling
worthwhile, if you have enough display list memory available.



6.17.50 PMARK
===============

Purpose
-------
Instructs the driver to draw a cursor.

Limitations
-----------
PMARK is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. All DEV_DS and DEV_RC drivers support this packet.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

BIGVEC drivers expect PBMARK and not PMARK.

If the ADI driver is BS or FAKE_BS, vpnumber may be non-zero (but must be a
valid, currently open viewport) and the driver can be expected to clip the
cursor to the specified viewport.

ADI drivers only know how to draw a simple orthogonal cursor (cursel types
0 and 3). But drivers expect to be notified of all cursors, including those
they can't draw.

For all values of member pcursel other than 0 or 3, the driver simply
returns with member pstat set to zero. This tells you to do the work.

If the driver draws the cursor, it returns a value of 1 in pstat.
Otherwise, it returns with pstat set to zero, instructing you to draw the
cursor yourself.

The coordinates supplied in members px and py are pixel coordinates for all
non_BS drivers, and for NO_BS viewports for BS drivers, and must be for a
point inside the specified viewport (remember that viewport 0 is the entire
graphic area of the screen). A cursor of the specified type must exist at
the specified location so that the driver can erase it. Most ADI drivers
use the same XOR cursor routine to draw and erase types 0 and 3 cursors.
All cursor types except 10 and 11 have LLG as the origin when pixel
coordinates are used. Types 10 and 11 use ULS coordinates.

The member logical must be set to FALSE if the cursor coordinates are pixel
and to TRUE if they are logical.

ADI drivers expect to get a PMARK packet just before each PDCURS packet.
The driver will fail the PMARK request. Some drivers use the PMARK packet
(which contains coordinates) to manage value-added driver features.

If you are controlling a display driver through a TEE driver, remember that
you must leave the cursor in the state AutoCAD expects it to be in. At a
minimum, on letting AutoCAD resume control, you must leave a cursor on
screen if AutoCAD had one on screen before you intervened, and you must not
have a cursor on screen if AutoCAD didn't.

If you are an ADS application, AutoCAD always removes any cursors from the
screen before giving control of the screen to you. You are required to
remove any cursors you put on the screen before you return control to
AutoCAD or before you switch modes (e.g., GOTEXT or RDSTART).

AutoCAD fills in all the members of this packet. The ADI driver may modify
member pstat.

History
-------
PMARK was introduced in ADI 3.0 with packet mode ADI. It was extended by
adding member vpnumber in ADI 4.0 to support multiple viewports in Release
10. It was extended by adding member logical in ADI 4.2. The related BIGVEC
packet PBMARK was also added in ADI 4.2.

Declaration
-----------
#define PMARK 7

struct pkmark {
    short func;    /* PMARK */
    short stat;
    short px, py;
    short pcursel;
    short vpnumber;
    short logical;
};

Description
-----------
PMARK instructs the driver to draw a cursor of type pcursel at screen
coordinates (px,py).

For all values of pcursel other than 0 or 3, the driver should simply
return a value of 0 in pstat, and the Autodesk product draws the cursor
itself.

Member pcursel values of 0 and 3 specify simple orthogonal crosshairs, and
the display driver may choose to draw these with optimized code. Autodesk
products normally draw a full- screen crosshair, but the driver can draw it
smaller (or allow the size to be configured by the user) if desired.

If member logical is false, the coordinates passed in px and py are
viewport-independent pixel coordinates. If member logical is true, the
coordinates are 15-bit logical viewport relative. In either case, it is the
driver's responsibility to clip the cursor to the specified viewport.

In ADI 4.2, PMARK uses 15-bit logical coordinates for viewport-relative
cursors for ADI 4.2 BS drivers, if AutoCAD is using logical coordinates for
drawing in the viewport. It uses pixel coordinates for all viewport-
independent cursors, all pre-ADI 4.2 drivers, viewports where logical
coordinates are not active (e.g., in paperspace) and all non-BS ADI 4.2
drivers. A new member, logical, has been appended to pkmark for ADI 4.2.
This is FALSE if the coordinates are pixel and TRUE if they are logical.
All cursor types except 10 and 11 have LLG as the origin when pixel
coordinates are used. Types 10 and 11 use ULS coordinates.

If the driver draws the cursor, it should return a value of 1 in member
pstat. Otherwise, it should return with pstat set to zero, instructing the
Autodesk product to draw the cursor.

ADI 4.1 and later drivers check to see if CF_STUDIO is set. If so, they
only XOR with the low 4 bits of the color palette.

See Also
--------
PBMARK, PCBMARK, PCMARK, PDCURS, PCCURS



6.17.51 PMAXVP
================

Purpose
-------
Allows a BS driver to set the maximum number of active viewports.

Limitations
-----------
PMAXVP is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. All ADI 4.1 and later DEV_DS and DEV_RC drivers support this
packet.

There is no reason for a secondary application to send this packet to an
ADI driver.

AutoCAD fills in all the members of this packet. The ADI driver modifies
member maxactvp.

History
-------
PMAXVP was added in ADI 4.1 to support Release 11. Release 12 sets an
absolute limit of 64 for maxactvp.

Declaration
-----------
#define PMAXVP  67

struct pkmaxvp {
    short pfunc;        /* PMAXVP */
    short maxactvp;     /* Max # of vp driver can handle */
};

Description
-----------
AutoCAD does not activate more viewports than the number you return in the
maxactvp member. If the user creates more than maxactvp viewports, the
excess viewports appear only as outlines.

AutoCAD is currently the only product using PMAXVP. Release 12 sets a limit
of 64 for maxactvp, if a driver requests a larger value, it will be reduced
to 64.



6.17.52 PMNUCURS
==================

Purpose
-------
Set the current text cursor to a screen menu box.

Limitations
-----------
PMNUCURS is a display packet and can be sent to DEV_DS and DEV_RC drivers
in display mode. All DEV_DS and DEV_RC drivers support this packet.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen. It can be sent only to drivers which have
been told to maintain a screen menu; the primary application does this by
setting CF_MENU in PINIT.pconfig. Secondary applications can determine if
this is enabled by examining PDINFO.pconfig (this is read-only).

0 <= pnboxes < PINIT.pmaxboxes

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PMNUCURS was introduced in ADI 3.0 with the packet mode interface.

Declaration
-----------
#define PMNUCURS  13

struct pkmnucur {
    short   pfunc;    /* PMNUCURS */
    short   pboxno;
    short   pnboxes;
};

Description
-----------
PMNUCURS instructs the driver to set the current text cursor to screen menu
box pboxno (0 is the top box).

There are pnboxes on the screen.

This request may be followed by a sequence of PCHAR requests to write into
the box, or by a PHLITE or PDHLITE request packet to highlight or
dehighlight the box.

AutoCAD is currently the only product using PMNUCURS.



6.17.53 PMENUFCN
==================

Purpose
-------
Constructs a screen menu.

Limitations
-----------
PMENUFCN is a display packet used only on with windowing operating systems.
It may be sent to DEV_DS and DEV_RC drivers in display mode. DEV_DS and
DEV_RC drivers on some windowing platforms (UNIX and OS/2, but not Windows
or Mac) support this packet.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PMENUFCN was introduced in OS/2 ADI 4.0. It has also been used for UNIX and
Windows display drivers, starting with ADI 4.1. The structure changed in
ADI 4.1 with the addition of the pmnum member.

Declaration
-----------
#define PMENUFCN  52

packed struct pkmenufcn {  /* build menu */
    short pfunc;           /* PMENUFCN */
    short pmfunc;          /* menu function request */
    short pmnum;           /* menu number */
    char  pmitem[1];
};

Description
-----------
This packet is sent to OS/2 ADI 4.0 and UNIX ADI 4.1 and later display
drivers. Windows ADI display drivers won't see this packet--it is
intercepted by winacad.dll which takes care of pull down menus.

A number of menu function requests may be passed through this packet, to
tell the display driver to construct a menu system.

Table 6-50. Values for PMENUFCN.pmfunc

Mnemonic       Value                  Meaning

MNUINIT        1     Initialize for loading menu set

MNUBGN         2     Start next menu

MNUITM         3     Add one item to menu

MNUEND         4     End of current menu

MNUDONE        5     Entire set is complete

MNUFILE        6     Send the current menu filename


This packet manages the pull down menus which are created by the *POP1
through *POP10 items in the AutoCAD menu file.

MNUINIT disables display of the menu and erases any stored menu bar items.

MNUBGN starts a column of items at the top.

MNUITM adds an item below the column started by MMUBGN.

MMUEND indicates the end of a column -- no item is passed with this packet.

MMUDONE signals that a complete menu bar has been sent, and the menu
drawing is reenabled.

Typically, one MNUINIT is sent, then one MNUBGN for each *POPn column,
followed by one MNUITM for each item in *POPn and a MNUEND for the end of
column. The MNUBGN, MNUITM, MNUEND sequence would be repeated until all of
the *POPn columns were sent. Then a final MMUDONE is sent.

MNUFILE indicates that the packet contains the file name of the loaded
menu. Winacad.dll uses the menu file name to find the associated bitmap
resource DLL, which in turn is used to display bitmaps in the menu.

AutoCAD is currently the only product using PMENUFCN.



6.17.54 PMENUGET
==================

Purpose
-------
Gets the attributes of a screen menu item.

Limitations
-----------
PMENUGET is a display packet used ADI 4.2 platforms with windowing
operating systems. It may be sent to DEV_DS and DEV_RC drivers in display
mode.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

AutoCAD fills in members pfunc, pmnum and pinum of this packet. The ADI
driver replies by filling in pmbits and pmark_char.

History
-------
PMENUGET was introduced in SPARC ADI 4.2.

Declaration
-----------
#define PMENUGET  112

packed struct pkmenuattr {    /* Get menu item attributes */
    short pfunc;                              /* PMENUGET */
    short pmnum;                           /* Menu number */
    short pinum;                           /* Item number */
    short pmbits;                       /* Item flag bits */
    char  pmark_char;   /* Mark char (if "mark" flag set) */
};

Description
-----------
This packet is sent to ADI 4.2 display drivers on windowing systems.

AutoCAD fills in the "pop" menu number for a pull down menu in member pmnum
and the menu item number in member pinum. pmnum is zero-based and pinum is
one-based. The pop menu on the left is zero and the item at the top of the
menu is one.

The driver returns the attributes of this menu item in pmbits and, if
MUN_MARK is set, the check mark character in pmark_char .

Table 6-51. Values for PMENUGET.pmbits

Mnemonic        Value              Meaning

MNU_GREY        0x01  Item is grayed out

MNU_MARK        0x02  Item is marked


AutoCAD is currently the only product using PMENUGET.



6.17.55 PMENUSET
==================

Purpose
-------
Sets the attributes of a screen menu item.

Limitations
-----------
PMENUSET is a display packet used ADI 4.2 platforms with windowing
operating systems. It may be sent to DEV_DS and DEV_RC drivers in display
mode.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PMENUSET was introduced in SPARC ADI 4.2.

Declaration
-----------
#define PMENUSET 111

packed struct pkmenuattr {  /* Set menu item attributes */
    short pfunc;                            /* PMENUSET */
    short pmnum;                         /* Menu number */
    short pinum;                         /* Item number */
    short pmbits;                     /* Item flag bits */
    char  pmark_char; /* Mark char (if "mark" flag set) */
};

Description
-----------
This packet is sent to ADI 4.2 display drivers.

AutoCAD fills in the "pop" menu number for a pull down menu in member pmnum
and the menu item number in member pinum. Pmnum is a zero-based value,
pinum is one-based. The pop menu on the left is zero and the item at the
top of the menu is one. AutoCAD fills in pmbits with the action(s) to be
taken. If the MNU_MARK flag bit is set, pmark_char contains a string
containing the check-mark character. Otherwise pmark_char is an empty
string. The ADI driver modifies the menu item accordingly.

Table 6-52. Values for PMENUSET.pmbits

Mnemonic       Value              Meaning

MNU_GREY       0x01  Item to be grayed out

MNU_MARK       0x02  Item to be marked


AutoCAD is currently the only product using PMENUSET.



6.17.56 PMENUSHOW
===================

Purpose
-------
Displays a screen menu.

Limitations
-----------
PMENUSHOW is a display packet used only on platforms with windowing
operating systems. It may be sent to DEV_DS and DEV_RC drivers in display
mode. All DEV_DS and DEV_RC drivers on windowing platforms (UNIX, OS/2 and
Windows, but not Mac) support this packet.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PMENUSHOW was introduced in OS/2 ADI 4.0. It has also been used in ADI 4.1
and later for UNIX and Windows display drivers.

Declaration
-----------
#define PMENUSHOW 53 /* Show a particular popup */

struct pkmenushow {  /* show popup */
    short pfunc;
    short pmenu;     /* pop number */
};

Description
-----------
AutoCAD Release 11 for Windows handles this packet in winacad.dll so that
the ADI driver, dsacad.dll, never sees it.

This is the command to pull down a menu which was constructed with PMENUFCN
packets.



6.17.57 PMODELINE
===================

Purpose
-------
Instructs driver to write a string to the mode line.

Limitations
-----------
PMODELINE is a display packet and can be sent to DEV_DS and DEV_RC drivers
in display mode. All DEV_DS and DEV_RC drivers support this packet.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen. It can be sent only to drivers which have
been told to maintain a status line - the primary application does this by
setting CF_STATUS in PINIT.pconfig.

Secondary applications can determine if this is enabled by examining
PDINFO.pconfig (this is read-only).

The string sent in this packet should be of a length less than or equal to
the value the driver reported in PINIT.modelinel.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PMODELINE was introduced in ADI 3.0 with the packet interface. At that
time, it did not pass the string ptext. In ADI 4.0 for XENIX, OS/2 and
P386, the packet was expanded to include ptext. In ADI 4.1, all platforms
supported the pass-data form of PMODELINE.

Declaration
-----------
#define PMODELINE 21

struct pkmodeline {
    short pfunc;        /* PMODELINE */
    short pnchars;      /* Number of chars in line */
    short pcolour;      /* Current color */
    char ptext[1];      /* mode string */
};

Description
-----------
PMODELINE instructs the driver to set the current text position to the
start of the status (mode) line and to display the null-terminated string
sent in member ptext[].

The string to be displayed is null-terminated and will not be followed by
PCHAR or PECHAR packets.

The current drawing color (the color in which new entities appear, however
derived) is passed to the driver in member pcolour so the driver can, if it
chooses, represent this on the status line.

PMODELINE is the driver's only notification of the need to write a string
to the mode line.

AutoCAD is currently the only product using PMODELINE.



6.17.58 PMODEMSG
==================

Purpose
-------
Instructs the driver to write a string to the title bar for the AutoCAD
graphic window.

Limitations
-----------
PMODEMSG is a display packet and can be sent to DEV_DS and DEV_RC drivers
on UNIX windowing systems in display mode. All DEV_DS and DEV_RC drivers
support this packet.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PMODEMSG was introduced in UNIX display ADI 4.1.

Declaration
-----------
#define PMODEMSG 70

struct pkmodemsg {
    short pfunc;        /* PMODEMSG */
    char pmessage[1];   /* message to show */
};

Description
-----------
PMODEMSG instructs the driver to write a string to the title bar of the
AutoCAD graphic window. Typically this string is either the current drawing
name or a tablet/mole mode message.

PMODEMSG is the driver's only notification of the need to write a string to
the title bar.

AutoCAD is currently the only product using PMODEMSG.



6.17.59 PMSGBOX
=================

Purpose
-------
Tells the display driver to put up a simple dialogue or alert box.

Limitations
-----------
PMSGBOX is a display packet used only on platforms with windowing operating
systems. It may be sent to DEV_DS and DEV_RC drivers in display mode. Pre-
ADI 4.2 DEV_DS and DEV_RC drivers on some windowing platforms (UNIX and
OS/2, but not Windows or Mac) support this packet.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

AutoCAD fills in all the members of this packet. The ADI driver returns a
response in pstat.

History
-------
PMSGBOX was introduced in OS/2 ADI 4.0. It has also been used in ADI 4.1
for UNIX display drivers.

Declaration
-----------
#define PMSGBOX   51   /* Put up message box */

struct pkmsgbox {      /* put up message box */
    short pfunc;
    short pstat;       /* response */
    short pyorn;       /* box yes/no buttons? */
    char pmessage[1];  /* the message starts here */
};

Description
-----------
Windows ADI 4.1 drivers don't see this packet - it is intercepted
winacad.dll, which takes care of displaying the alert or message box.

This packet is used to put up a message or alert box displaying a message
(which may be several lines in length) passed as a null-terminated string
in char pmessage[]. The flag pyorn determines if we put up an alert box
(which the user can only acknowledge) or a message box which can accept a
response (returned in pstat) from the user. If pyorn is true, put up a
message box, otherwise display an alert.

The pstat member should be returned as TRUE when an alert has been
acknowledged or a message box has been answered yes and as FALSE otherwise.



6.17.60 PNEWCFG
=================

Purpose
-------
Creates a new configuration record at configuration time.

Limitations
-----------
PNEWCFG is a display packet which can be emitted only by the primary
controlling product. The same product must handle all of the other display
configuration packets: PCFGREC, PCHGCFG, and PSHOWCFG, including providing
support for them by creating a configuration file.

This is a configuration-time packet.

AutoCAD fills in pfunc. The ADI driver fills in preclen and pcfgrec.

History
-------
PNEWCFG was added in ADI 4.0 for some platforms (XENIX, P386 and OS/2) and
in ADI 4.1 for the rest (DOS and UNIX).

Declaration
-----------
/* PNEWCFG, PCHGCFG and PSHOWCFG all use this struct */
#define PNEWCFG  60      /* new configuration record */

struct pkconfig {        /* config portion of adi driver */
    short pfunc;         /* PNEWCFG */
    short preclen;       /* configuration record length */
    char  pcfgrec[1];
};

Description
-----------
PNEWCFG, PCHGCFG and PSHOWCFG all share a single packet structure. They are
all used at configuration-time.

If your driver is being called for first-time configuration, PNEWCFG is
sent. If your driver has already been configured, PCHGCFG is sent. Note
that AutoCAD doesn't pay any attention to the contents of the configuration
record you ask it to store and retrieve.

You should return any private configuration record you want to save (via
member pcfgrec[]) and the exact length of the record in bytes in member
preclen.

Your driver is responsible for asking any questions of the user, collecting
and validating answers, and constructing the configuration record.

You are limited to less than 490 bytes for the configuration record to be
stored here. If you need a larger configuration record, you might use these
tools to store the filename of a separate file to which your driver will
have to write and read.

Typically your configuration record is a structure. You should use the
dispatcher services described earlier to conduct your dialogue with the
user.

A bug in Autodesk 3D Studio V1.0 limits the size of PCFGREC for 3D Studio
to the range from 1 - 100 bytes and a second bug causes Autodesk 3D Studio
to crash if you fail to supply a value for PRECLEN from 1 - 100 because the
default value supplied by Autodesk 3D Studio is invalid.

See Also
--------
PCFGREC, PCHGCFG, PSHOWCFG



6.17.61 PNOP
==============

Purpose
-------
Used as a place holder in the common memory buffer.

Limitations
-----------
PNOP is a display packet used only on platforms with windowing operating
systems which use a common memory buffer for their transport layer (e.g.
OS/2 and Windows). All DEV_DS and DEV_RC drivers on such windowing
platforms support this packet.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PNOP was introduced in OS/2 ADI 4.0. It has also been used in ADI 4.1 for
Windows display drivers.

Declaration
-----------
#define PNOP  48

struct pknop {
    short pfunc;  /* PNOP */
};

Description
-----------
AutoCAD Release 11 for Windows uses a common memory buffer internally, but
since ADI 4.1 Windows display drivers don't see this part of AutoCAD's
transport layer and do not see this packet, it is handled by winacad.dll.

The common memory buffer space not filled with display packets is filled
with PNOP packets as padding.

AutoCAD is currently the only product using PNOP.



6.17.62 PNOTIFY
=================

Purpose
-------
Notifies the ADI driver of events which the windowing system may not let it
know about.

Limitations
-----------
PNOTIFY is a display packet used only on platforms with windowing operating
systems. All DEV_DS and DEV_RC drivers on such windowing platforms support
this packet.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PNOTIFY was introduced in OS/2 ADI 4.0.

Declaration
-----------
#define PNOTIFY 58

packed struct pknotify { /* Notification packet */
    short pfunc;         /* PNOTIFY */
    short pfunc;        /* Notification function */
    short pxl;           /* Coordinates of dialogue box */
    short pyl;
    short pxh;
    short pyh;
};

Description
-----------
The following table shows the event types passed in PNOTIFY.pnfunc (see
notify.h):

Table 6-53. Values of PNOTIFY.pnfunc

Mnemonic        Value                      Meaning     Platform

MMNUSEL         1     Impending menu selection request      OS/2

MMNUSELX        2     Cancel the latter    OS/2

MDIALOGUP       3     AutoCAD dialogue going up  OS/2

MDIALOGDN       4     AutoCAD dialogue going away      OS/2

MSELSTART       5     Select command begun       OS/2

MSELEND         6     Select command finished    OS/2

MSYSPRN         7     OS/2 Control Panel printer  OS/2

MNSYSPRN        8     No OS/2 Control Panel printer    OS/2

MSAVEGFX        9     Save graphics screen       Mac

MRSTRGFX        10    Restore graphics screen    Mac

MBACKGRND       11    Becoming background task   Mac

MFOREGRND       12    Becoming foreground task   Mac

MSMCRSR         13    Use small cursor     Mac

MLGCRSR         14    Use large cursor     Mac

MQDSTART        15    Must use QuickDraw for drawing   Mac

MQDEND          16    May stop using QuickDraw   Mac

MCRSTART        17    Start cursor drawing       Mac

MCREND          18    End cursor drawing   Mac

MQUIESCNT       19    Ready to accept spooled command

MCFGINIT        21    Configuration begun

MCFGEND         22    Configuration finished

MCHKSCRN        23    Update state of off screen map   Mac


OS/2 ADI 4.0 Usage
------------------
This packet is sent to notify pmacad of several classes of events: the
appearance or disappearance of a dialogue box, enabling or disabling of
clipboard copying, enabling or disabling of the system printer.

MMNUSEL is received when we are at the AutoCAD main menu. We turn off the
waitcursor (hourglass), turn on the arrow cursor and enable the graphic
screen main menu window.

MMNUSELX is received after an item has been selected from the AutoCAD main
menu. The graphic screen main menu window is turned off.

MDIALOGUP is received before a dialogue box is sent. We create a window of
the proper size, in the location specified by pknotify, force it on top of
the graphic screen and give it the focus. The mouse is released if it was
captured, and it is marked as "out". Opendlgbox() handles much of this
housekeeping. Shortly afterward, a PBOXPUSH is likely, followed by packets
to create and display the dialogue box. Since curwin is set to the dialogue
box, packets like PLINE and PTEXT go to the dialogue box to help create it.

MDIALOGDN signals the death of a dialogue box. We will have already
received a PBOXPOP for this window. Now we can destroy the presentation
space, device context and window structure associated with it.

MSELSTART tells us that the user is about to start picking vectors for
transfer to the clipboard. Then, until we receive a MSELEND packet, we copy
all vectors which are highlighted ` to the clipboard.

Receipt of MSYSPRN is a signal to enable the system printer menu item,
whereas MNSYSPRN is a signal to disable it. This depends on what kind of
printer driver the user has selected.

Only the values 1-8 for pfunc were used in OS/2 ADI 4.0.

Windows ADI 4.1 Usage
---------------------
PNOTIFY is handled by the private DLL, acadwin.dll. ADI drivers for Windows
Release 11 do not see this packet.

Mac ADI 4.1 Usage
-----------------
This packet is sent to notify the Mac ADI driver of several different types
of events, marked "mac" in the table above. Other types of events are
described in notify.h, but they are not pertinent to Mac ADI; if you
receive anything other than the events marked "mac" above, you should
ignore them (and notify an appropriate person at Autodesk). The fields pxl,
pyl, pxh, and pyh are generally not used on the Mac, except that pxl is
sometimes used to return a status value.

MSAVEGFX is sent when something is about to occur which may damage the
graphics window, such as a Mac-native dialogue box going up, AutoCAD
becoming a background task, etc. The driver should do whatever is
appropriate to allow the graphics window to be restored when an MRSTRGFX
packet is sent later.

Caution: A driver should not assume that because the graphics window is not
damaged immediately after an MSAVEGFX, it will not be damaged later. For
example, AutoCAD can become a background task and not have the graphics
window obscured, but if the user later moves a window in a foreground
application so as to obscure AutoCAD's graphics window, the Mac OS does NOT
notify AutoCAD, and we therefore do not notify the driver.

MRSTRGFX is sent when the graphics window receives an update event; the
driver should restore the graphics window appropriately. If your driver
cares about such things, this would be a good time to see whether or not
the graphics window is obscured. If the driver restored the window, it
should place a one (1) in the packet's pxl field. If the driver did not
restore the window, it should place a zero in the pxl field, and AutoCAD
will redraw the window.

MBACKGRND and MFOREGRND are sent when AutoCAD is switched between being a
background task and the foreground task under the MultiFinder cooperative
multitasking environment. If the driver keeps track of the
foreground/background state, it should assume that whenever it gets a PINIT
or PREINIT, AutoCAD is the foreground task. Also, on an MBACKGRND, the
driver should probably do the same things it would do for an MSAVEGFX.

MSMCRSR and MLGCRSR notify the ADI driver to toggle between a "large" (full-
screen) and "small" (16 x 16 pixel) cursor.

MQDSTART and MQDEND bracket the beginning and end of a period during which
all vector drawing commands must be done with plain, vanilla QuickDraw
MoveTo/LineTo or Move/Line commands to the graphics window; no direct
setting of pixels in the frame buffer, no drawing to or blitting from off-
screen buffers, etc. This is done so that AutoCAD can record the QuickDraw
calls into a PICT for use with the clipboard or the "Print Screen" menu
item.



6.17.63 POPENBVP
==================

Purpose
-------
This optional packet opens a BIGVEC (31 bit) viewport.

Limitations
-----------
POPENBVP is a display packet and can be sent to DEV_DS and DEV_RC BIGVEC
drivers in display mode. Only BS BIGVEC DEV_DS and DEV_RC drivers support
this packet.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

Only the primary application (normally AutoCAD) may send this packet. If a
secondary application opens a viewport by sending this packet, AutoCAD and
the ADI driver will be out of synchronization - AutoCAD will think the
viewport is closed while the driver has already opened it.

A viewport should never be opened twice without an intervening PCLOSEVP.

AutoCAD fills in all the members of this packet. The ADI driver can modify
members gxdots and gydots.

History
-------
POPENBVP was introduced in ADI 4.2 to support BIGVEC multiple viewports in
Release 12.

Declaration
-----------
#define POPENBVP 102  /* Open a big viewport */

packed struct pkobvp {
    short pfunc;      /* POPENBVP */
    short vpnumber;   /* ID # for the new viewport */
    short vpxmin;     /* Corners of the viewport in LLG */
    short vpymin;     /* (ixdots, iydots) pixel coords */
    short vpxmax;
    short vpymax;
    long  gxdots;     /* You return the upper right corner */
    long  gydots;     /* of your logical space here */
};

Description
-----------
POPENBVP is sent to BIGVEC drivers to open a 31-bit logical viewport.
Except for the size of the logical space, this packet is processed just as
POPENVP is.

The members vpxmin, vpymin, vpxmax, and vpymax are the corners of the
viewport, expressed in LLG (ixdots,iydots) pixel coordinates. Members
gxdots and gydots are in pixel units, expressing a size, not a position.

The largest possible value for either gxdots or gydots is 0x7ffffffd.

The initial value passed to the driver in gxdots and gydots is the largest
possible logical space for this viewport. It is rarely advisable or
necessary for drivers to modify the default values passed here.

Although it is an error for an application to open an already open
viewport, a prudent driver will watch for an attempt to do this and handle
it reasonably.



6.17.64 POPENVP
=================

Purpose
-------
This optional packet opens a 15-bit viewport.

Limitations
-----------
POPENVP is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. Only BS or FAKE_BS DEV_DS and DEV_RC drivers support this
packet.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

Only the primary application (normally AutoCAD) may send this packet. If a
secondary application opens a viewport by sending this packet, AutoCAD and
the ADI driver will be out of synchronization - AutoCAD will think the
viewport is closed while the driver has already opened it.

A viewport should never be opened twice without an intervening PCLOSEVP.

AutoCAD fills in all the members of this packet. The ADI driver can modify
members gxdots and gydots.

History
-------
POPENVP was introduced in ADI 4.0 to support multiple viewports in Release
10. It is replaced by POPENBVP for ADI 4.2 BIGVEC drivers.

Declaration
-----------
#define POPENVP  38

packed struct pkovp {
    short pfunc;     /* POPENVP */
    short vpnumber;  /* the id # for the new viewport */
    short vpxmin;    /* corners of the viewport in LLG */
    short vpymin;    /* (ixdots, iydots) pixel coords */
    short vpxmax;
    short vpymax;
    short gxdots;    /* you return the number of pixels */
    short gydots;    /* in your logical space here */
};

Description
-----------
POPENVP is sent to 15-bit BS drivers (those which do not set PINIT.pefmodes
EF_BIGVEC). The members vpxmin, vpymin, vpxmax, and vpymax are the corners
of the viewport, expressed in LLG (ixdots,iydots) pixel coordinates.
Members gxdots and gydots are in pixel units, expressing a size, not a
position.

The largest possible value for either gxdots or gydots is 0x7ffe (or
32766). The value 0x7fff (or 32767) is reserved for use as a flag. Since
gxdots and gydots are pixel counts, note that the largest actual coordinate
values passed to the driver are gxdots - 1 and gydots - 1 (since
coordinates are zero-based and pixel counts are one-based).

The initial value passed to the driver in gxdots and gydots is the largest
possible logical space for this viewport.

AutoCAD Release 10 filled in default values for gxdots and gydots which
were adjusted for the aspect ratio of the viewport. AutoCAD Release 11 does
not make this adjustment; it sends the maximum possible size for your
logical space, regardless of aspect ratio. Most drivers will be able to use
these default values, unchanged.

Although it is an error for an application to open an already open
viewport, a prudent driver will watch for an attempt to do this and handle
it reasonably.



6.17.65 PPAL
==============

Purpose
-------
Saves or restores a palette.

Limitations
-----------
PPAL is a display packet and can be sent to DEV_RC drivers in display mode.
All DEV_RC ADI 4.2 drivers support this packet.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

Applications which use PAL_SAVE to save palettes must use matching
PAL_FORGET packets to release the saved palettes before terminating.

AutoCAD fills in pfunc, action and sometimes handle. The ADI driver fills
in status and sometimes handle.

History
-------
PPAL was introduced in ADI 4.2 for Release 12.

Declaration
-----------
#define PPAL 77      /* Palette save & restore commands */

struct pkpal {
    short pfunc;     /* PPAL */
    short action;
    long handle;
    short status;    /* GOOD if successful */
};

Description
-----------
PPAL is used for DEV_RC drivers to save and restore palettes in a manner
analogous to how PBIGBLIT saves and restores screen regions.

This packet is a request for the driver to either save or restore its
palette. If the driver is asked to save a palette, the driver is expected
to return a handle (typically the address of the buffer where the palette
was saved) to uniquely identify that save operation and a status of GOOD if
the save was successful. Multiple save and restore requests may be made in
any order.

Table 6-53a. Values for PPAL.action

Mnemonic            Value Meaning

PAL_FORGET          0     Forget palette saved with handle

PAL_SAVE            1     Save current palette and return handle

PAL_RESTORE         2     Restore palette saved with handle

PAL_ACAD_DEFAULT    3     Restore standard ACAD default palette


The PAL_SAVE operation saves the current palette and returns a handle. The
PAL_RESTORE operation restores the palette saved with handle (the
application passes the handle back to the driver). The PAL_FORGET operation
tells the driver to forget the palette associated with a handle. The
PAL_ACAD_DEFAULT operation restores the standard AutoCAD default palette
and returns the unique handle 0.

The following table shows the values filled in by the driver in member
status:

Table 6-54. Values for PPAL.status

Mnemonic      Value           Meaning

GOOD          0    Success

BAD           -1   Operation failed




6.17.66 PQPLOT
================

Purpose
-------
This is an optional packet. PQPLOT instructs the driver to perform a screen
dump to the printer.

Limitations
-----------
PQPLOT is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. This packet can be sent only while the driver is in display
mode and operating on the graphic screen. Secondary applications may send
this packet, but some drivers will not recognize it.

AutoCAD fills in all the members of this packet. The ADI driver can modify
pstat.

History
-------
PQPLOT was introduced in ADI 3.0 with the packet mode interface. Support
for PQPLOT was dropped in AutoCAD Release 12.

Declaration
-----------
#define PQPLOT 15

struct pkqplot {
    short   pfunc;    /* PQPLOT */
    short   pstat;
};

Description
-----------
PQPLOT instructs the driver to perform a screen dump (all viewports) to the
printer. If the driver performs the screen dump, it returns member pstat
equal to 1. Otherwise, the driver does nothing, and returns pstat equal to
0.

Support for PQPLOT was dropped in AutoCAD Release 12.

This call is initiated by AutoCAD's QPLOT command, which was discontinued
in release 12. If you want your ADI driver to support this function, your
driver can simply monitor unrecognized command strings and act as before.



6.17.67 PRCMAP
================

Purpose
-------
Reads color map entries from display drivers.

Limitations
-----------
PRCMAP is an alias for the rendering packet RDRCMAP. All ADI 4.2 DEV_DS
drivers are required to support this packet in display mode.

The controlling application fills in all the members of this packet. The
ADI driver modifies members red, green and blue. If a logical color is
requested, the ADI driver also modifies member code to return the physical
ACI associated with the logical color. Applications can tell if the ADI
driver has satisfied the logical color request by noticing if the code
member has been modified.

History
-------
Added in ADI 4.2 to support AVE Render.

Declaration
-----------
#define PRCMAP    2016         /* alias for RDRCMAP */
/* alias packet structure for PRCMAP a.k.a. RDRCMAP */

struct pkcmap {
    short pfunc;               /* PRCMAP */
    short code;                /* index */
    unsigned short red;        /* red intensity */
    unsigned short green;      /* green intensity */
    unsigned short blue;       /* blue intensity */
    unsigned short flags;      /* option flags */
};

Description
-----------
PRCMAP is an alias for the rendering packet RDRCMAP (they have the same
packet code). All DEV_DS ADI 4.2 drivers are required to support this
packet. DEV_RC drivers are required to support RDRCMAP along with other
rendering packets (see chapter 7).

DEV_DS drivers are only expected to be able to read the display color map.

The flags member is a bit-coded field that helps clarify how single-screen
systems should respond to the PRCMAP packet. Since DEV_DS drivers can only
return the display color map, they can ignore this member.

The color map index to be read is in member code when the packet is sent to
your driver. Fill in the color values and return the packet with member
code unchanged.

The color values should be within the range from 0 to PDINFO.maxintens.

Any undefined color should be returned with all three color members as zero
(0).

If the member code is sent to you as negative one (-1), this is a request
for your driver to return the number of initialized color map members. You
should return this value in members red, green and blue, repeating the
value in each member. This should be the same as the value you returned in
PDINFO.ncolours.

If the member code is sent to you as a value ranging from -2 to MINLCOLOR
(see colours.h), this is a request to return the current RGB value and ACI
of the requested logical color. For example, the code value -2 is a request
to return the current graphic screen background color. You will return the
RGB values assigned to the requested logical color in members red, green
and blue. You will also return the ACI (AutoCAD color index) of this color
in member code. This is used by AVE Render on UNIX platforms, and will be
used more extensively in the future.

See Also
--------
RDRCMAP



6.17.68 PREDRAW
=================

Purpose
-------
This optional packet tells a display list driver to redraw the graphics
screen from the driver's display list.

Limitations
-----------
PREDRAW is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. Drivers indicate support for this optional packet by setting
EF_REDRAW (and EF_BS for ADI 4.0 and later) in pefmodes in PINIT and
PDINFO.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

Use of this packet by secondary applications is not recommended. Drivers
expect many related complex support services from Autodesk products.

Secondary applications should not send "drawing" vectors to ADI drivers,
unless you plan to force the ADI driver to invalidate its display list with
a "flush" command before returning control to AutoCAD, and unless you
completely understand the correct scaling of the logical and physical
spaces currently in operation.

Note that display list drivers expect AutoCAD to provide extensive support
services. For example, AutoCAD is expected to send PCLEAR to clear the
viewport before it is redrawn. AutoCAD is also expected to send to the ADI
driver all required non-drawing vectors to restore the image in the
viewport. These are likely to include the viewport borders, icons, grid (if
any), and so forth.

Drivers that also returned EF_PROVP in the pefmodes member in PINIT and
PDINFO expect that long BS Redraws can be interrupted with a <Ctrl-C>.
These drivers return to the controlling product before the redraw is
complete to allow for <Ctrl-C> detection and expect to be called again with
PREDRAW if no <Ctrl-C> was detected. They also support partial viewport
Redraw requests.

AutoCAD fills in all the members of this packet. The ADI driver can modify
members pstat and vpnumber.

History
-------
This packet was added for primitive display list support in ADI 2.0. The
vpnumber member was added in ADI 4.0 to support Release 10 multiple
viewports (ADI 4.0 display list drivers set EF_BS). The rdxmin, rdymin,
rdxmax, and rdymax members were added in ADI 4.1 to support Release 11
overlapping viewports with partial viewport redraws. ADI 4.1 drivers set
EF_PROVP. New pflush and status bits were added in ADI 4.1 to support
returning to AutoCAD for <Ctrl-C> detection.

Declaration
-----------
#define PREDRAW  24    /* Local Redraw */

packed struct pkredraw {
    short pfunc;       /* PREDRAW */
    short pstat;       /* Driver's reply to AutoCAD */
    short pflush;      /* Request from AutoCAD */
    short vpnumber;
    short rdxmin;      /* corners of area to Redraw */
    short rdymin;      /* in pixel coordinates */
    short rdxmax;
    short rdymax;
};

Description
-----------
Display list drivers (those that support PREDRAW) are able to redraw only
the vectors and polygons which AutoCAD marked as drawing vectors and
drawing polygons. This was done by sending them through PFILL, PBFILL,
FASTDRAW, PBATCHVEC or through PVEC with the pdrawm bit DR_NORDRAW clear.

The PREDRAW requests are sent from the Autodesk product to the driver in
the pflush member, and the driver sends its replies back in the pstat
member according to the following tables.

Table 6-55. Requests sent to ADI driver in PREDRAW.pflush

Mnemonic       Value Meaning if Set

RD_OLD         0x0   Redraw all vectors

RE_FLUSH       0x1   Flush display list

RE_INIT        0x2   Starting a fresh Redraw sequence

RE_MORE        0x4   Continue the Redraw

RE_BREAK       0x8   Redraw interrupted by <Ctrl-C>

RE_PART        0x10  Partial Redraw request


Table 6-56. Requests sent from ADI driver in PREDRAW.pstat

Mnemonic       Value Meaning if Set

RE_FAIL        0x0   Could not do the Redraw

RE_DONE        0x1   Redraw is complete

RE_BUSY        0x2   Redraw still in progress


When a Redraw is necessary, the Autodesk product issues the PREDRAW request
with pflush set to 0, instructing the driver to redraw all vectors. The
Autodesk product still issues a PCLEAR request prior to the PREDRAW
request, and draws grid dots and so forth afterwards.

If the EF_BS flag was set in pefmodes in the PINIT packet and vpnumber is
zero, your driver should redraw the entire graphics area. If vpnumber is
nonzero, your driver should redraw the viewport specified in vpnumber.

If the driver is able to complete the Redraw, it should set pstat to 1
(RE_DONE).

Clearing pstat to 0 (RE_FAIL) indicates that the driver needs a fresh
display list. In this case, AutoCAD's action depends on the value passed in
vpnumber.

If vpnumber was passed as zero, the driver should return it as zero, and
the entire graphics area is redrawn. If vpnumber was nonzero, the driver
can either return the same value and get just the current viewport redrawn
or it can change vpnumber to zero to request a Redraw of the entire
graphics area. Your driver should not set vpnumber to any other value!

When the current contents of any display list are no longer valid, the
Autodesk product issues the PREDRAW packet with pflush set to one (1) to
indicate that the vector list should be discarded. In this case, no return
status is necessary.

Two features are available for drivers that returned the EF_PROVP flag in
pefmodes in the PINIT reply packet. One feature allows users to interrupt
long BS Redraws with <Ctrl-C>; the other feature allows for partial
viewport Redraw requests (RE_BREAK and RE_PART bits in pflush).

A typical Redraw might start with a RE_INIT request, indicating the start
of a Redraw sequence. If the driver is unable to redraw the specified
viewport from its local display list, it returns RE_FAIL in pstat.
Otherwise, it should redraw for about 100 ms (0.1 second) and then return
to AutoCAD with pstat set to RE_BUSY (assuming the display list is long
enough to require more than 0.1 second to completely redraw). Then, if the
user has not interrupted with a <Ctrl-C>, AutoCAD sends another PREDRAW
packet with RE_MORE in pflush, telling the driver to continue the redraw.
You should continue this sequence until either AutoCAD sends RE_BREAK (in
pflush), indicating that a <Ctrl-C> was pressed, or until your driver has
completed the requested Redraw operation and signals AutoCAD with RE_DONE
in pstat.

If AutoCAD signals that a <Ctrl-C> has interrupted the Redraw, the driver
should do any necessary internal cleanup to terminate the Redraw and return
to AutoCAD as quickly as possible.

If RE_PART is set in member pflush, this is a partial Redraw request. Your
driver should at least redraw all of each vector which passes through the
box defined by rdxmin, rdymin, rdxmax, and rdymax, clipping the vectors to
the entire viewport. You may simply redraw the entire viewport, if you
think this is faster. In cases where more than 80 or 90 percent of the
viewport is to be redrawn, it probably is faster to redraw everything than
it is to try to decide which vectors to draw.

If you want your driver to work with AutoCAD Release 10 and earlier, you
must pay careful attention to the PINIT member PINIT.pintlev and do non-
stop Redraws for Release 10 and earlier.



6.17.69 PREINIT
=================

Purpose
-------
Informs the display driver of a re-initialization of the display, often due
to a resizing of the screen.

Limitations
-----------
PREINIT is a display packet and can be sent to DEV_DS and DEV_RC drivers on
some windowing operating systems in display mode.

It should only be sent after an initial PINIT. PREINIT is the proper packet
to send after a window size change, text font size change, etc.

PINIT and PREINIT are not allowed between RDINIT and RDEND.

AutoCAD fills in members pfunc, pconfig and pintlev. On windowing platforms
it also fills in cdname. The ADI driver fills in all the other fields and
modifies pintlev.

History
-------
This packet was added in ADI 4.0 for OS/2. It has been used in UNIX display
ADI, Windows display ADI 4.1 and Macintosh ADI 4.1. The structure pkinit
has changed with the addition of various members as described earlier under
PINIT.

Declaration
-----------
#define PREINIT  57

struct pkinit {
    short pfunc;                               /* PREINIT */
    short pstat;                                /* Status */
    long pefmodes;         /* Extended function mode bits */
    short pconfig;           /* Screen configuration bits */
    short pintlev;                     /* Interface level */
    short pixdots;              /* Screen component sizes */
    short piydots;              /* Screen component sizes */
    short pixdotsm;             /* Screen component sizes */
    short pmodelinl;                  /* Mode line length */
    short pmnuchars;            /* Menu box size in chars */
    short pmaxboxes;                 /* Maximum menu size */
    short pmodes;                        /* Display modes */
    char psplit;              /* Lines in scrolling areas */
    char phwfill;                   /* Hardware fill mode */
    short pixwid, pixhgt; /* Pixel width & height (ratio) */
    char phidlines;                /* Hidden screen lines */
    char phidcols;               /* Hidden screen columns */
    short pymenumax;      /* Screen menu height in pixels */
    short pnuxdots;            /* AUI screen size in dots */
    short pnuydots;            /* AUI screen size in dots */
    short pnuxchars;          /* AUI screen size in chars */
    short pnuychars;          /* AUI screen size in chars */
    short pnuxbpc, pnuybpc;         /* Bits per character */
    short ybias;                     /* ULS - LLG y coord */
    long (*pfdraw)();                 /* FASTDRAW routine */
    char cdname[1];               /* Current drawing name */
};

Description
-----------
On most windowing platforms, AutoCAD sends PINIT for the first
initialization of the graphic screen, and then can send PREINIT multiple
times without intervening PTERM packets. The same structure is used for
PINIT and PREINIT. The same members are filled in by AutoCAD and by the
driver in handling both cases.

The difference is that one-time operations, such as allocating display list
memory, should not be repeated on PREINIT. Resizing AutoCAD's window is an
example of an operation which triggers PREINIT.



6.17.70 PREVEC
================

Purpose
-------
Allows a display list driver to change the status of a viewport from BS to
NOT_BS.

Limitations
-----------
PREVEC is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. Drivers indicate support for this optional packet by setting
EF_BS in pefmodes in PINIT and PDINFO.

Use of this packet by secondary applications is not recommended -- you
should not change the BS/NOT_BS state of a viewport because AutoCAD is not
aware of the change you have made.

AutoCAD fills in all the members of this packet. The ADI driver can modify
member rvflags.

History
-------
This packet was added in ADI 4.0 for Release 10. The ADI 4.0 "slave
viewport" feature was disabled in ADI 4.1 for Release 11. This resulted in
dropping use of the PREVEC flag bits "YES_VEC" and "UN_VEC". The "NOT_BS"
flag bit was added in ADI 4.1.

Declaration
-----------
#define PREVEC  46

struct pkrvec {
    short pfunc;        /* PREVEC */
    short rvflags;      /* Request flags */
    short vpnumber;     /* vp to switch status of */
    short master;       /* Who is that vp's master */
};

Description
-----------
The PREVEC packet allows a display list driver to change the status of a
viewport from BS to NOT_BS. It is useful if the driver runs short on
memory. Setting NOT_BS notifies AutoCAD that your driver can no longer
handle the viewport as a BS viewport.

This packet is sent only if EF_BS was set in PINIT.pefmodes.

Because the ADI 4.0 master/slave features have been discontinued, YES_VEC
and UN_VEC and the master member are ignored by any AutoCAD newer than
AutoCAD Release 10.

Setting AGAIN in the rvflags member facilitates changing the status of
several viewports in rapid succession.

Table 6-57. Values for PREVEC.rvflags

Mnemonic      ValueMeaning if Set

YES_VEC       0x1 No longer has meaning

UN_VEC        0x2 No longer has meaning

AGAIN         0x4 Send PREVEC again soon

NOT_BS        0x8 Set NO_BS for vpnumber




6.17.71 PROPENVP
==================

Purpose
-------
Reopens a viewport which has been moved on the screen or resized, but whose
display list is still valid.

Limitations
-----------
PREOPENVP is a display packet and can be sent to DEV_DS and DEV_RC drivers
in display mode. Drivers indicate support for this optional packet by
setting EF_BS and EF_PROVP in pefmodes in PINIT and PDINFO.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen. It may only be sent for a viewport which
is already open.

Use of this packet by secondary applications is not recommended; you will
confuse AutoCAD if you move or resize a viewport without AutoCAD's
knowledge.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
This packet was added in ADI 4.1 for Release 11 to support overlapping
transparent viewports.

Declaration
-----------
#define PROPENVP  66      /* reopen viewport */

struct pkrovp {
    short pfunc;          /* PROPENVP */
    short vpnumber;       /* Which viewport? */
    short vpxmin;         /* Revised corners of the */
    short vpymin;         /* vp in (ixdots,iydots) */
    short vpxmax;         /* Coordinates */
    short vpymax;
};

Description
-----------
This packet is sent only to BS drivers that set the EF_BS and EF_PROVP
flags in member pefmodes in the PINIT reply packet.

Viewports can be moved and resized by the user. If this is done, your
driver receives PROPENVP. Your driver should "reopen" the viewport and
continue to use its existing display list.

The members vpxmin, vpymin, vpxmax, vpymax contain the revised corners of
the viewport in (ixdots, iydots) coordinates.

You'll see this packet in AutoCAD if you move or resize a viewport with
TILEMODE = 0.



6.17.72 PROW
==============

Purpose
-------
Draw one row of grid dots, given a starting point and an increment and the
number of dots in a row, using XOR.

Limitations
-----------
PROW is a display packet and can be sent to BS DEV_DS and DEV_RC ADI 4.2
drivers in display mode. Drivers indicate support for this optional packet
by setting EF_BS in pefmodes in PINIT and PDINFO.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen. It may only be sent to BS viewports. Note
that two different coordinate systems are used in PROW depending on the
BIGVEC state of the driver.

The controlling application is responsible for clipping the grid drawn with
PROW so that it fits entirely inside the specified viewport.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
This packet was added in ADI 4.2 for Release 12 to support faster grid
drawing and to eliminate pixel-off-by-one errors. It replaces PDOT in BS
viewports for BS drivers. It was modified during ADI 4.2 development by
changing pdotcnt and scale to longs, pvpnumber to short.

Declaration
-----------
#define PROW 73             /* spec for a row of grid dots */

struct pkrow {
    short pfunc;            /* PROW */
    long pstartx, pstarty;  /* Starting point */
    long pxstep, pystep;    /* Increments */
    long pdotcnt;           /* Number of dots in the row */
    short pvpnumber;        /* Viewport to draw in */
    long scale;
};

Description
-----------
PROW sends your driver the specification for drawing one row of grid dots.
Clipping has already been done for you, all you have to do is scaling. PROW
uses logical coordinates.

The member scale contains bit coded flags indicating the scaling of the
values passed in pstartx, pstarty, pxstep and pystep.

Note that when we scale values up, this is done as a floating point
calculation inside AutoCAD. This adds additional precision for small values
without forcing your driver to handle a floating-point grid specification.
The internal computations in your driver should be done with 32 bit
arithmetic and should be truncated at the last minute.

Table 6-58. Values for PROW.scale

Mnemonic       Value        Meaning

STEP_UP        0x1 step values are * 65536

START_UP       0x2 start values are * 65536


If the viewport has a 15-bit logical space, the members pstartx, pstarty,
pxstep and pystep are in 15-bit logical coordinates * 65536 and the member
scale has both STEP_UP and START_UP set. If the viewport is BIGVEC, the
values are 31-bit logical values scaled according to the values in member
scale. If the starting point is closer to zero than 32768, the start values
are scaled up. Likewise, if the largest step value is larger than 32768,
the step values are not scaled. The idea is to keep the values small enough
to fit into a long. If the logical values are large enough to avoid
scaling, the logical->pixel transform should eliminate pixel-off-by-one
errors. In any case, the driver should draw the specified row of grid dots.

Non-BS viewports still receive the old PDOT packet. The ADI 4.2 "everything
logical" feature is designed to keep all operations in each viewport in a
single coordinate system. Thus, viewports in which the logical space is
inactive get everything in pixel coordinates, including grid dots (e.g., in
paperspace or DVIEW).

See the sample driver dspega42 for an example implementation of PROW.



6.17.73 PRPEN
===============

Purpose
-------
Senses the position of the screen-pointing device (light pen or touch-
screen).

Limitations
-----------
PRPEN is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

Use of this packet by secondary applications is not recommended because
drivers expect many related complex support services from Autodesk
products. For example, some drivers use PRPEN to send button box commands
to AutoCAD's screen menu. Some drivers use PRPEN for pointing device input,
and expect AutoCAD's usual support services for pointing devices.

AutoCAD fills in pfunc and pstat. The ADI driver may modify every field
except pfunc.

History
-------
Introduced in ADI 3.0 with packet mode ADI. Replaced in ADI 4.2 by
PRPEN_42.

Declaration
-----------
#define PRPEN  16

struct pkrpen {
    short   pfunc;       /* PRPEN */
    short   pstat;
    short   px, py;
};

Description
-----------
PRPEN instructs the driver to sense the position of the screen-pointing
device (e.g., light pen) and return its current position (in terms of
pixels on the graphics screen) in members px and py.

These coordinates should be returned in viewport-independent pixel
coordinates.

Your driver should return pstat, px, and py as indicated in the following
table.

Table 6-59. Return Values for struct pkrpen members

Response          pkrpen.pstat  pkrpen.px             pkrpen.py

No response       0

Tracking point    2   X-coord     Y-coord

Picked point      3   X-coord     Y-coord

Button pick       4  Button #


In AutoCAD, button picks that are returned by PRPEN (pstat equal to 4)
access the "AUX1" menu and can be used to support a multi-button function
box not necessarily associated with the light pen. Button code zero
references the first item in the "AUX1" menu. If the "AUX1" portion of the
menu file contains items that submit individual characters (as in "A\"),
the driver can use them in sequence to submit any command sequence it
needs.

However, this pre-ADI 4.0 trick is no longer needed; the PSTRING packet
allows more efficient communication with AutoCAD.

If you want your driver to work with Release 12 and with earlier AutoCAD
versions, you should support both PRPEN and PRPEN_42.



6.17.74 PRPEN_42
==================

Purpose
-------
Sense the position of the screen-pointing device (light pen or touch-
screen).

Limitations
-----------
PRPEN_42 is a display packet and can be sent to ADI 4.2 DEV_DS and DEV_RC
drivers in display mode. Do not send it to drivers that set the DI_NO_RPEN
flag bit in PDINFO.iflags.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

Use of this packet by secondary applications is not recommended - drivers
expect many related complex support services from Autodesk products. For
example, some drivers use PRPEN_42 to send button box commands to AutoCAD's
screen menu. Some drivers use PRPEN_42 for pointing device input, and
expect AutoCAD's usual support services for pointing devices.

AutoCAD fills in pfunc and pstat. The ADI driver can modify every field
except pfunc.

History
-------
PRPEN_42 was added in ADI 4.2 to replace PRPEN.

Declaration
-----------
#define PRPEN_42    107

packed struct pkrpen_42 {
    short pfunc;             /* Function code */
    short pstat;             /* Status: pen result */
    long px, py, pz;         /* Pen coordinates */
    long pix, piy, piz;      /* Pen roll, pitch and yaw */
    short pressure;
    short buttn;
    long pmodkey;            /* Modifier keys */
};

Description
-----------
ADI drivers that do not set the flag bit DI_NO_RPEN bit in PDINFO.iflags
receive PRPEN_42 packets.

PRPEN_42 replaces PRPEN for ADI 4.2 display drivers. It has the new 32 bit
members used by ADI 4.2 digitizers, but is otherwise used just as PRPEN
was. The new member pmodkey has meaning only for windowing operating
systems.

Your PRPEN_42 handler should use P_BUTTP to return button and coordinate
information simultaneously, just as PDIGTIZE_42 is handled.

PRPEN_42 instructs the driver to sense the position of the screen-pointing
device (e.g., light pen) and return its current position (in terms of
pixels on the graphics screen) in members px and py. If your pointing
device supports z, roll, pitch, and/or yaw values, these should also be
returned, otherwise these members should be zero. AutoCAD Release 12
ignores px, pix, piy, piz, and pressure.

Note that the natural ranges for px, py, pz, pressure, pix, piy, piz, and
buttons should have been returned in PDINFO so that AutoCAD knows how to
interpret these data.

These coordinates should be returned in viewport-independent (LLG) pixel
coordinates.

Button numbers should be returned in member buttn.

The pmodkey member is currently unused.

The pstat member contains one of the following: P_NONE, P_COORD, P_POINT,
P_POINTUP, P_BUTTP, P_BUTTPUP, P_OUT.

Table 6-60. Values for PRPEN_42.pstat

Mnemonic        Value                   Meaning

P_NONE          0 No data sample

P_COORD         2 Coords

P_POINT         3 Pick button pressed and coords

P_BUTTN         4 Menu button pressed (no longer valid, do not use)

P_BUTTP         5 Menu button pressed and coords

P_OUT           6 Cursor is out of window

P_POINTUP       7 Pick button released and coords

P_BUTTPUP       8 Menu button released and coords


Never return a value of P_BUTTN in pstat to indicate a button pressed.
Rather, use P_BUTTP to return both the button and coordinates at the same
time. P_BUTTN is now an illegal return value.

P_NONE means that there is no valid sample from the light pen. A value of
P_COORD is issued when the user is just moving the pen. P_COORD is also
issued between button down and button up events. A pick point is noted by
P_POINT and a release of the pick button is P_POINTUP. Likewise, the first
button on the digitizer would be noted by a P_BUTTP with buttn equal to 0.
A P_BUTTPUP with buttn equal to 0 would be issued when the user released
the first button. Note that buttons are zero based. In other words the
first button is a 0, the second is 1 etc.

In AutoCAD, button picks that are returned by PRPEN (pstat equal to 5)
access the "AUX1" menu and can be used to support a multi-button function
box not necessarily associated with the light pen. Button code zero
references the first item in the "AUX1" menu. If the "AUX1" portion of the
menu file contains items that submit individual characters (as in "A\"),
the driver can use them in sequence to submit any command sequence it
needs.

However, this pre-ADI 4.0 trick is no longer needed: the PSTRING packet
allows more efficient communication with AutoCAD.

If you want your driver to work with Release 12 and with earlier AutoCAD
versions, you should support both PRPEN and PRPEN_42.



6.17.75 PSHOWCFG
==================

Purpose
-------
Displays current configuration status on screen.

Limitations
-----------
PSHOWCFG is a display packet and can be sent to DEV_DS and DEV_RC drivers
in display mode.

Use of this packet by secondary applications is not recommended - secondary
applications should not reconfigure ADI drivers without AutoCAD's
knowledge.

This is a configuration-time packet.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PSHOWCFG was added in ADI 4.0 for some platforms (XENIX, P386 and OS/2) and
in ADI 4.1 for the rest (DOS and UNIX).

Declaration
-----------
/* PNEWCFG, PCHGCFG and PSHOWCFG all use this struct */
#define PSHOWCFG 62      /* show configuration record */

struct pkconfig {        /* config portion of adi driver */
    short pfunc;         /* PSHOWCFG */
    short preclen;       /* configuration record length */
    char  pcfgrec[1];
};

Description
-----------
PCHGCFG, PNEWCFG and PSHOWCFG all share a single packet structure. They are
all used at configuration time.

The PSHOWCFG packet is an informational packet that passes your driver its
private configuration record (that you saved with PNEWCFG or PCHGCFG), so
you can show the user (on screen) the current configuration status. Note
that AutoCAD does not pay attention to the contents of the configuration
record that it stores and retrieves for you.

Until Release 12 and ADI 4.2, display drivers have been expected to show
their devname string when passed PSHOWCFG. This is no longer correct - if
an ADI 4.2 driver detects that Release 12 is running, the driver should not
echo its devname string because AutoCAD will have already done so. The
driver might show configured options. These appear below the devname which
AutoCAD will have already displayed.

See Also
--------
PCFGREC, PCHGCFG, PNEWCFG



6.17.76 PSTRING
=================

Purpose
-------
Allows the driver to submit normal AutoCAD commands as fake keyboard input.

Limitations
-----------
PSTRING is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. It should not be sent to drivers that set the flag bit
DI_NO_STRINGS in PDINFO.iflags.

Use of this packet by secondary applications is not recommended. Secondary
applications can't respond correctly to the driver's fake keyboard input or
service zoom requests.

AutoCAD fills in pfunc, vpnumber, and status. The ADI driver can modify
srequest and constr.

History
-------
This feature was introduced in DOS ADI 4.0 as PCONIN, which accepted one
character at a time. XENIX ADI 4.0 turned PCONIN into PSTRING which sent a
whole string at a time. PSTRING is used on all ADI 4.1 platforms. In ADI
4.1, PSTRING was enhanced by adding srequest, status and the ZOOMRQ,
NOFAULT and NESTRING flag bits. In AutoCAD Release 12 (ADI 4.2) two more
secret commands (Zoom $1 and Zoom $2) were added. Three status flags were
also added in ADI 4.2.

Declaration
-----------
#define PSTRING  47

struct pknstring {
    short pfunc;           /* PSTRING */
    short vpnumber;        /* currently active vp */
    short status;          /* AutoCAD status */
    short srequest;        /* request to AutoCAD */
    char constr[1];        /* the string starts here */
};

Description
-----------
This packet is sent to drivers that do not set the flag bit DI_NO_STRINGS
in PDINFO.iflags.

If EF_MV in member pefmodes is set in the PINIT reply packet, this packet
allows the display driver to submit normal AutoCAD commands by overriding
keyboard input. The return value (if nonzero) is used as the next keystroke
sent to AutoCAD and is echoed on screen.

This packet is sent when AutoCAD is about to resort to the keyboard for
more input; scripts, AutoLISP input, and menu items in progress will
complete before AutoCAD looks to the display driver for more input. You may
return a null- terminated string in member constr[] to send a command to
AutoCAD.

The initial purpose of this packet is to make it possible for a big screen
display driver to request transparent pans and zooms, allowing extensions
to AutoCAD's user interface. A special option ($0) has been added to the
Zoom command to allow drivers to request a Zoom with the viewport corners
specified in "reals" (floating-point space). Thus, you can issue a command:

    Zoom $0 45.3 -2.le-002 100.54 250

Note that the four corners are xl, yl, xh, yh, separated by spaces. A space
at the end of the string is required to cause AutoCAD to execute the
command.

Zoom $0 can pan and zoom outside the current logical space, but only at the
cost of forcing a Regen. This is in contrast to PKZOOM, which only allows
Pan and Zoom inside the current logical space and does not force a Regen.

Two new display driver zoom commands, Zoom $1 and Zoom $2 have been added
in Release 12. These work like Zoom $0 in that they accept floating point
corners for a zoom box. Zoom $2 forces a regen with the view zoomed fully
in, so that logical and physical pixels are the same size, leaving the
largest possible range for zooming out before forcing another regen. Zoom
$1 forces a regen while zoomed as far out as possible, leaving as much
range for zooming in as possible.

The currently active viewport number (vpnumber) is available for your
information in this packet.

The status member contains bit-coded flags (added in ADI 4.2) which give
your driver some information about AutoCAD's state at the time when this
packet was sent. Note that these are not "bookend" state flags; they report
the current state of AutoCAD. This member is read-only from the driver's
point of view.

Table 6-61. Values for PSTRING.status

Mnemonic          ValueMeaning if Set

STAT_TILEMODE     0x1 TILEMODE = 1

STAT_PSPACE       0x2 AutoCAD is in paper space

STAT_UNSTABLE     0x4 AutoCAD is in an unstable state


If AutoCAD is "unstable", this is not likely to be a good time to send a
driver command through PSTRING or PKZOOM. You should wait for another
PSTRING packet which reports that AutoCAD is no longer unstable.

You can make requests of AutoCAD through srequest. ADI drivers fill in this
member and AutoCAD acts on the driver's requests.

The srequest member is a bit-coded field to send requests to AutoCAD. The
request bit options are as follows:

Table 6-62. Values for PSTRING.srequest

Mnemonic      Value                     Meaning if Set

NESTRING      0x1 PSTRING with no command echo

NOFAULT       0x2 Do not make this PSTRING command the AutoCAD default
command

ZOOMRQ        0x4 Send the driver a PKZOOM packet


The NESTRING option allows you to turn off AutoCAD's CMDECHO system
variable only for the duration of the PSTRING request. This speeds up
PSTRING since your driver is not sent strings to echo to the screen.

NOFAULT can be used to stop your driver's PSTRING command from becoming the
new AutoCAD default command.

The NESTRING and NOFAULT requests are not supported in ADI 4.1 for Windows.

ZOOMRQ allows you to ask for a PKZOOM packet to be sent. If ZOOMRQ is set,
any string in the member constr[] field is ignored.

You may either use PSTRING to fake keyboard input to AutoCAD, or to request
a PKZOOM packet, but you cannot do both at the same time.

The constr[] member contains the command string sent to AutoCAD. It is a
good idea to have "'" as the first character in your command string to make
your command transparent.

Another feature of Release 12 will help display driver authors to use
PSTRING effectively with foreign language versions of AutoCAD. Adding a
leading underscore "_" to a command string causes it to be interpreted as
US English, regardless of the language otherwise in use. Thus "cline" is
recognized as the line command. The underscore must be the first character
in the command. Transparent commands should be entered with the apostrophe
following the underscore, e.g. "_'line". If you want to make sure that
command redefinition doesn't take precedence in interpretation of a
command, the period may be used as before, e.g., "_.line" or "_'.line".

In P386 ADI, PSTRING replaced the obsolete PCONIN packet used in earlier
versions of ADI. Your P386 driver will not receive any PCONIN packets from
AutoCAD 386.

If your driver set both the EF_PROVP and EF_MV flags in member pefmodes in
the PINIT reply packet, it will receive an enhanced PSTRING packet
structure using structure pknstring when AutoCAD can accept user input.

If your driver only set the EF_MV flag (and not EF_PROVP) in pefmodes in
the PINIT reply packet, it will receive the old PSTRING packet structure,
structure pkstring.

For your information, here is the old pkstring structure declaration:

packed struct pkstring {
    short pfunc;         /* PSTRING */
    short vpnumber;      /* current vp FYI */
#ifdef XENIX
    char *constr;        /* init'd to NULL */
#endif
#ifdef PASS_DATA
    char constr[1];
#endif
#ifdef MSDOS
    unsigned short poff;
    unsigned short pseg;
#endif
};

Various PSTRING options might not work properly if you try to send more
than one AutoCAD command in a single PSTRING packet.

Also, if you want your ADI 4.1 driver to work with AutoCAD 386 Release 10,
you must detect which version of AutoCAD is running (via the PINIT packet
member PINIT.pintlev) and use the correct PSTRING packet definition.



6.17.77 PSYNC
===============

Purpose
-------
Synchronizes the local display list with the Autodesk product's internal
state. Provides status information and allows requests to be made.

Limitations
-----------
PSYNC is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. Drivers indicate a need for PSYNC packets by setting EF_SYNC
in pefmodes in PINIT and PDINFO. AutoCAD Release 11 and later will send a
few informational PSYNC packets even to drivers which do not set EF_SYNC.

This packet can only be sent while the driver is in display mode and
operating on the graphic screen.

This packet might present problems for secondary applications. They can't
service a driver's requests to modify aperture or pickbox, nor can they
redraw highlighting or repeat a prompt. Use with caution, if at all.

A new sync type was added in ADI 4.2 for Release 12, SY_NOSRV, to identify
syncs emitted by secondary applications that can't provide the usual PSYNC
services. Thus, secondary applications can safely use PSYNC with ADI 4.2
and later drivers, if they send SY_NOSRV.

Some display list drivers depend on PSYNC requests for proper operation.

AutoCAD fills in all the members of this packet. The ADI driver may modify
every member except pfunc and type.

History
-------
PSYNC started life in ADI 2.0 as a simple request to synchronize the
display. It was enhanced in ADI 3.1 by adding members prequest and
paperture for Release 9. It was enhanced again in ADI 4.0 by adding member
vpnumber for Release 10's multiple viewports. And it was further enhanced
in ADI 4.1 by adding members ppickbox and type for Release 11.

A new sync type was added in ADI 4.2 for Release 12, SY_NOSRV, to identify
syncs emitted by secondary applications that can't provide the usual PSYNC
services.

Declaration
-----------
#define PSYNC  23

struct pksync {
    short pfunc;         /* PSYNC */
    short prequest;      /* request code */
    short paperture;     /* aperture */
    short vpnumber;      /* current active vp */
    short ppickbox;      /* pickbox */
    short type;          /* sync type */
};

Description
-----------
For purposes of display synchronization, the PSYNC packet is issued
frequently only if the CF_SYNC and EF_SYNC flags were set in the pconfig
and pefmodes members in the PINIT reply packet respectively.

Even if the EF_SYNC flag was not set in the PINIT reply packet, occasional
PSYNC packets are sent from the Autodesk product for informational purposes
(to indicate the start and end of Redraw and Regen events and to send the
current viewport number to the driver before a PDINFO request triggered by
an ADS app).

For drivers that maintain local display buffers (vector lists), the PSYNC
request forces the local display buffers (queued vectors) to be drawn,
bringing the picture into synchronization with the Autodesk product's
internal state.

For example, this request is issued before digitizer samples are taken to
ensure that the entire picture is on the screen for the user to pick from.
PSYNC is also sent after each keystroke from the console.

The packet is sent with the vpnumber member initialized to the currently
active viewport, paperture to the current aperture value and member
ppickbox to the current pickbox size.

Member prequest is used to let your driver make special requests of the
Autodesk product, with the bit flags shown in the following table:

Table 6-63. Values for PSYNC.prequest

Mnemonic          ValueBitMeaning if Set

SY_APERTURE       0x1 0 Change aperture and pickbox size

SY_HILITE         0x2 1 Redraw nondrawing vectors for viewport vpnumber

SY_PROMPT         0x4 2 Reissue current prompt


AutoCAD supplies the current size (in pixels) of the object snap aperture
in the paperture member and the size of the entity selection pickbox in the
ppickbox member. If the driver wishes to change the aperture or pickbox
size, it should put the new sizes in paperture and ppickbox and set the
SY_APERTURE bit in the prequest member before returning. AutoCAD then sets
the object snap aperture and the entity selection pickbox size to the
specified values.

If you set SY_APERTURE in member prequest, AutoCAD uses the values you
return in member paperture and ppickbox as the new values for aperture and
pickbox. Because AutoCAD stores the aperture setting in its configuration
file, it is normal for the use of SY_APERTURE to cause a disk access. You
may change the pickbox and aperture sizes only in the currently active
viewport.

The SY_HILITE bit (if set) in member prequest instructs AutoCAD to redraw
any vectors that were not part of the drawing proper, such as highlighting.
Marker blips are never redrawn. If the EF_BS flag was set in the pefmodes
in the PINIT reply packet, and SY_HILITE is requested, the driver can
return a legal viewport number in vpnumber to request fresh nondrawing
vectors for that viewport. Returning zero in vpnumber references all
viewports.

Since servicing the SY_HILITE request is essentially a redraw operation,
internally in AutoCAD, your driver should be a little cautious about
requesting this service. It is not a good idea to request it when AutoCAD
is in a unstable state (see PSTRING.status).

The driver can set the SY_PROMPT flag in prequest to instruct AutoCAD to
reissue the current text prompt.

The type member is usually sent as zero from AutoCAD. At the start and end
of REGEN and REDRAW sequences, it is sent with a special value which might
be of use in maintaining bird's-eye displays and in display list
management.

The type SY_NOSRV was added in Release 12 and is recognized by ADI 4.2 and
later drivers. It is set by secondary applications which need to
synchronize the display but which cannot provide services such as
SY_HILITE, SY_PROMPT or SY_APERTURE. Prudent drivers will ignore all of the
members of such PSYNC packets except vpnumber, since secondary applications
might not bother to send you the current aperture or pickbox. But you
should synchronize the picture on receipt of such PSYNCs.

Table 6-64. Values for PSYNC.type

Mnemonic          ValueMeaning if Set

SY_SDRAW2         4 Beginning of Redraw event

SY_SDRAW1         3 Beginning of drawing vectors in a Redraw sequence

SY_SGEN2          2 Beginning of a Regen event

SY_SGEN1          1 Beginning of drawing vectors in a Regen sequence

SY_EGEN1          -1 End of drawing vectors in a Regen sequence

SY_EGEN2          -2 End of Regen event

SY_EDRAW1         -3 End of drawing vectors in a Redraw sequence

SY_EDRAW2         -4 End of Redraw event

SY_NOSRV          100 No services available for drivers


In some circumstances, it is possible for the PSYNC packet type member bit
flags to be sent in a nested sequence. For example, suppose a Regen is
requested from the text screen and the driver requests a Redraw in the
PGOGRAPH packet. As a worst case example your driver might receive
something like the sequence below:

SY_SGEN2
    SY_SDRAW2
        SY_SDRAW2
            SY_SDRAW1
            SY_EDRAW1
        SY_EDRAW2
    SY_EDRAW2
    SY_SGEN1
    SY_EGEN1
SY_EGEN2



6.17.78 PTABCFG
=================

Purpose
-------
This is an optional packet. PTABCFG supplies the driver with the
coordinates of the screen pointing area.

Limitations
-----------
PTABCFG is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode if they set EF_DIGTIZ in PINIT.pefmodes. PTABCFG should be
sent at initialization (shortly after PINIT) and whenever the tablet is
calibrated.

Use of this packet by secondary applications is not recommended because
secondary applications don't have the required information about tablet
scaling.

History
-------
This packet was added in ADI 4.0. It has been replaced in ADI 4.2 with
PTABCFG_42.

Declaration
-----------
#define PTABCFG  42

struct pktconfig {
    short pfunc;               /* PTABCFG */
    unsigned short llx, lly;
    unsigned short urx, ury;
};

Description
-----------
The PTABCFG packet is sent only if the EF_DIGTIZE and EF_MV flags were set
in PINIT.pefmodes. AutoCAD fills in all the members of this packet, and
members llx, lly, urx, and ury are in raw tablet coordinates.  The ADI
driver treats this as a read-only packet.

PTABCFG is sent during initialization (after PINIT) and after every tablet
configuration. It gives your driver the raw digitizer coordinates of the
corners of the "screen pointing area." These values, used along with the
PDIGTIZE packet, allow easier implementation of display driver commands
that use pointer input.



6.17.79 PTABCFG_42
====================

Purpose
-------
This is an optional packet. PTABCFG_42 supplies the driver with the
coordinates of the screen pointing area and information about the digitizer
driver's capabilities and coordinate ranges.

Limitations
-----------
PTABCFG_42 is a display packet and can be sent to ADI 4.2 DEV_DS and DEV_RC
drivers in display mode if they set EF_DIGTIZ in PINIT.pefmodes and
PDINFO.pefmodes.

PTABCFG_42 should be sent at initialization (shortly after PINIT) and
whenever the tablet is calibrated.

Use of this packet by secondary applications is not recommended because
secondary applications don't have the required information about tablet
scaling.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
This packet was added in ADI 4.2. It replaces PTABCFG. Modified during ADI
4.2 development by changing ints to longs.

Declaration
-----------
#define PTABCFG_42      106

packed struct pktconfig_42 {
    short pfunc;
    unsigned long llx;
    unsigned long lly;              /* Lower left corner */
    unsigned long urx;
    unsigned long ury;             /* Upper right corner */
    char cfgname[DEVNAMSZ + 1];      /* Config menu name */
    char execname[MAXPATHLEN];              /* Exec name */
    char model[MNAMLEN];                   /* Model name */
    long version;                      /* Version number */
    long options;                             /* Options */
    long x_max, y_max, z_max;            /* Linear range */
    long ix_max, iy_max, iz_max;     /* Rotational range */
    short pmin, pmax;          /* Pressure sensing range */
};

Description
-----------
The PTABCFG_42 packet is sent if the EF_DIGTIZE and EF_MV flags were set in
the pefmodes member in the PINIT reply packet, or if the PDINFO.iflags
DI_TABCFG request bit is set.

Members llx, lly, urx and ury are in raw tablet coordinates. They define
the corners of the screen pointing area of the digitizing tablet.

Members x_max, y_max, z_max, ix_max, iy_max and iz_max report the maximum
possible values for each of these directions of movement. The members pmin
and pmax report the device's range of pressure values. Display drivers
which want to interpret PDIGTIZE_42 packets will need these values since
the raw data are no longer scaled to 20480 by ADI 4.2 digitizer drivers. It
is also easy to tell from these values if a digitizer supports Z, roll,
pitch, yaw, or pressure data.

The member cfgname passes the digitizer driver's configuration menu name
string to the display driver. The NULL digitizer will contain "None". A 4.0
digitizer will contain "ADI digitizer (pre v4.1)" under UNIX and "ADI
digitizer (Real Mode)" under DOS.

The execname will contain the complete path name of the executable driver
for 4.2 and 4.1 digitizers. Under DOS for 4.0 digitizers the string will be
empty since AutoCAD doesn't store the name of the driver. In that
particular case the user is expected to install the TSR digitizer driver
before starting AutoCAD. A 4.0 UNIX digitizer driver will put the name of
the executable in execname. However, the executable name in this case will
not contain the complete path. The default name for 4.0 UNIX digitizers is
"dgadi".

The model member will be an empty string for all 4.0 digitizers. All 4.2
and 4.1 digitizers will contain the model string selected at configuration
time.

The version member will contain either DG_LEVEL_42, DG_LEVEL_41,
DG_LEVEL_40 or BAD. The NULL digitizer is the only one that will result in
version equal to BAD.

The options member passes the values returned by the digitizer in the
digitizer's EINIT packet. This tells the display driver which optional
digitizer features have been activated. For both 4.0 and the NULL digitizer
the options member will be 0.

The x_max and y_max entries will contain 0 for the NULL digitizer and 20480
for both 4.0 and 4.1 digitizers. The native range will be set only for 4.2
digitizers.

The z_max, ix_max, iy_max and iz_max fields will contain the native range
for 4.2 digitizers. They will be 0 for 4.1, 4.0 and the NULL digitizer.
These values will also be 0 for 4.2 digitizers that don't support a Z
coordinate or roll, pitch or yaw information.

PTABCFG_42 is called during initialization (after PINIT) and after every
tablet configuration. It gives your driver the raw digitizer coordinates of
the corners of the "screen pointing area." These values, used along with
the PDIGTIZE_42 packet, allow easier implementation of display driver
commands that use pointer input.

See Also
--------
PTABCFG, PDIGTIZE_42, PDINFO



6.17.80 PTERM
===============

Purpose
-------
Notifies the driver that drawing editor is being terminated. In AutoCAD
prior to Release 12, this signals a return to the AutoCAD main menu.

Limitations
-----------
PTERM is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode.

Use of this packet by secondary applications is not recommended. Secondary
applications should not terminate the display driver without AutoCAD's
knowledge, unless they reinitialize it into the state which AutoCAD expects
before returning control to AutoCAD.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PTERM was added with the packet mode ADI interface in ADI 3.0.

Declaration
-----------
#define PTERM  2

struct pkfonly {
       short  pfunc;     /* PTERM */
   };

Description
-----------
The PTERM packet indicates that the Autodesk product is leaving the drawing
editor. In AutoCAD Release 11 and earlier, PTERM signals a return to the
main menu, possibly followed by an exit to DOS. There is no main menu in
AutoCAD Release 12. Your driver should perform any required cleanup.

The driver should NOT clear the text screen, since this would erase any
error messages displayed by the Autodesk product should it exit abnormally.

A single-screen display is always in text mode when this packet is sent.

It is possible that PTERM might be sent twice. You should code defensively.

Release 12 sends PKILL to ADI 4.2 drivers just before exit to the operating
system.

See Also
--------
PKILL



6.17.81 PTEXT
===============

Purpose
-------
Writes raster text on the graphic screen.

Limitations
-----------
PTEXT is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode. It is supported only by drivers that set EF_NEWI in pefmodes
in PINIT and PDINFO.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

The controlling application is responsible for clipping text to fit the
screen and for saving and restoring any parts of the screen which may be
damaged (e.g., by using PBOXPUSH and PBOXPOP).

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PTEXT was added in ADI 3.0 as part of the support for "AUI". Support for it
was optional until ADI 4.1, when AUI support became mandatory. In ADI 4.1,
two new text attributes were added: TAPIXEL and TAXPARENT. Support for
these attributes was optional for DEV_DS drivers in ADI 4.1 but was
mandatory for ADI 4.1 DEV_RC drivers. Support for TAPIXEL and TAXPARENT is
indicated by setting EF_PTEXT in pefmodes. This became mandatory in ADI 4.2
for both DEV_DS and DEV_RC drivers.

The original ADI 3.0 PTEXT packet passed a pointer to the text string.
PTEXT was modified in ADI 4.0 to pass the string in the packet.

Declaration
-----------
#define PTEXT  31

packed struct pktext {
    short pfunc;     /* PTEXT */
    short px, py;    /* text location */
    short pattr;     /* text attribute bits */
    short ptlen;     /* text length */
    short pbgcolor;  /* text background color */
    short pfgcolor;  /* text foreground color */
    char ptext[1];   /* string */
};

Description
-----------
The PTEXT packet instructs the driver to write raster text on the graphic
screen. The first character should be drawn in the character cell specified
by (px,py). Successive characters should be drawn at ascending X locations.

The coordinates (px,py) are character cell coordinates if TAPIXEL is not
set and pixel coordinates of TAPIXEL is set. In either case, the origin is
at the upper left corner of the screen (ULS).

A maximum of one line of text is written by a single PTEXT request. The
text should be displayed with the attributes specified by the pattr member.
The pattr member is a bit-coded field with the following meanings (defined
in colours.h):

Table 6-65. Values for PTEXT.pattr

Mnemonic       Value   Meaning if Set

TANORM         0x0 Normal text (all bits clear)

TAINV          0x1 Reverse video text

TAGREY         0x2 Disabled text

TAXPARENT      0x4 Don't change background pixels

TAPIXEL        0x8 ULS pixel coordinates in px, py


The TANORM flag specifies normal text, whose background is the same color
as the background of the screen and whose intensity is normal.

The TAINV flag causes text to be written in reverse video, with the
background and foreground reversed or otherwise highlighted at the driver's
discretion.

The TAGREY flag signifies that the text denotes a disabled function. Such
text is generally "grayed out" by forcing every other pixel in a
checkerboard pattern to the background color (you are free to use other
visual cues if they work better). The driver must be able to handle TAGREY
in combination with TAINV either set or cleared. See "ADI Graphics Display
Test Procedures" for tips on testing grayed-out text.

The TAPIXEL flag indicates that members px and py are in ULS pixel
coordinates.

The TAXPARENT flag indicates that background pixels are to remain
unchanged.

The text string to be displayed is sent as a null-terminated string in the
ptext[] member. The actual number of characters written to the screen is
determined in one of two ways, depending on the value contained in the
ptlen member.

If ptlen is zero, the string is assumed to be null- terminated in the
normal C fashion. In this case, the driver outputs the string up to but not
including the terminating null value. Otherwise, exactly ptlen characters
are written to the screen

If the string contains less than ptlen characters, the driver appends blank
characters to the string. If the string contains more than ptlen
characters, the driver truncates the string.

Character codes comprising the text string will, for the U.S. domestic
version of the Autodesk product, always be in the inclusive range from 32
to 128, with 128 signifying a check mark.

Editions of Autodesk products in languages other than English might use
additional character codes beyond 128, and might use a different code for
the check mark character (see the PLANG packet description).

The members pbgcolor and pfgcolor are the colors (usually logical colors)
used to draw the text. The entire character cell is filled with pixels of
either of these two colors only.

See Also
--------
PLANG, PINIT



6.17.82 PTPROMPT
==================

Purpose
-------
Instructs the driver to set the current text cursor to the prompt line on
the screen (dual-screen systems).

Limitations
-----------
PTPROMPT is a display packet and can be sent to DEV_DS and DEV_RC dual-
screen drivers in display mode. Such drivers clear DM_GROK in PINIT.pmodes.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PTPROMPT was added with the packet interface in ADI 3.0.

Declaration
-----------
#define PTPROMPT  14

struct pkfonly {
    short  pfunc;    /* PTPROMPT */
};

Description
-----------
The PTPROMPT request is issued only on dual-screen displays, indicated by
clearing the DM_GROK flag (bit 2) in the pmodes member in the PINIT reply
packet.

PTPROMPT instructs the driver to set the current text cursor to the prompt
line on the screen. This request is followed by a sequence of PCHAR packets
to write to the prompt line. Text output to the prompt line is terminated
by a final PECHAR packet request.

AutoCAD Release 11 for Windows handles this packet in dsacad.dll so that it
is never sent to Windows ADI drivers.

See Also
--------
PCHAR, PECHAR



6.17.83 PTXTCLR
=================

Purpose
-------
Instructs the driver to clear the text screen.

Limitations
-----------
PTXTCLR is a display packet used only on platforms with windowing operating
systems. It may be sent to DEV_DS and DEV_RC drivers. All DEV_DS and DEV_RC
drivers on most windowing platforms (UNIX, OS/2 and Windows, but not Mac)
support this packet.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PTXTCLR was introduced in OS/2 ADI 4.0. It has also been used in ADI 4.1
for UNIX and Windows display drivers.

Declaration
-----------
#define PTXTCLR   50

packed struct pktxtclr {   /* clear text screen */
    short pfunc;           /* PTXTCLR */
};

Description
-----------
AutoCAD Release 11 for Windows handles this packet in winacad.dll so that
the ADI driver (dsacad.dll) never sees it.

PTXTCLR tells the driver to clear the text screen and reset the text cursor
to the upper left corner. This also resets the scroll bars for the text
screen and makes sure there is enough room in the scrolling text buffer for
at least another screen of text.

AutoCAD is currently the only product using PTXTCLR.



6.17.84 PTXTCHAR
==================

Purpose
-------
Sends characters to the display driver so it can in turn send them to the
operating system. Used for text-mode display.

Limitations
-----------
PTXTCHAR is a display packet used only on platforms with windowing
operating systems. It can be sent to DEV_DS and DEV_RC drivers. All DEV_DS
and DEV_RC drivers on most windowing platforms (UNIX, OS/2 and Windows, but
not Mac) support this packet.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet. AutoCAD is currently the only product using
PTXTCHAR.

History
-------
PTXTCHAR was introduced in OS/2 ADI 4.0. It has also been used for UNIX and
Windows display drivers, starting in ADI 4.1.

Declaration
-----------
#define PTXTCHAR  49

packed struct pktxtchar {   /* Char for text screen */
    short pfunc;            /* PTXTCHAR */
short pchar;
};

Description
-----------
Characters to be displayed on the text screen are sent through this packet.

On Windows ADI 4.1, winacad.dll takes care of writing the character to the
text screen, but passes this packet on to dsacad.dll so it can write the
character to the scrolling text area on the graphic screen. In other words,
dsacad.dll treats this like PWRSPLIT, with one exception: characters other
than carriage return or line feed are buffered and are actually written to
the screen only on receipt of a carriage return, line feed, PFLUSHCHAR
packet or some other special circumstance which leads the driver to believe
that synchronizing the scrolling text area is important (e.g., PTERM and
PREINIT).



6.17.85 PTXTSHOW
==================

Purpose
-------
Instructs the display driver to show or hide the text screen.

Limitations
-----------
PTXTSHOW is a display packet used only on platforms with windowing
operating systems. It may be sent to DEV_DS and DEV_RC drivers. All DEV_DS
and DEV_RC drivers on most windowing platforms (UNIX, OS/2 and Windows, but
not Mac) support this packet.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PTXTSHOW was introduced in OS/2 ADI 4.0. It has also been used for UNIX and
Windows display drivers, starting in ADI 4.1.

Declaration
-----------
#define PTXTSHOW 54       /* Show / hide text screen */

packed struct pktxtshow {
    short pfunc;          /* PTXTSHOW */
    short pshow;          /* Flag */
};

Description
-----------
AutoCAD Release 11 for Windows handles this packet in winacad.dll, the ADI
driver (dsacad.dll) never sees it.

Table 6-66. Values for PTXTSHOW.pshow

Values      Meaning

0           Block all GOTEXT operations (textok =0), hide text window, and
take it out of focus

1           Allow GOTEXT (textok = 1)

2           Allow GOTEXT, show text window and bring it into focus. If in
drawing editor, disable the graphics window and make the text window float
above the gfx


AutoCAD is currently the only product using PTXTSHOW.



6.17.86 PVEC
==============

Purpose
-------
Instructs the driver to draw a vector.

Limitations
-----------
PVEC is a display packet and can be sent to DEV_DS and DEV_RC drivers in
display mode while on the graphic screen.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

Secondary applications should not send drawing vectors - this would put a
BS driver's display list out of sync with AutoCAD. In other words, they
should send only non-drawing vectors with DR_NORDRAW set in pdrawm.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PVEC was added with the packet mode interface in ADI 3.0. It was extended
by the addition of member vpnumber in ADI 4.0 to support Release 10
multiple viewports.

Declaration
-----------
#define PVEC 5

packed struct pkvec {
    short pfunc;              /* PVEC */
    short pfx, pfy;           /* From point */
    short ptx, pty;           /* To point */
    short pcolour;            /* Color */
    short pdrawm;             /* Drawing modes */
    short vpnumber;
};

Description
-----------
The driver draws a vector from (pfx,pfy) to (ptx,pty).

If the EF_BS flag was set in pefmodes in the PINIT reply packet and
vpnumber is zero, members pfx, pfy, ptx, and pty are in LLG viewport-
independent coordinates. If member vpnumber is nonzero, then they are
viewport-relative logical coordinates.

Logical vectors arrive through PVEC only for BS drivers operating in 15-bit
mode. BIGVEC drivers receive logical vectors through PBIGVEC or PBATCHVEC.

The driver scales, clips, and draws the vector in the viewport indicated in
vpnumber. Nondrawing vectors are only drawn in viewport vpnumber.

The pcolour member may be less than negative one (-1), indicating a logical
color number. When the driver receives a logical color number in pcolour,
it substitutes the appropriate physical color corresponding to the
requested logical color. If pcolour is neither zero nor negative one, that
color is used to draw the vector. Refer to appendix A for color assignment
information.

If pcolour is zero, the vector is erased (preserving the background color
if it is something other than black). If pcolour is negative one, the
vector is usually XOR'ed with the background color in all image planes.

ADI 4.1 and later drivers check to see if CF_STUDIO is set. If so, they
only XOR with the low 4 bits of the color palette.

The bit flags in pdrawm are either instructional (a directive) or
informational in nature, as shown in the following tables:

Table 6-67. Values for PVEC.pdrawm (directives)

Mnemonic        Value              Meaning

DR_HILITE       0x0001         Highlighted

DR_NORDRW       0x0002 Vector is not part of drawing

DR_PHYSCY       0x0004 Obsolete unbiased coordinate system

DR_DASHED       0x0008   Real dashed lines


Table 6-68. Values for PVEC.pdrawm (informational)

Mnemonic        Value                 Meaning

DR_BORDER       0x0010        Viewport border

DR_CURSOR       0x0020         Part of cursor

DR_AXIS         0x0040         AXIS tick mark

DR_LISP         0x0080      Drawn by LISP app

DR_ICONS        0x0100 Icons, vpoint and dview

DR_MARK         0x0200 Blips, pedit mark, etc.

DR_VECA         0x0400 Drawing aligned - drag, 3d face, sketch, etc.

DR_SLIDE        0x0800                  Slide

DR_DHILIT       0x1000  Dehighlighting vector

DR_ZOOMD        0x2000           Zoom dynamic

DR_PLPRE        0x4000           Plot preview


DR_HILITE
---------
If the driver implements highlighting, pcolour is greater than zero, and
the DR_HILITE flag is set, the vector is drawn highlighted (preferably in a
dashed-line font, but it may use other forms of highlighting if they are
more effective). Otherwise, a solid vector is drawn.

Because support for AUI is required, the driver must be capable of drawing
a highlighted line in either normal drawing mode (pcolour greater than
zero) or XOR mode (pcolour equal to negative one (-1)). If both
highlighting and XOR are requested, XOR only the foreground segments to
make the operation reversible.

DR_NORDRAW
----------
The DR_NORDRW flag marks vectors that are not part of any drawing entity,
but are simply screen artifacts (e.g., the two lines forming a marker
blip). This is provided for BS drivers that use the PREDRAW packet. If the
DR_NORDRW flag is set, the vector is not redrawn by the next PREDRAW
request. Drivers that do not use the PREDRAW can ignore DR_NORDRW.

DR_DASHED
---------
When PVEC or PLINE see this option flag (which will never be seen together
with DR_HILITE), a highlighted vector should be drawn with gaps between the
visible segments. This is in contrast to DR_HILITE which erases to screen
background between visible segments. Support for this attribute is required
for all ADI 4.2 DEV_RC drivers.

It is not unusual for some graphics controllers to draw a different set of
pixels depending on the direction the vector is drawn. If garbage is left
on the screen after erasing a polyline or solid, you might try sorting the
coordinates before drawing the vector.

AutoShade sends AUI vectors through the PVEC packet instead of the PLINE
packet.

See Also
--------
PLINE, PREDRAW, PBIGVEC, PBATCHVEC, FASTDRAW



6.17.87 PVIEWPORT
===================

Purpose
-------
Specifies the visible portion of a viewport's logical space.

Limitations
-----------
PVIEWPORT is a display packet and can be sent to DEV_DS and DEV_RC BS
drivers in display mode. Support for this packet is optional and is
indicated by setting EF_BS in pefmodes in PINIT and PDINFO.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

Use of this packet by secondary applications is not recommended - secondary
applications should not change view parameters without AutoCAD's knowledge.

AutoCAD fills in all the members of this packet. The ADI driver can modify
vflags.

History
-------
This packet was added in ADI 4.0 to support Release 10 multiple viewports
for display list drivers. It is replaced by PBVIEWPORT for ADI 4.2 BIGVEC
drivers.

Declaration
-----------
#define PVIEWPORT  40

struct pkview {
    short   pfunc;       /* PVIEWPORT */
    short   vpnumber;
    short   lgxl, lgyl;
    short   lgxh, lgyh;
    short   master;
    char    vflags;
};

Description
-----------
The PVIEWPORT packet indicates what portion of a viewport's logical space
will be visible. It is not a Redraw or clear screen request.

The members lgxl, lgyl, lgxh and lgyh are in viewport-relative logical
coordinates.

The master member is ignored because the master/slave feature was
discontinued after AutoCAD Release 10.

The PVIEWPORT packet is usually followed either by a Redraw request (an
AutoCAD Pan or Zoom) or by an entirely new set of vectors (an AutoCAD
Regen).

If a BS driver is unable to handle this viewport in BS mode (perhaps due to
lack of display list memory), it may set the NO_BS bit flag in member
vflags to let AutoCAD know. The logical size of the viewport is reduced to
the viewport size and the driver is passed viewport-independent pixel
coordinates (through PVEC) for display directly on the screen. (Vectors
passed to the driver for a NO_BS viewport are all tagged for viewport
zero).

FAKE_BS drivers always set the BO_BS flag bit.

Table 6-69. Values for PVIEWPORT.vflags

Mnemonic      ValueMeaning if Set

NO_VEC        0x1 No longer used

NO_BS         0x2 This is not a BS viewport




6.17.88 PVPAGE
================

Purpose
-------
PVPAGE allows an application to select which video page to display and
which to read/write on, for displays which support multiple pages.

Limitations
-----------
PVPAGE is a display packet and can be sent to ADI 4.2 DEV_DS and DEV_RC BS
drivers in display mode. Support for this packet is optional and is
indicated by setting PDINFO.npages to a value greater than 1.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

The controlling application fills in every member. The ADI driver can
change member status.

History
-------
This packet was added in ADI 4.2 to support future Cyberspace applications.

Declaration
-----------
#define PVPAGE       76  /* controls active, visible page */

struct pkvpage {
    short pfunc;         /* PVPAGE */
    short active_page;   /* requested page to write to */
    short visual_page;   /* requested visible page */
    short status;        /* OK if successful */
};

Description
-----------
A driver which has more than one page of video memory at the configured
resolution and in the current mode, and which can support writing to an
invisible page, reports in PDINFO.npages or in RD_INFO.npages that it has
more than one page. Such drivers are required to respond to PVPAGE packets.
PVPAGE tells the driver which page to write into (until further notice) and
which page to make visible. These may be the same page or any two legal
pages in the same mode. The driver returns GOOD in member status if it can
meet the request and BAD if it cannot.

This packet can be sent in either display or in rendering mode. Typical use
of this feature is to construct a rendering on an invisible page, making it
visible after the image is complete, meanwhile leaving a different
rendering on the screen to entertain the user.

PVPAGES does not imply writing in two video pages at once.

RDEND (from rendering mode entered from the display screen) or PGOGRAPH
(from text mode) gets you the first display page with the last-displayed
display page contents restored to it. RDSTART gets you the first rendering
page with the last-displayed rendering page contents in it. We can look at
each pair as a circular queue. Whatever the application last revealed to
the world on the monitor is the last officially sanctioned version of the
display or rendering screen.

PDINFO.npages is the number of display pages.

RDINFO.npages is the number of rendering screen pages.

Any packet that takes you to the display screen (PINIT, PGOGRAPH, RDEND)
gets you page[0] for both display and active writing with the last
displayed contents restored in page[0].

RDSTART gets you rendering_page[0] for both display and writing with the
contents of the last displayed rendering restored in page[0].

PVPAGES changes which pages are displayed or active for whichever "mode" we
are in. The driver isn't expected to save extra pages of any non-current
mode (beyond the usual saving of the visible display or rendering page on
mode change).

If PVPAGE has been used to allow the image to be constructed on an
invisible display page, the PVPAGE packet which changes the visible page
also acts as an implied PSYNC, forcing everything to be drawn. PVPAGE
implies a PSYNC only if the visible page is changed.

If PVPAGE has not been used, PSYNC is sent to force everything to be drawn.
Applications will not send both PVPAGE and PSYNC during 3D operations.

See Also
--------
PDINFO and RD_INFO



6.17.89 PWHO
==============

Purpose
-------
PWHO lets ADI drivers know which application is executing them. It also can
let secondary applications know what ADI driver is currently running. It
has additional provisions for allowing ADI drivers to accept or reject
control by secondary applications, and it allows secondary applications to
clearly specify their mode of display operation.

Limitations
-----------
PWHO is a display packet and can be sent to ADI 4.2 DEV_DS and DEV_RC BS
drivers in display mode. It should be the first packet sent at
configuration and execution times.

There are versions of PWHO, with different packet codes but similar
structures, for every device type (rendering, digitizer, plotter, etc.).

PWHO may be sent at any time. Generally, any application which wants to
send CFG packets to a driver must send PWHO (or RDWHO) first so that the
driver knows who is configuring it.

ADS applications must not send PWHO directly to AutoCAD's display driver at
execution time - they should call ads_adistart() or ads_adiend(). These
cause AutoCAD to generate a PWHO packet with the application's information
filled in.

Applications which lack a serial number should stuff EOS into member
serial. Applications such as AVE Render which load a driver but do not
support alias device names should stuff 0 in member alias.

Note that it is incorrect for an application to send WHO_START twice
without an intervening WHO_END.

Primary applications should fill in the following fields: pfunc, psize,
product, prod_version, adipktlevel, action, alias, serial, driver_path, and
for UNIX platforms, cpid.

An ADI 4.2 application fills in adipktlevel with DS_LEVEL_42.

Secondary applications should fill in the following fields: pfunc, psize,
product, prod_version, adipktlevel, action, screen, serial, regapp_name
(for ADS applications), and cpid for UNIX platforms.

The ADI driver can modify members status, cleanup, driver_name and dpid.

History
-------
This packet was added in ADI 4.2. The structure was modified several times
during ADI 4.2 development by adding new members and by changing ints to
longs.

Declaration
-----------
#define PWHO 72                             /* See who.h */

struct pkwho {
    short pfunc;             /* PWHO for display drivers */
    short psize;                            /* PKWHOSIZE */
    short product;                       /* Product code */
    short prod_version;     /* Revision level of product */
    short adipktlevel;  /* Product's ADI interface level */
    short status;       /* Driver may return status here */
    short cleanup; /* Driver may return cleanup requests */
    short action;             /* App may request actions */
    short screen;            /* Display states requested */
    long alias;            /* display driver alias index */
    char  serial[WHO_SERIAL_SIZE];    /* ASCIIZ serial # */
    char  regapp_name[WHO_REGAPP_NAME_SIZE];
    char  driver_name[DEVNAMSZ + 1];      /* Name string */
    char driver_path[MAXPATHLEN];         /* Where found */
#ifdef UNIX
    long cpid;     /* controlling application's UNIX pid */
    long dpid;                      /* driver's UNIX pid */
#endif /* UNIX */
};

#define PKWHOSIZE (sizeof(struct pkwho))
#define WHO_SERIAL_SIZE 32
#define WHO_REGAPP_NAME_SIZE 32

Description
-----------
PWHO is sent by Autodesk products very early in configuration time with
WHO_CFG set and very early in execution time with WHO_XQT set. The idea is
to let drivers know which product is in control before the driver has to
respond to any requests from the product.

This packet will also be sent by AutoCAD at an application's request (in
ads_adistart() or ads_adiend()). For display drivers, it needs to originate
in AutoCAD core code so that AutoCAD can handle any requests which the
driver might make.

The member pfunc is defined differently for each device type, in the C
header file for each device type (e.g., dgp.h, plp.h, etc.). The structure
definition for pkwho and the definitions for products and versions are
defined in a new C header file, who.h.

The product ID number is unique for each Autodesk product. The header file
who.h defines these ID numbers. ID number zero is reserved for unknown (non-
Autodesk) primary products.

Table 6-70. Values for PWHO.product

Mnemonic          Value        Meaning

WHO_UNKNOWN       0 Unknown primary product

WHO_ACAD          1 AutoCAD

WHO_SHADE         2 AutoShade

WHO_SKETCH        3 AutoSketch

WHO_STUDIO        4 3D Studio

WHO_AME           5 AME

WHO_R12REND       7 AVE Render

WHO_AUNK          0x2000 unknown ADS application

WHO_TUNK          0x4000 unknown TEE application


Note that TEE applications are unable to provide cleanup services.

The member prod_version is made up of two parts: the upper 8 bits form the
major version number, while the lower 8 bits form a minor version number.
Thus, the first release of AutoCAD Release 12 would be 0x100 while a second
update release would be 0x101. As each new product or version is designed,
the author makes a code submission to update who.h, thus reserving a
number.

Table 6-70a. Values for PWHO.prod_version

Mnemonic        ValueMeaning

WHO_R12         0x100For AutoCAD Release 12 initial release

WHO_AME2        0x100AME 2.0


adipktlevel is sent from the Autodesk product to the ADI driver, indicating
which ADI interface level the user has selected. For most types of ADI
there are two parallel numbering system: intlevel and adipktlevel. The
intlevel numbers are an old system which proceeds sequentially. The
adipktlevel is a newer system with the lower 4 bits of the version
indicating minor revisions and the remaining bits indicating major version
changes.

The member status is returned as GOOD normally. If it is returned as less
than 0, the driver is indicating that it knows it cannot work with the
indicated product, version, serial number and interface level.

Table 6-71. Values for PWHO.status

Mnemonic            Value             Meaning

GOOD                0 Can work with product, etc.

BAD                 -1 Non-specific failure

ADI_BAD_VERSION     -2 Incompatible ADI version

ADI_BAD_APP         -3 Driver won't work with this application

ADI_BAD_SERIAL      -4 Serial number violation

ADI_BAD_PROD_VER    -5 Incompatible product version


The product's serial number is appended to this packet as a null terminated
ASCII string. This will allow vendors easily to lock their products to a
single serial number, if they like. Autodesk serial numbers are two ASCII
integers separated by a dash.

The member alias is filled in by AutoCAD at WHO_CFG and WHO_XQT time for
display drivers with an alias index. If the display driver has only one
device name, alias is zero. If the driver has more than one devname string,
AutoCAD will return the index of the selected devname.

The regapp_name member is, for ADS applications, a null-terminated string
which is returned by the application in ads_regapp().

The driver_name field is filled in by the ADI driver to pass a null-
terminated ASCII string (the currently configured dev_name string from the
edevent struct) to any application (particularly secondary applications)
wanting to know the identity of the current driver.

The driver_path member is sent from the primary product (e.g. AutoCAD) to
inform the driver of the full path from which the driver was loaded. This
is filled in by the primary product at configuration time and at execution
time. PWHO packets emitted by secondary applications won't have this filled
in.

The member cpid is used only on UNIX platforms - it passes the controlling
application's process id to the driver. Both primary and secondary
applications are required to fill in cpid. The member dpid returns the
driver's UNIX process id. UNIX digitizer and plotter drivers will find that
our library code has filled in dpid by the time that PWHO reaches the
driver's code. However, the driver can modify this value if it has a reason
to do so.

Table 6-72. Values for PWHO.action

Mnemonic         Value                 Meaning

WHO_CFG          1 Indicates configuration time, main app

WHO_XQT          2 Indicates execution time, main app

WHO_START        3 Used by secondary app on 1st takeover

WHO_PAUSE        4 Temporary end of secondary app takeover

WHO_RESUME       5 Secondary app resumes control

WHO_END          6 Secondary app terminates


When the primary product (e.g., AutoCAD) starts up in configuration, it
sets action to WHO_CFG. When the primary product starts at execution time,
it sets WHO_XQT. If a secondary application, via a TEE driver or an ADS
link takes over an ADI driver temporarily, it sets the action member to
WHO_START in a PWHO packet sent at its first takeover. At the end of its
takeover of the device, it sets member action to either WHO_PAUSE or
WHO_END. A PWHO packet with WHO_PAUSE tells the driver that the application
plans to take over again but is temporarily returning control to the
primary application. A PWHO packet with WHO_END indicates that the
secondary application does not expect to take over again.

Table 6-73. Values for PWHO.screen

Mnemonic            Value                Meaning

WHO_CURRENT_VP      0x1 If application operates only in current viewport

WHO_FOLDED          0x2 If application has asked AutoCAD to fold colors

WHO_240             0x4 If application is using the upper 240 colors


The WHO_CURRENT_VP flag bit is set if the application only wants to work in
the current viewport. Otherwise it is assumed to be operating full screen.

The WHO_FOLDED flag is set only if the WHO_240 flag is also set and the
application has asked AutoCAD to fold its upper 240 colors down into the
bottom 16. Otherwise AutoCAD uses all 256 colors.

The WHO_240 flag is set if the application plans to remap the colors above
ACI 15 (e.g., for rendering).

Note that WHO_FOLDED and WHO_240 are informational flags. AutoCAD handles
color folding internally, and AVE Render is responsible for sending you any
palette mapping packets.

For example, AVE Render, running as an ADS application on top of AutoCAD
Release 12, configured for full screen rendering, causes AutoCAD to send a
DEV_RC a PWHO packet with the WHO_CURRENT_VP flag cleared along with the
WHO_START flag set before it begins a full screen rendering (it does this
by making an ads_adistart() call, not by directly sending PWHO). When AVE
Render sends RDSTART, the driver saves the display screen image and palette
(as all single screen rendering drivers must) and changes to rendering
mode. Rendering packets follow to build up a rendered image. When it is
time to return control to AutoCAD, AVE Render sends RDEND to tell the
driver to return to the mode from which RDSTART was issued and, if
returning to display mode, restore the saved image and palette. It also
causes AutoCAD to send PWHO with action WHO_PAUSE. If the driver needs help
in repainting the screen, it can request cleanup actions through PWHO at
that time.

AVE Render can also shade in a viewport. WHO_CURRENT_VP signals this
intention. AVE Render sends a PDINFO packet to learn the current viewport
size and location. It is AVE Render's responsibility to clip, scale and
offset the polygons and scanlines it sends to fit the viewport. A PBIGBLIT
packet can save the viewport while a PPAL packet can save the palette. Note
that these packets allow multiple save and restore operations in arbitrary
order so that Render could shade in different viewports and restore the
images from them in any desired order. After rendering, AVE Render might
send PBIGBLIT and PPAL to restore the viewport and PWHO to notify the
driver of the end of its takeover. Or, it might just send PWHO and leave
the image in the viewport until later.

The cleanup member may be used by the driver to request help in restoring
normal AutoCAD operation. This service is provided by AutoCAD only if
WHO_PAUSE or WHO_END has been sent. It doesn't make sense to request
cleanup after rendering in a viewport. Bitcoded flags for this member
include:

Table 6-74. Values for PWHO.cleanup

Mnemonic       Value            Meaning

RP_STAT        1 Repaint status line

RP_MENU        2 Repaint screen menu

RP_SCROLL      4 Repaint scroll area

RP_GRAPH       8 Redraw picture

RP_TEXT        0x10 Redraw from hidden text screen

RP_BS          0x20 Ask BS driver to redraw graphics

RP_DIALOG      0x40 Redraw a dialogue box

RP_MLOAD       0x80 Reload menu

RP_REINIT      0x100 Driver requests complete Reinit


The new flag RP_REINIT triggers a fresh PINIT followed by a full repaint of
everything. Cleanup requests are satisfied immediately.

Note that the PINIT issued in response to a PWHO cleanup request is handled
differently by AutoCAD than most PINITs. The major difference is that
AutoCAD does NOT pay attention to the return values supplied by the driver
- it is assumed that the driver is being reinitialized to exactly the same
state it was in before the ADS application took over, i.e., the same screen
resolution, font size, etc.



6.17.90 PWINRESTORE
=====================

Purpose
-------
Restores the graphic screen saved as a result of a previous PWINSAVE.

Limitations
-----------
PWINRESTORE is a display packet and can be sent only to AutoCAD Release 11
for Windows ADI 4.1 DEV_DS and DEV_RC drivers in display mode. It can be
sent only if graphic mode after PINIT.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
Added in Release 11 AutoCAD for Windows ADI 4.1.

Declaration
-----------
#define PWINRESTORE  136
struct pkwinrestore {
    short pfunc;      /* PWINRESTORE */
    HDC hdc;          /* Window device context */
};
Description
-----------
AutoCAD sends PWINRESTORE whenever AutoCAD receives a WM_PAINT from
Windows. The hdc in this packet is the hdc returned by the BeginPaint()
call. This will not match AutoCAD's graphics window device context and will
include only the damaged area of AutoCAD's screen. When EndPaint() is
called (after your driver returns to AutoCAD from handling this packet),
Windows will blit this hdc to the screen. If you draw to AutoCAD's device
context instead of the hdc in this packet, your updates might be replaced
by a blank hole.

On receipt of this packet, the driver should restore the graphic area of
the screen to the image which existed at the last PWINSAVE packet.
Typically this is done with bitblit.

See Also
--------
PWINSAVE



6.17.91 PWINSAVE
==================

Purpose
-------
Save the graphic screen.

Limitations
-----------
PWINSAVE is a display packet and can be sent only to AutoCAD Release 11 for
Windows ADI 4.1 DEV_DS and DEV_RC drivers in display mode. It can be sent
only in graphic mode after PINIT.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PWINSAVE was added in Release 11 AutoCAD for Windows ADI 4.1.

Declaration
-----------
#define PWINSAVE  135
struct pkwinsave {
    short pfunc;     /* PWINSAVE */
    HWND hwnd;       /* Window handle */
};
Description
-----------
On receipt of this packet, the driver should save the graphic area of the
screen (typically in a bitmap).

AutoCAD sends a PWINSAVE packet to the display driver whenever it is
notified by Windows that it is about to be damaged. If AutoCAD was NOT
warned by Windows and the screen is damaged, AutoCAD tries to send fresh
vectors to the ADI driver. However, this doesn't always work. The only way
to assure successful screen repair in this case is to cancel any current
operation and redisplay all AutoCAD viewports. Because canceling every
current operation is unacceptable, if FASTDRAW is the selected screen
repair technique, and AutoCAD is busy when the screen is damaged, it is
possible that the repair attempt would be unsuccessful.

See Also
--------
PWINRESTORE



6.17.92 PWRSPLIT
==================

Purpose
-------
Writes text character to the text scrolling area.

Limitations
-----------
PWRSPLIT is a display packet and can be sent to DEV_DS and DEV_RC drivers
in display mode. All DEV_DS and DEV_RC drivers support this packet.

This is a display packet. It can be sent only to DEV_DS or DEV_RC drivers.
It can be sent only in graphic mode after PINIT.

This packet can be sent only while the driver is in display mode and
operating on the graphic screen.

AutoCAD fills in all the members of this packet. The ADI driver treats this
as a read-only packet.

History
-------
PWRSPLIT was added in ADI 3.0 with the advent of packet mode.

Declaration
-----------
#define PWRSPLIT  20

struct pkwrsplit {
    short   pfunc;    /* PWRSPLIT */
    short   pchar;
};

Description
-----------
Text is sent to the text-scrolling area on a single-screen system one
character at a time via the PWRSPLIT packet. The characters sent can
include carriage returns, tabs, new-lines, backspaces, and (in certain rare
cases) any character except NULL.

Your driver's PWRSPLIT handler must scroll the text area when a new-line
character is encountered on the bottom line of the screen, or when the last
column of the bottom line is reached.

The PWRSPLIT packet instructs the driver to write the character specified
in member pchar to the text scrolling area of the graphics screen at the
current text scrolling area position. Following the PWRSPLIT packet
request, the current text scrolling area position should be moved one
character to the right. The driver should maintain a current text scrolling
area position distinct from the text position used by other packets.

PWRSPLIT must be able to handle the following control characters: \t, \b,
\n and \r.

Don't advance the text cursor for other non-printing characters. A new line
(\n) implies carriage return (\r). Carriage return does not imply new line.

If the driver maintains its own hidden screen (indicated by returning both
members phidlines and phidcols equal to zero in the PINIT reply packet),
pchar should also be saved on the hidden screen.

If the hidden screen is maintained by AutoCAD (indicated by nonzero values
returned in phidlines and phidcols in the PINIT reply packet), the driver
need only draw the character on the graphics screen. AutoCAD takes care of
saving it.



6.17.93 PXPCOMD
=================

Purpose
-------
This is an optional packet. PXPCOMD notifies the driver when a transparent
display driver command character has been entered.

Limitations
-----------
PXPCOMD is a display packet and can be sent only to DEV_DS and DEV_RC
drivers in display mode.

AutoCAD fills in all the members of this packet. The ADI driver modifies
member pstat.

History
-------
PXPCOMD was added in ADI 3.0 with the advent of packet mode.

Declaration
-----------
#define PXPCOMD  26

struct pkxpcomd {
    short   pfunc;    /* PXPCOMD */
    short   pstat;
    short   pchar;
};

Description
-----------
The PXPCOMD packet is sent only if EF_XPCMD was set in PINIT.pefmodes.
PXPCOMD notifies the driver when a special transparent display driver
command character is entered. Currently, there is only one such character:
<Ctrl-L> (0C hexadecimal).

The transparent control character may be entered at any time by the user
and is immediately passed to the driver. This is the mechanism normally
used to invoke such functions as hardware Pan and Zoom.

The command character is passed to the driver in member pchar.

If the driver returns zero in pstat, AutoCAD proceeds with its unknown
character handling. Otherwise, AutoCAD assumes that the character has been
recognized and processed by the driver.




                  |====================================|
                  |                                    |
                  |           Chapter 7                |
                  |                                    |
                  | Combined Rendering and Display ADI |
                  |                                    |
                  |====================================|



7.1 Combined Rendering and Display (DEV_RC) Drivers
===================================================

The DEV_RC driver type is a single-screen combined rendering and display
driver. We encourage the development of DEV_RC drivers instead of new
DEV_DS drivers. The inclusion of AVE Render in AutoCAD Release 12 makes
combined display and rendering part of baseline AutoCAD functionality.

Packets for DEV_RC drivers come from both display ADI and rendering ADI.
The packet descriptions for DEV_RC drivers are detailed in chapter 6,
Display ADI, and chapter 8, Rendering ADI.


7.2 Multiple Display Modes
==========================

Many DEV_RC devices have multiple display modes, some of which lack enough
color depth to be of minimal rendering utility. The ADI 4.2 specification
requires that a device have at least one display mode in which an 8-bit
mapped palette is supported with at least 6 bits each for R, G, and B
values in the palette (this is the minimum required for 3D Studio v1.0).


7.3 Fake Big-Screen Drivers
=============================

All DEV_RC drivers must have at least "fake BS" capabilities. A fake BS
driver returns EF_BS in PINIT.pefmodes, claiming to maintain a display
list, but doesn't actually maintain a display list. Such drivers respond to
every PVIEWPORT or PBVIEWPORT packet with NO_BS and to every PREDRAW packet
with RE_FAIL, forcing the product to handle Redraws. The benefit of this
odd behavior is that fake BS drivers receive most of the BS packets and are
therefore aware of the size and location of every viewport. This
information essential to shading in a viewport.

FAKE_BS drivers should set EF_BIGVEC in PINIT and provide support for the
BIGVEC packets POPENBVP, PBVIEWPORT, PBMARK, PCBMARK, and PBFILL. If a
FAKE_BS driver fails to set EF_BIGVEC, it will needlessly force AutoCAD
into 15-bit mode.

7.3.1 Extended DEV_RC Specification
===================================

The DEV_RC driver type was introduced in ADI 4.1 for 3D Studio, but was
designed to be useful for AutoCAD and AutoShade as well. The ADI 4.1
implementation required display drivers to be able to handle some, but not
all, rendering functions in "display mode." The ADI 4.2 specification has
extended the definition of a DEV_RC driver to require full support for
rendering functions while in display mode.

The distinction between "rendering mode" and display mode now matters only
for devices which have a low quality (fast) rendering capability in display
mode and a slower true color ability in rendering mode. The user can
configure these drivers to do fast, display-mode renderings (typically 8
bits deep) or to do a mode switch to full screen 24- or 32-bit rendering
mode. The user can also choose to run the AutoCAD display in 24-bit mode,
which uses only 256 colors for vector drawing but gains 24-bit rendering
capability (while paying a speed penalty).

To be more specific, an ADI 4.2 DEV_RC is required to respond to the
packets described below as well as to both rendering and display packets
while in display mode. A mode switch from display mode to rendering mode
may be triggered by a RDSTART packet but is not required if the display
mode rendering support is adequate for the application's purposes. It is
possible for AVE Render to be configured for full-screen rendering even if
the rendering and display resolutions are not different. This offers the
user a chance to use the maximum screen real estate possible for their
rendering.

Drivers supporting different display and rendering physical or color
resolution in display and rendering modes must be able to respond to
display packets and rendering packets in the currently configured display
resolution and color depth and must also be able to respond in rendering
mode (after RDSTART) to rendering packets at the (different) currently
configured rendering resolution and color depth. RDINIT and RD_INFO inquire
about a driver's full-screen rendering mode capabilities, whereas PINIT and
PDINFO inquire about display mode (including rendering in a viewport)
capabilities.

Thus, the scanline flag bits in RDINIT control full-screen rendering
scanline color depth, and the RDINIT members ncolour, nshade, and maxintens
control the polygon color model for full-screen rendering mode.

For rendering in a viewport (display-mode rendering), the flag bits in
PDINFO control the color model for scanlines, the flag bits in PDINFO
control the color model for scanlines, and the PDINFO members ncolour,
nshades, and maxintens determine how polygons are rendered in a viewport.


7.4 Required Features for Display Mode
======================================

The following features must be supported by all ADI 4.2 DEV_RC drivers in
display mode (which can have different color depth and physical resolution
from rendering mode):

  * The AutoCAD display functions, including AUI support.

  * PTEXT attributes TAPIXEL and TAXPARENT.

  * The use of a mapped pallete for display functions. (This may be
    implemented with a lookup table for true color devices but must be
    supported by all drivers. AVE Render will change the palette even for
    continuous color devices in display mode during some programmable dialogue
    boxes.)

  * Separately configurable display and rendering resolutions.

  * Display resolutions of at least 320 by 200 with 256 colors (a minimum
    set by the 3D Studio materials editor) and at least 640 by 480 with 16
    colors. For 3D Studio it is also necessary to support at least an 80 column
    by 30 line text area on the graphic screen.

  * PBITBLT

  * PBIGBLIT

  * PDINFO

  * PWHO, including support for WHO_CURRENT_VP (i.e., at least DI_FAKE_BS
    support for BS packets). This is not a requirement to support a display
    list.

  * PLANG

  * PKILL

  * PPAL, if the device reports PDINFO.ncolours greater than 0.

  * PVPAGE, if more than one page is available.

  * RDPOLY

  * RDRSLINE, RDWSLINE

  * RDRCMAP, RDCMAPB, RDCMAP, RDCMAPE; i.e., they must either support a
mapped palette in hardware or pretend to in software. Note the requirement
for RDRCMAP to read logical colors and for all DEV_DS drivers to support
RDRCMAP.

  * DR_DASHED attribute in PBIGVEC, PBATCHVEC, PVEC, and PLINE.

  * Must be either BS or FAKE_BS.

  * BS drivers must support PROW (logical grid).

  * BS drivers must support logical cursors.

  * BS drivers must at least minimally support PSYNC.


7.5 Required Features for Full-Screen Rendering Mode
====================================================

The following features must be supported by a DEV_RC in full-screen
rendering mode (i.e., after RDSTART):

  * The standard AutoShade rendering packets.

  * Separately configurable display and rendering resolutions.

  * Rendering resolution of at least 640 by 200 with 256 colors for 3D
    Studio. AutoShade and AVE Render will tolerate 320 by 200 with 256 colors.

  * RDRSLINE, RDWSLINE

  * RD_INFO


7.6 Required Features for Rendering in a Viewport
=================================================

In order for AVE Render to permit rendering in a viewport to operate, an
ADI 4.2 DEV_RC must be configured for a display mode which meets these
requirements:

  * It must be either true color (PDINFO.ncolours = 0) or support at least
    128 colors (PDINFO.ncolours >= 128).

  * It sets one scanline and/or one polygon capability flag in
    PDINFO.iflags.

Note: AVE Render requires true color display modes to handle the palette
reading and writing packets RDRCMAP, RCMAPB, RDCMAP, and RDCMAPE (for some
programmable dialogue box operations).

A secondary application can learn about the driver's currently configured
display mode by sending a PDINFO packet to the driver. It can learn
something about its rendering mode capabilities by sending RD_INFO.


7.7 Typical Operation Scenarios
===============================

Four examples of DEV_RC operations are presented in this section: rendering
in a viewport, full-screen rendering, secondary applications sending
nondrawing vectors to a viewport, and secondary applications sending
nondrawing vectors to the full screen. These are general examples meant to clarify
these kinds of operations -- you should be able to extrapolate these to fit
your individual needs.

Do not make any assumptions on the packet sequencing shown in these
examples in writing your driver. As with all ADI drivers, you should never
rely on a specific packet sequence in your driver's packet-handling
routines.

7.7.1 Rendering in a Viewport
=============================

Following is a typical operating scenario for rendering in a viewport:

load AVE Render
    AVE Render may send RPCHGCFG to configure the driver
ads_adiinfo(ds)
    ....
at first shading command that needs to write to the display:
     AVE Render sends ads_adistart(...,WHO_START, WHO_CURRENT_VP)
         acad sends PWHO
         acad sends PDINFO
         acad sends PSYNC with current vp
     AVE Render sends PDINFO to get viewport size & position
    render to the viewport
     AVE Render sends PPAL to save palette
     AVE Render sets PHANDLE to the saved palette handle
     ads_adiend(...,WHO_PAUSE,WHO_CURRENT_VP)
         acad sends PWHO (driver should NOT send cleanup requests)

AutoCAD is able to draw again, the rendering is preserved
until that viewport is zoomed, panned or made unstable.
AutoCAD then restores its default palette for the damaged
viewport and redraws it. The palette for this viewport will
be restored with PPAL whenever it becomes current, until the
image is damaged.

next shading command
     AVE Render sends ads_adistart(...,WHO_RESUME, WHO_CURRENT_VP)
         acad send PWHO
         acad sends PDINFO
         acad sends PSYNC with current vpnumber
     AVE Render sends PDINFO
    (if the vpnumber is the same as last time, AVE Render
    sends PPAL to release the saved palette from the last
    rendering)
    render to viewport
     AVE Render sends PPAL to save palette
     AVE Render sets PHANDLE to the saved palette handle
     AVE Render sends ads_adiend(...,WHO_PAUSE, WHO_CURRENT_VP)
         acad sends PWHO (driver should NOT send cleanup requests)
more AutoCAD work
(Now AVE Render is about to terminate all rendering...)
AVE Render sends ads_adistart(...,WHO_RESUME, WHO_CURRENT_VP)
         acad sends PWHO
         acad sends PDINFO
         acad sends PSYNC with current vpnumber
     AVE Render sends PDINFO
     (if there are any saved rendering palettes, AVE Render
    should release them now with PPAL and PHANDLE
    operations.)
     ads_adiend(...,WHO_END, WHO_ACAD_PALETTE)
     acad sends PWHO (driver should NOT send cleanup requests)
    xunload AVE Render
7.7.2 Full-Screen Rendering
===========================

Following is a typical operation scenario for full-screen rendering:

   load AVE Render
      AVE Render may send RPCHGCFG to configure the driver
   ads_adiinfo(ds)
    ....
At first shading command that needs to write to the display:
      AVE Render uses ads_gotext to force text screen current,
      this causes the display driver to save the graphic screen.
      AVE Render sends ads_adistart(...,WHO_START, 0)
        acad sends PWHO
        acad sends PDINFO
        acad sends PSYNC
      AVE Render sends RDINIT to get rendering mode parameters
      AVE Render sends RDSTART packet to switch to rendering mode,
    render to the screen
    RDEND
    driver saves rendering screen, returns to text mode
    GOGRAPH
    driver restores display mode and last display screen,
    ads_adiend(...,WHO_PAUSE,0)
    acad sends PWHO (driver MAY make cleanup requests)

AutoCAD is able to draw again

Next shading command (this time in a viewport)
    AVE Render sends ads_adistart(...,WHO_RESUME, WHO_CURRENT_VP)
        acad sends PWHO
        acad sends PDINFO
        acad sends PSYNC with current vpnumber
    AVE sends PDINFO
    render to viewport
    ads_adiend(...,WHO_PAUSE, WHO_CURRENT_VP)
        acad sends PWHO (driver MAY make cleanup requests)
   more AutoCAD work
AVE Render sends ads_adistart(...,WHO_RESUME, WHO_CURRENT_VP)
        acad sends PWHO
        acad sends PSYNC with current vpnumber
    (if there are any saved rendering palettes, AVE Render
    should release them now with PPAL and PHANDLE
    operations.)
    ads_adiend(...,WHO_END, WHO_CURRENT_VP)
        acad sends PWHO (driver MAY make cleanup requests)
Unload AVE Render
        if AutoCAD sees that no other app wants the palette farbled,
        AutoCAD sends PPAL(PAL_ACAD_DEFAULT)
7.7.3 Nondrawing Vectors to a Viewport
======================================

Following is a typical operation scenario for a secondary application
sending nondrawing vectors to a viewport:

load app
ads_adiinfo(ds)
    ...
    ...
    ads_adistart(...., WHO_START, WHO_CURRENT_VP)
        acad sends PWHO
        acad sends PDINFO
        acad sends PSYNC
    app sends PDINFO to learn viewport size, etc.
    app sends vectors
    ads_adiend(...,WHO_PAUSE, WHO_CURRENT_VP)
        acad sends PWHO
    driver returns cleanup requests to AutoCAD
    AutoCAD resumes normal operation
7.7.4 Nondrawing Vectors to the Full Screen
===========================================

Following is a typical operation scenario for a secondary application
sending full-screen nondrawing vectors:

load app
ads_adiinfo(ds)
    ...
    ...
    ads_adistart(...., START, 0)
        acad sends PWHO
        acad sends PSYNC
    app sends PDINFO to learn screen size, etc.
    app sends vectors - using LLG or ULS coords as appropriate
       for PVEC or PLINE
    ads_adiend(...,PAUSE, 0)
        acad sends PWHO
    driver sends cleanup requests
    AutoCAD resumes normal operation
      


                    |================================|
                    |                                |
                    |           Chapter 8            |
                    |                                |
                    |         Rendering ADI          |
                    |                                |
                    |================================|




8.1 Introduction
================

This chapter describes rendering ADI, which includes DEV_RD (rendering
display), DEV_RH (rendering hardcopy), and DEV_RC drivers. DEV_RC drivers
are covered in detail in chapter 7, "Combined Display and Rendering ADI."

Autodesk products that can drive a rendering driver include AVE Render (an
ADS application that is part of AutoCAD Release 12), AutoShade, and
Autodesk 3D Studio. It is also possible for a secondary application, such
as an AutoCAD ADS program, to drive an ADI driver. The packet descriptions
below include discussion on how applications should behave when controlling
a rendering driver. This information is under the heading "Limitations."

Drivers written to work with AutoShade and Autodesk 3D Studio require both
a display interface and a rendering interface (used to produce color
renderings).

You can choose to write a single driver that works with AutoCAD, Autodesk
3D Studio, AutoShade, and AVE Render, as both a display and rendering
driver or you may decide to write separate drivers for display devices and
rendering devices. In fact, the rendering device need not be a video
display. Although AutoShade V2 supports both real-mode and P386 ADI
drivers, both Autodesk RenderMan and Autodesk 3D Studio support only P386
ADI drivers.

The rendering ADI specification, like other ADI specifications, has been
changing as Autodesk rendering products add new features or support new
technology. The result is new rendering packets and modifications to
existing rendering packets. Each packet description contains information
regarding changes in previous versions of ADI in a section titled
"History."

8.1.1 Polygons Versus Scanline Data
===================================

AVE Render and AutoShade send polygons and/or scanline data to rendering
ADI drivers. Autodesk RenderMan and Autodesk 3D Studio send only scanlines
to rendering drivers (for rendering purposes; polygons can be used for
other purposes).

Autodesk RenderMan always uses two triangles to clear the screen, or
portions thereof instead of sending RDCLEAR if only part of the image is
rerendered.

8.1.2 Continuous-Color Devices
==============================

If you initialize your device as a continuous-color device, AVE Render and
AutoShade never send RDPOLY packets; RDCRANGE is used instead.

AVE Render does send continuous-color devices RDCMAP packets to modify the
AutoCAD palette for programmable dialogues. And 3D Studio sends RDCMAP
requests to establish a mapped palette in display mode to support 3D
Studio's materials editor, even if you initialized your rendering device as
a continuous-color device (continuous-color capability is sometimes
referred to as continuous tone). Thus continuous-color DEV_RC drivers
should contain code to emulate a mapped palette.

If your rendering device is capable of more than 256 RGB shades, you might
want to treat it as a continuous-color device. A PostScript driver is an
example of a continuous-color driver (due to the large number of monochrome
dithering patterns available). You might also want to specify continuous
color if your device does not use RGB and the continuous-color
representation eases the translation to your device's color system.

8.1.3 General Rendering Notes
=============================

  * RDRSLINE, when used with devices that do dithering, should return true
color information, not dithered data.

  * ADI 4.2 rendering drivers should support RDWHO and RD_INFO.

  * rdadi42.h replaces rdadi.h for ADI 4.2.

  * For ADI 4.2, the rendering ADIRPKTLEVEL has been increased to 3.

8.1.4 3D Rendering
==================

We have added primitive 3D support to ADI 4.2 to support AVE Render and
Cyberspace. More sophisticated 3D support is planned.

The "ideal" 3D device for the model presented below provides the following
facilities:

  * A means of defining a view matrix and projection information.

  * A means of defining a polygon (a bounded region in 3-space) with the
provision to render the polygon as flat, using a Gouraud interpolation or
Phong shading.

  * The ability to group a set of these polygons into a named collection
    (referred to as a segment).

  * The ability to redraw an instance of such a segment on demand,
    transforming the points of the polygons through a 4x4 matrix. (Where
    normals are present for the vertices, they are transformed through the
    rotation part of the matrix.)

  * Support for proper hidden surface removal (typically via a z-buffer).

  * Support for double buffering (packets defined elsewhere).


8.2 Autodesk Products Capable of Rendering
==========================================

AutoShade employs two screens: graphics and rendering. The graphics
display, which looks much like the AutoSketch display, is used for command
selection and parameter setting by means of pull-down menus and dialogue
boxes. This screen is also used when plan or wireframe images are
displayed. The rendering screen is where fast-shaded and full-shaded images
are displayed. The two screens can be separate display devices or the same
device.

AVE Render is an ADS application, with much of the functionality of
AutoShade, included with AutoCAD Release 12. AVE Render uses the AutoCAD
display screen for wireframe images and user interface. It can be
configured to render to an AutoCAD viewport (if an ADI 4.2 DEV_RC driver is
present); it can instruct an ADI 4.2 DEV_RC to shift to full screen
rendering mode, or it can render to a separate video monitor using a
separately installed DEV_RD rendering driver. When AVE Render uses an ADI
4.2 DEV_RC driver by sharing it with AutoCAD, it uses of the ADS->ADI link
that is introduced in ADI 4.2.

AutoShade and Autodesk 3D Studio do not use the display list features of BS
display drivers.

There are five program modules in Autodesk 3D Studio. Although Autodesk 3D
Studio appears to be a single program, it was developed as a group of stand-
alone modules bound together at the end of development. The modules are the
2D Shaper, the 3D Lofter, the 3D Editor, the Keyframer, and the Materials
Editor.

Each of the modules loads and releases resources, such as ADI drivers, and
each maintains its own configuration information for drivers. Each of the
modules can use different display resolutions since they maintain different
configuration files and enter into different configuration dialogues.

Appendix C contains a more extensive discussion of the screen layouts and
operation of these Autodesk products.


8.3 Configuration
=================

All ADI rendering and rendering hardcopy drivers are sent configuration
packets during the configuration process. ADI 4.1 drivers are sent
RPNEWCFG, RPCHGCFG, RPSHOWCFG and (for DEV_RH only) RDETAIL. ADI 4.2
drivers are also sent RDWHO and RDLANG prior to the other configuration-
time packets. RDWHO is sent by the rendering application which is about to
send more configuration packets.

RDWHO and RDLANG are new ADI 4.2 packets that inform drivers of the
identity of the controlling product and of the language and code page in
use, prior to the main configuration packets. This simplifies
internationalization and the graceful handling of the special needs of
different products.

RPNEWCFG, RPCHGCFG, and RPSHOWCFG are sent at configuration time when the
user is configuring AutoShade, AVE Render, or Autodesk 3D Studio. They
allow your driver to use dispatcher functions to ask questions of the user.
You can store the answers in the product's configuration record by using
these three packets. Your configuration record is returned to you before
the RDINIT packet in the RPCFGREC packet at execution time.

If your driver is a DEV_RH, it is also sent the RDETAIL packet at
configuration time. It is advisable to let the Autodesk product handle I/O
for you. It can handle error reporting by putting up an alert box offering
an Abort or Retry option to the user. If your driver does its own I/O, you
will have no facility for presenting error messages to the user. AutoShade,
3D Studio, and AVE Render have no text screen once initial configuration
has been completed.

8.3.1 AutoShade Version 2 Logical Colors
========================================

AutoCAD has used logical colors (negative color numbers) for some time.
Before version 2, AutoShade did not send logical colors, thus confusing
some display ADI drivers. AutoShade V2 sends logical color numbers to ADI
display drivers. See appendix A for a discussion of logical colors.

8.3.2 Scanline Output for Autodesk RenderMan
============================================

AutoShade Version 2 with Autodesk RenderMan offers photorealistic rendering
capabilities. The only rendering output for Autodesk RenderMan is in the
form of scanlines. Thus it is important for all new rendering drivers to
support scanline output.

8.3.3 TGA and TIFF Files
========================

AVE Render and AutoShade Version 2 allow users to save and load TGA and
TIFF format images. The loading of these images requires that the rendering
driver support writing scanlines to the device. To save these file types,
the rendering driver must additionally support reading scan line data from
the device back to the Autodesk product. Whenever possible, your driver
should support both reading and writing scan lines. A rendering hardcopy
device might not support reading scanlines, but most rendering display
devices can.


8.4 Rendering Hardcopy
======================

This is an overview of how rendering hard copy works with AutoCAD Release
12 and AVE Render.

8.4.1 P386 Transport Layer
==========================

AVE Render loads a DEV_RH P386 ADI 4.2 driver. This is done with the old
environment variable (RHPADI) or magic filename (adirndhc.exp). The ADI
driver makes its dispatcher requests normally, putting dispatcher packets
into the dispatcher common memory buffer and calling AVE Render for service
through adientry(). AVE Render leaves the dispatcher packet in the AutoCAD
common memory buffer and makes an ADS request to AutoCAD for dispatcher
service (ads_dispt()).

8.4.2 UNIX Transport Layer
==========================

When a UNIX DEV_RH ADI 4.2 driver is started up, it gets the file
descriptors for the AutoCAD dispatcher pipes as arguments on the command
line. These pipes are used for dispatcher services. A second pair of pipes
to AVE Render is used for the flow of rendering packets. The four pipes are
managed by the library code linked with every DEV_RH UNIX ADI driver.

8.4.3 I/O Port Management
=========================

The configuration of hardware or file I/O for a DEV_RH is a special case.
At configuration-time, AVE Render sends RDETAIL to the driver. If the
driver supports more than one type of I/O (e.g., both serial and parallel),
the driver must use ciotype() to determine which I/O port type the user has
selected. The driver fills in device type (only one type is allowed here)
and communication parameters. AVE gets these from the RDETAIL packet
returned from the driver and saves them in its ave.cfg. It then makes an
ADS request to AutoCAD so that AutoCAD can ask the user the port
configuration questions that determine which port of the selected type the
device is using. See the chapter 5 section on ads_recfgport() for details
on the ADS request.

It is the ADI driver's responsibility to ask the user if she wants file
output. If file output is desired, the new bit FILEOUTPUT is set in
RDETAIL.type to let AVE Render know that file I/O via rhsend() is desired.
If FILEOUTPUT is set, no other bits should be set by the driver in the type
field.

At execution-time, after RDSTART, AVE Render makes another ADS request with
ads_recfgport(), this time filling in every argument except idvc that may
still be sent to AutoCAD as 0. AutoCAD will open the port, warning the user
to switch if AutoCAD sees that the port is shared with another device. On
return to AVE Render, AutoCAD will have filled in ads_recfgport with idvc.
AVE Render will then send a new execution-time packet to the DEV_RH driver:
RDRHOPEN. This serves two purposes: it tells the driver it is okay to start
sending rhsend() dispatcher requests, and it also supplies the driver with
the idvc argument to use in rhsend() requests.

If the driver requested file output at configuration-time by setting the
FILEOUTPUT bit, then AVE Render's execution-time request will also set this
bit. AVE Render will solicit a filename from the user because the driver
will have set RF_FILEOUTPUT in RDINIT, stimulating an RDFNAME request. AVE
sends the filename resulting from the RDFNAME request to AutoCAD in the
devname argument of ads_reconfig request. AutoCAD checks to be sure the
requested file can be opened and returns to AVE Render with an idvc value
for the driver to use in rhsend(). If the port or file can't be opened,
idvc is returned as -1.

After AVE Render is done rendering, it sends an RDEND packet to the ADI
driver. When the driver has completed processing RDEND and returned to AVE
Render, the idvc value sent at RDRHOPEN becomes no longer usable. AVE
Render sends a ads_recfgport() request to AutoCAD at this time with the
idvc value filled in and with IORD ORed into the iotype argument, telling
AutoCAD it is time to close the file or port. If a port was used and it was
shared with another device, AutoCAD now tells the user to switch devices
and then reinitializes the port for the original device.


8.5 Rendering Driver Packets
============================

Communication with the Autodesk product is managed by code in the library
files that you link with your driver. This hides most of the platform-
specific transport code.

For P386 ADI, an additional common memory buffer, offset by a fixed amount
from cbufadr, is used for passing scanline data. Your driver is given a
relative offset from cbufadr to the start of this second buffer whenever it
is required (e.g., in the RDRSLINE packet).

For the purposes of discussion in this chapter, the packets have been
divided into two groups: 2-dimensional (2D) and 3-dimensional (3D). Packet
usage tables are provided later in this chapter.

Packet communication via the common memory buffer depends on a structure
such as the following having been defined:

union rd_mstr {
    struct rd_init  rinit;     /* Initialize */
    struct rd_start rstart;    /* Start rendering */
    struct rd_poly  rpoly;     /* Polygon vertices */
    struct rd_cmap  rcmap;     /* Color map entry */
    struct rd_fname rfname;    /* Filename */
    struct rd_crange rcrange;  /* Shading range */
    struct rd_cpoly rcpoly;    /* Continuous-color polygon */
    struct rd_sline rsline;    /* Scanline data */
    struct rpkconfig rpkconfig;
    struct rpkcfgrec rpkcfgrec;
    struct rhcudetail rhcudetail;
    struct rdinfo rdinfo;
    struct rd_fgrab rfgrab;
    struct rhopen rhopen;
};
struct rendreq {
    short            rfunc;
    union rd_mstr    rpkt;
};

Notice that most rendering packets are sent inside a rendreq structure,
offset from the start of the common memory buffer by the short rfunc. This
is slightly different from display ADI packets, which include pfunc in the
packet structure.

8.5.1 Packets Added in ADI 4.2
==============================

The following packets were added in ADI 4.2, and are defined in either
rcadi3d.h or rdadi42.h:

P3D
PBPOLY3
PCPOLY3
PCSEG
PDLIGHT
PDRAWSEG
PDSEG
PLIGHT
PMODEL
PNPOLY3
PORTHO
POSEG
PPERSP
PPOLY3
PRIB
PSETCOLOR
PSETMATL
PVEC3
RDLANG
RDRHOPEN
RDWHO
RD_FGRAB
RD_INFO

8.5.2 Packet Usage Tables
=========================

The following table summarizes which 2-dimensional rendering packets are
used by each supporting Autodesk product:

Table 8-1. 2D Rendering packet usage

Packet  SHAD  RMAN   AVER    3DS      Comments
---------------------------------------------------
RDCLEAR   r     -   r       1,2 r   Clear rendering screen
RDCMAP    rm    rm  d rm    1,2dr   Map colors into lookup table
RDCMAPB   rm    rm  d rm    1,2dr   Begin changes to lookup table
RDCMAPE   rm    rm  d rm    1,2dr   End changes to lookup table
RDCPOLY   rc    rc  dc rc   1,2rc   Pass polygon vertices
RDCRANGE  rc    rc  dc rc   1,2rc   Color range
RDEND     r     r   r       1,2 r   Rendering process completed
RDETAIL   rh    rh  rh      1,2 rh  Hardcopy device configuration
RD_FGRAB  -     -   f       f       Grab a video frame
RDFNAME   r     r   r       -       Output filename
RD_INFO   -     -   d r     -       Rendering capability info
RDINIT    d     r   d r d r 1,2dr   Initialize rendering driver
RDLANG    -     -   d r     2 d     Render version of PLANG
RDPOLY    rm    rm  dm rm   -       Pass polygon vertices
RDRCMAP   d     rm  r  d rm 1,2dr   Read color map from RD driver
RDRHOPEN  -     -   rh      -       Open device for rhsend()
RDRSLINE  r     r   d r     1,2dr   Pass scanline data
RDSTART   d     r   d r d r 1,2dr   Begin new rendering
RDTERM    r     r   r       1,2 r   Rendering completed
RDWHO     -     -   d r     2 r     Controlling product
RDWSLINE  r     r   d r     1,2dr   Write scanline data to RD driver
RPCFGREC  d     r   d r d r 1,2dr   Execution-time configuration
RPCHGCFG  -     -   d r     1,2dr   Change configuration
RPNEWCFG  d     r   d r d r 1,2dr   Create configuration record
RPSHOWCFG -     -   d r f           Show configuration record

The following table summarizes which 3-dimensional rendering packets are
used by AVE Render. AutoShade, RenderMan, and 3D Studio don't utilize these
3D rendering packets.

Table 8-2. 3D rendering packets

Packet      AVE Render  Comments
--------------------------------------
P3D         3r          3D operation bookends
PBPOLY3     3r          3D polygon batch structure
PCPOLY3     -           3D polygon with vertex colors
PCSEG       -           Close current segment
PDLIGHT     -           Delete light source
PDRAWSEG    -           Draw segment
PDSEG       -           Delete segment
PLIGHT      3r          Define light source
PMODEL      -           Set modal segment transform
PNPOLY3     3r          3D polygon with vertex normals
PORTHO      3r          Orthographic projection
POSEG       -           Open segment
PPERSP      3r          Perspective projection
PPOLY3      3r          3D polygon
PSETCOLOR   3r          Set modal color
PSETMATL    3r          Set modal materials properties
PVEC3       -           3D vector
PVIEW       3r          Viewing transform

The following table shows the definitions for the symbols used in the
packet usage tables above:

Table 8-3. Key for rendering packet tables

Code  Definition
----------------
-       Not used
f       Indicates possible future usage
r       Rendering screen, any driver type
d       Display screen, any driver type
m       Mapped palette driver
c       Continuous-color driver
rm      Rendering screen, only mapped palette drivers
rc      Rendering screen, only continuous-color drivers
dm      Display screen, only mapped palette drivers
rh      Rendering hardcopy operations only
3       3D capable drivers only
SHAD    AutoShade
RMAN    AutoShade with Autodesk RenderMan
AVER    AVE Render
3DS     Autodesk 3D Studio

8.5.3 Color Models
==================

We use one of two color models for rendering: 8-bit paletted or continuous
color.

  * The 8-bit paletted color model is useful for devices with up to 256
    color capabilities. A palette is downloaded to the driver with RGB values
    for each palette entry. These palette entries are used in subsequent
    rendering operations involving both polygons (RDPOLY) and scanlines
    (RDWSLINE and RDRSLINE).

  * The continuous-color model is used for all other devices. These devices
    are sent RDCPOLY packets with floating point RGB values and scanline
    packets with 24-bit or 32-bit RGB values.

8.5.4 Modes
===========

A single-screen system can have three modes in a DOS environment. In
windowing operating systems, these modes can be represented by three
windows:

  * Text mode is used for configuration-time configuration. PGOTEXT and
    PGOTEXTU  are display packets that lead to the text screen. PTERM and PKILL
    are display packets that, depending on INTLEVEL, lead to the text screen in
    case the application forgot the PGOTEXT or PGOTEXTU.

    It is illegal for an application to issue PGOTEXT or PGOTEXTU from
    rendering mode.

AVE Render switches to the AutoCAD text screen just before issuing RDSTART
(when configured for full-screen rendering with a DEV_RC) and expects the
driver to return to the text screen at RDEND. AVE Render always expects the
driver to return to whichever screen it was in at RDSTART. Other
applications  may not switch to the text screen first. They should always
expect RDEND to return to whichever screen the driver was in when RDSTART
was issued.

  * Display mode is used to construct and display wireframe models. In
    AutoCAD Release 12, it is also possible to do rendering in a viewport while
    in display mode if a DEV_RC is configured. RDEND normally leads from
    rendering to display mode. If rendering mode was entered from the text
    screen, RDEND leads back to the text screen! PGOGRAPH leads from text mode
    to display mode (with DEV_DS and DEV_RC drivers).

    It is illegal for an application to issue PGOGRAPH from rendering mode --
    RDEND is the correct way to leave rendering mode.

  * Rendering mode is used for full-screen rendering. RDSTART normally
    triggers a switch to rendering mode. In AutoShade, this is usually issued
    from display mode.

8.5.5 Coordinate System
=======================

The coordinate system used for 2D rendering packets always has its origin
at the lower-left corner of the entire screen (LLS). All coordinates are
expressed in pixels.

When rendering in a viewport in display mode, the controlling application
is responsible for offsetting the scanlines and polygons and clipping them
to fit the viewport (whose size and location are returned by the ADI driver
in PDINFO).

Note that the rendering coordinate system used in display mode is different
from the display coordinate system used in display mode. The LLG display
coordinate system has its origin at the lower-left corner of the graphics
area of the AutoCAD screen. This is offset upward in the Y direction by the
height of the scrolling text area from the origin used for rendering
packets.



8.6 2D Rendering Packets
========================

These packets are defined in rdadi42.h.

8.6.1 RDCLEAR
=============

Purpose
-------
Instructs the driver to clear the rendering screen to the current
background color.

Limitations
-----------
Can be sent to DEV_RC drivers in rendering mode only. Can also be sent to
DEV_RD and DEV_RH drivers (in rendering mode).

Applications wanting to clear a DEC_RC viewport in display mode should use
the PCLEAR display packet (assuming a BS or FAKE_BS DEV_RC).

The controlling application fills in all members of this packet. The ADI
driver treats it as read-only.

History
-------
Introduced in ADI 3.0 to support AutoShade.

Declaration
-----------
#define RDCLEAR  2006

struct rendreq {
    short rfunc;    /* RDCLEAR */
};

Description
-----------
The RCLEAR packet instructs the driver to clear the rendering screen to the
current background color, and typically follows an RDSTART request. DEV_RH
drivers that allocate an image buffer should clear the buffer at this time.

The background color is determined by entry 0 in the rendering screen color
look-up table and can be changed by the RDCMAP packet.

If the RDCLEAR packet is issued by the controlling product before the color
look-up table has been set up, the driver should clear the screen to black.

Autodesk RenderMan can send a pair of polygons in background color to clear
a portion of the screen instead of sending the RDCLEAR packet if only part
of the image is rerendered.



8.6.2 RDCMAP
============

Purpose
-------
The RDCMAP request packet is used to map colors into the color look-up
table.

Limitations
-----------
Can be sent to DEV_RC drivers in display or rendering mode. It can also be
sent to DEV_RD and DEV_RH drivers in rendering mode. In any case, RDCMAP
should follow RDCMAPB. A series of RDCMAP packets should be terminated with
RDCMAPE.

RDCMAP should only be sent in rendering mode to drivers that report
rd_init.ncolour as greater than zero; that is, it should not be sent to
continuous-color devices (that report ncolour as 0 in rendering mode).

Palette indices in rendering mode (RDRCMAP.code) should be limited to the
range from 0 to rd_init.ncolour - 1 and must be less than 256. RGB values
can range from 0 to RDINIT.maxintens but in any case must be less than 256.

RDCMAP should normally be sent in display mode to DEV_RC drivers that
report PDINFO.ncolour as greater than zero; that is, it should not usually
be sent to continuous-color devices (that report PDINFO.ncolour as 0). AVE
Render sends color mapping packets to continuous-color ADI 4.2 DEV_RC
drivers to temporarily modify the display palette for Proteus dialogues. 3D
Studio v1.0 and v2.0 are also exceptions; they send palette mapping packets
to any DEV_RC in display mode. They also assume that palette animation is
possible.

Palette indices sent by secondary applications in display mode
(RDRCMAP.code) should always be limited to the range from 16 to
PDINFO.ncolour - 1 and in any case must be less than 256. Note that
secondary applications should not remap the AutoCAD first 16 colors (ACI 0-
-15). This limitation preserves the AutoCAD user interface colors. Primary
applications can remap colors from 0 to PDINFO.ncolour - 1 (to a maximum of
255). RGB values can range from 0 to PDINFO.maxintens but must be less than
256.

Both primary and secondary applications should fill in the flag bits
RF_CMREND, RF_CMDISP, and/or RF_CMFGRAB to indicate which palette(s) are to
be modified.

The controlling application fills in all members of this packet. The ADI
driver treats it as read-only.

History
-------
Introduced in ADI 3.0 to support AutoShade. The use of RDCMAP in display
mode for DEV_RC drivers was introduced in ADI 4.1 for 3D Studio. The use of
PDINFO to define display mode color capabilities was added in ADI 4.2.

ADI 4.2 introduced the use of the flag bits RF_CMREND, RF_CMDISP, and
RF_CMFGRAB to clearly specify the palette to be modified.

Declaration
-----------
#define RDCMAP  2008

struct rd_cmap {           /* Color map */
    short code;            /* Color table index */
    ushort red;            /* Red intensity */
    ushort green;          /* Green intensity */
    ushort blue;           /* Blue intensity */
    ushort flags;          /* Option flags */
};

Description
-----------
If you initialized your device as a continuous-color device in the RDINIT
reply packet (by returning 0 in RDINIT.ncolour), AutoShade never sends the
RDCMAP, RDCMAPB, RDCMAPE, or RDPOLY packets; RDCRANGE is used instead.
However, if your driver is a DEV_RC driver working with Autodesk 3D Studio,
you receive RDCMAP requests to establish a mapped display palette, even if
you initialized your rendering device as a continuous-color device.
Likewise, AVE Render expects continuous-color DEV_RC drivers to handle
palette mapping requests in display mode to allow AVE to modify the palette
for some Proteus dialogues.

Color table entries are specified in the code member, with the color
intensities for that table entry provided in the red, green, and blue
members. The flags member is used to clearly specify how a single-screen
system should handle the writing of scanline data and color maps.

Value ranges for the color table entry and RGB intensities in rendering
mode are determined from the return values of the ncolour and maxintens
members in the RDINIT reply packet. Refer to the RDINIT packet description
for information about the ncolour and maxintens members.

Value ranges for the color table entry and RGB intensities in display mode
for ADI 4.2 drivers are determined from the return values of the ncolour
and maxintens members in the PDINFO reply packet, unless 3D Studio v1.0 or
v2.0 is in control. 3D Studio assumes a 6-bit deep color map.

Color table entry index values in rendering mode (passed in the code
member) can range from 0 to (rd_init.ncolour-1). Table entry 0 is always
used by AutoShade for the current screen background color. Thus if RDCMAP
maps a new color into table entry 0, the rendering screen background color
should be changed accordingly. If this does not occur automatically as a
result of setting the new value for entry 0, your driver can wait until
after RDCMAPE is sent to display the new background color.

The values for members red, green, and blue are within the range 0 to
rd_init.maxintens in rendering mode and from 0 to PDINFO.maxintens in
display mode.

The flags member specifies which color map your driver should write:

Table 8-4. Values for RDCMAP.flags

Mnemonic  Value  Meaning
RF_CMREND  0x1  Write the rendering color map
RF_CMDISP  0x2  Write the display color map
RF_CMFGRAB  0x4  Write the frame grab palette

When a single screen system is on the display screen, RF_CMREND refers to
the saved rendering image from the last RDEND, which would be restored on
RDSTART with RF_VIEW set.

If the controlling application fails to set any of the flag bits, your
driver should assume the operation requested is on the current color map;
that is, if the request arrives in display mode, the display palette should
be read; if the request arrives in rendering mode, the rendering palette
should be read.

3D Studio v1.0 and v2.0 use palette animation in their materials editor.
Continuous color DEV_RC devices that are faking a palette have difficulty
with this mode. 3D Studio also enforces a rigid assumption of a 6-bit
palette depth in display mode.

See Also
--------
RDCMAPB, RDCMAPE, RDCRANGE, RDINIT, RDPOLY, RD_FGRAB



8.6.3 RDCMAPB
=============

Purpose
-------
Signals the beginning of changes to the color look-up table.

Limitations
-----------
Can be sent to DEV_RC drivers in display or rendering mode. Can also be
sent to DEV_RD and DEV_RH drivers in rendering mode. In any case, RDCMAPB
should be sent before RDCMAP.

RDCMAPB should only be sent in rendering mode to drivers that report
rd_init.ncolour as greater than zero.

RDCMAPB should normally be sent in display mode to DEV_RC drivers that
report PDINFO.ncolour as greater than zero; that is, it should not usually
be sent to continuous-color devices (that report PDINFO.ncolour as 0). AVE
Render sends color mapping packets to continuous-color ADI 4.2 DEV_RC
drivers to temporarily modify the display palette for Proteus dialogues. 3D
Studio v1.0 and v2.0 are also exceptions; they send palette mapping packets
to any DEV_RC in display mode. They also assume that palette animation is
possible.

RDCMAPB should be followed by a group of one or more RDCMAP packets,
terminated by an RDCMAPE packet.

The controlling application fills in all members of this packet. The ADI
driver treats it as read-only.

History
-------
Introduced in ADI 3.0 to support AutoShade. The use of RDCMAPB in display
mode for DEV_RC drivers was introduced in ADI 4.1 for 3D Studio. It was
extended for rendering in a viewport by AVE Render, and the use of PDINFO
to define display color capabilities was introduced in ADI 4.2.

Declaration
-----------
#define RDCMAPB  2007

struct rendreq {
    short rfunc;    /* RDCMAPB */
};

Description
-----------
The RDCMAPB packet signals the beginning of changes to the color look-up
table and is followed by multiple RDCMAP calls.

Drivers usually use this packet to reset a counter to zero, which
thereafter is used to count the number of initialized color map entries as
each RDCMAP packet is processed.



8.6.4 RDCMAPE
=============

Purpose
-------
Signals that all changes to the color look-up table have been completed.

Limitations
-----------
Can be sent to DEV_RC drivers in display or rendering mode. Can also be
sent to DEV_RD and DEV_RH drivers in rendering mode. In any case, RDCMAPE
should be sent after one or more RDCMAP packets.

RDCMAPE should normally be sent in display mode to DEV_RC drivers that
report PDINFO.ncolour as greater than zero; that is, it should not usually
be sent to continuous-color devices (which report PDINFO.ncolour as 0).

AVE Render sends color mapping packets to continuous-color ADI 4.2 DEV_RC
drivers to temporarily modify the display palette for Proteus dialogues. 3D
Studio v1.0 and v2.0 are also exceptions; they send palette mapping packets
to any DEV_RC in display mode. They also assume that palette animation is
possible.

The controlling application fills in all members of this packet. The ADI
driver treats it as read-only.

History
-------
Introduced in ADI 3.0 to support AutoShade. The use of RDCMAPE in display
mode for DEV_RC drivers was introduced in ADI 4.1 for 3D Studio. It was
extended for rendering in a viewport by AVE Render, and the use of PDINFO
to define display color capabilities was introduced in ADI 4.2.

Declaration
-----------
#define RDCMAPE  2009

struct rendreq {
    short rfunc;         /* RDCMAPE */
};

Description
-----------
The RDCMAPE packet indicates that all changes to the color look-up table
(performed by multiple RDCMAP calls) have been completed.

Your driver should ensure that the background color specified by entry zero
in the color look-up table is displayed on the rendering screen.

When changes are made to the color look-up table, the controlling
application might not use the entire look-up table, but, in rendering mode,
it is guaranteed to use at least one color entry, and a maximum of ncolour
(returned in the RDINIT reply packet) color entries. Changes are performed
sequentially by AutoShade and AVE render, from entry zero to entry (ncolour
- 1). This sequential guarantee does not apply to 3D Studio.

If the driver is a DEV_RC, in display mode, AVE Render might not use the
entire look-up table, but, it is guaranteed to use at least one color
entry, and a maximum of (ncolour - 16) (returned in the PDINFO reply
packet) color entries. Changes are performed sequentially, from entry 16 to
entry (ncolour - 1) or 255, whichever comes first.

If the preceding RDCMAP packets were sent in display mode, the display
palette must be updated on receipt of this packet. If the preceding RDCMAP
packets were sent in rendering mode, the rendering palette must be updated
on receipt of this packet. If the RF_MAPPEDPAL bit in the RDINIT packet has
been sent to a DEV_RC driver, and if the RF_CMREND, RF_CMDISP flag bits
were not used in RDCMAP packets to specify which color map(s) are to be
written, the driver must update both the display palette and the rendering
palette on receipt of this packet (if your DEV_RC device is not a
continuous-color rendering device).

See Also
--------
RDINIT, RDCMAPB, RDCMAP



8.6.5 RDCPOLY
=============

Purpose
-------
Passes polygon vertices to a continuous-color device driver.

Limitations
-----------
Can be sent in display mode to DEV_RC drivers that set the DI_CPOLY flag in
PDINFO.iflags. Can also be sent in full-screen rendering mode to DEV_RC,
DEV_RD, and DEV_RH drivers that report rd_info.ncolour as zero.

RDCPOLY should be preceded by RDCRANGE.

If the driver has set DI_SMOOTHPOLY in PDINFO.iflags, shading factors can
be sent at the polygon vertices in display mode. Likewise, if RF_SMOOTHFAC
is set in RDINIT.flags, shading factors can be sent in full-screen
rendering mode.

The coordinates vx and vy are in pixel coordinates with the origin at the
lower-left corner of the entire screen. In single viewport display
operations, the application is responsible for clipping the polygons to fit
inside the current viewport (whose location and size are available in
PDINFO).

Because Autodesk products have limited RDCPOLY polygons to three vertices
or less, to date, some drivers do not correctly handle polygons with more
than three vertices.

The controlling application fills in all members of this packet. The ADI
driver treats it as read-only.

History
-------
Introduced in ADI 3.0 to support AutoShade. Its use for DEV_RC drivers in
display mode was added in ADI 4.2.

Declaration
-----------
#define RDCPOLY  2013        /* Continuous color polygon */

struct rd_cpoly {
    ushort flags;            /* Flags */
    struct rd_rgb colour;    /* Fill color */
    struct rd_rgb ecolour;   /* Edge color */
    real shadef;             /* Shading factor */
    short nvert;             /* Number of vertices total */
    scrcoord vx[10];         /* Next 10 vertices */
    scrcoord vy[10];
    real sf[10];             /* Shade factor at each vertex*/
};

struct rd_rgb {
    double  r, g, b;
};

Description
-----------
Each RDCPOLY packet can pass a maximum of 10 polygon vertices to the
driver. If the polygon to be rendered contains more than 10 vertices, the
remaining vertices are passed to the driver by additional RDCPOLY packets.

The flags member is a 16-bit, bit-coded field. The top 10 bits are reserved
for invisible edges. Currently defined bits for flags are as follows:

Table 8-5. Values for RDCPOLY.flags

Mnemonic  Value  Meaning if Set
RF_MORE  0x1  Additional vertices to send
RF_CONT  0x2  Continuation of previous call
RF_LEFT  0x4  Image intended for left eye
RF_RIGHT  0x8  Image intended for right eye
RF_SF  0x10  Shade factors specified

The RF_MORE flag is set if additional RDCPOLY packets are required to pass
additional polygon vertices to the driver.

The RF_CONT flag is set if the current RDCPOLY packet is a continuation of
a previous RDCPOLY packet.

The top 10 bits (bits 6 through 15) of RDCPOLY.flags are used to indicate
which edges of the polygon should not be drawn in ecolour. Each of these
bits corresponds to an edge defined by (vx[i], vy[i]) to (vx[i+1],
vy[i+1]). If colour and ecolour are equal, the driver should ignore the
invisible edges, since any border it draws is invisible.

For example, if flags bit 6 is set, the edge from (vx[0], vy[0]) to (vx[1],
vy[1]) should not be drawn. If flags bit 7 is set, the edge from (vx[1],
vy[1]) to (vx[2], vy[2]) should not be drawn. If flags bit 8 is set, the
edge from (vx[2], vy[2]) to (vx[3], vy[3]) should not be drawn, and so
forth.

The members colour and ecolour are structures of type rd_rgb that specify
the RGB components of the polygon. The colour member specifies the polygon
face color, and the ecolour member specifies the polygon edge color. In the
current implementation, these two members are always equal so no edge
outlining needs to be performed. However, ecolour is used whenever the
nvert member is equal to one or two.

The shadef member is the shading factor to be applied to the basic color of
the polygon face. Values for shadef are within the range specified by the
minshade and maxshade members of the RDCRANGE packet.

The color components used to draw the polygon face are calculated by
multiplying the red (rd_rgb.r), green (rd_rgb.g), and blue (rd_rgb.b)
components in colour and ecolour by the shade factor, shadef. Colors are
expressed in this form so that faces with common source color can be
identified.

The nvert member contains the total number of vertices in the polygon, not
the number of vertices contained in the vertex list (unless the total
number of vertices in the polygon is 10 or less).

The members vx[] and vy[] can contain up to 10 vertices for each RDCPOLY
packet.

If multiple RDCPOLY requests are issued to the driver to pass a complete
polygon, the driver must keep track of the number of vertices passed with
each RDCPOLY packet to determine the number of RDCPOLY calls required to
complete the polygon, as well as the number of vertices it receives in the
last RDCPOLY packet. The last RDCPOLY request issued for a given polygon
always has the RF_MORE flag cleared (0).

Members shadef and sf[] are for optional smooth shading, a variation of
Gouraud shading. The smooth shading factors are made available only to
continuous-color devices that either do not support the scanline interface,
or that set the RF_SMOOTHFAC flag in the RDINIT packet. If the driver sets
RF_SMOOTHFAC, RDCPOLY packets include shade factors for each vertex.

Here is how AutoShade does smooth shading:

1)        Smooth shading goes through a complete mesh, calculating each
face's normal. Then, for every vertex for each face, AutoShade finds all
the surfaces adjacent to the current vertex.

  * utoShade takes the dot product of the current face normal with the
adjacent face's normal, and if the dot product is less than the threshold,
it is remembered (otherwise, it is ignored).

  * his process is repeated until all adjacent face's normals are either
ignored or remembered.

  * ext, the vertex's normal is averaged with the adjacent surface normals
to get the current vertex's normal. (This produces different normals for
each vertex in a face, compared to flat shading where each face has one
normal.)

2)        Next we calculate each vertex's shading factor with the vertex
normal in smooth shading. For example, each vertex has a different shading
factor.

3)        When outputting a face (triangles) we interpolate shading factors
between vertices, and the surface is smoothed when it is rendered.

Here is the difference between Smooth Shading and Gouraud Shading: in
Gouraud shading, shading factors are not calculated in step 2, but in step
3. Surface normals, interpolated between vertices and shading factors, are
then generated from each normal at the pixel level.

In a way, Gouraud shading does a better approximation than smooth shading,
but it takes more time and more memory to remember each vertex's normal.

Two special cases exist where your driver might receive an RDPOLY packet,
but you do not draw a polygon:

1) If the nvert member is one, a single pixel is drawn with the color
specified in ecolour at coordinates (vx[0], vy[0]).

2) If the nvert member is two, a vector is drawn with the color specified
in ecolour from coordinates (vx[0], vy[0]) to (vx[1], vy[1]).

If colored light sources are present, they are reflected in the r, g, and b
components of the colour and ecolour members.

AutoShade Versions 1.0, 1.1, and 2 and AVE Render never send polygons with
more than 3 vertices. However, this might change in the future.

AVE Render and AutoShade apply smooth shading only to meshes and only
during fast or full shade operations, when the user has turned on the
smooth shading option in the AutoShade Expert Specifications or AVE
Render's Preferences dialogue box.



8.6.6 RDCRANGE
==============

Purpose
-------
Color range for continuous-color devices.

Limitations
-----------
Can be sent in display mode to DEV_RC drivers that set the DI_CPOLY flag in
PDINFO.iflags. Can also be sent in full-screen rendering mode to DEV_RC,
DEV_RD and DEV_RH drivers that report rd_info.ncolour as zero.

RDCRANGE must be sent before any RDCPOLY packets are sent.

The controlling application fills in all members of this packet. The ADI
driver treats it as read-only.

History
-------
Introduced in ADI 3.0 to support AutoShade. Its use for DEV_RC drivers in
display mode was added in ADI 4.2.

Declaration
-----------
#define RDCRANGE 2012      /* Continuous color range */

struct rd_crange {
    real minshade;         /* Minimum shade multiplier */
    real maxshade;         /* Maximum shade multiplier */
    short rstretch;        /* Contrast stretch requested */
    struct rd_rgb bcolour; /* Background color request */
    real ambient;          /* Ambient contribution */
};

struct rd_rgb {
    double  r, g, b;
};

Description
-----------
If the ncolour member was set to zero in the RDINIT reply packet, the
device is treated as a continuous-color device in full-screen rendering
mode, causing the RDCMAPB, RDCMAP, RDCMAPE, and RDPOLY packets not to be
sent.

In this case, the RDCRANGE packet replaces the RDCMAPB, RDCMAP and RDCMAPE
packets, and the RDCPOLY packet is sent instead of RDPOLY.

If PDINFO.ncolour was set to zero, the device is treated as continuous-
color by AVE Render for the purposes of rendering in a display viewport.
RDPOLY requests are never made, but palette mapping requests are still made
to modify some Proteus dialogues.

The fields minshade and maxshade specify the range of floating-point
shading factors passed to subsequent RDCPOLY calls.

If the user has requested that the contrast in the picture be stretched to
use all the device's dynamic range, the rstretch member contains a nonzero
value. Otherwise, it contains the value zero.

Prior to version 2, AutoShade did not do contrast stretching for continuous-
color devices. AutoShade Version 2 provides this service. Therefore,
AutoShade Version 2 always sets the rstretch flag to FALSE, to indicate
that the driver should not do its own contrast stretching. Likewise, 3D
Studio v1 and v2 always set rstretch to FALSE. AVE Render also sets
rstretch to FALSE.

The bcolour member is a structure of type rd_rgb that contains three
components: r, g, and b. These components specify the user's requested
background color as light intensities from zero to one. For example, black
is represented by all three values equal to zero, white by all three values
equal to one, and yellow by "r" and "g" equal to one, with "b" equal to
zero. This form of floating-point color specification is used throughout
for continuous-color drivers, thereby allowing any possible color to be
specified.

Member ambient is used to pass the ambient light level chosen by the user
(which forms the base from which contrast stretching starts). Refer to
"Formula for Computing the Shading Factor" in appendix A of the AutoShade
User Guide (version 1.0 and 1.1) and chapter 6 of the AutoShade Version 2
User Guide.

The earliest versions of AutoShade did not pass the ambient member, and
most drivers just assumed a reasonable constant value (perhaps 0.2).



8.6.7 RDEND
===========

Purpose
-------
Indicates that the rendering process is complete, and triggers a return to
the mode from which rendering was started with RDSTART.

Limitations
-----------
Can be sent to DEV_RC drivers in rendering mode only. Can be sent to DEV_RD
and DEV_RH drivers (in rendering mode).

It is best to use RDSTART and RDEND packets in matching pairs. In other
words, applications should avoid sending two RDSTART packets without an
intervening RDEND, and likewise should not send RDEND unless an RDSTART has
preceded it.

Secondary applications must be careful to leave a DEV_RC driver in display
mode before yielding control back to AutoCAD.

AVE Render can issue RDSTART in text mode. In that case, RDEND leads back
to the text screen. Note that PGOGRAPH, PGOTEXT, and PGOTEXTU are illegal
in rendering mode.

The controlling application fills in all members of this packet. The ADI
driver treats it as read-only.

History
-------
Introduced in ADI 3.0 to support AutoShade. The notion of entering
rendering from text mode and hence returning to text mode at RDEND was
introduced in ADI 4.2 for AVE Render.

Declaration
-----------
#define RDEND  2003

struct rendreq {
    short rfunc;    /* RDEND */
};

Description
-----------
In general, AutoShade attempts to terminate a rendering initiated by an
RDSTART packet with a matching RDEND packet. However, it is possible that
multiple RDSTART calls might be issued without matching RDEND packets. It
is also possible that multiple RDEND packets might be sent that do not
correspond to matching RDSTART packets.

If you are a single-screen driver (sharing display and rendering on a
single screen on a nonwindowing platform), when your driver receives this
packet it should switch the display from rendering mode to display mode.
The screen configuration is indicated by the RF_SINGLSCR flag (bit 0) in
the flags member in the RDINIT reply packet. On windowing operating
systems, the user is left in control of the stacking order of the rendering
and display windows.

AVE Render adds a new twist to RDEND. The Render command can be issued from
the AutoCAD text screen. In this case, RDEND must lead back to the text
screen and not the display screen. In other words, ADI 4.2 drivers should
return on receipt of RDEND to the mode from which RDSTART was issued.

Many single screen drivers save the image (if any) on the rendering screen
in a file before switching to the display screen. This makes it easy to
restore the rendering on a RDSTART with RF_VIEW set.

An AutoShade V2 single-screen driver should save the last rendering image
so it can be restored on FLIPSCREEN (RDSTART with RF_VIEW set) and so the
image can be read by the RDRSLINE packet (probably without restoring it to
the screen). You can save the last rendering image in memory by using
malloc() or by saving it in a file.

3D Studio (v1.0 and v2.0) don't request contrast stretching, and they don't
set RF_VIEW. Thus, 3D Studio previous renderings won't be restored on
FLIPSCREEN.

In a single-screen configuration, if the RF_REDRAWSCR flag was set in the
RDINIT reply packet (the user has indicated that a flipscreen operation
requires a redraw), the RDEND packet signals such an operation.

If the driver does not always save the contents of the display screen
before switching to rendering on receiving an RDSTART, the user should set
RF_REDRAWSCR by (by answering Yes to the question, "Does flipscreen require
redraw?") and AutoShade redraws its menu bar and screen border, but not the
wireframe image.

See Also
--------
RDINIT, RDSTART, RDRSLINE



8.6.8 RDETAIL
=============

Purpose
-------
Configuration packet for hardcopy devices.

Limitations
-----------
This packet should be sent only to DEV_RH drivers. It is the primary
application's responsibility to use the information returned in this packet
to configure an output port for the rendering.

The controlling application fills in all members of this packet. The ADI
driver fills in every member except new.

History
-------
Introduced in ADI 4.1 for use with AutoShade 2.0 and 3D Studio 1.0.

Declaration
-----------
#define RDETAIL  2017

struct rhcudetail {
    short new;          /* new configuration? */
    short type;         /* Serial, Parallel, HPIB etc. */
    short baud;         /* Baud rate */
    short parity;       /* Parity */
    short data;         /* Data bits/frame */
    short stop;         /* Stop bits/frame */
    char handshake;     /* Hardware, XON/XOFF etc. */
};

Description
-----------
The RDETAIL packet is sent at configuration time by AVE Render, AutoShade,
and Autodesk 3D Studio for hardcopy devices.

When the controlling product sends the RDETAIL packet, the new member is
set to either zero or one. If new is TRUE (1), it is a first-time
configuration, and the rest of the members hold garbage. If this is a
reconfiguration, new member is set to FALSE (0), and the old configuration
values are passed to the driver in the rest of the members for
modification.

Your driver is responsible for returning the structure that makes up the
RDETAIL packet (struct rhcudetail) with all the structure members filled
in. Symbolic constants for many possible values are defined in the header
file rdadi42.h.

Member type indicates the type of interface supported by your device. If
you do not want to use the controlling product's I/O, return NODEVICE in
member type. AutoShade and 3D Studio accept multiple device type bits in
this member; these products ask the user if the rendering hard copy device
is connected to a serial or parallel port or if rendering to a file is
desired.

AVE Render does not provide this service. A DEV_RH must use dispatcher
services to find out if file output or port output is desired. If output
through a port is selected, and more than one type of port is possible, the
driver must use ciotype() to find out from the user which type of port has
been selected and must set at most a single device type bit in the type
member. AVE Render makes an ADS request to AutoCAD and AutoCAD asks the
user which port of the selected type the device is using. If the user has
selected file output, the DEV_RH should set RF_FILEOUT in RDINIT and use
the resulting RDFNAME packet to solicit a filename for the output file. AVE
Render and AutoCAD then open the desired file and send rhsend() data to the
file.

Table 8-6. Values for RDETAIL.type

Mnemonic  Value Meaning if Set
NODEVICE  0x0  Product's I/O services not used
SERIAL  0x1  Device uses serial interface
PARALLEL  0x2  Device uses parallel interface
FILEOUTPUT 0x100 Driver wants file output

If it is possible to configure your device for serial communication, you
must indicate the baud rate, parity, number of stop bits, and handshaking
method that the controlling product can expect.

The baud member should be initialized with the literal baud rate. For most
platforms, these are the valid baud rates: 50, 75, 110, 134, 150, 200, 300,
600, 1200, 1800, 2400, 4800, 9600 and 19200. Note that some DOS systems
have UART chips that might be unreliable at 19200.

Table 8-7. Values for RDETAIL.parity

Mnemonic  Value Meaning if Set
PARITY_NONE  0x0  No parity
PARITY_ODD  0x1  Odd parity
PARITY_EVEN  0x2  Even parity
PARITY_MARK  0x3  Mark parity
PARITY_SPACE 0x4  Space parity

Table 8-8. Values for RDETAIL.stop

Value Meaning if Set
0x1  One stop bit
0x2  Two stop bits

Table 8-9. Values for RDETAIL.handshake

Mnemonic  Value Meaning if Set
HANDSHAKE_XONXOFF  0x0  XON/XOFF handshake
HANDSHAKE_HARDWARE  0x1  Hardware handshake
HANDSHAKE_NONE  0x2  No flow control
HANDSHAKE_BOTH  0x3  Both hardware and XON/XOFF

Values used in RDETAIL.handshake and RDETAIL.parity are defined in
adihport.h.

Prior to AVE Render, rhsend() on 386 always enforced hardware handshaking
and never supported XON/XOFF. In AVE Render, rhsend() honors the handshake
flags in DETAIL, allowing for hardware handshaking and/or XON/XOFF.

On UNIX platforms prior to AVE Render, it was possible to enable hardware
handshaking (if supported on the particular UNIX platform) or XON/XOFF, but
not neither or both. In AVE Render you can select neither or both.

Your driver must return rdcudetail with members type, baud, parity, data,
stop, and handshake properly filled in, even if this is a reconfiguration
and there is no change in these members.



8.6.9 RD_FGRAB
==============

Purpose
-------
Lets an application request frame capture.

Limitations
-----------
If the RI_FRAME_GRABBER bit is set in the dflags_1 field of RD_INFO, then
the driver can grab video frames. The host application might send RD_FGRAB
during execution time. The application can then use RD_INFO to learn the
size and depth of the bitmap image grabbed; RDRCMAP packets (with
RF_CMFGRAB set) can be sent to read the frame grab palette if it is a
mapped palette, and RDRSLINE packets (with RF_SLFGRAB set) can be sent to
read scanlines from the grabbed image.

The application fills in all members. The ADI driver can modify member
status.

History
-------
Added in ADI 4.2.

Declaration
-----------
#define RD_FGRAB  2056

struct rd_fgrab {
    ushort flags;               /* Requests */
    ushort reps;                /* Successive frame grabs */
    ushort status;              /* Driver returns status here */
};
Description
-----------
The host program requests a frame grab by sending RD_FGRAB with the flags
and reps members filled in:

RF_WAIT_VSYNC 0x1 /* Start at vertical sync */ RF_AVERAGE 0x2 /* Average
successive frames */

If no flags bits are set, the driver is expected to grab a single frame,
starting immediately.

If the RE_WAIT_SYNC flag is set, the grab starts at the next vertical sync.
This flag is set only if the driver set RI_WAIT_VSYNC capability flag is in
RD_INFO.

If the RF_AVERAGE flag is set, the reps member tells the driver how many
successive frames to grab and average.

The driver returns GOOD in member status if the grab was successful and BAD
if it failed. After a successful grab, the image can be read by the host
program by successive RDRSLINE requests with a new bit, RF_SLFGRAB, set.
The usual x, y, and len parameters specify the portion of the grabbed image
to be returned. If the driver is for a paletted device, the host product
can read the grabbed image's palette by using RDRCMAP, setting a new bit
RF_CMFGRAB in the flags field of the packet.

RD_FGRAB is not yet used by any Autodesk product.



8.6.10 RDFNAME
==============

Purpose
-------
Passes an output filename to the driver.

Limitations
-----------
RDFNAME can be sent only in display mode, before the switch to rendering
mode. It can be sent to DEV_RC, DEV_RD, and DEV_RH drivers.

The application fills in all members. The ADI driver can modify members
flags and ftitle.

History
-------
Added in ADI 3.0 to support AutoShade. Note that the behavior of AVE Render
differs from previous products if the user cancels out of the filename
dialogue.

Declaration
-----------
#define RDFNAME  2011      /* User-supplied filename */
#define MAXFNAME 70

struct rd_fname {          /* Filename */
    ushort flags;
    char fname[MAXFNAME];  /* Name entered by user */
    int errmsg_offset;     /* Offset to error msg buffer */
    char ftitle[MAXFNAME]; /* Title for another request */
};

Description
-----------
Drivers that do not create files can ignore this packet. All Autodesk
products that support rendering use a dialogue box-based user interface. No
provision exists for a rendering driver to directly solicit a filename from
the user. RDFNAME is an indirect method of accomplishing this. It allows an
ADI driver to pass information to the Autodesk product, which is then used
to construct a dialogue box that solicits the filename. The result is
returned to the ADI driver.

The RDFNAME packet is used to pass an output filename to the driver for its
own use. This call occurs while still in display mode after the user has
requested a rendering, but before the RDSTART packet is sent.

If the user picked the Record item from the AutoShade display menu,
AutoShade first prompts for the name of the recording file. Following this
(or if the user did not select Record), AutoShade issues a series of
RDFNAME calls to let the driver obtain from the user a filename to use
during the rendering process. If the driver's purpose is to write an output
file, Record mode is probably superfluous and should be disabled by setting
the RF_FILEOUTPUT bit flag in the RDINIT reply packet.

The member flags is a 16-bit, bit-coded field used to control the flow of
information between AutoShade and the driver. Currently defined bit flags
are as follows:

Table 8-10. Values for RDFNAME.flags

Mnemonic  Value  Meaning if Set
RF_TITLE  0x1  AutoShade requests a title string from the driver
RF_CANCEL  0x2  User canceled filename request
RF_RECORDING 0x4  AutoShade performs file output during rendering
RF_GETFNAME  0x8  AutoShade should prompt user for filename
RF_ERROR  0x10  AutoShade should display alert box with error message

The first RDFNAME call has the RF_TITLE bit flag set, indicating that
AutoShade is requesting a title for its filename dialogue box and that the
fname[] field does not yet contain a filename pointer. If the driver does
not need a filename, it should simply ensure that the RF_GETFNAME flag is
clear and return to AutoShade; no further RDFNAME packets are sent for that
rendering.

If the driver needs a filename, it should indicate this by setting the
RF_GETFNAME bit flag in the reply packet. If a custom dialogue title is
desired, the driver should store the title string (a null-terminated ASCII
string not exceeding 70 characters in length) in the ftitle[] member of the
reply packet and set the RF_TITLE bit flag to signal that a title is
supplied. For example, the PostScript rendering driver supplies the title,
"Create PostScript output file." If the driver returns with the RF_GETFNAME
flag set, but the RF_TITLE flag clear, AutoShade uses the default dialogue
title.

Assuming that the RF_GETFNAME flag was set in the reply packet, AutoShade
asks the user for the filename and issues a second RDFNAME packet, passing
to the driver the filename provided by the user. If the user canceled out
of the dialogue box, the RF_CANCEL flag is set for this packet, and the
driver should just clear all flag bits and return.

AutoShade (v1 and v2) would continue to render after RF_CANCEL was returned
to the driver. AVE Render terminates the rendering immediately if the
driver doesn't set RF_ERROR. AVE Render terminates the rendering after
displaying the requested alert box if RF_ERROR is set by the driver.

If the driver receives an RDFNAME request packet with neither the RF_TITLE,
nor RF_CANCEL flags set in the flags member, the fname[] field contains the
filename string entered by the user. The filename does not normally include
an extension, so the driver should expect to add one. However, the driver
should never change or add to the string passed by AutoShade! If this is
necessary, your driver should first copy the string to its own local space
and edit it there. The driver should then attempt to open the file.

If the driver is unable to open the file, you should place an error message
in the buffer whose offset from *cbufadr is in the errmsg_offset member,
and set flag bits RF_ERROR, RF_TITLE, and RF_GETFNAME in the reply packet
to instruct AutoShade to display the error message in an alert box and
again ask the user for a filename. In this case, the title string should be
supplied again in ftitle[].

The RF_RECORDING bit flag is set by AutoShade to inform the driver that
AutoShade is performing output to a recording file during the rendering
process. The driver can ignore this bit, but should not alter it.

If an error message is needed, it should be a null-terminated ASCII string.
The string can contain multiple lines (embedded newline characters). No
single line can exceed 70 characters in length and the entire error message
cannot exceed 15 lines.

The error message might be too large to fit in the main packet buffer to be
passed back to AutoShade in the normal fashion. Therefore, AutoShade
provides an offset relative to *cbufadr to the start of a buffer where you
can place an error message string. The offset is in the member
errmsg_offset.

Notice how rendering file output is handled differently from plot file
output. In the case of plotting, we encourage drivers to use ppsend() to
hand off the output duties to AutoCAD. AutoCAD takes care of redirecting
this output to a file if the user requests file output.

AutoShade and 3D Studio do not offer this service for ADI rendering
hardcopy drivers. The driver is expected to handle file output locally. The
service provided by AutoShade or 3D Studio is simply the solicitation of
the output filename.

AVE Render, on the other hand, provides access to the rhsend() dispatcher
request, and thus provides I/O services comparable to those provided for
plotters.



8.6.11 RD_INFO
==============

Purpose
-------
Allows primary and secondary applications to get additional information
about a driver's rendering capabilities. For DEV_BI drivers, allows
successive bitmap inputs to have different sizes, color depths, an so on.

Limitations
-----------
RD_INFO can be sent to any ADI 4.2 rendering driver (DEV_RD, DEV_RH, or
DEV_RC) at any time. If the RD_INFO packet is sent at configuration time or
before RDINIT, it is simply a request for information from the driver. If
it is sent after RDINIT, the driver should notice and honor the pflags
field.

All ADI 4.2 DEV_RD, DEV_RH and DEV_RC drivers are required to support this
packet.

The controlling application fills in member pflags. The ADI driver should
fill in every other member.

History
-------
Added in ADI 4.2

Declaration
-----------
#define RD_INFO 2057

struct rdinfo {
    unsigned long pflags;        /* Requests from product */
    unsigned long dflags_1;        /* Driver capabilities */
    unsigned long dflags_2
    unsigned long flags_3d;
    double phys_x, phys_y;        /* Physical output size */
    ushort phys_unit;           /* INCH, FOOT, METER, etc */
    scrcoord bi_xdots, bi_ydots;  /* Image size in pixels */
    ushort pixwid, pixhgt;                /* Aspect ratio */
    ushort bi_ddepth;       /* Bitmap color depth in bits */
    short bi_mapdepth;      /* # of bits of palette depth */
    short npages;            /* Number of rendering pages */
    short nlights;             /* Number of light sources */
};

Description
-----------
RD_INFO is used to let drivers know more about the controlling product's
intentions and to allow the controlling product to learn more about the
driver's capabilities in rendering mode. For a DEV_RC, the driver should
respond with rendering mode capabilities only; PDINFO is used to inquire
about display mode capabilities.

The Autodesk product or ADS application fills in the pflags field to tell
the driver what to expect from the product. These are read-only flags from
the driver's point of view.

Table 8-11. Values for RD_INFO.pflags

Mnemonic  Value  Meaning
RI_FAST_VIDEO  0x1  Host can call video funcs
RI_BATCH_POLY  0x2  Polys come in batches
RI_XPARENT_ALPHA 0x4  Alpha means transparency
RI_ZBUF_ALPHA  0x8  Alpha means Z depth
RI_GAMMA_CORRECT 0x10  Product offers to gamma correct
RI_ABS_NORMAL  0x20  Bogus normals, use abs value

Fast Video
----------
The RI_FAST_VIDEO flag has been reserved for use with possible future
extensions to rendering ADI that would use far calls for very high speed
operations in a manner analogous to the use of FASTDRAW for AutoCAD vector
drawing. Not yet implemented.

Fast Polygon Mode (RI_BATCH_POLY)
---------------------------------
This has been done on UNIX platforms to speed up the rendering process. As
hardware performance increases, the overhead of sending single polygon
packets becomes the limiting factor. This is not yet implemented on non-
UNIX platforms.

Alpha Channel Use
-----------------
Rendering drivers have a flag (RF_SL32BIT in RDINIT.flags) that indicates
that the driver can accept 8-bit alpha-channel data along with 24-bit RGB
data per pixel. However, there are two uses for alpha-channel data:
transparency and z-buffer depth. Two flags indicate how the product wants
the driver to interpret alpha channel data: RI_XPARENT_ALPHA and
RI_ZBUF_ALPHA.

If neither bit is set, the alpha channel is to be ignored.

If RI_XPARENT_ALPHA is set by the product, the driver should interpret the
alpha channel value as a transparency value, with larger values indicating
that more background should be allowed to show through. If the driver can't
do this, it should clear the RI_XPARENT_ALPHA flag to inform the product
that it is unable to operate in this mode.

If RI_ZBUF_ALPHA is set by the product, the driver should interpret the
alpha channel value as a Z depth value, with larger values indicating
greater distance from the camera. If the driver can't do this operation, it
clears the RI_ZBUF_ALPHA bit to notify the product.

Gamma Correction
----------------
If RI_GAMMA_CORRECT is set, the Autodesk product can interact with the user
to solicit and apply gamma correction to renderings before they are sent to
the driver. This informational bit might be set by a future Autodesk
product.

RI_ABS_NORMAL
-------------
This flag is set if the current rendering has random polygon normals. If
the driver can do so, it should take the absolute value of all polygon
normals to force them to some semblance of sanity. This is of interest only
to 3D rendering drivers.

Table 8-12. Values for RD_INFO.dflags_1

Mnemonic  Value  Meaning
RI_RENDERER  0x1  Can render to screen
RI_FRAME_GRABBER  0x2  Can frame grab
RI_BI_ONLY  0x4  Bitmap input only device
RI_FILM_RECORDER  0x8  Outputs to film recorder
RI_PALETTE_ANIMATION  0x10  Can do palette animation
RI_RENDERMAN  0x20  Renders RIB files
RI_BITMAP  0x40  Handles bitmap files
RI_BS_DEV_RC  0x80  Renders in viewport
RI_WAIT_VSYNC  0x100  Can start at vertical sync
RI_HAS_UINFO  0x200  Driver has a UINFO packet
RI_NO_GAMMA  0x400  Don't want host gamma
RI_IMAGE  0x800  An image is present
RI_SCANNER  0x1000  DEV_BI is a scanner

DEV_BI Bitmap Input Devices
---------------------------
DEV_BI is not yet implemented by any Autodesk product.

A new DEV_BI device type has been added for ADI 4.2. A DEV_BI can input
bitmapped images into a local image buffer and then lets the Autodesk
product access the image via RDRSLINE and RDRCMAP packets. An RD_INFO
packet can be sent to a DEV_BI to see if it has an image in the buffer
(indicated by the presence of RI_IMAGE) and to learn the size, aspect
ratio, color depth, and so on, of the image.

A DEV_BI can be:

RI_FRAME_GRABBER  a video frame grabber

RI_BITMAP           a bitmap file input driver

RI_SCANNER          a scanner

A DEV_BI can also have other capabilities: it might be able to output
bitmap files (as a DEV_RH) or it might be a display and or renderer as in
the case of a frame grabber that has a frame buffer. The proper combination
of DEV_ flags is reported by such devices in the edevent struct.

Because a DEV_BI can handle images of varying size and color depth, we
can't expect the information returning in RDINIT to remain constant. A
bitmap file reader, for example, might read successive files of differing
sizes and color depths. Hence the three members described below:

The bi_mapdepth member specifies the palette depth of the bitmap image A
bi_mapdepth of 0 indicates that the image is true color, that is, there is
no palette.

The bi_ddepth member reports the number of bits of color data per pixel.
This would be 8 for a 256-color device; it might be 24 for a true color
device.

The bi_xdots and bi_ydots fields are used to report image size in pixels,
while the pixwid and pixhgt fields are used to report aspect ratio. If the
aspect ratio is unknown it should be reported as 0:0.

Two fields are provided for devices for which physical media size makes
sense (film recorders and scanners are possible examples). The members
phys_x and phys_y specify the physical size of the image (as currently
configured) and the phys_unit member specifies the units of measurement
used for phys_x and phys_y. These fields are meaningless if RI_NONE is
reported, indicating that physical size is not specified.

Table 8-13. Values for RD_INFO.phys_unit

Mnemonic  Value  Meaning
RI_NONE  0x0  No size is reported
RI_INCH  0x1  Size is in inches
RI_MILLIMETER  0x2  Size is in millimeters

Palette Animation
-----------------
The RI_PALETTE_ANIMATION flag identifies renderers with true mapped
palettes in display mode. Vendors with true color boards lacking palettes
in display mode have implemented DEV_RC drivers that have had problems with
3D Studio code, which expects to be able to do palette animation for the
materials editor.

Frame Grabber Capability Flags
------------------------------
The RD_INFO members related to frame grabbing are examined by the product
only if RI_FRAME_GRABBER is set in dflags_1.

If both RI_FRAME_GRABBER and RI_BI_ONLY are set, the device is only a frame
grabber and not a renderer. If RI_FRAME_GRABBER is set and RI_RENDERER is
set, the device is a renderer as well as an image capture device.

Drivers that set the RI_WAIT_VSYNC flag are reporting the capability of
waiting for vertical sync before starting a frame grab.

Frame grabbers must be able to process the new packet RD_FGRAB, described
later in this document.

UINFO Capability (not yet implemented)
--------------------------------------
Some devices can use a UINFO packet. If the driver sets RI_HAS_UINFO, then
the application can have a menu item that the user can select for
information about the driver. The UINFO packet can be used to inform a user
of such things as currently loaded film type or speed in a film recorder.

No Gamma
--------
If RI_NO_GAMMA is set, the driver is telling the Autodesk product not to
attempt gamma correction. This might be set by a driver for a device that
has its own gamma correction procedures.

Member dflags_2
---------------
The dflags_2 member is reserved for future use.

3D capability flags
-------------------
The flags_3d member reports on optional driver abilities to process 3d
floating point polygons (discussed in detail elsewhere). These flags are
used by AVE Render.

Table 8-14. Values for RD_INFO.flags_3d

Mnemonic  Value  Meaning
D3_FULL  0x1  Can do full screen 3D operations
D3_WIRE  0x4  3D wireframes with hidden line removal
D3_FLAT  0x8  Flat shading
D3_GOURAUD_NORM 0x10  Color interpolation for PNPOLY3s
D3_GOURAUD_COL  0x20  Color interpolation for PCPOLY3s
D3_AMBIENT  0x40  Ambient light type supported
D3_DIRECTED  0x80  Directed light type supported
D3_POINT  0x100  Point light type without shadows supported
D3_SPOT  0x200  Spotlight type supported
D3_MATL  0x400  Understands material properties
D3_MIXED  0x800  Can mix rendering modes
D3_PHONG  0x1000  Normal interpolation for PNPOLY3s
D3_OVFLAT  0x2000  Can override between single-normal and normal/vertex
shading
D3_OVWIRE  0x4000  Can override between solid shading and wireframes
D3_OVNORMS  0x8000  Can override between normal/vertex shading models
D3_SEGMENTS  0x10000 Can maintain a 3D segmented display list

npages
------
The npages member specifies the number of rendering pages available, just
as the PDINFO npages member does. If more than one page is reported
available for the currently configured mode, the driver is expected to
respond to the PVPAGE packet (specified elsewhere in this document). If a
driver supports more than one rendering mode in the current configuration
(e.g., both 3D and 2D), and if the different modes have different numbers
of pages available, the value reported in npages is the smallest number
available in any mode for this configuration.

nlights
-------
The nlights member specifies the number of light sources the driver can
support when doing 3D rendering.



8.6.12 RDINIT
=============

Purpose
-------
Initialize the rendering driver. Returns information to the controlling
application about the driver's capabilities in full-screen rendering mode.
With a DEV_RC, these can be quite different from display mode abilities
reported in PINIT and PDINFO.

Limitations
-----------
Can be sent to DEV_RC drivers in Display or rendering mode. Can be sent to
DEV_RD and DEV_RH drivers.

The RDINIT packet is sent to the driver with members rfunc and flags
initialized by the controlling application. All other members should be
filled in by the driver and returned.

RDINIT can be sent more than once to a driver (this allows secondary
applications to send RDINIT to get rendering capability information from a
driver and allows applications to reconfigure drivers).

RDINIT should always follow RDCFGREC. For ADI 4.2 drivers, RDINIT should
follow the sequence: RDWHO, RDLANG, RDCFGREC.

The controlling application fills in members flags and adiversion. The ADI
driver fills in every field except adiversion. See notes below regarding
which flag bits the ADI driver can modify.

History
-------
Introduced in ADI 3.0 to support AutoShade.

Declaration
-----------
#define RDINIT  2001   /* Initialize rendering device */
#define MAXINITNAME 66

struct rd_init {     /* Init; also used for RESIZE packet */
    ushort flags;           /* Initialization flags */
    scrcoord xdots, ydots;  /* Total screen size */
    ushort pixwid, pixhgt;  /* Pixel width and height */
    short ncolour;          /* Number of rgb color values */
    ushort maxintens;       /* Maximum intensity */
    ushort nshades;         /* Number of shades per color */
    char name[MAXINITNAME]; /* Driver name string */
    short adiversion;       /* ADIRPKTLEVEL */
};

Description
-----------
Because RDINIT can be sent more than once to ADI 4.2 drivers, you should
use an internal state flag to keep from performing one-time operations more
than once.

RDINIT is the signal for a driver to check to see if the rendering device
is present. For dual screen systems, it is an appropriate time to put the
rendering screen into rendering mode if it isn't already. Single screen
drivers should only do a presence check. RDINIT is not a clear screen
request. RDINIT does not supply information about a DEV_RC's display
capabilities, PDINFO fills that function.

Following are descriptions of each struct rd_init member. The structure is
declared and the flag mnemonics are #defined in the header file rdadi42.h.

ushort flags
------------
The flags member is a 16-bit, bit-coded field. Currently defined bit flag
values and their meanings are listed in table 5.7. Full descriptions of the
mnemonics follow the table. The bit flag symbolic constants (mnemonics) are
defined in the header file rdadi42.h.

Your driver should only change the bits defined in table 5.7, leaving the
rest unchanged. (Some are used by the controlling product for internal
purposes.)

Table 8-15. Values for RD_INIT.flags

Mnemonic  Value  Meaning if Set
RF_NOSLINE  0x0  No scanline capability
RF_SINGLSCR  0x1  Single-screen configuration (else dual-screen)
RF_REDRAWSCR  0x2  Redraw required on flip screen
RF_FAILINIT  0x4  Driver initialization failed
RF_FILEOUTPUT 0x8  Driver writes output to a file
RF_NAME  0x10  Driver returns name
RF_HARDCOPY  0x20  This is a hardcopy device
RF_DORESIZE  0x40  Device to be polled for size
RF_SMOOTHFAC  0x80  Send smooth shade factors
RF_SCANLINE  0x700  Scanline capability mask
RF_SL1BIT  0x100  1 bit/pixel output (monochrome)
RF_SL8BIT  0x200  8 bits/pixel (LUT) output
RF_SL24BIT  0x300  24 bits/pixel (b,g,r) output
RF_SL32BIT  0x400  32 bits/pixel (b,g,r, alpha)
RF_SLREAD  0x800  Driver can return scanline data as well as accept it.
Clear if write-only.
RF_SLORDERED  0x1000 Send scanline data in order from top to bottom of
image.
RF_MAPPEDPAL  0x2000 Mapped display palette
RF_BRESENHAM  0x4000 Driver uses same fill algorithm as AutoShade.

RF_SINGLSCR and RF_REDRAWSCR (set by application, read-only by driver)
----------------------------------------------------------------------
The RF_SINGLSCR and RF_REDRAWSCR flags are set by AutoShade in accordance
with information provided by the user during configuration and can be
examined by the driver if desired.

The RF_SINGLSCR flag is set if the user configured AutoShade for single-
screen operation, where the display device is also used for color
renderings. In this case, the driver must not switch to rendering mode
until it receives an RDSTART packet.

In a single-screen configuration, the RF_REDRAWSCR flag is set if the user
indicated that a Flipscreen operation requires a redraw. An RDEND packet
signals such an operation. AutoShade never saves the image from either the
display screen or the rendering screen, but if RF_REDRAWSCR was set, it
clears the display screen and redraws the borders and menu bar whenever the
user flips from the rendering screen to the display screen.

If the user indicates that no redraw is necessary for a Flipscreen, the
rendering is left on screen until a new wireframe image is drawn. This
implies that the driver has retained the menu bar on screen. Wireframe
images are preceded by a call to clear the display screen. Your driver's
instructions to the user should indicate how she should answer the redraw
on flipscreen question.

It is the driver's responsibility to save and restore the screen images on
a Flipscreen, if necessary.

AVE Render doesn't pay attention to RF_REDRAWSCR.

RF_FAILINIT (set by application, can be cleared by driver)
----------------------------------------------------------
Your driver should clear the RF_FAILINIT flag upon successful
initialization. If the driver detects an error during the initialization,
it should return with RF_FAILINIT set and AutoShade aborts. (A bug in
AutoShade v2 causes it to ignore RF_FAILINIT and 3D Studio v2.0 also
ignores RF_FAILINIT.)

RF_FILEOUTPUT (can be set by driver)
------------------------------------
Your driver should set the RF_FILEOUTPUT flag if the driver's purpose is to
write to an output file (such as a PostScript file) rather than to a
hardware device. When this bit is set, the Record item on the AutoShade
Display menu is grayed out so that the user cannot activate Record mode. A
RDFNAME packet is sent later to allow your driver to solicit a filename
from the user.

RF_HARDCOPY (can be set by application, cleared by driver on error)
-------------------------------------------------------------------
The RF_HARDCOPY bit is used for both input and output. On input, AutoShade
indicates whether it wants a hardcopy driver. On output, the driver sets it
to the appropriate value (in the unlikely event the driver can do either
one, it knows which duty it is supposed to perform).

RF_SMOOTHFAC (can be set by driver)
-----------------------------------
If the RF_SMOOTHFAC flag is set by the driver, it is a signal to AutoShade
or AVE Render that the driver can do smooth shading.

AutoShade or AVE Render uses polygon normals to compute smooth shading
factors at each polygon vertex. These shading factors are passed to the
device with each polygon. Only continuous-color devices can do smooth
shading (see the RDCPOLY packet). In other words, drivers that set
RF_SMOOTHFAC must also report ncolour = 0.

Note that RF_SMOOTHFAC lets the driver do smooth shading only when
AutoShade would normally do smooth shading internally. This means during
fast or full shade operations on meshes when the user has turned on the
smooth shading option in the AutoShade Expert Specifications dialogue box.

RF_SCANLINE and RF_NOSLINE (not flags; these are masks)
-------------------------------------------------------
The RF_SCANLINE and RF_NOSLINE masks indicate either scanline capability or
not, respectively. These bit masks can be used to test for the specific
scanline capabilities indicated by bit flags in the RDINIT packet. Note
that RF_SCANLINE and RF_NOSLINE are not flags.

If your driver has scanline read or write capabilities, you must set one
and only one of the four flags: RF_SL1BIT, RF_SL8BIT, RF_SL24BIT, or
RF_SL32BIT.

RF_SL1BIT (can be set by driver)
--------------------------------
RF_SL1BIT indicates 1-bit-per-pixel output. (note: 1-bit Scanline mode is
not yet supported by AutoShade)

RF_SL8BIT (can be set by driver)
--------------------------------
RF_SL8BIT indicates 8-bits-per-pixel output. Drivers that set RF_SL8BIT
must report 0 < ncolour.

RF_SL24BIT (can be set by driver)
---------------------------------
RF_SL24BIT indicates 24 bits per pixel, one byte for blue, one byte for
green, and one for red from left to right. Drivers that set RF_SL24BIT must
set ncolour = 0.

RF_SL32BIT (can be set by driver)
---------------------------------
RF_SL32BIT indicates 32-bits-per-pixel output: one byte blue, one byte
green, one byte red, and one byte alpha channel from left to right. Drivers
that set RF_SL32BIT must set ncolour = 0.

The alpha channel is defined in Autodesk RenderMan and TGA standards (the
percentage of the pixel covered by the generated image, compared to how
much is used for antialiasing calculations output when merging multiple
images).

RF_SLREAD (can be set by driver)
--------------------------------
The RF_SLREAD capability is used by AutoShade to let the user save
renderings in TGA or TIFF formats. The RF_SLREAD flag is set if the driver
can return scanline data as well as accept it, and clear if the driver is
write- only. This capability is used by AutoShade to let the user save
renderings in TGA or TIFF file formats. Autodesk 3D Studio makes additional
use of this scanline read capability.

RF_SLORDERED (can be set by driver)
-----------------------------------
The RF_SLORDERED flag is set if the driver cannot accept scan line data in
random order. This forces AutoShade to convert the scanline data to one and
two vertex polygons if scanline data are not ordered. These polygons are
not ordered.

At one time, AutoShade used single vertex polygons only for Mandelbrot
display, and a special case handler was included in an early VGA driver.
Now, drivers that set RF_SLORDERED must be more careful, especially if they
do dithering, to be sure that single vertex polygons get correct color
handling.

This is likely to greatly slow down output and therefore you shouldn't set
RF_SLORDERED if your device can handle the data in random order.

RF_MAPPEDPAL (set by product, can be cleared by driver)
-------------------------------------------------------
When the Autodesk product sends the RDINIT packet, the bit flag
RF_MAPPEDPAL indicates whether a mapped palette is required in display
mode. This is the only RDINIT flag bit that inquires for display mode
information.

It is all right for a driver to use continuous color in rendering mode even
if RF_MAPPEDPAL is set by the controlling application; this flag only
requests a mapped palette for display mode.

If the product sends RF_MAPPEDPAL cleared to zero, a mapped palette is not
required in display mode. If the flag is set, the product requires the use
of a 256-color mapped palette for display purposes. If your driver cannot
operate in this mode, it is not usable. Autodesk 3D Studio sets
RF_MAPPEDPAL when it is configured for a DEV_RC.

You should return RF_MAPPEDPAL equal to zero (cleared) if your driver
cannot use a mapped palette, and set it if your driver can use a mapped
display palette.

Note that if the driver is a continuous-color rendering device, and is a
DEV_RC, it still has to handle the 256- color palette mapping packets
RDCMAPB, RDCMAP, RDCMAPR, and RDCMAPE to establish the display palette.

RF_BRESENHAM (can be set by driver)
-----------------------------------
The RF_BRESENHAM bit flag is set if your driver uses the same fill
algorithm as AutoShade (Bresenham algorithm). Refer to the sample RDPTARGA
Targa rendering driver file, rdptarga.c, for an example of the RF_BRESENHAM
flag being set and the use of the AutoShade fill algorithm. Some of our
other sample drivers do not use the AutoShade fill algorithm and hence do
not set RF_BRESENHAM.

Polygon Fill and Scan Line Support
----------------------------------
It is recommended that your rendering driver support both polygon fill and
the scanline interfaces if possible. All Autodesk RenderMan and Autodesk 3D
Studio output is via scanline. AutoShade can send either polygons or
scanlines. Hardware that can do fast polygon fills gets best performance by
accepting polygons from AutoShade.

If your driver supports both scanline output and polygon output, does not
set the RF_SMOOTHFAC bit flag, and sets the RF_BRESENHAM bit, it can
receive a mixture of scanline data (for portions of an image where smooth
shading is relevant, such as meshes) and simple polygons without shading
factors (for portions of the image where flat shading is adequate).

Pixel-off-by-one Errors
-----------------------
Your choice of smooth shading algorithm and how you elect to handle polygon
fill and the scanline interface has the potential to produce pixel-off-by-
one errors.

These errors can happen when your driver is sent some polygons as scanlines
and some adjoining polygons as polygons. If your driver does not use
exactly the same polygon fill algorithm as AutoShade, problems arise when
the polygons filled by the two different algorithms meet.

Drivers that do their own smooth shading (indicated by setting the
RF_SMOOTHFAC flag) should not have any problems since those drivers receive
all polygons. Drivers that set the RF_SLORDERED flag should also be safe
from any problems as well, because they are sent one and two vertex
polygons in place of scanlines.

Drivers that can handle polygons but that do not do smooth shading might
have pixel-off- by-one errors. Because it is so common for drivers to use
fill algorithms different from the one used by AutoShade, the default case
is for AutoShade to scanline convert all questionable polygons. If you are
confident that your driver uses the same fill algorithm as AutoShade, you
can set the RF_BRESENHAM flag. This speeds up rendering by sending polygons
whenever possible.

Smooth Shading
--------------
Here is a table showing the interaction of the three bit flags when smooth
shading is enabled (when smooth shading is disabled all drivers are sent
polygons, and when Autodesk RenderMan is active all drivers are sent
scanlines).

Table 8-16. Data sent by smooth shading according to flag values

RF_BRESENHAM RF_SLORDERED RF_SMOOTHFAC Smooth Shading Sends
0  0  0  All scanlines
1  0  0  Scanlines and polygons
0  1  0  All polygons
1  1  0  All polygons
x  x  1  All polygons

Your driver should support scanline output. This is the only form of output
used by Autodesk RenderMan and Autodesk 3D Studio. It is also the only way
a 256-color device can accept smooth shaded images from AutoShade.

A 256 (or less)-color device can get smooth shaded data from AutoShade V2
by supporting the optional scanline capability. Or, it can fool AutoShade
by pretending to be a continuous- color device and then take on the job of
collapsing the color palette down to a manageable number of colors and
shades. A 256-color device that does not support scanline capabilities is
sent only simple polygons for flat (painter's algorithm) shading.

scrcoord xdots, ydots (filled in by the driver)
-----------------------------------------------
The values returned in xdots and ydots specify the size (in pixels) of the
graphics area of the screen. The xdots member is the horizontal size of the
graphics area of the screen, and ydots is the vertical size of the graphics
area.

These values determine the units used to specify polygon vertices passed to
the driver by the RDPOLY packet request. Vertex values range from zero to
(xdots minus one) and zero to (ydots minus one) with (0,0) representing the
lower-left corner of the screen.

ushort pixwid, pixhgt (filled in by the driver)
-----------------------------------------------
The pixwid member specifies the horizontal physical spacing between pixels,
and pixhgt specifies the vertical physical spacing between pixels. The
ratio of pixwid to pixhgt is used to correct the aspect ratio so that the
horizontal and vertical measurements of objects drawn on screen are equal.

On a device with square pixels, pixwid and pixhgt should both be one (1).
On devices with different X and Y scales, pixwid and pixhgt should be set
based on the physical screen measurement in each direction divided by the
number of pixels on the appropriate axis.

Only the ratio of pixwid to pixhgt is significant, so any desired units can
be used. However, since changes in the second decimal place of the ratio
(hundredths) results in visible changes on screen, the values should be as
accurate as possible.

The values returned in pixwid and pixhgt must be greater than zero and less
than 32767.

See the discussion on pixwid and pixhgt in the "Screen Size" section of
chapter 6, "Display ADI."

short ncolour (filled in by the driver)
---------------------------------------
The ncolour field specifies the total number of entries in the color look-
up table (LUT) and determines the number of colors that can be
simultaneously displayed on screen. For example, the IBM Professional
Graphics Controller supports 256 simultaneous colors. Values used to index
into the color look-up table (i.e., the value assigned to the code variable
in the RDCMAP request) must be within the range zero to (ncolour-1).

The valid range of values for ncolour is from 0 to 32767. AutoShade masks
the value passed in ncolour with 0x8000. Although drivers can report
ncolour as greater than 256, paletted drivers do not have a means of
displaying scanline data with more than 256 colors. Thus most devices with
more than 256 colors report ncolour as zero.

If the driver returns ncolour equal to zero, AutoShade treats the device as
a continuous-color device, and never sends the RDCMAPB, RDCMAP, RDCMAPE, or
RDPOLY packets. Instead, the RDCRANGE request is issued at the start of a
rendering and RDCPOLY packets are sent.

If your rendering device is capable of more than 256 RGB shades, you might
want to treat it as a continuous-color device. The PostScript driver is an
example of a continuous-color driver (due to the large number of monochrome
dithering patterns available). Also, you might specify continuous color if
your device does not use RGB and the continuous-color representation eases
the translation to your device's color system.

ushort maxintens (filled in by the driver)
------------------------------------------
This field is ignored if ncolour is 0. It is meaningful only for paletted
devices reporting 0 < ncolour < 32768.

The maxintens field specifies the maximum value that can be assigned to the
red, green, or blue components of a color look-up entry. For example, the
values assigned to the red, green, and blue variables passed to the driver
via the RDCMAP packet are within the range zero to maxintens. Similarly,
AutoShade returns the color palette RGB values within the range zero to
maxintens, up to a maximum of 255. For the IBM Professional Graphics
Controller, the value assigned to maxintens is 255.

ushort nshades (filled in by the driver)
----------------------------------------
This field is ignored if ncolour is 0. It is meaningful only for paletted
devices reporting 0 < ncolour < 32768.

The nshades member specifies the number of shades available per color,
which in turn determines the permissible number of intensity values for
each RGB gun.

For most devices, nshades equals (maxintens+1). However, some devices allow
a smaller number of shades per RGB gun than the value assigned to
maxintens. For example, for the IBM PGC, nshades is 15 even though
maxintens is 255. The nshades member can also be expressed as nshades
equals two raised to the n power (2^n), where n is the number of bits in a
color look-up entry. Thus a 6-bit device would report nshades as 64 and an
8-bit device would report 256.

char name[] (filled in by the driver)
-------------------------------------
The driver should return a text string in the reply packet's name[] member.
The text string is a null-terminated ASCII string that is written at the
beginning of all rendering recording files to identify the driver used to
produce the file. If the driver has several possible rendering modes with
different color depths, this string should include enough information to
uniquely specify the mode and color depth. AutoShade refuses to replay a
file unless the current name string matches the name string recorded in the
file.

For example, the IBM PGC driver returns a pointer to the string, "IBM
Professional Graphics Controller (PGC)." The string must not exceed 65
characters in length. If an identification string is being returned, the
driver should also set the RF_NAME bit flag in the flags member in the
reply packet.

short adiversion (filled in by the Autodesk product)
----------------------------------------------------
The adiversion member is sent from AutoShade with the current value of the
ADI interface level (symbolic constant ADIRPKTLEVEL). The low four bits of
this number indicate minor changes in the ADI interface, the upper bits
indicate major changes that will probably make the product incompatible
with older ADI drivers. The ADI interface level (ADIRPKTLEVEL) is defined
in the rdadi42.h header file.

Autodesk 3D Studio uses a special form of combined rendering and display
driver that can be configured either for AutoShade operation (where the
display driver uses the regular AutoCAD color palette), or for a new mode
of operation where the display driver uses a palette defined by the
rendering color mapping packets RDCMAPB, RDCMAP, and RDCMAPE. AVE Render
also uses an extended version of this DEV_RC interface.

See Also
--------
RDTERM, RDCPOLY, RDCMAP, RDCMAPB, RDCMAPE



8.6.13 RDLANG
=============

Purpose
-------
Allows rendering drivers to know the language and code page being used by
AutoCAD. This is helpful in internationalization of drivers.

Limitations
-----------
RDLANG should be the second packet (following RDWHO) sent to ADI 4.2 and
later rendering drivers at both CFG and XQT time. This packet should not be
sent to pre-ADI 4.2 drivers. It is sent only by applications that are about
to send CFG packets. This means the AVE Render sends RDLANG to a DEV_RC
driver if it is being shared by AutoCAD as a display driver, during
rendering configuration. AVE Render also sends it to stand-alone rendering
drivers.

The controlling application fills in all members of this packet. The ADI
driver treats it as read-only.

History
-------
The use of RDLANG for rendering drivers was added in ADI 4.2 to support
release 12.

Declaration
-----------
#define RDLANG 2055   /* Rendering drivers (rdadi42.h) */

struct pklang {
    short pfunc;                  /* RDLANG */
    short cchar;                  /* Check mark value */
    short options;                /* Option flag bits */
    short maxchar;          /* Highest numbered char code */
    char  lang[MAX_LAN + 1];      /* Language ID string */
    char  code_page[MAX_COP + 1]; /* Code page name */
};

#define MAX_LAN 8           /* Defined in path.h */
#define MAX_COP 20

Description
-----------
The ADI interface was originally designed to handle only 128 ASCII
characters, with character 128 having the special meaning of a check mark
for dialogue boxes. As overseas editions of AutoCAD have begun to use ADI
drivers, it has become necessary to extend the range of characters sent to
display drivers. Due to conflicts with some countries' character definition
conventions, these "8-bit font" versions of AutoCAD redefine the check mark
character to another value, often 255. PLANG is sent to display drivers to
negotiate the handling of this issue. In ADI 4.2 PLANG is also sent to
plotter and digitizer drivers and RDLANG is sent to rendering drivers as an
informational packet - AutoCAD does not examine the packet returned by the
driver.

Table 8-17. Values for RDLANG.options

Mnemonic  Value Bit Meaning if Set
FF_8BIT  0x1  0  FONT8BIT is active.
FF_SYSMENU 0x2  1  System has a menu bar.

The FF_SYSMENU option bit is used on some windowing platforms to inform a
display driver that a system menu bar is supported.

The RDLANG.lang and RDLANG.code_page members were introduced in ADI 4.2.
They inform the driver of the command language and code page that AutoCAD
believes are currently in use. These are derived from the software
environment and not from polling the keyboard or other hardware. The values
for RDLANG.lang and RDLANG.code_page are the same as for the PLANG packet
members of the same names. See the PLANG packet description in chapter 6,
Display ADI, for the values tables for these members.

Ctype Functions
---------------
We have added new dispatcher functions to export ctype functions that have
been correctly internationalized. See chapter 4, ADI Dispatcher, for
complete information on ctype functions.

3D Studio and AutoShade do not support the ctype dispatcher functions.
AutoCAD Release 12 does, thus conferring this support on AVE Render.



8.6.14 RDPOLY
=============

Purpose
-------
Pass polygon vertices to a paletted driver for filling.

Limitations
-----------
Can be sent to DEV_RC drivers in rendering mode. Can also be sent to DEV_RD
and DEV_RH drivers in rendering mode. In any case, RDPOLY should be sent
only to drivers that report rd_init.ncolour as greater than zero; that is,
it should not be sent to continuous- color devices (which report ncolour as
0).

DEV_RC drivers that set PDINFO.ncolour > 0 and which set the DI_FLATPOLY
flag in PDINFO.iflags can be sent RDPOLY packets while in display mode.

Applications should not send RDPOLY packets before defining a palette with
RDCMAPB, RDCMAP, and RDCMAPE packets.

The coordinates vx and vy are in pixel coordinates with the origin at the
lower-left corner of the entire screen. In single viewport display
operations, the application is responsible for clipping the polygons to fit
inside the current viewport (whose location and size are available in
PDINFO). In all operations, the application is responsible for clipping the
polygon to fit onto the rendering screen.

Because Autodesk products have limited RDPOLY polygons to three vertices or
less, to date, some drivers do not correctly handle polygons with more than
three vertices.

The controlling application fills in all members of this packet. The ADI
driver treats it as read-only.

History
-------
Introduced in ADI 3.0 to support AutoShade. The extension of RDPOLY to
display mode for DEV_RC drivers was made in ADI 4.2.

Declaration
-----------
#define RDPOLY  2010

struct rd_poly {
    unsigned short flags;
    short colour;
    short ecolour;
    short nvert;
    short vx[10];
    short vy[10];
};

Description
-----------
AutoShade passes polygon vertices to the driver using the RDPOLY packet.

Each RDPOLY packet can pass a maximum of 10 polygon vertices to the driver.
If the polygon to be rendered contains more than 10 vertices, the remaining
vertices are passed to the driver by additional RDPOLY packets.

The member flags is a 16-bit, bit-coded field. The top ten bits are
reserved for invisible edges. Currently defined bits for flags are as
follows:

Table 8-20. Bit flag values for RDPOLY.flags

Mnemonic  Value Bit Meaning if Set
RF_MORE  0x1  0  Additional vertices to send
RF_CONT  0x2  1  Continuation of previous call
RF_LEFT  0x4  2  Image intended for left eye
RF_RIGHT  0x8  3  Image intended for right eye

The RF_MORE bit is set if additional RDPOLY packets are required to pass
additional polygon vertices to the driver. The last RDPOLY packet sent for
a given polygon always has the RF_MORE bit cleared.

The RF_CONT bit is set if the current RDPOLY packet is a continuation of a
previous RDPOLY packet.

The top 10 bits (bits 6 through 15) of rd_poly.flags are used to indicate
which edges of the polygon should not be drawn in ecolour. Each of these
bits corresponds to an edge defined by (vx[i], vy[i]) to (vx[i+1],
vy[i+1]). If colour and ecolour are equal, the driver should ignore the
invisible edges, since any border it draws is invisible.

For example, if flags bit 6 is set, the edge from (vx[0], vy[0]) to (vx[1],
vy[1]) should not be drawn. If flags bit 7 is set, the edge from (vx[1],
vy[1]) to (vx[2], vy[2]) should not be drawn. If flags bit 8 is set, the
edge from (vx[2], vy[2]) to (vx[3], vy[3]) should not be drawn, and so
forth.

The colour and ecolour members are the look-up table indices specifying the
colors to be used to fill the polygon and to draw its edges, respectively.
In the current implementation, the two are always equal so that no edge
outlining need be performed. However, ecolour is used whenever nvert is
equal to one or two.

The nvert member contains the total number of vertices in the polygon, not
the number of vertices contained in the vertex list (unless the total
number of vertices in the polygon is 10 or less).

The members vx[] and vy[] can contain up to 10 vertices for each RDPOLY
packet.

If multiple RDPOLY requests are issued to the driver to pass a complete
polygon, the driver must keep track of the number of vertices passed with
each RDPOLY packet to determine the number of RDPOLY calls required to
complete the polygon, as well as the number of vertices it receives in the
last RDPOLY packet.

Two special cases exist where your driver can receive an RDCPOLY packet,
but you do not draw a polygon:

1)        If the nvert member is one (1), a single pixel is drawn with the
color specified in ecolour at coordinates (vx[0], vy[0]).

2)        If the nvert member is two (2), a vector is drawn with the color
specified in ecolour from coordinates (vx[0], vy[0]) to (vx[1], vy[1]).

If the ncolour member was cleared (0) in the RDINIT reply packet, AutoShade
assumes that it is a continuous-color device and the RDCMAPB, RDCMAP,
RDCMAPE, and RDPOLY packets are never called. Instead, the RDCRANGE packet
replaces the RDCMAPB, RDCMAP, and RDCMAPE packets; and RDCPOLY replaces the
RDPOLY packet.

See Also
--------
RDCPOLY, RDINIT



8.6.15 RDRCMAP
==============

Purpose
-------
Reads color map entries from rendering and display drivers.

Limitations
-----------
Can be sent to DEV_RC drivers in display or rendering mode. RDRCMAP can
also be sent to DEV_RD and DEV_RH drivers in rendering mode if they set
RF_SLREAD in RDINIT.flags and if they report 0 < RDINIT.ncolour. Can be
sent to ADI 4.2 DEV_DS drivers in display mode.

Requests for logical color values can only be made of ADI 4.2 and later
DEV_DS and DEV_RC drivers. DEV_RD drivers can't satisfy this request since
it asks for display information.

The controlling application fills in all members of this packet. The ADI
driver modifies members red, green, and blue. If a logical color is
requested, the ADI driver also modifies member code to return the physical
ACI associated with the logical color. Applications can tell if the ADI
driver has satisfied the logical color request by noticing if the code
member has been modified.

History
-------
Added in ADI 4.1 to support AutoShade 2.0 and 3D Studio 1.0. The flag
RF_CMFGRAB was added in ADI 4.2. Also added in ADI 4.2: the requirement to
report on logical colors, and the requirement for support by all DEV_RC and
DEV_DS display drivers.

Declaration
-----------
#define RDRCMAP  2016
struct rd_cmap {          /* Colour map */
    short code;           /* Index */
    ushort red;           /* Red intensity */
    ushort green;         /* Green intensity */
    ushort blue;          /* Blue intensity */
    ushort flags;         /* Option flags */
};

Description
-----------
DEV_DS drivers are only expected to be able to read the display color map
and DEV_RD drivers are only expected to be able to read the rendering color
map.

The flags member is a bit-coded field that helps clarify how single-screen
systems should respond to the RDRCMAP packet. AutoShade can send RDRCMAP as
a response to its Save Image command if an 8-bit rendering device is
configured. The RDRCMAP packet is sent while the display screen is active,
but the AutoShade intends that the rendering color map be returned.

Table 8-21. Bit Flags for RDRCMAP.flags

Mnemonic  Value Meaning if Set
RF_CMREND  0x1  Read the rendering color map
RF_CMDISP  0x2  Read the display color map
RF_CMFGRAB 0x4  Return frame grab palette

The RF_CMREND flag makes this intention (that the rendering color map be
returned) explicit. A single-screen driver can return the rendering color
map from the last saved rendering image. Autodesk 3D Studio might call
RDRCMAP with the RF_CMDISP flag set, which would tell a driver to read the
display color map of a DEV_RC driver in display mode.

When a single-screen system is on the display screen, RF_CMREND refers to
the saved rendering image from the last RDEND, which would be restored on
RDSTART with RF_VIEW set.

If the controlling application fails to set any flag bits, your driver
should assume the operation requested is on the current color map; that is,
if the request arrives in display mode, the display palette should be read;
if the request arrives in rendering mode, the rendering palette should be
read.

The color map index to be read is in member code when the packet is sent to
your driver. Fill in the color values and return the packet with member
code unchanged.

Any undefined color should be returned with all three color members as zero
(0).

If the member code is sent to you as negative one (-1), this is a request
for your driver to return the number of initialized color map members. You
should return this value in members red, green, and blue, repeating the
value in each member.

If the member code is sent to you as a value ranging from -2 to MINLCOLOR
(see colours.h), this is a request to return the current RGB value and ACI
of the requested logical color. For example, the code value -2 is a request
to return the current graphic screen background color. You must return the
RGB values assigned to the requested logical color in members red, green,
and blue. You must also return the ACI (AutoCAD color index) of this color
in member code. This is used by AVE Render on UNIX platforms, and will be
used more extensively in the future. Note that if the user has associated a
logical color with an ACI above 15 on DOS platforms, the RGB value of the
logical color (and thus the value reported by RDRCMAP) changes if AVE
Render has modified the palette. All ADI 4.2 DEV_RC drivers must support
this extension to RDRCMAP. This request is meaningful only if RF_CMDISP is
set. It is also reasonable for AVE Render to request a DEV_RH's preferred
background color by issuing RDRCMAP with a code of -2, while RF_CMREND is
set.

Your driver must support this packet if it is an 8-bit (look-up table)
driver and it supports the RDRSLINE packet.

AVE Render sends RDRCMAP packets to examine a DEV_RC's default palette
mapping (before it downloads a palette). Drivers must supply valid
responses for all palette entries, including the first 16 and the logical
colors. AVE Render expects ALL DEV_RC drivers to support these requests,
even those that report PDINFO.ncolour = 0.

For the sake of display (DEV_DS) driver authors, this packet has been
aliased as the display packet PRCMAP, with the structure pkcmap, defined in
dsadic42.h. This allows DEV_DS drivers to comply with the ADI 4.2
requirement to support this packet without having to include rdadi42.h. See
Chapter 6 for more details.



8.6.16 RDRHOPEN
===============

Purpose
-------
Tells a DEV_RH it is okay to start making rhsend() requests and passes an
idvc value to use in those requests.

Limitations
-----------
This packet can only be sent to ADI 4.2 and newer DEV_RH drivers. It can
only be sent at execution time, after an I/O port or file has been opened
for use by rhsend().

AVE Render fills in this packet. The ADI driver treats it as read-only.

History
-------
Introduced in ADI 4.2.

Declaration
-----------
#define RDRHOPEN 2054

struct rhopen {
    long idvc;
}

Description
-----------
This packet tells your driver that a device of the type you requested in
RDETAIL (at configuration time) has been opened for rendering hardcopy
output. Use the device descriptor handle, idvc, in your rdsend() requests
until you see an RDEND packet.

The idvc value is ephemeral. A new idvc value is be sent for every
rendering. It is valid only during that rendering. AVE Render invalidates
the handle when you return from processing the RDEND packet.

An idvc value of -1 indicates an error. An idvc value of 0 indicates an
uninitialized handle.



8.6.17 RDRSLINE
===============

Purpose
-------
Passes scanline data from the driver to the Autodesk product.

Limitations
-----------
Can be sent to DEV_RC drivers in display or rendering mode; or to DEV_RD
and DEV_RH drivers in rendering mode if they set RF_SLREAD in RDINIT.flags.
The color model to be used for scanline data in rendering mode is
determined by the RDINIT flags RF_SL1BIT, RF_SL8BIT, RF_SL24BIT, and
RF_SL32BIT. The color model for display mode scanline data is determined by
the PDINFO.iflags bits DI_R8BIT, DI_R24BIT, and DI_R32BIT.

3D Studio v1.0 always assumes a 6-bit deep palette and 8-bit scanline data
in display mode.

New applications must set flag bits to indicate from which buffer the
scanlines are to be read.

Note that there is a platform-dependent maximum allowable value for sdlen.
For P386 ADI 4.2 this maximum is PASSDATA_SIZE bytes (see the header file
rdadi42.h). Longer scanlines should be handled piecewise.

The controlling application fills in all members of this packet. The ADI
driver modifies member flags and the scanline data buffer pointed to by
rel_offset.

History
-------
Added in ADI 4.1 to support AutoShade 2.0 and 3D Studio 1.0. The flag
RF_SLFGRAB was added in ADI 4.2.

Declaration
-----------
#define RDRSLINE  2015

struct rd_sline {     /* Scan line data */
    ushort flags;     /* Flags */
    scrcoord x;       /* Start x */
    scrcoord y;       /* Start y */
    ushort xrpt;      /* Number of times to repeat data */
    ushort sdlen;     /* Number of bytes of data */
    int rel_offset;   /* Offset from cbufadr */
};

Description
-----------
RDRSLINE passes scanline data from the rendering driver to the controlling
product. This packet is only sent in rendering mode to drivers that set
RF_SCANLINE and RF_SLREAD in RDINIT.flags. If your driver is an 8-bit (look-
up table) driver, it must also support the RDRCMAP packet if it supports
the RDRSLINE packet.

DEV_RC drivers that set one of the flags DI_R8BIT, DI_R24BIT, or DI_R32BIT
in PDINFO are expected to handle RDRSLINE requests in display mode with the
flags bit RF_SLDISPLAY indicating that the display image is being
requested, using the display color model.

Drivers that support RDRSLINE enable AutoShade V2 to save raster image
files in various formats. AutoShade sends the packet with the members x, y,
sdlen, and sdata filled in. Your driver should return the data in the
buffer indicated by sdata or it should set the RF_SLFAILREAD bit in member
flags if it cannot. If there is no rendering image (or saved rendering
image in single-screen systems) it is advisable to return black for all the
requested pixels (in addition to setting RF_SLFAILREAD).

The sdlen field is a byte count, not a pixel count.

The following table shows the values for RDRSLINE.flags:

Table 8-22. Values for RDRSLINE.flags

Mnemonic  Value Meaning if Set
RF_SLFAILREAD 0x1  Set by the driver if a RDSLINE request failed
RF_SLRENDER  0x2  Scan line should be read from the rendering screen
RF_SLDISPLAY  0x4  Scan line should be read from the display screen of a
DEV_RC driver
RF_SLFGRAB  0x8  Return frame grab line

AutoShade typically sends the RDRSLINE packet while the display screen is
active.

The RF_SLRENDER and RF_SLDISPLAY flags allow AutoShade to unambiguously
request rendering scanline data while the display screen is active, still
leaving open the possibility of other products requesting display screen
scanline data. Old applications that fail to set any of the flag bits can
be assumed to be requesting rendering data.

An AutoShade V2 single-screen driver should have saved the last rendering
image so it can be restored on FLIPSCREEN (RDSTART) and so the image can be
read by the RDRSLINE packet (probably without restoring it to the screen).
You can save the last rendering image in memory by using malloc() or by
saving it in a file.



8.6.18 RDSTART
==============

Purpose
-------
Indicates the beginning of a new rendering. Triggers a switch to rendering
mode.

Limitations
-----------
Can be sent to any DEV_RD or DEV_RH driver while in display mode. Can be
sent to DEV_RC drivers in display mode only if the intent is that the
driver switch to full-screen rendering mode. RDSTART should not be sent to
a DEV_RC if rendering is to take place in display mode (e.g., in a
viewport).

AVE Render can send RDSTART while AutoCAD is in text mode if the user types
Render on the text screen. In that case, RDEND should lead back to the text
screen. Note that PGOGRAPH, PGOTEXT, and PGOTEXTU are illegal while inside
rendering mode. RDEND is the correct way to terminate rendering mode.

The controlling application fills in all members of this packet. The ADI
driver treats it as read-only.

History
-------
Added in ADI 3.0 to support AutoShade. The meaning of the RF_VIEW flag was
clarified in ADI 4.2.

Declaration
-----------
#define RDSTART  2002

struct rd_start {       /* Start rendering request */
    ushort flags;
};

Description
-----------
The RDSTART packet is passed to the driver every time a new full-screen
rendering is begun. RDSTART is not used for rendering in a viewport. When
the driver receives this packet, it should switch to the rendering screen.

If configured for single-screen operation, indicated by the RF_SINGLSCR bit
set in the RDINIT reply packet, the driver should switch the display from
display mode to rendering mode. This is not a request to clear the
rendering screen, even on single-screen systems. Single-screen drivers are
be sent either an RDCLEAR request or two large polygons to clear the
screen. Clearing it at RDSTART time just wastes CPU cycles.

Dual-screen systems should not clear the screen on receiving the RDSTART
packet. The Autodesk product calls RDCLEAR when it is time to clear the
screen. Some AutoShade V2 users might enter AutoShade with an image from
another application in the framebuffer with the intent of using the
AutoShade Save Image command to save the image in a supported format.

DEV_RH drivers should not clear their image buffer at RDSTART, they should
wait for RDCLEAR. The old sample PaintJet driver got away with doing this
incorrectly because AutoShade and AVE Render don't do merge operations for
paletted devices. A true color DEV_RH must be especially careful to follow
this rule, since merge operations are allowed for them.

On windowing operating systems, the user controls the stacking order of the
rendering and display windows.

Autodesk RenderMan does not issue RDCLEAR after RDSTART. Nevertheless,
drivers should not clear the screen on RDSTART. If Merge is not turned on,
Autodesk RenderMan sends two polygons to clear the area to be rendered
(which might be less than the full page or screen). If Merge is turned on
by the user, Autodesk RenderMan expects to be able to merge a new rendering
with the existing imagery on screen.

The flags member is a 16-bit, bit-coded options field that currently has
the following defined bit flags:

Table 8-23. Values for RDSTART.flags

Mnemonic  Value Meaning if Set
RF_VIEW  0x1  Restore last rendered image

The RF_VIEW flag indicates that this is the start of a rendering flipscreen
operation (triggered by the flipscreen key or by a mouse click), or it is
the start of a new rendering with MERGE turned on. If and only if the
RF_VIEW flag is set, rendering drivers should restore the last saved
rendering image (if any) on receiving RDSTART.

3D Studio (v1 and v2) never sets RF_VIEW, that is, 3D Studio never wants
the previous rendering restored on flipscreen.

In general, AutoShade attempts to terminate a rendering initiated by an
RDSTART packet with a matching RDEND packet. However, multiple RDSTART
calls might be issued without matching RDEND calls. Multiple RDEND calls
might also be issued that do not correspond to matching RDSTART calls
(e.g., during the AutoShade replayall operation).



8.6.19 RDTERM
=============

Purpose
-------
Indicates that all rendering has been completed.

Limitations
-----------
Can be set to any DEV_RD, DEV_RH, or DEV_RC driver. RDTERM should be the
last rendering packet sent to a driver.

RDTERM should not be sent by a secondary application to a driver that is
being shared by a primary application. For example, AVE Render does not
send RDTERM if it is using the AutoCAD combined rendering and display
driver (unless it is about to stimulate PKILL with the reinit setvar). It
can send RDTERM to a stand-alone rendering driver.

The controlling application fills in all members of this packet. The ADI
driver treats it as read-only.

History
-------
Introduced in ADI 3.0 to support AutoShade.

Declaration
-----------
#define RDTERM 2004

struct rendreq {
    short rfunc;    /* RDTERM */
};

Description
-----------
The RDTERM request indicates that all rendering is complete, and that the
driver can terminate the rendering process.

The RDTERM request also indicates that AutoShade is exiting to DOS. No
further rendering requests are issued during the current execution of
AutoShade.

See Also
--------
RDINIT



8.6.20 RDWHO
============

Purpose
-------
RDWHO lets ADI drivers know what application is executing them; it also can
let secondary applications know what ADI driver is currently running. It
has additional provisions for allowing ADI drivers to accept or reject
control by secondary application and it allows secondary applications to
clearly specify their mode of display operation.

Limitations
-----------
RDWHO is a rendering packet and can be sent to ADI 4.2 DEV_RD, DEV_RH, and
DEV_RC drivers (to configure the rendering mode part of the DEV_RC).

ADI 4.2 drivers expect the primary ADI 4.2 controlling application to send
PWHO as the first packet at configuration time and again as the first
packet at execution time. The application that loads an ADI driver is
primary for that driver (with the notable exception of TEE drivers, which
are secondary and should send RDWHO or PWHO only as bookends around
episodes of takeover of control).

RDWHO must be sent by any application about to send CFG packets to an ADI
rendering driver so the driver knows who is configuring it.

There are versions of RDWHO (called PWHO for other device types), with
different Packet codes but similar structures, for every device type
(display, digitizer, plotter, etc.).

RDWHO can be sent at any time.

Primary applications should fill in the following fields: pfunc, psize,
product, prod_version, adipktlevel, action, alias, serial, driver_path and
for UNIX platforms, cpid. Primary products should send PWHO as the first
packet at CFG time (with action WHO_CFG) and as the first packet at
execution time (with action WHO_XQT).

Secondary applications should fill in the following fields: pfunc, psize,
product, prod_version, adipktlevel, action, screen, serial, regapp_name
(for ADS applications), and cpid for UNIX platforms.

AVE Render fills in adipktlevel with the ADIRPKTLEVEL value defined for ADI
4.2 in rdadi42.h (3).

Applications that lack a serial number should stuff EOS into member serial.
Applications such as AVE Render that load a driver but do not support alias
device names should stuff 0 in member alias.

Note that it is incorrect for an application to send WHO_START twice
without an intervening WHO_END.

The controlling application fills in all members of this packet. The ADI
driver can modify members status and driver_name. On UNIX platforms, the
driver fills in dpid.

History
-------
This packet was added in ADI 4.2. The structure was modified several times
during ADI 4.2 development by adding new members and by changing ints to
longs.

Declaration
-----------
#define RDWHO 2058             /* See rdadi42.h and who.h */

struct pkwho {
    short pfunc;         /* RDWHO (for rendering drivers) */
    short psize;                             /* PKWHOSIZE */
    short product;                        /* Product code */
    short prod_version;      /* Revision level of product */
    short adipktlevel; /* ADI interface level for product */
    short status;        /* Driver can return status here */
    short cleanup;  /* Driver can return cleanup requests */
    short action;              /* App can request actions */
    short screen;             /* Display states requested */
    long alias;             /* Display driver alias index */
    char  serial[WHO_SERIAL_SIZE];     /* ASCIIZ serial # */
    char  regapp_name[WHO_REGAPP_NAME_SIZE];
    char  driver_name[DEVNAMSZ + 1];/* ASCIIZ driver name */
    char driver_path[MAXPATHLEN];   /* Where driver found */
#ifdef UNIX
    long cpid;      /* Controlling application's UNIX pid */
    long dpid;                       /* Driver's UNIX pid */
#endif /* UNIX */
};

#define PKWHOSIZE (sizeof(struct pkwho))
#define WHO_SERIAL_SIZE 32
#define WHO_REGAPP_NAME_SIZE 32

Description
-----------
RDWHO is sent by Autodesk products very early in configuration time with
WHO_CFG set and very early in execution time with WHO_XQT set. The idea is
to let drivers know what product is in control before the driver has to
respond to any requests from the product.

This packet is also sent by AutoCAD at an application's request (in
ads_adistart() or ads_adiend()). For DEV_RC drivers, it needs to originate
in AutoCAD core code so that AutoCAD can handle any requests the driver
might make.

The member pfunc is defined differently for each device type, in the C
header file for each device type (e.g., rdadi42.h, dgp.h, plp.h, etc.). The
structure definition for pkwho and the definitions for products and
versions are defined in a new C header file, who.h.

The product ID number will be unique for each Autodesk product. The header
file who.h defines these ID numbers. ID number zero will be reserved for
unknown (non-Autodesk) primary products.

Table 8-24. Values for RDWHO.product

Mnemonic  Value  Meaning
WHO_UNKNOWN  0  Unknown primary product
WHO_ACAD  1  AutoCAD
WHO_SHADE  2  AutoShade
WHO_SKETCH  3  AutoSketch
WHO_STUDIO  4  3D Studio
WHO_AME  5  AME
WHO_R12REND  7  AVE Render
WHO_AUNK  0x2000  Unknown ADS application
WHO_TUNK  0x4000  Unknown TEE application

Note that TEE applications cannot provide cleanup services.

The member prod_version is made up of two parts: the upper 8 bits form the
major version number, while the lower 8 bits form a minor version number.
Thus, the first release of AutoCAD Release 12 would be 0x100 while a second
update release would be 0x101. As each new product or version is designed,
the author makes a code submission to update who.h, thus reserving a
number.

Table 8-25. Sample prod_version values

Mnemonic  Value  Meaning
WHO_R12  0x100  For AutoCAD Release 12 initial release
WHO_AME2  0x100  AME 2.0

The adipktlevel is sent from the Autodesk product to the ADI driver,
indicating which ADI interface level the user has selected. For most types
of ADI there are two parallel numbering systems: intlevel and adipktlevel.
The intlevel numbers are an old system that proceeds sequentially. The
adipktlevel is a newer system with the lower 4 bits of the version
indicating minor revisions and the remaining bits indicating major version
changes.

The member status normally is returned as GOOD. If it is returned as less
than 0, the driver is indicating that it knows it cannot work with the
indicated product, version, serial number, and interface level.

Table 8-26. Values for the status member

Mnemonic  Value Meaning
GOOD  0  Can work with product
BAD  -1  Nonspecific failure
ADI_BAD_VERSION  -2  Incompatible ADI version
ADI_BAD_APP  -3  This driver won't work with this application
ADI_BAD_SERIAL  -4  Serial number violation
ADI_BAD_PROD_VER  -5  Incompatible product version

The product's serial number is appended to this packet as a null terminated
ASCII string. This allows vendors to easily lock their products to a single
serial number, if they like. Autodesk serial numbers are two ASCII integers
separated by a dash.

The member alias is filled in by AutoCAD at WHO_CFG and WHP_XQT time for
display drivers with an alias index. If the display driver has only one
device name, alias is zero. If the driver has more than one devname string,
AutoCAD returns the index of the selected devname.

The regapp_name member is for ADS applications, a null-terminated string
that is returned by the application in ads_regapp().

The driver_name field is filled in by the ADI driver to pass a null-
terminated ASCII string (the currently configured dev_name string from the
edevent struct) to any application (particularly secondary applications)
wanting to know the identity of the current driver.

The driver_path member is sent from the primary product (e.g. AutoCAD) to
inform the driver of the full path from which the driver was loaded. This
is filled in by the primary product at configuration time and at execution
time. RDWHO packets emitted by secondary applications won't have this
filled in.

The member cpid is used only on UNIX platforms; it passes the controlling
application's process ID to the driver. Both primary and secondary
applications are required to fill in cpid. The member dpid returns the
driver's UNIX process ID. UNIX digitizer and plotter drivers find that our
library code has filled in dpid by the time PWHO reaches the driver's code.
However, the driver can modify this value if necessary.

Table 8-27. Values for RDWHO.action

Mnemonic  Value Meaning
WHO_CFG  1  Indicates configuration time, main application
WHO_XQT  2  Indicates execution time, main application
WHO_START  3  Used by secondary app on first takeover
WHO_PAUSE  4  Temporary end of secondary application takeover
WHO_RESUME 5  Secondary application resumes control
WHO_END  6  Secondary application terminates

When the primary product (e.g., AutoCAD) starts up in configuration, it
sets action to WHO_CFG. When the primary product starts at execution time,
it sets WHO_XQT. If a secondary application, via a TEE driver or an ADS
link takes over an ADI driver temporarily, it sets the action member to
WHO_START in an RDWHO packet sent at its first takeover. At the end of its
takeover of the device, it sets action to either WHO_PAUSE or WHO_END. An
RDWHO packet with WHO_PAUSE tells the driver that the app plans to take
over again but is temporarily returning control to the primary application.
An RDWHO packet with WHO_END indicates that the secondary application does
not expect to take over again.

The screen member is used for PWHO for display drivers. It is zero for
RDWHO packets.

The cleanup member is used for PWHO for display drivers and is ignored in
the processing of RDWHO.



8.6.21 RDWSLINE
===============

Purpose
-------
Writes scanline data to the rendering driver.

Limitations
-----------
Can be sent to DEV_RC drivers in display or rendering mode. Can also be
sent to DEV_RD and DEV_RH drivers in rendering mode if they set one of the
bits in the RF_SCANLINE mask in RDINIT.flags. The Color mode to be used for
scanline data in rendering mode is determined by the RDINIT flags
RF_SL1BIT, RF_SL8BIT, RF_SL24BIT, and RF_SL32BIT. The color model for
display mode scanline data is determined by the PDINFO.iflags bits
DI_R8BIT, DI_R24BIT, and DI_R32BIT.

3D Studio v1.0 always assumes a 6-bit deep palette and 8-bit scanline data
in display mode.

New applications must set flag bits to indicate to which buffer the
scanlines are to be written.

Note that there is a platform-dependent maximum allowable value for sdlen.
For P386 ADI 4.2 this maximum is PASSDATA_SIZE bytes (see the header file
rdadi42.h). Longer scanlines should be handled piecewise.

The controlling application fills in all members of this packet. The ADI
driver treats it as read-only.

History
-------
Added in ADI 4.1 to support AutoShade 2.0 and 3D Studio 1.0.

Declaration
-----------
#define RDWSLINE  2014
struct rd_sline {        /* Scan line data */
    ushort flags;        /* Flags */
    scrcoord x;          /* Start x */
    scrcoord y;          /* Start y */
    ushort xrpt;         /* # of times to repeat data */
    ushort sdlen;        /* Number of bytes of data */
    int rel_offset;      /* Offset from cbufadr */
};

Description
-----------
RDWSLINE is used to pass scanline data from the controlling application to
the rendering driver. This packet is only received by drivers that set the
RF_SCANLINE bit flag in the RDINIT reply packet. The scanline data is in
the format requested by the driver at RDINIT time (1, 8, 24, or 32 bits per
pixel).

Member xrpt indicates the number of times the data are to be repeated, but
does not figure in the amount of data or number of pixels being
represented. This member is equal to one (1) unless the data are to be
repeated horizontally (as in outputting a constant color or a horizontally
repeating pattern).

Member sdlen is the total number of bytes of scanline data pointed to by
sdata. It is not a pixel count. In P386 ADI, member rel_offset is the
offset from *cbufadr to the start of the buffer holding scanline data.

The flags field is a 16-bit, bit-coded field with the currently defined
flags:

Table 8-28. Values for RDWSLINE.flags

Mnemonic  Value Meaning if Set
RF_SLRENDER  0x2  Scan line should be written to the rendering screen
RF_SLDISPLAY  0x4  Scan line should be written to the display screen of a
DEV_RC driver
RF_SLFGRAB  0x8  Write into frame grab buffer

If the controlling application doesn't set any of the flag bits, your
driver should assume that the "current" screen should be modified (e.g.,
the rendering screen if you are in rendering mode).

Bits in the RF_SCANLINE mask as defined in the RDINIT packet indicate the
format of the data in rendering replay (RND) file scanline packets.

The actual scanline data directly follows the packet in the RND file for
the number of bytes indicated in the sdlen member of the RDWSLINE packet.
The rel_offset member should be ignored in packets read from RND files.

See Also
--------
RDRSLINE, RDINIT



8.6.22 RPCFGREC
===============

Purpose
-------
Execution-time configuration packet that is sent before RDINIT.

Limitations
-----------
Must be sent early in execution-time (before RDINIT or RDSTART) to DEV_RC,
DEV_RD and DEV_RH drivers, by the rendering application in control during
rendering configuration time. The application must return the driver's
configuration record to it at this time.

Applications supporting ADI 4.2 should send RPCFGREC after RDWHO. The
controlling application fills in every member of this packet. The ADI
driver treats it as read-only.

History
-------
Added in ADI 4.1 to support AutoShade 386 v2 and 3D Studio v1.0.

Declaration
-----------
#define RPCFGREC 2059 /* Execution time config record */
struct rpkcfgrec {    /* Executor portion of adi driver */
    short pfunc;      /* RPCFGREC */
    short preclen;    /* Configuration record length */
    char paliasid;    /* Alias ID */
    char  pcfgrec[1];
};
Description
-----------
If your driver stored a configuration record at configuration time, it is
returned to you at execution time in this packet.

The alias ID (paliasid) is not yet implemented in P386 ADI. Your driver
should check the data returned by the RPCFGREC packet for validity. An
incomplete configuration by the user might result in garbage in this
record. It is good practice to include a sentinel you can test for.

RPCFGREC is guaranteed to be sent to your driver before the RDINIT packet.

See Also
--------
RPNEWCFG, RPCHGCFG, RPSHOWCFG



8.6.23 RPCHGCFG
===============

Purpose
-------
This packet is sent at configuration time if the user elects to change the
existing configuration.

Limitations
-----------
Can be sent only at configuration time, to DEV_RC, DEV_RD, and DEV_RH
drivers.

Applications that support ADI 4.2 can send RPCHGCFG at configuration time
RDWHO and after PLANG. The application is responsible for returning the
driver's existing configuration record in member pcfgrec.

The controlling application fills in every member of this packet. The ADI
driver can change preclen and pcfgrec.

History
-------
Added in ADI 4.1 to support AutoShade 386 2.0 and 3D Studio 1.0.

Declaration
-----------
#define RPCHGCFG  2061    /* Change configuration record */
/* RPNEWCFG, RPCHGCFG, and RPSHOWCFG all use this struct */

struct rpkconfig {
    short pfunc;          /* RPCHGCFG */
    short preclen;        /* Configuration record length */
    char  pcfgrec[1];     /* Private configuration record */
};

Description
-----------
RPCHGCFG, RPNEWCFG, and RPSHOWCFG all share a single packet structure. They
are all used at configuration time. If your driver is being called for
first-time configuration, RPNEWCFG is sent and you should return any
private configuration record (via member pcfgrec[]). Refer to the RPNEWCFG
packet description. These three packets (RPCHGCFG, RPNEWCFG, and RPSHOWCFG)
are only sent to protected-mode rendering and DEV_RC drivers.

If your driver has already been configured, you might receive the PCHGCFG
packet. This indicates that the user wants to go back through the
configuration dialogue, possibly answering differently.

Your driver is responsible for asking any questions of the user, collecting
and validating answers, and constructing the configuration record.

If your driver has already been configured, you might receive RPCHGCFG.
This indicates that the user wants to go back through the configuration
dialogue, possibly answering differently.

The RPSHOWCFG packet is an informational packet that passes your driver its
private configuration record (that you saved with RPNEWCFG or RPCHGCFG), so
you can show the user (on screen) the current configuration status. Note
that Autodesk controlling products ignore the contents of the configuration
record that are stored and retrieved for you.

Recall that you are limited to no more than 490 bytes for the configuration
record to be stored here by the product. If you need a larger configuration
record, you can use these tools to store the filename of a separate file,
which your driver can write and read to.

If a nonrecoverable error takes place during configuration, or if your
driver detects a <Ctrl-C> from the user, you should stuff zero in the
rpkconfig.rfunc member. This is recognized by the Autodesk product as a
signal to terminate.

Currently, AutoShade V2 does not let the user change an existing
configuration, hence, any change involves starting from scratch. So,
temporarily, your driver does not receive the RPSHOWCFG packet from
AutoShade.

A bug in Autodesk 3D Studio V1.0 limits the size of PCFGREC for 3D Studio
to the range from 1-100 bytes and a second bug causes Autodesk 3D Studio to
crash if you don't supply a value for PRECLEN from 1-100 because the
default value supplied by Autodesk 3D Studio is invalid.

Typically your configuration record is a structure. You can use the
Autodesk product dispatcher services described earlier to conduct your
dialogue with the user.

See Also
--------
RPCFGREC, RPNEWCFG, RPCHGCFG



8.6.24 RPNEWCFG
===============

Purpose
-------
Creates a new configuration record at configuration time.

Limitations
-----------
Can be sent only at CFG time, to DEV_RC, DEV_RD, and DEV_RH drivers.

Applications that support ADI 4.2 should send RPNEWCFG after RDWHO and
after PLANG.

The controlling application fills in every member of this packet. The ADI
driver can change preclen and pcfgrec.

Currently, AutoShade V2 does not let the user change an existing
configuration, hence, any change involves starting from scratch. So, for
the time being, your driver does not receive the RPSHOWCFG packet from
AutoShade.

History
-------
Added in ADI 4.1 to support AutoShade 386 2.0 and 3D Studio 1.0.

Declaration
-----------
#define RPNEWCFG  2060    /* New configuration record */
/* RPNEWCFG, RPCHGCFG, and RPSHOWCFG all use this struct */

struct rpkconfig {
    short pfunc;          /* RPNEWCFG */
    short preclen;        /* Configuration record length */
    char  pcfgrec[1];     /* Private configuration record */
};

Description
-----------
RPNEWCFG, RPCHGCFG and RPSHOWCFG all share a single packet structure. They
are all used at configuration time. If your driver is being called for
first-time configuration, PNEWCFG is sent.

You should return any private configuration record you want to save (via
pcfgrec[]) and the exact length of the record in bytes in preclen.

Your driver is responsible for asking any questions of the user, collecting
and validating answers, and constructing the configuration record. If your
driver has already been configured, RPCHGCFG is sent. This indicates the
user wants to go back through the configuration dialogue, possibly
answering differently.

The RPSHOWCFG packet is an informational packet that passes your driver its
private configuration record (that you saved with RPNEWCFG or RPCHGCFG), so
you can show the user (on screen) the current configuration status. Note
that Autodesk controlling products ignore the contents of the configuration
record that are stored and retrieved for you.

You are limited to less than 490 bytes for the configuration record to be
stored here by the product. If you need a larger configuration record, you
can use these tools to store the filename of a separate file, which your
driver can write and read to.

A bug in Autodesk 3D Studio V1.0 limits the size of PCFGREC for 3D Studio
to the range from 1-100 bytes and a second bug causes Autodesk 3D Studio to
crash if you fail to supply a value for PRECLEN from 1-100 because the
default value supplied by Autodesk 3D Studio is invalid.

If a nonrecoverable error takes place during configuration, or if your
driver detects a <Ctrl-C> from the user, you should stuff zero in the
rpkconfig.rfunc member. This is recognized by the Autodesk product as a
signal to terminate.

Typically your configuration record is a structure. You might use the
Autodesk product dispatcher services described earlier to conduct your
dialogue with the user.

See Also
--------
RPCFGREC, RPSHOWCFG



8.6.25 RPSHOWCFG
================

Purpose
-------
Displays current configuration status on screen.

Limitations
-----------
Can be sent only at CFG time, to DEV_RC, DEV_RD, and DEV_RH drivers.

Applications that support ADI 4.2 should send RPCFGREC after RDWHO.

The controlling application fills in every member of this packet. The ADI
driver treats it as read-only.

Currently, AutoShade V2 does not let the user change an existing
configuration, hence, any change involves starting from scratch. So, for
the time being, your driver does not receive the RPSHOWCFG packet from
AutoShade.

History
-------
Added in ADI 4.1 to support AutoShade 386 2.0 and 3D Studio 1.0.

Declaration
-----------
#define RPSHOWCFG 2062   /* Show configuration record */
/* RPNEWCFG, RPCHGCFG, and RPSHOWCFG all use this struct */

struct rpkconfig {
    short pfunc;         /* RPSHOWCFG */
    short preclen;       /* Configuration record length */
    char  pcfgrec[1];    /* Private configuration record */
};

Description
-----------
RPCHGCFG, RPNEWCFG, and RPSHOWCFG all share a single packet structure. They
are all used at configuration time. If your driver is being called for
first-time configuration, RPNEWCFG is sent and you should return any
private configuration record (via pcfgrec[]). Refer to the RPNEWCFG packet
description. These three packets (RPCHGCFG, RPNEWCFG, and RPSHOWCFG) are
only sent to protected-mode rendering and DEV_RC drivers.

If your driver has already been configured, you might receive the PCHGCFG
packet. This indicates that the user wants to go back through the
configuration dialogue, possibly answering differently. See the RPCHGCFG
packet description.

The RPSHOWCFG packet is an informational packet that passes your driver its
private configuration record (that you saved with RPNEWCFG or RPCHGCFG), so
you can show the user (on screen) the current configuration status. Note
that Autodesk controlling products ignore the contents of the configuration
record that are stored and retrieved for you.

See Also
--------
RPCFGREC, RPNEWCFG, RPCHGCFG


8.7 3D Rendering Interface
==========================

The 3D rendering packets described below can be used in two general modes.
AVE Render presently uses them in the immediate mode, with no segments and
no separate viewing transform. Polygons are sent in world coordinates in
this model.

The segmented model is likely to be used by Cyberspace.

The following table shows the packet codes for 3D operations (see
rcadi3d.h):

Table 8-29. 3D operation packet codes

Packet  Value  Description
PVIEW  79  Viewing transform
PORTHO  80  Orthographic projection
PPERSP  81  Perspective projection
POSEG  82  Open segment
PCSEG  83  Close current segment
PDSEG  84  Delete segment
PPOLY3  85  3D polygon
PNPOLY3  86  3D polygon with vertex normals
PCPOLY3  87  3D polygon with vertex colors
PVEC3  88  3D vector
PLIGHT  89  Define light source
PDLIGHT  90  Delete light source
PSETCOLOR  91  Set modal color
PSETMATL  92  Set modal materials properties
PMODEL  93  Set modal segment transform
PDRAWSEG  94  Draw segment
P3D  95  3D operation bookends
PBPOLY3  108  3D polygon batch structure

The GOURAUD_NORM shading model starts from PNPOLY3 packets and does color
interpolation. The GOURAUD_COL shading model starts from PCPOLY3 packets
and does color interpolation (ignoring light sources); this is useful for
internally illuminated objects. The PHONG shading model starts from PNPOLY3
packets and does normal interpolation (see Foley and van Dam, 2nd Ed.,
pages 736-739).

If a driver sets D3_MIXED, it can handle any combination of the shading
models whose capability flags are also set. Otherwise the driver can handle
only a single shading model in each frame.

If a driver sets nlights > 0, it can handle a total number of lights up to
nlights, with any mixture of the light types whose capability flags are
set.

Many of the new packets use these structures:

typedef int Segid;
typedef double Real;
typedef Real Vec3[3]; /*3D vector (for vertices and
                        normals)*/
typedef Real Mat44[4][4];
typedef struct
{
    short coltype;     /* RGB or index */
    union
    {
        Real rgb[3];
        long indx;
    } col_un;
} Color;

/* Values for Color.coltype */
#define D3COLOR_RGB   0
#define D3COLOR_INDEX 1

8.7.1 Color Notes
=================

RGB versus Mapped Palette
-------------------------
If we are operating in display mode, and the driver has reported in PDINFO
that it is capable of true color rendering in display mode, colors are RGB.
Otherwise they are paletted. If we are in rendering mode, the color system
is negotiated by RDINIT as usual.

If a paletted device has indicated that it supports materials properties,
and if the controlling product uses this capability, all 3D operations use
RGB color values; 2D operations will continue to use the device's palette.

Color by Polygon versus Color by segment instance
-------------------------------------------------
If the polygon packets have color values associated with them (PCOLOR flag
set), this controls. Otherwise color is by segment instance (from
PSETCOLOR). If a polygon packet contains PCOLORS color overrides, the
polygon does not have shading or materials properties applied to it.

8.7.2 Rendering Styles Supported
================================

These rendering styles are supportable with this ADI interface:

  * Wireframe without hidden line removal.

  * Wireframe with hidden line removal.

  * Flat - fnorm should reflect the face normal.

  * gouraud_norm - color interpolation of PNPOLY3 packets.

  * gouraud_col - color interpolation of PCPOLY3 packets.

  * Phong shading - normal interpolation of PNPOLY3 packets.

8.7.3 Typical 3D Operating Scenarios
====================================

These ADI extensions can be used by stand-alone applications as well as by
ADS applications.

8.7.3.1 Cyberspace Scenario
---------------------------

Following is a possible scenario for Cyberspace:

Load separate rendering driver.
Cyberspace now can send packets:
    RDINIT
    RDINFO - check on detailed capabilities, including npages.
    RDWHO
    RDSTART
    P3D
    set projection (either PORTHO or PPERSP)
    POSEG
    Many PSETMATL, PSETCOLOR, and POLY3 packets to send geometry.
    PCSEG
    ...
    POSEG
    Many PSETMATL, PSETCOLOR, and POLY3 packets to send geometry.
    PCSEG
    PLIGHT packets to place lights.
    PVIEW
    PVPAGE to set active & visible pages.
    then for (each segment) {
                PSETCOLOR
                PSETMATL
                PMODEL
                PDRAWSEG
         }
    PVPAGE to change visible page (makes image visible)
    ...

Note: Typically Cyberspace draws multiple instances of segments.

8.7.3.2 Scenario for AVE Render Running Single Screen
-----------------------------------------------------

ads_adiinfo()  ---  Get connection info about currently
                    installed driver.
ads_adistart() --- Starting bookend: causes AutoCAD to send
                   PWHO and PDINFO.
AVE Render now can send packets:
    PDINFO - Check on detailed capabilities.
    PCLEAR - Clear screen.
    P3D    - Clear z-buffer, set shading model.
    Set projection (either PORTHO or PPERSP).
    Set view (PVIEW).
    PLIGHT packets to place lights.
    Many POLY3, PSETMATL, and PSETCOLOR packets to render
    polygons in immediate mode.
    P3D    - Bookend.
    On the way back to AutoCAD...
    PPAL        (save palette)
ads_adiend()    (3d image left on screen)



8.8 3D Rendering Packet Descriptions
====================================

This section provides descriptions for the 3-dimensional ADI packets. ADI
3D rendering packets are defined in rcadi3d.h.

8.8.1 PVIEW
=============

Purpose
-------
Sets the current viewing transform.

Limitations
-----------
This is an ADI 4.2 3D rendering packet. It can be sent in display mode to
DEV_RC drivers that set D3_VP in PDINFO.flags_3d, and it can be sent in
rendering mode to DEV_RD and DEV_RC drivers that set D3_FULL in
RD_INFO.flags_3d.

This packet should be sent sometime after a P3D bookend with the D3_START
flag set and before a P3D bookend with the D3_END flag set.

The controlling application fills in every member of this packet. The ADI
driver treats it as read-only.

History
-------
This packet was added in ADI 4.2.

Declaration
-----------
#define PVIEW       79         /* Viewing transform */

struct pk3dview {
    short pfunc;    /* PVIEW packet code */
    short psize;    /* Packet size */
    short viewport; /* Viewport to use */
    Mat44 xform;    /* Viewing transform */
};

Description
-----------
Our matrices are right-handed. The fourth row is filled with 0,0,0,1. The
right column is used for translation of the target point from the model
coordinate system origin. This agrees with the standard described in Foley,
van Dam, Feiner and Hughes, Computer Graphics: Principles and Practice (2nd
ed).



8.8.2 PORTHO
==============

Purpose
-------
Establishes an orthographic projection.

Limitations
-----------
This is an ADI 4.2 3D rendering packet. It can be sent in display mode to
DEV_RC drivers that set the D3_VP capability bit in PDINFO.flags_3d and it
can be sent in rendering mode to drivers (DEV_RD and DEV_RC) that set the
D3_FULL capability bit in RD_INFO.flags_3d.

This packet should be sent sometime after a P3D bookend with the D3_START
flag set and before a P3D bookend with the D3_END flag set.

The controlling application fills in every member of this packet. The ADI
driver treats it as read-only.

History
-------
This packet was added in ADI 4.2.

Declaration
-----------
#define PORTHO      80         /* Orthographic projection */

struct pkortho {
    short pfunc;        /* PORTHO packet code */
    short psize;        /* Packet size */
    short viewport;     /* Viewport to use */
    Real zmin, zmax;    /* Clipping planes */
    Real pxmin, pxmax;
    Real pymin, pymax;
};

Description
-----------
PORTHO establishes an orthographic projection. The view includes the area
defined by the corners (pxmin, pymin) and (pxmax, pymax). It includes only
the geometry between the clipping planes defined by zmin and zmax. If this
is a rendering in a viewport, the member viewport specifies which viewport
is involved.



8.8.3 PPERSP
==============

Purpose
-------
Establishes a perspective projection.

Limitations
-----------
This is an ADI 4.2 3D rendering packet. It can be sent in display mode to
DEV_RC drivers that set the D3_VP capability bit in PDINFO.flags_3d and it
can be sent in rendering mode to drivers (DEV_RD and DEV_RC) that set the
D3_FULL capability bit in RD_INFO.flags_3d.

This packet should be sent sometime after a P3D bookend with the D3_START
flag set and before a P3D bookend with the D3_END flag set.

The controlling application fills in every member of this packet. The ADI
driver treats it as read-only.

History
-------
This packet was added in ADI 4.2.

Declaration
-----------
#define PPERSP      81  /* Perspective projection */

struct pkpersp {
    short pfunc;        /* PORTHO packet code */
    short psize;        /* Packet size */
    short viewport;     /* Viewport to use */
    Real ytheta;        /* Field of view angle, degrees 0-180 */
    Real znear, zfar;   /* Clipping planes */
};

Description
-----------
The angle ytheta is measured in the Y direction. The field of view angle in
the X direction can be computed from the aspect ratio. The eye point is at
the origin (0,0,0) and is looking along the negative Z direction.



8.8.4 POSEG
=============

Purpose
-------
Opens a segment.

Limitations
-----------
This is an ADI 4.2 3D rendering packet. It can be sent in display mode to
DEV_RC drivers that set the D3_VP and D3_SEGMENTS capability bits in
PDINFO.flags_3d and it can be sent in rendering mode to drivers (DEV_RD and
DEV_RC) that set the D3_FULL and D3_SEGMENTS capability bits in
RD_INFO.flags_3d.

This packet should be sent sometime after a P3D bookend with the D3_START
flag set and before a P3D bookend with the D3_END flag set.

The controlling application fills in every member of this packet. The ADI
driver treats it as read-only.

History
-------
This packet was added in ADI 4.2.

Declaration
-----------
#define POSEG 82  /* Open segment */

struct pkseg {
    short pfunc;        /* POSEG */
    short psize;
    Segid id;
};
Description
-----------
POSEG implies PCSEG if there is a currently open segment. In other words,
when you receive POSEG, close the open segment, if there is one, and open
the specified segment. All geometry in the segment is sent between POSEG
and PCSEG bookends.

Segments are intact even after an RDEND. That is, segments are only deleted
when requested to do so with PDSEG (or at RDTERM).

Segments can contain geometry data (PVEC3, PPOLY3, PNPOLY3, and PCPOLY3) as
well as PSETCOLOR and PSETMATL information. When a segment is drawn, it
inherits the color and material properties in effect. Color and material
data in a segment override the inherited values, and the original inherited
values are restored at the end of the segment drawing operation.



8.8.5 PDSEG
=============

Purpose
-------
Deletes a segment.

Limitations
-----------
This is an ADI 4.2 3D rendering packet. It can be sent in display mode to
DEV_RC drivers that set the D3_VP and D3_SEGMENTS capability bits in
PDINFO.flags_3d and it can be sent in rendering mode to drivers (DEV_RD and
DEV_RC) that set the D3_FULL and D3_SEGMENTS capability bits in
RD_INFO.flags_3d.

This packet should be sent sometime after a P3D bookend with the D3_START
flag set and before a P3D bookend with the D3_END flag set.

The controlling application fills in every member of this packet. The ADI
driver treats it as read-only.

History
-------
This packet was added in ADI 4.2.

Declaration
-----------
#define PDSEG 84  /* Delete segment */

struct pkseg {
    short pfunc;        /* PDSEG */
    short psize;
    Segid id;
};

Description
-----------
The PDSEG packet deletes a segment.



8.8.6 PCSEG
=============

Purpose
-------
Closes the currently open segment.

Limitations
-----------
This is an ADI 4.2 3D rendering packet. It can be sent in display mode to
DEV_RC drivers that set the D3_VP and D3_SEGMENTS capability bits in
PDINFO.flags_3d and it can be sent in rendering mode to drivers (DEV_RD and
DEV_RC) that set the D3_FULL and D3_SEGMENTS capability bits in
RD_INFO.flags_3d.

This packet should be sent sometime after a P3D bookend with the D3_START
flag set and before a P3D bookend with the D3_END flag set.

A segment should be open before a PCSEG packet is sent.

The controlling application fills in every member of this packet. The ADI
driver treats it as read-only.

History
-------
This packet was added in ADI 4.2.

Declaration
-----------
#define PCSEG  83       /* Close current segment */

struct pkseg {
    short pfunc;        /* PCSEG */
    short psize;
};

Description
-----------
Closes the currently open segment. All geometry in the segment is sent
between POSEG and PCSEG bookends.



8.8.7 PBPOLY3
===============

Purpose
-------
Adds a group of polygons to the currently open segment.

Limitations
-----------
This is an ADI 4.2 3D rendering packet. It can be sent in display mode to
DEV_RC drivers that set the D3_VP capability bit in PDINFO.flags_3d and it
can be sent in rendering mode to drivers (DEV_RD and DEV_RC) that set the
D3_FULL capability bit in RD_INFO.flags_3d.

This packet should be sent sometime after a P3D bookend with the D3_START
flag set and before a P3D bookend with the D3_END flag set.

A segment should be open before a PBPOLY3 packet is sent.

The controlling application fills in every member of this packet. The ADI
driver treats it as read-only.

History
-------
This packet was added in ADI 4.2.

Declaration
-----------
#define PBPOLY3 2066

struct pkbpoly {
    short pfunc;
    short psize;  /* Size of this packet (without polys) */
    short npolys;  /* Number of polygons to follow */
    long offset;   /* Offset from start of this packet
                      to first poly */
};

Description
-----------
The offset member is needed for Phar Lap, where the polygon buffer is not
contiguous with the main packet buffer.



8.8.8 PPOLY3
==============

Purpose
-------
Adds a polygon to the currently open segment.

Limitations
-----------
This is an ADI 4.2 3D rendering packet. It can be sent in display mode to
DEV_RC drivers that set the D3_VP capability bit in PDINFO.flags_3d and it
can be sent in rendering mode to drivers (DEV_RD and DEV_RC) that set the
D3_FULL capability bit in RD_INFO.flags_3d.

This packet should be sent sometime after a P3D bookend with the D3_START
flag set and before a P3D bookend with the D3_END flag set.

A segment should be open before a PPOLY3 packet is sent. PPOLY3s should be
sent only to drivers that indicate support for flat shading by setting
D3_FLAT in flags_3d.

The controlling application fills in every member of this packet. The ADI
driver treats it as read-only.

History
-------
This packet was added in ADI 4.2.

Declaration
-----------
#define PPOLY3      85         /* 3D polygon */
#define MAX3DVERT 4

struct pkpoly3 {
    short pfunc;     /* PPOLY3 packet code */
    short psize;     /* Total packet size in bytes */
    long flags;
    short n;         /* Number of points in poly */
    Vec3 fnorm;      /* Face normal for flat shading */
    Vec3 vert[MAX3DVERT]; /* Array of vertices */
    Color pcolor;    /* Polygon color */
};

Description
-----------
There are three forms of polygon packet, with different packet codes to
simplify packet batching. Polygons are limited to a maximum of 4 vertices.
Quads are planar.

Table 8-30. Values for PPOLY3.flags

Mnemonic          Value  Meaning

EDGE0             0x2    Edge 0 - 1

EDGE1             0x4    Edge 1- 2

EDGE2             0x8    Edge 2 - 0 or 2 -3

EDGE3             0x10   Edge 3 - 0

PCOLORS           0x20   If optional overall color is valid

DR3_IMMED         0x40   Render immediately


If the bits EDGE0, EDGE1, etc. are set, they indicate invisible polygon
edges.

The local pcolor value, if PPOLY3.flags PCOLORS is set, overrides the modal
PSETCOLOR value. If this override is in effect, this polygon is not shaded
and no material properties are applied.



8.8.9 PNPOLY3
===============

Purpose
-------
Adds a polygon to the currently open segment.

Limitations
-----------
This is an ADI 4.2 3D rendering packet. It can be sent in display mode to
DEV_RC drivers that set the D3_VP capability bit in PDINFO.flags_3d and it
can be sent in rendering mode to drivers (DEV_RD and DEV_RC) that set the
D3_FULL capability bit in RD_INFO.flags_3d.

This packet should be sent sometime after a P3D bookend with the D3_START
flag set and before a P3D bookend with the D3_END flag set.

A segment should be open before a PNPOLY3 packet is sent. PNPOLY3 packets
should only be sent to drivers that indicate support for either color
interpolation from vertex normals (by setting D3_GOURAUD_NORM in flags_3d)
or normal interpolation (by setting D3_PHONG in flags_3d).

The controlling application fills in every member of this packet. The ADI
driver treats it as read-only.

History
-------
This packet was added in ADI 4.2.

Declaration
-----------
#define PNPOLY3 86   /* 3D polygon with vertex normals */

struct pknormpoly3 {
    short pfunc;     /* PNPOLY3 packet code */
    short psize;     /* Total packet size in bytes */
    long flags;
    long n;          /* Number of points in poly */
    Vec3 fnorm;      /* Face normal for flat shading */
    Vec3 vert[MAX3DVERT]; /* Array of vertices */
    Vec3 norm[MAX3DVERT]; /* Vertex normals */
    Color pcolor;         /* Polygon color */
};

Description
-----------
There are three forms of polygon packet, with different packet codes to
simplify packet batching. Polygons are limited to a maximum of 4 vertices.
Quads are planar.

Table 8-31. Values for PNPOLY3.flags

Mnemonic          Value  Meaning

EDGE0             0x2    Edge 0 - 1

EDGE1             0x4    Edge 1- 2

EDGE2             0x8    Edge 2 - 0 or 2 -3

EDGE3             0x10   Edge 3 - 0

PCOLORS           0x20   If optional overall color is valid

DR3_IMMED         0x40   Render immediately


If the bits EDGE0, EDGE1, etc. are set, they indicate invisible polygon
edges.

The local pcolor value, if PPOLY3.flags PCOLORS is set, overrides the modal
PSETCOLOR value. If this override is in effect, this polygon is not shaded
and no material properties are applied.



8.8.10 PCPOLY3
================

Purpose
-------
Adds a polygon to the currently open segment.

Limitations
-----------
This is an ADI 4.2 3D rendering packet. It can be sent in display mode to
DEV_RC drivers that set the D3_VP capability bit in PDINFO.flags_3d and it
can be sent in rendering mode to drivers (DEV_RD and DEV_RC) that set the
D3_FULL capability bit in RD_INFO.flags_3d.

This packet should be sent sometime after a P3D bookend with the D3_START
flag set and before a P3D bookend with the D3_END flag set.

A segment should be open before a PCPOLY3 packet is sent.

The controlling application fills in every member of this packet. The ADI
driver treats it as read-only.

History
-------
This packet was added in ADI 4.2.

Declaration
-----------
#define PCPOLY3  87  /* 3D polygon with vertex colors */

struct pkcolpoly3 {
    short pfunc;     /* PCPOLY3 packet code */
    short psize;     /* Total packet size in bytes */
    long flags;
    short n;         /* Number of points in poly */
    Vec3 fnorm;      /* Face normal for flat shading */
    Vec3 vert[MAX3DVERT]; /* Array of vertices */
    Color vcolor[MAX3DVERT]; /* Vertex colors */
};

Description
-----------
There are three forms of polygon packet, with different packet codes to
simplify packet batching. Polygons are limited to a maximum of 4 vertices.
Quads are planar.

Table 8-32. Values for PCPOLY3.flags

Mnemonic        Value                   Meaning

EDGE0           0x2   Edge 0 - 1

EDGE1           0x4   Edge 1 - 2

EDGE2           0x8   Edge 2 - 0 or 2 - 3

EDGE3           0x10  Edge 3 - 0

PCOLORS         0x20  If optional overall color is valid

DR3_IMMED       0x40  Render immediately


If the bits EDGE0, EDGE1, etc. are set, they indicate invisible polygon
edges.

The local vcolor[] values, if PPOLY3.flags PCOLORS is set, override the
modal PSETCOLOR value. If this override is in effect, this polygon is not
shaded and no material properties are applied.



8.8.11 PVEC3
==============

Purpose
-------
Adds a vector to the currently open segment.

Limitations
-----------
This is an ADI 4.2 3D rendering packet. It can be sent in display mode to
DEV_RC drivers that set the D3_VP capability bit in PDINFO.flags_3d and it
can be sent in rendering mode to drivers (DEV_RD and DEV_RC) that set the
D3_FULL capability bit in RD_INFO.flags_3d.

This packet should be sent sometime after a P3D bookend with the D3_START
flag set and before a P3D bookend with the D3_END flag set.

A segment should be open before a PVEC3 packet is sent.

The controlling application fills in every member of this packet. The ADI
driver treats it as read-only.

History
-------
This packet was added in ADI 4.2.

Declaration
-----------
#define PVEC3 88        /* 3D vector */

struct pkvec3 {
    short pfunc;        /* PVEC3 packet code */
    short psize;
    long flags;
    Color vcolor;       /* Vector color */
    Vec3 from,to;
};

Description
-----------
Table 8-33. Values for PVEC3.flags

Mnemonic        Value                                    Meaning

END_ENTITY      0x01                                     Last vector in
entity

DR3_HILITE      0x02                                     Draw using
highlighting

DR3_NORDRW      0x04                                     Line is NOT a
drawing segment. Do not redisplay on Redraw calls

DR3_DASHED      0x08                                     Real dashed lines

DR3_IMMED       0x40                                     Draw immediately


If DR3_NORDRW is set, the member vcolor has meaning. Otherwise, the
segment's color is used.



8.8.12 PLIGHT
===============

Purpose
-------
Defines a light source.

Limitations
-----------
This is an ADI 4.2 3D rendering packet. It can be sent in display mode to
DEV_RC drivers that set the D3_VP capability bit in PDINFO.flags_3d and it
can be sent in rendering mode to drivers (DEV_RD and DEV_RC) that set the
D3_FULL capability bit in RD_INFO.flags_3d.

This packet should be sent sometime after a P3D bookend with the D3_START
flag set and before a P3D bookend with the D3_END flag set.

The controlling application fills in every member of this packet. The ADI
driver treats it as read-only.

History
-------
This packet was added in ADI 4.2.

Declaration
-----------
#define PLIGHT 89       /* define light source */

struct pklight {
    short pfunc;        /* PLIGHT  packet code */
    short psize;        /* Total packet size */
    short lnum;         /* Light source number */
    short ltype;        /* Type of light source */
    Vec3 posn;          /* Position of light source */
    Vec3 aim;           /* Aim point of directed & spotlights */
    Real cone_angle;
    Real cone_delta;
    Real beam_distribution;
    Real magnitude      /* Light intensity */
    Color lcolor;       /* Light color */
    Real attn_const;    /* Light source attenuation factors */
    Real attn_lin;
    Real attn_sqr;
};

Description
-----------
Light coordinates are in world coordinates. When placed, light coordinates
are transformed through the current view matrix. Subsequent PVIEW packets
cause the (world coordinate) positions of all active lights to be
retransformed through the new view matrix.

Directed lights are always located at infinity. The vectors define the
direction in which the light moves, that is, aim specifies the direction in
which the light is traveling. If a driver can't handle colored lights, it
should use the magnitude member as light intensity.

The light attenuation factors can be used with the following formula for
determining the total light attenuation for a light source:

attn = max((1.0 / (attn_const + (attn_lin*D) + (attn_sqr*D*D))),1.0)

(For more information, see Foley and van Dam, 2nd Ed., pages 725-727).

Table 8-34. Values for PLIGHT.ltype

Mnemonic          Value

LT_AMBIENT        0

LT_DIRECTED       1

LT_POINT          2

LT_SPOT           3


Below is a table showing which packet members have meaning for each light
type. An "X" indicates the member is meaningful:

Table 8-35. Light type for PLIGHT.ltype

Light type       Ambient      Directed  Point     Spot

lnum             X     X      X    X

ltype            X     X      X    X

posn                          X    X

aim                    X           X

cone_angle                         X

cone_delta                         X

beam_distribution                       X

magnitude        X     X      X    X

lcolor           X     X      X    X

attn_const                    X    X

attn_lin                      X    X

attn_sqr                      X    X


It is legitimate for subsequent PLIGHT packets to modify any attribute of a
previously defined light except the ltype attribute, without deleting the
light.



8.8.13 PDLIGHT
================

Purpose
-------
Deletes a light source.

Limitations
-----------
This is an ADI 4.2 3D rendering packet. It can be sent in display mode to
DEV_RC drivers that set the D3_VP capability bit in PDINFO.flags_3d and it
can be sent in rendering mode to drivers (DEV_RD and DEV_RC) that set the
D3_FULL capability bit in RD_INFO.flags_3d.

This packet should be sent sometime after a P3D bookend with the D3_START
flag set and before a P3D bookend with the D3_END flag set.

PDLIGHT should only be sent to delete light sources created with PLIGHT
packets.

The controlling application fills in every member of this packet. The ADI
driver treats it as read-only.

History
-------
This packet was added in ADI 4.2.

Declaration
-----------
#define PDLIGHT 90     /* Delete light source */

struct pkdlight {
    short pfunc;        /* PDLIGHT packet code */
    short psize;        /* Total packet size */
    short lnum;         /* Light source number */
};

Description
-----------
This packet deletes a light source.



8.8.14 PSETCOLOR
==================

Purpose
-------
Establishes the model color.

Limitations
-----------
This is an ADI 4.2 3D rendering packet. It can be sent in display mode to
DEV_RC drivers that set the D3_VP capability bit in PDINFO.flags_3d and it
can be sent in rendering mode to drivers (DEV_RD and DEV_RC) that set the
D3_FULL capability bit in RD_INFO.flags_3d.

This packet should be sent sometime after a P3D bookend with the D3_START
flag set and before a P3D bookend with the D3_END flag set.

The controlling application fills in every member of this packet. The ADI
driver treats it as read-only.

History
-------
This packet was added in ADI 4.2.

Declaration
-----------
#define PSETCOLOR  91      /* set modal color */

struct pksetcolor {
    short pfunc;     /* PSETCOLOR packet code */
    short psize;     /* Total packet size in bytes */
    Color col;       /* Default segment color */
};

Description
-----------
This sets the color for the subsequent geometry.



8.8.15 PSETMATL
=================

Purpose
-------
Establishes the modal materials property.

Limitations
-----------
This is an ADI 4.2 3D rendering packet. It can be sent in display mode to
DEV_RC drivers that set the D3_VP capability bit in PDINFO.flags_3d and it
can be sent in rendering mode to drivers (DEV_RD and DEV_RC) that set the
D3_FULL capability bit in RD_INFO.flags_3d.

This packet can only be sent to drivers that set the flags_3d capability
bit D3_MATL in PDINFO or RD_INFO.

This packet should be sent sometime after a P3D bookend with the D3_START
flag set and before a P3D bookend with the D3_END flag set.

The controlling application fills in every member of this packet. The ADI
driver can modify member status.

History
-------
This packet was added in ADI 4.2.

Declaration
-----------
#define PSETMATL 92  /* set modal materials properties */

struct pksetmatl {
    short pfunc;     /* PSETMATL packet code */
    short psize;     /* Total packet size in bytes */
    Real pka;        /* Ambient factor */
    Real pkd;        /* Diffuse factor */
    Real pks;        /* Specular factor */
    Real pse;        /* Specular exponent */
    Real trans;      /* Transparency 1.0 */
    Color psc;       /* Specular color */
    Color pac;       /* Ambient color */
    Color pdc;       /* Diffuse color */
    short status;    /* Driver returns status here */
};

Description
-----------
This sets the current material properties for the subsequent geometry. The
members pka, pkd, pks, pse, and trans all share domains from 0 to 1.0. A
value of 1.0 in the trans member means it is totally transparent.

Specular color is defined as in RenderMan (see page 233 of the RenderMan
Companion). The specular exponent is the reciprocal of "roughness:" zero is
a matte surface, 1 is the most shiny surface.

Two different models are possible for handling of ambient and diffuse
color. Use one model or the other, but not both! If your driver can apply
RGB multipliers for these properties, use members pac and pdc. Drivers that
support pac and pdc can ignore the "current color" determined by PSETCOLOR,
for this purpose. The colors pac and pdc operate directly on light sources,
for example:

AMBIENTred_contribution = LIGHTred * pac.red * pka

If your driver does not support pac and pdc, apply the multipliers pka and
pkd to the "current color" determined by PSETCOLOR, for example:

AMBIENTred_contribution = PSETCOLORred * pka

Your driver returns a status value:

#define MATL_OK       0   /* Success */
#define MATL_TOOMANY  1   /* Failed but fakes it */
#define MATL_FAIL     2   /* Failed, stop rendering */

If your driver can handle only a limited number of material definitions,
and the limit is exceeded, you have two choices: allow the rendering to
proceed with your best approximation (MATL_TOOMANY) or force the rendering
to be terminated by returning status as MATL_FAIL, and expect the host
product to rerender without sending you materials properties. These error
conditions are most likely for 8-bit devices.

Remember that all 3D Color values are sent as RGB, even for paletted
devices, if the product and driver agree to use materials properties. If
materials properties are used, ignore the vcolor member in polygon packets.



8.8.16 PMODEL
===============

Purpose
-------
Establishes a model segment transform.

Limitations
-----------
This is an ADI 4.2 3D rendering packet. It can be sent in display mode to
DEV_RC drivers that set the D3_VP capability bit in PDINFO.flags_3d and it
can be sent in rendering mode to drivers (DEV_RD and DEV_RC) that set the
D3_FULL capability bit in RD_INFO.flags_3d.

This packet should be sent sometime after a P3D bookend with the D3_START
flag set, and before a P3D bookend with the D3_END flag set.

The controlling application fills in every member of this packet. The ADI
driver treats it as read-only.

History
-------
This packet was added in ADI 4.2.

Declaration
-----------
#define PMODEL    93     /* Set modal segment transform */

struct pksetxform {
    short pfunc;    /* PMODEL packet code */
    short psize;    /* Total packet size in bytes */
    Mat44 xform;    /* Transform all this segment's polys */
};

Description
-----------
This sets the placement transform for subsequent geometry.



8.8.17 PDRAWSEG
=================

Purpose
-------
Instructs the driver to draw a segment.

Limitations
-----------
This is an ADI 4.2 3D rendering packet. It can be sent in display mode to
DEV_RC drivers that set the D3_VP and D3_SEGMENTS capability bits in
PDINFO.flags_3d and it can be sent in rendering mode to drivers (DEV_RD and
DEV_RC) that set the D3_FULL and D3_SEGMENTS capability bits in
RD_INFO.flags_3d.

This packet should be sent sometime after a P3D bookend with the D3_START
flag set and before a P3D bookend with the D3_END flag set.

The controlling application fills in every member of this packet. The ADI
driver treats it as read-only.

History
-------
This packet was added in ADI 4.2.

Declaration
-----------
#define PDRAWSEG     94         /* Draw segment */

struct pkdrawent {
    short pfunc;     /* PDRAWSEG packet code */
    short psize;     /* Total packet size in bytes */
    Segid id;        /* Segment id */
    short vpnumber;  /* Viewport to render in or 0 for full
                      screen */
    short shading_model;
    short flags;
};

Description
-----------
This tells the driver to display the segment, using the last set color,
materials properties, and segment transform, applying the current viewing
transform and projection.

The following table shows the values for member shading_model, indicating
which shading model to use.

Table 8-36. Values for PDRAWSEG.shading_model

Mnemonic              Value                     Meaning

SM_HIDDEN             1    Wireframe with hidden line removal

SM_FLAT               2    Flat shading (painter's algorithm)

SM_GOURAUD_NORM       3    Color interpolation for PNPOLY3s

SM_GOURAUD_COL        4    Color interpolation for PCPOLY3s

SM_WIREFRAME          5    Wireframe without hidden line removal

SM_PHONG              6    Normal interpolation for PNPOLY3s


The shading model flags resolve the potential ambiguity regarding handling
of vectors and PNPOLY3 polygons. They also allow for shading model
overrides for drivers that support this capability.

Table 8-37. Values for PDRAWSEG.flags

Mnemonic          Value               Meaning

DR3_UNDRAW        1    Undraw segment

DR3_HILITE        2    Draw segment highlighted

DR3_MATL          4    Use material properties

DR3_BACKF_REJ     8    Reject back faces


No shading model flag is required to indicate flat shading for PPOLY3
polygons. They are flat shaded unless a SM_WIREFRAME or SM_HIDDEN override
is in effect. Likewise, no shading model flag is required for color
interpolation Gouraud shading of PCPOLY3 polygons; this is the default for
such polygons, but SM_FLAT, SM_HIDDEN, and SM_WIREFRAME are possible
overrides.

The DR3_BACKF_REJ flag can override the global D3_BACKF_REJ in P3D (which
controls operations in immediate mode).



8.8.18 P3D
============

Purpose
-------
Bookend packet defining the start or end of 3D operations.

Limitations
-----------
This is an ADI 4.2 3D rendering packet. It can be sent in display mode to
DEV_RC drivers that set the D3_VP capability bit in PDINFO.flags_3d and it
can be sent in rendering mode to drivers (DEV_RD and DEV_RC) that set the
D3_FULL capability bit in RD_INFO.flags_3d.

The controlling application fills in every member of this packet. The ADI
driver treats it as read-only.

History
-------
This packet was added in ADI 4.2.

Declaration
-----------
#define P3D 95         /* 3D operation bookends */

struct pk3d {
    short pfunc;     /* P3D packet code */
    short psize;     /* Total packet size in bytes */
    short shading_model;   /* Global shading model */
    long flags;
};

Description
-----------
The P3D packet is used to provide bookends around episodes of 3D
operations. This is important for applications that operate in a viewport
on the display screen.

Table 8-38. Values for P3D.flags

Mnemonic          Value                      Meaning

D3_START          1     Begin 3D episode

D3_CLEAR          2     Clear the Z buffer, if there is one

D3_END            4     End 3D episode

D3_BACKF_REJ      8     Global default backface rejection flag


The D3_BACKF_REJ flag establishes a global default behavior for back face
rejection that is controlling in immediate mode. The DR3_BACKF_REJ flag in
PDRAWSEG overrides this for segmented operations.

Table 8-39. Values for P3D.shading_model

Mnemonic              Value                     Meaning

SM_HIDDEN             1    Wireframe with hidden line removal

SM_GOURAUD_NORM       3    Color interpolation for PNPOLY3s

SM_WIREFRAME          5    Wireframe without hidden line removal

SM_PHONG              6    Normal interpolation for PNPOLY3s


The shading_model member defines the global shading model for entities that
are ambiguous (vectors and PNPOLY3s).

If PVPAGE has been used to allow the image to be constructed on an
invisible display page, the PVPAGE packet that changes the visible page
also acts as an implied PSYNC, forcing everything to be drawn. PVPAGE
implies a PSYNC only if the visible page is changed.

If PVPAGE has not been used, PSYNC is sent to force everything to be drawn.
Applications do not send both PVPAGE and PSYNC during 3D operations.





                    |================================|
                    |                                |
                    |           Chapter 9            |
                    |                                |
                    |         Digitizer ADI          |
                    |                                |
                    |================================|




9.1 Introduction
================

This chapter contains information on the ADI interface for packet-mode
digitizer drivers for ADI versions since ADI 4.0 on all supported
platforms. Each packet is discussed both from the point of view of the
controlling application (in the "Limitations" section) and from the point
of view of the driver. The "History" section for each packet is useful for
applications that want to work with both old and new packet mode digitizer
drivers. The old INT mode (real-mode) ADI interface is not detailed here,
nor is the old INT-like packet mode for UNIX digitizers used in ADI 4.0
UNIX platforms.

The current ADI versions for the supported platforms are:

  * OS/2            ADI 4.0 (AutoCAD Release 10)

  * Windows         ADI 4.1 (AutoCAD Release 11)

  * P386            ADI 4.2 (AutoCAD Release 12)

  * UNIX (SCO System V)  ADI 4.1 (AutoCAD Release 11)

  * UNIX (SPARC)         ADI 4.2 (AutoCAD Release 12)


9.2 Historical Summary
======================

The packet mode digitizer interface was introduced by the OS/2 ADI 4.0 team
while working on AutoCAD Release 10. The interface has been ported to every
other AutoCAD platform except 640K DOS and to many other Autodesk products,
with extensions and improvements in each ADI version.

Table 9-1. Digitizer product availability history

Platform/Product  ADI version  Prod version Digitizer ADI interface
all platforms  pre-ADI 4.0  Before R10  INT mode ADI only
640K DOS  ADI 4.0  R10 acad  INT mode only
OS/2  ADI 4.0  R10 acad  Packet mode
SCO XENIX  ADI 4.0  R10 acad  INT-like packets
UNIX  ADI 4.0  R10 UNIX  INT-like packets
P386  ADI 4.0  R10 386  Packet mode
AutoShade (640K)  ADI 4.0  v1.0/1.1  INT mode ADI only
AutoShade 386  ADI 4.0  v1.1 shade  INT mode ADI only
640K DOS  ADI 4.1  R11 286  INT mode ADI only
P386  ADI 4.1  R11 386  Packet mode
UNIX  ADI 4.1  R11 UNIX  Packet mode
SCO UNIX  ADI 4.1  R11 SCO  Packet mode
Windows  ADI 4.1  R11 windows Packet mode
AutoShade 386  ADI 4.1  Shade 2.0  Packet mode
3D Studio 2.0  ADI 4.1  Studio v2  Packet mode
P386  ADI 4.2  R12 386  Packet mode
UNIX  ADI 4.2  R12 UNIX  Packet mode

9.3 New Features in ADI 4.2
===========================

ADI 4.2 has introduced some major new digitizer features, such as 32-bit
digitizer space and 3-dimensional, 6 degrees of freedom support.

9.3.1 Mandatory Digitizer DRAGG Mode Support
============================================

In ADI 4.1, support for DRAGG mode was optional. In ADI 4.2 it is required.
This is used in AutoCAD Release 12 in dialogue box edit fields, list-box
scroll bars, for auto-scrolling, in pull-down menus (pull-right), and in
the DRAGDOWN method of crossing/window object selection.

A new environment variable is honored in AutoCAD Release 12 which allows
users with old display drivers (which may depend on PDIGTIZE services with
DRAGG mode turned off) to disable DRAGG mode. If AutoCAD Release 12 sees
IGNORE_DRAGG set to a non-null value, and if a pre-ADI 4.2 display driver
is running which has set EF_DIGTIZ in PINIT.pefmodes, AutoCAD does not
request DRAGG mode from its digitizer driver.

9.3.2 32-bit Digitizer Space
============================

Until ADI 4.2, digitizers scaled their raw data to fit within the range 0
to 20480. In ADI 4.2 the digitizer data space has been expanded to a full
32 bits.

ADI 4.2 digitizers return data within the range of their natural
resolution. At initialization time, a digitizer indicates its data range
for each axis.

9.3.3 3D and 6DF Digitizer Data
===============================

ADI 4.2 provides support for 3-dimensional and 6-degree-of-freedom pointing
devices.

Devices that do not support z, ix, iy, or iz simply return zero for these
values and for their ranges.

The structure members ix, iy, and iz specify rotations about the X, Y and Z
axes in 3-space. If you picture an airplane with its X-axis parallel to the
fuselage and its Y-axis parallel to the wings, ix is roll or rotation about
the X-axis; iy is pitch or rotation about the Y-axis; and iz is yaw or
rotation about the Z-axis. Since the order in which you apply these
rotations can produce different orientations, we propose here that the
order of rotations be applied in the order X, Y then Z. The direction of
rotation about an axis is defined by the right-hand rule. In other words,
if you are looking down the X-axis from a point in the positive X direction
towards the origin, the rotation would be applied counter-clockwise. A
reference point from which to apply the rotation (i.e. from where to
measure 0 degrees) is defined as any point on the positive Z-axis for an X
rotation; any point on the positive X-axis for a Y rotation; and any point
on the positive Y-axis for a Z rotation. The number of degrees to apply to
a rotation is defined as:

ix * (360 / (ix_max + 1))

where ix is less than or equal to ix_max.

AutoCAD Release 12 does not yet make use of the Z, roll, pitch and yaw data
returned by a 3D digitizer, but these data are made available to ADI 4.2
display drivers via PDIGTIZE_42 (see chapter 6).

See figure 9-1 in the printed documentation (shows roll, pitch, and yaw).


9.4 Modes of Digitizer Operation (Stream, Polled, and Interrupt)
================================================================

The first digitizer drivers for AutoCAD operated in "Stream mode" in which
data was sent nonstop from the digitizer. AutoCAD would "poll" the device
by reading the stream until a complete sample was obtained. This method was
very slow since AutoCAD usually started reading in the middle of a sample,
discarded that partial sample, and then had to read another complete
sample.

The next generation of devices supported "remote" mode where a sample was
sent from the device only on request. This was faster than "stream mode,"
but still resulted in a lot of lost CPU time receiving repeated identical
samples when the digitizer had not changed state.

Some digitizer devices support "incremental mode" (or true interrupt mode)
in which a sample is sent from the device only when the coordinates change
or a button changes state. The earliest versions of this type of digitizer
device sometimes failed to send new samples for both button-down and button-
up events, so this mode was not supported by AutoCAD until ADI 4.1.

The latest generation of digitizing devices includes some that correctly
implement interrupt mode. Thus, support for this feature was added to the
ADI 4.1 digitizer ADI specification. This event-driven mode saves
considerable CPU overhead. It improves responsiveness of the cursor and
eliminates occasional "jerks" in cursor movement. (AutoCAD 386 jerks for
polled digitizers when the Phar Lap DOS Extender scans its page tables
every few seconds.) The older digitizer devices are still supported.

On UNIX platforms, our library code handles digitizer I/O for you. If
interrupt mode is enabled on these platforms, better performance usually
results (unless the device sends the sample too frequently).

9.4.1 Sharing the Same Serial Port
==================================

You can have two devices, a plotter and a digitizer, configured for the
same serial port. Obviously, you can only use one at a time, and it is
important to switch the cable at the appropriate times so the devices
attached can be reset or otherwise controlled correctly.

Follow these guidelines to determine when the cabling can be successfully
switched:

  * DIGITIZER to PLOTTER: If switching from a digitizer to a plotter, wait
until just after you have left the AutoCAD graphics screen(after specifying
the area to plot) before you switch the cable.

  * PLOTTER to DIGITIZER: If switching from a plotter to a digitizer, wait
for the "Plot complete" or the "Plot canceled" message. DO NOT wait until
you have reentered the AutoCAD graphics screen, because the digitizer might
not be reinitialized. Also, be sure to wait until the "Plot completed" or
"Plot canceled" message is displayed before switching the cable, because
the digitizer might receive some plotter data that could have operationally
altering side effects.

For AutoCAD Release 12:

  * DIGITIZER to PLOTTER: If switching from a digitizer to a plotter, wait
until you are prompted: "Press RETURN to continue or S for hardware setup."

  * PLOTTER to DIGITIZER: If switching from a plotter to a digitizer, wait
for the prompt which tells you to reconnect the digitizer.

On release 12 platforms that support multiple AutoCAD sessions, sharing the
same port between a plotter and a digitizer is impossible if more than one
AutoCAD is running (one AutoCAD would try to plot while another would still
expect digitizer services).

9.4.2 Relative Mode for ADI 4.2 Digitizers
==========================================

Many graphic tablets can operate in "mouse mode." This relative mode is
well adapted to most "paint" applications. Although ADI versions before 4.2
supported devices that report relative coordinates (e.g., mice), in
previous ADI versions (and for normal ADI 4.2 operation) ADI drivers have
been required to report absolute coordinates. Thus, a mouse driver has had
to convert relative coordinates to absolute coordinates.

In ADI 4.2, a new option flag has been added to allow Autodesk products to
request that drivers return relative coordinates. This new mode is not used
by AutoCAD, but is used by 3D Studio v2.0 and some other Autodesk products.

If the Autodesk product desires relative mode, it sets DG_RELATIVE in CINIT
and EINIT. If the device can operate in relative mode, it leaves the
DG_RELATIVE bit set and operates in relative mode. If the device can't
operate in relative mode, it clears the DG_RELATIVE bit and proceeds in
absolute mode.

#define DG_RELATIVE     0x2   /* motion-vectors returned */

In relative mode, the X, Y, and Z values returned to the Autodesk product
are deltas from the last sample. As with other ADI 4.2 digitizer data,
these are returned in unscaled "natural" coordinates for the device. The
members (see below) in the DETAIL_42 packet that specify coordinate range
return the natural coordinate change corresponding to one inch of movement
for X, Y, or Z. The angular range and pressure range values are returned as
they are for absolute mode.

Range values in DETAIL_42:

    long x_max;          /* Unsigned X coord range */
    long y_max;
    long z_max;

The values returned in dgexpkt for X, Y, and Z are signed deltas. The
values for pressure, ix, iy, and iz remain the same as in absolute mode and
are data valid as of the time of the sample. In other words, each digitizer
sample consists of both position change information and current orientation
and pressure data.

9.4.3 Mole Mode for Digitizers
==============================

Mole mode was introduced in OS/2 ADI 4.0. Although the code for mole mode
exists in UNIX ADI 4.1, it was not enabled because the required UNIX kernel
support for mole mode was not yet standard for UNIX ADI 4.1. Likewise, mole
mode is not yet supported in Windows ADI 4.1. We have enabled mole mode
support in UNIX ADI 4.2. Due to AutoCAD Release 12 using programmable
dialogues, mole mode support is much more important in Release 12.

According to Gary Scott, the programmer who first coined the term, "mole"
in "mole mode" comes from the world of espionage. The code used to
implement mole mode acts as a "double agent" and tricks the operating
system into believing it is a mouse, when in fact it works for AutoCAD.
However, the analogy between the term "mole" and another furry little
animal on the desktop is very hard to resist. In mole mode, the driver
"tunnels" under the operating system via a system driver that accepts
tablet messages from the mole tablet driver and inserts them in the system
mouse's message queue.

The digitizer can be in one of two different states, mole or normal. In
mole mode the digitizer acts very much like a system mouse. In the normal
operating mode, the digitizer operates as it normally does in AutoCAD.

Mole mode is currently "turned on" for SPARC AutoCAD Release 12.

The ADI library code checks to see if three conditions are met before it
attempts to configure mole mode:

1)  It checks to see if the UNIX kernel has support for mole mode.
    For SPARC AutoCAD Release 12, this involves installing a streams-based
    mouse driver that provides an entry point for mole data.

2)  The MOLEMODE flag must be ORed with the TABLET flag in your
    driver's DETAIL.tablet entry (struct dgcudetail).

3)  If the first two conditions are met, it asks the user whether
    they want to configure mole mode. A "Yes" answer lets mole mode be
    configured.


9.5 ADI 4.2 Interface Level
===========================

The symbolic constant ADIPKTLEVEL has been incremented from 3 to 4 for
AutoCAD Release 12 and ADI 4.2.

We have implemented an ADI version numbering scheme for ADIPKTLEVEL that
uses the four least significant bits for minor revisions that probably do
not cause major incompatibility. The upper bits are used for more major
changes. You must decide how to test for a compatible version, but one
suggested test is to see if the upper bits have changed, after masking off
the lower four bits. The symbolic constants defining various ADIPKTLEVELs
for different device types are in adi.h.

The packets and symbolic constants used in digitizer ADI are defined in
dgp.h.


9.6 ADI 4.2 Digitizer Driver Loading
====================================

In OS/2 ADI 4.0, ADI digitizer drivers appeared in the AutoCAD
Configuration menu. This was accomplished by code that searched for and
briefly executed potential ADI digitizers, just long enough to extract
their names.

In P386 ADI 4.0 and ADI 4.1 for all platforms, packet mode digitizer
drivers were configured with an environment variable (DGPADI) set to the
pathname of the desired digitizer driver.

AutoCAD Release 12 on all platforms searches for packet mode digitizer
drivers (they must have names starting with the letters "dg") and simply
scans the file looking for a sentinel and the driver name in the edevent
structure.


9.7 Sample ADI Digitizer Drivers
================================

Sample drivers are provided to assist developers to better understand ADI
device driver specifications, to help test development environments, and to
improve productivity. Please read the license agreement at the beginning of
each sample source code file regarding the use of the sample source code.

The list of sample drivers available on each platform and other platform-
specific information is available in a document file named adikit.doc
located in a directory named for the platform (e.g., \sparc\adikit.doc).


9.8 ADI 4.2 P386 Digitizer Implementation
=========================================

P386 digitizer drivers use shared memory for their transport layer, like
all P386 ADI drivers. See the discussion of P386 ADI driver loading and
communication in chapter 3.

The three basic modes for implementing a digitizer device are stream,
polled, and event driven (interrupt mode). If you use stream mode, use of
the new dispatcher function iormt() is a good plan. For polled mode, the
dispatcher function iorm() is handy. Both of these let AutoCAD handle the
digitizer's I/O, but get a complete sample in a single dispatcher request.

If you fail to use iorm() for a polled digitizer driver (some of the sample
drivers in this release of the ADIKIT do this), your driver will probably
fail to run correctly on systems with very slow CPUs.

If you decide to write an interrupt mode digitizer, your driver has full
responsibility for communication with the device.

You must write an interrupt handler that collects and stores data from the
digitizer in an area where your task-time routine can collect it. Your
driver needs to save and restore any other interrupt-handling vectors that
your code replaces. Note that your interrupt routine should be disconnected
during the AutoCAD Shell command and reconnected afterwards.

9.8.1 Implementing P386 Interrupt Mode
========================================

Implementing an ADI 4.1 or ADI 4.2 interrupt mode digitizer driver involves
several steps. You should ask the user which mode she prefers to use
(polled or interrupt).

If the user selects interrupt mode, the following steps should be used to
implement the driver:

1)  Set member interrupt of the DETAIL packet to 1.

2)  Get and save both real- and protected-mode interrupt vectors
    before installing your protected mode interrupt vector.

3)  Enable the appropriate IRQ number (passed in the EINIT packet) on
    the master or slave 8259 chip.

4)  Install your interrupt vector.

5)  Set the Digitizer mode to send a sample only when the puck has
    moved or a button was pressed or released.

6)  Process the digitizer's sample when an interrupt occurs.

7)  Handle the BSHELL and ASHELL notifications. Before the user
    shells out, you must restore the saved real-mode interrupt vectors. After
    the user reenters AutoCAD, you must reset your protected-mode interrupt
    vector.

Although this might sound complex, most code involved is generic enough to
get a good insight from the sample DEV_DG Summagraphics digitizer driver
(dgpsumi.c) and the interrupt-handling code in dgpsumia.asm.

The dispatcher function msysint32() allows queries to the system, useful
for getting interrupt vector information. Examples of this function are in
the dgpsumi sample driver.

9.8.2 Implementing UNIX Interrupt Mode
======================================

Fewer steps are involved in implementing a UNIX ADI 4.1 or ADI 4.2
interrupt mode digitizer driver. It is recommended you ask the user which
mode they prefer (polled or interrupt).

If the user selects interrupt mode, use the following steps to implement
the driver:

1)  Set member interrupt of the DETAIL packet to 1.

2)  Set the digitizer mode to send a sample only when the puck has
    moved or a button was pressed or released.

3)  Process the digitizer's sample when an interrupt occurs.

Our library code handles the grim details of UNIX interrupt mode.


9.9 ADI 4.0 OS/2 Digitizer Implementation
=========================================

OS/2 digitizer drivers are implemented as DLLs (dynamic link libraries).

PM AutoCAD can use two different types of pointing devices (other than the
keyboard): a system mouse and a mole tablet driver. This document doesn't
address the problem of writing an OS/2 system mouse driver since that is a
generic OS/2 driver. It does discuss mole tablet drivers.

Note: If AutoCAD cannot find mole.sys installed as a system driver, the
digitizer works in tablet mode only. See dgread_poll_no() and
dgread_intr_no() in dgmole.c for an example.

9.9.1 OS/2 Mole Tablet Driver
=============================

For standardization, we also request that your mole driver operate in
absolute mode, even if your device is capable of operating in relative
mode. If you must operate in relative mode, please see the sample driver
dgmsgmm.c for details.

In Digitizer mode, the driver sends digitizer samples directly to AutoCAD,
and the cursor is restricted to the AutoCAD graphics window. Digitizer mode
is required to operate AutoCAD with tablet mode on. In mole mode the driver
sends samples to a special driver called mole.sys which in turn sends the
samples to the system mouse queue. In this mode the digitizer operates much
like a mouse and is capable of moving the cursor anywhere on the screen.

During configuration of the digitizer the user has the option of getting
audio or visual prompts whenever the mole changes state. A beep is sounded
and/or MOLE appears in the title bar.

A mole tablet driver is a DLL that is initialized from the main AutoCAD
thread, but which starts up a thread of its own. It sends messages via two
routes:

While in tablet mode, it sends WM_ACAD_TABLET1 messages into the
pmacad.dll's message queue.

While in mole mode, the ADI driver uses the DosWrite command to send data
to the system mole device driver. This driver in turn inserts the messages
into the system mouse queue. This system mole driver (mole.sys) is
installed by the operating system at boot time. It must be in the
config.sys file.

A mole driver isn't polled by AutoCAD -- it initiates messages at intervals
(sleeping in between), acting as an event-driven device. AutoCAD perceives
all moles to be running in incremental mode (i.e., a sample is posted only
if there has been a change in the state of the digitizer). Therefore, the
gathering of data from moles is completely asynchronous to the operation of
AutoCAD.

If the digitizer can be programmed to output its data only when there is a
change of state, that is, incremental mode, the driver can use the
interrupt method of sending samples. The function dgread_intr() in dgmole.c
doesn't sleep for 30 milliseconds in between digitizer samples. See the
mole sample drivers provided, where POLLED is #ifdef'd for an example.

Note: This method is not a true poll and should not be interpreted as
polling. Packets are only returned from diginp() when there is a change of
state. If there is no change, diginp() returns after 1.2 seconds to check
for an exit condition. Otherwise there would not be a way to properly exit
the mouse thread.

The user can select up to three different methods of switching between mole
and normal mode. This part of the driver's configuration is handled inside
the driver, and should be standardized by copying the text and code used in
the sample mole drivers (dgmole.c).

1)  Define a dedicated mole pointing area on the digitizer. Whenever
    the pointer is in this area the digitizer works in mole mode.

2)  Define an area on the digitizer that toggles between digitizer
    and mole mode. Every time the cursor enters this area, the mode toggles.

3)  Define a button on the digitizer that toggles between digitizer
    and mole mode. This works only for digitizers with more than one button.

When configuring moles it is possible to reverse the way the crosshairs
move with respect to the puck if the two points specified for the mole or
screen pointing area are also reversed (see diagram below). This is an
unusual side effect that some users might even find useful.



When calibrating the tablet, if AutoCAD detects a mole and/or mouse point
input, it beeps and puts up an alert box warning the user. This alert box
goes up every time AutoCAD detects a point pick from nondigitizer input
while in the tablet command mode. There is no way to force a mole to become
a tablet from AutoCAD; in fact, there is no way to even tell what mode the
user is currently in.

You might notice the crosshairs jumping around the screen. If you are
toggling between mole and tablet mode, that is to be expected, because it
is unlikely that the mouse and tablet map to the same location. If the
mouse is moving and the digitizer is in mole mode, the crosshairs jump.
This is because both are sending samples to the mouse queue. The digitizer
input can be so sensitive that it is constantly updating its position, even
though you are not moving it.

9.9.1.1 OS/2 Configuration Time
-------------------------------

During configuration AutoCAD repeatedly sends packets to the driver with a
function code and model index informing the driver of the information it
needs. These packets include one dgbxinit packet and several dgcdmodel
packets. A typical sequence of packets for a new configuration might be:
CINIT, MODEL (repeated nmodels + 1 times), DETAIL, CURSOR, and CINFO,
though the exact sequence of packets varies depending on the configuration
state and the user's responses. Note that drivers should ignore
unrecognized packets.

struct dgcdmodel {
    short dgcode; /* Request code */
    short dgsize; /* Sizeof packet */
    short model; /* Model index */
};

The packets HMQUEUE and DGSTART used for OS/2 ADI 4.0 digitizer drivers are
not used in later ADI versions or platforms.

9.9.1.2 OS/2 Incremental Mode
-----------------------------

If the digitizer supports incremental mode you might want to use it. The
tablet sends data only when it has changed and therefore the drivers don't
request data from the tablet. This results in better performance. The only
difference between dgread_poll() and dgread_intr() (in dgmole.c) is that a
DosSleep() isn't called for 30 milliseconds. For driver examples, see the
dgmhit.c and dgmkurta.c. Search for POLLED to see typical changes that are
needed. Please refer to the installation guide for the correct switch
settings to set incremental mode for both these tablets.

The Hitachi 1111b and the Kurta III support this method but are not
implemented in the sample drivers provided with the kit. The Summagraphics
SummaSketch II reportedly supports incremental mode but no example is
included, nor has it been tested at this time. Note that the Kurta I and II
do not support incremental mode. Nor do the earlier SummaSketch tablets,
GTCO Digipad 7, and the Hitachi 1515b fully support incremental mode (the
button state isn't sent unless there is movement).

To fully support incremental mode, digitizers have to report every change
in their state. This includes not only cursor movement, but also button-
down and button-up events. Without button-up events it is impossible for a
digitizer to become a mole in interrupt-driven mode. (Note: In digitizers
that are not interrupt driven, we can detect button-up events by
continually polling the device. The OS/2 operating system reacts
differently, depending on whether the mouse button is held down or
clicked.)


9.10 ADI 4.1 Windows Digitizer Implementation
=============================================

Windows ADI 4.1 digitizer drivers are implemented as DLLs (dynamic link
libraries).

Windows ADI 4.1 development took place at the same time as P386 and UNIX
ADI 4.2 development. For this reason, the sample digitizer drivers in the
ADI 4.2 kit are #ifdef'd for Windows 4.1 as well as for P386 and UNIX ADI
4.2. You'll find that the Windows code uses a few ADI 4.2 features.

Digitizers should respond to a sample request upon receiving a DGSENSE
packet. The coordinate information, however, is passed back through the
main windows event loop, not DGSENSE. See the file common/dgcom.c.

Stream mode digitizer support presented a problem in ADI 4.1 for Windows.
Under certain conditions, AutoCAD was unable to keep up with the samples
sent from the digitizer. The digitizer was sending out samples faster than
AutoCAD was able to process them. This resulted in a heavy rubber-band
effect as samples started to back up in the serial input buffer.

To provide support for streaming digitizers, we implemented a new
dispatcher function named iormrc(). This function differs from the standard
iorm() call in that it returns a count of the number of bytes read. The
function also differs from the iorm() call in that it reads up to the
number bytes requested rather than reading all of the bytes requested.

Two of the sample drivers, dg\dgnumon and dg\dggtco, use the iormrc() call
to buffer digitizer data inside the ADI driver itself. These drivers scan
their internal buffers for either a button press or the final digitizer
sample stored in this buffer. If either is found, the sample is returned to
AutoCAD. In effect, the drivers toss out any samples received from the
digitizer between DGSENSE packets that do not contain a button press. For
examples, see the files dg\dgnumon.c and dg\dggtco.c.

9.10.1 Interrupt Handling
=========================

It is unlikely that your Windows ADI driver needs to handle interrupts, but
if you choose to use hardware interrupts, follow these guidelines. Your
interrupt-handling code must reside in a fixed code segment. This is
because interrupts can occur at any time, not just during the execution of
the application using the device. For your DLL code to be available at all
times to service interrupts, it must be in a fixed code segment.

Interrupt-handling code in your driver should not call client applications
directly. Also, you must not call AutoCAD using the SendMessage() routine,
because there is no mechanism to synchronize these calls with the AutoCAD
normal message processing. These calls might seem to work, but can lead to
race conditions, data corruption, and unpredictable behavior. Instead, you
can use the PostMessage() routine to place a message on the AutoCAD message
queue.

9.10.2 Windows ADI I/O Error Codes
==================================

I/O errors occurring with either the serial or parallel ports are handled
by AutoCAD but can affect digitizer and plotter ADI drivers. AutoCAD
assigns an error level to the I/O error, either "nonserious" or "serious."
The action taken depends on the error level that AutoCAD assigns. For a
nonserious error, AutoCAD may or may not issue a prompt dialogue box. If no
prompt dialogue box is issued, AutoCAD automatically handles the error, and
neither the user or the ADI driver is aware of it. For a serious error,
AutoCAD always displays a prompt dialogue box and either cancels the plot
(plotters) or disables the driver (digitizers). See the section "Windows
ADI I/O Error Handling" in chapter 10 for more information.


9.11 UNIX Digitizer Implementation
==================================

Digitizer drivers on all release 12 UNIX platforms are loaded as a child
process that communicates with AutoCAD by means of sockets or pipes. This
UNIX transport layer is hidden from your driver because it is part of the
library code we supply for linking with your driver. See the discussion of
UNIX ADI driver loading and communication in chapter 3.

9.11.1 Linking and I/O
======================

Your digitizer driver must be linked with our library code, dgalib.a, and
with dgumain.o. These modules provide the required startup code, socket or
pipe support, and dispatcher services to make a UNIX ADI 4.1 or 4.2
digitizer function.

Your driver must use our I/O services (ior() and iow()). These are provided
by code in the ADI library, local to your driver (digitizer driver
callbacks to AutoCAD are not made to satisfy I/O requests). This design was
selected to improve performance.

We have tried to make UNIX and P386 drivers as similar as possible, hiding
the platform differences in the ADI library code whenever possible.

9.11.2 Hardware Handshaking
===========================

Currently, handshaking does not apply to digitizers. Thus, under UNIX the
handshake member in the dgcudetail structure has no meaning for either
iow(DG) or ior(DG).

9.11.3 Digitizer Sharing
========================

A single UNIX ADI 4.1 or 4.2 digitizer can be "shared" between multiple
simultaneously active AutoCAD sessions. Only one session can receive data
and "picks" from the digitizer, but the user has control over which session
"sees" the digitizer.

This digitizer sharing is implemented by an internal design using sockets
to communicate between the digitizer and AutoCAD. The socket mechanism
allows the ADI support code to easily "connect" the driver to the proper
AutoCAD session.


9.12 UNIX Digitizer Modes of Operation
======================================

Stream, Polled, and Interrupt Modes
-----------------------------------
We do not recommend that digitizers be implemented using Stream mode, where
data is sent from the digitizer continuously. Both ADI polled and interrupt
modes are supported by UNIX ADI; the interrupt (incremental) mode is
greatly preferred for devices that can correctly support it.

Interrupt mode digitizers under UNIX are easy to implement -- simply set
the interrupt member in the DETAIL packet to indicate that your device
operates correctly in incremental mode, configure your device for
incremental mode, and the ADI library code does most of the rest of the
work. Your DGSENSE routine is sent a packet for each interrupt.

DRAGG Mode
----------
The ADI 4.1 and 4.2 specifications for digitizer drivers includes an
optional DRAGG mode. Support for DRAGG mode is required for UNIX ADI 4.1
and 4.2.

One of the requirements of DRAGG mode is to report multiple button-up/down
events. If your digitizer hardware does not report button events correctly,
it is always possible to compensate for this in software. See the Hitachi
digitizer driver for an example of code (common/dgcom.c) that reports
button-up events correctly even though the hardware does not (model 1515B).

9.12.1 SCO UNIX ADI 4.1 Implementation
======================================

This section describes the ADI 4.1 specification for SCO UNIX System V/386.

9.12.1.1 SCO UNIX ADI 4.1 Digitizer Drivers
-------------------------------------------
One major difference between SCO UNIX and other UNIX platforms is the
startup module, dgxmain.o. Most UNIX platforms use dgumain.o. If you
examine the digitizer make files, you'll see some minor SCO differences.

Interrupt mode is not supported in SCO UNIX ADI 4.1.


9.13 ADI Digitizer Test Procedures
==================================

The following test procedures are for use with AutoCAD:

1.  Set up your system for the digitizer you are testing. Cable the
    digitizer according to the instructions you will provide the user for this
    purpose.

2.  Configure AutoCAD for the digitizer. Verify that it works. Exit
    AutoCAD and reenter. Verify that the digitizer works. Reconfigure and
    verify that the device still works.

3.  Start a new drawing. Crosshair should appear on the screen
    immediately after bringing up the drawing. Be sure that the pointing device
    moves the crosshairs smoothly across the screen and that the crosshairs can
    be moved over the entire drawing screen. Moving the pointing device from
    the bottom of the digitizer pointing area to the top should move the
    crosshairs from the bottom of the screen to the top (into the menu bar, if
    that is present). Moving the pointing device from the extreme left of the
    digitizer pointing area to the right should move the crosshairs from the
    left of the screen to the right (into the menu area if the menu area is
    configured ON).

    Enter the LINE command and ensure that your pointer's "pick" button
    allows point selection.

4.  If you are using the standard AutoCAD menu, and the pointing
    device has multiple buttons, ensure that the button menu options work as
    documented in chapter 6 of the current AutoCAD Customization Manual. For a
    custom menu, check the documentation supplied with that menu.

5.  Test the pointing device in SKETCH mode.  The normal button menu
    cannot be used while a SKETCH command is in progress.

The following table lists the SKETCH subcommands and the pointer buttons
that correspond to them:

Table 9-1a. SKETCH subcommands

Command Character | Pointer Button | Function
----------------------------------------------------
P                    "Pick"             Raise/lower pen
(period)               1                Line to point
R                      2                Record lines
X, Space, Return       3                Record lines and exit
Q, <Ctrl-C>            4                Discard lines and exit
E                      5                Erase
C                      6                Connect

Use the following procedure to test AutoCAD operations that are specific to
digitizing tablets:

1.  If the tablet is large enough, use the standard AutoCAD tablet
    template to test for proper operation of tablet menus. Use the TABLET CFG
    command to configure the four menu areas and the screen pointing area. Then
    try selecting several boxes from each of the four menu areas.

2.  To test Tablet mode, use the TABLET CAL command to calibrate the
    tablet to area with known dimensions and check various points (with tablet
    mode ON) for accuracy. When calibrating the tablet, choose two points that
    require the command to perform coordinate calculations more difficult than
    those required by picking the origin and another point on either the X or Y
    axis.

3.  Moving the pointer out of proximity with the tablet should cause
    the screen crosshairs to disappear, but should not interfere with keyboard
    input. Move the pointer out of proximity and type in some AutoCAD commands.

4.  Bring up several dialogue boxes. Make sure you can use the scroll
    bars in dialogues. Test the use of radio buttons and check boxes.

5.  Shell out and verify that the digitizer works on return from
    shell. Likewise, F1 to the text screen and back to the graphic screen,
    verifying that the digitizer continues to work.

6.  If your driver supports several pointer types (puck, stylus,
    etc.), run all the tests with each type of pointer. If your driver supports
    several digitizer models, run all the tests with each model.


9. 14 Packet Usage
==================

The following two tables show ADI digitizer packet usage for both
configuration-time and execution-time packets. The first table shows packet
usage for AutoCAD, across platforms for releases 11 and 12. The second
table shows packet usage for the other applicable Autodesk products,
AutoShade, RenderMan, and 3D Studio. AVE Render uses the same digitizer
packets as AutoCAD.

An x indicates usage, a dash indicates the packet is not used. For a very
brief description of what each packet does, see the "Comments" column in
the second table; the packets are listed identically in both tables.

Table 9-2. AutoCAD and AVE Render digitizer packet usage

Packet           386  SPARC  386  SPARC  Windows
                 R12   R12   R11   R11
--------------------------------------------------
ACTIVATE         -    x       -     x       -
ASHELL           x    x       x     x       -
BSHELL           x    x       x     x       -
CINFO            -    x       -     x       x
CINIT            x    x       x     x       x
CURSOR           x    x       x     x       x
DETAIL           -    -       x     x       x
DETAIL_42        x    x       -     -       x
DGSENSE          -    -       x     x       x
DGSENSE_42       x    x       -     -       -
DGTERM           x    x       x     x       x
EINFO            x    x       x     x       x
EINIT            x    x       x     x       x
INFO             x    x       x     x       x
MODEL            x    x       x     x       x
MOUSEMODE        -    x       -     x       -
NCONN            -    x       -     x       -
PLANG            x    x       -     -       -
PWHO             x    x       -     -       -

The following table shows the digitizer packets used by Autodesk products
other than AutoCAD.

Table 9-3. Other products digitizer packet usage

Packet          SHADE RMAN  3DSv2          Comments
--------------------------------------------------------
ACTIVATE           -    -    -     Activate acad library
ASHELL             -    -    x     Shell command complete
BSHELL             -    -    x     Shell command starting
CINFO              -    -    -     Port config info
CINIT              x    x    x     CFG-time initialization
CURSOR             x    x    x     Valid cursor types
DETAIL             x    x    x     User-selected model
DETAIL_42          -    -    -     User-selected model
DGSENSE            x    x    x     Request sample pre-4.2
DGSENSE_42         -    -    -     Request sample 4.2
DGTERM             x    x    x     Termination warning
EINFO              x    x    x     Basic config info
EINIT              x    x    x     XQT-time initialization
INFO               x    x    x     Same as EINFO
MODEL              x    x    x     Get model names
MOUSEMODE          -    -    -     Toggle to mouse mode
NCONN              -    -    -     Number of ACAD sessions
PLANG              -    -    x     Language and code page
PWHO               -    -    x     Controlling product



9.15 Configuration-Time Packet Descriptions
===========================================

Digitizer packets and symbolic constants are defined in dgp.h. The packet
descriptions in this chapter are presented alphabetically in two sections:
configuration-time and execution-time packets.

9.15.1 CINFO
==============

Purpose
-------
AutoCAD passes I/O port configuration information down to the driver and
its linked-in library code. The driver must know the configured model
index, cursor type and communication parameters (on platforms where the
library code handles I/O) to be able to operate; this packet supplies the
essential data.

Limitations
-----------
CINFO should be sent to Windows or UNIX ADI 4.1 and later drivers, during
configuration time, after CURSOR (and thus after DETAIL). The controlling
application must fill in the packet with all available information. This
provides the ADI driver and its linked-in library code enough information
to start up the driver, if necessary, for mole configuration.

CINFO is not supported on 386 platforms.

AutoCAD fills in all members of this packet. The ADI driver treats this as
a read-only packet.

History
-------
Added in UNIX ADI 4.1

Declaration
-----------
#define CINFO  14

struct dgedinfo {
    short dgcode;      /* CINFO */
    short dgsize;      /* Size of packet */
    short modinx;      /* Model table index */
    short curinx;      /* Cursor table index */
    short baud;        /* Baud rate */
    short parity;      /* Parity */
    short data;        /* Data bits/frame */
    short stop;        /* Stop bits/frame */
    char handshake;    /* Hardware, XON/XOFF etc. */
    short lazy;        /* Pauses significant */
    char devname[30];
    short mole;        /* Mole indicator */
    struct dgmole mole_data;  /* Mole data */
    short interrupt;   /* 0=polled, 1=interrupt */
};

/* Mole structure */
struct dgmole {
    short mmethod; /* Mole toggle methods, 0 if not mole */
    short mbutton;                 /* Mole toggle button */
    short mcursor;        /* Number of buttons on cursor */
    short absrel;         /* Absolute or relative device */
    short hear;          /* Audible notify of mode change*/
    short see;           /* Visible notify of mode change*/
    short xinc;                  /* Steps in X direction */
    short yinc;                  /* Steps in Y direction */
    short mxl[5];               /* Mole X coordinate low */
    short mxh[5];              /* Mole X coordinate high */
    short myl[5];               /* Mole Y coordinate low */
    short myh[5];              /* Mole Y coordinate high */
    short motion_factor;        /* Scaling motion factor */
    short big_delta;  /* Throw out big mole mode changes */
};

Description
-----------
CINFO passes digitizer information from AutoCAD to the driver. Your driver
sees the dgedinfo structure with all the members filled in, except that in
the mole_data member, only mcursor contains valid data. Your driver should
not modify any CINFO packet members.

This packet is sent at configuration time and can be expected to
immediately precede an EINIT packet request. The EINIT packet request is
sent because of mole mode configuration that, if enabled, requires the
driver to be up and running at configuration time.



9.15.2 CINIT
==============

Purpose
-------
Configuration-time driver initialization.

Limitations
-----------
This must be the first CFG packet sent to OS/2 ADI 4.0, Windows ADI 4.1 and
P386 ADI 4.1 drivers. It should follow PWHO for ADI 4.2 drivers.

On UNIX platforms, CINIT should follow NCONN and should only be sent if
this is the first AutoCAD to connect to the digitizer server.

CINIT can only be sent at configuration time on any platform. The
controlling product must fill in member version with ADIPKTLEVEL and member
alias with the currently configured alias index. The controlling
application must examine member dgcode on return from the driver and
terminate the driver if the result is not OK. The driver can modify members
options, version, dgcode, and status.

The structure dgbxinit is used for both CINIT and EINIT. The structure
members io_addr, intnumb, numacads, hwnd, wTbPacket, hRgn,
lpTabletRegionStack, and lpTabletEnable are not used at configuration time;
they can remain uninitialized.

History
-------
This packet was introduced in OS/2 ADI 4.0. It was extended by the addition
of the options member in P386 ADI 4.0. The members io_addr and intnumb were
added in ADI 4.1 for use on P386. The member num_acads was added in UNIX
ADI 4.1. The group of #ifdef WIN members were added for Windows ADI 4.1.
The new options bit DG_RELATIVE was added in ADI 4.2. Some members
originally declared as int or unsigned were modified to more explicit
declarations during ADI 4.2 development.

Declaration
-----------
#define CINIT  7

struct dgbxinit {
    short dgcode;       /* CINIT */
    short dgsize;       /* Sizeof packet */
    short version;      /* ADI version number */
    short status;       /* Status code */
    short options;      /* Options required */
    char alias;         /* Alias ID */
#if WIN
    unsigned short io_addr;   /* Port address for int.mode */
    char intnumb;       /* IRQ # */
    short num_acads;    /* # of ACADs connected */
    HWND hwnd;          /* Graphics window handle */
    WORD wTbPacket;     /* System tablet packet message #*/
    HANDLE hRgn;        /* System tablet region handle */
    FARPROC lpTabletRegionStack; /* System tablet function */
    FARPROC lpTabletEnable;      /* System tablet function */
#else
    unsigned long io_addr;    /* Port address for int.mode */
    char intnumb;       /* IRQ # */
    long num_acads;     /* # of AutoCADs connected */
#endif  /* WIN */
};

Description
-----------
The structure dgbxinit is used for both CINIT and EINIT. The structure
members io_addr, intnumb, numacads, hwnd, wTbPacket, hRgn,
lpTabletRegionStack, and lpTabletEnable are not used at configuration time;
they are uninitialized.

AutoCAD calls the driver with member dgcode in struct dgbxinit set to
CINIT, member alias set to the alias ID, and member version set to the
current AutoCAD ADI version number. Any options required by the controlling
product are indicated by bits set by the product in member options. If the
driver is unable to operate in a requested optional mode, it should clear
the relevant option bit in the return packet.

Because more option flags might be added in later revisions of ADI, your
driver should test for option flags in a bitwise manner.

Table 9-4. Values for CINIT.options

Mnemonic         Value               Meaning if set

DRAGG            0x1  DRAGG mode required

DG_RELATIVE      0x2  relative mode required


DRAGG Mode
------------
AutoCAD 386 Release 11 sets the NODRAGG bit flag in member options. This
tells the driver to return one P_POINT when the pick button is first
pressed, and then to return P_NONE until it is released. AutoCAD Release 12
and 3D Studio v2.0 both set the DRAGG bit flag in member options,
requesting the driver to operate in DRAGG mode (continuing to return valid
coordinates while the pick button is down).

In DRAGG mode, a signal is sent to indicate that a button has been pressed
(along with valid coordinates and optional pressure), and then valid
coordinates (and optional pressure) continue to be sent while the button is
down. A new signal is sent when the button is released. If more than one
button is pressed, button-down and button-up signals are sent for each.

Thus in DRAGG mode when the pick button is pressed, P_POINT is returned
once with valid coordinates. Then P_COORD is repeatedly returned with valid
data until the pick button is released, at which time P_POINTUP is
returned. When a button other than the pick button is pressed, P_BUTTP is
returned with valid coordinates. Then P_COORD is repeatedly returned with
valid data until the button is released, at which time P_BUTTPUP is
returned.

Relative Mode
-------------
Many graphic tablets can operate in "mouse mode." AutoCAD doesn't use
relative mode. If a device operates in Mouse mode, AutoCAD requires the ADI
driver to convert relative coordinates to absolute coordinates (and to let
AutoCAD know the device is faking and can't operate as a digitizing tablet
by clearing the tablet flag member in the DETAIL or DETAIL_42 packet.

But relative mode is well adapted to most "paint" applications. These
applications can request the driver to return relative coordinates instead
of converting them to absolute values. Since there are some tablets that
don't support mouse mode, and some products that don't want this mode, this
feature is an option.

If the Autodesk product desires relative mode, it sets DG_RELATIVE in CINIT
and EINIT. If the device operates in relative mode, it leaves the
DG_RELATIVE bit set and proceeds to operate in relative mode. If the device
can't operate in relative mode, it clears the DG_RELATIVE bit and proceeds
in absolute mode.

In relative mode, the X, Y, and Z values returned to the Autodesk product
are deltas from the last sample. As with other ADI 4.2 digitizer data,
these are returned in unscaled "natural" coordinates for the device. The
members (see below) in the DETAIL_42 packet that specify coordinate range
return the natural coordinate change corresponding to one inch of movement
for X, Y, or Z. The angular range and pressure range values are returned as
they are for absolute mode.

Range values in DETAIL_42:

long x_max; /* Unsigned x coord range */
long y_max;
long z_max;

The values returned in dgexpkt for X, Y, and Z are signed deltas. The
values for pressure, ix, iy, and iz remain the same as in absolute mode,
and are data valid as of the time of the sample. In other words, each
digitizer sample consists of both position change information and current
orientation and pressure data.

The driver should return the options it is capable of handling in the
member options. The Autodesk product decides if it can use the driver in
cases where the driver fails to support all requested options.

Your driver should return a structure of type dgbxinit, with member dgcode
set to OK if the driver decides it can work with the ADI interface level
supplied by AutoCAD, or with dgcode set to BAD if it cannot.

Your driver should return its ADI version number (ADIPKTLEVEL) in member
version and it should return a type code in member status. The symbolic
constants used in ADI digitizer drivers are defined in the header file
dgp.h. ADI 4.2 drivers should return version as DG_LEVEL_42.

Here are the type codes for dgbxinit.status:

Table 9-5. Values for CINIT.status

Mnemonic       Value                            Meaning if Set

HARDWARE       0x0  This is a physical device other than the system mouse

NULLDIG        0x1  There is no digitizer

SYSTEM         0x2  This is a system mouse

AutoCAD Release 12 requests DRAGG mode from digitizers. Some release 12
features are compromised if DRAGG mode is not available.



9.15.3 CURSOR
===============

Purpose
-------
Sends AutoCAD a table of valid cursor types for the selected Digitizer
model.

Limitations
-----------
This is a configuration-time packet that should be sent after the DETAIL or
DETAIL_42 packet. The controlling application must fill in structure
dgcdmodel.

AutoCAD fills in all members of dgcdmodel. The ADI driver fills in all
members of dgcucursor.

History
-------
Introduced in OS/2 ADI 4.0.

Declaration
-----------
#define CURSOR  3

Application sends
-----------------
struct dgcdmodel {
    short dgcode;    /* CURSOR */
    short dgsize;    /* Sizeof packet */
    short model;     /* Model index */
};
Driver's response
-----------------
struct dgcucursor {
    short dgcode;             /* CURSOR */
    short dgsize;             /* Sizeof packet */
    short ncursors;           /* Number of cursors */
    char cursor[MAXCUR];      /* Table of valid cursors */
};

#define MAXCUR 16

Description
-----------
AutoCAD calls the driver with member dgcode in struct dgcdmodel set to
CURSOR and model set to the selected model index. The driver responds with
structure dgcucursor containing all valid cursors of the selected model.

Each entry in the member dgcucursor.cursor[] is the literal number of
buttons supported by a cursor supported by this device (e.g., 1, 4, 12,
etc.).

The dgcucursor.ncursors member should be initialized by your driver to the
number of valid cursors.



9.15.4 DETAIL
===============

Purpose
-------
DETAIL is sent after the user has selected the desired digitizer model. The
driver is told which model has been selected and in return tells AutoCAD
about some of the device's capabilities and communication parameters.

Limitations
-----------
This is a configuration-time packet that should be sent after MODEL to pre-
ADI 4.2 drivers. ADI 4.2 drivers should be sent DETAIL_42 instead.

It is the primary application's responsibility to find out from the user
which I/O port the digitizer is connected to. AutoCAD does this right after
sending the DETAIL packet.

AutoCAD fills in all members of dgcdmodel. The ADI driver fills in all
members of dgcudetail.

History
-------
DETAIL was introduced in OS/2 ADI 4.0. It was replaced by DETAIL_42 in ADI
4.2 for all platforms.

Declaration
-----------
#define DETAIL       2

Application sends
-----------------
struct dgcdmodel {
    short dgcode;    /* DETAIL */
    short dgsize;    /* Sizeof packet */
    short model;     /* Model index */
};

Driver's response
-----------------
struct dgcudetail {
    short dgcode;          /* DETAIL */
    short dgsize;          /* Sizeof packet */
    short tablet;          /* Tablet mode supported */
    short pauses;          /* pauses significant */
    short type;            /* Serial, Parallel, HPIB etc */
    short baud;            /* Baud rate */
    short parity;          /* Parity */
    short data;            /* Data bits/frame */
    short stop;            /* Stop bits/frame */
    short pmin, pmax;      /* Pressure sensing range */
    char handshake;        /* Hardware, XON/XOFF etc */
    short interrupt;       /* Interrupt or polled */
};

Description
-----------
AutoCAD calls the driver with member dgcode in struct dgcdmodel set to
DETAIL and member model set to the appropriate model index. Your driver
responds with struct dgcudetail with the appropriate values, described in
the following tables:

Table 9-6. Values for dgcudetail.tablet

Mnemonic      Value                    Meaning if Set

TABLET        0x1  Device sends absolute coordinates

NOTABLET      0x0  Relative pointing device; e.g., mouse

Don't confuse the tablet member with the DG_RELATIVE mode flag in
CINIT.options. The tablet member can be set to NOTABLET, indicating that
the device is really a mouse or other relative pointing device, but if
DG_RELATIVE wasn't requested, the device is still required to return
absolute coordinates. See the sample driver pharlap\dgpms.

Table 9-7. Values for DETAIL.pauses

Mnemonic       Value                     Meaning if Set

PAUSES         0x1  Pauses in data stream are significant

NOPAUSES       0x0  Pauses in data stream are not significant


Devices that only emit samples when moved set PAUSES. AutoCAD does not
block on input from such devices.

Table 9-8. Values for DETAIL.type

Mnemonic       Value                  Meaning if Set

NODEVICE       0x0  AutoCAD I/O is not used

SERIAL         0x1  Digitizer uses serial interface

PARALLEL       0x2  Digitizer uses parallel interface

HPIB           0x4  Digitizer uses HPIB interface

If it is possible for the user to configure your device for serial
communication, you must indicate the baud rate, parity, number of stop
bits, and handshaking method that the Autodesk product can expect.

The baud member should be initialized with the literal baud rate. For most
platforms, valid baud rate values are: 50, 75, 110, 134, 150, 200, 300,
600, 1200, 1800, 2400, 4800, 9600, and 19200. Note that some DOS systems
have UART chips that might be unreliable at 19200.

Table 9-9. Values for DETAIL.parity

Mnemonic       Value            Meaning if Set

NONE           0x0  No parity

ODD            0x1  Odd parity

EVEN           0x2  Even parity

MARK           0x3  Mark parity

SPACE          0x4  Space parity



Table 9-10. Values for DETAIL.stop

Value       Meaning if Set

0x1         One stop bit

0x2         Two stop bits



Table 9-11. Values for dgcudetail.handshake (see adihport.h)

Mnemonic              Value                  Meaning if Set

HANDSHAKE_XONXOFF     0x0  XON/XOFF handshake

HANDSHAKE_HARDWARE    0x1  Hardware handshake

HANDSHAKE_NONE        0x2  No flow control

HANDSHAKE_BOTH        0x3  Both hardware and XON/XOFF


On Windows, the handshake flags in DETAIL are honored for both reading and
writing.

For 386 and UNIX, no handshaking is enforced for either reading or writing
to digitizers. The handshake member has no meaning on these platforms.

The dgcudetail.pmin and dgcudetail.pmax members are used to return a range
of pressure values from pressure-sensitive devices. If your device does not
have a pressure-sensing stylus, return 0 in both of these members. If your
device has a pressure-sensing feature, return the minimum and maximum
possible values of pressure in pmin and pmax respectively. AutoCAD does not
use these pressure data.

Table 9-12. Values for dgcudetail.interrupt

Value         Meaning if Set

0x0           Polled mode

0x1           Interrupt mode

The polled or interrupt mode option should be given to the user at DETAIL
time, assuming your device supports both modes.

For P386 Platforms
------------------
If your device does not fully support interrupt mode, you should return 0
in dgcudetail.interrupt. If you return 0, indicating polled mode, AutoCAD
behaves as before. If you return a 1, indicating interrupt mode, AutoCAD
asks an additional question during I/O port configuration to get an IRQ
number from the user. This is returned to your driver in EINIT.intnumb at
execution time.

Until Release 11 386, AutoCAD has not used the hardware interrupt that
serial ports can generate, and it has been common for dealers to install
serial ports with no hardware IRQ. If you implement the interrupt mode
interface for your driver, a hardware IRQ is required. The user
documentation for your driver should emphasize this.

For UNIX Platforms
------------------
If your driver sets the interrupt member to 1, the ADI library operates the
serial port in interrupt mode and sends a DGSENSE packet whenever there is
input from your device. You should read the data using ior() and return the
sample in DGSENSE.

Example
-------
An example of interrupt mode is implemented in the sample driver, DGPSUMI.



9.15.5 DETAIL_42
==================

Purpose
-------
DETAIL_42 is sent after the user has selected the desired digitizer model.
The driver is told which model has been selected and in return tells
AutoCAD about the device's capabilities and communication parameters. Since
ADI 4.2 drivers return natural coordinates, part of the essential
information provided by the driver at DETAIL_42 time is the dynamic range
(domain) of the data the device can return.

Limitations
-----------
This is a configuration-time packet that should be sent after MODEL to ADI
4.2 drivers. Pre-ADI 4.2 drivers should be sent DETAIL instead. The
controlling application must fill in dgcode, dgsize, and model in structure
dgcdmodel.

It is the primary application's responsibility to find out from the user
which I/O port the digitizer is connected to. AutoCAD does this right after
sending the DETAIL_42 packet.

AutoCAD fills in all members of dgcdmodel. The ADI driver fills in all
members of dgcudetail_42.

History
-------
DETAIL_42 was introduced in 4.2. This is an expanded DETAIL packet with new
members for 3D and 6 degree of freedom data. Digitizer data has also been
extended to the natural range of the device, up to 32 bits.

Declaration
-----------
#define DETAIL_42  22

Application sends
-----------------
struct dgcdmodel {
    short dgcode;    /* DETAIL_42 */
    short dgsize;    /* Sizeof packet */
    short model;     /* Model index */
};
Driver's reply
--------------
struct dgcudetail_42 {
    short dgcode;          /* DETAIL_42 */
    short dgsize;          /* Sizeof packet */
    short tablet;          /* Tablet mode supported */
    short pauses;          /* Pauses significant */
    short type;            /* Serial, Parallel, HPIB etc */
    short baud;            /* Baud rate */
    short parity;          /* Parity */
    short data;            /* Data bits/frame */
    short stop;            /* Stop bits/frame */
    short pmin,pmax;       /* pressure sensing range */
    char handshake;        /* Hardware, XON/XOFF etc */
    short interrupt;       /* Interrupt or polled */
    char padding;          /* For alignment */
    long x_max;            /* Unsigned x coord range */
    long y_max;
    long z_max;
    long ix_max;           /* Roll angle range */
    long iy_max;
    long iz_max;
};

Description
-----------
AutoCAD calls the driver with member dgcode in struct dgcdmodel set to
DETAIL_42 and member model set to the appropriate model index. Your driver
responds with struct dgcudetail_42 with the appropriate values, described
in the following tables:

Table 9-13. Values for DETAIL_42.tablet

Mnemonic       Value                     Meaning if Set

TABLET         0x1  Device sends absolute coordinates

NOTABLET       0x0  Relative pointing device; e.g., mouse


Don't confuse the tablet member with the DG_RELATIVE mode flag in
CINIT.options. The tablet member can be set to NOTABLET, indicating that
the device is really a mouse or other relative pointing device, but if
DG_RELATIVE wasn't requested, the device is still required to return
absolute coordinates. See the sample driver pharlap\dgpms.

Table 9-14. Values for DETAIL_42.pauses

Mnemonic        Value                     Meaning if Set

PAUSES          0x1  Pauses in data stream are significant

NOPAUSES        0x0  Pauses in data stream are not significant

Devices that only emit samples when moved set PAUSES. AutoCAD does not
block on input from such devices.

Table 9-15. Values for DETAIL_42.type

Mnemonic       Value                  Meaning if Set

NODEVICE       0x0  AutoCAD I/O is not used

SERIAL         0x1  Digitizer uses serial interface

PARALLEL       0x2  Digitizer uses parallel interface

HPIB           0x4  Digitizer uses HPIB interface

If it is possible for the user to configure your device for serial
communication, you must indicate the baud rate, parity, number of stop
bits, and handshaking method the Autodesk product can expect.

The baud member should be initialized with the literal baud rate. For most
platforms, valid baud rate values are: 50, 75, 110, 134, 150, 200, 300,
600, 1200, 1800, 2400, 4800, 9600, and 19200. Note that some DOS systems
have UART chips that might be unreliable at 19200.

Table 9-16. Values for DETAIL_42.parity

Mnemonic       Value Meaning if Set

NONE           0x0   No parity

ODD            0x1   Odd parity

EVEN           0x2   Even parity

MARK           0x3   Mark parity

SPACE          0x4   Space parity



Table 9-17. Values for DETAIL_42.stop

Value        Meaning if Set

0x1          One stop bit

0x2          Two stop bits


Table 9-18. Values for DETAIL_42.handshake (see adihport.h)

Mnemonic               Value                 Meaning if Set

HANDSHAKE_XONXOFF      0x0  XON/XOFF handshake

HANDSHAKE_HARDWARE     0x1  Hardware handshake

HANDSHAKE_NONE         0x2  No flow control

HANDSHAKE_BOTH         0x3  Both hardware and XON/XOFF


On Windows, the handshake flags in DETAIL are honored for both reading and
writing to digitizers.

For 386 and UNIX, no handshaking is enforced for either reading or writing
to digitizers. The handshake member has no meaning on these platforms.

The DETAIL_42.pmin and DETAIL_42.pmax members are used to return a range of
pressure values from pressure-sensitive devices. If your device does not
have a pressure-sensing stylus, return 0 in both of these members. If your
device has a pressure-sensing feature, return the minimum and maximum
possible values of pressure in pmin and pmax respectively. AutoCAD does not
use these pressure data, but they are made available to ADI 4.2 display
drivers in PDIGTIZE_42 (see chapter 6).

If relative mode is not active (option bit DG_RELATIVE in CINIT/EINIT), the
DETAIL_42.x_max, DETAIL_42.y_max and DETAIL_42.z_max members are used to
return the natural data range (zero-based) of the digitizer in each axis.
If the digitizer lacks Z axis ability, it must return 0 for z_max.

If relative mode is active (option bit DG_RELATIVE in CINIT/EINIT), the
x_max, y_max and z_max members are used to return the data range (zero-
based) of the digitizer, which corresponds to one inch of movement in each
axis. If the digitizer lacks Z axis ability, it returns 0 for z_max.

Likewise, DETAIL.ix_max, DETAIL.iy_max, and DETAIL.iz_max are used to
return the natural data range for rotation about each axis. Devices that do
not support ix, iy, or iz simply return zero for these values.

The structure members ix_max, iy_max, and iz_max specify rotations about
the X, Y, and Z axes in 3-space. If you picture an airplane with its X-axis
parallel to the fuselage and its Y-axis parallel to the wings, ix is roll
or rotation about the X-axis; iy is pitch or rotation about the Y-axis; and
iz is yaw or rotation about the Z-axis.

Since the order in which you apply these rotations can produce different
orientations, we suggest that the order of rotations be applied in the
order X, Y, then Z. The direction of rotation about an axis is defined by
the right-hand rule.

In other words, if you are looking down the X-axis from a point in the
positive x direction towards the origin, the rotation would be applied
counter-clockwise. A reference point from which to apply the rotation
(i.e., from where to measure 0 degrees) is defined as any point on the
positive Z-axis for an X rotation; any point on the positive X-axis for a y
rotation; and any point on the positive Y-axis for a Z rotation. The number
of degrees to apply to a rotation is defined this way:

ix * (360 / (ix_max + 1))

where ix <= ix_max

AutoCAD does not yet make use of Z, roll, pitch and yaw data, but these are
made available to ADI 4.2 display drivers via PDIGTIZE_42.

Table 9-19. Values for DETAIL_42.interrupt

Value         Meaning if Set

0x0           Polled mode

0x1           Interrupt mode

The polled or interrupt mode choice should be a user option at DETAIL time,
assuming your device supports both modes. Some users' systems might be
interrupt-bound and thus unable to configure an IRQ for the digitizer port.

For P386 Platforms
------------------
If your device does not fully support interrupt mode, you should return 0
in dgcudetail.interrupt. If you return 0, indicating polled mode, AutoCAD
behaves as before. If you return a 1, indicating interrupt mode, AutoCAD
asks an additional question during I/O port configuration to get an IRQ
number from the user.

Until release 11, AutoCAD 386 did not use the hardware interrupt that
serial ports can generate, and it has been common for dealers to install
serial ports with no hardware IRQ. If you implement the interrupt mode
interface for your driver, a hardware IRQ is required. The user
documentation for your driver should emphasize this.

For UNIX Platforms
------------------
If your driver sets the interrupt member to 1, the ADI library operates the
serial port in interrupt mode and sends a DGSENSE packet whenever there is
input from your device. You should read the data using ior() and return the
sample in DGSENSE.

Example
-------
An example of interrupt mode is implemented in the sample driver, DGPSUMI.

See Also
--------
The ADI 4.2 dispatcher service, recfgport() allows a driver to modify its
communication parameters at execution time.



9.15.6 MODEL
==============

Purpose
-------
Solicits model names from the driver.

Limitations
-----------
MODEL is a configuration-time packet that should be sent after CINIT. The
controlling application sends MODEL once with member model set to 1. The
driver returns the number of models it supports. The controlling
application sends (nmodels-1) more MODEL packets to get a list of model
names from the driver.

It is the controlling application's responsibility to present the user with
a menu of models (if there are several) and solicit a choice. The resulting
model table index must be saved for future use.

AutoCAD fills in all members of this packet. The ADI driver modifies
nmodels, model, and mname.

History
-------
Introduced in OS/2 ADI 4.0.

Declaration
-----------
#define MODEL    1
#define MNAMLEN 32

struct dgcumodel {
    short dgcode;        /* MODEL */
    short dgsize;        /* Sizeof packet */
    short nmodels;    /* Total number of models in driver */
    short model;         /* Model index */
    char mname[MNAMLEN]; /* Model name */
};

Description
-----------
To get the list of digitizer models, AutoCAD usually has to make multiple
packet requests to a particular driver. To solicit model names from the
driver, AutoCAD sends the structure dgcumodel with dgcode set to MODEL and
model set to 1.

In structure dgcumodel, your driver should set the nmodels member to the
number of models supported by your driver. The model member is set to 1 for
the first model and the character string mname[] contains the model name.

Upon receiving the first packet back from the driver, AutoCAD tries to
allocate ((nmodels) * MNAMLEN) bytes to store the model names. If
successful, AutoCAD makes another (nmodels-1) request to the driver, each
time incrementing the value of model in structure dgcumodel.

Your driver should always set model to the model index being returned. If
AutoCAD requests a nonexistent model, you should set model to 0.



9.15.7 NCONN
==============

Purpose
-------
Gets the number of currently connected AutoCAD sessions from the ADI
library. This is a UNIX-only packet.

Limitations
-----------
On any UNIX platform that supports the digitizer server (i.e., that allows
one digitizer driver to serve multiple AutoCAD sessions), NCONN must be the
first packet sent to an ADI 4.1 UNIX digitizer and the third packet (after
PWHO and PLANG) sent to an ADI 4.2 UNIX digitizer.

This is a UNIX-only packet and is not supported on other platforms.

AutoCAD fills in all members of this packet. The ADI driver never sees this
packet; it is intercepted by library code, which modifies member num_acads.

History
-------
Introduced for UNIX ADI 4.1. Some members originally declared as int or
unsigned were modified to more explicit declarations during ADI 4.2
development.

Declaration
-----------
#define NCONN  16

struct dgbxinit {
    short dgcode;       /* NCONN */
    short dgsize;       /* Sizeof packet */
    short version;      /* ADI version number */
    short status;       /* Status code */
    short options;      /* Options required */
    char alias;         /* Alias ID */
#if WIN
    unsigned short io_addr; /* Port address for int.mode */
    char intnumb;       /* IRQ # */
    short num_acads;    /* # of ACADs connected */
    HWND hwnd;          /* Graphics window handle. */
    WORD wTbPacket;     /* System tablet packet message # */
    HANDLE hRgn;        /* System tablet region handle */
    FARPROC lpTabletRegionStack; /* System tablet function */
        FARPROC lpTabletEnable; /* System tablet function */
#else
    unsigned long io_addr; /* Port address for int.mode */
    char intnumb;       /* IRQ # */
    long num_acads;     /* # of AutoCADs connected */
#endif  /* WIN */

Description
-----------
The NCONN packet request is sent by AutoCAD before CINIT. The ADI library
(dgalib.a) fills in member num_acads with the number of AutoCAD sessions
currently connected to your driver.

Note: Your driver should not receive the NCONN packet request and no action
is required. It is intercepted by the ADI library that fills in member
num_acads with the number of AutoCAD sessions currently connected.


9.15.8 PLANG
==============

Purpose
-------
Lets digitizer drivers know the language and code page in use by AutoCAD.
This is helpful in internationalization of drivers.

Limitations
-----------
PLANG should be the second packet sent to ADI 4.2 and later digitizer
drivers at both configuration time and execution time. This packet should
not be sent to pre-ADI 4.2 drivers. It is sent only by the primary
application and should not be used by secondary applications.

AutoCAD fills in all members of this packet. The ADI driver treats it as
read-only.

History
-------
The use of PLANG for digitizer drivers was added in ADI 4.2 to support
AutoCAD Release 12.

Declaration
-----------
#define PLANG  24   /* For digitizer drivers (see plp.h) */
struct pklang {
    short pfunc;                       /* PLANG for DEV_DG */
    short cchar;                       /* Check mark value */
    short options;                     /* Option flag bits */
    short maxchar;           /* Highest numbered char code */
    char  lang[MAX_LAN + 1];         /* Language ID string */
    char  code_page[MAX_COP + 1];        /* Code page name */
};
Description
-----------
The ADI interface was originally designed to handle only 128 ASCII
characters, with character 128 having the special meaning of a check mark
for dialogue boxes. As overseas editions of AutoCAD have begun to use ADI
drivers, it has become necessary to extend the range of characters sent to
display drivers. Due to conflicts with some countries' character definition
conventions, these "8-bit font" versions of AutoCAD redefine the check mark
character to another value, often 255. PLANG is sent to display drivers to
negotiate the handling of this issue.

In ADI 4.2 PLANG is also sent to plotter and digitizer drivers as an
informational packet; AutoCAD does not examine the packet returned by the
driver. Note that different packet codes are used for PLANG for the
different device types (DEV_DS, DEV_PL and DEV_DG).

Table 9-20. Bit flag values for PLANG.options

Mnemonic        Value              Meaning if Set

FF_8BIT         0x1  FONT8BIT is active.

FF_SYSMENU      0x2  System has a menu bar.

The FF_SYSMENU option bit is used on some windowing platforms to inform a
display driver that a system menu bar is supported.

PLANG has been extended in ADI 4.2 with two new members: lang and
code_page. These members inform the driver of the command language and code
page AutoCAD believes are currently in use. These are derived from the
software environment and not as a result of polling the keyboard or other
hardware.

The values for the lang and code_page members of PLANG are the same as the
lang and code_page members of the RDLANG packet. See the tables in the
RDLANG packet description in chapter 8 for these values.

Ctype Functions
---------------
We have added new dispatcher functions to export ctype functions that have
been correctly internationalized. See chapter 4, ADI Dispatcher, for
complete information on ctype functions.



9.15.9 PWHO
=============

Purpose
-------
PWHO lets the digitizer driver know which product is executing the driver.

Limitations
-----------
This should be the first packet sent to an ADI 4.2 or later digitizer at
configuration time with PWHO.action set to WHO_CFG. It is the controlling
application's duty to fill in pfunc, psize, product, prod_version,
adipktlevel, action, serial, regapp_name (if ADS application), and cpid (if
UNIX). It is also desirable for the controlling application to fill in
cleanup with 0 and status with GOOD, in case a driver fails to fill them
in.

Applications that lack a serial number should stuff EOS into member serial.
Applications such as AVE Render that load a driver but do not support alias
device names should stuff 0 in member alias.

AutoCAD fills in pfunc, psize, product, prod_version, adipktlevel, action,
screen (0 for digitizers), alias, serial, driver_path, and cpid. The ADI
driver fills in cleanup (0 for digitizers), driver_name, and dpid.

AutoCAD Release 12 fills in adipktlevel with DG_LEVEL_42.

History
-------
PWHO was added for digitizers for release 12 in ADI 4.2. The structure was
modified several times during ADI 4.2 development by adding new members and
by changing ints to longs.

Declaration
-----------
#define PWHO  21        /* PWHO for digitizers */

struct pkwho {
    short pfunc;        /* PWHO for digitizers */
    short psize;        /* PKWHOSIZE */
    short product;      /* Product code */
    short prod_version; /* Revision level of product */
    short adipktlevel;  /* ADI interface level for product */
    short status;       /* Driver can return status here */
    short cleanup;   /* Driver can return cleanup requests */
    short action;       /* App can request actions */
    short screen;       /* Display states requested */
    long alias;         /* Display driver alias index */
    char  serial[WHO_SERIAL_SIZE]; /* ASCIIZ serial number */
    char  regapp_name[WHO_REGAPP_NAME_SIZE];
    char  driver_name[DEVNAMSZ + 1]; /* ASCIIZ driver name */
    char driver_path[MAXPATHLEN]; /* Where driver found */
#ifdef UNIX
    long cpid;     /* Controlling application's UNIX pid */
    long dpid;                      /* Driver's UNIX pid */
#endif /* UNIX */
};

#define PKWHOSIZE (sizeof(struct pkwho))
#define WHO_SERIAL_SIZE 32
#define WHO_REGAPP_NAME_SIZE 32

Description
-----------
PWHO is sent by Autodesk products very early in configuration time with
PWHO.action set to WHO_CFG and very early in execution time with
PWHO.action set to WHO_XQT. The idea is to let drivers know which product
is in control before the driver has to respond to any requests from the
product.

This packet is also sent by AutoCAD at an application's request (in
ads_adistart() or ads_adiend()).

The member pfunc is defined differently for each device type, in the C
header file for each device type (e.g., dgp.h, plp.h, etc.). The structure
definition for pkwho and the definitions for products and versions are
defined in a new C header file, who.h.

The product ID number is unique for each Autodesk product. The header file
who.h defines these ID numbers. ID number zero is reserved for unknown (non-
Autodesk) primary products, for example:

Table 9-23. Values for PWHO.product

Mnemonic          Value                Meaning

WHO_UNKNOWN       0     Unknown primary product

WHO_ACAD          1     AutoCAD

WHO_SHADE         2     Outside

WHO_SKETCH        3     AutoSketch

WHO_STUDIO        4     3D Studio

WHO_AME           5     AME

WHO_REND          7     AVE Render

WHO_AUNK          0x2000               Unknown ADS application

WHO_TUNK          0x4000               Unknown TEE application

Note that TEE applications are unable to provide cleanup services. Such
applications should return WHO_TUNK in the product field to let ADI drivers
know that a TEE driver is operating and that cleanup services can't be
expected.

The member prod_version is made up of two parts: the upper 8 bits form the
major version number, while the lower 8 bits form a minor version number.
Thus, the first release of AutoCAD Release 12 would be 0x100 while a second
update release would be 0x101. As each new product or version is designed,
the author makes a code submission to update who.h, thus reserving a
number.

Table 9-24. Values for PWHO.prod_version

Mnemonic       Value Meaning

WHO_R12        0x100 For AutoCAD Release 12 initial release

WHO_AME2       0x100 AME 2.0


adipktlevel is sent from the Autodesk product to the ADI driver, indicating
which ADI interface level the user has selected. For most types of ADI
there are two parallel numbering systems: intlevel and adipktlevel. The
intlevel numbers are an old system that proceeds sequentially. The
adipktlevel is a newer system with the lower 4 bits of the version
indicating minor revisions and the remaining bits indicating major version
changes.

The member status is normally returned as GOOD. If it is returned as BAD,
the driver is indicating that it cannot work with the indicated product,
version, and interface level.

Table 9-25. Values for PWHO.status

Mnemonic              Value  Meaning

GOOD                  0      Can work with product, etc.

BAD                   -1     Nonspecific failure

ADI_BAD_VERSION       -2     Incompatible ADI version

ADI_BAD_APP           -3     This driver won't work with this app

ADI_BAD_SERIAL        -4     Serial number violation

ADI_BAD_PROD_VER      -5     Incompatible product version

The product's serial number is appended to this packet as a null-terminated
ASCII string. This allows vendors to easily lock their products to a single
serial number, if they like. Autodesk serial numbers are two ASCII integers
separated by a dash.

The member alias is filled in by AutoCAD at WHO_CFG and WHO_XQT time for
display drivers with an alias index. If the display driver has only one
device name, alias is zero. If the driver has more than one devname string,
AutoCAD returns the index of the selected devname.

The regapp_name member is for ADS applications, a null-terminated string
returned by the application in ads_regapp().

The driver_name field is filled in by the ADI driver to pass a null-
terminated ASCII string (the currently configured dev_name string from the
edevent struct) to any application (particularly secondary applications)
wanting to know the identity of the current driver.

The driver_path member is sent from the primary product (e.g., AutoCAD) to
inform the driver of the full path from which the driver was loaded. This
is filled in by the primary product at configuration time and at execution
time. PWHO packets emitted by secondary applications don't have this filled
in.

The member cpid is used only on UNIX platforms; it passes the controlling
application's process ID to the driver. Both primary and secondary
applications are required to fill in cpid. The member dpid returns the
driver's UNIX process ID.

Table 9-26. Values for PWHO.action

Mnemonic         Value                          Meaning

WHO_CFG          1    Indicates configuration time, main application

WHO_XQT          2    Indicates execution time, main application

WHO_START        3    Used by secondary app on first takeover

WHO_PAUSE        4    Temporary end of secondary app takeover

WHO_RESUME       5    Secondary application resumes control

WHO_END          6    Secondary application terminates

When the primary product (e.g., AutoCAD) starts up in configuration, it
sets PWHO.action to WHO_CFG. When the primary product starts at execution
time, it sets WHO_XQT. If a secondary application, via a TEE driver or an
ADS link takes over an ADI driver temporarily, it sets the action member to
WHO_START in a PWHO packet sent at its first takeover. At the end of its
takeover of the device, it sets action to either WHO_PAUSE or WHO_END. A
PWHO packet with WHO_PAUSE tells the driver that the application plans to
take over again but is temporarily returning control to the primary
application. A PWHO packet with WHO_END indicates that the secondary
application does not expect to take over again.

It is incorrect for an application to send two WHO_START actions without an
intervening WHO_END.

The screen and cleanup members are used only for display drivers and are
empty for digitizers.

This is one of two digitizer packets whose first member is not dgcode but
pfunc.



9.16 Execution-Time Packet Descriptions
=======================================

Digitizer packets and symbolic constants are defined in dgp.h. The packet
descriptions in this chapter are presented alphabetically in two sections:
configuration-time and execution-time packets.

9.16.1 ACTIVATE
=================

Purpose
-------
ACTIVATE is sent by AutoCAD to tell the library code linked with your
driver to start getting samples from your device and to find out whether
the driver is in digitizer or mouse mode. The ADI library code responds to
this packet request.

Limitations
-----------
The ACTIVATE packet can be sent only to ADI 4.1 and later UNIX digitizer
drivers. ACTIVATE is an execution-time packet. It should be sent after
EINIT. It tells the digitizer library code to start up the driver and send
samples back. It also receives the mode the driver is operating in.

AutoCAD fills in the members of this packet. The ADI driver doesn't see
this packet; it is intercepted by library code.

History
-------
Introduced in ADI 4.1 for UNIX platforms.

Declaration
-----------
#define ACTIVATE 15

For ADI 4.1 drivers
-------------------
struct dgexpkt {
    short dgcode;       /* ACTIVATE Command code */
    short dgsize;       /* Sizeof packet */
    short buttn;        /* Button code */
    short x, y;         /* x and y values */
    short pressure;     /* Stylus pressure */
    short dgstat;
};

#define DGEXPKTSIZE (sizeof(struct dgexpkt))
For ADI 4.2 drivers
-------------------
struct dgbxinit {
    short dgcode;       /* ACTIVATE */
    short dgsize;       /* Sizeof packet */
    short version;      /* ADI version number */
    short status;       /* Status code */
    short options;      /* Options required */
    char alias;         /* Alias ID */
#if WIN
    unsigned short io_addr;   /* Port address for int.mode */
    char intnumb;                                 /* IRQ # */
    short num_acads;            /* # of AutoCADs connected */
    HWND hwnd;                   /* Graphics window handle */
    WORD wTbPacket;      /* System tablet packet message # */
    HANDLE hRgn;            /* System tablet region handle */
    FARPROC lpTabletRegionStack;/* System tablet function. */
        FARPROC lpTabletEnable; /* System tablet function. */
#else
    unsigned long io_addr;    /* Port address for int.mode */
    char intnumb;                                 /* IRQ # */
    long num_acads;             /* # of AutoCADs connected */
#endif  /* WIN */

#define MOUSEMODE 18
#define DIGITIZERMODE 19
#define NODIGITIZER 20

Description
-----------
At execution time, structure dgbxpkt can be sent to ADI 4.1 driver and
dgbxinit can be sent to ADI 4.2 drivers with member dgcode set to ACTIVATE.
The library code intercepts this packet request, starts your driver sending
samples, and returns in member dgcode a tag that indicates which mode your
driver is operating in: DIGITIZERMODE, NODIGITIZER, or MOUSEMODE.

Note: your ADI driver should not receive nor see the ACTIVATE, MOUSEMODE,
DIGITIZER, or NODIGITIZER packet requests. They are intercepted by the ADI
library code and the library code returns which mode your driver is
operating in. They are documented here for information only (they are
declared in dgp.h).



9.16.2 ASHELL
===============

Purpose
-------
Notifies the driver that a Shell command has completed.

Limitations
-----------
This should be the first packet sent after a Shell command.

AutoCAD fills in all members, the ADI driver treats it as read-only.

History
-------
Introduced in ADI 4.1.

Declaration
-----------
#define ASHELL  12    /* after shell notification */
struct dgedshell {
    short dgcode;     /* ASHELL */
    short dgsize;     /* Sizeof packet */
};

Description
-----------
The ASHELL packet is sent when a Shell command is complete.

If your driver implements interrupt mode, it must reconnect its interrupt
handler. Any driver that does its own I/O, indicated by returning the
NODEVICE flag in the DETAIL reply packet, and that uses serial I/O should
reinitialize its serial port at this time (the port settings might have
been modified during the Shell command).

You might also want to reinitialize the digitizing device if the user might
have disturbed its state during the Shell command.

See Also
--------
BSHELL



9.16.3 BSHELL
===============

Purpose
-------
Notifies the driver when a Shell command is about to begin.

Limitations
-----------
This should be the last packet sent before a Shell command is executed by
AutoCAD.

AutoCAD fills in this packet. The ADI driver treats it as read-only.

History
-------
Added in ADI 4.1.

Declaration
-----------
#define BSHELL  13        /* before shell notification */
struct dgedshell {
    short dgcode;         /* BSHELL */
    short dgsize;         /* Sizeof packet */
};

Description
-----------
The BSHELL request is issued when a Shell command is about to begin.

Most polled or Stream mode drivers can ignore this packet. An interrupt
mode digitizer driver must disconnect its interrupt routine in preparation
for the AutoCAD Shell command.

See Also
--------
ASHELL



9.16.4 DGSENSE
================

Purpose
-------
Requests a digitizer sample from the driver.

Limitations
-----------
This packet is sent when AutoCAD prior to release 12 wants a digitizer
sample or if release 12 is running with a pre-ADI 4.2 digitizer driver. It
must be sent after initialization has been completed (PWHO, PLANG, NCONN,
ACTIVATE, EINFO, EINIT).

AutoCAD fills in dgcode and dgsize. The ADI driver fills in dgcode, buttn,
x, y, and pressure. Library code modifies dgcode and dgstat on some
platforms.

History
-------
Introduced in OS/2 ADI 4.0 for release 10. Expanded in P386 ADI 4.1 by the
addition of the pressure member and expanded again in UNIX ADI 4.1 by the
addition of the dgstat member. Replaced by DGSENSE_42 in ADI 4.2.

Declaration
-----------
#define DGSENSE  6
struct dgexpkt {
    short dgcode;       /* DGSENSE */
    short dgsize;       /* Sizeof packet */
    short buttn;        /* Button code */
    short x, y;         /* x and y values */
    short pressure;     /* Stylus pressure */
    short dgstat;       /* Used only by library code */
};

Description
-----------
UNIX ADI library code uses member dgstat to transform the DGSENSE packets
returned by your driver into a form suitable for our socket or pipe-based
interface. You can code your driver normally and ignore the dgstat member.

When AutoCAD wants to read a sample from the driver it sets dgcode in
structure dgexpkt to DGSENSE and sends the packet to the driver. Your
driver responds by returning the structure dgexpkt with the members
assigned values according to the table below:

Table 9-27. Possible responses for struct dgexpkt members

dgcode          value           buttn    x         y

P_NONE          0    (none)     X coordinate       Y coordinate

P_COORD         2    (none)     X coordinate       Y coordinate

P_POINT         3    (none)     X coordinate       Y coordinate

P_BUTTN         4    Button number       (none)    (none)

P_BUTTP         5    Button number       X coordinate  Y coordinate

P_BUTTPUP       8    Button number       X coordinate  Y coordinate

P_POINTUP       7    (none)     X coordinate       Y coordinate

The symbolic constants for member dgcode are defined in the dgp.h header
file. The P_NONE flag indicates that the pointer has nothing to report. No
action is taken by AutoCAD. The driver can return this code when waiting
for a button to be released following a selection if DRAGG mode is not
active. AutoCAD does not perform this function; it is the responsibility of
the installed driver (as is any debouncing of buttons).

In DRAGG mode, P_NONE is returned when the puck or stylus is not in contact
with the tablet.

P_COORD indicates that a tracking coordinate pair is returned in X and Y.
The X and Y coordinates returned must fall within the range of 0 to 20480,
inclusive. P_COORD is used to return coordinates when the pick button is
not pressed (in NODRAGG mode). In this case AutoCAD tracks with the screen
or menu cursor.

In DRAGG mode, P_COORD should be returned as long as the puck or stylus is
on the tablet, with the exception of button-up or button-down transitions.

P_POINT indicates that a picked coordinate pair is returned in X and Y. The
X and Y coordinates returned must fall within the range of 0 to 20480,
inclusive. P_POINT is used to return the coordinates when the pick button
is first pressed.

P_BUTTN should not be used unless the driver is unable to return the button
number and the coordinates of the pointer at the time of a button pick. You
should use P_BUTTP if possible.

P_BUTTP indicates a button was pressed and that the button number and the
coordinates of the pointer at the time of the button pick are returned. The
button number is returned in buttn and the coordinates of the picked point
are returned in members x and y.

P_BUTTPUP indicates that a button has been released. The button number and
the coordinates of the pointer at the time of the button release are
returned. The button number is returned in buttn and the coordinates of the
picked point are returned in x and y. This code is returned only if DRAGG
mode is active, otherwise P_COORD is used.

P_POINTUP indicates that the pick button has just been released in DRAGG
mode. It is not used if DRAGG mode is inactive.

The values P_POINT, P_BUTTN, P_BUTTP, P_POINTUP, and P_BUTTPUP are returned
only on button state transitions.

The member pressure is returned with 0 if your device does not sense
pressure. Otherwise, it should contain the current pressure value, which
must be between pmin and pmax (returned in the DETAIL reply packet),
inclusive.

UNIX ADI 4.1 and later digitizers must support, and are usually asked to
operate in, DRAGG mode.



9.16.5 DGSENSE_42
===================

Purpose
-------
Requests a digitizer sample from the driver.

Limitations
-----------
This packet is sent when AutoCAD Release 12 wants a digitizer sample from
an ADI 4.2 digitizer driver. It must be sent after initialization has been
completed (PWHO, PLANG, NCONN, ACTIVATE, EINFO, EINIT).

AutoCAD fills in dgcode and dgsize. The ADI driver fills in dgcode, buttn,
x, y, z, ix, iy, iz, and pressure. Library code modifies dgcode and dgstat
on some platforms.

History
-------
Introduced in ADI 4.2 to replace DGSENSE.

Declaration
-----------
#define DGSENSE_42  23
struct dgexpkt_42 {
    short dgcode;     /* Command code */
    short dgsize;     /* Sizeof packet */
    short buttn;      /* Button code */
    long x, y, z;     /* 3-D data */
    long ix, iy, iz;  /* Roll, pitch, yaw */
    short pressure;   /* Stylus pressure */
    short dgstat;
};

Description
-----------
UNIX ADI library code uses member dgstat to transform the DGSENSE packets
returned by your driver into a form suitable for our socket or pipe-based
interface. You can code your driver normally and ignore the dgstat member.

When AutoCAD wants to read a sample from the driver it sets dgcode in
structure dgexpkt to DGSENSE and sends the packet to the driver. Your
driver responds by returning the structure dgexpkt with the members
assigned values according to the table below.

Table 9-28. Possible responses for struct dgexpkt_42 members

dgcode         value buttn     x        y

P_NONE         0     (none)    X coordinate      Y coordinate

P_COORD        2     (none)    X coordinate      Y coordinate

P_POINT        3     (none)    X coordinate      Y coordinate

P_BUTTN        4     Button number      (none)   (none)

P_BUTTP        5     Button number      X coordinate   Y coordinate

P_BUTTPUP      8     Button number      X coordinate   Y coordinate

P_POINTUP      7     (none)    X coordinate      Y coordinate

The symbolic constants for member dgcode are defined in the dgp.h header
file. The P_NONE flag indicates that the pointer has nothing to report. No
action is taken by AutoCAD. The driver can return this code when waiting
for a button to be released following a selection if DRAGG mode is not
active. AutoCAD does not perform this function; it is the responsibility of
the installed driver (as is any debouncing of buttons).

In DRAGG mode, P_NONE is returned when the puck or stylus is not in contact
with the tablet or if it is outside of the active tablet area.

P_COORD indicates that a tracking coordinate pair is returned in X and Y.
The X and Y coordinates returned must fall within the range of 0 to x_max,
y_max, inclusive (the values returned in DETAIL_42). P_COORD is used to
return coordinates when the pick button is not pressed (in NODRAGG mode).
In this case AutoCAD tracks with the screen or menu cursor.

In DRAGG mode, P_COORD should be returned as long as the puck or stylus is
on the tablet, with the exception of button-up or button-down transitions.

P_POINT indicates that a picked coordinate pair is returned in X and Y. The
X and Y coordinates returned must fall within the range of 0 to x_max,
y_max, inclusive. P_POINT is used to return the coordinates when the pick
button is first pressed.

P_BUTTN should not be used unless the driver is unable to return the button
number and the coordinates of the pointer at the time of a button pick. You
should use P_BUTTP if possible.

P_BUTTP indicates a button was pressed and that the button number and the
coordinates of the pointer at the time of the button pick are returned. The
button number is returned in buttn and the coordinates of the picked point
are returned in members x and y.

P_BUTTPUP indicates that a button has been released. The button number and
the coordinates of the pointer at the time of the button release are
returned. The button number is returned in buttn and the coordinates of the
picked point are returned in x and y. This code is returned only if DRAGG
mode is active, otherwise P_COORD is used.

P_POINTUP indicates that the pick button has just been released in DRAGG
mode. It is not used if DRAGG mode is inactive.

The values P_POINT, P_BUTTN, P_BUTTP, P_POINTUP, and P_BUTTPUP are returned
only on button state transitions.

The member pressure is returned with 0 if your device does not sense
pressure. Otherwise, it should contain the current pressure value, which
must be between pmin and pmax (returned in the DETAIL reply packet),
inclusive.

The values for z, ix, iy, and iz should be returned with 0 if your device
doesn't support them. Otherwise they should return the current values
(within the range 0 to z_max, ix_max, iy_max, and iz_max as defined the
DETAIL_42).

The structure members ix, iy, and iz specify rotations about the X, Y, and
Z axes in 3-space. If you picture an airplane with its X-axis parallel to
the fuselage and its Y-axis parallel to the wings, ix is roll or rotation
about the X-axis; iy is pitch or rotation about the Y-axis; and iz is yaw
or rotation about the Z-axis. Since the order in which you apply these
rotations can produce different orientations, we propose here that the
order of rotations be applied in the order X, Y, then Z. The direction of
rotation about an axis is defined by the right-hand rule. In other words,
if you are looking down the X-axis from a point in the positive X direction
towards the origin, the rotation would be applied counter-clockwise. A
reference point from which to apply the rotation (i.e. from where to
measure 0 degrees) is defined as any point on the positive Z-axis for an X
rotation; any point on the positive X-axis for a Y rotation; and any point
on the positive Y-axis for a Z rotation. The number of degrees to apply to
a rotation is defined this way: (ix * (360 / (ix_max + 1))), where
ix <= ix_max.

Relative Mode
-------------
Many graphic tablets are capable of operating in mouse mode. AutoCAD
doesn't use relative mode. If a device operates in Mouse mode, AutoCAD
requires the ADI driver to convert relative coordinates to absolute
coordinates (and to let AutoCAD know the device is faking and can't really
operate as a digitizing tablet by clearing the tablet flag member in the
DETAIL or DETAIL_42 packet).

But relative mode is well adapted to most "paint" applications. These
applications can request the driver to return relative coordinates instead
of converting them to absolute values. Since some tablets don't support
Mouse mode, and some products don't want this mode, this feature is an
option.

In relative mode, the X, Y, and Z values returned to the Autodesk product
are deltas from the last sample. As with other ADI 4.2 digitizer data,
these are returned in unscaled "natural" coordinates for the device. The
members (see below) in the DETAIL_42 packet that specify coordinate range
returns the natural coordinate change corresponding to one inch of movement
for X, Y, or Z. The angular range and pressure range values are returned as
they are for absolute mode.

Range values in DETAIL_42:

long x_max; /* Unsigned x coord range */
long y_max;
long z_max;

The values returned in dgexpkt for X, Y, and Z are signed deltas. The
values for pressure, ix, iy, and iz remain the same as in absolute mode and
are data valid as of the time of the sample. In other words, each digitizer
sample consists of both position change information and current orientation
and pressure data.

ADI 4.2 digitizers must support and are usually asked to operate in DRAGG
mode.

AutoCAD (through release 12) does not use relative mode for digitizers. 3D
Studio V2.0 uses relative mode.



9.16.6 DGTERM
===============

Purpose
-------
Tells the driver to prepare to be terminated.

Limitations
-----------
This should be the last packet sent to a digitizer driver.

AutoCAD fills in dgcode, the ADI driver treats this packet as read-only.

History
-------
This packet was introduced in OS/2 ADI 4.0.

Declaration
-----------
#define DGTERM  5
struct dgexpkt {
    short dgcode;       /* DGTERM */
    short dgsize;       /* Sizeof packet */
    short buttn;        /* Button code */
    short x, y;         /* x and y values */
    short pressure;     /* Stylus pressure */
};
Description
-----------
Before unloading the driver, member dgcode in structure dgexpkt is set to
DGTERM by AutoCAD. Your driver should clean up any dangling resources and
call dispterm().

On 386 Platforms
----------------
AutoCAD unloads your driver after you return from handling this packet. Do
not exit to DOS.

On UNIX Platforms
-----------------
Your driver should call dispterm(). The ADI library code intercepts this
packet after your driver has handled it.

The ADI library checks to see if there are any other active AutoCAD
sessions using your driver. If not, the pipes are closed and the driver
terminated. Your driver should not exit to the O/S.



9.16.7 EINIT
==============

Purpose
-------
Execution-time initialization.

Limitations
-----------
This packet should be sent at execution time after EINFO.

AutoCAD fills in all members of this packet. The ADI driver can modify
members dgcode, version, status and options.

History
-------
This packet was introduced in OS/2 ADI 4.0. It was extended by the addition
of the options member in P386 ADI 4.0. The members io_addr and intnumb were
added in ADI 4.1 for use on P386. The member num_acads was added in UNIX
ADI 4.1. The group of #ifdef WIN members were added for Windows ADI 4.1.
The new options bit DG_RELATIVE was added in ADI 4.2. Some members
originally declared as int or unsigned were modified to more explicit
declarations during ADI 4.2 development.

Declaration
-----------
#define EINIT  8          /* Execution time INIT */

struct dgbxinit {
    short dgcode;       /* EINIT */
    short dgsize;       /* Sizeof packet */
    short version;      /* ADI version number */
    short status;       /* Status code */
    short options;      /* Options required */
    char alias;         /* Alias ID */
#if WIN
    unsigned short io_addr;   /* Port address for int.mode */
    char intnumb;                                 /* IRQ # */
    short num_acads;               /* # of ACADs connected */
    HWND hwnd;                  /* Graphics window handle. */
    WORD wTbPacket;      /* System tablet packet message # */
    HANDLE hRgn;           /* System tablet region handle. */
    FARPROC lpTabletRegionStack; /* System tablet function */
    FARPROC lpTabletEnable;      /* System tablet function */
#else
    unsigned long io_addr;    /* Port address for int.mode */
    char intnumb;                                 /* IRQ # */
    long num_acads;                /* # of ACADs connected */
#endif  /* WIN */

Description
-----------
AutoCAD calls the driver with member dgcode in struct dgbxinit set to
EINIT, member alias set to the alias ID, and member version set to the
current AutoCAD ADI version number. Your driver might want to check for a
compatible version. Any options required by the controlling product are
indicated by bits set by the product in member options. If the driver is
unable to operate in a requested optional mode, it should clear the
relevant option bit in the return packet.

Because more option flags might be added in later revisions of ADI, your
driver should test for option flags in a bitwise manner.

Table 9-29. Values for the EINIT.options

Mnemonic         Value                 Meaning

DRAGG            0x1  If set, DRAGG mode required

DG_RELATIVE      0x2  If set, relative mode required

AutoCAD prior to release 12 sets member options to NODRAGG. This tells the
ADI driver to return one P_COORD when the pick button is first pressed, and
then to return P_NONE until it is released. AutoCAD Release 12 turns on the
DRAGG bit in member options, requiring support for DRAGG mode.

Other Autodesk products (e.g., Autodesk 3D Studio) or other versions of
AutoCAD (on different platforms) can send DRAGG in member options. In DRAGG
mode, a signal is sent to indicate that a button has been pressed (along
with valid coordinates and optional pressure), and then valid coordinates
(and optional pressure) continue to be sent while the button is down. A new
signal is sent when the button is released. If more than one button is
pressed, button-down and button-up signals are sent for each.

Thus, in DRAGG mode when the pick button is pressed, P_POINT is returned
once with valid coordinates. Then P_COORD is repeatedly returned with valid
data until the pick button is released, at which time P_POINTUP is
returned. When a button other than the pick button is pressed, P_BUTTP is
returned with valid coordinates. Then P_COORD is repeatedly returned with
valid data until the button is released, at which time P_BUTTPUP is
returned. If several buttons have been down, return P_BUTTPUP for each, as
it is released.

If an Autodesk product requests DRAGG and your device cannot operate in
this mode, return BAD in member status.

Your driver should return a structure of type dgbxinit, with member dgcode
set to OK if the driver decides it can work with the ADI interface level
supplied by AutoCAD, or with dgcode set to BAD if it cannot.

Your driver should return its ADI version number (ADIPKTLEVEL) in member
version. The symbolic constants used in ADI digitizer drivers are defined
in the header file dgp.h. ADI 4.2 drivers should return version as
DG_LEVEL_42.

On 386 Platforms
----------------
If the driver has set the interrupt member of the DETAIL packet to 0x1,
indicating interrupt mode operation, two additional members of the EINIT
packet's structure are sent to the driver: io_addr and intnumb.

Values for member io_addr are port addresses in hexadecimal format such as
0x3F8. The interrupt mode driver needs this information to pass on to its
interrupt handler. Examples of io_addr use are in the sample driver
DGPSUMI, in both the dgpsumi.c and dgpsumia.asm files.

Values for member intnumb are type char (8-bit hexadecimal). This value is
used to set the interrupt mask for either the master or slave 8259 chip.
Examples of how to set the interrupt mask for the 8259 chip are in the
sample driver DGPSUMI (dgpsumi.c).

UNIX Notes
----------
UNIX AutoCAD R11 and Release 12 turn on the DRAGG option bit. Your driver
must be ready to handle DRAGG mode.

Your driver can ignore the num_acads member and proceed normally with your
handling of the rest of the structure members.

The ADI library code in dgalib.a examines the num_acads member to see if
any other AutoCAD sessions are already using your driver.

Your driver can ignore the intnumb member because it has no meaning for
UNIX ADI.



9.16.8 EINFO
==============

9.16.9 INFO
===========

Purpose
-------
AutoCAD passes all the basic device configuration information back to the
ADI driver and its linked library code. The driver must know the configured
model index, cursor type, and communication parameters (on platforms where
the library code handles I/O) to be able to operate -- this packet supplies
the essential data.

Limitations
-----------
This is an execution-time packet. The appropriate version of it (see
"History") must be sent to the driver, with all the fields filled in,
before EINIT.

AutoCAD fills in all members of this packet. The ADI driver treats this as
a read-only packet.

History
-------
The original EINFO packet was introduced in OS/2 ADI 4.0. It was shortened
to INFO and lost the new member in P386 ADI 4.0. In UNIX ADI 4.1 the packet
was greatly extended by adding members baud, parity, data, stop, handshake,
lazy, devname, mole_data, and interrupt. The execution-time version of this
packet was renamed EINFO. This extended packet is now used on all
platforms.

Declaration
-----------
#define INFO  4
#define EINFO INFO

struct dgedinfo {
    short dgcode;             /* EINFO */
    short dgsize;             /* Size of packet */
    short modinx;             /* Model table index */
    short curinx;             /* Cursor table index */
    short baud;               /* Baud rate */
    short parity;             /* Parity */
    short data;               /* Data bits/frame */
    short stop;               /* Stop bits/frame */
    char handshake;           /* Hardware, XON/XOFF etc. */
    short lazy;               /* Pauses significant */
    char devname[30];
    short mole;               /* Mole indicator */
    struct dgmole mole_data;  /* Mole data */
    short interrupt;          /* 0 = polled, 1 = interrupt */
};

/* mole structure */
struct dgmole {
    short mmethod;                 /* Mole toggle methods, */
                                       /*  0 if not a mole */
    short mbutton;                   /* Mole toggle button */
    short mcursor;          /* Number of buttons on cursor */
    short absrel;           /* Absolute or relative device */
    short hear;           /* Audible notify of mode change */
    short see;            /* Visible notify of mode change */
    short xinc;                    /* Steps in x direction */
    short yinc;                    /* Steps in y direction */
    short mxl[5];                 /* Mole X coordinate low */
    short mxh[5];                /* Mole X coordinate high */
    short myl[5];                 /* Mole Y coordinate low */
    short myh[5];                /* Mole Y coordinate high */
    short motion_factor;          /* Scaling motion factor */
    short big_delta;    /* Throw out big mole mode changes */
};

Description
-----------
AutoCAD calls the driver with member dgcode in packet dgedinfo set to INFO.
Members modinx and curinx are set to the values saved in the configuration
record. No response is expected from the driver. This is an informational
packet only.

This packet is sent at execution time, before EINIT.

Because UNIX digitizer drivers (but not Phar Lap) have two INFO packets,
one for configuration time (CINFO) and one for execution time (INFO), it
was considered more appropriate to name the execution-time INFO packet
"EINFO." Since EINFO is defined as INFO, either constant works, however,
EINFO should be the symbol of choice.

On UNIX Platforms
-----------------
The INFO packet has been extended from the P386 implementation to pass
additional information regarding the port configuration. This is an
informational packet only.

The ADI library uses the extra members added to the dgedinfo structure to
initialize the serial port. No action is expected from your driver.

This packet is sent at execution time, before EINIT.



9.16.10 MOUSEMODE
===================

Purpose
-------
MOUSEMODE asks the library code linked with an ADI driver to toggle the
driver from digitizer mode to mouse mode or back.

Limitations
-----------
MOUSEMODE can be set to UNIX ADI 4.1 and later drivers during execution
time after the ACTIVATE request has started data flowing. It has meaning
only on platforms that support mole mode.

AutoCAD fills in all members of this packet. The ADI driver never sees this
packet; it is intercepted by library code.

History
-------
Added in ADI 4.1 for UNIX platforms.

Declaration
-----------
#define MOUSEMODE 18
For ADI 4.1 drivers
-------------------
struct dgexpkt {
    short dgcode;   /* MOUSEMODE */
    short dgsize;   /* Size of packet */
    short buttn;    /* Button code */
    short x, y;     /* x and y values */
    short pressure; /* Stylus pressure */
    short dgstat;
};
For ADI 4.2 drivers
-------------------
struct dgexpkt_42 {
    short dgcode;     /* Command code */
    short dgsize;     /* Sizeof packet */
    short buttn;      /* Button code */
    long x, y, z;     /* 3-D data */
    long ix, iy, iz;  /* Roll, pitch, yaw */
    short pressure;   /* Stylus pressure */
    short dgstat;
};

Description
-----------
MOUSEMODE asks the library code linked with an ADI driver to toggle the
driver from Digitizer mode to Mouse mode or back. Your driver never sees
this packet.



9.16.11 PLANG
===============

Limitations
-----------
PLANG should be the second packet sent to ADI 4.2 and later digitizer
drivers at both configuration and execution time. This packet should not be
sent to pre-ADI 4.2 drivers. It is sent only by the primary application and
should not be used by secondary applications.

AutoCAD fills in all members of this packet. The ADI drivers treats it as
read-only.

(See the earlier discussion of PLANG in this chapter.)



9.16.12 PWHO
==============

Limitations
-----------
This should be the first packet sent at an ADI 4.2 or later digitizer at
configuration time with PWHO.action set to WHO_CFG. It is the controlling
application's duty to fill in pfunc, psize, product, prod_version,
adipktlevel, action, serial, regapp_name, (if an ADS application), and cpid
(if UNIX). It is also desirable for the controlling application to fill in
cleanup with 0 and status with GOOD, if a driver fails to fill them in.

AutoCAD fills in pfunc, psize, product, prod_version, adipktlevel, action,
screen (0 for digitizers), alias, serial, driver_path, and cpid. The ADI
driver fills in cleanup (0 for digitizers), driver_name, and dpid.

(See the earlier discussion of PWHO in this chapter.)


                    |================================|
                    |                                |
                    |           Chapter 10           |
                    |                                |
                    |          Plotter ADI           |
                    |                                |
                    |================================|




10.1 Introduction
=================

This chapter describes the ADI plotter device specification, which also
handles raster hardcopy devices (printer plotters). Rendering hardcopy
devices are discussed in chapter 8, "Rendering ADI." Packet structures,
packet request codes, and symbolic constants for ADI plotter device drivers
are defined in plp.h for P386 and UNIX platforms.

This document concerns mainly P386 and UNIX ADI 4.2 packet mode plotter
drivers. It also contains information regarding OS/2 ADI 4.0 and Windows
ADI 4.1 plotter drivers. It does not, however, address the issues involved
in controlling a real-mode (INT mode) DOS driver.

10.1.1 Historical Summary
=========================

Until now, AutoCAD has been the only Autodesk product to use P386 ADI
plotters drivers. Hence, driver expectations have been strongly conditioned
by how AutoCAD handles plotting.

The packet mode plotter interface was introduced by the OS/2 ADI 4.0 team
while working on AutoCAD Release 10. The interface has been ported to every
other AutoCAD platform except 640K DOS, with extensions and improvements in
each ADI version.

Table 10-1. Supported products by ADI version

Platform/Product   ADI version   Product version     Plotter ADI interface
--------------------------------------------------------------------------
all platforms   Pre-ADI 4.0     Before R10      INT mode interface only
640k DOS        ADI 4.0         R10 AutoCAD     INT mode only
OS/2            ADI 4.0         R10 AutoCAD     Introduced packet mode
SCO XENIX       ADI 4.0         R10 AutoCAD     INT-like packets
UNIX            ADI 4.0         R10 UNIX        INT-like packets
P386            ADI 4.0         R10 386         Packet mode
640K DOS        ADI 4.1         R11 286         INT mode ADI only
P386            ADI 4.1         R11 386         Packet mode
UNIX            ADI 4.1         R11 UNIX        Packet mode
SCO UNIX        ADI 4.1         R11 SCO         Packet mode
Windows         ADI 4.1         R11 Windows     Packet mode
P386            ADI 4.2         R12 386         Packet mode
UNIX            ADI 4.2         R12 UNIX        Packet mode


10.1.1.1 ADI 4.2 Changes
------------------------

ADI 4.2 involves a major overhaul of AutoCAD plotting. The interface has
been extended for 256 colors, variable pen widths, and PCP files. The error
return values from plotter packets have been made consistent. AutoCAD now
honors a return value of BAD in plcode from any plotter packet as a signal
that the driver wants to terminate the plot. Previously AutoCAD only
listened to return values from some packets, and the error return code was
inconsistent across those packets.

To write a driver for older versions of AutoCAD, you should look at each
individual packet description for the value to be returned in plcode in
case of an error.

Note: The SPDCHK packet used in P386 ADI 4.1, and the SPEEDCHK packet used
in OS\2 ADI 4.1 are now obsolete and no longer used.

10.1.2 Sample ADI Plotter Drivers
=================================

Sample drivers are provided to assist developers to understand ADI device
driver specifications, to help test development environments, and to
improve productivity. Please read the license agreement at the beginning of
each sample source code file regarding the use of the sample source code.

The list of sample drivers available on each platform and other platform-
specific information is available in a document file named adikit.doc
located in a directory named for the platform (e.g., \sparc\adikit.doc).


10.2 Modes of Plotter Driver Operation
======================================

For plotting, AutoCAD has historically had two distinct modes of operation,
configuration time and execution or plot time. At configuration time or
"CFG," the selection of drivers, I/O ports, and so on, takes place. At plot
or "XQT" time, the user is shown the global plot parameters and given a
chance to modify them. Then the plot is created. Plotters are the one
AutoCAD device class that get extensive configuration at XQT (plot) time.
This creates three logically distinct times in the operation of a plotter
driver: configuration, plot time configuration, and plotting.

Internally, AutoCAD maintains two configuration records for plotting: a
generic plot configuration record and a device-specific configuration
record. Applications that want to control a plotter have to store these
data in a configuration file.

The generic configuration record concerns what the user has selected to
plot, the plot size, paper size, optimization level, and so on. These are
somewhat less device-independent values. They are sent to ADI 4.2 drivers
at various times in a structure plbxpl42cfg with packet codes that indicate
what the application is doing: CPREGENERIC, GENERIC_42, EPRECONF_42,
ECHGCONF_42, and GENERIC_42 again.

The specific configuration record holds device-specific data such as the
number of pens, maximum pen speed, number of line types, device capability
flags, I/O configuration data, and tables associating AutoCAD color indices
(ACI) with pen numbers, line types, speeds, and so on. It is sent to ADI
4.2 drivers in a group of packets: SPECIFICPENS, SPECIFICSPEED,
SPECIFICLTYPE, SPECIFICWIDS, and SPECIFIC_42.


10.3 Configuration
==================

The results of the generic plot configuration process are passed to the
driver both at configuration time, and at execution time, to give the
driver all available information to work with (and modify if the driver
wants to). An ADI 4.2 plotter driver should merge its configuration
questions into this process by clever use of information supplied in the
AutoCAD packets. The Hewlett-Packard GL/2 plotter (plphpgl2) sample driver
is a good example of this.

10.3.1 Printer Plotters
=======================

Logically, AutoCAD Release 12 only supports ADI plotters as hardcopy output
devices. Printer plotters can still be used as output devices; however, it
is the driver's responsibility to rasterize the AutoCAD vector data. The
Epson 24-pin sample printer plotter driver (plep) shows how this is done.

Rasterizing the vector data is usually simple because on most platforms the
operating system handles paging if RAM runs out. On platforms with adequate
virtual memory, only a single pass through the vector file is required, and
you can allocate enough memory (with malloc()) to hold a bit image to send
to your printer. On platforms with limited or no virtual memory support,
you should use the "banding" algorithm demonstrated in "rasta." It also
might be prudent to implement banding if the raster image is more than 2 or
3 megabytes.

Note that unless your driver tells AutoCAD it is a NOPENS or PPLOTTER
device (as plpoki.exp and plep do), the AutoCAD configurator asks the user
this:

Do you want to change pens while plotting?

It is necessary to configure printer plotters as NOPENS or PPLOTTER to keep
AutoCAD from asking meaningless questions about pens and to let AutoCAD
know it should handle rotated and offset plots differently than for vector
plotters. For example, AutoCAD clips vectors to fit inside MAX paper size
if NOPENS or PPLOTTER is set, but doesn't otherwise provide this service.


10.4 General Concepts
=====================

10.4.1 P386 ADI 4.2 Implementation
==================================

P386 plotter drivers, like all P386 ADI drivers, use shared memory for
their transport layer. See the discussion of P386 ADI driver loading and
communication in chapter 3.

Like all P386 ADI drivers, your plotter driver must have the entry point
function acalls(). AutoCAD calls this function to supply the entry point
for service routines (dispatcher functions) and to obtain the driver's
configuration and execution entry points. The driver saves the service
routine entry point in a global function pointer, *entvec() for use by the
driver portion of the dispatcher module (in library code you link to your
driver), and passes back to AutoCAD the edevent structure that holds the
device name, configuration entry point, execution entry point, a device
type flag, and the driver's interface level.

The sample Houston Instruments driver plphip contains an example of this.
The C file plphip.c passes back the edevent structure plhi with the
configuration entry point pladicfg(), the execution entry point pladixqt(),
and the device type flag DEV_PL.

All configuration time calls from AutoCAD to the driver are then made by
far calls to the configuration entry point pladicfg(), located in
plpface.asm, and which in turn makes a near call to pladicfg1() in the
driver. See the sample Houston Instruments driver plphip if further
clarification is necessary.

10.4.2 UNIX ADI 4.2 Implementation
==================================

Plotter drivers on all release 12 UNIX platforms are loaded as a child
process that communicates with AutoCAD by means of pipes. This UNIX
transport layer is hidden from your driver because it is part of the
library code we supply for linking with your driver. See the discussion of
UNIX ADI driver loading and communication in chapter 3.

Plotter drivers function almost the same as they do in the P386
environment. The most significant impact of UNIX on plotter drivers is that
the use of pipes has caused us to use an I/O blocking algorithm to improve
efficiency.

To achieve this improvement, the ADI library does several things:

  * All output through ppsend() is collected until a buffer (usually 4K) is
nearly full or plflush() is received. The size of the buffer is platform-
dependent and subject to change.

This assures synchronization of all plotter output. Your driver should use
plflush() whenever it is important that data be sent to the plotter
immediately (e.g., asking a plotter for hardclip limits).

  * The dispatcher library converts the iow() and plsend() dispatcher
functions to ppsend() calls because iow() and plsend() are logical subsets
of ppsend().

Because we have redirected iow() and plsend() calls through ppsend(), it is
most efficient to use ppsend() directly for all plotter output. In a future
version of UNIX plotter ADI, we will drop support for iow() and plsend().

  * Pen movement packets sent from AutoCAD to your driver are batched to
further speed up plot-to-file operations.

Your plotter driver must be linked with our library code, plalib.a, and
with plumain.o. These modules provide the required startup code, pipe
support, and dispatcher services.

As with P386 ADI, we strongly suggest that you use dispatcher services for
I/O to the plotter. You should use the ciotype() dispatcher function to
select the type of port.

AutoCAD solicits the device (port) name, and thereafter handles I/O through
plsend(), iow(), and ppsend(). These plotter driver I/O services are
provided by the ADI library through callbacks into AutoCAD core services.
You should use these services for standardized configuration and error
handling and to ensure that plot-to-file operations work normally.

10.4.3 OS/2 ADI 4.0 Implementation
==================================

OS/2 plotter drivers are implemented as DLLs. See the discussion of OS/2
ADI driver loading and communication in chapter 3.

The sample HP driver plohp.c should be examined occasionally to make the
discussion of plotter drivers less abstract. You'll probably find examining
the other sample drivers useful too.

plohp.c has the mandatory entry point pladi() that AutoCAD calls to learn
its other entry points and to pass plohp the entry point for service
routines to use. Plohp saves the service routine entry point in a global
function pointer *entvec() and passes back to AutoCAD the structure dscev,
which in turn holds the address of the first device name structure
(&ccname), the configuration entry point plcfg(), and the execution entry
plxqthp().

All configuration time calls from AutoCAD to plohp are then made to the
configuration entry point plcfg().

Note that the various structures and constants discussed below are defined
in pldll.h and pl.h.

10.4.4 Windows ADI 4.1 Implementation
=====================================

Windows ADI 4.1 plotter drivers are implemented as DLLs. See the discussion
of Windows ADI driver loading and communication in chapter 3.

Several discrete plotter drivers are supplied in the ADI kit. No printer
plotters are supplied because of the wide support for printer plotters from
the Windows System Printer. AutoCAD can communicate with the System Printer
through plsys.c, the generic plotter driver. While it is possible to write
a discrete printer plotter driver for AutoCAD, we encourage you to write a
Windows System Printer driver and talk to it through the possibly modified
plsys driver.

The ADI 4.1 plbxplotcfg structure packet has been replaced by the ADI 4.2
plbxpl42cfg structure packet. This packet is used to pass generic plotter
configuration to and from the driver at both configuration and execution
time. As a result, the GENERIC packet code has been dropped in favor of the
more appropriate GENERIC_42 packet code. Even though plotters are still
considered to be driven by the ADI 4.1 specification, this change
introduces one of the first ADI 4.2 modifications. This changes the plotter
specification bit map, pl_specs, from a char to a short, which can hold
more bits.

10.4.4.1 Windows System Printer Driver
--------------------------------------

The #define DEV_SYSPR is used to identify a system printer driver. When an
ADI driver wants to tell AutoCAD it is a system printer driver, it needs to
set (DEV_PL | DEV_SYSPR) in the devflags field of the devent structure
required by Windows ADI drivers. The DEV_SYSPR flag is used by AutoCAD core
code to enable special routines that deal with the system printer.

The PMGEN, PMFILE, and PMDEVMODE packets are intended only for use by
system printer drivers.

The PMGEN, PMFILE, and CINIT packets contain the current setting of the
printer selection radio button from the AutoCAD Environment Settings
dialogue box. The sample system printer driver uses these values to support
two independent system printer configurations.

10.4.4.2 Windows ADI I/O Error Handling
---------------------------------------

I/O errors occurring with either the serial or parallel ports are handled
by AutoCAD but can affect digitizer and plotter ADI drivers. AutoCAD
assigns an error level to the I/O error, either "nonserious" or "serious."
The action taken depends on the error level that AutoCAD assigns. For a
nonserious error, AutoCAD may or may not issue a prompt dialogue box. If no
prompt dialogue box is issued, AutoCAD automatically handles the error, and
neither the user or the ADI driver is aware of it. For a serious error,
AutoCAD always displays a prompt dialogue box and either cancels the plot
(plotters) or disables the driver (digitizers).

The ADI driver is unaware of the prompt dialogue box issued by AutoCAD in
response to an I/O error. The ADI driver is informed of I/O errors via the
return values of dispatcher calls. See the chapter on dispatcher functions
in the P386 documentation for information on return values. The ADI driver
will not get any CPU cycles until the user responds to the prompt dialogue
box.

In the case of plotter drivers, if a nonserious error occurs and AutoCAD
issues a prompt dialogue, the user can correct the error (by clicking on
the "retry" button), or promote the error to a serious error (by clicking
on the "cancel" button), which causes the plot to cancel (the ADI driver
would receive the ABORTPLOT packet). As far as the ADI driver is concerned,
the current state of AutoCAD would still be "inside" plsend().

In the case of digitizer drivers, if a nonserious error occurs and AutoCAD
issues a prompt dialogue, the user can correct the error or promote the
error to serious in the same way as for plotters. However, on a serious
error, the digitizer is disabled. To continue, the user will need to close
the drawing, fix the digitizer, and then open a drawing. The user does not
need to exit AutoCAD or Windows. For your information, the following table
lists the I/O errors that AutoCAD currently handles. No action is necessary
(or possible) by the ADI driver for handling these errors.

Table 10-2. AutoCAD extension for Windows I/O error handling

I/O Error Description                               DEV_DG      DEV_PL
-----------------------------------------------------------------------
Break condition (serial port only)                  N_N         S_P
CTS timeout (serial port only)                      S_P         S_P
Device not selected (parallel port only)            N_P         N_P
DSR timeout (serial port only)                      S_P         S_P
Framing error (serial port only)                    N_N         S_P
I/O error (parallel port only)                      N_P         N_P
Requested mode not supported                        S_P         S_P
Out of paper (parallel port only)                   N_P         N_P
Character overlap (serial port only)                N_N         S_P
Device timeout (parallel port only)                 S_P         S_P
CD timeout (serial port only)                       S_P         S_P
Receive queue overflow                              N_N         S_P
Parity error (serial port only)                     N_N         S_P
Transmit queue full                                 S_P         S_P
Receive buffer empty                                N_N         S_P
Cannot open port                                    S_P         S_P
Cannot set port parameters                          S_P         S_P

Table 10-3. Key for Windows I/O error table

Symbol  Definition
N_N  Nonserious, no prompt dialogue box issued
N_P  Nonserious, prompt dialogue box issued
S_P  Serious, prompt dialogue box issued

10.4.5 ADI Plotter Test Procedures
==================================

Use the pltst2.dwg (found in the \41brlmd\misc directory of the CDROM) to
test your plotter driver using the following steps:

1.        Configure AutoCAD for the plotter to be tested.  Cable the
plotter according to the instructions you will provide the user for this
purpose. Verify that it works. Exit AutoCAD and reenter. Verify that the
plotter works. Reconfigure and verify that the device still works.

2.        Scaling - Plot the view named SCALE to a specified scale
(e.g.1=1). Measure the dimensioned parts of the drawing checking that they
are plotted to the scale specified.

3.        90 Degree Rotation - Plot the drawing specifying 90-degree
rotation, MAX size paper, and FIT.  The plot should be rotated 90 degrees.
The plot should not be truncated.  If it is, the paper size is incorrect.

4.        Linetypes, Pen changes, Pen Widths and Pen speeds - If the
plotter driver supports multiple pens, line types, pen widths or pen
speeds, use AutoCAD's color assignment dialogue to select various
combinations of these.  Ensure that each pen, line type, width and speed is
accessible.  Change the layers to different pen numbers and pen speeds
supported on the plotter. Plot the drawing with representative
combinations, and verify that the appropriate line types and pens were
used.  If the plotter supports only one pen, test the "pause for pen
change" option.

5.        Origin Offset - Plot the drawing, specifying an offset from the
origin.  The plot should move the specified number of units from the
origin.

6.        MAX Size - Plot EXTENTS, MAX size, FIT, no rotation. The drawing
should not be truncated.

7.        Plot the configurable paper sizes, including USER sizes, with a
box drawn at the paper size, plotted extents, scale 1=1. The plot should
not be truncated.

8.        Plot a drawing complex enough to force your plotter to exercise
handshaking with the host computer.

9.        Run the above tests for each supported plotter resolution and on
each supported plotter model.


10.5 Plotter Packet Usage
=========================

AutoCAD is the only Autodesk product that uses ADI plotter packets. Both
configuration-time and execution-time packets are shown in this table. An x
indicates usage, o indicates optional, and a dash indicates the packet is
not used. Sun refers to the Sun SPARC, 386 refers to the extended DOS
platform, and Win to the Windows platform in the headings. Extremely brief
descriptions of what each packet does are listed here, see the packet
descriptions for complete information.

Table 10-4. AutoCAD plotter packet usage

                386 Sun 386 Sun 
Packet          R12 R12 R11 R11 Win        Comments
---------------------------------------------------------------------
ABORTPLOT        x   x   x   x   x  Abnormal plot termination
CINIT            x   x   x   x   x  CFG-time driver initialization
COLORTLTYPE      o   o   x   x   x  Return line type table for color index
COLORTSPEED      o   o   x   x   x  Return pen speed table for color index
CPREGENERIC      x   x   -   -   -  CFG-time generic plot dialogue data
DETAIL           x   x   x   x   x  Model-specific configuration from driver
DRAW             x   x   x   x   x  Move to coordinates with pen down
ECHGCONF         -   -   x   x   x  Sent if plot configuration changes
ECHGCONF_42      x   x   -   -   -  Sent if plot configuration changes
EINIT            x   x   x   x   x  Execution-time driver initialization
ENDPLOT          x   x   x   x   x  Signal to driver that plot is complete
EPOSTCONF        x   x       x   x  Notify driver before vectors are sent
EPRECONF         -   -   x   x   x  Send CFG record to plotter pre XQT-time
EPRECONF_42      x   x   -   -   -  Send configuration record to plotter
ESHOW            x   x   x   x   x  Show plot configuration to user
GENERIC          -   -   x   x   -  App informs driver of plot configuration
GENERIC_42       x   x   -   -   x  App informs driver of plot config
LEGEND           x   x   x   x   x  Driver-defined line types
MODEL            x   x   x   x   x  App gets model name from ADI driver
MOVE             x   x   x   x   x  Moves to coordinates with pen up
NEWLTYPE         o   o   o   o   o  Select plotter line font
NEWPEN           x   x   x   x   x  Select a pen
NEWPENWID        o   o   -   -   -  Enable multiple widths for plotters
NEWSPEED         o   o   o   x   x  Select drawing speed
PENRAISE         x   x   x   x   x  Plotter prepares for manual pen change
PLANG            x   x   -   -   -  Plotter driver language and code page
PLFILL           o   o   -   -   -  Enable devices to do polygon fills
PLOTSIZE         x   x   x   x   x  Max X and Y coordinates used in plot
PLPENS           x   x   x   x   x  Upload pen number table for color index
PLWIDS           -   -   x   x   x  Pen width table for app's color index
PLWIDS_42        o   o   -   -   -  Pen width table for app's color index
PMDEVMODE        -   -   -   -   x  Change to Windows driver print settings
PMFILE           -   -   -   -   x  Intended system printer driver action
PMGEN            -   -   -   -   x  ADI driver loads Windows printer driver
PWHO             x   x   -   -   -  Identify product executing the driver
PWHO             x   x   -   -   -  Tell driver of controlling application
SPECIFIC         -   -   x   x   x  Device-specific information for driver
SPECIFICLTYPE    o   o   -   -   -  Plotter-specific line type information
SPECIFICPENS     x   x   -   -   -  Plotter-specific pen number information
SPECIFICSPEED    o   o   -   -   -  Table of pen speed versus color index
SPECIFICWIDS     o   o   -   -   -  Table of pen width versus color index
SPECIFIC_42      x   x   -   -   -  Device-specific configuration record

10.6 Plotter Configuration-Time Packets
=======================================

Configuration-time initialization is done at least once when your driver is
first selected during AutoCAD configuration. During this plotter
configuration, AutoCAD requires certain information from your driver and
obtains this through an exchange of packets.

The first two members of most plotter packets are plcode and plsize. The
plcode member indicates which service AutoCAD is requesting of your driver,
and plsize tells your driver the size of the incoming request packet.

For every request packet sent by AutoCAD to your driver during
configuration, a reply packet is required. The reply packet you send back
to AutoCAD cannot be the same as the request packet you received. The
following packet descriptions include the appropriate return values for the
packet's structure members, used to indicate such things as device
information or whether your driver can handle a request.


10.7 Configuration-Time Packet Descriptions
===========================================

Below is a description of each plotter packet, presented in the approximate
order in which the packets are sent by AutoCAD to an ADI plotter driver.
The "Limitations" section of each packet description is a discussion from
the controlling application's point of view of when the packet should be
sent and how it must be handled.



10.7.1 PWHO
=============

Purpose
-------
PWHO lets the plotter driver know which product is executing the driver.
This is an optional packet that can be ignored by disinterested drivers.

Limitations
-----------
This should be the first packet sent to an ADI 4.2 or later plotter at
configuration time with PWHO.action set to WHO_CFG. It is the controlling
application's duty to fill in pfunc, psize, product, prod_version,
adipktlevel, action, serial, regapp_name (if ADS application), and cpid (if
UNIX). It is also necessary for the controlling application to fill in
cleanup with 0 and status with GOOD, if a driver fails to fill them in.

Applications lacking a serial number should stuff EOS into member serial.
Applications such as AVE Render, which load a driver but do not support
alias device names, should stuff 0 into member alias.

AutoCAD fills in pfunc, psize, product, prod_version, adipktlevel, action,
screen (0 for digitizers), alias, serial, driver_path, and cpid. The ADI
driver fills in cleanup (0 for digitizers), driver_name, and dpid.

AutoCAD Release 12 fills in adipktlevel with PL_LEVEL_42.

History
-------
PWHO was added for plotters for release 12 in ADI 4.2. The structure was
modified several times during ADI 4.2 development by adding new members and
by changing ints to longs.

Declaration
-----------
#define PWHO  49                      /* PWHO for plotters */
struct pkwho {
    short pfunc;                * PWHO for plotter drivers */
    short psize;                              /* PKWHOSIZE */
    short product;                         /* product code */
    short prod_version; /      * revision level of product */
    short adipktlevel;  /* ADI interface level for product */
    short status;         /* driver can return status here */
    short cleanup;   /* driver can return cleanup requests */
    short action;               /* app can request actions */
    short screen;              /* display states requested */
    long alias;              /* display driver alias index */
    char  serial[WHO_SERIAL_SIZE]; /* ASCIIZ serial number */
    char  regapp_name[WHO_REGAPP_NAME_SIZE];
    char  driver_name[DEVNAMSZ + 1]; /* ASCIIZ driver name */
    char driver_path[MAXPATHLEN];/* where driver was found */
#ifdef UNIX
    long cpid;               /* controlling app's UNIX pid */
    long dpid;                         * driver's UNIX pid */
#endif /* UNIX */
};

#define PKWHOSIZE (sizeof(struct pkwho))
#define WHO_SERIAL_SIZE 32
#define WHO_REGAPP_NAME_SIZE 32

Description
-----------
PWHO is the first packet sent by Autodesk products at configuration time
with PWHO.action set to WHO_CFG and the first execution-time packet with
PWHO.action set to WHO_XQT. The idea is to let drivers know which product
is in control before the driver has to respond to requests from the
product.

This packet is also sent by AutoCAD at an application's request (in
ads_adistart() or ads_adiend()).

The member pfunc is defined differently for each device type in the C
header file for each device type (e.g., dgp.h, plp.h, etc.). The structure
definition for pkwho and the definitions for products and versions are
defined in a new C header file, who.h.

The product ID number will be unique for each Autodesk product. The header
file who.h defines these ID numbers. ID number zero will be reserved for
unknown (non-Autodesk) primary products, for example:

Table 10-5. Values for PWHO.product

Mnemonic          Value                 Meaning

WHO_UNKNOWN       0    Unknown primary product

WHO_ACAD          1    AutoCAD

WHO_SHADE         2    AutoShade

WHO_SKETCH        3    AutoSketch

WHO_STUDIO        4    3D Studio

WHO_AME           5    AME

WHO_R12REND       7    AVE Render

WHO_AUNK          0x2000                Unknown ADS application

WHO_TUNK          0x4000                Unknown TEE application

Note that TEE applications cannot provide cleanup services. Such
applications should return WHO_TUNK in the product field to let ADI drivers
know that a TEE driver is operating and that cleanup services can't be
expected.

The member prod_version is made up of two parts: the upper 8 bits form the
major version number, while the lower 8 bits form a minor version number.
Thus, the first release of AutoCAD Release 12 would be 0x100 while a second
update release would be 0x101. As each new product or version is designed,
the author makes a code submission to update who.h, thus reserving a
number.

Table 9-24. Values for PWHO.prod_version

Mnemonic       Value Meaning

WHO_R12        0x100 For AutoCAD Release 12 initial release

WHO_AME2       0x100 AME 2.0



adipktlevel is sent from the Autodesk product to the ADI driver, indicating
which ADI interface level the user has selected. For most types of ADI
there are two parallel numbering systems: intlevel and adipktlevel. The
intlevel numbers are an old system that proceeds sequentially. The
adipktlevel is a newer system with the lower 4 bits of the version
indicating minor revisions and the remaining bits indicating major version
changes.

The member status is normally returned as GOOD. If it is returned as BAD,
the driver is indicating that it cannot work with the indicated product,
version, and interface level.

Table 10-6. Values for PWHO.status

Mnemonic            Value                       Meaning

GOOD                0     Can work with product, etc.

BAD                 -1    Nonspecific failure

ADI_BAD_VERSION     -2    Incompatible ADI version

ADI_BAD_APP         -3    This driver won't work with this application

ADI_BAD_SERIAL      -4    Serial number violation

ADI_BAD_PROD_VER    -5    Incompatible product version

The product's serial number is appended to this packet as a null-terminated
ASCII string. This lets vendors easily lock their products to a single
serial number, if they like. Autodesk serial numbers are two ASCII integers
separated by a dash.

The member alias is filled in by AutoCAD at WHO_CFG and WHO_XQT time for
display drivers with an alias index. If the display driver has only one
device name, alias is zero. If the driver has more than one devname string,
AutoCAD returns the index of the selected devname.

The regapp_name member is for ADS applications, a null-terminated string
returned by the application in ads_regapp().

The driver_name field is filled in by the ADI driver to pass a null-
terminated ASCII string to any application (particularly secondary
applications) wanting to know the identity of the current driver.

The driver_path member is sent from the primary product (e.g. AutoCAD) to
inform the driver of the full path from which the driver was loaded. This
is filled in by the primary product at configuration time and at execution
time. PWHO packets emitted by secondary applications don't have this filled
in.

The member cpid is used only on UNIX platforms. It passes the controlling
application's process ID to the driver. Both primary and secondary
applications are required to fill in cpid. The member dpid returns the
driver's UNIX process ID. UNIX digitizer and plotter drivers will find that
our library code has filled in dpid by the time PWHO reaches the driver's
code. However, the driver can modify this value if necessary.

Table 10-7. Values for PWHO.action

Mnemonic         Value                       Meaning

WHO_CFG          1    Indicates configuration time, main application

WHO_XQT          2    Indicates execution time, main application

WHO_START        3    Used by secondary app on 1st takeover

WHO_PAUSE        4    Temporary end of secondary app takeover

WHO_RESUME       5    Secondary application resumes control

WHO_END          6    Secondary application terminates

When the primary product (e.g., AutoCAD) starts up in configuration, it
sets action to WHO_CFG. When the primary product starts at execution time,
it sets WHO_XQT. If a secondary application, via a TEE driver or an ADS
link takes over an ADI driver temporarily, it sets the action member to
WHO_START in a PWHO packet sent at its first takeover. At the end of its
takeover of the device, it sets action to either WHO_PAUSE or WHO_END. A
PWHO packet with WHO_PAUSE tells the driver that the application plans to
take over again but is temporarily returning control to the primary
application. A PWHO packet with WHO_END indicates that the secondary
application does not expect to take over again.

It is incorrect for an application to send two WHO_START actions without an
intervening WHO_END.

The screen and cleanup members are used only for display drivers and are
empty for plotters.

This is one of two plotter packets whose first member is not plcode but
pfunc.



10.7.2 PLANG
==============

Purpose
-------
Lets plotter drivers know the language and code page being used by AutoCAD.
This is helpful in internationalizing drivers. This is an optional packet
and can be ignored by disinterested drivers.

Limitations
-----------
PLANG should be the second packet sent to ADI 4.2 and later plotter drivers
at both configuration and execution time. This packet should not be sent to
pre-ADI 4.2 drivers. It is sent only by the primary application and should
not be used by secondary applications.

AutoCAD fills in all members of this packet. The ADI driver treats this as
a read-only packet.

History
-------
The use of PLANG for plotter drivers was added in ADI 4.2 to support
AutoCAD Release 12.

Declaration
-----------
#define PLANG  50      /* for plotter drivers (see plp.h) */

struct pklang {
    short pfunc;                      /* PLANG for DEV_PL */
    short cchar;                      /* check mark value */
    short options;                    /* option flag bits */
    short maxchar;          /* highest numbered char code */
    char  lang[MAX_LAN + 1];  /* null-terminated language */
                                                ID string */
    char  code_page[MAX_COP + 1]; /* null-terminated code */
                                                page name */
};

Description
-----------
The ADI interface was originally designed to handle only 128 ASCII
characters, with character 128 having the special meaning of a check mark
for dialogue boxes. As overseas editions of AutoCAD have begun using ADI
drivers, it has become necessary to extend the range of characters sent to
display drivers. Due to conflicts with some countries' character definition
conventions, these "8-bit font" versions of AutoCAD redefine the check mark
character to another value, often 255. PLANG is sent to display drivers to
negotiate handling this issue. In ADI 4.2 PLANG is also sent to plotter and
digitizer drivers as an informational packet; AutoCAD does not examine the
packet returned by the driver. Note that different packet codes are used
for PLANG for different device types (DEV_DS, DEV_DG, and DEV_PL).

Table 10-8. Values for PLANG.options

Mnemonic        Value Meaning if Set

FF_8BIT         0x1   FONT8BIT is active

FF_SYSMENU      0x2   System has a menu bar

The FF_SYSMENU option bit is used on some windowing platforms to inform a
display driver that a system menu bar is supported. PLANG has been extended
in ADI 4.2 with two new members: lang and code_page. These members inform
the driver of the command language and code page AutoCAD believes are
currently in use. These are derived from the software environment and not
as a result of polling the keyboard or other hardware.

The PLANG.lang and PLANG.code_page members were introduced in ADI 4.2. They
inform the driver of the command language and code page that AutoCAD
believes are currently in use. These are derived from the software
environment and not from polling the keyboard or other hardware. See the
PLANG packet description in chapter 6, Display ADI, for the values tables
for these members.

Ctype Functions
---------------
We have added new dispatcher functions to export ctype functions that have
been correctly internationalized. See chapter 4, ADI Dispatcher, for
complete information on ctype functions.



10.7.3 CINIT
==============

Purpose
-------
Configuration-time driver initialization.

Limitations
-----------
This should be the first packet sent to pre-ADI 4.2 plotters at
configuration time and it should immediately follow PLANG for ADI 4.2
plotters. You must fill in alias with the currently configured alias index.
If the driver has only a single devname, the alias index is zero. You must
fill in your application's adiversion and number of supported colors.

Alias device names are name strings returned in the edevent struct when the
driver is loaded. ADI drivers can have up to 5 name strings in the edevent
struct on most platforms. A controlling product normally makes these appear
as distinct menu choices in a device selection Configuration menu. Many
drivers have only one name string and thus appear in the menu only once.
But some drivers have aliases and appear up to 5 times in the menu, under
different device names. In any case, your application will have already
presented a menu and solicited the user's choice of device type before
attempting to configure a driver. Thus you should know the alias index and
be able to pass it to the driver in CINIT (and in PWHO if it is a 4.2
driver).

Your application should abort the configuration process if the ADI driver
fails to return member plcode as OK.

AutoCAD fills in all members of this packet. The ADI driver modifies
plcode, version, and status.

History
-------
This packet was introduced in OS/2 ADI 4.0 for AutoCAD 386 Release 10. The
members thwnd and ghwnd were added for the Windows platform in ADI 4.1.

Declaration
-----------
#define CINIT 11

struct plbxinit {
    short plcode;       /* CINIT */
    short plsize;       /* Sizeof packet */
    short version;      /* ADI version number */
    short status;       /* Status code */
    short colours;      /* Max colors */
    char alias;         /* Alias ID */
#if WIN
    HWND thwnd;         /* Text window handle */
    HWND ghwnd;         /* Graphics window handle */
#endif /* WIN */
};

Description
-----------
The CINIT request code arrives in a packet with struct plbxinit. Member
alias is set by AutoCAD to the alias ID and colours is set by AutoCAD to
(MAXCOLOR + 1). Any colors or pens greater than the number supported by
AutoCAD are ignored.

Before release 12 of AutoCAD, MAXCOLOR was 15, while in release 12 it has
become 255.

The version member is set by AutoCAD to the current AutoCAD ADI version
number (ADIPKTLEVEL in plp.h). In deciding whether your driver can work
with a given interface level, in many cases you can ignore the lower 4 bits
of the member version unless some special feature is required for your
driver.

The idea behind version numbers is to provide upward and downward
compatibility to drivers. In other words, old drivers can usually work with
AutoCAD running a more recent version of ADI. In such cases, the driver
would (silently) ignore packet requests it does not understand. If the
driver decides it can work with the ADI version that AutoCAD is running, it
should return the symbolic constant OK in the member plcode, otherwise it
should return BAD.

The version member should be set by your driver to the ADI version it
supports. ADI 4.2 drivers, for example, return PL_LEVEL_42 in version.

The members plcode, version, and status are the only three members (with
appropriate values) returned by the driver to AutoCAD at CINIT time.

A null plotter driver should return NULLPLOTTER in member status to notify
AutoCAD that no plotter output takes place. A file output driver returns a
special code in status indicating the kind of file output requested. A
regular hardware plotter driver should return HARDWARE in status. Almost
all drivers return HARDWARE in member status.

Table 10-11. Possible values for CINIT.status

Mnemonic        Value                 Meaning if Set

HARDWARE        0x0  Driver is for a physical plotter

NULLPLOTTER     0x1  No plotter output (null PL driver)

The driver should return OK in plcode if it has successfully been started.
If any other value is returned in plcode, AutoCAD assumes the driver has
failed initialization; AutoCAD aborts the configuration process.

Windows ADI 4.1
---------------
The CINIT and EINIT packets (structure plbxinit) have two new members,
thwnd and ghwnd. These are the text and graphics window handles
respectively. These handles are currently used by the Generic System
Printer driver PLSYS.DLL when making Windows system calls requiring a
window handle. However, any plotter driver that makes Windows system calls
might find these handles useful.

AutoCAD sets the status member of the EINIT packet to the state of the
printer selection radio button from the AutoCAD Environment Settings
dialogue box.

If status is set to 1, the user has selected the Use Control Panel
Configuration radio button from the AutoCAD Environment Settings dialogue
box. Otherwise status is set to 0. The sample system printer driver uses
this value to determine which Windows printer driver to load.



10.7.4 MODEL
==============

Purpose
-------
Lets the application solicit model names from the ADI driver.

Limitations
-----------
MODEL should be sent after CINIT if this is a "new" configuration or if the
user wants to select a different model. The first MODEL packet lets your
application find out whether the driver supports several models. If it
does, you should send more MODEL packets to build a table of models and
find out which one the user wants.

AutoCAD fills in all members of struct plcdmodel. The ADI driver fills in
all members of struct plcumodel.

History
-------
This packet was introduced in OS/2 ADI 4.0 for AutoCAD 386 Release 10.

Declaration
-----------
#define MODEL   20
#define MNAMLEN 32
application sends:
------------------
struct plcdmodel {
    short plcode;       /* MODEL */
    short plsize;       /* Sizeof packet */
    short model;        /* Model index */
};
driver returns:
---------------
struct plcumodel {
    short plcode;        /* MODEL */
    short plsize;        /* Sizeof packet */
    short nmodels;   /* Total number of models in driver */
    short model;         /* Model index */
    char mname[MNAMLEN]; /* Model name */
};

Description
-----------
To make a list of your driver's supported plotter models, AutoCAD usually
has to make multiple MODEL packet calls to your driver (one call for each
model your driver supports).

To solicit the number of model names and the first model name from your
driver AutoCAD sends the struct plcdmodel with plcode set to MODEL and
model set to 1.

In struct plcumodel, your driver should set the nmodels member to the
number of models supported by your driver. The model member is set to 1 for
the first model and the character string mname[] contains the first model
name.

Upon receiving the first packet back from the driver, AutoCAD tries to
allocate ((nmodels) * MNAMLEN) bytes to store the model names. If
successful, AutoCAD makes another (nmodels-1) request to the driver, each
time incrementing the value of model in structure dgcumodel.

Your driver should always set model to the model index being returned. If
AutoCAD requests a nonexistent model, you should set model to 0.



10.7.5 DETAIL
===============

Purpose
-------
Lets the application solicit model-specific configuration information from
the ADI driver.

Limitations
-----------
This packet should be sent after MODEL or CINIT. You must fill in model so
the driver knows which of its models has been selected. This should be just
before you do generic plot configuration.

When this packet is returned to your application from the driver, your
application has to handle configuring the I/O port for the driver by asking
the user which port (of the type(s) supported by the driver) the plotter is
connected to. If the driver returns plcode as BAD, it indicates a serious
error or <Ctrl-C> detected.

AutoCAD fills in the members of this packet. The ADI driver fills in every
member except plsize, model, and new.

History
-------
This packet was introduced in OS/2 ADI 4.0 for AutoCAD 386 Release 10. The
option flags NOPENS, PPLOTTER, and SHEETFD were added in release 11 and ADI
4.1. The options flags SFILLS, FFILE and LONGAXIS were added in AutoCAD
Release 12 and ADI 4.2. Prior to release 12, AutoCAD did not examine plcode
on return from the driver.

Declaration
-----------
#define DETAIL  21

struct plcudetail {
    short plcode;      /* DETAIL */
    short plsize;      /* Sizeof packet */
    short model;       /* Model index */
    short new;         /* New configuration flag */
    real pl_xmax;      /* Max dimension in x direction */
    real pl_ymax;      /* Max dimension in y direction */
    real pl_xinc;      /* Steps/inch, x direction */
    real pl_yinc;      /* Steps/inch, y direction */
    short options;     /* Option bits */
    short pens;        /* Max number of pens */
    short maxspd;      /* Max speed, inches per sec */
    short lines;       /* Max number of line types */
    short type;        /* Serial, Parallel, HPIB etc. */
    short baud;        /* Baud rate */
    short parity;      /* Parity */
    short data;        /* Data bits/frame */
    short stop;        /* Stop bits/frame */
    char handshake;    /* Hardware, XON/XOFF etc. */
};

Description
-----------
The DETAIL packet is sent by AutoCAD to hardware plotter drivers. AutoCAD
calls the driver with member plcode in structure plcudetail set to DETAIL
and member model set to the appropriate model index. If this is a first-
time configuration, member new is FALSE and the rest of the fields hold
random uninitialized data.

If this is a first-time configuration (new = TRUE), your driver should fill
in all members with the default values for this model of device. These
default values are used in the AutoCAD configuration dialogue with the
user.

If this is not a first time configuration (new = FALSE), your driver is
still required to fill in the members baud, parity, type, data, stop, and
handshake; AutoCAD hasn't stored these and needs them every time this
packet is sent. Although your driver can modify the other members of this
packet when new is FALSE, you should have good reason for doing so. They
hold the values from the user's last configuration of your driver and might
be different from your standard defaults. The user normally expects her
configured values to be unchanged.

Beginning with release 12, ADI drivers can return plcode as BAD if there is
an error or a <Ctrl-C> detected during handling this packet. Older AutoCADs
did not examine the plcode return value.

Symbolic constants for many of the possible values are defined in the
header file plp.h.

The member model is set to 1 if only one model of plotter is supported by
your driver. Otherwise, it indicates which of several models has been
configured (e.g., it is 3 if the third model has been selected).

The possible return values that can be ANDed or ORed together for
plcudetail.options are given in the table below. Check the plp.h header
file for #define declarations of the mnemonics.

Table 10-12. Possible values for DETAIL.options

Mnemonic       Value  Meaning if returned

MULTPEN        0x0001                          Plotter has multiple pens

MULTLINE       0x0002                          Plotter can support multiple
line types

VARSPEED       0x0004                          Plotter can change pen speed

PENWID         0x0008                          Plotter has varying pen
width

VARINC         0x0010                          Plotter has varying
increments per inch

ONEPEN         0x0020                          Plotter has one pen (or
changes pens by hand)

SHEETFD        0x0040                          Plotter supports a sheet
feeder

NOPENS         0x0080                          Plotter has no physical pens
(printer plotter)

PPLOTTER       0x0080                          Alternate #define for NOPENS

SFILLS         0x0100                          Plotter can do smart polygon
fills

FFILE          0x0200                          Plotter only plots to file

LONGAXIS       0x0800                          Plotter can do long axis
plots

If your driver needs to save some bits in the options member, use only the
upper 4 bits. The remaining bits are reserved for Autodesk use.

Table 10-13. Possible Values for DETAIL.type

Mnemonic       Value                 Meaning if Set

NODEVICE       0x0  AutoCAD I/O is not used

SERIAL         0x1  Digitizer uses serial interface

PARALLEL       0x2  Digitizer uses parallel interface

HPIB           0x4  Digitizer uses HPIB interface

If it is possible for the user to configure your device for serial
communication, you must indicate the baud rate, parity, number of stop
bits, and handshaking method that AutoCAD can expect.

You can use the dispatcher ciotype() service to solicit the user for a
choice of interface type (if your device offers a choice). For OS\2 ADI
4.0, see the getdetail() procedure in plohp.c for an example, and for and
ADI 4.2 example, look at pladicfg1() in plphplj.c.

The baud member should be initialized with the literal baud rate. For most
platforms, valid baud rate values are: 50, 75, 110, 134, 150, 200, 300,
600, 1200, 1800, 2400, 4800, 9600, and 19200. Note that some DOS systems
have UART chips that might be unreliable at 19200.

Table 10-14. Values for DETAIL.parity (see adihport.h)

Mnemonic         Value Meaning if Set

PARITY_NONE      0x0   No parity

PARITY_ODD       0x1   Odd parity

PARITY_EVEN      0x2   Even parity

PARITY_MARK      0x3   Mark parity

PARITY_SPACE     0x4   Space parity


Table 10-15. Values for DETAIL.stop

Value         Meaning if Set

0x1           One stop bit

0x2           Two stop bits


Table 10-16. Values for DETAIL.handshake (see adihport.h)

Mnemonic              Value  Meaning if Set

HANDSHAKE_XONXOFF     0x0    XON/XOFF handshake

HANDSHAKE_HARDWARE    0x1    Hardware handshake

HANDSHAKE_NONE        0x2    No flow control

HANDSHAKE_BOTH        0x3    Both hardware and XON/XOFF


Your driver must return plcudetail with members type, baud, parity, data,
stop, and handshake properly filled in, even if this is a reconfiguration
and there is no change in these members.

The effect of the handshake member on various dispatcher output functions
varies by function, ADI version, and platform. See the tables below:

Table 10-17. Handshaking options for iow(PL)

Option          P386 pre-4.2     P386 4.2       Win 4.1     UNIX pre-4.2
UNIX 4.2

XONXOFF         no    yes  yes   yes   yes

HARDWARE        yes   yes  yes   maybe          maybe

NONE            yes   yes  yes   no    maybe

BOTH            no    yes  no    no    maybe



Table 10-18. Handshaking options for plsend()

Option          P386 pre-4.2     P386 4.2       Win 4.1     UNIX pre-4.2
UNIX 4.2

XONXOFF         always     always       yes     yes    yes

HARDWARE        yes   yes  yes   maybe  maybe

NONE            no    no   no    no     maybe

BOTH            no    yes  no    no     maybe



Table 10-19. Handshaking options for ppsend()

Option          P386 pre-4.2     P386 4.2       Win 4.1     UNIX pre-4.2
UNIX 4.2

XONXOFF         no    yes  yes   yes   yes

HARDWARE        yes   yes  yes   maybe          maybe

NONE            no    yes  no    no    maybe

BOTH            no    yes  no    no    maybe


Your instructions to users should indicate whether your driver does its own
I/O or uses the Autodesk ADI dispatcher services provided to allow AutoCAD
to handle I/O. If you have used the dispatcher functions, as we recommend,
the user can take advantage of the AutoCAD internal plot-to-file command
and the "autospool" capability. If your driver does direct I/O to the
hardware (bypassing AutoCAD), these features do not work.

If you handle your own I/O, your plot output should be faster. You
eliminate calls back into ACAD to output the pen commands to the port or
file. You also gain the ability to write I/O routines to talk to special
types of ports, networks, and so on, at the cost of losing the AutoCAD
critical error handling, and having plot-to-file and plot spooling fail to
work normally within AutoCAD.

It is possible to claim that your driver uses the AutoCAD output services
in DETAIL, examine the plbxpl42cfg.plspecs flag bit PL_FILE in GENERIC, and
redirect output to local routines if the user hasn't selected plot-to-file.



10.7.6 COLORTSPEED
====================

Purpose
-------
The driver is asked to return to the application a table that assigns a pen
speed to each color index. The application uses these as the default values
to present to the user in a pen speed configuration dialogue box.

Limitations
-----------
This packet must be solicited at configuration time after DETAIL by sending
struct plcdmodel with COLORSPEED in plcode and the model index in model.

COLORTSPEED is sent only to ADI 4.2 plotter drivers that set VARSPEED in
DETAIL.options. It is sent to all pre-ADI 4.2 drivers. It is sent only for
"new" configurations.

AutoCAD fills in all members of plcdmodel. The ADI driver fills in all
members of plcuspeedtab.

History
-------
This packet was introduced in OS/2 ADI 4.0 for AutoCAD 386 Release 10. It
has been expanded in AutoCAD Release 12 and ADI 4.2 for 256 colors.

Declaration
-----------
#define COLORTSPEED 23
#ifdef ADI42
#define MAXCOLOR    255
#else
#define MAXCOLOR    15
#endif
application sends:
------------------
struct plcdmodel {
    short plcode;       /* COLORSPEED */
    short plsize;       /* Sizeof packet */
    short model;        /* Model index */
};
driver returns:
---------------
struct plcuspeedtab {
    short plcode;              /* COLORTSPEED */
    short plsize;              /* Sizeof packet */
    short nspeeds;             /* Number of speeds */
    uchar table[MAXCOLOR+1];   /* Map of color to speed */
};

Description
-----------
AutoCAD calls the driver with member plcode in structure plcdmodel set to
COLORTSPEED and member model set to the appropriate model index if a new
configuration is in progress.

Your driver should return a structure of type plcuspeedtab and is
responsible for filling in the table in structure plcuspeedtab that maps
each color (0 to MAXCOLOR) to a specific speed. This establishes the
default speed values used in the AutoCAD pen dialogue with the user.

Your driver should also set nspeeds to the number of speeds supported by
the device.



10.7.7 COLORTLTYPE
====================

Purpose
-------
The driver is asked to return to the application a table that assigns a
line type to each color index. The application uses these as the default
values to present to the user in a line type configuration dialogue box.

Limitations
-----------
This packet must be solicited at configuration time after COLORSPEED by
sending struct plcdmodel with COLORLTYPE in plcode and the model index in
model.

COLORTLTYPE is sent only to ADI 4.2 plotter drivers that set MULTLINE in
DETAIL.options. It is sent to all pre-ADI 4.2 drivers. It is sent only for
"new" configurations.

AutoCAD fills in all members of plcdmodel. The ADI driver fills in all
members of plcultypetab.

History
-------
This packet was introduced in OS/2 ADI 4.0 for AutoCAD 386 Release 10. It
has been expanded in release 12 and ADI 4.2 for 256 colors.

Declaration
-----------
#define COLORLTYPE 22
#ifdef ADI42
#define MAXCOLOR    255
#else
#define MAXCOLOR    15
#endif
application sends:
------------------
struct plcdmodel {
    short plcode;       /* COLORLTYPE */
    short plsize;       /* Sizeof packet */
    short model;        /* Model index */
};
driver returns:
---------------
struct plcultypetab {
    short plcode;           /* COLORTLTYPE */
    short plsize;           /* Sizeof packet */
    short nlines;           /* Number of line types */
    uchar table[MAXCOLOR+1]; /* Map color to line type */
};

Description
-----------
AutoCAD calls the driver with member plcode in structure plcdmodel set to
COLORTLTYPE and member model set to the appropriate model index. It is sent
only for "new" configurations.

The driver returns a structure of type plcultypetab and is responsible for
filling in the table in structure plcultypetab that maps each color (0 to
MAXCOLOR) to a specific line type. This is used by AutoCAD to construct
default values for the line type dialogue with the user.

Your driver should also set nlines to the number of line types supported by
the device.

An AutoCAD convention assigns line type 0 to a solid line. You can assign
other line type numbers any meaning you like. The execution-time LEGEND
packet asks your driver to display your definitions.



10.7.8 PLWIDS
===============

Purpose
-------
This optional packet asks the driver to return to the application a table
that assigns a pen width to each color index. The application uses these as
the default values to present to the user in a pen width configuration
dialogue box.

Limitations
-----------
This packet should be sent only to pre-ADI 4.2 drivers immediately after
COLORLTYPE at configuration time. It is sent only for "new" configurations.

AutoCAD fills in all members of plcdmodel. The ADI driver fills in all
members of plcuwids.

History
-------
This packet was introduced in OS/2 ADI 4.0 for AutoCAD 386 Release 10. It
is replaced by PLWIDS_42 for ADI 4.2 drivers.

Declaration
-----------
#define PLWIDS     24
#define OLDCOLMAX  15
application sends:
------------------
struct plcdmodel {
    short plcode;       /* PLWIDS */
    short plsize;       /* Sizeof packet */
    short model;        /* Model index */
};
driver returns:
---------------
struct plcuwids {
    short plcode;             /* PLWIDS */
    short plsize;             /* Sizeof packet */
    short widths;             /* Number of widths */
    real pwid[OLDCOLMAX + 1];    /* Width table */
};

Description
-----------
AutoCAD calls the driver with member plcode in structure plcdmodel set to
PLWIDS and member model set to the appropriate model index. It is sent only
for "new" configurations.

Your driver should return a structure of type plcuwids and is responsible
for filling in the table in structure plcuwids that maps each color (0 to
MAXCOLOR) to a specific pen width as well as filling in member widths with
the number of pen widths. AutoCAD uses these values as the defaults in its
configuration dialogue with the user.

AutoCAD has not used the information solicited by this packet in any
version since OS/2. Drivers can ignore it.



10.7.9 PLWIDS_42
==================

Purpose
-------
The driver is asked to return to the application a table that assigns a pen
width to each color index. The application uses these as the default values
to present to the user in a pen width configuration dialogue box. Up to 256
pen widths, stored as reals (doubles), are normally set to a default value
of 0.01 inches.

Limitations
-----------
This packet should be sent only to ADI 4.2 drivers that set the PENWIDS bit
in the optbits member in DETAIL. It should be sent immediately after
COLORLTYPE at configuration time. It is sent only for "new" configurations.

AutoCAD fills in all members of plcdmodel. The ADI driver fills in all
members of pl42cuwids.

History
-------
Introduced in release 12 for ADI42. Modified during ADI 4.2 development by
changing ints to longs.

Declaration
-----------
#define PLWIDS_42 44

struct pl42cuwids {
    short plcode;     /* PLWIDS_42 */
    short plsize;     /* Sizeof packet */
    long widths;      /* Number of widths, all 256 of them */
    long offset;      /* Where we copy 2048 bytes */
    long offsize;     /* Size of pkt, 0 on Phar Lap, */
                      /* 2048 on UNIX */
};

#define PL42CUWIDSIZE (sizeof(struct pl42cuwids))

Description
-----------
PENWIDS_42 is a new packet used to receive the pen width data for all 256
AutoCAD colors. This packet uses a nonstandard packet transmission method
because of the P386 500-byte packet size restriction. The pen width data is
a 2K array of reals that is passed in a separate buffer. It is sent only
for "new" configurations.

The member offset indicates the starting address offset from the cmbufadr
to a 2K buffer used on Phar Lap to transport the pen widths. On UNIX, they
are at the end of the pl42cuwids structure.

The member offsize is used for the size of the returning packet. This is
just the size of the PLWIDS_42 packet on Phar Lap, but on UNIX it is the
packet size plus the size of the 256 reals added to the packet.

A sample driver use of this packet that works on both UNIX and DOS 386
drivers is as follows:

unsigned long tmprealptr; /* calc address, make a pointer */ real *rptr;
case PLWIDS_42:
#define PT pl42cuwids
    P->plcode = OK;
    P->plsize = P->offset + P->offsize;
    P->widths = modptr[index].pens;
    tmprealptr = (unsigned long)&(P->plcode) + P->offset;
    rptr = (real *)tmprealptr;
    for (j = 0; j <= MAXCOLOR; j++)
        *rptr++ = 0.01;
#undef PT
    break;

If your driver doesn't handle pen widths there is no need to use this
packet.

The values you supply here are used as default values for the AutoCAD
configuration dialogue with the user.



10.7.10 PLPENS
================

Purpose
-------
Lets the driver upload to AutoCAD a table that associates a pen number with
each AutoCAD color index. This is typically a default table that the user
can modify later in configuration.

Limitations
-----------
This packet must be solicited at configuration time after PLWIDS or
PLWIDS_42 by sending struct plcdmodel with PLPENS in plcode and the model
index in model. It is sent only for "new" configurations.

AutoCAD fills in all members of plcdmodel. The ADI driver fills in all
members of plcupens.

History
-------
This packet was introduced in OS/2 ADI 4.0 for AutoCAD 386 Release 10. It
has been expanded in release 12 and ADI 4.2 for 256 colors.

Declaration
-----------
#define PLPENS  25
#ifdef ADI42
#define MAXCOLOR    255
#else
#define MAXCOLOR    15
#endif
application sends:
------------------
struct plcdmodel {
    short plcode;       /* PLPENS */
    short plsize;       /* Sizeof packet */
    short model;        /* Model index */
};
driver returns:
---------------
struct plcupens {
    short plcode;              /* PLPENS */
    short plsize;              /* Sizeof packet */
    short pens;                /* Number of pens */
    uchar pnum[MAXCOLOR+1];    /* Pen number table */
};

Description
-----------
AutoCAD calls the driver with member plcode in structure plcdmodel set to
PLPENS and member model set to the appropriate model index. It is sent only
for "new" configurations.

Your driver should return a structure of type plcupens and is responsible
for filling in the table in structure plcupens that maps each color (0 to
MAXCOLOR) to a specific pen as well as the total number of pens in member
pens. These are used by AutoCAD as the default values in its configuration
dialogue with the user.

Color 0 is usually assigned to pen number 1.



10.7.11 CPREGENERIC
=====================

Purpose
-------
The AutoCAD generic plot dialogue data sent to the driver just before the
configuration-time configuration questions are asked by AutoCAD. This same
structure is sent after generic configuration in GENERIC_42, and at
execution time in EPRECONF_42, ECHGCONF_42, and GENERIC_42.

Limitations
-----------
This packet should be sent to ADI 4.2 plotters only at configuration time,
after PLPENS. This should be just before your application attempts generic
plot configuration. Your application should fill in all the values with the
most recent configuration or with your default values if this is a "new"
configuration.

AutoCAD fills in all members of this packet. The ADI driver can modify any
field except plsize. The ADI driver returns plcode as BAD if there is an
error or <Ctrl-C> detected during handling of this packet.

History
-------
Introduced in release 12 and ADI 4.2.

Declaration
-----------
#define CPREGENERIC  40
#define MAXUSR 5

struct plbxpl42cfg {
    short plcode;                           /* CPREGENERIC */
    short plsize;                         /* Sizeof packet */
    char pl_units;          /* 0 = inches, 1 = millimeters */
        long pl_specs;      /* ADI 4.2 specification flags */
    real pl_x, pl_y;                   /* Plot dimensions. */
    real pl_xmax, pl_ymax;          /* Max plot dimensions */
    real pl_xinc, pl_yinc;   /* X and Y plotter increments */
    real pl_orgx, pl_orgy;                 /* Plot origin. */
    char pl_szlab[9];            /* Standard size mnemonic */
    real pl_lwid;                   /* Line width (inches) */
    real pl_sclpu, pl_scldu;                      /* Scale */
    char pl_what;                         /* Viewport type */
    union {
        char pl_vname[31+1];                    /* View name
                                       (if pl_what == 'V') */
        real pl_w[4];               /* 'UV' Window corners */
    } pl_vw;
    char pl_optlv;                  /* Optimization level. */
    char pl_maxoptlv;               /* Optimization level. */
    short pl_dev1,     /* Cells reserved for device driver */
        pl_dev2;
    real  pl_usrx[MAXUSR],      /* User defined plot sizes */
        pl_usry[MAXUSR];
    real  lp_xmax;                  /* longplot paper size */
    real  lp_xinc;                  /* longplot x axis inc */
    real  lp_yinc;                  /* longplot y axis inc */
    real  lp_reduction;       /* longplot reduction factor */
    char  pltext[10];    /* Default plot-to-file extension */
};

#define PLBXPL42CFGSIZE (sizeof(struct plbxpl42cfg))

Description
-----------
The driver might need these values early in a reconfiguration, so they are
passed early in the configuration process.

This is a good time for driver-local questions to be asked of the user. It
is also time to change the global defaults listed in the plbxpl42cfg
structure to values more appropriate for your driver. For example, if your
device is a B size laser printer, you might want to use B instead of MAX
for your default paper size. You can set this in the pl_szlab. Set the
pl_specs bits at this time also. If your device only plots to file, 'OR' in
PL_FFILE or if file output is your driver's default, 'OR' in PL_FILE.

Your driver can return plcode as BAD if there is an error or if the user
presses <Ctrl-C> during the handling of this packet.

Table 10-20. Values for CPREGENERIC.pl_specs

Mnemonic         Value  Meaning if Set

PL_XYSWAP        0x001  Swap X and Y axis on plot

PL_SCALE         0x002  Scale specified

PL_MPEN          0x004  Multiple pen

PL_MPASS         0x008  Multiple pass on pens desired

PL_HIDE          0x0010                   Remove hidden lines

PL_FLCOR         0x0020                   Correct area fill for pen width

PL_FILE          0x0040                   Plot to a file flag

PL_ADI           0x0080                   ADI driver flag

PL_ROT1          0x00100                  First bit of plot rotation

PL_ROT2          0x00200                  Second bit of plot rotation

PL_LONGAXIS      0x00800                  Plotters with longaxis plotting

PL_FFILE         0x01000                  Forces plot-to-file only

PL_SORIENT       0x02000                  Set if "portrait" paper
orientation

PL_SYSPRN        0x10000                  This is a system printer driver

The following tests for various plot rotation values are defined in the
plp.h header file:

#define PLROT0(x) (!((x) & (PL_ROT1 | PL_ROT2)))
#define PLROT90(x) (((x) & PL_ROT1) && !((x) & PL_ROT2))
#define PLROT180(x) (!((x) & PL_ROT1) && ((x) & PL_ROT2))
#define PLROT270(x) (((x) & PL_ROT1) && ((x) & PL_ROT2))

Please see the discussion of GENERIC and GENERIC_42 for other details of
this packet.

After AutoCAD has received the driver's reply to this packet, AutoCAD asks
its configuration-time questions. AutoCAD completes a specific plotter
configuration dialogue with the user, and then goes through its own
"generic" configuration dialogue.

The user is given the plotting defaults and those modified by the driver in
the CPREGENERIC packet.

Plot optimization level = 2
Plot will NOT be written to a selected file
Sizes are in Inches
Plot origin is at (0.00,0.00)
Plotting area is 16.00 wide by 14.30 high (MAX size)
Plot is NOT rotated Pen width is 0.010
Area fill will NOT be adjusted for pen width
Hidden lines will NOT be removed
Plot will be scaled to fit available area

Do you want to change anything? (No/Yes/File(PCP)) <N>:

The results of any changes the user might have made are passed to the
driver in GENERIC or GENERIC_42.



10.7.12 GENERIC
=================

Purpose
-------
This lets the driver know what the application learned from the user during
generic plot configuration. It lets the driver modify the results of the
dialogue.

Limitations
-----------
This should be sent to pre-ADI 4.2 drivers right after your generic plot
dialogue, at configuration time. Your application must fill in all fields.
Your application must copy the data in this packet back into its
configuration record after the ADI driver returns it, in case the driver
has modified anything.

AutoCAD fills in all members of this packet. The ADI driver can modify any
field except plcode or plsize.

History
-------
This packet was introduced in OS/2 ADI 4.0 for AutoCAD 386 Release 10. It
was extended in ADI 4.1 for release 11 by the addition of pl_newspec. It
has been replaced by GENERIC_42 for ADI 4.2 and release 12.

Declaration
-----------
#define GENERIC  13

struct plbxplotcfg {
    short plcode;                               /* GENERIC */
    short plsize;                        /* Size of packet */
    char                                         /* Flags: */
        pl_units,           /* 0 = inches, 1 = millimeters */
        pl_specs;           /* ADI 4.0 specification flags */
    real pl_x, pl_y;                   /* Plot dimensions. */
    real pl_xmax, pl_ymax;          /* Max plot dimensions */
    real pl_xinc, pl_yinc;   /* X and Y plotter increments */
    real pl_orgx, pl_orgy;                 /* Plot origin. */
    char pl_szlab[5];            /* Standard size mnemonic */
    real pl_lwid;                   /* Line width (inches) */
    real pl_sclpu, pl_scldu;                      /* Scale */
    char pl_what;                         /* Viewport type */
    union {
        char pl_vname[31+1];                     /* View name
                                       (if pl_what == 'V') */
        real pl_w[4];               /* 'UV' Window corners */
    } pl_vw;
    char pl_optlv;                  /* Optimization level. */
    short pl_dev1,        /* Cells reserved for driver use */
        pl_dev2;
    short pl_newspec;               /* ADI 4.1 specs field */
};

Description
-----------
AutoCAD calls the driver with member plcode in structure plbxplotcfg set to
GENERIC. AutoCAD initializes the other members of the structure with
information obtained from the user (in the AutoCAD generic plot dialogue
box).

Your driver can now look at the data configured in the generic plot
dialogue with the user. You can make changes in the data, if necessary, and
AutoCAD updates its configuration record. It is not advisable to make
significant changes here without notifying or asking the user.

This packet was extended in ADI 4.1 by the addition of member pl_newspec.
The internal pl_specs stored in AutoCAD core have been expanded from a char
to a short. To retain compatibility with pre-4.1 drivers, the low 8 bits of
the internal pl_specs are passed in member pl_specs. ADI 4.1 drivers should
instead examine pl_newspec, which contains all 16 bits of data.

Table 10-21. Values for GENERIC.pl_newspec

Mnemonic        Value                 Meaning if Set

PL_XYSWAP       0x1  Swap X and Y axes on plot

PL_SCALE        0x2  Scale specified

PL_MPEN         0x4  Multiple pen

PL_MPASS        0x8  Multiple pass on pens desired

PL_HIDE         0x10                  Remove hidden lines

PL_FLCOR        0x20                  Correct area fill for pen width

PL_FILE         0x40                  Plot to a file flag

PL_ADI          0x80                  ADI driver flag

PL_ROT1         0x100                 First bit of plot rotation

PL_ROT2         0x200                 Second bit of plot rotation

The following tests for various plot rotation values are defined in plp.h:

#define PLROT0(x) (!((x) & (PL_ROT1 | PL_ROT2)))
#define PLROT90(x) (((x) & PL_ROT1) && !((x) & PL_ROT2))
#define PLROT180(x) (!((x) & PL_ROT1) && ((x) & PL_ROT2))
#define PLROT270(x) (((x) & PL_ROT1) && ((x) & PL_ROT2))


10.7.13 GENERIC_42
====================

Purpose
-------
This tells the driver what the application learned from the user during
generic plot configuration. It lets the driver modify the results of the
dialogue.

Limitations
-----------
This packet can be sent only to ADI 4.1 AutoCAD for Windows or ADI 4.2 and
later plotter drivers on other platforms. It must be sent at configuration
time immediately after your application completes its generic plot
configuration dialogue and must be filled in by your application with the
results of that dialogue. Your application must copy the data in this
packet back into its configuration record after the ADI driver returns it,
in case the driver has modified anything, unless the ADI driver returns BAD
in plcode. If so, the configuration should be terminated.

AutoCAD fills in all members of this packet. The ADI driver can modify any
field except plsize, but most drivers do not modify any data here.

History
-------
Introduced in ADI 4.1 for Windows and in ADI 4.2 for other platforms.
Replaces GENERIC.

Declaration
-----------
#define GENERIC_42   47
#define MAXUSR       5

struct plbxpl42cfg {
    short plcode;               /* CPREGENERIC */
    short plsize;               /* Sizeof packet */
    char pl_units;              /* 0 = inches, 1 = millimeters */
    long pl_specs;              /* ADI 4.2 spec flags */
    real pl_x, pl_y;            /* Plot dimensions. */
    real pl_xmax, pl_ymax;      /* Max plot dimensions */
    real pl_xinc, pl_yinc;      /* X and Y plotter increments */
    real pl_orgx, pl_orgy;      /* Plot origin. */
    char pl_szlab[9];           /* Standard size mnemonic */
    real pl_lwid;               /* Line width (inches) */
    real pl_sclpu, pl_scldu;    /* Scale */
    char pl_what;               /* Viewport type */
    union {
        char pl_vname[31+1];    /* View name (if pl_what=='V') */
        real pl_w[4];           /* 'UV' Window corners */
    } pl_vw;
    char pl_optlv;              /* Optimization level. */
    char pl_maxoptlv;           /* Optimization level. */
    short pl_dev1,              /* Cells reserved for */
          pl_dev2;              /*   device driver */
    real  pl_usrx[MAXUSR],      /* User-defined plot sizes* /
          pl_usry[MAXUSR];
    real  lp_xmax;              /* Longplot paper size */
    real  lp_xinc;              /* Longplot X axis inc*/
    real  lp_yinc;              /* Longplot Y axis inc*/
    real  lp_reduction;         /* Longplot reduction factor */
    char  pltext[10];         /* Default plot-to-file extension */
};

#define PLBXPL42CFGSIZE (sizeof(struct plbxpl42cfg))

Description
-----------
AutoCAD calls the driver with member plcode in structure plbxpl42cfg set to
GENERIC_42. AutoCAD initializes the other members of the structure with
information obtained from the user in the AutoCAD generic plot dialogue
box.

Your drivers can now look at the data configured in the generic plot
dialogue with the user. You can change the data, if necessary, and AutoCAD
updates its configuration record. It is not advisable to make major changes
here without notifying or asking the user.

If an ADI 4.2 driver detects a condition in which it wants the plot
terminated, it should return BAD in member plcode.

The following flags are defined for pl_specs:

Table 10-22. Values for GENERIC_42.pl_specs

Mnemonic        Value                   Meaning if Set

PL_XYSWAP       0x001                   Swap X and Y axes on plot

PL_SCALE        0x002                   Scale specified

PL_MPEN         0x004                   Multiple pen

PL_MPASS        0x008                   Multiple pass on pens desired

PL_HIDE         0x0010                  Remove hidden lines

PL_FLCOR        0x0020                  Correct area fill for pen width

PL_FILE         0x0040                  Plot to a file flag

PL_ADI          0x0080                  ADI driver flag

PL_ROT1         0x00100                 First bit of plot rotation

PL_ROT2         0x00200                 Second bit of plot rotation

PL_LONGAXIS     0x00800                 Plotters with longaxis plotting

PL_FFILE        0x01000                 Forces plot-to-file only

PL_SORIENT      0x02000                 Set if "portrait" paper orientation

PL_SYSPRN       0x10000                 This is a system printer driver

These are new members added to the packet in ADI 4.2 (these are not used in
Windows ADI 4.1):

Member pl_maxoptlv lets a driver set a maximum pen optimization level. This
lets the driver block the user from selecting a meaningless optimization
level for a device that has no pens, for example.

Members pl_usrx[MAXUSR] and pl_usry[MAXUSR], added in release 12, let users
save up to 5 user-defined plot sizes.

Members lp_xmax, lp_xinc, lp_yinc, and lp_reduction were added in release
12 to provide better support for longplots.



10.7.14 ENDPLOT
=================

Purpose
-------
Signals a UNIX driver that configuration is complete. Tells the driver to
terminate.

Limitations
-----------
On UNIX platforms, at the end of configuration time, plotter drivers are
terminated with ENDPLOT. The driver is reloaded at execution time.

AutoCAD fills in all members of this packet. The ADI driver treats this
packet as read-only.

History
-------
This packet was introduced with the OS/2 ADI interface in ADI 4.0 for
release 10. Its use was extended to configuration time for UNIX platforms
in ADI 4.1 for release 11.

Declaration
-----------
#define ENDPLOT  2

struct pledpkt {
    short plcode;        /* ENDPLOT */
    short plsize;        /* Size of packet */
    unsigned short x, y; /* Argument or X and Y values */
};

Description
-----------
The ENDPLOT code is sent at the end of configuration on UNIX. It is also
sent at the end of plotting on all platforms. It has no arguments. When
this code is received, the driver should perform its cleanup, call
dispterm(), and return to AutoCAD.

In UNIX ADI, the ENDPLOT packet can be sent at configuration time. It is
important that drivers know it is configuration time and avoid improper
actions (i.e., sending data to an uninitialized device or unopened output
file). UNIX ADI requires that a plotter driver terminate after
configuration via a call to dispterm(). A call to dispterm() must be made
as the last statement in the plotter driver's ENDPLOT handler. For UNIX ADI
plotters, dispterm() kills the process after some internal housekeeping.




10.8 Execution-Time Configuration Packet Descriptions
=====================================================

When the user asks AutoCAD to plot a drawing, the AutoCAD program the
"execution-time configuration" plotter packets begin flowing to the driver.
Prior to release 12, the Plot command could be invoked either from the
drawing editor (in which case AutoCAD switched to the text screen for
execution-time plot configuration) or from the Main menu (already in Text
mode). AutoCAD Release 12 no longer has the Main menu. All plots are from
inside the AutoCAD program. By default, the release 12 execution-time plot
configuration is done in a dialogue box, but the user can set CMDDIA to 0
and do plot configuration on the text screen.

The user goes through a "generic" plot configuration dialogue with AutoCAD
before the plot begins. ADI drivers can look at this configuration
information and change it. The driver also can enter into a "specific"
configuration dialogue with the user. The execution-time configuration
packets include: PWHO, PLANG, EINIT, EPRECONF, EPRECONF_42, ESHOW,
ECHGCONF, ECHGCONF_42, LEGEND, GENERIC, GENERIC_42, SPECIFIC, SPECIFICPENS,
SPECIFICSPEED, SPECIFICLTYPE, SPECIFICWIDS, SPECIFIC_42, EPOSTCONF, and
PLOTSIZE.

In AutoCAD Release 12, a new execution-time dialogue box interface replaces
the earlier text-based plotter configuration process. When release 12
plotter dialogues are used, the execution-time configuration packets can be
sent repeatedly to an ADI driver as the user clicks on various buttons in
the dialogue box. This flow of packets is somewhat different from earlier
versions of AutoCAD, where the execution-time configuration process was
text-based and linear.



10.8.1 PWHO
=============

Purpose
-------
Tells the driver which application is controlling.

Limitations
-----------
This should be the first execution packet sent to ADI 4.2 drivers. It
should have PWHO.action set to WHO_XQT if you are a primary application.
The controlling application fills in pfunc, psize, product, prod_version,
adipktlevel, action, serial, regapp_name, (if an ADS application), and cpid
(if UNIX). It is also desirable for the controlling application to fill in
cleanup with 0 and status with GOOD beforehnad, in case a driver fails to
fill them in.

Applications without a serial number should stuff EOS into member serial.
Applications such as AVE Render that load a driver but do not support alias
device names should stuff 0 in member alias.

AutoCAD fills in pfunc, psize, product, prod_version, adipktlevel, action,
screen (0 for digitizers), alias, serial, driver_path, and cpid. The ADI
driver fills in cleanup (0 for digitizers), driver_name, and dpid.

History
-------
This packet was added in AutoCAD Release 12 and ADI 4.2.

Declaration
-----------
#define PWHO  49    /* for plotters */

Description
-----------
See the discussion of PWHO earlier in this document.



10.8.2 PLANG
==============

Purpose
-------
Lets plotter drivers know the language and code page being used by AutoCAD.
This is helpful in internationalizing drivers.

Limitations
-----------
PLANG should be the second packet sent to ADI 4.2 and later plotter drivers
at both configuration and execution time. This packet should not be sent to
pre-ADI 4.2 drivers. It is sent only by the primary application and should
not be used by secondary applications.

AutoCAD fills in all members of this packet. The ADI driver treats this
packet as read-only.

History
-------
The use of PLANG for plotter drivers was added in ADI 4.2 to support
AutoCAD Release 12.

Declaration
-----------
#define PLANG  50      /* for plotter drivers (see plp.h) */

Description
-----------
See the discussion of PLANG earlier in this document.



10.8.3 EINIT
==============

Purpose
-------
Execution-time driver initialization.

Limitations
-----------
This should be the first execution packet for pre-ADI 4.2 drivers and the
third execution packet (following PLANG) for ADI 4.2 and later.

AutoCAD fills in all members of this packet. The ADI driver can modify
plcode, version, and status.

History
-------
EINIT was introduced in OS/2 ADI 4.0 for release 10. The members thwnd and
ghwnd were added for Windows in ADI 4.1. The value to be returned in plcode
in case of error was changed from ERR to BAD in ADI 4.2.

Declaration
-----------
#define EINIT 29

struct plbxinit {
    short plcode;    /* EINIT */
    short plsize;    /* Sizeof packet */
    short version;   /* ADI version number */
    short status;    /* Status code */
    short colours;   /* Max colors */
    char alias;      /* Alias ID */
#if WIN
    HWND thwnd;      /* Text window handle */
    HWND ghwnd;      /* Graphics window handle */
#endif /* WIN */
};
Description
-----------
AutoCAD calls the driver with member plcode in structure plbxinit set to
EINIT, member alias is set to the alias ID, colours is set to (MAXCOLOR +
1), and version is set to the current AutoCAD ADI version number
(ADIPKTLEVEL).

The version member should be set by your driver to the ADI version it
supports. ADI 4.2 drivers, for example, return PL_LEVEL_42 in member
version.

If the driver is for a hardware plotter, the device should be physically
initialized at this time. A successful initialization is assumed. If device
initialization is NOT successful, pre-ADI 4.2 drivers should return ERR in
EINIT.plcode. ADI 4.2 and later drivers return BAD in member plcode to
report errors or the detection of <Ctrl-C>.

Table 10-23. Values for EINIT.status

Mnemonic         Value Meaning if Set

HARDWARE         0x0   Driver is for a physical plotter

NULLPLOTTER      0x1   No plotter output (null PL driver)

ASCIIFILE        0x2   Plot to an ASCII file

BINARYFILE       0x3   Plot to a binary file

ACADDXBFILE      0x4   Plot to an AutoCAD DXB file

A regular hardware plotter driver should return HARDWARE in status. For
release 12 and ADI4.2, only HARDWARE is accepted here; ASCIIFILE,
BINARYFILE, and ACADDXBFILE are treated as hardware.

Before AutoCAD goes through its execution-time generic plot configuration
dialogue with the user, it sends the driver the SPECIFIC_42 sequence of
packets (or the SPECIFIC packet for old drivers) followed by an EPRECONF
packet. This gives the driver essential data that was stored in the
configuration records, both device-specific and plot-generic.

Windows ADI 4.1
---------------
The CINIT and EINIT packets (structure plbxinit) have two new members,
thwnd and ghwnd. These are the text and graphics window handles
respectively. These handles are currently used by the Generic System
Printer driver PLSYS.DLL when making Windows system calls requiring a
window handle. However, any plotter driver that makes Windows system calls
might find these handles useful.

AutoCAD sets the status member of the EINIT packet to the state of the
printer selection radio button from the AutoCAD Environment Settings
dialogue box.

If status is set to 1, the user has selected the Use Control Panel
Configuration radio button from the AutoCAD Environment Settings dialogue
box. Otherwise status is set to 0. The sample system printer driver uses
this value to determine which Windows printer driver to load.



10.8.4 SPECIFIC
=================

Purpose
-------
Device-specific configuration information sent to driver.

Limitations
-----------
SPECIFIC can be sent only to ADI 4.1 and earlier drivers. It should be sent
right after EINIT at execution time. Your application is responsible for
filling in all members of pledmodcfg with the information from your
configuration record. The ADI driver can modify plcode in the event of a
serious error.

History
-------
Introduced in OS/2 ADI 4.0 for release 10. Replaced by SPECIFICPENS,
SPECIFICSPEED, SPECIFICLTYPE, and SPECIFIC_42 for release 12 and ADI 4.2.

Declaration
-----------
#define SPECIFIC  14
#define OLDCOLMAX 15

struct pledplmodcfg {
    short plcode;             /* SPECIFIC */
    short plsize;             /* Sizeof packet */
    char d_modinx,            /* Index into feature table */
        d_hook,               /* Op sys interface */
        d_ltype[OLDCOLMAX+1], /* Map color to line type */
        d_speed[OLDCOLMAX+1], /* Pen speed */
        d_npens,              /* Number of pens */
        d_spmax,              /* Max pen speed */
        d_ltmax;              /* Number of line types */
        short d_bits;         /* Option bits */
        struct plpens d_pens; /* Map color to pen numbers */
        struct plwids d_wids; /* Map color to pen widths */
};
Description
-----------
AutoCAD sends SPECIFIC with all the members filled in with information
obtained from the driver at configuration time.

Your driver is not expected to respond to this informational packet unless
something is seriously wrong. In that case, pre-ADI 4.2 drivers can return
ERR in member plcode.



10.8.5 SPECIFICPENS
=====================

Purpose
-------
Sends plotter-specific pen number information from the application to the
driver for up to 256 pens. This informational packet many drivers ignore.

Limitations
-----------
This packet is sent to ADI 4.2 plotters in a group of packets:
SPECIFICPENS, SPECIFICSPEED, SPECIFICLTYPE, SPECIFICWIDS (if the driver
supports pen widths), and SPECIFIC_42 at execution time. AutoCAD Release 12
sends this group of packets repeatedly to ADI plotters at execution time,
both before and after execution-time configuration. This lets drivers see
how the AutoCAD internal configuration record has been changed. Your
application fills in the table that relates pen numbers to color indices.

It is sent only if the bit MULTPEN is set in the device's configuration
record member d_bits.

AutoCAD fills in all members of this packet. The ADI driver can modify
plcode in the event of a serious error.

History
-------
Introduced in release 12 and ADI 4.2. Replaces part of the old SPECFIC
packet.

Declaration
-----------
#define SPECIFICPENS  35     /* Copy specific pens for config */
#define MAXCOLOR  255

struct pl42cupens {
    short plcode;            /* SPECIFICPENS */
    short plsize;            /* Sizeof packet, PL42CUPENSSIZE */
    short pens;              /* Number of pens */
    uchar pnum[MAXCOLOR+1];  /* Pen number table */
};
#define PL42CUPENSSIZE (sizeof(struct pl42cupens))

Description
-----------
AutoCAD calls the driver with member plcode in structure pl42cupens set to
SPECIFICPENS. AutoCAD initializes the table with the pen information in its
internal configuration record. The values in pnum[] are the pen numbers
assigned to the corresponding AutoCAD color index. For example, pnum[3]
holds the pen number AutoCAD has assigned to color number 3.

If your driver has no discrete pens to assign to color indices, this packet
can be ignored. Likewise if your driver does not need advance notification
of the color->pen number assignments, you can ignore this packet. During
plotting, explicit pen changes are sent to your driver in NEWPEN packets.

Your driver is not expected to respond to this informational packet unless
something is seriously wrong. In that case, the driver can return BAD in
member plcode.



10.8.6 SPECIFICSPEED
======================

Purpose
-------
The application sends the driver its current table of pen speeds versus
AutoCAD color indices. This informational packet requires no response from
the driver.

Limitations
-----------
This packet is sent to ADI 4.2 plotters that set VARSPEED in
DETAIL.options. It is sent in a group of packets: SPECIFICPENS,
SPECIFICSPEED, SPECIFICLTYPE, SPECIFICWIDS (if the driver supports pen
widths), and SPECIFIC_42 at execution time. Your application fills in the
table that relates pen speeds to color indices.

It is sent only if the bit VARSPEED is set in the device's configuration
record member d_bits.

AutoCAD fills in all members of this packet. The ADI driver can modify
plcode in the event of a serious error.

History
-------
Introduced in release 12 and ADI 4.2. Replaces part of the old SPECFIC
packet.

Declaration
-----------
#define SPECIFICSPEED 37    /* Copy specific speeds config */

struct pl42cuspeedtab {
    short plcode;                         /* SPECIFICSPEED */
    short plsize;     /* Sizeof packet, PL42CUSPEEDTABSIZE */
    short nspeeds;                     /* Number of speeds */
    uchar table[MAXCOLOR+1];     /* Map of color to speed */
};

#define PL42CUSPEEDTABSIZE (sizeof(struct pl42cuspeedtab))

Description
-----------
AutoCAD calls the driver with member plcode in structure pled42modcfg set
to SPECIFICSPEED. AutoCAD initializes the table with the pen speed
information contained in its configuration record. The values in table[]
are the pen speeds assigned to the corresponding AutoCAD color index. For
example, table[4] holds the pen number AutoCAD has assigned to color number
4.

If your driver has no discrete pens or speeds assigned to pens, this packet
can be ignored. Likewise if your driver does not need advance notification
regarding speed data, you can ignore this packet. Explicit pen speed
changes are also sent during the actual plot in NEWSPEED packets.

Your driver is not expected to respond to this informational packet unless
something is seriously wrong. In that case, the driver can return BAD in
member plcode.



10.8.7 SPECIFICLTYPE
======================

Purpose
-------
Sends plotter-specific line type information from the application to the
driver for up to 256 pens. This informational packet normally requires no
action from the driver.

Limitations
-----------
This packet is sent to ADI 4.2 plotters that set MULTLINE in
DETAIL.options. It is sent in a group of packets: SPECIFICPENS,
SPECIFICSPEED, SPECIFICLTYPE, SPECIFICWIDS (if the driver supports pen
widths), and SPECIFIC_42 at execution time. Your application fills in the
table that relates line types to color indices.

It is sent only if the bit MULTLINE is set in the device's configuration
record member d_bits.

AutoCAD fills in all members of this packet. The ADI driver can modify
plcode in the event of a serious error.

History
-------
Introduced in release 12 and ADI 4.2. Replaces part of the old SPECFIC
packet.

Declaration
-----------
#define SPECIFICLTYPE 36    /* Copy specific ltypes config */

struct pl42cultypetab {
    short plcode;                         /* SPECIFICLTYPE */
    short plsize;                         /* Sizeof packet */
    short nlines;                  /* Number of line types */
    uchar table[MAXCOLOR+1]; /* Map of color to line type */
    };

#define PL42CULTYPETABSIZE (sizeof(struct pl42cultypetab))

Description
-----------
AutoCAD calls the driver with member plcode in structure pled42modcfg set
to SPECIFICLTYPE. AutoCAD initializes the table with the line type
information stored in its configuration record. The values in table[] are
the line types assigned to the corresponding AutoCAD color index, for
example, table[14] holds the line type number AutoCAD has assigned to color
number 14.

If your driver has no discrete pens or line types assigned to pens this
packet can be ignored. Likewise if your driver does not need advance
notification regarding linetype data, you can ignore this packet. Explicit
line type changes are also sent during the actual plot in NEWLTYPE packets.

Your driver is not expected to respond to this informational packet unless
something is seriously wrong. In that case, the driver can return BAD in
member plcode.



10.8.8 SPECIFICWIDS
=====================

Purpose
-------
Sends the currently configured table of pen width versus AutoCAD color
index data from the application to the driver for up to 256 pens. This
informational packet normally requires no response from the driver.

Limitations
-----------
This packet is sent to ADI 4.2 plotters if PENWID is set in DETAIL.options.
It is sent in a group of packets: SPECIFICPENS, SPECIFICSPEED,
SPECIFICLTYPE, SPECIFICWIDS (if the driver supports pen widths), and
SPECIFIC_42 at execution time. Your application fills in the table that
relates pen widths to color indices.

It is sent only if the bit PENWID is set in the device's configuration
record member d_bits.

AutoCAD fills in all members of this packet. The ADI driver can modify
plcode in the event of a serious error.

History
-------
Introduced in release 12 and ADI 4.2. Replaces part of the old SPECFIC
packet. The packet structure was modified during ADI 4.2 development by
changing ints to longs.

Declaration
-----------
#define SPECIFICWIDS  38  /* Copy specific pens for config */

struct pl42cuwids {
    short plcode;                          /* SPECIFICWIDS */
    short plsize;                         /* Sizeof packet */
    long widths;      /* Number of widths, all 256 of them */
    long offset;               /* Where we copy 2048 bytes */
    long offsize;           /* Size of pkt, 0 on Phar Lap, */
                                           /* 2048 on UNIX */
};

#define PL42CUWIDSSIZE (sizeof(struct pl42cupens))

Description
-----------
AutoCAD calls the driver with member plcode in structure pl42cuwids set to
SPECIFICWIDS. AutoCAD initializes the table with the pens width information
stored in its configuration record. The values in the table are the pen
width assigned to the corresponding AutoCAD color index.

SPECIFICWIDS is a new packet used to send the pen width data for all of
AutoCAD's 256 colors. This packet uses a nonstandard packet transmission
method because of the P386 500-byte packet size restriction. The pen width
data is a 2K array of reals passed in a separate buffer.

The member offset indicates the starting address offset from the cmbufadr
to a 2K buffer used on Phar Lap to transport the pen widths. On UNIX, this
offset is zero, indicating that the pen width table is at the end of the
pl42cuwids structure.

The member offsize is used for the size of the returning packet. This is
just the size of the PLWIDS_42 packet on Phar Lap, but on UNIX it is the
packet size plus the size of the 256 reals added to the packet.

If your driver has no discrete pens or pen widths assigned to pens, this
packet can be ignored. Likewise if your driver does not need advance
notification regarding linetype data, you can ignore this packet. Explicit
line type changes are also sent during the actual plot in NEWPENWID
packets.

Your driver is not expected to respond to this informational packet unless
something is seriously wrong. In that case, the driver can return BAD in
member plcode.



10.8.9 SPECIFIC_42
====================

Purpose
-------
The application returns its device-specific configuration record to the ADI
driver after the user has requested a plot at execution time and before the
application has completed the execution-time configuration dialogue. This
informational packet does not normally require a response from the ADI
driver.

Limitations
-----------
This packet is sent to ADI 4.2 plotters in a group of packets:
SPECIFICPENS, SPECIFICSPEED, SPECIFICLTYPE, SPECIFICWIDS (if the driver
supports pen widths) and SPECIFIC_42 at execution time. Your application
fills in the structure pled42sparse with data from your configuration
record.

AutoCAD fills in all members of this packet. The ADI driver can modify
plcode in the event of a serious error.

History
-------
Introduced in ADI 4.2 and release 12. This packet replaces SPECIFIC. The
old SPECIFIC packet contained all the pen tables. In ADI 4.2, these have
been separated into SPECIFICPENS, SPECIFICSPEED, SPECIFICLTYPE, and
SPECIFICWIDS due to the additional pens supported.

Declaration
-----------
#define SPECIFIC_42  43
#define DDSIZE       50
/* Moved the elements w/ 256 elements out of the structure */

struct pled42sparse {        /* plmodcfg record for ADI42 */
    short plcode;                          /* SPECIFIC_42 */
    short plsize;                        /* Sizeof packet */
    uchar d_modinx,           /* Index into feature table */
        d_hook,      /* Op sys SERIAL/PARALLEL/HPIB iface */
        d_npens,                        /* Number of pens */
        d_spmax,                         /* Max pen speed */
        d_ltmax;                  /* Number of line types */
    short d_bits;                          /* Option bits */
    uchar d_ndd;
    uchar d_driver_data[DDSIZE];      /* More driver data */
};
#define PLED42SPARSESIZE (sizeof(struct pled42sparse))

Description
-----------
AutoCAD calls the driver with member plcode in structure pled42modcfg set
to SPECIFIC_42. AutoCAD initializes the other members of the structure with
information stored in its configuration record.

Your driver is not expected to respond to this informational packet unless
something is seriously wrong. In that case, the driver can return BAD in
member plcode.



10.8.10 EPRECONF
==================

Purpose
-------
This sends part of the AutoCAD internal configuration record to the ADI
plotter for examination and possible modification shortly before execution-
time configuration dialogue box. This lets the ADI driver change some
values presented to the user, if necessary.

Limitations
-----------
EPRECONF can be sent to ADI 4.1 and older drivers. It must be sent at
execution time after SPECIFIC and before ESHOW. Your application must fill
in all members with data from your configuration record. If the driver
returns plcode as UPDCFGREC, you must modify your configuration record with
the new data.

AutoCAD fills in all members of this packet. The ADI driver can modify any
member of this packet except plsize.

History
-------
Introduced in OS/2 ADI 4.0 for release 10. Replaced by EPRECONF_42 in ADI
4.2 for release 12.

Declaration
-----------
#define EPRECONF  1

struct plebipkt {
    short plcode;         /* EPRECONF */
    short plsize;         /* sizeof packet */
    short version;        /* ADI version number */
    real plxmax, plymax;  /* Max plot dimensions */
    real plx, ply;        /* Plot dimensions */
    real plxinc, plyinc;  /* X and Y plotter increments */
    real pllwid;          /* Line width (inches) */
    short plnpens;        /* Number of pens */
    short plspdmax;       /* Max pen speed */
    short plltmax;        /* Max # of hardware line types */
    short options;        /* Option bits */
};
Description
-----------
AutoCAD calls the driver with the plcode member in structure plebipkt set
to EPRECONF just before the start of plot time configuration.

If your driver changes anything in this packet, it must return UPCFGREC in
plcode to tell AutoCAD to record the changes. The members that can be
changed are these: plxmax, plymax, plx, ply, plxinc, plyinc, pllwid,
plnpens, plspdmax, and plltmax.



10.8.11 EPRECONF_42
=====================

Purpose
-------
This packet sends the contents of the AutoCAD generic plot-configuration
record to the plotter driver. It lets the driver examine and possibly
modify these data before they are shown to the user in the XQT
configuration process. This same structure was sent before generic CFG plot
configuration in CPREGENERIC, right after generic CFG configuration in
GENERIC_42, and can be sent again later in GENERIC_42 and ECHGCONF_42.

Limitations
-----------
EPRECONF_42 can be sent to ADI 4.2 and later drivers. It must be sent at
execution time after SPECIFIC_42 and before ESHOW or ECHGCONF. Your
application must fill in all members with data from your configuration
record. If the driver returns plcode as UPDCFGREC, you must modify your
configuration record with the new data.

AutoCAD fills in all members of this packet. The ADI driver can modify any
member of this packet except plsize.

History
-------
Introduced in release 12 and ADI 4.2. Replaces EPRECONF.

The structure has been modified to conform with the complete plotcfg record
used by AutoCAD for release 12. Note that member names are different than
the old EPRECONF packet. This is to ensure consistency with the other ADI
4.2 packet member names.

Declaration
-----------
#define EPRECONF_42  48
#define MAXUSR       5

struct plbxpl42cfg {
    short plcode;                           /* CPREGENERIC */
    short plsize;                         /* Sizeof packet */
    char pl_units;          /* 0 = inches, 1 = millimeters */
    long pl_specs;          /* ADI 4.2 specification flags */
    real pl_x, pl_y;                   /* Plot dimensions. */
    real pl_xmax, pl_ymax;          /* Max plot dimensions */
    real pl_xinc, pl_yinc;   /* X and Y plotter increments */
    real pl_orgx, pl_orgy;                 /* Plot origin. */
    char pl_szlab[9];            /* Standard size mnemonic */
    real pl_lwid;                   /* Line width (inches) */
    real pl_sclpu, pl_scldu;                      /* Scale */
    char pl_what;                         /* Viewport type */
    union {
    char pl_vname[31+1];  /* View name (if pl_what == 'V') */
    real pl_w[4];                   /* 'UV' Window corners */
    } pl_vw;
    char pl_optlv;                  /* Optimization level. */
    char pl_maxoptlv;               /* Optimization level. */
    short pl_dev1,     /* Cells reserved for device driver */
          pl_dev2;
    real  pl_usrx[MAXUSR],      /* User-defined plot sizes */
          pl_usry[MAXUSR];
    real  lp_xmax;                  /* longplot paper size */
    real  lp_xinc;                  /* longplot X axis inc */
    real  lp_yinc;                  /* longplot Y axis inc */
    real  lp_reduction;       /* longplot reduction factor */
    char  pltext[10];    /* Default plot-to-file extension */
};
#define PLBXPL42CFGSIZE (sizeof(struct plbxpl42cfg))

Description
-----------
AutoCAD calls the driver with the plcode member in structure plbxpl42cfg
set to EPRECONF_42 just before the start of plot-time configuration.

If your driver changes anything in this packet, it must return UPCFGREC in
plcode to tell AutoCAD to record the changes.

If something is seriously wrong, your driver can return BAD in plcode.



10.8.12 ESHOW
===============

Purpose
-------
Notifies the driver that AutoCAD is about to show the user the current plot
configuration and ask her if she wants to change anything.

Limitations
-----------
Must be sent to all plotter drivers at execution time just before the
current plot configuration is displayed to the user.

In AutoCAD Release 12, when the plot dialogue box is enabled, this is sent
when the user selects "Show Device Requirements..." in the Device and
Default Selection dialogue window.

AutoCAD fills in all members of this packet. The ADI driver treats this as
a read-only packet.

History
-------
Added in ADI 4.1 for release 11.

Declaration
-----------
#define ESHOW  31

struct pledpkt {
    short plcode;        /* ESHOW */
    short plsize;        /* Size of packet */
    unsigned short x, y; /* Argument or X and Y values */
};

Description
-----------
If CMDDIA is set to 0 (disabling the plot dialogue box), and the text
screen for execution-time (plot) configuration is on a pre-release 12
version of AutoCAD, the ESHOW packet is sent when AutoCAD is about to
display the currently configured values in the generic plot dialogue box.
This question follows the displayed configuration:

Do you want to change anything? (No/Yes/File/Save) <N>:

In AutoCAD Release 12, when the plot dialogue box is enabled, this is sent
when the user selects "Show Device Requirements..." in the Device and
Default Selection dialogue window.

At this time, your driver can display special device-specific settings that
the user might want to change at plot time, and that cannot be changed in
the generic plot dialogue box.

If your driver uses dispatcher functions to display information at ESHOW
time (e.g., using mprintf()), and if the release 12 plot configuration
dialogue box is active, the Change Device Requirements button is enabled,
and a ECHGCONF_42 packet is sent in response to the user selecting this
widget. Thus, your driver should ask questions at ECHGCONF_42 time to
solicit new values for the parameters shown at ESHOW time.

The sample Epson 24-pin printer plotter driver (PLEP) shows an example of
using this packet.



10.8.13 LEGEND
================

Purpose
-------
Asks the driver to display its driver-defined line types.

Limitations
-----------
Can be sent at both configuration and execution time.

In AutoCAD Release 12, when the plot dialogue box is enabled, this is sent
when the user selects "Feature Legend ..." in Pen Assignments dialogue
window.

AutoCAD fills in all members of this packet. The ADI driver treats this as
a read-only packet.

History
-------
Introduced in OS/2 ADI 4.0 for release 10.

Declaration
-----------
#define LEGEND  15

struct pledfcn {
    short plcode;   /* LEGEND */
    short plsize;   /* Sizeof packet */
};

Description
-----------
AutoCAD calls the driver with plcode in structure pledfcn set to LEGEND.
AutoCAD only defines linetype 0 to be a solid line. Your driver can define
other linetypes.

This is a request for your driver to return to AutoCAD, via repeated
mprintf() calls, a display of the defined line types.

LEGEND can also display other driver-specific data such as a table of
allowed pen speeds. For an example of this, see the ADI driver plphip.c.



10.8.14 ECHGCONF
==================

Purpose
-------
This packet is sent if the user has decided to change the current plot
configuration. At ESHOW time your driver should have displayed device-
specific details. Now the user wants to change something. Your driver
should ask its questions now, before AutoCAD begins asking its generic
plotting questions.

Limitations
-----------
Must be sent only to pre-ADI 4.2 drivers, at XQT configuration time, if the
user has decided to modify the current plot configuration.

AutoCAD fills in all members of this packet. The ADI driver can modify any
member of this packet except plsize.

History
-------
Added in ADI 4.1 for release 11. Replaced by ECHGCONF_42 in AutoCAD Release
12 and ADI 4.2.

Declaration
-----------
#define ECHGCONF  32

struct plebipkt {
    short plcode;          /* ECHGCONF */
    short plsize;          /* sizeof packet */
    short version;         /* ADI version number */
    real plxmax, plymax;   /* Max plot dimensions */
    real plx, ply;         /* Plot dimensions */
    real plxinc, plyinc;   /* X and Y plotter increments */
    real pllwid;           /* Line width (inches) */
    short plnpens;         /* Number of pens */
    short plspdmax;        /* Max pen speed */
    short plltmax;         /* Max # of hardware line types */
    short options;         /* Option bits */
};

Description
-----------
AutoCAD calls the driver with member plcode in the structure plebipkt set
to ECHGCONF during execution-time plotter configuration, when the user has
answered Yes to the question

Do you want to change anything?

If your driver changes anything in this packet, you must return UPCFGREC in
plcode to tell AutoCAD to record the changes.

The members that might be changed are: plxmax, plymax, plx, ply, plxinc,
plyinc, pllwid, plnpens, plspdmax, and plltmax.

If your driver detects a condition where you want the plot terminated, you
should return BAD in member plcode.



10.8.15 ECHGCONF_42
=====================

Purpose
-------
This packet is sent if the user has decided to change the current plot
configuration. It contains the AutoCAD complete generic plot configuration
record. This same structure was sent before at configuration time in
CPREGENERIC and GENERIC_42, earlier in execution-time configuration in
EPRECONF_42, and is sent once more in GENERIC_42.

Limitations
-----------
Must be sent to ADI 4.2 and later drivers at XQT configuration time if the
user has decided to change the current plot configuration.

In AutoCAD Release 12, when the plot dialogue is enabled, this is sent when
the user selects "Change Device Requirements..." in the Device and Default
Selection dialogue box.

AutoCAD fills in all members of this packet. The ADI driver can modify any
member of this packet except plsize.

History
-------
Introduced in release 12 and ADI 4.2. Replaces ECHGCONF.

Declaration
-----------
#define ECHGCONF_42         46
#define MAXUSR              5

struct plbxpl42cfg {
    short plcode;                           /* CPREGENERIC */
    short plsize;                         /* Sizeof packet */
    char pl_units;          /* 0 = inches, 1 = millimeters */
    long pl_specs;          /* ADI 4.2 specification flags */
    real pl_x, pl_y;                   /* Plot dimensions. */
    real pl_xmax, pl_ymax;          /* Max plot dimensions */
    real pl_xinc, pl_yinc;   /* X and Y plotter increments */
    real pl_orgx, pl_orgy;                 /* Plot origin. */
    char pl_szlab[9];            /* Standard size mnemonic */
    real pl_lwid;                   /* Line width (inches) */
    real pl_sclpu, pl_scldu;                      /* Scale */
    char pl_what;                         /* Viewport type */
    union {
    char pl_vname[31+1];  /* View name (if pl_what == 'V') */
        real pl_w[4];               /* 'UV' Window corners */
    } pl_vw;
    char pl_optlv;                  /* Optimization level. */
    char pl_maxoptlv;               /* Optimization level. */
    short pl_dev1,     /* Cells reserved for device driver */
        pl_dev2;
    real  pl_usrx[MAXUSR],      /* User-defined plot sizes */
        pl_usry[MAXUSR];
    real  lp_xmax;                  /* longplot paper size */
    real  lp_xinc;                  /* longplot X axis inc */
    real  lp_yinc;                  /* longplot Y axis inc */
    real  lp_reduction;       /* longplot reduction factor */
    char  pltext[10];    /* Default plot-to-file extension */
};
#define PLBXPL42CFGSIZE (sizeof(struct plbxpl42cfg))

Description
-----------
At ESHOW time your driver should have displayed device-specific details.
Now the user wants to change something. Your driver should ask its
questions now, before AutoCAD begins asking its generic plotting questions.

In AutoCAD versions prior to release 12 and in release 12, if CMDDIA is set
to 0, disabling the plot dialogue box, this packet is sent if the user
answers Yes to the "Do you want to change anything?" question displayed at
ESHOW time.

In AutoCAD Release 12, when the plot dialogue is enabled, this is sent when
the user selects "Change Device Requirements..." in the Device and Default
Selection dialogue box.

You can change any of the values in the packet listed above, but do so with
caution, based on user input or some other good reason.

The sample Epson 24-pin printer plotter driver (PLEP) shows an example of
using of this packet.



10.8.16 PMGEN
===============

Purpose
-------
Instructs the ADI driver to load the Windows printer driver.

Limitations
-----------
PMGEN is a plotter packet and can be sent to DEV_SYSPR drivers during
execution time. It is used only on OS/2 and Windows.

AutoCAD fills in all members of this packet. The ADI driver treats this as
a read-only packet.

History
-------
PMGEN was introduced in OS/2 ADI 4.0 and added to ADI 4.1 for Windows ADI.

Declaration
-----------
#define PMGEN 16

struct pledpkt {
    short plcode;                          /* Command code */
    short plsize;                         /* Sizeof packet */
    unsigned short x, y;     /* Argument or x and y values */
};

Description
-----------
AutoCAD calls a system printer driver with member plcode in structure
pledpkt set to PMGEN and member x set to the state of the printer selection
radio button from the AutoCAD Environment Settings dialogue box.

If x is set to 1, the user has selected the Use Control Panel Configuration
radio button from the AutoCAD Environment Settings Dialogue box. Otherwise
X is set to 0. The sample system printer driver uses this value to
determine which Windows printer driver to load.

Upon receipt of this packet, the driver should load the appropriate Windows
printer driver and set up a device context for the printer.



10.8.17 PMFILE
================

Purpose
-------
Indicates that the plot should be sent to a disk file.

Limitations
-----------
PMFILE is a plotter packet and can be sent to DEV_SYSPR drivers during
execution time. It is used only on OS/2 and Windows.

AutoCAD fills in all members of this packet. The ADI driver treats this as
a read-only packet.

History
-------
PMFILE was introduced in OS/2 ADI 4.0 and added to ADI 4.1 for Windows ADI.

Declaration
-----------
#define PMFILE 17

struct pledfile {
    short plcode;                          /* Command code */
    short plsize;                         /* Sizeof packet */
    char tofile;            /* Plot going to port or file? */
    char fname[MAXFNAME];                      /* Filename */
};

Description
-----------
If the user has configured a system printer driver, this packet is sent at
execution initialization time. A nonzero value for the member tofile
indicates that the plot should be sent to a disk file. Drivers for hardware
plotters do not see this packet.



10.8.18 PMDEVMODE
===================

Purpose
-------
Indicates that the user wants to change the Windows printer driver print
settings.

Limitations
-----------
PMDEVMODE is a plotter packet and can be sent to a plotter driver at
execution time; however, it is intended for DEV_SYSPR drivers only. It is
used only on OS/2 and Windows.

AutoCAD fills in all members of this packet. The ADI driver treats this as
a read-only packet.

History
-------
PMDEVMODE was introduced in OS/2 ADI 4.0 and added to ADI 4.1 for Windows.

Declaration
-----------
#define PMDEVMODE 18

struct pledpkt {
    short plcode;                          /* Command code */
    short plsize;                         /* Sizeof packet */
    unsigned short x, y;     /* Argument or x and y values */
};

Description
-----------
AutoCAD calls a system printer driver with member plcode in structure
pledpkt set to PMDEVMODE and member x set to the state of the printer
selection radio button from the AutoCAD Environment Settings dialogue box.

If x is set to 1, the user has selected the Use Control Panel Configuration
radio button from the AutoCAD Environment Settings dialogue box. Otherwise
x is set to 0. The sample system printer driver uses this value to
determine which Windows printer driver to load.

Upon receipt of this packet, the ADI driver should call the printer driver
ExtDeviceMode() or DeviceMode() functions to let the user change the print
driver settings.



10.8.19 GENERIC
=================

Purpose
-------
This lets the driver know what the application learned from the user during
generic plot configuration, and lets the driver modify the results of the
dialogue.

Limitations
-----------
This packet can be sent only to ADI 4.1 and earlier drivers. It must be
sent after generic execution-time configuration questions have been
answered by the user, and your application must fill in the packet with the
results of this dialogue. Your application should update its configuration
record with the contents of this packet after the ADI driver has returned
it, unless the driver returned ERR in plcode, in which case the plot should
be terminated.

AutoCAD fills in all members of this packet. The ADI driver can modify any
member of this packet except plsize.

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD 386 Release 10; modified in ADI 4.1
by the addition of member pl_newspec, and replaced by GENERIC_42 in ADI 4.2
and release 12.

Declaration
-----------
#define GENERIC  13

struct plbxplotcfg {
    short plcode;                /* GENERIC */
    short plsize;                /* Size of packet */
    char                         /* Flags: */
        pl_units,                /* 0=inches, 1=millimeters*/
        pl_specs;                /* ADI 4.0 spec flags */
    real pl_x, pl_y;             /* Plot dimensions */
    real pl_xmax, pl_ymax;       /* Max plot dimensions */
    real pl_xinc, pl_yinc;       /* X,Y plotter increments */
    real pl_orgx, pl_orgy;       /* Plot origin. */
    char pl_szlab[5];            /* Standard size mnemonic */
    real pl_lwid;                /* Line width (inches) */
    real pl_sclpu, pl_scldu;     /* Scale */
    char pl_what;                /* Viewport type */
        union {
            char pl_vname[31+1]; /* View name */
            real pl_w[4];        /* 'UV' Window corners */
        } pl_vw;
    char pl_optlv;               /* Optimization level */
    short pl_dev1, pl_dev2;      /* Reserved for driver use*/
    short pl_newspec;            /* ADI 4.1 specs field */
};

Description
-----------
AutoCAD calls the driver with member plcode in structure plbxplotcfg set to
GENERIC. AutoCAD initializes the other members of the structure with
information obtained from the user in the AutoCAD generic plot dialogue.

This is your driver's chance to look at the data configured in the generic
plot dialogue with the user. You can make changes in the data, if
necessary, and AutoCAD updates its configuration record. It is not
advisable to make major changes here without notifying or asking the user.

If your driver detects a condition where you want the plot terminated, you
should return ERR in member plcode.

After the GENERIC packet is sent to the driver, AutoCAD again sends the
SPECIFIC packet, for information only (not to be modified). The user might
have changed some items in this packet during execution-time configuration
(e.g., color, line type, or speed mappings).



10.8.20 GENERIC_42
====================

Purpose
-------
This tells the driver what the application learned from the user during
generic plot configuration and lets the driver modify the results of the
dialogue. This same structure was sent before at configuration time in
CPREGENERIC and GENERIC_42 and earlier in execution-time configuration in
EPRECONF_42 and EPOSTCONF_42.

Limitations
-----------
This packet can be sent only to ADI 4.2 and later drivers. It must be sent
after generic execution-time configuration questions have been answered by
the user and your application must fill in the packet with the results of
this dialogue. Your application should update its configuration record with
the contents of this packet after the ADI driver has returned it, unless
the driver returned BAD in plcode, in which case the plot should be
terminated.

AutoCAD fills in all members of this packet. The ADI driver can modify any
member of this packet except plsize.

History
-------
Introduced in release 12 and ADI 4.2.

Declaration
-----------
#define GENERIC_42     47
#define MAXUSR 5

struct plbxpl42cfg {
    short plcode;                 /* CPREGENERIC */
    short plsize;                 /* Sizeof packet */
    char pl_units;         /* 0 = inches, 1 = millimeters */
    long pl_specs;          /* ADI 4.2 specification flags */
    real pl_x, pl_y;              /* Plot dimensions. */
    real pl_xmax, pl_ymax;        /* Max plot dimensions */
    real pl_xinc, pl_yinc;  /* X and Y plotter increments */
    real pl_orgx, pl_orgy;        /* Plot origin. */
    char pl_szlab[9];     /* Standard size mnemonic */
    real pl_lwid;                 /* Line width (inches) */
    real pl_sclpu, pl_scldu;      /* Scale */
    char pl_what;                 /* Viewport type */
    union {
        char pl_vname[31+1];      /* View name
                                 (if pl_what == 'V') */
        real pl_w[4];             /* 'UV' Window corners */
    } pl_vw;
    char pl_optlv;                /* Optimization level. */
    char pl_maxoptlv;             /* Optimization level. */
    short pl_dev1,    /* Cells reserved for device driver */
        pl_dev2;
    real  pl_usrx[MAXUSR], /* User-defined plot sizes */
        pl_usry[MAXUSR];
    real  lp_xmax;                /* longplot paper size */
    real  lp_xinc;                /* longplot X axis inc */
    real  lp_yinc;                /* longplot Y axis inc */
    real  lp_reduction;     /* longplot reduction factor */
    char  pltext[10];  /* Default plot-to-file extension */
};

#define PLBXPL42CFGSIZE (sizeof(struct plbxpl42cfg))

Description
-----------
AutoCAD calls the driver with member plcode in structure plbxpl42cfg set to
GENERIC_42. AutoCAD initializes the other members of the structure with
information obtained from the user in the AutoCAD generic plot dialogue
box.

This lets your driver look at the data configured in the generic plot
dialogue with the user. You can make changes in the data, if necessary, and
AutoCAD updates its configuration record. It is not advisable to make major
changes here without notifying or asking the user.

If your driver detects a condition where you want the plot terminated, you
should return BAD in member plcode.

After the GENERIC_42 packet is sent to the driver, AutoCAD again sends the
SPECIFICPENS, SPECIFICSPEED, SPECIFICLTYPE, SPECIFICWIDS, and SPECIFIC_42
packets, for information only (not to be modified). The user might have
changed some items in these packets during execution-time configuration
(e.g., color, line type, pen width, or speed mappings).



10.8.21 PLOTSIZE
==================

Purpose
-------
Informs the driver of the maximum X and Y coordinates used in the following
plot.

Limitations
-----------
Can be sent only during XQT configuration time. Must be sent just before
EPOSTCONF.

AutoCAD fills in all members of this packet. The ADI driver treats this as
a read-only packet.

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10.

Declaration
-----------
#define PLOTSIZE 10

struct pledpkt {
    short plcode;        /* PLOTSIZE */
    short plsize;        /* Size of packet */
    unsigned short x, y; /* Argument or x and y values */
};

Description
-----------
The PLOTSIZE code is sent before the beginning of the plot. The x and y
members contain the largest horizontal and vertical coordinates,
respectively, that AutoCAD uses in generating the plot. These coordinates
are specified as unsigned short numbers in the inclusive range from 0 to
65535. Values for X and Y coordinates in subsequent MOVE and DRAW commands
vary from 0 to the X and Y maximums returned in this packet.



10.8.22 EPOSTCONF
===================

Purpose
-------
Notifies the driver just before vectors are sent by AutoCAD.

Limitations
-----------
This must be the last execution-time configuration packet sent to an ADI
driver.

AutoCAD fills in all members of this packet. The ADI driver can modify
member plcode if a serious error is detected.

History
-------
EPOSTCONF was added in OS/2 ADI 4.0 for release 10.

Declaration
-----------
#define EPOSTCONF 30

struct pledpkt {
    short plcode;        /* EPOSTCONF */
    short plsize;        /* Size of packet */
    unsigned short x, y; /* Argument or x and y values */
};

Description
-----------
The EPOSTCONF code is sent just before the first vectors begin flowing to
the plotter, after execution-time configuration is completed. Any last
minute preparations for vectors should be completed on receipt of this
packet. This packet has no arguments.

If a pre-ADI 4.2 driver detects a condition where it wants the plot
terminated, it should return ERR in plcode. ADI 4.2 and later drivers
return BAD in plcode to terminate the plot.

This is when the hardware or file is initialized and made ready to receive
vectors or other plotting packets described below. See any of the sample
drivers provided in the ADI kit.

Execution-time Plotting Packets
-------------------------------
Now, plot time configuration has been completed. During the rest of
execution time, AutoCAD repeatedly calls the plotter driver with a packet
that contains a command code in one of its fields: MOVE, DRAW, PENRAISE,
NEWPEN, NEWSPEED, NEWLTYPE, ABORTPLOT, and ENDPLOT.

Packet Command Codes
--------------------
Most execution packet codes are sent by AutoCAD using structure pledpkt,
declared as follows:

struct pledpkt { /* Execution commands */
    short plcode; /* Command code */
    short plsize; /* Size of packet */
    unsigned short x, y; /* Argument or x and y values */
};

The command codes, summarized in the following table, tell the driver what
function to perform. The codes are defined in the plp.h header file.

Table 10-24. Execution-time packet command codes

Code            pledpkt.x            pledpkt.y

MOVE            X coordinate         Y coordinate

DRAW            X coordinate         Y coordinate

PENRAISE        (none)    (none)

NEWPEN          Pen number           (none)

NEWSPEED        Speed code           (none)

NEWLTYPE        Line type code       (none)

ABORTPLOT       (none)    (none)

ENDPLOT         (none)    (none)

Two new packets were added for ADI4.2 that don't use the above structure.
These packets are NEWPENWID and PLFILL. Their structures are described
later.



10.8.23 ABORTPLOT
===================

Purpose
-------
Abnormal plot termination by user.

Limitations
-----------
This packet should be sent only if your application wants to abort the
plot, and it must always be followed by ENDPLOT.

AutoCAD fills in all members of this packet. The ADI driver treats this as
a read-only packet.

History
-------
Introduced in OS/2 ADI 4.0 and release 10.

Declaration
-----------
#define ABORTPLOT  9

struct pledpkt {
    short plcode;        /* ABORTPLOT */
    short plsize;        /* size of packet */
    unsigned short x, y; /* Argument or x and y values */
};

Description
-----------
The ABORTPLOT is sent only when the plot has been terminated by the user by
pressing the interrupt key, normally <Ctrl-C>. An ADI driver receives the
code to indicate that abnormal termination action should be taken (e.g.,
flush the hardware buffer).

However, the driver should not exit at this point. The ABORTPLOT command
code is followed by an ENDPLOT command code, at which time the driver
should perform the usual end- of-plot functions, such as putting the pen
back and exiting.



10.8.24 DRAW
==============

Purpose
-------
Moves to coordinates with pen down.

Limitations
-----------
Can be sent only during execution plot time.

AutoCAD fills in all members of this packet. The ADI driver can modify
plcode if it detects a serious error.

History
-------
Introduced in OS/2 ADI 4.0 for release 10.

Declaration
-----------
#define DRAW  4

struct pledpkt {
    short plcode;        /* DRAW */
    short plsize;        /* Size of packet */
    unsigned short x, y; /* Argument or x and y values */
};

Description
-----------
The DRAW code is followed by two arguments, specifying the absolute
coordinates to which the pen should be moved with the pen down. The
coordinates X and Y are specified as unsigned short numbers in the
inclusive range of 0 to 65535.

If an ADI 4.2 driver detects a condition that requires termination of the
plot, it can return BAD in plcode.



10.8.25 ENDPLOT
=================

Purpose
-------
Signals the driver that a plot has completed.

Limitations
-----------
Can be sent only as the last packet at configuration time for UNIX plotters
or as the last packet at execution time for any platform.

AutoCAD fills in all members of this packet. The ADI driver treats this as
a read-only packet.

History
-------
Introduced in OS/2 ADI 4.0 for release 10.

Declaration
-----------
#define ENDPLOT  2

struct pledpkt {
    short plcode;        /* ENDPLOT */
    short plsize;        /* Size of packet */
    unsigned short x, y; /* Argument or x and y values */
};

Description
-----------
The ENDPLOT code is output at the end of a plot. It has no arguments. When
this code is received, the driver should perform its cleanup, call
dispterm(), and return to AutoCAD.



10.8.26 MOVE
==============

Purpose
-------
Moves to coordinates with the pen up.

Limitations
-----------
Can be sent only during execution plot time.

AutoCAD fills in all members of this packet. The ADI driver can modify
plcode if it detects a serious error.

History
-------
Introduced in OS/2 ADI 4.0 for release 10.

Declaration
-----------
#define MOVE  3

struct pledpkt {
    short plcode;        /* MOVE */
    short plsize;        /* Size of packet */
    unsigned short x, y; /* Argument or x and y values */
};

Description
-----------
The MOVE code is followed by two arguments, specifying the absolute
coordinates to which the pen should be moved with the pen up. The
coordinates X and Y are specified as unsigned short numbers in the
inclusive range of 0 to 65535.

If and ADI 4.2 driver detects a condition that requires termination of the
plot, it can return BAD in plcode.



10.8.27 NEWLTYPE
==================

Purpose
-------
Selects a plotter line font.

Limitations
-----------
Can be sent only during execution plot time. Should be sent only to drivers
that set MULTLINE in DETAIL.options.

AutoCAD fills in all members of this packet. The ADI driver can modify
plcode if it detects a serious error.

History
-------
Introduced in OS/2 ADI 4.0 for release 10.

Declaration
-----------
#define NEWLTYPE  7

struct pledpkt {
    short plcode;        /* NEWLTYPE */
    short plsize;        /* Size of packet */
    unsigned short x, y; /* Argument or x and y values */
};

Description
-----------
The NEWLTYPE code selects a plotter line font. The x field contains the
value, which selects the line font. It is a universal convention within
AutoCAD that zero selects a continuous (i.e., solid) line. The meaning of
the other line fonts is up to the driver.

If an ADI 4.2 driver detects a condition that requires termination of the
plot, it can return BAD in plcode.



10.8.28 NEWPEN
================

Purpose
-------
Selects a pen.

Limitations
-----------
Can be sent only during execution plot time. Should be sent only to drivers
that set MULTPEN in DETAIL.options.

AutoCAD fills in all members of this packet. The ADI driver can modify
plcode if it detects a serious error.

History
-------
Introduced in OS/2 ADI 4.0 for release 10.

Declaration
-----------
#define NEWPEN  5

struct pledpkt {
    short plcode;        /* NEWPEN */
    short plsize;        /* Size of packet */
    unsigned short x, y; /* Argument or x and y values */
};

Description
-----------
The NEWPEN code is the command that selects a pen. The x member contains
the value that specifies the pen number.

If an ADI 4.2 driver detects a condition that requires termination of the
plot, it can return BAD in plcode.



10.8.29 NEWSPEED
==================

Purpose
-------
Selects drawing speed.

Limitations
-----------
Can be sent only during execution plot time. Should be sent only to drivers
that set VARSPEED in DETAIL.options.

AutoCAD fills in all members of this packet. The ADI driver can modify
plcode if it detects a serious error.

History
-------
Introduced in OS/2 ADI 4.0 for release 10.

Declaration
-----------
#define NEWSPEED  6

struct pledpkt {
    short plcode;        /* NEWSPEED */
    short plsize;        /* Size of packet */
    unsigned short x, y; /* Argument or x and y values */
};

Description
-----------
The NEWSPEED code chooses a drawing speed for a variable speed plotter. The
x member contains the value that selects the speed.

The speed argument is range checked and does not exceed the maximum speed
configured, but is not checked otherwise. For a plotter with discrete
speeds, a driver processing this command that encounters a speed number the
plotter cannot handle should use the next slower speed.

If an ADI 4.2 driver detects a condition that requires termination of the
plot, it can return BAD in plcode.



10.8.30 NEWPENWID
===================

Purpose
-------
Enables multiple widths to be sent to plotters that have real pens of
different widths, or raster devices that can generate various size lines.

Limitations
-----------
Is only used by plotters that have set the PENWIDS bit in the drivers
option bits during the DETAIL packet.

AutoCAD fills in all members of this packet. The ADI driver can modify
plcode if it detects a serious error.

History
-------
Introduced in release 12 and ADI 4.2.

Declaration
-----------
#define NEWPENWID  41

struct plxpenwid {
    short plcode;              /* NEWPENWID */
    short plsize;
    real  width;               /* A real or double */
};

#define PLXWIDSIZE (sizeof(struct plxpenwid))

Description
-----------
NEWPENWID is followed by one argument that specifies the width of the lines
or vectors to follow. It is ignored or not sent for drivers that cannot
produce various line weights.

If an ADI 4.2 driver detects a condition that requires termination of the
plot, it can return BAD in plcode.



10.8.31 PENRAISE
==================

Purpose
-------
Lets the plotter prepare for a manual pen change.

Limitations
-----------
Can be sent only during execution plot time.

AutoCAD fills in all members of this packet. The ADI driver can modify
plcode if it detects a serious error.

History
-------
Introduced in OS/2 ADI 4.0 for AutoCAD Release 10.

Declaration
-----------
#define PENRAISE  8

struct pledpkt {
    short plcode;        /* PENRAISE */
    short plsize;        /* Size of packet */
    unsigned short x, y; /* Argument or x and y values */
};

Description
-----------
The PENRAISE code is generated before every pen change at the start of a
pass over the vector list. It lets the plotter prepare for a possible
manual pen change (for example, raising the pen and moving it to the middle
of the carriage). It is not the actual change pen command, which is the
NEWPEN command code.

A PENRAISE code can be sent when AutoCAD expects a delay for extended
computation before sending more vectors. In such cases, the PENRAISE
command is intended to prevent ink from pooling under the pen.

A PENRAISE command is always generated at the start of a plot.

If an ADI 4.2 driver detects a condition that requires termination of the
plot, it can return BAD in plcode.


10.8.32 PLFILL
================

Purpose
-------
If devices do polygon fills, AutoCAD lets them. Instead of having AutoCAD
fill in every filled area with individual lines, the driver is sent the
vertices that make up the area and color. The driver then fills the area.

Limitations
-----------
Can be sent only during execution plot time to ADI 4.2 and later drivers
that indicate support for smart polygon fills by setting SFILLS in
DETAIL.options.

AutoCAD fills in all members of this packet. The ADI driver can modify
plcode if it detects a serious error.

History
-------
Introduced in ADI 4.2 for release 12.

Declaration
-----------
#define PLFILL  33

struct plpkfill {        /* ADI42 will support smart fills */
    short plcode;                                /* PLFILL */
    short plsize;                            /* PLFILLSIZE */
    short pfunc;               /* Function code, use PLFILL*/
    short pcolour;                                /* Color */
    short pdrawm;                         /* Drawing modes */
    short pnvert;                    /* Number of vertices */
    unsigned short pvert[12][2];           /* Vertex table */
};

Description
-----------
The PLFILL code and its associated packet are sent only if the driver has
indicated during configuration that it can do so by setting the SFILLS bit
in DETAIL.options. Otherwise, areas are filled the old fashioned way, with
individual vectors.

The color of the polygon is sent in member colour. If the polygon is to be
highlighted, DR_HILITE (0x1) is set in member pdrawm.

The polygon to be drawn is made up of pnvert vertices, defined in a two-
dimensional table, pvert. This table contains 12 columns representing up to
12 vertices, and two rows representing X and Y coordinates. Valid column
subscript values must be within the range 0 to (pnvert - 1). Valid row
subscripts are 0 for X coordinates, and 1 for Y coordinates. Although 12
vertices can be represented, AutoCAD never passes a polygon with more than
10 vertices to PLFILL.

For an example of a driver doing smart fills, see the postscript driver
(PLPPOST.C) or the Hewlett Packard HPGL2 driver (PLPHPGL2.C).

OS/2 and Windows System Printer
-------------------------------
A user can choose to send plots to the system printer. If you have written
a system printer driver for your device, no further programming is
required.

Our generic system printer driver sends its output to the system which in
turn talks to your device-specific system printer driver.



10.8.33 PMFILE
================

Purpose
-------
Informs a system printer driver of the intended action.

Limitations
-----------
Should be sent only to a generic system printer driver (not device-specific
drivers).

AutoCAD fills in all members of this packet. The ADI driver can modify
plcode if it detects a serious error.

History
-------
Introduced in OS/2 ADI 4.0, also used by Windows ADI 4.1.

Declaration
-----------
#define PMFILE 17

struct pledfile {
    short plcode;           /* PMFILE */
    short plsize;           /* sizeof packet */
    char tofile;            /* Plot going to port or file? */
    char fname[MAXFNAME];   /* Filename */
};

Description
-----------
If the user has configured the PM system plotter, this packet is sent at
execution initialization time. A nonzero value for the member tofile
indicates that the plot should be sent to a disk file. Drivers for hardware
plotters do not see this packet.

Generic Plot File Output Formats
--------------------------------
In AutoCAD Release 12, an ADI driver, plpfile, provide the means to get
plotter output to a file in one of five different device-independent
formats. These are ASCII generic, binary generic, AutoCAD DXB, Binary
Printer Plotter file, and CAD/CAMERA files. The file interface level of
most of these formats has been incremented from 1 to 2 in release 12 due to
the change from 16- to 256-color plotting.

To send device-specific plotter codes to a file, the user still has to
select a specific hardware plotter and then answer this question
affirmatively:

Write the plot to a file? <N>

If your driver has used plsend(), iow() or ppsend(), the plotter output
from your driver is redirected by AutoCAD to the file the user selects.

Generic ASCII Format
--------------------
If the output format is a generic ASCII file, each plot command appears on
a new line, starting in the first text column. All command codes and
arguments appear as base ten numbers, separated by commas. Type A codes
appear by themselves. Type B codes consist of the command code followed by
the argument. Type C codes consist of the command code, followed by the X
and Y coordinates, comma delimited.

All numbers appearing in a plot file are unsigned. Arguments to type B
codes range from 0 to 255, and arguments to type C codes range from 0 to
65535.

The following actual plot file was generated by plotting a square. The
annotations did not appear in the original file, but were added to explain
the commands.

1,2            Begin plot, file level
2 8            Raise pen (start of pass)
5,1            Select new pen 1
7,0            Select line type 0 (solid)
6,1            Select speed 1
3,0,6953       Move to 0, 6953 - pen up
4,6954,6953    Draw to 6954, 6953 - top of square
4,6954,0       Draw to 6954, 0 - right side
4,0,0          Draw to 0,0 - bottom
4,0,6953       Draw to 0, 6953 - left side
2              End of plot
Generic Binary Format
---------------------
In a generic binary file, the codes and arguments appear precisely as they
do in an ASCII file, but are stored as binary numbers. Type A codes are
written as single bytes. Type B codes consist of a single-byte code,
followed by a one-byte argument. Type C codes are written as a single-byte
code, followed by two 16-bit arguments representing the X and Y
coordinates. Each 16-bit argument is written least significant byte first,
most significant byte last, in the standard 8086 representation.

The following is a hexadecimal dump of a binary file generated by the same
drawing that created the ASCII file above. Spacing has been added to the
dump to aid readability.

01 02
08
05 01
07 00
06 01
03 00 00 29 1B
04 2A 1B 29 1B
04 2A 1B 00 00
04 00 00 00 00
04 00 00 29 1B
02

See the AutoCAD Reference Manual for information on the AutoCAD DXB file
format.

OS/2 File Output
----------------
Under OS/2, rather than have the user choose the file format after
selecting ADI plotter from the menu, the file output selections are
included in the list with all the other hardware plotters. Since all
plotter drivers under OS/2 are ADI, it is redundant to have an ADI plotter
in the selection list.

The three file output drivers are implemented as a single DLL, each with a
separate alias identification to differentiate them. The plbxinit packet is
used to determine if the selected driver is a file output driver. AutoCAD
calls the driver with member plcode set to CINIT and member version set to
the current version number. The file output driver should set status to
either ASCIIFILE, BINARYFILE, or DXBFILE, indicating to AutoCAD the kind of
file output driver. The file output driver should also save the alias
passed to it in the packet.

To send device-specific plotter codes to a file, the user still has to
select a specific hardware plotter and then answer the question, "Write the
plot to a file? <N>" affirmatively.



                    |================================|
                    |                                |
                    |           Appendix A           |
                    |                                |
                    |       Color Assignments        |
                    |                                |
                    |================================|



A.1 Color Assignments
=====================

AutoCAD uses a 256-color fixed palette for display operations. AutoSketch
uses a 128-color palette (colors 0-127).

Whenever a color value is passed from an Autodesk software product to an
ADI graphics display, rendering, or plotter driver, the following default
color mapping should be used:

Table A-1. Color values passed to ADI driver

Value  Definition
-------------------
0       Background (erase)
1       Red
2       Yellow
3       Green
4       Cyan
5       Blue
6       Magenta
7       White (foreground)
8-15    Usually intensified versions of above (for 16 color devices)
8-9     User-configurable for 256-color devices
10-15   Shades of red for 256-color devices

If your display device does not support at least 256 colors, you should
still honor all 256 color numbers and display the closest color to the
requested color.

Since a number of different display palettes have been used with earlier
releases of AutoCAD, with different palettes in the AutoCAD internal VGA
and sample ADI drivers, it is desirable to allow the user to do some color
configuration so that new drivers can still display old drawings reasonably
well.

The table below provides some common color AutoCAD mappings. The new 16-
color ADI and Std 256 color maps are the default maps used.

Table A-2. Common color AutoCAD maps

Source              Colors 8-15                 Colors 16 - 255
----------------------------------------------------------------
Old internal VGA   Dim versions of colors 1-7    All gray or all white
Old 16-color ADI   Shades of red to match chroma Best chroma match
New 16-color ADI   Dim versions of colors 1-7    Best chroma match
Non-std 256 color  Dim versions of colors 1-7    Best chroma match
Std 256 color      Shades of red to match chroma Best chroma match

The phrase "best chroma match" in the table above means that the palette
should follow the rules defined in the following tables.

A.1.1 256-Color Devices
=======================

For devices that support 256 colors, the hue resulting from a color value
in the range 10-249 is determined by the first two digits, and the
saturation and value from the last digit, as follows:

Table A-3. Color hue and saturation values

Value  Definition
10  Red
50  Yellow
90  Green
130  Cyan
170  Blue
210  Magenta

Between each of these are three intermediate hues. For example, the table
below shows the hues between red and yellow:

Table A-4. Intermediate color hues

Value  Definition
10  Red
20  Reddish orange (intermediate hue)
30  Orange (intermediate hue)
40  Yellowish orange (intermediate hue)
50  Yellow

To each hue number, 0, 2, 4, 6, or 8 can be added to give a different
value, or brightness, with 0 the brightest and 8 the dimmest.

Finally, 1 can be added to produce a half-saturated, or pastel, color. For
example, color 18 is the dimmest red and 10 the brightest, 19 is the
dimmest pink and 11 the brightest. Colors 8 and 9 are typically various
grays or sometimes black.

The colors from 250-255 should be shades of gray, with 255 light gray and
250 dark gray.

If a display driver is requested to draw in a color that matches the
background color, white should be used (unless the background color is
white, in which case black should be used).

Included in the ADI ToolKit is the file chroma.dwg, an AutoCAD drawing that
shows all colors (1-255). This file is in the \dstestr11 directory on the
ADI distribution disk. You should use this sample drawing for debugging
your device driver.

A.1.2 Generating RGB Values
===========================

Following is a code fragment that can be used to generate RGB values from
AutoCAD color numbers:

#define  BLACK     0
#define  RED       1
#define  YELLOW    2
#define  GREEN     3
#define  CYAN      4
#define  BLUE      5
#define  MAGENTA   6
#define  WHITE     7
#define  SAT     1.0
/* Takes an AutoCAD color number in hsv and returns red,
   green, and blue intensities in rgb in the range 0.0
   to 1.0 */

static void hsv_to_fprgb(hsv, rgb)
short  hsv;
R_G_B *rgb;
{
    static double brightfac[5] = {   /* Brightness levels */
         1.0, 0.65, 0.5, 0.3, 0.15
    }, halfsat = .5;                /* Halfway saturation */
    int ih, vs;
    double h, s, f;
    /*ASSERT(hsv > 0 || hsv < 256); */
    switch (hsv) {
    case BLACK:
        rgb->green = 0.0;
        rgb->value = 0.0;
        rgb->uniq = 0;
        break;
    case RED:
        rgb->red   = SAT;
        rgb->green = 0.0;
        rgb->blue  = 0.0;
        rgb->value = 1.0;
        rgb->uniq = 1;
        break;
    case YELLOW:
        rgb->red   = SAT;
        rgb->green = SAT;
        rgb->blue  = 0.0;
        rgb->value = 1.0;
        rgb->uniq = 5;
        break;
    case GREEN:
        rgb->red   = 0.0;
        rgb->green = SAT;
        rgb->blue  = 0.0;
        rgb->value = 1.0;
        rgb->uniq = 9;
        break;
    case CYAN:
        rgb->red   = 0.0;
        rgb->green = SAT;
        rgb->blue  = SAT;
        rgb->value = 1.0;
        rgb->uniq = 13;
        break;
    case BLUE:
        rgb->red   = 0.0;
        rgb->green = 0.0;
        rgb->blue  = SAT;
        rgb->value = 1.0;
        rgb->uniq = 17;
        break;
    case MAGENTA:
        rgb->red   = SAT;
        rgb->green = 0.0;
        rgb->blue  = SAT;
        rgb->value = 1.0;
        rgb->uniq = 21;
        break;
    case WHITE:
        case 8:
        case 9:
        rgb->red   = SAT;
        rgb->green = SAT;
        rgb->blue  = SAT;
        rgb->value = 1.0;
        rgb->uniq = 49;
        break;
    default:

/* The chromatic colors. The hue resulting from an AutoCAD
   color 10-249 is determined by its first two digits, and
   the saturation and value from the last digit, as follows:
   Hues:
   10 -- Red
   50 -- Yellow
   90 -- Green
   130 -- Cyan
   170 -- Blue
   210 -- Magenta

   Between each of these are three intermediate hues, for
   example, between red and yellow, we have this:
   20 -- Reddish orange
   30 -- Orange
   40 -- Yellowish orange
   To each hue number, 0, 2, 4, 6, or 8 can be added to give
   a different "value," or brightness, with 0 the brightest
   and 8 the weakest. Finally, 1 can be added to produce a
   "half-saturated," or pastel, color. For example, color 18
   is the dimmest red and 10 the brightest. 19 is the dimmest
   pink and 11 the brightest. */

        if (hsv > 9 && hsv < 250) {
            /*  Apply the algorithm from Foley & Van Dam to
                turn HSV into RGB values */
            ih = (hsv - 10) / 10;    /* Integer hue value */
            if (ih >= 24)               /* Range is 0-23 */
                ih -= 24;
            vs = hsv % 10;  /* Encoded value & saturation */
            if (vs & 1)
               rgb->uniq = ih + 25;
            else
               rgb->uniq = ih + 1;
            h  = ih / 4.;     /* Map into range [0.0,6.0) */
            ih = (int)h;              /* The integer part */
            f  = h - ih;               /* Fractional part */
            rgb->value = brightfac[vs >> 1]; /* Value in
                                                     [0,1]*/
            s = vs & 1 ? halfsat : 1.0;     /* Saturation */
            switch (ih) {
            case 0:
                rgb->red    = 1.0;
                rgb->green = (double) (1.0 - s*(1.0-f));
                rgb->blue  = (double) (1.0 - s);
                break;
            case 1:
                rgb->red    = (double) (1.0-s*f);
                rgb->green = 1.0;
                rgb->blue  = (double) (1-s);
                break;
            case 2:
                rgb->red    = (double) (1.0-s);
                rgb->green = 1.0;
                rgb->blue  = (double) (1.0 - s*(1.0-f));
                break;
            case 3:
                rgb->red    = (double) (1.0-s);
                rgb->green = (double) (1.0-s*f);
                rgb->blue  = 1.0;
                break;
            case 4:
                rgb->red    = (double) (1.0 - s*(1.0-f));
                rgb->green = (double) (1.0-s);
                rgb->blue  = 1.0;
                break;
            case 5:
                rgb->red    = 1.0;
                rgb->green = (double) (1.0-s);
                rgb->blue  = (double) (1.0-s*f);
                break;
            }
        } else {
              /* Define some extra colors form dark gray
                 to white in the 250 to 255 slots */
              rgb->value = 0.33 + (hsv - 250)*0.134;
              rgb->red   = 1.0;
              rgb->green = 1.0;
              rgb->blue  = 1.0;
              rgb->uniq = 49;
        }
        break;  /* default */
    }
}

Note: We have used slightly different gray shades for colors 250 to 255 in
rcpvesa2 and rcpsvadi than those calculated above. These are: 18, 27, 36,
45, and 54 (out of a range from 0-63).


A.2 Logical Display Color Assignments
=====================================

The Autodesk user interface uses pull-down menus and dialogue boxes for
communication between software and user. The colors used for the various
elements of this user interface are necessarily distinct from those used
for drawing and screen displays. The concept of "logical colors" was
implemented to maintain this distinction.

A logical color is known to an Autodesk product only as a number. There is
no direct connection between a physical color and the logical color number.
It is the responsibility of the display driver to convert logical color
numbers to physical colors, and ensure that all colored elements are
visible.

For example, border colors for user interface elements (pull-down menus,
dialogue boxes, etc.) must be different from both the graphics area
background color and the background color of the element.

For monochrome display devices, all dialogue, menu, and pull-down
background colors are the same as the graphics area background color.

In addition, the foreground color of an element must differ from its
background color.

The following table summarizes logical color assignments as currently
defined in the colours.h header file included in the ADI ToolKit:

Table A-5. Logical color assignments

Mnemonic  Value  Usage
BGLCOLOR  -2  Graphics area background color
TBGLCOLOR  -3  Text area background color
TXTLCOLOR  -4  Color of text
BRDLCOLOR  -5  Color for border lines
ABGLCOLOR  -6  Alert box background color
AFGLCOLOR  -7  Alert box foreground color
ABRDLCOLOR  -8  Alert box border color
MBGLCOLOR  -9  Menu bar background color
MFGLCOLOR  -10  Menu bar foreground color
MBRDLCOLOR  -11  Menu bar border color
PBGLCOLOR  -12  Pull-down menu background color
PFGLCOLOR  -13  Pull-down menu foreground color
PBRDLCOLOR  -14  Pull-down menu border color
DBGLCOLOR  -15  Dialogue box background color
DFGLCOLOR  -16  Dialogue box foreground color
DBRDLCOLOR  -17  Dialogue box border color
LINELCOLOR  -18  Dialogue box line-drawing color
MINLCOLOR  -18  Most negative color number

AutoCAD Release 12 no longer uses the Alert Box logical colors (-6, -7, and
-8), but drivers should continue to support them for use with other
Autodesk products.

A.2.1 Recommended Modifications
===============================

The following changes to the old default logical color assignments are
recommended:

  * Change DBGLCOLOUR from YELLOW to WHITE.

  * Change LINELCOLOUR from BLUE to DARK GRAY.

Because ADS applications such as AVE Render may turn on color folding, we
recommend you restrict the AutoCAD color indices assigned to logical colors
to values less than 16. This keeps user interface widgets from being
damaged by color folding.

AutoCAD Release 12 doesn't use the Alert Box logical colors; however, ADS
applications, earlier versions of AutoCAD, and other Autodesk products do
use them. Therefore drivers should continue to support these colors.

When assigning physical colors to logical color values, keep the following
in mind:

1)        BGLCOLOR, TBGLCOLOR, TXTLCOLOR, and BRDLCOLOR describe colors
used for the corresponding areas of the display screen and should be
distinct from user interface elements.

2)        Alert boxes, dialogue boxes, the menu bar, and pull-down menus
all require three color elements: foreground, background, and border. The
border color must be different from the graphics area background color
(BGLCOLOR).

3)        LINELCOLOR must be different from DBGLCOLOR and ABGLCOLOR. If
convenient, it should also be different from DFGLCOLOR and AFGLCOLOR.

4)        Using too many colors can result in a distracting and
unattractive display. Do not hesitate to use the same color or color
combination for multiple purposes where no color conflict is likely to
arise.

5)        If the display supports only two colors (e.g., monochrome), the
entire color scheme is determined by the color assigned to BGLCOLOR. In
this case, all background colors are the same as BGLCOLOR, and all other
colors are different from BGLCOLOR. Two #defines in colours.h, DECLBGARRAY,
and the ISBGLCOLOR macro assist the driver in testing for background color.

6)        Try to detect user color configurations that will make user
interface elements invisible (e.g., identical or nearly identical
foreground and background colors) and either disallow the configuration
choice or warn the user.

A.2.2 16-Color Display Example
==============================

Sample color assignments for a 16-color display such as the IBM VGA are
shown in the following table. This table shows the colors assigned to each
physical color number (using black for the graphics background).

Table A-6. Sample color assignments

Physical Color #            Color Name

0                Black

1                Red

2                Yellow

3                Green

4                Cyan

5                Blue

6                Magenta

7                White

8                Dark gray

9                Dark red

10               Dark brown

11               Dark green

12               Dark cyan

13               Dark blue

14               Dark magenta

15               Light gray


This next table shows how these colors might be used for the logical
portions of the screen. The sample settings shown are the physical color
numbers.

Table A-7. Example of color use for logical screen portions

Logical color #  Used for        Sample settings

-2               Graphics background        0 (black)

-3               Text background            13 (dark blue)

-4               Text            7 (white)

-5               Border lines    8 (dark gray)

-6               Alert box background       7 (white)

-7               Alert box foreground       1 (red)

-8               Alert box border           8 (dark gray)

-9               Menu bar background        7 (white)

-10              Menu bar foreground        13 (dark blue)

-11              Menu bar border            8 (dark gray)

-12              Pull-down menu background  7 (white)

-13              Pull-down menu foreground  13 (dark blue)

-14              Pull-down menu border      15 (light gray)

-15              Dialogue box background    7 (white)

-16              Dialogue box foreground    0 (black)

-17              Dialogue box border        15 (light gray)

-18              Lines in dialogue boxes    8 (dark gray)


A.2.3 256-Color Display Example
===============================

Sample logical color assignments for a 256-color display are shown in the
following table. This table shows the colors assigned to each physical
color number.

Table A-8. Sample logical color assignments

Logical color #  Used for        Sample settings

-2               Graphics background        0 (black)

-3               Text background            5 (blue)

-4               Text            7 (white)

-5               Border lines    8 (dark gray)

-6               Alert box background       7 (white)

-7               Alert box foreground       1 (red)

-8               Alert box border           8 (dark gray)

-9               Menu bar background        7 (white)

-10              Menu bar foreground        5 (blue)

-11              Menu bar border            8 (dark gray)

-12              Pull-down menu background  7 (white)

-13              Pull-down menu foreground  5 (blue)

-14              Pull-down menu border      8 (dark gray)

-15              Dialogue box background    7 (white)

-16              Dialogue box foreground    0 (black)

-17              Dialogue box border        8 (dark gray)

-18              Lines in dialogue boxes    8 (dark gray)



A.3 256-Color Hardcopy Devices
==============================

AutoCAD Release 12 introduces 256-color hardcopy support. However, ADI 4.2
provides no plotter and display drivers to communicate with each other
regarding the current palette. Plotter drivers for color devices should use
our standard 256-color palette by default.

Two header files in the ADI 4.2 ToolKit present 8-bit 256-color palettes.
One file, apalette.h, is most suitable for display devices while the other,
bpalette.h, is color corrected to look better for most color hardcopy
devices. Color configuration or gamma correction for a hardcopy driver can
also be handled by a dialogue between the driver and the user.




                    |================================|
                    |                                |
                    |           Appendix B           |
                    |                                |
                    |          ADI History           |
                    |                                |
                    |================================|


B.1 ADI Historical Overview
===========================

This appendix is an overview of ADI development history. Some items
referred to are obsolete or features no longer supported. For information
about these items, see the complete ADI documentation set for the relevant
ADI version.

This overview is not exhaustive. Specific details of ADI packet or
dispatcher function development are included in the "Descriptions" sections
in the text of this book.


B.2 ADI Version 4.1 (November, 1990)
====================================

ADI 4.1 was tied to the release of AutoCAD Release 11 and included many
enhancements to take advantage of the increased feature set in AutoCAD
Release 11. Improved support for other Autodesk products such as AutoShade
and Autodesk 3D Studio was also added. The display interface level was 7.

Rendering drivers could now receive smooth shading factors (a variation of
Gouraud shading). An updated display testing suite for AutoCAD Release 11
was added to the kit. Floating-point emulation libraries were added because
Autodesk multimedia products don't require an Intel math coprocessor. And
ADI 4.1 introduced 8-bit fonts, which previous ADI versions did not
support.

With the third restricted release of AutoCAD Release 11 in September 1990,
rasterizing for 24-pin printer-plotter devices was added.

The second restricted release of AutoCAD Release 11 in July 1990 included
the ability to detect if Autodesk 3D Studio was the product running the
driver, and digitizer button-sensing was enhanced.

With the first restricted release of AutoShade Version 2 in June 1990, the
ability to use the same polygon fill algorithm as AutoShade (Bresenham) was
added, and the plotter ADI interface level constant ADIPKTLEVEL was
incremented from 1 to 2.

With the first restricted release of AutoCAD Release 11 in May 1990,
AutoCAD changed how it interpreted the ADI version level (ignored the 4
least significant bits).


B.3 ADI Version 4.0 (September 1988)
====================================

ADI 4.0 was a major step from ADI 3.1. Support for rendering drivers,
digitizer drivers, plotter drivers, and printer-plotter drivers was added.
Display ADI 4.0 added packet mode support for the multiple viewport
capabilities of AutoCAD Release 10. The display interface level was 6.

ADI 4.0 also provided direct support for display list drivers, eliminating
the need for older drivers to "fool" AutoCAD with several tricks to manage
their display list.

Support was added for optional "smart" dynamic dragging, optional
transparent command parsing, and optional "slave" viewports. (Slave
viewports were discontinued in AutoCAD Release 11.)

The exchanging of packets in packet mode ADI was modified to truncate any
packets longer than expected and to ignore unrecognized packets. This
enhanced compatibility with future ADI versions.


B.4 Display ADI Version 3.1 (November 1987)
===========================================

Display ADI 3.1 resolved some deficiencies reported in version 3.0, and it
was supplied as a driver update for AutoCAD Release 9. The display
interface level was 5. ADI 3.1 added the following:

  * An ability to capture raw input from any configured digitizer. This
allowed the display driver to process the digitizer input before sending it
to AutoCAD if desired.

  * The ability to allow a driver to adjust the size of the AutoCAD "pick
box" and the object snap "aperture" as needed.

  * ADI 3.0 required drivers to cope with four different screen coordinate
systems. ADI 3.1 eliminated one of these screen coordinate systems.


B.5 Display ADI Version 3.0 (September 1987)
============================================

This version of ADI display driver was included in the initial shipments of
AutoCAD Release 9 and in the initial release of AutoShade. The display
interface level was 4. ADI 3.0 added the following new features:

  * Extensions to the INT interface to support the Advanced User Interface
(AUI) used by AutoCAD Release 9 ADE-3.

  * A faster, more efficient "packet-mode" interface for AutoCAD graphics
display drivers (used also for AutoShade and AutoSketch).

  * A very fast "fast vector" drawing facility.

  * Optional Shell command notification.

  * Support for AutoShade rendering device requirements.



B.6 Display ADI Version 2.1 (December 1986)
===========================================

This version was first supplied as a driver update to AutoCAD Version 2.52,
and remained in use through AutoCAD Version 2.62. The display interface
level was 3.

B.7 ADI Display Version 2.0 (October 1986)
==========================================

This version of ADI only supported displays and was shipped with AutoCAD
Version 2.52. The display interface level was 2.





                    |==================================|
                    |                                  |
                    |           Appendix C             |
                    |                                  |
                    |   Graphic Display Environments   |
                    |                                  |
                    |==================================|


C.1 Graphic Display Environments
================================

This appendix describes the graphic display environments for Autodesk
products from the ADI driver viewpoint. You should be familiar with the
products you are writing a driver for, including screen layouts and product
terminology.


C.2 AutoCAD
===========

Conceptually, AutoCAD uses two display screens: a text screen (hidden), and
a graphics screen. For systems with one display, the AutoCAD user can flip
between these screens any time by pressing a function key (except while a
dialogue box is displayed on screen or the Dview, Zoom D, or Vpoint
commands are in progress).

The text screen contains the last screenfull of text. The graphics screen
is logically divided into four windows: the graphics area, the text-
scrolling area, the status line, and the screen-menu area. With the
exception of the graphics area, most display drivers permit the user to
turn each of these areas off to maximize the portion of the screen devoted
to the drawing. Standard placement of these windows is with the text-
scrolling area at the bottom of the display, the screen-menu area at the
right, the status line at the top, and the remainder devoted to the
graphics area.

The ADI driver must communicate the sizes of various screen areas to
AutoCAD. The following figure shows most of the variables involved:


$cb
___  ___  ______________________________________________  ___
 ^    ^  |      STATUS LINE              ^      ||      |  ^
 |    |  |--------------------------------------|| MENU |  |
 |    |  |                       CHARHGT-^      ||      |  |
      |  |                                      ||      |
      |  |                                      ||      |
 |       |<--- - - - - - XMAX - - - - - - - --->||      |  |
 |  YBIAS|                                      ||      |  |
         |<--- - - -  XMENUMIN - - - - - - - --->|      |
YSIZE |  |                                      ||      |  |
      |  |<--- - - - -  XSIZE - - - - - - - - - - - --->|  |
 |       |                                      ||      |
      |  |                                      ||      |  |
      |  |                                      ||     YMENUMAX
 |       |       (Drawing not to scale!)        ||      |
      |  |                                      ||      |  |
 |    |  |                                      ||      |  |
      v  |<-- LLG: origin for "Y biased" coords ||      |  v
 |   === |==============================================| ===
         |                                  ^           |
 |       |                                              |
 |       | TEXT-SCROLLING OR PROMPT AREA                |
_v_      |______________________________________________| ___
         ^                    CHARHGT*SPLIT-^     SPLITHGT-^
         |--LLS origin for AVE Render

$ce
Figure C-1. AutoCAD screen size variables

Since not all display hardware can store and manipulate a complete graphics
bitmap and a full screen of text, AutoCAD takes care of certain functions
that the display device cannot handle. During driver initialization, the
ADI driver tells AutoCAD which capabilities it has. For example, if the
display device and driver cannot store and scroll a text screen independent
of the graphics screen, AutoCAD keeps a buffer of text and scrolls it as
needed.

C.2.1 Dual-Screen and Single-Screen Displays
============================================

There are two forms of display devices: those that can operate in a single-
screen mode, and those that operate in a dual-screen mode. Dual-screen
devices use one monitor for the graphics screen and another monitor for the
text screen. Single-screen devices use only one monitor. Examples of single-
screen display devices are the Hercules Graphics Card and the IBM Video
Graphics Adapter.

Some devices can be operated in either single-screen or dual-screen mode,
depending on the hardware configuration of the user's machine. For dual-
screen systems, the text-scrolling area is replaced by a one-line prompt
area, although the term "text-scrolling area" often refers to whichever of
these is present.

C.2.2 Menu and Dialogue Box Support
===================================

The Advanced User Interface (AUI) was introduced in AutoCAD Release 9.
Driver support for AUI is mandatory for release 11 and newer versions of
AutoCAD, and for all other Autodesk products.

Pull-down menus require a pointing device; the keyboard cannot be used to
access them. When the user moves the pointing device to the top of the
graphics area (into the status line), the menu bar replaces the status
line. Pull-down menus are then accessed from the menu bar. The menu bar
feature relies on the status line being configured ON and being positioned
at the top of the screen.

To use the AUI features, the display driver must be capable of saving and
restoring the contents of the screen where the menu bar, pull-down menu,
icon menu, or dialogue box will be displayed. Furthermore, dialogue boxes
can be "stacked" on top of one another. In AutoCAD before Release 12, the
sum total of dialogue boxes on the stack at any time can exceed one
physical screen in size. For AutoShade, however, the total never exceeds
one screen. For AutoCAD Release 12, due to user-defined programmable
dialogues, there is no limit to the stacking of dialogue boxes. The most
recent box pushed onto the stack is always the first to be popped.

AutoCAD 386 does not provide space for box push requests because your
protected mode P386 driver has access to memory and can use the malloc()
function. The Phar Lap VMM swaps to disk if RAM runs out.

Although most Autodesk products that provide box push storage usually do so
in chunks of less than 64K, some products can satisfy a request larger than
64K with a single buffer. Be sure your code allows for this possibility.

Table C-1. Box push memory handling by product and platform

Product  Platform   Version  ADI Type  psavebl  Max Space Provided
----------------------------------------------------------------
AutoCAD   640K DOS  >= R9   Real mode   Ignored  Until disk full
AutoCAD     386     >= R10  P386        Ignored  Driver uses malloc()
AutoCAD     386     >= R10  Real mode   Ignored  Until disk full
AutoShade 640K DOS  any     Real mode   Required About 60K
AutoShade   386     2       Real mode   Required About 60K
AutoShade   386     2       P386        Ignored  Driver uses malloc()
AutoSketch 640K DOS < 3.0   Real mode   Required About 60k
AutoSketch 640K DOS 3.0     Real mode   Optional Until disk full
3D Studio   386     1.0     P386        Ignored  Driver uses malloc()


C.2.3 AutoCAD Coordinate Systems
================================

The following figure shows the relationship (for such drivers) between
"real," "logical," and viewport-independent "pixel" (or LLG) coordinates
for a given viewport, and the variables used to reference each. The visible
portion of the logical screen maps directly into the viewport of the
graphics area of the AutoCAD screen, as shown:


$cb
............................................................................
.                   REAL COORDINATES                              1.7e+308 .
.                                                                          .
.   ....................................................................   .
.   .               LOGICAL SCREEN                            (rxh,ryh).   .
.   .                                                 (lgxdots,lgydots).   .
.   .                                                                  .   .
.   .    ----------------------------------------------------------    .   .
.   .    |    VISIBLE PORTION OF LOGICAL SCREEN        (lgxh,lgyh)|    .   .
.   .    |        (LLG COORDINATES)                (vpxmax,vpymax)|    .   .
.   .    |                                                        |    .   .
.   .    |    *This visible portion maps to the graphics area of  |    .   .
.   .    |     the AutoCAD screen or viewport.                    |    .   .
.   .    |                                                        |    .   .
.   .    |(vpxmin,vpymin)                                         |    .   .
.   .    |(lgxl,lgyl)                                             |    .   .
.   .    ----------------------------------------------------------    .   .
.   .                                                                  .   .
.   .(0,0)                                                             .   .
.   .(rxl,ryl)                                                         .   .
.   ....................................................................   .
.                                                                          .
. -1.7e+308                                                                .
............................................................................

$ce
Figure C-2. AutoCAD screens

AutoCAD uses double-precision floating-point real numbers to define the
"drawing area." This area can be defined from Cartesian coordinate values
ranging from -1.7e+308 to 1.7e+308.

The logical screen is contained within these real coordinates and is in
integer space with coordinates ranging from (0,0) to (lgxdots, lgydots),
typically (32766, 32766). For BIGVEC drivers this is 0 to 0x7ffffffd.

The visible portion of the logical screen can pan and zoom within the area
defined by the logical screen. The visible portion of the logical screen is
defined by (lgxl,lgyl) in the lower-left corner and (lgxh,lgyh) in the
upper-right corner.

If AutoCAD is asked to split the screen into two "equal" viewports, they
may be slightly different in size because the starting screen size
available for the division was odd in the direction of division.

C.2.3.1 Single-Screen and Dual-Screen AutoCAD Drivers
-----------------------------------------------------

Dual-screen-only AutoCAD display drivers are considerably simpler than
single-screen drivers. A dual-screen driver does not have to deal with a
text-scrolling area. There is one unique dual-screen function call to move
the text cursor to the prompt area. The driver doesn't have to worry about
characters sent to the text screen, thus avoiding the whole issue of
special characters.

Technically, a single-screen driver has a text-scrolling area at the bottom
of the graphics screen and a dual-screen driver has a one-line prompt area
there.

The prompt area of a dual-screen system contains only messages that are
internally designated as prompts. Informational messages and echoing of
user input does not appear in the prompt area. In addition, the way text is
sent to the two areas differs.

For a single-screen driver, text is sent to the text-scrolling area via
PWRSPLIT. The driver's PWRSPLIT handler must scroll the text area when a
new-line character is encountered on the bottom line of the screen, or when
the last column of the bottom line is reached.

On a dual-screen system, AutoCAD uses DOS to display characters on the text
screen, without calling your display driver for anything.

For dual-screen drivers, text is sent to the prompt area by a PTPROMPT
call, followed by a series of PCHAR calls, and a PECHAR call to mark the
end of the string of PCHAR calls. With the exception that the sequence
begins with a PTPROMPT call instead of PMNUCURS, this is the same mechanism
as that used to display an item in the screen menu. The only things to
watch for with this mechanism are:

  * Ignore any character you don't want to display. Most drivers ignore
everything less than ASCII 32 or greater than ASCII 127 (see PLANG for
exceptions).

  * Ignore anything beyond the maximum length of the prompt area. The worst
case prompt (in the English language version of AutoCAD) is the Pline
command's prompt for input when you are starting an arc segment of a
polyline, which has an embedded new-line character.

  * The driver should not wrap to the beginning of the line if the input
string is too long. This is because AutoCAD pads each prompt with enough
spaces to ensure that the previous prompt is blanked out. If your driver
did this, and then a short prompt followed a long prompt (with more than
one line), the short prompt would be invisible due to the padding.


C.3 AutoShade
=============

Like AutoCAD, AutoShade employs two screens. A graphics display is used for
command selection and parameter setting by means of pull-down menus and
dialogue boxes. This screen is also used when plan or wireframe images are
displayed. AutoShade's second screen is the rendering screen; fast-shaded
and full-shaded images are displayed here. The two screens can be separate
display devices, or the same device.

AutoShade 386 supports protected-mode drivers that have direct access to
virtual memory and thus should be able to handle box-push requests on their
own. Real-mode ADI drivers are still given only limited help with box
pushes. See table C-1 for more information on AUI box push memory handling.

C.3.1 AutoShade Version 2 with Autodesk RenderMan
=================================================

AutoShade Version 2 with Autodesk RenderMan (also called AutoShade 386)
acts as a single product. RenderMan does not output packets directly to an
ADI driver. Packets generated by RenderMan are sent to drivers via
AutoShade, through the dispatcher.

Display driver packets can be generated during a RenderMan rendering for
such things as error messages, handling dialogues, and so forth. Therefore,
it is important to realize that any packet that can be generated by
AutoShade can also be sent to the ADI driver during a RenderMan rendering.

The possible rendering packets that an ADI driver can receive during a
RenderMan rendering are:

RDSTART
RDCLEAR
RDCMAPB
RDCMAP
RDCMAPE
RDEND
RDWSLINE
RDRSLINE


C.4 Autodesk 3D Studio
======================

Autodesk 3D Studio uses only protected-mode ADI drivers. Because these
drivers have direct access to virtual memory, your driver must take care of
its own box-push memory handling.

There are five program modules in Autodesk 3D Studio. Although Autodesk 3D
Studio appears to be a single program, it was developed as a group of stand-
alone modules that were bound together at the end of development. The
modules are: the 2D Shaper, the 3D Lofter, the 3D Editor, the Keyframer,
and the Materials Editor. 3D Studio program modules have differing ADI
driver requirements, listed below.

See the Autodesk 3D Studio Reference Manual for a detailed discussion of
display screen elements and the Materials Editor screen. All display
screens in Autodesk 3D Studio use pull-down menus and dialogue boxes.

DEV_DS and DEV_RC drivers that recognize 3D Studio as the host product
should only perform XORs with the lower 4 bits of their palette, and 3D
Studio will not run if you configure for a DEV_DS or DEV_RC driver with a
text screen smaller than 80x30.

C.4.1 Module Requirements
=========================

All modules load and release resources, such as ADI drivers, and maintain
their own configuration information. This lets modules use different
display resolutions because their configurations are separate from each
other.

The 2D Shaper, 3D Lofter, and 3D Editor can use the display part of a
DEV_RC driver. A resolution greater than or equal to 640x480 with 16 colors
and a mapped palette is required.

The renderer part of the 3D Editor can use a DEV_RD, DEV_RH, or the
rendering part of a REV_RC driver. It requires a minimum resolution of 320
by 200 by 256 colors. Rendering output is via scanlines.

In 3D Studio v1.0, the Keyframer cannot use ADI drivers. A VGA in 320 by
200 by 256 color mode is required. This restriction is not present in 3D
Studio v2.0.

The Materials Editor can use the display part of a DEV_RC driver. Because
of the function and purpose of the Materials Editor, there is no point to
supplying much more resolution than 320 by 200 by 256 colors. The Materials
Editor changes the image on the screen dynamically by making color map
calls--a device that lacks palette registers will have trouble with this.
Color map RGB values are sent within the ranging from 0-63. Your driver
might need to rescale this range if you have a true 8-bit range for RGB
values. materials editor sends color map values with RGB ranging from 0-63.
Your driver may need to rescale this range if you have a true 8-bit range
for RGB values.

C.4.2 Partial ADI 4.2 Support
=============================

3D Studio Version 2.0 supports three ADI 4.2 packets: PWHO, RDWHO, and
PKILL. All the other ADI support is per the ADI 4.1 specification.

The ADI 4.2 packets PWHO and RDWHO let drivers know which product is in
control. Although 3D Studio does not have ADS, the regapp_name field in
these two packets (the pkwho structure) is used by 3D Studio v2.0. It is
filled in with the name of the 3D Studio module currently in charge or the
device type currently being configured:

"3DS_MAIN"
"3DS_MEDIT"
"3DS_RC"
"3DS_RD"
"3DS_RH"
"3DS_VTR"
"3DS_DG"




                    |==============================|
                    |                              |
                    |          Appendix D          |
                    |                              |
                    |   Extended DOS Information   |
                    |                              |
                    |==============================|


D.1 Extended DOS Information
============================

This appendix provides a history of the Phar Lap 386|DOS-Extender versions
used with AutoCAD 386 and extended DOS information such as compatibility.
Much of the material presented here is covered in detail in the Phar Lap
documentation. We have distilled some of the more pertinent information on
Autodesk products' use of Phar Lap development tools to help in your driver
development.


D.2 AutoCAD 386 Release 10
==========================

AutoCAD 386 Release 10 shipped with the 2.2d Phar Lap 386|DOS-Extender.


D.3 AutoCAD 386 Release 11
==========================

The C1 version of AutoCAD 386 Release 11 was shipped with Phar Lap 386|DOS-
Extender version 2.2d. In November 1990 an upgraded 386|DOS-Extender was
made available to AutoCAD 386 users. This was version 2.6 and was installed
by running "newdx." The C2 version of AutoCAD 386 Release 11 was shipped
with 386|DOS-Extender version 2.6. The older 2.2d 386|DOS-Extender could
still be installed by running "olddx."

A software developer's kit for version 2.6 was never released to the
general market, so developers continued to use 2.2d tools for development
under release 11.

D.3.1 386|DOS-Extender 2.6
==========================

Following are some of the major improvements made in version 2.6:

  * A smaller kernel. 386|DOS-Extender 2.2d had a fixed conventional memory
footprint of approximately 180K. 386|DOS-Extender 2.6 only required 80K.
This additional memory translated into more space for shelled programs,
TSRs, and so forth.

  * Demand paged loading for AutoCAD. 386|DOS-Extender 2.2d loaded the
entire program into memory, and then freed up pieces when memory was
scarce. A feature of 386|DOS-Extender 2.6 was that it loaded code as
needed. This reduced the load time of AutoCAD 386 by 30 to 40 percent (this
386|DOS-Extender switch is called DEMANDLOAD).

  * XMS support. XMS stands for extended memory specification. XMS replaces
the method of VDISK headers and other schemes that applications have had to
rely on to share extended memory. XMS is necessary to access super extended
memory (above 16 MB on EISA machines).

  * Multiple Memory Support. 386|DOS-Extender 2.2d only allocated extended
memory via one source. If a VCPI-compliant expanded memory manager was
installed, AutoCAD 386 only obtained memory from that manager, even if
there was unused extended memory.

386|DOS-Extender 2.6 and newer uses memory from VCPI, extended, and XMS
memory pools. If an XMS driver is not installed, the order of memory
allocation is: 1) direct extended memory; 2) from the VCPI memory manager;
and 3) from Compaq built-in memory (Compaq machines only). If an XMS driver
is installed, all memory is allocated from the driver.

  * Limited Windows 3.0 support. 386|DOS-Extender version 2.6 runs in a
Windows 3.0 DOS Box, in both real and standard modes. Windows 3.0 requires
that graphics programs (like AutoCAD 386) run in the full-screen mode of
the DOS Box.

In standard mode, 386|DOS-Extender gets its memory from XMS. To make sure
that AutoCAD uses XMS memory when it runs in the DOS Box, you must have a
Windows PIF file set up so that XMS memory is available.

386|DOS-Extender version 2.6 does not support Windows 3.0 386 enhanced
mode. Autodesk does not warrant the suitability of Windows 3.0 as an
operating environment for AutoCAD 386.

  * Phar Lap added some new switches with 386|DOS-Extender 2.6. The
switches added were: DEMANDLOAD, MAXXMSMEM, MAXEXTMEM, and VSLEN. See your
Phar Lap documentation for complete information on them.

The DEMANDLOAD switch applied only to the AutoCAD executable and had no
effect on ADI or ADS programs. The VSLEN switch setting could be varied to
improve digitizer performance (by reducing the work on each _VSCAN scan);
however, this had no effect on interrupt-mode digitizer drivers.

D.3.2 386|DOS-Extender Upgrade from 2.6 to 3.0 and 4.0
======================================================

386|DOS-Extender 3.0 was never used for AutoCAD 386. The next update used
for AutoCAD 386 was 4.1, for release 12. Full DPMI support by 386|DOS-
Extender didn't occur until version 4.0. Improvements in version 3.0 Phar
Lap development tools are covered in your Phar Lap documentation.

Programs most affected by the 386|DOS-Extender 3.0 release were debuggers
because of changes to interrupt stack frames and the new system call for
installing processor exception handlers. Also, most debuggers probably
handled system-level operations that couldn't be done in unprivileged mode.

386|DOS-Extender 4.0 added full DPMI 0.9 support (0.9 is the version of
DPMI used with Windows 3.0/3.1).


D.4 AutoCAD 386 Release 12
==========================

D.4.1 Phar Lap 386|DOS-Extender
===============================

Version 4.1 of the 386|DOS-Extender is bound into AutoCAD 386. This version
differs from the 4.0 version primarily in its support of AutoCAD 386 under
Windows. The Windows device driver (pharlap.386, by Phar Lap) extends the
DPMI server in Windows so that AutoCAD can run as a full-screen DOS
application in a Windows DOS box.

D.4.2 386|DOS-Extender Switches
===============================

The default 386|DOS-Extender switches in AutoCAD 386 Release 12 are:

-minswfsize 400000 -swapdefdisk -swapchk off -demandload \ -vscan 20000

To change or add switches, use the cfig386 utility as follows:

cfig386 acad -newswitch -anotherswitch -etc

To start fresh use the -clear switch. For instance, if you want to restore
AutoCAD 386 to its original state, use the following command:

cfig386 acad -clear -minswfsize 400000 -swapdefdisk -swapchk off \
-demandload -vscan 20000

The UNPRIV switch is linked into AutoCAD so that it runs in unprivileged
mode. This allows it to run under Windows. Using the clear switch does not
disable the UNPRIV switch, though you may change UNPRIV to PRIV using the
cfig386 utility.

D.4.3 386|DOS-Extender Switches
===============================

Following is a list of 386|DOS-Extender 4.1 switches that are of interest
to developers. Some switches have an argument. Numerical arguments are
considered to be in decimal (base 10). To specify hexadecimal (base 16)
numbers, append the character "h" or "H" to the number. For complete
details on these switches, see your Phar Lap documentation.

MAXBLKXMS [nbytes]  Defines the maximum size, in bytes, of an individual
XMS block (default = 4 GB).

MAXXMSMEM [nbytes]  Defines the maximum number of bytes of XMS memory to
allocate (default = 4 GB).

MAXEXTMEM [nbytes]  Defines the maximum number of bytes of direct extended
memory to allocate (default = 4 GB).

MAXVCPIMEM [nbytes] Defines the maximum number of bytes of memory to
allocate from an EMS emulator that supports the VCPI interface (default = 4
GB).

XMS [setting]  The default setting for this switch is AUTO, which means
that the XMS lock block call returns linear addresses under 386-to-the-Max
and physical addresses under all other XMS drivers. Other settings are OFF,
PHYSICAL, and LINEAR.

NOPCD[WEITEK]  Don't assert the PCD (Page Cache Disable) bits for the
Weitek or Cyrix memory-mapped coprocessors on 486 or later PCs. By default
the PCD bits on 486s or higher are asserted. On Compaq machines, the PCD
bits are NOT asserted to work around a bug on Compaq 486/33L machines. This
switch can be used to turn off PCD bits on any 486 or later PC.

EXTLOW [address]    Establishes lowest address in direct extended memory
that the application can use.

EXTHIGH [address]   Establishes highest address in direct extended memory
that the application can use.

ERRATA17  Installs a software work-around for errata17 of the 386 chip. Use
this switch when running under 386|VMM on a machine with a B1 step 386 chip
and a hardware work-around for erratum 21. There is no point in using -
errata17 on a machine with a B1 386 chip and no hardware fix for erratum 21.

VDISK     A work-around for compatibility problems with other programs that
do not correctly follow the VDISK standard for allocating extended memory. If
386|DOS-Extender refuses to run an application because of inconsistent
VDISK allocation signatures, this switch can be used to force 386|DOS-
Extender to run the program. The larger of the two allocation marks present
will be used. Before using this switch you should check the allocation
sizes printed out with the error message when 386|DOS-Extender refuses to
run the program. If the larger of the two numbers printed out does not seem
reasonable it's necessary to calculate how much extended memory is in use
by other programs and to use the -EXTLOW switch to inform 386|DOS-Extender
of the correct value.

PRIV Privileged operation is not supported under DPMI, UNPRIV so AutoCAD
386 is linked with the -UNPRIV switch to operate under Windows. (See the
section titled "Running under Windows.")

NOSPCLMEM Tells 386|DOS-Extender not to look for special Compaq built-in
memory.

A20  Forces 386|DOS-Extender to disable A20 each time the 80386 switches to
real mode, and to re-enable A20 each time the 80386 switches to protected
mode.

SAVEREGS  Forces 386|DOS-Extender to preserve the high 16 bits of general
registers across switches to real mode initiated by software interrupts.

SWAPNAME [filename] The swap filename (default is a DOS temp file).

SWAPDEFDISK    The current default disk drive for the swap file (default is
the disk on which the application is located).

SWAPDIR [dirname]   The device and directory in which to place the page
swap file (default is the root directory of the device from which the
application was loaded).

LFU  Least Frequently Used page replacement policy (default).

NUR  Not Used Recently page replacement policy.

VSCAN [nmillisecs]  Page table scanning frequency in milliseconds (default
is 4000 ms).

VSLEN [nbytes] Maximum amount of linear address space to process on each
page table scan (default is FFFFFFFFh).

DEMANDLOAD     Pages in program as needed.

NOPGEXP   Forces 386|VMM not to page out of the .exp file. When used,
386|DOS-Extender reads the entire program into memory at load time and
places all swapped out pages (including code pages) in the swap file. This
is useful if the application is loaded from the network server and paging
over the network causes performance degradation.

MINSWFSIZE [nbytes] The minimum size of the swap file at program load time.

MAXSWFSIZE [nbytes] Limits the maximum disk space allocated to the swap
file. If not used, the only upper bound on swap file size is the amount of
free space available on the disk.

D.4.3.1 386|DOS-Extender Compatibility
--------------------------------------

386|DOS-Extender is fully compatible with XMS. It is also compatible with
VCPI-compliant EMS emulators. 386|DOS-Extender applications can operate
normally under DESQview. AutoCAD 386, when used in conjunction with the
pharlap.386 Windows device driver, can run in a Windows 3.1 DOS Box in
enhanced mode.

D.4.3.2 Direct Extended Memory Allocation
-----------------------------------------

386|DOS-Extender allows an AutoCAD 386 to allocate any direct extended
memory not in use by other programs. At initialization time 386|DOS-
Extender obtains the minimum available extended memory address by checking
for memory that was allocated starting at one MB, with the VDISK extended
memory allocation standard or with the technique used by the Microsoft
RAMDRIVE program. 386|DOS-Extender also obtains the top of extended memory
by calling the BIOS system function INT 15h, function 88h.

If you have installed on your system programs that use extended memory but
do not use any of the standard methods for allocating extended memory, you
need to limit the amount of extended memory that 386|DOS-Extender uses to
avoid conflict. This is done by determining which addresses in extended
memory are used by the other programs and then limiting the 386|DOS-
Extender use of extended memory with the EXTLOW and EXTHIGH command line
switches.

There is a secondary problem with the VDISK memory allocation standard. The
amount of memory allocated with this method is marked in two places: in a
signature block pointed to by the INT 19h interrupt vector, and in a boot
block maintained at 1 MB. Some programs that use this standard only update
the allocation mark in one location, usually the signature block of the INT
19h vector. Also, under MS-DOS version 3.3, the resident portion of the
print command takes over the INT 19h vector, which masks the VDISK
signature block.

Because of these problems, 386|DOS-Extender checks both VDISK allocation
marks. If the two values are not the same, 386|DOS-Extender prints out an
error message showing the two values and refuses to run the application
program. You should then check all the drivers in your config.sys file to
see which of them attempted to allocate extended memory. Determine whether
the larger of the two numbers that 386|DOS-Extender is finding is correct.
If it is, you can use the VDISK command line switch to tell 386|DOS-
Extender to proceed, using the larger of the two available numbers. If
neither number is correct (i.e., if you have a program that updates the
VDISK signature block but not the boot block, and you the run the MS-DOS
Print command under MS-DOS version 3.3), then you must use the EXTLOW
command line switch to give 386|DOS-Extender the correct value.

D.4.3.3 Address Line 20 Enabling
--------------------------------

All PC-compatible architectures can enable or disable address line 20 in
hardware. When address line 20 is disabled, the physical addresses placed
on the bus by the 80386 are truncated to 20 bits by external hardware. This
is for compatibility with MS-DOS programs that rely on address wraparound
at 1 MB. Therefore, address line 20 is typically disabled when MS-DOS is
executing in real mode.

For protected mode programs to run correctly, address line 20 must be
enabled so it can access memory above 1 MB. By default, 386|DOS-Extender
enables address line 20 during initialization and leaves it enabled while
the application program is executing. When the application program
terminates, 386|DOS-Extender returns address line 20 to the setting
(enabled or disabled) it had originally.

The command line switch A20 can be used to force 386|DOS-Extender to enable
address line 20 each time it switches to protected mode and to disable it
each time it switches to real mode. The only time this switch is needed is
when a real-mode program that relies on address wraparound at 1 MB is
executing while the protected-mode program is executing. Examples include a
terminate and stay resident program or a real-mode program to which the
protected-mode program EXECs.

There is a penalty associated with the use of the A20 switch. On the
original PC AT hardware design, it took several milliseconds to enable or
disable A20. Thus on systems with this design, using the A20 switch adds
several milliseconds to each mode switch.

However, all Compaq 386 machines manufactured after January 1987, the IBM
PS/2 architecture, and the EISA architecture can switch the A20 state in a
few microseconds.

D.4.3.4 RAM Disks and Disk Cache Programs
-----------------------------------------

RAM disks are programs that simulate a disk drive in memory. They are often
used to hold frequently accessed files to improve access times. Disk cache
programs cache data read from or written to the physical disk drives on a
system, to improve the performance of the system.

The only potential compatibility problem between 386|DOS-Extender and
either RAM disk or disk cache programs is their use of extended memory.
386|DOS-Extender is compatible with all programs that follow either the
VDISK standard, the BIOS extended memory size determination standard, or
the technique used by the Microsoft RAMDRIVE program, for allocating
extended memory. If you are using memory-resident programs that allocate
extended memory and do not follow one of these two standards, the EXTLOW
and EXTHIGH command line switches must be used to inform 386|DOS-Extender
how much extended memory is allocated to these programs.

Performance: Using a Disk Cache
-------------------------------
Most computer manufacturers distribute a disk cache program with their
machines. A disk cache program keeps recently referenced disk sectors in
memory, so that the system need not get them from the disk each time they
are referenced. Since 386|VMM keeps a page swap file on disk, there is
considerable disk I/O for paging when running programs much larger than the
available physical memory. With heavy disk activity, the DOS file system
needs to access the disk File Allocation Table (FAT) frequently. Since the
FAT tends to stay in the disk cache, the overall program performance can
often benefit from installing a small disk cache. It is not advisable to
allocate a lot of memory to the disk cache, since this reduces the amount
of physical memory available to 386|VMM.

D.4.3.5 386/387 Paging Errata Work-around
-----------------------------------------

80386 chip steps B1 and earlier have two chip errata (known as "erratum 17"
and "erratum 21") that occur only with protected-mode programs that use the
80387 floating-point coprocessor (i.e., AutoCAD 386). Both errata cause the
386 to stop processing instructions when an 80387 instruction is executed
under certain conditions, causing the program to apparently hang. Neither
erratum exists in any 386SX chip or in 386 chip step D0 (released in the
second quarter of 1988) and later.

The 386|DOS-Extender switch ERRATA17 installs a software work-around for
erratum 17, but leaves paging enabled (there is no viable software work-
around for erratum 21 with paging enabled). The ERRATA17 switch is only
needed if 386|VMM is used, and is only effective if a hardware work-around
for erratum 21 is in place (preventing erratum 17 does no good if erratum
21 can still occur).

You must either use chip step D0 or later of the 386 chip, or get a
hardware piggyback board with a work-around for erratum 21. Some PC
motherboards have a hardware work-around for erratum 21 designed in (i.e.,
all Compaq 386/20 PCs).

D.4.4 Important Differences Between AutoCAD Release 11 and Release 12
==========

Following are key 386|DOS-Extender-related differences between AutoCAD 386
Release 11 and AutoCAD 386 Release 12.

  * Release 11 was privilege; release 12 is unprivileged.

  * Release 11 does not run with DPMI 0.9; release 12 does.

  * Release 11 386|DOS-Extender default configured switches:

-minswfsize 400000 -swapdefdisk -swapchk off -intmap 8 -vscan 20000

  * Release 12 386|DOS-Extender default configured switches:

-minswfsize 400000 -swapdefdisk -swapchk off -demandload -vscan 20000

  * Demand loading became the default for release 12. Release 11 vC2 had
demand loading available (it required 386|DOS-Extender 2.6 or newer).


D.5 Debugging Information
=========================

Debugging ADI drivers in the extended DOS environment is covered in chapter
2. For information on debugging AutoCAD applications under the extended DOS
environment, see the ASCII text files for your compiler in the AutoCAD
directory /ads/docs. The MetaWare High C document is named highc.txt, the
WATCOM C/386 document is named watcom.txt, and the Zortech C++ document is
named ztc.txt. Details about AutoCAD and Phar Lap tools, such as important
switches, are in a document named pharlap.txt.


D.6 Running under Windows
===========================

To run AutoCAD 386 Release 12 under Windows, the Windows device driver
pharlap.386 supplied with 386|DOS-Extender 4.1 must be installed in the
Windows system.ini file by adding the following line to the [386Enh]
section of the file: device=pharlap.386, and then copy the driver into the
Windows subdirectory.

You also need to set up an acad.pif file for AutoCAD 386. In the PIF file
set Video Memory to High Graphics, EMS Memory to 0 KB for both the Required
and Limit fields, and XMS Memory to 0 KB for the Required field and a
minimum of 2048 KB, up to -1 (which takes as much as possible), for the
Limit field. Set Display Usage to Full Screen. You don't need to worry
about setting the Advanced options.

386|VMM and the switches associated with it are always disabled under
Windows since the Windows DPMI server allocates all extended memory. The
disabled switches are these:

DEMANDLOAD
EXTLOW
EXTHIGH
LFU
MAXSWFSIZE
MINSWFSIZE
NOPGEXP
NOSWFGROW1ST
NUR
SWAPCHK
SWAPDEFDISK
SWAPDIR
SWAPNAME
SWFGROW1ST
VSCAN
VSLEN

Since OFFSET is not supported under Windows, the Alternate Page Fault
handler in AutoCAD will not work if a NULL pointer is used, therefore
program carefully so as not to reference any NULL pointer or you could
bring AutoCAD down.

The DPMI host under Windows 3.x enhanced mode provides a virtual memory
environment. This means that when INT 21h Func 48h (allocate segment)
returns an error, the returned size of available memory includes all
available disk space. Don't try to allocate this amount unless you really
need it; it takes a long time for Windows to allocate it, and it will
consume all the free disk space. Under Windows 3.x, the returned number
should not be considered accurate since Windows does not take available
disk space into account when returning the amount of available virtual
memory.

AutoCAD 386 runs only under Windows 3.1 or greater because under Windows
3.0 you must preallocate your heap. Under Windows 3.0 you cannot grow the
segment without the risk of losing virtual memory paged to disk if the
segment's linear base address changes (i.e., if the segment gets moved).
Thus under Windows 3.0, release 12 ADS applications and protected mode ADI
drivers would each be given 2 MB of preallocated heap in addition to their
initial load size. One way to get around the 2 MB default of preallocated
heap is to set the heap size actually needed using MAXDATA. Under Windows
3.1, the default MAXDATA (4 GB) is not a problem since the segment can be
grown, allowing the compiler runtimes to shrink the segment to minimum at
initialization and then grow it as needed.


D.7 Summary of Differences Between Phar Lap 4.0 and 4.1
=======================================================

The following differences between 4.0 and 4.1 are most relevant to AutoCAD
386 and third-party developers. See your Phar Lap documentation for
complete information.

D.7.1 Modified System Calls
===========================

2509h, 250Ah
------------
These have limited support under Windows 3.0 if the pharlap.386 driver is
installed. The 2509h call will succeed only for linear addresses that fall
within the REALBREAK part of a segment. The returned value is NOT a
physical address, but an internal DOS extender handle. When passed to the
250Ah call, the REALBREAK pages are mapped to the end of the segment
specified in the 250Ah call.

250Fh
-----
This is supported under Windows 3.0 if the pharlap.386 driver is installed.

2520h
-----
extlim (offset 10h) is now guaranteed to be less than or equal to nextpg
(offset 0Ch). It returns currently available pages limited by the
application-set limit, rather than just remembering the limit if some other
program has consumed previously available pages. This is consistent with
what the 2521h call does: you can't use that call to set your limit above
the currently available pages.

D.7.1.1 Memory Allocator Adjustments in 386|DOS-Extender 4.1
------------------------------------------------------------

  * INT 21h Func 48h error return, the number of physical pages available,
is now limited by the MAXPGMMEM switch if used.

  * You cannot allocate both under NOPAGE or under DPMI more memory than
the MAXPGMMEM switch (if used). In previous versions MAXPGMMEM was disabled
under NOPAGE and DPMI.

  * Free XMS memory calculations are accurately made by allocating the
memory and then freeing it again.

  * On machines with greater than 64 MB and an XMS driver, you can now load
programs larger than 64 MB. In previous versions you could allocate all the
memory after loading, but you couldn't load a program larger than 64 MB.

D.7.1.2 INT 21h Func 2520h, Get Memory Statistics
-------------------------------------------------

Offset 0054h
------------
The number of free physical pages guaranteed available (always 0 under a
DPMI host). Other physical memory might be available, but not guaranteed
because 386|DOS-Extender hasn't allocated it yet and some other program
could allocate it first.

Offset 0058h
------------
The number of free physical pages reported available (but not guaranteed
because another program could get it first). Under a DPMI host, this is the
free physical page count returned by the host, but is basically a random
number under Windows 3.0.

Note that unlike INT 21h Func 48h, this does NOT subtract any additional
system pages that would be needed to allocate this much memory, so
typically you might only be able to allocate a few pages less than this.
Under 386|VMM or a DPMI host that supports virtual memory, this number (and
the number at offset 0054h) is not meaningful because it's reporting
physical pages.

Offset 005Ch
------------
The largest available free virtual memory block, in pages (limited by the
MAXPGMMEM switch, if used). Except under 386|VMM, this is the same number
returned by INT 21h function 48h. Under 386|VMM, this returns the amount of
virtual memory available. This is the most accurate number to use to find
out how much memory is available to be allocated in all environments. This
value was returned by the 2520h call starting with 386|DOS-Extender version
4.0.


D.8 386|DOS-Extender Manual Changes
===================================

Following are some differences between 386|DOS-Extender version 4.1 and the
third edition of "386|DOS-Extender Reference Manual," published in January
1991.

D.8.1 Windows 3.x Support
=========================

"The 386|DOS-Extender Programmer's Guide to DPMI and Windows" documents
Windows support as of 386|DOS-Extender version 4.0. This manual describes
in detail many of the issues involved with writing 386|DOS-Extender
applications that run in the DOS compatibility box of Windows 3.x enhanced
mode. Included in the manual is a large amount of C example code to
illustrate the ideas covered in the text.

In version 4.1, support for the REALBREAK switch, and the 250Fh call
(convert protected-mode address to MS-DOS address) has been added for
Windows 3.x. To enable REALBREAK support, you must install the pharlap.386
Windows device driver.

D.8.2 Interrupt Handlers Under Windows 3.x
==========================================

Windows 3.x enhanced mode supports demand-paged virtual memory. Page faults
in a hardware interrupt handler or a critical error handler are not
allowed; if one occurs it will crash Windows.

BEFORE installing a hardware interrupt handler or critical error handler,
you MUST lock all memory that is read or written by that handler. This
includes all code and data accessed by the handler, and also stack memory
if the handler switches stacks. It is not necessary to lock the stack if
you don't switch stacks, since the stack provided when your interrupt
handler is entered is always locked.

Use the 251Ah or 252Bh subfunction 5 system calls to lock memory, and the
251Bh or 252Bh subfunction 6 system calls to unlock memory. These calls are
documented in The 386|DOS-Extender Programmer's Guide to DPMI and Windows.
These are the same calls used to lock memory under the 386|VMM virtual
memory system. When not running under Windows or 386|VMM, these calls do
nothing and always return success. Correct procedure is therefore to always
lock down hardware interrupt handlers using these calls.

Do not increase the size of a segment accessed by a hardware interrupt
handler (for code, data, or stack). The segment can be moved in the linear
address space, and under DPMI there is no way to update the segment
descriptor when the segment moves, so there is a window where a hardware
interrupt can come in and the descriptor points to the old linear address,
which is no longer valid. If you need to resize a segment that is accessed
by a hardware interrupt handler, first unhook the hardware interrupt, then
resize the segment, then rehook the interrupt.

If you write an interrupt handler that chains to the previous handler, you
cannot forge a return address to regain control when the previous handler
IRETDs (by changing the 386|DOS-Extender umbrella CS:EIP values in the
stack frame) under Windows 3.x.

It is important to remember that most DPMI hosts (including Windows 3.x
enhanced mode) provide a virtual memory environment. This means that when
INT 21h Func 48h (allocate segment) returns an error, the returned size of
available memory includes all available disk space. Don't try to allocate
this amount unless you really need it; it takes a long time for Windows to
allocate it, and it will consume all free disk space. Under Windows 3.x,
the returned number should not be considered accurate since Windows does
not take available disk space into account when returning the amount of
available virtual memory.





                    |==================================|
                    |                                  |
                    |           Appendix E             |
                    |                                  |
                    | Confidential ADI Information for |
                    | Developers Under Nondisclosure   |
                    |            Agreements            |
                    |                                  |
                    |==================================|


E.1 Topics for Developers Under Nondisclosure
=============================================

This appendix presents topics for ADI developers who are under 
nondisclosure agreements, and is confidential. Topics
covered in this appendix include ADI prerelease or work-in-progress
subject matter, questions and answers, and some historical sample-driver
or product-related development information that may help in your current
driver development. If you are working with very old drivers or Autodesk
products, refer to the documentation that accompanied the old
product or ADIKIT for the most complete information.

This appendix is not available in the printed ADI documentation.


E.2 ADI Development Historical Notes
====================================

This section lists some notable additions, modifications, or bugs in the
ADIKIT or Autodesk products that might be useful to you in modifying your
older drivers or developing new ones. These notes are listed by ADI version
releases.


E.2.1 ADI Version 4.1 (November 1990)
--------------------------------------

  * The interface level was 7 for this release.

  * The PKZOOM packet was added, which included a warning that a requested
    Pan or Zoom would require a Regen.

  * The default interrupt vector for real-mode rendering hardcopy drivers
    for AutoShade Version 2 was changed from 7ah to 7ch.

  * The core code in AutoCAD for pkzoom() was failing to produce
    the correct view when a model space viewport was partly
    off screen (and thus clipped). It also allowed a driver
    to zoom in past the point where logical and physical pixels
    were equal without either providing a Regen warning or
    forcing a Regen, if a model space viewport was partly off
    screen and thus clipped. This has been fixed; a REGEN_WARNING
    is now issued.

  * Changed the name of the floating-point emulation version of
    the High C library to p386elib.lib, restored the in-line
    80287 p386lib.lib version of the library, renamed p386.pro to
    padi.pro and added an #ifdef on ADIEM, a tag that is defined
    on the High C command line if floating-point emulation is
    desired.

  * Changed some code in libraries p386elib.lib and p386lib.lib so that 
    attempts to exit to DOS go through the High C exit code, without
    closing the standard file handles or returning to DOS--you
    return to AutoCAD instead. A change in the link command line for P386
    ADI drivers was required for this to work: the -lib option must come 
    AFTER our library and before High C's.

  * AutoShade examines the rfunc member on return from each rendering 
    configuration call to a P386 driver. If the driver returns 0 in rfunc,
    AutoShade responds by terminating. This allows AutoShade to respond to
    a <Ctrl-C> during configuration. The sample HP PaintJet(R) rendering
    hardcopy driver (RDPPJ) was been modified to do this.

  * The default interrupt vector for real-mode rendering hardcopy drivers
    for AutoShade Version 2 was changed from 7ah to 7ch.


E.2.1.1 AutoCAD Release 11 Third Restricted Release (September 1990)
---------------------------------------------------------------------

  * Corrected an AutoShade bug that sent 24-bit colors in the
    wrong order (RGB instead of the documented BGR).

  * AutoShade V2 does contrast stretching for continuous tone drivers, 
    unlike earlier versions. RDCRANGE.rstretch is therefore always set to
    FALSE.

  * Corrected an error in scalepoly() in both sample EGA/VGA
    drivers (dsega41f and dspega41) which caused filled polygons
    to be clipped incorrectly, thus wiping out the upper and
    right-hand viewport borders. The viewport border is one pixel
    outside the clipping area of the viewport in MSPACE.

  * Scan-line ranges for Quickshade were one greater than they should have
    been and were corrected to the range from 0 to (ydots-1). Replay
    of TIFF files did not output the last scanline of the image. This
    was corrected in AutoShade 1.5.61. 

  * Added an alternative #define, PPLOTTER, equivalent to NOPENS, in plp.h.

  * Autodesk RenderMan does not issue RDCLEAR after RDSTART. If
    Merge is not turned on, it sends two polygons to "clear"
    the area to be rendered, which might be less than the full page
    or screen. If Merge is turned on by the user, Autodesk RenderMan
    expects to be able to merge a new rendering with existing imagery
    on screen.


E.2.1.2 AutoCAD Release 11 Second Restricted Release (July 1990)
-----------------------------------------------------------------

  * dgpsummi.c was modified to have a single entry point for both
    configuration and execution. A new assembly module, dguface,
    replaced dgpface for this driver.

  * The PPTEXT packet was removed and its functionality was handled inside
    the PTEXT packet as the TAPIXEL attribute. The old TRANSPARENT
    attribute in the PTEXT packet was renamed TAXPARENT.

  * CF_STUDIO, a flag in the PINIT packet, was added to indicate the product.

  * Changed how DRAGG mode works for P386 digitizers. Added P_OUT, 
    P_POINTUP, and P_BUTTPUP.

  * DRV_RC drivers are required for Autodesk 3D Studio display and
    rendering (they don't support animation).

  * P386 ADI digitizers with DRAGG mode support are required for
    Autodesk 3D Studio.

  * A correction was made in the sample drivers dsega41f and
    dspega41. The sample code was incorrectly computing wixdots,
    wiydots, vxdots, and vydots as zero-based values instead of
    true pixel counts. Several similar bugs inside AutoCAD core
    were also corrected. Be sure to look at sample code
    dated on or after 8/20/90 for this correction.

  * Added flag bits RF_SLRENDER and RF_SLDISPLAY in the RDRSLINE and
    RDWSLINE packets to indicate where scan-line data is to be read from.

  * Added flags member to RDCMAP and RDRCMAP and defined new flag bits
    RF_CMREND and RF_CMDISP to indicate which color map should be
    returned in a RDRCMAP request for a single-screen DRV_RC driver.


E.2.1.3 AutoShade 2.0 First Restricted Release (June, 1990)
-----------------------------------------------------------

  * The dispatcher function eos() was replaced by nultrm().

  * Changed RF_DISP1 to RF_MAPPEDPAL and changed RF_DISP2 to RF_BRESENHAM
    in RDINIT.

  * Added hpgl2-s, an HPGL2 sample driver with AutoSketch support.

  * Added DGPWA, a new WACOM pressure-sensitive tablet driver.

  * Added ADI revision level to sign-on banners of real-mode
    sample drivers, made sure that they all silently ignored
    unrecognized packets if compiled without the DEBUG option.

  * Added serial port reinitialization after Shell commands for DGPSUMI.

  * Fixed the time-out in ppsend() to make it about 5 seconds (it
    was too short) and enhanced ppsend() to enable it to do file output.

  * Corrected the "version" sent in PINIT to 6 so that ADI 4.1
    drivers running under the ADI 4.0 menu pick would know they
    were talking to an old generic driver that acted like
    AutoCAD Release 10. The ADI 4.1 menu pick still sends
    version as 7 to correctly identify ADI 4.1 display support.

  * Changed core code to remember if a <Ctrl-C> interrupted a
    redraw that sends a fresh display list to a BS driver,
    forcing a redraw of every viewport by AutoCAD (sending fresh
    vector lists) on the next user REDRAW.

  * Added support for HP LaserJet III in the HPGL2 sample driver.


E.2.1.4 AutoCAD Release 11 First Restricted Release (May 1990)
---------------------------------------------------------------

  * An early version of the sample PaintJet(R) rendering hardcopy driver
    was shipped in error. It did not correctly handle scan-line data by
    failing to support xrpt.

  * Changed the definition of DEV_RC from 0x100 to 0x60.

  * The QPLOT packet was deprecated.

  * AutoCAD started to ignore the 4 least significant bits of the ADI
    version level.

  * Added dispatcher functions ppsend() and usrbrk().


E.3 Known Bugs
==============

This section provides descriptions of some bugs that were significant
for ADI developers in the past.


E.3.1 Cursor Alignment Problems With AutoCAD
==========================================

AutoCAD Release 10 has had some pixel-off-by-one problems
with both internal drivers and ADI drivers. The most obvious example
of these has been an intermittent failure of the crosshair
cursor to align exactly with a rubber-band line when Snap is off.
This bug was caused by a lack of symmetry in transforming from
pixel to logical to floating-point spaces and back, inside
AutoCAD.

To prevent cursor misalignment problems, the
mechanisms to transform points between pixel coordinates and
logical (32K space) coordinates and double precision (drawing
file) coordinates have been reworked. The essence of the change
is that when points are transformed from a lower-precision space
to a higher-precision space (i.e. pixel->logical->drawing), the
value is targeted for the center of the lower-precision element.
Previously we targeted the lower-left corner. And when the points
are transformed from higher-precision to lower-precision spaces
(i.e. drawing->logical->pixel), the fractional portion of the
transformed values is truncated.

In the simple case where a Regen has just been performed, and
the logical pixels are considerably smaller than physical pixels,
the cursor now appears to be very well-behaved. However, when
zoomed in to the point where logical and physical pixels are
nearly the same size, the misalignment returns.

We allow a Zoom to go in until logical and physical pixels
become equal. If they are equal, there won't be problems with
misalignment. If logical pixels are smaller than one-half the size of
physical pixels, shouldn't be alignment problems. But
if you allow a Zoom in the range between these two values, there
probably will be alignment problems. You may want to enforce a
limit in your driver to make this Zoom range forbidden.

If your ADI driver has been compensating for our previous method
of transforming between spaces, you may need to modify the driver
to avoid new pixel-off-by-one problems.

A second class of problems happens in some ADI drivers that use
a different transform algorithm from logical to pixel coordinates
than AutoCAD uses internally. The Release 12 "everything logical"
feature solves this problem by consistently supplying everything
in a single consistent coordinate system on a viewport-by-viewport
basis.

Meanwhile, the transform used by AutoCAD core code for logical to
physical conversions is in the iclip() procedure in the assembly
language part of the sample EGA/VGA driver. For AutoCAD 386, this
module is dspgaa41.asm. For real-mode ADI it is dsegaa41.asm.

The scaling computation in iclip() has been changed in Release 11
AutoCAD 386 to use 32-bit arithmetic. The real- and protected-mode
display list sample drivers have recently been updated to use the
same routines. Older drivers that use the iclip() code from
AutoCAD Release 10 will experience cyclic pixel-off-by-one errors
due to rounding errors.


E.3.2 AutoCAD 386
-----------------

There was a bug in the AutoCAD 386 handling of PSYNC for P386
drivers. Use of SY_HILITE to request fresh nondrawing vectors
sometimes resulted in bogus vectors or polygons. The bug has been
fixed in release 10 c10a and in release 11.

Several bugs in AutoCAD Release 10 c2 were
corrected in Release 10 c7 and in AutoCAD 386. If a driver
contained work-arounds for these bugs, it would be broken for both
release 10 c7 and AutoCAD 386. Following is a list of the
release 10 c2 bugs that were fixed:

   * In the first few thousand AutoCAD Release 10s that
     shipped, if a BS driver did smart fills, filled solids in
     slides were incorrectly tagged as viewport-specific but
     scaled with pixel scaling, resulting in a filled solid
     appearing in the lower-left corner of the slide.

   * More recently it was discovered that BS drivers which do
     smart fills will experience a similar problem of mis-scaled
     solids in Dview, resulting in the filled solids appearing in
     the lower-left corner of the screen.

   * Drivers that implement smart dragging and color XOR
     run into trouble if their drag display list overflows while
     dragging a multicolored shape. Core code fails to send the
     correct color vectors to erase the drag image, resulting in
     garbage left on screen. BS drivers show a displaced
     screen image and incorrectly draw vectors after a Plot
     command.

   * Highlighting of filled polygons for BS drivers that
     implement PFILL: draw a filled solid, split into 4
     viewports. Zoom one viewport .25x to make it the master of
     the others. Select a slave and select the filled solid for
     erasure (this should highlight it).

   * AutoCAD sends a highlighted nondrawing solid to the MASTER
     viewport instead of to the slave. This is inconsistent with
     the handling of BS nondrawing vectors in PVEC, where we
     explicitly say the nondrawing vectors should never be copied
     from master to slave; each is sent its own vectors.


E.3.3 Autodesk 3D Studio Version 1.0
------------------------------------

All of the items below are either questions or bug reports for
Autodesk 3D Studio V1.0 as of December 17, 1990.

   * Commenting out everything in dsadicfg1() causes a crash.

     Answer: The driver MUST set the PNEWCFG field "preclen" to a
     number from 1 to 100. If the user does not set this field,
     a random number is left there. If the field
     value is out-of-bounds, the program may crash. If the
     driver doesn't want to use this packet, then set the "preclen"
     field to 1.  This also applies to RPNEWCFG.

     The configuration record mechanism in Autodesk 3D Studio is broken, 
     and will only take from 1 to slightly more than 100-byte
     configuration records.

   * "Do nothing" scanlines are drawn just before the
     rendering is displayed. RDWSLINE is called at the same
     Y valued for a fairly long time with the same scan-line
     value.

     Answer: True, this is an irritating error, especially for
     higher-resolution screens. This was meant to clear the screen;
     it is a leftover from attaching ADI to the rendering screen and
     was not readily noticeable at development time.

   * Drivers are reloaded between edit screens and the rendering
     screen.

     Answer:  True.

   * Returning to the materials editor, the top status line is
     not complete--it is done in chunks; if the cursor is moved
     slightly, a second PBOXCLR is called to finish the remaining
     portion.  This happens with higher resolutions, like
     1024-by-768 and higher.

     Answer: The materials editor has this bug.

   * For boards without color palettes, RDCMAP, RDCMAPB, and
     RDCMAPE are called to update the display.

     Answer: True. This can be messy for true color boards. But
     the regions affected are small.

   * In the materials editor at high resolution (we noted at 1024-by-768
     or 1280-by-1024) when dragging the vertical lines inside the
     slider bar, RDWSLINE calls are being made to restore the
     background under the vertical drag bar. However, the drag
     bar coords are given 1 pixel too low, so a white track is
     left under the bar. We can't be doing PLINE (function 32)
     wrong since every other line lines up correctly and when
     watched through RDWSLINE and PLINE, the coordinates do not agree.

     Answer:  This is a bug


   * PNEWCFG, RPNEWCFG. Both of these packets pass their configuration record
     to the DEV_RC. According to the ADI 4.1 specification,
     the driver is allowed up to 489 bytes for each
     configuration. Autodesk 3D Studio crashes internally when a driver
     uses about 200 bytes or more. Our configuration record is
     380 bytes, so we cannot use Autodesk 3D Studio to store our
     configuration.

     Note: The 3DADI.CFG initially is 334 bytes long, regardless
     of the size of the configuration record passed back by the
     driver.

     Answer: True. Use between 1 and 100 bytes, or write your own file.

   * PNEWCFG, RPNEWCFG. According to ADI 4.1, both of these
     packets are OPTIONAL. If a driver chooses to ignore them,
     Autodesk 3D Studio crashes internally from a memory protection fault,
     after writing a 1.2 MB 3dadi.tmp file.

     Note: Autodesk 3D Studio sets the length field ("preclen") to an
     invalid length before calling the driver.

     Answer: You must set the "preclen" field in the PNEWCFG and
     RPNEWCFG packets to 1 if you are not going to use the config record.

   * Why is the DEV_RC driver initialized three
     times before Autodesk 3D Studio is running? I can see the
     reason for two loaded during configuration, but once the
     3dadi.cfg file has been built, there is no reason to send
     the PINIT packet more than once. The multiple initializations
     are highly noticeable in the higher resolution modes,
     where initializing the graphics system multiple
     times takes longer.

     Answer:  True. There are multiple loadings.

   * During the initial configuration of Autodesk 3D Studio, both PNEWCFG
     and RPNEWCFG are sent. Upon choosing renderer, setup ...,
     configure, choose RCPADI, and then render; the RPNEWCFG
     packet is re-sent! Has Autodesk 3D Studio forgotten that the RCPADI
     device was previously configured? Also, why is the default
     renderer device set to RCPADI when a DEV_RC is operating?

     Answer: Autodesk 3D Studio loads multiple video drivers.

   * There is no way to find out the product type. Is it
     possible to add a config field inside RDINIT similar to
     PINIT?

     Answer: A new ADI packet will address this issue
     in a future release.

   * In the display portion of Autodesk 3D Studio, calls to RDCMAP are
     made. By printf()'s I've found the value to range between 0-63.
     Hence, I am using this value to scale the RGB data for my DAC.
     Will this change or remain the same in the future?

     Answer: Not yet decided.

Following are some Autodesk 3D Studio potential problems that are not yet
verified and are currently being analyzed.

   * If the rendering device has been set to RDPADI, a call is
     made to RDSTART when the Materials Editor is selected. This
     leaves the screen in rendering mode. However, if Autodesk 3D
     Studio is running in single-screen mode (i.e., VGA), the
     rest of the screen is not visible anymore, forcing you to
     run Autodesk 3D Studio in dual-screen mode.

   * Assume that RCPADI is defined and chosen in the set procedure as the
     rendering device, and the MAIN-DISPLAY and MATERIAL-DISPLAY (in
     3ds.set) are set to VGA. Then render an image or view (select
     RENDER). As soon as the rendering is
     completed, the program waits for a mouse button click to
     switch back to the display screen. If RDPADI is chosen in
     SETUP under RENDER and then the above procedure performed,
     the program switches back to display without waiting for the
     user. This happens in single-screen mode.

   * Autodesk 3D Studio never sets the bit RF_REDRAWSCR and allows no
     possible way to do that. I can set it up myself, but
     this breaks other cases. This means that if our
     board is running single screen with a VGA, I cannot run
     combined display/rendering driver and switch properly back
     to the VGA display when done.

   * There is no way to instruct inside Autodesk 3D Studio whether the
     displays share screens or not (like Shade). Therefore,
     on rendering, a dialogue box is left on screen that is
     subsequently covered with RDWSLINE calls. RDSTART does
     not clear the screen, but simply switches to it.

   * There is no way from inside Autodesk 3D Studio to indicate
     whether the displays share screens, as you can from
     AutoShade. Therefore, on rendering, a dialogue box is left on screen
     that is subsequently covered with RDWSLINE calls. RDSTART does
     not clear the screen, it simply switches to it.


E.4 ADI Questions and Answers
=============================

Following are some questions and answers from developers accumulated from
conversations, forums, and conferences.

E.4.1 March 1992 Developer Days Road Tour
-----------------------------------------

  * How do you merge configurations between the driver and products if you
    are dealing with several different products and revision levels?

    For AutoCAD Release 12 and 3D Studio v2.0, the PWHO packet will let you
    know who is asking to configure. Your driver should be able to do its
    configuration inside the product's configuration process.
    New Autodesk products should be capable of merged configurations.
    
    For older products, if you feel you can't merge your configuration with
    the product's, you can provide a stand-alone program. If a product
    starts sending configuration packets without PWHO, you can put up a
    message asking the user to run the stand-alone configuration program.


  * Will display lists work in AutoCAD paperspace?

    No.

  * Can the UCS icon be uniquely identified by the nondrawing vector
    tagging?

    No, we lump several types of icon in DR_ICON.


  * There are flags in RDINIT and RD_INFO that can recognize several
    types of rendering devices:

    RF_HARDCOPY         renders to paper
    RI_RENDERER         renders to a video screen
    RF_FILEOUTPUT       renders to a bitmap file
    RI_BITMAP           handles bitmap files (in or out)
    RI_FILM_RECORDER    renders to film

    The idea is to let the controlling product know what your output medium
    is. Some drivers may do more than one of these, for example, RI_RENDERER
    and RF_FILEOUTPUT for a device that renders to a file and a video screen
    at the same time.

  * Can 15/32-bit Regen change during execution time?

    No. Your driver should ask the user at configuration time, then report to
    AutoCAD in PINIT at the beginning of execution.

  * Do the nondrawing vector ID tags apply to PFILL (e.g., DR_ICON)?

    No.

  * Is there a limit on nested PBIGBLIT or PBOXPUSH/PBOXPOP packets?

    No. Your driver should always be prepared to resort to virtual memory
    or disk if on-board memory runs out.


  * Is there any way to cache plot preview?

    No. It is a Regen.

  * Is rasterin done with ADI?

    No, it is an ADS application. Each pixel is represented by an AutoCAD
    SOLID entity.

  * Is it possible to change the cursor presented in programmable dialogue
    boxes in AutoCAD 386?

    You can use the PMARK/PCMARK, PDCURS/PCDCURS packets (on DOS) to draw
    and erase the arrow cursor (cursel == 10). This allows ADI display
    drivers to use their raster cursor instead of the vector cursor.

  * How can you find out the view center and height?

    There are several ways to do this. Perhaps the simplest is to
    use PSTRING to send the inquiry and then trap the response in PWRSPLIT.
    You could also write LISP or ADS routines to find out and then tell you
    by a private communication channel.

    Another alternative requires that you run a BS or FAKE_BS
    driver. This way you see the POPENVP, PLOPEN, and PVIEWPORT
    packets and you know where in floating-point space the logical
    space is, and where in logical space the current viewport's view is.

    Using the conventions in our sample display list drivers (which
    store most of this information in a vpinfo[] structure, you can either
    simply compute the center of the viewport from its floating-point
    corners this way:

    centerx = vpinfo[i].rxl + (0.5 * (vpinfo[i].rhx - vpinfo[i].rxl));
    centery = vpinfo[i].ryl + (0.5 * (vpinfo[i].ryh - vpinfo[i].ryl));

    Or, to mimic the computations done in core, you can do
    the following:

    1) Compute the viewport aspect ratio:
    
        real wdsar;
        real dsar;     /* aspect ratio reported in PINIT or PDINFO */

        wdsar = dsar *
            (((real) vpinfo[i].wixdots / (ixdots + 1)) /
             ((real) vpinfo[i].wiydots / (iydots + 1)));


    2) Find the largest viewport dimension, using the floating-point 
       corners of the viewport:

        size = fmax((vpinfo[i].rxh -vpinfo[i].rxl) / wdsar, 
                (vpinfo[i].ryh - vpinfo[i].ryl));

    3) Find the center of the clipped viewport:

        centerx = vpinfo[i].rxl + wdsar * size * 0.5;
        centery = vpinfo[i].ryl + size * 0.5;

        If TILEMODE = 0 and the viewport in question is clipped (partly
        off screen), there is no easy way to make this computation.

  * We are looking into TEE drivers that allocate more heap space; this
    should be resolved when we send out ADI 4.2 TEE drivers.

  * Can you run a plotter from ADS?

    Yes. The command function lets you do this.

  * Why doesn't PMARK supply 3D information for drawing cursor types other
    than 0 and 3, such as nonortho 3D cursors?

    In ADI 4.2, we come close to this. You should get
    a PMARK that tells you the cursor type; the nondrawing vectors
    will follow shortly thereafter, tagged with DR_CURSOR.

  * Under ADI 4.0 in AutoCAD Release 10, if status 4 was returned while
    handling PDIGTIZE, AutoCAD sent a PSTRING packet. In ADI 4.1 (AutoCAD
    Release 11), this no longer happens--we must return status 0, 
    followed by status 4, to get a PSTRING. This causes cursor flickering.
    Is anything being done to address this?

    Extensive improvements were made to PDIGTIZE and PDIGTIZE_42 in AutoCAD
    Release 12, but it was determined that inserting PSTRING calls to handle
    this behavior was not desirable.

  * What is the default palette for plotters?

    The default AutoCAD palette is defined in apalette.h. This is 8-bit RGB
    data, suitable for video displays. You might need to transform it for the
    color model used by your plotter.

  * How can the plotter time-out be modified?

    The ADI 4.2 dispatcher function setpltmout() lets drivers modify the
    time-out value for ppsend().

  * Some developers want to write their own malloc(), and would like to
    modify the initializer. Is the initializer source code available?

    We don't provide the initializer source code because it
    is based on code owned by the compiler vendor.

  * Will there be foreign language support for TESTKIT?

    No plans exist for providing special foreign language versions of
    TESTKIT. TESTKIT can send any packet, including PLANG.
    If you do send PLANG, you have to provide the product-side
    services associated with it.

  * Does the Kanji version of AutoCAD provide support for English commands?

    Yes. The _command in English will work, as far as we know.

  * Will "standard" message file formats (for translation) be added to ADI?

    Not in ADI 4.2.

  * Will VMM-based ADI drivers for AutoCAD Release 11 break under DPMI-
    compliant applications such as AutoCAD Release 12?

    It depends on whether AutoCAD is privileged or not (the user can change
    this with the Phar Lap cfig386 utility). Old drivers (especially display
    drivers) used hard-coded segment selectors (such as 0x1c and 0x34) that
    are valid only if AutoCAD is privileged.

    The DPMI issue is slightly different. As long as a DPMI server (e.g.,
    Windows) is not running, AutoCAD linked with Phar Lap 4.1 will still
    operate with VCPI. If a DPMI server is present and AutoCAD
    is unprivileged, DPMI services replace VCPI.

  * Does STAT_UNSTABLE read as 0/1 (on/off) or is it only sent when AutoCAD
    is in an unstable state?

    Every PSTRING packet contains the status values that were current when 
    it was sent. These are not "bookend" packets.

  * Does AVE Render support a vertical scan-line capability for hardcopy
    output?  What about support for image rotation?

    AVE Render does not have vertical scan-line support.

    While there is not image rotation support in AVE Render, you can rotate
    the camera in AutoCAD to get the effect of a rotated view, and you can
    change the shape of the viewport you render into (e.g., make it tall
    and slender).

    Most rendering drivers have to use virtual memory to
    allocate space for a complete bitmap image. Once that has been
    done, the driver can scan it vertically to rotate the image. The sample
    PaintJet driver does this. Asking AVE Render to produce "ordered" scan
    lines is not a good choice--it just sends tiny polygons
    instead of scanlines.

  * Is the 32-bit vector data sent signed or unsigned?

    Signed, always positive.

  * What AutoCAD editing session functions result in PFILL packets
    being sent to a plotter?

    If FILL is on, Donuts, Traces, Polylines, and Solids will cause PFILL
    packets to be sent to a plotter.

  * Is it possible for plotter drivers obtain the PCP filename through a
    dispatcher function or some other mechanism, or move the location of
    the plotter configuration data from acad.cfg so the driver can parse
    plotter-specific data?

    There is no dispatcher service function for this. In making this design
    decision, we concluded that the 50 bytes of data (in acad.cfg) were
    device specific. AutoCAD saves a separate 50 bytes of data for every
    different plotter configuration.

    However, the PCP file is more drawing specific, and somewhat less
    device specific. By keeping the 50 bytes of device-specific data out
    of the PCP file, we made it easier to save a PCP file from one device
    and use it to configure a second device. That is, you can copy a PCP
    file, renaming the copy, and edit it with an ASCII editor to modify it
    for the second (different but somewhat similar) device. If binary
    device-specific data were part of the PCP file, this would be harder
    to do (you would have to delete the binary data, and then trick the
    new device into storing its binary data). Similarly, we don't include
    I/O port configuration data in the PCP file.
    
  * Will pattern fill support be implemented for hardcopy devices in ADI?

    Not in ADI 4.2.

  * Why do DEV_RC drivers receive RDLANG packets?  Does this mean that
    DEV_RC devices must support text in rendering mode?

    RDLANG is sent to drivers (e.g., DEV_RD, DEV_RH or DEV_RC) that might
    be loaded by AVE Render directly. This is useful at configuration time
    so the language and code page being used are known for configuration
    questions on the text screen. This is useful at execution time if you
    use RDFNAME to ask AVE Render to put up a file dialogue
    box (you supply prompt strings in RDFNAME that AVE Render puts into the
    dialogue box).

    Your driver is not expected to put text on the rendering screen.

  * How does AutoCAD handle overlapping fills and plotter optimization?

    AutoCAD doesn't do anything about overlapping fills or plotter 
    optimization when using PLFILL. When AutoCAD sends
    vectors, the overlapping vector optimization code remains essentially
    unchanged since AutoCAD Release 11.

  * Will PMODELINE truncate characters greater than the number of 
    characters set in PINIT for mode and status lines?

    ADI drivers have always been responsible for clipping PCOORDLINE 
    strings to fit the status line. AutoCAD core code will clip PMODELINE
    text to the length your driver returns in PINIT.modelinel. It is a good
    idea to set modelinel a couple of characters before the place where
    you start PCOORDLINE printing, to allow some space between them.

  * What vectors should a developer avoid in working with Phar Lap tools?

    Don't install your own alternate page fault handler with INT 21h Func
    2522h, since we install one in AutoCAD.  We also install our own
    out-of-swap-space handler (INT 21h Func 2523h).

    Another couple of vectors (functions) to avoid are INT 21h Func 2509h 
    and INT 21h Func 250A, since they have limited support under Windows. 
    The pharlap.386 Windows driver must be installed. 

    The 2509h call will succeed only for linear addresses that fall within
    the REALBREAK part of a segment. The returned value is NOT a physical 
    address, but rather an internal 386|DOS-Extender handle. When passed to 
    the 250Ah call, the REALBREAK pages will be mapped to the end of the
    segment specified in the 250Ah call.

    It is safest to use only facilities that have previously worked
    in AutoCAD Releases 10 and 11. However, with AutoCAD Release 12
    you need to observe caveats in Phar Lap documentation
    about using 386|DOS-Extender system calls in the Windows environment.
    
    If "vectors" refers to the Phar Lap hard-coded vectors used to
    point to areas like the system environment or the display frame buffer,
    the questionable area here is whether these vectors can be used
    under Windows. The best answers to these questions are provided
    by Phar Lap 4.0/4.1 documentation.

  * Will an ADI 4.2 driver work with AutoCAD Release 11?

    Only if it is carefully written to do so. Some of our sample drivers
    have this extra code, some do not. We'll document
    good examples of downward compatibility once they are completed.

  * What AutoCAD functions (i.e., cascading menus, scroll bars, etc.) 
    utilize DRAGG mode?

    DRAGG mode is used by dialogue boxes (edit fields, list-box 
    scroll bars and auto-scrolling), pull-down menus, and by the DRAGDOWN
    method of crossing/window object selection.

  * Will there be a combined plotter and rendering hardcopy ADI 
    specification?

    Not for AutoCAD Release 12.

  * Can the user change "standard" paper
    sizes (A-E, A0-A4, etc.) for the Plot Image areas?

    Several user sizes are supplied instead.

  * Is it possible to provide a switch to tell AutoShade, RenderMan, or AVE
    Render to pass pixels in column major order? The number of pixels 
    involved with large format plotters makes it unfeasible to transpose
    the pixel image matrix. This is related to the request for AVE Render
    to work in a paperspace viewport. Ideally, we want the user to be able
    to plot what they see on the display.

    Not in AutoCAD Release 12.

  * A problem occurs during batch mode plotting: if AutoCAD times
    out on a port, the remaining vectors and polygons are discarded. What
    can be done about this?

    We have added a dispatcher function in ADI 4.2, setpltmout(), that 
    allows an ADI driver to set the time-out duration for ppsend().

  * Will an ADI plotter packet be added to define fill patterns for
    polygons and wide lines?

    Not in AutoCAD Release 12.



E.5 Resolved Bugs Since the Q021 Restricted Release
===================================================

Following is a list of driver-related bugs resolved since the
Q021 restricted release of AutoCAD Release 12:

* Full screen rendering now works in AVE Render.

* RDCPOLY coordinates have been changed to the correct coordinate system.

* RDWHO sent before RPCFGREC now has all fields initialized.

* AutoCAD 386 Release 12 now uses the raster cursor for dialogues if
  the ADI driver supports it.

* 3D Studio v2.0 now works properly with a DEV_RC driver that supports true
  color.

* Pixel scaled polygons being sent through PBFILL to BIGVEC drivers was
  corrected.

* The display driver is completely reinitialized after a change in font
  size or resolution after Config or Reinit, correcting numerous problems.


* Corrected RDRSLINE for large scanlines basing bytes-per-pixel on the
  last RDWSLINE call.

* Corrected an initial RDEND call for Replay TGA.

* Corrected RDCPOLY, which had the wrong offset applied to coordinates for
  rendering in a viewport.


E.6 Resolved Bugs Since the Q033 Restricted Release
===================================================

Following is a list of driver-related bugs resolved since the
Q033 restricted release of AutoCAD Release 12:

* Open viewports were not always closed before PKILL. 

* AVE Render failed to terminate and reload drivers on reconfiguration. 

* INT 3 caused a crash with no debugger loaded. The 386|DOS-Extender v4.1
  has been modified to stub off INT 3 (as it was in earlier DOS Extenders).

* plseek(), pltell() and plflush() have been hooked up to work for 
  rhsend().

* PDIGTIZE_42 was totally confused if a pre-ADI 4.2 digitizer was
  configured.

* struct plbxplotcfg.pl_szlab[5] was mistakenly changed to a 9-byte array,
  breaking compatibility with ADI 4.1. This has been corrected.


E.7 Frequent Errors in ADI 4.2 DEV_RC Drivers
=============================================

Following is a list of frequent errors in ADI 4.2 DEV_RC drivers:

* Failure to fully support PPAL.

* Failure to understand the distinction between display mode capability
  packets (PINIT, PDINFO) and rendering mode capability packets (RDINIT, 
  RD_INFO). Rendering in a viewport is not rendering mode!

* Failure to support \t, \b, \r, and \n properly in PCHAR, PMODELINE,
  PCOORDLINE, and PWRSPLIT.

* Lack of a good presence test for supported display; failure to report the
  error in PINIT.pstat properly; failure to be in text mode on failure.

* Failure to support RDRCMAP from default AutoCAD display palette.

* Failure to gracefully handle the transition from TEXT mode
  to RENDERING mode. AVE Render can be started by scripts and commands
  typed on the text screen. Note that if RDSTART is issued while in text
  mode, RDEND should lead back to text mode.

* Exiting to DOS on receipt of PKILL. This doesn't let AutoCAD
  save the user's drawing.