Skip to content

Merging OpenGLRaw and gl

Jump to bottom
Sven Panne edited this page Dec 29, 2015 · 26 revisions

Motivation

Currently there are 2 similar, but different Haskell packages available for the raw access to OpenGL, OpenGLRaw and gl. While competition is good and healthy, especially in the Open Source world, the situation is a bit confusing for users: Which package should they use? And why should 2 different teams duplicate their effort for something functionally equivalent? To improve the situation, this proposal aims to merge those packages, basically making it possible to deprecate gl afterwards. The result will be a new version of OpenGLRaw containing "the best of both worlds", at the cost of not being backwards-compatible with neither OpenGLRaw nor gl. This is a price one has to pay to get a clean slate after a long time, and it's a small one considering the fact that previous versions are still available on Hackage.

Differences and how to resolve them

Haskell API

  • OpenGLRaw exposes OpenGL tokens as plain old Haskell values, e.g. gl_LINES = 0x0001 while gl uses bidirectional pattern synonyms, e.g. pattern GL_LINES = 0x0001. While it is a tiny bit more convenient to use and visually resembles the original OpenGL C API slightly more, the PatternSynonyms extension is only available in GHC >= 7.8.1 (released April 2014). Proposal: This is a tough call, it’s basically backwards compatibility vs. ease of use. Perhaps we should use pattern synonyms?

[Edward Kmett: the pattern synonyms were a very deliberate choice on the behalf of gl, because they can be used naked in pattern position. This can generate both more efficient and more readable code.]

[Sven Panne: Using pattern synonyms and dropping support for GHC < 7.8 is fine with me. For people using an older GHC, Hackage still has the old OpenGLRaw versions and should find a build plan for them, so older stuff continues to work.]

  • The types of the OpenGL tokes are slightly different, too: OpenGLRaw uses the more exact types from the OpenGL registry, i.e. one of GLbitfield, GLenum, GLubyte, GLuint, or GLuint64, while gl always uses (Num a, Eq a) => a. OpenGL is actually a bit sloppy regarding its types, but the generality provided by Num doesn't help: A survey of the uses of fromIntegral in the OpenGL package shows that basically all conversions are either due to the type of the value returned by some glGetFOO or by an impedance mismatch between OpenGL's types and Int (forced by some other library). In both cases, the more liberal type of the tokens wouldn't have helped. Resolution: Use the more exact types, any kind of conversions should be explicit.
  • OpenGLRaw has types per OpenGL version (see e.g. Core45), gl always exposes all of them (see Types). OpenGLRaw’s approach is following the spec more closely, e.g. GLsizeiptr is only mentioned in OpenGL >= 1.5. Resolution: Use OpenGLRaw’s approach.
  • The gl package exposes OpenGL ES APIs, too, but this is wrong for several reasons (Proposal: Do not expose OpenGL ES stuff, this should live in a separate package):
    • The token values can be API-dependent, and there is actually one example of this: GL_ACTIVE_PROGRAM_EXT has the value 0x8259 under OpenGL ES 2, while it has the value 0x8B8D under OpenGL. While this was actually a specification glitch, it is out in the wild now and ignoring it doesn’t it make go away.
    • OpenGL versions of extensions can be completely unrelated to their OpenGL ES versions, see e.g. GL_EXT_separate_shader_objects.
    • API entry points for OpenGL ES have to be retrieved via EGL, while OpenGL entry points must be retrieved via GLX/WGL/…, i.e. window-system-specific ways. Perhaps in some bright future EGL will be the one and only way (see e.g. the EGL_KHR_create_context) extension, but this is not the case at the moment.

[Edward Kmett: I was actually in the process of going further in gl and starting to roll in WebGL support! So this may be a bit of a sticking point.]

[Sven Panne: Until EGL unifies everything, offering both WebGL an "normal" OpenGL in a single package won't really work. The current EGL won't give you OpenGL-only entry points, and there is no guarantee that GLX/WGL/... will return the right entry points for WebGL. Annoying, but that's how it is today.]

  • Extensions in OpenGLRaw come in 2 versions when needed (core and compatibility, see e.g. VertexType2101010RevCore and VertexType2101010RevCompatibility), while gl ignores that distinction. Resolution: Do it like OpenGLRaw, the OpenGL registry clearly makes it explicit that extensions are profile-dependent in general.

Module names

  • The module prefix used by OpenGLRaw is Graphics.Rendering.OpenGL.Raw, while gl uses the shorter Graphics.GL. OpenGLRaw’s prefix is overly long and dates back many years, to a time when there was consensus that this might be a good idea. Nowadays gl’s choice looks much saner. Nevertheless, it’s desirable to distinguish the raw binding from any higher-level packages building on it, like OpenGL. Resolution: Use Graphics.GL.Raw as the prefix.

  • gl uses an additional Ext level below Graphics.GL for modules containing extensions, but this is superfluous and only makes things more verbose. The extensions are already grouped by their vendor IDs, which form their own sub-namespaces. Resolution: Simply drop Ext, this even buys us back 3 characters, which we spend on Raw (see item above).

  • OpenGLRaw uses the module name VersionXY for OpenGL versions without profiles, while gl uses StandardXY. Proposal: Use VersionXY, it’s more consistent with the OpenGL CPP defines.

  • Although formally OpenGL 3.2 introduced the notion of profiles, the OpenGL registry already does it for 3.0 and 3.1, too. OpenGLRaw follows the registry, while gl does not. The differences are small, though, only GL_INDEX, GL_TEXTURE_LUMINANCE_TYPE, and GL_TEXTURE_INTENSITY_TYPE. Resolution: Follow the registry.

Haddock Documentation

  • OpenGLRaw links to all possible man page versions of an API entry, while gl only links to the latest one, compare e.g. the documentation for glCreateProgram in OpenGLRaw and in gl. Note that the latest man page might document stuff which is not supported in previous versions and therefore it can be quite misleading. The documentation for an entity is always the same, regardless of the version. This is caused by the fact that the various modules basically consist of re-exports only, which is necessary to mix versions and extensions. Resolution: Use OpenGLRaw’s man page links, so the user can choose the right one.

  • OpenGLRaw documents each parameter directly in the signature, while gl does it in a more separated way, compare e.g. the documentation for glGetDebugMessageLog in OpenGLRaw and in gl. The former way avoids the mental matching of parameters and their corresponding documentation and is more direct. Resolution: Use OpenGLRaw’s way of parameter documentation.

  • gl repeatedly expands enumerant groups in the documentation, while OpenGLRaw just mentions the group names, compare e.g. the documentation for glGetTexLevelParameterfv in gl and in OpenGLRaw. The problem with enumerant groups in the registry is that they are highly incomplete, inconsistent and poorly maintained, but most importantly: They should better depend on the OpenGL version, which they don’t, so mentioning the individual enumerants is wrong and misleading in general (OpenGL versions both remove and add tokens/functions). Nevertheless, people seem to like it. Resolution: Change the group names into links to separately documented enumerant groups, getting rid of the duplication and visual overload. A new version of OpenGL containing that change is already on Hackage, compare e.g. the documentation for glGetTexLevelParameterfv in gl and in OpenGLRaw (The Hackage docs are broken due to a buggy Haddock version). Note that the alias computation for enumerants still needs some love, but it's basically working, and it's something not in gl.

Internals

The differences are not really relevant for users of the package, they are just here for reference.

  • Both OpenGLRaw and gl generate most of the binding from the XML API description from the OpenGL registry. OpenGLRaw has the resulting Haskell files checked in, while gl dynamically generates them during build time. Having the generated files checked in removes the need to build various XML-related packages, so it’s more convenient and faster for people just wanting to use OpenGL. Furthermore, when the OpenGL registry has changed, one has to look at the generated files anyway: The cabal file needs an update, perhaps needing some kind of version bump. Note that gl ships the build artifacts, too, but the library user nevertheless needs several (useless) hxt-related packages. Resolution: Continue to check in the generated files.

  • OpenGLRaw uses a git submodule for an OpenGL registry mirror to get gl.xml, while gl uses a checked-in version. Resolution: Use a git submodule, it’s a bit more explicit. Perhaps a note in the README about the git magic involved might be nice.

Acknowledgement

Thanks to Edward Kmett and Gabríel Arthúr Pétursson for their work on gl, thereby urging me to do things I would have been too lazy to do otherwise... 😉

Clone this wiki locally