Difference between revisions of "Reference:Version Directive"
Jholsenback (talk | contribs) m (1 revision: Reference Migration Initial Load) |
(Removed description of v3.8 behavior (error on late `#version 3.8` statement) that will be rolled back and not be present in v3.8.0 proper.) |
||
(9 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
[[Category:Language Directives]] | [[Category:Language Directives]] | ||
{{#indexentry:Directives, language, #version}} | {{#indexentry:Directives, language, #version}} | ||
− | {{#indexentry:#version | + | {{#indexentry:#version}} |
− | <p> | + | {{#indexentry:version}} |
− | used if you | + | <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> |
+ | |||
+ | <p>The syntax is:</p> | ||
+ | |||
<pre> | <pre> | ||
VERSION_DIRECTIVE: | VERSION_DIRECTIVE: | ||
#version FLOAT; | #version FLOAT; | ||
</pre> | </pre> | ||
− | <p | + | |
− | properly. | + | <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>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.</p> | |
− | <p>The built-in float identifier <code>version</code> contains the current setting of the version compatibility option. See | + | |
− | Float Expressions: [[ | + | <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> | ||
+ | #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 | ||
+ | </pre> | ||
+ | |||
+ | <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> | ||
+ | |||
+ | <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> | ||
+ | |||
+ | <p>Consider the following examples in their entirety:</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> | ||
+ | |||
<pre> | <pre> | ||
− | # | + | #version 3.7; |
− | # | + | #declare OtherTexture = texture { ... } |
− | |||
− | |||
</pre> | </pre> | ||
− | <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=" | + | <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> |
Latest revision as of 11:58, 21 June 2021
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 +MV
n.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.
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 +MV
n.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 in their entirety:
#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.