GCGlib  0.04.228
GCG Graphics Engine
GCGlib Documentation

General information

Marcelo Bernardes Vieira, Tássio Knop de Castro, Eder de Almeida Perez, Daniel Madeira, Patrícia Pereira Pampanelli, Virgínia Fernandes Mota, Thales Luis Rodrigues Sabino, José Luiz Souza Filho, Dhiego Cristiano Oliveira da Silva Sad, João Vitor de Sá Hauck, Pedro Henrique Fialho, Thiago de Oliveira Quinelato, Luiz Maurílio Maciel, Luciano Walenty Xavier Cejnog, Fernando Akio Yamada, Liliane Rodrigues de Almeida.
Make sure you have all dependencies in this documentation are installed to build or use GCGlib.
Careful destruction of object instances is recommended. Read documentation.
All class attributes may be read directly but must not be changed. Read documentation.


GCGlib cross-platform library concentrates all methods and algorithms developed by GCG researchers and students since 2007. It is a software repository intended to be used in all GCG projects and researches. Our library is also applied in the development of technological products for commercial and industrial purposes.

The library provides robust and reliable code for Linux and Microsoft Windows systems. For Linux, a Shared Object library is provided and runs in 32 bits and 64 bits platforms. Under Microsoft Windows, the GCGlib is provided as a DLL (Dynamic Linked Library) for MinGW using GNU C/C++. DLL libraries with 32 bits and 64 bits for Microsoft Studio Visual C/C++ are also available.

Most implemented algorithms are versions of well-known, public domain, methods. As GCGlib is being developed, algorithms can be adapted and enhanced to support our projects needs. Theoretical and technical knowledge in computer graphics, signal processing and computer vision is accumulated along this process. GCGlib includes functions and classes for:

  • 2D and 3D visualization
  • Subdivision schemes for adaptive surfaces
  • Geometry processing
  • Signal, video and image processing
  • Linear algebra
  • Camera and projector calibration
  • Physics simulation
  • Statistics and data analysis
  • Multithread management
  • Network communication

Using GCGlib library

GCGlib is deployed in a single library, along with the header gcg.h for developments, as a Shared Object (.so) in Linux and Dynamic Linked Library (.dll) in Windows. Potential users or developers are encouraged to download (www.gcg.ufjf.br) a package or installer containing GCGlib binaries and header, its examples and, for Windows systems, its dependencies. Packages for 32 bits and 64 bits are available for Windows (MSVC and MinGW versions) and Ubuntu Linux distributions.

In Windows, the dynamic library is a link free object. This means that no library must be linked to your project in order to satisfy GCGlib dependencies. In runtime, however, GCGlib depends upon several DLLs that must be installed in your system. All dependencies are provided to ease the task of GCGlib building. Some of them are automatically compiled along with GCGlib in Windows: jpeg library, glui (only for some examples). During GCGlib building, the CMake tool searches for dependencies like pthread, opengl, glu, and freeglut (only for some examples). If pthread or freeglut are not found, a binary copy of them are automatically copied to the GCGlib folder. If using MSVC compiler, it is mandatory to have a Windows SDK compatible with your platform installed. In summary, you must have installed (or put in the same directory of GCGlib) glu32.dll, pthreadGC2.dll (MinGW projects) or pthreadVC2.dll (Visual C++ projects). Other DLLs (opengl32.dll and glu32.dll for instance) are needed but they are usually distributed by default in Windows. Furthermore, for MinGW compilation, a specially designed vapiwin.dll is provided for video and camera interface.

The use of GCGlib in Linux is straightforward since all dependencies are easily obtained from package managers of most distributions. Most of them are installed by default when using GNU compilers (librt for example) or common applications. Make sure the proper development packages for glu, opengl and jpeg are available. For building and using one of the GCGlib examples, the freeglut and glui libraries are needed. Since Shared Objects are libraries that are linked upon execution, all you need is to keep dependencies updated.

Version compatibility

Versions of GCGlib have the form: major.minor.revision

 Original Version    New Version    Compatible?
  2.20.5              2.20.9         Yes      Compatibility across revision/patch versions is guaranteed.
  2.20.5              2.20.1         Yes      Compatibility across revision/patch versions is guaranteed.
  2.20.5              2.21.2         Possibly Compatibility with different minor versions is not guaranteed but is probable.
  2.20.5              3.0.0          No       Compatibility with different major versions is not guaranteed.

While some of the cells say "no", it is possible that the versions may be compatible, depending upon the particular functionalities used by the application.

Revision numbers are sequential. But the evolution of major and minor depends on how many or how much changes have occurred.

Building GCGlib library, its documentation and examples

GCGlib was developed using CMake tool to automate building, installation and packaging. These steps are handled without any supervision provided that all needed software and GCGlib dependencies are correctly configured.

The first step is to install CMake in your platform. After that, run

     cmake --help

to check the available generators. Install the C/C++ compiler or/and the IDE of your preference that matches one of the available generators. Some GCGlib features, like video capture for instance, will only work in Windows and Unix based systems. CMake will automatically find all libraries and software needed to build, install and pack GCGlib features: binaries, documentation and examples.

For correct version handling during compilation, you will need GIT client installed. This distributed version control tool retrieves the tags and logs from the GCGlib repository. CMake will search for GIT and, if it is not installed, the correct version numbers will not be inserted in the library, documentation and packages. We strongly recommend to install GIT and get the GCGlib sources from our online repository (see instructions below). Installing incorrect library versions can potentially lead to problems and instabilities.

In any platform, you should install Doxygen to automatically generate documentation. If Doxygen tool is not found while building, the HTML documentation quietly will not be generated.

In Windows, GCGlib can be compiled for MinGW and Visual C++. The Windows SDK is needed for MSVC compilers: install the version that best matches your platform and your MSVC version. Make sure that OpenGL and GLU development files are available (headers and linking libraries) in the expected folders (include and lib) of your compiler or SDK. You should install jpeglib and pthread for your compiler/platform but it is not mandatory. If jpeglib is not found, it is compiled (version 6b sources are available if needed) and linked to GCGlib quietly. Also, a generic version of pthread headers, libraries and binaries are provided with GCGlib sources. Its configuration is handled automatically by CMake. If you intend to build the examples, you also should install GLUI and GLUT. This is also not mandatory. The libglui is compiled if any example that includes it as dependency is built (i.e. its sources are available if needed) and the headers, libraries and binaries of freeglut are automatically included. If one of your purposes it to generate a GCGlib installer, you will need to install WIX (recommended) or NSIS software. They are naturally integrated to the CPack tool of CMake.

In Linux, all GCGlib dependencies are open-source and available in most distributions. You must install g++ and build-essential packages in most systems. Install the compatible libraries and development packages of: jpeg (libjpeg-dev), pthread (libpthread-stubs0-dev), glut (freeglut3, freeglut3-dev), glui (libglui-dev), opengl (binutils-gold, libglew-dev, mesa-common-dev) and glu (libglu1-mesa). Note that the package names, versions and dependencies vary among distributions. If you need to build using a specific compiler (MinGW 32 bits under a x86_64 system, for instance), check if the there are compatible packages for the target platform.

Download sources from GCGlib repository

GCGlib GIT repository is hosted at https://www.gcg.ufjf.br/git/gcglib. If you are using the command line for cloning, GIT will launch the default SSH password dialog (normally a graphical tool) for user authentication. To use the terminal to enter the password, first set SSH_ASKPASS empty as follows

     export SSH_ASKPASS=

The GCG website currently is not certified since it imply in costs. We however need encryption for obvious security reasons in our services, including GIT, which needs password transmissions. Trying to clone a repository directly will result in an verification error by the underlying OpenSSL. In order to use SSL protocol with a security certificate not issued by a "Certification Authority", execute the following command to disable the global SSL verification:

     export GIT_SSL_NO_VERIFY=true

Everything is ready to download the head version or, more specifically for GIT, to clone the repository with:

     git clone https://www.gcg.ufjf.br/git/gcglib


     git clone https://user_name@www.gcg.ufjf.br/git/gcglib

With the repository cloned, go inside one of its folders and execute the following command to disable SSL verification permanently for it:

     git config http.sslVerify false

This command allows push and pull operations over https protocol. GIT will use the SSL protocol for encrypted communication regardless the server certificate is trusted by "someone". Note that "Certification Authorities" have the role of making sure that someone is really who he says. GCG is not intended to get any user information except its username and password previously registered in our server. Thus, this is a safe site.

Configuring GCGlib with CMake

CMake tool generates targets in a two step process. The first one is to configure the generation tools. During configuration, the CMake cache is populated and makefiles (or IDE projects) are created by the execution of the scripts called CMakeLists.txt provided in the source tree. The user can change default options programmed into CMakeLists.txt scripts to control the makefile generation. The most important options for GCGlib are:

  • CMAKE_BUILD_TYPE: sets the preferable type of compilation as Release (optimized) or Debug (non-optimized and with debug symbols). Default value is Release.
  • CMAKE_INSTALL_PREFIX: sets the directory (relative or absolute) into which the target "install" will install GCGlib. The default folder is system dependent. In Windows, for example, it is automatically set to the C:/Program Files folder/. Useful for testing installation tree in a local directory.

CMake generates all makefiles, binaries and extra sources in the current directory. Consequently, you must execute CMake inside an empty folder (or previously used to configure with the same options). A common approach is to create a folder called "build" inside gcglib source folder (containing the topmost CMakeLists.txt). Execute the appropriate configuration command inside "gcglib/build/" folder passing the desired generator with the parameter -G "Generator Name". See CMake documentation for further explanations.

Some configuration examples varying the compiler name, the IDE project, 32 bits or 64 bits compiler, optimization or debug information, the destination folder for "install" target:

  • cmake ..
  • cmake .. -G "Unix Makefiles"
  • cmake .. -G "CodeBlocks - Unix Makefiles"
  • cmake .. -G "MinGW Makefiles"
  • cmake .. -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Debug
  • cmake .. -G "CodeBlocks - MinGW Makefiles"
  • cmake .. -G "Visual Studio 10 2010"
  • cmake .. -G "Visual Studio 10 2010 Win64"
  • cmake .. -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=./installfolder

Compiling GCGlib after configuration

Build example (after configuration):

  • cmake –build . –config Release
  • cmake –build . –config Debug

Install example (after configuration):

  • cmake –build . –config Release –target install

or (after building)

  • make install

Create package (after configuration):

  • cmake –build . –config Release –target package

or (after building)

  • cpack -C Release

GCGlib License - Graphics Engine

Copyright © 2007-2016 Group for Computer Graphics, Image and Vision - UFJF - Brazil.

Permission is hereby granted, free of charge, to any researcher, student, professor or collaborator, provided that is officially affiliated or in cooperation with the GCG, that obtain a copy of this software and associated documentation and example files (the "Software"), to deal in the Software for research or educational purposes except for commercial, industrial and other profit activity, without limitation to use, copy, modify and merge, subject to the following conditions:

  • The above copyright notice and this permission notice shall be fully included in all copies or substantial portions of the Software.
  • A complete citation to GCGlib version, GCG laboratory and to the website www.gcg.ufjf.br shall be included in all works, texts, pages, articles, reports, papers, websites, prototypes, books, dissertations, thesis, and all other types of public communications, published into any kind of media, printed or electronic, having part or all of its results or contents obtained using the Software.

GCGlib References, dependencies and trademarks

GCGlib is based in part on the following works, standard algorithms, publications, softwares and methods, whose authorship, copyrights and trademarks are exclusively owned by their respective authors and/or companies:

  • OpenGL: GCGlib uses the cross-platform OpenGL graphics library for real time rendering tasks.
  • Independent JPEG Group: this widely used free library is a Linux standard for JPEG image compression.
  • Pthreads Win32: it is a Windows version of the POSIX standard for multithread applications.
  • CMake: it is a cross-platform, open-source build system. CMake is a family of tools designed to build, test and package software. CMake was created by Kitware in response to the need for a powerful, cross-platform build environment for open-source projects such as ITK and VTK.
  • NSIS: (Nullsoft Scriptable Install System) is a professional open source system to create Windows installers. It is integrated to CMake/CPack.
  • WiX: It is a toolset to make Windows installers. It is integrated to CMake/CPack.
  • MinGW: forms an environment for developing and deploying native Microsoft Windows applications.
  • Numerical Recipes: a few numerical functions of GCGlib are adaptations of some of the methods presented in this complete and useful book family.
  • M. Matsumoto & T. Nishimura, "Mersenne Twister: A 623-Dimensionally Equidistributed Uniform Pseudo-Random Number Generator", ACM Transactions on Modeling and Computer Simulation, v.8, n.1, pp.3-30, 1998: we implemented a sequential version of the Mersenne Twister random number generator.
  • GIT: a distributed version control system that helps GCGlib to be constructed in a cooperation scheme.
  • Doxygen: automatically generates GCGlib documentation from gcg.h header.
  • GLUI: it is a GLUT-based C++ user interface library which provides controls such as buttons, checkboxes, radio buttons, and spinners to OpenGL applications. It is window-system independent, relying on GLUT to handle all system-dependent issues, such as window and mouse management. It is used in some of the GCGlib examples.
  • Algorithms and Data Structures course of professor Robert Sedgewick from Princeton University.
  • Sally A. Goldman and Kenneth J. Goldman, A Practical Guide to Data Structures and Algorithms using Java, Chapman & Hall/CRC, 2008, ISBN-13: 978-1-58488-455-2.
  • FreeGLUT: It is a free-software/open-source alternative to the OpenGL Utility Toolkit (GLUT) library. It is used in some of the GCGlib examples.
  • Windows™ and Visual Studio™ are trademarks of Microsoft Corporation © in the United States and/or other countries.
  • Apple™, Mac OS™, and Safari™ are trademarks of Apple Computer, Inc. © registered in the United States and other countries.
  • All other trademarks are the property of their respective owners.