Membangun aplikasi dengan WebGPU

François Beaufort
François Beaufort
GitHub

Bagi developer web, WebGPU adalah API grafis web yang menyediakan akses terpadu dan cepat ke GPU. WebGPU mengekspos kemampuan hardware modern dan memungkinkan operasi rendering dan komputasi di GPU, mirip dengan Direct3D 12, Metal, dan Vulkan.

Meskipun benar, cerita itu tidak lengkap. WebGPU adalah hasil dari upaya kolaboratif, termasuk perusahaan besar, seperti Apple, Google, Intel, Mozilla, dan Microsoft. Di antara mereka, beberapa menyadari bahwa WebGPU dapat menjadi lebih dari sekadar API JavaScript, tetapi API grafis lintas platform untuk developer di seluruh ekosistem, selain web.

Untuk memenuhi kasus penggunaan utama, JavaScript API diperkenalkan di Chrome 113. Namun, project penting lain telah dikembangkan bersamanya: webgpu.h C API. File header C ini mencantumkan semua prosedur dan struktur data WebGPU yang tersedia. Hal ini berfungsi sebagai hardware abstraction layer yang tidak bergantung pada platform, sehingga memungkinkan Anda mem-build aplikasi khusus platform dengan menyediakan antarmuka yang konsisten di berbagai platform.

Dalam dokumen ini, Anda akan mempelajari cara menulis aplikasi C++ kecil menggunakan WebGPU yang berjalan di web dan platform tertentu. Spoiler alert, Anda akan mendapatkan segitiga merah yang sama yang muncul di jendela browser dan jendela desktop dengan penyesuaian minimal pada codebase Anda.

Screenshot segitiga merah yang didukung WebGPU di jendela browser dan jendela desktop di macOS.
Segitiga yang sama yang didukung oleh WebGPU di jendela browser dan jendela desktop.

Bagaimana cara kerjanya?

Untuk melihat aplikasi yang telah selesai, lihat repositori aplikasi lintas platform WebGPU.

Aplikasi ini adalah contoh C++ minimalis yang menunjukkan cara menggunakan WebGPU untuk mem-build aplikasi desktop dan web dari satu codebase. Di balik layar, WebGPU menggunakan webgpu.h sebagai lapisan abstraksi hardware yang tidak bergantung pada platform melalui wrapper C++ yang disebut webgpu_cpp.h.

Di web, aplikasi dibuat berdasarkan Emscripten, yang memiliki binding yang mengimplementasikan webgpu.h di atas JavaScript API. Pada platform tertentu seperti macOS atau Windows, project ini dapat dibangun dengan Dawn, implementasi WebGPU lintas platform Chromium. Perlu diketahui bahwa wgpu-native, implementasi Rust webgpu.h, juga ada, tetapi tidak digunakan dalam dokumen ini.

Mulai

Untuk memulai, Anda memerlukan compiler C++ dan CMake untuk menangani build lintas platform dengan cara standar. Di dalam folder khusus, buat file sumber main.cpp dan file build CMakeLists.txt.

File main.cpp harus berisi fungsi main() kosong untuk saat ini.

int main() {}

File CMakeLists.txt berisi informasi dasar tentang project. Baris terakhir menentukan nama yang dapat dieksekusi adalah "app" dan kode sumbernya adalah 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")

Jalankan cmake -B build untuk membuat file build di subfolder "build/" dan cmake --build build untuk benar-benar mem-build aplikasi dan membuat file yang dapat dieksekusi.

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

# Run the app.
$ ./build/app

Aplikasi berjalan, tetapi belum ada output, karena Anda memerlukan cara untuk menggambar sesuatu di layar.

Mendapatkan Dawn

Untuk menggambar segitiga, Anda dapat memanfaatkan Dawn, implementasi WebGPU lintas platform Chromium. Ini mencakup library C++ GLFW untuk menggambar ke layar. Salah satu cara untuk mendownload Dawn adalah dengan menambahkannya sebagai submodul git ke repositori Anda. Perintah berikut mengambilnya di sub folder "dawn/".

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

Kemudian, tambahkan ke file CMakeLists.txt sebagai berikut:

  • Opsi DAWN_FETCH_DEPENDENCIES CMake mengambil semua dependensi Dawn.
  • Subfolder dawn/ disertakan dalam target.
  • Aplikasi Anda akan bergantung pada target dawn::webgpu_dawn, glfw, dan webgpu_glfw sehingga Anda dapat menggunakannya dalam file main.cpp nanti.
…
set(DAWN_FETCH_DEPENDENCIES ON)
add_subdirectory("dawn" EXCLUDE_FROM_ALL)
target_link_libraries(app PRIVATE dawn::webgpu_dawn glfw webgpu_glfw)

Membuka jendela

Setelah Dawn tersedia, gunakan GLFW untuk menggambar objek di layar. Library ini disertakan dalam webgpu_glfw untuk memudahkan Anda menulis kode yang tidak bergantung pada platform untuk pengelolaan jendela.

Untuk membuka jendela bernama "Jendela WebGPU" dengan resolusi 512x512, perbarui file main.cpp seperti di bawah. Perhatikan bahwa glfwWindowHint() digunakan di sini untuk tidak meminta inisialisasi API grafis tertentu.

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

Mem-build ulang aplikasi dan menjalankannya seperti sebelumnya kini akan menghasilkan jendela kosong. Kemajuan Anda bagus!

Screenshot jendela macOS kosong.
Jendela kosong.

Mendapatkan perangkat GPU

Di JavaScript, navigator.gpu adalah titik entri untuk mengakses GPU. Di C++, Anda perlu membuat variabel wgpu::Instance secara manual yang digunakan untuk tujuan yang sama. Untuk memudahkan, deklarasikan instance di bagian atas file main.cpp dan panggil wgpu::CreateInstance() di dalam main().

…
#include <webgpu/webgpu_cpp.h>

wgpu::Instance instance;
…

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

Mengakses GPU bersifat asinkron karena bentuk JavaScript API. Di C++, buat dua fungsi bantuan yang disebut GetAdapter() dan GetDevice() yang masing-masing menampilkan fungsi callback dengan wgpu::Adapter dan 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));
}

Untuk memudahkan akses, deklarasikan dua variabel wgpu::Adapter dan wgpu::Device di bagian atas file main.cpp. Perbarui fungsi main() untuk memanggil GetAdapter() dan menetapkan callback hasilnya ke adapter, lalu panggil GetDevice() dan tetapkan callback hasilnya ke device sebelum memanggil 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();
    });
  });
}

Menggambar segitiga

Rantai swap tidak ditampilkan di JavaScript API karena browser menanganinya. Di C++, Anda perlu membuatnya secara manual. Sekali lagi, untuk memudahkan, deklarasikan variabel wgpu::Surface di bagian atas file main.cpp. Tepat setelah membuat jendela GLFW di Start(), panggil fungsi wgpu::glfw::CreateSurfaceForWindow() yang praktis untuk membuat wgpu::Surface (mirip dengan kanvas HTML) dan konfigurasikan dengan memanggil fungsi ConfigureSurface() helper baru di InitGraphics(). Anda juga perlu memanggil surface.Present() untuk menampilkan tekstur berikutnya dalam loop while. Hal ini tidak memiliki efek yang terlihat karena belum ada rendering yang terjadi.

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

Sekarang adalah waktu yang tepat untuk membuat pipeline render dengan kode di bawah ini. Untuk akses yang lebih mudah, deklarasikan variabel wgpu::RenderPipeline di bagian atas file main.cpp dan panggil fungsi bantuan CreateRenderPipeline() di 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();
}

Terakhir, kirim perintah rendering ke GPU dalam fungsi Render() yang dipanggil setiap 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);
}

Membangun ulang aplikasi dengan CMake dan menjalankannya sekarang menghasilkan segitiga merah yang sudah lama dinantikan di jendela. Beristirahatlah—Anda berhak mendapatkannya.

Screenshot segitiga merah di jendela macOS.
Segitiga merah di jendela desktop.

Mengompilasi ke WebAssembly

Mari kita lihat sekarang perubahan minimal yang diperlukan untuk menyesuaikan codebase yang ada untuk menggambar segitiga merah ini di jendela browser. Sekali lagi, aplikasi dibuat berdasarkan Emscripten, alat untuk mengompilasi program C/C++ ke WebAssembly, yang memiliki binding yang menerapkan webgpu.h di atas JavaScript API.

Memperbarui setelan CMake

Setelah Emscripten diinstal, update file build CMakeLists.txt sebagai berikut. Kode yang ditandai adalah satu-satunya hal yang perlu Anda ubah.

  • set_target_properties digunakan untuk menambahkan ekstensi file "html" secara otomatis ke file target. Dengan kata lain, Anda akan membuat file "app.html".
  • Opsi link aplikasi USE_WEBGPU diperlukan untuk mengaktifkan dukungan WebGPU di Emscripten. Tanpanya, file main.cpp Anda tidak dapat mengakses file webgpu/webgpu_cpp.h.
  • Opsi link aplikasi USE_GLFW juga diperlukan di sini agar Anda dapat menggunakan kembali kode 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()

Mengupdate kode

Di Emscripten, pembuatan wgpu::surface memerlukan elemen kanvas HTML. Untuk melakukannya, panggil instance.CreateSurface() dan tentukan pemilih #canvas agar cocok dengan elemen kanvas HTML yang sesuai di halaman HTML yang dihasilkan oleh Emscripten.

Daripada menggunakan loop while, panggil emscripten_set_main_loop(Render) untuk memastikan fungsi Render() dipanggil dengan kecepatan yang lancar dan sesuai dengan browser dan monitor.

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

Mem-build aplikasi dengan Emscripten

Satu-satunya perubahan yang diperlukan untuk mem-build aplikasi dengan Emscripten adalah menambahkan perintah cmake di awal dengan skrip shell emcmake ajaib. Kali ini, buat aplikasi di subfolder build-web dan mulai server HTTP. Terakhir, buka browser Anda dan kunjungi 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
Screenshot segitiga merah di jendela browser.
Segitiga merah di jendela browser.

Langkah berikutnya

Berikut hal yang dapat Anda harapkan pada masa mendatang:

  • Peningkatan stabilitas API webgpu.h dan webgpu_cpp.h.
  • Dukungan awal fajar untuk Android dan iOS.

Sementara itu, ajukan masalah WebGPU untuk Emscripten dan Masalah Dawn beserta saran dan pertanyaan.

Resource

Silakan pelajari kode sumber aplikasi ini.

Jika Anda ingin mempelajari lebih lanjut cara membuat aplikasi 3D native di C++ dari awal dengan WebGPU, lihat Pelajari dokumentasi WebGPU untuk C++ dan Contoh WebGPU Native Dawn.

Jika tertarik dengan Rust, Anda juga dapat menjelajahi library grafis wgpu berdasarkan WebGPU. Lihat demo hello-triangle mereka.

Ucapan terima kasih

Artikel ini ditinjau oleh Corentin Wallez, Kai Ninomiya, dan Rachel Andrew.

Foto oleh Marc-Olivier Jodoin di Unsplash.