WebGL
Khronos
 

WebGL WEBGL_dynamic_texture Extension Proposed Specification

DO NOT IMPLEMENT!!!

Name

WEBGL_dynamic_texture

Contact

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

Contributors

Mark Callow, HI Corporation

Acorn Pooley, while at NVIDIA

Ken Russell, Google

David Sheets, Ashima Arts

William Hennebois, STMicroelectronics

Members of the WebGL working group

Version

Last modified date: July 15, 2014
Revision: 7

Number

WebGL extension #NN

Dependencies

Written against the WebGL API 1.0.2 specification.

Overview

A dynamic texture is a texture whose image changes frequently. The source of the stream of images may be a producer outside the control of the WebGL application. The classic example is using a playing video to texture geometry. Texturing with video is currently achieved by using the TEXTURE2D target and passing an HTMLVideoElement to texImage2D. It is difficult, if not impossible to implement video texturing with zero-copy efficiency via this API and much of the behavior is underspecified.

This extension provides a mechanism for streaming image frames from an HTMLVideoElement, HTMLCanvasElement or HTMLImageElement (having multiple frames such those created from animated GIF, APNG and MNG files) into a WebGL texture. This is done via a new texture target, TEXTURE_EXTERNAL_OES which can only be specified as being the consumer of an image stream from a new WDTStream object which provides commands for connecting to a producer element.

There is no support for most of the functions that manipulate other texture targets (e.g. you cannot use *[Tt]ex*Image*() functions with TEXTURE_EXTERNAL_OES). Also, TEXTURE_EXTERNAL_OES targets never have more than a single level of detail. These restrictions enable dynamic texturing with maximum efficiency. They remove the need for a copy of the image data manipulable via the WebGL API and allow sources which have internal formats not otherwise supported by WebGL, such as planar or interleaved YUV data, to be WebGL texture target siblings.

The extension extends GLSL ES with a new samplerExternalOES type and matching sampling functions that provide a place for an implementation to inject code for sampling non-RGB data when necessary without degrading performance for other texture targets. Sampling a TEXTURE_EXTERNAL_OES via a sampler of type samplerExternalOES always returns RGBA data. This allows the implementation to decide the most efficient format to use whether it be RGB or YUV data. If the underlying format was exposed, the application would have to query the format in use and provide shaders to handle both cases.

WDTStream provides a command for latching an image frame into the consuming texture as its contents. This is equivalent to copying the image into the texture but, due to the restrictions outlined above a copy is not necessary. Most implementations will be able to avoid one so this can be much faster than using texImage2D. Latching can and should be implemented in a way that allows the producer to run independently of 3D rendering.

Terminology note: throughout this specification opaque black refers to the RGBA value (0,0,0,1).

This extension exposes the NV_EGL_stream_consumer_external functionality to WebGL.

The following WebGL-specific behavioral changes apply:

For ease of reading, this specification briefly describes the new functions and enumerants of NV_EGL_stream_consumer_external. Consult that extension for detailed documentation of their meaning and behavior. Changes to the language of that extension are given later in this specification.

When this extension is enabled:

IDL

[NoInterfaceObject]
interface WEBGL_dynamic_texture {
  typedef double WDTNanoTime;

  const GLenum TEXTURE_EXTERNAL_OES = 0x8D65;
  const GLenum SAMPLER_EXTERNAL_OES = 0x8D66;
  const GLenum TEXTURE_BINDING_EXTERNAL_OES = 0x8D67;
  const GLenum REQUIRED_TEXTURE_IMAGE_UNITS_OES = 0x8D68;

  WDTStream? createStream();
 
  WDTNanoTime getLastDrawingBufferPresentTime();
  void setDrawingBufferPresentTime(WDTNanoTime pt);
  WDTNanoTime ustnow();
}; // interface WEBGL_dynamic_texture

IP Status

No known IP claims.

New Functions

On WEBGL_dynamic_texture:

WDTStream createStream()
Creates and returns a WDTStream object whose consumer is the WebGLTexture bound to the TEXTURE_EXTERNAL_OES target of the active texture unit at the time of the call.
WDTNanoTime getMinFrameDuration()
Returns the duration of the shortest frame of the currently connected dynamic source when playbackRate of the associated MediaController is 1.0.
WDTNanoTime getLastDBPresentTime()
Returns the UST the last time the DrawingBuffer was presented to the screen, i.e., after the last return of the script to the browser.
void setDBPresentationTime(WDTNanoTime presentTime)
Sets the UST at which the drawing buffer should be presented after the script returns to the browser.
WDTNanoTime ustnow()
Returns the current UST.

On WDTStream:

void WDTStream.connectSource(StreamSource source)
Connects the StreamSource specified by source as the producer for the stream. StreamSource can be an HTMLCanvasElement, HTMLImageElement or HTMLVideoElement.
StreamSource? WDTStream.getSource()
Returns the HTML{Canvas,Image,Video}Element that is connected to the WDTStream as the producer of images.
WDTStreamFrameInfo WDTStream.acquireImage()
Latches an image frame. Sampling the WebGLTexture, that is the WDTStream's consumer, will return values from the latched image. The image data is guaranteed not to change as long as the image is latched. WDTStream returns true when an image is successfully latched, false otherwise.
void WDTStream.releaseImage()
Releases the latched image. Subsequent samping of the WebGLTexture, that was bound to the TEXTURE_EXTERNAL_OES target of the active texture unit when the WDTStream was created, will return opaque black.

New Types

XXX Need to get the XSL fixed for interfaces ...

typedef double WDTNanoTime

This type is used for nanosecond time stamps and time periods.

typedef [NoInterfaceObject] interface WDTStreamFrameInfo { double frameTime; WDTNanoTime presentTime }

This type is used to provide information about the latched frame.

typedef [NoInterfaceObject] interface WDTStream { ... }

This type is used to manage the image stream between the producer and consumer.

New Tokens

The meaning and use of these tokens is exactly as described in NV_EGL_stream_consumer_external.

void bindTexture(GLenum target, WebGLTexture? texture)
TEXTURE_EXTERNAL_OES is accepted as a target by the target parameter of bindTexture()
WebGLActiveInfo? getActiveUniform(WebGLProgram? program, GLuint index)
SAMPLER_EXTERNAL_OES can be returned in the type field of the WebGLActiveInfo returned by getActiveUniform()
any getParameter(GLenum pname)
TEXTURE_BINDING_EXTERNAL_OES is accepted by the pname parameter of getParameter().
any getTexParameter*(GLenum target, GLenum pname)
REQUIRED_TEXTURE_IMAGE_UNITS_OES is accepted as the pname parameter of GetTexParameter*()

Additions to the WebGL Specification

In section 4.3 Supported GLSL Constructs, replace the paragraph beginning A WebGL implementation must ... with the following paragraph:

A WebGL implementation must only accept shaders which conform to The OpenGL ES Shading Language, Version 1.00 [GLES20GLSL], as extended by NV_EGL_stream_consumer_external, and which do not exceed the minimum functionality mandated in Sections 4 and 5 of Appendix A. In particular, a shader referencing state variables or commands that are available in other versions of GLSL (such as that found in versions of OpenGL for the desktop), must not be allowed to load.

In section 5.14 The WebGL Context , add the following to the WebGLRenderingContext interface. Note that until such time as this extension enters core WebGL the tokens and commands mentioned below will be located on the WebGL_dynamic_texture extension interface shown above.

  • In the list following /* GetPName */:
    TEXTURE_BINDING_EXTERNAL = 0x8D67;
  • In the list following /* TextureParameterName */:
    REQUIRED_TEXTURE_IMAGE_UNITS = 0x8D68;
  • In the list following /* TextureTarget */:
    TEXTURE_EXTERNAL = 0x8D65;
  • In the list following /* Uniform Types */:
    SAMPLER_EXTERNAL = 0x8D66;
  • In the alphabetical list of commands add the following :
    WDTStream? createStream(); 
    WDTNanoTime getLastDrawingBufferPresentTime();
    void setDrawingBufferPresentationTime(WDTNanoTime pt);
    WDTNanoTime ustnow();
  • In section 5.14.3 Setting and getting state, add the following to the table under getParameter.

    TEXTURE_BINDING_EXTERNAL int

    In section 5.14.8Texture objects, add the following to the table under getTexParameter.

    REQUIRED_TEXTURE_IMAGE_UNITS int

    Add a new section 5.14.8.1 External textures.

    5.14.8.1 External textures

    External textures are texture objects which receive image data from outside of the GL. They enable texturing with rapidly changing image data, e.g, a video, at low overhead and are used in conjunction with WDTStream objects to create dynamic textures. See Dynamic Textures for more information. An external texture object is created by binding an unused WebGLTexture to the target TEXTURE_EXTERNAL_OES. Note that only unused WebGLTextures or those previously used as external textures can be bound to TEXTURE_EXTERNAL_OES. Binding a WebGLTexture previously used with a different target or binding a WebGLTexture previously used with TEXTURE_EXTERNAL_OES to a different target generates a GL_INVALID_OPERATION error as documented in GL_NV_EGL_stream_consumer_external.txt.

    In section 5.14.10 Uniforms and attributes, add the following to the table under getUniform.

    samplerExternal long

    Add a new section 5.16 Dynamic Textures

    5.16 Dynamic Textures

    Dynamic textures are texture objects that display a stream of images coming from a producer outside the WebGL application, the classic example ibeing using a playing video to texture geometry from. A WDTStream object mediates between the producer and the consumer, the texture consuming the images.

    The command

    WDTStream? createStream();
    creates a WGTStream object whose consumer is the texture object currently bound to the TEXTURE_EXTERNAL_OES target in the active texture unit. The initial state of the newly created stream will be STREAM_CONNECTING. If the texture object is already the consumer of a stream, createStream generates an INVALID_OPERATION error and returns null. When a texture object that is the consumer of a stream is deleted, the stream is also deleted.

    In order to maintain synchronization with other tracks of an HTMLVideoElement's media group, most notably audio, the application must be able to measure how long it takes to draw the scene containing the dynamic texture and how long it takes the browser to compose and present the canvas.

    The command

    WDTNanoTime ustnow();
    returns the unadjusted system time, a monotonically increasing clock, in units of nanoseconds. The zero time of this clock is not important. It could start at system boot, browser start or navigation start.

    The command

    WDTNanoTime getLastDrawingBufferPresentTime();
    returns the UST the last time the composited page containing the drawing buffer's content was presented to the user.

    To ensure accurate synchronization of the textured image with other tracks of an HTMLVideoElement's media group, the application must be able to specify the presentation time of the drawing buffer.

    The command

    void setDrawingBufferPresentTime(WDTNanoTime pt);
    tells the browser the UST when the drawing buffer must be presented after the application returns to the browser. The browser must present the composited page containing the canvas to the user at the specified UST. If the specified time has already passed when control returns, the browser should present the drawing buffer as soon as possible. Should an explicit drawing buffer present function be added to WebGL, the presentation time will become one of its parameters.

    5.16.1 WDTStreamFrameInfo

    The WDTStreamFrameInfo interface represents information about a frame acquired from a WDTStream.

    [NoInterfaceObject] interface WDTStreamFrameInfo {
      readonly attribute double frameTime;
      readonly attribute WDTNanoTime presentTime;
    };

    5.16.1.1 Attributes

    The following attributes are available:

    frameTime of type double
    The time of the frame relative to the start of the producer's MediaController timeline in seconds. Equivalent to currentTime in an HTMLMediaElement.
    presentTime of type WDTNanoTime
    The time the frame must be presented in order to sync with other tracks in the element's mediagroup, particularly audio.

    5.16.2 WDTStream

    The WDTStream interface represents a stream object used for controlling an image stream being fed to a dynamic texture object.

    [NoInterfaceObject] interface WDTStream {
      typedef (HTMLCanvasElement or
               HTMLImageElement or
               HTMLVideoElement) StreamSource;
    
      const GLenum STREAM_CONNECTING = 0;
      const GLenum STREAM_EMPTY = 1;
      const GLenum STREAM_NEW_FRAME_AVAILABLE = 2;
      const GLenum STREAM_OLD_FRAME_AVAILABLE = 3;
      const GLenum STREAM_DISCONNECTED = 4;
    
      readonly attribute WebGLTexture consumer;
    
      readonly attribute WDTStreamFrameInfo consumerFrame;
      readonly attribute WDTStreamFrameInfo producerFrame;
    
      readonly attribute WDTNanoTime minFrameDuration;
    
      readonly attribute GLenum state;  
    
      attribute WDTNanotime acquireTimeout;
      attribute WDTNanoTime consumerLatency;
    
      void connectSource(StreamSource source);
      void disconnect();
      StreamSource? getSource();
    
      boolean acquireImage();
      void releaseImage();
    };

    5.16.2.1 Attributes

    consumer of type WebGLTexture
    The WebGLTexture that was bound to the TEXTURE_EXTERNAL_OES target of the active texture unit at the time the stream was created. Sampling this texture in a shader will return samples from the image latched by acquireImage.
    consumerFrame of type WDTStreamFrameInfo
    Information about the last frame latched by the consumer via acquireImage.
    producerFrame of type WDTStreamFrameInfo
    Information about the frame most recently inserted into the stream by the producer.
    minFrameDuration of type WDTNanoTime
    The minimum duration of a frame in the producer. Ideally this should be an attribute on HTMLVideoElement. Most video container formats have metadata that can be used to calculate this. It can only reflect the actual value once the stream is connected to a producer and the producer's READY_STATE is at least HAVE_METADATA. The initial value is Number.MAX_VALUE (i.e., infinity). Applications need this information to determine how complex their drawing can be while maintaining the video's frame rate.
    state of type GLenum
    The state of the stream. Possible states are STREAM_CONNECTING, STREAM_EMPTY, STREAM_NEW_FRAME_AVAILABLE, STREAM_OLD_FRAME_AVAILABLE and STREAM_DISCONNECTED.
    consumerLatency of type WDTNanoTime
    The time between the application latching an image from the stream and the drawing buffer being presented. This is the time by which the producer should delay playback of any synchronized tracks such as audio. The initial value is an implementation-dependent constant value, possibly zero. This should only be changed when the video is paused as producers will not be able to change the playback delay on, e.g. audio, without glitches. It may only be possible to set this prior to starting playback. Implementation experience is needed.
    acquireTimeout of type WDTNanoTime
    The maximum time to block in acquireImage waiting for a new frame. The initial value is 0.

    5.16.2.2 commands

    The command

    void connectSource(StreamSource source);
    connects the stream to the specified StreamSource element. If StreamSource is an HTMLMediaElement, the element's autoPlay attribute is set to false to prevent playback starting before the application is ready. If state is not STREAM_CONNECTING, an InvalidStateError exception is thrown. After connecting state becomes STREAM_EMPTY.

    The command

    void disconnect();
    disconnects the stream from its source. Subsequent sampling of the associated texture will return opaque black. state is set to STREAM_DISCONNECTED.

    The command

    StreamSource? getSource();
    returns the HTML element that is the producer for this stream.

    The command

    boolean acquireImage();
    causes consumer to latch the most recent image frame from the currently connected source. The rules for selecting the image to be latched mirror those for selecting the image drawn by the drawImage method of CanvasRenderingContext2D.

    For HTMLVideoElements, it latches the frame of video that will correspond to the current playback position of the audio channel, as defined in the HTML Living Standard, at least latency nanoseconds from the call returning, where latency is the consumerLatency attribute of the stream. If the element's readyState attribute is either HAVE_NOTHING or HAVE_METADATA, the command returns without latching anything and the texture remains incomplete. The effective size of the texture will be the element's intrinsic width and height.

    For animated HTMLImageElements it will latch the first frame of the animation. The effective size of the texture will be the element's intrinsic width and height.

    For HTMLCanvasElements it will latch the current content of the canvas as would be returned by a call to toDataURL.

    acquireImage will block until either the timeout specified by acquireTimeout expires or state is neither STREAM_EMPTY nor STREAM_OLD_FRAME_AVAILABLE, whichever comes first.

    The model is a stream of images between the producer and the WebGLTexture consumer. acquireImage latches the most recent image. If the producer has not inserted any new images since the last call to acquireImage then acquireImage will latch the same image it latched last time it was called. If the producer has inserted one new image since the last call then acquireImage will "latch" the newly inserted image. If the producer has inserted more than one new image since the last call then all but the most recently inserted image are discarded and acquireImage will "latch" the most recently inserted image. For HTMLVideoElements, the application can use the value of the frameTime attribute in the consumerFrame attribute to identify which image frame was actually latched.

    acquireImage returns true if an image has been acquired, and false if the timeout fired. It throws the following exceptions:

    XXX Complete after resolving issue 22. XXX

    The command

    void releaseImage();
    releases the latched image. releaseImage will prevent the producer from re-using and/or modifying the image until all preceding WebGL commands that use the image as a texture have completed. If acquireImage is called twice without an intervening call to releaseImage then releaseImage is implicitly called at the start of acquireImage.

    After successfully calling releaseImage the texture becomes "incomplete".

    If releaseImage is called twice without a successful intervening call to acquireImage, or called with no previous call to acquireImage, then the call does nothing and the texture remains in "incomplete" state. This is not an error

    It throws the following exceptions:

    XXX Complete after resolving issue 22. XXX

    To sample a dynamic texture, the texture object must be bound to the target TEXTURE_EXTERNAL_OES and the sampler uniform must be of type samplerExternal. If the texture object bound to TEXTURE_EXTERNAL_OES is not bound to a dynamic source then the texture is "incomplete" and the sampler will return opaque black.

    At the end of section 6 Differences between WebGL and OpenGL ES, add the following new sections. Note that differences are considered with respect to the OpenGL ES 2.0 specification as extended by NV_EGL_stream_consumer_external in the absence of OES_EGL_image_external.

    6.25 External Texture Support

    WebGL supports external textures but provides its own WDTStream interface instead of EGLStream. WDTStream connects an HTMLCanvasElement, HTMLImageElement or HTMLVideoElement as the producer for an external texture. Specific language changes follow.

    Section 3.7.14.1 External Textures as Stream Consumers is replaced with the following.

    To use a TEXTURE_EXTERNAL_OES texture as the consumer of images from a dynamic HTML element, bind the texture to the active texture unit, and call createStream to create a WDTStream. Use the stream's connectSource command to connect the stream to the desired producer HTML element. The width, height, format, type, internalformat, border and image data of the TEXTURE_EXTERNAL_OES texture will all be determined based on the specified dynamic HTML element. If the element does not have any source or the source is not yet loaded, the width, height & border will be zero, the format and internal format will be undefined. Once the element's source has been loaded and one (or more) images have been decoded these attributes are determined (internally by the implementation), but they are not exposed to the WebGL application and there is no way to query their values.

    The TEXTURE_EXTERNAL_OES texture remains the consumer of the dynamic HTML element's image frames until the first of any of these events occur:

    1. The texture is associated with a different dynamic HTML element (with a later call to WDTStream.connectSource).
    2. The texture is deleted in a call to deleteTextures.

    Sampling an external texture which is not connected to a dynamic HTML element will return opaque black. Sampling an external texture which is connected to a dynamic HTML element will return opaque black unless an image frame has been 'latched' into the texture by a successful call to WDTStream.acquireImage.

    Errors

    New State

    New Implementation-Dependent State

    Sample Code

    XXX IGNORE THIS SAMPLE CODE. IT HAS NOT YET BEEN UPDATED TO MATCH THE NEW SPEC TEXT. XXX

    This a fragment shader that samples a video texture. Note that the surrounding <script> tag is not essential; it is merely one way to include shader text in an HTML file.
    <script id="fshader" type="x-shader/x-fragment">
      #extension OES_EGL_image_external : enable 
      precision mediump float;
    
      uniform samplerExternalOES videoSampler;
    
      varying float v_Dot;
      varying vec2 v_texCoord;
    
      void main()
      {
        vec2 texCoord = vec2(v_texCoord.s, 1.0 - v_texCoord.t);
        vec4 color = texture2D(videoSampler, texCoord);
        color += vec4(0.1, 0.1, 0.1, 1);
        gl_FragColor = vec4(color.xyz * v_Dot, color.a);
      }
    </script>
    This shows fragments from an application that renders a spinning cube textured with a live video.
    <html>
    <script type="text/javascript">
    
      ///////////////////////////////////////////////////////////////////////
      // Create a video texture and bind a source to it.
      ///////////////////////////////////////////////////////////////////////
    
      // Array of files currently loading
      g_loadingFiles = [];
    
      // Clears all the files currently loading.
      // This is used to handle context lost events.
      function clearLoadingFiles() {
        for (var ii = 0; ii < g_loadingFiles.length; ++ii) {
          g_loadingFiles[ii].onload = undefined;
        }
        g_loadingFiles = [];
      }
    
      //
      // createVideoTexture
      //
      // Load video from the passed HTMLVideoElement id, bind it to a new WebGLTexture object
      // and return the WebGLTexture.
      //
      // Is there a constructor for an HTMLVideoElement so you can do like "new Image()?"
      //
      function createVideoTexture(ctx, videoId)
      {
        var texture = ctx.createTexture();
        var video = document.getElementById(videoId);
        g_loadingFiles.push(video);
        video.onload = function() { doBindVideo(ctx, video, texture) }
        return texture;
      }
    
      function doBindVideo(ctx, video, texture)
      {
        g_loadingFiles.splice(g_loadingFiles.indexOf(image), 1);
        ctx.bindTexture(ctx.TEXTURE_EXTERNAL_OES, texture);
        ctx.dynamicTextureSetSource(video);
        // These are the default values of these properties so the following
        // 4 lines are not necessary.
        ctx.texParameteri(ctx.TEXTURE_EXTERNAL_OES, ctx.TEXTURE_MAG_FILTER, ctx.LINEAR);
        ctx.texParameteri(ctx.TEXTURE_EXTERNAL_OES, ctx.TEXTURE_MIN_FILTER, ctx.LINEAR);
        ctx.texParameteri(ctx.TEXTURE_EXTERNAL_OES, ctx.TEXTURE_WRAP_S, ctx.CLAMP_TO_EDGE);
        ctx.texParameteri(ctx.TEXTURE_EXTERNAL_OES, ctx.TEXTURE_WRAP_T, ctx.CLAMP_TO_EDGE);
        ctx.bindTexture(ctx.TEXTURE_EXTERNAL_OES, null);
      }
    
      ///////////////////////////////////////////////////////////////////////
      // Initialize the application.
      ///////////////////////////////////////////////////////////////////////
    
      var g = {};
      var videoTexture;
    
      function init()
      {
        // Initialize
        var gl = initWebGL(
            // The id of the Canvas Element
            "example");
        if (!gl) {
          return;
        }
        var program = simpleSetup(
            gl,
            // The ids of the vertex and fragment shaders
            "vshader", "fshader",
            // The vertex attribute names used by the shaders.
            // The order they appear here corresponds to their index
            // used later.
            [ "vNormal", "vColor", "vPosition"],
            // The clear color and depth values
            [ 0, 0, 0.5, 1 ], 10000);
    
        // Set some uniform variables for the shaders
        gl.uniform3f(gl.getUniformLocation(program, "lightDir"), 0, 0, 1);
        // Use the default texture unit 0 for the video
        gl.uniform1i(gl.getUniformLocation(program, "samplerExternal"), 0);
    
        // Create a box. On return 'gl' contains a 'box' property with
        // the BufferObjects containing the arrays for vertices,
        // normals, texture coords, and indices.
        g.box = makeBox(gl);
    
        // Load an image to use. Returns a WebGLTexture object
        videoTexture = createVideoTexture(gl, "video");
        // Bind the video texture
        gl.bindTexture(gl.TEXTURE_EXTERNAL_OES, videoTexture);
    
        // Create some matrices to use later and save their locations in the shaders
        g.mvMatrix = new J3DIMatrix4();
        g.u_normalMatrixLoc = gl.getUniformLocation(program, "u_normalMatrix");
        g.normalMatrix = new J3DIMatrix4();
        g.u_modelViewProjMatrixLoc =
                gl.getUniformLocation(program, "u_modelViewProjMatrix");
        g.mvpMatrix = new J3DIMatrix4();
    
        // Enable all of the vertex attribute arrays.
        gl.enableVertexAttribArray(0);
        gl.enableVertexAttribArray(1);
        gl.enableVertexAttribArray(2);
    
        // Set up all the vertex attributes for vertices, normals and texCoords
        gl.bindBuffer(gl.ARRAY_BUFFER, g.box.vertexObject);
        gl.vertexAttribPointer(2, 3, gl.FLOAT, false, 0, 0);
    
        gl.bindBuffer(gl.ARRAY_BUFFER, g.box.normalObject);
        gl.vertexAttribPointer(0, 3, gl.FLOAT, false, 0, 0);
    
        gl.bindBuffer(gl.ARRAY_BUFFER, g.box.texCoordObject);
        gl.vertexAttribPointer(1, 2, gl.FLOAT, false, 0, 0);
    
        // Bind the index array
        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, g.box.indexObject);
    
        return gl;
      }
    
      // ...
    
      ///////////////////////////////////////////////////////////////////////
      // Draw a frame
      ///////////////////////////////////////////////////////////////////////
      function draw(gl)
      {
        // Make sure the canvas is sized correctly.
        reshape(gl);
    
        // Clear the canvas
        gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
    
        // Make a model/view matrix.
        g.mvMatrix.makeIdentity();
        g.mvMatrix.rotate(20, 1,0,0);
        g.mvMatrix.rotate(currentAngle, 0,1,0);
    
        // Construct the normal matrix from the model-view matrix and pass it in
        g.normalMatrix.load(g.mvMatrix);
        g.normalMatrix.invert();
        g.normalMatrix.transpose();
        g.normalMatrix.setUniform(gl, g.u_normalMatrixLoc, false);
    
        // Construct the model-view * projection matrix and pass it in
        g.mvpMatrix.load(g.perspectiveMatrix);
        g.mvpMatrix.multiply(g.mvMatrix);
        g.mvpMatrix.setUniform(gl, g.u_modelViewProjMatrixLoc, false);
    
        // Acquire the latest video image
        gl.dynamicTextureAcquireImage();
    
        // Draw the cube
        gl.drawElements(gl.TRIANGLES, g.box.numIndices, gl.UNSIGNED_BYTE, 0);
    
        // Allow updates to the image again
        gl.dynamicTextureReleaseImage();
    
        // Show the framerate
        framerate.snapshot();
    
        currentAngle += incAngle;
        if (currentAngle > 360)
          currentAngle -= 360;
      }
    </script>
    
    <body onload="start()">
    <video id="video" src="resources/video.ogv" autoplay="true" style="visibility: hidden">
    </video>
    <canvas id="example">
        If you're seeing this your web browser doesn't support the &lt;canvas&gt; element. Ouch!
    </canvas>
    <div id="framerate"></div>
    </body>
    
    </html>

    Conformance Tests

    Security Considerations

    Statistical fingerprinting is a privacy concern where a malicious web site may determine whether a user has visited a third-party web site by measuring the timing of cache hits and misses of resources in the third-party web site. Though the ustnow method of this extension returns time data to a greater accuracy than before, it does not make this privacy concern significantly worse than it was already.

    Issues

    1. What do applications need to be able to determine about the source?

      RESOLVED. Two things

    2. Neither the minimum inter-frame interval nor frame rate is exposed by HTMLMediaElements. How can it be determined?

      RESOLVED. Although there have been requests to expose the frame rate, in connection with non-linear editing and frame accurate seeks to SMPTE time-code positions, there has been no resolution. Therefore the stream object interface will have to provide a query for the minimum inter-frame interval. It can easily be derived from the frame-rate of fixed-rate videos or from information that is commonly stored in the container metadata for variable-rate formats. For example the Matroska and WebM containers provide a FrameRate item, albeit listed as "information only." Note that there is a tracking bug for this feature at WHATWG/W3C where browser vendors can express interest in implementing it.

    3. How can the application determine whether it has missed a frame?

      RESOLVED. If a frame's presentTime is earlier than ustnow() + consumerLatency then the application will have to drop the frame and acquire the next one.

    4. Why not use the TEXTURE2D target and texImage2D?

      RESOLVED. Use a new texture target and new commands. A new texture target makes it easy to specify, implement and conformance test the restrictions that enable a zero-copy implementation of dynamic textures as described in the Overview. Given that one of those restriction is not allowing modification of the texture data, which is normally done via texImage2D using a new command will make the usage model clearer.

    5. Why not use sampler2D uniforms?

      RESOLVED. Use a new sampler type. Many zero-copy implementations will need special shader code when sampling YUV format dynamic textures. Implementations may choose to (a) re-compile at run time or (b) inject conditional code which branches at run time according to the format of the texture bound to TEXTURE_EXTERNAL_OES in the texture unit to which the sampler variable is set. Without a new sampler type, such conditional code would have to be injected for every sampler fetch increasing the size of the shader and slowing sampling of other texture targets. In order to preserve the possibility of using approach (b), a new sampler type will be used.

    6. Should the API be implemented as methods on the texture object or as commands taking a texture object as a parameter?

      RESOLVED. Neither. The WebGLTexture object represents an OpenGL texture name. No object is created until the name is bound to a texture target. Therefore the new commands should operate on a the currently bound texture object.

    7. Should dynamic textures be a new texture type or can WebGLTexture be reused?

      RESOLVED. WebGLTexture can be reused. As noted in the previous issue a WebGLTexture represents a texture name and is a handle to multiple texture types. The type of texture is set according to the target to which the name is initially bound.

    8. Should this extension use direct texture access commands or should it use texParameter and getTexParameter?

      RESOLVED. Use the latter. There is no directly accessible texture object to which such commands can be added. Changing the API to have such objects is outside the scope of this extension.

    9. Should we re-use #extension NV_EGL_stream_consumer_external, create our own GLSL extension name or have both this and a WebGL-specific name?

      RESOLVED. Any of WEBGL_dynamic_texture or the aliases GL_NV_EGL_stream_consumer_external or GL_OES_EGL_image_external can be used to enable this extension's features in the shader. This permits the same shader to be used with both WebGL and OpenGL ES 2.0.

    10. What should happen when an object of type HTMLCanvasElement, HTMLImageElement or HTMLVideoElementis passed to the existing tex*Image2D commands?

      UNRESOLVED. This behavior is outside the scope of this extension but handling of these objects is very underspecified in the WebGL specification and needs to be clarified. Suggestion: for single-frame HTMLImageElement set the texture image to the HTMLImageElement; for an animated HTMLImageElement set the texture image to the first frame of the animation; for an HTMLCanvasElement, set the texture image to the current canvas image that would be returned by toDataURL; for an HTMLVideoElement, set the texture image to the current frame. In all cases, the texture image does not change until a subsequent call to a tex*Image2D command. Is this a change from the way any of these elements are handled today?

    11. Should acquireImage and releaseImage generate errors if called when the stream is already in the state to be set or ignore those extra calls?

      RESOLVED. They should not generate errors. acquireImage will be defined to implicitly call releaseImage if there has not been an intervening call.

    12. This API is implementable on any platform at varying levels of efficiency. Should it therefore move directly to core rather than being an extension?

      RESOLVED. No, unless doing so would result in implementations appearing sooner.

    13. Should this extension support HTMLImageElement?

      UNRESOLVED. The HTML 5 Living Standard provides virtually no rules for handling of animated HTMLImageElements and specifically no definition of a current frame. In order to texture the animations from such elements, this specification will need to provide rules. If we are tracking the behavior of CanvasRenderingContext2D.drawImage then there is no point supporting HTMLImageElement as the specification says to draw the first frame of animated HTMLImageElements.

    14. Should this extension extend HTMLMediaElement with an acquireImage/releaseImage API?

      RESOLVED. No. The API would have no purpose and would require HTML{Video,Canvas,Image}Element becoming aware of WebGLTexture or, even worse, aware of texture binding within WebGL. No similar API was exposed to support CanvasRenderingContext2D.drawImage. The HTMLElement is simply passed to drawImage.

    15. Should DOMHighResolutionTime and window.performance.now() from the W3C High-Resolution Time draft be used for the timestamps and as UST?

      RESOLVED. No. The specified unit is milliseconds and, although the preferred accuracy is microseconds, the required accuracy is only milliseconds. At millisecond accuracy it is not possible to distinguish between 29.97 fps and 30 fps which means sound for a 29.97 fps video will be ~3.5 seconds out of sync after 1 hour. Also fractional double values must be used to represent times < 1 ms with the attendant issues of variable time steps as the exponent changes. Feedback has been provided. Hopefully the draft specification will be updated.

    16. Should UST 0 be system start-up, browser start-up or navigationStart as defined in the W3C Navigation Timing proposed recommendation?

      RESOLVED. If DOMHighResolutionTime is used, then navigationStart makes sense otherwise it can be left to the implementation.

    17. Should UST wrap rather then increment the exponent, so as to maintain precision?

      UNRESOLVED. The exponent will need to be incremented after 2**53 nanoseconds (~ 41 days). UST could wrap to 0 after that or just keep counting. If it keeps counting, the precision will be halved so each tick will be 2 nanoseconds. The next precision change will occur after a further ~82 days.

    18. Should WDTStream.state be a proper idl enum?

      UNRESOLVED.

    19. Does the application need to be able to find out if it has missed a potential renderAnimationFrame callback, i.e, it has taken longer than the browser's natural rAF period? If so, how?

      UNRESOLVED.

    20. What are the base and units of a renderbuffer's present time on iOS?

      UNRESOLVED.

    21. CanvasRenderingContext2D.drawImage requires an InvalidStateError be thrown if either width or height of the source canvas is 0? Do we need to do mirror this?

      RESOLVED. Treating this situation as failing to acquire an image and so returning opaque black when sampled provides more consistent handling across StreamSource types and is more consistent with OpenGL ES.

    22. Should exceptions be used for errors on WDTStreams or should GL-style error handling be used?

      UNRESOLVED.

    Revision History

    Revision 1, 2012/07/05

    Revision 2, 2012/07/06

    Revision 3, 2012/07/20

    Revision 4, 2012/07/23

    Revision 5, 2012/08/30

    Revision 6, 2013/07/12

    Revision 7, 2014/07/15