2.2.2.7 User Message Directives
With the addition of conditional and loop directives, the POV-Ray language has the potential to be more like an
actual programming language. This means that it will be necessary to have some way to see what is going on when trying
to debug loops and conditionals. To fulfill this need we have added the ability to print text messages to the screen.
You have a choice of five different text streams to use including the ability to generate a fatal error if you find it
necessary. Limited formatting is available for strings output by this method.
2.2.2.7.1 Text Message Streams
The syntax for a text message is any of the following:
TEXT_STREAM_DIRECTIVE:
#debug STRING | #error STRING | #warning STRING
Where STRING is any valid string of text including string identifiers or functions which return strings.
For example:
#switch (clock*360)
#range (0,180)
#debug "Clock in 0 to 180 range\n"
#break
#range (180,360)
#debug "Clock in 180 to 360 range\n"
#break
#else
#warning "Clock outside expected range\n"
#warning concat("Value is:",str(clock*360,5,0),"\n")
#end
There are seven distinct text streams that POV-Ray uses for output.
You may output only to three of them. On some versions of POV-Ray, each stream is designated by a particular color.
Text from these streams are displayed whenever it is appropriate so there is often an intermixing of the text. The
distinction is only important if you choose to turn some of the streams off or to direct some of the streams to text
files. On some systems you may be able to review the streams separately in their own scroll-back buffer. See
"Directing Text Streams to Files" for details on re-directing the streams to a text file.
Here is a description of how POV-Ray uses each stream. You may use them for whatever purpose you want except note
that use of the #error stream causes a fatal error after the text is displayed.
Debug: This stream displays debugging messages. It was primarily designed for developers but this
and other streams may also be used by the user to display messages from within their scene files.
Error: This stream displays fatal error messages. After displaying this text, POV-Ray will
terminate. When the error is a scene parsing error, you may be shown several lines of scene text that leads up to the
error.
Warning: This stream displays warning messages during the parsing of scene files and other
warnings. Despite the warning, POV-Ray can continue to render the scene.
The #render and #statistsics could be accessed in previous versions. Their output is now
redirected to the #debug stream. The #banner and #status streams can not be
accessed by the user.
Some escape sequences are available to include non-printing control characters in your text. These sequences are
similar to those used in string literals in the C programming language. The sequences are:
All character escape sequences
"\a"
|
Bell or alarm,
|
0x07
|
"\b"
|
Backspace,
|
0x08
|
"\f"
|
Form feed,
|
0x0C
|
"\n"
|
New line (line feed)
|
0x0A
|
"\r"
|
Carriage return
|
0x0D
|
"\t"
|
Horizontal tab
|
0x09
|
"\uNNNN"
|
Unicode character code NNNN
|
0xNNNN
|
"\v"
|
Vertical tab
|
0x0B
|
"\0"
|
Null
|
0x00
|
"\\"
|
Backslash
|
0x5C
|
"\'"
|
Single quote
|
0x27
|
"\""
|
Double quote
|
0x22
|
For example:
#debug "This is one line.\nBut this is another"\n
Depending on what platform you are using, they may not be fully supported for console output. However they will
appear in any text file if you re-direct a stream to a file.
|