--- ray/doc/man/man1/rpict.1	2015/02/24 19:39:26	1.18
+++ ray/doc/man/man1/rpict.1	2019/06/09 17:48:13	1.25
@@ -1,4 +1,4 @@
-.\" RCSid "$Id: rpict.1,v 1.18 2015/02/24 19:39:26 greg Exp $"
+.\" RCSid "$Id: rpict.1,v 1.25 2019/06/09 17:48:13 rschregle Exp $"
 .TH RPICT 1 2/26/99 RADIANCE
 .SH NAME
 rpict - generate a RADIANCE picture
@@ -408,14 +408,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
@@ -540,7 +540,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 +559,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 +662,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
@@ -875,5 +910,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)