Tworzenie aplikacji za pomocą WebGPU

François Beaufort

Dla programistów stron internetowych WebGPU to internetowy interfejs API grafiki, który zapewnia jednolity i szybki interfejs i dostępu do układów GPU. WebGPU udostępnia nowoczesne możliwości sprzętowe i umożliwia renderowanie i obliczenia na procesorach graficznych GPU, podobnie jak w Direct3D 12, Metal i Vulkan.

To prawda, ale ta historia jest niepełna. Interfejs WebGPU jest wynikiem współpracy między innymi największych firm, takich jak Apple, Google, Intel, Mozilla Microsoft, Niektórzy z nich zauważyli że WebGPU może być czymś więcej niż interfejsem API JavaScript, ale wieloplatformową grafiką Interfejs API dla programistów w ekosystemach innych niż sieć.

Głównym przypadkiem użycia był interfejs API JavaScript, wprowadzone w Chrome 113. Jednak inny istotny wskaźnik który oprócz niego opracowaliśmy: webgpu.h C API. Ten plik nagłówka C zawiera listę wszystkich dostępnych procedur i struktur danych WebGPU. Służy jako niezależna od platformy warstwa abstrakcji sprzętowej, tworzenie aplikacji działających na określonych platformach, oferując spójny interfejs na różnych platformach.

Z tego dokumentu dowiesz się, jak napisać małą aplikację w języku C++ przy użyciu WebGPU, która działa zarówno w internecie, jak i na określonych platformach. Uwaga, spojler, ten sam czerwony trójkąt pojawia się w oknach przeglądarki i komputera z niewielkimi zmianami w bazie kodu.

Jak to działa?

Aby zobaczyć ukończoną aplikację, sprawdź repozytorium aplikacji wieloplatformowych WebGPU.

Aplikacja to minimalistyczny przykład w języku C++, który pokazuje, jak korzystać z WebGPU do tworzenia aplikacji komputerowych i internetowych przy użyciu jednej bazy kodu. W środowisku C++ biblioteka WebGPU webgpu.h jest używana jako niezależna od platformy warstwa abstrakcji sprzętowej z kodem C++ o nazwie webgpu_cpp.h.

W przeglądarce aplikacja jest utworzona za pomocą usługi Emscripten, która zawiera powiązania implementujące webgpu.h jako uzupełnienie interfejsu API JavaScript. Na określonych platformach, takich jak macOS czy Windows, ten projekt można tworzyć w oparciu o Dawn – wieloplatformową implementację WebGPU Chromium. Warto wspomnieć o wgpu-native – implementacji Rust dla webgpu.h, która też istnieje, ale nie jest używana w tym dokumencie.

Rozpocznij

Na początek potrzebujesz kompilatora C++ i narzędzia CMake, które pozwalają obsługiwać kompilacje międzyplatformowe w standardowy sposób. W specjalnym folderze utwórz Plik źródłowy main.cpp i plik kompilacji CMakeLists.txt.

Plik main.cpp powinien na razie zawierać pustą funkcję main().

int main() {}

Plik CMakeLists.txt zawiera podstawowe informacje o projekcie. Ostatni wiersz określa plik wykonywalny o nazwie „app” a jego kod źródłowy to 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")

Uruchom cmake -B build, aby utworzyć pliki kompilacji w kompilacji „build/” i cmake --build build, aby utworzyć aplikację i wygenerować plik wykonywalny.

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

# Run the app.
$ ./build/app

Aplikacja działa, ale nie ma jeszcze danych wyjściowych, ponieważ potrzebujesz sposobu na rysowanie elementów na ekranie.

O świcie

Aby narysować trójkąt, możesz skorzystać z Dawn, czyli wieloplatformowej implementacji procesora WebGPU w Chromium. Obejmuje to bibliotekę GLFW C++ w języku C++ do rysowania na ekranie. Jednym ze sposobów pobrania aplikacji Dawn jest dodanie jej jako modułu podrzędnego git do repozytorium. Poniższe polecenia pobierają go o „świcie/” .

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

Następnie dołącz do pliku CMakeLists.txt w ten sposób:

• Opcja CMake DAWN_FETCH_DEPENDENCIES pobiera wszystkie zależności typu Dawn.
• W folderze docelowym znajduje się podfolder dawn/.
• Aplikacja będzie korzystać z celów dawn::webgpu_dawn, glfw i webgpu_glfw, aby można było ich później użyć w pliku main.cpp.

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

Otwieranie okna

Aplikacja Dawn jest już dostępna. Teraz możesz rysować na ekranie za pomocą GLFW. Ta biblioteka dostępna w webgpu_glfw dla wygody umożliwia pisanie kodu niezależnego od platformy w przypadku zarządzania oknami.

Otwieranie okna o nazwie „Okno WebGPU” w rozdzielczości 512 x 512 zaktualizuj plik main.cpp w sposób opisany poniżej. Pamiętaj, że glfwWindowHint() jest tutaj używany do żądania inicjowania interfejsu API grafiki.

#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();
}

Przebudowanie aplikacji i uruchomienie jej tak jak dotychczas powoduje wyświetlenie pustego okna. Robisz postępy!

Pobranie urządzenia GPU

W języku JavaScript navigator.gpu to punkt wejścia umożliwiającego dostęp do GPU. W C++ musisz ręcznie utworzyć zmienną wgpu::Instance używaną w tym samym celu. Dla wygody zadeklaruj instance na górze pliku main.cpp i wywołaj funkcję wgpu::CreateInstance() w elemencie main().

…
#include <webgpu/webgpu_cpp.h>

wgpu::Instance instance;
…

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

Ze względu na kształt interfejsu JavaScript API dostęp do GPU jest asynchroniczny. W C++ utwórz 2 funkcje pomocnicze o nazwie GetAdapter() i GetDevice(), które zwracają odpowiednio funkcję wywołania zwrotnego z obiektami wgpu::Adapter i wgpu::Device.

#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));
}

Aby ułatwić dostęp, zadeklaruj 2 zmienne wgpu::Adapter i wgpu::Device na początku pliku main.cpp. Zaktualizuj funkcję main() tak, aby wywoływała metodę GetAdapter() i przypisz wynikowe wywołanie zwrotne do funkcji adapter, a następnie wywołaj GetDevice() i przypisz wynikowe wywołanie zwrotne do device przed wywołaniem 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();
    });
  });
}

Narysuj trójkąt

Łańcuch wymiany nie jest widoczny w interfejsie JavaScript API, ponieważ zajmuje się nim przeglądarka. W C++ musisz je utworzyć ręcznie. Dla wygody zadeklaruj zmienną wgpu::Surface na górze pliku main.cpp. Tuż po utworzeniu okna GLFW w Start() wywołaj przydatną funkcję wgpu::glfw::CreateSurfaceForWindow(), aby utworzyć wgpu::Surface (podobny do obszaru roboczego HTML), i skonfiguruj ją, wywołując nową funkcję pomocniczą ConfigureSurface() w InitGraphics(). Musisz również wywołać funkcję surface.Present(), aby zaprezentować następną teksturę w pętli podczas. Nie ma to widocznego wpływu, ponieważ nie jest jeszcze renderowane.

#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();
  }
}

Teraz jest dobry moment na utworzenie potoku renderowania za pomocą poniższego kodu. Aby ułatwić dostęp, zadeklaruj zmienną wgpu::RenderPipeline na górze pliku main.cpp i wywołaj funkcję pomocniczą CreateRenderPipeline() w 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();
}

Na koniec wyślij polecenia renderowania do GPU w funkcji Render() nazywanej każdą klatką.

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);
}

Odbudowanie aplikacji przy użyciu CMake i jej uruchomienie powoduje wyświetlenie w oknie długo wyczekiwanego czerwonego trójkąta. Zrób sobie przerwę—zasługujesz na to.

Kompilowanie do WebAssembly

Przyjrzyjmy się minimalnym zmianom wymaganym do dostosowania istniejącej bazy kodu tak, aby narysować taki czerwony trójkąt w oknie przeglądarki. Podstawą aplikacji jest Emscripten – narzędzie do kompilowania programów w języku C/C++ w WebAssembly, które oprócz interfejsu JavaScript API zawiera powiązania implementujące plik webgpu.h.

Aktualizacja ustawień CMake

Po zainstalowaniu Emscripten zaktualizuj plik kompilacji CMakeLists.txt w podany niżej sposób. Trzeba tylko zmienić zaznaczony kod.

• set_target_properties jest używany do automatycznego dodawania „html” zgodnie z rozszerzeniem pliku docelowego. Innymi słowy, zostanie wygenerowany plik „app.html”, .
• Opcja linku aplikacji USE_WEBGPU jest wymagana do włączenia obsługi WebGPU w Emscripten. Bez niej plik main.cpp nie będzie miał dostępu do pliku webgpu/webgpu_cpp.h.
• Aby można było ponownie użyć kodu GLFW, wymagana jest tu też opcja linku aplikacji USE_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()

Zaktualizuj kod

Do utworzenia elementu wgpu::surface w Emscripten wymagany jest element HTML canvas. W tym celu wywołaj funkcję instance.CreateSurface() i podaj selektor #canvas, aby dopasować odpowiedni element kanwy HTML na stronie HTML wygenerowanej przez Emscripten.

Zamiast używać pętli podczas odtwarzania, wywołaj funkcję emscripten_set_main_loop(Render), aby mieć pewność, że funkcja Render() jest wywoływana z odpowiednią, płynną częstotliwością i wyrównuje się z przeglądarką i monitorem.

#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
}

Utwórz aplikację za pomocą Emscripten

Jedyną zmianą potrzebną do utworzenia aplikacji z użyciem narzędzia Emscripten jest dodanie na początku poleceń cmake magicznego skryptu powłoki emcmake. Tym razem wygeneruj aplikację w podfolderze build-web i uruchom serwer HTTP. Na koniec otwórz przeglądarkę i wejdź na 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

.

Co dalej?

Oto, czego możesz się spodziewać w przyszłości:

• Ulepszenia stabilizacji interfejsów API webgpu.h i webgpu_cpp.h.
• Początek obsługi Androida i iOS.

W międzyczasie zgłaszaj sugestie i pytania dotyczące problemów z WebGPU w Emscripten oraz Dawn.

Zasoby

Zachęcam do zapoznania się z kodem źródłowym tej aplikacji.

Jeśli chcesz dowiedzieć się więcej o tworzeniu natywnych aplikacji 3D w języku C++ od podstaw przy użyciu WebGPU, zapoznaj się z dokumentacją dotyczącą WebGPU dla języka C++ i przykładami natywnego procesora internetowego (Dawn Native WebGPU).

Jeśli interesuje Cię Rust, możesz też zapoznać się z biblioteką grafiki wgpu opartą na WebGPU. Obejrzyj ich demonstrację hello-triangle.

Poświadczenia

Ten artykuł napisali Corentin Wallez, Kai Ninomiya i Rachel Andrew.

Zdjęcie: Marc-Olivier Jodoin, Unsplash.