              POVPANEL 2.0 -- A Control Panel for POVRAY 2.0

                        by  Malcolm Donald

                     Compuserve ID: 100036,504

                            15/10/93
-----------------------------------------------------------------
ACKNOWLEDGEMENTS:
=================
Using POVRAY has given me many hours of pleasure and many superb 
images! My thanks to the programming team for their efforts!!

As with Version 1.0, Microsoft Visual Basic for DOS
was used to design a control panel for POVRAY which would
facilitate setting the available options and enable easy
experimentation with them.

The resulting executable file was compressed using LZEXE.


----------------------------------------------------------------
REVISION HISTORY:
=================
31/12/92        Version 1.0

18/4/93         Version 1.1
                New features include:
                . Redesigned User Interface
                . On-line Help Screens
                . Integrated Text Editor
                . Multiple File Trace Capability

4/7/93          Version 1.2
                Maintenance Release.
                . Fixes problem with setting file path to
                  work(.pov) files.
                New features include:
                . Provision to turn off anti-alias switch for
                  fast tracing.
                . Ability to set up user-defined resolutions
                  for HUGE traces(e.g. 4096x4096).

15/10/93        Version 2.0
                . Redesigned user interface for POVRAY 2.0.
                . Enables setting of new features in POVRAY 2.0.
                . Includes QWIKTRACE command for fast,low detail
                  test trace.
                . Includes error trapping option for easier
                  identification of tracing problems.
-----------------------------------------------------------------


 *****************************************************************
 *    This programme is shareware.  This means you may try the   *
 *    programme for a period of 2 weeks and, if you continue to  *
 *    use it, you must pay a registration fee($5.00 US) to the   *
 *    author.  Otherwise, you are legally obliged to discontinue *
 *    using POVPANEL.                                            *
 *    For registration details please see the 'README.1ST' file. *
 ****************************************************************


INSTALLING THE PANEL:
     To install POVPANEL copy the file "pvpan2.exe" into your
     POVRAY directory(the one containing "povray.exe").  To
     display the main control panel type PVPAN2 at the DOS
     prompt in the POVRAY directory.

     ***NOTE FOR PREVIOUS PoVPANEL USERS************************
     PVPAN2 will use the information stored in your previous
     "POVRAY.DEF" file.  However, the panel settings are now
     stored in a new file - "PAN2.CFG" - so you will need to
     write a new .CFG file to disk when you are in the programme.
     You should delete the old settings file "povpanel.cfg".
     ************************************************************

GENERAL COMMENTS:
     Throughout the programme, the following controls are used:

     Ŀ    [ ] Off     ( ) Off    Ŀ    Ŀ
     _       [X] On      (.) On      ( ) 1         0.Auto  
                                 (.) 2         1.Tseng 
      TEXT     CHECK       OPTION      ( ) 3         2.Axis  
     Ŀ                              
      SET                              FRAME          LIST BOX
     
     COMMAND

     . Text Box - click to activate, then type in value or text.
                - cyan coloured boxes.
     . Command Buttons - click to activate - identified by 'happy
       face' cursor - perform the action described on button.
     . Check Boxes - click to toggle on/off - identified by '*'
       cursor.
     . Option Buttons - click to toggle on/off - identified by '*'
       cursor.
     . Frame - contains a number of option buttons, only one can
       be selected at any one time.
     . List Box - contains a list of settings. Click on setting
       to select it.

     **NB. Some setting boxes have been deactivated as a default
       eg.'User Defined Size' text boxes.  These boxes are
       outlined with a dim grey border(rather than a dark black
       one).
       To change these settings, first click on the adjacent
       option or check box to activate the text box, then type in
       your required value.
     
LAYOUT OF THE PANEL:
     The main panel has been redesigned for use with POVRAY 2.0.
     Apart from the toggles options, no values can be set from
     the main panel; it is basically a screen containing
     information on the settings of the tracing parameters.
     The screen is divided into three parts; on the left are the
     file and display card values; in the middle are the trace
     settings and, on the right are the toggles and command
     buttons.
     There is also a row of command buttons along the bottom of
     the screen.  The mouse cursor will change to reflect the type
     of control it is on; a '*' cursor means it is over a setting
     or selection control; a 'smiling face' means it is over a
     command button.

FILE SETTINGS:
     These consist of the following-

              SETTING                          = POVRAY Option
     -----------------------------------       ---------------
     . Include File Directory Path(*.INC)         +l
     . Sample File Directory Path(*.POV)          +l
     . Work(.POV) File Name                       -i
     ----------------------------------------------------------
     To choose these settings, click on the adjacent 'SET' buttons
     which will display the settings screens.  Select the
     appropriate paths and file(s) to trace. Return to the main
     panel which should display the values chosen.  Both the
     directory and file path screens have a help button which
     supplies further details.

DISPLAY/IMAGE SETTINGS:
              SETTING                           = POVRAY Option
     -----------------------------------      ------------------
     . Display Card                            eg. '4' for Tseng
     . Output palette                          eg. 'H' for Hicolor
     . Output file type                        eg. +ft for Targa
     . Trace Size                              eg. +w80 +h60
     -------------------------------------------------------------
     To choose these settings, click on the adjacent 'SET' button
     which will display the settings screen and select the
     appropriate values from the list boxes. To select a user
     defined trace size, click on the 'User Defined' check box and
     type in appropriate values.  Return to the main panel which
     should display the values chosen.

TRACING OPTIONS:
              SETTING                            = POVRAY Option
     -----------------------------------        ------------------
     . Antialias                                eg. +a1.0
     . Jitter                                   eg. +j1.0
     . Rays per Pixel                           eg. +r4
     . Buffer Size                              eg. +b30
     . Bounding Boxes                           eg. +mb25
     . Quality                                  eg. +q5
     . Clock value                              eg. +k2.0
     . Part Trace - start/end rows              eg. +sr20 +er50
     -------------------------------------------------------------
     To choose these settings, click on the adjacent set button
     which will display the setting screen, and select, or type
     in, the appropriate values in the frames.
     Default values are already set up on the tracing screen -
     these are indicated by asterisks. No further action is
     required if default values only are used.  To set up a
     different value, click on the appropriate option button to
     activate the text box, then type in the value.  To set the
     quality click on the scroll bar arrows.  To set part
     trace, type in appropriate values - BE SURE TO ENTER VALID
     VALUES - no error checking is done on values entered.  Return
     to the main panel which should display the values chosen.

TOGGLES:
              SETTING                            = POVRAY Option
     -----------------------------------        ------------------
     . Display while tracing                      eg. +d/-d
     . Continue trace                             eg. +c/-c
     . Halt on keypress                           eg. +x/-x
     . Pause before exit                          eg. +p/-p
     . POVRAY1.0 compatible                       eg. +mv1.0
     . Verbose on                                 eg. +v/-v
     . Error on                                   none
     -------------------------------------------------------------
     To toggle these settings on/off, simply click on them.
     The 'ERROR ON' setting is for use when a trace fails and you
     wish to read the error message returned from POVRAY2.0.  With
     this setting selected, the message remains on the screen
     until you press a key, which returns you to the panel.

COMMAND BUTTONS:
     There are a number of command buttons on the right side of
     the panel.  These are:
     . QWKTRACE - click to activate - provides a quick test trace
       of the .pov file chosen(confirms positioning of objects
       etc.).
       Values used include autodetection of display card and image
       size of w80xh60.  Ignores the panel settings.
     . RAYTRACE - click to activate - provides a trace using the
       current panel settings.
     . Help - provides help screen.
     . EXIT - shuts down the panel and returns to DOS.
     . Write .CFG - writes the file "PAN2.CFG" to disk which
       enables the retention of control panel settings between
       tracing sessions.
     . Load .CFG - loads the previously saved file settings in
       "PAN2.CFG" back into the panel.
     . About... - information about the version, author etc.

USING THE CONTROLS:
     The controls will respond to either keypresses or mouse
     clicks.  Move the mouse cursor or use the TAB key to move
     from one control to another(i.e. to select it).  Then to-
     . Operate Command Button     - Press ENTER or LEFT CLICK.
     . Choose a Checkbox Option   - Press SPACE or LEFT CLICK.
                                  - Option toggles ON/OFF.
     . Enter Text                 - Type entry.
     . Choose from File/Card List - Use ARROW keys or LEFT CLICK.
     . Choose from List Option    - Use ARROW keys or LEFT CLICK.
     . Choose Image Quality       - Use ARROW keys or LEFT DRAG.

*********************************************************************
YOUR FIRST PANEL SESSION:
     1. Install the panel as noted above, then delete or rename
        any old files with the name "povray.def" or "povpanel.cfg"
        (even those written by Version 1.2 of this programme -
        their format has been changed). Start the PVPAN2
        programme.

     2. Select the green 'SET' button alongside the Library Paths
        section and ENTER or LEFT CLICK.  You will see a new
        screen from which you may select the appropriate library
        paths(click on the 'Help' button for more information).
        Once you have chosen the desired settings, click on the
        'Write .DEF' button to save these settings.  You should
        only need to save these settings once, as they will be
        reloaded in subsequent sessions.  Return to the main
        control panel.
        WARNING: THESE PATHS MUST BE SET CORRECTLY FOR THE
        PROGRAMME TO FUNCTION PROPERLY!

        (The "Write.DEF" command button writes the file "povray.def"
        to disk which contains only the specified Include file path
        and the Sample file(i.e. the directory with the .pov files)
        path e.g.
              +lc:\povray\include +lc:\povray\samples

        I find it unnecessary to add any other options to this file
        as the default settings can easily be reloaded into the
        panel after each tracing session(or are very easily
        altered on screen).

     3. Select the green 'SET' button in the .POV File
        section and LEFT CLICK.  You will see a new screen from
        which you may select the appropriate file(s) to trace(you
        may trace up to 5 files successively without input).  I
        often like to 'tweak' .pov files until they are just right.
        To do this without leaving the programme, I have added a
        basic text editor which can be used to edit such files.
        There is a size limit of 30kb on editable files.  Please
        click on the 'Help' button for further information.  Once
        you have selected(and/or edited) your file(s), return to the
        main control panel.  You will note that the first(or only)
        file selected for tracing appears in the Work(.POV) File box.

     4. Select and set the other controls as required(if you
        have any problems click on the 'Help' button for further
        information). 

     5. To retain these settings between tracing sessions select
        the green "Write.CFG" Command button and write the .cfg
        file(i.e. POVPANEL.CFG) to disk.

     6. Select the "RAYTRACE" Command button to start the trace(s)
        or use "QWKTRACE" for a fast, low detail preview.

     7. The "EXIT" Command button may be selected at any time to
        return to DOS.

     8. After each trace is completed, the 'Message:' box will
        display the number of files traced so far.  After all
        traces are complete, you will be returned to the main
        control panel.

*************************************************************************
REPORTED PROBLEMS:
Two problems have occasionally been reported by users of the programme.
One is identified by the error message "Path not found in module FILEPATH
at address XXXX:XXXX".  This occurs when the programme cannot find the
directories for the .POV and/or .INC files.  Please check the path
details in the 'POVRAY.DEF' file and check that the correct directories
are listed there.
The other is identified by the error message "Input past end of file in
module POVPAN2".  This occurs when there is excess information in the
'POVRAY.DEF' file.  Check to ensure this file ONLY contains the two
directory paths set up by the panel
    eg. +lc:\povray\include
        +lc:\povray\samples
NO OTHER information should be found in this file.  If you are using
the 'POVRAY.DEF' file originally written for POVRAY you will find extra
information such as width/height settings.  Please delete this old
file and write a new one from inside PVPAN2.                                                                 
*************************************************************************

COMMENTS/SUGGESTIONS:
=====================
     If you have any comments or suggestions to make about
     POVPANEL please contact me via Compuserve(PACIFIC).
     My ID Number is:
                 100036,504
     If you continue to use the programme after a 2 week test
     period please register it.  See the file 'README.1ST' for
     registration details.

DISCLAIMER
==========
     The author is not responsible for any damage or losses of any
     kind caused by the use or misuse of the programme.  The
     author is under no obligation to provide service, corrections
     or advice on upgrades to the programme to any user who is not
     registered.

=================================================================
