                   Persistence of Vision(tm) Ray Tracer

                         POV-Ray(tm) Version 3.1g

                      Acorn RISC OS specific ReadMe

I. Introduction
===============      

This is a port of POV-Ray V3.1g to the Acorn RISC OS platform. Please read
this document carefully, as it contains information about the differences
to the original unix version of POV-Ray.

This PovRay version relies on the unix command-line sources, so doesn't have
any fancy option like mosaic preview. You *DO* have histograms though, but my
first (very rough) tests with them just output random pixels. I still don't
know if I did anything wrong. My guess is my machine is just too slow to get
anything interesting with this feature.

II. Filenames
=============

To adress the issue of filenames under RiscOS, the unix/dos extension and
actual filename are reversed. For instance, if you want to render
"galaxy.pov" in directory "adfs::4.$.Povray.Scenes", you may call "povray
+IADFS::4.$.Povray.Scenes.pov.galaxy +OADFS::4.$.Povray.Pics.tga.galaxy".
This is a well known trick under RiscOS. BUT, inside a scene file, you just
have to ask for say "colors.inc", the name tweaking is automatically handled
for you. If you used previous ports of PovRay for RiscOS, you are already
used to this.

Now even better, I first send the input filename to GStrans, so that you can
invoke the raytracer with something like "povray +I<Input> +O<Output>" where
Input and Output are OS variables previously defined with the *command Set.
On my personal setup, I call povray with +I<scenes$dir>.pov.<Input>
+O<pics$dir>.tga.<Input> (<scenes$Dir> and <pics$dir> are OS-variables
pointing to the actual locations of scenes or rendered pictures). Anyway, the
GSTrans call is just a bonus and you don't have to use it if you don't wish
to.

III. Environment Variables
==========================

The ported version of POV-Ray uses the same environment variables as the
unix version (POVINI). See the documentation or the file !ClickMe for help.

IV. Installation
================

Not much to say about it. Just unpack the archive and edit the povini file in
the ini directory to fit your system. That's it. You'll have to run on
!ClickMe once every time you want to use povray (it defines some environment
variables).

Two executables are provided: 'povray' and 'povrayyl'. The only difference is
that 'povrayyl' is linked with Claus Vohminkel's YLib Math library (v 0.10),
to speed up renderings a little. 'povray' works on any machine with the
FPEmulator. 'povrayyl' works on Floating Point Accelerator-enabled machines
only (FPA10 or ARM7500FE). The YLib gain is quite low however, around 10%
(mainly because povray is not exclusively made up of FP instructions).

You'll have to make sure that the executables (named povray and povrayyl) are
copied to a location pointed to by your Run$Path. If you've got the new boot
structure, !Boot.Library is just fine.

V. Memory
==========

You should have at least about 1300K for POV-Ray to run. 4-8MB are
recommended.

VI. Features
============

Throwback generation if you've previously run the DDEUtils module (there's no
switch on command-line to activate or disactivate this - only the presence of
the module is tested). The freeware implementation by Cy Booker is included
in directory 'support'.

VII. Known bugs
===============

- Not sure what triggers it, but there's a very annoying bug that occurs in a
totally unpredictable way, ie it is not easily repeatable. The symptom is a
"Internal error, no stack for trap handler". This bug was already present in
some previous ports when run on OS 3.1. It might be a fault in the Shared C
Lib. As far as I know, this bugs occurs only with the normal executable
(povray) with FPE 4.03. If you've got an FPA, only use povrayyl.

VIII. Future Plans
==================

 - Try to fix the bugs or find workarounds.

 - Update existing graphical front-ends to match the latest evolution of the
software (up to you !)

Send all comments and bug reports(!) to:

email:      speedsterh@yahoo.com (permanent email)
            or speedstr@ms41.hinet.net (home email read daily)

Jrme Mathevet