Merge pull request #12983 from alarkbentley/alark/async-picking

Added Scene.pickAsync for non GPU blocking picking

Author: mzschwartz5

CHANGES.md

@@ -21,6 +21,7 @@
 
 - Added experimental support for loading 3D Tiles as terrain, via `Cesium3DTilesTerrainProvider`. See [the PR](https://github.com/CesiumGS/cesium/pull/12963) for limitations on the types of 3D Tiles that can be used. [#12296](https://github.com/CesiumGS/cesium/issues/12296)
 - Added support for [EXT_mesh_primitive_edge_visibility](https://github.com/KhronosGroup/glTF/pull/2479) glTF extension. [#12765](https://github.com/CesiumGS/cesium/issues/12765)
+- Added `scene.pickAsync` for non GPU blocking picking using WebGL2 [#12983](https://github.com/CesiumGS/cesium/pull/12983)
 
 #### Fixes :wrench:
 
@@ -34,6 +35,7 @@
 - Fixed picking of `GroundPrimitive` with multiple `PolygonGeometry` instances selecting the wrong instance. [#12978](https://github.com/CesiumGS/cesium/pull/12978)
 - Fixed a bug where the removal of draped imagery layers did not update the rendered state [#12923](https://github.com/CesiumGS/cesium/issues/12923)
 - Fixed precision issues with Gaussian splat tilesets where the root tile does not have a world transform. [#12925](https://github.com/CesiumGS/cesium/issues/12925)
+- Fixed infinite recursion that would happen if user append post-render callbacks within existing callbacks [#12983](https://github.com/CesiumGS/cesium/pull/12983)
 
 ## 1.134.1 - 2025-10-10
 

CONTRIBUTORS.md

@@ -104,6 +104,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to Cesiu
   - [Erin Ingram](https://github.com/eringram)
   - [Daniel Zhong](https://github.com/danielzhong)
   - [Mark Schlosser](https://github.com/markschlosseratbentley)
+  - [Adam Larkeryd](https://github.com/alarkbentley)
 - [Flightradar24 AB](https://www.flightradar24.com)
   - [Aleksei Kalmykov](https://github.com/kalmykov)
 - [BIT Systems](http://www.caci.com/bit-systems)

packages/engine/Source/Renderer/Buffer.js

@@ -72,6 +72,26 @@ function Buffer(options) {
   this.vertexArrayDestroyable = true;
 }
 
+Buffer.createPixelBuffer = function (options) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.defined("options.context", options.context);
+  //>>includeEnd('debug');
+
+  if (!options.context._webgl2) {
+    throw new DeveloperError(
+      "A WebGL 2 context is required to create PixelBuffers.",
+    );
+  }
+
+  return new Buffer({
+    context: options.context,
+    bufferTarget: WebGLConstants.PIXEL_PACK_BUFFER,
+    typedArray: options.typedArray,
+    sizeInBytes: options.sizeInBytes,
+    usage: options.usage,
+  });
+};
+
 /**
  * Creates a vertex buffer, which contains untyped vertex data in GPU-controlled memory.
  * <br /><br />
@@ -242,6 +262,18 @@ Buffer.prototype._getBuffer = function () {
   return this._buffer;
 };
 
+Buffer.prototype._bind = function () {
+  const gl = this._gl;
+  const target = this._bufferTarget;
+  gl.bindBuffer(target, this._buffer);
+};
+
+Buffer.prototype._unBind = function () {
+  const gl = this._gl;
+  const target = this._bufferTarget;
+  gl.bindBuffer(target, null);
+};
+
 Buffer.prototype.copyFromArrayView = function (arrayView, offsetInBytes) {
   offsetInBytes = offsetInBytes ?? 0;
 

packages/engine/Source/Renderer/BufferUsage.js

@@ -7,12 +7,14 @@ const BufferUsage = {
   STREAM_DRAW: WebGLConstants.STREAM_DRAW,
   STATIC_DRAW: WebGLConstants.STATIC_DRAW,
   DYNAMIC_DRAW: WebGLConstants.DYNAMIC_DRAW,
+  DYNAMIC_READ: WebGLConstants.DYNAMIC_READ,
 
   validate: function (bufferUsage) {
     return (
       bufferUsage === BufferUsage.STREAM_DRAW ||
       bufferUsage === BufferUsage.STATIC_DRAW ||
-      bufferUsage === BufferUsage.DYNAMIC_DRAW
+      bufferUsage === BufferUsage.DYNAMIC_DRAW ||
+      bufferUsage === BufferUsage.DYNAMIC_READ
     );
   },
 };

packages/engine/Source/Renderer/Context.js

@@ -1,3 +1,4 @@
+import Buffer from "./Buffer.js";
 import Check from "../Core/Check.js";
 import Color from "../Core/Color.js";
 import ComponentDatatype from "../Core/ComponentDatatype.js";
@@ -1442,13 +1443,88 @@ Context.prototype.endFrame = function () {
 };
 
 /**
+ * @typedef {object} ReadState
+ *
+ * Options defining a rectangle to read pixels from.
+ *
+ * @private
+ * @property {number} [x=0] The x offset of the rectangle to read from.
+ * @property {number} [y=0] The y offset of the rectangle to read from.
+ * @property {number} [width=this.drawingBufferWidth] The width of the rectangle to read from.
+ * @property {number} [height=this.drawingBufferHeight] The height of the rectangle to read from.
+ * @property {FrameBuffer|undefined} [framebuffer] The framebuffer to read from. If undefined, the read will be from the default framebuffer.
+ */
+
+/**
+ * Read pixels from a framebuffer into a Pixel Buffer Object (PBO).
+ *
+ * @private
+ * @param {ReadState} readState Options defining a rectangle to read pixels from.
+ * @returns {Buffer} A PixelBuffer containing the pixels read from the specified rectangle.
+ *
+ * @exception {DeveloperError} A WebGL 2 context is required to read pixels using a PBO.
+ */
+Context.prototype.readPixelsToPBO = function (readState) {
+  const gl = this._gl;
+
+  readState = readState ?? Frozen.EMPTY_OBJECT;
+  const x = Math.max(readState.x ?? 0, 0);
+  const y = Math.max(readState.y ?? 0, 0);
+  const width = readState.width ?? this.drawingBufferWidth;
+  const height = readState.height ?? this.drawingBufferHeight;
+  const framebuffer = readState.framebuffer;
+
+  if (!this._webgl2) {
+    throw new DeveloperError(
+      "A WebGL 2 context is required to read pixels using a PBO.",
+    );
+  }
+
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.number.greaterThan("readState.width", width, 0);
+  Check.typeOf.number.greaterThan("readState.height", height, 0);
+  //>>includeEnd('debug');
+
+  let pixelDatatype = PixelDatatype.UNSIGNED_BYTE;
+  let pixelFormat = PixelFormat.RGBA;
+  if (defined(framebuffer) && framebuffer.numberOfColorAttachments > 0) {
+    pixelDatatype = framebuffer.getColorTexture(0).pixelDatatype;
+    pixelFormat = framebuffer.getColorTexture(0).pixelFormat;
+  }
+
+  const pixels = Buffer.createPixelBuffer({
+    context: this,
+    sizeInBytes: PixelFormat.textureSizeInBytes(
+      pixelFormat,
+      pixelDatatype,
+      width,
+      height,
+    ),
+    usage: BufferUsage.DYNAMIC_READ,
+  });
+
+  bindFramebuffer(this, framebuffer);
+
+  pixels._bind();
+  gl.readPixels(
+    x,
+    y,
+    width,
+    height,
+    pixelFormat,
+    PixelDatatype.toWebGLConstant(pixelDatatype, this),
+    0,
+  );
+  pixels._unBind();
+
+  return pixels;
+};
+
+/**
+ * Read pixels from a framebuffer into a typed array.
+ *
  * @private
- * @param {object} readState An object with the following properties:
- * @param {number} [readState.x=0] The x offset of the rectangle to read from.
- * @param {number} [readState.y=0] The y offset of the rectangle to read from.
- * @param {number} [readState.width=this.drawingBufferWidth] The width of the rectangle to read from.
- * @param {number} [readState.height=this.drawingBufferHeight] The height of the rectangle to read from.
- * @param {Framebuffer} [readState.framebuffer] The framebuffer to read from. If undefined, the read will be from the default framebuffer.
+ * @param {ReadState} readState Options defining a rectangle to read pixels from.
  * @returns {Uint8Array|Uint16Array|Float32Array|Uint32Array} The pixels in the specified rectangle.
  */
 Context.prototype.readPixels = function (readState) {
@@ -1467,12 +1543,14 @@ Context.prototype.readPixels = function (readState) {
   //>>includeEnd('debug');
 
   let pixelDatatype = PixelDatatype.UNSIGNED_BYTE;
+  let pixelFormat = PixelFormat.RGBA;
   if (defined(framebuffer) && framebuffer.numberOfColorAttachments > 0) {
     pixelDatatype = framebuffer.getColorTexture(0).pixelDatatype;
+    pixelFormat = framebuffer.getColorTexture(0).pixelFormat;
   }
 
   const pixels = PixelFormat.createTypedArray(
-    PixelFormat.RGBA,
+    pixelFormat,
     pixelDatatype,
     width,
     height,

packages/engine/Source/Renderer/Sync.js

@@ -0,0 +1,104 @@
+import Check from "../Core/Check.js";
+import destroyObject from "../Core/destroyObject.js";
+import DeveloperError from "../Core/DeveloperError.js";
+import Frozen from "../Core/Frozen.js";
+import RuntimeError from "../Core/RuntimeError.js";
+import WebGLConstants from "../Core/WebGLConstants.js";
+
+/**
+ * The WebGLSync interface is part of the WebGL 2 API and is used to synchronize activities between the GPU and the application.
+ *
+ * @param {object} options Object with the following properties:
+ * @param {Context} context
+ *
+ * @exception {DeveloperError} A WebGL 2 context is required to use Sync operations.
+ *
+ * @private
+ * @constructor
+ */
+function Sync(options) {
+  options = options ?? Frozen.EMPTY_OBJECT;
+  const context = options.context;
+
+  //>>includeStart('debug', pragmas.debug);
+  Check.defined("options.context", context);
+  //>>includeEnd('debug');
+
+  if (!context._webgl2) {
+    throw new DeveloperError(
+      "A WebGL 2 context is required to use Sync operations.",
+    );
+  }
+
+  const gl = context._gl;
+  const sync = gl.fenceSync(WebGLConstants.SYNC_GPU_COMMANDS_COMPLETE, 0);
+
+  this._gl = gl;
+  this._sync = sync;
+}
+Sync.create = function (options) {
+  return new Sync(options);
+};
+/**
+ * Query the sync status of this Sync object.
+ *
+ * @returns {number} Returns a WebGLConstants indicating the status of the sync object (WebGLConstants.SIGNALED or WebGLConstants.UNSIGNALED).
+ *
+ * @private
+ */
+Sync.prototype.getStatus = function () {
+  const status = this._gl.getSyncParameter(
+    this._sync,
+    WebGLConstants.SYNC_STATUS,
+  );
+  return status;
+};
+Sync.prototype.isDestroyed = function () {
+  return false;
+};
+Sync.prototype.destroy = function () {
+  this._gl.deleteSync(this._sync);
+  return destroyObject(this);
+};
+
+/**
+ * Incremantally polls the status of the Sync object until signaled then resolves.
+ * Usually polling should be done once per frame.
+ *
+ * @example
+ * try {
+ *  await sync.waitForSignal(function (next) {
+ *    setTimeout(next, 100);
+ *  });
+ *} catch (e) {
+ *  throw "Signal timeout";
+ *} finally {
+ *  sync.destroy();
+ *}
+ *
+ * @param {function} scheduleFunction Function for scheduling the next poll. Receives a callback as its only parameter.
+ * @param {number} [ttl=10] Max number of iterations to poll until timeout.
+ *
+ * @exception {RuntimeError} Wait for signal timeout.
+ */
+Sync.prototype.waitForSignal = async function (scheduleFunction, ttl) {
+  const self = this;
+  ttl = ttl ?? 10;
+  function waitForSignal0(resolve, reject, ttl) {
+    return () => {
+      const syncStatus = self.getStatus();
+      const signaled = syncStatus === WebGLConstants.SIGNALED;
+      if (signaled) {
+        resolve();
+      } else if (ttl <= 0) {
+        reject(new RuntimeError("Wait for signal timeout"));
+      } else {
+        scheduleFunction(waitForSignal0(resolve, reject, ttl - 1));
+      }
+    };
+  }
+  return new Promise((resolve, reject) => {
+    scheduleFunction(waitForSignal0(resolve, reject, ttl));
+  });
+};
+export default Sync;