WEBGL_texture_source_iframe
WebGL working group (public_webgl 'at' khronos.org)
Zhenyao Mo, Google Inc
Members of the WebGL working group
Last modified date: July 10, 2023
Revision: 2
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.
[Exposed=(Window,Worker), LegacyNoInterfaceObject]
interface WEBGL_texture_source_iframe {
Promise<void> bindTextureSource(GLenum target, HTMLIFrameElement iframe);
Promise<void> requestFrame(GLenum target);
undefined setEventForwarding(function(Event));
};
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:
target must be TEXTURE_2D; otherwise an INVALID_ENUM
error is generated.target, an INVALID_OPERATION is
generated.iframe is not the same origin, an INVALID_OPERATION is
generated.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.
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.
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 1, 2017/09/20
Revision 2, 2023/07/10