Reference Talk:Version Directive

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.