Merge pull request #2038 from robertpfeiffer/better-vsync

Display doc changes

Author: MyreMylar

docs/reST/ref/display.rst

@@ -171,10 +171,15 @@ required).
 
    .. versionadded:: 2.0.0 ``SCALED``, ``SHOWN`` and ``HIDDEN``
 
+   .. versionadded:: 2.0.0 ``vsync`` parameter
+
    By setting the ``vsync`` parameter to ``1``, it is possible to get a display
-   with vertical sync at a constant frame rate. Subsequent calls to
-   :func:`pygame.display.flip()` will block (i.e. *wait*) until the screen has
-   refreshed.
+   with vertical sync at a constant frame rate determined by the monitor and
+   graphics drivers. Subsequent calls to :func:`pygame.display.flip()` or
+   :func:`pygame.display.update()` will block (i.e. *wait*) until the screen
+   has refreshed, in order to prevent "screen tearing"
+   <https://en.wikipedia.org/wiki/Screen_tearing>.
+
    Be careful when using this feature together with ``pygame.time.Clock`` or
    :func:`pygame.time.delay()`, as multiple forms of waiting and frame rate
    limiting may interact to cause skipped frames.
@@ -185,7 +190,7 @@ required).
    ``set_mode()`` may raise an exception.
 
    Setting the ``vsync`` parameter to ``-1`` in conjunction with  ``OPENGL``
-   will request the OpenGL-specific feature "adaptive vsync".
+   will request the OpenGL-specific feature "adaptive vsync" <https://www.khronos.org/opengl/wiki/Swap_Interval#Adaptive_Vsync>.
 
    Here is an example usage of a call
    to ``set_mode()`` that may give you a display with vsync:
@@ -739,9 +744,20 @@ required).
 
    .. versionaddedold:: 2.0.0
 
+.. function:: is_fullscreen
+
+   | :sl:`Returns True if the pygame window created by pygame.display.set_mode() is in full-screen mode`
+   | :sg:`is_fullscreen() -> bool`
+
+   Edge cases:
+   If the window is in windowed mode, but maximized, this will return `False`.
+   If the window is in "borderless fullscreen" mode, this will return `True`.
+
+   .. versionadded:: 2.2.0
+
 .. function:: is_vsync
 
-   | :sl:`Returns True if vertical synchronisation for pygame.display.flip() is enabled`
+   | :sl:`Returns True if vertical synchronisation for pygame.display.flip() and pygame.display.update() is enabled`
    | :sg:`is_vsync() -> bool`
 
    .. versionadded:: 2.2.0

examples/glcube.py

@@ -41,7 +41,6 @@
     print("numpy missing. The GLCUBE example requires: pyopengl numpy")
     raise SystemExit
 
-
 # do we want to use the 'modern' OpenGL API or the old one?
 # This example shows you how to do both.
 USE_MODERN_GL = True
@@ -508,7 +507,7 @@ def draw_cube_modern(shader_data, filled_cube_indices, outline_cube_indices, rot
 
     # Rotate cube
     # rotation.theta += 1.0  # degrees
-    rotation.phi += 1.0  # degrees
+    # rotation.phi += 1.0  # degrees
     # rotation.psi += 1.0  # degrees
     model = eye(4, dtype=float32)
     # rotate(model, rotation.theta, 0, 0, 1)
@@ -521,7 +520,9 @@ def main():
     """run the demo"""
 
     # initialize pygame-ce and setup an opengl display
+
     pygame.init()
+    clock = pygame.time.Clock()
 
     gl_version = (3, 0)  # GL Version number (Major, Minor)
     if USE_MODERN_GL:
@@ -535,19 +536,24 @@ def main():
             pygame.GL_CONTEXT_PROFILE_MASK, pygame.GL_CONTEXT_PROFILE_CORE
         )
 
-    fullscreen = False  # start in windowed mode
-
+    # start in windowed mode
     display_size = (640, 480)
-    pygame.display.set_mode(
-        display_size, pygame.OPENGL | pygame.DOUBLEBUF | pygame.RESIZABLE
-    )
+    try:
+        pygame.display.set_mode(
+            display_size, pygame.OPENGL | pygame.DOUBLEBUF | pygame.RESIZABLE, vsync=1
+        )
+    except:
+        pygame.display.set_mode(
+            display_size, pygame.OPENGL | pygame.DOUBLEBUF | pygame.RESIZABLE
+        )
 
     if USE_MODERN_GL:
         gpu, f_indices, o_indices = init_gl_modern(display_size)
         rotation = Rotation()
     else:
         init_gl_stuff_old()
 
+    delta_time = 0
     going = True
     while going:
         # check for quit'n events
@@ -559,34 +565,41 @@ def main():
                 going = False
 
             elif event.type == pygame.KEYDOWN and event.key == pygame.K_f:
-                if not fullscreen:
+                if not pygame.display.is_fullscreen():
                     print("Changing to FULLSCREEN")
                     pygame.display.set_mode(
-                        (640, 480), pygame.OPENGL | pygame.DOUBLEBUF | pygame.FULLSCREEN
+                        display_size,
+                        pygame.OPENGL | pygame.DOUBLEBUF | pygame.FULLSCREEN,
                     )
                 else:
                     print("Changing to windowed mode")
                     pygame.display.set_mode(
-                        (640, 480), pygame.OPENGL | pygame.DOUBLEBUF
+                        display_size, pygame.OPENGL | pygame.DOUBLEBUF
                     )
-                fullscreen = not fullscreen
+
                 if gl_version[0] >= 4 or (gl_version[0] == 3 and gl_version[1] >= 2):
                     gpu, f_indices, o_indices = init_gl_modern(display_size)
                     rotation = Rotation()
                 else:
                     init_gl_stuff_old()
 
+        # orbit camera around by 60 degrees per second
+        angle = (delta_time / 1000) * 60
         if USE_MODERN_GL:
+            rotation.phi += angle
             draw_cube_modern(gpu, f_indices, o_indices, rotation)
         else:
             # clear screen and move camera
             GL.glClear(GL.GL_COLOR_BUFFER_BIT | GL.GL_DEPTH_BUFFER_BIT)
-            # orbit camera around by 1 degree
-            GL.glRotatef(1, 0, 1, 0)
+            # rotate camera to angle
+            GL.glRotatef(angle, 0, 1, 0)
             drawcube_old()
 
         pygame.display.flip()
-        pygame.time.wait(10)
+        if pygame.display.is_vsync():
+            delta_time = clock.tick()
+        else:
+            delta_time = clock.tick(60)
 
     pygame.quit()
 

src_c/display.c

@@ -2721,7 +2721,8 @@ static PyMethodDef _pg_display_methods[] = {
      DOC_DISPLAY_TOGGLEFULLSCREEN},
 
     {"_set_autoresize", (PyCFunction)pg_display_set_autoresize, METH_O,
-     "provisional API, subject to change"},
+     "DEPRECATED, never officially supported, kept only for compatibility "
+     "with release candidate"},
     {"_resize_event", (PyCFunction)pg_display_resize_event, METH_O,
      "DEPRECATED, never officially supported, kept only for compatibility "
      "with release candidate"},
@@ -2730,8 +2731,7 @@ static PyMethodDef _pg_display_methods[] = {
     {"get_desktop_sizes", (PyCFunction)pg_get_desktop_screen_sizes,
      METH_NOARGS, DOC_DISPLAY_GETDESKTOPSIZES},
     {"is_fullscreen", (PyCFunction)pg_is_fullscreen, METH_NOARGS,
-     "provisional API, subject to change"},
-
+     DOC_DISPLAY_ISFULLSCREEN},
     {"is_vsync", (PyCFunction)pg_is_vsync, METH_NOARGS, DOC_DISPLAY_ISVSYNC},
     {"get_desktop_refresh_rates", (PyCFunction)pg_desktop_refresh_rates,
      METH_NOARGS, DOC_DISPLAY_GETDESKTOPREFRESHRATES},

src_c/doc/display_doc.h

@@ -28,6 +28,7 @@
 #define DOC_DISPLAY_GETWINDOWSIZE "get_window_size() -> tuple\nReturn the size of the window or screen"
 #define DOC_DISPLAY_GETALLOWSCREENSAVER "get_allow_screensaver() -> bool\nReturn whether the screensaver is allowed to run."
 #define DOC_DISPLAY_SETALLOWSCREENSAVER "set_allow_screensaver(bool) -> None\nSet whether the screensaver may run"
-#define DOC_DISPLAY_ISVSYNC "is_vsync() -> bool\nReturns True if vertical synchronisation for pygame.display.flip() is enabled"
+#define DOC_DISPLAY_ISFULLSCREEN "is_fullscreen() -> bool\nReturns True if the pygame window created by pygame.display.set_mode() is in full-screen mode"
+#define DOC_DISPLAY_ISVSYNC "is_vsync() -> bool\nReturns True if vertical synchronisation for pygame.display.flip() and pygame.display.update() is enabled"
 #define DOC_DISPLAY_GETCURRENTREFRESHRATE "get_current_refresh_rate() -> int\nReturns the screen refresh rate or 0 if unknown"
 #define DOC_DISPLAY_GETDESKTOPREFRESHRATES "get_desktop_refresh_rates() -> list\nReturns the screen refresh rates for all displays (in windowed mode)."