glfw: window hints rework (#71)

* glfw: make comments into doc comments
* glfw: Publicize Window.CursorPos, Window.Size, Window.Pos, and Window.FrameSize
* glfw: Make enum value name the same format as other enum value names
* glfw: Window hints rework patch
* glfw: Relegate `Window.hint` to testing; move it down to just above the tests to reflect this, add doc comment line
* glfw: handle error `Error.InvalidEnum` explicitly, for clear error message in this unlikely edge case
* glfw: instate `Hint.context_no_error` as a hint, as it actually is specified to be a Window creation hint by the docs, and affirm removal of `Hint.context_revision`, which isn't.
The docs don't seem to specify a default value for `Hints.context_no_error` to take on, so we could set it based on `std.debug.runtime_safety` like this.
* glfw: default `context_no_error` to `false`, and added a note of caution about its usage as suggested.
* glfw: Inline enum values of `ClientApi`, `ContextCreationApi`, `ContextRobustness`, `ContextReleaseBehavior`, and `OpenGlProfile` from consts.zig, and remove the now unused constants (replaced by aformentioned enum values).
* glfw: Reference `Window.Hint` enum instead of `Window.Hints` struct to ensure fields are the same
* glfw: add comment explaining default values of `Window.Hints`
* glfw: change `OpenGlProfile` to `OpenGLProfile` based on established naming convention
* glfw: Update actual declaration of `OpenGLProfile`
* glfw: call `Window.defaultHints` after window creation, not before
* glfw: remove 'consts.zig', and move `dont_care` directly into 'main.zig'; fix anything referencing it.
* glfw: put `Window.defaultHints` into defer statement to handle cleanup in all paths
* glfw: move `Hint.focused` to match position of `Hints.focused`
* glfw: do 'zig fmt glfw/src'
* glfw: Cull `Window.Hint` comments, polish remaining; match order entirely according to current GLFW docs
* glfw: Change `Window.Hints.*Api` to `Window.Hints.*API`

Co-authored-by: Stephen Gutekanst <stephen@hexops.com>

README.md

@@ -71,7 +71,7 @@ pub fn main() !void {
     defer glfw.terminate();
 
     // Create our window
-    const window = try glfw.Window.create(640, 480, "Hello, mach-glfw!", null, null);
+    const window = try glfw.Window.create(640, 480, "Hello, mach-glfw!", null, null, .{});
     defer window.destroy();
 
     // Wait for the user to close the window.

src/consts.zig

@@ -1,31 +0,0 @@
-//! General constants
-
-const c = @import("c.zig").c;
-
-/// Possible values for glfw.Window.Hint.client_api hint
-pub const no_api = c.GLFW_NO_API;
-pub const opengl_api = c.GLFW_OPENGL_API;
-pub const opengl_es_api = c.GLFW_OPENGL_ES_API;
-
-/// Possible values for glfw.Window.Hint.context_robustness hint
-pub const no_robustness = c.GLFW_NO_ROBUSTNESS;
-pub const no_reset_notification = c.GLFW_NO_RESET_NOTIFICATION;
-pub const lose_context_on_reset = c.GLFW_LOSE_CONTEXT_ON_RESET;
-
-/// Possible values for glfw.Window.Hint.opengl_profile hint
-pub const opengl_any_profile = c.GLFW_OPENGL_ANY_PROFILE;
-pub const opengl_core_profile = c.GLFW_OPENGL_CORE_PROFILE;
-pub const opengl_compat_profile = c.GLFW_OPENGL_COMPAT_PROFILE;
-
-/// Possible values for glfw.Window.Hint.context_release_behavior hint
-pub const any_release_behavior = c.GLFW_ANY_RELEASE_BEHAVIOR;
-pub const release_behavior_flush = c.GLFW_RELEASE_BEHAVIOR_FLUSH;
-pub const release_behavior_none = c.GLFW_RELEASE_BEHAVIOR_NONE;
-
-/// Possible values for glfw.Window.Hint.context_creation_api hint
-pub const native_context_api = c.GLFW_NATIVE_CONTEXT_API;
-pub const egl_context_api = c.GLFW_EGL_CONTEXT_API;
-pub const osmesa_context_api = c.GLFW_OSMESA_CONTEXT_API;
-
-/// Possible value for various window hints, etc.
-pub const dont_care = c.GLFW_DONT_CARE;

src/main.zig

@@ -5,7 +5,9 @@ const c = @import("c.zig").c;
 
 const key = @import("key.zig");
 
-pub usingnamespace @import("consts.zig");
+/// Possible value for various window hints, etc.
+pub const dont_care = c.GLFW_DONT_CARE;
+
 pub const Error = @import("errors.zig").Error;
 const getError = @import("errors.zig").getError;
 
@@ -335,7 +337,7 @@ pub fn basicTest() !void {
     try init(.{});
     defer terminate();
 
-    const window = Window.create(640, 480, "GLFW example", null, null) catch |err| {
+    const window = Window.create(640, 480, "GLFW example", null, null, .{}) catch |err| {
         // return without fail, because most of our CI environments are headless / we cannot open
         // windows on them.
         std.debug.print("note: failed to create window: {}\n", .{err});

src/opengl.zig

@@ -171,7 +171,7 @@ test "makeContextCurrent" {
     try glfw.init(.{});
     defer glfw.terminate();
 
-    const window = glfw.Window.create(640, 480, "Hello, Zig!", null, null) catch |err| {
+    const window = glfw.Window.create(640, 480, "Hello, Zig!", null, null, .{}) catch |err| {
         // return without fail, because most of our CI environments are headless / we cannot open
         // windows on them.
         std.debug.print("note: failed to create window: {}\n", .{err});
@@ -199,7 +199,7 @@ test "swapInterval" {
     try glfw.init(.{});
     defer glfw.terminate();
 
-    const window = glfw.Window.create(640, 480, "Hello, Zig!", null, null) catch |err| {
+    const window = glfw.Window.create(640, 480, "Hello, Zig!", null, null, .{}) catch |err| {
         // return without fail, because most of our CI environments are headless / we cannot open
         // windows on them.
         std.debug.print("note: failed to create window: {}\n", .{err});
@@ -216,7 +216,7 @@ test "getProcAddress" {
     try glfw.init(.{});
     defer glfw.terminate();
 
-    const window = glfw.Window.create(640, 480, "Hello, Zig!", null, null) catch |err| {
+    const window = glfw.Window.create(640, 480, "Hello, Zig!", null, null, .{}) catch |err| {
         // return without fail, because most of our CI environments are headless / we cannot open
         // windows on them.
         std.debug.print("note: failed to create window: {}\n", .{err});
@@ -233,7 +233,7 @@ test "extensionSupported" {
     try glfw.init(.{});
     defer glfw.terminate();
 
-    const window = glfw.Window.create(640, 480, "Hello, Zig!", null, null) catch |err| {
+    const window = glfw.Window.create(640, 480, "Hello, Zig!", null, null, .{}) catch |err| {
         // return without fail, because most of our CI environments are headless / we cannot open
         // windows on them.
         std.debug.print("note: failed to create window: {}\n", .{err});