Introduction
------------

The IMAGE program uses many of Fastgraph's image display, creation, and
management routines. It lets you display and create BMP and PCX files, play
FLI/FLC files (continuously or one frame at a time), and if compiled as a
Win32 program, display JPEG files. In addition, IMAGE provides a way to
display information about the currently displayed image. As far as Windows
resources, IMAGE uses a top-level menu, with pull-down menus for each image
file type in the top-level menu, plus dialog boxes for selecting file names.

The files in the IMAGE distribution are:

   IMAGE.TXT     this file (ASCII text format)
   IMAGE.WRI     this file (Windows Write 3.1 format)
   IMAGE32.EXE   Win32 executable
   IMAGE16.EXE   Win16 executable

   C.ZIP         C/C++ source code files
   BUILDER.ZIP   C++Builder source code files
   DELPHI.ZIP    Delphi source code files
   BASIC.ZIP     Visual Basic source code files
   PASCAL.ZIP    Pascal source code files
   FORTRAN.ZIP   Fortran source code files

Initial Setup
-------------

Initially, the BMP menu only lets you open (display) a BMP file, but once you
do, its Make and Info selections are also enabled, as is the Make selection
on the PCX menu. The PCX pull-down menu is the same as the BMP pull-down
menu, but the FLI/FLC pull-down menu is different. It includes selections to
open a flic file (which displays its first frame), play a flic file
continuously (until Escape is pressed), play the next frame of the flic file,
rewind it, and obtain information about it. The JPEG menu has Open and Info
selections that behave like those on the BMP and PCX menus, but has no Make
selection. Because JPEG files require direct color virtual buffers (and thus
Win32), the items on the JPEG menu are always disabled if we compile IMAGE as
a Win16 program.

Each Open and Make menu selection obtains the image file name using the Open
File or Save File dialog boxes from the Windows common dialog box library.
The C++Builder, Delphi, and Visual Basic versions of IMAGE simply use the
common dialog box controls. For the C/C++ and Fortran versions, however,
things are more involved. We interface to the common dialog boxes through the
program's get_open_filename() and get_save_filename() functions. As the point
of the IMAGE program is to demonstrate Fastgraph's image file functions, we
wont delve into the mechanics of these two functions here. Suffice it to
say, get_open_filename() sets three global strings: file_name, containing the
full path name of the selected file; file_title, containing only the file
name and extension portions of the file name; and open_file, which contains
the same string as file_title. Similarly, get_save_filename() stores the file
name information in the file_name and file_title globals. Both functions
return OK if we selected a file, and ERR if we didnt (for example, if we
pressed the Cancel button in the dialog box).

The IMAGE programs WM_CREATE handler creates an initial 4x4 virtual buffer.
Because the image files that IMAGE loads can be any size, we create a virtual
buffer with the same dimensions as the image when we load the image. Before
we do this, however, we release the virtual buffer containing the previously
loaded image (the program's switch_buffers() function handles these tasks).
Creating the 4x4 virtual buffer eliminates the need for switch_buffers() to
treat the first image it loads as a special case (we chose the 4x4 size
because some Windows display drivers treat smaller drawing surfaces
inconsistently). The switch_buffers() function creates a 256-color virtual
buffer when loading a palette-based image file, or a 24-bit true color virtual
buffer when loading a direct color image file. To display and create direct
color image files, you must compile IMAGE as a Win32 application. In the
C/C++ version of the IMAGE program, the WM_CREATE handler also calls the
Windows API function GetMenu() to obtain a handle to the programs menus;
this is needed when we later enable or disable specific menu items.

How the Menu Handlers Work
--------------------------

The BMP|Open handler first obtains a file name through the Open File dialog
box. If successful, we call fg_bmphead() to read the BMP file header and
verify that the file really is a BMP file. If not, we display a message box
and return (this is also true if we try to display a 24-bit BMP file from a
Win16 program). If we get this far, then we do have a BMP file, so we call
fg_bmppal() to determine the number of colors in the BMP image, storing the
result in the global variable colors (note that we dont do anything with the
BMP palette, fg_bmppal() just provides a convenient way to get the number of
colors). Next we call  fg_bmpsize() to get the BMP image width and height,
storing these values in the global variables cxBuffer and cyBuffer. We then
call switch_buffers() to release the current virtual buffer and create a new
virtual buffer with dimensions equal to those of the BMP file were loading.
Next, fg_showbmp() loads the BMP file into the virtual buffer, and
fg_vbscale() makes it visible in the client area. Finally, we enable the
remaining items on the BMP menu and disable all items on the other menus
except Open and Make.

The BMP|Make handler obtains the name of the BMP file to create through a Save
File dialog box. If successful, we call fg_makebmp() to create a BMP file
with the same color depth as the original image.

The BMP|Info handler displays the image dimensions and color depth in a
message box, using the values obtained during BMP|Open processing.

The PCX|Open handler is very similar to the BMP|Open handler. Note how we set
bit 1 of the fg_showpcx() flags parameter. This overrides the image
positioning information in the PCX header, which might specify a position
other than (0,0).

The PCX|Make handler obtains the name of the PCX file to create through a Save
File dialog box. If successful, we call fg_makepcx() to create a 256-color
PCX file if the original image was palette-based, or a 24-bit PCX file if the
original image was a direct color image.

The PCX|Info handler displays the image dimensions and color depth in a
message box, using the values obtained during PCX|Open processing.

The FLI/FLC|Open handler first obtains the name of an FLI or FLC file and then
calls fg_flichead() to read the flic file header. After making sure we have
indeed selected a flic file, we set the colors global to 256 (because flic
files are always 256-color images) and call fg_flicsize() to obtain the image
dimensions. The switch_buffers() function then performs the virtual buffer
setup. We then call fg_flicopen() to set up the 16-byte context descriptor
for the low-level flic file routines, fg_flicplay() to load the first frame
into the virtual buffer, and fg_vbscale() to make it visible in the client
area. Next, we extract the frame count from offsets 6 and 7 in the flic file
header. Finally, we enable the remaining items in the FLI/FLC menu and
disable the Info items in the other menus.

The FLI/FLC|Play handler plays the flic file continuously with fg_showflic().
The flic file plays until the Escape key is pressed. After this, we call
fg_flicskip() with a negative frame count to rewind the flic file, so the
next call to fg_flicplay() will start with the first frame.

The FLI/FLC|Frame handler calls fg_flicplay() to play the next frame from the
flic file. If fg_flicplay() returns a zero frame count, weve reached the end
of file, so we rewind the flic file and again call fg_flicplay() to replay
the first frame. In any case, we then call fg_vbscale() to make the frame
visible in the client area.

The FLI/FLC|Reset handler calls fg_flicskip() with a negative frame count to
rewind the flic file, and then calls fg_flicplay() to display the first
frame. As usual, fg_vbscale() makes the first frame visible.

The FLI/FLC|Info handler displays information about the flic file, using
values obtained during the FLI/FLC|Open processing. Because flic files always
contain 256 colors, we instead display the frame count, which is a more
meaningful metric than the color depth for flic files.

The JPEG|Open handler first obtains a file name through the Open File dialog
box. If successful, we call fg_jpeghead() to read the JPEG file header and
verify that the file really is a JPEG file. If not, we display a message box
and return. If we get this far, then we do have a JPEG file, so we set the
colors global to zero (because JPEG files are always direct color images).
Next, we call fg_jpegmem() to calculate the required size of the internal
JPEG buffer, allocate that much dynamic memory, and pass the resulting buffer
and its size to fg_jpegbuf(). We then call fg_jpegsize() to obtain the image
dimensions and switch_buffers() to perform the required virtual buffer setup.
Next, we call fg_showjpeg() to load the JPEG file into the virtual buffer,
free the memory allocated for the internal JPEG buffer, and then call
fg_vbscale() to display the image in the client area. Finally, we enable the
Info item on the JPEG menu and disable all items on the other menus except
Open and Make.

The JPEG|Info handler displays information about the JPEG file, using values
obtained during the JPEG|Open processing. Because JPEG files are always
direct color images, we always display the image color depth as 24-bit RGB.

For more information about Fastgraph for Windows, contact:
----------------------------------------------------------

Ted Gruber Software
P.O. Box 13408
Las Vegas, NV  89112

(702) 735-1980 (voice)
(702) 735-4603 (fax)

email: fastgraph@aol.com
web: http://www.fastgraph.com
ftp: ftp.fastgraph.com/fg/Windows
