Index
POV-Ray for Windows™ documentation

Other Help Files

Main POV-Ray Documentation

Introduction

What is POV-Ray for Windows™ ?

Who can use POV-Ray for Windows ?

Internet URL's

Getting Started

The Editor

Internal Editor Reference

Basic Knowledge

The POV-Ray Windows

Understanding File Types

Understanding POV-Ray Options

Special Command-Line Options

The Menus

File Menu

Edit Menu

Insert Menu

Render Menu

Options Menu

Tools Menu

GUI Extensions Menu

Shortcut Menus

Misc

Bug Reports

Speed Considerations

System Requirements

CDROM's

Copyright

POV-Ray Legal Document


What is POV-Ray for Windows?
What is POV-Ray for Windows™?

POV-Ray for Windows™ is the Microsoft Windows version of POV-Ray version 3. POV-Ray™ is short for the Persistence of Vision™ Raytracer, a tool for producing high-quality computer graphics. POV-Ray™ is copyrighted freeware, that is to say, we, the authors, retain all rights and copyright over the program, but that we permit you to use it for no charge, subject to the conditions stated in the file povlegal.doc. You can view this file by bringing up the POV-Ray for Windows about box by using the Help menu or Alt-B and selecting the appropriate button, or you can read it by clicking here.

Like POV-Ray itself, POV-Ray for Windows is a ray tracer. It renders deceptively simple scene files into astonishing graphics. For an extensive discussion of the POV-Ray 3 Scene Description Language, see the POV-Ray Documentation. For a quick demonstration of POV-Ray for Windows, start up the program by selecting Run Demo from the Render menu.

(....And What Is It Not?)

POV-Ray for Windows is not a modeller. It will not let you design scenes graphically on-screen. There are several shareware and freeware programs available for this purpose. To write or modify POV-Ray scenes you just edit the actual text file containing the commands.

Spelling

Some US Residents have commented on the spelling of some words such as colour, initialisation, and minimised (they expect color, initialization, or minimized). POV-Ray is an international effort and as such our spelling sometimes conforms to British, European, or Australian, rather than American, English. This is particularly the case in this document.

BUG REPORTS

There is a section in this help file for bug reports. Make sure that you Read it before sending us a complaint/bug report !

This Is Not the POV-Ray Documentation.

One final note - this help file is not the POV-Ray documentation. It only tells you how to use the Microsoft Windows-specific portions of POV-Ray. The POV-Ray documentation itself is a separate file, accessible from the Help menu using the ’POV-Ray Documentation’ entry or by clicking here.

TRADEMARKS

The terms ’POV-Ray’, ’Persistence of Vision Ray Tracer’, ’POV-Team’, ’POV-Help’ and 'POVWIN' are trademarks of the Persistence of Vision Development Team.

’Windows’, ’Microsoft Windows’, ’Windows 95’ and ’Windows NT’ are trademarks of Microsoft Corporation. All other trademarks are acknowledged as being the property of their respective owners.


Who Can Use POV-Ray for Windows?

This is the good part: anyone can use POV-Ray for Windows. If you have never seen a ray tracing program before, you can have great fun just rendering the amazing sample scenes and animations installed together with POV-Ray for Windows. Once you have studied some scene files and spent a little bit of time reading this Help file and the POV-Ray 3 documentation, you can start putting basic scene files together. The way a few simple commands can generate a terrific image that will astound you.

Remember, though, that you do need to invest some time getting to know the program. For instance, you do not have to worry about most of the POV-Ray settings at first, but some of them are critical. Ignore them and POV-Ray for Windows may not do what you expect. The default settings have been selected so as to be satisfactory in the large majority of cases, but sometimes they will not give you what you want. Don't give up. The solution is bound to be a simple one, as long as you take the time to read the documentation. Investing a little bit of time getting to know the program will pay off - guaranteed!

As for experienced POV-Ray users, you will find POV-Ray for Windows makes life much easier. Working under Windows means you can edit one scene while rendering another and modifying the INI file of a third. This feature, combined with the File Queue option (see Render menu), lets you speed up the scene generation cycle considerably while leaving you the option of doing some 'serious' work at the same time!.


Internet URL's
Internet URL’s

The Internet

If you have a web browser installed and configured, clicking Here should load it and take you to our Web site, www.povray.org. [This may not work on all systems, depending on the configuration of your internet software, and you may need to dial up first.]. If nothing happens when you click the link then it most likely is not supported with your current web browser.

Here are some links that may be of interest -

The latest versions of the POV-Ray Official Files.
The POV-Ray News Server
The bi-monthly Internet Ray Tracing Competition (IRTC).


Getting Started

The Demo

If you have never seen POV-Ray at work before, start by running the demo (select Render/Run Demo), then click on Start Rendering. You will see POV-Ray for Windows start up a Render Window and generate a sample scene line by line. Notice that if you close the Render Window by double-clicking on the system icon in the top-left corner, the rendering job is not interrupted. If you have POV-Ray set up to save the image as a file (see Understanding POV-Ray Options), that file will be produced whether or not you display the image on screen as you render. To stop rendering, select Render/Stop Rendering.

Even if you minimize the rendering window, POV-Ray for Windows will display the progress of the rendering job by showing the percentage completed. If you close the render window and want it back, click the right mouse button over the main POV-Ray window, and select the appropriate menu item.

Starting a Render Job

Starting POV-Ray rendering any scene file is as simple as selecting the file through the menu (Render/Select File and Render) or dragging and dropping it from the Windows File Manager or Explorer. This will work with either a POV file or an INI file (as long as it has an associated POV file. See Understanding File Types). The scene is rendered with the current POV-Ray 3 options (see Understanding POV-Ray Options). The above assumes, of course, that you have the Options|Drag'N'Drop destination set to Renderer. If it is set to Editor, the file will be opened in the editor window instead.

NOTE!!! One of the most common errors new users make is turning off the display option. The Display option (+d) is ON by default. If you turn this OFF in the INI file or on the command line, POV-Ray will not display the file as you render, no matter how many times you press the Show Render Window button.

Also note! POV-Ray will write the output file to a .BMP by default. There is no way to 'save the render window' after rendering is completed.

Dragging and Dropping

Dragging and dropping from File Manager has the advantage that you can select more than one file at a time. You can drag and drop up to 512 POV and/or INI files. POV-Ray for Windows will start processing the first file in the queue and add the rest to the queue (see File Queue in the Render Menu).

Note that if the Drag'N'Drop Destination is set to Editor, the files will be opened in the internal editor instead. In that case, there is a limit of 32 files (total) that may be opened.


The Internal Editor

How to turn the internal editor on or off

Select the Options|Other Settings|Use Editor menu item. If the editors failed to load on startup, then this may have been turned off for you already. You should turn it on if you want to try loading the editors again, because, if you don’t, POV-Ray for Windows will never use the editor, even if you re-start it.

An important note

The internal editor on POV-Ray for Windows consists of two parts - a custom control (CodeMax from WinMain software - http://www.winmain.com/), and the 'wrapper' code that encapsulates it. It's important that you remember this, as it will explain some of the behavior that it exhibits (for example, not being able to reassign all keystrokes, just most of them).

The CodeMax Window

The CodeMax Feature Set

Color Syntax Highlighting.
Language-specific keywords, comments, and strings are colored differently to set them apart from plain text.

Fully Customizable Keyboard Mappings.
Keystrokes can be added and removed to emulate popular keyboard mappings, like Brief and Epsilon.

Keystroke Macros.
Users can record a series of keystrokes and assign a keystroke to play back the keystrokes repeatedly.  Up to 10 macros may be recorded.

Drag and Drop Text Manipulation.
Highlighted text can be dragged and dropped between any window supporting OLE text Drag and Drop.  Text may be copied or moved.

Multiple Split Views.
Users can create up to four separate views of the same edit buffer.  Each view can be scrolled independently.

Unlimited Undo/Redo.
All edit actions are fully undoable and redoable.  A limit can be set on the number of edit actions that may be undone.

Auto Indentation.
Once a language is chosen, as the user enters code, CodeMax will automatically indent lines to following the scoping rules of the language.

Column Selection and Manipulation.
Columns of text can be selected with the mouse and then manipulated.  Empty columns (columns with a width of zero characters) can be selected, causing subsequent typing and deletion to occur over multiple lines at the same time.

Over 120 Separate Edit Commands.
More than 120 separate edit commands can be assigned to a keystroke.

Using the Mouse

CodeMax supports the following mouse actions:

Mouse Action:	Result:
L-Button click over text	Changes the caret position
R-Button click	Displays the right click menu
L-Button down over selection, and drag	Moves text
Ctrl + L-Button down over selection, and drag	Copies text
L-Button click over left margin	Selects line
L-Button click over left margin, and drag	Selects multiple lines
Alt + L-Button down, and drag	Select columns of text
L-Button double click over text	Select word under cursor
Spin IntelliMouse mouse wheel	Scroll the window vertically
Single click IntelliMouse mouse wheel	Select the word under the cursor
Double click IntelliMouse mouse wheel	Select the line under the cursor
Click and drag splitter bar	Split the window into multiple views or adjust the current splitter position
Double click splitter bar	Split the window in half into multiple views or unsplit the window if already split
Default Keyboard Mappings

Listed below is the complete set of default keystrokes and the CodeMax command that each keystroke maps to:

Command	Keystroke
BookmarkNext	F2
BookmarkPrev	Shift + F2
BookmarkToggle	Control + F2
CharLeft	Left
CharLeftExtend	Shift + Left
CharRight	Right
CharRightExtend	Shift + Right
Copy	Control + C
Copy	Control + Insert
Cut	Shift + Delete
Cut	Control + X
CutSelection	Control + Alt + W
Delete	Delete
DeleteBack	Backspace
DocumentEnd	Control + End
DocumentEndExtend	Control + Shift + End
DocumentStart	Control + Home
DocumentStartExtend	Control + Shift + Home
Find	Alt + F3
Find	Control + F
FindNext	F3
FindNextWord	Control + F3
FindPrev	Shift + F3
FindPrevWord	Control + Shift + F3
FindReplace	Control + Alt + F3
GoToLine	Control + G
GoToMatchBrace	Control + ]
Home	Home
HomeExtend	Shift + Home
IndentSelection	Tab
LineCut	Control + Y
LineDown	Down
LineDowNextend	Shift + Down
LineEnd	End
LineEndExtend	Shift + End
LineOpenAbove	Control + Shift + N
LineUp	Up
LineUpExtend	Shift + Up
LowercaseSelection	Control + U
PageDown	Next
PageDowNextend	Shift + Next
PageUp	PRIOR
PageUpExtend	Shift + Prior
Paste	Control + V
Paste	Shift + Insert
Properties	Alt + Enter
RecordMacro	Control + Shift + R
Redo	Control + A
SelectLine	Control + Alt + F8
SelectSwapAnchor	Control + Shift + X
SentenceCut	Control + Alt + K
SentenceLeft	Control + Alt + Left
SentenceRight	Control + Alt + Right
SetRepeatCount	Control + R
TabifySelection	Control + Shift + T
ToggleOvertype	Insert
ToggleWhitespaceDisplay	Control + Alt + T
Undo	Control + Z
Undo	Alt + Backspace
UnindentSelection	Shift + Tab
UntabifySelection	Control + Shift + Space
UppercaseSelection	Control + Shift + U
WindowScrollDown	Control + Up
WindowScrollLeft	Control + PageUp
WindowScrollRight	Control + PageDown
WindowScrollUp	Control + Down
WordDeleteToEnd	Control + Delete
WordDeleteToStart	Control + Backspace
WordLeft	Control + Left
WordLeftExtend	Control + Shift + Left
WordRight	Control + Right
WordRightExtend	Control + Shift + Right
Introduction to the POV-Ray Editor

The POV-Ray internal editor is an advanced programmers editor, offering syntax highlighting for POV files (as well as C, Java, and a number of other languages), several indent styles, block indent/undent, column selections, OLE drag and drop, amongst other things. Most of the key mappings are configurable, as are the colors and a number of other options.

Note that the editor itself is implemented as two DLL's - cmedit.dll and cm101.dll. It is not essential for POVWIN's operation to have these present - it is quite possible for it to run without them. However, under normal circumstances, the editor is present.

Key mappings

Most of the keystrokes used by the editor are re-assignable - even those listed in the menus. (Some users had assumed that commands with shortcuts listed in the menus weren't assignable, but this isn't the case - if you change the assignment, the new shortcut shows up in the menu).

Each editor command can have up to two different keys assigned to it, and each key may have either one or two keystrokes. Most users will use only one keystroke, but those who are still familiar and comfortable with the old 'Wordstar' key assignments (e.g. Ctrl-Q, F for Find) will be pleased to discover that these are still available to them, should they want to take the time to assign them.

If you assign more than one keystroke to a command, and the command is one of those listed in the menus (not all commands are listed in the menus), the first keystroke assignment is the one that is listed in the menu as the shortcut key.

You can access the keystroke assignments via the CodeMax properties dialog. By default, this is mapped to Alt-Enter when a editor is displayed. Alternatively, you can get at it from the Editor menu (only visible when an editor is selected) or the editor RMB context menu.

IMPORTANT NOTE!!!

Not all commands are assignable ! Only the commands that are directly implemented in the CodeMax custom control are able to be set. These commands are ones that relate to operations on individual edit buffers. They do not include such things as file operations (load, save, print, etc). These operations are implemented in the POVWIN editor wrapper code and are not managed or able to be changed by CodeMax. Therefore, it should be clear that you can neither change the key bindings for operations such as file save, nor use the POVWIN-assigned keystroke (e.g. Ctrl-S in the case of save) for any other purpose.

Switching between Editor windows

You can use the Alt-LeftArrow and Alt-RightArrow keys to cycle amongst the editor windows and the message window.

Reserved Keys

The following edit-related keys and functions are implemented in POVWIN and are not available for modification via CodeMax. Do not use these keystrokes in the CodeMax key assignment dialog.

Save	Ctrl-S
Open	Ctrl-O
Close	Ctrl-F4
New	Ctrl-N
Print	Ctrl-P
Save As	Shift-Ctrl-A
Save All	Shift-Ctrl-V
Show Message Window	Alt-M

In addition, any keys used by other parts of POV-Ray for Windows may not be used in the editor, with the exception of the commands that only apply when the Message window is displayed (i.e. Ctrl-Ins for Copy Pane).

Match Brace

Several European users have commented that the default key assignment for 'Match Brace' (Ctrl-]) is not usable on their keyboards. Please note that you can change this to whatever you please (they assumed that it was not changeable when in fact it is).

Another thing to remember about the match brace command is that it only works if it is executed when the edit caret is on a brace character ('{', '}', '(', ')', '[', ']'). The caret will then jump to the matching character (e.g. if it's on a '(', it will jump to the matching ')').

Quick Rundown

Rather than attempt to document each and every command in the Editor menus (which consist of the right mouse button context menu, the Edit menu, the Text menu, and the Editor menu), we will cover only those issues that we feel you need to know. (We feel that most users don't need to be told that the 'Cut' command cuts text to the clipboard ...)

Even if you're someone who doesn't read documentation, please spend some time exploring the editor's menus ! Doing this will answer many of the questions posed to us in emails from users. If you're not sure what a menu option does, highlight it and look at the hint that appears in the status bar at the bottom of the window.

The editor is extensively customizable. It utilizes syntax highlighting and understands .POV and .INC files as being in POV syntax. You can change the color settings used from the properties dialog (ALT-ENTER). It also has built-in syntax highlighting for C, C++, Java, Basic, Pascal and SQL.

Here's a quick editor feature summary.

Syntax highlighting.

Keystroke macros. These are preserved across sessions.

Optional auto-save which, if turned on, saves changed files periodically.

Brace matching is available (cursor must be on a brace when you do it).

Block indent/undent

Tabify/untabify

Customizable colors.

Smart case preservation in replace operations.

Up to 10 bookmarks.

Optional auto-reload of changed files.

Multiple views of the one file (via splits).

OLE drag and drop between the editor and other programs.

Optional smooth-scrolling.

Intellimouse support.

Column selection (control-leftbutton and drag).

Up to 32 edit sessions.

MRU list also tracks the line, column, language, tab and indent settings.

You can split editor panes by dragging the little bar just above the top of the vertical scrollbar (and likewise for horizontal). This is only possible if it's not disabled via the properties dialog. Editor splits are not preserved across sessions (this is by design). You can drag and drop selected text between panes.

By default both scrollbars are on. You can change this from the properties or the Editor menu.

Note that the editor properties dialog only allows you to set things that are implemented within the editor. There are some other options implemented within the editor wrapper code in POV-Ray for Windows which are able to be accessed via the Editor menu (only visible when an editor is selected). For example, the keybinding for saving a file (Ctrl-S) is not listed in the editor properties since this function is handled by the wrapper code. You can't change this assignment.

Some properties only affect the current file, and some affect all files. Additionally, most (but not all) of those that affect the current file will become the default for any new files opened after that point. This is by design. For example, changing the tab stop setting only affects the current file, but will then become the default for new files from that point on.

You can drag and drop selected text between panes of the editor window, or between the editor and any OLE compliant drag and drop application, such as Microsoft Word. Control-dragging copies instead of cuts.

Some people have asked why the 'quit bugging me' option in the render save dialog is not persistent across sessions. This is by design and is not likely to change.

The RMB context menu has an option for 'show/hide message window' (as before, though many people didn't look closely enough to realize it). This window is now sizable (unlike the previous version, where it was a fixed size). A quick way to close this window is to drag the divider down to within a few pixels of the bottom border - when you release the mouse, the message window will vanish.

You can also tell POVWIN not to display the message window automatically when starting a render. You do this from the Editor menu, by turning off 'Auto-Show Parse Messages'. This is most useful with the Error File option.

POVWIN will now optionally automatically load a file in which a parse error has occurred into the editor (or select it if it's already loaded) and place the cursor on the line and column of the offending code. This is able to be turned on or off using the 'Auto-Load Error File' option in the Editor menu. Also, if this option is on, and the message window was displayed automatically (see above), it will be closed automatically rather than being left open (as used to be the case when an error happened). The text describing the error will be displayed in the status bar at the bottom of the window.

Understanding options

It's important to understand that many of the options that are accessible via the CodeMax properties dialog (Alt-Enter by default), apply to the current file only. Some, however, apply to all files, and some apply to the current file and all new files opened after that point. Confused yet ? ;). We'll explain more.

The Language Setting

The language setting is a good example of a setting that applies to the current file only. This setting determines what sort of syntax highlighting is applied to the file. For example, a POV or INC file would probably have a language setting of 'POV-Ray'. A Java file (should you choose to use POVWIN to edit one) would have a language setting of 'Java'.

This setting is initially (when you first open a file, or create a new one) set according to the file extension. .POV and .INC files are considered POV syntax. A new file (one with the name 'Untitled') has no language.

Once the file is first loaded, you are free to change the language to whatever you like. This change affects only the current file and no other file ! The change you have made will be remembered by POV-Ray. Any file that is still in the MRU list (or the 'Older File' list - see the File Menu section for more details) has its language setting stored along with a number of other attributes.

Note that if you open a file manually (using Drag-Drop or the file browse dialog, for example), the old settings are discarded, even if it was in the MRU list. This is by design.

The Tab Spacing Setting

The Tab spacing setting is a good example of a setting that applies to only the current file and to any new files opened after that point. Like the language setting, it applies only to the current file. That is, changing the tab spacing for one file does not automatically change it for all the other files that are already open. Like the language setting, a files tab setting is stored with the MRU list, so if you re-open a file from the MRU list, the old setting comes back.

Unlike the Language setting, however, the new value you apply to the tab value becomes the default for any file opened or created after that point (apart from those in the MRU list). So if you change the tab setting to, say, 3, the setting for the current file changes, but not that of any other open file. Any new file that you create or load from that point, however, will be created with a default tab spacing of 3.

The Font Setting

The Font setting is a good example of a global setting - it affects all open files. Once you change the font used in the editor, all open files get the new font, as well as any new files opened after that point.

Option Summary

In most cases it should be obvious whether an option is global or not. As a quick summary, the options in the 'Misc' tab of the CodeMax properties dialog are all global. The ones in the 'Language/Tabs' section are as explained above, except 'Convert tabs to spaces while typing', which is global, and 'Indent style', which is local and sets a new default. Those in the 'Color/Font' section are global. Finally, key assignments are obviously global to all editors (see the key assignment section above for caveats)

Backups

If the backups option is set (see 'Create Backups' in the Editor menu), the editor will create a backup file named the same as the original but with '.bak' appended to it the first time the file is saved in each edit session. Note that it is not created with each save, but only the first!

Also note that appending the '.bak' extension is meant literally - unlike editors that hail from the old 8.3 filename era, which would remove the old extension and replace it with .bak (e.g. 'foo.pov' would become 'foo.bak'), we literally append '.bak', such that 'foo.pov' becomes 'foo.pov.bak', thus avoiding the problem that having two files named 'foo.pov' and 'foo.inc' in the same directory would have caused.

Click Beyond EOL

The 'Click Beyond EOL' option (located in the Editor menu, and which by default is on) allows the editor caret to be positioned beyond the end of the line if you choose to left-click there with the mouse. This is the behavior that most users seem to want. However, a number of users have requested that the 'old' behavior (from the previous POVWIN editor, which did not allow the caret beyond the end of a line) be preserved.

If 'Click Beyond EOL' is turned off, and you left-click beyond the end of a line, the editor caret will snap to the location after the last character on the line. You can still manually (using the cursor keys) move the caret right past the end of the line, or down onto a new line (and thus be past the end of that line, if it were shorter) but that is beyond our control as it's implemented in the CodeMax control itself.

Auto-Reload

Auto-Reload (in the Editor menu, which by default is set to 'Ask') causes the editor to check the time and date of all files that are currently open when it receives focus from another application. For example, suppose you were using a program that automatically generates POV scene files (these are quite common) and had the output file open in POVWIN. If you switched to that application, told it to regenerate the output file, then switched back to POVWIN, the editor would detect that the file had been changed (assuming Auto-Reload is enabled).

The three settings available for Auto-Reload are 'Never', 'Ask', and 'Always'.

'Never' means never check - changes to a file made externally to POVWIN will not be detected and you risk overwriting the changes if you save the copy open in the editor.

'Ask' means that, if changes to a file are detected, POVWIN will ask you if you want it reloaded. If you reply 'Yes' and you have unsaved changes, they will be lost. Your undo buffer will also be cleared.

'Always' means that, if POVWIN detects that a file has changed, it will always reload it without asking you! If you have unsaved changes, they will be automatically discarded. Your undo buffer is also cleared.

If Auto-Reload is set to either 'Ask' or 'Always', be aware that switching focus to another application also causes all of your files to be automatically saved.

Warning

The auto-reload feature is not intended as a substitute for common sense. We do not guarantee that it will work. It is not always possible to determine if a file has changed (for example, the time stamp may not be updated by the other application) and apart from that, it takes time to save a file. If the other application is still in the process of saving the file when you switch back to POVWIN, it's possible that the change won't be picked up. Likewise if POVWIN is still saving the file when the other application is selected ; for example, if it is an editor with a similar feature, it may not pick up the change.

Nevertheless, Auto-Reload is a useful feature under most circumstances.

Color Scheme

The colors used by POVWIN's editors are able to be customized by you on a case-by-case basis. However, for convenience, there are two built-in color schemes accessible from the Editor menu. These are 'Black on White' (the default) and 'White on Black'.

Black on White is the traditional Windows style of presentation, with black text being drawn on a white background.

White on Black is the other way around - a black background with white text. Many users who became accustomed to using text editors under DOS will be comfortable with this.

Note that choosing one of these options will overwrite any changes you had made to your color scheme ! Once you have chosen a new scheme, you may customize it from that point.


The Povray Windows
The POV-Ray Windows

The Main Window

The left part of the status bar on the main window contains a information and help field. Next to the help field in the status bar you will find a Pixel-Per-Second indicator; and a clock showing time elapsed (in days-hours-minutes-seconds) since the beginning of the last render job. This clock stops when the job completes.

The Message Window

You can change the background of the message window, along with its font and font color, from the Options|Message Window menu.

The Render Window

The Render Window pops up whenever you render a scene with the POV-Ray 3 display option (+d) set. This option is set ON by default in POV-Ray for Windows.

The Render Window shows the scene as it is being rendered. It also has its own Shortcut Menu.

If you close the Render Window you can re-display it by selecting Re-display from the Render Window submenu in the Options Menu.

WARNING: just because you can see the image in the Render Window does not mean it is being saved to disk, or that it can be saved to disk. In many cases the data stored for display purposes is different than the data stored in an output file. If you don’t have Output_To_File switched ON (see the POV-Ray Documentation for more details) then you will not get an output file and once the render is finished it is too late. If you want an output file you must select it before you start rendering. Output to file is set to default on when POV-Ray is installed.

Don't forget that if you chose, during installation, to have images written to a default directory, then that is where they will be unless you override this behavior. If you didn't select this option then the file will be written to the current directory. Specifying an output file name that consists of only a path, such as c:\images\, will cause the output file to be written to that directory. POV-Ray determines if the filename is a path by looking at the last character and making sure that it is a '\'. Note that the directory must already exist. [The exception to this is during installation ; the directory specified then will be created by the installation program.]

NOTE that to disable the Render window, you must specify the ’-d’ option on the command-line, or the text ’Display=Off’ on the command-line or in one of the INI files processed. Simply closing the render window after it is created does not free up the memory used by it.

If you are running a high-resolution render, and have a high-color or true-color display, you can save a considerable amount of RAM by turning the render window off. Users of 8-bit display systems can save a smaller amount. The amount of RAM used by the render window can be calculated as render width * render height bytes, in the case of 8-bit displays, or render width * render height * 3 bytes, for high/true color displays.

If you have a high or true color display, selecting the Options|Render Window|Force 8-bit Display option will cause only one-third of the memory to be allocated for the render bitmap, since the data will be stored as 8-bit pixels instead of true-color (24-bit).

System Tray

Pressing ALT-W or selecting ‘Minimize into the system tray’ from the Options menu will place POVWIN™ into the Windows 95/NT System Tray. Just double-click on the icon to restore it. You can right-click to get a context menu while it is in the tray.

See also Speed Considerations


Understanding File Types

POV Files

POV-Ray for Windows works with two types of plain text files. The first is the standard POV-Ray scene description file. Although you may give files of this type any legitimate DOS name, it is easiest if you give them the .POV extension. In this Help file, scene description files are referred to as POV files.

The second type, the initialization file, is new to POV-Ray 3. Initialization files normally have .INI extensions and are referred to in this help file as INI files.

INI Files

An INI file is a text file containing settings for what used to be called POV-Ray command-line options. It replaces and expands on the functions of the DEF files associated with previous versions of POV-Ray. You can store a default set of options in the file called POVRAY.INI in the INI directory under the POV-Ray for Windows home directory. Any other INI file you can pass to POV-Ray for Windows by selecting it (through Render/Select File and Render) or by dragging it from the Windows File Manager and dropping it onto the POV-Ray window.

One of the options you can set in the INI file is the name of an input file. You can specify the name of a POV file here. If you now activate the INI file, the POV file referred to will be processed with the settings specified in the INI file. This way you can customize POV-Ray settings for any individual scene file.

For instance, if you have a file called SCENE.POV, you can create a file SCENE.INI to contain settings specific for SCENE.POV. If you include the option 'Input_File_Name=scene.pov' and activate SCENE.INI, POV-Ray will process SCENE.POV with all the stipulated options.

Remember, though, that any options set at the POV-Ray for Windows command line when you activate an INI file override any corresponding options in the INI file (see Understanding POV-Ray Options and Render Menu). Also, any options you do not set in the INI file will be taken as last set by any other INI file or as originally determined in POVRAY.INI.

You can instruct POV-Ray to generate an INI file containing all the options active at the time of rendering. This way, you can pass a POV file and its associated INI file on to another person and be confident that they will be able to generate the scene exactly the same way you did. See the POV-Ray 3 documentation for details.

Sections

Sections are not files in themselves; they are portions of INI files. Sections are a means of grouping multiple sets of POV-Ray options together in a single INI file, by introducing them with a section label. Consider the following INI file, taken from the POV-Ray 3 documentation:

  ; RES.INI
  ; This sample INI file is used to set resolution.

  +W120 +H100  ; This section has no label.
               ; Select it with "RES"

  [Low]
  +W80 +H60    ; This section has a label.
               ; Select it with "RES[Low]"

  [Med]
  +W320 +H200  ; This section has a label.
               ; Select it with "RES[Med]"

  [High]
  +W640 +H480  ; Labels are not case sensitive.
               ; "RES[high]" works

  [Really High]
  +W800 +H600  ; Labels may contain blanks

If you select this INI file, the default resolution setting will be 120 x 100. As soon as you select the [High] section, however, the resolution becomes 640 x 480. See Edit Settings/Render in the Render Menu for instructions on selecting sections.

For more information on POV-Ray options and INI files consult the POV-Ray Documentation.


Understanding POV-Ray Options

Options are what previous versions of POV-Ray used to refer to as command-line options. The term is no longer accurate for POV-Ray 3, because the command line is only one way of passing options to the program. There are now four ways you can pass an option to POV-Ray:

  You can store it in the POVRAY.INI file in the POV-Ray 3 RENDERER directory. This is a special INI file (see Understanding File Types). Whenever you start up POV-Ray for Windows, the program looks for a file called RENDERER\POVRAY.INI in the POV-Ray 3 home directory. This means POV-Ray for Windows always starts up with the settings defined in POVRAY.INI. If you want to make changes to the way POV-Ray works by default, you should make them in POVRAY.INI. The Tools menu contains an entry to edit the master POVRAY.INI.

  You can store it in a POVRAY.INI file in the current directory. POV-Ray looks for a POVRAY.INI file in the current directory whenever it starts rendering, but after it has read any POVRAY.INI file in the POV-Ray 3 RENDERER directory. Options in an INI file in the current directory override options in any copy of POVRAY.INI in the POV-Ray 3 home directory.

  You can store it in an INI file created for a particular scene. If you drop a specific INI file into the POV-Ray window, any options set in it will override corresponding options in previously activated INI files (including POVRAY.INI). Any options not included in the INI file will be unchanged, that is to say, they will remain as the master POVRAY.INI set them.

  You can enter it on the command line (see Render Menu). Any command-line option overrides corresponding options in either POVRAY.INI or any other INI file loaded during the current session. POV-Ray for Windows interprets the command line from left to right, so that any option (or INI file) on the command line overrides a corresponding option (or another INI file) to its left on the command line.


Special Command-Line Options

POV-Ray for Windows supports several special command-line options not recognized by other versions.

The /DEMO command tells POV-Ray to run its demonstration render. All other options on the command-line are ignored.

The /EXIT command tells POV-Ray to perform the render given by the other command-line options, combined with previously-set options such as internal command-line settings, INI file, source file, and so forth, and then to exit. By default, if this switch is not present, POV-Ray for Windows will remain running after the render is complete. This switch only applies to renders started by other options on the command-line. It will not affect renders started manually from within POV-Ray for Windows itself.

The /NR command (same as /NORESTORE) tells POV-Ray for Windows to not attempt to restore any previous edit sessions (i.e. files that were open in the editor). This is handy when you had a large number of files open and you don't want them taking up time loading.

The /RENDER command tells POV-Ray for Windows to render the file following. Only one /RENDER command is permitted on the command-line. Wildcards are not permitted.

The /EDIT command causes POV-Ray to load the following file into an editor. You can have multiple /EDIT commands on the command-line (with one file per /EDIT command). The filenames may not contain wildcards.

Note that in all the above cases, if you are using an operating system that supports long filenames (such as Windows 95), and the filename has spaces in it, then you will need to enclose the filename itself within quotes.


File Menu

NOTE

In the interest of brevity, we will not explain 'obvious' file menu entries. We assume that all readers will understand 'Save', 'Save As', etc.

New File

This creates a new file in a new window in the internal editor. The language type will be set to 'none', so unless you change this from the editor properties, syntax highlighting will not occur until you do a Save As.

Open File

This creates a new window in the internal editor and opens the specified file in it. POV-Ray will attempt to set the language type according to the extension. .POV and .INC files are assumed to be POV-Ray files and will have POV syntax highlighting. If you use a different file extension for POV source code, you can set the language type manually after you open it.

Note that POVWIN will not let you load more than one copy of the same file. If you attempt to load an already-loaded file, that file will be selected as the current file in the editor, but nothing else will happen.

Close All

This closes all files currently open in the internal editor.

Print

Provides a dialog that allows selection of printing options for the currently selected editor file (does not work with the message window). You can even choose two-up printing (that is, printing two pages on a single sheet of paper by splitting it down the middle).

Older Files

After files have scrolled off the bottom of the MRU (Most Recently Used) list that appears at the bottom of the File Menu, they will appear in the Older Files menu. The MRU list holds up to nine (9) files, the Older Files menu holds up to 32 additional files. If there are no files in the Older Files menu (such as when POV-Ray is initially installed), it will be disabled.

Exit (Alt+X)

This option lets you exit POV-Ray for Windows. If you have Save Settings on Exit selected, your current POV-Ray for Windows settings will be saved for your next session.

If you are using Windows 95/98 or NT 4, and you shut down your computer without exiting POV-Ray for Windows first, POV-Ray will load itself again next time you log in as the same user.

MRU List

The MRU (most recently used) file list holds up to nine (9) files. The Older Files menu (see above) holds up to 32 additional files. After a file scrolls off the bottom of the MRU list it goes into the top of the Older Files menu.

When you select a file from the MRU list, if it is already open in the editor, it is selected and moved to the top of the MRU list. Otherwise, it is opened and moved to the top of the list. The MRU list remembers several things about files, including the last line, column, and top line number, plus the tab, language, and indent settings. The comments in this paragraph also apply to the Older Files menu.


Edit Menu

Important Note

This menu will have different options depending on whether you have the Messages window or a file selected. This section only discusses the version shown with the Messages Window is selected. See the section on the Built-In Editors for a discussion of the Edit Menu when an editor is selected.

The Message Window shortcut keys for Cut, Copy, etc. have been changed to the newer Ctrl-C, Ctrl-V style. The old shortcuts (Ctrl-Ins etc.) will still work, however, even though they're not shown in the menu.

The shortcut keys assigned when the Editor Windows are selected are set according to your preferences. See the Built-In Editors section for more information as to how to do this.

Copy pane

This command lets you copy all the text currently displayed in the POV-Ray window to the clipboard. From there you can paste it into any text file for modification with a text editor or word processor. This can be particularly useful for bug reporting. Note: This option only appears if the currently selected window is the Messages window.

Clear Messages

Clears all messages in the Message Window.


Insert Menu

The Insert menu allows you to insert header sections, object definitions, etc. into a file you are editing with the internal editor with only a few clicks of your mouse.

This menu is built dynamically from the directory called 'Insert Menu', which is in the POV-Ray for Windows installation directory. The way it works is similar to the Windows 95/NT Start Menu. You can even edit it at run-time, and POVWIN will automatically pick up the fact that it's been changed and re-load it.

Each sub-menu in the Insert Menu is a directory (also called a 'folder' these days). To create a new sub-menu, just create a new directory. The submenu will have the same name as the directory. Note however that an empty directory (one that has no subdirectories or text files in it) will not appear in the Insert Menu.

The actual items that you can insert in your scene files are simply text files. POVWIN recognizes them by the extension .TXT. Any .TXT file in the Insert Menu directory tree will appear in the Insert Menu. The name shown in the Insert Menu will be the filename of the .TXT file, minus the .TXT extension. If you select this file from the Insert Menu, the contents of the corresponding text file will be inserted into your scene file at the current cursor location.

The easiest way to understand how it all fits together is to inspect the Insert Menu directory that ships with POV-Ray for Windows. The first item in the Insert Menu will allow you to do that by opening an Explorer window located at that point on your disk.

Here's a short example of part of the Insert Menu directory tree that ships with POVWIN.

|--Animation

   |--clock.txt

|--CSG operations

   |--difference.txt

   |--intersection.txt

   |--inverse.txt

   |--merge.txt

   |--union.txt

|--Expressions

   |--Built-in Ids.txt

   |--Math Operators.txt

   |--Relational Operators.txt

   |--Strings.txt

   |--Vector components.txt

|--Headers

   |--Additional includes.txt

   |--Scene File Header.txt

   |--Standard includes.txt

|--Light sources

   |--area light.txt

   |--Cylindrical light.txt

   |--light definition.txt

   |--looks_like.txt

   |--Point light.txt

   |--Spotlight.txt

|--Misc. Directives

   |--declare.txt

   |--default.txt

   |--if example.txt

   |--if.txt

   |--ifdef example.txt

   |--ifdef.txt

   |--Messages.txt

   |--switch example.txt

   |--switch.txt

   |--version.txt

   |--while.txt

|--Ready-Made Scenes

   |--Basic scene.txt

   |--Checkered floor.txt

   |--Image Map.txt

   |--Text Fonts.txt

|--Shape modifiers

   |--bounded_by.txt

   |--clipped_by.txt

   |--hollow.txt

   |--interior.txt

   |--media.txt

   |--no_shadow.txt

   |--open.txt


Render Menu

Edit Settings/Render (Alt+C)

This command lets you select an INI and/or a POV file and make any last-minute command-line changes to the POV-Ray options before rendering.

In the 'Ini file' box, you can select an INI file by typing in the filename. You can also browse your directory structure for it. POV-Ray for Windows remembers the last directory from which an INI file was actually selected. If you select an INI file that has sections (see Sections in Understanding File Types), the Section box shows the first section label. Clicking on the down arrow brings up a menu of other sections in the INI file for you to choose from.

In the 'Source file' box, you can select a POV file by typing in the filename. You can also browse your directory structure for it. Once again, the directory that shows up is the last directory from which a POV file was actually selected.

If you currently have an editor window selected, you will not be able to change these entries as they will be set to the name of the file you are editing (even if its extension is not .POV). If you want to use these fields you need to choose the Message window first.

The commands are processed from top to bottom. Any options in the INI file you select override the default POVRAY.INI file as well as any POVRAY.INI file in the directory where the scene file resides. A selected POV file overrides any 'Input_File_Name=' option in the selected INI file. Finally, any command-line options override corresponding options in any INI file. The command line is processed from left to right; if an option is repeated on the command line, the one last processed applies.

If you want to change the command-line settings but do not want to start rendering the currently loaded POV file, press Set but don't Render.

The command line is versatile. If you have a POV file and a number of options loaded, you can override the scene to be rendered by typing the name of another POV file on the command line. Conversely, you can type in one or more options (or the name of an INI file), forcing POV-Ray for Windows to render the currently loaded POV scene with the new options. If you type the name of an INI file which specifies a new POV file with the 'Input_File_Name=' option, the current scene file as well as the current options are overridden. See also Understanding File Types.

Select File and Render (Alt+S)

This is the way to select a file from disk for immediate rendering. If the file is a POV file, it is rendered with the current options. If it is an INI file with no POV input file specified, the options will apply to the currently loaded POV file, only to be overridden by command-line settings. If the INI file specifies a POV input file, that POV scene is rendered with the options set in the INI file. See also Understanding File Types.

Start Rendering (Go!)/Stop Rendering (Alt+G)

This is a toggle. If you are not currently rendering, the command Start Rendering instructs POV-Ray for Windows to start rendering the currently loaded POV file with the current settings. While POV-Ray for Windows is rendering, the command reads Stop Rendering and will interrupt the current rendering job. You can continue an interrupted rendering job by selecting Continue <filename> from the Rerun Menu

Run Demo

The easiest way to see what POV-Ray for Windows is capable of is selecting this command, which renders a sample POV-Ray file to screen. To interrupt rendering, select Render/Stop Rendering or double-click on the drawer icon in the top left-hand corner of the rendering window. See also Getting Started.

File Queue (Alt+Q)

Selecting this command lets you look at the queue of files ready to be processed. You can add a file to the bottom of the queue or delete a file (you have to select it first by clicking on it). Once you have made your changes to the file queue, press OK to confirm the changes or Cancel to leave the queue as it was before you called up the screen. You can select multiple files in the file browse dialog box by using Control or Shift when clicking on them.

The File Queue dialog box has two checkboxes in addition to the normal controls (like add/remove file etc.)

The first, Reload on Startup, when selected, causes the contents of the file queue to be stored to disk each time it is accessed. When POV-Ray is started up with this option active, and the file queue had entries in it, they are loaded off disk and back into the queue. If Auto Render was also selected, POV-Ray would then start rendering them.

The second, Auto Render, instructs POV-Ray for Windows to render whatever is in the file queue (see File Queue below). When you switch Auto Render off, any files dropped onto the POV-Ray window are added to the queue but not rendered. In other words, while Auto Render is turned off, the file queue is inactive. However, any file selected with the Render/Start Rendering command will still be processed. Once you switch Auto Render back on again, if there are files in the queue, they will begin to be processed.

NOTE that due to the way that some versions of Windows returns multiple file selections to us, if you use Ctrl or Shift to select more than two files in the Add to Queue file browse box, and then click on OK, the first and last entries will be transposed.

Clear Queue (n entries)

If you want to clear the entire queue in one go, this is the way to do it. The command shows you how many entries you will be throwing away.

Animation

Animation|Minimize Shellouts

The Minimize Shellouts options tells POV-Ray to run any specified shell-out in a minimized, non-active window. This can be important if you are doing some work in the foreground and do not want to be interrupted. Note that the command that you are starting must be capable of running in the background under Windows.

SUGGESTION - if you are running external DOS processes, you should consider creating a PIF file (see your Windows documentation) and running that instead. Then you will have more control over the way the program operates.

Animation|No Shellout Wait

If you specify a post-scene shell-out command in an INI file, POV-Ray for Windows hands over to the program specified. If you are running Windows 3.1x and Win32s, POV-Ray for Windows has no way of telling when the program shelled out to has finished, especially if it was a DOS program. All POV-Ray can do is show a screen explaining this and ask you to click the OK button when the external program has completed or if you don't want to wait for it to finish. If you do not want POV-Ray to display this message, select No Shellout Wait.

NOTE it is very important to note that if POV-Ray doesn't wait for the program, it must return immediately. If it returns immediately then obviously the programs return code cannot be monitored. In this case the return code will always be 0.

GUI Priority and Render Priority

These two submenus are related. The higher the GUI Priority, the more responsive POV-Ray for Windows will be. The higher the Rendering Priority, the more resources are devoted to rendering.

See also Speed Considerations.

On Completion

The On Completion submenu allows you to specify what POV-Ray will do when it completes a rendering.

On Completion|Do Nothing

No special actions are taken.

On Completion|Beep

POV-Ray for Windows can give an audible alert when it has finished a rendering job. The sound produced is a WAV file associated with the asterisk in the 'Sound' section of the Windows Control Panel. As with all other WAV files, this only works if you have a sound card. Without a sound card you will hear Windows produce a short beep through your PC speaker.

On Completion|Display Message

This will cause POV-Ray for Windows to display a message window indicating that it has finished.

On Completion|Beep and Display Message

This will cause POV-Ray for Windows to both beep and display a message window indicating that it has finished.

On Completion|Exit POV-Ray for Windows

POV-Ray for Windows will exit after the render has completed.

Rerun

This menu option brings up a sub-menu with the following options: Rerun Dialog ; Rerun filename ; Continue filename ; and a list of files. Some of the above will not be visible under some circumstances ; see below.

Rerun|Rerun Dialog (Alt+N)

Selecting this command brings up a list of the last rendering jobs performed (up to 16). You can select any one of them by clicking on it. You then have the option of rendering the job with the same POV-Ray settings used for the original job or viewing the rendering statistics for that job. If you select Render, you are shown the current render settings, which override any settings that the file was originally rendered with. See Edit Settings/Render in the Render Menu. See also Understanding POV-Ray Options.

Rerun|Rerun filename

This command, like the following, is only displayed if you have interrupted rendering of a scene (by selecting Stop Rendering from the Render Menu). The command shows the name of the interrupted file, and selecting it instructs POV-Ray for Windows to re-render the scene from the start.

Rerun|Continue filename

Like the previous command, this one restarts a current render, with the difference that any portion of the scene already rendered is taken up again. This only works if there was an output file being written.

Rerun|File list

The file list shows the last 16 rendering jobs the same way that the Rerun Dialog does. It also lets you select a recent file for re-rendering, but it does not let you view the rendering statistics beforehand.


Options Menu

Keep Single Instance

This option prevents more than one instance of POV-Ray for Windows from running at a time. If you attempt to launch a new one, the currently running one is activated instead. This is handy if you are using File Manager or Explorer to launch POV files by double-clicking. (Explorer users can get even more control by using the right mouse button menu.)

Use Render Animation

Turns on or off the use of the animated image in the top-right-hand corner of the tool bar. If it's turned on, and POV-Ray is rendering, an animation will be shown to indicate that a render is in progress. This animation is done from pre-generated images and uses very little CPU time.

Show Toolbar

Will alternately show or hide the toolbar

Place in System Tray (Alt+W)

Places POVWIN in the system tray on the taskbar. Double-click to restore POVWIN. You can also right-click to get a context menu.

'Other Settings' Sub-Menu

Other Settings|Use Editor

Turns the use of the internal editor on or off.

Other Settings|Use File Browse Template

This option, when selected, will cause POV-Ray for Windows to use a custom template for the file browse dialog boxes. If that sounds confusing, it's actually not - all it means is that, whenever you need to select a file, the dialog box provided will be somewhat bigger than the standard size. Most people find this useful, so the default for this option is checked.

Other Settings|Show Tips of the Day

This command lets you decide whether you want POV-Ray for Windows to display the tip of the day on startup. By default, POV-Ray for Windows displays a new tip every time the program is started more than 24 hours after the previous tip was shown. Selecting Show Tips of the Day has the same effect as selecting the 'Show tip tomorrow' box in the tip screen.

Other Settings|Show Next Tip

If you do not want to see the tip of the day pop up automatically on startup every day, you can still see a tip whenever you feel like it. If you select Show Next Tip, POV-Ray for Windows displays a single tip but keeps the 'Show tip tomorrow' box unchecked.

Other Settings|Show Tooltips

Turns Tooltips on or off. A Tooltip is a little yellow window that will pop up over a toolbar button if you keep the cursor there for long enough. The tip window tells you what the button does.

Other Settings|Preserve Messages

Whenever you perform a render, POV-Ray for Windows generates a number of messages (active POV-Ray settings, rendering statistics etc.) in the POV-Ray window. If you select Preserve Messages, POV-Ray for Windows retains all messages generated during the current session. If you deselect this option, all existing messages are deleted every time you perform a new render. If you want to retain rendering statistics beyond the POV-Ray for Windows session, refer to the POV-Ray 3 documentation for appropriate options. See also Clear Messages in the Edit Menu.

Don't forget that the statistics for each completed render are available from the Rerun Dialog.

Other Settings|Save Settings on Exit

If you select this command, any settings you have selected during your current POV-Ray for Windows session will be stored for the next one. These include the position and size of the Main Window as well the position of the Render Window. You can check which menu settings you have selected by going into the various menus. Any setting with a tick in front of it is selected. To toggle any setting, click on it once.

Drag’N’Drop Destination Sub-Menu

This menu option allows you to select the destination for the Drag’N’Drop function. You can choose the editor or the renderer. See also Dragging and Dropping

Message Window Sub-Menu

Selecting this menu item brings up a sub-menu with the following options:  Select Plain Background; Text Font; Text Color; Background Color; Tiling Options.

Message Window|Select Plain Background

POV-Ray for Windows comes with a bitmapped background as default. If you prefer a plain background, you can select this command. The background takes on the currently defined background color (see Background Color below).

Message Window|Text Font

Use this command to determine the font POV-Ray for Windows uses to display messages and statistics. In addition to the type of (non-proportional) font, you can set font size and appearance. POV-Ray for Windows remembers the font setting between sessions.

NOTE - if you select italic text, this setting will not be preserved across invocations of POV-Ray.

Message Window|Text Color

This command lets you determine which text color best fits the background you have selected for the Main Window.

Message Window|Background Color

This command lets you select the color of the plain background for the Main Window. Note that this command has no effect while you have tiled the background with a bitmap. The color only becomes visible when you Select Plain Background (see above).

Message Window|Tiling Options

You can change the tiled bitmap POV-Ray for Windows displays by default. Choosing Tiling Options brings up a sub-menu where you can select one of several built-in bitmaps. You can also browse your disk for other bitmaps you might prefer. POV-Ray for Windows pre-installs a number of them in the TILES subdirectory of your POV-Ray for Windows home directory. The bitmaps should have no more than 256 colors. If the BMP file you select is smaller than the Main Window, it will be tiled. If it is larger, POV-Ray for Windows fits it into the top-left corner of the Main Window and displays as much of it as the Main Window allows.

Note that because of the POV-Ray for Windows generalized palette, if you are running in 256-color mode, external bitmaps may not tile 100% perfectly, and the colors may be slightly altered. If you are running in 16-color mode, tiled backgrounds are not available at all. In practice, choosing tillable bitmaps other than the standard Marble one, using a 256-color display, will often not yield attractive results.

Render Window Sub-Menu

Selecting the Render Window command brings up a sub-menu with the following options: Force 8-bit Display; Get Focus on Creation; Keep Above Main; Hide When Main Minimized, Re-display, Autoclose and Close (see below).

Render Window|Force 8 bit Display

POV-Ray for Windows is capable of displaying a rendering scene in 24-bit color (Truecolor). This takes up a great deal of RAM, however: 3 bytes for every pixel in the rendered scene. If you do not have enough RAM to spare, you can select this command. It forces POV-Ray for Windows to display the scene in 8-bit color (1 byte per pixel) and to use color dithering to represent the rendered image on the screen. If you are already using a 256-color video mode it does not make any difference since the image is already stored as one byte per pixel. Note that this does not change the way that the rendered image is stored on disk. If you are writing an output file, the file will still be 24-bit color!

In 15 or 16 bit color modes, the image is stored in memory as 24-bit but only displayed as 15 or 16 bit. No dithering is (currently) performed in these modes.

Render Window|Get Focus on Creation

This command causes the POV-Ray window to get focus (pop to the foreground and become active) whenever a new file is processed. If POV-Ray for Windows is processing a file queue or animation, the POV-Ray Main Window gets focus every time a new file is initialized from the top of the queue, or a new pass over the animation source file is performed. This only applies, of course, if you are using the render window.

If you want to do other work on your Windows machine while POV-Ray is rendering, but you have the render window displayed, you will probably want to have this option off since otherwise the window will keep on popping up over whatever you are doing, each time a new image is rendered.

Render Window|Keep Above Main

If you make the POV-Ray for Windows Main Window active with Keep Above Main deselected, the rendering window may still be obscured by the main or any other window. Selecting Keep Above Main ensures that the rendering window pops up from under other windows whenever you make POV-Ray for Windows active.

Render Window|Hide When Main Minimized

If you have Keep Above Main deselected, the main POV-Ray window and the Render Window are no longer linked. You now have the option of continuing to show the Render Window whenever the Main Window is minimized. If you select this option, the Render Window disappears as soon as you minimize the Main Window.

Note that with Keep Above Main selected, this option is grayed out because it is irrelevant.

Render Window|Re-display

If the Render Window is closed (see Close below), you can re-display it by selecting this command. If the window is not closed in the first place (or has never been displayed), you cannot re-display it, and so the Re-display command is grayed.

Render Window|Autoclose

This causes the Render window to close automatically when rendering is complete.

Render Window|Close

This command closes the Render Window. This does not interfere with any rendering activity. Indeed, it speeds up rendering (see also Speed Considerations). To re-display the Render Window, select Re-display or use the right-mouse button speed menu.


Tools Menu

The Tools Menu provides you with a simple means of customizing POV-Ray for Windows. You can develop your own commands (up to 32) to show up under this menu. Since the menu is determined by the file PVTOOLS.INI, editing and reloading this INI file changes the Tools Menu.

Syntax

The syntax of entries in PVTOOLS.INI is as follows:

[Menu]
Itemn=Description

[Command]
Itemn=command_string

[Help]
Itemn=help_line

Where entries in the [Help] section are optional.

Itemn

  Item0 ... Item31

are the item numbers that define the order in which entries appear in the Tools Menu.

[Menu]

Entries in the [Menu] section are what actually appears in the Tools Menu. The '&' character tells Windows where to put the underline in the menu entry. The underlined letter becomes the abbreviation for the command. For example the letter 'C' in '&Click Me' would be underlined in the Tools Menu, and you could access the command by pressing Alt+T and then 'C'. (Alt+T activates the Tools Menu).

You should make sure that all Tools Menu entries have different abbreviations if you intend to access them this way. Of course, you don't have to supply any abbreviation if you don't want to.

[Command]

This is the command that POV-Ray will execute for that entry. This can be a Windows EXE or PIF, a DOS EXE or COM, or even a DOS batch file. The command consists of the actual command name followed by any parameters you want to supply to the program.

There is one special command, called '$S'. $S means 'use the shell association for the filename that follows it'. Let's look at an example -

  Item4=$S %1

Since %1 refers to the output file (see below) this means that Item 4 of the tools menu expands to a command to Windows to open the last output file with whatever program is associated with it. For example, if the last output file was 'c:\images\torus4.bmp' then the above command example would use whatever program is associated with BMP files (i.e. the program that Windows runs if you double-clicked on the TORUS4.BMP file in Windows Explorer) to open it.

NOTE! If using the Shell Open command ($S), DO NOT quote the parameters with '"'

POV-Ray for Windows has a number of pre-defined parameters that you can substitute into the command line before the program is run. These are defined by a percent sign ('%') followed by a letter or number. For example, '%i' means substitute the POV-Ray for Windows INI file directory in the place of the '%i'.

Let's look at the command:

  notepad.exe %ipvtools.txt

If you had installed POV-Ray for Windows into the directory 'c:\povwin3', then our standard INI file directory would be 'c:\povwin3\ini\'. When POV-Ray ran the above command, the '%i' would be replaced with 'c:\povwin3\ini\'. Note that the trailing '\' is provided by POV-Ray. This means that:

  notepad.exe %ipvtools.txt

would become:

  notepad.exe c:\povwin3\ini\pvtools.txt

Here are all of the predefined substitutions:

%0	The contents of the 'SourceFile' entry of the 'LastRender' section in PVENGINE.INI. This will be the input file provided to POV-Ray for the most recent render. This information is extracted from the rendering engine itself, rather than any input dialog or command-line. It is the file which, after all processing of the command line and INI files was complete, was finally assigned as the input file.

%1	The contents of the 'OutputFile' entry of the 'LastRender' section in PVENGINE.INI. This will be the output file from the last render, if any. This entry could be blank.

%2	The contents of the 'SceneFile' entry of the 'LastRender' section in PVENGINE.INI. This will be the scene file name for the last render, without the .POV extension. You can use this by appending a new extension to it. For example,

  tga2gif %d\%1 %2.gif

could expand to:

  tga2gif c:\scenes\myscene.tga myscene.gif

assuming the input file was myscene.pov and the current directory at that time was c:\scenes.

%3	The contents of the 'HistogramFile' entry of the 'LastRender' section in PVENGINE.INI. If there was a histogram file written, this will be its name. If the histogram file was in .CSV format, you'd probably use this to fire up Excel. Otherwise, you could use it to run a viewer program or a post-processor.

%4	The contents of the 'IniOutputFile' entry of the 'LastRender' section in PVENGINE.INI. If you had instructed POV-Ray to write an INI file from the last render, this would contain its name.

%D	The contents of the 'CurrentDirectory' entry of the 'LastRender' section in PVENGINE.INI. This is the current working directory that was set on your machine when POV-Ray began rendering the last file, and is what the other output file entries are probably relative to. You may need to provide '%d' with some of these other entries to get the full path.

%H	The POV-Ray for Windows home directory, as specified in WIN.INI. For example, 'c:\povwin3\'. Note the trailing backslash is supplied.

%I	The POV-Ray for Windows INI directory. e.g. 'c:\povwin3\ini\'.

%N	The preset INI filename, as used in the render options dialog (ALT+C).

%R	The last render file (with full path) as supplied to POV-Ray from the render or choose file dialog. This is not necessarily the same thing as %S or %0.

%S	The source file name as provided to POV-Ray on the last render of the current session. This is not necessarily the same thing as the %0 or %R directive. For example, %R will never provide the path to a file that was rendered via the File Queue without the use of the Command dialog. %S will, however, include any such file.

%T	The full path to PVTOOLS.INI. This is the file which holds the Tools Menu commands.

%%	A literal percent character ('%').

If any of the above seems confusing, there's an easy way to find out what's going on. If you place the statement DEBUG=1 in the General section of PVTOOLS.INI, POV-Ray for Windows will print out the string for each command both before and after it is expanded, instead of running the command that you select in the tool menu. That way you can see exactly what POV-Ray substitutes.

For example:

  [General]
  Debug=1

will turn on debugging. while

  [General]
  Debug=0

or omitting the statement entirely turns it off.

[Help]

You can have a help line appear in the status bar at the bottom of the window. You don't have to supply this entry if you don't want to.

[Help]
Item8=Lets you shell out to DOS

This command makes the string 'Lets you shell out to DOS' appear on the status bar when the mouse is over the 8th item in the Tools menu.

Reload Tool Menu

If you want your changes to take immediate effect after you have edited PVTOOLS.INI using a text editor, you have to select the Tools Menu command Reload Tool Menu to instruct POV-Ray for Windows to re-read the INI file and activate the new settings.

Edit PVTOOLS.INI

This standard Tools Menu command lets you modify PVTOOLS.INI using the Notepad editor. The command is part of PVTOOLS.INI itself, which means you may delete it entirely if you don't want it. It is present by default in the standard distribution of POV-Ray for Windows.

Example PVTOOLS.INI

[Menu]
Item0=&Click Me to Read Me FIRST !
Item1=&Edit master POVRAY.INI
Item2=Edit &last rendered file
Item3=Edit last &scene file
Item4=&View last rendered file
Item5=View &histogram image file
Item6=Edit secondary &INI file
Item7=Edit &PVTOOLS.INI
Item8=&MSDOS prompt

[Command]
Item0=notepad.exe %ipvtools.txt
Item1=notepad.exe %ipovray.ini
Item2=notepad.exe %r
Item3=notepad.exe %0
Item4=$S %1
Item5=$S %3
Item6=notepad.exe %n
Item7=notepad.exe %t
Item8=dosprmpt.pif

[Help]
Item0=This entry gives help on the Tools Menu
Item1=Edit master POVRAY.INI in installation directory
Item2=Edit the last file that POV-Ray was rendering
Item3=Edit the last scene file that you selected
Item4=View the output of the last render (assumes file output was on ; needs VUEPRO32.EXE)
Item5=View the histogram of the last render (assumes histogram image output was on ; needs VUEPRO32.EXE)
Item6=Edit secondary INI file as specified in Command-line dialog (Alt+C)
Item7=Edit PVTOOLS.INI to alter tools menu
Item8=Open a DOS shell prompt

Resulting Menu

This is the menu that results from the above PVTOOLS.INI.


GUI Extensions Menu

GUI Extensions are specialized DLL's that can add functionality to the POV-Ray for Windows user interface. They can also provide a means for external programs (such as the popular Moray modeller) to control POV-Ray in a limited manner. If you want more information on GUI Extensions see the newsgroup povray.programming on the POV news server, or retrieve the POV-Ray for Windows source code from our FTP site, and look at the example extension in the GUIEXT subdirectory.

Unless you are using a program that has a GUI Extension, or have installed one yourself, there will be a message 'No GUI Extensions Loaded' visible in this menu. If you have some installed, you can turn their functionality on or off by unchecking the 'Use Extensions' menu item.

The POV-Team provides no support whatsoever for GUI Extensions. The POV document that allows GUIEXT authors to write extensions to our specification requires them to provide support for them for at least a little while after they are released. If you have a third-party GUIEXT with which you are having problems, you should refer to the author of that extension. If he/she is no longer available for support, we cannot help you.


Shortcut Menus

Main Window

When you right-click on the Main Window, a shortcut menu pops up with the following entries:

Edit Settings/Render

Select File and Render

Start Rendering

Rerun Dialog

File Queue

Clear Queue

Re-display Render Window

Show Tip

GUI Priority

Render Priority

Render Window

Right-clicking on the Render Window brings up the following shortcuts:

Get Focus on Creation

Keep above Main

Hide when Main Minimized

Use Tiny Caption

Close


Bug Reports

Before submitting any bug reports, make sure that the bug is not in the list of known bugs below. Please remember that the POV-Ray developers are volunteers who give their time for free so you can enjoy this program for no charge. Keep this in mind when wording your message.

MAKE ABSOLUTELY SURE that the subject of your report isn’t already covered in this document. Questions that are already answered either in this help file, any README’s, installation notes, or other files supplied with this program will be totally ignored.

If you are after advice or assistance, try the internet newsgroup comp.graphics.rendering.raytracing,. Also, the POV-Ray News Server is becoming a popular place for discussions. You will find a list of newsgroups by clicking the above link or going to http://www.povray.org/groups.html.

Things that look like bugs but aren’t

Windows 95 users with the Microsoft Plus Pack will note that, if they have full-window dragging turned on, the message window will clear during resizing. The window goes back to normal afterwards. This isn’t a bug ; it’s a feature. We deliberately turn the window off because otherwise it will flash annoyingly during the resizing because Windows sends lots of paint messages to us.

Feature Requests are not bugs.

The above may seem to be an obvious statement, but it’s not so obvious that this section is unnecessary. Yes, some people have been sending feature requests to the bug reporting email address. This adds to the workload of the person handling bug reports. All feature requests sent to the bug reporting address will be totally ignored. If you want to request a feature, discuss it in one of the povray.* groups on news.povray.org.

’I don’t like the way this works so it must be a bug’

Yes, we get those too. A number of people have written to the bug reporting address complaining about the way a feature is implemented (such as the tabbed editor).

If you don’t like the way a feature works, then either a) turn it off (if available ; for example, the toolbar and the editor can all be turned off), b) don’t use the feature, or c) don’t use the program. We can never please everybody so if we change it to suit you we’ll annoy someone else (believe us, we know from experience).

Known Bugs

If you select an entire group of files and then drop them into povray, the first and last files will switch places. This is a bug in the way things are handled by Windows and not a bug in POV-Ray for Windows.

Filenames with high-ASCII characters may be truncated by the C runtime library, causing the renderer to fail to find them. This is beyond our control at this stage. Note that the editor handles such files without problems.

GUI Extensions

If you have installed any GUI Extensions (or used any software that may have installed them), make sure you see if the problem exists with the extensions disabled and unloaded.

To do this, go to the GUI Extensions menu, and deselect 'Use Extensions'. Then exit and restart POV-Ray for Windows. The GUI Extensions menu should then state 'No Extensions Loaded' (it may already do this if you've got none installed). Then attempt to duplicate the problem again.

Spelling

As stated in the introduction, we use international English spelling in many parts of POV-Ray for Windows. This means that many words that are normally spelt with a 'z' in American English (such as minimized) are spelt with the English 's' (e.g. minimised).

Email

Unfortunately, email bug reporting is no longer available due to the incorrect use of this facility by a number of users. You may only report bugs in POVWIN by using the newsgroups mentioned below.

News Server

Bug reports may be lodged about POVWIN by posting them in the appropriate group on our news server, news.povray.org. See http://www.povray.org/groups.html for information about the server, and particularly for information as to which group to use. If you don't post in the right group, the message may not be read by a member of the team.

Any messages or reports sent to us may (not necessarily will, but may) be reposted by us in our newsgroups, on USENET, or on our web site. If you do not wish your communication to be posted in this manner, please do not send us any.

You should not expect any reply to your message. If we need to write to you about it, we will.

The minimum information to include in your bug report is

The version number of POV-Ray for Windows. You can see this by selecting About from the Help Menu.

Your operating system. It’s surprising how many people fail to provide this basic piece of information. We need to know what version of Windows you are running

Your computer ; what processor and how much memory.

A complete description of the problem and what led up to it. It will make it a lot easier to track down if you can include a scene file that will cause the problem. If the file is large, try removing parts until you have the minimum scene file that will cause the problem.


Speed Considerations

Render Priority

Raising the render priority will speed up your render, at the cost of reducing system response times and slower execution of other programs. Note that by default POV-Ray for Windows is slower than POV-Ray for Dos would be on the same machine. This is simply because the default settings for render priority and GUI priority force POV-Ray for Windows to give up some CPU time (even if no other tasks are running), while POV-Ray for DOS has the machine more or less to itself. If you want faster renders, bump up the render priority and lower the GUI priority (but be prepared for sluggish response.)

Closing the render window will also speed up things. If your render is writing a lot of text to the message window, either hiding it (select an editor window for example), or better still, minimizing POV-Ray for Windows, will help somewhat. Note that the effect that these actions have is generally directly related to the time it takes to render the file, and the resolution of the render. They have less effect on long renders, and more effect on very fast renders.

In general, the more memory you have (up to a point) the faster things will run, although this is not a direct effect. (The less time Windows spends swapping things out to disk, the more time is available for your render)

Anti-aliasing, fog, halos, area lights, atmosphere--all of these will cause your scene to require more time for completion. See the POV-Ray documentation for more details.


System Requirements

POV-Ray for Windows requires Windows 95/98, Windows NT4, or later.

You’ll need at least 256-color graphic mode for the program and help to function in a relatively normal manner. Hi-color is strongly recommended.

The Alert on Completion (see Render Menu) command works best with a sound card.


POV-Ray Accessories

If you have internet access, check out www.povray.org for oodles of POV-Ray goodies.

The following items were produced by POV-Team members.

 The IRTC CDROM (Year One)

The IRTC CDROM (Year One) is a compilation of all entries made to the Internet Raytracing Competition during its first year of operation. As the IRTC is bi-monthly, this covers round #1 (May/June 1996) to round #6 (March/April 1997). There are over 1000 images and 500 source archives available.

This CDROM is designed to be used with a web browser - the entire CD is indexed via HTML and bears some resemblance to the IRTC website (with enhancements).

Almost all the submissions are 800x600 pixel JPEG's, and all have a text file accompanying them giving author's details and an explanation of the image. In some cases, that explanation is quite comprehensive. (That means that this CD is a great learning tool for POV-Ray users!) Additionally, many authors chose to provide the source to their images, in the form of data files for whatever renderer that they used. In most cases, the renderer of choice was POV-Ray, and thus there is a large collection of POV-Ray scene files on the CD, most for version 3.0 of that raytracer.

On the CD you will find all of the submission images, author's text files, and scene files available for the 96/97 year. In addition, the judges comments are available and have been linked to each submission's entry in that round's HTML page. Also included are the tabulated voting scores and results pages.

By popular demand, an effort was made to include the submissions from the predecessor of the IRTC. This competition was monthly and ran from November 1994 to December 1995. Due to the length of time that has passed, it was not possible to contact all of the authors for their permission to include their work, and as such only about half of the submissions are on the CD. This still adds up to over 150 raytracings, many of them stunning work by some of the same authors whose work you will find in the IRTC.

Also by popular demand, the CD contains the full set of official binaries for the freeware Persistence of Vision raytracer, version 3.02. This includes documentation and sample scenes as well as the program for the DOS, Windows 3.1, Windows 95/NT, Macintosh, x86 Linux, SunOS and Amiga platforms.

As a special bonus, the CD contains an AVI version of Thomas Schmidt and Rene' Schwietzke's excellent 'museum' raytraced animation. This AVI is 65 megabytes in size ! Also present are the high, medium, and low-bandwidth MPEG versions of this same animation. This AVI is not simply a conversion from the MPEG - it was put together by the authors from the original TGA files, especially for this CDROM.

Finally, there are high-quality versions of many of the scenes that won or achieved technical merit status in the competition. At the very least, these will be high-quality JPEG's, but in many cases they are in lossless TGA format. In addition, there are a number of these images in higher resolution than originally submitted, including a number in 1280x1024. Some of the winning authors have submitted bio's giving a little information about themselves.

The CD is ISO9660 compatible with short (MS-DOS) file names. It is a hybrid ISO/HFS disk meaning that Macintosh users can be happy ; the Mac side of things is fully laid-out for ease of use. On both Windows 95/NT and the Macintosh, if you have a web browser properly installed on your system, the disk will auto-start when it is inserted into your drive, loading the base index.htm file into the browser.

The disk, in total, contains over 550 megabytes of data. It was produced to help support the running costs of the POVRAY.ORG and IRTC.ORG websites.

See http://www.aussie.org/products/ for more information and to order from our secure server.

 The IRTC CDROM (Year Two)

The IRTC CDROM (Year Two) is a compilation of all entries made to the Internet Raytracing Competition during its second year of operation. As the IRTC is bi-monthly, this covers round #7 (May/June 1997) to round #12 (March/April 1998). It also includes the first three rounds of the IRTC Animations competition. As this runs every three months, this means that it includes round #1 (15 Oct 1997 - 15 Jan 1998), round #2 (15 Jan 1998 - 15 Apr 1998), and round #3 (15 Apr 1998 - 15 July 1998).

It also contains a large (800x600) MPG version of the winning 'Batteries Not Included' animation from the 'Toys' round (April-July 1998), as well as a 640x480 AVI generated directory from the TGA files. This latter file is 180mb in size!

This CD is similar to most respects to the Year One CD in terms of its presentation and layout. See http://www.aussie.org/products/ for more information and to order from our secure server.

 The IRTC CDROM (Year Three)

The IRTC CDROM (Year Three) is a compilation of all entries made to the Internet Raytracing Competition during its third year of operation. As the IRTC is bi-monthly, this covers round #13 (May/June 1998) to round #18 (March/April 1999). It also includes rounds 3 through 6 (inclusive) of the IRTC Animations competition. As the animations competition runs every three months, this means that it includes 15 Apr 1998 - 15 Jul 1998, 15 Jul 1998 - 15 Oct 1998, 15 Oct 1998 - 15 Jan 1999, and 15 Jan 1999 - 15 Apr 1999.

This CD is similar to most respects to the Year One and Two CD’s in terms of its presentation and layout. As of the time of writing (July 1999) it was not yet available but is expected out in August. See http://www.aussie.org/products/ for pricing and availability information.


POV-Ray Legal Document

Persistence of Vision™Ray Tracer
(POV-Ray™)
Version 3.1g Legal Information and License

May 1999

General License Agreement -- POVLEGAL.DOC

THIS NOTICE MUST ACCOMPANY ALL OFFICIAL OR CUSTOM PERSISTENCE OF VISION FILES. IT MAY NOT BE REMOVED OR MODIFIED. THIS INFORMATION PERTAINS TO ALL USE OF THE PACKAGE WORLDWIDE.  THIS DOCUMENT SUPERSEDES ALL PREVIOUS GENERAL LICENSES OR DISTRIBUTION POLICIES. ANY INDIVIDUALS, COMPANIES OR GROUPS WHO HAVE BEEN GRANTED SPECIAL LICENSES MAY CONTINUE TO DISTRIBUTE VERSION 2.x BUT MUST RE-APPLY FOR VERSION 3.00 OR LATER.

This document pertains to the use and distribution of the Persistence of Vision™ Ray Tracer a.k.a POV-Ray™. It applies to all POV-Ray program source files, executable (binary) files, scene files, documentation files, help file, bitmaps and INI files contained in official POV-Ray Team™ archives.  All of these are referred to here as "the software". The POV-Team reserves the right to revise these rules in future versions and to make additional rules to address new circumstances at any time.

All of this software is Copyright 1991,1999 by the POV-Ray Team™. Although it is distributed as freeware, it is NOT PUBLIC DOMAIN.

The copyrighted package may ONLY be distributed and/or modified according to the license granted herein.  The spirit of the license is to promote POV-Ray as a standard ray tracer, provide the full POV-Ray package freely to as many users as possible, prevent POV-Ray users and developers from being taken advantage of, enhance the life quality of those who come in contact with POV-Ray.  This license was created so these goals could be realized.  You are legally bound to follow these rules, but we hope you will follow them as a matter of ethics, rather than fear of litigation.

Usage Provisions

Permission is granted to the user to use the software and associated files in this package to create and render images. The use of this software for the purpose of creating images is completely free. The creator of a scene file and the image created from the scene file, retains all rights to the image and scene file they created and may use them for any purpose commercial or non-commercial.

The user is also granted the right to use the scenes files, fonts, bitmaps, and include files distributed in the INCLUDE and SCENES\INCDEMO sub-directories in their own scenes.  Such permission does not extend to files in the SCENES directory or its sub-directories.  The SCENES files are for your enjoyment and education but may not be the basis of any derivative works.

General Rules For All Distribution

The permission to distribute this package under certain very specific conditions is granted in advance, provided that the following conditions are met.

These archives must not be re-archived using a different method without the explicit permission of the POV-Team.  You may rename the archives only to meet the file name conventions of your system or to avoid file name duplications but we ask that you try to keep file names as similar to the originals as possible.  (For example: POVSRC.ZIP to POVSRC30.ZIP)

Ready-to-run unarchived distribution on CD-ROM is also permitted if the files are arranged in our standard directory or folder structure as though it had been properly installed on a hard disk.

You must distribute a FULL PACKAGE of files as described in the next section.  No portion of this package may be separated from the package and distributed separately other than under the conditions specified in the provisions given below.

Non-commercial distribution in which no money or compensation is charged (such as a user copying the software for a personal friend or colleague) is permitted with no other restrictions.

Teachers and educational institutions may also distribute the material to students for free or they may charge minimal copying costs if the software is to be used in a course.

Definition Of "Full Package"

A "full package" contains an executable program, documentation, and sample scenes.  For generic Unix platforms, there are no executables available so the portable C source code must be included instead of the executable program.

POV-Ray is officially distributed for MS-Dos; Windows 95/98/NT; Linux for Intel x86 series; Apple Macintosh; Apple PowerPC; SunOS; and Amiga. Other systems may be added in the future.

Distributors need not support all platforms but for each platform you support you must distribute a full package. For example a Macintosh only CD-ROM need not distribute the Windows versions.

This software may ONLY be bundled with other software packages according to the conditions specified in the provisions below.

Conditions For CD-ROM or Shareware/Freeware Distribution

Shareware and freeware distribution companies may distribute the software included in software-only compilations using media such as, but not limited to, floppy disk, CD-ROM, tape backup, optical disks, hard disks, or memory cards. This section only applies to distributors of collected programs. Anyone wishing to bundle the package with a shareware product must use the commercial bundling rules.

Distribution on CD-ROM or high capacity media such as backup tape is permitted if the total cost to the user is no more than $0.08 U.S. dollars per megabyte of data. For example a CD-ROM with 600 meg could cost no more than $48.00 US.

Any bundling with books, magazines or other print media is permitted if the total cost of the book or magazine with CD is less than the $48.00 limit. Bundling with more expensive publications or distributions should also use the commercial rules.

For floppy disk distribution, no more than five dollars U.S. ($5) can be charged per disk for the copying of this software and the media it is provided on. Space on each disk must be used as fully as possible. You may not spread the files over more disks than are necessary.

Conditions For On-Line Services And Bbs's Including Internet

On-line services, BBS's and internet sites may distribute the POV-Ray software under the conditions in this section. Sites which allow users to run POV-Ray from remote locations must use separate provisions in the section below.

The archives must all be easily available on the service and should be grouped together in a similar on-line area.

It is strongly requested that sites remove prior versions of POV-Ray to avoid user confusion and simplify or minimize our support efforts.

The site may only charge standard usage rates for the downloading of this software. A premium may not be charged for this package. I.E. CompuServe or America On-Line may make these archives available to their users, but they may only charge regular usage rates for the time required to download.

Online Or Remote Execution Of POV-Ray

Some internet sites have been set up so that remote users can actually run POV-Ray software on the internet server. Other companies sell CPU time for running POV-Ray software on workstations or high-speed computers. Such use of POV-Ray software is permitted under the following conditions.

Fees or charges, if any, for such services must be for connect time, storage or processor usage ONLY. No premium charges may be assessed for use of POV-Ray beyond that charged for use of other software. Users must be clearly notified that they are being charged for use of the computer and not for use of POV-Ray software.

Users must be prominently informed that they are using POV-Ray software, that such software is free, and where they can find official POV-Ray software. Any attempt to obscure the fact that the user is running POV-Ray is expressly prohibited.

All files normally available in a full package distribution, especially a copy of this license and full documentation must be available for download or readable online so that users of an online executable have access to all of the material of a full user package.

If the POV-Ray software has been modified in any way, it must also follow the provisions for custom versions below.

Permitted Modification And Custom Versions

Although the full source code for POV-Ray is distributed, there are strict rules for the use of the source code. The source distribution is provided to;  1) promote the porting of POV-Ray to hardware and operating systems which the POV-Team cannot support.  2) promote experimentation and development of new features to the core code which might eventually be incorporated into the official version.  3) provide insight into the inner workings of the program for educational purposes.

These license provisions have been established to promote the growth of POV-Ray and prevent difficulties for users and developers alike. Please follow them carefully for the benefit of all concerned when creating a custom version.

The user is granted the privilege to modify and compile the source code for their own personal use in any fashion they see fit. What you do with the software in your own home is your business.

However severe restrictions are imposed if the user wishes to distribute a modified version of the software, documentation or other parts of the package (here after referred to as a "custom version"). You must follow the provisions given below. This includes any translation of the documentation into other languages or other file formats.

A "custom version" is defined as a fully functional version of POV-Ray with all existing features intact. ANY OTHER USE OF ANY POV-Ray SOURCE CODE IS EXPRESSLY PROHIBITED. The POV-Team does not license source code for any use outside POV-Ray. No portion of the POV-Ray source code may be incorporated into another program unless it is clearly a custom version of POV-Ray that includes all of the basic functions of POV-Ray.

All executables, documentation, modified files and descriptions of the same must clearly identify themselves as a modified and unofficial version of POV-Ray. Any attempt to obscure the fact that the user is running POV-Ray or to obscure that this is an unofficial version expressly prohibited.

POV-Ray may not be linked into other software either at compile-time using an object code linker nor at run-time as a DLL, ActiveX, or other system. Such linkage can tend to blur the end-user's perception of which program provides which functions and thus qualifies as an attempt to obscure what is running.

To allow POV-Ray to communicate with outside programs, the official versions of POV-Ray include several internal communication "hooks" for it to call other tasks, often called an Application Programming Interface, or API. For example: the generic part of POV-Ray provides operating system shell-out API commands. The Windows version has a GUI-extension API and the ability to replace the text editor. Modification to these APIs or other officially supported communication mechanisms to increase functionality beyond that of the official version IS EXPRESSLY PROHIBITED.

Conditions For Distribution Of Custom Versions

If your re-compiled version meets all requirements for custom versions listed above, the following conditions apply to its distribution:

You must provide all POV-Ray support for all users who use your custom version. You must provide information so that user may contact you for support for your custom version. The POV-Ray Team is not obligated to provide you or your users any technical support.

Include contact information in the DISTRIBUTION_MESSAGE macros in the source file OPTOUT.H and insure that the program prominently displays this information. Display all copyright notices and credit screens for the official version.

Custom versions may only be distributed as freeware. You must make all of your modifications to POV-Ray freely and publicly available with FULL SOURCE CODE to the modified portions of POV-Ray and must freely distribute full source to any new parts of the custom version. The goal is that users must be able to re-compile the program themselves using readily available compilers and run-time libraries and to be able to further improve the program with their own modifications.

You must provide documentation for any and all modifications that you have made to the program that you are distributing. Include clear and obvious information on how to obtain the official POV-Ray.

The user is encouraged to send enhancements and bug fixes to the POV-Ray Team, but the team is in no way required to utilize these enhancements or fixes. By sending material to the team, the contributor asserts that he owns the materials or has the right to distribute these materials. He authorizes the team to use the materials any way they like. The contributor still retains rights to the donated material, but by donating, grants unrestricted, irrevocable usage and distribution rights to the POV- Team. The team doesn't have to use the material, but if we do, you do not acquire any rights related to POV-Ray. The team will give you credit as the creator of new code if applicable.

Include a copy of this document (POVLEGAL.DOC).

Conditions For Commercial Bundling

Vendors wishing to bundle POV-Ray with commercial software (including shareware) or other distribution not already described above must first obtain explicit permission from the POV-Team. Such permission is rarely granted. The POV-Team will decide if such distribution will be allowed on a case-by-case basis and may impose certain restrictions as it sees fit. The minimum terms are given below. Other conditions may be imposed.

  *	The product must be an existing product that has proven itself as commercially viable without POV-Ray included.

  *	The inclusion of POV-Ray should be promoted only as a free bonus and not as a feature designed to encourage customers to purchase or upgrade solely for the POV-Ray capability.

  *	Purchasers of your product must not be led to believe that they are paying for POV-Ray. Any mention of the POV-Ray bundle on the box, in advertising or in instruction manuals must be clearly marked with a disclaimer that POV-Ray is free software and can be obtained for free or nominal cost from various sources.

  *	Include clear and obvious information on how to obtain the official POV-Ray.

  *	You must provide all POV-Ray support for all users who acquired POV-Ray through your product. The POV-Team is not obligated to provide you or your customers any technical support.

  *	Include a credit page or pages in your documentation for POV-Ray.

  *	If you modify any portion POV-Ray for use with your hardware or software, you must follow the custom version rules in addition to these rules.

  *	Include contact and support information for your product.

  *	Include a full user package as described above.

POV-Team Endorsement Prohibitions

On rare occasions, the POV-Team endorses distributions in which POV-Team members are compensated participants and which the POV-Team has given approval.

Without specific approval, distributors (whether free or commercial) must not claim or imply in any way that the POV-Team officially endorses or supports the distributor or the product (such as CD, book, or magazine) associated with the distribution.

You may not claim or imply that the POV-Team derives any benefit from your distribution.

If you wish to emphasize that your distribution is legal, you may use this language "This distribution of the official version of POV-Ray is permitted under the terms of the General License in the file POVLEGAL.DOC. The POV- Team does not endorse the distributor or its products. The POV-Team receives no compensation for this distribution."

Retail Value Of This Software

Although POV-Ray is, when distributed within the terms of this agreement, free of charge, the retail value (or price) of this program is determined as US$20.00 per copy distributed or copied. If the software is distributed or copied without authorization you are legally liable to this debt to the copyright holder or any other person or organization delegated by the copyright holder for the collection of this debt, and you agree that you are legally bound by the above and will pay this debt within 30 days of the event.

However, none of the above paragraph constitutes permission for you to distribute this software outside of the terms of this agreement. In particular, the conditions and debt mentioned above (whether paid or unpaid) do not allow you to avoid statutory damages or other legal penalties and does not constitute any agreement that would allow you to avoid such other legal remedies as are available to the copyright holder.

Put simply, POV-Ray is only free if you comply with our distribution conditions; it is not free otherwise. The copyright holder of this software chooses to give it away free under these and only these conditions.

For the purpose of copyright regulations, the retail value of this software is US$20.00 per copy.

Other Provisions

The team permits and encourages the creation of programs, including commercial packages, which import, export or translate files in the POV-Ray Scene Description Language. There are no restrictions on use of the language itself. We reserve the right to add or remove or change any part of the language.

"POV-Ray", "Persistence of Vision", "POV-Team" and "POV-Help" are trademarks of the POV-Team.

While we do not claim any restrictions on the letters "POV" alone, we humbly request that you not use POV in the name of your product. Such use tends to imply it is a product of the POV-Team. Existing programs which used "POV" prior to the publication of this document need not feel guilty for doing so provided that you make it clear that the program is not the work of the team nor endorsed by us.

Revocation Of License

VIOLATION OF THIS LICENSE IS A VIOLATION OF COPYRIGHT LAWS. IT WILL RESULT IN REVOCATION OF ALL DISTRIBUTION PRIVILEGES AND MAY RESULT IN CIVIL OR CRIMINAL PENALTY.

Such violators who are prohibited from distribution will be identified in this document.

In this regard, "PC Format", a magazine published by Future Publishing, Ltd. in the United Kingdom, distributed incomplete versions of POV-Ray 1.0 in violation the license which was effect at the time. They later attempted to distribute POV-Ray 2.2 without prior permission of the POV- Team in violation the license which was in effect at the time. There is evidence that other Future Publishing companies have also violated our terms. Therefore "PC Format", and any other magazine, book or CD-ROM publication owned by Future Publishing is expressly prohibited from any distribution of POV-Ray software until further notice.

Disclaimer

This software is provided as is without any guarantees or warranty. Although the authors have attempted to find and correct any bugs in the package, they are not responsible for any damage or losses of any kind caused by the use or misuse of the package. The authors are under no obligation to provide service, corrections, or upgrades to this package.

Technical Support

We sincerely hope you have fun with our program. If you have any problems with the program, the team would like to hear about them. Also, if you have any comments, questions or enhancements, please the POV-Ray Team on the internet at http://www.povray.org or our private news server news.povray.org with over a dozen povray-related news groups.  The USENET group comp.graphics.rendering.raytracing is also a great source of information on POV-Ray and related topics.

License inquiries should be made via email and limited technical support is available via email to:

POV-Ray Team Coordinator  team-coord@povray.org

The following postal address is only for official license business and only if email is impossible.

We do not provide technical support via regular mail, only email. We don't care if you don't have a modem or online access. We will not mail you disks with updated versions. Do not send money.

Chris Young; 3119 Cossell Drive; Indianapolis, IN 46224 U.S.A.

The other authors' contact information may be found in the documentation.