Descriptions and Examples for the POV-Ray Raytracer by Friedrich A. Lohmüller
    About Variables in POV-Ray
 Deutsch Deutsch
Home
- POV-Ray Tutorial

  - POV-Ray Details

  - About Variables
      Built-in Identifiers
  > #declare, #local
      Expressions

  - A short
    Include File Tutorial


                                       

#declare and #local
User defined Identifiers and Objects
How to define our own variables and objects.

In the scenery description language (SDL) of POV-Ray there are existing
two methods to define our own variables and objects: #declare or #local.
Note: To avoid any collision with built-in identifiers and reserved words in POV-Ray,
it's strongly recommanded to use only words beginning with capital letters
for identifiers of variables declared by the user.

What can we declare by #declare or #local?
Some examples:

Numbers, floats, vectors
#declare End = 5;     //
#local D = 0.35;    // distance between ... and ...
#declare Column_Height = 3.50; // height of a column
#declare StartPoint = <0, 2.5, 0.5*sqrt(3)>   // start point
#local Angle_1 = degrees( atan ( 2.5 / sqrt(2)); // angle value in degrees

Textures and materials, pigment, color, finish, normal.
#declare My_Orange =  color rgb <1,0.6,0>;
#declare Orange_Plastic =
texture{ pigment{ My_Orange }
         finish { phong 1 reflection{ 0.1 metallic 0.1} }
       } // end of texture
Geometrcal Objects.
#declare Column_01 = cone{ <0,0,0>,0.30,<0,4.00,0>, 0.25
                           texture{ Orange_Plastic }
                         } // end of Column_01
Note:
- All #declare or #local of a float, vector or color require semicolon at the end.
- Declaring an identifier again overwrites the previous value.



- Why is it so helpfull to declare variables instead of using only floats?
Arguments:
Easier handling, because less to write!
It's basic for modular working! Who use it is more sucessful!
- Better Overview! (Don't forget to add some explaining comments!)
[Sure! You remember also 8 weeks later the meaning of 'A', ... but, they all say that! :-) ]

What should we '#declare'?
- Values, which were used at many statement - for easier change/adapting - that gives more indepency in design.
If we want to changes a value, which is needed several times in a scene, we need only to change it at one place!
(faster + less error sources!)
Example: Height of a column, textures, ...

- Textures, before using them in an object.
- Why is it so helpfull to declare textures before using them at an object?
- Try to declare all textures used in a scene somewhere before the objects.
Doing so allows us very easily to change some textures later.

- Creation of new objects for multible use in a scene
  Erzeugung von neuen Objekten für mehrfachen Gebrauch in einer Szene
Why is it so helpfull to declare objects which are used several times?
Arguments:
- less to write, specially by changing an object!
- prefabricated objects allow modulare working which is much clearer than many multiple descriptions of parts.


'#declare' or '#local'? - The difference between '#declare' and #local'.
Local identifiers are important to avoid Identifier Name Collisions.
Inside of an include file or inside of a macro (between the word '#macro' and the according '#end') declaring an identifier by #local has no effect on identifiers of the same name declared outside of this include file or macro. That means it temporary overrides an outside identifier of the same name without destroying it's value outside. After the inclusion of the include file or after the end of the macro all there declared local identifiers are destroyed. A '#local' used in the main scene file is identical to #declare (if it's not in an include file or macro).
As a result: We can use in a macro or in an include file the identifier names that are already used in the main scene file or in other macros or include files without destroying the according identifier values in the main scene file.
Destroying Identifiers
User defined identifiers can be destroyed with "#undef MyVariable" .
User defined identifiers can be created dependent on if they were not defined:
"#ifndef ( MyVariable ) #declare MyVariable = 0.5; #end"
This is an elegant method to create objects in include files with default values,
which can be overwritten by the user, if its necessary.
See also Check for Existence


top
© Friedrich A. Lohmüller, 2011
www.f-lohmueller.de