Update pysdl2.py example and add link to README-Examples.md

cztomczak · cztomczak · commit ddd6264454e7 · 2018-01-08T17:53:26.000+01:00
diff --git a/examples/README-examples.md b/examples/README-examples.md
@@ -43,6 +43,9 @@ workarounds.
   library (GTK 2)
 - [gtk3.py](gtk3.py): example for [PyGObject / PyGI](https://wiki.gnome.org/Projects/PyGObject)
   library (GTK 3). Currently broken on Mac ([#310](../../../issues/310)).
+- [pysdl2.py](pysdl2.py): off-screen rendering example for
+  [PySDL2](https://github.com/marcusva/py-sdl2) library. Currently tested
+  only on Linux.
 - [pywin32.py](pywin32.py): example for [pywin32](https://github.com/mhammond/pywin32)
   library
 - [qt.py](qt.py): example for [PyQt4](https://wiki.python.org/moin/PyQt4),
diff --git a/examples/pysdl2.py b/examples/pysdl2.py
@@ -1,71 +1,68 @@
 """
- Simple SDL2 / cefpython3 example.
+Example of embedding CEF browser using PySDL2 library.
 
- Requires pysdl2 (and SDL2 library).
- 
- Tested configurations:
- - SDL2 2.0.5 with PySDL2 0.9.3 on Fedora 25 (x86_64)
- - SDL2 with PySDL2 0.9.5 on Ubuntu 14.04
+This example is incomplete, see "Missing functionality" section
+further down. Pull requests for the missing functionality are welcome.
 
- Install instructions.
- 
- 1. Install SDL libraries for your OS, e.g:
+Requires PySDL2 and SDL2 libraries.
  
-    Fedora:
-    
-        sudo dnf install SDL2 SDL2_ttf SDL2_image SDL2_gfx SDL2_mixer
-        
-    Ubuntu:
-    
-        sudo apt-get install libsdl2-dev
-
- 2. Install PySDL via PIP:
+Tested configurations:
+- Fedora 25: SDL2 2.0.5 with PySDL2 0.9.3
+- Ubuntu 14.04: SDL2 with PySDL2 0.9.6
 
-    sudo pip2 install PySDL2
+Install instructions:
+1. Install SDL libraries for your OS, e.g:
+   - Fedora: sudo dnf install SDL2 SDL2_ttf SDL2_image SDL2_gfx SDL2_mixer
+   - Ubuntu: sudo apt-get install libsdl2-dev
+2. Install PySDL2 using pip package manager:
+   pip install PySDL2
  
- Event handling:
- 
- Where possible SDL2 events are mapped to CEF ones. Not all keyboard
- modifiers are handled in this example but these could be
- added by the reader (if desired). Modifiers that do not work
- for example:
- 
- - Ctrl
- - Mouse dragging
- - Marking text inputs with the shift key
- 
- Due to SDL2's lack of GUI widgets there are no GUI controls
- for the user. However, as an exercise this example could
- be extended by create some simple SDL2 widgets. An example of
- widgets made using PySDL2 can be found as part of the Pi
- Entertainment System at:
- https://github.com/neilmunday/pes/blob/master/lib/pes/ui.py
+Missing functionality:
+- Keyboard modifiers that are not yet handled in this example:
+  ctrl, marking text inputs with the shift key.
+- Mouse dragging
+- Window size is fixed, cannot be resized
+
+GUI controls:
+  Due to SDL2's lack of GUI widgets there are no GUI controls
+  for the user. However, as an exercise this example could
+  be extended by create some simple SDL2 widgets. An example of
+  widgets made using PySDL2 can be found as part of the Pi
+  Entertainment System at:
+  https://github.com/neilmunday/pes/blob/master/lib/pes/ui.py
 """
 
-import os
 import sys
 try:
+    # noinspection PyUnresolvedReferences
     from cefpython3 import cefpython as cef
 except ImportError:
-    print("cefpython3 module not found - please install")
+    print("ERROR: cefpython3 package not found")
+    print("To install type: `pip install cefpython3`")
     sys.exit(1)
 try:
+    # noinspection PyUnresolvedReferences
     import sdl2
+    # noinspection PyUnresolvedReferences
     import sdl2.ext
 except ImportError:
-    print("SDL2 module not found - please install")
+    print("ERROR: SDL2 package not found")
+    print("To install type: `pip install PySDL2`")
     sys.exit(1)
 try:
+    # noinspection PyUnresolvedReferences
     from PIL import Image
 except ImportError:
-    print("PIL module not found - please install")
+    print("ERROR: PIL package not found")
+    print("To install type: pip install Pillow")
     sys.exit(1)
 
+
 def main():
     # The following variables control the dimensions of the window
     # and browser display area
-    width = 1024
-    height = 768
+    width = 800
+    height = 600
     # headerHeight is useful for leaving space for controls
     # at the top of the window (future implementation?)
     headerHeight = 0
@@ -74,7 +71,6 @@ def main():
     # Mouse wheel fudge to enhance scrolling
     scrollEnhance = 20
     # Initialise CEF for offscreen rendering
-    WindowUtils = cef.WindowUtils()
     sys.excepthook = cef.ExceptHook
     cef.Initialize(settings={"windowless_rendering_enabled": True})
     window_info = cef.WindowInfo()
@@ -95,7 +91,8 @@ def main():
     # Define default background colour (black in this case)
     backgroundColour = sdl2.SDL_Color(0, 0, 0)
     # Create the renderer using hardware acceleration
-    renderer = sdl2.SDL_CreateRenderer(window, -1, sdl2.render.SDL_RENDERER_ACCELERATED)
+    renderer = sdl2.SDL_CreateRenderer(window, -1,
+                                       sdl2.render.SDL_RENDERER_ACCELERATED)
     # Set-up the RenderHandler, passing in the SDL2 renderer
     renderHandler = RenderHandler(renderer, width, height - headerHeight)
     # Create the browser instance
@@ -107,15 +104,16 @@ def main():
     browser.SendFocusEvent(True)
     browser.WasResized()
     # Begin the main rendering loop
-    shiftDown = False
     running = True
     while running:
         # Convert SDL2 events into CEF events (where appropriate)
         events = sdl2.ext.get_events()
         for event in events:
-            if event.type == sdl2.SDL_QUIT or (event.type == sdl2.SDL_KEYDOWN and event.key.keysym.sym == sdl2.SDLK_ESCAPE):
-                    running = False
-                    break
+            if (event.type == sdl2.SDL_QUIT
+                or (event.type == sdl2.SDL_KEYDOWN
+                    and event.key.keysym.sym == sdl2.SDLK_ESCAPE)):
+                running = False
+                break
             if event.type == sdl2.SDL_MOUSEBUTTONDOWN:
                 if event.button.button == sdl2.SDL_BUTTON_LEFT:
                     if event.button.y > headerHeight:
@@ -141,7 +139,9 @@ def main():
             elif event.type == sdl2.SDL_MOUSEMOTION:
                 if event.motion.y > headerHeight:
                     # Mouse move triggered in browser region
-                    browser.SendMouseMoveEvent(event.motion.x, event.motion.y - headerHeight, False)
+                    browser.SendMouseMoveEvent(event.motion.x,
+                                               event.motion.y - headerHeight,
+                                               False)
             elif event.type == sdl2.SDL_MOUSEWHEEL:
                 # Mouse wheel event
                 x = event.wheel.x
@@ -156,7 +156,8 @@ def main():
                     y += scrollEnhance
                 browser.SendMouseWheelEvent(0, 0, x, y)
             elif event.type == sdl2.SDL_TEXTINPUT:
-                # Handle text events to get actual characters typed rather than the key pressed
+                # Handle text events to get actual characters typed rather
+                # than the key pressed.
                 keycode = ord(event.text.text)
                 key_event = {
                     "type": cef.KEYEVENT_CHAR,
@@ -196,8 +197,8 @@ def main():
                         sdl2.SDLK_HOME,
                         sdl2.SDLK_END
                 ]:
-                    keycode = getKeyCode(event.key.keysym.sym)
-                    if keycode != None:
+                    keycode = get_key_code(event.key.keysym.sym)
+                    if keycode is not None:
                         key_event = {
                             "type": cef.KEYEVENT_RAWKEYDOWN,
                             "windows_key_code": keycode,
@@ -219,8 +220,8 @@ def main():
                         sdl2.SDLK_HOME,
                         sdl2.SDLK_END
                 ]:
-                    keycode = getKeyCode(event.key.keysym.sym)
-                    if keycode != None:
+                    keycode = get_key_code(event.key.keysym.sym)
+                    if keycode is not None:
                         key_event = {
                             "type": cef.KEYEVENT_KEYUP,
                             "windows_key_code": keycode,
@@ -251,10 +252,11 @@ def main():
         sdl2.SDL_RenderPresent(renderer)
     # User exited
     exit_app()
-    
-def getKeyCode(key):
+
+
+def get_key_code(key):
     """Helper function to convert SDL2 key codes to cef ones"""
-    keyMap = {
+    key_map = {
         sdl2.SDLK_RETURN: 13,
         sdl2.SDLK_DELETE: 46,
         sdl2.SDLK_BACKSPACE: 8,
@@ -265,26 +267,28 @@ def getKeyCode(key):
         sdl2.SDLK_HOME: 36,
         sdl2.SDLK_END: 35,
     }
-    if key in keyMap:
-        return keyMap[key]
+    if key in key_map:
+        return key_map[key]
     # Key not mapped, raise exception
-    print("Keyboard mapping incomplete: \
-unsupported SDL key %d. \
-See https://wiki.libsdl.org/SDLKeycodeLookup for mapping."
-    % key)
+    print("[pysdl2.py] Keyboard mapping incomplete:"
+          " unsupported SDL key %d."
+          " See https://wiki.libsdl.org/SDLKeycodeLookup for mapping."
+          % key)
     return None
 
+
 class LoadHandler(object):
     """Simple handler for loading URLs."""
     
-    def OnLoadingStateChange(self, browser, is_loading, **_):
+    def OnLoadingStateChange(self, is_loading, **_):
         if not is_loading:
-            print("loading complete")
+            print("[pysdl2.py] Page loading complete")
             
-    def OnLoadError(self, browser, frame, error_code, failed_url, **_):
+    def OnLoadError(self, frame, failed_url, **_):
         if not frame.IsMain():
             return
-        print("Failed to load %s" % failed_url)
+        print("[pysdl2.py] Failed to load %s" % failed_url)
+
 
 class RenderHandler(object):
     """
@@ -306,7 +310,7 @@ def GetViewRect(self, rect_out, **_):
         rect_out.extend([0, 0, self.__width, self.__height])
         return True
     
-    def OnPaint(self, browser, element_type, paint_buffer, **_):
+    def OnPaint(self, element_type, paint_buffer, **_):
         """
         Using the pixel data from CEF's offscreen rendering
         the data is converted by PIL into a SDL2 surface
@@ -323,6 +327,8 @@ def OnPaint(self, browser, element_type, paint_buffer, **_):
             # Following PIL to SDL2 surface code from pysdl2 source.
             mode = image.mode
             rmask = gmask = bmask = amask = 0
+            depth = None
+            pitch = None
             if mode == "RGB":
                 # 3x8-bit, 24bpp
                 if sdl2.endian.SDL_BYTEORDER == sdl2.endian.SDL_LIL_ENDIAN:
@@ -353,7 +359,7 @@ def OnPaint(self, browser, element_type, paint_buffer, **_):
                 depth = 32
                 pitch = self.__width * 4
             else:
-                print("Unsupported mode: %s" % mode)
+                print("[pysdl2.py] ERROR: Unsupported mode: %s" % mode)
                 exit_app()
             
             pxbuf = image.tobytes()
@@ -373,17 +379,20 @@ def OnPaint(self, browser, element_type, paint_buffer, **_):
                 # free memory used by previous texture
                 sdl2.SDL_DestroyTexture(self.texture)
             # Create texture
-            self.texture = sdl2.SDL_CreateTextureFromSurface(self.__renderer, surface)
+            self.texture = sdl2.SDL_CreateTextureFromSurface(self.__renderer,
+                                                             surface)
             # Free the surface
             sdl2.SDL_FreeSurface(surface)
         else:
-            print("Unsupport element_type in OnPaint")
+            print("[pysdl2.py] WARNING: Unsupport element_type in OnPaint")
+
 
 def exit_app():
     """Tidy up SDL2 and CEF before exiting."""
     sdl2.SDL_Quit()
     cef.Shutdown()
-    print("exited")
-    
+    print("[pysdl2.py] Exited gracefully")
+
+
 if __name__ == "__main__":
     main()
