This is a variable passed into POV-Ray, which can be used as a dynamically changing animation variable (clock) in a scene file.
(1a) Initial - This is the clock value at frame #1. It must be different than the "Final" clock value, but otherwise may be any floating point value.
(1b) Start At - This is the displayed clock value at the "Start At" frame value.
(1c) End At - This is the displayed clock value at the "End At" frame value.
(1d) Final - This is the clock value at the "Final" frame #. It must be different than the "Initial" clock value, but otherwise may be any floating point value.
Advanced Tips
-------------
***
*** To speed up rendering as much as possible on the Mac…
***
If you are in the beginning stages of scene creation, you often find yourself editing, rendering, editing, rendering, etc. To speed this up, try shrinking the image size to 32x32, and using the quick_color statements and setting the Image Quality down to about 3. Also hiding the image window during rendering speeds up POV-Ray a bit. If you are generating a final scene, try temporarily booting your Mac with no (or few) extensions on. Some of these, especially screen savers and network connections, can really slow things down. POV-Ray grabs more time if it is in the foreground, so don't switch it out behind others. Also, choose the POV-Ray Preferences item from the Edit menu, and set the Application Friendliness throttle way up, towards 11. Doing all of this can dramatically speed up the scene generation.
***
*** To edit large scene files…
***
Because of the current file size limitation in the POV-Ray built-in editor, you must make sure that the main “.POV” file is no larger than 32K bytes. To edit and render larger files, you must use another text editor to break the file into a small .POV file, which uses the #include statement to use the larger file(s). You can then edit and render the .POV file with POV-Ray. The larger include files must still be edited with another text editor. Note that if you use a word processor to do this (e.g. MacWrite, Word, WriteNow, etc.), you must save the file in “Text-Only” format.
***
*** To batch-render a series of individual scene files…
***
If you are rendering a few files of different output sizes/parameters, open each file in POV-Ray and set up its “Rendering Options” the way you want, and close each file when done. There should be no POV-Ray Source file window open now. Don't quit POV-Ray, but instead just switch to the System 7 Finder. Select all the files which you just opened and set options for. Now drag them over onto the POV-Ray application icon (or convenient application alias) and drop them on it. POV-Ray will (by default) render each file with its own option settings, and save each image before starting the next.
If during this batch rendering process, you want to add more files to the list, just drag the new files onto POV-Ray just like before. These new files will be added to the end of the list of files to batch-render.
To stop the batch rendering in progress, just choose "Stop Rendering" from the Render menu, or press command-period. The current scene will be interrupted, and all remaining scenes will not render. To resume, you will have to drop the remaining scene files onto POV-Ray again.
If you want a series of images to all be rendered, but with identical settings, then do this: Open any one of the files to be rendered, and set up its Rendering Options the way you want all the files to be done. Now choose “Application Preferences” from the File menu. Turn on the “Use Application Default Options” radio button, and turn on the “Save current file's rendering options as the default” checkbox, and click the Save button. Close the source window, but DON'T QUIT POV-RAY YET! Now switch back to the Finder, select all the files, and drag them onto the POV-Ray application icon, just like before. This time, all the files will ignore their individual settings, and use the default application setting.
NOTE: In the interest of safety and user sanity, POV-Ray doesn't remember this override state, but always returns to “…each file's settings…” when it is first run.
***
*** To generate a QuickTime movie from POV-Ray…
***
Use the “clock” variable in expressions in your scene, to scale, translate, or rotate objects. Then use the “Rendering Options” menu item, turn on the “Animate” checkbox, and click the “Settings” button to set the number of frames and the range of the clock variable. When you render the file, it will render multiple times and generate a series of PICT files. You can then use MacroMind Director, Apple's Convert-to-Movie, my FreeWare "MooVer" utility, or some other application to “import” the series of PICT files, and save the result as a QuickTime movie.
To stop the animation rendering in progress, just choose "Stop Rendering" from the Render menu, or press command-period. The current scene frame will be interrupted, and all upcoming frames will not render.
To resume from some frame, you can choose "Animation Settings" from the Rendering Options dialog, and set the "Start At:" to start where you left off. POV-Ray will then begin rendering from that frame to the "End At:" frame.
An example of a spinning box and a moving sphere is shown below:
box { <-1,-1,-1> <1,1,1> rotate clock*y }
sphere { <0,0,0> 2 translate clock*z/36-5 }
If you set up the frames to go from 1 to 20, and the clock value to go from 0 to 360, then the above box will make one complete revolution, and the sphere would move from -5 z to +5 z. The math is left as an exercise to the reader :-)
Animation tip: If you are creating an animation that you want to smoothly loop, there is a subtle problem you might run into. If you set up the animation to go from 0.0 to 360.0 degrees, you will notice that the first and last frames are the same, since in the
"polar regions", zero is the same as 360. This means that at the loop point of the movie, there will be a slight stall because the same frame is displayed twice. To get around this problem, you must do the following:
Set the Final frame to be one more than you actually want (e.g., 101), and set the "End At:" frame at one less than this (e.g., 100). Now set the "Start At:" frame number to 1, and set the Initial and Final clock values to the full range (e.g., 0.0 to 360.0)... whew, now you are ready to make a movie! Of course, you could just delete one of the frames and have a 99 frame movie, but that would be too easy.
Bugs, Quirks, and Future Directions
-----------------------------------
The Bad News...
************
* There is a maximum limit of 32,000 characters (approx. 32K bytes) in source files in the built-in text editor window. The text editor will not allow you to open or create files bigger than this. This is due to a limitation of the Macintosh TextEdit package (i.e., Programmer Laziness.) Although the main file to be rendered must be less than 32K in size, any #included (.INC) files may be of any size. You will just need to use some other editor or word processor to edit those. If you do use a word processor to edit them, remember to save your files in TEXT-only format.
* There is this same 32K limit in the Status window text. When the Status Window gets close to this limit, it just drops things off the top as it adds to the bottom. So you always have the last 32K of text in the window.
* If you create and render a scene file with nothing in it, it will display an error "no objects found in scene." If you try to run the same scene again, you will get some odd error messages.
* After each rendering job, POV-Ray "loses" about 1 KByte of RAM memory. This sloppy phenomenon, sometimes known in programming circles as a "memory leak", is not harmful. However, after you've done a large number of renders without quitting the application, you may eventually get an "out of memory" error. Just quit and restart POV-Ray, and it will be fine for awhile again. This will be more of a problem if you are doing animation renders with lots of frames. You may have to break it into multiple runs, or increase POV-Ray's application heap size. This was addressed prior to release, but not all leaks were found... it will be completely fixed in a future release. All "direct" memory leaks are fixed, what's left seems to be caused by calling runtime routines that themselves leak.
* POV-Ray should be creating the POV-Ray Virtual Image Buffer file in the Temporary Items folder if it is running under System 7, it currently does not.
* There is still an occasional quirk in the vertical scrollbar of the Status window, where it will get out of sync if you scroll it while the window is being filled. Nothing is lost, and if you scroll to the top and back to the bottom, all returns to normal.
* There are reports that the "Finder Balloon Help" of the POV-Ray Application (turn on Balloon Help and point at app in the Finder) does not work on some Macs. It will report a Finder "Type -192" error. It seems to work properly on other machines. This may be due to a corrupt desktop database, although rebuilding the desktop was reported not to help.
* Under System 6.x, POV-Ray will not automatically open a document that is double clicked from the Finder. You must run POV-Ray, then open the file from the File menu. Double-clicking documents DOES work properly in System 7, and in fact, multiple file drag-n-drop is supported. This missing System 6 feature was an intentional omission due to time constraints and the low priority of the feature.
* If you are using a virtual image buffer for a large image, it is not advisable to use the "Size Image to Window" mode, because the image won't display properly. This is only a display problem, It will save properly when finished.
* Adobe Photoshop prior to version 2.5 ignores the vertical-flipped bit of the TARGA files created by POV-Ray, and displays them upside down. Version 2.5 fixes this problem.
* With System 7 Virtual Memory (VM) on, and anti-alias setting on, and an anti-alias on, the VM file will do some thrashing occasionally if your rendering requires a virtual image buffer. This will just slow things way down; it doesn't cause any crashes.
The Good News, Coming sometime after version 2.0...
*****************************************
* Allow selecting an arbitrary area in Image window, and then re-rendering just that area (x1,y1 to x2,y2).. more flexible than the current start/end scanline method
* Allow user to scroll the Image window
* Let user pick file signature for PICT and Targa file formats. Currently, PICT files are saved with TeachText's signature and Targa files are saved with PhotoShop's (PICT creator type is currently saved in scene file's fPrf resource, & could be edited with ResEdit.)
* Built-in QuickTime movie support
* TIFF and PICT image (image-map) support for POV-Ray
* TrueType font support (extruded characters.. need generic POV-Ray syntax additions for typeface import?)
* Allow saving image directly to GIF or 8 bit Mac PICT format (currently just 24 bit PICT now.)
* Mac Network (distributed) rendering
The Mac Source Editor needs a _major_ facelift, to include:
* Abandon stock TextEdit, support source files larger than 32K chars
* Support tabs
* Search and replace features should be added
* Shape prototype generation, esp. torus and other tough ones
* Add balanced curly brace checking
* Simultaneously edit multiple source files, useful for Includes
One possible way to enhance the editor is to give up on the built-in text editor altogether, and tell the user to use BBEdit or some other text editor, and we could break POV-Ray into a faceless rendering engine that accepts AppleEvents. The options dialogs could be supported by a stand-alone application that could alter the file's settings prior to rendering. This makes POV-Ray more loosely coupled, but paves the way for drop-in editors and network rendering. Besides the time it would take to do this, an interesting obstacle to overcome is how the rendering engine would display its image. If it was not so tightly integrated, quick changes and re-rendering sessions may be more awkward. These are some interesting ideas... we are interested in hearing from users as to which way future versions of POV-Ray should head, let us know!
The Source Code
---------------
POV-Ray is a team effort, and the team members use Compuserve's Graphics Developers forum (GRAPHDEV) to keep abreast of changes and suggestions. Before you dive in and write massive enhancements, we suggest that you contact any of the team members and get to know the guidelines. We are an easy going bunch, and very friendly and interested in helping newcomers. And who knows, we may be working on the very same features you want to add, or your enhancement may be one we're hoping to see done. If you wish to make changes to POV-Ray, read the Port Guide, found in the POVSRC archive under MISC:PORTGUID.DOC.
Before you publically post altered source or executables, please review the POV-Ray legal documentation for copyright restrictions and rules of distribution. POVLEGAL.DOC can be found in any of the archives. To restate our position: please contact us directly with any bug fixes or enhancements. We can then incorporate them into the next general release.
The executables released by the POV Team for the Macintosh are built using Think C 6.0. It is possible to create even faster POV-Ray executables using a mix of Gnu C and MPW, but for a straight compilation, Think C 6.0 is a little smaller and faster than MPW 3.2 or MPW 3.3.
You will find the source code in two sections in the POVSRC archive. The main portion of POV-Ray is in POVSRC:SOURCE:. The additional Macintosh-specific source code is in POVSRC:MACHINE:MAC-Source:. These two sets of source should then be put together into a single POV-Ray Source folder before building (any name is fine.)
Some Apple header files for QuickTime compression are also included. These are mainly for the Think C 5 & 6 environment, as they are already present in MPW 3.3. If you're trying to build a version and add newer QuickTime features (1.61 is current as of this release), you may need to get newer header files from Apple or Symantec, or whoever is doing Apple's development system these days :-)
Think C Compiler Notes
------------------------
When compiling, you must use Think C 5.0 or later (preferably 5.0.4 or 6.0.) The enclosed Project file "POV.π" is for Think C 6.0. To compile under Think C 5.x, you will need to throw this file away and create a new one from scratch. Notes on how to do this are listed below.
Think C 5 & 6 don't have the following QuickTime headers, so we have provided them for now. You will need to copy them into Think C's "Apple Includes" folder.
ImageCodec.h
ImageCompression.h
MediaHandlers.h
Movies.h
MoviesFormat.h
QuickTimeComponents.h
You should first make a COPY of your "Standard Libraries:ANSI" library's Project file, and rename your copy to “ANSI-020.FPU.NoConsole”. This will be the ANSI library you'll be using for POV-Ray. Remove the files "console.c" and "command.c" from the project. Choose the Edit:Options menu, and change the following: Think C:Compiler settings, turn on all checkboxes except "4 byte ints" and "8 byte Doubles". Code Optimizations:turn on all, but not the Global Optimizations. Debugging:turn off all. Prefix:add a #define _NOCONSOLE_. Choose the menu Project:Set Project Type, and turn on "Separate Strs". Now "update" to compile all the modules.
For Think C 5 users, there are some additional steps, to create the POV.π project file from scratch. Start up Think C, create a new project called POV.π, and add all the .c source files to the project. Here's the current segmenting strategy:
=== Segment (povNEditor) ===
FileQueue.c
POV.c
POVMalloc.c
ScreenUtils.c
TextEditor.c
=== Segment (textures) ===
pigment.c
texture.c
txttest.c
=== Segment (tokenize) ===
express.c
matrices.c
tokenize.c
=== Segment (macwindows) ===
animate.c
imagewindow.c
popupmenu.c
printf2window.c
progressdialog.c
savecmppict.c
stdcompressionglue.o
templatemenu.c
=== Segment (files) ===
dump.c
gif.c
gifdecod.c
iff.c
raw.c
targa.c
=== Segment (parse) ===
parse.c
=== Segment (render) ===
normal.c
povray.c
ray.c
render.c
vect.c
=== Segment (polyquad) ===
poly.c
quadrics.c
=== Segment (heightfields) ===
hfield.c
=== Segment (cameraNlights) ===
camera.c
lighting.c
=== Segment (primparse) ===
boxes.c
colour.c
csg.c
image.c
objects.c
planes.c
point.c
=== Segment (primparse2) ===
blob.c
bound.c
cones.c
discs.c
=== Segment (primparse3) ===
spheres.c
triangle.c
=== Segment (bezier) ===
bezier.c
=== Segment (ansi) ===
ANSI-020.FPU.NoConsole
MacTraps
MacTraps2
Choose the Edit:Options:Think C: menu, and change the following: Language:turn on Check Pointer Types and Think C Language Extensions. Compiler settings, turn on all checkboxes except "4 byte ints" and "8 byte Doubles". Code Optimizations:turn on all. Debugging:turn off all. Prefix:add a #define _NOCONSOLE_. Choose the menu Project:Set Project Type, and turn on "Separate Strs", set the Creator to "PvRy", set the Size Flags to 58E0, set the type to Application, and set the Partition to 1000. Insert the following into the Prefix options from the Edit menu:
#define SystemSixOrLater true
#define _NOCONSOLE_ // turn off Think C console I/O
#include <MacHeaders>
#define NEEDS_68020 1 // turn on to force 68020 or better CPU code
#define NEEDS_COLORQD 1 // turn on to force Color Quickdraw ROM Support
#define NEEDS_32BITQD 1 // turn on to force 32Bit Quickdraw ROM Support
#define NEEDS_FPU 1 // turn on to force 68881 FPU calls
#define USE_NATIVE_MALLOC 1 // turn off to use C's malloc(), on for Mac's NewPtr()
After you build the application, you must set the application's (preferred) memory size to 2500, using the Finder's "Get Info" menu item. This is currently the only way to set the minimum and preferred memory sizes differently.
MPW C Compiler Notes
----------------------
The non-FPU version of POV-Ray was compiled under MPW, because the code generated was too big for Think C (specifically, hfield.c.) An MPW compile of the FPU version of POV-Ray is possible, but generates a noticeably larger and slower application.
POV-Ray has been compiled and tested using Apple's MPW C compiler, version 3.2.2 and 3.3. The make file supposedly supports MPW 3.0 and 3.1 as well, but has not been tested.
In order to compile POV-Ray with the included make file, you will first need to manually create an empty folder inside the POV-Ray Source folder called “obj”. The object files will be stored in there, instead of being sprinkled through the source code folder.
MPW 3.2 doesn't have the following QuickTime headers, so we have provided them for now. You will need to copy them into MPW's Interfaces:CIncludes folder.
ImageCodec.h
ImageCompression.h
MediaHandlers.h
Movies.h
MoviesFormat.h
QuickTimeComponents.h
You will also need to put the file "stdcompressionglue.o" into MPW's :Libraries:Libraries: folder.
There are quite a few flags used to turn on and off options (FPU, native-malloc, etc.), these are in the Make file itself.
There are some warnings that show up in the POV-Ray core code, all of them are due to unused function parameters. These are, in the immortal words of Douglas Adams, “Mostly Harmless.”
PowerPC Compiler Notes
----------------------
The PowerPC compile is being done by David Harr, and is as preliminary as the PowerPC development system for now. David Harr can be reached at wirehead@netcom.com.
