Check API availability for platform

dev
1

Not all parts of GLFW are supported on every platform that GLFW runs on. Some things, such as window icons, are not supported on MacOS. A new PR I created, adds support for application icons, but an implementation only exists for MacOS at the moment. For Wayland, several parts of GLFW are unavailable.

In order to determine if the current platform supports some functionality, the platform must first be queried with glfwGetPlatform, and then this result must be checked against a hard-coded set of rules, which were written specific to the GLFW documentation some time in the past.

I am wondering if perhaps GLFW should provide a means of acquiring the status of some given functionality, such as with a function called glfwPlatformSupportsAPI, glfwGetAPIAvailability or glfwGetAvailabilityStatus. Return values can be these sets of values:

  • GLFW_TRUE, GLFW_FALSE
  • GLFW_FEATURE_SUPPORTED, GLFW_FEATURE_UNIMPLEMENTED, GLFW_FEATURE_UNAVAILABLE

I believe that including information about every platform, is too heavy. Only information for the current platform, or all supported platforms in the compiled library should be available. This functionality could be optionally enabled or disabled with a compilation flag.

Personally, I prefer creating issues on Github, but I assume this is the preferred location, as I am looking for a discussion at the moment, rather than a hard request for the feature.

2

I am only a minor contributor to GLFW (as well as moderator on this forum), so my opinion likely doesn’t mean much, but my take would be that GLFW’s intention is to be platform independent and adding a platform status API goes against this.

Wayland is somewhat of an outlier as it was created after GLFW, and the design contravenes several windowing conventions.

Perhaps a simpler initial improvement might be to have a section in the documentation outlining the main platform differences?

3

Then surely my opinion means nothing. :wink:

This does not mean that GLFW has to be an obstacle to extending client usage with native API interaction, and that GLFW can not provide means of communicating platform differences to client code.

In order to provide a better experience for the end user, it’s often necessary to make a few adjustments based on the current platform. GLFW provides a very nice starting ground for cross-platform GUIs, but one of the powers of GLFW is that you can also build on top of it with platform specific code.

This is exactly the issue we’re currently having. Improving the documentation is never a bad thing, but it does not let clients dynamically check the state of the API implementations, (or otherwise statically in code). It requires reading the documentation, then creating some code to handle the different cases (best solution in several cases), then updating this every time the documentation changes. That’s harder to maintain.

Perhaps this might be a good addition to the documentation nonetheless, but I believe it would end up mostly being a “Wayland vs the rest”. I am more after the small differences between the platforms, and their details.

There’s a few things that GLFW doesn’t handle, so that clients must take special care. An example of this is that glfwRequestWindowAttention only bumps the MacOS Dock icon once. In order to bump it repeatedly, glfwRequestWindowAttention must be called repeatedly. This issue in particular, is best solved by updates to the documentation, as it’s not well expressed with API additions. So this is potentially an argument against such an addition to GLFW.

Usage of glfwSetWindowIcon, glfwRequestWindowAttention, and a few other functions, are good examples of when client code should act differently based on the underlying platform. I’m excluding Wayland here, as it differs in many ways from the other platforms. Windows and X11 are rather similar here, but MacOS does not support requesting attention for a given window, and GLFW does not support document windows (which would let clients set window icons on MacOS)[1], so depending on what the client wants to achieve, they have to check for the current platform, then branch their code appropriately.

  1. Even if GLFW supported document windows in Cocoa, setting the window icon on X11 and Windows also sets the Dock/taskbar icon, which does not happen on MacOS. ↩︎