/OpenGLAda

Thick Ada binding for OpenGL and GLFW

Primary LanguageAdaMIT LicenseMIT

OpenGLAda – OpenGL binding for Ada

Overview

OpenGLAda is a thick OpenGL binding for the Ada 2005 programming language. Unlike other, thin, bindings (see the project's homepage for a list), OpenGLAda enriches the original API with concepts and features provided by Ada, like object orientation, type safety and generics.

Besides standard OpenGL functionality, OpenGLAda optionally provides bindings to the following OpenGL-related libraries:

  • GLFW (opengl-glfw.gpr): This is a library for creating windows with an OpenGL context on them. It also provides functionality for capturing user input on keyboard, mouse and joystick. Having a window with an OpenGL context is the prerequisite for using any OpenGL functionality. The GLFW binding comes in two flavors: One for GLFW 2.x and one for GLFW 3+. There are significant differences between these two, the most prominent being that GLFW 3 can handle multiple windows. You can set the desired GLFW version for the binding at compile time.
  • SOIL (opengl-soil.gpr): The Simple OpenGL Image Library. This is a very tiny library for loading image files into OpenGL textures. It is public domain. Because it's so tiny, it is linked directly into OpenGLAda. Its source is included in the OpenGLAda sources.
  • FTGL (opengl-ftgl.gpr, deprecated): A library built on top of FreeType that provides an API to load TrueType fonts and render text with OpenGL. The Ada wrapper only provides basic functionality to load fonts and render text. As it does not include a wrapper to FreeType, the more low-level functionality has been excluded. This wrapper is not maintained anymore in favor of the new FreeType wrapper.
  • FreeType (FreeTypeAda/freetype.gpr): A library for loading TrueType and OpenType fonts. OpenGLAda includes FreeTypeAda, a wrapper for the FreeType library. The project opengl-text.gpr provides an original higher-level API for rendering text based on FreeTypeAda.

OpenGLAda supports MacOSX, Windows and X11-based systems. API documentation can be found on the project's homepage.

Prerequisites

In order to build OpenGLAda, you need to have:

  • A GNAT compiler¹. Compilers known to work well with OpenGLAda are GnuAda, AdaCore GNAT GPL 2017, and TDM-GCC. More information is available on the GCC website.
  • GPRBuild (is bundled with AdaCore's GNAT distribution). TDM-GCC users can get it from [here][16 (NOTE: The gprbuild bundled in this zip is known not to work. For the time being, if you're using TDM-GCC, replace gprbuild with gnatmake in all commands even though that will tell you that project support in gnatmake is deprecated and will soon be removed. The reason for this incompatibility has not been found yet).
  • An OpenGL implementation (usually comes bundled with your graphics driver)
  • Optionally GLFW (OpenGLAda is pretty useless without the ability to create an OpenGL context.)
  • Optionally FTGL (deprecated)
  • Optionally FreeType

¹: You may also be able to build OpenGLAda with another Ada compiler and/or without using the *.gpr files. You just have to import the sources to your project and whichever build system you are using. I never used other Ada compilers apart from GNAT, so if I accidentally used some GNAT-specific features in the code, please drop me a message.

Compilation

A Makefile is provided mainly for building the tests:

$ make tests

If you're on Windows and do not have the make utility available, you can build the test by executing

$ gprbuild -P opengl-glfw-test.gpr -XWindowing_System=windows
$ gprbuild -P opengl-test.gpr -XWindowing_System=windows

The tests require GLFW, because they need to create windows. By default, they try to link against GLFW 3+. You can instead build the tests against GLFW 2.x by executing:

$ gprbuild -P opengl-test.gpr -XWindowing_System=windows -XGLFW_Version=2
$ gprbuild -P opengl-glfw-test.gpr   -XWindowing_System=windows -XGLFW_Version=2

(Substitute windows with x11 or quartz if needed.)

Detailed Installation & Compilation Instructions

Each section has in its title the major version numbers of the environment in which it has been tested. Chances are that the instructions also work with other versions (e.g. on Windows 7 instead of Windows 10).

Windows 10 / GNAT GPL 2017 / GLFW 3

  • Download and install GNAT GPL 2017 Windows x86 from AdaCore's Libre Site. We assume you install it to C:\GNAT\2017. Make sure the bin folder is in the PATH of your shell.

  • Download 32-bit Windows binaries from the GLFW download section (tested with GLFW 3.2.1).

  • Open the zip folder and copy the file glfw3.dll from the lib-mingw folder into C:\GNAT\2017\lib.

  • Open your shell and navigate to the root folder of OpenGLAda. Execute:

     gprbuild -p -P opengl-test.gpr -XWindowing_System=windows

    This should produce executables in the bin folder inside OpenGLAda.

  • You can now either add C:\TDM-GCC-64\lib to your PATH or copy the glfw3.dll from there to the bin folder. One of those two options is necessary so that the binaries can find the dll.

  • Some of the test binaries require to be launched from the bin folder as working directory because they are loading shader files from hardcoded paths.

  • Keep in mind that you need to spread the glfw3.dll alongside your binaries for them to work.

  • If you want to use FreeType, download the official 32-bit Windows binary from the FreeType website and copy the file freetype6.dll from the bin folder into C:\GNAT\2017\lib, then execute:

    gprbuild -p -P opengl-text-test.gpr -XWindowing_System=windows -XFREETYPE_LIBRARY_NAME=freetype6

    The same things stated for the glfw3.dll are valid for the freetype6.dll.

Windows 10 / TDM-GCC 64bit / GLFW 3

These instructions are for building 64bit binaries on Windows.

  • Download and install the 64bit TDM-GCC compiler from here. In the installation wizard, make sure to check the (by default unchecked) ada option. Make sure the bin folder is in the PATH of your shell.

  • Download the 64-bit Windows binaries from the GLFW download section (tested with GLFW 3.2.1).

  • Open the zip folder and copy the file glfw3.dll from the lib-mingw-w64 folder into C:\TDM-GCC-64\lib.

  • Open your shell and navigate to the root folder of OpenGLAda. Execute:

     gnatmake -p -P opengl-test.gpr -XWindowing_System=windows

    This should produce executables in the bin folder inside OpenGLAda.

  • You can now either add C:\TDM-GCC-64\lib to your PATH or copy the glfw3.dll from there to the bin folder. One of those two options is necessary so that the binary can find the dll.

  • Some of the test binaries require to be launched from the bin folder as working directory because they are loading shader files from hardcoded paths.

  • Keep in mind that you need to spread the glfw3.dll alongside your binaries for them to work.

macOS High Sierra / GNAT GPL 2017 / GLFW 3

  • Download and install GNAT GPL 2017 x86_64 Mac OS X from AdaCore's Libre Site. We assume you install it to /usr/local/gnat. Make sure the bin folder is in the PATH of your shell.

  • There are multiple ways to install glfw; the most popular one is probably using Homebrew and executing brew install glfw.

  • Open your shell and navigate to the root folder of OpenGLAda. Execute:

     gprbuild -p -P opengl-test.gpr -XWindowing_System=quartz

    This should produce executables in the bin folder inside OpenGLAda.

  • Some of the test binaries require to be launched from the bin folder as working directory because they are loading shader files from hardcoded paths.

  • Keep in mind that you need to spread the glfw.dylib alongside your binaries for them to work.

  • If you want to use FreeType, you can install it with brew install freetype. You can build the tests with:

    gprbuild -p -P opengl-text-test.gpr -XWindowing_System=quartz

    The same things stated for the glfw.dylib are valid for the freetype.dylib.

Linux

Please refer to your package manager documentation. Most Linux distributions provide packages for GNAT and GLFW. On Debian, you need to install gprbuild as separate package.

Using OpenGLAda in your project

With GPRBuild

The easiest way to use OpenGLAda in your project is to just copy the sources in some dependency folder within your project folder, e.g.:

YourProject
 |
 |-dependencies
 |  |
 |  +-OpenGLAda
 |
 |-your
 |-project
 |-files
 +-...

If you're using the GPRBuild system, you can then just declare using OpenGLAda in your *.gpr file:

with "dependencies/OpenGLAda/opengl";

Alternatively, you can specify the path to the OpenGL project file in as environment variable:

export GPR_PROJECT_PATH=dependencies/OpenGLAda

... and then specify the dependency without the path:

with "opengl";

If you want to use GLFW, you also need to refer to the project opengl-glfw.gpr instead (it automatically adds a dependency to the opengl project).

The project files opengl.gpr and opengl-glfw.gpr take the following scenario parameters:

  • Windowing_System: Sets the backend windowing system. Used for GLFW and also for system-dependent parts of the API (GLX, WGL, CGL):

    • x11: X Windowing System (Linux, BSD, etc)
    • windows: Microsoft Windows
    • quartz: Quartz Compositor (OS X)

  • mode: May take one of the following values:

    • debug (default): Compile the project with debugging symbols and without optimization.
    • release: Compile the project for a release environment.

  • GLFW_Version (GLFW only): Sets the version of the GLFW library to link against. See here for a detailed comparison of the two API versions.

    • 2: GLFW 2.x. Only one window.
    • 3 (default): GLFW 3+. Multiple windows, multiple monitor support, etc.

  • Auto_Exceptions: Configures exception handling:

    • enabled (default): After each call to OpenGL, OpenGLAda checks whether OpenGL has set an error flag and if it had, raises the corresponding exception.
    • disabled: The user has to query the error flag on their own.

  • GLFW_LIBRARY_NAME: Sets the name of the GLFW library for linking. Default is glfw everywhere but on Windows with GLFW 3, in which case it is glfw3.

  • FREETYPE_LIBRARY_NAME: Sets the name of the FreeType library for linking. Default is freetype.

With other build systems

If you want to use another build system, take a look at the .gpr files bundled with OpenGLAda, they tell you which compiler and linker options you need to give in order to compile it.

Installation

OpenGLAda is not designed to be installed as a standalone library. The reasoning behind this is that OpenGLAda is a wrapper library that doesn't provide much functionality on its own. Therefore, maintaining a library installing routine does not seem worth the effort - even less as it would be expected to support multiple platforms.

Examples

OpenGLAda comes bundled with a lot of examples. They have mostly been translated from C examples from OpenGL textbooks. They are located inside the examples folder. Each example has a separate .gpr file with which it can be built.

Contributions of examples are always welcome.

Developer Documentation

OpenGLAda autogenerates its API binding to OpenGL. The autogenerated source files are those in src/gl/generated and they are generated from the *.spec files in src/gl/specs. The syntax of the spec files is similar to Ada.

The reason behind this is that all functionality newer than OpenGL 1.1 is not expected to be provided by the OpenGL implementation. Instead, function pointers to the implementations should be queried at runtime. This makes it possible for the user to provide a fallback in case some OpenGL functionality is not available on the target system.

The generate tool compiled from src/generator will take care of creating both the API imports from OpenGL and the code for loading the function pointers at runtime. The tool is only necessary when adding OpenGL API functions to OpenGLAda and thus not of interest to the general user, since the autogenerated files are checked in to version control.

If you change the *.spec files, running make generate afterwards will update the autogenerated files. Be sure to check them in along with the spec changes.

License

OpenGLAda is distributed under the terms of the MIT License. The Ada 2012 logo that is used in the SOIL tests is distributed under the terms of the CC BY-ND 3.0 license, the original author is AdaCore.