============== OGLplus README

:Author: Matúš Chochlík chochlik@gmail.com

.. contents::

.. _OpenGL: http://opengl.org/ .. _OpenAL: http://openal.org/ .. _EGL: http://www.khronos.org/egl .. _OGLplus: http://oglplus.org/ .. _CMake: http://www.cmake.org/ .. _Doxygen: http://www.doxygen.org/ .. _Inkscape: http://inkscape.org/ .. _libPNG: http://www.libpng.org/ .. _GLEW: http://glew.sourceforge.net/ .. _GL3W: http://github.com/shakesoda/gl3w .. _GLFW: http://www.glfw.org/ .. _FreeGLUT: http://freeglut.sourceforge.net/ .. _SDL: http://www.libsdl.org/ .. _wxGL: http://www.wxwidgets.org/ .. _Qt: http://qt.digia.com/

Important note

Please note that this project is obsolete and deprecated. A new version of EGL, OpenGL, OpenAL wrapper using modern C++ is implemented by the eagine-all project and its sub-modules:

• https://github.com/matus-chochlik/eagine-all

  • https://github.com/matus-chochlik/eagine-core
  • https://github.com/matus-chochlik/eagine-sslplus
  • https://github.com/matus-chochlik/eagine-msgbus
  • https://github.com/matus-chochlik/eagine-shapes
  • https://github.com/matus-chochlik/eagine-eglplus
  • https://github.com/matus-chochlik/eagine-oglplus
  • https://github.com/matus-chochlik/eagine-oalplus
  • https://github.com/matus-chochlik/eagine-ecs
  • https://github.com/matus-chochlik/eagine-app

Introduction to OGLplus

OGLplus_ is collection of portable open-source libraries which implement thin object-oriented facades over the OpenGL_ (version 3 and higher), OpenAL_ (version 1.1) and EGL_ (version 1.4) C-language APIs. It provides wrappers which automate resource and object management and make the use of OpenGL, OpenAL and EGL in C++ safer and easier.

Building and Installation

For the impatient:

::

linux and similar *nix systems

$> ./configure.sh

or

$> ./configure.sh --prefix=/path/to/install

$> cd _build $> make $> make install

windows

$> .\configure.bat

open the generated MSVC solution in the _build directory

or use some variant of make if available

On platforms with python

$> python configure.py --build

For the busy:

::

linux and similar *nix systems

$> ./configure.sh [--prefix=/path/to/install] [--no-docs] --no-examples --build --install

Overview

OGLplus uses a CMake-based build/configuration system. The library itself is header-only, which means that applications using it do not need to link to a compiled library, but need just to include the header files [#oglplus_link_library]_.

The build system handles several important tasks:

• Detects if the necessary things are installed and makes a site-configuration header file

• Detects the support for several C++11 features and builds a config header

• Builds several additional, automatically generated headers

• Installs all header files to a directory specified by the install prefix

• Builds the example executables and assets (textures, models, etc.) used by the examples (optional)

• Builds and installs the documentation (optional)

Requirements

• Compiler supporting required C++11 features [#req_cxx11_feats]_. Currently supported compilers:

  • g++ (at least version 4.5, 4.6 and higher is recommended)

  • clang++ (at least version 3.0) - possibly with some limitations due to the lack of support for some C++11 features

  • MSVC 2012 - with some limitations due to the lack of support for some C++11 features

• CMake_ (required)

• Doxygen_ (optional) is required to build the documentation. This can be disabled with the --no-docs command line option of the configure script (see below).

• Inkscape_ (optional) is used to convert textures for the examples from SVG to PNG. This is required only if the textures are not pre-built (typically when checked out from the repository, packaged releases are shipped with pre-built textures). Building of the textures is optional, they are not necessary when the building of examples is disabled.

• A library defining the OpenGL API (required) -- the GL/glcorearb.h or GL3/gl3.h headers or GLEW, GL3W, etc. and the corresponding binary library (libGL.so, OpenGL32.lib, libGLEW.so, etc.). OGLplus does not define the OpenGL symbols (types, constants, functions, etc.), therefore applications using it need to define them themselves (before including OGLplus). The examples currently need GLEW (at least version 1.9) or the GL/glcorearb.h header (available for download from www.opengl.org/registry/api/glcorearb.h) and a GL binary library exporting the OpenGL (3 or higher) functions. The build system detects the presence of GLEW or GL/glcorearb.h and configures compilation and linking of the examples accordingly. Note, however, that if several options (like both GLEW and GL/glcorearb.h plus the binary GL lib) are available it may be necessary to specify which option to use. On Linux and similar systems the precedence is following: GL/glcorearb.h + libGL.so, GL3/gl3.h + libGL.so, GLEW_ and GL3W_ (the first one found is used, unless specified otherwise). On Windows systems the precedence is: GLEW, GL3W, GL/glcorearb.h + OpenGL.lib and GL3/gl3.h + OpenGL.lib. Also note, that on systems with multiple versions of (for example one provided by Mesa3D and another provided by your GPU vendor) it may be necessary to specify with the option to the script (described below) in which directories to search for the library. The library to be used can be explicitly specified with the option or with one of the options of the script.

On Linux distributions with the apt package manager, the following should be enough to install most of the dependencies for the FreeGLUT+GLEW configuration:

::

sudo apt-get install doxygen cmake g++ libglew-dev freeglut3-dev libpng12-dev

For the configuration using GLFW+GLEW you would need the following:

::

sudo apt-get install doxygen cmake g++ libglew-dev libglfw-dev libpng12-dev

These two configs mentioned above are usually the ones that work on most systems. Of course other combinations of the 'GL-API' and 'GL-Context' libraries are supported and may be used as explained above. For other configurations using SDL, Qt4, wxWidgets, etc. you need to install the appropriate packages (the names vary wildly between distrubutions or even between versions of the same distribution so they are not listed here).

CMake-based build configuration

The CMake script defines and uses several variables to modify the build configuration, which can be specified on the command-line when invoking cmake (with the -D option. see cmake manual for details):

• HEADER_SEARCH_PATHS : (semicolon-separated) list of paths to additional directories to search when looking for 3rd-party headers like GL/glew.h, GL3/gl3.h, GL/glcorearb.h, etc.

• LIBRARY_SEARCH_PATHS : (semicolon-separated) list of paths to additional directories to search when looking for 3rd-party binary libraries like GL, GLEW, GL3W, GLFW, SDL, glut, png, etc.

• OGLPLUS_NO_EXAMPLES Off: Do not build the examples nor the assets.

• OGLPLUS_NO_DOCS Off: Do not build and install the documentation.

User-friendly configuration script

The configuration script comes in three flawors:

1. configure.sh -- For platforms with bash.
2. configure.bat -- For windows.
3. configure.py -- For platforms with python (recommended). This version of the script is the most portable and supports most features.

The configure script is a more user-friendly way to invoke cmake and to specify additional parameters for the configuration process.

Some of the more important command-line options are described below:

--help Display the help screen.

--prefix PATH Specifies the installation prefix path for cmake (sets the value of the CMAKE_INSTALL_PREFIX variable). If this option is not specified, cmake's default prefix is used.

--include-dir PATH Specify additional directiories to search when looking for header files. It may be used multiple times to specify multiple directories. Headers are searched in the directories specified with this option in the same order in which they appear on the command-line and the default system header locations are searched only afterwards. The first header found is used, in case there are multiple versions of the searched header file.

--library-dir PATH Specify additional directiories to search when looking for compiled libraries. It may be used multiple times to specify multiple directories. Libraries are searched in the directories specified with this option in the same order in which they appear on the command-line and the default system library locations are searched afterwards. The first library found is used, in case there are multiple versions of the searched library.

--no-docs Do not build the documentation.

See the --help option for the full description and detailed info on the usage of this script. Bash users can also do source config/configure.bash_complete to install a bash completion extension that allows to TAB-complete the command line arguments for the configure-oglplus configuration script that invokes configure.py.

Other build environments

Microsoft Visual Studio 2012

OGLplus contains a solution file and a set of project files for building some of the examples in MSVC 2012. The solution is located at the following path:

• $(OGLplusRoot)/etc/msvc11/OGLplus/OGLplus.sln

To build properly, it requires GLEW (1.9 or higher) and FreeGLUT libraries to be installed and added to the list of header/library search paths in the solution. This can be achieved by setting the following variables visible to MSVC:

• OGLPLUS_DEP_INCLUDE_DIRS - list of (semicolon-separated) paths pointing to the directories where GLUT's and GLEW's header files are located.

• OGLPLUS_DEP_LIBRARY_DIRS - list of (semicolon-separated) paths pointing to the directories where GLUT's and GLEW's .lib files are located.

• OGLPLUS_DEP_LIBS - list of (semicolon-separated) .lib files to be linked to the examples. Typically glew32.lib;freeglut.lib for dynamic linking or glew32s.lib;freeglut_static.lib