Descriptions and Examples for the POV-Ray Raytracer by Friedrich A. Lohmüller
    Include files with POV-Ray
How they work and How to make your own include files
Deutsch Deutsch

Home
- POV-Ray Tutorial

  - POV-Ray Details

  - About Variables

  - A Short
    Include File Tutorial
      Why Include Files?
      Self-made Include Files
          and how to call them.
      Special Notations, ".inc"
          "#local / #declare"
      Where to store
    >Design of Include Files
      Adding a new item
        to the 'Insert Menu'

                                                       

The Design of Self-made Include Files.

For the design of 'good' include files we take a look on the way how POV-Ray standard include files are designed:
// POV-Ray 3.6/3.7 sample include file "NAME.inc"
// author, date:
//---------------------------------------------------------
#ifndef( NAME_Inc_Temp)
#declare NAME_Inc_Temp = version;
#version 3.6;
//---------------------------------------------------------
    // .... your include file content
//---------------------------------------------------------
#version NAME_Inc_Temp;
#end
//------------------------------------- end of include file
This method garanties 2 things at once:
1. It avoids the unnecessary reloading of an already readed include file.
2. It changes POV-Ray to work with mode '#version 3.6;' during parsing the content of the include file and changes back to the version which the calling scenen file uses.

  For an include file named 'NAME.inc' we declare a global variable named 'NAME_Inc_Temp' which contains the POV-Ray version used by the calling POV-Ray scene file.
  If this variable is declared, than the include file was loaded somewhere before and will not be loaded again. So unnecessary loading actions are avoided. This version can be restored at the end.
  POV-Ray can change between the mode of a current version (like 3.6 or 3.7) by '#version 3.6;' and change back to older modes (like 3.5 or 3.6) for a part of the text by '#version 3.7;'.
This allows some (not a total) backward compatibility to the syntax of older versions.
Here the conditional statement '#ifndef (VARIABLE) /*Do read the include file in mode*/ #end' is used to store the currend version mode, change the mode to 3.6 for this content and restore the current mode at the end.


Make sure that all necessary standard include files are loaded:
Another good idea is to make sure that all necessary standard include files which this include file uses (i.e. color.inc, textures.inc, shapes.inc, shapes.inc etc.) are loaded also if the calling scene does not load these include files (red part):
// POV-Ray 3.6/3.7 sample include file "NAME.inc"
// author, date:
// What's that: ...
//---------------------------------------------------------
#ifndef( NAME_Inc_Temp)
#declare NAME_Inc_Temp = version;
#version 3.6;
//---------------------------------------------------------
#ifndef(  Colors_Inc_Temp)
#include "colors.inc"
#end
#ifndef(  Textures_Inc_Temp)
#include "textures.inc"
#end
#ifndef(  Shapes_Inc_Temp)
#include "shapes.inc"
#end
#ifndef(  Shapes2_Inc_Temp)
#include "shapes2.inc"
#end
//---------------------------------------------------------

    // .... your include file content

//---------------------------------------------------------
#version NAME_Inc_Temp;
#end
//------------------------------------- end of include file

Add Comment about the sense and an Example for usage: Besides of these basics it's recommanded to add comments with a good description about what this include file makes as well as an example of how to call it from a scene file!


....
top

© Friedrich A. Lohmüller, 2011
http://www.f-lohmueller.de