blender-core-gpu

To migrate viewport overlays from bgl to the gpu module, replace deprecated bgl calls with gpu module APIs for shaders, batches, and state management. This ensures compatibility across Blender 3.x through 5.x and prevents overlay rendering failures.

Custom POLYLINE shaders fail in Blender 4.x when mandatory uniforms like viewportSize and lineWidth are missing. You must provide these required shader uniforms and use version-correct built-in shader names to ensure lines render properly.

The correct way to remove SpaceView3D draw handlers is to strictly manage the draw-handler lifecycle by removing them during unregister. This prevents leaked ghost overlays and crashes caused by dangling GPU state references.

To prevent crashes during GPUOffScreen rendering, execute GPU operations on the main thread and explicitly free the GPUOffScreen object after use. Restoring GPU state after rendering also avoids production-breaking failures.

Blender 5.0 does not support the bgl module for custom viewport overlays. The bgl module has been fully removed, requiring developers to use the gpu module for shaders, batches, and textures to maintain drawing functionality.

To draw depth-tested debug lines in the Blender viewport, use the gpu module to create line batches with custom shaders. Apply proper GPU state management to ensure depth testing works correctly without leaking state.