Alpha Versions of DerelictUtil/SDL2/GL3/FI

For a little while now I’ve been working locally on some major updates to a few of the Derelict packages. I’ve decided to go ahead and tag some alpha releases for DUB of what I’ve got so far in order to make sure it works for others besides me. With the exception of one package, I’ve been using them locally without any problems. I’ll summarize the changes here for anyone who wants to try them out.

DerelictUtil version 3.0.0-alpha.1

This is the spark that ignited the changes in the other packages. Because it’s binary-incompatible with the existing 2.x versions, every Derelict package will have to be updated to use it in order for them all to live happily in the same application. This includes the “unofficial” Derelict packages out there that are built on DerelictUtil. Once all of the DerelictOrg packages are updated, other packages will not work with the latest versions unless they upgrade to DerelictUtil 3.0.0 as well.

Here are the major changes:

  • The xtypes and wintypes modules are gone.
  • The system module has the new manifest constants Derelict_Arch_32 and Derelict_Arch_64.
  • SharedLibLoader.bindFunc is now public.
  • A new public function, bindFunc_stdcall, has been added to SharedLibLoader. Some bindings, like DerelictFI, need this on Windows and had implemented it locally. Now it can be used by any package that needs it.
  • @nogc, @property and nothrow have been added to SharedLib and SharedLibLoader where appropriate.
  • __FILE__ and __LINE__ were added to the DerelictException constructors. This was also added to 2.0 and released under the 2.1 tag for anyone that wants it now, but since I’m in the middle of upgrading everything to 3.0, I didn’t bother upgrading the existing packages to 2.1.

If you maintain a Derelict binding, I recommend you start testing this out with version=~>3.0.0-alpha.1 in a new branch to make sure nothing is broken. I expect to drop the alpha suffix (and any future beta suffix) by the beginning of the new year.

DerelictSDL2 3.0.0-alpha.1

In addition to depending on the new DerelictUtil version, this version of DerelictSDL2 adds support for SDL_gpu (specifically, the API as it exists as of commit 18f04250f00c7c389460c7478851cea6b358a868), along with the option to use static instead of dynamic bindings for all of the SDL2_* libraries. To make any specific binding static, use versions with the syntax PackageName_Static in your dub configurations (or compiler command lines). For example, the following uses DerelictSDLImage as a static binding, but any of the other DerelictSDL2 bindings will be dynamic:

dependency "derelict-sdl2" version="~>3.0.0-alpha.1"

This means you will need to configure your build to link with the SDL2_image static library or either the import library on Windows, or the shared object on other systems. You would still use the load method for the other SDL2 bindings. The version DerelictSDL2_Static will enable the static version of all of the DerelictSDL2 bindings, as will the version Derelict_Static, which will also enable static versions of any Derelict package that supports it.

Alternatively, a subconfiguration can be specified in the dub file.

dependency "derelict-sdl2" version="~>3.0.0-alpha.1"
subConfiguration "derelict-sdl2" "derelict-sdl2-static"

This is the same as specifying the version DerelictSDL2_Static, with the addition that it excludes the dynamic-related modules from the build (though there’s still a compile-time dependency on DerelictUtil). The default configuration is derelict-sdl2-dynamic.

Note that DerelictSDL2ttf has been renamed to DerelictSDL2TTF, but the former is still around as an alias.

DerelictGLFW3 4.0.0-alpha.1

There are no major additions or changes to DerelictGLFW3, other than the dependency on the new DerelictUtil. I was actually going to brand this as version 3.2. However, there has been some confusion about DerelictGLFW3 versions and GLFW3 versions, given that the latter is currently on version 3.2 as well. Since I’m already bumping up the major versions of the other packages, doing so here helps to eliminate that source of confusion.

DerelictGLFW3 3.1 already supported a static configuration, derelict-glfw3-static. In this release, I’ve changed the expected version tag from DerelictGLFW3Static to DerelictGLFW3_Static for consistency. I’ve also added Derelict_Static as a synonym for DerelictGLFW3_Static. Using the subconfiguration instead of the version will exclude the dynamic binding modules from compilation and eliminate the dependency on DerelictUtil.

DerelictGL3 2.0.0-alpha.1

Major, major, breaking changes here. Of course it uses the new DerelictUtil, but the package has also been completely refactored. The first thing to note is that all of the modules now live in the derelict.opengl package (which should now be imported instead of the gl module), rather than derelict.opengl3. And what used to be the gl3 module is now simply gl. The following code does almost what the equivalent with the old package and module name does today.

import derelict.opengl;
void initGraphics() {
    // Create an OpenGL context
    // Now load OpenGL as usual

The call to reload  will still, by default, load the highest version of OpenGL available in the current context. The difference is that, now, no extensions are loaded by default. In order for extensions to be loaded, you have to mix them in somewhere. The easiest way to do that is to create a module specifically for that purpose. Something like this:

module mypackage.mygl;
public import derelict.opengl;
public import derelict.opengl.extensions.arb_b,
mixin(arbBindlessTexture); // GL_ARB_bindless_texture
mixin(arbComputeShader);   // GL_ARB_compute_shader

This will ensure that the extensions are declared in your new module and loaded when you call reload. Some extensions, like GL_ARB_compute_shader, have the same function and type names in the extension specification as they do in core OpenGL. In those cases, if the context supports the version where the extension is part of the core, then it will not be loaded as an extension. So with these specific extensions, you can test their availability with the following lines:

import mypackage.mygl;
// It's best to set some variables at start up, so you aren't
// calling isExtensionLoaded every time you need it. This is
// a departure from the current version of DerelictGL3, which
// provided such flags for you.
bool haveBindlessTexture;
bool haveComputeShader;

void setExtensionFlags() {
    // GL_ARB_bindless_texture is a full-on extension with ARB
    // suffixes on the function names, so you can simply check
    // if it has been loaded
    haveBindlessTexture = 

    // GL_ARB_compute_shader may be loaded as an extension or as
    // part of OpenGL 4.3. It's necessary to check for both unless
    // you know you will never have a 4.3 context.
    haveComputeShader = 
        DerelictGL3.loadedVersion >= GLVersion.gl43 || 

This requires detailed knowledge about which extensions share declarations with a core version and which don’t. That information can be found online, and it’s also easy to see in the comments of the arb_*.d modules, but eventually I’ll have a list of everything in the online docs.

It’s also possible now to specify a maximum version of OpenGL to support at compile-time. This will only include the type, constant and function declarations up to and including the version you specify. The default includes everything up to the highest supported version (which is currently 4.5). To take advantage of this, you have to mixin a template with the desired version number, like so:

module mypackage.mygl;
public import derelict.opengl;
mixin glFreeFuncs!(GLVersion.gl33);

This example will configure DerelictGL3 to only include declarations up to and including OpenGL 3.3. Extensions can still be mixed in as in the previous example (note again, this is a template mixin, where as the extensions are string mixins — I’ve settled on using the template mixins where compile-time parameters are needed and the string mixins elsewhere). Finally, the version DerelictGL3_CustomFreeFuncs needs to be specified in your dub configuration (or compiler command line), otherwise DerelictGL3 will mixin its own declarations and conflicts will arise.

Another major new feature is support for context objects. Essentially, this eliminates the free functions and wraps them up in a struct. Instances can then be loaded for each OpenGL context you activate in your program. This way, there’s no need to call DerelictGL3.reload every time you switch contexts. Just load a context object once when the context is created and it will have the proper function pointers as long as the context is valid.

The default implementation, as with the free function approach, includes support for up to OpenGL 4.5 and no extensions. It can be declared like so:

module mypackage.mygl;
public import derelict.opengl;
mixin glContext;
GLContext myContext;

You will also need to specify the version DerelictGL3_Contexts in your dub configuration or compiler command line. Additionally, you can specify a maximum OpenGL version to support.

mixin glContext!(GLVersion.gl33);

With both approaches, you can then declare an instance of GLContext to load like so.

void initGraphics() {
    // You still need to call DerelictGL3.load at some point,
    // but this does not load *any* OpenGL functions when
    // when using contexts -- not even the base 1.1 functions.
    // It will only load the library.

    // Create your OpenGL context (Win32, GLFW3, SDL2, whatever)

    // Now load the context once and never worry about it again.

   // Call OpenGL functions through the context

You can declare multiple instances of GLContext and load one for each context in your program. Just make sure you always call the functions on the instance associated with the currently active context.

Unfortunately, it’s not possible to mixin extensions with the default GLContext implementation. Adding support for that would have complicated the implementation a good deal. Instead, it’s easy to declare your own context type and mixin everything you need.

public import derelict.opengl;

// Make sure DerelicGL3 is configured with context support.
version(DerelictGL3_Contexts) {

    // Assign the desired GL version to a manifest constant so
    // it need not be repeated below. If none is specified in 
    // the template mixins, the highest supported version will 
    // be used.
    enum glCore = GLVersion.gl33;

    // In order for everything to work, a number a few default
    // modules need to be imported. A string mixin handles that.

    // Next, it's a good idea to mixin the type and constant
    // delcarations outside of the struct declaration.
    mixin glDecls!glCore;

    // Ditto for any extensions you need

    // Now declare the context type. Call it whatever you want. 
    // You'll need to mixin the functions and their loaders for 
    // all of the supported versions. If you use extensions, 
    // you'll need to mixin their functions and provide a method, 
    // loadExtensions, with the mixed-in loaders.
    struct MyGLContext {
        mixin glFuncs!glCore;    // Function declarations
        mixin glLoaders!glCore;  // Function loader implementations
        // Now the extension functions

        // This is optional, but convenient
        bool hasBindlessTexture;
        bool hasComputeShader;

        // Finally, the extension loader
        void loadExtensions()
            // This ensures 'theLoader' is available

            // Extension loader implementations
            with(theLoader) {

    // Declare a context instance
    MyGLContext myContext;      
else static assert(0, 
    "This app requires -version=DerelictGL3_Contexts!");

When using a context, the context instance becomes the vehicle for testing for extensions and OpenGL versions, rather than DerelictGL3.

void initGraphics() {
    // All of these methods would normally be called on DerelictGL3 
    myContext.load();  // Instead of DerelictGL3.reload()

    writeln("Context version is ", myContext.contextVersion);
    writeln("Loaded version is ", myContext.loadedVersion);

    // Assuming the custom context from above
    myContext.hasBindlessTexture = 
    myContext.hasComputeShader = 
        myContext.loadedVersion >= GLVersion.gl43 ||

This is a massive and complex change. I have only scratched the surface in using it myself, so it has not been tested thoroughly. That said, it has worked flawlessly for me so far. I’m eager to discover any bugs that are sure to exist, so I need more people using it.

Currently, the deprecated OpenGL stuff has not been ported over. I intend to get to that before the end of the month. Then you’ll be able to mix that stuff in as well, if you need it.

DerelictFI 3.0.0-alpha.1

There were no public-facing additions or changes here, other than the dependency on the new DerelictUtil. Currently, there is no support for using DerelictFI as a static binding, though it’s likely that I’ll add it soon.

More to Come

Most of the packages in DerelictOrg are going to get upgraded to use DerelictUtil 3.0.0 and will also have alpha releases, though the lesser used and neglected ones (like DerelictCEF and DerelictIL) are not a priority. I expect to have the important packages ready to go by the end of this month. Then, if all goes well, I’ll drop the alpha suffixes in the beginning of the new year.

If you try any of the new stuff, please report any issues you find. Thanks!

New Derelict Documentation

I’ve given the Derelict documentation an overhaul. Before, I created all of the HTML files manually and painstakingly fiddled with the stylesheet until I had something that didn’t make my eyes bleed. Needless to say, that’s an inefficient way to manage the process.

A couple of months back I decided to start working on a new “book” project covering the usage of DUB. I intend it to be freely available on line and have no plans to publish it as a print or ebook. I’m come to think of it more in terms of documentation than anything else. Given that I really do not want to craft any HTML by hand in this case, I’ve been experimenting with different solutions when I could find an hour or two in my schedule to do so. I initially expected to use GitBook,  but in the end I settled on MkDocs. That inspired me to do something about the Derelict documentation.

I’m very happy about this decision. Using markdown for the docs and a tool that provides some nice styles out of the box makes it all much easier to manage. At this point, all of the existing documentation except the package-specific pages (or which only two exist at the moment) has been converted. A couple of pages that are linked from elsewhere (like all of the Derelict package READMEs) are still there and redirect to the new stuff.

Package-specific documentation is on hold for the moment. As I’ve mentioned in previous posts, I’m in the process of updating every package to use a new version of DerelictUtil. This will result in a major version bump for every package. Once that’s complete, I’ll get busy on the docs.

As for the DUB guide, it’s still on the TODO list. Now that I’ve finally settled on a system to use in developing it, I’ll start working on it in bits in pieces. Just be aware that I’m not devoting all of my resources to it. In addition to it and the Derelict docs, I’ve got a little side project I’m programming and I’m preparing to start work on a new novel (my fourth this year). The latter is taking priority over everything else, as I intend to end up with something I’m willing to publish. So, yes, the DUB guide is coming, but don’t expect it any time soon.

DerelictUtil and DerelictSDL2 Updates

DerelictSDL2 2.0.1 has been pushed to github and is ready in the DUB repository. Nothing major here, just some function signature corrections. If you aren’t using those functions, no need to worry.

DerelictUtil 2.1 is also ready to go. The minor version bump is due to a potential binary incompatibility for people who manage their projects manually (with DUB, it would only be a problem for people using >= in their dependency declarations). There’s one change here: DerelictException now correctly reports the file name and line number. This is something I have included with every custom exception class I’ve written since D’s __FILE__ and __LINE__ constants were made to apply at the call site when used as default function parameter values. DerelictException predates that change by a considerable margin and I never paid any attention to it after. A PR has rectified that oversight.

DerelictUtil 3.0 is currently sitting in a github branch, but not yet available in the DUB repository. It removes some cruft and adds some new utilities that previously were implemented in specific Derelict packages, but have proven to be useful in the general case. To avoid as much breakage as possible, I’m not going to tag a new release until I have updated every Derelict package with a new version the depends on it. This is a gradual process. The biggest work is on DerelictGL3, which is getting a massive overhaul and support for compile-time OGL version configuration and custom context objects. This default behavior will be the same as it is now (with a new package name), but the new features will allow unused bits of the OGL API, including extensions, to be eliminated from the binary. The lion’s share of that work is done and I’ll hopefully have time to wrap it up later this month. Then I can turn my attention to the other packages. I expect to have DerelictUtil 3.0 ready to go by the end of the year, but I readily admit I have a dismal track record with such predictions.

DerelictOGL: DerelictGL3 Reborn?

I’m currently experimenting with a new approach to loading OpenGL in Derelict. What I’ve done is to put all of the declarations into manifest constant strings according to GL version and set things up so that a loading function for each is automatically registered when the string is mixed in. So then you can do this:

import derelict.ogl;

// This is the new thing here

void main()
    // Load the shared library + OpenGL 1.1

    // Create an OpenGL context


So the approach for loading the shared library and then the extended versions and extensions is the same. Aside from the name changes, the only difference is the mixin at the top of the file. The idea is that you would create your own OpenGL module (e.g. mygl), publicly import derelict.ogl, then mixin the version you want along with any extensions you intend to use.

One goal is to reduce the binary size by getting rid of the cruft you don’t want to use. Another is to make it possible to actually mix the function pointers in to a context object rather than having them as globals. Whether or not this proves practical remains to be seen.

At the moment, I’ve hit a brick wall with OpenGL 3.0+. Given that some of the ARB extensions were promoted to core with the same function and type names (names that had no ARB suffix even in the extension specification) For example, the declarations in GL_ARB_framebuffer_object are the same in the extension as they are in OGL 3.0. I haven’t yet figured a way to implement the mixins such that the user can mixin both the extension and the 3.0 functions without a conflict.

I have no idea if this is going to prove feasible in the long run. If it does, this will almost certainly become a new package rather than DerelictGL3 2.0. If it doesn’t, well, it was an interesting diversion.

Loading Conditionally Compiled GLFW 3 Functions

Only a few days after the release of DerelictGLFW3 3.0, I’ve tagged a 3.1 release. Four functions that were loaded automatically no longer are and a new public function was added to the DerelictGLFW3 loader, hence the version bump. The reason for the change is because of a new feature that no other Derelict binding currently has.

Throughout the binding’s existence, I have largely ignored the conditionally compiled native functions in the GLFW API. I added two Windows-specific and two Mac-specific functions to the binding as part of a pull request some time ago. This was fine, as, even though they were conditionally compiled, they were always present on the given platforms. I was also able to implement the return values in a way that didn’t require any platform-specific type declarations that might conflict with, say, custom bindings to the Cocoa API on Mac.

More native functions were added in GLFW 3.1 and, in GLFW 3.2, functions that depend on the Vulkan API were added. I thought I could get away without implementing them initially and put it off to later, but a couple of days after I announced the new version, an issue was reported on github wiht a possible solution (using a subclass of DerelictGLFW3Loader specifically for Vulkan functions). In my previous post, I already had a solution in mind using string mixins. In the end, I implemented using template mixins instead and, after it was tested, tagged the 3.1 release.

The problem is that the functions are declared using types specific to external APIs, such as the Vulkan API, or the Win32 API. I would either have to use C-style generic types (void*) where possible or declare my own types in Derelict. That, as has been shown in the past, will only lead to conflicts when a user imports types declared in a different binding that and try to use the functions from DerelictGLFW3.

Moreover, while I can be guaranteed that the Windows- and Mac-specific functions will be present on (almost) any GLFW binaries on those platforms, the same cannot be said of EGL, Vulkan, Mir, Wayland, or even X11. Adding these directly to the loader by default will result in exceptions when they are not present, forcing nearly every GLFW user to work around that with the selective loading mechanism. Quite far from an ideal situation.

By using template mixins, client code can import any binding with the types they need and then use the relvant GLFW functions without fail. For example:

import : HWND, HGLRC;
import derelict.glfw3;

mixin DerelictGLFW3_WindowsBind;

With this, the three Windows-specific functions declared in glfw3native.h will be available in client code. When compiling DerelictGLFW3 as a static binding, that’s all that need be done. For the default dynamic binding, the functions still need to be loaded.

void main() {

The loaders load method must be called first, then the free fucniton that loads the mixed in functions can be called.

Obviously, is part of DRuntime and I could depend on that in Derelict without resorting to mixins, but for consistency the Windows stuff uses the same approach as the other conditionally compiled functions where I don’t have that luxury. You can read more about which mixins and loaders all available, including which ones alias to DerelictGLFW3_NativeBind and DerelictGLFW3_loadNative, in the DerelictGLFW3 documentation.

Note that the system-specific stuff in DerelictGL3 has the same potential problem with type conflicts. However, since I moved the to using the DRuntime Win32 bindings, that potential has dramatically decreased (seems no one really uses any of the platform-specific stuff there anyway). I will most likely apply this technique there anyway to help shrink the size of the bindings a bit. I also intend to explore using it with the OpenGL extensions.

But that’s for another day and another post. Now it’s back to bothering people via email in my pursuit of content for the new D Blog.

GLFW 3.2 Support in DerelictGLFW3

GLFW 3.2 was released very recently. I’ve (mostly) added support for it to DerelictGLFW3, available now in the DUB repository under the 3.0.0 tag. There are a couple of caveats, though. First, the bindings for the functions in glfwnative.h are still incomplete. Second, I did not add bindings to the new Vulkan-related functions. Both the native stuff and the Vulkan stuff have a couple of potential issues I need to work around.

The first problem is that they are all conditionally compiled, meaning they may not be available in any give GLFW3 binary. Properly supporting them means segmenting the specific declaration on the D side in version blocks. In order for client code to make use of the version blocks, I would need to add subconfigurations for each possible version combination for both the dynamic and static builds of DerelictGLFW3. Not pretty.

The second problem is that all of the affected functions rely on types defined outside of GLFW. If I were to declare any of those types, for example VkInstance, in DerelictGLFW3, it would conflict with any Vulkan bindings the client might be using, making it a completely distinct type (i.e. derelict.glfw3.types.VkInstance vs. whatever.types.VkInstance). Again, not pretty.

I suspect the solution to this will be a set of string mixins that the user use to declare everything in the appropriate context, so that the types are picked up from whatever binding is used to Vulkan, XWindows, Wayland, and all of that (for the Windows stuff at least, it’s now possible to rely on Phobos for the appropriate types, but for consistency I’ll probably add it to the mixin anyway). The mixins will also need to implement a custom loader for these specific functions. I have simple approach to this in mind, so that’s not a problem.

I’ll get a solution implemented at some point, but I’m in no hurry. For now, please enjoy using the core GLFW 3.2 API in D.

DerelictAllegro5 Now Supports Allegro 5.2

DerelictAllegro5 has been buggy for a while, but the latest 1.0.1 tag seems to work as intended. It binds to Allegro 5.2, which was released a couple of months back. I finally got around to the update earlier this week.

If you want to use Allegro 5.0 with Derelict, you still can with the 0.0.8 release of DerelcitAllegro5, but be aware that it’s almost certainly buggy. I neglected it for a long time and found some issues with it when I was updating and I didn’t bother to fix them. I’ll pull any PRs made against that branch that are sent my way, but new projects should be using Allegro 5.2 anyway. In other words, I tagged the 5.2 branch as 1.0 because I consider the 5.0 branch dead.

On a related note, GLFW 3.2 was officially announced not long before I started on this post. I expect to update DerelictGLFW3 at some point in the next few days.

DerelictPHYSFS 2.0.0

DerelictPHYSFS spent quite some time languishing at the bottom of the second page of DerelictOrg projects, starving for attention. I created it on a whim a couple years ago when I wanted to use PhysicsFS for a project that I subsequently abandoned. In the time since, there have been no PRs for the project, no emails asking for help, no enhancement requests, nothing. So there it sat, forgotten.

Recently, I’ve begun work on assembling a codebase from the numerous abandoned games and graphics projects scattered around my dev projects folder. That eventually led me back to DerelictPHYSFS and a simple wrapper I had made for it (see Defile). The README for DerelictPHYSFS was still pointing to the old, defunct documentation page on this blog, rather than to the pages at (which are still far from complete, but should currently be informative enough to use any Derelict package without much difficulty). The binding itself was stable. The 2.0.x API of PhysicsFS had not changed since I first made the binding (the last stable release, 2.0.3, was in October, 2012!), but the 2.1 API is what you get when building PhysicsFS from the development branch.

I normally don’t like to update Derelict bindings against unreleased versions of a C library, but in this case I think an exception is warranted. Any shared libraries built from the development branch of PhysFS would be compatible with the existing binding, but it would be nice to be able to make use of the newer API. So I’ve updated DerelictPHYSFS to the unreleased PhysicsFS 2.1. You can get that in the 2.1 branch on github, or through a dependency version of ~>2.0.0 in your dub configurations. The original binding is still there in the 2.0 branch, currently at version 1.0.3 as a dub dependency. I have no plans to update it further, unless someone is using it and really needs a bugfix (but I don’t think many people actually are using it).

I’ve also updated Defile to depend on the new version of DerelictPHYSFS. I intend to expand its API as I need it. It’s been available in the dub registry for quite some time and is still there for anyone who wants to use it. If you do, I make no promises about support. It’s a personal project that I decided to share with others and not something I intend to make room in my schedule to support for anyone other than me. Simple bug fixes or enhancements, maybe (definitely those that benefit me!), but anything time consuming? Forget it. Don’t let that discourage you from using it, though, if it’s something you need. It’s Boost licensed, so feel free to take it and do what you want with it.

There’s a lot of work I intend to get done with Derelict in the coming months. I need to update DerelictAllegro5 to Allegro 5.2 and get it into what I consider the right state for a 1.0.0 tag. I need to add support to DerelictLUA for Lua 5.1 so it can be used with LuaJIT. I also want to implement a static binding configuration for it like I did for DerelictGLFW3. I intend to do the same for a few other Derelict packages. I also need to work more on the documentation. That’s all competing with my plans for and the example project from the book, the game-oriented stuff I’ve been working on the past few weeks, and some writing projects (not related to D or anything tech) I’ve got underway. Anyone got any spare time for sale?

DerelictUtil 2.0.6

I’m currently working on a project where I decided to make use of the Derelict’s ability to load specific file names in some cases, but the default in others. That’s when I discovered something about DerelictUtil I had forgotten — it doesn’t allow for empty or null library name strings.

For reasons lost in the mists of time, I originally chose to use an empty arg overload that calls the single string arg version, which then asserts the string is not empty or null. If I were starting from scratch today, I would make it so the single string arg overload takes an empty string as a default argument. Instead, I’ve modified the single string version to use the default library names in case of null or empty strings. If you also would like to make use of this, you should require a minimum dependency of version 2.0.6.