瞭解如何使用 Emscripten 從 WebAssembly 在網路上算繪 2D 圖形。
不同的作業系統有不同的繪圖 API。在撰寫跨平台程式碼或將圖形從一個系統移植到另一個系統時,這些差異會變得更加令人困惑,包括將原生程式碼移植到 WebAssembly 時。
在這篇文章中,您將瞭解幾種透過 C 或 Emscripten 編譯而成的 C++ 程式碼,為網路上的畫布元素繪製 2D 圖像的方法。
透過 Embind 繪製畫布
如果您要建立新專案,而非嘗試轉移現有專案,最簡單的方式就是透過 Emscripten 的繫結系統 Embind 使用 HTML Canvas API。Embind 可讓您直接操作任意 JavaScript 值。
如要瞭解如何使用 Embind,請先參考以下 MDN 範例,找出含有 <canvas> 元素的形狀,然後在其上繪製一些形狀
const canvas = document.getElementById('canvas');
const ctx = canvas.getContext('2d');
ctx.fillStyle = 'green';
ctx.fillRect(10, 10, 150, 100);
以下說明如何使用 Embind 將音譯為 C++:
#include <emscripten/val.h>
using emscripten::val;
// Use thread_local when you want to retrieve & cache a global JS variable once per thread.
thread_local const val document = val::global("document");
// …
int main() {
val canvas = document.call<val>("getElementById", "canvas");
val ctx = canvas.call<val>("getContext", "2d");
ctx.set("fillStyle", "green");
ctx.call<void>("fillRect", 10, 10, 150, 100);
}
連結這組程式碼時,請務必傳遞 --bind
,以便啟用 Embind:
emcc --bind example.cpp -o example.html
接著,您可以使用靜態伺服器提供已編譯的素材資源,並在瀏覽器中載入範例:
選擇無框畫元素
搭配上述 shell 指令使用 Emscripten 產生的 HTML 殼層時,系統會自動設定畫布。這麼做可讓您更輕鬆地建構簡單的示範和範例,但在較大型應用程式中,您可能會想要在自己設計的 HTML 網頁中加入 Emscripten 產生的 JavaScript 和 WebAssembly。
系統產生的 JavaScript 程式碼會尋找儲存在 Module.canvas
屬性中的畫布元素。如同其他模組屬性,您可以在初始化期間設定此屬性。
如果使用 ES6 模式 (將輸出內容設為副檔名為 .mjs
的路徑,或使用 -s EXPORT_ES6
設定),就可以傳遞以下畫布:
import initModule from './emscripten-generated.mjs';
const Module = await initModule({
canvas: document.getElementById('my-canvas')
});
如果您使用一般指令碼輸出內容,請先宣告 Module
物件,再載入 Emscripten 產生的 JavaScript 檔案:
<script>
var Module = {
canvas: document.getElementById('my-canvas')
};
</script>
<script src="emscripten-generated.js"></script>
OpenGL 和 SDL2
OpenGL 是用於處理電腦圖像的熱門跨平台 API。在 Emscripten 中使用時,Emscripten 會負責將支援的 OpenGL 作業子集轉換為 WebGL。如果您的應用程式仰賴 OpenGL ES 2.0 或 3.0 支援的功能,但 WebGL 不支援這項功能,Emscripten 仍可模擬這些功能,但您必須透過對應的設定選擇啟用。
您可以直接使用 OpenGL,也可以透過較高層級的 2D 和 3D 圖形程式庫使用。其中幾個已透過 Emscripten 移植到網頁。在這篇文章中,我將著重介紹 2D 圖形。由於 SDL2 經過充分測試,並支援 Emscripten 後端,因此目前建議使用這個程式庫。
繪製矩形
官方網站上的「關於 SDL」部分說明:
Simple DirectMedia Layer 是一種跨平台開發程式庫,旨在透過 OpenGL 和 Direct3D 提供低階存取音訊、鍵盤、滑鼠、搖桿和圖形硬體的功能。
所有這些功能 (控制音訊、鍵盤、滑鼠和圖形) 都已移植,並可與網頁上的 Emscripten 搭配運作,因此您可以輕鬆移植使用 SDL2 建構的整個遊戲。如果您要移植現有專案,請參閱 Emscripten 說明文件中的「Integrating with a build system」一節。
為簡化說明,本文將著重於單一檔案的情況,並將先前的矩形範例轉譯為 SDL2:
#include <SDL2/SDL.h>
int main() {
// Initialize SDL graphics subsystem.
SDL_Init(SDL_INIT_VIDEO);
// Initialize a 300x300 window and a renderer.
SDL_Window *window;
SDL_Renderer *renderer;
SDL_CreateWindowAndRenderer(300, 300, 0, &window, &renderer);
// Set a color for drawing matching the earlier `ctx.fillStyle = "green"`.
SDL_SetRenderDrawColor(renderer, /* RGBA: green */ 0x00, 0x80, 0x00, 0xFF);
// Create and draw a rectangle like in the earlier `ctx.fillRect()`.
SDL_Rect rect = {.x = 10, .y = 10, .w = 150, .h = 100};
SDL_RenderFillRect(renderer, &rect);
// Render everything from a buffer to the actual screen.
SDL_RenderPresent(renderer);
// TODO: cleanup
}
連結至 Emscripten 時,您必須使用 -s USE_SDL=2
。這會告訴 Emscripten 擷取已預先編譯為 WebAssembly 的 SDL2 程式庫,並將其連結至主要應用程式。
emcc example.cpp -o example.html -s USE_SDL=2
在瀏覽器中載入範例後,您會看到熟悉的綠色矩形:
不過,這個程式碼有幾個問題。首先,它缺少適當清理分配的資源。其次,在網頁上,系統不會在應用程式執行完畢後自動關閉網頁,因此可保留畫布上的圖片。不過,如果同樣的程式碼以原生方式重新編譯,
clang example.cpp -o example -lSDL2
並執行時,建立的視窗只會短暫閃爍,並在退出時立即關閉,因此使用者無法看到圖片。
整合事件迴圈
更完整且符合慣例的範例會需要在事件迴圈中等待,直到使用者選擇退出應用程式為止:
#include <SDL2/SDL.h>
int main() {
SDL_Init(SDL_INIT_VIDEO);
SDL_Window *window;
SDL_Renderer *renderer;
SDL_CreateWindowAndRenderer(300, 300, 0, &window, &renderer);
SDL_SetRenderDrawColor(renderer, /* RGBA: green */ 0x00, 0x80, 0x00, 0xFF);
SDL_Rect rect = {.x = 10, .y = 10, .w = 150, .h = 100};
SDL_RenderFillRect(renderer, &rect);
SDL_RenderPresent(renderer);
while (1) {
SDL_Event event;
SDL_PollEvent(&event);
if (event.type == SDL_QUIT) {
break;
}
}
SDL_DestroyRenderer(renderer);
SDL_DestroyWindow(window);
SDL_Quit();
}
將圖片繪製到視窗後,應用程式現在會在迴圈中等待,以便處理鍵盤、滑鼠和其他使用者事件。使用者關閉視窗時,會觸發 SDL_QUIT
事件,系統將攔截並退出迴圈。迴圈結束後,應用程式會執行清理作業,然後自行結束。
現在在 Linux 上編譯這個範例可正常運作,並顯示 300 x 300 和綠色矩形的視窗:
不過,這個範例無法在網路上運作。Emscripten 產生的網頁在載入期間立即凍結,且永遠不會顯示算繪圖片:
發生什麼事?我會引用「使用 WebAssembly 的非同步 Web API」一文中的答案:
簡單來說,瀏覽器會逐一從佇列中提取程式碼,以無限迴圈的方式執行所有程式碼。當某些事件觸發時,瀏覽器會將對應的處理常式排入佇列,並在下一個迴圈迭代時從佇列中取出並執行。這項機制可讓您只使用單一執行緒,同時模擬並行作業並執行大量並行作業。
請特別注意,雖然您的自訂 JavaScript (或 WebAssembly) 程式碼執行時,事件迴圈會遭到封鎖 [...]
先前的範例會執行無限的事件迴圈,而程式碼本身則會在瀏覽器隱含提供的另一個無限事件迴圈中執行。內部迴圈絕不會放棄對外部事件的控制權,因此瀏覽器不會有機會處理外部事件,或是在網頁中繪製內容。
解決這個問題的方法有兩種。
使用 Asyncify 解除事件迴圈封鎖
首先,如同連結文章中所述,您可以使用 Asyncify。這是 Emscripten 功能,可讓您「暫停」C 或 C++ 程式、將控制權交還給事件迴圈,並在某些非同步作業完成時喚醒程式。
這類非同步作業甚至可能「在最短可能時間內休眠」,透過 emscripten_sleep(0)
API 表示。將控制項嵌入迴圈中間,可確保在每次迭代時將控制項傳回至瀏覽器的事件迴圈,讓網頁保持回應能力並處理任何事件:
#include <SDL2/SDL.h>
#ifdef __EMSCRIPTEN__
#include <emscripten.h>
#endif
int main() {
SDL_Init(SDL_INIT_VIDEO);
SDL_Window *window;
SDL_Renderer *renderer;
SDL_CreateWindowAndRenderer(300, 300, 0, &window, &renderer);
SDL_SetRenderDrawColor(renderer, /* RGBA: green */ 0x00, 0x80, 0x00, 0xFF);
SDL_Rect rect = {.x = 10, .y = 10, .w = 150, .h = 100};
SDL_RenderFillRect(renderer, &rect);
SDL_RenderPresent(renderer);
while (1) {
SDL_Event event;
SDL_PollEvent(&event);
if (event.type == SDL_QUIT) {
break;
}
#ifdef __EMSCRIPTEN__
emscripten_sleep(0);
#endif
}
SDL_DestroyRenderer(renderer);
SDL_DestroyWindow(window);
SDL_Quit();
}
現在程式碼需要在啟用 Asyncify 的情況下進行編譯:
emcc example.cpp -o example.html -s USE_SDL=2 -s ASYNCIFY
應用程式又能正常在網頁上運作:
不過,Asyncify 可能會產生不小的程式碼大小開銷。如果僅用於應用程式中的頂層事件迴圈,較適合使用 emscripten_set_main_loop
函式。
使用「main loop」API 解除事件迴圈的封鎖
emscripten_set_main_loop
不需要在展開及倒轉呼叫堆疊時執行任何編譯器轉換,就能避免程式碼大小負擔。不過,在 Exchange 中,您需要手動修改更多程式碼。
首先,事件迴圈的主體必須擷取至個別函式中。接著,必須在第一個引數中使用該函式做為回呼,呼叫 emscripten_set_main_loop
,第二個引數中的 FPS (原生重新整理間隔的 0
),以及一個布林值表示是否要在第三個引數中模擬無限迴圈 (true
):
emscripten_set_main_loop(callback, 0, true);
新建立的回呼無法存取 main
函式中的堆疊變數,因此 window
和 renderer
這類變數必須要從堆積分配的結構體中擷取,並透過 API 的 emscripten_set_main_loop_arg
變體傳遞其指標,或是從全域 static
變數中擷取 (為了簡化,我採用後者)。結果雖然較難理解,但繪製的矩形與上一個範例相同:
#include <SDL2/SDL.h>
#include <stdio.h>
#ifdef __EMSCRIPTEN__
#include <emscripten.h>
#endif
SDL_Window *window;
SDL_Renderer *renderer;
bool handle_events() {
SDL_Event event;
SDL_PollEvent(&event);
if (event.type == SDL_QUIT) {
return false;
}
return true;
}
void run_main_loop() {
#ifdef __EMSCRIPTEN__
emscripten_set_main_loop([]() { handle_events(); }, 0, true);
#else
while (handle_events())
;
#endif
}
int main() {
SDL_Init(SDL_INIT_VIDEO);
SDL_CreateWindowAndRenderer(300, 300, 0, &window, &renderer);
SDL_SetRenderDrawColor(renderer, /* RGBA: green */ 0x00, 0x80, 0x00, 0xFF);
SDL_Rect rect = {.x = 10, .y = 10, .w = 150, .h = 100};
SDL_RenderFillRect(renderer, &rect);
SDL_RenderPresent(renderer);
run_main_loop();
SDL_DestroyRenderer(renderer);
SDL_DestroyWindow(window);
SDL_Quit();
}
由於所有控制流程變更都是手動完成,並反映在原始程式碼中,因此您可以再次編譯,而無須再使用 Asyncify 功能:
emcc example.cpp -o example.html -s USE_SDL=2
這個範例看似無用,因為其運作方式與第一個版本沒有差別,因為程式碼簡化了在畫布上繪製矩形的情況,而且依然會在網頁上忽略 handle_events
函式中只處理的 SDL_QUIT
事件。
不過,如要妥善整合事件迴圈,無論是透過 Asyncify 或 emscripten_set_main_loop
來加入,如果您決定加入任何類型的動畫或互動元素,都需要付費。
處理使用者互動
舉例來說,只要在最後一個範例中做出幾項變更,即可讓矩形配合鍵盤事件移動:
#include <SDL2/SDL.h>
#ifdef __EMSCRIPTEN__
#include <emscripten.h>
#endif
SDL_Window *window;
SDL_Renderer *renderer;
SDL_Rect rect = {.x = 10, .y = 10, .w = 150, .h = 100};
void redraw() {
SDL_SetRenderDrawColor(renderer, /* RGBA: black */ 0x00, 0x00, 0x00, 0xFF);
SDL_RenderClear(renderer);
SDL_SetRenderDrawColor(renderer, /* RGBA: green */ 0x00, 0x80, 0x00, 0xFF);
SDL_RenderFillRect(renderer, &rect);
SDL_RenderPresent(renderer);
}
uint32_t ticksForNextKeyDown = 0;
bool handle_events() {
SDL_Event event;
SDL_PollEvent(&event);
if (event.type == SDL_QUIT) {
return false;
}
if (event.type == SDL_KEYDOWN) {
uint32_t ticksNow = SDL_GetTicks();
if (SDL_TICKS_PASSED(ticksNow, ticksForNextKeyDown)) {
// Throttle keydown events for 10ms.
ticksForNextKeyDown = ticksNow + 10;
switch (event.key.keysym.sym) {
case SDLK_UP:
rect.y -= 1;
break;
case SDLK_DOWN:
rect.y += 1;
break;
case SDLK_RIGHT:
rect.x += 1;
break;
case SDLK_LEFT:
rect.x -= 1;
break;
}
redraw();
}
}
return true;
}
void run_main_loop() {
#ifdef __EMSCRIPTEN__
emscripten_set_main_loop([]() { handle_events(); }, 0, true);
#else
while (handle_events())
;
#endif
}
int main() {
SDL_Init(SDL_INIT_VIDEO);
SDL_CreateWindowAndRenderer(300, 300, 0, &window, &renderer);
redraw();
run_main_loop();
SDL_DestroyRenderer(renderer);
SDL_DestroyWindow(window);
SDL_Quit();
}
使用 SDL2_gfx 繪製其他形狀
SDL2 可在單一 API 中去除跨平台差異和不同類型的媒體裝置,但仍然是一個相當低階的程式庫。特別是圖形,雖然它提供用於繪製點、線和矩形的 API,但實作任何更複雜的形狀和轉換,則由使用者自行決定。
SDL2_gfx 是會填補該缺口的獨立程式庫。例如,可用來將上述範例中的矩形替換成圓形:
#include <SDL2/SDL.h>
#include <SDL2/SDL2_gfxPrimitives.h>
#ifdef __EMSCRIPTEN__
#include <emscripten.h>
#endif
SDL_Window *window;
SDL_Renderer *renderer;
SDL_Point center = {.x = 100, .y = 100};
const int radius = 100;
void redraw() {
SDL_SetRenderDrawColor(renderer, /* RGBA: black */ 0x00, 0x00, 0x00, 0xFF);
SDL_RenderClear(renderer);
filledCircleRGBA(renderer, center.x, center.y, radius,
/* RGBA: green */ 0x00, 0x80, 0x00, 0xFF);
SDL_RenderPresent(renderer);
}
uint32_t ticksForNextKeyDown = 0;
bool handle_events() {
SDL_Event event;
SDL_PollEvent(&event);
if (event.type == SDL_QUIT) {
return false;
}
if (event.type == SDL_KEYDOWN) {
uint32_t ticksNow = SDL_GetTicks();
if (SDL_TICKS_PASSED(ticksNow, ticksForNextKeyDown)) {
// Throttle keydown events for 10ms.
ticksForNextKeyDown = ticksNow + 10;
switch (event.key.keysym.sym) {
case SDLK_UP:
center.y -= 1;
break;
case SDLK_DOWN:
center.y += 1;
break;
case SDLK_RIGHT:
center.x += 1;
break;
case SDLK_LEFT:
center.x -= 1;
break;
}
redraw();
}
}
return true;
}
void run_main_loop() {
#ifdef __EMSCRIPTEN__
emscripten_set_main_loop([]() { handle_events(); }, 0, true);
#else
while (handle_events())
;
#endif
}
int main() {
SDL_Init(SDL_INIT_VIDEO);
SDL_CreateWindowAndRenderer(300, 300, 0, &window, &renderer);
redraw();
run_main_loop();
SDL_DestroyRenderer(renderer);
SDL_DestroyWindow(window);
SDL_Quit();
}
現在,您必須將 SDL2_gfx 程式庫連結至應用程式。這項作業的執行方式與 SDL2 類似:
# Native version
$ clang example.cpp -o example -lSDL2 -lSDL2_gfx
# Web version
$ emcc --bind foo.cpp -o foo.html -s USE_SDL=2 -s USE_SDL_GFX=2
以下是在 Linux 上執行的結果:
使用網頁版時:
如需更多圖形基本功能,請參閱自動產生的文件。