Manual for ClockPoV 1.5
-----------------------

     The ultimate shell for Persistence of Vision!

     Well, this is not a real manual. This is only the better translation
of the HYP manual I could do. You better read the ST-Guide HYP file because
even if redrew most of the popups and menus with characters, the missing
pictures are really... missing! And there is such a lack of interactivity
in this text! And I really miss all these text effects and colors... ;-)


     1 - Legal informations

     2 - System requirements
     3 - Interface behavior

     4 - Menu overview
     5 - ClockPoV main dialog
     6 - Pathnames dialog
     7 - Clock Animation Shell
     8 - Advanced options
     9 - Supersampling options
    10 - Partial rendering
    11 - Histogram options
     
         On the to-do list...

         Known bugs
     
         Thankings

.....................................
Note: Please read the PoV's documentation! Not all PoV's options are
explained herein.

AFAIK: As Far As I Know.

IMHO: In My Humble Opinion.


***************************************************************************


1 - LEGAL INFORMATIONS

     ClockPoV is FREEWARE. You can copy it, distribute it any (legal)
way as long as the archive remains untouched.
     
     Translations are welcomed but please send them to me so I can
include them in the archive and write your name in both copyright dialog
and documentation.

     The copyright of ClockPoV is mine so do not replace my name by yours
in the ressource file even for a translation! Thanks!
     
     Updates (if any) can be obtained directly from me. Ask first!
     
     Send also critism, suggestions, ideas, bug reports or even money
(I'll accept it)  ;-)  to:
     
     SoftBlue / Remi Villatel
     20 Route de Saint-Valry
     76450 Cany-Barville
     France
     
         NeST: Remi Villatel @ 90:800/1.6
     AtariNet:               @ 51:901/1.6
      FidoNet:               @ 2:320/107.6
     
     Internet: maxilys@worldnet.fr
     
.....................................
     SoftBlue reserves the right to make changes without further notice
to its softwares and/or documentations herein to improve reliability,
function or design. SoftBlue does not assume any liability arising out of
the application or use of anything described herein; neither does it convey
any license under its patents rights nor the rights of others.

     SoftBlue products are not authorized for use as part of life support
devices or systems intended for surgical implant into the body or intended
to support or interrupt life. User agrees to notify SoftBlue of any of such
intended end use whereupon SoftBlue will determine availability and suita-
bility of its product or products for the use intended.

     SoftBlue, the SoftBlue logo, ClockPoV and the ClockPoV logo are
trademarks or registred trademarks of the SoftBlue company.
     

***************************************************************************


 2 - SYSTEM REQUIREMENTS


     You can copy ClockPoV anywhere, inside or outside of a folder
but preferably not on a floppy. Floppies are definitively too slow.
Only 3 files must stay together (at the same place on your hard disk):
     CLOCKPOV.PRG, the program itself;
     CLOCKPOV.RSC, its ressource file;
     CLOCKPOV.SET, its default configuration file (if any).

     ClockPoV is written in GFA 3.6 with FaceValue (the only REAL
application builder on Atari) and will therefore support any graphics
card and any resolution since it is a GEM compliant program. Neverthe-
less, it will refuse to work in a resolution lower than 640*400 because
some dialogs extend beyond the screen limits in 320*200/240 and they
look awfull in 640*200/240. (Please, respect the designer's work!)  ;-)

     The ST-High resolution may look like a little high but as ClockPoV
does not (directly) support the PoV's display options, it does not matter.

     ClockPoV should support MagiC, MultiTOS and NAES too. Such systems
do not work on my Hades060 but I made tests on my TT030.

     ClockPoV will request around 200 Ko of any kind of RAM (ST/TT).
By now, it does not unload itself before launching PoV so be careful with
the PoV's output buffer size option if you are short of memory.

     If you want to benefit from the online help, you have to install the
ST-Guide accessory and to copy the "CLOCKPOV.HYP" and "CLOCKPOV.REF" files
in your hypertexts directory.

     ClockPoV is designed to support long filenames, i.e. the edit fields
containing filenames have a length of 20 characters but the names will
never be truncated nor upcased anyway. (Only the display may be truncated.)
To benefit from those long filenames, both GEMDOS and the file selector
must support them because this is the way ClockPoV handles files. No special
checkings are made to know if long filenames are available and no special
routines are called to support them.


***************************************************************************


 3 - CLOCKPOV INTERFACE

     WARNING! Although you can set a lot of things in ClockPoV, first
do not forget that only PoV 3 supports all of them! And second do not
forget to activate the desired options. Setting them does not mean
activating them!

     The 3D look available in Falcon's AES and above is voluntary disabled.

     All dialogs in ClockPoV are "windowed". They behave like normal
windows, except a few ones that cannot be topped by other windows. These
special windows always contain a little dialog to enter values (like the
width and the height) that must be checked before the window is closed
automatically.

     Appart from the "untoppable" windows, all windows can be cycled with
the dedicated menu entry or its corresponding shortcut [CONTROL W].

     When available, an "Help" button calls ST-Guide which then must be
installed (and the "CLOCKPOV.HYP" in the hypertexts folder). You can click
on an "Help" button but I made them very small to force you to use the [HELP]
key.  ;-)

     An underlined letter is a shortcut for you to click on a button or
to open a popup menu.

     In a popup menu, you can use the arrow keys to move the cursor and
the [RETURN] key to select or [ESC] to close the menu without performing
any selection.

     When you see an editable field but no text cursor, you have to click
on the field to change its value. An "untoppable" window will be opened for
you to type in.

     When you click on the "OK" button of a dialog, the typed values are
checked and eventually corrected or reset. In such a case, the window does
not close itself but displays the new values that you have to accept or
modify once again.

     When available, the closer button has the same effect as clicking on
the "OK" button, i.e. to confirm what you set or type. There is no "Cancel"
button since some setting may affect several dialogs, I did not know what
to cancel.

     WARNING! Changing the size of the raytraced image reset the partial
rendering to its full size. I designed a dialog to tell it to you but it
was too annoying and the partial rendering options are not so important.


***************************************************************************


 4 - MENU OVERVIEW

      ClockPoV  File  Options
     ----------------------------------------------------
     ////////////////////////////////////////////////////

 | ClockPoV |
+-------------------+
| Informations... ^I| The copyright dialog. (Very nice in color!)
+-------------------+
| ST-Guide          |
| DarkLord          |
| NOVA Color        | Your accessories. (These ones were mine when I took
| Control Panel     |                   this snapshot.)
| Hades Control     |
| (X)IMG-Snapshot   |
+-------------------+

 | File |
+------------------+
| Exec PoV       ^P| Very clear! But do not forget to set its path...
| Exec editor    ^E| The current script will be sent as command line.
| Exec viewer    ^V| The last raytraced image will be sent as command line.
+------------------+                    
| Quit ClockPoV  ^Q| Use this option at your own risks!  ;-)
+------------------+ (ClockPoV is only a shell so you quit WITHOUT further
                     notice.)


 | Options |
+-------------------------+
| All pathnames...     s^A|
+-------------------------+ 
| General...           s^G| ClockPoV main dialog.
| Clock anim. shell... s^C| 
| Advanced...          s^D| 
| Supersampling...     s^U| 
| Histogram...         s^H|
| Partial rendering... s^R| 
+-------------------------+ 
| Save options...      s^S| You can have several setups with different
| Load options...      s^L| names. Default setup is "CLOCKPOV.SET".
+-------------------------+ 
| Auto-save on exit       | To save the setup automatically. (v/)
+-------------------------+ 
| Cycle windows         ^W| Just note the shortcut [CONTROL W].
+-------------------------+ 


***************************************************************************


 5 - CLOCKPOV MAIN DIALOG

     Menu shortcut: [SHIFT CONTROL G]

     This is really the most important dialog in ClockPoV. All basics
options can be set in it and all other option dialogs can be called
from it.


Input: The script file.            Format: | Compressed TGA  |
Its path is displayed only in              | PNG 8 bits      |
the pathnames dialog.                      | PNG 16 bits     |
                                           | PPM             |
                                           | Uncompressed TGA|
[Library pathnames]
Do not forget to select the ones   The output format.
you want to use. They have to be   (The only hereabove format supported
set in the pathnames dialog.       by PoV 1 and 2 is uncompressed TGA.)


[+V] Verbose message               Output: The raytraced image.
If set, PoV tells you what it is   Its extension is changed accordingly
doing, otherwise not.              to the hereabove set format.
                                   Its path is displayed only in the
                                   pathnames dialog.
[+P] Pause | before| exit
           | after |
                                   Raytrace quality: | 0        |
Before exit, this is PoV's one.    Please remember   | 1        |
(Some versions of PoV 3 react      that only PoV 3   | 2        |
in a strange way to this option    supports radio-   | 3        |
which becomes therefore useless.)  sity.             | 4        |
After exit, this is ClockPoV's                       | 5        |
one. Solid as a rock! And you                        | 6        |
can use any mouse button.                            | 7        |
                                                     | 8        |
                                                     | 9        |
[+X] Early exit by key hit                           | Radiosity|
Set it if you want to interrupt
PoV's work.
                                   Image width and height
                                             [Predefined] |  160*120|
[+] Test every ???? pixels         Some usefull sizes.    |  320*240|
Always set to the width of a line.                        |  640*480|
                                                          |  800*600|
                                                          | 1024*768|
[+C] Continue aborted trace                               |  160*100|
There was a power failure during                          |  320*200|
the night? You can continue now. <G>                      |  640*400|


[+B] Output buffer: |   64|        [Partial rendering...]
                    |  128|        [SHIFT CONTROL R] in menu.
                    |  256|
                    |  512|
                    | 1024|        Antialiasing quality: | 0.0|
                    | 2048|        Usually 0.3 but you   | 0.1|
                                   can change this.      | 0.2|
The PoV's output file buffer.                            | 0.3|
Nowadays, the speed of the hard                          | 0.4|
disks are so high that there is                          | 0.5|
no real use for such a buffer;                           | 0.6|
the time spent to write the image                        | 0.7|
datas is insignifiant and some     [Supersampling]       | 0.8|
versions of PoV do not use it!     [SHIFT ^U] in menu.   | 0.9|


[Advanced options...]     [Histogram options...]     [Pathnames dialog...]
[SHIFT CONTROL D] in      [SHIFT CONTROL H] in       [SHIFT CONTROL A] in
menu.                     menu.                      menu.
                                   
[+K] [Clock Animation Shell...]    [ PoV ] To launch PoV. But you can
[SHIFT CONTROL C] in menu.         always launch it with its menu shortcut
                                   [CONTROL P].

.....................................
Note: Whatever the clock values are, the numbering always begins at 0 and
is increased by a step of 1. When you use the possibility to set the clock
to a specific value, the number is calculated and is the same as if you
made a complete loop.

Note: If you use the clock loop features, you can interrupt the loop in
pressing both mouse buttons. It is easier for you not to disable the early
exit option [+X], so you can press both mouse buttons while PoV is still
working then interrupt it with any key and the loop will be exited this
way; otherwise you will have to wait until PoV had finished its work.

Note: ClockPoV pause option (Pause after exit) only works ONCE, i.e. once
after a complete loop or a single raytracing. And whatever pause you
choose, do not forget to activate it!


***************************************************************************


 6 - PATHNAMES DIALOG

     Menu shortcut: [SHIFT CONTROL A]

     Even if this is not the dialog that is opened at first each time
you launch ClockPoV, you must cast more than a simple glance to it!


[PoV fullpath] The pathname to the executable TTP of PoV.


[Input path] Although it is written "path", you must select a script.
(Default extension: "POV".) The name of the script is only written in the
ClockPoV main dialog.


[Output path] Although it is written "path", you must select an output
image. (Extension depending on the format defined in ClockPoV main dialog.)
The name of the image is written in the main dialog.


[Library 1] You can defined up to six library pathnames that PoV will use
     .      to retrieve INC files and images to map. Set does not means
     .      activated so do not forget to select the pathes you want to
     .      use in the "Library pathnames" popup listbox of the ClockPoV
     .      main dialog.
[Library 6] You can erase a pathname in double-clicking on its button but
            one path will always remain as library 1. This library can not
            be erased nor deselected in the corresponding popup listbox.


[Editor fullpath] Enter here the pathname to your favorite text editor and
you will be able to call it with the corresponding menu entry "Exec editor"
or its shortcut [CONTROL E]. The name of the script will be sent to it as
command line.


[Viewer fullpath] Select your favorite paint package, an image processor or
a simple viewer. Whatever you choose, be sure that this program accept the
format of the last raytraced image; that is what will be sent to it as
command line when you will call it with the corresponding menu entry "Exec
viewer" or its shortcut [CONTROL V]. If no image has been raytraced yet,
the viewer is called but without a command line.

.....................................
Note: You can only click on the buttons or use their shortcuts.

Note: If you need to press [SHIFT] to obtain the ciphers on the main
keyboard (french keyboards are like that), you must press [SHIFT] and
[ALTERNATE] with the cipher to use the libraries button shortcuts.


***************************************************************************


 7 - CLOCK ANIMATION SHELL

     Menu shortcut: [SHIFT CONTROL C]

     This is not a real shell but this dialog enables you launch PoV
several times in a loop that will set the PoV's clock variable.


Insert numbering in
                                        Use | 3  | chars
                                            | 4  |
Do you prefer decimal or hexadecimal?       | all|
It's up to you! This numbering is done
in order that all images generated in   The size of the numbering.
a loop do not have the same name.       ("all" means 8 characters.)


[ ] Generate BAT file The pathnames of the raytraced images will
be written in an ASCII file for an animation generator (like MPLAYER for
example).   


( ) FOR clock=????.????      TO ????.????        STEP ????.????
    The start value          The end value       The sign of the step
                                                 will be automatically
AFAIK PoV does not accept negative values and    defined.
not all PoV versions will accept floatings.

( ) [  ] clock=????.???? [  ] To set the clock value within the limits of
the above loop. (Double click to reach the limits.)
                                        
( ) [Animation Sequencer] This part is disabled by now. It will become
more and more interresting... later! (Look at what's on the to-do list!)

The round radio buttons allow you to
choose between a loop or setting the    [  OK  ] Do not forget to activate                                        
clock value once.                       the clock animation shell with its
                                        corresponding [+K] button in the
                                        ClockPoV main dialog.

.....................................
Not to forget: Press both mouse buttons to interrupt a loop, but it does
NOT interrupt PoV's work; you have to interrupt it TOO someway! (Read my
trick at the bottom of the page dedicated to ClockPoV main dialog.)

Note: The BAT file is always written whether you use the clock features or
not (in this case, it is a kind of LOG file).


***************************************************************************


 8 - ADVANCED OPTIONS

     Menu shortcut: [SHIFT CONTROL D]

     I did not know what title to give to this dialog...  ;-)  Anyway,
here it is!


     All these options should be set to increase the raytracing speed.
     

[+MV] Compatibility to PoV | 3.0|
Always set the version to  | 2.0|
the one you are using.     | 1.0|


[ + ] This line is for you. All that you type in here will be added to the
end of the command line sent to PoV. I wrote somewhere in this hypertext
that ClockPoV does not directly supports PoV's display options but you can
use this line to add such options.

.....................................
Please read PoV's documentation to know what the unexplained options do.


***************************************************************************


 9 - SUPERSAMPLING OPTIONS

     Menu shortcut: [SHIFT CONTROL U]

     These options can be set for each object in your scripts or, here, 
globally for the entire image.


[+AM] Supersampling: | non-adaptive|
                     | adaptive    |


[+J] Antialiasing jitter amount: 0.??
Advised values are in between 0.0 and 0.5 (included).


[+R] Antialiathing depth: | 1x1| rays.
The number of rays used   | 2x2|
to calculate each pixel.  | 3x3|
You understand that 1x1   | 4x4|
has no effect although    | 5x5|
it is allowed.            | 6x6|
                          | 7x7|
                          | 8x8|
                          | 9x9|


***************************************************************************


10 - PARTIAL RENDERING

     Menu shortcut: [SHIFT CONTROL R]

     Although I never used these options, I included them... Do what you
want with them!  ;-)


                                   Colomns [Predefined] | Full size  |
Rows [Predefined] | Full size  |                        | Left half  |
                  | Top half   |                        | Middle half|
                  | Middle half|                        | Right half |
                  | Bottom half|

Start and end values will be swapped without further notice if necessary.
And wrong values will be reset to full size after notice.

     WARNING! All these values are automatically reset to full size each
time you change the size of the raytraced image.


***************************************************************************


11 - HISTOGRAM OPTIONS

     Menu shortcut: [SHIFT CONTROL H]

     Histogram is the less usefull option in PoV as it wastes time for no
real use but you can play with it, if you want.


[+HT] File format: | CSV speadsheet |
                   | PNG grayscale  |
                   | PPM heightfield|
                   | TGA heightfield|

The extension of the filename (under) will be changed accordingly.

.....................................
Please read PoV's documentation to know what the unexplained options do.


***************************************************************************


ON THE TO-DO LIST

     The Animation Sequencer!

     What I intended to do with that is to allow you to generate an
include file for your script. So you could use more than one single
variable to animate objects. What I am working on now is to provide
you more than simple variables to set, i.e. the possibility to set
curve or linear pathes for your objects to move along them. For
example, look at this (for PoV 3):

     #include "clockpov.inc"
     
     #declare banking = vrotate( <0,1,0>, -z*rr )
     
     camera {
          location <xx,yy+10,zz-30>
          sky banking
          look_at <xx,yy,zz>
     }
     
     light_source { <0,80,-40> color rgb <1,1,1>
          spotlight point_at <xx,yy,zz>
          radius 15
          falloff 25
     } // A light
     
     object {
          plane { y, 0 }
          pigment { strange_marble }
     } // The ground
     
     object {
          sphere { <0,0,0> 5 }
          pigment { white_with_a_red_ring_in_the_midle }
          rotate -z*rr
          translate <xx,yy,zz>
     } // The ball

     I already made the sphere bounce and roll across the space but the
resulting psychedelic QuickTime file was too big (22 Mo!) to be included
in ClockPoV's archive... and I'm still working on the interface of this
animation sequencer. So wait and see...


***************************************************************************


KNOWN BUGS

     Well, I noticed a strange behavior of ClockPoV when you double-click
on an edit field: it may hang. It happens sometimes only, not every time.
I dug deep in FaceValue engine but I did not find the reason. So, click
only once! <G>

     The second bug I found does not depend on ClockPoV but on the other
programs. After having launched another program, it may happen that
ClockPoV keeps the desktop background of the other program although the
menu and the dialogs are perfectly redrawn. The only program I know that
causes this strange behavior is Studio Photo under a monotask TOS. Any way,
it does not disturb the good working of ClockPoV, so try to ignore this...
Close your eyes! ;-)

     The last bug that you may encounter belongs to PoV! When there is not
enough space to render an image, PoV creates and empty file and reports
absolutely nothing to its shell! You are warned: Always be sure that there
is enough space on your hard disk! ClockPoV could evaluate the place for
an uncompressed TGA but for none of the other formats supported by PoV then
I dropped the idea to perfom a test. Nevertheless, ClockPoV always checks
the disk before writting its own files and warns you if necessary. (PoV is
a good program but a dirty one!) :-\


***************************************************************************


THANKINGS

     Thanks to...
 
     My mother who gave birth to me,  :-)
     The PoV Team who made PoV,
     All the guys who adapted PoV to the Atari and compatibles,
     Medusa Systems for my Hades060,
     Columbus Soft for its wonderful FaceValue,

     ...and a special thanking to Motorola for its legal message
     in the DSP 5600x manual that made me grin a lot...  <G>
     (Look at the end of the legal informations. I only changed
     a few words.)  ;-)


***************************************************************************
[EOF]
