html5.h

html5.h 中的 C++ API 定义了 Emscripten 的低级粘合绑定，用于从原生代码与 HTML5 事件交互。

提示

C++ API 与它们的 等效 HTML5 JavaScript API 密切映射。下面列出的 HTML5 规范提供了本文档中提供的“超出”信息的额外详细参考。

此外，可以查看 测试/示例代码，以了解代码的使用方式。

html5.h 映射的 API 的 HTML5 规范包括

如何使用此 API

大多数这些 API 使用基于事件的体系结构；功能是通过注册回调函数来访问的，该回调函数将在事件发生时被调用。

注意

游戏手柄 API 目前是一个例外，因为它只提供轮询 API。对于某些 API，既公开基于事件的模型，也公开基于轮询的模型。

注册函数

注册函数的典型格式如下（某些方法可能会省略各种参数）

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

target 参数是将回调注册应用到的 HTML 元素的 ID。此字段具有以下特殊含义

  • EMSCRIPTEN_EVENT_TARGET_WINDOW：事件监听器应用于 JavaScript window 对象。

  • EMSCRIPTEN_EVENT_TARGET_DOCUMENT：事件监听器应用于 JavaScript document 对象。

  • EMSCRIPTEN_EVENT_TARGET_SCREEN：事件监听器应用于 JavaScript window.screen 对象。

  • 0 或 NULL：如果使用选项 -sDISABLE_DEPRECATED_FIND_EVENT_TARGET_BEHAVIOR（默认）构建，则 NULL 表示无效元素。如果使用旧版选项 -sDISABLE_DEPRECATED_FIND_EVENT_TARGET_BEHAVIOR=0（不推荐）构建，则将根据事件类型自动选择默认元素。

  • #canvas：如果使用旧版选项 -sDISABLE_DEPRECATED_FIND_EVENT_TARGET_BEHAVIOR=0（不推荐）构建，则事件监听器应用于 Emscripten 默认的 WebGL 画布元素。如果使用选项 -sDISABLE_DEPRECATED_FIND_EVENT_TARGET_BEHAVIOR（默认）构建，则 #canvas 被解释为 CSS 查询选择器：“具有 CSS ID ‘canvas’ 的第一个元素”。

  • 任何其他字符串：使用传递的字符串对 DOM 执行 CSS 选择器查找，并将事件监听器应用于与查询匹配的第一个元素。

如果以上内容对您来说还不够，您可以使用类似以下内容在 JavaScript 中添加自定义映射

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

这将允许 !canvas 映射到 Module.canvas 中保存的画布。（您可以在 EM_JS 或 EM_ASM 块中编写该 JavaScript，该块发生在您调用注册函数之前，例如。）

userData 参数是用户定义的值，该值将（不变）传递给注册的事件回调。这可用于例如传递指向 C++ 类的指针或类似地将 C API 封装在干净的面向对象方式中。

useCapture 参数映射到 EventTarget.addEventListener 中的 useCapture。它指示是否启动捕获：如果为 true，回调将仅在 DOM 捕获和目标阶段被调用；如果为 false，则回调将在目标阶段和冒泡阶段被触发。有关更详细的说明，请参阅 DOM Level 3 事件。

大多数函数使用类型 EMSCRIPTEN_RESULT 返回结果。零和正值表示成功。负值表示失败。没有一个函数会通过抛出 JavaScript 或 C++ 异常来失败或中止。如果特定浏览器不支持给定功能，则在注册回调时将返回 EMSCRIPTEN_RESULT_NOT_SUPPORTED 值。

回调函数

当事件发生时，回调将使用相关的事件“类型”（例如 EMSCRIPTEN_EVENT_CLICK）、包含发生的事件详细信息的 struct 以及最初传递给注册函数的 userData 被调用。回调函数的通用格式为

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

返回 bool 的回调处理程序可以通过指定 true 来表示处理程序消耗了该事件（这会通过调用其 .preventDefault(); 成员来抑制该事件的默认操作）。返回 false 表示该事件未被消耗 - 默认的浏览器事件操作将执行，并且该事件将被允许像往常一样传递/冒泡。

使用 null 指针作为回调来调用注册函数会导致从给定的 target 元素中取消注册该回调。当在 atexit 处理程序传递期间调用 C exit() 函数时，所有事件处理程序也会自动取消注册。请使用函数 emscripten_set_main_loop() 或将 Module.noExitRuntime = true; 设置为确保离开 main() 不会立即导致 exit() 并清理事件处理程序。

受 Web 安全影响的函数

一些函数，包括 emscripten_request_pointerlock() 和 emscripten_request_fullscreen()，会受到 Web 安全的影响。

虽然函数可以在任何地方调用，但实际的“请求”只能在用户生成事件（例如键盘、鼠标或触摸按压/释放）的处理程序内发出。

在移植代码时，可能很难确保函数在适当的事件处理程序内被调用（以便立即发出请求）。为了方便起见，开发人员可以设置 deferUntilInEventHandler=true，以便在用户下次按下键盘或鼠标按钮时自动延迟不安全的请求。这简化了移植，但通常会导致用户体验较差。例如，用户必须在画布上单击一次才能隐藏指针或过渡到全屏。

在可能的情况下，函数应该只在适当的事件处理程序内调用。设置 deferUntilInEventHandler=false 会导致函数在由于安全限制而拒绝请求时中止并出现错误：这是一种用于发现函数在用户生成事件的处理程序之外被调用的实例的有效机制。

测试/示例代码

HTML5 测试代码演示了如何使用此 API

通用类型

EM_UTF8

这是 Emscripten 的 UTF8 字符串类型（映射到 char）。这用于节点名称、元素 ID 等。

函数返回值

此 API 中的大多数函数返回类型为 EMSCRIPTEN_RESULT 的结果。没有一个函数会通过抛出 JavaScript 或 C++ 异常而失败或终止。如果特定浏览器不支持给定功能，则在注册回调时将返回值 EMSCRIPTEN_RESULT_NOT_SUPPORTED。

EMSCRIPTEN_RESULT

此类型用于返回此 API 中大多数函数的结果。零和正值表示成功，负值表示失败。可能的返回值如下所示。

EMSCRIPTEN_RESULT_SUCCESS

操作成功。

EMSCRIPTEN_RESULT_DEFERRED

由于 Web 安全原因，请求的操作现在无法完成，已延迟到下一个事件处理程序中完成。

EMSCRIPTEN_RESULT_NOT_SUPPORTED

此浏览器或目标元素不支持给定操作。如果操作不受支持，则在注册回调时将返回此值。

EMSCRIPTEN_RESULT_FAILED_NOT_DEFERRED

由于 Web 安全原因，请求的操作现在无法完成。它失败了，因为用户要求操作不延迟。

EMSCRIPTEN_RESULT_INVALID_TARGET

操作失败，因为指定的 target 元素无效。

EMSCRIPTEN_RESULT_UNKNOWN_TARGET

操作失败，因为未找到指定的 target 元素。

EMSCRIPTEN_RESULT_INVALID_PARAM

操作失败，因为向函数传递了无效参数。

EMSCRIPTEN_RESULT_FAILED

通用失败结果消息，如果没有任何特定的结果可用，则返回。

EMSCRIPTEN_RESULT_NO_DATA

操作失败，因为当前没有数据可用。

按键

定义

EMSCRIPTEN_EVENT_KEYPRESS
EMSCRIPTEN_EVENT_KEYDOWN
EMSCRIPTEN_EVENT_KEYUP

Emscripten 键盘事件。

DOM_KEY_LOCATION

键盘上按键的位置；下面的值之一。

DOM_KEY_LOCATION_STANDARD
DOM_KEY_LOCATION_LEFT
DOM_KEY_LOCATION_RIGHT
DOM_KEY_LOCATION_NUMPAD

键盘上按键的位置。

结构体

EmscriptenKeyboardEvent

在 键盘事件 中传递的事件结构：keypress、keydown 和 keyup。

请注意，由于 DOM 3 级事件规范 在撰写本文时（2014 年 3 月）非常新，对规范中不同字段的统一支持仍在不断变化。请务必在多个浏览器中检查结果。有关如何解释传统键盘事件的示例，请参阅 未合并的拉取请求 #2222。

double timestamp

记录数据时的绝对挂钟时间（毫秒）。

EM_UTF8 key

所按按键的打印表示形式。

最大大小为 32 个 char（即 EM_UTF8 key[32]）。

EM_UTF8 code

一个字符串，用于标识正在按下的物理按键。该值不受当前键盘布局或修饰符状态的影响，因此特定按键始终返回相同的值。

最大大小为 32 个 char（即 EM_UTF8 code[32]）。

unsigned long location

指示键盘上按键的位置。一个 DOM_KEY_LOCATION 值。

bool ctrlKey
bool shiftKey
bool altKey
bool metaKey

指定在键盘事件期间哪些修饰符处于活动状态。

bool repeat

指定此键盘事件是否代表重复按下。

EM_UTF8 locale

一个区域字符串，指示配置的键盘区域。如果浏览器或设备不知道键盘的区域，则此字符串可能为空。

最大大小为 32 个字符（即 EM_UTF8 locale[32]）。

EM_UTF8 charValue

以下字段是来自先前版本的 DOM 键盘事件规范的值。参见 按键的字符表示形式。这是文档中的 char 字段，但重命名为 charValue 以避免使用 C 保留字。

最大大小为 32 个 char（即 EM_UTF8 charValue[32]）。

警告

此属性已从 DOM 3 级事件中删除。

unsigned long charCode

按键的 Unicode 引用号；此属性仅供 keypress 事件使用。对于其 char 属性包含多个字符的按键，这是该属性中第一个字符的 Unicode 值。

警告

此属性已弃用，您应该改用字段 key（如果可用）。

unsigned long keyCode

一个系统和实现相关的数字代码，标识所按按键的未修改值。

警告

此属性已弃用，您应该改用字段 key（如果可用）。

unsigned long which

一个系统和实现相关的数字代码，标识所按按键的未修改值；这通常与 keyCode 相同。

警告

此属性已弃用，您应该改用字段 key（如果可用）。请注意，虽然此字段已弃用，但 which 的跨浏览器支持可能优于其他字段，因此建议进行实验。有关更多信息，请阅读问题 https://github.com/emscripten-core/emscripten/issues/2817。

回调函数

em_key_callback_func

keypress 回调函数 的函数指针，定义为

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

  • eventType (int) – 键盘事件 的类型。

  • keyEvent (const EmscriptenKeyboardEvent*) – 与发生的键盘事件相关的信息。

  • userData (void*) – 最初传递给注册函数的 userData。

返回值

true (非零) 表示事件已被回调处理程序处理。

返回值类型

bool

函数

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)

注册一个回调函数，用于接收浏览器生成的键盘输入事件。

参数

  • target (const char*) – 目标 HTML 元素 ID.

  • userData (void*) – 用户定义的数据，将传递给回调函数（对 API 不透明）。

  • useCapture (bool) – 设置true 以使用捕获。

  • callback (em_key_callback_func) – 回调函数。该函数将使用事件类型、有关事件的信息以及从该注册函数传递的用户数据进行调用。如果事件已处理，回调函数应返回true。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

参见

注意

要接收事件，该元素必须是可聚焦的，请参见 https://github.com/emscripten-core/emscripten/pull/7484#issuecomment-437887001

鼠标

定义

EMSCRIPTEN_EVENT_CLICK
EMSCRIPTEN_EVENT_MOUSEDOWN
EMSCRIPTEN_EVENT_MOUSEUP
EMSCRIPTEN_EVENT_DBLCLICK
EMSCRIPTEN_EVENT_MOUSEMOVE
EMSCRIPTEN_EVENT_MOUSEENTER
EMSCRIPTEN_EVENT_MOUSELEAVE

Emscripten 鼠标事件。

结构体

EmscriptenMouseEvent

在 鼠标事件中传递的事件结构：click、mousedown、mouseup、dblclick、mousemove、mouseenter 和 mouseleave。

double timestamp

记录数据时的绝对挂钟时间（毫秒）。

long screenX
long screenY

相对于浏览器屏幕坐标系的坐标。

long clientX
long clientY

相对于与事件关联的视窗的坐标。

bool ctrlKey
bool shiftKey
bool altKey
bool metaKey

指定鼠标事件期间哪些修饰键处于活动状态。

unsigned short button

标识哪个指针设备按钮的状态发生了改变（请参见 MouseEvent.button）

  • 0 : 左键

  • 1 : 中键（如果存在）

  • 2 : 右键

unsigned short buttons

一个位掩码，指示事件发生时按下了哪些鼠标按钮组合。

long movementX
long movementY;

如果指针锁定处于活动状态，这两个额外的字段将提供自上次事件以来的相对鼠标移动。

long targetX
long targetY

这些字段提供相对于接收输入事件的目标 DOM 元素的坐标空间的鼠标坐标映射（Emscripten 特定的扩展；坐标向下舍入到最接近的整数）。

long canvasX
long canvasY

这些字段提供映射到 Emscripten 画布客户端区域的鼠标坐标（Emscripten 特定的扩展；坐标向下舍入到最接近的整数）。

long padding

内部，可以忽略。

注意

仅限实现者：将此结构体填充到 8 字节的倍数，以使 WheelEvent 无歧义地对齐到 8 字节。

回调函数

em_mouse_callback_func

用于鼠标 事件 回调 函数的函数指针，定义为

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

  • eventType (int) – 鼠标 事件的类型。

  • mouseEvent (const EmscriptenMouseEvent*) – 有关发生的鼠标事件的信息。

  • userData (void*) – 最初传递给注册函数的 userData。

返回值

true (非零) 表示事件已被回调处理程序处理。

返回值类型

bool

函数

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)

注册一个回调函数，用于接收浏览器生成的鼠标输入事件。

参数

  • target (const char*) – 目标 HTML 元素 ID.

  • userData (void*) – 用户定义的数据，将传递给回调函数（对 API 不透明）。

  • useCapture (bool) – 设置true 以使用捕获。

  • 回调函数 (em_mouse_callback_func) – 回调函数。该函数使用事件类型、有关事件的信息以及从此注册函数传递的用户数据进行调用。如果事件被消耗，则回调函数应返回 true。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_get_mouse_status(EmscriptenMouseEvent *mouseState)

返回最近接收到的鼠标事件状态。

请注意，为了使此函数调用成功，emscripten_set_xxx_callback 必须首先使用鼠标事件类型之一和非零回调函数指针调用，以启用鼠标状态捕获。

参数
返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

滚轮

定义

EMSCRIPTEN_EVENT_WHEEL

Emscripten 滚轮事件。

DOM_DELTA_PIXEL

增量的度量单位必须为像素（来自 规范）。

DOM_DELTA_LINE

增量的度量单位必须为文本的单个行（来自 规范）。

DOM_DELTA_PAGE

增量的度量单位必须为页面，定义为单个屏幕或分隔的页面（来自 规范）。

结构

EmscriptenWheelEvent

在 鼠标滚轮事件 中传递的事件结构。

EmscriptenMouseEvent mouse

指定与该事件相关的常规鼠标信息。

double deltaX
double deltaY
double deltaZ

每个轴上滚轮的移动量。请注意，这些值可能是小数，因此您应该避免简单地将其转换为整数，否则可能会导致滚动值为 0。正 Y 滚动方向是在向下滚动页面时（页面 CSS 像素 +Y 方向），这对应于在 Windows、Linux 和 macOS 上向下滚动鼠标滚轮（远离屏幕），以及在 macOS 上禁用“自然滚动”选项时。

unsigned long deltaMode

其中一个 DOM_DELTA_ 值，指示增量值的度量单位。

回调函数

em_wheel_callback_func

用于 滚轮 事件 回调 函数 的函数指针，定义为

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

  • eventType (int) – 滚轮事件类型 (EMSCRIPTEN_EVENT_WHEEL）。

  • wheelEvent (const EmscriptenWheelEvent*) – 有关发生的滚轮事件的信息。

  • userData (void*) – 最初传递给注册函数的 userData。

返回值

true (非零) 表示事件已被回调处理程序处理。

返回值类型

bool

函数

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

注册用于接收浏览器生成的 鼠标滚轮事件 的回调函数。

参数

  • target (const char*) – 目标 HTML 元素 ID.

  • userData (void*) – 用户定义的数据，将传递给回调函数（对 API 不透明）。

  • useCapture (bool) – 设置true 以使用捕获。

  • 回调函数 (em_wheel_callback_func) – 回调函数。该函数使用事件类型、有关事件的信息以及从此注册函数传递的用户数据进行调用。如果事件被消耗，则回调函数应返回 true。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

UI

定义

EMSCRIPTEN_EVENT_RESIZE
EMSCRIPTEN_EVENT_SCROLL

Emscripten UI 事件。

结构

EmscriptenUiEvent

在 DOM 元素 UIEvent 事件中传递的事件结构：resize 和 scroll。

long detail

对于 resize 和 scroll 事件，这始终为零。

int documentBodyClientWidth
int documentBodyClientHeight

document.body 元素的 clientWidth/clientHeight。

int windowInnerWidth
int windowInnerHeight

浏览器窗口的 innerWidth/innerHeight。

int windowOuterWidth
int windowOuterHeight;

浏览器窗口的 outerWidth/outerHeight。

int scrollTop
int scrollLeft

页面滚动位置（向下舍入到最接近的像素）。

回调函数

em_ui_callback_func

用于 UI 事件 回调 函数 的函数指针，定义为

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

  • eventType (int) – UI 事件类型 (EMSCRIPTEN_EVENT_RESIZE）。

  • uiEvent (const EmscriptenUiEvent*) – 有关发生的 UI 事件的信息。

  • userData (void*) – 最初传递给注册函数的 userData。

返回值

true (非零) 表示事件已被回调处理程序处理。

返回值类型

bool

函数

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)

注册用于接收 DOM 元素 resize 和 scroll 事件的回调函数。

注意

  • 对于 resize 回调函数，将 target = EMSCRIPTEN_EVENT_TARGET_WINDOW 传入以从 Window 对象获取 resize 事件。

  • DOM3 事件规范只要求 Window 对象发送 resize 事件。在其他 DOM 元素上注册 resize 回调函数是有效的，但浏览器不需要为这些事件触发 resize 事件。

参数

  • target (const char*) – 目标 HTML 元素 ID.

  • userData (void*) – 用户定义的数据，将传递给回调函数（对 API 不透明）。

  • useCapture (bool) – 设置true 以使用捕获。

  • 回调函数 (em_ui_callback_func) – 回调函数。该函数使用事件类型、有关事件的信息以及从此注册函数传递的用户数据进行调用。如果事件被消耗，则回调函数应返回 true。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

焦点

定义

EMSCRIPTEN_EVENT_BLUR
EMSCRIPTEN_EVENT_FOCUS
EMSCRIPTEN_EVENT_FOCUSIN
EMSCRIPTEN_EVENT_FOCUSOUT

Emscripten 焦点事件。

结构体

EmscriptenFocusEvent

DOM 元素中传递的事件结构体blur、focus、focusin 和 focusout 事件。

EM_UTF8 nodeName

目标 HTML 元素的 nodeName。

最大大小 128 char（即 EM_UTF8 nodeName[128]）。

EM_UTF8 id

目标元素的 ID。

最大大小 128 char（即 EM_UTF8 id[128]）。

回调函数

em_focus_callback_func

用于 focus event callback functions 的函数指针，定义为

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

  • eventType (int) – 聚焦事件类型 (EMSCRIPTEN_EVENT_BLUR).

  • focusEvent (const EmscriptenFocusEvent*) – 关于发生的聚焦事件的信息。

  • userData (void*) – 最初传递给注册函数的 userData。

返回值

true (非零) 表示事件已被回调处理程序处理。

返回值类型

bool

函数

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)

注册一个回调函数，用于接收 DOM 元素blur、focus、focusin 和 focusout 事件。

参数

  • target (const char*) – 目标 HTML 元素 ID.

  • userData (void*) – 用户定义的数据，将传递给回调函数（对 API 不透明）。

  • useCapture (bool) – 设置true 以使用捕获。

  • callback (em_focus_callback_func) – 回调函数。该函数将使用事件类型、有关事件的信息以及从此注册函数传递的用户数据进行调用。如果事件被消耗，回调函数应返回 true。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

设备方向

定义

EMSCRIPTEN_EVENT_DEVICEORIENTATION

Emscripten deviceorientation 事件。

结构体

EmscriptenDeviceOrientationEvent

在 deviceorientation 事件中传递的事件结构体。

double alpha
double beta
double gamma

设备的 方向，用从固定在地球上的坐标系到固定在设备上的坐标系的变换表示。

下图（来源：dev.opera.com）和定义说明了坐标系

  • alpha：设备绕 Z 轴旋转的角度。

  • beta：设备绕 X 轴旋转的角度。

  • gamma：设备绕 Y 轴旋转的角度。

Image of device showing X, Y, Z axes
bool absolute

如果为 false，则方向仅相对于某个其他基准方向，而不是相对于固定坐标系。

回调函数

em_deviceorientation_callback_func

用于 orientation event callback functions 的函数指针，定义为

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

  • eventType (int) – 方向事件类型 (EMSCRIPTEN_EVENT_DEVICEORIENTATION).

  • deviceOrientationEvent (const EmscriptenDeviceOrientationEvent*) – 关于发生的事件的信息。

  • userData (void*) – 最初传递给注册函数的 userData。

返回值

true (非零) 表示事件已被回调处理程序处理。

返回值类型

bool

函数

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

注册一个回调函数，用于接收 deviceorientation 事件。

参数

  • userData (void*) – 用户定义的数据，将传递给回调函数（对 API 不透明）。

  • useCapture (bool) – 设置true 以使用捕获。

  • callback (em_deviceorientation_callback_func) – 回调函数。该函数将使用事件类型、有关事件的信息以及从此注册函数传递的用户数据进行调用。如果事件被消耗，回调函数应返回 true。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_get_deviceorientation_status(EmscriptenDeviceOrientationEvent *orientationState)

返回最近接收到的 deviceorientation 事件状态。

注意，要使此函数调用成功，必须先使用某个鼠标事件类型和非零回调函数指针调用 emscripten_set_deviceorientation_callback()，以启用 deviceorientation 状态捕获。

参数
返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

设备运动

定义

EMSCRIPTEN_EVENT_DEVICEMOTION

Emscripten devicemotion 事件。

结构体

EmscriptenDeviceMotionEvent

在 devicemotion 事件中传递的事件结构体。

double accelerationX
double accelerationY
double accelerationZ

设备的加速度，不包括重力。

double accelerationIncludingGravityX
double accelerationIncludingGravityY
double accelerationIncludingGravityZ

设备的加速度，包括重力。

double rotationRateAlpha
double rotationRateBeta
double rotationRateGamma

设备的旋转增量。

int supportedFields

一个位域，它是 EMSCRIPTEN_DEVICE_MOTION_EVENT_SUPPORTS_* 字段的组合，指定该结构体的当前浏览器支持的不同字段。例如，如果该字段中不存在 EMSCRIPTEN_DEVICE_MOTION_EVENT_SUPPORTS_ACCELERATION 位，则应假定该结构体的 accelerationX/Y/Z 字段无效。

回调函数

em_devicemotion_callback_func

用于 devicemotion 事件 回调 函数 的函数指针，定义为

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

  • eventType (int) – devicemotion 事件的类型 (EMSCRIPTEN_EVENT_DEVICEMOTION).

  • deviceMotionEvent (const EmscriptenDeviceMotionEvent*) – 关于发生的 devicemotion 事件的信息。

  • userData (void*) – 最初传递给注册函数的 userData。

返回值

true (非零) 表示事件已被回调处理程序处理。

返回值类型

bool

函数

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

注册一个用于接收 devicemotion 事件的回调函数。

参数

  • userData (void*) – 用户定义的数据，将传递给回调函数（对 API 不透明）。

  • useCapture (bool) – 设置true 以使用捕获。

  • callback (em_devicemotion_callback_func) – 回调函数。该函数使用事件类型、关于事件的信息和从该注册函数传递的用户数据调用。如果事件被消耗，则回调应该返回 true。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_get_devicemotion_status(EmscriptenDeviceMotionEvent *motionState)

返回最近收到的 devicemotion 事件状态。

请注意，为了使此函数调用成功，emscripten_set_devicemotion_callback() 必须首先使用鼠标事件类型之一和非零回调函数指针调用，以启用 devicemotion 状态捕获。

参数
返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

方向

定义

EMSCRIPTEN_EVENT_ORIENTATIONCHANGE

Emscripten orientationchange 事件。

EMSCRIPTEN_ORIENTATION_UNKNOWN

方向 API 不受支持或方向类型未知。

EMSCRIPTEN_ORIENTATION_PORTRAIT_PRIMARY

主要肖像模式方向。

EMSCRIPTEN_ORIENTATION_PORTRAIT_SECONDARY

次要肖像模式方向。

EMSCRIPTEN_ORIENTATION_LANDSCAPE_PRIMARY

主要横向模式方向。

EMSCRIPTEN_ORIENTATION_LANDSCAPE_SECONDARY

次要横向模式方向。

结构体

EmscriptenOrientationChangeEvent

在 orientationchange 事件中传递的事件结构。

int orientationIndex

其中一个 EM_ORIENTATION_PORTRAIT_xxx 字段，或者如果未知，则为 EMSCRIPTEN_ORIENTATION_UNKNOWN。

int orientationAngle

Emscripten 特定扩展：某些浏览器引用 window.orientation，因此也报告该值。

方向角度以度为单位。0： “默认方向”，即握持移动设备的默认直立方向。可能是横向或纵向。

回调函数

em_orientationchange_callback_func

用于 orientationchange 事件 回调 函数 的函数指针，定义为

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

  • eventType (int) – orientationchange 事件的类型 (EMSCRIPTEN_EVENT_ORIENTATIONCHANGE).

  • orientationChangeEvent (const EmscriptenOrientationChangeEvent*) – 关于发生的 orientationchange 事件的信息。

  • userData (void*) – 最初传递给注册函数的 userData。

返回值

true (非零) 表示事件已被回调处理程序处理。

返回值类型

bool

函数

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

注册一个用于接收 orientationchange 事件的回调函数。

参数

  • userData (void*) – 用户定义的数据，将传递给回调函数（对 API 不透明）。

  • useCapture (bool) – 设置true 以使用捕获。

  • callback (em_orientationchange_callback_func) – 回调函数。该函数使用事件类型、关于事件的信息和从该注册函数传递的用户数据调用。如果事件被消耗，则回调应该返回 true。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_get_orientation_status(EmscriptenOrientationChangeEvent *orientationStatus)

返回当前设备方向状态。

参数
返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_lock_orientation(int allowedOrientations)

将屏幕方向锁定到给定的 allowed orientations 集。

参数
返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_unlock_orientation(void)

移除方向锁定，以便屏幕可以转向任何方向。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

全屏

定义

EMSCRIPTEN_EVENT_FULLSCREENCHANGE

Emscripten fullscreenchange 事件。

EMSCRIPTEN_FULLSCREEN_SCALE

一种类似枚举的类型，它指定 Emscripten 运行时在通过调用函数 emscripten_request_fullscreen_strategy() 和 emscripten_enter_soft_fullscreen() 将目标元素以全屏模式显示时，应如何处理目标元素的 CSS 大小。

EMSCRIPTEN_FULLSCREEN_SCALE_DEFAULT

指定 Emscripten 运行时在全屏模式和窗口模式之间转换时不应调整 DOM 元素的大小。浏览器将负责将 DOM 元素缩放到全屏大小。此模式下适当的浏览器行为是将元素拉伸以适合整个显示，而忽略纵横比，但在撰写本文时，浏览器在此处实现了不同的行为。有关更多信息，请参阅 https://github.com/emscripten-core/emscripten/issues/2556 中的讨论。

EMSCRIPTEN_FULLSCREEN_SCALE_STRETCH

指定 Emscripten 运行时应在过渡到全屏模式时明确拉伸目标元素的 CSS 大小以覆盖整个屏幕。这将改变显示内容的纵横比。

EMSCRIPTEN_FULLSCREEN_SCALE_ASPECT

指定 Emscripten 运行时应明确缩放目标元素的 CSS 大小以覆盖整个屏幕，同时添加垂直或水平黑色字母箱填充以保留内容的纵横比。此处使用的纵横比是画布元素的渲染目标大小。要更改所需的纵横比，请在进入全屏模式之前调用 emscripten_set_canvas_element_size()。

EMSCRIPTEN_FULLSCREEN_CANVAS_SCALE

一种类似枚举的类型，它指定 Emscripten 运行时在通过调用函数 emscripten_request_fullscreen_strategy() 和 emscripten_enter_soft_fullscreen() 将目标元素以全屏模式显示时，应如何处理目标画布元素的像素大小（渲染目标分辨率）。要更好地了解画布元素的 CSS 大小与画布元素的渲染目标大小之间的根本区别，请参阅 https://www.khronos.org/webgl/wiki/HandlingHighDPI。

EMSCRIPTEN_FULLSCREEN_CANVAS_SCALE_NONE

指定 Emscripten 运行时在全屏模式下不应对显示在全屏模式下的目标画布元素的渲染目标分辨率进行任何更改。当您的应用程序设置为渲染到单个固定分辨率，并且在任何情况下都无法更改时，请使用此模式。

EMSCRIPTEN_FULLSCREEN_CANVAS_SCALE_STDDEF

指定 Emscripten 运行时应调整画布元素的渲染目标的大小，使其在全屏模式下与元素的 CSS 大小 1:1 匹配。在高 DPI 显示器（window.devicePixelRatio > 1）上，CSS 大小与设备的物理屏幕分辨率不同。调用 emscripten_get_device_pixel_ratio() 以获取屏幕上 CSS 像素与实际设备像素之间的像素比率。当您想要渲染到与 DPI 无关的像素分辨率时，请使用此模式。

EMSCRIPTEN_FULLSCREEN_CANVAS_SCALE_HIDEF

指定 Emscripten 运行时应将画布渲染目标的大小调整为与设备上的物理屏幕分辨率 1:1 匹配。这对应于视网膜 iOS 和其他具有高 DPI 的移动和桌面设备上的高清显示器。使用此模式以匹配并渲染 1:1 到本机显示分辨率。

EMSCRIPTEN_FULLSCREEN_FILTERING

一种类似枚举的类型，指定当元素在全屏模式下显示时，要应用于该元素的哪种图像过滤算法。

EMSCRIPTEN_FULLSCREEN_FILTERING_DEFAULT

指定图像过滤模式不应从 CSS 样式中的现有设置更改。

EMSCRIPTEN_FULLSCREEN_FILTERING_NEAREST

在全屏模式下，将 CSS 样式应用于使用最近邻图像过滤算法显示内容的元素。

EMSCRIPTEN_FULLSCREEN_FILTERING_BILINEAR

在全屏模式下，将 CSS 样式应用于使用双线性图像过滤算法显示内容的元素。这是默认的浏览器行为。

结构体

EmscriptenFullscreenChangeEvent

在 fullscreenchange 事件中传递的事件结构体。

bool isFullscreen

指定浏览器页面上的元素当前是否处于全屏状态。

bool fullscreenEnabled

指定当前页面是否具有以全屏模式显示元素的能力。

EM_UTF8 nodeName

处于全屏模式的目标 HTML 元素的 nodeName。

最大大小 128 char（即 EM_UTF8 nodeName[128]）。

如果 isFullscreen 为 false，则 nodeName、id 以及 elementWidth 和 elementHeight 指定了刚退出全屏模式的元素的信息。

EM_UTF8 id

处于全屏模式的目标 HTML 元素的 ID。

最大大小 128 char（即 EM_UTF8 id[128]）。

int elementWidth
int elementHeight

更改全屏状态的元素的新像素大小。

int screenWidth
int screenHeight

整个屏幕的大小（以像素为单位）。

EmscriptenFullscreenStrategy

传递给函数 emscripten_request_fullscreen_strategy() 和 emscripten_enter_soft_fullscreen() 的选项结构体，用于配置目标元素在全屏模式下的显示方式。

EMSCRIPTEN_FULLSCREEN_SCALE scaleMode

指定在全屏模式下显示时，目标元素的 CSS 大小（显示大小）如何调整大小的规则。

EMSCRIPTEN_FULLSCREEN_CANVAS_SCALE canvasResolutionScaleMode

指定在全屏模式下显示时，目标元素的渲染目标大小（像素分辨率）如何调整。

EMSCRIPTEN_FULLSCREEN_FILTERING filteringMode

指定在全屏模式下应用于元素的图像过滤算法。

em_canvasresized_callback_func canvasResizedCallback

如果非零，则指向用户提供的回调函数，该函数将在 CSS 或画布渲染目标大小发生更改时被调用。使用此回调可靠地获取有关画布调整大小事件的信息。

void *canvasResizedCallbackUserData

存储一个自定义数据字段，该字段将传递给对用户提供的回调函数的所有调用。

回调函数

em_fullscreenchange_callback_func

用于 fullscreen event callback functions 的函数指针，定义为

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

  • eventType (int) – 全屏事件类型 (EMSCRIPTEN_EVENT_FULLSCREENCHANGE).

  • fullscreenChangeEvent (const EmscriptenFullscreenChangeEvent*) – 关于发生的全屏事件的信息。

  • userData (void*) – 最初传递给注册函数的 userData。

返回值

true (非零) 表示事件已被回调处理程序处理。

返回值类型

bool

函数

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

注册一个回调函数，用于接收 fullscreenchange 事件。

参数
返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_get_fullscreen_status(EmscriptenFullscreenChangeEvent *fullscreenStatus)

返回当前页面的 全屏 状态。

参数
返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_request_fullscreen(const char *target, bool deferUntilInEventHandler)

请求给定的目标元素过渡到全屏模式。

注意

此函数可以在任何地方调用，但出于网络安全原因，其关联的请求只能在用户生成的事件的事件处理程序内引发（例如，键盘、鼠标或触摸按压/释放）。这对移植和 deferUntilInEventHandler 的值有影响 - 有关更多信息，请参阅 受网络安全影响的函数。

注意

此函数仅执行全屏请求，而不会更改要在全屏模式下显示的 DOM 元素的任何参数。在撰写本文时，浏览器在全屏模式下显示元素的方式存在差异。有关更多信息，请阅读 https://github.com/emscripten-core/emscripten/issues/2556 中的讨论。要以在浏览器之间一致的方式在全屏模式下显示元素，请优先调用函数 emscripten_request_fullscreen_strategy()。此函数最好只在 emscripten_request_fullscreen_strategy() 定义的预配置预设以某种方式与开发人员的用例发生冲突的情况下调用。

参数

  • target (const char*) – 目标 HTML 元素 ID.

  • deferUntilInEventHandler (bool) – 如果 true 在用户生成的事件处理程序之外进行的请求将在用户下次按下键盘或鼠标按钮时自动延迟。如果 false，则如果在用户生成的事件处理程序之外调用，请求将失败。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

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

请求给定的目标元素以自定义的演示模式进入全屏模式。此函数与emscripten_request_fullscreen()相同，但此函数添加了控制大小调整和纵横比的选项，并确保行为在所有浏览器中一致。

注意

此函数对 DOM 进行更改以满足跨浏览器的演示一致性。这些更改旨在尽可能少地侵入，并且在恢复窗口浏览后，这些更改将被清除。如果这些更改有任何冲突，请参见函数 emscripten_request_fullscreen()，该函数执行简单的全屏请求，而不对 DOM 进行任何修改。

参数

  • fullscreenStrategy (const EmscriptenFullscreenStrategy*) – [in] 指向由调用者填充的配置结构，该结构指定全屏模式的显示选项。

EMSCRIPTEN_RESULT emscripten_exit_fullscreen(void)

从正确的全屏模式返回窗口浏览模式。

不要调用此函数尝试从软全屏模式返回到窗口浏览模式，反之亦然。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

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

进入“软”全屏模式，其中给定的目标元素显示在页面的整个客户端区域，而所有其他元素都隐藏，但实际上没有请求浏览器的全屏模式。此函数在实际全屏 API 不理想或不需要的情况下很有用，例如 Firefox OS 的打包应用程序，其中应用程序本质上已经覆盖了整个屏幕。

按下 esc 键不会自动退出软全屏模式。要返回到窗口演示模式，请手动调用函数 emscripten_exit_soft_fullscreen()。

EMSCRIPTEN_RESULT emscripten_exit_soft_fullscreen()

从软全屏模式返回窗口浏览模式。不要调用此函数尝试从真实全屏模式返回到窗口浏览模式，反之亦然。

指针锁定

定义

EMSCRIPTEN_EVENT_POINTERLOCKCHANGE

Emscripten pointerlockchange 事件。

EMSCRIPTEN_EVENT_POINTERLOCKERROR

Emscripten pointerlockerror 事件。

结构

EmscriptenPointerlockChangeEvent

在 pointerlockchange 事件中传递的事件结构。

bool isActive

指定浏览器页面上的元素当前是否启用了指针锁定。

EM_UTF8 nodeName

具有指针锁定激活的目标 HTML 元素的nodeName。

最大大小 128 char（即 EM_UTF8 nodeName[128]）。

EM_UTF8 id

具有指针锁定激活的目标 HTML 元素的 ID。

最大大小 128 char（即 EM_UTF8 id[128]）。

回调函数

em_pointerlockchange_callback_func

用于 pointerlockchange 事件 回调 函数 的函数指针，定义为

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

  • eventType (int) – 指针锁定更改事件的类型 (EMSCRIPTEN_EVENT_POINTERLOCKCHANGE）。

  • pointerlockChangeEvent (const EmscriptenPointerlockChangeEvent*) – 关于发生的指针锁定更改事件的信息。

  • userData (void*) – 最初传递给注册函数的 userData。

返回值

true (非零) 表示事件已被回调处理程序处理。

返回值类型

bool

em_pointerlockerror_callback_func

用于 pointerlockerror 事件 回调 函数 的函数指针，定义为

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

  • eventType (int) – 指针锁定错误事件的类型 (EMSCRIPTEN_EVENT_POINTERLOCKERROR）。

  • void* reserved (const) – 为将来使用保留；传入 0。

  • userData (void*) – 最初传递给注册函数的 userData。

返回值

true (非零) 表示事件已被回调处理程序处理。

返回值类型

bool

函数

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

注册回调函数以接收 pointerlockchange 事件。

指针锁定隐藏鼠标光标，并通过 mousemove 事件将相对鼠标移动事件专门提供给目标元素。

参数
返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

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

注册回调函数以接收 pointerlockerror 事件。

参数
返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_get_pointerlock_status(EmscriptenPointerlockChangeEvent *pointerlockStatus)

返回当前页面指针锁定状态。

参数
返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_request_pointerlock(const char *target, bool deferUntilInEventHandler)

请求给定的目标元素获取指针锁定。

注意

此函数可以在任何地方调用，但出于网络安全原因，其关联的请求只能在用户生成的事件的事件处理程序内引发（例如，键盘、鼠标或触摸按压/释放）。这对移植和 deferUntilInEventHandler 的值有影响 - 有关更多信息，请参阅 受网络安全影响的函数。

参数

  • target (const char*) – 目标 HTML 元素 ID.

  • deferUntilInEventHandler (bool) – 如果 true 在用户生成的事件处理程序之外进行的请求将在用户下次按下键盘或鼠标按钮时自动延迟。如果 false，则如果在用户生成的事件处理程序之外调用，请求将失败。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_exit_pointerlock(void)

退出指针锁定状态，并恢复显示鼠标光标。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

可见性

定义

EMSCRIPTEN_EVENT_VISIBILITYCHANGE

Emscripten visibilitychange 事件。

EMSCRIPTEN_VISIBILITY_HIDDEN

文档隐藏（不可见）。

EMSCRIPTEN_VISIBILITY_VISIBLE

文档至少部分可见。

EMSCRIPTEN_VISIBILITY_PRERENDER

文档已在屏幕外加载，并且不可见 (prerender）。

EMSCRIPTEN_VISIBILITY_UNLOADED

文档将要卸载。

结构

EmscriptenVisibilityChangeEvent

在 visibilitychange 事件中传递的事件结构。

bool hidden

如果为真，则当前浏览器页面现在已隐藏。

int visibilityState

指定当前页面可见性状态的更细粒度的状态。其中一个 EMSCRIPTEN_VISIBILITY_ 值。

回调函数

em_visibilitychange_callback_func

用于visibilitychange event callback functions的函数指针，定义为

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

  • eventType (int) – visibilitychange 事件的类型 (EMSCRIPTEN_VISIBILITY_HIDDEN).

  • visibilityChangeEvent (const EmscriptenVisibilityChangeEvent*) – 关于发生的 visibilitychange 事件的信息。

  • userData (void*) – 最初传递给注册函数的 userData。

返回值

true (非零) 表示事件已被回调处理程序处理。

返回值类型

bool

函数

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

注册一个回调函数，用于接收visibilitychange 事件。

参数

  • userData (void*) – 用户定义的数据，将传递给回调函数（对 API 不透明）。

  • useCapture (bool) – 设置true 以使用捕获。

  • callback (em_visibilitychange_callback_func) – 回调函数。该函数将使用事件类型、事件信息以及从此注册函数传递的用户数据进行调用。如果事件被消耗，则回调函数应返回 true。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_get_visibility_status(EmscriptenVisibilityChangeEvent *visibilityStatus)

返回当前页面可见性状态。

参数
返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

触摸

定义

EMSCRIPTEN_EVENT_TOUCHSTART
EMSCRIPTEN_EVENT_TOUCHEND
EMSCRIPTEN_EVENT_TOUCHMOVE
EMSCRIPTEN_EVENT_TOUCHCANCEL

Emscripten 触摸事件。

结构体

EmscriptenTouchPoint

指定页面上单个触摸点的状态。

long identifier

每个触摸点的识别号码。

long screenX
long screenY

相对于整个屏幕原点的触摸坐标，以像素为单位。

long clientX
long clientY

相对于视窗的触摸坐标，以像素为单位。

long pageX
long pageY

相对于视窗的触摸坐标，以像素为单位，包括任何滚动偏移量。

bool isChanged

指定此事件期间触摸点是否发生变化。

bool onTarget

指定此触摸点是否仍在最初按下它的原始目标上方。

long targetX
long targetY

这些字段给出了相对于接收输入事件的目标 DOM 元素的坐标空间映射的触摸坐标（Emscripten 特定扩展）。

long canvasX
long canvasY

映射到 Emscripten 画布客户端区域的触摸坐标，以像素为单位（Emscripten 特定扩展）。

EmscriptenTouchEvent

指定单个touchevent的数据。

double timestamp

记录数据时的绝对挂钟时间（毫秒）。

int numTouches

touches 数组中有效元素的数量。

bool ctrlKey
bool shiftKey
bool altKey
bool metaKey

指定触摸事件期间哪些修饰符处于活动状态。

EmscriptenTouchPoint touches[32]

当前活动触摸的数组，每个手指一个。

回调函数

em_touch_callback_func

用于touch event callback functions的函数指针，定义为

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

  • eventType (int) – 触摸事件的类型 (EMSCRIPTEN_EVENT_TOUCHSTART).

  • touchEvent (const EmscriptenTouchEvent*) – 关于发生的触摸事件的信息。

  • userData (void*) – 最初传递给注册函数的 userData。

返回值

true (非零) 表示事件已被回调处理程序处理。

返回值类型

bool

函数

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)

注册一个回调函数，用于接收触摸事件 : touchstart, touchend, touchmove 和 touchcancel.

参数

  • target (const char*) – 目标 HTML 元素 ID.

  • userData (void*) – 用户定义的数据，将传递给回调函数（对 API 不透明）。

  • useCapture (bool) – 设置true 以使用捕获。

  • callback (em_touch_callback_func) – 回调函数。该函数将使用事件类型、事件信息以及从此注册函数传递的用户数据进行调用。如果事件被消耗，则回调函数应返回 true。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

游戏手柄

定义

EMSCRIPTEN_EVENT_GAMEPADCONNECTED
EMSCRIPTEN_EVENT_GAMEPADDISCONNECTED

Emscripten 游戏手柄 事件。

结构体

EmscriptenGamepadEvent

表示游戏手柄的当前快照状态。

double timestamp

记录数据时的绝对挂钟时间（毫秒）。

int numAxes

axis 数组中有效轴条目的数量。

int numButtons

analogButton 和 digitalButton 数组中有效按钮条目的数量。

double axis[64]

游戏手柄轴的模拟状态，范围为 [-1, 1]。

double analogButton[64]

游戏手柄按钮的模拟状态，范围为 [0, 1]。

bool digitalButton[64]

游戏手柄按钮的数字状态，为 0 或 1。

bool connected

指定此游戏手柄是否已连接到浏览器页面。

long index

与该手柄关联的序数，从零开始。

EM_UTF8 id

连接的手柄设备的品牌或样式的 ID。 通常，这将包括 USB 供应商和产品 ID。

最大大小为 64 个 char（即 EM_UTF8 id[64]）。

EM_UTF8 mapping

一个字符串，用于标识该设备的布局或控制映射。

最大大小为 64 个 char（即 EM_UTF8 mapping[64]）。

回调函数

em_gamepad_callback_func

用于 gamepad event callback functions 的函数指针，定义为

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

  • eventType (int) – 手柄事件的类型 (EMSCRIPTEN_EVENT_GAMEPADCONNECTED).

  • gamepadEvent (const EmscriptenGamepadEvent*) – 关于发生的 gamepad 事件的信息。

  • userData (void*) – 最初传递给注册函数的 userData。

返回值

true (非零) 表示事件已被回调处理程序处理。

返回值类型

bool

函数

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)

注册一个回调函数，用于接收 手柄 事件：gamepadconnected 和 gamepaddisconnected。

参数

  • userData (void*) – 用户定义的数据，将传递给回调函数（对 API 不透明）。

  • useCapture (bool) – 设置true 以使用捕获。

  • callback (em_gamepad_callback_func) – 回调函数。 该函数使用事件类型、关于事件的信息以及从该注册函数传递的用户数据来调用。 如果事件被消耗，则回调函数应返回 true。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_sample_gamepad_data(void)

该函数采样连接的手柄数据的新状态，并返回 EMSCRIPTEN_RESULT_SUCCESS（如果当前浏览器支持手柄 API），或 EMSCRIPTEN_RESULT_NOT_SUPPORTED（如果当前浏览器不支持手柄 API）。 请注意，即使返回 EMSCRIPTEN_RESULT_SUCCESS，当前浏览器选项卡也可能没有连接任何手柄。

在调用函数 emscripten_get_num_gamepads() 或 emscripten_get_gamepad_status() 之前，请调用该函数。

int emscripten_get_num_gamepads(void)

在调用 emscripten_sample_gamepad_data() 之后，该函数将返回连接到系统的 手柄数量，或者如果当前浏览器不支持 手柄，则返回 EMSCRIPTEN_RESULT_NOT_SUPPORTED。

注意

在按下手柄上的按钮之前，手柄不会显示为已连接。

注意

手柄 API 使用 手柄状态对象数组来返回每个设备的状态。 设备通过它们在该数组中的索引来识别。 因此，如果先连接手柄 A，然后连接手柄 B，然后断开手柄 A 的连接，则手柄 B 将不会取代手柄 A，因此在这种情况下，即使手柄 A 不再存在，该函数仍将继续返回 2 作为连接的手柄数量。 为了找出实际连接的手柄数量，请监听 gamepadconnected 和 gamepaddisconnected 事件。 将函数 emscripten_get_num_gamepads() 的返回值减 1 可视为可传递给函数 emscripten_get_gamepad_status() 的最大索引值。

返回值

连接到浏览器选项卡的手柄数量。

返回值类型

int

EMSCRIPTEN_RESULT emscripten_get_gamepad_status(int index, EmscriptenGamepadEvent *gamepadState)

在调用 emscripten_sample_gamepad_data() 之后，该函数将返回位于控制器数组中给定索引处的 手柄控制器的当前 手柄状态的快照。

参数
返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

电池

定义

EMSCRIPTEN_EVENT_BATTERYCHARGINGCHANGE
EMSCRIPTEN_EVENT_BATTERYLEVELCHANGE

Emscripten 电池管理器 事件。

结构

EmscriptenBatteryEvent

在 电池管理器 事件中传递的事件结构：chargingchange 和 levelchange。

double chargingTime

电池充满电所剩的时间（秒）。

double dischargingTime

电池耗尽并导致系统挂起所剩的时间（秒）。

double level

当前电池电量，范围为 0 到 1.0。

bool charging;

如果电池正在充电，则为 true，否则为 false。

回调函数

em_battery_callback_func

用于 batterymanager event callback functions 的函数指针，定义为

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

  • eventType (int) – batterymanager 事件的类型 (EMSCRIPTEN_EVENT_BATTERYCHARGINGCHANGE).

  • batteryEvent (const EmscriptenBatteryEvent*) – 关于发生的 batterymanager 事件的信息。

  • userData (void*) – 最初传递给注册函数的 userData。

返回值

true (非零) 表示事件已被回调处理程序处理。

返回值类型

bool

函数

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)

注册一个回调函数，用于接收 电池管理器 事件：chargingchange 和 levelchange。

参数

  • userData (void*) – 用户定义的数据，将传递给回调函数（对 API 不透明）。

  • callback (em_battery_callback_func) – 回调函数。 该函数使用事件类型、关于事件的信息以及从该注册函数传递的用户数据来调用。 如果事件被消耗，则回调函数应返回 true。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_get_battery_status(EmscriptenBatteryEvent *batteryState)

返回当前电池状态。

参数
返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

振动

函数

EMSCRIPTEN_RESULT emscripten_vibrate(int msecs)

产生持续指定时间（毫秒）的 振动。

参数

  • msecs (int) – 振动所需的持续时间（毫秒）。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_vibrate_pattern(int *msecsArray, int numEntries)

产生复杂的振动反馈模式。

参数

  • msecsArray (int*) – 一个包含计时条目的数组 [on, off, on, off, on, off, …]，其中每隔一个条目指定振动持续时间，另一个条目指定静默持续时间。

  • numEntries (int) – 数组 msecsArray 中整数的个数。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

页面卸载

定义

EMSCRIPTEN_EVENT_BEFOREUNLOAD

Emscripten beforeunload 事件。

回调函数

em_beforeunload_callback

用于 beforeunload event callback functions 的函数指针，定义为

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

  • eventType (int) – beforeunload 事件类型 (EMSCRIPTEN_EVENT_BEFOREUNLOAD).

  • reserved (const void*) – 为将来使用保留；传入 0。

  • userData (void*) – 最初传递给注册函数的 userData。

返回值

返回一个要显示给用户的字符串。

返回值类型

char*

函数

EMSCRIPTEN_RESULT emscripten_set_beforeunload_callback(void *userData, em_beforeunload_callback callback)

注册一个回调函数用于接收页面 beforeunload 事件。

挂钩到这个事件，以便在页面关闭之前执行操作（例如，显示一个通知询问用户是否真的要离开页面）。

参数

  • userData (void*) – 用户定义的数据，将传递给回调函数（对 API 不透明）。

  • callback (em_beforeunload_callback) – 一个回调函数。该函数使用事件类型、有关事件的信息以及从该注册函数传递的用户数据调用。如果事件被消耗，则回调函数应返回 true。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

WebGL 上下文

定义

EMSCRIPTEN_EVENT_WEBGLCONTEXTLOST
EMSCRIPTEN_EVENT_WEBGLCONTEXTRESTORED

Emscripten WebGL 上下文 事件。

EMSCRIPTEN_WEBGL_CONTEXT_HANDLE

表示 Emscripten WebGL 上下文对象的句柄。值 0 表示无效/无上下文（这是一个 intptr_t 的类型定义）。

结构体

EmscriptenWebGLContextAttributes

指定 WebGL 上下文创建参数。

bool alpha

如果 true，则为上下文请求 alpha 通道。如果创建 alpha 通道，则可以将画布渲染与底层网页内容混合。默认值：true。

bool depth

如果 true，则请求至少 16 位的深度缓冲区。如果 false，则不会初始化深度缓冲区。默认值：true。

bool stencil

如果 true，则请求至少 8 位的模板缓冲区。如果 false，则不会初始化模板缓冲区。默认值：false。

bool antialias

如果 true，则使用浏览器指定的算法和质量级别初始化抗锯齿。如果 false，则禁用抗锯齿。默认值：true。

bool premultipliedAlpha

如果 true，则渲染上下文的 alpha 通道将被视为表示预乘 alpha 值。如果 false，则 alpha 通道表示非预乘 alpha。默认值：true。

bool preserveDrawingBuffer

如果 true，则在连续的 requestAnimationFrame() 调用之间保留绘图缓冲区的内容。如果 false，则在每次 requestAnimationFrame() 开始时清除颜色、深度和模板。通常将此设置为 false 会提供更好的性能。默认值：false。

EM_WEBGL_POWER_PREFERENCE powerPreference

向 WebGL 画布实现提供一个提示，说明它应该如何选择使用可用的 GPU 资源。EM_WEBGL_POWER_PREFERENCE_DEFAULT、EM_WEBGL_POWER_PREFERENCE_LOW_POWER、EM_WEBGL_POWER_PREFERENCE_HIGH_PERFORMANCE 之一。

bool failIfMajorPerformanceCaveat

如果 true，则请求上下文创建在浏览器只能创建不能提供良好硬件加速性能的上下文的情况下中止。默认值：false。

int majorVersion
int minorVersion

Emscripten 特定的扩展，指定要初始化的 WebGL 上下文版本。

例如，传入 majorVersion=1、minorVersion=0 以请求 WebGL 1.0 上下文，传入 majorVersion=2、minorVersion=0 以请求 WebGL 2.0 上下文。

默认值：majorVersion=1、minorVersion=0

bool enableExtensionsByDefault

如果 true，则在上下文创建后，所有与 GLES2 兼容的非性能影响型 WebGL 扩展将自动为你启用。如果 false，则默认情况下不会启用任何扩展，你需要手动调用 emscripten_webgl_enable_extension() 来启用你想要使用的每个扩展。默认值：true。

bool explicitSwapControl

默认情况下，当 explicitSwapControl 处于其默认状态 false 时，渲染的 WebGL 内容会在使用 WebGL 渲染的事件处理程序返回到浏览器事件循环时隐式地呈现（显示给用户）。如果将 explicitSwapControl 设置为 true，则渲染的内容在事件处理程序函数完成时不会自动显示在屏幕上，而是通过 emscripten_webgl_commit_frame() 函数将交换控制权交给用户管理。

为了能够设置 explicitSwapControl==true，必须通过以下两种方式之一显式启用对它的支持：1) 通过添加 -sOFFSCREEN_FRAMEBUFFER Emscripten 链接器标志，并启用 renderViaOffscreenBackBuffer==1，或 2) 通过添加链接器标志 -sOFFSCREENCANVAS_SUPPORT，并在支持 OffscreenCanvas 的浏览器中运行。

bool renderViaOffscreenBackBuffer

如果 true，则会为创建的 WebGL 上下文分配一个额外的中间后备缓冲区（离屏渲染目标），并且渲染将发生在这个后备缓冲区，而不是直接发生在 WebGL 的“默认后备缓冲区”。如果满足以下条件，则需要启用此功能：1) explicitSwapControl==true 且浏览器不支持 OffscreenCanvas，2) 当在工作线程中执行 WebGL 渲染且浏览器不支持 OffscreenCanvas，以及 3) 当从多个线程同时执行 WebGL 上下文访问时（与是否支持 OffscreenCanvas 无关）。

由于支持离屏帧缓冲区会为编译后的输出添加一些额外的代码，因此必须通过 -sOFFSCREEN_FRAMEBUFFER Emscripten 链接器标志显式启用对它的支持。当同时使用 -sOFFSCREEN_FRAMEBUFFER 和 -sOFFSCREENCANVAS_SUPPORT 链接器标志启用构建时，离屏后备缓冲区可以用作类似于 polyfill 的兼容性回退，以便在浏览器不支持 OffscreenCanvas API 时从 pthread 中启用渲染 WebGL。

bool proxyContextToMainThread

此成员指定在 pthread 中创建 WebGL 上下文时将用于创建的 WebGL 上下文的线程模型。可能的值有三个：EMSCRIPTEN_WEBGL_CONTEXT_PROXY_DISALLOW、EMSCRIPTEN_WEBGL_CONTEXT_PROXY_FALLBACK 或 EMSCRIPTEN_WEBGL_CONTEXT_PROXY_ALWAYS。如果指定了 EMSCRIPTEN_WEBGL_CONTEXT_PROXY_DISALLOW，则 WebGLRenderingContext 对象将在调用 emscripten_webgl_create_context() 函数的 pthread 内创建，作为基于 OffscreenCanvas 的渲染上下文。这只有在以下情况下才有可能：1）当前浏览器支持 OffscreenCanvas 规范，2）代码使用启用了 -sOFFSCREENCANVAS_SUPPORT 链接器标志进行编译，3）上下文正在创建的 Canvas 对象已使用函数 emscripten_pthread_attr_settransferredcanvases() 传输到调用 pthread（在 pthread 最初创建时），以及 4）在同一时间，从给定 Canvas 中不存在基于 OffscreenCanvas 的上下文。

如果 WebGL 渲染上下文作为基于 OffscreenCanvas 的上下文创建，它将受到限制，只有创建上下文的 pthread 可以启用对它的访问（通过 emscripten_webgl_make_context_current() 函数）。其他线程将无法激活对上下文的渲染，即基于 OffscreenCanvas 的上下文本质上“绑定”到创建它们的 pthread。

如果当前浏览器不支持 OffscreenCanvas，您可以指定 EMSCRIPTEN_WEBGL_CONTEXT_PROXY_ALWAYS WebGL 上下文创建标志。如果传递此标志，并且代码使用启用了 -sOFFSCREEN_FRAMEBUFFER 进行编译，则 WebGL 上下文将作为“代理上下文”创建。在此上下文模式下，WebGLRenderingContext 对象实际上将在主浏览器线程上创建，并且所有 WebGL API 调用将作为异步消息从 pthread 代理到主线程。与基于 OffscreenCanvas 的上下文相比，这将对性能和延迟造成影响，但是与基于 OffscreenCanvas 的上下文不同，代理上下文可以在任意数量的 pthread 之间共享：您可以在任何 pthread 中使用 emscripten_webgl_make_context_current() 函数来激活和停用对 WebGL 上下文的访问：例如，您可能有一个 WebGL 加载线程和另一个 WebGL 渲染线程，它们通过使用 emscripten_webgl_make_context_current() 函数协作地获取和释放对 WebGL 渲染上下文的访问来协调对 WebGL 渲染上下文的共享访问。代理上下文不需要浏览器有任何特殊支持，因此任何支持 WebGL 的浏览器都可以创建代理的 WebGL 上下文。

即使浏览器支持 OffscreenCanvas，EMSCRIPTEN_WEBGL_CONTEXT_PROXY_ALWAYS WebGL 上下文创建标志也将始终创建一个代理上下文。如果您希望在浏览器支持时优先创建高性能的 OffscreenCanvas 上下文，但仅回退到代理的 WebGL 上下文以保持与尚不支持 OffscreenCanvas 的浏览器的兼容性，您可以指定 EMSCRIPTEN_WEBGL_CONTEXT_PROXY_FALLBACK 上下文创建标志。要使用此标志，代码应使用 -sOFFSCREEN_FRAMEBUFFER 和 -sOFFSCREENCANVAS_SUPPORT 链接器标志进行编译。

调用 emscripten_webgl_init_context_attributes() 后，proxyContextToMainThread 的默认值为 EMSCRIPTEN_WEBGL_CONTEXT_PROXY_DISALLOW，如果 WebGL 上下文是在主线程上创建的。这意味着默认情况下在主线程上创建的 WebGL 上下文在多个线程之间不可共享（以避免在不需要时启用代理时/如果启用代理会导致意外的性能损失）。要创建可以在多个 pthread 之间共享的上下文，请将 proxyContextToMainThread 标志设置为 EMSCRIPTEN_WEBGL_CONTEXT_PROXY_ALWAYS。

回调函数

em_webgl_context_callback

WebGL Context 事件 回调 函数 的函数指针，定义为

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

  • eventType (int) – WebGL 上下文 事件 的类型。

  • reserved (const void*) – 为将来使用保留；传入 0。

  • userData (void*) – 最初传递给注册函数的 userData。

返回值

true (非零) 表示事件已被回调处理程序处理。

返回值类型

bool

函数

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)

注册一个用于 canvas WebGL 上下文 事件的回调函数：webglcontextlost 和 webglcontextrestored。

参数

  • target (const char*) – 目标 HTML 元素 ID.

  • userData (void*) – 用户定义的数据，将传递给回调函数（对 API 不透明）。

  • useCapture (bool) – 设置true 以使用捕获。

  • callback (em_webgl_context_callback) – 回调函数。该函数将使用事件类型、有关事件的信息以及从此注册函数传递的用户数据进行调用。如果事件被使用，则回调应返回 true。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

bool emscripten_is_webgl_context_lost(EMSCRIPTEN_WEBGL_CONTEXT_HANDLE context)

查询给定的 WebGL 上下文，以查看它是否处于丢失的上下文状态。

参数
返回值

如果 WebGL 上下文处于丢失状态（或上下文不存在）则为 true

返回值类型

bool

void emscripten_webgl_init_context_attributes(EmscriptenWebGLContextAttributes *attributes)

将给定 EmscriptenWebGLContextAttributes 结构的所有字段填充为其在 WebGL 1.0 中使用的默认值。

调用此函数作为向前兼容的方法，以确保如果将来在 EmscriptenWebGLContextAttributes 结构中添加了新字段，它们也将在没有更改任何代码的情况下被默认初始化。

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

创建并返回一个新的 WebGL 上下文。

注意

  • 成功调用此函数不会立即激活该渲染上下文。在创建上下文后，调用 emscripten_webgl_make_context_current() 来激活它。

  • 此函数将尝试初始化完全请求的上下文版本。它不会例如初始化更新的向后兼容版本或类似版本。

参数

  • target (const char*) – 要在其中初始化 WebGL 上下文的 DOM canvas 元素。

  • attributes (const EmscriptenWebGLContextAttributes*) – 请求的上下文版本的属性。

返回值

成功时，非零值，表示创建上下文的句柄。失败时，为 0。

返回值类型

EMSCRIPTEN_WEBGL_CONTEXT_HANDLE

EMSCRIPTEN_RESULT emscripten_webgl_make_context_current(EMSCRIPTEN_WEBGL_CONTEXT_HANDLE context)

激活给定的 WebGL 上下文以进行渲染。调用此函数后，所有 OpenGL 函数（glBindBuffer()、glDrawArrays() 等）都可以应用于给定的 GL 上下文。

参数
返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

EMSCRIPTEN_WEBGL_CONTEXT_HANDLE emscripten_webgl_get_current_context()

返回当前活动的 WebGL 渲染上下文，如果没有上下文处于活动状态，则返回 0。在没有活动的渲染上下文的情况下调用任何 WebGL 函数是未定义的，并且可能会抛出 JavaScript 异常。

返回值

当前活动的 WebGL 渲染上下文，如果没有上下文处于活动状态，则返回 0。

返回值类型

EMSCRIPTEN_WEBGL_CONTEXT_HANDLE

EMSCRIPTEN_RESULT emscripten_webgl_get_context_attributes(EMSCRIPTEN_WEBGL_CONTEXT_HANDLE context, EmscriptenWebGLContextAttributes *outAttributes)

获取用于初始化给定 WebGL 上下文的上下文创建属性。

参数
返回值

成功时，EMSCRIPTEN_RESULT_SUCCESS。

EMSCRIPTEN_RESULT emscripten_webgl_commit_frame()

呈现（“交换”）当前活动的 WebGL 上下文上渲染的内容，以便在 canvas 上可见。此函数在使用 explicitSwapControl==true 上下文创建属性创建的 WebGL 上下文中可用。如果 explicitSwapControl==false，则在从调用事件处理程序返回到浏览器时，“隐式”地将渲染的内容显示在屏幕上。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值，表示失败的原因。

返回值类型

EMSCRIPTEN_RESULT

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

获取指定 WebGL 上下文的 drawingBufferWidth 和 drawingBufferHeight。

参数

  • context (EMSCRIPTEN_WEBGL_CONTEXT_HANDLE) – 要获取宽高信息的 WebGL 上下文。

  • *width (int) – 上下文的 drawingBufferWidth。

  • *height (int) – 上下文的 drawingBufferHeight。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT emscripten_webgl_destroy_context(EMSCRIPTEN_WEBGL_CONTEXT_HANDLE context)

删除给定的 WebGL 上下文。如果该上下文是活动的，则不会设置任何活动上下文。

参数
返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

bool emscripten_webgl_enable_extension(EMSCRIPTEN_WEBGL_CONTEXT_HANDLE context, const char *extension)

在给定上下文中启用给定的扩展。

参数
返回值

如果给定的扩展由上下文支持，则为 true，否则为 false。

返回值类型

bool

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

调整 DOM 中给定 Canvas 元素的像素宽度和高度。

参数

  • target – 指定要调整大小的画布的选择器。

  • width – Canvas 元素的新像素宽度。

  • height – Canvas 元素的新像素高度。

返回值

如果调整大小成功，则为 EMSCRIPTEN_RESULT_SUCCESS，如果失败，则为 EMSCRIPTEN_RESULT_* 错误值之一。

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

获取 DOM 中给定 Canvas 元素的当前像素宽度和高度。

参数

  • target – 指定要调整大小的画布的选择器。

  • width – 指向接收画布元素宽度的内存位置的指针。该指针不能为 null。

  • height – 指向接收画布元素高度的内存位置的指针。该指针不能为 null。

返回值

如果宽度和高度检索成功，则为 EMSCRIPTEN_RESULT_SUCCESS，如果失败，则为 EMSCRIPTEN_RESULT_* 错误值之一。

CSS

函数

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

调整 Emscripten 网页上由 target 指定的元素的 CSS 宽度和高度。

参数

  • target (const char*) – 要调整大小的元素。

  • width (double) – 元素的新宽度。

  • height (double) – 元素的新高度。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

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

获取由 target 指定的元素的当前 CSS 宽度和高度。

参数

  • target (const char*) – 要获取大小的元素。

  • width (double*) – 元素的宽度。

  • height (double*) – 元素的高度。

返回值

EMSCRIPTEN_RESULT_SUCCESS，或其他结果值之一。

返回值类型

EMSCRIPTEN_RESULT

动画和计时

这里提供的 API 是直接调用相关 Web API 的低级函数，没有其他功能。它们不会与 emscripten 运行时集成，例如检查程序是否已停止并取消回调。为此，请参阅函数 emscripten_set_main_loop()。

函数

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

在调用线程上对给定函数执行 setTimeout() 回调调用。

参数

  • cb – 要调用的回调函数。

  • msecs – 回调应触发的毫秒延迟。

  • userData – 指定一个自定义数据指针大小的字段，该字段将传递给回调函数。

返回值

对 setTimeout() 调用的 ID，可以传递给 emscripten_clear_timeout() 以取消挂起的超时计时器。

void emscripten_clear_timeout(long setTimeoutId)

取消调用线程上挂起的 setTimeout() 调用。此函数必须在与注册回调的 emscripten_set_timeout() 调用相同的线程上调用。

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

在调用线程上对给定函数初始化一个 setTimeout() 循环。指定的回调函数 ‘cb’ 需要不断返回 true，只要动画循环应继续运行。当函数返回 false 时，setTimeout() 循环将停止。注意：循环将立即以 0 毫秒延迟开始 - 传入的 intervalMsecs 时间指定后续回调调用应触发的间隔。

参数

  • cb – 要调用的回调函数。

  • intervalMsecs – 回调应不断触发的毫秒间隔。

  • userData – 指定一个自定义数据指针大小的字段，该字段将传递给回调函数。

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

在调用线程上对给定函数执行单个 requestAnimationFrame() 回调调用。

参数

  • cb – 要调用的回调函数。此函数将在调用时接收当前高精度计时器值（performance.now() 的值）。

  • userData – 指定一个自定义数据指针大小的字段，该字段将传递给回调函数。

返回值

对 requestAnimationFrame() 调用的 ID，可以传递给 emscripten_cancel_animation_frame() 以取消挂起的 requestAnimationFrame 计时器。

void emscripten_cancel_animation_frame(long requestAnimationFrameId)

在注册的 requestAnimationFrame() 回调在调用线程上运行之前取消它。此函数必须在与注册回调的 emscripten_request_animation_frame() 调用相同的线程上调用。

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

在调用线程上对给定函数初始化一个 requestAnimationFrame() 循环。指定的回调函数 ‘cb’ 需要不断返回 true，只要动画循环应继续运行。当函数返回 false 时，动画帧循环将停止。

参数

  • cb – 要调用的回调函数。此函数将在调用时接收当前高精度计时器值（performance.now() 的值）。

  • userData – 指定一个自定义数据指针大小的字段，该字段将传递给回调函数。

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

在调用线程上对给定函数执行一个 setImmediate() 回调调用。返回对 setImmediate() 调用的 ID，可以传递给 emscripten_clear_immediate() 函数以取消挂起的 setImmediate() 调用。TODO：目前 setImmediate() 的 polyfill 仅在主浏览器线程中有效，而在 pthreads 中无效。

参数

  • cb – 要调用的回调函数。

  • userData – 指定一个自定义数据指针大小的字段，该字段将传递给回调函数。

返回值

对 setImmediate() 调用的 ID，可以传递给 emscripten_clear_immediate() 以取消挂起的回调。

void emscripten_clear_immediate(long setImmediateId)

取消当前线程上待处理的 setImmediate() 调用。此函数必须在与注册回调的 emscripten_set_immediate() 调用相同的线程上调用。

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

在当前线程的给定函数上初始化一个 setImmediate() 循环。指定的回调函数 'cb' 需要一直返回 true，只要循环应该继续运行。当函数返回 false 时，setImmediate() 循环将停止。 TODO: 目前 setImmediate() 的 polyfill 仅在主浏览器线程中有效，而在 pthreads 中无效。

参数

  • cb – 要调用的回调函数。

  • userData – 指定一个自定义数据指针大小的字段，该字段将传递给回调函数。

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

在当前线程的给定函数上初始化一个 setInterval() 循环。返回初始化循环的 ID。用此 ID 调用 emscripten_clear_interval() 来终止循环。注意，此函数将导致给定的回调函数被重复调用。不要在回调函数内部对同一个回调函数再次调用 emscripten_set_interval()，因为这样会注册多个同时运行的循环。

参数

  • cb – 要调用的回调函数。

  • intervalMsecs – 回调应不断触发的毫秒间隔。

  • userData – 指定一个自定义数据指针大小的字段，该字段将传递给回调函数。

返回值

一个 setInterval() 调用的 ID，可以传递给 emscripten_clear_interval() 来取消当前正在执行的间隔计时器。

void emscripten_clear_interval(long setIntervalId)

取消当前线程上正在执行的 setInterval() 循环。此函数必须在与注册回调的 emscripten_set_interval() 调用相同的线程上调用。

参数
double emscripten_date_now(void)

在当前线程中调用 JavaScript Date.now() 函数。

返回值

自 UNIX 纪元（1970 年 1 月 1 日星期四 00:00:00）以来的毫秒数。

double emscripten_performance_now(void)

在当前线程中调用 JavaScript performance.now() 函数。注意，此函数返回的值基于不同的时间偏移，具体取决于在哪个线程中调用此函数。也就是说，不要跨线程比较 performance.now() 返回的绝对时间值。（比较相对时间值是可以的）。在主线程中，此函数返回自页面启动以来的毫秒数。在 Web Worker/pthread 中，此函数返回自托管该 pthread 的 Worker 启动以来的毫秒数。（当一个 pthread 退出并启动另一个 pthread 时，Worker 通常不会被拆卸，而是被保存在一个池中，因此此函数不保证从 pthread 启动时开始计时）。

返回值

一个高精度的毫秒级挂钟时间值。

抛出

函数

void emscripten_throw_number(double number)

调用 JavaScript throw 语句并抛出一个数字。

void emscripten_throw_string(const char *utf8String)

调用 JavaScript throw 语句并抛出一个字符串。

void emscripten_unwind_to_js_event_loop(void)

抛出一个 JavaScript 异常，该异常会解开堆栈并将执行权交还给浏览器事件循环。此函数不会将执行权返回给调用代码。

当移植进入无限循环的代码时，此函数非常有用。我们无需实际运行无限循环（因为 Web 上不允许这样做），而是可以设置循环体以异步执行（使用 emscripten_set_main_loop() 或其他方法），并调用此函数来停止执行，这一点很重要，因为我们不希望执行正常继续。