Adds OpenGL swap interval documentation.

1 files changed, 22 insertions, 0 deletions

diff --git a/src/Fl_Gl_Window.cxx b/src/Fl_Gl_Window.cxx
index b59d7d5de..4912765c7 100644
--- a/src/Fl_Gl_Window.cxx
+++ b/src/Fl_Gl_Window.cxx
@@ -163,6 +163,14 @@ void Fl_Gl_Window::swap_buffers() {
 
 /**
  Sets the rate at which the GL windows swaps buffers.
+ This method can be called after the OpenGL context was created, typically
+ within the user overridden `Fl_Gl_Window::draw()` method that will be
+ overridden by the user.
+ \note This method depends highly on the underlying OpenGL contexts and driver
+    implementation. Most driver seem to accept only 0 and 1 to swap buffer
+    asynchronously or in sync with the vertical blank.
+ \param[in] frames set the number of vertical frame blanks between OpenGL
+    buffer swaps
  */
 void Fl_Gl_Window::swap_interval(int frames) {
   pGlWindowDriver->swap_interval(frames);
@@ -170,6 +178,20 @@ void Fl_Gl_Window::swap_interval(int frames) {
 
 /**
  Gets the rate at which the GL windows swaps buffers.
+ This method can be called after the OpenGL context was created, typically
+ within the user overridden `Fl_Gl_Window::draw()` method that will be
+ overridden by the user.
+ \note This method depends highly on the underlying OpenGL contexts and driver
+    implementation. Some drivers return no information, most drivers don't
+    support intervals with multiple frames and return only 0 or 1.
+ \note Some drivers have the ability to set the swap interval but no way
+    to query it, hence this method may return -1 even though the interval was
+    set correctly. Conversely a return value greater zero does not guarantee
+    that the driver actually honors the setting.
+ \return an integer greater zero if vertical blanking is taken into account
+    when swapping OpenGL buffers
+ \return 0 if the vertical blanking is ignored
+ \return -1 if the information can not be retrieved
  */
 int Fl_Gl_Window::swap_interval() const {
   return pGlWindowDriver->swap_interval();