search

matus-chochlik / oglplus

OGLplus is a collection of open-source, cross-platform libraries which implement an object-oriented facade over the OpenGL® (version 3 and higher) and also 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 these libraries in C++ safer and more convenient.
http://oglplus.org/
Boost Software License 1.0
494 stars 71 forks source link

readme

============== 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:

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

The build system handles several important tasks:

Requirements

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

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:

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:

These variables can be set either as system or user environment variables or the OGLplus-site.props property sheet file (located in the solution's directory) can be used. Either edit the file in a text editor or use MSVC's Property Manager and set the variables listed above as appropriate on your system. Note, that the OGLplus-site.props file already defines variables like the above, but with appended underscore (for example OGLPLUS_DEP_INCLUDE_DIRS_, etc.). To set the variables you can open the file in a text editor, remove the underscores and set the values to match your system configuration.

Also note that when building the examples via the MSVC solutions the $(OGLplusRoot)/_prebuilt/ directory is required. This directory contains automatically generated textures and other files that are not in the source repository. This directory is included in the release packages. If you are building from sources from the Git repository also download a recent package and copy the _prebuilt/ directory into to the directory where you have cloned the repo or use the cmake build system and build them that way.

Assets used in examples

Many of the examples use binary media files which are not suitable for inclusion to the source repository mainly because of their size. OGLplus examples use texture bitmaps, fonts and models, OALplus examples use sounds, etc. Some of these media files can be generated from textual representations (for example SVG files converted or POVray sources rendered to bitmaps). Assets for which there is a textual source and its size does not exceed certain limits are included in the repository and are rendered into their binary form by the build system. This may however require some third-party applications and the rendering process can be very time-consuming.

Because of this, some of the medium-sized assets are pre-built and shipped with the release packages (in the _prebuilt/ directory) and the larger assets can be downloaded individually from http://sourceforge.net/projects/oglplus/files/assets/

Acknowledgements

License

Copyright 2008-2019 Matus Chochlik. Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

.. [#oglplus_link_library] Although OGLplus is generally a header-only library, several parts of it (mostly some complex functions or functions with static data) can optionally be built separately and linked to applications, which can lead to improved build times especially for larger projects. See the documentation for the OGLPLUS_LINK_LIBRARY preprocessor configuration option for more details. Generally if OGLPLUS_LINK_LIBRARY is set to zero then everything is inlined, otherwise some functions are only declared, but not defined and the oglplus/lib.hpp header that contains the definition of all such functions must be included in one of the translation units that are linked into the final application.

.. [#req_cxx11_feats] OGLplus requires the following C++11 features: The type_traits and tuple librares, variadic preprocessor macros, r-value references and move-constructors. OGLplus also uses (but has workarounds for or disables certain components and/or functions if the features are not available): Strongly typed enumerations, variadic templates, initializer lists, lambdas, defaulted and deleted functions, function template default arguments, constexpr, noexcept, nullptr, explicit conversion operators, unicode literals and user-defined literals.