
                        Degas-to-chunky Converter
                    --------------------------------
                    by The Paranoid of Paranoia 2002
                    
                    
                    

Requires an Atari ST with 100 KBytes of RAM, any resolution, any 680x0 


This little program converts the top left block of pixels of a 
DEGAS-PI1-picture file to chunky format with either 1-byte-per-pixel
of which only the 4-bit are being used or 4-bits-per-pixel,
meaning 2-pixels-per-byte, called ".16".
No restrictions apply to the DEGAS file.

Required are the filenames of both input DEGAS-file and output 
.16-file. If a file with the output-filename is already existing,
it will be overwritten.

The program accepts several kinds of flags, of which some require an
additional parameter (d stands for default):
  -8     = 8-bits per pixel, meaning 1 pixel per byte  (byte-mode)  (d)
  -4     = 4-bits per pixel, meaning 2 pixels per pyte (nibble-mode)
  -p     = Include Palette (additional 32-bytes per file)           (d)
  -n     = Surpass Palette generation
  -x     = followed by up to 3 digits for picture size on x-axis
           (May be any multiple of 16 between 16 and 320)
  -y     = followed by up to 3 digits for picture size on y-axis
           (May be any integer value between 1 and 200)
  -z     = RenormaliZation of each pixel-value by a factor of 4
           (only usable on 1-pixel-per-byte chunky modes)
  
Please note that there is - in contrast to most Unix- or CP/M-programs
no space permitted between the -x/-y flag and the digits.
In general, a space terminates the flag or parameter, meaning that 
there must be a space between each of the flags, the flags and the 
filenames and between the filenames for correct detection.
Also, it is not necessary to give all the flags. Defaults are being
used for missing flags. The Defaults are 160 pixels a line, 100 lines
in total, palette is included, 1 byte per pixel is used and no
renormalizing is being done.
Unrecognized flags or insane values will return an error message.
Double or directly contradicting flags, like using both -4 and -8
will not generate errors. In that case, the flag given last will be
applied. Otherwise, the order of the flags is free.

Example for usage of the flags:

  -4 -p -x320 -y200 IN.PI1 OUT.16
  will create a chunky-file using 4 bits per pixel, packing 2 pixels 
  in 1 byte, of the size 320x200 pixels with palette included.

  -x64 -y64 -8 -n -z IN.PI1 OUT.16
  will create a chunky-file using 1 byte per pixel, has no palette
  information and is 64x64 pixels in size. Each byte-value of the
  pixel data will be multiplied by a factor of 4.

  -z -p IN.PI1 OUT.16
  will create a chunky-file using 1 byte per pixel, each multiplied
  by 4 with palette included of the size 160x100 pixels.

The output-file features the following format for include in your
programs:
  - 1 byte header, containing the magic number "16" ($10)
  - 1 byte with the status flag. Each bit resembles the flags
      given in the commandline with the following structure:
      00000XXX       Interpretation
           ||+------ 4-bits per pixel, 2 pixels per byte if 1
           ||        8-bits per pixel, 1 pixel per byte  if 0
           |+------- Renormalized by a factor of 4       if 1
           |         Unmodified pixel data               if 0
           +-------- Palette included                    if 1
                     No Palette included                 if 0
  - 1 byte, containing the number of pixels per line
  - 1 byte, containing the number of lines
  - if palette generation was enabled, the next 32-bytes contain
    the palette as being used in the DEGAS-file.
    If palette generation was disabled, data starts right after
    the header.
  - Chunky data
    Depending on the -4 or -8 flag, the following block contains
    the picture content in chunky format. This means either that
    each byte contains one pixel (when -8 is being issued), commonly
    used for chunky-byte-buffers, or each byte contains 2 pixels,
    each using 4 bits (when -4 is being issued), with the upper 4
    bits (4-7) describing the left pixel and the lower 4 bits (0-3)
    containing the right pixel. This is useful for chunky-nibble
    buffers.

This file-format is suitable and intended for use in programs that 
require easy to access pixel information, which is in most cases hard 
to do with the Atari ST internal bitplane format, where the bits for 
each pixel are scattered over 2 or 4 words.
The conversion program was mainly written for converting DEGAS 
graphics to chunky format for usage in so-called "new-school" demos, 
that require chunky pixel formats for internal handling.

The renormalizing by a factor of 4 is sensible for any kind of
chunky data that is directly being used in conjunction with the
chunky-to-planar routine using byte-buffers since in this case,
usually each pixel-value is being used as an offset for a table
of longwords. Since a longword consists of 4 bytes, addressing
the correct table entry requires a multiplication by a factor of
four.
Because nibble buffers do not allow values larger than 15 per
pixel, the renormalization cannot be done on these.


Absolutely no warranties are given with this program.
Compatibility should be high, since only GEMDOS is being used.
Tested on TOS 2.06 with and without NVDI 4.11, TOS 4.04 with and
without NVDI, MiNT and N.AES 2.0 (on a FAT12-filesystem), 68000
and 68030 processor, in various monochrome and coloured
resolutions.


Known bugs:
  The program has been tested for a while and has several error
  handling routines. False flag-parameters, bogus flag settings
  such as faulty x- or y-sizes, file-not-found and file-creation
  errors are being detected and reported. Additional spaces in the
  parameters are commonly ignored, just between -x, -y and the
  digits may be no space. Otherwise, one space just terminates the
  flag or the filename given and additional spaces will not be
  read or interpreted.
  The DEGAS-file is being checked by the size, the output-file is
  however not being checked for, so overwriting will definetly be
  done if the file already exists.
  Otherwise, if you find this program malfunctioning, please report
  the conditions that make it malfunction to me so i can fix it.

Small warning:
  MiNT users should be aware that the ordinary GEMDOS routines for
  loading and saving files will be used. This might cause trouble 
  on extended file-systems. It is recommended to be used only on
  filesystems where the GEMDOS routines are working well.
  No responsibility will be taken for any loss of data that might
  occur in conjunction with this program on any filesystem.


Thanks to:
  Ray of .tSCc.   for his help and motivation
  Ultra of Cream  for telling me about byte and nibble-buffers
  Evil of DHS     for his demo-engine that has been massively
                  redesigned for these purposes
  J.F.Reschke,
  H.-D. Jankowski,
  D.Rabich        for the ST-Profibook, otherwise the logic of
                  writing a TTP-program would have stayed a
                  miracle to me.





Enjoy,

             The Paranoid of Paranoia 2002
      (paranoid@atari.org)   (http://paranoia.atari.org)