Overview of planned and rejected internal APIs to expose

dev
1

I originally created an issue on Github, before I discovered in the CONTRIBUTIONS.md file that this was highly discouraged for my type of issue. So I’ll paste the original text into here. Contributing to GLFW, where to find things, and where to write and discuss things, is very confusing.

Is there some kind of a roadmap or structured overview of which platform specific APIs that are planned, on hold, or declined, to be part of GLFW?

The milestones do not specifically list exactly which APIs we/you want to expose/wrap or not.

For those of us working with GLFW through a wrapper, in a non-native language (such as Java + LWJGL), interacting with these native APIs is not a happy experience. So for that purpose, the more that gets put into GLFW, the better. This comes with a great risk of bloating GLFW, as well as piping platform specific APIs through GLFW in a way that later hampers or prevents platform-agnostic APIs from being added. There’s also a risk of introducing APIs that provide subpar and severely limited functionality of the native API, and interfere with client code’s attempts at working with the native API for platform-specific features. There’s a lot of open issues, much more than @elmindreda and other important developers can work on alone. For example, I have tried looking into helping with MacOS code, but the more I look at it, the more Cocoa functionality I discover, that would be a great addition to GLFW seen from the perspective of MacOS, but not necessarily from other perspectives.

This might not be an issue to those of you that know all the different platforms very well (MacOS, Windows, X11, Wayland), but I believe it can be a valuable resource to those of us that don’t. I know the capabilities and limitations of Cocoa, but not the other platforms, and even if multiple platforms support similar functionality, I don’t know how to best bridge them. If similar functionality exists across platforms, and it’s been decided that wrapping this in GLFW is a good addition to GLFW itself, such efforts are best discussed in dedicated issues or PRs.

GLFW wraps/exposes certain platform-gnostic APIs, not only for compatibility reasons, but also simplifying common tasks. It would be nice to know which ones should not be exposed, which ones should be exposed in a platform-gnostic way, and which ones in a platform-agnostic way.

I also wonder what the overall plans for GLFW 4.0 are, and which parts of the library are supposed to be redesigned, and the reasons behind it. Many of the issues and PRs for GLFW were created many years ago, and the discussions in them span several years. I believe the lack of a greater overview raises the bar for participation, raises the risk of incompatibly adding functionality, greatly increases development time, and puts more strain on everyone that maintains, develops and contributes to GLFW.

There is also a chance that I myself have come to request this, because I failed at navigating the issues, and building myself a mental overview. Discussions in issues and PRs are scattered, and it’s not necessarily easy to search for discussions revolving a particular platform’s API. I may also be somewhat impatient. My apologies if I made a mistake here. Perhaps it is best if each of these native APIs are discussed in dedicated issues, from start to end?

2

TL;DR Very good points. All of the things you mention need to be documented better, and the existing bits of documentation need to be updated and gathered or linked. Would you be interested in helping with this?

Not anymore, but there probably should be, in some form. Essentially, anything directly related to top-level windows, HID input (other than audio or video), display monitors, bridging rendering APIs or is intrinsically tied to those things is up for consideration.

The reason I hesitate to that the boundary is both fuzzy and in motion. I would for example consider bits of theming (light/dark mode) and power management (activities) in scope for GLFW now, but it wasn’t originally. I worry a little that it would dissuade people from pointing out things like that.

Yep. That is a good summary of the tension.

Yup, and that’s true for every platform. They all have nifty things that don’t fit well into something like GLFW. I’m working on improving how well GLFW co-exists with other code using the same underlying APIs and/or related ones, so that more things are at least possible. Some of that has been released already.

The most important bit of 4.0 will be to decouple various functions and features. There are some very non-orthogonal bits of the API that stem from an earlier, more limited idea of what GLFW was for, and those limit what can be added to the existing API.

For example a window being focused when shown, windows coupled tightly to video modes, windows coupled tightly to OpenGL contexts, full screen windows not being hide-able, legacy OpenGL being the default everywhere, idle inhibiting tied to full screen, etc.

The remaining bits that must be done are fixes to naming and function signatures.

The documentation for these bits of GLFW are either outdated, incomplete or non-existent, so no, it’s not you. With regard to platform APIs specifically, the Github labels may be helpful.

Sorry, I’m not sure what you mean here. One issue per feature per platform API?

3

Of course; I’m already here in the interest of helping, but I have limited exposure to the internals of GLFW, and past discussions. Do you have any specific ideas in mind, or should I throw myself into it? A ROADMAP.md file? Platform APIs overview.md? A linked issue? Or perhaps a link to a thread on this site? The wiki could likely use some updates with contributor help as well.

If you have any links to past/current discussions/content you believe are important to stay updated on, please share that.

As long as these overviews are regularly maintained and updated, and the discussions are kept alive, or given a definite answer, such a boundary can be kept as a moving line. Subjects are added to the roadmap when they’ve been deemed a good fit for GLFW, and we are sufficiently confident they can be implemented in a unified manner across all platforms, without causing noteworthy problems to those that need extra platform-specific. They are removed or put on hold if large problems with such a feature are discovered, and no immediate solution is present. This does not sound like an unmaintable job whatsoever.

I’m not sure if I follow. Are you worried that if we maintain a roadmap and overview of APIs and our view on them, that people will refrain from sharing their opinions on these matters?

Is there anywhere specific I can go to read more about this, or will I have to crawl the PRs and issues on Github?

I meant one issue per constrained API for a given platform. So one issue for one part of Cocoa, and another issue for a similar part of Win32, etc. I do not believe this is a good idea, though. It only scatters the pieces more.

Thanks for your reply. It provides a useful starting ground for building what’s needed. :slight_smile:

4

Do you have an idea of the boundary of this? Obviously, temporarily preventing sleep is a minimum, but there are many more possibilities. For example, the list of Win32 power management functions reveals quite a lot of functionality, and supporting everything might not be a good idea. However, some applications may want a lot of that, so it’s possible a sibling project should be developed in addition to GLFW, as an addon/extension to GLFW, instead of only providing a subset of that functionality in GLFW.

Adding only minor power management functionality to GLFW risks creating a similar situation as with the GLFW threading, which was removed from GLFW, but that might not be a problem.