*******************************************************************************
* PhotoQL V0.19: a  GD2 PE program  written in C by Roberto Porro 14 Mar 2001 *
*******************************************************************************

-------------------------------------------------------------------------------
                                   LEGAL STUFF
-------------------------------------------------------------------------------

                                Copyright notice

This software is  a freeware, it is  NOT in the public domain.  This software is
copyright (c) 2000 Roberto Porro.

You are granted a limited license to:

 - use this  software free  of charge  for  your own  usage and/or  in your  own
   programs (including commercial and shareware programs);
 - make as many copies of this software as you like;
 - give  to others as  many copies of  this software as  you like, by  any means
   you like (BBS, Internet, disks, CD-ROM, etc...);

provided however that:

 - when you incorporate my software into yours, this is mentioned;
 - any  copy given  to another  person be entire  and unmodified,  i.e. contains
   all the unmodified files of this software, including this copyright notice;
 - any copy  given to  another  person  be so  on a non-profit  and  no  benefit
   basis (i.e. you may charge for the media and mailing costs ONLY);
 - you do not  claim for any ownership / rights on this  software and you do not
   place any restriction on its further distribution.

                                     Disclaimers

The  author cannot  be  held liable  for  any  loss or  damage  -direct or  not-
resulting from the use of this  program or its documentation. Although carefully
tested, this  program is not guaranteed  being bug free. This  software is free,
use it at your own risks or just don't use it at all.

-------------------------------------------------------------------------------
                                       Preface
-------------------------------------------------------------------------------

Whit the new GD2 interface the QL family computer has, at last, the way to show 
graphic up to 24 bit.

-------------------------------------------------------------------------------
                                    About PhotoQL
-------------------------------------------------------------------------------

Photo QL is a C piece of code that  uses the Qdos call to trap#3 to perform the
correct ink call.
It reads data from a file, stores a row of pixels in a buffer and then call the
appropriate QDOS routine to display them.

-------------------------------------------------------------------------------

The PhotoQL file is shipped in ZIP format and you will find:

1. - The program itself
2. - This text

-------------------------------------------------------------------------------
                                 How to use PhotoQL
-------------------------------------------------------------------------------

PhotoQL can  be EXecuted  from the basic command line or from the  Shell in the
standard Unix way:

        ex flp1_photo_exe;"flp1_image_tga"

        > photo win3_images_image_tga

It's up  to you to  select the  correct file type or the program will refuse to
show a single pixel!

Another way is to use it within the FileInfo II, so if you want set it to  work
properly do:

        1. call File Info II config

        2. fill with:

        Extensions: extension of the file PhotoQL can deal with (see below)
        Actions: Show (or something else)
        Executable file to load: full_path_photo_exe
        Command line: <<devN_name_ext>>
        Put on job stack

        3. Back to point 2 for each file type

        4. Save a configured copy!!

Then you have only to select the file to show it!

From the 0.17 release you may invoke Photo QL with no  parameters: in this  case
a click on the ESC l_item will prompt for a selection menu and, from here, a new
LOAD option allows to call a QPAC2 FILE SELECT MENU.
There are also a QUIT and a CANCEL options.

--------------------------------------------------------------------------------
                                  What you need
--------------------------------------------------------------------------------

PhotoQL uses the new graphic GD2 routines, so you MUST HAVE SMSQE with GD2 level
implemented.
You also  need: PE & WMAN  (included with SMSQE), a pointer device, about 360 Kb 
memory free (min.) in  order to  load  a 300x200  24 Bit image, the Button Frame
whilst about 500K are the bytes required by a 640x400 interlaced RGB png image.

The program runs at a good speed on my QXLII 68040 with 8Mb RAM.

--------------------------------------------------------------------------------
              What kind of format PhotoQL can deal with?
--------------------------------------------------------------------------------

PhotoQL  V 0.19 is able to  display:

- TARGA (TGA) 2 24 bit images.
- TARGA (TGA) 10 24 bit RLE (a lot of them can be  produced  by  POVRAY).
- BMP (BMP) uncompressed type (may  be found in the MS-Windows OS).
- BMP (BMP) RLE8 and RLE4.
- PCX (PCX) (Zsoft  Paintbrush type) 24 bit, 256  colours, 16 colours  EGA/VGA
        tyep 4 colours (*) CGA, B&W monochrome and some "type 2" PCX (standard
        is 3 or 5).
- GIF (GIF) (**) files (1)
- JPEG (JPG) as from  "The  Independent JPEG  Group's JPEG software release 6b
      of 27-Mar-1998". (See the JPEG library for more).
- PNG (PNG) images as from the PNG library.
      Since the  PNG library  is able to  handle  gamma  correction the system
      variable  "SCREEN_GAMMA" may be used to give a gamma correction value to
      the prog. A default value of 1.7 is given.
- PIC standard QL image format mode 4, mode 8  and mode 33 Q40 native colours:
      tested only with one demo image. :(
- TIF TIFF images: uncompressed and  compressed, fax G2/G3 and all types as in
      the: " LIBTIFF 3. 5. 6 beta  Copyright 1988-1996 Sam Leffler / 1991-1996 
      Silicon Graphics, Inc. "

--------------------------------------------------------------------------------
                              NEW in this version.
--------------------------------------------------------------------------------

In version 0.19:

1)- Complete TIFF decoding support. (Not all features tested yet!). Embedded  in
    the code are routines for printing  tiff dirs, write tiff files etc. (may be
    in future releases....).
2)- Due to  the  large amount  of memory  required by  the LIBTIFF  there is  no
    resize function for tiff images. (I am working around it).
3)- The GIF engine now implements the restore background function.

--------------------------------------------------------------------------------
                               PREVIOUS VERSIONS 
--------------------------------------------------------------------------------

In version 0.18 there are some changes:

1)- Images are centered, a dotted gray area surrounds the image if the window is
    larger than the image itself.
2)- If the image is too large to fit in the current screen a resize routine will
    be performed. 
    If there is no memory to handle the image a 'Not enough memory' warning will
    be shown and no resize is done.
3)- A gauge is shown during the resize process.
4)- The resized image is converted into a jpeg temporary file named "res_jpg":
    this file is placed in the win1_ root and it will be unlinked on exiting the
    program. 
    If you want to keep this file make a copy when PhotoQl is running.

                                   --- * ---

If you have installed the "GBM" package  it is  possible, from version 0.16,  to
take advantage of this packet convert capacity.

Four new system vars have been added to do so:

1)- GBM_PTH is used to specify the path of the "gbmbpp" executable in the form:
    SETENV "GBM_PTH=win1_bin_gbmbpp"

2)- GBM_PAR is used to specify the params to give to "gbmbpp" as:
    SETENV "GBM_PAR=-m 8:8:8"

3)- PQLFIL is the device_path for the temp file pic_pcx:
    SETENV "PQLFIL=ram1_"

4)- PQLFCT: removed from v.017

The only required value is GBM_PTH others are defaulted to:

    GBM_PAR -m 8:8:8
    PQLFIL ram1_pic_pcx

If no GBM_PTH or an incorrect GBM_PTH is given the program will exit.

To use this feature:

A. Install the GBM package (download it form Thierry Godefroy's site).
B. Read the GBM manual!!!
C. Modify your boot adding the new SETENVS.
D. Add the file extensions to FileInfoII as shown before.
E. Reboot your system.
F. Try it!

NOTE that  some  files  don't display  and Photo QL exits  after few  secs: that
means some error during gbmbpp phase i.e. the file is not in the  correct format
and it is not a Photo QL fault.

                                   --- * ---

(*) Due to the CGA palette  system, pseudocolours are used so some image may not
    be displayed with the original palette. 

(**)       "The Graphics Interchange Format(c) is the Copyright property of
            CompuServe Incorporated.  GIF(sm) is a Service Mark property of
            CompuServe Incorporated."

(1) About this GIF decoder.

This GIF engine decoder takes care of a subset of GIF89a specifications.
It is  able  to recognise  all  blocks  in a GIF Data  Stream but  only few  are
processed. 

Apart the header block and the Logical Screen Descriptor, it can deal with:

- Global Colour Table (if any) or a 256 colours table is added as default.
- Image Descriptor Blocks: Interlaced Flag processed.
- Graphic Control Extension Blocks: only Transparency Flag and Index processed.
- Comment Extension Blocks: skipped.
- Plain Text Extension Blocks: skipped.
- Application Extension Blocks: skipped.
- Trailers: recognised.
- On Line Capabilities Dialogue: not implemented.

Due  to the  implemented  functions and the  hardware there is  something like a
capability of run some animated gif files, but it is still slow!

                                   --- * ---

ONLY FOR TIFF in ver 0.19.
There  is no  limit  on the  image size (only ram): if the  size is greater than 
the  screen format then only the left uppermost section will be shown.
Try to change the display size.


*** NOTE ABOUT JPEG.

The JPEG file format, as defined in JPEG  specifications, is always top - bottom 
oriented. So images displayed upside down are not standard!!

                                 --- * ---

PhotoQL will refuse to operate if:

1. the file format is not supported,
2. there is not enough memory to allocate memory for row and/or palette,
3. the GD2 level interface is not present,
4. PE is not present,

and it'll return to the caller.

PhotoQl can operate in mode 4 or mode 8  too but you will  see only 4/8  colours
(do you think something else?), so put the screen in true color mode!

The Basic command used for switching to true colour mode is: DISP_COLOUR 3

--------------------------------------------------------------------------------
                                       To do
--------------------------------------------------------------------------------

1. Add new graphics 
2. Add a 'Save as...' option
3. More..... (I have many filters like  emboss, edge, lens, crop, etc... only a
              lot of time is required!!!)

Thanks to Thierry Godefroy for his precious suggestions.

-------------------------------------------------------------------------------
                                       History
-------------------------------------------------------------------------------
V 0.19 14 Mar 2001

Files format added:
	TIFF (all formats?) see LIBTIFF documentation for more.

New functions:
	GIF restore background implemented.

----

V 0.18 17 Dec 2000

New functions:
        Image centering routines.
        Auto resizing facility when the image is larger than the screen.
        Jpeg temporary image from resized image (see text).
        Gauge indicator during resizing and converting process.
-----

V 0.17 01 Dec 2000

Files format added:
        PIC standard QL file type mode 4, 8, 33(*). 

New functions:
        New faster graphic plot routine including native colours too.
        Auto resize at startup to adjust to image size.
        Auto resize after a DO action on the resize loose item.
        A QPAC2 FILE SELECT facility.
        A QUIT, CANCEL or LOAD sub-menu (from the ESC loose item).
        Photo QL may be invoked without parameters.
        Errors in pop-up windows. (ABORT-RETRY buttons perform an exit call).

(*)     PIC 33  are pic files from  the Q40. For  those files native colours are
        used.
-----
        
V 0.16 12 Nov 2000

New functions:
        If the  GBM "Generalised Bitmap Module" is  present in  the system  this
        release is able to recall the "gbmbpp" to convert unknown formats to PCX
        standard format.
        See text for more details.
-----

V 0.15 09 Nov 2000

Files format added:
        PNG file  type. 
                        PNG files converted  internally into 8  bits per channel
        RGB(A) images. To  reduce memory usage: all images processed a row at  a
        time. Interlaced images  are shown  using the 'rectangle'  method if the
        size of the image is less than 200 x 200 pixels, otherwise the 'sparkle'
        method  will be  used but, for  speed optimization, these  operaions are
        performed  in  memory: thus wait some  time for the image! (without this
        'optimization' the image has to be redrawn 7 times!!)
-----

V 0.14.1 05 Nov 2000

Bugs fixed:
        Pick Button Thing now recalls photo_exe.
        (Thanks to Thierry)
-----

V 0.14 04 Nov 2000

Bugs fixed:
        GIF engine rewrote. The old one sometimes crashed the system.
        Resize of window now checks the screen resolution.
        
Files format added:
        GIF interlaced and some GIF animation.
-----

V 0.13 31 Oct 2000

Files format added:
        JPEG file format.
        GIF file format.
        BMP RLE8 256 colours RLE8 compression.
        BMP RLE4 16 colours RLE4 compression.
        PCX 4 Colours CGA (pseudocolours used).
        PCX B&W 2 colours.
-----

V 0.12 25 Oct 2000

Bugs fixed:
        Targa 10: last line has more pixels than the image width.
        BMP: scan lines padded with zero to end on a 32-bit boundary.

Files format added:
        PCX rle compressed 256 colours.
        PCX rle compressed 16 colours EGA/VGA.
        BMP 256 colours uncompressed.
        BMP 16 colours uncompressed.
        BMP monochrome uncompressed.

Note about PCX 256:
      This format tested only with palette id code 12 because I have no way to
      check palette with id code 10.
-----

V 0.11 22 Oct 2000

Bugs fixed:
        BMP header structure is compliant with BMP specifications.
        BMP files with odd pixel width.

Files format added:
        TGA 10 rle compressed 24 Bit graphic true colour images.
        PCX rle compressed 24 Bit graphics true colour images.
-----

V 0.10 18 Oct 2000

        This is the first release version.
        PE added.
        Resize, Move, Sleep and Esc button.
        Memory request is minimal.
        Auto detect TGA display orientation.
        File type: TGA 2 uncompressed 24 Bit graphic true colour images.
                   BMP uncompressed 24 Bit graphic true colour images.
-----

Previous alpha (never released)

        C skeleton.
        No PE, no scaling capacity, file larger than screen not plotted.
        Memory request: HUGE. (all file loaded in memory).
        Manual selection of the display orientation (upside down).
        No tests of file type.
        File type: TGA 2 uncompressed 24 Bit graphic true colour images.
      
-------------------------------------------------------------------------------
                                   Roberto Porro  gqscgp@tin.it  Savona, ITALY
-------------------------------------------------------------------------------
