/home/lindsay/xeolabs/xeogl-next/xeogl/src/camera/perspective.js
API Docs for:

File: /home/lindsay/xeolabs/xeogl-next/xeogl/src/camera/perspective.js

  1. /**
  2. A **Perspective** defines a perspective projection transform for a {{#crossLink "Camera"}}Camera{{/crossLink}}.
  3.  
  4. ## Overview
  5.  
  6. * A {{#crossLink "Camera"}}Camera{{/crossLink}} has a Perspective to configure its perspective projection mode.
  7.  
  8. ## Examples
  9.  
  10. * [Camera with perspective projection](../../examples/#camera_perspective)
  11.  
  12. ## Usage
  13.  
  14. * See {{#crossLink "Camera"}}{{/crossLink}}
  15.  
  16. @class Perspective
  17. @module xeogl
  18. @submodule camera
  19. @constructor
  20. @param [owner] {Component} Owner component. When destroyed, the owner will destroy this component as well. Creates this component within the default {{#crossLink "Scene"}}{{/crossLink}} when omitted.
  21. @param [cfg] {*} Configs
  22. @param [cfg.id] {String} Optional ID, unique among all components in the parent scene, generated automatically when omitted.
  23. @param [cfg.meta] {String:Object} Optional map of user-defined metadata to attach to this Perspective.
  24. @param [cfg.parent] {String|Transform} ID or instance of a parent {{#crossLink "Transform"}}{{/crossLink}} within the same {{#crossLink "Scene"}}Scene{{/crossLink}}.
  25. @param [cfg.fov=60.0] {Number} Field-of-view angle, in degrees.
  26. @param [cfg.fovAxis="min"] {String} The field-of-view axis: "x", "y", or "min" to use whichever is currently the minimum.
  27. @param [cfg.near=0.1] {Number} Position of the near plane on the View-space Z-axis.
  28. @param [cfg.far=10000] {Number} Position of the far plane on the View-space Z-axis.
  29. @author xeolabs / http://xeolabs.com
  30. @author Artur-Sampaio / https://github.com/Artur-Sampaio
  31. @extends Component
  32. */
  33.  
  34. import {math} from '../math/math.js';
  35. import {Component} from '../component.js';
  36. import {State} from '../renderer/state.js';
  37. import {componentClasses} from "./../componentClasses.js";
  38.  
  39. const type = "xeogl.Perspective";
  40.  
  41. class Perspective extends Component {
  42.  
  43. /**
  44. JavaScript class name for this Component.
  45.  
  46. For example: "xeogl.AmbientLight", "xeogl.MetallicMaterial" etc.
  47.  
  48. @property type
  49. @type String
  50. @final
  51. */
  52. get type() {
  53. return type;
  54. }
  55.  
  56. init(cfg) {
  57.  
  58. super.init(cfg);
  59.  
  60. this._state = new State({
  61. matrix: math.mat4()
  62. });
  63.  
  64. this._dirty = false;
  65. this._fov = 60.0;
  66. this._near = 0.1;
  67. this._far = 10000.0;
  68.  
  69. // Recompute aspect from change in canvas size
  70. this._canvasResized = this.scene.canvas.on("boundary", this._needUpdate, this);
  71.  
  72. this.fov = cfg.fov;
  73. this.fovAxis = cfg.fovAxis;
  74. this.near = cfg.near;
  75. this.far = cfg.far;
  76. }
  77.  
  78. _update() {
  79. const WIDTH_INDEX = 2;
  80. const HEIGHT_INDEX = 3;
  81. const boundary = this.scene.viewport.boundary;
  82. const aspect = boundary[WIDTH_INDEX] / boundary[HEIGHT_INDEX];
  83. let fov = this._fov;
  84. const fovAxis = this._fovAxis;
  85. if (fovAxis == "x" || (fovAxis == "min" && aspect < 1) || (fovAxis == "max" && aspect > 1)) {
  86. fov = fov / aspect;
  87. }
  88. fov = Math.min(fov, 120);
  89. math.perspectiveMat4(fov * (Math.PI / 180.0), aspect, this._near, this._far, this._state.matrix);
  90. this._renderer.imageDirty();
  91. this.fire("matrix", this._state.matrix);
  92. }
  93.  
  94. /**
  95. The field-of-view angle (FOV).
  96.  
  97. Fires a {{#crossLink "Perspective/fov:event"}}{{/crossLink}} event on change.
  98.  
  99. @property fov
  100. @default 60.0
  101. @type Number
  102. */
  103. set fov(value) {
  104. this._fov = (value !== undefined && value !== null) ? value : 60.0;
  105. this._needUpdate(0); // Ensure matrix built on next "tick"
  106. /**
  107. Fired whenever this Perspective's {{#crossLink "Perspective/fov:property"}}{{/crossLink}} property changes.
  108.  
  109. @event fov
  110. @param value The property's new value
  111. */
  112. this.fire("fov", this._fov);
  113. }
  114.  
  115. get fov() {
  116. return this._fov;
  117. }
  118.  
  119. /**
  120. The FOV axis.
  121.  
  122. Options are "x", "y" or "min", to use the minimum axis.
  123.  
  124. Fires a {{#crossLink "Perspective/fov:event"}}{{/crossLink}} event on change.
  125.  
  126. @property fovAxis
  127. @default "min"
  128. @type String
  129. */
  130. set fovAxis(value) {
  131. value = value || "min";
  132. if (this._fovAxis === value) {
  133. return;
  134. }
  135. if (value !== "x" && value !== "y" && value !== "min") {
  136. this.error("Unsupported value for 'fovAxis': " + value + " - defaulting to 'min'");
  137. value = "min";
  138. }
  139. this._fovAxis = value;
  140. this._needUpdate(0); // Ensure matrix built on next "tick"
  141. /**
  142. Fired whenever this Perspective's {{#crossLink "Perspective/fovAxis:property"}}{{/crossLink}} property changes.
  143.  
  144. @event fovAxis
  145. @param value The property's new value
  146. */
  147. this.fire("fovAxis", this._fovAxis);
  148. }
  149.  
  150. get fovAxis() {
  151. return this._fovAxis;
  152. }
  153.  
  154. /**
  155. Position of this Perspective's near plane on the positive View-space Z-axis.
  156.  
  157. Fires a {{#crossLink "Perspective/near:event"}}{{/crossLink}} event on change.
  158.  
  159. @property near
  160. @default 0.1
  161. @type Number
  162. */
  163. set near(value) {
  164. this._near = (value !== undefined && value !== null) ? value : 0.1;
  165. this._needUpdate(0); // Ensure matrix built on next "tick"
  166. /**
  167. Fired whenever this Perspective's {{#crossLink "Perspective/near:property"}}{{/crossLink}} property changes.
  168. @event near
  169. @param value The property's new value
  170. */
  171. this.fire("near", this._near);
  172. }
  173.  
  174. get near() {
  175. return this._near;
  176. }
  177.  
  178. /**
  179. Position of this Perspective's far plane on the positive View-space Z-axis.
  180.  
  181. Fires a {{#crossLink "Perspective/far:event"}}{{/crossLink}} event on change.
  182.  
  183. @property far
  184. @default 10000.0
  185. @type Number
  186. */
  187. set far(value) {
  188. this._far = (value !== undefined && value !== null) ? value : 10000;
  189. this._needUpdate(0); // Ensure matrix built on next "tick"
  190. /**
  191. Fired whenever this Perspective's {{#crossLink "Perspective/far:property"}}{{/crossLink}} property changes.
  192.  
  193. @event far
  194. @param value The property's new value
  195. */
  196. this.fire("far", this._far);
  197. }
  198.  
  199. get far() {
  200. return this._far;
  201. }
  202.  
  203. /**
  204. The Perspective's projection transform matrix.
  205.  
  206. Fires a {{#crossLink "Perspective/matrix:event"}}{{/crossLink}} event on change.
  207.  
  208. @property matrix
  209. @default [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
  210. @type {Float32Array}
  211. */
  212. get matrix() {
  213. if (this._updateScheduled) {
  214. this._doUpdate();
  215. }
  216. return this._state.matrix;
  217. }
  218.  
  219. destroy() {
  220. super.destroy();
  221. this._state.destroy();
  222. super.destroy();
  223. this.scene.canvas.off(this._canvasResized);
  224. }
  225. }
  226.  
  227. componentClasses[type] = Perspective;
  228.  
  229. export{Perspective};