emscripten.h¶

このページでは、emscripten.hによって提供される公開C++ APIについて説明します。

Emscriptenは、可能な限り既存の/使い慣れたAPIを使用します（例：SDL）。このAPIは、JavaScriptまたはブラウザ環境に固有の機能、または既存のAPIがない機能に対するC++サポートを提供します。

インラインアセンブリ/JavaScript
C/C++からのJavaScriptの呼び出し
ブラウザ実行環境
非同期ファイルシステムAPI
非同期IndexedDB API
コンパイル
Worker API
ロギングユーティリティ
ソケットイベント登録
未整列型
擬似同期関数
Asyncify関数
ABI関数

インラインアセンブリ/JavaScript ¶

以下のAPIに関するガイド資料は、C/C++からJavaScriptを呼び出すにあります。

定義¶

EM_JS(return_type, function_name, arguments, code)¶

JavaScriptライブラリ関数の便利な構文。

これにより、Cコード内でJavaScriptを関数として宣言し、通常のC関数のように呼び出すことができます。たとえば、次のCプログラムは、Emscriptenでコンパイルしてブラウザで実行した場合、2つのアラートを表示します。

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

ヌル終端された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を宣言でき、コンパイルされたコードがブラウザで実行されるときに実行されます。たとえば、次のCコードは、Emscriptenでコンパイルしてブラウザで実行した場合、2つのアラートを表示します。

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

引数はJavaScriptコードブロック内に渡すことができ、$0、$1などの変数として渡されます。これらの引数は、int32_tまたはdoubleのいずれかの型になります。

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

{と}に注意してください。

ヌル終端された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の実行を終えた後に実行が再開されます。同期プロキシにより、値を返すことも可能になります。次の2つのバリアントを参照してください。

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ワーカーのスコープ内で実行されます。メインランタイムスレッドのスコープで関数を評価するには、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ワーカーのスコープ内で実行されます。メインランタイムスレッドのスコープで関数を評価するには、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ワーカーのスコープ内で実行されます。メインランタイムスレッドのスコープで関数を評価するには、emscripten_sync_run_in_main_runtime_thread()関数を参照してください。

パラメータ

script (const char*) – 評価するスクリプト。

戻り値

評価の結果（文字列）。

戻り値の型

char*

void emscripten_async_run_script(const char *script, int millis)¶

指定された時間後に、非同期的にスクリプトを実行します。

この関数はpthreadから呼び出すことができ、pthreadをホストしているWebワーカーのスコープ内で実行されます。メインランタイムスレッドのスコープで関数を評価するには、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環境は、指定された1秒あたりのフレーム数でその関数を呼び出します。メインブラウザスレッドで呼び出された場合、fpsとして0または負の値を設定すると、ブラウザのrequestAnimationFrameメカニズムを使用してメインループ関数を呼び出します。レンダリングを行っている場合は、ブラウザのrequestAnimationFrameがブラウザとモニターに適切に合わせたスムーズなレートでレンダリングするようにするため、**強く推奨**されます。アプリケーションでまったくレンダリングを行わない場合は、コードに適した特定のフレームレートを選択する必要があります。

simulate_infinite_loopがtrueの場合、関数は例外をスローして呼び出し元の処理を停止します。emscripten_set_main_loop()への呼び出し後のコードではなく、メインループが実行されるようになるため、これは無限ループをシミュレートするためにできる限り近い方法です（glutMainLoop in GLUTで同様のことを行っています）。このパラメータがfalseの場合、動作は、このパラメータがAPIに追加される前の動作と同じになります。つまり、処理は通常通り継続されます。どちらの場合も、グローバルデストラクタ、atexitなどは実行されません。メインループはまだ実行中であることがわかっているためですが、無限ループをシミュレートしない場合、スタックはアンワインドされます。つまり、simulate_infinite_loopがfalseの場合、スタック上にオブジェクトを作成した場合、メインループが最初に呼び出される前にクリーンアップされます。

この関数はpthreadで呼び出すことができ、その場合、コールバックループは呼び出しスレッドのコンテキストで呼び出されるように設定されます。ループが機能するためには、呼び出しスレッドは、pthreadメイン関数から終了することでブラウザに定期的に「戻す」必要があります。コールバックは、呼び出しスレッドが他のコードを実行していない場合にのみ実行できるためです。つまり、同期的にブロッキングするメインループを実行することは、emscripten_set_main_loop()関数と互換性がありません。

requestAnimationFrame() APIはwebワーカーでは使用できないため、fps <= 0でpthreadでemscripten_set_main_loop()を呼び出した場合、ディスプレイのリフレッシュレートに同期させる効果がエミュレートされ、一般的に垂直同期間隔と正確に一致することはありません。

ヒント

スレッドごとに、同時に存在できるメインループ関数は1つだけです。メインループ関数を変更するには、まずcancelで現在のループを取り消し、その後この関数を呼び出して別のループを設定します。

注記

emscripten_set_main_loop_expected_blockers()、emscripten_pause_main_loop()、emscripten_resume_main_loop()、およびemscripten_cancel_main_loop()を参照して、呼び出しスレッドのメインループのブロック、一時停止、再開に関する情報を参照してください。

注記

この関数を呼び出すと、パラメータfpsで指定されたタイミングモードが適用されるため、呼び出しスレッドでのemscripten_set_main_loop_timing()への以前の呼び出しの効果は上書きされます。現在のスレッドに異なるタイミングモードを指定するには、メインループを設定した後にemscripten_set_main_loop_timing()関数を呼び出します。

注記

現在、新しいWasm例外処理とsimulate_infinite_loop == trueを同時に使用することは、呼び出し時にスタック上にデストラクタを持つオブジェクトがあるC++プロジェクトではまだ動作しません。

パラメータ

func (em_callback_func) – 呼び出しスレッドのメインイベントループとして設定するC関数。
fps (int) – JavaScriptが関数を呼び出す1秒あたりのフレーム数。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関数。関数のシグネチャには、arg値を渡すためのvoid*パラメータが必要です。
arg (void*) – メインループ関数に渡されるユーザー定義データ。API自体では変更されません。
fps (int) – JavaScriptが関数を呼び出す1秒あたりのフレーム数。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) – メインループブロッカー関数。関数のシグネチャには、arg値を渡すためのvoid*パラメータが必要です。
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_set_main_loop()関数を呼び出すことで指定されたメインループをEmscriptenランタイムが駆動する速度を対話的に制御するために使用できます。ネイティブ開発では、これは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は、メインループへの後続のティック間の待機時間をミリ秒単位で指定し、更新はディスプレイのvsyncレートとは独立して行われます（vsyncオフ）。この方法は、JavaScriptのsetTimeout関数を使用してアニメーションを駆動します。
- modeがEM_TIMING_RAFの場合、requestAnimationFrame関数を使用して更新が行われ（vsync有効）、この値はメインループの「スワップインターバル」レートとして解釈されます。1の値は、ランタイムがすべてのvsync（通常60fps）でレンダリングする必要があることを指定し、2の値は、メインループコールバックが2番目のvsync（30fps）ごとでのみ呼び出されることを意味します。一般的な式として、nの値は、メインループがn番目のvsyncごと、または60Hzディスプレイの場合は60/nのレート、120Hzディスプレイの場合は120/nのレートで更新されることを意味します。
- modeがEM_TIMING_SETIMMEDIATEの場合、setImmediate関数を使用して更新が行われ、使用できない場合はpostMessageを使用してエミュレートされます。詳細については、「MDNのsetImmediate setImmediate on MDN <https://developer.mozilla.org/en-US/docs/Web/API/Window/setImmediate>」を参照してください。このモードは、ドラフト段階にある不安定なWeb拡張機能に依存し、IE以外のブラウザでは現在サポートされておらず、実装はレビューで物議を醸しているため、Emscriptenの出力をWebに展開する場合には**強く推奨されません**。

戻り値の型

int

戻り値

成功すると0が返され、失敗するとゼロ以外の値が返されます。この関数を呼び出す前にアクティブなメインループがない場合に失敗が発生します。

注記

ブラウザは、他の提供されているモードではなく、アニメーションにrequestAnimationFrameを使用することに重点的に最適化されています。そのため、ブラウザ全体で最高のエクスペリエンスを得るために、mode=EM_TIMING_RAFおよびvalue=1でこの関数を呼び出すと、最適な結果が得られます。JavaScriptのsetTimeout関数を使用すると、スタッターが発生し、一般的にrequestAnimationFrame関数を使用する場合よりもエクスペリエンスが悪くなることが知られています。

注記

setTimeoutとrequestAnimationFrameの間には機能的な違いがあります。ユーザーがブラウザウィンドウを最小化したり、アプリケーションタブを隠したりした場合、ブラウザは通常requestAnimationFrameのコールバックの呼び出しを停止しますが、setTimeoutベースのメインループは、間隔が大幅に絞られるものの、実行を続けます。setTimeout on MDN <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()関数を呼び出すことで制御されます。

パラメータ mode

NULLでない場合、使用されているタイミングモードがここに返されます。

型 mode

int*

パラメータ value

NULLでない場合、使用されているタイミング値がここに返されます。

型 value

int*

void emscripten_set_main_loop_expected_blockers(int num)¶

これからプッシュされるブロッカーの数を設定します。

この数は、一連のブロッカーを通過する相対的な進捗状況を報告するために使用されます。その後に、メインループが続行されます。

例えば、ゲームでは新しいレベルを開始する前に10個のブロッカーを実行する必要があるかもしれません。この操作では、最初にこの値を「10」に設定してから、10個のブロッカーをプッシュします。3番目のブロッカー（例えば）が完了すると、進捗状況は3/10と表示されます。

パラメータ

num (int) – これからプッシュされるブロッカーの数。

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

JavaScriptイベントループに制御を返す後に、C関数を非同期的に呼び出します。

これはsetTimeoutによって行われます。

ネイティブにビルドすると、SDL_Delayの後、単純な直接呼び出しになります（そのためには**SDL.h**を含める必要があります）。

millisが負の場合、ブラウザのrequestAnimationFrameメカニズムが使用されます。（0はsetTimeoutが依然として使用されることを意味し、基本的に「できるだけ早く非同期的に実行する」ことを意味します。）

パラメータ

func (em_arg_callback_func) – 非同期的に呼び出すC関数。関数のシグネチャには、arg値を渡すためのvoid*パラメータが必要です。
arg (void*) – C関数に渡すユーザー定義の引数。
millis (int) – 関数を呼び出すまでのタイムアウト。

void emscripten_exit_with_live_runtime(void)¶

現在のスレッドの実行を停止しますが、後でコードを実行し続けられるようにランタイムはアクティブな状態のままです（そのため、グローバルデストラクタなどは実行されません）。emscripten_async_call()などの非同期操作を実行すると、ランタイムは自動的にアクティブな状態が維持されるため、これらの場合はこの関数を呼び出す必要はありません。

マルチスレッドアプリケーションでは、これは現在のスレッドを終了するだけです（そして、それが実行されているWebワーカーで後でコードを実行できるようにします）。

void emscripten_force_exit(int status)¶

exit()を呼び出した場合と同様に、ランタイムをシャットダウンしてプログラムを終了（終了）します。

emscripten_force_exitは、以前にemscripten_exit_with_live_runtime()を呼び出した場合や、その他の方法でランタイムをアクティブな状態に維持した場合でも、ランタイムをシャットダウンします。言い換えれば、このメソッドは、main()の完了後にアクティブな状態が維持された後でも、ランタイムを完全にシャットダウンするオプションを提供します。

EXIT_RUNTIMEが設定されていない場合（デフォルトではそうなっています）、ランタイムはシャットダウンできません。シャットダウンを実行するためのコードを含めていないためです。ランタイムを終了できるようにするには、-sEXIT_RUNTIMEを使用してビルドします。

パラメータ

status (int) – *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コマンドは、OSカーソルではなくSDLカーソルを表示および非表示にします。このコマンドは、アプリが独自のカーソルを描画する場合にOSカーソルを非表示にするのに役立ちます。

double emscripten_get_now(void)¶

ブラウザが提供する、現在の時間の最高精度の表現を返します。

これはDate.nowまたはperformance.nowを使用します。結果は絶対時間ではなく、この関数の他の呼び出しとの比較でのみ意味があります。

戻り値の型: double
戻り値: ミリ秒（ms）単位の現在時刻。

float emscripten_random(void)¶

0〜1の範囲の乱数を生成します。これはMath.random()にマップされます。

戻り値の型: float
戻り値: 乱数。

非同期ファイルシステムAPI ¶

typedefs¶

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)* : 読み込まれた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)* : データを含むバッファへのポインタ。ワーカー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()を呼び出す必要があります。

ファイルの準備ができると、argとfileで指定されたオブジェクトポインタを使用してonloadコールバックが呼び出されます。ダウンロード中は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）。これを使用してリクエストを中止できます。

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などはファイルで動作します）。

ファイルの準備ができると、arg、メモリ内のバッファへのポインタ、およびバッファのサイズを含む符号なし整数を指定してonloadコールバックが呼び出されます。ダウンロード中は、onprogressコールバックがプログレス情報と共に呼び出されます。エラーが発生した場合は、HTTPステータスコードとステータス記述を含む文字列を指定してonerrorが呼び出されます。

パラメータ

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) : データの合計サイズ（バイト単位）。サイズが不明な場合は0。

戻り値

リクエストへのハンドル（int）。これを使用してリクエストを中止できます。

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は2番目のパラメータも受け取ります。これは「偽の」ファイル名であり、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);

ファイル名またはURLから共有ライブラリをロードする非同期dlopen操作を開始します。すぐに返し、呼び出し元がイベントループに戻る必要があります。onsuccessとonerrorコールバックは、リクエストの成功または失敗を通知するために使用されます。onerrorコールバック時に、通常のdlerror C関数を用いてエラーの詳細を取得できます。フラグは、通常のdlopen C関数で使用されるものと同じです。

パラメータ

char* filename (const) – ロードする共有ライブラリのファイル名（またはURL）。
flags (int) – dlopenフラグを参照してください。
user_data (void*) – onsuccessとonerrorコールバックに渡されるユーザーデータ。
onsuccess (em_dlopen_callback) – ライブラリが正常にロードされた場合に呼び出されます。
onerror (em_arg_callback_func) – ライブラリのロードにエラーがあった場合に呼び出されます。

非同期IndexedDB API ¶

IndexedDBは、データを永続的に保存できるブラウザAPIです。つまり、そこにデータを保存し、ユーザーがウェブページを再訪したときに後でロードすることができます。IDBFSは、Emscriptenファイルシステム層を通してIndexedDBを使用する1つの方法を提供します。ここにリストされている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)* : データを含むバッファへのポインタ。ワーカー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"); }

これは、シンボルが定義されているオブジェクトファイルがそれ以外にリンカによって含まれている場合にのみ機能することに注意してください。オブジェクトファイルがアーカイブの一部であり、それ以外に参照されていない場合、リンカはそれをまったく含めず、オブジェクトファイル内のシンボルは含まれず、エクスポートされません。この制限を回避する1つの方法は、アーカイブファイルのどちら側にも-Wl,--whole-archive / -Wl,--no-whole-archiveフラグを使用することです。

Worker API ¶

typedefs¶

int worker_handle¶

Web Workerをラップして、Workerの作成と通信を可能にします。

現在のAPIは、主にジョブをWorkerに送信して応答を待つメインスレッドに焦点を当てていることに注意してください。つまり、非対称的な方法で、Workerからメインスレッドに要求されることなくメッセージを送信する現在のAPIはありません。

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は、POSIXスレッドの実装とこのWorker APIは互換性がないため、-pthreadフラグを使用してコンパイルしないでください。

パラメータ

url (const char*) – WorkerスクリプトのURL。

戻り値

新しく作成されたワーカーへのハンドル。

戻り値の型

worker_handle

void emscripten_destroy_worker(worker_handle worker)¶

ワーカーを破棄します。emscripten_create_worker()を参照してください。

パラメータ

worker (worker_handle) – 破棄するワーカーへのハンドル。

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

非同期的にワーカーを呼び出します。

ワーカー関数は、2つのパラメーター（データポインターとサイズ）で呼び出されます。ポインターとサイズで定義されたデータブロックは、コールバック中のみ存在します。**その後は使用できません**。コールバックの外でその情報の一部を保持する必要がある場合は、安全な場所にコピーする必要があります。

呼び出されたワーカー関数は、emscripten_worker_respond()を呼び出すことでデータを送信できます。ワーカーが呼び出されると、コールバックが指定されている場合、3つの引数（データポインター、サイズ、emscripten_call_worker()を呼び出したときに提供された引数）でコールバックが呼び出されます（コールバックを呼び出しに簡単に関連付けるため）。データポインターとサイズで定義されたデータブロックは、ワーカー関数内のデータブロックと同様に動作します。コールバック中のみ存在します。

パラメータ

worker (worker_handle) – 呼び出すワーカーへのハンドル。
funcname (const char*) – ワーカー内の関数の名前。関数はC関数である必要があり（C++の名前マングリングは使用できません）、エクスポートされている必要があります(EXPORTED_FUNCTIONS)。
data (char*) – コピーするメモリーブロックのアドレス。
size (int) – メモリーブロックのサイズ。
callback (em_worker_callback_func) –
応答を含むワーカーコールバック。これは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)¶

ワーカー呼び出し時（つまり、メインスレッドからemscripten_call_worker()を使用して呼び出されたとき）に応答を送信します。

どちらの関数も、ワーカーを呼び出したスレッドにメッセージをポストします。emscripten_worker_respond_provisionally()は複数回呼び出すことができ、ワーカーの作成者にポストするメッセージがキューイングされます。最終的に、_respond バリアントを呼び出す必要があります。これにより、それ以上のメッセージは許可されなくなり、このワーカー呼び出しのために以前に割り当てられたフレームワークリソースが解放されます。

注記

プロビジョナルバージョンを呼び出すことはオプションですが、リークを防ぐために非プロビジョナルバージョンを呼び出す必要があります。

パラメータ

data (char*) – ポストするメッセージ。
size (int) – メッセージのサイズ（バイト単位）。

int emscripten_get_worker_queue_size(worker_handle worker)¶

ワーカーから待機中の応答数を調べます。

これは、コールバックを持つemscripten_call_worker()への呼び出し（null コールバックを持つ呼び出しは無視されます）のうち、まだ応答が受信されていないものだけをカウントします。これは、ワーカーの状況を確認し、そのビジー状態を把握し、スロットリングに関する基本的な決定を行うための簡単な方法です。

パラメータ

worker (worker_handle) – 関連するワーカーへのハンドル。

戻り値

ワーカーから待機中の応答数。

戻り値の型

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) – EM_LOG_xxxフラグのリストにある項目のバイナリOR。出力オプションを指定します。
char* format (const) – printfスタイルのフォーマット文字列。
... – printfスタイルの「…」パラメータリスト。printfのフォーマット規則に従って解析されます。

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

現在のコールスタックをプログラムで取得します。

コールスタックを書き込まずに、必要なバイト数を問い合わせるには、outとmaxbytesに0を渡します。この場合、関数はその完全なコールスタックを保持するために必要なバイト数（終端のゼロを含む）を返します。後続の呼び出しでは異なる行番号が付けられるため、これは完全に正確ではない可能性があることに注意してください。安全のために数バイト余分に割り当てることをお勧めします。

パラメータ

flags (int) – EM_LOG_xxxフラグのリストにある項目のバイナリOR。出力オプションを指定します。EM_LOG_CONSOLE、EM_LOG_WARN、EM_LOG_ERRORフラグはこの関数では適用されず、無視されます。
out (char*) – コールスタック文字列が書き込まれるメモリ領域へのポインタ。この関数によって出力される文字列は常にヌル終端されます。
maxbytes (int) – この関数がoutが指すメモリに書き込むことができる最大バイト数。十分なスペースがない場合、出力は切り捨てられます（ただし、常にヌル終端されます）。

戻り値

書き込まれたバイト数（文字数ではなく、終端のゼロも含まれます）。

戻り値の型

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）をヌル終端を含む文字列として出力します。これは、JSエンジンがdoubleを可能な限り最小のサイズで、doubleの情報（全て）を保持する形で出力するのに優れたサポートを持っているため便利です。つまり、完全に可逆的に解析できます（残念ながら、snprintfなどはそうではありません）。

パラメータ

x (double) – 倍精度浮動小数点数。
to (char*) – 十分なサイズが事前に割り当てられたバッファ。出力が要求されない場合はNULL（必要なサイズを取得するために使用）。
max (signed) – 出力ポインタ「to」に書き込むことができる最大バイト数（ヌル終端を含む）。

戻り値の型

必要なバイト数（ヌル終端を含まない）。（toがNULLでない場合に実際に書き込まれるバイト数）。

ソケットイベントの登録 ¶

このセクションの関数は、ソケットイベントを受信するためのコールバック関数を登録します。これらのイベントはWebSocketイベントに似ていますが、内部Emscriptenソケット処理の後に出力されます。つまり、例えば、メッセージコールバックはデータがrecv_queueに追加された後にトリガーされるため、このコールバックを受信するアプリケーションは、コールバックのパラメータとして渡されるファイル記述子を使用してデータを簡単に読み取ることができます。すべてのコールバックには、通知されたアクティビティが発生したソケットを表すファイル記述子（fd）が渡されます。エラーコールバックには、ソケットエラー番号（errno）を表すintと、エラーメッセージ（msg）を表すchar*も渡されます。

特定のイベントを処理するために登録できるコールバック関数は1つだけです。そのため、特定の登録関数を複数回呼び出すと、最初のコールバックが置き換えられます。同様に、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コールバック関数のほとんどには、コールバックをトリガーしたソケットのファイル記述子が渡されますが、エラー発生時のコールバックには、ファイル記述子、エラーコード、エラーメッセージを含む配列が渡されます。

注記

基盤となるJavaScriptの実装ではuserDataは渡されません。これは主にC/C++コードで使用され、emscripten_set_socket_*_callback呼び出しは単にuserDataを含むクロージャを作成し、それを基盤となるJavaScriptイベント登録メカニズムへのコールバックとして渡します。

コールバック関数¶

em_socket_callback¶

emscripten_set_socket_open_callback()およびその他のソケット関数（emscripten_set_socket_error_callback()を除く）の関数ポインタ。これは次のように定義されています。

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

パラメータ

fd (int) – コールバックをトリガーしたソケットのファイル記述子。
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) – コールバックをトリガーしたソケットのファイル記述子。
err (int) – 発生したエラーのコード。
msg (int) – 発生したエラーのメッセージ。
userData (void*) – イベント登録関数に最初に渡されたuserData。

関数¶

void emscripten_set_socket_error_callback(void *userData, em_socket_error_callback callback)¶

WebSocketエラーによってトリガーされます。

詳細はソケットイベント登録を参照してください。

パラメータ

userData (void*) – コールバック関数に渡される任意のユーザーデータ。
callback (em_socket_error_callback) – コールバック関数のポインタ。コールバック関数はファイルディスクリプタ、エラーコード、メッセージ、およびこの関数に渡された任意のuserDataを返します。

void emscripten_set_socket_open_callback(void *userData, em_socket_callback callback)¶

WebSocketが開かれたときにトリガーされます。

詳細はソケットイベント登録を参照してください。

パラメータ

userData (void*) – コールバック関数に渡される任意のユーザーデータ。
callback (em_socket_callback) – コールバック関数のポインタ。コールバック関数はファイルディスクリプタとこの関数に渡された任意のuserDataを返します。

void emscripten_set_socket_listen_callback(void *userData, em_socket_callback callback)¶

listenが呼び出されたときにトリガーされます（合成イベント）。

詳細はソケットイベント登録を参照してください。

パラメータ

userData (void*) – コールバック関数に渡される任意のユーザーデータ。
callback (em_socket_callback) – コールバック関数のポインタ。コールバック関数はファイルディスクリプタとこの関数に渡された任意のuserDataを返します。

void emscripten_set_socket_connection_callback(void *userData, em_socket_callback callback)¶

接続が確立されたときにトリガーされます。

詳細はソケットイベント登録を参照してください。

パラメータ

userData (void*) – コールバック関数に渡される任意のユーザーデータ。
callback (em_socket_callback) – コールバック関数のポインタ。コールバック関数はファイルディスクリプタとこの関数に渡された任意のuserDataを返します。

void emscripten_set_socket_message_callback(void *userData, em_socket_callback callback)¶

ソケットから読み取れるデータがある場合にトリガーされます。

詳細はソケットイベント登録を参照してください。

パラメータ

userData (void*) – コールバック関数に渡される任意のユーザーデータ。
callback (em_socket_callback) – コールバック関数のポインタ。コールバック関数はファイルディスクリプタとこの関数に渡された任意のuserDataを返します。

void emscripten_set_socket_close_callback(void *userData, em_socket_callback callback)¶

WebSocketが閉じられたときにトリガーされます。

詳細はソケットイベント登録を参照してください。

パラメータ

userData (void*) – コールバック関数に渡される任意のユーザーデータ。
callback (em_socket_callback) – コールバック関数のポインタ。コールバック関数はファイルディスクリプタとこの関数に渡された任意のuserDataを返します。

アラインメントされていない型 ¶

typedef¶

emscripten_align1_short¶

emscripten_align2_int¶

emscripten_align1_int¶

emscripten_align2_float¶

emscripten_align1_float¶

emscripten_align4_double¶

emscripten_align2_double¶

emscripten_align1_double¶

アラインメントされていない型。これらは、SAFE_HEAPがアラインメントされていない操作を検出した場合に、LLVMがアラインメントされていないロード/ストアをコードの該当箇所に生成することを強制するために使用できます。

使用例については、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 – ダウンロードされたデータを含むバッファへのポインタが格納される出力パラメータ。この領域は自動的にmallocされます。**解放しないとメモリリークが発生します！**
pnum – ダウンロードされたデータのサイズが格納される出力パラメータ。
perror – エラーが発生した場合は0以外の値が格納される出力パラメータ。

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 – ダウンロードされたデータを含むバッファへのポインタが格納される出力パラメータ。この領域は自動的にmallocされます。**解放しないとメモリリークが発生します！**
pnum – ダウンロードされたデータのサイズが格納される出力パラメータ。
perror – エラーが発生した場合は0以外の値が格納される出力パラメータ。

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 – エラーが発生した場合は0以外の値が格納される出力パラメータ。

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

IndexedDBからデータを同期的に削除します。

パラメータ

db_name – データベース名
file_id – ファイル名
perror – エラーが発生した場合は0以外の値が格納される出力パラメータ。

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

IndexedDBにファイルが存在するかどうかを同期的に確認します。

パラメータ

db_name – データベース名
file_id – ファイル名
pexists – ファイルが存在する場合は0以外の値が格納される出力パラメータ。
perror – エラーが発生した場合は0以外の値が格納される出力パラメータ。

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

IndexedDBからすべてのデータを同期的にクリアします。

パラメータ

db_name – データベース名
perror – エラーが発生した場合は0以外の値が格納される出力パラメータ。

Asyncify関数 ¶

これらの関数はAsyncifyを使用している場合のみ機能します。

typedef¶

em_scan_func¶

スキャンコールバックで使用される関数ポインタ型。メモリ範囲の先頭と末尾の2つのポインタを受け取ります。その後、その範囲をスキャンできます。

次のように定義されています。

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()¶: これにより、コンパイル時に2つのWasmファイルが作成されます。1つ目は通常どおりダウンロードして実行されるWasmファイル、2つ目は遅延読み込みされるWasmファイルです。emscripten_lazy_load_code()呼び出しに到達すると、2つ目のWasmを読み込み、それを用いて実行を再開します。

ここでは、最初のダウンロードを非常に小さくすることができます。コードベースにemscripten_lazy_load_code()呼び出しを十分に配置すると、最適化によって到達できないと判断されたコードを最初のWasmから削除できます。2つ目のダウンロードされた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) – メモリが増加したインデックス。