@cesium/engine 10.1.0 → 11.1.0

package/Source/Scene/SpecularEnvironmentCubeMap.js

@@ -0,0 +1,240 @@
+import defined from "../Core/defined.js";
+import destroyObject from "../Core/destroyObject.js";
+import Event from "../Core/Event.js";
+import loadKTX2 from "../Core/loadKTX2.js";
+import PixelFormat from "../Core/PixelFormat.js";
+import CubeMap from "../Renderer/CubeMap.js";
+import PixelDatatype from "../Renderer/PixelDatatype.js";
+import Sampler from "../Renderer/Sampler.js";
+import TextureMinificationFilter from "../Renderer/TextureMinificationFilter.js";
+
+/**
+ * Manages a cube map for use as a specular environment map.
+ *
+ * @alias SpecularEnvironmentCubeMap
+ * @constructor
+ *
+ * @param {string} url The url to the KTX2 file containing the specular environment map and convoluted mipmaps.
+ * @private
+ */
+function SpecularEnvironmentCubeMap(url) {
+  this._url = url;
+
+  this._cubeMapBuffers = undefined;
+  this._texture = undefined;
+
+  this._maximumMipmapLevel = undefined;
+
+  this._loading = false;
+  this._ready = false;
+
+  this._errorEvent = new Event();
+}
+
+Object.defineProperties(SpecularEnvironmentCubeMap.prototype, {
+  /**
+   * The url to the KTX2 file containing the specular environment map and convoluted mipmaps.
+   * @memberof SpecularEnvironmentCubeMap.prototype
+   * @type {string}
+   * @readonly
+   */
+  url: {
+    get: function () {
+      return this._url;
+    },
+  },
+  /**
+   * Gets an event that is raised when encountering an asynchronous error.  By subscribing
+   * to the event, you will be notified of the error and can potentially recover from it.
+   * @memberof SpecularEnvironmentCubeMap.prototype
+   * @type {Event}
+   * @readonly
+   */
+  errorEvent: {
+    get: function () {
+      return this._errorEvent;
+    },
+  },
+  /**
+   * A texture containing all the packed convolutions.
+   * @memberof SpecularEnvironmentCubeMap.prototype
+   * @type {Texture}
+   * @readonly
+   */
+  texture: {
+    get: function () {
+      return this._texture;
+    },
+  },
+  /**
+   * The maximum number of mip levels with valid environment map data.
+   * This may differ from the number of mips in the WebGL cubemap.
+   * The data loaded at <code>maximumMipmapLevel</code> is suitable for
+   * PBR rendering of a material with maximum roughness (1.0).
+   * @memberOf SpecularEnvironmentCubeMap.prototype
+   * @type {number}
+   * @readonly
+   */
+  maximumMipmapLevel: {
+    get: function () {
+      return this._maximumMipmapLevel;
+    },
+  },
+  /**
+   * Determines if the cube map is complete and ready to use.
+   * @memberof SpecularEnvironmentCubeMap.prototype
+   * @type {boolean}
+   * @readonly
+   */
+  ready: {
+    get: function () {
+      return this._ready;
+    },
+  },
+});
+
+SpecularEnvironmentCubeMap.isSupported = function (context) {
+  const supportsFloatBuffersAndTextures =
+    (context.colorBufferHalfFloat && context.halfFloatingPointTexture) ||
+    (context.floatingPointTexture && context.colorBufferFloat);
+  return supportsFloatBuffersAndTextures && context.supportsTextureLod;
+};
+
+function cleanupResources(map) {
+  map._cubeMapBuffers = undefined;
+}
+
+/**
+ * Loads the environment map image and constructs the cube map for specular radiance calculations.
+ * <p>
+ * Once the image is loaded, the next call cleans up unused resources. Every call after that is a no-op.
+ * </p>
+ * @param {FrameState} frameState The frame state.
+ *
+ * @private
+ */
+SpecularEnvironmentCubeMap.prototype.update = function (frameState) {
+  const { context } = frameState;
+
+  if (!SpecularEnvironmentCubeMap.isSupported(context)) {
+    return;
+  }
+
+  if (defined(this._texture)) {
+    cleanupResources(this);
+    return;
+  }
+
+  if (!defined(this._texture) && !this._loading) {
+    const cachedTexture = context.textureCache.getTexture(this._url);
+    if (defined(cachedTexture)) {
+      cleanupResources(this);
+      this._texture = cachedTexture;
+      this._maximumMipmapLevel = this._texture.maximumMipmapLevel;
+      this._ready = true;
+    }
+  }
+
+  const cubeMapBuffers = this._cubeMapBuffers;
+  if (!defined(cubeMapBuffers) && !this._loading) {
+    const that = this;
+    loadKTX2(this._url)
+      .then(function (buffers) {
+        that._cubeMapBuffers = buffers;
+        that._loading = false;
+      })
+      .catch(function (error) {
+        if (that.isDestroyed()) {
+          return;
+        }
+        that._errorEvent.raiseEvent(error);
+      });
+    this._loading = true;
+  }
+
+  if (!defined(this._cubeMapBuffers)) {
+    return;
+  }
+
+  // Datatype is defined if it is a normalized type (i.e. ..._UNORM, ..._SFLOAT)
+  let { pixelDatatype } = cubeMapBuffers[0].positiveX;
+  if (!defined(pixelDatatype)) {
+    pixelDatatype = context.halfFloatingPointTexture
+      ? PixelDatatype.HALF_FLOAT
+      : PixelDatatype.FLOAT;
+  }
+  const pixelFormat = PixelFormat.RGBA;
+
+  const mipLevels = cubeMapBuffers.length;
+  this._maximumMipmapLevel = mipLevels - 1;
+
+  const faceSize = cubeMapBuffers[0].positiveX.width;
+  const expectedMipLevels = Math.log2(faceSize) + 1;
+  if (mipLevels !== expectedMipLevels) {
+    // We assume the last supplied mip level was computed as the specular radiance
+    // for roughness 1.0.
+    // Fill the remaining levels with null values, to avoid WebGL errors.
+    const dummyMipLevel = {};
+    Object.values(CubeMap.FaceName).forEach((faceName) => {
+      dummyMipLevel[faceName] = undefined;
+    });
+    for (let mipLevel = mipLevels; mipLevel < expectedMipLevels; mipLevel++) {
+      cubeMapBuffers.push(dummyMipLevel);
+    }
+  }
+
+  const sampler = new Sampler({
+    minificationFilter: TextureMinificationFilter.LINEAR_MIPMAP_LINEAR,
+  });
+
+  const cubeMap = new CubeMap({
+    context: context,
+    source: cubeMapBuffers[0],
+    flipY: false,
+    pixelDatatype: pixelDatatype,
+    pixelFormat: pixelFormat,
+    sampler: sampler,
+  });
+  cubeMap.loadMipmaps(cubeMapBuffers.slice(1));
+  this._texture = cubeMap;
+
+  this._texture.maximumMipmapLevel = this._maximumMipmapLevel;
+  context.textureCache.addTexture(this._url, this._texture);
+
+  this._ready = true;
+};
+
+/**
+ * Returns true if this object was destroyed; otherwise, false.
+ * <p>
+ * If this object was destroyed, it should not be used; calling any function other than
+ * <code>isDestroyed</code> will result in a {@link DeveloperError} exception.
+ * </p>
+ *
+ * @returns {boolean} <code>true</code> if this object was destroyed; otherwise, <code>false</code>.
+ *
+ * @see SpecularEnvironmentCubeMap#destroy
+ */
+SpecularEnvironmentCubeMap.prototype.isDestroyed = function () {
+  return false;
+};
+
+/**
+ * Destroys the WebGL resources held by this object.  Destroying an object allows for deterministic
+ * release of WebGL resources, instead of relying on the garbage collector to destroy this object.
+ * <p>
+ * Once an object is destroyed, it should not be used; calling any function other than
+ * <code>isDestroyed</code> will result in a {@link DeveloperError} exception.  Therefore,
+ * assign the return value (<code>undefined</code>) to the object as done in the example.
+ * </p>
+ *
+ * @exception {DeveloperError} This object was destroyed, i.e., destroy() was called.
+ *
+ * @see SpecularEnvironmentCubeMap#isDestroyed
+ */
+SpecularEnvironmentCubeMap.prototype.destroy = function () {
+  cleanupResources(this);
+  this._texture = this._texture && this._texture.destroy();
+  return destroyObject(this);
+};
+export default SpecularEnvironmentCubeMap;

package/Source/Scene/SphereEmitter.js

@@ -60,7 +60,7 @@ SphereEmitter.prototype.emit = function (particle) {
   particle.position = Cartesian3.fromElements(x, y, z, particle.position);
   particle.velocity = Cartesian3.normalize(
     particle.position,
-    particle.velocity
+    particle.velocity,
   );
 };
 export default SphereEmitter;

package/Source/Scene/StructuralMetadata.js

@@ -231,7 +231,7 @@ StructuralMetadata.prototype.getPropertyTexture = function (propertyTextureId) {
  * @private
  */
 StructuralMetadata.prototype.getPropertyAttribute = function (
-  propertyAttributeId
+  propertyAttributeId,
 ) {
   //>>includeStart('debug', pragmas.debug);
   Check.typeOf.number("propertyAttributeId", propertyAttributeId);

package/Source/Scene/StyleExpression.js

@@ -67,7 +67,7 @@ StyleExpression.prototype.getShaderFunction = function (
   functionSignature,
   variableSubstitutionMap,
   shaderState,
-  returnType
+  returnType,
 ) {
   DeveloperError.throwInstantiationError();
 };

package/Source/Scene/Sun.js

@@ -270,11 +270,15 @@ Sun.prototype.update = function (frameState, passState, useHdr) {
   const position = SceneTransforms.computeActualEllipsoidPosition(
     frameState,
     sunPosition,
-    scratchCartesian4
+    scratchCartesian4,
   );
 
   const dist = Cartesian3.magnitude(
-    Cartesian3.subtract(position, frameState.camera.position, scratchCartesian4)
+    Cartesian3.subtract(
+      position,
+      frameState.camera.position,
+      scratchCartesian4,
+    ),
   );
   const projMatrix = context.uniformState.projection;
 
@@ -287,28 +291,28 @@ Sun.prototype.update = function (frameState, passState, useHdr) {
   const positionCC = Matrix4.multiplyByVector(
     projMatrix,
     positionEC,
-    scratchCartesian4
+    scratchCartesian4,
   );
   const positionWC = SceneTransforms.clipToGLWindowCoordinates(
     passState.viewport,
     positionCC,
-    scratchPositionWC
+    scratchPositionWC,
   );
 
   positionEC.x = CesiumMath.SOLAR_RADIUS;
   const limbCC = Matrix4.multiplyByVector(
     projMatrix,
     positionEC,
-    scratchCartesian4
+    scratchCartesian4,
   );
   const limbWC = SceneTransforms.clipToGLWindowCoordinates(
     passState.viewport,
     limbCC,
-    scratchLimbWC
+    scratchLimbWC,
   );
 
   this._size = Cartesian2.magnitude(
-    Cartesian2.subtract(limbWC, positionWC, scratchCartesian4)
+    Cartesian2.subtract(limbWC, positionWC, scratchCartesian4),
   );
   this._size = 2.0 * this._size * (1.0 + 2.0 * this._glowLengthTS);
   this._size = Math.ceil(this._size);

package/Source/Scene/SunPostProcess.js

@@ -154,18 +154,18 @@ function updateSunPosition(postProcess, context, viewport) {
     viewport,
     0.0,
     1.0,
-    postProcessMatrix4Scratch
+    postProcessMatrix4Scratch,
   );
   const sunPositionEC = Matrix4.multiplyByPoint(
     viewMatrix,
     sunPosition,
-    sunPositionECScratch
+    sunPositionECScratch,
   );
   let sunPositionWC = Transforms.pointToGLWindowCoordinates(
     viewProjectionMatrix,
     viewportTransformation,
     sunPosition,
-    sunPositionWCScratch
+    sunPositionWCScratch,
   );
 
   sunPositionEC.x += CesiumMath.SOLAR_RADIUS;
@@ -173,7 +173,7 @@ function updateSunPosition(postProcess, context, viewport) {
     projectionMatrix,
     viewportTransformation,
     sunPositionEC,
-    sunPositionEC
+    sunPositionEC,
   );
   const sunSize =
     Cartesian2.magnitude(Cartesian2.subtract(limbWC, sunPositionWC, limbWC)) *
@@ -205,13 +205,13 @@ function updateSunPosition(postProcess, context, viewport) {
     downSampleViewport,
     0.0,
     1.0,
-    postProcessMatrix4Scratch
+    postProcessMatrix4Scratch,
   );
   sunPositionWC = Transforms.pointToGLWindowCoordinates(
     viewProjectionMatrix,
     viewportTransformation,
     sunPosition,
-    sunPositionWCScratch
+    sunPositionWCScratch,
   );
 
   size.x *= downSampleWidth / width;