RPIECE(1)                                                            RPIECE(1)



NNAAMMEE
       rpiece - render pieces of a RADIANCE picture

SSYYNNOOPPSSIISS
       rrppiieeccee  [  --vv ][ --xx xxrreess ][ --yy yyrreess ][ --XX xxddiivv ][ --YY yyddiivv ][ --FF||RR ssyynncc--
       ffiillee ][ --TT ttiimmeelliimm ] [ $$EEVVAARR ] [ @@ffiillee ] [ rpict options ]  --oo  ppiiccttuurree
       ooccttrreeee

DDEESSCCRRIIPPTTIIOONN
       _R_p_i_e_c_e  renders  a RADIANCE picture a piece at a time, calling _r_p_i_c_t_(_1_)
       to do the actual work.  This is useful for running multiple _r_p_i_c_t  pro-
       cesses  on  cooperating machines to render a single picture, which is a
       shared file specified with the _-_o option.  The overall  picture  dimen-
       sions will be _x_r_e_s by _y_r_e_s (or smaller, depending on the _-_p_a option and
       other view options), and the picture will be rendered in _x_d_i_v  by  _y_d_i_v
       pieces.

       There are two basic methods for telling _r_p_i_e_c_e which piece(s) of a pic-
       ture to render.  The explicit method is to write on the standard  input
       the _X and _Y position of the desired piece(s), where _X runs from zero to
       _x_d_i_v_-_1 and _Y runs from zero to _y_d_i_v_-_1_.  (The lower left piece of a pic-
       ture corresponds to (0,0) in this system.)  Alternatively, the implicit
       specification method uses a synchronization  file  to  determine  which
       piece  is  to be rendered next.  Specified with the _-_F option, _s_y_n_c_f_i_l_e
       initially contains the values for _x_d_i_v and  _y_d_i_v_,  so  the  _-_X  and  _-_Y
       options  are unnecessary.  (However, they are used if _s_y_n_c_f_i_l_e does not
       exist.)  The first _r_p_i_e_c_e process puts a lock on _s_y_n_c_f_i_l_e and  modifies
       its  contents before starting work on the first piece of the image.  It
       writes the _X and _Y position of the piece it will work on, so  the  next
       _r_p_i_e_c_e  process to modify _s_y_n_c_f_i_l_e will start on the next piece.  (When
       it finishes with its piece, it appends the index to the  end  of  _s_y_n_c_-
       _f_i_l_e_._)   This  procedure  continues  until  all the pieces are done, at
       which point all of the _r_p_i_e_c_e processes will terminate.

       The _-_R option may be used instead of _-_F if some of the pieces were  not
       properly  finished  by  previous  (killed) runs of _r_p_i_e_c_e_.  This option
       should be used by at most one _r_p_i_e_c_e process,  which  must  be  started
       first and with _n_o _o_t_h_e_r _r_p_i_e_c_e _p_r_o_c_e_s_s_e_s _r_u_n_n_i_n_g or else it will reren-
       der the same pieces other  processes  have  begun.   Once  the  recover
       process  is  started, you may start other _r_p_i_e_c_e processes using the _-_F
       option to run simultaneously.  If some processes die during  execution,
       leaving one or more half-finished pieces in the picture even though the
       other processes think the work is done, you may  run  a  single  _r_p_i_e_c_e
       with the _-_R option by itself to repair the holes.

       The _-_v flag switches on verbose mode, where _r_p_i_e_c_e reports to the stan-
       dard output after each piece begins and after each piece is finished.

       Options may be given on the command line and/or read from the  environ-
       ment and/or read from a file.  A command argument beginning with a dol-
       lar sign ('$') is immediately replaced by the  contents  of  the  given
       environment  variable.   A  command  argument beginning with an at sign
       ('@') is immediately replaced by the contents of the given file.

EEXXAAMMPPLLEE
       First _r_p_i_e_c_e process is started on the machine "goober":

         goober% echo 1 8 > syncfile
         goober% echo -F syncfile -x 1024 -y 1024 -vf view -o picture octree >
         args
         goober% rpiece @args &

       Second _r_p_i_e_c_e processes is started on the machine "sucker":

         sucker% rpiece @args &

NNOOTTEESS
       Due  to  NFS  file  buffering,  the network lock manager is employed to
       guarantee consistency in the output file  even  though  non-overlapping
       writes  are  used.   This would tend to slow the process down if _r_p_i_e_c_e
       were to wait for this I/O to  complete  before  starting  on  the  next
       piece,  so  _r_p_i_e_c_e  forks separate processes to hang around waiting for
       I/O completion.  The number of processes thus designated is set by  the
       MAXFORK  macro in the program (compiled in the src/util directory).  If
       the fork call is slow on a system, it may actually  be  better  to  set
       MAXFORK  to  zero.   In other cases, the network lock manager may be so
       slow that this value should be increased to get the best utilization.

       The output picture is not run-length encoded, and can be  quite  large.
       The  approximate size (in kilobytes) can be computed by the simple for-
       mula:

         filesize = xres*yres/256

       Make sure that there is enough space on  the  filesystem  to  hold  the
       entire  picture  before  beginning.   Once the picture is finished, the
       _r_a___r_g_b_e_(_1_) program with the -r option may  be  used  to  convert  to  a
       run-length   encoded  picture  for  more  efficient  storage,  although
       _p_f_i_l_t_(_1_) or any of the other Radiance picture filters will do the  same
       thing.

       The  ALRM  signal may be used to gracefully terminate an _r_p_i_e_c_e process
       after it finishes the current piece.  This permits other currently run-
       ning  or  subsequently started _r_p_i_e_c_e process(es) to continue rendering
       the picture without loss.  The _-_T option will send the ALRM  signal  to
       _r_p_i_e_c_e after the specified number of (decimal) hours.  This is the best
       way to force a time limit on the computation,  since  information  will
       not  be  lost, though the process may continue for some time afterwards
       to finish its current piece.

BBUUGGSS
       This program may not work on some systems whose  NFS  lock  manager  is
       unreliable.  In particular, some System V derivative UNIX systems often
       have problems with the network lock manager.  If the output  is  scram-
       bled or rpict aborts with some ambient file related problem, you should
       just remove the ambient file and go back to normal rendering.

AAUUTTHHOORR
       Greg Ward

SSEEEE AALLSSOO
       getinfo(1), pfilt(1), ra_rgbe(1), rpict(1), ximage(1)



RADIANCE                            10/1/98                          RPIECE(1)
