Manual page for netrender(1)

netrender   -   render a frame using one or more remote servers

SYNOPSIS

netrender [ options ] ribfile [ribfile ...]

DESCRIPTION

netrender is a program that passes a sequence of RenderMan Interface Bytestream (RIB) requests to one or more prman processes launched by Network RenderMan render servers. The locally-launched netrender program can supply all local RenderMan shaders and textures to the remote prman process by reading the files locally and sending them over the netrender network connections; optionally, the prman processes can read these files directly from external file servers themselves to improve performance. All output (dspy) from the remote prman process(es) is routed back to the local netrender client and its dspysrvr process, thus output images are written or displayed on the client host.

A typical netrender invocation is:

netrender -h remote_host_name   ribfiles

OPTIONS

-version

Prints the netrender client/renderer version.

-h hostname[:N]

Specifies the computer hostname on which to find the nrm/alfserver. The -h option may be specified more than once to have the frame processed in parallel by several instances of the renderer, possibly distributed around the network. Each -h causes a new invocation or prman to occur, creating a new prman process, and consuming a prman license.

The optional processor count, e.g. -h hostname:4 requests multithreaded execution of the prman process on the named host. See the description of the prman -t option for a details on targetting multiple CPUs on one host. Note: multithreaded netrender currently also requires the "-F" option, see below. As usual with multithreaded renders, site-developed plug-ins must be thread-safe in this mode.

If the -h option is absent, the environment variable RENDERHOST will be queried for the hostname. If neither -h nor RENDERHOST specifies a host, then the netrender server on the local host (where netrender was invoked) will be used.

-f

Tells the remote renderer that it should attempt to open shader and texture files itself "directly" from the server host. For example, the files may actually be resident on the server by prior arrangement, or the files may be on some shared fileserver and are accessible with local-file semantics (e.g. NFS or mounted network drive). If the server fails to find a file locally, it defers back to the netrender client context to open and copy the file. The native network file system will usually be much higher performance than netrender's own simple point-to-point transfers, and furthermore will likely benefit from OS caching strategies. Note that RIB files are still transfered via netrender in this mode.

-F

This mode is similar to the "-f" option above, but it Forces the remote prman processes to perform direct i/o without fallback to netrender file transer. All files including RIB files are required to be accessible through "local" i/o mechanisms on the server, such network mounted filesystems on a fileserver. The emphasis here is on improving performance, and particularly avoiding the approximately serial transfer time of multi-gigabyte RIB files to each server through netrender's own simple protocol. The caller must arrange for the RIB file(s) and other assets to be network-accessible on all potential servers using the specified filenames.

The "-F" option is also currently required when doing multithreaded rendering on the remote servers. That is, the direct i/o mode is a prerequisite for multithreaded use of prman.

-crop xmin xmax ymin ymax

Defines a crop window, overriding the CropWindow specified via RIB.

-d dispType

Overrides the RIB Display type specified in the RIB file.

-cd path

Overrides the presumed current directory with *path*.

-R keyword

Sends the specified word (or quoted list of words) to the server for use in selecting a particular version of PRMan to run, or environment to establish. The keywords can be arbitrary, and are processed by a site-modifiable procedure in alfserver.ini on each server. Typically they are used to establish a site-defined environment prior to launching a particular version of the prman. For example: several shows may be in production at once, each locked down to a particular set of tools; the tools may all be accessible from each server, and this option allows a single alfserver to multiplex requests for frames from each show on a per-request basis.

-progress

Causes percent-done status to be written to the terminal. Each new status message uses carriage-return to overwrite the previous value. There is an alternate form, -Progress, which writes simple newline-delimited lines to the terminal; note that each remote server will generate their own percentage values based on their assigned work, and the processor index will precede each message.

-p port_number

Specifies the TCP network port number on which servers are expected to be listening for netrender connections. This value must be coordinated with the start-up parameters of the servers themselves. If -p is absent, netrender will call getservbyname asking for the port number for service "alfserver" and protocol "tcp". This may be set by a system adminstrator either in the local file /etc/services or through a directory service, such as NIS. If no port is found through getservbyname the port number will be set from the /nrmserver/port line in the rendermn.ini file. If no port number is found by any of these means, port 1500 will be used.

-T

Tells netrender to use the Tractor protocol, rather than Alfserver (equivalent to setting the environment variable NRM_TRACTOR=1).

-woff id,...

Suppresses the specified PRMan warning messages.

-rif plugin [-rifargs arg arg ... -rifend]

Execute the given rif plugin and arguments on the RIB stream while rendering.

MULTI-HOST vs MultithrEAD RENDERING

The interpretation of netrender's "-h host:N" option was changed for the 15.0 release, to clearly separate the number of requested servers from the degree of threading requested on each individual server. Previously, for example, "-h host -h host" and "-h host:2" were synonyms, sometimes causing two independent prman processes to be started, each working on a portion of the same frame. Furthermore, if the netrender "-F" option was also given, then both forms were (usually) coalesced into "prman -t:2" on the named host.

Now, each occurrence of "-h host" on the netrender command-line will always produce a separate prman process. Optionally, a suffix count may be added to each such hostname, like "-h host:4". This count will always be interpreted as a request for multiple rendering threads in that rendering process, targeting the given number of CPUs. The count will be passed as "prman -t:N" to the remote server. The special count "all", e.g. "-h host:all", can be used to request threads to fill all CPUs on that server.

When no count suffix is provided, the default prman multithreading behavior is still controlled by the /prman/nprocessors setting in rendermn.ini, and optionally in netrman.ini, on each server. The renderer defaults to using "one license worth" of CPUs per frame, or to the number of system-reported CPUs if that is smaller. The nprocessors setting provides a means to override the system-reported CPU count. Sites with prman plug-ins that are not thread-safe can set nprocessors to 1 to always force single-threaded behavior.

Note that the netrender option "-F" is still required to allow multithreaded prman to operate correctly with netrender. Without it, prman will be forced into single-threaded mode when launched via netrender.

ENVIRONMENT

The following environment variables are used (if set) by netrender:

RMANTREE	path to the base directory of the RenderMan software
		default: %RMAN%
RMANCONFIG	path to the configurations defaults file
			default: ${RMANTREE}/etc/rendermn.ini
RENDERHOST	name of default Network RenderMan server host

FILES

${RMANTREE}/etc/rendermn.ini	renderer configuration defaults file
${RMANTREE}/etc/netrman.ini	overrides for prman in netrender mode
${RMANTREE}/etc/messages	directory containing error message files
${RMANTREE}/etc/dspysrvr	RenderMan display server for image output
${RMANTREE}/lib/shaders		RenderMan standard shaders directory
${RMANTREE}/bin/alfserver	the netrender server executable
${RMANTREE}/etc/alfserver.ini	server configuration defaults file