Merge pull request #664 from MyreMylar/improve-draw-ui-docs

Improve documentation around premultiplied alpha

Author: MyreMylar

docs/source/index.rst

@@ -21,6 +21,9 @@ Features
 
  - Support for localizing your GUI into different languages.
 
+ - Uses premultiplied alpha blending for improved clarity and accuracy with semi-transparent pixels and improved
+   performance.
+
  - As closely respecting of the pygame way of doing things as possible.
 
 

pygame_gui/ui_manager.py

@@ -361,14 +361,19 @@ def get_mouse_position(self) -> Tuple[int, int]:
 
     def draw_ui(self, window_surface: pygame.surface.Surface):
         """
-        Draws all the UI elements on the screen. Generally you want this to be after the rest of
-        your game sprites have been drawn.
+        Draws all the UI elements on to a surface passed in, usually an opaque surface the size of the screen or window.
+        Generally you want this to be after the rest of your game sprites have been drawn.
 
         If you want to do something particularly unusual with drawing you may have to write your
         own UI manager.
 
         :param window_surface: The screen or window surface on which we are going to draw all of
-         our UI Elements.
+         our UI Elements. As pygame_gui uses premultiplied alpha, if the surface passed in is
+         transparent or semi transparent then it should use premultiplied alpha as well and be
+         blitted afterward using the BLEND_PREMULTIPLIED special_flag.
+
+         You can read more about premultiplied alpha in this short tutorial:
+         https://pyga.me/docs/tutorials/en/premultiplied-alpha.html
 
         """
         self.ui_group.draw(window_surface)