ARM Club 3/TheARMClub_PDCD3.iso/hensa/desktop/povfront_1/!POVray3/!Help

Text File | 1997-06-08 | 11KB | 213 lines

Persistence of Vision V3 Front-end Program
==========================================

Introduction
------------

This application provides a convenient desktop based front end to the
Persistence of Vision Ray Tracer. It allows you to control virtually all of
the options available under POV from icons and menus, and makes POV a lot
easier to use under RISC OS. In the documentation below, POV or 'the
executable' refers to the Persistence of Vision Public Domain Ray Tracer
Program. The Persistence of Vision ray tracer is copyright by the
POV team, and you should read the documentation accompanying it for
more information. '!POVray3' refers to this application. I have not been
able to test !POVray3 under RISC OS 2, but as far as I know, it should work
correctly under both RISC OS 2 and RISC OS 3. Note, however, that under
RISC OS 2, the enhanced 'features' such as 3D windows and solid icon
drags (see below) will not be available. I'm afraid I don't have the money
to buy a Risc PC so I have no idea whether it will work on one. The
templates are set up so as to remain properly aligned when used with a
proportional font, so it theoretically should work on Risc PC...

What's not included
-------------------

As well as this program, you'll need a copy of the POV program itself. This
is normally run from the command line - the front end program simply passes
the parameters which you select to it. A copy of the POV program should be
available from many PD sites - you will need version 3.x (currently V3.0 at
time of writing). If you have Internet/JANET access, then it is available
by ftp from micros.hensa.ac.uk, in the directory (at the time of writing)
micros/arch/a/a235. This contains a number of files, including the
instruction for the ray tracer itself (as opposed to this, which is the
instructions for the front end!), and the ray tracer executable.

Alternatively, if you have a C compiler, you can get the source code by ftp
from alfred.ccs.carleton.ca, and compile it
yourself. You will also need a copy of the include files, again, these
should be available from the places mentioned above.

Setting up
----------

As mentioned above, you'll need a copy of the executable, if you haven't
already got one. This is the ray tracer itself, and will take the form
of an 'Absolute' file (one with a dark blue icon with an Archimedes 'A').
Double clicking on it will show a small *Command window in the middle
of the screen with some information about it, probably followed by
an error message.

Assuming you've got a copy of the POV executable program, you'll need to
install it. Open the !POVray3 directory by double clicking on it with
[SHIFT] held down, and copy the executable into it by dragging it using the
Select button. !POVray3 expects the executable to have a filename "POVray",
so if this is not the case then rename it. If you have a floating point
unit, use an executable compiled using ylib.

Running !POVray3
---------------

Double click the icon as normal to run. !POVray3 will then install its icon
onto the icon bar.

Open the main window by clicking on the icon, or, alternatively, by dragging
a POV scene description file (filetype &376 or &FFF (text)) onto the icon.
You can also load a type &376 file by double clicking it.

Most of the icons in the window are fairly self explanatory. The width and
height are specified by clicking on the appropriate writeable icon. Clicking
on the 'Partial' icon will select a partial trace. Specify the start and end
positions in the writeable icons.

If you have previously aborted a trace, clicking on the 'Continue' icon will
cause the ray tracer to read in the aborted file and continue it. This
option is only available if you are NOT using the 'Use save box' option.
This will be explained later...

The V1.00 icon, if selected, will cause the ray tracer to use input
compatible with POV version 1.00, to enable you to trace scene files
produced for the earlier version of POV.

!POVray3 has two modes of operation. If the 'Use save box' icon is selected,
then when the trace has been completed, the image can be saved in the usual
RISC OS way using the save option from the main menu (accessed by clicking
Menu in the main window) and dragging the save icon. This method requires
there to be enough space in the scrap directory to hold the final image.
The save icon displayed (and hence the filetype of the final output) depends
upon the output format selected - Targa and DKB files have their own
filetypes. If you have seleced 'Raw RGB files', then the save box will
represent a directory - dragging this creates a directory containing the
separate red green and blue files.

The other mode applies if the 'Use save box' icon is not selected. In this
case, the image output is saved into the directory specified in the 'Path'
sub-menu, under the same leaf name as the input file. If, for example, you
set 'Path' to 'ADFS::0.$', then trace a file called 'Scene1', the output
will go to a file 'ADFS::0.$.Scene1'. You can use system
variables here (as an example, the initial default uses the variable
<POVpicture$Dir>), but make sure they have been defined before you use
them (invalid pathnames should (hopefully) be detected...). As before,
filetype is set according to the format selection, with 'Raw RGB files'
creating a directory containing the raw files. As you may appreciate from
this, !POVray3 can only know the precise output filename before the trace if
'Use save box' mode is off (using a save box, you don't determine the save
name until the trace is finished). This is the reason you can't use
'Continue' with a save box - the ray tracer doesn't know where to find the
output file to read it in.

The format of the output is specified by the top right group of radio icons.
The group of icons below this select the quality of the output.
Anti-aliasing and jittering are selected by the icons below this.

The rays per pixel icon specifies the number of rays per pixel when
anti-aliasing, and the frame clock icon specifies the value of the frame
clock variable supplied to the ray tracer.

From the main menu, you can select the input library to search for the
#include files, the path (for output if 'Use save box' mode is off), the
output buffer, and bounding slabs. The Path, Buffer, and Use slabs menu items
are ticked if selected. If unticked, then that option is not used in tracing
(eg. bounding slabs are only used if the option is ticked in the menu).

Normally, ray tracing takes over all of the processor time. If however you
select 'Task window' from the main menu, the ray tracer will be run in a
Task Window, and hence multi-task. If this is selected, however, it is not
possible to use the save box option, and verbose output is not provided
during the trace. Also, the filetype of the output file will not be set
automatically.

The start and cancel icons are probably obvious.....

Clicking menu on the icon bar icon will open another menu. From this, you
can quit the application, or save the defaults. This will save the status of
the width, height, save box, rays per pixel, format, quality, anti-aliasing,
jittering, library, output path, and bounding slabs into a default file.
These values are restored whenever the application is started.

If something goes wrong during the trace, try increasing the size of the
'Next' slot in the task manager before clicking on 'Start'.

!POVray3 has two sets of window templates; the normal ones, and RISC OS 3
!NewLook style windows. These are automatically selected according to
whether bit 1 of CMOS byte &8C is set - if you have RISC OS 3.1 or better
and have selected 3D windows in !NewLook, then !POVray3 will use 3D
windows, otherwise it will use normal 2D windows. RISC OS 3 support also
includes the use of solid icon drags - if you have the DragASprite bit
in CMOS RAM set, then !POVray3 will use DragASprite solid icon drags in the
save boxes.

For more information on POV, refer to the POV documentation, which will
explain the various options and parameters described above in greater
detail.

Addendum to !POVray3 documentation
----------------------------------

This document is modified from that which was supplied with an earlier
version of this program, known as !POVray2. This previous version was a front
end for POV V2.2. The current version, !POVray3 is basically an update of the
earlier version. It has some important modifications, however, to support the
different file naming convention which are used in the version of POV 3
available from HENSA. The POV 3 executable appears to expect to find
directories named after the three letter DOS / Unix style extension; for
example, Targa files go into a directory called TGA. This version of !POVray3
supports this transparently via the 'Unix names' menu option, which should
always be switched on. Support for POV 3's radiosity feature is also provided
by means of an extra radio button to select it.

*** Note: This version was produced to address the problem of interfacing
*** the version of POV 3.0 on HENSA, using the Unix names menu option.
*** It hasn't been tested with any other version, and hence may not
*** (will probably not!) work with them. If another port of POV appears
*** which handles file names differently, then a new version of !POVray3
*** may be released to handle it.

This version of !POVray3 is kind of a stop-gap - I produced it when I found
that !POVray2 wouldn't work with POV 3 due to the different file naming
convention. I eventually intend to completely re-write this program to give
support for the !POVray3 animation options, and to improve the multi-tasking
support. That, however, is a little way into the future...

Further Information
-------------------

!POVray3 is simply a front end for the Persistence of Vision Ray Tracer, and
is in no way a part of the POV distribution; the POV team are not
responsible in any way for it. The program is freeware - you may distribute
copies of it by any means, provided that:

1.) It is distributed as is, with no modifications to any part of it. This
    document must be included.
2.) You may not make any charge for it except to cover the cost of disc
    copying and postage and packing etc.

The POV executable file is part of a seperate distribution, and has its own
rules which cover distribution - see the relevant parts of the POV
documentation. It should not be distributed with this program unless those
rules are complied with.

No claim is made as to the suitability of this program, and I am not in
any way responsible for any loss occurring through its use.


Well, now that's that out of the way, I hope you find this program useful -
I certainly find it easier than typing out voluminous command lines each
time. I've tried to debug it thoroughly, but I'll bet there are hundreds of
'undocumented features' floating around. Ah well.... You may send me any
reports of bugs, or comments and suggestions by e-mail as below (this
address is probably only applicable until September 1997).

Brian Ruth, March 1997

E-mail: [e-mail]