Difference between revisions of "Reference:Version Directive"

From POV-Wiki
Jump to navigation Jump to search
m (minor update)
m (changes from talk page)
Line 3: Line 3:
 
{{#indexentry:#version}}
 
{{#indexentry:#version}}
 
{{#indexentry:version}}
 
{{#indexentry:version}}
<p>As POV-Ray has evolved from version 1.0 through 3.8 we have made every effort to maintain some amount of backwards compatibility with earlier versions. Some old or obsolete features can be handled directly without any special consideration by the user. Some old or obsolete features can no longer be handled at all. However <em>some</em> old features can still be
+
<p>Since POV-Ray has evolved over the years from version 1.0 through 3.8 we have made every effort to maintain some amount of backwards compatibility with earlier versions. Some old or obsolete features can be handled directly without any special consideration by the user. Some old or obsolete features can no longer be handled at all. However <em>some</em> old features can still be used if you alert POV-Ray that this is an older scene. The <code>#version</code> directive can be used to switch version compatibility or change default settings several times throughout a scene file.</p>
used if you warn POV-Ray that this is an older scene. The <code>#version</code> directive can be used to switch version compatibility to different setting several times throughout a scene file. The syntax is:</p>
+
 
 +
<p>The syntax is:</p>
 +
 
 
<pre>
 
<pre>
 
VERSION_DIRECTIVE:  
 
VERSION_DIRECTIVE:  
 
   #version FLOAT;
 
   #version FLOAT;
 
</pre>
 
</pre>
<p class="Note"><strong>Note:</strong> There should be a semi-colon after the float expression in a <code>#version</code> directive. This semi-colon is introduced in POV-Ray version 3.1. If omitted, it generates a warning and some macros may not work
+
 
properly.</p>
+
<p>There must be a semi-colon after the float expression in a <code>#version</code> directive. If omitted a warning is generated and some macros may not work properly. Additionally you may use the <code>Version=</code><em>n.n</em> option or the <code>+MV</code><em>n.n</em> switch to establish the <em>initial</em> setting. For example, the parsing of float expressions was introduced in version 2.0 and it was incompatible with <em>any</em> version 1.0 scene file. Using <code>#version 1.0</code> turns off expression parsing as well as many warning messages so that nearly all 1.0 files will still work. Some obsolete or re-designed features <em>are totally unavailable in the current version of POV-Ray REGARDLESS OF THE VERSION SETTING.</em> Details on these features are noted throughout this documentation.</p>
<p>Additionally you may use the <code>Version=</code><em>n.n</em> option or the <code>+MV</code><em>n.n</em> switch to establish the <em>initial</em> setting. See <!--<linkto "Language Version">Language Version</linkto>--->[[Reference:Scene Parsing Options#Language Version|Language Version]] for details. For example, one feature introduced in 2.0 that was incompatible with any 1.0 scene files is the parsing of float expressions. Using <code>#version 1.0</code> turns off expression parsing as well as many warning messages so that nearly all 1.0 files will still work.</p>
+
 
<p class="Note"><strong>Note:</strong> Some obsolete or re-designed features <em>are totally unavailable in the current version of POV-Ray REGARDLESS OF THE VERSION SETTING.</em> Details on these features are noted throughout this documentation.</p>
+
<p>As of version 3.7 the following <em>requirement</em> has been implemented. In order to obtain full version 3.7 functionality you <em>MUST</em> specify the <code>#version 3.7;</code> directive in your scene file. Prior to a <code>#version</code> directive appearing the version defaults to 3.62. Additionally, if the first <code>#version</code> directive appears after any other declaration, or a <code>#version</code> directive does not appear at all a post-parse warning is issued. A {{Change}} as of POV-Ray 3.8 now makes it an outright error to use <code>#version 3.8;</code> or higher in a main scene file that does not start with a <code>#version</code> directive.</p>
<p>The built-in float identifier <code>version</code> contains the current setting of the version compatibility option. See
+
 
Float Expressions: [[Reference:Numeric Expressions#Built-in Variables|:Float, built-in variables|Built-in Variables]]. Together with the built-in <code>version</code> identifier the <code>#version</code> directive allows you to save and restore the previous values of this compatibility setting. The new <code>#local</code> identifier option is especially useful here. For example, suppose <code>mystuff.inc</code> is in version 3.5 format. At the top of the file you could put:</p>
+
<p>New defaults require that the language version is explicitly set to 3.8 or higher via the <code>#version</code> directive the <code>Version=</code>n.n INI setting or the <code>+MV</code>n.n command-line option. Otherwise POV-Ray will fall back to legacy defaults for backwards compatibility.</p>
 +
 
 +
<p>If you do need to do some processing before you decide on a version compatibility option start your scene with the following
 +
construct:</p>
 +
<pre>
 +
  #version version;
 +
</pre>
 +
 
 +
<p>The built-in float identifier <code>version</code> contains the current setting of the version compatibility option. See Float Expressions: [[Reference:Numeric Expressions#Built-in Variables|:Float, built-in variables|Built-in Variables]]. Together with the built-in <code>version</code> identifier and the <code>#version</code> directive will allow you to save and restore the previous values of this compatibility setting. The <code>#local</code> identifier option is especially useful here. For example the include file <code>mystuff.inc</code> is in version 3.5 format, so at the top of that file you would include:</p>
 
<pre>
 
<pre>
 
   #local Temp_Vers = version;  // Save previous value
 
   #local Temp_Vers = version;  // Save previous value
Line 22: Line 32:
 
</pre>
 
</pre>
  
<p>As of version 3.7, there has been a <em>requirement</em> implemented. In order to obtain full version 3.7
+
<p class="Note"><strong>Note:</strong> In version 3.7, if the version compatibility option was left at its default, the <code>version</code> identifier evaluated to the actual POV-Ray version number, instead of matching the defaulted version compatibility setting of 3.62. This would cause problems with include files using the above construct, as it would inadvertently switch the compatibility setting from 3.62 to 3.7. This has been fixed by a {{Change}} in version 3.8, where the <code>version</code> identifier matches the version compatibility option default in such a situation. There is still one exception to this rule: If the scene starts with a <code>#version</code> directive, and the <code>version</code> identifier is used in that directive, it will default to the actual POV-Ray version number in that very first statement, so that the <code>#version version;</code> idiom can still be used.</p>
functionality, you <em>MUST</em> specify the <code>#version 3.7</code> directive in your scene file. Prior to a
+
 
<code>#version</code> directive appearing, the version defaults to 3.62. Additionally, if the first <code>#version</code>
+
<p>As previously mentioned the <code>#version</code> directive can be used to switch back and forth between the defaults as long as no explicit <code>#default</code> directive statement is specified. However, as soon as the first <code>#default</code> directive is encountered, any subsequent <code>#version</code> directives that would normally affect the defaults will instead just generate a warning.</p>
appears after any other declaration, or a <code>#version</code> directive does not appear at all,
+
 
a post-parse warning is issued, and a {{Change}} as of POV-Ray 3.8 or later it is now considered an outright error to use
+
<p>Consider the following examples:</p>
<code>#version 3.8</code> or higher in a main scene file that does not start with a <code>#version</code> directive.</p>
+
 
 +
<pre>
 +
  #version 3.7;
 +
  #declare LegacyTexture = texture { ... }
 +
</pre>
 +
 
 +
<p>The <code>#version</code> directive switches to the version 3.7 defaults. If <em>LegacyTexture</em> does not explicitly specify an ambient value it will be set to a value of 0.1</p>
 +
 
 +
<pre>
 +
  #version 3.8;
 +
  #declare ModernTexture = texture { ... }
 +
  #default { pigment { color rgb <1,0,0> } }
 +
</pre>
 +
 
 +
<p>The <code>#version</code> directive switches to the version 3.8 defaults. If <em>ModernTexture</em> does not explicitly specify an ambient value, it will be set to a value of zero.</p>
  
<p>If you do need to do some processing before you decide on a version compatibility option, start your scene with the following
 
construct:</p>
 
 
<pre>
 
<pre>
   #version version;
+
   #version 3.7;
 +
  #declare OtherTexture = texture { ... }
 
</pre>
 
</pre>
Note that unless the version compatibility option has explicitly been set by the INI file option <code>Version=</code><em>n.n</em>
 
or by the <code>+MV</code><em>n.n</em> command-line switch, <code>version</code> evaluates to the actual POV-Ray software version
 
when used inside the first <code>#version</code> statement, even in version 3.8 or later where it evaluates to the effective
 
version compatibility option anywhere else.
 
  
<p class="Warning"><strong>Warning:</strong> The version directive and command-line setting no longer provide compatibility with most rendering bugs in versions prior to POV-Ray 3.5. However, compatibility with the scene language is provided for scenes as old as POV-Ray 1.0 just as in all previous versions of POV-Ray. Nevertheless, we strongly recommend you update scenes at least to POV-Ray 3.7 syntax if you plan to use them in future versions of POV-Ray.</p>
+
<p>The <code>#version</code> directive just generates a warning because the earlier <code>#default</code> directive has <em>locked</em> the version 3.8 defaults overriding the pigment in the process. If <em>OtherTexture</em> does not explicitly specify an ambient value, it will also have an ambient value of zero.</p>
 +
 
 +
<p class="Note"><strong>Note:</strong> The version directive and command-line setting no longer provides compatibility with most rendering bugs in versions prior to POV-Ray 3.5. However, compatibility with the scene language is provided for scenes as old as POV-Ray 1.0 just as in all previous versions of POV-Ray. Nevertheless, we strongly recommend you update scenes at least to POV-Ray 3.7 syntax if you plan to use them in future versions of POV-Ray.</p>

Revision as of 00:04, 1 October 2018

Since POV-Ray has evolved over the years from version 1.0 through 3.8 we have made every effort to maintain some amount of backwards compatibility with earlier versions. Some old or obsolete features can be handled directly without any special consideration by the user. Some old or obsolete features can no longer be handled at all. However some old features can still be used if you alert POV-Ray that this is an older scene. The #version directive can be used to switch version compatibility or change default settings several times throughout a scene file.

The syntax is:

VERSION_DIRECTIVE: 
  #version FLOAT;

There must be a semi-colon after the float expression in a #version directive. If omitted a warning is generated and some macros may not work properly. Additionally you may use the Version=n.n option or the +MVn.n switch to establish the initial setting. For example, the parsing of float expressions was introduced in version 2.0 and it was incompatible with any version 1.0 scene file. Using #version 1.0 turns off expression parsing as well as many warning messages so that nearly all 1.0 files will still work. Some obsolete or re-designed features are totally unavailable in the current version of POV-Ray REGARDLESS OF THE VERSION SETTING. Details on these features are noted throughout this documentation.

As of version 3.7 the following requirement has been implemented. In order to obtain full version 3.7 functionality you MUST specify the #version 3.7; directive in your scene file. Prior to a #version directive appearing the version defaults to 3.62. Additionally, if the first #version directive appears after any other declaration, or a #version directive does not appear at all a post-parse warning is issued. A Change as of POV-Ray 3.8 now makes it an outright error to use #version 3.8; or higher in a main scene file that does not start with a #version directive.

New defaults require that the language version is explicitly set to 3.8 or higher via the #version directive the Version=n.n INI setting or the +MVn.n command-line option. Otherwise POV-Ray will fall back to legacy defaults for backwards compatibility.

If you do need to do some processing before you decide on a version compatibility option start your scene with the following construct:

  #version version;

The built-in float identifier version contains the current setting of the version compatibility option. See Float Expressions: Built-in Variables. Together with the built-in version identifier and the #version directive will allow you to save and restore the previous values of this compatibility setting. The #local identifier option is especially useful here. For example the include file mystuff.inc is in version 3.5 format, so at the top of that file you would include:

  #local Temp_Vers = version;  // Save previous value
  #version 3.5;                // Change to 3.5 mode
    ...                        // Version 3.5 stuff goes here...
  #version Temp_Vers;          // Restore previous version

Note: In version 3.7, if the version compatibility option was left at its default, the version identifier evaluated to the actual POV-Ray version number, instead of matching the defaulted version compatibility setting of 3.62. This would cause problems with include files using the above construct, as it would inadvertently switch the compatibility setting from 3.62 to 3.7. This has been fixed by a Change in version 3.8, where the version identifier matches the version compatibility option default in such a situation. There is still one exception to this rule: If the scene starts with a #version directive, and the version identifier is used in that directive, it will default to the actual POV-Ray version number in that very first statement, so that the #version version; idiom can still be used.

As previously mentioned the #version directive can be used to switch back and forth between the defaults as long as no explicit #default directive statement is specified. However, as soon as the first #default directive is encountered, any subsequent #version directives that would normally affect the defaults will instead just generate a warning.

Consider the following examples:

  #version 3.7;
  #declare LegacyTexture = texture { ... }

The #version directive switches to the version 3.7 defaults. If LegacyTexture does not explicitly specify an ambient value it will be set to a value of 0.1

  #version 3.8;
  #declare ModernTexture = texture { ... }
  #default { pigment { color rgb <1,0,0> } }

The #version directive switches to the version 3.8 defaults. If ModernTexture does not explicitly specify an ambient value, it will be set to a value of zero.

  #version 3.7;
  #declare OtherTexture = texture { ... }

The #version directive just generates a warning because the earlier #default directive has locked the version 3.8 defaults overriding the pigment in the process. If OtherTexture does not explicitly specify an ambient value, it will also have an ambient value of zero.

Note: The version directive and command-line setting no longer provides compatibility with most rendering bugs in versions prior to POV-Ray 3.5. However, compatibility with the scene language is provided for scenes as old as POV-Ray 1.0 just as in all previous versions of POV-Ray. Nevertheless, we strongly recommend you update scenes at least to POV-Ray 3.7 syntax if you plan to use them in future versions of POV-Ray.