Renderer: Deprecate `renderAsync()`. (#32022)

* Renderer: Deprecate `renderAsync()`.

* Examples: Clean up.

* Playground: Fix PreviewEditor.

* Renderer: Improve comment.

* Renderer: Use `Error` instead of error log.

* Update deprecation version.

examples/webgpu_compute_texture.html

@@ -40,10 +40,9 @@
 
 			let camera, scene, renderer;
 
-			init();
-			render();
+			init().then( render );
 
-			function init() {
+			async function init() {
 
 				if ( WebGPU.isAvailable() === false ) {
 
@@ -108,6 +107,8 @@
 				renderer.setSize( window.innerWidth, window.innerHeight );
 				document.body.appendChild( renderer.domElement );
 
+				await renderer.init();
+
 				// compute texture
 				renderer.computeAsync( computeNode );
 
@@ -134,7 +135,7 @@
 
 			function render() {
 
-				renderer.renderAsync( scene, camera );
+				renderer.render( scene, camera );
 
 			}
 

examples/webgpu_custom_fog_background.html

@@ -58,6 +58,7 @@
 				renderer = new THREE.WebGPURenderer( { antialias: true } );
 				renderer.setPixelRatio( window.devicePixelRatio );
 				renderer.setSize( window.innerWidth, window.innerHeight );
+				renderer.setAnimationLoop( animate );
 				renderer.toneMapping = THREE.NoToneMapping; // apply tone mapping in post processing, instead
 				document.body.appendChild( renderer.domElement );
 
@@ -91,7 +92,6 @@
 					.load( 'royal_esplanade_1k.hdr', function ( texture ) {
 
 						texture.mapping = THREE.EquirectangularReflectionMapping;
-
 						scene.environment = texture;
 
 						// model
@@ -101,8 +101,6 @@
 
 							scene.add( gltf.scene );
 
-							render();
-
 						} );
 
 					} );
@@ -114,7 +112,6 @@
 				controls.maxDistance = 5;
 				controls.target.set( 0, - 0.1, - 0.2 );
 				controls.update();
-				controls.addEventListener( 'change', render ); // use if there is no animation loop
 
 				window.addEventListener( 'resize', onWindowResize );
 
@@ -127,15 +124,13 @@
 
 				renderer.setSize( window.innerWidth, window.innerHeight );
 
-				render();
-
 			}
 
 			//
 
-			function render() {
+			function animate() {
 
-				postProcessing.renderAsync();
+				postProcessing.render();
 
 			}
 

examples/webgpu_loader_gltf.html

@@ -44,10 +44,9 @@
 
 			let camera, scene, renderer;
 
-			init();
-			render();
+			init().then( render );
 
-			function init() {
+			async function init() {
 
 				const container = document.createElement( 'div' );
 				document.body.appendChild( container );
@@ -90,6 +89,8 @@
 				renderer.toneMapping = THREE.ACESFilmicToneMapping;
 				container.appendChild( renderer.domElement );
 
+				await renderer.init();
+
 				const controls = new OrbitControls( camera, renderer.domElement );
 				controls.addEventListener( 'change', render ); // use if there is no animation loop
 				controls.minDistance = 2;
@@ -116,7 +117,7 @@
 
 			function render() {
 
-				renderer.renderAsync( scene, camera );
+				renderer.render( scene, camera );
 
 			}
 

examples/webgpu_loader_gltf_anisotropy.html

@@ -51,7 +51,7 @@
 				renderer = new THREE.WebGPURenderer( { antialias: true } );
 				renderer.setPixelRatio( window.devicePixelRatio );
 				renderer.setSize( window.innerWidth, window.innerHeight );
-				renderer.setAnimationLoop( render );
+				renderer.setAnimationLoop( animate );
 				renderer.toneMapping = THREE.ACESFilmicToneMapping;
 				renderer.toneMappingExposure = 1.35;
 				document.body.appendChild( renderer.domElement );
@@ -65,7 +65,6 @@
 				controls.target.set( 0, - 0.08, 0.11 );
 				controls.minDistance = 0.1;
 				controls.maxDistance = 2;
-				controls.addEventListener( 'change', render );
 				controls.update();
 
 				const hdrLoader = new HDRLoader().setPath( 'textures/equirectangular/' );
@@ -102,9 +101,9 @@
 
 			}
 
-			function render() {
+			function animate() {
 
-				renderer.renderAsync( scene, camera );
+				renderer.render( scene, camera );
 
 			}
 

examples/webgpu_materials_matcap.html

@@ -57,7 +57,7 @@
 				renderer = new THREE.WebGPURenderer( { antialias: true } );
 				renderer.setPixelRatio( window.devicePixelRatio );
 				renderer.setSize( window.innerWidth, window.innerHeight );
-				renderer.setAnimationLoop( render );
+				renderer.setAnimationLoop( animate );
 				renderer.inspector = new Inspector();
 				document.body.appendChild( renderer.domElement );
 
@@ -74,24 +74,20 @@
 
 				// controls
 				const controls = new OrbitControls( camera, renderer.domElement );
-				controls.addEventListener( 'change', render );
 				controls.enableZoom = false;
 				controls.enablePan = false;
 
-				// manager
-				const manager = new THREE.LoadingManager( render );
-
 				// matcap
-				const loaderEXR = new EXRLoader( manager );
+				const loaderEXR = new EXRLoader();
 				const matcap = loaderEXR.load( 'textures/matcaps/040full.exr' );
 
 				// normalmap
-				const loader = new THREE.TextureLoader( manager );
+				const loader = new THREE.TextureLoader();
 
 				const normalmap = loader.load( 'models/gltf/LeePerrySmith/Infinite-Level_02_Tangent_SmoothUV.jpg' );
 
 				// model
-				new GLTFLoader( manager ).load( 'models/gltf/LeePerrySmith/LeePerrySmith.glb', function ( gltf ) {
+				new GLTFLoader().load( 'models/gltf/LeePerrySmith/LeePerrySmith.glb', function ( gltf ) {
 
 					mesh = gltf.scene.children[ 0 ];
 					mesh.position.y = - 0.25;
@@ -143,9 +139,9 @@
 
 			}
 
-			function render() {
+			function animate() {
 
-				renderer.renderAsync( scene, camera );
+				renderer.render( scene, camera );
 
 			}
 

examples/webgpu_materials_transmission.html

@@ -68,7 +68,6 @@
 					hdrEquirect.mapping = THREE.EquirectangularReflectionMapping;
 
 					init();
-					render();
 
 				} );
 
@@ -77,7 +76,7 @@
 				renderer = new THREE.WebGPURenderer( { antialias: true } );
 				renderer.setPixelRatio( window.devicePixelRatio );
 				renderer.setSize( window.innerWidth, window.innerHeight );
-				renderer.setAnimationLoop( render );
+				renderer.setAnimationLoop( animate );
 				renderer.inspector = new Inspector();
 				document.body.appendChild( renderer.domElement );
 
@@ -245,9 +244,9 @@
 
 			}
 
-			function render() {
+			function animate() {
 
-				renderer.renderAsync( scene, camera );
+				renderer.render( scene, camera );
 
 			}
 

examples/webgpu_storage_buffer.html

@@ -185,6 +185,8 @@
 				renderer.setPixelRatio( window.devicePixelRatio );
 				renderer.setSize( window.innerWidth / 2, window.innerHeight );
 
+				await renderer.init();
+
 				document.body.appendChild( renderer.domElement );
 				renderer.domElement.style.position = 'absolute';
 				renderer.domElement.style.top = '0';
@@ -216,7 +218,7 @@
 					renderer.info.reset();
 
 					await renderer.computeAsync( compute );
-					await renderer.renderAsync( scene, camera );
+					renderer.render( scene, camera );
 
 					renderer.resolveTimestampsAsync( THREE.TimestampQuery.COMPUTE );
 					renderer.resolveTimestampsAsync( THREE.TimestampQuery.RENDER );

examples/webgpu_texturegrad.html

@@ -100,6 +100,7 @@
 				const renderer = new THREE.WebGPURenderer( { antialias: false, forceWebGL: forceWebGL } );
 				renderer.setPixelRatio( window.devicePixelRatio );
 				renderer.setSize( window.innerWidth / 2, window.innerHeight );
+				renderer.setAnimationLoop( animate );
 
 				document.body.appendChild( renderer.domElement );
 				renderer.domElement.style.position = 'absolute';
@@ -122,15 +123,11 @@
 
 				//
 
+				function animate() {
 
-				 const animate = async function () {
-
-					await renderer.renderAsync( scene, camera );
-
+					renderer.render( scene, camera );
 			
-				};
-
-				renderer.setAnimationLoop( animate );
+				}
 
 				window.addEventListener( 'resize', onWindowResize );
 

examples/webgpu_textures_partialupdate.html

@@ -77,6 +77,7 @@
 				renderer = new THREE.WebGPURenderer( { antialias: true, forceWebGL: false } );
 				renderer.setPixelRatio( window.devicePixelRatio );
 				renderer.setSize( window.innerWidth, window.innerHeight );
+				renderer.setAnimationLoop( animate );
 
 				document.body.appendChild( renderer.domElement );
 
@@ -95,14 +96,12 @@
 
 			}
 
-			async function animate() {
-
-				requestAnimationFrame( animate );
+			function animate() {
 
 				const elapsedTime = clock.getElapsedTime();
 
 
-				await renderer.renderAsync( scene, camera );
+				renderer.render( scene, camera );
 
 
 				if ( elapsedTime - last > 0.1 ) {

playground/editors/PreviewEditor.js

@@ -161,8 +161,10 @@ export class PreviewEditor extends BaseNodeEditor {
 
 		}
 
-		await renderer.clearAsync();
-		await renderer.renderAsync( scene, camera );
+		if ( renderer.hasInitialized() === false ) await renderer.init();
+
+		renderer.clear();
+		renderer.render( scene, camera );
 
 		viewHelper.render( renderer );
 

src/renderers/common/Info.js

@@ -54,7 +54,7 @@ class Info {
 		 * @property {number} triangles - The number of rendered triangle primitives of the current frame.
 		 * @property {number} points - The number of rendered point primitives of the current frame.
 		 * @property {number} lines - The number of rendered line primitives of the current frame.
-		 * @property {number} timestamp - The timestamp of the frame when using `renderer.renderAsync()`.
+		 * @property {number} timestamp - The timestamp of the frame.
 		 */
 		this.render = {
 			calls: 0,

src/renderers/common/PostProcessing.js

@@ -3,6 +3,7 @@ import { ColorManagement } from '../../math/ColorManagement.js';
 import { vec4, renderOutput } from '../../nodes/TSL.js';
 import { NoToneMapping } from '../../constants.js';
 import QuadMesh from '../../renderers/common/QuadMesh.js';
+import { warnOnce } from '../../utils.js';
 
 /**
  * This module is responsible to manage the post processing setups in apps.
@@ -207,37 +208,14 @@ class PostProcessing {
 	 * its animation loop (not the one from the renderer).
 	 *
 	 * @async
+	 * @deprecated
 	 * @return {Promise} A Promise that resolves when the render has been finished.
 	 */
 	async renderAsync() {
 
-		this._update();
-
-		if ( this._context.onBeforePostProcessing !== null ) this._context.onBeforePostProcessing();
-
-		const renderer = this.renderer;
-
-		const toneMapping = renderer.toneMapping;
-		const outputColorSpace = renderer.outputColorSpace;
-
-		renderer.toneMapping = NoToneMapping;
-		renderer.outputColorSpace = ColorManagement.workingColorSpace;
-
-		//
+		warnOnce( 'PostProcessing: "renderAsync()" has been deprecated. Use "render()" and "await renderer.init();" when creating the renderer.' ); // @deprecated r181
 
-		const currentXR = renderer.xr.enabled;
-		renderer.xr.enabled = false;
-
-		await this._quadMesh.renderAsync( renderer );
-
-		renderer.xr.enabled = currentXR;
-
-		//
-
-		renderer.toneMapping = toneMapping;
-		renderer.outputColorSpace = outputColorSpace;
-
-		if ( this._context.onAfterPostProcessing !== null ) this._context.onAfterPostProcessing();
+		this.render();
 
 	}
 

src/renderers/common/QuadMesh.js

@@ -2,6 +2,7 @@ import { BufferGeometry } from '../../core/BufferGeometry.js';
 import { Float32BufferAttribute } from '../../core/BufferAttribute.js';
 import { Mesh } from '../../objects/Mesh.js';
 import { OrthographicCamera } from '../../cameras/OrthographicCamera.js';
+import { warnOnce } from '../../utils.js';
 
 const _camera = /*@__PURE__*/ new OrthographicCamera( - 1, 1, 1, - 1, 0, 1 );
 
@@ -81,12 +82,15 @@ class QuadMesh extends Mesh {
 	 * Async version of `render()`.
 	 *
 	 * @async
+	 * @deprecated
 	 * @param {Renderer} renderer - The renderer.
 	 * @return {Promise} A Promise that resolves when the render has been finished.
 	 */
 	async renderAsync( renderer ) {
 
-		return renderer.renderAsync( this, _camera );
+		warnOnce( 'QuadMesh: "renderAsync()" has been deprecated. Use "render()" and "await renderer.init();" when creating the renderer.' ); // @deprecated r181
+
+		renderer.render( this, _camera );
 
 	}
 

src/renderers/common/Renderer.js

@@ -35,7 +35,7 @@ import { DoubleSide, BackSide, FrontSide, SRGBColorSpace, NoToneMapping, LinearF
 import { float, vec3, vec4 } from '../../nodes/tsl/TSLCore.js';
 import { reference } from '../../nodes/accessors/ReferenceNode.js';
 import { highpModelNormalViewMatrix, highpModelViewMatrix } from '../../nodes/accessors/ModelNode.js';
-import { error, warn } from '../../utils.js';
+import { error, warn, warnOnce } from '../../utils.js';
 
 const _scene = /*@__PURE__*/ new Scene();
 const _drawingBufferSize = /*@__PURE__*/ new Vector2();
@@ -971,15 +971,16 @@ class Renderer {
 	 * Renders the scene in an async fashion.
 	 *
 	 * @async
+	 * @deprecated
 	 * @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.
 	 */
 	async renderAsync( scene, camera ) {
 
-		if ( this._initialized === false ) await this.init();
+		warnOnce( 'Renderer: "renderAsync()" has been deprecated. Use "render()" and "await renderer.init();" when creating the renderer.' ); // @deprecated r181
 
-		this._renderScene( scene, camera );
+		this.render( scene, camera );
 
 	}
 
@@ -1203,23 +1204,24 @@ class Renderer {
 
 	/**
 	 * Renders the scene or 3D object with the given camera. This method can only be called
-	 * if the renderer has been initialized.
+	 * if the renderer has been initialized. When using `render()` inside an animation loop,
+	 * it's guaranteed the renderer will be initialized. The animation loop must be defined
+	 * with {@link Renderer#setAnimationLoop} though.
+	 *
+	 * For all other use cases (like when using on-demand rendering), you must call
+	 * {@link Renderer#init} before rendering.
 	 *
 	 * The target of the method is the default framebuffer (meaning the canvas)
 	 * or alternatively a render target when specified via `setRenderTarget()`.
 	 *
 	 * @param {Object3D} scene - The scene or 3D object to render.
 	 * @param {Camera} camera - The camera to render the scene with.
-	 * @return {?Promise} A Promise that resolve when the scene has been rendered.
-	 * Only returned when the renderer has not been initialized.
 	 */
 	render( scene, camera ) {
 
 		if ( this._initialized === false ) {
 
-			warn( 'Renderer: .render() called before the backend is initialized. Try using .renderAsync() instead.' );
-
-			return this.renderAsync( scene, camera );
+			throw new Error( 'Renderer: .render() called before the backend is initialized. Use "await renderer.init();" before rendering.' );
 
 		}