Difference between revisions of "Documentation:Windows Section 5.3"

From POV-Wiki
Jump to navigation Jump to search
m (heading changes, moved a sub-section and some cleanup)
m (generic version)
 
(45 intermediate revisions by 3 users not shown)
Line 7: Line 7:
 
<br>
 
<br>
 
<!--</wikitalk>--->
 
<!--</wikitalk>--->
<!--REMOVE--->===Options Menu===<!--THIS--->
 
====Online Operations====
 
<!--<indexentry primary "Options Menu, Online Operations">--->
 
<p>
 
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.
 
</p>
 
 
<p>[[Image:WinImgSubMenusOnline.gif|-]]</p>
 
====Check For New Versions====
 
<!--<indexentry "new versions, checking for" "checking for new versions" "updating POV-Ray">--->
 
<p>
 
The 'Check For New Versions' feature - which is turned on by default, unless you chose
 
to turn it off when given the opportunity during install - 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.
 
</p>
 
 
<p class="Note">
 
Note: All POV-Ray does is <i>check for</i> a new version; it does <b>not</b> download
 
it ! We would never download anything onto your computer without your permission.
 
</p>
 
 
<p>
 
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 -
 
</p>
 
 
<p>[[Image:WinImgSubMenusUpdatepage.gif|A sample 'updated version available' page.]]</p>
 
 
<p>
 
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 dialler dialog to pop up while you are working.
 
</p>
 
 
<p>
 
Additionally, it stricly limits how often it will try. As a rule, it will make one check
 
every seven days (or whatever longer period is required for you to both be using POV-Ray
 
and online at the same time. POV-Ray does <b>not</b> run the checks out of a scheduler
 
or something like that - you have to be actually running the program for anything to
 
happen).
 
</p>
 
 
<p>
 
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 at least seven 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.
 
</p>
 
 
<p>
 
If an update is available, POV-Ray will remember the version number of the new version.
 
If you choose not to download it, you will not be reminded about that version again.
 
</p>
 
 
<p class="Note">
 
Note: POV-Ray uses the Microsoft WinINet functionality to perform the above connection.
 
If this is not installed on your computer (e.g. you are running Windows 95 with
 
Internet Explorer version 3 or earlier), then the update functionality will not work.
 
Please also be aware that the WinINet components use whatever settings have been configured
 
in the 'Internet' applet of your control panel (e.g. your proxy server, etc).
 
</p>
 
 
====Include System Information====
 
<p>
 
This option - which is turned on by default, unless you chose to turn it off when given
 
the opportunity during install - instructs POV-Ray for Windows to include some information
 
that is valuable to the developers when it sends the above update request.
 
</p>
 
 
<p class="Note">
 
Note: we would <b>never</b> 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 for you, our users, when we rewrite POV-Ray for version 4.0.
 
</p>
 
 
<p>
 
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).
 
</p>
 
 
<pre>
 
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)
 
</pre>
 
 
<p>
 
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.
 
</p>
 
 
<p>
 
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. For example, we
 
today still do not know the most common resolution or color depth that users have.
 
We don't know how important 256-color or low-resolution support is, since we do not
 
know how many people are using that configuration.
 
</p>
 
 
<p>
 
By leaving this option turned on, you are helping us help all users in the future.
 
</p>
 
 
===Other Settings===
 
<!--<indexentry primary "Options Menu, Other Settings">--->
 
<p>
 
This sub-menu contains a number of less-commonly-used options so as to reduce clutter in the
 
main options menu.
 
</p>
 
 
<p>
 
[[Image:WinImgSubMenusOthersettings.gif|-]]
 
</p>
 
 
====Use Editor====
 
<p>
 
Turns the use of the internal editor on or off.
 
</p>
 
 
====Show Tips of the Day====
 
<p>
 
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.
 
</p>
 
 
====Show Tooltips====
 
<p>
 
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.
 
</p>
 
 
====Preserve Messages====
 
<p>
 
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 <!--<linkto "Edit Menu">Edit Menu</linkto>--->[[Documentation:Windows Section 5#Edit Menu|Edit Menu]].
 
</p>
 
 
<p>
 
N.B. Don't forget that the statistics for each completed render are available from the
 
<!--<linkto "Rerun Dialog">Rerun Dialog</linkto>--->[[Documentation:Windows Section 5.2#Rerun|Rerun Dialog]].
 
</p>
 
 
====Save Settings on Exit====
 
<p>
 
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.
 
</p>
 
 
====Hide New User Help====
 
<!--<indexentry primary "Help On This Menu">--->
 
 
<p>
 
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.
 
</p>
 
 
====Show Next Tip====
 
<p>
 
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.
 
</p>
 
 
====Re-Render Insert Menu Bitmaps====
 
<p>
 
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).
 
</p>
 
 
<p>
 
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.
 
</p>
 
 
====Message Window====
 
<!--<indexentry primary "Options Menu, Message Window" "Message Window Menu">--->
 
<p>
 
This sub-menu allows you to set certain properties of the message window.
 
</p>
 
 
<p>[[Image:WinImgSubMenusMessagewin.gif|-]]</p>
 
 
====Select Plain Background====
 
<p>
 
POV-Ray for Windows comes with a bitmapped background as default. If you prefer a plain
 
background, you can select this command. The background takes on the currently defined
 
background color (see Background Color below).
 
</p>
 
 
====Text Font====
 
<p>
 
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.
 
</p>
 
 
<p class="note">
 
Note: If you select italic text, this setting will not be preserved across invocations of POV-Ray.
 
</p>
 
 
====Text Color====
 
<p>
 
This command lets you determine which text color best fits the background you have selected
 
for the Main Window.
 
</p>
 
 
====Background Color====
 
<p>
 
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).
 
</p>
 
 
====Tiling Options====
 
<p>
 
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.</p>
 
 
<p> 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.
 
</p>
 
 
====Render Window====
 
<!--<indexentry primary "Options Menu, Render Window" "Render Window Menu">--->
 
 
<p>
 
This sub-menu allows you to set certain properties of the render window.
 
</p>
 
 
<p>[[Image:WinImgSubMenusRenderwin.gif|-]]</p>
 
 
====Force 8 Bit Display====
 
<p>
 
POV-Ray for Windows is capable of displaying a rendering scene in 24-bit color (Truecolor).
 
This takes up a great deal of RAM, however: 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!
 
</p>
 
 
<p>
 
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.
 
</p>
 
 
====Preserve Contents During Animation====
 
<!--<indexentry "animation, preserving window contents during">--->
 
 
<p>
 
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).
 
</p>
 
 
<p>
 
Note that the render window contents are always erased prior to the first frame, regardless
 
of the setting of this option.
 
</p>
 
 
====Re-display====
 
<!--<indexentry primary "Re-display Render Window">--->
 
 
<p>
 
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.
 
</p>
 
 
<p>
 
Note that this command is also available on the toolbar.
 
</p>
 
 
====Autoclose====
 
<p>
 
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.
 
</p>
 
 
====Close====
 
<p>
 
This command closes the Render Window. This does not interfere with any rendering activity.
 
Indeed, it speeds up rendering (see also <!--<linkto "Speed Considerations">Speed Considerations</linkto>--->[[Documentation:Windows Section 7#Speed Considerations|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.
 
</p>
 
 
<p>
 
Note that this command is also available on the toolbar.
 
</p>
 
 
====Keep Above Main====
 
<p>
 
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).
 
</p>
 
 
<p class="Note">
 
Note: if you enable this option, the 'Get Focus on Creation' and 'Hide When Main Minimized'
 
options detailed below will be grayed out.
 
</p>
 
 
====Get Focus on Creation====
 
<p>
 
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.
 
</p>
 
 
<p>
 
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.
 
</p>
 
 
<p class="Hint">
 
Hint: A handy shortcut to remember is that hitting the <b>Escape</b> key when the render
 
window gets focus will return focus to the main window. This is particularly useful after
 
a quick test render.
 
</p>
 
 
<p class="Note">
 
Note: if the 'Keep Above Main' option documented above is enabled, this option will be
 
greyed 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.
 
</p>
 
 
====Hide When Main Minimized====
 
<p>
 
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.
 
</p>
 
 
<p class="Note">
 
Note: if the 'Keep Above Main' option documented above is enabled, this option will be
 
greyed 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.
 
</p>
 
 
====Editor Window====
 
<p>
 
This sub-menu is identical to the main <!--<linkto "Editor Menu">Editor Menu</linkto>--->[[Documentation:Windows Section 5.1#Editor Menu|Editor Menu]]. It is
 
included in the Options Menu for consistency.
 
</p>
 
 
 
===Tools Menu===
 
===Tools Menu===
<!--<indexentry primary "Tools Menu" "Menus, Tools Menu">--->
+
{{#indexentry:Tools Menu, Menus}}
 +
{{#indexentry:Tools Menu}}
  
<p>
+
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
The Tools Menu provides you with a simple means of customizing POV-Ray for Windows. You can  
+
<tr>
develop your own commands (up to 32) to show up under this menu. Since the menu is determined  
+
  <td>
by the file PVTOOLS.INI, editing and reloading this INI file changes the Tools Menu.
+
    [[Image:win-toolsmenu.png|center|219px<!--left--->]]
</p>
+
  </td>
 +
  <td>
 +
    <p>The Tools Menu provides you with a simple means of customizing POV-Ray for Windows. You can develop your own commands (up to 32) to show up under this menu. Since the menu is determined by the file PVTOOLS.INI, editing and reloading this INI file changes the Tools Menu.</p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td>
 +
    <p class="caption">The Tools Menu</p>
 +
  </td>
 +
  <td></td>
 +
</tr>
 +
</table>
  
<p>[[Image:WinImgMenusTools.gif|-]]</p>
+
====PVTOOLS.INI Syntax====
 
 
====Syntax Coloring====
 
 
<p>
 
<p>
 
The syntax of entries in PVTOOLS.INI is as follows:
 
The syntax of entries in PVTOOLS.INI is as follows:
Line 428: Line 35:
 
<pre>
 
<pre>
 
[Menu]
 
[Menu]
Item<i>n</i>=Description
+
ItemN=Description
 
   
 
   
 
[Command]
 
[Command]
Item<i>n</i>=command_string
+
ItemN=command_string
 
   
 
   
 
[Help]
 
[Help]
Item<i>n</i>=help_line
+
ItemN=help_line
 
</pre>
 
</pre>
  
 
<p>
 
<p>
Where <i>n</i> is a number between 0 and 31, and entries in the <code>[Help]</code> section are optional.
+
Where <em>N</em> is a number between 0 and 31, and entries in the <code>[Help]</code> section are optional.
 
</p>
 
</p>
  
Line 457: Line 64:
 
to.  
 
to.  
 
</p>
 
</p>
 +
<p class="Note"><strong>Note:</strong> By default newer versions of Windows will not display
 +
the underline beneath the abbreviation until you press ALT. This means if you use the mouse
 +
to open the menu you won't see the underlines.</p>
  
 
<p><strong>[Command]</strong></p>
 
<p><strong>[Command]</strong></p>
 
<p>
 
<p>
This is the command that POV-Ray will execute for that entry. This can be a Windows EXE or
+
This is the command that POV-Ray will execute for that entry. This can be a Windows EXE, a batch
PIF, a DOS EXE or COM, or even a DOS batch file. The command consists of the actual command  
+
file, or anything else that may be executed by the Win32 ShellExecute() API call. The command
name followed by any parameters you want to supply to the program.<br>
+
consists of the actual command name followed by any parameters you want to supply to the program.<br>
There is one special command, called '$S'. $S means 'use the shell association for the  
+
There are two special commands, '$S' and '$E'. $S means 'use the shell association for the
filename that follows it'. Let's look at an example -</p>
+
filename that follows it', and '$E' means 'open the following file in the internal POVWIN editor'.
 +
Let's look at an example -</p>
  
 
<pre>
 
<pre>
Line 473: Line 84:
 
Since %1 refers to the output file (see below) this means that Item 4 of the tools menu  
 
Since %1 refers to the output file (see below) this means that Item 4 of the tools menu  
 
expands to a command to Windows to open the last output file with whatever program is  
 
expands to a command to Windows to open the last output file with whatever program is  
associated with it. For example, if the last output file was 'c:\images\torus4.bmp' then the  
+
associated with it. For example, if the last output file was '<code>c:\images\torus4.png</code>' then the  
above command example would use whatever program is associated with BMP files (i.e. the  
+
above command example would use whatever program is associated with PNG files (i.e. the  
program that Windows runs if you double-clicked on the TORUS4.BMP file in Windows Explorer) to  
+
program that Windows runs if you double-clicked on the <code>TORUS4.PNG</code> file in Windows Explorer) to  
 
open it.
 
open it.
 
</p>
 
</p>
  
<p class="Note">
+
<p class="Note"><strong>Note:</strong> If using the $S or $E special commands, <em>do not</em> quote
Note: If using the Shell Open command ($S), DO NOT quote the parameters with '&quot;', even if they
+
the parameters with '&quot;', even if they will have spaces in them. Both of these commands
will have spaces in them.
+
may only be supplied a single parameter, which is taken to be the entire line following the command.
 
</p>
 
</p>
  
Line 498: Line 109:
  
 
<p>
 
<p>
If you had installed POV-Ray for Windows into the directory 'c:\povwin3', then our standard  
+
If you had installed POV-Ray for Windows into the directory '<code>c:\povwin3</code>', then our standard  
INI file directory would be 'c:\povwin3\ini\'. When POV-Ray ran the above command, the '%i'  
+
INI file directory would be '<code>c:\povwin3\ini\</code>'. When POV-Ray ran the above command, the '%i'  
would be replaced with 'c:\povwin3\ini\'. Note that the trailing '\' is provided by POV-Ray.  
+
would be replaced with '<code>c:\povwin3\ini\</code>'. Note that the trailing '\' is provided by POV-Ray.  
 
This means that:
 
This means that:
 
</p>
 
</p>
Line 518: Line 129:
 
<p>Here are all of the predefined substitutions:</p>
 
<p>Here are all of the predefined substitutions:</p>
  
<table width="100%">
+
<table width="100%" class="option-list">
 
<tr>
 
<tr>
 
<td valign="top" width="10%">%0</td>
 
<td valign="top" width="10%">%0</td>
Line 540: Line 151:
 
<td valign="top">
 
<td valign="top">
 
The contents of the 'SceneFile' entry of the 'LastRender' section in PVENGINE.INI. This will  
 
The contents of the 'SceneFile' entry of the 'LastRender' section in PVENGINE.INI. This will  
be the scene file name for the last render, without the .POV extension. You can use this by  
+
be the scene file name for the last render, without the <code>.POV</code> extension. You can use this by  
 
appending a new extension to it. For example,
 
appending a new extension to it. For example,
  
Line 553: Line 164:
 
</pre>
 
</pre>
  
assuming the input file was myscene.pov and the current directory at that time was c:\scenes.
+
assuming the input file was <code>myscene.pov</code> and the current directory at that time was <code>c:\scenes</code>.
</td>
 
</tr>
 
<tr>
 
<td valign="top">%3</td>
 
<td valign="top">
 
The contents of the 'HistogramFile' entry of the 'LastRender' section in PVENGINE.INI. If
 
there was a histogram file written, this will be its name. If the histogram file was in .CSV
 
format, you'd probably use this to fire up Excel. Otherwise, you could use it to run a viewer
 
program or a post-processor.
 
 
</td>
 
</td>
 
</tr>
 
</tr>
Line 584: Line 186:
 
<td valign="top">%H</td>
 
<td valign="top">%H</td>
 
<td valign="top">
 
<td valign="top">
The POV-Ray for Windows home directory, as specified in the registry, e.g. 'c:\Program Files\POV-Ray for Windows v3.6\'.  
+
The POV-Ray for Windows install directory, as specified in the registry or inferred at run-
Note the trailing backslash is supplied.
+
time, e.g. '<code>c:\Program Files\POV-Ray for Windows vX.y\</code>'. Note the trailing backslash is supplied.
 +
</td>
 +
</tr>
 +
<tr>
 +
<td valign="top">%P</td>
 +
<td valign="top">
 +
The POV-Ray for Windows user documents directory, as specified in the registry or inferred at run-
 +
time, e.g. '<code>c:\Users\Joe\Documents\POV-Ray\vX.y\</code>'. Note the trailing backslash is supplied.
 +
This is the directory where the sample scenes, include files, and INI files are stored.
 
</td>
 
</td>
 
</tr>
 
</tr>
Line 591: Line 201:
 
<td valign="top">%I</td>
 
<td valign="top">%I</td>
 
<td valign="top">
 
<td valign="top">
The POV-Ray for Windows INI directory. e.g. 'c:\Program Files\POV-Ray for Windows v3.6\ini'.
+
The POV-Ray for Windows INI directory. e.g. '<code>c:\Users\Joe\Documents\POV-Ray\vX.y\ini\</code>'.
 
</td>
 
</td>
 
</tr>
 
</tr>
Line 619: Line 229:
 
<td valign="top">%T</td>
 
<td valign="top">%T</td>
 
<td valign="top">
 
<td valign="top">
The full path to PVTOOLS.INI. This is the file which holds the Tools Menu commands.
+
The full path to <code>PVTOOLS.INI</code>. This is the file which holds the Tools Menu commands.
 
</td>
 
</td>
 
</tr>
 
</tr>
Line 632: Line 242:
 
<p>
 
<p>
 
If any of the above seems confusing, there's an easy way to find out what's going on. If you  
 
If any of the above seems confusing, there's an easy way to find out what's going on. If you  
place the statement DEBUG=1 in the General section of PVTOOLS.INI, POV-Ray for Windows will  
+
place the statement DEBUG=1 in the General section of <code>PVTOOLS.INI</code>, POV-Ray for Windows will  
 
print out the string for each command both before and after it is expanded, instead of running  
 
print out the string for each command both before and after it is expanded, instead of running  
 
the command that you select in the tool menu. That way you can see exactly what POV-Ray  
 
the command that you select in the tool menu. That way you can see exactly what POV-Ray  
Line 663: Line 273:
 
<pre>
 
<pre>
 
[Help]
 
[Help]
Item8=Lets you shell out to DOS
+
Item1=Edit master POVRAY.INI in installation directory
 
</pre>
 
</pre>
  
 
<p>
 
<p>
This command makes the string 'Lets you shell out to DOS' appear on the status bar when the  
+
This command makes the string 'Edit master POVRAY.INI in installation directory' appear on the status bar when the  
mouse is over the 8th item in the Tools menu.
+
mouse is over the 1st item in the Tools menu.
 
</p>
 
</p>
  
Line 689: Line 299:
 
[Menu]
 
[Menu]
 
Item0=Edit &amp;master POVRAY.INI
 
Item0=Edit &amp;master POVRAY.INI
Item1=Edit &amp;last rendered file
+
Item1=Edit PVEN&amp;GINE.INI
Item2=Edit last &amp;scene file
+
Item2=Edit &amp;last rendered file
Item3=&amp;View last rendered file
+
Item3=Edit last &amp;scene file
Item4=View &amp;histogram image file
+
Item4=&amp;View last rendered file
 
Item5=Edit resolution &amp;INI file
 
Item5=Edit resolution &amp;INI file
Item6=Edit &amp;this menu.
+
Item6=Edit &amp;user-defined syntax file
 +
Item7=&amp;Browse sample scenes folder
 +
Item8=Edit &amp;this menu
  
 
[Command]
 
[Command]
# NOTE! If using the Shell Open command ($S), DO NOT quote the parameters with '&quot;'
+
# NOTE! If using the $E or $E, DO NOT quote the parameters with '&quot;'.
Item0=notepad.exe &quot;%hrenderer\povray.ini&quot;
+
# If you are calling a program directly, you will probably need to quote the
Item1=notepad.exe &quot;%r&quot;
+
# parameter; e.g. notepad.exe &quot;%r&quot;
Item2=notepad.exe &quot;%0&quot;
+
Item0=$e %pini\povray.ini
Item3=$S %1
+
Item1=$e %pini\pvengine.ini
Item4=$S %3
+
Item2=$e %r
Item5=notepad.exe &quot;%n&quot;
+
Item3=$e %0
Item6=notepad.exe &quot;%t&quot;
+
Item4=$s %1
 +
Item5=$e %n
 +
Item6=$e %I\user-keywords.txt
 +
Item7=$s %pscenes\
 +
Item8=$e %t
  
 
[Help]
 
[Help]
 
Item0=Edit master POVRAY.INI in installation directory
 
Item0=Edit master POVRAY.INI in installation directory
Item1=Edit the last file that POV-Ray was rendering
+
Item1=Edit PVENGINE.INI in installation directory
Item2=Edit the last scene file that you selected
+
Item2=Edit the last file that POV-Ray was rendering
Item3=View the output of the last render (assumes file output was on)
+
Item3=Edit the last scene file that you selected
Item4=View the histogram of the last render (assumes histogram image output was on)
+
Item4=View the output of the last render (assumes file output was on)
Item5=Edit secondary INI file as specified in Command-line dialog.
+
Item5=Edit secondary INI file as specified in Command-line dialog
Item6=Edit PVTOOLS.INI to alter this menu
+
Item6=Edit the user-defined syntax highlighting file
 +
Item7=Open the folder containing the sample scenes installed with POV-Ray
 +
Item8=Edit PVTOOLS.INI to alter this menu
  
 
[General]
 
[General]
Line 719: Line 337:
 
</pre>
 
</pre>
  
====GUI Extensions Menu====
+
===Window Menu===
<!--<indexentry primary "GUI Extensions Menu" "Menus, GUI Extensions">--->
+
{{#indexentry:Window Menu}}
 
+
{{#indexentry:Menus, Window}}
<p>
 
GUI Extensions are specialized DLL's that can add functionality to the POV-Ray for Windows
 
user interface. They can also provide a means for external programs (such as the popular Moray
 
modeller) to control POV-Ray in a limited manner. If you want more information on GUI
 
Extensions see the newsgroup [news://news.povray.org/povray.programming povray.programming]
 
on the [http://www.povray.org/groups.html POV-Ray news server], or retrieve the
 
POV-Ray for Windows source code from our FTP site, and look at the example extension in the
 
GUIEXT subdirectory.
 
</p>
 
 
 
<p>[[Image:WinImgMenusGuiext.gif|-]]</p>
 
  
 
<p>
 
<p>
Unless you are using a program that has a GUI Extension, or have installed one yourself, there
+
The Window menu contains a number of commands related to editor tab management (in the context of this section, a 'window'
will be a message 'No GUI Extensions Loaded' visible in this menu. If you have some installed,
+
refers to a tab in the editor) and additionally a list of tabs showing the name of their contents. At a minimum (if no files
you can turn their functionality on or off by unchecking the 'Use Extensions' menu item.
+
are open) this list will contain one entry: the Message tab.
 
</p>
 
</p>
  
 
<p>
 
<p>
The POV-Team provides no support whatsoever for GUI Extensions. The POV document that allows
+
The MRU (most-recently-used) arrangement of the tab list in this menu makes it trivial to toggle between files without taking your eyes off the text or using the mouse. The most recently viewed tab (i.e. the current one) will always be entry 1 in the list. The second most recently viewed (i.e. the last tab viewed before switching to the current one) will always be entry 2 in the list, and so forth. Given that entries 1 through 10 in the list are given the menu mnemonics 1 through 0 respectively, all you need to do to toggle between the current and previous files is hit Alt-W then 2. To go to the third oldest, Alt-W then 3, and so forth. Note that the MRU list is not saved on exit.
GUIEXT authors to write extensions to our specification requires them to provide support for
 
them for at least a little while after they are released. If you have a third-party GUIEXT
 
with which you are having problems, you should refer to the author of that extension. If
 
he/she is no longer available for support, we cannot help you.
 
 
</p>
 
</p>
  
 
===Context Menus===
 
===Context Menus===
<!--<indexentry primary "Context Menus" "Menus, Context Menus">--->
+
{{#indexentry:Context Menus, Menus}}
 
<p>
 
<p>
 
Most POV-Ray windows have shortcut (also known as 'context') menus. You access them by  
 
Most POV-Ray windows have shortcut (also known as 'context') menus. You access them by  
Line 757: Line 360:
 
</p>
 
</p>
  
====The Message Window Context Menu====
+
====The Message Window context menu====
<!--<indexentry primary "Message Window, Context Menu" "Context Menus, Message Window">--->
+
{{#indexentry:Message Window, Context Menu, Context Menus}}
 
+
<!--BEGIN DO NOT alter or move--->
<p>
+
{{#indexentry:Message Window Menu}}
When the mouse right button is pressed over the Message window, a pop-up menu containing
+
<!--END DO NOT alter or move--->
the following commands is displayed:
+
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
</p>
+
<tr>
 +
  <td>
 +
    [[Image:win-messagewincontext.png|center|202px<!--left--->]]
 +
  </td>
 +
  <td>
 +
    <p>When the mouse right button is pressed over the Message window, a pop-up menu containing these commands are displayed:</p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td>
 +
    <p class="caption">The Message Window context menu</p>
 +
  </td>
 +
  <td></td>
 +
</tr>
 +
</table>
  
<p>[[Image:WinImgMenusMessagewin.gif|-]]</p>
+
<p>All of these commands and sub-menus except 'Minimize to System Tray' and 'Show Tip' are documented elsewhere; the following list links to that documentation.</p>
 
 
<p>
 
All of these commands and submenus except 'Minimize to System Tray' and 'Show Tip' are  
 
documented elsewhere; the following list links to that documentation.
 
</p>
 
  
 
<ul>
 
<ul>
<li><!--<linkto "Edit Settings/Render">Edit Settings/Render</linkto>--->[[Documentation:Windows Section 5.2#Edit Settings/Render|Edit Settings/Render]]
+
<li><!--<linkto "Edit Settings/Render">Edit Settings/Render</linkto>--->[[Documentation:Windows Section 5.2#Edit Settings/Render dialog|Edit Settings/Render dialog]]</li>
<li><!--<linkto "Select File and Render">Select File and Render</linkto>--->[[Documentation:Windows Section 5.2#Select File and Render|Select File and Render]]
+
<li><!--<linkto "Select File and Render">Select File and Render</linkto>--->[[Documentation:Windows Section 5.2#Select File and Render dialog|Select File and Render dialog]]</li>
<li><!--<linkto "Start Rendering">Start Rendering</linkto>--->[[Documentation:Windows Section 5.2#Start Rendering (Go!)/Stop Rendering|Start Rendering]]
+
<li><!--<linkto "Start Rendering">Start Rendering</linkto>--->[[Documentation:Windows Section 5.2#Start Rendering (Go!)/Stop Rendering|Start Rendering]]</li>
<li><!--<linkto "Rerun Dialog">Rerun Dialog</linkto>--->[[Documentation:Windows Section 5.2#Rerun|Rerun Dialog]]
+
<li><!--<linkto "File Queue">File Queue</linkto>--->[[Documentation:Windows Section 5.2#File Queue dialog|File Queue dialog]]</li>
<li><!--<linkto "File Queue">File Queue</linkto>--->[[Documentation:Windows Section 5.2#File Queue|File Queue]]
+
<li><!--<linkto "Clear Queue">Clear Queue</linkto>--->[[Documentation:Windows Section 5.2#Clear Queue|Clear Queue]]</li>
<li><!--<linkto "Clear Queue">Clear Queue</linkto>--->[[Documentation:Windows Section 5.2#Clear Queue|Clear Queue]]
+
<li><!--<linkto "Clear Messages">Clear Messages</linkto>--->[[Documentation:Windows Section 5#Clear Messages|Clear Messages]]</li>
<li><!--<linkto "Clear Messages">Clear Messages</linkto>--->[[Documentation:Windows Section 5#Clear Messages|Clear Messages]]
+
<li><!--<linkto "Re-display Render Window">Re-display Render Window</linkto>--->[[Documentation:Windows Section 5.2#Re-Display|Re-Display Render Window]]</li>
<li><!--<linkto "Re-display Render Window">Re-display Render Window</linkto>--->[[Documentation:Windows Section 5.3#Re-display|Re-display Render Window]]
+
<li><!--<linkto "Render Priority">Render Priority</linkto>--->[[Documentation:Windows Section 7#Render Priority|Render Priority]]</li>
<li><!--<linkto "Render Priority">Render Priority</linkto>--->[[Documentation:Windows Section 7#Render Priority|Render Priority]]
 
 
</ul>
 
</ul>
  
Line 798: Line 409:
 
====Show Tip====
 
====Show Tip====
 
<p>
 
<p>
If you select Show Tip, POV-Ray for Windows displays a single tip (see <!--<linkto "Show Tips of the Day">Show Tips of the Day</linkto>--->[[Documentation:Windows Section 5.3#Show Tips of the Day|Show Tips of the Day]]).
+
If you select Show Tip, POV-Ray for Windows displays a single tip (see <!--<linkto "Show Tips of the Day">Show Tips of the Day</linkto>--->[[Documentation:Windows Section 5.2#Show Tips of the Day|Show Tips of the Day]]).
 
</p>
 
</p>
  
====The Render Window Context Menu====
+
====The Render Window context menu====
<!--<indexentry primary "Render Window, Context Menu" "Context Menus, Render Window">--->
+
{{#indexentry:Render Window, Context Menu, Context Menus}}
 
+
<!--BEGIN DO NOT alter or move--->
<p>
+
{{#indexentry:Render Window Menu}}
When the mouse right button is pressed over the Render window, a pop-up menu containing
+
<!--END DO NOT alter or move--->
the following commands is displayed:
+
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
</p>
+
<tr>
 
+
  <td>
<p>[[Image:WinImgMenusRenderwin.gif|-]]</p>
+
    [[Image:win-renderwincontext.png|center|462px<!--centered--->]]
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td>
 +
    <p class="caption">The Render Window context menu</p>
 +
  </td>
 +
</tr>
 +
</table>
  
 
<p>
 
<p>
See the <!--<linkto "Render Window Menu">Render Window sub-menu</linkto>--->[[Documentation:Windows Section 5.3#Render Window|Render Window sub-menu]] for documentation
+
See the <!--<linkto "Render Window Menu">Render Window sub-menu</linkto>--->[[Documentation:Windows Section 5.2#Render Window sub-menu|Render Window sub-menu]] for documentation
 
on the commands in this menu.
 
on the commands in this menu.
 
</p>
 
</p>
  
====The Editor Window Context Menu====
+
====The Editor Window context menu====
<!--<indexentry primary "Editor Window, Context Menu" "Context Menus, Editor Window">--->
+
{{#indexentry:Editor Window, Context Menu, Context Menus}}
 
+
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<p>
+
<tr>
When the mouse right button is pressed over the Editor window, a pop-up menu containing
+
  <td>
the following commands is displayed:
+
    [[Image:win-editorwindowcontext.png|center|494px<!--centered--->]]
</p>
+
  </td>
 
+
</tr>
<p>[[Image:WinImgMenusEditwin.gif|-]]</p>
+
<tr>
 +
  <td>
 +
    <p class="caption">The Editor Window context menu</p>
 +
  </td>
 +
</tr>
 +
</table>
  
 
<p>
 
<p>
Line 834: Line 458:
  
 
<ul>
 
<ul>
<li><!--<linkto "Cut">Cut</linkto>--->[[Documentation:Windows Section 5#Cut|Cut]]
+
<li><!--<linkto "Cut">Cut</linkto>--->[[Documentation:Windows Section 5#Cut|Cut]]</li>
<li><!--<linkto "Copy">Copy</linkto>--->[[Documentation:Windows Section 5#Copy|Copy]]
+
<li><!--<linkto "Copy">Copy</linkto>--->[[Documentation:Windows Section 5#Copy|Copy]]</li>
<li><!--<linkto "Paste">Paste</linkto>--->[[Documentation:Windows Section 5#Paste|Paste]]
+
<li><!--<linkto "Paste">Paste</linkto>--->[[Documentation:Windows Section 5#Paste|Paste]]</li>
<li><!--<linkto "Undo">Undo</linkto>--->[[Documentation:Windows Section 5#Undo|Undo]]
+
<li><!--<linkto "Undo">Undo</linkto>--->[[Documentation:Windows Section 5#Undo|Undo]]</li>
<li><!--<linkto "Redo">Redo</linkto>--->[[Documentation:Windows Section 5#Redo|Redo]]
+
<li><!--<linkto "Redo">Redo</linkto>--->[[Documentation:Windows Section 5#Redo|Redo]]</li>
<li><!--<linkto "Bookmarks">Bookmark</linkto>--->[[Documentation:Windows Section 5#Bookmarks|Bookmark]]
+
<li><!--<linkto "Bookmarks">Bookmark</linkto>--->[[Documentation:Windows Section 5.1#Bookmarks sub-menu|Bookmark sub-menu]]</li>
<li><!--<linkto "File Menu">File</linkto>--->[[Documentation:Windows Section 5#File Menu|File]]
+
<li><!--<linkto "File Menu">File</linkto>--->[[Documentation:Windows Section 5#File Menu|File]]</li>
<li><!--<linkto "Search Menu">Search</linkto>--->[[Documentation:Windows Section 5#Search Menu|Search]]
+
<li><!--<linkto "Search Menu">Search</linkto>--->[[Documentation:Windows Section 5#Search Menu|Search]]</li>
<li><!--<linkto "Selection">Selection</linkto>--->[[Documentation:Windows Section 5#Selection|Selection]]
+
<li><!--<linkto "Selection">Selection</linkto>--->[[Documentation:Windows Section 5#Selection sub-menu|Selection sub-menu]]</li>
<li><!--<linkto "Close File">Close Current File</linkto>--->[[Documentation:Windows Section 5#Close|Close Current File]]
+
<li><!--<linkto "Close File">Close Current File</linkto>--->[[Documentation:Windows Section 5#Close|Close Current File]]</li>
<li><!--<linkto "Editor Preferences">Properties</linkto>--->[[Documentation:Windows Section 5.1#Editor Preferences|Properties]]
+
<li><!--<linkto "Editor Preferences">Properties</linkto>--->[[Documentation:Windows Section 5.1#Editor Preferences|Properties]]</li>
 
</ul>
 
</ul>
  
Line 866: Line 490:
 
</p>
 
</p>
  
====Open <Filename>====
+
====Open Filename====
 
<p>
 
<p>
 
Whenever you open the context menu, the editor first looks underneath the edit caret to see
 
Whenever you open the context menu, the editor first looks underneath the edit caret to see
 
if there is a line that looks like a POV-Ray scene file '#include' directive. If one is found,
 
if there is a line that looks like a POV-Ray scene file '#include' directive. If one is found,
 
the name of the specified file is placed into the menu in place of &quot;filename&quot;. If
 
the name of the specified file is placed into the menu in place of &quot;filename&quot;. If
one is not found, then it may show &quot;Copy ... to Command-Line&quot; (see below).
+
one is not found, then it may show <em>Copy ... to Command-Line</em> (see below).
 
</p>
 
</p>
  
Line 880: Line 504:
 
</p>
 
</p>
  
====Copy "..." to Command-Line====
+
====Copy ... to Command-Line====
<!--<indexentry primary "Command-Line, copying text to">--->
+
{{#indexentry:Command-Line, copying text to}}
  
 
<p>
 
<p>
Line 897: Line 521:
 
<ol type="a">
 
<ol type="a">
 
<li>The first non-whitespace character after the '<code>//</code>' is either a '<code>+</code>'
 
<li>The first non-whitespace character after the '<code>//</code>' is either a '<code>+</code>'
or a '<code>-</code>', and the next character after that is alphabetical, or
+
or a '<code>-</code>', and the next character after that is alphabetical, or</li>
<li>The first non-whitespace after the '<code>//</code>' contains '<code>Cmd:</code>' (case-insensitive).
+
<li>The first non-whitespace after the '<code>//</code>' contains '<code>Cmd:</code>' (case-insensitive).</li>
 
</ol>
 
</ol>
  
 
<p>
 
<p>
If the line fits this description then the text after the '<code>//</code>' (with the '<code>Cmd:</code>'
+
If the line fits this description then the text after the '<code>//</code>' (with the '<code>Cmd:</code>' removed if it were present) is considered the command-line (minus leading and trailing whitespace). There is one slight variation to the detection rules, though:
removed if it were present) is considered the command-line (minus leading and trailing whitespace).
+
if the line also contains a quoted string that looks like it could be a filename and you right-click before the end of that string,
 +
the context menu will present the 'Open File in Editor' option instead of the 'Copy Command' option. To get the 'Copy Command' option,
 +
simply make sure you right-click somewhere to the right of the filename.
 
</p>
 
</p>
  
<p>
+
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
In this case the menu will have a command to copy the found command to the toolbar
+
<tr>
command-line, such as the one shown below. If this command is chosen, the text in the
+
  <td>
toolbar command-line will be replaced with the text extracted from the line, and focus
+
    [[Image:win-editorcontextcopycmd.png|center|320px<!--centered--->]]
will be changed to the toolbar command-line field.
+
  </td>
</p>
+
</tr>
 +
<tr>
 +
  <td>
 +
    <p class="caption">The &quot;Copy to command-line&quot; feature</p>
 +
  </td>
 +
</tr>
 +
</table>
  
<p>[[Image:WinImgMenusEditwin-cmdline.gif|-]]</p>
+
<p>In this case the menu will have a command to copy the found command to the toolbar command-line, such as the one shown on the left. If this command is chosen, the text in the toolbar command-line will be replaced with the text extracted from the line, and focus will be changed to the toolbar command-line field.</p>
  
 
<p>
 
<p>
Line 938: Line 570:
 
// Cmd: Width=960 Height=400 Antialias_Threshold=0.1 AntiAlias=On
 
// Cmd: Width=960 Height=400 Antialias_Threshold=0.1 AntiAlias=On
 
</pre>
 
</pre>
 
 
 
<p>
 
<p>
 
See also <!--<linkto "Toolbar Command Line">Toolbar Command Line</linkto>--->[[Documentation:Windows Section 4#Toolbar Command Line|Toolbar Command Line]].
 
See also <!--<linkto "Toolbar Command Line">Toolbar Command Line</linkto>--->[[Documentation:Windows Section 4#Toolbar Command Line|Toolbar Command Line]].
Line 947: Line 577:
 
<table width=100% border=0 cellspacing=0 cellpadding=5>
 
<table width=100% border=0 cellspacing=0 cellpadding=5>
 
<tr><td width=50% bgcolor=#EEEEEF>
 
<tr><td width=50% bgcolor=#EEEEEF>
[[Documentation:Windows Section 5.2#Drag'N'Drop Destination|Drag'N'Drop Destination]]</td>
+
[[Documentation:Windows Section 5.2#Include System Information|Include System Information]]</td>
 
<td width=50% bgcolor=#EEEEEF align=right>
 
<td width=50% bgcolor=#EEEEEF align=right>
 
[[Documentation:Windows Section 6#Bug Reports|Bug Reports]]</td></tr>
 
[[Documentation:Windows Section 6#Bug Reports|Bug Reports]]</td></tr>

Latest revision as of 11:34, 4 July 2017

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


Tools Menu

win-toolsmenu.png

The Tools Menu provides you with a simple means of customizing POV-Ray for Windows. You can develop your own commands (up to 32) to show up under this menu. Since the menu is determined by the file PVTOOLS.INI, editing and reloading this INI file changes the Tools Menu.

The Tools Menu

PVTOOLS.INI Syntax

The syntax of entries in PVTOOLS.INI is as follows:

[Menu]
ItemN=Description
 
[Command]
ItemN=command_string
 
[Help]
ItemN=help_line

Where N is a number between 0 and 31, and entries in the [Help] section are optional.

Item0 ... Item31

are the item numbers that define the order in which entries appear in the Tools Menu.

[Menu]

Entries in the [Menu] section are what actually appears in the Tools Menu. The '&' character tells Windows where to put the underline in the menu entry. The underlined letter becomes the abbreviation for the command. For example the letter 'C' in '&Click Me' would become 'Click Me' when displayed in the Tools Menu, and you could access the command by pressing Alt+T and then 'C'. (Alt+T activates the Tools Menu).
You should make sure that all Tools Menu entries have different abbreviations if you intend to access them this way. Of course, you don't have to supply any abbreviation if you don't want to.

Note: By default newer versions of Windows will not display the underline beneath the abbreviation until you press ALT. This means if you use the mouse to open the menu you won't see the underlines.

[Command]

This is the command that POV-Ray will execute for that entry. This can be a Windows EXE, a batch file, or anything else that may be executed by the Win32 ShellExecute() API call. The command consists of the actual command name followed by any parameters you want to supply to the program.
There are two special commands, '$S' and '$E'. $S means 'use the shell association for the filename that follows it', and '$E' means 'open the following file in the internal POVWIN editor'. Let's look at an example -

Item4=$S %1

Since %1 refers to the output file (see below) this means that Item 4 of the tools menu expands to a command to Windows to open the last output file with whatever program is associated with it. For example, if the last output file was 'c:\images\torus4.png' then the above command example would use whatever program is associated with PNG files (i.e. the program that Windows runs if you double-clicked on the TORUS4.PNG file in Windows Explorer) to open it.

Note: If using the $S or $E special commands, do not quote the parameters with '"', even if they will have spaces in them. Both of these commands may only be supplied a single parameter, which is taken to be the entire line following the command.

POV-Ray for Windows has a number of pre-defined parameters that you can substitute into the command line before the program is run. These are defined by a percent sign ('%') followed by a letter or number. For example, '%i' means substitute the POV-Ray for Windows INI file directory in the place of the '%i'.

Let's look at the command:

notepad.exe %ipvtools.txt

If you had installed POV-Ray for Windows into the directory 'c:\povwin3', then our standard INI file directory would be 'c:\povwin3\ini\'. When POV-Ray ran the above command, the '%i' would be replaced with 'c:\povwin3\ini\'. Note that the trailing '\' is provided by POV-Ray. This means that:

notepad.exe %ipvtools.txt

would become:

notepad.exe c:\povwin3\ini\pvtools.txt

Here are all of the predefined substitutions:

%0

The contents of the 'SourceFile' entry of the 'LastRender' section in PVENGINE.INI. This will be the input file provided to POV-Ray for the most recent render. This information is extracted from the rendering engine itself, rather than any input dialog or command-line. It is the file which, after all processing of the command line and INI files was complete, was finally assigned as the input file.

%1

The contents of the 'OutputFile' entry of the 'LastRender' section in PVENGINE.INI. This will be the output file from the last render, if any. This entry could be blank.

%2

The contents of the 'SceneFile' entry of the 'LastRender' section in PVENGINE.INI. This will be the scene file name for the last render, without the .POV extension. You can use this by appending a new extension to it. For example,

tga2gif %d\%1 %2.gif

could expand to:

tga2gif c:\scenes\myscene.tga myscene.gif

assuming the input file was myscene.pov and the current directory at that time was c:\scenes.

%4

The contents of the 'IniOutputFile' entry of the 'LastRender' section in PVENGINE.INI. If you had instructed POV-Ray to write an INI file from the last render, this would contain its name.

%D

The contents of the 'CurrentDirectory' entry of the 'LastRender' section in PVENGINE.INI. This is the current working directory that was set on your machine when POV-Ray began rendering the last file, and is what the other output file entries are probably relative to. You may need to provide '%d' with some of these other entries to get the full path.

%H

The POV-Ray for Windows install directory, as specified in the registry or inferred at run- time, e.g. 'c:\Program Files\POV-Ray for Windows vX.y\'. Note the trailing backslash is supplied.

%P

The POV-Ray for Windows user documents directory, as specified in the registry or inferred at run- time, e.g. 'c:\Users\Joe\Documents\POV-Ray\vX.y\'. Note the trailing backslash is supplied. This is the directory where the sample scenes, include files, and INI files are stored.

%I

The POV-Ray for Windows INI directory. e.g. 'c:\Users\Joe\Documents\POV-Ray\vX.y\ini\'.

%N

The preset INI filename, as used in the render options dialog.

%R

The last render file (with full path) as supplied to POV-Ray from the render or choose file dialog. This is not necessarily the same thing as %S or %0.

%S

The source file name as provided to POV-Ray on the last render of the current session. This is not necessarily the same thing as the %0 or %R directive. For example, %R will never provide the path to a file that was rendered via the File Queue without the use of the Command dialog. %S will, however, include any such file.

%T

The full path to PVTOOLS.INI. This is the file which holds the Tools Menu commands.

%%

A literal percent character ('%').

If any of the above seems confusing, there's an easy way to find out what's going on. If you place the statement DEBUG=1 in the General section of PVTOOLS.INI, POV-Ray for Windows will print out the string for each command both before and after it is expanded, instead of running the command that you select in the tool menu. That way you can see exactly what POV-Ray substitutes. The printout will be visible in the messages window.

For example:

[General]
Debug=1

will turn on debugging. while

[General]
Debug=0 

or omitting the statement entirely turns it off.

[Help]

You can have a help line appear in the status bar at the bottom of the window. You don't have to supply this entry if you don't want to.

Example:

[Help]
Item1=Edit master POVRAY.INI in installation directory

This command makes the string 'Edit master POVRAY.INI in installation directory' appear on the status bar when the mouse is over the 1st item in the Tools menu.

Reload Tool Menu

If you want your changes to take immediate effect after you have edited PVTOOLS.INI using a text editor, you have to select the Tools Menu command Reload Tool Menu to instruct POV-Ray for Windows to re-read the INI file and activate the new settings.

Edit PVTOOLS.INI

This standard Tools Menu command lets you modify PVTOOLS.INI using the Notepad editor. The command is part of PVTOOLS.INI itself, which means you may delete it entirely if you don't want it. It is present by default in the standard distribution of POV-Ray for Windows.

Example PVTOOLS.INI

[Menu]
Item0=Edit &master POVRAY.INI
Item1=Edit PVEN&GINE.INI
Item2=Edit &last rendered file
Item3=Edit last &scene file
Item4=&View last rendered file
Item5=Edit resolution &INI file
Item6=Edit &user-defined syntax file
Item7=&Browse sample scenes folder
Item8=Edit &this menu

[Command]
# NOTE! If using the $E or $E, DO NOT quote the parameters with '"'.
# If you are calling a program directly, you will probably need to quote the
# parameter; e.g. notepad.exe "%r"
Item0=$e %pini\povray.ini
Item1=$e %pini\pvengine.ini
Item2=$e %r
Item3=$e %0
Item4=$s %1
Item5=$e %n
Item6=$e %I\user-keywords.txt
Item7=$s %pscenes\
Item8=$e %t

[Help]
Item0=Edit master POVRAY.INI in installation directory
Item1=Edit PVENGINE.INI in installation directory
Item2=Edit the last file that POV-Ray was rendering
Item3=Edit the last scene file that you selected
Item4=View the output of the last render (assumes file output was on)
Item5=Edit secondary INI file as specified in Command-line dialog
Item6=Edit the user-defined syntax highlighting file
Item7=Open the folder containing the sample scenes installed with POV-Ray
Item8=Edit PVTOOLS.INI to alter this menu

[General]
Debug=0

Window Menu

The Window menu contains a number of commands related to editor tab management (in the context of this section, a 'window' refers to a tab in the editor) and additionally a list of tabs showing the name of their contents. At a minimum (if no files are open) this list will contain one entry: the Message tab.

The MRU (most-recently-used) arrangement of the tab list in this menu makes it trivial to toggle between files without taking your eyes off the text or using the mouse. The most recently viewed tab (i.e. the current one) will always be entry 1 in the list. The second most recently viewed (i.e. the last tab viewed before switching to the current one) will always be entry 2 in the list, and so forth. Given that entries 1 through 10 in the list are given the menu mnemonics 1 through 0 respectively, all you need to do to toggle between the current and previous files is hit Alt-W then 2. To go to the third oldest, Alt-W then 3, and so forth. Note that the MRU list is not saved on exit.

Context Menus

Most POV-Ray windows have shortcut (also known as 'context') menus. You access them by right-clicking over the window in question (e.g. the message, edit, or render window). The menu that appears will have the most commonly-used commands (as available in the main menus) that apply to that particular type of window.

The Message Window context menu

win-messagewincontext.png

When the mouse right button is pressed over the Message window, a pop-up menu containing these commands are displayed:

The Message Window context menu

All of these commands and sub-menus except 'Minimize to System Tray' and 'Show Tip' are documented elsewhere; the following list links to that documentation.

Minimize to System Tray

This command (which is also available as a toolbar button) will hide POV-Ray for Windows and place a small icon in the system tray (the system tray usually contains a clock and is often at the right hand side of the task bar at the bottom of the screen).

You can use the right-mouse button on this icon to get a context menu. Double-clicking on it restores POVWIN from the tray.

Show Tip

If you select Show Tip, POV-Ray for Windows displays a single tip (see Show Tips of the Day).

The Render Window context menu

win-renderwincontext.png

The Render Window context menu

See the Render Window sub-menu for documentation on the commands in this menu.

The Editor Window context menu

win-editorwindowcontext.png

The Editor Window context menu

The actual content of the line shown as 'Open "filename"' will vary according to what was on the line under the cursor when the right mouse button was clicked. All of the commands except 'Show Messages', 'Context Help', and 'Open "filename"' are documented elsewhere; the following list links to that documentation.

Show or Hide Messages

Manually cause the small message window to be displayed (or hidden if it is showing, in which case this menu entry will read 'Hide Message Window' instead of 'Show Message Window'). Note that you can also use the Escape key to hide the message window.

See Auto-Show Parse Messages for more information.

Context Help

This command (which can also be activated with the F1 key) will cause the editor to look for the closest word to the edit caret and attempt to look it up in the help file. If more than one match is found, you will be given a choice as to which one. If no match is found, the help file will open with the index at the closest match it could find.

Open Filename

Whenever you open the context menu, the editor first looks underneath the edit caret to see if there is a line that looks like a POV-Ray scene file '#include' directive. If one is found, the name of the specified file is placed into the menu in place of "filename". If one is not found, then it may show Copy ... to Command-Line (see below).

If you then select this command, the editor will attempt to find and open the file in a new edit window. The standard include paths (as defined in PVENGINE.INI) will be searched if the file is not found relative to the current directory.

Copy ... to Command-Line

If, when the editor searches for an include file name on the current line (see above), it does not find one, it will then look for something that looks like a 'command line'. By 'command line' we mean a line that could be used in the toolbar command-line field as options. The editor uses several simple rules to decide if something is likely to be a command-line:

Firstly, the line must contain a '//' somewhere. Then, either -

  1. The first non-whitespace character after the '//' is either a '+' or a '-', and the next character after that is alphabetical, or
  2. The first non-whitespace after the '//' contains 'Cmd:' (case-insensitive).

If the line fits this description then the text after the '//' (with the 'Cmd:' removed if it were present) is considered the command-line (minus leading and trailing whitespace). There is one slight variation to the detection rules, though: if the line also contains a quoted string that looks like it could be a filename and you right-click before the end of that string, the context menu will present the 'Open File in Editor' option instead of the 'Copy Command' option. To get the 'Copy Command' option, simply make sure you right-click somewhere to the right of the filename.

win-editorcontextcopycmd.png

The "Copy to command-line" feature

In this case the menu will have a command to copy the found command to the toolbar command-line, such as the one shown on the left. If this command is chosen, the text in the toolbar command-line will be replaced with the text extracted from the line, and focus will be changed to the toolbar command-line field.

The purpose of this facility is to allow users to keep a set of commonly-used command-line options at the top of the scene file, and use this facility to quickly copy one of them to the command-line for a render.

Example command-lines which could be embedded into a scene file -

// +w480 +h200 +a0.1
// +w960 +h400 +a0.1

The following would also be legal (and equivalent to the above example) -

// Cmd: Width=480 Height=200 Antialias_Threshold=0.1 AntiAlias=On
// Cmd: Width=960 Height=400 Antialias_Threshold=0.1 AntiAlias=On

See also Toolbar Command Line.


Include System Information Bug Reports


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