visual/VisualStim.js

  1. /** @module visual **/
  2. /**
  3.  * Base class for all visual stimuli.
  4.  *
  5.  * @author Alain Pitiot
  6.  * @version 2022.2.0
  7.  * @copyright (c) 2017-2020 Ilixa Ltd. (http://ilixa.com) (c) 2020-2022 Open Science Tools Ltd. (https://opensciencetools.org)
  8.  * @license Distributed under the terms of the MIT License
  9.  */
  11. import * as PIXI from "pixi.js-legacy";
  12. import { MinimalStim } from "../core/MinimalStim.js";
  13. import { WindowMixin } from "../core/WindowMixin.js";
  14. import * as util from "../util/Util.js";
  16. /**
  17.  * Base class for all visual stimuli.
  18.  *
  19.  * @extends MinimalStim
  20.  * @mixes WindowMixin
  21.  */
  22. export class VisualStim extends util.mix(MinimalStim).with(WindowMixin)
  23. {
  24. 	/**
  25. 	 * @param {Object} options
  26. 	 * @param {String} options.name - the name used when logging messages from this stimulus
  27. 	 * @param {module:core.Window} options.win - the associated Window
  28. 	 * @param {string} [options.units= "height"] - the units of the stimulus (e.g. for size, position, vertices)
  29. 	 * @param {number} [options.ori= 0.0] - the orientation (in degrees)
  30. 	 * @param {number} [options.opacity= 1.0] - the opacity
  31. 	 * @param {number} [options.depth= 0] - the depth (i.e. the z order)
  32. 	 * @param {Array.<number>} [options.pos= [0, 0]] - the position of the center of the stimulus
  33. 	 * @param {number} [options.size= 1.0] - the size
  34. 	 * @param {PIXI.Graphics} [options.clipMask= null] - the clip mask
  35. 	 * @param {boolean} [options.autoDraw= false] - whether or not the stimulus should be automatically drawn on every frame flip
  36. 	 * @param {boolean} [options.autoLog= false] - whether or not to log
  37. 	 */
  38. 	constructor({ name, win, units, ori, opacity, depth, pos, size, clipMask, autoDraw, autoLog } = {})
  39. 	{
  40. 		super({ win, name, autoDraw, autoLog });
  42. 		this._addAttribute(
  43. 			"units",
  44. 			units,
  45. 			(typeof win !== "undefined" && win !== null) ? win.units : "height",
  46. 			this._onChange(true, true),
  47. 		);
  48. 		this._addAttribute(
  49. 			"pos",
  50. 			pos,
  51. 			[0, 0],
  52. 		);
  53. 		this._addAttribute(
  54. 			"size",
  55. 			size,
  56. 			undefined,
  57. 		);
  58. 		this._addAttribute(
  59. 			"ori",
  60. 			ori,
  61. 			0.0,
  62. 		);
  63. 		this._addAttribute(
  64. 			"opacity",
  65. 			opacity,
  66. 			1.0,
  67. 			this._onChange(true, false),
  68. 		);
  69. 		this._addAttribute(
  70. 			"depth",
  71. 			depth,
  72. 			0,
  73. 			this._onChange(false, false),
  74. 		);
  75. 		this._addAttribute(
  76. 			"clipMask",
  77. 			clipMask,
  78. 			null,
  79. 			this._onChange(false, false),
  80. 		);
  82. 		// bounding box of the stimulus, in stimulus units
  83. 		// note: boundingBox does not take the orientation into account
  84. 		this._addAttribute("boundingBox", PIXI.Rectangle.EMPTY);
  86. 		// the stimulus need to be updated:
  87. 		this._needUpdate = true;
  89. 		// the PIXI representation also needs to be updated:
  90. 		this._needPixiUpdate = true;
  91. 	}
  93. 	/**
  94. 	 * Force a refresh of the stimulus.
  95. 	 *
  96. 	 * refresh() is called, in particular, when the Window is resized.
  97. 	 */
  98. 	refresh()
  99. 	{
  100. 		this._onChange(true, true)();
  101. 	}
  103. 	/**
  104. 	 * Setter for the size attribute.
  105. 	 *
  106. 	 * @param {undefined | null | number | number[]} size - the stimulus size
  107. 	 * @param {boolean} [log= false] - whether of not to log
  108. 	 */
  109. 	setSize(size, log = false)
  110. 	{
  111. 		// size is either undefined, null, or a tuple of numbers:
  112. 		if (typeof size !== "undefined" && size !== null)
  113. 		{
  114. 			size = util.toNumerical(size);
  115. 			if (!Array.isArray(size))
  116. 			{
  117. 				size = [size, size];
  118. 			}
  119. 		}
  121. 		const hasChanged = this._setAttribute("size", size, log);
  123. 		if (hasChanged)
  124. 		{
  125. 			this._onChange(true, true)();
  126. 		}
  127. 	}
  129. 	/**
  130. 	 * Setter for the orientation attribute.
  131. 	 *
  132. 	 * @param {number} ori - the orientation in degree with 0 as the vertical position, positive values rotate clockwise.
  133. 	 * @param {boolean} [log= false] - whether of not to log
  134. 	 */
  135. 	setOri(ori, log = false)
  136. 	{
  137. 		const hasChanged = this._setAttribute("ori", ori, log);
  139. 		if (hasChanged)
  140. 		{
  141. 			let radians = -ori * 0.017453292519943295;
  142. 			this._rotationMatrix = [
  143. 				[Math.cos(radians), -Math.sin(radians)],
  144. 				[Math.sin(radians), Math.cos(radians)]
  145. 			];
  147. 			if (this._pixi instanceof PIXI.DisplayObject) {
  148. 				this._pixi.rotation = -ori * Math.PI / 180;
  149. 			} else {
  150. 				this._onChange(true, true)();
  151. 			}
  152. 		}
  153. 	}
  155. 	/**
  156. 	 * Setter for the position attribute.
  157. 	 *
  158. 	 * @param {Array.<number>} pos - position of the center of the stimulus, in stimulus units
  159. 	 * @param {boolean} [log= false] - whether of not to log
  160. 	 */
  161. 	setPos(pos, log = false)
  162. 	{
  163. 		const prevPos = this._pos;
  164. 		const hasChanged = this._setAttribute("pos", util.toNumerical(pos), log);
  166. 		if (hasChanged)
  167. 		{
  168. 			this._needUpdate = true;
  170. 			// update the bounding box, without calling _estimateBoundingBox:
  171. 			this._boundingBox.x += this._pos[0] - prevPos[0];
  172. 			this._boundingBox.y += this._pos[1] - prevPos[1];
  173. 		}
  174. 	}
  176. 	/**
  177. 	 * Setter for the depth attribute.
  178. 	 *
  179. 	 * @param {Array.<number>} depth - order in which stimuli is rendered, kind of css's z-index with a negative sign.
  180. 	 * @param {boolean} [log= false] - whether of not to log
  181. 	 */
  182. 	setDepth (depth = 0, log = false) {
  183. 		this._setAttribute("depth", depth, log);
  184. 		if (this._pixi) {
  185. 			this._pixi.zIndex = -this._depth;
  186. 		}
  187. 	}
  189. 	/**
  190. 	 * Determine whether an object is inside the bounding box of the stimulus.
  191. 	 *
  192. 	 * @param {Object} object - the object
  193. 	 * @param {string} units - the units
  194. 	 * @return {boolean} whether or not the object is inside the bounding box of the stimulus
  195. 	 */
  196. 	contains(object, units)
  197. 	{
  198. 		// get the position of the object, in pixel coordinates:
  199. 		const objectPos_px = util.getPositionFromObject(object, units);
  201. 		if (typeof objectPos_px === "undefined")
  202. 		{
  203. 			throw {
  204. 				origin: "VisualStim.contains",
  205. 				context: "when determining whether VisualStim: " + this._name + " contains object: " + util.toString(object),
  206. 				error: "unable to determine the position of the object",
  207. 			};
  208. 		}
  210. 		// test for inclusion:
  211. 		return this._getBoundingBox_px().contains(objectPos_px[0], objectPos_px[1]);
  212. 	}
  214. 	/**
  215. 	 * Estimate the bounding box.
  216. 	 *
  217. 	 * @protected
  218. 	 */
  219. 	_estimateBoundingBox()
  220. 	{
  221. 		throw {
  222. 			origin: "VisualStim._estimateBoundingBox",
  223. 			context: `when estimating the bounding box of visual stimulus: ${this._name}`,
  224. 			error: "this method is abstract and should not be called.",
  225. 		};
  226. 	}
  228. 	/**
  229. 	 * Get the bounding box in pixel coordinates
  230. 	 *
  231. 	 * @protected
  232. 	 * @returns {PIXI.Rectangle} the bounding box, in pixel coordinates
  233. 	 */
  234. 	_getBoundingBox_px()
  235. 	{
  236. 		if (this._units === "pix")
  237. 		{
  238. 			return this._boundingBox.clone();
  239. 		}
  240. 		else if (this._units === "norm")
  241. 		{
  242. 			return new PIXI.Rectangle(
  243. 				this._boundingBox.x * this._win.size[0] / 2,
  244. 				this._boundingBox.y * this._win.size[1] / 2,
  245. 				this._boundingBox.width * this._win.size[0] / 2,
  246. 				this._boundingBox.height * this._win.size[1] / 2,
  247. 			);
  248. 		}
  249. 		else if (this._units === "height")
  250. 		{
  251. 			const minSize = Math.min(this._win.size[0], this._win.size[1]);
  252. 			return new PIXI.Rectangle(
  253. 				this._boundingBox.x * minSize,
  254. 				this._boundingBox.y * minSize,
  255. 				this._boundingBox.width * minSize,
  256. 				this._boundingBox.height * minSize,
  257. 			);
  258. 		}
  259. 		else
  260. 		{
  261. 			throw Object.assign(response, { error: `unknown units: ${this._units}` });
  262. 		}
  263. 	}
  265. 	/**
  266. 	 * Generate a callback that prepares updates to the stimulus.
  267. 	 * This is typically called in the constructor of a stimulus, when attributes are added
  268. 	 * 	with _addAttribute.
  269. 	 *
  270. 	 * @protected
  271. 	 * @param {boolean} [withPixi = false] - whether or not the PIXI representation must
  272. 	 * 	also be updated
  273. 	 * @param {boolean} [withBoundingBox = false] - whether or not to immediately estimate
  274. 	 * 	the bounding box
  275. 	 * @return {Function}
  276. 	 */
  277. 	_onChange(withPixi = false, withBoundingBox = false)
  278. 	{
  279. 		return () =>
  280. 		{
  281. 			this._needUpdate = true;
  282. 			if (withPixi)
  283. 			{
  284. 				this._needPixiUpdate = true;
  285. 			}
  286. 			if (withBoundingBox)
  287. 			{
  288. 				this._estimateBoundingBox();
  289. 			}
  290. 		};
  291. 	}
  292. }