Context.get_current_texture() can now raise DrawCancelled (#820)

* Context.get_current_texture() can now raise DrawCancelled.

* clean

* codegen and lint

* add docs

* ruff/codegen

* doc

* extra note

Author: almarklein

CHANGELOG.md

@@ -29,7 +29,9 @@ Possible sections in each release:
     * `wgpu.backends.wgpu_native.extras.create_pipeline_layout(..., push_constant_layouts)` -> `device.create_pipeline_layout(..., immediate_size)`
     * `wgpu.backends.wgpu_native.extras.set_push_constants()` -> `encoder.set_immediates()` (and different signature)
     * in wgsl `var<push_constant>` -> `var<immediate>`
-
+* ``context.get_current_texture()`` now raises ``wgpu.DrawCancelled`` when no texture could be obtained, e.g. when the window is occluded.
+  Downstream code should capture that error and skip the frame, optionally invoking some sort of sleep to save energy.
+  See https://github.com/pygfx/wgpu-py/pull/820 for context.
 
 
 ## [v0.31.1] - 23-06-2026

codegen/apipatcher.py

@@ -38,13 +38,16 @@ def patch_base_api(code):
     idl = get_idl_parser()
 
     # Write __all__
-    extra_public_classes = ["GPUPromise"]
+    extra_public_classes = ["GPUPromise", "DrawCancelled"]
     all_public_classes = [*idl.classes.keys(), *extra_public_classes]
+    all_public_classes.sort()
+    all_public_classes.remove("GPU")
+    all_public_classes.insert(0, "GPU")  # ruff RUF022 wants it at the top
     part1, found_all, part2 = code.partition("\n__all__ =")
     if found_all:
         part2 = part2.split("]", 1)[-1]
         line = "\n__all__ = ["
-        line += ", ".join(f'"{name}"' for name in sorted(all_public_classes))
+        line += ", ".join(f'"{name}"' for name in all_public_classes)
         line += "]"
         code = part1 + line + part2
 

docs/wgpu.rst

@@ -56,7 +56,7 @@ Async code
 
 Some methods and properties in the WebGPU API are asynchronous. In wgpu-py, these methods
 are always suffixed with ``_async``. These method also have a synchronous variant, which
-come in two flafours:
+come in two flavours:
 
 * If the method has the plain method name (no suffix), the synchronous method is
   available in WebGPU as well. There's no problem to use this variant.
@@ -180,6 +180,9 @@ Error handling
 Errors in wgpu-native are raised as Python errors where possible. Uncaught errors
 and warnings are logged using the ``wgpu`` logger.
 
+A special :class:`DrawCancelled` exception is raised by ``context.get_current_texture()`` when no
+texture could be obtained (e.g. when the window is occluded) and the frame must be skipped.
+
 There are specific exceptions that can be raised:
 * :class:`GPUError` is the generic (base) error class.
 * :class:`GPUValidationError` is for wgpu validation errors. Shader errors also fall into this category.
@@ -221,6 +224,7 @@ List of GPU classes
     :template: wgpu_class_layout.rst
 
     ~GPU
+    ~DrawCancelled
     ~GPUAdapterInfo
     ~GPUAdapter
     ~GPUBindGroup

examples/gui_direct.py

@@ -51,7 +51,11 @@ def main():
         context.set_physical_size(*glfw.get_framebuffer_size(window))
 
         # draw a frame
-        draw_frame()
+        try:
+            draw_frame()
+        except wgpu.DrawCancelled:  # window occluded
+            time.sleep(0.1)
+            continue
         # present the frame to the screen
         context.present()
         # stats

examples/gui_direct2.py

@@ -89,7 +89,11 @@ def run(self):
                     print(err)
 
             # draw a frame
-            draw_frame()
+            try:
+                draw_frame()
+            except wgpu.DrawCancelled:  # window occluded
+                time.sleep(0.1)
+                continue
             # present the frame to the screen
             context.present()
             # stats

wgpu/_classes.py

@@ -23,6 +23,7 @@
 
 __all__ = [
     "GPU",
+    "DrawCancelled",
     "GPUAdapter",
     "GPUAdapterInfo",
     "GPUBindGroup",
@@ -2449,6 +2450,13 @@ def reason(self) -> enums.DeviceLostReasonEnum:
         return self._reason
 
 
+@apidiff.add("Added because Python deals with native windows")
+class DrawCancelled(Exception):  # noqa: N818
+    """An excepion raised to cancel a draw when the surface texture could not be obtained,
+    e.g. because the window is hidden or occluded.
+    """
+
+
 class GPUError(Exception):
     """A generic GPU error."""
 

wgpu/backends/wgpu_native/_api.py

@@ -706,7 +706,6 @@ class GPUCanvasContext(classes.GPUCanvasContext):
 
     _surface_id = ffi.NULL
     _wgpu_config = None
-    _skip_present_screen = False
 
     def __init__(self, present_info: dict):
         super().__init__(present_info)
@@ -930,8 +929,6 @@ def _create_texture_screen(self):
             # Clear buffer, so we only have to perform these checks when set_physical_size has been called.
             self._new_physical_size = None
 
-        # Prepare for obtaining a texture.
-        status_str_map = enum_int2str["SurfaceGetCurrentTextureStatus"]
         # H: nextInChain: WGPUChainedStruct *, texture: WGPUTexture, status: WGPUSurfaceGetCurrentTextureStatus
         surface_texture = new_struct_p(
             "WGPUSurfaceTexture *",
@@ -944,64 +941,61 @@ def _create_texture_screen(self):
         # H: void f(WGPUSurface surface, WGPUSurfaceTexture * surfaceTexture)
         libf.wgpuSurfaceGetCurrentTexture(self._surface_id, surface_texture)
         status_int = surface_texture.status
-        status_str = status_str_map.get(status_int, "Unknown")
         texture_id = surface_texture.texture
 
         if status_int == lib.WGPUSurfaceGetCurrentTextureStatus_SuccessOptimal:
             # Yay! Everything is good and we can render this frame.
             self._number_of_successive_unsuccesful_textures = 0
+        elif status_int == lib.WGPUSurfaceGetCurrentTextureStatus_Occluded:
+            # Nothing is wrong, but this frame must be skipped
+            self._number_of_successive_unsuccesful_textures = 0
+            raise classes.DrawCancelled("Occluded")
         elif status_int in [
             lib.WGPUSurfaceGetCurrentTextureStatus_SuccessSuboptimal,
-            lib.WGPUSurfaceGetCurrentTextureStatus_Timeout,
             lib.WGPUSurfaceGetCurrentTextureStatus_Outdated,
             lib.WGPUSurfaceGetCurrentTextureStatus_Lost,
         ]:
+            # We can try to re-configure in some cases
             if texture_id:
                 # H: void f(WGPUTexture texture)
                 libf.wgpuTextureRelease(texture_id)
                 texture_id = 0
-            # Try to re-configure, if we can
             self._configure_screen_real()
             # H: void f(WGPUSurface surface, WGPUSurfaceTexture * surfaceTexture)
             libf.wgpuSurfaceGetCurrentTexture(self._surface_id, surface_texture)
             status_int = surface_texture.status
-            status_str = status_str_map.get(status_int, "Unknown")
             texture_id = surface_texture.texture
 
         # If still not optimal, we need to make some decisions ...
         if status_int != lib.WGPUSurfaceGetCurrentTextureStatus_SuccessOptimal:
             # It's ok if we miss a sporadic frame during resizing, but warn if it becomes too much.
+            status_str_map = enum_int2str["SurfaceGetCurrentTextureStatus"]
+            status_str = status_str_map.get(status_int, "Unknown")
             self._number_of_successive_unsuccesful_textures += 1
-            if self._number_of_successive_unsuccesful_textures > 5:
-                n = self._number_of_successive_unsuccesful_textures
-                self._number_of_successive_unsuccesful_textures = 0
+            n = self._number_of_successive_unsuccesful_textures
+            if (n % 100 == 0) or n in (5, 12, 25, 50):
                 logger.warning(
                     f"No succesful surface texture obtained for {n} frames: {status_str!r}"
                 )
+
             # Decide what to do
             if status_int == lib.WGPUSurfaceGetCurrentTextureStatus_SuccessSuboptimal:
                 # Can still use the texture
                 pass
-            elif status_int in [
-                lib.WGPUSurfaceGetCurrentTextureStatus_Timeout,
-                lib.WGPUSurfaceGetCurrentTextureStatus_Outdated,
-                lib.WGPUSurfaceGetCurrentTextureStatus_Lost,
-            ]:
-                # Use a dummy texture that we cannot present
-                if texture_id:
-                    # H: void f(WGPUTexture texture)
-                    libf.wgpuTextureRelease(texture_id)
-                    texture_id = 0
-                self._skip_present_screen = True
-                return self._create_plain_texture()
             else:
+                # lib.WGPUSurfaceGetCurrentTextureStatus_Timeout,
+                # lib.WGPUSurfaceGetCurrentTextureStatus_Outdated,
+                # lib.WGPUSurfaceGetCurrentTextureStatus_Lost,
                 # WGPUSurfaceGetCurrentTextureStatus_OutOfMemory
                 # WGPUSurfaceGetCurrentTextureStatus_DeviceLost
                 # WGPUSurfaceGetCurrentTextureStatus_Error
-                # This is something we cannot recover from.
-                raise RuntimeError(
-                    f"Cannot get surface texture: {status_str} ({status_int})."
-                )
+
+                # Skip the frame
+                if texture_id:
+                    # H: void f(WGPUTexture texture)
+                    libf.wgpuTextureRelease(texture_id)
+                    texture_id = 0
+                raise classes.DrawCancelled(f"{status_str} ({status_int})")
 
         # I don't expect this to happen, but let's check just in case.
         if not texture_id:
@@ -1046,29 +1040,11 @@ def _create_texture_screen(self):
         device = self._config["device"]
         return GPUTexture(label, texture_id, device, tex_info)
 
-    def _create_plain_texture(self):
-        # To have a dummy texture in case we have a size mismatch and must drop frames
-        width, height = self._physical_size
-        width, height = max(width, 1), max(height, 1)
-
-        # Note that the label 'present' is used by read_texture() to determine
-        # that it can use a shared copy buffer.
-        device = self._config["device"]
-        return device.create_texture(
-            label="present",
-            size=(width, height, 1),
-            format=self._config["format"],
-            usage=self._config["usage"] | flags.TextureUsage.COPY_SRC,
-        )
-
     def _present_screen(self):
-        if self._skip_present_screen:
-            self._skip_present_screen = False
-        else:
-            # H: WGPUStatus f(WGPUSurface surface)
-            status = libf.wgpuSurfacePresent(self._surface_id)
-            if status != lib.WGPUStatus_Success:
-                logger.warning("wgpuSurfacePresent failed")
+        # H: WGPUStatus f(WGPUSurface surface)
+        status = libf.wgpuSurfacePresent(self._surface_id)
+        if status != lib.WGPUStatus_Success:
+            logger.warning("wgpuSurfacePresent failed")
 
     def _release(self):
         self._drop_texture()
@@ -4213,6 +4189,10 @@ class GPUInternalError(classes.GPUInternalError, GPUError):
     pass
 
 
+class DrawCancelled(classes.DrawCancelled):
+    pass
+
+
 # %%
 
 

wgpu/resources/codegen_report.md

@@ -20,9 +20,10 @@
 * Diffs for GPUTextureView: add size, add texture
 * Diffs for GPUBindingCommandsMixin: change set_bind_group
 * Diffs for GPUQueue: add read_buffer, add read_texture, hide copy_external_image_to_texture
-* Validated 38 classes, 121 methods, 52 properties
+* Diffs for DrawCancelled: add DrawCancelled
+* Validated 39 classes, 121 methods, 52 properties
 ### Patching API for backends/wgpu_native/_api.py
-* Validated 38 classes, 116 methods, 0 properties
+* Validated 39 classes, 115 methods, 0 properties
 ## Validating backends/wgpu_native/_api.py
 * Enum PipelineErrorReason missing in webgpu.h
 * Enum AutoLayoutMode missing in webgpu.h