From 175a5fd3cccb6a01aaf1a7ff286b93dbe52b2942 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/Backend.js | 2 +- src/renderers/common/Pipelines.js | 2 +- src/renderers/common/PostProcessing.js | 2 +- src/renderers/common/Renderer.js | 16 +++---- src/renderers/common/extras/PMREMGenerator.js | 42 +++++++++++++++++++ src/renderers/webgl-fallback/WebGLBackend.js | 4 +- src/renderers/webgpu/WebGPUBackend.js | 9 ++-- .../webgpu/utils/WebGPUPipelineUtils.js | 2 +- 9 files changed, 62 insertions(+), 19 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/Backend.js b/src/renderers/common/Backend.js index 415545fdb8ad0a..55ded0cd82e37a 100644 --- a/src/renderers/common/Backend.js +++ b/src/renderers/common/Backend.js @@ -207,7 +207,7 @@ class Backend { * * @abstract * @param {RenderObject} renderObject - The render object. - * @param {Array} promises - An array of compilation promises which are used in `compileAsync()`. + * @param {Array>} promises - An array of compilation promises which are used in `compileAsync()`. */ createRenderPipeline( /*renderObject, promises*/ ) { } diff --git a/src/renderers/common/Pipelines.js b/src/renderers/common/Pipelines.js index e1b12907418498..c263b37485c377 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/PostProcessing.js b/src/renderers/common/PostProcessing.js index 64310d9fb9e54a..a97be26d542d26 100644 --- a/src/renderers/common/PostProcessing.js +++ b/src/renderers/common/PostProcessing.js @@ -148,7 +148,7 @@ class PostProcessing { * its animation loop (not the one from the renderer). * * @async - * @return {Promise} A Promise that resolves when the render has been finished. + * @return {Promise} A Promise that resolves when the render has been finished. */ async renderAsync() { diff --git a/src/renderers/common/Renderer.js b/src/renderers/common/Renderer.js index 4da2b2545ca496..ac3a897bdfe685 100644 --- a/src/renderers/common/Renderer.js +++ b/src/renderers/common/Renderer.js @@ -691,7 +691,7 @@ class Renderer { * Initializes the renderer so it is ready for usage. * * @async - * @return {Promise} A Promise that resolves when the renderer has been initialized. + * @return {Promise} A Promise that resolves when the renderer has been initialized. */ async init() { @@ -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 ) { @@ -927,7 +927,7 @@ class Renderer { * @async * @param {Object3D} scene - The scene or 3D object to render. * @param {Camera} camera - The camera. - * @return {Promise} A Promise that resolves when the render has been finished. + * @return {Promise} A Promise that resolves when the render has been finished. */ async renderAsync( scene, camera ) { @@ -944,7 +944,7 @@ class Renderer { * the CPU waits for the GPU to complete its operation (e.g. a compute task). * * @async - * @return {Promise} A Promise that resolves when synchronization has been finished. + * @return {Promise} A Promise that resolves when synchronization has been finished. */ async waitForGPU() { @@ -1433,7 +1433,7 @@ class Renderer { * * @async * @param {Function} callback - The application's animation loop. - * @return {Promise} A Promise that resolves when the set has been executed. + * @return {Promise} A Promise that resolves when the set has been executed. */ async setAnimationLoop( callback ) { @@ -1920,7 +1920,7 @@ class Renderer { * @param {Boolean} [color=true] - Whether the color buffer should be cleared or not. * @param {Boolean} [depth=true] - Whether the depth buffer should be cleared or not. * @param {Boolean} [stencil=true] - Whether the stencil buffer should be cleared or not. - * @return {Promise} A Promise that resolves when the clear operation has been executed. + * @return {Promise} A Promise that resolves when the clear operation has been executed. */ async clearAsync( color = true, depth = true, stencil = true ) { @@ -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 ) { @@ -2252,7 +2252,7 @@ class Renderer { * * @async * @param {Texture} texture - The texture. - * @return {Promise} A Promise that resolves when the texture has been initialized. + * @return {Promise} A Promise that resolves when the texture has been initialized. */ async initTextureAsync( texture ) { diff --git a/src/renderers/common/extras/PMREMGenerator.js b/src/renderers/common/extras/PMREMGenerator.js index 1f9d70a5b4e303..3918ecb455ece1 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/webgl-fallback/WebGLBackend.js b/src/renderers/webgl-fallback/WebGLBackend.js index 53924bc581f7e2..c3f259a4b6f610 100644 --- a/src/renderers/webgl-fallback/WebGLBackend.js +++ b/src/renderers/webgl-fallback/WebGLBackend.js @@ -276,7 +276,7 @@ class WebGLBackend extends Backend { * the CPU waits for the GPU to complete its operation (e.g. a compute task). * * @async - * @return {Promise} A Promise that resolves when synchronization has been finished. + * @return {Promise} A Promise that resolves when synchronization has been finished. */ async waitForGPU() { @@ -1247,7 +1247,7 @@ class WebGLBackend extends Backend { * Creates a render pipeline for the given render object. * * @param {RenderObject} renderObject - The render object. - * @param {Array} promises - An array of compilation promises which are used in `compileAsync()`. + * @param {Array>} promises - An array of compilation promises which are used in `compileAsync()`. */ createRenderPipeline( renderObject, promises ) { diff --git a/src/renderers/webgpu/WebGPUBackend.js b/src/renderers/webgpu/WebGPUBackend.js index b7b00ae9a8d7d0..92e9be46e9d75b 100644 --- a/src/renderers/webgpu/WebGPUBackend.js +++ b/src/renderers/webgpu/WebGPUBackend.js @@ -150,7 +150,7 @@ class WebGPUBackend extends Backend { * * @async * @param {Renderer} renderer - The renderer. - * @return {Promise} A Promise that resolves when the backend has been initialized. + * @return {Promise} A Promise that resolves when the backend has been initialized. */ async init( renderer ) { @@ -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 ) { @@ -1063,7 +1064,7 @@ class WebGPUBackend extends Backend { * the CPU waits for the GPU to complete its operation (e.g. a compute task). * * @async - * @return {Promise} A Promise that resolves when synchronization has been finished. + * @return {Promise} A Promise that resolves when synchronization has been finished. */ async waitForGPU() { @@ -1539,7 +1540,7 @@ class WebGPUBackend extends Backend { * @async * @param {RenderContext} renderContext - The render context. * @param {String} type - The render context. - * @return {Promise} A Promise that resolves when the time stamp has been computed. + * @return {Promise} A Promise that resolves when the time stamp has been computed. */ async resolveTimestampAsync( renderContext, type = 'render' ) { @@ -1617,7 +1618,7 @@ class WebGPUBackend extends Backend { * Creates a render pipeline for the given render object. * * @param {RenderObject} renderObject - The render object. - * @param {Array} promises - An array of compilation promises which are used in `compileAsync()`. + * @param {Array>} promises - An array of compilation promises which are used in `compileAsync()`. */ createRenderPipeline( renderObject, promises ) { diff --git a/src/renderers/webgpu/utils/WebGPUPipelineUtils.js b/src/renderers/webgpu/utils/WebGPUPipelineUtils.js index 5292bed51d8b1e..fbb99fb8f29cde 100644 --- a/src/renderers/webgpu/utils/WebGPUPipelineUtils.js +++ b/src/renderers/webgpu/utils/WebGPUPipelineUtils.js @@ -55,7 +55,7 @@ class WebGPUPipelineUtils { * Creates a render pipeline for the given render object. * * @param {RenderObject} renderObject - The render object. - * @param {Array} promises - An array of compilation promises which are used in `compileAsync()`. + * @param {Array>} promises - An array of compilation promises which are used in `compileAsync()`. */ createRenderPipeline( renderObject, promises ) {