html5.h

Die C++-APIs in html5.h definieren die Emscripten Low-Level Glue Bindings zur Interaktion mit HTML5-Events aus nativem Code.

Tipp

Die C++-APIs sind eng an ihre äquivalenten HTML5 JavaScript APIs angelehnt. Die unten aufgeführten HTML5-Spezifikationen bieten zusätzliche detaillierte Referenzinformationen „zusätzlich zu“ den in diesem Dokument bereitgestellten Informationen.

Zusätzlich kann der Test-/Beispielcode eingesehen werden, um zu sehen, wie der Code verwendet wird.

Die HTML5-Spezifikationen für APIs, die von html5.h abgebildet werden, umfassen

• DOM Level 3 Events: Tastatur, Maus, Mausrad, Größenänderung, Scrollen, Fokus.

• Geräteorientierungsereignisse für Gyroskop und Beschleunigungsmesser.

• Bildschirmorientierungsereignisse für Hoch-/Querformat-Behandlung.

• Vollbildereignisse für Übergänge zwischen Browser-Canvas-Vollbildmodi.

• Pointer-Lock-Events zur relativen Mausbewegungssteuerung.

• Vibrations-API zur haptischen Vibrationsrückmeldung von Mobilgeräten.

• Page Visibility Events zur Energieverwaltung.

• Touch Events.

• Gamepad API.

• Beforeunload-Ereignis.

• WebGL-Kontextereignisse.

• Animation und Timing.

• Konsole.

• Throw.

Wie man diese API verwendet

Die meisten dieser APIs verwenden eine ereignisbasierte Architektur; die Funktionalität wird durch die Registrierung einer Callback-Funktion aufgerufen, die aufgerufen wird, wenn das Ereignis auftritt.

Hinweis

Die Gamepad API ist derzeit eine Ausnahme, da nur eine Polling-API verfügbar ist. Für einige APIs werden sowohl ein ereignisbasiertes als auch ein polling-basiertes Modell angeboten.

Registrierungsfunktionen

Das typische Format von Registrierungsfunktionen ist wie folgt (einige Methoden können verschiedene Parameter weglassen)

EMSCRIPTEN_RESULT emscripten_set_some_callback(
  const char *target,   // ID of the target HTML element.
  void *userData,   // User-defined data to be passed to the callback.
  bool useCapture,   // Whether or not to use capture.
  em_someevent_callback_func callback   // Callback function.
);

Der Parameter target ist die ID des HTML-Elements, auf das die Callback-Registrierung angewendet werden soll. Dieses Feld hat die folgenden speziellen Bedeutungen

• EMSCRIPTEN_EVENT_TARGET_WINDOW: Der Event-Listener wird auf das JavaScript window-Objekt angewendet.

• EMSCRIPTEN_EVENT_TARGET_DOCUMENT: Der Event-Listener wird auf das JavaScript document-Objekt angewendet.

• EMSCRIPTEN_EVENT_TARGET_SCREEN: Der Event-Listener wird auf das JavaScript window.screen-Objekt angewendet.

• 0 oder NULL: Wenn mit der Option -sDISABLE_DEPRECATED_FIND_EVENT_TARGET_BEHAVIOR (Standard) gebaut wird, bezeichnet NULL ein ungültiges Element. Wenn mit der veralteten Option -sDISABLE_DEPRECATED_FIND_EVENT_TARGET_BEHAVIOR=0 (nicht empfohlen) gebaut wird, wird ein Standardelement automatisch basierend auf dem Ereignistyp ausgewählt.

• #canvas: Wenn mit der veralteten Option -sDISABLE_DEPRECATED_FIND_EVENT_TARGET_BEHAVIOR=0 (nicht empfohlen) gebaut wird, wird der Event-Listener auf das Standard-WebGL-Canvas-Element von Emscripten angewendet. Wenn mit der Option -sDISABLE_DEPRECATED_FIND_EVENT_TARGET_BEHAVIOR (Standard) gebaut wird, wird #canvas als CSS-Query-Selektor interpretiert: „das erste Element mit der CSS-ID ‚canvas‘“.

• Jeder andere String: Eine CSS-Selektor-Suche wird mit dem übergebenen String im DOM durchgeführt, und der Event-Listener wird auf das erste Element angewendet, das der Abfrage entspricht.

Wenn die obigen Informationen für Sie nicht ausreichen, können Sie benutzerdefinierte Zuordnungen in JavaScript hinzufügen, indem Sie so etwas wie

specialHTMLTargets["!canvas"] = Module.canvas;

Dadurch wird !canvas auf das in Module.canvas enthaltene Canvas abgebildet. (Sie können dieses JavaScript beispielsweise in einem EM_JS- oder EM_ASM-Block schreiben, der vor dem Aufruf der Registrierungsfunktion ausgeführt wird.)

Der Parameter userData ist ein benutzerdefinierter Wert, der (unverändert) an den registrierten Event-Callback übergeben wird. Dies kann beispielsweise verwendet werden, um einen Zeiger auf eine C++-Klasse zu übergeben oder die C-API auf ähnliche Weise sauber objektorientiert zu kapseln.

Der Parameter useCapture wird auf useCapture in EventTarget.addEventListener abgebildet. Er gibt an, ob das Capturing eingeleitet werden soll oder nicht: Wenn true, wird der Callback nur für die DOM-Capture- und Target-Phasen aufgerufen; wenn false, wird der Callback während der Target- und Bubbling-Phasen ausgelöst. Siehe DOM Level 3 Events für eine detailliertere Erklärung.

Die meisten Funktionen geben das Ergebnis unter Verwendung des Typs EMSCRIPTEN_RESULT zurück. Null und positive Werte bedeuten Erfolg. Negative Werte signalisieren einen Fehler. Keine der Funktionen schlägt fehl oder bricht ab, indem eine JavaScript- oder C++-Ausnahme ausgelöst wird. Wenn ein bestimmter Browser die angegebene Funktion nicht unterstützt, wird der Wert EMSCRIPTEN_RESULT_NOT_SUPPORTED zum Zeitpunkt der Registrierung des Callbacks zurückgegeben.

Callback-Funktionen

Wenn das Ereignis eintritt, wird der Callback mit dem relevanten Ereignis-„Typ“ (z. B. EMSCRIPTEN_EVENT_CLICK), einer struct, die die Details des aufgetretenen Ereignisses enthält, und den userData, die ursprünglich an die Registrierungsfunktion übergeben wurden, aufgerufen. Das allgemeine Format der Callback-Funktion ist

typedef bool (*em_someevent_callback_func) // Callback function. Return true if event is "consumed".
  (
  int eventType, // The type of event.
  const EmscriptenSomeEvent *someEvent, // Information about the event.
  void *userData // User data passed from the registration function.
  );

Callback-Handler, die einen bool zurückgeben, können true angeben, um zu signalisieren, dass der Handler das Ereignis konsumiert hat (dies unterdrückt die Standardaktion für dieses Ereignis, indem die Methode .preventDefault(); aufgerufen wird). Die Rückgabe von false zeigt an, dass das Ereignis nicht konsumiert wurde – die Standard-Browser-Ereignisaktion wird ausgeführt und das Ereignis kann wie gewohnt weitergegeben/aufsteigen.

Das Aufrufen einer Registrierungsfunktion mit einem null-Zeiger für den Callback führt zu einer Deregistrierung dieses Callbacks vom angegebenen target-Element. Alle Event-Handler werden auch automatisch deregistriert, wenn die C-Funktion exit() während des atexit-Handler-Durchlaufs aufgerufen wird. Verwenden Sie entweder die Funktion emscripten_set_main_loop() oder setzen Sie Module.noExitRuntime = true;, um sicherzustellen, dass das Verlassen von main() nicht sofort einen exit() und die Bereinigung der Event-Handler bewirkt.

Funktionen, die von der Web-Sicherheit betroffen sind

Einige Funktionen, darunter emscripten_request_pointerlock() und emscripten_request_fullscreen(), sind von der Web-Sicherheit betroffen.

Obwohl die Funktionen überall aufgerufen werden können, können die eigentlichen „Anfragen“ nur innerhalb des Handlers für ein vom Benutzer generiertes Ereignis (z. B. Tastendruck, Maus- oder Berührungsdruck/-freigabe) ausgelöst werden.

Beim Portieren von Code kann es schwierig sein, sicherzustellen, dass die Funktionen innerhalb geeigneter Event-Handler aufgerufen werden (damit die Anfragen sofort ausgelöst werden). Als Annehmlichkeit können Entwickler deferUntilInEventHandler=true setzen, um unsichere Anfragen automatisch aufzuschieben, bis der Benutzer das nächste Mal eine Tastatur- oder Maustaste drückt. Dies vereinfacht das Portieren, führt aber oft zu einer schlechteren Benutzererfahrung. Zum Beispiel muss der Benutzer einmal auf den Canvas klicken, um den Zeiger zu verbergen oder in den Vollbildmodus zu wechseln.

Wo immer möglich, sollten die Funktionen nur innerhalb geeigneter Event-Handler aufgerufen werden. Das Setzen von deferUntilInEventHandler=false führt dazu, dass die Funktionen mit einem Fehler abbrechen, wenn die Anfrage aufgrund einer Sicherheitsbeschränkung abgelehnt wird: Dies ist ein nützlicher Mechanismus, um Fälle zu entdecken, in denen die Funktionen außerhalb des Handlers für ein vom Benutzer generiertes Ereignis aufgerufen werden.

Test-/Beispielcode

Der HTML5-Testcode demonstriert die Verwendung dieser API

• test_html5_core.c

• test_html5_fullscreen.c

• test_html5_mouse.c

Allgemeine Typen

EM_UTF8

Dies ist der Emscripten-Typ für einen UTF8-String (entspricht einem char). Dies wird für Knotennamen, Element-IDs usw. verwendet.

Funktionsergebniswerte

Die meisten Funktionen in dieser API geben ein Ergebnis vom Typ EMSCRIPTEN_RESULT zurück. Keine der Funktionen schlägt fehl oder bricht ab, indem eine JavaScript- oder C++-Ausnahme ausgelöst wird. Wenn ein bestimmter Browser die angegebene Funktion nicht unterstützt, wird der Wert EMSCRIPTEN_RESULT_NOT_SUPPORTED zum Zeitpunkt der Registrierung des Callbacks zurückgegeben.

EMSCRIPTEN_RESULT

Dieser Typ wird verwendet, um das Ergebnis der meisten Funktionen in dieser API zurückzugeben. Null und positive Werte bedeuten Erfolg, während negative Werte einen Fehler signalisieren. Mögliche Werte sind unten aufgeführt.

EMSCRIPTEN_RESULT_SUCCESS

Der Vorgang war erfolgreich.

EMSCRIPTEN_RESULT_DEFERRED

Die angeforderte Operation kann aus Web-Sicherheitsgründen derzeit nicht abgeschlossen werden und wurde zur Fertigstellung im nächsten Event-Handler zurückgestellt.

EMSCRIPTEN_RESULT_NOT_SUPPORTED

Die angegebene Operation wird von diesem Browser oder dem Zielelement nicht unterstützt. Dieser Wert wird zum Zeitpunkt der Callback-Registrierung zurückgegeben, wenn die Operation nicht unterstützt wird.

EMSCRIPTEN_RESULT_FAILED_NOT_DEFERRED

Die angeforderte Operation konnte aus Web-Sicherheitsgründen nicht abgeschlossen werden. Sie schlug fehl, weil der Benutzer die Operation nicht aufschieben wollte.

EMSCRIPTEN_RESULT_INVALID_TARGET

Die Operation schlug fehl, da das angegebene Zielelement ungültig ist.

EMSCRIPTEN_RESULT_UNKNOWN_TARGET

Die Operation schlug fehl, da das angegebene Zielelement nicht gefunden wurde.

EMSCRIPTEN_RESULT_INVALID_PARAM

Die Operation schlug fehl, da ein ungültiger Parameter an die Funktion übergeben wurde.

EMSCRIPTEN_RESULT_FAILED

Generische Fehlermeldung, die zurückgegeben wird, wenn kein spezifisches Ergebnis verfügbar ist.

EMSCRIPTEN_RESULT_NO_DATA

Die Operation schlug fehl, da derzeit keine Daten verfügbar sind.

Tasten

Definiert

EMSCRIPTEN_EVENT_KEYPRESS

EMSCRIPTEN_EVENT_KEYDOWN

EMSCRIPTEN_EVENT_KEYUP

Emscripten-Tastenereignisse.

DOM_KEY_LOCATION

Die Position der Taste auf der Tastatur; einer der folgenden Werte.

DOM_KEY_LOCATION_STANDARD

DOM_KEY_LOCATION_LEFT

DOM_KEY_LOCATION_RIGHT

DOM_KEY_LOCATION_NUMPAD

Positionen der Taste auf der Tastatur.

Struktur

EmscriptenKeyboardEvent

Die Ereignisstruktur, die in Tastaturereignissen übergeben wird: keypress, keydown und keyup.

Beachten Sie, dass die DOM Level 3 Events Spezifikation zum Zeitpunkt des Schreibens (2014-03) sehr neu ist, weshalb eine einheitliche Unterstützung der verschiedenen Felder in der Spezifikation noch im Fluss ist. Überprüfen Sie die Ergebnisse unbedingt in mehreren Browsern. Siehe den unmerged Pull Request #2222 für ein Beispiel, wie die älteren Tastenereignisse zu interpretieren sind.

double timestamp

Absolute Wanduhrzeit, zu der die Daten aufgezeichnet wurden (Millisekunden).

EM_UTF8 key

Die gedruckte Darstellung der gedrückten Taste.

Maximale Größe 32 char (d.h. EM_UTF8 key[32]).

EM_UTF8 code

Ein String, der die physisch gedrückte Taste identifiziert. Der Wert wird nicht durch das aktuelle Tastaturlayout oder den Modifikatorstatus beeinflusst, sodass eine bestimmte Taste immer den gleichen Wert zurückgibt.

Maximale Größe 32 char (d.h. EM_UTF8 code[32]).

unsigned long location

Gibt die Position der Taste auf der Tastatur an. Einer der DOM_KEY_LOCATION-Werte.

bool ctrlKey

bool shiftKey

bool altKey

bool metaKey

Gibt an, welche Modifikatoren während des Tastenereignisses aktiv waren.

bool repeat

Gibt an, ob dieses Tastaturereignis einen wiederholten Tastendruck darstellt.

EM_UTF8 locale

Ein Ländereinstellung-String, der die konfigurierte Tastaturländereinstellung angibt. Dies kann ein leerer String sein, wenn der Browser oder das Gerät die Tastatur-Ländereinstellung nicht kennt.

Maximale Größe 32 Zeichen (d.h. EM_UTF8 locale[32]).

EM_UTF8 charValue

Die folgenden Felder sind Werte aus früheren Versionen der DOM-Tastenereignis-Spezifikationen. Siehe die Zeichenrepräsentation der Taste. Dies ist das Feld char aus den Docs, aber umbenannt in charValue, um ein C-reserviertes Wort zu vermeiden.

Maximale Größe 32 char (d.h. EM_UTF8 charValue[32]).

Warnung

Dieses Attribut wurde aus den DOM Level 3 Events entfernt.

unsigned long charCode

Die Unicode-Referenznummer der Taste; dieses Attribut wird nur vom keypress-Ereignis verwendet. Bei Tasten, deren Attribut char mehrere Zeichen enthält, ist dies der Unicode-Wert des ersten Zeichens in diesem Attribut.

Warnung

Dieses Attribut ist veraltet, Sie sollten stattdessen das Feld key verwenden, falls verfügbar.

unsigned long keyCode

Ein system- und implementierungsabhängiger numerischer Code, der den unveränderten Wert der gedrückten Taste identifiziert.

Warnung

Dieses Attribut ist veraltet, Sie sollten stattdessen das Feld key verwenden, falls verfügbar.

unsigned long which

Ein system- und implementierungsabhängiger numerischer Code, der den unveränderten Wert der gedrückten Taste identifiziert; dieser ist normalerweise derselbe wie keyCode.

Warnung

Dieses Attribut ist veraltet, Sie sollten stattdessen das Feld key verwenden, falls verfügbar. Beachten Sie jedoch, dass die Cross-Browser-Unterstützung für which möglicherweise besser ist als für die anderen Felder, daher wird Experimentieren empfohlen. Lesen Sie Issue https://github.com/emscripten-core/emscripten/issues/2817 für weitere Informationen.

Callback-Funktionen

em_key_callback_func

Funktionszeiger für die keypress callback functions, definiert als

typedef bool (*em_key_callback_func)(int eventType, const EmscriptenKeyboardEvent *keyEvent, void *userData);

Parameter

• eventType (int) – Der Typ des Tastenereignisses.

• keyEvent (const EmscriptenKeyboardEvent*) – Informationen über das aufgetretene Tastenereignis.

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

Gibt zurück

true (ungleich Null), um anzuzeigen, dass das Ereignis vom Callback-Handler konsumiert wurde.

Rückgabetyp

bool

Funktionen

EMSCRIPTEN_RESULT emscripten_set_keypress_callback(const char *target, void *userData, bool useCapture, em_key_callback_func callback)

EMSCRIPTEN_RESULT emscripten_set_keydown_callback(const char *target, void *userData, bool useCapture, em_key_callback_func callback)

EMSCRIPTEN_RESULT emscripten_set_keyup_callback(const char *target, void *userData, bool useCapture, em_key_callback_func callback)

Registriert eine Callback-Funktion für den Empfang von vom Browser generierten Tastatureingabeereignissen.

Parameter

• target (const char*) – Ziel-HTML-Element-ID.

• userData (void*) – Benutzerdefinierte Daten, die an den Callback übergeben werden (opak für die API).

• useCapture (bool) – Setzen Sie true, um Capture zu verwenden.

• callback (em_key_callback_func) – Eine Callback-Funktion. Die Funktion wird mit dem Ereignistyp, Informationen über das Ereignis und Benutzerdaten aufgerufen, die von dieser Registrierungsfunktion übergeben wurden. Der Callback sollte true zurückgeben, wenn das Ereignis konsumiert wurde.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

Siehe auch

• https://developer.mozilla.org/en/DOM/Event/UIEvent/KeyEvent

• http://www.javascriptkit.com/jsref/eventkeyboardmouse.shtml

Hinweis

Um Ereignisse zu empfangen, muss das Element fokussierbar sein, siehe https://github.com/emscripten-core/emscripten/pull/7484#issuecomment-437887001

Maus

Definiert

EMSCRIPTEN_EVENT_CLICK

EMSCRIPTEN_EVENT_MOUSEDOWN

EMSCRIPTEN_EVENT_MOUSEUP

EMSCRIPTEN_EVENT_DBLCLICK

EMSCRIPTEN_EVENT_MOUSEMOVE

EMSCRIPTEN_EVENT_MOUSEENTER

EMSCRIPTEN_EVENT_MOUSELEAVE

Emscripten-Mausereignisse.

Struktur

EmscriptenMouseEvent

Die Ereignisstruktur, die in Mausereignissen übergeben wird: click, mousedown, mouseup, dblclick, mousemove, mouseenter und mouseleave.

double timestamp

Absolute Wanduhrzeit, zu der die Daten aufgezeichnet wurden (Millisekunden).

long screenX

long screenY

Die Koordinaten relativ zum Bildschirmkoordinatensystem des Browsers.

long clientX

long clientY

Die Koordinaten relativ zum mit dem Ereignis verbundenen Viewport.

bool ctrlKey

bool shiftKey

bool altKey

bool metaKey

Gibt an, welche Modifikatoren während des Mausereignisses aktiv waren.

unsigned short button

Identifiziert, welche Zeigergerätetaste ihren Zustand geändert hat (siehe MouseEvent.button)

• 0 : Linke Taste

• 1 : Mittlere Taste (falls vorhanden)

• 2 : Rechte Taste

unsigned short buttons

Eine Bitmaske, die angibt, welche Kombinationen von Maustasten zum Zeitpunkt des Ereignisses gedrückt waren.

long movementX

long movementY;

Wenn die Zeigersperre aktiv ist, geben diese beiden zusätzlichen Felder die relative Mausbewegung seit dem letzten Ereignis an.

long targetX

long targetY

Diese Felder geben die Mauskoordinaten an, die relativ zum Koordinatenraum des empfangenden DOM-Zielelements für Eingabeereignisse zugeordnet sind (Emscripten-spezifische Erweiterung; Koordinaten werden auf die nächste ganze Zahl abgerundet).

long canvasX

long canvasY

Diese Felder geben die Mauskoordinaten an, die dem Emscripten-Canvas-Clientbereich zugeordnet sind (Emscripten-spezifische Erweiterung; Koordinaten werden auf die nächste ganze Zahl abgerundet).

long padding

Intern, kann ignoriert werden.

Hinweis

Nur für Implementierer: Diese Struktur auf ein Vielfaches von 8 Bytes auffüllen, damit WheelEvent eindeutig auf 8 Bytes ausgerichtet ist.

Callback-Funktionen

em_mouse_callback_func

Funktionszeiger für die Mausereignis-Callback-Funktionen, definiert als

typedef bool (*em_mouse_callback_func)(int eventType, const EmscriptenMouseEvent *mouseEvent, void *userData);

Parameter

• eventType (int) – Der Typ des Mausereignisses.

• mouseEvent (const EmscriptenMouseEvent*) – Informationen über das aufgetretene Mausereignis.

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

Gibt zurück

true (ungleich Null), um anzuzeigen, dass das Ereignis vom Callback-Handler konsumiert wurde.

Rückgabetyp

bool

Funktionen

EMSCRIPTEN_RESULT emscripten_set_click_callback(const char *target, void *userData, bool useCapture, em_mouse_callback_func callback)

EMSCRIPTEN_RESULT emscripten_set_mousedown_callback(const char *target, void *userData, bool useCapture, em_mouse_callback_func callback)

EMSCRIPTEN_RESULT emscripten_set_mouseup_callback(const char *target, void *userData, bool useCapture, em_mouse_callback_func callback)

EMSCRIPTEN_RESULT emscripten_set_dblclick_callback(const char *target, void *userData, bool useCapture, em_mouse_callback_func callback)

EMSCRIPTEN_RESULT emscripten_set_mousemove_callback(const char *target, void *userData, bool useCapture, em_mouse_callback_func callback)

EMSCRIPTEN_RESULT emscripten_set_mouseenter_callback(const char *target, void *userData, bool useCapture, em_mouse_callback_func callback)

EMSCRIPTEN_RESULT emscripten_set_mouseleave_callback(const char *target, void *userData, bool useCapture, em_mouse_callback_func callback)

Registriert eine Callback-Funktion zum Empfang von browsergenerierten Maus-Eingabeereignissen.

Parameter

• target (const char*) – Ziel-HTML-Element-ID.

• userData (void*) – Benutzerdefinierte Daten, die an den Callback übergeben werden (opak für die API).

• useCapture (bool) – Setzen Sie true, um Capture zu verwenden.

• callback (em_mouse_callback_func) – Eine Callback-Funktion. Die Funktion wird mit dem Ereignistyp, Informationen über das Ereignis und Benutzerdaten aufgerufen, die von dieser Registrierungsfunktion übergeben wurden. Der Callback sollte true zurückgeben, wenn das Ereignis konsumiert wurde.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_get_mouse_status(EmscriptenMouseEvent *mouseState)

Gibt den zuletzt empfangenen Mausereignisstatus zurück.

Beachten Sie, dass für den Erfolg dieses Funktionsaufrufs emscripten_set_xxx_callback zuvor mit einem der Mausereignistypen und einem Callback-Funktionszeiger ungleich Null aufgerufen worden sein muss, um die Mauszustandserfassung zu aktivieren.

Parameter

• mouseState (EmscriptenMouseEvent*) – Der zuletzt empfangene Mausereignisstatus.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

Rad

Definiert

EMSCRIPTEN_EVENT_WHEEL

Emscripten Radereignis.

DOM_DELTA_PIXEL

Die Einheiten der Messung für das Delta müssen Pixel sein (aus Spezifikation).

DOM_DELTA_LINE

Die Maßeinheiten für das Delta müssen einzelne Textzeilen sein (aus Spezifikation).

DOM_DELTA_PAGE

Die Maßeinheiten für das Delta müssen Seiten sein, entweder als einzelner Bildschirm oder als abgegrenzte Seite definiert (aus Spezifikation).

Struktur

EmscriptenWheelEvent

Die Ereignisstruktur, die in Mausradereignissen übergeben wird.

EmscriptenMouseEvent mouse

Gibt allgemeine Mausinformationen zu diesem Ereignis an.

double deltaX

double deltaY

double deltaZ

Bewegung des Rades auf jeder Achse. Beachten Sie, dass diese Werte Bruchteile sein können, daher sollten Sie es vermeiden, sie einfach in Ganzzahlen umzuwandeln, da dies zu Scrollwerten von 0 führen kann. Die positive Y-Scrollrichtung ist das Scrollen der Seite nach unten (Seiten-CSS-Pixel +Y-Richtung), was dem Scrollen des Mausrades nach unten (weg vom Bildschirm) unter Windows, Linux und auch unter macOS entspricht, wenn die Option „natürliches Scrollen“ deaktiviert ist.

unsigned long deltaMode

Einer der DOM_DELTA_-Werte, der die Maßeinheiten für die Delta-Werte angibt.

Callback-Funktionen

em_wheel_callback_func

Funktionszeiger für die Wheel-Ereignis-Callback-Funktionen, definiert als

typedef bool (*em_wheel_callback_func)(int eventType, const EmscriptenWheelEvent *wheelEvent, void *userData);

Parameter

• eventType (int) – Der Typ des Radereignisses (EMSCRIPTEN_EVENT_WHEEL).

• wheelEvent (const EmscriptenWheelEvent*) – Informationen über das aufgetretene Radereignis.

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

Gibt zurück

true (ungleich Null), um anzuzeigen, dass das Ereignis vom Callback-Handler konsumiert wurde.

Rückgabetyp

bool

Funktionen

EMSCRIPTEN_RESULT emscripten_set_wheel_callback(const char *target, void *userData, bool useCapture, em_wheel_callback_func callback)

Registriert eine Callback-Funktion zum Empfang von browsergenerierten Mausrad-Ereignissen.

Parameter

• target (const char*) – Ziel-HTML-Element-ID.

• userData (void*) – Benutzerdefinierte Daten, die an den Callback übergeben werden (opak für die API).

• useCapture (bool) – Setzen Sie true, um Capture zu verwenden.

• callback (em_wheel_callback_func) – Eine Callback-Funktion. Die Funktion wird mit dem Ereignistyp, Informationen über das Ereignis und Benutzerdaten aufgerufen, die von dieser Registrierungsfunktion übergeben wurden. Der Callback sollte true zurückgeben, wenn das Ereignis konsumiert wurde.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

Benutzeroberfläche

Definiert

EMSCRIPTEN_EVENT_RESIZE

EMSCRIPTEN_EVENT_SCROLL

Emscripten UI-Ereignisse.

Struktur

EmscriptenUiEvent

Die Ereignisstruktur, die in DOM-Element UIEvent-Ereignissen übergeben wird: resize und scroll.

long detail

Bei Größenänderungs- und Scrollereignissen ist dies immer Null.

int documentBodyClientWidth

int documentBodyClientHeight

Die clientWidth/clientHeight des document.body-Elements.

int windowInnerWidth

int windowInnerHeight

Die innerWidth/innerHeight des Browserfensters.

int windowOuterWidth

int windowOuterHeight;

Die outerWidth/outerHeight des Browserfensters.

int scrollTop

int scrollLeft

Die Seiten-Scrollposition (abgerundet auf den nächsten Pixel).

Callback-Funktionen

em_ui_callback_func

Funktionszeiger für die UI-Ereignis-Callback-Funktionen, definiert als

typedef bool (*em_ui_callback_func)(int eventType, const EmscriptenUiEvent *uiEvent, void *userData);

Parameter

• eventType (int) – Der Typ des UI-Ereignisses (EMSCRIPTEN_EVENT_RESIZE).

• uiEvent (const EmscriptenUiEvent*) – Informationen über das aufgetretene UI-Ereignis.

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

Gibt zurück

true (ungleich Null), um anzuzeigen, dass das Ereignis vom Callback-Handler konsumiert wurde.

Rückgabetyp

bool

Funktionen

EMSCRIPTEN_RESULT emscripten_set_resize_callback(const char *target, void *userData, bool useCapture, em_ui_callback_func callback)

EMSCRIPTEN_RESULT emscripten_set_scroll_callback(const char *target, void *userData, bool useCapture, em_ui_callback_func callback)

Registriert eine Callback-Funktion zum Empfang von DOM-Element Größenänderungs- und Scrollereignissen.

Hinweis

• Für den resize-Callback geben Sie target = EMSCRIPTEN_EVENT_TARGET_WINDOW ein, um resize-Ereignisse vom Window-Objekt zu erhalten.

• Die DOM3 Events Spezifikation erfordert nur, dass das Window-Objekt resize-Ereignisse sendet. Es ist gültig, einen resize-Callback auf andere DOM-Elemente zu registrieren, aber der Browser ist nicht verpflichtet, resize-Ereignisse für diese auszulösen.

Parameter

• target (const char*) – Ziel-HTML-Element-ID.

• userData (void*) – Benutzerdefinierte Daten, die an den Callback übergeben werden (opak für die API).

• useCapture (bool) – Setzen Sie true, um Capture zu verwenden.

• callback (em_ui_callback_func) – Eine Callback-Funktion. Die Funktion wird mit dem Ereignistyp, Informationen über das Ereignis und Benutzerdaten aufgerufen, die von dieser Registrierungsfunktion übergeben wurden. Der Callback sollte true zurückgeben, wenn das Ereignis konsumiert wurde.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

Fokus

Definiert

EMSCRIPTEN_EVENT_BLUR

EMSCRIPTEN_EVENT_FOCUS

EMSCRIPTEN_EVENT_FOCUSIN

EMSCRIPTEN_EVENT_FOCUSOUT

Emscripten-Fokusereignisse.

Struktur

EmscriptenFocusEvent

Die Ereignisstruktur, die in DOM-Elementen blur-, focus-, focusin- und focusout-Ereignissen übergeben wird.

EM_UTF8 nodeName

Der nodeName des Ziel-HTML-Elements.

Maximale Größe 128 char (d.h. EM_UTF8 nodeName[128]).

EM_UTF8 id

Die ID des Zielelements.

Maximale Größe 128 char (d.h. EM_UTF8 id[128]).

Callback-Funktionen

em_focus_callback_func

Funktionszeiger für die Fokus-Ereignis-Callback-Funktionen, definiert als

typedef bool (*em_focus_callback_func)(int eventType, const EmscriptenFocusEvent *focusEvent, void *userData);

Parameter

• eventType (int) – Der Typ des Fokusereignisses (EMSCRIPTEN_EVENT_BLUR).

• focusEvent (const EmscriptenFocusEvent*) – Informationen über das aufgetretene Fokusereignis.

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

Gibt zurück

true (ungleich Null), um anzuzeigen, dass das Ereignis vom Callback-Handler konsumiert wurde.

Rückgabetyp

bool

Funktionen

EMSCRIPTEN_RESULT emscripten_set_blur_callback(const char *target, void *userData, bool useCapture, em_focus_callback_func callback)

EMSCRIPTEN_RESULT emscripten_set_focus_callback(const char *target, void *userData, bool useCapture, em_focus_callback_func callback)

EMSCRIPTEN_RESULT emscripten_set_focusin_callback(const char *target, void *userData, bool useCapture, em_focus_callback_func callback)

EMSCRIPTEN_RESULT emscripten_set_focusout_callback(const char *target, void *userData, bool useCapture, em_focus_callback_func callback)

Registriert eine Callback-Funktion zum Empfangen von DOM-Element Blur-, Focus-, Focusin- und Focusout-Ereignissen.

Parameter

• target (const char*) – Ziel-HTML-Element-ID.

• userData (void*) – Benutzerdefinierte Daten, die an den Callback übergeben werden (opak für die API).

• useCapture (bool) – Setzen Sie true, um Capture zu verwenden.

• callback (em_focus_callback_func) – Eine Callback-Funktion. Die Funktion wird mit dem Ereignistyp, Informationen über das Ereignis und Benutzerdaten aufgerufen, die von dieser Registrierungsfunktion übergeben wurden. Der Callback sollte true zurückgeben, wenn das Ereignis konsumiert wurde.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

Geräteausrichtung

Definiert

EMSCRIPTEN_EVENT_DEVICEORIENTATION

Emscripten deviceorientation Ereignisse.

Struktur

EmscriptenDeviceOrientationEvent

Die Ereignisstruktur, die im deviceorientation-Ereignis übergeben wird.

double alpha

double beta

double gamma

Die Ausrichtung des Geräts in Bezug auf die Transformation von einem am Erdboden fixierten Koordinatensystem zu einem im Gerät fixierten Koordinatensystem.

Das Bild (Quelle: dev.opera.com) und die Definitionen unten veranschaulichen das Koordinatensystem

• alpha: die Rotation des Geräts um die Z-Achse.

• beta: die Rotation des Geräts um die X-Achse.

• gamma: die Rotation des Geräts um die Y-Achse.

bool absolute

Wenn false, ist die Ausrichtung nur relativ zu einer anderen Basisausrichtung, nicht zu dem festen Koordinatensystem.

Callback-Funktionen

em_deviceorientation_callback_func

Funktionszeiger für die Orientierungsereignis-Callback-Funktionen, definiert als

typedef bool (*em_deviceorientation_callback_func)(int eventType, const EmscriptenDeviceOrientationEvent *deviceOrientationEvent, void *userData);

Parameter

• eventType (int) – Der Typ des Orientierungsereignisses (EMSCRIPTEN_EVENT_DEVICEORIENTATION).

• deviceOrientationEvent (const EmscriptenDeviceOrientationEvent*) – Informationen über das aufgetretene Orientierungsereignis.

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

Gibt zurück

true (ungleich Null), um anzuzeigen, dass das Ereignis vom Callback-Handler konsumiert wurde.

Rückgabetyp

bool

Funktionen

EMSCRIPTEN_RESULT emscripten_set_deviceorientation_callback(void *userData, bool useCapture, em_deviceorientation_callback_func callback)

Registriert eine Callback-Funktion zum Empfangen des deviceorientation-Ereignisses.

Parameter

• userData (void*) – Benutzerdefinierte Daten, die an den Callback übergeben werden (opak für die API).

• useCapture (bool) – Setzen Sie true, um Capture zu verwenden.

• callback (em_deviceorientation_callback_func) – Eine Callback-Funktion. Die Funktion wird mit dem Ereignistyp, Informationen über das Ereignis und Benutzerdaten aufgerufen, die von dieser Registrierungsfunktion übergeben wurden. Der Callback sollte true zurückgeben, wenn das Ereignis konsumiert wurde.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_get_deviceorientation_status(EmscriptenDeviceOrientationEvent *orientationState)

Gibt den zuletzt empfangenen deviceorientation-Ereignisstatus zurück.

Beachten Sie, dass für den Erfolg dieses Funktionsaufrufs emscripten_set_deviceorientation_callback() zuvor mit einem der Mausereignistypen und einem nicht-null Callback-Funktionszeiger aufgerufen worden sein muss, um die deviceorientation-Zustandserfassung zu ermöglichen.

Parameter

• orientationState (EmscriptenDeviceOrientationEvent*) – Der zuletzt empfangene deviceorientation-Ereignisstatus.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

Gerätebewegung

Definiert

EMSCRIPTEN_EVENT_DEVICEMOTION

Emscripten Devicemotion-Ereignis.

Struktur

EmscriptenDeviceMotionEvent

Die Ereignisstruktur, die im Devicemotion-Ereignis übergeben wird.

double accelerationX

double accelerationY

double accelerationZ

Beschleunigung des Geräts ohne Gravitation.

double accelerationIncludingGravityX

double accelerationIncludingGravityY

double accelerationIncludingGravityZ

Beschleunigung des Geräts einschließlich Gravitation.

double rotationRateAlpha

double rotationRateBeta

double rotationRateGamma

Die Rotationsdelta des Geräts.

int supportedFields

Ein Bitfeld, das eine Kombination von EMSCRIPTEN_DEVICE_MOTION_EVENT_SUPPORTS_* Feldern ist, die die verschiedenen Felder dieser Struktur angeben, die der aktuelle Browser unterstützt. Wenn zum Beispiel das EMSCRIPTEN_DEVICE_MOTION_EVENT_SUPPORTS_ACCELERATION Bit in diesem Feld nicht vorhanden ist, dann sollten die accelerationX/Y/Z Felder dieser Struktur als nicht gültig angenommen werden.

Callback-Funktionen

em_devicemotion_callback_func

Funktionszeiger für die Devicemotion-Ereignis-Callback-Funktionen, definiert als

typedef bool (*em_devicemotion_callback_func)(int eventType, const EmscriptenDeviceMotionEvent *deviceMotionEvent, void *userData);

Parameter

• eventType (int) – Der Typ des Devicemotion-Ereignisses (EMSCRIPTEN_EVENT_DEVICEMOTION).

• deviceMotionEvent (const EmscriptenDeviceMotionEvent*) – Informationen über das aufgetretene Devicemotion-Ereignis.

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

Gibt zurück

true (ungleich Null), um anzuzeigen, dass das Ereignis vom Callback-Handler konsumiert wurde.

Rückgabetyp

bool

Funktionen

EMSCRIPTEN_RESULT emscripten_set_devicemotion_callback(void *userData, bool useCapture, em_devicemotion_callback_func callback)

Registriert eine Callback-Funktion zum Empfangen des Devicemotion-Ereignisses.

Parameter

• userData (void*) – Benutzerdefinierte Daten, die an den Callback übergeben werden (opak für die API).

• useCapture (bool) – Setzen Sie true, um Capture zu verwenden.

• callback (em_devicemotion_callback_func) – Eine Callback-Funktion. Die Funktion wird mit dem Ereignistyp, Informationen über das Ereignis und Benutzerdaten aufgerufen, die von dieser Registrierungsfunktion übergeben wurden. Der Callback sollte true zurückgeben, wenn das Ereignis konsumiert wurde.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_get_devicemotion_status(EmscriptenDeviceMotionEvent *motionState)

Gibt den zuletzt empfangenen Devicemotion-Ereignisstatus zurück.

Beachten Sie, dass für den Erfolg dieses Funktionsaufrufs emscripten_set_devicemotion_callback() zuvor mit einem der Mausereignistypen und einem Callback-Funktionszeiger ungleich Null aufgerufen worden sein muss, um die devicemotion-Zustandserfassung zu aktivieren.

Parameter

• motionState (EmscriptenDeviceMotionEvent*) – Der zuletzt empfangene devicemotion-Ereignisstatus.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

Ausrichtung

Definiert

EMSCRIPTEN_EVENT_ORIENTATIONCHANGE

Emscripten orientationchange-Ereignis.

EMSCRIPTEN_ORIENTATION_UNKNOWN

Entweder wird die Orientierungs-API nicht unterstützt oder der Orientierungstyp ist unbekannt.

EMSCRIPTEN_ORIENTATION_PORTRAIT_PRIMARY

Primäre Hochformat-Ausrichtung.

EMSCRIPTEN_ORIENTATION_PORTRAIT_SECONDARY

Sekundäre Hochformat-Ausrichtung.

EMSCRIPTEN_ORIENTATION_LANDSCAPE_PRIMARY

Primäre Querformat-Ausrichtung.

EMSCRIPTEN_ORIENTATION_LANDSCAPE_SECONDARY

Sekundäre Querformat-Ausrichtung.

Struktur

EmscriptenOrientationChangeEvent

Die Ereignisstruktur, die im orientationchange-Ereignis übergeben wird.

int orientationIndex

Eines der EM_ORIENTATION_PORTRAIT_xxx-Felder oder EMSCRIPTEN_ORIENTATION_UNKNOWN, falls unbekannt.

int orientationAngle

Emscripten-spezifische Erweiterung: Einige Browser beziehen sich auf window.orientation, also geben Sie dies auch an.

Orientierungswinkel in Grad. 0: „Standardausrichtung“, d.h. Standard-Aufrechtausrichtung, in der das Mobilgerät gehalten wird. Kann entweder Quer- oder Hochformat sein.

Callback-Funktionen

em_orientationchange_callback_func

Funktionszeiger für die Orientationchange-Ereignis-Callback-Funktionen, definiert als

typedef bool (*em_orientationchange_callback_func)(int eventType, const EmscriptenOrientationChangeEvent *orientationChangeEvent, void *userData);

Parameter

• eventType (int) – Der Typ des Orientationchange-Ereignisses (EMSCRIPTEN_EVENT_ORIENTATIONCHANGE).

• orientationChangeEvent (const EmscriptenOrientationChangeEvent*) – Informationen über das aufgetretene Orientationchange-Ereignis.

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

Gibt zurück

true (ungleich Null), um anzuzeigen, dass das Ereignis vom Callback-Handler konsumiert wurde.

Rückgabetyp

bool

Funktionen

EMSCRIPTEN_RESULT emscripten_set_orientationchange_callback(void *userData, bool useCapture, em_orientationchange_callback_func callback)

Registriert eine Callback-Funktion zum Empfangen des orientationchange-Ereignisses.

Parameter

• userData (void*) – Benutzerdefinierte Daten, die an den Callback übergeben werden (opak für die API).

• useCapture (bool) – Setzen Sie true, um Capture zu verwenden.

• callback (em_orientationchange_callback_func) – Eine Callback-Funktion. Die Funktion wird mit dem Ereignistyp, Informationen über das Ereignis und Benutzerdaten aufgerufen, die von dieser Registrierungsfunktion übergeben wurden. Der Callback sollte true zurückgeben, wenn das Ereignis verbraucht wird.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_get_orientation_status(EmscriptenOrientationChangeEvent *orientationStatus)

Gibt den aktuellen Status der Geräteausrichtung zurück.

Parameter

• orientationStatus (EmscriptenOrientationChangeEvent*) – Der zuletzt empfangene Ausrichtungsstatus.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_lock_orientation(int allowedOrientations)

Sperrt die Bildschirmausrichtung auf den angegebenen Satz von allowed orientations.

Parameter

• allowedOrientations (int) – Ein Bitfeld-Satz von EMSCRIPTEN_ORIENTATION_xxx-Flags.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_unlock_orientation(void)

Entfernt die Ausrichtungssperre, sodass der Bildschirm in jede Ausrichtung gedreht werden kann.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

Vollbild

Definiert

EMSCRIPTEN_EVENT_FULLSCREENCHANGE

Emscripten fullscreenchange-Ereignis.

EMSCRIPTEN_FULLSCREEN_SCALE

Ein enum-ähnlicher Typ, der angibt, wie die Emscripten-Laufzeit die CSS-Größe des Zielelements behandeln soll, wenn es im Vollbildmodus über Aufrufe der Funktionen emscripten_request_fullscreen_strategy() und emscripten_enter_soft_fullscreen() angezeigt wird.

EMSCRIPTEN_FULLSCREEN_SCALE_DEFAULT

Gibt an, dass das DOM-Element von der Emscripten-Laufzeit beim Übergang zwischen Vollbild- und Fenstermodus nicht in der Größe geändert werden sollte. Der Browser ist für die Skalierung des DOM-Elements auf die Vollbildgröße verantwortlich. Das korrekte Browserverhalten in diesem Modus ist es, das Element zu strecken, um die gesamte Anzeige unter Ignorierung des Seitenverhältnisses auszufüllen, aber zum Zeitpunkt des Schreibens implementieren Browser hier unterschiedliche Verhaltensweisen. Weitere Informationen finden Sie in der Diskussion unter https://github.com/emscripten-core/emscripten/issues/2556.

EMSCRIPTEN_FULLSCREEN_SCALE_STRETCH

Gibt an, dass die Emscripten-Laufzeit die CSS-Größe des Zielelements explizit dehnen sollte, um den gesamten Bildschirm beim Übergang in den Vollbildmodus abzudecken. Dies ändert das Seitenverhältnis des angezeigten Inhalts.

EMSCRIPTEN_FULLSCREEN_SCALE_ASPECT

Gibt an, dass die Emscripten-Laufzeit die CSS-Größe des Zielelements explizit skalieren sollte, um den gesamten Bildschirm abzudecken, während entweder vertikale oder horizontale schwarze Letterbox-Polsterung hinzugefügt wird, um das Seitenverhältnis des Inhalts zu erhalten. Das hier verwendete Seitenverhältnis ist die Renderzielgröße des Canvas-Elements. Um das gewünschte Seitenverhältnis zu ändern, rufen Sie emscripten_set_canvas_element_size() auf, bevor Sie in den Vollbildmodus wechseln.

EMSCRIPTEN_FULLSCREEN_CANVAS_SCALE

Ein enum-ähnlicher Typ, der angibt, wie die Emscripten-Laufzeit die Pixelgröße (Renderzielauflösung) des Ziel-Canvas-Elements behandeln soll, wenn es im Vollbildmodus über Aufrufe der Funktionen emscripten_request_fullscreen_strategy() und emscripten_enter_soft_fullscreen() angezeigt wird. Um den zugrundeliegenden Unterschied zwischen der CSS-Größe eines Canvas-Elements und der Renderzielgröße eines Canvas-Elements besser zu verstehen, siehe https://www.khronos.org/webgl/wiki/HandlingHighDPI.

EMSCRIPTEN_FULLSCREEN_CANVAS_SCALE_NONE

Gibt an, dass die Emscripten-Laufzeit keine Änderungen an der Renderzielauflösung des Ziel-Canvas-Elements vornehmen sollte, das im Vollbildmodus angezeigt wird. Verwenden Sie diesen Modus, wenn Ihre Anwendung so eingerichtet ist, dass sie in einer einzigen festen Auflösung rendert, die unter keinen Umständen geändert werden kann.

EMSCRIPTEN_FULLSCREEN_CANVAS_SCALE_STDDEF

Gibt an, dass die Emscripten-Laufzeit das Renderziel des Canvas-Elements so anpassen sollte, dass es im Vollbildmodus 1:1 mit der CSS-Größe des Elements übereinstimmt. Auf hochauflösenden Displays (window.devicePixelRatio > 1) ist die CSS-Größe nicht identisch mit der physischen Bildschirmauflösung des Geräts. Rufen Sie emscripten_get_device_pixel_ratio() auf, um das Pixelverhältnis zwischen CSS-Pixeln und tatsächlichen Gerätepixeln des Bildschirms zu erhalten. Verwenden Sie diesen Modus, wenn Sie in einer DPI-unabhängigen Pixelauflösung rendern möchten.

EMSCRIPTEN_FULLSCREEN_CANVAS_SCALE_HIDEF

Gibt an, dass die Emscripten-Laufzeit die Größe des Canvas-Renderziels so anpassen sollte, dass sie 1:1 mit der physischen Bildschirmauflösung auf dem Gerät übereinstimmt. Dies entspricht hochauflösenden Displays auf Retina iOS und anderen mobilen und Desktop-Geräten mit hoher DPI. Verwenden Sie diesen Modus, um die native Displayauflösung 1:1 anzupassen und zu rendern.

EMSCRIPTEN_FULLSCREEN_FILTERING

Ein enum-ähnlicher Typ, der angibt, welcher Bildfilteralgorithmus auf das Element angewendet werden soll, wenn es im Vollbildmodus präsentiert wird.

EMSCRIPTEN_FULLSCREEN_FILTERING_DEFAULT

Gibt an, dass der Bildfiltermodus nicht von der bestehenden Einstellung im CSS-Stil geändert werden sollte.

EMSCRIPTEN_FULLSCREEN_FILTERING_NEAREST

Wendet einen CSS-Stil auf das Element an, der den Inhalt im Vollbildmodus mithilfe eines Nearest-Neighbor-Bildfilteralgorithmus anzeigt.

EMSCRIPTEN_FULLSCREEN_FILTERING_BILINEAR

Wendet einen CSS-Stil auf das Element an, der den Inhalt im Vollbildmodus mithilfe eines bilinearen Bildfilteralgorithmus anzeigt. Dies ist das Standardverhalten des Browsers.

Struktur

EmscriptenFullscreenChangeEvent

Die Ereignisstruktur, die im fullscreenchange-Ereignis übergeben wird.

bool isFullscreen

Gibt an, ob ein Element auf der Browserseite derzeit im Vollbildmodus angezeigt wird.

bool fullscreenEnabled

Gibt an, ob die aktuelle Seite die Möglichkeit hat, Elemente im Vollbildmodus anzuzeigen.

EM_UTF8 nodeName

Der nodeName des Ziel-HTML-Elements, das sich im Vollbildmodus befindet.

Maximale Größe 128 char (d.h. EM_UTF8 nodeName[128]).

Wenn isFullscreen false ist, dann geben nodeName, id und elementWidth und elementHeight Informationen über das Element an, das gerade den Vollbildmodus verlassen hat.

EM_UTF8 id

Die ID des Ziel-HTML-Elements, das sich im Vollbildmodus befindet.

Maximale Größe 128 char (d.h. EM_UTF8 id[128]).

int elementWidth

int elementHeight

Die neue Pixelgröße des Elements, dessen Vollbildstatus sich geändert hat.

int screenWidth

int screenHeight

Die Größe des gesamten Bildschirms, in Pixeln.

EmscriptenFullscreenStrategy

Die Optionsstruktur, die an die Funktionen emscripten_request_fullscreen_strategy() und emscripten_enter_soft_fullscreen() übergeben wird, um zu konfigurieren, wie das Zielelement im Vollbildmodus angezeigt werden soll.

EMSCRIPTEN_FULLSCREEN_SCALE scaleMode

Gibt die Regel an, wie die CSS-Größe (die angezeigte Größe) des Zielelements bei der Anzeige im Vollbildmodus angepasst wird.

EMSCRIPTEN_FULLSCREEN_CANVAS_SCALE canvasResolutionScaleMode

Gibt an, wie die Renderzielgröße (die Pixelauflösung) des Zielelements angepasst wird, wenn es im Vollbildmodus angezeigt wird.

EMSCRIPTEN_FULLSCREEN_FILTERING filteringMode

Gibt den Bildfilteralgorithmus an, der auf das Element im Vollbildmodus angewendet werden soll.

em_canvasresized_callback_func canvasResizedCallback

Wenn ungleich Null, verweist auf eine vom Benutzer bereitgestellte Callback-Funktion, die aufgerufen wird, wenn sich entweder die CSS- oder die Canvas-Renderzielgröße ändert. Verwenden Sie diesen Callback, um zuverlässig Informationen über Canvas-Größenänderungsereignisse zu erhalten.

void *canvasResizedCallbackUserData

Speichert ein benutzerdefiniertes Datenfeld, das an alle Aufrufe der vom Benutzer bereitgestellten Callback-Funktion übergeben wird.

Callback-Funktionen

em_fullscreenchange_callback_func

Funktionszeiger für die fullscreen event callback functions, definiert als

typedef bool (*em_fullscreenchange_callback_func)(int eventType, const EmscriptenFullscreenChangeEvent *fullscreenChangeEvent, void *userData);

Parameter

• eventType (int) – Der Typ des Vollbildereignisses (EMSCRIPTEN_EVENT_FULLSCREENCHANGE).

• fullscreenChangeEvent (const EmscriptenFullscreenChangeEvent*) – Informationen über das aufgetretene Vollbildereignis.

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

Gibt zurück

true (ungleich Null), um anzuzeigen, dass das Ereignis vom Callback-Handler konsumiert wurde.

Rückgabetyp

bool

Funktionen

EMSCRIPTEN_RESULT emscripten_set_fullscreenchange_callback(const char *target, void *userData, bool useCapture, em_fullscreenchange_callback_func callback)

Registriert eine Callback-Funktion zum Empfangen des fullscreenchange-Ereignisses.

Parameter

• target (const char*) – Ziel-HTML-Element-ID.

• userData (void*) – Benutzerdefinierte Daten, die an den Callback übergeben werden (opak für die API).

• useCapture (bool) – Setzen Sie true, um Capture zu verwenden.

• callback (em_fullscreenchange_callback_func) – Eine Callback-Funktion. Die Funktion wird mit dem Ereignistyp, Informationen über das Ereignis und Benutzerdaten aufgerufen, die von dieser Registrierungsfunktion übergeben wurden. Der Callback sollte true zurückgeben, wenn das Ereignis verbraucht wird.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_get_fullscreen_status(EmscriptenFullscreenChangeEvent *fullscreenStatus)

Gibt den aktuellen Vollbildstatus der Seite zurück.

Parameter

• fullscreenStatus (EmscriptenFullscreenChangeEvent*) – Der zuletzt empfangene Vollbildstatus.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_request_fullscreen(const char *target, bool deferUntilInEventHandler)

Fordert das angegebene Zielelement an, in den Vollbildmodus zu wechseln.

Hinweis

Diese Funktion kann überall aufgerufen werden, aber aus Gründen der Web-Sicherheit kann ihre zugehörige Anfrage nur innerhalb des Ereignishandlers für ein benutzergeneriertes Ereignis (z. B. Tastatur-, Maus- oder Berührungsdruck/-freigabe) ausgelöst werden. Dies hat Auswirkungen auf die Portierung und den Wert von deferUntilInEventHandler — siehe Funktionen, die von der Web-Sicherheit betroffen sind für weitere Informationen.

Hinweis

Diese Funktion führt lediglich eine Vollbildanfrage durch, ohne Parameter des DOM-Elements zu ändern, das im Vollbildmodus angezeigt werden soll. Zum Zeitpunkt des Schreibens gibt es Unterschiede in der Art und Weise, wie Browser Elemente im Vollbildmodus darstellen. Weitere Informationen finden Sie in der Diskussion unter https://github.com/emscripten-core/emscripten/issues/2556. Um ein Element im Vollbildmodus browserübergreifend konsistent anzuzeigen, bevorzugen Sie stattdessen den Aufruf der Funktion emscripten_request_fullscreen_strategy(). Diese Funktion sollte am besten nur in Szenarien aufgerufen werden, in denen die vorkonfigurierten Voreinstellungen, die durch emscripten_request_fullscreen_strategy() definiert sind, in irgendeiner Weise mit dem Anwendungsfall des Entwicklers kollidieren.

Parameter

• target (const char*) – Ziel-HTML-Element-ID.

• deferUntilInEventHandler (bool) – Wenn true, werden Anfragen, die außerhalb eines benutzergenerierten Ereignishandlers gestellt werden, automatisch auf das nächste Drücken einer Tastatur- oder Maustaste durch den Benutzer verschoben. Wenn false, schlägt die Anfrage fehl, wenn sie außerhalb eines benutzergenerierten Ereignishandlers aufgerufen wird.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_request_fullscreen_strategy(const char *target, bool deferUntilInEventHandler, const EmscriptenFullscreenStrategy *fullscreenStrategy)

Fordert das angegebene Zielelement an, in den Vollbildmodus zu wechseln, wobei ein benutzerdefinierter Präsentationsmodus für das Element verwendet wird. Diese Funktion ist ansonsten identisch mit emscripten_request_fullscreen(), aber diese Funktion fügt Optionen zur Steuerung von Größenänderung und Seitenverhältnis hinzu und stellt sicher, dass das Verhalten browserübergreifend konsistent ist.

Hinweis

Diese Funktion nimmt Änderungen am DOM vor, um eine konsistente Darstellung über Browser hinweg zu gewährleisten. Diese Änderungen wurden so konzipiert, dass sie so wenig wie möglich stören, und die Änderungen werden gelöscht, sobald das Browsen im Fenster wiederhergestellt ist. Wenn eine dieser Änderungen in Konflikt steht, siehe stattdessen die Funktion emscripten_request_fullscreen(), die eine bloße Vollbildanfrage ohne Änderungen am DOM durchführt.

Parameter

• fullscreenStrategy (const EmscriptenFullscreenStrategy*) – [in] Verweist auf eine vom Aufrufer gefüllte Konfigurationsstruktur, die Anzeigeoptionen für den Vollbildmodus angibt.

EMSCRIPTEN_RESULT emscripten_exit_fullscreen(void)

Kehrt aus einem echten Vollbildmodus in den Fenstermodus zurück.

Rufen Sie diese Funktion nicht auf, um zu versuchen, aus einem Soft-Vollbildmodus in den Fenstermodus zurückzukehren oder umgekehrt.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_enter_soft_fullscreen(const char *target, const EmscriptenFullscreenStrategy *fullscreenStrategy)

Aktiviert einen "Soft"-Vollbildmodus, bei dem das angegebene Zielelement im gesamten Clientbereich der Seite angezeigt und alle anderen Elemente ausgeblendet werden, aber nicht tatsächlich der Vollbildmodus für den Browser angefordert wird. Diese Funktion ist nützlich in Fällen, in denen die eigentliche Fullscreen API nicht wünschenswert oder erforderlich ist, z. B. in gepackten Apps für Firefox OS, wo Anwendungen im Wesentlichen bereits den gesamten Bildschirm abdecken.

Das Drücken der Esc-Taste beendet den Soft-Vollbildmodus nicht automatisch. Um in den Fenstermodus zurückzukehren, rufen Sie manuell die Funktion emscripten_exit_soft_fullscreen() auf.

EMSCRIPTEN_RESULT emscripten_exit_soft_fullscreen()

Kehrt aus einem Soft-Vollbildmodus in den Fenstermodus zurück. Rufen Sie diese Funktion nicht auf, um zu versuchen, aus einem echten Vollbildmodus in den Fenstermodus zurückzukehren oder umgekehrt.

Zeiger-Sperre

Definiert

EMSCRIPTEN_EVENT_POINTERLOCKCHANGE

Emscripten pointerlockchange Ereignis.

EMSCRIPTEN_EVENT_POINTERLOCKERROR

Emscripten pointerlockerror Ereignis.

Struktur

EmscriptenPointerlockChangeEvent

Die Ereignisstruktur, die im pointerlockchange-Ereignis übergeben wird.

bool isActive

Gibt an, ob ein Element auf der Browserseite derzeit eine Zeigersperre aktiviert hat.

EM_UTF8 nodeName

Der nodeName des Ziel-HTML-Elements, das die Zeigersperre aktiv hat.

Maximale Größe 128 char (d.h. EM_UTF8 nodeName[128]).

EM_UTF8 id

Die ID des Ziel-HTML-Elements, das die Zeigersperre aktiv hat.

Maximale Größe 128 char (d.h. EM_UTF8 id[128]).

Callback-Funktionen

em_pointerlockchange_callback_func

Funktionszeiger für die pointerlockchange event callback functions, definiert als

typedef bool (*em_pointerlockchange_callback_func)(int eventType, const EmscriptenPointerlockChangeEvent *pointerlockChangeEvent, void *userData);

Parameter

• eventType (int) – Der Typ des Pointerlockchange-Ereignisses (EMSCRIPTEN_EVENT_POINTERLOCKCHANGE).

• pointerlockChangeEvent (const EmscriptenPointerlockChangeEvent*) – Informationen über das aufgetretene Pointerlockchange-Ereignis.

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

Gibt zurück

true (ungleich Null), um anzuzeigen, dass das Ereignis vom Callback-Handler konsumiert wurde.

Rückgabetyp

bool

em_pointerlockerror_callback_func

Funktionszeiger für die pointerlockerror event callback functions, definiert als

typedef bool (*em_pointerlockerror_callback_func)(int eventType, const void *reserved, void *userData);

Parameter

• eventType (int) – Der Typ des Pointerlockerror-Ereignisses (EMSCRIPTEN_EVENT_POINTERLOCKERROR).

• void* reserved (const) – Für zukünftige Verwendung reserviert; Übergabe von 0.

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

Gibt zurück

true (ungleich Null), um anzuzeigen, dass das Ereignis vom Callback-Handler konsumiert wurde.

Rückgabetyp

bool

Funktionen

EMSCRIPTEN_RESULT emscripten_set_pointerlockchange_callback(const char *target, void *userData, bool useCapture, em_pointerlockchange_callback_func callback)

Registriert eine Callback-Funktion zum Empfangen des pointerlockchange-Ereignisses.

Pointer Lock blendet den Mauszeiger aus und gibt dem Zielelement ausschließlich relative Mausbewegungsereignisse über das mousemove-Ereignis.

Parameter

• target (const char*) – Ziel-HTML-Element-ID.

• userData (void*) – Benutzerdefinierte Daten, die an den Callback übergeben werden (opak für die API).

• useCapture (bool) – Setzen Sie true, um Capture zu verwenden.

• callback (em_pointerlockchange_callback_func) – Eine Callback-Funktion. Die Funktion wird mit dem Ereignistyp, Informationen über das Ereignis und Benutzerdaten aufgerufen, die von dieser Registrierungsfunktion übergeben wurden. Der Callback sollte true zurückgeben, wenn das Ereignis verbraucht wird.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_set_pointerlockerror_callback(const char *target, void *userData, bool useCapture, em_pointerlockerror_callback_func callback)

Registriert eine Callback-Funktion zum Empfangen des pointerlockerror-Ereignisses.

Parameter

• target (const char*) – Ziel-HTML-Element-ID.

• userData (void*) – Benutzerdefinierte Daten, die an den Callback übergeben werden (opak für die API).

• useCapture (bool) – Setzen Sie true, um Capture zu verwenden.

• callback (em_pointerlockerror_callback_func) – Eine Callback-Funktion. Die Funktion wird mit dem Ereignistyp, Informationen über das Ereignis und Benutzerdaten aufgerufen, die von dieser Registrierungsfunktion übergeben wurden. Der Callback sollte true zurückgeben, wenn das Ereignis verbraucht wird.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_get_pointerlock_status(EmscriptenPointerlockChangeEvent *pointerlockStatus)

Gibt den aktuellen Zeigersperrstatus der Seite zurück.

Parameter

• pointerlockStatus (EmscriptenPointerlockChangeEvent*) – Der zuletzt empfangene Zeigersperrstatus.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_request_pointerlock(const char *target, bool deferUntilInEventHandler)

Fordert das angegebene Zielelement an, die Zeigersperre zu übernehmen.

Hinweis

Diese Funktion kann überall aufgerufen werden, aber aus Gründen der Web-Sicherheit kann ihre zugehörige Anfrage nur innerhalb des Ereignishandlers für ein benutzergeneriertes Ereignis (z. B. Tastatur-, Maus- oder Berührungsdruck/-freigabe) ausgelöst werden. Dies hat Auswirkungen auf die Portierung und den Wert von deferUntilInEventHandler — siehe Funktionen, die von der Web-Sicherheit betroffen sind für weitere Informationen.

Parameter

• target (const char*) – Ziel-HTML-Element-ID.

• deferUntilInEventHandler (bool) – Wenn true, werden Anfragen, die außerhalb eines benutzergenerierten Ereignishandlers gestellt werden, automatisch auf das nächste Drücken einer Tastatur- oder Maustaste durch den Benutzer verschoben. Wenn false, schlägt die Anfrage fehl, wenn sie außerhalb eines benutzergenerierten Ereignishandlers aufgerufen wird.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_exit_pointerlock(void)

Beendet den Zeigersperrzustand und stellt die Sichtbarkeit des Mauszeigers wieder her.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

Sichtbarkeit

Definiert

EMSCRIPTEN_EVENT_VISIBILITYCHANGE

Emscripten visibilitychange-Ereignis.

EMSCRIPTEN_VISIBILITY_HIDDEN

Das Dokument ist verborgen (nicht sichtbar).

EMSCRIPTEN_VISIBILITY_VISIBLE

Das Dokument ist zumindest teilweise sichtbar.

EMSCRIPTEN_VISIBILITY_PRERENDER

Das Dokument wird außerhalb des Bildschirms geladen und ist nicht sichtbar (prerender).

EMSCRIPTEN_VISIBILITY_UNLOADED

Das Dokument soll entladen werden.

Struktur

EmscriptenVisibilityChangeEvent

Die Ereignisstruktur, die im visibilitychange-Ereignis übergeben wird.

bool hidden

Wenn wahr, ist die aktuelle Browserseite jetzt ausgeblendet.

int visibilityState

Gibt einen feineren Status des aktuellen Seiten-Sichtbarkeitsstatus an. Einer der EMSCRIPTEN_VISIBILITY_-Werte.

Callback-Funktionen

em_visibilitychange_callback_func

Funktionszeiger für die visibilitychange event callback functions, definiert als

typedef bool (*em_visibilitychange_callback_func)(int eventType, const EmscriptenVisibilityChangeEvent *visibilityChangeEvent, void *userData);

Parameter

• eventType (int) – Der Typ des visibilitychange-Ereignisses (EMSCRIPTEN_VISIBILITY_HIDDEN).

• visibilityChangeEvent (const EmscriptenVisibilityChangeEvent*) – Informationen über das aufgetretene visibilitychange-Ereignis.

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

Gibt zurück

true (ungleich Null), um anzuzeigen, dass das Ereignis vom Callback-Handler konsumiert wurde.

Rückgabetyp

bool

Funktionen

EMSCRIPTEN_RESULT emscripten_set_visibilitychange_callback(void *userData, bool useCapture, em_visibilitychange_callback_func callback)

Registriert eine Callback-Funktion zum Empfangen des visibilitychange-Ereignisses.

Parameter

• userData (void*) – Benutzerdefinierte Daten, die an den Callback übergeben werden (opak für die API).

• useCapture (bool) – Setzen Sie true, um Capture zu verwenden.

• callback (em_visibilitychange_callback_func) – Eine Callback-Funktion. Die Funktion wird mit dem Ereignistyp, Informationen über das Ereignis und Benutzerdaten aufgerufen, die von dieser Registrierungsfunktion übergeben wurden. Der Callback sollte true zurückgeben, wenn das Ereignis verbraucht wird.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_get_visibility_status(EmscriptenVisibilityChangeEvent *visibilityStatus)

Gibt den aktuellen Sichtbarkeitsstatus der Seite zurück.

Parameter

• visibilityStatus (EmscriptenVisibilityChangeEvent*) – Der zuletzt empfangene Seiten-Sichtbarkeitsstatus.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

Berührung

Definiert

EMSCRIPTEN_EVENT_TOUCHSTART

EMSCRIPTEN_EVENT_TOUCHEND

EMSCRIPTEN_EVENT_TOUCHMOVE

EMSCRIPTEN_EVENT_TOUCHCANCEL

Emscripten-Touch-Events.

Struktur

EmscriptenTouchPoint

Gibt den Status eines einzelnen Touch-Punkts auf der Seite an.

long identifier

Eine Identifikationsnummer für jeden Touch-Punkt.

long screenX

long screenY

Die Berührungskoordinate relativ zum Ursprung des gesamten Bildschirms, in Pixeln.

long clientX

long clientY

Die Berührungskoordinate relativ zum Viewport, in Pixeln.

long pageX

long pageY

Die Berührungskoordinate relativ zum Viewport, in Pixeln, und einschließlich eines eventuellen Scroll-Offsets.

bool isChanged

Gibt an, ob sich der Touch-Punkt während dieses Ereignisses geändert hat.

bool onTarget

Gibt an, ob dieser Touch-Punkt immer noch über dem ursprünglichen Ziel liegt, auf dem er ursprünglich gedrückt wurde.

long targetX

long targetY

Diese Felder geben die Touch-Koordinaten relativ zum Koordinatenraum des Ziel-DOM-Elements an, das die Eingabeereignisse empfängt (Emscripten-spezifische Erweiterung).

long canvasX

long canvasY

Die Touch-Koordinaten, die auf den Emscripten-Canvas-Clientbereich abgebildet sind, in Pixeln (Emscripten-spezifische Erweiterung).

EmscriptenTouchEvent

Gibt die Daten eines einzelnen Touch-Ereignisses an.

double timestamp

Absolute Wanduhrzeit, zu der die Daten aufgezeichnet wurden (Millisekunden).

int numTouches

Die Anzahl der gültigen Elemente im touches-Array.

bool ctrlKey

bool shiftKey

bool altKey

bool metaKey

Gibt an, welche Modifier-Tasten während des Touch-Ereignisses aktiv waren.

EmscriptenTouchPoint touches[32]

Ein Array der aktuell aktiven Berührungen, eine für jeden Finger.

Callback-Funktionen

em_touch_callback_func

Funktionszeiger für die Touch-Ereignis-Callback-Funktionen, definiert als

typedef bool (*em_touch_callback_func)(int eventType, const EmscriptenTouchEvent *touchEvent, void *userData);

Parameter

• eventType (int) – Der Typ des Touch-Ereignisses (EMSCRIPTEN_EVENT_TOUCHSTART).

• touchEvent (const EmscriptenTouchEvent*) – Informationen über das aufgetretene Touch-Ereignis.

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

Gibt zurück

true (ungleich Null), um anzuzeigen, dass das Ereignis vom Callback-Handler konsumiert wurde.

Rückgabetyp

bool

Funktionen

EMSCRIPTEN_RESULT emscripten_set_touchstart_callback(const char *target, void *userData, bool useCapture, em_touch_callback_func callback)

EMSCRIPTEN_RESULT emscripten_set_touchend_callback(const char *target, void *userData, bool useCapture, em_touch_callback_func callback)

EMSCRIPTEN_RESULT emscripten_set_touchmove_callback(const char *target, void *userData, bool useCapture, em_touch_callback_func callback)

EMSCRIPTEN_RESULT emscripten_set_touchcancel_callback(const char *target, void *userData, bool useCapture, em_touch_callback_func callback)

Registriert eine Callback-Funktion zum Empfangen von Touch-Ereignissen: touchstart, touchend, touchmove und touchcancel.

Parameter

• target (const char*) – Ziel-HTML-Element-ID.

• userData (void*) – Benutzerdefinierte Daten, die an den Callback übergeben werden (opak für die API).

• useCapture (bool) – Setzen Sie true, um Capture zu verwenden.

• callback (em_touch_callback_func) – Eine Callback-Funktion. Die Funktion wird mit dem Ereignistyp, Informationen über das Ereignis und Benutzerdaten aufgerufen, die von dieser Registrierungsfunktion übergeben wurden. Der Callback sollte true zurückgeben, wenn das Ereignis verbraucht wird.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

Gamepad

Definiert

EMSCRIPTEN_EVENT_GAMEPADCONNECTED

EMSCRIPTEN_EVENT_GAMEPADDISCONNECTED

Emscripten Gamepad-Ereignisse.

Struktur

EmscriptenGamepadEvent

Repräsentiert den aktuellen Momentaufnahme-Status eines Gamepads.

double timestamp

Absolute Wanduhrzeit, zu der die Daten aufgezeichnet wurden (Millisekunden).

int numAxes

Die Anzahl der gültigen Achseneinträge im axis-Array.

int numButtons

Die Anzahl der gültigen Tasten-Einträge in den Arrays analogButton und digitalButton.

double axis[64]

Der analoge Zustand der Gamepad-Achsen im Bereich [-1, 1].

double analogButton[64]

Der analoge Zustand der Gamepad-Tasten im Bereich [0, 1].

bool digitalButton[64]

Der digitale Zustand der Gamepad-Tasten, entweder 0 oder 1.

bool connected

Gibt an, ob dieses Gamepad mit der Browserseite verbunden ist.

long index

Eine Ordnungszahl, die diesem Gamepad zugeordnet ist, nullbasiert.

EM_UTF8 id

Eine ID für die Marke oder den Stil des verbundenen Gamepad-Geräts. Typischerweise enthält diese die USB-Hersteller- und eine Produkt-ID.

Maximale Größe 64 char (d.h. EM_UTF8 id[64]).

EM_UTF8 mapping

Eine Zeichenfolge, die das Layout oder die Steuerungsbelegung dieses Geräts identifiziert.

Maximale Größe 64 char (d.h. EM_UTF8 mapping[64]).

Callback-Funktionen

em_gamepad_callback_func

Funktionszeiger für die Gamepad-Ereignis-Callback-Funktionen, definiert als

typedef bool (*em_gamepad_callback_func)(int eventType, const EmscriptenGamepadEvent *gamepadEvent, void *userData)

Parameter

• eventType (int) – Der Typ des Gamepad-Ereignisses (EMSCRIPTEN_EVENT_GAMEPADCONNECTED).

• gamepadEvent (const EmscriptenGamepadEvent*) – Informationen über das aufgetretene Gamepad-Ereignis.

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

Gibt zurück

true (ungleich Null), um anzuzeigen, dass das Ereignis vom Callback-Handler konsumiert wurde.

Rückgabetyp

bool

Funktionen

EMSCRIPTEN_RESULT emscripten_set_gamepadconnected_callback(void *userData, bool useCapture, em_gamepad_callback_func callback)

EMSCRIPTEN_RESULT emscripten_set_gamepaddisconnected_callback(void *userData, bool useCapture, em_gamepad_callback_func callback)

Registriert eine Callback-Funktion zum Empfangen der Gamepad-Ereignisse: gamepadconnected und gamepaddisconnected.

Parameter

• userData (void*) – Benutzerdefinierte Daten, die an den Callback übergeben werden (opak für die API).

• useCapture (bool) – Setzen Sie true, um Capture zu verwenden.

• callback (em_gamepad_callback_func) – Eine Callback-Funktion. Die Funktion wird mit dem Ereignistyp, Informationen über das Ereignis und Benutzerdaten aufgerufen, die von dieser Registrierungsfunktion übergeben wurden. Der Callback sollte true zurückgeben, wenn das Ereignis verbraucht wird.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_sample_gamepad_data(void)

Diese Funktion nimmt einen neuen Status der verbundenen Gamepad-Daten auf und gibt entweder EMSCRIPTEN_RESULT_SUCCESS zurück, wenn die Gamepad-API vom aktuellen Browser unterstützt wird, oder EMSCRIPTEN_RESULT_NOT_SUPPORTED, wenn die Gamepad-API nicht unterstützt wird. Beachten Sie, dass selbst wenn EMSCRIPTEN_RESULT_SUCCESS zurückgegeben wird, möglicherweise noch keine Gamepads mit dem aktuellen Browser-Tab verbunden sind.

Rufen Sie diese Funktion auf, bevor Sie eine der Funktionen emscripten_get_num_gamepads() oder emscripten_get_gamepad_status() aufrufen.

int emscripten_get_num_gamepads(void)

Nachdem emscripten_sample_gamepad_data() aufgerufen wurde, gibt diese Funktion die Anzahl der an das System angeschlossenen Gamepads oder EMSCRIPTEN_RESULT_NOT_SUPPORTED zurück, wenn der aktuelle Browser keine Gamepads unterstützt.

Hinweis

Ein Gamepad wird erst als verbunden angezeigt, wenn eine Taste darauf gedrückt wird.

Hinweis

Die Gamepad-API verwendet ein Array von Gamepad-Zustandsobjekten, um den Zustand jedes Geräts zurückzugeben. Die Geräte werden über ihren Index in diesem Array identifiziert. Aus diesem Grund, wenn man zuerst Gamepad A, dann Gamepad B verbindet und dann Gamepad A trennt, soll Gamepad B nicht den Platz von Gamepad A einnehmen, so dass in diesem Szenario diese Funktion immer noch zwei für die Anzahl der verbundenen Gamepads zurückgeben wird, auch wenn Gamepad A nicht mehr vorhanden ist. Um die tatsächliche Anzahl der verbundenen Gamepads zu finden, hören Sie auf die gamepadconnected- und gamepaddisconnected-Ereignisse. Betrachten Sie den Rückgabewert der Funktion emscripten_get_num_gamepads() minus eins als den größten Indexwert, der an die Funktion emscripten_get_gamepad_status() übergeben werden kann.

Gibt zurück

Die Anzahl der Gamepads, die mit dem Browser-Tab verbunden sind.

Rückgabetyp

int

EMSCRIPTEN_RESULT emscripten_get_gamepad_status(int index, EmscriptenGamepadEvent *gamepadState)

Nach dem Aufruf von emscripten_sample_gamepad_data() gibt diese Funktion eine Momentaufnahme des aktuellen Gamepad-Zustands für den Gamepad-Controller am angegebenen Index des Controller-Arrays zurück.

Parameter

• index (int) – Der Index des zu überprüfenden Gamepads (im Array der verbundenen Gamepads).

• gamepadState (EmscriptenGamepadEvent*) – Der zuletzt empfangene Gamepad-Status.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

Batterie

Definiert

EMSCRIPTEN_EVENT_BATTERYCHARGINGCHANGE

EMSCRIPTEN_EVENT_BATTERYLEVELCHANGE

Emscripten Batteriemanager-Ereignisse.

Struktur

EmscriptenBatteryEvent

Die Ereignisstruktur, die in den Batteriemanager-Ereignissen übergeben wird: chargingchange und levelchange.

double chargingTime

Verbleibende Zeit bis zur vollständigen Aufladung des Akkus (Sekunden).

double dischargingTime

Verbleibende Zeit, bis der Akku leer ist und das System in den Standby-Modus versetzt wird (Sekunden).

double level

Aktueller Akkustand, auf einer Skala von 0 bis 1,0.

bool charging;

true, wenn der Akku geladen wird, false andernfalls.

Callback-Funktionen

em_battery_callback_func

Funktionszeiger für die Batteriemanager-Ereignis-Callback-Funktionen, definiert als

typedef bool (*em_battery_callback_func)(int eventType, const EmscriptenBatteryEvent *batteryEvent, void *userData);

Parameter

• eventType (int) – Der Typ des batterymanager-Ereignisses (EMSCRIPTEN_EVENT_BATTERYCHARGINGCHANGE).

• batteryEvent (const EmscriptenBatteryEvent*) – Informationen über das aufgetretene batterymanager-Ereignis.

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

Gibt zurück

true (ungleich Null), um anzuzeigen, dass das Ereignis vom Callback-Handler konsumiert wurde.

Rückgabetyp

bool

Funktionen

EMSCRIPTEN_RESULT emscripten_set_batterychargingchange_callback(void *userData, em_battery_callback_func callback)

EMSCRIPTEN_RESULT emscripten_set_batterylevelchange_callback(void *userData, em_battery_callback_func callback)

Registriert eine Callback-Funktion zum Empfangen der Batteriemanager-Ereignisse: chargingchange und levelchange.

Parameter

• userData (void*) – Benutzerdefinierte Daten, die an den Callback übergeben werden (opak für die API).

• callback (em_battery_callback_func) – Eine Callback-Funktion. Die Funktion wird mit dem Ereignistyp, Informationen über das Ereignis und Benutzerdaten aufgerufen, die von dieser Registrierungsfunktion übergeben wurden. Der Callback sollte true zurückgeben, wenn das Ereignis verbraucht wird.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_get_battery_status(EmscriptenBatteryEvent *batteryState)

Gibt den aktuellen Batteriestatus zurück.

Parameter

• batteryState (EmscriptenBatteryEvent*) – Der zuletzt empfangene Batteriestatus.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

Vibration

Funktionen

EMSCRIPTEN_RESULT emscripten_vibrate(int msecs)

Erzeugt eine Vibration für die angegebene Zeit in Millisekunden.

Parameter

• msecs (int) – Die Dauer der benötigten Vibration (Millisekunden).

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_vibrate_pattern(int *msecsArray, int numEntries)

Erzeugt ein komplexes Vibrationsmuster.

Parameter

• msecsArray (int*) – Ein Array von Zeiteinträgen [an, aus, an, aus, an, aus, ...], wobei jeder zweite eine Vibrationsdauer und jeder andere eine Stille-Dauer angibt.

• numEntries (int) – Die Anzahl der ganzen Zahlen im Array msecsArray.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

Seitenentladung

Definiert

EMSCRIPTEN_EVENT_BEFOREUNLOAD

Emscripten beforeunload-Ereignis.

Callback-Funktionen

em_beforeunload_callback

Funktionszeiger für die beforeunload event callback functions, definiert als

typedef const char *(*em_beforeunload_callback)(int eventType, const void *reserved, void *userData);

Parameter

• eventType (int) – Der Typ des beforeunload-Ereignisses (EMSCRIPTEN_EVENT_BEFOREUNLOAD).

• reserved (const void*) – Für zukünftige Verwendung reserviert; Übergabe von 0.

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

Gibt zurück

Gibt einen String zurück, der dem Benutzer angezeigt werden soll.

Rückgabetyp

char*

Funktionen

EMSCRIPTEN_RESULT emscripten_set_beforeunload_callback(void *userData, em_beforeunload_callback callback)

Registriert eine Callback-Funktion zum Empfangen des Seiten-beforeunload-Ereignisses.

Haken Sie sich in dieses Ereignis ein, um Aktionen unmittelbar vor dem Schließen der Seite auszuführen (z. B. um eine Benachrichtigung anzuzeigen, die den Benutzer fragt, ob er die Seite wirklich verlassen möchte).

Parameter

• userData (void*) – Benutzerdefinierte Daten, die an den Callback übergeben werden (opak für die API).

• callback (em_beforeunload_callback) – Eine Callback-Funktion. Die Funktion wird mit dem Ereignistyp, Informationen über das Ereignis und Benutzerdaten aufgerufen, die von dieser Registrierungsfunktion übergeben wurden. Der Callback sollte true zurückgeben, wenn das Ereignis verbraucht wird.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

WebGL-Kontext

Definiert

EMSCRIPTEN_EVENT_WEBGLCONTEXTLOST

EMSCRIPTEN_EVENT_WEBGLCONTEXTRESTORED

Emscripten WebGL-Kontext-Ereignisse.

EMSCRIPTEN_WEBGL_CONTEXT_HANDLE

Repräsentiert einen Handle zu einem Emscripten WebGL-Kontextobjekt. Der Wert 0 bezeichnet einen ungültigen/keinen Kontext (dies ist ein Typedef zu einem intptr_t).

Struktur

EmscriptenWebGLContextAttributes

Gibt WebGL-Kontexterstellungsparameter an.

bool alpha

Wenn true, fordern Sie einen Alpha-Kanal für den Kontext an. Wenn Sie einen Alpha-Kanal erstellen, können Sie die Canvas-Rendering mit dem darunter liegenden Webseiteninhalt überblenden. Standardwert: true.

bool depth

Wenn true, fordern Sie einen Tiefenpuffer von mindestens 16 Bit an. Wenn false, wird kein Tiefenpuffer initialisiert. Standardwert: true.

bool stencil

Wenn true, fordern Sie einen Stencil-Puffer von mindestens 8 Bit an. Wenn false, wird kein Stencil-Puffer initialisiert. Standardwert: false.

bool antialias

Wenn true, wird Antialiasing mit einem browserspezifischen Algorithmus und Qualitätsniveau initialisiert. Wenn false, ist Antialiasing deaktiviert. Standardwert: true.

bool premultipliedAlpha

Wenn true, wird der Alpha-Kanal des Renderkontexts als vor-multiplizierte Alpha-Werte behandelt. Wenn false, repräsentiert der Alpha-Kanal nicht-vor-multipliziertes Alpha. Standardwert: true.

bool preserveDrawingBuffer

Wenn true, werden die Inhalte des Zeichenpuffers zwischen aufeinanderfolgenden requestAnimationFrame()-Aufrufen beibehalten. Wenn false, werden Farbe, Tiefe und Stencil am Anfang jedes requestAnimationFrame() gelöscht. Im Allgemeinen führt das Setzen auf false zu einer besseren Leistung. Standardwert: false.

EM_WEBGL_POWER_PREFERENCE powerPreference

Gibt der WebGL-Canvas-Implementierung einen Hinweis, wie sie die Nutzung der verfügbaren GPU-Ressourcen wählen soll. Einer von EM_WEBGL_POWER_PREFERENCE_DEFAULT, EM_WEBGL_POWER_PREFERENCE_LOW_POWER, EM_WEBGL_POWER_PREFERENCE_HIGH_PERFORMANCE.

bool failIfMajorPerformanceCaveat

Wenn true, wird die Kontexterstellung abgebrochen, wenn der Browser nur einen Kontext erstellen kann, der keine gute hardwarebeschleunigte Leistung bietet. Standardwert: false.

int majorVersion

int minorVersion

Emscripten-spezifische Erweiterungen, die die zu initialisierende WebGL-Kontextversion angeben.

Geben Sie beispielsweise majorVersion=1, minorVersion=0 an, um einen WebGL 1.0-Kontext anzufordern, und majorVersion=2, minorVersion=0, um einen WebGL 2.0-Kontext anzufordern.

Standardwert: majorVersion=1, minorVersion=0

bool enableExtensionsByDefault

Wenn true, werden alle GLES2-kompatiblen, nicht leistungsbeeinträchtigenden WebGL-Erweiterungen nach der Kontexterstellung automatisch für Sie aktiviert. Wenn false, werden standardmäßig keine Erweiterungen aktiviert, und Sie müssen emscripten_webgl_enable_extension() manuell aufrufen, um jede gewünschte Erweiterung zu aktivieren. Standardwert: true.

bool explicitSwapControl

Standardmäßig, wenn explicitSwapControl im Standardzustand false ist, wird der gerenderte WebGL-Inhalt implizit (dem Benutzer angezeigt) auf dem Canvas dargestellt, wenn der Event-Handler, der mit WebGL rendert, zur Browser-Event-Schleife zurückkehrt. Wenn explicitSwapControl auf true gesetzt ist, wird der gerenderte Inhalt nicht automatisch auf dem Bildschirm angezeigt, wenn die Event-Handler-Funktion beendet ist, sondern die Kontrolle über das Swapping wird dem Benutzer über die Funktion emscripten_webgl_commit_frame() überlassen.

Um explicitSwapControl==true setzen zu können, muss die Unterstützung dafür explizit aktiviert werden, entweder 1) durch Hinzufügen des Emscripten-Linker-Flags -sOFFSCREEN_FRAMEBUFFER und Aktivierung von renderViaOffscreenBackBuffer==1, oder 2) durch Hinzufügen des Linker-Flags -sOFFSCREENCANVAS_SUPPORT und Ausführung in einem Browser, der OffscreenCanvas unterstützt.

bool renderViaOffscreenBackBuffer

Wenn true, wird dem erstellten WebGL-Kontext ein zusätzlicher Zwischen-Backbuffer (Offscreen-Renderziel) zugewiesen, und das Rendern erfolgt in diesen Backbuffer anstatt direkt in den "Standard-Backbuffer" von WebGL. Dies muss aktiviert werden, wenn 1) explicitSwapControl==true und der Browser OffscreenCanvas nicht unterstützt, 2) wenn WebGL-Rendering in einem Worker-Thread durchgeführt wird und der Browser OffscreenCanvas nicht unterstützt, und 3) wenn WebGL-Kontextzugriffe von mehreren Threads gleichzeitig durchgeführt werden (unabhängig davon, ob OffscreenCanvas unterstützt wird oder nicht).

Da die Unterstützung von Offscreen-Framebuffern eine gewisse Menge an zusätzlichem Code zum kompilierten Output hinzufügt, muss die Unterstützung dafür explizit über das Emscripten-Linker-Flag -sOFFSCREEN_FRAMEBUFFER aktiviert werden. Wenn gleichzeitig mit den Linker-Flags -sOFFSCREEN_FRAMEBUFFER und -sOFFSCREENCANVAS_SUPPORT gebaut wird, kann der Offscreen-Backbuffer als Polyfill-ähnlicher Kompatibilitäts-Fallback verwendet werden, um das Rendern von WebGL aus einem Pthread zu ermöglichen, wenn der Browser die OffscreenCanvas API nicht unterstützt.

bool proxyContextToMainThread

Dieses Element spezifiziert das Threading-Modell, das für den erstellten WebGL-Kontext verwendet wird, wenn der WebGL-Kontext in einem Pthread erstellt wird. Drei Werte sind möglich: EMSCRIPTEN_WEBGL_CONTEXT_PROXY_DISALLOW, EMSCRIPTEN_WEBGL_CONTEXT_PROXY_FALLBACK oder EMSCRIPTEN_WEBGL_CONTEXT_PROXY_ALWAYS. Wenn EMSCRIPTEN_WEBGL_CONTEXT_PROXY_DISALLOW angegeben ist, wird das WebGLRenderingContext-Objekt innerhalb des Pthreads erstellt, der die Funktion emscripten_webgl_create_context() als OffscreenCanvas-basierten Rendering-Kontext aufruft. Dies ist nur möglich, wenn 1) der aktuelle Browser die OffscreenCanvas-Spezifikation unterstützt, 2) der Code mit dem Linker-Flag -sOFFSCREENCANVAS_SUPPORT kompiliert wurde, 3) das Canvas-Objekt, auf dem der Kontext erstellt wird, beim ursprünglichen Erstellen des Pthreads mit der Funktion emscripten_pthread_attr_settransferredcanvases() an den aufrufenden Pthread übertragen wurde, und 4) kein OffscreenCanvas-basierter Kontext bereits gleichzeitig von diesem Canvas existiert.

Wenn ein WebGL-Rendering-Kontext als OffscreenCanvas-basierter Kontext erstellt wird, hat er die Einschränkung, dass nur der Pthread, der den Kontext erstellt hat, den Zugriff darauf aktivieren kann (über die Funktion emscripten_webgl_make_context_current()). Andere Threads können das Rendering auf den Kontext nicht aktivieren, d.h. OffscreenCanvas-basierte Kontexte sind im Wesentlichen an den Pthread "gebunden", der sie erstellt hat.

Wenn der aktuelle Browser OffscreenCanvas nicht unterstützt, können Sie das WebGL-Kontext-Erstellungs-Flag EMSCRIPTEN_WEBGL_CONTEXT_PROXY_ALWAYS angeben. Wenn dieses Flag übergeben wird und der Code mit aktiviertem -sOFFSCREEN_FRAMEBUFFER kompiliert wurde, wird der WebGL-Kontext als "proxied context" erstellt. In diesem Kontextmodus wird das WebGLRenderingContext-Objekt tatsächlich im Haupt-Browser-Thread erstellt, und alle WebGL-API-Aufrufe werden als asynchrone Nachrichten vom Pthread in den Haupt-Thread proxied. Dies hat einen Leistungs- und Latenzeinfluss im Vergleich zu OffscreenCanvas-Kontexten, aber im Gegensatz zu OffscreenCanvas-basierten Kontexten können proxied contexts über beliebig viele Pthreads geteilt werden: Sie können die Funktion emscripten_webgl_make_context_current() in jedem Pthread verwenden, um den Zugriff auf den WebGL-Kontext zu aktivieren und zu deaktivieren: Sie könnten zum Beispiel einen WebGL-Lade-Thread und einen weiteren WebGL-Rendering-Thread haben, die den gemeinsamen Zugriff auf den WebGL-Rendering-Kontext durch kooperatives Erwerben und Freigeben des Zugriffs auf den WebGL-Rendering-Kontext über die Funktion emscripten_webgl_make_context_current() koordinieren. Proxied contexts erfordern keine besondere Unterstützung vom Browser, so dass jeder WebGL-fähige Browser einen proxied WebGL-Kontext erstellen kann.

Das WebGL-Kontext-Erstellungs-Flag EMSCRIPTEN_WEBGL_CONTEXT_PROXY_ALWAYS erstellt immer einen proxied Kontext, auch wenn der Browser OffscreenCanvas unterstützt hätte. Wenn Sie einen leistungsstärkeren OffscreenCanvas-Kontext bevorzugen möchten, wenn er vom Browser unterstützt wird, aber nur auf einen proxied WebGL-Kontext zurückfallen möchten, um die Kompatibilität mit Browsern zu gewährleisten, die noch keine OffscreenCanvas-Unterstützung haben, können Sie das Kontext-Erstellungs-Flag EMSCRIPTEN_WEBGL_CONTEXT_PROXY_FALLBACK angeben. Um dieses Flag zu verwenden, sollte der Code mit beiden Linker-Flags -sOFFSCREEN_FRAMEBUFFER und -sOFFSCREENCANVAS_SUPPORT kompiliert werden.

Der Standardwert von proxyContextToMainThread nach dem Aufruf von emscripten_webgl_init_context_attributes() ist EMSCRIPTEN_WEBGL_CONTEXT_PROXY_DISALLOW, wenn der WebGL-Kontext im Hauptthread erstellt wird. Dies bedeutet, dass WebGL-Kontexte, die im Hauptthread erstellt werden, standardmäßig nicht zwischen mehreren Threads geteilt werden können (um versehentlichen Leistungsverlust durch Aktivierung des Proxyings zu vermeiden, wenn/falls es nicht benötigt wird). Um einen Kontext zu erstellen, der zwischen mehreren Pthreads geteilt werden kann, setzen Sie das Flag proxyContextToMainThread auf EMSCRIPTEN_WEBGL_CONTEXT_PROXY_ALWAYS.

Callback-Funktionen

em_webgl_context_callback

Funktionszeiger für die WebGL-Kontext-Ereignis-Callback-Funktionen, definiert als

typedef bool (*em_webgl_context_callback)(int eventType, const void *reserved, void *userData);

Parameter

• eventType (int) – Der Typ des WebGL-Kontext-Ereignisses.

• reserved (const void*) – Für zukünftige Verwendung reserviert; Übergabe von 0.

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

Gibt zurück

true (ungleich Null), um anzuzeigen, dass das Ereignis vom Callback-Handler konsumiert wurde.

Rückgabetyp

bool

Funktionen

EMSCRIPTEN_RESULT emscripten_set_webglcontextlost_callback(const char *target, void *userData, bool useCapture, em_webgl_context_callback callback)

EMSCRIPTEN_RESULT emscripten_set_webglcontextrestored_callback(const char *target, void *userData, bool useCapture, em_webgl_context_callback callback)

Registriert eine Callback-Funktion für die WebGL-Kontext-Ereignisse des Canvas: webglcontextlost und webglcontextrestored.

Parameter

• target (const char*) – Ziel-HTML-Element-ID.

• userData (void*) – Benutzerdefinierte Daten, die an den Callback übergeben werden (opak für die API).

• useCapture (bool) – Setzen Sie true, um Capture zu verwenden.

• callback (em_webgl_context_callback) – Eine Callback-Funktion. Die Funktion wird mit dem Ereignistyp, Informationen zum Ereignis und Benutzerdaten, die von dieser Registrierungsfunktion übergeben wurden, aufgerufen. Der Callback sollte true zurückgeben, wenn das Ereignis verbraucht wurde.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

bool emscripten_is_webgl_context_lost(EMSCRIPTEN_WEBGL_CONTEXT_HANDLE context)

Fragt den gegebenen WebGL-Kontext ab, ob er sich in einem verlorenen Kontextzustand befindet.

Parameter

• target (EMSCRIPTEN_WEBGL_CONTEXT_HANDLE) – Gibt einen Handle für den zu testenden Kontext an.

Gibt zurück

true, wenn der WebGL-Kontext in einem verlorenen Zustand ist (oder der Kontext nicht existiert)

Rückgabetyp

bool

void emscripten_webgl_init_context_attributes(EmscriptenWebGLContextAttributes *attributes)

Füllt alle Felder der gegebenen EmscriptenWebGLContextAttributes-Struktur mit ihren Standardwerten für die Verwendung mit WebGL 1.0.

Rufen Sie diese Funktion als zukunftskompatible Methode auf, um sicherzustellen, dass, wenn in Zukunft neue Felder zur Struktur EmscriptenWebGLContextAttributes hinzugefügt werden, diese ebenfalls standardmäßig initialisiert werden, ohne dass Code geändert werden muss.

Parameter

• attributes (EmscriptenWebGLContextAttributes*) – Die zu befüllende Struktur.

EMSCRIPTEN_WEBGL_CONTEXT_HANDLE emscripten_webgl_create_context(const char *target, const EmscriptenWebGLContextAttributes *attributes)

Erstellt und gibt einen neuen WebGL-Kontext zurück.

Hinweis

• Ein erfolgreicher Aufruf dieser Funktion wird den Rendering-Kontext nicht sofort aktivieren. Rufen Sie emscripten_webgl_make_context_current() nach dem Erstellen eines Kontexts auf, um ihn zu aktivieren.

• Diese Funktion versucht, die genau angeforderte Kontextversion zu initialisieren. Sie wird z.B. keine neuere abwärtskompatible Version oder ähnliches initialisieren.

Parameter

• target (const char*) – Das DOM-Canvas-Element, in dem der WebGL-Kontext initialisiert werden soll.

• attributes (const EmscriptenWebGLContextAttributes*) – Die Attribute der angeforderten Kontextversion.

Gibt zurück

Bei Erfolg ein nicht-null Wert, der einen Handle für den erstellten Kontext darstellt. Bei Misserfolg 0.

Rückgabetyp

EMSCRIPTEN_WEBGL_CONTEXT_HANDLE

EMSCRIPTEN_RESULT emscripten_webgl_make_context_current(EMSCRIPTEN_WEBGL_CONTEXT_HANDLE context)

Aktiviert den gegebenen WebGL-Kontext für das Rendering. Nach dem Aufruf dieser Funktion können alle OpenGL-Funktionen (glBindBuffer(), glDrawArrays(), etc.) auf den gegebenen GL-Kontext angewendet werden.

Parameter

• context (EMSCRIPTEN_WEBGL_CONTEXT_HANDLE) – Der zu aktivierende WebGL-Kontext.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

EMSCRIPTEN_WEBGL_CONTEXT_HANDLE emscripten_webgl_get_current_context()

Gibt den aktuell aktiven WebGL-Rendering-Kontext zurück, oder 0, wenn kein Kontext aktiv ist. Das Aufrufen von WebGL-Funktionen, wenn kein aktiver Rendering-Kontext vorhanden ist, ist undefiniert und kann eine JavaScript-Ausnahme auslösen.

Gibt zurück

Der aktuell aktive WebGL-Rendering-Kontext, oder 0, wenn kein Kontext aktiv ist.

Rückgabetyp

EMSCRIPTEN_WEBGL_CONTEXT_HANDLE

EMSCRIPTEN_RESULT emscripten_webgl_get_context_attributes(EMSCRIPTEN_WEBGL_CONTEXT_HANDLE context, EmscriptenWebGLContextAttributes *outAttributes)

Ruft die Kontext-Erstellungsattribute ab, die zur Initialisierung des gegebenen WebGL-Kontexts verwendet wurden.

Parameter

• context (EMSCRIPTEN_WEBGL_CONTEXT_HANDLE) – Der abzufragende WebGL-Kontext.

• *outAttributes (EmscriptenWebGLContextAttributes) – Die Kontext-Erstellungsattribute des angegebenen Kontexts werden hier eingetragen. Dieser Zeiger darf nicht null sein.

Gibt zurück

Bei Erfolg, EMSCRIPTEN_RESULT_SUCCESS.

EMSCRIPTEN_RESULT emscripten_webgl_commit_frame()

Präsentiert ("swappt") den auf dem aktuell aktiven WebGL-Kontext gerenderten Inhalt, um ihn auf dem Canvas sichtbar zu machen. Diese Funktion ist für WebGL-Kontexte verfügbar, die mit dem Kontext-Erstellungsattribut explicitSwapControl==true erstellt wurden. Wenn explicitSwapControl==false, wird der gerenderte Inhalt "implizit" auf dem Bildschirm angezeigt, wenn vom aufrufenden Ereignishandler an den Browser zurückgegeben wird.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS, oder einer der anderen Ergebniswerte, die einen Grund für den Fehler angeben.

Rückgabetyp

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_webgl_get_drawing_buffer_size(EMSCRIPTEN_WEBGL_CONTEXT_HANDLE context, int *width, int *height)

Ruft die drawingBufferWidth und drawingBufferHeight des angegebenen WebGL-Kontexts ab.

Parameter

• context (EMSCRIPTEN_WEBGL_CONTEXT_HANDLE) – Der WebGL-Kontext, dessen Breite/Höhe abgefragt werden soll.

• *width (int) – Die drawingBufferWidth des Kontexts.

• *height (int) – Die drawingBufferHeight des Kontexts.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_webgl_destroy_context(EMSCRIPTEN_WEBGL_CONTEXT_HANDLE context)

Löscht den gegebenen WebGL-Kontext. Wenn dieser Kontext aktiv war, wird kein Kontext als aktiv gesetzt.

Parameter

• context (EMSCRIPTEN_WEBGL_CONTEXT_HANDLE) – Der zu löschende WebGL-Kontext.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

bool emscripten_webgl_enable_extension(EMSCRIPTEN_WEBGL_CONTEXT_HANDLE context, const char *extension)

Aktiviert die angegebene Erweiterung im angegebenen Kontext.

Parameter

• context (EMSCRIPTEN_WEBGL_CONTEXT_HANDLE) – Der WebGL-Kontext, auf dem die Erweiterung aktiviert werden soll.

• extension (const char*) – Eine Zeichenfolge, die die WebGL-Erweiterung identifiziert. Zum Beispiel "OES_texture_float".

Gibt zurück

true, wenn die angegebene Erweiterung vom Kontext unterstützt wird, und false, wenn die Erweiterung nicht verfügbar war.

Rückgabetyp

bool

EMSCRIPTEN_RESULT emscripten_set_canvas_element_size(const char *target, int width, int height)

Ändert die Pixelbreite und -höhe des gegebenen Canvas-Elements im DOM.

Parameter

• target – Gibt einen Selektor für den Canvas an, dessen Größe geändert werden soll.

• width – Neue Pixelbreite des Canvas-Elements.

• height – Neue Pixelhöhe des Canvas-Elements.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS, wenn die Größenänderung erfolgreich war, und einer der EMSCRIPTEN_RESULT_* Fehlerwerte bei Misserfolg.

EMSCRIPTEN_RESULT emscripten_get_canvas_element_size(const char *target, int *width, int *height)

Ruft die aktuelle Pixelbreite und -höhe des gegebenen Canvas-Elements im DOM ab.

Parameter

• target – Gibt einen Selektor für den Canvas an, dessen Größe geändert werden soll.

• width – Ein Zeiger auf den Speicherort, an dem die Breite des Canvas-Elements empfangen wird. Dieser Zeiger darf nicht null sein.

• height – Ein Zeiger auf den Speicherort, an dem die Höhe des Canvas-Elements empfangen wird. Dieser Zeiger darf nicht null sein.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS, wenn das Abrufen von Breite und Höhe erfolgreich war, und einer der EMSCRIPTEN_RESULT_* Fehlerwerte bei Misserfolg.

CSS

Funktionen

EMSCRIPTEN_RESULT emscripten_set_element_css_size(const char * target, double width, double height)

Ändert die CSS-Breite und -Höhe des Elements, das durch target auf der Emscripten-Webseite angegeben ist.

Parameter

• target (const char*) – Zu änderndes Element.

• width (double) – Neue Breite des Elements.

• height (double) – Neue Höhe des Elements.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_get_element_css_size(const char * target, double * width, double * height)

Ruft die aktuelle CSS-Breite und -Höhe des Elements ab, das durch target angegeben ist.

Parameter

• target (const char*) – Element, dessen Größe abgerufen werden soll.

• width (double*) – Breite des Elements.

• height (double*) – Höhe des Elements.

Gibt zurück

EMSCRIPTEN_RESULT_SUCCESS oder einer der anderen Ergebniswerte.

Rückgabetyp

EMSCRIPTEN_RESULT

Animation und Timing

Die hier bereitgestellte API sind Low-Level-Funktionen, die die relevanten Web-APIs direkt aufrufen und nichts weiter. Sie integrieren sich nicht in die Emscripten-Laufzeit, wie z.B. die Überprüfung, ob das Programm angehalten wurde und ein Callback in diesem Fall abgebrochen wird. Zu diesem Zweck siehe die Funktion emscripten_set_main_loop().

Funktionen

long emscripten_set_timeout(void (*cb)(void *userData), double msecs, void *userData)

Führt einen setTimeout()-Callback-Aufruf auf der gegebenen Funktion im aufrufenden Thread aus.

Parameter

• cb – Die aufzurufende Callback-Funktion.

• msecs – Millisekunden-Verzögerung, bis der Callback ausgelöst werden soll.

• userData – Gibt ein zeigergroßes Feld von benutzerdefinierten Daten an, das an die Callback-Funktion übergeben wird.

Gibt zurück

Eine ID für den setTimeout()-Aufruf, die an emscripten_clear_timeout() übergeben werden kann, um den ausstehenden Timeout-Timer abzubrechen.

void emscripten_clear_timeout(long setTimeoutId)

Bricht einen ausstehenden setTimeout()-Aufruf im aufrufenden Thread ab. Diese Funktion muss im selben Thread aufgerufen werden wie der emscripten_set_timeout()-Aufruf, der den Callback registriert hat.

Parameter

• setTimeoutId – Eine ID, die von der Funktion emscripten_set_timeout() zurückgegeben wird.

void emscripten_set_timeout_loop(bool (*cb)(double time, void *userData), double intervalMsecs, void *userData)

Initialisiert eine setTimeout()-Schleife für die angegebene Funktion im aufrufenden Thread. Die angegebene Callback-Funktion 'cb' muss weiterhin true zurückgeben, solange die Animationsschleife weiterlaufen soll. Wenn die Funktion false zurückgibt, stoppt die setTimeout()-Schleife. Hinweis: Die Schleife startet sofort mit einer Verzögerung von 0 ms – die übergebene Zeit in intervalMsecs gibt das Intervall an, in dem die aufeinanderfolgenden Callback-Aufrufe ausgelöst werden sollen.

Parameter

• cb – Die aufzurufende Callback-Funktion.

• intervalMsecs – Millisekunden-Intervall, in dem der Callback weiterhin ausgelöst werden soll.

• userData – Gibt ein zeigergroßes Feld von benutzerdefinierten Daten an, das an die Callback-Funktion übergeben wird.

long emscripten_request_animation_frame(bool (*cb)(double time, void *userData), void *userData)

Führt einen einzelnen requestAnimationFrame()-Callback-Aufruf für die gegebene Funktion im aufrufenden Thread aus.

Parameter

• cb – Die aufzurufende Callback-Funktion. Diese Funktion empfängt den aktuellen hochpräzisen Timerwert (Wert von performance.now()) zum Zeitpunkt des Aufrufs.

• userData – Gibt ein zeigergroßes Feld von benutzerdefinierten Daten an, das an die Callback-Funktion übergeben wird.

Gibt zurück

Eine ID für den requestAnimationFrame()-Aufruf, die an emscripten_cancel_animation_frame() übergeben werden kann, um den ausstehenden requestAnimationFrame-Timer abzubrechen.

void emscripten_cancel_animation_frame(long requestAnimationFrameId)

Bricht einen registrierten requestAnimationFrame()-Callback im aufrufenden Thread ab, bevor er ausgeführt wird. Diese Funktion muss im selben Thread aufgerufen werden wie der emscripten_request_animation_frame()-Aufruf, der den Callback registriert hat.

Parameter

• requestAnimationFrameId – Eine ID, die von der Funktion emscripten_request_animation_frame() zurückgegeben wird.

void emscripten_request_animation_frame_loop(bool (*cb)(double time, void *userData), void *userData)

Initialisiert eine requestAnimationFrame()-Schleife für die angegebene Funktion im aufrufenden Thread. Die angegebene Callback-Funktion 'cb' muss weiterhin true zurückgeben, solange die Animationsschleife weiterlaufen soll. Wenn die Funktion false zurückgibt, stoppt die Animationsrahmen-Schleife.

Parameter

• cb – Die aufzurufende Callback-Funktion. Diese Funktion empfängt den aktuellen hochpräzisen Timerwert (Wert von performance.now()) zum Zeitpunkt des Aufrufs.

• userData – Gibt ein zeigergroßes Feld von benutzerdefinierten Daten an, das an die Callback-Funktion übergeben wird.

long emscripten_set_immediate(void (*cb)(void *userData), void *userData)

Führt einen setImmediate()-Callback-Aufruf für die gegebene Funktion im aufrufenden Thread aus. Gibt eine ID für den setImmediate()-Aufruf zurück, die an die Funktion emscripten_clear_immediate() übergeben werden kann, um einen ausstehenden setImmediate()-Aufruf abzubrechen. TODO: Der Polyfill von setImmediate() funktioniert derzeit nur im Haupt-Browser-Thread, aber nicht in Pthreads.

Parameter

• cb – Die aufzurufende Callback-Funktion.

• userData – Gibt ein zeigergroßes Feld von benutzerdefinierten Daten an, das an die Callback-Funktion übergeben wird.

Gibt zurück

Eine ID für den setImmediate()-Aufruf, die an emscripten_clear_immediate() übergeben werden kann, um den ausstehenden Callback abzubrechen.

void emscripten_clear_immediate(long setImmediateId)

Bricht einen ausstehenden setImmediate()-Aufruf im aufrufenden Thread ab. Diese Funktion muss im selben Thread aufgerufen werden wie der emscripten_set_immediate()-Aufruf, der den Callback registriert hat.

Parameter

• setImmediateId – Eine ID, die von der Funktion emscripten_set_immediate() zurückgegeben wird.

void emscripten_set_immediate_loop(bool (*cb)(void *userData), void *userData)

Initialisiert eine setImmediate()-Schleife für die angegebene Funktion im aufrufenden Thread. Die angegebene Callback-Funktion 'cb' muss weiterhin true zurückgeben, solange die Schleife weiterlaufen soll. Wenn die Funktion false zurückgibt, stoppt die setImmediate()-Schleife. TODO: Der Polyfill von setImmediate() funktioniert derzeit nur im Haupt-Browser-Thread, aber nicht in Pthreads.

Parameter

• cb – Die aufzurufende Callback-Funktion.

• userData – Gibt ein zeigergroßes Feld von benutzerdefinierten Daten an, das an die Callback-Funktion übergeben wird.

long emscripten_set_interval(void (*cb)(void *userData), double intervalMsecs, void *userData)

Initialisiert eine setInterval()-Schleife für die gegebene Funktion im aufrufenden Thread. Gibt eine ID für die initialisierte Schleife zurück. Rufen Sie emscripten_clear_interval() mit dieser ID auf, um die Schleife zu beenden. Beachten Sie, dass diese Funktion dazu führt, dass der gegebene Callback wiederholt aufgerufen wird. Rufen Sie emscripten_set_interval() nicht erneut für dieselbe Callback-Funktion innerhalb des Callbacks auf, da dies dazu führen würde, dass mehrere Schleifen gleichzeitig ausgeführt werden.

Parameter

• cb – Die aufzurufende Callback-Funktion.

• intervalMsecs – Millisekunden-Intervall, in dem der Callback weiterhin ausgelöst werden soll.

• userData – Gibt ein zeigergroßes Feld von benutzerdefinierten Daten an, das an die Callback-Funktion übergeben wird.

Gibt zurück

Eine ID für den setInterval()-Aufruf, die an emscripten_clear_interval() übergeben werden kann, um den aktuell ausgeführten Intervall-Timer abzubrechen.

void emscripten_clear_interval(long setIntervalId)

Bricht eine aktuell ausgeführte setInterval()-Schleife im aufrufenden Thread ab. Diese Funktion muss im selben Thread aufgerufen werden wie der emscripten_set_interval()-Aufruf, der den Callback registriert hat.

Parameter

• setIntervalId – Eine ID, die von der Funktion emscripten_set_interval() zurückgegeben wird.

double emscripten_date_now(void)

Ruft die JavaScript-Funktion Date.now() im aktuellen Thread auf.

Gibt zurück

Die Anzahl der Millisekunden, die seit der UNIX-Epoche vergangen sind. (00:00:00 Donnerstag, 1. Januar 1970)

double emscripten_performance_now(void)

Ruft die JavaScript-Funktion performance.now() im aktuellen Thread auf. Beachten Sie, dass der von dieser Funktion zurückgegebene Wert je nachdem, in welchem Thread diese Funktion aufgerufen wird, auf unterschiedlichen Zeitversatz basiert. Das heißt, vergleichen Sie keine absoluten Zeitwerte, die von performance.now() zurückgegeben werden, über Threads hinweg. (Das Vergleichen relativer Zeitwerte ist in Ordnung). Im Hauptthread gibt diese Funktion die Anzahl der Millisekunden zurück, die seit dem Start der Seite vergangen sind. In einem Web Worker/Pthread gibt diese Funktion die Anzahl der Millisekunden zurück, die seit dem Start des Workers, der diesen Pthread hostet, vergangen sind. (Worker werden im Allgemeinen nicht abgebaut, wenn ein Pthread beendet wird und ein zweiter startet, sondern sie werden in einem Pool am Leben gehalten, daher ist nicht garantiert, dass diese Funktion ab dem Zeitpunkt, zu dem ein Pthread startet, bei 0 zu zählen beginnt)

Gibt zurück

Ein hochpräziser Wallclock-Zeitwert in Millisekunden.

Throw

Funktionen

void emscripten_throw_number(double number)

Ruft eine JavaScript-throw-Anweisung auf und wirft eine Zahl.

void emscripten_throw_string(const char *utf8String)

Ruft eine JavaScript-throw-Anweisung auf und wirft einen String.

void emscripten_unwind_to_js_event_loop(void)

Löst eine JavaScript-Ausnahme aus, die den Stack entlädt und die Ausführung an die Browser-Ereignisschleife zurückgibt. Diese Funktion gibt die Ausführung nicht an den aufrufenden Code zurück.

Diese Funktion kann nützlich sein, wenn Code portiert wird, der in eine Endlosschleife geraten würde. Anstatt tatsächlich eine Endlosschleife auszuführen, was im Web nicht erlaubt ist, können wir den Schleifenkörper so einrichten, dass er asynchron ausgeführt wird (mit emscripten_set_main_loop() oder etwas anderem), und diese Funktion aufrufen, um die Ausführung anzuhalten, was wichtig ist, da wir nicht möchten, dass die Ausführung normal fortgesetzt wird.