Add print_report (#334)

* Add print_report

* backends do not have to implement print_report

* fmt

Author: almarklein

wgpu/__init__.py

@@ -33,6 +33,10 @@ def _register_backend(cls):
     globals()["GPU"] = GPU
     globals()["request_adapter"] = gpu.request_adapter
     globals()["request_adapter_async"] = gpu.request_adapter_async
+    if hasattr(gpu, "print_report"):
+        globals()["print_report"] = gpu.print_report
+    else:
+        globals()["print_report"] = _base_GPU.print_report
 
 
 _base_GPU = GPU  # noqa: F405, N816

wgpu/backends/rs.py

@@ -363,6 +363,83 @@ async def request_adapter_async(self, *, canvas, power_preference=None):
             canvas=canvas, power_preference=power_preference
         )  # no-cover
 
+    def _generate_report(self):
+        """Get a dictionary with info about the internal status of WGPU.
+        The structure of the dict is not defined, for the moment. Use print_report().
+        """
+
+        # H: surfaces: WGPUStorageReport, backendType: WGPUBackendType, vulkan: WGPUHubReport, metal: WGPUHubReport, dx12: WGPUHubReport, dx11: WGPUHubReport, gl: WGPUHubReport
+        struct = new_struct_p(
+            "WGPUGlobalReport *",
+            # not used: surfaces
+            # not used: backendType
+            # not used: vulkan
+            # not used: metal
+            # not used: dx12
+            # not used: dx11
+            # not used: gl
+        )
+
+        # H: void f(WGPUInstance instance, WGPUGlobalReport* report)
+        lib.wgpuGenerateReport(get_wgpu_instance(), struct)
+
+        report = {}
+
+        report["surfaces"] = {
+            "occupied": struct.surfaces.numOccupied,
+            "vacant": struct.surfaces.numVacant,
+            "error": struct.surfaces.numError,
+            "element_size": struct.surfaces.elementSize,
+        }
+        report["backend_type"] = struct.backendType  # note: could make this a set
+        for backend in ("vulkan", "metal", "dx12", "dx11", "gl"):
+            c_hub_report = getattr(struct, backend)
+            report[backend] = {}
+            for key in dir(c_hub_report):
+                c_storage_report = getattr(c_hub_report, key)
+                storage_report = {
+                    "occupied": c_storage_report.numOccupied,
+                    "vacant": c_storage_report.numVacant,
+                    "error": c_storage_report.numError,
+                    "element_size": c_storage_report.elementSize,
+                }
+                # if any(x!=0 for x in storage_report.values()):
+                report[backend][key] = storage_report
+
+        return report
+
+    def print_report(self):
+        def print_line(topic, occupied, vacant, error, el_size):
+            print(
+                topic.rjust(20),
+                str(occupied).rjust(8),
+                str(vacant).rjust(8),
+                str(error).rjust(8),
+                str(el_size).rjust(8),
+            )
+
+        def print_storage_report(topic, d):
+            print_line(topic, d["occupied"], d["vacant"], d["error"], d["element_size"])
+
+        report = self._generate_report()
+
+        print(f"{self.__class__.__module__}.WGPU report:")
+        print()
+        print_line("", "Occupied", "Vacant", "Error", "el-size")
+        print()
+        print_storage_report("surfaces", report["surfaces"])
+        for backend in ("vulkan", "metal", "dx12", "dx11", "gl"):
+            backend_has_stuff = False
+            for hub_report in report[backend].values():
+                report_has_stuff = any(x != 0 for x in hub_report.values())
+                backend_has_stuff |= report_has_stuff
+            if backend_has_stuff:
+                print_line(f"--- {backend} ---", "", "", "", "")
+                for key, val in report[backend].items():
+                    print_storage_report(key, val)
+            else:
+                print_line(f"--- {backend} ---", "", "", "", "")
+
 
 class GPUCanvasContext(base.GPUCanvasContext):
     def __init__(self, canvas):

wgpu/base.py

@@ -108,6 +108,11 @@ def get_preferred_canvas_format(self):
         """
         raise RuntimeError("Use canvas.get_preferred_format() instead.")
 
+    @apidiff.add("Usefull")
+    def print_report(self):
+        """Print a report about the interals if the backend."""
+        print(f"{self.__class__.__module__}.GPU: No report available.")
+
 
 class GPUCanvasContext:
     """A context object associated with a canvas, to present what has been drawn."""

wgpu/resources/codegen_report.md

@@ -9,23 +9,23 @@
 * Wrote 35 enums to enums.py
 * Wrote 59 structs to structs.py
 ### Patching API for base.py
-* Diffs for GPU: change get_preferred_canvas_format, change request_adapter, change request_adapter_async
+* Diffs for GPU: add print_report, change get_preferred_canvas_format, change request_adapter, change request_adapter_async
 * Diffs for GPUCanvasContext: add get_preferred_format, add present
 * Diffs for GPUDevice: add adapter, add create_buffer_with_data, hide import_external_texture, hide pop_error_scope, hide push_error_scope
 * Diffs for GPUBuffer: add map_read, add map_write, hide get_mapped_range, hide map_async, hide unmap
 * Diffs for GPUTexture: add size
 * Diffs for GPUTextureView: add size, add texture
 * Diffs for GPUQueue: add read_buffer, add read_texture, hide copy_external_image_to_texture
-* Validated 39 classes, 111 methods, 44 properties
+* Validated 39 classes, 112 methods, 44 properties
 ### Patching API for backends/rs.py
 * Diffs for GPUAdapter: add request_device_tracing
-* Validated 39 classes, 98 methods, 0 properties
+* Validated 39 classes, 100 methods, 0 properties
 ## Validating rs.py
 * Enum BufferMapState missing in wgpu.h
 * Enum PipelineErrorReason missing in wgpu.h
 * Enum AutoLayoutMode missing in wgpu.h
 * Enum CanvasAlphaMode missing in wgpu.h
 * Wrote 231 enum mappings and 49 struct-field mappings to rs_mappings.py
-* Validated 93 C function calls
-* Not using 90 C functions
-* Validated 72 C structs
+* Validated 94 C function calls
+* Not using 89 C functions
+* Validated 73 C structs