Basics

The framework consists of several base libraries with the prefix cgv, a standard cgv_viewer and several plugins that can be loaded when starting the viewer by specifying them in the command line arguments. All plugin interfaces and the registration is handled by the cgv libraries.

The cgv libraries (dependencies) are

cgv_signal ... signal mechanism and binding of functions to signals
cgv_utils ... helps to work with files and text and has functionality to parse text
cgv_type (cgv_utils) ... standardized type declaration and type reflection support
cgv_reflect (cgv_utils/type) ... mechanism to reflect types in C++
cgv_data (cgv_utils/type) ... data management such as smart pointers and data views
cgv_base (cgv_reflect(data/type/utils) ... registration mechanism, communication and hierarchical structures
cgv_math (cgv_base/type/utils) ... large collection of mostly templated math functions and solvers
cgv_media (cgv_base/data/type/utils) ... support for fonts, images, video and 3D data
cgv_gui (cgv_media/base/data/type/utils) ... abstraction of gui
cgv_render (cgv_gui/media/base/data/type/utils) ... rendering support with OpenGL specialization
cgv_os ... basic operating system support (threads, sockets)

Deprecated is the cgv library that includes all of the above components in one library.

Supported Platforms

Currently the following system configurations are supported

Windows XP / Vista
- Microsoft Visual Studio
  - Visual Studio 2005 (abbreviated by vs8)
  - Visual Studio 2008 (abbreviated by vs9)
  - Visual Studio 2008 Express (abbreviated by vs9e)
  - Visual Studio 2010 (abbreviated by vs10)
  - Visual Studio 2013 (abbreviated by vs12)
  - Visual Studio 2015 (abbreviated by vs14)
  - Visual Studio 2017 (abbreviated by vs141)
  - Visual Studio 2019 (abbreviated by vs142)
  - Visual Studio 2022 (abbreviated by vs143)
- CMake
Linux
- CMake

All compilers can be used at the same time. When using the PPP build system under Windows, the postfix "_8", "_9", "_9e", "_10", "_12", "_14", "_141", "_142", "_143" is used for applications and libraries to distinguish the versions. For example "cgv_viewer_12.exe" loads "cgv_12.dll" and "cgv_viewer_14.exe" loads "cgv_14.dll" on startup.

Configurations

For building libraries, plugins, and applications there are four configurations, which are distinguished by extending the compiler postfix. In the following list the cgv internal name of the configuration is given followed by configuration name in vs14 and the full name of the cgv dll with all postfixes that are used in the same way for all other libraries and applications

shared release (Release Dll) cgv_14.dll
shared debug (Debug Dll) cgv_d14.dll
static release (Release) cgv_s14.dll
static debug (Debug) cgv_ds14.dll

The build system also allows to build an executable from a plugin which is then typed application_plugin. In this case there are two more build configurations "Release Exe" and "Debug Exe", which both build a statically linked executable. The project of an application_plugin must have an application - typically the cgv_viewer - as dependent project. The source files of the dependent application project are added to the project of the application_plugin and built only in the "Exe"-configurations.

Plugins

A plugin can register instances or factories of newly implemented classes. The new classes are derived from interface class declared in the cgv libraries as for example cgv::render::drawable. Registration is typically done in the constructor of a static dummy variable of special template types that do nothing else but register an object or a factory. When the plugin is compiled to a dll the registration code is executed when the dll is loaded.

Directory Tree

The framework is provided through https://github.com/sgumhold/cgv.git. Use the master branch by default. The framework consists of the following tree of sub directories:

3rd ... 3rd party libraries conditioned for the cgv framework currently including ANN, fltk, glew, jpeg, png, pthread (deprecated), tiff, openvr, webserver, zlib.
apps ... applications currently including the cgv_viewer
tool ... different tools necessary for compilation: res_prep (conversion of resource files into source files), ppp_tool (preprocessing of header files and makefile generation), shader_test (compilation of shader codes and programs), display (tool to adjust display settings - Windows only)
bin ... binaries and scripts (ppp, generate_makefile)
cgv ... set of core libraries
- base ... basic class hierarchy, support for plugin framework, basic communication classes for signals and rebinding of functions
- config ... configuration for ppp and different platforms
- data ... data management like ref_ptr and formated data
- defines ... basic helpers for macro programming
- gui ... abstracted gui framework based on a driver concept. Currently, only a fltk driver is available in the plugin cg_fltk.
- math ... template classes for math, mostly linear algebra
- media ... support for different media types
  - font ... interface for font server and font faces (use gui plugin like cg_fltk)
  - image ... interfaces and driver plugin mechanism for image reader and writer with bmp support (use the cmi_io plugin)
  - illum ... light source and material data structures
  - mesh ... simple mesh data structure for static and streaming meshes, marching cubes, dual contouring, obj reader
  - video ... interfaces and driver plugin mechanism for video reader and writer (use the cmv_avi plugin under windows)
- os ... support for threads, mutexes, system clipboard, display, sockets and simple webserver
- reflect ... simple to use self reflection mechanism (use library cgv/libs/cgv_reflect_types for implementation of self for most important types defined in cgv core libraries)
- render ... abstracted interface for GPU programming (use with library cgv/libs/cgv_gl for OpenGL implementation of interfaces)
- signal ... signal mechanism and binding of functions to signals
- type ... support for compile time information about types
- utils ... utility functions for handling files, processing text, bit operations, simple progression on the console, stop watch and incremental statistics computation
doc ... source for related pages of documentation
make ... makefiles, currently support for cmake and different versions of visual studio via the built in ppp build chain
libs
- ann_wrapper ... C++-wrapper to ann library
- cgv_gl ... implementation of interfaces in cgv_render for OpenGL
- cgv_reflect_types ... implementation of type reflection according to cgv_reflect for most important types of cgv core libraries
- cgv_win32 .. preliminary implementation of some windows specific gui features
- delaunay ... template based implementation of point insertion algorithm for computation of delaunay triangulations
- glsu ... support library to set up stereo renderung
- multi_mouse ... support to access several mouse devices in parallel (windows only)
- plot ... library to draw plots of 1D and 2D functions
- ppp ... script engine used for ppp source and makefile file processing tool
- gamepad ... library to access gamepad devices
- cg_gamepad ... library that provides a gamepad_server that emits events from gamepad devices
- space_pilot ... library to access space pilot devices
- vr ... basic vr support without further dependencies
- cg_vr ... library that provides a vr_server that emits events from vr devices
plugins ... commonly used plugins
- cg_fltk ... plugin that implements the abstract gui framework
- cg_icons ... icon resources
- cg_multi_mouse ... adds multi-mouse events to handle cg_fltk gui
- cmi_io ... support for image io
- cmv_avi ... support for video io through avi files
- crg_view ... provides mouse interaction for the opengl view in the cgv_viewer
- crg_planar_view ... variant of crg_view where only 2d navigation is possible
- crg_spherical_view ... variant of crg_view with a spherical coordinate system
- crg_stereo_view ... provides mouse interaction for a stereoscopic opengl view
- crg_grid ... renders a grid
- crg_antialias ... supports jitter based antialiasing
- crg_depth_of_field ... supports rendering with depth of field
- crg_light ... provides gui to adjust light sources
- examples ... different example classes that illustrate the cgv framework
- openvr_driver ... openvr api driver for the vr library
- vr_emulator ... plugin that provides vr_kit emulation
- crg_vr_view ... extends crg_stereo_view with support to render to vr_kit hmds
- vr_test ... sample plugin that shows how to use vr kits
test ... test sources for different parts of the framework that also serve as examples

Usage of the cgv_viewer

The cgv_viewer can load plugins after start up. It parses the command line arguments with the help of the function cgv::base::process_command_line_args declared in the header cgv/base/register.h. This function simply calls the cgv::base::process_command function for each argument. The command syntax is explained in the documentation of this function.

A plugin can register objects, object factories and registration listeners. Object and factory registration events are delayed until all plugins have been read. Then all registration events are sent to all registered listeners, such that the order in which the plugins are read is not important.

After startup the viewer provides a main menu that can be extended by the plugins, a 3d view and a tab group with guis for registered object instances, which is only shown if there is at least one registered object instance that provides a gui.

In the main menu the item "new" is meant for entries of factories that create new object instances. A factory can be tagged singleton, in which case only one instance can be created. There is also a shortcut assigned to each factory, for example <Ctrl-Q>. If pressed, a new object instance is created. In case of a singleton factory, pressing the shortcut again will toggle visibility of the object instance in the 3d view and select its gui in the tab group of guis.

Configuration Files

The registration facility and the property interface of the cgv framework as described on page Namespace cgv::base is exploited to support configuration files. A configuration file is passed to the viewer with the command syntax config:"file_name". The use of quotes is important when the file path contains spaces. To add the config command line argument in a project file use the addCommandLineArgs define (see Internal Makefiles (Windows only)).

Config files are user specific and should therefore not be checked into the svn repository. Therefore, a twofold strategy is realized based on a default config file and a user specific. The default file is checked into the svn repository and has the extension ".def". It will be specified in -c config:-commands to the viewer and is always available from the svn repository. The user can copy the default file into a file with the same name but the extension ".cfg" and specify his user specific configuration there. The viewer will first check for the existence of the ".cfg" file and if present read this instead of the default file.

The syntax of the config file is very simple. Lines that start with a '/' are comments. Empty lines are ignored. Lines that contain configuration information are processed with the cgv::base::process_command function. Let us explain the most important commands with a simple example config file

/ this is a comment
show all
 
name(cgv 3d viewer):x=4;y=30;w=1024;h=768
type(graphical_text_interpreter):x=1032;y=30;w=592;h=768
name(gti):file_name="D:\Projects\project\gti\examples\examples.dcr"
 
persistent
name(stereo interactor):view_dir_x=?;view_dir_y=?;view_dir_z=?
 
initial
name(stereo interactor):extent=2

There are two possibilities to address registered objects in a config file:

by name ... with the syntax name(gti) followed by a colon. This is supported only for objects derived from cgv::base::named and the name is matches against cgv::base::named::get_name().
by type ... with the syntax type(graphical_text_interpreter) followed by a colon. This makes sense only for singleton objects. The type is matched against cgv::base::base::get_type_name(). The rest of each line after the colon, a semicolon separated list of member assignments follows. This is passed to the cgv::base::base::multi_set() method. Strings can be enclosed with single or double quotes. If a quote is part of the string, one can use the backslash as escape character. A backslash is either referenced by a double backslash inside a quoted string or if not followed by the enclosing quote symbol, also by a single backslash - as for example in the file name assignment in the above sample.

There are two modes to set members of registered objects in the config file:

initial ... the value is set once when the config file is read
persistent ... the value is set when the config file is read and the config file is updated whenever the value is changed. This allows to make the current values of selected members persistent over several runs of the application. Only members that are reflected inside the cgv::base::self_reflect method are supported for persistent configuration. At the beginning of a config file the default mode is initial. The special config file lines persistent and initial change the mode for the successive entries of the config file. When a member is configured persistently and the question mark ? is assigned to a member, the initial value set by the application is kept and written to the config file after the first run of the application.

The line "show all" is a special command that will cause the viewer to print out all registered objects and their properties to the console window. In this way one can find out all objects that can be configured.