Mega Top 1/os2_top1.zip/os2_top1/APPS/RAYTRACE/PMPOVF/POVFRAME.DOC

Text File | 1993-10-22 | 23KB | 458 lines

                      POVFrame 2.0 For OS/2 2.x

                    Copyright (c) 1993  Bill Pulver

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

Thank you for trying POVFrame. This program enables you to use the FreeWare
raytracing program POV-Ray from the OS/2 2.x DeskTop. Most of the functions
needed to effectivly use POV-Ray in the WPS environment are available from
the POVFrames user interface.

       This program is being distributed as shareware!!

A registration fee of $20 (US) is required if the program is used beyond a
30 day trial period. THANK YOU! See ORDER.DOC for further information.

NOTE: This program is NOT a "product" of the POV-Ray team. I use OS/2 for
      my main machine & thought others would find a POV-Ray shell usefull.
      Please dont bother others on the team with questions about this
      program! <g> See ORDER.DOC for more info.

Also: The OS/2 compile of POV-Ray seems to be less "tolerant" of math errors
      than the "official" ICB compile is. It will sometimes crash on large,
      complex image files. If this happens try using the "official" Code
      Builder compile to render your image. I'm using CSet/2 C++ @ CSD level
      1 & it seems to have some math accuracy problems. Many of the images
      that use higher order surfaces will crash with an underflow or overflow
      error. These can be masked but then some images may appear to trace
      fine & end up with "fly specs" in the image when completed. For now
      I think it'd be better to have it abort than spend hours or days only
      to find a "fly spec'd" image as the result. If anybody has some tricks
      or advice on CSet/2 C++ please let me know. For now, if it wont trace
      with the OS/2 compile the ICB compile will usually work.





       ------------
       Installation
       ------------

    Installation of the program is fairly simple. The VROBJ.DLL file is
the VX-Rexx function library, it may be placed in a directory in your OS/2
LIBPATH statement (D:\OS2\DLL is good) or it may simply be left in the same
directory as the POVFrame executable file. (POVFRAME.EXE)

    A third party OS/2 support program called STARTD.EXE is required
to start the DOS sessions since a value larger than OS/2's default
must be used for DPMI_MEMORY_LIMIT. STARTD will start a DOS session with
the values in the POV.INI file. They may be changed the same as if they
were being set in the DOS Session notebook setup by editing POV.INI
with a text editor. DO NOT DELETE POV.INI or the DOS version of POV-Ray
will not run. For convienece the original BBS distribution file of STARTD
is included with POVFrame. It is copyrighted but is freely distributable.
   By default POVFrame expects the DOS executable & the OS/2 executable
to be in the same directory as POVFrame. This is the simplest & most reliable
way to use the program but different paths may be entered with POVFrames
"defaults" pulldown as described below. STARTD may also be left in the same
directory or placed in a directory that is pointed to by your OS/2 PATH
statement in your OS/2 CONFIG.SYS file.





USING POVFrame
--------------

   ----------------
   DeskTop Options
   ----------------

    If you are familiar with the options available for running POV-Ray
most of the options on the DeskTop should be old hat for you. For further
information on POV-Ray and the options available please consult the POV-Ray
documentation distributed in POVDOC.ZIP. POVFrame will build a new POV-Ray
DEF file for each POV-Ray image run so multiple images with different
settings may be started. POVFrame uses a DEF file named POVDOS.DEF for the
DOS compile, POVOS2.DEF for the OS/2 compile and POVANIM.DEF for animation
runs. An OS/2 text mode compile of POV-Ray is included with this program.
It IS NOT shareware but freeware & registration of POVFrame does not relate
to it. It has been slightly modified from the distribution source code in
that all errors and the final image STATS are sent to STDERR in order to
capture them in the VX-Rexx console, the regular POV-Ray run time
info, credits, +v verbose line info etc are sent to STDOUT & will appear
in the OS/2 session window during the image run. Errors and image stats
may be saved to a disk file from the VX-Rexx console using an option in
the upper left "frame" button. The standard POV-Ray Team release DOS compile
distributed as POVIBM.EXE may be used for the DOS version.


The following describes the options, installation & use of POVFrame:

                     ------------------------
                         POVFrame Options
                     ------------------------


Output Buffering:
-----------------
    This group box allows you to select whether you want POV-Ray to
buffer the image as it is rendered. The size of the buffer is entered in
the dialog box. The "Disable Image Buffering" checkbox enables & disables
this option for POV-Ray image runs. Note that using an image buffer can
significantly increase rendering speed by restricting disk writes. The
default is to use buffering with a 512K buffer.

Image Run Parameters:
---------------------
    This group box controls the resolution of the image run and allows
the use of POV-Ray's ability to render only a portion of the complete image.
The "Do A Partial Render" checkbox enables & disables this option. The
"Percentage Partial" checkbox toggles between doing a partial render based
on physical starting/ending lines & columns of the image or based on a
percentage of the image width & height. Valid values for a render based on
the physical resolution of the image are 0 to Image Width & 0 to Image Height.
Valid values for percentage based renders are 0 to 99.9%. The values for all
these options are simply entered into the dialog boxes.

Output File Type:
-----------------
    This group box of Radio Buttons selects the file type to be written.
Just click on the one you want.

Image File Selected:
--------------------
    This dialog box is an informational box to tell you what image file
the program will render. The file may be selected from the "Files" pulldown
menu in the upper left, the "Files" button in the Image File Selected group
box, or by pointing to the entry field with the mouse cursor, clicking mouse
button 1 to move focus to that dialog box & pressing a key on the keyboard.

Other Options:
--------------
    This group box contains checkboxes and radio buttons for the various
commonly used POV-Ray options. See the POV-Ray docs for specific information
on what each one does. A "check" in a checkbox or radiobutton signifies that
option is enabled for the next image run. Note that the "Display" option is
valid ONLY with a DOS compile. (It will work with either the "official" POV-
Ray Teams ICB compile or a Watcom 9.5 compile.)

Use the "Verbose" option for the OS/2 compile supplied with POVFrame.

Image Quality & Anti-Aliasing:
------------------------------
    These dialog boxes set the values for POV-Rays quality and anti-
aliasing features. The quality levels are selected by running thru POV-Rays
valid options using a "spin-button". The values for Anti-Aliasing are
entered via the dialog boxes in this area. The Disable Anti-Aliasing checkbox
will disable AA for the next image run. By default it is disabled since
you will probably only want to use it for a final "high quality" image run.

OS/2 GO! and DOS GO!:
---------------------
    POVFrame will start either a DOS compile of POV-Ray or an OS/2 compile
of POV-Ray. The POV-Ray teams ICB (DOS) compile of POV-Ray 2.0 has the ability
to render an image of any resolution to a WPS desktop window by using the
VGA 320x200x256 mode as the display option. (+d1 POV-Ray option) The "Display
Image While Rendering" radio button option is valid ONLY for the DOS compile
at the moment. The OS/2 compile supplied with POVFrame will display the
verbose "current line being rendered" option to the OS/2 session window during
the image run. Errors and the image trace stats are written to the VX-Rexx
consol handler and may be reviewed and saved from there. (Saved from the upper
left button pulldown menu.) Upon completion rendered image files will have
the same name as the image "source" & the appropriate extension for the type
of file written. For example, using the program defaults for paths & such,
D:\POVRAY\BLOB.POV will render to D:\POVRAY\BLOB.TGA if the TGA file type is
selected. The VX-Rexx console window must be closed "manually" after POVFrame
is terminated. You may also save the contents of the VX-Rexx console to a
file. This makes for a good way to save image stats for the OS/2 compiles
image runs if desired.

Of course you must either have the DOS &/or OS/2 EXE's of POV-Ray in the
same directory as POVFrame, or have the appropriate paths defined for them,
for proper operation.



   --------------
   PullDown Menus
   --------------

Files:
------
    The "Files" pulldown supplies file services. Image files to be rendered
may be selected from here. Image files to be edited may also be selected as
well as deleted.

 The "Select Image File to Render" option is identical in function to the
"Files" pushbutton in the "Image File Selected" groupbox on the desktop
explained earlier.

 The "Edit POV-Ray File" option selects a POV-Ray image source file for editing
and calls OS/2s "built in" editor, EPM.EXE (The Enhanced Editor), to actually
edit the image file. Multiple files may be opened in different windows to
allow cut 'n paste editing of entire image file sets. Due to a limitation
in the file selection dialog there can only be 1 default file mask. In this
case *.POV is used. Other masks may be entered manually in the "Open
Filename:" dialog box at the top to select *.INC or other POV-Ray image file
extensions. If a filename that does not exist is entered EPM will open a file
by that name for editing. New image files may be created that way.

 The "Delete A File" dialog may be used to delete unwanted or outdated
files. By default all files are displayed in the dialog. A second dialog
box will open to -make sure- you want to delete the file selected.


Defaults:
---------

All of the following are stored in the POVFRAME.INI file and, after setup,
are loaded each time the program is started.

    The defaults pulldown allows initial settings for POVFrame to be
set & saved as well as POV-Ray options that are less frequently changed.
Items such as your POV-Ray image "source" files path and POV-Ray library
directories. (Up to 4) All of these options are saved in the POVFRAME.INI
file and will be loaded each time the program is started. All path names
must be fully qualified.

 The "POV-Ray Source Path" option allows entry of the path to your POV-Ray
image "source" files directory. This is the directory where your IMAGE
SOURCE FILES are located, NOT the POV-Ray program it's self. Enter a fully
qualified path name including a trailing backslash.
EXAMPLE: D:\POVRAY\IMAGES\

 The "Library Paths" option opens a submenu that allows entry of up to 4
library directories for POV-Ray. Again, fully qualified paths *must* be
entered.

 The "DOS (& OS/2) EXE Defaults" options allow you to seperate your DOS and
OS/2 EXECUTABLES by specifying a specific path to your DOS/OS2 executable
file and a directory that all your DOS/OS2 rendered images should be placed
in upon completion.
 By default the program expects both the OS/2 and DOS executables to be in
the same directory as POVFRAME.EXE. Also, by default, rendered images are
placed in the same directory as the image "source" file they are rendered
from. These options are provided for "house keeping" if you'd like to use
them to keep things a little more "organized". They also allow the
use of both the OS/2 and DOS compiles to render the same image at the same
time. (If this is attempted with the program defaults both compiles will
attempt to write the image to the SAME file!!!... Leads to some wierd results
sometimes.)

 The "OS/2 EXE Defaults" allows the same options to be set for the OS/2
executable.

 The "OS/2 View Program" option allows the entry of the path too, and name
of, an *external* OS/2 image viewer and/or post processor. A fully qualified
path must be entered.
Some options that are available for this are PMVIEW, PMJPEG and JOEVIEW, all
of which are also shareware programs and may be obtained from many BBS's and
On Line services. I've tried them all & they all work quite well. The program
selected by this option is called from a files dialog under the "External"
pulldown menu. Just about any OS/2 program that can have the image file name
passed to it on the command line may be used here.

 The "DOS View Program" option does the same thing as the OS/2 View Program
option but the files used for this one may be DOS files. Since I use
a TSENG ET4000 based HiColor/TrueColor video card in my machine here I use
TGVIEW.EXE by John Swenson for this option. It allows me to click on the TGA
file I'd like to look at in the files dialog presented under the "External"
pulldown. As with the "View Program" option above, just about any DOS program
may be used for this option. The DOS session started when the program is
invoked under the "External" pulldown is a FULL SCREEN session. This allows
use of HiColor or TrueColor hardware and the DOS progams that support it.
PICLAB and other image processors may also be started from here. The idea
between the "View Program" and "Post Processor Program" options is to allow
as many OS/2 and DOS programs as possible to be called directly from the
POVFrame desktop & have the name of an image file passed directly to them.
Again, fully qualified path names and EXE names should be used for both of
these options.

 The "Animation Player Program" option allows entry of the name of an Animation
player to call for playing animations. Trilobytes PLAY program works quite
well for this purpose in a window with 320x200x256 FLI files. Other formats
may require switching the session to full screen to run if it gets suspended
due to an unsupported graphics mode. The file selection menu will open in
your DOS output directory by default since this is where DTA animations
are built & placed upon completion.

You may also enter the paths to the POV-Ray modeling programs "MORAY" and
"POVCAD" in this pulldown. Both are started in a FULL SCREEN DOS session
when called using the selection under the "External" pulldown. The Windows
version of POVCAD may also be used. OS/2 will automaticly start a Windows
session and load the program. Once again, enter fully qualified path names.
MORAY and POVCAD must be explicitly set up to be called from another
directory. MORAY, for instance, needs to have all of it's own internal path
names explicitly defined with fully qualified path names in it's
configuration file. In it's "default" setup it will be looking for model
files in your POVFrame directory (since thats where it was called from)
instead of it's own. I've tested them & they both seem to run quite well
this way.


 The "External" pulldown menu option located on the main window menu bar
actually calls & executes the programs whose names and paths have been
entered as described above.


SnapShot
---------

 The "SnapShot" option will examine the >>> CURRENT STATE <<< all of the
entry boxes, radio buttons and check boxes on the main POV-Ray options
desktop (with the exception of the Partial Image rendering paramaters)
and save them to a defaults file named POVSNAP.INI. These settings will
then be loaded as the DeskTop defaults for future program startups.
For example, say you'd like a default image buffer of 200K, display during
render with a pause at completion, and a quality setting of +q5. Set these
options up this way by entering the appropriate values & punching the right
buttons, then run the SnapShot option. From then on, when you start the
program, these items will be set up this way. It does, however, slow down
program startup by a few seconds. To return to the programs "built in"
defaults DELETE the file POVSNAP.INI.


Animation:
----------

    The "Generate Animation" option is a VERY BASIC animation loop
generator that uses the POV-Ray 2.0 "clock" option to pass frame information
to the program. It's currently a very simple system. Frame and clock values
may be entered in the entry boxes. The clock increment value for the animation
may be entered manually or the program will calculate even steps for the
clock increment when the AutoCalculate checkbox is "checked'. It does not
check for "logical" values, the user needs to enter numbers that make sense.
For instance if your going to >start< your clock value at 100 and >end< at
-100 for 20 frames, dont enter +10 as the increment value, enter -10.

BE VERY CAREFULL TO ENTER ** ONLY ** NUMBERS WHEN THE AUTOCALCULATE IS "ON".
The program will crash if anything but numeric values or a minus sign ("-" as
-first- charactor on the line) are entered. Limitation of VX-REXX.......

The program will ignore a minus sign entered as the FIRST charactor in the
entry field to allow negative numbers to be entered. REXX's math support is
quite limited, the program will crash if an Alpha charactor is entered since
math for undefined variables (which is how REXX interprets it) is undefined.
Currently ONLY the DOS compile of POV-Ray is used for animation generation.
(POVFrame writes out a DOS batch file with a seperate command line for each
frame to be generated.) The output image files will be numbered sequentialy
based on the frame values and the first 4 charactors of the image file name.
To facilitate simpler use of programs such as Dave Masons "DTA" frames
numbered from 0 to 9 will have 3 leading zeros prepended, frames numbered
from 10 to 99 will have 2 zeros prepended and 100 to 999 will have 1 zero
added.

I.E. Frames are numbered xxxx0000, xxxx0001.. xxxx0035.. xxxx0235.. xxxx2200
etc..

This allows for animations up to 10,000 frames in length. (0 to 9999)

It's not much but it does make for -easy- linear animation generation.
Simply replace the value that you would like to vary in your POV-Ray 2.0
image "source" file with the word "clock" & the values will be passsed to it.
EXAMPLE:
       Used to vary the "z" position of the camera in this case.

                  camera {
                          location  <-5, 8, clock>
                          direction <0, 0, 1.2071>
                          look_at   <0, 0, 0>
                          }


--- If you have any ideas on anything to add here, or the rest of the program
    for that matter, I'd like to hear them!

  The program now also provides a control panel for generating animations
with "Daves Targa Animator" (DTA) by David K. Mason.

*DTA must to be placed in the same directory as POVFrame.*

The "files" button will, by default, open a file selection dialog in the
DOS output directory since the DOS version of POV-Ray is used to generate
animations under POVFrame. Simply select one of the files in the sequence
you want to animate. Say for instance you have generated an animation with
BOX.POV. The POVFrame output files will be numbered like this, assuming
frames 0 to 10:

BOX0000.TGA
BOX0001.TGA
BOX0002.TGA
.
.
BOX0009.TGA
BOX0010.TGA.

Simply point to any one of these and click on it. POVFrame will strip the
last 4 charactors from the end of the file name and replace them with a
wildcard '*' to be passed to DTA for compiling the animation. POVFrame
expects the frames to be numbered in it's format. I.E. the last 4 charactors
of the name are the number sequence. Other names may be -manually- entered in
the files input box to generate animations from images compiled from other
sources. In this case an output file name should also be entered manually.
 If no name is entered for the Output file DTA will use it's own default
name. (ANIM.FLI in the case of .FLI animations) See DTA's docs for more
detailed information on the program and what it's options are/do.
You may select the DTA options you'd like to use by clicking on them or
using the SpinButtons. For most of the SpinButtons a value of ZERO (0)
means that option is disabled since a zero value for these items is
meaningless. See the "Hints" at the bottom of the POVFrame Window for the
specifics. (This saves some processing overhead to not have CheckBoxes etc.
for those items.) To add gamma correction to your animation click on the
"Gamma Correction" checkbox and enter the value to be used in the entry
box next to it.

In most cases the "hints" at the bottom of the MAIN POVFrame WINDOW supply
basic information about each option when the mouse cursor is placed over it.


Help:
-----

    The program now includes a basic "port" of the POVRAY DOC files
to OS/2's INF format. This file is viewed using OS/2's "built in" VIEW
program. To use the DOCs from inside POVFrame the INF file MUST be in the
same directory as POVFrame. Your machine must also have OS/2's VIEW program
in it's PATH someplace. (This is the installed default for OS/2.)
The POVDOC.INF file included with POVFrame is the same doc file for POV-Ray
that is distributed in POVDOC.ZIP.

    The "Hints ON/OFF" item will turn the "hints" at the bottom of
the POVFrame main window on & off. The flickering bothers some people so
they can now be disabled. If a SNAPSHOT (see above) is done while they
are OFF this will become the programs default startup mode.


    "About" is just that!





This gives an intro to the program. The best way to get the feel of it is
to, of course, USE it. Expirement & have fun!!!


Thanks for your time:
Bill Pulver

Please send bug reports & suggestions to one of the following E-MAIL addresses.
They are listed in desending order of frequency of usage, just not enough
hours in the day......

InterNet folks, PLEASE include your "return address" in the body of your
message. Deciphering the routing headers can sometimes be a difficult task!
<G>

CIS     : 70405,1152                   <------ Most often used!
InterNet: [e-mail]
AOL     : BPulver
Delphi  : BILLP
Genie   : B.Pulver
Prodigy : NCCJ93A