 ----------------    -- The *ULTIMATE* ANSI Editor ---    -------------
                                                            
߲  ߲߲߱  ߰ ߰  ߲߱߱   ߲
                
           
    n            
     c          
  ߰                  
  ް               
ܰܰ߰           ܰ  ܰ  ܰ
                                                                
                                                                           
                            Written and Designed by:
                      HOOPTiE (hooptie@cibola.net)                      
 ܰ                                                                     ܰ
                          Interface Design and ArtWork:
                      Nivenh, Stone the Crow, and Neurotic

TABLE OF CONTENTS -----------------------------------------------------------

1.0 GENERAL INFORMATION
    1.1 Legal Disclaimer
    1.2 Description and Requirements
    1.3 Prototype/Beta Notice
    1.4 Registrations

2.0 ARTWORX BASIC PRINCIPLES
    2.1 Command line options
    2.2 Editing Keys
    2.3 Command Keys
    2.4 Option Keys

3.0 USING ARTWORX
    3.1 File Commands - Loading, Saving, and Merging.

4.0 THE OPTIONS MENU

5.0 VGA MODE EDITOR
    3.1 How the VGA Editor works
    3.2 Using the mouse

7.0 ARTWORX DATA STRUCTURES
   7.1 .AN2 (ANSI/2) Specifications and Structure
   7.2 .ADF (ArtWorx Data Format)
   7.3 Programming a .ADF Viewer (Pseudo Code)
   7.4 TextColor Conversion Chart
   7.5 Setting the VGA Palette in C++
   7.6 Initializing the VGA Font in C++
   7.7 Turning on iCEColor in ASM/C++
   7.8 Setting up characters 8-bits wide in ASM/C++
                        
GENERAL INFORMATION --------------------------------------------------- [1.0]

   The following information is provided as general information about
ArtWorx, Sector Logic, registration, etc.  If there are any questions,
comments, suggestions, or bug reports, please send mail to 
hooptie@cibola.net.

LEGAL DISCLAIMER                                                        [1.1]
   
   Sector Logic (refered to as "SL") grants the Purchaser and the 
Purchaser accepts a non-transferable and non-exclusive license to use, on 
a single computer, ArtWorx and accompanying materials provided to the 
Purchaser by SL.  The Purchaser is hereby licensed only to read the 
program from its medium into the memory of a single computer soley for the
purpose of executing the program.  Sector Logic and its appointed
associates reserves the right to terminate the license at any time without
cause or warning if the Purchasers violates any of the licensing provisions.  
Purchaser agrees that the Software Products and accompanying materials are 
sole property of SL and that SL maintains title to and ownership of the
Software Products at all times.  Purchaser agrees to make no more than one
(1) working copy and one (1) backup copy for personal use only.  Except as
indicated above, ArtWorx, its accompanying data files, and additional 
documents may not, in any part or in whole, be copied, reproduced, 
translated, or distributed to other parties.

  Sector Logic makes no warantees or guarentees of any kind,
expressed or implied, with respect to the quality, performance, accuracy, or
fitness of ArtWorx and its accompanying materials for any particular
purpose.  SL assumes no responsibility for any decisions made or actions
taken on the part of the Purchaser because of the use of the Software
Products.  In no event shall SL, or any of its representatives, be held
liable for any loss of profit or any other damages, including but not limited
to special, incidental, consequential, or other damage arising out of the 
use or inability to use this product -- even if SL or an authorized agent of
such has been advised of the possibility of such damages -- or for any 
claim by any other party.

   If you do not understand the terms and conditions of the above license,
please consult your local attorney for a detailed explaination of them
before purchasing an registration key.

GENERAL DESCRIPTION                                                     [1.2]
   
   When ArtWorx began development, it was written with two design parameters:  
Exceed the existing ANSI line limit offered by other drawing programs and 
simplify the interface making it a more intuitive.  When it was in the 
beginning stages, THEDRAW was used as the "standard" by which a comparison 
would be made since it is most likely the widest used and most stable drawing 
program currently out.  However, ArtWorx was NOT intended to be an exact   
duplicate of TheDraw since it, too, lacked some functionality.  While 
ACiDDRAW, GUILEDRAW, and several other editors both exceeded the 100 line 
limit and contained a few nice "gimmics", neither of them were very stable 
and both lacked functionality.  

   Later in the development of ArtWorx, features and options were added from
the suggestions of the beta testers.  After all the new features were sorted
out, it became obvious that beta testers, artists, and programmers wanted
ArtWorx to have some the same features as iCE's privately released "iCE Draw" 
did.  Therefore, ArtWorx has been developed to offer artists and programmers 
with the widest range of capabilities and options.  Here are a list of 
features; options which are planned for version 1.00 are marked with an (*)
while those which have already been implimented (-) are marked with a (-).
 
        - An improved interface, getting away for TheDraw's standard.
        - "Brush" like editing/painting features
        - Full assortment of transformations (ie:  fill/change foreground or
          background color, fill/change characters, etc)
        - Stretchable lines, elipses and boxes as in VGA painting programs
        - Extended background colors (iCE Color)
        * ASCII, ANSI, Binary, C/C++ Header, Pascal, .ADF, and Palette
          file type support (both for load, save, and merge).
        - VGA Font Editor/Generator
        - .ADF - ArtWorx Data Format - holds VGA Font Definitions, the entire
          palette register segment, and binary screen data for programmers
        - BinVU - Unlimited size ANSI's or .ADF's can be saved as a .EXE file
        - Picture length is limited ONLY by XMS memory
        * Sauce and Syrup (extended information) support.
        - Full Mouse Support
        - Fully configurable user interface
        * VGA Mode ANSI Editor/Viewer
        - Tons of options to tailor ArtWorx to your exact liking including
          two ways to scroll pictures (normal and windowed), two file 
          selection menus (normal and with SAUCE info), the cursor 
          appearance, etc.

   System Requirements:
        - 386 SX16 with at least 2Mb RAM configured as XMS
        - Approximately 512kb free memory
        - MS-DOS 5.0, Windows 95, Windows NT, or OS/2 Warp
          (Has been tested on all OS's except Windows NT)
        - 256Kb VGA graphics video card and color monitor
        - MicroSoft Compatible Mouse is recommended

ARTWORX BETA NOTICE                                                     [1.3]
   
   If the version of ArtWorx is labeled as a *PROTOTYPE* or Beta version,
this means that not all of the features have been implimented, and all the 
bugs have not been worked out.  These are uncompleted versions, compiled 
in the interim for authorized Beta testers.  As a result, they could 
seriously "suck" due to the lack of testing, etc.  If you choose to execute
these versions of ArtWorx, you assume all responsibility for any damage or
loss of data that may be incurred.

   Additionally, Sector Logic will *NOT* support beta drivers and operating
systems from third parties.  While version 0.75b was going through initial
testing, a great deal of people complained that ArtWorx would not work with
their QEMM.  After a great deal of headaches due to mixed reports (some 
people said that ArtWorx worked fine with QEMM while other said it did not), 
research, and time infront of my compiler, I found out that some people were
using a BETA version of QEMM!
                                                                        
REGISTRATION                                                            [1.4]

   ArtWorx is *NOT* Shareware, FreeWare, Public Domain, or a free program.  
Users are authorized to use the unregistered version distributed via bulletin 
board systems and the internet for a period of 30 days; after which, the 
copyright laws require the user to register the software by purchasing a 
registration key.

   NORMAL REGISTRATION:  Under normal circumstances, users may purchase a  
registration license for $25.00.  When new versions are released, upgraded
keys can will be created.  Registration costs can be reduced or waived 
subjectively in lieu of "services rendered" by HOOPTiE on a "one by one" 
basis.

   To register ArtWorx a money order or casher's check for $25 must must 
accompany the registration form to the following address:

        Sector Logic                    hooptie@cibola.net (Author's e-mail)
        109 N. Oregon Ste. 404-B        915.534.4449 Sector Logic Orders
        El Paso, TX  79901                           and Tech Support.
   
   To encourage users to register ArtWorx, the "Lamer Lag" has been 
implimented - the program pauses each time you begin the program or a new
picture.  When you register ArtWorx, you gain the following benefits:
         
        - No more annoying delays when you start ArtWorx or a new picture
        - QuickLoad from the command line is enabled
        - Free updates through the internet
        - Full Sauce Support (Title is unchangable in unregistered version)
        - Full BinVU scripting and support
        - Free technical support from the author through the internet or
          voice via the Sector Logic Technical Support Line (915-534-4449).
                        
ARTWORX BASIC PRINCIPLES ---------------------------------------------- [2.0]

   Using ArtWorx is very easy, there are three types of keys:  Editing keys,
Command keys, and Option keys.  The Editing keys are what you use to move 
the cursor and blocks.  All command keys are ALT sequences that do something
or perform some task.  This includes the VGA Editor, Font Editor, Palette
Editor, Transformations Menu, Load/Save/Merge, etc.  The option commands are
all CTRL sequences and alter how ArtWorx behaves--it toggles feature ON or
OFF.  This includes Windowed Scrolling, Under ANSI, Debug Mode, Mini Palette,
etc.

ARTWORX COMMAND-LINE OPTIONS                                            [2.1]

   ArtWorx is fully configurable from within the program itself.  The
following command-line options are provided to address specific circumstances
and speed up some processes.

        /XMS=xxxx      Manually set the amount of XMS memory ArtWorx uses. 
                       This will override the XMS detection, thus solve the 
                       problem that occured with beta versions of QEMM 8.0.  
                       The amount of memory is specified in Kb.  If you want 
                       to use 1Mb of XMS memory, the command line would be 
                       /XMS=1024.

        /L <FILENAME>  Quick Load ArtWorx.  This command bypasses the normal
                       introduction sequence and opens a file during startup.

        /VIEWER        Loads ArtWorx in view-mode.  Editing will NOT be
                       be allowed while in this mode.

        * More commandline options will be available by the release of 
          version 1.00.  None have been implimented to this point because
          they are not as important as some of the other options.

ARTWORX EDITING KEYS                                                    [2.2]
        
        F1 - F10    Function Key Characters 
                    The character set you currently have selected will be
                    displayed when you hit the given key for F1 - F10.

        ARROWS      Cursor Movement 
                    Moves the cursor in various directions.

        Ctrl-C      Block/Highlight Copy 
                    Copies a highlighted block from the screen and
                    places it on the clipboard for later use.

        Shft-ARROW  Block/Highlight Text 
                    Highlights a block for Cutting/Copying, Tranforming,
                    Filling, etc.

        Shft-INS    Paste 
                    Pastes a block from the clipboard onto the working
                    area.

        Shft-DEL    Block/Highlight Cut 
                    Cuts a highlighted block from the screen and places
                    it on the clipboard for later use.

        DEL         Block/Highlight Delete 
                    Deletes a highlighted block from the the picture.

        Ctrl-HOME   Character Set Toggle 
                    Incriment the character set back one set.

        Ctrl-PGUP   Character Set Toggle 
                    Incriment the character set forward one set.

        Ctrl-RIGHT  Foreground Color Select 
                    Incriment the foreground color forward one color.

        Crtl-LEFT   Foreground Color Select 
                    Incriment the foreground color back one color.

        Ctrl-END    Background Color Select 
                    Incriment the background color back one color.

        Ctrl-PGDN   Foreground Color Select 
                    Incriment the background forward one color.

ARTWORX COMMAND KEYS                                                    [2.3]

        Alt-N       New Screen 
                    What this command does is lets you clear your current
                    workspace, and load a new one, or "make" a new one.
                    (Like TheDraw's ALT-C [clear screen]).

        Alt-L       Load File 
                    What this command does is lets you load a current file
                    into memory, and edit it.  It does not have to be an ansi
                    of any type, it can be anything.

        Alt-M       Merge Files 
                    This is an easy way to load to files together.  Unlike
                    TheDraw, AcidDraw, or GuileDraw ... You can't do this.
                    TheDraw you can, but, it is a longer process.  By merging
                    two files, you are loading the two together, onto one
                    workspace.  So, what you are doing is putting the ansi's
                    together basically.

        Alt-S       Save File 
                    This command will let you Save your current workspace or
                    picture, or whatever you are doing, to a file on the Hard
                    Disk.

        Alt-T       Transformations 
                    Fill the foreground or background with a color or
                    character, center a cut block or text within the
                    highlighted area, flip the block on the X or Y axis,
                    transform foreground, background, or characters from
                    value to another.
        
        Alt-A       Attribute 
                    Quick access to the text color palette based on the 
                    normal palette values, not ArtWorx's remapped palette.

        Alt-P       ToolBox Access 
                    The ToolBox lets you choose a variety of 5 options.  Of
                    making a Circle (Filled/Open), Box (Filled/Open), and a
                    Line.  (Will have further explanation later in docs!)

        Alt-Q/X     Quit/eXit 
                    This is pretty much just to "eXit/Quit" Artworx.  The
                    universal exiting key.

        Alt-Z       Undo 
                    Undo lets you change the *LAST* change you have made to
                    your art/workspace.  Very good if you make a mistake, and
                    you notice it before you do ANYTHING else.  It will let
                    you go back to the normal or "right" screen or the flaw-
                    less one to say.  So you do not have to redo the WHOLE
                    thing or something that would take forever.

        Alt-B       Buffer 
                    This command sets the buffer to the current Y position of
                    the cursor and is used in conjunction with highlighted
                    large blocks.

        Alt-E       Palette Editor 
                    This command allows you to change the RGB values of 
                    each ANSI color.  While the changes would not affect
                    normal text-based files (.ANS, .ASC, etc), it WILL be
                    used for the .ADF and BinVU files.

        Alt-F       ArtWorx Font Editor
                    This command allows you to alter the actual VGA fonts
                    for your system.  Keep in mind that changed fonts are
                    not available in .ANS, .ASC, and .BIN formats.

        Alt-U       Function Key Editor
                    There are 20 character sets which can be moved into
                    the function keys.  This editor allows you to configure
                    each of those sets.

        Alt-D       Display Mode        
                    This displays the last object in memory and allows
                    the user to paint with/manipulate the object.  For 
                    more information about Display Mode, see the appropriate
                    header below.

ARTWORX TOGGLES                                                         [2.4]

        ESC         Palette Toggle 
                    This toggles the palette on the bottom of the screen on
                    so that you have easy access to everything.  By hitting
                    it again, it will turn it off or TAKE it off the screen.

        Ctrl-D      Debug Information 
                    This action changes the bottom line of the palette from
                    the normal function key characters to a list of toggles
                    and a compressed version of the function keys.

        Ctrl-B      Block/Highlight Display 
                    This will display your current block hilight from the
                    clipboard.

        Ctrl-W      Windowed Scrolling 
                    This command toggles the WINDOWED_SCROLLING toggle.  When
                    off, the picture only scrolls when the cursor attempts to
                    move outside the limits of the screen.  When on, the
                    picture is scrolled with each movement of the cursor.

        Ctrl-U      Ansi Under Ansi 
                    This command toggles the UNDER_ANSI switch. When this is
                    off, displayed blocks are shown as if they are above the
                    screen; and, when this is on, displayed blocks are shown
                    as if they are behind the screen.  Giving it the effect
                    of having an ansi UNDER another ansi.  Pretty wicked!

        Ctrl-R      Transparency 
                    This command toggles the Transparent switch.  Opaque
                    blocks are displayed EXACTLY as they are cut/copied.
                    Transparent blocks show through blank areas.  Blank areas
                    are defined as black spaces or null characters.

        Ctrl-O      Cursor Toggle 
                    This will toggle your cursor into a "" type cursor
                    (flashing), or into the normal little flashing cursor.

        Ctrl-M      Mini-Palette 
                    This will give you a smaller palette, making it offer
                    MORE lines to use on your screen, OTHER than the huge
                    block palette toggled on by hitting the ESC key.

VGA MODE EDITOR ------------------------------------------------------- [5.0]

The VGA EDITOR is not an original concept of ArtWorx.  Two poor attempts
were made previously by a program called "RAGE" (Rapid ANSI Graphics Engine)
and DarkDraw.  Unfortunately, neither program offered much functionality.
The ArtWorx VGA editor was designed to be fast, simple, and functional.  The
basic concept of the editor allows the artist to edit 100 screen lines
without suffering from the proportion problems of the 80x50 textmode.

Since ACiDDraw is the standard by which VGA ANSI viewing is measured,
ArtWorx was pitted against ACiDDraw on a 486-DX2/80 with 64Mb RAM under
DOS 6.22.  A merged collage of ANSI reaching exactly 1200 lines was used to
test the two programs.  While using the PGDN key in ACiDDraw, it took 7.8
seconds to scroll 1000 lines (ACiDDraw does not support ANSI's over 1000
lines).  ArtWorx was tested both by using the mouse scroll bar and the PGDN
key.  With the mouse, it took ArtWorx 5.4 seconds to scroll through the
entire 1200 line ANSI; and, with the PGDN key, it was approximately 2.1
seconds or less (it was difficult to measure exactly).

HOW THE VGA EDITOR WORKS                                                [5.1]

A mouse is required to edit ANSI's in VGA mode; the keypad only scrolls the 
ANSI.  At the bottom of the screen, there are three color bars.  The two 
small ones (labeled Button 1 and Button 2) correspond to the buttons on the
mouse.  In VGA mode, colors are used to represent different characters.  
ArtWorx calculates the color by considering the foreground, background, 
and shading character.  

  F1   F2   F3   F4     F1   F2   F3   F4
Ŀ Ŀ
                 
 
  Button 1              Button 2

If you are drawing with the F4 selection with either mouse button, ArtWorx
will use the F5/F6 half-blocks.  If you are using the F1-F3 keys, half-blocks
are not available.

To the left of the mouse button indicator is the master color bar with all
16 available colors.  On the top and bottom are four different indicators
or pointers.  Pointers that "face" to the left are for the left mouse button
while pointers that "face" to the right are for the right mouse button.
The top row of pointers indicate the foreground color; and, the bottom row
of colors indicate the background color.

USING THE MOUSE                                                         [5.2]

EDITING:  To draw/edit the ANSI in VGA mode, simply press and hold either 
mouse button and sketch until your heart is content.

SCROLLING:  You may either use the UP/DN to scroll one line, PGUP/PGDN to
scroll a whole page, the mouse on the single up or down arrow to scroll one
line at a time, or the double arrows to scroll a page at a time.  Be careful
though - when you use the mouse to scroll the ANSI, it can go rather fast.

CHANGING COLORS:  On the master color bar, press and hold the mouse button
that you wish to change over the indicator and drag it to the desired color.
The top row of indicators are for the foreground and the bottom row is for
the background.  As you change the foreground/background colors, the button
indicator will change as well.

CHANGING SHADES:  Simply click on the shade you wish to use with either mouse
button.

ARTWORX DATA STRUCTURES AND CODE EXAMPLES ----------------------------- [7.0]

The following is a collection of tables, pseudo-code algorythms, and specific
ASM/C++ source code provided as information for programmers.  The code
was originally compiled with Borland Turbo C++ version 3.00.  If you are
using a compiler other than TC 3.0, some modification may be necessary.
For example, in MicroSoft C++, the INP command should read _INP.

ANSI/2 (.AN2) - EXTENDED ANSI CODES                                     [7.1]

NOTE:  This specification is under beta development and is subject to
       change.  This document is merely for informational purposes only
       at this point until the specification is more clearly defined 
       and implimented.

The ANSI/2 system has been created out of a need for a better graphics
standard which does not suffer from the slow display rates of RIP and 
VGA bitmapped graphics.  ANSI/2 is a happy medium that offers artists
the ability to control the VGA font and palette to create more versatile
graphics while maintaining the low overhead and high speed of ANSI.
The following is an outline of the ANSI extensions and what their 
purposes are:

ESC[V           = ANSI/2 Version Request.  The terminal should respond with
                  the string, "ANSI/2x"; X is a one-byte character
                  representing a revision number.  Version 1 would return
                  an open smiley face after the "ANSI/2".

ESC[x;rgbP      = The 'P' command indicates a single palette register change
                  using the following information:
                     x - BYTE; palette register ranging from 0 (black) to 63 
                         (bright white). Keep in mind that you are altering
                         the registers and not the colors  For example, the
                         bright white (textcolor 15) register is 63, bright
                         yellow (textcolor 14) is register 62.  See the end
                         of this document for a complete list of textcolor
                         and register equivolents.
                     r - BYTE; red value ranging from 0 to 63.
                     g - BYTE; green value ranging from 0 to 63.
                     b - BYTE; blue value ranging from 0 to 63.
                     P - Palette Command; must follow the rgb data to be 
                         recognized as the extension to change the palette 
                         register.

ESC[Q;rgb...    = Mass Palette Change.  'Q' Preceeds a 192 byte record
                  which indicates to the terminal to change the ENTIRE
                  palette at once.  There are no seperators between the
                  rgb pairs, and just like above, the rgb data is BYTE 
                  information.  The terminal should expect EXACTLY 192
                  bytes after the ESC[Q sequence.  Finally, no palette
                  registers should be changed until after the entire
                  192 byte record is received.

ESC[T;...       = Font Change.  'T' preceeds a 4096 byte record which
                  corresponds to standard VGA font data.  ANSI/2 is assuming
                  normal VGA mode (80x25) with each character being made up
                  of 16 scanlines.  4096 bytes comes from 256 characters x
                  16 scanlines per character = 4096 bytes.  There is
                  terminating character for this sequence; and, exactly 
                  4096 bytes should be sent with this command.

ESC[t;ch;ln;... = Limited Font Change.  The command character is 't' (case
                  sensitive) which indicates that part of a font record will
                  follow.  Once again, ANSI/2 is assuming normal VGA text
                  text mode (80x25) with each character being 16 bytes long.
                  There is no terminating character for this sequence.
                     ch - BYTE (0-255); This is the character to begin with.
                     ln - BYTE (0-255); This is the length or number of 
                          characters to modify.  The terminal should expect
                          16 (bytes per character) * LN (# of characters).
                     
                     * For instance, if you wanted to modify JUST the capital
                       letters ("A" thru "Z"), the ANSI/2 code would look
                       like this:  ESC[t;A;(^Z);...
                         (A)  is the byte representation of character 65
                         (^Z) which is a non-printable character, is the 
                              byte representation for character 26.

                     ** Additional Note:  Char(26) represents the end of a
                        file; and, if a the BBS reads to EOF and not to
                        the file length, it could cause problems.  This will
                        be rectified in ArtWorx by NOT writing ^Z (chr 26) or 
                        ESC (chr 27) in any of these sequences.  Users will 
                        be able to modify less than 26 and more than 27 
                        characters with the 't' sequence.  Furthermore, any 
                        future editor of ANSI/2 should realize the problems 
                        with writing these codes to a normal text file and 
                        avoid them.

ESC[Z           = Full Reset Command.  This sequence restores the default 
                  palette and VGA font.  The easiest and fastest way to 
                  accomplish this is to switch the screen mode to 40 column 
                  mode and then back to 80 column mode.  All video card 
                  (even TTL) supports this call; and, there shouldn't be any 
                  flicker on the screen since it is only changing between two 
                  text modes.

                  In C++, the RESET source code would look like this:
                     void reset_textscreen(void) {
                        textmode(C40);
                        textmode(C80);
                     }

ESC[z;fpi       = Selective Reset Command.  This sequence resets or toggles
                  three settings selectively.  F, P, and I are all BYTES
                  ranging from 0 (off) to 1 (on).
                     f - FONT      (0) = Do not reset the font
                                   (1) = Reset/Load the default font
                     p - PALETTE   (0) = Do not reset the palette
                                   (1) = Reset/Load the default palette
                     i - iCEColor  (0) = Turn iCEColor OFF
                                   (1) = Turn iCEColor ON

When a terminal and/or BBS detects the ANSI/2 emulation, there are a few 
defaults which need to be setup.

  (a) iCEColor = ON.  This eliminates blinking and allows bright background
                      colors.  This seems *SO* much more useful than
                      blinking characters that it simply makes sense to have
                      it turned on.
  
  (b) Chr_Width()     This ASM routine modifies the width of the VGA
                      VGA character set so that only 8 bits are used instead
                      of the standard 9.  This SHOULD BE (but does not have
                      to be) togglable from the terminal and/or BBS because
                      on SOME VGA card, it messes up.  If this is NOT
                      setup, blank lines will appear on the right side of
                      characters that are supposed to match up.  It's not
                      a major problem and this routine is NOT vital to the
                      operation of ANSI/2; however, when it's not on, the
                      display looks rather goofey.

Definition of BYTE Data for ANSI/2

   Since ANSI is intended to be a purely text format, binary data cannot be 
included because ^Z (char #26) marks the end of file (EOF).  In a binary
file, this does not matter; however, in a text file (which is what all BBS
software treat user-configurable screen), this is a very big deal.  As such,
BYTE data must be represented in a text-readable format and not include any
control characters such as ^Z.  For this reason, the following BYTE data
specification has been implimented to remove any problems with the mixing 
of binary data and text data.

   For binary data, the assumption is made that the data sent will be between
character #128 and #255.  Unfortunately, this only covers half of the
possible range; therefore, any character preceeded by character #1 should
have 128 subtracted from it's ASCII value.  For instance, if a string like
the following was sent in ANSI/2 emulation for binary data:

   

It would be translated into the following values:

    = 65     = 32     = 200     = 0    = 1     = 254

In other words, 

    = 65, 32, 200, 0, 1, 254

in binary ANSI/2 data.

While this is certainly not readable by humanly standards, it is the most
compact means of sending binary data through a text-only file.  This should NOT
pose any major coding problems and it will definitely solve the problems that
binary data causes in text files.  This convention applies to all ANSI/2
requirements for binary data.


.ADF - ARTWORX DATA FORMAT                                              [7.2]

The .ADF specification is a essentially a single file which contains VGA font
data, the RGB registers for the text palette (registers 0-63), and an
unlimited amount of binary screen data.  It is intended primarily for
programmers who would like to add a unique look to any textmode program.

The control structure for the .ADF file is simple:

    BYTE                  : Version #
    Array of BYTES [192]  : Binary Palette Data in 3-byte triplets.  These
                            values correspond to the RGB data passed to
                            the VGA card.
    Array of BYTES [4096] : VGA Font Data.  Regardless of the screen mode, 
                            4096 bytes is written to the file.  This is the
                            binary data passed to the VGA card to generate
                            fonts.
    Array of BYTES [....] : (Unknown/Undefined Size) Screen Data.  This is
                            the actual screen data in the binary, two-byte
                            (character/attribute) format.  This data can
                            be directly copied to the screen and should not
                            go through the bios or console.

HOW TO CREATE AN .ADF VIEWER                                            [7.4]

The following is an pseudo-code algorythm to read, display, and scroll
through an .ADF file.  For specific programming examples of C++ code to 
accomplish specific tasks, please see the Figures at the end of this 
document.

   CHAR version         // Version of .ADF specification
   CHAR palette[192]    // VGA palette information
   CHAR old_pal[192]    // OLD VGA palette information
   CHAR vga_font[4096]  // VGA font information
   CHAR vbuffer[4000]   // VGA text screen buffer

   main :
      CHAR key=0        // Key pressed
      CHAR ext=0        // Extended key code
      INT  exit_stat=0  // When to exit the program
      INT  pointer=0    // Top line of ANSI being displayed
      INT  max_lines=0  // Maximum number of ANSI lines
      
      fopen <filename> as binary
      max_lines=(filesize(filename)-4298)/160   // Figure out exactly how
                                                // many lines of screen
                                                // data are in the file

      read version (1 byte)
      read palette (192 bytes)
      read vga_font (4096 bytes)

      for x=0 to 63                             // Capture the existing
        get_vga_palette (x, old_pal[x])         // palette so it can be
      next x                                    // restored on exiting

      call set_ice_color ()
      call set_character_width ()
      call set_palette_registers (palette)
      call set_vga_font (vga_font)

      do while (exit_stat=0)
        seek (pointer*160+4289)         // Goto the right place in the file
                                        // and not read the header.  Since 
                                        // pointer is a line, pointer * 160
                                        // is the byte position for that
                                        // line.
        
        read vbuffer (4000 bytes)       // Read the screen data
        
        memory_copy vbuffer 
          to screen (4000 bytes)        // Copy the data read to the actual
                                        // screen to be displayed

        key=get_key()                   // reads the keystroke
        if (key=0) then ext=get_key()   // reads the extended key stroke
        
        if (ext="H") pointer=pointer-1  // Up
        if (ext="P") pointer=pointer+1  // Down
        if (key=27) exit_stat=1         // Escape exits/quits

        if (pointer > 
           max_lines-25 ) then 
           pointer=max_lines-25         // Make sure you are not trying to 
                                        // read past the end of the file

        if (pointer < 0) then
           pointer=0                    // Make sure that you don't try to
                                        // display the header as part of the
                                        // picture

      end while

      set_vga_palette (old_palette)
      set_normal_color ()
      screenmode (80x50)                // This will reset the default font
      screenmode (80x25)                // Returns to the normal screen mode

   end of program

ANSI COLOR TO REGISTER CONVERSION CHART                                 [7.5]

The following chart explains the relationship between the textcolors which
are normally accessed from programming languages, the VGA Palette register,
and the ANSI color identification.

                  Description    Color    Register     ANSI Color
                  ------------   -----    --------     ----------
                  Black            0         0         ESC[0;30m
                  Blue             1         1         ESC[0;34m
                  Green            2         2         ESC[0;32m
                  Cyan             3         3         ESC[0;36m
                  Red              4         4         ESC[0;31m
                  Purple           5         5         ESC[0;35m
                  Brown            6        20         ESC[0;33m
                  White            7         7         ESC[0;37m
                  Dk. Grey         8        56         ESC[1;30m
                  Br. Blue         9        57         ESC[1;34m
                  Br. Green       10        58         ESC[1;32m
                  Br. Cyan        11        59         ESC[1;36m
                  Br. Red         12        60         ESC[1;31m
                  Br. Purple      13        61         ESC[1;35m
                  Yellow          14        62         ESC[1;33m
                  Br. White       15        63         ESC[1;37m

C++ EXAMPLE OF CHANGING A VGA SINGLE VGA PALETTE REGISTER               [7.6]

  #define PALETTE_MASK         0x3c6
  #define PALETTE_REGISTER_RD  0x3c7
  #define PALETTE_REGISTER_WR  0x3c8
  #define PALETTE_DATA         0x3c9

  typedef struct rgb_color_typ {  // This structure holds a RGB triples
         unsigned char red;       // red   component of color 0-63
         unsigned char green;     // green component of color 0-63
    unsigned char blue;      // blue  component of color 0-63
  } rgb_color, *rgb_color_ptr;

  // Set a palette register
          void set_palette(int index, rgb_color color) {
                 outp(PALETTE_MASK,0xff);
                 outp(PALETTE_REGISTER_WR, index);
                 outp(PALETTE_DATA,color.red);
                 outp(PALETTE_DATA,color.green);
                 outp(PALETTE_DATA,color.blue);
          }

C++ EXAMPLE OF MODIFYING THE VGA FONT                                   [7.7]

  // SET THE VGA FONT

  // font_data[] is a 4096 byte array that contains the entire font data to
  // be passed to the interrupt

          void set_font(void) {
                 struct REGPACK r;
                 r.r_bx=0x1000;                  // 16 scanline font
                 r.r_es = FP_SEG(font_data);     // Segment of the font data
                 r.r_bp = FP_OFF(font_data);     // Offset of the font data
                 r.r_ax = 0x1110;                // Int 10h SubFunction
                 r.r_cx = 256;                   // 256 characters
                 r.r_dx = 0;                     // Starting with character  
                                                 // #0 (the NULL)
                 intr(0x10, &r);                 // Load the actual data
          }

ASM EXAMPLE OF SWITCHING ICE COLOR                                      [7.8]

iCE Color is a means of disabling the BLINK attribute and using the upper
8 colors (#8/Dark Grey to #15/Bright White) as background colors.  This is 
the default setup for all .ADF and ANSI/2 files.

  // Turn on iCE Color
          asm {
                 mov bl,0000h       // 0001h turns iCE Color Off
                 mov ax,1003h
                 int 10h
          }

ASM EXAMPLE OF SETTING THE CHARACTER WIDTH                              [7.9]

Under normal circumstances, the VGA font size is 9x16 or 9x14, and not the
perfect 8x16 as the font editor is in ArtWorx.  As a result, if two
characters are drawn to match up on, there will almost always be a line
between the two characters if they are placed next to each other on the
same line.

This routine changes that definition so that EXACTLY 8x16 characters are
displayed on the screen.  Keep in mind that this is not exactly a 
"conventional" programming practice, even though it does work.  As a result,
it can pose some problems.  For instance, almost all video cards create a
"shadow line" when the cursor is in the first column.  Some older video cards
like those in the Packard Bell Legend Series, will display the entire first
row on the right hand side of the screen.

Therefore, the BBS and/or terminal program that supports this should make
this an togglable option.

  void chr_width(void) {
  asm {
          mov     dx,03c4h
          mov     ax,0100h
          out     dx,ax

          mov     dx,03c4h
          mov     ax,0301h
          out     dx,ax

          mov     dx,03c2h
          mov     al,063h
          out     dx,al

          mov     dx,03c4h
          mov     ax,0300h
          out     dx,ax

          mov     dx,03d4h
          mov     ax,4f09h
          out     dx,ax
      }
  }
