Documentation: Add comprehensive docstrings for Vulkan compatibility methods - improves code maintainability and developer understanding

Author: ra100

model/base_entity.py

@@ -69,11 +69,30 @@ def is_dirty(self, value: bool):
         self.dirty = value
 
     def _is_vulkan_backend(self):
-        """Check if the current GPU backend is Vulkan."""
+        """
+        Check if the current GPU backend is Vulkan.
+
+        Uses cached backend detection for performance. This method is called
+        frequently during rendering operations, so caching prevents expensive
+        repeated GPU queries.
+
+        Returns:
+            bool: True if backend is Vulkan, False for OpenGL or other backends
+        """
         return BackendCache.is_vulkan()
 
     @property
     def _shader(self):
+        """
+        Get the appropriate shader for this entity based on GPU backend.
+
+        Vulkan and OpenGL require different shaders for optimal rendering:
+        - Vulkan: Uses built-in POLYLINE_UNIFORM_COLOR for proper line width support
+        - OpenGL: Uses custom shaders with dash pattern support
+
+        Returns:
+            GPUShader: Appropriate shader for current backend and entity type
+        """
         is_vulkan = self._is_vulkan_backend()
 
         if self.is_point():
@@ -233,6 +252,19 @@ def is_dashed(self):
         return False
 
     def draw(self, context):
+        """
+        Render this entity using GPU-appropriate methods.
+
+        This method handles rendering differences between Vulkan and OpenGL:
+        - Vulkan: Uses POLYLINE_UNIFORM_COLOR shader with lineWidth/viewportSize uniforms
+        - OpenGL: Uses custom shaders with traditional gpu.state line width setting
+
+        For points on Vulkan, entities should override update() to create triangle
+        geometry instead of using point primitives.
+
+        Args:
+            context: Blender context containing viewport and region information
+        """
         if not self.is_visible(context):
             return
 

utilities/constants.py

@@ -11,7 +11,18 @@
 
 # Rendering constants for Vulkan compatibility
 class RenderingConstants:
-    """Centralized rendering constants for consistent visual appearance."""
+    """
+    Centralized rendering constants for consistent visual appearance across GPU backends.
+
+    These constants ensure consistent rendering between Vulkan and OpenGL backends,
+    particularly for geometry-based rendering on Vulkan where traditional point/line
+    primitives have limitations.
+
+    Vulkan Compatibility Notes:
+    - Point sizes are used for triangle geometry (rectangles/cubes)
+    - Line widths apply to POLYLINE_UNIFORM_COLOR shader uniforms
+    - Dash patterns create actual geometry gaps rather than shader effects
+    """
 
     # Point sizes for Vulkan geometry-based rendering
     VULKAN_POINT_2D_SIZE = 0.06  # Size of 2D point rectangles
@@ -27,12 +38,32 @@ class RenderingConstants:
 
     @classmethod
     def dash_pattern_length(cls):
-        """Total length of one dash pattern (dash + gap)."""
+        """
+        Calculate total length of one complete dash pattern.
+
+        Returns:
+            float: Combined length of dash + gap for pattern calculations
+        """
         return cls.DASH_LENGTH + cls.GAP_LENGTH
 
 # GPU Backend detection cache
 class BackendCache:
-    """Cache GPU backend detection to avoid repeated expensive queries."""
+    """
+    Performance cache for GPU backend detection to avoid repeated expensive queries.
+
+    The gpu.platform.backend_type_get() call is expensive and happens frequently
+    during rendering operations. This cache stores the result after the first call
+    and provides fast subsequent access.
+
+    Thread Safety:
+        This cache is designed for single-threaded use within Blender's main thread.
+
+    Usage:
+        if BackendCache.is_vulkan():
+            # Use Vulkan-specific rendering path
+        else:
+            # Use OpenGL fallback
+    """
     _backend_type = None
     _is_vulkan = None