From 4f14ee0d582dfb14d300abfa85265f4dce428666 Mon Sep 17 00:00:00 2001 From: Samuel Rigaud Date: Mon, 13 Jan 2025 10:02:38 -0500 Subject: [PATCH] Docs: improve Promise typing --- src/nodes/code/ScriptableNode.js | 2 +- src/renderers/common/Pipelines.js | 2 +- src/renderers/common/Renderer.js | 4 +- src/renderers/common/extras/PMREMGenerator.js | 42 +++++++++++++++++++ src/renderers/webgpu/WebGPUBackend.js | 1 + 5 files changed, 47 insertions(+), 4 deletions(-) diff --git a/src/nodes/code/ScriptableNode.js b/src/nodes/code/ScriptableNode.js index e2ad49d0ea27c1..23bd6cbc69dc1d 100644 --- a/src/nodes/code/ScriptableNode.js +++ b/src/nodes/code/ScriptableNode.js @@ -416,7 +416,7 @@ class ScriptableNode extends Node { * * @param {String} name - The function name. * @param {...Any} params - A list of parameters. - * @return {Any} The result of the function call. + * @return {Promise} The result of the function call. */ async callAsync( name, ...params ) { diff --git a/src/renderers/common/Pipelines.js b/src/renderers/common/Pipelines.js index e1b12907418498..7da76e51af61e9 100644 --- a/src/renderers/common/Pipelines.js +++ b/src/renderers/common/Pipelines.js @@ -343,7 +343,7 @@ class Pipelines extends DataMap { * @param {ProgrammableStage} stageVertex - The programmable stage representing the vertex shader. * @param {ProgrammableStage} stageFragment - The programmable stage representing the fragment shader. * @param {String} cacheKey - The cache key. - * @param {Array} promises - An array of compilation promises which is only relevant in context of `Renderer.compileAsync()`. + * @param {Array?} promises - An array of compilation promises which is only relevant in context of `Renderer.compileAsync()`. * @return {ComputePipeline} The compute pipeline. */ _getRenderPipeline( renderObject, stageVertex, stageFragment, cacheKey, promises ) { diff --git a/src/renderers/common/Renderer.js b/src/renderers/common/Renderer.js index 4da2b2545ca496..05761ea21360c0 100644 --- a/src/renderers/common/Renderer.js +++ b/src/renderers/common/Renderer.js @@ -795,7 +795,7 @@ class Renderer { * @param {Object3D} scene - The scene or 3D object to precompile. * @param {Camera} camera - The camera that is used to render the scene. * @param {Scene} targetScene - If the first argument is a 3D object, this parameter must represent the scene the 3D object is going to be added. - * @return {Promise} A Promise that resolves when the compile has been finished. + * @return {Promise>} A Promise that resolves when the compile has been finished. */ async compileAsync( scene, camera, targetScene = null ) { @@ -2187,7 +2187,7 @@ class Renderer { * * @async * @param {Node|Array} computeNodes - The compute node(s). - * @return {Promise?} A Promise that resolve when the compute has finished. + * @return {Promise} A Promise that resolve when the compute has finished. */ async computeAsync( computeNodes ) { diff --git a/src/renderers/common/extras/PMREMGenerator.js b/src/renderers/common/extras/PMREMGenerator.js index 1f9d70a5b4e303..07d4c53dfeb8c0 100644 --- a/src/renderers/common/extras/PMREMGenerator.js +++ b/src/renderers/common/extras/PMREMGenerator.js @@ -135,6 +135,7 @@ class PMREMGenerator { * @param {Number} [far=100] - The far plane distance. * @param {RenderTarget?} [renderTarget=null] - The render target to use. * @return {RenderTarget} The resulting PMREM. + * @see fromSceneAsync */ fromScene( scene, sigma = 0, near = 0.1, far = 100, renderTarget = null ) { @@ -175,6 +176,21 @@ class PMREMGenerator { } + /** + * Generates a PMREM from a supplied Scene, which can be faster than using an + * image if networking bandwidth is low. Optional sigma specifies a blur radius + * in radians to be applied to the scene before PMREM generation. Optional near + * and far planes ensure the scene is rendered in its entirety (the cubeCamera + * is placed at the origin). + * + * @param {Scene} scene - The scene to be captured. + * @param {Number} [sigma=0] - The blur radius in radians. + * @param {Number} [near=0.1] - The near plane distance. + * @param {Number} [far=100] - The far plane distance. + * @param {RenderTarget?} [renderTarget=null] - The render target to use. + * @return {Promise} The resulting PMREM. + * @see fromScene + */ async fromSceneAsync( scene, sigma = 0, near = 0.1, far = 100, renderTarget = null ) { if ( this._hasInitialized === false ) await this._renderer.init(); @@ -191,6 +207,7 @@ class PMREMGenerator { * @param {Texture} equirectangular - The equirectangular texture to be converted. * @param {RenderTarget?} [renderTarget=null] - The render target to use. * @return {RenderTarget} The resulting PMREM. + * @see fromEquirectangularAsync */ fromEquirectangular( equirectangular, renderTarget = null ) { @@ -212,6 +229,16 @@ class PMREMGenerator { } + /** + * Generates a PMREM from an equirectangular texture, which can be either LDR + * or HDR. The ideal input image size is 1k (1024 x 512), + * as this matches best with the 256 x 256 cubemap output. + * + * @param {Texture} equirectangular - The equirectangular texture to be converted. + * @param {RenderTarget?} [renderTarget=null] - The render target to use. + * @return {Promise} The resulting PMREM. + * @see fromEquirectangular + */ async fromEquirectangularAsync( equirectangular, renderTarget = null ) { if ( this._hasInitialized === false ) await this._renderer.init(); @@ -228,6 +255,7 @@ class PMREMGenerator { * @param {Texture} cubemap - The cubemap texture to be converted. * @param {RenderTarget?} [renderTarget=null] - The render target to use. * @return {RenderTarget} The resulting PMREM. + * @see fromCubemapAsync */ fromCubemap( cubemap, renderTarget = null ) { @@ -249,6 +277,16 @@ class PMREMGenerator { } + /** + * Generates a PMREM from an cubemap texture, which can be either LDR + * or HDR. The ideal input cube size is 256 x 256, + * with the 256 x 256 cubemap output. + * + * @param {Texture} cubemap - The cubemap texture to be converted. + * @param {RenderTarget?} [renderTarget=null] - The render target to use. + * @return {Promise} The resulting PMREM. + * @see fromCubemap + */ async fromCubemapAsync( cubemap, renderTarget = null ) { if ( this._hasInitialized === false ) await this._renderer.init(); @@ -260,6 +298,8 @@ class PMREMGenerator { /** * Pre-compiles the cubemap shader. You can get faster start-up by invoking this method during * your texture's network fetch for increased concurrency. + * + * @returns {Promise} */ async compileCubemapShader() { @@ -275,6 +315,8 @@ class PMREMGenerator { /** * Pre-compiles the equirectangular shader. You can get faster start-up by invoking this method during * your texture's network fetch for increased concurrency. + * + * @returns {Promise} */ async compileEquirectangularShader() { diff --git a/src/renderers/webgpu/WebGPUBackend.js b/src/renderers/webgpu/WebGPUBackend.js index b7b00ae9a8d7d0..05428ced1f7549 100644 --- a/src/renderers/webgpu/WebGPUBackend.js +++ b/src/renderers/webgpu/WebGPUBackend.js @@ -764,6 +764,7 @@ class WebGPUBackend extends Backend { * * @async * @param {RenderContext} renderContext - The render context. + * @return {Promise} A Promise that resolves when the occlusion query results have been processed. */ async resolveOccludedAsync( renderContext ) {