glfw-d 1.0.1

D translation of GLFW, a multi-platform library for OpenGL, OpenGL ES, Vulkan, window and input


To use this package, run the following command in your project's root directory:


This package provides sub packages which can be used individually:

glfw-d:example - opens a GLFW window

GLFW-D

A translation from C to D of GLFW version 3.3.2 (commit 0a49ef0).

GLFW is a multi-platform library for OpenGL, OpenGL ES, Vulkan, window and input. (See also: what is GLFW)

GLFW has 5 targets, but currently only three are availabe in this translation.

GLFW TargetTranslatedPrimarily used for
Win32✔️ YesWindows
X11✔️ YesLinux (older)
Cocoa❌ NomacOS
Wayland❌ NoLinux (newer)
Osmesa✔️ YesOff-screen rendering (?)

The translation sticks close to the C source code, so all uses of e.g. memcpy, printf and pointer arithmetic are intact and not replaced with idiomatic D. The Doxygen documentation in glfw.h and glfwnative.h (here glfw3/api.d and glfw3/apinative.d) is translated to use DDoc Params: and Returns: sections.

The translation is licensed under the zlib/libpng license like the original code. The translation is not affiliated with the original project.

Basic usage

If you are using dub, add this package as a dependency. In dub.sdl:

dependency "glfw-d" version="~>1.0.1"

In dub.json:

"dependencies": {
	"glfw-d": "~>1.0.1"
}

Then you should be ready to go.

import glfw3.api;

void main() {
	// call GLFW functions, such as:
	glfwInit();
	glfwTerminate();
}

Check out the example subpackage for an example of a GLFW application that creates a window and reads input:

dub run glfw-d:example

Note that you probably want to use OpenGL / Vulkan bindings (bindbc-opengl or erupted) in order to actually display anything in your window.

See also: the tutorial on glfw.org

Reasons for using it

Using GLFW in your D project usually involves depending on a binding to the C-library, (such as bindbc-glfw or derelict-glfw3). You'd then include a glfw3.dll with your releases for Windows users, and ask Linux users to install glfw using their package manager. Your application then has to call a function that loads the function pointers at runtime, and then you check whether that succeeded or whether the shared library was missing or corrupted.

If you statically linked to GLFW, you don't have the hassle of run-time loading: everything you need is in the executable itself. You could add pre-compiled static libraries to your repository, but you need to have one for each combination of settings you want: Windows / Linux, 32-bit / 64-bit, debug / release, etc. You also need to make sure to link the correct C runtime library (e.g. libcmt.lib / msvcrt.dll). It's very easy for issues to arise:

With this translation, you can simply use Dub, and your D compiler settings (C runtime, optimization flags, debug info) also apply to GLFW.

Compile times are pretty short. I get these results from the 'total' time of time dub build glfw-d --force on Debian Linux:

build typetime (s)
dmd debug0.5
dmd release1.1
ldc2 debug1.0
ldc2 release2.7

Dub caches builds, so these compile times only apply the first time.

Disadvantages

  • The C sources are more battle-tested. There is a chance the translation introduced new bugs.
  • While GLFW is pretty stable, it is still being maintained by a group of contributors and new releases with new features and fixes come out. Once GLFW 3.4 comes out, this translation will lag behind for who knows how long. However, you can always switch back to compiling the C sources.

Todo

  • Thoroughly test on platforms So far I used this library for my own OpenGL application and succesfully ran it on Debian Linux with X11 and Windows 7, but there are aspects that are not yet tested. I have not used this with Vulkan or OpenGL ES. I haven't used the native api (glfw3/apinative.d here) or functions for custom cursor creation yet.

  • Add Wayland support This platform needs to be translated still.

  • Add Cocoa support. This is low priority though since I don't have a computer that runs macOS and have little personal interest in this platform.

Advanced usage

Adding glfw-d to an existing D application using GLFW

If you are already using different static bindings to GLFW (e.g. bindbc-glfw with BindGLFW_Static), you can still use those with this package: You don't have to change import bindbc.glfw; to import glfw3.api;. Simply add the dependency to glfw-d and remove the linkage with the C library from libs, sourceFiles or lflags in your dub file.

Configurations

Dub should automatically pick a configuration based on your operating system. If you are on Linux but don't want to use the x11 target, you can e.g. add to your dub.sdl:

subConfiguration "glfw-d" "osmesa"

Or dub.json:

"subConfigurations": {
	"glfw-d": "osmesa"
}

To expose the native API, set the appropriate version identifiers. The available window API versions are:

  • GLFW_EXPOSE_NATIVE_WIN32
  • GLFW_EXPOSE_NATIVE_COCOA
  • GLFW_EXPOSE_NATIVE_X11
  • GLFW_EXPOSE_NATIVE_WAYLAND

The available context API versions are:

  • GLFW_EXPOSE_NATIVE_WGL
  • GLFW_EXPOSE_NATIVE_NSGL
  • GLFW_EXPOSE_NATIVE_GLX
  • GLFW_EXPOSE_NATIVE_EGL
  • GLFW_EXPOSE_NATIVE_OSMESA

Example dub.sdl:

versions "GLFW_EXPOSE_NATIVE_WIN32" "GLFW_EXPOSE_NATIVE_WGL"

dub.json:

"versions": ["GLFW_EXPOSE_NATIVE_WIN32", "GLFW_EXPOSE_NATIVE_WGL"]

Compiling manually

If you don't want to use dub, it is not hard to compile it manually since all source files you need are in a single folder: source/glfw3. Look in dub.sdl which source files and version identifier your desired platform uses, then pass them to a D compiler:

# from the root of this repository
cd source/glfw3
dmd -version=_GLFW_WIN32 -I../ -m64 -lib -of=../../build/glfw.lib context.d init.d input.d monitor.d vulkan.d window.d mappings.d internal.d api.d win32_platform.d win32_init.d win32_joystick.d win32_monitor.d win32_time.d win32_thread.d win32_window.d wgl_context.d egl_context.d osmesa_context.d directinput8.d

BetterC

Since it's a direct translation of a C codebase, it might compile with -betterC, but there might be linking errors because of certain C macros that are functions in druntime, such as:

core.sys.posix.sys.select.FD_SET
core.sys.posix.sys.select.FD_ZERO

This might or might not give linker errors in your application, depending on your compiler and settings.

Building a shared library DLL

Building a shared library from the D sources should be possible, but I haven't tried it yet. It may be as simple as adding export to functions that had GLFWAPI in the C sources, and adding a configuration with targetType "sharedLibrary" in dub.sdl, but it also may be more difficult than that.

Authors:
  • dkorpel
Sub packages:
glfw-d:example
Dependencies:
none
Versions:
1.0.1 2020-Aug-20
1.0.0 2020-Aug-19
~master 2020-Sep-02
~develop 2020-Sep-02
Show all 4 versions
Download Stats:
  • 1 downloads today

  • 1 downloads this week

  • 16 downloads this month

  • 16 downloads total

Score:
0.3
Short URL:
glfw-d.dub.pm