GLFW3 now as a standalone, OS-agnostic platform

[johnmarianhoffman]

What is this?

This is a followup to my other pull request "New platform: GLFW3!" (#172). There seemed to be enough interest in actually leveraging GLFW's cross-platform nature for me to go ahead and make the changes necessary to get a fully cross platform version going. I was on vacation so I figured "why not..."

I will try to keep the notes here short since the "why" and "how" is already pretty well laid out in the other PR.

This PR just extends that work to Windows and Linux (and of course, Mac).

As of today, it is tested and working on:

• Windows 10
• Linux (Ubuntu 20.04 LTS)
• Mac OS 10.15.5

Thank you to @olc-slav, @MumflrFumperdink, and @Zij-IT for the help in testing and feedback while building.

Please feel free to reach out with any further suggestions or feedback!

Known "issue:"

I did my best to preserve exact behavior between the GLFW platform and the pre-existing platforms. With high-DPI screens such as Mac's Retina displays, or some Windows displays depending on configuration, there is a "scaling factor" applied to the screen. GLFW will only render into the native pixel sizes and will ignore this platform-level scaling factor. Windows in particular is very good about respecting this scaling factor.

While this is not truly a bug, just a difference in behavior, it does create a disparity between the native platforms and GLFW.

Fortunately GLFW gives us a tool to read the scaling factor from the monitor, which we can then pass to our "Contruct" method which will compensate for us, if we so desire:

int main()
{

	float xScale = 1.0f, yScale = 1.0f;

#if defined(__GLFW__)
	glfwInit();
	glfwGetMonitorContentScale(glfwGetPrimaryMonitor(), &xScale, &yScale);
	glfwTerminate();
#endif

	Example demo;
	if (demo.Construct(256, 240, xScale*3, yScale*3))
		demo.Start();
	return 0;

}

The above code is already present in olcExampleProgram.cpp of the PR.

Compiling instructions

All of the pre-existing compilations should work exactly as they did before (i.e. the core behavior of the PGE remains exactly the same).

Enabling GLFW (Mac, Linux, Windows)

To use the GLFW-flavored platform instead of the preexisting system platforms, add #define __GLFW__ before your #include "olcPixelGameEngine":

#define __GLFW__
#define OLC_PGE_APPLICATION
#include "olcPixelGameEngine.h"

Compiling

Mac:

clang++ -std=c++17 olcExampleProgram.cpp -o olcExampleProgram -lz -lpng -framework OpenGL -framework OpenGL -lglfw3 -framework Cocoa -framework IOKit -framework CoreFoundation 

Linux:

g++ -std=c++17 olcExampleProgram.cpp -o olcExampleProgram -lz -lpng -lglfw -lOpenGL -lpthread

Windows (with Visual Studio)

TL;DR:

Download the latest GLFW precompiled libraries and configure your project to use the \path\to\glfw-***\include for headers and link against the glfw3.lib library. Ensure you download and link against your desired architecture (32-bit or 64-bit).

(More) Detailed Instructions:

1. Download the latest release from https://www.glfw.org/ and unzip into a directory on your machine (for example C:\Users\username\Code)

2. Create a new, blank Visual Studio C++ project and copy the contents of olcExampleProgram.cpp into a new “main.cpp” file.

   (Note the contents of olcExampleProgram are different in the glfw_standalone_platform branch)

3. Add the olcPixelGameEngine.h header into the project

4. In your project settings (Project -> {solution name} Properties):

   1. Under “Configuration Properties” -> “C/C++” -> “All Options” add the glfw include directory to the “Additional Include Directories” property. E.g. C:\Users\username\Code\glfw-3.3.2\include
   2. Under “Configuration Properties” -> “Linker” -> “All Options”:
      1. add the directory containing the glfw library to the “additional library directories” property, and
      2. add “glfw3.lib” to the “Additional dependencies” property

[OneLoneCoder]

This seems like a big change, so i'll wait until conclusive evidence of correctness before bringing it in. Likely in 2.10

[johnmarianhoffman]

What tests would you like to see for correctness?

Additionally, with GLFW3, some sort of continuous integration testing would be easier to demonstrate correctness than manual environment configurations. I'm happy to demonstrate working setups to get things kicked off, however considering that it does require a 3rd party library (not prebaked for most OSes) there is more configuration necessary than existing platforms, so a longer-term solution might be something like Travis CI or Jenkins with some simple tests (i.e. compile the example program).

[OneLoneCoder]

Are you on our discord server? Its easier to discuss plans. In principle ive nothing against platforms/renderers that require stuff, Ive been working on an EGL version, and theres a DX11 version happening too. Since PGE is becoming useful to people, Im trying to coordinate a more professional testing/release/roadmap situation.

[johnmarianhoffman]

I am on the discord server, I just don't lurk too often. Happy to be present though for a discussion if there is a semi-set time (or a rough time) that people are chatting!

[kktos]

@johnmarianhoffman To make it more transparent (and easier to the eyes ;) ), could it be possible to put the GLFW bootstrap inside the Construct method ?

#if defined(__GLFW__)
	glfwInit();
	glfwGetMonitorContentScale(glfwGetPrimaryMonitor(), &xScale, &yScale);
	glfwTerminate();
#endif

[OneLoneCoder]

Im going to upset you now as 2.10 is coming very soon and introduces some incompatibilities im sure. It would be useful to examine this platform and let a few people on the discord server try it out.

[johnmarianhoffman]

It takes a whole heck of a lot more to upset me than some conflicts, but I appreciate the concern! :)

To be honest though things are fairly busy at work so I may not have much time to review for the next few weeks. I will likely be able to take a look in early February.

I will try and keep a closer eye on the Discord. Does most of the planning/discussing take place in #pixel-game-engine?