Source: extern/util.js

  1. import register from "../util/register.js";
  3. import m_assert_fact from "../util/assert.js";
  4. import m_compat_fact from "../intern/compat.js";
  5. import m_generator_fact from "../util/generator.js";
  6. import m_print_fact from "../intern/print.js";
  7. import * as m_quat from "../libs/gl_matrix/quat.js";
  8. import * as m_tbn from "../intern/tbn.js";
  9. import * as m_util from "../intern/util.js";
  10. import * as m_vec3 from "../libs/gl_matrix/vec3.js";
  12. /**
  13.  * Contains various utility methods for math, searching etc.
  14.  * @module util
  15.  */
  16. function Util(ns, exports) {
  18. var m_assert   = m_assert_fact(ns);
  19. var m_compat   = m_compat_fact(ns);
  20. var m_generator = m_generator_fact(ns);
  21. var m_print    = m_print_fact(ns);
  23. /**
  24.  * X-axis vector.
  25.  * @const {Vec3} module:util.AXIS_X
  26.  */
  27. exports.AXIS_X  = new Float32Array([1, 0, 0]);
  28. /**
  29.  * Y-axis vector.
  30.  * @const {Vec3} module:util.AXIS_Y
  31.  */
  32. exports.AXIS_Y  = new Float32Array([0, 1, 0]);
  33. /**
  34.  * Z-axis vector.
  35.  * @const {Vec3} module:util.AXIS_Z
  36.  */
  37. exports.AXIS_Z  = new Float32Array([0, 0, 1]);
  38. /**
  39.  * Negative x-axis vector.
  40.  * @const {Vec3} module:util.AXIS_MX
  41.  */
  42. exports.AXIS_MX = new Float32Array([-1, 0, 0]);
  43. /**
  44.  * Negative y-axis vector.
  45.  * @const {Vec3} module:util.AXIS_MY
  46.  */
  47. exports.AXIS_MY = new Float32Array([ 0,-1, 0]);
  48. /**
  49.  * Negative z-axis vector.
  50.  * @const {Vec3} module:util.AXIS_MZ
  51.  */
  52. exports.AXIS_MZ = new Float32Array([ 0, 0,-1]);
  54. /**
  55.  * Rotation sequence enum.
  56.  * @typedef {number} RotationSequence
  57.  */
  59. /**
  60.  * Rotation sequence: XYX.
  61.  * @const {RotationSequence} module:util.XYX
  62.  */
  63. exports.XYX = m_util.XYX;
  64. /**
  65.  * Rotation sequence: YZY.
  66.  * @const {RotationSequence} module:util.YZY
  67.  */
  68. exports.YZY = m_util.YZY;
  69. /**
  70.  * Rotation sequence: ZXZ.
  71.  * @const {RotationSequence} module:util.ZXZ
  72.  */
  73. exports.ZXZ = m_util.ZXZ;
  74. /**
  75.  * Rotation sequence: XZX.
  76.  * @const {RotationSequence} module:util.XZX
  77.  */
  78. exports.XZX = m_util.XZX;
  79. /**
  80.  * Rotation sequence: YXY.
  81.  * @const {RotationSequence} module:util.YXY
  82.  */
  83. exports.YXY = m_util.YXY;
  84. /**
  85.  * Rotation sequence: ZYZ.
  86.  * @const {RotationSequence} module:util.ZYZ
  87.  */
  88. exports.ZYZ = m_util.ZYZ;
  89. /**
  90.  * Rotation sequence: XYZ.
  91.  * @const {RotationSequence} module:util.XYZ
  92.  */
  93. exports.XYZ = m_util.XYZ;
  94. /**
  95.  * Rotation sequence: YZX.
  96.  * @const {RotationSequence} module:util.YZX
  97.  */
  98. exports.YZX = m_util.YZX;
  99. /**
  100.  * Rotation sequence: ZXY.
  101.  * @const {RotationSequence} module:util.ZXY
  102.  */
  103. exports.ZXY = m_util.ZXY;
  104. /**
  105.  * Rotation sequence: XZY.
  106.  * @const {RotationSequence} module:util.XZY
  107.  */
  108. exports.XZY = m_util.XZY;
  109. /**
  110.  * Rotation sequence: YXZ.
  111.  * @const {RotationSequence} module:util.YXZ
  112.  */
  113. exports.YXZ = m_util.YXZ;
  114. /**
  115.  * Rotation sequence: ZYX.
  116.  * @const {RotationSequence} module:util.ZYX
  117.  */
  118. exports.ZYX = m_util.ZYX;
  120. /**
  121.  * Create a new Float32Array.
  122.  * @param {number|Array|TypedArray} param Constructor param
  123.  * @returns {Float32Array} New Float32Array.
  124.  */
  125. exports.f32 = function(param) {
  126.     param = param || 0;
  127.     return m_util.f32(param);
  128. }
  130. /**
  131.  * Abort the program if assertion is false.
  132.  * @method module:util.assert
  133.  * @param {boolean} Boolean expression result
  134.  * @deprecated Do not use it anymore
  135.  */
  136. exports.assert = m_assert.assert;
  138. /**
  139.  * Search for object in array.
  140.  * @method module:util.keyfind
  141.  * @param {string} key Key
  142.  * @param {*} value Value
  143.  * @param {Object[]} array Array of objects.
  144.  * @returns {Object[]} Array of found objects.
  145.  */
  146. exports.keyfind = m_util.keyfind;
  148. /**
  149.  * Search for object in array.
  150.  * @method module:util.keysearch
  151.  * @param {string} key Key.
  152.  * @param {*} value Value.
  153.  * @param {Array} array Array of objects.
  154.  * @returns {?Object} First found object or null.
  155.  */
  156. exports.keysearch = m_util.keysearch;
  158. /**
  159.  * Extract rotation from the 4x4 matrix to quaternion vector.
  160.  * @method module:util.matrix_to_quat
  161.  * @param {Mat4} matrix 4x4 matrix
  162.  * @returns {Quat} Quaternion
  163.  */
  164. exports.matrix_to_quat = function(matrix) {
  165.     return m_util.matrix_to_quat(matrix);
  166. }
  168. /**
  169.  * Convert euler angles in the ZYX intrinsic system to quaternion.
  170.  * @method module:util.euler_to_quat
  171.  * @param {Euler} euler Euler angles. The angles order: an angle of the rotation around the x axis,
  172.  * an angle of the rotation around the y axis, an angle of the rotation around the z axis.
  173.  * @param {Quat} [quat] Destination quaternion vector.
  174.  * @returns {Quat} Quaternion vector.
  175.  */
  176. exports.euler_to_quat = function(euler, quat) {
  177.     if (!quat)
  178.         quat = new Float32Array(4);
  180.     return m_util.euler_to_quat(euler, quat);
  181. }
  183. /**
  184.  * Convert Euler angles in the ordered intrinsic system to quaternion.
  185.  * @method module:util.ordered_angles_to_quat
  186.  * @param {Euler} angles Ordered Euler angles. Euler angles have the same order as
  187.  * the intrinsic rotation sequence.
  188.  * @param {RotationSequence} order Intrinsic rotation sequence.
  189.  * @param {Quat} [quat] Destination quaternion vector.
  190.  * @returns {Quat} Quaternion vector.
  191.  */
  192. exports.ordered_angles_to_quat = function(angles, order, quat) {
  193.     if (!quat)
  194.         quat = m_quat.create();
  196.     return m_util.ordered_angles_to_quat(angles, order, quat);
  197. }
  199. /**
  200.  * Convert quaternion to Euler angles in the ordered intrinsic system.
  201.  * @method module:util.quat_to_ordered_angles
  202.  * @param {Quat} quat Quaternion vector.
  203.  * @param {RotationSequence} order Intrinsic rotation sequence.
  204.  * @param {Euler} [angles] Destination Euler angles vector. Euler angles have 
  205.  * the same order as the intrinsic rotation sequence.
  206.  * @returns {Euler} Euler angles vector.
  207.  */
  208. exports.quat_to_ordered_angles = function(quat, order, angles) {
  209.     if (!angles)
  210.         angles = m_vec3.create();
  212.     return m_util.quat_to_ordered_angles(quat, order, angles);
  213. }
  215. /**
  216.  * Convert quaternion rotation to euler rotation.
  217.  * @method module:util.quat_to_euler
  218.  * @param {Quat} quat Quaternion vector
  219.  * @param {Euler} [euler] Destination euler vector
  220.  * @returns {Euler} Euler vector
  221.  */
  222. exports.quat_to_euler = function(quat, euler) {
  223.     if (!euler)
  224.         euler = new Float32Array(3);
  226.     return m_util.quat_to_euler(quat, euler);
  227. }
  229. /**
  230.  * Get sign of the number.
  231.  * @method module:util.sign
  232.  * @param {number} value Input value
  233.  * @returns {number} -1,0,1 for negative, zero or positive number accordingly
  234.  */
  235. exports.sign = m_util.sign;
  237. /**
  238.  * Clamp the number.
  239.  * @method module:util.clamp
  240.  * @param {number} value Input value
  241.  * @param {number} min Lower bound
  242.  * @param {number} max Upper bound
  243.  * @returns {number} Clamped value
  244.  */
  245. exports.clamp = m_util.clamp;
  247. /**
  248.  * Convert quaternion rotation to a directional vector.
  249.  * @method module:util.quat_to_dir
  250.  * @param {Quat} quat Rotation quaternion
  251.  * @param {Vec3} ident Identity vector
  252.  * @param {Vec3} [dest] Destination vector
  253.  * @returns {Vec3} Destination vector.
  254.  */
  255. exports.quat_to_dir = m_util.quat_to_dir;
  257. /**
  258.  * Project camera quaternion rotation on a horizontal plane.
  259.  * @method module:util.ground_project_cam_quat
  260.  * @param {Quat} quat Source quaternion.
  261.  * @param {Quat} [dest] Destination quaternion.
  262.  * @returns {Quat} Destination quaternion.
  263.  */
  264. exports.ground_project_cam_quat = function(quat, dest) {
  265.     return m_util.quat_project(quat, m_util.AXIS_MZ, m_util.AXIS_Z, m_util.AXIS_Y, dest);
  266. }
  268. /**
  269.  * Transform a camera quaternion to a mesh quaternion.
  270.  * @method module:util.cam_quat_to_mesh_quat
  271.  * @param {Quat} cam_quat Camera quaternion.
  272.  * @param {Quat} [dest] Destination quaternion.
  273.  * @returns {Quat} Destination quaternion.
  274.  */
  275. exports.cam_quat_to_mesh_quat = function(cam_quat, dest) {
  276.     return m_util.cam_quat_to_mesh_quat(cam_quat, dest);
  277. }
  279. /**
  280.  * Perform quaternion projection.
  281.  * @method module:util.quat_project
  282.  * @param {Quat} quat Quaternion to project.
  283.  * @param {Vec3} quat_ident_dir Direction corresponding to the identity quaternion.
  284.  * @param {Vec3} plane Plane direction (normal).
  285.  * @param {Vec3} plane_ident_dir Direction corresponding to the
  286.  * identity quaternion in a plane.
  287.  * @param {Quat} [dest=quat.create()] Destination quaternion.
  288.  * @returns {Quat} Destination quaternion.
  289.  */
  290. exports.quat_project = function(quat, quat_ident_dir,
  291.         plane, plane_ident_dir, dest) {
  293.     if (m_vec3.dot(plane, plane_ident_dir) != 0) {
  294.         m_print.error("Wrong in-plane direction");
  295.         return null;
  296.     }
  298.     return m_util.quat_project(quat, quat_ident_dir,
  299.             plane, plane_ident_dir, dest);
  300. }
  302. exports.hash_code = function() {
  303.     return m_generator.hash_code.apply(m_generator, arguments);
  304. }
  306. /**
  307.  * Perform exponential smoothing.
  308.  * @method module:util.smooth
  309.  * @param {number} curr Current value.
  310.  * @param {number} last Last smoothed value.
  311.  * @param {number} delta Time delta.
  312.  * @param {number} period Mean lifetime for averaging.
  313.  * @returns {number} Smoothed value
  314.  */
  315. exports.smooth = m_util.smooth;
  317. /**
  318.  * Perform exponential smoothing (vector form).
  319.  * @method module:util.smooth_v
  320.  * @param {Float32Array} curr Current value.
  321.  * @param {Float32Array} last Last smoothed value.
  322.  * @param {Float32Array} delta Time delta.
  323.  * @param {Float32Array} period Mean lifetime for averaging.
  324.  * @param {Float32Array} [dest] Smoothed value
  325.  * @returns {Float32Array} Smoothed value
  326.  */
  327. exports.smooth_v = m_util.smooth_v;
  329. /**
  330.  * Check if object is a vector.
  331.  * @method module:util.is_vector
  332.  * @param {Object} o Object
  333.  * @param {number} [dimension=0] Dimension, allow any if not specified
  334.  * @returns {boolean} Check result
  335.  */
  336. exports.is_vector = m_util.is_vector;
  338. /**
  339.  * Correct the camera quaternion rotation.
  340.  * @method module:util.correct_cam_quat_up
  341.  * @param {Quat} quat Quaternion to correct
  342.  * @param {boolean} up_only Disable upside-down camera view
  343.  */
  344. exports.correct_cam_quat_up = m_util.correct_cam_quat_up;
  346. exports.quat_to_angle_axis = m_util.quat_to_angle_axis;
  348. exports.random_from_array = m_util.random_from_array;
  350. exports.horizontal_direction = m_util.horizontal_direction;
  352. /**
  353.  * Convert radian angle into range [0, 2PI)
  354.  * @method module:util.angle_wrap_0_2pi
  355.  * @param {number} angle Angle in radians
  356.  * @returns {number} Converted angle
  357.  */
  358. exports.angle_wrap_0_2pi = m_util.angle_wrap_0_2pi;
  360. /**
  361.  * Convert radian angle into custom range [from, to)
  362.  * @method module:util.angle_wrap_periodic
  363.  * @param {number} angle Angle in radians
  364.  * @param {number} from Value from in radians
  365.  * @param {number} to Value to in radians
  366.  * @returns {number} Converted angle
  367.  */
  368. exports.angle_wrap_periodic = m_util.angle_wrap_periodic;
  370. /**
  371.  * Smooth step function.
  372.  * @method module:util.smooth_step
  373.  * @param {number} t Input value.
  374.  * @param {number} min Min clamping value.
  375.  * @param {number} max Max clamping value.
  376.  * @returns {number} Result value.
  377.  */
  378. exports.smooth_step = m_util.smooth_step;
  380. /**
  381.  * Linear interpolation function.
  382.  * @method module:util.lerp
  383.  * @param {number} t Input value.
  384.  * @param {number} from Start interpolation value.
  385.  * @param {number} to End interpolation value.
  386.  * @returns {number} Result value.
  387.  */
  388. exports.lerp = m_util.lerp;
  390. /**
  391.  * Convert degrees to radians.
  392.  * @method module:util.deg_to_rad
  393.  * @param {number} degrees Angle in degrees.
  394.  * @returns {number} Angle in radians.
  395.  */
  396. exports.deg_to_rad = m_util.deg_to_rad;
  398. /**
  399.  * Convert radians to degrees.
  400.  * @method module:util.rad_to_deg
  401.  * @param {number} radians Angle in radians.
  402.  * @returns {number} Angle in degrees.
  403.  */
  404. exports.rad_to_deg = m_util.rad_to_deg;
  405. /**
  406.  * Convert directional vector to quaternion.
  407.  * @method module:util.dir_to_quat
  408.  * @param {Vec3} dir Directional vector.
  409.  * @param {Vec3} ident Identity vector
  410.  * @param {Quat} [dest] Destination quaternion
  411.  * @returns {Quat} Destination quaternion
  412.  */
  413. exports.dir_to_quat = m_util.dir_to_quat;
  415. /**
  416.  * Check if Internet Explorer 11 is using.
  417.  * @method module:util.is_ie11
  418.  * @returns {boolean} Check result.
  419.  */
  420. exports.is_ie11 = m_compat.is_ie11;
  422. /**
  423.  * Generate flat array of TBN quaternions
  424.  * @method module:util.gen_tbn_quats
  425.  * @param {Float32Array} normals Flat array of normals.
  426.  * @param {Float32Array} [tangents] Flat array of tangents.
  427.  * @returns {Float32Array} Flat array of quaternions.
  428.  * @deprecated Do not use it anymore
  429.  */
  430. exports.gen_tbn_quats = function(normals, tangents) {
  431.     m_print.error_once("util.gen_tbn_quats() deprecated. " +
  432.         "Do not use it anymore.");
  434.     return m_tbn.from_norm_tan(normals, tangents);
  435. }
  437. /**
  438.  * Returns the integer part of the given number.
  439.  * @method module:util.trunc
  440.  * @param {number} value Original value.
  441.  * @returns {number} Truncated value.
  442.  */
  443. exports.trunc = m_util.trunc;
  445. }
  447. var util_factory = register("util", Util);
  449. export default util_factory;