emscripten.h

Diese Seite dokumentiert die öffentlichen C++-APIs, die von emscripten.h bereitgestellt werden.

Emscripten verwendet, wo immer möglich, bestehende/bekannte APIs (z.B. SDL). Diese API bietet C++-Unterstützung für Funktionen, die spezifisch für JavaScript oder die Browserumgebung sind, oder für die es keine bestehende API gibt.

Inline-Assembly/JavaScript

Anleitungsmaterial für die folgenden APIs finden Sie unter Aufrufen von JavaScript aus C/C++.

Defines

EM_JS(return_type, function_name, arguments, code)

Bequeme Syntax für JavaScript-Bibliotheksfunktionen.

Dies ermöglicht es Ihnen, JavaScript in Ihrem C-Code als Funktion zu deklarieren, die wie eine normale C-Funktion aufgerufen werden kann. Zum Beispiel würde das folgende C-Programm zwei Warnungen anzeigen, wenn es mit Emscripten kompiliert und im Browser ausgeführt würde

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

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

Argumente können als normale C-Argumente übergeben werden und haben denselben Namen im JavaScript-Code. Diese Argumente können entweder vom Typ int32_t oder double sein.

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

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

Nullterminierte C-Strings können ebenfalls an EM_JS-Funktionen übergeben werden, müssen aber, um mit ihnen zu arbeiten, aus dem Heap kopiert werden, um sie in hochstufige JavaScript-Strings umzuwandeln.

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

Auf die gleiche Weise können Zeiger auf beliebige Typen (einschließlich void *) innerhalb von EM_JS-Code übergeben werden, wo sie als Ganzzahlen erscheinen, wie es die char *-Zeiger oben taten. Der Zugriff auf die Daten kann durch direktes Lesen des Heaps verwaltet werden.

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

Zusätzlich können EM_JS-Funktionen einen Wert an den C-Code zurückgeben. Der Ausgabewert wird mit einer return-Anweisung zurückgegeben

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

Strings können von JavaScript an C zurückgegeben werden, aber man muss vorsichtig mit der Speicherverwaltung sein.

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(...)

Bequeme Syntax für Inline-Assembly/JavaScript.

Dies ermöglicht es Ihnen, JavaScript in Ihrem C-Code "inline" zu deklarieren, das dann ausgeführt wird, wenn Ihr kompilierter Code im Browser ausgeführt wird. Zum Beispiel würde der folgende C-Code zwei Warnungen anzeigen, wenn er mit Emscripten kompiliert und im Browser ausgeführt würde

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

Argumente können innerhalb des JavaScript-Codeblocks übergeben werden, wo sie als Variablen $0, $1 usw. ankommen. Diese Argumente können entweder vom Typ int32_t oder double sein.

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

Beachten Sie die { und }.

Nullterminierte C-Strings können ebenfalls an EM_ASM-Blöcke übergeben werden, aber um mit ihnen zu arbeiten, müssen sie aus dem Heap kopiert werden, um sie in hochstufige JavaScript-Strings umzuwandeln.

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

Auf die gleiche Weise können Zeiger auf beliebige Typen (einschließlich void *) innerhalb von EM_ASM-Code übergeben werden, wo sie als Ganzzahlen erscheinen, wie es die char *-Zeiger oben taten. Der Zugriff auf die Daten kann durch direktes Lesen des Heaps verwaltet werden.

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

Hinweis

  • Ab Emscripten 1.30.4 erscheinen die Inhalte von EM_ASM-Codeblöcken in der normalen JS-Datei, und infolgedessen können Closure-Compiler und andere JavaScript-Minifizierer damit arbeiten. Möglicherweise müssen Sie an einigen Stellen Sicherheitsanführungszeichen verwenden (a['b'] anstelle von a.b), um eine Minifizierung zu vermeiden.

  • Der C-Präprozessor versteht JavaScript-Token nicht, und daher kann es notwendig sein, den Codeblock in Klammern zu setzen, wenn der code-Block ein Komma-Zeichen , enthält. Zum Beispiel wird der Code EM_ASM(return [1,2,3].length); nicht kompiliert, aber EM_ASM((return [1,2,3].length)); schon.

EM_ASM_INT(code, ...)

Dieses Makro sowie EM_ASM_DOUBLE und EM_ASM_PTR verhalten sich wie EM_ASM, geben aber zusätzlich einen Wert an den C-Code zurück. Der Ausgabewert wird mit einer return-Anweisung zurückgegeben

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

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

Ähnlich wie EM_ASM_INT, aber für Zeiger-große Rückgabewerte. Beim Bau mit -sMEMORY64 führt dies zu einem i64-Rückgabewert, andernfalls zu einem i32-Rückgabewert.

Strings können von JavaScript an C zurückgegeben werden, aber man muss vorsichtig mit der Speicherverwaltung sein.

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, ...)

Ähnlich wie EM_ASM_INT, aber für einen double-Rückgabewert.

MAIN_THREAD_EM_ASM(code, ...)

Dies verhält sich wie EM_ASM, führt den Aufruf aber im Hauptthread aus. Dies ist nützlich in einer pthreads-Build, wenn Sie vom DOM aus mit einem pthread interagieren möchten; dies leitet den Aufruf im Grunde für Sie weiter.

Dieser Aufruf wird synchron an den Hauptthread weitergeleitet, d.h. die Ausführung wird fortgesetzt, nachdem der Hauptthread die Ausführung des JS beendet hat. Synchrones Proxying ermöglicht auch die Rückgabe eines Wertes, siehe die nächsten beiden Varianten.

MAIN_THREAD_EM_ASM_INT(code, ...)

Ähnlich wie MAIN_THREAD_EM_ASM, gibt aber einen int-Wert zurück.

MAIN_THREAD_EM_ASM_DOUBLE(code, ...)

Ähnlich wie MAIN_THREAD_EM_ASM, gibt aber einen double-Wert zurück.

MAIN_THREAD_EM_ASM_PTR(code, ...)

Ähnlich wie MAIN_THREAD_EM_ASM, gibt aber einen Zeigerwert zurück.

MAIN_THREAD_ASYNC_EM_ASM(code, ...)

Ähnlich wie MAIN_THREAD_EM_ASM, wird aber asynchron weitergeleitet, d.h. der Hauptthread erhält eine Anfrage, den Code auszuführen, und wird ihn ausführen, wenn er kann; der Worker wartet nicht darauf. (Beachten Sie, dass, wenn dies im Hauptthread aufgerufen wird, nichts weitergeleitet werden muss und der JS sofort und synchron ausgeführt wird.)

Aufrufen von JavaScript aus C/C++

Anleitungsmaterial für die folgenden APIs finden Sie unter Aufrufen von JavaScript aus C/C++.

Funktionszeigertypen für Rückrufe

Die folgenden Typen werden verwendet, um Funktions-Callback-Signaturen zu definieren, die in einer Reihe von Funktionen in dieser Datei verwendet werden.

em_callback_func

Allgemeiner Funktionszeigertyp zur Verwendung in Callbacks ohne Parameter.

Definiert als

typedef void (*em_callback_func)(void)
em_arg_callback_func

Generischer Funktionszeigertyp zur Verwendung in Callbacks mit einem einzelnen void*-Parameter.

Dieser Typ wird verwendet, um Funktions-Callbacks zu definieren, die beliebige Daten übergeben müssen. Zum Beispiel setzt emscripten_set_main_loop_arg() benutzerdefinierte Daten und übergibt sie bei Abschluss an einen Callback dieses Typs.

Definiert als

typedef void (*em_arg_callback_func)(void*)
em_str_callback_func

Allgemeiner Funktionszeigertyp zur Verwendung in Callbacks mit einem C-String (const char *) Parameter.

Dieser Typ wird für Funktions-Callbacks verwendet, denen ein C-String übergeben werden muss. Zum Beispiel wird er in emscripten_async_wget() verwendet, um den Namen einer Datei zu übergeben, die asynchron geladen wurde.

Definiert als

typedef void (*em_str_callback_func)(const char *)

Funktionen

void emscripten_run_script(const char *script)

Schnittstelle zur zugrunde liegenden JavaScript-Engine. Diese Funktion wird das gegebene Skript eval() ausführen. Hinweis: Wenn -sDYNAMIC_EXECUTION=0 gesetzt ist, ist diese Funktion nicht verfügbar.

Diese Funktion kann von einem pthread aufgerufen werden und wird im Umfang des Web Workers ausgeführt, der den pthread hostet. Um eine Funktion im Umfang des Hauptlaufzeit-Threads auszuwerten, siehe die Funktion emscripten_sync_run_in_main_runtime_thread().

Parameter

  • script (const char*) – Das auszuwertende Skript.

Rückgabetyp

void

int emscripten_run_script_int(const char *script)

Schnittstelle zur zugrunde liegenden JavaScript-Engine. Diese Funktion wird das gegebene Skript eval() ausführen. Hinweis: Wenn -sDYNAMIC_EXECUTION=0 gesetzt ist, ist diese Funktion nicht verfügbar.

Diese Funktion kann von einem pthread aufgerufen werden und wird im Umfang des Web Workers ausgeführt, der den pthread hostet. Um eine Funktion im Umfang des Hauptlaufzeit-Threads auszuwerten, siehe die Funktion emscripten_sync_run_in_main_runtime_thread().

Parameter

  • script (const char*) – Das auszuwertende Skript.

Gibt zurück

Das Ergebnis der Auswertung als Ganzzahl.

Rückgabetyp

int

char *emscripten_run_script_string(const char *script)

Schnittstelle zur zugrunde liegenden JavaScript-Engine. Diese Funktion wird das gegebene Skript eval() ausführen. Beachten Sie, dass diese Überladung einen einzigen Puffer verwendet, der zwischen Aufrufen geteilt wird. Hinweis: Wenn -sDYNAMIC_EXECUTION=0 gesetzt ist, ist diese Funktion nicht verfügbar.

Diese Funktion kann von einem pthread aufgerufen werden und wird im Umfang des Web Workers ausgeführt, der den pthread hostet. Um eine Funktion im Umfang des Hauptlaufzeit-Threads auszuwerten, siehe die Funktion emscripten_sync_run_in_main_runtime_thread().

Parameter

  • script (const char*) – Das auszuwertende Skript.

Gibt zurück

Das Ergebnis der Auswertung als String.

Rückgabetyp

char*

void emscripten_async_run_script(const char *script, int millis)

Ein Skript asynchron nach einer bestimmten Zeit ausführen.

Diese Funktion kann von einem pthread aufgerufen werden und wird im Umfang des Web Workers ausgeführt, der den pthread hostet. Um eine Funktion im Umfang des Hauptlaufzeit-Threads auszuwerten, siehe die Funktion emscripten_sync_run_in_main_runtime_thread().

Parameter

  • script (const char*) – Das auszuwertende Skript.

  • millis (int) – Die Zeitspanne in Millisekunden, bevor das Skript ausgeführt wird.

Rückgabetyp

void

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

Lädt ein Skript asynchron von einer URL.

Dies integriert sich in das Run-Dependencies-System, sodass Ihr Skript addRunDependency mehrmals aufrufen, verschiedene asynchrone Aufgaben vorbereiten und removeRunDependency für diese aufrufen kann; wenn alle abgeschlossen sind (oder wenn es von Anfang an keine Run-Dependencies gab), wird onload aufgerufen. Ein Beispiel hierfür ist das Laden eines Asset-Moduls, d.h. die Ausgabe des Dateipackagers.

Diese Funktion ist derzeit nur im Haupt-Browserthread verfügbar und schlägt sofort fehl, indem sie den bereitgestellten onerror()-Handler aufruft, wenn sie in einem pthread aufgerufen wird.

Parameter

  • script (const char*) – Das auszuwertende Skript.

  • onload (em_callback_func) – Eine Callback-Funktion ohne Parameter, die ausgeführt wird, wenn das Skript vollständig geladen wurde.

  • onerror (em_callback_func) – Eine Callback-Funktion ohne Parameter, die ausgeführt wird, wenn beim Laden ein Fehler auftritt.

Rückgabetyp

void

Browser-Ausführungsumgebung

Anleitungsmaterial für die folgenden APIs finden Sie unter Emscripten-Laufzeitumgebung.

Funktionen

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

Setzt eine C-Funktion als Hauptereignisschleife für den aufrufenden Thread.

Wenn die Hauptschleifenfunktion benutzerdefinierte Daten empfangen muss, verwenden Sie stattdessen emscripten_set_main_loop_arg().

Die JavaScript-Umgebung ruft diese Funktion mit einer bestimmten Anzahl von Bildern pro Sekunde auf. Wenn im Haupt-Browser-Thread aufgerufen wird, verwendet das Setzen von 0 oder einem negativen Wert als fps den requestAnimationFrame-Mechanismus des Browsers, um die Hauptschleifenfunktion aufzurufen. Dies ist SEHR empfehlenswert, wenn Sie Rendering durchführen, da der requestAnimationFrame des Browsers sicherstellt, dass Sie mit einer angemessenen, flüssigen Rate rendern, die sich richtig an den Browser und Monitor anpasst. Wenn Sie in Ihrer Anwendung überhaupt nicht rendern, sollten Sie eine bestimmte Bildrate wählen, die für Ihren Code sinnvoll ist.

Wenn simulate_infinite_loop true ist, wirft die Funktion eine Ausnahme, um die Ausführung des Aufrufers zu stoppen. Dies führt dazu, dass die Hauptschleife betreten wird, anstatt dass Code nach dem Aufruf von emscripten_set_main_loop() ausgeführt wird, was der Simulation einer unendlichen Schleife am nächsten kommt (wir machen etwas Ähnliches in glutMainLoop in GLUT). Wenn dieser Parameter false ist, ist das Verhalten dasselbe wie vor der Hinzufügung dieses Parameters zur API, nämlich dass die Ausführung normal fortgesetzt wird. Beachten Sie, dass in beiden Fällen keine globalen Destruktoren, atexit usw. ausgeführt werden, da wir wissen, dass die Hauptschleife weiterhin läuft, aber wenn wir keine unendliche Schleife simulieren, wird der Stack abgewickelt. Das bedeutet, dass, wenn simulate_infinite_loop false ist und Sie ein Objekt auf dem Stack erstellt haben, es bereinigt wird, bevor die Hauptschleife zum ersten Mal aufgerufen wird.

Diese Funktion kann in einem pthread aufgerufen werden, wobei die Callback-Schleife so eingerichtet wird, dass sie im Kontext des aufrufenden Threads aufgerufen wird. Damit die Schleife funktioniert, muss der aufrufende Thread regelmäßig durch Beenden seiner pthread-Hauptfunktion an den Browser "zurückgeben", da der Callback nur ausgeführt werden kann, wenn der aufrufende Thread keinen anderen Code ausführt. Dies bedeutet, dass die Ausführung einer synchron blockierenden Hauptschleife nicht mit der Funktion emscripten_set_main_loop() kompatibel ist.

Da die requestAnimationFrame()-API in Web-Workern nicht verfügbar ist, wird, wenn emscripten_set_main_loop() in einem pthread mit fps <= 0 aufgerufen wird, der Effekt der Synchronisierung mit der Bildwiederholfrequenz des Displays emuliert und stimmt im Allgemeinen nicht genau mit den Vsync-Intervallen überein.

Tipp

Es kann pro Thread nur eine Hauptschleifenfunktion gleichzeitig geben. Um die Hauptschleifenfunktion zu ändern, brechen Sie zunächst die aktuelle Schleife ab und rufen Sie dann diese Funktion auf, um eine andere festzulegen.

Hinweis

Siehe emscripten_set_main_loop_expected_blockers(), emscripten_pause_main_loop(), emscripten_resume_main_loop() und emscripten_cancel_main_loop() für Informationen über das Blockieren, Pausieren und Fortsetzen der Hauptschleife des aufrufenden Threads.

Hinweis

Der Aufruf dieser Funktion überschreibt die Wirkung aller vorherigen Aufrufe von emscripten_set_main_loop_timing() im aufrufenden Thread, indem der durch den Parameter fps angegebene Timing-Modus angewendet wird. Um einen anderen Timing-Modus für den aktuellen Thread anzugeben, rufen Sie die Funktion emscripten_set_main_loop_timing() auf, nachdem Sie die Hauptschleife eingerichtet haben.

Hinweis

Derzeit funktioniert die gleichzeitige Verwendung der neuen Wasm-Ausnahmebehandlung und simulate_infinite_loop == true in C++-Projekten, die Objekte mit Destruktoren auf dem Stack zum Zeitpunkt des Aufrufs haben, noch nicht.

Parameter

  • func (em_callback_func) – C-Funktion, die als Hauptereignisschleife für den aufrufenden Thread gesetzt werden soll.

  • fps (int) – Anzahl der Bilder pro Sekunde, mit der JavaScript die Funktion aufruft. Das Setzen von int <=0 (empfohlen) verwendet den requestAnimationFrame-Mechanismus des Browsers, um die Funktion aufzurufen.

  • simulate_infinite_loop (bool) – Wenn true, wirft diese Funktion eine Ausnahme, um die Ausführung des Aufrufers zu stoppen.

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

Setzt eine C-Funktion als Hauptereignisschleife für den aufrufenden Thread und übergibt ihr benutzerdefinierte Daten.

Siehe auch

Die Informationen in emscripten_set_main_loop() gelten auch für diese Funktion.

Parameter

  • func (em_arg_callback_func) – C-Funktion, die als Hauptereignisschleife gesetzt werden soll. Die Funktionssignatur muss einen void*-Parameter für die Übergabe des arg-Wertes haben.

  • arg (void*) – Benutzerdefinierte Daten, die an die Hauptschleifenfunktion übergeben werden, unverändert von der API selbst.

  • fps (int) – Anzahl der Bilder pro Sekunde, mit der JavaScript die Funktion aufruft. Das Setzen von int <=0 (empfohlen) verwendet den requestAnimationFrame-Mechanismus des Browsers, um die Funktion aufzurufen.

  • simulate_infinite_loop (bool) – Wenn true, wirft diese Funktion eine Ausnahme, um die Ausführung des Aufrufers zu stoppen.

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)

Fügt eine Funktion hinzu, die die Hauptschleife für den aufrufenden Thread blockiert.

Die Funktion wird am Ende einer Warteschlange von Ereignissen hinzugefügt, die blockiert werden sollen; die Hauptschleife wird erst ausgeführt, wenn alle Blocker in der Warteschlange abgeschlossen sind.

In der "gezählten" Version werden Blocker (intern) gezählt und Module.setStatus wird mit einem Text aufgerufen, um den Fortschritt zu melden (setStatus ist ein allgemeiner Hook, den ein Programm definieren kann, um Verarbeitungsaktualisierungen anzuzeigen).

Hinweis

  • Hauptschleifenblocker verhindern, dass die Hauptschleife läuft, und können gezählt werden, um den Fortschritt anzuzeigen. Im Gegensatz dazu werden emscripten_async_calls nicht gezählt, blockieren die Hauptschleife nicht und können zu einem bestimmten Zeitpunkt in der Zukunft ausgelöst werden.

Parameter

  • func (em_arg_callback_func) – Die Hauptschleifenblockerfunktion. Die Funktionssignatur muss einen void*-Parameter für die Übergabe des arg-Wertes haben.

  • arg (void*) – Benutzerdefinierte Argumente, die an die Blockerfunktion übergeben werden sollen.

Rückgabetyp

void

void emscripten_pause_main_loop(void)
void emscripten_resume_main_loop(void)

Pausiert und setzt die Hauptschleife für den aufrufenden Thread fort.

Das Pausieren und Fortsetzen der Hauptschleife ist nützlich, wenn Ihre App eine synchrone Operation ausführen muss, zum Beispiel um eine Datei aus dem Netzwerk zu laden. Es könnte falsch sein, die Hauptschleife vor dem Abschluss dieser Operation auszuführen (der ursprüngliche Code geht davon aus), daher können Sie den Code in asynchrone Callbacks aufteilen, aber Sie müssen die Hauptschleife pausieren, bis diese abgeschlossen sind.

Hinweis

Dies sind ziemlich niedrigstufige Funktionen. emscripten_push_main_loop_blocker() (und Verwandte) bieten bequemere Alternativen.

void emscripten_cancel_main_loop(void)

Bricht die Hauptereignisschleife für den aufrufenden Thread ab.

Siehe auch emscripten_set_main_loop() und emscripten_set_main_loop_arg() für Informationen zum Einrichten und Verwenden der Hauptschleife.

Hinweis

Diese Funktion bricht die Hauptschleife ab, was bedeutet, dass sie nicht mehr aufgerufen wird. Es treten keine weiteren Änderungen am Kontrollfluss auf. Insbesondere wenn Sie die Hauptschleife mit der Option simulate_infinite_loop gestartet haben, können Sie die Hauptschleife weiterhin abbrechen, aber die Ausführung wird im Code direkt nach dem Setzen der Hauptschleife nicht fortgesetzt (wir führen dort tatsächlich keine unendliche Schleife aus – das ist in JavaScript nicht möglich, um eine unendliche Schleife zu simulieren, halten wir die Ausführung in diesem Stadium an, und das nächste, was ausgeführt wird, ist die Hauptschleife selbst, so dass es so aussieht, als ob dort eine unendliche Schleife begonnen hätte; das Abbrechen der Hauptschleife bricht die Metapher sozusagen)..

int emscripten_set_main_loop_timing(int mode, int value)

Gibt den Planungsmodus an, mit dem die Taktfunktion der Hauptschleife des aufrufenden Threads aufgerufen wird.

Diese Funktion kann verwendet werden, um die Rate interaktiv zu steuern, mit der die Emscripten-Laufzeit die durch den Aufruf der Funktion emscripten_set_main_loop() angegebene Hauptschleife steuert. In der nativen Entwicklung entspricht dies dem "Swap-Intervall" oder dem "Präsentationsintervall" für 3D-Rendering. Das neue, durch diese Funktion angegebene Taktintervall wird sofort auf die bestehende Hauptschleife angewendet, und diese Funktion darf nur nach dem Einrichten einer Hauptschleife über emscripten_set_main_loop() aufgerufen werden.

Param int mode

Der zu verwendende Timing-Modus. Zulässige Werte sind EM_TIMING_SETTIMEOUT, EM_TIMING_RAF und EM_TIMING_SETIMMEDIATE.

Parameter

  • value (int) –

    Der zu aktivierende Timing-Wert für die Hauptschleife. Dieser Wert wird je nach mode-Parameter unterschiedlich interpretiert.

    • Wenn mode EM_TIMING_SETTIMEOUT ist, dann gibt value die Anzahl der Millisekunden an, die zwischen aufeinanderfolgenden Ticks der Hauptschleife gewartet werden soll, und Aktualisierungen erfolgen unabhängig von der Vsync-Rate des Displays (Vsync aus). Diese Methode verwendet die JavaScript-Funktion setTimeout, um die Animation zu steuern.

    • Wenn mode EM_TIMING_RAF ist, werden Updates mit der Funktion requestAnimationFrame (mit aktiviertem Vsync) durchgeführt, und dieser Wert wird als "Swap-Intervall"-Rate für die Hauptschleife interpretiert. Der Wert 1 gibt der Laufzeit an, dass sie bei jedem Vsync rendern soll (typischerweise 60fps), während der Wert 2 bedeutet, dass der Hauptschleifen-Callback nur bei jedem zweiten Vsync (30fps) aufgerufen werden sollte. Als allgemeine Formel bedeutet der Wert n, dass die Hauptschleife bei jedem n-ten Vsync aktualisiert wird, oder mit einer Rate von 60/n für 60Hz-Displays und 120/n für 120Hz-Displays.

    • Wenn mode EM_TIMING_SETIMMEDIATE ist, werden Updates mit der Funktion setImmediate durchgeführt, oder, falls nicht verfügbar, via postMessage emuliert. Weitere Informationen finden Sie unter setImmediate auf MDN <https://developer.mozilla.org/en-US/docs/Web/API/Window/setImmediate>. Beachten Sie, dass dieser Modus dringend nicht empfohlen wird, wenn Emscripten-Ausgaben im Web bereitgestellt werden, da er von einer instabilen Web-Erweiterung abhängt, die sich im Entwurfsstatus befindet, von Browsern außer IE derzeit nicht unterstützt wird und seine Implementierung in der Überprüfung als kontrovers angesehen wurde.

Rückgabetyp

int

Gibt zurück

Bei Erfolg wird der Wert 0 zurückgegeben, bei Fehler ein Wert ungleich Null. Ein Fehler tritt auf, wenn vor dem Aufruf dieser Funktion keine Hauptschleife aktiv ist.

Hinweis

Browser optimieren stark auf die Verwendung von requestAnimationFrame für Animationen anstelle der anderen bereitgestellten Modi. Aus diesem Grund liefert der Aufruf dieser Funktion mit mode=EM_TIMING_RAF und value=1 die besten Ergebnisse für eine optimale Erfahrung in verschiedenen Browsern. Die Verwendung der JavaScript-Funktion setTimeout führt bekanntermaßen zu Stottern und einer generell schlechteren Erfahrung als die Verwendung der Funktion requestAnimationFrame.

Hinweis

Es gibt einen funktionalen Unterschied zwischen setTimeout und requestAnimationFrame: Wenn der Benutzer das Browserfenster minimiert oder den Anwendungs-Tab ausblendet, stoppen Browser typischerweise das Aufrufen von requestAnimationFrame-Callbacks, aber die setTimeout-basierte Hauptschleife wird weiterhin ausgeführt, wenn auch mit stark gedrosselten Intervallen. Weitere Informationen finden Sie unter setTimeout auf MDN <https://developer.mozilla.org/en-US/docs/Web/API/WindowTimers.setTimeout#Inactive_tabs>.

void emscripten_get_main_loop_timing(int *mode, int *value)

Gibt den aktuell wirksamen Hauptschleifen-Timing-Modus zurück. Zur Interpretation der Werte siehe die Dokumentation der Funktion emscripten_set_main_loop_timing(). Der Timing-Modus wird durch Aufrufen der Funktionen emscripten_set_main_loop_timing() und emscripten_set_main_loop() gesteuert.

Parameter Modus

Wenn nicht null, wird der verwendete Timing-Modus hier zurückgegeben.

Typ Modus

int*

Parameterwert

Wenn nicht null, wird der verwendete Timing-Wert hier zurückgegeben.

Typwert

int*

void emscripten_set_main_loop_expected_blockers(int num)

Setzt die Anzahl der Blocker, die gleich gepusht werden sollen.

Die Zahl wird verwendet, um den relativen Fortschritt durch eine Reihe von Blockern zu melden, danach wird die Hauptschleife fortgesetzt.

Zum Beispiel muss ein Spiel möglicherweise 10 Blocker ausführen, bevor ein neues Level gestartet wird. Die Operation würde diesen Wert zuerst auf '10' setzen und dann die 10 Blocker pushen. Wenn der 3. Blocker (sagen wir) abgeschlossen ist, wird der Fortschritt als 3/10 angezeigt.

Parameter

  • num (int) – Die Anzahl der Blocker, die gleich gepusht werden sollen.

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

Ruft eine C-Funktion asynchron auf, d.h. nachdem die Kontrolle an die JavaScript-Ereignisschleife zurückgegeben wurde.

Dies geschieht durch ein setTimeout.

Beim nativen Erstellen wird dies zu einem einfachen direkten Aufruf, nach SDL_Delay (Sie müssen dafür SDL.h einbinden).

Wenn millis negativ ist, wird der requestAnimationFrame-Mechanismus des Browsers verwendet. (Beachten Sie, dass 0 bedeutet, dass setTimeout immer noch verwendet wird, was im Grunde "asynchron so schnell wie möglich ausführen" bedeutet.)

Parameter

  • func (em_arg_callback_func) – Die C-Funktion, die asynchron aufgerufen werden soll. Die Funktionssignatur muss einen void*-Parameter für die Übergabe des arg-Wertes haben.

  • arg (void*) – Benutzerdefiniertes Argument, das an die C-Funktion übergeben werden soll.

  • millis (int) – Timeout, bevor die Funktion aufgerufen wird.

void emscripten_exit_with_live_runtime(void)

Stoppt den aktuellen Ausführungsthread, lässt aber die Laufzeit am Leben, sodass Sie später Code weiter ausführen können (globale Destruktoren usw. werden also nicht ausgeführt). Beachten Sie, dass die Laufzeit automatisch am Leben erhalten wird, wenn Sie eine asynchrone Operation wie emscripten_async_call() durchführen, sodass Sie diese Funktion in diesen Fällen nicht aufrufen müssen.

In einer Multithread-Anwendung beendet dies nur den aktuellen Thread (und ermöglicht das spätere Ausführen von Code im Web Worker, in dem er läuft).

void emscripten_force_exit(int status)

Beendet die Laufzeit und das Programm, als ob Sie exit() aufgerufen hätten.

Der Unterschied besteht darin, dass emscripten_force_exit die Laufzeit beendet, selbst wenn Sie zuvor emscripten_exit_with_live_runtime() aufgerufen oder die Laufzeit anderweitig am Leben erhalten haben. Mit anderen Worten, diese Methode gibt Ihnen die Möglichkeit, die Laufzeit vollständig zu beenden, nachdem sie über den Abschluss von main() hinaus am Leben erhalten wurde.

Beachten Sie, dass, wenn EXIT_RUNTIME nicht gesetzt ist (was standardmäßig der Fall ist), die Laufzeit nicht beendet werden kann, da wir den Code dazu nicht enthalten. Erstellen Sie mit -sEXIT_RUNTIME, wenn Sie die Laufzeit beenden können möchten.

Parameter

  • status (int) – Dasselbe wie für die libc-Funktion exit().

double emscripten_get_device_pixel_ratio(void)

Gibt den Wert von window.devicePixelRatio zurück.

Rückgabetyp

double

Gibt zurück

Das Pixelverhältnis oder 1.0, falls nicht unterstützt.

char *emscripten_get_window_title()

Gibt den Fenstertitel zurück.

Der zurückgegebene String ist bis zum nächsten Aufruf der Funktion gültig

void emscripten_set_window_title(char *title)

Setzt den Fenstertitel.

void emscripten_get_screen_size(int *width, int *height)

Gibt die Breite und Höhe des Bildschirms zurück.

void emscripten_hide_mouse(void)

Versteckt den Mauszeiger des Betriebssystems über dem Canvas.

Beachten Sie, dass der Befehl SDL_ShowCursor von SDL den SDL-Cursor anzeigt und versteckt, nicht den des Betriebssystems. Dieser Befehl ist nützlich, um den Betriebssystem-Cursor auszublenden, wenn Ihre App einen eigenen Cursor zeichnet.

double emscripten_get_now(void)

Gibt die präziseste Darstellung der aktuellen Zeit zurück, die der Browser bietet.

Dies verwendet entweder Date.now oder performance.now. Das Ergebnis ist keine absolute Zeit und ist nur im Vergleich zu anderen Aufrufen dieser Funktion aussagekräftig.

Rückgabetyp

double

Gibt zurück

Die aktuelle Zeit in Millisekunden (ms).

float emscripten_random(void)

Generiert eine Zufallszahl im Bereich 0-1. Dies entspricht Math.random().

Rückgabetyp

float

Gibt zurück

Eine Zufallszahl.

Asynchrone Dateisystem-API

Typedefs

em_async_wget_onload_func

Funktionszeigertyp für den onload-Callback von emscripten_async_wget_data() (spezifische Werte der Parameter in dieser Methode dokumentiert).

Definiert als

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

Funktionszeigertyp für den onload-Callback von emscripten_async_wget2() (spezifische Werte der Parameter in dieser Methode dokumentiert).

Definiert als

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

Funktionszeigertyp für die onerror- und onprogress-Callbacks von emscripten_async_wget2() (spezifische Werte der Parameter in dieser Methode dokumentiert).

Definiert als

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

Funktionszeigertyp für den onload-Callback von emscripten_async_wget2_data() (spezifische Werte der Parameter in dieser Methode dokumentiert).

Definiert als

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

Funktionszeigertyp für den onerror-Callback von emscripten_async_wget2_data() (spezifische Werte der Parameter in dieser Methode dokumentiert).

Definiert als

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

Funktionszeigertyp für den onprogress-Callback von emscripten_async_wget2_data() (spezifische Werte der Parameter in dieser Methode dokumentiert).

Definiert als

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

Funktionszeigertyp für den onload-Callback von emscripten_run_preload_plugins_data() (spezifische Werte der Parameter in dieser Methode dokumentiert).

Definiert als

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

Funktionen

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

Lädt eine Datei asynchron von einer URL.

Zusätzlich zum Abrufen der URL aus dem Netzwerk werden Preload-Plugins ausgeführt, sodass die Daten in IMG_Load usw. verwendbar sind (wir führen die Arbeit asynchron aus, damit der Browser das Bild oder Audio usw. dekodiert). Weitere Informationen zum Vorladen von Dateien finden Sie unter Vorladen von Dateien.

Wenn die Datei bereit ist, wird der onload-Callback aufgerufen. Tritt ein Fehler auf, wird onerror aufgerufen. Die Callbacks werden mit der Datei als Argument aufgerufen.

Parameter

  • char* url (const) – Die zu ladende URL.

  • char* file (const) – Der Name der Datei, die aus der URL erstellt und geladen wurde. Wenn die Datei bereits existiert, wird sie überschrieben. Wenn das Zielverzeichnis für die Datei im Dateisystem nicht existiert, wird es erstellt. Es kann ein relativer Pfadname übergeben werden, der relativ zum aktuellen Arbeitsverzeichnis zum Zeitpunkt des Aufrufs dieser Funktion interpretiert wird.

  • onload (em_str_callback_func) –

    Callback bei erfolgreichem Laden der Datei. Der Parameterwert der Callback-Funktion ist

    • *(const char*) : Der Name der file, die von der URL geladen wurde.

  • onerror (em_str_callback_func) –

    Callback im Fehlerfall. Der Parameterwert der Callback-Funktion ist

    • *(const char*) : Der Name der file, die von der URL nicht geladen werden konnte.

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

Lädt einen Puffer asynchron von einer URL.

Dies ist die "Daten"-Version von emscripten_async_wget().

Anstatt in eine Datei zu schreiben, schreibt diese Funktion direkt in einen Puffer im Speicher. Dies vermeidet den Overhead der Verwendung des emulierten Dateisystems; beachten Sie jedoch, dass, da keine Dateien verwendet werden, keine Preload-Plugins ausgeführt werden können, um Dinge für IMG_Load usw. einzurichten (IMG_Load usw. arbeiten mit Dateien).

Wenn die Datei bereit ist, wird der onload-Callback aufgerufen. Tritt ein Fehler auf, wird onerror aufgerufen.

Parameter

  • url (const char*) – Die URL der zu ladenden Datei.

  • arg (void*) – Benutzerdefinierte Daten, die an die Callbacks übergeben werden, unverändert von der API selbst. Dies kann von einem Callback verwendet werden, um den zugehörigen Aufruf zu identifizieren.

  • onload (em_async_wget_onload_func) –

    Callback bei erfolgreichem Laden der URL in den Puffer. Die Parameterwerte der Callback-Funktion sind

    • *(void*) : Gleich arg (benutzerdefinierte Daten).

    • *(void*) : Ein Zeiger auf einen Puffer mit den Daten. Beachten Sie, dass, wie bei der Worker-API, der Datenpuffer nur während des Callbacks existiert; er muss während dieser Zeit verwendet oder kopiert werden.

    • *(int) : Die Größe des Puffers in Bytes.

  • onerror (em_arg_callback_func) –

    Callback im Fehlerfall. Die Parameterwerte der Callback-Funktion sind

    • *(void*) : Gleich arg (benutzerdefinierte Daten).

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)

Lädt eine Datei asynchron von einer URL.

Dies ist eine experimentelle "feature-reichere" Version von emscripten_async_wget().

Preload-Plug-ins werden zum jetzigen Zeitpunkt nicht auf die heruntergeladenen Daten angewendet. Sie können emscripten_run_preload_plugins() im onload-Callback aufrufen, wenn Sie die heruntergeladene Datei mit IMG_Load und Ähnlichem verwenden möchten.

Wenn die Datei bereit ist, wird der onload-Callback mit den in arg und file angegebenen Objektzeigern aufgerufen. Während des Downloads wird der onprogress-Callback aufgerufen.

Parameter

  • url (const char*) – Die URL der zu ladenden Datei.

  • file (const char*) – Der Name der Datei, die aus der URL erstellt und geladen wurde. Wenn die Datei bereits existiert, wird sie überschrieben. Wenn das Zielverzeichnis für die Datei im Dateisystem nicht existiert, wird es erstellt. Es kann ein relativer Pfadname übergeben werden, der relativ zum aktuellen Arbeitsverzeichnis zum Zeitpunkt des Aufrufs dieser Funktion interpretiert wird.

  • requesttype (const char*) – 'GET' oder 'POST'.

  • param (const char*) – Anfrageparameter für POST-Anfragen (siehe requesttype). Die Parameter werden auf die gleiche Weise angegeben, wie sie in der URL für eine entsprechende GET-Anfrage wären: z.B. key=value&key2=value2.

  • arg (void*) – Benutzerdefinierte Daten, die an die Callbacks übergeben werden, unverändert von der API selbst. Dies kann von einem Callback verwendet werden, um den zugehörigen Aufruf zu identifizieren.

  • onload (em_async_wget2_onload_func) –

    Callback bei erfolgreichem Laden der Datei. Die Parameterwerte der Callback-Funktion sind

    • *(void*) : Gleich arg (benutzerdefinierte Daten).

    • *(const char*) : Die file, die dem ursprünglichen Aufruf übergeben wurde.

  • onerror (em_async_wget2_onstatus_func) –

    Callback im Fehlerfall. Die Parameterwerte der Callback-Funktion sind

    • *(void*) : Gleich arg (benutzerdefinierte Daten).

    • *(int) : Der HTTP-Statuscode.

  • onprogress (em_async_wget2_onstatus_func) –

    Callback während des Ladevorgangs der Datei. Die Parameterwerte der Callback-Funktion sind

    • *(void*) : Gleich arg (benutzerdefinierte Daten).

    • *(int) : Der Fortschritt (Prozentsatz abgeschlossen).

Gibt zurück

Ein Handle zum Anfordern (int), das zum Abbrechen der Anforderung verwendet werden kann.

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)

Lädt einen Puffer asynchron von einer URL.

Dies ist die "Daten"-Version von emscripten_async_wget2(). Es ist eine experimentelle "feature-reichere" Version von emscripten_async_wget_data().

Anstatt in eine Datei zu schreiben, schreibt diese Funktion direkt in einen Puffer im Speicher. Dies vermeidet den Overhead der Verwendung des emulierten Dateisystems; beachten Sie jedoch, dass, da keine Dateien verwendet werden, keine Preload-Plugins ausgeführt werden können, um Dinge für IMG_Load usw. einzurichten (IMG_Load usw. arbeiten mit Dateien).

Wenn die Datei bereit ist, wird der onload-Callback mit den in arg angegebenen Objektzeigern, einem Zeiger auf den Puffer im Speicher und einer vorzeichenlosen Ganzzahl, die die Größe des Puffers enthält, aufgerufen. Während des Downloads wird der onprogress-Callback mit Fortschrittsinformationen aufgerufen. Wenn ein Fehler auftritt, wird onerror mit dem HTTP-Statuscode und einem String mit der Statusbeschreibung aufgerufen.

Parameter

  • url (const char*) – Die URL der zu ladenden Datei.

  • requesttype (const char*) – 'GET' oder 'POST'.

  • param (const char*) – Anfrageparameter für POST-Anfragen (siehe requesttype). Die Parameter werden auf die gleiche Weise angegeben, wie sie in der URL für eine entsprechende GET-Anfrage wären: z.B. key=value&key2=value2.

  • arg (void*) – Benutzerdefinierte Daten, die an die Callbacks übergeben werden, unverändert von der API selbst. Dies kann von einem Callback verwendet werden, um den zugehörigen Aufruf zu identifizieren.

  • free (int) – Teilt der Laufzeit mit, ob der zurückgegebene Puffer nach Abschluss von onload freigegeben werden soll. Wenn false, ist die Freigabe des Puffers die Verantwortung des Empfängers.

  • onload (em_async_wget2_data_onload_func) –

    Callback bei erfolgreichem Laden der Datei. Die Parameterwerte der Callback-Funktion sind

    • *(unsigned) : Handle zur Anfrage

    • *(void*) : Gleich arg (benutzerdefinierte Daten).

    • *(void*) : Ein Zeiger auf den Puffer im Speicher.

    • *(unsigned) : Die Größe des Puffers (in Bytes).

  • onerror (em_async_wget2_data_onerror_func) –

    Callback im Fehlerfall. Die Parameterwerte der Callback-Funktion sind

    • *(unsigned) : Handle zur Anfrage

    • *(void*) : Gleich arg (benutzerdefinierte Daten).

    • *(int) : Der HTTP-Fehlercode.

    • *(const char*) : Ein String mit der Statusbeschreibung.

  • onprogress (em_async_wget2_data_onprogress_func) –

    Callback, der (regelmäßig) während des Ladevorgangs der Datei aufgerufen wird, um den Fortschritt zu aktualisieren. Die Parameterwerte der Callback-Funktion sind

    • *(unsigned) : Handle zur Anfrage

    • *(void*) : Gleich arg (benutzerdefinierte Daten).

    • *(int) : Die Anzahl der geladenen Bytes.

    • *(int) : Die Gesamtgröße der Daten in Bytes, oder Null, wenn die Größe nicht verfügbar ist.

Gibt zurück

Ein Handle zum Anfordern (int), das zum Abbrechen der Anforderung verwendet werden kann.

void emscripten_async_wget2_abort(int handle)

Bricht eine asynchrone Anfrage ab, die mit emscripten_async_wget2() oder emscripten_async_wget2_data() ausgelöst wurde.

Parameter

  • handle (int) – Ein Handle zur abzubrechenden Anfrage.

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)

Führt Preload-Plugins asynchron auf einem Datenpuffer aus. Dies ist eine "Daten"-Version von emscripten_run_preload_plugins(), die Rohdaten als Eingabe anstelle eines Dateinamens erhält (dies kann die Notwendigkeit vermeiden, Daten zuerst in eine Datei zu schreiben). Weitere Informationen zu Preload-Plugins finden Sie unter Vorladen von Dateien.

Wenn die Datei geladen ist, wird der onload-Callback aufgerufen. Tritt ein Fehler auf, wird onerror aufgerufen.

onload empfängt auch einen zweiten Parameter, der ein "fiktiver" Dateiname ist, den Sie an IMG_Load übergeben können (es ist keine tatsächliche Datei, aber er identifiziert dieses Bild, damit IMG_Load es verarbeiten kann). Beachten Sie, dass der Benutzer dieser API dafür verantwortlich ist, den für den fiktiven Dateinamen zugewiesenen Speicher mit free() freizugeben.

Parameter

  • data (char*) – Der zu verarbeitende Datenpuffer.

  • suffix (const char*) – Das Dateisuffix, z.B. 'png' oder 'jpg'.

  • arg (void*) – Benutzerdefinierte Daten, die an die Callbacks übergeben werden, unverändert von der API selbst. Dies kann von einem Callback verwendet werden, um den zugehörigen Aufruf zu identifizieren.

  • onload (em_run_preload_plugins_data_onload_func) –

    Callback bei erfolgreicher Verarbeitung der Daten. Die Parameterwerte der Callback-Funktion sind

    • *(void*) : Gleich arg (benutzerdefinierte Daten).

    • *(const char*) : Ein "fiktiver" Dateiname, den Sie an IMG_Load übergeben können. Weitere Informationen finden Sie oben.

  • onerror (em_arg_callback_func) –

    Callback im Fehlerfall. Der Parameterwert der Callback-Funktion ist

    • *(void*) : Gleich arg (benutzerdefinierte Daten).

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

Startet einen asynchronen dlopen-Vorgang, um eine gemeinsam genutzte Bibliothek von einem Dateinamen oder einer URL zu laden. Kehrt sofort zurück und erfordert, dass der Aufrufer zur Ereignisschleife zurückkehrt. Die Callbacks onsuccess und onerror werden verwendet, um Erfolg oder Misserfolg der Anforderung zu signalisieren. Bei einem onerror-Callback kann die normale C-Funktion dlerror verwendet werden, um die Fehlerdetails zu erhalten. Die Flags sind dieselben wie die, die in der normalen C-Funktion dlopen verwendet werden.

Parameter

  • char* filename (const) – Der Dateiname (oder URLs) der zu ladenden gemeinsam genutzten Bibliothek.

  • flags (int) – Siehe dlopen-Flags.

  • user_data (void*) – Benutzerdaten, die an die onsuccess- und onerror-Callbacks übergeben werden.

  • onsuccess (em_dlopen_callback) – Wird aufgerufen, wenn die Bibliothek erfolgreich geladen wurde.

  • onerror (em_arg_callback_func) – Wird aufgerufen, wenn beim Laden der Bibliothek ein Fehler auftrat.

Asynchrone IndexedDB-API

IndexedDB ist eine Browser-API, die es Ihnen ermöglicht, Daten persistent zu speichern, d.h. Sie können Daten dort speichern und später laden, wenn der Benutzer die Webseite erneut besucht. IDBFS bietet eine Möglichkeit, IndexedDB über die Emscripten-Dateisystemschicht zu verwenden. Die hier aufgeführten emscripten_idb_*-Methoden bieten eine alternative API, direkt zu IndexedDB, wodurch der Overhead der Dateisystemschicht vermieden wird.

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)

Lädt Daten asynchron aus dem lokalen IndexedDB-Speicher. Dies ermöglicht die Nutzung persistenter Daten ohne den Overhead der Dateisystemschicht.

Wenn die Daten bereit sind, wird der onload-Callback aufgerufen. Tritt ein Fehler auf, wird onerror aufgerufen.

Parameter

  • db_name – Die IndexedDB-Datenbank, aus der geladen werden soll.

  • file_id – Der Bezeichner der zu ladenden Daten.

  • arg (void*) – Benutzerdefinierte Daten, die an die Callbacks übergeben werden, unverändert von der API selbst. Dies kann von einem Callback verwendet werden, um den zugehörigen Aufruf zu identifizieren.

  • onload (em_async_wget_onload_func) –

    Callback bei erfolgreichem Laden der URL in den Puffer. Die Parameterwerte der Callback-Funktion sind

    • *(void*) : Gleich arg (benutzerdefinierte Daten).

    • *(void*) : Ein Zeiger auf einen Puffer mit den Daten. Beachten Sie, dass, wie bei der Worker-API, der Datenpuffer nur während des Callbacks existiert; er muss während dieser Zeit verwendet oder kopiert werden.

    • *(int) : Die Größe des Puffers in Bytes.

  • onerror (em_arg_callback_func) –

    Callback im Fehlerfall. Die Parameterwerte der Callback-Funktion sind

    • *(void*) : Gleich arg (benutzerdefinierte Daten).

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

Speichert Daten asynchron in den lokalen IndexedDB-Speicher. Dies ermöglicht die Verwendung persistenter Daten ohne den Overhead der Dateisystemschicht.

Wenn die Daten gespeichert wurden, wird der onstore-Rückruf aufgerufen. Wenn ein Fehler auftritt, wird onerror aufgerufen.

Parameter

  • db_name – Die IndexedDB-Datenbank, aus der geladen werden soll.

  • file_id – Der Bezeichner der zu ladenden Daten.

  • ptr – Ein Zeiger auf die zu speichernden Daten.

  • num – Die Anzahl der zu speichernden Bytes.

  • arg (void*) – Benutzerdefinierte Daten, die an die Callbacks übergeben werden, unverändert von der API selbst. Dies kann von einem Callback verwendet werden, um den zugehörigen Aufruf zu identifizieren.

  • onstore (em_arg_callback_func) –

    Rückruf bei erfolgreicher Speicherung des Datenpuffers in der URL. Die Parameterwerte der Rückruffunktion sind

    • *(void*) : Gleich arg (benutzerdefinierte Daten).

  • onerror (em_arg_callback_func) –

    Callback im Fehlerfall. Die Parameterwerte der Callback-Funktion sind

    • *(void*) : Gleich arg (benutzerdefinierte Daten).

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)

Löscht Daten asynchron aus dem lokalen IndexedDB-Speicher.

Wenn die Daten gelöscht wurden, wird der ondelete-Rückruf aufgerufen. Wenn ein Fehler auftritt, wird onerror aufgerufen.

Parameter

  • db_name – Die IndexedDB-Datenbank.

  • file_id – Der Bezeichner der Daten.

  • arg (void*) – Benutzerdefinierte Daten, die an die Callbacks übergeben werden, unverändert von der API selbst. Dies kann von einem Callback verwendet werden, um den zugehörigen Aufruf zu identifizieren.

  • ondelete (em_arg_callback_func) –

    Rückruf bei erfolgreicher Löschung

    • *(void*) : Gleich arg (benutzerdefinierte Daten).

  • onerror (em_arg_callback_func) –

    Callback im Fehlerfall. Die Parameterwerte der Callback-Funktion sind

    • *(void*) : Gleich arg (benutzerdefinierte Daten).

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)

Prüft asynchron, ob Daten mit einer bestimmten ID im lokalen IndexedDB-Speicher vorhanden sind.

Wenn die Daten überprüft wurden, wird der oncheck-Rückruf aufgerufen. Wenn ein Fehler auftritt, wird onerror aufgerufen.

Parameter

  • db_name – Die IndexedDB-Datenbank.

  • file_id – Der Bezeichner der Daten.

  • arg (void*) – Benutzerdefinierte Daten, die an die Callbacks übergeben werden, unverändert von der API selbst. Dies kann von einem Callback verwendet werden, um den zugehörigen Aufruf zu identifizieren.

  • oncheck (em_idb_exists_func) –

    Rückruf bei erfolgreicher Prüfung, mit Argumenten

    • *(void*) : Gleich arg (benutzerdefinierte Daten).

    • int : Ob die Datei existiert oder nicht.

  • onerror (em_arg_callback_func) –

    Callback im Fehlerfall. Die Parameterwerte der Callback-Funktion sind

    • *(void*) : Gleich arg (benutzerdefinierte Daten).

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

Löscht asynchron alle Daten aus dem lokalen IndexedDB-Speicher.

Wenn der Speicher geleert wurde, wird der onclear-Rückruf aufgerufen. Wenn ein Fehler auftritt, wird onerror aufgerufen.

Parameter

  • db_name – Die IndexedDB-Datenbank.

  • arg (void*) – Benutzerdefinierte Daten, die an die Callbacks übergeben werden, unverändert von der API selbst. Dies kann von einem Callback verwendet werden, um den zugehörigen Aufruf zu identifizieren.

  • onclear (em_arg_callback_func) –

    Rückruf bei erfolgreicher Leerung. Der Parameter der Rückruffunktion ist

    • *(void*) : Gleich arg (benutzerdefinierte Daten).

  • onerror (em_arg_callback_func) –

    Rückruf im Fehlerfall. Der Parameter der Rückruffunktion ist

    • *(void*) : Gleich arg (benutzerdefinierte Daten).

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

Führt Preload-Plugins für eine Datei asynchron aus. Dies funktioniert mit bereits vorhandenen Dateidaten und führt alle erforderlichen asynchronen Operationen aus, die als Preload-Plugins verfügbar sind, wie z.B. das Dekodieren von Bildern zur Verwendung in IMG_Load oder das Dekodieren von Audio zur Verwendung in Mix_LoadWAV. Weitere Informationen zu Preload-Plugins finden Sie unter Dateien vorladen.

Sobald die Operationen abgeschlossen sind, wird der onload-Rückruf aufgerufen. Wenn ein Fehler auftritt, wird onerror aufgerufen. Die Rückrufe werden mit der Datei als Argument aufgerufen.

Parameter

  • file (const char*) – Der Name der zu verarbeitenden Datei.

  • onload (em_str_callback_func) –

    Rückruf bei erfolgreicher Verarbeitung der Datei. Der Parameterwert der Rückruffunktion ist

    • (const char)* : Der Name der file, die verarbeitet wurde.

  • onerror (em_str_callback_func) –

    Callback im Fehlerfall. Der Parameterwert der Callback-Funktion ist

    • (const char)* : Der Name der file, für die die Operation fehlgeschlagen ist.

Gibt zurück

0 bei Erfolg, -1 wenn die Datei nicht existiert

Rückgabetyp

int

Kompilieren

EMSCRIPTEN_KEEPALIVE

Weist den Compiler und Linker an, ein Symbol zu erhalten und zu exportieren, als ob Sie es zu EXPORTED_FUNCTIONS hinzugefügt hätten.

Zum Beispiel:

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

Beachten Sie, dass dies nur funktioniert, wenn die Objektdatei, in der das Symbol definiert ist, anderweitig vom Linker eingeschlossen wird. Wenn die Objektdatei Teil eines Archivs ist und nicht anderweitig referenziert wird, wird der Linker sie überhaupt nicht einschließen und alle Symbole in der Objektdatei werden nicht eingeschlossen oder exportiert. Eine Möglichkeit, diese Einschränkung zu umgehen, ist die Verwendung der Flags -Wl,--whole-archive / -Wl,--no-whole-archive auf beiden Seiten der Archivdatei.

Worker API

Typedefs

int worker_handle

Ein Wrapper um Web Worker, der es Ihnen ermöglicht, Worker zu erstellen und mit ihnen zu kommunizieren.

Beachten Sie, dass die aktuelle API hauptsächlich auf einen Haupt-Thread ausgerichtet ist, der Jobs an Worker sendet und auf Antworten wartet, d.h. asymmetrisch. Es gibt derzeit keine API, um eine Nachricht ohne Anforderung von einem Worker an den Haupt-Thread zu senden.

em_worker_callback_func

Funktionszeiger-Typ für den Rückruf von emscripten_call_worker() (spezifische Werte der Parameter sind in dieser Methode dokumentiert).

Definiert als

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

Funktionen

worker_handle emscripten_create_worker(const char * url)

Erstellt einen Worker.

Ein Worker muss separat vom Hauptprogramm und mit dem auf 1 gesetzten Flag BUILD_AS_WORKER kompiliert werden.

Dieser Worker darf nicht mit dem Flag -pthread kompiliert werden, da die POSIX-Threads-Implementierung und diese Worker-API inkompatibel sind.

Parameter

  • url (const char*) – Die URL des Worker-Skripts.

Gibt zurück

Ein Handle für den neu erstellten Worker.

Rückgabetyp

worker_handle

void emscripten_destroy_worker(worker_handle worker)

Zerstört einen Worker. Siehe emscripten_create_worker()

Parameter

  • worker (worker_handle) – Ein Handle für den zu zerstörenden Worker.

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

Ruft einen Worker asynchron auf.

Die Worker-Funktion wird mit zwei Parametern aufgerufen: einem Datenzeiger und einer Größe. Der durch Zeiger und Größe definierte Datenblock existiert nur während des Rückrufs: er kann danach nicht mehr verwendet werden. Wenn Sie einige dieser Informationen außerhalb des Rückrufs behalten müssen, müssen sie an einen sicheren Ort kopiert werden.

Die aufgerufene Worker-Funktion kann Daten zurückgeben, indem sie emscripten_worker_respond() aufruft. Wenn der Worker aufgerufen wird und ein Rückruf angegeben wurde, wird dieser mit drei Argumenten aufgerufen: einem Datenzeiger, einer Größe und einem Argument, das beim Aufruf von emscripten_call_worker() bereitgestellt wurde (um Rückrufe leichter Anrufen zuordnen zu können). Der durch den Datenzeiger und die Größe definierte Datenblock verhält sich wie der Datenblock in der Worker-Funktion – er existiert nur während des Rückrufs.

Parameter

  • worker (worker_handle) – Ein Handle für den aufzurufenden Worker.

  • funcname (const char*) – Der Name der Funktion im Worker. Die Funktion muss eine C-Funktion sein (also kein C++-Name Mangling) und muss exportiert werden (EXPORTED_FUNCTIONS).

  • data (char*) – Die Adresse eines zu kopierenden Speicherblocks.

  • size (int) – Die Größe des Speicherblocks.

  • callback (em_worker_callback_func) –

    Worker-Rückruf mit der Antwort. Dies kann null sein. Die Parameterwerte der Rückruffunktion sind

    • (char)* : Der data-Zeiger, der in emscripten_call_worker() bereitgestellt wurde.

    • (int) : Die size des Datenblocks.

    • *(void*) : Gleich arg (benutzerdefinierte Daten).

  • arg (void*) – Ein Argument (Benutzerdaten), das an den Rückruf übergeben wird

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

Sendet eine Antwort in einem Worker-Aufruf (d.h. wenn vom Hauptthread mittels emscripten_call_worker() aufgerufen).

Beide Funktionen senden eine Nachricht an den Thread zurück, der den Worker aufgerufen hat. Die Variante emscripten_worker_respond_provisionally() kann mehrfach aufgerufen werden, wodurch Nachrichten an den Ersteller des Workers gesendet werden. Schließlich muss die _respond-Variante aufgerufen werden, die weitere Nachrichten unterbindet und zuvor für diesen Worker-Aufruf zugewiesene Framework-Ressourcen freigibt.

Hinweis

Der Aufruf der provisorischen Version ist optional, aber Sie müssen die nicht-provisorische Version aufrufen, um Lecks zu vermeiden.

Parameter

  • data (char*) – Die zu sendende Nachricht.

  • size (int) – Die Größe der Nachricht in Bytes.

int emscripten_get_worker_queue_size(worker_handle worker)

Prüft, wie viele Antworten von einem Worker erwartet werden.

Dies zählt nur Aufrufe von emscripten_call_worker(), die einen Rückruf hatten (Aufrufe mit Null-Rückrufen werden ignoriert), und bei denen die Antwort noch nicht empfangen wurde. Es ist eine einfache Möglichkeit, den Status des Workers zu überprüfen, um zu sehen, wie beschäftigt er ist, und grundlegende Entscheidungen über die Drosselung zu treffen.

Parameter
Gibt zurück

Die Anzahl der von einem Worker erwarteten Antworten.

Rückgabetyp

int

Protokollierungs-Dienstprogramme

Definitionen

EM_LOG_CONSOLE

Wenn angegeben, protokolliert direkt in das Browser-Konsolen-/Inspektorfenster. Wenn nicht angegeben, protokolliert über das Anwendungsmodul.

EM_LOG_WARN

Wenn angegeben, wird eine Warnmeldung ausgegeben (kombiniert mit EM_LOG_CONSOLE).

EM_LOG_INFO

Wenn angegeben, wird eine Informationsmeldung an die Konsole ausgegeben (kombiniert mit EM_LOG_CONSOLE).

EM_LOG_DEBUG

Wenn angegeben, wird eine Debug-Meldung an die Konsole ausgegeben (kombiniert mit EM_LOG_CONSOLE).

EM_LOG_ERROR

Wenn angegeben, wird eine Fehlermeldung ausgegeben (kombiniert mit EM_LOG_CONSOLE). Wenn weder EM_LOG_WARN, EM_LOG_ERROR, EM_LOG_INFO noch EM_LOG_DEBUG angegeben ist, wird eine Logmeldung ausgegeben. EM_LOG_WARN, EM_LOG_INFO, EM_LOG_DEBUG und EM_LOG_ERROR schließen sich gegenseitig aus. Wenn EM_LOG_CONSOLE nicht angegeben ist, wird die Nachricht über err() (für EM_LOG_ERROR oder EM_LOG_WARN) oder ansonsten über out() ausgegeben.

EM_LOG_C_STACK

Wenn angegeben, wird ein Aufrufstapel ausgegeben, der Dateinamen enthält, die sich auf die ursprünglichen C-Quellen unter Verwendung von Quellkarteninformationen beziehen.

EM_LOG_JS_STACK

Wenn angegeben, wird ein Aufrufstapel ausgegeben, der Dateinamen enthält, die sich auf Zeilen in der erstellten .js/.html-Datei beziehen, zusammen mit der Nachricht. Die Flags EM_LOG_C_STACK und EM_LOG_JS_STACK können kombiniert werden, um sowohl unübersetzte als auch übersetzte Datei- und Zeileninformationen auszugeben.

EM_LOG_NO_PATHS

Wenn angegeben, werden die Pfadnamen der Dateiinformationen im Aufrufstapel weggelassen.

Funktionen

long emscripten_get_compiler_setting(const char *name)

Gibt den Wert einer Compiler-Einstellung zurück.

Zum Beispiel, um den Integer-Wert von INITIAL_MEMORY während der Kompilierung zurückzugeben

emscripten_get_compiler_setting("INITIAL_MEMORY")

Für Werte, die etwas anderes als eine Ganzzahl enthalten, wird ein String zurückgegeben (Sie müssen den long-Rückgabewert in einen char* umwandeln).

Nützliche Dinge, die dies tun kann, sind die Version von Emscripten ("EMSCRIPTEN_VERSION"), die Optimierungsstufe ("OPT_LEVEL"), die Debug-Stufe ("DEBUG_LEVEL") usw.

Damit dieser Befehl funktioniert, müssen Sie mit der folgenden Compileroption kompilieren (da wir die Build-Größe mit diesen Metadaten nicht erhöhen wollen)

-sRETAIN_COMPILER_SETTINGS
Parameter

  • name (const char*) – Die zurückzugebende Compiler-Einstellung.

Gibt zurück

Der Wert der angegebenen Einstellung. Beachten Sie, dass für Werte, die keine Ganzzahl sind, ein String zurückgegeben wird (wandeln Sie den int-Rückgabewert in einen char* um).

Rückgabetyp

int

int emscripten_has_asyncify()

Gibt zurück, ob pseudosynchrone Funktionen verwendet werden können.

Rückgabetyp

int

Gibt zurück

1, wenn das Programm mit -sASYNCIFY kompiliert wurde, sonst 0.

void emscripten_debugger()

Gibt debugger aus.

Dies ist inline im Code, was der JavaScript-Engine mitteilt, den Debugger aufzurufen, wenn sie dort ankommt.

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

Gibt eine Nachricht auf der Konsole aus, optional mit Aufrufstapelinformationen.

Parameter

  • flags (int) – Ein binäres ODER von Elementen aus der Liste der EM_LOG_xxx-Flags, die Druckoptionen angeben.

  • char* format (const) – Ein printf-ähnlicher Formatstring.

  • ... – Eine printf-ähnliche „…“-Parameterliste, die gemäß den printf-Formatierungsregeln analysiert wird.

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

Ruft den aktuellen Aufrufstapel programmatisch ab.

Um die benötigte Anzahl von Bytes für einen Aufrufstapel abzufragen, ohne ihn zu schreiben, übergeben Sie 0 an out und maxbytes. In diesem Fall gibt die Funktion die Anzahl der Bytes (einschließlich des abschließenden Nullzeichens) zurück, die benötigt werden, um den vollständigen Aufrufstapel zu speichern. Beachten Sie, dass dies möglicherweise nicht vollständig genau ist, da nachfolgende Aufrufe unterschiedliche Zeilennummern enthalten werden. Es ist daher am besten, zur Sicherheit ein paar zusätzliche Bytes zu reservieren.

Parameter

  • flags (int) – Eine binäre ODER-Verknüpfung von Elementen aus der Liste der EM_LOG_xxx-Flags, die Druckoptionen angeben. Die Flags EM_LOG_CONSOLE, EM_LOG_WARN und EM_LOG_ERROR gelten in dieser Funktion nicht und werden ignoriert.

  • out (char*) – Ein Zeiger auf einen Speicherbereich, in den die Aufrufstapelzeichenfolge geschrieben wird. Die von dieser Funktion ausgegebene Zeichenfolge ist immer nullterminiert.

  • maxbytes (int) – Die maximale Anzahl von Bytes, die diese Funktion in den Speicher schreiben kann, auf den out zeigt. Wenn nicht genügend Platz vorhanden ist, wird die Ausgabe abgeschnitten (aber immer nullterminiert).

Gibt zurück

Die Anzahl der geschriebenen Bytes (nicht die Anzahl der Zeichen, also auch die abschließende Null).

Rückgabetyp

int

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

Ruft vorgeladene Bilddaten und die Größe des Bildes ab.

Die Funktion gibt einen Zeiger auf das geladene Bild oder NULL zurück – der Zeiger sollte mit free() freigegeben werden. Die Breite/Höhe des Bildes werden in die Parameter w und h geschrieben, wenn die Daten gültig sind.

Parameter

  • path (const char*) – Vollständiger Pfad/Dateiname zur Datei, die das vorgeladene Bild enthält.

  • w (int*) – Breite des Bildes (wenn Daten gültig sind).

  • h (int*) – Höhe des Bildes (wenn Daten gültig sind).

Gibt zurück

Ein Zeiger auf das vorgeladene Bild oder NULL.

Rückgabetyp

char*

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

Ruft vorgeladene Bilddaten aus einer C FILE* ab.

Parameter

  • file (FILE*) – Die FILE, die das vorgeladene Bild enthält.

  • w (int*) – Breite des Bildes (wenn Daten gültig sind).

  • h (int*) – Höhe des Bildes (wenn Daten gültig sind).

Gibt zurück

Ein Zeiger auf das vorgeladene Bild oder NULL.

Rückgabetyp

char*

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

Druckt ein Double als String, einschließlich eines Nullterminators. Dies ist nützlich, da JS-Engines eine gute Unterstützung für das Drucken eines Doubles auf eine Weise bieten, die die geringstmögliche Größe einnimmt, aber alle Informationen im Double bewahrt, d.h. es kann dann perfekt reversibel zurückparsiert werden (snprintf usw. tun dies leider nicht).

Parameter

  • x (double) – Das Double.

  • to (char*) – Ein vorab zugewiesener Puffer ausreichender Größe oder NULL, wenn keine Ausgabe angefordert wird (nützlich, um die notwendige Größe zu erhalten).

  • max (signed) – Die maximale Anzahl von Bytes, die in den Ausgabepointer „to“ geschrieben werden können (einschließlich des Nullterminators).

Rückgabetyp

Die Anzahl der notwendigen Bytes, ohne den Nullterminator (tatsächlich geschrieben, wenn to nicht NULL ist).

Registrierung von Socket-Ereignissen

Die Funktionen in diesem Abschnitt registrieren Callback-Funktionen zum Empfangen von Socket-Ereignissen. Diese Ereignisse sind analog zu WebSocket-Ereignissen, werden aber nach der internen Emscripten-Socket-Verarbeitung ausgelöst. Dies bedeutet beispielsweise, dass der Nachrichten-Callback ausgelöst wird, nachdem die Daten zur recv_queue hinzugefügt wurden, so dass eine Anwendung, die diesen Callback empfängt, die Daten einfach über den als Parameter an den Callback übergebenen Dateideskriptor lesen kann. Alle Callbacks erhalten einen Dateideskriptor (fd), der den Socket darstellt, auf dem die gemeldete Aktivität stattfand. Der Fehler-Callback akzeptiert auch einen int, der die Socket-Fehlernummer (errno) darstellt, und einen char*, der die Fehlermeldung (msg) darstellt.

Es kann nur eine einzige Callback-Funktion registriert werden, um ein bestimmtes Ereignis zu behandeln. Ein mehrfacher Aufruf einer bestimmten Registrierungsfunktion führt dazu, dass der erste Callback ersetzt wird. Ebenso wird durch Übergabe einer NULL-Callback-Funktion an einen beliebigen emscripten_set_socket_*_callback-Aufruf der für dieses Ereignis registrierte Callback abgemeldet.

Der userData-Zeiger ermöglicht es, beliebige Daten, die während der Ereignisregistrierung angegeben wurden, an den Callback zu übergeben. Dies ist besonders nützlich, um this-Zeiger in objektorientiertem Code zu übergeben.

Zusätzlich zur Möglichkeit, Netzwerk-Callbacks von C aus zu registrieren, ist es auch für nativen JavaScript-Code möglich, den zugrunde liegenden Mechanismus direkt zu verwenden, der zur Implementierung der Callback-Registrierung verwendet wird. Das folgende Codebeispiel zeigt beispielsweise einfache Logging-Callbacks, die standardmäßig registriert werden, wenn SOCKET_DEBUG aktiviert ist:

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

Die meisten der oben genannten JavaScript-Callback-Funktionen erhalten den Dateideskriptor des Sockets, der den Callback ausgelöst hat. Der On-Error-Callback erhält jedoch ein Array, das den Dateideskriptor, den Fehlercode und eine Fehlermeldung enthält.

Hinweis

Die zugrunde liegende JavaScript-Implementierung übergibt keine userData. Dies ist hauptsächlich für C/C++-Code von Nutzen, und die emscripten_set_socket_*_callback-Aufrufe erstellen einfach einen Closure, der die userData enthält, und übergeben diese als Callback an den zugrunde liegenden JavaScript-Ereignisregistrierungsmechanismus.

Callback-Funktionen

em_socket_callback

Funktionszeiger für emscripten_set_socket_open_callback() und die anderen Socket-Funktionen (außer emscripten_set_socket_error_callback()). Dies ist definiert als

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

  • fd (int) – Der Dateideskriptor des Sockets, der den Callback ausgelöst hat.

  • userData (void*) – Die userData, die ursprünglich an die Ereignisregistrierungsfunktion übergeben wurde.

em_socket_error_callback

Funktionszeiger für den emscripten_set_socket_error_callback(), definiert als

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

  • fd (int) – Der Dateideskriptor des Sockets, der den Callback ausgelöst hat.

  • err (int) – Der Code für den aufgetretenen Fehler.

  • msg (int) – Die Nachricht für den aufgetretenen Fehler.

  • userData (void*) – Die userData, die ursprünglich an die Ereignisregistrierungsfunktion übergeben wurde.

Funktionen

void emscripten_set_socket_error_callback(void *userData, em_socket_error_callback callback)

Wird durch einen WebSocket-Fehler ausgelöst.

Weitere Informationen finden Sie unter Registrierung von Socket-Ereignissen.

Parameter

  • userData (void*) – Beliebige Benutzerdaten, die an den Callback übergeben werden sollen.

  • callback (em_socket_error_callback) – Zeiger auf eine Callback-Funktion. Der Callback gibt einen Dateideskriptor, einen Fehlercode und eine Nachricht sowie die beliebigen userData zurück, die an diese Funktion übergeben wurden.

void emscripten_set_socket_open_callback(void *userData, em_socket_callback callback)

Wird ausgelöst, wenn der WebSocket geöffnet wurde.

Weitere Informationen finden Sie unter Registrierung von Socket-Ereignissen.

Parameter

  • userData (void*) – Beliebige Benutzerdaten, die an den Callback übergeben werden sollen.

  • callback (em_socket_callback) – Zeiger auf eine Callback-Funktion. Der Callback gibt einen Dateideskriptor und die beliebigen userData zurück, die an diese Funktion übergeben wurden.

void emscripten_set_socket_listen_callback(void *userData, em_socket_callback callback)

Wird ausgelöst, wenn listen aufgerufen wurde (synthetisches Ereignis).

Weitere Informationen finden Sie unter Registrierung von Socket-Ereignissen.

Parameter

  • userData (void*) – Beliebige Benutzerdaten, die an den Callback übergeben werden sollen.

  • callback (em_socket_callback) – Zeiger auf eine Callback-Funktion. Der Callback gibt einen Dateideskriptor und die beliebigen userData zurück, die an diese Funktion übergeben wurden.

void emscripten_set_socket_connection_callback(void *userData, em_socket_callback callback)

Wird ausgelöst, wenn die Verbindung hergestellt wurde.

Weitere Informationen finden Sie unter Registrierung von Socket-Ereignissen.

Parameter

  • userData (void*) – Beliebige Benutzerdaten, die an den Callback übergeben werden sollen.

  • callback (em_socket_callback) – Zeiger auf eine Callback-Funktion. Der Callback gibt einen Dateideskriptor und die beliebigen userData zurück, die an diese Funktion übergeben wurden.

void emscripten_set_socket_message_callback(void *userData, em_socket_callback callback)

Wird ausgelöst, wenn Daten vom Socket gelesen werden können.

Weitere Informationen finden Sie unter Registrierung von Socket-Ereignissen.

Parameter

  • userData (void*) – Beliebige Benutzerdaten, die an den Callback übergeben werden sollen.

  • callback (em_socket_callback) – Zeiger auf eine Callback-Funktion. Der Callback gibt einen Dateideskriptor und die beliebigen userData zurück, die an diese Funktion übergeben wurden.

void emscripten_set_socket_close_callback(void *userData, em_socket_callback callback)

Wird ausgelöst, wenn der WebSocket geschlossen wurde.

Weitere Informationen finden Sie unter Registrierung von Socket-Ereignissen.

Parameter

  • userData (void*) – Beliebige Benutzerdaten, die an den Callback übergeben werden sollen.

  • callback (em_socket_callback) – Zeiger auf eine Callback-Funktion. Der Callback gibt einen Dateideskriptor und die beliebigen userData zurück, die an diese Funktion übergeben wurden.

Ungerade Typen

Typedefs

emscripten_align1_short
emscripten_align2_int
emscripten_align1_int
emscripten_align2_float
emscripten_align1_float
emscripten_align4_double
emscripten_align2_double
emscripten_align1_double

Ungerade Typen. Diese können verwendet werden, um LLVM zu zwingen, ungerade Lade-/Speicheroperationen an Stellen im Code zu emittieren, wo SAFE_HEAP eine ungerade Operation gefunden hat.

Beispiele zur Verwendung finden Sie unter test/core/test_set_align.c.

Hinweis

Es ist besser, nicht-ausgerichtete Operationen zu vermeiden, aber wenn Sie von einem gepackten Byte-Stream oder ähnlichem lesen, können diese Typen nützlich sein!

Pseudosynchrone Funktionen

Diese Funktionen erfordern Asyncify (-sASYNCIFY). Diese Funktionen sind asynchron, erscheinen aber in C synchron. Weitere Details finden Sie unter Asyncify.

Schlafen

void emscripten_sleep(unsigned int ms)

Schläft für ms Millisekunden. Dies erscheint dem Code wie ein normaler "synchroner" Schlaf, d.h. die Ausführung wird erst fortgesetzt, wenn der Schlaf beendet ist. Beachten Sie jedoch, dass dies durch eine Rückkehr zur Ereignisschleife implementiert wird (es ist nicht möglich, im Web tatsächlich blockierend zu schlafen), was bedeutet, dass andere asynchrone Ereignisse auftreten können.

Netzwerk

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

Lädt eine Datei von einer URL synchron. Die asynchrone Version finden Sie unter emscripten_async_wget().

Neben dem Abrufen der URL aus dem Netzwerk werden Preload-Plugins ausgeführt, damit die Daten in IMG_Load usw. verwendet werden können (wir erledigen die Arbeit synchron, damit der Browser das Bild oder Audio usw. dekodiert). Weitere Informationen zum Vorladen von Dateien finden Sie unter Dateien vorladen.

Diese Funktion blockiert; sie kehrt erst zurück, wenn alle Operationen abgeschlossen sind. Sie können die Datei dann öffnen und lesen, wenn sie erfolgreich war.

Parameter

  • char* url (const) – Die zu ladende URL.

  • char* file (const) – Der Name der Datei, die aus der URL erstellt und geladen wurde. Wenn die Datei bereits existiert, wird sie überschrieben. Wenn das Zielverzeichnis für die Datei im Dateisystem nicht existiert, wird es erstellt. Es kann ein relativer Pfadname übergeben werden, der relativ zum aktuellen Arbeitsverzeichnis zum Zeitpunkt des Aufrufs dieser Funktion interpretiert wird.

Gibt zurück

0 bei Erfolg oder 1 bei Fehler.

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

Ruft Daten synchron aus dem Netzwerk ab und speichert sie in einem Speicherpuffer, der für Sie zugewiesen wird. Sie müssen den Puffer freigeben, sonst wird er lecken!

Parameter

  • url – Die URL, von der abgerufen werden soll

  • pbuffer – Ein Ausgabeparameter, der mit einem Zeiger auf einen Puffer gefüllt wird, der die heruntergeladenen Daten enthält. Dieser Speicher wurde für Sie mit malloc reserviert, und Sie müssen ihn freigeben, sonst wird er lecken!

  • pnum – Ein Ausgabeparameter, der mit der Größe der heruntergeladenen Daten gefüllt wird.

  • perror – Ein Ausgabeparameter, der bei einem Fehler mit einem Wert ungleich Null gefüllt wird.

IndexedDB

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

Ruft Daten synchron aus IndexedDB ab und speichert sie in einem Speicherpuffer, der für Sie zugewiesen wird. Sie müssen den Puffer freigeben, sonst wird er lecken!

Parameter

  • db_name – Der Name der Datenbank, aus der geladen werden soll

  • file_id – Der Name der zu ladenden Datei

  • pbuffer – Ein Ausgabeparameter, der mit einem Zeiger auf einen Puffer gefüllt wird, der die heruntergeladenen Daten enthält. Dieser Speicher wurde für Sie mit malloc reserviert, und Sie müssen ihn freigeben, sonst wird er lecken!

  • pnum – Ein Ausgabeparameter, der mit der Größe der heruntergeladenen Daten gefüllt wird.

  • perror – Ein Ausgabeparameter, der bei einem Fehler mit einem Wert ungleich Null gefüllt wird.

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

Speichert Daten synchron in IndexedDB.

Parameter

  • db_name – Der Name der Datenbank, in der gespeichert werden soll

  • file_id – Der Name der zu speichernden Datei

  • buffer – Ein Zeiger auf die zu speichernden Daten

  • num – Die Anzahl der zu speichernden Bytes

  • perror – Ein Ausgabeparameter, der bei einem Fehler mit einem Wert ungleich Null gefüllt wird.

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

Löscht Daten synchron aus IndexedDB.

Parameter

  • db_name – Der Name der Datenbank, aus der gelöscht werden soll

  • file_id – Der Name der zu löschenden Datei

  • perror – Ein Ausgabeparameter, der bei einem Fehler mit einem Wert ungleich Null gefüllt wird.

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

Prüft synchron, ob eine Datei in IndexedDB existiert.

Parameter

  • db_name – Der Name der Datenbank, in der geprüft werden soll

  • file_id – Der Name der zu prüfenden Datei

  • pexists – Ein Ausgabeparameter, der mit einem Wert ungleich Null gefüllt wird, wenn die Datei in dieser Datenbank existiert.

  • perror – Ein Ausgabeparameter, der bei einem Fehler mit einem Wert ungleich Null gefüllt wird.

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

Löscht synchron alle Daten aus IndexedDB.

Parameter

  • db_name – Der Name der zu leerenden Datenbank

  • perror – Ein Ausgabeparameter, der bei einem Fehler mit einem Wert ungleich Null gefüllt wird.

Asyncify-Funktionen

Diese Funktionen funktionieren nur bei Verwendung von Asyncify.

Typedefs

em_scan_func

Funktionszeigertyp zur Verwendung in Scan-Callbacks, der zwei Zeiger für den Anfang und das Ende eines Speicherbereichs empfängt. Sie können diesen Bereich dann scannen.

Definiert als

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

Funktionen

void emscripten_scan_stack(em_scan_func func)

Scannt den C-Benutzerspace-Stack, d.h. den vom kompilierten Code verwalteten Stack (im Gegensatz zum internen Stack der Wasm-VM, der nicht direkt beobachtbar ist). Diese Daten befinden sich bereits im linearen Speicher; diese Funktion bietet Ihnen lediglich eine einfache Möglichkeit, ihren Speicherort zu ermitteln.

void emscripten_scan_registers(em_scan_func func)

Scannt "Register", womit wir Daten meinen, die sich nicht im Speicher befinden. In Wasm bedeutet das Daten, die in Lokalen gespeichert sind, einschließlich Lokalen in Funktionen, die weiter oben im Stack liegen – die Wasm-VM hat sie ausgelagert, aber davon ist für den Benutzercode nichts sichtbar).

Beachten Sie, dass diese Funktion Wasm-Locals scannt. Abhängig von der LLVM-Optimierungsstufe scannt dies möglicherweise nicht die ursprünglichen Locals in Ihrem Quellcode. Zum Beispiel bei -O0 können Locals auf dem Stack gespeichert werden. Um sicherzustellen, dass Sie alles Notwendige scannen, können Sie auch emscripten_scan_stack verwenden.

Diese Funktion erfordert Asyncify – sie verlässt sich auf diese Option, um den lokalen Zustand bis zum Stack zu vergießen. Infolgedessen erhöht sie den Overhead Ihres Programms.

void emscripten_lazy_load_code()

Dies erstellt zur Kompilierungszeit zwei Wasm-Dateien: die erste Wasm, die normal heruntergeladen und ausgeführt wird, und eine zweite, die lazy-geladen wird. Wenn ein emscripten_lazy_load_code()-Aufruf erreicht wird, laden wir die zweite Wasm und setzen die Ausführung damit fort.

Die Idee hierbei ist, dass der anfängliche Download recht klein sein kann, wenn Sie genügend emscripten_lazy_load_code()-Aufrufe in Ihrem Codebase platzieren, da der Optimierer Code aus dem ersten Wasm entfernen kann, wenn er feststellt, dass er nicht erreicht werden kann. Die zweite heruntergeladene Wasm kann Ihren vollständigen Codebase enthalten, einschließlich selten verwendeter Funktionen, wobei das Lazy-Loading möglicherweise gar nicht stattfindet.

Hinweis

Dies erfordert das Kompilieren mit -sASYNCIFY_LAZY_LOAD_CODE.

ABI-Funktionen

Die folgenden Funktionen sind nicht in emscripten.h deklariert, werden aber intern in unseren Systembibliotheken verwendet. Sie könnten für Sie relevant sein, wenn Sie den Emscripten-Laufzeit-JS-Code ersetzen oder Emscripten-Binärdateien in Ihrer eigenen Laufzeit ausführen.

void emscripten_notify_memory_growth(i32 index)

Wird aufgerufen, wenn der Speicher gewachsen ist. In einer JS-Laufzeit wird dies verwendet, um zu wissen, wann die JS-Ansichten auf den Wasm-Speicher aktualisiert werden müssen, die wir sonst nach jeder Wasm-Codeausführung ständig überprüfen müssten. Siehe diese WASI-Diskussion.

Parameter

  • index (i32) – Welcher Speicher gewachsen ist.