Merge pull request #1874 from robertpfeiffer/better-vsync

Better VSync
Enable vsync by forcing GPU render paths
Raise exceptions when VSync is unavailable
Allow games to query VSync state

Author: robertpfeiffer

buildconfig/stubs/pygame/display.pyi

@@ -75,3 +75,6 @@ def get_allow_screensaver() -> bool: ...
 def set_allow_screensaver(value: bool = True) -> None: ...
 def get_desktop_sizes() -> List[Tuple[int, int]]: ...
 def is_fullscreen() -> bool: ...
+def is_vsync() -> bool: ...
+def get_current_refresh_rate() -> int: ...
+def get_desktop_refresh_rates() -> List[int]: ...

docs/reST/ref/display.rst

@@ -115,9 +115,9 @@ required).
    | :sl:`Initialize a window or screen for display`
    | :sg:`set_mode(size=(0, 0), flags=0, depth=0, display=0, vsync=0) -> Surface`
 
-   This function will create a display Surface. The arguments passed in are
-   requests for a display type. The actual created display will be the best
-   possible match supported by the system.
+   This will create a window or display output and return a display Surface.
+   The arguments passed in are requests for a display type. The actual created
+   display will be the best possible match supported by the system.
 
    Note that calling this function implicitly initializes ``pygame.display``, if
    it was not initialized before.
@@ -173,21 +173,42 @@ required).
    .. versionadded:: 2.0.0 ``SCALED``, ``SHOWN`` and ``HIDDEN``
 
    By setting the ``vsync`` parameter to ``1``, it is possible to get a display
-   with vertical sync, but you are not guaranteed to get one. The request only
-   works at all for calls to ``set_mode()`` with the ``pygame.OPENGL`` or
-   ``pygame.SCALED`` flags set, and is still not guaranteed even with one of
-   those set. What you get depends on the hardware and driver configuration
-   of the system pygame is running on. Here is an example usage of a call
+   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.
+   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.
+
+   The request only works when graphics acceleration is available on the
+   system. The exact behaviour depends on the hardware and driver
+   configuration. When  ``vsync`` is requested, but unavailable,
+   ``set_mode()`` may raise an exception.
+
+   Setting the ``vsync`` parameter to ``-1`` in conjunction with  ``OPENGL``
+   will request the OpenGL-specific feature "adaptive vsync".
+
+   Here is an example usage of a call
    to ``set_mode()`` that may give you a display with vsync:
 
    ::
 
      flags = pygame.OPENGL | pygame.FULLSCREEN
-     window_surface = pygame.display.set_mode((1920, 1080), flags, vsync=1)
+     try:
+        window_surface = pygame.display.set_mode((1920, 1080), flags, vsync=1)
+        vsync_success=True
+     except pygame.error:
+        window_surface = pygame.display.set_mode((1920, 1080), flags)
+        vsync_success=False
 
-   Vsync behaviour is considered experimental, and may change in future releases.
+   .. versionadded:: 2.0.0 ``vsync`` parameter
+
+   .. versionchanged:: 2.2.0 passing ``vsync`` can raise an exception
+
+   .. versionchanged:: 2.2.0 explicit request for "adaptive vsync"
+
+   .. versionchanged:: 2.2.0 ``vsync=1`` does not require ``SCALED`` or ``OPENGL``
 
-   .. versionadded:: 2.0.0 ``vsync``
 
    Basic example:
 
@@ -723,7 +744,43 @@ required).
 
    .. versionadded:: 2.0.0
 
+.. function:: is_vsync
+
+   | :sl:`Returns True if vertical synchronisation for pygame.display.flip() is enabled`
+   | :sg:`is_vsync() -> bool`
+
+   .. versionadded:: 2.2.0
+
+.. function:: get_current_refresh_rate() -> int
+
+   | :sl:`Returns the screen refresh rate or 0 if unknown`
+   | :sg:`get_current_refresh_rate() -> int`
+
+   The screen refresh rate for the current window. In windowed mode, this
+   should be equal to the refresh rate of the desktop the window is on.
+
+   If no window is open, an exception is raised.
+
+   When a constant refresh rate cannot be determined, 0 is returned.
+
+   .. versionadded:: 2.2.0
+
+.. function:: get_desktop_refresh_rates() -> list
+
+   | :sl:`Returns the screen refresh rates for all displays (in windowed mode).`
+   | :sg:`get_desktop_refresh_rates() -> list`
+
+   If the current window is in full-screen mode, the actual refresh rate for
+   that window can differ.
+
+   This is safe to call when no window is open (i.e. before any calls to
+   :func:`pygame.display.set_mode()`
+
+   When a constant refresh rate cannot be determined, 0 is returned for that
+   desktop.
+
 
+   .. versionadded:: 2.2.0
    .. ## pygame.display.set_allow_screensaver ##
 
 .. ## pygame.display ##

examples/setmodescale.py

@@ -11,6 +11,7 @@
 """
 
 import pygame as pg
+import sys
 
 pg.init()
 
@@ -19,7 +20,13 @@
 clock = pg.time.Clock()
 
 print("desktops", pg.display.get_desktop_sizes())
-screen = pg.display.set_mode(RES, pg.SCALED | pg.RESIZABLE)
+
+do_vsync = bool("--vsync" in sys.argv)
+
+if do_vsync:
+    screen = pg.display.set_mode(RES, pg.SCALED | pg.RESIZABLE, vsync=1)
+else:
+    screen = pg.display.set_mode(RES, pg.SCALED | pg.RESIZABLE)
 
 # MAIN LOOP
 
@@ -47,9 +54,6 @@
             done = True
         if event.type == pg.KEYDOWN and event.key == pg.K_f:
             pg.display.toggle_fullscreen()
-        if event.type == pg.VIDEORESIZE:
-            pg.display._resize_event(event)
-
     i += 1
     i = i % screen.get_width()
     j += i % 2
@@ -59,9 +63,21 @@
     pg.draw.circle(screen, (0, 0, 0), (100, 100), 20)
     pg.draw.circle(screen, (0, 0, 200), (0, 0), 10)
     pg.draw.circle(screen, (200, 0, 0), (160, 120), 30)
-    pg.draw.line(screen, (250, 250, 0), (0, 120), (160, 0))
+    if do_vsync:
+        # vertical line that moves horizontally to make screen tearing obvious
+        pg.draw.line(screen, (250, 250, 0), (i, 0), (i, 120))
+    else:
+        pg.draw.line(screen, (250, 250, 0), (0, 120), (160, 0))
     pg.draw.circle(screen, (255, 255, 255), (i, j), 5)
 
-    pg.display.flip()
-    clock.tick(FPS)
+    pg.display.set_caption("FPS:" + str(clock.get_fps()))
+    if do_vsync:
+        pg.display.flip()
+        # FPS should be limited by vsync, so we tick really fast
+        # we only need to have the clock tick to track FPS
+        clock.tick()
+    else:
+        clock.tick(FPS)
+        pg.display.flip()
+
 pg.quit()