OrbitControls: Introduce listenToPointerEvents().

docs/examples/en/controls/OrbitControls.html

@@ -28,7 +28,8 @@ <h2>Code Example</h2>
 
 		const camera = new THREE.PerspectiveCamera( 45, window.innerWidth / window.innerHeight, 1, 10000 );
 
-		const controls = new OrbitControls( camera, renderer.domElement );
+		const controls = new OrbitControls( camera );
+		controls.listenToPointerEvents( renderer.domElement );
 
 		//controls.update() must be called after any manual changes to the camera's transform
 		camera.position.set( 0, 20, 100 );
@@ -288,6 +289,11 @@ <h3>[method:void listenToKeyEvents] ( [param:HTMLDOMElement domElement] )</h3>
 			Adds key event listeners to the given DOM element. *window* is a recommended argument for using this method.
 		</p>
 
+		<h3>[method:void listenToPointerEvents] ( [param:HTMLDOMElement domElement] )</h3>
+		<p>
+			Adds pointer event listeners to the given DOM element. *renderer.domElement* is a recommended argument for using this method.
+		</p>
+
 		<h3>[method:null reset] ()</h3>
 		<p>
 			Reset the controls to their state from either the last time the [page:.saveState] was called, or the initial state.

docs/examples/ko/controls/OrbitControls.html

@@ -27,7 +27,8 @@ <h2>코드 예시</h2>
 
 		const camera = new THREE.PerspectiveCamera( 45, window.innerWidth / window.innerHeight, 1, 10000 );
 
-		const controls = new OrbitControls( camera, renderer.domElement );
+		const controls = new OrbitControls( camera );
+		controls.listenToPointerEvents( renderer.domElement );
 
 		//controls.update()는 카메라 변환설정을 수동으로 변경한 후에 호출해야 합니다.
 		camera.position.set( 0, 20, 100 );
@@ -283,6 +284,11 @@ <h3>[method:void listenToKeyEvents] ( [param:HTMLDOMElement domElement] )</h3>
 			Adds key event listeners to the given DOM element. *window* is a recommended argument for using this method.
 		</p>
 
+		<h3>[method:void listenToPointerEvents] ( [param:HTMLDOMElement domElement] )</h3>
+		<p>
+			Adds pointer event listeners to the given DOM element. *renderer.domElement* is a recommended argument for using this method.
+		</p>
+
 		<h3>[method:null reset] ()</h3>
 		<p>
 			컨트롤이 마지막으로 호출된 [page:.saveState] 시점으로 돌리거나, 초기상태로 재설정합니다.

docs/examples/zh/controls/OrbitControls.html

@@ -28,7 +28,8 @@ <h2>代码示例</h2>
 
 		const camera = new THREE.PerspectiveCamera( 45, window.innerWidth / window.innerHeight, 1, 10000 );
 
-		const controls = new OrbitControls( camera, renderer.domElement );
+		const controls = new OrbitControls( camera );
+		controls.listenToPointerEvents( renderer.domElement );
 
 		//controls.update() must be called after any manual changes to the camera's transform
 		camera.position.set( 0, 20, 100 );
@@ -285,6 +286,11 @@ <h3>[method:void listenToKeyEvents] ( [param:HTMLDOMElement domElement] )</h3>
 			为指定的DOM元素添加按键监听。推荐将window作为指定的DOM元素。
 		</p>
 
+		<h3>[method:void listenToPointerEvents] ( [param:HTMLDOMElement domElement] )</h3>
+		<p>
+			Adds pointer event listeners to the given DOM element. *renderer.domElement* is a recommended argument for using this method.
+		</p>
+
 		<h3>[method:null reset] ()</h3>
 		<p>
 			将控制器重置为上次调用[page:.saveState]时的状态，或者初始状态。

examples/css2d_label.html

@@ -104,7 +104,8 @@
 				labelRenderer.domElement.style.top = '0px';
 				document.body.appendChild( labelRenderer.domElement );
 
-				const controls = new OrbitControls( camera, labelRenderer.domElement );
+				const controls = new OrbitControls( camera );
+				controls.listenToPointerEvents( labelRenderer.domElement );
 				controls.minDistance = 5;
 				controls.maxDistance = 100;
 

examples/css3d_orthographic.html

@@ -92,7 +92,8 @@
 				renderer2.domElement.style.top = 0;
 				document.body.appendChild( renderer2.domElement );
 
-				const controls = new OrbitControls( camera, renderer2.domElement );
+				const controls = new OrbitControls( camera );
+				controls.listenToPointerEvents( renderer2.domElement );
 				controls.minZoom = 0.5;
 				controls.maxZoom = 2;
 

examples/js/controls/OrbitControls.js

@@ -7,11 +7,8 @@
 
 THREE.OrbitControls = function ( object, domElement ) {
 
-	if ( domElement === undefined ) console.warn( 'THREE.OrbitControls: The second parameter "domElement" is now mandatory.' );
-	if ( domElement === document ) console.error( 'THREE.OrbitControls: "document" should not be used as the target "domElement". Please use "renderer.domElement" instead.' );
-
 	this.object = object;
-	this.domElement = domElement;
+	this.domElement = null;
 
 	// Set to false to disable this control
 	this.enabled = true;
@@ -102,6 +99,21 @@ THREE.OrbitControls = function ( object, domElement ) {
 
 	};
 
+	this.listenToPointerEvents = function ( domElement ) {
+
+		if ( domElement === document ) console.error( 'THREE.OrbitControls: "document" should not be used as the target "domElement". Please use "renderer.domElement" instead.' );
+
+		domElement.addEventListener( 'contextmenu', onContextMenu );
+		domElement.addEventListener( 'pointerdown', onPointerDown );
+		domElement.addEventListener( 'wheel', onMouseWheel );
+		domElement.addEventListener( 'touchstart', onTouchStart );
+		domElement.addEventListener( 'touchend', onTouchEnd );
+		domElement.addEventListener( 'touchmove', onTouchMove );
+
+		this.domElement = domElement;
+
+	};
+
 	this.saveState = function () {
 
 		scope.target0.copy( scope.target );
@@ -1172,14 +1184,12 @@ THREE.OrbitControls = function ( object, domElement ) {
 
 	//
 
-	scope.domElement.addEventListener( 'contextmenu', onContextMenu );
+	if ( domElement !== undefined ) {
 
-	scope.domElement.addEventListener( 'pointerdown', onPointerDown );
-	scope.domElement.addEventListener( 'wheel', onMouseWheel );
+		console.warn( 'THREE.OrbitControls: The domElement constructor param has been deprecated. Use .listenToPointerEvents() instead.' );
+		this.listenToPointerEvents( domElement );
 
-	scope.domElement.addEventListener( 'touchstart', onTouchStart );
-	scope.domElement.addEventListener( 'touchend', onTouchEnd );
-	scope.domElement.addEventListener( 'touchmove', onTouchMove );
+	}
 
 	// force an update at start
 

examples/jsm/controls/OrbitControls.js

@@ -17,11 +17,8 @@ import {
 
 var OrbitControls = function ( object, domElement ) {
 
-	if ( domElement === undefined ) console.warn( 'THREE.OrbitControls: The second parameter "domElement" is now mandatory.' );
-	if ( domElement === document ) console.error( 'THREE.OrbitControls: "document" should not be used as the target "domElement". Please use "renderer.domElement" instead.' );
-
 	this.object = object;
-	this.domElement = domElement;
+	this.domElement = null;
 
 	// Set to false to disable this control
 	this.enabled = true;
@@ -112,6 +109,21 @@ var OrbitControls = function ( object, domElement ) {
 
 	};
 
+	this.listenToPointerEvents = function ( domElement ) {
+
+		if ( domElement === document ) console.error( 'THREE.OrbitControls: "document" should not be used as the target "domElement". Please use "renderer.domElement" instead.' );
+
+		domElement.addEventListener( 'contextmenu', onContextMenu );
+		domElement.addEventListener( 'pointerdown', onPointerDown );
+		domElement.addEventListener( 'wheel', onMouseWheel );
+		domElement.addEventListener( 'touchstart', onTouchStart );
+		domElement.addEventListener( 'touchend', onTouchEnd );
+		domElement.addEventListener( 'touchmove', onTouchMove );
+
+		this.domElement = domElement;
+
+	};
+
 	this.saveState = function () {
 
 		scope.target0.copy( scope.target );
@@ -1182,14 +1194,12 @@ var OrbitControls = function ( object, domElement ) {
 
 	//
 
-	scope.domElement.addEventListener( 'contextmenu', onContextMenu );
+	if ( domElement !== undefined ) {
 
-	scope.domElement.addEventListener( 'pointerdown', onPointerDown );
-	scope.domElement.addEventListener( 'wheel', onMouseWheel );
+		console.warn( 'THREE.OrbitControls: The domElement constructor param has been deprecated. Use .listenToPointerEvents() instead.' );
+		this.listenToPointerEvents( domElement );
 
-	scope.domElement.addEventListener( 'touchstart', onTouchStart );
-	scope.domElement.addEventListener( 'touchend', onTouchEnd );
-	scope.domElement.addEventListener( 'touchmove', onTouchMove );
+	}
 
 	// force an update at start
 

examples/misc_controls_orbit.html

@@ -50,7 +50,8 @@
 
 				// controls
 
-				controls = new OrbitControls( camera, renderer.domElement );
+				controls = new OrbitControls( camera );
+				controls.listenToPointerEvents( renderer.domElement ); // mandatory
 				controls.listenToKeyEvents( window ); // optional
 
 				//controls.addEventListener( 'change', render ); // call this only in static scenes (i.e., if there is no animation loop)

examples/misc_controls_transform.html

@@ -57,7 +57,8 @@
 				const geometry = new THREE.BoxGeometry( 200, 200, 200 );
 				const material = new THREE.MeshLambertMaterial( { map: texture, transparent: true } );
 
-				orbit = new OrbitControls( currentCamera, renderer.domElement );
+				orbit = new OrbitControls( currentCamera );
+				orbit.listenToPointerEvents( renderer.domElement );
 				orbit.update();
 				orbit.addEventListener( 'change', render );
 

examples/misc_exporter_collada.html

@@ -80,7 +80,8 @@
 				window.addEventListener( 'resize', onWindowResize );
 
 				// CONTROLS
-				cameraControls = new OrbitControls( camera, renderer.domElement );
+				cameraControls = new OrbitControls( camera );
+				cameraControls.listenToPointerEvents( renderer.domElement );
 				cameraControls.addEventListener( 'change', render );
 
 				// TEXTURE MAP

examples/misc_exporter_draco.html

@@ -98,7 +98,8 @@
 
 				//
 
-				const controls = new OrbitControls( camera, renderer.domElement );
+				const controls = new OrbitControls( camera );
+				controls.listenToPointerEvents( renderer.domElement );
 				controls.target.set( 0, 25, 0 );
 				controls.update();
 

examples/misc_exporter_ply.html

@@ -82,7 +82,8 @@
 
 				//
 
-				const controls = new OrbitControls( camera, renderer.domElement );
+				const controls = new OrbitControls( camera );
+				controls.listenToPointerEvents( renderer.domElement );
 				controls.target.set( 0, 25, 0 );
 				controls.update();
 

examples/misc_exporter_stl.html

@@ -82,7 +82,8 @@
 
 				//
 
-				const controls = new OrbitControls( camera, renderer.domElement );
+				const controls = new OrbitControls( camera );
+				controls.listenToPointerEvents( renderer.domElement );
 				controls.target.set( 0, 25, 0 );
 				controls.update();
 

examples/physics_ammo_break.html

@@ -113,7 +113,8 @@
 			renderer.shadowMap.enabled = true;
 			container.appendChild( renderer.domElement );
 
-			controls = new OrbitControls( camera, renderer.domElement );
+			controls = new OrbitControls( camera );
+			controls.listenToPointerEvents( renderer.domElement );
 			controls.target.set( 0, 2, 0 );
 			controls.update();
 

examples/physics_ammo_cloth.html

@@ -80,7 +80,8 @@
 				renderer.shadowMap.enabled = true;
 				container.appendChild( renderer.domElement );
 
-				controls = new OrbitControls( camera, renderer.domElement );
+				controls = new OrbitControls( camera );
+				controls.listenToPointerEvents( renderer.domElement );
 				controls.target.set( 0, 2, 0 );
 				controls.update();
 

examples/physics_ammo_instancing.html

@@ -118,7 +118,8 @@
 
 				//
 
-				const controls = new OrbitControls( camera, renderer.domElement );
+				const controls = new OrbitControls( camera );
+				controls.listenToPointerEvents( renderer.domElement );
 				controls.target.y = 0.5;
 				controls.update();
 

examples/physics_ammo_rope.html

@@ -83,7 +83,8 @@
 			renderer.shadowMap.enabled = true;
 			container.appendChild( renderer.domElement );
 
-			controls = new OrbitControls( camera, renderer.domElement );
+			controls = new OrbitControls( camera );
+			controls.listenToPointerEvents( renderer.domElement );
 			controls.target.set( 0, 2, 0 );
 			controls.update();
 

examples/physics_ammo_terrain.html

@@ -102,7 +102,8 @@
 				camera.position.z = terrainDepthExtents / 2;
 				camera.lookAt( 0, 0, 0 );
 
-				const controls = new OrbitControls( camera, renderer.domElement );
+				const controls = new OrbitControls( camera );
+				controls.listenToPointerEvents( renderer.domElement );
 				controls.enableZoom = false;
 
 				const geometry = new THREE.PlaneGeometry( terrainWidthExtents, terrainDepthExtents, terrainWidth - 1, terrainDepth - 1 );

examples/physics_ammo_volume.html

@@ -87,7 +87,8 @@
 				renderer.shadowMap.enabled = true;
 				container.appendChild( renderer.domElement );
 
-				controls = new OrbitControls( camera, renderer.domElement );
+				controls = new OrbitControls( camera );
+				controls.listenToPointerEvents( renderer.domElement );
 				controls.target.set( 0, 2, 0 );
 				controls.update();
 

examples/webaudio_orientation.html

@@ -147,7 +147,8 @@
 
 			//
 
-			const controls = new OrbitControls( camera, renderer.domElement );
+			const controls = new OrbitControls( camera );
+			controls.listenToPointerEvents( renderer.domElement );
 			controls.target.set( 0, 0.1, 0 );
 			controls.update();
 			controls.minDistance = 0.5;

examples/webaudio_timing.html

@@ -136,7 +136,8 @@
 
 			//
 
-			const controls = new OrbitControls( camera, renderer.domElement );
+			const controls = new OrbitControls( camera );
+			controls.listenToPointerEvents( renderer.domElement );
 			controls.minDistance = 1;
 			controls.maxDistance = 25;
 

examples/webgl2_materials_texture3d.html

@@ -56,7 +56,8 @@
 			camera.up.set( 0, 0, 1 ); // In our data, z is up
 
 			// Create controls
-			controls = new OrbitControls( camera, renderer.domElement );
+			controls = new OrbitControls( camera );
+			controls.listenToPointerEvents( renderer.domElement );
 			controls.addEventListener( 'change', render );
 			controls.target.set( 64, 64, 128 );
 			controls.minZoom = 0.5;

examples/webgl2_volume_instancing.html

@@ -43,7 +43,8 @@
 				camera = new THREE.PerspectiveCamera( 60, window.innerWidth / window.innerHeight, 0.1, 1000 );
 				camera.position.set( 0, 0, 4 );
 
-				controls = new OrbitControls( camera, renderer.domElement );
+				controls = new OrbitControls( camera );
+				controls.listenToPointerEvents( renderer.domElement );
 				controls.autoRotate = true;
 				controls.autoRotateSpeed = - 1.0;
 				controls.enableDamping = true;

examples/webgl_animation_cloth.html

@@ -560,7 +560,8 @@
 				renderer.shadowMap.enabled = true;
 
 				// controls
-				const controls = new OrbitControls( camera, renderer.domElement );
+				const controls = new OrbitControls( camera );
+				controls.listenToPointerEvents( renderer.domElement );
 				controls.maxPolarAngle = Math.PI * 0.5;
 				controls.minDistance = 1000;
 				controls.maxDistance = 5000;

examples/webgl_animation_keyframes.html

@@ -57,7 +57,8 @@
 			const camera = new THREE.PerspectiveCamera( 40, window.innerWidth / window.innerHeight, 1, 100 );
 			camera.position.set( 5, 2, 8 );
 
-			const controls = new OrbitControls( camera, renderer.domElement );
+			const controls = new OrbitControls( camera );
+			controls.listenToPointerEvents( renderer.domElement );
 			controls.target.set( 0, 0.5, 0 );
 			controls.update();
 			controls.enablePan = false;

examples/webgl_animation_skinning_additive_blending.html

@@ -154,7 +154,8 @@
 				camera = new THREE.PerspectiveCamera( 45, window.innerWidth / window.innerHeight, 1, 100 );
 				camera.position.set( - 1, 2, 3 );
 
-				const controls = new OrbitControls( camera, renderer.domElement );
+				const controls = new OrbitControls( camera );
+				controls.listenToPointerEvents( renderer.domElement );
 				controls.enablePan = false;
 				controls.enableZoom = false;
 				controls.target.set( 0, 1, 0 );

examples/webgl_buffergeometry_compression.html

@@ -84,7 +84,8 @@
 				camera.position.y = 2 * radius;
 				camera.position.z = 2 * radius;
 
-				controls = new OrbitControls( camera, renderer.domElement );
+				controls = new OrbitControls( camera );
+				controls.listenToPointerEvents( renderer.domElement );
 
 				//