Documentation:Windows Section 5.2
|
This document is protected, so submissions, corrections and discussions should be held on this documents talk page. |
Insert Menu
 |
|
The 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. 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 menu.
How the Insert Menu is Built
Physical Layout
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 'Transformations'
(which creates the menu entry called 'Transformations' in the above sample
image) so that it appears between the 'Expressions' and 'Headers'
items in the menu. You could achieve this by re-naming the folder from 'Transformations'
to, say, 'F0 - Transformations' (the choice of 'F0' in this
example is arbitrary - you could use anything that will alphabetically sort between
'Expressions' and 'Headers').
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 .txt)
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 '.txt' extension.
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.
See also Re-Render Insert Menu Bitmaps in the Other Settings menu.
Render Menu
 |
The Render Menu contains options that relate to starting, stopping, and controlling the rendering process (i.e. the generation of images). |
|
The Render Menu |
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. |
|
The Render Settings dialog |
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.
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.
Run Benchmark
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 |
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).
Clear Queue
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.
Prevent Sleep
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 Sound Settings dialog |
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).
Do Nothing
No special actions are taken.
Display Message
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.
Options Menu
 |
This menu contains settings that change the operation of POV-Ray for Windows as a whole. |
|
The 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.)
Show Toolbar
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. |
|
Update Checks sub-menu |
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 -
 |
|
A sample updated version available page |
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).
| Allow Column Selection | Other Settings |
|
This document is protected, so submissions, corrections and discussions should be held on this documents talk page. |