updated docs

Author: flyx

CHANGELOG

@@ -1,6 +1,10 @@
 v0.8.0
+ * __Breaking change__: Removed SOIL since it doesn't compile on macOS Catalina
+   and replaced it with GID. Added `opengl-images.gpr` to replace SOIL
+   functionality.
+ * __Breaking change__: Removed the long-deprecated FTGL binding.
  * Fixed the binding of `glGetTransformFeedbackVarying`
- * Fixed error when creating an empty Depth_Component texture (#135)
+ * Fixed a bug when creating an empty Depth_Component texture (#135)
  * Added package:
    - GL.Objects.Queries
  * Added missing functionality in:
@@ -9,8 +13,8 @@ v0.8.0
                          glGenTransformFeedbacks, glDeleteTransformFeedbacks,
                          glBindTransformFeedback, glMapBufferRange,
                          glFlushMappedBufferRange, glGetBufferSubData)
- * Removed SOIL since it doesn't compile on macOS Catalina and replaced it with
-   GID. Added `opengl-images.gpr` to replace SOIL functionality.
+ 
+ * Fixed a bug when querying shaders from a program object (#129).
 v0.7.0:
  * Added missing functionality in:
    - GL.Objects.Buffers (glBindBufferBase, glDrawElementsInstanced,

README.md

@@ -18,14 +18,14 @@ bindings to the following OpenGL-related libraries:
    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.
- * [FreeType][19] (`FreeTypeAda/freetype.gpr`): A library for loading TrueType
-   and OpenType fonts. OpenGLAda includes [FreeTypeAda][20], a wrapper for the
-   FreeType library. The project `opengl-text.gpr` provides an original
+ * [FreeType][19] (`deps/FreeTypeAda/freetype.gpr`): A library for loading
+   TrueType and OpenType fonts. OpenGLAda includes [FreeTypeAda][20], a wrapper
+   for the FreeType library. The project `opengl-text.gpr` provides an original
    higher-level API for rendering text based on FreeTypeAda.
- * [GID][10] (`opengl-images.gpr`): The *Generic Image Decoder*. This is an
+ * [GID][10] (`deps/gid/gid.gpr`): The *Generic Image Decoder*. This is an
    original Ada library for loading common image formats, which is included in
-   OpenGLAda. The project `opengl-images.gpr` provides simple subroutines to
-   generate OpenGL textures with GID.
+   OpenGLAda. The project `opengl-images.gpr` provides an original higher-level
+   API for generating OpenGL textures with GID.
 
 OpenGLAda supports macOS, Windows and X11-based systems. API documentation can
 be found on the [project's homepage][4].
@@ -46,12 +46,14 @@ Compared to C, OpenGLAda provides the features of the following C libraries:
  * [Image loading][24]: OpenGLAda includes the [GID][10] library for image
    loading.
 
-## Windows Installer
+## Building & Installation
 
-There is an installer available for Windows + GNAT Community in the
+### Windows
+
+There is an installer available for 64bit Windows + GNAT Community in the
 [repository's *releases* section][21] which includes all optional dependencies.
 
-## Prerequisites
+### Prerequisites
 
 In order to build OpenGLAda, you need to have:
 
@@ -75,11 +77,11 @@ 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, open an issue.
 
-## Installation
+### Installation
 
 To install OpenGLAda with all optional libraries, execute
 
-    $ gprbuild [options] openglada.gpr
+    $ gprbuild -p [options] openglada.gpr
     $ gprinstall [options] openglada.gpr
 
 Where *[options]* is the set of scenario variables you want to use (generally
@@ -119,7 +121,7 @@ in the form of `-X`*name*`=`*value*`). The available variables are:
 
 For example, a typical Windows installation would be
 
-    $ gprbuild -XWindowing_System=windows -Xmode=release openglada.gpr
+    $ gprbuild -p -XWindowing_System=windows -Xmode=release openglada.gpr
     $ gprinstall -XWindowing_System=windows -Xmode=release openglada.gpr
 
 Installing OpenGLAda makes its projects available to `gprbuild` and also to
@@ -130,7 +132,7 @@ GNAT Studio. You can now import it like this:
     with "opengl-text";
     -- and so on
 
-**Note:** The projects file `openglada.gpr` is just an aggregate project used
+**Note:** The project file `openglada.gpr` is just an aggregate project used
 for installation. In your projects, depend on `opengl.gpr` and its child
 projects.
 
@@ -162,31 +164,62 @@ Examples are available in [this repository][11].
 
 ## 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.
+I have written an article about the development of OpenGLAda on AdaCore's blog:
+
+ * [Part 1][25]
+ * [Part 2][26]
+
+### Binding Generation
+
+OpenGL implementations do not necessarily provide the newest OpenGL version,
+but possibly some older one with some functionality of the newer versions
+provided as extensions. For OpenGLAda, this means that most OpenGL functionality
+cannot be linked against via the library loader, since loading the library
+would immediately fail if any function is not available, even if the user never
+calls it. Most notoriously, Windows does not provide any OpenGL functionality
+newer than 1.1 via library loading.
+
+The remedy for this is that function pointers of newer OpenGL functions must
+be queried at runtime. This is a tedious process and similar for each function.
+For this reason, OpenGLAda uses a code generator to autogenerate the function
+pointer types and the code loading each function, as well as the code importing
+OpenGL 1.1 functions via library loading.
 
-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 library user to provide a fallback in case some OpenGL functionality is not
-available on the target system.
+The code generator can be found in `src/generator`. It processes the files found
+in `src/gl/specs` and creates the files found in `src/gl/generated`. The
+generator is a tool used at compile-time for building OpenGLAda and of no
+interest to the general user. The generated files are checked in to version
+control. The generator also generates the markdown file which is the base for
+the [function mapping list][27] on the website.
 
-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.
+The process of wrapping a new OpenGL function is:
 
-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.
+ * Add the function specification to one of the `*.spec` files in `src/gl/specs`.
+ * Run `make generate`, which builds the generator and generates the Ada code.
+ * Check in the newly generated code along with the changed spec.
+
+The `*.spec` files use a syntax similar to Ada.
+
+### Building the Windows Installer
+
+The Windows installer is generated with the [WiX Toolset][28]. You'll need its
+executables `heat.exe`, `candle.exe` and `light.exe` in your `PATH`. Executing
+the script `create-msi.ps1` in the `install` directory containing it will
+
+ * download binaries of the GLFW and FreeType libraries
+ * build OpenGLAda with GNAT
+ * install OpenGLAda in a temporary directory
+ * Build an MSI installer that will copy OpenGLAda's binaries as well as the
+   GLFW and FreeType libraries into the installation directory of a
+   GNAT Community installation.
 
 ## License
 
-OpenGLAda is distributed under the terms of the [MIT License][7]. The Ada 2012
-logo that is used in the images tests is distributed under the terms of the
-[CC BY-ND 3.0][8] license, the original author is [AdaCore][9].
+OpenGLAda, as well as the included libraries FreeTypeAda and GID, are
+distributed under the terms of the [MIT License][7].
+
+The Ada 2012 logo that is used in the images tests is distributed under the
+terms of the [CC BY-ND 3.0][8] license, the original author is [AdaCore][9].
 
  [1]: http://libre.adacore.com/
  [2]: http://www.adacore.com/gnatpro/toolsuite/gprbuild/
@@ -208,4 +241,8 @@ logo that is used in the images tests is distributed under the terms of the
  [21]: https://github.com/flyx/OpenGLAda/releases
  [22]: http://glew.sourceforge.net/
  [23]: https://www.opengl.org/resources/libraries/glut/
- [24]: https://www.khronos.org/opengl/wiki/Image_Libraries
+ [24]: https://www.khronos.org/opengl/wiki/Image_Libraries
+ [25]: https://blog.adacore.com/the-road-to-a-thick-opengl-binding-for-ada
+ [26]: https://blog.adacore.com/the-road-to-a-thick-opengl-binding-for-ada-part-2
+ [27]: https://flyx.github.io/OpenGLAda/mapping.html
+ [28]: https://wixtoolset.org/