Nicolas Calimet <pov4grasp@free.fr>

Updated Aug 29, 2006

Click for full-size (24 KB)

The Unix render frontend patch is an extension to POV-Ray / MegaPOV for Unix that modifies the user interface by adding color and format capabilities to the POV-Ray text streams and an alternate implementation for the ASCII display feature.

Introduction

User interface

The additional features provided in this patch can be user-controlled via either environment variables or patch-specific command-line options which exist in several variants. In the rest of this document command-line options are given as a single variant. Refer to the common user interface instructions for details.

POV-Ray text streams

The POV-Ray text streams are used by the program to output various messages such as render statistics, debug messages and errors. By default POV-Ray for Unix sends those streams to the standard error (often noted stderr) unless they are redirected to files using the appropriate POV-Ray command-line options or INI settings.

This patch allows to better control the way those streams are output. Each stream can be assigned a color (actually several attributes such as foreground and background color, text blinking, etc.) and a format (typically, simple prefix and suffix texts surrounding the original message). Additionally, custom tab stops can be defined to properly handle the stream messages containing tabular characters (tabs are internally expanded to spaces). A tab marker may be displayed using an user-specified character.

ASCII display

POV-Ray for Unix offers several ways to display the image it renders: graphics displays (usually using the X Window System) or a text display that shows a crude representation of the image in the form of fixed-size ASCII character array. The text display can be useful when one wants to avoid running an X server or when such facility is not available on the platform. (On the Linux platform, other non-X graphic displays are available too; see in particular the Linux framebuffer display patch.) Unfortunately, in POV-Ray 3.6 for Unix this feature does not work well due to the periodic output of status messages.

Click for full-size (13 KB) This patch offers an alternate implementation of the legacy ASCII display feature. First, the status messages are placed at the bottom of the terminal (unless stderr is not connected to a tty) to avoid interfering with the 77x22 character array depicting the rendered image. Second, the rendering can be stopped by pressing the 'q' key anytime after parsing is started (and provided the interrupting option +X or Test_Abort is on). This implementation also properly handles mosaic preview and the drawing of vista boxes.

ANSI-compatible terminal

The stream colors and ASCII display features can only work with terminals that are able to understand ANSI escape sequences (usually most modern terminals do, e.g. "xterm" or "linux"). The patch detects whether the terminal has such capability; it warns that colors or a nice-looking ASCII display cannot be used otherwise.

The terminal is defined by the value of the TERM environment variable or the --term command-line option. Usually the appropriate value for the TERM environment is automatically set when starting a new shell.

Terminal capabilities are defined in so-called terminfo files which are located under the /usr/share/terminfo/ hierarchy (also called terminfo database) by default. An alternate location can be set via the TERMINFO environment variable.

Note: There is no command-line option to override the TERMINFO setting.

A given terminfo file is located in a subdirectory of the terminfo database named from the first letter of the terminal. For instance, the capabilities for the "xterm" terminal are described in the $TERMINFO/x/xterm file. A terminfo file contains binary data only. Refer to the terminfo(5) manual for details.

POV-Ray stream wrap width

Description

POV-Ray for Unix always outputs its text streams with a maximum of 80 characters per line, i.e. long messages are splitted over several lines with a wrap width of 80. The text wrapping normally occurs at a word boundary. When no space is present in the last quarter of the line, the text is wrapped sharp within the last word.

A wrap width of 80 characters is ideal for the terminals that were originally designed for displaying 80x24 (vt100) or 80x25 (IBM PC) characters on a text-only console screen. However, most modern terminals and terminal emulators support arbitrary sizes and can display lines of more than e.g. 150 characters depending on the screen resolution and font size. Example of such a terminal is "xterm".

This patch offers the possibility to change the wrap width so as to benefit from wide terminals.

Synopsis

Environment variable:

export POV_STREAM_WRAP_WIDTH=INTEGER  # bash-like shells
setenv POV_STREAM_WRAP_WIDTH INTEGER  # csh-like shells

Command-line option:

--pov-stream-wrap-width=INTEGER

where INTEGER is a positive value of at least 80.

Note: Only wrap width values equal to or above 80 are valid.

Default value

Terminal width, or 80 when the terminal size cannot be determined (e.g. when stderr is not connected to a tty device).

Example

The following:

export POV_STREAM_WRAP_WIDTH=120

will wrap the text lines after 120 characters unless the terminal window is smaller (and its size can be determined).

POV-Ray stream color(s)

Global color behaviour: `POV_STREAM_COLOR`

Description

This setting controls whether colors are used for POV-Ray streams regardless of the actual color settings described in the next section.

Synopsis

Environment variable:

export POV_STREAM_COLOR=MODE  # bash-like shells
setenv POV_STREAM_COLOR MODE  # csh-like shells

Command-line option:

--pov-stream-color=MODE

MODE:

never | always | auto

The option value means:

never: never use colors for the POV-Ray streams
always: always use colors
auto: stream colors are used only if the standard error is connected to a terminal (tty)

Note: always and auto assume that the user-defined colors exist and are valid.

Default value

The default corresponds to the always behaviour.

Example

The following:

export POV_STREAM_COLOR=auto

will allow to color the POV-Ray streams when the standard error is connected to a terminal (e.g. screen output) and disable stream colors otherwise (e.g. when redirecting stderr to a file or pipe).

Stream colors: `POV_STREAM_COLORS`

Description

This patch allows to assign colors (text and background colors) and other decoration attributes (bold, underline, etc.) to the individual POV-Ray streams. The syntax is inspired from the color capability of GNU ls; see the output of the dircolors(1) command for an example.

Note: The colors are not used when the POV-Ray streams are redirected to files using the appropriate POV-Ray options (e.g. +GAfile).

Synopsis

Environment variable:

export POV_STREAM_COLORS=COLORS  # bash-like shells
setenv POV_STREAM_COLORS COLORS  # csh-like shells

Command-line option:

--pov-stream-colors=COLORS

COLORS:

STREAMCOLOR[:STREAMCOLOR:...:STREAMCOLOR]

STREAMCOLOR:

STREAM=COLORDEF

STREAM:

all | banner | debug | fatal | render | statistic | status | warning

COLORDEF:

INTEGER[;INTEGER;...;INTEGER]

A color definition COLORDEF consists of a sequence of integers (codes) seperated by semi-colons, in any order. The valid numeric codes and their usual meaning are defined in categories as follows:

foreground color codes:

code 30 31 32 33 34 35 36 37

meaning black red green yellow blue magenta cyan gray
background color codes:

code 40 41 42 43 44 45 46 47

meaning gray red green yellow blue magenta cyan white
attribute codes:

code 0 1 2 4 5 7 8

meaning none bold dim underline blink reverse invisible

code	`30`	`31`	`32`	`33`	`34`	`35`	`36`	`37`
meaning	black	red	green	yellow	blue	magenta	cyan	gray

code	`40`	`41`	`42`	`43`	`44`	`45`	`46`	`47`
meaning	gray	red	green	yellow	blue	magenta	cyan	white

code	`0`	`1`	`2`	`4`	`5`	`7`	`8`
meaning	none	bold	dim	underline	blink	reverse	invisible

Numeric codes that are left-padded with zeros, e.g. 05 or 000041, are valid too.

In case two color codes belong to the same category (i.e. foreground or background) the last code specified is used. Attributes codes can be mixed to obtain combined effects. For instance, the definition 1;4;31;42 should give this.

Note: The colors and attributes scheme above does entirely depend on your terminal capabilities and settings. For instance, the xterm terminal does not recognize the "invisible" attribute. Some terminals may replace the bold attribute by a brighter intensity for the text color. Others allow to redefine the individual color codes with arbitrary RGB triplets.

The all stream is a special definition that applies to all of the POV-Ray streams and is inherited by the other definitions. This behaviour allows to define a default setting for all the POV-Ray streams at once (for instance the background color) and then tweak some of the streams individually by adding more codes (for instance text color, bold attribute).

Default value

None.

Example

The following:

export POV_STREAM_COLORS="all=1;31:fatal=43"

will color all text streams in bold red and add a yellow background to the fatal error stream.

Usage example

This example shows how to setup different POV-Ray stream colors depending on the terminal currently in use:

for bash-like shells:

export POV_STREAM_COLOR=auto
case "$TERM" in
  linux*) export POV_STREAM_COLORS="all=1:fatal=37;41:warning=33:debug=0;35";;
  xterm*) export POV_STREAM_COLORS="fatal=1;37;41:warning=30;43:status=1:debug=35";;
esac

You may place such definitions in your ~/.bashrc or ~/.profile startup script.

for csh-like shells:

setenv POV_STREAM_COLOR auto
switch ("$TERM")
  case "linux*":
    setenv POV_STREAM_COLORS "all=1:fatal=37;41:warning=33:debug=0;35"
    breaksw
  case "xterm*":
    setenv POV_STREAM_COLORS "fatal=1;37;41:warning=30;43:status=1:debug=35"
    breaksw
endsw

You may place such definitions in your ~/.cshrc or ~/.profile startup script.

POV-Ray stream format(s)

Global format behaviour: `POV_STREAM_FORMAT`

Description

This setting controls whether formats are used for POV-Ray streams regardless of the actual format settings described in the next section.

Synopsis

Environment variable:

export POV_STREAM_FORMAT=MODE  # bash-like shells
setenv POV_STREAM_FORMAT MODE  # csh-like shells

Command-line option:

--pov-stream-format=MODE

MODE:

never | always | auto

The option value means:

never: never output user formats, only the original POV-Ray message
always: always output formatted messages
auto: stream formats are used only if the standard error is connected to a terminal (tty)

Note: always and auto assume that the user-defined formats exist and are valid.

Default value

The default corresponds to the always behaviour.

Example

The following:

export POV_STREAM_FORMAT=auto

will allow to format the POV-Ray streams when the standard error is connected to a terminal (e.g. screen output) and disable stream formats otherwise (e.g. when redirecting stderr to a file or pipe).

Stream formats: `POV_STREAM_FORMATS`

Description

This patch offers the possibility to format the various POV-Ray streams, allowing for e.g. easy filtering. While relatively flexible, the format essentially consists in the original POV-Ray message surrounded by optional prefix and suffix texts. The suffix text is always right-aligned so as to match the stream wrap width.

Note: The formats are not used when the POV-Ray streams are redirected to files using the appropriate POV-Ray options (e.g. +GAfile).

Synopsis

Environment variable:

export POV_STREAM_FORMATS=FORMATS  # bash-like shells
setenv POV_STREAM_FORMATS FORMATS  # csh-like shells

Command-line option:

--pov-stream-formats=FORMATS

FORMATS:

STREAMFORMAT[:STREAMFORMAT:...:STREAMFORMAT]

STREAMFORMAT:

STREAM=FORMATDEF

STREAM:

all | banner | debug | fatal | render | statistic | status | warning

FORMATDEF:

[STRING] [%s] [STRING]

A format definition FORMATDEF is a string containing arbitrary text and at least one %s formatter that indicates the original POV-Ray message to output. For instance: prefix-text %s suffix-text

A single %s formatter is allowed, i.e. only the first one found in the format string will be expanded to the original POV-Ray message. If either no %s formatter is found or the format string is empty/not valid (see below) then no custom formatting is applied and the original POV-Ray message is output as-is.

Any colon character (:) that is part of the format string must be escaped with a backslash (\:) otherwise it is recognized as a format seperator. Backslash is escaped as double-backslashes (\\) unless the shell interprets it as a single backslash (in which case \\\\ should be used instead). Other usual control characters such as newline (\n) or tab (\t) are not allowed and are passed as n and t, respectively.

The all stream is a special definition that applies to all of the POV-Ray streams except those that have their own format specified explicitely. Therefore, to unformat a particular stream while the all definition is present, one has to define the format of this stream by using any of:

the formatter alone, e.g. status=%s
an empty format string, e.g. status=
an invalid format string, e.g. status=junk

Default value

None.

Example

The following:

export POV_STREAM_FORMATS="warning=WARNING: %s"

will format the warning messages with a "WARNING: " prefix while all the other streams will output their original, unformatted messages.

Usage example

This example shows how to setup POV-Ray stream formats:

for bash-like shells:

export POV_STREAM_FORMAT=always
export POV_STREAM_FORMATS="all=POV> %s <POV:fatal=*** %s ***:banner="

You may place such definitions in your ~/.bashrc or ~/.profile startup script.

for csh-like shells:

setenv POV_STREAM_FORMAT always
setenv POV_STREAM_FORMATS "all=POV> %s <POV:fatal=*** %s ***:banner="

You may place such definitions in your ~/.cshrc or ~/.profile startup script.

In this example, all POV-Ray streams (unless specified otherwise) are formatted (whether output to the screen or not) with a leading "POV> " and a trailing " <POV" surrounding the original message. As special cases, the fatal errors are formatted with surrounding stars and the banner messages are not formatted at all.

POV-Ray stream tab stops and tab mark

Description

Some of the POV-Ray streams can output user-defined messages (e.g. debug stream) or text obtained from input files (e.g. when reporting a parse error) which may contain tabular characters (tabs). Tabs are control characters that are usually interpreted by the terminal and displayed according to its tab stops setting. The latter cannot be obtained in a portable way within POV-Ray.

To let POV-Ray consistently display the tabs together with the stream formats and (background) colors, this patch internally replaces all tab characters by spaces when sending the messages to stderr. Since the tab stops settings of the terminal are thus ignored, the patch allows to define custom tab stops in order to emulate the terminal behaviour. The option syntax is inspired by the less utility.

Tab stops can be optionally displayed in the form of a single character ("tab mark") that is either left or right-aligned on the tab boundary.

Synopsis

Environment variables:

export POV_STREAM_TAB_STOPS=INTEGER[,INTEGER,...,INTEGER]  # bash-like shells
export POV_STREAM_TAB_MARK=MARKER

setenv POV_STREAM_TAB_STOPS INTEGER[,INTEGER,...,INTEGER]  # csh-like shells
setenv POV_STREAM_TAB_MARK MARKER

Command-line options:

--pov-stream-tab-stops=INTEGER[,INTEGER,...,INTEGER]
--pov-stream-tab-mark=MARKER

MARKER:

CHARACTER | INTEGER

The value for the stream tab stops is either:

a single positive number x: tab stops are set at multiples of x;
a list of comma-seperated positive numbers x1,x2,...,xN: tab stops are set at those columns and then continue with the same spacing as the last two.

Note: Only positive, 1-based tab stops are allowed. Comma-seperated values should define a series of increasing numbers otherwise some tab stops will be ignored (and reported as such).

The value for the stream tab mark is either:

a single 8 bit character (typically from the US-ASCII or ISO 8859 charsets, e.g. _ for underscore) that is always right-aligned to the tab boundary;
a character code in the form of an octal (0nnn), decimal (nnn), or hexadecimal (0xnn) number which sign specifies the character alignment (positive is right-aligned, negative is left-aligned).

Note: Not all characters or character codes are allowed: characters which decimal code is 127 or below 32 are forbidden. A left-aligned character alignment cannot be specified when using the single-character syntax.

Default values

Tab stops are placed at a regular interval of 8 characters.

Tab mark is a space character.

Example

Click for full-size (14 KB)

The following:

export POV_STREAM_TAB_STOPS=8,16,20
export POV_STREAM_TAB_MARK=0xAC

will set tab stops at columns 8, 16, 20, 24, 28, etc. and show tabulations with a right-aligned "not sign" character (character code 0xAC) on an ISO 8859-1 (Latin-1) compatible terminal.

Extensions and patches to POV-Ray 3.6 / MegaPOV 1.2 for Unix

Introduction

User interface

POV-Ray text streams

ASCII display

ANSI-compatible terminal

POV-Ray stream wrap width

Description

Synopsis

Default value

Example

POV-Ray stream color(s)

Global color behaviour: POV_STREAM_COLOR

Description

Synopsis

Default value

Example

Stream colors: POV_STREAM_COLORS

Description

Synopsis

Default value

Example

Usage example

POV-Ray stream format(s)

Global format behaviour: POV_STREAM_FORMAT

Description

Synopsis

Default value

Example

Stream formats: POV_STREAM_FORMATS

Description

Synopsis

Default value

Example

Usage example

POV-Ray stream tab stops and tab mark

Description

Synopsis

Default values

Example

Extensions and patches to
POV-Ray 3.6 / MegaPOV 1.2 for Unix

Global color behaviour: `POV_STREAM_COLOR`

Stream colors: `POV_STREAM_COLORS`

Global format behaviour: `POV_STREAM_FORMAT`

Stream formats: `POV_STREAM_FORMATS`