gledimp - Gled for the impatient
This document covers four main topics:
Installing Gled: how to get and install Gled
Running Gled: how to run Gled and what you can do with it
Building Gled: how to build Gled from sources; CVS instructions
Extending Gled: how to create new libsets and write your own classes
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.
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.
gled_base_and_required_softwareThe full binary install contains all the libraries and executables needed
to run Gled as well as the demos. All you need to do is:
Get the current full base package: ftp://ftp.gled.org/current/binary-<BUILD>/gled_base_and_required_software.tar.gz
Untar it (it will unpack into gled-run directory) and cd into it.
( As ROOT is the largest package, a version without ROOT is also
available as gled_base_and_required_software_no_root. )
Initialize the environment: '. binenv.sh' or 'source binenv.csh'.
( If you took the no-root) package, fix the script so that $ROOTSYS
points to the ROOT instalation. )
Run: gled hello_gled.C
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.
gled_baseThe 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:
Get ftp://ftp.gled.org/current/binary-<BUILD>/gled_base.tar.gz and unpack it.
cd into gled-run/external and unpack the needed binary
packages. In this case get:
fltk-<VER>.tar.gz and fltk-mt-<VER>.tar.gz
from ftp://ftp.gled.org/current/required_software/binary-<BUILD>/ and extract them.
Fix binenv.[c]sh: correct the location of $ROOTSYS and if
DevIL is installed in a nonstandard location make sure that its
libraries are reachable by the dynamic linker (either via
/etc/ld.so.conf or LD_LIBRARY_PATH).
source this script (or initialize your environment
accordingly). Now you're ready to run:
gled hello_gled.C
Reading section Running Gled is recommended.
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
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.
Basic distribution of Gled depends on the following software:
ROOT. Homepage: http://root.cern.ch/ ; download:
http://root.cern.ch/root/Availability.html .
ROOT is released quite often and quite often, also, there is no
binary compatibility between patch releases. For development of
Gled the latest release is used, unless there are some
unresolved issues.
If you have your own ROOT and intend to use Gled binaries, make
sure that the versions of your ROOT and ROOT that Gled was
compiled with are the same. If you will be compiling Gled yourself,
then I believe it should work for any ROOT-3.x/y.
FLTK. Homepage: http://www.fltk.org/ ;
Gled uses FLTK v1.1 branch, usually the latest patch version.
If you want to build your own FLTK, use --enable-threads and
--enable-shared options to configure.
fltk-mt is a small library of widgets, partially collected from
fltk bazaar and partially written for Gled itself. You can get its
source from the required_software/ directory in Gled distribution:
ftp://ftp.gled.org/current/required_software/source/ .
DevIL (Developers Image Library)
Homepage: http://openil.sourceforge.net/ ;
This is the neatest image library I could find (and I've been
searching for a long time) and it handles image loading/saving as well
as transforming in a simple, GL-like manner.
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.
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.
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.
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
Gled GUIGled'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.
ROOT promptIn 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.
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.
The shell window displays object graphs. Each object can have two types of pointers to other objects:
Links are by default shown on the right hand-side of the shell and
can be expanded/collapsed by using the left collapsor box. A link is
in fact a named pointer. The link functionality is an extension of
standard tree structure that allows Gled to handle arbitrarily
complex object graphs.
Lists are collections of pointers to other objects. The right collapsor box will expand/collapse the list contents for a given object. This is the functionality you are used to from standard directory browsers.
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).
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.
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.
The following is a bootstrap procedure done in gled and
saturn executables.
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.
Start the GUI thread that manages all FLTK windows and eye's event-loop.
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.
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.
Unless -nomoons option is given, allow moon connections. This can
also be achieved later by calling
Gled::theOne->AllowMoonConnections().
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.
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.
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/ .
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
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.
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.
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.
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.
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.
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:
an already existing build directory of Gled
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):
./configure --reconf make
./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.
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.
Fully Gled enabled classes or glasses: instances of such classes
enter the object graphs of Gled and are capable of generating and
processing method invocation requests (MIRs). Further, they are
representable in Gled GUI and can spawn object views. Glasses can
have their own renderers that are used to render their representations
in 3D space.
Glasses must be subclassed from the ZGlass class and by default
reside in the Glasses directory. ZGlass itself inherits from
ROOT's base class TObject.
Fully ROOT enabled classes or stones can be streamed and
accessed from CINT. In Gled context they are used as data
containers for structures that can be data members of glasses (either
directly or via a pointer).
Stones must be subclassed from TObject and reside in the Stones
directory.
Other classes and namespaces. Sometimes you will need other
supporting structures, internal representations or functions and
wrappers for external libraries. In principle, you can place them
anywhere, but you should edit the Makefile accordingly. The
preferred place for namespaces that will be accessed by other libsets
is in <libset-name> directory. (The GledCore libset departs
from this convention and holds public namespaces in Gled and
GledView directories.)
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.
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.
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:
First own PreDraw is called (in fact ZNode::PreDraw, which sets
up transformation matrix), then PreDraw of mTexture (bind texture/enable
texturing).
Own Draw (just a rectangle with texture coordinates), then
PostDraw of mTexture (unbind texture / disable texturing).
Full render descent is made for all list members
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 detailsRnrBits 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.
RnrCtrl and RnrBitsRnrCtrl 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).