\chapter{Options}

This appendix describes the command-line arguments accepted by {\em rayshade}.
These options override defaults
as well as any values or flags given in the input file,
and are thus useful for generating test and other unusual, ``non-standard''
renderings.

The general form of a \rayshade command line is:
\begin{quote}
{\tt rayshade} [{\em Options}] [{\em filename}]
\end{quote}

If given, the input file is read from {\em filename}.  By default,
the input file is read from the standard input.
Recall that, by default, the image file is written to the standard
output; you will need to redirect the standard output if you have not
chosen to write the image to a file directly.

Command-line options fall into to broad categories: those that set
numerical or other values and thus must be followed by further arguments,
and those that simply turn features on and off.  {\em Rayshade}'s
convention is to name the value-setting arguments using capital letters,
and feature-toggling arguments using lower-case letters.

\begin{defkey}{-A}{{\em thresh}}
	Set the adaptive ray tree pruning value.
\end{defkey}
Overrides the value specified via the {\tt cutoff} keyword.

\begin{defkey}{-a}{}
	Toggle writing of alpha channel.
\end{defkey}
This option is only available when the Utah Raster Toolkit is
being used.

\begin{defkey}{-C}{}
	Specify the options that should be passed to the C
	preprocessor.
\end{defkey}
The C preprocessor, if available, is applied to all of the input
passed to {\em rayshade}.

\begin{defkey}{-c}{}
	Continue an interrupted rendering.
\end{defkey}
When given, this option indicates that the image file being written
to contains a partially-completed image.  \Rayshade will scan the
image to determine the scanline from which to continue the rendering.
This option is only available with the Utah Raster Toolkit.
The {\tt -O} option must also be used.

\begin{defkey}{-D}{{\em depth}}
	Set maximum ray tree depth.
\end{defkey}
Overrides the value specified in the input file via the {\tt maxdepth}
keyword.

\begin{defkey}{-E}{{\em separation}}
	Set eye separation for rendering of stereo pairs.
\end{defkey}
Overrides the value specified via the {\tt eyesep} keyword.

\begin{defkey}{-e}{}
	Write exponential RLE file.
\end{defkey}
This option is only available for use with the Utah Raster Toolkit.

\begin{defkey}{-F}{{\em freq}}
	Set frequency of status report.
\end{defkey}
Overrides the value given using the {\tt report} keyword.

\begin{defkey}{-G}{{\em gamma}}
	Use given gamma correction exponent writing writing
	color information to the image file.
\end{defkey}
The default value for {\em gamma} is 1.0.

\begin{defkey}{-h}{}
	Print a short use message.
\end{defkey}

\begin{defkey}{-j}{}
	Use jittered sampling to perform antialiasing.
\end{defkey}
This option overrides the {\tt adaptive} keyword, if present,
in the input file.

\begin{defkey}{-l}{}
	Render the left stereo pair image.
\end{defkey}

\begin{defkey}{-n}{}
	Do not render shadows.
\end{defkey}

\begin{defkey}{-O}{{\em outfile}}
	Write the image to the named file.
\end{defkey}
This option overrides the name given with the {\tt outfile} keyword,
if any,
in the input file.

\begin{defkey}{-o}{}
	Trace shadow rays through transparent objects.
\end{defkey}
Giving this option is equivalent to specifying {\tt shadowtransp}
in the input file.  By default, \rayshade does not trace shadow
rays through transparent objects.

\begin{defkey}{-P}{{\em depth}}
	Use adaptive supersampling with the given
	maximum depth.
\end{defkey}
This option overrides the {\tt jittered} keyword and the
value associated the
{\tt adaptive} keyword given in the input file, if any.

\begin{defkey}{-p}{}
	Perform preview-quality rendering.
\end{defkey}
This option is equivalent to {\tt -n -P 0 -S 1}.

\begin{defkey}{-q}{}
	Do not print warning messages.
\end{defkey}

\begin{defkey}{-R}{{\em xres yres}}
	Produce an image {\em xres} pixels wide by
	{\em yres} pixels high.
\end{defkey}
This option overrides any resolution set by use of
the {\tt screen} keyword.

\begin{defkey}{-r}{}
	Render the right stereo pair image.
\end{defkey}

\begin{defkey}{-S}{{\em samples}}
	Use $samples^2$ jittered samples.
\end{defkey}
This option overrides any value set through the use of
the {\tt samples} keyword in the input file.

\begin{defkey}{-s}{}
	Disable caching of  shadowing information.
\end{defkey}
It should not be necessary to ever use this option.

\begin{defkey}{-T}{{\em r g b}}
	Set the contrast threshold in the three
	color channels for use in adaptive supersampling.
\end{defkey}
This option overrides any value given through the use of
the {\em contrast} keyword.

\begin{defkey}{-V}{{\em	filename}}
	Write verbose output to the named file.
\end{defkey}
This option overrides any file named through the use of
the {\tt report} keyword.

\begin{defkey}{-v}{}
	Write verbose output.
\end{defkey}
When given, this option causes information about the options
selected and the objects defined to be included in the
report file.
