Difference between revisions of "Documentation:Windows Section 3"

Latest revision as of 14:41, 4 July 2017

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

Command-Line Options

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

You can store them in the INI\POVRAY.INI file located within the POV-Ray documents directory. This is the master INI file. Whenever you start a render, this file is read before any other INI file. If you want to make changes to the way POV-Ray works by default, you should make them in this file. The Tools menu contains an entry to edit this master POVRAY.INI.
You can store them in an POVRAY.INI file in the directory containing the file being rendered. POV-Ray looks for a POVRAY.INI file in this location whenever it starts rendering after it has read the master POVRAY.INI file. Options in this INI file will thus override options specified in the master POVRAY.INI.
You can store them in an INI file created for a particular scene (this is a standard POV-Ray feature not specific to Windows).
You can enter them on the command line (see Command Line Dialog or the Toolbar Command Line). Any command-line option override any options specified elsewhere (i.e. they have the highest priority). POV-Ray for Windows interprets the command line from left to right, so that any option (or INI file) on the command line overrides a corresponding option (or another INI file) to its left on the command line.

POV-Ray Documents Directory

The 'POV-Ray Documents Directory' is the file folder on your computer that the user-editable files for POVWIN are stored. The default for this has changed in version 3.7. In prior versions, this was called the 'Home Directory' and was the same location that the POV-Ray program itself was installed in. Due to changes required to support Windows Vista and later, POVWIN now installs in two folders: the first, holding the program and any support files that are not user-specific (such as the help), is placed wherever you specified it be placed during install (by default this will be in Program Files).

The location of the POV-Ray Documents directory containing user-editable files (include and INI files, sample scenes, insert menu, etc) now defaults to <Your Documents Folder>\POV-Ray\vX.y. You may specify a different location upon install if you wish.

Note: System admins/lab techs should check the /INSTALL command-line option for means of customizing the above.

Special Command-Line Options

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

Note: Do not confuse the term 'command-line options' in this section with the toolbar command-line. The command-line we are referring to here is the one used to start the POV-Ray for Windows program file. The following special command-line options cannot be used on the toolbar command-line or in the command-line dialog.

The /DEMO command tells POV-Ray to run its demonstration render. All other options on the command-line are ignored.
The /EXIT command tells POV-Ray to perform the render given by the other command-line options, combined with previously-set options such as internal command-line settings, INI file, source file, and so forth, and then to exit. By default, if this switch is not present, POV-Ray for Windows will remain running after the render is complete. This switch only applies to renders started by other options on the command-line. It will not affect renders started manually from within POV-Ray for Windows itself.
The /NR command (same as /NORESTORE) tells POV-Ray for Windows to not attempt to restore any previous edit sessions (i.e. files that were open in the editor). This is handy when you had a large number of files open and you don't want them taking up time loading.
The /RENDER command tells POV-Ray for Windows to render the file following. Only one command is permitted on the command-line. Wildcards are not permitted.
The /EDIT command causes POV-Ray to load the following file into an editor. You can have multiple commands on the command-line, with one file per command. The filenames may not contain wildcards.
The /EDITDLLPATH normally would not be needed, unless the DLL isn't in the expected location and isn't stored with the EXE. It excepts a PATHNAME as an argument.
The /INSTALL and /QINSTALL options are to ease non-standard installations of POV-Ray. See below for more information.
The /THREADS option allows you to specify how many threads are used during renders (this value can also be set via a menu option but is - by design - not persisted).
The /DEBUG option turns on a number of debugging features related to POVWIN specifically (i.e. not related to rendering or the core code). During startup some additional information is written to the message pane. Further, the same information is written to the Windows debug facility via OutputDebugString. Finally, the file c:\temp\povdebug.txt will be created (provided that the c:\temp directory already exists) and the debug output sent there as well. If the file already exists, it is deleted prior to re-creation. The file is opened and closed each time it is appended to during the session.
The /BENCHMARK option runs the standard POV-Ray benchmark. See below for more details.

Note: When supplying a filename with spaces in it, you will need to enclose the filename itself within quotes.

The Benchmark Command-line Option

The /BENCHMARK command-line option causes POVWIN to begin rendering the standard POV-Ray benchmark as soon as it is launched, then exit. Normally no dialogs should be presented - the intention is to allow for the benchmark to be rendered without user interaction. The results of the benchmark are automatically placed into the clipboard at the end of the run, and additionally saved to a file in the POV-Ray documents directory (this is the same location that the include file and sample scene folders are placed upon installation - by default this is c:\users\<username>\Documents\POV-Ray\vX.y). The file name is in the format benchmark-YYYYMMDD.HHMMSS.txt, where the timestamp represents the time the render completed. An example of the file content is below.

CPU time used: kernel 0.87 seconds, user 2049.90 seconds, total 2050.77 seconds.
Elapsed time 274.16 seconds, CPU vs elapsed time ratio 7.48.
Render averaged 956.16 PPS (127.83 PPS CPU time) over 262144 pixels using 8 thread(s).

Render of benchmark version 2.01 completed at Saturday, September 21, 2013 06:34:15 UTC.
----------------------------------------------------------------------------
cpuarchitecture=9
numberofcpus=8
processortype=8664
processorlevel=21
processorrevision=258
cpufrequency=3612
cpufeatureset=540753406
cpuname=AMD FX(tm)-8150 Eight-Core Processor           
cpuidentifier=AMD64 Family 21 Model 1 Stepping 2
cpuvendoridentifier=AuthenticAMD
osversion=6.1
osbuild=7600
csdversion=
physicalmemory=12843241472
povversion=3.7.0
compilerversion=.msvc10
platformversion=win32

Most of the contained information is self-explanatory. To interpret the values shown for fields such as cpuarchitecture, please consult the Microsoft documentation for the GetNativeSystemInfo() Win32 API call.

Non-Standard Installations

The /INSTALL and /QINSTALL command-line switches should not normally be needed. They exist to make it easier for POV-Ray to be set up in a lab environment or otherwise used without having to perform a full installation. See below for detailed information.

Background

POVWIN does not require the normal registry entries (HKCU\Software\POV-Ray) to be present in order to function. It can, if need be, infer the information it needs at run-time, provided a standard layout is used. If this works for you, it may not be necessary to install anything. The only support binaries needed by the program are expected to be in the bin directory along with the executable; these are the editor DLL's, the crashdump utility (optional), and dbghelp.dll (also optional, and only needed for crashdumps). There is no dependance on dynamic run-time libraries outside of the standard ones shipped with Windows.

The two distinct locations POVWIN needs to know of are the location of the non-user-specific files (DLL's, help files, etc), and the location of the user-specific files. The normal layout is to have the EXE's and DLL's in a bin directory, help files in help, sound files in sound, and background bitmap tiles (not used by default) in tiles. All of these directories should be contained in the same parent directory or the root of a drive or network mapping. This location (referred to as the 'Home' directory in previous versions of POVWIN) is used by POVWIN to work out where to find e.g. the help file if F1 is pressed. The second location is the place where the user-editable files are expected to be found. This covers the include files, sample scenes, and the INI folder used to read and store settings that aren't obtained from the registry.

If the home directory is not specified in the registry, POVWIN will attempt to work it out by looking at the path from which it was loaded, then taking the parent of that and looking for the help directory within that. So for example if POVWIN was loaded from m:\foo\bar\bin\pvengine32.exe, it would look for m:\foo\bar\help. If this is not found it will look for sounds and then finally tiles. If any of these succeed it will infer that this parent directory is the home and store that for the session along with a value in the registry that lets POVWIN check if it has changed (the Home registry key is not set however). The first time this infer succeeds, a message is displayed in a dialog saying so. The next time POVWIN starts it will do the infer again and if the location has not changed it won't display this message.

If the POVWIN documents directory is not stored in the registry, POVWIN will - each time it is run - look for its presence in the default location, which is <User's Documents Folder>\POV-Ray\vX.y. If that directory does not exist, it will be automatically created along with the INI directory beneath it. No error message is issued if this create fails, however, nor will it prevent POVWIN from working (provided any needed source/include files can be located elsewhere).

If you want to persist the inferred location, or want to provide custom locations for the above without the need to run an installer on each workstation, you may use the /INSTALL or /QINSTALL command-line switches as documented below.

The /INSTALL and /QINSTALL switches

/INSTALL and /QINSTALL operate identically except that if you use /QINSTALL, any actions taken are performed quietly and any questions that would normally be asked are defaulted.

The syntax is /INSTALL [home dir] [user dir], where home dir is the location of the directory containing the bin, help etc folders as described above, and user dir is that of the POV-Ray user documents folder. The paths, if supplied, must be quoted if they contain spaces. If called without parameters, POVWIN attempts to infer the first path as normal and if successful writes this location to HKCU and (if permissions permit) to HKLM. When run normally POVWIN will first look in HKCU then HKLM for the home directory, so this can be used to set a machine-wide value.

If called with one parameter, the action is the same as for no parameters, except that no infer is done: the supplied path is just written to the registry.

If called with two parameters, the action is as above, and the second parameter is taken to be the location of the user files directory. This is checked for validity; if it does not exist a dialog will ask if you wish to use it anyway (unless you specified quiet, in which case the answer defaults to 'yes'). This value is then written to the registry under HKCU; there is no HKLM equivalent at this point.

For most cases, the zero or one parameter version would be sufficient, as POVWIN is quite happy to use the default location for the user documents and will not issue any messages if it doesn't exist.

Publishing via Group Policy

If you wish to push the settings out via GP, there's only one or two values you need to supply. The main one is the location of the home dir containing the binaries etc. This is HKCU\Software\POV-Ray\vX.y\Windows\Home, which is a REG_SZ containing the path. Alternately you may place this into the same location within HKLM on each workstation; either is sufficient (with HKCU being checked first).

The second value is that of the user files directory: HKCU\Software\POV-Ray\vX.y\Windows\DocPath, also a REG_SZ. There is no HKLM equivalent of this.

In either case, if the version of POV-Ray changes, the registry key will change accordingly, but only for X.y releases; e.g. 3.9 would use HKCU\Software\POV-Ray\v3.9\..., but 3.8.1 would still use HKCU\Software\POV-Ray\v3.8\.... This allows multiple versions of POV-Ray to be used on the same system.

System Admins / Lab Techs

If you need to do custom installation of POVWIN, please see Non-Standard Installations. If you want to use our standard installer, please note it is built with NSIS and is thus not available as an MSI. [We did experiment with MSI's - for about two years our betas were MSI-based - but after some bad experience with InstallShield decided to go with an open-source installer.]

Please note also that any official Windows binaries distributed by the POV-Ray developers will be signed. This includes the setup executable itself and all DLL's and EXE's contained within it. The key as of the time of writing (February 2013) is issued by DigiCert to Persistence of Vision Raytracer Pty Ltd and has a thumbprint of 32 61 e6 2e 2e e8 2a fa 71 2f a2 0e 89 b6 5b a0 68 35 20 e4.

Note: The POV-Ray developers would like to extend thanks to DigiCert for providing us with the above code-signing key and also our site SSL certificates.

Adding New Resolutions

The 'Preset Rendering Options' drop-down combobox on the toolbar provides a quick way of choosing previously specified sets of rendering options. The contents of this combobox can be modified. Here's how to do it.

All the resolution and rendering options that are available in the combobox mentioned above, are in fact loaded from an INI file. The INI file is called QUICKRES.INI by default, and is located in the INI folder within the POV-Ray documents folder referred to above. This file is known as the 'secondary INI file' (or 'resolution INI file') because it is loaded after the main POVRAY.INI (see INI Files for more information). You can also change the current secondary INI file selection from the Render Settings dialog.

An easy way to edit the secondary INI file is to select 'Edit Resolution INI File' from the Tools menu. Each section (delimited by '[' and ']') in this file will, once POV-Ray for Windows is restarted, be loaded into the resolution combobox for you to choose. Of course, you are not limited to resolutions; the sections can contain any valid POV-Ray INI file options, such as output file type, anti-aliasing, radiosity settings, etc.

To add a new resolution, just add a new section and re-start POV-Ray. Here's an example of what you could add to insert the new resolution 1600 x 1200 with AA 0.3. The entry will appear on the resolution list with the name 'Big and Slow' -

[Big and Slow]
Width=1600
Height=1200
Antialias=On
Antialias_Threshold=0.3

The name of the section between the square brackets ('Big and Slow') is what you see in the resolution list.

One more thing - you don't need to add a new resolution to the INI file if you don't want to. You can still, as always, specify an arbitrary resolution on the command-line via the Render Settings Dialog mentioned above or via the toolbar command-line.

Note: One occasional mistake made by users of previous versions of POV-Ray for Windows was to assume that the list of resolutions available in the above toolbar combobox was fixed and unable to be changed (some even thought that POV-Ray could not render any resolutions other than those listed in the combobox ... despite the documentation saying otherwise). This is a good illustration of the need to read documentation.

For Those Who use an Image Output Directory

Windows