Current Shareware 1994 January/SHAR194.ISO/graphuti/fimaps.zip/FIMAPS.DOC

Text File | 1993-10-30 | 15KB | 288 lines

FIMAPS 1.0  -  Fractint Map Creation Program

                               ┌──────────────┐
                               │ Introduction │
                               └──────────────┘
This program creates smooth 256-color palette maps for use by Fractint.
It requires at least a VGA video card and monitor capable of 320x200x256.
The program is in the public domain.

*** It is probably not necessary to read this doc in order to use the program
*** EXCEPT, please read the Running External Programs section toward the end.
*** Also, the configuration file that comes with FIMAPS is set up for viewing
*** GIFs only in 320x200x256 mode.  This can easily be changed for viewing
*** higher resolution SVGA modes.  See Viewing GIFs and Configuration.
*** The .ICO icon file is for OS/2, not Windows.

What it does
------------
This program creates 'smooth' 256-color palette maps for use with Fractint;
'smooth' meaning that all the colors gradually blend into each other.
For example, if the user selects 6 for the number of ranges the program will
select 6 random colors evenly spaced along the 256-color palette and then
gradually blend the in-between colors. This should be obvious when you run the
program.  The program can also do 'neon' effects where every other color in
the range is random and the other is a single, user selected color.  If black
is selected for the neon color, it will produce an effect like the NEON.MAP
that comes with Fractint.  This program's main purpose is to create random maps
(similar to hitting the <enter> key in Fractint) so except for the 'neon' color
the user cannot select the colors.

When the program creates a map that you like you can save it to a .MAP ASCII
file that is compatible with Fractint. Other programs, such as IMPROCES, can
also use maps in this format.
By shelling to a picture viewing program, FIMAPS can display an image with one
of it's palettes and you can change palettes with the image on screen.
John Bridges' freeware program PICEM is included for this purpose, but you can
use your favorite picture viewing program instead.

The Program
-----------
FIMAPS was written in Clarion Professional Developer 2.1 along with Jay Cotton's
PCX3 LEM (a shareware third party Language Extension Module) and AKA Tools 2.5
(a commercial third party LEM that provides access to DOS functions, low level
system calls, etc.)
Since FIMAPS is in the public domain I have included the source code although
I doubt if many of you have access to a Clarion compiler.
However, except for the screen handling stuff, Clarion is very similar to
BASIC, C, PASCAL, etc. so if you would like to see how I create the palettes you
can probably figure it out.

FIMAPS is in the public domain but I would hope that if you hack it, you will
give credit where credit is due and take the blame when blame is due.
However please note that PICEM, although free, is NOT public domain.

Any comments or bug reports would be very much appreciated.  I can be reached
on the RIME Fractal Conference or by mail at the following address:

Nick Grasso
4092 Murphy Road
Thompson, Ohio 44086
U.S.A.

                                ┌─────────────┐
                                │ Main Screen │
                                └─────────────┘
To move between the fields on the screens press the Down Arrow, Tab, or Enter to
go to the next field or the Up Arrow, Shift-Tab, or Escape to go to the previous
field.  Pressing Escape will also reset a field to its previous value and
pressing Escape on the first field will exit the screen or window.
Press one of the Function Keys shown on the bottom of the screen to do something
besides move around the fields.

Fields
------
No. of color ranges: The number of random colors that the program will create.
  This must be a number between 2 and 255. The program will create this many
  random colors evenly spaced between 1 and 255 and blend the in-between colors.
  If you select 255, you will just get 255 random colors. If you are going to
  use Neon, this should be an even number (see the Neon field).

Repeat every: If this is not 0, the color ranges will be repeated. For example,
  if No. of color ranges is 18 and Repeat every is 3, the program will choose
  only 3 random color ranges that will be repeated 6 times. This number must be
  greater than 1 and less than the No. of color ranges.  For best results, it
  should be an even multiple of the No. of color ranges.

Neon: If you enter Y (yes), FIMAPS will use a color that you define and make
  every other color random. If you use Neon, the no. of color ranges should be
  an even number, otherwise the last range of palette colors will all be the
  same.

Neon color: These fields are only used if you selected Yes for Neon. They are
  the 3 color components (Red,Green,Blue) of the Neon color. Enter numbers
  between 0 and 63. If you use 0-0-0 (black) it will make a map like NEON.MAP
  that comes with Fractint.

Set color 0: If this is N (no), the program will not mess with color 0, that is,
  it will be set to 0-0-0 (black) and will not take part in color cycling.

Save map filename: The [path\]filename of the file to save the ASCII map file.

Prompt if file exists: If you enter Y (yes) the program will ask first if you
  hit F6 to save a map file and it already exists, otherwise it will overwrite
  any existing file without asking.

View GIF filename: The [path\]filename of the GIF file that you want to view.
  See Displaying GIFs.

Function Keys
-------------
Press one of these at any time to make the program actually do something.

F1 - Help: Don't expect too much from this key.

F2 - Configuration: This is where you specify which programs are run when F5 or
  F7 is hit.  You can also specify these options in the FIMAPS.CFG file so you
  don't have go to through this configuration each time you run FIMAPS.
  (See Configuration)

F3 - Exit: Return to from whence you came.

F4 - View current map: This will re-display the current map.  If you haven't yet
  created a map by hitting F9, it will first read the default map from your
  video card - this may take some extra time.

F5 - View GIF.  If you haven't yet created a map, the note for F4 applies.
  If the 'View GIF filename' is blank or the file doesn't exist, a scrolling
  list of all the GIFs in the current directory will be brought up and you can
  select one.  You can also enter wildcards, e.g., C:\PICS\T*.PCX.
  (See Displaying GIFs)

F6 - Save current map: Writes an ASCII file compatible with Fractint's .MAP
  files.  Note that the file will contain a '<' to the right of each random
  color the program selected.  The colors in between have been 'blended'.
  I used this for debugging but I thought I would leave it in.  However, these
  will not appear if you have done any color cycling.

F7 - Execute another program as defined in your configuration.
     (See Running External Programs)

F8 - Execute any DOS command. (See Running External Programs)

F9 - Create map: Creates and displays a new color map based on the fields
  currently on the screen.

                              ┌─────────────────┐
                              │ Displaying GIFs │
                              └─────────────────┘
Since Clarion doesn't have any built in graphics capabilities and I don't know
of any third party extensions to display GIFs, FIMAPS must shell to an external
program to display an image when F5 is hit.  This program must have the
capability to display the image and then exit leaving the image on the screen
and not resetting the video mode.  FIMAPS will then be able to manipulate the
palette while the image is on the screen.  Note that FIMAPS is not limited to
GIFs; you can specify any image the external program is capable of displaying.
The freeware program PICEM is included for this purpose.  Note that the
FIMAPS.CFG configuration file specifies PICEM (actually TPICEM, the 'tiny'
version) at a resolution of 320x200x256.  To display higher resolutions change
the /v:l parameter to whatever you want (see PICEM.DOC).

If you have a favorite picture viewing program, you can use it instead of PICEM.
The only requirement is that it must be able to display a picture from a command
line prompt and then exit but leaving the picture on the screen.
This program, along with any necessary command line parameters, are specified
in either FIMAPS.CFG or by pressing F2 on the Main Screen.
I have tested FIMAPS with 3 other popular picture viewing programs.
Use the following command line parameters:

  PICEM (or TPICEM) /V:x /E /K
  VPIC /A /R
  GDS /S /Z0 /X
  CSHOW

For PICEM, replace x with the video mode you want, e.g., /V:L for 320x200x256,
/V:S for SVGA 640x480x256, /V:T for SVGA 800x600x256 (see PICEM.DOC for others).
*** I have noticed that PICEM 2.7 (the version included here) does not display
*** 1024x768x256 GIFs on my system.  There is a later version (3.01d) but that
*** version doesn't run properly on my system at all.

VPIC is my favorite since it is the only one that will run in existing memory
on my machine; it decodes the picture directly to video memory.
Also, unlike PICEM, it will try to pick the correct video mode based on the
size of the picture if you use the /A parameter.
CSHOW is a special case because you must append '+X' to the end of the filename.
FIMAPS takes this into account.  If the string 'cshow' is anywhere on the
View GIF command, it will automatically append '+X' to the View GIF filename.

                          ┌────────────────────────┐
                          │ While in Graphics Mode │
                          └────────────────────────┘
While a picture or a map is on the screen, i.e., after you hit F4 or F5, you can
create a new map or cycle the colors by pressing one of the following keys.
You will note that FIMAPS is much slower than Fractint when displaying maps and
cycling colors.  Sorry, but I'm not young enough to code in assembly language.

  F9 or Enter creates a new color map
  > or . color cycles forward one time
  < or , color cycles backward one time
  1 thru 0 color cycles forward or backward times 10, e.g., 1 will cycle 10
    colors, 2 will cycle 20 colors, 0 will cycle 100 colors
  + or gray + specifies forward color cycling for 1 thru 0
  - or gray - specifies backward color cycling for 1 thru 0
  Any other key returns you to the previous screen

The +/- do not color cycle; they only determine which direction to color cyle
if 1 thru 0 is hit. > and < will also set the direction for 1 thru 0.

While a map is on the screen you can hit F5 to display the picture specified
by View GIF filename.  However, unlike pressing F5 on the Main Screen, if this
file doesn't exist, a list of files in the current directory will not appear.
You will be returned to the Main Screen where you have to press F5 again if you
want to bring up a list of files.

When you have a color map that you like you must return to the Main Screen in
order to save it to a file. FIMAPS does not have the ability to read .MAP files
from disk or to save .GIF images to disk.

                               ┌───────────────┐
                               │ Configuration │
                               └───────────────┘
When you run FIMAPS, it looks for a file called FIMAPS.CFG in the current
directory.  If it's not there, it looks in the directory that FIMAPS.EXE is in.
This configuration file tells FIMAPS what program to run when F5 or F7 is hit.
The FIMAPS.CFG that comes with FIMAPS specifies TPICEM as the F5 program and
FRACTINT as the F7 program. You can change these to whatever you want - see the
FIMAPS.CFG file itself for its format.
Also, these can be changed by hitting F2 on the Main Screen to bring up the
Configuration Screen.  However, the configuration file saves you from doing this
every time you run FIMAPS.  The fields on the Configuration Screen are:

View GIF command: this is the program (including any command line parameters)
  that will display the image specified on the 'View GIF filename' field on the
  main screen (See Displaying GIFs).  Specify the \directory if this program
  isn't on your path.

Run in existing memory: enter N or Y - see Running External Programs below.

DOS command for F7: this is the program to run when F7 is hit.  This can be any
  valid DOS command, program, or batch file - see Running External Programs.

Run in existing memory: enter N or Y - see Running External Programs below.

Screen text for F7: this is simply the text that will appear on the Main Screen
  to remind you what will happen when you hit F7.

                         ┌───────────────────────────┐
                         │ Running External Programs │
                         └───────────────────────────┘
When FIMAPS runs an external program or command via the F5, F7, or F8 key, it
can do so in two ways.  It either runs the program in existing memory or it
downloads most of itself to disk, runs the program, then reloads itself.
Running in existing memory is faster but you are limited to the memory left
after FIMAPS has hogged most of it.  The amount of memory left while FIMAPS is
running is displayed in the upper left of the Main Screen.  This number is
updated at various times but should not change too much.  Unless you are running
DOS commands or small programs you should tell FIMAPS to NOT run in existing
memory.

However, when not running in existing memory, you can set an environment
variable CLATMP to tell FIMAPS where to put its memory image file. You can
specify a RAM drive if you have one, e.g., type SET CLATMP=D:\ at the DOS prompt
before running FIMAPS if you have a RAM drive called D: If you don't specify
CLATMP it defaults to the current directory.  The memory image file will be
about 300K.  If you get a message saying Couldn't Create .TMP Memory Image File,
then you probably don't have 300K available on the disk. Be careful when running
external programs in existing memory as it is possible to crash your PC.

As noted above, VPIC is the only picture viewer I know of that can run in
existing memory, at least on my machine.  You can speed up displaying GIFs even
more by copying your GIF view program to your RAM drive before running FIMAPS.

                              ┌───────────────┐
                              │ Miscellaneous │
                              └───────────────┘
You will no doubt notice that FIMAPS is considerably slower than Fractint when
displaying color palettes and color cycling.  This program ain't written in
assembly language!  FIMAPS runs much faster under OS/2 2.1 because of OS/2's
32 bit graphics system. I have included an icon for OS/2.

I plan on adding more special effects for future releases, for example, uneven
spacing of colors, non-smooth transitions, and more user control over the colors
selected. If you have an interesting algorithm for creating color maps, please
let me know and I will try to program it into the next version.
Any comments, criticisms, or bug reports are greatly appreciated.
See the Introduction for my address.

--Nick--