WebGL WEBGL_texture_source_iframe Extension Proposed Specification





WebGL working group (public_webgl 'at' khronos.org)


Zhenyao Mo, Google Inc

Members of the WebGL working group


Last modified date: September 20, 2017
Revision: 1


WebGL extension #NN


Written against the WebGL API 1.0 specification.

Written against the WebGL API 2.0 specification.


This extension enables WebGL implementations to bind an HTMLIFrameElement object as the data source to a texture. While bound, the extension provides an API to allow applications to request the latest iframe rendering results to be blitted to the texture. The extension also provides an API to allow applications to transform and forward related user input events from WebGL canvas to the bound iframe, thus enabling the bound iframe to be interative inside a WebGL scene.

Due to security concerns, currently this extension only supports same origin iframes. This limitaion may be lifted in the future.


interface WEBGL_texture_source_iframe {
  Promise<void> bindTextureSource(GLenum target, HTMLIFrameElement iframe);
  Promise<void> requestFrame(GLenum target);
  void setEventForwarding(function(Event));

New Functions

Promise<void> bindTextureSource(GLenum target, HTMLIFrameElement iframe)

This function connects an iframe to the texture currently bound to target and returns a promise that will be fulfilled once the iframe is rendered and ready to be blitted to the texture. If the iframe is null, any existing binding between the texture and an iframe is broken. If there are any errors, generate the GL error synchronously and the returned promise is rejected with an InvalidStateError.

Once the function returns successfully, the texture is defined as following: its effective internal format becomes RGBA8; its width and height becomes iframe element's width and height.

Error cases are listed below:

Note this function returns a promise asynchronously because wiring an iframe rendering results to a WebGL texture could take multiple frames. The iframe could be invisible, therefore not part of the rendering pipeline and needs to be inserted into it. The iframe could also be in a seperate process from the one where WebGL is in, although this is likely not the case right now because we currently limit iframe to be same origin only.

Promise<void> requestFrame(GLenum target)

This function instructs implementations to update the texture with the latest iframe rendering results. The function returns a promise that will be fulfilled when the iframe rendering results from the same animation frame when this function is called has been blitted to the texture.

If an application uses requestAnimationFrame, implementations must guarantee once this function is called, the iframe rendering results from the same frame has been blitted to the texture when entering the next animation frame. Therefore, it is not necessary for an application to depend on the state of the returned promise. The promise is for applications that do not use requestAnimationFrame.

Once this function called, it is not recommended to read from the texture until the returns promise is fulfilled. The content of the texture during this period is undefined.

void setEventForwarding(Function func)

This function allows an application to define an event forwarding function that decides whether to forward user input events received on the WebGL canvas to the iframe. If yes, this function needs to transform event locations and displacements as needed. With this, an application can allow users to interact the iframe rendered inside the WebGL scene.

The event forwarding function takes an event as input, and output a bool. If returning true, the event is forwarded to the iframe and event data might have been modified to transform the event from WebGL canvas coordinates to iframe coordinates.

TODO(zmo@chromium.org): need some help how to define the forwarding function signature.

Revision History

Revision 1, 2017/09/20