WebGL
Khronos
 

WebGL WEBGL_get_buffer_sub_data_async Extension Draft Specification

Name

WEBGL_get_buffer_sub_data_async

Contact

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

Contributors

Kai Ninomiya, Google Inc.

Members of the WebGL working group

Version

Last modified date: December 13, 2016
Revision: 1

Number

WebGL extension #34

Dependencies

Written against the WebGL API 2.0 specification.

Overview

This extension allows asynchronous buffer readback in WebGL 2.0.

When this extension is enabled:

IDL

[NoInterfaceObject]
interface WEBGL_get_buffer_sub_data_async {
  // Asynchronous version of getBufferSubData which fulfills the returned promise when the data becomes available.
  Promise<ArrayBuffer> getBufferSubDataAsync(GLenum target, GLintptr srcByteOffset, ArrayBufferView dstBuffer,
                                                   optional GLuint dstOffset = 0, optional GLuint length = 0); // May throw DOMException
};
  

New Functions

Promise<ArrayBuffer> getBufferSubDataAsync(GLenum target, GLintptr srcByteOffset, ArrayBufferView dstBuffer, optional GLuint dstOffset, optional GLuint length)
Reads back data asynchronously from the bound WebGLBuffer into dstBuffer.

Let buf be the buffer bound to target at the time getBufferSubDataAsync is called. If length is 0, let copyLength be dstBuffer.length - dstOffset; otherwise, let copyLength be length.

If copyLength is greater than zero, copy copyLength typed elements (each of size dstBuffer.BYTES_PER_ELEMENT) from buf into dstBuffer, reading buf starting at byte index srcByteOffset and writing into dstBuffer starting at element index dstOffset. If copyLength is 0, no data is written to dstBuffer, but this does not cause a GL error to be generated. When invoked, getBufferSubDataAsync must run these steps: If the returned Promise is rejected, no data is written to dstBuffer.
Even if getBufferSubDataAsync is called multiple times in a row with the same dstBuffer, then callbacks added synchronously will never see results of subsequent getBufferSubDataAsync calls.
Compared to the synchronous version of getBufferSubData, this version may impose less overhead on applications. Intended use cases include reading pixels into a pixel buffer object and examining that data on the CPU. It does not force the graphics pipeline to be stalled as getBufferSubData does.

Revision History

Revision 1, 2016/12/13