Créer une application avec WebGPU

François Beaufort

Pour les développeurs Web, WebGPU est une API graphique Web qui fournit un accès unifié et rapide aux GPU. WebGPU expose des fonctionnalités matérielles modernes et permet d'effectuer des opérations de rendu et de calcul sur un GPU, comme Direct3D 12, Metal et Vulkan.

C'est vrai, mais cette histoire est incomplète. WebGPU est le résultat d'un effort collaboratif impliquant de grandes entreprises telles qu'Apple, Google, Intel, Mozilla et Microsoft. Parmi eux, certains ont réalisé que WebGPU pouvait être plus qu'une API JavaScript, mais une API graphique multiplate-forme pour les développeurs dans différents écosystèmes, en dehors du Web.

Pour répondre au cas d'utilisation principal, une API JavaScript a été introduite dans Chrome 113. Cependant, un autre projet important a été développé en parallèle: l'API C webgpu.h. Ce fichier d'en-tête C répertorie toutes les procédures et structures de données disponibles de WebGPU. Il sert de couche d'abstraction matérielle indépendante de la plate-forme, ce qui vous permet de créer des applications spécifiques à la plate-forme en fournissant une interface cohérente entre les différentes plates-formes.

Dans ce document, vous allez apprendre à écrire une petite application C++ à l'aide de WebGPU qui s'exécute à la fois sur le Web et sur des plates-formes spécifiques. Attention, vous verrez le même triangle rouge dans une fenêtre de navigateur et une fenêtre d'ordinateur, avec des ajustements minimes de votre codebase.

Même triangle optimisé par WebGPU dans une fenêtre de navigateur et une fenêtre d'ordinateur.

Fonctionnement

Pour voir l'application terminée, consultez le dépôt de l'application multiplate-forme WebGPU.

L'application est un exemple minimaliste en C++ qui montre comment utiliser WebGPU pour créer des applications Web et de bureau à partir d'un seul codebase. En interne, il utilise webgpu.h de WebGPU comme couche d'abstraction matérielle indépendante de la plate-forme via un wrapper C++ appelé webgpu_cpp.h.

Avertissement:Les API webgpu.h et webgpu_cpp.h sont susceptibles d'être modifiées.

Sur le Web, l'application est compilée avec Emscripten, qui dispose de liaisons implémentant webgpu.h au-dessus de l'API JavaScript. Sur des plates-formes spécifiques telles que macOS ou Windows, ce projet peut être compilé avec Dawn, l'implémentation WebGPU multiplate-forme de Chromium. Notez qu'wgpu-native, une implémentation Rust de webgpu.h, existe également, mais n'est pas utilisé dans ce document.

Commencer

Pour commencer, vous avez besoin d'un compilateur C++ et de CMake pour gérer les builds multiplates-formes de manière standard. Dans un dossier dédié, créez un fichier source main.cpp et un fichier de compilation CMakeLists.txt.

Pour l'instant, le fichier main.cpp doit contenir une fonction main() vide.

int main() {}

Le fichier CMakeLists.txt contient des informations de base sur le projet. La dernière ligne spécifie que le nom de l'exécutable est "app" et que son code source est main.cpp.

cmake_minimum_required(VERSION 3.13) # CMake version check
project(app)                         # Create project "app"
set(CMAKE_CXX_STANDARD 20)           # Enable C++20 standard

add_executable(app "main.cpp")

Exécutez cmake -B build pour créer des fichiers de compilation dans un sous-dossier "build/" et cmake --build build pour compiler l'application et générer le fichier exécutable.

# Build the app with CMake.
$ cmake -B build && cmake --build build

# Run the app.
$ ./build/app

L'application s'exécute, mais aucune sortie n'est générée, car vous devez trouver un moyen de dessiner des éléments à l'écran.

Obtenir Dawn

Pour dessiner votre triangle, vous pouvez utiliser Dawn, l'implémentation WebGPU multiplate-forme de Chromium. Cela inclut la bibliothèque C++ GLFW pour le dessin à l'écran. Pour télécharger Dawn, vous pouvez l'ajouter en tant que sous-module Git à votre dépôt. Les commandes suivantes le récupèrent dans un sous-dossier "dawn/".

$ git init
$ git submodule add https://dawn.googlesource.com/dawn

Ajoutez ensuite les éléments suivants au fichier CMakeLists.txt:

• L'option DAWN_FETCH_DEPENDENCIES de CMake récupère toutes les dépendances de Dawn.
• Le sous-dossier dawn/ est inclus dans la cible.
• Votre application dépendra des cibles dawn::webgpu_dawn, glfw et webgpu_glfw afin que vous puissiez les utiliser plus tard dans le fichier main.cpp.

…
set(DAWN_FETCH_DEPENDENCIES ON)
add_subdirectory("dawn" EXCLUDE_FROM_ALL)
target_link_libraries(app PRIVATE dawn::webgpu_dawn glfw webgpu_glfw)

Ouvrir une fenêtre

Maintenant que Dawn est disponible, utilisez GLFW pour dessiner des éléments à l'écran. Cette bibliothèque incluse dans webgpu_glfw pour plus de commodité vous permet d'écrire du code indépendant de la plate-forme pour la gestion des fenêtres.

Pour ouvrir une fenêtre intitulée "Fenêtre WebGPU" avec une résolution de 512x512, mettez à jour le fichier main.cpp comme indiqué ci-dessous. Notez que glfwWindowHint() est utilisé ici pour ne demander aucune initialisation d'API graphique particulière.

#include <GLFW/glfw3.h>

const uint32_t kWidth = 512;
const uint32_t kHeight = 512;

void Start() {
  if (!glfwInit()) {
    return;
  }

  glfwWindowHint(GLFW_CLIENT_API, GLFW_NO_API);
  GLFWwindow* window =
      glfwCreateWindow(kWidth, kHeight, "WebGPU window", nullptr, nullptr);

  while (!glfwWindowShouldClose(window)) {
    glfwPollEvents();
    // TODO: Render a triangle using WebGPU.
  }
}

int main() {
  Start();
}

Si vous recompilez l'application et l'exécutez comme avant, une fenêtre vide s'affiche. Vous faites des progrès !

Fenêtre vide.

Obtenir l'appareil GPU

En JavaScript, navigator.gpu est le point d'entrée permettant d'accéder au GPU. En C++, vous devez créer manuellement une variable wgpu::Instance qui sert au même objectif. Pour plus de commodité, déclarez instance en haut du fichier main.cpp et appelez wgpu::CreateInstance() dans main().

…
#include <webgpu/webgpu_cpp.h>

wgpu::Instance instance;
…

int main() {
  instance = wgpu::CreateInstance();
  Start();
}

L'accès au GPU est asynchrone en raison de la forme de l'API JavaScript. En C++, créez deux fonctions d'assistance appelées GetAdapter() et GetDevice() qui renvoient respectivement une fonction de rappel avec un wgpu::Adapter et un wgpu::Device.

Remarque:Cet exemple est simplifié lorsque l'API WebAssembly JavaScript Promise Integration est disponible. Ce n'est pas le cas au moment de la rédaction.

#include <iostream>
…

void GetAdapter(void (*callback)(wgpu::Adapter)) {
  instance.RequestAdapter(
      nullptr,
      [](WGPURequestAdapterStatus status, WGPUAdapter cAdapter,
         const char* message, void* userdata) {
        if (status != WGPURequestAdapterStatus_Success) {
          exit(0);
        }
        wgpu::Adapter adapter = wgpu::Adapter::Acquire(cAdapter);
        reinterpret_cast<void (*)(wgpu::Adapter)>(userdata)(adapter);
  }, reinterpret_cast<void*>(callback));
}

void GetDevice(void (*callback)(wgpu::Device)) {
  adapter.RequestDevice(
      nullptr,
      [](WGPURequestDeviceStatus status, WGPUDevice cDevice,
          const char* message, void* userdata) {
        wgpu::Device device = wgpu::Device::Acquire(cDevice);
        device.SetUncapturedErrorCallback(
            [](WGPUErrorType type, const char* message, void* userdata) {
              std::cout << "Error: " << type << " - message: " << message;
            },
            nullptr);
        reinterpret_cast<void (*)(wgpu::Device)>(userdata)(device);
  }, reinterpret_cast<void*>(callback));
}

Pour un accès plus facile, déclarez deux variables wgpu::Adapter et wgpu::Device en haut du fichier main.cpp. Mettez à jour la fonction main() pour appeler GetAdapter() et attribuer son rappel de résultat à adapter, puis appelez GetDevice() et attribuez son rappel de résultat à device avant d'appeler Start().

wgpu::Adapter adapter;
wgpu::Device device;
…

int main() {
  instance = wgpu::CreateInstance();
  GetAdapter([](wgpu::Adapter a) {
    adapter = a;
    GetDevice([](wgpu::Device d) {
      device = d;
      Start();
    });
  });
}

Dessiner un triangle

La chaîne de remplacement n'est pas exposée dans l'API JavaScript, car le navigateur s'en occupe. En C++, vous devez le créer manuellement. Encore une fois, pour plus de commodité, déclarez une variable wgpu::Surface en haut du fichier main.cpp. Juste après avoir créé la fenêtre GLFW dans Start(), appelez la fonction wgpu::glfw::CreateSurfaceForWindow() pratique pour créer un wgpu::Surface (similaire à un canevas HTML) et configurez-le en appelant la nouvelle fonction d'assistance ConfigureSurface() dans InitGraphics(). Vous devez également appeler surface.Present() pour présenter la prochaine texture dans la boucle while. Cela n'a aucun effet visible, car aucun rendu n'est effectué pour le moment.

#include <webgpu/webgpu_glfw.h>
…

wgpu::Surface surface;
wgpu::TextureFormat format;

void ConfigureSurface() {
  wgpu::SurfaceCapabilities capabilities;
  surface.GetCapabilities(adapter, &capabilities);
  format = capabilities.formats[0];

  wgpu::SurfaceConfiguration config{
      .device = device,
      .format = format,
      .width = kWidth,
      .height = kHeight};
  surface.Configure(&config);
}

void InitGraphics() {
  ConfigureSurface();
}

void Render() {
  // TODO: Render a triangle using WebGPU.
}

void Start() {
  …
  surface = wgpu::glfw::CreateSurfaceForWindow(instance, window);

  InitGraphics();

  while (!glfwWindowShouldClose(window)) {
    glfwPollEvents();
    Render();
    surface.Present();
    instance.ProcessEvents();
  }
}

C'est le moment de créer le pipeline de rendu avec le code ci-dessous. Pour un accès plus facile, déclarez une variable wgpu::RenderPipeline en haut du fichier main.cpp et appelez la fonction d'assistance CreateRenderPipeline() dans InitGraphics().

wgpu::RenderPipeline pipeline;
…

const char shaderCode[] = R"(
    @vertex fn vertexMain(@builtin(vertex_index) i : u32) ->
      @builtin(position) vec4f {
        const pos = array(vec2f(0, 1), vec2f(-1, -1), vec2f(1, -1));
        return vec4f(pos[i], 0, 1);
    }
    @fragment fn fragmentMain() -> @location(0) vec4f {
        return vec4f(1, 0, 0, 1);
    }
)";

void CreateRenderPipeline() {
  wgpu::ShaderModuleWGSLDescriptor wgslDesc{};
  wgslDesc.code = shaderCode;

  wgpu::ShaderModuleDescriptor shaderModuleDescriptor{
      .nextInChain = &wgslDesc};
  wgpu::ShaderModule shaderModule =
      device.CreateShaderModule(&shaderModuleDescriptor);

  wgpu::ColorTargetState colorTargetState{.format = format};

  wgpu::FragmentState fragmentState{.module = shaderModule,
                                    .targetCount = 1,
                                    .targets = &colorTargetState};

  wgpu::RenderPipelineDescriptor descriptor{
      .vertex = {.module = shaderModule},
      .fragment = &fragmentState};
  pipeline = device.CreateRenderPipeline(&descriptor);
}

void InitGraphics() {
  …
  CreateRenderPipeline();
}

Enfin, envoyez des commandes de rendu au GPU dans la fonction Render() appelée à chaque frame.

void Render() {
  wgpu::SurfaceTexture surfaceTexture;
  surface.GetCurrentTexture(&surfaceTexture);

  wgpu::RenderPassColorAttachment attachment{
      .view = surfaceTexture.texture.CreateView(),
      .loadOp = wgpu::LoadOp::Clear,
      .storeOp = wgpu::StoreOp::Store};

  wgpu::RenderPassDescriptor renderpass{.colorAttachmentCount = 1,
                                        .colorAttachments = &attachment};

  wgpu::CommandEncoder encoder = device.CreateCommandEncoder();
  wgpu::RenderPassEncoder pass = encoder.BeginRenderPass(&renderpass);
  pass.SetPipeline(pipeline);
  pass.Draw(3);
  pass.End();
  wgpu::CommandBuffer commands = encoder.Finish();
  device.GetQueue().Submit(1, &commands);
}

Si vous recompilez l'application avec CMake et l'exécutez, le triangle rouge tant attendu s'affiche dans une fenêtre. Faites une pause, vous l'avez bien mérité.

Triangle rouge dans une fenêtre d'ordinateur.

Compiler en WebAssembly

Voyons maintenant les modifications minimales requises pour ajuster votre base de code existante afin de dessiner ce triangle rouge dans une fenêtre de navigateur. Encore une fois, l'application est compilée avec Emscripten, un outil permettant de compiler des programmes C/C++ en WebAssembly, qui comporte des liaisons implémentant webgpu.h au-dessus de l'API JavaScript.

Modifier les paramètres CMake

Une fois Emscripten installé, mettez à jour le fichier de compilation CMakeLists.txt comme suit. Le code mis en surbrillance est la seule chose que vous devez modifier.

• set_target_properties permet d'ajouter automatiquement l'extension de fichier "html" au fichier cible. En d'autres termes, vous allez générer un fichier "app.html".
• L'option de lien d'application USE_WEBGPU est requise pour activer la prise en charge de WebGPU dans Emscripten. Sans elle, votre fichier main.cpp ne peut pas accéder au fichier webgpu/webgpu_cpp.h.
• L'option de lien d'application USE_GLFW est également requise ici pour que vous puissiez réutiliser votre code GLFW.

cmake_minimum_required(VERSION 3.13) # CMake version check
project(app)                         # Create project "app"
set(CMAKE_CXX_STANDARD 20)           # Enable C++20 standard

add_executable(app "main.cpp")

if(EMSCRIPTEN)
  set_target_properties(app PROPERTIES SUFFIX ".html")
  target_link_options(app PRIVATE "-sUSE_WEBGPU=1" "-sUSE_GLFW=3")
else()
  set(DAWN_FETCH_DEPENDENCIES ON)
  add_subdirectory("dawn" EXCLUDE_FROM_ALL)
  target_link_libraries(app PRIVATE dawn::webgpu_dawn glfw webgpu_glfw)
endif()

Mettre à jour le code

Dans Emscripten, la création d'un wgpu::surface nécessite un élément de canevas HTML. Pour ce faire, appelez instance.CreateSurface() et spécifiez le sélecteur #canvas pour qu'il corresponde à l'élément de canevas HTML approprié dans la page HTML générée par Emscripten.

Au lieu d'utiliser une boucle while, appelez emscripten_set_main_loop(Render) pour vous assurer que la fonction Render() est appelée à un débit fluide approprié qui s'aligne correctement sur le navigateur et l'écran.

#include <GLFW/glfw3.h>
#include <webgpu/webgpu_cpp.h>
#include <iostream>
#if defined(__EMSCRIPTEN__)
#include <emscripten/emscripten.h>
#else
#include <webgpu/webgpu_glfw.h>
#endif

void Start() {
  if (!glfwInit()) {
    return;
  }

  glfwWindowHint(GLFW_CLIENT_API, GLFW_NO_API);
  GLFWwindow* window =
      glfwCreateWindow(kWidth, kHeight, "WebGPU window", nullptr, nullptr);

#if defined(__EMSCRIPTEN__)
  wgpu::SurfaceDescriptorFromCanvasHTMLSelector canvasDesc{};
  canvasDesc.selector = "#canvas";

  wgpu::SurfaceDescriptor surfaceDesc{.nextInChain = &canvasDesc};
  surface = instance.CreateSurface(&surfaceDesc);
#else
  surface = wgpu::glfw::CreateSurfaceForWindow(instance, window);
#endif

  InitGraphics();

#if defined(__EMSCRIPTEN__)
  emscripten_set_main_loop(Render, 0, false);
#else
  while (!glfwWindowShouldClose(window)) {
    glfwPollEvents();
    Render();
    surface.Present();
    instance.ProcessEvents();
  }
#endif
}

Créer l'application avec Emscripten

La seule modification nécessaire pour créer l'application avec Emscripten consiste à ajouter le script shell emcmake magique au début des commandes cmake. Cette fois, générez l'application dans un sous-dossier build-web et démarrez un serveur HTTP. Enfin, ouvrez votre navigateur et accédez à build-web/app.html.

# Build the app with Emscripten.
$ emcmake cmake -B build-web && cmake --build build-web

# Start a HTTP server.
$ npx http-server

Triangle rouge dans une fenêtre de navigateur.

Étape suivante

Voici ce à quoi vous pouvez vous attendre à l'avenir:

• Améliorations apportées à la stabilisation des API webgpu.h et webgpu_cpp.h.
• Prise en charge initiale de Dawn pour Android et iOS.

En attendant, veuillez signaler les problèmes WebGPU pour Emscripten et les problèmes Dawn avec vos suggestions et questions.

Ressources

N'hésitez pas à explorer le code source de cette application.

Si vous souhaitez en savoir plus sur la création d'applications 3D natives en C++ à partir de zéro avec WebGPU, consultez la documentation d'apprentissage de WebGPU pour C++ et les exemples de WebGPU natif Dawn.

Si Rust vous intéresse, vous pouvez également explorer la bibliothèque graphique wgpu basée sur WebGPU. Découvrez la démonstration hello-triangle.

Remerciements

Cet article a été relu par Corentin Wallez, Kai Ninomiya et Rachel Andrew.

Photo de Marc-Olivier Jodoin sur Unsplash.