Utils¶
The wgpu library provides a few utilities. Note that most functions below need to be explictly imported.
Logger¶
Errors, warnings, and info messages (including messages generated by
wgpu-native) are logged using Python’s default logging mechanics. The
wgpu logger instance is in wgpu.logger
, but can also be obtained
via:
import logging
logger = logging.getLogger("wgpu")
Diagnostics¶
To print a full diagnostic report:
wgpu.diagnostics.print_report()
To inspect (for example) the total buffer usage:
>>> counts = wgpu.diagnostics.object_counts.get_dict()
>>> print(counts["Buffer"])
{'count': 3, 'resource_mem': 784}
- class wgpu._diagnostics.DiagnosticsRoot¶
Root object to access wgpu diagnostics (i.e.
wgpu.diagnostics
).Per-topic diagnostics can be accessed as attributes on this object. These include
system
,wgpu_native_info
,versions
,object_counts
,wgpu_natrive_counts
.- get_dict()¶
Get a dict that represents the full diagnostics info.
The keys are the diagnostic topics, and the values are dicts of dicts. See e.g.
wgpu.diagnostics.counts.get_dict()
for a topic-specific dict.
- get_report()¶
Get the full textual diagnostic report (as a str).
- print_report()¶
Convenience method to print the full diagnostics report.
- class wgpu._diagnostics.Diagnostics(name)¶
Object that represents diagnostics on a specific topic.
This is a base class that must be subclassed to provide diagnostics on a certain topic. Instantiating the class registers it with the root diagnostics object.
- get_dict()¶
Get the diagnostics for this topic, in the form of a Python dict.
Subclasses must implement this method. The dict can be a simple map of keys to values (str, int, float):
foo: 1 bar: 2
If the values are dicts, the data has a table-like layout, with the keys representing the table header:
count mem Adapter: 1 264 Buffer: 4 704
Subdicts are also supported, which results in multi-row entries. In the report, the keys of the subdicts have colons behind them:
count mem backend o v e el_size Adapter: 1 264 vulkan: 1 0 0 264 d3d12: 1 0 0 220 Buffer: 4 704 vulkan: 4 0 0 176 d3d12: 0 0 0 154
- get_report()¶
Get the textual diagnostics report for this topic.
- get_subscript()¶
Get informative text that helps interpret the report.
Subclasses can implement this method. The text will show below the table in the report.
- print_report()¶
Print the diagnostics report for this topic.
Get default device¶
- wgpu.utils.get_default_device()¶
Get a wgpu device object. If this succeeds, it’s likely that the WGPU lib is usable on this system. If not, this call will probably exit (Rust panic). When called multiple times, returns the same global device object (useful for e.g. unit tests).
Compute with buffers¶
from wgpu.utils.compute import compute_with_buffers
- wgpu.utils.compute_with_buffers(*args, **kwargs)¶
Shadertoy¶
from wgpu.utils.shadertoy import Shadertoy
- class wgpu.utils.shadertoy.Shadertoy(shader_code, resolution=(800, 450), offscreen=False, inputs=[])¶
Provides a “screen pixel shader programming interface” similar to shadertoy.
It helps you research and quickly build or test shaders using WGSL or GLSL via WGPU.
- Parameters:
shader_code (str) – The shader code to use.
resolution (tuple) – The resolution of the shadertoy.
offscreen (bool) – Whether to render offscreen. Default is False.
inputs (list) – A list of
ShadertoyChannel
objects. Supports up to 4 inputs. Defaults to sampling a black texture.
The shader code must contain a entry point function:
WGSL:
fn shader_main(frag_coord: vec2<f32>) -> vec4<f32>{}
GLSL:void shader_main(out vec4 frag_color, in vec2 frag_coord){}
It has a parameter
frag_coord
which is the current pixel coordinate (in range 0..resolution, origin is bottom-left), and it must return a vec4<f32> color (for GLSL, it’s theout vec4 frag_color
parameter), which is the color of the pixel at that coordinate.some built-in variables are available in the shader:
i_mouse
: the mouse position in pixelsi_date
: the current date and time as a vec4 (year, month, day, seconds)i_resolution
: the resolution of the shadertoyi_time
: the global time in secondsi_time_delta
: the time since last frame in secondsi_frame
: the frame numberi_framerate
: the number of frames rendered in the last second.
For GLSL, you can also use the aliases
iTime
,iTimeDelta
,iFrame
,iResolution
,iMouse
,iDate
andiFrameRate
of these built-in variables, the entry point function also has an aliasmainImage
, so you can use the shader code copied from shadertoy website without making any changes.- property resolution¶
The resolution of the shadertoy as a tuple (width, height) in pixels.
- property shader_code¶
The shader code to use.
- property shader_type¶
The shader type, automatically detected from the shader code, can be “wgsl” or “glsl”.
- snapshot(time_float: float = 0.0, mouse_pos: tuple = (0, 0, 0, 0))¶
Returns an image of the specified time. (Only available when
offscreen=True
)- Parameters:
time_float (float) – The time to snapshot. It essentially sets
i_time
to a specific number. (Default is 0.0)mouse_pos (tuple) – The mouse position in pixels in the snapshot. It essentially sets
i_mouse
to a 4-tuple. (Default is (0,0,0,0))
- Returns:
snapshot with transparancy. This object can be converted to a numpy array (without copying data)
- Return type:
frame (memoryview)
using
np.asarray(arr)