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.

At the same time, this document is written by an impatient man: it temporarily replaces a better organized and more detailed documentation for users and developers.


Installing Gled

Currently, Gled only compiles and runs on linux.

Distributions of Gled are available from ftp://ftp.gled.org/ gled-<major>.<minor>.<patch> . The link current should point 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, rendering) and possibly also executables. The core of the Gled system itself is contained in the GledCore libset. The Gled-base distribution contains three libsets: GledCore, Geom1 and Numerica.

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 external-base package or as a part of full Gled binary distribution gled-base-full. If you want to build foreign software yourself, see External software.

External packages of other libsets (not part of base) are not packed in the common tarballs.

Binary packages are available for the following platforms:

  1. rh7.3-gcc2.96 -- RedHat 7.3 with gcc 2.96. Should work on most linux distributions, but to my experience not on Debian Sarge.

  2. rh9-gcc3.2 -- RedHat 9 with gcc 3.2

  3. sarge-gcc3.2 -- Debian Sarge with gcc 3.2

For all of them ROOT-3.05.05 was used.

Full binary install: gled-base-full

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

In short:

 wget -q ftp://ftp.gled.org/current/packs/gled-base-full-rh7.3-gcc2.96.tar.gz
 tar xzf gled-base-full-rh7.3-gcc2.96.tar.gz
 cd gled-base
 . binenv.sh
 gled hello_gled.C

Reading section Running Gled is recommended.

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/external/ ) and to properly configure the environment. Sources are in src/ and binaries in dist/ directory. prebuilt/ holds the packages, that were not rebuilt and originate from elsewhere (for v1.2.0 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/dist 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/internal/gled-run.tar.gz file (warning: it has no common root directory, so create a directory and cd into it prior to unpacking).

Then you will most certainly need the GledCore libset. For example, the following script will get you the equivalent of what gled-base provides for rh7.3-gcc2.96:

 mkdir gled-base; cd gled-base
 wget -q ftp://ftp.gled.org/current/internal/gled-run.tar.gz
 for a in GledCore Geom1 Numerica ; do
   wget -q ftp://ftp.gled.org/current/libsets/dist/$a-rh7.3-gcc2.96.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 tar unpacks into demos/<libset-name> and contains CINT macro scripts and possibly some data files. The location where you unpack them is irrelevant.

External 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.

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

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.

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 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.

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 nothing. You can use it to view the render stack at render time of a given object.

Two things that are really missing are the possibility of attaching the camera to a given object and the ability to move/rotate objects directly from the pupil. This has been implemented in Gled-1.0 and is high on the todo list.

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 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/src/ . To get the base sources, do:

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

CVS

 CVSROOT=":pserver:anonymous@cvs.gled.org:/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/external/dist/ 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 Installing Gled.

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:

-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),

-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 ./mecca.

mecca is a sub-make executor. Use mecca -t <target> to invoke non-default target (say clean, distclean, etc). 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 for every build 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.
     mkdir new-dir; cd new-dir
     wget -q ftp://ftp.gled.org/current/internal/gled-build.tar.gz
     tar xzf gled-build.tar.gz

    or if you're using cvs:

     cvs co gled-build
     # mv gled-build new-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
     ./mecca
  2.  ./configure --external=<paths-to-ext-soft> --base=<paths-to-base-installs>
     ./mecca

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 ./mecca as usually.

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).