These notes are specific to the Macintosh version only. For information regarding POV-Ray functions, including the scene description language, refer to the separate documentation for POV-Ray.
Overview
-------------
POV-Ray is a ray-tracing program. It uses mathematical representations of 3-D objects such as spheres, planes, and triangles, and mathematical models of light sources to calculate and render photograph-like images. POV-Ray uses a special ╥scene description language╙ saved in text files to describe these objects. There is a built-in text editor for small POV-Ray source files (the standard 32k limitations currently apply.) POV-Ray can read and render included files of any size, however. Just use your favorite word processor to create or edit larger documents, but be sure to save your files in TEXT-only format. Refer to the POV-Ray documentation and any of the dozens of example files to see how an object description file is made.
If you don't read read-me files (or even if you do)
--------------------------------------------
The pre-defined paths ":::Include:" and "::Include:" are created automatically in the POV Preferences when you first run POV-Ray Mac, so the example files will render without a hitch. Have fun.
POV-Ray Requirements and Main Features
----------------------------------------------
Ñ Requires a 68020 or later CPU with a Floating Point Unit (or an FPU software emulator.) For example, a Macintosh II, Powerbook 170, LC, Classic II, or SE/30.
Ñ Runs under System 6.0.4 or better. System 7 required AppleEvents are supported. This also means that text files can be ╥dropped╙ onto POV from the Finder (in 7.0) and it will open them.
Ñ Requires 32 bit Color Quickdraw capable machines. Note: 32 bit Color Quickdraw is automatically installed with System 7 on color machines, but you must use the Custom Install options to get it on the SE/30 and other black & white systems. There is a separate extension that should be present when running System 6. This extension (╥32 bit QuickDraw╙ version 1.2) can be found on many BBSes, or from local Apple Dealers.
Ñ POV-Ray runs great on the Quadra, with rendering times comparable to an IBM PC 486/33.
Ñ Can run and render small files in a 1 mb application memory partition. Suggested size is 2-4 mb, and some very large files have been known to use as much as14 MB (for monster projects, it's time to turn on your Virtual Memory, or buy some 4 mb SIMMs now!)
Ñ POV-Ray can run in the background while you perform other work, and has settings for trading off its background friendliness against performance.
Ñ POV-Ray can output image files as Macintosh PICT files, or in Targa format. Other versions of POV-Ray (such as the IBM PC version) also output the data in other formats more useful to those platforms. If you select Targa as the output file format, the image data can be reloaded later if you need to stop POV-Ray for any reason. Creating a Targa output file is thus recommended for very long renderings -- you can interrupt the rendering process to do other work if it takes longer than expected. Once POV-Ray has finished rendering an image, it can be saved as a PICT file which can be read by most paint or image processing programs. POV-Ray's PICT files are always saved in highest quality 24 bit color (even if you're viewing it on a monochrome display), with optional dithering for 8 bit or less capable color displays.
It's suggested that you convert your PICT output to a GIF file with PhotoShop or GIFConverter if you're not using a 24 bit video display, because there's no palette information encoded into the POV-Ray PICT files. A PICT conversion utility will provide a well chosen palette of colors to display your image with, improving your display quality immensely.
Ñ POV-Ray can optionally save the final image and shut down the power to the computer when the rendering is complete. This feature works under System 6 and 7.
Ñ If the Option key is held down when selecting the picture saving menu, a QuickTime compression options dialog will appear after you name the PICT file. The QuickTime INIT must be installed to take advantage of this feature. High quality JPEG is recommended for still images. Video compression is your best choice if you're piecing together a POV animation.
Ñ╩Smaller POV-Ray images can be ╥copied╙ onto the clipboard, for pasting into System 7 icons or other paint software. For these icons, it's recommended that you render the image with 32x32 resolution and use the Draw Border menu command after the image has rendered, before pasting the icon.
Ñ╩POV-Ray has a limited set of image enhancement functions designed for icon creation but can also be used on larger images when POV has enough free memory.
Ñ If you're trying to render a scene file that is larger than 32k, break it up into smaller pieces and create a new file that uses #include to include all of the individual parts. In general, a scene file larger than 32k has too many object definitions, and it's better anyway to create objects as included files that can be shared with other scene files you create later.
Ñ Balloon help is provided by David Harr.
Program Notes
------------------
This version of POV-Ray is a hefty rewrite and user interface redesign, and thus bears little resemblance to earlier versions. Familiarize yourself with the new features -- you should be pleasantly surprised.
POV-Ray tries to store images entirely in RAM while rendering them. Sometimes this is not possible, because the image requires (4 x Width x Height) bytes of memory. For example, a 640 x 480 image needs about 1.25 megabytes of RAM. When POV can't hold the image in RAM, it will hold it in a temporary disk file, and do more disk I/O. Allocate more memory to POV-Ray to avoid increased wear and tear on your hard disk and to speed up rendering times on large images.
If you're using virtual memory, particularly for extremely complex images, you may notice outrageously large delays during parsing. This is the result of serious inefficiency in the way Think C's memory allocation and Apple's virtual memory system interact. Once parsing has finished, actual rendering time should be fairly comparable to non-virtual memory systems.
POV-Ray is set to an initial memory partition size of 2,350K. This size is sufficient to render all of the standard example files except IONIC5 with room to spare. IONIC5 requires that you set the memory partition to 5,200K. For less complex images, POV-Ray can render effectively in a memory partition as small as 800K, and the vast majority of the example scene files will render with 1,100K. To change POV's memory partition, click once on the POV-Ray program icon in the Finder, then choose ╥Get Info╙ from the File menu. The application memory size is in a box in the lower right corner of the window, and can be edited.
Known Bugs
----------------
There is a limit of 32,000 characters in source text files in the built-in editor. This is a limitation of Apple's TextEdit package.
Out-of-memory conditions are not handled very gracefully. If you get an out-of-memory error in POV-Ray, it is best to immediately save your scene description file and quit POV-Ray. Fix the problem by increasing POV-Ray's application memory size (use Finder's Get Info menu item), or reduce the output image size or scene complexity next time you run POV-Ray. If you continue to use POV-Ray after any kind of "out of memory" error, POV-Ray may crash and your scene file work may be lost if you haven't saved it.
POV-Ray cannot automatically open documents that are double clicked from the Finder while using System 6.
With anti-alias setting greater than zero (adaptive anti-aliasing,) the virtual memory file will do some thrashing occasionally if your rendering requires virtual display memory. This will just slow things down; it doesn't cause any crashes.
Other Files
----------
In addition to the application, you should be able to find archives with the following:
POV-Ray Documentation
Example Files
Think C 5.0 and MPW 3.2 compatible Source Code
Source Code
-----------
If you wish to make changes to POV-Ray, read the Port Guide. Keep in mind that POV-Ray is a team effort, and team members use Compuserve's COMART forum to keep abreast of changes and suggestions. Before diving in and writing massive enhancements, contact the team and get to know the procedures. They are an easy going bunch, and very friendly to newcomers.
If you want to improve the Macintosh version, please don't hesitate to contact us. 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. See the end of this document for where to get more information.
Don't distribute ANY modified version of POV-Ray, even if your modifications are minimal. If you have any questions, review the POV-Ray documentation for copyright restrictions and rules of distribution. The POV Team does not permit the public release of modified source code or executables. This restriction is necessary for us to provide consistent support and avoid repeats of past problems of incompatible versions coming into widespread use. To restate our position: please contact us directly with bug fixes or enhancements.
The executable released by the POV Team for the Macintosh is built using Think C 5.0.2. It's possible to create faster POV-Ray executables using a mix of Gnu C and MPW, but for a straight compilation Think C 5.0.x beats MPW. Jim Nitchals has already contacted Symantec with suggestions for further improving Think C, so we expect future versions of POV-Ray to run even faster.
Think C Compiler Notes (Jim's fortÄ)
---------------------------------
When compiling, you must use Think C 5.0.1 or later. Think C 5.0 (the first release) is buggy as all get-out and updates have been available for some time now on all the major online services, free of charge.
You should first make a COPY of your ANSI library's Project file, and rename your copy to ╥ANSI 881/020 No Console╙. This will be the ANSI library you'll be using for POV. Change the compiler settings to 68881, 68020, and native floating point. Remove console.c and command.c from the project. Insert a #define _NOCONSOLE_ into the Prefix options from the Edit menu. You must also make sure the ╥Far Data╙ option from the Set Project Type╔ menu is CHECKED. Update the ANSI 881/020 No Console project. This is all really important; POV-Ray won't work otherwise.
To save space, I didn't include the POV Project file itself. You can build one pretty easily, though. The POV-Ray project should have 68881, 68020, and native floating point checked. The Prefix options from the Edit menu of Think C should read:
#include <MacHeaders>
The project file is called ╥POV.╣╙. The resources for POV are contained in ╥pov.╣.rsrc╙, which is also provided.
Add MacTraps and MacTraps2 from the Mac Libraries of Think C to the POV.╣ project..
The Size flags in the Project->Set Project Type╔ menu should be set to 58C0. The application signature is 'PVtm', and the recommended partition size is 2350K. Far data MUST be checked; far code does not need to be checked.
Strict prototype enforcement is enabled, and ╥infer prototypes╙ is the preferred option for this setting.
Far Code is not necessary, but Far Data may be necessary when building this version of POV-Ray. Make sure your ANSI 881/020 No Console and POV-Ray projects agree on this option. The release version is built using Far Data.
Some Apple header files and glue for QuickTime compression are included. If you're trying to build a version and QuickTime 1.1 or later has been released (1.0 is current as of this release), get new files from Apple and incorporate them into your version of the POV source. Use the "oConv" utility to convert any MPW object modules supplied with QuickTime. If there's a link error with missing names, consult the Think C User Manual (page 291-294) to fix the vocabulary file for the all-uppercase names in the object module.
There appear to be no problems at all using the global optimization features in Think C 5.0.1 or 5.0.2. I recommend enabling all of the optimization options. The POV-Ray source itself is 100% compatible with Think C 5.0.1 and 5.0.2.
Here are some suggested partitions for the Project file:
POV-Ray has been compiled and tested using Apple's MPW C compiler, version 3.2. 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 need to dump all the source into a folder (e.g. POV:) and create an empty folder inside that called ╥obj╙. The object files will be stored in there, instead of being sprinkled through the source code.
There are a fair number of warnings that show up in the POV-Ray core code, all of them are due to unused local variables that have not been removed. These are, in the immortal words of Douglas Adams, ╥Mostly Harmless.╙ I hope to convince the team to remove these in a later release so the compile is cleaner, and the stack is less cluttered.
Some Apple header files and glue for QuickTime compression are included. If you're trying to build a version and QuickTime 1.1 or later has been released (1.0 is current as of this release), get new files from Apple.
*************************
POV Option Dialogs in Detail
*************************
Here's a short description of the various options presented before rendering:
File Rendering Options
-----------------------------
Ñ Thumbnail: this button changes the settings to a 32 x 32 pixel ╥thumbnail╙, which is ideal for previewing images and creating System 7 Finder icons. Thumbnails can be further edited within POV to adjust contrast and brightness, and draw a black border around the edges. To paste into a System 7 icon, first render an image then choose ╥Copy╙ from the Edit menu of POV-Ray. Go to the Finder, Get Info on a file then click on the icon in its info window. Choose "Paste" from the Edit menu of the Finder, and the icon will change to the new image.
Ñ 320 x 240 (preview): this button changes the settings for rendering at 320 x 240 pixel resolution. This setting is good for seeing all but the finest details in an image.
Ñ 640 x 480 (high quality): use this button for high quality rendering. A Targa output file is automatically selected in this mode, so that you can interrupt the rendering if need be. Note that you can then turn the ╥Create Targa file╙ option back off if you do not want this option.
Ñ OK: Click this button when you're satisfied with the settings. Pressing the <return> key also hits this button.
Ñ Cancel: Cick here if you've decided not to render the chosen file. Pressing the <esc> key also hits this button.
Ñ Create Targa output file: Check the box to create or continue rendering with an output file. Targa Output files are useful if you may need to interrupt or quit POV-Ray during the middle of a long rendering, or if you want to share a final output image with a less-fortunate (non-Macintosh owner) friend.
Ñ Continue tracing with Targa output: Click here if you rendered part of the image earlier with Targa output selected, and now want to resume where POV-Ray was interrupted. This option requires that the option ╥Create Targa output file╙ be checked as well.
Ñ Image width, height: Choose the dimensions (in pixels) of the image you wish to render. Larger dimensions require more memory; you should increase POV-Ray's Application Memory size if you work with very large (640 x 480 or larger) pictures.
Ñ From, To: If you don't want to render the entire image, these fields let you choose the top and bottom lines between which POV-Ray will render. A utility may be available someday to let you render partial images quickly on several Macs, then combine them into a single image. These options will let you use POV-Ray in conjunction with a network of Macintoshes, if available, to improve your rendering times. In the meantime, this is useful if you need to see one area of a scene, but don't want to wait for the whole image to render.
Ñ Quality: Choose the image's rendering quality. See the POV-Ray documentation for more detail on this option. 9 is highest quality, 0 is lowest. Settings lower than 9 will render a little faster, but degrade image quality drastically. It's recommended to leave the quality at 9 unless you absolutely need the higher speed.
Ñ Antialiasing: Check this box to use antialiasing, a technique which combines several samplings of the scene for each final output dot. Simply put, antialiasing smooths out rough edges and ╥jaggies╙, the stair-step pattern that occurs when an edge is tilted in the scene. Turning this on can slow down rendering by a large factor (up to 16 times slower in the worst cases!) but is considered essential for a high quality photo-realistic result.
Ñ Antialias Threshold: a value from 0.00 to 1.00 should be used to determine when anti-aliasing ╥kicks in.╙ During rendering, the current dot being rendered is compared with surrounding dots. If the color value difference exceeds this threshold (a sharp edge is found, for example,) anti-aliasing is used to calculate the dot more accurately. A value of zero fully anti-aliases the entire image. Values larger than 0.5 won't help image quality much. Adjusting this value lets you trade off rendering speed versus anti-aliasing quality.
POV Preferences
----------------------
Most of these options are the same as the File options above, and are used as the defaults if the file does not have its own settings. The additional options are listed below:
Ñ Background friendliness. Change this number to lower values for better cooperation with other programs, or higher if you want quicker rendering times. This value can be changed during rendering if you're not getting the kind of results you want. In general, a value of 2 or 3 will give you good results while still remaining background friendly. Set this value to its maximum of 15 if you're rendering a slow image and aren't using the computer for anything else at all. Set background friendliness to 1 if you're need to use your other applications with absolute minimum interference from POV-Ray.
Ñ Library search paths: This is a list of volume and folder names to look for included images or data files in. The path name should list the name of the disk, and the name of the folders within the disk, separated by the colon character (":"). For example:
Big Mac:POV.Includes
refers to the folder ╥POV.Includes╙, and the hard disk ╥Big Mac╙ which holds it. If you were to use this example, POV-Ray will search inside the ╥POV.Includes╙ folder for graphics or data files associated with the file you're trying to render, and for the standard includes. Note that spaces ARE allowed in the names of folders or your hard disk. Place each folder on a separate line. It's usually a better idea to keep your project and included graphics and data files together in the same folder; the Library search paths shouldn't be used unless you feel comfortable with it, and it's part of your personal style.
When POV-Ray first creates its preferences, it also creates two library search paths. The first, ╥:::Includes:╙, tells POV-Ray to look two folders up from where your scene file is located (for example, two folders up from the BumpMap folder inside Level1) to find and use the "Includes" (Standard POV-Ray shapes and textures) folder. The second, ╥::Includes╙, tells POV to look one folder up to locate Includes (BasicVue.POV in the Level1 folder, for example, needs this.)
If you keep your scene files in their own folder right alongside the Level1, Level2, Level3 and "Include" folders, everything should work without a need to edit the Library search paths at all.
************
The Menus
************
Here's a short description of the menus in POV:
File Menu
---------
Ñ New: Creates a new empty text document for creating a source text file for POV-Ray. Before you can render a document, you must first save it to disk. Also, when you start POV-Ray (with no documents) it will open a new document.
Ñ Open: open a source file to render. Some file option settings will be read from a resource in the selected file, or POV-Ray default settings will be used if it's being rendered for the first time. This menu is not available while another image is still being rendered. Wait for the other rendering to finish first, save and close the file, then open the new file.
Ñ File Rendering Options: Brings up the options dialog to allow the settings to be changed for the currently opened source file. These options are then "attached" to the source file, and will be remembered the next time the file is opened for rendering.
Ñ Close: closes the open image's window. This doesn't dispose of the image data; a new window can still be opened (using the Image menu.)
Ñ Save: Saves any changes to the currently opened source file. If the file has not yet been saved to disk, you will be asked what to call the file first.
Ñ╩Save As: Lets you save a copy of the current file under a new name elsewhere.
Ñ Render: Kicks off the rendering process on the currently opened source file. The file is read and interpreted by the parser, and progress and any errors are displayed in a separate status window. If all is well, an image window is opened, and the output picture is rendered into it.
If your scene file has been changed but not saved before you choose this menu option, POV-Ray will ask you if you wish to save changes to the scene file. Answer with a click on "OK" if you're satisfied with the changes you made to the scene file and are ready to use them in a rendering.
Ñ Pause: Temporarily stops or resumes the rendering process. This menu is useful if POV-Ray is taking too much time rendering an image, and is interfering with a very important task in the foreground.
Ñ Stop Rendering: Permanently stops the current rendering process. This menu can't be undone -- there's no "resume rendering" function. Use this menu only if you wish to completely end the rendering process. If you were saving the file to Targa output, you could resume the rendering later if you chose the ╥Continue Rendering using Targa Output╙ option in the File Preferences.
Ñ Save image as PICT: Saves the rendered image as a PICT file. PICT files are the standard interchange format for Macintosh graphic images. If the option key is held when you choose this menu item, and the QuickTime INIT is installed properly, you will be asked to supply additional information for QuickTime image compression.
Ñ POV Preferences: Sets the application default preferences for newly created source files, and allows you to specify the "background friendliness" of POV-Ray, and set paths to search for include files. These preferences are saved in a file in your System Folder (Preferences folder in System 7.)
Ñ Quit: exits POV.
Edit Menu
---------
Ñ Undo: undoes an image enhancement (see below), or undoes the editing in the source file. Multiple undo of text edits is supported!
Ñ Copy: Copies the rendered image to the clipboard, to be pasted into other open applications.
Ñ Cut/Copy/Paste: Does the expected thing to the source file.
Ñ Go To Line: Lets you specify a line number, and jumps to that line in the source file.
Ñ Redo: reverses the action of an undo command, and restores the changes that were undone.
Settings Menu
-------------
The options in the Settings menu are recorded into POV preferences file when you select POV Preferences. This is the best time to change settings, because they'll be remembered for future use.
Ñ Dither image: uses 32 bit QuickDraw's "Dither" copy mode to draw the image. This option won't take effect on a 24 bit graphic display, because it's not necessary. On the other hand, this is the only viable option for a single bit monochrome display such as an SE/30 or PowerBook. Dithered images usually look much better, but may have a "grainy" appearance.
Ñ Shutdown when done: If this is checked (on) then when POV-Ray completes the current rendering session, it will save the image, and quit and send a "Shut Down" message to the Macintosh. Depending on the model of Macintosh, this may put up the "Ok to turn off your Mac" dialog, or actually turn off the power.
Image menu
-----------
This menu allows you to control the size of the window used to view the rendered image. "No Window" doesn't actually prevent the rendering process from happening, it just hides it (can speed up rendering a little.) You can always open a window if there's a rendered image present. It also allows enhancements to rendered images that are small enough to fit entirely in RAM. The functions are self-explanatory, and there's a "Revert" menu option that really should belong in the File menu. Play with the options and see how they affect the image. Image enhancement might be improved if there are enough requests for it. For now, export your images into Photoshop (which can read the Targa output files that POV-Ray can create) or Studio/32, and play with them there.
Photoshop has a cosmetic bug which causes it to ignore a vertical flipping flag in Targa files; therefore it loads POV-Ray images upside-down. Just Select All, then Flip Vertical. Nobody's perfect, but write letters to Adobe. It's not POV-Ray's fault.
View: Lets you show or hide the window, and magnify the displayed image.
Draw Border: Draws a black one-pixel border around the image. This is suggested if you are making a 32x32 Finder icon image.
Image enhancement choices let you make incremental changes to the image before saving it. The image enhancement functions only work if your image is small enough that POV-Ray didn't have to create a virtual memory buffer. All images smaller than 128x128 will fit in RAM without using virtual memory.
Revert to Rendered: Lets you throw away all your experimental enhancement changes, and restore the original image.
Credits
--------
This Mac front end was not created from scratch.. Jim Nitchals extensively modified an earlier version written by Thomas Okken, added the mini text editor and the virtual memory image swapping code, and the first version of the PICT file saving package. Jim also improved the POV-Ray multitasking and memory management to allow multiple renderings without quitting the program.
A few ideas were gleaned from a version built by Glenn Sugden.
Eduard [esp] Schwan ported the code from Think C and tested it in MPW C, revamped the user interface, added a generic status window that captured "printf"s for both Think and MPW, got the AppleEvent stuff to work, added QuickTime support, reworded this document, and bombarded Jim with late night calls, bug reports, source changes, and wild suggestions.
Jim would like to thank his wonderful wife and best friend, Cindy, for her support while he was coding and rendering many late nights. Thanks!
Eduard would like to thank Lorrie, Bryon, Sushi, and V.G.s (patient wife, impatient 4 year old son, oblivious lap cat, and super donut shop) for sticking around while the bugs and pixels were thickest.
Jim wishes there was a VG.'s nearby. They DO make the best donuts and also baked Cindy's and his wedding cake.
Thanks in advance to the testers who'll be beating up this version.
Encore.. more info please!
-----------------------
(0) POV-Ray creates two special types of files during its operation. The first is "POV-Ray Prefs", which will be put inside your system folder, and the Preferences folder if you use System 7. It should be left there, as it stores important preference information. The other file is called "POV-Ray.imageTemp", which is only used during rendering of large images. It can be deleted if POV-Ray is NOT running and somehow the file was left around.
(1) Refer to the POV-Ray documentation for general information on the scene description language, and general theory of operation.
(2) Join Compuserve's COMART forum for support on POV-specific items.
(3) For Macintosh-specific issues, please contact one of us directly:
Jim Nitchals can be reached on:
Compuserve: 73117,3020
America Online: JimN8
Internet: jimn8@aol.com
When mailing me questions via Internet, I'd like to assume that your question can be posted publicly in online forums along with my reply. This way others can benefit from your experience. If you don't want your question posted publicly, no problem. Just say something. Please use my AOL Internet address and not my Compuserve address. Compuserve surcharges Internet mail and AOL doesn't (yet.)
Eduard [esp] Schwan can be reached on:
AppleLink: JL.MacTech
Internet: jl.mactech@applelink.apple.com
WWIVNet: 261@6952 (Dead Zone)
(4) There will be online support for POV-Ray in America Online's Company Support area of the PC Graphics and Mac Graphics forums (keywords: "PGR" or "MGR") as soon as POV-Ray 1.0 is released to the public.
