From 5e48d25cdbe69b40229e9eea0d98744d377f82c7 Mon Sep 17 00:00:00 2001
From: dcnieho <dcnieho@7f0cb862-5218-0410-a997-914c9d46530a>
Date: Fri, 1 Mar 2013 07:15:20 +0000
Subject: [PATCH] document coordinates returned by glutPositionFunc, other doc
 improvements regarding docs

git-svn-id: https://svn.code.sf.net/p/freeglut/code/trunk@1538 7f0cb862-5218-0410-a997-914c9d46530a
---
 freeglut/freeglut/src/mswin/fg_main_mswin.c |  5 ++++
 freeglut/web-src/docs/api.php               | 29 ++++++++++++++++-----
 2 files changed, 27 insertions(+), 7 deletions(-)

diff --git a/freeglut/freeglut/src/mswin/fg_main_mswin.c b/freeglut/freeglut/src/mswin/fg_main_mswin.c
index be412ba..a791222 100644
--- a/freeglut/freeglut/src/mswin/fg_main_mswin.c
+++ b/freeglut/freeglut/src/mswin/fg_main_mswin.c
@@ -536,6 +536,11 @@ LRESULT CALLBACK fgPlatformWindowProc( HWND hWnd, UINT uMsg, WPARAM wParam, LPAR
             /* Check window visible, we don't want to call the position callback when the user minimized the window */
             if (window->State.Visible)
             {
+                /* Get top-left of non-client area of window, matching coordinates of
+                 * glutInitPosition and glutPositionWindow, but not those of 
+                 * glutGet(GLUT_WINDOW_X) and glutGet(GLUT_WINDOW_Y), which return
+                 * top-left of client area.
+                 */
                 GetWindowRect( window->Window.Handle, &windowRect );
             
                 if (window->Parent)
diff --git a/freeglut/web-src/docs/api.php b/freeglut/web-src/docs/api.php
index 7b96502..c8d0a7d 100644
--- a/freeglut/web-src/docs/api.php
+++ b/freeglut/web-src/docs/api.php
@@ -303,13 +303,18 @@ sizes in order to subtract them off the window's initial position until
 some time after the window has been created.  Therefore we decided on
 the following behavior, both under Windows and under UNIX/X11:
 <ul><li>When you create a window with position (x,y) and size (w,h), the
-upper left hand corner of the outside of the window is at (x,y) and the
-size of the drawable area is (w,h).
-<li>When you query the size and position of the window <i>freeglut</i>
-will return the size of the drawable area--the (w,h) that you specified
-when you created the window--and the coordinates of the upper left hand
-corner of the drawable area--which is <u>NOT</u> the (x,y) position of
-the window you specified when you created it.</ul>
+upper left hand corner of the outside of the window (the non-client
+area) is at (x,y) and the size of the drawable (client) area is (w,h).
+The coordinates taken by <tt>glutInitPosition</tt> and
+<tt>glutPositionWindow</tt>, as well as the coordinates provided by
+<i>FreeGLUT</i> when it calls the <tt>glutPositionFunc</tt> callback,
+specify the top-left of the non-client area of the window.</li>
+<li>When you query the size and position of the window using
+<tt>glutGet</tt>, <i>FreeGLUT</i> will return the size of the drawable
+area--the (w,h) that you specified when you created the window--and the
+coordinates of the upper left hand corner of the drawable (client)
+area--which is <u>NOT</u> the (x,y) position of the window you specified
+when you created it.</ul>
 </p>
 
 <h2>3.3 Terminology</h2>
@@ -884,6 +889,16 @@ repositioned/moved programatically or by the user.
 <p><tt>void glutPositionFunc ( void
 (* callback)( int x, int y) );</tt></p>
 
+<p><b>Description</b></p>
+
+<p>When <i>FreeGLUT</i> calls this callback, it provides the new
+position on the screen of the top-left of the <u>non-client area</u>,
+that is, the same coordinates used by <tt>glutInitPosition</tt> and
+<tt>glutPositionWindow</tt>. To get the position on the screen of the
+top-left of the client area, use <tt>glutGet(GLUT_WINDOW_X)</tt> and
+<tt>glutGet(GLUT_WINDOW_Y)</tt>. See <a href="#Conventions">FreeGLUT's
+conventions</a> for more information.</p>
+
 <p><b>Changes From GLUT</b></p>
 
 <p>This function is not implemented in GLUT.</p>