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.