OS/2 Professional/OS2PRO194.ISO/os2/wps/graphic/povframe/povframe.doc

Text File | 1994-02-11 | 28KB | 549 lines

                      POVFrame 2.2 For OS/2 2.x

                Copyright (c) 1993, 1994  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 effectively 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 useful.
      Please don't 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++ 2.0 @ CSD
      level 1 & it seems to have some math accuracy problems. Many of the
      images that use higher order surfaces will end up with "specs" in the
      image or will crash with an underflow or overflow error.

      *** PLEASE *** Run a small test image & check it before allowing the
      machine to run for an extended period of time generating an image. If
      "specs" show up in the image, or if it wont trace with the OS/2
      compile, the DOS ICB compile will usually work. Waiting on CSet/2 C++
      2.1 here now......



       ------------
       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 using
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 convenience 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 also now includes a full
INF format "port" of the POV-Ray doc file in POVDOC.INF. This file may be
called and reviewed from the POVFrame "Help" pulldown.
  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 handler, 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 under POVFrame.


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 256K 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 renders are based on 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.

File names may also be entered manually by simply typing them in the Files
dialog box that opens.

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, a Watcom C 9.5 compile or a Symantec C/C++ 6.1 compile.
It will *not* work with a DJGCC compile at present.)

Since the OS/2 compile of POV-Ray supplied with POVFrame does not support any
render to screen options, you should use the "Verbose" option to monitor your
images progress with it.

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.2 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. The OS/2 compile writes errors and the image trace stats to the
VX-Rexx console 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" push-button 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 in the POVFrame
dialog box EPM will open a file by that name for editing. New image files
may be created in this 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. Your primary library path should also be set to your image source
files directory (same as above) if you use files that have .INC files, such
as POV-Rays "COLORS.INC", that are stored in that directory.

 The "DOS (& OS/2) EXE Defaults" options allow you to separate 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 weird 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 program used for this one may be DOS applications. 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 programs 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 in order 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 automatically 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 parameters)
and save them to a defaults file named POVSNAP.INI. These settings will
then be loaded as the DeskTop defaults for future program start-ups.
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 start-up by a few seconds. To return to the programs "built in"
defaults DELETE the file POVSNAP.INI. The "hints" at the bottom of the screen
may also be set to default to "off" at program start-up by turning them off
and executing "SnapShot".


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

        The "Generate Animation" option is a VERY BASIC animation "loop"
generator that uses the POV-Ray 2.2 "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, don't enter +10 as the increment value, enter -10. Also,
your StartFrame value should always be smaller than your EndFrame value and
your Frame Increment should always be >= 1. If values other than these are
entered POVFrame will present a warning dialog before it attempts to run the
animation. You may return to the setup window to change the values by
selecting the "OK" button. You may also continue *on* with the values entered
by selecting the "Ignore" button. If values are illogical (Startframe 30,
endframe 10, Frame increment +10 for instance) the values used for the clock
may be in error or you may end up with an empty POVANIM.BAT file.
Backwards counts usually will work with proper values though (-10 frame
increment in EX. above for instance), thats why the ignore option was
included. I can't think of a reason to do it this way off hand, but why
restrict things?...... DTA will, however, compile frames in positive order, 0,
1, 2, 3, etc.

YOU SHOULD ENTER **ONLY** NUMBERS WHEN THE AUTOCALCULATE OPTION IS "ON".

The program will no longer crash if anything but numeric values or a minus
sign ("-" as the -first- character on the line) are entered but will instead
BEEP at you..... You may use backspace to erase the invalid characters and
enter the numbers you want. The Clock Increment and Frame Increment Values
will be set to 1 when an *empty field* exists so the numbers displayed may
be ambiguous.

The program will allow a minus sign to be entered as the FIRST character
in the entry field to allow negative numbers to be entered.

Currently ONLY the DOS compile of POV-Ray is used for animation generation.
(POVFrame writes out a DOS batch file, with a separate command line for each
frame to be generated, and then runs the batch file.) The output image files
will be numbered sequentially based on the frame values and the first 4
characters 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 prepended.

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.2
image "source" file with the word "clock" & the values will be passed 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>
                          }

Remember, you can use POV-Ray 2.2's math capability to alter the relative
linear motion between objects. If, for instance, you have one object that uses
< 0, 10, clock > to define it's 3D position, you can use < 0, 10, clock*0.5 >
to define the position of another object that will move 1/2 the distance
of the first in a given amount of time.  I.E. it moves 1/2 as fast when the
animation is played. Careful use of this technique can make for some quite
complex animations. It's still limited to linear values in the current POV-Ray,
but it's useful.

--- 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 is a very powerful
shareware program that will generate animation files in the 256 color FLI and
FLC format as well as 15bit FLH and 24bit FLT animations. It will also
do image color reduction, dithering & conversion to several other formats
from the TGA files POV-Ray generates and lots more. It's available on many
BBS's, CompuServe in the Graphics Developers Forum (GO GRAPHDEV), AOL and
various other sites around the world. Many of the BBS's listed in the
POVINF.DOC file will probably also have DTA. **** DTA is a shareware program,
separate from POVFrame, and must be registered with Dave Mason. (See the DTA
docs for details.) Note that the latest DTA (2.1Beta) writes a file slightly
different from the old FLX format for HighColor (15bit) files and now uses
the FLH file extension. Also, 24bit BMP and 24bit FLT files require DTA
2.1Beta or newer.

*DTA must to be placed in the same directory as POVFrame.* The control panel
is designed to operate with DTA 2.0.3 or newer. This version comes as a
single executable. Older versions were distributed as 2 executables, a real
mode one and a protected mode one. These versions may not work correctly.
(Version 2.0.7 is the one tests of POVFrame were done with.) Again, only the
BETA of DTA 2.1 supports the 24bit BMP image file and 24bit FLT animation
files as of this writing.

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 characters 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 characters
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 set to OFF this will become the programs default start-up mode.


        "About" is just that! This message is placed on screen at program
start up. It is NOT displayed when the program is started in the registered
version of POVFrame...... Call it my concession to nag-ware. <g>



   --------------
    Hints & Tips
   --------------

Some people have found that having the PATH to the DOS executable of POV-Ray
defined in *both* POVFrame *and* their DOS PATH statement will cause the
DOS Session for POV-Ray to not be started. It is currently unknown why this
should happen. It works all 3 ways for me here, DOS PATH only, POVFrame
defaults only, or both at once. For everyone that has had this problem defining
the DOS EXE directory ONLY in the PATH statement of their AUTOEXEC.BAT file
has cured the problem. I.E. Include the directory that contains your DOS
compile of POV-Ray in your DOS PATH statement, DO NOT enter it in POVFrames
"defaults" pulldown.
(Entering blank space in any of the "defaults" entry fields will clear the
 entry in the INI file.)

Others have found that deleting the POVFRAME.INI file and reentering the
values has cured messages such as "could not start session". These type
things ONLY seem to happen during INITIAL setup, once the "working
combination" is found the program runs w/o problems from then on.

I have been unable to duplicate either one of these conditions at this time.

Make sure POV.INI is in a place STARTD can find it. It seems to work best
when they are both in the same directory as POVFrame although other places
may be used as explained earlier.



This gives an intro to the program. The best way to get the feel of it is
to, of course, USE it. Experiment & 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 descending 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> Also please note that InterNET responses from CompuServe are sometimes
bounced with "unknown host" messages. I have full InterNET access thru Delphi
but the UI is abysmal compared to Golden Commpass on CIS. If I get a bounced
message from the CIS mailer I will attempt a response thru Delphi.

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


rev. 2/11/94