Merge pull request #2577 from Starbuck5/software-window-starbuck

Window update->flip, doc changes

buildconfig/stubs/pygame/_window.pyi

@@ -27,7 +27,7 @@ class Window:
     def set_modal_for(self, parent: Window) -> None: ...
     def set_icon(self, icon: Surface) -> None: ...
     def get_surface(self) -> Surface: ...
-    def update_from_surface(self) -> None: ...
+    def flip(self) -> None: ...
 
     grab_mouse: bool
     grab_keyboard: bool

docs/reST/ref/sdl2_video.rst

@@ -298,34 +298,53 @@
       | :sl:`Get the window surface`
       | :sg:`get_surface() -> Surface`
 
-      Return a reference to the surface associated with the window.
-
-      The size of surface will automatically change to fit the window size.
+      Returns a "display surface" for this Window. The surface returned is
+      analogous to the surface returned by :func:`pygame.display.set_mode`.
+
+      This method allows software rendering (classic pygame rendering) on top
+      of the Window API. This method should not be called when using hardware
+      rendering (coming soon).
 
-      The window surface become invalid when the window is destroyed.
+      Similarly to the "display surface" returned by :mod:`pygame.display`,
+      this surface will change size with the Window, and will become invalid
+      after the Window's destruction.
 
-      .. seealso:: :func:`update_from_surface`
+      .. seealso:: :func:`flip`
 
       .. versionadded:: 2.4.0
 
-   .. method:: update_from_surface
+   .. method:: flip
+
+      | :sl:`Update the display surface to the window.`
+      | :sg:`flip() -> None`
 
-      | :sl:`Update the window surface to the window.`
-      | :sg:`update_from_surface() -> None`
+      Update content from the display surface to the window. This is the Window
+      class equivalent of :func:`pygame.display.flip`.
 
-      Update content from the window surface to the window.
+      This method allows software rendering (classic pygame rendering) on top
+      of the Window API. This method should not be called when using hardware
+      rendering (coming soon).
 
-      Here is an example of using ``get_surface`` and ``update_from_surface``:
+      Here is a runnable example of using ``get_surface`` and ``flip``:
 
       .. code-block:: python
 
+         import pygame
+         from pygame._sdl2 import video
+
          win = video.Window()
-         surf = win.get_surface() # get the window surface
+         surf = win.get_surface()  # get the window surface
+
+         while True:
+            for event in pygame.event.get():
+               if event.type == pygame.QUIT:
+                     pygame.quit()
+                     raise SystemExit
 
-         # draw something on the surface
-         surf.fill((255,0,0))
+            # draw something on the surface
+            surf.fill("red")
 
-         win.update_from_surface() # update the surface to the window
+            win.flip()  # update the surface to the window
 
 
       .. versionadded:: 2.4.0

src_c/doc/sdl2_video_doc.h

@@ -23,7 +23,7 @@
 #define DOC_SDL2_VIDEO_WINDOW_DISPLAYINDEX "get_display_index -> int\nGet the index of the display that owns the window (**read-only**)"
 #define DOC_SDL2_VIDEO_WINDOW_FROMDISPLAYMODULE "from_display_module() -> Window\nCreate a Window object using window data from display module"
 #define DOC_SDL2_VIDEO_WINDOW_GETSURFACE "get_surface() -> Surface\nGet the window surface"
-#define DOC_SDL2_VIDEO_WINDOW_UPDATEFROMSURFACE "update_from_surface() -> None\nUpdate the window surface to the window."
+#define DOC_SDL2_VIDEO_WINDOW_FLIP "flip() -> None\nUpdate the display surface to the window."
 #define DOC_SDL2_VIDEO_WINDOW_SETWINDOWED "set_windowed() -> None\nEnable windowed mode (exit fullscreen)"
 #define DOC_SDL2_VIDEO_WINDOW_SETFULLSCREEN "set_fullscreen(desktop=False) -> None\nEnter fullscreen"
 #define DOC_SDL2_VIDEO_WINDOW_DESTROY "destroy() -> None\nDestroy the window"

src_c/window.c

@@ -168,7 +168,7 @@ window_get_surface(pgWindowObject *self)
 }
 
 static PyObject *
-window_update_from_surface(pgWindowObject *self)
+window_flip(pgWindowObject *self)
 {
     int result;
 
@@ -1034,8 +1034,8 @@ static PyMethodDef window_methods[] = {
      DOC_SDL2_VIDEO_WINDOW_SETMODALFOR},
     {"set_icon", (PyCFunction)window_set_icon, METH_O,
      DOC_SDL2_VIDEO_WINDOW_SETICON},
-    {"update_from_surface", (PyCFunction)window_update_from_surface,
-     METH_NOARGS, DOC_SDL2_VIDEO_WINDOW_UPDATEFROMSURFACE},
+    {"flip", (PyCFunction)window_flip, METH_NOARGS,
+     DOC_SDL2_VIDEO_WINDOW_FLIP},
     {"get_surface", (PyCFunction)window_get_surface, METH_NOARGS,
      DOC_SDL2_VIDEO_WINDOW_GETSURFACE},
     {"from_display_module", (PyCFunction)window_from_display_module,

test/window_test.py

@@ -351,13 +351,13 @@ def test_window_surface_with_display_module(self):
         surf2 = win2.get_surface()
         self.assertIs(surf1, surf2)
 
-    def test_window_update_from_surface(self):
+    def test_window_flip(self):
         win = Window(size=(640, 480))
         surf = win.get_surface()
         surf.fill((255, 0, 0))
 
-        self.assertRaises(TypeError, lambda: win.update_from_surface("an argument"))
-        self.assertIs(win.update_from_surface(), None)
+        self.assertRaises(TypeError, lambda: win.flip("an argument"))
+        self.assertIs(win.flip(), None)
         win.destroy()
 
     def tearDown(self):