NAME

gledimp - Gled for the impatient

DESCRIPTION

This document covers four main topics:

As this is guide for the impatient, it is far from complete and none of the topics is covered in the necessary level of detail.

Installing Gled

Currently, Gled only compiles and runs on GNU/linux. In principle, it should be possible to make it run on any platform that has POSIX threads. gcc is the only supported compiler.

Distributions of Gled are available from ftp://ftp.gled.org/gled-<major>.<minor>.<patch>. The link current points to the latest release.

Gled is usually not installed in the usual sense of the word. It resides in its own directory and user's environment needs to be configured for its use (ROOT follows the same principle). This is good, when you need to have several versions of the same package lurking around and you don't want to burden yourself with messy un-installs (here rm is your friend).

The Gled system can be extended via libsets. Each libset is a combination of several libraries (base, GUI, GL rendering) and possibly also executables. The core of the Gled system itself is contained in the GledCore libset. The gled_base distribution contains four libsets: GledCore, Geom1, Numerica and GTS.

Each libset can depend on external software, some of which might not be widely available. To minimize the fuss, such software packages are available in binary format. You can download them separately, tar-balled in required_software_base package or as a part of full Gled binary distribution gled_base_and_required_software. If you want to build foreign software yourself, see Required software.

Full binary install: gled_base_and_required_software

The full binary install contains all the libraries and executables needed to run Gled as well as the demos. All you need to do is:

In short:

 b=x86-fc1-gcc3.3.2
 wget -q ftp://ftp.gled.org/current/binary-$b/gled_base_and_required_software.tar.gz
 tar xzf gled_base_and_required_software.tar.gz
 cd gled-base
 . binenv.sh
 gled hello_gled.C

Reading section Running Gled is recommended. Instructions for running demos are also there.

Partial binary install: gled_base

The partial binary install only provides binaries and libraries for Gled base libsets. It is your responsibility to provide proper versions of external software (all of it is also available from ftp://ftp.gled.org/current/required_software/) and to properly configure the environment. Sources are in source/ and binaries in binary-<BUILD>/ directory. The externally_built/ directory holds the packages, that were not rebuilt and originate from elsewhere (for v1.2 ROOT is the only package distributed this way).

For example, assume you already have ROOT and DevIL but would like to get binary versions of FLTK and fltk-mt:

Reading section Running Gled is recommended.

Installing additional libsets

All libsets are available as binary tarballs from ftp://ftp.gled.org/current/libsets/binary-<BUILD>/ directory. To install them, simply unpack them in the top-level Gled directory (the one that environment variable $GLEDSYS is set to).

In principle, you can install all libsets from scratch. In this case, you should first get and unpack the ftp://ftp.gled.org/current/environments/gled-run.tar.gz file.

Then you will need the GledCore libset (as it provides the gled executable and basic libraries) and any other libsets that you might want (see http://www.gled.org/libsets/ for a list). For example, the following script will get you the equivalent of what gled_base provides.

 wget -q ftp://ftp.gled.org/current/environments/gled-run.tar.gz
 tar xzf gled-run.tar.gz
 cd gled-run
 b=x86-rh7.3-gcc2.96
 for a in GledCore Geom1 Numerica ; do
   wget -q ftp://ftp.gled.org/current/libsets/binary-$b/$a.tar.gz
   wget -q ftp://ftp.gled.org/current/demos/$a.tar.gz
 done
 ls *.tar.gz | xargs -i tar xzf {}
 rm -rf *.tar.gz

Demos

Note that the gled_base distribution already contains demos for the base libsets.

Demos are available for each libset. The tarballs can be downloaded from ftp://ftp.gled.org/current/demos/<libset-name>.tar.gz. Each demo tarball unpacks into demos/<libset-name> and contains CINT macro scripts and possibly some data files. The location where you unpack them is irrelevant.

Required software

Basic distribution of Gled depends on the following software:

Running Gled

Gled has two main executables. gled is the standard one and spawns Gled native GUI (FLTK) while saturn has command-line interface only and is useful for pure servers and proxies.

Both will list their command-line options if started with -h switch:

 # prompt > saturn -h
 Arguments: [options] [dir] [file(s)]
                         dir   ~ cd to dir prior to exec of files
                         files ~ ROOT macro scripts to process
 Gled options:
 -------------
   -r[un]                spawn Saturn/Sun immediately (before processing files)
                         Saturn if -master is specified, Sun otherwise
   -nomoons              do not accept moon connections
   -s[ssize]     <num>   specify size of sun-space (can be eg. 2e20)
   -p[ort]       <num>   specify server port (def 9061)
   -m[aster] <host>[:<port>] master Saturn address (def port 9061)
   -n[ame]       <str>   name of Saturn
   -t[itle]      <str>   title of Saturn
   -l                    no splash info
   -norint               do not run TRint (useful for batch saturns)
 
 Authentication options:
   -noauth               do not use authentication
   -authdir      <str>   directory containing auth data (def ~/.gled/auth)
   -saturnid     <str>   identity of the Saturn (def 'sun.absolute' or 'saturn')
   -eyeid        <str>   default identity of Eyes (def 'guest')

But usually:

 gled -noauth my_scene.C eye.C # Start gled wo/ authentication,
			       # exec my_scene.C and a default viewer eye.C
 # or:
 gled sun.C scene1.C scene2.C ... eye.C

There is no rule as to what macros should contain, but before you start adding objects into the system, the server must be spawned, as in $GLEDSYS/macros/sun.C:

 if(Gled::theOne->GetSaturn() == 0) {
   Gled::theOne->SpawnSun();
 }

Gled's search path for macros is initially set to .:$HOME/.gled:$GLEDSYS/macros. Some standard macros are supplied with the distribution and reside in the $GLEDSYS/macros directory. Have a look.

To quit Gled, click on the Eat flaming death button in the main window or type .q on the ROOT prompt.

Setting-up the environment

If you downloaded the full binary packet, then the script binenv.sh (or binenv.csh) should do the job:

 cd <gled-top-dir>
 . binenv.sh	      # for sh-s
 source binenv.csh    # for csh-s

The scripts set the environment variables ROOTSYS and GLEDSYS and extend the PATH and LD_LIBRARY_PATH variables. They expect ROOT to be in external/root/ and all other external software to reside in external/. The current directory serves as the GLEDSYS.

 # This is environment for binary gled base distribution.
 # Use as: . binenv.sh
 # Should be run from top Gled directory
 
 dir=`pwd`
 
 export ROOTSYS=$dir/external/root
 export GLEDSYS=$dir
 
 # ROOT
 PATH=$PATH:$ROOTSYS/bin
 LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ROOTSYS/lib
 
 # External
 PATH=$PATH:$dir/external/bin
 LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$dir/external/lib
 MANPATH=$MANPATH:$dir/external/man
 
 # Gled
 PATH=$PATH:$GLEDSYS/bin
 LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$GLEDSYS/lib
 
 export PATH LD_LIBRARY_PATH MANPATH

Please modify the scripts to suit your needs.

Configuration of Gled

External configuration is only needed for authentication support. All other configuration can be done via command-line options and start-up scripts. See the $GLEDSYS/macros directory and the provided demos for examples.

Current implementation of the authentication procedure is based on the RSA public key cryptography and uses challenge-response authentication. All further communication `trusts' the accepted socket and is not encrypted. The authentication and group membership data are stored in a file-system directory structure. The root of the structure defaults to ENV{HOME}/.gled/auth, but can be changed with the -authdir command-line option (e.g. gled -authdir /etc/gled/auth). The keys are stored in the public_keys and private_keys directories with the individual filename being equal to the name of the identity it is representing. This means that if you want to allow user foo.bar@baz.org to login to the cluster, you must obtain his public key and copy it to the public_keys directory. Group membership information is stored in the groups directory. Each group is represented by a file (again, with the same name as the group) which is simply a new-line separated list of identities that are allowed to claim this group identity. By convention the group names begin with the @ character (e.g. @admin or @admin@baz.org).

To initialize the authentication system do:

 gled-auth-init -dir <auth-directory>
 # default -dir=~/.gled/auth

This will create the standard directory structure in the given directory and populate it with standard identities for servers, proxies and clients. To add additional identities use:

 gled-auth-genkeypair -name <some-user-name>

Use standard shell commands and editors to modify the authentication structures.

Running demos

All demos are available as CINT scripts. Note that Gled's search path for macros is initially set to .:$HOME/.gled:$GLEDSYS/macros and that other scripts can be called from within the scripts using the gROOT->Macro("sun.C"); syntax. From ROOT's prompt it can be executed simply by .x sun.C.

The hello_gled.C script contains instructions that startup the server, create some objects and open a viewer (a GUI shell and a GL window). The hello_gled.C is part of the gled-run package. If you installed Gled from source () it is not present.

Other demos (contained in demo/<libset-name> directories) also start the server (if it is not already started), but they DO NOT start the viewer. Therefore they should be run as:

 cd demo/<libset>
 gled <demo-name>.C eye.C

or even

 gled sun.C <demo-name>.C eye.C

In the last case the sun.C macro starts the server in advance.

Note that you might need the -nauth (to disable authentication) or -eyeid sun.absolute (to spawn GUI with the adminstrator privileges) if you want to edit the top-level objects.

To check for demo updates:

 cd demos/Geom1 # or just demos to update all libset-demos
 cvs update -d

The Gled GUI

Gled's GUI attempts to offer a generic representation of object graphs (GUI shell/browser) and moderate introspection into the functioning of the system itself (log viewer, direct access to cluster graph). At the same time ROOT's interactive prompt has been retained: it allows invoking of C/C++ calls directly. It plays the role of a start-up console, system monitor, debugger and execution environment for C/C++ scripts.

The following is a brief overview of command-line interface and GUI, that should get you going.

The terminal: ROOT prompt

In the terminal from which you launch gled, you will be presented with a command-line prompt of CINT, the C/C++ interpreter. This prompt in principle belongs to ROOT (whose event-loop is running in a separate thread), but as Gled's objects can be exported into (or created from) the context of the interpreter, it belongs also to Gled.

It really helps on this point if you are a bit familiar with ROOT. To run it's demos, do:

 cd $ROOTSYS/tutorials
 root demos.C demoshelp.C 

More detailed tutorials can be found at ROOT's homepage: http://root.cern.ch/.

Executing macros. As mentioned above, macros can be executed from the ROOT prompt using the .x <macro-name.C> syntax. Most macros from the macros/ and demos/ directories are plain scripts enclosed in curly braces. When such a script is executed, all variables declared in it (even in inner scopes ... for example, try with demos/Geom1/spheres.C) can still be referenced from the interpreter. You can clear interpreter's list of global variables by issuing gInterpreter->ResetGlobals().

If the file invoked by .x contains functions (i.e. has a proper C/C++ syntax), than the functions will be imported into the interpreter and the function with the name equal to that of the file will be executed. In this case you can also just import (load) the functions by doing .L <file-name>.

Importing objects from Gled. By right clicking on the name box in the object browser you can select the Export to CINT entry. You will be prompted for variable name under which the object will be exported to the interpreter.

Now you can in principle call any method on the Gled object. BUT if you are running a server with connected clients, those method calls will not be sent to clients. In this case the use of interpreter for direct manipulation of exported Gled objects is limited to server start-up. There is a way to properly post method invocation requests from CINT, but it is beyond the scope of this introduction.

Gled window

The main gled window contains basic controls for spawning eyes, loading libsets, setting of debug level and a prominent exit button. The reset of the window is a message browser, where output from different parts of Gled will accumulate.

Shell / Nest window

The shell window displays object graphs. Each object can have two types of pointers to other objects:

In default shell (the one spawned by macro eye.C or from GUI button) you get to the loaded scenes by list-expanding SunKing and then Scenes.

By double clicking on the name box of an object you get its full view: all auto generated widgets are stacked in separate window. Changing the values will send proper change requests to the server (then it gets back update notifications). Value fields can be click-dragged in manner of sliders (middle mouse moves by factor 10, right mouse by 100).

Selecting View->Link/Custom will toggle between display of links for a given object and a custom view of control widgets (such as you have in the full view). Some predefined views are available. You can edit the format string by selecting View->Edit Custom.

Drag-and-drop somewhat works. Dragging an object on the link-name-box sets the link. Dragging on the name-box in the graph (tree) browser appends the object as the last element in the list if the target of the drop operation is a ZList (Gled's list base-class).

Pupil (GL window)

To navigate in a GL window (pupil) use left/middle mouse buttons. Control key modifies behaviour and is really useful.

 left-drag          forward/backwards slide left/right
 ctrl-left-drag     slide up/down     slide left/right
 mid-drag           turn up/down      turn left/right
 ctrl-mid-drag      turn down/up      roll left/right (think pilot stick)
 <Home>		    return to the origin.

The pupil renders the conents of its PupilInfo. You can find active PupilInfo lenses (those that have an associated GL window) of a given shell by expanding ShellInfo's link Pupils. By opening full view of the PupilInfo object (named Example Pupil in the default shell) you can set up some rendering parameters.

Picking works (bound to right mouse button), but presently does very little. You can use it to view the render stack at render time of a given object or to spawn a GUI window allowing interaction with the object.

Two thing that is really missing is the ability to move/rotate objects directly from the pupil itself. This has been implemented in Gled-1.0 and was quite useful.

Connecting to a running Gled

To connect to an already running gled, use:

 gled -r -m <host-to-connect-to> moon.C

moon.C script will in principle just open the shell and a GL window on the first scene.

Once connected, you cannot reconnect to another saturn: quit gled and run a new one.

If the master dies (or closes socket), gled will die with an assertion failure. This should be fixed soon.

Gled Bootstrap

The following is a bootstrap procedure done in gled and saturn executables.

  1. Create Gled/GledGUI object (saturn/gled), parse command-line options. The Gled object is a singleton, accessible via Gled::theOne (or GledGUI::theOne) both from your compiled code and ROOT prompt/scripts.

  2. Start the GUI thread that manages all FLTK windows and eye's event-loop.

  3. If -r option is given, start-up the Saturn (server). Note that moons (clients) are not allowed to connect yet, while eyes are.

    In case of a moon (when -master <host> option is given), this step (call to function that starts server threads) will finish after ALL mandatory queens have been received from the master server. This means that the scripts (being executed on the next step) can rely on having client object-space set-up properly.

  4. TRint (ROOT's interactive application) processes macros given on the command line. Note that the server is not allowing moon connections yet and the scripts can freely create objects and attach them into the object graphs without worrying about the clients.

  5. Unless -nomoons option is given, allow moon connections. This can also be achieved later by calling Gled::theOne->AllowMoonConnections().

  6. Unless -norint option is given, run TRint in a dedicated thread. After that the command-line prompt is receiving input. This thread also runs all ROOT's X-windows (canvases containing histograms, ROOT browsers). FLTK and ROOT have different X displays.

Known issues

Sometimes Gled dies quite horribly. It's a very generic multi-threaded application which has not undergone rigorous testing. Besides, there are quite some things that can be done to gled to make it die. Be patient ... it will get better.

ROOT's interactive application (interface to CINT) that handles the terminal input pretends to be able to handle most of the signals (like SIGSEGV). This is not always true and there is a high probability that your terminal will lock up and you will not be able to kill gled in any other way than to kill it (as in killall gled). This can be `fixed' by adding gSystem->IgnoreSignal(kSigSegmentationViolation, true) somewhere in the initialization script or to your .rootrc or rootlogon.C file.

Building Gled

Getting sources, setting up the environment

To build Gled, you must get the gled-build package and sources of all desired libsets and their dependencies. Information about libsets can be found at http://www.gled.org/libsets/ .

Source tarballs

The source packages are available from ftp://ftp.gled.org/gled/current/libsets/source/ . To get the base sources, do:

 wget -q ftp://ftp.gled.org/current/environments/gled-build.tar.gz
 cd gled-build
 for a in GledCore Geom1 Numerica ; do
   wget -q ftp://ftp.gled.org/current/libsets/source/$a-src.tar.gz
 done
 ls *.tar.gz | xargs -i tar xzf {}
 # rm -rf *.tar.gz

CVS

 CVSROOT=":pserver:anonymous@cvs.gled.org:/mnt/data/cvs/gled-1.2"
 cvs login # empty password
 cvs co gled-build
 cd gled-build
 cvs co GledCore Numerica Geom1 # GTS
 # demos
 cvs co demos/GledCore demos/Geom1 demos/Numerica # demos/GTS

The repository can be browsed at http://www.gled.org/cgi-bin/viewcvs.cgi.

External software and environment

The development files of required external software must be available. All binary versions of external software provided on ftp://ftp.gled.org/current/required_software/binary-<BUILD>/ are in fact developers packages, i.e. they also contain the relevant header files. If you have downloaded the base external binaries, you can sym-link the external/ directory from that installation here. In this case, you can also use the binenv.(c)sh script.

Anyway, the build environment is exactly the same as the run-time environment. So the environment set-up can be done as described in the section Setting-up the environment. The configure script produces the environment set-up scripts build_env.sh and build_env.csh which can be used to easily access an existing Gled build.

Configuring

First edit the build_libsets file. It must contain names of all libsets to be built. The base distribution contains GledCore, Geom1 and Numerica libsets. Source tarball of a libset unpacks into <libset-name>/ directory.

The command-line options for configure script and their default values are stored in the configure.rc file. You can edit the file or use command-line options. Options can be given as --<opt1>=<val1> or -<opt1> <val1>, option names can be abbreviated.

The most relevant options are (see configure.rc for full listing and default values):

-ucpp <str>: user cpp-flags (e.g. -D_SOMETHING_),

-ucxx <str>: user cxx-flags,

-uld <str>: user ld-flags,

-debug: implies -DDEBUG and -g (otherwise -O),

-libsets <auto> | <auto-prompt> | <file:[filename]> | [libset1:libset2...]: libsets to build. The default is <auto-prompt> which scans the directory, displays the list of found libsets and asks for confirmation.

-external <search-path>: search-path is a ':' separated list of directories to include/link from; each dir implies -I<dir>/include and -L<dir>/lib,

-base <search-path>: search-path is a ':' separated list of existing Gled build directories in which build has been completed. configure will resolve dependencies of local libsets by trying to locate the missing libsets in base directories.

Now run ./configure <whatever options you need>. configure creates a file build_config which contains a perl-data-dump of two hashes holding information needed for compilation of libsets. Dependencies are resolved, so the order of compilation is determined properly even if build_libsets file contains them in a wrong order.

The configure script also creates all auto-generated files and runs make depend in all lib-set directories.

Building

In principle, just run make.

The default target builds all libraries and executables and installs them into $GLEDSYS/lib and bin directories.

Make process uses the default compiler. Export the CXX variable if you want to use some other compiler.

Extending Gled

In principle, Gled should be extended by creating new libsets. However, the Gled project is young and many indispensable classes are missing from the base release. See http://www.gled.org/status/ and http://www.gled.org/contributing/ for details on development status/plans and other information for developers/contributors.

Creating a libset

To create a libset directory, you can use the gled-create-libset script. You need to decide on the libset's name and select an unused library id (unsigned int; it can be trivially changed so you don't need to worry). Then you need a build directory. This can either be:

  1. an already existing build directory of Gled

  2. a new directory where this libset will be compiled and an existing build of Gled will be used to satisfy the libset dependencies. The configure script has a -base option which specifies the location(s) of existing builds.

     wget -q ftp://ftp.gled.org/current/environments/gled-build.tar.gz
     tar xzf gled-build.tar.gz
     # mv gled-build some-dir

    or if you're using cvs:

     cvs co gled-build
     # mv gled-build some-dir

In any case, all libsets that the new libset will depend upon and their dependencies must be available (all libsets depend on GledCore). Also, you need to set-up the environment.

To create a libset FooSet with id 101, use

 gled-create-libset FooSet 101

This will create directory FooSet containing all standard directories and files. Edit the Makefile and add all libset dependencies of FooSet to REQUIRES_LIB_SETS line near the beginning. If your libset will not contain any executables and does not depend on any external libraries, this is all you will ever need to do. Otherwise see GledCore::Makefile for an example of building executables and Geom1::Makefile for an example of linking against additional libraries.

Another important file is glass.list in the libset directory: this is a simple catalog of all Gled classes (or glasses) in this libset. Initially it is empty (containing some commented examples from GledCore).

Another thing to do is to edit build_libsets in the top build directory and append FooSet to the list.

Now you can run, depending of your build directory (enumeration as above):

  1.  ./configure --reconf
     make
  2.  ./configure --external=<paths-to-ext-soft> --base=<paths-to-base-installs>
     make

but this will produce libset FooSet with glue code only. Creation of classes is described in the next section.

Adding classes to a libset

Classes making up a libset can be divided into several categories, depending on the role they play in the Gled system. For clarity, as well as to simplify the build process, the files (header and implementation) for each category are placed in a separate directory.

Adding glasses

To get a skeleton code of a glass cd to libset directory and type:

 gled-create-glass -class <new-glass-name> -base <base-glass-name>

There are quite some conventions that a glass header file should conform to. The basic ones are fulfilled automatically by the above script.

Edit the glass.list file and add a line describing the new glass. Then you will almost certainly add some member data and methods. You should follow the ROOT convention for basic types: it assures interoperability of different architectures (int ~ Int_t, unsigned short ~ UShort_t etc.). Examples will be most fruitful ... so take a look at some glasses from the base distribution (Geom1/SMorph can serve you well).

Header files of glasses are parsed by project7 parser / code generator. It creates Gled compliant Get/Set methods, wrappers for MIR creation and processing and a separate class named <glass-name>View which contains GUI code needed to manage widgets representing the glass.

Instructions for project7 are contained in comments directly following the declarations. The output is stored in two files: <glass-name>.h7 and <glass-name>.c7 which has to be included back in corresponding source file.

Comments have two parts, separated by the 7 character. The left part pertains to Gled mechanisms while the right one is constructor for a perl class that will generate the widget code (see GledCore/perllib/Gled_Widgets.pm). For the time being, there is a shortage of documentation: some is available at http://www.gled.org/docs/ but the code of existing glasses should also be inspected.

Data member example (Geom1/SMorph):

 Real_t        mSx;            // X{GS}  7 Value(-range=>[0,100, 1,100], -join=>1)

X{GS} ~ Xport{GS} generates Get/SetSx methods. The widget will be created by the Value perl class. 1/100 is the default step for drag operations. In full view the next widget will be possibly appended to the same line.

Link example (GledCore/ZNodeLink):

 ZGlass*       mGlass;         // X{GS} L{} RnrBits{0,4,0,0, 0,0,0,5}

X as above, but this is a link: L{}. RnrBits are explained below.

Method example (GledCore/Eventor):

 virtual void  Start();        // X{E} 7 MButt(-join=>1)

X{E} ~ generate MIR bindings and create a button that will send request for invocation of this method.

And from GledCore/ZList:

 virtual void Add(ZGlass* g);  // X{E} C{1}

Export as above, but this method has to be called with one context argument. From GUI shell up to two such arguments can be defined by setting Beta and Gamma links of the ShellInfo.

At the moment it is not possible to call methods that take non-glass arguments from the shell, but a simple extension is planned.

Stone members can have their specialized widgets. As an example see Geom1/SMorph::mColor declaration.

Header files are also parsed by rootcint, ROOT's class catalog and I/O method (Streamer) generator. By adding an ! on the first character of comment directly following the data member declaration, this member will not be stored/retrieved to/from the stream. Example from the ZGlass class:

 Bool_t     bMIRActive;	     //  X{GS} 7 BoolOut(-join=>1)
 Short_t    mRefCount;       //! X{G}  7 ValOut(-width=>4)

In this case, the mRefCount variable is not streamed. This is to be used for variables that store temporary data, have a local (per Saturn) meaning only or can be regenerated from other data.

Building. From the top build directory you should run ./configure --reconfig. This will regenerate glass catalogues on build level and on libset level. Now you can run make as usual.

Adding stones

To create a stone skeleton code do:

 gled-create-stone -c <class-name> -b <base-class>

in the libset directory. No special configuring should be necessary, but running:

 make pre_depend
 make depend

is still needed.

Header files of stones (as well as all other headers) can also be processed by project7, but only Get/Set methods will be generated for non-glasses. In pre_depend phase of build header files are scanned for lines like #include "some-name\.h7" and, if found, appropriate commands are executed and dependencies for the built dumped into make_p7.inc file.

Rendering classes

So far only OpenGL rendering is supported. Glass renderers are stored in Rnr/GL directory and should be named <glass-name>_GL_Rnr. To create a skeleton code type (do not postfix the GL_Rnr part):

 gled-create-rnr -class <glass-name> -base <rnr-base-glass>
 e.g.: gled-create-rnr -class SMorph -base ZNode

See examples of some rendering classes (note that some renderers are not optimised for speed yet).

Rendering of each glass is separated in three functions:

PreDraw: set-up of render data, pushing of some attributes, sometimes change of transformation matrix,

Draw: the actual drawing code,

PostDraw: clean-up after PreDraw.

Further, ZList descendants contain any number of children and any ZGlass descendant posses any number of links to other glasses. RnrDriver is quite general and each glass can be configured to invoke Draw methods of self, of list members, of links and of list members of glasses pointed to by links in a definite order. This information is encoded in GledViewNS::RnrCtrl and GledViewNS::RnrBits structures.

Each glass with its own renderer has a RnrCtrl declaration in comments at the top of the glass declaration. It contains the overall RnrBits for the glass. Each link has a separate collection of RnrBits. Let's decode this data for Geom1/Board glass which renders a textured rectangle:

 class Board : public ZNode { //     self     list members
			      //     render   render
   // 7777 RnrCtrl("true, 4, RnrBits(1,2,4,0, 0,0,0,3)")
   MAC_RNR_FRIENDS(Board);
 protected:
   ZImage*       mTexture;       // X{GS} L{} RnrBits{1,0,2,0, 0,0,0,0}

RnrBits constructor takes eight render levels, divided in two groups of four. The first group pertains to self-rendering (or rendering of object pointed to in case of a link) and the second group to list-member rendering.

The first three numbers tell on which levels to invoke PreDraw, Draw and PostDraw. The last one is for full descent: here render driver calls for full render of the object in question according to its own render bits. It usually doesn't make much sense to use both explicit and full rendering for a given class/link.

Rendering of Board will follow links and consists of four rendering levels:

  1. First own PreDraw is called (in fact ZNode::PreDraw, which sets up transformation matrix), then PreDraw of mTexture (bind texture/enable texturing).

  2. Own Draw (just a rectangle with texture coordinates), then PostDraw of mTexture (unbind texture / disable texturing).

  3. Full render descent is made for all list members

  4. Own PostDraw is called (again ZNode::PostDraw; pop transformation matrix).

As subclasses still render links of their descendants, it is important to inspect RnrBits of parent glasses before deciding on RnrCtrl for a new glass. There should be a general rule for setting RnrBits ... you're invited to join the rendering infrastructure discussion.

RnrBits details

RnrBits consist of two groups of four numbers. The first group tells RnrDriver on which levels to invoke object's own rendering functions: the first number is for PreDraw, the second for Draw and the third one for PostDraw. The fourth number is only relevant for links and specifies on which render level to perform a full renderer descent, that is to recursively descent into the rendering of the object pointed to by the link. (OK, you could also use this bit for top object rendering, but you would better limit the maximum render depth of the render driver before.)

The second group specifies the same information for ALL list members of this object (if it is a ZList descendant, otherwise these bits are ignored). At a given level all corresponding methods ( PreDraw/Draw/PostDraw/<full-descent>) will be invoked in list order. For links this information is relevant only if the link is referencing a ZList descendant. Then the link is dereferenced as a list and the corresponding methods are called for this list.

This last option was intended for complex renderer stat set-ups with pushing and popping of a collection of attributes stored in a list. For a GL example, imagine having a link to a list having elements for: a) setting render mode to wire-frame, b) changing lightning conditions, c) etc. Besides, this list could then easily be shared among several scene elements.

Future of RnrCtrl and RnrBits

RnrCtrl and RnrBits are now hard-coded in the class definition. The original idea was to allow setting of custom render bits for each object on GUI shell level. This is not yet implemented, although the base viewing classes (OptoStructs::*View) and whole rendering infrastructure is designed to allow an easy implementation.

This was to be combined with the option of adding local links to object entries in the GUI shell (these links are only visible by shell user and renderers). By setting those links to render state modification objects/lists a full local control over renderer state could be achieved.

Another option that seems reasonable is to store RnrCtrl/RnrBits on lens level (via auto-generated link partners (e.g. ZNode* mParent; implies also RnrBits mParentRnrBits;) and a specialized GUI window for inspecting/setting rendering related information).