WebGL WEBGL_shader_pixel_local_storage Extension Draft Specification

Name

WEBGL_shader_pixel_local_storage

Contact

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

Contributors

Chris Dalton, Rive

Kenneth Russell, Google Inc.

Shahbaz Youssefi, Google Inc.

Kelsey Gilbert, Mozilla Corp.

Geoff Lang, Google Inc.

Kimmo Kinnunen, Apple Inc.

Members of the WebGL working group

Version

Last modified date: September 08, 2023
Revision: 2

Number

WebGL extension #49

Dependencies

Written against the WebGL API 2.0 specification.

Overview

This extension exposes the ANGLE_shader_pixel_local_storage functionality to WebGL.

The following WebGL-specific behavioral changes apply:

Coherency is indicated by the function isCoherent(), rather than the existence of a similar extension string.

Exposing two distinct, yet almost identical interfaces would be much less convenient.
FramebufferMemorylessPixelLocalStorageANGLE is not supported.

Browsers must be able to interrupt a WebGL rendering context at any moment, and if memoryless pixel local storage planes could be active during such a time, their contents would become invalidated.
FramebufferPixelLocalStorageInterruptANGLE and FramebufferPixelLocalStorageRestoreANGLE are not supported.

These commands are only intended for internal use by the browser implementation.
When this extension is enabled, the following WebGL extensions are enabled implicitly:

Consult the above extension for documentation, issues and new functions and enumerants.

IDL

[Exposed=(Window,Worker), LegacyNoInterfaceObject]
interface WEBGL_shader_pixel_local_storage {
  const GLenum MAX_PIXEL_LOCAL_STORAGE_PLANES_WEBGL = 0x96E0;
  const GLenum MAX_COLOR_ATTACHMENTS_WITH_ACTIVE_PIXEL_LOCAL_STORAGE_WEBGL = 0x96E1;
  const GLenum MAX_COMBINED_DRAW_BUFFERS_AND_PIXEL_LOCAL_STORAGE_PLANES_WEBGL = 0x96E2;
  const GLenum PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_WEBGL = 0x96E3;
  const GLenum LOAD_OP_ZERO_WEBGL = 0x96E4;
  const GLenum LOAD_OP_CLEAR_WEBGL = 0x96E5;
  const GLenum LOAD_OP_LOAD_WEBGL = 0x96E6;
  const GLenum STORE_OP_STORE_WEBGL = 0x96E7;
  const GLenum PIXEL_LOCAL_FORMAT_WEBGL = 0x96E8;
  const GLenum PIXEL_LOCAL_TEXTURE_NAME_WEBGL = 0x96E9;
  const GLenum PIXEL_LOCAL_TEXTURE_LEVEL_WEBGL = 0x96EA;
  const GLenum PIXEL_LOCAL_TEXTURE_LAYER_WEBGL = 0x96EB;
  const GLenum PIXEL_LOCAL_CLEAR_VALUE_FLOAT_WEBGL = 0x96EC;
  const GLenum PIXEL_LOCAL_CLEAR_VALUE_INT_WEBGL = 0x96ED;
  const GLenum PIXEL_LOCAL_CLEAR_VALUE_UNSIGNED_INT_WEBGL = 0x96EE;
  GLboolean isCoherent();
  undefined framebufferTexturePixelLocalStorageWEBGL(GLint plane,
                                                     WebGLTexture? texture,
                                                     GLint level,
                                                     GLint layer);
  undefined framebufferPixelLocalClearValuefvWEBGL(GLint plane,
                                                   Float32List value,
                                                   optional unsigned long long srcOffset = 0);
  undefined framebufferPixelLocalClearValueivWEBGL(GLint plane,
                                                   Int32List value,
                                                   optional unsigned long long srcOffset = 0);
  undefined framebufferPixelLocalClearValueuivWEBGL(GLint plane,
                                                    Uint32List value,
                                                    optional unsigned long long srcOffset = 0);
  undefined beginPixelLocalStorageWEBGL(sequence<GLenum> loadops);
  undefined endPixelLocalStorageWEBGL(sequence<GLenum> storeops);
  undefined pixelLocalStorageBarrierWEBGL();
  any getFramebufferPixelLocalStorageParameterWEBGL(GLint plane, GLenum pname);
};

New Functions

GLboolean isCoherent(): Indicates whether pixel local storage operations touching the same pixel are invoked synchronously and in API primitive order. If false, the application must call pixelLocalStorageBarrierWEBGL()between rendering passes that touch the same pixel.
Use this function to determine if pixel local storage is coherent, rather than checking for another extension string.

undefined framebufferTexturePixelLocalStorageWEBGL(GLint plane, WebGLTexture? texture, GLint level, GLint layer)

Establishes the backing texture for the given plane.

If texture has been deleted, generates an INVALID_OPERATION error.

If texture was generated by a different WebGL2RenderingContext than this one, generates an INVALID_OPERATION error.

undefined framebufferPixelLocalClearValuefvWEBGL(GLint plane, Float32List value, optional unsigned long long srcOffset = 0)

Sets the floating point clear value for the given plane.

If value has fewer than srcOffset + 4 elements, generates an INVALID_VALUE error.

undefined framebufferPixelLocalClearValueivWEBGL(GLint plane, Int32List value, optional unsigned long long srcOffset = 0)

Sets the signed integer clear value for the given plane.

If value has fewer than srcOffset + 4 elements, generates an INVALID_VALUE error.

undefined framebufferPixelLocalClearValueuivWEBGL(GLint plane, Uint32List value, optional unsigned long long srcOffset = 0)

Sets the unsigned integer clear value for the given plane.

If value has fewer than srcOffset + 4 elements, generates an INVALID_VALUE error.

undefined beginPixelLocalStorageWEBGL(sequence<GLenum> loadops): Activates pixel local storage.

undefined endPixelLocalStorageWEBGL(sequence<GLenum> storeops): Deactivates pixel local storage.

undefined pixelLocalStorageBarrierWEBGL(): Delimits a boundary between distinct, non-self-overlapping rendering passes.

any getFramebufferPixelLocalStorageParameterWEBGL(GLint plane, GLenum pname): Returns a specific parameter for the given pixel local storage plane. The return type of this method depends on the parameter queried. See the below section on "New Tokens".

New Tokens

undefined getParameter(GLenum pname)

pname accepts the following new tokens.

The return type is GLint for all additional parameters.

pname	returned type
MAX_PIXEL_LOCAL_STORAGE_PLANES_WEBGL	GLint
MAX_COLOR_ATTACHMENTS_WITH_ACTIVE_PIXEL_LOCAL_STORAGE_WEBGL	GLint
MAX_COMBINED_DRAW_BUFFERS_AND_PIXEL_LOCAL_STORAGE_PLANES_WEBGL	GLint
PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_WEBGL	GLint

undefined beginPixelLocalStorageWEBGL(sequence<GLenum> loadops)

loadops accepts the following new tokens:

loadops
LOAD_OP_ZERO_WEBGL
LOAD_OP_CLEAR_WEBGL
LOAD_OP_LOAD_WEBGL

undefined endPixelLocalStorageWEBGL(sequence<GLenum> storeops)

storeops accepts the following new tokens:

storeops
STORE_OP_STORE_WEBGL

any getFramebufferPixelLocalStorageParameterWEBGL(GLint plane, GLenum pname)

pname accepts the following new tokens.

The return type depends on the parameter queried.

pname	returned type
PIXEL_LOCAL_FORMAT_WEBGL	GLenum
PIXEL_LOCAL_TEXTURE_NAME_WEBGL	WebGLTexture?
PIXEL_LOCAL_TEXTURE_LEVEL_WEBGL	GLint
PIXEL_LOCAL_TEXTURE_LAYER_WEBGL	GLint
PIXEL_LOCAL_CLEAR_VALUE_FLOAT_WEBGL	Float32Array
PIXEL_LOCAL_CLEAR_VALUE_INT_WEBGL	Int32Array
PIXEL_LOCAL_CLEAR_VALUE_UNSIGNED_INT_WEBGL	Uint32Array

Revision History

Revision 1, 2022/12/06

Initial Draft.

Revision 2, 2023/09/08

Changed srcOffset arguments to "unsigned long long" for Wasm.