POV-Ray for Windows version 3.7 | ||||
|
||||
Home | POV-Ray for Windows | POV-Ray Tutorial | POV-Ray Reference |
This section will help new users get started with POV-Ray for Windows.
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 block by block. By default, these blocks are 32x32 pixels in size. Notice that if you close the Render Window, the rendering job is not interrupted. If you have POV-Ray set up to save the image as a file (this is the default setting), that file will be produced whether or not you display the image on screen as you render. To stop rendering, select Render/Stop Rendering (or use the keyboard short-cut ALT-G).
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, or just click the toolbar button labelled 'Show'.
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 Windows 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 Command-Line Options). Note that you can tell POV-Ray for Windows to open a file in the editor instead of rendering it if you drag and drop it into the program (this is in fact the default setting now). See the Options Menu for more information.
N.B. 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. However this does not mean the rendered file is not written to disk.
Please also note that POV-Ray for Windows will write the output file to a .PNG by default. There is no way to 'save the render window' after rendering is completed. If you turned file output off before starting the render, and change your mind, you will have to start the rendering all over again. We recommend that you just leave file output on all the time.
Dragging and dropping (a.k.a. Drag'N'Drop) from Windows Explorer (a.k.a. 'My Computer') 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 dialog in the Render Menu for more details.
Note: If the dropped files destination is set to Editor (the default), the files will be opened in the internal editor instead. In that case, there is a limit of 32 files that may be opened at any one time.
When POVWIN is installed using the official installer, a file association is established between .POV files and POVWIN. This means that if you double-click on a file with the .POV extension it will be opened in POVWIN's editor. In addition, right-clicking on a .POV file to open the standard Windows context menu will show two dedicated menu entries: 'Open' and 'Render with POV-Ray'. 'Open' is the same as double-clicking (internally it calls POVWIN with the '/EDIT' option). Choosing 'Render with POV-Ray' will cause the selected file to be rendered by POVWIN (note that it is not opened in the editor - having a file open in the editor is not a requirement for rendering it).
Newer versions of Windows allow users to associate other file types with programs of their choice; e.g. as a 'default program'.
As a general rule, if this is done for POVWIN and the file is double-clicked, POVWIN will open it in the editor rather than render it (which
would otherwise be the default, for compatibility with versions of POV-Ray for other platforms). If you want to associate a file
extension with POVWIN in order to render it rather than edit it, you'll need to change the association to pass the /RENDER
command-line option Documenting how to change windows to include this is beyond the scope of this tutorial.
There is a comprehensive beginner's tutorial included in this help file. It relates to the use of POV-Ray in general (i.e. on all platforms, not only Windows), so we recommend that you read the rest of section 1 first before attempting to go any further, as section 1 tells you how to use the interface of POV-Ray for Windows itself. The more ambitious may like to check out the advanced tutorial section.
This section points out the various types of text files that POV-Ray for Windows works with.
POV-Ray for Windows works with two types of plain text files. The first is the standard POV-Ray scene description file (also known as 'SDL', for Scene Description Language). Although you may give files of this type any legitimate extension, it is more convenient for you if you name them using the .POV extension. In this Help file, scene description files are referred to as POV files.
The second type, the initialization file, normally have .INI extensions and are referred to in this help file as INI files.
An INI file is a text file containing settings that instruct POV-Ray how to render a scene. These settings are different from what is in the POV file, which contains instructions to POV-Ray about what is in a scene.
You can store a default set of options in the file called POVRAY.INI in the INI folder under the POV-Ray documents folder. Unless you chose to install the user-specific files elsewhere when you installed, this will be (for example) 'POV-Ray\v3.7\ini\povray.ini' within your 'My Documents' folder. There is a command in the Tools menu that allows you to open this directly (regardless of where you installed).
You can also pass any other INI file 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 any INI file is the name of an input file. If you now instruct POVRAY to render the INI file, it will use the above option to determine what POV file to read to generate the actual image. Any other options provided in the INI file will also be applied to the image; hence this way you can customize POV-Ray settings for any individual scene file without having to type them in each time.
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' in SCENE.INI, and then ask POV-Ray to render SCENE.INI, POV-Ray will process SCENE.POV with the options specified in SCENE.INI.
Remember, though, that any options set at the POV-Ray for Windows command line when you process an INI file override any corresponding options in the INI file (see Command-line Options and Render Menu). Also, any options you do not set in the INI file will be inherited from any previously-processed INI files (e.g. 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 section titled Using INI Files for more information about INI files.
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. The 'quick resolution' listbox in POVWIN is an example of this type of file. For more information on POV-Ray options and INI files consult the section on POV-Ray Options.
The POV-Ray internal editor is an advanced programmer's 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.
It consists of two parts - a custom control, 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). It is not essential for POVWIN's operation to have the editor present - it is quite possible for it to run without it. However, under normal circumstances, the editor is present.
As of version 3.7 there been a few notable changes to the POVWIN IDE.
Note: The term 'source file' means either a .POV, .INI, .MAC or .MCR file.
Here are just a few of the features offered by the editor, as implemented in POVWIN:
Select the Options|Other Settings|Use Editor menu item. If this is off, POV-Ray for Windows will not attempt to load the editor DLL at startup, and the editors will not be available.
By default, POV-Ray for Windows will attempt to re-load the files you had open in the editor when you last exited the program. If this causes a problem (e.g. maybe one of the files is very large and you don't want it re-loaded), you can add the '/NR' (or '/NORESTORE') option to the POV-Ray for Windows command line. In this case POVWIN will flush the list of files you had opened.
You can use the Alt+LeftArrow and Alt+RightArrow keys to cycle amongst the editor windows and the message window. Some users are more comfortable with Ctrl-Tab, so this is available as well.
This facility is designed to speed up the authoring of POV-Ray scene files by allowing you to quickly insert any of the standard or user-defined keywords by typing part of the word and pressing TAB (provided you have the 'Overlay Keyword Expansion On Tab Key' option in the Editor Menu turned on).
If this option is enabled, the tab key serves two functions: it firstly will function to invoke keyword expansion, and secondly, if it appears that keyword expansion is not desired at the current edit position, it functions as a normal tab key (inserting tabs or spaces as defined by your configuration of the editor).
Before getting into the explanation below, we suggest you try it for yourself. Firstly, make sure that 'Overlay Keyword Expansion On Tab Key' is turned on (this is the default so unless you have turned it off it will already be on).
Now, open a .POV file in an editor if you don't already have one open, and position the edit cursor ('caret')
on a blank line and type the letters 'am
', then press TAB. The word 'ambient
'
should now appear where you had 'am
'. Now press it again and you will see the word
'ambient
' become 'ambient_light
'. Now press SHIFT+TAB (shift and tab
together) and you will see that it goes back to 'ambient
', and, if pressed again, back
to plain 'am
'.
When you press TAB, the editor firstly looks at the characters to the left and right of the current edit caret position. If there is blank space to the left of the caret, or there is no blank space to the right of the caret then keyword expansion does not occur and the TAB key will function normally. Note that for the purposes of this test, the start of the line is not considered blank space, but the end of the line is.
To pass the above test, therefore, the caret must be at the end of a word containing at least one character, followed by a space, tab, or the end of the line. The editor will then get this word from the line and compare it (with case-sensitivity) against the list of known POV-Ray scene file keywords that it holds internally.
If the above comparison yields a perfect match (that is, the word on the left of the caret is exactly the same as a keyword), then keyword expansion does not occur and the tab key functions normally.
If the above test fails (that is, the word is not a perfect match), then a test is made for a partial match. If the word on the left of the caret does not even partially match any word in the keyword list, then expansion does not occur and the tab key functions normally.
If the above test passes, the word on the left of the caret must be a partial
keyword (for example, 'pigm
' is considered a partial keyword since the
editor knows that 'pigment
' is a keyword). Given this fact, the editor
extracts the list of all keywords that match the partial keyword (in the above example,
'pigment
', 'pigment_map
', and 'pigment_pattern
'
all contain the prefix 'pigm
' and as such would be included in the list).
The editor stores this list in memory and then completes the partial keyword with the
first one (alphabetically) from the list it stored (in the above example, this would be
'pigment
'). Once this has occurred, the editor is in 'keyword expansion'
mode. The editor remains in this mode until you move the edit position or otherwise make
any change to the text other than via TAB and SHIFT-TAB expansion.
Pressing TAB again will cause the next keyword in the stored list of possible matches to appear, replacing the first one, and so forth. If you reach the end of the list, pressing TAB will cause the caption bar of POV-Ray for Windows to flash. This is a visual indication that there are no more keywords in the forward direction.
Pressing SHIFT+TAB causes the previous keyword to appear, and if you are at the first keyword in the list, it will cause the original text you typed to be restored. If you are at the original word and press SHIFT+TAB, the caption bar will flash to indicate that you cannot go back any further.
While all this sounds complex in theory, it is in practice very straightforward and natural to use, and once you get used to it you probably won't want to go back to the old way of doing things.
The advantage of keyword expansion becomes clear if you look at the following example:
suppose you wanted to enter the 'smooth_color_triangle
' keyword. You could
of course type the entire keyword in (a total of twenty-one keystrokes). Or, using
keyword expansion, you could enter it using only four keystrokes by typing
'sm
' then TAB and TAB again. The first tab expands it to 'smooth
'
and the second tab expands it all the way to 'smooth_color_triangle
'.
Hint: If you use keyword expansion and accidentally expand to a word you don't want, if you haven't yet exited keyword expansion mode, the best way to get back is to use SHIFT+TAB to go backwards. It is very easy to just hit the normal 'Undo' key out of habit. While this will work, it won't always restore the caret position. Using SHIFT+TAB also moves the edit caret back to its starting position as well as restoring the starting word.
![]() |
The CodeList feature is, like Keyword Expansion, designed to make editing POV-Ray scene files more convenient. It is by default assigned to the keystroke CTRL+SPACE (you can change this from the Keyboard Configuration property page). Unlike keyword expansion (which allows you to cycle through a list of keywords, one at a time), CodeList allows you to see many of them at once, and select one with the cursor keys or mouse. |
CodeList keyword expansion |
When you press CTRL+SPACE, the editor will extract the word under or immediately to the left of the edit caret (note that this differs from keyword expansion, which requires that the caret be at the end of a word). If this word is blank (that is, the caret was on blank space), or if the word does not even partially match any keyword, an alphabetically-sorted list of all POV-Ray scene file keywords is displayed slightly to the right of and below the edit position. If the extracted word was blank, the list will be positioned at the first entry, otherwise it will be positioned at the keyword that is closest (alphabetically) to the extracted word.
If, however, the extracted word perfectly matches a keyword, and is not part of any other keyword in the list, then the list box does not appear. Instead, the keyword that it matched is inserted into the line and the edit caret is moved to the end of that keyword.
If the above match does not occur, then the alphabetically-sorted list of keywords is displayed, and the list is positioned such that the keyword that the extracted word most closely matches is highlighted and is as close as possible to the center of the displayed portion of the list.
If you look at the above image, you will see an example of this situation. The partial
keyword (just above and to the left of the top left-hand corner of the list box) is
'phon
', and the list has been positioned to the closest keyword, which is
'phong
'.
Once the list is displayed, you can cause the highlighted entry to be inserted into the line by just pressing ENTER, SPACE, TAB, or CTRL+SPACE again, or by double-clicking on a list entry. Pressing the ESCAPE key will remove the listbox without altering the line you are editing. You can navigate the listbox by using the up, down, page-up and page-down keys on your keyboard, by the mouse, or by typing (see below). If you cause text to be inserted by any of the above methods other than SPACE, the edit caret will be positioned immediately at the end of the inserted word. If, however, you press SPACE, the word will be inserted followed by a space, and the new edit position will be after the space.
While the list is displayed, even though the up and down arrow keys map to the listbox, the normal character keys still map to the editor. If you continue to type, the letters will be typed into the line at the editor caret position, and, additionally, the list box will automatically scroll so that the highlighted line is always the keyword that has the closest match to what you have typed in.
Just like keyword expansion, the codelist feature can seem complicated when explained in words. However, once you get used to it, it will become quite natural to use.
The built-in editor is extensively customizable. It utilizes syntax highlighting and understands .POV, .INC, .MAC, and .MCR 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, SQL, HTML and XML. Users can also add their own keywords for syntax highlighting and auto-completion in the editor. See the file ini\user-keywords.txt
located in the user's POV-Ray documents folder (or use the tool menu shortcut to open it).
One important thing to note right away is that the editor properties dialog only allows you to set things that are implemented within the editor (remember, the editor is two components - a DLL called 'povcmax32.dll' (or similar), and another DLL which loads and 'wraps' it into POV-Ray for Windows). 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 people have asked why the don't ask again option in the render save dialog is not persistent across sessions. This is by design and is not likely to change.
The edit window context menu has an option for 'show/hide message window'. This window - when displayed at the bottom of an editor window - is sizable. A quick way to close the message window is just to hit ESCAPE, or 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 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. The text describing the error will be displayed in the status bar at the bottom of the window. Note that, occasionally, if the error occurs inside a macro, the displayed line/column for the error will be wrong (though this is uncommon).
Listed below is the complete set of default keystrokes and the CodeMax command that each keystroke maps to. Note that many depend on caret position. If two sets of keystrokes are listed, either may be used (e.g. 'Copy' is defined as 'Ctrl + C or Ctrl + Insert', which means that you may use either 'Ctrl + C' or 'Ctrl + Insert' to perform a copy; whichever suits you. There is no difference between one or the other).
Note that if more than one key sequence is assigned to a command, and the command is one of those listed in the menus (not all commands are listed in the menus), the key sequence shown as the shortcut key in the menu is generally the shortest one (in terms of its printed representation).
You can change any of the below-mentioned key assignments if the defaults don't suit you. Additionally, the below table does not list the more than 50 commands for which there is no default key assignment. Use Alt + Enter on an editor screen, or select 'Codemax Properties' from the Editor menu to assign these.
BookmarkNext | F2 | Move to next bookmark |
BookmarkPrev | Shift + F2 | Move to previous bookmark |
BookmarkToggle | Ctrl + F2 | Place a bookmark |
CharLeft | Left Arrow | Move caret left |
CharLeftExtend | Shift + Left Arrow | Move caret left and highlight |
CharRight | Right Arrow | Move caret right |
CharRightExtend | Shift + Right Arrow | Move caret right and highlight |
CodeList | Ctrl + Space | Show keywords (reference or insertion into file) |
Copy | Ctrl + C or Ctrl + Insert | Copy selection to clipboard |
Cut | Ctrl + X or Shift + Delete | Remove selection to clipboard |
CutSelection | Ctrl + Alt + W | Remove selection (same as Cut) |
Delete | Delete | Delete one character right (can Undo) |
DeleteBack | Backspace or Shift + Backspace | Remove one character left (can Undo) |
DocumentEnd | Ctrl + End | Move to end of file |
DocumentEndExtend | Ctrl + Shift + End | Move to end of file and highlight |
DocumentStart | Ctrl + Home | Move to start of file |
DocumentStartExtend | Ctrl + Shift + Home | Move to start of file and highlight |
Find | Alt + F3 or Ctrl + F | Find, or search |
FindNext | F3 | Find next (specified) |
FindNextWord | Ctrl + F3 | Find next (selected) |
FindPrev | Shift + F3 | Find previous (specified) |
FindPrevWord | Ctrl + Shift + F3 | Find previous (selected) |
FindReplace | Ctrl + Alt + F3 or Ctrl + H | Find/Replace dialog |
GoToLine | Ctrl + G | Move to a line number dialog |
GoToMatchBrace | Ctrl + ] | Match brace }, bracket ], or parenthesis ) |
Home | Home | Move to start of line text (or line) |
HomeExtend | Shift + Home | Move to start of line and highlight |
IndentSelection | Tab | Indentation (number of spaces set in properties) |
LineCut | Ctrl + Y | Remove current line |
LineDown | Down Arrow | Move to next line |
LineDownExtend | Shift + Down Arrow | Move to next line and highlight |
LineEnd | End | Move to end of line text (or line) |
LineEndExtend | Shift + End | Move to end of line and highlight |
LineOpenAbove | Ctrl + Shift + N | Make new line above current line |
LineUp | Up Arrow | Move to previous line |
LineUpExtend | Shift + Up Arrow | Move to previous line and highlight |
LowerCaseSelection | Ctrl + U | Change highlighted text to lower case |
PageDown | Page Dn | Move down a page |
PageDownExtend | Shift + Page Dn | Move down a page and highlight |
PageUp | Page Up | Move up a page |
PageUpExtend | Shift + Page Up | Move up a page and highlight |
Paste | Ctrl + V or Shift + Insert | Place clipboard contents into file |
Properties | Alt + Enter | CodeMax properties dialog |
RecordMacro | Ctrl + Shift + R | Record/stop a macro |
Redo | Ctrl + Y | Redoes last undone action (i.e. undo an undo) |
SelectAll | Ctrl + A | Highlight entire file |
SelectLine | Ctrl + Alt + F8 | Highlight the current line |
SelectSwapAnchor | Ctrl + Shift + X | Switch place of caret with start of highlighting |
SentenceCut | Ctrl + Alt + K | Remove a continuous line to clipboard |
SentenceLeft | Ctrl + Alt + Left Arrow | Move to start of continuous line |
SentenceRight | Ctrl + Alt + Right Arrow | Move to end of continuous line |
SetRepeatCount | Ctrl + R | Number of times to do next command |
TabifySelection | Ctrl + Shift + T | Change highlighted spaces to tabs |
ToggleOvertype | Insert | Toggle between inserting and overwriting |
ToggleWhitespaceDisplay | Ctrl + Alt + T | Show or hide spaces |
Undo | Ctrl + Z or Alt + Backspace | Undo last change |
UnindentSelection | Shift + Tab | Remove indentation of selected line |
UntabifySelection | Ctrl + Shift + Space | Change highlighted tabs to spaces |
UpperCaseSelection | Ctrl + Shift + U | Change highlighted text to upper case |
WindowScrollDown | Ctrl + Up Arrow | Scroll file down, leaving caret |
WindowScrollLeft | Ctrl + Page Up | Scroll file left, leaving caret |
WindowScrollRight | Ctrl + Page Dn | Scroll file right, leaving caret |
WindowScrollUp | Ctrl + Down Arrow | Scroll file up, leaving caret |
WordDeleteToEnd | Ctrl + Delete | Delete a word from caret to end |
WordDeleteToStart | Ctrl + Backspace | Delete a word from caret to start |
WordLeft | Ctrl + Left Arrow | Move to start of current word |
WordLeftExtend | Ctrl + Shift + Left Arrow | Move to start of current word and highlight |
WordRight | Ctrl + Right Arrow | Move to end of current word |
WordRightExtend | Ctrl + Shift + Right Arrow | Move to end of current word and highlight |
Most of the keystrokes used by the editor are re-assignable - even those listed in the menus. (Some users have assumed that commands with shortcuts listed in the menus aren'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 keyboard actions assigned to it, and each keyboard action 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 key sequence to a command, and the command is one of those listed in the menus (not all commands are listed in the menus), the one that is listed in the menu as the shortcut key is generally the shortest one (in terms of its printed representation).
You can access the keystroke assignments via the CodeMax properties dialog. By default, this is mapped to Alt+Enter when an editor is displayed. Alternatively, you can get at it from the Editor menu (only visible when an editor is selected) or the editor right-mouse-button context menu.
Not all commands are assignable ! In general, only the commands that are directly implemented in the CodeMax editor DLL 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.
The editor supports the following mouse actions:
Left click over text | Changes the caret position |
Right click over open file | Displays the pop-up menu |
Left Button down over selection, hold and drag | Moves text |
Ctrl + Left Button down over selection, hold and drag | Copies text |
Left click over left margin | Selects line |
Left click over left margin, hold and drag up or down | Selects multiple lines |
Alt + Left Button down, hold and drag | Select columns of text |
Left double click over text | Select word under cursor |
Spin IntelliMouse (compatible) mouse wheel | Scroll the window vertically |
Single click mouse wheel | Select the word under the cursor |
Double click 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 |
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. 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 ')').
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, .INC, .MCR and .MAC 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 file-specific 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 the file was in the MRU list. This is by design.
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.
I/O Restrictions are a feature introduced in POV-Ray v3.5. The purpose of this feature is to attempt to at least partially protect a machine running POV-Ray from having files read or written outside of a given set of directories.
The need for this is related to the fact that the POV-Ray scene language has, over the years, become something more akin to a scripting language combined with a scene-description model. It is now possible to write obsfucated POV-Ray code, and to open, create, read and write arbitrary files anywhere on the target system's hard disk (subject to operating system permission).
The basic idea of I/O Restrictions is to attempt to protect the user from a script that may have been downloaded from an untrusted source, and which may attempt to create or modify files that it should not.
The I/O Restriction facility hooks the file open and creation functions in the core POV-Ray renderer code, and allows the Windows version to allow or deny any particular file operation. Please note that this only affects file I/O from the core POV-Ray code; that is, the code that implements the parser and renderer. It does not affect which files the Windows interface can read and write. That is to say, it does not prevent you loading a file into an editor, or saving a file from the editor, or any other feature implemented on the Windows interface that is not part of the core POV-Ray feature set. (The 'core feature set' is those features of POV-Ray that are available on all operating systems and computer platforms for which a version of POV is available).
We do not guarantee that the I/O Restriction facility will actually stop anything from happening. There is always the chance that, like almost all software, it could have a bug in it that causes it to malfunction. Therefore, the onus is on the person who chooses to load an INI or scene file into POV-Ray to ensure that it does not do anything that it should not do. I/O Restrictions are just a sometimes-helpful backup for manual checks.
Please read this section in full so that you understand the caveats and conditions of the facility (such as the fact that some directories are allowed by default).
Now to the details: how to configure the I/O Restrictions (or get them out of your hair if you want them turned off). Under the Options menu there is a sub-menu called Script I/O Restrictions.
![]() |
Script I/O Restrictions sub-menu |
This provides you with high-level control of the restriction subsystem. The top section of the menu provides you with three options (detailed below). You can only choose one of the three. The bottom section provides you with two additional options, either of which can be on or off.
If this option is chosen, POV scripts can read/write everything (subject to operating system permission). The I/O Restriction system is turned off.
If this option is chosen. POV scripts can read anything, but file creation and file write is only allowed in the implicit and user-specified directories (see Low-Level Configuration for more information on how to specify which directories).
Another way to put it is that I/O Restrictions are turned off for reading files, but not for writing them.
Both read and write by POV scripts is restricted to implicit and user-specified directories. Note that this is the default setting for a clean installation of POV-Ray for Windows.
Note that the above settings do not just affect scripted file I/O; they also affect things like include files, output files, and input .POV files. Basically any file-related input or output by the rendering engine. You should take careful note of this statement if you are in the habit of writing your output files to anywhere other than the same directory as the scene file is in (see below).
In addition to the above, there are two other options:
If turned on, the current directory (but not any below it) is automatically added to the allowed list of read/write locations. Since POVWIN sets the current directory to that which contains the source file (.pov or .ini) at the start of a render, this automatically enables the location containing a scene for read/write. For most people, this is a useful feature, so it is on by default for a clean install.
Please note that having this option unchecked does not prevent read in the current directory if you have turned off read restrictions (as documented above), and nor will it prevent writing if you have turned off I/O Restrictions altogether. Also, turning it on will not allow read/write in subdirectories of the current directory - just that dir alone.
If this option is selected (the default), shell-outs will not be permitted. 'Shell Outs' are a facility where an INI file can specify that a particular program be run either before or after a frame is rendered as well as at other points in the parse/render process. If you want these, you have to explicitly allow them by unchecking this option.
This section tells you how to manually specify explicit directories for read/write access, if the standard settings aren't suitable. First we need to cover what is and isn't protected by default.
The overall concept of the I/O Restrictions, when enabled, is that everything should be denied unless it is explicitly allowed (with one or two exceptions). So unless you add a directory to the 'allowed' list, unless it is one of the implicitly allowed locations then the directory in question is not permitted to be accessed.
The exceptions to the 'deny everything' rule (referred to above as 'implicit' locations) are as follows:
Note: The INI subdirectory contained within the document install directory is permanently write-protected (unless the I/O Restriction system is turned off). Even if you grant permission to write this dir from he below INI file, writes will not succeed. This is to prevent the INI file that contains the I/O Restriction configuration from being modified by a script to grant itself more access next time POVWIN is run.
To add or change allowed directories, you'll need to modify the file <installdir>\ini\pvengine.ini
,
where <installdir>
is where the POV-Ray for Windows user-editable files where installed. An easy way
to get at this file is to select it from the tools menu (by default, it is the second item).
Within PVENGINE.INI
you may see two sections like the following ... (note
that the actual contents of the installed version are slightly different from this example).
[Permitted Input Paths] 1=%INSTALLDIR% [Permitted Output Paths] 1=%INSTALLDIR%
If they are not present, it means that POVWIN is using the defaults, in which case you may add them. For example, %INSTALLDIR% is implicitly allowed for input and does not need to be added to the INI file (though there is no harm in doing so).
%INSTALLDIR%
resolves to the location that the POVWIN user-editable files were installed. It would be
legal to say something like -
%INSTALLDIR%\scenes
for example, to refer to (say) C:\Users\Joe\Documents\POV-Ray\3.7\Scenes
.
Relative paths are legal as well, and will be resolved only once at load time (but relative to the current directory, not the documents folder). For example, a relative path like the following ...
[Permitted Output Paths] 1=..\output
would be resolved with relation to the current directory at the time POV-Ray for Windows was
started, so if you started pvengine.exe from the directory c:\myscenes\newscene
,
then the above path would be resolved as c:\myscenes\output
. Please note that the
actual location of the POV-Ray executable file is not relevent here - it is the current directory that
matters (which is not necessarily that of the program installation). You only need to care about this
if you want to use relative paths in the restrictions setup: 99% of users don't, so if it doesn't make
sense, don't worry :-)
A directory placed in the permitted input paths section only allows read. One placed in the output paths section permits both read and write; write permission is inferred to mean read permission. This means you don't need to duplicate entries (the above example shows such a duplication - it is not harmful, just unnecessary). You can have up to 64 entries (numbered 0..63) in each section.
An entry in the permitted paths sections gives permission not only for that directory, but all the ones below it (note that this is different from the 'permit read/write in current directory' option mentioned earlier, which only applies to that one directory alone, and not those below it).
A reminder that, as mentioned above, if write protection is turned on at all, the
<installdir>\INI directory
is always write-protected, and nothing in the
above permission sections should be able to allow it. This is to prevent a script from modifying
pvengine.ini to remove or alter the I/O Restrictions for the next time that POVWIN runs.
Some users have POV-Ray set up such that all images are written into the same output directory. To make this work with I/O Restrictions active, and assuming the output directory isn't in the POV-Ray for Windows document folder, you will need to add that directory to the permitted output list.
For example, if your image output directory is c:\images\
, you could have something
like this in the INI file -
[Permitted Input Paths] 1=%INSTALLDIR% [Permitted Output Paths] 1=%INSTALLDIR% 2=c:\images
If you want to grant access to an entire drive (e.g. d:\), just add it like this -
[Permitted Input Paths] 1=%INSTALLDIR% [Permitted Output Paths] 1=%INSTALLDIR% 2=c:\images 3=d:\