Reference Section 8Documentation
From POV-Wiki
|
This document is protected, so submissions, corrections and discussions should be held on this documents talk page. |
Contents |
Quick Reference
This is a consolidation of the entire syntax for the POV-Ray's Scene Description Language. Note that the syntax conventions used here are slightly different than those used in the user documentation.
The following syntax conventions are used:
ITEM- An item not in brackets indicates that it is a required item.
[ITEM]- Brackets surround an optional item. If brackets are part of the item, that is noted where applicable.
ITEM...- An ellipsis indicates an item that may be used one or more times.
[ITEM...]- An ellipsis within brackets indicates an item that may be used zero or more times.
ITEM ITEM- Two or more juxtaposed items indicates that they should be used in the given order.
ITEM | ITEM- A pipe separates two or more alternatives from which only one item should be used.
ITEM & ITEM- An ampersand separates two or more items that may be used in any order.
Juxtaposition has precedence over the pipe or ampersand. In the following example, you would select one of the keyword and vector pairs. For that last pair, the keyword itself is optional.
rgb 3D_VECTOR | rgbf 4D_VECTOR | rgbt 4D_VECTOR | [rgbft] 5D_VECTOR
Some item names are simply descriptive in nature. An indication of the item's type is given by a prefix on the item name, as follows:
F_- A FLOAT item
I_- An INT item
V_- A VECTOR item
V4_- A 4-D VECTOR item
Note: This document provides only the syntax of the Scene Description Language (SDL). The intent is to provide a single reference for all statements and keywords. It does not provide definitions for the numerous keywords nor explain their usage.
Quick Reference Contents
The Scene
- Describe a POV-Ray scene:
- SCENE:
SCENE_ITEM...- SCENE_ITEM:
LANGUAGE_DIRECTIVE | CAMERA | LIGHT | OBJECT | ATMOSPHERIC_EFFECT | GLOBAL_SETTINGS
Language Basics
Floats
- Float Expressions
- FLOAT:
NUMERIC_TERM [SIGN NUMERIC_TERM]...- SIGN:
+ | -- NUMERIC_TERM:
NUMERIC_FACTOR [MULT NUMERIC_FACTOR]...- MULT:
* | /- NUMERIC_FACTOR:
FLOAT_LITERAL | FLOAT_IDENTIFIER | SIGN NUMERIC_FACTOR | FLOAT_FUNCTION | FLOAT_BUILT_IN_IDENT | ( FULL_EXPRESSION ) | ! NUMERIC_FACTOR | VECTOR_FACTOR DECIMAL_POINT DOT_ITEM | FLOAT_FUNCTION_INVOCATION- FLOAT_LITERAL:
MANTISSA [EXP [SIGN] DIGIT...]- MANTISSA:
DIGIT... [DECIMAL_POINT [DIGIT...]] | DECIMAL_POINT DIGIT...- DIGIT:
0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9- DECIMAL_POINT:
.- EXP:
e | E- FLOAT_FUNCTION:
abs (FLOAT) | acos (FLOAT) | acosh (FLOAT) | asc (STRING) | asin (FLOAT) | asinh (FLOAT) | atan (FLOAT) | atanh (FLOAT) | atan2 (FLOAT,FLOAT) | ceil (FLOAT) | cos (FLOAT) | cosh (FLOAT) | defined (IDENTIFIER) | degrees (FLOAT) | dimensions (ARRAY_IDENTIFIER) | dimension_size (ARRAY_IDENTIFIER,INT) | div (FLOAT,FLOAT) | exp (FLOAT) | file_exists (STRING) | floor (FLOAT) | int (FLOAT) | inside (SOLID_OBJECT_IDENT, VECTOR) | ln (FLOAT) | log (FLOAT) | max (FLOAT,FLOAT[,FLOAT]...) | min (FLOAT,FLOAT[,FLOAT]...) | mod (FLOAT,FLOAT) | pow (FLOAT,FLOAT) | radians (FLOAT) | rand (FLOAT) | seed (FLOAT) | select (FLOAT,FLOAT,FLOAT,[FLOAT]) | sin (FLOAT) | sinh (FLOAT) | sqrt (FLOAT) | strcmp (STRING,STRING) | strlen (STRING) | tan (FLOAT) | tanh (FLOAT) | val (STRING) | vdot (VECTOR,VECTOR) | vlength (VECTOR)- FLOAT_BUILT_IN_IDENT:
BOOLEAN_KEYWORD | clock | clock_delta | clock_on | final_clock | final_frame | frame_number | image_height | image_width | initial_clock | initial_frame | pi | version- BOOLEAN_KEYWORD:
true | yes | on | false | no | off- FULL_EXPRESSION:
FLOAT | LOGICAL_EXPRESSION [? FULL_EXPRESSION : FULL_EXPRESSION]- LOGICAL_EXPRESSION:
REL_TERM [LOGICAL_OPERATOR REL_TERM]...- LOGICAL_OPERATOR:
& | |- REL_TERM:
FLOAT [REL_OPERATOR FLOAT]... | STRING REL_OPERATOR STRING- REL_OPERATOR:
< | <= | = | >= | > | !=- DOT_ITEM:
x | y | z | t | u | v | red | green | blue | filter | transmit | gray- INT:
FLOAT- Any fractional part is discarded.
- BOOL:
BOOLEAN_KEYWORD | LOGICAL_EXPRESSION
Vectors
- Vector Expressions
- VECTOR:
VECTOR_TERM [SIGN VECTOR_TERM]...- VECTOR_TERM:
VECTOR_FACTOR [MULT VECTOR_FACTOR]...- VECTOR_FACTOR:
VECTOR_LITERAL | VECTOR_IDENTIFIER | SIGN VECTOR_FACTOR | VECTOR_FUNCTION | VECTOR_BUILT_IN_IDENT | ( VECTOR_FULL_EXPRESSION ) | ! VECTOR_FACTOR | FLOAT_FACTOR | VECTOR_FUNCTION_INVOCATION | COLOR_FUNCTION_INVOCATION | SPLINE_INVOCATION- VECTOR_LITERAL:
< FLOAT, FLOAT [, FLOAT [, FLOAT [, FLOAT ]]] >- VECTOR_FUNCTION:
min_extent (OBJECT_IDENTIFIER) | max_extent (OBJECT_IDENTIFIER) | trace (OBJECT_IDENTIFIER,VECTOR,VECTOR[,VECTOR_IDENTIFIER]) | vaxis_rotate (VECTOR,VECTOR,FLOAT) | vcross (VECTOR,VECTOR) | vrotate (VECTOR,VECTOR) | vnormalize (VECTOR) | vturbulence (FLOAT,FLOAT,FLOAT,VECTOR)- VECTOR_BUILT_IN_IDENT:
x | y | z | t | u | v- VECTOR_FULL_EXPRESSION:
VECTOR | LOGICAL_EXPRESSION ? VECTOR_FULL_EXPRESSION : VECTOR_FULL_EXPRESSION
Colors
- Color Expressions
- COLOR:
[color] COLOR_BODY | colour COLOR_BODY- COLOR_BODY:
COLOR_VECTOR | COLOR_KEYWORD_GROUP | COLOR_IDENTIFIER- COLOR_VECTOR:
rgb 3D_VECTOR | rgbf 4D_VECTOR | rgbt 4D_VECTOR | [rgbft] 5D_VECTOR | srgb 3D_VECTOR | srgbf 4D_VECTOR | srgbt 4D_VECTOR | srgbft 5D_VECTOR- COLOR_KEYWORD_GROUP:
[COLOR_IDENTIFIER] COLOR_KEYWORD_ITEMS- COLOR_KEYWORD_ITEMS:
[red FLOAT] & [green FLOAT] & [blue FLOAT] & [filter FLOAT] & [transmit FLOAT]
User defined Functions
- User-Defined Functions
- USER_FUNCTION:
FLOAT_USER_FUNCTION | VECTOR_USER_FUNCTION | COLOR_USER_FUNCTION- FLOAT_USER_FUNCTION:
function { FN_FLOAT } | function (IDENT_LIST) { FN_FLOAT } | function { pattern { PATTERN [PATTERN_MODIFIERS]} }- IDENT_LIST:
IDENT_ITEM [, IDENT_LIST]- The maximum number of parameter identifiers is 56. An identifier may not be repeated in the list.
- IDENT_ITEM:
x | y | z | u | v | PARAM_IDENTIFIER- PATTERN:
MAP_PATTERN | brick [BRICK_ITEM] | checker | hexagon | object { LIST_OBJECT }- VECTOR_USER_FUNCTION:
function { SPECIAL_VECTOR_FUNCTION }- SPECIAL_VECTOR_FUNCTION:
TRANSFORM | SPLINE- COLOR_USER_FUNCTION:
function { PIGMENT }
- Specify a float expression in a user-defined function:
- FN_FLOAT
LOGIC_AND [OR LOGIC_AND]- OR:
|- LOGIC_AND:
REL_TERM [AND REL_TERM]- AND:
&- REL_TERM:
TERM [REL_OPERATOR TERM]- REL_OPERATOR:
< | <= | = | >= | > | !=- TERM:
FACTOR [SIGN FACTOR]- SIGN:
+ | -- FACTOR:
EXPRESSION [MULT EXPRESSION]- MULT:
* | /- EXPRESSION:
FLOAT_LITERAL | FLOAT_IDENTIFIER | FN_FLOAT_FUNCTION | FLOAT_BUILT_IN_IDENT | ( FN_FLOAT ) | IDENT_ITEM | SIGN EXPRESSION | VECTOR_FUNCTION_INVOCATION.FN_DOT_ITEM | COLOR_FUNCTION_INVOCATION.FN_DOT_ITEM | FLOAT_FUNCTION_INVOCATION- FN_DOT_ITEM:
DOT_ITEM | hf- FN_FLOAT_FUNCTION:
abs (FN_FLOAT) | acos (FN_FLOAT) | acosh (FN_FLOAT) | asin (FN_FLOAT) | asinh (FN_FLOAT) | atan (FN_FLOAT) | atanh (FN_FLOAT) | atan2 (FN_FLOAT,FN_FLOAT) | ceil (FN_FLOAT) | cos (FN_FLOAT) | cosh (FN_FLOAT) | degrees (FN_FLOAT) | exp (FN_FLOAT) | floor (FN_FLOAT) | int (FN_FLOAT) | ln (FN_FLOAT) | log (FN_FLOAT) | max (FN_FLOAT,FN_FLOAT[,FN_FLOAT]...) | min (FN_FLOAT,FN_FLOAT[,FN_FLOAT]...) | mod (FN_FLOAT,FN_FLOAT) | pow (FN_FLOAT,FN_FLOAT) | prod (IDENTIFIER, FN_FLOAT, FN_FLOAT, FN_FLOAT) | radians (FN_FLOAT) | sin (FN_FLOAT) | sinh (FN_FLOAT) | sqrt (FN_FLOAT) | sum (IDENTIFIER, FN_FLOAT, FN_FLOAT, FN_FLOAT) |tan (FN_FLOAT) | tanh (FN_FLOAT) | select (FN_FLOAT,FN_FLOAT,FN_FLOAT [,FN_FLOAT])
- Create an identifier for a user-defined function:
- USER_FUNCTION_DECLARATION:
#declare FLOAT_FUNCTION_IDENTIFIER = FLOAT_USER_FUNCTION |
#local FLOAT_FUNCTION_IDENTIFIER = FLOAT_USER_FUNCTION |
#declare VECTOR_FUNCTION_IDENTIFIER = VECTOR_USER_FUNCTION |
#local VECTOR_FUNCTION_IDENTIFIER = VECTOR_USER_FUNCTION |
#declare COLOR_FUNCTION_IDENTIFIER = COLOR_USER_FUNCTION |
#local COLOR_FUNCTION_IDENTIFIER = COLOR_USER_FUNCTION
- Reference a user-defined function:
- FLOAT_FUNCTION_INVOCATION:
FLOAT_FUNCTION_IDENTIFIER (FN_PARAM_LIST)- VECTOR_FUNCTION_INVOCATION:
VECTOR_FUNCTION_IDENTIFIER (FN_PARAM_LIST)- COLOR_FUNCTION_INVOCATION:
COLOR_FUNCTION_IDENTIFIER (FN_PARAM_LIST)- FN_PARAM_LIST:
FN_PARAM_ITEM [, FN_PARAM_LIST]- FN_PARAM_ITEM:
x | y | z | u | v | FLOAT
Strings
- String Expressions
- STRING:
STRING_FUNCTION | STRING_IDENTIFIER | STRING_LITERAL- STRING_FUNCTION:
chr (INT) | concat (STRING,STRING[,STRING]...) | str (FLOAT,INT,INT) | strlwr (STRING) | strupr (STRING) | substr (STRING,INT,INT) | vstr (INT,VECTOR,STRING,INT,INT)- STRING_LITERAL:
QUOTE [CHARACTER...] QUOTE- Limited to 256 characters.
- QUOTE:
"- CHARACTER:
- Any ASCII or Unicode character, depending on the charset setting in global_settings.
The following escape sequences might be useful when writing to files or message streams:
\a- alarm
\b- backspace
\f- form feed
\n- new line
\r- carriage return
\t- horizontal tab
\uNNNN- unicode character four-digit code
\v- vertical tab
\\- backslash
\'- single quote
\"- double quote
- STRING_REL_TERM:
STRING_LITERAL [STRING_REL_OPERATOR STRING_LITERAL]...- STRING_REL_OPERATOR:
< | <= | = | >= | > | !=
Arrays
- Define an array:
- ARRAY_DECLARATION:
#declare ARRAY_IDENTIFIER = array DIMENSION... [ARRAY_INITIALIZER] |
#local ARRAY_IDENTIFIER = array DIMENSION... [ARRAY_INITIALIZER]- Limited to five dimensions.
- DIMENSION:
[ INT ]- The brackets here are part of the dimension specification. The integer must be greater than zero.
- ARRAY_INITIALIZER:
{ ARRAY_INITIALIZER [, ARRAY_INITIALIZER]... } |
{ RVALUE [, RVALUE]... }
- Place a value into an array:
- ARRAY_ELEMENT_ASSIGNMENT:
#declare ARRAY_REFERENCE = RVALUE [;] |
#local ARRAY_REFERENCE = RVALUE [;]- The semicolon is required for a FLOAT, VECTOR or COLOR assignment.
- Reference an array:
- ARRAY_REFERENCE:
ARRAY_IDENTIFIER ELEMENT...- ELEMENT:
[ INT ]- The brackets here are part of the element specification.
Splines
- Define a spline:
- SPLINE:
spline { SPLINE_ITEMS }- SPLINE_ITEMS
[SPLINE_TYPE] PATH_LIST | SPLINE_IDENTIFIER [SPLINE_TYPE][PATH_LIST]- SPLINE_TYPE:
linear_spline | quadratic_spline | cubic_spline | natural_spline- PATH_LIST:
FLOAT, VECTOR [[,] PATH_LIST]
- Reference a spline:
- SPLINE_INVOCATION:
SPLINE_IDENTIFIER ( FLOAT [, SPLINE_TYPE] )
Language Directives
- Control the parsing of sections of the scene file:
- LANGUAGE_DIRECTIVE:
INCLUDE_DIRECTIVE | IDENTIFIER_DECLARATION | UNDEF_DIRECTIVE | FOPEN_DIRECTIVE | FCLOSE_DIRECTIVE | READ_DIRECTIVE | WRITE_DIRECTIVE | DEFAULT_DIRECTIVE | VERSION_DIRECTIVE | IF_DIRECTIVE | IFDEF_DIRECTIVE | IFNDEF_DIRECTIVE | SWITCH_DIRECTIVE | WHILE_DIRECTIVE | FOR_DIRECTIVE | TEXT_STREAM_DIRECTIVE | MACRO_DEFINITION
File Inclusion
- Insert content of another scene file:
- INCLUDE_DIRECTIVE:
#include FILE_NAME- File inclusion may be nested at most 10 levels deep.
- FILE_NAME:
STRING
Identifier Declaration
- Create an identifier for a value, object, etc.
- IDENTIFIER_DECLARATION:
#declare [deprecated] IDENTIFIER = RVALUE [;] |
#local [deprecated] IDENTIFIER = RVALUE [;]- Up to 127 characters, starting with a letter, consisting of letters, digits and/or the underscore. The semicolon is required for a FLOAT, VECTOR or COLOR declaration.
- RVALUE:
FLOAT | VECTOR | COLOR | USER_FUNCTION | STRING | ARRAY_REFERENCE | SPLINE | TRANSFORM | CAMERA | LIGHT | OBJECT | MATERIAL | INTERIOR | TEXTURE | TEXTURE_MAP | PIGMENT | COLOR_MAP | PIGMENT_MAP | NORMAL | SLOPE_MAP | NORMAL_MAP | FINISH | MEDIA | DENSITY | DENSITY_MAP | FOG | RAINBOW | SKY_SPHERE
- Destroy an identifier:
- UNDEF_DIRECTIVE:
#undef IDENTIFIER
| image files (*.png, *.pot, *.df3) | File Input/Output |
|
This document is protected, so submissions, corrections and discussions should be held on this documents talk page. |
