wgpu

WGPU

wgpu ist eine plattformübergreifende, sichere, reine RUST-Grafik-API. Es läuft nativ auf Vulkan, Metall, D3D12 und OpenGL; und über WebGL2 und WebGPU auf WASM.

Die API basiert auf dem WebGPU -Standard. Es dient als Kern der WebGPU -Integration in Firefox und Deno.

Repo -Übersicht

Das Repository hostet die folgenden Bibliotheken:

• - Benutzer gegenüber der Rost -API.
• - Interne sichere Implementierung.
• - Interne unsichere GPU -API -Abstraktionsschicht.
• - Rosttypen, die zwischen allen Kisten geteilt werden.
• - eigenständige Shader-Übersetzungsbibliothek.
• - Sammlung dünner Abstraktionen über D3D12.
• - WebGPU -Implementierung für die Laufzeit Deno JavaScript/TypeScript

Die folgenden Binärdateien:

• - Werkzeug zum Übersetzen von Shadern zwischen verschiedenen Sprachen mit naga .
• - Werkzeug zum Erhalten von Informationen zu GPUs im System.
• cts_runner - WebGPU -Konformitätstest Suite -Läufer mit deno_webgpu .
• player - eigenständige Anwendung zur Wiederholung der API -Spuren.

Eine Übersicht über alle Komponenten im GFX-RS-Ökosystem finden Sie im großen Bild.

Erste Schritte

Rost

Rostbeispiele finden Sie bei WGPU/Beispielen. Sie können die Beispiele für native mit cargo run --bin wgpu-examples <example> anführen. Siehe die Liste der Beispiele.

Um die Beispiele in einem Browser zu betreiben, führen Sie cargo xtask run-wasm . Öffnen Sie dann http://localhost:8000 in Ihrem Browser, und Sie können ein Beispiel zum Ausführen auswählen. Um eines der WebGPU -basierten Beispiele anzuzeigen, müssen Sie natürlich sicherstellen, dass Ihr Browser es unterstützt.

Wenn Sie nach einem WGPU -Tutorial suchen, sehen Sie sich Folgendes an:

• https://sotrh.github.io/learn-wgpu/

C/C ++

Um WGPU in C/C ++ zu verwenden, benötigen Sie WGPU-Gebot.

Wenn Sie nach einem WGPU C ++ - Tutorial suchen, sehen Sie sich Folgendes an:

• https://eliemichel.github.io/learnwebgpu/

Andere

Wenn Sie WGPU in anderen Sprachen verwenden möchten, gibt es viele Bindungen an den WGPU-Gebiet aus Sprachen wie Python, D, Julia, Kotlin und mehr. Siehe die Liste.

Gemeinschaft

Wir haben den Matrixraum mit einigen verschiedenen Räumen, die die WGPU -Community bilden:

• - Diskussion der Entwicklung der WGPU.
• - Diskussion über die Entwicklung der Naga.
• - Diskussion über die Verwendung der Bibliothek und des umgebenden Ökosystems.
• - Diskussion über alles andere.

Wiki

Wir haben ein Wiki, das als Wissensbasis dient.

Unterstützte Plattformen

API	Fenster	Linux/Android	macOS/iOS	Web (WASM)
Vulkan	✅	✅	?
Metall			✅
DX12	✅
OpenGL	? (GL 3.3+)	? (GL es 3.0+)	?	? (Webgl2)
Webgpu				✅

✅ = Erstklasse -Unterstützung
? = Unterstützung im Ablevel/Best -Aufwand
? = Benötigt die Winkelübersetzungsschicht (nur GL es 3.0)
? = Benötigt die Moltenvk -Translationsschicht
= Nicht unterstützt, obwohl offen für Beiträge

Shader -Unterstützung

WGPU unterstützt Shader in WGSL, Spire-V und GLSL. Sowohl HLSL als auch GLSL haben Compiler, um Spire-V zu zielen. Alle diese Shader -Sprachen können mit jedem Backend verwendet werden, wenn wir alle Conversions umgehen. Zusätzlich verschwindet die Unterstützung für diese Shader -Eingänge nicht.

Während WebGPU keine andere Schattierungssprache als WGSL unterstützt, werden wir Ihre Nicht-WGSL-Shader automatisch konvertieren, wenn Sie auf WebGPU ausgeführt werden.

WGSL wird standardmäßig immer unterstützt, aber GLSL und SPIR-V benötigen Funktionen, die zur Unterstützung ermöglicht werden können.

Beachten Sie, dass die WGSL -Spezifikation noch in der Entwicklung ist, sodass die Entwurfsspezifikation nicht genau beschreibt, was wgpu unterstützt. Weitere Informationen finden Sie unten.

Um Spire-V-Shader zu aktivieren, aktivieren Sie das spirv Merkmal von WGPU. Aktivieren Sie die glsl -Funktion von WGPU, um GLSL -Shader zu aktivieren.

Winkel

Angle ist eine Übersetzungsschicht von GLES bis hin zu anderen von Google entwickelten Backends. Wir unterstützen das Ausführen unseres GLES3 -Backends darüber, um Plattformen DX11 -Unterstützung zu erreichen, die sonst nicht zugänglich sind. Um mit Winkel zu laufen, muss die "Winkel" -Funktion aktiviert und Winkelbibliotheken an einem für die Anwendung sichtbaren Ort platziert werden. Diese Binärdateien können von GFBuild-Angle-Artefakten heruntergeladen werden. Bei Macs mit Apple Silicon kann manuelle Zusammenstellung erforderlich sein.

Unter Windows müssen Sie sie im Allgemeinen in das Arbeitsverzeichnis, im selben Verzeichnis wie die ausführbare Datei oder irgendwo in Ihrem Weg kopieren. Unter Linux können Sie mit der Umgebung LD_LIBRARY_PATH auf sie hinweisen.

MSRV -Richtlinie

Aufgrund komplexer Angehörigen haben wir zwei MSRV -Richtlinien:

• d3d12 , naga , wgpu-core , wgpu-hal und wgpu-types MSRV sind 1,76 , können jedoch in Zukunft niedriger sein als der Rest des Arbeitsbereichs.
• Der Rest des Arbeitsbereichs hat derzeit auch ein MSRV von 1,76 , ist jedoch möglicherweise höher als oben aufgeführte Kisten.

Es wird auf CI (in "/.github/workflows/ci.yml") mit den Variablen CORE_MSRV und REPO_MSRV durchgesetzt. Diese Version kann nur in Breaking -Veröffentlichungen aktualisiert werden, obwohl wir alle drei Monate eine Breaking -Version veröffentlichen.

Die Kisten der naga , wgpu-core , wgpu-hal und wgpu-types sollten vor dem MSRV-MSRV von Firefox für nächtliche Builds niemals einen MSRV erfordern, wie durch den Wert von MINIMUM_RUST_VERSION in python/mozboot/mozboot/util.py festgelegt.

Umgebungsvariablen

Alle Test- und Beispiel -Infrastruktur teilen die gleichen Umgebungsvariablen, die bestimmen, auf welchem ​​Backend/GPU sie ausgeführt werden.

• WGPU_ADAPTER_NAME mit einer Substring des Namens des Adapters, den Sie verwenden möchten (Ex. 1080 entspricht NVIDIA GeForce 1080ti ).
• WGPU_BACKEND mit einer von Kommas getrennten Liste der Backends, die Sie verwenden möchten ( vulkan , metal , dx12 oder gl ).
• WGPU_POWER_PREF Mit der Leistungspräferenz auswählen, wenn ein bestimmter Adaptername nicht angegeben ist ( high , low oder none )
• WGPU_DX12_COMPILER Mit dem DX12 -Shader -Compiler, den Sie verwenden möchten ( dxc oder fxc , beachten Sie, dass dxc dxil.dll und dxcompiler.dll im funktionierenden Verzeichnis benötigt, da es sonst auf fxc zurückfällt)
• WGPU_GLES_MINOR_VERSION MIT DER MONTH OpenGL ES 3 -Versionsnummer anfordern ( 0 , 1 , 2 oder automatic ).
• WGPU_ALLOW_UNDERLYING_NONCOMPLIANT_ADAPTER mit einem Booleschen, ob nicht konforme Treiber aufgezählt werden ( 0 für False, 1 für True).

Verwenden Sie beim Ausführen der CTS die Variablen DENO_WEBGPU_ADAPTER_NAME , DENO_WEBGPU_BACKEND , DENO_WEBGPU_POWER_PREFERENCE .

Testen

Wir haben mehrere Testmethoden, von denen jede unterschiedliche Eigenschaften über WGPU testet. Wir führen unsere Tests automatisch auf CI aus. Der aktuelle Stand der CI -Tests:

Plattform/Backend	Tests	Notizen
Windows/DX12	✔️	Verwenden von Kette
Windows/OpenGL	✔️	Verwenden von llvmpipe
MacOS/Metall	✔️	Verwenden von Hardware -Läufern
Linux/Vulkan	✔️	mit Lavapipe
Linux/OpenGL ES	✔️	Verwenden von llvmpipe
Chrome/Webgl	✔️	mit Swiftshader
Chrome/WebGPU		nicht eingerichtet

Kerntestinfrastruktur

Wir verwenden ein Tool namens cargo nextest um unsere Tests durchzuführen. Um es zu installieren, leiten cargo install cargo-nextest .

Um die Testsuite auszuführen:

 cargo xtask test

Um die Testsuite auf WebGL auszuführen (derzeit unvollständig):

 cd wgpu
wasm-pack test --headless --chrome --no-default-features --features webgl --workspace

Dadurch werden die Tests automatisch mit einem verpackten Browser ausgeführt. Entfernen Sie --headless um die Tests mit jedem Browser durchzuführen, den Sie unter http://localhost:8000 wünschen.

Wenn Sie ein Benutzer sind und eine Möglichkeit haben möchten, zu WGPU beizutragen, benötigen wir immer mehr Hilfe beim Schreiben von Testfällen.

WebGPU -Konformitätstestsuite

WebGPU enthält eine Konformitätstestsuite, um zu überprüfen, ob die Implementierungen korrekt funktionieren. Wir können diese CTS gegen WGPU ausführen.

Um die CTS auszuführen, müssen Sie sich zunächst ansehen:

 git clone https://github.com/gpuweb/cts.git
cd cts
# works in bash and powershell
git checkout $(cat ../cts_runner/revision.txt)

Um einen bestimmten Testssatz durchzuführen:

 # Must be inside the `cts` folder we just checked out, else this will fail
cargo run --manifest-path ../Cargo.toml -p cts_runner --bin cts_runner -- ./tools/run_deno --verbose "<test string>"

Um die vollständige Liste der Tests zu finden, gehen Sie zum Online -CTS -Viewer.

Die Liste der derzeit aktivierten CTS -Tests finden Sie hier.

Verfolgung der WebGPU- und WGSL -Entwurfsspezifikationen

Die wgpu -Kiste soll eine idiomatische Rostübersetzung der WebGPU -API sein. Diese Spezifikation, zusammen mit ihrer Schattierungssprache WGSL, befindet sich beide noch in der Phase "Arbeitsentwurf", und während die allgemeinen Umrisse stabil sind, ändern sich die Details häufig. Bis die Spezifikation stabilisiert ist, unterscheidet sich die wgpu -Kiste und die Version von WGSL, die sie implementiert, wahrscheinlich von dem, was angegeben wird, wenn die Implementierung aufkommt.

Genau welche WGSL -Funktionen wgpu unterstützt, hängt davon ab, wie Sie es verwenden:

• Wenn wgpu als natives Code ausgeführt wird, verwendet sie die NAGA -Kiste, um den WGSL -Code in die Schattierungssprache der nativen GPU -API Ihrer Plattform zu übersetzen. Naga hat einen Meilenstein für die Einholung der WGSL-Spezifikation, aber im Allgemeinen gibt es keine aktuelle Zusammenfassung der Unterschiede zwischen Naga und der WGSL-Spezifikation.

• Beim Ausführen in einem Webbrowser (durch Kompilierung zu WebAssembly) ohne aktiviertes "webgl" stützt sich wgpu auf die WebGPU -Implementierung des Browsers. WGSL -Shader werden einfach an den Browser übergeben, sodass festgelegt wird, welche WGSL -Funktionen Sie verwenden können.

• Wenn Sie in einem Webbrowser mit aktivierter wgpu -Funktion "webgl" ausgeführt werden, verwendet wgpu NAGA, um WGSL -Programme in GLSL zu übersetzen. Dies verwendet dieselbe Version von Naga, als ob Sie wgpu als nativen Code ausführen würden.

Koordinatensysteme

WGPU verwendet die Koordinatensysteme von D3D und Metall:

Machen	Textur