Threejs TrackballControl源码解析

/**
 * @author Eberhard Graether / http://egraether.com/
 * @author Mark Lundin  / http://mark-lundin.com
 * @author Simone Manini / http://daron1337.github.io
 * @author Luca Antiga  / http://lantiga.github.io
 */
// 其实只需要该表相机的位置和朝向就能看到世界的各个方面属性，
// 位置和朝向的改变通常需要用到四元素、球面坐标、向量计算等
//
// TrackballControls需要开发者手动调用他的update才会有所改变
const THREE = require('../three/three');
export let TrackballControls = function ( object, domElement ) {

  var _this = this;
  // 这个类有六种状态
  var STATE = { NONE: - 1, ROTATE: 0, ZOOM: 1, PAN: 2, TOUCH_ROTATE: 3, TOUCH_ZOOM_PAN: 4 };

  this.object = object;// object指向相机
  this.domElement = ( domElement !== undefined ) ? domElement : document;

  // API
  //
  // 表示这个类是否起作用；如果为false鼠标交互没有效果
  this.enabled = true;
  // 设置屏幕的位置和偏移
  this.screen = { left: 0, top: 0, width: 0, height: 0 };

  this.rotateSpeed = 1.0;// 移动鼠标时场景旋转的速度
  this.zoomSpeed = 1.2; // 鼠标滚轮放大缩小的速度
  this.panSpeed = 0.3; // 上下左右移动的速度

  // 控制旋转、作坊、平移
  this.noRotate = false;
  this.noZoom = false;
  this.noPan = false;

  this.staticMoving = false;
  this.dynamicDampingFactor = 0.2;// 阻尼系数；旋转时候的阻力

  // 表示相机距离物体的最小距离和最大距离
  this.minDistance = 0;
  this.maxDistance = Infinity;

  // 定义键盘A S D的ASCII码
  this.keys = [ 65 /*A*/, 83 /*S*/, 68 /*D*/ ];

  // internals这些私有变量用来追踪相机状态

  this.target = new THREE.Vector3();// 目标点

  var EPS = 0.000001;

  var lastPosition = new THREE.Vector3(); // 相机上次的位置

  var _state = STATE.NONE,// 相机当前状态
  _prevState = STATE.NONE,// 相机上一个状态

  _eye = new THREE.Vector3(),// 眼睛的朝向

  _movePrev = new THREE.Vector2(),
  _moveCurr = new THREE.Vector2(),

  _lastAxis = new THREE.Vector3(),
  _lastAngle = 0,

  _zoomStart = new THREE.Vector2(),
  _zoomEnd = new THREE.Vector2(),

  _touchZoomDistanceStart = 0,
  _touchZoomDistanceEnd = 0,

  _panStart = new THREE.Vector2(),
  _panEnd = new THREE.Vector2();

  // for reset
  // 保存相机的最初始状态
  this.target0 = this.target.clone();
  this.position0 = this.object.position.clone();// 相机的当前位置
  this.up0 = this.object.up.clone(); // 相机的上方向

  // events

  var changeEvent = { type: 'change' };
  var startEvent = { type: 'start' };
  var endEvent = { type: 'end' };


  // methods

  this.handleResize = function () {

    if ( this.domElement === document ) {

      this.screen.left = 0;
      this.screen.top = 0;
      this.screen.width = window.innerWidth;
      this.screen.height = window.innerHeight;

    } else {

      var box = this.domElement.getBoundingClientRect();
      // adjustments come from similar code in the jquery offset() function
      var d = this.domElement.ownerDocument.documentElement;
      this.screen.left = box.left + window.pageXOffset - d.clientLeft;
      this.screen.top = box.top + window.pageYOffset - d.clientTop;
      this.screen.width = box.width;
      this.screen.height = box.height;

    }

  };

  this.handleEvent = function ( event ) {

    if ( typeof this[ event.type ] == 'function' ) {

      this[ event.type ]( event );

    }

  };

  var getMouseOnScreen = ( function () {

    var vector = new THREE.Vector2();

    return function getMouseOnScreen( pageX, pageY ) {
    // 将鼠标坐标转换成0-1，左上角为0，0右下角为1，1

      vector.set(
        ( pageX - _this.screen.left ) / _this.screen.width,
        ( pageY - _this.screen.top ) / _this.screen.height
      );

      return vector;

    };

  }() );

  var getMouseOnCircle = ( function () {

    var vector = new THREE.Vector2();

    return function getMouseOnCircle( pageX, pageY ) {
    // 将鼠标位置转换为圆坐标, 由于屏幕宽高未必一致，
    // 这里以宽度一半作为半径

      vector.set(
        ( ( pageX - _this.screen.width * 0.5 - _this.screen.left ) / ( _this.screen.width * 0.5 ) ),
        ( ( _this.screen.height + 2 * ( _this.screen.top - pageY ) ) / _this.screen.width ) // screen.width intentional
      );

      return vector;

    };

  }() );

  this.rotateCamera = ( function() {

    var axis = new THREE.Vector3(),
      quaternion = new THREE.Quaternion(),
      eyeDirection = new THREE.Vector3(),
      objectUpDirection = new THREE.Vector3(),
      objectSidewaysDirection = new THREE.Vector3(),
      moveDirection = new THREE.Vector3(),
      angle;

    // 旋转实际相当于将手势在相机屏幕上的移动转化为在一个以焦点为圆心的球上的转动
    // moveDiection就是我们要将相机eye向量的旋转方向
    // 3d中要将一个向量向另一个向量靠拢，最好使用四元数来做旋转
    return function rotateCamera() {
      // moveDirection表示以相机屏幕中心点为圆心，在相机屏幕上的一个向量
      moveDirection.set( _moveCurr.x - _movePrev.x, _moveCurr.y - _movePrev.y, 0 );
      angle = moveDirection.length();

      if ( angle ) {// 判断是否有旋转

        _eye.copy( _this.object.position ).sub( _this.target );

        eyeDirection.copy( _eye ).normalize();// 相机视线轴
        objectUpDirection.copy( _this.object.up ).normalize();// 相机up轴
        objectSidewaysDirection.crossVectors( objectUpDirection, eyeDirection ).normalize();// 相机x轴

        objectUpDirection.setLength( _moveCurr.y - _movePrev.y );// y轴移动距离
        objectSidewaysDirection.setLength( _moveCurr.x - _movePrev.x );// x轴移动距离
        // moveDiection就是我们要将相机eye向量的旋转方向
        moveDirection.copy( objectUpDirection.add( objectSidewaysDirection ) );// 计算出在相机屏幕的移动向量

        axis.crossVectors( moveDirection, _eye ).normalize();// 计算出四元数的旋转轴
        // 3d中要将一个向量向另一个向量靠拢，最好使用四元数来做旋转
        angle *= _this.rotateSpeed;// 将相机屏幕移动距离转化为角度
        quaternion.setFromAxisAngle( axis, angle );

        //对视线轴和相机up轴应用四元数旋转
        //对eye和up同时旋转保持二者相对位置关系
        _eye.applyQuaternion( quaternion );
        _this.object.up.applyQuaternion( quaternion );

        _lastAxis.copy( axis );
        _lastAngle = angle;

      } else if ( ! _this.staticMoving && _lastAngle ) {

        _lastAngle *= Math.sqrt( 1.0 - _this.dynamicDampingFactor );
        _eye.copy( _this.object.position ).sub( _this.target );
        quaternion.setFromAxisAngle( _lastAxis, _lastAngle );
        _eye.applyQuaternion( quaternion );
        _this.object.up.applyQuaternion( quaternion );

      }

      _movePrev.copy( _moveCurr );

    };

  }() );

  // 透视相机的效果是近大远小当相机离物体越近物体显示越大
  // 所以在透视情况下做放大缩小只要改变eye向量的长度
  this.zoomCamera = function () {

    var factor;

    if ( _state === STATE.TOUCH_ZOOM_PAN ) {

      factor = _touchZoomDistanceStart / _touchZoomDistanceEnd;
      _touchZoomDistanceStart = _touchZoomDistanceEnd;
      _eye.multiplyScalar( factor );

    } else {
      // 获取放到缩小的倍数，这个倍数不能小于0；当倍数小于1时为缩小，
      // 当倍数大于1时为放大
      factor = 1.0 + ( _zoomEnd.y - _zoomStart.y ) * _this.zoomSpeed;

      if ( factor !== 1.0 && factor > 0.0 ) {

        _eye.multiplyScalar( factor );

      }

      if ( _this.staticMoving ) {

        _zoomStart.copy( _zoomEnd );

      } else {
        // 做一个动画效果
        _zoomStart.y += ( _zoomEnd.y - _zoomStart.y ) * this.dynamicDampingFactor;

      }

    }

  };

  this.panCamera = ( function() {

    var mouseChange = new THREE.Vector2(),
      objectUp = new THREE.Vector3(),
      pan = new THREE.Vector3();

    return function panCamera() {
      // 屏幕左上点为0，0右下点为1，1
      // 这里得到鼠标移动的方向和距离 （二维向量）
      mouseChange.copy( _panEnd ).sub( _panStart );

      if ( mouseChange.lengthSq() ) {
        // 移动的距离跟相机距离物体的距离成正比
        // 相机距离物体越远移动距离越多；
        // 但这样做的感觉并不是很好
        mouseChange.multiplyScalar( _eye.length() * _this.panSpeed );
        // 得出相机的right轴方向和up轴方向的移动距离
        // 注意这时候的用的坐标都是世界坐标
        pan.copy( _eye ).cross( _this.object.up ).setLength( mouseChange.x );
        pan.add( objectUp.copy( _this.object.up ).setLength( mouseChange.y ) );
        // 移动相机位置和聚焦点位置，保持eye向量不变
        // 这里保证无论怎么旋转场景，当鼠标做平移操作时，
        // 场景都是平行于屏幕上下移动的，而不是相对于他们自己的模型坐标系移动
        _this.object.position.add( pan );
        _this.target.add( pan );// 如果焦点没有移动我们相当于一直在盯着一个点看

        if ( _this.staticMoving ) {// 一次性移动

          _panStart.copy( _panEnd );

        } else {// 多次缓慢移动

          _panStart.add( mouseChange.subVectors( _panEnd, _panStart ).multiplyScalar( _this.dynamicDampingFactor ) );

        }

      }

    };

  }() );

  // 相机的可视范围的远近由近景面和远景面决定；
  // 如果相机无限缩小小于近景面或物体离着相机的距离大于远景面
  // 那么相机将不会看到任何东西；所以有时候我们要控制相机的跟物体的距离
  this.checkDistances = function () {

    if ( ! _this.noZoom || ! _this.noPan ) {
      // 根据鼠标距离物体的最大最小距离来调整相机位置
      if ( _eye.lengthSq() > _this.maxDistance * _this.maxDistance ) {

        _this.object.position.addVectors( _this.target, _eye.setLength( _this.maxDistance ) );
        _zoomStart.copy( _zoomEnd );

      }

      if ( _eye.lengthSq() < _this.minDistance * _this.minDistance ) {

        _this.object.position.addVectors( _this.target, _eye.setLength( _this.minDistance ) );
        _zoomStart.copy( _zoomEnd );

      }

    }

  };

  /**
   * 这个函数会不断的更新相机位置和方向来反映相机的变化，
   * 屏幕的内容也会跟着变化
   * @return {[type]} [description]
   */
  this.update = function () {
    // 计算目标点到相机点的距离
    _eye.subVectors( _this.object.position, _this.target );
    // 更新旋转部分
    if ( ! _this.noRotate ) {

      _this.rotateCamera();

    }
    // 更新缩放部分
    if ( ! _this.noZoom ) {

      _this.zoomCamera();

    }
    // 更新上下左右移动相机部分
    if ( ! _this.noPan ) {

      _this.panCamera();

    }
    // 更新相机当前的位置
    _this.object.position.addVectors( _this.target, _eye );
    // 检查相机的位置是否在minDistance和maxDistance之间
    _this.checkDistances();
    // 从相机点看到目标点得到相机的模型矩阵
    _this.object.lookAt( _this.target );
    // 当相机位置变化后，发送一个相机状态改变的事件
    if ( lastPosition.distanceToSquared( _this.object.position ) > EPS ) {

      _this.dispatchEvent( changeEvent );
      // 保存相机当前位置
      lastPosition.copy( _this.object.position );

    }

  };

  this.reset = function () {

    _state = STATE.NONE;
    _prevState = STATE.NONE;

    _this.target.copy( _this.target0 );
    _this.object.position.copy( _this.position0 );
    _this.object.up.copy( _this.up0 );

    _eye.subVectors( _this.object.position, _this.target );

    _this.object.lookAt( _this.target );

    _this.dispatchEvent( changeEvent );

    lastPosition.copy( _this.object.position );

  };

  // listeners

  function keydown( event ) {

    if ( _this.enabled === false ) return;

    window.removeEventListener( 'keydown', keydown );

    _prevState = _state;

    if ( _state !== STATE.NONE ) {

      return;

    } else if ( event.keyCode === _this.keys[ STATE.ROTATE ] && ! _this.noRotate ) {

      _state = STATE.ROTATE;

    } else if ( event.keyCode === _this.keys[ STATE.ZOOM ] && ! _this.noZoom ) {

      _state = STATE.ZOOM;

    } else if ( event.keyCode === _this.keys[ STATE.PAN ] && ! _this.noPan ) {

      _state = STATE.PAN;

    }

  }

  function keyup( event ) {

    if ( _this.enabled === false ) return;

    _state = _prevState;

    window.addEventListener( 'keydown', keydown, false );

  }

  function mousedown( event ) {
    // 如果不启用，那么直接返回，什么事也不做
    if ( _this.enabled === false ) return;
    // 阻止默认行为、阻止冒泡
    event.preventDefault();
    event.stopPropagation();
    // 如果当前相机无状态，记录鼠标按键
    if ( _state === STATE.NONE ) {

      _state = event.button;

    }
    // 如果相机状态为旋转
    if ( _state === STATE.ROTATE && ! _this.noRotate ) {
      // 将鼠标坐标转换成为以屏幕中心点为圆心，屏幕宽度一半为半径的园坐标
      // 记录更新相机状态
      _moveCurr.copy( getMouseOnCircle( event.pageX, event.pageY ) );
      _movePrev.copy( _moveCurr );

    } else if ( _state === STATE.ZOOM && ! _this.noZoom ) {
      // 如果相机状态为缩放，将鼠标坐标转换成(0, 0)~(1, 1)之间
      // 屏幕左上角为0，0右下角为1，1
      // 记录相机状态
      _zoomStart.copy( getMouseOnScreen( event.pageX, event.pageY ) );
      _zoomEnd.copy( _zoomStart );

    } else if ( _state === STATE.PAN && ! _this.noPan ) {
      // 将鼠标坐标转换为0，0~1，1之间并记录位置状态
      _panStart.copy( getMouseOnScreen( event.pageX, event.pageY ) );
      _panEnd.copy( _panStart );

    }
    // 在鼠标按下时绑定事件
    document.addEventListener( 'mousemove', mousemove, false );
    document.addEventListener( 'mouseup', mouseup, false );

    _this.dispatchEvent( startEvent );

  }

  function mousemove( event ) {

    if ( _this.enabled === false ) return;

    event.preventDefault();
    event.stopPropagation();

    if ( _state === STATE.ROTATE && ! _this.noRotate ) {

      _movePrev.copy( _moveCurr );
      _moveCurr.copy( getMouseOnCircle( event.pageX, event.pageY ) );

    } else if ( _state === STATE.ZOOM && ! _this.noZoom ) {

      _zoomEnd.copy( getMouseOnScreen( event.pageX, event.pageY ) );

    } else if ( _state === STATE.PAN && ! _this.noPan ) {

      _panEnd.copy( getMouseOnScreen( event.pageX, event.pageY ) );

    }

  }

  function mouseup( event ) {

    if ( _this.enabled === false ) return;

    event.preventDefault();
    event.stopPropagation();

    _state = STATE.NONE;

    document.removeEventListener( 'mousemove', mousemove );
    document.removeEventListener( 'mouseup', mouseup );
    _this.dispatchEvent( endEvent );

  }

  function mousewheel( event ) {

    if ( _this.enabled === false ) return;

    event.preventDefault();
    event.stopPropagation();
    // deltaMode：返回一个数值，表示滚动的单位
    // 0表示像素，1表示行，2表示页。
    switch ( event.deltaMode ) {

                        case 2:
                                // Zoom in pages
                                _zoomStart.y -= event.deltaY * 0.025;
                                break;

      case 1:
                                // Zoom in lines
        _zoomStart.y -= event.deltaY * 0.01;
        break;

      default:
        // undefined, 0, assume pixels
        _zoomStart.y -= event.deltaY * 0.00025;
        break;

    }

    _this.dispatchEvent( startEvent );
    _this.dispatchEvent( endEvent );

  }

  function touchstart( event ) {

    if ( _this.enabled === false ) return;

    switch ( event.touches.length ) {

      case 1:
        _state = STATE.TOUCH_ROTATE;
        _moveCurr.copy( getMouseOnCircle( event.touches[ 0 ].pageX, event.touches[ 0 ].pageY ) );
        _movePrev.copy( _moveCurr );
        break;

      default: // 2 or more
        _state = STATE.TOUCH_ZOOM_PAN;
        var dx = event.touches[ 0 ].pageX - event.touches[ 1 ].pageX;
        var dy = event.touches[ 0 ].pageY - event.touches[ 1 ].pageY;
        _touchZoomDistanceEnd = _touchZoomDistanceStart = Math.sqrt( dx * dx + dy * dy );

        var x = ( event.touches[ 0 ].pageX + event.touches[ 1 ].pageX ) / 2;
        var y = ( event.touches[ 0 ].pageY + event.touches[ 1 ].pageY ) / 2;
        _panStart.copy( getMouseOnScreen( x, y ) );
        _panEnd.copy( _panStart );
        break;

    }

    _this.dispatchEvent( startEvent );

  }

  function touchmove( event ) {

    if ( _this.enabled === false ) return;

    event.preventDefault();
    event.stopPropagation();

    switch ( event.touches.length ) {

      case 1:
        _movePrev.copy( _moveCurr );
        _moveCurr.copy( getMouseOnCircle( event.touches[ 0 ].pageX, event.touches[ 0 ].pageY ) );
        break;

      default: // 2 or more
        var dx = event.touches[ 0 ].pageX - event.touches[ 1 ].pageX;
        var dy = event.touches[ 0 ].pageY - event.touches[ 1 ].pageY;
        _touchZoomDistanceEnd = Math.sqrt( dx * dx + dy * dy );

        var x = ( event.touches[ 0 ].pageX + event.touches[ 1 ].pageX ) / 2;
        var y = ( event.touches[ 0 ].pageY + event.touches[ 1 ].pageY ) / 2;
        _panEnd.copy( getMouseOnScreen( x, y ) );
        break;

    }

  }

  function touchend( event ) {

    if ( _this.enabled === false ) return;

    switch ( event.touches.length ) {

      case 0:
        _state = STATE.NONE;
        break;

      case 1:
        _state = STATE.TOUCH_ROTATE;
        _moveCurr.copy( getMouseOnCircle( event.touches[ 0 ].pageX, event.touches[ 0 ].pageY ) );
        _movePrev.copy( _moveCurr );
        break;

    }

    _this.dispatchEvent( endEvent );

  }

  function contextmenu( event ) {

    event.preventDefault();

  }

  this.dispose = function() {

    this.domElement.removeEventListener( 'contextmenu', contextmenu, false );
    this.domElement.removeEventListener( 'mousedown', mousedown, false );
    this.domElement.removeEventListener( 'wheel', mousewheel, false );

    this.domElement.removeEventListener( 'touchstart', touchstart, false );
    this.domElement.removeEventListener( 'touchend', touchend, false );
    this.domElement.removeEventListener( 'touchmove', touchmove, false );

    document.removeEventListener( 'mousemove', mousemove, false );
    document.removeEventListener( 'mouseup', mouseup, false );

    window.removeEventListener( 'keydown', keydown, false );
    window.removeEventListener( 'keyup', keyup, false );

  };

  this.domElement.addEventListener( 'contextmenu', contextmenu, false );
  this.domElement.addEventListener( 'mousedown', mousedown, false );
  this.domElement.addEventListener( 'wheel', mousewheel, false );

  this.domElement.addEventListener( 'touchstart', touchstart, false );
  this.domElement.addEventListener( 'touchend', touchend, false );
  this.domElement.addEventListener( 'touchmove', touchmove, false );

  window.addEventListener( 'keydown', keydown, false );
  window.addEventListener( 'keyup', keyup, false );

  this.handleResize();

  // force an update at start
  this.update();

};
THREE.TrackballControls = TrackballControls;
THREE.TrackballControls.prototype = Object.create( THREE.EventDispatcher.prototype );
THREE.TrackballControls.prototype.constructor = THREE.TrackballControls;