Merge branch 'master' into time_get_ticks_test

buildconfig/pygame-stubs/display.pyi

@@ -42,6 +42,7 @@ def set_mode(
     flags: Optional[int] = 0,
     depth: Optional[int] = 0,
     display: Optional[int] = 0,
+    vsync: Optional[int] = 0
 ) -> Surface: ...
 def get_surface() -> Surface: ...
 def flip() -> None: ...

docs/reST/ref/display.rst

@@ -104,7 +104,7 @@ required).
 .. function:: set_mode
 
    | :sl:`Initialize a window or screen for display`
-   | :sg:`set_mode(size=(0, 0), flags=0, depth=0, display=0) -> Surface`
+   | :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
@@ -152,11 +152,28 @@ required).
       pygame.OPENGL        create an OpenGL-renderable display
       pygame.RESIZABLE     display window should be sizeable
       pygame.NOFRAME       display window will have no border or controls
-      pygame.SCALED        resolution depends on desktop size and scale graphics
+      pygame.SCALED        resolution depends on desktop size and scale
+                           graphics
 
    .. versionadded:: 2.0.0 ``SCALED``
 
-   For example:
+   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 actually get depends entirely on the hardware and driver
+   configuration of the system pygame is running on. 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)
+
+   .. versionadded:: 2.0.0 ``vsync``
+
+   Basic example:
 
    ::
 
@@ -248,7 +265,8 @@ required).
 
      hw:         1 if the display is hardware accelerated
      wm:         1 if windowed display modes can be used
-     video_mem:  The megabytes of video memory on the display. This is 0 if unknown
+     video_mem:  The megabytes of video memory on the display. This is 0 if
+                 unknown
      bitsize:    Number of bits used to store each pixel
      bytesize:   Number of bytes used to store each pixel
      masks:      Four values used to pack RGBA values into pixels
@@ -260,10 +278,11 @@ required).
      blit_sw:    1 if software Surface blitting is accelerated
      blit_sw_CC: 1 if software Surface colorkey blitting is accelerated
      blit_sw_A:  1 if software Surface pixel alpha blitting is accelerated
-     current_h, current_w:  Height and width of the current video mode, or of the
-       desktop mode if called before the display.set_mode is called.
-       (current_h, current_w are available since SDL 1.2.10, and pygame 1.8.0)
-       They are -1 on error, or if an old SDL is being used.
+     current_h, current_w:  Height and width of the current video mode, or
+                 of the desktop mode if called before the display.set_mode
+                 is called. (current_h, current_w are available since
+                 SDL 1.2.10, and pygame 1.8.0). They are -1 on error, or if
+                 an old SDL is being used.
 
    .. ## pygame.display.Info ##
 
@@ -405,7 +424,8 @@ required).
 
        GL_CONTEXT_PROFILE_CORE             disable deprecated features
        GL_CONTEXT_PROFILE_COMPATIBILITY    allow deprecated features
-       GL_CONTEXT_PROFILE_ES               allow only the ES feature subset of OpenGL
+       GL_CONTEXT_PROFILE_ES               allow only the ES feature
+                                           subset of OpenGL
 
    :const:`GL_ACCELERATED_VISUAL`
 

examples/testsprite.py

@@ -169,7 +169,7 @@ def main(
 
     # if "-fast" in sys.argv:
 
-    screen = pg.display.set_mode(screen_dims, flags)
+    screen = pg.display.set_mode(screen_dims, flags, vsync="-vsync" in sys.argv)
 
     # this is mainly for GP2X, so it can quit.
     pg.joystick.init()

src_c/display.c

@@ -1033,10 +1033,10 @@ pg_set_mode(PyObject *self, PyObject *arg, PyObject *kwds)
         title = state->title;
     }
 
-    if (vsync && !(flags & (PGS_SCALED | PGS_OPENGL))) {
-        return RAISE(pgExc_SDLError,
-                     "vsync needs either SCALED or OPENGL flag");
-    }
+    // if (vsync && !(flags & (PGS_SCALED | PGS_OPENGL))) {
+    //     return RAISE(pgExc_SDLError,
+    //                  "vsync needs either SCALED or OPENGL flag");
+    // }
 
     /* set these only in toggle_fullscreen, clear on set_mode */
     state->toggle_windowed_w = 0;

src_c/doc/display_doc.h

@@ -3,7 +3,7 @@
 #define DOC_PYGAMEDISPLAYINIT "init() -> None\nInitialize the display module"
 #define DOC_PYGAMEDISPLAYQUIT "quit() -> None\nUninitialize the display module"
 #define DOC_PYGAMEDISPLAYGETINIT "get_init() -> bool\nReturns True if the display module has been initialized"
-#define DOC_PYGAMEDISPLAYSETMODE "set_mode(size=(0, 0), flags=0, depth=0, display=0) -> Surface\nInitialize a window or screen for display"
+#define DOC_PYGAMEDISPLAYSETMODE "set_mode(size=(0, 0), flags=0, depth=0, display=0, vsync=0) -> Surface\nInitialize a window or screen for display"
 #define DOC_PYGAMEDISPLAYGETSURFACE "get_surface() -> Surface\nGet a reference to the currently set display surface"
 #define DOC_PYGAMEDISPLAYFLIP "flip() -> None\nUpdate the full display Surface to the screen"
 #define DOC_PYGAMEDISPLAYUPDATE "update(rectangle=None) -> None\nupdate(rectangle_list) -> None\nUpdate portions of the screen for software displays"
@@ -49,7 +49,7 @@ pygame.display.get_init
 Returns True if the display module has been initialized
 
 pygame.display.set_mode
- set_mode(size=(0, 0), flags=0, depth=0, display=0) -> Surface
+ set_mode(size=(0, 0), flags=0, depth=0, display=0, vsync=0) -> Surface
 Initialize a window or screen for display
 
 pygame.display.get_surface

test/time_test.py

@@ -134,7 +134,6 @@ def todo_test_tick_busy_loop(self):
 
         self.fail()
 
-
 class TimeModuleTest(unittest.TestCase):
     def test_delay(self):
         """Tests time.delay() function."""