Windows Section 5.2Documentation
This document is protected, so submissions, corrections and discussions should be held on this documents talk page.
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. It is only visible if you have selected an editor window.
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.
It has the additional special feature that menu entries may optionally have an image file associated with them, which is displayed when that entry is highlighted. A set of these image files is shipped with POV-Ray for Windows as standard; you can re-render these at a higher resolution if you like - see Re-Render Insert Menu Bitmaps in the Other Settings sub-menu menu.
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.
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.
Sorting the Insert Menu
It is possible to order the insert menu entries any way you like, both for folders and for the files (or sub-folders) within them. Normally, the entries are added to the menu in alphabetical order, with all folders being added before files. However, you can influence the ordering of each group (folders and files) by prepending a 'NN - ' to a folder or file, where 'NN' is any letter or digit (note however that this does not permit you to place a file before a folder).
For example, suppose you wanted to move the folder called '
(which creates the menu entry called '
Transformations' in the above sample
image) so that it appears between the '
Expressions' and '
items in the menu. You could achieve this by re-naming the folder from '
to, say, '
F0 - Transformations' (the choice of '
F0' in this
example is arbitrary - you could use anything that will alphabetically sort between
Expressions' and '
When the editor code builds the insert menu (which happens each time you change it), any file or folder that starts with a prefix of 'NN - ' (note the trailing space) will be sorted using the prefix, but displayed without the prefix.
Adding a Separator
Creating a special file called '
-.txt' (a hyphen followed by
usually prefixed by a '
NN - ' (e.g. '
30 - -.txt'), will cause
a menu separator to be drawn instead of inserting a new item into the menu. The contents
of the file are ignored.
To create a separator between sub-menus, do the same thing as above, but create a folder instead
of a file and leave off the '
Using the Insert Menu
Each Insert Menu text file can have an associated BMP, JPG or PNG file that provides a preview of the item that the text file can generate. In the previous example image, the item provides the
no_reflection keyword, so the preview image shows a rendered example of this in use. 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.
The Render Menu contains options that relate to starting, stopping, and controlling the rendering process (i.e. the generation of images).
Edit Settings/Render dialog
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 dialog
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
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.
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.
This command instructs POV-Ray for Windows to run the standard POV-Ray benchmark file, using a given set of options. In version 3.7 the built-in benchmark mode has been further modified to run without accessing any other distribution files, so now benchmarking can now be done with just the compiled executable.
Note: The file itself and the options used are built into the program and may not be changed (this includes the resolution). Any options specified on the command-line will be ignored.
Be aware that during the render, there is no image display, and furthermore, no output file is produced. The only purpose of the benchmark command is to determine how long it takes to render the standard file with the specific options used.
Immediately before POV-Ray for Windows starts writing the render information to the message display, it will output a line telling you what version of the official benchmark is being used.
Note: If you choose to quote your benchmark results publicly, it is essential that you include the benchmark version and the exact version of POV-Ray that you ran it on. Changes to the benchmark file itself, and optimizations to POV-Ray, may make comparisions between different versions of the benchmark or different versions of POV-Ray meaningless, especially if it is CPU performance that you are testing.
The actual benchmark file used is built-in to the program; it is not dependent on the
benchmark.pov file which is included in the
~\scenes\advanced directory. However, if you want to run the benchmark manually, or on another platform, you may use that file (just make sure it is the same version). The file also contains the recommended command-line parameters to be used with the render.
After the benchmark completes a dialog box will be displayed showing the average PPS (pixels per second) that the render took. Larger numbers are better (indicative of a faster and/or more efficient CPU). We recommend using this number when quoting results. The results are also copied to the clipboard.
File Queue dialog
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 check-boxes 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: 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. (We can't swap them back to their original position since we can't tell if the transposition has happened in the first place).
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.
The available render priority settings are 'Low', 'Normal, 'High' and 'Background'. Changing this setting can allow POV-Ray to get more (or less) of the CPU during renders; the higher the priority, the more CPU time should be allocated to POV-Ray. The Background setting is only available on Windows Vista or later, and causes the render to be run at a very low priority.
Some users have expressed surprise that changing render priority does not always seem to significantly affect rendering times. This will be the case if the computer in question is not doing anything else at the time. All the render priority setting does is tell Windows to change the priority it assigns to POV-Ray when it is sharing the CPU time out amongst processes. This generally only matters when you are running another CPU-intensive process on the computer; i.e. one that would compete with POV-Ray for a share of CPU time. It is then that changing this setting will make a noticeable difference. If the computer isn't doing much (other than running POV-Ray), then the render is already getting more or less all of the CPU time.
See also Speed Considerations.
The Duty Cycle setting is provided only for unusual cases of heat accumulation. It is not intended to be used in other circumstances (as it offers little benefit other than as described below). Unless you are using a laptop in a restricted environment (or perhaps in orbit), this sub-menu will be of little interest to you.
Some computers - particularly laptops or notebooks - cool their CPU's by convection. No CPU fan is used. This can make this type of device prone to overheating in certain circumstances (for example, where circulation of air is restricted, such as in a confined space, or where hot air does not, by its nature, rise, such as in zero-gravity).
POV-Ray makes extensive use of a processor's Floating Point Unit (FPU), a portion of the CPU that is not normally prone to high activity over long periods. Such use can potentially cause the CPU to generate more heat. Additionally, high CPU activity can cause the unit's normal heat-reducing facilities (such as lower-power CPU modes) to be inactive.
The Duty Cycle setting is used to tell POV-Ray to only use a certain percentage of the CPU's available time, even if nothing else is competing for the CPU. For example, a duty cycle of 10% would cause POV-Ray, during a render, to sleep for 90% of the available time, and only render during 10% of it.
During rendering, if the duty cycle is not set to 100% (the default), POV-Ray will update the status bar at the bottom of the window if it is in sleep mode. This update will show how many seconds remain until rendering starts again (which is based around a ten-second cycle). For example, a duty cycle of 70% would see POV-Ray render for seven seconds, then sleep for three.
Note: While it may seem far-fetched to include a feature in POV-Ray that seems primarily to be of use in zero-gravity, it in fact is for this exact reason it is here. On 25 April 2002, African entrepreneur Mark Shuttleworth was blasted into space in a Russian Soyuz capsule. Accompanying Mark on this launch was a copy of POV-Ray for Windows v3.5 beta 15, and a special scene written for the purpose by two of the word's best POV-Ray artists. Whilst on the International Space Station, Mark rendered a 6000x8000 pixel version of that scene. This scene is now available as a poster; see our website for more information.
Thread Count dialog
Selecting this entry displays a dialog allowing you to set the number of threads used for rendering. The default value varies according to system, but in general should be equal to the number of cores available to POVWIN (or double that if hyperthreading is available). Changing this value will only affect new renders and does not persist (i.e. it is not saved upon exit). This is by design. If you wish to set a permanent value please modify POVRAY.INI or set it on the command-line.
This option, which is enabled by default, instructs POVWIN to request that Windows not go into low-power or sleep mode whilst a render is in progress. During renders if this option is set POVWIN will notify Windows once every 10 seconds that it needs use of the system; unless Windows is instructed (via power management settings) to ignore this advice it will not put the system into low-power mode. Note that this does not affect the screensaver or display power management, which will work as normal.
Sound Settings dialog
In the sound setting dialogue you can enable POV-Ray to signal the finishing of a render, a parse error and a render error or cancellation of a render. For each of the three signals a specific sound (WAV file) can be set.
The On Completion submenu allows you to specify what POV-Ray will do when it completes a rendering (or series of renderings, in the case of animations).
No special actions are taken.
This will cause POV-Ray for Windows to display a message window indicating that it has finished.
Exit POV-Ray for Windows
POV-Ray for Windows will exit after the render has completed.
This menu contains settings that change the operation of POV-Ray for Windows as a whole.
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.)
This option will alternately show or hide the toolbar, and can be used if you want more room for the editor.
Place in System Tray
Places POVWIN in the system tray on the taskbar. Double-click to restore POVWIN. You can also right-click to get a context menu.
Script I/O Restrictions
See the I/O Restrictions topic.
This sub-menu allows you to select the destination for the files that are dropped onto the POV-Ray window from Windows Explorer or similar file managers. See Dragging and Dropping Files for full information.
This sub-menu contains settings related to checking for updated versions of POV-Ray for Windows.
Periodically Check for Updates
The 'Periodically Check for Updates' feature - which is turned on by default - instructs POV-Ray for Windows to periodically ask our web server if there is a newer version of POV-Ray available than the one you are using.
Note: All POV-Ray does is check for a new version; it does not download it. We would never download files onto your computer without your permission.
If POV-Ray discovers that there is a new version available, it will display a page in your default web browser that looks something like the one depicted below -
POV-Ray attempts to be both intelligent and polite about the way that it does these checks. It will not perform one unless Windows tells it that the internet is already connected. In this way, it does not cause an annoying dialer dialog to pop up while you are working. Additionally, POV-Ray does not run the checks out of a scheduler or via any third-party program - you have to be actually running POV-Ray for Windows for anything to happen. It also won't run a check the first time it is started after installation, in order to give you time to turn off the update check option if that's what you want to do.
If it successfully contacts our web server and receives a 'yes' or 'no' answer as to whether an upgrade is available, it will not attempt again for several days. If, however, it failed in its attempt to contact the server, it will try again in no less than 24 hours. POV-Ray will never contact our server more than once per day.
Note: POV-Ray uses the Microsoft WinINet functionality to perform the above connection; this means that whatever settings have been configured in the 'Internet' applet of your control panel (e.g. your proxy server) will be applied to the request.
Include System Information
This option - which is turned on by default - instructs POV-Ray for Windows to include some information that is valuable to the developers when it sends the above update request.
Note: We would never intentionally send any information that personally identifies you or that could violate your privacy. All we are interested in is system information that will help us better cater our userbase when we create new versions of POV-Ray. Of particular importance to us is knowing common memory, CPU, and screen configurations employed by our users.
Here is an actual sample of the information that is sent, exactly as it appears on the wire (taken as of v3.5 release candidate 5). The data sent in the current version may vary from this, but is fundamentally the same concept.
TestVersion=3.5.beta.RC5.msvc.win32 CurrentVersion=3.5.beta.RC5.msvc.win32 CPUArchitecture=0x0000 NumberOfCPUs=0x0001 ProcessorType=0x024a ProcessorLevel=0x0006 ProcessorRevision=0x0404 OSVersion=5.0 OSBuild=0x00000893 CSDVersion=Service Pack 2 BitsPerPixel=32 HorzRes=1600 VertRes=1200 NumberOfMonitors=1 HasMouseWheel=1 CPUFrequency=1396 FeatureSet=0x00004fff CPUName=AMD Athlon(tm) Processor CPUIdentifier=x86 Family 6 Model 4 Stepping 4 VendorIdentifier=AuthenticAMD PhysicalMemory=1073201152 DefaultLanguage=English (Australia)
This tells us that the machine running POV-Ray was a single-CPU box equipped with an AMD Athlon CPU running at 1396mhz (1.4ghz), and had 1,073,201,152 bytes (1 gigabyte) of RAM. It is running version 3.5.beta.RC5.msvc.win32 of POV-Ray for Windows on version 5.0 of Microsoft Windows (this is Windows 2000), which had been patched up to service pack 2. It had a single monitor, set for a resolution of 1600x1200 pixels with 32 bits per pixel. Its mouse had a mouse wheel. The user's default language selection was English.
Information like this - while seeming rather mundane - is important to us because it tells us the sort of hardware that people are using POV-Ray on.
Check for Update Now
This command instructs POV-Ray to check for an updated version immediately. If an update is available the normal update message is shown (as described above). Otherwise a message will be shown indicating the outcome (e.g. no update available, failed to contact server, etc).
This sub-menu contains a number of less-commonly-used options so as to reduce clutter in the main options menu.
This sub-menu is designed to allow for selection of a video source for the experimental video image mapping feature. It is currently disabled pending a re-implementation of the capture code.
Turns the use of the internal editor on or off.
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.
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.
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. See also Clear Messages in the Edit Menu.
Save Settings on Exit
If you select this option, 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.
Hide New User Help
Selecting this option will cause the 'Help On This Menu' entries to be removed from all menus. We recommend you do this once you're an experienced user.
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.
Re-Render Insert Menu Bitmaps
The preview bitmaps distributed with the POV-Ray for Windows insert menu are of a fairly small size in order to keep the size of the distributed setup file down. However, it is easy to re-render them all at a larger size (though it may take a while on a slower computer).
Just select the 'Re-Render Insert Menu Bitmaps' option and leave POV-Ray for Windows running. Eventually all the bitmaps will be replaced with larger ones.
This sub-menu allows you to set certain properties of the message window.
Select Plain Background
If you have chose a background image for the message window and want to change back to a plain color, you can select this command. The background takes on the currently defined background color (see Background Color below).
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.
This command lets you determine which text color best fits the background you have selected for the message window.
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).
You can change the tiled bitmap POV-Ray for Windows displays in its message window. 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 tileable bitmaps other than the standard Marble one, using a 256-color display, will often not yield attractive results.
This sub-menu allows you to set certain properties of the render preview window.
Force 8 Bit Display
POV-Ray for Windows is capable of displaying a rendering scene in 24-bit color (Truecolor). This takes up more RAM than 8-bit mode: 3 bytes for every pixel in the rendered scene. If you do not have enough RAM to spare, you should select this option. 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.
Preserve Contents During Animation
If this option is enabled (the default) and you are rendering an animation, the contents of the render window (which shows the previous frame of the animation) are not erased prior to a new frame being started. This makes it easier to see subtle changes in the image output (such as a small object moving from frame to frame, while the rest of the image stays static).
Note that the render window contents are always erased prior to the first frame, regardless of the setting of this option.
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.
Note that this command is also available on the toolbar.
This causes the Render window to close automatically when rendering is complete. This is particularly useful if you're doing quick test renders at low resolution.
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, use the right-mouse button speed menu on the message window, or simply click the 'Show' toolbar button.
Note that this command is also available on the toolbar.
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. Note that if this option is set, you cannot hide the render window behind the main window (this can be a problem if you are rendering at the same time you are editing; hence the ability to set both modes via this option).
Note: If you enable this option, the 'Get Focus on Creation' and 'Hide When Main Minimized' options detailed below will be grayed out.
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.
Hint: A handy shortcut to remember is that hitting the Escape key when the render window gets focus will return focus to the main window. This is particularly useful after a quick test render.
Note: If the 'Keep Above Main' option documented above is enabled, this option will be grayed out. This is because 'Keep Above Main' implies 'Get Focus On Creation'. If you don't want the render window to get focus on creation, you will need to turn 'Keep Above Main' off.
Hide When Main Minimized
If you have 'Keep Above Main' turned off, 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: If the 'Keep Above Main' option documented above is enabled, this option will be grayed out. This is because 'Keep Above Main' implies 'Hide When Main Minimized'. If you don't want the render window to be hidden when the main window is minimized, you will need to turn 'Keep Above Main' off.
This sub-menu is identical to the main Editor Menu. It is included in the Options Menu for consistency.
|Allow Column Selection||Other Settings|
This document is protected, so submissions, corrections and discussions should be held on this documents talk page.