|
|
Line 1: |
Line 1: |
− | ==Introduction==
| |
− | ===Command-line Options===
| |
− | <p>The reference section describes all command line switches and INI file
| |
− | keywords that are used to set the options of POV-Ray. It is supposed to be
| |
− | used as a reference for looking up things. It does not contain detailed
| |
− | explanations on how scenes are written or how POV-Ray is used. It just
| |
− | explains all features, their syntax, applications, limits, drawbacks,
| |
− | etc.</p>
| |
− |
| |
− | <p>Options may be specified by switches
| |
− | or INI-style options. Almost all INI-style options have equivalent <code>
| |
− | +</code>/ <code>-</code> switches and most switches have equivalent INI-style
| |
− | option. The following sections give a detailed description of each POV-Ray
| |
− | option. It includes both the INI-style settings and the <code> +</code>/
| |
− | <code>-</code> switches.</p>
| |
− | <p>
| |
− | The notation and terminology used is described in the tables below.</p>
| |
− |
| |
− | <table width="100%">
| |
− | <tr>
| |
− | <td width="30%"><code>Keyword=</code>bool</td>
| |
− |
| |
− | <td width="70%">Turn <code>Keyword</code> on if bool equals <code>true</code>, <code>
| |
− | yes</code>, <code>on</code> or <code>1</code> and Turn it off if it is any
| |
− | other value.</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>Keyword=true</code></td>
| |
− |
| |
− | <td>Do this option if <code>true</code>, <code>yes</code>, <code> on</code>
| |
− | or <code>1</code> is specified.</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>Keyword=false</code></td>
| |
− |
| |
− | <td>Do this option if <code>false</code>, <code>no</code>, <code>
| |
− | off</code> or <code>0</code> is specified.</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>Keyword=</code>filename</td>
| |
− |
| |
− | <td>Set <code>Keyword</code> to filename where filename is any valid file
| |
− | name.
| |
− | <p class="Note"><strong>Note:</strong> some options prohibit the use of any of the above <code>
| |
− | true</code> or <code>false</code> values as a file name. They are noted in
| |
− | later sections.</p></td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td>n</td>
| |
− |
| |
− | <td>Any integer such as in <code>+W320</code></td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td>n.n</td>
| |
− |
| |
− | <td>Any float such as in <code>Clock=3.45</code></td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td>0.n</td>
| |
− |
| |
− | <td>Any float < 1.0 even if it has no leading 0</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td>s</td>
| |
− |
| |
− | <td>Any string of text</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td>x or y</td>
| |
− |
| |
− | <td>Any single character</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td>path</td>
| |
− |
| |
− | <td>Any directory name, drive optional, no final path separator
| |
− | ("\" or "/", depending on the operating system)</td>
| |
− | </tr>
| |
− | </table>
| |
− |
| |
− | <p>Unless otherwise specifically noted, you may assume that either a plus or
| |
− | minus sign before a switch will produce the same results.</p>
| |
− |
| |
− | ===Animation Options===
| |
− | <!--<indexentry "Animation, options" "Options, animation">--->
| |
− |
| |
− | <p>Internal animation loop, automatic output file name numbering and the
| |
− | ability to shell out to the operating system to external utilities which can
| |
− | assemble individual frames into an animation, greatly improved the animation capability.
| |
− | The internal animation loop is simple yet flexible. You may still use external programs or batch files to
| |
− | create animations without the internal loop.</p>
| |
− |
| |
− | ===External Animation Loop===
| |
− | <!--<indexentry "Animation, external loop">--->
| |
− | <!--<indexentry "+k">--->
| |
− | <table width="100%">
| |
− | <tr>
| |
− | <td width="30%"><code>Clock=</code>n.n</td>
| |
− |
| |
− | <td width="70%">Sets <code><!--<linkto "clock">clock</linkto>--->[[Documentation:Reference Section 2.1#Built-in Variables|clock]]</code> float identifier to n.n</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>+K</code>n.n</td>
| |
− |
| |
− | <td>Same as <code>Clock=</code>n.n</td>
| |
− | </tr>
| |
− | </table>
| |
− | <!--<indexentry primary "Clock, ini-option">--->
| |
− | <p>The <code>Clock=</code><em>n.n</em> option or the <code>
| |
− | +K</code><em>n.n</em> switch may be used to pass a single float value to the
| |
− | program for basic animation. The value is stored in the float identifier
| |
− | <code>clock</code>. If an object had a <code>rotate <0,clock,0></code>
| |
− | attached then you could rotate the object by different amounts over different
| |
− | frames by setting <code> +K10.0</code>,<code>+K20.0</code>... etc. on
| |
− | successive renderings. It is up to the user to repeatedly invoke POV-Ray with
| |
− | a different <code> Clock</code> value and a different <code>
| |
− | Output_File_Name</code> for each frame.</p>
| |
− |
| |
− | ===Internal Animation Loop===
| |
− | <!--<indexentry "Animation, internal loop">--->
| |
− | <table width="100%">
| |
− | <tr>
| |
− | <td width="30%"><code>Initial_Frame=</code>n</td><!--<indexentry primary "Initial_Frame, ini-option">--->
| |
− |
| |
− | <td width="70%">Sets initial frame number to n</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>Final_Frame=</code>n</td><!--<indexentry primary "Final_Frame, ini-option">--->
| |
− |
| |
− | <td>Sets final frame number to n</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>Initial_Clock=</code>n.n</td><!--<indexentry primary "Initial_Clock, ini-option">--->
| |
− |
| |
− | <td>Sets initial clock value to n.n</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>Final_Clock=</code>n.n</td><!--<indexentry primary "Final_Clock, ini-option">--->
| |
− |
| |
− | <td>Sets final clock value to n.n</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>+KFI</code>n</td><!--<indexentry "+kfi">--->
| |
− |
| |
− | <td>Same as <code>Initial_Frame=</code>n</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>+KFF</code>n</td><!--<indexentry "+kff">--->
| |
− |
| |
− | <td>Same as <code>Final_Frame=</code>n</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>+KI</code>n.n</td><!--<indexentry "+ki">--->
| |
− |
| |
− | <td>Same as <code>Initial_Clock=</code>n.n</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>+KF</code>n.n</td>
| |
− |
| |
− | <td>Same as <code>Final_Clock=</code>n.n</td>
| |
− | </tr>
| |
− | </table>
| |
− |
| |
− | <p>The internal animation loop relieves the user of the
| |
− | task of generating complicated sets of batch files to invoke POV-Ray multiple
| |
− | times with different settings. While the multitude of options may look
| |
− | intimidating, the clever set of default values means that you will probably
| |
− | only need to specify the <code>Final_Frame</code>=<em>n</em> or the
| |
− | <code>+KFF</code><em>n</em> option to specify the number of frames. All other
| |
− | values may remain at their defaults.</p>
| |
− | <p>
| |
− | Any <code>Final_Frame</code> setting other than -1 will trigger
| |
− | POV-Ray's internal animation loop. For example <code>
| |
− | Final_Frame=10</code> or <code>+KFF10</code> causes POV-Ray to render your
| |
− | scene 10 times. If you specified <code><!--<linkto "Output_File_Name">Output_File_Name</linkto>--->[[Documentation:Reference Section 1.1#Output File Name|Output_File_Name]]=file.tga</code>
| |
− | then each frame would be output as <code>file01.tga</code>, <code>file02.tga</code>,
| |
− | <code>file03.tga</code> etc. The number of zero-padded digits in the file name
| |
− | depends upon the final frame number. For example <code>+KFF100</code> would
| |
− | generate <code>file001.tga</code> through <code>file100.tga</code>. The frame
| |
− | number may encroach upon the file name. On MS-DOS with an eight character limit,
| |
− | <code>myscene.pov</code> would render to <code>mysce001.tga</code> through
| |
− | <code>mysce100.tga</code>.</p>
| |
− | <p>
| |
− | The default <code>Initial_Frame=1</code> will probably never have to be
| |
− | changed. You would only change it if you were assembling a long animation
| |
− | sequence in pieces. One scene might run from frame 1 to 50 and the next from
| |
− | 51 to 100. The <code>Initial_Frame</code>=<em>n</em> or <code>
| |
− | +KFI</code><em>n</em> option is for this purpose.</p>
| |
− | <p class="Note"><strong>Note:</strong> if you wish to render a subset of frames such as 30 through 40 out
| |
− | of a 1 to 100 animation, you should not change <code>Initial_Frame</code> or
| |
− | <code>Final_Frame</code>. Instead you should use the subset commands
| |
− | described in section "<!--<linkto "Subsets of Animation Frames">Subsets of Animation Frames</linkto>--->[[Documentation:Reference Section 1#Subsets of Animation Frames|Subsets of Animation Frames]]".</p>
| |
− | <p>
| |
− | Unlike some animation packages, the action in POV-Ray animated scenes does
| |
− | not depend upon the integer frame numbers. Rather you should design your
| |
− | scenes based upon the float identifier <code><!--<linkto "clock">clock</linkto>--->[[Documentation:Reference Section 2.1#Built-in Variables|clock]]</code>. By default, the
| |
− | clock value is 0.0 for the initial frame and 1.0 for the final frame. All
| |
− | other frames are interpolated between these values. For example if your
| |
− | object is supposed to rotate one full turn over the course of the animation,
| |
− | you could specify <code>rotate 360*clock*y</code>. Then as clock runs from
| |
− | 0.0 to 1.0, the object rotates about the y-axis from 0 to 360 degrees.</p>
| |
− | <p>
| |
− | The major advantage of this system is that you can render a 10 frame
| |
− | animation or a 100 frame or 500 frame or 329 frame animation yet you still
| |
− | get one full 360 degree rotation. Test renders of a few frames work exactly
| |
− | like final renders of many frames.</p>
| |
− | <p>
| |
− | In effect you define the motion over a continuous float valued parameter
| |
− | (the clock) and you take discrete samples at some fixed intervals (the
| |
− | frames). If you take a movie or video tape of a real scene it works the same
| |
− | way. An object's actual motion depends only on time. It does not depend
| |
− | on the frame rate of your camera.</p>
| |
− | <p>
| |
− | Many users have already created scenes for POV-Ray 2 that expect clock
| |
− | values over a range other than the default 0.0 to 1.0. For this reason we
| |
− | provide the <code>Initial_Clock</code>=<em>n.n</em>
| |
− | or <code>+KI</code><em>n.n</em> and <code>Final_Clock</code>=<em>n.n</em>
| |
− | or <code>+KF</code><em>n.n</em> options. For example to run the clock from 25.0 to
| |
− | 75.0 you would specify <code>Initial_Clock=25.0</code> and <code>Final_Clock=75.0</code>.
| |
− | Then the clock would be set to 25.0 for the initial frame and 75.0 for the final frame.
| |
− | In-between frames would have clock values interpolated from 25.0 through 75.0 proportionally.</p>
| |
− | <p>
| |
− | Users who are accustomed to using frame numbers rather than clock values
| |
− | could specify <code> Initial_Clock=1.0</code> and <code>Final_Clock=10.0</code>
| |
− | and <code>Frame_Final=10</code> for a 10 frame animation.</p>
| |
− | <p>
| |
− | For new scenes, we recommend you do not change the <code>
| |
− | Initial_Clock</code> or <code> Final_Clock</code> from their default 0.0 to
| |
− | 1.0 values. If you want the clock to vary over a different range than the
| |
− | default 0.0 to 1.0, we recommend you handle this inside your scene file as
| |
− | follows...</p>
| |
− | <pre>
| |
− | #declare Start = 25.0;
| |
− | #declare End = 75.0;
| |
− | #declare My_Clock = Start+(End-Start)*clock;
| |
− | </pre>
| |
− |
| |
− | <p>Then use <code>My_Clock</code> in the scene description. This keeps the
| |
− | critical values 25.0 and 75.0 in your .pov file.</p>
| |
− | <p class="Note"><strong>Note:</strong> more details concerning the inner workings of the animation loop
| |
− | are in the section on shell-out operating system commands in section
| |
− | "<!--<linkto "Shell-out to Operating System">Shell-out to Operating System</linkto>--->[[Documentation:Reference Section 1.2#Shell-out to Operating System|Shell-out to Operating System]]".</p>
| |
− |
| |
− | ===Subsets of Animation Frames===
| |
− | <!--<indexentry "Animation, subsets of frames">--->
| |
− |
| |
− | <table width="100%">
| |
− | <tr>
| |
− | <td width="30%"><code>Subset_Start_Frame=</code>n<!--<indexentry primary "Subset_Start_Frame"><indexentry primary "Subset_Start_Frame, ini-option"></td>--->
| |
− |
| |
− | <td width="70%">Set subset starting frame to n</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>Subset_Start_Frame=</code>0.n</td>
| |
− |
| |
− | <td>Set subset starting frame to n percent</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>Subset_End_Frame=</code>n<!--<indexentry primary "Subset_End_Frame"><indexentry primary "Subset_End_Frame, ini-option"></td>--->
| |
− |
| |
− | <td>Set subset ending frame to n</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>Subset_End_Frame=</code>0.n</td>
| |
− |
| |
− | <td>Set subset ending frame to n percent</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>+SF</code>0.n<!--<indexentry "+sf"></td>--->
| |
− |
| |
− | <td>Same as <code>Subset_Start_Frame</code></td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>+EF</code>0.n<!--<indexentry "+ef"></td>--->
| |
− |
| |
− | <td>Same as <code>Subset_End_Frame</code></td>
| |
− | </tr>
| |
− | </table>
| |
− |
| |
− | <p>When creating a long animation, it may be handy to render only a portion
| |
− | of the animation to see what it looks like. Suppose you have 100 frames but
| |
− | only want to render frames 30 through 40. If you set <code>Initial_Frame=30</code>
| |
− | and <code>Final_Frame=40</code> then the clock would vary from 0.0 to 1.0 from
| |
− | frames 30 through 40 rather than 0.30 through 0.40 as it should. Therefore
| |
− | you should leave <code> Initial_Frame=1</code> and <code>Final_Frame=100</code>
| |
− | and use <code>Subset_Start_Frame=30</code> and <code>Subset_End_Frame=40</code>
| |
− | to selectively render part of the scene. POV-Ray will then properly compute the
| |
− | clock values.</p>
| |
− | <p>
| |
− | Usually you will specify the subset using the actual integer frame numbers
| |
− | however an alternate form of the subset commands takes a float value in the
| |
− | range <em>0.0 <=n.nnn <=1.0</em> which is interpreted as a fraction of
| |
− | the whole animation. For example, <code> Subset_Start_Frame=0.333</code> and
| |
− | <code>Subset_End_Frame=0.667</code> would render the middle 1/3rd of a
| |
− | sequence regardless of the number of frames.</p>
| |
− | ===Cyclic Animation===
| |
− | <!--<indexentry "Animation, cyclic">--->
| |
− |
| |
− | <table width="100%">
| |
− | <tr>
| |
− | <td width="30%"><code>Cyclic_Animation=</code>bool<!--<indexentry primary "Cyclic_Animation"></td>--->
| |
− |
| |
− | <td width="70%">Turn cyclic animation on/off</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>+KC</code><!--<indexentry "+kc"></td>--->
| |
− |
| |
− | <td>Turn cyclic animation on</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>-KC</code><!--<indexentry "-kc"></td>--->
| |
− |
| |
− | <td>Turn cyclic animation off</td>
| |
− | </tr>
| |
− | </table>
| |
− |
| |
− | <p>Many computer animation sequences are designed to be run in a continuous
| |
− | loop. Suppose you have an object that rotates exactly 360 degrees over the
| |
− | course of your animation and you did <code>rotate 360*clock*y</code> to do
| |
− | so. Both the first and last frames would be identical. Upon playback there
| |
− | would be a brief one frame jerkiness. To eliminate this problem you need to
| |
− | adjust the clock so that the last frame does not match the first. For example
| |
− | a ten frame cyclic animation should not use clock 0.0 to 1.0. It should run
| |
− | from 0.0 to 0.9 in 0.1 increments. However if you change to 20 frames it
| |
− | should run from 0.0 to 0.95 in 0.05 increments. This complicates things
| |
− | because you would have to change the final clock value every time you changed
| |
− | <code>Final_Frame</code>. Setting <code>Cyclic_Animation=on</code> or using
| |
− | <code>+KC</code> will cause POV-Ray to automatically adjust the final clock
| |
− | value for cyclic animation regardless of how many total frames. The default
| |
− | value for this setting is off.</p>
| |
− |
| |
− | ===Field Rendering===
| |
− | <!--<indexentry "Animation, field rendering">--->
| |
− |
| |
− | <table width="100%">
| |
− | <tr>
| |
− | <td width="30%"><code>Field_Render=</code>bool<!--<indexentry primary "Field_Render"></td>--->
| |
− |
| |
− | <td width="70%">Turn field rendering on/off</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>Odd_Field=</code>bool<!--<indexentry primary "Odd_Field"></td>--->
| |
− |
| |
− | <td>Set odd field flag</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>+UF</code><!--<indexentry "+uf"></td>--->
| |
− |
| |
− | <td>Turn field rendering on</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>-UF</code><!--<indexentry "-uf"></td>--->
| |
− |
| |
− | <td>Turn field rendering off</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>+UO</code><!--<indexentry "+uo"></td>--->
| |
− |
| |
− | <td>Set odd field flag on</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>-UO</code><!--<indexentry "-uo"></td>--->
| |
− |
| |
− | <td>Set odd field flag off</td>
| |
− | </tr>
| |
− | </table>
| |
− |
| |
− | <p>Field rendering is sometimes used for animations when the animation is
| |
− | being output for television. TVs only display alternate scan lines on each
| |
− | vertical refresh. When each frame is being displayed the fields are
| |
− | interlaced to give the impression of a higher resolution image. The even scan
| |
− | lines make up the even field, and are drawn first (i.e. scan lines 0, 2, 4,
| |
− | etc.), followed by the odd field, made up of the odd numbered scan lines are
| |
− | drawn afterwards. If objects in an animation are moving quickly, their
| |
− | position can change noticeably from one field to the next. As a result, it
| |
− | may be desirable in these cases to have POV-Ray render alternate fields at
| |
− | the actual field rate (which is twice the frame rate), rather than rendering
| |
− | full frames at the normal frame rate. This would save a great deal of time
| |
− | compared to rendering the entire animation at twice the frame rate, and then
| |
− | only using half of each frame.</p>
| |
− | <p>
| |
− | By default, field rendering is not used. Setting <code>
| |
− | Field_Render=on</code> or using <code> +UF</code> will cause alternate frames
| |
− | in an animation to be only the even or odd fields of an animation. By
| |
− | default, the first frame is the even field, followed by the odd field. You
| |
− | can have POV-Ray render the odd field first by specifying <code>
| |
− | Odd_Field=on</code>, or by using the <code> +UO</code> switch.</p>
| |
− |
| |
− | ===General Output Options===
| |
− | <!--<indexentry "Options, general output">--->
| |
− | ===Height and Width of Output===
| |
− | <!--<indexentry "Options, height and width" "Resolution">--->
| |
− |
| |
− | <table width="100%">
| |
− | <tr>
| |
− | <td width="30%"><code>Height=</code>n<!--<indexentry primary "Height, ini-option"></td>--->
| |
− |
| |
− | <td width="70%">Sets screen height to n pixels</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>Width=</code>n<!--<indexentry primary "Width, ini-option"></td>--->
| |
− |
| |
− | <td>Sets screen width to n pixels</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>+H</code>n<!--<indexentry "+h"></td>--->
| |
− |
| |
− | <td>Same as <code>Height=</code>n</td>
| |
− | </tr>
| |
− |
| |
− | <tr>
| |
− | <td><code>+W</code>n<!--<indexentry "+w"></td>--->
| |
− |
| |
− | <td>Same as <code>Width=</code>n</td>
| |
− | </tr>
| |
− | </table>
| |
− |
| |
− | <p>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.</p>
| |
| ===Partial Output Options=== | | ===Partial Output Options=== |
| <!--<indexentry "Options, partial output">---> | | <!--<indexentry "Options, partial output">---> |
Line 567: |
Line 115: |
| format is used.</p> | | format is used.</p> |
| | | |
− | <p>when rendering a subset of *rows* (<code>+sr/+er</code>) POV-Ray writes the full height into the image file header and only writes those lines into the | + | <p>When rendering a subset of *rows* (<code>+sr/+er</code>) POV-Ray writes the full height into the image file header and only writes those lines into the |
| image that are rendered. This can cause problems with image reading | | image that are rendered. This can cause problems with image reading |
| programs that are not checking the file while reading and just read over | | programs that are not checking the file while reading and just read over |
| the end.</p> | | the end.</p> |
| | | |
− | <p>if POV-Ray wrote the actual height of the partial image into the image | + | <p>If POV-Ray wrote the actual height of the partial image into the image |
| header there would be no way to continue the trace in a later run.</p> | | header there would be no way to continue the trace in a later run.</p> |
| + | |
| + | :* Merged correction (writed->writes) back into main document. As well as missing caps on 1st words of last two paragraphs. BTW: It's not necessary to copy the ENTIRE page just the affected section(s) please. --[[User:Jholsenback|jholsenback]] 03:30, 28 May 2010 (UTC) |