diff --git a/examples/src/examples/graphics/integer-textures.example.mjs b/examples/src/examples/graphics/integer-textures.example.mjs index a6bcd6738e4..7cb67974f50 100644 --- a/examples/src/examples/graphics/integer-textures.example.mjs +++ b/examples/src/examples/graphics/integer-textures.example.mjs @@ -232,6 +232,7 @@ assetListLoader.load(() => { const gameScreenMaterial = gameScreen.render.material; gameScreenMaterial.diffuse = pc.Color.BLACK; gameScreenMaterial.emissiveMap = outputTexture; + gameScreenMaterial.emissive = pc.Color.WHITE; gameScreenMaterial.useLighting = false; gameScreenMaterial.update(); app.root.addChild(gameScreen); diff --git a/examples/src/examples/graphics/mesh-decals.example.mjs b/examples/src/examples/graphics/mesh-decals.example.mjs index ae277e622a3..71afae68cfb 100644 --- a/examples/src/examples/graphics/mesh-decals.example.mjs +++ b/examples/src/examples/graphics/mesh-decals.example.mjs @@ -200,6 +200,7 @@ assetListLoader.load(() => { material.blendType = pc.BLEND_ADDITIVEALPHA; // additive alpha blend material.depthWrite = false; // optimization - no need to write to depth buffer, as decals are part of the ground plane material.emissiveMap = assets.heart.resource; + material.emissive = pc.Color.WHITE; material.opacityMap = assets.heart.resource; material.depthBias = -0.1; // depth biases to avoid z-fighting with ground plane material.slopeDepthBias = -0.1; diff --git a/examples/src/examples/graphics/painter.example.mjs b/examples/src/examples/graphics/painter.example.mjs index befda84658b..647a864f10d 100644 --- a/examples/src/examples/graphics/painter.example.mjs +++ b/examples/src/examples/graphics/painter.example.mjs @@ -54,7 +54,7 @@ app.on('destroy', () => { */ function createPrimitive(primitiveType, position, scale, layer, material) { // create primitive - const primitive = new pc.Entity(); + const primitive = new pc.Entity(`Brush-${primitiveType}`); primitive.addComponent('render', { type: primitiveType, layers: layer, @@ -91,7 +91,6 @@ app.scene.layers.insert(paintLayer, 0); // create a material we use for the paint brush - it uses emissive color to control its color, which is assigned later const brushMaterial = new pc.StandardMaterial(); -brushMaterial.emissiveTint = true; brushMaterial.useLighting = false; brushMaterial.update(); @@ -141,7 +140,9 @@ app.root.addChild(camera); // material used to add render target into the world const material = new pc.StandardMaterial(); +material.name = 'EmissiveMaterial'; material.emissiveMap = texture; +material.emissive = pc.Color.WHITE; material.useLighting = false; material.update(); diff --git a/examples/src/examples/graphics/reflection-box.example.mjs b/examples/src/examples/graphics/reflection-box.example.mjs index 87d574ffc69..55a88a193b1 100644 --- a/examples/src/examples/graphics/reflection-box.example.mjs +++ b/examples/src/examples/graphics/reflection-box.example.mjs @@ -162,6 +162,7 @@ assetListLoader.load(() => { const screenMaterial = new pc.StandardMaterial(); screenMaterial.useLighting = false; screenMaterial.emissiveMap = videoTexture; + screenMaterial.emissive = pc.Color.WHITE; screenMaterial.update(); /** diff --git a/examples/src/examples/graphics/render-to-texture.example.mjs b/examples/src/examples/graphics/render-to-texture.example.mjs index 9baa1e01fa1..8ea4e0cd245 100644 --- a/examples/src/examples/graphics/render-to-texture.example.mjs +++ b/examples/src/examples/graphics/render-to-texture.example.mjs @@ -247,9 +247,11 @@ assetListLoader.load(() => { tv.setLocalEulerAngles(90, 0, 0); tv.render.castShadows = false; tv.render.receiveShadows = false; + /** @type {pc.StandardMaterial} */ const material = tv.render.material; material.emissiveMap = texture; // assign the rendered texture as an emissive texture + material.emissive = pc.Color.WHITE; material.update(); // setup skydome, use top mipmap level of cubemap (full resolution) diff --git a/examples/src/examples/graphics/texture-basis.example.mjs b/examples/src/examples/graphics/texture-basis.example.mjs index 7ca438c5f50..164e488ce30 100644 --- a/examples/src/examples/graphics/texture-basis.example.mjs +++ b/examples/src/examples/graphics/texture-basis.example.mjs @@ -78,7 +78,6 @@ assetListLoader.load(() => { // Construct material const material = new pc.StandardMaterial(); material.useMetalness = true; - material.diffuse = new pc.Color(0.3, 0.3, 0.3); material.gloss = 0.8; material.metalness = 0.7; material.diffuseMap = assets.color.resource; diff --git a/examples/src/examples/graphics/video-texture.example.mjs b/examples/src/examples/graphics/video-texture.example.mjs index b98813250a5..96c69bbbc45 100644 --- a/examples/src/examples/graphics/video-texture.example.mjs +++ b/examples/src/examples/graphics/video-texture.example.mjs @@ -114,6 +114,7 @@ assetListLoader.load(() => { const material = new pc.StandardMaterial(); material.useLighting = false; material.emissiveMap = videoTexture; + material.emissive = pc.Color.WHITE; material.update(); // set the material on the screen mesh diff --git a/package-lock.json b/package-lock.json index c7a9d9c9e80..cd3f7bbdf14 100644 --- a/package-lock.json +++ b/package-lock.json @@ -42,9 +42,9 @@ "rollup-plugin-visualizer": "^5.12.0", "serve": "^14.2.2", "sinon": "^17.0.1", - "typedoc": "^0.25.13", - "typedoc-plugin-mdn-links": "^3.1.22", - "typescript": "^5.4.5", + "typedoc": "^0.26.3", + "typedoc-plugin-mdn-links": "^3.2.2", + "typescript": "^5.5.3", "xhr2": "^0.2.1" }, "engines": { @@ -2392,6 +2392,12 @@ "win32" ] }, + "node_modules/@shikijs/core": { + "version": "1.10.1", + "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-1.10.1.tgz", + "integrity": "sha512-qdiJS5a/QGCff7VUFIqd0hDdWly9rDp8lhVmXVrS11aazX8LOTRLHAXkkEeONNsS43EcCd7gax9LLoOz4vlFQA==", + "dev": true + }, "node_modules/@sinonjs/commons": { "version": "3.0.1", "resolved": "https://registry.npmjs.org/@sinonjs/commons/-/commons-3.0.1.tgz", @@ -2621,12 +2627,6 @@ "node": ">=8" } }, - "node_modules/ansi-sequence-parser": { - "version": "1.1.1", - "resolved": "https://registry.npmjs.org/ansi-sequence-parser/-/ansi-sequence-parser-1.1.1.tgz", - "integrity": "sha512-vJXt3yiaUL4UU546s3rPXlsry/RnM730G1+HkpKE012AN0sx1eOrxSu95oKDIonskeLTijMgqWZ3uDEe3NFvyg==", - "dev": true - }, "node_modules/ansi-styles": { "version": "3.2.1", "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.1.tgz", @@ -6030,12 +6030,6 @@ "node": ">=6" } }, - "node_modules/jsonc-parser": { - "version": "3.2.1", - "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.2.1.tgz", - "integrity": "sha512-AilxAyFOAcK5wA1+LeaySVBrHsGQvUFCDWXKpZjzaL0PqW+xfBOttn8GNtWKFWqneyMZj41MWF9Kl6iPWLwgOA==", - "dev": true - }, "node_modules/jsonfile": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz", @@ -6274,6 +6268,15 @@ "node": ">= 0.8.0" } }, + "node_modules/linkify-it": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-5.0.0.tgz", + "integrity": "sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==", + "dev": true, + "dependencies": { + "uc.micro": "^2.0.0" + } + }, "node_modules/locate-path": { "version": "6.0.0", "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz", @@ -6499,18 +6502,29 @@ "integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==", "dev": true }, - "node_modules/marked": { - "version": "4.3.0", - "resolved": "https://registry.npmjs.org/marked/-/marked-4.3.0.tgz", - "integrity": "sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==", + "node_modules/markdown-it": { + "version": "14.1.0", + "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.1.0.tgz", + "integrity": "sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg==", "dev": true, - "bin": { - "marked": "bin/marked.js" + "dependencies": { + "argparse": "^2.0.1", + "entities": "^4.4.0", + "linkify-it": "^5.0.0", + "mdurl": "^2.0.0", + "punycode.js": "^2.3.1", + "uc.micro": "^2.1.0" }, - "engines": { - "node": ">= 12" + "bin": { + "markdown-it": "bin/markdown-it.mjs" } }, + "node_modules/mdurl": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-2.0.0.tgz", + "integrity": "sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==", + "dev": true + }, "node_modules/media-typer": { "version": "0.3.0", "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-0.3.0.tgz", @@ -7402,6 +7416,15 @@ "integrity": "sha512-jmYNElW7yvO7TV33CjSmvSiE2yco3bV2czu/OzDKdMNVZQWfxCblURLhf+47syQRBntjfLdd/H0egrzIG+oaFQ==", "dev": true }, + "node_modules/punycode.js": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz", + "integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==", + "dev": true, + "engines": { + "node": ">=6" + } + }, "node_modules/qjobs": { "version": "1.2.0", "resolved": "https://registry.npmjs.org/qjobs/-/qjobs-1.2.0.tgz", @@ -8143,15 +8166,12 @@ } }, "node_modules/shiki": { - "version": "0.14.7", - "resolved": "https://registry.npmjs.org/shiki/-/shiki-0.14.7.tgz", - "integrity": "sha512-dNPAPrxSc87ua2sKJ3H5dQ/6ZaY8RNnaAqK+t0eG7p0Soi2ydiqbGOTaZCqaYvA/uZYfS1LJnemt3Q+mSfcPCg==", + "version": "1.10.1", + "resolved": "https://registry.npmjs.org/shiki/-/shiki-1.10.1.tgz", + "integrity": "sha512-uafV7WCgN4YYrccH6yxpnps6k38sSTlFRrwc4jycWmhWxJIm9dPrk+XkY1hZ2t0I7jmacMNb15Lf2fspa/Y3lg==", "dev": true, "dependencies": { - "ansi-sequence-parser": "^1.1.0", - "jsonc-parser": "^3.2.0", - "vscode-oniguruma": "^1.7.0", - "vscode-textmate": "^8.0.0" + "@shikijs/core": "1.10.1" } }, "node_modules/side-channel": { @@ -8820,33 +8840,34 @@ } }, "node_modules/typedoc": { - "version": "0.25.13", - "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.25.13.tgz", - "integrity": "sha512-pQqiwiJ+Z4pigfOnnysObszLiU3mVLWAExSPf+Mu06G/qsc3wzbuM56SZQvONhHLncLUhYzOVkjFFpFfL5AzhQ==", + "version": "0.26.3", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.26.3.tgz", + "integrity": "sha512-6d2Sw9disvvpdk4K7VNjKr5/3hzijtfQVHRthhDqJgnhMHy1wQz4yPMJVKXElvnZhFr0nkzo+GzjXDTRV5yLpg==", "dev": true, "dependencies": { "lunr": "^2.3.9", - "marked": "^4.3.0", - "minimatch": "^9.0.3", - "shiki": "^0.14.7" + "markdown-it": "^14.1.0", + "minimatch": "^9.0.5", + "shiki": "^1.9.1", + "yaml": "^2.4.5" }, "bin": { "typedoc": "bin/typedoc" }, "engines": { - "node": ">= 16" + "node": ">= 18" }, "peerDependencies": { - "typescript": "4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x" + "typescript": "4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x || 5.5.x" } }, "node_modules/typedoc-plugin-mdn-links": { - "version": "3.1.22", - "resolved": "https://registry.npmjs.org/typedoc-plugin-mdn-links/-/typedoc-plugin-mdn-links-3.1.22.tgz", - "integrity": "sha512-ZvwMN8u8FntDag4Pa403DbSCHXbw6Dxj5Tq65tPx6QvxAN6RCyWG63JATnO3GWjgWVWL6Mcnqi7gswHU1BYSAA==", + "version": "3.2.2", + "resolved": "https://registry.npmjs.org/typedoc-plugin-mdn-links/-/typedoc-plugin-mdn-links-3.2.2.tgz", + "integrity": "sha512-3xlxS32c29Mey5SxqgCEF1lYYceQyoILhJM0Ewh2ISW8Ql3NzhC3SGpuvft4YtzpZIdB+YR7aIMkhlDquA0M+Q==", "dev": true, "peerDependencies": { - "typedoc": ">= 0.23.14 || 0.24.x || 0.25.x" + "typedoc": ">= 0.23.14 || 0.24.x || 0.25.x || 0.26.x" } }, "node_modules/typedoc/node_modules/brace-expansion": { @@ -8859,9 +8880,9 @@ } }, "node_modules/typedoc/node_modules/minimatch": { - "version": "9.0.3", - "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.3.tgz", - "integrity": "sha512-RHiac9mvaRw0x3AYRgDC1CxAP7HTcNrrECeA8YYJeWnpo+2Q5CegtZjaotWTWxDG3UeGA1coE05iH1mPjT/2mg==", + "version": "9.0.5", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.5.tgz", + "integrity": "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==", "dev": true, "dependencies": { "brace-expansion": "^2.0.1" @@ -8874,9 +8895,9 @@ } }, "node_modules/typescript": { - "version": "5.4.5", - "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.4.5.tgz", - "integrity": "sha512-vcI4UpRgg81oIRUFwR0WSIHKt11nJ7SAVlYNIu+QpqeyXP+gpQJy/Z4+F0aGxSE4MqwjyXvW/TzgkLAx2AGHwQ==", + "version": "5.5.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.5.3.tgz", + "integrity": "sha512-/hreyEujaB0w76zKo6717l3L0o/qEUtRgdvUBvlkhoWeOVMjMuHNHk0BRBzikzuGDqNmPQbg5ifMEqsHLiIUcQ==", "dev": true, "bin": { "tsc": "bin/tsc", @@ -8909,6 +8930,12 @@ "node": "*" } }, + "node_modules/uc.micro": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-2.1.0.tgz", + "integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==", + "dev": true + }, "node_modules/unbox-primitive": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/unbox-primitive/-/unbox-primitive-1.0.2.tgz", @@ -9097,18 +9124,6 @@ "node": ">=0.10.0" } }, - "node_modules/vscode-oniguruma": { - "version": "1.7.0", - "resolved": "https://registry.npmjs.org/vscode-oniguruma/-/vscode-oniguruma-1.7.0.tgz", - "integrity": "sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA==", - "dev": true - }, - "node_modules/vscode-textmate": { - "version": "8.0.0", - "resolved": "https://registry.npmjs.org/vscode-textmate/-/vscode-textmate-8.0.0.tgz", - "integrity": "sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg==", - "dev": true - }, "node_modules/w3c-xmlserializer": { "version": "5.0.0", "resolved": "https://registry.npmjs.org/w3c-xmlserializer/-/w3c-xmlserializer-5.0.0.tgz", @@ -9369,6 +9384,18 @@ "integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==", "dev": true }, + "node_modules/yaml": { + "version": "2.4.5", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.4.5.tgz", + "integrity": "sha512-aBx2bnqDzVOyNKfsysjA2ms5ZlnjSAW2eG3/L5G/CSujfjLJTJsEw1bGw8kCf04KodQWk1pxlGnZ56CRxiawmg==", + "dev": true, + "bin": { + "yaml": "bin.mjs" + }, + "engines": { + "node": ">= 14" + } + }, "node_modules/yargs": { "version": "17.7.2", "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.7.2.tgz", diff --git a/package.json b/package.json index 42f544dec02..2db5ee36aa8 100644 --- a/package.json +++ b/package.json @@ -77,8 +77,9 @@ "error", { "definedTags": [ + "attribute", "category", - "attribute" + "import" ] } ] @@ -132,9 +133,9 @@ "rollup-plugin-visualizer": "^5.12.0", "serve": "^14.2.2", "sinon": "^17.0.1", - "typedoc": "^0.25.13", - "typedoc-plugin-mdn-links": "^3.1.22", - "typescript": "^5.4.5", + "typedoc": "^0.26.3", + "typedoc-plugin-mdn-links": "^3.2.2", + "typescript": "^5.5.3", "xhr2": "^0.2.1" }, "scripts": { diff --git a/scripts/spine/playcanvas-spine.3.8.js b/scripts/spine/playcanvas-spine.3.8.js index 697bb3e1c29..b8847d97c84 100644 --- a/scripts/spine/playcanvas-spine.3.8.js +++ b/scripts/spine/playcanvas-spine.3.8.js @@ -1,4 +1,4 @@ -/* Copyright 2015-2023 PlayCanvas Ltd */ +/* Copyright 2015-2024 PlayCanvas Ltd */ var spine = (function (pc) { 'use strict'; @@ -7837,10 +7837,7 @@ var spine = (function (pc) { f = !0, o = !1; try { - if (i = (t = t.call(r)).next, 0 === l) { - if (Object(t) !== t) return; - f = !1; - } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); + if (i = (t = t.call(r)).next, 0 === l) ; else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { @@ -7853,307 +7850,6 @@ var spine = (function (pc) { return a; } } - function _regeneratorRuntime() { - _regeneratorRuntime = function () { - return e; - }; - var t, - e = {}, - r = Object.prototype, - n = r.hasOwnProperty, - o = Object.defineProperty || function (t, e, r) { - t[e] = r.value; - }, - i = "function" == typeof Symbol ? Symbol : {}, - a = i.iterator || "@@iterator", - c = i.asyncIterator || "@@asyncIterator", - u = i.toStringTag || "@@toStringTag"; - function define(t, e, r) { - return Object.defineProperty(t, e, { - value: r, - enumerable: !0, - configurable: !0, - writable: !0 - }), t[e]; - } - try { - define({}, ""); - } catch (t) { - define = function (t, e, r) { - return t[e] = r; - }; - } - function wrap(t, e, r, n) { - var i = e && e.prototype instanceof Generator ? e : Generator, - a = Object.create(i.prototype), - c = new Context(n || []); - return o(a, "_invoke", { - value: makeInvokeMethod(t, r, c) - }), a; - } - function tryCatch(t, e, r) { - try { - return { - type: "normal", - arg: t.call(e, r) - }; - } catch (t) { - return { - type: "throw", - arg: t - }; - } - } - e.wrap = wrap; - var h = "suspendedStart", - l = "suspendedYield", - f = "executing", - s = "completed", - y = {}; - function Generator() {} - function GeneratorFunction() {} - function GeneratorFunctionPrototype() {} - var p = {}; - define(p, a, function () { - return this; - }); - var d = Object.getPrototypeOf, - v = d && d(d(values([]))); - v && v !== r && n.call(v, a) && (p = v); - var g = GeneratorFunctionPrototype.prototype = Generator.prototype = Object.create(p); - function defineIteratorMethods(t) { - ["next", "throw", "return"].forEach(function (e) { - define(t, e, function (t) { - return this._invoke(e, t); - }); - }); - } - function AsyncIterator(t, e) { - function invoke(r, o, i, a) { - var c = tryCatch(t[r], t, o); - if ("throw" !== c.type) { - var u = c.arg, - h = u.value; - return h && "object" == typeof h && n.call(h, "__await") ? e.resolve(h.__await).then(function (t) { - invoke("next", t, i, a); - }, function (t) { - invoke("throw", t, i, a); - }) : e.resolve(h).then(function (t) { - u.value = t, i(u); - }, function (t) { - return invoke("throw", t, i, a); - }); - } - a(c.arg); - } - var r; - o(this, "_invoke", { - value: function (t, n) { - function callInvokeWithMethodAndArg() { - return new e(function (e, r) { - invoke(t, n, e, r); - }); - } - return r = r ? r.then(callInvokeWithMethodAndArg, callInvokeWithMethodAndArg) : callInvokeWithMethodAndArg(); - } - }); - } - function makeInvokeMethod(e, r, n) { - var o = h; - return function (i, a) { - if (o === f) throw new Error("Generator is already running"); - if (o === s) { - if ("throw" === i) throw a; - return { - value: t, - done: !0 - }; - } - for (n.method = i, n.arg = a;;) { - var c = n.delegate; - if (c) { - var u = maybeInvokeDelegate(c, n); - if (u) { - if (u === y) continue; - return u; - } - } - if ("next" === n.method) n.sent = n._sent = n.arg;else if ("throw" === n.method) { - if (o === h) throw o = s, n.arg; - n.dispatchException(n.arg); - } else "return" === n.method && n.abrupt("return", n.arg); - o = f; - var p = tryCatch(e, r, n); - if ("normal" === p.type) { - if (o = n.done ? s : l, p.arg === y) continue; - return { - value: p.arg, - done: n.done - }; - } - "throw" === p.type && (o = s, n.method = "throw", n.arg = p.arg); - } - }; - } - function maybeInvokeDelegate(e, r) { - var n = r.method, - o = e.iterator[n]; - if (o === t) return r.delegate = null, "throw" === n && e.iterator.return && (r.method = "return", r.arg = t, maybeInvokeDelegate(e, r), "throw" === r.method) || "return" !== n && (r.method = "throw", r.arg = new TypeError("The iterator does not provide a '" + n + "' method")), y; - var i = tryCatch(o, e.iterator, r.arg); - if ("throw" === i.type) return r.method = "throw", r.arg = i.arg, r.delegate = null, y; - var a = i.arg; - return a ? a.done ? (r[e.resultName] = a.value, r.next = e.nextLoc, "return" !== r.method && (r.method = "next", r.arg = t), r.delegate = null, y) : a : (r.method = "throw", r.arg = new TypeError("iterator result is not an object"), r.delegate = null, y); - } - function pushTryEntry(t) { - var e = { - tryLoc: t[0] - }; - 1 in t && (e.catchLoc = t[1]), 2 in t && (e.finallyLoc = t[2], e.afterLoc = t[3]), this.tryEntries.push(e); - } - function resetTryEntry(t) { - var e = t.completion || {}; - e.type = "normal", delete e.arg, t.completion = e; - } - function Context(t) { - this.tryEntries = [{ - tryLoc: "root" - }], t.forEach(pushTryEntry, this), this.reset(!0); - } - function values(e) { - if (e || "" === e) { - var r = e[a]; - if (r) return r.call(e); - if ("function" == typeof e.next) return e; - if (!isNaN(e.length)) { - var o = -1, - i = function next() { - for (; ++o < e.length;) if (n.call(e, o)) return next.value = e[o], next.done = !1, next; - return next.value = t, next.done = !0, next; - }; - return i.next = i; - } - } - throw new TypeError(typeof e + " is not iterable"); - } - return GeneratorFunction.prototype = GeneratorFunctionPrototype, o(g, "constructor", { - value: GeneratorFunctionPrototype, - configurable: !0 - }), o(GeneratorFunctionPrototype, "constructor", { - value: GeneratorFunction, - configurable: !0 - }), GeneratorFunction.displayName = define(GeneratorFunctionPrototype, u, "GeneratorFunction"), e.isGeneratorFunction = function (t) { - var e = "function" == typeof t && t.constructor; - return !!e && (e === GeneratorFunction || "GeneratorFunction" === (e.displayName || e.name)); - }, e.mark = function (t) { - return Object.setPrototypeOf ? Object.setPrototypeOf(t, GeneratorFunctionPrototype) : (t.__proto__ = GeneratorFunctionPrototype, define(t, u, "GeneratorFunction")), t.prototype = Object.create(g), t; - }, e.awrap = function (t) { - return { - __await: t - }; - }, defineIteratorMethods(AsyncIterator.prototype), define(AsyncIterator.prototype, c, function () { - return this; - }), e.AsyncIterator = AsyncIterator, e.async = function (t, r, n, o, i) { - void 0 === i && (i = Promise); - var a = new AsyncIterator(wrap(t, r, n, o), i); - return e.isGeneratorFunction(r) ? a : a.next().then(function (t) { - return t.done ? t.value : a.next(); - }); - }, defineIteratorMethods(g), define(g, u, "Generator"), define(g, a, function () { - return this; - }), define(g, "toString", function () { - return "[object Generator]"; - }), e.keys = function (t) { - var e = Object(t), - r = []; - for (var n in e) r.push(n); - return r.reverse(), function next() { - for (; r.length;) { - var t = r.pop(); - if (t in e) return next.value = t, next.done = !1, next; - } - return next.done = !0, next; - }; - }, e.values = values, Context.prototype = { - constructor: Context, - reset: function (e) { - if (this.prev = 0, this.next = 0, this.sent = this._sent = t, this.done = !1, this.delegate = null, this.method = "next", this.arg = t, this.tryEntries.forEach(resetTryEntry), !e) for (var r in this) "t" === r.charAt(0) && n.call(this, r) && !isNaN(+r.slice(1)) && (this[r] = t); - }, - stop: function () { - this.done = !0; - var t = this.tryEntries[0].completion; - if ("throw" === t.type) throw t.arg; - return this.rval; - }, - dispatchException: function (e) { - if (this.done) throw e; - var r = this; - function handle(n, o) { - return a.type = "throw", a.arg = e, r.next = n, o && (r.method = "next", r.arg = t), !!o; - } - for (var o = this.tryEntries.length - 1; o >= 0; --o) { - var i = this.tryEntries[o], - a = i.completion; - if ("root" === i.tryLoc) return handle("end"); - if (i.tryLoc <= this.prev) { - var c = n.call(i, "catchLoc"), - u = n.call(i, "finallyLoc"); - if (c && u) { - if (this.prev < i.catchLoc) return handle(i.catchLoc, !0); - if (this.prev < i.finallyLoc) return handle(i.finallyLoc); - } else if (c) { - if (this.prev < i.catchLoc) return handle(i.catchLoc, !0); - } else { - if (!u) throw new Error("try statement without catch or finally"); - if (this.prev < i.finallyLoc) return handle(i.finallyLoc); - } - } - } - }, - abrupt: function (t, e) { - for (var r = this.tryEntries.length - 1; r >= 0; --r) { - var o = this.tryEntries[r]; - if (o.tryLoc <= this.prev && n.call(o, "finallyLoc") && this.prev < o.finallyLoc) { - var i = o; - break; - } - } - i && ("break" === t || "continue" === t) && i.tryLoc <= e && e <= i.finallyLoc && (i = null); - var a = i ? i.completion : {}; - return a.type = t, a.arg = e, i ? (this.method = "next", this.next = i.finallyLoc, y) : this.complete(a); - }, - complete: function (t, e) { - if ("throw" === t.type) throw t.arg; - return "break" === t.type || "continue" === t.type ? this.next = t.arg : "return" === t.type ? (this.rval = this.arg = t.arg, this.method = "return", this.next = "end") : "normal" === t.type && e && (this.next = e), y; - }, - finish: function (t) { - for (var e = this.tryEntries.length - 1; e >= 0; --e) { - var r = this.tryEntries[e]; - if (r.finallyLoc === t) return this.complete(r.completion, r.afterLoc), resetTryEntry(r), y; - } - }, - catch: function (t) { - for (var e = this.tryEntries.length - 1; e >= 0; --e) { - var r = this.tryEntries[e]; - if (r.tryLoc === t) { - var n = r.completion; - if ("throw" === n.type) { - var o = n.arg; - resetTryEntry(r); - } - return o; - } - } - throw new Error("illegal catch attempt"); - }, - delegateYield: function (e, r, n) { - return this.delegate = { - iterator: values(e), - resultName: r, - nextLoc: n - }, "next" === this.method && (this.arg = t), y; - } - }, e; - } function _typeof(o) { "@babel/helpers - typeof"; @@ -8228,17 +7924,6 @@ var spine = (function (pc) { }; return _setPrototypeOf(o, p); } - function _isNativeReflectConstruct() { - if (typeof Reflect === "undefined" || !Reflect.construct) return false; - if (Reflect.construct.sham) return false; - if (typeof Proxy === "function") return true; - try { - Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function () {})); - return true; - } catch (e) { - return false; - } - } function _assertThisInitialized(self) { if (self === void 0) { throw new ReferenceError("this hasn't been initialised - super() hasn't been called"); @@ -8253,20 +7938,6 @@ var spine = (function (pc) { } return _assertThisInitialized(self); } - function _createSuper(Derived) { - var hasNativeReflectConstruct = _isNativeReflectConstruct(); - return function _createSuperInternal() { - var Super = _getPrototypeOf(Derived), - result; - if (hasNativeReflectConstruct) { - var NewTarget = _getPrototypeOf(this).constructor; - result = Reflect.construct(Super, arguments, NewTarget); - } else { - result = Super.apply(this, arguments); - } - return _possibleConstructorReturn(this, result); - }; - } function _superPropBase(object, property) { while (!Object.prototype.hasOwnProperty.call(object, property)) { object = _getPrototypeOf(object); @@ -8274,11 +7945,11 @@ var spine = (function (pc) { } return object; } - function _get$1() { + function _get() { if (typeof Reflect !== "undefined" && Reflect.get) { - _get$1 = Reflect.get.bind(); + _get = Reflect.get.bind(); } else { - _get$1 = function _get(target, property, receiver) { + _get = function _get(target, property, receiver) { var base = _superPropBase(target, property); if (!base) return; var desc = Object.getOwnPropertyDescriptor(base, property); @@ -8288,7 +7959,7 @@ var spine = (function (pc) { return desc.value; }; } - return _get$1.apply(this, arguments); + return _get.apply(this, arguments); } function _slicedToArray(arr, i) { return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest(); @@ -8327,7 +7998,7 @@ var spine = (function (pc) { function _createForOfIteratorHelper(o, allowArrayLike) { var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"]; if (!it) { - if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") { + if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike ) { if (it) o = it; var i = 0; var F = function () {}; @@ -8379,11 +8050,11 @@ var spine = (function (pc) { if (typeof input !== "object" || input === null) return input; var prim = input[Symbol.toPrimitive]; if (prim !== undefined) { - var res = prim.call(input, hint || "default"); + var res = prim.call(input, hint ); if (typeof res !== "object") return res; throw new TypeError("@@toPrimitive must return a primitive value."); } - return (hint === "string" ? String : Number)(input); + return (String )(input); } function _toPropertyKey(arg) { var key = _toPrimitive(arg, "string"); @@ -8412,7 +8083,7 @@ var spine = (function (pc) { }; this.pcTexture = texture; } - _createClass(SpineTextureWrapper, [{ + return _createClass(SpineTextureWrapper, [{ key: "setFilters", value: function setFilters(minFilter, magFilter) { this.pcTexture.minFilter = TO_TEXTURE_FILTER[minFilter]; @@ -8435,7 +8106,6 @@ var spine = (function (pc) { this.pcTexture.destroy(); } }]); - return SpineTextureWrapper; }(); function getDefaultExportFromCjs (x) { @@ -8525,8 +8195,11 @@ var spine = (function (pc) { createToken('XRANGEPLAINLOOSE', "[v=\\s]*(".concat(src[t.XRANGEIDENTIFIERLOOSE], ")") + "(?:\\.(".concat(src[t.XRANGEIDENTIFIERLOOSE], ")") + "(?:\\.(".concat(src[t.XRANGEIDENTIFIERLOOSE], ")") + "(?:".concat(src[t.PRERELEASELOOSE], ")?").concat(src[t.BUILD], "?") + ")?)?"); createToken('XRANGE', "^".concat(src[t.GTLT], "\\s*").concat(src[t.XRANGEPLAIN], "$")); createToken('XRANGELOOSE', "^".concat(src[t.GTLT], "\\s*").concat(src[t.XRANGEPLAINLOOSE], "$")); - createToken('COERCE', "".concat('(^|[^\\d])' + '(\\d{1,').concat(MAX_SAFE_COMPONENT_LENGTH, "})") + "(?:\\.(\\d{1,".concat(MAX_SAFE_COMPONENT_LENGTH, "}))?") + "(?:\\.(\\d{1,".concat(MAX_SAFE_COMPONENT_LENGTH, "}))?") + "(?:$|[^\\d])"); + createToken('COERCEPLAIN', "".concat('(^|[^\\d])' + '(\\d{1,').concat(MAX_SAFE_COMPONENT_LENGTH, "})") + "(?:\\.(\\d{1,".concat(MAX_SAFE_COMPONENT_LENGTH, "}))?") + "(?:\\.(\\d{1,".concat(MAX_SAFE_COMPONENT_LENGTH, "}))?")); + createToken('COERCE', "".concat(src[t.COERCEPLAIN], "(?:$|[^\\d])")); + createToken('COERCEFULL', src[t.COERCEPLAIN] + "(?:".concat(src[t.PRERELEASE], ")?") + "(?:".concat(src[t.BUILD], ")?") + "(?:$|[^\\d])"); createToken('COERCERTL', src[t.COERCE], true); + createToken('COERCERTLFULL', src[t.COERCEFULL], true); createToken('LONETILDE', '(?:~>?)'); createToken('TILDETRIM', "(\\s*)".concat(src[t.LONETILDE], "\\s+"), true); exports.tildeTrimReplace = '$1~'; @@ -8645,7 +8318,7 @@ var spine = (function (pc) { this.build = m[5] ? m[5].split('.') : []; this.format(); } - _createClass(SemVer, [{ + return _createClass(SemVer, [{ key: "format", value: function format() { this.version = "".concat(this.major, ".").concat(this.minor, ".").concat(this.patch); @@ -8723,7 +8396,7 @@ var spine = (function (pc) { do { var a = this.build[i]; var b = other.build[i]; - debug('prerelease compare', i, a, b); + debug('build compare', i, a, b); if (a === undefined && b === undefined) { return 0; } else if (b === undefined) { @@ -8834,7 +8507,6 @@ var spine = (function (pc) { return this; } }]); - return SemVer; }(); var semver$1 = SemVer$3; getDefaultExportFromCjs(semver$1); @@ -8882,727 +8554,76 @@ var spine = (function (pc) { options = options || {}; var match = null; if (!options.rtl) { - match = version.match(re[t.COERCE]); + match = version.match(options.includePrerelease ? re[t.COERCEFULL] : re[t.COERCE]); } else { + var coerceRtlRegex = options.includePrerelease ? re[t.COERCERTLFULL] : re[t.COERCERTL]; var next; - while ((next = re[t.COERCERTL].exec(version)) && (!match || match.index + match[0].length !== version.length)) { + while ((next = coerceRtlRegex.exec(version)) && (!match || match.index + match[0].length !== version.length)) { if (!match || next.index + next[0].length !== match.index + match[0].length) { match = next; } - re[t.COERCERTL].lastIndex = next.index + next[1].length + next[2].length; + coerceRtlRegex.lastIndex = next.index + next[1].length + next[2].length; } - re[t.COERCERTL].lastIndex = -1; + coerceRtlRegex.lastIndex = -1; } if (match === null) { return null; } - return parse("".concat(match[2], ".").concat(match[3] || '0', ".").concat(match[4] || '0'), options); + var major = match[2]; + var minor = match[3] || '0'; + var patch = match[4] || '0'; + var prerelease = options.includePrerelease && match[5] ? "-".concat(match[5]) : ''; + var build = options.includePrerelease && match[6] ? "+".concat(match[6]) : ''; + return parse("".concat(major, ".").concat(minor, ".").concat(patch).concat(prerelease).concat(build), options); }; var coerce_1 = coerce; var coerce$1 = getDefaultExportFromCjs(coerce_1); - var iterator; - var hasRequiredIterator; - function requireIterator() { - if (hasRequiredIterator) return iterator; - hasRequiredIterator = 1; - iterator = function iterator(Yallist) { - Yallist.prototype[Symbol.iterator] = _regeneratorRuntime().mark(function _callee() { - var walker; - return _regeneratorRuntime().wrap(function _callee$(_context) { - while (1) switch (_context.prev = _context.next) { - case 0: - walker = this.head; - case 1: - if (!walker) { - _context.next = 7; - break; - } - _context.next = 4; - return walker.value; - case 4: - walker = walker.next; - _context.next = 1; - break; - case 7: - case "end": - return _context.stop(); - } - }, _callee, this); - }); - }; - return iterator; - } - - var yallist = Yallist$1; - Yallist$1.Node = Node; - Yallist$1.create = Yallist$1; - function Yallist$1(list) { - var self = this; - if (!(self instanceof Yallist$1)) { - self = new Yallist$1(); - } - self.tail = null; - self.head = null; - self.length = 0; - if (list && typeof list.forEach === 'function') { - list.forEach(function (item) { - self.push(item); - }); - } else if (arguments.length > 0) { - for (var i = 0, l = arguments.length; i < l; i++) { - self.push(arguments[i]); - } - } - return self; - } - Yallist$1.prototype.removeNode = function (node) { - if (node.list !== this) { - throw new Error('removing node which does not belong to this list'); - } - var next = node.next; - var prev = node.prev; - if (next) { - next.prev = prev; - } - if (prev) { - prev.next = next; - } - if (node === this.head) { - this.head = next; - } - if (node === this.tail) { - this.tail = prev; - } - node.list.length--; - node.next = null; - node.prev = null; - node.list = null; - return next; - }; - Yallist$1.prototype.unshiftNode = function (node) { - if (node === this.head) { - return; - } - if (node.list) { - node.list.removeNode(node); - } - var head = this.head; - node.list = this; - node.next = head; - if (head) { - head.prev = node; - } - this.head = node; - if (!this.tail) { - this.tail = node; - } - this.length++; - }; - Yallist$1.prototype.pushNode = function (node) { - if (node === this.tail) { - return; - } - if (node.list) { - node.list.removeNode(node); - } - var tail = this.tail; - node.list = this; - node.prev = tail; - if (tail) { - tail.next = node; - } - this.tail = node; - if (!this.head) { - this.head = node; - } - this.length++; - }; - Yallist$1.prototype.push = function () { - for (var i = 0, l = arguments.length; i < l; i++) { - push(this, arguments[i]); - } - return this.length; - }; - Yallist$1.prototype.unshift = function () { - for (var i = 0, l = arguments.length; i < l; i++) { - unshift(this, arguments[i]); - } - return this.length; - }; - Yallist$1.prototype.pop = function () { - if (!this.tail) { - return undefined; - } - var res = this.tail.value; - this.tail = this.tail.prev; - if (this.tail) { - this.tail.next = null; - } else { - this.head = null; - } - this.length--; - return res; - }; - Yallist$1.prototype.shift = function () { - if (!this.head) { - return undefined; - } - var res = this.head.value; - this.head = this.head.next; - if (this.head) { - this.head.prev = null; - } else { - this.tail = null; - } - this.length--; - return res; - }; - Yallist$1.prototype.forEach = function (fn, thisp) { - thisp = thisp || this; - for (var walker = this.head, i = 0; walker !== null; i++) { - fn.call(thisp, walker.value, i, this); - walker = walker.next; - } - }; - Yallist$1.prototype.forEachReverse = function (fn, thisp) { - thisp = thisp || this; - for (var walker = this.tail, i = this.length - 1; walker !== null; i--) { - fn.call(thisp, walker.value, i, this); - walker = walker.prev; - } - }; - Yallist$1.prototype.get = function (n) { - for (var i = 0, walker = this.head; walker !== null && i < n; i++) { - walker = walker.next; - } - if (i === n && walker !== null) { - return walker.value; - } - }; - Yallist$1.prototype.getReverse = function (n) { - for (var i = 0, walker = this.tail; walker !== null && i < n; i++) { - walker = walker.prev; - } - if (i === n && walker !== null) { - return walker.value; - } - }; - Yallist$1.prototype.map = function (fn, thisp) { - thisp = thisp || this; - var res = new Yallist$1(); - for (var walker = this.head; walker !== null;) { - res.push(fn.call(thisp, walker.value, this)); - walker = walker.next; - } - return res; - }; - Yallist$1.prototype.mapReverse = function (fn, thisp) { - thisp = thisp || this; - var res = new Yallist$1(); - for (var walker = this.tail; walker !== null;) { - res.push(fn.call(thisp, walker.value, this)); - walker = walker.prev; - } - return res; - }; - Yallist$1.prototype.reduce = function (fn, initial) { - var acc; - var walker = this.head; - if (arguments.length > 1) { - acc = initial; - } else if (this.head) { - walker = this.head.next; - acc = this.head.value; - } else { - throw new TypeError('Reduce of empty list with no initial value'); - } - for (var i = 0; walker !== null; i++) { - acc = fn(acc, walker.value, i); - walker = walker.next; - } - return acc; - }; - Yallist$1.prototype.reduceReverse = function (fn, initial) { - var acc; - var walker = this.tail; - if (arguments.length > 1) { - acc = initial; - } else if (this.tail) { - walker = this.tail.prev; - acc = this.tail.value; - } else { - throw new TypeError('Reduce of empty list with no initial value'); - } - for (var i = this.length - 1; walker !== null; i--) { - acc = fn(acc, walker.value, i); - walker = walker.prev; - } - return acc; - }; - Yallist$1.prototype.toArray = function () { - var arr = new Array(this.length); - for (var i = 0, walker = this.head; walker !== null; i++) { - arr[i] = walker.value; - walker = walker.next; - } - return arr; - }; - Yallist$1.prototype.toArrayReverse = function () { - var arr = new Array(this.length); - for (var i = 0, walker = this.tail; walker !== null; i++) { - arr[i] = walker.value; - walker = walker.prev; - } - return arr; - }; - Yallist$1.prototype.slice = function (from, to) { - to = to || this.length; - if (to < 0) { - to += this.length; - } - from = from || 0; - if (from < 0) { - from += this.length; - } - var ret = new Yallist$1(); - if (to < from || to < 0) { - return ret; - } - if (from < 0) { - from = 0; - } - if (to > this.length) { - to = this.length; - } - for (var i = 0, walker = this.head; walker !== null && i < from; i++) { - walker = walker.next; - } - for (; walker !== null && i < to; i++, walker = walker.next) { - ret.push(walker.value); - } - return ret; - }; - Yallist$1.prototype.sliceReverse = function (from, to) { - to = to || this.length; - if (to < 0) { - to += this.length; - } - from = from || 0; - if (from < 0) { - from += this.length; - } - var ret = new Yallist$1(); - if (to < from || to < 0) { - return ret; - } - if (from < 0) { - from = 0; - } - if (to > this.length) { - to = this.length; - } - for (var i = this.length, walker = this.tail; walker !== null && i > to; i--) { - walker = walker.prev; - } - for (; walker !== null && i > from; i--, walker = walker.prev) { - ret.push(walker.value); - } - return ret; - }; - Yallist$1.prototype.splice = function (start, deleteCount) { - if (start > this.length) { - start = this.length - 1; - } - if (start < 0) { - start = this.length + start; - } - for (var i = 0, walker = this.head; walker !== null && i < start; i++) { - walker = walker.next; - } - var ret = []; - for (var i = 0; walker && i < deleteCount; i++) { - ret.push(walker.value); - walker = this.removeNode(walker); - } - if (walker === null) { - walker = this.tail; - } - if (walker !== this.head && walker !== this.tail) { - walker = walker.prev; - } - for (var i = 0; i < (arguments.length <= 2 ? 0 : arguments.length - 2); i++) { - walker = insert(this, walker, i + 2 < 2 || arguments.length <= i + 2 ? undefined : arguments[i + 2]); - } - return ret; - }; - Yallist$1.prototype.reverse = function () { - var head = this.head; - var tail = this.tail; - for (var walker = head; walker !== null; walker = walker.prev) { - var p = walker.prev; - walker.prev = walker.next; - walker.next = p; - } - this.head = tail; - this.tail = head; - return this; - }; - function insert(self, node, value) { - var inserted = node === self.head ? new Node(value, null, node, self) : new Node(value, node, node.next, self); - if (inserted.next === null) { - self.tail = inserted; - } - if (inserted.prev === null) { - self.head = inserted; - } - self.length++; - return inserted; - } - function push(self, item) { - self.tail = new Node(item, self.tail, null, self); - if (!self.head) { - self.head = self.tail; - } - self.length++; - } - function unshift(self, item) { - self.head = new Node(item, null, self.head, self); - if (!self.tail) { - self.tail = self.head; - } - self.length++; - } - function Node(value, prev, next, list) { - if (!(this instanceof Node)) { - return new Node(value, prev, next, list); - } - this.list = list; - this.value = value; - if (prev) { - prev.next = this; - this.prev = prev; - } else { - this.prev = null; - } - if (next) { - next.prev = this; - this.next = next; - } else { - this.next = null; - } - } - try { - requireIterator()(Yallist$1); - } catch (er) {} - getDefaultExportFromCjs(yallist); - - var Yallist = yallist; - var MAX = Symbol('max'); - var LENGTH = Symbol('length'); - var LENGTH_CALCULATOR = Symbol('lengthCalculator'); - var ALLOW_STALE = Symbol('allowStale'); - var MAX_AGE = Symbol('maxAge'); - var DISPOSE = Symbol('dispose'); - var NO_DISPOSE_ON_SET = Symbol('noDisposeOnSet'); - var LRU_LIST = Symbol('lruList'); - var CACHE = Symbol('cache'); - var UPDATE_AGE_ON_GET = Symbol('updateAgeOnGet'); - var naiveLength = function naiveLength() { - return 1; - }; var LRUCache = function () { - function LRUCache(options) { + function LRUCache() { _classCallCheck(this, LRUCache); - if (typeof options === 'number') options = { - max: options - }; - if (!options) options = {}; - if (options.max && (typeof options.max !== 'number' || options.max < 0)) throw new TypeError('max must be a non-negative number'); - this[MAX] = options.max || Infinity; - var lc = options.length || naiveLength; - this[LENGTH_CALCULATOR] = typeof lc !== 'function' ? naiveLength : lc; - this[ALLOW_STALE] = options.stale || false; - if (options.maxAge && typeof options.maxAge !== 'number') throw new TypeError('maxAge must be a number'); - this[MAX_AGE] = options.maxAge || 0; - this[DISPOSE] = options.dispose; - this[NO_DISPOSE_ON_SET] = options.noDisposeOnSet || false; - this[UPDATE_AGE_ON_GET] = options.updateAgeOnGet || false; - this.reset(); + this.max = 1000; + this.map = new Map(); } - _createClass(LRUCache, [{ - key: "max", - get: function get() { - return this[MAX]; - }, - set: function set(mL) { - if (typeof mL !== 'number' || mL < 0) throw new TypeError('max must be a non-negative number'); - this[MAX] = mL || Infinity; - trim(this); - } - }, { - key: "allowStale", - get: function get() { - return this[ALLOW_STALE]; - }, - set: function set(allowStale) { - this[ALLOW_STALE] = !!allowStale; - } - }, { - key: "maxAge", - get: function get() { - return this[MAX_AGE]; - }, - set: function set(mA) { - if (typeof mA !== 'number') throw new TypeError('maxAge must be a non-negative number'); - this[MAX_AGE] = mA; - trim(this); - } - }, { - key: "lengthCalculator", - get: function get() { - return this[LENGTH_CALCULATOR]; - }, - set: function set(lC) { - var _this = this; - if (typeof lC !== 'function') lC = naiveLength; - if (lC !== this[LENGTH_CALCULATOR]) { - this[LENGTH_CALCULATOR] = lC; - this[LENGTH] = 0; - this[LRU_LIST].forEach(function (hit) { - hit.length = _this[LENGTH_CALCULATOR](hit.value, hit.key); - _this[LENGTH] += hit.length; - }); - } - trim(this); - } - }, { - key: "length", - get: function get() { - return this[LENGTH]; - } - }, { - key: "itemCount", - get: function get() { - return this[LRU_LIST].length; - } - }, { - key: "rforEach", - value: function rforEach(fn, thisp) { - thisp = thisp || this; - for (var walker = this[LRU_LIST].tail; walker !== null;) { - var prev = walker.prev; - forEachStep(this, fn, walker, thisp); - walker = prev; - } - } - }, { - key: "forEach", - value: function forEach(fn, thisp) { - thisp = thisp || this; - for (var walker = this[LRU_LIST].head; walker !== null;) { - var next = walker.next; - forEachStep(this, fn, walker, thisp); - walker = next; - } - } - }, { - key: "keys", - value: function keys() { - return this[LRU_LIST].toArray().map(function (k) { - return k.key; - }); - } - }, { - key: "values", - value: function values() { - return this[LRU_LIST].toArray().map(function (k) { - return k.value; - }); - } - }, { - key: "reset", - value: function reset() { - var _this2 = this; - if (this[DISPOSE] && this[LRU_LIST] && this[LRU_LIST].length) { - this[LRU_LIST].forEach(function (hit) { - return _this2[DISPOSE](hit.key, hit.value); - }); + return _createClass(LRUCache, [{ + key: "get", + value: function get(key) { + var value = this.map.get(key); + if (value === undefined) { + return undefined; + } else { + this.map.delete(key); + this.map.set(key, value); + return value; } - this[CACHE] = new Map(); - this[LRU_LIST] = new Yallist(); - this[LENGTH] = 0; - } - }, { - key: "dump", - value: function dump() { - var _this3 = this; - return this[LRU_LIST].map(function (hit) { - return isStale(_this3, hit) ? false : { - k: hit.key, - v: hit.value, - e: hit.now + (hit.maxAge || 0) - }; - }).toArray().filter(function (h) { - return h; - }); - } - }, { - key: "dumpLru", - value: function dumpLru() { - return this[LRU_LIST]; } }, { - key: "set", - value: function set(key, value, maxAge) { - maxAge = maxAge || this[MAX_AGE]; - if (maxAge && typeof maxAge !== 'number') throw new TypeError('maxAge must be a number'); - var now = maxAge ? Date.now() : 0; - var len = this[LENGTH_CALCULATOR](value, key); - if (this[CACHE].has(key)) { - if (len > this[MAX]) { - _del(this, this[CACHE].get(key)); - return false; - } - var node = this[CACHE].get(key); - var item = node.value; - if (this[DISPOSE]) { - if (!this[NO_DISPOSE_ON_SET]) this[DISPOSE](key, item.value); - } - item.now = now; - item.maxAge = maxAge; - item.value = value; - this[LENGTH] += len - item.length; - item.length = len; - this.get(key); - trim(this); + key: "delete", + value: function _delete(key) { + if (this.map.has(key)) { + this.map.delete(key); return true; - } - var hit = new Entry(key, value, len, now, maxAge); - if (hit.length > this[MAX]) { - if (this[DISPOSE]) this[DISPOSE](key, value); + } else { return false; } - this[LENGTH] += hit.length; - this[LRU_LIST].unshift(hit); - this[CACHE].set(key, this[LRU_LIST].head); - trim(this); - return true; - } - }, { - key: "has", - value: function has(key) { - if (!this[CACHE].has(key)) return false; - var hit = this[CACHE].get(key).value; - return !isStale(this, hit); - } - }, { - key: "get", - value: function get(key) { - return _get(this, key, true); - } - }, { - key: "peek", - value: function peek(key) { - return _get(this, key, false); - } - }, { - key: "pop", - value: function pop() { - var node = this[LRU_LIST].tail; - if (!node) return null; - _del(this, node); - return node.value; } }, { - key: "del", - value: function del(key) { - _del(this, this[CACHE].get(key)); - } - }, { - key: "load", - value: function load(arr) { - this.reset(); - var now = Date.now(); - for (var l = arr.length - 1; l >= 0; l--) { - var hit = arr[l]; - var expiresAt = hit.e || 0; - if (expiresAt === 0) this.set(hit.k, hit.v);else { - var maxAge = expiresAt - now; - if (maxAge > 0) { - this.set(hit.k, hit.v, maxAge); - } + key: "set", + value: function set(key, value) { + var deleted = this.delete(key); + if (!deleted && value !== undefined) { + if (this.map.size >= this.max) { + var firstKey = this.map.keys().next().value; + this.delete(firstKey); } + this.map.set(key, value); } - } - }, { - key: "prune", - value: function prune() { - var _this4 = this; - this[CACHE].forEach(function (value, key) { - return _get(_this4, key, false); - }); + return this; } }]); - return LRUCache; }(); - var _get = function _get(self, key, doUse) { - var node = self[CACHE].get(key); - if (node) { - var hit = node.value; - if (isStale(self, hit)) { - _del(self, node); - if (!self[ALLOW_STALE]) return undefined; - } else { - if (doUse) { - if (self[UPDATE_AGE_ON_GET]) node.value.now = Date.now(); - self[LRU_LIST].unshiftNode(node); - } - } - return hit.value; - } - }; - var isStale = function isStale(self, hit) { - if (!hit || !hit.maxAge && !self[MAX_AGE]) return false; - var diff = Date.now() - hit.now; - return hit.maxAge ? diff > hit.maxAge : self[MAX_AGE] && diff > self[MAX_AGE]; - }; - var trim = function trim(self) { - if (self[LENGTH] > self[MAX]) { - for (var walker = self[LRU_LIST].tail; self[LENGTH] > self[MAX] && walker !== null;) { - var prev = walker.prev; - _del(self, walker); - walker = prev; - } - } - }; - var _del = function _del(self, node) { - if (node) { - var hit = node.value; - if (self[DISPOSE]) self[DISPOSE](hit.key, hit.value); - self[LENGTH] -= hit.length; - self[CACHE].delete(hit.key); - self[LRU_LIST].removeNode(node); - } - }; - var Entry = _createClass(function Entry(key, value, length, now, maxAge) { - _classCallCheck(this, Entry); - this.key = key; - this.value = value; - this.length = length; - this.now = now; - this.maxAge = maxAge || 0; - }); - var forEachStep = function forEachStep(self, fn, node, thisp) { - var hit = node.value; - if (isStale(self, hit)) { - _del(self, node); - if (!self[ALLOW_STALE]) hit = undefined; - } - if (hit) fn.call(thisp, hit.value, hit.key, self); - }; - var lruCache = LRUCache; - getDefaultExportFromCjs(lruCache); + var lrucache = LRUCache; + getDefaultExportFromCjs(lrucache); var SemVer = semver$1; var compare$6 = function compare(a, b, loose) { @@ -9727,7 +8748,7 @@ var spine = (function (pc) { } debug('comp', this); } - _createClass(Comparator, [{ + return _createClass(Comparator, [{ key: "parse", value: function parse(comp) { var r = this.options.loose ? re[t.COMPARATORLOOSE] : re[t.COMPARATOR]; @@ -9813,7 +8834,6 @@ var spine = (function (pc) { return ANY; } }]); - return Comparator; }(); comparator = Comparator; var parseOptions = parseOptions_1; @@ -9888,7 +8908,7 @@ var spine = (function (pc) { } this.format(); } - _createClass(Range, [{ + return _createClass(Range, [{ key: "format", value: function format() { this.range = this.set.map(function (comps) { @@ -9996,13 +9016,10 @@ var spine = (function (pc) { return false; } }]); - return Range; }(); range = Range; - var LRU = lruCache; - var cache = new LRU({ - max: 1000 - }); + var LRU = lrucache; + var cache = new LRU(); var parseOptions = parseOptions_1; var Comparator = requireComparator(); var debug = debug_1; @@ -10192,7 +9209,7 @@ var spine = (function (pc) { return comp.trim().replace(re[options.includePrerelease ? t.GTE0PRE : t.GTE0], ''); }; var hyphenReplace = function hyphenReplace(incPr) { - return function ($0, from, fM, fm, fp, fpr, fb, to, tM, tm, tp, tpr, tb) { + return function ($0, from, fM, fm, fp, fpr, fb, to, tM, tm, tp, tpr) { if (isX(fM)) { from = ''; } else if (isX(fm)) { @@ -10305,6 +9322,7 @@ var spine = (function (pc) { this.skeletonVersion = semver.valid(semver.coerce(_skeletonData.version)); this._spine_3_6_0 = semver.satisfies(this.skeletonVersion, '<=3.6.0'); this._spine_3_7_99 = semver.satisfies(this.skeletonVersion, '<=3.7.99'); + this._spine_4_0_X = semver.satisfies(this.skeletonVersion, '~4.0.0'); this._spine_4_1_X = semver.satisfies(this.skeletonVersion, '~4.1.23'); this.skeleton = new spine$1.Skeleton(_skeletonData); this.skeleton.updateWorldTransform(); @@ -10333,7 +9351,7 @@ var spine = (function (pc) { this.init(); this._hidden = false; } - _createClass(Spine, [{ + return _createClass(Spine, [{ key: "destroy", value: function destroy() { this.removeFromLayers(); @@ -10420,6 +9438,7 @@ var spine = (function (pc) { var material = new pc__namespace.StandardMaterial(); material.emissiveMap = texture; material.emissiveVertexColor = true; + material.emissive = pc__namespace.Color.WHITE; material.opacityMap = texture; material.opacityVertexColor = true; material.depthWrite = false; @@ -10443,26 +9462,32 @@ var spine = (function (pc) { } else if (attachment instanceof spine$1.MeshAttachment) { slot._active.type = ATTACHMENT_TYPE.MESH; } - if (attachment.region && attachment.region.texture) { - var texture = attachment.region.texture.pcTexture; - if (texture) { - if (texture instanceof pc__namespace.StandardMaterial) { - this._materials[texture.name] = texture; - slot.material = texture.name; - } else { - var key = null; - if (texture.name) { - key = texture.name; - } else if (texture.getSource() instanceof Image) { - key = texture.getSource().getAttribute('src'); - } - if (key) { - if (this._materials[key] === undefined) { - var material = this.createMaterial(texture); - this._materials[key] = material; - } - slot.material = key; + var texture = null; + if (attachment.region) { + if (attachment.region.texture) { + texture = attachment.region.texture.pcTexture; + } + if (attachment.region.page && attachment.region.page.texture) { + texture = attachment.region.page.texture.pcTexture; + } + } + if (texture) { + if (texture instanceof pc__namespace.StandardMaterial) { + this._materials[texture.name] = texture; + slot.material = texture.name; + } else { + var key = null; + if (texture.name) { + key = texture.name; + } else if (texture.getSource() instanceof Image) { + key = texture.getSource().getAttribute('src'); + } + if (key) { + if (this._materials[key] === undefined) { + var material = this.createMaterial(texture); + this._materials[key] = material; } + slot.material = key; } } } @@ -10722,25 +9747,37 @@ var spine = (function (pc) { this.addToLayers(); } }]); - return Spine; }(); + function _callSuper$1(_this, derived, args) { + function isNativeReflectConstruct() { + if (typeof Reflect === "undefined" || !Reflect.construct) return false; + if (Reflect.construct.sham) return false; + if (typeof Proxy === "function") return true; + try { + return !Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function () {})); + } catch (e) { + return false; + } + } + derived = _getPrototypeOf(derived); + return _possibleConstructorReturn(_this, isNativeReflectConstruct() ? Reflect.construct(derived, args || [], _getPrototypeOf(_this).constructor) : derived.apply(_this, args)); + } var SpineComponent = function (_Component) { - _inherits(SpineComponent, _Component); - var _super = _createSuper(SpineComponent); function SpineComponent(system, entity) { - var _this; + var _this2; _classCallCheck(this, SpineComponent); - _this = _super.call(this, system, entity); - _this.on('set_atlasAsset', _this.onSetAsset, _assertThisInitialized(_this)); - _this.on('set_textureAssets', _this.onSetAssets, _assertThisInitialized(_this)); - _this.on('set_skeletonAsset', _this.onSetAsset, _assertThisInitialized(_this)); - _this.on('set_atlasData', _this.onSetResource, _assertThisInitialized(_this)); - _this.on('set_textures', _this.onSetResource, _assertThisInitialized(_this)); - _this.on('set_skeletonData', _this.onSetResource, _assertThisInitialized(_this)); - return _this; + _this2 = _callSuper$1(this, SpineComponent, [system, entity]); + _this2.on('set_atlasAsset', _this2.onSetAsset, _this2); + _this2.on('set_textureAssets', _this2.onSetAssets, _this2); + _this2.on('set_skeletonAsset', _this2.onSetAsset, _this2); + _this2.on('set_atlasData', _this2.onSetResource, _this2); + _this2.on('set_textures', _this2.onSetResource, _this2); + _this2.on('set_skeletonData', _this2.onSetResource, _this2); + return _this2; } - _createClass(SpineComponent, [{ + _inherits(SpineComponent, _Component); + return _createClass(SpineComponent, [{ key: "_createSpine", value: function _createSpine() { if (this.data.spine) { @@ -10922,7 +9959,6 @@ var spine = (function (pc) { } } }]); - return SpineComponent; }(pc.Component); var SpineComponentData = _createClass(function SpineComponentData() { @@ -10938,26 +9974,39 @@ var spine = (function (pc) { this.skeletonData = null; }); + function _callSuper(_this, derived, args) { + function isNativeReflectConstruct() { + if (typeof Reflect === "undefined" || !Reflect.construct) return false; + if (Reflect.construct.sham) return false; + if (typeof Proxy === "function") return true; + try { + return !Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function () {})); + } catch (e) { + return false; + } + } + derived = _getPrototypeOf(derived); + return _possibleConstructorReturn(_this, isNativeReflectConstruct() ? Reflect.construct(derived, args || [], _getPrototypeOf(_this).constructor) : derived.apply(_this, args)); + } var SpineComponentSystem = function (_ComponentSystem) { - _inherits(SpineComponentSystem, _ComponentSystem); - var _super = _createSuper(SpineComponentSystem); function SpineComponentSystem(app) { - var _this; + var _this2; _classCallCheck(this, SpineComponentSystem); - _this = _super.call(this, app); - _this.id = 'spine'; - _this.ComponentType = SpineComponent; - _this.DataType = SpineComponentData; - _this.schema = ['enabled', 'atlasAsset', 'textureAssets', 'skeletonAsset', 'atlasData', 'textures', 'skeletonData', 'speed', 'spine']; - _this.on('beforeremove', _this.onBeforeRemove, _assertThisInitialized(_this)); - _this.app.systems.on('update', _this.onUpdate, _assertThisInitialized(_this)); - return _this; + _this2 = _callSuper(this, SpineComponentSystem, [app]); + _this2.id = 'spine'; + _this2.ComponentType = SpineComponent; + _this2.DataType = SpineComponentData; + _this2.schema = ['enabled', 'atlasAsset', 'textureAssets', 'skeletonAsset', 'atlasData', 'textures', 'skeletonData', 'speed', 'spine']; + _this2.on('beforeremove', _this2.onBeforeRemove, _this2); + _this2.app.systems.on('update', _this2.onUpdate, _this2); + return _this2; } - _createClass(SpineComponentSystem, [{ + _inherits(SpineComponentSystem, _ComponentSystem); + return _createClass(SpineComponentSystem, [{ key: "initializeComponentData", value: function initializeComponentData(component, data, properties) { properties = ['enabled', 'atlasAsset', 'textureAssets', 'skeletonAsset', 'atlasData', 'textures', 'skeletonData', 'spine']; - _get$1(_getPrototypeOf(SpineComponentSystem.prototype), "initializeComponentData", this).call(this, component, data, properties); + _get(_getPrototypeOf(SpineComponentSystem.prototype), "initializeComponentData", this).call(this, component, data, properties); } }, { key: "onBeforeRemove", @@ -10986,7 +10035,6 @@ var spine = (function (pc) { } } }]); - return SpineComponentSystem; }(pc.ComponentSystem); (function () { diff --git a/src/core/event-handle.js b/src/core/event-handle.js index 8046beca8ec..58c2c15abbf 100644 --- a/src/core/event-handle.js +++ b/src/core/event-handle.js @@ -1,5 +1,10 @@ import { Debug } from '../core/debug.js'; +/** + * @import { EventHandler } from './event-handler.js' + * @import { HandleEventCallback } from './event-handler.js' + */ + /** * Event Handle that is created by {@link EventHandler} and can be used for easier event removal * and management. @@ -27,7 +32,7 @@ import { Debug } from '../core/debug.js'; */ class EventHandle { /** - * @type {import('./event-handler.js').EventHandler} + * @type {EventHandler} * @private */ handler; @@ -39,7 +44,7 @@ class EventHandle { name; /** - * @type {import('./event-handler.js').HandleEventCallback} + * @type {HandleEventCallback} * @ignore */ callback; @@ -64,9 +69,9 @@ class EventHandle { _removed = false; /** - * @param {import('./event-handler.js').EventHandler} handler - source object of the event. + * @param {EventHandler} handler - source object of the event. * @param {string} name - Name of the event. - * @param {import('./event-handler.js').HandleEventCallback} callback - Function that is called when event is fired. + * @param {HandleEventCallback} callback - Function that is called when event is fired. * @param {object} scope - Object that is used as `this` when event is fired. * @param {boolean} [once] - If this is a single event and will be removed after event is fired. */ diff --git a/src/core/math/curve-evaluator.js b/src/core/math/curve-evaluator.js index 71f5f92a6ef..fe49d05f0c1 100644 --- a/src/core/math/curve-evaluator.js +++ b/src/core/math/curve-evaluator.js @@ -1,6 +1,10 @@ import { CURVE_LINEAR, CURVE_SMOOTHSTEP, CURVE_SPLINE, CURVE_STEP } from './constants.js'; import { math } from './math.js'; +/** + * @import { Curve } from './curve.js' + */ + /** * A class for evaluating a curve at a specific time. */ @@ -32,7 +36,7 @@ class CurveEvaluator { /** * Create a new CurveEvaluator instance. * - * @param {import('./curve.js').Curve} curve - The curve to evaluate. + * @param {Curve} curve - The curve to evaluate. * @param {number} time - The initial time to evaluate the curve at. Defaults to 0. */ constructor(curve, time = 0) { diff --git a/src/core/math/mat3.js b/src/core/math/mat3.js index 3411169f07c..6746d4b30de 100644 --- a/src/core/math/mat3.js +++ b/src/core/math/mat3.js @@ -1,5 +1,10 @@ import { Vec3 } from './vec3.js'; +/** + * @import { Mat4 } from './mat4.js' + * @import { Quat } from './quat.js' + */ + /** * A 3x3 matrix. * @@ -242,7 +247,7 @@ class Mat3 { /** * Converts the specified 4x4 matrix to a Mat3. * - * @param {import('./mat4.js').Mat4} m - The 4x4 matrix to convert. + * @param {Mat4} m - The 4x4 matrix to convert. * @returns {Mat3} Self for chaining. */ setFromMat4(m) { @@ -267,7 +272,7 @@ class Mat3 { /** * Sets this matrix to the given quaternion rotation. * - * @param {import('./quat.js').Quat} r - A quaternion rotation. + * @param {Quat} r - A quaternion rotation. * @returns {Mat3} Self for chaining. * @example * const r = new pc.Quat(1, 2, 3, 4).normalize(); @@ -314,7 +319,7 @@ class Mat3 { /** * Set the matrix to the inverse of the specified 4x4 matrix. * - * @param {import('./mat4.js').Mat4} src - The 4x4 matrix to invert. + * @param {Mat4} src - The 4x4 matrix to invert. * @returns {Mat3} Self for chaining. * * @ignore diff --git a/src/core/math/mat4.js b/src/core/math/mat4.js index a03a922ef40..22b50d9f27c 100644 --- a/src/core/math/mat4.js +++ b/src/core/math/mat4.js @@ -3,6 +3,10 @@ import { Vec2 } from './vec2.js'; import { Vec3 } from './vec3.js'; import { Vec4 } from './vec4.js'; +/** + * @import { Quat } from './quat.js' + */ + const _halfSize = new Vec2(); const x = new Vec3(); const y = new Vec3(); @@ -944,7 +948,7 @@ class Mat4 { * scale. * * @param {Vec3} t - A 3-d vector translation. - * @param {import('./quat.js').Quat} r - A quaternion rotation. + * @param {Quat} r - A quaternion rotation. * @param {Vec3} s - A 3-d vector scale. * @returns {Mat4} Self for chaining. * @example diff --git a/src/core/math/quat.js b/src/core/math/quat.js index e0d3570cde5..9df36c96c34 100644 --- a/src/core/math/quat.js +++ b/src/core/math/quat.js @@ -1,6 +1,10 @@ import { math } from './math.js'; import { Vec3 } from './vec3.js'; +/** + * @import { Mat4 } from './mat4.js' + */ + /** * A quaternion. * @@ -466,7 +470,7 @@ class Quat { * Converts the specified 4x4 matrix to a quaternion. Note that since a quaternion is purely a * representation for orientation, only the translational part of the matrix is lost. * - * @param {import('./mat4.js').Mat4} m - The 4x4 matrix to convert. + * @param {Mat4} m - The 4x4 matrix to convert. * @returns {Quat} Self for chaining. * @example * // Create a 4x4 rotation matrix of 180 degrees around the y-axis diff --git a/src/core/math/random.js b/src/core/math/random.js index 4fddba8218e..aab1147139d 100644 --- a/src/core/math/random.js +++ b/src/core/math/random.js @@ -1,5 +1,10 @@ import { math } from './math.js'; +/** + * @import { Vec2 } from './vec2.js' + * @import { Vec3 } from './vec3.js' + */ + // golden angle in radians: PI * (3 - sqrt(5)) const _goldenAngle = 2.399963229728653; @@ -12,7 +17,7 @@ const random = { /** * Return a pseudo-random 2D point inside a unit circle with uniform distribution. * - * @param {import('./vec2.js').Vec2} point - The returned generated point. + * @param {Vec2} point - The returned generated point. */ circlePoint(point) { const r = Math.sqrt(Math.random()); @@ -25,7 +30,7 @@ const random = { * Generates evenly distributed deterministic points inside a unit circle using Fermat's spiral * and Vogel's method. * - * @param {import('./vec2.js').Vec2} point - The returned generated point. + * @param {Vec2} point - The returned generated point. * @param {number} index - Index of the point to generate, in the range from 0 to numPoints - 1. * @param {number} numPoints - The total number of points of the set. */ @@ -44,7 +49,7 @@ const random = { * sphere). For example by specifying 0.4 and 0.6 and start and end, a band around the equator * would be generated. * - * @param {import('./vec3.js').Vec3} point - The returned generated point. + * @param {Vec3} point - The returned generated point. * @param {number} index - Index of the point to generate, in the range from 0 to numPoints - 1. * @param {number} numPoints - The total number of points of the set. * @param {number} [start] - Part on the sphere along y axis to start the points, in the range diff --git a/src/core/shape/bounding-box.js b/src/core/shape/bounding-box.js index 4837f36670a..379e59cd533 100644 --- a/src/core/shape/bounding-box.js +++ b/src/core/shape/bounding-box.js @@ -1,5 +1,11 @@ import { Vec3 } from '../math/vec3.js'; +/** + * @import { BoundingSphere } from './bounding-sphere.js' + * @import { Mat4 } from '../math/mat4.js' + * @import { Ray } from './ray.js' + */ + const tmpVecA = new Vec3(); const tmpVecB = new Vec3(); const tmpVecC = new Vec3(); @@ -227,7 +233,7 @@ class BoundingBox { /** * Test if a ray intersects with the AABB. * - * @param {import('./ray.js').Ray} ray - Ray to test against (direction must be normalized). + * @param {Ray} ray - Ray to test against (direction must be normalized). * @param {Vec3} [point] - If there is an intersection, the intersection point will be copied * into here. * @returns {boolean} True if there is an intersection. @@ -294,7 +300,7 @@ class BoundingBox { * matrix. * * @param {BoundingBox} aabb - Box to transform and enclose. - * @param {import('../math/mat4.js').Mat4} m - Transformation matrix to apply to source AABB. + * @param {Mat4} m - Transformation matrix to apply to source AABB. * @param {boolean} ignoreScale - If true is specified, a scale from the matrix is ignored. Defaults to false. */ setFromTransformedAabb(aabb, m, ignoreScale = false) { @@ -403,7 +409,7 @@ class BoundingBox { /** * Test if a Bounding Sphere is overlapping, enveloping, or inside this AABB. * - * @param {import('./bounding-sphere.js').BoundingSphere} sphere - Bounding Sphere to test. + * @param {BoundingSphere} sphere - Bounding Sphere to test. * @returns {boolean} True if the Bounding Sphere is overlapping, enveloping, or inside the * AABB and false otherwise. */ diff --git a/src/core/shape/bounding-sphere.js b/src/core/shape/bounding-sphere.js index 4e63c1f81f3..bd145fc4321 100644 --- a/src/core/shape/bounding-sphere.js +++ b/src/core/shape/bounding-sphere.js @@ -1,6 +1,10 @@ import { Debug } from '../debug.js'; import { Vec3 } from '../math/vec3.js'; +/** + * @import { Ray } from './ray.js' + */ + const tmpVecA = new Vec3(); const tmpVecB = new Vec3(); @@ -51,7 +55,7 @@ class BoundingSphere { /** * Test if a ray intersects with the sphere. * - * @param {import('./ray.js').Ray} ray - Ray to test against (direction must be normalized). + * @param {Ray} ray - Ray to test against (direction must be normalized). * @param {Vec3} [point] - If there is an intersection, the intersection point will be copied * into here. * @returns {boolean} True if there is an intersection. diff --git a/src/core/shape/frustum.js b/src/core/shape/frustum.js index e162dc3f3a2..6a4ffbc7c42 100644 --- a/src/core/shape/frustum.js +++ b/src/core/shape/frustum.js @@ -1,5 +1,11 @@ import { Plane } from './plane.js'; +/** + * @import { BoundingSphere } from './bounding-sphere.js' + * @import { Mat4 } from '../math/mat4.js' + * @import { Vec3 } from '../math/vec3.js' + */ + /** * A frustum is a shape that defines the viewing space of a camera. It can be used to determine * visibility of points and bounding spheres. Typically, you would not create a Frustum shape @@ -61,8 +67,7 @@ class Frustum { /** * Updates the frustum shape based on the supplied 4x4 matrix. * - * @param {import('../math/mat4.js').Mat4} matrix - The matrix describing the shape of the - * frustum. + * @param {Mat4} matrix - The matrix describing the shape of the frustum. * @example * // Create a perspective projection matrix * const projection = pc.Mat4(); @@ -93,7 +98,7 @@ class Frustum { * Tests whether a point is inside the frustum. Note that points lying in a frustum plane are * considered to be outside the frustum. * - * @param {import('../math/vec3.js').Vec3} point - The point to test. + * @param {Vec3} point - The point to test. * @returns {boolean} True if the point is inside the frustum, false otherwise. */ containsPoint(point) { @@ -112,7 +117,7 @@ class Frustum { * sphere is completely inside the frustum, 2 is returned. Note that a sphere touching a * frustum plane from the outside is considered to be outside the frustum. * - * @param {import('./bounding-sphere.js').BoundingSphere} sphere - The sphere to test. + * @param {BoundingSphere} sphere - The sphere to test. * @returns {number} 0 if the bounding sphere is outside the frustum, 1 if it intersects the * frustum and 2 if it is contained by the frustum. */ diff --git a/src/core/shape/plane.js b/src/core/shape/plane.js index d129c870dac..13f191b94ba 100644 --- a/src/core/shape/plane.js +++ b/src/core/shape/plane.js @@ -1,5 +1,9 @@ import { Vec3 } from '../math/vec3.js'; +/** + * @import { Ray } from './ray.js' + */ + /** * An infinite plane. Internally it's represented in a parametric equation form: * ax + by + cz + distance = 0. @@ -82,7 +86,7 @@ class Plane { /** * Test if a ray intersects with the infinite plane. * - * @param {import('./ray.js').Ray} ray - Ray to test against (direction must be normalized). + * @param {Ray} ray - Ray to test against (direction must be normalized). * @param {Vec3} [point] - If there is an intersection, the intersection point will be copied * into here. * @returns {boolean} True if there is an intersection. @@ -101,7 +105,7 @@ class Plane { } /** - * Normalize the normal of the plane. + * Normalize the plane. * * @returns {Plane} Self for chaining. */ diff --git a/src/core/shape/tri.js b/src/core/shape/tri.js index 7ddd33075d8..5d11e8b097a 100644 --- a/src/core/shape/tri.js +++ b/src/core/shape/tri.js @@ -1,5 +1,9 @@ import { Vec3 } from '../math/vec3.js'; +/** + * @import { Ray } from './ray.js' + */ + const e1 = new Vec3(); const e2 = new Vec3(); const h = new Vec3(); @@ -83,7 +87,7 @@ class Tri { /** * Test if a ray intersects with the triangle. * - * @param {import('./ray.js').Ray} ray - Ray to test against (direction must be normalized). + * @param {Ray} ray - Ray to test against (direction must be normalized). * @param {Vec3} [point] - If there is an intersection, the intersection point will be copied * into here. * @returns {boolean} True if there is an intersection. diff --git a/src/deprecated/deprecated.js b/src/deprecated/deprecated.js index 53061896743..af1fad142e7 100644 --- a/src/deprecated/deprecated.js +++ b/src/deprecated/deprecated.js @@ -689,8 +689,9 @@ function _deprecateTint(name) { } _deprecateTint('diffuseTint'); +_deprecateTint('emissiveTint'); + _defineAlias('specularTint', 'specularMapTint'); -_defineAlias('emissiveTint', 'emissiveMapTint'); _defineAlias('aoVertexColor', 'aoMapVertexColor'); _defineAlias('diffuseVertexColor', 'diffuseMapVertexColor'); _defineAlias('specularVertexColor', 'specularMapVertexColor'); diff --git a/src/extras/exporters/core-exporter.js b/src/extras/exporters/core-exporter.js index dc485ccd7a7..2516b08538e 100644 --- a/src/extras/exporters/core-exporter.js +++ b/src/extras/exporters/core-exporter.js @@ -5,6 +5,10 @@ import { drawQuadWithShader } from '../../scene/graphics/quad-render-utils.js'; import { RenderTarget } from '../../platform/graphics/render-target.js'; import { FILTER_LINEAR, ADDRESS_CLAMP_TO_EDGE, isCompressedPixelFormat, PIXELFORMAT_RGBA8 } from '../../platform/graphics/constants.js'; +/** + * @import { Color } from '../../core/math/color.js' + */ + const textureBlitVertexShader = /* glsl */` attribute vec2 vertex_position; varying vec2 uv0; @@ -38,7 +42,7 @@ class CoreExporter { * * @param {Texture} texture - The source texture to be converted. * @param {object} options - Object for passing optional arguments. - * @param {import('../../core/math/color.js').Color} [options.color] - The tint color to modify the texture with. + * @param {Color} [options.color] - The tint color to modify the texture with. * @param {number} [options.maxTextureSize] - Maximum texture size. Texture is resized if over the size. * @returns {Promise|Promise} - The canvas element containing the image. * diff --git a/src/extras/exporters/gltf-exporter.js b/src/extras/exporters/gltf-exporter.js index eb70534c313..01230249464 100644 --- a/src/extras/exporters/gltf-exporter.js +++ b/src/extras/exporters/gltf-exporter.js @@ -1,5 +1,10 @@ import { CoreExporter } from './core-exporter.js'; - +import { math } from '../../core/math/math.js'; +import { Vec2 } from '../../core/math/vec2.js'; +import { Vec3 } from '../../core/math/vec3.js'; +import { Quat } from '../../core/math/quat.js'; +import { Color } from '../../core/math/color.js'; +import { BoundingBox } from '../../core/shape/bounding-box.js'; import { CULLFACE_NONE, INDEXFORMAT_UINT8, INDEXFORMAT_UINT16, INDEXFORMAT_UINT32, @@ -12,18 +17,16 @@ import { TYPE_UINT8, TYPE_INT16, TYPE_UINT16, TYPE_INT32, TYPE_UINT32, TYPE_FLOAT32 } from '../../platform/graphics/constants.js'; -import { math } from '../../core/math/math.js'; -import { Vec2 } from '../../core/math/vec2.js'; -import { Vec3 } from '../../core/math/vec3.js'; -import { Quat } from '../../core/math/quat.js'; -import { Color } from '../../core/math/color.js'; -import { BoundingBox } from '../../core/shape/bounding-box.js'; import { IndexBuffer } from '../../platform/graphics/index-buffer.js'; import { VertexBuffer } from '../../platform/graphics/vertex-buffer.js'; import { StandardMaterial } from '../../scene/materials/standard-material.js'; import { BasicMaterial } from '../../scene/materials/basic-material.js'; import { BLEND_NONE, BLEND_NORMAL, PROJECTION_ORTHOGRAPHIC } from '../../scene/constants.js'; +/** + * @import { Entity } from '../../framework/entity.js' + */ + const ARRAY_BUFFER = 34962; const ELEMENT_ARRAY_BUFFER = 34963; @@ -759,7 +762,7 @@ class GltfExporter extends CoreExporter { /** * Converts a hierarchy of entities to GLB format. * - * @param {import('playcanvas').Entity} entity - The root of the entity hierarchy to convert. + * @param {Entity} entity - The root of the entity hierarchy to convert. * @param {object} options - Object for passing optional arguments. * @param {number} [options.maxTextureSize] - Maximum texture size. Texture is resized if over * the size. diff --git a/src/extras/exporters/usdz-exporter.js b/src/extras/exporters/usdz-exporter.js index b73a2c4f355..df923f50ea7 100644 --- a/src/extras/exporters/usdz-exporter.js +++ b/src/extras/exporters/usdz-exporter.js @@ -1,5 +1,6 @@ import { CoreExporter } from "./core-exporter.js"; import { zipSync, strToU8 } from 'fflate'; +import { Color } from '../../core/math/color.js'; import { SEMANTIC_POSITION, @@ -8,7 +9,12 @@ import { SEMANTIC_TEXCOORD1 } from "../../platform/graphics/constants.js"; -import { Color } from '../../core/math/color.js'; +/** + * @import { Entity } from '../../framework/entity.js' + * @import { Material } from '../../scene/materials/material.js' + * @import { Mesh } from '../../scene/mesh.js' + * @import { Texture } from '../../platform/graphics/texture.js' + */ const ROOT_FILE_NAME = 'root'; @@ -74,7 +80,7 @@ class UsdzExporter extends CoreExporter { /** * Maps a mesh to a reference (path) inside the usdz container * - * @type {Map} + * @type {Map} * @ignore */ meshMap; @@ -82,7 +88,7 @@ class UsdzExporter extends CoreExporter { /** * Maps a material to a reference (path) inside the usdz container * - * @type {Map} + * @type {Map} * @ignore */ materialMap; @@ -97,7 +103,7 @@ class UsdzExporter extends CoreExporter { /** * A map of texture requests * - * @type {Map} + * @type {Map} * @ignore */ textureMap; @@ -140,7 +146,7 @@ class UsdzExporter extends CoreExporter { /** * Converts a hierarchy of entities to USDZ format. * - * @param {import('../../framework/entity.js').Entity} entity - The root of the entity hierarchy to convert. + * @param {Entity} entity - The root of the entity hierarchy to convert. * @param {object} options - Object for passing optional arguments. * @param {number} [options.maxTextureSize] - Maximum texture size. Texture is resized if over * the size. diff --git a/src/extras/gizmo/gizmo.js b/src/extras/gizmo/gizmo.js index fb6fface429..2ce1f0fb855 100644 --- a/src/extras/gizmo/gizmo.js +++ b/src/extras/gizmo/gizmo.js @@ -6,6 +6,16 @@ import { EventHandler } from '../../core/event-handler.js'; import { PROJECTION_PERSPECTIVE } from '../../scene/constants.js'; import { Entity } from '../../framework/entity.js'; +/** + * @import { AppBase } from '../../framework/app-base.js' + * @import { CameraComponent } from '../../framework/components/camera/component.js' + * @import { GraphNode } from '../../scene/graph-node.js' + * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js' + * @import { Layer } from '../../scene/layer.js' + * @import { MeshInstance } from '../../scene/mesh-instance.js' + * @import { TriData } from './tri-data.js' + */ + // temporary variables const tmpV1 = new Vec3(); const tmpM1 = new Mat4(); @@ -174,7 +184,7 @@ class Gizmo extends EventHandler { /** * Internal reference to the app containing the gizmo. * - * @type {import('../../framework/app-base.js').AppBase} + * @type {AppBase} * @protected */ _app; @@ -182,7 +192,7 @@ class Gizmo extends EventHandler { /** * Internal reference to the graphics device of the app. * - * @type {import('../../platform/graphics/graphics-device.js').GraphicsDevice} + * @type {GraphicsDevice} * @protected */ _device; @@ -190,7 +200,7 @@ class Gizmo extends EventHandler { /** * Internal reference to camera component to view the gizmo. * - * @type {import('../../framework/components/camera/component.js').CameraComponent} + * @type {CameraComponent} * @protected */ _camera; @@ -198,7 +208,7 @@ class Gizmo extends EventHandler { /** * Internal reference to layer to render the gizmo.. * - * @type {import('../../scene/layer.js').Layer} + * @type {Layer} * @protected */ _layer; @@ -206,24 +216,24 @@ class Gizmo extends EventHandler { /** * The graph nodes attached to the gizmo. * - * @type {import('../../scene/graph-node.js').GraphNode[]} + * @type {GraphNode[]} */ nodes = []; /** * The root gizmo entity. * - * @type {import('../../framework/entity.js').Entity} + * @type {Entity} */ root; /** * @typedef IntersectData - * @property {import('./tri-data.js').TriData[]} triData - The array of {@link TriData} - * @property {import('../../scene/graph-node.js').GraphNode} parent - The mesh parent node. - * @property {import('../../scene/mesh-instance.js').MeshInstance[]} meshInstances - - * array of mesh instances for rendering + * @property {TriData[]} triData - The array of {@link TriData}. + * @property {GraphNode} parent - The mesh parent node. + * @property {MeshInstance[]} meshInstances - Array of mesh instances for rendering. */ + /** * The intersection data object. * @@ -234,10 +244,9 @@ class Gizmo extends EventHandler { /** * Creates a new Gizmo object. * - * @param {import('../../framework/app-base.js').AppBase} app - The application instance. - * @param {import('../../framework/components/camera/component.js').CameraComponent} camera - - * The camera component. - * @param {import('../../scene/layer.js').Layer} layer - The render layer. + * @param {AppBase} app - The application instance. + * @param {CameraComponent} camera - The camera component. + * @param {Layer} layer - The render layer. * @example * const gizmo = new pc.Gizmo(app, camera, layer); */ @@ -259,8 +268,8 @@ class Gizmo extends EventHandler { this._onPointerMove = this._onPointerMove.bind(this); this._onPointerUp = this._onPointerUp.bind(this); - this._device.canvas.addEventListener('pointerdown', this._onPointerDown); - this._device.canvas.addEventListener('pointermove', this._onPointerMove); + this._device.canvas.addEventListener('pointerdown', this._onPointerDown, true); + this._device.canvas.addEventListener('pointermove', this._onPointerMove, true); this._device.canvas.addEventListener('pointerup', this._onPointerUp); app.on('update', () => this._updateScale()); @@ -402,7 +411,7 @@ class Gizmo extends EventHandler { /** * @param {number} x - The x coordinate. * @param {number} y - The y coordinate. - * @returns {import('../../scene/mesh-instance.js').MeshInstance[]} - The mesh instances. + * @returns {MeshInstance[]} - The mesh instances. * @private */ _getSelection(x, y) { @@ -454,7 +463,7 @@ class Gizmo extends EventHandler { /** * Attach an array of graph nodes to the gizmo. * - * @param {import('../../scene/graph-node.js').GraphNode[]} [nodes] - The graph nodes. Defaults to []. + * @param {GraphNode[]} [nodes] - The graph nodes. Defaults to []. * @example * const gizmo = new pc.Gizmo(app, camera, layer); * gizmo.attach([boxA, boxB]); @@ -493,8 +502,7 @@ class Gizmo extends EventHandler { } /** - * Destroys the gizmo instance; detaches - * all graph nodes. + * Detaches all graph nodes and destroys the gizmo instance. * * @example * const gizmo = new pc.Gizmo(app, camera, layer); diff --git a/src/extras/gizmo/rotate-gizmo.js b/src/extras/gizmo/rotate-gizmo.js index 2d12f08d6aa..01e32a93ac8 100644 --- a/src/extras/gizmo/rotate-gizmo.js +++ b/src/extras/gizmo/rotate-gizmo.js @@ -4,11 +4,17 @@ import { Quat } from '../../core/math/quat.js'; import { Mat4 } from '../../core/math/mat4.js'; import { Vec3 } from '../../core/math/vec3.js'; import { PROJECTION_ORTHOGRAPHIC, PROJECTION_PERSPECTIVE } from '../../scene/constants.js'; - import { AxisDisk } from './axis-shapes.js'; import { GIZMO_LOCAL } from './gizmo.js'; import { SHAPEAXIS_FACE, SHAPEAXIS_X, SHAPEAXIS_Y, SHAPEAXIS_Z, TransformGizmo } from "./transform-gizmo.js"; +/** + * @import { AppBase } from '../../framework/app-base.js' + * @import { CameraComponent } from '../../framework/components/camera/component.js' + * @import { GraphNode } from '../../scene/graph-node.js' + * @import { Layer } from '../../scene/layer.js' + */ + // temporary variables const tmpV1 = new Vec3(); const tmpV2 = new Vec3(); @@ -65,7 +71,7 @@ class RotateGizmo extends TransformGizmo { /** * Internal mapping from each attached node to their starting rotation in local space. * - * @type {Map} + * @type {Map} * @private */ _nodeLocalRotations = new Map(); @@ -73,7 +79,7 @@ class RotateGizmo extends TransformGizmo { /** * Internal mapping from each attached node to their starting rotation in world space. * - * @type {Map} + * @type {Map} * @private */ _nodeRotations = new Map(); @@ -81,7 +87,7 @@ class RotateGizmo extends TransformGizmo { /** * Internal mapping from each attached node to their offset position from the gizmo. * - * @type {Map} + * @type {Map} * @private */ _nodeOffsets = new Map(); @@ -118,10 +124,9 @@ class RotateGizmo extends TransformGizmo { /** * Creates a new RotateGizmo object. * - * @param {import('../../framework/app-base.js').AppBase} app - The application instance. - * @param {import('../../framework/components/camera/component.js').CameraComponent} camera - - * The camera component. - * @param {import('../../scene/layer.js').Layer} layer - The render layer. + * @param {AppBase} app - The application instance. + * @param {CameraComponent} camera - The camera component. + * @param {Layer} layer - The render layer. * @example * const gizmo = new pc.RotateGizmo(app, camera, layer); */ diff --git a/src/extras/gizmo/scale-gizmo.js b/src/extras/gizmo/scale-gizmo.js index 0a6a2307175..8c332a5cf9c 100644 --- a/src/extras/gizmo/scale-gizmo.js +++ b/src/extras/gizmo/scale-gizmo.js @@ -1,10 +1,16 @@ import { Vec3 } from '../../core/math/vec3.js'; import { Quat } from '../../core/math/quat.js'; - import { AxisBoxCenter, AxisBoxLine, AxisPlane } from './axis-shapes.js'; import { GIZMO_LOCAL } from './gizmo.js'; import { SHAPEAXIS_X, SHAPEAXIS_XYZ, SHAPEAXIS_Y, SHAPEAXIS_Z, TransformGizmo } from './transform-gizmo.js'; +/** + * @import { AppBase } from '../../framework/app-base.js' + * @import { CameraComponent } from '../../framework/components/camera/component.js' + * @import { GraphNode } from '../../scene/graph-node.js' + * @import { Layer } from '../../scene/layer.js' + */ + // temporary variables const tmpV1 = new Vec3(); const tmpV2 = new Vec3(); @@ -75,7 +81,7 @@ class ScaleGizmo extends TransformGizmo { /** * Internal mapping from each attached node to their starting scale. * - * @type {Map} + * @type {Map} * @private */ _nodeScales = new Map(); @@ -96,10 +102,9 @@ class ScaleGizmo extends TransformGizmo { /** * Creates a new ScaleGizmo object. * - * @param {import('../../framework/app-base.js').AppBase} app - The application instance. - * @param {import('../../framework/components/camera/component.js').CameraComponent} camera - - * The camera component. - * @param {import('../../scene/layer.js').Layer} layer - The render layer. + * @param {AppBase} app - The application instance. + * @param {CameraComponent} camera - The camera component. + * @param {Layer} layer - The render layer. * @example * const gizmo = new pc.ScaleGizmo(app, camera, layer); */ diff --git a/src/extras/gizmo/transform-gizmo.js b/src/extras/gizmo/transform-gizmo.js index f202fa9fca4..4fc4c4a9f22 100644 --- a/src/extras/gizmo/transform-gizmo.js +++ b/src/extras/gizmo/transform-gizmo.js @@ -5,6 +5,7 @@ import { Vec3 } from '../../core/math/vec3.js'; import { Ray } from '../../core/shape/ray.js'; import { Plane } from '../../core/shape/plane.js'; import { PROJECTION_PERSPECTIVE } from '../../scene/constants.js'; +import { Gizmo } from "./gizmo.js"; import { COLOR_RED, @@ -13,7 +14,14 @@ import { COLOR_YELLOW, COLOR_GRAY } from './default-colors.js'; -import { Gizmo } from "./gizmo.js"; + +/** + * @import { AppBase } from '../../framework/app-base.js' + * @import { AxisShape } from './axis-shapes.js' + * @import { CameraComponent } from '../../framework/components/camera/component.js' + * @import { Layer } from '../../scene/layer.js' + * @import { MeshInstance } from '../../scene/mesh-instance.js' + */ // temporary variables const tmpV1 = new Vec3(); @@ -143,7 +151,7 @@ class TransformGizmo extends Gizmo { _colorAlpha = 0.6; /** - * Internal color for meshs. + * Internal color for meshes. * * @type {Object} * @protected @@ -207,7 +215,7 @@ class TransformGizmo extends Gizmo { /** * Internal object containing the axis shapes to render. * - * @type {Object.} + * @type {Object.} * @protected */ _shapes = {}; @@ -215,7 +223,7 @@ class TransformGizmo extends Gizmo { /** * Internal mapping of mesh instances to axis shapes. * - * @type {Map} + * @type {Map} * @private */ _shapeMap = new Map(); @@ -223,7 +231,7 @@ class TransformGizmo extends Gizmo { /** * Internal currently hovered shape. * - * @type {import('./axis-shapes.js').AxisShape | null} + * @type {AxisShape | null} * @private */ _hoverShape = null; @@ -302,10 +310,9 @@ class TransformGizmo extends Gizmo { /** * Creates a new TransformGizmo object. * - * @param {import('../../framework/app-base.js').AppBase} app - The application instance. - * @param {import('../../framework/components/camera/component.js').CameraComponent} camera - - * The camera component. - * @param {import('../../scene/layer.js').Layer} layer - The render layer. + * @param {AppBase} app - The application instance. + * @param {CameraComponent} camera - The camera component. + * @param {Layer} layer - The render layer. * @example * const gizmo = new pc.TransformGizmo(app, camera, layer); */ @@ -515,7 +522,7 @@ class TransformGizmo extends Gizmo { } /** - * @param {import('../../scene/mesh-instance.js').MeshInstance} [meshInstance] - The mesh instance. + * @param {MeshInstance} [meshInstance] - The mesh instance. * @returns {string} - The axis. * @private */ @@ -527,7 +534,7 @@ class TransformGizmo extends Gizmo { } /** - * @param {import('../../scene/mesh-instance.js').MeshInstance} [meshInstance] - The mesh instance. + * @param {MeshInstance} [meshInstance] - The mesh instance. * @returns {boolean} - Whether the mesh instance is a plane. * @private */ @@ -539,7 +546,7 @@ class TransformGizmo extends Gizmo { } /** - * @param {import('../../scene/mesh-instance.js').MeshInstance} [meshInstance] - The mesh instance. + * @param {MeshInstance} [meshInstance] - The mesh instance. * @private */ _hover(meshInstance) { @@ -722,14 +729,14 @@ class TransformGizmo extends Gizmo { * * @param {string} shapeAxis - The shape axis. Can be: * - * {@link SHAPEAXIS_X} - * {@link SHAPEAXIS_Y} - * {@link SHAPEAXIS_Z} - * {@link SHAPEAXIS_YZ} - * {@link SHAPEAXIS_XZ} - * {@link SHAPEAXIS_XY} - * {@link SHAPEAXIS_XYZ} - * {@link SHAPEAXIS_FACE} + * - {@link SHAPEAXIS_X} + * - {@link SHAPEAXIS_Y} + * - {@link SHAPEAXIS_Z} + * - {@link SHAPEAXIS_YZ} + * - {@link SHAPEAXIS_XZ} + * - {@link SHAPEAXIS_XY} + * - {@link SHAPEAXIS_XYZ} + * - {@link SHAPEAXIS_FACE} * * @param {boolean} enabled - The enabled state of shape. */ @@ -746,14 +753,14 @@ class TransformGizmo extends Gizmo { * * @param {string} shapeAxis - The shape axis. Can be: * - * {@link SHAPEAXIS_X} - * {@link SHAPEAXIS_Y} - * {@link SHAPEAXIS_Z} - * {@link SHAPEAXIS_YZ} - * {@link SHAPEAXIS_XZ} - * {@link SHAPEAXIS_XY} - * {@link SHAPEAXIS_XYZ} - * {@link SHAPEAXIS_FACE} + * - {@link SHAPEAXIS_X} + * - {@link SHAPEAXIS_Y} + * - {@link SHAPEAXIS_Z} + * - {@link SHAPEAXIS_YZ} + * - {@link SHAPEAXIS_XZ} + * - {@link SHAPEAXIS_XY} + * - {@link SHAPEAXIS_XYZ} + * - {@link SHAPEAXIS_FACE} * * @returns {boolean} - Then enabled state of the shape */ diff --git a/src/extras/gizmo/translate-gizmo.js b/src/extras/gizmo/translate-gizmo.js index d28f31cd714..7a2c2457a17 100644 --- a/src/extras/gizmo/translate-gizmo.js +++ b/src/extras/gizmo/translate-gizmo.js @@ -1,8 +1,8 @@ import { Vec3 } from '../../core/math/vec3.js'; import { Quat } from '../../core/math/quat.js'; - import { AxisArrow, AxisPlane, AxisSphereCenter } from './axis-shapes.js'; import { GIZMO_LOCAL } from './gizmo.js'; + import { SHAPEAXIS_FACE, SHAPEAXIS_X, @@ -11,6 +11,13 @@ import { TransformGizmo } from './transform-gizmo.js'; +/** + * @import { AppBase } from '../../framework/app-base.js' + * @import { CameraComponent } from '../../framework/components/camera/component.js' + * @import { GraphNode } from '../../scene/graph-node.js' + * @import { Layer } from '../../scene/layer.js' + */ + // temporary variables const tmpV1 = new Vec3(); const tmpV2 = new Vec3(); @@ -79,7 +86,7 @@ class TranslateGizmo extends TransformGizmo { /** * Internal mapping from each attached node to their starting position in local space. * - * @type {Map} + * @type {Map} * @private */ _nodeLocalPositions = new Map(); @@ -87,7 +94,7 @@ class TranslateGizmo extends TransformGizmo { /** * Internal mapping from each attached node to their starting position in world space. * - * @type {Map} + * @type {Map} * @private */ _nodePositions = new Map(); @@ -100,10 +107,9 @@ class TranslateGizmo extends TransformGizmo { /** * Creates a new TranslateGizmo object. * - * @param {import('../../framework/app-base.js').AppBase} app - The application instance. - * @param {import('../../framework/components/camera/component.js').CameraComponent} camera - - * The camera component. - * @param {import('../../scene/layer.js').Layer} layer - The render layer. + * @param {AppBase} app - The application instance. + * @param {CameraComponent} camera - The camera component. + * @param {Layer} layer - The render layer. * @example * const gizmo = new pc.TranslateGizmo(app, camera, layer); */ diff --git a/src/extras/mini-stats/mini-stats.js b/src/extras/mini-stats/mini-stats.js index 0c10ff559c0..f01b78fe211 100644 --- a/src/extras/mini-stats/mini-stats.js +++ b/src/extras/mini-stats/mini-stats.js @@ -2,7 +2,6 @@ import { math } from '../../core/math/math.js'; import { Texture } from '../../platform/graphics/texture.js'; import { ADDRESS_REPEAT, FILTER_NEAREST } from '../../platform/graphics/constants.js'; import { LAYERID_UI } from '../../scene/constants.js'; - import { CpuTimer } from './cpu-timer.js'; import { GpuTimer } from './gpu-timer.js'; import { StatsTimer } from './stats-timer.js'; @@ -10,6 +9,11 @@ import { Graph } from './graph.js'; import { WordAtlas } from './word-atlas.js'; import { Render2d } from './render2d.js'; +/** + * @import { AppBase } from '../../framework/app-base.js' + * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js' + */ + /** * MiniStats is a small graphical overlay that displays realtime performance metrics. By default, * it shows CPU and GPU utilization, frame timings and draw call count. It can also be configured @@ -19,7 +23,7 @@ class MiniStats { /** * Create a new MiniStats instance. * - * @param {import('../../framework/app-base.js').AppBase} app - The application. + * @param {AppBase} app - The application. * @param {object} [options] - Options for the MiniStats instance. * @param {object[]} [options.sizes] - Sizes of area to render individual graphs in and spacing * between individual graphs. @@ -280,8 +284,8 @@ class MiniStats { /** * Create the graphs requested by the user and add them to the MiniStats instance. * - * @param {import('../../framework/app-base.js').AppBase} app - The application. - * @param {import('../../platform/graphics/graphics-device.js').GraphicsDevice} device - The graphics device. + * @param {AppBase} app - The application. + * @param {GraphicsDevice} device - The graphics device. * @param {object} options - Options for the MiniStats instance. * @private */ diff --git a/src/extras/render-passes/render-pass-prepass.js b/src/extras/render-passes/render-pass-prepass.js index 8f3592b7a4b..1def214a14f 100644 --- a/src/extras/render-passes/render-pass-prepass.js +++ b/src/extras/render-passes/render-pass-prepass.js @@ -1,7 +1,3 @@ -import { - LAYERID_DEPTH, - SHADER_PREPASS_VELOCITY -} from '../../scene/constants.js'; import { FILTER_NEAREST, PIXELFORMAT_RGBA32F, @@ -12,6 +8,15 @@ import { Texture } from '../../platform/graphics/texture.js'; import { RenderPass } from '../../platform/graphics/render-pass.js'; import { RenderTarget } from '../../platform/graphics/render-target.js'; +import { + LAYERID_DEPTH, + SHADER_PREPASS_VELOCITY +} from '../../scene/constants.js'; + +/** + * @import { BindGroup } from '../../platform/graphics/bind-group.js' + */ + const tempMeshInstances = []; // uniform name of the depth texture @@ -29,7 +34,7 @@ const VELOCITY_UNIFORM_NAME = 'uSceneVelocityMap'; * @ignore */ class RenderPassPrepass extends RenderPass { - /** @type {import('../../platform/graphics/bind-group.js').BindGroup[]} */ + /** @type {BindGroup[]} */ viewBindGroups = []; /** @type {Texture} */ diff --git a/src/framework/anim/binder/anim-binder.js b/src/framework/anim/binder/anim-binder.js index ff08cc39892..49f0f7a1f59 100644 --- a/src/framework/anim/binder/anim-binder.js +++ b/src/framework/anim/binder/anim-binder.js @@ -1,3 +1,7 @@ +/** + * @import { AnimTarget } from '../evaluator/anim-target.js' + */ + /** * This interface is used by {@link AnimEvaluator} to resolve unique animation target path strings * into instances of {@link AnimTarget}. @@ -70,7 +74,7 @@ class AnimBinder { * handle setting the value, or return null if no such target exists. * * @param {string} path - The animation curve path to resolve. - * @returns {import('../evaluator/anim-target.js').AnimTarget|null} - Returns the target + * @returns {AnimTarget|null} - Returns the target * instance on success and null otherwise. */ resolve(path) { diff --git a/src/framework/anim/binder/default-anim-binder.js b/src/framework/anim/binder/default-anim-binder.js index a68b5a3aa42..0babc193afc 100644 --- a/src/framework/anim/binder/default-anim-binder.js +++ b/src/framework/anim/binder/default-anim-binder.js @@ -2,6 +2,7 @@ import { Debug } from '../../../core/debug.js'; import { AnimBinder } from './anim-binder.js'; import { AnimTarget } from '../evaluator/anim-target.js'; import { Entity } from '../../entity.js'; + /** * Implementation of {@link AnimBinder} for animating a skeleton in the graph-node hierarchy. * diff --git a/src/framework/anim/controller/anim-blend-tree-1d.js b/src/framework/anim/controller/anim-blend-tree-1d.js index 0bb8eff0629..f4adebaca73 100644 --- a/src/framework/anim/controller/anim-blend-tree-1d.js +++ b/src/framework/anim/controller/anim-blend-tree-1d.js @@ -1,7 +1,11 @@ import { math } from '../../../core/math/math.js'; - import { AnimBlendTree } from './anim-blend-tree.js'; +/** + * @import { AnimState } from './anim-state.js' + * @import { Vec2 } from '../../../core/math/vec2.js' + */ + /** * An AnimBlendTree that calculates its weights using a 1D algorithm based on the thesis * http://runevision.com/thesis/rune_skovbo_johansen_thesis.pdf Chapter 6. @@ -10,14 +14,13 @@ class AnimBlendTree1D extends AnimBlendTree { /** * Create a new BlendTree1D instance. * - * @param {import('./anim-state.js').AnimState} state - The AnimState that this AnimBlendTree - * belongs to. + * @param {AnimState} state - The AnimState that this AnimBlendTree belongs to. * @param {AnimBlendTree|null} parent - The parent of the AnimBlendTree. If not null, the * AnimNode is stored as part of a {@link AnimBlendTree} hierarchy. * @param {string} name - The name of the BlendTree. Used when assigning an {@link AnimTrack} * to its children. - * @param {number|import('../../../core/math/vec2.js').Vec2} point - The coordinate/vector - * that's used to determine the weight of this node when it's part of an {@link AnimBlendTree}. + * @param {number|Vec2} point - The coordinate/vector that's used to determine the weight of + * this node when it's part of an {@link AnimBlendTree}. * @param {string[]} parameters - The anim component parameters which are used to calculate the * current weights of the blend trees children. * @param {object[]} children - The child nodes that this blend tree should create. Can either diff --git a/src/framework/anim/controller/anim-blend-tree.js b/src/framework/anim/controller/anim-blend-tree.js index 65f54e3eac9..2111e093360 100644 --- a/src/framework/anim/controller/anim-blend-tree.js +++ b/src/framework/anim/controller/anim-blend-tree.js @@ -1,5 +1,10 @@ import { AnimNode } from './anim-node.js'; +/** + * @import { AnimState } from './anim-state.js' + * @import { Vec2 } from '../../../core/math/vec2.js' + */ + /** * BlendTrees are used to store and blend multiple AnimNodes together. BlendTrees can be the child * of other AnimBlendTrees, in order to create a hierarchy of AnimNodes. It takes a blend type as @@ -10,14 +15,13 @@ class AnimBlendTree extends AnimNode { /** * Create a new AnimBlendTree instance. * - * @param {import('./anim-state.js').AnimState} state - The AnimState that this AnimBlendTree - * belongs to. + * @param {AnimState} state - The AnimState that this AnimBlendTree belongs to. * @param {AnimBlendTree|null} parent - The parent of the AnimBlendTree. If not null, the * AnimNode is stored as part of a {@link AnimBlendTree} hierarchy. * @param {string} name - The name of the BlendTree. Used when assigning an {@link AnimTrack} * to its children. - * @param {number|import('../../../core/math/vec2.js').Vec2} point - The coordinate/vector - * that's used to determine the weight of this node when it's part of an {@link AnimBlendTree}. + * @param {number|Vec2} point - The coordinate/vector that's used to determine the weight of + * this node when it's part of an {@link AnimBlendTree}. * @param {string[]} parameters - The anim component parameters which are used to calculate the * current weights of the blend trees children. * @param {object[]} children - The child nodes that this blend tree should create. Can either diff --git a/src/framework/anim/controller/anim-controller.js b/src/framework/anim/controller/anim-controller.js index 0744c4ee2eb..0e968529653 100644 --- a/src/framework/anim/controller/anim-controller.js +++ b/src/framework/anim/controller/anim-controller.js @@ -1,15 +1,20 @@ import { Debug } from '../../../core/debug.js'; import { sortPriority } from '../../../core/sort.js'; import { AnimClip } from '../evaluator/anim-clip.js'; -import { AnimState } from './anim-state.js'; -import { AnimNode } from './anim-node.js'; -import { AnimTransition } from './anim-transition.js'; import { ANIM_GREATER_THAN, ANIM_LESS_THAN, ANIM_GREATER_THAN_EQUAL_TO, ANIM_LESS_THAN_EQUAL_TO, ANIM_EQUAL_TO, ANIM_NOT_EQUAL_TO, ANIM_INTERRUPTION_NONE, ANIM_INTERRUPTION_PREV, ANIM_INTERRUPTION_NEXT, ANIM_INTERRUPTION_PREV_NEXT, ANIM_INTERRUPTION_NEXT_PREV, ANIM_PARAMETER_TRIGGER, ANIM_STATE_START, ANIM_STATE_END, ANIM_STATE_ANY, ANIM_CONTROL_STATES } from './constants.js'; +import { AnimState } from './anim-state.js'; +import { AnimNode } from './anim-node.js'; +import { AnimTransition } from './anim-transition.js'; + +/** + * @import { AnimEvaluator } from '../evaluator/anim-evaluator.js' + * @import { EventHandler } from '../../../core/event-handler.js' + */ /** * The AnimController manages the animations for its entity, based on the provided state graph and @@ -98,16 +103,16 @@ class AnimController { /** * Create a new AnimController. * - * @param {import('../evaluator/anim-evaluator.js').AnimEvaluator} animEvaluator - The - * animation evaluator used to blend all current playing animation keyframes and update the - * entities properties based on the current animation values. + * @param {AnimEvaluator} animEvaluator - The animation evaluator used to blend all current + * playing animation keyframes and update the entities properties based on the current + * animation values. * @param {object[]} states - The list of states used to form the controller state graph. * @param {object[]} transitions - The list of transitions used to form the controller state * graph. * @param {boolean} activate - Determines whether the anim controller should automatically play * once all {@link AnimNodes} are assigned animations. - * @param {import('../../../core/event-handler.js').EventHandler} eventHandler - The event - * handler which should be notified with anim events. + * @param {EventHandler} eventHandler - The event handler which should be notified with anim + * events. * @param {Function} findParameter - Retrieves a parameter which is used to control the * transition between states. * @param {Function} consumeTrigger - Used to set triggers back to their default state after diff --git a/src/framework/anim/controller/anim-node.js b/src/framework/anim/controller/anim-node.js index c05d3b698e9..3e3acd742e5 100644 --- a/src/framework/anim/controller/anim-node.js +++ b/src/framework/anim/controller/anim-node.js @@ -1,5 +1,10 @@ import { Vec2 } from '../../../core/math/vec2.js'; +/** + * @import { AnimBlendTree } from './anim-blend-tree.js' + * @import { AnimState } from './anim-state.js' + */ + /** * AnimNodes are used to represent a single animation track in the current state. Each state can * contain multiple AnimNodes, in which case they are stored in a BlendTree hierarchy, which will @@ -9,10 +14,9 @@ class AnimNode { /** * Create a new AnimNode instance. * - * @param {import('./anim-state.js').AnimState} state - The AnimState that this BlendTree - * belongs to. - * @param {import('./anim-blend-tree.js').AnimBlendTree|null} parent - The parent of the AnimNode. - * If not null, the AnimNode is stored as part of an {@link AnimBlendTree} hierarchy. + * @param {AnimState} state - The AnimState that this BlendTree belongs to. + * @param {AnimBlendTree|null} parent - The parent of the AnimNode. If not null, the AnimNode + * is stored as part of an {@link AnimBlendTree} hierarchy. * @param {string} name - The name of the AnimNode. Used when assigning an {@link AnimTrack} to * it. * @param {number[]|number} point - The coordinate/vector thats used to determine the weight of diff --git a/src/framework/anim/controller/anim-state.js b/src/framework/anim/controller/anim-state.js index 6d2078f9753..ddee00bf10a 100644 --- a/src/framework/anim/controller/anim-state.js +++ b/src/framework/anim/controller/anim-state.js @@ -1,14 +1,17 @@ import { Debug } from '../../../core/debug.js'; import { AnimTrack } from '../evaluator/anim-track.js'; - +import { + ANIM_BLEND_1D, ANIM_BLEND_2D_CARTESIAN, ANIM_BLEND_2D_DIRECTIONAL, ANIM_BLEND_DIRECT, ANIM_CONTROL_STATES +} from './constants.js'; import { AnimBlendTree1D } from './anim-blend-tree-1d.js'; import { AnimBlendTreeCartesian2D } from './anim-blend-tree-2d-cartesian.js'; import { AnimBlendTreeDirectional2D } from './anim-blend-tree-2d-directional.js'; import { AnimBlendTreeDirect } from './anim-blend-tree-direct.js'; import { AnimNode } from './anim-node.js'; -import { - ANIM_BLEND_1D, ANIM_BLEND_2D_CARTESIAN, ANIM_BLEND_2D_DIRECTIONAL, ANIM_BLEND_DIRECT, ANIM_CONTROL_STATES -} from './constants.js'; + +/** + * @import { AnimController } from './anim-controller.js' + */ /** * Defines a single state that the controller can be in. Each state contains either a single @@ -26,7 +29,7 @@ class AnimState { /** * Create a new AnimState instance. * - * @param {import('./anim-controller.js').AnimController} controller - The controller this + * @param {AnimController} controller - The controller this * AnimState is associated with. * @param {string} name - The name of the state. Used to find this state when the controller * transitions between states and links animations. diff --git a/src/framework/anim/evaluator/anim-clip.js b/src/framework/anim/evaluator/anim-clip.js index 5edba2d97bc..716a10e4931 100644 --- a/src/framework/anim/evaluator/anim-clip.js +++ b/src/framework/anim/evaluator/anim-clip.js @@ -1,5 +1,10 @@ import { AnimSnapshot } from './anim-snapshot.js'; +/** + * @import { AnimTrack } from './anim-track.js' + * @import { EventHandler } from '../../../core/event-handler.js' + */ + // TODO: add configurable looping start/end times? /** @@ -18,13 +23,12 @@ class AnimClip { /** * Create a new animation clip. * - * @param {import('./anim-track.js').AnimTrack} track - The animation data. + * @param {AnimTrack} track - The animation data. * @param {number} time - The initial time of the clip. * @param {number} speed - Speed of the animation playback. * @param {boolean} playing - true if the clip is playing and false otherwise. * @param {boolean} loop - Whether the clip should loop. - * @param {import('../../../core/event-handler.js').EventHandler} [eventHandler] - The handler - * to call when an event is fired by the clip. + * @param {EventHandler} [eventHandler] - The handler to call when an event is fired by the clip. */ constructor(track, time, speed, playing, loop, eventHandler) { this._name = track.name; // default to track name diff --git a/src/framework/anim/evaluator/anim-evaluator.js b/src/framework/anim/evaluator/anim-evaluator.js index 14508910b75..8baf3cd1774 100644 --- a/src/framework/anim/evaluator/anim-evaluator.js +++ b/src/framework/anim/evaluator/anim-evaluator.js @@ -1,6 +1,11 @@ import { AnimTargetValue } from './anim-target-value.js'; import { AnimBlend } from './anim-blend.js'; +/** + * @import { AnimBinder } from '../binder/anim-binder.js' + * @import { AnimClip } from './anim-clip.js' + */ + /** * AnimEvaluator blends multiple sets of animation clips together. * @@ -10,8 +15,8 @@ class AnimEvaluator { /** * Create a new animation evaluator. * - * @param {import('../binder/anim-binder.js').AnimBinder} binder - interface resolves curve - * paths to instances of {@link AnimTarget}. + * @param {AnimBinder} binder - Interface that resolves curve paths to instances of + * {@link AnimTarget}. */ constructor(binder) { this._binder = binder; @@ -24,7 +29,7 @@ class AnimEvaluator { /** * The list of animation clips. * - * @type {import('./anim-clip.js').AnimClip[]} + * @type {AnimClip[]} */ get clips() { return this._clips; @@ -33,7 +38,7 @@ class AnimEvaluator { /** * Add a clip to the evaluator. * - * @param {import('./anim-clip.js').AnimClip} clip - The clip to add to the evaluator. + * @param {AnimClip} clip - The clip to add to the evaluator. */ addClip(clip) { const targets = this._targets; @@ -159,7 +164,7 @@ class AnimEvaluator { * Returns the first clip which matches the given name, or null if no such clip was found. * * @param {string} name - Name of the clip to find. - * @returns {import('./anim-clip.js').AnimClip|null} - The clip with the given name or null if no such clip was found. + * @returns {AnimClip|null} - The clip with the given name or null if no such clip was found. */ findClip(name) { const clips = this._clips; diff --git a/src/framework/anim/evaluator/anim-snapshot.js b/src/framework/anim/evaluator/anim-snapshot.js index f88f842b9bc..3ffc725aa7d 100644 --- a/src/framework/anim/evaluator/anim-snapshot.js +++ b/src/framework/anim/evaluator/anim-snapshot.js @@ -1,5 +1,9 @@ import { AnimCache } from './anim-cache.js'; +/** + * @import { AnimTrack } from './anim-track.js' + */ + /** * AnimSnapshot stores the state of an animation track at a particular time. * @@ -9,7 +13,7 @@ class AnimSnapshot { /** * Create a new animation snapshot. * - * @param {import('./anim-track.js').AnimTrack} animTrack - The source track. + * @param {AnimTrack} animTrack - The source track. */ constructor(animTrack) { this._name = animTrack.name + 'Snapshot'; diff --git a/src/framework/anim/evaluator/anim-target-value.js b/src/framework/anim/evaluator/anim-target-value.js index ba175f30593..d5ee88e5860 100644 --- a/src/framework/anim/evaluator/anim-target-value.js +++ b/src/framework/anim/evaluator/anim-target-value.js @@ -3,6 +3,10 @@ import { ANIM_LAYER_ADDITIVE, ANIM_LAYER_OVERWRITE } from '../controller/constan import { AnimBlend } from './anim-blend.js'; import { math } from '../../../core/math/math.js'; +/** + * @import { AnimComponent } from '../../components/anim/component.js' + */ + /** * Used to store and update the value of an animation target. This combines the values of multiple * layer targets into a single value. diff --git a/src/framework/anim/evaluator/anim-track.js b/src/framework/anim/evaluator/anim-track.js index c48c8dec28f..6da503c9b28 100644 --- a/src/framework/anim/evaluator/anim-track.js +++ b/src/framework/anim/evaluator/anim-track.js @@ -1,5 +1,10 @@ import { AnimEvents } from './anim-events.js'; +/** + * @import { AnimCurve } from './anim-curve.js' + * @import { AnimData } from './anim-data.js' + */ + /** * An AnimTrack stores the curve data necessary to animate a set of target nodes. It can be linked * to the nodes it should animate using the {@link AnimComponent#assignAnimation} method. @@ -20,9 +25,9 @@ class AnimTrack { * * @param {string} name - The track name. * @param {number} duration - The duration of the track in seconds. - * @param {import('./anim-data.js').AnimData[]} inputs - List of curve key data. - * @param {import('./anim-data.js').AnimData[]} outputs - List of curve value data. - * @param {import('./anim-curve.js').AnimCurve[]} curves - The list of curves. + * @param {AnimData[]} inputs - List of curve key data. + * @param {AnimData[]} outputs - List of curve value data. + * @param {AnimCurve[]} curves - The list of curves. * @param {AnimEvents} animEvents - A sequence of animation events. * @ignore */ @@ -56,7 +61,7 @@ class AnimTrack { /** * Gets the list of curve key data contained in the AnimTrack. * - * @type {import('./anim-data.js').AnimData[]} + * @type {AnimData[]} */ get inputs() { return this._inputs; @@ -65,7 +70,7 @@ class AnimTrack { /** * Gets the list of curve values contained in the AnimTrack. * - * @type {import('./anim-data.js').AnimData[]} + * @type {AnimData[]} */ get outputs() { return this._outputs; @@ -74,7 +79,7 @@ class AnimTrack { /** * Gets the list of curves contained in the AnimTrack. * - * @type {import('./anim-curve.js').AnimCurve[]} + * @type {AnimCurve[]} */ get curves() { return this._curves; diff --git a/src/framework/app-base.js b/src/framework/app-base.js index 5cc3c029fb2..200346c956a 100644 --- a/src/framework/app-base.js +++ b/src/framework/app-base.js @@ -35,6 +35,10 @@ import { Material } from '../scene/materials/material.js'; import { StandardMaterial } from '../scene/materials/standard-material.js'; import { setDefaultMaterial } from '../scene/materials/default-material.js'; +import { + FILLMODE_FILL_WINDOW, FILLMODE_KEEP_ASPECT, + RESOLUTION_AUTO, RESOLUTION_FIXED +} from './constants.js'; import { Asset } from './asset/asset.js'; import { AssetRegistry } from './asset/asset-registry.js'; import { BundleRegistry } from './bundle/bundle-registry.js'; @@ -47,32 +51,24 @@ import { Entity } from './entity.js'; import { SceneRegistry } from './scene-registry.js'; import { script } from './script.js'; import { ApplicationStats } from './stats.js'; +import { getApplication, setApplication } from './globals.js'; -import { - FILLMODE_FILL_WINDOW, FILLMODE_KEEP_ASPECT, - RESOLUTION_AUTO, RESOLUTION_FIXED -} from './constants.js'; - -import { - getApplication, - setApplication -} from './globals.js'; - -// Mini-object used to measure progress of loading sets -class Progress { - constructor(length) { - this.length = length; - this.count = 0; - } - - inc() { - this.count++; - } - - done() { - return (this.count === this.length); - } -} +/** + * @import { AppOptions } from './app-options.js' + * @import { BatchManager } from '../scene/batching/batch-manager.js' + * @import { ElementInput } from './input/element-input.js' + * @import { GamePads } from '../platform/input/game-pads.js' + * @import { GraphicsDevice } from '../platform/graphics/graphics-device.js' + * @import { Keyboard } from '../platform/input/keyboard.js' + * @import { Lightmapper } from './lightmapper/lightmapper.js' + * @import { MeshInstance } from '../scene/mesh-instance.js' + * @import { Mesh } from '../scene/mesh.js' + * @import { Mouse } from '../platform/input/mouse.js' + * @import { SoundManager } from '../platform/sound/manager.js' + * @import { Texture } from '../platform/graphics/texture.js' + * @import { TouchDevice } from '../platform/input/touch-device.js' + * @import { XrManager } from './xr/xr-manager.js' + */ /** * Gets the current application, if any. @@ -246,7 +242,7 @@ class AppBase extends EventHandler { /** * Initialize the app. * - * @param {import('./app-options.js').AppOptions} appOptions - Options specifying the init + * @param {AppOptions} appOptions - Options specifying the init * parameters for the app. */ init(appOptions) { @@ -257,7 +253,7 @@ class AppBase extends EventHandler { /** * The graphics device used by the application. * - * @type {import('../platform/graphics/graphics-device.js').GraphicsDevice} + * @type {GraphicsDevice} */ this.graphicsDevice = device; @@ -266,7 +262,7 @@ class AppBase extends EventHandler { this.stats = new ApplicationStats(device); /** - * @type {import('../platform/sound/manager.js').SoundManager} + * @type {SoundManager} * @private */ this._soundManager = appOptions.soundManager; @@ -402,7 +398,7 @@ class AppBase extends EventHandler { /** * The run-time lightmapper. * - * @type {import('./lightmapper/lightmapper.js').Lightmapper} + * @type {Lightmapper} */ this.lightmapper = null; if (appOptions.lightmapper) { @@ -413,7 +409,7 @@ class AppBase extends EventHandler { /** * The application's batch manager. * - * @type {import('../scene/batching/batch-manager.js').BatchManager} + * @type {BatchManager} * @private */ this._batcher = null; @@ -425,35 +421,35 @@ class AppBase extends EventHandler { /** * The keyboard device. * - * @type {import('../platform/input/keyboard.js').Keyboard} + * @type {Keyboard} */ this.keyboard = appOptions.keyboard || null; /** * The mouse device. * - * @type {import('../platform/input/mouse.js').Mouse} + * @type {Mouse} */ this.mouse = appOptions.mouse || null; /** * Used to get touch events input. * - * @type {import('../platform/input/touch-device.js').TouchDevice} + * @type {TouchDevice} */ this.touch = appOptions.touch || null; /** * Used to access GamePad input. * - * @type {import('../platform/input/game-pads.js').GamePads} + * @type {GamePads} */ this.gamepads = appOptions.gamepads || null; /** * Used to handle input for {@link ElementComponent}s. * - * @type {import('./input/element-input.js').ElementInput} + * @type {ElementInput} */ this.elementInput = appOptions.elementInput || null; if (this.elementInput) @@ -462,7 +458,7 @@ class AppBase extends EventHandler { /** * The XR Manager that provides ability to start VR/AR sessions. * - * @type {import('./xr/xr-manager.js').XrManager} + * @type {XrManager} * @example * // check if VR is available * if (app.xr.isAvailable(pc.XRTYPE_VR)) { @@ -600,7 +596,7 @@ class AppBase extends EventHandler { } /** - * @type {import('../platform/sound/manager.js').SoundManager} + * @type {SoundManager} * @ignore */ get soundManager() { @@ -611,7 +607,7 @@ class AppBase extends EventHandler { * The application's batch manager. The batch manager is used to merge mesh instances in * the scene, which reduces the overall number of draw calls, thereby boosting performance. * - * @type {import('../scene/batching/batch-manager.js').BatchManager} + * @type {BatchManager} */ get batcher() { Debug.assert(this._batcher, "BatchManager has not been created and is required for correct functionality."); @@ -689,62 +685,34 @@ class AppBase extends EventHandler { preload: true }); - const progress = new Progress(assets.length); + if (assets.length === 0) { + this.fire("preload:end"); + callback(); + return; + } - let _done = false; + let loadedCount = 0; - // check if all loading is done - const done = () => { - // do not proceed if application destroyed - if (!this.graphicsDevice) { - return; - } + const onAssetLoadOrError = () => { + loadedCount++; + this.fire('preload:progress', loadedCount / assets.length); - if (!_done && progress.done()) { - _done = true; + if (loadedCount === assets.length) { this.fire("preload:end"); callback(); } }; - // totals loading progress of assets - const total = assets.length; - - if (progress.length) { - const onAssetLoad = (asset) => { - progress.inc(); - this.fire('preload:progress', progress.count / total); - - if (progress.done()) - done(); - }; - - const onAssetError = (err, asset) => { - progress.inc(); - this.fire('preload:progress', progress.count / total); - - if (progress.done()) - done(); - }; - - // for each asset - for (let i = 0; i < assets.length; i++) { - if (!assets[i].loaded) { - assets[i].once('load', onAssetLoad); - assets[i].once('error', onAssetError); - - this.assets.load(assets[i]); - } else { - progress.inc(); - this.fire("preload:progress", progress.count / total); - - if (progress.done()) - done(); - } + // for each asset + assets.forEach((asset) => { + if (!asset.loaded) { + asset.once('load', onAssetLoadOrError); + asset.once('error', onAssetLoadOrError); + this.assets.load(asset); + } else { + onAssetLoadOrError(); } - } else { - done(); - } + }); } _preloadScripts(sceneData, callback) { @@ -1745,7 +1713,7 @@ class AppBase extends EventHandler { /** * Draw meshInstance at this frame * - * @param {import('../scene/mesh-instance.js').MeshInstance} meshInstance - The mesh instance + * @param {MeshInstance} meshInstance - The mesh instance * to draw. * @param {Layer} [layer] - The layer to render the mesh instance into. Defaults to * {@link LAYERID_IMMEDIATE}. @@ -1758,7 +1726,7 @@ class AppBase extends EventHandler { /** * Draw mesh at this frame. * - * @param {import('../scene/mesh.js').Mesh} mesh - The mesh to draw. + * @param {Mesh} mesh - The mesh to draw. * @param {Material} material - The material to use to render the mesh. * @param {Mat4} matrix - The matrix to use to render the mesh. * @param {Layer} [layer] - The layer to render the mesh into. Defaults to {@link LAYERID_IMMEDIATE}. @@ -1792,7 +1760,7 @@ class AppBase extends EventHandler { * range [0, 2]. * @param {number} height - The height of the rectangle of the rendered texture. Should be in * the range [0, 2]. - * @param {import('../platform/graphics/texture.js').Texture} texture - The texture to render. + * @param {Texture} texture - The texture to render. * @param {Material} material - The material used when rendering the texture. * @param {Layer} [layer] - The layer to render the texture into. Defaults to {@link LAYERID_IMMEDIATE}. * @param {boolean} [filterable] - Indicate if the texture can be sampled using filtering. diff --git a/src/framework/app-options.js b/src/framework/app-options.js index 9b2473e5667..f526306201a 100644 --- a/src/framework/app-options.js +++ b/src/framework/app-options.js @@ -1,3 +1,18 @@ +/** + * @import { BatchManager } from '../scene/batching/batch-manager.js' + * @import { ComponentSystem } from './components/system.js' + * @import { ElementInput } from './input/element-input.js' + * @import { GamePads } from '../platform/input/game-pads.js' + * @import { GraphicsDevice } from '../platform/graphics/graphics-device.js' + * @import { Keyboard } from '../platform/input/keyboard.js' + * @import { Lightmapper } from './lightmapper/lightmapper.js' + * @import { Mouse } from '../platform/input/mouse.js' + * @import { ResourceHandler } from './handlers/handler.js' + * @import { SoundManager } from '../platform/sound/manager.js' + * @import { TouchDevice } from '../platform/input/touch-device.js' + * @import { XrManager } from './xr/xr-manager.js' + */ + /** * AppOptions is an object that holds configuration settings utilized in the creation of AppBase. It * allows functionality to be included or excluded from the AppBase instance. @@ -6,35 +21,35 @@ class AppOptions { /** * Input handler for {@link ElementComponent}s. * - * @type {import('./input/element-input.js').ElementInput} + * @type {ElementInput} */ elementInput; /** * Keyboard handler for input. * - * @type {import('../platform/input/keyboard.js').Keyboard} + * @type {Keyboard} */ keyboard; /** * Mouse handler for input. * - * @type {import('../platform/input/mouse.js').Mouse} + * @type {Mouse} */ mouse; /** * TouchDevice handler for input. * - * @type {import('../platform/input/touch-device.js').TouchDevice} + * @type {TouchDevice} */ touch; /** * Gamepad handler for input. * - * @type {import('../platform/input/game-pads.js').GamePads} + * @type {GamePads} */ gamepads; @@ -62,49 +77,49 @@ class AppOptions { /** * The sound manager * - * @type {import('../platform/sound/manager.js').SoundManager} + * @type {SoundManager} */ soundManager; /** * The graphics device. * - * @type {import('../platform/graphics/graphics-device.js').GraphicsDevice} + * @type {GraphicsDevice} */ graphicsDevice; /** * The lightmapper. * - * @type {typeof import('./lightmapper/lightmapper.js').Lightmapper} + * @type {typeof Lightmapper} */ lightmapper; /** * The BatchManager. * - * @type {typeof import('../scene/batching/batch-manager.js').BatchManager} + * @type {typeof BatchManager} */ batchManager; /** * The XrManager. * - * @type {typeof import('./xr/xr-manager.js').XrManager} + * @type {typeof XrManager} */ xr; /** * The component systems the app requires. * - * @type {typeof import('./components/system.js').ComponentSystem[]} + * @type {typeof ComponentSystem[]} */ componentSystems = []; /** * The resource handlers the app requires. * - * @type {typeof import('./handlers/handler.js').ResourceHandler[]} + * @type {typeof ResourceHandler[]} */ resourceHandlers = []; } diff --git a/src/framework/application.js b/src/framework/application.js index 9643d9f995a..1679824d569 100644 --- a/src/framework/application.js +++ b/src/framework/application.js @@ -1,12 +1,8 @@ import { platform } from '../core/platform.js'; - import { WebglGraphicsDevice } from '../platform/graphics/webgl/webgl-graphics-device.js'; - import { SoundManager } from '../platform/sound/manager.js'; - import { Lightmapper } from './lightmapper/lightmapper.js'; import { BatchManager } from '../scene/batching/batch-manager.js'; - import { AppBase } from './app-base.js'; import { AppOptions } from './app-options.js'; import { AnimationComponentSystem } from './components/animation/system.js'; @@ -32,7 +28,6 @@ import { CameraComponentSystem } from './components/camera/system.js'; import { LightComponentSystem } from './components/light/system.js'; import { ScriptComponentSystem } from './components/script/system.js'; import { GSplatComponentSystem } from './components/gsplat/system.js'; - import { RenderHandler } from './handlers/render.js'; import { AnimationHandler } from './handlers/animation.js'; import { AnimClipHandler } from './handlers/anim-clip.js'; @@ -58,9 +53,17 @@ import { TemplateHandler } from './handlers/template.js'; import { TextHandler } from './handlers/text.js'; import { TextureAtlasHandler } from './handlers/texture-atlas.js'; import { TextureHandler } from './handlers/texture.js'; - import { XrManager } from './xr/xr-manager.js'; +/** + * @import { ElementInput } from './input/element-input.js' + * @import { GamePads } from '../platform/input/game-pads.js' + * @import { GraphicsDevice } from '../platform/graphics/graphics-device.js' + * @import { Keyboard } from '../platform/input/keyboard.js' + * @import { Mouse } from '../platform/input/mouse.js' + * @import { TouchDevice } from '../platform/input/touch-device.js' + */ + /** * An Application represents and manages your PlayCanvas application. If you are developing using * the PlayCanvas Editor, the Application is created for you. You can access your Application @@ -91,21 +94,15 @@ class Application extends AppBase { * * @param {HTMLCanvasElement} canvas - The canvas element. * @param {object} [options] - The options object to configure the Application. - * @param {import('./input/element-input.js').ElementInput} [options.elementInput] - Input - * handler for {@link ElementComponent}s. - * @param {import('../platform/input/keyboard.js').Keyboard} [options.keyboard] - Keyboard - * handler for input. - * @param {import('../platform/input/mouse.js').Mouse} [options.mouse] - Mouse handler for - * input. - * @param {import('../platform/input/touch-device.js').TouchDevice} [options.touch] - TouchDevice - * handler for input. - * @param {import('../platform/input/game-pads.js').GamePads} [options.gamepads] - Gamepad - * handler for input. + * @param {ElementInput} [options.elementInput] - Input handler for {@link ElementComponent}s. + * @param {Keyboard} [options.keyboard] - Keyboard handler for input. + * @param {Mouse} [options.mouse] - Mouse handler for input. + * @param {TouchDevice} [options.touch] - TouchDevice handler for input. + * @param {GamePads} [options.gamepads] - Gamepad handler for input. * @param {string} [options.scriptPrefix] - Prefix to apply to script urls before loading. * @param {string} [options.assetPrefix] - Prefix to apply to asset urls before loading. - * @param {import('../platform/graphics/graphics-device.js').GraphicsDevice} [options.graphicsDevice] - The - * graphics device used by the application. If not provided, a WebGl graphics device will be - * created. + * @param {GraphicsDevice} [options.graphicsDevice] - The graphics device used by the + * application. If not provided, a WebGl graphics device will be created. * @param {object} [options.graphicsDeviceOptions] - Options object that is passed into the * {@link GraphicsDevice} constructor. * @param {string[]} [options.scriptsOrder] - Scripts in order of loading first. diff --git a/src/framework/asset/asset-list-loader.js b/src/framework/asset/asset-list-loader.js index 0822e688e59..cda31f46eb0 100644 --- a/src/framework/asset/asset-list-loader.js +++ b/src/framework/asset/asset-list-loader.js @@ -1,7 +1,10 @@ import { EventHandler } from '../../core/event-handler.js'; - import { Asset } from './asset.js'; +/** + * @import { AssetRegistry } from './asset-registry.js' + */ + /** * Used to load a group of assets and fires a callback when all assets are loaded. * @@ -24,10 +27,44 @@ import { Asset } from './asset.js'; */ class AssetListLoader extends EventHandler { /** - * Create a new AssetListLoader using a list of assets to load and the asset registry used to load and manage them. + * @type {Set} + * @private + */ + _assets = new Set(); + + /** + * @type {Set} + * @private + */ + _loadingAssets = new Set(); + + /** + * @type {Set} + * @private + */ + _waitingAssets = new Set(); + + /** @private */ + _loading = false; + + /** @private */ + _loaded = false; + + /** + * Array of assets that failed to load. + * + * @type {Asset[]} + * @private + */ + _failed = []; + + /** + * Create a new AssetListLoader using a list of assets to load and the asset registry used to + * load and manage them. * - * @param {Asset[]|number[]} assetList - An array of {@link Asset} objects to load or an array of Asset IDs to load. - * @param {import('./asset-registry.js').AssetRegistry} assetRegistry - The application's asset registry. + * @param {Asset[]|number[]} assetList - An array of {@link Asset} objects to load or an array + * of Asset IDs to load. + * @param {AssetRegistry} assetRegistry - The application's asset registry. * @example * const assetListLoader = new pc.AssetListLoader([ * new pc.Asset("texture1", "texture", { url: 'http://example.com/my/assets/here/texture1.png') }), @@ -36,13 +73,8 @@ class AssetListLoader extends EventHandler { */ constructor(assetList, assetRegistry) { super(); - this._assets = new Set(); - this._loadingAssets = new Set(); - this._waitingAssets = new Set(); + this._registry = assetRegistry; - this._loading = false; - this._loaded = false; - this._failed = []; // list of assets that failed to load assetList.forEach((a) => { if (a instanceof Asset) { @@ -66,13 +98,11 @@ class AssetListLoader extends EventHandler { */ destroy() { // remove any outstanding listeners - const self = this; - this._registry.off("load", this._onLoad); this._registry.off("error", this._onError); - this._waitingAssets.forEach(function (id) { - self._registry.off("add:" + id, this._onAddAsset); + this._waitingAssets.forEach((id) => { + this._registry.off("add:" + id, this._onAddAsset); }); this.off("progress"); @@ -84,9 +114,11 @@ class AssetListLoader extends EventHandler { } /** - * Start loading asset list, call done() when all assets have loaded or failed to load. + * Start loading asset list and call `done()` when all assets have loaded or failed to load. * - * @param {Function} done - Callback called when all assets in the list are loaded. Passed (err, failed) where err is the undefined if no errors are encountered and failed contains a list of assets that failed to load. + * @param {Function} done - Callback called when all assets in the list are loaded. Passed + * `(err, failed)` where `err` is `undefined` if no errors are encountered and failed contains + * an array of assets that failed to load. * @param {object} [scope] - Scope to use when calling callback. */ load(done, scope) { @@ -143,7 +175,7 @@ class AssetListLoader extends EventHandler { if (this._loaded) { done.call(scope, Array.from(this._assets)); } else { - this.once("load", function (assets) { + this.once("load", (assets) => { done.call(scope, assets); }); } @@ -182,7 +214,7 @@ class AssetListLoader extends EventHandler { // this to be fired after any other // asset load events setTimeout(() => { - this._loadingComplete(this._failed); + this._loadingComplete(); }, 0); } } @@ -200,7 +232,7 @@ class AssetListLoader extends EventHandler { // this to be fired after any other // asset load events setTimeout(() => { - this._loadingComplete(this._failed); + this._loadingComplete(); }, 0); } } diff --git a/src/framework/asset/asset-reference.js b/src/framework/asset/asset-reference.js index d792b6b1917..6e54b56c392 100644 --- a/src/framework/asset/asset-reference.js +++ b/src/framework/asset/asset-reference.js @@ -1,3 +1,8 @@ +/** + * @import { Asset } from './asset.js' + * @import { AssetRegistry } from './asset-registry.js' + */ + /** * An object that manages the case where an object holds a reference to an asset and needs to be * notified when changes occur in the asset. e.g. notifications include load, add and remove @@ -11,11 +16,9 @@ class AssetReference { * * @param {string} propertyName - The name of the property that the asset is stored under, * passed into callbacks to enable updating. - * @param {import('./asset.js').Asset|object} parent - The parent object that contains the - * asset reference, passed into callbacks to enable updating. Currently an asset, but could be - * component or other. - * @param {import('./asset-registry.js').AssetRegistry} registry - The asset registry that - * stores all assets. + * @param {Asset|object} parent - The parent object that contains the asset reference, passed + * into callbacks to enable updating. Currently an asset, but could be component or other. + * @param {AssetRegistry} registry - The asset registry that stores all assets. * @param {object} callbacks - A set of functions called when the asset state changes: load, * add, remove. * @param {object} [callbacks.load] - The function called when the asset loads diff --git a/src/framework/asset/asset-registry.js b/src/framework/asset/asset-registry.js index 11007871c58..26bcd1e2ef4 100644 --- a/src/framework/asset/asset-registry.js +++ b/src/framework/asset/asset-registry.js @@ -2,11 +2,15 @@ import { path } from '../../core/path.js'; import { Debug } from '../../core/debug.js'; import { EventHandler } from '../../core/event-handler.js'; import { TagsCache } from '../../core/tags-cache.js'; - import { standardMaterialTextureParameters } from '../../scene/materials/standard-material-parameters.js'; - import { Asset } from './asset.js'; +/** + * @import { Bundle } from '../bundle/bundle.js' + * @import { BundleRegistry } from '../bundle/bundle-registry.js' + * @import { ResourceLoader } from '../handlers/loader.js' + */ + /** * Callback used by {@link AssetRegistry#filter} to filter assets. * @@ -29,7 +33,7 @@ import { Asset } from './asset.js'; * to load from. Return a single bundle to ensure asset is loaded from it. * * @callback BundlesFilterCallback - * @param {import('../bundle/bundle.js').Bundle[]} bundles - List of bundles which contain the asset. + * @param {Bundle[]} bundles - List of bundles which contain the asset. */ /** @@ -162,6 +166,12 @@ class AssetRegistry extends EventHandler { */ _assets = new Set(); + /** + * @type {import('../handlers/loader.js').ResourceLoader} + * @private + */ + _loader; + /** * @type {Map} * @private @@ -197,15 +207,14 @@ class AssetRegistry extends EventHandler { /** * BundleRegistry * - * @type {import('../bundle/bundle-registry.js').BundleRegistry|null} + * @type {BundleRegistry|null} */ bundles = null; /** * Create an instance of an AssetRegistry. * - * @param {import('../handlers/loader.js').ResourceLoader} loader - The ResourceLoader used to - * load the asset files. + * @param {ResourceLoader} loader - The ResourceLoader used to load the asset files. */ constructor(loader) { super(); @@ -216,7 +225,8 @@ class AssetRegistry extends EventHandler { /** * Create a filtered list of assets from the registry. * - * @param {object} filters - Properties to filter on, currently supports: 'preload: true|false'. + * @param {object} [filters] - Filter options. + * @param {boolean} [filters.preload] - Filter by preload setting. * @returns {Asset[]} The filtered list of assets. */ list(filters = {}) { @@ -343,7 +353,7 @@ class AssetRegistry extends EventHandler { } /** - * Load the asset's file from a remote source. Listen for "load" events on the asset to find + * Load the asset's file from a remote source. Listen for `load` events on the asset to find * out when it is loaded. * * @param {Asset} asset - The asset to load. @@ -355,7 +365,7 @@ class AssetRegistry extends EventHandler { * @param {BundlesFilterCallback} [options.bundlesFilter] - A callback that will be called * when loading an asset that is contained in any of the bundles. It provides an array of * bundles and will ensure asset is loaded from bundle returned from a callback. By default - * smallest filesize bundle is choosen. + * smallest filesize bundle is chosen. * @example * // load some assets * const assetsToLoad = [ @@ -702,8 +712,8 @@ class AssetRegistry extends EventHandler { * const assets = app.assets.findByTag(["level-1", "monster"], ["level-2", "monster"]); * // returns all assets that tagged by (`level-1` AND `monster`) OR (`level-2` AND `monster`) */ - findByTag() { - return this._tags.find(arguments); + findByTag(...query) { + return this._tags.find(query); } /** diff --git a/src/framework/asset/asset.js b/src/framework/asset/asset.js index 45c14d0a919..25b6275e7cc 100644 --- a/src/framework/asset/asset.js +++ b/src/framework/asset/asset.js @@ -1,15 +1,17 @@ import { path } from '../../core/path.js'; import { Tags } from '../../core/tags.js'; - import { EventHandler } from '../../core/event-handler.js'; - import { findAvailableLocale } from '../i18n/utils.js'; - import { ABSOLUTE_URL } from './constants.js'; import { AssetFile } from './asset-file.js'; import { getApplication } from '../globals.js'; import { http } from '../../platform/net/http.js'; +/** + * @import { AssetRegistry } from './asset-registry.js' + * @import { ResourceLoaderCallback } from '../handlers/loader.js' + */ + // auto incrementing number for asset ids let assetIdCounter = -1; @@ -220,7 +222,7 @@ class Asset extends EventHandler { /** * The asset registry that this Asset belongs to. * - * @type {import('./asset-registry.js').AssetRegistry|null} + * @type {AssetRegistry|null} */ this.registry = null; @@ -599,8 +601,7 @@ class Asset extends EventHandler { * via http. * * @param {string} loadUrl - The URL as passed into the handler - * @param {import('../handlers/loader.js').ResourceLoaderCallback} callback - The callback - * function to receive results. + * @param {ResourceLoaderCallback} callback - The callback function to receive results. * @param {Asset} [asset] - The asset * @param {number} maxRetries - Number of retries if http download is required * @ignore diff --git a/src/framework/bundle/bundle-registry.js b/src/framework/bundle/bundle-registry.js index f215db2f5d9..2985c1f543f 100644 --- a/src/framework/bundle/bundle-registry.js +++ b/src/framework/bundle/bundle-registry.js @@ -1,3 +1,8 @@ +/** + * @import { Asset } from '../asset/asset.js' + * @import { AssetRegistry } from '../asset/asset-registry.js' + */ + /** * Keeps track of which assets are in bundles and loads files from bundles. * @@ -6,21 +11,21 @@ class BundleRegistry { /** * Index of bundle assets. - * @type {Map} + * @type {Map} * @private */ _idToBundle = new Map(); /** * Index of asset id to set of bundle assets. - * @type {Map>} + * @type {Map>} * @private */ _assetToBundles = new Map(); /** * Index of file url to set of bundle assets. - * @type {Map>} + * @type {Map>} * @private */ _urlsToBundles = new Map(); @@ -35,7 +40,7 @@ class BundleRegistry { /** * Create a new BundleRegistry instance. * - * @param {import('../asset/asset-registry.js').AssetRegistry} assets - The asset registry. + * @param {AssetRegistry} assets - The asset registry. */ constructor(assets) { this._assets = assets; @@ -47,7 +52,7 @@ class BundleRegistry { /** * Called when asset is added to AssetRegistry. * - * @param {import('../asset/asset.js').Asset} asset - The asset that has been added. + * @param {Asset} asset - The asset that has been added. * @private */ _onAssetAdd(asset) { @@ -256,8 +261,8 @@ class BundleRegistry { /** * Lists all of the available bundles that reference the specified asset. * - * @param {import('../asset/asset.js').Asset} asset - The asset to search by. - * @returns {import('../asset/asset.js').Asset[]|null} An array of bundle assets or null if the + * @param {Asset} asset - The asset to search by. + * @returns {Asset[]|null} An array of bundle assets or null if the * asset is not in any bundle. */ listBundlesForAsset(asset) { @@ -269,7 +274,7 @@ class BundleRegistry { /** * Lists all bundle assets. * - * @returns {import('../asset/asset.js').Asset[]} An array of bundle assets. + * @returns {Asset[]} An array of bundle assets. */ list() { return Array.from(this._idToBundle.values()); diff --git a/src/framework/components/anim/component-layer.js b/src/framework/components/anim/component-layer.js index ea22769e54b..d655f4d8367 100644 --- a/src/framework/components/anim/component-layer.js +++ b/src/framework/components/anim/component-layer.js @@ -1,10 +1,15 @@ import { Debug } from '../../../core/debug.js'; import { math } from '../../../core/math/math.js'; - import { AnimTrack } from '../../anim/evaluator/anim-track.js'; import { AnimTransition } from '../../anim/controller/anim-transition.js'; import { ANIM_LAYER_OVERWRITE } from '../../anim/controller/constants.js'; +/** + * @import { AnimComponent } from './component.js' + * @import { AnimController } from '../../anim/controller/anim-controller.js' + * @import { Asset } from '../../asset/asset.js' + */ + /** * The Anim Component Layer allows managers a single layer of the animation state graph. * @@ -18,13 +23,13 @@ class AnimComponentLayer { _name; /** - * @type {import('../../anim/controller/anim-controller.js').AnimController} + * @type {AnimController} * @private */ _controller; /** - * @type {import('./component.js').AnimComponent} + * @type {AnimComponent} * @private */ _component; @@ -60,10 +65,8 @@ class AnimComponentLayer { * Create a new AnimComponentLayer instance. * * @param {string} name - The name of the layer. - * @param {import('../../anim/controller/anim-controller.js').AnimController} controller - The - * controller to manage this layers animations. - * @param {import('./component.js').AnimComponent} component - The component that this layer is - * a member of. + * @param {AnimController} controller - The controller to manage this layers animations. + * @param {AnimComponent} component - The component that this layer is a member of. * @param {number} [weight] - The weight of this layer. Defaults to 1. * @param {string} [blendType] - The blend type of this layer. Defaults to {@link ANIM_LAYER_OVERWRITE}. * @ignore @@ -381,7 +384,7 @@ class AnimComponentLayer { * Returns the asset that is associated with the given state. * * @param {string} stateName - The name of the state to get the asset for. - * @returns {import('../../asset/asset.js').Asset} The asset associated with the given state. + * @returns {Asset} The asset associated with the given state. */ getAnimationAsset(stateName) { return this._component.animationAssets[`${this.name}:${stateName}`]; diff --git a/src/framework/components/anim/component.js b/src/framework/components/anim/component.js index 38dd2e14d19..69486a1f2d4 100644 --- a/src/framework/components/anim/component.js +++ b/src/framework/components/anim/component.js @@ -1,20 +1,21 @@ import { Debug } from '../../../core/debug.js'; import { Asset } from '../../asset/asset.js'; - import { AnimEvaluator } from '../../anim/evaluator/anim-evaluator.js'; import { AnimController } from '../../anim/controller/anim-controller.js'; - import { Component } from '../component.js'; - -import { - ANIM_PARAMETER_BOOLEAN, ANIM_PARAMETER_FLOAT, ANIM_PARAMETER_INTEGER, ANIM_PARAMETER_TRIGGER, ANIM_CONTROL_STATES -} from '../../anim/controller/constants.js'; import { AnimComponentBinder } from './component-binder.js'; import { AnimComponentLayer } from './component-layer.js'; import { AnimStateGraph } from '../../anim/state-graph/anim-state-graph.js'; import { Entity } from '../../entity.js'; +import { + ANIM_PARAMETER_BOOLEAN, ANIM_PARAMETER_FLOAT, ANIM_PARAMETER_INTEGER, ANIM_PARAMETER_TRIGGER, ANIM_CONTROL_STATES +} from '../../anim/controller/constants.js'; import { AnimTrack } from '../../anim/evaluator/anim-track.js'; +/** + * @import { AnimComponentSystem } from './system.js' + */ + /** * The Anim Component allows an Entity to playback animations on models and entity properties. * @@ -24,8 +25,7 @@ class AnimComponent extends Component { /** * Create a new AnimComponent instance. * - * @param {import('./system.js').AnimComponentSystem} system - The {@link ComponentSystem} that - * created this Component. + * @param {AnimComponentSystem} system - The {@link ComponentSystem} that created this Component. * @param {Entity} entity - The Entity that this Component is attached to. */ constructor(system, entity) { diff --git a/src/framework/components/anim/system.js b/src/framework/components/anim/system.js index 1bac038e2c8..014a072513b 100644 --- a/src/framework/components/anim/system.js +++ b/src/framework/components/anim/system.js @@ -1,10 +1,13 @@ import { AnimTrack } from '../../anim/evaluator/anim-track.js'; import { Component } from '../component.js'; import { ComponentSystem } from '../system.js'; - import { AnimComponent } from './component.js'; import { AnimComponentData } from './data.js'; +/** + * @import { AppBase } from '../../app-base.js' + */ + const _schema = [ 'enabled' ]; @@ -18,7 +21,7 @@ class AnimComponentSystem extends ComponentSystem { /** * Create an AnimComponentSystem instance. * - * @param {import('../../app-base.js').AppBase} app - The application managing this system. + * @param {AppBase} app - The application managing this system. * @ignore */ constructor(app) { diff --git a/src/framework/components/animation/component.js b/src/framework/components/animation/component.js index a1c843aed50..51b964824dc 100644 --- a/src/framework/components/animation/component.js +++ b/src/framework/components/animation/component.js @@ -1,16 +1,19 @@ import { Debug } from '../../../core/debug.js'; - import { AnimClip } from '../../anim/evaluator/anim-clip.js'; import { AnimEvaluator } from '../../anim/evaluator/anim-evaluator.js'; import { AnimTrack } from '../../anim/evaluator/anim-track.js'; import { DefaultAnimBinder } from '../../anim/binder/default-anim-binder.js'; - import { Skeleton } from '../../../scene/animation/skeleton.js'; - import { Asset } from '../../asset/asset.js'; - import { Component } from '../component.js'; +/** + * @import { Animation } from '../../../scene/animation/animation.js' + * @import { AnimationComponentSystem } from './system.js' + * @import { Entity } from '../../entity.js' + * @import { Model } from '../../../scene/model.js' + */ + /** * The Animation Component allows an Entity to playback animations on models. * @@ -18,7 +21,7 @@ import { Component } from '../component.js'; */ class AnimationComponent extends Component { /** - * @type {Object} + * @type {Object} * @private */ _animations = {}; @@ -39,7 +42,7 @@ class AnimationComponent extends Component { animEvaluator = null; /** - * @type {import('../../../scene/model.js').Model|null} + * @type {Model|null} * @ignore */ model = null; @@ -109,10 +112,9 @@ class AnimationComponent extends Component { /** * Create a new AnimationComponent instance. * - * @param {import('./system.js').AnimationComponentSystem} system - The {@link ComponentSystem} - * that created this component. - * @param {import('../../entity.js').Entity} entity - The Entity that this component is - * attached to. + * @param {AnimationComponentSystem} system - The {@link ComponentSystem} that created this + * component. + * @param {Entity} entity - The Entity that this component is attached to. */ constructor(system, entity) { // eslint-disable-line no-useless-constructor super(system, entity); @@ -121,7 +123,7 @@ class AnimationComponent extends Component { /** * Sets the dictionary of animations by name. * - * @type {Object} + * @type {Object} */ set animations(value) { this._animations = value; @@ -132,7 +134,7 @@ class AnimationComponent extends Component { /** * Gets the dictionary of animations by name. * - * @type {Object} + * @type {Object} */ get animations() { return this._animations; @@ -343,7 +345,7 @@ class AnimationComponent extends Component { * Return an animation. * * @param {string} name - The name of the animation asset. - * @returns {import('../../../scene/animation/animation.js').Animation} An Animation. + * @returns {Animation} An Animation. */ getAnimation(name) { return this.animations[name]; @@ -352,7 +354,7 @@ class AnimationComponent extends Component { /** * Set the model driven by this animation component. * - * @param {import('../../../scene/model.js').Model} model - The model to set. + * @param {Model} model - The model to set. * @ignore */ setModel(model) { diff --git a/src/framework/components/animation/system.js b/src/framework/components/animation/system.js index 32121fc713a..d7f7ea37427 100644 --- a/src/framework/components/animation/system.js +++ b/src/framework/components/animation/system.js @@ -1,9 +1,13 @@ import { Component } from '../component.js'; import { ComponentSystem } from '../system.js'; - import { AnimationComponent } from './component.js'; import { AnimationComponentData } from './data.js'; +/** + * @import { AppBase } from '../../app-base.js' + * @import { Entity } from '../../entity.js' + */ + const _schema = [ 'enabled' ]; @@ -17,7 +21,7 @@ class AnimationComponentSystem extends ComponentSystem { /** * Create an AnimationComponentSystem instance. * - * @param {import('../../app-base.js').AppBase} app - The application managing this system. + * @param {AppBase} app - The application managing this system. * @ignore */ constructor(app) { @@ -62,8 +66,8 @@ class AnimationComponentSystem extends ComponentSystem { /** * Create a clone of component. This creates a copy of all component data variables. * - * @param {import('../../entity.js').Entity} entity - The entity to clone the component from. - * @param {import('../../entity.js').Entity} clone - The entity to clone the component into. + * @param {Entity} entity - The entity to clone the component from. + * @param {Entity} clone - The entity to clone the component into. * @returns {AnimationComponent} The newly cloned component. * @ignore */ @@ -98,7 +102,7 @@ class AnimationComponentSystem extends ComponentSystem { } /** - * @param {import('../../entity.js').Entity} entity - The entity having its component removed. + * @param {Entity} entity - The entity having its component removed. * @param {AnimationComponent} component - The component being removed. * @private */ diff --git a/src/framework/components/audio-listener/component.js b/src/framework/components/audio-listener/component.js index 4ba67169f7c..0da2296cb36 100644 --- a/src/framework/components/audio-listener/component.js +++ b/src/framework/components/audio-listener/component.js @@ -1,5 +1,10 @@ import { Component } from '../component.js'; +/** + * @import { AudioListenerComponentSystem } from './system.js' + * @import { Entity } from '../../entity.js' + */ + /** * Represents the audio listener in the 3D world, so that 3D positioned audio sources are heard * correctly. @@ -10,10 +15,8 @@ class AudioListenerComponent extends Component { /** * Create a new AudioListenerComponent instance. * - * @param {import('./system.js').AudioListenerComponentSystem} system - The ComponentSystem - * that created this component. - * @param {import('../../entity.js').Entity} entity - The Entity that this component is - * attached to. + * @param {AudioListenerComponentSystem} system - The ComponentSystem that created this component. + * @param {Entity} entity - The Entity that this component is attached to. */ constructor(system, entity) { // eslint-disable-line no-useless-constructor super(system, entity); diff --git a/src/framework/components/audio-listener/system.js b/src/framework/components/audio-listener/system.js index e163d3b94f9..960b4cab2fc 100644 --- a/src/framework/components/audio-listener/system.js +++ b/src/framework/components/audio-listener/system.js @@ -1,11 +1,13 @@ import { Debug } from '../../../core/debug.js'; - import { Component } from '../component.js'; import { ComponentSystem } from '../system.js'; - import { AudioListenerComponent } from './component.js'; import { AudioListenerComponentData } from './data.js'; +/** + * @import { AppBase } from '../../app-base.js' + */ + const _schema = ['enabled']; /** @@ -17,7 +19,7 @@ class AudioListenerComponentSystem extends ComponentSystem { /** * Create a new AudioListenerComponentSystem instance. * - * @param {import('../../app-base.js').AppBase} app - The application managing this system. + * @param {AppBase} app - The application managing this system. * @ignore */ constructor(app) { diff --git a/src/framework/components/button/component.js b/src/framework/components/button/component.js index 2280629a1b0..ad7d96133c5 100644 --- a/src/framework/components/button/component.js +++ b/src/framework/components/button/component.js @@ -1,15 +1,19 @@ import { now } from '../../../core/time.js'; - import { math } from '../../../core/math/math.js'; import { Color } from '../../../core/math/color.js'; - import { EntityReference } from '../../utils/entity-reference.js'; - import { Component } from '../component.js'; - import { BUTTON_TRANSITION_MODE_SPRITE_CHANGE, BUTTON_TRANSITION_MODE_TINT } from './constants.js'; import { ELEMENTTYPE_GROUP } from '../element/constants.js'; +/** + * @import { Asset } from '../../../framework/asset/asset.js' + * @import { ButtonComponentData } from './data.js' + * @import { ButtonComponentSystem } from './system.js' + * @import { Entity } from '../../entity.js' + * @import { Vec4 } from '../../../core/math/vec4.js' + */ + const VisualState = { DEFAULT: 'DEFAULT', HOVER: 'HOVER', @@ -242,10 +246,8 @@ class ButtonComponent extends Component { /** * Create a new ButtonComponent instance. * - * @param {import('./system.js').ButtonComponentSystem} system - The ComponentSystem that - * created this component. - * @param {import('../../entity.js').Entity} entity - The entity that this component is - * attached to. + * @param {ButtonComponentSystem} system - The ComponentSystem that created this component. + * @param {Entity} entity - The entity that this component is attached to. */ constructor(system, entity) { super(system, entity); @@ -273,7 +275,7 @@ class ButtonComponent extends Component { // TODO: Remove this override in upgrading component /** - * @type {import('./data.js').ButtonComponentData} + * @type {ButtonComponentData} * @ignore */ get data() { @@ -322,7 +324,7 @@ class ButtonComponent extends Component { * Sets the entity to be used as the button background. The entity must have an * {@link ElementComponent} configured as an image element. * - * @type {import('../../../framework/entity.js').Entity} + * @type {Entity} */ set imageEntity(arg) { this._setValue('imageEntity', arg); @@ -331,7 +333,7 @@ class ButtonComponent extends Component { /** * Gets the entity to be used as the button background. * - * @type {import('../../../framework/entity.js').Entity} + * @type {Entity} */ get imageEntity() { return this.data.imageEntity; @@ -341,7 +343,7 @@ class ButtonComponent extends Component { * Sets the padding to be used in hit-test calculations. Can be used to expand the bounding box * so that the button is easier to tap. Defaults to `[0, 0, 0, 0]`. * - * @type {import('../../../core/math/vec4.js').Vec4} + * @type {Vec4} */ set hitPadding(arg) { this._setValue('hitPadding', arg); @@ -350,7 +352,7 @@ class ButtonComponent extends Component { /** * Gets the padding to be used in hit-test calculations. * - * @type {import('../../../core/math/vec4.js').Vec4} + * @type {Vec4} */ get hitPadding() { return this.data.hitPadding; @@ -458,7 +460,7 @@ class ButtonComponent extends Component { /** * Sets the sprite to be used as the button image when the user hovers over it. * - * @type {import('../../../framework/asset/asset.js').Asset} + * @type {Asset} */ set hoverSpriteAsset(arg) { this._setValue('hoverSpriteAsset', arg); @@ -467,7 +469,7 @@ class ButtonComponent extends Component { /** * Gets the sprite to be used as the button image when the user hovers over it. * - * @type {import('../../../framework/asset/asset.js').Asset} + * @type {Asset} */ get hoverSpriteAsset() { return this.data.hoverSpriteAsset; @@ -494,7 +496,7 @@ class ButtonComponent extends Component { /** * Sets the sprite to be used as the button image when the user presses it. * - * @type {import('../../../framework/asset/asset.js').Asset} + * @type {Asset} */ set pressedSpriteAsset(arg) { this._setValue('pressedSpriteAsset', arg); @@ -503,7 +505,7 @@ class ButtonComponent extends Component { /** * Gets the sprite to be used as the button image when the user presses it. * - * @type {import('../../../framework/asset/asset.js').Asset} + * @type {Asset} */ get pressedSpriteAsset() { return this.data.pressedSpriteAsset; @@ -530,7 +532,7 @@ class ButtonComponent extends Component { /** * Sets the sprite to be used as the button image when the button is not interactive. * - * @type {import('../../../framework/asset/asset.js').Asset} + * @type {Asset} */ set inactiveSpriteAsset(arg) { this._setValue('inactiveSpriteAsset', arg); @@ -539,7 +541,7 @@ class ButtonComponent extends Component { /** * Gets the sprite to be used as the button image when the button is not interactive. * - * @type {import('../../../framework/asset/asset.js').Asset} + * @type {Asset} */ get inactiveSpriteAsset() { return this.data.inactiveSpriteAsset; diff --git a/src/framework/components/button/data.js b/src/framework/components/button/data.js index add28b75723..300ee807aa8 100644 --- a/src/framework/components/button/data.js +++ b/src/framework/components/button/data.js @@ -1,14 +1,18 @@ import { Color } from '../../../core/math/color.js'; import { Vec4 } from '../../../core/math/vec4.js'; - import { BUTTON_TRANSITION_MODE_TINT } from './constants.js'; +/** + * @import { Asset } from '../../../framework/asset/asset.js' + * @import { Entity } from '../../../framework/entity.js' + */ + class ButtonComponentData { constructor() { this.enabled = true; this.active = true; - /** @type {import('../../../framework/entity.js').Entity} */ + /** @type {Entity} */ this.imageEntity = null; this.hitPadding = new Vec4(); this.transitionMode = BUTTON_TRANSITION_MODE_TINT; @@ -16,13 +20,13 @@ class ButtonComponentData { this.pressedTint = new Color(0.5, 0.5, 0.5); this.inactiveTint = new Color(0.25, 0.25, 0.25); this.fadeDuration = 0; - /** @type {import('../../../framework/asset/asset.js').Asset} */ + /** @type {Asset} */ this.hoverSpriteAsset = null; this.hoverSpriteFrame = 0; - /** @type {import('../../../framework/asset/asset.js').Asset} */ + /** @type {Asset} */ this.pressedSpriteAsset = null; this.pressedSpriteFrame = 0; - /** @type {import('../../../framework/asset/asset.js').Asset} */ + /** @type {Asset} */ this.inactiveSpriteAsset = null; this.inactiveSpriteFrame = 0; } diff --git a/src/framework/components/button/system.js b/src/framework/components/button/system.js index bc0cc2e6e97..4a3404010d0 100644 --- a/src/framework/components/button/system.js +++ b/src/framework/components/button/system.js @@ -1,8 +1,11 @@ import { ComponentSystem } from '../system.js'; - import { ButtonComponent } from './component.js'; import { ButtonComponentData } from './data.js'; +/** + * @import { AppBase } from '../../app-base.js' + */ + const _schema = [ 'enabled', 'active', @@ -30,7 +33,7 @@ class ButtonComponentSystem extends ComponentSystem { /** * Create a new ButtonComponentSystem. * - * @param {import('../../app-base.js').AppBase} app - The application. + * @param {AppBase} app - The application. * @ignore */ constructor(app) { diff --git a/src/framework/components/camera/component.js b/src/framework/components/camera/component.js index 7e593e36dab..f02c0422496 100644 --- a/src/framework/components/camera/component.js +++ b/src/framework/components/camera/component.js @@ -1,18 +1,31 @@ import { Debug } from '../../../core/debug.js'; - import { ASPECT_AUTO, LAYERID_UI, LAYERID_DEPTH } from '../../../scene/constants.js'; import { Camera } from '../../../scene/camera.js'; import { ShaderPass } from '../../../scene/shader-pass.js'; - import { Component } from '../component.js'; - import { PostEffectQueue } from './post-effect-queue.js'; +/** + * @import { CameraComponentSystem } from './system.js' + * @import { Color } from '../../../core/math/color.js' + * @import { Entity } from '../../entity.js' + * @import { Frustum } from '../../../core/shape/frustum.js' + * @import { LayerComposition } from '../../../scene/composition/layer-composition.js' + * @import { Layer } from '../../../scene/layer.js' + * @import { Mat4 } from '../../../core/math/mat4.js' + * @import { RenderPass } from '../../../platform/graphics/render-pass.js' + * @import { RenderTarget } from '../../../platform/graphics/render-target.js' + * @import { RenderingParams } from '../../../scene/renderer/rendering-params.js' + * @import { Vec3 } from '../../../core/math/vec3.js' + * @import { Vec4 } from '../../../core/math/vec4.js' + * @import { XrErrorCallback } from '../../xr/xr-manager.js' + */ + /** * Callback used by {@link CameraComponent#calculateTransform} and {@link CameraComponent#calculateProjection}. * * @callback CalculateMatrixCallback - * @param {import('../../../core/math/mat4.js').Mat4} transformMatrix - Output of the function. + * @param {Mat4} transformMatrix - Output of the function. * @param {number} view - Type of view. Can be {@link VIEW_CENTER}, {@link VIEW_LEFT} or {@link VIEW_RIGHT}. Left and right are only used in stereo rendering. */ @@ -101,10 +114,8 @@ class CameraComponent extends Component { /** * Create a new CameraComponent instance. * - * @param {import('./system.js').CameraComponentSystem} system - The ComponentSystem that - * created this Component. - * @param {import('../../entity.js').Entity} entity - The Entity that this Component is - * attached to. + * @param {CameraComponentSystem} system - The ComponentSystem that created this Component. + * @param {Entity} entity - The Entity that this Component is attached to. */ constructor(system, entity) { super(system, entity); @@ -182,7 +193,7 @@ class CameraComponent extends Component { * Sets the render passes the camera uses for rendering, instead of its default rendering. * Set this to an empty array to return to the default behavior. * - * @type {import('../../../platform/graphics/render-pass.js').RenderPass[]} + * @type {RenderPass[]} * @ignore */ set renderPasses(passes) { @@ -192,7 +203,7 @@ class CameraComponent extends Component { /** * Gets the render passes the camera uses for rendering, instead of its default rendering. * - * @type {import('../../../platform/graphics/render-pass.js').RenderPass[]} + * @type {RenderPass[]} * @ignore */ get renderPasses() { @@ -212,7 +223,7 @@ class CameraComponent extends Component { * Gets a {@link RenderingParams} that defines rendering parameters, or null if those are not * set. * - * @type {import('../../../scene/renderer/rendering-params.js').RenderingParams|null} + * @type {RenderingParams|null} */ get rendering() { return this._camera.renderingParams; @@ -343,7 +354,7 @@ class CameraComponent extends Component { /** * Sets the camera component's clear color. Defaults to `[0.75, 0.75, 0.75, 1]`. * - * @type {import('../../../core/math/color.js').Color} + * @type {Color} */ set clearColor(value) { this._camera.clearColor = value; @@ -352,7 +363,7 @@ class CameraComponent extends Component { /** * Gets the camera component's clear color. * - * @type {import('../../../core/math/color.js').Color} + * @type {Color} */ get clearColor() { return this._camera.clearColor; @@ -519,7 +530,7 @@ class CameraComponent extends Component { /** * Gets the camera's frustum shape. * - * @type {import('../../../core/shape/frustum.js').Frustum} + * @type {Frustum} */ get frustum() { return this._camera.frustum; @@ -724,7 +735,7 @@ class CameraComponent extends Component { /** * Gets the camera's projection matrix. * - * @type {import('../../../core/math/mat4.js').Mat4} + * @type {Mat4} */ get projectionMatrix() { return this._camera.projectionMatrix; @@ -734,7 +745,7 @@ class CameraComponent extends Component { * Sets the rendering rectangle for the camera. This controls where on the screen the camera * will render in normalized screen coordinates. Defaults to `[0, 0, 1, 1]`. * - * @type {import('../../../core/math/vec4.js').Vec4} + * @type {Vec4} */ set rect(value) { this._camera.rect = value; @@ -744,7 +755,7 @@ class CameraComponent extends Component { /** * Gets the rendering rectangle for the camera. * - * @type {import('../../../core/math/vec4.js').Vec4} + * @type {Vec4} */ get rect() { return this._camera.rect; @@ -782,7 +793,7 @@ class CameraComponent extends Component { * Sets the render target to which rendering of the camera is performed. If not set, it will * render simply to the screen. * - * @type {import('../../../platform/graphics/render-target.js').RenderTarget} + * @type {RenderTarget} */ set renderTarget(value) { this._camera.renderTarget = value; @@ -792,7 +803,7 @@ class CameraComponent extends Component { /** * Gets the render target to which rendering of the camera is performed. * - * @type {import('../../../platform/graphics/render-target.js').RenderTarget} + * @type {RenderTarget} */ get renderTarget() { return this._camera.renderTarget; @@ -802,7 +813,7 @@ class CameraComponent extends Component { * Sets the scissor rectangle for the camera. This clips all pixels which are not in the * rectangle. The order of the values is `[x, y, width, height]`. Defaults to `[0, 0, 1, 1]`. * - * @type {import('../../../core/math/vec4.js').Vec4} + * @type {Vec4} */ set scissorRect(value) { this._camera.scissorRect = value; @@ -811,7 +822,7 @@ class CameraComponent extends Component { /** * Gets the scissor rectangle for the camera. * - * @type {import('../../../core/math/vec4.js').Vec4} + * @type {Vec4} */ get scissorRect() { return this._camera.scissorRect; @@ -856,7 +867,7 @@ class CameraComponent extends Component { /** * Gets the camera's view matrix. * - * @type {import('../../../core/math/mat4.js').Mat4} + * @type {Mat4} */ get viewMatrix() { return this._camera.viewMatrix; @@ -874,7 +885,7 @@ class CameraComponent extends Component { const hasDepthLayer = this.layers.find(layerId => layerId === LAYERID_DEPTH); if (hasDepthLayer) { - /** @type {import('../../../scene/layer.js').Layer} */ + /** @type {Layer} */ const depthLayer = this.system.app.scene.layers.getLayerById(LAYERID_DEPTH); if (value) { @@ -938,8 +949,7 @@ class CameraComponent extends Component { * 0 to `canvas.offsetHeight` of the application's canvas element. * @param {number} cameraz - The distance from the camera in world space to create the new * point. - * @param {import('../../../core/math/vec3.js').Vec3} [worldCoord] - 3D vector to receive world - * coordinate result. + * @param {Vec3} [worldCoord] - 3D vector to receive world coordinate result. * @example * // Get the start and end points of a 3D ray fired from a screen click position * const start = entity.camera.screenToWorld(clickX, clickY, entity.camera.nearClip); @@ -949,7 +959,7 @@ class CameraComponent extends Component { * app.systems.rigidbody.raycastFirst(start, end, function (result) { * console.log("Entity " + result.entity.name + " was selected"); * }); - * @returns {import('../../../core/math/vec3.js').Vec3} The world space coordinate. + * @returns {Vec3} The world space coordinate. */ screenToWorld(screenx, screeny, cameraz, worldCoord) { const device = this.system.app.graphicsDevice; @@ -961,10 +971,9 @@ class CameraComponent extends Component { /** * Convert a point from 3D world space to 2D screen space. * - * @param {import('../../../core/math/vec3.js').Vec3} worldCoord - The world space coordinate. - * @param {import('../../../core/math/vec3.js').Vec3} [screenCoord] - 3D vector to receive - * screen coordinate result. - * @returns {import('../../../core/math/vec3.js').Vec3} The screen space coordinate. + * @param {Vec3} worldCoord - The world space coordinate. + * @param {Vec3} [screenCoord] - 3D vector to receive screen coordinate result. + * @returns {Vec3} The screen space coordinate. */ worldToScreen(worldCoord, screenCoord) { const device = this.system.app.graphicsDevice; @@ -1006,8 +1015,8 @@ class CameraComponent extends Component { } /** - * @param {import('../../../scene/composition/layer-composition.js').LayerComposition} oldComp - Old layer composition. - * @param {import('../../../scene/composition/layer-composition.js').LayerComposition} newComp - New layer composition. + * @param {LayerComposition} oldComp - Old layer composition. + * @param {LayerComposition} newComp - New layer composition. * @private */ onLayersChanged(oldComp, newComp) { @@ -1019,7 +1028,7 @@ class CameraComponent extends Component { } /** - * @param {import('../../../scene/layer.js').Layer} layer - The layer to add the camera to. + * @param {Layer} layer - The layer to add the camera to. * @private */ onLayerAdded(layer) { @@ -1029,7 +1038,7 @@ class CameraComponent extends Component { } /** - * @param {import('../../../scene/layer.js').Layer} layer - The layer to remove the camera from. + * @param {Layer} layer - The layer to remove the camera from. * @private */ onLayerRemoved(layer) { @@ -1086,7 +1095,7 @@ class CameraComponent extends Component { /** * Calculates aspect ratio value for a given render target. * - * @param {import('../../../platform/graphics/render-target.js').RenderTarget|null} [rt] - Optional + * @param {RenderTarget|null} [rt] - Optional * render target. If unspecified, the backbuffer is used. * @returns {number} The aspect ratio of the render target (or backbuffer). */ @@ -1100,7 +1109,7 @@ class CameraComponent extends Component { /** * Prepare the camera for frame rendering. * - * @param {import('../../../platform/graphics/render-target.js').RenderTarget|null} [rt] - Render + * @param {RenderTarget|null} [rt] - Render * target to which rendering will be performed. Will affect camera's aspect ratio, if * aspectRatioMode is {@link ASPECT_AUTO}. * @ignore @@ -1144,9 +1153,9 @@ class CameraComponent extends Component { * used for getting access to additional WebXR spec extensions. * @param {boolean} [options.imageTracking] - Set to true to attempt to enable {@link XrImageTracking}. * @param {boolean} [options.planeDetection] - Set to true to attempt to enable {@link XrPlaneDetection}. - * @param {import('../../xr/xr-manager.js').XrErrorCallback} [options.callback] - Optional - * callback function called once the session is started. The callback has one argument Error - - * it is null if the XR session started successfully. + * @param {XrErrorCallback} [options.callback] - Optional callback function called once the + * session is started. The callback has one argument Error - it is null if the XR session + * started successfully. * @param {boolean} [options.anchors] - Optional boolean to attempt to enable {@link XrAnchors}. * @param {object} [options.depthSensing] - Optional object with parameters to attempt to enable * depth sensing. @@ -1177,9 +1186,8 @@ class CameraComponent extends Component { /** * Attempt to end XR session of this camera. * - * @param {import('../../xr/xr-manager.js').XrErrorCallback} [callback] - Optional callback - * function called once session is ended. The callback has one argument Error - it is null if - * successfully ended XR session. + * @param {XrErrorCallback} [callback] - Optional callback function called once session is + * ended. The callback has one argument Error - it is null if successfully ended XR session. * @example * // On an entity with a camera component * this.entity.camera.endXr(function (err) { @@ -1196,9 +1204,8 @@ class CameraComponent extends Component { } /** - * Function to copy properties from the source CameraComponent. - * Properties not copied: postEffects. - * Inherited properties not copied (all): system, entity, enabled. + * Function to copy properties from the source CameraComponent. Properties not copied: + * postEffects. Inherited properties not copied (all): system, entity, enabled. * * @param {CameraComponent} source - The source component. * @ignore diff --git a/src/framework/components/camera/post-effect-queue.js b/src/framework/components/camera/post-effect-queue.js index 45498bdcf58..21c334f9c16 100644 --- a/src/framework/components/camera/post-effect-queue.js +++ b/src/framework/components/camera/post-effect-queue.js @@ -2,9 +2,14 @@ import { ADDRESS_CLAMP_TO_EDGE, FILTER_NEAREST, PIXELFORMAT_RGBA16F, PIXELFORMAT import { DebugGraphics } from '../../../platform/graphics/debug-graphics.js'; import { RenderTarget } from '../../../platform/graphics/render-target.js'; import { Texture } from '../../../platform/graphics/texture.js'; - import { LAYERID_DEPTH } from '../../../scene/constants.js'; +/** + * @import { AppBase } from '../../app-base.js' + * @import { CameraComponent } from './component.js' + * @import { PostEffect } from '../../../scene/graphics/post-effect.js' + */ + class PostEffectEntry { constructor(effect, inputTarget) { this.effect = effect; @@ -23,8 +28,8 @@ class PostEffectQueue { /** * Create a new PostEffectQueue instance. * - * @param {import('../../app-base.js').AppBase} app - The application. - * @param {import('./component.js').CameraComponent} camera - The camera component. + * @param {AppBase} app - The application. + * @param {CameraComponent} camera - The camera component. */ constructor(app, camera) { this.app = app; @@ -136,8 +141,7 @@ class PostEffectQueue { * Adds a post effect to the queue. If the queue is disabled adding a post effect will * automatically enable the queue. * - * @param {import('../../../scene/graphics/post-effect.js').PostEffect} effect - The post - * effect to add to the queue. + * @param {PostEffect} effect - The post effect to add to the queue. */ addEffect(effect) { // first rendering of the scene requires depth buffer @@ -169,8 +173,7 @@ class PostEffectQueue { * Removes a post effect from the queue. If the queue becomes empty it will be disabled * automatically. * - * @param {import('../../../scene/graphics/post-effect.js').PostEffect} effect - The post effect - * to remove. + * @param {PostEffect} effect - The post effect to remove. */ removeEffect(effect) { diff --git a/src/framework/components/camera/system.js b/src/framework/components/camera/system.js index e68a438e243..84d872a04f5 100644 --- a/src/framework/components/camera/system.js +++ b/src/framework/components/camera/system.js @@ -1,13 +1,15 @@ import { sortPriority } from '../../../core/sort.js'; import { Color } from '../../../core/math/color.js'; import { Vec4 } from '../../../core/math/vec4.js'; - import { Component } from '../component.js'; import { ComponentSystem } from '../system.js'; - import { CameraComponent } from './component.js'; import { CameraComponentData } from './data.js'; +/** + * @import { AppBase } from '../../app-base.js' + */ + const _schema = ['enabled']; /** @@ -27,7 +29,7 @@ class CameraComponentSystem extends ComponentSystem { /** * Create a new CameraComponentSystem instance. * - * @param {import('../../app-base.js').AppBase} app - The Application. + * @param {AppBase} app - The Application. * @ignore */ constructor(app) { diff --git a/src/framework/components/collision/component.js b/src/framework/components/collision/component.js index 56fdca259a1..34c681606d7 100644 --- a/src/framework/components/collision/component.js +++ b/src/framework/components/collision/component.js @@ -1,10 +1,16 @@ import { Quat } from '../../../core/math/quat.js'; import { Vec3 } from '../../../core/math/vec3.js'; - import { Asset } from '../../asset/asset.js'; - import { Component } from '../component.js'; +/** + * @import { CollisionComponentData } from './data.js' + * @import { CollisionComponentSystem } from './system.js' + * @import { Entity } from '../../entity.js' + * @import { GraphNode } from '../../../scene/graph-node.js' + * @import { Model } from '../../../scene/model.js' + */ + const _vec3 = new Vec3(); const _quat = new Quat(); @@ -91,10 +97,8 @@ class CollisionComponent extends Component { /** * Create a new CollisionComponent. * - * @param {import('./system.js').CollisionComponentSystem} system - The ComponentSystem that - * created this Component. - * @param {import('../../entity.js').Entity} entity - The Entity that this Component is - * attached to. + * @param {CollisionComponentSystem} system - The ComponentSystem that created this Component. + * @param {Entity} entity - The Entity that this Component is attached to. */ constructor(system, entity) { super(system, entity); @@ -121,7 +125,7 @@ class CollisionComponent extends Component { // TODO: Remove this override in upgrading component /** - * @type {import('./data.js').CollisionComponentData} + * @type {CollisionComponentData} * @ignore */ get data() { @@ -361,7 +365,7 @@ class CollisionComponent extends Component { /** * Sets the model that is added to the scene graph for the mesh collision volume. * - * @type {import('../../../scene/model.js').Model | null} + * @type {Model | null} */ set model(arg) { this._setValue('model', arg); @@ -370,7 +374,7 @@ class CollisionComponent extends Component { /** * Gets the model that is added to the scene graph for the mesh collision volume. * - * @type {import('../../../scene/model.js').Model | null} + * @type {Model | null} */ get model() { return this.data.model; @@ -637,7 +641,7 @@ class CollisionComponent extends Component { } /** - * @param {import('../../../scene/graph-node.js').GraphNode} parent - The parent node. + * @param {GraphNode} parent - The parent node. * @private */ _onInsert(parent) { diff --git a/src/framework/components/collision/data.js b/src/framework/components/collision/data.js index 2adf57377a2..3bb0917687c 100644 --- a/src/framework/components/collision/data.js +++ b/src/framework/components/collision/data.js @@ -1,6 +1,11 @@ import { Quat } from '../../../core/math/quat.js'; import { Vec3 } from '../../../core/math/vec3.js'; +/** + * @import { Asset } from '../../../framework/asset/asset.js' + * @import { Model } from '../../../scene/model.js' + */ + class CollisionComponentData { constructor() { this.enabled = true; @@ -12,15 +17,15 @@ class CollisionComponentData { this.axis = 1; this.height = 2; this.convexHull = false; - /** @type {import('../../../framework/asset/asset.js').Asset | number} */ + /** @type {Asset | number} */ this.asset = null; - /** @type {import('../../../framework/asset/asset.js').Asset | number} */ + /** @type {Asset | number} */ this.renderAsset = null; this.checkVertexDuplicates = true; // Non-serialized properties this.shape = null; - /** @type {import('../../../scene/model.js').Model | null} */ + /** @type {Model | null} */ this.model = null; this.render = null; this.initialized = false; diff --git a/src/framework/components/collision/system.js b/src/framework/components/collision/system.js index 6d5830dc062..2187aafce2b 100644 --- a/src/framework/components/collision/system.js +++ b/src/framework/components/collision/system.js @@ -1,20 +1,19 @@ import { Debug } from '../../../core/debug.js'; - import { Mat4 } from '../../../core/math/mat4.js'; import { Quat } from '../../../core/math/quat.js'; import { Vec3 } from '../../../core/math/vec3.js'; - import { SEMANTIC_POSITION } from '../../../platform/graphics/constants.js'; - import { GraphNode } from '../../../scene/graph-node.js'; import { Model } from '../../../scene/model.js'; - import { ComponentSystem } from '../system.js'; - import { CollisionComponent } from './component.js'; import { CollisionComponentData } from './data.js'; import { Trigger } from './trigger.js'; +/** + * @import { AppBase } from '../../app-base.js' + */ + const mat4 = new Mat4(); const p1 = new Vec3(); const p2 = new Vec3(); @@ -654,7 +653,7 @@ class CollisionComponentSystem extends ComponentSystem { /** * Creates a new CollisionComponentSystem instance. * - * @param {import('../../app-base.js').AppBase} app - The running {@link AppBase}. + * @param {AppBase} app - The running {@link AppBase}. * @ignore */ constructor(app) { diff --git a/src/framework/components/collision/trigger.js b/src/framework/components/collision/trigger.js index cc78577b3a3..6dcec1fd09f 100644 --- a/src/framework/components/collision/trigger.js +++ b/src/framework/components/collision/trigger.js @@ -1,5 +1,10 @@ import { BODYFLAG_NORESPONSE_OBJECT, BODYMASK_NOT_STATIC, BODYGROUP_TRIGGER, BODYSTATE_ACTIVE_TAG, BODYSTATE_DISABLE_SIMULATION } from '../rigid-body/constants.js'; +/** + * @import { AppBase } from '../../app-base.js' + * @import { Component } from '../component.js' + */ + let _ammoVec1, _ammoQuat, _ammoTransform; /** @@ -10,10 +15,9 @@ class Trigger { /** * Create a new Trigger instance. * - * @param {import('../../app-base.js').AppBase} app - The running {@link AppBase}. - * @param {import('../component.js').Component} component - The component for which the trigger - * will be created. - * @param {ComponentData} data - The data for the component. + * @param {AppBase} app - The running {@link AppBase}. + * @param {Component} component - The component for which the trigger will be created. + * @param {object} data - The data for the component. */ constructor(app, component, data) { this.entity = component.entity; diff --git a/src/framework/components/component.js b/src/framework/components/component.js index 062c4e5baef..988d0be96b6 100644 --- a/src/framework/components/component.js +++ b/src/framework/components/component.js @@ -1,5 +1,10 @@ import { EventHandler } from '../../core/event-handler.js'; +/** + * @import { ComponentSystem } from './system.js' + * @import { Entity } from '../entity.js' + */ + /** * Components are used to attach functionality on a {@link Entity}. Components can receive update * events each frame, and expose properties to the PlayCanvas Editor. @@ -17,24 +22,22 @@ class Component extends EventHandler { /** * The ComponentSystem used to create this Component. * - * @type {import('./system.js').ComponentSystem} + * @type {ComponentSystem} */ system; /** * The Entity that this Component is attached to. * - * @type {import('../entity.js').Entity} + * @type {Entity} */ entity; /** * Base constructor for a Component. * - * @param {import('./system.js').ComponentSystem} system - The ComponentSystem used to create - * this Component. - * @param {import('../entity.js').Entity} entity - The Entity that this Component is attached - * to. + * @param {ComponentSystem} system - The ComponentSystem used to create this component. + * @param {Entity} entity - The Entity that this Component is attached to. */ constructor(system, entity) { super(); diff --git a/src/framework/components/element/component.js b/src/framework/components/element/component.js index 7f52ea5e4cd..808cc61df76 100644 --- a/src/framework/components/element/component.js +++ b/src/framework/components/element/component.js @@ -1,25 +1,31 @@ import { Debug } from '../../../core/debug.js'; import { TRACE_ID_ELEMENT } from '../../../core/constants.js'; - import { Mat4 } from '../../../core/math/mat4.js'; import { Vec2 } from '../../../core/math/vec2.js'; import { Vec3 } from '../../../core/math/vec3.js'; import { Vec4 } from '../../../core/math/vec4.js'; - import { FUNC_ALWAYS, FUNC_EQUAL, STENCILOP_INCREMENT, STENCILOP_REPLACE } from '../../../platform/graphics/constants.js'; - import { LAYERID_UI } from '../../../scene/constants.js'; import { BatchGroup } from '../../../scene/batching/batch-group.js'; import { StencilParameters } from '../../../platform/graphics/stencil-parameters.js'; - import { Entity } from '../../entity.js'; - import { Component } from '../component.js'; - import { ELEMENTTYPE_GROUP, ELEMENTTYPE_IMAGE, ELEMENTTYPE_TEXT, FITMODE_STRETCH } from './constants.js'; import { ImageElement } from './image-element.js'; import { TextElement } from './text-element.js'; +/** + * @import { BoundingBox } from '../../../core/shape/bounding-box.js' + * @import { CanvasFont } from '../../../framework/font/canvas-font.js' + * @import { Color } from '../../../core/math/color.js' + * @import { ElementComponentData } from './data.js' + * @import { ElementComponentSystem } from './system.js' + * @import { Font } from '../../../framework/font/font.js' + * @import { Material } from '../../../scene/materials/material.js' + * @import { Sprite } from '../../../scene/sprite.js' + * @import { Texture } from '../../../platform/graphics/texture.js' + */ + const position = new Vec3(); const invParentWtm = new Mat4(); @@ -215,8 +221,7 @@ class ElementComponent extends Component { /** * Create a new ElementComponent instance. * - * @param {import('./system.js').ElementComponentSystem} system - The ComponentSystem that - * created this Component. + * @param {ElementComponentSystem} system - The ComponentSystem that created this Component. * @param {Entity} entity - The Entity that this Component is attached to. */ constructor(system, entity) { @@ -309,7 +314,7 @@ class ElementComponent extends Component { // TODO: Remove this override in upgrading component /** - * @type {import('./data.js').ElementComponentData} + * @type {ElementComponentData} * @ignore */ get data() { @@ -389,7 +394,7 @@ class ElementComponent extends Component { /** * Gets the world space axis-aligned bounding box for this element component. * - * @type {import('../../../core/shape/bounding-box.js').BoundingBox | null} + * @type {BoundingBox | null} */ get aabb() { if (this._image) { @@ -1260,7 +1265,7 @@ class ElementComponent extends Component { * Sets the color of the image for {@link ELEMENTTYPE_IMAGE} types or the color of the text for * {@link ELEMENTTYPE_TEXT} types. * - * @type {import('../../../core/math/color.js').Color} + * @type {Color} */ set color(arg) { this._setValue('color', arg); @@ -1269,7 +1274,7 @@ class ElementComponent extends Component { /** * Gets the color of the element. * - * @type {import('../../../core/math/color.js').Color} + * @type {Color} */ get color() { if (this._text) { @@ -1286,7 +1291,7 @@ class ElementComponent extends Component { /** * Sets the font used for rendering the text. Only works for {@link ELEMENTTYPE_TEXT} types. * - * @type {import('../../../framework/font/font.js').Font | import('../../../framework/font/canvas-font.js').CanvasFont} + * @type {Font|CanvasFont} */ set font(arg) { this._setValue('font', arg); @@ -1295,7 +1300,7 @@ class ElementComponent extends Component { /** * Gets the font used for rendering the text. * - * @type {import('../../../framework/font/font.js').Font | import('../../../framework/font/canvas-font.js').CanvasFont} + * @type {Font|CanvasFont} */ get font() { if (this._text) { @@ -1590,7 +1595,7 @@ class ElementComponent extends Component { /** * Sets the texture to render. Only works for {@link ELEMENTTYPE_IMAGE} types. * - * @type {import('../../../platform/graphics/texture.js').Texture} + * @type {Texture} */ set texture(arg) { this._setValue('texture', arg); @@ -1599,7 +1604,7 @@ class ElementComponent extends Component { /** * Gets the texture to render. * - * @type {import('../../../platform/graphics/texture.js').Texture} + * @type {Texture} */ get texture() { if (this._image) { @@ -1634,7 +1639,7 @@ class ElementComponent extends Component { /** * Sets the material to use when rendering an image. Only works for {@link ELEMENTTYPE_IMAGE} types. * - * @type {import('../../../scene/materials/material.js').Material} + * @type {Material} */ set material(arg) { this._setValue('material', arg); @@ -1643,7 +1648,7 @@ class ElementComponent extends Component { /** * Gets the material to use when rendering an image. * - * @type {import('../../../scene/materials/material.js').Material} + * @type {Material} */ get material() { if (this._image) { @@ -1680,7 +1685,7 @@ class ElementComponent extends Component { * Sets the sprite to render. Only works for {@link ELEMENTTYPE_IMAGE} types which can render * either a texture or a sprite. * - * @type {import('../../../scene/sprite.js').Sprite} + * @type {Sprite} */ set sprite(arg) { this._setValue('sprite', arg); @@ -1689,7 +1694,7 @@ class ElementComponent extends Component { /** * Gets the sprite to render. * - * @type {import('../../../scene/sprite.js').Sprite} + * @type {Sprite} */ get sprite() { if (this._image) { @@ -1844,7 +1849,7 @@ class ElementComponent extends Component { /** * Sets the text outline effect color and opacity. Only works for {@link ELEMENTTYPE_TEXT} types. * - * @type {import('../../../core/math/color.js').Color} + * @type {Color} */ set outlineColor(arg) { this._setValue('outlineColor', arg); @@ -1853,7 +1858,7 @@ class ElementComponent extends Component { /** * Gets the text outline effect color and opacity. * - * @type {import('../../../core/math/color.js').Color} + * @type {Color} */ get outlineColor() { if (this._text) { @@ -1887,7 +1892,7 @@ class ElementComponent extends Component { /** * Sets the text shadow effect color and opacity. Only works for {@link ELEMENTTYPE_TEXT} types. * - * @type {import('../../../core/math/color.js').Color} + * @type {Color} */ set shadowColor(arg) { this._setValue('shadowColor', arg); @@ -1896,7 +1901,7 @@ class ElementComponent extends Component { /** * Gets the text shadow effect color and opacity. * - * @type {import('../../../core/math/color.js').Color} + * @type {Color} */ get shadowColor() { if (this._text) { diff --git a/src/framework/components/element/element-drag-helper.js b/src/framework/components/element/element-drag-helper.js index e9df0481d37..ec542d980ac 100644 --- a/src/framework/components/element/element-drag-helper.js +++ b/src/framework/components/element/element-drag-helper.js @@ -1,14 +1,16 @@ import { platform } from '../../../core/platform.js'; import { EventHandler } from '../../../core/event-handler.js'; - import { Quat } from '../../../core/math/quat.js'; import { Vec2 } from '../../../core/math/vec2.js'; import { Vec3 } from '../../../core/math/vec3.js'; - import { ElementComponent } from './component.js'; import { Ray } from '../../../core/shape/ray.js'; import { Plane } from '../../../core/shape/plane.js'; +/** + * @import { ElementMouseEvent, ElementSelectEvent, ElementTouchEvent } from '../../input/element-input.js' + */ + const _inputScreenPosition = new Vec2(); const _inputWorldPosition = new Vec3(); const _ray = new Ray(); @@ -166,7 +168,7 @@ class ElementDragHelper extends EventHandler { * This method calculates the `Vec3` intersection point of plane/ray intersection based on * the mouse/touch input event. If there is no intersection, it returns `null`. * - * @param {import('../../input/element-input').ElementTouchEvent | import('../../input/element-input').ElementMouseEvent | import('../../input/element-input').ElementSelectEvent} event - The event. + * @param {ElementTouchEvent|ElementMouseEvent|ElementSelectEvent} event - The event. * @returns {Vec3|null} The `Vec3` intersection point of plane/ray intersection, if there * is an intersection, otherwise `null` * @private @@ -242,7 +244,7 @@ class ElementDragHelper extends EventHandler { /** * This method is linked to `_element` events: `mousemove` and `touchmove` * - * @param {import('../../input/element-input').ElementTouchEvent} event - The event. + * @param {ElementTouchEvent} event - The event. * @private */ _onMove(event) { diff --git a/src/framework/components/element/image-element.js b/src/framework/components/element/image-element.js index 4bef785df40..ae2d4c0c003 100644 --- a/src/framework/components/element/image-element.js +++ b/src/framework/components/element/image-element.js @@ -1,12 +1,10 @@ import { Debug } from '../../../core/debug.js'; import { TRACE_ID_ELEMENT } from '../../../core/constants.js'; - import { math } from '../../../core/math/math.js'; import { Color } from '../../../core/math/color.js'; import { Vec2 } from '../../../core/math/vec2.js'; import { Vec3 } from '../../../core/math/vec3.js'; import { Vec4 } from '../../../core/math/vec4.js'; - import { FUNC_EQUAL, PRIMITIVE_TRISTRIP, @@ -17,7 +15,6 @@ import { import { VertexBuffer } from '../../../platform/graphics/vertex-buffer.js'; import { VertexFormat } from '../../../platform/graphics/vertex-format.js'; import { DeviceCache } from '../../../platform/graphics/device-cache.js'; - import { LAYER_HUD, LAYER_WORLD, SPRITE_RENDERMODE_SIMPLE, SPRITE_RENDERMODE_SLICED, SPRITE_RENDERMODE_TILED @@ -27,11 +24,16 @@ import { Mesh } from '../../../scene/mesh.js'; import { MeshInstance } from '../../../scene/mesh-instance.js'; import { Model } from '../../../scene/model.js'; import { StencilParameters } from '../../../platform/graphics/stencil-parameters.js'; - import { FITMODE_STRETCH, FITMODE_CONTAIN, FITMODE_COVER } from './constants.js'; - import { Asset } from '../../asset/asset.js'; +/** + * @import { BoundingBox } from '../../../core/shape/bounding-box.js' + * @import { Material } from '../../../scene/materials/material.js' + * @import { Sprite } from '../../../scene/sprite.js' + * @import { Texture } from '../../../platform/graphics/texture.js' + */ + const _tempColor = new Color(); const _vertexFormatDeviceCache = new DeviceCache(); @@ -268,15 +270,15 @@ class ImageElement { // public /** @type {number} */ this._textureAsset = null; - /** @type {import('../../../platform/graphics/texture.js').Texture} */ + /** @type {Texture} */ this._texture = null; /** @type {number} */ this._materialAsset = null; - /** @type {import('../../../scene/materials/material.js').Material} */ + /** @type {Material} */ this._material = null; /** @type {number} */ this._spriteAsset = null; - /** @type {import('../../../scene/sprite.js').Sprite} */ + /** @type {Sprite} */ this._sprite = null; this._spriteFrame = 0; /** @type {number} */ @@ -1321,7 +1323,7 @@ class ImageElement { // private /** - * @type {import('../../../core/shape/bounding-box.js').BoundingBox | null} + * @type {BoundingBox | null} */ get aabb() { if (this._renderable.meshInstance) { diff --git a/src/framework/components/element/system.js b/src/framework/components/element/system.js index 1573c95ba75..f8f63fa8e25 100644 --- a/src/framework/components/element/system.js +++ b/src/framework/components/element/system.js @@ -1,21 +1,19 @@ import { Color } from '../../../core/math/color.js'; import { Vec2 } from '../../../core/math/vec2.js'; import { Vec4 } from '../../../core/math/vec4.js'; - -import { - PIXELFORMAT_RGBA8 -} from '../../../platform/graphics/constants.js'; +import { PIXELFORMAT_RGBA8 } from '../../../platform/graphics/constants.js'; import { Texture } from '../../../platform/graphics/texture.js'; - import { BLEND_PREMULTIPLIED, SPRITE_RENDERMODE_SLICED, SPRITE_RENDERMODE_TILED } from '../../../scene/constants.js'; import { StandardMaterial } from '../../../scene/materials/standard-material.js'; - import { ComponentSystem } from '../system.js'; - import { ELEMENTTYPE_IMAGE, ELEMENTTYPE_TEXT } from './constants.js'; import { ElementComponent } from './component.js'; import { ElementComponentData } from './data.js'; +/** + * @import { AppBase } from '../../app-base.js' + */ + const _schema = ['enabled']; /** @@ -27,7 +25,7 @@ class ElementComponentSystem extends ComponentSystem { /** * Create a new ElementComponentSystem instance. * - * @param {import('../../app-base.js').AppBase} app - The application. + * @param {AppBase} app - The application. * @ignore */ constructor(app) { @@ -353,9 +351,8 @@ class ElementComponentSystem extends ComponentSystem { material.emissive.set(1, 1, 1); } else { name = "Bitmap" + name; - material.emissive.set(0.5, 0.5, 0.5); // set to non-(1,1,1) so that tint is actually applied + material.emissive.set(1, 1, 1); material.emissiveMap = this._defaultTexture; - material.emissiveTint = true; material.opacityMap = this._defaultTexture; material.opacityMapChannel = 'a'; } @@ -391,9 +388,8 @@ class ElementComponentSystem extends ComponentSystem { const material = new StandardMaterial(); material.diffuse.set(0, 0, 0); // black diffuse color to prevent ambient light being included - material.emissive.set(0.5, 0.5, 0.5); // use non-white to compile shader correctly + material.emissive.set(1, 1, 1); material.emissiveMap = this._defaultTexture; - material.emissiveTint = true; material.opacityMap = this._defaultTexture; material.opacityMapChannel = 'a'; material.opacityTint = true; diff --git a/src/framework/components/element/text-element.js b/src/framework/components/element/text-element.js index ccef59b9bcb..04eb662c086 100644 --- a/src/framework/components/element/text-element.js +++ b/src/framework/components/element/text-element.js @@ -1,25 +1,24 @@ import { Debug } from '../../../core/debug.js'; import { string } from '../../../core/string.js'; - import { math } from '../../../core/math/math.js'; import { Color } from '../../../core/math/color.js'; import { Vec2 } from '../../../core/math/vec2.js'; - import { BoundingBox } from '../../../core/shape/bounding-box.js'; - import { SEMANTIC_POSITION, SEMANTIC_TEXCOORD0, SEMANTIC_COLOR, SEMANTIC_ATTR8, SEMANTIC_ATTR9, TYPE_FLOAT32 } from '../../../platform/graphics/constants.js'; import { VertexIterator } from '../../../platform/graphics/vertex-iterator.js'; import { GraphNode } from '../../../scene/graph-node.js'; import { MeshInstance } from '../../../scene/mesh-instance.js'; import { Model } from '../../../scene/model.js'; import { Mesh } from '../../../scene/mesh.js'; - import { LocalizedAsset } from '../../asset/asset-localized.js'; - import { FONT_BITMAP, FONT_MSDF } from '../../font/constants.js'; - import { Markup } from './markup.js'; +/** + * @import { CanvasFont } from '../../../framework/font/canvas-font.js' + * @import { Font } from '../../../framework/font/font.js' + */ + class MeshInfo { constructor() { // number of symbols @@ -139,7 +138,7 @@ class TextElement { this._fontAsset.on('change', this._onFontChange, this); this._fontAsset.on('remove', this._onFontRemove, this); - /** @type {import('../../../framework/font/font.js').Font | import('../../../framework/font/canvas-font.js').CanvasFont} */ + /** @type {Font | CanvasFont} */ this._font = null; this._color = new Color(1, 1, 1, 1); @@ -1909,7 +1908,7 @@ class TextElement { // private /** - * @type {import('../../../core/shape/bounding-box.js').BoundingBox} + * @type {BoundingBox} */ get aabb() { if (this._aabbDirty) { diff --git a/src/framework/components/gsplat/component.js b/src/framework/components/gsplat/component.js index 847315efd34..f9cb66e62f8 100644 --- a/src/framework/components/gsplat/component.js +++ b/src/framework/components/gsplat/component.js @@ -3,6 +3,15 @@ import { Asset } from '../../asset/asset.js'; import { AssetReference } from '../../asset/asset-reference.js'; import { Component } from '../component.js'; +/** + * @import { BoundingBox } from '../../../core/shape/bounding-box.js' + * @import { Entity } from '../../entity.js' + * @import { GSplatComponentSystem } from './system.js' + * @import { GSplatInstance } from '../../../scene/gsplat/gsplat-instance.js' + * @import { Material } from '../../../scene/materials/material.js' + * @import { SplatMaterialOptions } from '../../../scene/gsplat/gsplat-material.js' + */ + /** * The GSplatComponent enables an {@link Entity} to render 3D Gaussian Splats. Splats are always * loaded from {@link Asset}s rather than being created programmatically. The asset type is @@ -20,13 +29,13 @@ class GSplatComponent extends Component { _layers = [LAYERID_WORLD]; // assign to the default world layer /** - * @type {import('../../../scene/gsplat/gsplat-instance.js').GSplatInstance|null} + * @type {GSplatInstance|null} * @private */ _instance = null; /** - * @type {import('../../../core/shape/bounding-box.js').BoundingBox|null} + * @type {BoundingBox|null} * @private */ _customAabb = null; @@ -38,7 +47,7 @@ class GSplatComponent extends Component { _assetReference; /** - * @type {import('../../../scene/gsplat/gsplat-material.js').SplatMaterialOptions|null} + * @type {SplatMaterialOptions|null} * @private */ _materialOptions = null; @@ -46,10 +55,8 @@ class GSplatComponent extends Component { /** * Create a new GSplatComponent. * - * @param {import('./system.js').GSplatComponentSystem} system - The ComponentSystem that - * created this Component. - * @param {import('../../entity.js').Entity} entity - The Entity that this Component is - * attached to. + * @param {GSplatComponentSystem} system - The ComponentSystem that created this Component. + * @param {Entity} entity - The Entity that this Component is attached to. */ constructor(system, entity) { super(system, entity); @@ -78,7 +85,7 @@ class GSplatComponent extends Component { /** * Sets a custom object space bounding box for visibility culling of the attached gsplat. * - * @type {import('../../../core/shape/bounding-box.js').BoundingBox|null} + * @type {BoundingBox|null} */ set customAabb(value) { this._customAabb = value; @@ -90,7 +97,7 @@ class GSplatComponent extends Component { /** * Gets the custom object space bounding box for visibility culling of the attached gsplat. * - * @type {import('../../../core/shape/bounding-box.js').BoundingBox|null} + * @type {BoundingBox|null} */ get customAabb() { return this._customAabb; @@ -99,7 +106,7 @@ class GSplatComponent extends Component { /** * Sets a {@link GSplatInstance} on the component. If not set or loaded, it returns null. * - * @type {import('../../../scene/gsplat/gsplat-instance.js').GSplatInstance|null} + * @type {GSplatInstance|null} * @ignore */ set instance(value) { @@ -133,7 +140,7 @@ class GSplatComponent extends Component { /** * Gets the {@link GSplatInstance} on the component. * - * @type {import('../../../scene/gsplat/gsplat-instance.js').GSplatInstance|null} + * @type {GSplatInstance|null} * @ignore */ get instance() { @@ -156,7 +163,7 @@ class GSplatComponent extends Component { /** * Gets the material used to render the gsplat. * - * @type {import('../../../scene/materials/material.js').Material|undefined} + * @type {Material|undefined} */ get material() { return this._instance?.material; diff --git a/src/framework/components/gsplat/system.js b/src/framework/components/gsplat/system.js index a720d2e352c..747beef34b1 100644 --- a/src/framework/components/gsplat/system.js +++ b/src/framework/components/gsplat/system.js @@ -1,12 +1,14 @@ import { Vec3 } from '../../../core/math/vec3.js'; import { BoundingBox } from '../../../core/shape/bounding-box.js'; - import { Component } from '../component.js'; import { ComponentSystem } from '../system.js'; - import { GSplatComponent } from './component.js'; import { GSplatComponentData } from './data.js'; +/** + * @import { AppBase } from '../../app-base.js' + */ + const _schema = [ 'enabled' ]; @@ -27,7 +29,7 @@ class GSplatComponentSystem extends ComponentSystem { /** * Create a new GSplatComponentSystem. * - * @param {import('../../app-base.js').AppBase} app - The Application. + * @param {AppBase} app - The Application. * @ignore */ constructor(app) { diff --git a/src/framework/components/joint/component.js b/src/framework/components/joint/component.js index 09b9a34d2ee..0b4307840ce 100644 --- a/src/framework/components/joint/component.js +++ b/src/framework/components/joint/component.js @@ -1,14 +1,16 @@ import { Debug } from '../../../core/debug.js'; - import { math } from '../../../core/math/math.js'; import { Mat4 } from '../../../core/math/mat4.js'; import { Quat } from '../../../core/math/quat.js'; import { Vec2 } from '../../../core/math/vec2.js'; - import { Component } from '../component.js'; - import { MOTION_FREE, MOTION_LIMITED, MOTION_LOCKED } from './constants.js'; +/** + * @import { Entity } from '../../entity.js' + * @import { JointComponentSystem } from './system.js' + */ + const properties = [ 'angularDampingX', 'angularDampingY', 'angularDampingZ', 'angularEquilibriumX', 'angularEquilibriumY', 'angularEquilibriumZ', @@ -34,10 +36,8 @@ class JointComponent extends Component { /** * Create a new JointComponent instance. * - * @param {import('./system.js').JointComponentSystem} system - The ComponentSystem that - * created this Component. - * @param {import('../../entity.js').Entity} entity - The Entity that this Component is - * attached to. + * @param {JointComponentSystem} system - The ComponentSystem that created this Component. + * @param {Entity} entity - The Entity that this Component is attached to. */ constructor(system, entity) { super(system, entity); diff --git a/src/framework/components/joint/system.js b/src/framework/components/joint/system.js index 429aa2fb908..5e8f0e7850e 100644 --- a/src/framework/components/joint/system.js +++ b/src/framework/components/joint/system.js @@ -1,9 +1,12 @@ import { Component } from '../component.js'; import { ComponentSystem } from '../system.js'; - import { JointComponent } from './component.js'; import { JointComponentData } from './data.js'; +/** + * @import { AppBase } from '../../app-base.js' + */ + const _schema = ['enabled']; /** @@ -15,8 +18,7 @@ class JointComponentSystem extends ComponentSystem { /** * Create a new JointComponentSystem instance. * - * @param {import('../../app-base.js').AppBase} app - The application. - * @ignore + * @param {AppBase} app - The application. */ constructor(app) { super(app); diff --git a/src/framework/components/layout-child/component.js b/src/framework/components/layout-child/component.js index 87435571054..6cdce897dcf 100644 --- a/src/framework/components/layout-child/component.js +++ b/src/framework/components/layout-child/component.js @@ -1,5 +1,10 @@ import { Component } from '../component.js'; +/** + * @import { Entity } from '../../entity.js' + * @import { LayoutChildComponentSystem } from './system.js' + */ + /** * A LayoutChildComponent enables the Entity to control the sizing applied to it by its parent * {@link LayoutGroupComponent}. @@ -10,10 +15,8 @@ class LayoutChildComponent extends Component { /** * Create a new LayoutChildComponent. * - * @param {import('./system.js').LayoutChildComponentSystem} system - The ComponentSystem that - * created this Component. - * @param {import('../../entity.js').Entity} entity - The Entity that this Component is - * attached to. + * @param {LayoutChildComponentSystem} system - The ComponentSystem that created this Component. + * @param {Entity} entity - The Entity that this Component is attached to. */ constructor(system, entity) { super(system, entity); diff --git a/src/framework/components/layout-child/system.js b/src/framework/components/layout-child/system.js index 260a1a7563b..48ee36fa270 100644 --- a/src/framework/components/layout-child/system.js +++ b/src/framework/components/layout-child/system.js @@ -1,9 +1,12 @@ import { Component } from '../component.js'; import { ComponentSystem } from '../system.js'; - import { LayoutChildComponent } from './component.js'; import { LayoutChildComponentData } from './data.js'; +/** + * @import { AppBase } from '../../app-base.js' + */ + const _schema = ['enabled']; /** @@ -15,7 +18,7 @@ class LayoutChildComponentSystem extends ComponentSystem { /** * Create a new LayoutChildComponentSystem instance. * - * @param {import('../../app-base.js').AppBase} app - The application. + * @param {AppBase} app - The application. * @ignore */ constructor(app) { diff --git a/src/framework/components/layout-group/component.js b/src/framework/components/layout-group/component.js index f2cc6a67c3b..599c4123a0e 100644 --- a/src/framework/components/layout-group/component.js +++ b/src/framework/components/layout-group/component.js @@ -1,13 +1,16 @@ import { Debug } from '../../../core/debug.js'; import { Vec2 } from '../../../core/math/vec2.js'; import { Vec4 } from '../../../core/math/vec4.js'; - import { ORIENTATION_HORIZONTAL } from '../../../scene/constants.js'; - import { FITTING_NONE } from './constants.js'; import { Component } from '../component.js'; import { LayoutCalculator } from './layout-calculator.js'; +/** + * @import { Entity } from '../../entity.js' + * @import { LayoutGroupComponentSystem } from './system.js' + */ + function getElement(entity) { return entity.element; } @@ -26,10 +29,8 @@ class LayoutGroupComponent extends Component { /** * Create a new LayoutGroupComponent instance. * - * @param {import('./system.js').LayoutGroupComponentSystem} system - The ComponentSystem that - * created this Component. - * @param {import('../../entity.js').Entity} entity - The Entity that this Component is - * attached to. + * @param {LayoutGroupComponentSystem} system - The ComponentSystem that created this Component. + * @param {Entity} entity - The Entity that this Component is attached to. */ constructor(system, entity) { super(system, entity); diff --git a/src/framework/components/layout-group/system.js b/src/framework/components/layout-group/system.js index 29cd8e63c9f..1ae29509a6f 100644 --- a/src/framework/components/layout-group/system.js +++ b/src/framework/components/layout-group/system.js @@ -1,12 +1,14 @@ import { Vec2 } from '../../../core/math/vec2.js'; import { Vec4 } from '../../../core/math/vec4.js'; - import { Component } from '../component.js'; import { ComponentSystem } from '../system.js'; - import { LayoutGroupComponent } from './component.js'; import { LayoutGroupComponentData } from './data.js'; +/** + * @import { AppBase } from '../../app-base.js' + */ + const _schema = ['enabled']; const MAX_ITERATIONS = 100; @@ -20,7 +22,7 @@ class LayoutGroupComponentSystem extends ComponentSystem { /** * Create a new LayoutGroupComponentSystem instance. * - * @param {import('../../app-base.js').AppBase} app - The application. + * @param {AppBase} app - The application. * @ignore */ constructor(app) { diff --git a/src/framework/components/light/component.js b/src/framework/components/light/component.js index 99fbb6e9f16..4ac650475d0 100644 --- a/src/framework/components/light/component.js +++ b/src/framework/components/light/component.js @@ -1,14 +1,20 @@ import { math } from '../../../core/math/math.js'; import { Vec4 } from '../../../core/math/vec4.js'; - import { MASK_AFFECT_LIGHTMAPPED, MASK_AFFECT_DYNAMIC, MASK_BAKE } from '../../../scene/constants.js'; - import { Asset } from '../../asset/asset.js'; - import { Component } from '../component.js'; - import { properties } from './data.js'; +/** + * @import { Color } from '../../../core/math/color.js' + * @import { Entity } from '../../entity.js' + * @import { LightComponentData } from './data.js' + * @import { LightComponentSystem } from './system.js' + * @import { Light } from '../../../scene/light.js' + * @import { Texture } from '../../../platform/graphics/texture.js' + * @import { Vec2 } from '../../../core/math/vec2.js' + */ + /** * The Light Component enables the Entity to light the scene. There are three types of light: * directional, omni and spot. Directional lights are global in that they are considered to be @@ -39,10 +45,8 @@ class LightComponent extends Component { /** * Creates a new LightComponent instance. * - * @param {import('./system.js').LightComponentSystem} system - The ComponentSystem that - * created this Component. - * @param {import('../../entity.js').Entity} entity - The Entity that this Component is - * attached to. + * @param {LightComponentSystem} system - The ComponentSystem that created this Component. + * @param {Entity} entity - The Entity that this Component is attached to. */ constructor(system, entity) { super(system, entity); @@ -55,7 +59,7 @@ class LightComponent extends Component { // TODO: Remove this override in upgrading component /** - * @type {import('./data.js').LightComponentData} + * @type {LightComponentData} * @ignore */ get data() { @@ -84,7 +88,7 @@ class LightComponent extends Component { } /** - * @type {import('../../../scene/light.js').Light} + * @type {Light} * @ignore */ set light(arg) { @@ -92,7 +96,7 @@ class LightComponent extends Component { } /** - * @type {import('../../../scene/light.js').Light} + * @type {Light} * @ignore */ get light() { @@ -131,7 +135,7 @@ class LightComponent extends Component { * Sets the color of the light. The alpha component of the color is ignored. Defaults to white * (`[1, 1, 1]`). * - * @type {import('../../../core/math/color.js').Color}; + * @type {Color}; */ set color(arg) { this._setValue( @@ -147,7 +151,7 @@ class LightComponent extends Component { /** * Gets the color of the light. * - * @type {import('../../../core/math/color.js').Color}; + * @type {Color}; */ get color() { return this.data.color; @@ -681,7 +685,7 @@ class LightComponent extends Component { * Sets the texture to be used as the cookie for this light. Only spot and omni lights can have * cookies. Defaults to null. * - * @type {import('../../../platform/graphics/texture.js').Texture|null} + * @type {Texture|null} */ set cookie(arg) { this._setValue('cookie', arg, function (newValue, oldValue) { @@ -692,7 +696,7 @@ class LightComponent extends Component { /** * Gets the texture to be used as the cookie for this light. * - * @type {import('../../../platform/graphics/texture.js').Texture|null} + * @type {Texture|null} */ get cookie() { return this.data.cookie; @@ -797,7 +801,7 @@ class LightComponent extends Component { /** * Sets the spotlight cookie scale. * - * @type {import('../../../core/math/vec2.js').Vec2|null} + * @type {Vec2|null} */ set cookieScale(arg) { this._setValue( @@ -823,7 +827,7 @@ class LightComponent extends Component { /** * Gets the spotlight cookie scale. * - * @type {import('../../../core/math/vec2.js').Vec2|null} + * @type {Vec2|null} */ get cookieScale() { return this.data.cookieScale; @@ -832,7 +836,7 @@ class LightComponent extends Component { /** * Sets the spotlight cookie position offset. * - * @type {import('../../../core/math/vec2.js').Vec2|null} + * @type {Vec2|null} */ set cookieOffset(arg) { this._setValue( @@ -848,7 +852,7 @@ class LightComponent extends Component { /** * Gets the spotlight cookie position offset. * - * @type {import('../../../core/math/vec2.js').Vec2|null} + * @type {Vec2|null} */ get cookieOffset() { return this.data.cookieOffset; diff --git a/src/framework/components/light/data.js b/src/framework/components/light/data.js index e9527641b5e..17c4df8daf7 100644 --- a/src/framework/components/light/data.js +++ b/src/framework/components/light/data.js @@ -1,3 +1,4 @@ +import { Color } from '../../../core/math/color.js'; import { BLUR_GAUSSIAN, LAYERID_WORLD, @@ -7,12 +8,14 @@ import { SHADOWUPDATE_REALTIME } from '../../../scene/constants.js'; -import { Color } from '../../../core/math/color.js'; +/** + * @import { Light } from '../../../scene/light.js' + */ class LightComponentData { enabled = true; - /** @type {import('../../../scene/light.js').Light} */ + /** @type {Light} */ light; type = 'directional'; diff --git a/src/framework/components/light/system.js b/src/framework/components/light/system.js index d6a4aaf7590..c04f8c7d916 100644 --- a/src/framework/components/light/system.js +++ b/src/framework/components/light/system.js @@ -1,14 +1,15 @@ import { Color } from '../../../core/math/color.js'; import { Vec2 } from '../../../core/math/vec2.js'; - import { LIGHTSHAPE_PUNCTUAL } from '../../../scene/constants.js'; import { Light, lightTypes } from '../../../scene/light.js'; - import { ComponentSystem } from '../system.js'; - import { LightComponent } from './component.js'; import { properties, LightComponentData } from './data.js'; +/** + * @import { AppBase } from '../../app-base.js' + */ + /** * A Light Component is used to dynamically light the scene. * @@ -18,7 +19,7 @@ class LightComponentSystem extends ComponentSystem { /** * Create a new LightComponentSystem instance. * - * @param {import('../../app-base.js').AppBase} app - The application. + * @param {AppBase} app - The application. * @ignore */ constructor(app) { diff --git a/src/framework/components/model/component.js b/src/framework/components/model/component.js index c455734f79e..4c25e56d176 100644 --- a/src/framework/components/model/component.js +++ b/src/framework/components/model/component.js @@ -1,17 +1,22 @@ import { Debug } from '../../../core/debug.js'; -import { - LAYERID_WORLD -} from '../../../scene/constants.js'; +import { LAYERID_WORLD } from '../../../scene/constants.js'; import { BatchGroup } from '../../../scene/batching/batch-group.js'; import { GraphNode } from '../../../scene/graph-node.js'; import { MeshInstance } from '../../../scene/mesh-instance.js'; import { Model } from '../../../scene/model.js'; import { getShapePrimitive } from '../../graphics/primitive-cache.js'; - import { Asset } from '../../asset/asset.js'; - import { Component } from '../component.js'; +/** + * @import { BoundingBox } from '../../../core/shape/bounding-box.js' + * @import { Entity } from '../../entity.js' + * @import { LayerComposition } from '../../../scene/composition/layer-composition.js' + * @import { Layer } from '../../../scene/layer.js' + * @import { Material } from '../../../scene/materials/material.js' + * @import { ModelComponentSystem } from './system.js' + */ + /** * Enables an Entity to render a model or a primitive shape. This Component attaches additional * model geometry in to the scene graph below the Entity. @@ -62,7 +67,7 @@ class ModelComponent extends Component { _materialAsset = null; /** - * @type {import('../../../scene/materials/material.js').Material} + * @type {Material} * @private */ _material; @@ -105,7 +110,7 @@ class ModelComponent extends Component { _batchGroupId = -1; /** - * @type {import('../../../core/shape/bounding-box.js').BoundingBox|null} + * @type {BoundingBox|null} * @private */ _customAabb = null; @@ -127,10 +132,8 @@ class ModelComponent extends Component { /** * Create a new ModelComponent instance. * - * @param {import('./system.js').ModelComponentSystem} system - The ComponentSystem that - * created this Component. - * @param {import('../../entity.js').Entity} entity - The Entity that this Component is - * attached to. + * @param {ModelComponentSystem} system - The ComponentSystem that created this Component. + * @param {Entity} entity - The Entity that this Component is attached to. */ constructor(system, entity) { super(system, entity); @@ -174,7 +177,7 @@ class ModelComponent extends Component { * for skinned characters in order to avoid per frame bounding box computations based on bone * positions. * - * @type {import('../../../core/shape/bounding-box.js').BoundingBox|null} + * @type {BoundingBox|null} */ set customAabb(value) { this._customAabb = value; @@ -194,7 +197,7 @@ class ModelComponent extends Component { * Gets the custom object space bounding box that is used for visibility culling of attached * mesh instances. * - * @type {import('../../../core/shape/bounding-box.js').BoundingBox|null} + * @type {BoundingBox|null} */ get customAabb() { return this._customAabb; @@ -652,7 +655,7 @@ class ModelComponent extends Component { * Sets the {@link Material} that will be used to render the model. The material is ignored for * renders of type 'asset'. * - * @type {import('../../../scene/materials/material.js').Material} + * @type {Material} */ set material(value) { if (this._material === value) @@ -666,7 +669,7 @@ class ModelComponent extends Component { /** * Gets the {@link Material} that will be used to render the model. * - * @type {import('../../../scene/materials/material.js').Material} + * @type {Material} */ get material() { return this._material; @@ -774,10 +777,8 @@ class ModelComponent extends Component { } /** - * @param {import('../../../scene/composition/layer-composition.js').LayerComposition} oldComp - The - * old layer composition. - * @param {import('../../../scene/composition/layer-composition.js').LayerComposition} newComp - The - * new layer composition. + * @param {LayerComposition} oldComp - The old layer composition. + * @param {LayerComposition} newComp - The new layer composition. * @private */ onLayersChanged(oldComp, newComp) { @@ -789,7 +790,7 @@ class ModelComponent extends Component { } /** - * @param {import('../../../scene/layer.js').Layer} layer - The layer that was added. + * @param {Layer} layer - The layer that was added. * @private */ onLayerAdded(layer) { @@ -799,7 +800,7 @@ class ModelComponent extends Component { } /** - * @param {import('../../../scene/layer.js').Layer} layer - The layer that was removed. + * @param {Layer} layer - The layer that was removed. * @private */ onLayerRemoved(layer) { @@ -1185,8 +1186,7 @@ class ModelComponent extends Component { } /** - * @param {import('../../../scene/materials/material.js').Material} material - The material to - * be set. + * @param {Material} material - The material to be set. * @private */ _setMaterial(material) { diff --git a/src/framework/components/model/system.js b/src/framework/components/model/system.js index bc4c047afc6..419170b10dd 100644 --- a/src/framework/components/model/system.js +++ b/src/framework/components/model/system.js @@ -1,19 +1,17 @@ import { extend } from '../../../core/core.js'; - import { Vec3 } from '../../../core/math/vec3.js'; - import { BoundingBox } from '../../../core/shape/bounding-box.js'; - import { getDefaultMaterial } from '../../../scene/materials/default-material.js'; - import { Asset } from '../../asset/asset.js'; - import { Component } from '../component.js'; import { ComponentSystem } from '../system.js'; - import { ModelComponent } from './component.js'; import { ModelComponentData } from './data.js'; +/** + * @import { AppBase } from '../../app-base.js' + */ + const _schema = ['enabled']; /** @@ -26,7 +24,7 @@ class ModelComponentSystem extends ComponentSystem { /** * Create a new ModelComponentSystem instance. * - * @param {import('../../app-base.js').AppBase} app - The Application. + * @param {AppBase} app - The Application. * @ignore */ constructor(app) { diff --git a/src/framework/components/particle-system/component.js b/src/framework/components/particle-system/component.js index 3a83a537440..20335c2777e 100644 --- a/src/framework/components/particle-system/component.js +++ b/src/framework/components/particle-system/component.js @@ -1,11 +1,19 @@ import { LAYERID_DEPTH } from '../../../scene/constants.js'; import { Mesh } from '../../../scene/mesh.js'; import { ParticleEmitter } from '../../../scene/particle-system/particle-emitter.js'; - import { Asset } from '../../asset/asset.js'; - import { Component } from '../component.js'; +/** + * @import { CurveSet } from '../../../core/math/curve-set.js' + * @import { Curve } from '../../../core/math/curve.js' + * @import { Entity } from '../../entity.js' + * @import { ParticleSystemComponentData } from './data.js' + * @import { ParticleSystemComponentSystem } from './system.js' + * @import { Texture } from '../../../platform/graphics/texture.js' + * @import { Vec3 } from '../../../core/math/vec3.js' + */ + // properties that do not need rebuilding the particle system const SIMPLE_PROPERTIES = [ 'emitterExtents', @@ -107,9 +115,8 @@ class ParticleSystemComponent extends Component { /** * Create a new ParticleSystemComponent. * - * @param {import('./system.js').ParticleSystemComponentSystem} system - The ComponentSystem - * that created this Component. - * @param {import('../../entity.js').Entity} entity - The Entity this Component is attached to. + * @param {ParticleSystemComponentSystem} system - The ComponentSystem that created this Component. + * @param {Entity} entity - The Entity this Component is attached to. */ constructor(system, entity) { super(system, entity); @@ -139,7 +146,7 @@ class ParticleSystemComponent extends Component { // TODO: Remove this override in upgrading component /** - * @type {import('./data.js').ParticleSystemComponentData} + * @type {ParticleSystemComponentData} * @ignore */ get data() { @@ -573,7 +580,7 @@ class ParticleSystemComponent extends Component { * Sets the extents of a local space bounding box within which particles are spawned at random * positions. This only applies to particle system with the shape `EMITTERSHAPE_BOX`. * - * @type {import('../../../core/math/vec3.js').Vec3} + * @type {Vec3} */ set emitterExtents(arg) { this._setValue('emitterExtents', arg); @@ -583,7 +590,7 @@ class ParticleSystemComponent extends Component { * Gets the extents of a local space bounding box within which particles are spawned at random * positions. * - * @type {import('../../../core/math/vec3.js').Vec3} + * @type {Vec3} */ get emitterExtents() { return this.data.emitterExtents; @@ -594,7 +601,7 @@ class ParticleSystemComponent extends Component { * spawned. It is aligned to the center of emitterExtents. This only applies to particle system * with the shape `EMITTERSHAPE_BOX`. * - * @type {import('../../../core/math/vec3.js').Vec3} + * @type {Vec3} */ set emitterExtentsInner(arg) { this._setValue('emitterExtentsInner', arg); @@ -604,7 +611,7 @@ class ParticleSystemComponent extends Component { * Gets the exception of extents of a local space bounding box within which particles are not * spawned. * - * @type {import('../../../core/math/vec3.js').Vec3} + * @type {Vec3} */ get emitterExtentsInner() { return this.data.emitterExtentsInner; @@ -689,7 +696,7 @@ class ParticleSystemComponent extends Component { * volume centered on the owner entity's position. If a particle crosses the boundary of one * side of the volume, it teleports to the opposite side. * - * @type {import('../../../core/math/vec3.js').Vec3} + * @type {Vec3} */ set wrapBounds(arg) { this._setValue('wrapBounds', arg); @@ -698,7 +705,7 @@ class ParticleSystemComponent extends Component { /** * Gets the wrap bounds of the particle system. * - * @type {import('../../../core/math/vec3.js').Vec3} + * @type {Vec3} */ get wrapBounds() { return this.data.wrapBounds; @@ -863,7 +870,7 @@ class ParticleSystemComponent extends Component { * Sets the particle normal. This only applies to particle system with the orientation modes * `PARTICLEORIENTATION_WORLD` and `PARTICLEORIENTATION_EMITTER`. * - * @type {import('../../../core/math/vec3.js').Vec3} + * @type {Vec3} */ set particleNormal(arg) { this._setValue('particleNormal', arg); @@ -872,7 +879,7 @@ class ParticleSystemComponent extends Component { /** * Gets the particle normal. * - * @type {import('../../../core/math/vec3.js').Vec3} + * @type {Vec3} */ get particleNormal() { return this.data.particleNormal; @@ -881,7 +888,7 @@ class ParticleSystemComponent extends Component { /** * Sets the local space velocity graph. * - * @type {import('../../../core/math/curve-set.js').CurveSet} + * @type {CurveSet} */ set localVelocityGraph(arg) { this._setValue('localVelocityGraph', arg); @@ -890,7 +897,7 @@ class ParticleSystemComponent extends Component { /** * Gets the local space velocity graph. * - * @type {import('../../../core/math/curve-set.js').CurveSet} + * @type {CurveSet} */ get localVelocityGraph() { return this.data.localVelocityGraph; @@ -900,7 +907,7 @@ class ParticleSystemComponent extends Component { * Sets the second velocity graph. If not null, particles pick random values between * localVelocityGraph and localVelocityGraph2. * - * @type {import('../../../core/math/curve-set.js').CurveSet} + * @type {CurveSet} */ set localVelocityGraph2(arg) { this._setValue('localVelocityGraph2', arg); @@ -909,7 +916,7 @@ class ParticleSystemComponent extends Component { /** * Gets the second velocity graph. * - * @type {import('../../../core/math/curve-set.js').CurveSet} + * @type {CurveSet} */ get localVelocityGraph2() { return this.data.localVelocityGraph2; @@ -918,7 +925,7 @@ class ParticleSystemComponent extends Component { /** * Sets the world space velocity graph. * - * @type {import('../../../core/math/curve-set.js').CurveSet} + * @type {CurveSet} */ set velocityGraph(arg) { this._setValue('velocityGraph', arg); @@ -927,7 +934,7 @@ class ParticleSystemComponent extends Component { /** * Gets the world space velocity graph. * - * @type {import('../../../core/math/curve-set.js').CurveSet} + * @type {CurveSet} */ get velocityGraph() { return this.data.velocityGraph; @@ -937,7 +944,7 @@ class ParticleSystemComponent extends Component { * Sets the second world space velocity graph. If not null, particles pick random values * between velocityGraph and velocityGraph2. * - * @type {import('../../../core/math/curve-set.js').CurveSet} + * @type {CurveSet} */ set velocityGraph2(arg) { this._setValue('velocityGraph2', arg); @@ -946,7 +953,7 @@ class ParticleSystemComponent extends Component { /** * Gets the second world space velocity graph. * - * @type {import('../../../core/math/curve-set.js').CurveSet} + * @type {CurveSet} */ get velocityGraph2() { return this.data.velocityGraph2; @@ -955,7 +962,7 @@ class ParticleSystemComponent extends Component { /** * Sets the rotation speed graph. * - * @type {import('../../../core/math/curve.js').Curve} + * @type {Curve} */ set rotationSpeedGraph(arg) { this._setValue('rotationSpeedGraph', arg); @@ -964,7 +971,7 @@ class ParticleSystemComponent extends Component { /** * Gets the rotation speed graph. * - * @type {import('../../../core/math/curve.js').Curve} + * @type {Curve} */ get rotationSpeedGraph() { return this.data.rotationSpeedGraph; @@ -974,7 +981,7 @@ class ParticleSystemComponent extends Component { * Sets the second rotation speed graph. If not null, particles pick random values between * rotationSpeedGraph and rotationSpeedGraph2. * - * @type {import('../../../core/math/curve.js').Curve} + * @type {Curve} */ set rotationSpeedGraph2(arg) { this._setValue('rotationSpeedGraph2', arg); @@ -983,7 +990,7 @@ class ParticleSystemComponent extends Component { /** * Gets the second rotation speed graph. * - * @type {import('../../../core/math/curve.js').Curve} + * @type {Curve} */ get rotationSpeedGraph2() { return this.data.rotationSpeedGraph2; @@ -992,7 +999,7 @@ class ParticleSystemComponent extends Component { /** * Sets the radial speed graph. Velocity vector points from emitter origin to particle position. * - * @type {import('../../../core/math/curve.js').Curve} + * @type {Curve} */ set radialSpeedGraph(arg) { this._setValue('radialSpeedGraph', arg); @@ -1001,7 +1008,7 @@ class ParticleSystemComponent extends Component { /** * Gets the radial speed graph. * - * @type {import('../../../core/math/curve.js').Curve} + * @type {Curve} */ get radialSpeedGraph() { return this.data.radialSpeedGraph; @@ -1012,7 +1019,7 @@ class ParticleSystemComponent extends Component { * radialSpeedGraph and radialSpeedGraph2. Velocity vector points from emitter origin to * particle position. * - * @type {import('../../../core/math/curve.js').Curve} + * @type {Curve} */ set radialSpeedGraph2(arg) { this._setValue('radialSpeedGraph2', arg); @@ -1021,7 +1028,7 @@ class ParticleSystemComponent extends Component { /** * Gets the second radial speed graph. * - * @type {import('../../../core/math/curve.js').Curve} + * @type {Curve} */ get radialSpeedGraph2() { return this.data.radialSpeedGraph2; @@ -1030,7 +1037,7 @@ class ParticleSystemComponent extends Component { /** * Sets the scale graph. * - * @type {import('../../../core/math/curve.js').Curve} + * @type {Curve} */ set scaleGraph(arg) { this._setValue('scaleGraph', arg); @@ -1039,7 +1046,7 @@ class ParticleSystemComponent extends Component { /** * Gets the scale graph. * - * @type {import('../../../core/math/curve.js').Curve} + * @type {Curve} */ get scaleGraph() { return this.data.scaleGraph; @@ -1049,7 +1056,7 @@ class ParticleSystemComponent extends Component { * Sets the second scale graph. If not null, particles pick random values between `scaleGraph` * and `scaleGraph2`. * - * @type {import('../../../core/math/curve.js').Curve} + * @type {Curve} */ set scaleGraph2(arg) { this._setValue('scaleGraph2', arg); @@ -1058,7 +1065,7 @@ class ParticleSystemComponent extends Component { /** * Gets the second scale graph. * - * @type {import('../../../core/math/curve.js').Curve} + * @type {Curve} */ get scaleGraph2() { return this.data.scaleGraph2; @@ -1067,7 +1074,7 @@ class ParticleSystemComponent extends Component { /** * Sets the color graph. * - * @type {import('../../../core/math/curve-set.js').CurveSet} + * @type {CurveSet} */ set colorGraph(arg) { this._setValue('colorGraph', arg); @@ -1076,7 +1083,7 @@ class ParticleSystemComponent extends Component { /** * Gets the color graph. * - * @type {import('../../../core/math/curve-set.js').CurveSet} + * @type {CurveSet} */ get colorGraph() { return this.data.colorGraph; @@ -1086,7 +1093,7 @@ class ParticleSystemComponent extends Component { * Sets the second color graph. If not null, particles pick random values between `colorGraph` * and `colorGraph2`. * - * @type {import('../../../core/math/curve-set.js').CurveSet} + * @type {CurveSet} */ set colorGraph2(arg) { this._setValue('colorGraph2', arg); @@ -1095,7 +1102,7 @@ class ParticleSystemComponent extends Component { /** * Gets the second color graph. * - * @type {import('../../../core/math/curve-set.js').CurveSet} + * @type {CurveSet} */ get colorGraph2() { return this.data.colorGraph2; @@ -1104,7 +1111,7 @@ class ParticleSystemComponent extends Component { /** * Sets the alpha graph. * - * @type {import('../../../core/math/curve.js').Curve} + * @type {Curve} */ set alphaGraph(arg) { this._setValue('alphaGraph', arg); @@ -1113,7 +1120,7 @@ class ParticleSystemComponent extends Component { /** * Gets the alpha graph. * - * @type {import('../../../core/math/curve.js').Curve} + * @type {Curve} */ get alphaGraph() { return this.data.alphaGraph; @@ -1123,7 +1130,7 @@ class ParticleSystemComponent extends Component { * Sets the second alpha graph. If not null, particles pick random values between `alphaGraph` * and `alphaGraph2`. * - * @type {import('../../../core/math/curve.js').Curve} + * @type {Curve} */ set alphaGraph2(arg) { this._setValue('alphaGraph2', arg); @@ -1132,7 +1139,7 @@ class ParticleSystemComponent extends Component { /** * Gets the second alpha graph. * - * @type {import('../../../core/math/curve.js').Curve} + * @type {Curve} */ get alphaGraph2() { return this.data.alphaGraph2; @@ -1142,7 +1149,7 @@ class ParticleSystemComponent extends Component { * Sets the color map texture to apply to all particles in the system. If no texture is * assigned, a default spot texture is used. * - * @type {import('../../../platform/graphics/texture.js').Texture} + * @type {Texture} */ set colorMap(arg) { this._setValue('colorMap', arg); @@ -1151,7 +1158,7 @@ class ParticleSystemComponent extends Component { /** * Gets the color map texture to apply to all particles in the system. * - * @type {import('../../../platform/graphics/texture.js').Texture} + * @type {Texture} */ get colorMap() { return this.data.colorMap; @@ -1161,7 +1168,7 @@ class ParticleSystemComponent extends Component { * Sets the normal map texture to apply to all particles in the system. If no texture is * assigned, an approximate spherical normal is calculated for each vertex. * - * @type {import('../../../platform/graphics/texture.js').Texture} + * @type {Texture} */ set normalMap(arg) { this._setValue('normalMap', arg); @@ -1170,7 +1177,7 @@ class ParticleSystemComponent extends Component { /** * Gets the normal map texture to apply to all particles in the system. * - * @type {import('../../../platform/graphics/texture.js').Texture} + * @type {Texture} */ get normalMap() { return this.data.normalMap; diff --git a/src/framework/components/particle-system/data.js b/src/framework/components/particle-system/data.js index 65339c63aad..e495f79239c 100644 --- a/src/framework/components/particle-system/data.js +++ b/src/framework/components/particle-system/data.js @@ -1,7 +1,14 @@ import { Vec3 } from '../../../core/math/vec3.js'; - import { BLEND_NORMAL, EMITTERSHAPE_BOX, LAYERID_WORLD, PARTICLEMODE_GPU, PARTICLEORIENTATION_SCREEN } from '../../../scene/constants.js'; +/** + * @import { Asset } from '../../../framework/asset/asset.js' + * @import { CurveSet } from '../../../core/math/curve-set.js' + * @import { Curve } from '../../../core/math/curve.js' + * @import { Mesh } from '../../../scene/mesh.js' + * @import { Texture } from '../../../platform/graphics/texture.js' + */ + class ParticleSystemComponentData { constructor() { this.numParticles = 1; // Amount of particles allocated (max particles = max GL texture width at this moment) @@ -22,13 +29,13 @@ class ParticleSystemComponentData { this.wrapBounds = new Vec3(); this.localSpace = false; this.screenSpace = false; - /** @type {import('../../../platform/graphics/texture.js').Texture} */ + /** @type {Texture} */ this.colorMap = null; - /** @type {import('../../../framework/asset/asset.js').Asset} */ + /** @type {Asset} */ this.colorMapAsset = null; - /** @type {import('../../../platform/graphics/texture.js').Texture} */ + /** @type {Texture} */ this.normalMap = null; - /** @type {import('../../../framework/asset/asset.js').Asset} */ + /** @type {Asset} */ this.normalMapAsset = null; this.loop = true; this.preWarm = false; @@ -41,11 +48,11 @@ class ParticleSystemComponentData { this.stretch = 0.0; this.alignToMotion = false; this.depthSoftening = 0; - /** @type {import('../../../framework/asset/asset.js').Asset} */ + /** @type {Asset} */ this.renderAsset = null; - /** @type {import('../../../framework/asset/asset.js').Asset} */ + /** @type {Asset} */ this.meshAsset = null; - /** @type {import('../../../scene/mesh.js').Mesh} */ + /** @type {Mesh} */ this.mesh = null; // Mesh to be used as particle. Vertex buffer is supposed to hold vertex position in first 3 floats of each vertex // Leave undefined to use simple quads this.depthWrite = false; @@ -65,39 +72,39 @@ class ParticleSystemComponentData { this.animLoop = true; // Time-dependent parameters - /** @type {import('../../../core/math/curve.js').Curve} */ + /** @type {Curve} */ this.scaleGraph = null; - /** @type {import('../../../core/math/curve.js').Curve} */ + /** @type {Curve} */ this.scaleGraph2 = null; - /** @type {import('../../../core/math/curve-set.js').CurveSet} */ + /** @type {CurveSet} */ this.colorGraph = null; - /** @type {import('../../../core/math/curve-set.js').CurveSet} */ + /** @type {CurveSet} */ this.colorGraph2 = null; - /** @type {import('../../../core/math/curve.js').Curve} */ + /** @type {Curve} */ this.alphaGraph = null; - /** @type {import('../../../core/math/curve.js').Curve} */ + /** @type {Curve} */ this.alphaGraph2 = null; - /** @type {import('../../../core/math/curve-set.js').CurveSet} */ + /** @type {CurveSet} */ this.localVelocityGraph = null; - /** @type {import('../../../core/math/curve-set.js').CurveSet} */ + /** @type {CurveSet} */ this.localVelocityGraph2 = null; - /** @type {import('../../../core/math/curve-set.js').CurveSet} */ + /** @type {CurveSet} */ this.velocityGraph = null; - /** @type {import('../../../core/math/curve-set.js').CurveSet} */ + /** @type {CurveSet} */ this.velocityGraph2 = null; - /** @type {import('../../../core/math/curve.js').Curve} */ + /** @type {Curve} */ this.rotationSpeedGraph = null; - /** @type {import('../../../core/math/curve.js').Curve} */ + /** @type {Curve} */ this.rotationSpeedGraph2 = null; - /** @type {import('../../../core/math/curve.js').Curve} */ + /** @type {Curve} */ this.radialSpeedGraph = null; - /** @type {import('../../../core/math/curve.js').Curve} */ + /** @type {Curve} */ this.radialSpeedGraph2 = null; this.blendType = BLEND_NORMAL; diff --git a/src/framework/components/particle-system/system.js b/src/framework/components/particle-system/system.js index 7faadd8cc50..1a819785be1 100644 --- a/src/framework/components/particle-system/system.js +++ b/src/framework/components/particle-system/system.js @@ -1,14 +1,15 @@ import { Curve } from '../../../core/math/curve.js'; import { CurveSet } from '../../../core/math/curve-set.js'; import { Vec3 } from '../../../core/math/vec3.js'; - import { Asset } from '../../asset/asset.js'; - import { ComponentSystem } from '../system.js'; - import { ParticleSystemComponent } from './component.js'; import { ParticleSystemComponentData } from './data.js'; +/** + * @import { AppBase } from '../../app-base.js' + */ + const _schema = [ 'enabled', 'autoPlay', @@ -84,7 +85,7 @@ class ParticleSystemComponentSystem extends ComponentSystem { /** * Create a new ParticleSystemComponentSystem. * - * @param {import('../../app-base.js').AppBase} app - The Application. + * @param {AppBase} app - The Application. * @ignore */ constructor(app) { diff --git a/src/framework/components/registry.js b/src/framework/components/registry.js index 64be81a7d2c..e3c6a0f0b19 100644 --- a/src/framework/components/registry.js +++ b/src/framework/components/registry.js @@ -1,5 +1,30 @@ import { EventHandler } from '../../core/event-handler.js'; +/** + * @import { AnimComponentSystem } from './anim/system.js' + * @import { AnimationComponentSystem } from './animation/system.js' + * @import { AudioListenerComponentSystem } from './audio-listener/system.js' + * @import { ButtonComponentSystem } from './button/system.js' + * @import { CameraComponentSystem } from './camera/system.js' + * @import { CollisionComponentSystem } from './collision/system.js' + * @import { ElementComponentSystem } from './element/system.js' + * @import { JointComponentSystem } from './joint/system.js' + * @import { LayoutChildComponentSystem } from './layout-child/system.js' + * @import { LayoutGroupComponentSystem } from './layout-group/system.js' + * @import { LightComponentSystem } from './light/system.js' + * @import { ModelComponentSystem } from './model/system.js' + * @import { ParticleSystemComponentSystem } from './particle-system/system.js' + * @import { RenderComponentSystem } from './render/system.js' + * @import { RigidBodyComponentSystem } from './rigid-body/system.js' + * @import { ScreenComponentSystem } from './screen/system.js' + * @import { ScriptComponentSystem } from './script/system.js' + * @import { ScrollViewComponentSystem } from './scroll-view/system.js' + * @import { ScrollbarComponentSystem } from './scrollbar/system.js' + * @import { SoundComponentSystem } from './sound/system.js' + * @import { SpriteComponentSystem } from './sprite/system.js' + * @import { ZoneComponentSystem } from './zone/system.js' + */ + /** * Store, access and delete instances of the various ComponentSystems. */ @@ -7,7 +32,7 @@ class ComponentSystemRegistry extends EventHandler { /** * Gets the {@link AnimComponentSystem} from the registry. * - * @type {import('./anim/system.js').AnimComponentSystem|undefined} + * @type {AnimComponentSystem|undefined} * @readonly */ anim; @@ -15,7 +40,7 @@ class ComponentSystemRegistry extends EventHandler { /** * Gets the {@link AnimationComponentSystem} from the registry. * - * @type {import('./animation/system.js').AnimationComponentSystem|undefined} + * @type {AnimationComponentSystem|undefined} * @readonly */ animation; @@ -23,7 +48,7 @@ class ComponentSystemRegistry extends EventHandler { /** * Gets the {@link AudioListenerComponentSystem} from the registry. * - * @type {import('./audio-listener/system.js').AudioListenerComponentSystem|undefined} + * @type {AudioListenerComponentSystem|undefined} * @readonly */ audiolistener; @@ -31,7 +56,7 @@ class ComponentSystemRegistry extends EventHandler { /** * Gets the {@link ButtonComponentSystem} from the registry. * - * @type {import('./button/system.js').ButtonComponentSystem|undefined} + * @type {ButtonComponentSystem|undefined} * @readonly */ button; @@ -39,7 +64,7 @@ class ComponentSystemRegistry extends EventHandler { /** * Gets the {@link CameraComponentSystem} from the registry. * - * @type {import('./camera/system.js').CameraComponentSystem|undefined} + * @type {CameraComponentSystem|undefined} * @readonly */ camera; @@ -47,7 +72,7 @@ class ComponentSystemRegistry extends EventHandler { /** * Gets the {@link CollisionComponentSystem} from the registry. * - * @type {import('./collision/system.js').CollisionComponentSystem|undefined} + * @type {CollisionComponentSystem|undefined} * @readonly */ collision; @@ -55,7 +80,7 @@ class ComponentSystemRegistry extends EventHandler { /** * Gets the {@link ElementComponentSystem} from the registry. * - * @type {import('./element/system.js').ElementComponentSystem|undefined} + * @type {ElementComponentSystem|undefined} * @readonly */ element; @@ -63,7 +88,7 @@ class ComponentSystemRegistry extends EventHandler { /** * Gets the {@link JointComponentSystem} from the registry. * - * @type {import('./joint/system.js').JointComponentSystem|undefined} + * @type {JointComponentSystem|undefined} * @readonly * @ignore */ @@ -72,7 +97,7 @@ class ComponentSystemRegistry extends EventHandler { /** * Gets the {@link LayoutChildComponentSystem} from the registry. * - * @type {import('./layout-child/system.js').LayoutChildComponentSystem|undefined} + * @type {LayoutChildComponentSystem|undefined} * @readonly */ layoutchild; @@ -80,7 +105,7 @@ class ComponentSystemRegistry extends EventHandler { /** * Gets the {@link LayoutGroupComponentSystem} from the registry. * - * @type {import('./layout-group/system.js').LayoutGroupComponentSystem|undefined} + * @type {LayoutGroupComponentSystem|undefined} * @readonly */ layoutgroup; @@ -88,7 +113,7 @@ class ComponentSystemRegistry extends EventHandler { /** * Gets the {@link LightComponentSystem} from the registry. * - * @type {import('./light/system.js').LightComponentSystem|undefined} + * @type {LightComponentSystem|undefined} * @readonly */ light; @@ -96,7 +121,7 @@ class ComponentSystemRegistry extends EventHandler { /** * Gets the {@link ModelComponentSystem} from the registry. * - * @type {import('./model/system.js').ModelComponentSystem|undefined} + * @type {ModelComponentSystem|undefined} * @readonly */ model; @@ -104,7 +129,7 @@ class ComponentSystemRegistry extends EventHandler { /** * Gets the {@link ParticleSystemComponentSystem} from the registry. * - * @type {import('./particle-system/system.js').ParticleSystemComponentSystem|undefined} + * @type {ParticleSystemComponentSystem|undefined} * @readonly */ particlesystem; @@ -112,7 +137,7 @@ class ComponentSystemRegistry extends EventHandler { /** * Gets the {@link RenderComponentSystem} from the registry. * - * @type {import('./render/system.js').RenderComponentSystem|undefined} + * @type {RenderComponentSystem|undefined} * @readonly */ render; @@ -120,7 +145,7 @@ class ComponentSystemRegistry extends EventHandler { /** * Gets the {@link RigidBodyComponentSystem} from the registry. * - * @type {import('./rigid-body/system.js').RigidBodyComponentSystem|undefined} + * @type {RigidBodyComponentSystem|undefined} * @readonly */ rigidbody; @@ -128,7 +153,7 @@ class ComponentSystemRegistry extends EventHandler { /** * Gets the {@link ScreenComponentSystem} from the registry. * - * @type {import('./screen/system.js').ScreenComponentSystem|undefined} + * @type {ScreenComponentSystem|undefined} * @readonly */ screen; @@ -136,7 +161,7 @@ class ComponentSystemRegistry extends EventHandler { /** * Gets the {@link ScriptComponentSystem} from the registry. * - * @type {import('./script/system.js').ScriptComponentSystem|undefined} + * @type {ScriptComponentSystem|undefined} * @readonly */ script; @@ -144,7 +169,7 @@ class ComponentSystemRegistry extends EventHandler { /** * Gets the {@link ScrollbarComponentSystem} from the registry. * - * @type {import('./scrollbar/system.js').ScrollbarComponentSystem|undefined} + * @type {ScrollbarComponentSystem|undefined} * @readonly */ scrollbar; @@ -152,7 +177,7 @@ class ComponentSystemRegistry extends EventHandler { /** * Gets the {@link ScrollViewComponentSystem} from the registry. * - * @type {import('./scroll-view/system.js').ScrollViewComponentSystem|undefined} + * @type {ScrollViewComponentSystem|undefined} * @readonly */ scrollview; @@ -160,7 +185,7 @@ class ComponentSystemRegistry extends EventHandler { /** * Gets the {@link SoundComponentSystem} from the registry. * - * @type {import('./sound/system.js').SoundComponentSystem|undefined} + * @type {SoundComponentSystem|undefined} * @readonly */ sound; @@ -168,7 +193,7 @@ class ComponentSystemRegistry extends EventHandler { /** * Gets the {@link SpriteComponentSystem} from the registry. * - * @type {import('./sprite/system.js').SpriteComponentSystem|undefined} + * @type {SpriteComponentSystem|undefined} * @readonly */ sprite; @@ -176,7 +201,7 @@ class ComponentSystemRegistry extends EventHandler { /** * Gets the {@link ZoneComponentSystem} from the registry. * - * @type {import('./zone/system.js').ZoneComponentSystem|undefined} + * @type {ZoneComponentSystem|undefined} * @readonly * @ignore */ diff --git a/src/framework/components/render/component.js b/src/framework/components/render/component.js index f20c87c51b0..f4eaf3a60f6 100644 --- a/src/framework/components/render/component.js +++ b/src/framework/components/render/component.js @@ -6,14 +6,18 @@ import { MorphInstance } from '../../../scene/morph-instance.js'; import { getShapePrimitive } from '../../graphics/primitive-cache.js'; import { GraphNode } from '../../../scene/graph-node.js'; import { SkinInstanceCache } from '../../../scene/skin-instance-cache.js'; - import { Asset } from '../../asset/asset.js'; import { AssetReference } from '../../asset/asset-reference.js'; - import { Component } from '../component.js'; - import { EntityReference } from '../../utils/entity-reference.js'; +/** + * @import { BoundingBox } from '../../../core/shape/bounding-box.js' + * @import { Entity } from '../../entity.js' + * @import { Material } from '../../../scene/materials/material.js' + * @import { RenderComponentSystem } from './system.js' + */ + /** * The RenderComponent enables an {@link Entity} to render 3D meshes. The {@link RenderComponent#type} * property can be set to one of several predefined shape types (such as `box`, `sphere`, `cone` @@ -54,8 +58,8 @@ import { EntityReference } from '../../utils/entity-reference.js'; * - [Primitive Shapes](https://playcanvas.github.io/#/graphics/shapes) * - [Loading Render Assets](https://playcanvas.github.io/#/graphics/render-asset) * - * @property {import('../../entity.js').Entity} rootBone A reference to the entity to be used as - * the root bone for any skinned meshes that are rendered by this component. + * @property {Entity} rootBone A reference to the entity to be used as the root bone for any + * skinned meshes that are rendered by this component. * * @category Graphics */ @@ -101,7 +105,7 @@ class RenderComponent extends Component { _meshInstances = []; /** - * @type {import('../../../core/shape/bounding-box.js').BoundingBox|null} + * @type {BoundingBox|null} * @private */ _customAabb = null; @@ -130,7 +134,7 @@ class RenderComponent extends Component { * Material used to render meshes other than asset type. It gets priority when set to * something else than defaultMaterial, otherwise materialASsets[0] is used. * - * @type {import('../../../scene/materials/material.js').Material} + * @type {Material} * @private */ _material; @@ -144,10 +148,8 @@ class RenderComponent extends Component { /** * Create a new RenderComponent. * - * @param {import('./system.js').RenderComponentSystem} system - The ComponentSystem that - * created this Component. - * @param {import('../../entity.js').Entity} entity - The Entity that this Component is - * attached to. + * @param {RenderComponentSystem} system - The ComponentSystem that created this Component. + * @param {Entity} entity - The Entity that this Component is attached to. */ constructor(system, entity) { super(system, entity); @@ -212,7 +214,7 @@ class RenderComponent extends Component { * for skinned characters in order to avoid per frame bounding box computations based on bone * positions. * - * @type {import('../../../core/shape/bounding-box.js').BoundingBox|null} + * @type {BoundingBox|null} */ set customAabb(value) { this._customAabb = value; @@ -230,7 +232,7 @@ class RenderComponent extends Component { * Gets the custom object space bounding box that is used for visibility culling of attached * mesh instances. * - * @type {import('../../../core/shape/bounding-box.js').BoundingBox|null} + * @type {BoundingBox|null} */ get customAabb() { return this._customAabb; @@ -552,7 +554,7 @@ class RenderComponent extends Component { * Sets the material {@link Material} that will be used to render the component. The material * is ignored for renders of type 'asset'. * - * @type {import('../../../scene/materials/material.js').Material} + * @type {Material} */ set material(value) { if (this._material !== value) { @@ -569,7 +571,7 @@ class RenderComponent extends Component { /** * Gets the material {@link Material} that will be used to render the component. * - * @type {import('../../../scene/materials/material.js').Material} + * @type {Material} */ get material() { return this._material; @@ -679,7 +681,7 @@ class RenderComponent extends Component { } /** - * @param {import('../../entity.js').Entity} entity - The entity set as the root bone. + * @param {Entity} entity - The entity set as the root bone. * @private */ _onSetRootBone(entity) { diff --git a/src/framework/components/render/system.js b/src/framework/components/render/system.js index 12688a94cb1..9de0522aa80 100644 --- a/src/framework/components/render/system.js +++ b/src/framework/components/render/system.js @@ -1,15 +1,15 @@ import { Vec3 } from '../../../core/math/vec3.js'; - import { BoundingBox } from '../../../core/shape/bounding-box.js'; - import { getDefaultMaterial } from '../../../scene/materials/default-material.js'; - import { Component } from '../component.js'; import { ComponentSystem } from '../system.js'; - import { RenderComponent } from './component.js'; import { RenderComponentData } from './data.js'; +/** + * @import { AppBase } from '../../app-base.js' + */ + const _schema = [ { name: 'rootBone', type: 'entity' }, 'enabled' @@ -43,7 +43,7 @@ class RenderComponentSystem extends ComponentSystem { /** * Create a new RenderComponentSystem. * - * @param {import('../../app-base.js').AppBase} app - The Application. + * @param {AppBase} app - The Application. * @ignore */ constructor(app) { diff --git a/src/framework/components/rigid-body/component.js b/src/framework/components/rigid-body/component.js index 2d8d9d5798c..65994a406ce 100644 --- a/src/framework/components/rigid-body/component.js +++ b/src/framework/components/rigid-body/component.js @@ -1,6 +1,6 @@ import { Quat } from '../../../core/math/quat.js'; import { Vec3 } from '../../../core/math/vec3.js'; - +import { Component } from '../component.js'; import { BODYFLAG_KINEMATIC_OBJECT, BODYTYPE_STATIC, BODYGROUP_DYNAMIC, BODYGROUP_KINEMATIC, BODYGROUP_STATIC, @@ -8,7 +8,11 @@ import { BODYSTATE_ACTIVE_TAG, BODYSTATE_DISABLE_DEACTIVATION, BODYSTATE_DISABLE_SIMULATION, BODYTYPE_DYNAMIC, BODYTYPE_KINEMATIC } from './constants.js'; -import { Component } from '../component.js'; + +/** + * @import { Entity } from '../../entity.js' + * @import { RigidBodyComponentSystem } from './system.js' + */ // Shared math variable to avoid excessive allocation let _ammoTransform; @@ -164,9 +168,8 @@ class RigidBodyComponent extends Component { /** * Create a new RigidBodyComponent instance. * - * @param {import('./system.js').RigidBodyComponentSystem} system - The ComponentSystem that - * created this component. - * @param {import('../../entity.js').Entity} entity - The entity this component is attached to. + * @param {RigidBodyComponentSystem} system - The ComponentSystem that created this component. + * @param {Entity} entity - The entity this component is attached to. */ constructor(system, entity) { // eslint-disable-line no-useless-constructor super(system, entity); diff --git a/src/framework/components/rigid-body/system.js b/src/framework/components/rigid-body/system.js index d95b1989b86..36856662795 100644 --- a/src/framework/components/rigid-body/system.js +++ b/src/framework/components/rigid-body/system.js @@ -1,16 +1,18 @@ import { now } from '../../../core/time.js'; import { ObjectPool } from '../../../core/object-pool.js'; import { Debug } from '../../../core/debug.js'; - import { Vec3 } from '../../../core/math/vec3.js'; - import { Component } from '../component.js'; import { ComponentSystem } from '../system.js'; - import { BODYFLAG_NORESPONSE_OBJECT } from './constants.js'; import { RigidBodyComponent } from './component.js'; import { RigidBodyComponentData } from './data.js'; +/** + * @import { AppBase } from '../../app-base.js' + * @import { Entity } from '../../entity.js' + */ + let ammoRayStart, ammoRayEnd; /** @@ -22,7 +24,7 @@ class RaycastResult { /** * The entity that was hit. * - * @type {import('../../entity.js').Entity} + * @type {Entity} */ entity; @@ -51,7 +53,7 @@ class RaycastResult { /** * Create a new RaycastResult instance. * - * @param {import('../../entity.js').Entity} entity - The entity that was hit. + * @param {Entity} entity - The entity that was hit. * @param {Vec3} point - The point at which the ray hit the entity in world space. * @param {Vec3} normal - The normal vector of the surface where the ray hit in world space. * @param {number} hitFraction - The normalized distance (between 0 and 1) at which the ray hit @@ -75,14 +77,14 @@ class SingleContactResult { /** * The first entity involved in the contact. * - * @type {import('../../entity.js').Entity} + * @type {Entity} */ a; /** * The second entity involved in the contact. * - * @type {import('../../entity.js').Entity} + * @type {Entity} */ b; @@ -132,8 +134,8 @@ class SingleContactResult { /** * Create a new SingleContactResult instance. * - * @param {import('../../entity.js').Entity} a - The first entity involved in the contact. - * @param {import('../../entity.js').Entity} b - The second entity involved in the contact. + * @param {Entity} a - The first entity involved in the contact. + * @param {Entity} b - The second entity involved in the contact. * @param {ContactPoint} contactPoint - The contact point between the two entities. * @ignore */ @@ -244,7 +246,7 @@ class ContactResult { /** * The entity that was involved in the contact with this entity. * - * @type {import('../../entity.js').Entity} + * @type {Entity} */ other; @@ -258,8 +260,7 @@ class ContactResult { /** * Create a new ContactResult instance. * - * @param {import('../../entity.js').Entity} other - The entity that was involved in the - * contact with this entity. + * @param {Entity} other - The entity that was involved in the contact with this entity. * @param {ContactPoint[]} contacts - An array of ContactPoints with the other entity. * @ignore */ @@ -345,7 +346,7 @@ class RigidBodyComponentSystem extends ComponentSystem { /** * Create a new RigidBodyComponentSystem. * - * @param {import('../../app-base.js').AppBase} app - The Application. + * @param {AppBase} app - The Application. * @ignore */ constructor(app) { @@ -670,9 +671,8 @@ class RigidBodyComponentSystem extends ComponentSystem { * Stores a collision between the entity and other in the contacts map and returns true if it * is a new collision. * - * @param {import('../../entity.js').Entity} entity - The entity. - * @param {import('../../entity.js').Entity} other - The entity that collides with the first - * entity. + * @param {Entity} entity - The entity. + * @param {Entity} other - The entity that collides with the first entity. * @returns {boolean} True if this is a new collision, false otherwise. * @private */ @@ -803,7 +803,7 @@ class RigidBodyComponentSystem extends ComponentSystem { /** * Returns true if the entity has a contact event attached and false otherwise. * - * @param {import('../../entity.js').Entity} entity - Entity to test. + * @param {Entity} entity - Entity to test. * @returns {boolean} True if the entity has a contact and false otherwise. * @private */ diff --git a/src/framework/components/screen/component.js b/src/framework/components/screen/component.js index e04cab1a1db..00c6378f0be 100644 --- a/src/framework/components/screen/component.js +++ b/src/framework/components/screen/component.js @@ -1,13 +1,14 @@ import { Debug } from '../../../core/debug.js'; - import { Mat4 } from '../../../core/math/mat4.js'; import { Vec2 } from '../../../core/math/vec2.js'; - import { Entity } from '../../entity.js'; - import { SCALEMODE_BLEND, SCALEMODE_NONE } from './constants.js'; import { Component } from '../component.js'; +/** + * @import { ScreenComponentSystem } from './system.js' + */ + const _transform = new Mat4(); /** @@ -20,8 +21,7 @@ class ScreenComponent extends Component { /** * Create a new ScreenComponent. * - * @param {import('./system.js').ScreenComponentSystem} system - The ComponentSystem that - * created this Component. + * @param {ScreenComponentSystem} system - The ComponentSystem that created this Component. * @param {Entity} entity - The Entity that this Component is attached to. */ constructor(system, entity) { diff --git a/src/framework/components/screen/system.js b/src/framework/components/screen/system.js index 19085e7cdf3..b7b23ee12c0 100644 --- a/src/framework/components/screen/system.js +++ b/src/framework/components/screen/system.js @@ -1,13 +1,14 @@ import { IndexedList } from '../../../core/indexed-list.js'; - import { Vec2 } from '../../../core/math/vec2.js'; - import { Component } from '../component.js'; import { ComponentSystem } from '../system.js'; - import { ScreenComponent } from './component.js'; import { ScreenComponentData } from './data.js'; +/** + * @import { AppBase } from '../../app-base.js' + */ + const _schema = ['enabled']; /** @@ -19,7 +20,7 @@ class ScreenComponentSystem extends ComponentSystem { /** * Create a new ScreenComponentSystem instance. * - * @param {import('../../app-base.js').AppBase} app - The application. + * @param {AppBase} app - The application. * @ignore */ constructor(app) { diff --git a/src/framework/components/script/component.js b/src/framework/components/script/component.js index b99fd3efc8a..a3c4dad9d4c 100644 --- a/src/framework/components/script/component.js +++ b/src/framework/components/script/component.js @@ -1,17 +1,20 @@ import { Debug } from '../../../core/debug.js'; import { SortedLoopArray } from '../../../core/sorted-loop-array.js'; - import { ScriptAttributes, assignAttributesToScript } from '../../script/script-attributes.js'; +import { Component } from '../component.js'; +import { Entity } from '../../entity.js'; import { SCRIPT_INITIALIZE, SCRIPT_POST_INITIALIZE, SCRIPT_UPDATE, SCRIPT_POST_UPDATE, SCRIPT_SWAP } from '../../script/constants.js'; - -import { Component } from '../component.js'; -import { Entity } from '../../entity.js'; import { ScriptType } from '../../script/script-type.js'; import { getScriptName } from '../../script/script.js'; +/** + * @import { ScriptComponentSystem } from './system.js' + * @import { Script } from '../../script/script.js' + */ + const toLowerCamelCase = str => str[0].toLowerCase() + str.substring(1); /** @@ -156,8 +159,7 @@ class ScriptComponent extends Component { /** * Create a new ScriptComponent instance. * - * @param {import('./system.js').ScriptComponentSystem} system - The ComponentSystem that - * created this Component. + * @param {ScriptComponentSystem} system - The ComponentSystem that created this Component. * @param {Entity} entity - The Entity that this Component is attached to. */ constructor(system, entity) { @@ -166,7 +168,7 @@ class ScriptComponent extends Component { /** * Holds all script instances for this component. * - * @type {import('../../script/script-type.js').ScriptType[]} + * @type {ScriptType[]} * @private */ this._scripts = []; @@ -203,7 +205,7 @@ class ScriptComponent extends Component { * Sets the array of all script instances attached to an entity. This array is read-only and * should not be modified by developer. * - * @type {import('../../script/script.js').Script[]} + * @type {Script[]} */ set scripts(value) { this._scriptsData = value; @@ -254,7 +256,7 @@ class ScriptComponent extends Component { /** * Gets the array of all script instances attached to an entity. * - * @type {import('../../script/script-type.js').ScriptType[]} + * @type {ScriptType[]} */ get scripts() { return this._scripts; @@ -604,8 +606,7 @@ class ScriptComponent extends Component { /** * Detect if script is attached to an entity. * - * @param {string|typeof import('../../script/script-type.js').ScriptType} nameOrType - The - * name or type of {@link ScriptType}. + * @param {string|typeof ScriptType} nameOrType - The name or type of {@link ScriptType}. * @returns {boolean} If script is attached to an entity. * @example * if (entity.script.has('playerController')) { @@ -628,10 +629,9 @@ class ScriptComponent extends Component { /** * Get a script instance (if attached). * - * @param {string|typeof import('../../script/script-type.js').ScriptType} nameOrType - The - * name or type of {@link ScriptType}. - * @returns {import('../../script/script-type.js').ScriptType|null} If script is attached, the - * instance is returned. Otherwise null is returned. + * @param {string|typeof ScriptType} nameOrType - The name or type of {@link ScriptType}. + * @returns {ScriptType|null} If script is attached, the instance is returned. Otherwise null + * is returned. * @example * const controller = entity.script.get('playerController'); */ @@ -652,8 +652,7 @@ class ScriptComponent extends Component { /** * Create a script instance and attach to an entity script component. * - * @param {string|typeof import('../../script/script.js').Script} nameOrType - The - * name or type of {@link Script}. + * @param {string|typeof Script} nameOrType - The name or type of {@link Script}. * @param {object} [args] - Object with arguments for a script. * @param {boolean} [args.enabled] - If script instance is enabled after creation. Defaults to * true. @@ -663,10 +662,10 @@ class ScriptComponent extends Component { * script and attributes must be initialized manually. Defaults to false. * @param {number} [args.ind] - The index where to insert the script instance at. Defaults to * -1, which means append it at the end. - * @returns {import('../../script/script-type.js').ScriptType|null} Returns an instance of a - * {@link ScriptType} if successfully attached to an entity, or null if it failed because a - * script with a same name has already been added or if the {@link ScriptType} cannot be found - * by name in the {@link ScriptRegistry}. + * @returns {ScriptType|null} Returns an instance of a {@link ScriptType} if successfully + * attached to an entity, or null if it failed because a script with a same name has already + * been added or if the {@link ScriptType} cannot be found by name in the + * {@link ScriptRegistry}. * @example * entity.script.create('playerController', { * attributes: { @@ -766,8 +765,7 @@ class ScriptComponent extends Component { /** * Destroy the script instance that is attached to an entity. * - * @param {string|typeof import('../../script/script-type.js').ScriptType} nameOrType - The - * name or type of {@link ScriptType}. + * @param {string|typeof ScriptType} nameOrType - The name or type of {@link ScriptType}. * @returns {boolean} If it was successfully destroyed. * @example * entity.script.destroy('playerController'); @@ -825,8 +823,7 @@ class ScriptComponent extends Component { /** * Swap the script instance. * - * @param {string|typeof import('../../script/script-type.js').ScriptType} nameOrType - The - * name or type of {@link ScriptType}. + * @param {string|typeof ScriptType} nameOrType - The name or type of {@link ScriptType}. * @returns {boolean} If it was successfully swapped. * @private */ @@ -996,8 +993,7 @@ class ScriptComponent extends Component { /** * Move script instance to different position to alter update order of scripts within entity. * - * @param {string|typeof import('../../script/script-type.js').ScriptType} nameOrType - The - * name or type of {@link ScriptType}. + * @param {string|typeof ScriptType} nameOrType - The name or type of {@link ScriptType}. * @param {number} ind - New position index. * @returns {boolean} If it was successfully moved. * @example diff --git a/src/framework/components/script/system.js b/src/framework/components/script/system.js index 492c0b01cbd..180ccc5bd8f 100644 --- a/src/framework/components/script/system.js +++ b/src/framework/components/script/system.js @@ -1,10 +1,12 @@ import { SortedLoopArray } from '../../../core/sorted-loop-array.js'; - import { ComponentSystem } from '../system.js'; - import { ScriptComponent } from './component.js'; import { ScriptComponentData } from './data.js'; +/** + * @import { AppBase } from '../../app-base.js' + */ + const METHOD_INITIALIZE_ATTRIBUTES = '_onInitializeAttributes'; const METHOD_INITIALIZE = '_onInitialize'; const METHOD_POST_INITIALIZE = '_onPostInitialize'; @@ -26,7 +28,7 @@ class ScriptComponentSystem extends ComponentSystem { /** * Create a new ScriptComponentSystem. * - * @param {import('../../app-base.js').AppBase} app - The application. + * @param {AppBase} app - The application. * @ignore */ constructor(app) { diff --git a/src/framework/components/scroll-view/component.js b/src/framework/components/scroll-view/component.js index ad775e4053d..b5c9321dc87 100644 --- a/src/framework/components/scroll-view/component.js +++ b/src/framework/components/scroll-view/component.js @@ -1,19 +1,20 @@ import { Debug } from '../../../core/debug.js'; - import { math } from '../../../core/math/math.js'; import { Vec2 } from '../../../core/math/vec2.js'; import { Vec3 } from '../../../core/math/vec3.js'; - import { ORIENTATION_HORIZONTAL, ORIENTATION_VERTICAL } from '../../../scene/constants.js'; - import { EntityReference } from '../../utils/entity-reference.js'; - import { ElementDragHelper } from '../element/element-drag-helper.js'; - import { SCROLL_MODE_BOUNCE, SCROLL_MODE_CLAMP, SCROLL_MODE_INFINITE, SCROLLBAR_VISIBILITY_SHOW_ALWAYS, SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED } from './constants.js'; import { Component } from '../component.js'; import { EVENT_MOUSEWHEEL } from '../../../platform/input/constants.js'; +/** + * @import { Entity } from '../../entity.js' + * @import { ScrollViewComponentData } from './data.js' + * @import { ScrollViewComponentSystem } from './system.js' + */ + const _tempScrollValue = new Vec2(); /** @@ -39,10 +40,8 @@ class ScrollViewComponent extends Component { /** * Create a new ScrollViewComponent. * - * @param {import('./system.js').ScrollViewComponentSystem} system - The ComponentSystem that - * created this Component. - * @param {import('../../entity.js').Entity} entity - The Entity that this Component is - * attached to. + * @param {ScrollViewComponentSystem} system - The ComponentSystem that created this Component. + * @param {Entity} entity - The Entity that this Component is attached to. */ constructor(system, entity) { super(system, entity); @@ -86,7 +85,7 @@ class ScrollViewComponent extends Component { // TODO: Remove this override in upgrading component /** - * @type {import('./data.js').ScrollViewComponentData} + * @type {ScrollViewComponentData} * @ignore */ get data() { @@ -301,7 +300,7 @@ class ScrollViewComponent extends Component { * Sets the entity to be used as the masked viewport area, within which the content will scroll. * This entity must have an ElementGroup component. * - * @type {import('../../../framework/entity.js').Entity} + * @type {Entity} */ set viewportEntity(arg) { this._setValue('viewportEntity', arg); @@ -310,7 +309,7 @@ class ScrollViewComponent extends Component { /** * Gets the entity to be used as the masked viewport area, within which the content will scroll. * - * @type {import('../../../framework/entity.js').Entity} + * @type {Entity} */ get viewportEntity() { return this.data.viewportEntity; @@ -320,7 +319,7 @@ class ScrollViewComponent extends Component { * Sets the entity which contains the scrolling content itself. This entity must have an * {@link ElementComponent}. * - * @type {import('../../../framework/entity.js').Entity} + * @type {Entity} */ set contentEntity(arg) { this._setValue('contentEntity', arg); @@ -329,7 +328,7 @@ class ScrollViewComponent extends Component { /** * Gets the entity which contains the scrolling content itself. * - * @type {import('../../../framework/entity.js').Entity} + * @type {Entity} */ get contentEntity() { return this.data.contentEntity; @@ -339,7 +338,7 @@ class ScrollViewComponent extends Component { * Sets the entity to be used as the horizontal scrollbar. This entity must have a * {@link ScrollbarComponent}. * - * @type {import('../../../framework/entity.js').Entity} + * @type {Entity} */ set horizontalScrollbarEntity(arg) { this._setValue('horizontalScrollbarEntity', arg); @@ -348,7 +347,7 @@ class ScrollViewComponent extends Component { /** * Gets the entity to be used as the horizontal scrollbar. * - * @type {import('../../../framework/entity.js').Entity} + * @type {Entity} */ get horizontalScrollbarEntity() { return this.data.horizontalScrollbarEntity; @@ -358,7 +357,7 @@ class ScrollViewComponent extends Component { * Sets the entity to be used as the vertical scrollbar. This entity must have a * {@link ScrollbarComponent}. * - * @type {import('../../../framework/entity.js').Entity} + * @type {Entity} */ set verticalScrollbarEntity(arg) { this._setValue('verticalScrollbarEntity', arg); @@ -367,7 +366,7 @@ class ScrollViewComponent extends Component { /** * Gets the entity to be used as the vertical scrollbar. * - * @type {import('../../../framework/entity.js').Entity} + * @type {Entity} */ get verticalScrollbarEntity() { return this.data.verticalScrollbarEntity; @@ -401,7 +400,7 @@ class ScrollViewComponent extends Component { /** * @param {string} onOrOff - 'on' or 'off'. - * @param {import('./system.js').ScrollViewComponentSystem} system - The ComponentSystem that + * @param {ScrollViewComponentSystem} system - The ComponentSystem that * created this Component. * @private */ diff --git a/src/framework/components/scroll-view/data.js b/src/framework/components/scroll-view/data.js index d546a75f25d..0cdff8a13e3 100644 --- a/src/framework/components/scroll-view/data.js +++ b/src/framework/components/scroll-view/data.js @@ -1,5 +1,9 @@ import { Vec2 } from '../../../core/math/vec2.js'; +/** + * @import { Entity } from '../../../framework/entity.js' + */ + const DEFAULT_DRAG_THRESHOLD = 10; class ScrollViewComponentData { @@ -32,16 +36,16 @@ class ScrollViewComponentData { /** @type {number} */ verticalScrollbarVisibility; - /** @type {import('../../../framework/entity.js').Entity} */ + /** @type {Entity} */ viewportEntity; - /** @type {import('../../../framework/entity.js').Entity} */ + /** @type {Entity} */ contentEntity; - /** @type {import('../../../framework/entity.js').Entity} */ + /** @type {Entity} */ horizontalScrollbarEntity; - /** @type {import('../../../framework/entity.js').Entity} */ + /** @type {Entity} */ verticalScrollbarEntity; } diff --git a/src/framework/components/scroll-view/system.js b/src/framework/components/scroll-view/system.js index d02b5bede21..2a74ab2beea 100644 --- a/src/framework/components/scroll-view/system.js +++ b/src/framework/components/scroll-view/system.js @@ -1,9 +1,11 @@ +import { Vec2 } from '../../../core/math/vec2.js'; import { ComponentSystem } from '../system.js'; - import { ScrollViewComponent } from './component.js'; import { ScrollViewComponentData } from './data.js'; -import { Vec2 } from '../../../core/math/vec2.js'; +/** + * @import { AppBase } from '../../app-base.js' + */ const _schema = [ { name: 'enabled', type: 'boolean' }, @@ -34,7 +36,7 @@ class ScrollViewComponentSystem extends ComponentSystem { /** * Create a new ScrollViewComponentSystem instance. * - * @param {import('../../app-base.js').AppBase} app - The application. + * @param {AppBase} app - The application. * @ignore */ constructor(app) { diff --git a/src/framework/components/scrollbar/component.js b/src/framework/components/scrollbar/component.js index f2869185de8..713a50971b7 100644 --- a/src/framework/components/scrollbar/component.js +++ b/src/framework/components/scrollbar/component.js @@ -1,13 +1,15 @@ import { math } from '../../../core/math/math.js'; - import { ORIENTATION_HORIZONTAL } from '../../../scene/constants.js'; - import { Component } from '../component.js'; - import { ElementDragHelper } from '../element/element-drag-helper.js'; - import { EntityReference } from '../../utils/entity-reference.js'; +/** + * @import { Entity } from '../../entity.js' + * @import { ScrollbarComponentData } from './data.js' + * @import { ScrollbarComponentSystem } from './system.js' + */ + /** * A ScrollbarComponent enables a group of entities to behave like a draggable scrollbar. * @@ -29,10 +31,8 @@ class ScrollbarComponent extends Component { /** * Create a new ScrollbarComponent. * - * @param {import('./system.js').ScrollbarComponentSystem} system - The ComponentSystem that - * created this Component. - * @param {import('../../entity.js').Entity} entity - The Entity that this Component is - * attached to. + * @param {ScrollbarComponentSystem} system - The ComponentSystem that created this Component. + * @param {Entity} entity - The Entity that this Component is attached to. */ constructor(system, entity) { super(system, entity); @@ -50,7 +50,7 @@ class ScrollbarComponent extends Component { // TODO: Remove this override in upgrading component /** - * @type {import('./data.js').ScrollbarComponentData} + * @type {ScrollbarComponentData} * @ignore */ get data() { @@ -141,7 +141,7 @@ class ScrollbarComponent extends Component { * Sets the entity to be used as the scrollbar handle. This entity must have a * {@link ScrollbarComponent}. * - * @type {import('../../../framework/entity.js').Entity} + * @type {Entity} */ set handleEntity(arg) { this._setValue('handleEntity', arg); @@ -150,7 +150,7 @@ class ScrollbarComponent extends Component { /** * Gets the entity to be used as the scrollbar handle. * - * @type {import('../../../framework/entity.js').Entity} + * @type {Entity} */ get handleEntity() { return this.data.handleEntity; diff --git a/src/framework/components/scrollbar/data.js b/src/framework/components/scrollbar/data.js index 243f76fde4d..81c274eaa97 100644 --- a/src/framework/components/scrollbar/data.js +++ b/src/framework/components/scrollbar/data.js @@ -1,5 +1,9 @@ import { ORIENTATION_HORIZONTAL } from '../../../scene/constants.js'; +/** + * @import { Entity } from '../../../framework/entity' + */ + class ScrollbarComponentData { enabled = true; @@ -10,7 +14,7 @@ class ScrollbarComponentData { /** @type {number} */ handleSize; - /** @type {import('../../../framework/entity').Entity} */ + /** @type {Entity} */ handleEntity; } diff --git a/src/framework/components/scrollbar/system.js b/src/framework/components/scrollbar/system.js index ec24224ca1d..3be71f2602a 100644 --- a/src/framework/components/scrollbar/system.js +++ b/src/framework/components/scrollbar/system.js @@ -1,8 +1,11 @@ import { ComponentSystem } from '../system.js'; - import { ScrollbarComponent } from './component.js'; import { ScrollbarComponentData } from './data.js'; +/** + * @import { AppBase } from '../../app-base.js' + */ + const _schema = [ { name: 'enabled', type: 'boolean' }, { name: 'orientation', type: 'number' }, @@ -20,7 +23,7 @@ class ScrollbarComponentSystem extends ComponentSystem { /** * Create a new ScrollbarComponentSystem. * - * @param {import('../../app-base.js').AppBase} app - The application. + * @param {AppBase} app - The application. * @ignore */ constructor(app) { diff --git a/src/framework/components/sound/component.js b/src/framework/components/sound/component.js index 948c4a89460..03bf4a1c579 100644 --- a/src/framework/components/sound/component.js +++ b/src/framework/components/sound/component.js @@ -1,11 +1,14 @@ import { Debug } from '../../../core/debug.js'; - import { DISTANCE_LINEAR } from '../../../platform/audio/constants.js'; - import { Component } from '../component.js'; - import { SoundSlot } from './slot.js'; +/** + * @import { Entity } from '../../entity.js' + * @import { SoundComponentSystem } from './system.js' + * @import { SoundInstance } from '../../../platform/sound/instance.js' + */ + /** * The SoundComponent enables an {@link Entity} to play audio. The SoundComponent can manage * multiple {@link SoundSlot}s, each of which can play a different audio asset with its own set @@ -116,10 +119,8 @@ class SoundComponent extends Component { /** * Create a new Sound Component. * - * @param {import('./system.js').SoundComponentSystem} system - The ComponentSystem that - * created this component. - * @param {import('../../entity.js').Entity} entity - The entity that the Component is attached - * to. + * @param {SoundComponentSystem} system - The ComponentSystem that created this component. + * @param {Entity} entity - The entity that the Component is attached to. */ constructor(system, entity) { super(system, entity); @@ -521,7 +522,8 @@ class SoundComponent extends Component { * * @param {string} name - The name of the {@link SoundSlot} to look for. * @param {string} property - The name of the property to look for. - * @returns {*} The value from the looked property inside the slot with specified name. May be undefined if slot does not exist. + * @returns {*} The value from the looked property inside the slot with specified name. May be + * undefined if slot does not exist. * @private */ _getSlotProperty(name, property) { @@ -584,9 +586,9 @@ class SoundComponent extends Component { * created and played. * * @param {string} name - The name of the {@link SoundSlot} to play. - * @returns {import('../../../platform/sound/instance.js').SoundInstance|null} The sound - * instance that will be played. Returns null if the component or its parent entity is disabled - * or if the SoundComponent has no slot with the specified name. + * @returns {SoundInstance|null} The sound instance that will be played. Returns null if the + * component or its parent entity is disabled or if the SoundComponent has no slot with the + * specified name. * @example * // get asset by id * const asset = app.assets.get(10); diff --git a/src/framework/components/sound/slot.js b/src/framework/components/sound/slot.js index 38581ebc320..ebe51c5064d 100644 --- a/src/framework/components/sound/slot.js +++ b/src/framework/components/sound/slot.js @@ -1,14 +1,15 @@ import { EventHandler } from '../../../core/event-handler.js'; import { Debug } from '../../../core/debug.js'; - import { math } from '../../../core/math/math.js'; import { Vec3 } from '../../../core/math/vec3.js'; - import { Asset } from '../../asset/asset.js'; - import { SoundInstance } from '../../../platform/sound/instance.js'; import { SoundInstance3d } from '../../../platform/sound/instance3d.js'; +/** + * @import { SoundComponent } from './component.js' + */ + // temporary object for creating instances const instanceOptions = { volume: 0, @@ -111,7 +112,7 @@ class SoundSlot extends EventHandler { /** * Create a new SoundSlot. * - * @param {import('./component.js').SoundComponent} component - The Component that created this + * @param {SoundComponent} component - The Component that created this * slot. * @param {string} [name] - The name of the slot. Defaults to 'Untitled'. * @param {object} [options] - Settings for the slot. diff --git a/src/framework/components/sound/system.js b/src/framework/components/sound/system.js index 4dab7e3a949..3105976a4db 100644 --- a/src/framework/components/sound/system.js +++ b/src/framework/components/sound/system.js @@ -1,13 +1,15 @@ import { Debug } from '../../../core/debug.js'; - import { hasAudioContext } from '../../../platform/audio/capabilities.js'; - import { Component } from '../component.js'; import { ComponentSystem } from '../system.js'; - import { SoundComponent } from './component.js'; import { SoundComponentData } from './data.js'; +/** + * @import { AppBase } from '../../app-base.js' + * @import { SoundManager } from '../../../platform/sound/manager.js' + */ + const _schema = ['enabled']; /** @@ -19,7 +21,7 @@ class SoundComponentSystem extends ComponentSystem { /** * Create a SoundComponentSystem. * - * @param {import('../../app-base.js').AppBase} app - The Application. + * @param {AppBase} app - The Application. * @ignore */ constructor(app) { @@ -35,7 +37,7 @@ class SoundComponentSystem extends ComponentSystem { /** * Gets / sets the sound manager. * - * @type {import('../../../platform/sound/manager.js').SoundManager} + * @type {SoundManager} */ this.manager = app.soundManager; Debug.assert(this.manager, "SoundComponentSystem cannot be created without sound manager"); diff --git a/src/framework/components/sprite/component.js b/src/framework/components/sprite/component.js index d3f6c26fe17..ab332eae333 100644 --- a/src/framework/components/sprite/component.js +++ b/src/framework/components/sprite/component.js @@ -1,10 +1,8 @@ import { Debug } from '../../../core/debug.js'; - import { math } from '../../../core/math/math.js'; import { Color } from '../../../core/math/color.js'; import { Vec2 } from '../../../core/math/vec2.js'; import { Vec4 } from '../../../core/math/vec4.js'; - import { LAYERID_WORLD, SPRITE_RENDERMODE_SLICED, SPRITE_RENDERMODE_TILED @@ -13,12 +11,17 @@ import { BatchGroup } from '../../../scene/batching/batch-group.js'; import { GraphNode } from '../../../scene/graph-node.js'; import { MeshInstance } from '../../../scene/mesh-instance.js'; import { Model } from '../../../scene/model.js'; - import { Component } from '../component.js'; - import { SPRITETYPE_SIMPLE, SPRITETYPE_ANIMATED } from './constants.js'; import { SpriteAnimationClip } from './sprite-animation-clip.js'; +/** + * @import { Asset } from '../../asset/asset.js' + * @import { Entity } from '../../entity.js' + * @import { SpriteComponentSystem } from './system.js' + * @import { Sprite } from '../../../scene/sprite.js' + */ + const PARAM_EMISSIVE_MAP = 'texture_emissiveMap'; const PARAM_OPACITY_MAP = 'texture_opacityMap'; const PARAM_EMISSIVE = 'material_emissive'; @@ -108,9 +111,9 @@ class SpriteComponent extends Component { /** * Create a new SpriteComponent instance. * - * @param {import('./system.js').SpriteComponentSystem} system - The ComponentSystem that + * @param {SpriteComponentSystem} system - The ComponentSystem that * created this Component. - * @param {import('../../entity.js').Entity} entity - The Entity that this Component is + * @param {Entity} entity - The Entity that this Component is * attached to. */ constructor(system, entity) { @@ -255,7 +258,7 @@ class SpriteComponent extends Component { * Sets the asset id or the {@link Asset} of the sprite to render. Only works for * {@link SPRITETYPE_SIMPLE} sprites. * - * @type {number|import('../../asset/asset.js').Asset} + * @type {number|Asset} */ set spriteAsset(value) { this._defaultClip.spriteAsset = value; @@ -264,7 +267,7 @@ class SpriteComponent extends Component { /** * Gets the asset id or the {@link Asset} of the sprite to render. * - * @type {number|import('../../asset/asset.js').Asset} + * @type {number|Asset} */ get spriteAsset() { return this._defaultClip._spriteAsset; @@ -273,7 +276,7 @@ class SpriteComponent extends Component { /** * Sets the current sprite. * - * @type {import('../../../scene/sprite.js').Sprite} + * @type {Sprite} */ set sprite(value) { this._currentClip.sprite = value; @@ -282,7 +285,7 @@ class SpriteComponent extends Component { /** * Gets the current sprite. * - * @type {import('../../../scene/sprite.js').Sprite} + * @type {Sprite} */ get sprite() { return this._currentClip.sprite; @@ -987,7 +990,7 @@ class SpriteComponent extends Component { * @param {string} [data.name] - The name of the new animation clip. * @param {number} [data.fps] - Frames per second for the animation clip. * @param {boolean} [data.loop] - Whether to loop the animation clip. - * @param {number|import('../../asset/asset.js').Asset} [data.spriteAsset] - The asset id or + * @param {number|Asset} [data.spriteAsset] - The asset id or * the {@link Asset} of the sprite that this clip will play. * @returns {SpriteAnimationClip} The new clip that was added. */ diff --git a/src/framework/components/sprite/sprite-animation-clip.js b/src/framework/components/sprite/sprite-animation-clip.js index b291ecba90d..700264a6e63 100644 --- a/src/framework/components/sprite/sprite-animation-clip.js +++ b/src/framework/components/sprite/sprite-animation-clip.js @@ -1,11 +1,13 @@ import { EventHandler } from '../../../core/event-handler.js'; - import { math } from '../../../core/math/math.js'; - import { Asset } from '../../asset/asset.js'; - import { SPRITE_RENDERMODE_SIMPLE } from '../../../scene/constants.js'; +/** + * @import { SpriteComponent } from './component.js' + * @import { Sprite } from '../../../scene/sprite.js' + */ + /** * Handles playing of sprite animations and loading of relevant sprite assets. * @@ -81,8 +83,7 @@ class SpriteAnimationClip extends EventHandler { /** * Create a new SpriteAnimationClip instance. * - * @param {import('./component.js').SpriteComponent} component - The sprite component managing - * this clip. + * @param {SpriteComponent} component - The sprite component managing this clip. * @param {object} data - Data for the new animation clip. * @param {number} [data.fps] - Frames per second for the animation clip. * @param {boolean} [data.loop] - Whether to loop the animation clip. @@ -165,7 +166,7 @@ class SpriteAnimationClip extends EventHandler { /** * Sets the current sprite used to play the animation. * - * @type {import('../../../scene/sprite.js').Sprite} + * @type {Sprite} */ set sprite(value) { if (this._sprite) { @@ -236,7 +237,7 @@ class SpriteAnimationClip extends EventHandler { /** * Gets the current sprite used to play the animation. * - * @type {import('../../../scene/sprite.js').Sprite} + * @type {Sprite} */ get sprite() { return this._sprite; diff --git a/src/framework/components/sprite/system.js b/src/framework/components/sprite/system.js index 128811b28ff..0dd41289562 100644 --- a/src/framework/components/sprite/system.js +++ b/src/framework/components/sprite/system.js @@ -1,20 +1,20 @@ import { Color } from '../../../core/math/color.js'; - import { CULLFACE_NONE, PIXELFORMAT_RGBA8 } from '../../../platform/graphics/constants.js'; import { Texture } from '../../../platform/graphics/texture.js'; - import { BLEND_PREMULTIPLIED, SPRITE_RENDERMODE_SLICED, SPRITE_RENDERMODE_TILED } from '../../../scene/constants.js'; import { StandardMaterial } from '../../../scene/materials/standard-material.js'; - import { Component } from '../component.js'; import { ComponentSystem } from '../system.js'; - import { SpriteComponent } from './component.js'; import { SpriteComponentData } from './data.js'; +/** + * @import { AppBase } from '../../app-base.js' + */ + const _schema = ['enabled']; /** @@ -26,7 +26,7 @@ class SpriteComponentSystem extends ComponentSystem { /** * Create a new SpriteComponentSystem instance. * - * @param {import('../../app-base.js').AppBase} app - The application. + * @param {AppBase} app - The application. * @ignore */ constructor(app) { @@ -73,9 +73,8 @@ class SpriteComponentSystem extends ComponentSystem { const material = new StandardMaterial(); material.diffuse.set(0, 0, 0); // black diffuse color to prevent ambient light being included - material.emissive.set(0.5, 0.5, 0.5); // use non-white to compile shader correctly + material.emissive.set(1, 1, 1); material.emissiveMap = texture; - material.emissiveTint = true; material.opacityMap = texture; material.opacityMapChannel = 'a'; material.opacityTint = true; diff --git a/src/framework/components/system.js b/src/framework/components/system.js index 07679e438ed..d055bf39109 100644 --- a/src/framework/components/system.js +++ b/src/framework/components/system.js @@ -1,10 +1,15 @@ import { EventHandler } from '../../core/event-handler.js'; - import { Color } from '../../core/math/color.js'; import { Vec2 } from '../../core/math/vec2.js'; import { Vec3 } from '../../core/math/vec3.js'; import { Vec4 } from '../../core/math/vec4.js'; +/** + * @import { AppBase } from '../app-base.js' + * @import { Component } from './component.js' + * @import { Entity } from '../entity.js' + */ + /** * Component Systems contain the logic and functionality to update all Components of a particular * type. @@ -13,7 +18,7 @@ class ComponentSystem extends EventHandler { /** * Create a new ComponentSystem instance. * - * @param {import('../app-base.js').AppBase} app - The application managing this system. + * @param {AppBase} app - The application managing this system. */ constructor(app) { super(); @@ -28,10 +33,9 @@ class ComponentSystem extends EventHandler { /** * Create new {@link Component} and component data instances and attach them to the entity. * - * @param {import('../entity.js').Entity} entity - The Entity to attach this component to. + * @param {Entity} entity - The Entity to attach this component to. * @param {object} [data] - The source data with which to create the component. - * @returns {import('./component.js').Component} Returns a Component of type defined by the - * component system. + * @returns {Component} Returns a Component of type defined by the component system. * @example * const entity = new pc.Entity(app); * app.systems.model.addComponent(entity, { type: 'box' }); @@ -60,7 +64,7 @@ class ComponentSystem extends EventHandler { /** * Remove the {@link Component} from the entity and delete the associated component data. * - * @param {import('../entity.js').Entity} entity - The entity to remove the component from. + * @param {Entity} entity - The entity to remove the component from. * @example * app.systems.model.removeComponent(entity); * // entity.model === undefined @@ -84,9 +88,9 @@ class ComponentSystem extends EventHandler { /** * Create a clone of component. This creates a copy of all component data variables. * - * @param {import('../entity.js').Entity} entity - The entity to clone the component from. - * @param {import('../entity.js').Entity} clone - The entity to clone the component into. - * @returns {import('./component.js').Component} The newly cloned component. + * @param {Entity} entity - The entity to clone the component from. + * @param {Entity} clone - The entity to clone the component into. + * @returns {Component} The newly cloned component. * @ignore */ cloneComponent(entity, clone) { @@ -100,7 +104,7 @@ class ComponentSystem extends EventHandler { * store. This can be overridden by derived Component Systems and either called by the derived * System or replaced entirely. * - * @param {import('./component.js').Component} component - The component being initialized. + * @param {Component} component - The component being initialized. * @param {object} data - The data block used to initialize the component. * @param {Array} properties - The array of property * descriptors for the component. A descriptor can be either a plain property name, or an diff --git a/src/framework/components/zone/component.js b/src/framework/components/zone/component.js index 7b46a7c3eed..10dc2a4f3d7 100644 --- a/src/framework/components/zone/component.js +++ b/src/framework/components/zone/component.js @@ -1,7 +1,11 @@ import { Vec3 } from '../../../core/math/vec3.js'; - import { Component } from '../component.js'; +/** + * @import { Entity } from '../../entity.js' + * @import { ZoneComponentSystem } from './system.js' + */ + /** * The ZoneComponent allows you to define an area in world space of certain size. This can be used * in various ways, such as affecting audio reverb when {@link AudioListenerComponent} is within @@ -62,10 +66,8 @@ class ZoneComponent extends Component { /** * Create a new ZoneComponent instance. * - * @param {import('./system.js').ZoneComponentSystem} system - The ComponentSystem that - * created this Component. - * @param {import('../../entity.js').Entity} entity - The Entity that this Component is - * attached to. + * @param {ZoneComponentSystem} system - The ComponentSystem that created this Component. + * @param {Entity} entity - The Entity that this Component is attached to. */ constructor(system, entity) { super(system, entity); diff --git a/src/framework/components/zone/system.js b/src/framework/components/zone/system.js index 4d826f4fb8e..b4d42bebc02 100644 --- a/src/framework/components/zone/system.js +++ b/src/framework/components/zone/system.js @@ -1,11 +1,13 @@ import { Vec3 } from '../../../core/math/vec3.js'; - import { Component } from '../component.js'; import { ComponentSystem } from '../system.js'; - import { ZoneComponent } from './component.js'; import { ZoneComponentData } from './data.js'; +/** + * @import { AppBase } from '../../app-base.js' + */ + const _schema = ['enabled']; /** @@ -17,7 +19,7 @@ class ZoneComponentSystem extends ComponentSystem { /** * Create a new ZoneComponentSystem. * - * @param {import('../../app-base.js').AppBase} app - The application. + * @param {AppBase} app - The application. * @ignore */ constructor(app) { diff --git a/src/framework/entity.js b/src/framework/entity.js index 4aaa741cb36..e4b8f981f04 100644 --- a/src/framework/entity.js +++ b/src/framework/entity.js @@ -1,12 +1,33 @@ import { Debug } from '../core/debug.js'; import { guid } from '../core/guid.js'; - import { GraphNode } from '../scene/graph-node.js'; - import { getApplication } from './globals.js'; /** - * @typedef {import('./components/component.js').Component} Component + * @import { AnimComponent } from './components/anim/component.js' + * @import { AnimationComponent } from './components/animation/component.js' + * @import { AppBase } from './app-base.js' + * @import { AudioListenerComponent } from './components/audio-listener/component.js' + * @import { ButtonComponent } from './components/button/component.js' + * @import { CameraComponent } from './components/camera/component.js' + * @import { CollisionComponent } from './components/collision/component.js' + * @import { Component } from './components/component.js' + * @import { ElementComponent } from './components/element/component.js' + * @import { GSplatComponent } from './components/gsplat/component.js' + * @import { LayoutChildComponent } from './components/layout-child/component.js' + * @import { LayoutGroupComponent } from './components/layout-group/component.js' + * @import { LightComponent } from './components/light/component.js' + * @import { ModelComponent } from './components/model/component.js' + * @import { ParticleSystemComponent } from './components/particle-system/component.js' + * @import { RenderComponent } from './components/render/component.js' + * @import { RigidBodyComponent } from './components/rigid-body/component.js' + * @import { ScreenComponent } from './components/screen/component.js' + * @import { ScriptComponent } from './components/script/component.js' + * @import { ScriptType } from './script/script-type.js' + * @import { ScrollViewComponent } from './components/scroll-view/component.js' + * @import { ScrollbarComponent } from './components/scrollbar/component.js' + * @import { SoundComponent } from './components/sound/component.js' + * @import { SpriteComponent } from './components/sprite/component.js' */ /** @@ -73,7 +94,7 @@ class Entity extends GraphNode { /** * Gets the {@link AnimComponent} attached to this entity. * - * @type {import('./components/anim/component.js').AnimComponent|undefined} + * @type {AnimComponent|undefined} * @readonly */ anim; @@ -81,7 +102,7 @@ class Entity extends GraphNode { /** * Gets the {@link AnimationComponent} attached to this entity. * - * @type {import('./components/animation/component.js').AnimationComponent|undefined} + * @type {AnimationComponent|undefined} * @readonly */ animation; @@ -89,7 +110,7 @@ class Entity extends GraphNode { /** * Gets the {@link AudioListenerComponent} attached to this entity. * - * @type {import('./components/audio-listener/component.js').AudioListenerComponent|undefined} + * @type {AudioListenerComponent|undefined} * @readonly */ audiolistener; @@ -97,7 +118,7 @@ class Entity extends GraphNode { /** * Gets the {@link ButtonComponent} attached to this entity. * - * @type {import('./components/button/component.js').ButtonComponent|undefined} + * @type {ButtonComponent|undefined} * @readonly */ button; @@ -105,7 +126,7 @@ class Entity extends GraphNode { /** * Gets the {@link CameraComponent} attached to this entity. * - * @type {import('./components/camera/component.js').CameraComponent|undefined} + * @type {CameraComponent|undefined} * @readonly */ camera; @@ -113,7 +134,7 @@ class Entity extends GraphNode { /** * Gets the {@link CollisionComponent} attached to this entity. * - * @type {import('./components/collision/component.js').CollisionComponent|undefined} + * @type {CollisionComponent|undefined} * @readonly */ collision; @@ -121,7 +142,7 @@ class Entity extends GraphNode { /** * Gets the {@link ElementComponent} attached to this entity. * - * @type {import('./components/element/component.js').ElementComponent|undefined} + * @type {ElementComponent|undefined} * @readonly */ element; @@ -129,7 +150,7 @@ class Entity extends GraphNode { /** * Gets the {@link GSplatComponent} attached to this entity. * - * @type {import('./components/gsplat/component.js').GSplatComponent|undefined} + * @type {GSplatComponent|undefined} * @readonly */ gsplat; @@ -137,7 +158,7 @@ class Entity extends GraphNode { /** * Gets the {@link LayoutChildComponent} attached to this entity. * - * @type {import('./components/layout-child/component.js').LayoutChildComponent|undefined} + * @type {LayoutChildComponent|undefined} * @readonly */ layoutchild; @@ -145,7 +166,7 @@ class Entity extends GraphNode { /** * Gets the {@link LayoutGroupComponent} attached to this entity. * - * @type {import('./components/layout-group/component.js').LayoutGroupComponent|undefined} + * @type {LayoutGroupComponent|undefined} * @readonly */ layoutgroup; @@ -153,7 +174,7 @@ class Entity extends GraphNode { /** * Gets the {@link LightComponent} attached to this entity. * - * @type {import('./components/light/component.js').LightComponent|undefined} + * @type {LightComponent|undefined} * @readonly */ light; @@ -161,7 +182,7 @@ class Entity extends GraphNode { /** * Gets the {@link ModelComponent} attached to this entity. * - * @type {import('./components/model/component.js').ModelComponent|undefined} + * @type {ModelComponent|undefined} * @readonly */ model; @@ -169,7 +190,7 @@ class Entity extends GraphNode { /** * Gets the {@link ParticleSystemComponent} attached to this entity. * - * @type {import('./components/particle-system/component.js').ParticleSystemComponent|undefined} + * @type {ParticleSystemComponent|undefined} * @readonly */ particlesystem; @@ -177,7 +198,7 @@ class Entity extends GraphNode { /** * Gets the {@link RenderComponent} attached to this entity. * - * @type {import('./components/render/component.js').RenderComponent|undefined} + * @type {RenderComponent|undefined} * @readonly */ render; @@ -185,7 +206,7 @@ class Entity extends GraphNode { /** * Gets the {@link RigidBodyComponent} attached to this entity. * - * @type {import('./components/rigid-body/component.js').RigidBodyComponent|undefined} + * @type {RigidBodyComponent|undefined} * @readonly */ rigidbody; @@ -193,7 +214,7 @@ class Entity extends GraphNode { /** * Gets the {@link ScreenComponent} attached to this entity. * - * @type {import('./components/screen/component.js').ScreenComponent|undefined} + * @type {ScreenComponent|undefined} * @readonly */ screen; @@ -201,7 +222,7 @@ class Entity extends GraphNode { /** * Gets the {@link ScriptComponent} attached to this entity. * - * @type {import('./components/script/component.js').ScriptComponent|undefined} + * @type {ScriptComponent|undefined} * @readonly */ script; @@ -209,7 +230,7 @@ class Entity extends GraphNode { /** * Gets the {@link ScrollbarComponent} attached to this entity. * - * @type {import('./components/scrollbar/component.js').ScrollbarComponent|undefined} + * @type {ScrollbarComponent|undefined} * @readonly */ scrollbar; @@ -217,7 +238,7 @@ class Entity extends GraphNode { /** * Gets the {@link ScrollViewComponent} attached to this entity. * - * @type {import('./components/scroll-view/component.js').ScrollViewComponent|undefined} + * @type {ScrollViewComponent|undefined} * @readonly */ scrollview; @@ -225,7 +246,7 @@ class Entity extends GraphNode { /** * Gets the {@link SoundComponent} attached to this entity. * - * @type {import('./components/sound/component.js').SoundComponent|undefined} + * @type {SoundComponent|undefined} * @readonly */ sound; @@ -233,7 +254,7 @@ class Entity extends GraphNode { /** * Gets the {@link SpriteComponent} attached to this entity. * - * @type {import('./components/sprite/component.js').SpriteComponent|undefined} + * @type {SpriteComponent|undefined} * @readonly */ sprite; @@ -241,13 +262,13 @@ class Entity extends GraphNode { /** * Component storage. * - * @type {Object} + * @type {Object} * @ignore */ c = {}; /** - * @type {import('./app-base.js').AppBase} + * @type {AppBase} * @private */ _app; @@ -279,8 +300,8 @@ class Entity extends GraphNode { * Create a new Entity. * * @param {string} [name] - The non-unique name of the entity, default is "Untitled". - * @param {import('./app-base.js').AppBase} [app] - The application the entity belongs to, - * default is the current application. + * @param {AppBase} [app] - The application the entity belongs to, default is the current + * application. * @example * const entity = new pc.Entity(); * @@ -345,8 +366,8 @@ class Entity extends GraphNode { * * @param {object} [data] - The initialization data for the specific component type. Refer to * each specific component's API reference page for details on valid values for this parameter. - * @returns {import('./components/component.js').Component|null} The new Component that was - * attached to the entity or null if there was an error. + * @returns {Component|null} The new Component that was attached to the entity or null if there + * was an error. * @example * const entity = new pc.Entity(); * @@ -399,14 +420,14 @@ class Entity extends GraphNode { * Search the entity and all of its descendants for the first component of specified type. * * @param {string} type - The name of the component type to retrieve. - * @returns {import('./components/component.js').Component} A component of specified type, if - * the entity or any of its descendants has one. Returns undefined otherwise. + * @returns {Component} A component of specified type, if the entity or any of its descendants + * has one. Returns undefined otherwise. * @example * // Get the first found light component in the hierarchy tree that starts with this entity * const light = entity.findComponent("light"); */ findComponent(type) { - const entity = this.findOne(entity => entity?.c[type]); + const entity = this.findOne(entity => entity.c?.[type]); return entity && entity.c[type]; } @@ -414,22 +435,22 @@ class Entity extends GraphNode { * Search the entity and all of its descendants for all components of specified type. * * @param {string} type - The name of the component type to retrieve. - * @returns {import('./components/component.js').Component[]} All components of specified type - * in the entity or any of its descendants. Returns empty array if none found. + * @returns {Component[]} All components of specified type in the entity or any of its + * descendants. Returns empty array if none found. * @example * // Get all light components in the hierarchy tree that starts with this entity * const lights = entity.findComponents("light"); */ findComponents(type) { - return this.find(entity => entity?.c[type]).map(entity => entity.c[type]); + return this.find(entity => entity.c?.[type]).map(entity => entity.c[type]); } /** * Search the entity and all of its descendants for the first script instance of specified type. * - * @param {string|typeof import('./script/script-type.js').ScriptType} nameOrType - The name or type of {@link ScriptType}. - * @returns {import('./script/script-type.js').ScriptType|undefined} A script instance of specified type, if the entity or any of its descendants - * has one. Returns undefined otherwise. + * @param {string|typeof ScriptType} nameOrType - The name or type of {@link ScriptType}. + * @returns {ScriptType|undefined} A script instance of specified type, if the entity or any of + * its descendants has one. Returns undefined otherwise. * @example * // Get the first found "playerController" instance in the hierarchy tree that starts with this entity * const controller = entity.findScript("playerController"); @@ -442,8 +463,8 @@ class Entity extends GraphNode { /** * Search the entity and all of its descendants for all script instances of specified type. * - * @param {string|typeof import('./script/script-type.js').ScriptType} nameOrType - The name or type of {@link ScriptType}. - * @returns {import('./script/script-type.js').ScriptType[]} All script instances of specified type in the entity or any of its + * @param {string|typeof ScriptType} nameOrType - The name or type of {@link ScriptType}. + * @returns {ScriptType[]} All script instances of specified type in the entity or any of its * descendants. Returns empty array if none found. * @example * // Get all "playerController" instances in the hierarchy tree that starts with this entity diff --git a/src/framework/font/canvas-font.js b/src/framework/font/canvas-font.js index 7c07efaefaa..64d701258da 100644 --- a/src/framework/font/canvas-font.js +++ b/src/framework/font/canvas-font.js @@ -1,8 +1,6 @@ import { string } from '../../core/string.js'; import { EventHandler } from '../../core/event-handler.js'; - import { Color } from '../../core/math/color.js'; - import { ADDRESS_CLAMP_TO_EDGE, FILTER_LINEAR, FILTER_LINEAR_MIPMAP_LINEAR, @@ -10,6 +8,10 @@ import { } from '../../platform/graphics/constants.js'; import { Texture } from '../../platform/graphics/texture.js'; +/** + * @import { AppBase } from '../app-base.js' + */ + const MAX_TEXTURE_SIZE = 4096; const DEFAULT_TEXTURE_SIZE = 512; @@ -62,7 +64,7 @@ class CanvasFont extends EventHandler { /** * Create a new CanvasFont instance. * - * @param {import('../app-base.js').AppBase} app - The application. + * @param {AppBase} app - The application. * @param {object} options - The font options. * @param {string} [options.fontName] - The name of the font. CSS font names are supported. * Defaults to 'Arial'. diff --git a/src/framework/font/font.js b/src/framework/font/font.js index da18c4035d4..cae741387f9 100644 --- a/src/framework/font/font.js +++ b/src/framework/font/font.js @@ -1,5 +1,9 @@ import { FONT_MSDF } from './constants.js'; +/** + * @import { Texture } from '../../platform/graphics/texture.js' + */ + /** * Represents the resource of a font asset. * @@ -9,8 +13,7 @@ class Font { /** * Create a new Font instance. * - * @param {import('../../platform/graphics/texture.js').Texture[]} textures - The font - * textures. + * @param {Texture[]} textures - The font textures. * @param {object} data - The font data. */ constructor(textures, data) { @@ -21,7 +24,7 @@ class Font { /** * The font textures. * - * @type {import('../../platform/graphics/texture.js').Texture[]} + * @type {Texture[]} */ this.textures = textures; diff --git a/src/framework/graphics/picker.js b/src/framework/graphics/picker.js index 74615d7e235..5b3d23627ef 100644 --- a/src/framework/graphics/picker.js +++ b/src/framework/graphics/picker.js @@ -1,16 +1,20 @@ import { Color } from '../../core/math/color.js'; - import { ADDRESS_CLAMP_TO_EDGE, FILTER_NEAREST, PIXELFORMAT_RGBA8 } from '../../platform/graphics/constants.js'; import { RenderTarget } from '../../platform/graphics/render-target.js'; import { Texture } from '../../platform/graphics/texture.js'; - import { Layer } from '../../scene/layer.js'; - import { Debug } from '../../core/debug.js'; import { RenderPassPicker } from './render-pass-picker.js'; import { math } from '../../core/math/math.js'; import { Vec4 } from '../../core/math/vec4.js'; +/** + * @import { AppBase } from '../app-base.js' + * @import { CameraComponent } from '../components/camera/component.js' + * @import { MeshInstance } from '../../scene/mesh-instance.js' + * @import { Scene } from '../../scene/scene.js' + */ + const tempSet = new Set(); const _rect = new Vec4(); @@ -37,8 +41,7 @@ class Picker { /** * Create a new Picker instance. * - * @param {import('../app-base.js').AppBase} app - The application managing this picker - * instance. + * @param {AppBase} app - The application managing this picker instance. * @param {number} width - The width of the pick buffer in pixels. * @param {number} height - The height of the pick buffer in pixels. */ @@ -74,8 +77,7 @@ class Picker { * @param {number} y - The top edge of the rectangle. * @param {number} [width] - The width of the rectangle. Defaults to 1. * @param {number} [height] - The height of the rectangle. Defaults to 1. - * @returns {import('../../scene/mesh-instance.js').MeshInstance[]} An array of mesh instances - * that are in the selection. + * @returns {MeshInstance[]} An array of mesh instances that are in the selection. * @example * // Get the selection at the point (10,20) * const selection = picker.getSelection(10, 20); @@ -117,8 +119,8 @@ class Picker { * @param {number} y - The top edge of the rectangle. * @param {number} [width] - The width of the rectangle. Defaults to 1. * @param {number} [height] - The height of the rectangle. Defaults to 1. - * @returns {Promise} - Promise that - * resolves with an array of mesh instances that are in the selection. + * @returns {Promise} - Promise that resolves with an array of mesh instances + * that are in the selection. * @example * // Get the mesh instances at the rectangle with start at (10,20) and size of (5,5) * picker.getSelectionAsync(10, 20, 5, 5).then((meshInstances) => { @@ -221,11 +223,10 @@ class Picker { * be called multiple times on the same picker object. Therefore, if the models or camera do * not change in any way, {@link Picker#prepare} does not need to be called again. * - * @param {import('../components/camera/component.js').CameraComponent} camera - The camera - * component used to render the scene. - * @param {import('../../scene/scene.js').Scene} scene - The scene containing the pickable mesh - * instances. - * @param {Layer[]} [layers] - Layers from which objects will be picked. If not supplied, all layers of the specified camera will be used. + * @param {CameraComponent} camera - The camera component used to render the scene. + * @param {Scene} scene - The scene containing the pickable mesh instances. + * @param {Layer[]} [layers] - Layers from which objects will be picked. If not supplied, all + * layers of the specified camera will be used. */ prepare(camera, scene, layers) { diff --git a/src/framework/graphics/render-pass-picker.js b/src/framework/graphics/render-pass-picker.js index 6019164ae70..91468be0a24 100644 --- a/src/framework/graphics/render-pass-picker.js +++ b/src/framework/graphics/render-pass-picker.js @@ -1,9 +1,12 @@ import { DebugGraphics } from '../../platform/graphics/debug-graphics.js'; import { BlendState } from '../../platform/graphics/blend-state.js'; import { RenderPass } from '../../platform/graphics/render-pass.js'; - import { SHADER_PICK } from '../../scene/constants.js'; +/** + * @import { BindGroup } from '../../platform/graphics/bind-group.js' + */ + const tempMeshInstances = []; const lights = [[], [], []]; @@ -11,7 +14,7 @@ const lights = [[], [], []]; * A render pass implementing rendering of mesh instances into a pick buffer. */ class RenderPassPicker extends RenderPass { - /** @type {import('../../platform/graphics/bind-group.js').BindGroup[]} */ + /** @type {BindGroup[]} */ viewBindGroups = []; constructor(device, renderer) { diff --git a/src/framework/handlers/animation.js b/src/framework/handlers/animation.js index a39ebc16311..f4df5d9e313 100644 --- a/src/framework/handlers/animation.js +++ b/src/framework/handlers/animation.js @@ -1,17 +1,16 @@ import { path } from '../../core/path.js'; - import { Quat } from '../../core/math/quat.js'; import { Vec3 } from '../../core/math/vec3.js'; - import { http, Http } from '../../platform/net/http.js'; - import { Animation, Key, Node } from '../../scene/animation/animation.js'; import { AnimEvents } from '../anim/evaluator/anim-events.js'; - import { GlbParser } from '../parsers/glb-parser.js'; - import { ResourceHandler } from './handler.js'; +/** + * @import { AppBase } from '../app-base.js' + */ + /** * Resource handler used for loading {@link Animation} resources. * @@ -19,7 +18,7 @@ import { ResourceHandler } from './handler.js'; */ class AnimationHandler extends ResourceHandler { /** - * @param {import('../app-base.js').AppBase} app - The running {@link AppBase}. + * @param {AppBase} app - The running {@link AppBase}. * @ignore */ constructor(app) { diff --git a/src/framework/handlers/audio.js b/src/framework/handlers/audio.js index f802eb5731e..61ba50b006e 100644 --- a/src/framework/handlers/audio.js +++ b/src/framework/handlers/audio.js @@ -1,14 +1,14 @@ import { path } from '../../core/path.js'; import { Debug } from '../../core/debug.js'; - import { http, Http } from '../../platform/net/http.js'; - import { hasAudioContext } from '../../platform/audio/capabilities.js'; - import { Sound } from '../../platform/sound/sound.js'; - import { ResourceHandler } from './handler.js'; +/** + * @import { AppBase } from '../app-base.js' + */ + // checks if user is running IE const ie = (function () { if (typeof window === 'undefined') { @@ -53,7 +53,7 @@ class AudioHandler extends ResourceHandler { /** * Create a new AudioHandler instance. * - * @param {import('../app-base.js').AppBase} app - The running {@link AppBase}. + * @param {AppBase} app - The running {@link AppBase}. * @ignore */ constructor(app) { diff --git a/src/framework/handlers/basis.js b/src/framework/handlers/basis.js index a142061395a..48be738b4a7 100644 --- a/src/framework/handlers/basis.js +++ b/src/framework/handlers/basis.js @@ -4,6 +4,10 @@ import { PIXELFORMAT_RGB565, PIXELFORMAT_RGBA4 } from '../../platform/graphics/c import { BasisWorker } from './basis-worker.js'; import { http } from '../../platform/net/http.js'; +/** + * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js' + */ + // get the list of the device's supported compression formats const getCompressionFormats = (device) => { return { @@ -316,8 +320,7 @@ let deviceDetails = null; /** * Enqueue a blob of basis data for transcoding. * - * @param {import('../../platform/graphics/graphics-device.js').GraphicsDevice} device - The - * graphics device. + * @param {GraphicsDevice} device - The graphics device. * @param {string} url - URL of the basis file. * @param {object} data - The file data to transcode. * @param {Function} callback - Callback function to receive transcode result. diff --git a/src/framework/handlers/bundle.js b/src/framework/handlers/bundle.js index a3c52d4284f..ebf1579cd52 100644 --- a/src/framework/handlers/bundle.js +++ b/src/framework/handlers/bundle.js @@ -3,6 +3,10 @@ import { Debug } from '../../core/debug.js'; import { Untar } from './untar.js'; import { ResourceHandler } from './handler.js'; +/** + * @import { AppBase } from '../app-base.js' + */ + /** * Loads Bundle Assets. * @@ -12,7 +16,7 @@ class BundleHandler extends ResourceHandler { /** * Create a new BundleHandler instance. * - * @param {import('../app-base.js').AppBase} app - The running {@link AppBase}. + * @param {AppBase} app - The running {@link AppBase}. */ constructor(app) { super(app, 'bundle'); diff --git a/src/framework/handlers/container.js b/src/framework/handlers/container.js index 7c5aeb36fee..88f1fecfd76 100644 --- a/src/framework/handlers/container.js +++ b/src/framework/handlers/container.js @@ -1,17 +1,23 @@ import { path } from '../../core/path.js'; - import { GlbContainerParser } from '../parsers/glb-container-parser.js'; - import { ResourceHandler } from './handler.js'; +/** + * @import { AppBase } from '../app-base.js' + * @import { Asset } from '../asset/asset.js' + * @import { Entity } from '../entity.js' + * @import { MeshInstance } from '../../scene/mesh-instance.js' + * @import { ResourceHandlerCallback } from './handler.js' + */ + /** * @interface * @name ContainerResource * @description Container for a list of animations, textures, materials, renders and a model. - * @property {import('../asset/asset.js').Asset[]} renders An array of the Render assets. - * @property {import('../asset/asset.js').Asset[]} materials An array of {@link Material} and/or {@link StandardMaterial} assets. - * @property {import('../asset/asset.js').Asset[]} textures An array of the {@link Texture} assets. - * @property {import('../asset/asset.js').Asset[]} animations An array of the {@link Animation} assets. + * @property {Asset[]} renders An array of the Render assets. + * @property {Asset[]} materials An array of {@link Material} and/or {@link StandardMaterial} assets. + * @property {Asset[]} textures An array of the {@link Texture} assets. + * @property {Asset[]} animations An array of the {@link Animation} assets. * @category Graphics */ class ContainerResource { @@ -20,8 +26,8 @@ class ContainerResource { * * @param {object} [options] - The initialization data for the model component type * {@link ModelComponent}. - * @returns {import('../entity.js').Entity} A single entity with a model component. Model - * component internally contains a hierarchy based on {@link GraphNode}. + * @returns {Entity} A single entity with a model component. Model component internally + * contains a hierarchy based on {@link GraphNode}. * @example * // load a glb file and instantiate an entity with a model component based on it * app.assets.loadFromUrl("statue.glb", "container", function (err, asset) { @@ -40,8 +46,8 @@ class ContainerResource { * * @param {object} [options] - The initialization data for the render component type * {@link RenderComponent}. - * @returns {import('../entity.js').Entity} A hierarchy of entities with render components on - * entities containing renderable geometry. + * @returns {Entity} A hierarchy of entities with render components on entities containing + * renderable geometry. * @example * // load a glb file and instantiate an entity with a render component based on it * app.assets.loadFromUrl("statue.glb", "container", function (err, asset) { @@ -76,10 +82,9 @@ class ContainerResource { /** * Applies a material variant to an entity hierarchy. * - * @param {import('../entity.js').Entity} entity - The entity root to which material variants - * will be applied. - * @param {string} [name] - The name of the variant, as queried from getMaterialVariants, - * if null the variant will be reset to the default. + * @param {Entity} entity - The entity root to which material variants will be applied. + * @param {string} [name] - The name of the variant, as queried from getMaterialVariants, if + * null the variant will be reset to the default. * @example * // load a glb file and instantiate an entity with a render component based on it * app.assets.loadFromUrl("statue.glb", "container", function (err, asset) { @@ -97,10 +102,9 @@ class ContainerResource { * this method allows for setting the variant on a specific set of mesh instances instead of the * whole entity. * - * @param {import('../../scene/mesh-instance').MeshInstance[]} instances - An array of mesh - * instances. - * @param {string} [name] - The name of the variant, as queried by getMaterialVariants. If - * null, the variant will be reset to the default. + * @param {MeshInstance[]} instances - An array of mesh instances. + * @param {string} [name] - The name of the variant, as queried by getMaterialVariants. If null, + * the variant will be reset to the default. * @example * // load a glb file and instantiate an entity with a render component based on it * app.assets.loadFromUrl("statue.glb", "container", function (err, asset) { @@ -166,7 +170,7 @@ class ContainerHandler extends ResourceHandler { /** * Create a new ContainerResource instance. * - * @param {import('../app-base.js').AppBase} app - The running {@link AppBase}. + * @param {AppBase} app - The running {@link AppBase}. * @ignore */ constructor(app) { @@ -214,10 +218,9 @@ class ContainerHandler extends ResourceHandler { * @param {string} [url.load] - The URL to be used for loading the resource. * @param {string} [url.original] - The original URL to be used for identifying the resource * format. This is necessary when loading, for example from blob. - * @param {import('./handler.js').ResourceHandlerCallback} callback - The callback used when - * the resource is loaded or an error occurs. - * @param {import('../asset/asset.js').Asset} [asset] - Optional asset that is passed by - * ResourceLoader. + * @param {ResourceHandlerCallback} callback - The callback used when the resource is loaded or + * an error occurs. + * @param {Asset} [asset] - Optional asset that is passed by ResourceLoader. */ load(url, callback, asset) { if (typeof url === 'string') { @@ -233,8 +236,7 @@ class ContainerHandler extends ResourceHandler { /** * @param {string} url - The URL of the resource to open. * @param {*} data - The raw resource data passed by callback from {@link ResourceHandler#load}. - * @param {import('../asset/asset.js').Asset} [asset] - Optional asset that is passed by - * ResourceLoader. + * @param {Asset} [asset] - Optional asset that is passed by ResourceLoader. * @returns {*} The parsed resource data. */ open(url, data, asset) { diff --git a/src/framework/handlers/cubemap.js b/src/framework/handlers/cubemap.js index e516a43e27f..971d4cd6b30 100644 --- a/src/framework/handlers/cubemap.js +++ b/src/framework/handlers/cubemap.js @@ -3,11 +3,13 @@ import { TEXTURETYPE_DEFAULT, TEXTURETYPE_RGBM } from '../../platform/graphics/constants.js'; import { Texture } from '../../platform/graphics/texture.js'; - import { Asset } from '../asset/asset.js'; - import { ResourceHandler } from './handler.js'; +/** + * @import { AppBase } from '../app-base.js' + */ + /** * Resource handler used for loading cubemap {@link Texture} resources. * @@ -17,7 +19,7 @@ class CubemapHandler extends ResourceHandler { /** * Create a new CubemapHandler instance. * - * @param {import('../app-base.js').AppBase} app - The running {@link AppBase}. + * @param {AppBase} app - The running {@link AppBase}. * @ignore */ constructor(app) { diff --git a/src/framework/handlers/font.js b/src/framework/handlers/font.js index d59f667f610..e280ee301eb 100644 --- a/src/framework/handlers/font.js +++ b/src/framework/handlers/font.js @@ -1,12 +1,13 @@ import { path } from '../../core/path.js'; import { string } from '../../core/string.js'; - import { http } from '../../platform/net/http.js'; - import { Font } from '../font/font.js'; - import { ResourceHandler } from './handler.js'; +/** + * @import { AppBase } from '../app-base.js' + */ + function upgradeDataSchema(data) { // convert v1 and v2 to v3 font data schema if (data.version < 3) { @@ -40,7 +41,7 @@ class FontHandler extends ResourceHandler { /** * Create a new FontHandler instance. * - * @param {import('../app-base.js').AppBase} app - The running {@link AppBase}. + * @param {AppBase} app - The running {@link AppBase}. * @ignore */ constructor(app) { diff --git a/src/framework/handlers/gsplat.js b/src/framework/handlers/gsplat.js index 86170b77e12..dd34a15768f 100644 --- a/src/framework/handlers/gsplat.js +++ b/src/framework/handlers/gsplat.js @@ -1,12 +1,15 @@ import { PlyParser } from '../parsers/ply.js'; - import { ResourceHandler } from './handler.js'; +/** + * @import { AppBase } from '../app-base.js' + */ + class GSplatHandler extends ResourceHandler { /** * Create a new GSplatHandler instance. * - * @param {import('../app-base.js').AppBase} app - The running {@link AppBase}. + * @param {AppBase} app - The running {@link AppBase}. * @ignore */ constructor(app) { diff --git a/src/framework/handlers/handler.js b/src/framework/handlers/handler.js index 36c2db15051..a9efdeed7c7 100644 --- a/src/framework/handlers/handler.js +++ b/src/framework/handlers/handler.js @@ -1,3 +1,9 @@ +/** + * @import { AppBase } from '../app-base.js' + * @import { AssetRegistry } from '../asset/asset-registry.js' + * @import { Asset } from '../asset/asset.js' + */ + /** * Callback used by {@link ResourceHandler#load} when a resource is loaded (or an error occurs). * @@ -20,7 +26,7 @@ class ResourceHandler { /** * The running app instance. * - * @type {import('../app-base').AppBase} + * @type {AppBase} */ _app; @@ -28,7 +34,7 @@ class ResourceHandler { _maxRetries = 0; /** - * @param {import('../app-base').AppBase} app - The running {@link AppBase}. + * @param {AppBase} app - The running {@link AppBase}. * @param {string} handlerType - The type of the resource the handler handles. */ constructor(app, handlerType) { @@ -64,8 +70,7 @@ class ResourceHandler { * format. This is necessary when loading, for example from blob. * @param {ResourceHandlerCallback} callback - The callback used when the resource is loaded or * an error occurs. - * @param {import('../asset/asset.js').Asset} [asset] - Optional asset that is passed by - * ResourceLoader. + * @param {Asset} [asset] - Optional asset that is passed by ResourceLoader. */ load(url, callback, asset) { // do nothing @@ -77,8 +82,7 @@ class ResourceHandler { * * @param {string} url - The URL of the resource to open. * @param {*} data - The raw resource data passed by callback from {@link ResourceHandler#load}. - * @param {import('../asset/asset.js').Asset} [asset] - Optional asset that is passed by - * ResourceLoader. + * @param {Asset} [asset] - Optional asset that is passed by ResourceLoader. * @returns {*} The parsed resource data. */ open(url, data, asset) { @@ -89,8 +93,8 @@ class ResourceHandler { * The patch function performs any operations on a resource that requires a dependency on its * asset data or any other asset data. The base implementation does nothing. * - * @param {import('../asset/asset.js').Asset} asset - The asset to patch. - * @param {import('../asset/asset-registry.js').AssetRegistry} assets - The asset registry. + * @param {Asset} asset - The asset to patch. + * @param {AssetRegistry} assets - The asset registry. */ patch(asset, assets) { // do nothing diff --git a/src/framework/handlers/hierarchy.js b/src/framework/handlers/hierarchy.js index ce3532ed685..e5c47c2ca83 100644 --- a/src/framework/handlers/hierarchy.js +++ b/src/framework/handlers/hierarchy.js @@ -1,11 +1,14 @@ import { SceneParser } from '../parsers/scene.js'; import { SceneUtils } from './scene-utils.js'; - import { ResourceHandler } from './handler.js'; +/** + * @import { AppBase } from '../app-base.js' + */ + class HierarchyHandler extends ResourceHandler { /** - * @param {import('../app-base').AppBase} app - The running {@link AppBase}. + * @param {AppBase} app - The running {@link AppBase}. */ constructor(app) { super(app, 'hierarchy'); diff --git a/src/framework/handlers/loader.js b/src/framework/handlers/loader.js index 6ca1929b878..114e836761b 100644 --- a/src/framework/handlers/loader.js +++ b/src/framework/handlers/loader.js @@ -1,5 +1,13 @@ import { Debug } from '../../core/debug.js'; +/** + * @import { AppBase } from '../app-base.js' + * @import { AssetRegistry } from '../asset/asset-registry.js' + * @import { Asset } from '../asset/asset.js' + * @import { BundlesFilterCallback } from '../asset/asset-registry.js' + * @import { ResourceHandler } from './handler.js' + */ + /** * Callback used by {@link ResourceLoader#load} when a resource is loaded (or an error occurs). * @@ -16,7 +24,7 @@ class ResourceLoader { /** * Create a new ResourceLoader instance. * - * @param {import('../app-base.js').AppBase} app - The application. + * @param {AppBase} app - The application. */ constructor(app) { this._handlers = {}; @@ -48,7 +56,7 @@ class ResourceLoader { * - {@link ASSET_SCRIPT} * - {@link ASSET_CONTAINER} * - * @param {import('./handler.js').ResourceHandler} handler - An instance of a resource handler + * @param {ResourceHandler} handler - An instance of a resource handler * supporting at least `load()` and `open()`. * @example * const loader = new ResourceLoader(); @@ -72,7 +80,7 @@ class ResourceLoader { * Get a {@link ResourceHandler} for a resource type. * * @param {string} type - The name of the resource type that the handler is registered with. - * @returns {import('./handler.js').ResourceHandler|undefined} The registered handler, or + * @returns {ResourceHandler|undefined} The registered handler, or * undefined if the requested handler is not registered. */ getHandler(type) { @@ -92,12 +100,12 @@ class ResourceLoader { * @param {string} type - The type of resource expected. * @param {ResourceLoaderCallback} callback - The callback used when the resource is loaded or * an error occurs. Passed (err, resource) where err is null if there are no errors. - * @param {import('../asset/asset.js').Asset} [asset] - Optional asset that is passed into + * @param {Asset} [asset] - Optional asset that is passed into * handler. * @param {object} [options] - Additional options for loading. * @param {boolean} [options.bundlesIgnore] - If set to true, then asset will not try to load * from a bundle. Defaults to false. - * @param {import('../asset/asset-registry.js').BundlesFilterCallback} [options.bundlesFilter] - A callback that will be called + * @param {BundlesFilterCallback} [options.bundlesFilter] - A callback that will be called * when loading an asset that is contained in any of the bundles. It provides an array of * bundles and will ensure asset is loaded from bundle returned from a callback. By default * smallest filesize bundle is choosen. @@ -281,8 +289,8 @@ class ResourceLoader { * Perform any operations on a resource, that requires a dependency on its asset data or any * other asset data. * - * @param {import('../asset/asset.js').Asset} asset - The asset to patch. - * @param {import('../asset/asset-registry.js').AssetRegistry} assets - The asset registry. + * @param {Asset} asset - The asset to patch. + * @param {AssetRegistry} assets - The asset registry. */ patch(asset, assets) { const handler = this._handlers[asset.type]; diff --git a/src/framework/handlers/material.js b/src/framework/handlers/material.js index 662ec86ae30..87745fd294b 100644 --- a/src/framework/handlers/material.js +++ b/src/framework/handlers/material.js @@ -1,15 +1,15 @@ import { http } from '../../platform/net/http.js'; - import { PIXELFORMAT_RGBA8 } from '../../platform/graphics/constants.js'; import { Texture } from '../../platform/graphics/texture.js'; - import { standardMaterialCubemapParameters, standardMaterialTextureParameters } from '../../scene/materials/standard-material-parameters.js'; - import { AssetReference } from '../asset/asset-reference.js'; import { JsonStandardMaterialParser } from '../parsers/material/json-standard-material.js'; - import { ResourceHandler } from './handler.js'; +/** + * @import { AppBase } from '../app-base.js' + */ + const PLACEHOLDER_MAP = { aoMap: 'white', diffuseMap: 'gray', @@ -40,7 +40,7 @@ class MaterialHandler extends ResourceHandler { /** * Create a new MaterialHandler instance. * - * @param {import('../app-base.js').AppBase} app - The running {@link AppBase}. + * @param {AppBase} app - The running {@link AppBase}. * @ignore */ constructor(app) { diff --git a/src/framework/handlers/model.js b/src/framework/handlers/model.js index 96c17db0ef7..93892ad1be4 100644 --- a/src/framework/handlers/model.js +++ b/src/framework/handlers/model.js @@ -1,14 +1,14 @@ import { path } from '../../core/path.js'; - import { http, Http } from '../../platform/net/http.js'; - import { getDefaultMaterial } from '../../scene/materials/default-material.js'; - import { GlbModelParser } from '../parsers/glb-model.js'; import { JsonModelParser } from '../parsers/json-model.js'; - import { ResourceHandler } from './handler.js'; +/** + * @import { AppBase } from '../app-base.js' + */ + /** * Callback used by {@link ModelHandler#addParser} to decide on which parser to use. * @@ -28,7 +28,7 @@ class ModelHandler extends ResourceHandler { /** * Create a new ModelHandler instance. * - * @param {import('../app-base.js').AppBase} app - The running {@link AppBase}. + * @param {AppBase} app - The running {@link AppBase}. * @ignore */ constructor(app) { diff --git a/src/framework/handlers/render.js b/src/framework/handlers/render.js index d27f8923b76..e8c87e81f72 100644 --- a/src/framework/handlers/render.js +++ b/src/framework/handlers/render.js @@ -1,7 +1,10 @@ import { Render } from '../../scene/render.js'; - import { ResourceHandler } from './handler.js'; +/** + * @import { AppBase } from '../app-base.js' + */ + // The scope of this function is the render asset function onContainerAssetLoaded(containerAsset) { const renderAsset = this; @@ -50,7 +53,7 @@ class RenderHandler extends ResourceHandler { /** * Create a new RenderHandler instance. * - * @param {import('../app-base.js').AppBase} app - The running {@link AppBase}. + * @param {AppBase} app - The running {@link AppBase}. * @ignore */ constructor(app) { diff --git a/src/framework/handlers/scene.js b/src/framework/handlers/scene.js index 4bca3bdf5c2..64dcd14ec6c 100644 --- a/src/framework/handlers/scene.js +++ b/src/framework/handlers/scene.js @@ -1,8 +1,11 @@ import { SceneUtils } from './scene-utils.js'; import { SceneParser } from '../parsers/scene.js'; - import { ResourceHandler } from './handler.js'; +/** + * @import { AppBase } from '../app-base.js' + */ + /** * Resource handler used for loading {@link Scene} resources. * @@ -12,7 +15,7 @@ class SceneHandler extends ResourceHandler { /** * Create a new SceneHandler instance. * - * @param {import('../app-base.js').AppBase} app - The running {@link AppBase}. + * @param {AppBase} app - The running {@link AppBase}. * @ignore */ constructor(app) { diff --git a/src/framework/handlers/script.js b/src/framework/handlers/script.js index 5940350b9bd..20e028f1310 100644 --- a/src/framework/handlers/script.js +++ b/src/framework/handlers/script.js @@ -3,10 +3,13 @@ import { script } from '../script.js'; import { ScriptTypes } from '../script/script-types.js'; import { registerScript } from '../script/script-create.js'; import { ResourceLoader } from './loader.js'; - import { ResourceHandler } from './handler.js'; import { Script } from '../script/script.js'; +/** + * @import { AppBase } from '../app-base.js' + */ + const toLowerCamelCase = str => str[0].toLowerCase() + str.substring(1); /** @@ -20,7 +23,7 @@ class ScriptHandler extends ResourceHandler { /** * Create a new ScriptHandler instance. * - * @param {import('../app-base.js').AppBase} app - The running {@link AppBase}. + * @param {AppBase} app - The running {@link AppBase}. * @ignore */ constructor(app) { diff --git a/src/framework/handlers/sprite.js b/src/framework/handlers/sprite.js index 75221bfad3d..a05d0843c3f 100644 --- a/src/framework/handlers/sprite.js +++ b/src/framework/handlers/sprite.js @@ -1,11 +1,12 @@ import { path } from '../../core/path.js'; - import { http } from '../../platform/net/http.js'; - import { Sprite } from '../../scene/sprite.js'; - import { ResourceHandler } from './handler.js'; +/** + * @import { AppBase } from '../app-base.js' + */ + // The scope of this function is the sprite asset function onTextureAtlasLoaded(atlasAsset) { const spriteAsset = this; @@ -29,7 +30,7 @@ class SpriteHandler extends ResourceHandler { /** * Create a new SpriteHandler instance. * - * @param {import('../app-base.js').AppBase} app - The running {@link AppBase}. + * @param {AppBase} app - The running {@link AppBase}. * @ignore */ constructor(app) { diff --git a/src/framework/handlers/texture-atlas.js b/src/framework/handlers/texture-atlas.js index 44b7d5b126f..62cbb36bb4b 100644 --- a/src/framework/handlers/texture-atlas.js +++ b/src/framework/handlers/texture-atlas.js @@ -1,18 +1,19 @@ import { path } from '../../core/path.js'; import { Vec2 } from '../../core/math/vec2.js'; import { Vec4 } from '../../core/math/vec4.js'; - import { ADDRESS_CLAMP_TO_EDGE, ADDRESS_MIRRORED_REPEAT, ADDRESS_REPEAT, FILTER_LINEAR, FILTER_NEAREST, FILTER_NEAREST_MIPMAP_NEAREST, FILTER_NEAREST_MIPMAP_LINEAR, FILTER_LINEAR_MIPMAP_NEAREST, FILTER_LINEAR_MIPMAP_LINEAR, TEXTURETYPE_DEFAULT, TEXTURETYPE_RGBM } from '../../platform/graphics/constants.js'; import { http } from '../../platform/net/http.js'; - import { TextureAtlas } from '../../scene/texture-atlas.js'; - import { ResourceHandler } from './handler.js'; +/** + * @import { AppBase } from '../app-base.js' + */ + const JSON_ADDRESS_MODE = { 'repeat': ADDRESS_REPEAT, 'clamp': ADDRESS_CLAMP_TO_EDGE, @@ -39,7 +40,7 @@ class TextureAtlasHandler extends ResourceHandler { /** * Create a new TextureAtlasHandler instance. * - * @param {import('../app-base.js').AppBase} app - The running {@link AppBase}. + * @param {AppBase} app - The running {@link AppBase}. * @ignore */ constructor(app) { diff --git a/src/framework/handlers/texture.js b/src/framework/handlers/texture.js index a6a686f3410..bc2d5be2ab4 100644 --- a/src/framework/handlers/texture.js +++ b/src/framework/handlers/texture.js @@ -1,5 +1,4 @@ import { path } from '../../core/path.js'; - import { TEXHINT_ASSET, ADDRESS_CLAMP_TO_EDGE, ADDRESS_MIRRORED_REPEAT, ADDRESS_REPEAT, @@ -9,16 +8,18 @@ import { } from '../../platform/graphics/constants.js'; import { Texture } from '../../platform/graphics/texture.js'; import { TextureUtils } from '../../platform/graphics/texture-utils.js'; - import { BasisParser } from '../parsers/texture/basis.js'; import { ImgParser } from '../parsers/texture/img.js'; import { KtxParser } from '../parsers/texture/ktx.js'; import { Ktx2Parser } from '../parsers/texture/ktx2.js'; import { DdsParser } from '../parsers/texture/dds.js'; import { HdrParser } from '../parsers/texture/hdr.js'; - import { ResourceHandler } from './handler.js'; +/** + * @import { AppBase } from '../app-base.js' + */ + const JSON_ADDRESS_MODE = { 'repeat': ADDRESS_REPEAT, 'clamp': ADDRESS_CLAMP_TO_EDGE, @@ -121,7 +122,7 @@ class TextureHandler extends ResourceHandler { /** * Create a new TextureHandler instance. * - * @param {import('../app-base.js').AppBase} app - The running {@link AppBase}. + * @param {AppBase} app - The running {@link AppBase}. * @ignore */ constructor(app) { diff --git a/src/framework/i18n/i18n.js b/src/framework/i18n/i18n.js index 18868cab4e2..942c62a7f43 100644 --- a/src/framework/i18n/i18n.js +++ b/src/framework/i18n/i18n.js @@ -1,19 +1,12 @@ import { EventHandler } from '../../core/event-handler.js'; - import { Asset } from '../asset/asset.js'; +import { DEFAULT_LOCALE, DEFAULT_LOCALE_FALLBACKS } from './constants.js'; +import { findAvailableLocale, getLang, getPluralFn, replaceLang } from './utils.js'; import { I18nParser } from './i18n-parser.js'; -import { - DEFAULT_LOCALE, - DEFAULT_LOCALE_FALLBACKS -} from './constants.js'; - -import { - replaceLang, - getLang, - getPluralFn, - findAvailableLocale -} from './utils.js'; +/** + * @import { AppBase } from '../app-base.js' + */ /** * Handles localization. Responsible for loading localization assets and returning translations for @@ -24,7 +17,7 @@ class I18n extends EventHandler { /** * Create a new I18n instance. * - * @param {import('../app-base.js').AppBase} app - The application. + * @param {AppBase} app - The application. */ constructor(app) { super(); diff --git a/src/framework/input/element-input.js b/src/framework/input/element-input.js index 9dcb4ef81e1..4b4ceea3b23 100644 --- a/src/framework/input/element-input.js +++ b/src/framework/input/element-input.js @@ -2,11 +2,18 @@ import { platform } from '../../core/platform.js'; import { Vec3 } from '../../core/math/vec3.js'; import { Vec4 } from '../../core/math/vec4.js'; import { Ray } from '../../core/shape/ray.js'; - import { Mouse } from '../../platform/input/mouse.js'; - import { getApplication } from '../globals.js'; +/** + * @import { CameraComponent } from '../components/camera/component.js' + * @import { ElementComponent } from '../components/element/component.js' + * @import { MouseEvent } from '../../platform/input/mouse-event.js' + * @import { TouchEvent } from '../../platform/input/touch-event.js' + * @import { Touch } from '../../platform/input/touch-event.js' + * @import { XrInputSource } from '../xr/xr-input-source.js' + */ + let targetX, targetY; const vecA = new Vec3(); const vecB = new Vec3(); @@ -116,34 +123,31 @@ class ElementInputEvent { /** * Create a new ElementInputEvent instance. * - * @param {import('../../platform/input/mouse-event.js').MouseEvent - * |import('../../platform/input/touch-event.js').TouchEvent} event - MouseEvent or TouchEvent - * that was originally raised. - * @param {import('../components/element/component.js').ElementComponent} element - The - * ElementComponent that this event was originally raised on. - * @param {import('../components/camera/component.js').CameraComponent} camera - The - * CameraComponent that this event was originally raised via. + * @param {MouseEvent|TouchEvent} event - MouseEvent or TouchEvent that was originally raised. + * @param {ElementComponent} element - The ElementComponent that this event was originally + * raised on. + * @param {CameraComponent} camera - The CameraComponent that this event was originally raised + * via. */ constructor(event, element, camera) { /** * MouseEvent or TouchEvent that was originally raised. * - * @type {import('../../platform/input/mouse-event.js').MouseEvent - * |import('../../platform/input/touch-event.js').TouchEvent} + * @type {MouseEvent|TouchEvent} */ this.event = event; /** * The ElementComponent that this event was originally raised on. * - * @type {import('../components/element/component.js').ElementComponent} + * @type {ElementComponent} */ this.element = element; /** * The CameraComponent that this event was originally raised via. * - * @type {import('../components/camera/component.js').CameraComponent} + * @type {CameraComponent} */ this.camera = camera; @@ -172,11 +176,11 @@ class ElementMouseEvent extends ElementInputEvent { /** * Create an instance of an ElementMouseEvent. * - * @param {import('../../platform/input/mouse-event.js').MouseEvent} event - The MouseEvent that + * @param {MouseEvent} event - The MouseEvent that * was originally raised. - * @param {import('../components/element/component.js').ElementComponent} element - The + * @param {ElementComponent} element - The * ElementComponent that this event was originally raised on. - * @param {import('../components/camera/component.js').CameraComponent} camera - The + * @param {CameraComponent} camera - The * CameraComponent that this event was originally raised via. * @param {number} x - The x coordinate. * @param {number} y - The y coordinate. @@ -267,14 +271,14 @@ class ElementTouchEvent extends ElementInputEvent { /** * Create an instance of an ElementTouchEvent. * - * @param {import('../../platform/input/touch-event.js').TouchEvent} event - The TouchEvent that was originally raised. - * @param {import('../components/element/component.js').ElementComponent} element - The + * @param {TouchEvent} event - The TouchEvent that was originally raised. + * @param {ElementComponent} element - The * ElementComponent that this event was originally raised on. - * @param {import('../components/camera/component.js').CameraComponent} camera - The + * @param {CameraComponent} camera - The * CameraComponent that this event was originally raised via. * @param {number} x - The x coordinate of the touch that triggered the event. * @param {number} y - The y coordinate of the touch that triggered the event. - * @param {import('../../platform/input/touch-event.js').Touch} touch - The touch object that triggered the event. + * @param {Touch} touch - The touch object that triggered the event. */ constructor(event, element, camera, x, y, touch) { super(event, element, camera); @@ -283,14 +287,14 @@ class ElementTouchEvent extends ElementInputEvent { * The Touch objects representing all current points of contact with the surface, * regardless of target or changed status. * - * @type {import('../../platform/input/touch-event.js').Touch[]} + * @type {Touch[]} */ this.touches = event.touches; /** * The Touch objects representing individual points of contact whose states changed between * the previous touch event and this one. * - * @type {import('../../platform/input/touch-event.js').Touch[]} + * @type {Touch[]} */ this.changedTouches = event.changedTouches; this.x = x; @@ -298,7 +302,7 @@ class ElementTouchEvent extends ElementInputEvent { /** * The touch object that triggered the event. * - * @type {import('../../platform/input/touch-event.js').Touch} + * @type {Touch} */ this.touch = touch; } @@ -314,11 +318,11 @@ class ElementSelectEvent extends ElementInputEvent { * Create an instance of a ElementSelectEvent. * * @param {XRInputSourceEvent} event - The XRInputSourceEvent that was originally raised. - * @param {import('../components/element/component.js').ElementComponent} element - The + * @param {ElementComponent} element - The * ElementComponent that this event was originally raised on. - * @param {import('../components/camera/component.js').CameraComponent} camera - The + * @param {CameraComponent} camera - The * CameraComponent that this event was originally raised via. - * @param {import('../xr/xr-input-source.js').XrInputSource} inputSource - The XR input source + * @param {XrInputSource} inputSource - The XR input source * that this event was originally raised from. */ constructor(event, element, camera, inputSource) { @@ -327,7 +331,7 @@ class ElementSelectEvent extends ElementInputEvent { /** * The XR input source that this event was originally raised from. * - * @type {import('../xr/xr-input-source.js').XrInputSource} + * @type {XrInputSource} */ this.inputSource = inputSource; } @@ -488,7 +492,7 @@ class ElementInput { * Add a {@link ElementComponent} to the internal list of ElementComponents that are being * checked for input. * - * @param {import('../components/element/component.js').ElementComponent} element - The + * @param {ElementComponent} element - The * ElementComponent. */ addElement(element) { @@ -500,7 +504,7 @@ class ElementInput { * Remove a {@link ElementComponent} from the internal list of ElementComponents that are being * checked for input. * - * @param {import('../components/element/component.js').ElementComponent} element - The + * @param {ElementComponent} element - The * ElementComponent. */ removeElement(element) { diff --git a/src/framework/lightmapper/lightmapper.js b/src/framework/lightmapper/lightmapper.js index 44b25b044f3..f82118010a4 100644 --- a/src/framework/lightmapper/lightmapper.js +++ b/src/framework/lightmapper/lightmapper.js @@ -4,7 +4,6 @@ import { Color } from '../../core/math/color.js'; import { math } from '../../core/math/math.js'; import { Vec3 } from '../../core/math/vec3.js'; import { BoundingBox } from '../../core/shape/bounding-box.js'; - import { ADDRESS_CLAMP_TO_EDGE, CHUNKAPI_1_65, @@ -18,13 +17,6 @@ import { DebugGraphics } from '../../platform/graphics/debug-graphics.js'; import { RenderTarget } from '../../platform/graphics/render-target.js'; import { drawQuadWithShader } from '../../scene/graphics/quad-render-utils.js'; import { Texture } from '../../platform/graphics/texture.js'; - -import { MeshInstance } from '../../scene/mesh-instance.js'; -import { LightingParams } from '../../scene/lighting/lighting-params.js'; -import { WorldClusters } from '../../scene/lighting/world-clusters.js'; -import { shaderChunks } from '../../scene/shader-lib/chunks/chunks.js'; -import { shaderChunksLightmapper } from '../../scene/shader-lib/chunks/chunks-lightmapper.js'; - import { BAKE_COLORDIR, FOG_NONE, GAMMA_NONE, TONEMAP_LINEAR, @@ -35,10 +27,15 @@ import { SHADOWUPDATE_REALTIME, SHADOWUPDATE_THISFRAME, SHADER_FORWARD } from '../../scene/constants.js'; +import { MeshInstance } from '../../scene/mesh-instance.js'; +import { LightingParams } from '../../scene/lighting/lighting-params.js'; +import { WorldClusters } from '../../scene/lighting/world-clusters.js'; +import { RenderingParams } from '../../scene/renderer/rendering-params.js'; +import { shaderChunks } from '../../scene/shader-lib/chunks/chunks.js'; +import { shaderChunksLightmapper } from '../../scene/shader-lib/chunks/chunks-lightmapper.js'; import { Camera } from '../../scene/camera.js'; import { GraphNode } from '../../scene/graph-node.js'; import { StandardMaterial } from '../../scene/materials/standard-material.js'; - import { BakeLightSimple } from './bake-light-simple.js'; import { BakeLightAmbient } from './bake-light-ambient.js'; import { BakeMeshNode } from './bake-mesh-node.js'; @@ -47,7 +44,14 @@ import { LightmapFilters } from './lightmap-filters.js'; import { BlendState } from '../../platform/graphics/blend-state.js'; import { DepthState } from '../../platform/graphics/depth-state.js'; import { RenderPassLightmapper } from './render-pass-lightmapper.js'; -import { RenderingParams } from '../../scene/renderer/rendering-params.js'; + +/** + * @import { AssetRegistry } from '../asset/asset-registry.js' + * @import { Entity } from '../entity.js' + * @import { ForwardRenderer } from '../../scene/renderer/forward-renderer.js' + * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js' + * @import { Scene } from '../../scene/scene.js' + */ const MAX_LIGHTMAP_SIZE = 2048; @@ -65,14 +69,11 @@ class Lightmapper { /** * Create a new Lightmapper instance. * - * @param {import('../../platform/graphics/graphics-device.js').GraphicsDevice} device - The - * graphics device used by the lightmapper. - * @param {import('../entity.js').Entity} root - The root entity of the scene. - * @param {import('../../scene/scene.js').Scene} scene - The scene to lightmap. - * @param {import('../../scene/renderer/forward-renderer.js').ForwardRenderer} renderer - The - * renderer. - * @param {import('../asset/asset-registry.js').AssetRegistry} assets - Registry of assets to - * lightmap. + * @param {GraphicsDevice} device - The graphics device used by the lightmapper. + * @param {Entity} root - The root entity of the scene. + * @param {Scene} scene - The scene to lightmap. + * @param {ForwardRenderer} renderer - The renderer. + * @param {AssetRegistry} assets - Registry of assets to lightmap. * @ignore */ constructor(device, root, scene, renderer, assets) { @@ -509,8 +510,8 @@ class Lightmapper { /** * Generates and applies the lightmaps. * - * @param {import('../entity.js').Entity[]|null} nodes - An array of entities (with model or - * render components) to render lightmaps for. If not supplied, the entire scene will be baked. + * @param {Entity[]|null} nodes - An array of entities (with model or render components) to + * render lightmaps for. If not supplied, the entire scene will be baked. * @param {number} [mode] - Baking mode. Can be: * * - {@link BAKE_COLOR}: single color lightmap diff --git a/src/framework/lightmapper/render-pass-lightmapper.js b/src/framework/lightmapper/render-pass-lightmapper.js index 8c7dac98178..692e84f9a18 100644 --- a/src/framework/lightmapper/render-pass-lightmapper.js +++ b/src/framework/lightmapper/render-pass-lightmapper.js @@ -2,11 +2,15 @@ import { DebugGraphics } from '../../platform/graphics/debug-graphics.js'; import { RenderPass } from '../../platform/graphics/render-pass.js'; import { SHADER_FORWARD } from '../../scene/constants.js'; +/** + * @import { BindGroup } from '../../platform/graphics/bind-group.js' + */ + /** * A render pass implementing rendering of mesh instance receivers for light-mapper. */ class RenderPassLightmapper extends RenderPass { - /** @type {import('../../platform/graphics/bind-group.js').BindGroup[]} */ + /** @type {BindGroup[]} */ viewBindGroups = []; constructor(device, renderer, camera, worldClusters, receivers, lightArray) { diff --git a/src/framework/parsers/glb-parser.js b/src/framework/parsers/glb-parser.js index b6ce7ebbf6d..af2aaec5c8a 100644 --- a/src/framework/parsers/glb-parser.js +++ b/src/framework/parsers/glb-parser.js @@ -1194,10 +1194,8 @@ const createMaterial = (gltfMaterial, textures) => { color = gltfMaterial.emissiveFactor; // Convert from linear space to sRGB space material.emissive.set(Math.pow(color[0], 1 / 2.2), Math.pow(color[1], 1 / 2.2), Math.pow(color[2], 1 / 2.2)); - material.emissiveTint = true; } else { material.emissive.set(0, 0, 0); - material.emissiveTint = false; } if (gltfMaterial.hasOwnProperty('emissiveTexture')) { diff --git a/src/framework/parsers/gsplat-resource.js b/src/framework/parsers/gsplat-resource.js index c91b249cdde..5aa37192e1f 100644 --- a/src/framework/parsers/gsplat-resource.js +++ b/src/framework/parsers/gsplat-resource.js @@ -3,6 +3,12 @@ import { GSplatInstance } from '../../scene/gsplat/gsplat-instance.js'; import { GSplat } from '../../scene/gsplat/gsplat.js'; import { GSplatCompressed } from '../../scene/gsplat/gsplat-compressed.js'; +/** + * @import { GSplatData } from '../../scene/gsplat/gsplat-data.js' + * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js' + * @import { SplatMaterialOptions } from '../../scene/gsplat/gsplat-material.js' + */ + /** * The resource for the gsplat asset type. * @@ -10,13 +16,13 @@ import { GSplatCompressed } from '../../scene/gsplat/gsplat-compressed.js'; */ class GSplatResource { /** - * @type {import('../../platform/graphics/graphics-device.js').GraphicsDevice} + * @type {GraphicsDevice} * @ignore */ device; /** - * @type {import('../../scene/gsplat/gsplat-data.js').GSplatData} + * @type {GSplatData} * @ignore */ splatData; @@ -28,8 +34,8 @@ class GSplatResource { splat = null; /** - * @param {import('../../platform/graphics/graphics-device.js').GraphicsDevice} device - The graphics device. - * @param {import('../../scene/gsplat/gsplat-data.js').GSplatData} splatData - The splat data. + * @param {GraphicsDevice} device - The graphics device. + * @param {GSplatData} splatData - The splat data. * @ignore */ constructor(device, splatData) { @@ -54,7 +60,7 @@ class GSplatResource { /** * Instantiates an entity with a {@link GSplatComponent}. * - * @param {import('../../scene/gsplat/gsplat-material.js').SplatMaterialOptions} [options] - The options. + * @param {SplatMaterialOptions} [options] - The options. * @returns {Entity} The entity with {@link GSplatComponent}. */ instantiate(options = {}) { diff --git a/src/framework/parsers/material/json-standard-material.js b/src/framework/parsers/material/json-standard-material.js index 5585293ebd1..bdbbd2203bb 100644 --- a/src/framework/parsers/material/json-standard-material.js +++ b/src/framework/parsers/material/json-standard-material.js @@ -120,7 +120,6 @@ class JsonStandardMaterialParser { ['lightMapVertexColor', 'lightVertexColor'], ['specularMapTint', 'specularTint'], - ['emissiveMapTint', 'emissiveTint'], ['metalnessMapTint', 'metalnessTint'], ['clearCoatGlossiness', 'clearCoatGloss'] diff --git a/src/framework/parsers/ply.js b/src/framework/parsers/ply.js index 0dccf4c5f06..862ae04d944 100644 --- a/src/framework/parsers/ply.js +++ b/src/framework/parsers/ply.js @@ -3,6 +3,13 @@ import { GSplatCompressedData } from '../../scene/gsplat/gsplat-compressed-data. import { GSplatResource } from './gsplat-resource.js'; import { Mat4 } from '../../core/math/mat4.js'; +/** + * @import { AssetRegistry } from '../asset/asset-registry.js' + * @import { Asset } from '../asset/asset.js' + * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js' + * @import { ResourceHandlerCallback } from '../handlers/handler.js' + */ + /** * @typedef {Int8Array|Uint8Array|Int16Array|Uint16Array|Int32Array|Uint32Array|Float32Array|Float64Array} DataType */ @@ -470,18 +477,18 @@ const defaultElementFilter = val => defaultElementsSet.has(val); const mat4 = new Mat4(); class PlyParser { - /** @type {import('../../platform/graphics/graphics-device.js').GraphicsDevice} */ + /** @type {GraphicsDevice} */ device; - /** @type {import('../asset/asset-registry.js').AssetRegistry} */ + /** @type {AssetRegistry} */ assets; /** @type {number} */ maxRetries; /** - * @param {import('../../platform/graphics/graphics-device.js').GraphicsDevice} device - The graphics device. - * @param {import('../asset/asset-registry.js').AssetRegistry} assets - The asset registry. + * @param {GraphicsDevice} device - The graphics device. + * @param {AssetRegistry} assets - The asset registry. * @param {number} maxRetries - Maximum amount of retries. */ constructor(device, assets, maxRetries) { @@ -494,9 +501,9 @@ class PlyParser { * @param {object} url - The URL of the resource to load. * @param {string} url.load - The URL to use for loading the resource. * @param {string} url.original - The original URL useful for identifying the resource type. - * @param {import('../handlers/handler.js').ResourceHandlerCallback} callback - The callback used when + * @param {ResourceHandlerCallback} callback - The callback used when * the resource is loaded or an error occurs. - * @param {import('../asset/asset.js').Asset} asset - Container asset. + * @param {Asset} asset - Container asset. */ async load(url, callback, asset) { const response = await fetch(url.load); diff --git a/src/framework/parsers/texture/texture.js b/src/framework/parsers/texture/texture.js index 5d7b2df0439..f8938a02c39 100644 --- a/src/framework/parsers/texture/texture.js +++ b/src/framework/parsers/texture/texture.js @@ -1,21 +1,27 @@ /** - * Interface to a texture parser. Implementations of this interface handle the loading - * and opening of texture assets. + * @import { Asset } from '../../asset/asset.js' + * @import { GraphicsDevice } from '../../../platform/graphics/graphics-device.js' + * @import { ResourceHandlerCallback } from '../../../framework/handlers/handler.js' + * @import { Texture } from '../../../platform/graphics/texture.js' + */ + +/** + * Interface to a texture parser. Implementations of this interface handle the loading and opening + * of texture assets. */ class TextureParser { /* eslint-disable jsdoc/require-returns-check */ /** * @function * @name TextureParser#load - * @description Load the texture from the remote URL. When loaded (or failed), - * use the callback to return an the raw resource data (or error). + * @description Load the texture from the remote URL. When loaded (or failed), use the callback + * to return an the raw resource data (or error). * @param {object} url - The URL of the resource to load. * @param {string} url.load - The URL to use for loading the resource. * @param {string} url.original - The original URL useful for identifying the resource type. - * @param {import('../../../framework/handlers/handler.js').ResourceHandlerCallback} callback - The callback used when - * the resource is loaded or an error occurs. - * @param {import('../../asset/asset.js').Asset} [asset] - Optional asset that is passed by - * ResourceLoader. + * @param {ResourceHandlerCallback} callback - The callback used when the resource is loaded or + * an error occurs. + * @param {Asset} [asset] - Optional asset that is passed by ResourceLoader. */ load(url, callback, asset) { throw new Error('not implemented'); @@ -28,9 +34,8 @@ class TextureParser { * JSON and return a {@link Model}. * @param {string} url - The URL of the resource to open. * @param {*} data - The raw resource data passed by callback from {@link ResourceHandler#load}. - * @param {import('../../../platform/graphics/graphics-device.js').GraphicsDevice} device - The - * graphics device. - * @returns {import('../../../platform/graphics/texture.js').Texture} The parsed resource data. + * @param {GraphicsDevice} device - The graphics device. + * @returns {Texture} The parsed resource data. */ open(url, data, device) { throw new Error('not implemented'); diff --git a/src/framework/scene-registry.js b/src/framework/scene-registry.js index 03c4d15d5ad..23a5acc2d3d 100644 --- a/src/framework/scene-registry.js +++ b/src/framework/scene-registry.js @@ -1,16 +1,19 @@ import { path } from '../core/path.js'; import { Debug } from '../core/debug.js'; - import { ABSOLUTE_URL } from './asset/constants.js'; - import { SceneRegistryItem } from './scene-registry-item.js'; +/** + * @import { AppBase } from './app-base.js' + * @import { Entity } from './entity.js' + */ + /** * Callback used by {@link SceneRegistry#loadSceneHierarchy}. * * @callback LoadHierarchyCallback * @param {string|null} err - The error message in the case where the loading or parsing fails. - * @param {import('./entity.js').Entity} [entity] - The loaded root entity if no errors were encountered. + * @param {Entity} [entity] - The loaded root entity if no errors were encountered. */ /** @@ -25,7 +28,7 @@ import { SceneRegistryItem } from './scene-registry-item.js'; * * @callback ChangeSceneCallback * @param {string|null} err - The error message in the case where the loading or parsing fails. - * @param {import('./entity.js').Entity} [entity] - The loaded root entity if no errors were encountered. + * @param {Entity} [entity] - The loaded root entity if no errors were encountered. */ /** @@ -33,7 +36,7 @@ import { SceneRegistryItem } from './scene-registry-item.js'; * * @callback LoadSceneCallback * @param {string|null} err - The error message in the case where the loading or parsing fails. - * @param {import('./entity.js').Entity} [entity] - The loaded root entity if no errors were encountered. + * @param {Entity} [entity] - The loaded root entity if no errors were encountered. */ /** @@ -52,7 +55,7 @@ import { SceneRegistryItem } from './scene-registry-item.js'; */ class SceneRegistry { /** - * @type {import('./app-base.js').AppBase} + * @type {AppBase} * @private */ _app; @@ -72,7 +75,7 @@ class SceneRegistry { /** * Create a new SceneRegistry instance. * - * @param {import('./app-base.js').AppBase} app - The application. + * @param {AppBase} app - The application. */ constructor(app) { this._app = app; diff --git a/src/framework/script.js b/src/framework/script.js index 488e49e231c..a3dbee6ec59 100644 --- a/src/framework/script.js +++ b/src/framework/script.js @@ -1,17 +1,21 @@ import { getApplication } from './globals.js'; +/** + * @import { AppBase } from './app-base.js' + */ + /** * Callback used by {@link script.createLoadingScreen}. * * @callback CreateScreenCallback - * @param {import('./app-base.js').AppBase} app - The application. + * @param {AppBase} app - The application. */ /** * Callback used by {@link script.create}. * * @callback CreateScriptCallback - * @param {import('./app-base.js').AppBase} app - The application. + * @param {AppBase} app - The application. * @returns {object} Return the Type of the script resource to be instanced for each Entity. * @ignore */ diff --git a/src/framework/script/script-attributes.js b/src/framework/script/script-attributes.js index 89d971242a9..45967d84c1e 100644 --- a/src/framework/script/script-attributes.js +++ b/src/framework/script/script-attributes.js @@ -8,6 +8,12 @@ import { Vec4 } from '../../core/math/vec4.js'; import { GraphNode } from '../../scene/graph-node.js'; import { Asset } from '../asset/asset.js'; +/** + * @import { Application } from '../../framework/application.js' + * @import { ScriptType } from './script-type.js' + * @import { Script } from '../../framework/script/script.js' + */ + const components = ['x', 'y', 'z', 'w']; const vecLookup = [undefined, undefined, Vec2, Vec3, Vec4]; @@ -155,7 +161,7 @@ function rawToValue(app, args, value, old) { /** * Takes an attribute schema, a value and current value, and return a new value. * - * @param {import('../../framework/application.js').Application} app - The working application + * @param {Application} app - The working application * @param {AttributeSchema} schema - The attribute schema used to resolve properties * @param {*} value - The raw value to create * @param {*} current - The existing value @@ -173,10 +179,10 @@ function attributeToValue(app, schema, value, current) { * Assigns values to a script instance based on a map of attributes schemas * and a corresponding map of data. * - * @param {import('../../framework/application.js').Application} app - The application instance + * @param {Application} app - The application instance * @param {Object} attributeSchemaMap - A map of names to Schemas * @param {Object} data - A Map of data to assign to the Script instance - * @param {import('../../framework/script/script.js').Script} script - A Script instance to assign values on + * @param {Script} script - A Script instance to assign values on */ export function assignAttributesToScript(app, attributeSchemaMap, data, script) { @@ -210,7 +216,7 @@ class ScriptAttributes { /** * Create a new ScriptAttributes instance. * - * @param {typeof import('./script-type.js').ScriptType} scriptType - Script Type that attributes relate to. + * @param {typeof ScriptType} scriptType - Script Type that attributes relate to. */ constructor(scriptType) { this.scriptType = scriptType; diff --git a/src/framework/script/script-registry.js b/src/framework/script/script-registry.js index 752151f2fd0..2279953d696 100644 --- a/src/framework/script/script-registry.js +++ b/src/framework/script/script-registry.js @@ -1,5 +1,11 @@ import { EventHandler } from '../../core/event-handler.js'; +/** + * @import { AppBase } from '../app-base.js' + * @import { AttributeSchema } from './script-attributes.js' + * @import { ScriptType } from './script-type.js' + */ + /** * Container for all {@link ScriptType}s that are available to this application. Note that * PlayCanvas scripts can access the Script Registry from inside the application with @@ -9,13 +15,13 @@ import { EventHandler } from '../../core/event-handler.js'; */ class ScriptRegistry extends EventHandler { /** - * @type {Object} + * @type {Object} * @private */ _scripts = {}; /** - * @type {typeof import('./script-type.js').ScriptType[]} + * @type {typeof ScriptType[]} * @private */ _list = []; @@ -23,7 +29,7 @@ class ScriptRegistry extends EventHandler { /** * A Map of script names to attribute schemas. * - * @type {Map} + * @type {Map} * @private */ _scriptSchemas = new Map(); @@ -31,7 +37,7 @@ class ScriptRegistry extends EventHandler { /** * Create a new ScriptRegistry instance. * - * @param {import('../app-base.js').AppBase} app - Application to attach registry to. + * @param {AppBase} app - Application to attach registry to. */ constructor(app) { super(); @@ -48,7 +54,7 @@ class ScriptRegistry extends EventHandler { * Registers a schema against a script instance. * * @param {string} id - The key to use to store the schema - * @param {import('./script-attributes.js').AttributeSchema} schema - An schema definition for the script + * @param {AttributeSchema} schema - An schema definition for the script */ addSchema(id, schema) { if (!schema) return; @@ -59,7 +65,7 @@ class ScriptRegistry extends EventHandler { * Returns a schema for a given script name. * * @param {string} id - The key to store the schema under - * @returns {import('./script-attributes.js').AttributeSchema | undefined} - The schema stored under the key + * @returns {AttributeSchema | undefined} - The schema stored under the key */ getSchema(id) { return this._scriptSchemas.get(id); @@ -71,7 +77,7 @@ class ScriptRegistry extends EventHandler { * registry, and the new script has a `swap` method defined, it will perform code hot swapping * automatically in async manner. * - * @param {typeof import('./script-type.js').ScriptType} script - Script Type that is created + * @param {typeof ScriptType} script - Script Type that is created * using {@link createScript}. * @returns {boolean} True if added for the first time or false if script already exists. * @example @@ -178,7 +184,7 @@ class ScriptRegistry extends EventHandler { /** * Remove {@link ScriptType}. * - * @param {string|typeof import('./script-type.js').ScriptType} nameOrType - The name or type + * @param {string|typeof ScriptType} nameOrType - The name or type * of {@link ScriptType}. * @returns {boolean} True if removed or False if already not in registry. * @example @@ -211,7 +217,7 @@ class ScriptRegistry extends EventHandler { * Get {@link ScriptType} by name. * * @param {string} name - Name of a {@link ScriptType}. - * @returns {typeof import('./script-type.js').ScriptType} The Script Type if it exists in the + * @returns {typeof ScriptType} The Script Type if it exists in the * registry or null otherwise. * @example * var PlayerController = app.scripts.get('playerController'); @@ -223,7 +229,7 @@ class ScriptRegistry extends EventHandler { /** * Check if a {@link ScriptType} with the specified name is in the registry. * - * @param {string|typeof import('./script-type.js').ScriptType} nameOrType - The name or type + * @param {string|typeof ScriptType} nameOrType - The name or type * of {@link ScriptType}. * @returns {boolean} True if {@link ScriptType} is in registry. * @example @@ -244,7 +250,7 @@ class ScriptRegistry extends EventHandler { /** * Get list of all {@link ScriptType}s from registry. * - * @returns {Array} list of all {@link ScriptType}s + * @returns {Array} list of all {@link ScriptType}s * in registry. * @example * // logs array of all Script Type names available in registry diff --git a/src/framework/script/script.js b/src/framework/script/script.js index 3bc0f58a42a..3e7bdb45502 100644 --- a/src/framework/script/script.js +++ b/src/framework/script/script.js @@ -2,12 +2,18 @@ import { Debug } from '../..//core/debug.js'; import { EventHandler } from '../../core/event-handler.js'; import { SCRIPT_INITIALIZE, SCRIPT_POST_INITIALIZE } from './constants.js'; +/** + * @import { AppBase } from '../app-base.js' + * @import { Entity } from '../entity.js' + */ + /** * The `Script` class is the fundamental base class for all scripts within PlayCanvas. It provides * the minimal interface required for a script to be compatible with both the Engine and the * Editor. * - * At its core, a script is simply a collection of methods that are called at various points in the Engine's lifecycle. These methods are: + * At its core, a script is simply a collection of methods that are called at various points in the + * Engine's lifecycle. These methods are: * * {@link Script#initialize} - Called once when the script is initialized * {@link Script#postInitialize} - Called once after all scripts have been initialized @@ -15,7 +21,8 @@ import { SCRIPT_INITIALIZE, SCRIPT_POST_INITIALIZE } from './constants.js'; * {@link Script#postUpdate} - Called every frame, after all scripts have been updated * {@link Script#swap} - Called when a script is redefined * - * These methods are entirely optional, but provide a useful way to manage the lifecycle of a script and perform any necessary setup and cleanup. + * These methods are entirely optional, but provide a useful way to manage the lifecycle of a + * script and perform any necessary setup and cleanup. * * Below is a simple example of a script that rotates an entity every frame. * @example @@ -27,7 +34,8 @@ import { SCRIPT_INITIALIZE, SCRIPT_POST_INITIALIZE } from './constants.js'; * } * ``` * - * When this script is attached to an entity, the update will be called every frame, slowly rotating the entity around the Y-axis. + * When this script is attached to an entity, the update will be called every frame, slowly + * rotating the entity around the Y-axis. * * For more information on how to create scripts, see the [Scripting Overview](https://developer.playcanvas.com/user-manual/scripting/). * @@ -97,7 +105,8 @@ export class Script extends EventHandler { static EVENT_DESTROY = 'destroy'; /** - * Fired when script attributes have changed. This event is available in two forms. They are as follows: + * Fired when script attributes have changed. This event is available in two forms. They are as + * follows: * * 1. `attr` - Fired for any attribute change. The handler is passed the name of the attribute * that changed, the value of the attribute before the change and the value of the attribute @@ -146,14 +155,14 @@ export class Script extends EventHandler { /** * The {@link AppBase} that the instance of this type belongs to. * - * @type {import('../app-base.js').AppBase} + * @type {AppBase} */ app; /** * The {@link Entity} that the instance of this type belongs to. * - * @type {import('../entity.js').Entity} + * @type {Entity} */ entity; @@ -188,10 +197,8 @@ export class Script extends EventHandler { * Create a new Script instance. * * @param {object} args - The input arguments object. - * @param {import('../app-base.js').AppBase} args.app - The {@link AppBase} that is running the - * script. - * @param {import('../entity.js').Entity} args.entity - The {@link Entity} that the script is - * attached to. + * @param {AppBase} args.app - The {@link AppBase} that is running the script. + * @param {Entity} args.entity - The {@link Entity} that the script is attached to. */ constructor(args) { super(); @@ -246,8 +253,8 @@ export class Script extends EventHandler { /** * @typedef {object} ScriptInitializationArgs * @property {boolean} [enabled] - True if the script instance is in running state. - * @property {import('../app-base.js').AppBase} app - The {@link AppBase} that is running the script. - * @property {import('../entity.js').Entity} entity - The {@link Entity} that the script is attached to. + * @property {AppBase} app - The {@link AppBase} that is running the script. + * @property {Entity} entity - The {@link Entity} that the script is attached to. */ /** diff --git a/src/framework/stats.js b/src/framework/stats.js index 51d1527433a..f741678dd52 100644 --- a/src/framework/stats.js +++ b/src/framework/stats.js @@ -1,5 +1,9 @@ import { getApplication } from './globals.js'; +/** + * @import { GraphicsDevice } from '../platform/graphics/graphics-device.js' + */ + /** * Records performance-related statistics related to the application. */ @@ -7,7 +11,7 @@ class ApplicationStats { /** * Create a new ApplicationStats instance. * - * @param {import('../platform/graphics/graphics-device.js').GraphicsDevice} device - The + * @param {GraphicsDevice} device - The * graphics device. */ constructor(device) { diff --git a/src/framework/template.js b/src/framework/template.js index dc96ef2eeb0..4af2ef95d4a 100644 --- a/src/framework/template.js +++ b/src/framework/template.js @@ -1,11 +1,16 @@ import { SceneParser } from './parsers/scene.js'; +/** + * @import { AppBase } from './app-base.js' + * @import { Entity } from './entity.js' + */ + /** * Create a Template resource from raw database data. */ class Template { /** - * @type {import('./app-base.js').AppBase} + * @type {AppBase} * @private */ _app; @@ -14,7 +19,7 @@ class Template { _data; /** - * @type {import('./entity.js').Entity|null} + * @type {Entity|null} * @private */ _templateRoot = null; @@ -22,7 +27,7 @@ class Template { /** * Create a new Template instance. * - * @param {import('./app-base.js').AppBase} app - The application. + * @param {AppBase} app - The application. * @param {object} data - Asset data from the database. */ constructor(app, data) { @@ -33,7 +38,7 @@ class Template { /** * Create an instance of this template. * - * @returns {import('./entity.js').Entity} The root entity of the created instance. + * @returns {Entity} The root entity of the created instance. */ instantiate() { if (!this._templateRoot) { // at first use, after scripts are loaded diff --git a/src/framework/xr/xr-anchor.js b/src/framework/xr/xr-anchor.js index 2c16f31ffc7..1322a0577b3 100644 --- a/src/framework/xr/xr-anchor.js +++ b/src/framework/xr/xr-anchor.js @@ -1,8 +1,11 @@ import { EventHandler } from '../../core/event-handler.js'; - import { Vec3 } from '../../core/math/vec3.js'; import { Quat } from '../../core/math/quat.js'; +/** + * @import { XrAnchors } from './xr-anchors.js' + */ + /** * Callback used by {@link XrAnchor#persist}. * @@ -102,7 +105,7 @@ class XrAnchor extends EventHandler { _uuidRequests = null; /** - * @param {import('./xr-anchors.js').XrAnchors} anchors - Anchor manager. + * @param {XrAnchors} anchors - Anchor manager. * @param {object} xrAnchor - Native XRAnchor object that is provided by WebXR API. * @param {string|null} uuid - ID string associated with a persistent anchor. * @ignore diff --git a/src/framework/xr/xr-anchors.js b/src/framework/xr/xr-anchors.js index ba3a035481a..bd7d8ccb45b 100644 --- a/src/framework/xr/xr-anchors.js +++ b/src/framework/xr/xr-anchors.js @@ -2,6 +2,13 @@ import { EventHandler } from '../../core/event-handler.js'; import { platform } from '../../core/platform.js'; import { XrAnchor } from './xr-anchor.js'; +/** + * @import { Quat } from '../../core/math/quat.js' + * @import { Vec3 } from '../../core/math/vec3.js' + * @import { XrAnchorForgetCallback } from './xr-anchor.js' + * @import { XrManager } from './xr-manager.js' + */ + /** * Callback used by {@link XrAnchors#create}. * @@ -84,7 +91,7 @@ class XrAnchors extends EventHandler { static EVENT_DESTROY = 'destroy'; /** - * @type {import('./xr-manager.js').XrManager} + * @type {XrManager} * @ignore */ manager; @@ -144,8 +151,8 @@ class XrAnchors extends EventHandler { _list = []; /** - * Map of callbacks to XRAnchors so that we can call its callback once - * an anchor is updated with a pose for the first time. + * Map of callbacks to XRAnchors so that we can call its callback once an anchor is updated + * with a pose for the first time. * * @type {Map} * @private @@ -153,7 +160,7 @@ class XrAnchors extends EventHandler { _callbacksAnchors = new Map(); /** - * @param {import('./xr-manager.js').XrManager} manager - WebXR Manager. + * @param {XrManager} manager - WebXR Manager. * @ignore */ constructor(manager) { @@ -233,12 +240,11 @@ class XrAnchors extends EventHandler { /** * Create an anchor using position and rotation, or from hit test result. * - * @param {import('../../core/math/vec3.js').Vec3|XRHitTestResult} position - Position for an anchor or - * a hit test result. - * @param {import('../../core/math/quat.js').Quat|XrAnchorCreateCallback} [rotation] - Rotation for an - * anchor or a callback if creating from a hit test result. - * @param {XrAnchorCreateCallback} [callback] - Callback to fire when anchor was created or failed to be - * created. + * @param {Vec3|XRHitTestResult} position - Position for an anchor or a hit test result. + * @param {Quat|XrAnchorCreateCallback} [rotation] - Rotation for an anchor or a callback if + * creating from a hit test result. + * @param {XrAnchorCreateCallback} [callback] - Callback to fire when anchor was created or + * failed to be created. * @example * // create an anchor using a position and rotation * app.xr.anchors.create(position, rotation, function (err, anchor) { @@ -299,7 +305,8 @@ class XrAnchors extends EventHandler { * Restore anchor using persistent UUID. * * @param {string} uuid - UUID string associated with persistent anchor. - * @param {XrAnchorCreateCallback} [callback] - Callback to fire when anchor was created or failed to be created. + * @param {XrAnchorCreateCallback} [callback] - Callback to fire when anchor was created or + * failed to be created. * @example * // restore an anchor using uuid string * app.xr.anchors.restore(uuid, function (err, anchor) { @@ -346,8 +353,8 @@ class XrAnchors extends EventHandler { * Forget an anchor by removing its UUID from underlying systems. * * @param {string} uuid - UUID string associated with persistent anchor. - * @param {import('./xr-anchor.js').XrAnchorForgetCallback} [callback] - Callback to - * fire when anchor persistent data was removed or error if failed. + * @param {XrAnchorForgetCallback} [callback] - Callback to fire when anchor persistent data + * was removed or error if failed. * @example * // forget all available anchors * const uuids = app.xr.anchors.uuids; diff --git a/src/framework/xr/xr-dom-overlay.js b/src/framework/xr/xr-dom-overlay.js index 8d3e1757c9a..d7948d49ad6 100644 --- a/src/framework/xr/xr-dom-overlay.js +++ b/src/framework/xr/xr-dom-overlay.js @@ -1,5 +1,9 @@ import { platform } from '../../core/platform.js'; +/** + * @import { XrManager } from './xr-manager.js' + */ + /** * DOM Overlay provides the ability to use DOM elements as an overlay in a WebXR AR session. It * requires that the root DOM element is provided for session start. That way, input source select @@ -25,7 +29,7 @@ import { platform } from '../../core/platform.js'; */ class XrDomOverlay { /** - * @type {import('./xr-manager.js').XrManager} + * @type {XrManager} * @private */ _manager; @@ -45,7 +49,7 @@ class XrDomOverlay { /** * Create a new XrDomOverlay instance. * - * @param {import('./xr-manager.js').XrManager} manager - WebXR Manager. + * @param {XrManager} manager - WebXR Manager. * @ignore */ constructor(manager) { diff --git a/src/framework/xr/xr-finger.js b/src/framework/xr/xr-finger.js index bc05a978eab..73cd407c45a 100644 --- a/src/framework/xr/xr-finger.js +++ b/src/framework/xr/xr-finger.js @@ -1,3 +1,8 @@ +/** + * @import { XrHand } from './xr-hand.js' + * @import { XrJoint } from './xr-joint.js' + */ + /** * Represents finger with related joints and index. * @@ -11,19 +16,19 @@ class XrFinger { _index; /** - * @type {import('./xr-hand.js').XrHand} + * @type {XrHand} * @private */ _hand; /** - * @type {import('./xr-joint.js').XrJoint[]} + * @type {XrJoint[]} * @private */ _joints = []; /** - * @type {import('./xr-joint.js').XrJoint|null} + * @type {XrJoint|null} * @private */ _tip = null; @@ -32,7 +37,7 @@ class XrFinger { * Create a new XrFinger instance. * * @param {number} index - Index of a finger. - * @param {import('./xr-hand.js').XrHand} hand - Hand that finger relates to. + * @param {XrHand} hand - Hand that finger relates to. * @ignore */ constructor(index, hand) { @@ -53,7 +58,7 @@ class XrFinger { /** * Hand that finger relates to. * - * @type {import('./xr-hand.js').XrHand} + * @type {XrHand} */ get hand() { return this._hand; @@ -63,7 +68,7 @@ class XrFinger { * List of joints that relates to this finger, starting from joint closest to wrist all the way * to the tip of a finger. * - * @type {import('./xr-joint.js').XrJoint[]} + * @type {XrJoint[]} */ get joints() { return this._joints; @@ -72,7 +77,7 @@ class XrFinger { /** * Tip of a finger, or null if not available. * - * @type {import('./xr-joint.js').XrJoint|null} + * @type {XrJoint|null} */ get tip() { return this._tip; diff --git a/src/framework/xr/xr-hand.js b/src/framework/xr/xr-hand.js index 30ac1c80e61..4aab08f03e2 100644 --- a/src/framework/xr/xr-hand.js +++ b/src/framework/xr/xr-hand.js @@ -1,11 +1,14 @@ import { EventHandler } from '../../core/event-handler.js'; import { platform } from '../../core/platform.js'; import { Vec3 } from '../../core/math/vec3.js'; - import { XRHAND_LEFT } from './constants.js'; import { XrFinger } from './xr-finger.js'; import { XrJoint } from './xr-joint.js'; +/** + * @import { XrInputSource } from './xr-input-source.js' + * @import { XrManager } from './xr-manager.js' + */ /** * @type {string[][]} @@ -55,13 +58,13 @@ class XrHand extends EventHandler { static EVENT_TRACKINGLOST = 'trackinglost'; /** - * @type {import('./xr-manager.js').XrManager} + * @type {XrManager} * @private */ _manager; /** - * @type {import('./xr-input-source.js').XrInputSource} + * @type {XrInputSource} * @private */ _inputSource; @@ -105,8 +108,7 @@ class XrHand extends EventHandler { /** * Represents a hand with fingers and joints. * - * @param {import('./xr-input-source.js').XrInputSource} inputSource - Input Source that hand - * is related to. + * @param {XrInputSource} inputSource - Input Source that hand is related to. * @ignore */ constructor(inputSource) { diff --git a/src/framework/xr/xr-hit-test-source.js b/src/framework/xr/xr-hit-test-source.js index f99dd419022..9011ce53120 100644 --- a/src/framework/xr/xr-hit-test-source.js +++ b/src/framework/xr/xr-hit-test-source.js @@ -2,6 +2,11 @@ import { EventHandler } from '../../core/event-handler.js'; import { Quat } from '../../core/math/quat.js'; import { Vec3 } from '../../core/math/vec3.js'; +/** + * @import { XrInputSource } from './xr-input-source.js' + * @import { XrManager } from './xr-manager.js' + */ + /** * @type {Vec3[]} */ @@ -60,7 +65,7 @@ class XrHitTestSource extends EventHandler { static EVENT_RESULT = 'result'; /** - * @type {import('./xr-manager.js').XrManager} + * @type {XrManager} * @private */ manager; @@ -78,7 +83,7 @@ class XrHitTestSource extends EventHandler { _transient; /** - * @type {null|import('./xr-input-source.js').XrInputSource} + * @type {null|XrInputSource} * @private */ _inputSource; @@ -86,10 +91,10 @@ class XrHitTestSource extends EventHandler { /** * Create a new XrHitTestSource instance. * - * @param {import('./xr-manager.js').XrManager} manager - WebXR Manager. + * @param {XrManager} manager - WebXR Manager. * @param {XRHitTestSource} xrHitTestSource - XRHitTestSource object that is created by WebXR API. * @param {boolean} transient - True if XRHitTestSource created for input source profile. - * @param {null|import('./xr-input-source.js').XrInputSource} inputSource - Input Source for which hit test is created for, or null. + * @param {null|XrInputSource} inputSource - Input Source for which hit test is created for, or null. * @ignore */ constructor(manager, xrHitTestSource, transient, inputSource = null) { @@ -155,7 +160,7 @@ class XrHitTestSource extends EventHandler { /** * @param {XRTransientInputHitTestResult[]} results - Hit test results. - * @param {null|import('./xr-input-source.js').XrInputSource} inputSource - Input source. + * @param {null|XrInputSource} inputSource - Input source. * @private */ updateHitResults(results, inputSource) { diff --git a/src/framework/xr/xr-hit-test.js b/src/framework/xr/xr-hit-test.js index ca39d5f479f..6c43f5d955a 100644 --- a/src/framework/xr/xr-hit-test.js +++ b/src/framework/xr/xr-hit-test.js @@ -1,9 +1,14 @@ import { platform } from '../../core/platform.js'; import { EventHandler } from '../../core/event-handler.js'; - import { XRSPACE_VIEWER } from './constants.js'; import { XrHitTestSource } from './xr-hit-test-source.js'; +/** + * @import { Ray } from '../../core/shape/ray.js' + * @import { XrInputSource } from './xr-input-source.js' + * @import { XrManager } from './xr-manager.js' + */ + /** * Callback used by {@link XrHitTest#start} and {@link XrHitTest#startForInputSource}. * @@ -94,7 +99,7 @@ class XrHitTest extends EventHandler { static EVENT_ERROR = 'error'; /** - * @type {import('./xr-manager.js').XrManager} + * @type {XrManager} * @private */ manager; @@ -127,7 +132,7 @@ class XrHitTest extends EventHandler { /** * Create a new XrHitTest instance. * - * @param {import('./xr-manager.js').XrManager} manager - WebXR Manager. + * @param {XrManager} manager - WebXR Manager. * @ignore */ constructor(manager) { @@ -213,7 +218,7 @@ class XrHitTest extends EventHandler { * - {@link XRTRACKABLE_MESH}: Mesh - indicates that the hit test results will be computed * based on the meshes detected by the underlying Augmented Reality system. * - * @param {import('../../core/shape/ray.js').Ray} [options.offsetRay] - Optional ray by which + * @param {Ray} [options.offsetRay] - Optional ray by which * hit test ray can be offset. * @param {XrHitTestStartCallback} [options.callback] - Optional callback function called once * hit test source is created or failed. @@ -316,7 +321,7 @@ class XrHitTest extends EventHandler { /** * @param {XRHitTestSource} xrHitTestSource - Hit test source. * @param {boolean} transient - True if hit test source is created from transient input source. - * @param {import('./xr-input-source.js').XrInputSource|null} inputSource - Input Source with which hit test source is associated with. + * @param {XrInputSource|null} inputSource - Input Source with which hit test source is associated with. * @param {Function} callback - Callback called once hit test source is created. * @private */ diff --git a/src/framework/xr/xr-image-tracking.js b/src/framework/xr/xr-image-tracking.js index 1915282bfbf..60b9ff6fe45 100644 --- a/src/framework/xr/xr-image-tracking.js +++ b/src/framework/xr/xr-image-tracking.js @@ -1,8 +1,11 @@ import { EventHandler } from '../../core/event-handler.js'; import { platform } from '../../core/platform.js'; - import { XrTrackedImage } from './xr-tracked-image.js'; +/** + * @import { XrManager } from './xr-manager.js' + */ + /** * Image Tracking provides the ability to track real world images using provided image samples and * their estimated sizes. The underlying system will assume that tracked image can move and rotate @@ -24,7 +27,7 @@ class XrImageTracking extends EventHandler { static EVENT_ERROR = 'error'; /** - * @type {import('./xr-manager.js').XrManager} + * @type {XrManager} * @private */ _manager; @@ -51,7 +54,7 @@ class XrImageTracking extends EventHandler { * Image Tracking provides the ability to track real world images by provided image samples and * their estimate sizes. * - * @param {import('./xr-manager.js').XrManager} manager - WebXR Manager. + * @param {XrManager} manager - WebXR Manager. * @ignore */ constructor(manager) { diff --git a/src/framework/xr/xr-input-source.js b/src/framework/xr/xr-input-source.js index 5d8bf37d5de..ed629932cb1 100644 --- a/src/framework/xr/xr-input-source.js +++ b/src/framework/xr/xr-input-source.js @@ -3,11 +3,16 @@ import { Mat4 } from '../../core/math/mat4.js'; import { Quat } from '../../core/math/quat.js'; import { Vec3 } from '../../core/math/vec3.js'; import { Ray } from '../../core/shape/ray.js'; - import { XrHand } from './xr-hand.js'; - import { now } from '../../core/time.js'; +/** + * @import { Entity } from '../entity.js' + * @import { XrHitTestSource } from './xr-hit-test-source.js' + * @import { XrHitTestStartCallback } from './xr-hit-test.js' + * @import { XrManager } from './xr-manager.js' + */ + const vec3A = new Vec3(); const quat = new Quat(); let ids = 0; @@ -158,7 +163,7 @@ class XrInputSource extends EventHandler { _id; /** - * @type {import('./xr-manager.js').XrManager} + * @type {XrManager} * @private */ _manager; @@ -284,13 +289,13 @@ class XrInputSource extends EventHandler { _elementInput = true; /** - * @type {import('../entity.js').Entity|null} + * @type {Entity|null} * @private */ _elementEntity = null; /** - * @type {import('./xr-hit-test-source.js').XrHitTestSource[]} + * @type {XrHitTestSource[]} * @private */ _hitTestSources = []; @@ -298,7 +303,7 @@ class XrInputSource extends EventHandler { /** * Create a new XrInputSource instance. * - * @param {import('./xr-manager.js').XrManager} manager - WebXR Manager. + * @param {XrManager} manager - WebXR Manager. * @param {XRInputSource} xrInputSource - A WebXR input source. * @ignore */ @@ -452,7 +457,7 @@ class XrInputSource extends EventHandler { * If {@link XrInputSource#elementInput} is true, this property will hold entity with Element * component at which this input source is hovering, or null if not hovering over any element. * - * @type {import('../entity.js').Entity|null} + * @type {Entity|null} */ get elementEntity() { return this._elementEntity; @@ -461,7 +466,7 @@ class XrInputSource extends EventHandler { /** * List of active {@link XrHitTestSource} instances associated with this input source. * - * @type {import('./xr-hit-test-source.js').XrHitTestSource[]} + * @type {XrHitTestSource[]} */ get hitTestSources() { return this._hitTestSources; @@ -663,8 +668,8 @@ class XrInputSource extends EventHandler { * based on the meshes detected by the underlying Augmented Reality system. * * @param {Ray} [options.offsetRay] - Optional ray by which hit test ray can be offset. - * @param {import('./xr-hit-test.js').XrHitTestStartCallback} [options.callback] - Optional - * callback function called once hit test source is created or failed. + * @param {XrHitTestStartCallback} [options.callback] - Optional callback function called once + * hit test source is created or failed. * @example * app.xr.input.on('add', function (inputSource) { * inputSource.hitTestStart({ @@ -692,7 +697,7 @@ class XrInputSource extends EventHandler { } /** - * @param {import('./xr-hit-test-source.js').XrHitTestSource} hitTestSource - Hit test source + * @param {XrHitTestSource} hitTestSource - Hit test source * to be added. * @private */ @@ -712,7 +717,7 @@ class XrInputSource extends EventHandler { } /** - * @param {import('./xr-hit-test-source.js').XrHitTestSource} hitTestSource - Hit test source + * @param {XrHitTestSource} hitTestSource - Hit test source * to be removed. * @private */ diff --git a/src/framework/xr/xr-input.js b/src/framework/xr/xr-input.js index 38e24031b47..7cc31f07ba6 100644 --- a/src/framework/xr/xr-input.js +++ b/src/framework/xr/xr-input.js @@ -2,6 +2,10 @@ import { EventHandler } from '../../core/event-handler.js'; import { platform } from '../../core/platform.js'; import { XrInputSource } from './xr-input-source.js'; +/** + * @import { XrManager } from './xr-manager.js' + */ + /** * Provides access to input sources for WebXR. * @@ -123,7 +127,7 @@ class XrInput extends EventHandler { static EVENT_SQUEEZEEND = 'squeezeend'; /** - * @type {import('./xr-manager.js').XrManager} + * @type {XrManager} * @private */ manager; @@ -149,7 +153,7 @@ class XrInput extends EventHandler { /** * Create a new XrInput instance. * - * @param {import('./xr-manager.js').XrManager} manager - WebXR Manager. + * @param {XrManager} manager - WebXR Manager. * @ignore */ constructor(manager) { diff --git a/src/framework/xr/xr-joint.js b/src/framework/xr/xr-joint.js index 4d24f3e23ad..567b5a8efbd 100644 --- a/src/framework/xr/xr-joint.js +++ b/src/framework/xr/xr-joint.js @@ -3,6 +3,11 @@ import { Mat4 } from '../../core/math/mat4.js'; import { Quat } from '../../core/math/quat.js'; import { Vec3 } from '../../core/math/vec3.js'; +/** + * @import { XrFinger } from './xr-finger.js' + * @import { XrHand } from './xr-hand.js' + */ + const tipJointIds = platform.browser && window.XRHand ? [ 'thumb-tip', 'index-finger-tip', @@ -36,13 +41,13 @@ class XrJoint { _id; /** - * @type {import('./xr-hand.js').XrHand} + * @type {XrHand} * @private */ _hand; /** - * @type {import('./xr-finger.js').XrFinger} + * @type {XrFinger} * @private */ _finger; @@ -112,8 +117,8 @@ class XrJoint { * * @param {number} index - Index of a joint within a finger. * @param {string} id - Id of a joint based on WebXR Hand Input Specs. - * @param {import('./xr-hand.js').XrHand} hand - Hand that joint relates to. - * @param {import('./xr-finger.js').XrFinger|null} finger - Finger that joint is related to. + * @param {XrHand} hand - Hand that joint relates to. + * @param {XrFinger|null} finger - Finger that joint is related to. * Can be null in the case of the wrist joint. * @ignore */ @@ -189,7 +194,7 @@ class XrJoint { /** * Hand that joint relates to. * - * @type {import('./xr-hand.js').XrHand} + * @type {XrHand} */ get hand() { return this._hand; @@ -198,7 +203,7 @@ class XrJoint { /** * Finger that joint relates to. * - * @type {import('./xr-finger.js').XrFinger|null} + * @type {XrFinger|null} */ get finger() { return this._finger; diff --git a/src/framework/xr/xr-light-estimation.js b/src/framework/xr/xr-light-estimation.js index d4a314235b6..c3ef7426f30 100644 --- a/src/framework/xr/xr-light-estimation.js +++ b/src/framework/xr/xr-light-estimation.js @@ -3,9 +3,12 @@ import { Color } from '../../core/math/color.js'; import { Mat4 } from '../../core/math/mat4.js'; import { Quat } from '../../core/math/quat.js'; import { Vec3 } from '../../core/math/vec3.js'; - import { XRTYPE_AR } from './constants.js'; +/** + * @import { XrManager } from './xr-manager.js' + */ + const vec3A = new Vec3(); const vec3B = new Vec3(); const mat4A = new Mat4(); @@ -45,7 +48,7 @@ class XrLightEstimation extends EventHandler { static EVENT_ERROR = 'error'; /** - * @type {import('./xr-manager.js').XrManager} + * @type {XrManager} * @private */ _manager; @@ -101,7 +104,7 @@ class XrLightEstimation extends EventHandler { /** * Create a new XrLightEstimation instance. * - * @param {import('./xr-manager.js').XrManager} manager - WebXR Manager. + * @param {XrManager} manager - WebXR Manager. * @ignore */ constructor(manager) { diff --git a/src/framework/xr/xr-manager.js b/src/framework/xr/xr-manager.js index 327b1712c64..d7d140bb8e2 100644 --- a/src/framework/xr/xr-manager.js +++ b/src/framework/xr/xr-manager.js @@ -1,11 +1,9 @@ import { Debug } from "../../core/debug.js"; - import { EventHandler } from '../../core/event-handler.js'; import { platform } from '../../core/platform.js'; import { Mat4 } from '../../core/math/mat4.js'; import { Quat } from '../../core/math/quat.js'; import { Vec3 } from '../../core/math/vec3.js'; - import { XRTYPE_INLINE, XRTYPE_VR, XRTYPE_AR, XRDEPTHSENSINGUSAGE_CPU, XRDEPTHSENSINGFORMAT_L8A8 } from './constants.js'; import { XrDomOverlay } from './xr-dom-overlay.js'; import { XrHitTest } from './xr-hit-test.js'; @@ -17,6 +15,12 @@ import { XrAnchors } from './xr-anchors.js'; import { XrMeshDetection } from './xr-mesh-detection.js'; import { XrViews } from './xr-views.js'; +/** + * @import { AppBase } from '../app-base.js' + * @import { CameraComponent } from '../components/camera/component.js' + * @import { Entity } from '../entity.js' + */ + /** * Callback used by {@link XrManager#endXr} and {@link XrManager#startXr}. * @@ -107,7 +111,7 @@ class XrManager extends EventHandler { static EVENT_ERROR = 'error'; /** - * @type {import('../app-base.js').AppBase} + * @type {AppBase} * @ignore */ app; @@ -225,7 +229,7 @@ class XrManager extends EventHandler { anchors; /** - * @type {import('../components/camera/component.js').CameraComponent} + * @type {CameraComponent} * @private */ _camera = null; @@ -281,7 +285,7 @@ class XrManager extends EventHandler { /** * Create a new XrManager instance. * - * @param {import('../app-base.js').AppBase} app - The main application. + * @param {AppBase} app - The main application. * @ignore */ constructor(app) { @@ -333,8 +337,8 @@ class XrManager extends EventHandler { * callback when session is created or failed to create. Integrated XR APIs need to be enabled * by providing relevant options. * - * @param {import('../components/camera/component.js').CameraComponent} camera - It will be - * used to render XR session and manipulated based on pose tracking. + * @param {CameraComponent} camera - It will be used to render XR session and manipulated based + * on pose tracking. * @param {string} type - Session type. Can be one of the following: * * - {@link XRTYPE_INLINE}: Inline - always available type of session. It has limited features @@ -362,8 +366,8 @@ class XrManager extends EventHandler { * * @param {object} [options] - Object with additional options for XR session initialization. * @param {number} [options.framebufferScaleFactor] - Framebuffer scale factor should - * be higher than 0.0, by default 1.0 (no scaling). A value of 0.5 will reduce the resolution of - * an XR session in half, and a value of 2.0 will double the resolution. + * be higher than 0.0, by default 1.0 (no scaling). A value of 0.5 will reduce the resolution + * of an XR session in half, and a value of 2.0 will double the resolution. * @param {string[]} [options.optionalFeatures] - Optional features for XRSession start. It is * used for getting access to additional WebXR spec extensions. * @param {boolean} [options.anchors] - Set to true to attempt to enable @@ -1041,7 +1045,7 @@ class XrManager extends EventHandler { /** * Active camera for which XR session is running or null. * - * @type {import('../entity.js').Entity|null} + * @type {Entity|null} */ get camera() { return this._camera ? this._camera.entity : null; diff --git a/src/framework/xr/xr-mesh-detection.js b/src/framework/xr/xr-mesh-detection.js index be849137f16..f799f9e637a 100644 --- a/src/framework/xr/xr-mesh-detection.js +++ b/src/framework/xr/xr-mesh-detection.js @@ -2,6 +2,10 @@ import { platform } from "../../core/platform.js"; import { EventHandler } from "../../core/event-handler.js"; import { XrMesh } from "./xr-mesh.js"; +/** + * @import { XrManager } from './xr-manager.js' + */ + /** * Mesh Detection provides the ability to detect real world meshes based on the * scanning and reconstruction by the underlying AR system. @@ -69,7 +73,7 @@ class XrMeshDetection extends EventHandler { static EVENT_REMOVE = 'remove'; /** - * @type {import('./xr-manager.js').XrManager} + * @type {XrManager} * @private */ _manager; @@ -101,7 +105,7 @@ class XrMeshDetection extends EventHandler { /** * Create a new XrMeshDetection instance. * - * @param {import('./xr-manager.js').XrManager} manager - WebXR Manager. + * @param {XrManager} manager - WebXR Manager. * @ignore */ constructor(manager) { diff --git a/src/framework/xr/xr-mesh.js b/src/framework/xr/xr-mesh.js index fd32335e0ef..08e483918c1 100644 --- a/src/framework/xr/xr-mesh.js +++ b/src/framework/xr/xr-mesh.js @@ -2,6 +2,10 @@ import { EventHandler } from "../../core/event-handler.js"; import { Vec3 } from "../../core/math/vec3.js"; import { Quat } from "../../core/math/quat.js"; +/** + * @import { XrMeshDetection } from './xr-mesh-detection.js' + */ + /** * Detected Mesh instance that provides its transform (position, rotation), * triangles (vertices, indices) and its semantic label. Any of its properties can @@ -35,7 +39,7 @@ class XrMesh extends EventHandler { static EVENT_CHANGE = 'change'; /** - * @type {import('./xr-mesh-detection.js').XrMeshDetection} + * @type {XrMeshDetection} * @private */ _meshDetection; @@ -67,7 +71,7 @@ class XrMesh extends EventHandler { /** * Create a new XrMesh instance. * - * @param {import('./xr-mesh-detection.js').XrMeshDetection} meshDetection - Mesh Detection + * @param {XrMeshDetection} meshDetection - Mesh Detection * interface. * @param {XRMesh} xrMesh - XRMesh that is instantiated by WebXR system. * @ignore diff --git a/src/framework/xr/xr-plane-detection.js b/src/framework/xr/xr-plane-detection.js index 41a30f3422b..bb21cd3276c 100644 --- a/src/framework/xr/xr-plane-detection.js +++ b/src/framework/xr/xr-plane-detection.js @@ -2,6 +2,10 @@ import { platform } from '../../core/platform.js'; import { EventHandler } from '../../core/event-handler.js'; import { XrPlane } from './xr-plane.js'; +/** + * @import { XrManager } from './xr-manager.js' + */ + /** * Plane Detection provides the ability to detect real world surfaces based on estimations of the * underlying AR system. @@ -69,7 +73,7 @@ class XrPlaneDetection extends EventHandler { static EVENT_REMOVE = 'remove'; /** - * @type {import('./xr-manager.js').XrManager} + * @type {XrManager} * @private */ _manager; @@ -101,7 +105,7 @@ class XrPlaneDetection extends EventHandler { /** * Create a new XrPlaneDetection instance. * - * @param {import('./xr-manager.js').XrManager} manager - WebXR Manager. + * @param {XrManager} manager - WebXR Manager. * @ignore */ constructor(manager) { diff --git a/src/framework/xr/xr-plane.js b/src/framework/xr/xr-plane.js index e176fc6f0cb..3065049b943 100644 --- a/src/framework/xr/xr-plane.js +++ b/src/framework/xr/xr-plane.js @@ -2,6 +2,10 @@ import { EventHandler } from '../../core/event-handler.js'; import { Quat } from '../../core/math/quat.js'; import { Vec3 } from '../../core/math/vec3.js'; +/** + * @import { XrPlaneDetection } from './xr-plane-detection.js' + */ + let ids = 0; /** @@ -43,7 +47,7 @@ class XrPlane extends EventHandler { _id; /** - * @type {import('./xr-plane-detection.js').XrPlaneDetection} + * @type {XrPlaneDetection} * @private */ _planeDetection; @@ -81,8 +85,7 @@ class XrPlane extends EventHandler { /** * Create a new XrPlane instance. * - * @param {import('./xr-plane-detection.js').XrPlaneDetection} planeDetection - Plane detection - * system. + * @param {XrPlaneDetection} planeDetection - Plane detection system. * @param {*} xrPlane - XRPlane that is instantiated by WebXR system. * @ignore */ diff --git a/src/framework/xr/xr-view.js b/src/framework/xr/xr-view.js index ec91895e5fc..4dcfa66af76 100644 --- a/src/framework/xr/xr-view.js +++ b/src/framework/xr/xr-view.js @@ -3,9 +3,12 @@ import { Texture } from '../../platform/graphics/texture.js'; import { Vec4 } from "../../core/math/vec4.js"; import { Mat3 } from "../../core/math/mat3.js"; import { Mat4 } from "../../core/math/mat4.js"; - import { ADDRESS_CLAMP_TO_EDGE, FILTER_LINEAR, FILTER_NEAREST, PIXELFORMAT_RGB8 } from '../../platform/graphics/constants.js'; +/** + * @import { XrManager } from './xr-manager.js' + */ + /** * Represents an XR View which represents a screen (monoscopic scenario such as a mobile phone) or an eye * (stereoscopic scenario such as an HMD context). It provides access to the view's color and depth information @@ -28,7 +31,7 @@ class XrView extends EventHandler { static EVENT_DEPTHRESIZE = 'depth:resize'; /** - * @type {import('./xr-manager.js').XrManager} + * @type {XrManager} * @private */ _manager; @@ -132,7 +135,7 @@ class XrView extends EventHandler { /** * Create a new XrView instance. * - * @param {import('./xr-manager.js').XrManager} manager - WebXR Manager. + * @param {XrManager} manager - WebXR Manager. * @param {XRView} xrView - [XRView](https://developer.mozilla.org/en-US/docs/Web/API/XRView) * object that is created by WebXR API. * @param {number} viewsCount - Number of views available for the session. diff --git a/src/framework/xr/xr-views.js b/src/framework/xr/xr-views.js index d55fd9dab81..d7838fef7fe 100644 --- a/src/framework/xr/xr-views.js +++ b/src/framework/xr/xr-views.js @@ -4,6 +4,10 @@ import { XrView } from "./xr-view.js"; import { XRTYPE_AR, XRDEPTHSENSINGUSAGE_GPU, XRDEPTHSENSINGFORMAT_L8A8, XRDEPTHSENSINGFORMAT_F32 } from "./constants.js"; import { PIXELFORMAT_LA8, PIXELFORMAT_R32F } from '../../platform/graphics/constants.js'; +/** + * @import { XrManager } from './xr-manager.js' + */ + /** * Provides access to list of {@link XrView}'s. And information about their capabilities, * such as support and availability of view's camera color texture, depth texture and other parameters. @@ -37,7 +41,7 @@ class XrViews extends EventHandler { static EVENT_REMOVE = 'remove'; /** - * @type {import('./xr-manager.js').XrManager} + * @type {XrManager} * @private */ _manager; @@ -106,7 +110,7 @@ class XrViews extends EventHandler { }; /** - * @param {import('./xr-manager.js').XrManager} manager - WebXR Manager. + * @param {XrManager} manager - WebXR Manager. * @ignore */ constructor(manager) { diff --git a/src/platform/audio/channel.js b/src/platform/audio/channel.js index 996ad5773e4..5744e889b52 100644 --- a/src/platform/audio/channel.js +++ b/src/platform/audio/channel.js @@ -1,7 +1,11 @@ import { math } from '../../core/math/math.js'; - import { hasAudioContext } from './capabilities.js'; +/** + * @import { SoundManager } from '../sound/manager.js' + * @import { Sound } from '../sound/sound.js' + */ + /** * A channel is created when the {@link SoundManager} begins playback of a {@link Sound}. Usually * created internally by {@link SoundManager#playSound} or {@link SoundManager#playSound3d}. @@ -13,8 +17,8 @@ class Channel { /** * Create a new Channel instance. * - * @param {import('../sound/manager.js').SoundManager} manager - The SoundManager instance. - * @param {import('../sound/sound.js').Sound} sound - The sound to playback. + * @param {SoundManager} manager - The SoundManager instance. + * @param {Sound} sound - The sound to playback. * @param {object} [options] - Optional options object. * @param {number} [options.volume] - The playback volume, between 0 and 1. Defaults to 1. * @param {number} [options.pitch] - The relative pitch. Defaults to 1 (plays at normal pitch). diff --git a/src/platform/audio/channel3d.js b/src/platform/audio/channel3d.js index 87ba2090b7f..f4d7205b96a 100644 --- a/src/platform/audio/channel3d.js +++ b/src/platform/audio/channel3d.js @@ -1,11 +1,15 @@ import { Debug } from '../../core/debug.js'; import { math } from '../../core/math/math.js'; import { Vec3 } from '../../core/math/vec3.js'; - import { DISTANCE_EXPONENTIAL, DISTANCE_INVERSE, DISTANCE_LINEAR } from './constants.js'; import { hasAudioContext } from './capabilities.js'; import { Channel } from './channel.js'; +/** + * @import { SoundManager } from '../sound/manager.js' + * @import { Sound } from '../sound/sound.js' + */ + // default maxDistance, same as Web Audio API const MAX_DISTANCE = 10000; @@ -18,8 +22,8 @@ class Channel3d extends Channel { /** * Create a new Channel3d instance. * - * @param {import('../sound/manager.js').SoundManager} manager - The SoundManager instance. - * @param {import('../sound/sound.js').Sound} sound - The sound to playback. + * @param {SoundManager} manager - The SoundManager instance. + * @param {Sound} sound - The sound to playback. * @param {object} [options] - Optional options object. * @param {number} [options.volume] - The playback volume, between 0 and 1. Defaults to 1. * @param {number} [options.pitch] - The relative pitch. Defaults to 1 (plays at normal pitch). diff --git a/src/platform/graphics/bind-group-format.js b/src/platform/graphics/bind-group-format.js index 22b371164f7..46fa04338df 100644 --- a/src/platform/graphics/bind-group-format.js +++ b/src/platform/graphics/bind-group-format.js @@ -1,12 +1,16 @@ import { TRACEID_BINDGROUPFORMAT_ALLOC } from '../../core/constants.js'; import { Debug, DebugHelper } from '../../core/debug.js'; - import { TEXTUREDIMENSION_2D, TEXTUREDIMENSION_CUBE, TEXTUREDIMENSION_3D, TEXTUREDIMENSION_2D_ARRAY, SAMPLETYPE_FLOAT, PIXELFORMAT_RGBA8, SAMPLETYPE_INT, SAMPLETYPE_UINT, SHADERSTAGE_COMPUTE, SHADERSTAGE_VERTEX } from './constants.js'; import { DebugGraphics } from './debug-graphics.js'; +/** + * @import { GraphicsDevice } from './graphics-device.js' + * @import { ScopeId } from './scope-id.js' + */ + let id = 0; const textureDimensionInfo = { @@ -29,7 +33,7 @@ class BindBaseFormat { slot = -1; /** - * @type {import('./scope-id.js').ScopeId|null} + * @type {ScopeId|null} * @ignore */ scopeId = null; @@ -149,6 +153,7 @@ class BindTextureFormat extends BindBaseFormat { * A class to describe the format of the storage texture for {@link BindGroupFormat}. Storage * texture is a texture created with the storage flag set to true, which allows it to be used as an * output of a compute shader. + * * Note: At the current time, storage textures are only supported in compute shaders in a * write-only mode. * @@ -230,10 +235,9 @@ class BindGroupFormat { /** * Create a new instance. * - * @param {import('./graphics-device.js').GraphicsDevice} graphicsDevice - The graphics device - * used to manage this vertex format. - * @param {(BindTextureFormat|BindStorageTextureFormat|BindUniformBufferFormat|BindStorageBufferFormat)[]} formats - * - An array of bind formats. Note that each entry in the array uses up one slot. The exception + * @param {GraphicsDevice} graphicsDevice - The graphics device used to manage this vertex format. + * @param {(BindTextureFormat|BindStorageTextureFormat|BindUniformBufferFormat|BindStorageBufferFormat)[]} formats - + * An array of bind formats. Note that each entry in the array uses up one slot. The exception * is a texture format that has a sampler, which uses up two slots. The slots are allocated * sequentially, starting from 0. */ @@ -266,7 +270,7 @@ class BindGroupFormat { } }); - /** @type {import('./graphics-device.js').GraphicsDevice} */ + /** @type {GraphicsDevice} */ this.device = graphicsDevice; const scope = graphicsDevice.scope; diff --git a/src/platform/graphics/bind-group.js b/src/platform/graphics/bind-group.js index 305d9032c7b..e8381a9f80f 100644 --- a/src/platform/graphics/bind-group.js +++ b/src/platform/graphics/bind-group.js @@ -3,6 +3,14 @@ import { TRACEID_BINDGROUP_ALLOC } from '../../core/constants.js'; import { UNIFORM_BUFFER_DEFAULT_SLOT_NAME } from './constants.js'; import { DebugGraphics } from './debug-graphics.js'; +/** + * @import { BindGroupFormat } from './bind-group-format.js' + * @import { GraphicsDevice } from './graphics-device.js' + * @import { StorageBuffer } from './storage-buffer.js' + * @import { Texture } from './texture.js' + * @import { UniformBuffer } from './uniform-buffer.js' + */ + let id = 0; /** @@ -28,7 +36,7 @@ class BindGroup { */ renderVersionUpdated = -1; - /** @type {import('./uniform-buffer.js').UniformBuffer[]} */ + /** @type {UniformBuffer[]} */ uniformBuffers; /** @@ -42,12 +50,10 @@ class BindGroup { /** * Create a new Bind Group. * - * @param {import('./graphics-device.js').GraphicsDevice} graphicsDevice - The graphics device - * used to manage this uniform buffer. - * @param {import('./bind-group-format.js').BindGroupFormat} format - Format of the bind group. - * @param {import('./uniform-buffer.js').UniformBuffer} [defaultUniformBuffer] - The default - * uniform buffer. Typically a bind group only has a single uniform buffer, and this allows - * easier access. + * @param {GraphicsDevice} graphicsDevice - The graphics device used to manage this uniform buffer. + * @param {BindGroupFormat} format - Format of the bind group. + * @param {UniformBuffer} [defaultUniformBuffer] - The default uniform buffer. Typically a bind + * group only has a single uniform buffer, and this allows easier access. */ constructor(graphicsDevice, format, defaultUniformBuffer) { this.id = id++; @@ -61,7 +67,7 @@ class BindGroup { this.storageBuffers = []; this.uniformBuffers = []; - /** @type {import('./uniform-buffer.js').UniformBuffer} */ + /** @type {UniformBuffer} */ this.defaultUniformBuffer = defaultUniformBuffer; if (defaultUniformBuffer) { this.setUniformBuffer(UNIFORM_BUFFER_DEFAULT_SLOT_NAME, defaultUniformBuffer); @@ -84,8 +90,7 @@ class BindGroup { * Assign a uniform buffer to a slot. * * @param {string} name - The name of the uniform buffer slot - * @param {import('./uniform-buffer.js').UniformBuffer} uniformBuffer - The Uniform buffer to - * assign to the slot. + * @param {UniformBuffer} uniformBuffer - The Uniform buffer to assign to the slot. */ setUniformBuffer(name, uniformBuffer) { const index = this.format.bufferFormatsMap.get(name); @@ -100,8 +105,7 @@ class BindGroup { * Assign a storage buffer to a slot. * * @param {string} name - The name of the storage buffer slot. - * @param {import('./storage-buffer.js').StorageBuffer} storageBuffer - The storage buffer to - * assign to the slot. + * @param {StorageBuffer} storageBuffer - The storage buffer to assign to the slot. */ setStorageBuffer(name, storageBuffer) { const index = this.format.storageBufferFormatsMap.get(name); @@ -116,7 +120,7 @@ class BindGroup { * Assign a texture to a named slot. * * @param {string} name - The name of the texture slot. - * @param {import('./texture.js').Texture} texture - Texture to assign to the slot. + * @param {Texture} texture - Texture to assign to the slot. */ setTexture(name, texture) { const index = this.format.textureFormatsMap.get(name); @@ -134,7 +138,7 @@ class BindGroup { * Assign a storage texture to a named slot. * * @param {string} name - The name of the texture slot. - * @param {import('./texture.js').Texture} texture - Texture to assign to the slot. + * @param {Texture} texture - Texture to assign to the slot. */ setStorageTexture(name, texture) { const index = this.format.storageTextureFormatsMap.get(name); diff --git a/src/platform/graphics/compute.js b/src/platform/graphics/compute.js index 8f32dc1596c..d57cb464dc0 100644 --- a/src/platform/graphics/compute.js +++ b/src/platform/graphics/compute.js @@ -1,3 +1,13 @@ +/** + * @import { GraphicsDevice } from './graphics-device.js' + * @import { IndexBuffer } from './index-buffer.js' + * @import { ScopeId } from './scope-id.js' + * @import { Shader } from './shader.js' + * @import { StorageBuffer } from './storage-buffer.js' + * @import { Texture } from './texture.js' + * @import { VertexBuffer } from './vertex-buffer.js' + */ + /** * A helper class storing a parameter value as well as its scope ID. * @@ -6,7 +16,7 @@ class ComputeParameter { value; - /** @type {import('./scope-id.js').ScopeId} */ + /** @type {ScopeId} */ scopeId = null; } @@ -18,7 +28,7 @@ class Compute { /** * A compute shader. * - * @type {import('./shader.js').Shader|null} + * @type {Shader|null} * @ignore */ shader = null; @@ -58,9 +68,9 @@ class Compute { * Create a compute instance. Note that this is supported on WebGPU only and is a no-op on * other platforms. * - * @param {import('./graphics-device.js').GraphicsDevice} graphicsDevice - + * @param {GraphicsDevice} graphicsDevice - * The graphics device. - * @param {import('./shader.js').Shader} shader - The compute shader. + * @param {Shader} shader - The compute shader. * @param {string} [name] - The name of the compute instance, used for debugging only. */ constructor(graphicsDevice, shader, name = 'Unnamed') { @@ -77,8 +87,8 @@ class Compute { * Sets a shader parameter on a compute instance. * * @param {string} name - The name of the parameter to set. - * @param {number|number[]|Float32Array|import('./texture.js').Texture|import('./storage-buffer.js').StorageBuffer|import('./vertex-buffer.js').VertexBuffer|import('./index-buffer.js').IndexBuffer} value - * - The value for the specified parameter. + * @param {number|number[]|Float32Array|Texture|StorageBuffer|VertexBuffer|IndexBuffer} value - + * The value for the specified parameter. */ setParameter(name, value) { let param = this.parameters.get(name); @@ -94,7 +104,7 @@ class Compute { * Returns the value of a shader parameter from the compute instance. * * @param {string} name - The name of the parameter to get. - * @returns {number|number[]|Float32Array|import('./texture.js').Texture|import('./storage-buffer.js').StorageBuffer|import('./vertex-buffer.js').VertexBuffer|import('./index-buffer.js').IndexBuffer|undefined} + * @returns {number|number[]|Float32Array|Texture|StorageBuffer|VertexBuffer|IndexBuffer|undefined} * The value of the specified parameter. */ getParameter(name) { diff --git a/src/platform/graphics/debug-graphics.js b/src/platform/graphics/debug-graphics.js index 4bc79082019..50141c745d8 100644 --- a/src/platform/graphics/debug-graphics.js +++ b/src/platform/graphics/debug-graphics.js @@ -1,3 +1,7 @@ +/** + * @import { GraphicsDevice } from './graphics-device.js' + */ + /** * Internal graphics debug system - gpu markers and similar. Note that the functions only execute * in the debug build, and are stripped out in other builds. @@ -22,7 +26,7 @@ class DebugGraphics { /** * Push GPU marker to the stack on the device. * - * @param {import('./graphics-device.js').GraphicsDevice} device - The graphics device. + * @param {GraphicsDevice} device - The graphics device. * @param {string} name - The name of the marker. */ static pushGpuMarker(device, name) { @@ -33,7 +37,7 @@ class DebugGraphics { /** * Pop GPU marker from the stack on the device. * - * @param {import('./graphics-device.js').GraphicsDevice} device - The graphics device. + * @param {GraphicsDevice} device - The graphics device. */ static popGpuMarker(device) { if (DebugGraphics.markers.length) { diff --git a/src/platform/graphics/device-cache.js b/src/platform/graphics/device-cache.js index f621e40aa4f..6f9c09fa66d 100644 --- a/src/platform/graphics/device-cache.js +++ b/src/platform/graphics/device-cache.js @@ -1,3 +1,7 @@ +/** + * @import { GraphicsDevice } from './graphics-device.js' + */ + /** * A cache storing shared resources associated with a device. The resources are removed * from the cache when the device is destroyed. @@ -6,14 +10,14 @@ class DeviceCache { /** * Cache storing the resource for each GraphicsDevice * - * @type {Map} + * @type {Map} */ _cache = new Map(); /** * Returns the resources for the supplied device. * - * @param {import('./graphics-device.js').GraphicsDevice} device - The graphics device. + * @param {GraphicsDevice} device - The graphics device. * @param {() => any} onCreate - A function that creates the resource for the device. * @returns {any} The resource for the device. */ @@ -39,7 +43,7 @@ class DeviceCache { /** * Destroys and removes the content of the cache associated with the device * - * @param {import('./graphics-device.js').GraphicsDevice} device - The graphics device. + * @param {GraphicsDevice} device - The graphics device. */ remove(device) { this._cache.get(device)?.destroy?.(device); diff --git a/src/platform/graphics/dynamic-buffer.js b/src/platform/graphics/dynamic-buffer.js index c8122250515..ddad6795974 100644 --- a/src/platform/graphics/dynamic-buffer.js +++ b/src/platform/graphics/dynamic-buffer.js @@ -3,11 +3,15 @@ import { BindGroupFormat, BindUniformBufferFormat } from './bind-group-format.js import { BindGroup } from './bind-group.js'; import { SHADERSTAGE_FRAGMENT, SHADERSTAGE_VERTEX, UNIFORM_BUFFER_DEFAULT_SLOT_NAME } from './constants.js'; +/** + * @import { GraphicsDevice } from './graphics-device.js' + */ + /** * A base class representing a single per platform buffer. */ class DynamicBuffer { - /** @type {import('./graphics-device.js').GraphicsDevice} */ + /** @type {GraphicsDevice} */ device; /** diff --git a/src/platform/graphics/dynamic-buffers.js b/src/platform/graphics/dynamic-buffers.js index 37e357e18cf..4837c310c0e 100644 --- a/src/platform/graphics/dynamic-buffers.js +++ b/src/platform/graphics/dynamic-buffers.js @@ -1,14 +1,19 @@ import { Debug } from '../../core/debug.js'; import { math } from '../../core/math/math.js'; +/** + * @import { DynamicBuffer } from './dynamic-buffer.js' + * @import { GraphicsDevice } from './graphics-device.js' + */ + /** * A container for storing the used areas of a pair of staging and gpu buffers. */ class UsedBuffer { - /** @type {import('./dynamic-buffer.js').DynamicBuffer} */ + /** @type {DynamicBuffer} */ gpuBuffer; - /** @type {import('./dynamic-buffer.js').DynamicBuffer} */ + /** @type {DynamicBuffer} */ stagingBuffer; /** @@ -41,7 +46,7 @@ class DynamicBufferAllocation { /** * The gpu buffer this allocation will be copied to. * - * @type {import('./dynamic-buffer.js').DynamicBuffer} + * @type {DynamicBuffer} */ gpuBuffer; @@ -73,14 +78,14 @@ class DynamicBuffers { /** * Internally allocated gpu buffers. * - * @type {import('./dynamic-buffer.js').DynamicBuffer[]} + * @type {DynamicBuffer[]} */ gpuBuffers = []; /** * Internally allocated staging buffers (CPU writable) * - * @type {import('./dynamic-buffer.js').DynamicBuffer[]} + * @type {DynamicBuffer[]} */ stagingBuffers = []; @@ -97,7 +102,7 @@ class DynamicBuffers { /** * Create the system of dynamic buffers. * - * @param {import('./graphics-device.js').GraphicsDevice} device - The graphics device. + * @param {GraphicsDevice} device - The graphics device. * @param {number} bufferSize - The size of the underlying large buffers. * @param {number} bufferAlignment - Alignment of each allocation. */ diff --git a/src/platform/graphics/graphics-device.js b/src/platform/graphics/graphics-device.js index cecc29e780c..b5104a5d61b 100644 --- a/src/platform/graphics/graphics-device.js +++ b/src/platform/graphics/graphics-device.js @@ -6,7 +6,6 @@ import { Vec2 } from '../../core/math/vec2.js'; import { Tracing } from '../../core/tracing.js'; import { Color } from '../../core/math/color.js'; import { TRACEID_TEXTURES } from '../../core/constants.js'; - import { CULLFACE_BACK, CLEARFLAG_COLOR, CLEARFLAG_DEPTH, @@ -19,6 +18,17 @@ import { VertexBuffer } from './vertex-buffer.js'; import { VertexFormat } from './vertex-format.js'; import { StencilParameters } from './stencil-parameters.js'; +/** + * @import { Compute } from './compute.js' + * @import { DEVICETYPE_WEBGL2, DEVICETYPE_WEBGPU } from './constants.js' + * @import { DynamicBuffers } from './dynamic-buffers.js' + * @import { GpuProfiler } from './gpu-profiler.js' + * @import { IndexBuffer } from './index-buffer.js' + * @import { RenderTarget } from './render-target.js' + * @import { Shader } from './shader.js' + * @import { Texture } from './texture.js' + */ + /** * The graphics device manages the underlying graphics context. It is responsible for submitting * render state changes and graphics primitives to the hardware. A graphics device is tied to a @@ -50,7 +60,7 @@ class GraphicsDevice extends EventHandler { /** * The render target representing the main back-buffer. * - * @type {import('./render-target.js').RenderTarget|null} + * @type {RenderTarget|null} * @ignore */ backBuffer = null; @@ -191,7 +201,7 @@ class GraphicsDevice extends EventHandler { /** * Currently active render target. * - * @type {import('./render-target.js').RenderTarget|null} + * @type {RenderTarget|null} * @ignore */ renderTarget = null; @@ -199,7 +209,7 @@ class GraphicsDevice extends EventHandler { /** * Array of objects that need to be re-initialized after a context restore event * - * @type {import('./shader.js').Shader[]} + * @type {Shader[]} * @ignore */ shaders = []; @@ -207,7 +217,7 @@ class GraphicsDevice extends EventHandler { /** * An array of currently created textures. * - * @type {import('./texture.js').Texture[]} + * @type {Texture[]} * @ignore */ textures = []; @@ -215,7 +225,7 @@ class GraphicsDevice extends EventHandler { /** * A set of currently created render targets. * - * @type {Set} + * @type {Set} * @ignore */ targets = new Set(); @@ -327,7 +337,7 @@ class GraphicsDevice extends EventHandler { /** * The dynamic buffer manager. * - * @type {import('./dynamic-buffers.js').DynamicBuffers} + * @type {DynamicBuffers} * @ignore */ dynamicBuffers; @@ -335,7 +345,7 @@ class GraphicsDevice extends EventHandler { /** * The GPU profiler. * - * @type {import('./gpu-profiler.js').GpuProfiler} + * @type {GpuProfiler} */ gpuProfiler; @@ -596,8 +606,7 @@ class GraphicsDevice extends EventHandler { * Sets the specified render target on the device. If null is passed as a parameter, the back * buffer becomes the current target for all rendering operations. * - * @param {import('./render-target.js').RenderTarget|null} renderTarget - The render target to - * activate. + * @param {RenderTarget|null} renderTarget - The render target to activate. * @example * // Set a render target to receive all rendering output * device.setRenderTarget(renderTarget); @@ -614,8 +623,7 @@ class GraphicsDevice extends EventHandler { * {@link GraphicsDevice#draw}, the specified index buffer will be used to provide index data * for any indexed primitives. * - * @param {import('./index-buffer.js').IndexBuffer|null} indexBuffer - The index buffer to assign to - * the device. + * @param {IndexBuffer|null} indexBuffer - The index buffer to assign to the device. */ setIndexBuffer(indexBuffer) { // Store the index buffer @@ -627,8 +635,7 @@ class GraphicsDevice extends EventHandler { * {@link GraphicsDevice#draw}, the specified vertex buffer(s) will be used to provide vertex * data for any primitives. * - * @param {import('./vertex-buffer.js').VertexBuffer} vertexBuffer - The vertex buffer to - * assign to the device. + * @param {VertexBuffer} vertexBuffer - The vertex buffer to assign to the device. */ setVertexBuffer(vertexBuffer) { @@ -649,7 +656,7 @@ class GraphicsDevice extends EventHandler { /** * Queries the currently set render target on the device. * - * @returns {import('./render-target.js').RenderTarget} The current render target. + * @returns {RenderTarget} The current render target. * @example * // Get the current render target * const renderTarget = device.getRenderTarget(); @@ -661,8 +668,7 @@ class GraphicsDevice extends EventHandler { /** * Initialize render target before it can be used. * - * @param {import('./render-target.js').RenderTarget} target - The render target to be - * initialized. + * @param {RenderTarget} target - The render target to be initialized. * @ignore */ initRenderTarget(target) { @@ -810,7 +816,7 @@ class GraphicsDevice extends EventHandler { * - {@link DEVICETYPE_WEBGL2} * - {@link DEVICETYPE_WEBGPU} * - * @type {import('./constants.js').DEVICETYPE_WEBGL2 | import('./constants.js').DEVICETYPE_WEBGPU} + * @type {DEVICETYPE_WEBGL2|DEVICETYPE_WEBGPU} */ get deviceType() { return this._deviceType; @@ -868,8 +874,7 @@ class GraphicsDevice extends EventHandler { /** * Dispatch multiple compute shaders inside a single compute shader pass. * - * @param {Array} computes - An array of compute shaders to - * dispatch. + * @param {Array} computes - An array of compute shaders to dispatch. */ computeDispatch(computes) { } @@ -878,6 +883,7 @@ class GraphicsDevice extends EventHandler { * Get a renderable HDR pixel format supported by the graphics device. * * Note: + * * - When the `filterable` parameter is set to false, this function returns one of the supported * formats on the majority of devices apart from some very old iOS and Android devices (99%). * - When the `filterable` parameter is set to true, the function returns a format on a diff --git a/src/platform/graphics/index-buffer.js b/src/platform/graphics/index-buffer.js index cd262f75a1b..510c31dd3ea 100644 --- a/src/platform/graphics/index-buffer.js +++ b/src/platform/graphics/index-buffer.js @@ -1,5 +1,10 @@ import { Debug } from '../../core/debug.js'; import { TRACEID_VRAM_IB } from '../../core/constants.js'; + +/** + * @import { GraphicsDevice } from './graphics-device.js' + */ + import { BUFFER_STATIC, INDEXFORMAT_UINT16, INDEXFORMAT_UINT32, typedArrayIndexFormatsByteSize } from './constants.js'; @@ -18,8 +23,7 @@ class IndexBuffer { /** * Create a new IndexBuffer instance. * - * @param {import('./graphics-device.js').GraphicsDevice} graphicsDevice - The graphics device - * used to manage this index buffer. + * @param {GraphicsDevice} graphicsDevice - The graphics device used to manage this index buffer. * @param {number} format - The type of each index to be stored in the index buffer. Can be: * * - {@link INDEXFORMAT_UINT8} diff --git a/src/platform/graphics/render-pass.js b/src/platform/graphics/render-pass.js index 88f9556bac1..4cc3b12754b 100644 --- a/src/platform/graphics/render-pass.js +++ b/src/platform/graphics/render-pass.js @@ -3,6 +3,12 @@ import { Tracing } from '../../core/tracing.js'; import { Color } from '../../core/math/color.js'; import { TRACEID_RENDER_PASS, TRACEID_RENDER_PASS_DETAIL } from '../../core/constants.js'; +/** + * @import { GraphicsDevice } from '../graphics/graphics-device.js' + * @import { RenderTarget } from '../graphics/render-target.js' + * @import { Texture } from './texture.js' + */ + class ColorAttachmentOps { /** * A color used to clear the color attachment when the clear is enabled. @@ -16,12 +22,11 @@ class ColorAttachmentOps { clear = false; /** - * True if the attachment needs to be stored after the render pass. False - * if it can be discarded. - * Note: This relates to the surface that is getting rendered to, and can be either - * single or multi-sampled. Further, if a multi-sampled surface is used, the resolve - * flag further specifies if this gets resolved to a single-sampled surface. This - * behavior matches the WebGPU specification. + * True if the attachment needs to be stored after the render pass. False if it can be + * discarded. Note: This relates to the surface that is getting rendered to, and can be either + * single or multi-sampled. Further, if a multi-sampled surface is used, the resolve flag + * further specifies if this gets resolved to a single-sampled surface. This behavior matches + * the WebGPU specification. * * @type {boolean} */ @@ -95,7 +100,7 @@ class RenderPass { /** * The graphics device. * - * @type {import('../graphics/graphics-device.js').GraphicsDevice} + * @type {GraphicsDevice} */ device; @@ -115,10 +120,12 @@ class RenderPass { /** * The render target for this render pass: - * - `undefined`: render pass does not render to any render target - * - `null`: render pass renders to the backbuffer - * - Otherwise, renders to the provided RT. - * @type {import('../graphics/render-target.js').RenderTarget|null|undefined} + * + * - `undefined`: render pass does not render to any render target + * - `null`: render pass renders to the backbuffer + * - Otherwise, renders to the provided RT. + * + * @type {RenderTarget|null|undefined} */ renderTarget; @@ -188,7 +195,7 @@ class RenderPass { /** * Creates an instance of the RenderPass. * - * @param {import('../graphics/graphics-device.js').GraphicsDevice} graphicsDevice - The + * @param {GraphicsDevice} graphicsDevice - The * graphics device. */ constructor(graphicsDevice) { @@ -221,14 +228,13 @@ class RenderPass { } /** - * @param {import('../graphics/render-target.js').RenderTarget|null} [renderTarget] - The render - * target to render into (output). This function should be called only for render passes which - * use render target, or passes which render directly into the default framebuffer, in which - * case a null or undefined render target is expected. + * @param {RenderTarget|null} [renderTarget] - The render target to render into (output). This + * function should be called only for render passes which use render target, or passes which + * render directly into the default framebuffer, in which case a null or undefined render + * target is expected. * @param {object} [options] - Object for passing optional arguments. - * @param {import('./texture.js').Texture} [options.resizeSource] - A texture to use as a source - * for the automatic render target resize operation. If not provided, no automatic resizing - * takes place. + * @param {Texture} [options.resizeSource] - A texture to use as a source for the automatic + * render target resize operation. If not provided, no automatic resizing takes place. * @param {number} [options.scaleX] - The scale factor for the render target width. Defaults to 1. * @param {number} [options.scaleY] - The scale factor for the render target height. Defaults to 1. */ @@ -347,8 +353,8 @@ class RenderPass { /** * Mark render pass as clearing the full stencil buffer. * - * @param {number|undefined} stencilValue - The stencil value to clear to, or undefined to preserve the - * existing content. + * @param {number|undefined} stencilValue - The stencil value to clear to, or undefined to + * preserve the existing content. */ setClearStencil(stencilValue) { if (stencilValue) diff --git a/src/platform/graphics/render-target.js b/src/platform/graphics/render-target.js index f0a40562a34..2b4a92bfe24 100644 --- a/src/platform/graphics/render-target.js +++ b/src/platform/graphics/render-target.js @@ -4,6 +4,10 @@ import { PIXELFORMAT_DEPTH, PIXELFORMAT_DEPTHSTENCIL, isSrgbPixelFormat } from ' import { DebugGraphics } from './debug-graphics.js'; import { GraphicsDevice } from './graphics-device.js'; +/** + * @import { Texture } from './texture.js' + */ + let id = 0; /** @@ -20,25 +24,25 @@ class RenderTarget { name; /** - * @type {import('./graphics-device.js').GraphicsDevice} + * @type {GraphicsDevice} * @private */ _device; /** - * @type {import('./texture.js').Texture} + * @type {Texture} * @private */ _colorBuffer; /** - * @type {import('./texture.js').Texture[]} + * @type {Texture[]} * @private */ _colorBuffers; /** - * @type {import('./texture.js').Texture} + * @type {Texture} * @private */ _depthBuffer; @@ -79,17 +83,16 @@ class RenderTarget { * @param {object} [options] - Object for passing optional arguments. * @param {boolean} [options.autoResolve] - If samples > 1, enables or disables automatic MSAA * resolve after rendering to this RT (see {@link RenderTarget#resolve}). Defaults to true. - * @param {import('./texture.js').Texture} [options.colorBuffer] - The texture that this render - * target will treat as a rendering surface. - * @param {import('./texture.js').Texture[]} [options.colorBuffers] - The textures that this - * render target will treat as a rendering surfaces. If this option is set, the colorBuffer - * option is ignored. + * @param {Texture} [options.colorBuffer] - The texture that this render target will treat as a + * rendering surface. + * @param {Texture[]} [options.colorBuffers] - The textures that this render target will treat + * as a rendering surfaces. If this option is set, the colorBuffer option is ignored. * @param {boolean} [options.depth] - If set to true, depth buffer will be created. Defaults to * true. Ignored if depthBuffer is defined. - * @param {import('./texture.js').Texture} [options.depthBuffer] - The texture that this render - * target will treat as a depth/stencil surface (WebGL2 only). If set, the 'depth' and - * 'stencil' properties are ignored. Texture must have {@link PIXELFORMAT_DEPTH} or - * {@link PIXELFORMAT_DEPTHSTENCIL} format. + * @param {Texture} [options.depthBuffer] - The texture that this render target will treat as a + * depth/stencil surface (WebGL2 only). If set, the 'depth' and 'stencil' properties are + * ignored. Texture must have {@link PIXELFORMAT_DEPTH} or {@link PIXELFORMAT_DEPTHSTENCIL} + * format. * @param {number} [options.face] - If the colorBuffer parameter is a cubemap, use this option * to specify the face of the cubemap to render to. Can be: * @@ -422,7 +425,7 @@ class RenderTarget { /** * Color buffer set up on the render target. * - * @type {import('./texture.js').Texture} + * @type {Texture} */ get colorBuffer() { return this._colorBuffer; @@ -432,7 +435,7 @@ class RenderTarget { * Accessor for multiple render target color buffers. * * @param {*} index - Index of the color buffer to get. - * @returns {import('./texture.js').Texture} - Color buffer at the specified index. + * @returns {Texture} - Color buffer at the specified index. */ getColorBuffer(index) { return this._colorBuffers?.[index]; @@ -442,7 +445,7 @@ class RenderTarget { * Depth buffer set up on the render target. Only available, if depthBuffer was set in * constructor. Not available if depth property was used instead. * - * @type {import('./texture.js').Texture} + * @type {Texture} */ get depthBuffer() { return this._depthBuffer; diff --git a/src/platform/graphics/shader-chunks/frag/gles3.js b/src/platform/graphics/shader-chunks/frag/gles3.js index 2bcd27f3be6..b3ef3658bfc 100644 --- a/src/platform/graphics/shader-chunks/frag/gles3.js +++ b/src/platform/graphics/shader-chunks/frag/gles3.js @@ -89,6 +89,4 @@ layout(location = 7) out highp outType_7 pc_fragColor7; #define TEXTURE_ACCEPT_HIGHP(name) highp sampler2D name #define GL2 -#define SUPPORTS_TEXLOD -#define SUPPORTS_MRT `; diff --git a/src/platform/graphics/shader-chunks/frag/webgpu.js b/src/platform/graphics/shader-chunks/frag/webgpu.js index 1100cb5c955..2a1d6b0d21b 100644 --- a/src/platform/graphics/shader-chunks/frag/webgpu.js +++ b/src/platform/graphics/shader-chunks/frag/webgpu.js @@ -74,6 +74,4 @@ layout(location = 7) out highp outType_7 pc_fragColor7; #define GL2 #define WEBGPU -#define SUPPORTS_TEXLOD -#define SUPPORTS_MRT `; diff --git a/src/platform/graphics/shader-processor-options.js b/src/platform/graphics/shader-processor-options.js index 97e86a5917b..df7489a1092 100644 --- a/src/platform/graphics/shader-processor-options.js +++ b/src/platform/graphics/shader-processor-options.js @@ -1,29 +1,33 @@ import { BINDGROUP_VIEW } from "./constants.js"; +/** + * @import { BindGroupFormat } from './bind-group-format.js' + * @import { GraphicsDevice } from './graphics-device.js' + * @import { UniformBufferFormat } from './uniform-buffer-format.js' + * @import { VertexFormat } from './vertex-format.js' + */ + /** * Options to drive shader processing to add support for bind groups and uniform buffers. * * @ignore */ class ShaderProcessorOptions { - /** @type {import('./uniform-buffer-format.js').UniformBufferFormat[]} */ + /** @type {UniformBufferFormat[]} */ uniformFormats = []; - /** @type {import('./bind-group-format.js').BindGroupFormat[]} */ + /** @type {BindGroupFormat[]} */ bindGroupFormats = []; - /** @type {import('./vertex-format.js').VertexFormat[]} */ + /** @type {VertexFormat[]} */ vertexFormat; /** * Constructs shader processing options, used to process the shader for uniform buffer support. * - * @param {import('./uniform-buffer-format.js').UniformBufferFormat} [viewUniformFormat] - Format - * of the uniform buffer. - * @param {import('./bind-group-format.js').BindGroupFormat} [viewBindGroupFormat] - Format of - * the bind group. - * @param {import('./vertex-format.js').VertexFormat} [vertexFormat] - Format of the vertex - * buffer. + * @param {UniformBufferFormat} [viewUniformFormat] - Format of the uniform buffer. + * @param {BindGroupFormat} [viewBindGroupFormat] - Format of the bind group. + * @param {VertexFormat} [vertexFormat] - Format of the vertex buffer. */ constructor(viewUniformFormat, viewBindGroupFormat, vertexFormat) { @@ -77,7 +81,7 @@ class ShaderProcessorOptions { /** * Generate unique key representing the processing options. * - * @param {import('./graphics-device.js').GraphicsDevice} device - The device. + * @param {GraphicsDevice} device - The device. * @returns {string} - Returns the key. */ generateKey(device) { diff --git a/src/platform/graphics/shader-processor.js b/src/platform/graphics/shader-processor.js index c29471df683..2881c3a872c 100644 --- a/src/platform/graphics/shader-processor.js +++ b/src/platform/graphics/shader-processor.js @@ -10,6 +10,12 @@ import { import { UniformFormat, UniformBufferFormat } from './uniform-buffer-format.js'; import { BindGroupFormat, BindTextureFormat } from './bind-group-format.js'; +/** + * @import { GraphicsDevice } from './graphics-device.js' + * @import { ShaderProcessorOptions } from './shader-processor-options.js' + * @import { Shader } from './shader.js' + */ + // accepted keywords // TODO: 'out' keyword is not in the list, as handling it is more complicated due // to 'out' keyword also being used to mark output only function parameters. @@ -100,9 +106,9 @@ class ShaderProcessor { /** * Process the shader. * - * @param {import('./graphics-device.js').GraphicsDevice} device - The graphics device. + * @param {GraphicsDevice} device - The graphics device. * @param {object} shaderDefinition - The shader definition. - * @param {import('./shader.js').Shader} shader - The shader definition. + * @param {Shader} shader - The shader definition. * @returns {object} - The processed shader data. */ static run(device, shaderDefinition, shader) { @@ -227,11 +233,10 @@ class ShaderProcessor { * All leftover uniforms create uniform buffer and bind group for the mesh itself, containing * uniforms that change on the level of the mesh. * - * @param {import('./graphics-device.js').GraphicsDevice} device - The graphics device. + * @param {GraphicsDevice} device - The graphics device. * @param {Array} uniforms - Lines containing uniforms. - * @param {import('./shader-processor-options.js').ShaderProcessorOptions} processingOptions - - * Uniform formats. - * @param {import('./shader.js').Shader} shader - The shader definition. + * @param {ShaderProcessorOptions} processingOptions - Uniform formats. + * @param {Shader} shader - The shader definition. * @returns {object} - The uniform data. Returns a shader code block containing uniforms, to be * inserted into the shader, as well as generated uniform format structures for the mesh level. */ diff --git a/src/platform/graphics/shader-utils.js b/src/platform/graphics/shader-utils.js index 965dec0852b..0e60c569fca 100644 --- a/src/platform/graphics/shader-utils.js +++ b/src/platform/graphics/shader-utils.js @@ -4,13 +4,16 @@ import { SEMANTIC_TEXCOORD3, SEMANTIC_TEXCOORD4, SEMANTIC_TEXCOORD5, SEMANTIC_TEXCOORD6, SEMANTIC_TEXCOORD7, SEMANTIC_COLOR, SEMANTIC_BLENDINDICES, SEMANTIC_BLENDWEIGHT } from './constants.js'; - import gles3FS from './shader-chunks/frag/gles3.js'; import gles3VS from './shader-chunks/vert/gles3.js'; import webgpuFS from './shader-chunks/frag/webgpu.js'; import webgpuVS from './shader-chunks/vert/webgpu.js'; import sharedFS from './shader-chunks/frag/shared.js'; +/** + * @import { GraphicsDevice } from './graphics-device.js' + */ + const _attrib2Semantic = { vertex_position: SEMANTIC_POSITION, vertex_normal: SEMANTIC_NORMAL, @@ -37,7 +40,7 @@ class ShaderUtils { /** * Creates a shader definition. * - * @param {import('./graphics-device.js').GraphicsDevice} device - The graphics device. + * @param {GraphicsDevice} device - The graphics device. * @param {object} options - Object for passing optional arguments. * @param {string} [options.name] - A name of the shader. * @param {object} [options.attributes] - Attributes. Will be extracted from the vertexCode if diff --git a/src/platform/graphics/shader.js b/src/platform/graphics/shader.js index b3692897ad0..60290fe60ea 100644 --- a/src/platform/graphics/shader.js +++ b/src/platform/graphics/shader.js @@ -4,6 +4,12 @@ import { platform } from '../../core/platform.js'; import { Preprocessor } from '../../core/preprocessor.js'; import { DebugGraphics } from './debug-graphics.js'; +/** + * @import { BindGroupFormat } from './bind-group-format.js' + * @import { GraphicsDevice } from './graphics-device.js' + * @import { UniformBufferFormat } from './uniform-buffer-format.js' + */ + let id = 0; /** @@ -20,7 +26,7 @@ class Shader { /** * Format of the uniform buffer for mesh bind group. * - * @type {import('./uniform-buffer-format.js').UniformBufferFormat} + * @type {UniformBufferFormat} * @ignore */ meshUniformBufferFormat; @@ -28,7 +34,7 @@ class Shader { /** * Format of the bind group for the mesh bind group. * - * @type {import('./bind-group-format.js').BindGroupFormat} + * @type {BindGroupFormat} * @ignore */ meshBindGroupFormat; @@ -39,14 +45,13 @@ class Shader { * Consider {@link createShaderFromCode} as a simpler and more powerful way to create * a shader. * - * @param {import('./graphics-device.js').GraphicsDevice} graphicsDevice - The graphics device - * used to manage this shader. + * @param {GraphicsDevice} graphicsDevice - The graphics device used to manage this shader. * @param {object} definition - The shader definition from which to build the shader. * @param {string} [definition.name] - The name of the shader. * @param {Object} [definition.attributes] - Object detailing the mapping of * vertex shader attribute names to semantics SEMANTIC_*. This enables the engine to match - * vertex buffer data as inputs to the shader. When not specified, rendering without - * vertex buffer is assumed. + * vertex buffer data as inputs to the shader. When not specified, rendering without vertex + * buffer is assumed. * @param {string} [definition.vshader] - Vertex shader source (GLSL code). Optional when * compute shader is specified. * @param {string} [definition.fshader] - Fragment shader source (GLSL code). Optional when diff --git a/src/platform/graphics/storage-buffer.js b/src/platform/graphics/storage-buffer.js index 541c9950f10..5e699bd542c 100644 --- a/src/platform/graphics/storage-buffer.js +++ b/src/platform/graphics/storage-buffer.js @@ -2,6 +2,10 @@ import { Debug } from '../../core/debug.js'; import { TRACEID_VRAM_SB } from '../../core/constants.js'; import { BUFFERUSAGE_STORAGE } from './constants.js'; +/** + * @import { GraphicsDevice } from './graphics-device.js' + */ + let id = 0; /** @@ -17,11 +21,10 @@ class StorageBuffer { /** * Create a new StorageBuffer instance. * - * @param {import('./graphics-device.js').GraphicsDevice} graphicsDevice - The graphics device - * used to manage this storage buffer. + * @param {GraphicsDevice} graphicsDevice - The graphics device used to manage this storage buffer. * @param {number} byteSize - The size of the storage buffer in bytes. - * @param {number} [bufferUsage] - The usage type of the storage buffer. Can be a combination of - * {@link BUFFERUSAGE_READ}, {@link BUFFERUSAGE_WRITE}, {@link BUFFERUSAGE_COPY_SRC} and + * @param {number} [bufferUsage] - The usage type of the storage buffer. Can be a combination + * of {@link BUFFERUSAGE_READ}, {@link BUFFERUSAGE_WRITE}, {@link BUFFERUSAGE_COPY_SRC} and * {@link BUFFERUSAGE_COPY_DST} flags. This parameter can be omitted if no special usage is * required. */ @@ -64,12 +67,12 @@ class StorageBuffer { * @param {number} [offset] - The byte offset of data to read. Defaults to 0. * @param {number} [size] - The byte size of data to read. Defaults to the full size of the * buffer minus the offset. - * @param {ArrayBufferView|null} [data] - Typed array to populate with the data read from the storage - * buffer. When typed array is supplied, enough space needs to be reserved, otherwise only - * partial data is copied. If not specified, the data is returned in an Uint8Array. Defaults to - * null. - * @returns {Promise} A promise that resolves with the data read from the storage - * buffer. + * @param {ArrayBufferView|null} [data] - Typed array to populate with the data read from the + * storage buffer. When typed array is supplied, enough space needs to be reserved, otherwise + * only partial data is copied. If not specified, the data is returned in an Uint8Array. + * Defaults to null. + * @returns {Promise} A promise that resolves with the data read from the + * storage buffer. * @ignore */ read(offset = 0, size = this.byteSize, data = null) { diff --git a/src/platform/graphics/texture.js b/src/platform/graphics/texture.js index c8b692ebb5d..d919545d8e6 100644 --- a/src/platform/graphics/texture.js +++ b/src/platform/graphics/texture.js @@ -1,8 +1,6 @@ import { Debug } from '../../core/debug.js'; import { TRACEID_TEXTURE_ALLOC, TRACEID_VRAM_TEXTURE } from '../../core/constants.js'; import { math } from '../../core/math/math.js'; - -import { TextureUtils } from './texture-utils.js'; import { isCompressedPixelFormat, getPixelFormatArrayType, @@ -21,6 +19,11 @@ import { TEXTUREDIMENSION_2D_ARRAY, TEXTUREDIMENSION_CUBE } from './constants.js'; +import { TextureUtils } from './texture-utils.js'; + +/** + * @import { GraphicsDevice } from './graphics-device.js' + */ let id = 0; @@ -96,8 +99,7 @@ class Texture { /** * Create a new Texture instance. * - * @param {import('./graphics-device.js').GraphicsDevice} graphicsDevice - The graphics device - * used to manage this texture. + * @param {GraphicsDevice} graphicsDevice - The graphics device used to manage this texture. * @param {object} [options] - Object for passing optional arguments. * @param {string} [options.name] - The name of the texture. Defaults to null. * @param {number} [options.width] - The width of the texture in pixels. Defaults to 4. diff --git a/src/platform/graphics/transform-feedback.js b/src/platform/graphics/transform-feedback.js index f844f8d723b..5c0258d3617 100644 --- a/src/platform/graphics/transform-feedback.js +++ b/src/platform/graphics/transform-feedback.js @@ -1,11 +1,14 @@ import { Debug } from '../../core/debug.js'; - import { BUFFER_GPUDYNAMIC, PRIMITIVE_POINTS } from './constants.js'; import { VertexBuffer } from './vertex-buffer.js'; import { DebugGraphics } from './debug-graphics.js'; import { Shader } from './shader.js'; import { ShaderUtils } from './shader-utils.js'; +/** + * @import { GraphicsDevice } from './graphics-device.js' + */ + /** * This object allows you to configure and use the transform feedback feature (WebGL2 only). How to * use: @@ -111,8 +114,7 @@ class TransformFeedback { /** * Creates a transform feedback ready vertex shader from code. * - * @param {import('./graphics-device.js').GraphicsDevice} graphicsDevice - The graphics device - * used by the renderer. + * @param {GraphicsDevice} graphicsDevice - The graphics device used by the renderer. * @param {string} vertexCode - Vertex shader code. Should contain output variables starting with "out_". * @param {string} name - Unique name for caching the shader. * @returns {Shader} A shader to use in the process() function. diff --git a/src/platform/graphics/uniform-buffer-format.js b/src/platform/graphics/uniform-buffer-format.js index 7e895c6358f..c53985ae493 100644 --- a/src/platform/graphics/uniform-buffer-format.js +++ b/src/platform/graphics/uniform-buffer-format.js @@ -12,6 +12,11 @@ import { UNIFORMTYPE_IVEC4ARRAY, UNIFORMTYPE_UVEC4ARRAY, UNIFORMTYPE_BVEC4ARRAY } from './constants.js'; +/** + * @import { GraphicsDevice } from './graphics-device.js' + * @import { ScopeId } from './scope-id.js' + */ + // map of UNIFORMTYPE_*** to number of 32bit components const uniformTypeToNumComponents = []; uniformTypeToNumComponents[UNIFORMTYPE_FLOAT] = 1; @@ -67,7 +72,7 @@ class UniformFormat { offset; /** - * @type {import('./scope-id.js').ScopeId} + * @type {ScopeId} * @ignore */ scopeId; @@ -210,7 +215,7 @@ class UniformBufferFormat { /** * Create a new UniformBufferFormat instance. * - * @param {import('./graphics-device.js').GraphicsDevice} graphicsDevice - The graphics device. + * @param {GraphicsDevice} graphicsDevice - The graphics device. * @param {UniformFormat[]} uniforms - An array of uniforms to be stored in the buffer */ constructor(graphicsDevice, uniforms) { diff --git a/src/platform/graphics/uniform-buffer.js b/src/platform/graphics/uniform-buffer.js index 1a6a3696862..a501fa71d3e 100644 --- a/src/platform/graphics/uniform-buffer.js +++ b/src/platform/graphics/uniform-buffer.js @@ -9,6 +9,13 @@ import { import { DebugGraphics } from './debug-graphics.js'; import { DynamicBufferAllocation } from './dynamic-buffers.js'; +/** + * @import { DynamicBindGroup } from './bind-group.js' + * @import { GraphicsDevice } from './graphics-device.js' + * @import { UniformBufferFormat } from './uniform-buffer-format.js' + * @import { UniformFormat } from './uniform-buffer-format.js' + */ + // Uniform buffer set functions - only implemented for types for which the default // array to buffer copy does not work, or could be slower. const _updateFunctions = []; @@ -227,10 +234,9 @@ class UniformBuffer { /** * Create a new UniformBuffer instance. * - * @param {import('./graphics-device.js').GraphicsDevice} graphicsDevice - The graphics device - * used to manage this uniform buffer. - * @param {import('./uniform-buffer-format.js').UniformBufferFormat} format - Format of the - * uniform buffer. + * @param {GraphicsDevice} graphicsDevice - The graphics device used to manage this uniform + * buffer. + * @param {UniformBufferFormat} format - Format of the uniform buffer. * @param {boolean} [persistent] - Whether the buffer is persistent. Defaults to true. */ constructor(graphicsDevice, format, persistent = true) { @@ -298,8 +304,7 @@ class UniformBuffer { * Assign a value to the uniform specified by its format. This is the fast version of assigning * a value to a uniform, avoiding any lookups. * - * @param {import('./uniform-buffer-format.js').UniformFormat} uniformFormat - The format of - * the uniform. + * @param {UniformFormat} uniformFormat - The format of the uniform. * @param {any} value - The value to assign to the uniform. */ setUniform(uniformFormat, value) { @@ -369,11 +374,11 @@ class UniformBuffer { } /** - * @param {import('./bind-group.js').DynamicBindGroup} [dynamicBindGroup] - The function fills - * in the info about the dynamic bind group for this frame, which uses this uniform buffer. Only - * used if the uniform buffer is non-persistent. This allows the uniform buffer to be used - * without having to create a bind group for it. Note that the bind group can only contains - * this single uniform buffer, and no other resources. + * @param {DynamicBindGroup} [dynamicBindGroup] - The function fills in the info about the + * dynamic bind group for this frame, which uses this uniform buffer. Only used if the uniform + * buffer is non-persistent. This allows the uniform buffer to be used without having to create + * a bind group for it. Note that the bind group can only contains this single uniform buffer, + * and no other resources. */ update(dynamicBindGroup) { diff --git a/src/platform/graphics/vertex-buffer.js b/src/platform/graphics/vertex-buffer.js index 8228a5036a5..74c4fb66e8f 100644 --- a/src/platform/graphics/vertex-buffer.js +++ b/src/platform/graphics/vertex-buffer.js @@ -2,6 +2,11 @@ import { Debug } from '../../core/debug.js'; import { TRACEID_VRAM_VB } from '../../core/constants.js'; import { BUFFER_STATIC } from './constants.js'; +/** + * @import { GraphicsDevice } from './graphics-device.js' + * @import { VertexFormat } from './vertex-format.js' + */ + let id = 0; /** @@ -16,10 +21,9 @@ class VertexBuffer { /** * Create a new VertexBuffer instance. * - * @param {import('./graphics-device.js').GraphicsDevice} graphicsDevice - The graphics device - * used to manage this vertex buffer. - * @param {import('./vertex-format.js').VertexFormat} format - The vertex format of this vertex + * @param {GraphicsDevice} graphicsDevice - The graphics device used to manage this vertex * buffer. + * @param {VertexFormat} format - The vertex format of this vertex buffer. * @param {number} numVertices - The number of vertices that this vertex buffer will hold. * @param {object} [options] - Object for passing optional arguments. * @param {number} [options.usage] - The usage type of the vertex buffer (see BUFFER_*). @@ -93,8 +97,7 @@ class VertexBuffer { /** * Returns the data format of the specified vertex buffer. * - * @returns {import('./vertex-format.js').VertexFormat} The data format of the specified vertex - * buffer. + * @returns {VertexFormat} The data format of the specified vertex buffer. */ getFormat() { return this.format; diff --git a/src/platform/graphics/vertex-format.js b/src/platform/graphics/vertex-format.js index 933938919da..be05e473b27 100644 --- a/src/platform/graphics/vertex-format.js +++ b/src/platform/graphics/vertex-format.js @@ -1,15 +1,17 @@ import { Debug } from '../../core/debug.js'; import { hashCode } from '../../core/hash.js'; - import { math } from '../../core/math/math.js'; import { StringIds } from '../../core/string-ids.js'; - import { SEMANTIC_TEXCOORD0, SEMANTIC_TEXCOORD1, SEMANTIC_ATTR12, SEMANTIC_ATTR13, SEMANTIC_ATTR14, SEMANTIC_ATTR15, SEMANTIC_COLOR, SEMANTIC_TANGENT, TYPE_FLOAT32, typedArrayTypesByteSize, vertexTypesNames } from './constants.js'; import { DeviceCache } from './device-cache.js'; +/** + * @import { GraphicsDevice } from './graphics-device.js' + */ + const stringIds = new StringIds(); const webgpuValidElementSizes = [2, 4, 8, 12, 16]; @@ -111,8 +113,8 @@ class VertexFormat { /** * Create a new VertexFormat instance. * - * @param {import('./graphics-device.js').GraphicsDevice} graphicsDevice - The graphics device - * used to manage this vertex format. + * @param {GraphicsDevice} graphicsDevice - The graphics device used to manage this vertex + * format. * @param {AttributeDescription[]} description - An array of vertex attribute descriptions. * @param {number} [vertexCount] - When specified, vertex format will be set up for * non-interleaved format with a specified number of vertices. (example: PPPPNNNNCCCC), where @@ -217,9 +219,8 @@ class VertexFormat { /** * The {@link VertexFormat} used to store matrices of type {@link Mat4} for hardware instancing. * - * @param {import('./graphics-device.js').GraphicsDevice} graphicsDevice - The graphics device - * used to create this vertex format. - * + * @param {GraphicsDevice} graphicsDevice - The graphics device used to create this vertex + * format. * @returns {VertexFormat} The default instancing vertex format. */ static getDefaultInstancingFormat(graphicsDevice) { diff --git a/src/platform/graphics/vertex-iterator.js b/src/platform/graphics/vertex-iterator.js index 6aafca85b12..c59f69b7002 100644 --- a/src/platform/graphics/vertex-iterator.js +++ b/src/platform/graphics/vertex-iterator.js @@ -1,6 +1,12 @@ import { Debug } from '../../core/debug.js'; import { typedArrayTypes } from './constants.js'; +/** + * @import { ScopeId } from './scope-id.js' + * @import { VertexBuffer } from './vertex-buffer.js' + * @import { VertexFormat } from './vertex-format.js' + */ + function set1(a) { this.array[this.index] = a; } @@ -116,11 +122,11 @@ class VertexIteratorAccessor { * that are not relevant to this attribute. * @param {number} vertexElement.stride - The number of total bytes that are between the start * of one vertex, and the start of the next. - * @param {import('./scope-id.js').ScopeId} vertexElement.scopeId - The shader input variable - * corresponding to the attribute. + * @param {ScopeId} vertexElement.scopeId - The shader input variable corresponding to the + * attribute. * @param {number} vertexElement.size - The size of the attribute in bytes. - * @param {import('./vertex-format.js').VertexFormat} vertexFormat - A vertex format that - * defines the layout of vertex data inside the buffer. + * @param {VertexFormat} vertexFormat - A vertex format that defines the layout of vertex data + * inside the buffer. */ constructor(buffer, vertexElement, vertexFormat) { this.index = 0; @@ -220,8 +226,7 @@ class VertexIterator { /** * Create a new VertexIterator instance. * - * @param {import('./vertex-buffer.js').VertexBuffer} vertexBuffer - The vertex buffer to be - * iterated. + * @param {VertexBuffer} vertexBuffer - The vertex buffer to be iterated. */ constructor(vertexBuffer) { // Store the vertex buffer @@ -253,8 +258,7 @@ class VertexIterator { /** * Moves the vertex iterator on to the next vertex. * - * @param {number} [count] - Optional number of steps to move on when calling next. Defaults to - * 1. + * @param {number} [count] - Number of steps to move on when calling next. Defaults to 1. * @example * const iterator = new pc.VertexIterator(vertexBuffer); * iterator.element[pc.SEMANTIC_POSITION].set(-0.9, -0.9, 0.0); @@ -357,8 +361,7 @@ class VertexIterator { * only part of the data gets copied out (typed arrays ignore read/write out of range). * * @param {string} semantic - The semantic of the vertex element to read. - * @param {number[]|ArrayBufferView} data - The - * array to receive the data. + * @param {number[]|ArrayBufferView} data - The array to receive the data. * @returns {number} The number of vertices read. * @ignore */ diff --git a/src/platform/graphics/webgl/webgl-graphics-device.js b/src/platform/graphics/webgl/webgl-graphics-device.js index 19656534f04..5e395d05ecb 100644 --- a/src/platform/graphics/webgl/webgl-graphics-device.js +++ b/src/platform/graphics/webgl/webgl-graphics-device.js @@ -2,7 +2,6 @@ import { math } from '../../../core/math/math.js'; import { Debug } from '../../../core/debug.js'; import { platform } from '../../../core/platform.js'; import { Color } from '../../../core/math/color.js'; - import { CLEARFLAG_COLOR, CLEARFLAG_DEPTH, CLEARFLAG_STENCIL, CULLFACE_NONE, @@ -26,12 +25,10 @@ import { PRIMITIVE_TRISTRIP, DEVICETYPE_WEBGL2 } from '../constants.js'; - import { GraphicsDevice } from '../graphics-device.js'; import { RenderTarget } from '../render-target.js'; import { Texture } from '../texture.js'; import { DebugGraphics } from '../debug-graphics.js'; - import { WebglVertexBuffer } from './webgl-vertex-buffer.js'; import { WebglIndexBuffer } from './webgl-index-buffer.js'; import { WebglShader } from './webgl-shader.js'; @@ -45,6 +42,11 @@ import { StencilParameters } from '../stencil-parameters.js'; import { WebglGpuProfiler } from './webgl-gpu-profiler.js'; import { TextureUtils } from '../texture-utils.js'; +/** + * @import { RenderPass } from '../render-pass.js' + * @import { VertexBuffer } from '../vertex-buffer.js' + */ + const invalidateAttachments = []; const _fullScreenQuadVS = /* glsl */` @@ -1322,7 +1324,7 @@ class WebglGraphicsDevice extends GraphicsDevice { /** * Start a render pass. * - * @param {import('../render-pass.js').RenderPass} renderPass - The render pass to start. + * @param {RenderPass} renderPass - The render pass to start. * @ignore */ startRenderPass(renderPass) { @@ -1385,7 +1387,7 @@ class WebglGraphicsDevice extends GraphicsDevice { /** * End a render pass. * - * @param {import('../render-pass.js').RenderPass} renderPass - The render pass to end. + * @param {RenderPass} renderPass - The render pass to end. * @ignore */ endRenderPass(renderPass) { @@ -1903,11 +1905,14 @@ class WebglGraphicsDevice extends GraphicsDevice { // #if _DEBUG const samplerName = sampler.scopeId.name; - if (samplerName === 'uSceneDepthMap' || samplerName === 'uDepthMap') { - Debug.warnOnce(`A sampler ${samplerName} is used by the shader but a scene depth texture is not available. Use CameraComponent.requestSceneDepthMap / enable Depth Grabpass on the Camera Component to enable it.`); + Debug.assert(samplerName !== 'texture_grabPass', `Engine provided texture with sampler name 'texture_grabPass' is not longer supported, use 'uSceneColorMap' instead`); + Debug.assert(samplerName !== 'uDepthMap', `Engine provided texture with sampler name 'uDepthMap' is not longer supported, use 'uSceneDepthMap' instead`); + + if (samplerName === 'uSceneDepthMap') { + Debug.warnOnce('A sampler uSceneDepthMap is used by the shader but a scene depth texture is not available. Use CameraComponent.requestSceneDepthMap / enable Depth Grabpass on the Camera Component to enable it.'); } - if (samplerName === 'uSceneColorMap' || samplerName === 'texture_grabPass') { - Debug.warnOnce(`A sampler ${samplerName} is used by the shader but a scene color texture is not available. Use CameraComponent.requestSceneColorMap / enable Color Grabpass on the Camera Component to enable it.`); + if (samplerName === 'uSceneColorMap') { + Debug.warnOnce('A sampler uSceneColorMap is used by the shader but a scene color texture is not available. Use CameraComponent.requestSceneColorMap / enable Color Grabpass on the Camera Component to enable it.'); } // #endif @@ -2241,7 +2246,7 @@ class WebglGraphicsDevice extends GraphicsDevice { * Sets the output vertex buffer. It will be written to by a shader with transform feedback * varyings. * - * @param {import('../vertex-buffer.js').VertexBuffer} tf - The output vertex buffer. + * @param {VertexBuffer} tf - The output vertex buffer. * @ignore */ setTransformFeedbackBuffer(tf) { diff --git a/src/platform/graphics/webgl/webgl-render-target.js b/src/platform/graphics/webgl/webgl-render-target.js index 0c68d258708..a3bb32a3c9c 100644 --- a/src/platform/graphics/webgl/webgl-render-target.js +++ b/src/platform/graphics/webgl/webgl-render-target.js @@ -2,6 +2,11 @@ import { Debug } from "../../../core/debug.js"; import { PIXELFORMAT_RGBA8 } from "../constants.js"; import { DebugGraphics } from "../debug-graphics.js"; +/** + * @import { RenderTarget } from '../render-target.js' + * @import { WebglGraphicsDevice } from './webgl-graphics-device.js' + */ + /** * A private class representing a pair of framebuffers, when MSAA is used. */ @@ -318,8 +323,8 @@ class WebglRenderTarget { /** * Checks the completeness status of the currently bound WebGLFramebuffer object. * - * @param {import('./webgl-graphics-device.js').WebglGraphicsDevice} device - The graphics device. - * @param {import('../render-target.js').RenderTarget} target - The render target. + * @param {WebglGraphicsDevice} device - The graphics device. + * @param {RenderTarget} target - The render target. * @param {string} [type] - An optional type string to append to the error message. * @private */ diff --git a/src/platform/graphics/webgl/webgl-shader-input.js b/src/platform/graphics/webgl/webgl-shader-input.js index 547cce67115..da0ad570a03 100644 --- a/src/platform/graphics/webgl/webgl-shader-input.js +++ b/src/platform/graphics/webgl/webgl-shader-input.js @@ -1,6 +1,18 @@ -import { UNIFORMTYPE_FLOAT, UNIFORMTYPE_FLOATARRAY, UNIFORMTYPE_VEC2, UNIFORMTYPE_VEC3, UNIFORMTYPE_VEC4, - UNIFORMTYPE_VEC2ARRAY, UNIFORMTYPE_VEC3ARRAY, UNIFORMTYPE_VEC4ARRAY, UNIFORMTYPE_INT, UNIFORMTYPE_INTARRAY, UNIFORMTYPE_UINT, UNIFORMTYPE_UINTARRAY, UNIFORMTYPE_BOOL, UNIFORMTYPE_BOOLARRAY, UNIFORMTYPE_IVEC2, UNIFORMTYPE_IVEC2ARRAY, UNIFORMTYPE_UVEC2, UNIFORMTYPE_UVEC2ARRAY, UNIFORMTYPE_BVEC2, UNIFORMTYPE_BVEC2ARRAY, UNIFORMTYPE_IVEC3, UNIFORMTYPE_UVEC3, UNIFORMTYPE_BVEC3, UNIFORMTYPE_IVEC4, UNIFORMTYPE_UVEC4, UNIFORMTYPE_BVEC4, UNIFORMTYPE_IVEC3ARRAY, UNIFORMTYPE_UVEC3ARRAY, UNIFORMTYPE_BVEC3ARRAY, UNIFORMTYPE_IVEC4ARRAY, UNIFORMTYPE_UVEC4ARRAY, UNIFORMTYPE_BVEC4ARRAY } from '../constants.js'; import { Version } from '../version.js'; +import { + UNIFORMTYPE_FLOAT, UNIFORMTYPE_FLOATARRAY, UNIFORMTYPE_VEC2, UNIFORMTYPE_VEC3, UNIFORMTYPE_VEC4, + UNIFORMTYPE_VEC2ARRAY, UNIFORMTYPE_VEC3ARRAY, UNIFORMTYPE_VEC4ARRAY, UNIFORMTYPE_INT, + UNIFORMTYPE_INTARRAY, UNIFORMTYPE_UINT, UNIFORMTYPE_UINTARRAY, UNIFORMTYPE_BOOL, + UNIFORMTYPE_BOOLARRAY, UNIFORMTYPE_IVEC2, UNIFORMTYPE_IVEC2ARRAY, UNIFORMTYPE_UVEC2, + UNIFORMTYPE_UVEC2ARRAY, UNIFORMTYPE_BVEC2, UNIFORMTYPE_BVEC2ARRAY, UNIFORMTYPE_IVEC3, + UNIFORMTYPE_UVEC3, UNIFORMTYPE_BVEC3, UNIFORMTYPE_IVEC4, UNIFORMTYPE_UVEC4, UNIFORMTYPE_BVEC4, + UNIFORMTYPE_IVEC3ARRAY, UNIFORMTYPE_UVEC3ARRAY, UNIFORMTYPE_BVEC3ARRAY, UNIFORMTYPE_IVEC4ARRAY, + UNIFORMTYPE_UVEC4ARRAY, UNIFORMTYPE_BVEC4ARRAY +} from '../constants.js'; + +/** + * @import { GraphicsDevice } from '../graphics-device.js' + */ /** * Representation of a shader uniform. @@ -9,8 +21,7 @@ class WebglShaderInput { /** * Create a new WebglShaderInput instance. * - * @param {import('../graphics-device.js').GraphicsDevice} graphicsDevice - The graphics device - * used to manage this shader input. + * @param {GraphicsDevice} graphicsDevice - The graphics device used to manage this shader input. * @param {string} name - The name of the shader input. * @param {number} type - The type of the shader input. * @param {number | WebGLUniformLocation} locationId - The location id of the shader input. diff --git a/src/platform/graphics/webgl/webgl-shader.js b/src/platform/graphics/webgl/webgl-shader.js index 925647bf637..da2e2d04ccf 100644 --- a/src/platform/graphics/webgl/webgl-shader.js +++ b/src/platform/graphics/webgl/webgl-shader.js @@ -1,12 +1,16 @@ import { Debug } from '../../../core/debug.js'; import { TRACEID_SHADER_COMPILE } from '../../../core/constants.js'; import { now } from '../../../core/time.js'; - import { WebglShaderInput } from './webgl-shader-input.js'; import { SHADERTAG_MATERIAL, semanticToLocation } from '../constants.js'; import { DeviceCache } from '../device-cache.js'; import { DebugGraphics } from '../debug-graphics.js'; +/** + * @import { Shader } from '../shader.js' + * @import { WebglGraphicsDevice } from './webgl-graphics-device.js' + */ + let _totalCompileTime = 0; const _vertexShaderBuiltins = new Set([ @@ -60,7 +64,7 @@ class WebglShader { /** * Free the WebGL resources associated with a shader. * - * @param {import('../shader.js').Shader} shader - The shader to free. + * @param {Shader} shader - The shader to free. */ destroy(shader) { if (this.glProgram) { @@ -89,8 +93,8 @@ class WebglShader { /** * Restore shader after the context has been obtained. * - * @param {import('./webgl-graphics-device.js').WebglGraphicsDevice} device - The graphics device. - * @param {import('../shader.js').Shader} shader - The shader to restore. + * @param {WebglGraphicsDevice} device - The graphics device. + * @param {Shader} shader - The shader to restore. */ restoreContext(device, shader) { this.compile(device, shader); @@ -100,8 +104,8 @@ class WebglShader { /** * Compile shader programs. * - * @param {import('./webgl-graphics-device.js').WebglGraphicsDevice} device - The graphics device. - * @param {import('../shader.js').Shader} shader - The shader to compile. + * @param {WebglGraphicsDevice} device - The graphics device. + * @param {Shader} shader - The shader to compile. */ compile(device, shader) { @@ -113,8 +117,8 @@ class WebglShader { /** * Link shader programs. This is called at a later stage, to allow many shaders to compile in parallel. * - * @param {import('./webgl-graphics-device.js').WebglGraphicsDevice} device - The graphics device. - * @param {import('../shader.js').Shader} shader - The shader to compile. + * @param {WebglGraphicsDevice} device - The graphics device. + * @param {Shader} shader - The shader to compile. */ link(device, shader) { @@ -183,7 +187,7 @@ class WebglShader { /** * Compiles an individual shader. * - * @param {import('./webgl-graphics-device.js').WebglGraphicsDevice} device - The graphics device. + * @param {WebglGraphicsDevice} device - The graphics device. * @param {string} src - The shader source code. * @param {boolean} isVertexShader - True if the shader is a vertex shader, false if it is a * fragment shader. @@ -245,8 +249,8 @@ class WebglShader { /** * Link the shader, and extract its attributes and uniform information. * - * @param {import('./webgl-graphics-device.js').WebglGraphicsDevice} device - The graphics device. - * @param {import('../shader.js').Shader} shader - The shader to query. + * @param {WebglGraphicsDevice} device - The graphics device. + * @param {Shader} shader - The shader to query. * @returns {boolean} True if the shader was successfully queried and false otherwise. */ finalize(device, shader) { @@ -362,8 +366,8 @@ class WebglShader { /** * Check the compilation status of a shader. * - * @param {import('./webgl-graphics-device.js').WebglGraphicsDevice} device - The graphics device. - * @param {import('../shader.js').Shader} shader - The shader to query. + * @param {WebglGraphicsDevice} device - The graphics device. + * @param {Shader} shader - The shader to query. * @param {WebGLShader} glShader - The WebGL shader. * @param {string} source - The shader source code. * @param {string} shaderType - The shader type. Can be 'vertex' or 'fragment'. @@ -391,7 +395,7 @@ class WebglShader { /** * Check the linking status of a shader. * - * @param {import('./webgl-graphics-device.js').WebglGraphicsDevice} device - The graphics device. + * @param {WebglGraphicsDevice} device - The graphics device. * @returns {boolean} True if the shader is already linked, false otherwise. Note that unless the * device supports the KHR_parallel_shader_compile extension, this will always return true. */ diff --git a/src/platform/graphics/webgl/webgl-texture.js b/src/platform/graphics/webgl/webgl-texture.js index e1f86fa5499..a3993183ee6 100644 --- a/src/platform/graphics/webgl/webgl-texture.js +++ b/src/platform/graphics/webgl/webgl-texture.js @@ -1,5 +1,4 @@ import { Debug } from '../../../core/debug.js'; - import { PIXELFORMAT_A8, PIXELFORMAT_L8, PIXELFORMAT_LA8, PIXELFORMAT_RGB565, PIXELFORMAT_RGBA5551, PIXELFORMAT_RGBA4, PIXELFORMAT_RGB8, PIXELFORMAT_RGBA8, PIXELFORMAT_DXT1, PIXELFORMAT_DXT3, PIXELFORMAT_DXT5, @@ -16,6 +15,11 @@ import { PIXELFORMAT_ETC2_SRGB, PIXELFORMAT_ETC2_SRGBA, PIXELFORMAT_ASTC_4x4_SRGB } from '../constants.js'; +/** + * @import { Texture } from '../texture.js' + * @import { WebglGraphicsDevice } from './webgl-graphics-device.js' + */ + /** * Checks that an image's width and height do not exceed the max texture size. If they do, it will * be scaled down to that maximum size and returned as a canvas element. @@ -67,7 +71,7 @@ class WebglTexture { dirtyParameterFlags = 0; constructor(texture) { - /** @type {import('../texture.js').Texture} */ + /** @type {Texture} */ this.texture = texture; } @@ -439,8 +443,8 @@ class WebglTexture { } /** - * @param {import('./webgl-graphics-device.js').WebglGraphicsDevice} device - The device. - * @param {import('../texture.js').Texture} texture - The texture to update. + * @param {WebglGraphicsDevice} device - The device. + * @param {Texture} texture - The texture to update. */ upload(device, texture) { @@ -795,7 +799,7 @@ class WebglTexture { const texture = this.texture; - /** @type {import('./webgl-graphics-device.js').WebglGraphicsDevice} */ + /** @type {WebglGraphicsDevice} */ const device = texture.device; return device.readTextureAsync(texture, x, y, width, height, options); } diff --git a/src/platform/graphics/webgpu/webgpu-bind-group-format.js b/src/platform/graphics/webgpu/webgpu-bind-group-format.js index e3a87e264ab..a9f65e18bac 100644 --- a/src/platform/graphics/webgpu/webgpu-bind-group-format.js +++ b/src/platform/graphics/webgpu/webgpu-bind-group-format.js @@ -1,10 +1,14 @@ import { Debug, DebugHelper } from '../../../core/debug.js'; import { StringIds } from '../../../core/string-ids.js'; import { SAMPLETYPE_FLOAT, SAMPLETYPE_UNFILTERABLE_FLOAT, SAMPLETYPE_DEPTH, SAMPLETYPE_INT, SAMPLETYPE_UINT } from '../constants.js'; - import { WebgpuUtils } from './webgpu-utils.js'; import { gpuTextureFormats } from './constants.js'; +/** + * @import { BindGroupFormat } from '../bind-group-format.js' + * @import { WebgpuGraphicsDevice } from './webgpu-graphics-device.js' + */ + const samplerTypes = []; samplerTypes[SAMPLETYPE_FLOAT] = 'filtering'; samplerTypes[SAMPLETYPE_UNFILTERABLE_FLOAT] = 'non-filtering'; @@ -31,11 +35,11 @@ const stringIds = new StringIds(); */ class WebgpuBindGroupFormat { /** - * @param {import('../bind-group-format.js').BindGroupFormat} bindGroupFormat - Bind group format. + * @param {BindGroupFormat} bindGroupFormat - Bind group format. */ constructor(bindGroupFormat) { - /** @type {import('./webgpu-graphics-device.js').WebgpuGraphicsDevice} */ + /** @type {WebgpuGraphicsDevice} */ const device = bindGroupFormat.device; const { key, descr } = this.createDescriptor(bindGroupFormat); diff --git a/src/platform/graphics/webgpu/webgpu-bind-group.js b/src/platform/graphics/webgpu/webgpu-bind-group.js index d9df72ef250..bf0a960b6b0 100644 --- a/src/platform/graphics/webgpu/webgpu-bind-group.js +++ b/src/platform/graphics/webgpu/webgpu-bind-group.js @@ -1,6 +1,12 @@ import { Debug, DebugHelper } from '../../../core/debug.js'; import { WebgpuDebug } from './webgpu-debug.js'; +/** + * @import { BindGroup } from '../bind-group.js' + * @import { WebgpuGraphicsDevice } from './webgpu-graphics-device.js' + * @import { WebgpuTexture } from './webgpu-texture.js' + */ + /** * A WebGPU implementation of the BindGroup, which is a wrapper over GPUBindGroup. */ @@ -38,8 +44,8 @@ class WebgpuBindGroup { /** * Creates a bind group descriptor in WebGPU format * - * @param {import('./webgpu-graphics-device.js').WebgpuGraphicsDevice} device - Graphics device. - * @param {import('../bind-group.js').BindGroup} bindGroup - Bind group to create the + * @param {WebgpuGraphicsDevice} device - Graphics device. + * @param {BindGroup} bindGroup - Bind group to create the * descriptor for. * @returns {object} - Returns the generated descriptor of type GPUBindGroupDescriptor, which * can be used to create a GPUBindGroup @@ -79,7 +85,7 @@ class WebgpuBindGroup { const textureFormats = bindGroup.format.textureFormats; bindGroup.textures.forEach((tex, textureIndex) => { - /** @type {import('./webgpu-texture.js').WebgpuTexture} */ + /** @type {WebgpuTexture} */ const wgpuTexture = tex.impl; const textureFormat = format.textureFormats[textureIndex]; const slot = textureFormats[textureIndex].slot; @@ -115,7 +121,7 @@ class WebgpuBindGroup { const storageTextureFormats = bindGroup.format.storageTextureFormats; bindGroup.storageTextures.forEach((tex, textureIndex) => { - /** @type {import('./webgpu-texture.js').WebgpuTexture} */ + /** @type {WebgpuTexture} */ const wgpuTexture = tex.impl; const slot = storageTextureFormats[textureIndex].slot; diff --git a/src/platform/graphics/webgpu/webgpu-buffer.js b/src/platform/graphics/webgpu/webgpu-buffer.js index c6e712badec..a0e9d693c78 100644 --- a/src/platform/graphics/webgpu/webgpu-buffer.js +++ b/src/platform/graphics/webgpu/webgpu-buffer.js @@ -1,6 +1,10 @@ import { TRACEID_RENDER_QUEUE } from '../../../core/constants.js'; import { Debug, DebugHelper } from '../../../core/debug.js'; +/** + * @import { WebgpuGraphicsDevice } from './webgpu-graphics-device.js' + */ + /** * A WebGPU implementation of the Buffer. */ @@ -40,7 +44,7 @@ class WebgpuBuffer { } /** - * @param {import('./webgpu-graphics-device.js').WebgpuGraphicsDevice} device - Graphics device. + * @param {WebgpuGraphicsDevice} device - Graphics device. * @param {*} storage - */ unlock(device, storage) { diff --git a/src/platform/graphics/webgpu/webgpu-compute-pipeline.js b/src/platform/graphics/webgpu/webgpu-compute-pipeline.js index 3ec2f5f37c7..a6d63f30ebb 100644 --- a/src/platform/graphics/webgpu/webgpu-compute-pipeline.js +++ b/src/platform/graphics/webgpu/webgpu-compute-pipeline.js @@ -3,6 +3,10 @@ import { TRACEID_COMPUTEPIPELINE_ALLOC } from "../../../core/constants.js"; import { WebgpuDebug } from "./webgpu-debug.js"; import { WebgpuPipeline } from "./webgpu-pipeline.js"; +/** + * @import { WebgpuShader } from './webgpu-shader.js' + */ + let _pipelineId = 0; class WebgpuComputePipeline extends WebgpuPipeline { @@ -21,7 +25,7 @@ class WebgpuComputePipeline extends WebgpuPipeline { const wgpu = this.device.wgpu; - /** @type {import('./webgpu-shader.js').WebgpuShader} */ + /** @type {WebgpuShader} */ const webgpuShader = shader.impl; /** @type {GPUComputePipelineDescriptor} */ diff --git a/src/platform/graphics/webgpu/webgpu-debug.js b/src/platform/graphics/webgpu/webgpu-debug.js index 047d1905999..f42fa51ff7c 100644 --- a/src/platform/graphics/webgpu/webgpu-debug.js +++ b/src/platform/graphics/webgpu/webgpu-debug.js @@ -1,6 +1,10 @@ import { Debug } from "../../../core/debug.js"; import { DebugGraphics } from "../debug-graphics.js"; +/** + * @import { WebgpuGraphicsDevice } from './webgpu-graphics-device.js' + */ + // Maximum number of times a duplicate error message is logged. const MAX_DUPLICATES = 5; @@ -19,8 +23,7 @@ class WebgpuDebug { /** * Start a validation error scope. * - * @param {import('./webgpu-graphics-device.js').WebgpuGraphicsDevice} device - The graphics - * device. + * @param {WebgpuGraphicsDevice} device - The graphics device. */ static validate(device) { device.wgpu.pushErrorScope('validation'); @@ -31,8 +34,7 @@ class WebgpuDebug { /** * Start an out-of-memory error scope. * - * @param {import('./webgpu-graphics-device.js').WebgpuGraphicsDevice} device - The graphics - * device. + * @param {WebgpuGraphicsDevice} device - The graphics device. */ static memory(device) { device.wgpu.pushErrorScope('out-of-memory'); @@ -43,8 +45,7 @@ class WebgpuDebug { /** * Start an internal error scope. * - * @param {import('./webgpu-graphics-device.js').WebgpuGraphicsDevice} device - The graphics - * device. + * @param {WebgpuGraphicsDevice} device - The graphics device. */ static internal(device) { device.wgpu.pushErrorScope('internal'); @@ -55,8 +56,7 @@ class WebgpuDebug { /** * End the previous error scope, and print errors if any. * - * @param {import('./webgpu-graphics-device.js').WebgpuGraphicsDevice} device - The graphics - * device. + * @param {WebgpuGraphicsDevice} device - The graphics device. * @param {...any} args - Additional parameters that form the error message. */ static end(device, ...args) { diff --git a/src/platform/graphics/webgpu/webgpu-graphics-device.js b/src/platform/graphics/webgpu/webgpu-graphics-device.js index 5c70b71c72c..5506b19209e 100644 --- a/src/platform/graphics/webgpu/webgpu-graphics-device.js +++ b/src/platform/graphics/webgpu/webgpu-graphics-device.js @@ -1,15 +1,15 @@ import { TRACEID_RENDER_QUEUE } from '../../../core/constants.js'; import { Debug, DebugHelper } from '../../../core/debug.js'; - import { PIXELFORMAT_RGBA8, PIXELFORMAT_BGRA8, DEVICETYPE_WEBGPU, BUFFERUSAGE_READ, BUFFERUSAGE_COPY_DST, semanticToLocation } from '../constants.js'; -import { GraphicsDevice } from '../graphics-device.js'; +import { BindGroupFormat } from '../bind-group-format.js'; +import { BindGroup } from '../bind-group.js'; import { DebugGraphics } from '../debug-graphics.js'; +import { GraphicsDevice } from '../graphics-device.js'; import { RenderTarget } from '../render-target.js'; import { StencilParameters } from '../stencil-parameters.js'; - import { WebgpuBindGroup } from './webgpu-bind-group.js'; import { WebgpuBindGroupFormat } from './webgpu-bind-group-format.js'; import { WebgpuIndexBuffer } from './webgpu-index-buffer.js'; @@ -28,8 +28,12 @@ import { WebgpuGpuProfiler } from './webgpu-gpu-profiler.js'; import { WebgpuResolver } from './webgpu-resolver.js'; import { WebgpuCompute } from './webgpu-compute.js'; import { WebgpuBuffer } from './webgpu-buffer.js'; -import { BindGroupFormat } from '../bind-group-format.js'; -import { BindGroup } from '../bind-group.js'; + +/** + * @import { BindGroup } from '../bind-group.js' + * @import { RenderPass } from '../render-pass.js' + * @import { WebgpuBuffer } from './webgpu-buffer.js' + */ const _uniqueLocations = new Map(); @@ -422,7 +426,7 @@ class WebgpuGraphicsDevice extends GraphicsDevice { /** * @param {number} index - Index of the bind group slot - * @param {import('../bind-group.js').BindGroup} bindGroup - Bind group to attach + * @param {BindGroup} bindGroup - Bind group to attach * @param {number[]} [offsets] - Byte offsets for all uniform buffers in the bind group. */ setBindGroup(index, bindGroup, offsets) { @@ -610,7 +614,7 @@ class WebgpuGraphicsDevice extends GraphicsDevice { /** * Start a render pass. * - * @param {import('../render-pass.js').RenderPass} renderPass - The render pass to start. + * @param {RenderPass} renderPass - The render pass to start. * @ignore */ startRenderPass(renderPass) { @@ -679,7 +683,7 @@ class WebgpuGraphicsDevice extends GraphicsDevice { /** * End a render pass. * - * @param {import('../render-pass.js').RenderPass} renderPass - The render pass to end. + * @param {RenderPass} renderPass - The render pass to end. * @ignore */ endRenderPass(renderPass) { @@ -858,7 +862,7 @@ class WebgpuGraphicsDevice extends GraphicsDevice { /** * Clear the content of a storage buffer to 0. * - * @param {import('./webgpu-buffer.js').WebgpuBuffer} storageBuffer - The storage buffer. + * @param {WebgpuBuffer} storageBuffer - The storage buffer. * @param {number} [offset] - The offset of data to clear. Defaults to 0. * @param {number} [size] - The size of data to clear. Defaults to the full size of the buffer. * @ignore @@ -882,7 +886,7 @@ class WebgpuGraphicsDevice extends GraphicsDevice { /** * Read a content of a storage buffer. * - * @param {import('./webgpu-buffer.js').WebgpuBuffer} storageBuffer - The storage buffer. + * @param {WebgpuBuffer} storageBuffer - The storage buffer. * @param {number} [offset] - The byte offset of data to read. Defaults to 0. * @param {number} [size] - The byte size of data to read. Defaults to the full size of the * buffer minus the offset. @@ -964,7 +968,7 @@ class WebgpuGraphicsDevice extends GraphicsDevice { /** * Issues a write operation of the provided data into a storage buffer. * - * @param {import('./webgpu-buffer.js').WebgpuBuffer} storageBuffer - The storage buffer. + * @param {WebgpuBuffer} storageBuffer - The storage buffer. * @param {number} bufferOffset - The offset in bytes to start writing to the storage buffer. * @param {ArrayBufferView} data - The data to write to the storage buffer. * @param {number} dataOffset - Offset in data to begin writing from. Given in elements if data diff --git a/src/platform/graphics/webgpu/webgpu-mipmap-renderer.js b/src/platform/graphics/webgpu/webgpu-mipmap-renderer.js index 10dbca5a671..6a747cba330 100644 --- a/src/platform/graphics/webgpu/webgpu-mipmap-renderer.js +++ b/src/platform/graphics/webgpu/webgpu-mipmap-renderer.js @@ -3,11 +3,17 @@ import { SHADERLANGUAGE_WGSL } from "../constants.js"; import { Debug, DebugHelper } from "../../../core/debug.js"; import { DebugGraphics } from "../debug-graphics.js"; +/** + * @import { WebgpuGraphicsDevice } from './webgpu-graphics-device.js' + * @import { WebgpuShader } from './webgpu-shader.js' + * @import { WebgpuTexture } from './webgpu-texture.js' + */ + /** * A WebGPU helper class implementing texture mipmap generation. */ class WebgpuMipmapRenderer { - /** @type {import('./webgpu-graphics-device.js').WebgpuGraphicsDevice} */ + /** @type {WebgpuGraphicsDevice} */ device; constructor(device) { @@ -62,7 +68,7 @@ class WebgpuMipmapRenderer { /** * Generates mipmaps for the specified WebGPU texture. * - * @param {import('./webgpu-texture.js').WebgpuTexture} webgpuTexture - The texture to generate mipmaps for. + * @param {WebgpuTexture} webgpuTexture - The texture to generate mipmaps for. */ generate(webgpuTexture) { @@ -81,7 +87,7 @@ class WebgpuMipmapRenderer { const device = this.device; const wgpu = device.wgpu; - /** @type {import('./webgpu-shader.js').WebgpuShader} */ + /** @type {WebgpuShader} */ const webgpuShader = this.shader.impl; const pipeline = wgpu.createRenderPipeline({ diff --git a/src/platform/graphics/webgpu/webgpu-pipeline.js b/src/platform/graphics/webgpu/webgpu-pipeline.js index a56ecf54cc7..264f7ec19f0 100644 --- a/src/platform/graphics/webgpu/webgpu-pipeline.js +++ b/src/platform/graphics/webgpu/webgpu-pipeline.js @@ -1,6 +1,11 @@ import { TRACEID_PIPELINELAYOUT_ALLOC } from '../../../core/constants.js'; import { Debug, DebugHelper } from '../../../core/debug.js'; +/** + * @import { BindGroupFormat } from '../bind-group-format.js' + * @import { WebgpuGraphicsDevice } from './webgpu-graphics-device.js' + */ + let _layoutId = 0; /** @@ -8,15 +13,14 @@ let _layoutId = 0; */ class WebgpuPipeline { constructor(device) { - /** @type {import('./webgpu-graphics-device.js').WebgpuGraphicsDevice} */ + /** @type {WebgpuGraphicsDevice} */ this.device = device; } // TODO: this could be cached using bindGroupKey /** - * @param {import('../bind-group-format.js').BindGroupFormat[]} bindGroupFormats - An array - * of bind group formats. + * @param {BindGroupFormat[]} bindGroupFormats - An array of bind group formats. * @returns {any} Returns the pipeline layout. */ getPipelineLayout(bindGroupFormats) { diff --git a/src/platform/graphics/webgpu/webgpu-render-pipeline.js b/src/platform/graphics/webgpu/webgpu-render-pipeline.js index 3c7c85ff2ee..fddceb9005a 100644 --- a/src/platform/graphics/webgpu/webgpu-render-pipeline.js +++ b/src/platform/graphics/webgpu/webgpu-render-pipeline.js @@ -2,13 +2,23 @@ import { Debug, DebugHelper } from "../../../core/debug.js"; import { hash32Fnv1a } from "../../../core/hash.js"; import { array } from "../../../core/array-utils.js"; import { TRACEID_RENDERPIPELINE_ALLOC } from "../../../core/constants.js"; - import { WebgpuVertexBufferLayout } from "./webgpu-vertex-buffer-layout.js"; import { WebgpuDebug } from "./webgpu-debug.js"; import { WebgpuPipeline } from "./webgpu-pipeline.js"; import { DebugGraphics } from "../debug-graphics.js"; import { bindGroupNames } from "../constants.js"; +/** + * @import { BindGroupFormat } from '../bind-group-format.js' + * @import { BlendState } from '../blend-state.js' + * @import { DepthState } from '../depth-state.js' + * @import { RenderTarget } from '../render-target.js' + * @import { Shader } from '../shader.js' + * @import { StencilParameters } from '../stencil-parameters.js' + * @import { VertexFormat } from '../vertex-format.js' + * @import { WebgpuShader } from './webgpu-shader.js' + */ + let _pipelineId = 0; const _primitiveTopology = [ @@ -113,20 +123,17 @@ class WebgpuRenderPipeline extends WebgpuPipeline { /** * @param {object} primitive - The primitive. - * @param {import('../vertex-format.js').VertexFormat} vertexFormat0 - The first vertex format. - * @param {import('../vertex-format.js').VertexFormat} vertexFormat1 - The second vertex format. - * @param {import('../shader.js').Shader} shader - The shader. - * @param {import('../render-target.js').RenderTarget} renderTarget - The render target. - * @param {import('../bind-group-format.js').BindGroupFormat[]} bindGroupFormats - An array of - * bind group formats. - * @param {import('../blend-state.js').BlendState} blendState - The blend state. - * @param {import('../depth-state.js').DepthState} depthState - The depth state. + * @param {VertexFormat} vertexFormat0 - The first vertex format. + * @param {VertexFormat} vertexFormat1 - The second vertex format. + * @param {Shader} shader - The shader. + * @param {RenderTarget} renderTarget - The render target. + * @param {BindGroupFormat[]} bindGroupFormats - An array of bind group formats. + * @param {BlendState} blendState - The blend state. + * @param {DepthState} depthState - The depth state. * @param {number} cullMode - The cull mode. * @param {boolean} stencilEnabled - Whether stencil is enabled. - * @param {import('../stencil-parameters.js').StencilParameters} stencilFront - The stencil - * state for front faces. - * @param {import('../stencil-parameters.js').StencilParameters} stencilBack - The stencil - * state for back faces. + * @param {StencilParameters} stencilFront - The stencil state for front faces. + * @param {StencilParameters} stencilBack - The stencil state for back faces. * @returns {GPURenderPipeline} Returns the render pipeline. * @private */ @@ -230,13 +237,11 @@ class WebgpuRenderPipeline extends WebgpuPipeline { } /** - * @param {import('../depth-state.js').DepthState} depthState - The depth state. - * @param {import('../render-target.js').RenderTarget} renderTarget - The render target. + * @param {DepthState} depthState - The depth state. + * @param {RenderTarget} renderTarget - The render target. * @param {boolean} stencilEnabled - Whether stencil is enabled. - * @param {import('../stencil-parameters.js').StencilParameters} stencilFront - The stencil - * state for front faces. - * @param {import('../stencil-parameters.js').StencilParameters} stencilBack - The stencil - * state for back faces. + * @param {StencilParameters} stencilFront - The stencil state for front faces. + * @param {StencilParameters} stencilBack - The stencil state for back faces. * @returns {object} Returns the depth stencil state. * @private */ @@ -295,7 +300,7 @@ class WebgpuRenderPipeline extends WebgpuPipeline { const wgpu = this.device.wgpu; - /** @type {import('./webgpu-shader.js').WebgpuShader} */ + /** @type {WebgpuShader} */ const webgpuShader = shader.impl; /** @type {GPURenderPipelineDescriptor} */ diff --git a/src/platform/graphics/webgpu/webgpu-render-target.js b/src/platform/graphics/webgpu/webgpu-render-target.js index 061d86553b3..5e95c30250d 100644 --- a/src/platform/graphics/webgpu/webgpu-render-target.js +++ b/src/platform/graphics/webgpu/webgpu-render-target.js @@ -2,6 +2,12 @@ import { Debug, DebugHelper } from '../../../core/debug.js'; import { StringIds } from '../../../core/string-ids.js'; import { WebgpuDebug } from './webgpu-debug.js'; +/** + * @import { RenderPass } from '../render-pass.js' + * @import { RenderTarget } from '../render-target.js' + * @import { WebgpuGraphicsDevice } from '../webgpu/webgpu-graphics-device.js' + */ + const stringIds = new StringIds(); /** @@ -83,8 +89,7 @@ class WebgpuRenderTarget { renderPassDescriptor = {}; /** - * @param {import('../render-target.js').RenderTarget} renderTarget - The render target owning - * this implementation. + * @param {RenderTarget} renderTarget - The render target owning this implementation. */ constructor(renderTarget) { this.renderTarget = renderTarget; @@ -103,8 +108,7 @@ class WebgpuRenderTarget { * Release associated resources. Note that this needs to leave this instance in a state where * it can be re-initialized again, which is used by render target resizing. * - * @param {import('../webgpu/webgpu-graphics-device.js').WebgpuGraphicsDevice} device - The - * graphics device. + * @param {WebgpuGraphicsDevice} device - The graphics device. */ destroy(device) { this.initialized = false; @@ -186,9 +190,8 @@ class WebgpuRenderTarget { /** * Initialize render target for rendering one time. * - * @param {import('../webgpu/webgpu-graphics-device.js').WebgpuGraphicsDevice} device - The - * graphics device. - * @param {import('../render-target.js').RenderTarget} renderTarget - The render target. + * @param {WebgpuGraphicsDevice} device - The graphics device. + * @param {RenderTarget} renderTarget - The render target. */ init(device, renderTarget) { @@ -278,7 +281,7 @@ class WebgpuRenderTarget { /** * @param {GPUDevice} wgpu - The WebGPU device. - * @param {import('../render-target.js').RenderTarget} renderTarget - The render target. + * @param {RenderTarget} renderTarget - The render target. * @param {number} index - The color buffer index. * @returns {GPURenderPassColorAttachment} The color attachment. * @private @@ -349,7 +352,7 @@ class WebgpuRenderTarget { /** * Update WebGPU render pass descriptor by RenderPass settings. * - * @param {import('../render-pass.js').RenderPass} renderPass - The render pass to start. + * @param {RenderPass} renderPass - The render pass to start. */ setupForRenderPass(renderPass) { diff --git a/src/platform/graphics/webgpu/webgpu-resolver.js b/src/platform/graphics/webgpu/webgpu-resolver.js index 6ac43360404..daa74aabc97 100644 --- a/src/platform/graphics/webgpu/webgpu-resolver.js +++ b/src/platform/graphics/webgpu/webgpu-resolver.js @@ -3,11 +3,16 @@ import { SHADERLANGUAGE_WGSL } from "../constants.js"; import { Debug, DebugHelper } from "../../../core/debug.js"; import { DebugGraphics } from "../debug-graphics.js"; +/** + * @import { WebgpuGraphicsDevice } from './webgpu-graphics-device.js' + * @import { WebgpuShader } from './webgpu-shader.js' + */ + /** * A WebGPU helper class implementing custom resolve of multi-sampled textures. */ class WebgpuResolver { - /** @type {import('./webgpu-graphics-device.js').WebgpuGraphicsDevice} */ + /** @type {WebgpuGraphicsDevice} */ device; /** @@ -85,7 +90,7 @@ class WebgpuResolver { */ createPipeline(format) { - /** @type {import('./webgpu-shader.js').WebgpuShader} */ + /** @type {WebgpuShader} */ const webgpuShader = this.shader.impl; const pipeline = this.device.wgpu.createRenderPipeline({ diff --git a/src/platform/graphics/webgpu/webgpu-shader.js b/src/platform/graphics/webgpu/webgpu-shader.js index 65870b985c3..772cb87257a 100644 --- a/src/platform/graphics/webgpu/webgpu-shader.js +++ b/src/platform/graphics/webgpu/webgpu-shader.js @@ -1,10 +1,14 @@ import { Debug, DebugHelper } from '../../../core/debug.js'; import { SHADERLANGUAGE_WGSL } from '../constants.js'; import { DebugGraphics } from '../debug-graphics.js'; - import { ShaderProcessor } from '../shader-processor.js'; import { WebgpuDebug } from './webgpu-debug.js'; +/** + * @import { GraphicsDevice } from '../graphics-device.js' + * @import { Shader } from '../shader.js' + */ + /** * A WebGPU implementation of the Shader. */ @@ -46,10 +50,10 @@ class WebgpuShader { computeEntryPoint = 'main'; /** - * @param {import('../shader.js').Shader} shader - The shader. + * @param {Shader} shader - The shader. */ constructor(shader) { - /** @type {import('../shader.js').Shader} */ + /** @type {Shader} */ this.shader = shader; const definition = shader.definition; @@ -82,7 +86,7 @@ class WebgpuShader { /** * Free the WebGPU resources associated with a shader. * - * @param {import('../shader.js').Shader} shader - The shader to free. + * @param {Shader} shader - The shader to free. */ destroy(shader) { this._vertexCode = null; @@ -180,8 +184,8 @@ class WebgpuShader { /** * Restore shader after the context has been obtained. * - * @param {import('../graphics-device.js').GraphicsDevice} device - The graphics device. - * @param {import('../shader.js').Shader} shader - The shader to restore. + * @param {GraphicsDevice} device - The graphics device. + * @param {Shader} shader - The shader to restore. */ restoreContext(device, shader) { } diff --git a/src/platform/graphics/webgpu/webgpu-texture.js b/src/platform/graphics/webgpu/webgpu-texture.js index 417654c75df..65cabc4504d 100644 --- a/src/platform/graphics/webgpu/webgpu-texture.js +++ b/src/platform/graphics/webgpu/webgpu-texture.js @@ -1,7 +1,6 @@ import { TRACEID_RENDER_QUEUE } from '../../../core/constants.js'; import { Debug, DebugHelper } from '../../../core/debug.js'; import { math } from '../../../core/math/math.js'; - import { pixelFormatInfo, isCompressedPixelFormat, ADDRESS_REPEAT, ADDRESS_CLAMP_TO_EDGE, ADDRESS_MIRRORED_REPEAT, @@ -16,6 +15,11 @@ import { TextureUtils } from '../texture-utils.js'; import { WebgpuDebug } from './webgpu-debug.js'; import { gpuTextureFormats } from './constants.js'; +/** + * @import { Texture } from '../texture.js' + * @import { WebgpuGraphicsDevice } from './webgpu-graphics-device.js' + */ + // map of ADDRESS_*** to GPUAddressMode const gpuAddressModes = []; gpuAddressModes[ADDRESS_REPEAT] = 'repeat'; @@ -75,7 +79,7 @@ class WebgpuTexture { format; constructor(texture) { - /** @type {import('../texture.js').Texture} */ + /** @type {Texture} */ this.texture = texture; this.format = gpuTextureFormats[texture.format]; @@ -271,9 +275,8 @@ class WebgpuTexture { } /** - * @param {import('./webgpu-graphics-device.js').WebgpuGraphicsDevice} device - The graphics - * device. - * @param {import('../texture.js').Texture} texture - The texture. + * @param {WebgpuGraphicsDevice} device - The graphics device. + * @param {Texture} texture - The texture. */ uploadImmediate(device, texture) { @@ -286,7 +289,7 @@ class WebgpuTexture { } /** - * @param {import('./webgpu-graphics-device.js').WebgpuGraphicsDevice} device - The graphics + * @param {WebgpuGraphicsDevice} device - The graphics * device. */ uploadData(device) { @@ -518,7 +521,7 @@ class WebgpuTexture { const size = paddedBytesPerRow * height; // create a temporary staging buffer - /** @type {import('./webgpu-graphics-device.js').WebgpuGraphicsDevice} */ + /** @type {WebgpuGraphicsDevice} */ const device = texture.device; const stagingBuffer = device.createBufferImpl(BUFFERUSAGE_READ | BUFFERUSAGE_COPY_DST); stagingBuffer.allocate(device, size); diff --git a/src/platform/graphics/webgpu/webgpu-vertex-buffer-layout.js b/src/platform/graphics/webgpu/webgpu-vertex-buffer-layout.js index fcd0090cc7d..7a26850d93f 100644 --- a/src/platform/graphics/webgpu/webgpu-vertex-buffer-layout.js +++ b/src/platform/graphics/webgpu/webgpu-vertex-buffer-layout.js @@ -3,6 +3,10 @@ import { TYPE_INT8, TYPE_UINT8, TYPE_INT16, TYPE_UINT16, TYPE_INT32, TYPE_UINT32, TYPE_FLOAT32, TYPE_FLOAT16 } from '../constants.js'; +/** + * @import { VertexFormat } from '../vertex-format.js' + */ + // map of TYPE_*** to GPUVertexFormat const gpuVertexFormats = []; gpuVertexFormats[TYPE_INT8] = 'sint8'; @@ -34,8 +38,8 @@ class WebgpuVertexBufferLayout { /** * Obtain a vertex layout of one or two vertex formats. * - * @param {import('../vertex-format.js').VertexFormat} vertexFormat0 - The first vertex format. - * @param {import('../vertex-format.js').VertexFormat} [vertexFormat1] - The second vertex format. + * @param {VertexFormat} vertexFormat0 - The first vertex format. + * @param {VertexFormat} [vertexFormat1] - The second vertex format. * @returns {any[]} - The vertex layout. */ get(vertexFormat0, vertexFormat1 = null) { @@ -54,8 +58,8 @@ class WebgpuVertexBufferLayout { } /** - * @param {import('../vertex-format.js').VertexFormat} vertexFormat0 - The first vertex format. - * @param {import('../vertex-format.js').VertexFormat} vertexFormat1 - The second vertex format. + * @param {VertexFormat} vertexFormat0 - The first vertex format. + * @param {VertexFormat} vertexFormat1 - The second vertex format. * @returns {any[]} - The vertex buffer layout. */ create(vertexFormat0, vertexFormat1) { diff --git a/src/platform/input/controller.js b/src/platform/input/controller.js index 7b62cc2f9ae..af0ed29cdb0 100644 --- a/src/platform/input/controller.js +++ b/src/platform/input/controller.js @@ -1,5 +1,4 @@ import { type } from '../../core/core.js'; - import { ACTION_GAMEPAD, ACTION_KEYBOARD, ACTION_MOUSE, EVENT_MOUSEMOVE, @@ -9,6 +8,10 @@ import { import { Keyboard } from './keyboard.js'; import { Mouse } from './mouse.js'; +/** + * @import { GamePads } from './game-pads.js' + */ + /** * A general input handler which handles both mouse and keyboard input assigned to named actions. * This allows you to define input handlers separately to defining keyboard/mouse configurations. @@ -29,7 +32,7 @@ class Controller { _mouse; /** - * @type {import('./game-pads.js').GamePads|null} + * @type {GamePads|null} * @private */ _gamepads; @@ -56,7 +59,7 @@ class Controller { * @param {object} [options] - Optional arguments. * @param {Keyboard} [options.keyboard] - A Keyboard object to use. * @param {Mouse} [options.mouse] - A Mouse object to use. - * @param {import('./game-pads.js').GamePads} [options.gamepads] - A Gamepads object to use. + * @param {GamePads} [options.gamepads] - A Gamepads object to use. * @example * const c = new pc.Controller(document); * diff --git a/src/platform/input/keyboard-event.js b/src/platform/input/keyboard-event.js index 2c605befc65..cbe59e43fb0 100644 --- a/src/platform/input/keyboard-event.js +++ b/src/platform/input/keyboard-event.js @@ -1,3 +1,7 @@ +/** + * @import { Keyboard } from './keyboard.js' + */ + /** * The KeyboardEvent is passed into all event callbacks from the {@link Keyboard}. It corresponds * to a key press or release. @@ -29,8 +33,7 @@ class KeyboardEvent { /** * Create a new KeyboardEvent. * - * @param {import('./keyboard.js').Keyboard} keyboard - The keyboard object which is firing the - * event. + * @param {Keyboard} keyboard - The keyboard object which is firing the event. * @param {globalThis.KeyboardEvent} event - The original browser event that was fired. * @example * const onKeyDown = function (e) { diff --git a/src/platform/input/mouse-event.js b/src/platform/input/mouse-event.js index 83e211202c6..2699b2f6e91 100644 --- a/src/platform/input/mouse-event.js +++ b/src/platform/input/mouse-event.js @@ -1,5 +1,9 @@ import { MOUSEBUTTON_NONE } from './constants.js'; +/** + * @import { Mouse } from './mouse.js' + */ + /** * Returns true if pointer lock is currently enabled. * @@ -107,7 +111,7 @@ class MouseEvent { /** * Create a new MouseEvent instance. * - * @param {import('./mouse.js').Mouse} mouse - The Mouse device that is firing this event. + * @param {Mouse} mouse - The Mouse device that is firing this event. * @param {globalThis.MouseEvent|globalThis.WheelEvent} event - The original browser event that fired. */ constructor(mouse, event) { diff --git a/src/platform/input/touch-event.js b/src/platform/input/touch-event.js index 92d22c924bd..ec95c8b9baa 100644 --- a/src/platform/input/touch-event.js +++ b/src/platform/input/touch-event.js @@ -1,3 +1,7 @@ +/** + * @import { TouchDevice } from './touch-device.js' + */ + /** * This function takes a browser Touch object and returns the coordinates of the touch relative to * the target DOM element. @@ -123,8 +127,7 @@ class TouchEvent { /** * Create a new TouchEvent instance. It is created from an existing browser event. * - * @param {import('./touch-device.js').TouchDevice} device - The source device of the touch - * events. + * @param {TouchDevice} device - The source device of the touch events. * @param {globalThis.TouchEvent} event - The original browser TouchEvent. */ constructor(device, event) { diff --git a/src/platform/sound/instance.js b/src/platform/sound/instance.js index 3048a02b861..43ad513dff1 100644 --- a/src/platform/sound/instance.js +++ b/src/platform/sound/instance.js @@ -1,9 +1,12 @@ import { EventHandler } from '../../core/event-handler.js'; - import { math } from '../../core/math/math.js'; - import { hasAudioContext } from '../audio/capabilities.js'; +/** + * @import { SoundManager } from './manager.js' + * @import { Sound } from './sound.js' + */ + const STATE_PLAYING = 0; const STATE_PAUSED = 1; const STATE_STOPPED = 2; @@ -92,8 +95,8 @@ class SoundInstance extends EventHandler { /** * Create a new SoundInstance instance. * - * @param {import('./manager.js').SoundManager} manager - The sound manager. - * @param {import('./sound.js').Sound} sound - The sound to play. + * @param {SoundManager} manager - The sound manager. + * @param {Sound} sound - The sound to play. * @param {object} options - Options for the instance. * @param {number} [options.volume] - The playback volume, between 0 and 1. Defaults to 1. * @param {number} [options.pitch] - The relative pitch. Defaults to 1 (plays at normal pitch). @@ -113,7 +116,7 @@ class SoundInstance extends EventHandler { super(); /** - * @type {import('./manager.js').SoundManager} + * @type {SoundManager} * @private */ this._manager = manager; @@ -137,7 +140,7 @@ class SoundInstance extends EventHandler { this._loop = !!(options.loop !== undefined ? options.loop : false); /** - * @type {import('./sound.js').Sound} + * @type {Sound} * @private */ this._sound = sound; @@ -472,7 +475,7 @@ class SoundInstance extends EventHandler { /** * Sets the sound resource that the instance will play. * - * @type {import('./sound.js').Sound} + * @type {Sound} */ set sound(value) { this._sound = value; @@ -487,7 +490,7 @@ class SoundInstance extends EventHandler { /** * Gets the sound resource that the instance will play. * - * @type {import('./sound.js').Sound} + * @type {Sound} */ get sound() { return this._sound; diff --git a/src/platform/sound/instance3d.js b/src/platform/sound/instance3d.js index a3d8d8d41e2..c5b51b30bdb 100644 --- a/src/platform/sound/instance3d.js +++ b/src/platform/sound/instance3d.js @@ -1,12 +1,15 @@ import { Debug } from '../../core/debug.js'; import { math } from '../../core/math/math.js'; import { Vec3 } from '../../core/math/vec3.js'; - import { DISTANCE_EXPONENTIAL, DISTANCE_INVERSE, DISTANCE_LINEAR } from '../audio/constants.js'; import { hasAudioContext } from '../audio/capabilities.js'; - import { SoundInstance } from './instance.js'; +/** + * @import { SoundManager } from './manager.js' + * @import { Sound } from './sound.js' + */ + // default maxDistance, same as Web Audio API const MAX_DISTANCE = 10000; @@ -31,8 +34,8 @@ class SoundInstance3d extends SoundInstance { /** * Create a new SoundInstance3d instance. * - * @param {import('./manager.js').SoundManager} manager - The sound manager. - * @param {import('./sound.js').Sound} sound - The sound to play. + * @param {SoundManager} manager - The sound manager. + * @param {Sound} sound - The sound to play. * @param {object} options - Options for the instance. * @param {number} [options.volume] - The playback volume, between 0 and 1. Defaults to 1. * @param {number} [options.pitch] - The relative pitch. Defaults to 1 (plays at normal pitch). diff --git a/src/platform/sound/listener.js b/src/platform/sound/listener.js index 1a164c8fa41..2bd455ce5b9 100644 --- a/src/platform/sound/listener.js +++ b/src/platform/sound/listener.js @@ -1,13 +1,16 @@ -import { Debug } from '../../core/debug.js'; import { Mat4 } from '../../core/math/mat4.js'; import { Vec3 } from '../../core/math/vec3.js'; +/** + * @import { SoundManager } from './manager.js' + */ + /** * Represents an audio listener - used internally. */ class Listener { /** - * @type {import('./manager.js').SoundManager} + * @type {SoundManager} * @private */ _manager; @@ -18,12 +21,6 @@ class Listener { */ position = new Vec3(); - /** - * @type {Vec3} - * @private - */ - velocity = new Vec3(); - /** * @type {Mat4} * @private @@ -33,7 +30,7 @@ class Listener { /** * Create a new listener instance. * - * @param {import('./manager.js').SoundManager} manager - The sound manager. + * @param {SoundManager} manager - The sound manager. */ constructor(manager) { this._manager = manager; @@ -67,27 +64,6 @@ class Listener { } } - /** - * Get the velocity of the listener. - * - * @returns {Vec3} The velocity of the listener. - * @deprecated - */ - getVelocity() { - Debug.warn('Listener#getVelocity is not implemented.'); - return this.velocity; - } - - /** - * Set the velocity of the listener. - * - * @param {Vec3} velocity - The new velocity of the listener. - * @deprecated - */ - setVelocity(velocity) { - Debug.warn('Listener#setVelocity is not implemented.'); - } - /** * Set the orientation matrix of the listener. * diff --git a/src/platform/sound/manager.js b/src/platform/sound/manager.js index 556ea331ee5..ffea521e2e6 100644 --- a/src/platform/sound/manager.js +++ b/src/platform/sound/manager.js @@ -1,14 +1,15 @@ import { Debug } from '../../core/debug.js'; - import { EventHandler } from '../../core/event-handler.js'; - import { math } from '../../core/math/math.js'; - import { Channel } from '../audio/channel.js'; import { Channel3d } from '../audio/channel3d.js'; - import { Listener } from './listener.js'; +/** + * @import { Sound } from './sound.js' + * @import { Vec3 } from '../../core/math/vec3.js' + */ + const CONTEXT_STATE_RUNNING = 'running'; /** @@ -131,7 +132,7 @@ class SoundManager extends EventHandler { /** * Create a new {@link Channel} and begin playback of the sound. * - * @param {import('./sound.js').Sound} sound - The Sound object to play. + * @param {Sound} sound - The Sound object to play. * @param {object} [options] - Optional options object. * @param {number} [options.volume] - The volume to playback at, between 0 and 1. * @param {boolean} [options.loop] - Whether to loop the sound when it reaches the end. @@ -150,8 +151,8 @@ class SoundManager extends EventHandler { /** * Create a new {@link Channel3d} and begin playback of the sound at the position specified. * - * @param {import('./sound.js').Sound} sound - The Sound object to play. - * @param {import('../../core/math/vec3.js').Vec3} position - The position of the sound in 3D space. + * @param {Sound} sound - The Sound object to play. + * @param {Vec3} position - The position of the sound in 3D space. * @param {object} options - Optional options object. * @param {number} [options.volume] - The volume to playback at, between 0 and 1. * @param {boolean} [options.loop] - Whether to loop the sound when it reaches the end. diff --git a/src/scene/animation/skeleton.js b/src/scene/animation/skeleton.js index e2f7df06a1b..5792293e0f1 100644 --- a/src/scene/animation/skeleton.js +++ b/src/scene/animation/skeleton.js @@ -2,6 +2,11 @@ import { Debug } from '../../core/debug.js'; import { Quat } from '../../core/math/quat.js'; import { Vec3 } from '../../core/math/vec3.js'; +/** + * @import { Animation } from './animation.js' + * @import { GraphNode } from '../graph-node.js' + */ + class InterpolatedKey { constructor() { this._written = false; @@ -42,12 +47,11 @@ class Skeleton { /** * Create a new Skeleton instance. * - * @param {import('../graph-node.js').GraphNode} graph - The root {@link GraphNode} of the - * skeleton. + * @param {GraphNode} graph - The root {@link GraphNode} of the skeleton. */ constructor(graph) { /** - * @type {import('./animation.js').Animation} + * @type {Animation} * @private */ this._animation = null; @@ -76,7 +80,7 @@ class Skeleton { /** * Sets the animation on the skeleton. * - * @type {import('./animation.js').Animation} + * @type {Animation} */ set animation(value) { this._animation = value; @@ -86,7 +90,7 @@ class Skeleton { /** * Gets the animation on the skeleton. * - * @type {import('./animation.js').Animation} + * @type {Animation} */ get animation() { return this._animation; @@ -254,8 +258,7 @@ class Skeleton { * Links a skeleton to a node hierarchy. The nodes animated skeleton are then subsequently used * to drive the local transformation matrices of the node hierarchy. * - * @param {import('../graph-node.js').GraphNode} graph - The root node of the graph that the - * skeleton is to drive. + * @param {GraphNode} graph - The root node of the graph that the skeleton is to drive. */ setGraph(graph) { this.graph = graph; diff --git a/src/scene/batching/batch-manager.js b/src/scene/batching/batch-manager.js index afbd8fc15b5..bd4916f853b 100644 --- a/src/scene/batching/batch-manager.js +++ b/src/scene/batching/batch-manager.js @@ -3,14 +3,12 @@ import { now } from '../../core/time.js'; import { Mat3 } from '../../core/math/mat3.js'; import { Vec3 } from '../../core/math/vec3.js'; import { BoundingBox } from '../../core/shape/bounding-box.js'; - import { PRIMITIVE_TRIANGLES, PRIMITIVE_TRIFAN, PRIMITIVE_TRISTRIP, SEMANTIC_POSITION, SEMANTIC_NORMAL, SEMANTIC_TANGENT, SEMANTIC_BLENDINDICES, TYPE_FLOAT32, typedArrayIndexFormats, typedArrayTypes, typedArrayTypesByteSize } from '../../platform/graphics/constants.js'; - import { SPRITE_RENDERMODE_SIMPLE } from '../constants.js'; import { Mesh } from '../mesh.js'; import { MeshInstance } from '../mesh-instance.js'; @@ -19,6 +17,17 @@ import { Batch } from './batch.js'; import { BatchGroup } from './batch-group.js'; import { SkinBatchInstance } from './skin-batch-instance.js'; +/** + * @import { Entity } from '../../framework/entity.js' + * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js' + * @import { Scene } from '../scene.js' + */ + +const _triFanIndices = [0, 1, 3, 2, 3, 1]; +const _triStripIndices = [0, 1, 3, 0, 3, 2]; + +const mat3 = new Mat3(); + function paramsIdentical(a, b) { if (a && !b) return false; if (!a && b) return false; @@ -47,11 +56,6 @@ function equalParamSets(params1, params2) { return true; } -const _triFanIndices = [0, 1, 3, 2, 3, 1]; -const _triStripIndices = [0, 1, 3, 0, 3, 2]; - -const mat3 = new Mat3(); - function getScaleSign(mi) { return mi.node.worldTransform.scaleSign; } @@ -65,11 +69,9 @@ class BatchManager { /** * Create a new BatchManager instance. * - * @param {import('../../platform/graphics/graphics-device.js').GraphicsDevice} device - The - * graphics device used by the batch manager. - * @param {import('../../framework/entity.js').Entity} root - The entity under which batched - * models are added. - * @param {import('../scene.js').Scene} scene - The scene that the batch manager affects. + * @param {GraphicsDevice} device - The graphics device used by the batch manager. + * @param {Entity} root - The entity under which batched models are added. + * @param {Scene} scene - The scene that the batch manager affects. */ constructor(device, root, scene) { this.device = device; diff --git a/src/scene/batching/batch.js b/src/scene/batching/batch.js index d54d27fc9fa..fd3cf0b4dc4 100644 --- a/src/scene/batching/batch.js +++ b/src/scene/batching/batch.js @@ -1,5 +1,9 @@ import { BoundingBox } from '../../core/shape/bounding-box.js'; +/** + * @import { MeshInstance } from '../mesh-instance.js' + */ + /** * Holds information about batched mesh instances. Created in {@link BatchManager#create}. * @@ -12,14 +16,14 @@ class Batch { /** * An array of original mesh instances, from which this batch was generated. * - * @type {import('../mesh-instance.js').MeshInstance[]} + * @type {MeshInstance[]} */ origMeshInstances; /** * A single combined mesh instance, the result of batching. * - * @type {import('../mesh-instance.js').MeshInstance} + * @type {MeshInstance} */ meshInstance = null; @@ -40,8 +44,7 @@ class Batch { /** * Create a new Batch instance. * - * @param {import('../mesh-instance.js').MeshInstance[]} meshInstances - The mesh instances to - * be batched. + * @param {MeshInstance[]} meshInstances - The mesh instances to be batched. * @param {boolean} dynamic - Whether this batch is dynamic (supports transforming mesh * instances at runtime). * @param {number} batchGroupId - Link this batch to a specific batch group. This is done diff --git a/src/scene/camera.js b/src/scene/camera.js index d5100f3b9fe..b36e865958c 100644 --- a/src/scene/camera.js +++ b/src/scene/camera.js @@ -3,9 +3,7 @@ import { Mat4 } from '../core/math/mat4.js'; import { Vec3 } from '../core/math/vec3.js'; import { Vec4 } from '../core/math/vec4.js'; import { math } from '../core/math/math.js'; - import { Frustum } from '../core/shape/frustum.js'; - import { ASPECT_AUTO, PROJECTION_PERSPECTIVE, LAYERID_WORLD, LAYERID_DEPTH, LAYERID_SKYBOX, LAYERID_UI, LAYERID_IMMEDIATE @@ -13,6 +11,12 @@ import { import { RenderPassColorGrab } from './graphics/render-pass-color-grab.js'; import { RenderPassDepthGrab } from './graphics/render-pass-depth-grab.js'; +/** + * @import { RenderPass } from '../platform/graphics/render-pass.js' + * @import { RenderingParams } from './renderer/rendering-params.js' + * @import { ShaderPassInfo } from './shader-pass.js' + */ + // pre-allocated temp variables const _deviceCoord = new Vec3(); const _halfSize = new Vec3(); @@ -27,7 +31,7 @@ const _frustumPoints = [new Vec3(), new Vec3(), new Vec3(), new Vec3(), new Vec3 */ class Camera { /** - * @type {import('./shader-pass.js').ShaderPassInfo|null} + * @type {ShaderPassInfo|null} */ shaderPassInfo = null; @@ -37,14 +41,14 @@ class Camera { renderPassColorGrab = null; /** - * @type {import('../platform/graphics/render-pass.js').RenderPass|null} + * @type {RenderPass|null} */ renderPassDepthGrab = null; /** * The rendering parameters. * - * @type {import('./renderer/rendering-params.js').RenderingParams|null} + * @type {RenderingParams|null} */ renderingParams = null; @@ -52,7 +56,7 @@ class Camera { * Render passes used to render this camera. If empty, the camera will render using the default * render passes. * - * @type {import('../platform/graphics/render-pass.js').RenderPass[]} + * @type {RenderPass[]} */ renderPasses = []; diff --git a/src/scene/composition/layer-composition.js b/src/scene/composition/layer-composition.js index 83434d4bf4c..97d71bd79c5 100644 --- a/src/scene/composition/layer-composition.js +++ b/src/scene/composition/layer-composition.js @@ -6,6 +6,11 @@ import { sortPriority } from '../../core/sort.js'; import { LAYERID_DEPTH } from '../constants.js'; import { RenderAction } from './render-action.js'; +/** + * @import { CameraComponent } from '../../framework/components/camera/component.js' + * @import { Layer } from '../layer.js' + */ + /** * Layer Composition is a collection of {@link Layer} that is fed to {@link Scene#layers} to define * rendering order. @@ -18,14 +23,14 @@ class LayerComposition extends EventHandler { /** * A read-only array of {@link Layer} sorted in the order they will be rendered. * - * @type {import('../layer.js').Layer[]} + * @type {Layer[]} */ layerList = []; /** * A mapping of {@link Layer#id} to {@link Layer}. * - * @type {Map} + * @type {Map} * @ignore */ layerIdMap = new Map(); @@ -33,7 +38,7 @@ class LayerComposition extends EventHandler { /** * A mapping of {@link Layer#name} to {@link Layer}. * - * @type {Map} + * @type {Map} * @ignore */ layerNameMap = new Map(); @@ -41,7 +46,7 @@ class LayerComposition extends EventHandler { /** * A mapping of {@link Layer} to its opaque index in {@link LayerComposition#layerList}. * - * @type {Map} + * @type {Map} * @ignore */ layerOpaqueIndexMap = new Map(); @@ -49,7 +54,7 @@ class LayerComposition extends EventHandler { /** * A mapping of {@link Layer} to its transparent index in {@link LayerComposition#layerList}. * - * @type {Map} + * @type {Map} * @ignore */ layerTransparentIndexMap = new Map(); @@ -76,14 +81,14 @@ class LayerComposition extends EventHandler { * Inside {@link Layer#onPreCull}, {@link Layer#onPostCull}, {@link Layer#onPreRender}, * {@link Layer#onPostRender}. * - * @type {import('../../framework/components/camera/component.js').CameraComponent[]} + * @type {CameraComponent[]} */ cameras = []; /** * A mapping of {@link CameraComponent} to its index in {@link LayerComposition#cameras}. * - * @type {Map} + * @type {Map} * @ignore */ camerasMap = new Map(); @@ -415,7 +420,7 @@ class LayerComposition extends EventHandler { /** * Adds a layer (both opaque and semi-transparent parts) to the end of the {@link LayerComposition#layerList}. * - * @param {import('../layer.js').Layer} layer - A {@link Layer} to add. + * @param {Layer} layer - A {@link Layer} to add. */ push(layer) { // add both opaque and transparent to the end of the array @@ -436,7 +441,7 @@ class LayerComposition extends EventHandler { * Inserts a layer (both opaque and semi-transparent parts) at the chosen index in the * {@link LayerComposition#layerList}. * - * @param {import('../layer.js').Layer} layer - A {@link Layer} to add. + * @param {Layer} layer - A {@link Layer} to add. * @param {number} index - Insertion position. */ insert(layer, index) { @@ -458,7 +463,7 @@ class LayerComposition extends EventHandler { /** * Removes a layer (both opaque and semi-transparent parts) from {@link LayerComposition#layerList}. * - * @param {import('../layer.js').Layer} layer - A {@link Layer} to remove. + * @param {Layer} layer - A {@link Layer} to remove. */ remove(layer) { // remove all occurrences of a layer @@ -489,7 +494,7 @@ class LayerComposition extends EventHandler { * Adds part of the layer with opaque (non semi-transparent) objects to the end of the * {@link LayerComposition#layerList}. * - * @param {import('../layer.js').Layer} layer - A {@link Layer} to add. + * @param {Layer} layer - A {@link Layer} to add. */ pushOpaque(layer) { // add opaque to the end of the array @@ -507,7 +512,7 @@ class LayerComposition extends EventHandler { * Inserts an opaque part of the layer (non semi-transparent mesh instances) at the chosen * index in the {@link LayerComposition#layerList}. * - * @param {import('../layer.js').Layer} layer - A {@link Layer} to add. + * @param {Layer} layer - A {@link Layer} to add. * @param {number} index - Insertion position. */ insertOpaque(layer, index) { @@ -530,7 +535,7 @@ class LayerComposition extends EventHandler { * Removes an opaque part of the layer (non semi-transparent mesh instances) from * {@link LayerComposition#layerList}. * - * @param {import('../layer.js').Layer} layer - A {@link Layer} to remove. + * @param {Layer} layer - A {@link Layer} to remove. */ removeOpaque(layer) { // remove opaque occurrences of a layer @@ -556,7 +561,7 @@ class LayerComposition extends EventHandler { /** * Adds part of the layer with semi-transparent objects to the end of the {@link LayerComposition#layerList}. * - * @param {import('../layer.js').Layer} layer - A {@link Layer} to add. + * @param {Layer} layer - A {@link Layer} to add. */ pushTransparent(layer) { // add transparent to the end of the array @@ -573,7 +578,7 @@ class LayerComposition extends EventHandler { /** * Inserts a semi-transparent part of the layer at the chosen index in the {@link LayerComposition#layerList}. * - * @param {import('../layer.js').Layer} layer - A {@link Layer} to add. + * @param {Layer} layer - A {@link Layer} to add. * @param {number} index - Insertion position. */ insertTransparent(layer, index) { @@ -595,7 +600,7 @@ class LayerComposition extends EventHandler { /** * Removes a transparent part of the layer from {@link LayerComposition#layerList}. * - * @param {import('../layer.js').Layer} layer - A {@link Layer} to remove. + * @param {Layer} layer - A {@link Layer} to remove. */ removeTransparent(layer) { // remove transparent occurrences of a layer @@ -621,7 +626,7 @@ class LayerComposition extends EventHandler { /** * Gets index of the opaque part of the supplied layer in the {@link LayerComposition#layerList}. * - * @param {import('../layer.js').Layer} layer - A {@link Layer} to find index of. + * @param {Layer} layer - A {@link Layer} to find index of. * @returns {number} The index of the opaque part of the specified layer, or -1 if it is not * part of the composition. */ @@ -632,7 +637,7 @@ class LayerComposition extends EventHandler { /** * Gets index of the semi-transparent part of the supplied layer in the {@link LayerComposition#layerList}. * - * @param {import('../layer.js').Layer} layer - A {@link Layer} to find index of. + * @param {Layer} layer - A {@link Layer} to find index of. * @returns {number} The index of the semi-transparent part of the specified layer, or -1 if it * is not part of the composition. */ @@ -671,8 +676,8 @@ class LayerComposition extends EventHandler { * Finds a layer inside this composition by its ID. Null is returned, if nothing is found. * * @param {number} id - An ID of the layer to find. - * @returns {import('../layer.js').Layer|null} The layer corresponding to the specified ID. - * Returns null if layer is not found. + * @returns {Layer|null} The layer corresponding to the specified ID. Returns null if layer is + * not found. */ getLayerById(id) { return this.layerIdMap.get(id) ?? null; @@ -682,8 +687,8 @@ class LayerComposition extends EventHandler { * Finds a layer inside this composition by its name. Null is returned, if nothing is found. * * @param {string} name - The name of the layer to find. - * @returns {import('../layer.js').Layer|null} The layer corresponding to the specified name. - * Returns null if layer is not found. + * @returns {Layer|null} The layer corresponding to the specified name. Returns null if layer + * is not found. */ getLayerByName(name) { return this.layerNameMap.get(name) ?? null; diff --git a/src/scene/composition/render-action.js b/src/scene/composition/render-action.js index 5d24c4f200b..369643a33e5 100644 --- a/src/scene/composition/render-action.js +++ b/src/scene/composition/render-action.js @@ -1,3 +1,9 @@ +/** + * @import { BindGroup } from '../../platform/graphics/bind-group.js' + * @import { Layer } from '../layer.js' + * @import { RenderTarget } from '../../platform/graphics/render-target.js' + */ + /** * Class representing an entry in the final order of rendering of cameras and layers in the engine * this is populated at runtime based on LayerComposition @@ -6,7 +12,7 @@ class RenderAction { constructor() { // the layer - /** @type {import('../layer.js').Layer|null} */ + /** @type {Layer|null} */ this.layer = null; // true if this uses transparent sublayer, opaque otherwise @@ -18,7 +24,7 @@ class RenderAction { /** * render target this render action renders to (taken from either camera or layer) * - * @type {import('../../platform/graphics/render-target.js').RenderTarget|null} + * @type {RenderTarget|null} */ this.renderTarget = null; @@ -40,7 +46,7 @@ class RenderAction { this.lastCameraUse = false; // an array of view bind groups (the number of these corresponds to the number of views when XR is used) - /** @type {import('../../platform/graphics/bind-group.js').BindGroup[]} */ + /** @type {BindGroup[]} */ this.viewBindGroups = []; // true if the camera should render using render passes it specifies diff --git a/src/scene/compress/compress-utils.js b/src/scene/compress/compress-utils.js index 1d4977a9d33..3b1789d5534 100644 --- a/src/scene/compress/compress-utils.js +++ b/src/scene/compress/compress-utils.js @@ -1,8 +1,12 @@ +/** + * @import { Entity } from '../../framework/entity.js' + */ + class CompressUtils { /** * Set position, rotation and scale of an entity using compressed scene format. * - * @param {import('../../framework/entity.js').Entity} entity - The entity. + * @param {Entity} entity - The entity. * @param {object} data - Json entity data from a compressed scene. * @param {object} compressed - Compression metadata. */ diff --git a/src/scene/frame-graph.js b/src/scene/frame-graph.js index 7b5e253ae76..1d1ee1b811b 100644 --- a/src/scene/frame-graph.js +++ b/src/scene/frame-graph.js @@ -1,24 +1,29 @@ import { Debug } from '../core/debug.js'; +/** + * @import { RenderPass } from '../platform/graphics/render-pass.js' + * @import { RenderTarget } from '../platform/graphics/render-target.js' + * @import { Texture } from '../platform/graphics/texture.js' + */ + /** * A frame graph represents a single rendering frame as a sequence of render passes. */ class FrameGraph { - /** @type {import('../platform/graphics/render-pass.js').RenderPass[]} */ + /** @type {RenderPass[]} */ renderPasses = []; /** * Map used during frame graph compilation. It maps a render target to its previous occurrence. * - * @type {Map} + * @type {Map} */ renderTargetMap = new Map(); /** * Add a render pass to the frame. * - * @param {import('../platform/graphics/render-pass.js').RenderPass} renderPass - The render - * pass to add. + * @param {RenderPass} renderPass - The render pass to add. */ addRenderPass(renderPass) { Debug.assert(renderPass); @@ -89,9 +94,9 @@ class FrameGraph { // If those passes are separated only by passes not requiring cubemap (shadows ..), // we skip the mipmap generation till the last rendering to the cubemap, to avoid // mipmaps being generated after each face. - /** @type {import('../platform/graphics/texture.js').Texture} */ + /** @type {Texture} */ let lastCubeTexture = null; - /** @type {import('../platform/graphics/render-pass.js').RenderPass} */ + /** @type {RenderPass} */ let lastCubeRenderPass = null; for (let i = 0; i < renderPasses.length; i++) { const renderPass = renderPasses[i]; diff --git a/src/scene/graphics/post-effect.js b/src/scene/graphics/post-effect.js index 69ba9ae1d03..215254666a9 100644 --- a/src/scene/graphics/post-effect.js +++ b/src/scene/graphics/post-effect.js @@ -2,6 +2,12 @@ import { Vec4 } from '../../core/math/vec4.js'; import { BlendState } from '../../platform/graphics/blend-state.js'; import { drawQuadWithShader } from './quad-render-utils.js'; +/** + * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js' + * @import { RenderTarget } from '../../platform/graphics/render-target.js' + * @import { Shader } from '../../platform/graphics/shader.js' + */ + const _viewport = new Vec4(); /** @@ -15,14 +21,13 @@ class PostEffect { /** * Create a new PostEffect instance. * - * @param {import('../../platform/graphics/graphics-device.js').GraphicsDevice} graphicsDevice - - * The graphics device of the application. + * @param {GraphicsDevice} graphicsDevice - The graphics device of the application. */ constructor(graphicsDevice) { /** * The graphics device of the application. * - * @type {import('../../platform/graphics/graphics-device.js').GraphicsDevice} + * @type {GraphicsDevice} */ this.device = graphicsDevice; @@ -54,12 +59,11 @@ class PostEffect { /** * Render the post effect using the specified inputTarget to the specified outputTarget. * - * @param {import('../../platform/graphics/render-target.js').RenderTarget} inputTarget - The - * input render target. - * @param {import('../../platform/graphics/render-target.js').RenderTarget} outputTarget - The - * output render target. If null then this will be the screen. - * @param {import('../../core/math/vec4.js').Vec4} [rect] - The rect of the current camera. If - * not specified, it will default to [0, 0, 1, 1]. + * @param {RenderTarget} inputTarget - The input render target. + * @param {RenderTarget} outputTarget - The output render target. If null then this will be the + * screen. + * @param {Vec4} [rect] - The rect of the current camera. If not specified, it will default to + * `[0, 0, 1, 1]`. */ render(inputTarget, outputTarget, rect) { } @@ -67,12 +71,10 @@ class PostEffect { /** * Draw a screen-space rectangle in a render target, using a specified shader. * - * @param {import('../../platform/graphics/render-target.js').RenderTarget|null} target - The - * output render target. - * @param {import('../../platform/graphics/shader.js').Shader} shader - The shader to be used - * for drawing the rectangle. - * @param {import('../../core/math/vec4.js').Vec4} [rect] - The normalized screen-space position - * (rect.x, rect.y) and size (rect.z, rect.w) of the rectangle. Default is [0, 0, 1, 1]. + * @param {RenderTarget|null} target - The output render target. + * @param {Shader} shader - The shader to be used for drawing the rectangle. + * @param {Vec4} [rect] - The normalized screen-space position (rect.x, rect.y) and size (rect.z, + * rect.w) of the rectangle. Default is `[0, 0, 1, 1]`. */ drawQuad(target, shader, rect) { let viewport; diff --git a/src/scene/graphics/quad-render-utils.js b/src/scene/graphics/quad-render-utils.js index 01019446cb2..f50520272f8 100644 --- a/src/scene/graphics/quad-render-utils.js +++ b/src/scene/graphics/quad-render-utils.js @@ -1,20 +1,25 @@ import { Debug } from '../../core/debug.js'; import { Vec4 } from '../../core/math/vec4.js'; - import { QuadRender } from './quad-render.js'; import { RenderPassQuad } from './render-pass-quad.js'; +/** + * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js' + * @import { RenderTarget } from '../../platform/graphics/render-target.js' + * @import { Shader } from '../../platform/graphics/shader.js' + * @import { Texture } from '../../platform/graphics/texture.js' + */ + const _tempRect = new Vec4(); /** * Draws a screen-space quad using a specific shader. * - * @param {import('../../platform/graphics/graphics-device.js').GraphicsDevice} device - The graphics device used to draw - * the quad. - * @param {import('../../platform/graphics/render-target.js').RenderTarget|null} target - The destination render - * target. If undefined, target is the frame buffer. - * @param {import('../../platform/graphics/shader.js').Shader} shader - The shader used for rendering the quad. Vertex - * shader should contain `attribute vec2 vertex_position`. + * @param {GraphicsDevice} device - The graphics device used to draw the quad. + * @param {RenderTarget|null} target - The destination render target. If undefined, target is the + * frame buffer. + * @param {Shader} shader - The shader used for rendering the quad. Vertex shader should contain + * `attribute vec2 vertex_position`. * @param {Vec4} [rect] - The viewport rectangle of the quad, in pixels. Defaults to fullscreen: * `[0, 0, target.width, target.height]`. * @param {Vec4} [scissorRect] - The scissor rectangle of the quad, in pixels. Defaults to fullscreen: @@ -68,14 +73,11 @@ function drawQuadWithShader(device, target, shader, rect, scissorRect) { /** * Draws a texture in screen-space. Mostly used by post-effects. * - * @param {import('../../platform/graphics/graphics-device.js').GraphicsDevice} device - The graphics device used to draw - * the texture. - * @param {import('../../platform/graphics/texture.js').Texture} texture - The source texture to be drawn. Accessible as + * @param {GraphicsDevice} device - The graphics device used to draw the texture. + * @param {Texture} texture - The source texture to be drawn. Accessible as * `uniform sampler2D * source` in shader. - * @param {import('../../platform/graphics/render-target.js').RenderTarget} [target] - The destination render target. - * Defaults to the frame buffer. - * @param {import('../../platform/graphics/shader.js').Shader} [shader] - The optional custom - * shader used for rendering the texture. + * @param {RenderTarget} [target] - The destination render target. Defaults to the frame buffer. + * @param {Shader} [shader] - The optional custom shader used for rendering the texture. * @param {Vec4} [rect] - The viewport rectangle to use for the texture, in pixels. Defaults to * fullscreen: `[0, 0, target.width, target.height]`. * @param {Vec4} [scissorRect] - The scissor rectangle to use for the texture, in pixels. Defaults diff --git a/src/scene/graphics/quad-render.js b/src/scene/graphics/quad-render.js index ab7693fd873..eb9ed8f3daf 100644 --- a/src/scene/graphics/quad-render.js +++ b/src/scene/graphics/quad-render.js @@ -7,6 +7,10 @@ import { ShaderProcessorOptions } from "../../platform/graphics/shader-processor import { UniformBuffer } from "../../platform/graphics/uniform-buffer.js"; import { processShader } from "../shader-lib/utils.js"; +/** + * @import { Shader } from '../../platform/graphics/shader.js' + */ + const _quadPrimitive = { type: PRIMITIVE_TRISTRIP, base: 0, @@ -48,7 +52,7 @@ class QuadRender { /** * Create a new QuadRender instance. * - * @param {import('../../platform/graphics/shader.js').Shader} shader - The shader to be used to render the quad. + * @param {Shader} shader - The shader to be used to render the quad. */ constructor(shader) { @@ -91,10 +95,10 @@ class QuadRender { * Renders the quad. If the viewport is provided, the original viewport and scissor is restored * after the rendering. * - * @param {import('../../core/math/vec4.js').Vec4} [viewport] - The viewport rectangle of the - * quad, in pixels. The viewport is not changed if not provided. - * @param {import('../../core/math/vec4.js').Vec4} [scissor] - The scissor rectangle of the - * quad, in pixels. Used only if the viewport is provided. + * @param {Vec4} [viewport] - The viewport rectangle of the quad, in pixels. The viewport is + * not changed if not provided. + * @param {Vec4} [scissor] - The scissor rectangle of the quad, in pixels. Used only if the + * viewport is provided. */ render(viewport, scissor) { diff --git a/src/scene/graphics/render-pass-color-grab.js b/src/scene/graphics/render-pass-color-grab.js index 6a7c3eb00f7..cec507ac02e 100644 --- a/src/scene/graphics/render-pass-color-grab.js +++ b/src/scene/graphics/render-pass-color-grab.js @@ -4,17 +4,12 @@ import { RenderPass } from "../../platform/graphics/render-pass.js"; import { RenderTarget } from "../../platform/graphics/render-target.js"; import { Texture } from "../../platform/graphics/texture.js"; -// uniform names (first is current name, second one is deprecated name for compatibility) -const _colorUniformNames = ['uSceneColorMap', 'texture_grabPass']; +// uniform name +const _colorUniformName = 'uSceneColorMap'; /** * A render pass implementing grab of a color buffer. * - * TODO: implement mipmapped color buffer support for WebGL 1 as well, which requires - * the texture to be a power of two, by first downscaling the captured framebuffer - * texture to smaller power of 2 texture, and then generate mipmaps and use it for rendering - * TODO: or even better, implement blur filter to have smoother lower levels - * * @ignore */ class RenderPassColorGrab extends RenderPass { @@ -50,7 +45,7 @@ class RenderPassColorGrab extends RenderPass { // allocate texture buffer const mipmaps = device.isWebGL2; const texture = new Texture(device, { - name: _colorUniformNames[0], + name: _colorUniformName, format, width: sourceRenderTarget ? sourceRenderTarget.colorBuffer.width : device.width, height: sourceRenderTarget ? sourceRenderTarget.colorBuffer.height : device.height, @@ -108,7 +103,7 @@ class RenderPassColorGrab extends RenderPass { // assign uniform const colorBuffer = this.colorRenderTarget.colorBuffer; - _colorUniformNames.forEach(name => device.scope.resolve(name).setValue(colorBuffer)); + device.scope.resolve(_colorUniformName).setValue(colorBuffer); } execute() { @@ -135,22 +130,6 @@ class RenderPassColorGrab extends RenderPass { device.activeTexture(device.maxCombinedTextures - 1); device.bindTexture(colorBuffer); device.gl.generateMipmap(colorBuffer.impl._glTarget); - - } else { // webgl 1 - - // initialize the texture - if (!colorBuffer.impl._glTexture) { - colorBuffer.impl.initialize(device, colorBuffer); - } - - // copy framebuffer to it - device.bindTexture(colorBuffer); - const gl = device.gl; - gl.copyTexImage2D(gl.TEXTURE_2D, 0, colorBuffer.impl._glFormat, 0, 0, colorBuffer.width, colorBuffer.height, 0); - - // stop the device from updating this texture further - colorBuffer._needsUpload = false; - colorBuffer._needsMipmapsUpload = false; } DebugGraphics.popGpuMarker(device); diff --git a/src/scene/graphics/render-pass-depth-grab.js b/src/scene/graphics/render-pass-depth-grab.js index 7b0a3227b76..764014e5ad5 100644 --- a/src/scene/graphics/render-pass-depth-grab.js +++ b/src/scene/graphics/render-pass-depth-grab.js @@ -4,8 +4,8 @@ import { RenderPass } from "../../platform/graphics/render-pass.js"; import { RenderTarget } from "../../platform/graphics/render-target.js"; import { Texture } from "../../platform/graphics/texture.js"; -// uniform names (first is current name, second one is deprecated name for compatibility) -const _depthUniformNames = ['uSceneDepthMap', 'uDepthMap']; +// uniform name +const _depthUniformName = 'uSceneDepthMap'; /** * A render pass implementing grab of a depth buffer, used on WebGL 2 and WebGPU devices. @@ -39,7 +39,7 @@ class RenderPassDepthGrab extends RenderPass { // allocate texture buffer const texture = new Texture(device, { - name: _depthUniformNames[0], + name: _depthUniformName, format, width: sourceRenderTarget ? sourceRenderTarget.colorBuffer.width : device.width, height: sourceRenderTarget ? sourceRenderTarget.colorBuffer.height : device.height, @@ -116,7 +116,7 @@ class RenderPassDepthGrab extends RenderPass { // assign uniform const colorBuffer = useDepthBuffer ? this.depthRenderTarget.depthBuffer : this.depthRenderTarget.colorBuffer; - _depthUniformNames.forEach(name => device.scope.resolve(name).setValue(colorBuffer)); + device.scope.resolve(_depthUniformName).setValue(colorBuffer); } execute() { diff --git a/src/scene/graphics/render-pass-shader-quad.js b/src/scene/graphics/render-pass-shader-quad.js index da78187ce02..aa71f64fbc0 100644 --- a/src/scene/graphics/render-pass-shader-quad.js +++ b/src/scene/graphics/render-pass-shader-quad.js @@ -5,6 +5,11 @@ import { DepthState } from "../../platform/graphics/depth-state.js"; import { RenderPass } from "../../platform/graphics/render-pass.js"; import { createShaderFromCode } from "../shader-lib/utils.js"; +/** + * @import { Shader } from '../../platform/graphics/shader.js' + * @import { StencilParameters } from '../../platform/graphics/stencil-parameters.js' + */ + /** * A render pass that implements rendering a quad with a shader, and exposes controls over the * render state. This is typically used as a base class for render passes that render a quad with @@ -39,14 +44,14 @@ class RenderPassShaderQuad extends RenderPass { /** * Stencil parameters for front faces to use when rendering the quad. Defaults to null. * - * @type {import('../../platform/graphics/stencil-parameters.js').StencilParameters|null} + * @type {StencilParameters|null} */ stencilFront = null; /** * Stencil parameters for back faces to use when rendering the quad. Defaults to null. * - * @type {import('../../platform/graphics/stencil-parameters.js').StencilParameters|null} + * @type {StencilParameters|null} */ stencilBack = null; @@ -69,7 +74,7 @@ class RenderPassShaderQuad extends RenderPass { /** * Sets the shader used to render the quad. * - * @type {import('../../platform/graphics/shader.js').Shader} + * @type {Shader} * @ignore */ set shader(shader) { diff --git a/src/scene/graphics/reproject-texture.js b/src/scene/graphics/reproject-texture.js index 83d925a9f33..d143e5834bf 100644 --- a/src/scene/graphics/reproject-texture.js +++ b/src/scene/graphics/reproject-texture.js @@ -1,7 +1,6 @@ import { Debug } from '../../core/debug.js'; import { random } from '../../core/math/random.js'; import { Vec3 } from '../../core/math/vec3.js'; - import { FILTER_NEAREST, TEXTUREPROJECTION_OCTAHEDRAL, TEXTUREPROJECTION_CUBE @@ -9,14 +8,17 @@ import { import { DebugGraphics } from '../../platform/graphics/debug-graphics.js'; import { DeviceCache } from '../../platform/graphics/device-cache.js'; import { RenderTarget } from '../../platform/graphics/render-target.js'; -import { drawQuadWithShader } from './quad-render-utils.js'; import { Texture } from '../../platform/graphics/texture.js'; - import { ChunkUtils } from '../shader-lib/chunk-utils.js'; import { shaderChunks } from '../shader-lib/chunks/chunks.js'; import { getProgramLibrary } from '../shader-lib/get-program-library.js'; import { createShaderFromCode } from '../shader-lib/utils.js'; import { BlendState } from '../../platform/graphics/blend-state.js'; +import { drawQuadWithShader } from './quad-render-utils.js'; + +/** + * @import { Vec4 } from '../../core/math/vec4.js' + */ const getProjectionName = (projection) => { switch (projection) { @@ -393,7 +395,7 @@ void main(void) { * @param {number} [options.face] - Optional cubemap face to update (default is update all faces). * @param {string} [options.distribution] - Specify convolution distribution - 'none', 'lambert', * 'phong', 'ggx'. Default depends on specularPower. - * @param {import('../../core/math/vec4.js').Vec4} [options.rect] - Optional viewport rectangle. + * @param {Vec4} [options.rect] - Optional viewport rectangle. * @param {number} [options.seamPixels] - Optional number of seam pixels to render * @returns {boolean} True if the reprojection was applied and false otherwise (e.g. if rect is empty) * @category Graphics diff --git a/src/scene/gsplat/gsplat-compressed-data.js b/src/scene/gsplat/gsplat-compressed-data.js index e7563078543..a4491db5df2 100644 --- a/src/scene/gsplat/gsplat-compressed-data.js +++ b/src/scene/gsplat/gsplat-compressed-data.js @@ -3,6 +3,10 @@ import { Vec3 } from '../../core/math/vec3.js'; import { Vec4 } from '../../core/math/vec4.js'; import { GSplatData } from './gsplat-data.js'; +/** + * @import { BoundingBox } from '../../core/shape/bounding-box.js' + */ + const SH_C0 = 0.28209479177387814; // iterator for accessing compressed splat data @@ -115,7 +119,7 @@ class GSplatCompressedData { * Calculate pessimistic scene aabb taking into account splat size. This is faster than * calculating an exact aabb. * - * @param {import('../../core/shape/bounding-box.js').BoundingBox} result - Where to store the resulting bounding box. + * @param {BoundingBox} result - Where to store the resulting bounding box. * @returns {boolean} - Whether the calculation was successful. */ calcAabb(result) { diff --git a/src/scene/gsplat/gsplat-compressed.js b/src/scene/gsplat/gsplat-compressed.js index a437d3f6d5b..b0e68fd4fb9 100644 --- a/src/scene/gsplat/gsplat-compressed.js +++ b/src/scene/gsplat/gsplat-compressed.js @@ -1,17 +1,25 @@ import { Vec2 } from '../../core/math/vec2.js'; +import { Texture } from '../../platform/graphics/texture.js'; +import { BoundingBox } from '../../core/shape/bounding-box.js'; import { ADDRESS_CLAMP_TO_EDGE, FILTER_NEAREST, PIXELFORMAT_RGBA32F, PIXELFORMAT_RGBA32U } from '../../platform/graphics/constants.js'; -import { Texture } from '../../platform/graphics/texture.js'; -import { BoundingBox } from '../../core/shape/bounding-box.js'; import { createGSplatCompressedMaterial } from './gsplat-compressed-material.js'; +/** + * @import { BoundingBox } from '../../core/shape/bounding-box.js' + * @import { GSplatCompressedData } from './gsplat-compressed-data.js' + * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js' + * @import { Material } from '../materials/material.js' + * @import { SplatMaterialOptions } from './gsplat-material.js' + */ + class GSplatCompressed { device; numSplats; - /** @type {import('../../core/shape/bounding-box.js').BoundingBox} */ + /** @type {BoundingBox} */ aabb; /** @type {Float32Array} */ @@ -24,8 +32,8 @@ class GSplatCompressed { chunkTexture; /** - * @param {import('../../platform/graphics/graphics-device.js').GraphicsDevice} device - The graphics device. - * @param {import('./gsplat-compressed-data.js').GSplatCompressedData} gsplatData - The splat data. + * @param {GraphicsDevice} device - The graphics device. + * @param {GSplatCompressedData} gsplatData - The splat data. */ constructor(device, gsplatData) { const numSplats = gsplatData.numSplats; @@ -58,9 +66,8 @@ class GSplatCompressed { } /** - * @param {import('./gsplat-material.js').SplatMaterialOptions} options - The splat material options. - * @returns {import('../materials/material.js').Material} material - The material to set up for - * the splat rendering. + * @param {SplatMaterialOptions} options - The splat material options. + * @returns {Material} material - The material to set up for the splat rendering. */ createMaterial(options) { const result = createGSplatCompressedMaterial(options); diff --git a/src/scene/gsplat/gsplat-data.js b/src/scene/gsplat/gsplat-data.js index b4a61f7e514..37a3dddf868 100644 --- a/src/scene/gsplat/gsplat-data.js +++ b/src/scene/gsplat/gsplat-data.js @@ -4,6 +4,12 @@ import { Quat } from '../../core/math/quat.js'; import { Vec3 } from '../../core/math/vec3.js'; import { BoundingBox } from '../../core/shape/bounding-box.js'; +/** + * @import { PlyElement } from '../../framework/parsers/ply.js' + * @import { Scene } from '../scene.js' + * @import { Vec4 } from '../../core/math/vec4.js' + */ + const vec3 = new Vec3(); const mat4 = new Mat4(); const quat = new Quat(); @@ -89,14 +95,14 @@ const calcSplatMat = (result, p, r) => { }; class GSplatData { - // /** @type {import('./ply-reader').PlyElement[]} */ + /** @type {PlyElement[]} */ elements; numSplats; - // /** - // * @param {import('./ply-reader').PlyElement[]} elements - The elements. - // */ + /** + * @param {PlyElement[]} elements - The elements. + */ constructor(elements) { this.elements = elements; this.numSplats = this.getElement('vertex').count; @@ -177,7 +183,7 @@ class GSplatData { * @param {Vec3|null} [p] - the vector to receive splat position * @param {Quat|null} [r] - the quaternion to receive splat rotation * @param {Vec3|null} [s] - the vector to receive splat scale - * @param {import('../../core/math/vec4.js').Vec4|null} [c] - the vector to receive splat color + * @param {Vec4|null} [c] - the vector to receive splat color * @returns {SplatIterator} - The iterator */ createIter(p, r, s, c) { @@ -319,7 +325,7 @@ class GSplatData { } /** - * @param {import('../scene.js').Scene} scene - The application's scene. + * @param {Scene} scene - The application's scene. * @param {Mat4} worldMat - The world matrix. */ renderWireframeBounds(scene, worldMat) { diff --git a/src/scene/gsplat/gsplat-instance.js b/src/scene/gsplat/gsplat-instance.js index 89b80762bbc..6a0194febd9 100644 --- a/src/scene/gsplat/gsplat-instance.js +++ b/src/scene/gsplat/gsplat-instance.js @@ -8,6 +8,15 @@ import { GSplatSorter } from './gsplat-sorter.js'; import { VertexFormat } from '../../platform/graphics/vertex-format.js'; import { VertexBuffer } from '../../platform/graphics/vertex-buffer.js'; +/** + * @import { Camera } from '../camera.js' + * @import { GSplat } from './gsplat.js' + * @import { GraphNode } from '../graph-node.js' + * @import { Material } from '../materials/material.js' + * @import { SplatMaterialOptions } from './gsplat-material.js' + * @import { Texture } from '../../platform/graphics/texture.js' + */ + const mat = new Mat4(); const cameraPosition = new Vec3(); const cameraDirection = new Vec3(); @@ -15,7 +24,7 @@ const viewport = [0, 0]; /** @ignore */ class GSplatInstance { - /** @type {import('./gsplat.js').GSplat} */ + /** @type {GSplat} */ splat; /** @type {Mesh} */ @@ -24,10 +33,10 @@ class GSplatInstance { /** @type {MeshInstance} */ meshInstance; - /** @type {import('../materials/material.js').Material} */ + /** @type {Material} */ material; - /** @type {import('../../platform/graphics/texture.js').Texture} */ + /** @type {Texture} */ orderTexture; options = {}; @@ -42,14 +51,14 @@ class GSplatInstance { /** * List of cameras this instance is visible for. Updated every frame by the renderer. * - * @type {import('../camera.js').Camera[]} + * @type {Camera[]} * @ignore */ cameras = []; /** - * @param {import('./gsplat.js').GSplat} splat - The splat instance. - * @param {import('./gsplat-material.js').SplatMaterialOptions} options - The options. + * @param {GSplat} splat - The splat instance. + * @param {SplatMaterialOptions} options - The options. */ constructor(splat, options) { this.splat = splat; @@ -166,7 +175,7 @@ class GSplatInstance { /** * Sorts the GS vertices based on the given camera. - * @param {import('../graph-node.js').GraphNode} cameraNode - The camera node used for sorting. + * @param {GraphNode} cameraNode - The camera node used for sorting. */ sort(cameraNode) { if (this.sorter) { diff --git a/src/scene/gsplat/gsplat.js b/src/scene/gsplat/gsplat.js index 33d9e098189..6d568e43510 100644 --- a/src/scene/gsplat/gsplat.js +++ b/src/scene/gsplat/gsplat.js @@ -13,6 +13,12 @@ import { Texture } from '../../platform/graphics/texture.js'; import { BoundingBox } from '../../core/shape/bounding-box.js'; import { createGSplatMaterial } from './gsplat-material.js'; +/** + * @import { GSplatData } from './gsplat-data.js' + * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js' + * @import { Material } from '../materials/material.js' + */ + const _tmpVecA = new Vec3(); const _tmpVecB = new Vec3(); const _tmpVecC = new Vec3(); @@ -29,7 +35,7 @@ class GSplat { /** @type {Float32Array} */ centers; - /** @type {import('../../core/shape/bounding-box.js').BoundingBox} */ + /** @type {BoundingBox} */ aabb; /** @type {Texture} */ @@ -45,8 +51,8 @@ class GSplat { transformCTexture; /** - * @param {import('../../platform/graphics/graphics-device.js').GraphicsDevice} device - The graphics device. - * @param {import('./gsplat-data.js').GSplatData} gsplatData - The splat data. + * @param {GraphicsDevice} device - The graphics device. + * @param {GSplatData} gsplatData - The splat data. */ constructor(device, gsplatData) { const numSplats = gsplatData.numSplats; @@ -79,8 +85,7 @@ class GSplat { } /** - * @returns {import('../materials/material.js').Material} material - The material to set up for - * the splat rendering. + * @returns {Material} material - The material to set up for the splat rendering. */ createMaterial(options) { const result = createGSplatMaterial(options); @@ -134,7 +139,7 @@ class GSplat { * 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. * - * @param {import('./gsplat-data.js').GSplatData} gsplatData - The source data + * @param {GSplatData} gsplatData - The source data */ updateColorData(gsplatData) { const texture = this.colorTexture; @@ -158,7 +163,7 @@ class GSplat { } /** - * @param {import('./gsplat-data.js').GSplatData} gsplatData - The source data + * @param {GSplatData} gsplatData - The source data */ updateTransformData(gsplatData) { diff --git a/src/scene/layer.js b/src/scene/layer.js index 560f210c421..1c881b8a7ff 100644 --- a/src/scene/layer.js +++ b/src/scene/layer.js @@ -1,6 +1,5 @@ import { Debug } from '../core/debug.js'; import { hash32Fnv1a } from '../core/hash.js'; - import { LIGHTTYPE_DIRECTIONAL, LAYER_FX, @@ -9,6 +8,21 @@ import { } from './constants.js'; import { Material } from './materials/material.js'; +/** + * @import { Camera } from './camera.js' + * @import { CameraComponent } from '../framework/components/camera/component.js' + * @import { Light } from './light.js' + * @import { LightComponent } from '../framework/components/light/component.js' + * @import { MeshInstance } from './mesh-instance.js' + * @import { Vec3 } from '../core/math/vec3.js' + */ + +// Layers +let layerCounter = 0; + +const lightKeys = []; +const _tempMaterials = new Set(); + function sortManual(drawCallA, drawCallB) { return drawCallA.drawOrder - drawCallB.drawOrder; } @@ -32,24 +46,18 @@ function sortFrontToBack(drawCallA, drawCallB) { const sortCallbacks = [null, sortManual, sortMaterialMesh, sortBackToFront, sortFrontToBack]; -// Layers -let layerCounter = 0; - -const lightKeys = []; -const _tempMaterials = new Set(); - class CulledInstances { /** * Visible opaque mesh instances. * - * @type {import('./mesh-instance.js').MeshInstance[]} + * @type {MeshInstance[]} */ opaque = []; /** * Visible transparent mesh instances. * - * @type {import('./mesh-instance.js').MeshInstance[]} + * @type {MeshInstance[]} */ transparent = []; } @@ -65,7 +73,7 @@ class Layer { /** * Mesh instances assigned to this layer. * - * @type {import('./mesh-instance.js').MeshInstance[]} + * @type {MeshInstance[]} * @ignore */ meshInstances = []; @@ -73,7 +81,7 @@ class Layer { /** * Mesh instances assigned to this layer, stored in a set. * - * @type {Set} + * @type {Set} * @ignore */ meshInstancesSet = new Set(); @@ -81,7 +89,7 @@ class Layer { /** * Shadow casting instances assigned to this layer. * - * @type {import('./mesh-instance.js').MeshInstance[]} + * @type {MeshInstance[]} * @ignore */ shadowCasters = []; @@ -89,7 +97,7 @@ class Layer { /** * Shadow casting instances assigned to this layer, stored in a set. * - * @type {Set} + * @type {Set} * @ignore */ shadowCastersSet = new Set(); @@ -97,7 +105,7 @@ class Layer { /** * Visible (culled) mesh instances assigned to this layer. Looked up by the Camera. * - * @type {WeakMap} + * @type {WeakMap} * @private */ _visibleInstances = new WeakMap(); @@ -105,7 +113,7 @@ class Layer { /** * All lights assigned to a layer. * - * @type {import('./light.js').Light[]} + * @type {Light[]} * @private */ _lights = []; @@ -113,7 +121,7 @@ class Layer { /** * All lights assigned to a layer stored in a set. * - * @type {Set} + * @type {Set} * @private */ @@ -122,7 +130,7 @@ class Layer { /** * Set of light used by clustered lighting (omni and spot, but no directional). * - * @type {Set} + * @type {Set} * @private */ _clusteredLightsSet = new Set(); @@ -132,7 +140,7 @@ class Layer { * to match their order in _lightIdHash, so that their order matches the order expected by the * generated shader code. * - * @type {import('./light.js').Light[][]} + * @type {Light[][]} * @private */ _splitLights = [[], [], []]; @@ -155,13 +163,13 @@ class Layer { requiresLightCube = false; /** - * @type {import('../framework/components/camera/component.js').CameraComponent[]} + * @type {CameraComponent[]} * @ignore */ cameras = []; /** - * @type {Set} + * @type {Set} * @ignore */ camerasSet = new Set(); @@ -525,7 +533,7 @@ class Layer { /** * Gets the lights used by clustered lighting in a set. * - * @type {Set} + * @type {Set} * @ignore */ get clusteredLightsSet() { @@ -573,8 +581,7 @@ class Layer { /** * Adds an array of mesh instances to this layer. * - * @param {import('./mesh-instance.js').MeshInstance[]} meshInstances - Array of - * {@link MeshInstance}. + * @param {MeshInstance[]} meshInstances - Array of {@link MeshInstance}. * @param {boolean} [skipShadowCasters] - Set it to true if you don't want these mesh instances * to cast shadows in this layer. Defaults to false. */ @@ -618,8 +625,8 @@ class Layer { /** * Removes multiple mesh instances from this layer. * - * @param {import('./mesh-instance.js').MeshInstance[]} meshInstances - Array of - * {@link MeshInstance}. If they were added to this layer, they will be removed. + * @param {MeshInstance[]} meshInstances - Array of {@link MeshInstance}. If they were added to + * this layer, they will be removed. * @param {boolean} [skipShadowCasters] - Set it to true if you want to still cast shadows from * removed mesh instances or if they never did cast shadows before. Defaults to false. */ @@ -652,8 +659,7 @@ class Layer { * Adds an array of mesh instances to this layer, but only as shadow casters (they will not be * rendered anywhere, but only cast shadows on other objects). * - * @param {import('./mesh-instance.js').MeshInstance[]} meshInstances - Array of - * {@link MeshInstance}. + * @param {MeshInstance[]} meshInstances - Array of {@link MeshInstance}. */ addShadowCasters(meshInstances) { const shadowCasters = this.shadowCasters; @@ -672,8 +678,8 @@ class Layer { * Removes multiple mesh instances from the shadow casters list of this layer, meaning they * will stop casting shadows. * - * @param {import('./mesh-instance.js').MeshInstance[]} meshInstances - Array of - * {@link MeshInstance}. If they were added to this layer, they will be removed. + * @param {MeshInstance[]} meshInstances - Array of {@link MeshInstance}. If they were added to + * this layer, they will be removed. */ removeShadowCasters(meshInstances) { const shadowCasters = this.shadowCasters; @@ -716,8 +722,7 @@ class Layer { /** * Adds a light to this layer. * - * @param {import('../framework/components/light/component.js').LightComponent} light - A - * {@link LightComponent}. + * @param {LightComponent} light - A {@link LightComponent}. */ addLight(light) { @@ -738,8 +743,7 @@ class Layer { /** * Removes a light from this layer. * - * @param {import('../framework/components/light/component.js').LightComponent} light - A - * {@link LightComponent}. + * @param {LightComponent} light - A {@link LightComponent}. */ removeLight(light) { @@ -853,8 +857,7 @@ class Layer { /** * Adds a camera to this layer. * - * @param {import('../framework/components/camera/component.js').CameraComponent} camera - A - * {@link CameraComponent}. + * @param {CameraComponent} camera - A {@link CameraComponent}. */ addCamera(camera) { if (!this.camerasSet.has(camera.camera)) { @@ -867,8 +870,7 @@ class Layer { /** * Removes a camera from this layer. * - * @param {import('../framework/components/camera/component.js').CameraComponent} camera - A - * {@link CameraComponent}. + * @param {CameraComponent} camera - A {@link CameraComponent}. */ removeCamera(camera) { if (this.camerasSet.has(camera.camera)) { @@ -889,10 +891,10 @@ class Layer { } /** - * @param {import('./mesh-instance.js').MeshInstance[]} drawCalls - Array of mesh instances. + * @param {MeshInstance[]} drawCalls - Array of mesh instances. * @param {number} drawCallsCount - Number of mesh instances. - * @param {import('../core/math/vec3.js').Vec3} camPos - Camera position. - * @param {import('../core/math/vec3.js').Vec3} camFwd - Camera forward vector. + * @param {Vec3} camPos - Camera position. + * @param {Vec3} camFwd - Camera forward vector. * @private */ _calculateSortDistances(drawCalls, drawCallsCount, camPos, camFwd) { @@ -914,7 +916,7 @@ class Layer { /** * Get access to culled mesh instances for the provided camera. * - * @param {import('./camera.js').Camera} camera - The camera. + * @param {Camera} camera - The camera. * @returns {CulledInstances} The culled mesh instances. * @ignore */ @@ -928,8 +930,7 @@ class Layer { } /** - * @param {import('./camera.js').Camera} camera - The camera to sort the visible mesh instances - * for. + * @param {Camera} camera - The camera to sort the visible mesh instances for. * @param {boolean} transparent - True if transparent sorting should be used. * @ignore */ diff --git a/src/scene/light.js b/src/scene/light.js index adf636ffca0..3b00bd0d167 100644 --- a/src/scene/light.js +++ b/src/scene/light.js @@ -4,7 +4,6 @@ import { Mat4 } from '../core/math/mat4.js'; import { Vec2 } from '../core/math/vec2.js'; import { Vec3 } from '../core/math/vec3.js'; import { Vec4 } from '../core/math/vec4.js'; - import { BLUR_GAUSSIAN, LIGHTTYPE_DIRECTIONAL, LIGHTTYPE_OMNI, LIGHTTYPE_SPOT, @@ -16,6 +15,11 @@ import { import { ShadowRenderer } from './renderer/shadow-renderer.js'; import { DepthState } from '../platform/graphics/depth-state.js'; +/** + * @import { BindGroup } from '../platform/graphics/bind-group.js' + * @import { Layer } from './layer.js' + */ + const tmpVec = new Vec3(); const tmpBiases = { bias: 0, @@ -83,7 +87,7 @@ class LightRenderData { this.visibleCasters = []; // an array of view bind groups, single entry is used for shadows - /** @type {import('../platform/graphics/bind-group.js').BindGroup[]} */ + /** @type {BindGroup[]} */ this.viewBindGroups = []; } @@ -121,7 +125,7 @@ class Light { /** * The Layers the light is on. * - * @type {Set} + * @type {Set} */ layers = new Set(); diff --git a/src/scene/lighting/world-clusters-debug.js b/src/scene/lighting/world-clusters-debug.js index 1ea3aea8af9..db3a431ad9c 100644 --- a/src/scene/lighting/world-clusters-debug.js +++ b/src/scene/lighting/world-clusters-debug.js @@ -170,7 +170,6 @@ class WorldClustersDebug { material.useLighting = false; material.emissive = new Color(1, 1, 1); material.emissiveVertexColor = true; - material.emissiveTint = false; material.blendType = BLEND_ADDITIVEALPHA; material.depthWrite = false; material.update(); diff --git a/src/scene/lighting/world-clusters.js b/src/scene/lighting/world-clusters.js index 70447cd22d8..177f5ddd7b7 100644 --- a/src/scene/lighting/world-clusters.js +++ b/src/scene/lighting/world-clusters.js @@ -6,6 +6,10 @@ import { LIGHTTYPE_DIRECTIONAL, LIGHTTYPE_SPOT, MASK_AFFECT_DYNAMIC, MASK_AFFECT import { LightsBuffer } from './lights-buffer.js'; import { Debug } from '../../core/debug.js'; +/** + * @import { Texture } from '../../platform/graphics/texture.js' + */ + const tempVec3 = new Vec3(); const tempMin3 = new Vec3(); const tempMax3 = new Vec3(); @@ -29,7 +33,7 @@ class ClusterLight { // Main class implementing clustered lighting. Internally it organizes the omni / spot lights placement in world space 3d cell structure, // and also uses LightsBuffer class to store light properties in textures class WorldClusters { - /** @type {import('../../platform/graphics/texture.js').Texture} */ + /** @type {Texture} */ clusterTexture; constructor(device) { diff --git a/src/scene/materials/basic-material.js b/src/scene/materials/basic-material.js index 52bc34494fe..5e3befb22fb 100644 --- a/src/scene/materials/basic-material.js +++ b/src/scene/materials/basic-material.js @@ -1,7 +1,5 @@ import { Color } from '../../core/math/color.js'; - import { ShaderProcessorOptions } from '../../platform/graphics/shader-processor-options.js'; - import { SHADERDEF_INSTANCING, SHADERDEF_MORPH_NORMAL, SHADERDEF_MORPH_POSITION, SHADERDEF_MORPH_TEXTURE_BASED_INT, @@ -11,6 +9,12 @@ import { getProgramLibrary } from '../shader-lib/get-program-library.js'; import { basic } from '../shader-lib/programs/basic.js'; import { Material } from './material.js'; +/** + * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js' + * @import { Scene } from '../scene.js' + * @import { Texture } from '../../platform/graphics/texture.js' + */ + /** * A BasicMaterial is for rendering unlit geometry, either using a constant color or a color map * modulated with a color. @@ -44,7 +48,7 @@ class BasicMaterial extends Material { * The color map of the material (default is null). If specified, the color map is * modulated by the color property. * - * @type {import('../../platform/graphics/texture.js').Texture|null} + * @type {Texture|null} */ colorMap = null; @@ -68,8 +72,8 @@ class BasicMaterial extends Material { } /** - * @param {import('../../platform/graphics/graphics-device.js').GraphicsDevice} device - The graphics device. - * @param {import('../scene.js').Scene} scene - The scene. + * @param {GraphicsDevice} device - The graphics device. + * @param {Scene} scene - The scene. * @ignore */ updateUniforms(device, scene) { diff --git a/src/scene/materials/default-material.js b/src/scene/materials/default-material.js index b2ad6fc9202..77221946f1a 100644 --- a/src/scene/materials/default-material.js +++ b/src/scene/materials/default-material.js @@ -1,17 +1,19 @@ import { Debug } from '../../core/debug.js'; - import { DeviceCache } from '../../platform/graphics/device-cache.js'; +/** + * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js' + * @import { StandardMaterial } from './standard-material.js' + */ + // device cache storing default material const defaultMaterialDeviceCache = new DeviceCache(); /** * Returns default material, which is a material used instead of null material. * - * @param {import('../../platform/graphics/graphics-device.js').GraphicsDevice} device - The - * graphics device used to own the material. - * @returns {import('./standard-material.js').StandardMaterial} The default instance of - * {@link StandardMaterial}. + * @param {GraphicsDevice} device - The graphics device used to own the material. + * @returns {StandardMaterial} The default instance of {@link StandardMaterial}. */ function getDefaultMaterial(device) { const material = defaultMaterialDeviceCache.get(device); @@ -22,10 +24,8 @@ function getDefaultMaterial(device) { /** * Assigns the default material to device cache * - * @param {import('../../platform/graphics/graphics-device.js').GraphicsDevice} device - The - * graphics device used to own the material. - * @param {import('./standard-material.js').StandardMaterial} material - The instance of - * {@link StandardMaterial}. + * @param {GraphicsDevice} device - The graphics device used to own the material. + * @param {StandardMaterial} material - The instance of {@link StandardMaterial}. */ function setDefaultMaterial(device, material) { Debug.assert(material); diff --git a/src/scene/materials/material.js b/src/scene/materials/material.js index 71e474de239..ba83c614108 100644 --- a/src/scene/materials/material.js +++ b/src/scene/materials/material.js @@ -1,5 +1,4 @@ import { Debug } from '../../core/debug.js'; - import { BLENDMODE_ZERO, BLENDMODE_ONE, BLENDMODE_SRC_COLOR, BLENDMODE_DST_COLOR, BLENDMODE_ONE_MINUS_DST_COLOR, BLENDMODE_SRC_ALPHA, @@ -11,7 +10,6 @@ import { import { BlendState } from '../../platform/graphics/blend-state.js'; import { DepthState } from '../../platform/graphics/depth-state.js'; import { ShaderProcessorOptions } from '../../platform/graphics/shader-processor-options.js'; - import { BLEND_ADDITIVE, BLEND_NORMAL, BLEND_NONE, BLEND_PREMULTIPLIED, BLEND_MULTIPLICATIVE, BLEND_ADDITIVEALPHA, BLEND_MULTIPLICATIVE2X, BLEND_SCREEN, @@ -20,6 +18,13 @@ import { import { processShader } from '../shader-lib/utils.js'; import { getDefaultMaterial } from './default-material.js'; +/** + * @import { MeshInstance } from '../mesh-instance.js' + * @import { Shader } from '../../platform/graphics/shader.js' + * @import { StencilParameters } from '../../platform/graphics/stencil-parameters.js' + * @import { Texture } from '../../platform/graphics/texture.js' + */ + // blend mode mapping to op, srcBlend and dstBlend const blendModes = []; blendModes[BLEND_SUBTRACTIVE] = { src: BLENDMODE_ONE, dst: BLENDMODE_ONE, op: BLENDEQUATION_REVERSE_SUBTRACT }; @@ -48,7 +53,7 @@ class Material { * user specifies the shader. Most material types generate multiple shader variants, and do not * set this. * - * @type {import('../../platform/graphics/shader.js').Shader} + * @type {Shader} * @private */ _shader = null; @@ -56,7 +61,7 @@ class Material { /** * The mesh instances referencing this material * - * @type {import('../mesh-instance.js').MeshInstance[]} + * @type {MeshInstance[]} * @private */ meshInstances = []; @@ -83,7 +88,7 @@ class Material { * The cache of shader variants generated for this material. The key represents the unique * variant, the value is the shader. * - * @type {Map} + * @type {Map} * @ignore */ variants = new Map(); @@ -137,14 +142,14 @@ class Material { /** * Stencil parameters for front faces (default is null). * - * @type {import('../../platform/graphics/stencil-parameters.js').StencilParameters|null} + * @type {StencilParameters|null} */ stencilFront = null; /** * Stencil parameters for back faces (default is null). * - * @type {import('../../platform/graphics/stencil-parameters.js').StencilParameters|null} + * @type {StencilParameters|null} */ stencilBack = null; @@ -281,7 +286,7 @@ class Material { /** * Sets the shader used by this material to render mesh instances. Defaults to `null`. * - * @type {import('../../platform/graphics/shader.js').Shader|null} + * @type {Shader|null} */ set shader(shader) { this._shader = shader; @@ -290,7 +295,7 @@ class Material { /** * Gets the shader used by this material to render mesh instances. * - * @type {import('../../platform/graphics/shader.js').Shader|null} + * @type {Shader|null} */ get shader() { return this._shader; @@ -583,8 +588,7 @@ class Material { * Sets a shader parameter on a material. * * @param {string} name - The name of the parameter to set. - * @param {number|number[]|Float32Array|import('../../platform/graphics/texture.js').Texture} data - - * The value for the specified parameter. + * @param {number|number[]|Float32Array|Texture} data - The value for the specified parameter. */ setParameter(name, data) { @@ -667,8 +671,7 @@ class Material { /** * Registers mesh instance as referencing the material. * - * @param {import('../mesh-instance.js').MeshInstance} meshInstance - The mesh instance to - * register. + * @param {MeshInstance} meshInstance - The mesh instance to register. * @ignore */ addMeshInstanceRef(meshInstance) { @@ -678,8 +681,7 @@ class Material { /** * De-registers mesh instance as referencing the material. * - * @param {import('../mesh-instance.js').MeshInstance} meshInstance - The mesh instance to - * de-register. + * @param {MeshInstance} meshInstance - The mesh instance to de-register. * @ignore */ removeMeshInstanceRef(meshInstance) { diff --git a/src/scene/materials/standard-material-options-builder.js b/src/scene/materials/standard-material-options-builder.js index e2c96a0cd25..e27fca51002 100644 --- a/src/scene/materials/standard-material-options-builder.js +++ b/src/scene/materials/standard-material-options-builder.js @@ -207,9 +207,6 @@ class StandardMaterialOptionsBuilder { const specularityFactorTint = useSpecular && stdMat.useMetalnessSpecularColor && (stdMat.specularityFactorTint || (stdMat.specularityFactor < 1 && !stdMat.specularityFactorMap)); - const emissiveTintColor = !stdMat.emissiveMap || (notWhite(stdMat.emissive) && stdMat.emissiveTint); - const emissiveTintIntensity = (stdMat.emissiveIntensity !== 1); - const isPackedNormalMap = stdMat.normalMap ? (stdMat.normalMap.format === PIXELFORMAT_DXT5 || stdMat.normalMap.type === TEXTURETYPE_SWIZZLEGGGR) : false; options.opacityTint = (stdMat.blendType !== BLEND_NONE || stdMat.alphaTest > 0 || stdMat.opacityDither !== DITHER_NONE) ? 1 : 0; @@ -218,7 +215,6 @@ class StandardMaterialOptionsBuilder { options.specularityFactorTint = specularityFactorTint ? 1 : 0; options.metalnessTint = (stdMat.useMetalness && stdMat.metalness < 1) ? 1 : 0; options.glossTint = 1; - options.emissiveTint = (emissiveTintColor ? 2 : 0) + (emissiveTintIntensity ? 1 : 0); options.diffuseEncoding = stdMat.diffuseMap?.encoding; options.diffuseDetailEncoding = stdMat.diffuseDetailMap?.encoding; options.emissiveEncoding = stdMat.emissiveMap?.encoding; diff --git a/src/scene/materials/standard-material-options.js b/src/scene/materials/standard-material-options.js index c9d80f771d3..906e5412a75 100644 --- a/src/scene/materials/standard-material-options.js +++ b/src/scene/materials/standard-material-options.js @@ -43,13 +43,6 @@ class StandardMaterialOptions { */ glossTint = false; - /** - * Defines if {@link StandardMaterial#emissive} constant should affect emissive color. - * - * @type {boolean} - */ - emissiveTint = false; - /** * Defines if {@link StandardMaterial#opacity} constant should affect opacity value. * diff --git a/src/scene/materials/standard-material-parameters.js b/src/scene/materials/standard-material-parameters.js index 88444222057..3b6c4f0bc82 100644 --- a/src/scene/materials/standard-material-parameters.js +++ b/src/scene/materials/standard-material-parameters.js @@ -74,7 +74,6 @@ const standardMaterialParameterTypes = { fresnelModel: 'number', emissive: 'rgb', - emissiveTint: 'boolean', ..._textureParameter('emissive'), emissiveIntensity: 'number', diff --git a/src/scene/materials/standard-material.js b/src/scene/materials/standard-material.js index 6d53c97d64b..72ccc4032a2 100644 --- a/src/scene/materials/standard-material.js +++ b/src/scene/materials/standard-material.js @@ -2,9 +2,7 @@ import { Debug } from '../../core/debug.js'; import { Color } from '../../core/math/color.js'; import { math } from '../../core/math/math.js'; import { Vec2 } from '../../core/math/vec2.js'; - import { ShaderProcessorOptions } from '../../platform/graphics/shader-processor-options.js'; - import { CUBEPROJ_BOX, CUBEPROJ_NONE, DETAILMODE_MUL, @@ -21,6 +19,13 @@ import { _matTex2D, standard } from '../shader-lib/programs/standard.js'; import { Material } from './material.js'; import { StandardMaterialOptionsBuilder } from './standard-material-options-builder.js'; import { standardMaterialCubemapParameters, standardMaterialTextureParameters } from './standard-material-parameters.js'; +import { DebugGraphics } from '../../platform/graphics/debug-graphics.js'; + +/** + * @import { BoundingBox } from '../../core/shape/bounding-box.js' + * @import { StandardMaterialOptions } from './standard-material-options.js' + * @import { Texture } from '../../platform/graphics/texture.js' + */ // properties that get created on a standard material const _props = {}; @@ -37,11 +42,11 @@ const _tempColor = new Color(); * Callback used by {@link StandardMaterial#onUpdateShader}. * * @callback UpdateShaderCallback - * @param {import('./standard-material-options.js').StandardMaterialOptions} options - An object with shader generator settings (based on current + * @param {StandardMaterialOptions} options - An object with shader generator settings (based on current * material and scene properties), that you can change and then return. Properties of the object passed * into this function are documented in {@link StandardMaterial}. Also contains a member named litOptions * which holds some of the options only used by the lit shader backend {@link LitShaderOptions}. - * @returns {import('./standard-material-options.js').StandardMaterialOptions} Returned settings will be used by the shader. + * @returns {StandardMaterialOptions} Returned settings will be used by the shader. */ /** @@ -54,8 +59,8 @@ const _tempColor = new Color(); * (RGB), where each component is between 0 and 1. * @property {Color} diffuse The diffuse color of the material. This color value is 3-component * (RGB), where each component is between 0 and 1. Defines basic surface color (aka albedo). - * @property {import('../../platform/graphics/texture.js').Texture|null} diffuseMap The main - * (primary) diffuse map of the material (default is null). + * @property {Texture|null} diffuseMap The main (primary) diffuse map of the material (default is + * null). * @property {number} diffuseMapUv Main (primary) diffuse map UV channel. * @property {Vec2} diffuseMapTiling Controls the 2D tiling of the main (primary) diffuse map. * @property {Vec2} diffuseMapOffset Controls the 2D offset of the main (primary) diffuse map. Each @@ -67,9 +72,8 @@ const _tempColor = new Color(); * @property {boolean} diffuseVertexColor Multiply diffuse by the mesh vertex colors. * @property {string} diffuseVertexColorChannel Vertex color channels to use for diffuse. Can be * "r", "g", "b", "a", "rgb" or any swizzled combination. - * @property {import('../../platform/graphics/texture.js').Texture|null} diffuseDetailMap The - * detail (secondary) diffuse map of the material (default is null). Will only be used if main - * (primary) diffuse map is non-null. + * @property {Texture|null} diffuseDetailMap The detail (secondary) diffuse map of the material + * (default is null). Will only be used if main (primary) diffuse map is non-null. * @property {number} diffuseDetailMapUv Detail (secondary) diffuse map UV channel. * @property {Vec2} diffuseDetailMapTiling Controls the 2D tiling of the detail (secondary) diffuse * map. @@ -97,8 +101,7 @@ const _tempColor = new Color(); * Affects specular intensity and tint. * @property {boolean} specularTint Multiply specular map and/or specular vertex color by the * constant specular value. - * @property {import('../../platform/graphics/texture.js').Texture|null} specularMap The specular - * map of the material (default is null). + * @property {Texture|null} specularMap The specular map of the material (default is null). * @property {number} specularMapUv Specular map UV channel. * @property {Vec2} specularMapTiling Controls the 2D tiling of the specular map. * @property {Vec2} specularMapOffset Controls the 2D offset of the specular map. Each component is @@ -109,12 +112,12 @@ const _tempColor = new Color(); * @property {boolean} specularVertexColor Use mesh vertex colors for specular. If specularMap or * are specularTint are set, they'll be multiplied by vertex colors. * @property {string} specularVertexColorChannel Vertex color channels to use for specular. Can be + * "r", "g", "b", "a", "rgb" or any swizzled combination. * @property {boolean} specularityFactorTint Multiply specularity factor map and/or specular vertex color by the * constant specular value. - * "r", "g", "b", "a", "rgb" or any swizzled combination. * @property {number} specularityFactor The factor of specular intensity, used to weight the fresnel and specularity. Default is 1.0. - * @property {import('../../platform/graphics/texture.js').Texture|null} specularityFactorMap The - * factor of specularity as a texture (default is null). + * @property {Texture|null} specularityFactorMap The factor of specularity as a texture (default is + * null). * @property {number} specularityFactorMapUv Specularity factor map UV channel. * @property {Vec2} specularityFactorMapTiling Controls the 2D tiling of the specularity factor map. * @property {Vec2} specularityFactorMapOffset Controls the 2D offset of the specularity factor map. Each component is @@ -138,9 +141,8 @@ const _tempColor = new Color(); * * @property {number} clearCoat Defines intensity of clearcoat layer from 0 to 1. Clearcoat layer * is disabled when clearCoat == 0. Default value is 0 (disabled). - * @property {import('../../platform/graphics/texture.js').Texture|null} clearCoatMap Monochrome - * clearcoat intensity map (default is null). If specified, will be multiplied by normalized - * 'clearCoat' value and/or vertex colors. + * @property {Texture|null} clearCoatMap Monochrome clearcoat intensity map (default is null). If + * specified, will be multiplied by normalized 'clearCoat' value and/or vertex colors. * @property {number} clearCoatMapUv Clearcoat intensity map UV channel. * @property {Vec2} clearCoatMapTiling Controls the 2D tiling of the clearcoat intensity map. * @property {Vec2} clearCoatMapOffset Controls the 2D offset of the clearcoat intensity map. Each @@ -157,9 +159,9 @@ const _tempColor = new Color(); * from 0 (rough) to 1 (mirror). * @property {boolean} clearCoatGlossInvert Invert the clearcoat gloss component (default is false). * Enabling this flag results in material treating the clear coat gloss members as roughness. - * @property {import('../../platform/graphics/texture.js').Texture|null} clearCoatGlossMap Monochrome - * clearcoat glossiness map (default is null). If specified, will be multiplied by normalized - * 'clearCoatGloss' value and/or vertex colors. + * @property {Texture|null} clearCoatGlossMap Monochrome clearcoat glossiness map (default is + * null). If specified, will be multiplied by normalized 'clearCoatGloss' value and/or vertex + * colors. * @property {number} clearCoatGlossMapUv Clearcoat gloss map UV channel. * @property {Vec2} clearCoatGlossMapTiling Controls the 2D tiling of the clearcoat gloss map. * @property {Vec2} clearCoatGlossMapOffset Controls the 2D offset of the clearcoat gloss map. @@ -172,9 +174,8 @@ const _tempColor = new Color(); * If clearCoatGlossMap is set, it'll be multiplied by vertex colors. * @property {string} clearCoatGlossVertexColorChannel Vertex color channel to use for clearcoat * glossiness. Can be "r", "g", "b" or "a". - * @property {import('../../platform/graphics/texture.js').Texture|null} clearCoatNormalMap The - * clearcoat normal map of the material (default is null). The texture must contains normalized, - * tangent space normals. + * @property {Texture|null} clearCoatNormalMap The clearcoat normal map of the material (default is + * null). The texture must contains normalized, tangent space normals. * @property {number} clearCoatNormalMapUv Clearcoat normal map UV channel. * @property {Vec2} clearCoatNormalMapTiling Controls the 2D tiling of the main clearcoat normal * map. @@ -186,8 +187,8 @@ const _tempColor = new Color(); * the assigned main clearcoat normal map. It should be normally between 0 (no bump mapping) and 1 * (full bump mapping), but can be set to e.g. 2 to give even more pronounced bump effect. * @property {boolean} useIridescence Enable thin-film iridescence. - * @property {import('../../platform/graphics/texture.js').Texture|null} iridescenceMap The - * per-pixel iridescence intensity. Only used when useIridescence is enabled. + * @property {Texture|null} iridescenceMap The per-pixel iridescence intensity. Only used when + * useIridescence is enabled. * @property {number} iridescenceMapUv Iridescence map UV channel. * @property {Vec2} iridescenceMapTiling Controls the 2D tiling of the iridescence map. * @property {Vec2} iridescenceMapOffset Controls the 2D offset of the iridescence map. Each component is @@ -196,9 +197,9 @@ const _tempColor = new Color(); * map. * @property {string} iridescenceMapChannel Color channels of the iridescence map to use. Can be "r", * "g", "b" or "a". - * @property {import('../../platform/graphics/texture.js').Texture|null} iridescenceThicknessMap The - * per-pixel iridescence thickness. Defines a gradient weight between iridescenceThicknessMin and - * iridescenceThicknessMax. Only used when useIridescence is enabled. + * @property {Texture|null} iridescenceThicknessMap The per-pixel iridescence thickness. Defines a + * gradient weight between iridescenceThicknessMin and iridescenceThicknessMax. Only used when + * useIridescence is enabled. * @property {number} iridescenceThicknessMapUv Iridescence thickness map UV channel. * @property {Vec2} iridescenceThicknessMapTiling Controls the 2D tiling of the iridescence * thickness map. @@ -225,8 +226,7 @@ const _tempColor = new Color(); * at direct angles. * @property {number} metalness Defines how much the surface is metallic. From 0 (dielectric) to 1 * (metal). - * @property {import('../../platform/graphics/texture.js').Texture|null} metalnessMap Monochrome - * metalness map (default is null). + * @property {Texture|null} metalnessMap Monochrome metalness map (default is null). * @property {number} metalnessMapUv Metalness map UV channel. * @property {Vec2} metalnessMapTiling Controls the 2D tiling of the metalness map. * @property {Vec2} metalnessMapOffset Controls the 2D offset of the metalness map. Each component @@ -240,9 +240,8 @@ const _tempColor = new Color(); * @property {string} metalnessVertexColorChannel Vertex color channel to use for metalness. Can be * "r", "g", "b" or "a". * @property {number} gloss Defines the glossiness of the material from 0 (rough) to 1 (shiny). - * @property {import('../../platform/graphics/texture.js').Texture|null} glossMap Gloss map - * (default is null). If specified, will be multiplied by normalized gloss value and/or vertex - * colors. + * @property {Texture|null} glossMap Gloss map (default is null). If specified, will be multiplied + * by normalized gloss value and/or vertex colors. * @property {boolean} glossInvert Invert the gloss component (default is false). Enabling this * flag results in material treating the gloss members as roughness. * @property {number} glossMapUv Gloss map UV channel. @@ -258,8 +257,7 @@ const _tempColor = new Color(); * "r", "g", "b" or "a". * @property {number} refraction Defines the visibility of refraction. Material can refract the * same cube map as used for reflections. - * @property {import('../../platform/graphics/texture.js').Texture|null} refractionMap The map of - * the refraction visibility. + * @property {Texture|null} refractionMap The map of the refraction visibility. * @property {number} refractionMapUv Refraction map UV channel. * @property {Vec2} refractionMapTiling Controls the 2D tiling of the refraction map. * @property {Vec2} refractionMapOffset Controls the 2D offset of the refraction map. Each component @@ -283,8 +281,8 @@ const _tempColor = new Color(); * instead of pre-computed cube maps for refractions. * @property {number} thickness The thickness of the medium, only used when useDynamicRefraction * is enabled. The unit is in base units, and scales with the size of the object. - * @property {import('../../platform/graphics/texture.js').Texture|null} thicknessMap The - * per-pixel thickness of the medium, only used when useDynamicRefraction is enabled. + * @property {Texture|null} thicknessMap The per-pixel thickness of the medium, only used when + * useDynamicRefraction is enabled. * @property {number} thicknessMapUv Thickness map UV channel. * @property {Vec2} thicknessMapTiling Controls the 2D tiling of the thickness map. * @property {Vec2} thicknessMapOffset Controls the 2D offset of the thickness map. Each component is @@ -301,10 +299,10 @@ const _tempColor = new Color(); * within the medium. Only used when useDynamicRefraction is enabled. * @property {Color} emissive The emissive color of the material. This color value is 3-component * (RGB), where each component is between 0 and 1. - * @property {boolean} emissiveTint Multiply emissive map and/or emissive vertex color by the - * constant emissive value. - * @property {import('../../platform/graphics/texture.js').Texture|null} emissiveMap The emissive - * map of the material (default is null). Can be HDR. + * @property {Texture|null} emissiveMap The emissive map of the material (default is null). Can be + * HDR. When the emissive map is applied, the emissive color is multiplied by the texel color in the + * map. Since the emissive color is black by default, the emissive map won't be visible unless the + * emissive color is changed. * @property {number} emissiveIntensity Emissive color multiplier. * @property {number} emissiveMapUv Emissive map UV channel. * @property {Vec2} emissiveMapTiling Controls the 2D tiling of the emissive map. @@ -315,7 +313,7 @@ const _tempColor = new Color(); * @property {string} emissiveMapChannel Color channels of the emissive map to use. Can be "r", * "g", "b", "a", "rgb" or any swizzled combination. * @property {boolean} emissiveVertexColor Use mesh vertex colors for emission. If emissiveMap or - * emissiveTint are set, they'll be multiplied by vertex colors. + * emissive are set, they'll be multiplied by vertex colors. * @property {string} emissiveVertexColorChannel Vertex color channels to use for emission. Can be * "r", "g", "b", "a", "rgb" or any swizzled combination. * @property {boolean} useSheen Toggle sheen specular effect on/off. @@ -323,8 +321,8 @@ const _tempColor = new Color(); * This color value is 3-component (RGB), where each component is between 0 and 1. * @property {boolean} sheenTint Multiply sheen map and/or sheen vertex color by the constant * sheen value. - * @property {import('../../platform/graphics/texture.js').Texture|null} sheenMap The sheen - * microstructure color map of the material (default is null). + * @property {Texture|null} sheenMap The sheen microstructure color map of the material (default is + * null). * @property {number} sheenMapUv Sheen map UV channel. * @property {Vec2} sheenMapTiling Controls the 2D tiling of the sheen map. * @property {Vec2} sheenMapOffset Controls the 2D offset of the sheen map. Each component is @@ -341,8 +339,8 @@ const _tempColor = new Color(); * Enabling this flag results in material treating the sheen gloss members as roughness. * @property {boolean} sheenGlossTint Multiply sheen glossiness map and/or sheen glossiness vertex * value by the scalar sheen glossiness value. - * @property {import('../../platform/graphics/texture.js').Texture|null} sheenGlossMap The sheen - * glossiness microstructure color map of the material (default is null). + * @property {Texture|null} sheenGlossMap The sheen glossiness microstructure color map of the + * material (default is null). * @property {number} sheenGlossMapUv Sheen map UV channel. * @property {Vec2} sheenGlossMapTiling Controls the 2D tiling of the sheen glossiness map. * @property {Vec2} sheenGlossMapOffset Controls the 2D offset of the sheen glossiness map. @@ -361,8 +359,7 @@ const _tempColor = new Color(); * {@link BLEND_ADDITIVE} or any other mode. Also note that for most semi-transparent objects you * want {@link Material#depthWrite} to be false, otherwise they can fully occlude objects behind * them. - * @property {import('../../platform/graphics/texture.js').Texture|null} opacityMap The opacity map - * of the material (default is null). + * @property {Texture|null} opacityMap The opacity map of the material (default is null). * @property {number} opacityMapUv Opacity map UV channel. * @property {string} opacityMapChannel Color channel of the opacity map to use. Can be "r", "g", * "b" or "a". @@ -397,9 +394,8 @@ const _tempColor = new Color(); * Defaults to {@link DITHER_NONE}. * @property {number} alphaFade Used to fade out materials when * {@link StandardMaterial#opacityFadesSpecular} is set to false. - * @property {import('../../platform/graphics/texture.js').Texture|null} normalMap The main - * (primary) normal map of the material (default is null). The texture must contains normalized, - * tangent space normals. + * @property {Texture|null} normalMap The main (primary) normal map of the material (default is + * null). The texture must contains normalized, tangent space normals. * @property {number} normalMapUv Main (primary) normal map UV channel. * @property {Vec2} normalMapTiling Controls the 2D tiling of the main (primary) normal map. * @property {Vec2} normalMapOffset Controls the 2D offset of the main (primary) normal map. Each @@ -409,9 +405,8 @@ const _tempColor = new Color(); * @property {number} bumpiness The bumpiness of the material. This value scales the assigned main * (primary) normal map. It should be normally between 0 (no bump mapping) and 1 (full bump * mapping), but can be set to e.g. 2 to give even more pronounced bump effect. - * @property {import('../../platform/graphics/texture.js').Texture|null} normalDetailMap The detail - * (secondary) normal map of the material (default is null). Will only be used if main (primary) - * normal map is non-null. + * @property {Texture|null} normalDetailMap The detail (secondary) normal map of the material + * (default is null). Will only be used if main (primary) normal map is non-null. * @property {number} normalDetailMapUv Detail (secondary) normal map UV channel. * @property {Vec2} normalDetailMapTiling Controls the 2D tiling of the detail (secondary) normal * map. @@ -422,10 +417,10 @@ const _tempColor = new Color(); * @property {number} normalDetailMapBumpiness The bumpiness of the material. This value scales the * assigned detail (secondary) normal map. It should be normally between 0 (no bump mapping) and 1 * (full bump mapping), but can be set to e.g. 2 to give even more pronounced bump effect. - * @property {import('../../platform/graphics/texture.js').Texture|null} heightMap The height map - * of the material (default is null). Used for a view-dependent parallax effect. The texture must - * represent the height of the surface where darker pixels are lower and lighter pixels are higher. - * It is recommended to use it together with a normal map. + * @property {Texture|null} heightMap The height map of the material (default is null). Used for a + * view-dependent parallax effect. The texture must represent the height of the surface where + * darker pixels are lower and lighter pixels are higher. It is recommended to use it together with + * a normal map. * @property {number} heightMapUv Height map UV channel. * @property {string} heightMapChannel Color channel of the height map to use. Can be "r", "g", "b" * or "a". @@ -435,26 +430,22 @@ const _tempColor = new Color(); * @property {number} heightMapRotation Controls the 2D rotation (in degrees) of the height map. * @property {number} heightMapFactor Height map multiplier. Affects the strength of the parallax * effect. - * @property {import('../../platform/graphics/texture.js').Texture|null} envAtlas The prefiltered - * environment lighting atlas (default is null). This setting overrides cubeMap and sphereMap and - * will replace the scene lighting environment. - * @property {import('../../platform/graphics/texture.js').Texture|null} cubeMap The cubic - * environment map of the material (default is null). This setting overrides sphereMap and will - * replace the scene lighting environment. - * @property {import('../../platform/graphics/texture.js').Texture|null} sphereMap The spherical - * environment map of the material (default is null). This will replace the scene lighting - * environment. + * @property {Texture|null} envAtlas The prefiltered environment lighting atlas (default is null). + * This setting overrides cubeMap and sphereMap and will replace the scene lighting environment. + * @property {Texture|null} cubeMap The cubic environment map of the material (default is null). + * This setting overrides sphereMap and will replace the scene lighting environment. + * @property {Texture|null} sphereMap The spherical environment map of the material (default is + * null). This will replace the scene lighting environment. * @property {number} cubeMapProjection The type of projection applied to the cubeMap property: * - {@link CUBEPROJ_NONE}: The cube map is treated as if it is infinitely far away. * - {@link CUBEPROJ_BOX}: Box-projection based on a world space axis-aligned bounding box. * Defaults to {@link CUBEPROJ_NONE}. - * @property {import('../../core/shape/bounding-box.js').BoundingBox} cubeMapProjectionBox The - * world space axis-aligned bounding box defining the box-projection used for the cubeMap property. - * Only used when cubeMapProjection is set to {@link CUBEPROJ_BOX}. + * @property {BoundingBox} cubeMapProjectionBox The world space axis-aligned bounding box + * defining the box-projection used for the cubeMap property. Only used when cubeMapProjection is + * set to {@link CUBEPROJ_BOX}. * @property {number} reflectivity Environment map intensity. - * @property {import('../../platform/graphics/texture.js').Texture|null} lightMap A custom lightmap - * of the material (default is null). Lightmaps are textures that contain pre-rendered lighting. - * Can be HDR. + * @property {Texture|null} lightMap A custom lightmap of the material (default is null). Lightmaps + * are textures that contain pre-rendered lighting. Can be HDR. * @property {number} lightMapUv Lightmap UV channel * @property {string} lightMapChannel Color channels of the lightmap to use. Can be "r", "g", "b", * "a", "rgb" or any swizzled combination. @@ -467,8 +458,8 @@ const _tempColor = new Color(); * @property {string} lightVertexColorChannel Vertex color channels to use for baked lighting. Can * be "r", "g", "b", "a", "rgb" or any swizzled combination. * @property {boolean} ambientTint Enables scene ambient multiplication by material ambient color. - * @property {import('../../platform/graphics/texture.js').Texture|null} aoMap The main (primary) baked ambient - * occlusion (AO) map (default is null). Modulates ambient color. + * @property {Texture|null} aoMap The main (primary) baked ambient occlusion (AO) map (default is + * null). Modulates ambient color. * @property {number} aoMapUv Main (primary) AO map UV channel * @property {string} aoMapChannel Color channel of the main (primary) AO map to use. Can be "r", "g", "b" or "a". * @property {Vec2} aoMapTiling Controls the 2D tiling of the main (primary) AO map. @@ -479,18 +470,16 @@ const _tempColor = new Color(); * multiplied by vertex colors. * @property {string} aoVertexColorChannel Vertex color channels to use for AO. Can be "r", "g", * "b" or "a". - * @property {import('../../platform/graphics/texture.js').Texture|null} aoDetailMap The - * detail (secondary) baked ambient occlusion (AO) map of the material (default is null). Will only be used if main - * (primary) ao map is non-null. + * @property {Texture|null} aoDetailMap The detail (secondary) baked ambient occlusion (AO) map of + * the material (default is null). Will only be used if main (primary) ao map is non-null. * @property {number} aoDetailMapUv Detail (secondary) AO map UV channel. - * @property {Vec2} aoDetailMapTiling Controls the 2D tiling of the detail (secondary) AO - * map. - * @property {Vec2} aoDetailMapOffset Controls the 2D offset of the detail (secondary) AO - * map. Each component is between 0 and 1. + * @property {Vec2} aoDetailMapTiling Controls the 2D tiling of the detail (secondary) AO map. + * @property {Vec2} aoDetailMapOffset Controls the 2D offset of the detail (secondary) AO map. Each + * component is between 0 and 1. * @property {number} aoDetailMapRotation Controls the 2D rotation (in degrees) of the detail * (secondary) AO map. - * @property {string} aoDetailMapChannel Color channels of the detail (secondary) AO map - * to use. Can be "r", "g", "b" or "a" (default is "g"). + * @property {string} aoDetailMapChannel Color channels of the detail (secondary) AO map to use. + * Can be "r", "g", "b" or "a" (default is "g"). * @property {string} aoDetailMode Determines how the main (primary) and detail (secondary) * AO maps are blended together. Can be: * @@ -661,8 +650,8 @@ class StandardMaterial extends Material { * Sets a vertex shader attribute on a material. * * @param {string} name - The name of the parameter to set. - * @param {string} semantic - Semantic to map the vertex data. Must match with the semantic set on vertex stream - * of the mesh. + * @param {string} semantic - Semantic to map the vertex data. Must match with the semantic set + * on vertex stream of the mesh. * @example * mesh.setVertexStream(pc.SEMANTIC_ATTR15, offset, 3); * material.setAttribute('offset', pc.SEMANTIC_ATTR15); @@ -767,12 +756,14 @@ class StandardMaterial extends Material { this._setParameter('material_gloss', this.gloss); - if (!this.emissiveMap || this.emissiveTint) { - this._setParameter('material_emissive', getUniform('emissive')); - } - if (this.emissiveIntensity !== 1) { - this._setParameter('material_emissiveIntensity', this.emissiveIntensity); - } + Debug.call(() => { + if (this.emissiveMap && this.emissive.r === 0 && this.emissive.g === 0 && this.emissive.b === 0) { + Debug.warnOnce(`Emissive map is set but emissive color is black, making the map invisible. Set emissive color to white to make the map visible. Rendering [${DebugGraphics.toString()}]`, this); + } + }); + + this._setParameter('material_emissive', getUniform('emissive')); + this._setParameter('material_emissiveIntensity', this.emissiveIntensity); if (this.refraction > 0) { this._setParameter('material_refraction', this.refraction); @@ -1197,7 +1188,6 @@ function _defineMaterialProps() { _defineFlag('sheenTint', false); _defineFlag('specularTint', false); _defineFlag('specularityFactorTint', false); - _defineFlag('emissiveTint', false); _defineFlag('fastTbn', false); _defineFlag('useMetalness', false); _defineFlag('useMetalnessSpecularColor', false); diff --git a/src/scene/mesh-instance.js b/src/scene/mesh-instance.js index 8e3fad953dd..f8618f32539 100644 --- a/src/scene/mesh-instance.js +++ b/src/scene/mesh-instance.js @@ -1,11 +1,8 @@ import { Debug, DebugHelper } from '../core/debug.js'; - import { BoundingBox } from '../core/shape/bounding-box.js'; import { BoundingSphere } from '../core/shape/bounding-sphere.js'; - import { BindGroup } from '../platform/graphics/bind-group.js'; import { UniformBuffer } from '../platform/graphics/uniform-buffer.js'; - import { BLEND_NONE, BLEND_NORMAL, LAYER_WORLD, @@ -17,7 +14,6 @@ import { SORTKEY_FORWARD, SHADERDEF_MORPH_TEXTURE_BASED_INT } from './constants.js'; - import { GraphNode } from './graph-node.js'; import { getDefaultMaterial } from './materials/default-material.js'; import { LightmapCache } from './graphics/lightmap-cache.js'; @@ -25,12 +21,32 @@ import { DebugGraphics } from '../platform/graphics/debug-graphics.js'; import { hash32Fnv1a } from '../core/hash.js'; import { array } from '../core/array-utils.js'; +/** + * @import { BindGroupFormat } from '../platform/graphics/bind-group-format.js' + * @import { Camera } from './camera.js' + * @import { GSplatInstance } from './gsplat/gsplat-instance.js' + * @import { GraphicsDevice } from '../platform/graphics/graphics-device.js' + * @import { Material } from './materials/material.js' + * @import { Mesh } from './mesh.js' + * @import { MorphInstance } from './morph-instance.js' + * @import { RenderingParams } from './renderer/rendering-params.js' + * @import { Scene } from './scene.js' + * @import { ScopeId } from '../platform/graphics/scope-id.js' + * @import { Shader } from '../platform/graphics/shader.js' + * @import { SkinInstance } from './skin-instance.js' + * @import { StencilParameters } from '../platform/graphics/stencil-parameters.js' + * @import { Texture } from '../platform/graphics/texture.js' + * @import { UniformBufferFormat } from '../platform/graphics/uniform-buffer-format.js' + * @import { Vec3 } from '../core/math/vec3.js' + * @import { VertexBuffer } from '../platform/graphics/vertex-buffer.js' + */ + let id = 0; const _tmpAabb = new BoundingBox(); const _tempBoneAabb = new BoundingBox(); const _tempSphere = new BoundingSphere(); -/** @type {Set} */ +/** @type {Set} */ const _meshSet = new Set(); // internal array used to evaluate the hash for the shader instance @@ -40,7 +56,7 @@ const lookupHashes = new Uint32Array(4); * Internal data structure used to store data used by hardware instancing. */ class InstancingData { - /** @type {import('../platform/graphics/vertex-buffer.js').VertexBuffer|null} */ + /** @type {VertexBuffer|null} */ vertexBuffer = null; /** @@ -58,7 +74,7 @@ class ShaderInstance { /** * A shader. * - * @type {import('../platform/graphics/shader.js').Shader|undefined} + * @type {Shader|undefined} */ shader; @@ -86,8 +102,7 @@ class ShaderInstance { /** * Returns the mesh bind group for the shader. * - * @param {import('../platform/graphics/graphics-device.js').GraphicsDevice} device - The - * graphics device. + * @param {GraphicsDevice} device - The graphics device. * @returns {BindGroup} - The mesh bind group. */ getBindGroup(device) { @@ -109,8 +124,7 @@ class ShaderInstance { /** * Returns the uniform buffer for the shader. * - * @param {import('../platform/graphics/graphics-device.js').GraphicsDevice} device - The - * graphics device. + * @param {GraphicsDevice} device - The graphics device. * @returns {UniformBuffer} - The uniform buffer. */ getUniformBuffer(device) { @@ -143,8 +157,8 @@ class ShaderInstance { * * @callback CalculateSortDistanceCallback * @param {MeshInstance} meshInstance - The mesh instance. - * @param {import('../core/math/vec3.js').Vec3} cameraPosition - The position of the camera. - * @param {import('../core/math/vec3.js').Vec3} cameraForward - The forward vector of the camera. + * @param {Vec3} cameraPosition - The position of the camera. + * @param {Vec3} cameraForward - The forward vector of the camera. */ /** @@ -214,7 +228,7 @@ class MeshInstance { flipFacesFactor = 1; /** - * @type {import('./gsplat/gsplat-instance.js').GSplatInstance|null} + * @type {GSplatInstance|null} * @ignore */ gsplatInstance = null; @@ -237,7 +251,7 @@ class MeshInstance { instancingData = null; /** - * @type {Record} + * @type {Record} * @ignore */ parameters = {}; @@ -253,7 +267,7 @@ class MeshInstance { /** * The stencil parameters for front faces or null if no stencil is enabled. * - * @type {import('../platform/graphics/stencil-parameters.js').StencilParameters|null} + * @type {StencilParameters|null} * @ignore */ stencilFront = null; @@ -261,7 +275,7 @@ class MeshInstance { /** * The stencil parameters for back faces or null if no stencil is enabled. * - * @type {import('../platform/graphics/stencil-parameters.js').StencilParameters|null} + * @type {StencilParameters|null} * @ignore */ stencilBack = null; @@ -302,19 +316,19 @@ class MeshInstance { _layer = LAYER_WORLD; /** - * @type {import('./materials/material.js').Material|null} + * @type {Material|null} * @private */ _material = null; /** - * @type {import('./skin-instance.js').SkinInstance|null} + * @type {SkinInstance|null} * @private */ _skinInstance = null; /** - * @type {import('./morph-instance.js').MorphInstance|null} + * @type {MorphInstance|null} * @private */ _morphInstance = null; @@ -352,9 +366,8 @@ class MeshInstance { /** * Create a new MeshInstance instance. * - * @param {import('./mesh.js').Mesh} mesh - The graphics mesh to instance. - * @param {import('./materials/material.js').Material} material - The material to use for this - * mesh instance. + * @param {Mesh} mesh - The graphics mesh to instance. + * @param {Material} material - The material to use for this mesh instance. * @param {GraphNode} [node] - The graph node defining the transform for this instance. This * parameter is optional when used with {@link RenderComponent} and will use the node the * component is attached to. @@ -427,7 +440,7 @@ class MeshInstance { /** * Sets the graphics mesh being instanced. * - * @type {import('./mesh.js').Mesh} + * @type {Mesh} */ set mesh(mesh) { @@ -448,7 +461,7 @@ class MeshInstance { /** * Gets the graphics mesh being instanced. * - * @type {import('./mesh.js').Mesh} + * @type {Mesh} */ get mesh() { return this._mesh; @@ -568,13 +581,10 @@ class MeshInstance { * * @param {number} shaderPass - The shader pass index. * @param {number} lightHash - The hash value of the lights that are affecting this mesh instance. - * @param {import('./scene.js').Scene} scene - The scene. - * @param {import('./renderer/rendering-params.js').RenderingParams} renderParams - The rendering - * parameters. - * @param {import('../platform/graphics/uniform-buffer-format.js').UniformBufferFormat} [viewUniformFormat] - The - * format of the view uniform buffer. - * @param {import('../platform/graphics/bind-group-format.js').BindGroupFormat} [viewBindGroupFormat] - The - * format of the view bind group. + * @param {Scene} scene - The scene. + * @param {RenderingParams} renderParams - The rendering parameters. + * @param {UniformBufferFormat} [viewUniformFormat] - The format of the view uniform buffer. + * @param {BindGroupFormat} [viewBindGroupFormat] - The format of the view bind group. * @param {any} [sortedLights] - Array of arrays of lights. * @returns {ShaderInstance} - the shader instance. * @ignore @@ -639,7 +649,7 @@ class MeshInstance { /** * Sets the material used by this mesh instance. * - * @type {import('./materials/material.js').Material} + * @type {Material} */ set material(material) { @@ -669,7 +679,7 @@ class MeshInstance { /** * Gets the material used by this mesh instance. * - * @type {import('./materials/material.js').Material} + * @type {Material} */ get material() { return this._material; @@ -733,7 +743,7 @@ class MeshInstance { * Sets the skin instance managing skinning of this mesh instance. Set to null if skinning is * not used. * - * @type {import('./skin-instance.js').SkinInstance|null} + * @type {SkinInstance|null} */ set skinInstance(val) { this._skinInstance = val; @@ -744,7 +754,7 @@ class MeshInstance { /** * Gets the skin instance managing skinning of this mesh instance. * - * @type {import('./skin-instance.js').SkinInstance|null} + * @type {SkinInstance|null} */ get skinInstance() { return this._skinInstance; @@ -754,7 +764,7 @@ class MeshInstance { * Sets the morph instance managing morphing of this mesh instance. Set to null if morphing is * not used. * - * @type {import('./morph-instance.js').MorphInstance|null} + * @type {MorphInstance|null} */ set morphInstance(val) { @@ -774,7 +784,7 @@ class MeshInstance { /** * Gets the morph instance managing morphing of this mesh instance. * - * @type {import('./morph-instance.js').MorphInstance|null} + * @type {MorphInstance|null} */ get morphInstance() { return this._morphInstance; @@ -903,7 +913,7 @@ class MeshInstance { * Test if meshInstance is visible by camera. It requires the frustum of the camera to be up to * date, which forward-renderer takes care of. This function should not be called elsewhere. * - * @param {import('./camera.js').Camera} camera - The camera to test visibility against. + * @param {Camera} camera - The camera to test visibility against. * @returns {boolean} - True if the mesh instance is visible by the camera, false otherwise. * @ignore */ @@ -947,9 +957,8 @@ class MeshInstance { /** * Sets up {@link MeshInstance} to be rendered using Hardware Instancing. * - * @param {import('../platform/graphics/vertex-buffer.js').VertexBuffer|null} vertexBuffer - - * Vertex buffer to hold per-instance vertex data (usually world matrices). Pass null to turn - * off hardware instancing. + * @param {VertexBuffer|null} vertexBuffer - Vertex buffer to hold per-instance vertex data + * (usually world matrices). Pass null to turn off hardware instancing. * @param {boolean} cull - Whether to perform frustum culling on this instance. If true, the whole * instance will be culled by the camera frustum. This often involves setting * {@link RenderComponent#customAabb} containing all instances. Defaults to false, which means @@ -1004,7 +1013,7 @@ class MeshInstance { * over parameter of the same name if set on Material this mesh instance uses for rendering. * * @param {string} name - The name of the parameter to set. - * @param {number|number[]|import('../platform/graphics/texture.js').Texture|Float32Array} data - The + * @param {number|number[]|Texture|Float32Array} data - The * value for the specified parameter. * @param {number} [passFlags] - Mask describing which passes the material should be included * in. @@ -1043,8 +1052,7 @@ class MeshInstance { * reference counting of lightmaps and releases them when no longer referenced. * * @param {string} name - The name of the parameter to set. - * @param {import('../platform/graphics/texture.js').Texture|null} texture - The lightmap - * texture to set. + * @param {Texture|null} texture - The lightmap texture to set. * @ignore */ setRealtimeLightmap(name, texture) { @@ -1082,8 +1090,7 @@ class MeshInstance { * Used to apply parameters from this mesh instance into scope of uniforms, called internally * by forward-renderer. * - * @param {import('../platform/graphics/graphics-device.js').GraphicsDevice} device - The - * graphics device. + * @param {GraphicsDevice} device - The graphics device. * @param {number} passFlag - The pass flag for the current render pass. * @ignore */ diff --git a/src/scene/mesh.js b/src/scene/mesh.js index 9fb0998cace..5699608eb00 100644 --- a/src/scene/mesh.js +++ b/src/scene/mesh.js @@ -2,7 +2,6 @@ import { Debug } from '../core/debug.js'; import { RefCountedObject } from '../core/ref-counted-object.js'; import { Vec3 } from '../core/math/vec3.js'; import { BoundingBox } from '../core/shape/bounding-box.js'; - import { BUFFER_DYNAMIC, BUFFER_STATIC, INDEXFORMAT_UINT16, INDEXFORMAT_UINT32, @@ -16,9 +15,15 @@ import { IndexBuffer } from '../platform/graphics/index-buffer.js'; import { VertexBuffer } from '../platform/graphics/vertex-buffer.js'; import { VertexFormat } from '../platform/graphics/vertex-format.js'; import { VertexIterator } from '../platform/graphics/vertex-iterator.js'; - import { RENDERSTYLE_SOLID, RENDERSTYLE_WIREFRAME, RENDERSTYLE_POINTS } from './constants.js'; +/** + * @import { Geometry } from './geometry/geometry.js' + * @import { GraphicsDevice } from '../platform/graphics/graphics-device.js' + * @import { Morph } from './morph.js' + * @import { Skin } from './skin.js' + */ + let id = 0; // Helper class used to store vertex / index data streams and related properties, when mesh is programmatically modified @@ -211,7 +216,7 @@ class Mesh extends RefCountedObject { /** * The skin data (if any) that drives skinned mesh animations for this mesh. * - * @type {import('./skin.js').Skin|null} + * @type {Skin|null} */ skin = null; @@ -245,7 +250,7 @@ class Mesh extends RefCountedObject { _geometryData = null; /** - * @type {import('./morph.js').Morph|null} + * @type {Morph|null} * @private */ _morph = null; @@ -269,8 +274,7 @@ class Mesh extends RefCountedObject { /** * Create a new Mesh instance. * - * @param {import('../platform/graphics/graphics-device.js').GraphicsDevice} graphicsDevice - - * The graphics device used to manage this mesh. + * @param {GraphicsDevice} graphicsDevice - The graphics device used to manage this mesh. * @param {object} [options] - Object for passing optional arguments. * @param {boolean} [options.storageVertex] - Defines if the vertex buffer can be used as * a storage buffer by a compute shader. Defaults to false. Only supported on WebGPU. @@ -289,10 +293,9 @@ class Mesh extends RefCountedObject { /** * Create a new Mesh instance from {@link Geometry} object. - * @param {import('../platform/graphics/graphics-device.js').GraphicsDevice} graphicsDevice - - * The graphics device used to manage this mesh. - * @param {import('./geometry/geometry.js').Geometry} geometry - The geometry object to create - * the mesh from. + * + * @param {GraphicsDevice} graphicsDevice - The graphics device used to manage this mesh. + * @param {Geometry} geometry - The geometry object to create the mesh from. * @param {object} [options] - An object that specifies optional inputs for the function as follows: * @param {boolean} [options.storageVertex] - Defines if the vertex buffer of the mesh can be used as * a storage buffer by a compute shader. Defaults to false. Only supported on WebGPU. @@ -350,7 +353,7 @@ class Mesh extends RefCountedObject { * Sets the morph data that drives morph target animations for this mesh. Set to null if * morphing is not used. * - * @type {import('./morph.js').Morph|null} + * @type {Morph|null} */ set morph(morph) { @@ -370,7 +373,7 @@ class Mesh extends RefCountedObject { /** * Gets the morph data that drives morph target animations for this mesh. * - * @type {import('./morph.js').Morph|null} + * @type {Morph|null} */ get morph() { return this._morph; @@ -614,8 +617,7 @@ class Mesh extends RefCountedObject { * * @param {string} semantic - The meaning of the vertex element. For supported semantics, see * SEMANTIC_* in {@link VertexFormat}. - * @param {number[]|ArrayBufferView} data - Vertex - * data for the specified semantic. + * @param {number[]|ArrayBufferView} data - Vertex data for the specified semantic. * @param {number} componentCount - The number of values that form a single Vertex element. For * example when setting a 3D position represented by 3 numbers per vertex, number 3 should be * specified. @@ -650,9 +652,9 @@ class Mesh extends RefCountedObject { * * @param {string} semantic - The semantic of the vertex element to get. For supported * semantics, see SEMANTIC_* in {@link VertexFormat}. - * @param {number[]|ArrayBufferView} data - An - * array to populate with the vertex data. When typed array is supplied, enough space needs to - * be reserved, otherwise only partial data is copied. + * @param {number[]|ArrayBufferView} data - An array to populate with the vertex data. When + * typed array is supplied, enough space needs to be reserved, otherwise only partial data is + * copied. * @returns {number} Returns the number of vertices populated. */ getVertexStream(semantic, data) { @@ -692,8 +694,7 @@ class Mesh extends RefCountedObject { /** * Sets the vertex positions array. Vertices are stored using {@link TYPE_FLOAT32} format. * - * @param {number[]|ArrayBufferView} positions - Vertex - * data containing positions. + * @param {number[]|ArrayBufferView} positions - Vertex data containing positions. * @param {number} [componentCount] - The number of values that form a single position element. * Defaults to 3 if not specified, corresponding to x, y and z coordinates. * @param {number} [numVertices] - The number of vertices to be used from data array. If not @@ -706,8 +707,7 @@ class Mesh extends RefCountedObject { /** * Sets the vertex normals array. Normals are stored using {@link TYPE_FLOAT32} format. * - * @param {number[]|ArrayBufferView} normals - Vertex - * data containing normals. + * @param {number[]|ArrayBufferView} normals - Vertex data containing normals. * @param {number} [componentCount] - The number of values that form a single normal element. * Defaults to 3 if not specified, corresponding to x, y and z direction. * @param {number} [numVertices] - The number of vertices to be used from data array. If not @@ -721,8 +721,7 @@ class Mesh extends RefCountedObject { * Sets the vertex uv array. Uvs are stored using {@link TYPE_FLOAT32} format. * * @param {number} channel - The uv channel in [0..7] range. - * @param {number[]|ArrayBufferView} uvs - Vertex - * data containing uv-coordinates. + * @param {number[]|ArrayBufferView} uvs - Vertex data containing uv-coordinates. * @param {number} [componentCount] - The number of values that form a single uv element. * Defaults to 2 if not specified, corresponding to u and v coordinates. * @param {number} [numVertices] - The number of vertices to be used from data array. If not @@ -736,8 +735,7 @@ class Mesh extends RefCountedObject { * Sets the vertex color array. Colors are stored using {@link TYPE_FLOAT32} format, which is * useful for HDR colors. * - * @param {number[]|ArrayBufferView} colors - Vertex - * data containing colors. + * @param {number[]|ArrayBufferView} colors - Vertex data containing colors. * @param {number} [componentCount] - The number of values that form a single color element. * Defaults to 4 if not specified, corresponding to r, g, b and a. * @param {number} [numVertices] - The number of vertices to be used from data array. If not @@ -752,9 +750,8 @@ class Mesh extends RefCountedObject { * useful for LDR colors. Values in the array are expected in [0..255] range, and are mapped to * [0..1] range in the shader. * - * @param {number[]|ArrayBufferView} colors - Vertex - * data containing colors. The array is expected to contain 4 components per vertex, - * corresponding to r, g, b and a. + * @param {number[]|ArrayBufferView} colors - Vertex data containing colors. The array is + * expected to contain 4 components per vertex, corresponding to r, g, b and a. * @param {number} [numVertices] - The number of vertices to be used from data array. If not * provided, the whole data array is used. This allows to use only part of the data array. */ @@ -781,9 +778,9 @@ class Mesh extends RefCountedObject { /** * Gets the vertex positions data. * - * @param {number[]|ArrayBufferView} positions - An - * array to populate with the vertex data. When typed array is supplied, enough space needs to - * be reserved, otherwise only partial data is copied. + * @param {number[]|ArrayBufferView} positions - An array to populate with the vertex data. + * When typed array is supplied, enough space needs to be reserved, otherwise only partial data + * is copied. * @returns {number} Returns the number of vertices populated. */ getPositions(positions) { @@ -793,9 +790,9 @@ class Mesh extends RefCountedObject { /** * Gets the vertex normals data. * - * @param {number[]|ArrayBufferView} normals - An - * array to populate with the vertex data. When typed array is supplied, enough space needs to - * be reserved, otherwise only partial data is copied. + * @param {number[]|ArrayBufferView} normals - An array to populate with the vertex data. When + * typed array is supplied, enough space needs to be reserved, otherwise only partial data is + * copied. * @returns {number} Returns the number of vertices populated. */ getNormals(normals) { @@ -806,9 +803,9 @@ class Mesh extends RefCountedObject { * Gets the vertex uv data. * * @param {number} channel - The uv channel in [0..7] range. - * @param {number[]|ArrayBufferView} uvs - An - * array to populate with the vertex data. When typed array is supplied, enough space needs to - * be reserved, otherwise only partial data is copied. + * @param {number[]|ArrayBufferView} uvs - An array to populate with the vertex data. When + * typed array is supplied, enough space needs to be reserved, otherwise only partial data is + * copied. * @returns {number} Returns the number of vertices populated. */ getUvs(channel, uvs) { @@ -818,9 +815,9 @@ class Mesh extends RefCountedObject { /** * Gets the vertex color data. * - * @param {number[]|ArrayBufferView} colors - An - * array to populate with the vertex data. When typed array is supplied, enough space needs to - * be reserved, otherwise only partial data is copied. + * @param {number[]|ArrayBufferView} colors - An array to populate with the vertex data. When + * typed array is supplied, enough space needs to be reserved, otherwise only partial data is + * copied. * @returns {number} Returns the number of vertices populated. */ getColors(colors) { diff --git a/src/scene/model.js b/src/scene/model.js index be0225fb778..e541b47968a 100644 --- a/src/scene/model.js +++ b/src/scene/model.js @@ -3,6 +3,10 @@ import { MeshInstance } from './mesh-instance.js'; import { MorphInstance } from './morph-instance.js'; import { SkinInstance } from './skin-instance.js'; +/** + * @import { GraphNode } from './graph-node.js' + */ + /** * A model is a graphical object that can be added to or removed from a scene. It contains a * hierarchy and any number of mesh instances. @@ -13,7 +17,7 @@ class Model { /** * The root node of the model's graph node hierarchy. * - * @type {import('./graph-node.js').GraphNode|null} + * @type {GraphNode|null} */ graph = null; diff --git a/src/scene/morph-instance.js b/src/scene/morph-instance.js index 678ba3bb7a3..5d21057d02d 100644 --- a/src/scene/morph-instance.js +++ b/src/scene/morph-instance.js @@ -1,13 +1,16 @@ import { Debug } from '../core/debug.js'; - import { BLENDEQUATION_ADD, BLENDMODE_ONE } from '../platform/graphics/constants.js'; import { drawQuadWithShader } from './graphics/quad-render-utils.js'; import { RenderTarget } from '../platform/graphics/render-target.js'; import { DebugGraphics } from '../platform/graphics/debug-graphics.js'; - import { createShaderFromCode } from './shader-lib/utils.js'; import { BlendState } from '../platform/graphics/blend-state.js'; +/** + * @import { Morph } from './morph.js' + * @import { Shader } from '../platform/graphics/shader.js' + */ + // vertex shader used to add morph targets from textures into render target const textureMorphVertexShader = /* glsl */ ` attribute vec2 vertex_position; @@ -33,13 +36,13 @@ class MorphInstance { /** * Create a new MorphInstance instance. * - * @param {import('./morph.js').Morph} morph - The {@link Morph} to instance. + * @param {Morph} morph - The {@link Morph} to instance. */ constructor(morph) { /** * The morph with its targets, which is being instanced. * - * @type {import('./morph.js').Morph} + * @type {Morph} */ this.morph = morph; morph.incRefCount(); @@ -249,7 +252,7 @@ class MorphInstance { * Create complete shader for texture based morphing. * * @param {number} count - Number of textures to blend. - * @returns {import('../platform/graphics/shader.js').Shader} Shader. + * @returns {Shader} Shader. * @private */ _getShader(count) { diff --git a/src/scene/morph.js b/src/scene/morph.js index decdb969cad..c1931291b6f 100644 --- a/src/scene/morph.js +++ b/src/scene/morph.js @@ -3,15 +3,19 @@ import { RefCountedObject } from '../core/ref-counted-object.js'; import { Vec3 } from '../core/math/vec3.js'; import { FloatPacking } from '../core/math/float-packing.js'; import { BoundingBox } from '../core/shape/bounding-box.js'; -import { Texture } from '../platform/graphics/texture.js'; -import { VertexBuffer } from '../platform/graphics/vertex-buffer.js'; -import { VertexFormat } from '../platform/graphics/vertex-format.js'; - import { TYPE_UINT32, SEMANTIC_ATTR15, ADDRESS_CLAMP_TO_EDGE, FILTER_NEAREST, PIXELFORMAT_RGBA16F, PIXELFORMAT_RGB32F, PIXELFORMAT_RGBA32F, PIXELFORMAT_RGBA16U, isIntegerPixelFormat } from '../platform/graphics/constants.js'; +import { Texture } from '../platform/graphics/texture.js'; +import { VertexBuffer } from '../platform/graphics/vertex-buffer.js'; +import { VertexFormat } from '../platform/graphics/vertex-format.js'; + +/** + * @import { GraphicsDevice } from '../platform/graphics/graphics-device.js' + * @import { MorphTarget } from './morph-target.js' + */ /** * Contains a list of {@link MorphTarget}s, a combined delta AABB and some associated data. @@ -31,9 +35,8 @@ class Morph extends RefCountedObject { /** * Create a new Morph instance. * - * @param {import('./morph-target.js').MorphTarget[]} targets - A list of morph targets. - * @param {import('../platform/graphics/graphics-device.js').GraphicsDevice} graphicsDevice - - * The graphics device used to manage this morph target. + * @param {MorphTarget[]} targets - A list of morph targets. + * @param {GraphicsDevice} graphicsDevice - The graphics device used to manage this morph target. * @param {object} [options] - Object for passing optional arguments. * @param {boolean} [options.preferHighPrecision] - True if high precision storage should be * preferred. This is faster to create and allows higher precision, but takes more memory and @@ -252,7 +255,7 @@ class Morph extends RefCountedObject { /** * Gets the array of morph targets. * - * @type {import('./morph-target.js').MorphTarget[]} + * @type {MorphTarget[]} */ get targets() { return this._targets; diff --git a/src/scene/render.js b/src/scene/render.js index 6643f5b51f0..74c4cc63a2e 100644 --- a/src/scene/render.js +++ b/src/scene/render.js @@ -1,5 +1,9 @@ import { EventHandler } from '../core/event-handler.js'; +/** + * @import { Mesh } from './mesh.js' + */ + /** * A `Render` contains an array of meshes that are referenced by a single hierarchy node in a GLB * scene, and are accessible using the {@link ContainerResource#renders} property. A `Render` is @@ -23,7 +27,7 @@ class Render extends EventHandler { * Meshes are reference counted, and this class owns the references and is responsible for * releasing the meshes when they are no longer referenced. * - * @type {Array|null} + * @type {Array|null} * @private */ _meshes = null; @@ -31,7 +35,7 @@ class Render extends EventHandler { /** * Sets the meshes that the render contains. * - * @type {Array|null} + * @type {Array|null} */ set meshes(value) { // decrement references on the existing meshes @@ -47,7 +51,7 @@ class Render extends EventHandler { /** * Gets the meshes that the render contains. * - * @type {Array|null} + * @type {Array|null} */ get meshes() { return this._meshes; diff --git a/src/scene/renderer/forward-renderer.js b/src/scene/renderer/forward-renderer.js index 87d9326bf7d..7d7c9a24713 100644 --- a/src/scene/renderer/forward-renderer.js +++ b/src/scene/renderer/forward-renderer.js @@ -1,11 +1,8 @@ import { now } from '../../core/time.js'; import { Debug } from '../../core/debug.js'; - import { Vec3 } from '../../core/math/vec3.js'; import { Color } from '../../core/math/color.js'; - import { DebugGraphics } from '../../platform/graphics/debug-graphics.js'; - import { FOG_NONE, FOG_LINEAR, LIGHTTYPE_OMNI, LIGHTTYPE_SPOT, LIGHTTYPE_DIRECTIONAL, @@ -13,12 +10,24 @@ import { LAYERID_DEPTH } from '../constants.js'; import { WorldClustersDebug } from '../lighting/world-clusters-debug.js'; - import { Renderer } from './renderer.js'; import { LightCamera } from './light-camera.js'; import { RenderPassForward } from './render-pass-forward.js'; import { RenderPassPostprocessing } from './render-pass-postprocessing.js'; +/** + * @import { BindGroup } from '../../platform/graphics/bind-group.js' + * @import { Camera } from '../camera.js' + * @import { FrameGraph } from '../frame-graph.js' + * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js' + * @import { LayerComposition } from '../composition/layer-composition.js' + * @import { Layer } from '../layer.js' + * @import { MeshInstance } from '../mesh-instance.js' + * @import { RenderTarget } from '../../platform/graphics/render-target.js' + * @import { Scene } from '../scene.js' + * @import { WorldClusters } from '../lighting/world-clusters.js' + */ + const _noLights = [[], [], []]; const tmpColor = new Color(); @@ -64,8 +73,7 @@ class ForwardRenderer extends Renderer { /** * Create a new ForwardRenderer instance. * - * @param {import('../../platform/graphics/graphics-device.js').GraphicsDevice} graphicsDevice - The - * graphics device used by the renderer. + * @param {GraphicsDevice} graphicsDevice - The graphics device used by the renderer. */ constructor(graphicsDevice) { super(graphicsDevice); @@ -143,7 +151,7 @@ class ForwardRenderer extends Renderer { // #endif /** - * @param {import('../scene.js').Scene} scene - The scene. + * @param {Scene} scene - The scene. */ dispatchGlobalLights(scene) { const ambientUniform = this.ambientColor; @@ -488,7 +496,7 @@ class ForwardRenderer extends Renderer { const drawCallsCount = drawCalls.length; for (let i = 0; i < drawCallsCount; i++) { - /** @type {import('../mesh-instance.js').MeshInstance} */ + /** @type {MeshInstance} */ const drawCall = drawCalls[i]; // #if _PROFILER @@ -519,8 +527,10 @@ class ForwardRenderer extends Renderer { material._scene = scene; if (material.dirty) { + DebugGraphics.pushGpuMarker(device, `Node: ${drawCall.node.name}, Material: ${material.name}`); material.updateUniforms(device, scene); material.dirty = false; + DebugGraphics.popGpuMarker(device); } } @@ -667,25 +677,22 @@ class ForwardRenderer extends Renderer { * Forward render mesh instances on a specified layer, using a camera and a render target. * Shaders used are based on the shaderPass provided, with optional clustered lighting support. * - * @param {import('../camera.js').Camera} camera - The - * camera. - * @param {import('../../platform/graphics/render-target.js').RenderTarget|undefined} renderTarget - The - * render target. - * @param {import('../layer.js').Layer} layer - The layer. + * @param {Camera} camera - The camera. + * @param {RenderTarget|undefined} renderTarget - The render target. + * @param {Layer} layer - The layer. * @param {boolean} transparent - True if transparent sublayer should be rendered, opaque * otherwise. * @param {number} shaderPass - A type of shader to use during rendering. - * @param {import('../../platform/graphics/bind-group.js').BindGroup[]} viewBindGroups - An array - * storing the view level bing groups (can be empty array, and this function populates if per - * view). + * @param {BindGroup[]} viewBindGroups - An array storing the view level bing groups (can be + * empty array, and this function populates if per view). * @param {object} [options] - Object for passing optional arguments. * @param {boolean} [options.clearColor] - True if the color buffer should be cleared. * @param {boolean} [options.clearDepth] - True if the depth buffer should be cleared. * @param {boolean} [options.clearStencil] - True if the stencil buffer should be cleared. - * @param {import('../lighting/world-clusters.js').WorldClusters} [options.lightClusters] - The - * world clusters object to be used for clustered lighting. - * @param {import('../mesh-instance.js').MeshInstance[]} [options.meshInstances] - The mesh - * instances to be rendered. Use when layer is not provided. + * @param {WorldClusters} [options.lightClusters] - The world clusters object to be used for + * clustered lighting. + * @param {MeshInstance[]} [options.meshInstances] - The mesh instances to be rendered. Use + * when layer is not provided. * @param {object} [options.splitLights] - The split lights to be used for clustered lighting. */ renderForwardLayer(camera, renderTarget, layer, transparent, shaderPass, viewBindGroups, options = {}) { @@ -815,9 +822,9 @@ class ForwardRenderer extends Renderer { /** * Builds a frame graph for the rendering of the whole frame. * - * @param {import('../frame-graph.js').FrameGraph} frameGraph - The frame-graph that is built. - * @param {import('../composition/layer-composition.js').LayerComposition} layerComposition - The - * layer composition used to build the frame graph. + * @param {FrameGraph} frameGraph - The frame-graph that is built. + * @param {LayerComposition} layerComposition - The layer composition used to build the frame + * graph. * @ignore */ buildFrameGraph(frameGraph, layerComposition) { @@ -912,9 +919,8 @@ class ForwardRenderer extends Renderer { } /** - * @param {import('../frame-graph.js').FrameGraph} frameGraph - The frame graph. - * @param {import('../composition/layer-composition.js').LayerComposition} layerComposition - The - * layer composition. + * @param {FrameGraph} frameGraph - The frame graph. + * @param {LayerComposition} layerComposition - The layer composition. */ addMainRenderPass(frameGraph, layerComposition, renderTarget, startIndex, endIndex) { @@ -930,8 +936,7 @@ class ForwardRenderer extends Renderer { } /** - * @param {import('../composition/layer-composition.js').LayerComposition} comp - The layer - * composition. + * @param {LayerComposition} comp - The layer composition. */ update(comp) { diff --git a/src/scene/renderer/render-pass-forward.js b/src/scene/renderer/render-pass-forward.js index fab11bbdc4e..eab9c93bd1d 100644 --- a/src/scene/renderer/render-pass-forward.js +++ b/src/scene/renderer/render-pass-forward.js @@ -2,13 +2,20 @@ import { TRACEID_RENDER_PASS_DETAIL } from "../../core/constants.js"; import { Debug } from "../../core/debug.js"; import { now } from "../../core/time.js"; import { Tracing } from "../../core/tracing.js"; - import { BlendState } from "../../platform/graphics/blend-state.js"; import { DebugGraphics } from "../../platform/graphics/debug-graphics.js"; import { RenderPass } from "../../platform/graphics/render-pass.js"; import { RenderAction } from "../composition/render-action.js"; import { SHADER_FORWARD } from "../constants.js"; +/** + * @import { CameraComponent } from '../../framework/components/camera/component.js' + * @import { LayerComposition } from '../composition/layer-composition.js' + * @import { Layer } from '../layer.js' + * @import { Renderer } from './renderer.js' + * @import { Scene } from '../scene.js' + */ + /** * A render pass used render a set of layers using a camera. * @@ -16,22 +23,22 @@ import { SHADER_FORWARD } from "../constants.js"; */ class RenderPassForward extends RenderPass { /** - * @type {import('../composition/layer-composition.js').LayerComposition} + * @type {LayerComposition} */ layerComposition; /** - * @type {import('../scene.js').Scene} + * @type {Scene} */ scene; /** - * @type {import('./renderer.js').Renderer} + * @type {Renderer} */ renderer; /** - * @type {import('../composition/render-action.js').RenderAction[]} + * @type {RenderAction[]} */ renderActions = []; @@ -58,9 +65,9 @@ class RenderPassForward extends RenderPass { /** * Adds a layer to be rendered by this render pass. * - * @param {import('../../framework/components/camera/component.js').CameraComponent} cameraComponent - - * The camera component that is used to render the layers. - * @param {import('../layer.js').Layer} layer - The layer to be added. + * @param {CameraComponent} cameraComponent - The camera component that is used to render the + * layers. + * @param {Layer} layer - The layer to be added. * @param {boolean} transparent - True if the layer is transparent. * @param {boolean} autoClears - True if the render target should be cleared based on the camera * and layer clear flags. Defaults to true. @@ -92,10 +99,10 @@ class RenderPassForward extends RenderPass { * given id and transparency is reached (inclusive). Note that only layers that are enabled * and are rendered by the specified camera are added. * - * @param {import('../composition/layer-composition.js').LayerComposition} composition - The - * layer composition containing the layers to be added, typically the scene layer composition. - * @param {import('../../framework/components/camera/component.js').CameraComponent} cameraComponent - - * The camera component that is used to render the layers. + * @param {LayerComposition} composition - The layer composition containing the layers to be + * added, typically the scene layer composition. + * @param {CameraComponent} cameraComponent - The camera component that is used to render the + * layers. * @param {number} startIndex - The index of the first layer to be considered for adding. * @param {boolean} firstLayerClears - True if the first layer added should clear the render * target. @@ -225,8 +232,7 @@ class RenderPassForward extends RenderPass { } /** - * @param {import('../composition/render-action.js').RenderAction} renderAction - The render - * action. + * @param {RenderAction} renderAction - The render action. * @param {boolean} firstRenderAction - True if this is the first render action in the render pass. */ renderRenderAction(renderAction, firstRenderAction) { diff --git a/src/scene/renderer/renderer.js b/src/scene/renderer/renderer.js index 4b41d2cf331..2f94d027a9c 100644 --- a/src/scene/renderer/renderer.js +++ b/src/scene/renderer/renderer.js @@ -1,22 +1,12 @@ import { Debug, DebugHelper } from '../../core/debug.js'; import { now } from '../../core/time.js'; +import { BlueNoise } from '../../core/math/blue-noise.js'; import { Vec2 } from '../../core/math/vec2.js'; import { Vec3 } from '../../core/math/vec3.js'; import { Vec4 } from '../../core/math/vec4.js'; import { Mat3 } from '../../core/math/mat3.js'; import { Mat4 } from '../../core/math/mat4.js'; import { BoundingSphere } from '../../core/shape/bounding-sphere.js'; - -import { - SORTKEY_DEPTH, SORTKEY_FORWARD, - VIEW_CENTER, PROJECTION_ORTHOGRAPHIC, - LIGHTTYPE_DIRECTIONAL, MASK_AFFECT_DYNAMIC, MASK_AFFECT_LIGHTMAPPED, MASK_BAKE, - SHADOWUPDATE_NONE, SHADOWUPDATE_THISFRAME -} from '../constants.js'; -import { LightTextureAtlas } from '../lighting/light-texture-atlas.js'; -import { Material } from '../materials/material.js'; -import { LightCube } from '../graphics/light-cube.js'; - import { CLEARFLAG_COLOR, CLEARFLAG_DEPTH, CLEARFLAG_STENCIL, BINDGROUP_MESH, BINDGROUP_VIEW, UNIFORM_BUFFER_DEFAULT_SLOT_NAME, @@ -31,15 +21,33 @@ import { UniformBuffer } from '../../platform/graphics/uniform-buffer.js'; import { BindGroup, DynamicBindGroup } from '../../platform/graphics/bind-group.js'; import { UniformFormat, UniformBufferFormat } from '../../platform/graphics/uniform-buffer-format.js'; import { BindGroupFormat, BindUniformBufferFormat, BindTextureFormat } from '../../platform/graphics/bind-group-format.js'; - +import { + SORTKEY_DEPTH, SORTKEY_FORWARD, + VIEW_CENTER, PROJECTION_ORTHOGRAPHIC, + LIGHTTYPE_DIRECTIONAL, MASK_AFFECT_DYNAMIC, MASK_AFFECT_LIGHTMAPPED, MASK_BAKE, + SHADOWUPDATE_NONE, SHADOWUPDATE_THISFRAME +} from '../constants.js'; +import { LightCube } from '../graphics/light-cube.js'; +import { getBlueNoiseTexture } from '../graphics/noise-textures.js'; +import { LightTextureAtlas } from '../lighting/light-texture-atlas.js'; +import { Material } from '../materials/material.js'; import { ShadowMapCache } from './shadow-map-cache.js'; import { ShadowRendererLocal } from './shadow-renderer-local.js'; import { ShadowRendererDirectional } from './shadow-renderer-directional.js'; import { ShadowRenderer } from './shadow-renderer.js'; import { WorldClustersAllocator } from './world-clusters-allocator.js'; import { RenderPassUpdateClustered } from './render-pass-update-clustered.js'; -import { getBlueNoiseTexture } from '../graphics/noise-textures.js'; -import { BlueNoise } from '../../core/math/blue-noise.js'; + +/** + * @import { Camera } from '../camera.js' + * @import { CulledInstances } from '../layer.js' + * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js' + * @import { LayerComposition } from '../composition/layer-composition.js' + * @import { Light } from '../light.js' + * @import { MeshInstance } from '../mesh-instance.js' + * @import { RenderTarget } from '../../platform/graphics/render-target.js' + * @import { Scene } from '../scene.js' + */ let _skinUpdateIndex = 0; const viewProjMat = new Mat4(); @@ -104,7 +112,7 @@ class Renderer { * A set of visible mesh instances which need further processing before being rendered, e.g. * skinning or morphing. Extracted during culling. * - * @type {Set} + * @type {Set} * @private */ processingMeshInstances = new Set(); @@ -118,14 +126,14 @@ class Renderer { /** * A list of all unique lights in the layer composition. * - * @type {import('../light.js').Light[]} + * @type {Light[]} */ lights = []; /** * A list of all unique local lights (spot & omni) in the layer composition. * - * @type {import('../light.js').Light[]} + * @type {Light[]} */ localLights = []; @@ -133,7 +141,7 @@ class Renderer { * A list of unique directional shadow casting lights for each enabled camera. This is generated * each frame during light culling. * - * @type {Map>} + * @type {Map>} */ cameraDirShadowLights = new Map(); @@ -142,7 +150,7 @@ class Renderer { * is cleared each frame, and updated each time a directional light shadow is rendered for a * camera, and allows us to manually schedule shadow passes when a new camera needs a shadow. * - * @type {Map} + * @type {Map} */ dirLightShadows = new Map(); @@ -151,13 +159,12 @@ class Renderer { /** * Create a new instance. * - * @param {import('../../platform/graphics/graphics-device.js').GraphicsDevice} graphicsDevice - The - * graphics device used by the renderer. + * @param {GraphicsDevice} graphicsDevice - The graphics device used by the renderer. */ constructor(graphicsDevice) { this.device = graphicsDevice; - /** @type {import('../scene.js').Scene|null} */ + /** @type {Scene|null} */ this.scene = null; // TODO: allocate only when the scene has clustered lighting enabled @@ -304,10 +311,8 @@ class Renderer { /** * Set up the viewport and the scissor for camera rendering. * - * @param {import('../camera.js').Camera} camera - The camera containing the viewport - * information. - * @param {import('../../platform/graphics/render-target.js').RenderTarget} [renderTarget] - The - * render target. NULL for the default one. + * @param {Camera} camera - The camera containing the viewport information. + * @param {RenderTarget} [renderTarget] - The render target. NULL for the default one. */ setupViewport(camera, renderTarget) { @@ -468,7 +473,7 @@ class Renderer { /** * Clears the active render target. If the viewport is already set up, only its area is cleared. * - * @param {import('../camera.js').Camera} camera - The camera supplying the value to clear to. + * @param {Camera} camera - The camera supplying the value to clear to. * @param {boolean} [clearColor] - True if the color buffer should be cleared. Uses the value * from the camera if not supplied. * @param {boolean} [clearDepth] - True if the depth buffer should be cleared. Uses the value @@ -633,8 +638,7 @@ class Renderer { /** * Update skin matrices ahead of rendering. * - * @param {import('../mesh-instance.js').MeshInstance[]|Set} drawCalls - MeshInstances - * containing skinInstance. + * @param {MeshInstance[]|Set} drawCalls - MeshInstances containing skinInstance. * @ignore */ updateGpuSkinMatrices(drawCalls) { @@ -659,8 +663,7 @@ class Renderer { /** * Update morphing ahead of rendering. * - * @param {import('../mesh-instance.js').MeshInstance[]|Set} drawCalls - MeshInstances - * containing morphInstance. + * @param {MeshInstance[]|Set} drawCalls - MeshInstances containing morphInstance. * @ignore */ updateMorphing(drawCalls) { @@ -683,8 +686,7 @@ class Renderer { /** * Update gsplats ahead of rendering. * - * @param {import('../mesh-instance.js').MeshInstance[]|Set} drawCalls - MeshInstances - * containing gsplatInstances. + * @param {MeshInstance[]|Set} drawCalls - MeshInstances containing gsplatInstances. * @ignore */ updateGSplats(drawCalls) { @@ -696,8 +698,7 @@ class Renderer { /** * Update draw calls ahead of rendering. * - * @param {import('../mesh-instance.js').MeshInstance[]|Set} drawCalls - MeshInstances - * requiring updates. + * @param {MeshInstance[]|Set} drawCalls - MeshInstances requiring updates. * @ignore */ gpuUpdate(drawCalls) { @@ -892,9 +893,9 @@ class Renderer { } /** - * @param {import('../camera.js').Camera} camera - The camera used for culling. - * @param {import('../mesh-instance.js').MeshInstance[]} drawCalls - Draw calls to cull. - * @param {import('../layer.js').CulledInstances} culledInstances - Stores culled instances. + * @param {Camera} camera - The camera used for culling. + * @param {MeshInstance[]} drawCalls - Draw calls to cull. + * @param {CulledInstances} culledInstances - Stores culled instances. */ cull(camera, drawCalls, culledInstances) { // #if _PROFILER @@ -1038,12 +1039,11 @@ class Renderer { } /** - * Shadow map culling for directional and visible local lights - * visible meshInstances are collected into light._renderData, and are marked as visible - * for directional lights also shadow camera matrix is set up + * Shadow map culling for directional and visible local lights visible meshInstances are + * collected into light._renderData, and are marked as visible for directional lights also + * shadow camera matrix is set up. * - * @param {import('../composition/layer-composition.js').LayerComposition} comp - The layer - * composition. + * @param {LayerComposition} comp - The layer composition. */ cullShadowmaps(comp) { @@ -1118,11 +1118,10 @@ class Renderer { } /** - * visibility culling of lights, meshInstances, shadows casters - * Also applies meshInstance.visible + * visibility culling of lights, meshInstances, shadows casters. Also applies + * `meshInstance.visible`. * - * @param {import('../composition/layer-composition.js').LayerComposition} comp - The layer - * composition. + * @param {LayerComposition} comp - The layer composition. */ cullComposition(comp) { @@ -1188,7 +1187,7 @@ class Renderer { } /** - * @param {import('../mesh-instance.js').MeshInstance[]} drawCalls - Mesh instances. + * @param {MeshInstance[]} drawCalls - Mesh instances. * @param {boolean} onlyLitShaders - Limits the update to shaders affected by lighting. */ updateShaders(drawCalls, onlyLitShaders) { @@ -1226,8 +1225,7 @@ class Renderer { } /** - * @param {import('../composition/layer-composition.js').LayerComposition} comp - The layer - * composition to update. + * @param {LayerComposition} comp - The layer composition to update. */ beginFrame(comp) { @@ -1299,8 +1297,7 @@ class Renderer { /** * Updates the layer composition for rendering. * - * @param {import('../composition/layer-composition.js').LayerComposition} comp - The layer - * composition to update. + * @param {LayerComposition} comp - The layer composition to update. */ updateLayerComposition(comp) { diff --git a/src/scene/renderer/shadow-renderer-directional.js b/src/scene/renderer/shadow-renderer-directional.js index 8bb5394f306..0ae7145714e 100644 --- a/src/scene/renderer/shadow-renderer-directional.js +++ b/src/scene/renderer/shadow-renderer-directional.js @@ -3,14 +3,20 @@ import { math } from '../../core/math/math.js'; import { Vec3 } from '../../core/math/vec3.js'; import { Mat4 } from '../../core/math/mat4.js'; import { BoundingBox } from '../../core/shape/bounding-box.js'; - import { LIGHTTYPE_DIRECTIONAL, SHADOWUPDATE_NONE } from '../constants.js'; - import { ShadowMap } from './shadow-map.js'; import { RenderPassShadowDirectional } from './render-pass-shadow-directional.js'; +/** + * @import { Camera } from '../camera.js' + * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js' + * @import { Light } from '../light.js' + * @import { Renderer } from './renderer.js' + * @import { ShadowRenderer } from './shadow-renderer.js' + */ + const visibleSceneAabb = new BoundingBox(); const center = new Vec3(); const shadowCamView = new Mat4(); @@ -46,13 +52,13 @@ function getDepthRange(cameraViewMatrix, aabbMin, aabbMax) { } class ShadowRendererDirectional { - /** @type {import('./renderer.js').Renderer} */ + /** @type {Renderer} */ renderer; - /** @type {import('./shadow-renderer.js').ShadowRenderer} */ + /** @type {ShadowRenderer} */ shadowRenderer; - /** @type {import('../../platform/graphics/graphics-device.js').GraphicsDevice} */ + /** @type {GraphicsDevice} */ device; constructor(renderer, shadowRenderer) { @@ -199,8 +205,8 @@ class ShadowRendererDirectional { /** * Create a render pass for directional light shadow rendering for a specified camera. * - * @param {import('../light.js').Light} light - The directional light. - * @param {import('../camera.js').Camera} camera - The camera. + * @param {Light} light - The directional light. + * @param {Camera} camera - The camera. * @returns {RenderPassShadowDirectional|null} - The render pass if the shadow rendering is * required, or null otherwise. */ diff --git a/src/scene/renderer/shadow-renderer-local.js b/src/scene/renderer/shadow-renderer-local.js index 97a2a9e13c0..d18cd923f7b 100644 --- a/src/scene/renderer/shadow-renderer-local.js +++ b/src/scene/renderer/shadow-renderer-local.js @@ -1,23 +1,29 @@ import { math } from '../../core/math/math.js'; - -import { ShadowMap } from './shadow-map.js'; import { LIGHTTYPE_OMNI, LIGHTTYPE_SPOT } from '../constants.js'; - +import { ShadowMap } from './shadow-map.js'; import { RenderPassShadowLocalNonClustered } from './render-pass-shadow-local-non-clustered.js'; +/** + * @import { FrameGraph } from '../../scene/frame-graph.js' + * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js' + * @import { Light } from '../../scene/light.js' + * @import { Renderer } from './renderer.js' + * @import { ShadowRenderer } from './shadow-renderer.js' + */ + class ShadowRendererLocal { // temporary list to collect lights to render shadows for shadowLights = []; - /** @type {import('./renderer.js').Renderer} */ + /** @type {Renderer} */ renderer; - /** @type {import('./shadow-renderer.js').ShadowRenderer} */ + /** @type {ShadowRenderer} */ shadowRenderer; - /** @type {import('../../platform/graphics/graphics-device.js').GraphicsDevice} */ + /** @type {GraphicsDevice} */ device; constructor(renderer, shadowRenderer) { @@ -108,8 +114,8 @@ class ShadowRendererLocal { * Prepare render passes for rendering of shadows for local non-clustered lights. Each shadow face * is a separate render pass as it renders to a separate render target. * - * @param {import('../../scene/frame-graph.js').FrameGraph} frameGraph - The frame graph. - * @param {import('../../scene/light.js').Light[]} localLights - The list of local lights. + * @param {FrameGraph} frameGraph - The frame graph. + * @param {Light[]} localLights - The list of local lights. */ buildNonClusteredRenderPasses(frameGraph, localLights) { diff --git a/src/scene/renderer/shadow-renderer.js b/src/scene/renderer/shadow-renderer.js index 039a505b8cf..a6c97f29b04 100644 --- a/src/scene/renderer/shadow-renderer.js +++ b/src/scene/renderer/shadow-renderer.js @@ -4,11 +4,9 @@ import { Color } from '../../core/math/color.js'; import { Mat4 } from '../../core/math/mat4.js'; import { Vec3 } from '../../core/math/vec3.js'; import { Vec4 } from '../../core/math/vec4.js'; - import { SHADERSTAGE_FRAGMENT, SHADERSTAGE_VERTEX, UNIFORMTYPE_MAT4, UNIFORM_BUFFER_DEFAULT_SLOT_NAME } from '../../platform/graphics/constants.js'; import { DebugGraphics } from '../../platform/graphics/debug-graphics.js'; import { drawQuadWithShader } from '../graphics/quad-render-utils.js'; - import { BLUR_GAUSSIAN, LIGHTTYPE_DIRECTIONAL, LIGHTTYPE_OMNI, @@ -26,6 +24,23 @@ import { BindUniformBufferFormat, BindGroupFormat } from '../../platform/graphic import { BlendState } from '../../platform/graphics/blend-state.js'; import { RenderingParams } from './rendering-params.js'; +/** + * @import { Camera } from '../camera.js' + * @import { LayerComposition } from '../composition/layer-composition.js' + * @import { LightTextureAtlas } from '../lighting/light-texture-atlas.js' + * @import { Light } from '../light.js' + * @import { MeshInstance } from '../mesh-instance.js' + * @import { Renderer } from './renderer.js' + * @import { ShaderPassInfo } from '../shader-pass.js' + */ + +const tempSet = new Set(); +const shadowCamView = new Mat4(); +const shadowCamViewProj = new Mat4(); +const pixelOffset = new Float32Array(2); +const blurScissorRect = new Vec4(1, 1, 0, 0); +const viewportMatrix = new Mat4(); + function gauss(x, sigma) { return Math.exp(-(x * x) / (2.0 * sigma * sigma)); } @@ -47,34 +62,26 @@ function gaussWeights(kernelSize) { return values; } -const tempSet = new Set(); -const shadowCamView = new Mat4(); -const shadowCamViewProj = new Mat4(); -const pixelOffset = new Float32Array(2); -const blurScissorRect = new Vec4(1, 1, 0, 0); -const viewportMatrix = new Mat4(); - class ShadowRenderer { /** * A cache of shadow passes. First index is looked up by light type, second by shadow type. * - * @type {import('../shader-pass.js').ShaderPassInfo[][]} + * @type {ShaderPassInfo[][]} * @private */ shadowPassCache = []; /** - * @param {import('./renderer.js').Renderer} renderer - The renderer. - * @param {import('../lighting/light-texture-atlas.js').LightTextureAtlas} lightTextureAtlas - The - * shadow map atlas. + * @param {Renderer} renderer - The renderer. + * @param {LightTextureAtlas} lightTextureAtlas - The shadow map atlas. */ constructor(renderer, lightTextureAtlas) { this.device = renderer.device; - /** @type {import('./renderer.js').Renderer} */ + /** @type {Renderer} */ this.renderer = renderer; - /** @type {import('../lighting/light-texture-atlas.js').LightTextureAtlas} */ + /** @type {LightTextureAtlas} */ this.lightTextureAtlas = lightTextureAtlas; const scope = this.device.scope; @@ -157,14 +164,13 @@ class ShadowRenderer { /** * Culls the list of shadow casters used by the light by the camera, storing visible mesh * instances in the specified array. - * @param {import('../composition/layer-composition.js').LayerComposition} comp - The layer - * composition used as a source of shadow casters, if those are not provided directly. - * @param {import('../light.js').Light} light - The light. - * @param {import('../mesh-instance.js').MeshInstance[]} visible - The array to store visible - * mesh instances in. - * @param {import('../camera.js').Camera} camera - The camera. - * @param {import('../mesh-instance.js').MeshInstance[]} [casters] - Optional array of mesh - * instances to use as casters. + * + * @param {LayerComposition} comp - The layer composition used as a source of shadow casters, + * if those are not provided directly. + * @param {Light} light - The light. + * @param {MeshInstance[]} visible - The array to store visible mesh instances in. + * @param {Camera} camera - The camera. + * @param {MeshInstance[]} [casters] - Optional array of mesh instances to use as casters. */ cullShadowCasters(comp, light, visible, camera, casters) { @@ -243,7 +249,7 @@ class ShadowRenderer { } /** - * @param {import('../light.js').Light} light - The light. + * @param {Light} light - The light. * @returns {number} Index of shadow pass info. */ getShadowPass(light) { @@ -272,9 +278,8 @@ class ShadowRenderer { } /** - * @param {import('../mesh-instance.js').MeshInstance[]} visibleCasters - Visible mesh - * instances. - * @param {import('../light.js').Light} light - The light. + * @param {MeshInstance[]} visibleCasters - Visible mesh instances. + * @param {Light} light - The light. */ submitCasters(visibleCasters, light) { diff --git a/src/scene/renderer/world-clusters-allocator.js b/src/scene/renderer/world-clusters-allocator.js index 76fae5c2583..384b90a0fde 100644 --- a/src/scene/renderer/world-clusters-allocator.js +++ b/src/scene/renderer/world-clusters-allocator.js @@ -1,6 +1,11 @@ import { DebugHelper } from '../../core/debug.js'; import { WorldClusters } from '../lighting/world-clusters.js'; +/** + * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js' + * @import { RenderAction } from '../composition/render-action.js' + */ + const tempClusterArray = []; /** @@ -26,15 +31,14 @@ class WorldClustersAllocator { * Render actions with all unique light clusters. The key is the hash of lights on a layer, the * value is a render action with unique light clusters. * - * @type {Map} + * @type {Map} */ _clusters = new Map(); /** * Create a new instance. * - * @param {import('../../platform/graphics/graphics-device.js').GraphicsDevice} graphicsDevice - - * The graphics device. + * @param {GraphicsDevice} graphicsDevice - The graphics device. */ constructor(graphicsDevice) { this.device = graphicsDevice; diff --git a/src/scene/scene.js b/src/scene/scene.js index 240e8413200..2fbc4828536 100644 --- a/src/scene/scene.js +++ b/src/scene/scene.js @@ -6,9 +6,7 @@ import { Quat } from '../core/math/quat.js'; import { math } from '../core/math/math.js'; import { Mat3 } from '../core/math/mat3.js'; import { Mat4 } from '../core/math/mat4.js'; - import { PIXELFORMAT_RGBA8, ADDRESS_CLAMP_TO_EDGE, FILTER_LINEAR } from '../platform/graphics/constants.js'; - import { BAKE_COLORDIR, FOG_NONE, LAYERID_IMMEDIATE } from './constants.js'; import { LightingParams } from './lighting/lighting-params.js'; import { Sky } from './skybox/sky.js'; @@ -16,6 +14,14 @@ import { Immediate } from './immediate/immediate.js'; import { EnvLighting } from './graphics/env-lighting.js'; import { RenderingParams } from './renderer/rendering-params.js'; +/** + * @import { Entity } from '../framework/entity.js' + * @import { GraphicsDevice } from '../platform/graphics/graphics-device.js' + * @import { LayerComposition } from './composition/layer-composition.js' + * @import { Layer } from './layer.js' + * @import { Texture } from '../platform/graphics/texture.js' + */ + /** * A scene is graphical representation of an environment. It manages the scene hierarchy, all * graphical objects, lights, and scene-wide properties. @@ -189,7 +195,7 @@ class Scene extends EventHandler { * The root entity of the scene, which is usually the only child to the {@link Application} * root entity. * - * @type {import('../framework/entity.js').Entity} + * @type {Entity} */ root = null; @@ -203,7 +209,7 @@ class Scene extends EventHandler { /** * Environment lighting atlas * - * @type {import('../platform/graphics/texture.js').Texture|null} + * @type {Texture|null} * @private */ _envAtlas = null; @@ -211,7 +217,7 @@ class Scene extends EventHandler { /** * The skybox cubemap as set by user (gets used when skyboxMip === 0) * - * @type {import('../platform/graphics/texture.js').Texture|null} + * @type {Texture|null} * @private */ _skyboxCubeMap = null; @@ -226,8 +232,7 @@ class Scene extends EventHandler { /** * Create a new Scene instance. * - * @param {import('../platform/graphics/graphics-device.js').GraphicsDevice} graphicsDevice - - * The graphics device used to manage this scene. + * @param {GraphicsDevice} graphicsDevice - The graphics device used to manage this scene. * @ignore */ constructor(graphicsDevice) { @@ -239,7 +244,7 @@ class Scene extends EventHandler { this._gravity = new Vec3(0, -9.8, 0); /** - * @type {import('./composition/layer-composition.js').LayerComposition} + * @type {LayerComposition} * @private */ this._layers = null; @@ -249,7 +254,7 @@ class Scene extends EventHandler { /** * Array of 6 prefiltered lighting data cubemaps. * - * @type {import('../platform/graphics/texture.js').Texture[]} + * @type {Texture[]} * @private */ this._prefilteredCubemaps = []; @@ -308,7 +313,7 @@ class Scene extends EventHandler { /** * Gets the default layer used by the immediate drawing functions. * - * @type {import('./layer.js').Layer} + * @type {Layer} * @ignore */ get defaultDrawLayer() { @@ -390,7 +395,7 @@ class Scene extends EventHandler { /** * Sets the environment lighting atlas. * - * @type {import('../platform/graphics/texture.js').Texture} + * @type {Texture} */ set envAtlas(value) { if (value !== this._envAtlas) { @@ -418,7 +423,7 @@ class Scene extends EventHandler { /** * Gets the environment lighting atlas. * - * @type {import('../platform/graphics/texture.js').Texture} + * @type {Texture} */ get envAtlas() { return this._envAtlas; @@ -455,7 +460,7 @@ class Scene extends EventHandler { /** * Sets the {@link LayerComposition} that defines rendering order of this scene. * - * @type {import('./composition/layer-composition.js').LayerComposition} + * @type {LayerComposition} */ set layers(layers) { const prev = this._layers; @@ -466,7 +471,7 @@ class Scene extends EventHandler { /** * Gets the {@link LayerComposition} that defines rendering order of this scene. * - * @type {import('./composition/layer-composition.js').LayerComposition} + * @type {LayerComposition} */ get layers() { return this._layers; @@ -537,7 +542,7 @@ class Scene extends EventHandler { /** * Sets the 6 prefiltered cubemaps acting as the source of image-based lighting. * - * @type {import('../platform/graphics/texture.js').Texture[]} + * @type {Texture[]} */ set prefilteredCubemaps(value) { value = value || []; @@ -570,7 +575,7 @@ class Scene extends EventHandler { /** * Gets the 6 prefiltered cubemaps acting as the source of image-based lighting. * - * @type {import('../platform/graphics/texture.js').Texture[]} + * @type {Texture[]} */ get prefilteredCubemaps() { return this._prefilteredCubemaps; @@ -579,7 +584,7 @@ class Scene extends EventHandler { /** * Sets the base cubemap texture used as the scene's skybox when skyboxMip is 0. Defaults to null. * - * @type {import('../platform/graphics/texture.js').Texture} + * @type {Texture} */ set skybox(value) { if (value !== this._skyboxCubeMap) { @@ -591,7 +596,7 @@ class Scene extends EventHandler { /** * Gets the base cubemap texture used as the scene's skybox when skyboxMip is 0. * - * @type {import('../platform/graphics/texture.js').Texture} + * @type {Texture} */ get skybox() { return this._skyboxCubeMap; @@ -801,12 +806,11 @@ class Scene extends EventHandler { /** * Sets the cubemap for the scene skybox. * - * @param {import('../platform/graphics/texture.js').Texture[]} [cubemaps] - An array of - * cubemaps corresponding to the skybox at different mip levels. If undefined, scene will - * remove skybox. Cubemap array should be of size 7, with the first element (index 0) - * corresponding to the base cubemap (mip level 0) with original resolution. Each remaining - * element (index 1-6) corresponds to a fixed prefiltered resolution (128x128, 64x64, 32x32, - * 16x16, 8x8, 4x4). + * @param {Texture[]} [cubemaps] - An array of cubemaps corresponding to the skybox at + * different mip levels. If undefined, scene will remove skybox. Cubemap array should be of + * size 7, with the first element (index 0) corresponding to the base cubemap (mip level 0) + * with original resolution. Each remaining element (index 1-6) corresponds to a fixed + * prefiltered resolution (128x128, 64x64, 32x32, 16x16, 8x8, 4x4). */ setSkybox(cubemaps) { if (!cubemaps) { diff --git a/src/scene/shader-lib/chunks/lit/frag/refractionDynamic.js b/src/scene/shader-lib/chunks/lit/frag/refractionDynamic.js index f2f7b271766..14ef331b7cb 100644 --- a/src/scene/shader-lib/chunks/lit/frag/refractionDynamic.js +++ b/src/scene/shader-lib/chunks/lit/frag/refractionDynamic.js @@ -13,14 +13,10 @@ vec3 evalRefractionColor(vec3 refractionVector, float gloss, float refractionInd // use built-in getGrabScreenPos function to convert screen position to grab texture uv coords vec2 uv = getGrabScreenPos(projectionPoint); - #ifdef SUPPORTS_TEXLOD - // Use IOR and roughness to select mip - float iorToRoughness = (1.0 - gloss) * clamp((1.0 / refractionIndex) * 2.0 - 2.0, 0.0, 1.0); - float refractionLod = log2(uScreenSize.x) * iorToRoughness; - vec3 refraction = texture2DLodEXT(uSceneColorMap, uv, refractionLod).rgb; - #else - vec3 refraction = texture2D(uSceneColorMap, uv).rgb; - #endif + // Use IOR and roughness to select mip + float iorToRoughness = (1.0 - gloss) * clamp((1.0 / refractionIndex) * 2.0 - 2.0, 0.0, 1.0); + float refractionLod = log2(uScreenSize.x) * iorToRoughness; + vec3 refraction = texture2DLodEXT(uSceneColorMap, uv, refractionLod).rgb; return refraction; } diff --git a/src/scene/shader-lib/chunks/standard/frag/emissive.js b/src/scene/shader-lib/chunks/standard/frag/emissive.js index 4488760d442..c342e55dbc8 100644 --- a/src/scene/shader-lib/chunks/standard/frag/emissive.js +++ b/src/scene/shader-lib/chunks/standard/frag/emissive.js @@ -1,22 +1,9 @@ export default /* glsl */` -#ifdef MAPCOLOR uniform vec3 material_emissive; -#endif - -#ifdef MAPFLOAT uniform float material_emissiveIntensity; -#endif void getEmission() { - dEmission = vec3(1.0); - - #ifdef MAPFLOAT - dEmission *= material_emissiveIntensity; - #endif - - #ifdef MAPCOLOR - dEmission *= material_emissive; - #endif + dEmission = material_emissive * material_emissiveIntensity; #ifdef MAPTEXTURE dEmission *= $DECODE(texture2DBias($SAMPLER, $UV, textureBias)).$CH; diff --git a/src/scene/shader-lib/get-program-library.js b/src/scene/shader-lib/get-program-library.js index f84b9a2ec92..0c9ca4dad92 100644 --- a/src/scene/shader-lib/get-program-library.js +++ b/src/scene/shader-lib/get-program-library.js @@ -1,15 +1,19 @@ import { Debug } from '../../core/debug.js'; import { DeviceCache } from '../../platform/graphics/device-cache.js'; +/** + * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js' + * @import { ProgramLibrary } from './program-library.js' + */ + // Device cache storing a program library const programLibraryDeviceCache = new DeviceCache(); /** * Returns program library for a specified instance of a device. * - * @param {import('../../platform/graphics/graphics-device.js').GraphicsDevice} device - The - * graphics device used to own the program library. - * @returns {import('./program-library.js').ProgramLibrary} The instance of {@link ProgramLibrary} + * @param {GraphicsDevice} device - The graphics device used to own the program library. + * @returns {ProgramLibrary} The instance of {@link ProgramLibrary} * @ignore */ function getProgramLibrary(device) { @@ -21,10 +25,8 @@ function getProgramLibrary(device) { /** * Assigns the program library to device cache. * - * @param {import('../../platform/graphics/graphics-device.js').GraphicsDevice} device - The - * graphics device used to own the program library. - * @param {import('./program-library.js').ProgramLibrary} library - The instance of - * {@link ProgramLibrary}. + * @param {GraphicsDevice} device - The graphics device used to own the program library. + * @param {ProgramLibrary} library - The instance of {@link ProgramLibrary}. * @ignore */ function setProgramLibrary(device, library) { diff --git a/src/scene/shader-lib/program-library.js b/src/scene/shader-lib/program-library.js index 8e9d40e6ffa..627e774481f 100644 --- a/src/scene/shader-lib/program-library.js +++ b/src/scene/shader-lib/program-library.js @@ -1,14 +1,16 @@ import { Debug } from '../../core/debug.js'; import { hashCode } from '../../core/hash.js'; import { version, revision } from '../../core/core.js'; - import { Shader } from '../../platform/graphics/shader.js'; - import { SHADER_FORWARD, SHADER_DEPTH, SHADER_PICK, SHADER_SHADOW, SHADER_PREPASS_VELOCITY } from '../constants.js'; import { ShaderPass } from '../shader-pass.js'; import { StandardMaterialOptions } from '../materials/standard-material-options.js'; import { RenderingParams } from '../renderer/rendering-params.js'; +/** + * @import { ShaderGenerator } from './programs/shader-generator.js' + */ + /** * A class responsible for creation and caching of required shaders. * There is a two level cache. The first level generates the shader based on the provided options. @@ -35,7 +37,7 @@ class ProgramLibrary { /** * Named shader generators. * - * @type {Map} + * @type {Map} */ _generators = new Map(); @@ -83,8 +85,8 @@ class ProgramLibrary { /** * Returns a generated shader definition for the specified options. They key is used to cache the * shader definition. - * @param {import('./programs/shader-generator.js').ShaderGenerator} generator - The generator - * to use. + * + * @param {ShaderGenerator} generator - The generator to use. * @param {string} name - The unique name of the shader generator. * @param {number} key - A unique key representing the shader options. * @param {object} options - The shader options. diff --git a/src/scene/shader-lib/programs/lit-shader.js b/src/scene/shader-lib/programs/lit-shader.js index 8c1782d5861..850c3cfb88a 100644 --- a/src/scene/shader-lib/programs/lit-shader.js +++ b/src/scene/shader-lib/programs/lit-shader.js @@ -4,9 +4,6 @@ import { SEMANTIC_TEXCOORD0, SEMANTIC_TEXCOORD1, SHADERTAG_MATERIAL } from '../../../platform/graphics/constants.js'; -import { shaderChunks } from '../chunks/chunks.js'; -import { ChunkUtils } from '../chunk-utils.js'; - import { BLEND_ADDITIVEALPHA, BLEND_NORMAL, BLEND_PREMULTIPLIED, FRESNEL_SCHLICK, @@ -18,15 +15,21 @@ import { SPECOCC_AO, SPECOCC_GLOSSDEPENDENT, SPRITE_RENDERMODE_SLICED, SPRITE_RENDERMODE_TILED, shadowTypeToString, SHADER_PREPASS_VELOCITY } from '../../constants.js'; +import { shaderChunks } from '../chunks/chunks.js'; +import { ChunkUtils } from '../chunk-utils.js'; import { LightsBuffer } from '../../lighting/lights-buffer.js'; import { ShaderPass } from '../../shader-pass.js'; - import { validateUserChunks } from '../chunks/chunk-validation.js'; import { ShaderUtils } from '../../../platform/graphics/shader-utils.js'; import { ChunkBuilder } from '../chunk-builder.js'; import { ShaderGenerator } from './shader-generator.js'; import { Debug } from '../../../core/debug.js'; +/** + * @import { GraphicsDevice } from '../../../platform/graphics/graphics-device.js' + * @import { LitShaderOptions } from './lit-shader-options.js' + */ + const builtinAttributes = { vertex_normal: SEMANTIC_NORMAL, vertex_tangent: SEMANTIC_TANGENT, @@ -51,10 +54,8 @@ const builtinVaryings = { class LitShader { /** - * @param {import('../../../platform/graphics/graphics-device.js').GraphicsDevice} device - The - * graphics device. - * @param {import('./lit-shader-options.js').LitShaderOptions} options - The - * lit options. + * @param {GraphicsDevice} device - The graphics device. + * @param {LitShaderOptions} options - The lit options. */ constructor(device, options) { this.device = device; diff --git a/src/scene/shader-lib/programs/lit.js b/src/scene/shader-lib/programs/lit.js index 4446146c891..84c166678de 100644 --- a/src/scene/shader-lib/programs/lit.js +++ b/src/scene/shader-lib/programs/lit.js @@ -3,6 +3,10 @@ import { LitShader } from './lit-shader.js'; import { LitOptionsUtils } from './lit-options-utils.js'; import { ShaderGenerator } from './shader-generator.js'; +/** + * @import { GraphicsDevice } from '../../../platform/graphics/graphics-device.js' + */ + const dummyUvs = [0, 1, 2, 3, 4, 5, 6, 7]; class ShaderGeneratorLit extends ShaderGenerator { @@ -18,8 +22,7 @@ class ShaderGeneratorLit extends ShaderGenerator { } /** - * @param {import('../../../platform/graphics/graphics-device.js').GraphicsDevice} device - The - * graphics device. + * @param {GraphicsDevice} device - The graphics device. * @param {object} options - The options to be passed to the backend. * @returns {object} Returns the created shader definition. */ diff --git a/src/scene/shader-lib/programs/standard.js b/src/scene/shader-lib/programs/standard.js index 26e93417a96..66890e7c4aa 100644 --- a/src/scene/shader-lib/programs/standard.js +++ b/src/scene/shader-lib/programs/standard.js @@ -1,5 +1,4 @@ import { Debug } from '../../../core/debug.js'; - import { BLEND_NONE, DITHER_BAYER8, DITHER_NONE, FRESNEL_SCHLICK, SHADER_FORWARD, @@ -13,6 +12,10 @@ import { StandardMaterialOptions } from '../../materials/standard-material-optio import { LitOptionsUtils } from './lit-options-utils.js'; import { ShaderGenerator } from './shader-generator.js'; +/** + * @import { GraphicsDevice } from '../../../platform/graphics/graphics-device.js' + */ + const _matTex2D = []; const buildPropertiesList = (options) => { @@ -199,8 +202,7 @@ class ShaderGeneratorStandard extends ShaderGenerator { } /** - * @param {import('../../../platform/graphics/graphics-device.js').GraphicsDevice} device - The - * graphics device. + * @param {GraphicsDevice} device - The graphics device. * @param {StandardMaterialOptions} options - The create options. * @returns {object} Returns the created shader definition. */ diff --git a/src/scene/shader-lib/utils.js b/src/scene/shader-lib/utils.js index d5cec70be86..cb432f5c9cc 100644 --- a/src/scene/shader-lib/utils.js +++ b/src/scene/shader-lib/utils.js @@ -6,11 +6,15 @@ import { Debug } from '../../core/debug.js'; import { ShaderGenerator } from './programs/shader-generator.js'; import { SHADERLANGUAGE_WGSL } from '../../platform/graphics/constants.js'; +/** + * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js' + * @import { ShaderProcessorOptions } from '../../platform/graphics/shader-processor-options.js' + */ + /** * Create a shader from named shader chunks. * - * @param {import('../../platform/graphics/graphics-device.js').GraphicsDevice} device - The - * graphics device. + * @param {GraphicsDevice} device - The graphics device. * @param {string} vsName - The vertex shader chunk name. * @param {string} fsName - The fragment shader chunk name. * @param {boolean | Record} [useTransformFeedback] - Whether @@ -52,8 +56,7 @@ function createShader(device, vsName, fsName, useTransformFeedback = false, shad * compile on both WebGL and WebGPU. Specifically, these blocks are added, and should not be * part of provided vsCode and fsCode: shader version, shader precision, commonly used extensions. * - * @param {import('../../platform/graphics/graphics-device.js').GraphicsDevice} device - The - * graphics device. + * @param {GraphicsDevice} device - The graphics device. * @param {string} vsCode - The vertex shader code. * @param {string} fsCode - The fragment shader code. * @param {string} uniqueName - Unique name for the shader. If a shader with this name already @@ -124,8 +127,7 @@ class ShaderGeneratorPassThrough extends ShaderGenerator { * Process shader using shader processing options, utilizing cache of the ProgramLibrary * * @param {Shader} shader - The shader to be processed. - * @param {import('../../platform/graphics/shader-processor-options.js').ShaderProcessorOptions} processingOptions - - * The shader processing options. + * @param {ShaderProcessorOptions} processingOptions - The shader processing options. * @returns {Shader} The processed shader. */ function processShader(shader, processingOptions) { diff --git a/src/scene/shader-pass.js b/src/scene/shader-pass.js index f481176bd41..ec30da1ae60 100644 --- a/src/scene/shader-pass.js +++ b/src/scene/shader-pass.js @@ -1,9 +1,12 @@ import { Debug } from '../core/debug.js'; +import { DeviceCache } from '../platform/graphics/device-cache.js'; import { SHADER_FORWARD, SHADER_DEPTH, SHADER_PICK, SHADER_SHADOW, SHADER_PREPASS_VELOCITY } from './constants.js'; -import { DeviceCache } from '../platform/graphics/device-cache.js'; +/** + * @import { GraphicsDevice } from '../platform/graphics/graphics-device.js' + */ // device cache storing shader pass data per device const shaderPassDeviceCache = new DeviceCache(); @@ -110,8 +113,7 @@ class ShaderPass { /** * Get access to the shader pass instance for the specified device. * - * @param {import('../platform/graphics/graphics-device.js').GraphicsDevice} device - The - * graphics device. + * @param {GraphicsDevice} device - The graphics device. * @returns { ShaderPass } The shader pass instance for the specified device. */ static get(device) { diff --git a/src/scene/skin-instance.js b/src/scene/skin-instance.js index acaccace917..2821ae8737e 100644 --- a/src/scene/skin-instance.js +++ b/src/scene/skin-instance.js @@ -1,10 +1,15 @@ import { Debug } from '../core/debug.js'; import { math } from '../core/math/math.js'; import { Mat4 } from '../core/math/mat4.js'; - import { FILTER_NEAREST, PIXELFORMAT_RGBA32F, TEXTURELOCK_READ } from '../platform/graphics/constants.js'; import { Texture } from '../platform/graphics/texture.js'; +/** + * @import { Entity } from '../framework/entity.js' + * @import { GraphNode } from './graph-node.js' + * @import { Skin } from './skin.js' + */ + const _invMatrix = new Mat4(); /** @@ -17,7 +22,7 @@ class SkinInstance { /** * An array of nodes representing each bone in this skin instance. * - * @type {import('./graph-node.js').GraphNode[]} + * @type {GraphNode[]} */ bones; @@ -26,7 +31,7 @@ class SkinInstance { /** * Create a new SkinInstance instance. * - * @param {import('./skin.js').Skin} skin - The skin that will provide the inverse bind pose + * @param {Skin} skin - The skin that will provide the inverse bind pose * matrices to generate the final matrix palette. */ constructor(skin) { @@ -89,10 +94,9 @@ class SkinInstance { /** * Resolves skin bones to a hierarchy with the rootBone at its root. * - * @param {import('../framework/entity.js').Entity} rootBone - A reference to the entity to be used as - * the root bone. - * @param {import('../framework/entity.js').Entity} entity - Specifies the entity used if the - * bone match is not found in the hierarchy - usually the entity the render component is attached to. + * @param {Entity} rootBone - A reference to the entity to be used as the root bone. + * @param {Entity} entity - Specifies the entity used if the bone match is not found in the + * hierarchy - usually the entity the render component is attached to. * @ignore */ resolve(rootBone, entity) { @@ -104,7 +108,7 @@ class SkinInstance { const bones = []; for (let j = 0; j < skin.boneNames.length; j++) { const boneName = skin.boneNames[j]; - /** @type {import('../framework/entity.js').Entity|import('./graph-node.js').GraphNode|null} */ + /** @type {Entity|GraphNode|null} */ let bone = rootBone.findByName(boneName); if (!bone) { @@ -118,7 +122,7 @@ class SkinInstance { } /** - * @param {import('./skin.js').Skin} skin - The skin. + * @param {Skin} skin - The skin. */ initSkin(skin) { diff --git a/src/scene/skin.js b/src/scene/skin.js index 5bda7ba6add..e6e081b9681 100644 --- a/src/scene/skin.js +++ b/src/scene/skin.js @@ -1,3 +1,8 @@ +/** + * @import { GraphicsDevice } from '../platform/graphics/graphics-device.js' + * @import { Mat4 } from '../core/math/mat4.js' + */ + /** * A skin contains data about the bones in a hierarchy that drive a skinned mesh animation. * Specifically, the skin stores the bone name and inverse bind matrix and for each bone. Inverse @@ -9,9 +14,8 @@ class Skin { /** * Create a new Skin instance. * - * @param {import('../platform/graphics/graphics-device.js').GraphicsDevice} graphicsDevice - - * The graphics device used to manage this skin. - * @param {import('../core/math/mat4.js').Mat4[]} ibp - The array of inverse bind matrices. + * @param {GraphicsDevice} graphicsDevice - The graphics device used to manage this skin. + * @param {Mat4[]} ibp - The array of inverse bind matrices. * @param {string[]} boneNames - The array of bone names for the bones referenced by this skin. */ constructor(graphicsDevice, ibp, boneNames) { diff --git a/src/scene/skybox/sky-mesh.js b/src/scene/skybox/sky-mesh.js index 7224e8719b8..ca7bda4de62 100644 --- a/src/scene/skybox/sky-mesh.js +++ b/src/scene/skybox/sky-mesh.js @@ -1,6 +1,5 @@ import { CULLFACE_FRONT } from '../../platform/graphics/constants.js'; import { ShaderProcessorOptions } from '../../platform/graphics/shader-processor-options.js'; - import { LAYERID_SKYBOX } from '../constants.js'; import { Material } from '../materials/material.js'; import { MeshInstance } from '../mesh-instance.js'; @@ -8,6 +7,13 @@ import { getProgramLibrary } from '../shader-lib/get-program-library.js'; import { skybox } from '../shader-lib/programs/skybox.js'; import { SkyGeometry } from './sky-geometry.js'; +/** + * @import { GraphNode } from '../graph-node.js' + * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js' + * @import { Scene } from '../scene.js' + * @import { Texture } from '../../platform/graphics/texture.js' + */ + /** * A visual representation of the sky. */ @@ -20,11 +26,10 @@ class SkyMesh { meshInstance = null; /** - * @param {import('../../platform/graphics/graphics-device.js').GraphicsDevice} device - The - * graphics device. - * @param {import('../scene.js').Scene} scene - The scene owning the sky. - * @param {import('../graph-node.js').GraphNode} node - The graph node of the sky mesh instance. - * @param {import('../../platform/graphics/texture.js').Texture} texture - The texture of the sky. + * @param {GraphicsDevice} device - The graphics device. + * @param {Scene} scene - The scene owning the sky. + * @param {GraphNode} node - The graph node of the sky mesh instance. + * @param {Texture} texture - The texture of the sky. * @param {string} type - The type of the sky. One of the SKYMESH_* constants. */ constructor(device, scene, node, texture, type) { diff --git a/src/scene/skybox/sky.js b/src/scene/skybox/sky.js index bf78b1e4d38..604f490424e 100644 --- a/src/scene/skybox/sky.js +++ b/src/scene/skybox/sky.js @@ -3,6 +3,10 @@ import { SKYTYPE_INFINITE } from "../constants.js"; import { GraphNode } from "../graph-node.js"; import { SkyMesh } from "./sky-mesh.js"; +/** + * @import { Scene } from '../scene.js' + */ + /** * Implementation of the sky. * @@ -45,7 +49,7 @@ class Sky { /** * Constructs a new sky. * - * @param {import('../scene.js').Scene} scene - The scene owning the sky. + * @param {Scene} scene - The scene owning the sky. */ constructor(scene) { this.device = scene.device; @@ -58,7 +62,6 @@ class Sky { this.projectedSkydomeCenterId = this.device.scope.resolve('projectedSkydomeCenter'); } - applySettings(render) { this.type = render.skyType ?? SKYTYPE_INFINITE; this.node.setLocalPosition(new Vec3(render.skyMeshPosition ?? [0, 0, 0])); diff --git a/src/scene/sprite.js b/src/scene/sprite.js index 88389cc0a8c..7e07c9b4da9 100644 --- a/src/scene/sprite.js +++ b/src/scene/sprite.js @@ -1,10 +1,14 @@ import { EventHandler } from '../core/event-handler.js'; import { Vec2 } from '../core/math/vec2.js'; - import { SPRITE_RENDERMODE_SIMPLE, SPRITE_RENDERMODE_SLICED, SPRITE_RENDERMODE_TILED } from './constants.js'; import { Mesh } from './mesh.js'; import { Geometry } from './geometry/geometry.js'; +/** + * @import { GraphicsDevice } from '../platform/graphics/graphics-device.js' + * @import { TextureAtlas } from './texture-atlas.js' + */ + // normals are the same for every mesh const spriteNormals = [ 0, 0, 1, @@ -30,8 +34,7 @@ class Sprite extends EventHandler { /** * Create a new Sprite instance. * - * @param {import('../platform/graphics/graphics-device.js').GraphicsDevice} device - The - * graphics device of the application. + * @param {GraphicsDevice} device - The graphics device of the application. * @param {object} [options] - Options for creating the Sprite. * @param {number} [options.pixelsPerUnit] - The number of pixels that map to one PlayCanvas * unit. Defaults to 1. @@ -42,8 +45,7 @@ class Sprite extends EventHandler { * - {@link SPRITE_RENDERMODE_TILED} * * Defaults to {@link SPRITE_RENDERMODE_SIMPLE}. - * @param {import('./texture-atlas.js').TextureAtlas} [options.atlas] - The texture atlas. - * Defaults to null. + * @param {TextureAtlas} [options.atlas] - The texture atlas. Defaults to null. * @param {string[]} [options.frameKeys] - The keys of the frames in the sprite atlas that this * sprite is using. Defaults to null. */ @@ -99,7 +101,7 @@ class Sprite extends EventHandler { /** * Sets the texture atlas. * - * @type {import('./texture-atlas.js').TextureAtlas} + * @type {TextureAtlas} */ set atlas(value) { if (value === this._atlas) return; @@ -129,7 +131,7 @@ class Sprite extends EventHandler { /** * Gets the texture atlas. * - * @type {import('./texture-atlas.js').TextureAtlas} + * @type {TextureAtlas} */ get atlas() { return this._atlas; @@ -206,7 +208,7 @@ class Sprite extends EventHandler { /** * An array that contains a mesh for each frame. * - * @type {import('./mesh.js').Mesh[]} + * @type {Mesh[]} */ get meshes() { return this._meshes; diff --git a/src/scene/texture-atlas.js b/src/scene/texture-atlas.js index 7e7224c1350..f79cd4cdd7c 100644 --- a/src/scene/texture-atlas.js +++ b/src/scene/texture-atlas.js @@ -1,5 +1,11 @@ import { EventHandler } from '../core/event-handler.js'; +/** + * @import { Texture } from '../platform/graphics/texture.js' + * @import { Vec2 } from '../core/math/vec2.js' + * @import { Vec4 } from '../core/math/vec4.js' + */ + /** * A TextureAtlas contains a number of frames from a texture. Each frame defines a region in a * texture. The TextureAtlas is referenced by {@link Sprite}s. @@ -33,7 +39,7 @@ class TextureAtlas extends EventHandler { super(); /** - * @type {import('../platform/graphics/texture.js').Texture} + * @type {Texture} * @private */ this._texture = null; @@ -47,7 +53,7 @@ class TextureAtlas extends EventHandler { /** * Sets the texture used by the atlas. * - * @type {import('../platform/graphics/texture.js').Texture} + * @type {Texture} */ set texture(value) { this._texture = value; @@ -57,7 +63,7 @@ class TextureAtlas extends EventHandler { /** * Gets the texture used by the atlas. * - * @type {import('../platform/graphics/texture.js').Texture} + * @type {Texture} */ get texture() { return this._texture; @@ -87,12 +93,10 @@ class TextureAtlas extends EventHandler { * * @param {string} key - The key of the frame. * @param {object} data - The properties of the frame. - * @param {import('../core/math/vec4.js').Vec4} data.rect - The u, v, width, height properties - * of the frame in pixels. - * @param {import('../core/math/vec2.js').Vec2} data.pivot - The pivot of the frame - values - * are between 0-1. - * @param {import('../core/math/vec4.js').Vec4} data.border - The border of the frame for - * 9-slicing. Values are ordered as follows: left, bottom, right, top border in pixels. + * @param {Vec4} data.rect - The u, v, width, height properties of the frame in pixels. + * @param {Vec2} data.pivot - The pivot of the frame - values are between 0-1. + * @param {Vec4} data.border - The border of the frame for 9-slicing. Values are ordered as + * follows: left, bottom, right, top border in pixels. * @example * atlas.setFrame('1', { * rect: new pc.Vec4(0, 0, 128, 128), diff --git a/test/scene/materials/standard-material.test.mjs b/test/scene/materials/standard-material.test.mjs index 07d5c747367..72a5c8a2e47 100644 --- a/test/scene/materials/standard-material.test.mjs +++ b/test/scene/materials/standard-material.test.mjs @@ -130,7 +130,6 @@ describe('StandardMaterial', function () { expect(material.emissiveMapTiling.x).to.equal(1); expect(material.emissiveMapTiling.y).to.equal(1); expect(material.emissiveMapUv).to.equal(0); - expect(material.emissiveTint).to.equal(false); expect(material.emissiveVertexColor).to.equal(false); expect(material.emissiveVertexColorChannel).to.equal('rgb'); diff --git a/utils/plugins/rollup-types-fixup.mjs b/utils/plugins/rollup-types-fixup.mjs index 6d4bd7a4b9b..ab5c2d18620 100644 --- a/utils/plugins/rollup-types-fixup.mjs +++ b/utils/plugins/rollup-types-fixup.mjs @@ -79,7 +79,6 @@ const STANDARD_MAT_PROPS = [ ['emissiveMapRotation', 'number'], ['emissiveMapTiling', 'Vec2'], ['emissiveMapUv', 'number'], - ['emissiveTint', 'boolean'], ['emissiveVertexColor', 'boolean'], ['emissiveVertexColorChannel', 'string'], ['enableGGXSpecular', 'boolean'],