

                        NEOCHROME FORMAT PICTURE VIEWER
                                 By Lee Russell
     Index.

     Section A.
             A.1. - The Purpose Of This Program.
             A.2. - The Limitations Of This Program

     Section B.
             B.1. - Machine Type.
             B.2. - Display Type.
             B.3. - Available Memory.

     Section C.
             C.1. - A  Discussion  Of  Coding  Conventions  Used  In  This
                    Program.
             C.2. - A Discussion Of Memory Allocation.
             C.3. - Discussion Of GEM Usage.
             C.4. - Function Prototype Analysis.

     Section D.
             D.1. - User Guide.

     Section E.
             E.1. - Technical Guide.

     Appendix A.
             A.1. - Acknowledgements.


     ======================================================================
     Section A.1. - The Purpose Of This Program.

     This program allows  the  user  to  display  NEOCHROME format ('.neo')
     picture files without having to load  the package itself. This will be
     of benefit to artists  who  need  to  locate  pictures quickly, to DTP
     users who may not have access to  the package itself and to anyone who
     simply wants to view artwork.

     The NEOCHROME format is well supported,  with most packages offering a
     load / export '.neo' option.

     ======================================================================
     Section A.2. - The Limitations Of This Program.

     This program has the following limitations,

        a) It will only allow the user to display one picture per session.
           It must be re-loaded every time a picture is to be displayed. I
           hope to improve on this in version 1.1.

        b) It does not give any on-screen help to indicate that the user
           should click the left mouse button in order to finish looking
           at a picture. Again, I hope version 1.1 will correct this.

        c) The NEOCHROME format only supports low resolution pictures.
           Therefore the user will have to find another viewer to display
           medium and high resolution pictures.

     ======================================================================
     Section B.1. - Machine Type.

     This program should run  on  any  Atari  ST/STE/TT/Falcon. It makes no
     assumptions about the platform it is  running  on. If the host machine
     has a Blitter chip available this is enabled and utilised.

     Section B.2. - Display Type.

     This program is configured to run in low resolution only. Therefore, a
     colour display is required.

     Section B.3. - Available Memory.

     This program should  run  quite  happily  run  on  a 'standard' (512k)
     machine. It requires a workspace of approximately 32k.

     This program will operate much faster  if the pictures to be displayed
     are kept in a RAM disk.

     ======================================================================
     Section C.1. - Discussion Of Coding Conventions.

     In this program the following coding conventions apply,

     The base address for the temporary  screen buffer is referenced by the
     variables picaddr and tpicaddr.

     All GEM function calls requiring the VDI workstation handle are passed
     the variable handle.

     The variable name cntr is used as the control variable in loops.

     In the function disp_pic  the  clipping  rectangle is referenced using
     the 'standard' variable name 'pxyarray'.

     Memory for the  temporary  screen  buffer  is  allocated  using malloc
     rather than the GEMDOS  function  Malloc.  This  is  because Malloc is
     limited to 20 blocks of allocated memory per process under TOS 1.0/1.2
     and exceeding this limit may cause the  machine to crash. There are no
     limitations using the internal memory manager malloc.

     All error conditions are flagged to  the user via form_alert's and the
     program  then  terminates  via  the  exit  function  with  the  status
     EXIT_FAILURE.
     ======================================================================
     Section C.2. - Memory Allocation.

     This program uses  only a  handful  of  global  variables and there is
     only one significant local memory allocation;

     Global Variables :

     FILE *neo_file     This is the pointer to the picture file which is
                        to be displayed.

     short old_pal[16]  This contains a copy of the initial colour
                        palette, before a picture is displayed.

     short new_pal[16]  This contains a copy of the colour palette to use
                        for the picture to be displayed; as read in from
                        neo_file.

     short *picaddr     This points to the base of the area allocated to
                        hold the picture to be displayed.

     short *tpicaddr    This is initialy set as a copy of picaddr. It is
                        used in the function open_file() to store each
                        word of picture data in the malloc'ed area.

     int ap_id          The GEM AES application handle.

     short handle       The GEM VDI virtual workstation handle.

     short phys_handle  The GEM VDI physical workstation handle.

     short work_in[11]  GEM VDI workstation defaults array. Used in
                        v_opnvwk().

     short work_out[57] Array returned by v_opnvwk().

     short contrl[12]   VDI global array.
     short ptsin[128]   VDI global array.
     short ptsout[128]  VDI global array.

     short dummy        Used in functions requiring a dummy parameter.

     Local Variables :

     As detailed above, both  picaddr  and  tpicaddr  reference a malloc'ed
     memory area. This area is  allocated  in the function initialise() and
     is 32000 bytes  long  (the  size  of  the  ST's  memory  mapped screen
     display).

     ======================================================================
     Section C.3. - Discussion Of GEM Usage.

     There is very little use made  of  GEM in this program. In particular,
     no use is made of windows. The  system will only communicate errors to
     the user  via  form_alert()s,  otherwise  the  program  is  quite 'un-
     friendly'. However, the concept  is  simple  so  very little on screen
     help should be required.

     The program incorporates calls to the following GEM / TOS functions;

        Function        OS              Purpose
        appl_init()     AES             Open AES Application
        graf_handle()   AES             Find The VDI Physical Handle
        v_opvwk()       VDI             Open VDI Virtual Workstation
        appl_exit()     AES             Inform AES That Program Is
                                        Terminating.
        form_alert()    AES             Display Error Messages.
        v_clsvwk()      VDI             Close VDI Virtual Workstation.
        Blitmode()      XBIOS           Get / Set Blitter Configuration.
        Getrez()        XBIOS           Determine Current Display Mode.
        getcd()         GEMDOS          Determine Current Drive & Path.
        fsel_exinput()  AES             Get A Filename Using Extended File
                                        Selector.
        graf_mouse()    AES             Change The Mouse Form.
        v_clrwk()       VDI             Clear The VDI Virtual Workstation.
        Setpalette      XBIOS           Set The Display Palette.
        vro_cpyfm()     VDI             Perform A BitBlit Operation.
        evnt_button()   AES             Wait For A Mouse Button Event.

     The picture is displayed by 'blitting'  it  from the buffer pointed to
     by picaddr using the VDI function  vro_cpyfm(). This method was chosen
     for its speed of screen update; it  will  of course be faster on those
     machines fitted with a blitter chip.

     ======================================================================
     Section C.4. - Function Prototype Analysis.

     void initialise(void);
     Initialises the AES via appl_init(). A  GEM VDI virtual workstation is
     opened. A memory block 32000 bytes  long is reserved for the NeoChrome
     format picture data. If a hardware blitter is available it is enabled.
     The current screen resolution is checked to ensure that the program is
     run in low resolution only.  The  current  colour palette is stored to
     enable  the  initial  colours  to   be  restored  before  the  program
     terminates.

     void open_file(void);
     The user selects a '.neo' file to display from the GEM extended file
     selector. This file is opened and read into memory.

     void disp_pic(void);
     The mouse pointer is hidden  and  the  picture  is displayed. Once the
     user has clicked the left mouse button the colour palette is reset and
     the mouse is re-enabled.

     void close_station(void);
     The memory reserved for the picture  data is released. The workstation
     is  cleared  and  closed  and   the  AES  application  terminated  via
     appl_exit().

     void read_error(void);
     This function displays an  error  form_alert()  if  the NeoChrome disk
     file cannot be read.  The  memory  reserved  for  the  picture data is
     released. The workstation is  closed  and  the  AES  informed that the
     program no longer requires its  services  via appl_exit(). The program
     then terminates via exit() returning the value EXIT_FAILURE to the OS.
     ======================================================================
     Section D.1. - User Guide.

     PICSHOW is a low resolution program that uses the ST's 16 colour , 320
     x 200 pixel display mode.

     Your ST computer must  be  in  low  resolution  before  you start this
     program. If the computer is not in  low resolution an error message is
     diplayed and the program terminates.

     To use this program simply select  a  NeoChrome format picture file to
     display from the GEM File Selector.  After  a few moments the selected
     picture will be displayed. When you  have finished viewing the picture
     click the left mouse button to  return  to  the desktop. If you decide
     not to display a picture simply click on the CANCEL button on the File
     Selector, you will be returned immediately to the desktop.

     If your machine is equipped with  a  Blitter chip this will be enabled
     and used by this program. You  may  wish to deactivate this chip after
     using Picshow.

     Installation Notes.
     This program will run from any  disk  drive  / RAM disk setup that you
     may have and need not be in the root directory.

     Disclaimer Notice.
     This program has been tested on the following machine configurations;

        ATARI 520STFM - with 4meg memory
        ATARI 520STE  - with 1meg memory

     and has been found to work with no problems.

     In the event of  this  program  malfunctioning  the  author accepts no
     responsibility for any losses that  the  user  may suffer. The user is
     deemed to accept these  terms  as  soon  as  he  /  she first uses the
     program.

     ======================================================================
     NEOCHROME FORMAT PICTURE VIEWER

     Suggestions, Comments and Bug Reports.
     Any user who wishes to offer  suggestions  or comments on this program
     or who has discovered a serious bug  can  write to me at the following
     address,

        Mr. L.J. Russell
        1 Drybeck Avenue
        Ramsgate
        Kent
        CT11 ONX

     This program is designated to be PUBLIC DOMAIN software by the author.
     The software may  be  freely  copied  and  distributed  subject to the
     following conditions,

        i) The author retains the 'intellectual' copyright to the program
           code,
       ii) These notes must be distributed along with the software,
      iii) The program code may not be altered by anyone other than the
           author.

     Enjoy !

     L.J. Russell
     15th August 1993
     Revised 22nd October 1994

     ======================================================================
     Section E.1. - Technical Guide

     There are  three  technically  interesting  topics  addressed  by this
     program,

             i) The format of a NeoChrome picture file,
            ii) The layout of the ST's video RAM,
           iii) The usage of the Blitter functions.

     i) NeoChrome File Format.

     The format of a NeoChrome disk file is :-

        1 Word  - Flag (Always 0)
        1 Word  - Resolution (0 = Low Res, 1 = Med. Res, 2 = High Res)
                  (Picshow assumes all .neo files are Low Res)
       16 Words - Colour palette. Word 1 = Background colour.
       12 Bytes - Filename (Usually left blank)
        3 Words - Colour animation controls.
        1 Word  - Image X offset (Unused, always 0)
        1 Word  - Image Y offset (Unused, always 0)
        1 Word  - Image Width (Unused, always 320)
        1 Word  - Image Height (Unused, always 200)
       33 Words - Reserved for future expansion
     16000 Words - Picture data, entire screen saved as one continuous
                   block.

     ii) The Layout Of The ST's Video RAM.

     The Atari ST range of computers use  a  32k  block of RAM to produce a
     memory mapped video display. This RAM can currently be configured into
     three modes,
        Low Resolution    - 320 x 200 pixels, 16 colours
        Medium Resolution - 640 x 200 pixels, 4 colours
        High Resolution   - 640 x 400 pixels, 2 colours

     This program  in  only  concerned  with  generating  a  low resolution
     display.

     In low resolution each pixel requires 4 bits to hold its colour index.
     However, rather than storing all  the  bits  for  a pixel in one word,
     they are spread over 4 words.  Thus  four  words hold all the data for
     sixteen pixels. All the lsb's of a pixel  are in one word and the next
     bits in the next word and so on.

     iii) The Usage Of The Blitter Functions.

     This program uses the Blitter  (Bit  Block  Transfer) routines to copy
     the picture data from a temporary  buffer into the memory mapped video
     RAM. If there is a Blitter chip fitted it is enabled.

     The presence of a hardware blitter is checked for by calling the XBIOS
     function Blitmode. The format of this function is :-

        old = Blitmode(mode);

        short old;      - old blitter configuration
        short mode;     - new blitter configuration

     The presence of a blitter  is  checked  for  by  passing -1 in mode to
     obtain the current blitter status. This  status is returned in old and
     has two bits which are of use,

        Bit     Meaning When Set
        0       Perform Blits In Hardware
        1       Hardware Blitter Is Available

     If a blitter is available the command Blitmode(old|1); will enable it.

     This programs performs a blit by calling the VDI function vro_cpyfm().
     The format of this function is :-

        vro_cpyfm(handle, wr_mode, pxyarray, source, dest);

        int handle;     - VDI workstation handle
        int wr_mode     - logic operation to perform
        short *pxyarray - pointer to 8 shorts which describe the source
                          rectangle in the source form and target
                          rectangle in the destination form.
        MFDB source     - source memory form definition block
        MFDB dest       - destination memory form definition block

     An MFDB has the following structure,

        typedef struct fdbstr
                {
                void *fd_addr;
                short fd_w;
                short fd_h;
                short fd_wdwidth;
                short fd_stand;
                short fd_nplanes;
                short fd_r1;
                short fd_r2;
                short fd_r3;
                } MFDB;

     The various elements of the MFDB are :-

        fd_addr         - gives the address of the memory area to use.
                          This should be NULL if a physical device (like
                          the screen) is to be used.

        the remaining parameters may be left blank if fd_addr = NULL.

        fd_w            - Width of form in pixels. For a low resolution
                          picture this should be 320.
        fd_h            - Height of form in pixels. For a low resolution
                          picture this should be 200.
        fd_wdwidth      - Form width in words. This is equal to the width
                          of the raster area in pixels divided by the word
                          size. For a low resolution picture this should
                          be 20 - 320 / 16 = 20.
        fd_stand        - 0 = the form is in device specific format
                          1 = the form is in device independant format
                          For a NeoChrome file this is set to 0.
        fd_nplanes      - Number of bit planes. A low resolution screen
                          has 4 bit planes.
        fd_r1 to fd_r3  - Reserved fields, do not set to any value.

     The wr_mode parameter can be one of  16 values. It describes the logic
     operation to be performed between the source and destination forms. As
     this program is merely concerned with displaying a full screen picture
     the value S_ONLY has been selected.  Note, the HiSoft documentation is
     rather confusing on this parameter,  the Atari documentation is easier
     to understand.

     The pxyarray parameter is a  pointer  to  8  shorts with the following
     meanings,

     pxyarray[0] - x co-ordinate of top left corner of source rectangle
     pxyarray[1] - y co-ordinate of top left corner of source rectangle
     pxyarray[2] - x co-ordinate of bottom right corner of source rectangle
     pxyarray[3] - y  co-ordinate  of   bottom  right  corner  of  source
                   destination
     pxyarray[4] to pxyarray[7] repeat these for the destination rectangle.

     In order to display a full  screen  picture in low resolution pxyarray
     is declared as follows;

        short pxyarray[8]={0,0,319,199,0,0,319,199};

     ======================================================================
     Appendix A.1. - Acknowledgements.

     The author would like to acknowledge the following reference sources,

        Atari ST - Tricks & Tips - Abacus Software ISBN 0-916439-47-X

        Atari ST/TT Developer's Kit - GEM VDI Programming Guide
        (Published by Atari Corp (UK) Ltd, Ref ST/TT Developer's Kit
         Document SSW 1201-0003)

     The author would also like to thank Mr A. Bodin of Atari Corp (UK) Ltd
     for the information regarding the ST screen display which he provided.

     The information regarding the  format  of  a  NeoChrome  disk file was
     taken from an article which appeared in  the December 1991 issue of ST
     Format -
     Probing Inside Pictures.

     Atari ST, 520STFM and 520STE  are  trademarks or registered trademarks
     of Atari Corporation.

     GEM is a registered trademark of Digital Research Inc.

     The following  software  was  used  during  the  development  of  this
     program,

        Lattice C v 5.5 - (c) HiSoft & Lattice Inc
        Protext v 4.37  - (c) Arnor

     ======================================================================
