playcanvas 2.24.0-beta.32 → 2.24.0-beta.34

package/build/playcanvas/src/core/core.js

@@ -1,5 +1,5 @@
-const version = "2.24.0-beta.32";
-const revision = "3f0066f";
+const version = "2.24.0-beta.34";
+const revision = "eb5f1c2";
 function extend(target, ex) {
 	for (const prop in ex) {
 		const copy = ex[prop];

package/build/playcanvas/src/extras/input/controllers/orbit-controller.d.ts

@@ -3,6 +3,8 @@
  * view around the focus within {@link yawRange} and {@link pitchRange}, the first two `move`
  * components pan the focus point, and the third scales the distance within {@link zoomRange}.
  * Motion is smoothed with {@link rotateDamping}, {@link moveDamping} and {@link zoomDamping}.
+ * With {@link horizontalPan}, the pan moves the focus point across the ground instead of the
+ * plane of the view.
  *
  * @category Input
  * @alpha
@@ -42,6 +44,13 @@ export class OrbitController extends InputController {
      * The zoom damping. A higher value means more damping. A value of 0 means no damping.
      */
     zoomDamping: number;
+    /**
+     * Whether the pan moves the focus point across the horizontal plane, as when dragging a map,
+     * instead of across the plane of the view. The first two `move` components are then the
+     * distances to move the focus point to the right and forward, level with the ground, so the
+     * height of the focus point does not change. Default is false.
+     */
+    horizontalPan: boolean;
     set pitchRange(range: import("../../../index.js").Vec2);
     get pitchRange(): import("../../../index.js").Vec2;
     set yawRange(range: import("../../../index.js").Vec2);

package/build/playcanvas/src/extras/input/controllers/orbit-controller.js

@@ -15,6 +15,7 @@ class OrbitController extends InputController {
 	rotateDamping = 0.98;
 	moveDamping = 0.98;
 	zoomDamping = 0.98;
+	horizontalPan = false;
 	set pitchRange(range) {
 		this._targetRootPose.pitchRange.copy(range);
 		this._rootPose.copy(this._targetRootPose.rotate(Vec3.ZERO));
@@ -50,8 +51,13 @@ class OrbitController extends InputController {
 	}
 	update(frame, dt) {
 		const { move, rotate } = frame.read();
-		offset.set(move[0], move[1], 0);
-		rotation.setFromEulerAngles(this._rootPose.angles).transformVector(offset, offset);
+		if (this.horizontalPan) {
+			offset.set(move[0], 0, -move[1]);
+			rotation.setFromEulerAngles(0, this._rootPose.angles.y, 0).transformVector(offset, offset);
+		} else {
+			offset.set(move[0], move[1], 0);
+			rotation.setFromEulerAngles(this._rootPose.angles).transformVector(offset, offset);
+		}
 		this._targetRootPose.move(offset);
 		const { z: dist } = this._targetChildPose.position;
 		this._targetChildPose.move(offset.set(0, 0, dist * (1 + move[2]) - dist));

package/build/playcanvas/src/framework/components/gsplat/component.d.ts

@@ -29,13 +29,13 @@
  * - [Billions of Splats](https://playcanvas.github.io/#/gaussian-splatting/billions)
  * - [Downtown Streaming](https://playcanvas.github.io/#/gaussian-splatting/downtown)
  * - [Global Sorting](https://playcanvas.github.io/#/gaussian-splatting/global-sorting)
- * - [LOD Instances](https://playcanvas.github.io/#/gaussian-splatting/lod-instances)
+ * - [LOD Instances](https://playcanvas.github.io/#/gaussian-splatting/streamed-instances)
  * - [Multi-Splat](https://playcanvas.github.io/#/gaussian-splatting/multi-splat)
  * - [Multi-View](https://playcanvas.github.io/#/gaussian-splatting/multi-view)
  * - [Picking](https://playcanvas.github.io/#/gaussian-splatting/picking)
- * - [Reveal Effect](https://playcanvas.github.io/#/gaussian-splatting/reveal)
- * - [Shader Effects](https://playcanvas.github.io/#/gaussian-splatting/shader-effects)
- * - [Spherical Harmonics](https://playcanvas.github.io/#/gaussian-splatting/spherical-harmonics)
+ * - [Reveal Effect](https://playcanvas.github.io/#/gaussian-splatting-fx/reveal)
+ * - [Shader Effects](https://playcanvas.github.io/#/gaussian-splatting-fx/shader-effects)
+ * - [Spherical Harmonics](https://playcanvas.github.io/#/gaussian-splatting/simple-sh)
  * - [Streamed LCC2](https://playcanvas.github.io/#/gaussian-splatting/streamed-lcc2)
  * - [Streamed SOG](https://playcanvas.github.io/#/gaussian-splatting/streamed-sog)
  * - [Streamed SOG with Spherical Harmonics](https://playcanvas.github.io/#/gaussian-splatting/streamed-sog-sh)

package/build/playcanvas/src/framework/components/particle-system/component.d.ts

@@ -39,11 +39,11 @@ export const _properties: string[];
  *
  * Relevant Engine API examples:
  *
- * - [Particle Animated Index](https://playcanvas.github.io/#/graphics/particles-anim-index)
- * - [Particle Mesh](https://playcanvas.github.io/#/graphics/particles-mesh)
- * - [Particle Random Sprites](https://playcanvas.github.io/#/graphics/particles-random-sprites)
- * - [Particle Snow](https://playcanvas.github.io/#/graphics/particles-snow)
- * - [Particle Spark](https://playcanvas.github.io/#/graphics/particles-spark)
+ * - [Particle Animated Index](https://playcanvas.github.io/#/particles/anim-index)
+ * - [Particle Mesh](https://playcanvas.github.io/#/particles/mesh)
+ * - [Particle Random Sprites](https://playcanvas.github.io/#/particles/random-sprites)
+ * - [Particle Snow](https://playcanvas.github.io/#/particles/snow)
+ * - [Particle Spark](https://playcanvas.github.io/#/particles/spark)
  * - [Particles in a user interface](https://playcanvas.github.io/#/user-interface/particle-system)
  *
  * @hideconstructor

package/build/playcanvas/src/framework/parsers/sog-bundle.js

@@ -159,7 +159,14 @@ class SogBundleParser {
 				callback(`Error parsing meta.json: ${err}`);
 				return;
 			}
-			const filenames = ["means", "scales", "quats", "sh0", "shN"].map((key) => meta[key]?.files ?? []).flat();
+			if (meta.version !== void 0 && meta.version !== 2 && meta.version !== 3) {
+				callback(`Error loading gsplat: unsupported SOG version ${meta.version} in ${url.original}`);
+				return;
+			}
+			const filenames = [
+				...["means", "scales", "quats", "sh0", "shN"].map((key) => meta[key]?.files ?? []).flat(),
+				...(meta.blind ?? []).map((t) => t.files[0])
+			];
 			const promises = [];
 			for (const filename of filenames) {
 				const file = files.find((f) => f.filename === filename);
@@ -194,7 +201,7 @@ class SogBundleParser {
 				promises.push(promise);
 			}
 			Object.values(textures).forEach((t) => this.app.assets.load(t));
-			await Promise.allSettled(promises);
+			const results = await Promise.allSettled(promises);
 			if (this._shouldAbort(asset, unloaded)) {
 				Object.values(textures).forEach((t) => {
 					assets.remove(t);
@@ -203,6 +210,15 @@ class SogBundleParser {
 				callback(null, null);
 				return;
 			}
+			const failed = results.findIndex((r) => r.status === "rejected");
+			if (failed !== -1) {
+				Object.values(textures).forEach((t) => {
+					assets.remove(t);
+					t.unload();
+				});
+				callback(`Error loading gsplat: failed to load ${filenames[failed]} in ${url.original}: ${results[failed].reason}`);
+				return;
+			}
 			Object.values(textures).forEach((t) => {
 				if (t.file) {
 					t.file.contents = null;
@@ -215,11 +231,12 @@ class SogBundleParser {
 			data.numSplats = meta.count;
 			data.means_l = textures[meta.means.files[0]].resource;
 			data.means_u = textures[meta.means.files[1]].resource;
-			data.quats = textures[meta.quats.files[0]].resource;
+			data.quats = meta.quats ? textures[meta.quats.files[0]].resource : null;
 			data.scales = textures[meta.scales.files[0]].resource;
 			data.sh0 = textures[meta.sh0.files[0]].resource;
 			data.sh_centroids = textures[meta.shN?.files[0]]?.resource;
 			data.sh_labels = textures[meta.shN?.files[1]]?.resource;
+			data.blind = (meta.blind ?? []).map((t) => textures[t.files[0]].resource);
 			data.shBands = GSplatSogData.calcBands(data.sh_centroids?.width);
 			if (!decompress) {
 				if (this._shouldAbort(asset, unloaded)) {

package/build/playcanvas/src/framework/parsers/sog.js

@@ -81,16 +81,19 @@ class SogParser {
 	}
 	async loadTextures(url, callback, asset, meta) {
 		const gsplatCentersEnabledAtLoad = this.app.scene?.gsplatCentersEnabled !== false;
-		if (meta.version !== 2) {
+		if (meta.version === void 0) {
 			meta = upgradeMeta(meta);
+		} else if (meta.version !== 2 && meta.version !== 3) {
+			callback(`Error loading gsplat: unsupported SOG version ${meta.version} in ${url.original}`);
+			return;
 		}
 		const { assets } = this.app;
-		const subs = ["means", "quats", "scales", "sh0", "shN"];
+		const subs = ["means", "quats", "scales", "sh0", "shN", "blind"];
 		const textures = {};
 		const promises = [];
 		const base = window.document?.baseURI ?? window.location.href;
 		subs.forEach((sub) => {
-			const files = meta[sub]?.files ?? [];
+			const files = sub === "blind" ? (meta.blind ?? []).map((t) => t.files[0]) : meta[sub]?.files ?? [];
 			textures[sub] = files.map((filename) => {
 				const texture = new Asset(filename, "texture", {
 					url: asset.options?.mapUrl?.(filename) ?? new URL(filename, new URL(url.load, base).toString()).toString(),
@@ -125,7 +128,7 @@ class SogParser {
 		});
 		combineProgress(asset, textureAssets);
 		textureAssets.forEach((t) => assets.load(t));
-		await Promise.allSettled(promises);
+		const results = await Promise.allSettled(promises);
 		if (this._shouldAbort(asset, unloaded)) {
 			textureAssets.forEach((t) => {
 				assets.remove(t);
@@ -134,17 +137,27 @@ class SogParser {
 			callback(null, null);
 			return;
 		}
+		const failed = results.findIndex((r) => r.status === "rejected");
+		if (failed !== -1) {
+			textureAssets.forEach((t) => {
+				assets.remove(t);
+				t.unload();
+			});
+			callback(`Error loading gsplat: failed to load ${textureAssets[failed].file.filename} in ${url.original}: ${results[failed].reason}`);
+			return;
+		}
 		const data = new GSplatSogData();
 		data.url = url.original;
 		data.meta = meta;
 		data.numSplats = meta.count;
 		data.means_l = textures.means[0].resource;
 		data.means_u = textures.means[1].resource;
-		data.quats = textures.quats[0].resource;
+		data.quats = textures.quats[0]?.resource ?? null;
 		data.scales = textures.scales[0].resource;
 		data.sh0 = textures.sh0[0].resource;
 		data.sh_centroids = textures.shN?.[0]?.resource;
 		data.sh_labels = textures.shN?.[1]?.resource;
+		data.blind = textures.blind.map((t) => t.resource);
 		data.shBands = GSplatSogData.calcBands(data.sh_centroids?.width);
 		const decompress = asset.data?.decompress;
 		if (!decompress) {
@@ -180,8 +193,11 @@ class SogParser {
 		callback(null, resource);
 	}
 	load(url, callback, asset) {
+		const loadTextures = (meta) => {
+			this.loadTextures(url, callback, asset, meta).catch((err) => callback(`Error loading gsplat: ${url.original} [${err}]`));
+		};
 		if (asset.data?.means) {
-			this.loadTextures(url, callback, asset, asset.data);
+			loadTextures(asset.data);
 		} else {
 			if (typeof url === "string") {
 				url = {
@@ -200,7 +216,7 @@ class SogParser {
 					return;
 				}
 				if (!err) {
-					this.loadTextures(url, callback, asset, meta);
+					loadTextures(meta);
 				} else {
 					callback(`Error loading gsplat meta: ${url.original} [${err}]`);
 				}

package/build/playcanvas/src/scene/gsplat/gsplat-data.d.ts

@@ -28,6 +28,13 @@ export class GSplatData {
      * @type {boolean}
      */
     activated: boolean;
+    /**
+     * Application-defined data stored with the splat file, as in glTF's `extras`: the `extras`
+     * value of a decompressed SOG's meta.json. Undefined when the source has none.
+     *
+     * @type {*}
+     */
+    extras: any;
     getProp(name: any, elementName?: string): import("../../framework/parsers/ply.js").DataType;
     getElement(name: any): PlyElement;
     addProp(name: any, storage: any): void;

package/build/playcanvas/src/scene/gsplat/gsplat-data.js

@@ -69,6 +69,7 @@ class GSplatData {
 	numSplats;
 	comments;
 	activated = false;
+	extras;
 	constructor(elements, comments = []) {
 		this.elements = elements;
 		this.numSplats = this.getElement("vertex").count;

package/build/playcanvas/src/scene/gsplat/gsplat-resource-base.d.ts

@@ -171,6 +171,14 @@ export class GSplatResourceBase {
      * @ignore
      */
     get supportsWorkBufferGeometry(): boolean;
+    /**
+     * Application-defined data stored with the splat file, as in glTF's `extras`: the `extras`
+     * value of a SOG's meta.json. The engine attaches no meaning to it. Undefined when the file
+     * has none, and for formats that cannot carry it.
+     *
+     * @type {*}
+     */
+    get extras(): any;
     /**
      * Gets the number of splats in the resource.
      *

package/build/playcanvas/src/scene/gsplat/gsplat-resource-base.js

@@ -77,6 +77,9 @@ class GSplatResourceBase {
 	get supportsWorkBufferGeometry() {
 		return false;
 	}
+	get extras() {
+		return void 0;
+	}
 	static createMesh(device) {
 		const splatInstanceSize = GSplatResourceBase.instanceSize;
 		const meshPositions = new Float32Array(12 * splatInstanceSize);

package/build/playcanvas/src/scene/gsplat/gsplat-resource.d.ts

@@ -22,7 +22,8 @@ export class GSplatResource extends GSplatResourceBase {
     /**
      * Updates pixel data of splatColor texture based on the supplied color components and opacity.
      * Assumes that the texture is using an RGBA format where RGB are color components influenced
-     * by SH spherical harmonics and A is opacity after a sigmoid transformation.
+     * by SH spherical harmonics and A is opacity after a sigmoid transformation, plus the optional
+     * `opacity_excess` property: the opacity above 1 that merged (decimated) gaussians carry.
      *
      * @param {GSplatData} gsplatData - The source data
      * @ignore

package/build/playcanvas/src/scene/gsplat/gsplat-resource.js

@@ -57,6 +57,9 @@ class GSplatResource extends GSplatResourceBase {
 	configureMaterialDefines(defines) {
 		defines.set("SH_BANDS", this.shBands);
 	}
+	get extras() {
+		return this.gsplatData.extras;
+	}
 	updateColorData(gsplatData) {
 		const texture = this.streams.getTexture("splatColor");
 		if (!texture) {
@@ -68,13 +71,17 @@ class GSplatResource extends GSplatResourceBase {
 		const cg = gsplatData.getProp("f_dc_1");
 		const cb = gsplatData.getProp("f_dc_2");
 		const ca = gsplatData.getProp("opacity");
+		const excess = gsplatData.getProp("opacity_excess");
 		const activated = gsplatData.activated;
 		const SH_C0 = 0.28209479177387814;
 		for (let i = 0; i < this.numSplats; ++i) {
 			const r = cr[i] * SH_C0 + 0.5;
 			const g = cg[i] * SH_C0 + 0.5;
 			const b = cb[i] * SH_C0 + 0.5;
-			const a = activated ? ca[i] : 1 / (1 + Math.exp(-ca[i]));
+			let a = activated ? ca[i] : 1 / (1 + Math.exp(-ca[i]));
+			if (excess && excess[i] > 0) {
+				a = Math.min(a + excess[i], 1.5625);
+			}
 			data[i * 4 + 0] = float2Half(r);
 			data[i * 4 + 1] = float2Half(g);
 			data[i * 4 + 2] = float2Half(b);

package/build/playcanvas/src/scene/gsplat/gsplat-sog-blind.d.ts

@@ -0,0 +1,55 @@
+export type BlindField = {
+    /**
+     * - Index of the field's texture in `meta.blind`.
+     */
+    texture: number;
+    /**
+     * - The field name.
+     */
+    name: string;
+    /**
+     * - Shader identifier suffix derived from the name.
+     */
+    id: string;
+    /**
+     * - The encoding.
+     */
+    type: string;
+    /**
+     * - Index of the field's first byte in the texel (0 = R).
+     */
+    offset: number;
+    /**
+     * - Number of bytes.
+     */
+    bytes: number;
+    /**
+     * - Value of the smallest code (unorm encodings).
+     */
+    min: number;
+    /**
+     * - Value of the largest code (unorm encodings).
+     */
+    max: number;
+};
+/**
+ * Shader code for the blind field accessors, appended to the SOG read code: the
+ * `gsplatSogBlindVS` decoding helpers, then one accessor per field from the `sogBlindField`
+ * template. The textures are declared as streams `blind0`, `blind1`, ... whose generated
+ * `loadBlind<i>()` returns the RGBA8 texel as normalized floats.
+ *
+ * @param {BlindField[]} fields - The fields, from {@link parseBlindFields}.
+ * @param {boolean} wgsl - Generate WGSL (else GLSL).
+ * @returns {string} The accessor functions, empty when there are no fields.
+ */
+export function blindAccessors(fields: BlindField[], wgsl: boolean): string;
+/**
+ * The fields of a SOG meta's blind textures, each with its texture index, byte offset and shader
+ * identifier. Fields are packed in order, so each starts where the previous field of its texture
+ * ended. The data is assumed valid, as the tools writing it check it; debug builds report
+ * problems.
+ *
+ * @param {object} meta - The SOG meta.json.
+ * @returns {BlindField[]} The fields.
+ */
+export function parseBlindFields(meta: object): BlindField[];

package/build/playcanvas/src/scene/gsplat/gsplat-sog-blind.js

@@ -0,0 +1,55 @@
+import glslBlindField from "../shader-lib/glsl/chunks/gsplat/vert/formats/sogBlindField.js";
+import wgslBlindField from "../shader-lib/wgsl/chunks/gsplat/vert/formats/sogBlindField.js";
+const BLIND_TYPE_BYTES = { u8: 1, u16: 2, u24: 3, u32: 4, f16: 2, f32: 4, unorm8: 1, unorm16: 2 };
+const DEFAULT_RANGE = [0, 1];
+const isIntegerType = (type) => type[0] === "u" && !type.startsWith("unorm");
+const RE_ID = /\{id\}/g;
+const RE_RETURN_TYPE = /\{returnType\}/g;
+const RE_TEXTURE = /\{texture\}/g;
+const RE_OFFSET = /\{offset\}/g;
+const RE_BYTES = /\{bytes\}/g;
+const RE_DECODE = /\{decode\}/g;
+const blindFieldId = (name) => name.replace(/\W/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
+const parseBlindFields = (meta) => {
+	const fields = [];
+	(meta.blind ?? []).forEach((texture, t) => {
+		let offset = 0;
+		for (const f of texture.fields) {
+			const bytes = BLIND_TYPE_BYTES[f.type];
+			const [min, max] = f.range ?? DEFAULT_RANGE;
+			fields.push({ texture: t, name: f.name, id: blindFieldId(f.name), type: f.type, offset, bytes, min, max });
+			offset += bytes;
+		}
+	});
+	return fields;
+};
+const floatLiteral = (v) => {
+	const s = String(v);
+	return /[.e]/i.test(s) ? s : `${s}.0`;
+};
+const blindAccessors = (fields, wgsl) => {
+	if (!fields.length) {
+		return "";
+	}
+	const template = wgsl ? wgslBlindField : glslBlindField;
+	const accessors = fields.map((f) => {
+		const integer = isIntegerType(f.type);
+		let decode = "bits";
+		if (f.type === "f16") {
+			decode = "sogBlindF16(bits)";
+		} else if (f.type === "f32") {
+			decode = "sogBlindF32(bits)";
+		} else if (!integer) {
+			const steps = f.type === "unorm8" ? "255.0" : "65535.0";
+			decode = `sogBlindUnorm(bits, ${steps}, ${floatLiteral(f.min)}, ${floatLiteral(f.max)})`;
+		}
+		return template.replace(RE_ID, f.id).replace(RE_RETURN_TYPE, integer ? wgsl ? "u32" : "uint" : wgsl ? "f32" : "float").replace(RE_TEXTURE, String(f.texture)).replace(RE_OFFSET, String(f.offset)).replace(RE_BYTES, String(f.bytes)).replace(RE_DECODE, decode);
+	});
+	return `
+#include "gsplatSogBlindVS"
+${accessors.join("")}`;
+};
+export {
+	blindAccessors,
+	parseBlindFields
+};

package/build/playcanvas/src/scene/gsplat/gsplat-sog-data.d.ts

@@ -10,7 +10,13 @@ export class GSplatSogData {
     sh_centroids: any;
     sh_labels: any;
     /**
-     * V2-only codebook LUT (256x1 RGBA32F): .r = scales, .g = sh0, .b = shN, .a unused.
+     * V3 per-gaussian blind data textures (RGBA8), one per `meta.blind` entry.
+     *
+     * @type {Texture[]}
+     */
+    blind: Texture[];
+    /**
+     * V2/V3 codebook LUT (256x1 RGBA32F): .r = scales, .g = sh0, .b = shN, .a unused.
      * Built from meta codebooks in prepareCodebook(). Null for V1 assets.
      *
      * @type {Texture|null}
@@ -49,8 +55,8 @@ export class GSplatSogData {
     decompress(): Promise<GSplatData>;
     generateCenters(): Promise<void>;
     /**
-     * Creates the V2 codebook LUT texture. Packs the three 256-entry scalar codebooks
-     * (scales, sh0, shN) into a single 256x1 RGBA32F texture:
+     * Creates the V2/V3 codebook LUT texture. Packs the 256-entry scalar codebooks into a
+     * single 256x1 RGBA32F texture:
      * - .r = scales codebook
      * - .g = sh0 codebook
      * - .b = shN codebook