EnvisionPC: Release 0.5

by Mark Schmelzenbach 
Copyright (c)1997-98


Introduction

Many years ago, APX released a program called Envision.  It was THE game
design tool.  It had an integrated character editor, map maker and many
other useful utilities.  Having recently returned to the Atari 8-bit scene, 
due mostly to the high quality emulators now available, I felt like 
pounding out a quick game.  I scrounged around for a copy of Envision--
and was rather surprised to be unable to find one.

As such, I set out to write my own version.  However, this time it runs on
the PC (either Linux or DOS/W95).  I can already hear the gasps of horror
rippling through the crowd.  Why write a design tool for the 8-bit that 
runs on a different platform?  The answer is twofold: first, it is useful to
switch between applications (i.e. the Atari Emulator, and EnvisionPC). 
Second, this type of editor begs to use the mouse.  Since I haven't seen an
emulator that uses the mouse--and since my Atari ST mice are all dead, I
decided to write this a cross-platform tool.



Installation

The zip file includes the following files:

envision.txt: this file

cwsdpmi.exe: a DPMI server needed by DJGPP programs.  If you are running
             Windows or Windows 95, you don't need this program.
cwsdpmi.doc: docs for the DPMI server.
 emu386.dxe: floating-point emulation for those who don't have an on-board
             FP processor.  If you have a 486DX or better, you can erase
             this file.

envision.exe: the DOS executable.  This program was compiled with DJGPP, an
              excellent FREE 32-bit C compiler.
envision.elf: the statically linked Linux executable.  This is in ELF
              format, so if you haven't upgraded yet, now would be a good
              time.

src/*.*:  The source code for Envision, including Makefiles.  Notice that
          compiling this program requires the GRX20 package.  This is
          available at the same sites as DJGPP.

Note for Linux uses:
If you are running the Linux version, you will need to either run the
program as root (not recommended) or change the file permissions to allow
the program access to the VGA registers.  To do this you will need to
set-uid root.  As root, execute the following commands:
  chown root envision.elf
  chmod a+rs,go-w envision.elf
This should do the trick...

    

Usage

This editor is based loosely around memories of the original Envision
program.  However, since I haven't actually used the program in over 8
years, don't expect it to be the same.

The character editor screen is divided into four main sections:
  Along the bottom of the screen is the font currently being edited.  The
current 'cell' actually being changed is highlighted by a blue square. 
Clicking on any letter in this section will select that letter for editing.
  The right hand side of the screen is a gird...this is an enlarged
version of the selected cell. Left clicking on the grid will fill in a
pixel, while right clicking will erase the pixel.  The mouse button can be
held down for continuous drawing.  Along side the grid is an example of what
the character will look like in Antic mode 6 (Graphics 1), 7 (Graphics 2)
and 4.
  The left hand side of the screen contains the command menu.  All commands 
are accessible through either the keyboard or the command menu.  To activate 
a command, click on the command button with the mouse or press the letter 
that is highlighted.  There are multiple command menus, accessible by clicking
on the tabs along the top.  Notice that the keyboard commands are always 
active, even if the equivalent button is not displayed.
  The center of the screen is a copy of the upper left-hand corner of the
map.  You can edit this box (and change the graphics mode) from the map
editor.
The font editor can hold up to 10 font 'banks' in memory at a time.  To change
between banks, press the numbers 0-9 to select the appropriate font.  Also,
the arrows next to the bank indicator can similarly be used.

Currently the commands available in the character editor are:

'b': blank
  clears the currently selected character

'i': inverse
  inverts the currently selected character...this toggles the status of 
  all pixels

'u': undo
   restores the character to the state it was in before the character was
   selected.  This command is a little twitchy, so you can undo the undo...

'a': Atari 
   restores the character to the original Atari character.

'A': All Atari (shift-a)
   This restores the entire bank of characters to the default Atari
   character set.

'h': horizontal flip
   flips the character horizontally

'v': vertical flip
   flips the character vertically

'r': rotate
   rotates the charater 90 degrees counter-clock wise

'c': copy
   This copies the character to another cell.  Select the destination cell 
   by clicking on it along the bottom.  Notice that copying between font 
   banks is allowed--encouraged even.

'x': extended copy
   This command copies a range of characters.  The source beginning cell
   is the current editing cell, select the ending cells, then the select
   the begining destination cell.  Again, copying between banks is allowed,
   as well as overlapping source/destinations.

't': transparent copy
   This command overlays the current character onto another cell.  Select the
   destination cell by clicking on it along the bottom.  This mode is useful
   mainly for designing ANTIC 4 and 5 characters
   
'g': toggles the GTIA register.  <currently not implemented>

'p': poke
   This command allows you to set the color registers to desired values. 
   The colors are taken from a header file from David Firth's Atari 800
   emulator.  He includes a note that these colors were provided by Chris
   Lam.  I think that they ar fairly accurate, although I could have sworn
   that the color 70 was red.  Here is seems to be a lavander.  Can anyone
   confirm and/or deny this?

'n': numbers
   This displays the values that make up the currently defined charater. 
   Pressing it one shows decimal values, pressing again shows hex values and
   again turns off the number display.

arrow keys: slide
   The arrow keys (left/right/up/down) slide the character the corresponding
   direction

0-9: select font bank
   The number keys select the appropriate font bank

'o': options
   This is where the basic options for file input/output are set.  You will
   be prompted for a disk image file name (or none, if you wish to use the
   harddrive instead), the export format, and line numbering parameters, if
   appropriate.

'l': load a font
   Loads a font, either from the harddrive or from an .XFD disk-image

's': save a font
   Saves a font, either to the harddrive or to an .XFD disk-image

'e': export a font
   This command allows the font to be written to disk in a form useful for
   programming.  You can select a range of characters to export, or the entire
   font.  If you are writing to the harddrive, the format will be ASCII,
   if you are writing to an .XFD disk-image, it will be written in ATASCII

   Currently available formats are:

     BASIC -- written out as DATA statements, seperated by commas from a
              given linenumber, incrementing by a given step.
     MAE -- written out as .BY statements, seperated by commas, no line
            numbers
     MAC/65 -- written out as .BYTE statements, seperated by commas from a      
               given linenumber, incrementing by a given step.
     Action! -- written as a byte array.

     The format is set in the default options menu, accessed by the 'o'
     command described above.  Let me know if you think there are other 
     formats that would be useful.

'm': enters map mode

Pressing Escape or control-q will exit the program.  (Linux users may need to
press Escape twice).


The Map maker

The map screen is divided into three sections:  the character palette, the
command menu and the map itself.  Clicking on a character will select that
as the current drawing character.  Left clicking on the map display will
place the character at the current cursor position.  

Available commands in the map editor:
'f': find
   This performs a search/replace on the current map.  You will be prompted
   for the character to search for, and it will be replaced by the current
   draw character.  This command is effected by the current Ratio (see
   below).  So, to replace 10% of all 'A's with 'B's, set the Ratio to 10,
   set the draw character to 'B', then execute this command and select 'A'.

'c': clear
   This fills the entire map with the current draw character.  This command
   is effected by the current ratio (below).  A ratio of 100 will fill the
   entire map with the draw character.  Smaller ratios will result is
   characters 'spotting' the map.

'r': ratio
   This commands sets the ratio value for the find and clear commands.  A
   ratio of 100 means that the character will always be replaced/set.  A
   ratio of 10 means that it will be replaced/set 10% of the time.

'u': upper/under
   In ANTIC modes 6 and 7 (graphic modes 1 and 2), there are only 64
   characters available.  Normally, the upper 64 are visible.  This command
   toggles between the upper 64 and lower 64 possible characters.

't': type mode
   Entering this mode allows you to move the cursor with the cursor keys. 
   Pressing any other keuy will result in typing that character at the
   current position on the map.  To exit this mode, press escape.  (Use
   the draw character to place an esc symbol or arrow symbols into the map)

'l': load a map
   This loads a map from the harddrive/.XFD image (depending on the options
   set in the editor).  The map file format is as follows:

      ANTIC mode:  1 byte
      map width: 2 bytes (low byte, then high byte)
      map height: 2 bytes (low byte, then high byte)
      color map: 5 bytes (PF0, PF1, PF2, PF3, PF4)
      ...
      map data: (map width*map height) bytes
      ...
      font data: 1024 bytes

   Does anyone know the fileformat for Envision .map files?  I would like to
   make this compatible.

's': save a map
   Saves a .map file

'w': write a RAW map
   This saves only the raw data of the map.  No mode/size/font info is
   included.

'm': select Antic mode
   Enter the desired graphics mode.  Valid modes are ANTIC modes (2-7)
   See the chart below for details.

'z': resize a map
   The resizes the map.  If you are making the map smaller, map data
   outside the new boundries will be lost.  The map dimensions can range
   up to 512x512.  The smallest size depends on the ANTIC display mode,
   as detailed in the following chart:
                +-------+-------+-------+-------+  
                | ANTIC | BASIC | min x | min y |
                +-------+-------+-------+-------+
                |  2    | GR.0  |  40   | 24    |
                +-------+-------+-------+-------+
                |  3    | N/A   |  40   | 24    |
                +-------+-------+-------+-------+
                |  4    | N/A   |  40   | 24    |
                +-------+-------+-------+-------+
                |  5    | N/A   |  40   | 12    |
                +-------+-------+-------+-------+
                |  6    | GR.1  |  20   | 24    |
                +-------+-------+-------+-------+
                |  7    | GR.2  |  20   | 12    |
                +-------+-------+-------+-------+

'e': returns to the editor

arrow keys move the cursor/scroll the display

Again, escape will exit the program.


Disclaimer:

I provide no guarentees what-so-ever with this program.  I have had some
problems with the .XFD writing/reading routines--so be sure to back up your
.XFD images before trying to read and write to them.  You have been warned.
If you find problems, or would like to see enhancements/fixes to the program
contact me via the e-mail address below.



To do:

o Add import utilities to change bitmaps into character banks.
o Add better ANTIC 4 and ANTIC 5 editing
o Improve the .XFD save routine to allow overwrite.
o Add GTIA emulation(?)
o Add DLI support(?)



Credits:

 * The .XFD disk routines are based on the xfd_tools package written by
   Ivo van Poorten <ipoorten@cs.vu.nl>

 * The bitmap rotation routine is taken from a Graphics Gems II article by
   Ken Yap entitled "A Fast 90-Degree Bitmap Rotator" (pp. 84-85)

 * The color header file containing RGB values for each Atari color was
   written by Chris Lam <lamcw@sun.aston.ac.uk>

 * DJ Delorie for the excellent DJGPP compiler--available on all SUNSITE 
   mirrors.

 * for the GRX graphics package

 * Charles Sandman for the DPMI server

--Mark Schmelzenbach
  e-mail: schmelze@cs.utah.edu or schmelzenbach@sisna.com
  08/04/97
