@cesium/engine 11.0.0 → 12.0.0

package/Source/Renderer/CubeMap.js

@@ -1,17 +1,24 @@
+import BoxGeometry from "../Core/BoxGeometry.js";
+import Cartesian3 from "../Core/Cartesian3.js";
 import Check from "../Core/Check.js";
 import defaultValue from "../Core/defaultValue.js";
 import defined from "../Core/defined.js";
 import destroyObject from "../Core/destroyObject.js";
 import DeveloperError from "../Core/DeveloperError.js";
+import GeometryPipeline from "../Core/GeometryPipeline.js";
 import CesiumMath from "../Core/Math.js";
 import PixelFormat from "../Core/PixelFormat.js";
+import VertexFormat from "../Core/VertexFormat.js";
+import BufferUsage from "./BufferUsage.js";
 import ContextLimits from "./ContextLimits.js";
 import CubeMapFace from "./CubeMapFace.js";
+import Framebuffer from "./Framebuffer.js";
 import MipmapHint from "./MipmapHint.js";
 import PixelDatatype from "./PixelDatatype.js";
 import Sampler from "./Sampler.js";
 import TextureMagnificationFilter from "./TextureMagnificationFilter.js";
 import TextureMinificationFilter from "./TextureMinificationFilter.js";
+import VertexArray from "./VertexArray.js";
 
 /**
  * @typedef CubeMap.BufferSource
@@ -91,13 +98,13 @@ function CubeMap(options) {
     //>>includeStart('debug', pragmas.debug);
     if (
       !Object.values(CubeMap.FaceName).every((faceName) =>
-        defined(source[faceName])
+        defined(source[faceName]),
       )
     ) {
       throw new DeveloperError(
         `options.source requires faces ${Object.values(CubeMap.FaceName).join(
-          ", "
-        )}.`
+          ", ",
+        )}.`,
       );
     }
     //>>includeEnd('debug');
@@ -105,11 +112,11 @@ function CubeMap(options) {
     ({ width, height } = source.positiveX);
 
     //>>includeStart('debug', pragmas.debug);
-    for (const faceName of CubeMap.getFaceNames()) {
+    for (const faceName of CubeMap.faceNames()) {
       const face = source[faceName];
       if (Number(face.width) !== width || Number(face.height) !== height) {
         throw new DeveloperError(
-          "Each face in options.source must have the same width and height."
+          "Each face in options.source must have the same width and height.",
         );
       }
     }
@@ -121,7 +128,7 @@ function CubeMap(options) {
   //>>includeStart('debug', pragmas.debug);
   if (!defined(width) || !defined(height)) {
     throw new DeveloperError(
-      "options requires a source field to create an initialized cube map or width and height fields to create a blank cube map."
+      "options requires a source field to create an initialized cube map or width and height fields to create a blank cube map.",
     );
   }
 
@@ -135,7 +142,7 @@ function CubeMap(options) {
 
   if (size > ContextLimits.maximumCubeMapSize) {
     throw new DeveloperError(
-      `Width and height must be less than or equal to the maximum cube map size (${ContextLimits.maximumCubeMapSize}). Check maximumCubeMapSize.`
+      `Width and height must be less than or equal to the maximum cube map size (${ContextLimits.maximumCubeMapSize}). Check maximumCubeMapSize.`,
     );
   }
 
@@ -145,7 +152,7 @@ function CubeMap(options) {
 
   if (PixelFormat.isDepthFormat(pixelFormat)) {
     throw new DeveloperError(
-      "options.pixelFormat cannot be DEPTH_COMPONENT or DEPTH_STENCIL."
+      "options.pixelFormat cannot be DEPTH_COMPONENT or DEPTH_STENCIL.",
     );
   }
 
@@ -155,7 +162,7 @@ function CubeMap(options) {
 
   if (pixelDatatype === PixelDatatype.FLOAT && !context.floatingPointTexture) {
     throw new DeveloperError(
-      "When options.pixelDatatype is FLOAT, this WebGL implementation must support the OES_texture_float extension."
+      "When options.pixelDatatype is FLOAT, this WebGL implementation must support the OES_texture_float extension.",
     );
   }
 
@@ -164,7 +171,7 @@ function CubeMap(options) {
     !context.halfFloatingPointTexture
   ) {
     throw new DeveloperError(
-      "When options.pixelDatatype is HALF_FLOAT, this WebGL implementation must support the OES_texture_half_float extension."
+      "When options.pixelDatatype is HALF_FLOAT, this WebGL implementation must support the OES_texture_half_float extension.",
     );
   }
   //>>includeEnd('debug');
@@ -174,7 +181,7 @@ function CubeMap(options) {
   const internalFormat = PixelFormat.toInternalFormat(
     pixelFormat,
     pixelDatatype,
-    context
+    context,
   );
 
   const gl = context._gl;
@@ -206,7 +213,7 @@ function CubeMap(options) {
       size,
       preMultiplyAlpha,
       flipY,
-      initialized
+      initialized,
     );
   }
   this._positiveX = constructFace(gl.TEXTURE_CUBE_MAP_POSITIVE_X);
@@ -227,23 +234,49 @@ function CubeMap(options) {
   } else {
     gl.pixelStorei(
       gl.UNPACK_COLORSPACE_CONVERSION_WEBGL,
-      gl.BROWSER_DEFAULT_WEBGL
+      gl.BROWSER_DEFAULT_WEBGL,
     );
   }
 
-  for (const faceName of CubeMap.getFaceNames()) {
+  for (const faceName of CubeMap.faceNames()) {
     loadFace(this[faceName], source?.[faceName], 0);
   }
 
   gl.bindTexture(textureTarget, null);
 }
 
+/**
+ * Copy an existing texture to a cubemap face.
+ * @param {FrameState} frameState The current rendering frameState
+ * @param {Texture} texture Texture being copied
+ * @param {CubeMap.FaceName} face The face to which to copy
+ * @param {number} [mipLevel=0] The mip level at which to copy
+ */
+CubeMap.prototype.copyFace = function (frameState, texture, face, mipLevel) {
+  const context = frameState.context;
+  const framebuffer = new Framebuffer({
+    context: context,
+    colorTextures: [texture],
+    destroyAttachments: false,
+  });
+
+  framebuffer._bind();
+
+  this[face].copyMipmapFromFramebuffer(
+    0,
+    0,
+    texture.width,
+    texture.height,
+    defaultValue(mipLevel, 0),
+  );
+  framebuffer._unBind();
+  framebuffer.destroy();
+};
+
 /**
  * An enum defining the names of the faces of a cube map.
- *
  * @alias {CubeMap.FaceName}
  * @enum {string}
- *
  * @private
  */
 CubeMap.FaceName = Object.freeze({
@@ -255,7 +288,7 @@ CubeMap.FaceName = Object.freeze({
   NEGATIVEZ: "negativeZ",
 });
 
-function* makeFacesIterator() {
+function* makeFaceNamesIterator() {
   yield CubeMap.FaceName.POSITIVEX;
   yield CubeMap.FaceName.NEGATIVEX;
   yield CubeMap.FaceName.POSITIVEY;
@@ -266,22 +299,18 @@ function* makeFacesIterator() {
 
 /**
  * Creates an iterator for looping over the cubemap faces.
- *
  * @type {Iterable<CubeMap.FaceName>}
- *
  * @private
  */
-CubeMap.getFaceNames = function () {
-  return makeFacesIterator();
+CubeMap.faceNames = function () {
+  return makeFaceNamesIterator();
 };
 
 /**
  * Load texel data into one face of a cube map.
- *
  * @param {CubeMapFace} cubeMapFace The face to which texel values will be loaded.
  * @param {ImageData|HTMLImageElement|HTMLCanvasElement|HTMLVideoElement|CubeMap.BufferSource} [source] The source for texel values to be loaded into the texture.
  * @param {number} [mipLevel=0] The mip level to which the texel values will be loaded.
- *
  * @private
  */
 function loadFace(cubeMapFace, source, mipLevel) {
@@ -306,7 +335,7 @@ function loadFace(cubeMapFace, source, mipLevel) {
       0,
       pixelFormat,
       PixelDatatype.toWebGLConstant(pixelDatatype, context),
-      null
+      null,
     );
     return;
   }
@@ -318,7 +347,7 @@ function loadFace(cubeMapFace, source, mipLevel) {
     unpackAlignment = PixelFormat.alignmentInBytes(
       pixelFormat,
       pixelDatatype,
-      size
+      size,
     );
   }
   gl.pixelStorei(gl.UNPACK_ALIGNMENT, unpackAlignment);
@@ -332,7 +361,7 @@ function loadFace(cubeMapFace, source, mipLevel) {
         pixelFormat,
         pixelDatatype,
         size,
-        size
+        size,
       );
     }
     gl.texImage2D(
@@ -344,7 +373,7 @@ function loadFace(cubeMapFace, source, mipLevel) {
       0,
       pixelFormat,
       PixelDatatype.toWebGLConstant(pixelDatatype, context),
-      arrayBufferView
+      arrayBufferView,
     );
   } else {
     // Only valid for DOM-Element uploads
@@ -356,11 +385,13 @@ function loadFace(cubeMapFace, source, mipLevel) {
       internalFormat,
       pixelFormat,
       PixelDatatype.toWebGLConstant(pixelDatatype, context),
-      source
+      source,
     );
   }
 }
 
+CubeMap.loadFace = loadFace;
+
 Object.defineProperties(CubeMap.prototype, {
   positiveX: {
     get: function () {
@@ -447,6 +478,29 @@ Object.defineProperties(CubeMap.prototype, {
   },
 });
 
+/**
+ * Get a vector representing the cubemap face direction
+ * @param {CubeMap.FaceName} face The relevant face
+ * @param {Cartesian3} [result] The object onto which to store the result.
+ * @returns {Cartesian3} The vector representing the cubemap face direction
+ */
+CubeMap.getDirection = function (face, result) {
+  switch (face) {
+    case CubeMap.FaceName.POSITIVEX:
+      return Cartesian3.clone(Cartesian3.UNIT_X, result);
+    case CubeMap.FaceName.NEGATIVEX:
+      return Cartesian3.negate(Cartesian3.UNIT_X, result);
+    case CubeMap.FaceName.POSITIVEY:
+      return Cartesian3.clone(Cartesian3.UNIT_Y, result);
+    case CubeMap.FaceName.NEGATIVEY:
+      return Cartesian3.negate(Cartesian3.UNIT_Y, result);
+    case CubeMap.FaceName.POSITIVEZ:
+      return Cartesian3.clone(Cartesian3.UNIT_Z, result);
+    case CubeMap.FaceName.NEGATIVEZ:
+      return Cartesian3.negate(Cartesian3.UNIT_Z, result);
+  }
+};
+
 /**
  * Set up a sampler for use with a cube map.
  * @param {CubeMap} cubeMap The cube map containing the texture to be sampled by this sampler.
@@ -492,7 +546,7 @@ function setupSampler(cubeMap, sampler) {
     gl.texParameteri(
       target,
       cubeMap._textureFilterAnisotropic.TEXTURE_MAX_ANISOTROPY_EXT,
-      sampler.maximumAnisotropy
+      sampler.maximumAnisotropy,
     );
   }
   gl.bindTexture(target, null);
@@ -531,7 +585,7 @@ CubeMap.prototype.loadMipmaps = function (source, skipColorSpaceConversion) {
   } else {
     gl.pixelStorei(
       gl.UNPACK_COLORSPACE_CONVERSION_WEBGL,
-      gl.BROWSER_DEFAULT_WEBGL
+      gl.BROWSER_DEFAULT_WEBGL,
     );
   }
 
@@ -539,7 +593,7 @@ CubeMap.prototype.loadMipmaps = function (source, skipColorSpaceConversion) {
     const mipSource = source[i];
     // mipLevel 0 was the base layer, already loaded when the CubeMap was constructed.
     const mipLevel = i + 1;
-    for (const faceName of CubeMap.getFaceNames()) {
+    for (const faceName of CubeMap.faceNames()) {
       loadFace(this[faceName], mipSource[faceName], mipLevel);
     }
   }
@@ -573,7 +627,7 @@ CubeMap.prototype.generateMipmap = function (hint) {
   //>>includeStart('debug', pragmas.debug);
   if (this._size > 1 && !CesiumMath.isPowerOfTwo(this._size)) {
     throw new DeveloperError(
-      "width and height must be a power of two to call generateMipmap()."
+      "width and height must be a power of two to call generateMipmap().",
     );
   }
   if (!MipmapHint.validate(hint)) {
@@ -592,6 +646,29 @@ CubeMap.prototype.generateMipmap = function (hint) {
   gl.bindTexture(target, null);
 };
 
+/**
+ * Create a vertex array that can be used for cubemap shaders.
+ * @param {Context} context The rendering context
+ * @returns {VertexArray} The created vertex array
+ */
+CubeMap.createVertexArray = function (context) {
+  const geometry = BoxGeometry.createGeometry(
+    BoxGeometry.fromDimensions({
+      dimensions: new Cartesian3(2.0, 2.0, 2.0),
+      vertexFormat: VertexFormat.POSITION_ONLY,
+    }),
+  );
+  const attributeLocations = (this._attributeLocations =
+    GeometryPipeline.createAttributeLocations(geometry));
+
+  return VertexArray.fromGeometry({
+    context: context,
+    geometry: geometry,
+    attributeLocations: attributeLocations,
+    bufferUsage: BufferUsage.STATIC_DRAW,
+  });
+};
+
 CubeMap.prototype.isDestroyed = function () {
   return false;
 };

package/Source/Renderer/CubeMapFace.js

@@ -19,7 +19,7 @@ function CubeMapFace(
   size,
   preMultiplyAlpha,
   flipY,
-  initialized
+  initialized,
 ) {
   this._context = context;
   this._texture = texture;
@@ -99,12 +99,12 @@ CubeMapFace.prototype.copyFrom = function (options) {
   Check.typeOf.number.greaterThanOrEquals("yOffset", yOffset, 0);
   if (xOffset + source.width > this._size) {
     throw new DeveloperError(
-      "xOffset + options.source.width must be less than or equal to width."
+      "xOffset + options.source.width must be less than or equal to width.",
     );
   }
   if (yOffset + source.height > this._size) {
     throw new DeveloperError(
-      "yOffset + options.source.height must be less than or equal to height."
+      "yOffset + options.source.height must be less than or equal to height.",
     );
   }
   //>>includeEnd('debug');
@@ -133,7 +133,7 @@ CubeMapFace.prototype.copyFrom = function (options) {
     unpackAlignment = PixelFormat.alignmentInBytes(
       pixelFormat,
       pixelDatatype,
-      width
+      width,
     );
   }
   gl.pixelStorei(gl.UNPACK_ALIGNMENT, unpackAlignment);
@@ -143,7 +143,7 @@ CubeMapFace.prototype.copyFrom = function (options) {
   } else {
     gl.pixelStorei(
       gl.UNPACK_COLORSPACE_CONVERSION_WEBGL,
-      gl.BROWSER_DEFAULT_WEBGL
+      gl.BROWSER_DEFAULT_WEBGL,
     );
   }
 
@@ -161,7 +161,7 @@ CubeMapFace.prototype.copyFrom = function (options) {
             pixelFormat,
             pixelDatatype,
             size,
-            size
+            size,
           );
         }
         pixels = arrayBufferView;
@@ -180,7 +180,7 @@ CubeMapFace.prototype.copyFrom = function (options) {
         pixelFormat,
         pixelDatatype,
         size,
-        size
+        size,
       );
     }
     gl.texImage2D(
@@ -192,7 +192,7 @@ CubeMapFace.prototype.copyFrom = function (options) {
       0,
       pixelFormat,
       PixelDatatype.toWebGLConstant(pixelDatatype, this._context),
-      pixels
+      pixels,
     );
     this._initialized = true;
   }
@@ -208,7 +208,7 @@ CubeMapFace.prototype.copyFrom = function (options) {
           pixelFormat,
           pixelDatatype,
           width,
-          height
+          height,
         );
       }
       gl.texSubImage2D(
@@ -220,7 +220,7 @@ CubeMapFace.prototype.copyFrom = function (options) {
         height,
         pixelFormat,
         PixelDatatype.toWebGLConstant(pixelDatatype, this._context),
-        arrayBufferView
+        arrayBufferView,
       );
     } else {
       // Only valid for DOM-Element uploads
@@ -235,7 +235,7 @@ CubeMapFace.prototype.copyFrom = function (options) {
         yOffset,
         pixelFormat,
         PixelDatatype.toWebGLConstant(pixelDatatype, this._context),
-        source
+        source,
       );
     }
   }
@@ -245,25 +245,22 @@ CubeMapFace.prototype.copyFrom = function (options) {
 
 /**
  * Copies texels from the framebuffer to the cubemap's face.
- *
  * @param {number} [xOffset=0] An offset in the x direction in the cubemap where copying begins.
  * @param {number} [yOffset=0] An offset in the y direction in the cubemap where copying begins.
  * @param {number} [framebufferXOffset=0] An offset in the x direction in the framebuffer where copying begins from.
  * @param {number} [framebufferYOffset=0] An offset in the y direction in the framebuffer where copying begins from.
  * @param {number} [width=CubeMap's width] The width of the subimage to copy.
  * @param {number} [height=CubeMap's height] The height of the subimage to copy.
- *
- * @exception {DeveloperError} Cannot call copyFromFramebuffer when the texture pixel data type is FLOAT.
- * @exception {DeveloperError} Cannot call copyFromFramebuffer when the texture pixel data type is HALF_FLOAT.
- * @exception {DeveloperError} This CubeMap was destroyed, i.e., destroy() was called.
- * @exception {DeveloperError} xOffset must be greater than or equal to zero.
- * @exception {DeveloperError} yOffset must be greater than or equal to zero.
- * @exception {DeveloperError} framebufferXOffset must be greater than or equal to zero.
- * @exception {DeveloperError} framebufferYOffset must be greater than or equal to zero.
- * @exception {DeveloperError} xOffset + source.width must be less than or equal to width.
- * @exception {DeveloperError} yOffset + source.height must be less than or equal to height.
- * @exception {DeveloperError} This CubeMap was destroyed, i.e., destroy() was called.
- *
+ * @throws {DeveloperError} Cannot call copyFromFramebuffer when the texture pixel data type is FLOAT.
+ * @throws {DeveloperError} Cannot call copyFromFramebuffer when the texture pixel data type is HALF_FLOAT.
+ * @throws {DeveloperError} This CubeMap was destroyed, i.e., destroy() was called.
+ * @throws {DeveloperError} xOffset must be greater than or equal to zero.
+ * @throws {DeveloperError} yOffset must be greater than or equal to zero.
+ * @throws {DeveloperError} framebufferXOffset must be greater than or equal to zero.
+ * @throws {DeveloperError} framebufferYOffset must be greater than or equal to zero.
+ * @throws {DeveloperError} xOffset + source.width must be less than or equal to width.
+ * @throws {DeveloperError} yOffset + source.height must be less than or equal to height.
+ * @throws {DeveloperError} This CubeMap was destroyed, i.e., destroy() was called.
  * @example
  * // Copy the framebuffer contents to the +x cube map face.
  * cubeMap.positiveX.copyFromFramebuffer();
@@ -274,7 +271,7 @@ CubeMapFace.prototype.copyFromFramebuffer = function (
   framebufferXOffset,
   framebufferYOffset,
   width,
-  height
+  height,
 ) {
   xOffset = defaultValue(xOffset, 0);
   yOffset = defaultValue(yOffset, 0);
@@ -289,31 +286,31 @@ CubeMapFace.prototype.copyFromFramebuffer = function (
   Check.typeOf.number.greaterThanOrEquals(
     "framebufferXOffset",
     framebufferXOffset,
-    0
+    0,
   );
   Check.typeOf.number.greaterThanOrEquals(
     "framebufferYOffset",
     framebufferYOffset,
-    0
+    0,
   );
   if (xOffset + width > this._size) {
     throw new DeveloperError(
-      "xOffset + source.width must be less than or equal to width."
+      "xOffset + source.width must be less than or equal to width.",
     );
   }
   if (yOffset + height > this._size) {
     throw new DeveloperError(
-      "yOffset + source.height must be less than or equal to height."
+      "yOffset + source.height must be less than or equal to height.",
     );
   }
   if (this._pixelDatatype === PixelDatatype.FLOAT) {
     throw new DeveloperError(
-      "Cannot call copyFromFramebuffer when the texture pixel data type is FLOAT."
+      "Cannot call copyFromFramebuffer when the texture pixel data type is FLOAT.",
     );
   }
   if (this._pixelDatatype === PixelDatatype.HALF_FLOAT) {
     throw new DeveloperError(
-      "Cannot call copyFromFramebuffer when the texture pixel data type is HALF_FLOAT."
+      "Cannot call copyFromFramebuffer when the texture pixel data type is HALF_FLOAT.",
     );
   }
   //>>includeEnd('debug');
@@ -331,7 +328,87 @@ CubeMapFace.prototype.copyFromFramebuffer = function (
     framebufferXOffset,
     framebufferYOffset,
     width,
-    height
+    height,
+  );
+  gl.bindTexture(target, null);
+  this._initialized = true;
+};
+
+/**
+ * Copies texels from the framebuffer to the cubemap's face mipmap.
+ * @param {number} [xOffset=0] An offset in the x direction in the framebuffer where copying begins from.
+ * @param {number} [yOffset=0] An offset in the y direction in the framebuffer where copying begins from.
+ * @param {number} [width=CubeMap's width] The width of the subimage to copy.
+ * @param {number} [height=CubeMap's height] The height of the subimage to copy.
+ * @param {number} [level=0] The level of detail. Level 0 is the base image level and level n is the n-th mipmap reduction level.
+ * @throws {DeveloperError} Cannot call copyFromFramebuffer when the texture pixel data type is FLOAT.
+ * @throws {DeveloperError} Cannot call copyFromFramebuffer when the texture pixel data type is HALF_FLOAT.
+ * @throws {DeveloperError} This CubeMap was destroyed, i.e., destroy() was called.
+ * @throws {DeveloperError} xOffset must be greater than or equal to zero.
+ * @throws {DeveloperError} yOffset must be greater than or equal to zero.
+ * @throws {DeveloperError} framebufferXOffset must be greater than or equal to zero.
+ * @throws {DeveloperError} framebufferYOffset must be greater than or equal to zero.
+ * @throws {DeveloperError} xOffset + source.width must be less than or equal to width.
+ * @throws {DeveloperError} yOffset + source.height must be less than or equal to height.
+ * @throws {DeveloperError} This CubeMap was destroyed, i.e., destroy() was called.
+ *
+ * @example
+ * // Copy the framebuffer contents to the +x cube map face.
+ * cubeMap.positiveX.copyFromFramebuffer();
+ */
+CubeMapFace.prototype.copyMipmapFromFramebuffer = function (
+  xOffset,
+  yOffset,
+  width,
+  height,
+  level,
+) {
+  xOffset = defaultValue(xOffset, 0);
+  yOffset = defaultValue(yOffset, 0);
+  width = defaultValue(width, this._size);
+  height = defaultValue(height, this._size);
+  level = defaultValue(level, 0);
+
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.number.greaterThanOrEquals("xOffset", xOffset, 0);
+  Check.typeOf.number.greaterThanOrEquals("yOffset", yOffset, 0);
+
+  if (xOffset + width > this._size) {
+    throw new DeveloperError(
+      "xOffset + source.width must be less than or equal to width.",
+    );
+  }
+  if (yOffset + height > this._size) {
+    throw new DeveloperError(
+      "yOffset + source.height must be less than or equal to height.",
+    );
+  }
+  if (this._pixelDatatype === PixelDatatype.FLOAT) {
+    throw new DeveloperError(
+      "Cannot call copyFromFramebuffer when the texture pixel data type is FLOAT.",
+    );
+  }
+  if (this._pixelDatatype === PixelDatatype.HALF_FLOAT) {
+    throw new DeveloperError(
+      "Cannot call copyFromFramebuffer when the texture pixel data type is HALF_FLOAT.",
+    );
+  }
+  //>>includeEnd('debug');
+
+  const gl = this._context._gl;
+  const target = this._textureTarget;
+
+  gl.activeTexture(gl.TEXTURE0);
+  gl.bindTexture(target, this._texture);
+  gl.copyTexImage2D(
+    this._targetFace,
+    level,
+    this._internalFormat,
+    xOffset,
+    yOffset,
+    width,
+    height,
+    0,
   );
   gl.bindTexture(target, null);
   this._initialized = true;