     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     ~ PARADIZE Rasterbar Generator ~
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 (c) 2007/2008/2009 by Simon Sunnyboy / Paradize
 http://paradize.atari.org/

0. Introduction

     The Paradize Rasterbar Generator is an utility for game and 
     demo developers on the Atari ST/STE/TT and Falcon range of 
     computers.

     It allows to prepare tables with color data. It helps with
     calculating smooth color gradients for the STE palette.

     All data can be saved into various data formats for use in 
     your own programs.

1. System requirements

     Atari ST/STE/TT or Falcon Computer running TOS
     color display (for ST-LOW)
     STE palette optional (for way smoother rasters)

     The program will run on STF class machines. However it
     will tell you that you loose color information.
     Recommended is to use an Atari STE. 

     This utility is meant to be run under singletasking TOS.
     If it works for you with MagiC or MinT, great, if not
     do not report this as a bug. This program is for TOS!

     If your CT60 or other CPU booster creates troubles
     disable it and run the program from a genuine Atari Corp.
     configuration.

     Hades, Milan and other "GEM compatibles" are officially
     not supported and never will be.

2. Installation

     To install the program just place the program folder
     anywhere on your harddrive or a floppy disk.

     To start the program, simply doubleclick RASTGEN.PRG on
     the desktop. A title screen with an example raster effect
     should appear. Press SPACE to go into the main screen.

3. The main screen

     The main screen is divided into 3 parts. The large help
     screen on the left which tells you the actions you can
     use.

     The work panel follows which tells you the current curor
     position, the color at the current cursor position and
     block marks (if you have marked a block).

     Finally on the right edge of the screen you have the
     cursor for data entry and the current rasters in memory.

     The whole program is keyboard operated, except for
     selecting files for loading and saving.

4. A word about colors

     The Paradize Rasterbar Generator works in STE color space
     with 16 possible settings for R, G and B components.
     Color values are displayed in a linear fashion, not in
     the STE coding. The program will convert from linear to
     STE and back on the fly.

     Your main color is the socalled working color. This is
     manipulated through the RGB settings and used to define
     raster table entries.

     Even on an STF you will be allowed to manipulate the
     STE color space, even you will not be able to see the
     finer color separations possible on the STE.

5. Keyboard commands

     Various keys are at your disposal.

     Cursor Up           moves the cursor up (it will wrap if
                         you go beyond the top of the screen)

     Cursor Down         moves the cursor down

     R,G,B               increase color components (they will
                         wrap around if you exceed 15)

     Number block        Those keys will increase or decrease
     4,5,6,7,8,9         R,G or B components of the working
                         color.

     SPACE               This deposits the current color at the
                         cursor position and moves the cursor
                         one step down.

     RETURN              This calculates an automated color
                         gradient. It starts from the current
                         color at the cursor position and
                         fades the color step by step until it
                         reaches your selected working color.
                         The cursor moves down for each step.

     CLR/HOME            Clears all rasters.

     UNDO                Undoes the last data entry or action.

     C                   Copies the color from the cursor
                         position to your working color.

     F1                  Allows you to load a set of rasters
                         saved in the RST format.

     F2                  Allows you to save rasters in various
                         formats. Only RST can be loaded back
                         into the Rasterbar Generator.

     F3                  Fills all possible raster positions
                         with the current working color.

     F4                  Sets the upper mark for the copy buffer.

     F5                  Sets the lower mark for the copy buffer.

     F6                  Copies all entries in the marked range
                         into the copy buffer.

     F7                  Inserts the contents of the copy buffer
                         at the current cursor position.

     F8                  Empties the copy buffer.

     F10                 Enters the test screen.

     ESC                 Exits the program to the desktop. It
                         allows you to save your changes if
                         desired.

6. The test screen

     The test screen allows you to try out the current rasters.
     It rasters a few logos with your colors.

     You can tweak the number of scanlines to be colored with
     the current entry. Press 1 to 0 to select between
     1 to 10 scanlines per entry.

     If you set it to 2 lines, only the first 100 entries of
     your table will be shown to raster 200 scanlines.

     Press SPACE to go back to the main screen.

7. File formats

     The Paradize Rasterbar Generator allows you to save your
     raster colors in various file formats. Only the binary
     RST format can be loaded back into the program.

     You can always save the current selection between block
     marks. You do not need to have the selection copied into
     the copy buffer first. 

     RST format (binary)
     -------------------

     This is the native and binary fileformat.

     Offset      Content
     --------------------------------------------------------
         +0      LONG 'pRTG'      File type identifier
         +4      WORD count       Number of rasters colors
         +6      WORD ....        `count` 16bit WORDS with
                                  STE palette entries of your
                                  colors.

     A file with a full set of 200 raster colors is 406 bytes
     long.

     LST format (GFABASIC)
     ---------------------

     Saves your colors as DATA statements or a prepared
     array of WORD values with your rasters.

     You cannot load this data back into the Rasterbar
     Generator.

     S format  (Motorola Assembler format)
     -------------------------------------

     Saves a .S file with dc.w statements for use with your
     favourite assembler.

     This also cannot be loaded back into the Rasterbar
     Generator.

     All color values are saved as STE palette entries.
     They can be directly written into the ST color registers.
     Also all raster table information is fully compatible
     with STF although it will loose colro information.

8. Final words

     This utility has been in the works for quite some time.
     It mainly is a test case for my own raster routines
     so I took the opportunity to both make the routine
     stable and usable and create a useful utility for further
     use of this routine.

     It was bugfixed quite a few times and was forgotten on my 
     harddisk for almost a year. After reviewing the code I 
     thought it was ready so here you go :)

9. Contact information

     Contact us for any questions or comments.

     Email               Simon Sunnyboy <marndt@asmsoftware.de>
     WWW                 http://paradize.atari.org/
     IRC                 #paradize on IRCNet

     Feel free to use and copy this program. Leave all files
     intact, including this documentation.
     The motto is: "Copy me, I wanna travel!"

10. Final words

     STay cool, STay Atari /|\
     Simon Sunnyboy signing off on April 4th 2009

-eof-

