<prev [index] next>

RendView Manual -- Component Data Base

First of all, a word why it is named "component data base": This is because internally, the component data base (database) not only stores the render and filter descriptions but also knows about all available task (render and filter) drivers, task sources, task driver interfaces and image formats, i.e. main "components" of RendView.

For you as the user, most important are the render and filter descriptions (desc).
Note: There are render/filter drivers (like the POVRay driver which knows how to launch POVRay and the generic filter driver) and there are render/filter descs. Do not mix these up. A render desc is something e.g. saying that you have a renderer which can be driven by the POVRay driver and whose executable can be found at some location. Furthermore, you have a different desc for an old version of POVRay, etc.

Also note that the render and filter descs (including the additional command line args to be passed) are always local to the current machine. [To pass additional args to all clients, use the task source: -l-r-args.] The LDR server as well as each LDR client has its own list of render and filter descs. The reason is fairly clear: because installation and include paths for renderers and filters as well as the number of installed renderers/filtrs can vary between different LDR client machines.
The renderers and filters are identified by their name (the name of the desc). Thus, the name must always refer to the same renderer/filter on all LDR clients and the LDR server. I.e. if you name a filter sglow, then sglow must be the same filter on all LDR clients and the server. The server does not need to have the filter installed but it needs a desc if any client should apply it (specify a dummy binpath on the server side if not installed).

Specifying render and filter desc(ription)s

Render and filter descriptions are most easily specified via the filer renderers.par and filters.par. (Of course, you can name the files as you like.)
An example renderers.par file containing two render descs looks like that:
# renderers.par config file for RendView

searchpath = /usr/bin /usr/local/bin ./

*section povray3.1g
  driver = povray
  binpath = povray
  req_args+= -J
  inc_path= /usr/lib/povray/include
*end

*section "povray3.5"
  driver = povray
  binpath = /usr/src/povray/povray-3.5-build/src/povray
  stopsig = SIGSTOP
  req_args+= -J -display :0.0
  inc_path= /usr/src/povray/povray-3.5/include/ /usr/lib/povray/include
*end
(You already know that example from the quick start chapter.)
An example filters.par looks quite similar:
# filters.par config file for RendView

*include "/usr/local/lib/rendview/site-filters.par"

*section sglow
  driver = generic
  binpath = /opt/filters/secret/sglow
  req_args+= -glow-fact=0.177 -recurse=no "-mark=this is cool"
*end
Each desc has a name which is specified after the *section keywoard. It is probably a bad idea to use dashes in the name. Write povray3.1g instead of povray-3.1g. The reason is that the dash is a special separating character at command line parsing.

The above examples already describe all available parameters inside the descs:

driver=DRV
(REQUIRED) Specify the render/filter driver to use. Currently, only the povray render driver (capable of driving POVRay versions 3.1g and 3.5) as well as the generic filter driver (capable of driving all filters which read the image data from stdin and write the output to stdout) are available.
See also -list-rd (below) and the info about render/filter shell scripts on the taskmanager page.
binpath=PATH
(REQUIRED) This simply states where to find the binary executable for this renderer/filter. This is either an absolute path (beginning with "/") or a relaive path (not beginning with "/"). Absolute paths are taken as they are while relative paths are looked up in the searchpath (seee below).
stopsig=SIGNAL
The stop signal to use when (temporarily) stopping the task, i.e. SIGTSTP or SIGSTOP. Always keep the default SIGTSTP unless you must use SIGSTOP (e.g. for POVRay-3.50c which does not respond to SIGTSTP when not on terminal). Especially when using shell script renderers or filters, make sure to use SIGTSTP and have the script act correctly when catching SIGTSTP and SIGTERM. See this note for more info on shell scripts.
Note: Due to a bug in the param code, the stopsig spec in the desc file overrides the setting on the command line. Hence, never use stopsig on the command line unless the complete render desc is specified on the cmdline. (FIXME :)
req_args+=ARGLIST
Pass these additional arguments to the render/filter process. You can use quotes (") to enclose arguments containing spaces as done in the filter example. Alternatively, you can use the backslash to protect spaces. You must use the backslash to mask quotes and backslashes in case you want to pass those in the args.
inc_path=DIRLIST
This is only available for render descriptions and specifies a list of space-separated paths which are passed as include path to the renderer (e.g. using +L for POVRay).
Furthermore, there is one parameter which can be set once for all render descs and one for all filter descs (outside any *section):

searchpath=DIRLIST
Space-separated list of directories where to search for render/filter binaries without absolute path. The DIRLIST is searched left-to-right. Use ./ to include the current directory.
Note that you can include other files using the *include statement as shown in the filters.par example.

Options understood by the component data base

The component data base understands several options which can be split into three categories: Specifying desc files, specifying descs and querying info.

Querying info

The following options are available. All these options prevent RendView from running normally, i.e. it will exit after processing the command line arguments.

-version
Display the software version of this RendView binary.
-author
Display the author of RendView and a brief bug reporting information.
-license
Display the RendView license. This does not dump the complete GNU GPL, just refers to it.
-help
Well, this dumps a little help screen. You will note that the help text is colored on the console (pass -nocolor if you want to disable that). The help screen is automagically formatted in the width of the current terminal leading to nice indention.
As the help text is quite length, you can use -SECTION-help for most (but not all) sections, e.g. -l-help to just get info about parameters for the local task source.
-list-rd, -list-fd
Dump a list of all available render/filter drivers.
-list-imgfmt
Write out a list of known image formats (which can be specified as -l-oformat for the renderer and filter).
-list-opmode
Dump a list of supported operation modes (see also -opmode=).
-list-tsource, -list-tdriver
Dump a list of built-in task sources and driver interfaces, respectively.
-list-ri, -list-fi
Dump the render and filter descs (which were read in from file (renderers.par, filters.par) or command line) as used by RendView when running. Can be used to check things.

Specifying desc files

This was already mentioned in quick start. You will most likely have to pass one or both of these options:

-rdfile, -fdfile=FILE
Specify the complete path to the renderer and filter description files, respectively. Only one render/filter desc file can be specified but you can *include other files from inside the parameter files.
You do not have to specify these options because you can also specify the complete render/filter descs on the command line (see below). However, using these files often comes handy.
These options are probably best put into the environment var RENDVIEWARGS (see below).

Specifying descs on the command line

This is done very similar as when done in desc files. All parameters have the same name. Instead of specifying a *section, you simply prepend the desc name. An example illustrates that. The following cmd line would be equivalent to the povray3.1g desc in the renderers.par file above:
-ri-povray3.1g-driver=povray -ri-povray3.1g-binpath=povray -ri-povray3.1g-req_atgs+="-J" -ri-povray3.1g-inc_path=/usr/lib/povray/include
As you see it gets a bit unhandy...

However, there is an advanced command line section handler. It works as follows: use -SECT-{ and all following parameters will be considered in the section SECT. Use -} to end that again, for example, the povray3.5 in the renderers.par file above would look like:
-ri-povray3.5-{ -driver=povray -binpath=/usr/src/povray/povray-3.5-build/src/povray -req_args+="-J -display :0.0" -inc_path="/usr/src/povray/povray-3.5/include/ /usr/lib/povray/inc" -}
Note: Please make sure you leave spaces where you see them here. And please note the quotes used for the req_args and inc_path to protect the spaces from getting interpreted by the shell.

You can also use this method to pass several options for the local task source like
-l-{ -nframes=10 -f0=80 -size=160x120 -rd=povray3.1g -}

Using the environment vars

RendView understands three environment variables: RENDVIEWARGS, LDRSERVERARGS and LDRCLIENTARGS. Only one of these vars is read in upon program start, all the others are ignored. Which variable is read in depends solely on the binary name RendView is called. You may symlink/hardlink/copy the rendview binary giving it the alternative names ldrserver and ldrclient. Only these three names are recognized, all others default to normal rendview behavior. The binary name has two consequences:
The corresponding environment var is read in.
The corresponding operation mode is used (unless explicitly overridden using -opmode=).
Note that you cannot influence the used environment variable using the -opmode= parameter.

The environment vars simply hold parameters/"command line" options. They are read in just as if they were passed on the command line (but before the actual command line args to allow for overriding using the command line). (This is the reason why you will see negative arg numbers in errors concerning the passed arguments.)

You can use the env var as you like. It seems to be useful to pass the list of LDR clients (-Ld-clients), the -rdfile as well as the -fdfile and all other parameters which do not get changed frequently, using an env var. Note that it is legal to specify LDR clients even if you are in normal RendView or ldrclient operation mode -- they will simply be ignored. (Same is true for all other options.)
Then, you call RendView and only specify those options which you vary frequently.

 
<prev [index] next>
Last modified: 2008-02-11 21:06:41 Copyright © 2003 Wolfgang Wieser