/home/lindsay/xeolabs/xeogl-next/xeogl/src/lighting/dirLight.js
API Docs for:

File: /home/lindsay/xeolabs/xeogl-next/xeogl/src/lighting/dirLight.js

  1. /**
  2. A **DirLight** is a directional light source that illuminates all {{#crossLink "Mesh"}}Meshes{{/crossLink}} equally
  3. from a given direction.
  4.  
  5. ## Overview
  6.  
  7. * DirLights have a direction, but no position.
  8. * The direction is the **direction that the light is emitted in**.
  9. * DirLights may be defined in either **World** or **View** coordinate space. When in World-space, their direction
  10. is relative to the World coordinate system, and will appear to move as the {{#crossLink "Camera"}}{{/crossLink}} moves.
  11. When in View-space, their direction is relative to the View coordinate system, and will behave as if fixed to the viewer's
  12. head as the {{#crossLink "Camera"}}{{/crossLink}} moves.
  13. * A DirLight can also have a {{#crossLink "Shadow"}}{{/crossLink}} component, to configure it to cast a shadow.
  14. * {{#crossLink "AmbientLight"}}{{/crossLink}}, {{#crossLink "DirLight"}}{{/crossLink}},
  15. {{#crossLink "SpotLight"}}{{/crossLink}} and {{#crossLink "PointLight"}}{{/crossLink}} instances are registered by ID
  16. on {{#crossLink "Scene/lights:property"}}Scene#lights{{/crossLink}} for convenient access.
  17.  
  18. ## Examples
  19.  
  20. * [View-space directional three-point lighting](../../examples/#lights_directional_view_threePoint)
  21. * [World-space directional three-point lighting](../../examples/#lights_directional_world_threePoint)
  22.  
  23. ## Usage
  24.  
  25. In the example below we'll customize the default Scene's light sources, defining an AmbientLight and a couple of
  26. DirLights, then create a Phong-shaded box mesh.
  27.  
  28. ````javascript
  29. new xeogl.AmbientLight({
  30. color: [0.8, 0.8, 0.8],
  31. intensity: 0.5
  32. });
  33.  
  34. new xeogl.DirLight({
  35. dir: [1, 1, 1], // Direction the light is shining in
  36. color: [0.5, 0.7, 0.5],
  37. intensity: 1.0,
  38. space: "view", // Other option is "world", for World-space
  39. shadow: false // Default
  40. });
  41.  
  42. new xeogl.DirLight({
  43. dir: [0.2, -0.8, 0.8],
  44. color: [0.8, 0.8, 0.8],
  45. intensity: 0.5,
  46. space: "view",
  47. shadow: false
  48. });
  49.  
  50. // Create box mesh
  51. new xeogl.Mesh({
  52. material: new xeogl.PhongMaterial({
  53. ambient: [0.5, 0.5, 0.5],
  54. diffuse: [1,0.3,0.3]
  55. }),
  56. geometry: new xeogl.BoxGeometry()
  57. });
  58. ````
  59.  
  60. @class DirLight
  61. @module xeogl
  62. @submodule lighting
  63. @constructor
  64. @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.
  65. @param [cfg] {*} The DirLight configuration
  66. @param [cfg.id] {String} Optional ID, unique among all components in the parent {{#crossLink "Scene"}}Scene{{/crossLink}}, generated automatically when omitted.
  67. @param [cfg.meta] {String:Object} Optional map of user-defined metadata to attach to this DirLight.
  68. @param [cfg.dir=[1.0, 1.0, 1.0]] {Float32Array} A unit vector indicating the direction that the light is shining,
  69. given in either World or View space, depending on the value of the **space** parameter.
  70. @param [cfg.color=[0.7, 0.7, 0.8 ]] {Float32Array} The color of this DirLight.
  71. @param [cfg.intensity=1.0 ] {Number} The intensity of this DirLight, as a factor in range ````[0..1]````.
  72. @param [cfg.space="view"] {String} The coordinate system the DirLight is defined in - "view" or "space".
  73. @param [cfg.shadow=false] {Boolean} Flag which indicates if this DirLight casts a shadow.
  74. @extends Component
  75. */
  76. import {Component} from '../component.js';
  77. import {State} from '../renderer/state.js';
  78. import {RenderBuffer} from '../renderer/renderBuffer.js';
  79. import {math} from '../math/math.js';
  80. import {componentClasses} from "./../componentClasses.js";
  81.  
  82. const type = "xeogl.DirLight";
  83.  
  84. class DirLight extends Component {
  85.  
  86. /**
  87. JavaScript class name for this Component.
  88.  
  89. For example: "xeogl.AmbientLight", "xeogl.MetallicMaterial" etc.
  90.  
  91. @property type
  92. @type String
  93. @final
  94. */
  95. get type() {
  96. return type;
  97. }
  98.  
  99. init(cfg) {
  100.  
  101. super.init(cfg);
  102.  
  103. const self = this;
  104.  
  105. this._shadowRenderBuf = null;
  106. this._shadowViewMatrix = null;
  107. this._shadowProjMatrix = null;
  108. this._shadowViewMatrixDirty = true;
  109. this._shadowProjMatrixDirty = true;
  110.  
  111. this._state = new State({
  112. type: "dir",
  113. dir: math.vec3([1.0, 1.0, 1.0]),
  114. color: math.vec3([0.7, 0.7, 0.8]),
  115. intensity: 1.0,
  116. space: cfg.space || "view",
  117. shadow: false,
  118. shadowDirty: true,
  119.  
  120. getShadowViewMatrix: (function () {
  121. const look = math.vec3();
  122. const up = math.vec3([0, 1, 0]);
  123. return function () {
  124. if (self._shadowViewMatrixDirty) {
  125. if (!self._shadowViewMatrix) {
  126. self._shadowViewMatrix = math.identityMat4();
  127. }
  128. const dir = self._state.dir;
  129. math.lookAtMat4v([-dir[0], -dir[1], -dir[2]], [0, 0, 0], up, self._shadowViewMatrix);
  130. self._shadowViewMatrixDirty = false;
  131. }
  132. return self._shadowViewMatrix;
  133. };
  134. })(),
  135.  
  136. getShadowProjMatrix: function () {
  137. if (self._shadowProjMatrixDirty) { // TODO: Set when canvas resizes
  138. if (!self._shadowProjMatrix) {
  139. self._shadowProjMatrix = math.identityMat4();
  140. }
  141. math.orthoMat4c(-10, 10, -10, 10, 0, 500.0, self._shadowProjMatrix);
  142. self._shadowProjMatrixDirty = false;
  143. }
  144. return self._shadowProjMatrix;
  145. },
  146.  
  147. getShadowRenderBuf: function () {
  148. if (!self._shadowRenderBuf) {
  149. self._shadowRenderBuf = new RenderBuffer(self.scene.canvas.canvas, self.scene.canvas.gl, { size: [1024, 1024]});
  150. }
  151. return self._shadowRenderBuf;
  152. }
  153. });
  154.  
  155. this.dir = cfg.dir;
  156. this.color = cfg.color;
  157. this.intensity = cfg.intensity;
  158. this.shadow = cfg.shadow;
  159. this.scene._lightCreated(this);
  160. }
  161.  
  162. /**
  163. The direction in which the light is shining.
  164.  
  165. @property dir
  166. @default [1.0, 1.0, 1.0]
  167. @type Float32Array
  168. */
  169. set dir(value) {
  170. this._state.dir.set(value || [1.0, 1.0, 1.0]);
  171. this._shadowViewMatrixDirty = true;
  172. this._renderer.shadowsDirty();
  173. }
  174.  
  175. get dir() {
  176. return this._state.dir;
  177. }
  178.  
  179. /**
  180. The color of this DirLight.
  181.  
  182. @property color
  183. @default [0.7, 0.7, 0.8]
  184. @type Float32Array
  185. */
  186. set color(value) {
  187. this._state.color.set(value || [0.7, 0.7, 0.8]);
  188. this._renderer.imageDirty();
  189. }
  190.  
  191. get color() {
  192. return this._state.color;
  193. }
  194.  
  195. /**
  196. The intensity of this DirLight.
  197.  
  198. Fires a {{#crossLink "DirLight/intensity:event"}}{{/crossLink}} event on change.
  199.  
  200. @property intensity
  201. @default 1.0
  202. @type Number
  203. */
  204. set intensity(value) {
  205. value = value !== undefined ? value : 1.0;
  206. this._state.intensity = value;
  207. this._renderer.imageDirty();
  208. }
  209.  
  210. get intensity() {
  211. return this._state.intensity;
  212. }
  213.  
  214. /**
  215. Flag which indicates if this DirLight casts a shadow.
  216.  
  217. @property shadow
  218. @default false
  219. @type Boolean
  220. */
  221. set shadow(value) {
  222. value = !!value;
  223. if (this._state.shadow === value) {
  224. return;
  225. }
  226. this._state.shadow = value;
  227. this._shadowViewMatrixDirty = true;
  228. this._renderer.shadowsDirty();
  229. }
  230.  
  231. get shadow() {
  232. return this._state.shadow;
  233. }
  234.  
  235. destroy() {
  236. super.destroy();
  237. this._state.destroy();
  238. if (this._shadowRenderBuf) {
  239. this._shadowRenderBuf.destroy();
  240. }
  241. this.scene._lightDestroyed(this);
  242. this._renderer.shadowsDirty();
  243. }
  244. }
  245.  
  246. componentClasses[type] = DirLight;
  247.  
  248. export {DirLight};
  249.