TOS Silver 2000/TOS Silver 2000.iso/Anwendun/Pov/POV302/README.TXT

Text File | 1997-07-18 | 21.0 KB | 478 lines

/--------------------------------------------------------------------\
) Unofficial POVRay v3.02 for Atari M680x0 platform (x-port v2.00)   (
\--------------------------------------------------------------------/

This is the final version of my POVRay v3.02 MS-DOS port to the Atari
platform. This is the second 'complete' port for the Atari/TOS based
compatibles. A complete list of changes from v3.00 (the last TOS port
to be released in this series) to v3.02 can be found in REVISION.DOC.

A brief word of warning:

Although POVRay v3.02 is based partially on the algorithms from Dieter
Bayer's FTPOV v2.2 and is therefore much quicker than the original
POVRay v2.2, it does contain a lot of new features which are every bit
as intensive as they are impressive. It is quite easy to produce a
scene that will take forever to render even on the fastest of fast
platforms. This means a number of the example images will render
relatively slowly, and so give the false impression POVRay 3 is much
slower than some of it's predecessors. For this reason, it may be
worth experimenting with a few of the older scenes & capabilities
before diving into things like atmospheric effects, focal blur,
attenuated glass, halos and some of the other new processor-killing
functions which are now available.

It is STRONGLY ADVISED you equip yourself with AT LEAST a 68030
processor and probably a 68881 or 68882 floating-point coprocessor
as well. There is support for vanilla 68000 and 68030, but be prepared
for IMMENSELY long render times if you do have to take this route. If
you are lucky enough to own a 68040 processor with integral FPU, then
you are not going to have too much of a problem at all. If you are
absolutely DROWNING in luck and happen to have a 68060-based 'Hades060'
or something like that, then you have far too much disposable income,
and considering the nature of POV, probably far too much free time as
well. :)

]--------------------------------------------------------------------[

Configuration:

Setting up POVRay can be a little difficult if you are just starting
to learn your way around the system.

You *can* use it directly from the Desktop, although that is a *very*
tiresome way to go about things. You can also use a command line shell
like MUPFEL which will make things a tiny bit easier but it can still
be fiddly if you are not used to command line systems.

One of the best methods is to use a special POV shell like POVSHELL or
the soon-to-be-released SHELLY by Henrik Lynngaard. This will automate
most of the options and parameters passed to the POVRAY.TTP file,
making life a lot easier.

I have my own system which relies on the Hisoft text editor which
comes with Devpac and Lattice 'C' packages. That lets you integrate
POVRay directly into the text editor, and you can render the scene in
the topmost edit window by selecting POVRay from the dropdown tools
menu. It's a great way to launch POV! Details on how to set this up
are given in POVRUN.TXT, but you will have to get your hands on a copy
of the Hisoft editor first!

1) Renaming & locating the program

Pick a version of POVRay 3 from the list of binaries available - make
sure it is one that suits your processor or you will achieve reduced
performance and probably even nasty crashes!

When you have chosen a binary, rename it to 'POVRAY.TTP' and transfer
it to the location where you want to use it. This will be your system
BIN folder if you are using a command line to launch POV, or you could
just transfer it to the root location in the supplied POVRAY3 folder.

'POVRAY' is the universally agreed naming system for POV binaries on
all computer systems. It is the name used in any examples and batch
files you might encounter.

2) Configuring POVRAY.INI

Locate the file 'POVRAY.INI' (which should be in the POVRAY3 folder)
and load it into your favourite text editor. Edit the lines containing
the keywords 'Display' and 'Verbose', according to the Atari-specific
configuration docs found elsewhere in this archive. The files are
called CFG_FALC.TXT, CFG_TT.TXT & CFG_ST.TXT. These changes simply
ensure that POVRay will not attempt to try anything not possible on
that particular machine, which includes preview modes on non-Falcon
systems.

3) Environment variables

There are *several* ways to configure POVRay, but it is clearly very
helpful to set up the POVINI environment variable no matter what kind
of setup you are trying to use. It can take away some of the problems
you might encounter with the paths and locations of relevant files.

If you don't specify the location of the default POVRAY.INI file using
the POVINI variable, you will have to specify it's location on the
command line *every* time you try to render a scene! That would force
you to keep the POVRAY.INI file beside the TTP file for simplicity and
would probably require you to copy the scene file to the same location
so everything can be found easily by the TTP! Yeuck!

To avoid all this exrta fiddling around, add the following line to the
environment variable part your most frequently used config files. There
are several different syntaxes for this depending on your system. A few
of the more common formats are shown here:

# MiNT's 'MINT.CNF' configuration file

setenv POVINI f:\povray3\povray.ini

# MultiTOS's 'GEM.CNF' configuration file

setenv POVINI=f:\povray3\povray.ini

# Gemini's 'PROFILE' configuration file

setenv POVINI "f:\povray3\povray.ini"

# N.AES's 'N_AES.CNF' configuration file

export POVINI=f:\povray3\povray.ini

# GemRAM's 'GEM.CNF' configuration file    (under normal TOS)

setenv POVINI=f:\povray3\povray.ini

# ENV.CPX's environment variable syntax (under normal TOS)

POVINI=f:\povray3\povray.ini

Of course, you should check the syntax used in your current config
files before adding any of these to make sure they are correct, and
you should also edit the path to suit your own POVRay 3 installation.

If you *don't* use any of the systems quoted above, and don't have any
configuration files to which you can add environment variables, then
you should consider looking for an appropriate way to achieve this
with an auto folder program or a CPX. Programs like SETENV, GEMRAM and
ENV.CPX for the control panel will all do the job nicely under normal
TOS. Other systems like MiNT, Geneva and Magic should all have config
files you need without requiring extra software.

With the POVINI variable correctly configured, the POVRAY.TTP binary
will be able to locate the default POVRAY.INI file every time a POV
scene is rendered, regardless of where the TTP file happens to be at
that time. You could even place POVRAY.TTP in your BIN directory if you
intend to launch it from a command line!

]--------------------------------------------------------------------[

Operation:

The simplest way to launch POV is to add any special options to the
POVRAY.INI file (or some other secondary INI file) and use:

 povray.ttp -isource.pov [file.ini]

...either from the desktop, a command line shell or from a POV shell.

You don't *actually* need to specify for the default POVRAY.INI file
because POV will find it automatically so long as it is specified in
the POVINI environment variable. If the POVINI variable is missing or
is incorrectly set up, the POVRAY.INI file *must* be specified for it
to be noticed by POVRay. If your scene renders with the wrong options
then it is likely your POVRAY.INI file is not being located properly!

It is worth trying a few quick tests with simple scenes to make sure
the POVRAY.INI file is being read properly. Sometimes it can be hard
to tell without making some obvious changes and watching the result.
Turning the 'verbose' option on and off is a good way to see if the
INI file is being used. It's also nice and easy to do!

~

Alernatively, you can specify the in/out filenames in the INI file
itself like this:

 Input_File_Name=f:\povray3\myscene.pov
 Output_File_Name=f:\povray3\myscene.tga

And just use:

 povray.ttp [file.ini]

You WILL need to specify POVRAY.INI here if you don't specify anything
else or you will be presented with the help screen. Starting POVRay
without a command line will ALWAYS bring up this help screen, even
with the POVINI environment variable correctly set up!

~

Or if you are not keen on the INI file system (and why not???) you
can always revert to the tiresome old POV2 method:

 povray.ttp -isrc.pov -odst.tga -q9 +ft +dl +x +p +b30 povray.ini

...etc...etc...

~

Launching animations is more complicated, and depends on how the
animation is set up. See POVRAY.DOC for details.

If you are using the 'internal animation loop' feature of POVRay, then
it will be sufficient to set up the appropriate options in the default
INI file in order to render an animation. If you are depending on the
external animation loop, or shelling out to the CLI, then you will
need to read the documentation because it does get more complicated.

]--------------------------------------------------------------------[

Additions:

Preview display feature
-----------------------

The most significant addition is 16-bit truecolour preview support
(Falcon only) which can be invoked via the INI file or CLI. You can
actually choose which 16-bit mode you want to use - low, medium or
high (high is RGB only) and if you use Videlity, BlowUP, VI or
FalconScreen, any custom TC modes you have set up will be available
as required. Even if the mode is a non-standard aspect ratio (VGA
medium = 320x480 or perhaps 416x624) then the program will adjust the
preview render so it still looks 'square'.

[BlowUP users: Because BlowUP can't differentiate between desktop
resolutions when changing video mode, all modes (low, medium & high) will
result in exactly the same screen display. If you have not enabled a
BlowUP TC mode then the normal desktop modes will be available instead.]

[ScreenBlaster users: Screenblaster has no VSetMode function, and so
is completely incapable of supporting resolution changes other than
via the Desktop. It can't be used with the preview modes for this very
reason. Use another screen expander if you want preview support.]

The video mode INI file options are as follows:

Display = on/off    - enable/disable truecolour display

Video_Mode = l         - low res: 320x200/320x240/custom-low
Video_Mode = m         - med res: 320x400/320x480/custom-med
Video_Mode = h         - high res: 640x400/640x480/custom-high

Alternatively, if you prefer to use the command line instead of the
INI file, you can use:

-d            - disable display

+dl            - enable display (low res)
+dm            - enable display (med res)
+dh            - enable display (high res)

The display mode supports the following capabilities:

1) Flexible truecolour display supporting both standard & custom modes.
2) Vista-buffer preview support.
3) Mosaic-preview support with automatic size correction.
4) Automatic display ratio correction - for 'brickbat' video modes.
5) Automatic size correction for images larger than display.

Future expansion will allow overscan modes to be used on RGB monitors.

Screenblanker
-------------

The second important addition is the built-in (Falcon) screenblanker.
When both 'verbose' and 'display' are disabled in the 68030+ versions,
a built-in screenblanker will kick in immediately after parsing has
finished. This screenblanker will only turn off when the scene is
interrupted by a keypress or when the scene has completed. Moving the
mouse will not have any effect. The screen blanker speeds up rendering
by a few % and stops your monitor burning out in the process. :)

Notes:

* Because the preview modes are Falcon-specific, you should not
  attempt to use them on non-Falcon machines. The 68000 versiond do
  not support the display and screenblanker features, but the 68030+
  binaries do. These features will only work on the Falcon. If you
  are using a non-Falcon machine with a non-68000 binary, you should
  turn 'display' off and 'verbose' on to prevent any crashes.

]--------------------------------------------------------------------[

Changes:

There are some small extras implemented in the Atari version for
various reasons. They are listed here:

* When 'verbose' is disabled and 'display' is enabled, the credits
  will not be shown. This speeds up execution and prevents loads of
  text scrolling up the screen before anything happens. This is very
  annoying when you are not using a very large screen mode, and you
  have to wait for the scrolling to stop. It's not such a problem
  on the PC where DOS is character-mapped and therefore very fast,
  but TOS used bitmapped graphics modes all the time and scrolling
  text can sometimes be relatively slow. CLI/INI options are still
  shown for practical reasons. If you want to read the credits, then
  you can leave the verbose switch on (default).

* Because POV is such an excellent benchmarking program, it is
  useful to be provided with accurate timing information for each
  scene. Unfortunately, the original version used the system clock
  and so was only accurate to the nearest 2 seconds. This special
  version is internally accurate to 1/200th of a second, and the
  final figures are accurate to 2 decimal places.

]--------------------------------------------------------------------[

Omissions:

There are a number of things still missing from this Atari version and
they are listed here for reference:

* ASCII console GUI interface. This is MSDOS specific, isn't actually
  needed for anything in particular.

There may be other differences from the MSDOS version, but these are
the ones I am currently aware of. There may also be some bugs which
have not yet been discovered. Some bugs present in the MSDOS version
have actually been fixed.

]--------------------------------------------------------------------[

Bugs and other problems:

There are a few minor bugs and inconsistencies specific to this port
which are described here:

* Multitasking support while using the display modes is unlikely to
  work at the moment. This will be corrected in future versions. It
  will however still work under Magic in single-tasking mode so it's
  not a particularly serious problem. It just means everything else
  has to stop while rendering takes place. The program will however
  multitask quite happily if you don't enable the display option.

* The 68000+68881 version of the executable (POV68SFP.TTP) has never
  actually been tested. In fact, the floating point libraries used
  in the program haven't even been tested since they were compiled
  specifically for the creation of this program. If it doesn't work
  then I'm afraid you'll just have to put up with the 68000 version.

]--------------------------------------------------------------------[

Executables supplied:

* POV68000.TTP    - TOS compatible + 68000.

  This version should run on any Atari compatible machine, but it will
  run very slowly. It *only* contains instructions which are supported
  on the 68000 processor. This means is the only binary capable of
  running on a standard ST or STE. It will *not* allow you to use the
  preview display option.

* POV68SFP.TTP    - TOS compatible + 68000 + I/O mapped 68881/2.

  This version will _only_ run on a 68000 based Atari compatible with
  an I/O mapped 68881/2 coprocessor. This should include the Mega/MSTE
  with 68881/2 FPU, although it has never actually been tested! The
  binary was compiled with the special SFP004 Portable Math Library
  patchlevel 23. Just like the vanilla 68000 version, It will *not*
  allow you to use the preview display option.

* POV68030.TTP    - TOS compatible + 68020/68030/68LC040.

  This version will run on *any* 68020, 68030, 68040/68LC040 or even
  68060 based Atari compatible, but it does not rely on a coprocessor
  and will therefore run relatively slowly. It is ideal for use with
  Falcon030, TT or PAK machines without an FPU. This is normally the
  version you have to put up with while you are waiting for your 68882
  to arrive! This version *does* support truecolour preview modes, but
  it should only *ever* be enabled on Falcon machines.

* POV68881.TTP    - TOS compatible + 68020/68030 + 68881/2.

  This version will only run on 68020 or 68030 based Atari compatibles
  with a 68881/2 coprocessor, or a 68040 or 68060 based machine with
  the appropriate FPSP (Floating Point Software Package) installed.
  This version is the best option for most Atari POVRay users, since
  Falcon and TT machines are easily equipped with an FPU if they do
  not contain one already. It is the second fastest of all these
  executables. This version *does* support truecolour preview modes,
  but it should only *ever* be enabled on Falcon machines.

* POV68040.TTP    - TOS compatible + 68040/68060 + FPSP emulator.

  This special version is compiled _specifically_ for 68040 or 68060
  based Atari compatibles with the appropriate FPSP (Floating Point
  Software Package) installed. It will *not* run on any other type
  of platform, due to it's extensive use of integral 68040 instuctions.
  This version of POVRay is the fastest version of all. If you have a
  68040 or 68060, then you really should use it! This version *does*
  support truecolour preview modes, but it should only ever be enabled
  on Falcon machines.

]--------------------------------------------------------------------[

Notes on the new executables:

* Machines equipped with a 68LC040 will be forced to use the POV68030
  binary because the LC chips have *no* integral FPU hardware!

* For practical reasons, it is suggested that users attempt to obtain
  a hardware FPU if they do not have one already. POVRay is not the
  kind of program that will run quickly without an FPU, if indeed
  it can be called 'quick' under any circumstances - but lack of an
  FPU will significantly increase rendering times and may even be
  impractical for most purposes. The practical minimum specification
  required to run POVRay is usually a 68030+68882 running at 16MHz or
  above, but it depends a great deal on your level of patience. :)

* All versions supplied with this package are GCC++ v2.7.2.2 generated
  using -O3 optimisation (with a couple of exceptions for the sake of
  tweaking), and the new GCC MiNTLIBs patchlevel 46. A special version
  of the GCC/PML libraries was generated for each binary, so all of
  the code present is specific for that processor configuration. The
  68040 binary uses 68040 compiled libraries etc. etc.

* I spent a long time experimenting with the GCC++ v2.7.2.2 compiler
  optimisation switches to get these programs running as fast as
  possible, so I know they are as close to 'fast' as they are going
  to get with that compiler. Versions generated with other compilers
  such as Lattice and Pure-C always result in slower code, except
  in the case of vanilla 68000, where Lattice appears to have a
  slight edge due to slightly better 68k software float libraries.

* Anyone using the 68040 version should be made aware that installing
  a copy of the 'MC68040 ToolKit' driver software in the auto folder
  can accelerate rendering to something like 250% normal expected
  performance. You can achieve even more speed by using the supplied
  ECBACK tool to enable the 68040 copyback-cache feature over the
  entire area of FastRAM. This typically yields noticable improvement
  over the basic ToolKit-enhanced figures.

]--------------------------------------------------------------------[

Notes:

* The 16-bit display modes and screenblanking are only available on
  Falcon machines, and won't work on anything else. Don't try to use
  these features on the 030+ binaries if you don't have a Falcon.
  Simply turn 'display' 'off' and 'verbose' 'on' to make sure these
  features are skipped.

* The POVMSDOS.DOC file covers a number of points which are still
  relevant to this Atari version - mainly due to the fact it was
  ported from the MSDOS sourcecode. Any PC specific information
  however should definitely be treated with due caution!

]--------------------------------------------------------------------[

Further notes:

* Read the Atari-specific docs stored elsewhere this package, as they
  deal with alternative ways of setting the software up, and several
  other machine-related issues that are not covered here.

]--------------------------------------------------------------------[

This seems to be the only version of POVRay v3.xx available for TOS
based systems which actually works reliably, and supports all of the
platform-specific features like the preview mode & precision timer.
Hopefully, this version will be adopted as the 'official' unofficial
TOS port and so benefit from future improvements as they become
available to me.

Queries and platform-specific bug reports should be aimed at the
following email address:

Email: <[e-mail]>

The Atari/TOS version of the sourcecode can be obtained from the same
address if anyone wishes to make their own improvements, although I
would like to be notified so it can be done in a non-conflicting way.

Doug Little ~ July 1997