--- ray/doc/man/man1/rpict.1	2015/05/26 10:00:46	1.19
+++ ray/doc/man/man1/rpict.1	2025/04/23 15:09:03	1.32
@@ -1,4 +1,4 @@
-.\" RCSid "$Id: rpict.1,v 1.19 2015/05/26 10:00:46 greg Exp $"
+.\" RCSid "$Id: rpict.1,v 1.32 2025/04/23 15:09:03 greg Exp $"
 .TH RPICT 1 2/26/99 RADIANCE
 .SH NAME
 rpict - generate a RADIANCE picture
@@ -18,6 +18,8 @@ rpict - generate a RADIANCE picture
 ]
 .br
 .B "rpict [ options ] \-defaults"
+.br
+.B "rpict \-features [feat1 ..]"
 .SH DESCRIPTION
 .I Rpict
 generates a picture from the RADIANCE scene given in
@@ -41,6 +43,21 @@ In the second form shown above, the default values
 for the options (modified by those options present)
 are printed with a brief explanation.
 .PP
+In the third form, a list of supported features is sent
+to the standard output, one per line.
+If additional arguments follow, they are checked for presence in
+this list.
+If a feature includes subfeatures, these may be checked as well by
+specifying:
+.nf
+
+	rpict -features FeatName=subfeat1,subfeat2
+
+.fi
+If any named feature or subfeature is missing, an error is
+reported and the program returns an error status.
+If all of the named features are present, a zero status is returned.
+.PP
 Most options are followed by one or more arguments, which must be
 separated from the option and each other by white space.
 The exceptions to this rule are the 
@@ -211,10 +228,10 @@ Set the pixel sample jitter to
 Distributed ray-tracing performs anti-aliasing by randomly sampling
 over pixels.
 A value of one will randomly distribute samples over full
-pixels.
+pixels, and is not really recommended due to the tendency of
+samples to (nearly) coincide.
 A value of zero samples pixel centers only.
-A value between zero and one is usually best
-for low-resolution images.
+A value around 0.5-0.8 is typical.
 .TP
 .BI -pm \ frac
 Set the pixel motion blur to
@@ -254,6 +271,28 @@ to use a very small fraction with the
 .I \-pd
 option, to avoid the ghosting effect of too few samples.
 .TP
+.BI -pc " xr yr xg yg xb yb xw yw"
+Use the specified chromaticity pairs for output primaries and white
+point rather than the standard RGB color space.
+.TP
+.BR \-pRGB
+Output standard RGB values (the default).
+.TP
+.BR \-pXYZ
+Output standard CIE XYZ tristimulus values rather than RGB.
+.TP
+.BI -f \ source
+Load definitions from the file
+.I source
+and assign at the global level.
+The usual set of library directories is searched based on the
+.I RAYPATH
+environment variable.
+.TP
+.BI -e \ expr
+Set additional definitions from
+.I expr.
+.TP
 .BI -dj \ frac
 Set the direct jittering to
 .I frac.
@@ -310,21 +349,21 @@ change greater than the
 specification will be calculated.
 .TP
 .BI -dr \ N
-Set the number of relays for secondary sources to
+Set the number of relays for virtual sources to
 .I N.
-A value of 0 means that secondary sources will be ignored.
+A value of 0 means that virtual sources will be ignored.
 A value of 1 means that sources will be made into first generation
-secondary sources; a value of 2 means that first generation
-secondary sources will also be made into second generation secondary
+virtual sources; a value of 2 means that first generation
+virtual sources will also be made into second generation virtual
 sources, and so on.
 .TP
 .BI -dp \ D
-Set the secondary source presampling density to D.
+Set the virtual source presampling density to D.
 This is the number of samples per steradian 
 that will be used to determine ahead of time whether or not
 it is worth following shadow rays through all the reflections and/or
-transmissions associated with a secondary source path.
-A value of 0 means that the full secondary source path will always
+transmissions associated with a virtual source path.
+A value of 0 means that the full virtual source path will always
 be tested for shadows if it is tested at all.
 .TP
 .BR \-dv
@@ -408,14 +447,14 @@ Set the number of ambient bounces to
 This is the maximum number of diffuse bounces computed by the indirect
 calculation. A value of zero implies no indirect calculation. 
 .IP
-In photon mapping mode (see
+This value defaults to 1 in photon mapping mode (see
 .I -ap
-below), a positive value implies that global photon irradiance is
-always computed via
+below), implying that global photon irradiance is always computed via
 .I one
-ambient bounce. A negative value enables a preview mode that directly
-visualises the irradiance from the global photon map without any ambient
-bounces.
+ambient bounce; this behaviour applies to any positive number of ambient
+bounces, regardless of the actual value specified.  A negative value enables
+a preview mode that directly visualises the irradiance from the global
+photon map without any ambient bounces.
 .TP
 .BI -ar \ res
 Set the ambient resolution to
@@ -439,14 +478,14 @@ A value of zero is interpreted as unlimited resolution
 Set the ambient accuracy to
 .I acc.
 This value will approximately equal the error
-from indirect illuminance interpolation.
+from indirect irradiance interpolation.
 A value of zero implies no interpolation.
 .TP
 .BI -ad \ N
 Set the number of ambient divisions to
 .I N.
 The error in the Monte Carlo calculation of indirect
-illuminance will be inversely proportional to the square
+irradiance will be inversely proportional to the square
 root of this number.
 A value of zero implies no indirect calculation.
 .TP
@@ -459,13 +498,15 @@ show a significant change.
 .BI -af \ fname
 Set the ambient file to
 .I fname.
-This is where indirect illuminance will be stored and retrieved.
-Normally, indirect illuminance values are kept in memory and
+This is where indirect irradiance will be stored and retrieved.
+Normally, indirect irradiance values are kept in memory and
 lost when the program finishes or dies.
-By using a file, different invocations can share illuminance
+By using a file, different invocations can share irradiance
 values, saving time in the computation.
-Also, by creating an ambient file during a low resolution rendering,
-better results can be obtained in a second high resolution pass.
+Also, by creating an ambient file during a low-resolution rendering,
+better results can be obtained in a second high-resolution pass.
+(It is a good idea to keep all of the calculation parameters the same,
+changing only the dimensions of the output picture.)\0
 The ambient file is in a machine-independent binary format
 which may be examined with
 .I lookamb(1).
@@ -540,7 +581,9 @@ Global photon irradiance is evaluated as part of the a
 above), caustic photon irradiance is evaluated at primary rays, and 
 indirect inscattering in 
 .I mist
-is accounted for by volume photons.
+is accounted for by volume photons. Contribution photons are treated as
+global photons by
+.I rpict.
 .IP
 Additionally specifying 
 .I bwidth2
@@ -557,14 +600,47 @@ in which case the bandwidth, if specified, is ignored,
 is invariably looked up.
 .IP
 Using direct photons replaces the direct calculation with density estimates
-for debugging and validation of photon emission.       
+for debugging and validation of photon emission.
 .TP
 .BI -am " frac"
-Coefficient for maximum search radius for photon map lookups. The search 
-radius is automatically determined based on the average photon distance to the
-distribution's centre of gravity, and scaled by this coefficient. Increase this
-value if multiple warnings about short photon lookups are issued.
+Maximum search radius for photon map lookups.  Without this option, an
+initial maximum search radius is estimated for each photon map from the
+average photon distance to the distribution's centre of gravity.  It is then
+adapted to the photon density in subsequent lookups.  This option imposes a
+global fixed maximum search radius for
+.I all
+photon maps, thus defeating the automatic adaptation.  It is useful when
+multiple warnings about short photon lookups are issued.  Note that this
+option does not conflict with the bandwidth specified with the
+.I \-ap
+option; the number of photons found will not exceed the latter, but may be
+lower if the maximum search radius contains fewer photons, thus resulting in
+short lookups.  Setting this radius too large, on the other hand, may
+degrade performance.
 .TP
+.BI -ac " pagesize"
+Set the photon cache page size when using out-of-core photon mapping. The
+photon cache reduces disk I/O incurred by on-demand loading (paging) of
+photons, and thus increases performance. This
+is expressed as a (float) multiple of the density estimate bandwidth
+specified with
+.I \-ap
+under the assumption that photon lookups are local to a cache page. Cache
+performance is sensitive to this parameter: larger pagesizes will reduce the
+paging frequency at the expense of higher latency when paging does occur.
+Sensible values are in the range 4 (default) to 16.
+.TP
+.BI -aC " cachesize"
+Set the total number of photons cached when using out-of-core photon
+mapping, taking into account the pagesize specified by
+.I \-ac. 
+Note that this is approximate as the number of cache pages is rounded to
+the nearest prime. This allows adapting the cache to the available physical
+memory. Cache performance is less sensitive to this parameter, and reasonable 
+performance can obtained with as few as 10k photons. The default is 1M. This 
+option recognises multiplier suffixes (k = 1e3, M = 1e6), both in upper and 
+lower case.
+.TP
 .BI -me " rext gext bext"
 Set the global medium extinction coefficient to the indicated color,
 in units of 1/distance (distance in world coordinates).
@@ -627,8 +703,8 @@ is zero, then Russian roulette is used for ray
 termination, and the
 .I -lw
 setting (below) must be positive.
-If N is a negative integer, then this sets the upper limit
-of reflections past which Russian roulette will be used.
+If N is a negative integer, then this limits the maximum
+number of reflections even with Russian roulette.
 In scenes with dielectrics and total internal reflection,
 a setting of 0 (no limit) may cause a stack overflow.
 .TP
@@ -645,6 +721,19 @@ continue rays with a probability equal to the ray weig
 divided by the given
 .I frac.
 .TP
+.BI -cs \ Ns
+Use
+.I Ns
+bands for spectral sampling rather than the default RGB calculation space.
+The maximum setting is controlled by the compiler macro MAXCSAMP, and
+defaults to 24.
+Larger values for Ns will be reduced to MAXCSAMP.
+.TP
+.BI -cw " nmA nmB"
+Set extrema to the given wavelengths for spectral sampling.
+The default is 380 and 780 nanometers.
+The order specified does not matter.
+.TP
 .BI -S \ seqstart
 Instead of generating a single picture based only on the view
 parameters given on the command line, this option causes
@@ -839,6 +928,8 @@ A value of zero turns automatic reporting off.
 Send error messages and progress reports to
 .I efile
 instead of the standard error.
+(Note this option overlaps with "-e expr" above, so file paths
+with '=' or ':' in them are not allowed on this option.)
 .TP
 .BR \-w
 Boolean switch for warning messages.
@@ -849,7 +940,7 @@ rpict \-vp 10 5 3 \-vd 1 \-.5 0 scene.oct > scene.hdr
 .PP
 rpict \-S 1 \-o frame%02d.hdr scene.oct < keyframes.vf
 .PP
-To render ambient illuminance in photon mapping mode from a global photon 
+To render ambient irradiance in photon mapping mode from a global photon 
 map global.pm via one ambient bounce, and from a caustic photon map 
 caustic.pm:
 .IP "" .2i
@@ -875,4 +966,4 @@ option.
 Greg Ward
 .SH "SEE ALSO"
 getinfo(1), lookamb(1), mkpmap(1), oconv(1), pdfblur(1), pfilt(1), 
-pinterp(1), pmblur(1), printf(3), ra_rgbe(1), rad(1), rtrace(1), rvu(1)
+pinterp(1), pmblur(1), printf(3), ra_rgbe(1), rad(1), rpiece(1), rtpict(1), rtrace(1), rvu(1)