emscripten.h

本頁記錄 emscripten.h 提供的公開 C++ API。

Emscripten 盡可能使用現有/熟悉的 API（例如：SDL）。此 API 提供 C++ 支援，適用於 JavaScript 或瀏覽器環境的特定功能，或沒有現有 API 的功能。

內聯組合/JavaScript

下列 API 的指南材料可在從 C/C++ 呼叫 JavaScript中找到。

定義

EM_JS(return_type, function_name, arguments, code)

JavaScript 程式庫函式的便利語法。

這可讓您在 C 程式碼中將 JavaScript 宣告為函式，可以像一般的 C 函式一樣呼叫。例如，如果使用 Emscripten 編譯下列 C 程式，並在瀏覽器中執行，則會顯示兩個警示

EM_JS(void, two_alerts, (), {
  alert('hai');
  alert('bai');
});

int main() {
  two_alerts();
  return 0;
}

引數可以作為正常的 C 引數傳遞，並在 JavaScript 程式碼中具有相同的名稱。這些引數可以是 int32_t 或 double 類型。

EM_JS(void, take_args, (int x, float y), {
  console.log('I received: ' + [x, y]);
});

int main() {
  take_args(100, 35.5);
  return 0;
}

也可以將以 null 結尾的 C 字串傳遞到 EM_JS 函式，但是若要操作它們，需要從堆積中複製出來，以轉換為高階 JavaScript 字串。

EM_JS(void, say_hello, (const char* str), {
  console.log('hello ' + UTF8ToString(str));
}

同樣地，任何類型的指標（包括 void *）都可以在 EM_JS 程式碼內傳遞，它們會像上面的 char * 指標一樣顯示為整數。可以透過直接讀取堆積來管理資料的存取。

EM_JS(void, read_data, (int* data), {
  console.log('Data: ' + HEAP32[data>>2] + ', ' + HEAP32[(data+4)>>2]);
});

int main() {
  int arr[2] = { 30, 45 };
  read_data(arr);
  return 0;
}

此外，EM_JS 函式可以將值傳回 C 程式碼。輸出值會使用 return 陳述式傳回

EM_JS(int, add_forty_two, (int n), {
  return n + 42;
});

EM_JS(int, get_memory_size, (), {
  return HEAP8.length;
});

int main() {
  int x = add_forty_two(100);
  int y = get_memory_size();
  // ...
}

字串可以從 JavaScript 傳回 C，但是需要小心處理記憶體管理。

EM_JS(char*, get_unicode_str, (), {
  var jsString = 'Hello with some exotic Unicode characters: Tässä on yksi lumiukko: ☃, ole hyvä.';
  // 'jsString.length' would return the length of the string as UTF-16
  // units, but Emscripten C strings operate as UTF-8.
  return stringToNewUTF8(jsString);
});

int main() {
  char* str = get_unicode_str();
  printf("UTF8 string says: %s\n", str);
  // Each call to _malloc() must be paired with free(), or heap memory will leak!
  free(str);
  return 0;
}
EM_ASM(...)

內聯組合/JavaScript 的便利語法。

這可讓您在 C 程式碼中「內聯」宣告 JavaScript，然後在瀏覽器中執行編譯後的程式碼時執行。例如，如果使用 Emscripten 編譯下列 C 程式碼，並在瀏覽器中執行，則會顯示兩個警示

EM_ASM(alert('hai'); alert('bai'));

引數可以在 JavaScript 程式碼區塊內傳遞，它們會以變數 $0、$1 等的形式抵達。這些引數可以是 int32_t 或 double 類型。

EM_ASM({
  console.log('I received: ' + [$0, $1]);
}, 100, 35.5);

請注意 { 和 }。

也可以將以 null 結尾的 C 字串傳遞到 EM_ASM 區塊，但是若要操作它們，需要從堆積中複製出來，以轉換為高階 JavaScript 字串。

EM_ASM(console.log('hello ' + UTF8ToString($0)), "world!");

同樣地，任何類型的指標（包括 void *）都可以在 EM_ASM 程式碼內傳遞，它們會像上面的 char * 指標一樣顯示為整數。可以透過直接讀取堆積來管理資料的存取。

int arr[2] = { 30, 45 };
EM_ASM({
  console.log('Data: ' + HEAP32[$0>>2] + ', ' + HEAP32[($0+4)>>2]);
}, arr);

注意

  • 從 Emscripten 1.30.4 開始，EM_ASM 程式碼區塊的內容會顯示在一般的 JS 檔案內，因此，Closure 編譯器和其他 JavaScript 縮小工具可以對其進行操作。您可能需要在某些地方使用安全引號（a['b'] 而不是 a.b）以避免發生縮小。

  • C 前置處理器不了解 JavaScript 符號，因此，如果 code 區塊包含逗號字元 ,，則可能需要將程式碼區塊包裝在括號內。例如，程式碼 EM_ASM(return [1,2,3].length); 將無法編譯，但 EM_ASM((return [1,2,3].length)); 可以。

EM_ASM_INT(code, ...)

此巨集以及 EM_ASM_DOUBLE 和 EM_ASM_PTR 的行為類似於 EM_ASM，但是除此之外，它們也會將值傳回 C 程式碼。輸出值會使用 return 陳述式傳回

int x = EM_ASM_INT({
  return $0 + 42;
}, 100);

int y = EM_ASM_INT(return HEAP8.length);
EM_ASM_PTR(code, ...)

與 EM_ASM_INT 類似，但適用於指標大小的回傳值。使用 -sMEMORY64 建置時，這會產生 i64 回傳值，否則會產生 i32 回傳值。

字串可以從 JavaScript 傳回 C，但是需要小心處理記憶體管理。

char *str = (char*)EM_ASM_PTR({
  var jsString = 'Hello with some exotic Unicode characters: Tässä on yksi lumiukko: ☃, ole hyvä.';
  var lengthBytes = lengthBytesUTF8(jsString)+1;
  // 'jsString.length' would return the length of the string as UTF-16
  // units, but Emscripten C strings operate as UTF-8.
  return stringToNewUTF8(jsString);
});
printf("UTF8 string says: %s\n", str);
free(str); // Each call to _malloc() must be paired with free(), or heap memory will leak!
EM_ASM_DOUBLE(code, ...)

與 EM_ASM_INT 類似，但適用於 double 回傳值。

MAIN_THREAD_EM_ASM(code, ...)

其行為類似於 EM_ASM，但是在主要執行緒上執行呼叫。這在 pthreads 建置中很有用，當您想要從 pthread 與 DOM 互動時；這基本上會為您代理呼叫。

此呼叫會以同步方式代理到主要執行緒，也就是說，執行會在主要執行緒完成執行 JS 之後繼續。同步代理也讓傳回值成為可能，請參閱接下來的兩個變體。

MAIN_THREAD_EM_ASM_INT(code, ...)

與 MAIN_THREAD_EM_ASM 類似，但會傳回 int 值。

MAIN_THREAD_EM_ASM_DOUBLE(code, ...)

與 MAIN_THREAD_EM_ASM 類似，但會傳回 double 值。

MAIN_THREAD_EM_ASM_PTR(code, ...)

與 MAIN_THREAD_EM_ASM 類似，但會傳回指標值。

MAIN_THREAD_ASYNC_EM_ASM(code, ...)

與 MAIN_THREAD_EM_ASM 類似，但是以非同步方式代理，也就是說，主要執行緒會收到執行程式碼的請求，並在可以時執行；工作程式不會等待。 （請注意，如果是在主要執行緒上呼叫，則沒有任何要代理的項目，並且會立即同步執行 JS。）

從 C/C++ 呼叫 JavaScript

下列 API 的指南材料可在從 C/C++ 呼叫 JavaScript中找到。

回呼的函式指標類型

以下類型用於定義此檔案中多個函數使用的函數回呼簽名。

em_callback_func

用於無參數回呼的通用函數指標類型。

定義為

typedef void (*em_callback_func)(void)
em_arg_callback_func

用於具有單個 void* 參數的回呼的通用函數指標類型。

此類型用於定義需要傳遞任意資料的函數回呼。例如，emscripten_set_main_loop_arg() 設定使用者定義的資料，並在完成時將其傳遞給此類型的回呼。

定義為

typedef void (*em_arg_callback_func)(void*)
em_str_callback_func

用於具有 C 字串 (const char *) 參數的回呼的通用函數指標類型。

此類型用於需要傳遞 C 字串的函數回呼。例如，它用於 emscripten_async_wget() 中，以傳遞已非同步載入的檔案名稱。

定義為

typedef void (*em_str_callback_func)(const char *)

函數

void emscripten_run_script(const char *script)

與底層 JavaScript 引擎的介面。此函數將 eval() 給定的腳本。注意：如果設定了 -sDYNAMIC_EXECUTION=0，則此函數將不可用。

此函數可以從 pthread 呼叫，並且它會在託管 pthread 的 Web Worker 的範圍內執行。若要在主要執行緒的範圍內評估函數，請參閱函數 emscripten_sync_run_in_main_runtime_thread()。

參數

  • script (const char*) – 要評估的腳本。

返回類型

void

int emscripten_run_script_int(const char *script)

與底層 JavaScript 引擎的介面。此函數將 eval() 給定的腳本。注意：如果設定了 -sDYNAMIC_EXECUTION=0，則此函數將不可用。

此函數可以從 pthread 呼叫，並且它會在託管 pthread 的 Web Worker 的範圍內執行。若要在主要執行緒的範圍內評估函數，請參閱函數 emscripten_sync_run_in_main_runtime_thread()。

參數

  • script (const char*) – 要評估的腳本。

返回

評估的結果，為整數。

返回類型

int

char *emscripten_run_script_string(const char *script)

與底層 JavaScript 引擎的介面。此函數將 eval() 給定的腳本。請注意，此多載在呼叫之間使用單個共用緩衝區。注意：如果設定了 -sDYNAMIC_EXECUTION=0，則此函數將不可用。

此函數可以從 pthread 呼叫，並且它會在託管 pthread 的 Web Worker 的範圍內執行。若要在主要執行緒的範圍內評估函數，請參閱函數 emscripten_sync_run_in_main_runtime_thread()。

參數

  • script (const char*) – 要評估的腳本。

返回

評估的結果，為字串。

返回類型

char*

void emscripten_async_run_script(const char *script, int millis)

在指定的時間量後，非同步執行腳本。

此函數可以從 pthread 呼叫，並且它會在託管 pthread 的 Web Worker 的範圍內執行。若要在主要執行緒的範圍內評估函數，請參閱函數 emscripten_sync_run_in_main_runtime_thread()。

參數

  • script (const char*) – 要評估的腳本。

  • millis (int) – 腳本執行前的時間量，以毫秒為單位。

返回類型

void

void emscripten_async_load_script(const char *script, em_callback_func onload, em_callback_func onerror)

從 URL 非同步載入腳本。

這與執行相依性系統整合，因此您的腳本可以多次呼叫 addRunDependency，準備各種非同步任務，並對它們呼叫 removeRunDependency；當所有任務完成時（或如果一開始沒有執行相依性），將呼叫 onload。這種用法的一個範例是載入資產模組，即檔案封裝器的輸出。

此函數目前僅在主要瀏覽器執行緒中可用，並且如果在 pthread 中呼叫，它會立即失敗並呼叫提供的 onerror() 處理常式。

參數

  • script (const char*) – 要評估的腳本。

  • onload (em_callback_func) – 當腳本完全載入時執行的回呼函數，不帶參數。

  • onerror (em_callback_func) – 如果載入時發生錯誤，則執行的回呼函數，不帶參數。

返回類型

void

瀏覽器執行環境

以下 API 的指南資料可以在 Emscripten 執行環境 中找到。

函數

void emscripten_set_main_loop(em_callback_func func, int fps, bool simulate_infinite_loop)

將 C 函數設定為呼叫執行緒的主要事件迴圈。

如果主要迴圈函數需要接收使用者定義的資料，請改用 emscripten_set_main_loop_arg()。

JavaScript 環境會以指定的每秒幀數呼叫該函數。如果在主要瀏覽器執行緒上呼叫，將 fps 設定為 0 或負值將使用瀏覽器的 requestAnimationFrame 機制來呼叫主要迴圈函數。如果您要進行渲染，則**強烈**建議使用此方法，因為瀏覽器的 requestAnimationFrame 將確保您以適當的平滑速率進行渲染，該速率與瀏覽器和顯示器正確對齊。如果您的應用程式中根本不進行渲染，則應為您的程式碼選擇有意義的特定幀速率。

如果 simulate_infinite_loop 為 true，則該函數會擲出例外狀況，以停止呼叫者的執行。這將導致進入主要迴圈，而不是執行呼叫 emscripten_set_main_loop() 後面的程式碼，這是我們最接近模擬無限迴圈的方法（我們在 glutMainLoop 中執行類似的操作）。如果此參數為 false，則行為與此參數新增至 API 之前相同，即執行會正常繼續。請注意，在這兩種情況下，我們都不會執行全域解構子、atexit 等，因為我們知道主要迴圈仍會執行，但如果我們不模擬無限迴圈，則堆疊將會解除。這表示如果 simulate_infinite_loop 為 false，而且您在堆疊上建立了物件，則會在第一次呼叫主要迴圈之前將其清除。

可以在 pthread 中呼叫此函數，在這種情況下，回呼迴圈會設定為在呼叫執行緒的內容中呼叫。為了讓迴圈運作，呼叫執行緒必須透過從其 pthread 主要函數退出來定期「返回」到瀏覽器，因為只有在呼叫執行緒未執行任何其他程式碼時，才能執行回呼。這表示同步封鎖主要迴圈與 emscripten_set_main_loop() 函數不相容。

由於 requestAnimationFrame() API 在 Web Worker 中不可用，當在 pthread 中呼叫 emscripten_set_main_loop() 且 fps <= 0 時，會模擬與顯示器的重新整理速率同步的效果，而且通常不會與垂直同步間隔精確對齊。

提示

每個執行緒一次只能有一個主要迴圈函數。若要變更主要迴圈函數，請先 取消目前的迴圈，然後呼叫此函數以設定另一個迴圈。

注意

請參閱 emscripten_set_main_loop_expected_blockers()、emscripten_pause_main_loop()、emscripten_resume_main_loop() 和 emscripten_cancel_main_loop()，以取得有關封鎖、暫停和恢復呼叫執行緒的主要迴圈的資訊。

注意

呼叫此函數會覆寫呼叫執行緒中任何先前呼叫 emscripten_set_main_loop_timing() 的效果，方法是套用參數 fps 指定的計時模式。若要為目前的執行緒指定不同的計時模式，請在設定主要迴圈後呼叫函數 emscripten_set_main_loop_timing()。

注意

目前，同時使用 新的 Wasm 例外狀況處理和 simulate_infinite_loop == true 尚未在 C++ 專案中運作，這些專案在呼叫時堆疊上有具有解構子的物件。

參數

  • func (em_callback_func) – 要設定為呼叫執行緒的主要事件迴圈的 C 函數。

  • fps (int) – JavaScript 呼叫函數的每秒幀數。設定 int <=0（建議）會使用瀏覽器的 requestAnimationFrame 機制來呼叫函數。

  • simulate_infinite_loop (bool) – 如果為 true，則此函數會擲出例外狀況，以停止呼叫者的執行。

void emscripten_set_main_loop_arg(em_arg_callback_func func, void *arg, int fps, bool simulate_infinite_loop)

將 C 函數設定為呼叫執行緒的主要事件迴圈，並將使用者定義的資料傳遞給它。

另請參閱

emscripten_set_main_loop() 中的資訊也適用於此函數。

參數

  • func (em_arg_callback_func) – 作為主要事件迴圈設定的 C 函式。函式簽章必須有一個 void* 參數，用於傳遞 arg 值。

  • arg (void*) – 傳遞給主迴圈函式的使用者定義資料，API 本身不會修改此資料。

  • fps (int) – JavaScript 呼叫此函式的每秒影格數。設定 int <=0 （建議使用）會使用瀏覽器的 requestAnimationFrame 機制來呼叫函式。

  • simulate_infinite_loop (bool) – 如果為 true，則此函數會擲出例外狀況，以停止呼叫者的執行。

void emscripten_push_main_loop_blocker(em_arg_callback_func func, void *arg)
void emscripten_push_uncounted_main_loop_blocker(em_arg_callback_func func, void *arg)

新增一個會阻塞呼叫執行緒的主要迴圈的函式。

此函式會新增到要被阻塞的事件佇列末端；主迴圈將不會執行，直到佇列中的所有阻塞器都完成。

在「已計數」版本中，阻塞器會被計數（內部），並且會使用一些文字呼叫 Module.setStatus 來報告進度（setStatus 是一個程式可以定義的通用掛鉤，以便顯示處理更新）。

注意

  • 主迴圈阻塞器會阻止主迴圈執行，並且可以計數以顯示進度。相反地，emscripten_async_calls 不會被計數，不會阻塞主迴圈，並且可以在未來特定時間觸發。

參數

  • func (em_arg_callback_func) – 主迴圈阻塞器函式。函式簽章必須有一個 void* 參數，用於傳遞 arg 值。

  • arg (void*) – 要傳遞給阻塞器函式的使用者定義引數。

返回類型

void

void emscripten_pause_main_loop(void)
void emscripten_resume_main_loop(void)

暫停和恢復呼叫執行緒的主要迴圈。

如果您的應用程式需要執行某些同步操作，例如從網路載入檔案，則暫停和恢復主迴圈很有用。在該操作完成之前執行主迴圈可能是錯誤的（原始程式碼假設如此），因此您可以將程式碼分成非同步回呼，但是您必須暫停主迴圈，直到它們完成。

注意

這些是相當底層的函式。 emscripten_push_main_loop_blocker() （以及相關的函式）提供了更方便的替代方案。

void emscripten_cancel_main_loop(void)

取消呼叫執行緒的主要事件迴圈。

另請參閱 emscripten_set_main_loop() 和 emscripten_set_main_loop_arg()，以取得有關設定和使用主迴圈的資訊。

注意

此函式會取消主迴圈，這表示它將不再被呼叫。控制流程不會發生其他變更。特別是，如果您使用 simulate_infinite_loop 選項啟動主迴圈，您仍然可以取消主迴圈，但是執行將不會在設定主迴圈後的程式碼中繼續執行（我們實際上不會在那裡執行無限迴圈 - 這在 JavaScript 中是不可能的，因此為了模擬無限迴圈，我們會在該階段暫停執行，然後接下來執行的就是主迴圈本身，因此看起來好像無限迴圈已經開始了；取消主迴圈有點打破了這個隱喻）。

int emscripten_set_main_loop_timing(int mode, int value)

指定呼叫執行緒的主迴圈滴答函式將使用的排程模式。

此函式可以用於互動式控制 Emscripten 執行階段驅動透過呼叫 emscripten_set_main_loop() 所指定的主迴圈的速率。在原生開發中，這對應於 3D 渲染的「交換間隔」或「顯示間隔」。此函式指定的新滴答間隔會立即對現有的主迴圈生效，而且必須在透過 emscripten_set_main_loop() 設定主迴圈後才呼叫此函式。

param int mode

要使用的計時模式。允許的值為 EM_TIMING_SETTIMEOUT、EM_TIMING_RAF 和 EM_TIMING_SETIMMEDIATE。

參數

  • value (int) –

    要為主迴圈啟用的計時值。此值的解讀方式根據 mode 參數而有所不同

    • 如果 mode 為 EM_TIMING_SETTIMEOUT，則 value 會指定主迴圈的後續滴答之間要等待的毫秒數，並且更新的發生與顯示器的垂直同步速率（垂直同步關閉）無關。此方法使用 JavaScript setTimeout 函式來驅動動畫。

    • 如果 mode 為 EM_TIMING_RAF，則會使用 requestAnimationFrame 函式（啟用垂直同步）執行更新，並且此值會被解讀為主迴圈的「交換間隔」速率。1 的值指定執行階段應該在每次垂直同步時渲染（通常為 60fps），而 2 的值表示主迴圈回呼應該僅在每次第二次垂直同步時呼叫（30fps）。作為一般公式，值 n 表示主迴圈會在每次第 n 次垂直同步時更新，或者對於 60Hz 顯示器，速率為 60/n，對於 120Hz 顯示器，速率為 120/n。

    • 如果 mode 為 EM_TIMING_SETIMMEDIATE，則會使用 setImmediate 函式執行更新，如果無法使用，則會透過 postMessage 模擬。有關更多資訊，請參閱 MDN 上的 setImmediate <https://developer.mozilla.org/en-US/docs/Web/API/Window/setImmediate>。請注意，當將 Emscripten 輸出部署到網路時，強烈不建議使用此模式，因為它依賴於處於草稿狀態的不穩定 Web 擴充功能，除了 IE 以外的瀏覽器目前都不支援它，並且它的實作在審查中被認為是有爭議的。

返回類型

int

返回

成功時傳回值 0，失敗時傳回非零值。如果在此函式呼叫之前沒有活動的主迴圈，則會發生失敗。

注意

瀏覽器會針對使用 requestAnimationFrame 來進行動畫而非其他提供的模式進行大量最佳化。因此，為了在瀏覽器之間獲得最佳體驗，使用 mode=EM_TIMING_RAF 和 value=1 呼叫此函式會產生最佳結果。已知使用 JavaScript setTimeout 函式會導致跳幀和比使用 requestAnimationFrame 函式更差的體驗。

注意

setTimeout 和 requestAnimationFrame 之間存在功能上的差異：如果使用者最小化瀏覽器視窗或隱藏您的應用程式索引標籤，瀏覽器通常會停止呼叫 requestAnimationFrame 回呼，但是基於 setTimeout 的主迴圈將會繼續執行，儘管間隔會大幅縮減。有關更多資訊，請參閱 MDN 上的 setTimeout <https://developer.mozilla.org/en-US/docs/Web/API/WindowTimers.setTimeout#Inactive_tabs>。

void emscripten_get_main_loop_timing(int *mode, int *value)

傳回目前生效的主迴圈計時模式。如需值的解讀，請參閱函式 emscripten_set_main_loop_timing() 的文件。計時模式由呼叫函式 emscripten_set_main_loop_timing() 和 emscripten_set_main_loop() 控制。

param mode

如果不是 null，則會在此處傳回使用的計時模式。

type mode

int*

param value

如果不是 null，則會在此處傳回使用的計時值。

type value

int*

void emscripten_set_main_loop_expected_blockers(int num)

設定即將推送的阻塞器數量。

此數量用於報告一組阻塞器的相對進度，之後主迴圈將繼續。

舉例來說，一個遊戲可能需要在開始新關卡前執行 10 個阻擋器。操作會先將此值設定為「10」，然後推送這 10 個阻擋器。當第 3 個阻擋器（假設）完成時，進度會顯示為 3/10。

參數

  • num (整數) – 即將推送的阻擋器數量。

void emscripten_async_call(em_arg_callback_func func, void *arg, int millis)

非同步呼叫 C 函數，也就是在將控制權返回給 JavaScript 事件迴圈之後。

這是透過 setTimeout 完成的。

在原生建置時，這會變成簡單的直接呼叫，在 SDL_Delay 之後（您必須包含 SDL.h）。

如果 millis 為負值，則會使用瀏覽器的 requestAnimationFrame 機制。（請注意，0 表示仍使用 setTimeout，這基本上表示「盡快非同步執行」。）

參數

  • func (em_arg_callback_func) – 要非同步呼叫的 C 函數。函數簽名必須具有 void* 參數，用於傳遞 arg 值。

  • arg (void*) – 要傳遞給 C 函數的使用者定義引數。

  • millis (整數) – 呼叫函數前的逾時時間。

void emscripten_exit_with_live_runtime(void)

停止目前的執行緒，但保持執行階段存活，以便您稍後繼續執行程式碼（因此不會執行全域解構子等）。請注意，當您執行非同步操作（例如 emscripten_async_call()）時，執行階段會自動保持存活，因此您不需要在這些情況下呼叫此函數。

在多執行緒應用程式中，這只會結束目前的執行緒（並允許稍後在執行它的 Web Worker 中執行程式碼）。

void emscripten_force_exit(int status)

關閉執行階段並結束（終止）程式，就像您呼叫 exit() 一樣。

不同之處在於，即使您先前呼叫了 emscripten_exit_with_live_runtime() 或以其他方式保持執行階段存活，emscripten_force_exit 也會關閉執行階段。換句話說，此方法可讓您在執行階段保持存活，超過 main() 完成後完全關閉執行階段。

請注意，如果未設定 EXIT_RUNTIME（預設情況下是這樣），則無法關閉執行階段，因為我們不包含執行此操作的程式碼。如果您想要能夠退出執行階段，請使用 -sEXIT_RUNTIME 進行建置。

參數

  • status (整數) – 與 libc 函數 exit() 相同。

double emscripten_get_device_pixel_ratio(void)

傳回 window.devicePixelRatio 的值。

返回類型

double

返回

像素比例，如果不支持則為 1.0。

char *emscripten_get_window_title()

傳回視窗標題。

傳回的字串在下次呼叫函數之前都是有效的

void emscripten_set_window_title(char *title)

設定視窗標題。

void emscripten_get_screen_size(int *width, int *height)

傳回螢幕的寬度和高度。

void emscripten_hide_mouse(void)

隱藏畫布上的 OS 滑鼠游標。

請注意，SDL 的 SDL_ShowCursor 命令會顯示和隱藏 SDL 游標，而不是 OS 游標。如果您的應用程式繪製自己的游標，此命令對於隱藏 OS 游標很有用。

double emscripten_get_now(void)

傳回瀏覽器提供的目前時間的最高精確度表示法。

這會使用 Date.now 或 performance.now。結果不是絕對時間，僅與此函數的其他呼叫進行比較才有意義。

返回類型

double

返回

目前時間，以毫秒 (ms) 為單位。

float emscripten_random(void)

產生 0-1 範圍內的隨機數。這會對應到 Math.random()。

返回類型

float

返回

隨機數。

非同步檔案系統 API

類型定義

em_async_wget_onload_func

emscripten_async_wget_data() 的 onload 回呼的函數指標類型（該方法中記錄的參數特定值）。

定義為

typedef void (*em_async_wget_onload_func)(void*, void*, int)
em_async_wget2_onload_func

emscripten_async_wget2() 的 onload 回呼的函數指標類型（該方法中記錄的參數特定值）。

定義為

typedef void (*em_async_wget2_onload_func)(void*, const char*)
em_async_wget2_onstatus_func

emscripten_async_wget2() 的 onerror 和 onprogress 回呼的函數指標類型（該方法中記錄的參數特定值）。

定義為

typedef void (*em_async_wget2_onstatus_func)(void*, int)
em_async_wget2_data_onload_func

emscripten_async_wget2_data() 的 onload 回呼的函數指標類型（該方法中記錄的參數特定值）。

定義為

typedef void (*em_async_wget2_data_onload_func)(unsigned, void*, void *, unsigned)
em_async_wget2_data_onerror_func

emscripten_async_wget2_data() 的 onerror 回呼的函數指標類型（該方法中記錄的參數特定值）。

定義為

typedef void (*em_async_wget2_data_onerror_func)(unsigned, void*, int, const char*)
em_async_wget2_data_onprogress_func

emscripten_async_wget2_data() 的 onprogress 回呼的函數指標類型（該方法中記錄的參數特定值）。

定義為

typedef void (*em_async_wget2_data_onprogress_func)(unsigned, void*, int, int)
em_run_preload_plugins_data_onload_func

emscripten_run_preload_plugins_data() 的 onload 回呼的函數指標類型（該方法中記錄的參數特定值）。

定義為

typedef void (*em_run_preload_plugins_data_onload_func)(void*, const char*)

函數

void emscripten_async_wget(const char* url, const char* file, em_str_callback_func onload, em_str_callback_func onerror)

從 URL 非同步載入檔案。

除了從網路擷取 URL 之外，還會執行預載外掛程式，以便資料可在 IMG_Load 等中使用（我們會非同步執行工作，以使瀏覽器解碼影像或音訊等）。如需有關預載檔案的詳細資訊，請參閱 預載檔案。

當檔案準備就緒時，將會呼叫 onload 回呼。如果發生任何錯誤，則會呼叫 onerror。回呼會使用檔案作為其引數進行呼叫。

參數

  • char* url (const) – 要載入的 URL。

  • char* file (const) – 從 URL 建立和載入的檔案名稱。如果檔案已存在，則會覆寫。如果檔案的目的地目錄在檔案系統上不存在，則會建立。可以傳遞相對路徑名稱，它將相對於呼叫此函數時的目前工作目錄進行解譯。

  • onload (em_str_callback_func) –

    檔案成功載入時的回呼。回呼函數參數值為

    • (const char)* : 從 URL 載入的 file 名稱。

  • onerror (em_str_callback_func) –

    發生失敗事件時的回呼。回呼函數參數值為

    • (const char)* : 無法從 URL 載入的 file 名稱。

void emscripten_async_wget_data(const char* url, void *arg, em_async_wget_onload_func onload, em_arg_callback_func onerror)

從 URL 異步載入緩衝區。

這是 emscripten_async_wget() 的「資料」版本。

此函式不是寫入檔案，而是直接寫入記憶體中的緩衝區。這避免了使用模擬檔案系統的額外開銷；但請注意，由於不使用檔案，它無法執行預載外掛程式來為 IMG_Load 等設定 (IMG_Load 等在檔案上運作)。

當檔案準備好時，將會呼叫 onload 回呼函數。如果發生任何錯誤，將會呼叫 onerror。

參數

  • url (const char*) – 要載入的檔案的 URL。

  • arg (void*) – 使用者定義的資料，會傳遞給回呼函數，而 API 本身不會修改此資料。回呼函數可以使用此資料來識別相關的呼叫。

  • onload (em_async_wget_onload_func) –

    成功將 URL 載入緩衝區時的回呼函數。回呼函數參數值如下：

    • (void)*：等於 arg (使用者定義的資料)。

    • (void)*：指向包含資料的緩衝區的指標。請注意，與 worker API 一樣，資料緩衝區僅在回呼期間存在；必須在該時間內使用或複製它。

    • (int)：緩衝區的大小，以位元組為單位。

  • onerror (em_arg_callback_func) –

    發生錯誤時的回呼函數。回呼函數參數值如下：

    • (void)*：等於 arg (使用者定義的資料)。

int emscripten_async_wget2(const char* url, const char* file, const char* requesttype, const char* param, void *arg, em_async_wget2_onload_func onload, em_async_wget2_onstatus_func onerror, em_async_wget2_onstatus_func onprogress)

從 URL 非同步載入檔案。

這是 emscripten_async_wget() 的 實驗性「功能更完整」版本。

目前不會對下載的資料執行預載外掛程式。如果您希望能夠將下載的檔案與 IMG_Load 等一起使用，您可能需要在 onload 回呼函數中呼叫 emscripten_run_preload_plugins()。

當檔案準備好時，將會呼叫 onload 回呼函數，並提供 arg 和 file 中提供的物件指標。在下載期間，會呼叫 onprogress 回呼函數。

參數

  • url (const char*) – 要載入的檔案的 URL。

  • file (const char*) – 從 URL 建立和載入的檔案名稱。如果檔案已存在，將會覆寫。如果檔案的目的地目錄在檔案系統上不存在，則會建立該目錄。可以傳遞相對路徑名稱，該路徑名稱將根據呼叫此函式時的目前工作目錄進行解譯。

  • requesttype (const char*) – 「GET」或「POST」。

  • param (const char*) – POST 請求的請求參數 (請參閱 requesttype)。參數的指定方式與等效 GET 請求的 URL 相同：例如 key=value&key2=value2。

  • arg (void*) – 使用者定義的資料，會傳遞給回呼函數，而 API 本身不會修改此資料。回呼函數可以使用此資料來識別相關的呼叫。

  • onload (em_async_wget2_onload_func) –

    檔案成功載入時的回呼函數。回呼函數參數值如下：

    • (void)*：等於 arg (使用者定義的資料)。

    • (const char)*：傳遞至原始呼叫的 file。

  • onerror (em_async_wget2_onstatus_func) –

    發生錯誤時的回呼函數。回呼函數參數值如下：

    • (void)*：等於 arg (使用者定義的資料)。

    • (int)：HTTP 狀態碼。

  • onprogress (em_async_wget2_onstatus_func) –

    檔案載入期間的回呼函數。回呼函數參數值如下：

    • (void)*：等於 arg (使用者定義的資料)。

    • (int)：進度 (已完成的百分比)。

返回

請求的控制代碼 (int)，可用於 abort 中斷請求。

int emscripten_async_wget2_data(const char* url, const char* requesttype, const char* param, void *arg, int free, em_async_wget2_data_onload_func onload, em_async_wget2_data_onerror_func onerror, em_async_wget2_data_onprogress_func onprogress)

從 URL 異步載入緩衝區。

這是 emscripten_async_wget2() 的「資料」版本。它是 emscripten_async_wget_data() 的 實驗性「功能更完整」版本。

此函式不是寫入檔案，而是直接寫入記憶體中的緩衝區。這避免了使用模擬檔案系統的額外開銷；但請注意，由於不使用檔案，它無法執行預載外掛程式來為 IMG_Load 等設定 (IMG_Load 等在檔案上運作)。

當檔案準備好時，將會呼叫 onload 回呼函數，並提供 arg 中提供的物件指標、指向記憶體中緩衝區的指標，以及包含緩衝區大小的無符號整數。在下載期間，會呼叫 onprogress 回呼函數，並提供進度資訊。如果發生錯誤，將會呼叫 onerror，並提供 HTTP 狀態碼和包含狀態描述的字串。

參數

  • url (const char*) – 要載入的檔案的 URL。

  • requesttype (const char*) – 「GET」或「POST」。

  • param (const char*) – POST 請求的請求參數 (請參閱 requesttype)。參數的指定方式與等效 GET 請求的 URL 相同：例如 key=value&key2=value2。

  • arg (void*) – 使用者定義的資料，會傳遞給回呼函數，而 API 本身不會修改此資料。回呼函數可以使用此資料來識別相關的呼叫。

  • free (int) – 告知執行階段是否在 onload 完成後釋放傳回的緩衝區。如果為 false，則釋放緩衝區是接收者的責任。

  • onload (em_async_wget2_data_onload_func) –

    檔案成功載入時的回呼函數。回呼函數參數值如下：

    • (unsigned)：請求的控制代碼

    • (void)*：等於 arg (使用者定義的資料)。

    • (void)*：指向記憶體中緩衝區的指標。

    • (unsigned)：緩衝區的大小 (以位元組為單位)。

  • onerror (em_async_wget2_data_onerror_func) –

    發生錯誤時的回呼函數。回呼函數參數值如下：

    • (unsigned)：請求的控制代碼

    • (void)*：等於 arg (使用者定義的資料)。

    • (int)：HTTP 錯誤碼。

    • (const char)*：包含狀態描述的字串。

  • onprogress (em_async_wget2_data_onprogress_func) –

    在檔案載入期間 (定期) 呼叫的回呼函數，以更新進度。回呼函數參數值如下：

    • (unsigned)：請求的控制代碼

    • (void)*：等於 arg (使用者定義的資料)。

    • (int)：已載入的位元組數。

    • (int)：資料的總大小 (以位元組為單位)，如果大小不可用，則為零。

返回

請求的控制代碼 (int)，可用於 abort 中斷請求。

void emscripten_async_wget2_abort(int handle)

中止使用 emscripten_async_wget2() 或 emscripten_async_wget2_data() 引發的非同步請求。

參數

  • handle (int) – 要中止的請求的控制代碼。

void emscripten_run_preload_plugins_data(char* data, int size, const char *suffix, void *arg, em_run_preload_plugins_data_onload_func onload, em_arg_callback_func onerror)

在資料緩衝區上非同步執行預載外掛程式。這是 emscripten_run_preload_plugins() 的「資料」版本，它接收原始資料作為輸入，而不是檔案名稱 (這可以避免首先將資料寫入檔案的需要)。有關預載外掛程式的詳細資訊，請參閱 預載檔案。

當檔案載入時，將會呼叫 onload 回呼函數。如果發生任何錯誤，將會呼叫 onerror。

onload 也會接收第二個參數，這是一個「假的」檔案名稱，您可以將其傳遞到 IMG_Load 中（它不是一個實際的檔案，而是為了讓 IMG_Load 能夠處理此影像而識別它）。請注意，此 API 的使用者有責任 free() 釋放為假的檔案名稱所分配的記憶體。

參數

  • data (char*) – 要處理的資料緩衝區。

  • suffix (const char*) – 檔案後綴，例如「png」或「jpg」。

  • arg (void*) – 使用者定義的資料，會傳遞給回呼函數，而 API 本身不會修改此資料。回呼函數可以使用此資料來識別相關的呼叫。

  • onload (em_run_preload_plugins_data_onload_func) –

    成功處理資料後的回呼函式。回呼函式的參數值為：

    • (void)*：等於 arg (使用者定義的資料)。

    • (const char)*：一個「假的」檔案名稱，您可以將其傳遞到 IMG_Load 中。請參閱上文以取得更多資訊。

  • onerror (em_arg_callback_func) –

    發生失敗事件時的回呼。回呼函數參數值為

    • (void)*：等於 arg (使用者定義的資料)。

void emscripten_dlopen(const char *filename, int flags, void* user_data, em_dlopen_callback onsuccess, em_arg_callback_func onerror);

開始一個非同步的 dlopen 操作，從檔案名稱或 URL 載入共享程式庫。立即返回並要求呼叫者返回事件迴圈。onsuccess 和 onerror 回呼函式用於發出請求成功或失敗的信號。在 onerror 回呼函式中，可以使用一般的 dlerror C 函式取得錯誤詳細資訊。flags 與一般的 dlopen C 函式中使用的相同。

參數

  • char* filename (const) – 要載入的共享程式庫的檔案名稱 (或 URL)。

  • flags (int) – 請參閱 dlopen flags。

  • user_data (void*) – 傳遞給 onsuccess 和 onerror 回呼函式的使用者資料。

  • onsuccess (em_dlopen_callback) – 如果程式庫載入成功，則會呼叫此函式。

  • onerror (em_arg_callback_func) – 如果載入程式庫時發生錯誤，則會呼叫此函式。

非同步 IndexedDB API

IndexedDB 是一種瀏覽器 API，可讓您持久儲存資料，也就是說，您可以將資料儲存在那裡，並在使用者重新造訪網頁時載入它。IDBFS 提供了一種透過 Emscripten 檔案系統層使用 IndexedDB 的方式。emscripten_idb_* 此處列出的方法提供了一個直接連接到 IndexedDB 的替代 API，從而避免了檔案系統層的開銷。

void emscripten_idb_async_load(const char *db_name, const char *file_id, void* arg, em_async_wget_onload_func onload, em_arg_callback_func onerror)

從本機 IndexedDB 儲存空間非同步載入資料。這允許使用持久資料，而不會產生檔案系統層的開銷。

當資料準備就緒時，將呼叫 onload 回呼函式。如果發生任何錯誤，將呼叫 onerror。

參數

  • db_name – 要從中載入的 IndexedDB 資料庫。

  • file_id – 要載入的資料的識別碼。

  • arg (void*) – 使用者定義的資料，會傳遞給回呼函數，而 API 本身不會修改此資料。回呼函數可以使用此資料來識別相關的呼叫。

  • onload (em_async_wget_onload_func) –

    成功將 URL 載入緩衝區時的回呼函數。回呼函數參數值如下：

    • (void)*：等於 arg (使用者定義的資料)。

    • (void)*：指向包含資料的緩衝區的指標。請注意，與 worker API 一樣，資料緩衝區僅在回呼期間存在；必須在該時間內使用或複製它。

    • (int)：緩衝區的大小，以位元組為單位。

  • onerror (em_arg_callback_func) –

    發生錯誤時的回呼函數。回呼函數參數值如下：

    • (void)*：等於 arg (使用者定義的資料)。

void emscripten_idb_async_store(const char *db_name, const char *file_id, void* ptr, int num, void* arg, em_arg_callback_func onstore, em_arg_callback_func onerror);

將資料非同步儲存到本機 IndexedDB 儲存空間。這允許使用持久資料，而不會產生檔案系統層的開銷。

當資料儲存完成時，將呼叫 onstore 回呼函式。如果發生任何錯誤，將呼叫 onerror。

參數

  • db_name – 要從中載入的 IndexedDB 資料庫。

  • file_id – 要載入的資料的識別碼。

  • ptr – 指向要儲存的資料的指標。

  • num – 要儲存的位元組數。

  • arg (void*) – 使用者定義的資料，會傳遞給回呼函數，而 API 本身不會修改此資料。回呼函數可以使用此資料來識別相關的呼叫。

  • onstore (em_arg_callback_func) –

    成功將資料緩衝區儲存到 URL 的回呼函式。回呼函式的參數值為：

    • (void)*：等於 arg (使用者定義的資料)。

  • onerror (em_arg_callback_func) –

    發生錯誤時的回呼函數。回呼函數參數值如下：

    • (void)*：等於 arg (使用者定義的資料)。

void emscripten_idb_async_delete(const char *db_name, const char *file_id, void* arg, em_arg_callback_func ondelete, em_arg_callback_func onerror)

從本機 IndexedDB 儲存空間非同步刪除資料。

當資料刪除完成時，將呼叫 ondelete 回呼函式。如果發生任何錯誤，將呼叫 onerror。

參數

  • db_name – IndexedDB 資料庫。

  • file_id – 資料的識別碼。

  • arg (void*) – 使用者定義的資料，會傳遞給回呼函數，而 API 本身不會修改此資料。回呼函數可以使用此資料來識別相關的呼叫。

  • ondelete (em_arg_callback_func) –

    成功刪除後的回呼函式

    • (void)*：等於 arg (使用者定義的資料)。

  • onerror (em_arg_callback_func) –

    發生錯誤時的回呼函數。回呼函數參數值如下：

    • (void)*：等於 arg (使用者定義的資料)。

void emscripten_idb_async_exists(const char *db_name, const char *file_id, void* arg, em_idb_exists_func oncheck, em_arg_callback_func onerror)

非同步檢查具有特定 ID 的資料是否存在於本機 IndexedDB 儲存空間中。

當資料檢查完成時，將呼叫 oncheck 回呼函式。如果發生任何錯誤，將呼叫 onerror。

參數

  • db_name – IndexedDB 資料庫。

  • file_id – 資料的識別碼。

  • arg (void*) – 使用者定義的資料，會傳遞給回呼函數，而 API 本身不會修改此資料。回呼函數可以使用此資料來識別相關的呼叫。

  • oncheck (em_idb_exists_func) –

    成功檢查後的回呼函式，具有以下參數：

    • (void)*：等於 arg (使用者定義的資料)。

    • int：檔案是否存在。

  • onerror (em_arg_callback_func) –

    發生錯誤時的回呼函數。回呼函數參數值如下：

    • (void)*：等於 arg (使用者定義的資料)。

void emscripten_idb_async_clear(const char *db_name, void* arg, em_arg_callback_func onclear, em_arg_callback_func onerror)

非同步清除本機 IndexedDB 儲存空間中的所有資料。

當儲存空間清除完成時，將呼叫 onclear 回呼函式。如果發生任何錯誤，將呼叫 onerror。

參數

  • db_name – IndexedDB 資料庫。

  • arg (void*) – 使用者定義的資料，會傳遞給回呼函數，而 API 本身不會修改此資料。回呼函數可以使用此資料來識別相關的呼叫。

  • onclear (em_arg_callback_func) –

    成功清除後的回呼函式。回呼函式的參數為：

    • (void)*：等於 arg (使用者定義的資料)。

  • onerror (em_arg_callback_func) –

    發生失敗事件時的回呼函式。回呼函式的參數為：

    • (void)*：等於 arg (使用者定義的資料)。

int emscripten_run_preload_plugins(const char* file, em_str_callback_func onload, em_str_callback_func onerror)

非同步在檔案上執行預載外掛程式。它適用於已存在的檔案資料，並執行任何可作為預載外掛程式的必要非同步操作，例如解碼影像以在 IMG_Load 中使用，或解碼音訊以在 Mix_LoadWAV 中使用。有關預載外掛程式的詳細資訊，請參閱 預載檔案。

操作完成後，將呼叫 onload 回呼函式。如果發生任何錯誤，將呼叫 onerror。回呼函式會使用檔案作為其參數進行呼叫。

參數

  • file (const char*) – 要處理的檔案名稱。

  • onload (em_str_callback_func) –

    成功處理檔案後的回呼函式。回呼函式的參數值為：

    • (const char)*：已處理的 file 名稱。

  • onerror (em_str_callback_func) –

    發生失敗事件時的回呼。回呼函數參數值為

    • (const char)*：操作失敗的 file 名稱。

返回

如果成功則為 0，如果檔案不存在則為 -1

返回類型

int

編譯

EMSCRIPTEN_KEEPALIVE

告知編譯器和連結器保留符號並匯出它，就像您將其新增至 EXPORTED_FUNCTIONS 一樣。

例如

void EMSCRIPTEN_KEEPALIVE my_function() { printf("I am being kept alive\n"); }

請注意，這只有在定義符號的物件檔被連結器以其他方式包含時才有效。如果物件檔是封存的一部分，並且沒有以其他方式被引用，則連結器根本不會包含它，並且物件檔中的任何符號都不會被包含或匯出。解決此限制的一種方法是在封存檔的兩側使用 -Wl,--whole-archive / -Wl,--no-whole-archive 旗標。

Worker API

類型定義

int worker_handle

Web worker 的包裝函式，可讓您建立 worker 並與其通訊。

請注意，目前的 API 主要關注向 worker 發送作業並等待回應的主執行緒，即以不對稱的方式，目前沒有 API 可以在沒有 worker 要求的情況下從 worker 向主執行緒發送訊息。

em_worker_callback_func

來自 emscripten_call_worker() 的回呼函式的函式指標類型 (該方法中記錄的參數的特定值)。

定義為

typedef void (*em_worker_callback_func)(char*, int, void*)

函式

worker_handle emscripten_create_worker(const char * url)

建立一個 worker。

必須將 worker 與主程式分開編譯，並將 BUILD_AS_WORKER 旗標設定為 1。

該 worker 不得使用 -pthread 旗標進行編譯，因為 POSIX 執行緒實作與此 Worker API 不相容。

參數

  • url (const char*) – worker 指令碼的 URL。

返回

新建立的 Worker 的控制代碼。

返回類型

worker_handle

void emscripten_destroy_worker(worker_handle worker)

銷毀一個 Worker。請參閱 emscripten_create_worker()。

參數

  • worker ( worker_handle ) – 要銷毀的 Worker 的控制代碼。

void emscripten_call_worker(worker_handle worker, const char *funcname, char *data, int size, em_worker_callback_func callback, void *arg)

非同步呼叫一個 Worker。

將使用兩個參數呼叫 Worker 函式：一個資料指標和一個大小。由指標和大小定義的資料區塊僅在回呼期間存在：之後不能依賴它。 如果您需要在回呼之外保留一些該資訊，則需要將其複製到安全的位置。

被呼叫的 Worker 函式可以透過呼叫 emscripten_worker_respond() 來傳回資料。 當呼叫 Worker 時，如果提供了回呼，將使用三個參數呼叫它：一個資料指標、一個大小和一個在呼叫 emscripten_call_worker() 時提供的引數 (以便更容易將回呼與呼叫關聯)。 由資料指標和大小定義的資料區塊的行為與 Worker 函式中的資料區塊類似 — 它僅在回呼期間存在。

參數

  • worker ( worker_handle ) – 要呼叫的 Worker 的控制代碼。

  • funcname (const char*) – Worker 中函式的名稱。 函式必須是 C 函式 (因此沒有 C++ 名稱修飾)，並且必須匯出 (EXPORTED_FUNCTIONS)。

  • data (char*) – 要複製的記憶體區塊的位址。

  • size (int) – 記憶體區塊的大小。

  • callback ( em_worker_callback_func ) –

    帶有回應的 Worker 回呼。 這可以是 null。 回呼函式參數值為

    • (char)* : emscripten_call_worker() 中提供的 data 指標。

    • (int) : 資料區塊的 size。

    • (void)*：等於 arg (使用者定義的資料)。

  • arg (void*) – 要傳遞給回呼的引數 (使用者資料)

void emscripten_worker_respond(char *data, int size)
void emscripten_worker_respond_provisionally(char *data, int size)

當在 Worker 呼叫中 (也就是說，當由主執行緒使用 emscripten_call_worker() 呼叫時) 發送回應。

兩個函式都會將訊息發回呼叫 Worker 的執行緒。 emscripten_worker_respond_provisionally() 變體可以多次調用，這將把要發送到 Worker 建立者的訊息排隊。 最終，必須調用 _respond 變體，這將禁止進一步的訊息並釋放先前為此 Worker 呼叫分配的框架資源。

注意

呼叫暫時版本是可選的，但您必須呼叫非暫時版本以避免記憶體洩漏。

參數

  • data (char*) – 要發佈的訊息。

  • size (int) – 訊息的大小，以位元組為單位。

int emscripten_get_worker_queue_size(worker_handle worker)

檢查有多少回應正在等待來自 Worker 的回應。

這只會計算對 emscripten_call_worker() 的呼叫，這些呼叫具有回呼 (忽略具有 null 回呼的呼叫)，並且尚未收到回應。 這是一種簡單的方法來檢查 Worker 的狀態，以了解其忙碌程度，並對節流做出基本決定。

參數
返回

從 Worker 等待的回應數。

返回類型

int

記錄公用程式

定義

EM_LOG_CONSOLE

如果指定，則直接記錄到瀏覽器主控台/檢測器視窗。 如果未指定，則透過應用程式模組記錄。

EM_LOG_WARN

如果指定，則列印警告訊息 (與 EM_LOG_CONSOLE 結合使用)。

EM_LOG_INFO

如果指定，則將資訊訊息列印到主控台 (與 EM_LOG_CONSOLE 結合使用)。

EM_LOG_DEBUG

如果指定，則將除錯訊息列印到主控台 (與 EM_LOG_CONSOLE 結合使用)。

EM_LOG_ERROR

如果指定，則列印錯誤訊息 (與 EM_LOG_CONSOLE 結合使用)。 如果未指定 EM_LOG_WARN、 EM_LOG_ERROR、 EM_LOG_INFO 或 EM_LOG_DEBUG，則會列印記錄訊息。 EM_LOG_WARN、 EM_LOG_INFO、 EM_LOG_DEBUG 和 EM_LOG_ERROR 是互斥的。 如果未指定 EM_LOG_CONSOLE，則訊息將透過 err() (適用於 EM_LOG_ERROR 或 EM_LOG_WARN) 或 out() 輸出。

EM_LOG_C_STACK

如果指定，則列印一個呼叫堆疊，其中包含使用來源對應資訊參照原始 C 來源的檔案名稱。

EM_LOG_JS_STACK

如果指定，則列印一個呼叫堆疊，其中包含參照已建置的 .js/.html 檔案中的行以及訊息的檔案名稱。 可以組合旗標 EM_LOG_C_STACK 和 EM_LOG_JS_STACK 以輸出未翻譯和已翻譯的檔案和行資訊。

EM_LOG_NO_PATHS

如果指定，則呼叫堆疊中的檔案資訊路徑名稱將被省略。

函式

long emscripten_get_compiler_setting(const char *name)

傳回編譯器設定的值。

例如，若要傳回在編譯期間表示 INITIAL_MEMORY 值的整數

emscripten_get_compiler_setting("INITIAL_MEMORY")

對於包含整數以外任何內容的值，會傳回字串 (您需要將 long 傳回值轉換為 char*)。

它的一些有用的功能是提供 Emscripten 的版本 ("EMSCRIPTEN_VERSION")、最佳化層級 ("OPT_LEVEL")、除錯層級 ("DEBUG_LEVEL") 等。

為了使此命令正常運作，您必須使用以下編譯器選項進行建置 (因為我們不希望增加此中繼資料的建置大小)

-sRETAIN_COMPILER_SETTINGS
參數

  • name (const char*) – 要回傳的編譯器設定名稱。

返回

指定設定的值。請注意，對於整數以外的值，將會回傳字串（將 int 回傳值轉換為 char*）。

返回類型

int

int emscripten_has_asyncify()

回傳是否可以使用偽同步函式。

返回類型

int

返回

如果程式使用 -sASYNCIFY 編譯，則回傳 1，否則回傳 0。

void emscripten_debugger()

發出 debugger。

這會在程式碼中內嵌，告知 JavaScript 引擎如果執行到此處則調用偵錯工具。

void emscripten_log(int flags, const char* format, ...)

將訊息列印到主控台，可選擇包含呼叫堆疊資訊。

參數

  • flags (int) – 一組二進制 OR 運算的 EM_LOG_xxx 旗標，用於指定列印選項。

  • char* format (const) – printf 風格的格式字串。

  • ... – printf 風格的 “…” 參數列表，會根據 printf 格式規則進行解析。

int emscripten_get_callstack(int flags, char *out, int maxbytes)

以程式方式取得目前的呼叫堆疊。

若要查詢呼叫堆疊所需的位元組數，而不實際寫入，請將 0 傳遞給 out 和 maxbytes，在這種情況下，函式將回傳容納完整呼叫堆疊所需的位元組數（包括終止零）。請注意，這可能不是完全準確的，因為後續的呼叫將會帶有不同的行號，因此最好分配一些額外的位元組以確保安全。

參數

  • flags (int) – 一組二進制 OR 運算的 EM_LOG_xxx 旗標，用於指定列印選項。旗標 EM_LOG_CONSOLE、EM_LOG_WARN 和 EM_LOG_ERROR 在此函式中不適用，會被忽略。

  • out (char*) – 指向記憶體區域的指標，呼叫堆疊字串將會寫入到該區域。此函式輸出的字串將始終以 null 字元結尾。

  • maxbytes (int) – 此函式可以寫入到 out 所指向的記憶體的最大位元組數。如果空間不足，輸出將會被截斷（但始終以 null 字元結尾）。

返回

寫入的位元組數（非字元數，因此也將包含終止零）。

返回類型

int

char *emscripten_get_preloaded_image_data(const char *path, int *w, int *h)

取得預先載入的影像資料和影像大小。

函式回傳指向載入影像的指標，或 NULL — 該指標應使用 free() 釋放。如果資料有效，影像的寬度和高度將會寫入到 w 和 h 參數中。

參數

  • path (const char*) – 包含預先載入影像的檔案完整路徑/檔案名稱。

  • w (int*) – 影像寬度（如果資料有效）。

  • h (int*) – 影像高度（如果資料有效）。

返回

指向預先載入影像的指標或 NULL。

返回類型

char*

char *emscripten_get_preloaded_image_data_from_FILE(FILE *file, int *w, int *h)

從 C FILE* 取得預先載入的影像資料。

參數

  • file (FILE*) – 包含預先載入影像的 FILE。

  • w (int*) – 影像寬度（如果資料有效）。

  • h (int*) – 影像高度（如果資料有效）。

返回

指向預先載入影像的指標或 NULL。

返回類型

char*

int emscripten_print_double(double x, char *to, signed max)

將 double 列印為字串，包括 null 終止符。這很有用，因為 JS 引擎能夠很好地支援以盡可能小的尺寸列印 double，同時保留 double 中的所有資訊，也就是說，之後可以完全可逆地解析回去（snprintf 等函式無法做到）。

參數

  • x (double) – double 值。

  • to (char*) – 預先分配的足夠大小的緩衝區，如果不需要輸出則為 NULL（用於取得必要大小時很有用）。

  • max (signed) – 可以寫入輸出指標 ‘to’ 的最大位元組數（包括 null 終止符）。

返回類型

必要的位元組數，不包括 null 終止符（如果 to 不是 NULL，則實際寫入）。

Socket 事件註冊

本節中的函式會註冊回呼函式，用於接收 socket 事件。這些事件類似於 WebSocket 事件，但在內部 Emscripten socket 處理之後發出。例如，這表示訊息回呼會在資料新增到 *recv_queue* 後觸發，因此接收此回呼的應用程式可以使用作為參數傳遞給回呼的檔案描述符，簡單地讀取資料。所有的回呼都會傳遞一個檔案描述符 (fd)，表示發生通知活動的 socket。錯誤回呼也會取得一個 int，表示 socket 錯誤編號 (errno)，以及一個 char*，表示錯誤訊息 (msg)。

只能註冊單一回呼函式來處理任何給定的事件，因此多次呼叫給定的註冊函式將導致第一個回呼被取代。同樣地，將 NULL 回呼函式傳遞給任何 emscripten_set_socket_*_callback 呼叫將取消註冊該事件註冊的回呼。

userData 指標允許在事件註冊期間指定的任意資料傳遞給回呼，這對於在物件導向程式碼中傳遞 this 指標特別有用。

除了能夠從 C 註冊網路回呼之外，原生 JavaScript 程式碼也可以直接使用用於實作回呼註冊的基礎機制。例如，以下程式碼顯示了當啟用 SOCKET_DEBUG 時預設註冊的簡單記錄回呼

Module['websocket']['on']('error', function(error) {console.log('Socket error ' + error);});
Module['websocket']['on']('open', function(fd) {console.log('Socket open fd = ' + fd);});
Module['websocket']['on']('listen', function(fd) {console.log('Socket listen fd = ' + fd);});
Module['websocket']['on']('connection', function(fd) {console.log('Socket connection fd = ' + fd);});
Module['websocket']['on']('message', function(fd) {console.log('Socket message fd = ' + fd);});
Module['websocket']['on']('close', function(fd) {console.log('Socket close fd = ' + fd);});

上面的大多數 JavaScript 回呼函式都會傳遞觸發回呼的 socket 檔案描述符，但是錯誤回呼會傳遞一個包含檔案描述符、錯誤碼和錯誤訊息的陣列。

注意

基礎 JavaScript 實作不會傳遞 userData。這主要適用於 C/C++ 程式碼，而 emscripten_set_socket_*_callback 呼叫僅建立一個包含 userData 的閉包，並將其作為回呼傳遞給基礎 JavaScript 事件註冊機制。

回呼函式

em_socket_callback

emscripten_set_socket_open_callback() 和其他 socket 函式（除了 emscripten_set_socket_error_callback()）的函式指標。其定義如下：

typedef void (*em_socket_callback)(int fd, void *userData);
參數

  • fd (int) – 觸發回呼的 socket 的檔案描述符。

  • userData (void*) – 最初傳遞給事件註冊函式的 userData。

em_socket_error_callback

emscripten_set_socket_error_callback() 的函式指標，定義如下：

typedef void (*em_socket_error_callback)(int fd, int err, const char* msg, void *userData);
參數

  • fd (int) – 觸發回呼的 socket 的檔案描述符。

  • err (int) – 發生的錯誤代碼。

  • msg (int) – 發生的錯誤訊息。

  • userData (void*) – 最初傳遞給事件註冊函式的 userData。

函式

void emscripten_set_socket_error_callback(void *userData, em_socket_error_callback callback)

由 WebSocket 錯誤觸發。

如需詳細資訊，請參閱Socket 事件註冊。

參數

  • userData (void*) – 要傳遞給回呼的任意使用者資料。

  • callback (em_socket_error_callback) – 指向回呼函式的指標。回呼會回傳檔案描述符、錯誤代碼和訊息，以及傳遞給此函式的任意 userData。

void emscripten_set_socket_open_callback(void *userData, em_socket_callback callback)

當 WebSocket 開啟時觸發。

如需詳細資訊，請參閱Socket 事件註冊。

參數

  • userData (void*) – 要傳遞給回呼的任意使用者資料。

  • callback (em_socket_callback) – 指向回呼函式的指標。此回呼函式會傳回檔案描述符和傳遞至此函式的任意 userData。

void emscripten_set_socket_listen_callback(void *userData, em_socket_callback callback)

當呼叫 listen 時觸發（合成事件）。

如需詳細資訊，請參閱Socket 事件註冊。

參數

  • userData (void*) – 要傳遞給回呼的任意使用者資料。

  • callback (em_socket_callback) – 指向回呼函式的指標。此回呼函式會傳回檔案描述符和傳遞至此函式的任意 userData。

void emscripten_set_socket_connection_callback(void *userData, em_socket_callback callback)

當連線建立時觸發。

如需詳細資訊，請參閱Socket 事件註冊。

參數

  • userData (void*) – 要傳遞給回呼的任意使用者資料。

  • callback (em_socket_callback) – 指向回呼函式的指標。此回呼函式會傳回檔案描述符和傳遞至此函式的任意 userData。

void emscripten_set_socket_message_callback(void *userData, em_socket_callback callback)

當有資料可從 socket 讀取時觸發。

如需詳細資訊，請參閱Socket 事件註冊。

參數

  • userData (void*) – 要傳遞給回呼的任意使用者資料。

  • callback (em_socket_callback) – 指向回呼函式的指標。此回呼函式會傳回檔案描述符和傳遞至此函式的任意 userData。

void emscripten_set_socket_close_callback(void *userData, em_socket_callback callback)

當 WebSocket 關閉時觸發。

如需詳細資訊，請參閱Socket 事件註冊。

參數

  • userData (void*) – 要傳遞給回呼的任意使用者資料。

  • callback (em_socket_callback) – 指向回呼函式的指標。此回呼函式會傳回檔案描述符和傳遞至此函式的任意 userData。

未對齊的型別

型別定義

emscripten_align1_short
emscripten_align2_int
emscripten_align1_int
emscripten_align2_float
emscripten_align1_float
emscripten_align4_double
emscripten_align2_double
emscripten_align1_double

未對齊的型別。這些可以用來強制 LLVM 在程式碼中 SAFE_HEAP 發現未對齊操作的位置發出未對齊的載入/儲存。

如需使用範例，請參閱 test/core/test_set_align.c。

注意

最好避免未對齊的操作，但是如果您要從封裝的位元組串流讀取，或者類似的情況，這些型別可能會很有用！

偽同步函式

這些函式需要 Asyncify (-sASYNCIFY)。這些函式是非同步的，但在 C 中看起來是同步的。有關更多詳細資訊，請參閱 Asyncify。

睡眠

void emscripten_sleep(unsigned int ms)

睡眠 ms 毫秒。這對程式碼來說似乎是正常的「同步」睡眠，也就是說，直到睡眠完成，才會繼續執行到下一個原始碼行。但是請注意，這是透過返回事件迴圈來實作的（實際上無法在 Web 上以阻塞方式睡眠），這表示可能會發生其他非同步事件。

網路

int emscripten_wget(const char* url, const char* file)

同步 從 URL 載入檔案。對於非同步版本，請參閱 emscripten_async_wget()。

除了從網路擷取 URL 之外，還會執行預先載入外掛程式，以便資料可在 IMG_Load 等中使用（我們同步執行工作，使瀏覽器解碼圖像或音訊等）。有關預先載入檔案的更多資訊，請參閱 預先載入檔案。

此函式為阻塞式；它不會返回，直到所有操作完成。然後，您可以開啟並讀取檔案（如果成功）。

參數

  • char* url (const) – 要載入的 URL。

  • char* file (const) – 從 URL 建立和載入的檔案名稱。如果檔案已存在，則會覆寫。如果檔案的目的地目錄在檔案系統上不存在，則會建立。可以傳遞相對路徑名稱，它將相對於呼叫此函數時的目前工作目錄進行解譯。

返回

成功時為 0，錯誤時為 1。

void emscripten_wget_data(const char* url, void** pbuffer, int* pnum, int *perror);

同步從網路擷取資料，並將其儲存到記憶體中的緩衝區，該緩衝區是為您配置的。您必須釋放緩衝區，否則會洩漏！

參數

  • url – 要從中擷取的 URL

  • pbuffer – 一個 out 參數，將填入指向包含下載資料的緩衝區的指標。此空間已為您 malloc，您必須釋放它，否則會洩漏！

  • pnum – 一個 out 參數，將填入下載資料的大小。

  • perror – 一個 out 參數，如果發生錯誤，將填入非零值。

IndexedDB

void emscripten_idb_load(const char *db_name, const char *file_id, void** pbuffer, int* pnum, int *perror);

同步從 IndexedDB 擷取資料，並將其儲存到記憶體中的緩衝區，該緩衝區是為您配置的。您必須釋放緩衝區，否則會洩漏！

參數

  • db_name – 要從中載入的資料庫名稱

  • file_id – 要載入的檔案名稱

  • pbuffer – 一個 out 參數，將填入指向包含下載資料的緩衝區的指標。此空間已為您 malloc，您必須釋放它，否則會洩漏！

  • pnum – 一個 out 參數，將填入下載資料的大小。

  • perror – 一個 out 參數，如果發生錯誤，將填入非零值。

void emscripten_idb_store(const char *db_name, const char *file_id, void* buffer, int num, int *perror);

同步將資料儲存到 IndexedDB。

參數

  • db_name – 要儲存到的資料庫名稱

  • file_id – 要儲存的檔案名稱

  • buffer – 指向要儲存資料的指標

  • num – 要儲存的位元組數

  • perror – 一個 out 參數，如果發生錯誤，將填入非零值。

void emscripten_idb_delete(const char *db_name, const char *file_id, int *perror);

同步從 IndexedDB 刪除資料。

參數

  • db_name – 要從中刪除的資料庫名稱

  • file_id – 要刪除的檔案名稱

  • perror – 一個 out 參數，如果發生錯誤，將填入非零值。

void emscripten_idb_exists(const char *db_name, const char *file_id, int* pexists, int *perror);

同步檢查檔案是否存在於 IndexedDB 中。

參數

  • db_name – 要在其中檢查的資料庫名稱

  • file_id – 要檢查的檔案名稱

  • pexists – 一個 out 參數，如果檔案存在於該資料庫中，將填入非零值。

  • perror – 一個 out 參數，如果發生錯誤，將填入非零值。

void emscripten_idb_clear(const char *db_name, int *perror);

同步清除 IndexedDB 中的所有資料。

參數

  • db_name – 要清除的資料庫名稱

  • perror – 一個 out 參數，如果發生錯誤，將填入非零值。

Asyncify 函式

這些函式僅在使用 Asyncify 時才有效。

型別定義

em_scan_func

用於掃描回呼的函式指標型別，接收兩個指標，分別指向記憶體範圍的開頭和結尾。然後您可以掃描該範圍。

定義為

typedef void (*em_scan_func)(void*, void*)

函式

void emscripten_scan_stack(em_scan_func func)

掃描 C 使用者空間堆疊，這表示編譯程式碼管理的堆疊（相對於 Wasm VM 的內部堆疊，它無法直接觀察）。此資料已在線性記憶體中；此函式僅為您提供一種簡單的方法來知道它在哪裡。

void emscripten_scan_registers(em_scan_func func)

掃描「暫存器」，我們指的是不在記憶體中的資料。在 Wasm 中，這表示儲存在區域變數中的資料，包括堆疊較高函式中的區域變數 - Wasm VM 已將它們溢出，但所有這些都無法讓使用者程式碼觀察到）。

請注意，此函式會掃描 Wasm 區域變數。根據 LLVM 的最佳化層級，這可能不會掃描原始碼中的原始區域變數。例如，在 -O0 中，區域變數可能會儲存在堆疊上。為了確保您掃描所有必要的內容，您也可以執行 emscripten_scan_stack。

此函式需要 Asyncify - 它依賴該選項將區域狀態溢出到整個堆疊中。因此，它會增加程式的負擔。

void emscripten_lazy_load_code()

這會在編譯時建立兩個 Wasm 檔案：第一個 Wasm 會正常下載和執行，第二個 Wasm 會延遲載入。當到達 emscripten_lazy_load_code() 呼叫時，我們會載入第二個 Wasm 並使用它繼續執行。

這裡的想法是，如果您的程式碼庫中有足夠的 emscripten_lazy_load_code() 呼叫，則初始下載可以非常小，因為最佳化器如果看到無法到達，則可以從第一個 Wasm 中移除程式碼。第二個下載的 Wasm 可以包含您的完整程式碼庫，包括很少使用的函式，在這種情況下，延遲載入可能根本不會發生。

注意

這需要使用 -sASYNCIFY_LAZY_LOAD_CODE 進行建置。

ABI 函式

以下函式未在 emscripten.h 中宣告，但在我們的系統程式庫中內部使用。如果您要替換 Emscripten 執行階段 JS 程式碼，或在您自己的執行階段中執行 Emscripten 二進位檔，您可能會關心它們。

void emscripten_notify_memory_growth(i32 index)

當記憶體擴增時呼叫。在 JS 執行環境中，這用於知道何時更新 Wasm 記憶體的 JS 視圖，否則我們需要在任何 Wasm 程式碼執行後不斷檢查。請參閱這個 wasi 討論。

參數

  • index (i32) – 指示哪個記憶體已擴增。