Reference Section 8.1Documentation

This document is protected, so submissions, corrections and discussions should be held on this documents talk page.

Language Directives

File Input/Output

Open a text file:

FOPEN_DIRECTIVE:

#fopen FILE_HANDLE_IDENTIFIER FILE_NAME OPEN_TYPE

OPEN_TYPE:

read | write | append

Close a text file:

FCLOSE_DIRECTIVE:

#fclose FILE_HANDLE_IDENTIFIER

Read string, float and/or vector values from a text file:

READ_DIRECTIVE:

#read ( FILE_HANDLE_IDENTIFIER, DATA_IDENTIFIER [, DATA_IDENTIFIER]... )

Use defined (FILE_HANDLE_IDENTIFIER) to detect end-of-file after a read.

DATA_IDENTIFIER:

UNDECLARED_IDENTIFIER | FLOAT_IDENTIFIER | VECTOR_IDENTIFIER | STRING_IDENTIFIER | ARRAY_REFERENCE

May read a value into an array reference if the array element's type has already been established.

Write string, float and/or vector values to a file:

WRITE_DIRECTIVE:

#write ( FILE_HANDLE_IDENTIFIER, [BINARY_WORD_TYPE,] DATA_ITEM [, DATA_ITEM]... )

BINARY_WORD_TYPE:

uint8 | sint8 | uint16be | uint16le | sint16be | sint16le | sint32be | sint32le

DATA_ITEM:

FLOAT | VECTOR | STRING

Quick Reference Contents

Default Texture

Specify a default texture, pigment, normal or finish:

DEFAULT_DIRECTIVE:

#default { DEFAULT_ITEM }

DEFAULT_ITEM:

PLAIN_TEXTURE | PIGMENT | NORMAL | FINISH

Quick Reference Contents

Version Identifier

Specify the POV-Ray compatibility version number:

VERSION_DIRECTIVE:

#version FLOAT;

Quick Reference Contents

Control Flow Directives

Conditionally parse a section of the scene file, depending on a boolean expression:

IF_DIRECTIVE:

#if ( BOOL ) TOKENS [#elseif ( BOOL ) TOKENS] [#else TOKENS] #end

TOKENS:

Any number of POV-Ray keywords, identifiers, values and/or punctuation.

Conditionally parse a section of the scene file, depending on the existence of an identifier:

IFDEF_DIRECTIVE:

#ifdef ( IDENTIFIER ) TOKENS [#elseif ( IDENTIFER ) TOKENS] [#else TOKENS] #end

IFNDEF_DIRECTIVE:

#ifndef ( IDENTIFIER ) TOKENS [#elseif ( IDENTIFER ) TOKENS] [#else TOKENS] #end

Conditionally parse a section of the scene file, depending on the value of a float expression:

SWITCH_DIRECTIVE:

#switch ( FLOAT ) SWITCH_CLAUSE... [#else TOKENS] #end

SWITCH_CLAUSE:

#case ( FLOAT ) TOKENS [#break] |
#range ( F_LOW, F_HIGH ) TOKENS [#break]

Repeat a section of the scene file while a boolean condition is true:

WHILE_DIRECTIVE:

#while ( LOGICAL_EXPRESSION ) TOKENS [#break] #end

Increment an Identifier from Start to End (inclusive) with the given Step size:

FOR_DIRECTIVE:

#for (Identifier, Start, End [, Step]) TOKENS [#break] #end

Quick Reference Contents

Message Streams

Send a message to a text stream:

TEXT_STREAM_DIRECTIVE:

#debug STRING | #error STRING | #warning STRING

Quick Reference Contents

Macro

Define a macro:

MACRO_DEFINITION:

#macro MACRO_IDENTIFIER ( [PARAM_IDENTIFIER [, PARAM_IDENTIFIER]...] ) TOKENS [#break] #end

A parameter identifier may not be repeated in the list.

Invoke a macro:

MACRO_INVOCATION:

MACRO_IDENTIFIER ( [ACTUAL_PARAM [, ACTUAL_PARAM]...] )

ACTUAL_PARAM:

IDENTIFIER | RVALUE

Quick Reference Contents

Embedded Directives

Some directives may be embedded in CAMERA, LIGHT, OBJECT and ATMOSPHERIC_EFFECT statements. However, the directives should only include items (if any) that are valid for a given statement. Also, they should not disrupt the required order of items, where applicable.

EMBEDDED_DIRECTIVE:

IDENTIFIER_DECLARATION | UNDEF_DIRECTIVE | READ_DIRECTIVE | WRITE_DIRECTIVE | IF_DIRECTIVE | IFDEF_DIRECTIVE | IFNDEF_DIRECTIVE | SWITCH_DIRECTIVE | WHILE_DIRECTIVE | TEXT_STREAM_DIRECTIVE

Quick Reference Contents

Transformations

Rotate, resize, move, or otherwise manipulate the coordinates of an object or texture

TRANSFORMATION:

rotate VECTOR | scale VECTOR | translate VECTOR | TRANSFORM | MATRIX

TRANSFORM:

transform TRANSFORM_IDENTIFIER | transform { [TRANSFORM_ITEM...] }

TRANSFORM_ITEM:

TRANSFORM_IDENTIFIER | TRANSFORMATION | inverse

MATRIX:

matrix < F_VAL00, F_VAL01, F_VAL02, F_VAL10, F_VAL11, F_VAL12, F_VAL20, F_VAL21, F_VAL22, F_VAL30, F_VAL31, F_VAL32 >

Quick Reference Contents

Camera

Describe the position, projection type and properties of the camera viewing the scene

CAMERA:

Jump to SDL

camera { [CAMERA_TYPE] [CAMERA_ITEMS] [CAMERA_MODIFIERS] } |

camera { CAMERA_IDENTIFIER [TANSFORMATIONS ...] }

CAMERA_TYPE:

perspective | orthographic | mesh_camera {MESHCAM_MODIFIERS} location direction smooth | fisheye | ultra_wide_angle | omnimax | panoramic | spherical | cylinder CYLINDER_TYPE

CYLINDER_TYPE:

1 | 2 | 3 | 4

CAMERA_ITEMS:

[location VECTOR] & [right VECTOR] & [up VECTOR] & [direction VECTOR] & [sky VECTOR]

CAMERA_MODIFIERS:

[angle [angle F_HORIZONTAL] [,F_VERTICAL]] & [look_at VECTOR] & [FOCAL_BLUR] & [NORMAL] & [TRANSFORMATION...]

FOCAL_BLUR:

aperture FLOAT & blur_samples [MIN_SAMPLES,] MAX_SAMPLES & [focal_point VECTOR] & [confidence FLOAT] & [variance FLOAT] & [bokeh {pigment {BOKEH}}]

MESHCAM_MODIFIERS:

RAYS_PER_PIXEL & DISTRIBUTION_TYPE & [MAX_DISTANCE] & MESH_OBJECT & [MESH_OBJECT...]

RAYS_PER_PIXEL:

FLOAT > 1

DISTRIBUTION_TYPE:

0 | 1 | 2 | 3

MAX_DISTANCE:

FLOAT > EPSILON

MIN_SAMPLES:

INT

MAX_SAMPLES:

INT

BOKEH:

COLOR_VECTOR in the range of <0,0,0> ... <1,1,0>

Quick Reference Contents

Lights

Specify light sources for the scene or for specific objects

LIGHT:

LIGHT_SOURCE | LIGHT_GROUP

Describe the position, type and properties of a light source for the scene:

LIGHT_SOURCE:

Jump to SDL

light_source { V_LOCATION, COLOR [LIGHT_SOURCE_ITEMS] }

LIGHT_SOURCE_ITEMS:

[LIGHT_TYPE] & [AREA_LIGHT_ITEMS] & [LIGHT_MODIFIERS]

LIGHT_TYPE:

spotlight [SPOTLIGHT_ITEMS] | cylinder [SPOTLIGHT_ITEMS]

SPOTLIGHT_ITEMS:

[radius FLOAT] & [falloff FLOAT] & [tightness FLOAT] & [point_at VECTOR]

AREA_LIGHT_ITEMS:

area_light V_AXIS1, V_AXIS2, I_SIZE1, I_SIZE2 [AREA_LIGHT_MODIFIERS]

AREA_LIGHT_MODIFIERS:

[adaptive INT] & [jitter] & [circular] & [orient] & [area_illumination [BOOL]]

LIGHT_MODIFIERS:

[LIGHT_PHOTONS] & [looks_like { OBJECT }] & [TRANSFORMATION...] & [fade_distance FLOAT] &[fade_power FLOAT] & [media_attenuation [BOOL]] & [media_interaction [BOOL]] &[shadowless] & [projected_through { OBJECT_IDENTIFIER }] & [parallel [point_at VECTOR]]

Specify how a light source should interact with photons:

LIGHT_PHOTONS:

photons { LIGHT_PHOTON_ITEMS }

LIGHT_PHOTON_ITEMS:

[refraction BOOL] & [reflection BOOL] & [area_light]

Quick Reference Contents

Lightgroup

Assign objects to specific light sources:

LIGHT_GROUP:

Jump to SDL

light_group { LIGHT_GROUP_ITEM... [LIGHT_GROUP_MODIFIERS] }

LIGHT_GROUP_ITEM:

LIGHT_SOURCE | OBJECT | LIGHT_GROUP

LIGHT_GROUP_MODIFIERS:

[global_lights BOOL] & [TRANSFORMATION...]

Quick Reference Contents

Objects

Describe an object in the scene

OBJECT:

FINITE_SOLID_OBJECT | FINITE_PATCH_OBJECT | INFINITE_SOLID_OBJECT | ISOSURFACE | PARAMETRIC | CSG_OBJECT | OBJECT_STATEMENT

OBJECT_STATEMENT:

object { OBJECT_IDENTIFIER [OBJECT_MODIFIERS] }

Quick Reference Contents

Finite Solid Objects

Describe a solid finite shape:

FINITE_SOLID_OBJECT:

BLOB | BOX | CONE | CYLINDER | HEIGHT_FIELD | ISOSURFACE | JULIA_FRACTAL | LATHE | OVUS | PARAMETRIC | PRISM | SPHERE | SPHERE_SWEEP | SUPERELLIPSOID | SOR | TEXT | TORUS

The blob object:

BLOB:

Jump to SDL

blob { [threshold FLOAT] BLOB_ITEM... [BLOB_MODIFIERS] }

BLOB_ITEM:

sphere { V_CENTER, F_RADIUS, [strength] F_STRENGTH [COMPONENT_MODIFIERS] } |
cylinder { V_END1, V_END2, F_RADIUS, [strength] F_STRENGTH [COMPONENT_MODIFIERS] }

COMPONENT_MODIFIERS:

[TEXTURE] & [PIGMENT] & [NORMAL] & [FINISH] & [TRANSFORMATION...]

BLOB_MODIFIERS:

[hierarchy [BOOL]] & [sturm [BOOL]] & [OBJECT_MODIFIERS]

The box object:

BOX:

Jump to SDL

box { V_CORNER1, V_CORNER2 [BOX_MODIFIERS] }

BOX_MODIFIERS:

[UV_MAPPING] & [OBJECT_MODIFIERS]

The cone object:

CONE:

Jump to SDL

cone { V_BASE_CENTER, F_BASE_RADIUS, V_CAP_CENTER, F_CAP_RADIUS [open] [OBJECT_MODIFIERS] }

The cylinder object:

CYLINDER:

Jump to SDL

cylinder { V_BASE_CENTER, V_CAP_CENTER, F_RADIUS [open] [OBJECT_MODIFIERS] }

The height field object:

HEIGHT_FIELD:

Jump to SDL

height_field { HF_IMAGE [HF_MODIFIERS] }

HF_IMAGE:

FUNCTION_IMAGE | [HF_TYPE] FILE_NAME [gamma HF_GAMMA] [premultiplied BOOL]

HF_TYPE:

exr | gif | hdr | iff | jpeg | pgm | png | ppm | sys | tga | tiff

HF_GAMMA:

FLOAT | srgb

HF_MODIFIERS:

[hierarchy [BOOL]] & [smooth] & [water_level FLOAT] & [OBJECT_MODIFIERS]

The isosurface object:

ISOSURFACE:

Jump to SDL

isosurface { FLOAT_USER_FUNCTION [ISOSURFACE_ITEMS] [OBJECT_MODIFIERS] }

ISOSURFACE_ITEMS:

[contained_by { CONTAINER }] & [threshold FLOAT] & [accuracy FLOAT] & [max_gradient FLOAT [evaluate F_MIN_ESTIMATE, F_MAX_ESTIMATE, F_ATTENUATION]] & [open] & [INTERSECTION_LIMIT]

CONTAINER:

sphere { V_CENTER, F_RADIUS } | box { V_CORNER1, V_CORNER2 }

INTERSECTION_LIMIT:

max_trace INT | all_intersections

The Julia fractal object:

JULIA_FRACTAL:

Jump to SDL

julia_fractal { 4D_VECTOR [JF_ITEMS] [OBJECT_MODIFIERS] }

JF_ITEMS:

[ALGEBRA_ITEM] & [max_iteration INT] & [precision FLOAT] & [slice V4_NORMAL, F_DISTANCE]

ALGEBRA_ITEM:

quaternion [QUATER_FUNCTION] | hypercomplex [HYPER_FUNCTION]

QUATER_FUNCTION:

sqr | cube

HYPER_FUNCTION:

sqr | cube | exp | reciprocal | sin | asin | sinh | asinh | cos | acos | cosh | acosh | tan | atan | tanh | atanh | ln | pwr (FLOAT,FLOAT)

The lathe object:

LATHE:

Jump to SDL

lathe { [LATHE_SPLINE_TYPE] I_NUM_POINTS, POINT_LIST [LATHE_MODIFIERS] }

LATHE_SPLINE_TYPE:

linear_spline | quadratic_spline | cubic_spline | bezier_spline

POINT_LIST:

2D_VECTOR [, 2D_VECTOR]...

The quantity of 2D_VECTORs is specified by the I_NUM_POINTS value.

LATHE_MODIFIERS:

[sturm [BOOL]] & [UV_MAPPING] & [OBJECT_MODIFIERS]

The ovus object:

OVUS:

Jump to SDL

ovus { BOTTOM_RADIUS, TOP_RADIUS [OBJECT_MODIFIERS] }

The parametric object:

PARAMETRIC:

Jump to SDL

parametric { FLOAT_USER_FUNCTION, FLOAT_USER_FUNCTION, FLOAT_USER_FUNCTION 2D_VECTOR, 2D_VECTOR [PARAMETRIC_ITEMS] [UV_MAPPING] & [OBJECT_MODIFIERS] }

PARAMETRIC_ITEMS:

[contained_by { CONTAINER }] & [max_gradient FLOAT] & [accuracy FLOAT] & [precompute I_DEPTH, x, y, z]

CONTAINER:

sphere { V_CENTER, F_RADIUS } | box { V_CORNER1, V_CORNER2 }

The prism object:

PRISM:

Jump to SDL

prism { [PRISM_ITEMS] F_HEIGHT1, F_HEIGHT2, I_NUM_POINTS, POINT_LIST [open] [PRISM_MODIFIERS] }

PRISM_ITEMS:

[PRISM_SPLINE_TYPE] & [PRISM_SWEEP_TYPE]

PRISM_SPLINE_TYPE:

linear_spline | quadratic_spline | cubic_spline | bezier_spline

PRISM_SWEEP_TYPE:

linear_sweep | conic_sweep

PRISM_MODIFIERS:

[sturm [BOOL]] & [OBJECT_MODIFIERS]

The sphere object:

SPHERE:

Jump to SDL

sphere { V_CENTER, F_RADIUS [SPHERE_MODIFIERS] }

SPHERE_MODIFIERS:

[UV_MAPPING] & [OBJECT_MODIFIERS]

The sphere sweep object:

SPHERE_SWEEP:

Jump to SDL

sphere_sweep { SWEEP_SPLINE_TYPE I_NUM_SPHERES, SPHERE_LIST [tolerance F_DEPTH_TOLERANCE] [OBJECT_MODIFIERS] }

SWEEP_SPLINE_TYPE:

linear_spline | b_spline | cubic_spline

SPHERE_LIST:

V_CENTER, F_RADIUS [, SPHERE_LIST]

The quantity of V_CENTER, F_RADIUS pairs is specified by the I_NUM_SPHERES value.

The superquadric ellipsoid object:

SUPERELLIPSOID:

Jump to SDL

superellipsoid { < FLOAT, FLOAT > [OBJECT_MODIFIERS] }

The surface of revolution object:

SOR:

Jump to SDL

sor { I_NUM_POINTS, POINT_LIST [open] [SOR_MODIFIERS] }

SOR_MODIFIERS:

[sturm [BOOL]] & [UV_MAPPING] & [OBJECT_MODIFIERS]

The text object:

TEXT:

Jump to SDL

text { ttf FILE_NAME STRING F_THICKNESS, V_OFFSET [OBJECT_MODIFIERS] }

The torus object:

TORUS:

Jump to SDL

torus { F_MAJOR_RADIUS, F_MINOR_RADIUS [TORUS_MODIFIERS] }

TORUS_MODIFIERS:

[sturm [BOOL]] & [UV_MAPPING] & [OBJECT_MODIFIERS]

Quick Reference Contents

Finite Patch Objects

Describe a totally thin, finite shape:

FINITE_PATCH_OBJECT:

Jump to SDL

BICUBIC_PATCH | DISC | MESH | MESH2 | POLYGON | TRIANGLE | SMOOTH_TRIANGLE

The bicubic patch object:

BICUBIC_PATCH:

Jump to SDL

bicubic_patch { PATCH_ITEMS [PATCH_UV_VECTORS] CONTROL_POINTS [BICUBIC_PATCH_MODIFIERS] }

PATCH_ITEMS:

type PATCH_TYPE & [u_steps INT] & [v_steps INT] & [flatness FLOAT]

PATCH_TYPE:

0 | 1

PATCH_UV_VECTORS:

uv_vectors V2_CORNER1, V2_CORNER2, V2_CORNER3, V2_CORNER4

CONTROL_POINTS:

16 VECTORs, optionally separated by commas.

BICUBIC_PATCH_MODIFIERS:

[UV_MAPPING] & [OBJECT_MODIFIERS]

The disc object:

DISC:

Jump to SDL

disc { V_CENTER, V_NORMAL, F_RADIUS [, F_HOLE_RADIUS] [OBJECT_MODIFIERS] }

The mesh object:

MESH:

Jump to SDL

mesh { MESH_TRIANGLE... [MESH_MODIFIERS] }

MESH_TRIANGLE:

triangle { V_CORNER1, V_CORNER2, V_CORNER3 [MESH_UV_VECTORS] [MESH_TEXTURE] } |
smooth_triangle { V_CORNER1, V_NORMAL1, V_CORNER2, V_NORMAL2, V_CORNER3, V_NORMAL3 [MESH_UV_VECTORS] [MESH_TEXTURE] }

MESH_UV_VECTORS:

uv_vectors V2_CORNER1, V2_CORNER2, V2_CORNER3

MESH_TEXTURE:

texture { TEXTURE_IDENTIFIER } |
texture_list { TEXTURE_IDENTIFIER TEXTURE_IDENTIFIER TEXTURE_IDENTIFIER }

MESH_MODIFIERS:

[inside_vector V_DIRECTION] & [hierarchy [BOOL]] & [UV_MAPPING] & [OBJECT_MODIFIERS]

The mesh2 object:

MESH2:

Jump to SDL

mesh2 { MESH2_VECTORS [TEXTURE_LIST] MESH2_INDICES [MESH2_MODIFIERS] }

MESH2_VECTORS:

VERTEX_VECTORS [NORMAL_VECTORS] [UV_VECTORS]

VERTEX_VECTORS:

vertex_vectors { I_NUM_VERTICES, VECTOR [, VECTOR]... }

NORMAL_VECTORS:

normal_vectors { I_NUM_NORMALS, VECTOR [, VECTOR]... }

UV_VECTORS:

uv_vectors { I_NUM_UV_VECTORS, 2D_VECTOR [, 2D_VECTOR]... }

TEXTURE_LIST:

texture_list { I_NUM_TEXTURES, TEXTURE [, TEXTURE]... }

MESH2_INDICES:

FACE_INDICES [NORMAL_INDICES] [UV_INDICES]

FACE_INDICES:

face_indices { I_NUM_FACES, FACE_INDICES_ITEM [, FACE_INDICES_ITEM]... }

FACE_INDICES_ITEM:

VECTOR [, I_TEXTURE_INDEX [, I_TEXTURE_INDEX, I_TEXTURE_INDEX ]]

NORMAL_INDICES:

normal_indices { I_NUM_FACES, VECTOR [, VECTOR]... }

UV_INDICES:

uv_indices { I_NUM_FACES, VECTOR [, VECTOR]... }

MESH2_MODIFIERS:

[inside_vector V_DIRECTION] & [UV_MAPPING] & [OBJECT_MODIFIERS]

The polygon object:

POLYGON:

Jump to SDL

polygon { I_NUM_POINTS, V_POINT [, V_POINT]... [OBJECT_MODIFIERS] }

The quantity of V_POINTs is specified by the I_NUM_POINTS value.

The triangle object:

TRIANGLE:

Jump to SDL

triangle { V_CORNER1, V_CORNER2, V_CORNER3 [OBJECT_MODIFIERS] }

The smooth triangle object:

SMOOTH_TRIANGLE:

Jump to SDL

smooth_triangle { V_CORNER1, V_NORMAL1, V_CORNER2, V_NORMAL2, V_CORNER3, V_NORMAL3 [OBJECT_MODIFIERS] }

Quick Reference Contents

Identifier Declaration

Infinite Solid Objects

This document is protected, so submissions, corrections and discussions should be held on this documents talk page.