Difference between revisions of "Reference:General Output Options"

From POV-Wiki
Jump to navigation Jump to search
m (1 revision: underscore link repair)
m (cleanup)
Line 212: Line 212:
 
<tr>
 
<tr>
 
<td width="30%"><code>Continue_Trace=</code>bool{{#indexentry:Continue_Trace, ini-option}}</td>
 
<td width="30%"><code>Continue_Trace=</code>bool{{#indexentry:Continue_Trace, ini-option}}</td>
 
 
<td width="70%">Sets continued trace on/off</td>
 
<td width="70%">Sets continued trace on/off</td>
 
</tr>
 
</tr>
Line 218: Line 217:
 
<tr>
 
<tr>
 
<td><code>+C</code>{{#indexentry:+c}}</td>
 
<td><code>+C</code>{{#indexentry:+c}}</td>
 
 
<td>Sets continued trace on</td>
 
<td>Sets continued trace on</td>
 
</tr>
 
</tr>
Line 224: Line 222:
 
<tr>
 
<tr>
 
<td><code>-C</code>{{#indexentry:-c}}</td>
 
<td><code>-C</code>{{#indexentry:-c}}</td>
 
 
<td>Sets continued trace off</td>
 
<td>Sets continued trace off</td>
 
</tr>
 
</tr>
Line 230: Line 227:
 
<tr>
 
<tr>
 
<td><code>Create_Ini=</code>file{{#indexentry:Create_Ini, ini-option}}</td>
 
<td><code>Create_Ini=</code>file{{#indexentry:Create_Ini, ini-option}}</td>
 
 
<td>Generate an INI file to file</td>
 
<td>Generate an INI file to file</td>
 
</tr>
 
</tr>
Line 236: Line 232:
 
<tr>
 
<tr>
 
<td><code>Create_Ini=</code>true</td>
 
<td><code>Create_Ini=</code>true</td>
 
 
<td>Generate file.ini where file is scene name.</td>
 
<td>Generate file.ini where file is scene name.</td>
 
</tr>
 
</tr>
Line 242: Line 237:
 
<tr>
 
<tr>
 
<td><code>Create_Ini=</code>false</td>
 
<td><code>Create_Ini=</code>false</td>
 
 
<td>Turn off generation of previously set file.ini</td>
 
<td>Turn off generation of previously set file.ini</td>
 
</tr>
 
</tr>
Line 248: Line 242:
 
<tr>
 
<tr>
 
<td><code>+GI</code>file{{#indexentry:+gi}}</td>
 
<td><code>+GI</code>file{{#indexentry:+gi}}</td>
 
 
<td>Same as <code>Create_Ini=</code>file</td>
 
<td>Same as <code>Create_Ini=</code>file</td>
 
</tr>
 
</tr>
 
</table>
 
</table>
  
<p>If you abort a render while it is in progress or if you used the
+
<p>If you abort a render while it is in progress or if you used the <code>[[Reference:General Output Options#Partial Output Options|:End_Row|End_Row]]</code> option to end the render prematurely, you can use <code>Continue_Trace=on</code> or <code>+C</code> option to continue the render later at the point where you left off. This option reads in the previously generated output file, displays the partial image rendered so far, then
<code>[[Reference:General Output Options#Partial Output Options|:End_Row|End_Row]]</code> option to end the render prematurely, you can use
+
proceeds with the ray-tracing. This option cannot be used if file output is disabled with <code>[[Reference:File Output Options|:Output_to_file|Output_to_file]]=off</code> or <code>-F</code>.</p>
<code>Continue_Trace=on</code> or <code>+C</code> option to continue the render
+
 
later at the point where you left off. This option reads in the previously
+
<p>The <code>Continue_Trace</code> option may not work if the <code>Start_Row</code> option has been set to anything but the top of the file, depending on the output format being used. Also POV-Ray cannot continue the file once it has been opened and saved again by any program.</p>
generated output file, displays the partial image rendered so far, then
+
 
proceeds with the ray-tracing. This option cannot be used if file output is
+
<p>POV-Ray tries to figure out where to resume an interrupted trace by reading any previously generated data in the specified output file. All file formats contain the image size, so this will override any image size settings
disabled with <code>[[Reference:File Output Options|:Output_to_file|Output_to_file]]=off</code>
+
specified. Some file formats (namely TGA and PNG) also store information about where the file started (i. e. <code> +SC</code><em>n</em> and <code>+SR</code><em>n</em> options), alpha output <code>+UA</code>, and bit-depth
or <code>-F</code>.</p>
+
<code>+FN</code><em>n</em>, which will override these settings. It is up to the user to make sure that all other options are set the same as the original render.</p>
<p>
+
 
The <code>Continue_Trace</code> option may not work if the <code>Start_Row</code>
+
<p>The <code>Create_Ini</code> option or <code>+GI</code> switch provides an easy way to create an INI file with all of the rendering options, so you can re-run files with the same options, or ensure you have all the same options when resuming. This option creates an INI file with every option set at the value used for that rendering. This includes default values which you have not specified. For example if you run POV-Ray with...</p>
option has been set to anything but the top of the file, depending on the output format being used. Also POV-Ray cannot continue the file once it has been opened and saved again by any program</p>
+
 
<p>
 
POV-Ray tries to figure out where to resume an interrupted trace by reading
 
any previously generated data in the specified output file. All file formats
 
contain the image size, so this will override any image size settings
 
specified. Some file formats (namely TGA and PNG) also store information
 
about where the file started (i. e. <code> +SC</code><em>n</em> and <code>
 
+SR</code><em>n</em> options), alpha output <code>+UA</code>, and bit-depth
 
<code>+FN</code><em>n</em>, which will override these settings. It is up to
 
the user to make sure that all other options are set the same as the original
 
render.</p>
 
<p>
 
The <code>Create_Ini</code> option or <code>+GI</code> switch provides an
 
easy way to create an INI file with all of the rendering options, so you can
 
re-run files with the same options, or ensure you have all the same options
 
when resuming. This option creates an INI file with every option set at the
 
value used for that rendering. This includes default values which you have
 
not specified. For example if you run POV-Ray with...</p>
 
 
<pre>
 
<pre>
 
POVRAY +Isimple.pov MYOPTS +GIrerun.ini MOREOPTS
 
POVRAY +Isimple.pov MYOPTS +GIrerun.ini MOREOPTS
 
</pre>
 
</pre>
  
<p>POV-Ray will create a file called <code>rerun.ini</code> with all of the
+
<p>POV-Ray will create a file called <code>rerun.ini</code> with all of the options used to generate this scene. The file is not written until all options have been processed. This means that in the above example, the file
options used to generate this scene. The file is not written until all
+
will include options from both <code>myopts.ini</code> and <code>moreopts.ini</code> despite the fact that the <code>+GI</code> switch is specified between them. You may now re-run the scene with...</p>
options have been processed. This means that in the above example, the file
+
 
will include options from both <code>myopts.ini</code> and <code>
 
moreopts.ini</code> despite the fact that the <code>+GI</code> switch is
 
specified between them. You may now re-run the scene with...</p>
 
 
<pre>
 
<pre>
 
POVRAY RERUN
 
POVRAY RERUN
Line 296: Line 269:
  
 
<p>or resume an interrupted trace with</p>
 
<p>or resume an interrupted trace with</p>
 +
 
<pre>
 
<pre>
 
POVRAY RERUN +C
 
POVRAY RERUN +C
 
</pre>
 
</pre>
  
<p>If you add other switches with the <code>rerun.ini</code> reference, they
+
<p>If you add other switches with the <code>rerun.ini</code> reference, they will be included in future re-runs because the file is re-written every time you use it.</p>
will be included in future re-runs because the file is re-written every time
+
 
you use it.</p>
+
<p>The <code>Create_Ini</code> option is also useful for documenting how a scene was rendered. If you render <code> waycool.pov</code> with <code>Create_Ini=on</code> then it will create a file <code>waycool.ini</code> that
<p>
+
you could distribute along with your scene file so other users can exactly re-create your image.</p>
The <code>Create_Ini</code> option is also useful for documenting how a
 
scene was rendered. If you render <code> waycool.pov</code> with <code>
 
Create_Ini=on</code> then it will create a file <code>waycool.ini</code> that
 
you could distribute along with your scene file so other users can exactly
 
re-create your image.</p>
 

Revision as of 15:28, 10 August 2012

Height and Width of Output

Height=n
Sets screen height to n pixels
Width=n
Sets screen width to n pixels
+Hn
Same as Height=n
+Wn
Same as Width=n

These switches set the height and width of the image in pixels. This specifies the image size for file output. The preview display, if on, will generally attempt to pick a video mode to accommodate this size but the display settings do not in any way affect the resulting file output.

Max Image Buffer Memory

Max_Image_Buffer_Memory=n
Sets the allowable size of the output image cache
+MIn
Same as Max_Image_Buffer_Memory=n

This INI parameter sets the number of megabytes of RAM to allow for output image caching. If the output image happens to use more than this, a file backed temporary image is used instead. If using this option you must specify a value. This option is on by default and its value is 128.

Partial Output Options

Start_Column=n
Set first column to n pixels
Start_Column=0.n Set first column to n percent of width
+SC0.n
Same as Start_Column
Start_Row=n
Set first row to n pixels
Start_Row=0.n Set first row to n percent of height
+Sn
Same as Start_Row=n
+SR0.n or +S0.n Same as Start_Row=0.n
End_Column=n
Set last column to n pixels
End_Column=0.n Set last column to n percent of width
+EC0.n
Same as End_Column
End_Row=n
Set last row to n pixels
End_Row=0.n Set last row to n percent of height
+En
Same as End_Row=n
+ER0.n or +E0.n Same as End_Row=0.n

When doing test rendering it is often convenient to define a small, rectangular sub-section of the whole screen so you can quickly check out one area of the image. The Start_Row, End_Row, Start_Column and End_Column options allow you to define the subset area to be rendered. The default values are the full size of the image from (1,1) which is the upper left to (w,h) on the lower right where w and h are the Width=n and Height=n values you have set.

Note: If the number specified is greater than 1 then it is interpreted as an absolute row or column number in pixels. If it is a decimal value between 0.0 and 1.0 then it is interpreted as a percent of the total width or height of the image.

For example: Start_Row=0.75 and Start_Column=0.75 starts on a row 75% down from the top at a column 75% from the left. Thus it renders only the lower-right 25% of the image regardless of the specified width and height.

The +SR, +ER, +SC and +EC switches work in the same way as the corresponding INI-style settings for both absolute settings or percentages. Early versions of POV-Ray allowed only start and end rows to be specified with +Sn and +En so they are still supported in addition to +SR and +ER.

When rendering a subset of columns (+sc/+ec) and/or rows (+sr/+er), POV-Ray generates a full width image and fills the not rendered columns with black pixels. This should not be a problem for any image reading program no matter what file format is used. Earlier versions of POV-Ray had problems when a subset of rows (+sr/+er) was rendered. The full height information was written into the image file header but it only wrote image data for those lines that were actually rendered. This made output files that were incompatible with various image processing tools. In version 3.7 this is no longer the case.

Interrupting Options

Test_Abort=bool
Turn test for user abort on/off
+X
Turn test abort on
-X
Turn test abort off
Test_Abort_Count=n
Set to test for abort every n pixels
+Xn Set to test for abort every n pixels on
-Xn Set to test for abort off (in future test every n pixels)

On some operating systems once you start a rendering you must let it finish. The Test_Abort=on option or +X switch causes POV-Ray to test the keyboard for keypress. If you have pressed a key, it will generate a controlled user abort. Files will be flushed and closed but only data through the last full row of pixels is saved. POV-Ray exits with an error code 2 (normally POV-Ray returns 0 for a successful run or 1 for a fatal error).

When this option is on, the keyboard is polled on every line while parsing the scene file and on every pixel while rendering. Because polling the keyboard can slow down a rendering, the Test_Abort_Count=n option or +Xn switch causes the test to be performed only every n pixels rendered or scene lines parsed.

Resuming Options

Continue_Trace=bool
Sets continued trace on/off
+C
Sets continued trace on
-C
Sets continued trace off
Create_Ini=file
Generate an INI file to file
Create_Ini=true Generate file.ini where file is scene name.
Create_Ini=false Turn off generation of previously set file.ini
+GIfile
Same as Create_Ini=file

If you abort a render while it is in progress or if you used the End_Row option to end the render prematurely, you can use Continue_Trace=on or +C option to continue the render later at the point where you left off. This option reads in the previously generated output file, displays the partial image rendered so far, then proceeds with the ray-tracing. This option cannot be used if file output is disabled with Output_to_file=off or -F.

The Continue_Trace option may not work if the Start_Row option has been set to anything but the top of the file, depending on the output format being used. Also POV-Ray cannot continue the file once it has been opened and saved again by any program.

POV-Ray tries to figure out where to resume an interrupted trace by reading any previously generated data in the specified output file. All file formats contain the image size, so this will override any image size settings specified. Some file formats (namely TGA and PNG) also store information about where the file started (i. e. +SCn and +SRn options), alpha output +UA, and bit-depth +FNn, which will override these settings. It is up to the user to make sure that all other options are set the same as the original render.

The Create_Ini option or +GI switch provides an easy way to create an INI file with all of the rendering options, so you can re-run files with the same options, or ensure you have all the same options when resuming. This option creates an INI file with every option set at the value used for that rendering. This includes default values which you have not specified. For example if you run POV-Ray with...

POVRAY +Isimple.pov MYOPTS +GIrerun.ini MOREOPTS

POV-Ray will create a file called rerun.ini with all of the options used to generate this scene. The file is not written until all options have been processed. This means that in the above example, the file will include options from both myopts.ini and moreopts.ini despite the fact that the +GI switch is specified between them. You may now re-run the scene with...

POVRAY RERUN

or resume an interrupted trace with

POVRAY RERUN +C

If you add other switches with the rerun.ini reference, they will be included in future re-runs because the file is re-written every time you use it.

The Create_Ini option is also useful for documenting how a scene was rendered. If you render waycool.pov with Create_Ini=on then it will create a file waycool.ini that you could distribute along with your scene file so other users can exactly re-create your image.