Reference:File I/O Directives

You may open, read, write, append, and close plain ASCII text files while parsing POV-Ray scenes. This feature is primarily intended to help pass information between frames of an animation. Values such as an object's position can be written while parsing the current frame and read back during the next frame. Clever use of this feature could allow a POV-Ray scene to generate its own include files or write self-modifying scripts. We trust that users will come up with other interesting uses for this feature.

Note: Some platform versions of POV-Ray (e.g. Windows) provide means to restrict the ability of scene files to read & write files.

The fopen Directive

Users may open a text file using the #fopen directive. The syntax is as follows:

FOPEN_DIRECTIVE:
  #fopen IDENTIFIER "filename" OPEN_TYPE
OPEN_TYPE:
  read | write | append

Where IDENTIFIER is an undefined identifier used to reference this file as a file handle, "filename" is any string literal or string expression which specifies the file name. Files opened with the read are open for read only. Those opened with write create a new file with the specified name and it overwrites any existing file with that name. Those opened with append opens a file for writing but appends the text to the end of any existing file.

The file handle identifier created by #fopen is always global and remains in effect (and the file remains open) until the scene parsing is complete or until you #fclose the file. You may use #ifdef FILE_HANDLE_IDENTIFIER to see if a file is open.

The fclose Directive

Files opened with the #fopen directive are automatically closed when scene parsing completes however you may close a file using the #fclose directive. The syntax is as follows:

FCLOSE_DIRECTIVE:
  #fclose FILE_HANDLE_IDENTIFIER

Where FILE_HANDLE_IDENTIFIER is previously opened file opened with the #fopen directive. See The #fopen Directive.

The read Directive

You may read string, float or vector values from a plain ASCII text file directly into POV-Ray variables using the #read directive. The file must first be opened in read mode using the #fopen directive. The syntax for #read is as follows:

READ_DIRECTIVE:
  #read (FILE_HANDLE_IDENTIFIER, DATA_IDENTIFIER[,DATA_IDENTIFIER]..)
DATA_IDENTIFIER:
  UNDECLARED_IDENTIFIER | FLOAT_IDENTIFIER | VECTOR_IDENTIFIER | 
  STRING_IDENTIFIER

Where FILE_HANDLE_IDENTIFIER is the previously opened file. It is followed by one or more DATA_IDENTIFIERs separated by commas. The parentheses around the identifier list are required. A DATA_IDENTIFIER is any undeclared identifier or any previously declared string identifier, float identifier, or vector identifier. Undefined identifiers will be turned into global identifiers of the type determined by the data which is read. Previously defined identifiers remain at whatever global/local status they had when originally created. Type checking is performed to insure that the proper type data is read into these identifiers.

The format of the data to be read must be a series of valid string literals, float literals, or vector literals separated by commas. Expressions or identifiers are not permitted in the data file however unary minus signs and exponential notation are permitted on float values.

If you attempt to read past end-of-file, the file is automatically closed and the FILE_HANDLE_IDENTIFIER is deleted from the symbol table. This means that the boolean function defined(IDENTIFIER) can be used to detect end-of-file.

For example:

#fopen MyFile "mydata.txt" read
#while (defined(MyFile))
  #read (MyFile,Var1,Var2,Var3)
  ...
#end

The write Directive

You may write string, float or vector values to a plain ASCII text file from POV-Ray variables using the #write directive. Additionally it is now possible to write 8, 16, and 32-bit words to an external file.

These words may be arranged in either little or big-endian fashion. Placing one of the following keywords in the argument list of a #write statement causes the values up to the next comma to be written in binary format, using 2's complement integer representation, rounded to the nearest integer in the representable range:

  uint8              - unsigned byte (0..255)
  sint8              - signed byte (-128..127)
  uint16be, uint16le - unsigned 16-bit word (0..65535)
  sint16be, sint16le - signed 16-bit word (-32768..32767)
  sint32be, sint32le - signed 32-bit word (-2^31..2^31-1)

Note: Currently, unsigned 32-bit words are not supported.

Keywords ending in "be" will cause the values to be written most significant byte first (big endian, aka network byte order) while those ending in "le" will instead write the least significant byte first (little endian, Intel format).

Note: See the sample macro ARRAYS_WriteDF3 in arrays.inc to see how this feature may be used.

As always, the file must first be opened in either write or append mode using the #fopen directive. The syntax for the #write directive is as follows:

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

Where FILE_HANDLE_IDENTIFIER is the previously opened file. It is followed by one or more DATA_ITEMs separated by commas. The parentheses around the identifier list are required. A DATA_ITEM is any valid string expression, float expression, or vector expression. Float expressions are evaluated and written as signed float literals. If you require format control, you should use the str(VALUE,L,P) function to convert it to a formatted string. See String Functions for details on the str function. Vector expressions are evaluated into three signed float constants and are written with angle brackets and commas in standard POV-Ray vector notation. String expressions are evaluated and written as specified.

Note: Data read by the #read directive must have comma delimiters between values and quotes around string data but the #write directive does not automatically output commas or quotes.

For example the following #read directive reads a string, float and vector.

#read (MyFile,MyString,MyFloat,MyVect)

It expects to read something like:

"A quote delimited string", -123.45, <1,2,-3>

The POV-Ray code to write this might be:

#declare Val1 = -123.45;
#declare Vect1 = <1,2,-3>;
#write(MyFile,"\"A quote delimited string\",",Val1,",",Vect1,"\n")

See String Literals and Text Formatting for details on writing special characters such as quotes, newline, etc.