Jholsenback: 1 revision: underscore link repair

2012-07-17T18:09:31Z

1 revision: underscore link repair

Jholsenback: still testing that theory

2012-07-12T09:19:57Z

still testing that theory

Jholsenback: 1 revision: Reference Migration Initial Load

2012-03-15T19:08:47Z

1 revision: Reference Migration Initial Load

Jholsenback: 1 revision: Initial Load (TF)

2012-03-11T22:12:12Z

1 revision: Initial Load (TF)

New page

[[Category:Command-Line and INI-File Options]]
<table width="100%" class="option-list">
<tr>
<td width="30%"><code>Pre_Scene_Command=</code>s{{#indexentry:Pre_Scene_Command, ini-option}}</td>

<td width="70%">Set command before entire scene</td>
</tr>

<tr>
<td><code>Pre_Frame_Command=</code>s{{#indexentry:Pre_Frame_Command, ini-option}}</td>

<td>Set command before each frame</td>
</tr>

<tr>
<td><code>Post_Scene_Command=</code>s{{#indexentry:Post_Scene_Command, ini-option}}</td>

<td>Set command after entire scene</td>
</tr>

<tr>
<td><code>Post_Frame_Command=</code>s{{#indexentry:Post_Frame_Command, ini-option}}</td>

<td>Set command after each frame</td>
</tr>

<tr>
<td><code>User_Abort_Command=</code>s{{#indexentry:User_Abort_Command, ini-option}}</td>

<td>Set command when user aborts POV-Ray</td>
</tr>

<tr>
<td><code>Fatal_Error_Command=</code>s{{#indexentry:Fatal_Error_Command, ini-option}}</td>

<td>Set command when POV-Ray has fatal error</td>
</tr>
</table>

Note: No <code>+</code> or <code>-</code> switches are available for
these options. They cannot be used from the command line. They may only be
used from INI files.

POV-Ray offers you the opportunity to shell-out to the operating system at
several key points to execute another program or batch file. Usually this is
used to manage files created by the internal animation loop however the shell
commands are available for any scene. The string s is a single line
of text which is passed to the operating system to execute a program. For
example
<pre>
Post_Scene_Command=tga2gif -d -m myfile
</pre>

would use the utility <code>tga2gif</code> with the <code>-D</code> and
<code>-M</code> parameters to convert <code>myfile.tga</code> to <code>
myfile.gif</code> after the scene had finished rendering.

Note: Individual platforms may provide means of preventing shell-outs
from occurring. For example, the Windows version provides a menu command to
turn shell-outs off (which is the default setting for that platform). The
reason for this (along with file I/O restrictions) is to attempt to prevent
untrusted INI files from doing harm to your system.
==String Substitution in Shell Commands==
It could get cumbersome to change the <code>Post_Scene_Command</code>
every time you changed scene names. POV-Ray can substitute various values
into a command string for you. For example:
<pre>
Post_Scene_Command=tga2gif -d -m %s
</pre>

POV-Ray will substitute the <code>%s</code> with the scene name in the
command. The scene name is the <code>Input_File_Name</code> or
<code>+I</code> setting with any drive, directory and extension removed. For
example:
<pre>
Input_File_Name=c:\povray3\scenes\waycool.pov
</pre>

is stripped down to the scene name <code>waycool</code> which results
in...
<pre>
Post_Scene_Command=tga2gif -d -m waycool
</pre>

In an animation it may be necessary to have the exact output file name
with the frame number included. The string <code>%o</code> will substitute
the output file name. Suppose you want to save your output files in a zip
archive using the utility program <code>pkzip</code>. You could do...
<pre>
Post_Frame_Command=pkzip -m %s %o
</pre>

After rendering frame 12 of <code>myscene.pov</code> POV-Ray would shell
to the operating system with
<pre>
pkzip -m myscene mysce012.tga
</pre>

The <code>-M</code> switch in <code>pkzip</code> moves <code>
mysce012.tga</code> to <code>myscene.zip</code> and removes it from the
directory. Note that <code>%o</code> includes frame numbers only when in an
animation loop. During the <code>Pre_Scene_Command</code> and <code>
Post_Scene_Command</code> there is no frame number so the original,
unnumbered <code>Output_File_Name</code> is used. Any <code>
User_Abort_Command</code> or <code>Fatal_Error_Command</code> not inside the
loop will similarly give an unnumbered <code>%o</code> substitution.

Here is the complete list of substitutions available for a command
string.

<table width="100%" class="option-list">
<tr>
<td width="30%"><code>%o</code></td>

<td width="70%">Output file name with extension and embedded frame number if any</td>
</tr>

<tr>
<td><code>%s</code></td>

<td>Scene name derived by stripping path and ext from input name</td>
</tr>

<tr>
<td><code>%n</code></td>

<td>Frame number of this frame</td>
</tr>

<tr>
<td><code>%k</code></td>

<td>Clock value of this frame</td>
</tr>

<tr>
<td><code>%h</code></td>

<td>Height of image in pixels</td>
</tr>

<tr>
<td><code>%w</code></td>

<td>Width of image in pixels</td>
</tr>

<tr>
<td><code>%%</code></td>

<td>A single % sign.</td>
</tr>
</table>

==Shell Command Sequencing==
Here is the sequence of events in an animation loop. Non-animated scenes
work the exact same way except there is no loop.
<ol>
<li>Process all INI file keywords and command line switches just once.</li>
<li>Open any text output streams and do Create_INI if any.</li>
<li>Execute Pre_Scene_Command if any.</li>
<li>Loop through frames (or just do once on non-animation).
<ol type="a">
<li>Execute Pre_Frame_Command if any.</li>
<li>Parse entire scene file, open output file and read settings, turn on
display, render the frame, destroy all objects, textures etc., close output
file, close display.</li>
<li>Execute Post_Frame_Command if any.</li>
<li>Repeat above steps until all frames are done.</li>
</ol></li>
<li>Execute Post_Scene_Command if any.</li>
<li>Finish</li>
</ol>

If the user interrupts processing the <code>User_Abort_Command</code>, if
any, is executed. User aborts can only occur during the parsing and rendering
parts of step (4b) above. If a fatal error occurs that POV-Ray notices the
<code>Fatal_Error_Command</code>, if any, is executed. Sometimes an
unforeseen bug or memory error could cause a total crash of the program in
which case there is no chance to shell out. Fatal errors can occur just about
anywhere including during the processing of switches or INI files. If a fatal
error occurs before POV-Ray has read the <code> Fatal_Error_Command</code>
string then obviously no shell can occur.
Note: The entire scene is re-parsed for every frame. Future versions of
POV-Ray may allow you to hold over parts of a scene from one frame to the
next but for now it starts from scratch every time.
Note: The <code>Pre_Frame_Command</code> occurs before the
scene is parsed. You might use this to call some custom scene generation utility
before each frame. This utility could rewrite your <code> .pov</code>
or <code>.inc</code> files if needed. Perhaps you will want to generate new
<code>.gif</code> or <code>.tga</code> files for image maps or height fields on each frame.

==Shell Command Return Actions==
<table width="100%" class="option-list">
<tr>
<td width="30%"><code>Pre_Scene_Return=</code>s{{#indexentry:Pre_Scene_Return}}</td>

<td width="70%">Set pre scene return actions</td>
</tr>

<tr>
<td><code>Pre_Frame_Return=</code>s{{#indexentry:Pre_Frame_Return}}</td>

<td>Set pre frame return actions</td>
</tr>

<tr>
<td><code>Post_Scene_Return=</code>s{{#indexentry:Post_Scene_Return}}</td>

<td>Set post scene return actions</td>
</tr>

<tr>
<td><code>Post_Frame_Return=</code>s{{#indexentry:Post_Frame_Return}}</td>

<td>Set post frame return actions</td>
</tr>

<tr>
<td><code>User_Abort_Return=</code>s{{#indexentry:User_Abort_Return}}</td>

<td>Set user abort return actions</td>
</tr>

<tr>
<td><code>Fatal_Error_Return=</code>s{{#indexentry:Fatal_Error_Return}}</td>

<td>Set fatal return actions</td>
</tr>
</table>

Note: No <code>+</code> or <code>-</code> switches are available for
these options. They cannot be used from the command line. They may only be
used from INI files.

Most operating systems allow application programs to return an error code if
something goes wrong. When POV-Ray executes a shell command it can make use
of this error code returned from the shell process and take some appropriate
action if the code is zero or non-zero. POV-Ray itself returns such codes. It
returns 0 for success, 1 for fatal error and 2 for user abort.

The actions are designated by a single letter in the different <code>
..._Return</code>=s options. The possible actions are:

<table width="100%" class="option-list">
<tr>
<td width="30%"><code>I</code></td>

<td width="70%">ignore the code</td>
</tr>

<tr>
<td><code>S</code></td>

<td>skip one step</td>
</tr>

<tr>
<td><code>A</code></td>

<td>all steps skipped</td>
</tr>

<tr>
<td><code>Q</code></td>

<td>quit POV-Ray immediately</td>
</tr>

<tr>
<td><code>U</code></td>

<td>generate a user abort in POV-Ray</td>
</tr>

<tr>
<td><code>F</code></td>

<td>generate a fatal error in POV-Ray</td>
</tr>
</table>

For example if your <code>Pre_Frame_Command</code> calls a program which
generates your height field data and that utility fails then it will return a
non-zero code. We would probably want POV-Ray to abort as well. The option
<code>Pre_Frame_Return=F</code> will cause POV-Ray to do a fatal abort if the
<code>Pre_Frame_Command</code> returns a non-zero code.

Sometimes a non-zero code from the external process is a good thing. Suppose
you want to test if a frame has already been rendered. You could use the
<code>S</code> action to skip this frame if the file is already rendered.
Most utilities report an error if the file is not found. For example the
command...
<pre>
pkzip -V myscene mysce012.tga
</pre>

tells pkzip you want to view the catalog of <code>myscene.zip</code> for
the file <code>mysce012.tga</code>. If the file is not in the archive
<code>pkzip</code> returns a non-zero code.

However we want to skip if the file is found. Therefore we need to reverse
the action so it skips on zero and does not skip on non-zero. To reverse
the zero vs. non-zero triggering of an action precede it with a
"<code>-</code>" sign (note a "<code>!</code>" will also
work since it is used in many programming languages as a negate
operator).

<code>Pre_Frame_Return=S</code> will skip if the code shows error
(non-zero) and will proceed normally on no error (zero). <code>
Pre_Frame_Return=-S</code> will skip if there is no error (zero) and will
proceed normally if there is an error (non-zero).

The default for all shells is <code>I</code> which means that the return
action is ignored no matter what. POV-Ray simply proceeds with whatever it
was doing before the shell command. The other actions depend upon the
context. You may want to refer back to the animation loop sequence chart in
the previous section [[Reference:Shell_Command_Options#Shell_Command_Sequencing|Shell Command Sequencing]]. The action for
each shell is as follows.

On return from any <code>User_Abort_Command</code>:
If there is an action triggered...

<table width="100%" class="option-list">
<tr>
<td width="30%">Specified Action:</td>
<td width="70%">Results:</td>
</tr>

<tr>
<td><code>F</code></td>

<td>
Turn this user abort into a fatal error. 
Do the <code>Fatal_Error_Command</code>, if any. 
Exit POV-Ray with error code 1.
</td>
</tr>

<tr>
<td><code>S</code>, <code>A</code>, <code>Q</code>, or <code>U</code></td>

<td>
Proceed with the user abort. 
Exit POV-Ray with error code 2.
</td>
</tr>
</table>

On return from any <code>Fatal_Error_Command</code>:
POV-Ray will proceed with the fatal error no matter what. It will exit POV-Ray with error code 1.
On return from any <code>Pre_Scene_Command</code>, <code>Pre_Frame_Command</code>, <code>Post_Frame_Command</code> or <code>Post_Scene_Commands</code>:
If there is an action triggered...

<table width="100%" class="option-list">
<tr>
<td width="30%">Specified Action:</td>
<td width="70%">Results:</td>
</tr>

<tr>
<td><code>F</code></td>

<td>
Turn this user abort into a fatal error. 
Do the <code>Fatal_Error_Command</code>, if any. 
Exit POV-Ray with error code 1.
</td>
</tr>

<tr>
<td><code>U</code></td>

<td>
Generate a user abort. 
Do the <code>User_Abort_Command</code>, if any. 
Exit POV-Ray with an error code 2.
</td>
</tr>

<tr>
<td><code>Q</code></td>

<td>
Quit POV-Ray immediately. Acts as though POV-Ray never really ran. 
Do no further shells, not even a <code>Post_Scene_Command</code>. 
Exit POV-Ray with an error code 0.
</td>
</tr>
</table>

On return from a <code>Pre_Scene_Command</code>:
If there is an action triggered...

<table width="100%" class="option-list">
<tr>
<td width="30%">Specified Action:</td>
<td width="70%">Results:</td>
</tr>

<tr>
<td><code>S</code></td>

<td>
Skip rendering all frames. Acts as though the scene completed all frames normally. 
Do not do any <code>Pre_Frame_Command</code> or <code>Post_Frame_Commands</code>. 
Do the <code>Post_Scene_Command</code>, if any. 
Exit POV-Ray with error code 0.
Note: See the [[Reference:Shell_Command_Options#Shell_Command_Sequencing|chart]], this means skip #4
</td>
</tr>

<tr>
<td><code>A</code></td>

<td>
Skip all scene activity. Works exactly like <code>Q</code> quit. Acts as though POV-Ray never really ran.
Do no further shells, not even a <code>Post_Scene_Command</code> 
Exit POV-Ray with an error code 0.
Note: See the [[Reference:Shell_Command_Options#Shell_Command_Sequencing|chart]], this means skip #6
</td>
</tr>
</table>

On return from a <code>Pre_Frame_Command</code>:
If there is an action triggered...

<table width="100%" class="option-list">
<tr>
<td width="30%">Specified Action:</td>
<td width="70%">Results:</td>
</tr>

<tr>
<td><code>S</code></td>

<td>
Skip only this frame. Acts as though this frame never existed. 
Do not do the <code>Post_Frame_Command</code>. 
Proceed with the next frame.
Note: See the [[Reference:Shell_Command_Options#Shell_Command_Sequencing|chart]], this means skip #4b, #4c but loop back as needed in #4d
</td>
</tr>

<tr>
<td><code>A</code></td>

<td>
Skip rendering this frame and all remaining frames. Acts as though the scene completed all frames normally. 
Do not do any further <code>Post_Frame_Commands</code>. 
Do the <code>Post_Scene_Command</code>, if any. 
Exit POV-Ray with error code 0.
Note: See the [[Reference:Shell_Command_Options#Shell_Command_Sequencing|chart]], this means skip the rest of #4 and proceed at #5
</td>
</tr>
</table>

On return from a <code>Post_Frame_Command</code>:
If there is an action triggered...

<table width="100%" class="option-list">
<tr>
<td width="30%">Specified Action:</td>
<td width="70%">Results:</td>
</tr>

<tr>
<td><code>S</code> or <code>A</code></td>

<td>
Skip all remaining frames. Acts as though the scene completed all frames normally. 
Do not do any further <code>Post_Frame_Commands</code>. 
Do the <code>Post_Scene_Command</code>, if any. 
Exit POV-Ray with error code 0.
Note: See the [[Reference:Shell_Command_Options#Shell_Command_Sequencing|chart]], this means skip the rest of #4 and proceed at #5
</td>
</tr>
</table>

On return from any <code>Post_Scene_Command</code>:
If there is an action triggered and you have specified <code>S</code> or <code>A</code> then no special action occurs. This is the same as <code>I</code> for this shell command.

@@ Line 316: / Line 316: @@
 was doing before the shell command. The other actions depend upon the
 context. You may want to refer back to the animation loop sequence chart in
-the previous section <!--<linkto "Shell Command Sequencing">Shell Command Sequencing</linkto>--->[[Reference:Shell_Command_Options#Shell_Command_Sequencing|Shell Command Sequencing]]. The action for
+the previous section [[Reference:Shell Command Options#Shell Command Sequencing|Shell Command Sequencing]]. The action for
 each shell is as follows.</p>
@@ Line 407: / Line 407: @@
 Do the <code>Post_Scene_Command</code>, if any.<br>
 Exit POV-Ray with error code 0.</p>
-<p class="Note"><strong>Note:</strong> See the [[Reference:Shell_Command_Options#Shell_Command_Sequencing|chart]], this means skip #4</p>
+<p class="Note"><strong>Note:</strong> See the [[Reference:Shell Command Options#Shell Command Sequencing|chart]], this means skip #4</p>
 </td>
 </tr>
@@ Line 418: / Line 418: @@
 <p>Do no further shells, not even a <code>Post_Scene_Command</code><br>
 Exit POV-Ray with an error code 0.</p>
-<p class="Note"><strong>Note:</strong> See the [[Reference:Shell_Command_Options#Shell_Command_Sequencing|chart]], this means skip #6</p>
+<p class="Note"><strong>Note:</strong> See the [[Reference:Shell Command Options#Shell Command Sequencing|chart]], this means skip #6</p>
 </td>
 </tr>
@@ Line 439: / Line 439: @@
 Do not do the <code>Post_Frame_Command</code>.<br>
 Proceed with the next frame.</p>
-<p class="Note"><strong>Note:</strong> See the [[Reference:Shell_Command_Options#Shell_Command_Sequencing|chart]], this means skip #4b, #4c but loop back as needed in #4d</p>
+<p class="Note"><strong>Note:</strong> See the [[Reference:Shell Command Options#Shell Command Sequencing|chart]], this means skip #4b, #4c but loop back as needed in #4d</p>
 </td>
 </tr>
@@ Line 451: / Line 451: @@
 Do the <code>Post_Scene_Command</code>, if any.<br>
 Exit POV-Ray with error code 0.</p>
-<p class="Note"><strong>Note:</strong> See the [[Reference:Shell_Command_Options#Shell_Command_Sequencing|chart]], this means skip the rest of #4 and proceed at #5</p>
+<p class="Note"><strong>Note:</strong> See the [[Reference:Shell Command Options#Shell Command Sequencing|chart]], this means skip the rest of #4 and proceed at #5</p>
 </td>
 </tr>
@@ Line 473: / Line 473: @@
 Do the <code>Post_Scene_Command</code>, if any.<br>
 Exit POV-Ray with error code 0.</p>
-<p class="Note"><strong>Note:</strong> See the [[Reference:Shell_Command_Options#Shell_Command_Sequencing|chart]], this means skip the rest of #4 and proceed at #5</p>
+<p class="Note"><strong>Note:</strong> See the [[Reference:Shell Command Options#Shell Command Sequencing|chart]], this means skip the rest of #4 and proceed at #5</p>
 </td>
 </tr>

← Older revision	Revision as of 18:09, 17 July 2012
(No difference)

← Older revision	Revision as of 19:08, 15 March 2012
(No difference)

Reference:Shell Command Options - Revision history

Jholsenback: 1 revision: underscore link repair

Jholsenback: still testing that theory

Jholsenback: 1 revision: Reference Migration Initial Load

Jholsenback: 1 revision: Initial Load (TF)