Difference between revisions of "Documentation:Windows Section 5.2"

Revision as of 01:53, 2 February 2013

This document is protected, so submissions, corrections and discussions should be held on this documents talk page.

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.

The Insert 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 above example image, the item provides the spiral2 pattern, so the preview image shows a rendered example of this pattern.

Preview images can be of any bit-depth, but if you want to distribute them we strongly recommend that they be no more than 8-bit. Additionally, they should be no larger than 640x480 pixels.

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.

The Insert Sub-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.

Render Priority Sub-Menu

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.

Duty Cycle Sub-Menu

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

On Completion Sub-Menu

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.

Drag'N'Drop Destination

	This sub-menu allows you to select the destination for the Drag'N'Drop function. See Dragging and Dropping Files for full information.
The Drag'N'Drop Sub-Menu

Online Operations

	This sub-menu contains two options relating to POV-Ray for Window's ability to contact the POV-Ray web site to determine if there is an updated version available.
Online Operations Sub-Menu

Check For New Versions

The 'Check For New Versions' 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 any 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 something like that - you have to be actually running the program for anything to happen. It also won't run a check the first time it is run 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. (By default, the update checks in release versions are set for every five days, though this may change). 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 rewrite POV-Ray for version 4.0.

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.

Allow Column Selection

Other Settings