From b9d4875f3e05876035eb773ea6e69ccc9b359e1d Mon Sep 17 00:00:00 2001
From: Camilla Berglund <elmindreda@elmindreda.org>
Date: Sun, 10 Nov 2013 13:56:27 +0100
Subject: [PATCH] Improved documentation of hacks.

---
 deps/GL/glext.h    | 3 +++
 src/cocoa_window.m | 7 +++++--
 src/context.c      | 4 ++--
 src/glx_context.c  | 7 ++++---
 src/x11_window.c   | 9 ++++++---
 5 files changed, 20 insertions(+), 10 deletions(-)

diff --git a/deps/GL/glext.h b/deps/GL/glext.h
index acb46983..4edeae9f 100644
--- a/deps/GL/glext.h
+++ b/deps/GL/glext.h
@@ -4130,6 +4130,9 @@ GLAPI void APIENTRY glVertexBlendARB (GLint count);
 
 #ifndef GL_ARB_vertex_buffer_object
 #define GL_ARB_vertex_buffer_object 1
+/* HACK: This is a workaround for gltypes.h on OS X 10.9 defining these types as
+ *       long instead of ptrdiff_t
+ */
 #if defined(__APPLE__)
 typedef long GLsizeiptrARB;
 typedef long GLintptrARB;
diff --git a/src/cocoa_window.m b/src/cocoa_window.m
index 48e4d703..24a41fa0 100644
--- a/src/cocoa_window.m
+++ b/src/cocoa_window.m
@@ -67,7 +67,7 @@ static void enterFullscreenMode(_GLFWwindow* window)
                              withOptions:options];
 
     // HACK: Synthesize focus event as window does not become key when the view
-    // is made full screen
+    //       is made full screen
     // TODO: Remove this when moving to a full screen window
     _glfwInputWindowFocus(window, GL_TRUE);
 }
@@ -80,7 +80,7 @@ static void leaveFullscreenMode(_GLFWwindow* window)
         return;
 
     // HACK: Synthesize focus event as window does not become key when the view
-    // is made full screen
+    //       is made full screen
     // TODO: Remove this when moving to a full screen window
     _glfwInputWindowFocus(window, GL_FALSE);
 
@@ -1036,6 +1036,9 @@ void _glfwPlatformRestoreWindow(_GLFWwindow* window)
 void _glfwPlatformShowWindow(_GLFWwindow* window)
 {
     // Make us the active application
+    // HACK: This has been moved here from initializeAppKit to prevent
+    //       applications using only hidden windows from being activated, but
+    //       should probably not be done every time any window is shown
     [NSApp activateIgnoringOtherApps:YES];
 
     [window->ns.object makeKeyAndOrderFront:nil];
diff --git a/src/context.c b/src/context.c
index cdc9d911..9279af8e 100644
--- a/src/context.c
+++ b/src/context.c
@@ -402,8 +402,8 @@ GLboolean _glfwRefreshContextAttribs(void)
             else if (glfwExtensionSupported("GL_ARB_debug_output"))
             {
                 // HACK: This is a workaround for older drivers (pre KHR_debug)
-                // not setting the debug bit in the context flags for debug
-                // contexts
+                //       not setting the debug bit in the context flags for
+                //       debug contexts
                 window->glDebug = GL_TRUE;
             }
         }
diff --git a/src/glx_context.c b/src/glx_context.c
index 58c25757..824ffab3 100644
--- a/src/glx_context.c
+++ b/src/glx_context.c
@@ -75,7 +75,7 @@ static GLboolean chooseFBConfig(const _GLFWfbconfig* desired, GLXFBConfig* resul
     if (strcmp(vendor, "Chromium") == 0)
     {
         // HACK: This is a (hopefully temporary) workaround for Chromium
-        // (VirtualBox GL) not setting the window bit on any GLXFBConfigs
+        //       (VirtualBox GL) not setting the window bit on any GLXFBConfigs
         trustWindowBit = GL_FALSE;
     }
 
@@ -485,8 +485,9 @@ int _glfwCreateContext(_GLFWwindow* window,
         if (window->glx.context == NULL)
         {
             // HACK: This is a fallback for the broken Mesa implementation of
-            // GLX_ARB_create_context_profile, which fails default 1.0 context
-            // creation with a GLXBadProfileARB error in violation of the spec
+            //       GLX_ARB_create_context_profile, which fails default 1.0
+            //       context creation with a GLXBadProfileARB error in violation
+            //       of the extension spec
             if (_glfw.x11.errorCode == _glfw.glx.errorBase + GLXBadProfileARB &&
                 wndconfig->clientAPI == GLFW_OPENGL_API &&
                 wndconfig->glProfile == GLFW_OPENGL_ANY_PROFILE &&
diff --git a/src/x11_window.c b/src/x11_window.c
index ac78a154..f5fba1b3 100644
--- a/src/x11_window.c
+++ b/src/x11_window.c
@@ -129,8 +129,8 @@ static GLboolean createWindow(_GLFWwindow* window,
         if (wndconfig->monitor == NULL)
         {
             // HACK: This is a workaround for windows without a background pixel
-            // not getting any decorations on certain older versions of Compiz
-            // running on Intel hardware
+            //       not getting any decorations on certain older versions of
+            //       Compiz running on Intel hardware
             wa.background_pixel = BlackPixel(_glfw.x11.display,
                                              _glfw.x11.screen);
             wamask |= CWBackPixel;
@@ -258,6 +258,9 @@ static GLboolean createWindow(_GLFWwindow* window,
         }
         else
         {
+            // HACK: Explicitly setting PPosition to any value causes some WMs,
+            //       notably Compiz and Metacity, to honor the position of
+            //       unmapped windows set by XMoveWindow
             hints->flags |= PPosition;
             hints->x = hints->y = 0;
         }
@@ -275,7 +278,7 @@ static GLboolean createWindow(_GLFWwindow* window,
 
     // Set ICCCM WM_CLASS property
     // HACK: Until a mechanism for specifying the application name is added, the
-    // initial window title is used as the window class name
+    //       initial window title is used as the window class name
     if (strlen(wndconfig->title))
     {
         XClassHint* hint = XAllocClassHint();