Centralize and document near/far defaults a bit

arcade/camera/camera_2d.py

@@ -10,7 +10,7 @@
 from arcade.camera.data_types import (
     CameraData,
     OrthographicProjectionData,
-    ZeroProjectionDimension,
+    ZeroProjectionDimension, DEFAULT_NEAR_ORTHO, DEFAULT_FAR,
 )
 from arcade.camera.projection_functions import (
     generate_orthographic_matrix,
@@ -90,8 +90,8 @@ def __init__(
         up: tuple[float, float] = (0.0, 1.0),
         zoom: float = 1.0,
         projection: Rect | None = None,
-        near: float = -100.0,
-        far: float = 100.0,
+        near: float = DEFAULT_NEAR_ORTHO,
+        far: float = DEFAULT_FAR,
         *,
         scissor: Rect | None = None,
         render_target: Framebuffer | None = None,

arcade/camera/data_types.py

@@ -7,7 +7,7 @@
 from __future__ import annotations
 
 from contextlib import contextmanager
-from typing import Generator, Protocol
+from typing import Generator, Protocol, Final
 
 from pyglet.math import Vec2, Vec3
 from typing_extensions import Self
@@ -16,6 +16,8 @@
 
 __all__ = [
     "CameraData",
+    "DEFAULT_FAR",
+    "DEFAULT_NEAR_ORTHO",
     "OrthographicProjectionData",
     "PerspectiveProjectionData",
     "Projection",
@@ -25,6 +27,23 @@
     "duplicate_camera_data",
 ]
 
+DEFAULT_NEAR_ORTHO: Final[float] = -100.0
+"""The default backward-facing depth cutoff for orthographic rendering.
+
+Unless an orthographic camera is provided a different value, this will be
+used as the near cutoff for its point of view.
+
+The :py:class:`~arcade.camera.perspective.PerspectiveProjector` uses
+``0.01`` as its default near value to avoid division by zero.
+"""
+
+DEFAULT_FAR: Final[float] = 100.0
+"""The default forward-facing depth cutoff for all Arcade cameras.
+ 
+Unless a camera is provided a different value, anything further away than this
+value will not be drawn.
+"""
+
 
 class ZeroProjectionDimension(ValueError):
     """A projection's dimensions were zero along at least one axis.

arcade/camera/orthographic.py

@@ -6,7 +6,7 @@
 from pyglet.math import Mat4, Vec2, Vec3
 from typing_extensions import Self
 
-from arcade.camera.data_types import CameraData, OrthographicProjectionData, Projector
+from arcade.camera.data_types import CameraData, OrthographicProjectionData, Projector, DEFAULT_NEAR_ORTHO, DEFAULT_FAR
 from arcade.camera.projection_functions import (
     generate_orthographic_matrix,
     generate_view_matrix,
@@ -78,8 +78,8 @@ def __init__(
             0.5 * self._window.width,  # Left, Right
             -0.5 * self._window.height,
             0.5 * self._window.height,  # Bottom, Top
-            -100,
-            100,  # Near, Far
+            DEFAULT_NEAR_ORTHO,
+            DEFAULT_FAR,  # Near, Far
         )
 
     @property

arcade/camera/perspective.py

@@ -7,7 +7,7 @@
 from pyglet.math import Mat4, Vec2, Vec3
 from typing_extensions import Self
 
-from arcade.camera.data_types import CameraData, PerspectiveProjectionData, Projector
+from arcade.camera.data_types import CameraData, PerspectiveProjectionData, Projector, DEFAULT_FAR
 from arcade.camera.projection_functions import (
     generate_perspective_matrix,
     generate_view_matrix,
@@ -27,6 +27,12 @@
 class PerspectiveProjector(Projector):
     """
     The simplest from of a perspective camera.
+
+    .. warning:: Near cutoffs for perspective projection must be greater than zero.
+
+                 This prevents division by zero errors since perspective involves
+                 dividing by distance.
+
     Using ViewData and PerspectiveProjectionData PoDs (Pack of Data)
     it generates the correct projection and view matrices. It also
     provides methods and a context manager for using the matrices in
@@ -78,7 +84,7 @@ def __init__(
             self._window.width / self._window.height,  # Aspect
             60,  # Field of View,
             0.01,
-            100.0,  # near, # far
+            DEFAULT_FAR,  # near, # far
         )
 
     @property

arcade/examples/depth_of_field.py

@@ -33,6 +33,7 @@
 
 import arcade
 from arcade import get_window, SpriteList, SpriteSolidColor, Text, Window, View
+from arcade.camera.data_types import DEFAULT_NEAR_ORTHO, DEFAULT_FAR
 from arcade.color import RED
 from arcade.experimental.postprocessing import GaussianBlur
 from arcade.gl import NEAREST, Program, Texture2D, geometry
@@ -182,6 +183,10 @@ def render(self):
 class GameView(View):
     """Window subclass to hold sprites and rendering helpers.
 
+    To keep the code simpler, this example uses a default camera. That means
+    that any sprite outside Arcade's default camera near and far render cutoffs
+    (``-100.0`` to ``100.0``) will not be drawn.
+
     Args:
         text_color:
             The color of the focus indicator.
@@ -190,13 +195,19 @@ class GameView(View):
         focus_change_speed:
             How fast the focus bounces back and forth
             between the ``-focus_range`` and ``focus_range``.
+        min_sprite_depth:
+            The minimum sprite depth we'll generate sprites between
+         max_sprite_depth:
+            The maximum sprite depth we'll generate sprites between.
     """
 
     def __init__(
         self,
         text_color: RGBA255 = RED,
         focus_range: float = 16.0,
         focus_change_speed: float = 0.1,
+        min_sprite_depth: float = DEFAULT_NEAR_ORTHO,
+        max_sprite_depth: float = DEFAULT_FAR
     ):
         super().__init__()
         self.sprites: SpriteList = SpriteList()
@@ -215,7 +226,7 @@ def __init__(
 
         # Randomize sprite depth, size, and angle, but set color from depth.
         for _ in range(100):
-            depth = uniform(-100, 100)
+            depth = uniform(min_sprite_depth, max_sprite_depth)
             color = Color.from_gray(int(255 * (depth + 100) / 200))
             s = SpriteSolidColor(
                 randint(100, 200),