Basic 8 Manual Errata Manual Corrections page 77 @CYLNDER,X,Y,RADIUS,HALFLEN,VIEW radius=1-127 page 100 @SCLIP,left,right,down,up radius is from 1-127 page 107 @SPHERE,X,Y,Radius radius=1-127 page 108 @SPOOL,X,Y,INNER RADIUS,OUTER RADIUS,VIEW radius=1-127 page 115 @TOROID,X,Y,INSIDE RADIUS,OUTSIDE RAD1US,VIEW radius 1-127 @LOGO PARANETER CHANGES FOR USE WITH @STRUCT/@SDAT/@SEND You DO NOT follow the parameters with a string of characters. Instead follow the parameters with a series of numbers that are the ASCII equivilent of the characters. For example, if your letters are "abc" you would send the following parameters after the Length parameter;,65,66,67. This will create the logo string "abc". Also, while there are no required parameters for LOGO types, you must still follow the @STRUCT command with a @SDAT on a line by itself. For example; @STRUCT,5,2,1,AD @SDAT @SDAT,l,254,0,0,0,1,1,2,3,65,66,67 @SDAT,0 @SEND This creates the LOGO string "abc". Basic 8.0 The Enhanced Graphics System For The C128 Developed by LR Wallace, DP Darus WALRUSOFT March 19, 1987 (C) 1986 WALRUSOFT ---------------------------------------------------------- Dear Valued Customer, Thank you for purchasing Basic 8 with Basic Paint. Basic Paint was created using Basic 8 and has been included with the package as an added bonus to show what can be accomplished with Basic 8. Also included is an Icon based, Desk-top utility which enables you to access your Basic 8 programs quickly and conveniently. We think you will find Basic 8 to be one of the most sophisticated and powerful software packages available for the C-l28. It breaks new ground in unleashing hidden graphic capabilities rivaling those of l6-Bit Computers! Your purchase enables us to continue to offer software of the highest quality to users of the Commodore 64 and 128. Patech Software is founded on Three Basic Principles: 1. To offer the best quality software at a fair price. (One which accurately reflects its true value to the user.) 2. To offer realistic and usable support to each Registered user after purchase, to ensure that he gets full value from the software. 3. To Present the software in its original state, without copy-protection of any kind! This enables you to make back-ups for your convenience and the protection of your investment (as well as your equipment!). You put your trust in Patech when you purchased Basic 8. In turn, we are putting our trust in you to help ensure that we are fairly compen- sated for our software. Only through this mutual trust can we continue to serve your software needs. Please don't force us to add copy protection to our software. That would only hurt both of us! Patech is a very open company. If you have any questions, comments or suggestions, please write to us. We will do our best to respond promptly. If you have written any programs (with or without the aid of Basic 8) which you think have merit, or if you have an idea for one which you think fills a genuine need, please contact us. We are always interested in good programs and ideas. Who knows, you may just become the newest member of the Patech Software Development Team! To keep fully informed of future products and updates; and to become a Registered User, please mail the enclosed Registration Card. Whenever you contact us for support, please reference the Serial Number printed on the card. (Make a record of the number before you mail the card!) I hope you find that Basic 8 fulfills your expectations. Thanks again for your support. Sincerely, Paresh Patel, President Patech Software, Inc. P.O. Box 5208 Somerset, NJ 08873 (1) TABLE OF CONTENTS Page TABLE OF CONTENTS 1 HARDWARE REQUIREMENTS 2 MAKING BACKUPS 3 PHILOSOPHY 4 FOREWORD 6 1. INTRODUCTION 8 1.1 COMMAND SUMMARY 12 1.2 STARTING BASIC 8.0 13 2. SCREENS AND MODES 14 3. DRAWING COMMANDS 20 4. THREE DIMENSIONAL GRAPHICS 25 5. MEMORY MANAGEMENT 31 5.1 BUFFERS 31 5.2 STRUCTURES 32 A. Saving and recalling STRUCTURES 33 B. Patterns 35 C. Logo 36 D. Character Font 36 E. Brush 37 6. Exotic Commands 38 7. Making A Distributable Disk - The Run Time System 42 8. BASIC PAINT 44 9. WIOS WORKBENCH And Other Supplied Utilities 62 10. Basic 8.0 COMMAND ENCLYOPEDIA 65 11. Printer Drivers 122 Appendix A: The 8563 VIDEO CHIP - Ram Expansion 173 Appendix B: VIDEO RAM MEMORY MAPS (MODE's 0-3) 175 Appendix C: C128 Basic 8.0 MEMORY MAP 177 Appendix D: File Formats, Naming Conventions 179 Appendix E: Data Compression Algorithms 185 Appendix F: Other Suggested Standards 187 The Players 188 (2) Required Equipment Commodore C128 (or C128D) Computer in C128 80 column Mode only At Least 1 disk drive (154l, 1571, 1581 and compatibles) RGB Monitor Supported Hardware Options External RAM Expansion Model 1700 128K RAM cartridge, or Model 1750 512K RAM cartridge Internal 64K RAM Expansion for the 8563 Video Display Chip (New C128D model comes with the 64K already built in.) Model 1351 Proportional Mouse Standard Joystick Dot Matrix Printers (See Chapter 11 for specific printers) (3) MAKING BACKUPS OF YOUR BASIC 8.0 DISK Even though it is copyrighted, your BASIC 8.0 disk is not copyprotected. In fact, it comes with a built in backup facility. The original disk you buy is not meant to be used for work. The first time you boot the disk, have three formatted blank disks ready. Put the original BASIC 8.0 disk into the drive and either turn on the computer or press the reset button (if the computer is already on). You vill be prompted with a menu which has three choices. These menu options allow you to make a BASIC 8.O Work Disk, a BASIC PAINT Work Disk or a BASIC 8.0 RunTime Disk. You should make one of each, then put the original BASIC 8.0 System Disk away, where it will be safe. Use it at another time to make additional work disks or runtime disks. Of course, you can also use your favorite disk copy program to back up your work disks and runtime disks. The BASIC 8.O Work Disk is for writing and editing your BASIC 8.0 programs. You may not give this disk away! Make a backup of this disk, and work from your backup work disk. This disk contains the complete BASIC 8.0 editor system, and is the disk you will use for creating your own BASIC 8.0 programs. To use this disk, just put it in the drive and boot the computer. The BASIC 8.0 system will load and become initialized. You may then write programs, run them and save them as you normally would. The difference lies in the many new BASIC 8.O commands available. The BASIC PAINT Work Disk contains the included 80 column color paint program, as well as menus, fonts and requestors. It is a RunTime Program, meaning it contains only the runtime library, not the editor. You cannot edit or list the program, (4) and you cannot sell or give it away. The BASIC PAINT disk is also an autoboot disk. Just plug in a 1351 mouse into port one or a joystick into port two and boot the disk. You will be presented with a series of menus and requestors that allow you to configure the program to your system. The BASIC 8.0 RunTime Disk is the only legal way to sell or give away programs you have written with BASIC 8.0. It contains the RunTime Library, which is a program that allows BASIC 8.0 programs to run, but not edited or listed. This disk also contains the WORKBENCH program, which is simply a BASIC 8.0 program that allows you to use a mouse to load and run BASIC 8.0 programs. This disk too is a autoboot disk. It will load and activate the RunTime Library, and then it loads and runs the WIOS WORKBENCH. You can put your own programs and their required files on this disk, where they can be loaded by pointing the mouse and selecting them with the mouse buttons. Or you can alter the booting sequence of the RunTime Disk in order to directly load and run your program. See Chapter Seven for details. OUR PHILOSOPHY ON SOFTWARE COPY PROTECTION We made a very deliberate decision to not put any type of copy protection on the disk, so you could easily make working disks. At this time, nearly all new Commodore software is protected. So why not BASIC 8.0? We believe that C128 users deserve to be trusted. We believe in giving you value for your money. So on this disk is not only the first truly unique C128 software package (BASIC 8.0), there is a FREE run time system that can be used by registered owners to produce program disks that will run your BASIC 8.0 programs without using the BASIC 8.0 (5) editor disk. These run time systems can be given away or sold without you paying us royalties! So if you write an exceptional program you want to share, you can do so legally without infringing on our copyright. (These run time programs can only be ran, not edited or altered by the user.) If that isn't enough, there is also a bonus program written in BASIC 8.O called BASIC PAINT. This is a very powerful graphic paint package, actually more powerful than most commercial systems available for sale. This program is also copyrighted, so you may not give it away or sell it. Use BASIC PAINT just as a paint system, or use it to create pictures, brushes and patterns for use in your BASIC 8.0 programs. Besides informing you that making copies of BASIC 8.0 and BASIC PAINT and giving them away (or selling them) is illegal and makes you subject to criminal penalties, please consider this. We spent two years developing this system for the C128, at a time when most software developers were ignoring your software needs. We have given you one of the most powerful graphic languages ever produced on eight bit machines, a free run time system for the programs you develop, as well as a powerful paint package. We have trusted you by allowing you to make copies of the disk for your own use. If we find that all this is not respected and piracy occurs anyway, other software being developed by us may well never show up, or may be protected if it does. But if you show the proper restraint and do not give out illegal copies, rest assured we will follow with more powerful, unique and unprotected software for your C128. And who knows, other companies may follow our lead! (6) FOREWORD The Commodore 128 personal computer was released in mid 1985 as the logical upgrade path to the popular C64 computer. In order to address the wants and needs of the potential C128 computer buyers, Commodore asked for suggestions about what the users would like in this new computer system. The major suggestions were implemented. These were C64 compatibility, a faster high capacity disk drive, more standard memory and ram expansion capability, a higher level BASIC language, and a professional 80 column color display. All these improvements over the C64 allowed Commodore to create what is perhaps the most powerful 8 bit microcomputer yet released to the public, and they explain why in a little more than a year over one million C128's have been sold. One problem associated with the C128 has been the limited amount of software developed for its native C128 mode. This is mainly because of the C64 compatibility as software developers wanted to play it safe and only released software that would run in C64 mode. This lack of real C128 mode software has led to a good deal of anger and disappointment in the C128 buying public, yet they have stayed with their chosen computer system. And of the one hundred or so native C128 packages available after a year, most have been productivity packages like word processors, spreadsheets and databases. Interestingly enough the ones that have been successful have all catered to the C128's 80 column display capabilities. While the built in Basic 7.0 has a very large base of commands that take advantage of the C128's 40 column graphics capability, almost nothing is available to the BASIC programmer (7) to access the C128's 80 column graphics possibilities, which are quite extensive and actually more powerful than the supported 40 column graphics. In fact Commodore originally stated that there would be no high resolution RGB graphics (except text) as the 8563 chip was not designed to support them and any that could be added via software would be too slow to be usable. The authors of Basic 8.0 demonstrated that high speed monochrome graphics were not only possible, but quite practical in an early copyrighted language extension called Ultra Hires. This small graphics language generated such an avalanche of world-wide interest that we decided to see just how extensive the graphics of the 8563 were. Our criteria was to produce the most powerful and productive graphics system ever developed for a 8 bit computer. With Basic 8.0 we more than succeeded. David P. Darus Louis R. Wallace (8) CHAPTER ONE INTRODUCTION TO THE BASIC 8.0 PROGRAMMING LANGUAGE Basic 8.0 is a new and exciting programming environment for the C128 computer owner. It allows you to use an entirely new aspect of graphics on the C128, graphics that actually exceed the high resolution and power that the C128 and C64 user have come to expect. Yet it does so while being compatible with the existing advanced non-graphic commands of Basic 7.0 that are built into the computer. Why is Basic 8.0 so powerful? Well, first of all it offers an extremely high resolution graphics display of 640 X 200 pixels on the screen at the same time (twice the resolution of 40 column mode). This screen memory is completely separate from the normal system ram contained in the computer, and unlike the 40 column graphic screen it does not use any of the users valuable programming ram. Secondly, the normal bitmap graphics used on microcomputers are a two dimensional system. With Basic 8.0 however, its drawing commands work in a three dimensional environment, and the BASIC programmer has a great deal of control over perspective, rotation, viewing angles, the origin and depth of view. Furthermore, it gives the programmer commands to generate three dimensional solid surfaces, a power usually only available on much more expensive computers. Third, Basic 8.0 offers the RGB graphics user five different types of graphic displays, four of which can use all 16 colors on the screen at the same time. It is also possible to have several screens in memory simultaneously, each with a different color resolution and/or screen size. Fourth, Basic 8.0 has many other special Chapter One (9) and unique features. For example you can make Virtual screens that are much larger than the normal 640 X 200 displayable screen. By using the SCRDEF command you can create custom screens that are up to 2040 pixels wide or over 800 pixels tall. Conversely, by using the MODE command you can easily switch between any of the 32 predefined graphic screens. There are also commands to SCROLL a screen, save and load screens and brushes, define a LOGO, PAINT with exotic color PATTERNS of your own design, create WINDOWS, make printed copies of your images on many different printers (and in many different sizes as well as in color) and much more. Another important feature of Basic 8.0 is it's total support of the C128 and its hardware expansion capabilities. Obviously the 80 column RGB display is used. And of course the Basic 8.O user can make use of the 1541,1571 and 1581 disk drives. Support for a number of different dot matrix printers allow programs to create hardcopy of the graphic screens. Basic 8.0 also is one of the first commercial software packages to support the 1700 and 1750 ram expansion modules. You will find that the new 1351 proportional mouse has found a home here in Basic 8.0 programs, and you can still use a joystick too. You will even find that the extra 64K video ram expansion for the 8563 chip being installed in tens of thousands of C128's by their owners (and already present in the new C128D) is completely supported. Basic 8.0 can use in one way or another the whole 704 K ram that can be installed in the C128, as well as virtually every peripheral device. In fact every time you upgrade your C128 computer, you will find Basic 8.0 waiting with even more capabilities for you to use! Chapter One (10) The following chapters will help you learn about Basic 8.0 and its commands and techniques. They are divided into several sections: screens and modes, 3d graphics, solid shapes, memory management, data structures, the mouse/joystick/pointer system, printers and more. Following these chapters you will find a Basic 8.0 ENCYLOPEDIA, which is an organized directory of the commands and their syntax. Here every command is listed and each parameter explained. Then comes the Basic 8.0 MEMORY MAP, which simply shows the areas of the computer that are used by the ROMS, RAM and Basic 8.0 itself. Finally the appendix contains information on the data compression algorithms used, the file format for the graphics, 3d data file structures and more! The hardware in the C128 that lets Basic 8.0 generate all these special graphics is the 8563 Video Display Chip. This is a very powerful RGB display processor that is a new addition to the Commodore computer family. It is controlled through 37 registers that are completely separate from the normal C128 operating system. If is only possible to address the 8563 registers and its video display ram through two locations in the C128. These are $D600 (Address Register) and $D601 (Data Register). Programming the 8563 can be quite complex, and explains why graphics were thought to be infeasable, though obviously not impossible. On a standard C128 the 8563 video chip has 16k of dedicated display ram you can use, but it is quite possible to expand that ram to 64k, opening a whole new world of C128 and Basic 8.0 graphics. Basic 8.0 allows you to access these new capabilities as well as creating many additional features in your own programs. It does this while still supporting the built in Basic 7 commands Chapter One (11) (except of course the 40 column graphics commands). How does Basic 8.0 work? Well, the language is what is known as a wedge. A wedge is a machine language program that is wedged into the computers BASIC interpreter where the new commands can be executed (and evaluated) along with the old. One of the problems associated with these types of languages is the fact they slow down the normal basic interpreter simply by adding more commands. Basic 8.O does not work this way because we did not want to slow down your programs. Instead we choose a method called a syntax error wedge. This technique prefixes the new commands with a character that is not used by BASIC in any of its' normal commands. So when this character is encountered in a statement, the operating system jumps to the routine that handles syntax errors. We have taken over that function, and check for one of our commands when an error occurs. If it is a real syntax error the program passes it on to the operating system for evaluation. If however we find it to be a Basic 8.0 command it jumps to our new interpreter. Only then is the new command interpreted. This technique saves a great deal of time in processing the program, especially when (like in Basic 8.0) the added language consists of a large number of new commands. This time savings means your programs run as fast as is possible. The special character used to prefix all Basic 8.0 commands is the @ character. It is easy to see in your programs, and does not require pressing the shift key on the C128 keyboard to use. And, finally it should make it far easier for a compiler to be developed for the Basic 8.0 language, should a developer wish to do so. Chapter One (12) Basic 8.0 COMMAND SUMMARY @ANGLE @ARC @BOX @BRUSHPATRN @BUFFER @CBRUBH @CHAR @CIRCLE @CLEAR @COLOR @COPY @CYLNDR @DIR$ @DISPLAY @DOT @DRWMODA @DRWMODB @FETCH @FLASH @GR0W @HCOPY @LINE @LOGO @LSTRUCT @MODE @MOUSE @ORIGIN @PAINT @PATTERN @PIXEL @PTR @SCALE @SCLIP @SCRDEF @SCREEN @SCROLL @SDAT @SEND @SPHERE @SPOOL @SSTRUCT @STASH @STORE @STRUCT @STYLE @TEXT @TOROID @VIEW @WALRUS @WINDOWCLOSE @WINDOWOPEN @ZOOM Chapter One (13) STARTING BASIC 8.0 To start BASIC 8.0 turn on your disk drive and RGB monitor. If you are using a dual monitor (like the 1902) make sure it is in RGB mode. Press the 40/80 column key on the C128 down. Put the BASIC 8.0 Work Disk in the drive, and turn on the computer. The system will autoboot (load and run itself). When it is finished loading, you can then run one of the supplied utility programs or write your own. Chapter One (14) CHAPTER TWO SCREENS AND MODES There are five different screen formats supported by BASIC 8. The key difference between them lies not in the screen pixel resolution, but rather in the color resolution or color cell size. In monochrome graphics mode there is no color information stored for a color cell, so there is only two colors, foreground and background, available to the screen. Therefore a 640 X 200 monochrome screen requires 16000 bytes of ram for the bitmap, and no ram for color information. To use many colors at once you must have somewhere in memory to store the color information, or attributes. On the C128 a single attribute byte controls the color information for a color cell. Each attribute is responsible for storing the color information for a specific area of the screen known as the color cell. A color cell is always 8 bits (pixels) wide, and can be either 2, 4, 8 or 16 scanlines (pixels) tall. Each color cell can have any 2 colors, a foreground color and a background color, from a palette of 16 colors. The larger the color cell, the smaller the amount of ram required for color attributes. The smaller the color cell the more ram required for color attributes. So when using the multicolor modes some ram in addition to the bitmap ram is required to store the color information, with the exact amount depending on the color cell and screen size. The five possible display modes are defined as such: Mode Type Color Resolution 0 Monochrome No color cell 1 Color Mode 1 8 X 2 pixel color cell 2 Color Mode 2 8 X 4 pixel color cell 3 Color Mode 3 8 X 8 pixel color cell 4 Color Mode 4 8 X 16 pixel color cell Chapter Two (15) For some point of reference look at display mode 3. It uses an 8 X 8 pixel color cell, which means that each of the 8 X 8 cells on the screen in this display mode can have their own unique pair of colors, one for the foreground and the other for the background. This is the same color resolution as the C64 or C128 composite high resolution screens color capacity, yet the bitmap has twice the horizontal screen resolution of the composite mode. Each color cell requires 1 byte of attribute memory in addition to the bitmap ram requirements. Using a 640 X 200 display with an 8 X 8 color cell requires 16000 bytes for the bitmap and 2000 bytes for the color attributes totaling 18000 bytes of ram. This is obviously more than the 16K built in for the 8563 to use and since none of the C128's system ram can be directly accessed for 80 column graphic purposes it is not possible to display a full 640 X 200 color screen in any of the color modes with only the standard 16K. That's why we strongly recommend you have the full 64K video ram installed in your C128 (see appendix). The ram requirements for a 640 X 200 screen in each display mode are: DISPLAY MODE DESCRIPTION COLOR CELL SIZE RAM REQUIRED Monochrome 0 16000 Color Mode 1 8 X 2 24000 Color Mode 2 8 X 4 20000 Color Mode 3 8 X 8 18000 Color Mode 4 8 X 16 17000 As you can see it is not possible to have these full screen colors without the extra ram. If you have installed the full 64K of ram (or have a C128D) you can use any display mode as well as virtual screens larger than 640 x 200. However in a standard C128 there is only 16K, so to get around this limitation and still provide color, you must define screens that are less than Chapter Two (16) 200 pixels high, which frees some ram to be used for color information. You can define your own screens using the @SCRDEF (SCReen DEFinition) command, or simply use the @MODE,O command to define 8 separate screens designed for the 16K C128. These screens already make allowances for the limited memory, and create screen displays of various heights and resolutions. They are as follows: SCREEN 0 640 X 200 Monochrome SCREEN 1 640 X 192 Color 8 X 16 SCREEN 2 640 X 192 Color 8 X 8 SCREEN 3 640 X 192 Color 8 X 4 SCREEN 4 640 X 192 Color 8 X 2 SCREEN 5 640 X 192 Color 8 X 8 Interlaced SCREEN 6 640 X 192 Color 8 X 4 Interlaced SCREEN 7 640 X 192 Color 8 X 2 Interlaced After using the @MODE,O command you can work on any of the above screens by just using the @SCREEN,n command, where n is 0-7. We have found the @SCREEN,2 (640 X 176 Color, 8 X 8 color cell) the most generally useful color display in the standard, unexpanded C128. If your needs are such that a smaller display (640 X 152 or 640 X 104) is useful, by all means use those screens. The extra color capability is exceptional, and it allows for strikingly beautiful color displays. If you need a larger color display in a 16K system, use @SCREEN,1 for a 640 X 192 color display using a 8 X 16 color cell. You can use only one of the @MODE,O screens at any one time, but you can switch very easily between the different screen types. You can also maintain the different screens in memory as brushes, or @STORE them to disk until needed. Depending on the size of your program, you can @STASH several screens in the C128's ram banks 0 and 1. However, if you have the 1700 or 1750 Ram Expansion cartridges you can have dozens of screens, fonts, brushes, logos Chapter Two (17) and patterns in memory at one time. If you have the 64K video ram expansion installed in your C128 (see Appendix) or own a C128D your screen possibilities are enhanced virtually 1000%! You can now use all four @MODE commands. @MODE,1-3 offers twenty four spectacular screen combinations. Besides 640 X 200 monochrome screens there is every possible 640 X 200 color screen (8 X 16, 8 X 8, 8 X 4 and 8 X 2). There is a large variety of VIRTUAL SCREENS (screens larger than what can be displayed on the monitor at once), including monochrome displays such as 1280 X 409, 640 X 819, 2040 X 252 and 800 X 655 pixels. There are many virtual color screens as well, up to 640 X 728 pixels. @MODE, 1 and @MODE,2 both contain combinations that allow two to four screens in memory at once, regardless of the screen size or type. Of course, you can use the @SCRDEF command to custom design screens of any size using any of the five color types. When used it overrides the definition given that screen number by @MODE,n. Take a look at the various screens in each mode, because it is likely most of the screens you want will be there; if not, then make some of your own design. You can find a detailed list of the screens in each mode in the chapter BASIC 8 COMMAND ENCYCLOPEDIA under @MODE; the complete syntax of @SCRDEF is also listed there. You activate your chosen graphic screen with the command @SCREEN, draw screen, view screen. The draw screen and view screen signifies which of the possible (at one time) 8 screen definitions to use as your current drawing screen and viewing screen. They do not have to be the same, so you can be looking at one screen while drawing on another (in 64K video ram systems) . This is ideal for many applications, and can be used Chapter Two (18) for double buffered displays, a technique often used for animation. And screens can be saved or loaded with the @STORE and @DISPLAY commands. At times you will need the use of the normal text screen, and you can return to it quite easily with @TEXT. This initializes the C128 80 column text display, using the standard character fonts. If you want to install custom fonts in text mode, using the @FONT command will allow you to load any two fonts into memory for use with the 80 column text display. Another powerful command is @WINDOWOPEN. This command allows you to define special subwindow areas of the screen. The upper left corner of the window becomes the screen location 0,0. Both the windows size and location is user defined, and once defined all subsequent drawing commands default to it. It stays the default output until another @WINDOWOPEN or @SCREEN command is issued or you give the command @WINDOWCLOSE. Once opened, the window can be cleared, filled with color, drawn into, etc. If clipping is on, objects drawn outside the window are clipped. Most, but not all, of the graphic commands work on the current window. Those that do not (like @STASH, @FETCH, @COPY etc.) are not drawing commands. In the BASIC 8.0 COMMAND ENCLYCLOPEDIA each command is defined and if it does not respond to the @WINDOWOPEN command, it will be clearly labeled as such. Here is a simple example program that will define a @MODE,O 640 X 176 color screen, clear the display and set up some default drawing colors. 10 @WALRUS,0:REM define the 16K ram mode 20 @MODE,O:REM Select the 8 screens available to 16K users 30 @COLOR,O,8,O:REM black background, red drawing color, black border 40 @SCREEN,2,2:REM use the 640 x 176 color display 8x8 cells 50 @CLEAR,O:REM clear the display 60 SLEEP 5:REM wait 5 seconds Chapter Two (19) 70 @TEXT:REM return to text mode A final note. The different color screen are not compatible. You cannot display an 8 x 8 screen in an 8 x 2 mode. The same is true for brushes. They can only use the color mode from which they were created. Monochrome screens and brushes can be loaded into any screen, although they will not contain any color information. Color screens and brushes of any color cell resolution can be displayed in a monochrome screen, with the color information ignored by the monochrome display. By going through a monochrome intermediary, you can transfer the bitmap of screens and brushes from different color modes. Chapter Two (20) CHAPTER THREE GRAPHICS BASIC 8.0 has all the graphics shapes you would expect from a graphics oriented language. It has @DOT, @LINE, @BOX, @ARC, @CIRCLE, @PAINT and more. These are normally rather standard commands, but this is BASIC 8.0, not some simple graphics system. Each of these commands offers far more than found in any other language. For example, each of them works in 3 dimensions. That's right, 3D! Each point is defined as an element of a X,Y,Z coordinate system. This is far more advanced than the simpler 2D system used on other graphic systems. It allows you to define and draw complex 3D objects without complex (and slow) mathematical calculations. It doesn't stop there either. BASIC 8.O has some powerful pattern capabilities that allows you to define patterns n bytes wide by m pixels deep and in color. This is especially useful with the @PAINT command, but also the drawing commands (and the character command) can be told to draw in the current pattern. That means your lines, circles, boxes, dots, arcs and letters can all be patterned (like the AMIGA). There's more! Each of the drawing commands (except @DOT) can be given a height parameter that allows you to multidraw it. You can define both the direction and the step value used by the height parameter with the @GROW command. The syntax is @GROW,x step,y step,z step; these step parameters can be positive or negative values. Therefore it is possible to grow in several dimensions and directions, all at the same time! If the step value is 1 or -1, the line is drawn as a solid. If it is 0 there is no growth in that direction. If greater or less than 1 or -1 then each layer of the graphic is stepped by that number of lines. What can you do with this? Well, for one thing it allows Chapter Three (21) lines of different weights. For another, when used with the @CIRCLE command it allows you to draw cylinders. Used with the @ARC or @BOX commands it allows you to draw 3D bars of various shapes, or use a subtended arc and make 3D pie wedges for graphs or charts. @BOX allows shearing which means to pull the base left or right from its position, while holding the top still. These parameters allow you to specify a shear direction (X or Y) and a shear value (how far to shear it). This allows you to make complex 3D bars very easily. @ARC offers a few special features too. While it can be used for circles or ellipses, it can also be used for generating segments of a curve by specifying the start and ending angles of the arc. You can set the increment of the arc (angle between the lines used to draw the arc) to create other geometric shapes. The smaller the increment, the smoother the line. The larger the increment, the more noticeable the lines. If you define an increment of 45 degrees, the arc becomes an octagon (8 sides). Use 60 degrees and it's a hexagon (6 sides), 90 degrees and you have a diamond, and 120 degrees for a triangle. When using pixel oriented graphics, a problem arises. The pixel is not symmetrical, rather it is bigger in the Y direction than the X. This means if you draw a 100 pixel horizontal line and a 100 pixel vertical line, the vertical line will be physically longer. To compensate for this BASIC 8.0 has the command @SCALE. There are three scale modes available. The first, @SCALE,O is the normal mode. Here the Y pixel is longer than the X, so a 640 X 200 pixel screen is just that. @SCALE,1 tells the graphic primitives to use a different pixel scale. The Chapter Three (22) 640 X 200 physical pixel screen becomes a 640 X 512 logical screen. There are no more real pixels displayed but they are addressed differently. This new graphic scale means that in the example above, both 100 pixel lines are the same physical length. @SCALE,2 doubles the logical scale of @SCALE,1. The screen now becomes 1280 X 1024 logical pixels. Again here we have no additional pixels, only a better logical addressing where all the addressable points are the same size. It is very important not to confuse these logical screens with virtual screens. Virtual screens really are physically larger in terms of real pixels. If you are working in a large virtual screen and change the scale the virtual screen is adjusted accordingly. To determine the new pixel ranges, use these formulas: @SCALE,1 NewX = 01dMaxX, NewY = OldMaxY/.39 @SCALE,2 NewX = 01dMaxX*2, NewY = (OldMaxY/.39]*2 OldMaxX and OldMaxY are the largest X and Y values in the current screen. A word about using @SCALE is in order. While it does compensate for the C128's non-symmetrical pixel, it has the drawback of slowing the rate of drawing. That's because the scaled points must be converted to the physical screen pixels. So don't use @SCALE 1 or 2 in situations where speed is important. @PATTERN allows you to specify one of the 192 structures as the current pattern. You can fill an enclosed area with the @PAINT command. @PAINT uses the currently defined pattern, if pattern mode has been selected in @DRWMODA, otherwise @PAINT uses the current color for a solid paint. @PATTERN allows you to create incredibly detailed patterned fills, and of course the Chapter Three (23) pattern can be in color. Anything you can define as a brush can be used as a pattern. Just @STASH the screen area you want in memory as a brush, then use @BRUSHPATRN to make that brush into a pattern. For information on defining a pattern structure see the chapter on structures or the BASIC 8.0 ENCYCLOPEDIA. You can also find out information on any specified pixel with the command @PIXEL. It allows you to tell if a given pixel is on, and what the colors are within its color cell. When using the multicolor modes, it is easy to set the drawing, background and border color with the @COLOR command. It allows each to be any of 16 colors. Normally there is no different border color in the C128 RGB mode, but while in color mode BASIC 8.0 was able to get around that limitation. You can also use the @CLEAR command to fill the current screen or window with the colors of your choice, or even to fill it with one of 255 different simple patterned shades based upon the numbers 0-255. Another graphic command is @CHAR. @CHAR allows you to write on the graphics screen using any character font you want. You can use the two built in fonts, or you can load a new font into a structure and use it. The characters can be enlarged up to 16 times in both the x and y directions. You can position the character string anywhere on the active drawing screen. If you are using the color modes you can specify the foreground and/or the background color of the character by inserting control codes in the string. You can also give the direction to print the character string. The direction can be left, right, up, down or combinations of them, like up and to the right. And there are many special character control codes in addition to colors Chapter Three (24) available. For example, you can underline, rotate, flip, mirror, reverse, pattern, complement, inverse and blank under the character string, just by including the proper control code. For details of the @CHAR command see the BASIC 8.0 ENCYCLOPEDIA (CHAPTER 10). There are other commands used with the graphic commands that modify the way they are used. The commands are @DRWMODA and @DRWMODB. Each allows you to turn on and off different drawing modes. For example, you can use @DRWMODA to draw, erase or use the XOR (complement) mode when drawing pixels. You can turn on and off patterned drawing. You can merge a pattern with the screen, and set the clipping flag. (Clipping chops off the drawing commands when they leave the edges of the current screen or window.) You can also change from perspective to parallel 3D drawing modes with the @DRWMODB command as well as setting the Unplotlast and Unplotvertex flags, so that when drawing multiheight objects they have a more obvious 3D appearance. All the parameters of @DRWMODA and @DRWMODB are explained in the BASIC 8.0 COMMAND ENCYCLOPEDIA. lO @WALRU6,0:REM 16K video ram system 20 @MODE,O:REM use 16K screens 30 @SCREEN,2,2:REM use 640 x 176 screen 40 @DRWMODA,1,0,0,0,0,0,0:REM define drawmodea using JAM1 color 50 @DRWMODB,O,O,O 60 @COLOR,O,8,O:@CLEAR,O:REM set colors, clear screen 70 FOR I=l TO 100:REM Define random lines and colors 80 Xl=INT(RND(1)*640) 90 Yl=INT(RND(1)*176) 100 Zl=INT(RND(1)*100) 110 X2=INT(RND(1)*640) 110 Y2=INT(RND(1)*176) 130 Z2=INT(RND(1)*100) 140 C=INT(RND(1)*15)+1 150 @COLOR,O,C,O 160 @LINE,X1,Yl,Z1,X2,Y2,Z2,1 170 NEXT I l80 SLEEP 5:REM wait 5 seconds 190 @CLEAR:@TEXT:REM return to text mode Chapter Three (25) CHAPTER FOUR THREE. DIMENSIONAL GRAPHICS Commands and Theory Many of BASIC 8.0's graphic commands work in three dimensions, or 3 space. In order to increase the graphics power available, there are a number of special commands that effect how the graphics are drawn. But before discussing them, a short explanation of 3 dimensional graphics and its terms is necessary. Three dimensional graphics means there are three coordinate axes used to define a point. In normal microcomputer graphics only 2 dimensions are used. They are labeled X and Y, where the X axis is horizontal to the screen and Y is vertical (up and down). In three space, a new axis is defined, Z. This Z axis is directed into and out of the screen. (See Figure 4.1) Y ! Z ! / ! / ! / ---------+---------- X / ! / ! / ! ! Figure 4.l 3D Coordinate Axis There are two viewing methods commonly used in 3D graphics. One is parallel, where the Z coordinate is simply used to offset the point when converted to the 2D space of the screen. The other is perspective viewing, which uses a point in 3 space as Chapter Four (26) its vanishing point. Perspective makes objects drawn near to the viewer (Z values decrease) appear bigger, and objects drawn away from the observer toward the vanishing point (Z values increase) appear smaller. You can select perspective or parallel mode by using the @DRWMODB command. The vanishing point has no effect when using parallel mode. When drawing in perspective mode, objects that approach the vanishing point appear to be smaller. If they reach the vanishing point they become a single point, and if they exceed it they become larger (to our eyes). By being able to define the vanishing point (with the @0RIGIN command) you can control the degree of three dimensional perspective your images will assume. Another aspect of 3 space that effects the way we perceive a 3D object is its origin. The origin is essentially the center of the universe to your object, line or point. When you rotate, you are rotating around the origin. The default center of rotation is the 3D point 0,0,0. Sometimes you don't want an object to rotate around this point, because, depending on your position in space relative to this default origin, you can end up with your object completely off the screen. If you wanted to rotate an object around its own center and stay in the same screen location you would have a problem. BASIC 8.0 removes this difficulty by allowing you to define any spot in 3 space as the center of rotation. To control where the origin is as well as the vanishing point, use the @0RIGIN command. For example, if your object was a cube, by setting the center of origin to the center of. the cube your object would rotate around its own center, and stay in the same spot while doing so. In BASIC 8.0 you can make a 3D object or point appear Chapter Four (27) different with parallel drawing mode set by using the @VIEW command. @VIEW sets the position of your eye around the Y axis. It has the effect of a simple rotation of your eye (not your data) around the Y axis, so when you draw you see your object at a different point of view. In order to have complete rotation control, BASIC 8.0 uses the @ANGLE command. It allows you to set global rotation values that are used by all the drawing commands (except @CHAR), as well as the rotation sequence. There are three different axes in 3 space, the X, Y and Z axes. You can rotate your objects in any of these three directions, both in the positive and negative directions. You can rotate in more than one axis at once, which results in a multiple transformation of the object. When rotating in several directions at once, the end results differs based on what sequence you rotate (XYZ, XZY, YXZ, YZX, ZXY or ZYX). An object rotated in the sequence XYZ will appear different from one rotated in XZY, even if the angles of rotation are the same. All of these parameters are definable with the @ANGLE command. When you draw with the graphic commands they respond to the currently defined @ANGLE setting. The default is @ANGLE,O,O,O,O (no rotation). Once set to another value, all the drawing commands output their functions accordingly. For example, if you are drawing an arc, and the @ANGLE is defined to be a 45 degree rotation around the Y axis (@ANGLE,O,45,0,0), the resulting arc will appear to be rotated 45 degrees in the Y axis. The commands @DOT, @LINE, @BOX, @ARC, and @CIRCLE all will respond to the given @ANGLE. Most importantly, you can change the rotation angle as many times as your program requires. However, remember Chapter Four (28) that complex rotations will decrease the speed of your graphics (although only a tiny fraction of what they would be if mathematically rotated in basic). Here is an example of a BASIC 8.0 program that draws a rotated line using the @ANGLE command to rotate it around the Z axis. Notice that the line definition is never changed, only the @ANGLE values change. 10 @WALRUS,O:REM 16 K VIDEO MODE 20 @MODE,O:REM USE FIRST 8 SCREEN DEFINITIONS 30 @SCREEN,O,O:REM MONOCHROME SCREEN 640 X 200 40 @SCALE,O:REM USE NORMAL SCALE 50 @DRWMODA,1,0,0,0,0,0,0: @DRWMODB,0,0,0: REM STANDARD MODES 60 @ANGLE,O,O,O,O:REM DEFAULT NO ROTATION 70 @0RIGIN,320, 100,0,320,100,200:REM ORIGIN IN SCREEN CENTER 80 @CLEAR,O:@COLOR,O,8,O:REM CLEAR SCREEN, SET COLOR TO RED 9O FOR AN=O TO 360 STEP 20 :REM CHANGE ANGLE BY 20 DEGREES 100 @ANGLE,O,O,AN,O:REM ROTATE LINE AN DEGREES AROUND Z 110 @LINE,200,100,0,440,100,0,1: REM DRAW LINE 120 NEXT AN 130 GETKEY A$:REM WAIT FOR A KEY PRESS l4O REM CLEAR ALTERED ROTATION VALUES 150 @ANGLE,O,O,0,0 160 REM RETURN TO TEXT MODE 170 @TEXT In addition to these 3D drawing commands, there are several designed to be used to generate SOLID 3D OBJECTS. These are based upon techniques developed for the C64 computer by Mr. Richard Rylander and first published in the May 1985 Dr. Dobb's Journal. Because of the 3D nature of our work, Mr. Rylander allowed us to convert his solids algorithms to the C128 for use in BASIC 8.0. We wish to thank him for his great work and generosity. The Rylander Solid commands allow you to generate textured (halftone or random) solid images such as SPHERES, TOROIDS, CYLINDERS and SPOOLS. You have a great deal of control over clipping the objects, shading and texture. It cannot be chapter Four (29) emphasized enough the incredible graphics possibilities of the solid generation commands. The solid commands differ from the regular 3D graphic commands in that they are defined using the normal 2D X,Y system. You can not use a Z coordinate value when defining their positions. Perhaps the most interesting of the Rylander shapes is the sphere. It allows you to generate a solid spherical object, which can be used in many drawings or illustrations for quite a dramatic effect. The command is @SPHERE,X,Y,RADIUS. It will place the sphere at the given coordinate X,Y (remember these commands have no Z axis control). You can change the clipping, shading and lighting with the @STYLE and @SCLIP commands. You can create a toroidal shape (somewhat donut shaped) with the command @TOROID. This allows you to define both the inside radius and the outside radius, as well as the view (horizontal, vertical or top) so the shape can be quite different looking with the same command. Another of the Rylander shapes is SPOOL. A spool surface can be thought of as the inside of the toroid surface. Created with the @SPOOL command, it allows you to specify the inner and outer radius, and two viewpoints, horizontal and vertical. The final Rylander solid shape is the CYLINDER shape. This will create a horizontal or vertical cylinder, with you defining its radius, halflength and view. To make these even more useful, there are two command that can be used to define the characteristics of the solids in much the same way as @DRWMODA and @DRWMODB define the drawing commands. Chapter Four (30) @STYLE sets up the shading (textured or halftoned), scaling (symmetrical or elongated) and lighting (normal or backlite). @SCLIP allows you to only draw part of the solid, and clip the rest. This makes it easier to combine the shapes into more complex solids. While the solids commands do not respond to the 3D commands (@ANGLE, @VIEW etc.) they do respond to the @COLOR, @WINDOWOPEN/@WINDOWCLOSE and bitmap screen (@COPY, @STASH/@FETCH) commands. Here is a simple example that creates a green textured sphere. 10 @MODE,O 20 @SCREEN,2 30 @COLOR, 0, 5, 0:@CLEAR,0 40 @DRWMODA,1,0,0,0,0,0,0:@DRWMODB,0,0,0 50 @STYLE,0,1,1 60 @SPHERE,320,200,50 70 GETKEY A$ 80 @TEXT An important point should be made about the 3D drawing and 3D solid commands. Your program, when it finishes up and exits, should set the ANGLE, VIEW, DRWMOD's, ORIGIN etc. back to the default values. Otherwise the next program will begin in these modes. Always finish with @ANGLE,O,O,O,O and @DRWMODA,0,0,0,0,0,0,0. (See Appendix D) Chapter Four (31) CHAPTER FIVE MEMORY MANAGEMENT BUFFERS, STRUCTURES AND OTHER DELIGHTS BASIC 8.0 is able to utilize up to 10 different 64K banks of ram for storage. Two of these are ram banks 0 and 1, which are the two standard ram banks used by the C128 itself. The other 8 are made available when you install external ram via the 1700 or 1750 ram expansion cartridges. If you have added the 1700 ram expansion cartridge, which has 128K of ram, you have then added two addition banks, bringing the total available 64K banks to 4. If you have added the 1750 ram expansion cartridge it adds 512K additional ram, giving you 8 additional banks of 64K for a total of 10 banks. Basic 8.0 allows you to access that ram by the use of a data structure system. Each of the 10 banks is referred to as a BUFFER. The BUFFER numbers are 0-9, where 0 and 1 are the standard C128 banks 0 and 1, and BUFFERS 2-9 are the external banks added with the ram expansion. You can also define where in the ram bank a BUFFER will begin and it's size in order to effectively use the system ram banks 0 and 1. Obviously you cannot just use all the ram in banks 0 and 1, as that would leave no room for programs and variables; yet very few programs use every byte in those banks. That leaves some for use as BUFFERS; but it is far better to have the external ram for structures, and leave internal ram for programs. For example, let's define a BUFFER in ram hank 1. Since this bank is also used for basic program variables you should adjust the variable start or end pointers so that your buffer doesn't corrupt your variables or visa versa. POKE 47,0:POKE 48,68:CLR @BUFFER,1,1024, 16384 Chapter Five (32) This example uses ram bank 1 as the BUFFER, with it starting at decimal 1024 and is 16384 bytes long. It moves the start of variables in bank 1 up 16K to make room for the data buffer. That's enough for several fonts, or even a full screen monochrome picture. If you have the external ram expansion installed, you could use several of its ram banks instead. For example; @BUFFER,2,0,65535 :rem use external ram bank 0, use all 64k @BUFFER,3,0,65535 :rem use external ram bank 1, use all 64k @BUFFER,4,0,65535 :rem use external ram bank 2, use all 64k @BUFFER,5,0,65535 :rem use external ram bank 3, use all 64k This gives you a total of 256k of ram to use as BASIC 8.0 STRUCTURE storage. You can use all 10 banks if you wish, or any combination. With the external ram installed and used for storage, you can use banks 0 and 1 just for your program and its variables, allowing for very large and graphically complex programs. STRUCTURES Once you have declared your BUFFERS, you can define structures to use that memory. There are 4 types of structures you can define. There is the PATTERN structure, used to define a bitmap pattern (of any size) and its' color (if any). There is the LOGO type, which is used to generate one or more character strings. For example, you could define a structure that would print to a specific place on the screen, with a particular font, and any defined size. You can define many character fonts with the FONT structure, allowing you to have an unlimited number of different character fonts all at once. Finally there is the BRUSH type of structure, which is a rectangular area of bitmap (including color if it is present). Brushes allow you to pick up any area of the screen and save them to memory or disk, flip Chapter Five (33) them, mirror or reverse them, then put them back on the screen where ever you want. If you are using color the color is saved and manipulated as well. You can even compress them to their smallest possible size for compact storage. Even more impressive is that a brush can be copied to another STRUCTURE as a pattern type. This allows ANYTHING you can place on the screen to be used as a pattern! The data structure is defined using the commands @STRUCT, @SDAT, and @SEND. These commands work together to create different types of usable structures. The command @STRUCT includes the structure number (0-191) used to identify which structure when using later commands. Then the structure type (1-4), followed by a BUFFER number, and an address in the buffer. Once you have defined the type, use the command @SDAT (Structure DATa) to send whatever data is appropriate. You can use Basic 7.0 commands within the @STRUCT:@SDAT:@SEND block, for example FOR NEXT, DO WHILE LOOP etc., to generate data. You can use the @SDAT and @SEND commands to find the next available address in the buffer, as they return that information value when used. For example, if you are using the @SDAT command to send pattern data, the next available address in the BUFFER is found by using @SDAT like this; @BUFFER,2,0,65535 :rem external ram, 64k buffer @STRUCT,2,1,2,0:rem struct 2,type pattern, buffer 2,address 0 AD = @SDAT,pattern data, pattern data, pattern data rem AD = next address available @SEND :rem finished defining pattern structure A) Loading and Saving STRUCTURES STRUCTURES come in four types, pattern, logo, character and Chapter Five (34) brush. You use the commands @LSTRUCT and @SSTRUCT to load and save all four types of STRUCTURES. When you want to load you define a BUFFER that can be used to store the data, then use @LSTRUCT to load it into memory. If you have a STRUCTURE in memory you want to save, then @SSTRUCT can be used to store it to disk. Here is a small example that loads the supplied 160 column character font into a STRUCTURE to be used with the @CHAR command. @BUFFER,9,0,65535 : REM use external ram bank 9, all 64 k @LSTRUCT,0,8,9,0,"FNT.160 COL":REM STRUCTO, DRIVE 8,BUFFER 9, Address O,filename AD=@SEND :REM AD now has the next address in BUFFER 9 This short program segment has now added a 160 column character font to external ram memory as structure 0, where you can use it with the @CHAR command. If we wanted to add another font as well, the program would continue this way. @LSTRUCT,1,8,9,AD,"FNT.COMPUTER":REM STRUCTl,DRIVE8,BUFFER 9,Address AD,filename AD=@SEND :REM AD now has the next address in BUFFER 9 We could now begin using the different fonts with the @CHAR command, indicating which one we wanted with it's STRUCTURE number. However, perhaps we want to load some BRUSH types also. We still use @LSTRUCT to load. @LSTRUCT,2,8,9,AD,filename :REM STRUCT#2,DRIVE8,BUFFER 9, Address AD,filename AD=@SEND :REM AD now has next available address in BUFFER 9 We now have easily loaded two fonts and a BRUSH in as user recallable STRUCTURES. We could have loaded LOGO or PATTERN types just as easily. The @LSTRUCT command allows you total control, for example, you might have created on the screen an object that you want to save as a BRUSH. Continuing our program above (still using BUFFER 9) we will @STASH it to a STRUCTURE, then save it to disk. Chapter Five (35) OA=AD :REM Save starting address of this Structure AD=@STASH,3,9,AD,0,0,100, 100, 1 :REM STASH area of screen 0, 0 to 100, 100 to STRUCTURE 3 in BUFFER 9 in compressed format. AD now contains the next address in BUFFER 9. @SSTRUCT,3,8,filename :REM SAVE STRUCTURE @SEND :REM Save the file We have now saved the BRUSH as a disk file, but it is also still available in memory to be used. We could @FETCH it to the screen, use @CBRUSH (ChangeBRUSH) to flip, reverse or mirror it, or even use @BRUSHPATRN (BRUSH to PATTERN) to make a pattern out of it. Of course, since it is stored on the disk we can always reload it at another time. B) PATTERN STRUCTURES BASIC 8.0 has a very extensive pattern capability. You can define a pattern from 1 to 255 bytes wide, and up to 255 pixels deep. If you wish, it can also contain foreground and background information for each color cell in the pattern. Once defined, the pattern can be loaded to and from disk, and used to fill an enclosed area with the @PAINT command. It can also be used in the graphic drawing commands as draw pattern by setting the appropriate parameter in @DRWMODA. The syntax of the PATTERN STRUCTURE is: @STRUCT,4,1,9,AD:REM STRUCT44,pattern,BUFFER 9,Address AD @SDAT,2,8, 1,1 :REM 2 bytes X 8 pixels bitmap, 1 X 1 color @SDAT,255,255,128,0,128,0,128,0,255,255,0,128,0,128,0,128 :REM That is the bitmap data for a brickwall @SDAT,206 :REM color (brown on lite grey), AD=next address AD=@SEND STRUCTURE 4 is now defined as a PATTERN type. You can use it by specifying STRUCTURE 4 when you use the PATTERN command. You can make small simple patterns, or very complex ones. The easiest way to make a pattern is to convert a BRUSH to a PATTERN Chapter Five (36) with the command @BRUSHPATRN. C) LOGO STRUCTURES LOGO STRUCTURES are a special form of the @CHAR command. They allow you to print a number of different character strings out by a single command. So certain often used strings can be saved and loaded directly from the disk. A good example of a LOGO STRUCTURE is a menu of options. It could be stored as a BRUSH, but a LOGO requires much less memory because it is text data, not bitmap data. Here is an example of a LOGO STRUCTURE. OA=AD:REM SAVE AD FOR NEXT EXAMPLE LA=XXXXX :REM LA (LOGO Address in BUFFER 1) @STRUCT,5,2,1,LA :REM STRUCT#5, LOGO, BUFFER 9, Address LA @SDAT, 1,CHARSET STRUCT#,l4,16,0,2,2,2,13,"MENU OPTION 1" @SDAT, 1,CHARSET STRUCT#,l4,32,0,2,2,2,13,"MENU OPTION 2" @SDAT, 1,CHARSET STRUCT#,l4,48,0,2,2,2,13,"MENU OPTION 3" @SDAT, 1,CHARSET STRUCT#,l4,64,0,2,2,2,13,"MENU OPTION 4" @SDAT,O :REM Finished the LOGO AD=@SEND :REM complete this STRUCTURE, AD is next address @SSTRUCT,5,8,"LOGO.MENU":REM Save LOGO STRUCTURE @SEND :REM save LOGO to disk LA=AD:REM SAVE NEXT ADDRESS IN BUFFER 1 AD=OA:REM RESTORE AD FOR NEXT EXAMPLE When defining LOGO STRUCTURES, the first parameter of the @SDAT command should be either 0 or l. A 0 indicates you are finished, while a 1 means continue, I have more data to give. And, because the character string data in LOGO's are accessed by the CHAR command (in much the same way as a string variable) ALL LOGO structures must be stored in BUFFER 1 (system bank 1). Remember, LOGO structures in BUFFER 1 only! D) CHARACTER FONT STRUCTURES BASIC 8.0 has the capability of using virtually unlimited fonts. These fonts can be defined with any standard character editor used for the C64 or C128. They must be converted to the proper BASIC 8.0 format for a CHARACTER STRUCTURE with the utility program Font Converter supplied on your BASIC 8.0 disk. Chapter Five (37) All this program does is add a small header file to the beginning of the font so BASIC 8.O can tell what kind of STRUCTURE it is. (For information on file formats see the Appendix.) CHARACTER STRUCTURES must be loaded into memory with the @LSTRUCT/@SEND command. After that they are available whenever you need them. Continuing our program examples above: @LSTRUCT,6,8,9,AD,"FNT.TECH":REM STRUCT#,DRIVE#,BUFFER9,AD,name AD=@SEND :REM Get the font, AD = next Address in BUFFER 9 E) BRUSH STRUCTURES Perhaps the most useful type of STRUCTURE is the BRUSH STRUCTURE. This type allows you to @STASH and @FETCH a piece of the screen, any size, back and forth from memory. Of course you can also save it to disk, where it can be recalled as a BRUSH with the @LSTRUCT, or even displayed directly with the @DISPLAY command. BRUSHES can also be manipulated with the @CBRUSH (ChangeBRUSH) command. This can make flipped, reversed or mirrored images of your brush. Or use the @BRUSHPATRN command to make a copy of a BRUSH as a PATTERN STRUCTURE. @STASH,7,9,AD,0,0,100,100,0 :REM STASH screen 0,0-100,100 as brush structure #7. Do not compress the data. AD=next BUFFER 9 address @CBRUSH,7,0,0, 1:REM FLIP BRUSH IN MEMORY @SSTRUCT,7,8,"BRUSH.TWO" :REM Prepare to save BRUSH @SEND :REM Save To Disk as BRUSH.TWO AD=@BRUSHPATRN,7,8,9,AD :REM Make Pattern Structure #8 @FETCH,7,0,100,0 :REM FETCH FLIPPED BRUSH TO SCREEN A BRUSH can be loaded to a STRUCTURE and saved from a STRUCTURE. It can be returned to the screen with the @FETCH command, or loaded directly to the screen from disk with @DISPLAY. When loaded with the @DISPLAY command, the brush is returned to exactly where it was stored from, or you can specify the X and Y to load it to. Other areas of the screen are not affected. Chapter Five (38) CHAPTER SIX ADDITIONAL BASIC 8.0 COMMANDS BASIC 8.O offers a number of other interesting advanced commands. For example, if you have the extra 64K video ram installed for the 8563 video chip (the new C128D cones with it standard, older C128's do not) you can make use of the @SCROLL command. @SCROLL allows you to move in one of eight directions at any of 255 speeds and up to 255 units. The directions are up, up/right, right, down/right, down, down/left, left and up/left. The speed is from 0-254, where 0 is the fastest. Each unit of speed adds a 0.0255 second delay between increments. The X scroll unit is on the byte level, while the Y scroll unit is in pixels. Or, by beginning your parameter list for SCROLL with 255, you can move directly to a specified scanline. Use @SCROLL with virtual screens (screens wider than 640 or higher than 200) to move around. One very important aspect of any graphics system (language or application) is in getting what is on your screen to a printer. In order to make it easy, we have created installable printer drivers that allow you to create a hardcopy of the screen. The programmable command to do so is called HCOPY, and just as BASIC 8.0 is very flexible, so is it's hardcopy capabilities. There are 11 different printers that are directly supported by BASIC 8.0. The default (built in) is EPSON, but if your printer is different merely load in one of the other drivers. (See chapter on printers for instructions on installing a printer driver.) Since the screen size you can use with BASIC 8.0 can differ, and also since many printers have different dot densities and different horizontal resolutions, HCOPY was designed to allow Chapter Six (39) you to print in a variety of different ways. The syntax of HCOPY is: @HCOPY,Secondary Address,Height (l-4),Density (1-7),Rotation Flag The secondary address for printer bitmap mode differs from printer to printer. (See chapter on BASIC 8.0 printer drivers for secondary address of your printer.) The height flag is how large to make your printout, with 1 the smallest and 4 very tall. The density parameter allows you to change the dot density of your printer, if possible. (Not all printers have more than one density, but some like the EPSON and PANASONIC have seven different settings. By setting to a larger density, you can print an image smaller than it would have been in a lower density.) Finally, the rotation flag allows you to rotate the printed image 90 degrees. With some printers, like the Commodore MPS 801 or Seikosha 1000, the image is always rotated because these printers cannot even print 640 dots per line (the smallest horizontal screen resolution). To make it possible for even more printers to be supported, Chapter Eleven lists the assembly language source code for every printer driver. Experienced programmers can use these as a base to develop even more printer drivers. MOUSE, JOYSTICK and POINTERS BASIC 8.0 also offers mouse and joystick control, along with a very precise graphic pointer function. You choose between the mouse (the 1351 proportional mouse, NOT the 1350 joystick mouse) and a joystick with @MOUSE,1,DEVICE,X,Y[,Joystick speed]. This activates the IRQ controller reading routine. As long as it remains on it will then constantly update (internally) the position of the mouse or joystick. You can then find the current Chapter Six (40) X and Y value with the @MOUSE function. It will return the X or Y value, where it can be used to position the arrow with the @PTR,1,X,Y,PTR DEF# command. For example; @MOUSE,1,0,320,100 starts the mouse reader using the mouse and positions it at 320,100 @MOUSE,1,1,320,100,2 starts the mouse reader using the joystick and positions it at 320,100 moving 2 pixels @MOUSE,O turns off the IRQ mouse reader MX=@MOUSE,2,0 returns the current mouse x position to MX MY=@MOUSE, 2, 1 returns the current mouse y position to MY The pointer function has three basic forms. One turns off the pointer while the other two are used for positioning. @PTR,O Turn off the pointer and restore the old image. @PTR,1,MX,MY,PTR DEF (0-15) Turn on at NX,MY using the pointer definition given and "floats" over bitmap. @PTR,2,MX,MY,PTR DEF (0-15) Turn on at MX,MY using the pointer definition given and draws on the bitmap Programming the mouse/pointer system is quite easy. First you turn on the proper mode (mouse or joystick) at the location you want to start. Then just use the @MOUSE,2 command to find the X and Y positions, and set the pointer position to those locations. Here is a small example program that will initialize the mouse, and move the pointer as you move the mouse. 10 TRAP 140:REM PRESS RUN/STOP KEY TO EXIT PROGRAM 20 @WALRUS,O:REM 16K MODE 30 @MODE,O:REM USE MODE 0 SCREENS 40 @SCREEN,O:REM USE SCREEN 0, MONOCHROME 50 @COLOR,0,4,0:REM SET COLOR 60 @CLEAR,O:REM CLEAR SCREEN 70 @DRWMODA,1,0,0,0,0,0,0:@DRWMODB,0,0,0:REM JAM 1 MODE 80 MX=320:MY=100:REM INITIAL X,Y 85 OX=MX:OY=MY:REM SAVE VALUES 90 @MOUSE, 1,0,MX,MY:REM USE 1351 MOUSE 100 @PTR, 1,MX,MY,O:REM USE ARROW POINTER (0) AT MX,MY 110 MX=@MOUSE,2,0:MY=@MOUSE,2,1:REM FIND NEW MX,MY 115 IF MX=OX AND MY=OY THEN GOTO 110:REM ANY MOVEMENT? 120 @PTR,1,MX,MY,O:REM REP0SITION POINTER AT NEW MX,MY 125 OX=MX:OY=MY:REM UPDATE OLD VALUES 130 GOTO 110:REM CONTINUE TO CHECK FOR MOVEMENT 140 @PTR,O:@MOUSE,O:REM TURN OFF POINTER AND MOUSE READER 150 @TEXT:REM RETURN TO TEXT MODE Another useful command is @FLASH. This command allows you Chapter Six (41) to reverse a rectangular area of the screen, from 1 to 255 times. It is very useful for bringing something to a user's attention. If you are in monochrome mode, it reverses the bitmap. If you are in color mode only the color information is reversed (which is very fast compared to the bitmap flash). Another BASIC 8.0 command that is both exotic as well as useful is the command @ZOOM. This command allows you to fetch an uncompressed brush from memory as an enlarged version of the brush. And it can do so in a number of different sizes. Since BASIC 8.0 is a bitmap graphics language, it offers very little for use in 80 column text mode. However, there are two text commands. The first is @TEXT, which returns your program to text mode from graphics mode. It also re-initializes some of the various parameters back to their default values. For example, @ANGLE is set to 0,0,0,0 and @SCALE is set to 0. The other text mode command is @FONT. This command allows you to set the two character sets available in text mode to any font you wish. Just load in the font as a structure and specify in the @FONT command which structure to use as a font. It is downloaded to the 8563 chip, where it becomes available in text mode. Once a @TEXT command has been issued, the standard character fonts are restored, so it will be necessary to re-issue the @FONT command. Chapter Six (42) Chapter Seven Making A Distributable Disk The Run-Time Module The ability to give away (or sell) programs written with BASIC 8.0 centers around the RunTime Library supplied with your BABIC 8.O system. When you first booted your original disk, you were offered the option of making a Basic 8.0 Run Time Disk. If you. have not yet done so, you should get a blank disk and create one. If you have already done so, make a backup of the Run Time Disk. It is this disk that you are allowed to distribute. The Run Time Disk is a autoboot disk, meaning it will load and run when you boot the computer (if the disk is in the drive). The normal startup sequence will install the BASIC 8.0 Run Time System, then load and run the WI0S WORKBENCH (see Chapter Nine). To use your program under the WORKBENCH, save your program on the Run Time Disk with a filename that starts with the letters B8. and is followed with a filename less than 12 characters. For example, if your program is called 'CHARTMAKER' you would save it with the name B8.CHARTMAKER on the WORKBENCH disk. When the WIOS WORKBENCH is automatically ran on bootup, it will be able to find the CHARTMAKER program. However, you may want to have your program be loaded directly, bypassing the WIOS WORKBENCH. In that case, you will need to change one of the programs on the Run Time Disk. To do this, insert your working copy of the Run Time Disk. Save your program to this disk. Then load the program called: STARTUP and type LIST and press return. You will see the single line: 10 RUN "WORKBENCH" To change the bootup sequence in order to autoboot your Chapter Seven (43) BASIC 8.0 program, type the following line 10 RUN "filename" (RETURN) (the (RETURN) means press the RETURN KEY). The filename should be the name of your program. To make sure the new line has been entered correctly, type LIST and then RETURN. You should see 10 RUN "filename" as the only line in the program. If it is wrong, retype the line as instructed above and check it again. If it is okay, then type: SCRATCH "STARTUP" (RETURN) The C128 will ask: ARE YOU SURE? Y (RETURN) You reply Y and press return You have now erased the startup file. At this point you need to save the newly modified (with your filename in place of WORKBENCH) program as STARTUP. To do so type: DSAVE "STARTUP" (RETURN) You have now created a BASIC 8.0 Run Time Disk that will automatically load and run your program. As a registered owner of BASIC 8.0, you may give away this Run Time Disk, or sell it if you wish. Remember, this is the only way you may give away programs using the BASIC 8.0 language! Chapter Seven (44) Chapter Eight BASIC PAINT The 80 Column Color Paint Program Along with all the added programming capabilities of BASIC 8.0, you also get a complete graphics application. This program, written completely in BASIC 8.0, is called BASIC PAINT ( (c) 1987 WALRUSOFT ). BASIC PAINT has several very important uses. First and foremost, it is meant to be a stand alone graphics paint program, complete in every detail. You can use it simply to draw or paint pictures for your amusement or as a means of artistic expression. Secondly, it is meant to be an accessory to the BASIC 8.0 programmer. You can use it to create pictures, brushes, icons or patterns that can be used later in your own BASIC 8.0 programs. And finally, BASIC PAINT is meant to be an example of what you can do with the programming power offered by BASIC 8.0. As mentioned, BASIC PAINT offers all the standard computer paint package graphic functions (freehand draw, line, box, circle and polygon) found in most commercial programs. You can add text, fill areas (with solids and patterns) and print your pictures. But BASIC PAINT goes further than that. You can add 3D solids to your pictures, cut and paste to and from a clipboard, zoom in for precise editing, and even lock your image for later recall (lock acts like an oops function). You control the program with a pointer using either a mouse or joystick, you can change your pointer to eight different shapes, and can set the drawing modes in many combinations of draw, erase, complement and pattern. You can also draw using thick lines or very thin lines, with the exact size being up to you. BASIC PAINT works in all five graphic modes supported by Chapter Eight (45) BASIC 8.0. You have your choice of monochrome and the four color resolutions (8 x 16, 8 x 8, 8 x 4 and 8 x 2). And just like BASIC 8.O, BASIC PAINT supports the 1700 and 1750 external ram expansion modules. Even more exciting, if your C128 has the full 64K of video ram you can use BASIC PAINT to draw on several size virtual vertical screens. BASIC PAINT is designed to be simple to use, even intuitive In nature. It is essentially a mouse driven program, controlled By the mouse, the left and right mouse buttons and graphic icons. (Icons are pictures that represent a particular function.) By pointing to a icon and pressing the left mouse button (or the joystick button) you select that icon's function. At times you will want to indicate that you are finished doing something, or perhaps you will want to change your mind and return to the previous option. This is accomplished by clicking the right mouse button (or the ESCAPE key if you are using a joystick). This left button (for selection) and right button (for ESCAPE) system becomes very natural after a while. In fact, if you are using a mouse, the only keyboard input is when you are saving an image or if you want to shear a box. (If you are using a joystick the keyboard ESCAPE key is used instead of the mouse right button.) To use BASIC PAINT, simply insert the BASIC PAINT Work Disk In your C128 and boot it, either by turning on the computer or (if it is already on) by pressing the reset button. The program will autoboot, and you will quickly be presented with a special type of menu called a requestor (see Figure 1). This requestor menu is requesting information on how your computer is equipped, BASIC PAINT will work best with your system. (You should Chapter Eight (46) always keep your working copy of the BASIC PAINT disk in drive 8 when using it as it will often need to load requestors and menus from the disk.) -------------------------------------- ! Press M for Mouse J for joystick ! ! Video RAM: O 16k 0 64k ! ! System RAM: 0 128k 0 256k 0 640k ! ! Continue ! -------------------------------------- Figure 1 The first thing to do is indicate what type of controller you are using (see figure 1). If you have the 1351 mouse (inserted in port 1 only), press M. If you are using a joystick (inserted in port 2 only), press J. Once you have done so, you will notice an arrow pointer appear on the screen. You can now use your chosen control device to move this pointer, and the select button (left mouse button or the joystick button) to indicate your choices to the computer. Next tell the computer how much ram your 80 column video chip has installed. If your computer is a standard C128 and has not been modified, you have 16K. That is the default selection. If your C128 has had the 64K video ram installed (the C128D comes with the extra ram), point to the 64K box and click the select button (left mouse button). Notice how the box becomes black. This indicates you have now selected 64K of video ram. (WARNING! If you do NOT have 64K, it does no good at all to make this choice and choosing it will cause the program to work incorrectly.) Next, choose the amount of system ram your C128 has Chapter Eight (47) installed. If your computer does not have any extra ram you have 128K, the default. If you have the 1700 expansion cartridge you have a total of 256K, and if you have the 1750 cartridge you have a total of 640K. Point to the appropriate box and click the select button. If you have made a mistake and selected the wrong options, you can change them quite easily by simply pointing to the correct box and clicking the select button. Once you have the proper settings, point to the CONTINUE box and click the select button, and these values will be used by BASIC PAINT during this session. Once you have selected the CONTINUE box, BASIC PAINT will display a new requestor menu. Depending on your previous choices, you will be offered a selection of graphic screen type to choose from. ---------------------------- ! 0 640 x 200 monochrome ! ! 0 640 x 192 color 8 x 16 ! ! 0 640 x 176 color 8 x 8 ! ! 0 640 x 152 color 8 x 4 ! ! 0 640 x 104 color 8 x 2 ! ! Continue ! ---------------------------- Figure 2 If your system has 16K of video ram, the second requestor menu (Figure 2) allows you to choose one of five different screens. These are the same screens allowed in MODE 0 of BASIC 8.0 They differ on the size of the color cell and the total size of the screen. (See Chapter Two for more information on Chapter Eight (48) screens.) Choose the screen you wish to work with by pointing to the proper box and clicking the select button, then click on the CONTINUE box. You will then proceed to the main drawing screen. ------------------- ! 0 Monochrome ! ! 0 8 x 16 Color ! ! 0 8 x 8 Color ! ! 0 8 x 4 Color ! ! 0 8 x 2 Color ! ! Continue ! ------------------- Figure 3 If your system has the full 64K of video ram, you are also presented with a requestor menu (Figure 3) asking for the screen type, however no screen sizes are listed. Choose the screen type you want, you will then be presented with a third requestor menu that asks for the actual size of the screen you want. These third menus (see Figure 4-8) offer screens greater than 200 pixels high, although only a viewport of 640 x 200 pixels is visible at one time. When you are drawing the screen will automatically scroll up and down to keep up with the mouse. --------------- --------------- --------------- ! Monochrome ! ! 8 x 16 Color! ! 8 x 8 Color! ! 0 640 x 200 ! ! 0 640 x 200 ! ! 0 640 x 200 ! ! 0 640 x 300 ! ! 0 640 x 400 ! ! 0 640 x 300 ! ! 0 640 x 400 ! ! 0 640 x 600 ! ! 0 640 x 400 ! ! 0 640 x 500 ! ! 0 640 x 700 ! ! 0 640 x 600 ! ! 0 640 x 600 ! ! Continue ! ! Continue ! ! 0 640 x 800 ! --------------- --------------- ! Continue ! --------------- Figures 4-6 --------------- --------------- ! 8 x 4 Color! ! 8 x 2 Color! ! 0 640 x 200 ! ! 0 640 x 200 ! ! 0 640 x 300 ! ! 0 640 x 300 ! ! 0 640 x 400 ! ! 0 640 x 400 ! ! 0 640 x 600 ! ! 0 640 x 500 ! ! Continue ! ! Continue ! --------------- --------------- Figures 7-8 Chapter Eight (49) Figure 4-8 At this point the screen will display the WALRUS logo screen And indicate the amount of video ram you have chosen. It then clears and the BASIC PAINT drawing screen is created. <> Figure 9 This screen consists of the drawing area and a strip of icons (pictures) at the top of the screen (Figure 9). Each icon represents one or more graphic functions, and they can be selected by pointing with the arrow and clicking the select button. When additional choices are required, submenus will appear. You can make the additional selections, or use the right button to ESCAPE back one step. Once you have made your selection, the icon strip disappears and the screen is made available for your drawing activity. When you are finished with hat function, click the right button of the mouse to escape back to the menu(s) (or use the ESCAPE key if you are using the joystick). Here is a description of each function. FREEHAND DRAW To draw in a freehand mode, move the pointer to the first Icon in the icon strip. The wiggly line represents drawing. With the pointer on the icon, click the select (left mouse) button. The icon strip will disappear, leaving the entire screen available for drawing. To draw hold down the left mouse button and move the mouse. A line will follow the pointer's tip. When you wish to stop drawing, let off the button. You can then move Chapter Eight (50) to another location and start drawing again, or click the right mouse button (or ESCAPE key if using a joystick) to restore the icon strip. You will notice that the lines you have drawn are black on the grey screen. These are the default colors. You can change them with the color icon (be sure and set the JAM options in the drawmode icon properly). LINE The second icon represents the line function. To draw lines, point to this icon and click the select button on your controller. As before, the icon strip disappears. Point to where you want the line to start and click the select button. The pointer will disappear, leaving you with a flashing line. As you move the mouse this line will follow you, a process called rubber-banding. Move the tip of the line to where you want it to end, and click the select button. The line will quit rubber-banding, but will continue to flash. At this point you can click the select button to accept this line, causing it to be drawn in the current color and mode, or if you decide it is not what you want you can click the right mouse button and it will disappear. You can then either draw another line, or click the right button and escape back to the icon strip. You can also use the right button to escape while actually rubber-banding the line. You will notice that when you escape while rubber-banding the pointer returns to the exact spot where you started the line. And when you have actually drawn a line, it starts exactly where the line ends. BOX Box allows you to draw rectangles and works very much like the line function. Point to the box icon and click the select Chapter Eight (51) button. The icon strip disappears, and you are free to move the pointer to any spot on the screen. When you have the pointer where you want one of the corners of the rectangle to be, click the select button. Just as with line the pointer goes away, only this time you have a box that rubber-bands, not a line. If the starting location was not correct, click the right button to escape and start the box again, otherwise move it's corner to create the size and position you want. When it is just as you want it, click the select button and again you have a flashing box that is waiting for the select button to accept and be drawn or the escape button to cause it to be erased. However, box has a couple of extra features at this point. You can press the X or Y key, and this will allow you to shear the flashing box in the indicated direction. (Shearing means to move one side while holding the opposite side still.) This allows you to create more complex shapes. Once you have begun shearing you have the same options as in normal box mode, that is to select or escape. Once selected you can still escape and start over as before. When you have finished drawing your boxes you can use the right button to escape back to the icon strip. POLYGONS <<>> Figure l0 The circle icon represents the polygon menu. Select this icon and a new submenu (Figure 10) appears. This submenu has six icons, circle, ellipse, triangle, diamond, hexagon and octagon. You can select one of these by pointing and clicking at the Chapter Eight (52) desired object, or use the right button to escape back to the icon strip. If you chose circle, the icons disappear and you are free to move anywhere in the screen. Place the pointer on the spot where the center of the circle is to be and click the left button. The pointer is replaced with a rubber-banding line. This line represents the radius of the circle, which is the distance from the center of the circle to its edge. When you have the radius the size you want, click the left button and the circle will be drawn over and over. If it is correctly sized and placed, click the left mouse button, otherwise use the right button to escape and start over. You can repeat this as often as you wish. When you are finished, use the right button to escape back to the polygon submenu, where you can select another shape or escape again back to the main icon strip. The other five shapes (ellipse, triangle, diamond, hexagon and octagon) work somewhat differently. When they are selected, you again point to where the center is to be and click the left button. Only here, instead of a single line you get two lines. These represent the two different radius required for these types of shapes, the X radius and the Y radius. As you move the mouse (or joystick) you will notice they each change in length. With a little practice you can quickly become quite skilled at using this technique for these complex polygons. And as always, use the left button to select and the right button to escape back to the polygon submenu and main icon strip. SOLIDS Chapter Eight (53) <<>> Figure 11 The solids icon also represents a more complex submenu. When the solid icon is selected, a submenu (Figure 11) is presented that offers eight different shapes and two drawing styles. The shapes are sphere, horizontal, vertical and topview toroids, horizontal and vertical spools and horizontal and vertical cylinders. The two style options on the right side of the menu represent the type of texture (random or halftone). You change the texture freely from the menu by pointing and clicking with the left selection button. Sphere is controlled just like circle. Point to where the center is to be and click the left button. The pointer is replaced with a single line, (the radius). Move the line to make the proper radius, then click the left button. A beautiful solid sphere will be quickly drawn. Once it is finished, you can create another or click the right button to escape back to the solids submenu. The other solids use the two line radius method. In the case of the horizontal and vertical spools, cylinders and toroids, they are fairly straight forward and easy. The topview toroid also uses two lines, but in this case they represent the inside radius and the outside radius. It is possible to select it such that the outside radius is smaller than the inside, an obvious impossibility. In that case the pointer appears as a question mark for a couple of seconds, meaning essientially "Say What?". Practice using the solids for a while and their use will Chapter Eight (54) become quite clear and easy. Use the right button to escape to the submenu, where you can select a different shape or escape again to the main icon strip. CUT The icon shaped like a pair of scissors is used to cut a rectangular area of the screen to the clipboard area, where it can be copied (pasted) to another location, or saved to disk as a brush (from the disk menu), or even used as a pattern for the fill function. CUT does not erase the area you have selected. To cut an area, select the cut icon and position the pointer at one corner of the desired rectangle and click the left button. The pointer is replaced with a rubber-banded box, which you then use to enclose the area you want to put in the clipboard. Again use the left button to select, and the box will be adjusted to the boundaries required by the graphic mode you are in (color modes always round up and down to the edges of the color cell, and the rectangle must always begin and end on an even byte boundary. For more information on this see GRID mode in the drawmodes section.) At this point you can accept by clicking with the left button, or reject and escape with the right button. Once you have selected, you can then escape back to the icon strip, or replace the current contents of the clipboard with a new object. You can only have one item in the clipboard at a time. PASTE The paste jar icon is used to paste (copy) the contents of the clipboard back on the screen. To use point to the paste jar Chapter Eight (55) icon and click the left button. Then point to the position where you want the upper left corner of the clipboards object to be and click the left button to paste it on the screen. You can repeat this as often as you wish, making many copies of a single object. When you are finished, click the right button to escape back to the icon strip. When pasting while in the color modes, keep in mind that the color memory of the object has been stored in the clipboard as well as the bitmap. So if your pasted object overlaps upon an area with a different set of colors than that found in the clipboard, the old screen colors in that area will be replaced with those of the stashed object. TEXT Choosing the text icon loads another submenu. This one offers a number of different fonts, as well as allowing you to set the height and width of the font you are using. To select a font, point to the one you want and click the select button. It will be loaded into the memory of the computer where it can be used. To change the height, point to the letters Ht and click once. Then click on the up or down arrows to change the height. To change the width, point to the letters Wd and click once. Again, the arrows are used to increase or decrease the width of the character. If you have selected the special 160 column font, set your width to 0. (This is the only time the width should be less than 1.) When you are ready to type your characters, point to the word DRAW and click once. The menus disappear, and you can position your letters with the mouse pointer or with the keyboard Chapter Eight (56) cursor keys. Wherever the pointer rests is the top of the character cell. You may type whatever you wish. Pressing RETURN moves the cursor down one line and flush left on the screen (if there is enough room to do so). To exit this mode press the escape button. Remember, the text responds to the draw modes DRAW and COMPLEMENT in the DRAWMODE submenu. FILL The FILL icon is used to paint an enclosed area with either a solid color or the current pattern, depending on the drawmode in use at the time of the fill action. To fill just point at the icon and click with the select button. The icon strip disappears and the pointer can be moved to any spot on the screen. Point to a spot within the area to fill and click the select button. (Remember to only fill a completely enclosed area, as it will leak out and fill the whole screen!) The area will then be filled. When it is finished you can repeat it again, or escape back to the main icons. ZOOM The ZOOM icon (it looks like a magnifying glass) allows you to zoom into a small area for editing. Point to it and click on the select button. The icon strip is removed and you can then move to the general area you wish to edit. Once there click the select button and a box will appear. You can then move the box to enclose the exact area you wish. Click the select button again, and a ZOOM window will appear, and it will fill with the magnified image of the smaller box's contents. Once it is filled you can move the mouse to the points you wish to edit and change them by clicking with the select button. If the pixel is already on it is turned off, if off it is turned Chapter Eight (57) on. The dot will be in the current color and drawmode. To change these there are icons to change color and drawmode outside the ZOOM window. Once you are finished editing, use the escape button to close the ZOOM window. You can then ZOOM into another area, or escape back to the main icon strip. NOTE: ZOOM does not work in 8 x 16 mode! DRAWMODE <<>> Figure 12 The DRAWMODE icon represents a second submenu (Figure 12). Once selected this menu appears and you can select the functions You want. One set of functions is called the COLOR JAMS. These Set the various JAM modes. Jam0 uses the color information found On the screen, and it ignores your choice of colors in the icon strip. Jaml uses your foreground color choice, but ignores your background color. Instead it uses the background colors it finds in the area you are drawing in. JAM2 uses both of your current color choices, foreground and background. The other set of modes concern the type of bitmap drawmode You wish. These are DRAW, ERASE, COMPlement, Pattern, Trail and GRID. Draw is the normal drawing mode. This simply means you want To draw in normal mode using a solid line. Complement mode produces a reverse image. The points that Chapter Eight (58) are already off are turned on, those on are turned off. (You will notice that the pointer also responds to this mode.) Erase sets the mode to turn off all points that you draw on. Use this mode to remove (unpaint) an area. If you want you can change the pointer from the arrow to another definition (from the main icon strip) in order to make a larger eraser. Pattern mode turns on and off the pattern drawmode. When off all drawing and filling is done in solid mode. When on the current pattern is used when drawing. Trail mode is used when in freehand drawing. Instead of drawing it leaves a trail of the current pointer definition. Trail always uses the JAM0 mode, regardless of the settings in the JAM options. Grid sets the drawing mode to a grid. The grid is always 8 pixels wide, and is as tall as the color cell size. This is very useful when cutting and pasting, as it allows you more precision when performing these functions. One addition feature is found in the DRAWMODE menu. This is the line height. You can change the line thickness by pointing to the up or down arrows, changing the line size found in the box. LOCK Lock allows you to store a copy of the screen in memory (if you have the available memory free in the form of the 1700 or 1750 ram cartridges) in case you wish to restore it later after making some change you don't like. Once a screen is locked, you can restore it by choosing the CLEAR SCREEN option. UNLOCK Unlock turns off LOCK mode, allowing you to completely clear Chapter Eight (59) the screen. DISK The DISK icon loads a submenu that makes available many disk functions, as well as the ability to convert brushes in the clipboard into patterns. LOAD PICTURE Loads a directory of available brushes to be loaded as pictures. Just point and select, or return to the MAIN MENU. SAVE PICTURE An input box opens where you type in a filename to save the current picture to the currently selected drive. The name should start with 'PICT.'. LOAD BRUSH Load a directory of brushes that can be loaded into the clipboard as brushes, or you can return to the MAIN MENU. SAVE BRUSH An input box opens where you type in a filename to save the current clipboard to the currently selected drive. The name should start with 'BRUS.'. LOAD PATTERN Load a directory of patterns that can be loaded into the pattern clipboard, or you can return to the MAIN MENU. SAVE PATTERN An input box opens where you type in a filename to save the current pattern clipboard to the current drive. The file should begin with 'PATR.'. BRUSHTOPATTERN This copies the contents of the brush (CUT & PASTE) clipboard to the pattern clipboard, where it can be used as a pattern (if pattern is set in DRAWMODES) or it can be saved as a pattern using SAVE PATTERN. DIRECTORY Loads a directory of all files on the current disk. CHANGE DEVICE Change your disk drive from drives 8-12. CAUTION: BASIC PAINT requires the disk with it's files and requestors to always be in device 8. By changing the device, you only change the input./output of user created files (brushes, pictures and patterns). When a menu requestor is needed it will still be loaded from device 8. CHANGE DRIVE Switches between drive 0 and 1 for users of dual drives. BASIC PAINT menu requestors will always be loaded from drive 0. PRINT The PRINT icon displays a submenu that requests several Chapter Eight (60) types of information. It asks for the HEIGHT of the printout, which can be up to 4. It allows you to set the DENSITY of the printout from 1-7. You can set the hardcopy to be rotated or unrotated, and you can set the secondary address to whatever your printer (and interface) requires for graphics screen dumps. And it allows you to switch between the various printer drivers. (If you change the printer type the appropriate driver will be loaded from disk and installed.) When you have the settings you want press the ESCAPE button and you will be presented with a small requestor that simply says PRINT. If you still want to print, point at it and click the select button. (Make sure you have your printer hooked up and turned on.) If you wish to change your mind click the ESCAPE button and you will abort the printing process. The next time you return to the PRINT submenu it will remember your last settings. See Chapter 11 on printers for information on your specific printer. COLOR Colors are set by the FG/BG color box. To change these colors, point at the top of the box (for ForeGround) or the bottom (for BackGround) and click the select button. If you are using monochrome, the entire display will change as a result. If you are in color mode, only the contents of the color box will reflect the new colors. However, if you draw (while in JAM1 or JAM2 DRAWMODES) you will use these selected colors. CLR The CLR icon is used to clear the display. If in color mode it clears the image using the current colors for foreground and background. However, if the screen has been LOCKed, clicking on Chapter Eight (61) clear will simply restore it to the LOCKed image. EXIT The EXIT icon will open a small window in the upper left side of the screen. You may exit the program completely start it again (perhaps to draw in a different mode). Or, if you change your mind you can click the ESCAPE button and return to drawing. ***************************************************** Finally, if you are at the main icon strip there are a couple of additional features you can access from the keyboard. 1) If you are using a joystick, you can change your drawing speed by pressing the +/- keys. (The faster you draw with the joystick, the coarser the resolution.) 2) You can change the pointer to one of eight definitions by pressing the ALT key and one of the keys 0-7 (at the same time). There are several interesting shapes, some of which you may prefer to the arrow. If your pointer seems to disappear when it is inside a solid color area, remember it is NOT a sprite. It shares the same color memory as the image it rests upon. To make it always visible, set the draw mode to COMP. However, when drawing the complement mode draws on areas where the bitmap is empty, and reverses where it is already on. COMPLEMENT mode is not always the best choice when, drawing, but it does offer some interesting effects. If you have questions about BASIC PAINT's screens and modes, see Chapter 2 for further information. Chapter Eight (62) Chapter Nine WIOS WORKBENCH And Other Supplied Utilities WIOS WORKBENCH The WIOS (Walrusoft Icon Operating System) WORKBENCH is really nothing more than a BASIC 8.0 program. It uses a few of the new commands, along with some standard BASIC 7 commands, to emulate the increasingly popular graphics user interface. It will load and run any program written in BASIC 8.0 that starts with the letters B8. and are followed by a filename that does not exceed 12 characters. The WIOS WORRBENCH supports up to 4 disk drives, including the 1541, 1571 and 1581 drives. When it is first run it checks to see how many disk drives are present, then puts up on the screen a simple requestor that asks if you are using a mouse (port 1) or a joystick (port 2). Press the appropriate key (M or J) and you will then see one or more disk icons labeled DRIVE N (N is 8-11). The arrow pointer is also active. By moving the control device (mouse or joystick) the pointer will move. To see the contents of a drive, move the pointer to the drive you want and press the left mouse button (or the joystick fire button). (Make sure there is a disk in the drive!) Once you have pressed the button, a window will open and some brief disk activity will occur. If any files are found (that start with BB.XXXXX) the name of the file and a small icon that looks like a flowchart is shown in the window. A total of ten files can he seen in the window at one time. If there is more than 10 files, you can see t.hem by putting the arrow pointer on the little scroll arrows (at the bottom of the window) and clicking the left mouse button (or joystick fire button). If Chapter Nine (63) there are any more files, the screen will shift and the new files be displayed. To move back the other direction, click on the other scroll arrow. If you see the program you want, just point to it and click the button and it will load and run. If the file you want is not there, point to the close gadget In the upper left corner of the window (NOT THE SCREEN!) and click the button. This will instantly close the window. You can point to another disk icon, or remove the disk from the drive and insert another and repeat the process. If you want to exit the WIOS WORKBENCH, use the close gadget In the upper left corner of the screen. Clicking on this gadget will close the screen and return to text mode. If you want to run it again, insert the disk with the WORRBENCH and type: RUN "WORKBENCH" The WORKBENCH program, like many of the supplied programs written in BASIC 8.0, is meant to be both useful and instructive. It is a real (although somewhat limited) graphic interface. It allows a user to load BASIC 8.0 applications quickly and easily, even if they don't even know how to find a directory by the normal methods. For that reason, it is the standard startup program on your BASIC 8.0 RUNTIME DISK (It is also on the BASIC 8.0 WORK DISK). All you (the BASIC 8.0 programmer) have to do to share your programs is to DSAVE them to the runtime disk with the name B8.XXXXX and the WORKBENCH will allow users to simply boot, point, click and go! However, like all the supplied BASIC 8.0 programs, the WORKBENCH is meant to be instructive. It demonstrates many aspects of programming in BASIC 8.0, and is a good place to look for examples of using the language. Chapter Nine (64) BASIC 8.0 Utilities PICT CONVERTER/FONT CONVERTER/LOGO MAKER This is a set of utility programs that are used for various special functions. The PICT CONVERTER allows you to convert pictures made with ULTRA HIRES (an early graphics language for the 80 column C128) to BASIC 8.0 format. The FONT CONVERTER will convert a standard 40 column font created with any C64/C128 font editor to the BASIC 8.0 structure format. The font must be a simple binary file. Once converted, it can be loaded with the @LSTRUCT command in BASIC 8.0 programs. The LOGO MAKER utility allows you to make LOGO structures that can be loaded directly with the @LSTRUCT command. Just follow the prompts and it will do all the work of creating your LOGO. Chapter Nine (65) CHAPTER TEN - THE BASIC 8.0 COMMAND ENCYCLOPEDIA 04/10/87 @ANGLE Angle will perform a rotation of how your object (line, box, circle, dot and arc) is viewed around the X,Y,Z axis. Your data remains unchanged, but the result is one of a 3D transformation around the given axis in the given rotation sequence. This rotation occurs when you render graphics. SYNTAX: @ANGLE,X angle, Y angle, Z angle, Rotation Sequence X angle - -360 to 360 X angle of rotation Y angle - -360 to 360 Y angle of rotation Z angle - -360 to 360 Z angle of rotation Rotation Sequence - 0-5 Order in which rotation about the various axis is performed. Different sequences give different results. If rotation sequence is greater than 5 than rotation sequence defaults to 0. Sequence # Rotation Sequence 0 XYZ 1 XZY 2 YXZ 3 YZX 4 ZXY 5 ZYX Chapter 10 - The BASIC 8.0 Library (66) @ARC Used to draw ellipse, arcs, polygons, pie wedges, subtended arcs SYNTAX: @ARC, Center X, Center Y, Center Z, X radius, Y radius, Starting Angle, Ending Angle, Increment, Thickness, Subtend Flag Center X - 0-65535 X center of arc. Center Y - 0-65535 Y center of arc Center Z - -32768 to 32767 Z center of arc X radius - 0-65535 Radius of arc in horizontal direction. Y radius - 0-65535 Radius of arc in vrtical direction. Starting angle -360 to 360 angle at which to start arc Ending angle -360 to 360 angle at which to end arc Increment 1-180 smoothness of the arc (angle between lines) 1-8 very smooth 30 12 sides 45 8 sides 60 6 sides 90 4 sides 120 3 sides Thickness - 0-65535 Number of times the @ARC is drawn stepping by the value defined by the @GROW command. Subtend flag - 0-1 0 = do not subtend arc Non 0 = draw lines from starting and ending angle To center of arc. ARC is rotated, scaled and clipped (if necessary) before being drawn. Chapter 10 - The BASIC 8.0 Library (67) @BOX Draw a box or rectangle SYNTAX: @BOX,X1,Y1,Z1,X2,Y2,Z2,Shear direction, Shear value, Thickness X1 - 0-65535 Corner 1 X coordinate of box. Y1 - 0-65535 Corner 1 Y coordinate of box. Zl - -32768 to 32767 Corner 1 Z coordinate of box. X2 - 0-65535 Opposite diagonal corner X coordinate of box. Y2 - 0-65535 Opposite diagonal corner Y coordinate of box. Z2 - -32768 to 32767 Opposite diagonal corner Z coordinate of box. Shear direction 0-2 0=no shear 1=X shear (move corners 3&4 right or left) 2=Y shear (move corners 2&3 up or down) 3 X & Y shear 4 or greater produces a value of 0-3, depending on the valueAND3. Shear value -32768 to 32767 number of pixels to move the affected corners depending on direction of shear. Thickness - 0-65535 Number of times the box is drawn stepping by the value defined by the @GROW command. BOX is rotated, scaled and clipped (if necessary) before being drawn. Chapter 10 - The BASIC 8.0 Library (68) @BRUSHPATRN Convert a brush to a pattern. Allows any piece of a screen to be used as a pattern for the paint command. SYNTAX: @BRUSHPATRN,Brush Structure #, Pattern Structure #, Buffer #, Address Brush Structure # - Brush # to convert to pattern Pattern Structure # - Destination pattern structure 0-191 Buffer - Buffer to store the structure Address - Address in Buffer for pattern @BRUSHPATRN works on any uncompressed brush that is no more than 255 bytes (2040 pixels) wide and 255 scan lines (pixels) deep. If the brush is color, the pattern is color. A=@BRUSHPATRN,0,1,2,1024 IF A=-1 then wrong structure type or brush is compressed. ELSE A=next address in the destination pattern buffer. Chapter 10 - The BASIC 8.0 Library (69) @BUFFER Defines an area in each bank to be used as data storage of Structures. SYNTAX: @BUFFER, Buffer #, Beginning Address, Size Buffer # - 0-9 Indicates which of the 10 banks to use 0 System Ram Bank 0 1 System Ram Bank 1 2-9 Expansion Ram Banks 0-7 * Buffer numbers greater than 9 default to 9. * Beginning Address - 0-65535 Indicates where BUFFER will begin in designated bank. Size - 0-65535 Indicates the amount of continuous ram to be used as a BUFFER. NOTE: @BUFFER doesn't check if size is greater than the amount left after the beginning address is defined. For example: @BUFFER, 1,32000,65535 Buffer starts at 32000 for 65335 bytes This will give unpredictable (and probably unpleasant) results Chapter 10 - The BASIC 8.0 Library (70) @CBRUSH Change a non-compressed BRUSH in memory SYNTAX: @CBRUSH,STRUCTURE #,REVERSE, REFLECT, FLIP Structure # 0-191 Number of STRUCTURE with BRUSH data REVERSE 0-1 0 No Reverse 1 Reverse REFLECT 0-1 0 No Reflect 1 Reflect FLIP 0-1 0 No Flip 1 Flip Once a BRUSH is modified with @CBRUSH, you can @FETCH it to the screen in its new form. You can combine the commands to do several actions at once. If structure is wrong type or compressed, -1 is returned. ex., e=@chrush,structure#,reverae,reflect,flip Chapter 10 - The BASIC 8.0 Library (71) @CHAR Outputs a text string to the 8563 bitmap screen. SYNTAX: @CHAR, Structure #,Column,Row,Height,width,Direction,"Character string" structure # 0-191 indicate a ram resident font in a user defined structure. 254 indicates uppercase/lowercase ROM font. 255 indicates uppercase/graphics ROM font. Column 0-255 Horizontal column number Row 0-819 Vertical scan line (pixel) Height 1-16 Height of character Width 0-16 Width of character 0 indicates 160 col char set Values greater than 16 default to 16. Direction 0-7 Indicates direction to print 0 Print up 1 Print up & right 2 Print right 3 Print down & right 4 Print down 5 Print left & down 6 Print left 7 Print left & up Greater then 7 becomes 0-7 String Text string to print. String can contain special control codes embedded within the character string to be printed. These control codes are created by pressing the CTRL key and the indicated letter. CONTROL CODES CTRL-B Blank cell under character CTRL-I Inverse cell (AND) with character CTRL-0 Overwrite cell (OR) with character CTRL-X Complement cel1 (XOR) with character CTRL-F Flip character upside down (Toggle) CTRL-P Pattern character (Toggle) CTRL-U Underline character (Toggle) CTRL-Y+ Rotates character left 90 degrees CTRL-Y- Rotates character right 90 degrees CTRL-Y Resets character upright CTRL- Z Mirror Image character (toggle) CTRL-RVS ON Reverse on CTRL-RVS OFF Reverse off COLOR CTRL CODES CTRL-C By itself turns Jam 0 color control on CTRL-CForeground Color Sets character color (Jam l) CTRL-CForeGroundBackground Color This is Jam 2 mode. Foreground or Background color is set by pressing Chapter 10 - The BASIC 8.0 Library (72) the CTRL Key or CBM Key and the appropriate color key. CTRL-Cursor Up,down,left,right These work on a 8 X 8 cell only SHIFTED CLR Clears screen with last FC/BG colors. HOME Places cursor at 0,0 position in window. FULL CHARACTER WRAP IS SUPPORTED IN OUTPUT WINDOW IN ALL DIRECTIONS. Chapter 10 - The BASIC 8.0 Library (73) @CIRCLE Draws a fast circle. SYNTAX: @CIRCLE,Center X,Center Y,Center Z,Radius,Thickness Center X - 0-65535 X center of circle Center Y - 0-65535 Y center of circle Center Z - -32768 to 32767 Z center of circle Radius 0-65535 radius of circle Thickness - 0-65535 Number of times the circle is drawn stepping by the value defined by the @GROW command. CIRCLE is rotated, scaled and clipped (if necessary) before being drawn. The @CIRCLE command produces a symmetrical circle, but in SCALE 0 it will appear to be an ellipse (due to the unsymmetrical y direction). Setting SCALE to 1 or 2 will allow you to make a proper circle. Or use @ARC with the x radius and y radius adjusted accordingly. Chapter 10 - The BASIC 8.0 Library (74) @CLEAR Clear the bitmap screen SYNTAX: @CLEAR,Bitmap Fill Value[,Background Color,Foreground Color] Bitmap Fill Value - 0-255 Fills bitmap area with given value 0 clear window 1 Only the windows color information is affected, bitmap image is untouched. 255 solid window 2-254 various vertical striped windows result Color parameters are optional. If omitted current colors are used. Background Color - 0-15 Sets Background color Foreground Color - 0-15 Sets Foreground color If a window was opened with the border flag set, every time the window is cleared the border is drawn in the current drawmode on the inside boundaries of the window. This will continue to occur until the window is closed. Chapter 10 - The BASIC 8.0 Library (75) @COLOR Defines colors for foreground, background and border SYNTAX: @COLOR, background color, foreground color, outline (border) color Background color : 0-15 See color table Foreground color : 0-15 See color table Outline Color : 0-15 See color table NOTES: Outline color achieved only in multicolor modes. COLOR TABLE 0 Black 1 Dark Grey 2 Blue 3 Lite Blue 4 Green 5 Lite Green 6 Cyan 7 Lite Cyan 8 Red 9 Lite Red 10 Purple 11 Lite Purple 12 Brown 13 Yellow 14 Lite Grey 15 White If using monochrome mode the effect of the @COLOR command will be to change the display colors immediately. In color modes the border will change at once, but only subsequent graphic commands will use the new colors. Chapter 10 - The BASIC 8.0 Library (76) @COPY @COPY moves a rectangular area of screen to any other defined screen area. It uses the 8563 block write capabilities, and is very fast. It works on the column (8 pixel) level horizontally and scan lines (pixels) vertically when in monochrome. When in color the y values are adjusted to the color cell size. SYNTAX: @COPY, Source Screen, Start X, Start Y, DX, DY, Destination Screen, EX, EY Source Screen : 0-7 as defined by @MODE or @SCRDEF Start X : 0-2047 Defined as pixels, but rounded down to nearest column. Start Y : 0-819 Defined as scan lines (pixels) but rounded down to color cell. DX : Distance in pixels, rounded up to columns DY : Distance in scan lines (pixels) rounded up to next color cell. Destination Screen : 0-7 as defined by @MODE or @SCRDEF EX : Ending X at destination screen, rounded down to nearest column EY : Ending Y at destination screen, in scan lines (pixels) **** NOTE **** @COPY WILL NOT WORK RELIABLY WHEN VIEWING A VIRTUAL HORIZONTAL SCREEN GREATER THAN 640 PIXELS. YOU MAY VSE @COPY ON A VERTICAL VIRTUAL SCREEN, BUT @COPY WILL ONLY WORK ON VIRTUAL HORIZONTAL SCREENS IF YOU ARE VIEWING A NON-VIRTUAL HORIZONTAL SCREEN. FOR EXAMPLE, IF YOU HAVE TWO 8CREENS, ONE THAT IS A HORIZONTAL VIRTUAL OF 1280 X 200 AND ANOTHER THAT IS 640 X 400 VERTICAL VIRTUAL. YOU CAN @COPY ON THE 1280 X 200 IF YOU ARE VIEWING THE 64O X 400. ATTEMPTS TO @COPY OM THE 1280 X 200 WHILE VIEWING IT WILL CAUSE THE COPIED BITMAP TO BE DISTORTED. THIS IS DUE TO A BUG IN THE 8563 ADDRESS INCREMENT PER ROW REGISTER. IF START X,Y PLUS DX,DY IS OUT OF BOUNDS THEN SOURCE RECTANGLE COPIED IS CLIPPED. IP END X,Y PLUS DX,DY IS OUT OF BOUNDS THEN DESTINATION RECTANGLE IS CLIPPED AND X,Y,DX,DY,EX,EY ARE SCALED IF NECESSARY. Chapter 10 - The BASIC 8.0 Library (77) @CYLNDR Draw solid cylinder SYNTAX: @CYLNDR,X,Y,Radius,Halflen,View X 0-Xmax Y 0-YMax Radius 1-255 Halflen 1-128 View 0/1 type of cylinder 0 horizontal 1 vertical Chapter 10 - The BASIC 8.0 Library (78) @DIR$ Read a directory entry Requires considerable setup from basic SYNTAX: L=@DIR$ @DIR$ returns a string to the first variable in your program. The variable must be a string type. @DIR$ returns a value equal to the length of the string found. You must use the LEFT$(VAR$,L) to remove any trailing null values. Here is an example routine that will search the directory for all BRUS. files. VARIABLE DESCRIPTIONS dn=device# sd=drive side (0 or 1) dp$= directory pattern to seek de=directory index variahle = ends up as last index in de$() de$=directory entry variable...This must be first variable in your program. 10 de$=" ":rem de$=16 spaces 20 dim de$(244):rem maximum number of possible files 30 dp$="brush.":rem look for brush files 40 dn=8:sd=0:rem drive 8, side 0 50 de=0:rem number of directory entries 60 open 3,dn,O,"$"+mid$(str$(sd),2)+":"+dp$+"*" :rem open file 70 1=@DIR$:rem 1 is the length of the string now in de$ 80 if st<>0 then 110 90 de$(de)=left$(de$,1) 100 de=de+1:goto 70 110 close 3 120 rem print out all found entries 130 for i=O to de:print de$(i):next i The pattern used in the open command is a wildcard used to search for specific files. To get all the files on a directory, just use the $ as the search string. The variable sd is used in case of a dual drive. And the array used to store the filenames, DE$(244) is dimensioned to the number 244 in order to work with the 1581 disk drive, which can store a larger number of file entries than the 1541 or 1571 disk drives (144 each). Chapter 10 - The BASIC 8.0 Library (79) @DISPLAY Recalls a @STOREd screen or brush to the designated screen at the location from which it was stored or a specified location. SYNTAX: @DISPLAY, SCREEN #, DEVICE #, DRAWMODE, "FILENAME" [,X,Y] SCREEN# - The number of the screen the file is to be loaded to. It does not have to be the screen you are currently viewing. DEVICE # - The drive number you are using, ex. 8 DRAWMODE - 0-3 0 Erase under (replace) 1 Merge with (OR) 2 Common (AND) 3 Complement (XOR) FILENAME - The name of the screen or brush to load. It will be loaded to the area of the screen it was saved from (i.e., the same X,Y coordinates). X,Y - Optional screen locations to display brush to. NOTE: If you use the optional X,Y parameters for displaying a brush to a position other than the default values, there is one thing to watch for. If Y is greater than the original Y it was saved from, (0 in the case of a picture, the Y hotspot in the case of a brush), then THERE IS NO CLIPPING PERFORMED IN THE Y DIRECTION!. So be sure your brush or picture will fit in the area and not overrun the bottom of the current screen display. If it does, unusual (and probably visually unpleasant) screen effects occur. This will happen only with @DISPLAY. Chapter 10 - The BASIC 8.0 Library (80) @DOT Plots a single pixel in 3 space SYNTAX: @DOT,X,Y,Z X - 0-65535 X coordinate of point. Highest visible X is equal to Xmax of virtual screen, or Window width. Y - 0-65535 Y coordinate of point. Highest visible Y is equal to Ymax of virtual screen, or Window depth. Z - -32768 to 32767 Z coordinate of point. Z value of 0 is the plane of the screen. Positive values are directed into the screen, while negative vales are directed towards the viewer. DOT is rotated, scaled and clipped (if necessary) before being drawn. Chapter 10 - The BASIC 8.0 Library (81) @DRWMOD Two Commands to define global drawing modes to be used with graphic commands. SYNTAX: @DRWMODA,Jam,InverseVideo,Complement,Undraw,Pattern,Merge,Clip @DRWMODB,Zview,Unplotlast,Unplotvertex Jam : 0-2 Updates color memory when drawing on a color screen. 0 Uses foreground/background colors found in cell.(Fastest) 1 Uses background color in cell and foreground color set by @COLOR command. 2 Uses foreground/background colors set by @COLOR command. InverseVideo : 0-1 Reverses colors set by Jam option. 0 off 1 on Complement : 0-1 Turns on XOR mode. Pixels on are turned off, pixels off are turned on. 0 off 1 on Undraw : 0-1 Turns on erase mode. Actually unplots all pixels. 0 off 1 on Pattern : 0-1 Uses previously defined pattern when drawing. 0 off 1 on Merge : 0-1 Merge pattern with screen using OR mode, pixels on are unaffected. 0 off 1 on Clip : 0-1 Turns on and off global screen/window clipping. 0 on 1 off ***NOTE*** The default is 0, CLIPPING ON. Turn it off for an increase in drawing speed. ***** DRWMODB values may be used in any combination ***** Zviev : 0-1 Turns on either parallel or perspective 3D 0 Perspective on (objects drawn toward vanishing point appear smaller as they approach it). 1 Parallel on. Retains object shape and size but it is offset based upon Z coordinate. Unplotlast : 0-1 Unplots last iteration of a multi-height drawing of a graphic primitive (i.e., lines, circles, boxes etc). Used to make 3D bars from boxes. 0 off 1 on Unplotvertex : 0-1 Unplots vertexs of graphic primitives (i.e., circles, arcs, boxes etc) Also used to give 3D appearances of bars, tubes etc. Chapter 10 - The BASIC 8.0 Library (82) @FETCH To recall a @STASHed area to the display screen. SYNTAX: @FETCH,STRUCTURE #,X,Y,DRAW MODE STRUCTURE # - 0-191 The structure # used when @STASHing X - The screen X location to recall the BRUSH to. X is rounded down to the start of the current