Make clear() more reasonable

arcade/application.py

@@ -21,7 +21,7 @@
 from arcade import set_window
 from arcade.color import TRANSPARENT_BLACK
 from arcade.context import ArcadeContext
-from arcade.types import Color, RGBA255, RGBA255OrNormalized
+from arcade.types import Color, RGBOrA255, RGBANormalized
 from arcade import SectionManager
 from arcade.utils import is_raspberry_pi
 
@@ -260,10 +260,10 @@ def ctx(self) -> ArcadeContext:
         return self._ctx
 
     def clear(
-            self,
-            color: Optional[RGBA255OrNormalized] = None,
-            normalized: bool = False,
-            viewport: Optional[Tuple[int, int, int, int]] = None,
+        self,
+        color: Optional[RGBOrA255] = None,
+        color_normalized: Optional[RGBANormalized] = None,
+        viewport: Optional[Tuple[int, int, int, int]] = None,
     ):
         """Clears the window with the configured background color
         set through :py:attr:`arcade.Window.background_color`.
@@ -272,14 +272,18 @@ def clear(
             with one of the following:
 
             1. A :py:class:`~arcade.types.Color` instance
-            2. A 4-length RGBA :py:class:`tuple` of byte values (0 to 255)
-            3. A 4-length RGBA :py:class:`tuple` of normalized floats (0.0 to 1.0)
+            2. A 3 or 4-length RGB/RGBA :py:class:`tuple` of byte values (0 to 255)
+
+        :param color_normalized: (Optional) override the current background color
+            using normalized values (0.0 to 1.0). For example, (1.0, 0.0, 0.0, 1.0)
+            making the window contents red.
 
-        :param normalized: If the color format is normalized (0.0 -> 1.0) or byte values
         :param Tuple[int, int, int, int] viewport: The viewport range to clear
         """
-        color = color if color is not None else self.background_color
-        self.ctx.screen.clear(color, normalized=normalized, viewport=viewport)
+        # Use the configured background color if none is provided
+        if color is None and color_normalized is None:
+            color = self.background_color
+        self.ctx.screen.clear(color=color, color_normalized=color_normalized, viewport=viewport)
 
     @property
     def background_color(self) -> Color:
@@ -310,7 +314,7 @@ def background_color(self) -> Color:
         return self._background_color
 
     @background_color.setter
-    def background_color(self, value: RGBA255):
+    def background_color(self, value: RGBOrA255):
         self._background_color = Color.from_iterable(value)
 
     def run(self) -> None:
@@ -990,24 +994,26 @@ def add_section(self, section, at_index: Optional[int] = None, at_draw_order: Op
 
     def clear(
         self,
-        color: Optional[RGBA255OrNormalized] = None,
-        normalized: bool = False,
+        color: Optional[RGBOrA255] = None,
+        color_normalized: Optional[RGBANormalized] = None,
         viewport: Optional[Tuple[int, int, int, int]] = None,
     ):
-        """Clears the View's Window with the configured background color
+        """Clears the window with the configured background color
         set through :py:attr:`arcade.Window.background_color`.
 
         :param color: (Optional) override the current background color
             with one of the following:
 
             1. A :py:class:`~arcade.types.Color` instance
-            2. A 4-length RGBA :py:class:`tuple` of byte values (0 to 255)
-            3. A 4-length RGBA :py:class:`tuple` of normalized floats (0.0 to 1.0)
+            2. A 3 or 4-length RGB/RGBA :py:class:`tuple` of byte values (0 to 255)
+
+        :param color_normalized: (Optional) override the current background color
+            using normalized values (0.0 to 1.0). For example, (1.0, 0.0, 0.0, 1.0)
+            making the window contents red.
 
-        :param normalized: If the color format is normalized (0.0 -> 1.0) or byte values
         :param Tuple[int, int, int, int] viewport: The viewport range to clear
         """
-        self.window.clear(color, normalized, viewport)
+        self.window.clear(color=color, color_normalized=color_normalized, viewport=viewport)
 
     def on_update(self, delta_time: float):
         """To be overridden"""

arcade/examples/gl/3d_cube_with_cubes.py

@@ -110,7 +110,7 @@ def on_draw(self):
 
         # Draw the current cube using the last one as a texture
         self.fbo1.use()
-        self.fbo1.clear(color=(1.0, 1.0, 1.0, 1.0), normalized=True)
+        self.fbo1.clear(color_normalized=(1.0, 1.0, 1.0, 1.0))
 
         translate = Mat4.from_translation((0, 0, -1.75))
         rx = Mat4.from_rotation(self.time, (1, 0, 0))

arcade/examples/minimap.py

@@ -111,7 +111,7 @@ def setup(self):
     def update_minimap(self):
         proj = 0, MAP_WIDTH, 0, MAP_HEIGHT
         with self.minimap_sprite_list.atlas.render_into(self.minimap_texture, projection=proj) as fbo:
-            fbo.clear(MINIMAP_BACKGROUND_COLOR)
+            fbo.clear(color=MINIMAP_BACKGROUND_COLOR)
             self.wall_list.draw()
             self.player_sprite.draw()
 

arcade/examples/minimap_camera.py

@@ -124,7 +124,7 @@ def on_draw(self):
 
         # Draw new minimap using the camera
         self.camera_minimap.use()
-        self.clear(MINIMAP_BACKGROUND_COLOR)
+        self.clear(color=MINIMAP_BACKGROUND_COLOR)
         self.wall_list.draw()
         self.player_list.draw()
 

arcade/examples/sections_demo_1.py

@@ -127,7 +127,7 @@ def __init__(self):
 
     def on_draw(self):
         # clear the screen
-        self.clear(arcade.color.BEAU_BLUE)
+        self.clear(color=arcade.color.BEAU_BLUE)
 
         # draw a line separating each Section
         arcade.draw_line(self.window.width / 2, 0, self.window.width / 2,

arcade/examples/sections_demo_2.py

@@ -161,7 +161,7 @@ def end_game(self, winner: Player):
         self.setup()  # prepare a new game
 
     def on_draw(self):
-        self.clear(BEAU_BLUE)  # clear the screen
+        self.clear(color=BEAU_BLUE)  # clear the screen
 
         self.ball.draw()  # draw the ball
 

arcade/experimental/atlas_render_into.py

@@ -32,12 +32,12 @@ def on_draw(self):
     def render_into_sprite_texture(self):
         # Render shape into texture atlas in the first sprite texture's space
         with self.spritelist.atlas.render_into(self.texture_1) as fbo:
-            fbo.clear((255, 0, 0, 255))
+            fbo.clear(color=(255, 0, 0, 255))
             arcade.draw_rectangle_filled(128, 128, 160, 160, arcade.color.WHITE, self.elapsed_time * 100)
 
         # Render a shape into the second texture in the atlas
         with self.spritelist.atlas.render_into(self.texture_2) as fbo:
-            fbo.clear((0, 255, 0, 255))
+            fbo.clear(color=(0, 255, 0, 255))
             arcade.draw_circle_filled(
                 128,
                 128,

arcade/experimental/clock/clock_window.py

@@ -27,7 +27,7 @@
 from arcade import NoOpenGLException
 from arcade.color import TRANSPARENT_BLACK
 from arcade.context import ArcadeContext
-from arcade.types import Color, RGBA255, RGBA255OrNormalized
+from arcade.types import Color, RGBOrA255, RGBOrANormalized
 from arcade import SectionManager
 from arcade.utils import is_raspberry_pi
 
@@ -262,8 +262,8 @@ def ctx(self) -> ArcadeContext:
 
     def clear(
             self,
-            color: Optional[RGBA255OrNormalized] = None,
-            normalized: bool = False,
+            color: Optional[RGBOrA255] = None,
+            color_normalized: Optional[RGBOrANormalized] = None,
             viewport: Optional[Tuple[int, int, int, int]] = None,
     ):
         """Clears the window with the configured background color
@@ -276,11 +276,14 @@ def clear(
             2. A 4-length RGBA :py:class:`tuple` of byte values (0 to 255)
             3. A 4-length RGBA :py:class:`tuple` of normalized floats (0.0 to 1.0)
 
-        :param normalized: If the color format is normalized (0.0 -> 1.0) or byte values
+        :param color_normalized: (Optional) override the current background color
+            with a 4-length RGBA :py:class:`tuple` of normalized floats (0.0 to 1.0)
+
         :param Tuple[int, int, int, int] viewport: The viewport range to clear
         """
-        color = color if color is not None else self.background_color
-        self.ctx.screen.clear(color, normalized=normalized, viewport=viewport)
+        if color is None and color_normalized is None:
+            color = self.background_color
+        self.ctx.screen.clear(color=color, color_normalized=color_normalized, viewport=viewport)
 
     @property
     def background_color(self) -> Color:
@@ -311,7 +314,7 @@ def background_color(self) -> Color:
         return self._background_color
 
     @background_color.setter
-    def background_color(self, value: RGBA255):
+    def background_color(self, value: RGBOrA255):
         self._background_color = Color.from_iterable(value)
 
     @property
@@ -1001,24 +1004,26 @@ def add_section(self, section, at_index: Optional[int] = None, at_draw_order: Op
 
     def clear(
         self,
-        color: Optional[RGBA255OrNormalized] = None,
-        normalized: bool = False,
+        color: Optional[RGBOrA255] = None,
+        color_normalized: Optional[RGBOrANormalized] = None,
         viewport: Optional[Tuple[int, int, int, int]] = None,
     ):
-        """Clears the View's Window with the configured background color
+        """Clears the window with the configured background color
         set through :py:attr:`arcade.Window.background_color`.
 
         :param color: (Optional) override the current background color
             with one of the following:
 
             1. A :py:class:`~arcade.types.Color` instance
-            2. A 4-length RGBA :py:class:`tuple` of byte values (0 to 255)
-            3. A 4-length RGBA :py:class:`tuple` of normalized floats (0.0 to 1.0)
+            2. A 3 or 4-length RGB/RGBA :py:class:`tuple` of byte values (0 to 255)
+
+        :param color_normalized: (Optional) override the current background color
+            using normalized values (0.0 to 1.0). For example, (1.0, 0.0, 0.0, 1.0)
+            making the window contents red.
 
-        :param normalized: If the color format is normalized (0.0 -> 1.0) or byte values
         :param Tuple[int, int, int, int] viewport: The viewport range to clear
         """
-        self.window.clear(color, normalized, viewport)
+        self.window.ctx.screen.clear(color=color, color_normalized=color_normalized, viewport=viewport)
 
     def on_update(self, delta_time: float):
         """To be overridden"""

arcade/experimental/lights.py

@@ -154,7 +154,7 @@ def __getitem__(self, i) -> Light:
     def __enter__(self):
         self._prev_target = self.ctx.active_framebuffer
         self._fbo.use()
-        self._fbo.clear(self._background_color)
+        self._fbo.clear(color=self._background_color)
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):

arcade/experimental/sprite_collect_coins_minimap.py

@@ -106,7 +106,7 @@ def on_draw(self):
         self.clear()
 
         self.offscreen.use()
-        self.offscreen.clear(arcade.color.AMAZON)
+        self.offscreen.clear(color=arcade.color.AMAZON)
 
         arcade.draw_rectangle_outline(SCREEN_WIDTH / 2,
                                       SCREEN_HEIGHT / 2,

arcade/experimental/texture_render_target.py

@@ -40,7 +40,7 @@ def texture(self) -> Texture2D:
 
     def clear(self):
         """Clear the texture with the configured background color"""
-        self._fbo.clear(self._background_color)
+        self._fbo.clear(color=self._background_color)
 
     def set_background_color(self, color: RGBA255):
         """Set the background color for the light layer"""

arcade/gl/buffer.py

@@ -62,7 +62,7 @@ def __init__(
         gl.glBindBuffer(gl.GL_ARRAY_BUFFER, self._glo)
         # print(f"glBufferData(gl.GL_ARRAY_BUFFER, {self._size}, data, {self._usage})")
 
-        if data is not None and len(data) > 0:
+        if data is not None and len(data) > 0:  # type: ignore
             self._size, data = data_to_ctypes(data)
             gl.glBufferData(gl.GL_ARRAY_BUFFER, self._size, data, self._usage)
         elif reserve > 0:

arcade/gl/framebuffer.py

@@ -2,7 +2,7 @@
 
 from ctypes import c_int, string_at
 from contextlib import contextmanager
-from typing import Optional, Tuple, List, TYPE_CHECKING, Union
+from typing import Generator, Optional, Tuple, List, TYPE_CHECKING
 import weakref
 
 
@@ -305,7 +305,7 @@ def __exit__(self, exc_type, exc_val, exc_tb):
             self._prev_fbo.use()
 
     @contextmanager
-    def activate(self):
+    def activate(self) -> Generator[Framebuffer, None, None]:
         """Context manager for binding the framebuffer.
 
         Unlike the default context manager in this class
@@ -348,10 +348,10 @@ def _use(self, *, force: bool = False):
 
     def clear(
         self,
-        color: Union[RGBOrA255, RGBOrANormalized] = (0.0, 0.0, 0.0, 0.0),
         *,
+        color: Optional[RGBOrA255] = None,
+        color_normalized: Optional[RGBOrANormalized] = None,
         depth: float = 1.0,
-        normalized: bool = False,
         viewport: Optional[Tuple[int, int, int, int]] = None,
     ):
         """
@@ -361,12 +361,13 @@ def clear(
             fb.clear(color=arcade.color.WHITE)
 
             # Clear framebuffer using the color red in normalized form
-            fbo.clear(color=(1.0, 0.0, 0.0, 1.0), normalized=True)
+            fbo.clear(color_normalized=(1.0, 0.0, 0.0, 1.0))
 
         If the background color is an ``RGB`` value instead of ``RGBA```
         we assume alpha value 255.
 
-        :param color: A 3 or 4 component tuple containing the color
+        :param color: A 3 or 4 component tuple containing the color (prioritized over color_normalized)
+        :param color_normalized: A 3 or 4 component tuple containing the color in normalized form
         :param depth: Value to clear the depth buffer (unused)
         :param normalized: If the color values are normalized or not
         :param Tuple[int, int, int, int] viewport: The viewport range to clear
@@ -379,24 +380,26 @@ def clear(
             else:
                 self.scissor = None
 
-            if normalized:
-                # If the colors are already normalized we can pass them right in
+            clear_color = 0.0, 0.0, 0.0, 0.0
+            if color is not None:
                 if len(color) == 3:
-                    gl.glClearColor(*color, 1.0)
+                    clear_color = color[0] / 255, color[1] / 255, color[2] / 255, 1.0
+                elif len(color) == 4:
+                    clear_color = color[0] / 255, color[1] / 255, color[2] / 255, color[3] / 255
                 else:
-                    gl.glClearColor(*color)
-            else:
-                # OpenGL wants normalized colors (0.0 -> 1.0)
-                if len(color) == 3:
-                    gl.glClearColor(color[0] / 255, color[1] / 255, color[2] / 255, 1.0)
+                    raise ValueError("Color should be a 3 or 4 component tuple")
+            elif color_normalized is not None:
+                if len(color_normalized) == 3:
+                    clear_color = color_normalized[0], color_normalized[1], color_normalized[2], 1.0
+                elif len(color_normalized) == 4:
+                    clear_color = color_normalized
                 else:
-                    # mypy does not understand that color[3] is guaranteed to work in this codepath, pyright does.
-                    # We can remove this type: ignore if we switch to pyright.
-                    gl.glClearColor(
-                        color[0] / 255, color[1] / 255, color[2] / 255, color[3] / 255  # type: ignore
-                    )
+                    raise ValueError("Color should be a 3 or 4 component tuple")
+
+            gl.glClearColor(*clear_color)
 
             if self.depth_attachment:
+                gl.glClearDepth(depth)
                 gl.glClear(gl.GL_COLOR_BUFFER_BIT | gl.GL_DEPTH_BUFFER_BIT)
             else:
                 gl.glClear(gl.GL_COLOR_BUFFER_BIT)

arcade/perf_graph.py

@@ -292,7 +292,7 @@ def update_graph(self, delta_time: float):
                 self.minimap_texture, projection=self.proj) as fbo:
 
             # Set the background color
-            fbo.clear(self.background_color)
+            fbo.clear(color=self.background_color)
 
             # Draw lines & their labels
             for text in self._all_text_objects:

arcade/text.py

@@ -651,7 +651,7 @@ def create_text_sprite(
         texture_atlas = arcade.get_window().ctx.default_atlas
     texture_atlas.add(texture)
     with texture_atlas.render_into(texture) as fbo:
-        fbo.clear(background_color or arcade.color.TRANSPARENT_BLACK)
+        fbo.clear(color=background_color or arcade.color.TRANSPARENT_BLACK)
         text_object.draw()
 
     return arcade.Sprite(

doc/tutorials/raycasting/example.py

@@ -90,12 +90,12 @@ def load_shader(self):
     def on_draw(self):
         self.channel0.use()
         # clear_color = 0, 0, 0, 0
-        # self.channel0.clear(clear_color)
+        # self.channel0.clear(color=clear_color)
         self.wall_list.draw()
 
         self.channel1.use()
-        # self.channel1.clear(clear_color)
-        self.channel1.clear(arcade.color.ARMY_GREEN)
+        # self.channel1.clear(color=clear_color)
+        self.channel1.clear(color=arcade.color.ARMY_GREEN)
         self.bomb_list.draw()
 
         self.use()

doc/tutorials/shader_inputs/texture_write.py

@@ -20,7 +20,7 @@ def __init__(self):
         self.fbo = self.ctx.framebuffer(color_attachments=[self.tex])
 
         # Put something in the framebuffer to start
-        self.fbo.clear(arcade.color.ALMOND)
+        self.fbo.clear(color=arcade.color.ALMOND)
         with self.fbo:
             arcade.draw_circle_filled(
                 SCREEN_WIDTH / 2,