The C++ APIs in html5.h define the Emscripten low-level glue bindings to interact with HTML5 events from native code.
Tip
The C++ APIs map closely to their equivalent HTML5 JavaScript APIs. The HTML5 specifications listed below provide additional detailed reference “over and above” the information provided in this document.
In addition, the Test/Example code can be reviewed to see how the code is used.
The HTML5 specifications for APIs that are mapped by html5.h include:
- DOM Level 3 Events: Keyboard, Mouse, Mouse Wheel, Resize, Scroll, Focus.
- Device Orientation Events for gyro and accelerometer.
- Screen Orientation Events for portrait/landscape handling.
- Fullscreen Events for browser canvas fullscreen modes transitioning.
- Pointer Lock Events for relative-mode mouse motion control.
- Vibration API for mobile device haptic vibration feedback control.
- Page Visibility Events for power management control.
- Touch Events.
- Gamepad API.
- Beforeunload event.
- WebGL context events
Table of Contents
Most of these APIs use an event-based architecture; functionality is accessed by registering a callback function that will be called when the event occurs.
Note
The Gamepad API is currently an exception, as only a polling API is available. For some APIs, both an event-based and a polling-based model are exposed.
The typical format of registration functions is as follows (some methods may omit various parameters):
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. EM_BOOL useCapture, // Whether or not to use capture. em_someevent_callback_func callback // Callback function. );
The target parameter is the ID of the HTML element to which the callback registration is to be applied. This field has the following special meanings:
- 0 or NULL: A default element is chosen automatically based on the event type, which should be reasonable most of the time.
- #window: The event listener is applied to the JavaScript window object.
- #document: The event listener is applied to the JavaScript document object.
- #screen: The event listener is applied to the JavaScript window.screen object.
- #canvas: The event listener is applied to the Emscripten default WebGL canvas element.
- Any other string without a leading hash “#” sign: The event listener is applied to the element on the page with the given ID.
The userData parameter is a user-defined value that is passed (unchanged) to the registered event callback. This can be used to, for example, pass a pointer to a C++ class or similarly to enclose the C API in a clean object-oriented manner.
The useCapture parameter maps to useCapture in EventTarget.addEventListener. It indicates whether or not to initiate capture: if true the callback will be invoked only for the DOM capture and target phases; if false the callback will be triggered during the target and bubbling phases. See DOM Level 3 Events for a more detailed explanation.
Most functions return the result using the type EMSCRIPTEN_RESULT. Non-zero and positive values denote success. Negative values signal failure. None of the functions fail or abort by throwing a JavaScript or C++ exception. If a particular browser does not support the given feature, the value EMSCRIPTEN_RESULT_NOT_SUPPORTED will be returned at the time the callback is registered.
When the event occurs the callback is invoked with the relevant event “type” (for example EMSCRIPTEN_EVENT_CLICK), a struct containing the details of the event that occurred, and the userData that was originally passed to the registration function. The general format of the callback function is:
typedef EM_BOOL (*em_someevent_callback_func) // Callback function. Return true if event is "consumed".
(
int eventType, // The type of event.
const EmscriptenSomeEvent *keyEvent, // Information about the event.
void *userData // User data passed from the registration function.
);
Callback handlers that return an EM_BOOL may specify true to signal that the handler consumed the event (this suppresses the default action for that event by calling its .preventDefault(); member). Returning false indicates that the event was not consumed — the default browser event action is carried out and the event is allowed to pass on/bubble up as normal.
Calling a registration function with a null pointer for the callback causes a de-registration of that callback from the given target element. All event handlers are also automatically unregistered when the C exit() function is invoked during the atexit handler pass. Either use the function emscripten_set_main_loop() or set Module.noExitRuntime = true; to make sure that leaving main() will not immediately cause an exit() and clean up the event handlers.
Some functions, including emscripten_request_pointerlock() and emscripten_request_fullscreen(), are affected by web security.
While the functions can be called anywhere, the actual “requests” can only be raised inside the handler for a user-generated event (for example a key, mouse or touch press/release).
When porting code, it may be difficult to ensure that the functions are called inside appropriate event handlers (so that the requests are raised immediately). As a convenience, developers can set deferUntilInEventHandler=true to automatically defer insecure requests until the user next presses a keyboard or mouse button. This simplifies porting, but often results in a poorer user experience. For example, the user must click once on the canvas to hide the pointer or transition to full screen.
Where possible, the functions should only be called inside appropriate event handlers. Setting deferUntilInEventHandler=false causes the functions to abort with an error if the request is refused due to a security restriction: this is a useful mechanism for discovering instances where the functions are called outside the handler for a user-generated event.
This is the Emscripten type for a bool.
This is the Emscripten type for a UTF8 string (maps to a char). This is used for node names, element ids, etc.
Most functions in this API return a result of type EMSCRIPTEN_RESULT. None of the functions fail or abort by throwing a JavaScript or C++ exception. If a particular browser does not support the given feature, the value EMSCRIPTEN_RESULT_NOT_SUPPORTED will be returned at the time the callback is registered.
This type is used to return the result of most functions in this API. Positive values denote success, while zero and negative values signal failure. Possible values are listed below.
The operation succeeded.
The requested operation cannot be completed now for web security reasons, and has been deferred for completion in the next event handler.
The given operation is not supported by this browser or the target element. This value will be returned at the time the callback is registered if the operation is not supported.
The requested operation could not be completed now for web security reasons. It failed because the user requested the operation not be deferred.
The operation failed because the specified target element is invalid.
The operation failed because the specified target element was not found.
The operation failed because an invalid parameter was passed to the function.
Generic failure result message, returned if no specific result is available.
The operation failed because no data is currently available.
The event structure passed in keyboard events: keypress, keydown and keyup.
Note that since the DOM Level 3 Events spec is very recent at the time of writing (2014-03), uniform support for the different fields in the spec is still in flux. Be sure to check the results in multiple browsers. See the unmerged pull request #2222 for an example of how to interpret the legacy key events.
The printed representation of the pressed key.
Maximum size 32 char (i.e. EM_UTF8 key[32]).
A string that identifies the physical key being pressed. The value is not affected by the current keyboard layout or modifier state, so a particular key will always return the same value.
Maximum size 32 char (i.e. EM_UTF8 code[32]).
Indicates the location of the key on the keyboard. One of the DOM_KEY_LOCATION values.
Specifies which modifiers were active during the key event.
A locale string indicating the configured keyboard locale. This may be an empty string if the browser or device doesn’t know the keyboard’s locale.
Maximum size 32 char (i.e. EM_UTF8 locale[32]).
The following fields are values from previous versions of the DOM key events specifications. See the character representation of the key. This is the field char from the docs, but renamed to charValue to avoid a C reserved word.
Maximum size 32 char (i.e. EM_UTF8 charValue[32]).
Warning
This attribute has been dropped from DOM Level 3 events.
The Unicode reference number of the key; this attribute is used only by the keypress event. For keys whose char attribute contains multiple characters, this is the Unicode value of the first character in that attribute.
Warning
This attribute is deprecated, you should use the field key instead, if available.
A system and implementation dependent numerical code identifying the unmodified value of the pressed key.
Warning
This attribute is deprecated, you should use the field key instead, if available.
A system and implementation dependent numeric code identifying the unmodified value of the pressed key; this is usually the same as keyCode.
Warning
This attribute is deprecated, you should use the field key instead, if available. Note thought that while this field is deprecated, the cross-browser support for which may be better than for the other fields, so experimentation is recommended. Read issue https://github.com/kripken/emscripten/issues/2817 for more information.
Function pointer for the keypress callback functions, defined as:
typedef EM_BOOL (*em_key_callback_func)(int eventType, const EmscriptenKeyboardEvent *keyEvent, void *userData);
Parameters: |
|
---|---|
Returns: | true (non zero) to indicate that the event was consumed by the callback handler. |
Return type: |
Registers a callback function for receiving browser-generated keyboard input events.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: | |
See also: |
The event structure passed in mouse events: click, mousedown, mouseup, dblclick, mousemove, mouseenter and mouseleave.
A timestamp of when this data was generated by the browser. This is an absolute wallclock time in milliseconds.
Specifies which modifiers were active during the mouse event.
Identifies which pointer device button changed state (see MouseEvent.button):
- 0 : Left button
- 1 : Middle button (if present)
- 2 : Right button
A bitmask that indicates which combinations of mouse buttons were being held down at the time of the event.
If pointer lock is active, these two extra fields give relative mouse movement since the last event.
These fields give the mouse coordinates mapped relative to the coordinate space of the target DOM element receiving the input events (Emscripten-specific extension).
These fields give the mouse coordinates mapped to the Emscripten canvas client area (Emscripten-specific extension).
Internal, and can be ignored.
Note
Implementers only: pad this struct to multiple of 8 bytes to make WheelEvent unambiguously align to 8 bytes.
Function pointer for the mouse event callback functions, defined as:
typedef EM_BOOL (*em_mouse_callback_func)(int eventType, const EmscriptenMouseEvent *keyEvent, void *userData);
Parameters: |
|
---|---|
Returns: | true (non zero) to indicate that the event was consumed by the callback handler. |
Return type: |
Registers a callback function for receiving browser-generated mouse input events.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Returns the most recently received mouse event state.
Note that for this function call to succeed, emscripten_set_xxx_callback must have first been called with one of the mouse event types and a non-zero callback function pointer to enable the Mouse state capture.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Emscripten wheel event.
The event structure passed in mousewheel events.
Specifies general mouse information related to this event.
Movement of the wheel on each of the axis. Note that these values may be fractional, so you should avoid simply casting them to integer, or it might result in scroll values of 0. The positive Y scroll direction is when scrolling the page downwards (page CSS pixel +Y direction), which corresponds to scrolling the mouse wheel downwards (away from the screen) on Windows, Linux, and also on OSX when the ‘natural scroll’ option is disabled.
One of the DOM_DELTA_ values that indicates the units of measurement for the delta values.
Function pointer for the wheel event callback functions, defined as:
typedef EM_BOOL (*em_wheel_callback_func)(int eventType, const EmscriptenWheelEvent *keyEvent, void *userData);
Parameters: |
|
---|---|
Returns: | true (non zero) to indicate that the event was consumed by the callback handler. |
Return type: |
Registers a callback function for receiving browser-generated mousewheel events.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
The event structure passed in DOM element UIEvent events: resize and scroll.
Specifies additional detail/information about this event.
The clientWidth/clientHeight of the document.body element.
The outerWidth/outerHeight of the browser window.
Function pointer for the UI event callback functions, defined as:
typedef EM_BOOL (*em_ui_callback_func)(int eventType, const EmscriptenUiEvent *keyEvent, void *userData);
Parameters: |
|
---|---|
Returns: | true (non zero) to indicate that the event was consumed by the callback handler. |
Return type: |
Registers a callback function for receiving DOM element resize and scroll events.
Note
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Function pointer for the focus event callback functions, defined as:
typedef EM_BOOL (*em_focus_callback_func)(int eventType, const EmscriptenFocusEvent *keyEvent, void *userData);
Parameters: |
|
---|---|
Returns: | true (non zero) to indicate that the event was consumed by the callback handler. |
Return type: |
Registers a callback function for receiving DOM element blur, focus, focusin and focusout events.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
The event structure passed in the deviceorientation event.
Absolute wallclock time when the event occurred (in milliseconds).
The orientation of the device in terms of the transformation from a coordinate frame fixed on the Earth to a coordinate frame fixed in the device.
The image (source: dev.opera.com) and definitions below illustrate the co-ordinate frame:
Function pointer for the orientation event callback functions, defined as:
typedef EM_BOOL (*em_deviceorientation_callback_func)(int eventType, const EmscriptenDeviceOrientationEvent *keyEvent, void *userData);
Parameters: |
|
---|---|
Returns: | true (non zero) to indicate that the event was consumed by the callback handler. |
Return type: |
Registers a callback function for receiving the deviceorientation event.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Returns the most recently received deviceorientation event state.
Note that for this function call to succeed, emscripten_set_deviceorientation_callback() must have first been called with one of the mouse event types and a non-zero callback function pointer to enable the deviceorientation state capture.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Emscripten devicemotion event.
The event structure passed in the devicemotion event.
Absolute wallclock time when the event occurred (milliseconds).
Acceleration of the device excluding gravity.
Function pointer for the devicemotion event callback functions, defined as:
typedef EM_BOOL (*em_devicemotion_callback_func)(int eventType, const EmscriptenDeviceMotionEvent *keyEvent, void *userData);
Parameters: |
|
---|---|
Returns: | true (non zero) to indicate that the event was consumed by the callback handler. |
Return type: |
Registers a callback function for receiving the devicemotion event.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Returns the most recently received devicemotion event state.
Note that for this function call to succeed, emscripten_set_devicemotion_callback() must have first been called with one of the mouse event types and a non-zero callback function pointer to enable the devicemotion state capture.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Emscripten orientationchange event.
Primary portrait mode orientation.
Secondary portrait mode orientation.
Primary landscape mode orientation.
Secondary landscape mode orientation.
The event structure passed in the orientationchange event.
One of the EM_ORIENTATION_PORTRAIT_xxx fields, or -1 if unknown.
Emscripten-specific extension: Some browsers refer to window.orientation, so report that as well.
Orientation angle in degrees. 0: “default orientation”, i.e. default upright orientation to hold the mobile device in. Could be either landscape or portrait.
Function pointer for the orientationchange event callback functions, defined as:
typedef EM_BOOL (*em_orientationchange_callback_func)(int eventType, const EmscriptenOrientationChangeEvent *keyEvent, void *userData);
Parameters: |
|
---|---|
Returns: | true (non zero) to indicate that the event was consumed by the callback handler. |
Return type: |
Registers a callback function for receiving the orientationchange event.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Returns the current device orientation state.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Locks the screen orientation to the given set of allowed orientations.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Removes the orientation lock so the screen can turn to any orientation.
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
---|---|
Return type: | EMSCRIPTEN_RESULT |
Emscripten fullscreenchange event.
An enum-like type which specifies how the Emscripten runtime should treat the CSS size of the target element when displaying it in fullscreen mode via calls to functions emscripten_request_fullscreen_strategy() and emscripten_enter_soft_fullscreen().
Specifies that the DOM element should not be resized by Emscripten runtime when transitioning between fullscreen and windowed modes. The browser will be responsible for scaling the DOM element to the fullscreen size. The proper browser behavior in this mode is to stretch the element to fit the full display ignoring aspect ratio, but at the time of writing, browsers implement different behavior here. See the discussion at https://github.com/kripken/emscripten/issues/2556 for more information.
Specifies that the Emscripten runtime should explicitly stretch the CSS size of the target element to cover the whole screen when trasnsitioning to fullscreen mode. This will change the aspect ratio of the displayed content.
Specifies that the Emscripten runtime should explicitly scale the CSS size of the target element to cover the whole screen, while adding either vertical or horizontal black letterbox padding to preserve the aspect ratio of the content. The aspect ratio that is used here is the render target size of the canvas element. To change the desired aspect ratio, call emscripten_set_canvas_size() before entering fullscreen mode.
An enum-like type which specifies how the Emscripten runtime should treat the pixel size (render target resolution) of the target canvas element when displaying it in fullscreen mode via calls to functions emscripten_request_fullscreen_strategy() and emscripten_enter_soft_fullscreen(). To better understand the underlying distinction between the CSS size of a canvas element versus the render target size of a canvas element, see https://www.khronos.org/webgl/wiki/HandlingHighDPI.
Specifies that the Emscripten runtime should not do any changes to the render target resolution of the target canvas element that is displayed in fullscreen mode. Use this mode when your application is set up to render to a single fixed resolution that cannot be changed under any condition.
Specifies that the Emscripten runtime should resize the render target of the canvas element to match 1:1 with the CSS size of the element in fullscreen mode. On high DPI displays (window.devicePixelRatio > 1), the CSS size is not the same as the physical screen resolution of the device. Call emscripten_get_device_pixel_ratio() to obtain the pixel ratio between CSS pixels and actual device pixels of the screen. Use this mode when you want to render to a pixel resolution that is DPI-independent.
Specifies that the Emscripten runtime should resize the canvas render target size to match 1:1 with the physical screen resolution on the device. This corresponds to high definition displays on retina iOS and other mobile and desktop devices with high DPI. Use this mode to match and render 1:1 to the native display resolution.
An enum-like type that specifies what kind of image filtering algorithm to apply to the element when it is presented in fullscreen mode.
Specifies that the image filtering mode should not be changed from the existing setting in the CSS style.
Applies a CSS style to the element that displays the content using a nearest-neighbor image filtering algorithm in fullscreen mode.
Applies a CSS style to the element that displays the content using a bilinear image filtering algorithm in fullscreen mode. This is the default browser behavior.
The event structure passed in the fullscreenchange event.
Specifies if the current page has the ability to display elements fullscreen.
The nodeName of the target HTML Element that is in full screen mode.
Maximum size 128 char (i.e. EM_UTF8 nodeName[128]).
If isFullscreen is false, then nodeName, id and elementWidth and ElementHeight specify information about the element that just exited fullscreen mode.
The ID of the target HTML element that is in full screen mode.
Maximum size 128 char (i.e. EM_UTF8 id[128]).
The options structure that is passed in to functions emscripten_request_fullscreen_strategy() and emscripten_enter_soft_fullscreen() to configure how the target element should be displayed in fullscreen mode.
Specifies the rule how the CSS size (the displayed size) of the target element is resized when displayed in fullscreen mode.
Specifies how the render target size (the pixel resolution) of the target element is adjusted when displayed in fullscreen mode.
Specifies the image filtering algorithm to apply to the element in fullscreen mode.
If nonzero, points to a user-provided callback function which will be called whenever either the CSS or the canvas render target size changes. Use this callback to reliably obtain information about canvas resize events.
Stores a custom data field which will be passed to all calls to the user-provided callback function.
Function pointer for the fullscreen event callback functions, defined as:
typedef EM_BOOL (*em_fullscreenchange_callback_func)(int eventType, const EmscriptenFullscreenChangeEvent *keyEvent, void *userData);
Parameters: |
|
---|---|
Returns: | true (non zero) to indicate that the event was consumed by the callback handler. |
Return type: |
Registers a callback function for receiving the fullscreenchange event.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Returns the current page fullscreen state.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Requests the given target element to transition to full screen mode.
Note
This function can be called anywhere, but for web security reasons its associated request can only be raised inside the event handler for a user-generated event (for example a key, mouse or touch press/release). This has implications for porting and the value of deferUntilInEventHandler — see Functions affected by web security for more information.
Note
This function only performs a fullscreen request without changing any parameters of the DOM element that is to be displayed in fullscreen mode. At the time of writing, there are differences in how browsers present elements in fullscreen mode. For more information, read the discussion at https://github.com/kripken/emscripten/issues/2556. To display an element in fullscreen mode in a way that is consistent across browsers, prefer calling the function emscripten_request_fullscreen_strategy() instead. This function is best called only in scenarios where the preconfigured presets defined by emscripten_request_fullscreen_strategy() conflict with the developer’s use case in some way.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: | EMSCRIPTEN_RESULT |
Requests the given target element to transition to full screen mode, using a custom presentation mode for the element. This function is otherwise the same as emscripten_request_fullscreen(), but this function adds options to control how resizing and aspect ratio, and ensures that the behavior is consistent across browsers.
Note
This function makes changes to the DOM to satisfy consistent presentation across browsers. These changes have been designed to intrude as little as possible, and the changes are cleared once windowed browsing is restored. If any of these changes are conflicting, see the function emscripten_request_fullscreen() instead, which performs a bare fullscreen request without any modifications to the DOM.
Parameters: |
|
---|
Returns back to windowed browsing mode from a proper fullscreen mode.
Do not call this function to attempt to return to windowed browsing mode from a soft fullscreen mode, or vice versa.
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
---|---|
Return type: | EMSCRIPTEN_RESULT |
Enters a “soft” fullscreen mode, where the given target element is displayed in the whole client area of the page and all other elements are hidden, but does not actually request fullscreen mode for the browser. This function is useful in cases where the actual Fullscreen API is not desirable or needed, for example in packaged apps for Firefox OS, where applications essentially already cover the whole screen.
Pressing the esc button does not automatically exit the soft fullscreen mode. To return to windowed presentation mode, manually call the function emscripten_exit_soft_fullscreen().
Returns back to windowed browsing mode from a soft fullscreen mode. Do not call this function to attempt to return to windowed browsing mode from a real fullscreen mode, or vice versa.
Emscripten pointerlockchange events.
The event structure passed in the pointerlockchange event.
Specifies whether an element on the browser page currently has pointer lock enabled.
Function pointer for the pointerlockchange event callback functions, defined as:
typedef EM_BOOL (*em_pointerlockchange_callback_func)(int eventType, const EmscriptenPointerlockChangeEvent *keyEvent, void *userData);
Parameters: |
|
---|---|
Returns: | true (non zero) to indicate that the event was consumed by the callback handler. |
Return type: |
Registers a callback function for receiving the pointerlockchange event.
Pointer lock hides the mouse cursor and exclusively gives the target element relative mouse movement events via the mousemove event.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Returns the current page pointerlock state.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Requests the given target element to grab pointerlock.
Note
This function can be called anywhere, but for web security reasons its associated request can only be raised inside the event handler for a user-generated event (for example a key, mouse or touch press/release). This has implications for porting and the value of deferUntilInEventHandler — see Functions affected by web security for more information.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Exits pointer lock state and restores the mouse cursor to be visible again.
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
---|---|
Return type: | EMSCRIPTEN_RESULT |
Emscripten visibilitychange event.
The event structure passed in the visibilitychange event.
If true, the current browser page is now hidden.
Specifies a more fine-grained state of the current page visibility status. One of the EMSCRIPTEN_VISIBILITY_ values.
Function pointer for the visibilitychange event callback functions, defined as:
typedef EM_BOOL (*em_visibilitychange_callback_func)(int eventType, const EmscriptenVisibilityChangeEvent *keyEvent, void *userData);
Parameters: |
|
---|---|
Returns: | true (non zero) to indicate that the event was consumed by the callback handler. |
Return type: |
Registers a callback function for receiving the visibilitychange event.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Returns the current page visibility state.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Specifies the status of a single touch point on the page.
An identification number for each touch point.
The touch coordinate relative to the viewport, in pixels, and including any scroll offset.
Specifies whether this touch point is still above the original target on which it was initially pressed.
Specifies the data of a single touchevent.
The number of valid elements in the touches array.
Specifies which modifiers were active during the touch event.
An array of currently active touches, one for each finger.
Function pointer for the touch event callback functions, defined as:
typedef EM_BOOL (*em_touch_callback_func)(int eventType, const EmscriptenTouchEvent *keyEvent, void *userData);
Parameters: |
|
---|---|
Returns: | true (non zero) to indicate that the event was consumed by the callback handler. |
Return type: |
Registers a callback function for receiving touch events : touchstart, touchend, touchmove and touchcancel.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Represents the current snapshot state of a gamepad.
Absolute wallclock time when the data was recorded (milliseconds).
The number of valid axis entries in the axis array.
The number of valid button entries in the analogButton and digitalButton arrays.
The analog state of the gamepad axes, in the range [-1, 1].
The analog state of the gamepad buttons, in the range [0, 1].
The digital state of the gamepad buttons, either 0 or 1.
An ordinal associated with this gamepad, zero-based.
Function pointer for the gamepad event callback functions, defined as:
typedef EM_BOOL (*em_gamepad_callback_func)(int eventType, const EmscriptenGamepadEvent *keyEvent, void *userData)
Parameters: |
|
---|---|
Returns: | true (non zero) to indicate that the event was consumed by the callback handler. |
Return type: |
Registers a callback function for receiving the gamepad events: gamepadconnected and gamepaddisconnected.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Returns the number of gamepads connected to the system or EMSCRIPTEN_RESULT_NOT_SUPPORTED if the current browser does not support gamepads.
Note
A gamepad does not show up as connected until a button on it is pressed.
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
---|---|
Return type: | int |
Returns a snapshot of the current gamepad state.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Emscripten batterymanager events.
The event structure passed in the batterymanager events: chargingchange and levelchange.
Time remaining until the battery is fully charged (seconds).
Time remaining until the battery is empty and the system will be suspended (seconds).
Current battery level, on a scale of 0 to 1.0.
true if the battery is charging, false otherwise.
Function pointer for the batterymanager event callback functions, defined as:
typedef EM_BOOL (*em_battery_callback_func)(int eventType, const EmscriptenBatteryEvent *keyEvent, void *userData);
Parameters: |
|
---|---|
Returns: | true (non zero) to indicate that the event was consumed by the callback handler. |
Return type: |
Registers a callback function for receiving the batterymanager events: chargingchange and levelchange.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Returns the current battery status.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Produces a vibration for the specified time, in milliseconds.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Produces a complex vibration feedback pattern.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Emscripten beforeunload event.
Function pointer for the beforeunload event callback functions, defined as:
typedef const char *(*em_beforeunload_callback)(int eventType, const void *reserved, void *userData);
Parameters: |
|
---|---|
Returns: | Return a string to be displayed to the user. |
Return type: | char* |
Registers a callback function for receiving the page beforeunload event.
Hook into this event to perform actions immediately prior to page close (for example, to display a notification to ask if the user really wants to leave the page).
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Emscripten WebGL context events.
Represents a handle to an Emscripten WebGL context object. The value 0 denotes an invalid/no context (this is a typedef to an int).
Specifies WebGL context creation parameters.
If true, request an alpha channel for the context. If you create an alpha channel, you can blend the canvas rendering with the underlying web page contents. Default value: true.
If true, request a depth buffer of at least 16 bits. If false, no depth buffer will be initialized. Default value: true.
If true, request a stencil buffer of at least 8 bits. If false, no stencil buffer will be initialized. Default value: false.
If true, antialiasing will be initialized with a browser-specified algorithm and quality level. If false, antialiasing is disabled. Default value: true.
If true, the alpha channel of the rendering context will be treated as representing premultiplied alpha values. If false, the alpha channel represents non-premultiplied alpha. Default value: true.
If true, the contents of the drawing buffer are preserved between consecutive requestAnimationFrame() calls. If false, color, depth and stencil are cleared at the beginning of each requestAnimationFrame(). Generally setting this to false gives better performance. Default value: false.
If true, hints the browser to initialize a low-power GPU rendering context. If false, prefers to initialize a high-performance rendering context. Default value: false.
If true, requests context creation to abort if the browser is only able to create a context that does not give good hardware-accelerated performance. Default value: false.
Emscripten-specific extensions which specify the WebGL context version to initialize.
For example, pass in majorVersion=1, minorVersion=0 to request a WebGL 1.0 context, and majorVersion=2, minorVersion=0 to request a WebGL 2.0 context.
Default value: majorVersion=1, minorVersion=0
If true, all GLES2-compatible non-performance-impacting WebGL extensions will automatically be enabled for you after the context has been created. If false, no extensions are enabled by default, and you need to manually call emscripten_webgl_enable_extension() to enable each extension that you want to use. Default value: true.
Function pointer for the WebGL Context event callback functions, defined as:
typedef EM_BOOL (*em_webgl_context_callback)(int eventType, const void *reserved, void *userData);
Parameters: |
|
---|---|
Returns: | true (non zero) to indicate that the event was consumed by the callback handler. |
Return type: |
Registers a callback function for the canvas WebGL context events: webglcontextlost and webglcontextrestored.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Queries the given canvas element for whether its WebGL context is in a lost state.
Parameters: |
|
---|---|
Returns: | true if the WebGL context is in a lost state. |
Return type: |
Populates all fields of the given EmscriptenWebGLContextAttributes structure to their default values for use with WebGL 1.0.
Call this function as a forward-compatible way to ensure that if there are new fields added to the EmscriptenWebGLContextAttributes structure in the future, that they also will get default-initialized without having to change any code.
Parameters: |
|
---|
Creates and returns a new WebGL context.
Note
Parameters: |
|
---|---|
Returns: | On success, a strictly positive value that represents a handle to the created context. On failure, a negative number that can be cast to an EMSCRIPTEN_RESULT field to get the reason why the context creation failed. |
Return type: |
Activates the given WebGL context for rendering. After calling this function, all OpenGL functions (glBindBuffer(), glDrawArrays(), etc.) can be applied to the given GL context.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Returns the currently active WebGL rendering context, or 0 if no context is active. Calling any WebGL functions when there is no active rendering context is undefined and may throw a JavaScript exception.
Returns: | The currently active WebGL rendering context, or 0 if no context is active. |
---|---|
Return type: | EMSCRIPTEN_WEBGL_CONTEXT_HANDLE |
Deletes the given WebGL context. If that context was active, then the no context is set to active.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Enables the given extension on the given context.
Parameters: |
|
---|---|
Returns: | EM_TRUE if the given extension is supported by the context, and EM_FALSE if the extension was not available. |
Return type: |
Resizes the css width and height of the element specified by target on the Emscripten web page.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |
Gets the current css width and height of the element specified by target.
Parameters: |
|
---|---|
Returns: | EMSCRIPTEN_RESULT_SUCCESS, or one of the other result values. |
Return type: |