Previous page Next page

Array Identifiers

New in POV-Ray 3.1 you may now declare arrays of identifiers of up to five dimensions. Any item that can be declared as an identifier can be declared in an array.

Declaring Arrays

The syntax for declaring an array is as follows:

STRING_DECLARATION:
#declare IDENTIFIER = array[ INT ][ [ INT ] ]...[ARRAY_INITIALIZER] |
#local IDENTIFIER = array[ INT ][ [ INT ] ]...[ARRAY_INITIALIZER]
ARRAY_INITIALIZER:
{ARRAY_ITEM, [ARRAY_ITEM, ]... }
ARRAY_ITEM:
RVALUE |
ARRAY_INITIALIZER

Where IDENTIFIER is the name of the identifier up to 40 characters long and INT is a valid float expression which is internally truncated to an integer which specifies the size of the array. The optional ARRAY_INITIALIZER is discussed in the next section "Array Initalizers". Here is an example of a one-dimensional, uninitalized array.

 #declare MyArray = array[10]

This declares an uninitalized array of ten elements. The elements are referenced as MyArray[0] through MyArray[9]. As yet, the type of the elements are undetermined. Once you have initialized any element of the array, all other elements can only be defined as that type. An attempt to reference an uninitalized element results in an error. For example:

 #declare MyArray = array[10];

 #declare MyArray[5] = pigment{White}  //all other elements must be

                     //pigments too.

 #declare MyArray[2] = normal{bumps 0.2} //generates an error

 #declare Thing = MyArray[4] //error: uninitalized array element

Multi-dimensional arrays up to five dimensions may be declared. For example:

 #declare MyGrid = array[4][5]

declares a 20 element array of 4 rows and 5 columns. Elements are referenced from MyGrid[0][0] to MyGrid[3][4]. Although it is permissible to reference an entire array as a whole, you may not reference just one dimension of a multi-dimensional array. For example:

 #declare MyArray = array[10]

 #declare MyGrid = array[4][5]

 #declare YourArray = MyArray  //this is ok

 #declare YourGrid = MyGrid   //so is this

 #declare OneRow  = MyGrid[2] //this is illegal

Large uninitalized arrays do not take much memory. Internally they are arrays of pointers so they probably use just 4 bytes per element. Once initialized with values, they consume memory depending on what you put in them.

The rules for local vs global arrays are the same as any other identifier. Note that this applies to the entire array. You cannot mix local and global elements in the same array. See "#declare vs. #local" for information on identifier scope.

Array Initalizers

Because it is cumbersome to individually initialize the elements of an array, you may initialize it as it is created using array initializer syntax. For example:

 #include "colors.inc"

 #declare FlagColors = array[3] {Red,White,Blue}

Multi-dimensional arrays may also be initialized this way. For example:

 #declare Digits =

 array[4][10]

 {

  {7,6,7,0,2,1,6,5,5,0},

  {1,2,3,4,5,6,7,8,9,0},

  {0,9,8,7,6,5,4,3,2,1},

  {1,1,2,2,3,3,4,4,5,5}

 }

The commas are required between elements and between dimensions as shown in the example.

Previous page Next page