index.d.ts 40 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922
  1. /// <reference path="./global.d.ts" />
  2. import type { Dict } from '@pixi/utils';
  3. import { EventEmitter } from '@pixi/utils';
  4. import type { Filter } from '@pixi/core';
  5. import type { IPointData } from '@pixi/math';
  6. import type { MaskData } from '@pixi/core';
  7. import type { Matrix } from '@pixi/math';
  8. import type { ObservablePoint } from '@pixi/math';
  9. import type { Point } from '@pixi/math';
  10. import { Rectangle } from '@pixi/math';
  11. import type { Renderer } from '@pixi/core';
  12. import { Transform } from '@pixi/math';
  13. /**
  14. * 'Builder' pattern for bounds rectangles.
  15. *
  16. * This could be called an Axis-Aligned Bounding Box.
  17. * It is not an actual shape. It is a mutable thing; no 'EMPTY' or those kind of problems.
  18. * @memberof PIXI
  19. */
  20. export declare class Bounds {
  21. /** @default Infinity */
  22. minX: number;
  23. /** @default Infinity */
  24. minY: number;
  25. /** @default -Infinity */
  26. maxX: number;
  27. /** @default -Infinity */
  28. maxY: number;
  29. rect: Rectangle;
  30. /**
  31. * It is updated to _boundsID of corresponding object to keep bounds in sync with content.
  32. * Updated from outside, thus public modifier.
  33. */
  34. updateID: number;
  35. constructor();
  36. /**
  37. * Checks if bounds are empty.
  38. * @returns - True if empty.
  39. */
  40. isEmpty(): boolean;
  41. /** Clears the bounds and resets. */
  42. clear(): void;
  43. /**
  44. * Can return Rectangle.EMPTY constant, either construct new rectangle, either use your rectangle
  45. * It is not guaranteed that it will return tempRect
  46. * @param rect - Temporary object will be used if AABB is not empty
  47. * @returns - A rectangle of the bounds
  48. */
  49. getRectangle(rect?: Rectangle): Rectangle;
  50. /**
  51. * This function should be inlined when its possible.
  52. * @param point - The point to add.
  53. */
  54. addPoint(point: IPointData): void;
  55. /**
  56. * Adds a point, after transformed. This should be inlined when its possible.
  57. * @param matrix
  58. * @param point
  59. */
  60. addPointMatrix(matrix: Matrix, point: IPointData): void;
  61. /**
  62. * Adds a quad, not transformed
  63. * @param vertices - The verts to add.
  64. */
  65. addQuad(vertices: Float32Array): void;
  66. /**
  67. * Adds sprite frame, transformed.
  68. * @param transform - transform to apply
  69. * @param x0 - left X of frame
  70. * @param y0 - top Y of frame
  71. * @param x1 - right X of frame
  72. * @param y1 - bottom Y of frame
  73. */
  74. addFrame(transform: Transform, x0: number, y0: number, x1: number, y1: number): void;
  75. /**
  76. * Adds sprite frame, multiplied by matrix
  77. * @param matrix - matrix to apply
  78. * @param x0 - left X of frame
  79. * @param y0 - top Y of frame
  80. * @param x1 - right X of frame
  81. * @param y1 - bottom Y of frame
  82. */
  83. addFrameMatrix(matrix: Matrix, x0: number, y0: number, x1: number, y1: number): void;
  84. /**
  85. * Adds screen vertices from array
  86. * @param vertexData - calculated vertices
  87. * @param beginOffset - begin offset
  88. * @param endOffset - end offset, excluded
  89. */
  90. addVertexData(vertexData: Float32Array, beginOffset: number, endOffset: number): void;
  91. /**
  92. * Add an array of mesh vertices
  93. * @param transform - mesh transform
  94. * @param vertices - mesh coordinates in array
  95. * @param beginOffset - begin offset
  96. * @param endOffset - end offset, excluded
  97. */
  98. addVertices(transform: Transform, vertices: Float32Array, beginOffset: number, endOffset: number): void;
  99. /**
  100. * Add an array of mesh vertices.
  101. * @param matrix - mesh matrix
  102. * @param vertices - mesh coordinates in array
  103. * @param beginOffset - begin offset
  104. * @param endOffset - end offset, excluded
  105. * @param padX - x padding
  106. * @param padY - y padding
  107. */
  108. addVerticesMatrix(matrix: Matrix, vertices: Float32Array, beginOffset: number, endOffset: number, padX?: number, padY?: number): void;
  109. /**
  110. * Adds other {@link Bounds}.
  111. * @param bounds - The Bounds to be added
  112. */
  113. addBounds(bounds: Bounds): void;
  114. /**
  115. * Adds other Bounds, masked with Bounds.
  116. * @param bounds - The Bounds to be added.
  117. * @param mask - TODO
  118. */
  119. addBoundsMask(bounds: Bounds, mask: Bounds): void;
  120. /**
  121. * Adds other Bounds, multiplied by matrix. Bounds shouldn't be empty.
  122. * @param bounds - other bounds
  123. * @param matrix - multiplicator
  124. */
  125. addBoundsMatrix(bounds: Bounds, matrix: Matrix): void;
  126. /**
  127. * Adds other Bounds, masked with Rectangle.
  128. * @param bounds - TODO
  129. * @param area - TODO
  130. */
  131. addBoundsArea(bounds: Bounds, area: Rectangle): void;
  132. /**
  133. * Pads bounds object, making it grow in all directions.
  134. * If paddingY is omitted, both paddingX and paddingY will be set to paddingX.
  135. * @param paddingX - The horizontal padding amount.
  136. * @param paddingY - The vertical padding amount.
  137. */
  138. pad(paddingX?: number, paddingY?: number): void;
  139. /**
  140. * Adds padded frame. (x0, y0) should be strictly less than (x1, y1)
  141. * @param x0 - left X of frame
  142. * @param y0 - top Y of frame
  143. * @param x1 - right X of frame
  144. * @param y1 - bottom Y of frame
  145. * @param padX - padding X
  146. * @param padY - padding Y
  147. */
  148. addFramePad(x0: number, y0: number, x1: number, y1: number, padX: number, padY: number): void;
  149. }
  150. export declare interface Container extends GlobalMixins.Container, DisplayObject {
  151. }
  152. /**
  153. * Container is a general-purpose display object that holds children. It also adds built-in support for advanced
  154. * rendering features like masking and filtering.
  155. *
  156. * It is the base class of all display objects that act as a container for other objects, including Graphics
  157. * and Sprite.
  158. *
  159. * ```js
  160. * import { BlurFilter } from '@pixi/filter-blur';
  161. * import { Container } from '@pixi/display';
  162. * import { Graphics } from '@pixi/graphics';
  163. * import { Sprite } from '@pixi/sprite';
  164. *
  165. * let container = new Container();
  166. * let sprite = Sprite.from("https://s3-us-west-2.amazonaws.com/s.cdpn.io/693612/IaUrttj.png");
  167. *
  168. * sprite.width = 512;
  169. * sprite.height = 512;
  170. *
  171. * // Adds a sprite as a child to this container. As a result, the sprite will be rendered whenever the container
  172. * // is rendered.
  173. * container.addChild(sprite);
  174. *
  175. * // Blurs whatever is rendered by the container
  176. * container.filters = [new BlurFilter()];
  177. *
  178. * // Only the contents within a circle at the center should be rendered onto the screen.
  179. * container.mask = new Graphics()
  180. * .beginFill(0xffffff)
  181. * .drawCircle(sprite.width / 2, sprite.height / 2, Math.min(sprite.width, sprite.height) / 2)
  182. * .endFill();
  183. * ```
  184. * @memberof PIXI
  185. */
  186. export declare class Container<T extends DisplayObject = DisplayObject> extends DisplayObject {
  187. /**
  188. * The array of children of this container.
  189. * @readonly
  190. */
  191. readonly children: T[];
  192. /**
  193. * If set to true, the container will sort its children by zIndex value
  194. * when updateTransform() is called, or manually if sortChildren() is called.
  195. *
  196. * This actually changes the order of elements in the array, so should be treated
  197. * as a basic solution that is not performant compared to other solutions,
  198. * such as @link https://github.com/pixijs/pixi-display
  199. *
  200. * Also be aware of that this may not work nicely with the addChildAt() function,
  201. * as the zIndex sorting may cause the child to automatically sorted to another position.
  202. * @see PIXI.settings.SORTABLE_CHILDREN
  203. */
  204. sortableChildren: boolean;
  205. /**
  206. * Should children be sorted by zIndex at the next updateTransform call.
  207. *
  208. * Will get automatically set to true if a new child is added, or if a child's zIndex changes.
  209. */
  210. sortDirty: boolean;
  211. parent: Container;
  212. containerUpdateTransform: () => void;
  213. protected _width: number;
  214. protected _height: number;
  215. constructor();
  216. /**
  217. * Overridable method that can be used by Container subclasses whenever the children array is modified.
  218. * @param _length
  219. */
  220. protected onChildrenChange(_length?: number): void;
  221. /**
  222. * Adds one or more children to the container.
  223. *
  224. * Multiple items can be added like so: `myContainer.addChild(thingOne, thingTwo, thingThree)`
  225. * @param {...PIXI.DisplayObject} children - The DisplayObject(s) to add to the container
  226. * @returns {PIXI.DisplayObject} - The first child that was added.
  227. */
  228. addChild<U extends T[]>(...children: U): U[0];
  229. /**
  230. * Adds a child to the container at a specified index. If the index is out of bounds an error will be thrown
  231. * @param {PIXI.DisplayObject} child - The child to add
  232. * @param {number} index - The index to place the child in
  233. * @returns {PIXI.DisplayObject} The child that was added.
  234. */
  235. addChildAt<U extends T>(child: U, index: number): U;
  236. /**
  237. * Swaps the position of 2 Display Objects within this container.
  238. * @param child - First display object to swap
  239. * @param child2 - Second display object to swap
  240. */
  241. swapChildren(child: T, child2: T): void;
  242. /**
  243. * Returns the index position of a child DisplayObject instance
  244. * @param child - The DisplayObject instance to identify
  245. * @returns - The index position of the child display object to identify
  246. */
  247. getChildIndex(child: T): number;
  248. /**
  249. * Changes the position of an existing child in the display object container
  250. * @param child - The child DisplayObject instance for which you want to change the index number
  251. * @param index - The resulting index number for the child display object
  252. */
  253. setChildIndex(child: T, index: number): void;
  254. /**
  255. * Returns the child at the specified index
  256. * @param index - The index to get the child at
  257. * @returns - The child at the given index, if any.
  258. */
  259. getChildAt(index: number): T;
  260. /**
  261. * Removes one or more children from the container.
  262. * @param {...PIXI.DisplayObject} children - The DisplayObject(s) to remove
  263. * @returns {PIXI.DisplayObject} The first child that was removed.
  264. */
  265. removeChild<U extends T[]>(...children: U): U[0];
  266. /**
  267. * Removes a child from the specified index position.
  268. * @param index - The index to get the child from
  269. * @returns The child that was removed.
  270. */
  271. removeChildAt(index: number): T;
  272. /**
  273. * Removes all children from this container that are within the begin and end indexes.
  274. * @param beginIndex - The beginning position.
  275. * @param endIndex - The ending position. Default value is size of the container.
  276. * @returns - List of removed children
  277. */
  278. removeChildren(beginIndex?: number, endIndex?: number): T[];
  279. /** Sorts children by zIndex. Previous order is maintained for 2 children with the same zIndex. */
  280. sortChildren(): void;
  281. /** Updates the transform on all children of this container for rendering. */
  282. updateTransform(): void;
  283. /**
  284. * Recalculates the bounds of the container.
  285. *
  286. * This implementation will automatically fit the children's bounds into the calculation. Each child's bounds
  287. * is limited to its mask's bounds or filterArea, if any is applied.
  288. */
  289. calculateBounds(): void;
  290. /**
  291. * Retrieves the local bounds of the displayObject as a rectangle object.
  292. *
  293. * Calling `getLocalBounds` may invalidate the `_bounds` of the whole subtree below. If using it inside a render()
  294. * call, it is advised to call `getBounds()` immediately after to recalculate the world bounds of the subtree.
  295. * @param rect - Optional rectangle to store the result of the bounds calculation.
  296. * @param skipChildrenUpdate - Setting to `true` will stop re-calculation of children transforms,
  297. * it was default behaviour of pixi 4.0-5.2 and caused many problems to users.
  298. * @returns - The rectangular bounding area.
  299. */
  300. getLocalBounds(rect?: Rectangle, skipChildrenUpdate?: boolean): Rectangle;
  301. /**
  302. * Recalculates the content bounds of this object. This should be overriden to
  303. * calculate the bounds of this specific object (not including children).
  304. * @protected
  305. */
  306. protected _calculateBounds(): void;
  307. /**
  308. * Renders this object and its children with culling.
  309. * @protected
  310. * @param {PIXI.Renderer} renderer - The renderer
  311. */
  312. protected _renderWithCulling(renderer: Renderer): void;
  313. /**
  314. * Renders the object using the WebGL renderer.
  315. *
  316. * The [_render]{@link PIXI.Container#_render} method is be overriden for rendering the contents of the
  317. * container itself. This `render` method will invoke it, and also invoke the `render` methods of all
  318. * children afterward.
  319. *
  320. * If `renderable` or `visible` is false or if `worldAlpha` is not positive or if `cullable` is true and
  321. * the bounds of this object are out of frame, this implementation will entirely skip rendering.
  322. * See {@link PIXI.DisplayObject} for choosing between `renderable` or `visible`. Generally,
  323. * setting alpha to zero is not recommended for purely skipping rendering.
  324. *
  325. * When your scene becomes large (especially when it is larger than can be viewed in a single screen), it is
  326. * advised to employ **culling** to automatically skip rendering objects outside of the current screen.
  327. * See [cullable]{@link PIXI.DisplayObject#cullable} and [cullArea]{@link PIXI.DisplayObject#cullArea}.
  328. * Other culling methods might be better suited for a large number static objects; see
  329. * [@pixi-essentials/cull]{@link https://www.npmjs.com/package/@pixi-essentials/cull} and
  330. * [pixi-cull]{@link https://www.npmjs.com/package/pixi-cull}.
  331. *
  332. * The [renderAdvanced]{@link PIXI.Container#renderAdvanced} method is internally used when when masking or
  333. * filtering is applied on a container. This does, however, break batching and can affect performance when
  334. * masking and filtering is applied extensively throughout the scene graph.
  335. * @param renderer - The renderer
  336. */
  337. render(renderer: Renderer): void;
  338. /**
  339. * Render the object using the WebGL renderer and advanced features.
  340. * @param renderer - The renderer
  341. */
  342. protected renderAdvanced(renderer: Renderer): void;
  343. /**
  344. * To be overridden by the subclasses.
  345. * @param _renderer - The renderer
  346. */
  347. protected _render(_renderer: Renderer): void;
  348. /**
  349. * Removes all internal references and listeners as well as removes children from the display list.
  350. * Do not use a Container after calling `destroy`.
  351. * @param options - Options parameter. A boolean will act as if all options
  352. * have been set to that value
  353. * @param {boolean} [options.children=false] - if set to true, all the children will have their destroy
  354. * method called as well. 'options' will be passed on to those calls.
  355. * @param {boolean} [options.texture=false] - Only used for child Sprites if options.children is set to true
  356. * Should it destroy the texture of the child sprite
  357. * @param {boolean} [options.baseTexture=false] - Only used for child Sprites if options.children is set to true
  358. * Should it destroy the base texture of the child sprite
  359. */
  360. destroy(options?: IDestroyOptions | boolean): void;
  361. /** The width of the Container, setting this will actually modify the scale to achieve the value set. */
  362. get width(): number;
  363. set width(value: number);
  364. /** The height of the Container, setting this will actually modify the scale to achieve the value set. */
  365. get height(): number;
  366. set height(value: number);
  367. }
  368. export declare interface DisplayObject extends Omit<GlobalMixins.DisplayObject, keyof EventEmitter>, EventEmitter {
  369. }
  370. /**
  371. * The base class for all objects that are rendered on the screen.
  372. *
  373. * This is an abstract class and can not be used on its own; rather it should be extended.
  374. *
  375. * ## Display objects implemented in PixiJS
  376. *
  377. * | Display Object | Description |
  378. * | ------------------------------- | --------------------------------------------------------------------- |
  379. * | {@link PIXI.Container} | Adds support for `children` to DisplayObject |
  380. * | {@link PIXI.Graphics} | Shape-drawing display object similar to the Canvas API |
  381. * | {@link PIXI.Sprite} | Draws textures (i.e. images) |
  382. * | {@link PIXI.Text} | Draws text using the Canvas API internally |
  383. * | {@link PIXI.BitmapText} | More scaleable solution for text rendering, reusing glyph textures |
  384. * | {@link PIXI.TilingSprite} | Draws textures/images in a tiled fashion |
  385. * | {@link PIXI.AnimatedSprite} | Draws an animation of multiple images |
  386. * | {@link PIXI.Mesh} | Provides a lower-level API for drawing meshes with custom data |
  387. * | {@link PIXI.NineSlicePlane} | Mesh-related |
  388. * | {@link PIXI.SimpleMesh} | v4-compatible mesh |
  389. * | {@link PIXI.SimplePlane} | Mesh-related |
  390. * | {@link PIXI.SimpleRope} | Mesh-related |
  391. *
  392. * ## Transforms
  393. *
  394. * The [transform]{@link DisplayObject#transform} of a display object describes the projection from its
  395. * local coordinate space to its parent's local coordinate space. The following properties are derived
  396. * from the transform:
  397. *
  398. * <table>
  399. * <thead>
  400. * <tr>
  401. * <th>Property</th>
  402. * <th>Description</th>
  403. * </tr>
  404. * </thead>
  405. * <tbody>
  406. * <tr>
  407. * <td>[pivot]{@link PIXI.DisplayObject#pivot}</td>
  408. * <td>
  409. * Invariant under rotation, scaling, and skewing. The projection of into the parent's space of the pivot
  410. * is equal to position, regardless of the other three transformations. In other words, It is the center of
  411. * rotation, scaling, and skewing.
  412. * </td>
  413. * </tr>
  414. * <tr>
  415. * <td>[position]{@link PIXI.DisplayObject#position}</td>
  416. * <td>
  417. * Translation. This is the position of the [pivot]{@link PIXI.DisplayObject#pivot} in the parent's local
  418. * space. The default value of the pivot is the origin (0,0). If the top-left corner of your display object
  419. * is (0,0) in its local space, then the position will be its top-left corner in the parent's local space.
  420. * </td>
  421. * </tr>
  422. * <tr>
  423. * <td>[scale]{@link PIXI.DisplayObject#scale}</td>
  424. * <td>
  425. * Scaling. This will stretch (or compress) the display object's projection. The scale factors are along the
  426. * local coordinate axes. In other words, the display object is scaled before rotated or skewed. The center
  427. * of scaling is the [pivot]{@link PIXI.DisplayObject#pivot}.
  428. * </td>
  429. * </tr>
  430. * <tr>
  431. * <td>[rotation]{@link PIXI.DisplayObject#rotation}</td>
  432. * <td>
  433. * Rotation. This will rotate the display object's projection by this angle (in radians).
  434. * </td>
  435. * </tr>
  436. * <tr>
  437. * <td>[skew]{@link PIXI.DisplayObject#skew}</td>
  438. * <td>
  439. * <p>Skewing. This can be used to deform a rectangular display object into a parallelogram.</p>
  440. * <p>
  441. * In PixiJS, skew has a slightly different behaviour than the conventional meaning. It can be
  442. * thought of the net rotation applied to the coordinate axes (separately). For example, if "skew.x" is
  443. * ⍺ and "skew.y" is β, then the line x = 0 will be rotated by ⍺ (y = -x*cot⍺) and the line y = 0 will be
  444. * rotated by β (y = x*tanβ). A line y = x*tanϴ (i.e. a line at angle ϴ to the x-axis in local-space) will
  445. * be rotated by an angle between ⍺ and β.
  446. * </p>
  447. * <p>
  448. * It can be observed that if skew is applied equally to both axes, then it will be equivalent to applying
  449. * a rotation. Indeed, if "skew.x" = -ϴ and "skew.y" = ϴ, it will produce an equivalent of "rotation" = ϴ.
  450. * </p>
  451. * <p>
  452. * Another quite interesting observation is that "skew.x", "skew.y", rotation are communtative operations. Indeed,
  453. * because rotation is essentially a careful combination of the two.
  454. * </p>
  455. * </td>
  456. * </tr>
  457. * <tr>
  458. * <td>angle</td>
  459. * <td>Rotation. This is an alias for [rotation]{@link PIXI.DisplayObject#rotation}, but in degrees.</td>
  460. * </tr>
  461. * <tr>
  462. * <td>x</td>
  463. * <td>Translation. This is an alias for position.x!</td>
  464. * </tr>
  465. * <tr>
  466. * <td>y</td>
  467. * <td>Translation. This is an alias for position.y!</td>
  468. * </tr>
  469. * <tr>
  470. * <td>width</td>
  471. * <td>
  472. * Implemented in [Container]{@link PIXI.Container}. Scaling. The width property calculates scale.x by dividing
  473. * the "requested" width by the local bounding box width. It is indirectly an abstraction over scale.x, and there
  474. * is no concept of user-defined width.
  475. * </td>
  476. * </tr>
  477. * <tr>
  478. * <td>height</td>
  479. * <td>
  480. * Implemented in [Container]{@link PIXI.Container}. Scaling. The height property calculates scale.y by dividing
  481. * the "requested" height by the local bounding box height. It is indirectly an abstraction over scale.y, and there
  482. * is no concept of user-defined height.
  483. * </td>
  484. * </tr>
  485. * </tbody>
  486. * </table>
  487. *
  488. * ## Bounds
  489. *
  490. * The bounds of a display object is defined by the minimum axis-aligned rectangle in world space that can fit
  491. * around it. The abstract `calculateBounds` method is responsible for providing it (and it should use the
  492. * `worldTransform` to calculate in world space).
  493. *
  494. * There are a few additional types of bounding boxes:
  495. *
  496. * | Bounds | Description |
  497. * | --------------------- | ---------------------------------------------------------------------------------------- |
  498. * | World Bounds | This is synonymous is the regular bounds described above. See `getBounds()`. |
  499. * | Local Bounds | This the axis-aligned bounding box in the parent's local space. See `getLocalBounds()`. |
  500. * | Render Bounds | The bounds, but including extra rendering effects like filter padding. |
  501. * | Projected Bounds | The bounds of the projected display object onto the screen. Usually equals world bounds. |
  502. * | Relative Bounds | The bounds of a display object when projected onto a ancestor's (or parent's) space. |
  503. * | Natural Bounds | The bounds of an object in its own local space (not parent's space, like in local bounds)|
  504. * | Content Bounds | The natural bounds when excluding all children of a `Container`. |
  505. *
  506. * ### calculateBounds
  507. *
  508. * [Container]{@link Container} already implements `calculateBounds` in a manner that includes children.
  509. *
  510. * But for a non-Container display object, the `calculateBounds` method must be overridden in order for `getBounds` and
  511. * `getLocalBounds` to work. This method must write the bounds into `this._bounds`.
  512. *
  513. * Generally, the following technique works for most simple cases: take the list of points
  514. * forming the "hull" of the object (i.e. outline of the object's shape), and then add them
  515. * using {@link PIXI.Bounds#addPointMatrix}.
  516. *
  517. * ```js
  518. * calculateBounds(): void
  519. * {
  520. * const points = [...];
  521. *
  522. * for (let i = 0, j = points.length; i < j; i++)
  523. * {
  524. * this._bounds.addPointMatrix(this.worldTransform, points[i]);
  525. * }
  526. * }
  527. * ```
  528. *
  529. * You can optimize this for a large number of points by using {@link PIXI.Bounds#addVerticesMatrix} to pass them
  530. * in one array together.
  531. *
  532. * ## Alpha
  533. *
  534. * This alpha sets a display object's **relative opacity** w.r.t its parent. For example, if the alpha of a display
  535. * object is 0.5 and its parent's alpha is 0.5, then it will be rendered with 25% opacity (assuming alpha is not
  536. * applied on any ancestor further up the chain).
  537. *
  538. * The alpha with which the display object will be rendered is called the [worldAlpha]{@link PIXI.DisplayObject#worldAlpha}.
  539. *
  540. * ## Renderable vs Visible
  541. *
  542. * The `renderable` and `visible` properties can be used to prevent a display object from being rendered to the
  543. * screen. However, there is a subtle difference between the two. When using `renderable`, the transforms of the display
  544. * object (and its children subtree) will continue to be calculated. When using `visible`, the transforms will not
  545. * be calculated.
  546. *
  547. * It is recommended that applications use the `renderable` property for culling. See
  548. * [@pixi-essentials/cull]{@link https://www.npmjs.com/package/@pixi-essentials/cull} or
  549. * [pixi-cull]{@link https://www.npmjs.com/package/pixi-cull} for more details.
  550. *
  551. * Otherwise, to prevent an object from rendering in the general-purpose sense - `visible` is the property to use. This
  552. * one is also better in terms of performance.
  553. * @memberof PIXI
  554. */
  555. export declare abstract class DisplayObject extends EventEmitter {
  556. abstract sortDirty: boolean;
  557. /** The display object container that contains this display object. */
  558. parent: Container;
  559. /**
  560. * The multiplied alpha of the displayObject.
  561. * @readonly
  562. */
  563. worldAlpha: number;
  564. /**
  565. * World transform and local transform of this object.
  566. * This will become read-only later, please do not assign anything there unless you know what are you doing.
  567. */
  568. transform: Transform;
  569. /** The opacity of the object. */
  570. alpha: number;
  571. /**
  572. * The visibility of the object. If false the object will not be drawn, and
  573. * the updateTransform function will not be called.
  574. *
  575. * Only affects recursive calls from parent. You can ask for bounds or call updateTransform manually.
  576. */
  577. visible: boolean;
  578. /**
  579. * Can this object be rendered, if false the object will not be drawn but the updateTransform
  580. * methods will still be called.
  581. *
  582. * Only affects recursive calls from parent. You can ask for bounds manually.
  583. */
  584. renderable: boolean;
  585. /**
  586. * Should this object be rendered if the bounds of this object are out of frame?
  587. *
  588. * Culling has no effect on whether updateTransform is called.
  589. */
  590. cullable: boolean;
  591. /**
  592. * If set, this shape is used for culling instead of the bounds of this object.
  593. * It can improve the culling performance of objects with many children.
  594. * The culling area is defined in local space.
  595. */
  596. cullArea: Rectangle;
  597. /**
  598. * The area the filter is applied to. This is used as more of an optimization
  599. * rather than figuring out the dimensions of the displayObject each frame you can set this rectangle.
  600. *
  601. * Also works as an interaction mask.
  602. */
  603. filterArea: Rectangle;
  604. /**
  605. * Sets the filters for the displayObject.
  606. * IMPORTANT: This is a WebGL only feature and will be ignored by the canvas renderer.
  607. * To remove filters simply set this property to `'null'`.
  608. */
  609. filters: Filter[] | null;
  610. /** Used to fast check if a sprite is.. a sprite! */
  611. isSprite: boolean;
  612. /** Does any other displayObject use this object as a mask? */
  613. isMask: boolean;
  614. /**
  615. * Which index in the children array the display component was before the previous zIndex sort.
  616. * Used by containers to help sort objects with the same zIndex, by using previous array index as the decider.
  617. * @protected
  618. */
  619. _lastSortedIndex: number;
  620. /**
  621. * The original, cached mask of the object.
  622. * @protected
  623. */
  624. _mask: Container | MaskData;
  625. /** The bounds object, this is used to calculate and store the bounds of the displayObject. */
  626. _bounds: Bounds;
  627. /** Local bounds object, swapped with `_bounds` when using `getLocalBounds()`. */
  628. _localBounds: Bounds;
  629. /**
  630. * The zIndex of the displayObject.
  631. * A higher value will mean it will be rendered on top of other displayObjects within the same container.
  632. * @protected
  633. */
  634. protected _zIndex: number;
  635. /**
  636. * Currently enabled filters.
  637. * @protected
  638. */
  639. protected _enabledFilters: Filter[];
  640. /** Flags the cached bounds as dirty. */
  641. protected _boundsID: number;
  642. /** Cache of this display-object's bounds-rectangle. */
  643. protected _boundsRect: Rectangle;
  644. /** Cache of this display-object's local-bounds rectangle. */
  645. protected _localBoundsRect: Rectangle;
  646. /** If the object has been destroyed via destroy(). If true, it should not be used. */
  647. protected _destroyed: boolean;
  648. /** The number of times this object is used as a mask by another object. */
  649. private _maskRefCount;
  650. private tempDisplayObjectParent;
  651. displayObjectUpdateTransform: () => void;
  652. /**
  653. * Mixes all enumerable properties and methods from a source object to DisplayObject.
  654. * @param source - The source of properties and methods to mix in.
  655. */
  656. static mixin(source: Dict<any>): void;
  657. constructor();
  658. /**
  659. * Fired when this DisplayObject is added to a Container.
  660. * @instance
  661. * @event added
  662. * @param {PIXI.Container} container - The container added to.
  663. */
  664. /**
  665. * Fired when this DisplayObject is removed from a Container.
  666. * @instance
  667. * @event removed
  668. * @param {PIXI.Container} container - The container removed from.
  669. */
  670. /**
  671. * Fired when this DisplayObject is destroyed. This event is emitted once
  672. * destroy is finished.
  673. * @instance
  674. * @event destroyed
  675. */
  676. /** Readonly flag for destroyed display objects. */
  677. get destroyed(): boolean;
  678. /** Recalculates the bounds of the display object. */
  679. abstract calculateBounds(): void;
  680. abstract removeChild(child: DisplayObject): void;
  681. /**
  682. * Renders the object using the WebGL renderer.
  683. * @param renderer - The renderer.
  684. */
  685. abstract render(renderer: Renderer): void;
  686. /** Recursively updates transform of all objects from the root to this one internal function for toLocal() */
  687. protected _recursivePostUpdateTransform(): void;
  688. /** Updates the object transform for rendering. TODO - Optimization pass! */
  689. updateTransform(): void;
  690. /**
  691. * Calculates and returns the (world) bounds of the display object as a [Rectangle]{@link PIXI.Rectangle}.
  692. *
  693. * This method is expensive on containers with a large subtree (like the stage). This is because the bounds
  694. * of a container depend on its children's bounds, which recursively causes all bounds in the subtree to
  695. * be recalculated. The upside, however, is that calling `getBounds` once on a container will indeed update
  696. * the bounds of all children (the whole subtree, in fact). This side effect should be exploited by using
  697. * `displayObject._bounds.getRectangle()` when traversing through all the bounds in a scene graph. Otherwise,
  698. * calling `getBounds` on each object in a subtree will cause the total cost to increase quadratically as
  699. * its height increases.
  700. *
  701. * The transforms of all objects in a container's **subtree** and of all **ancestors** are updated.
  702. * The world bounds of all display objects in a container's **subtree** will also be recalculated.
  703. *
  704. * The `_bounds` object stores the last calculation of the bounds. You can use to entirely skip bounds
  705. * calculation if needed.
  706. *
  707. * ```js
  708. * const lastCalculatedBounds = displayObject._bounds.getRectangle(optionalRect);
  709. * ```
  710. *
  711. * Do know that usage of `getLocalBounds` can corrupt the `_bounds` of children (the whole subtree, actually). This
  712. * is a known issue that has not been solved. See [getLocalBounds]{@link PIXI.DisplayObject#getLocalBounds} for more
  713. * details.
  714. *
  715. * `getBounds` should be called with `skipUpdate` equal to `true` in a render() call. This is because the transforms
  716. * are guaranteed to be update-to-date. In fact, recalculating inside a render() call may cause corruption in certain
  717. * cases.
  718. * @param skipUpdate - Setting to `true` will stop the transforms of the scene graph from
  719. * being updated. This means the calculation returned MAY be out of date BUT will give you a
  720. * nice performance boost.
  721. * @param rect - Optional rectangle to store the result of the bounds calculation.
  722. * @returns - The minimum axis-aligned rectangle in world space that fits around this object.
  723. */
  724. getBounds(skipUpdate?: boolean, rect?: Rectangle): Rectangle;
  725. /**
  726. * Retrieves the local bounds of the displayObject as a rectangle object.
  727. * @param rect - Optional rectangle to store the result of the bounds calculation.
  728. * @returns - The rectangular bounding area.
  729. */
  730. getLocalBounds(rect?: Rectangle): Rectangle;
  731. /**
  732. * Calculates the global position of the display object.
  733. * @param position - The world origin to calculate from.
  734. * @param point - A Point object in which to store the value, optional
  735. * (otherwise will create a new Point).
  736. * @param skipUpdate - Should we skip the update transform.
  737. * @returns - A point object representing the position of this object.
  738. */
  739. toGlobal<P extends IPointData = Point>(position: IPointData, point?: P, skipUpdate?: boolean): P;
  740. /**
  741. * Calculates the local position of the display object relative to another point.
  742. * @param position - The world origin to calculate from.
  743. * @param from - The DisplayObject to calculate the global position from.
  744. * @param point - A Point object in which to store the value, optional
  745. * (otherwise will create a new Point).
  746. * @param skipUpdate - Should we skip the update transform
  747. * @returns - A point object representing the position of this object
  748. */
  749. toLocal<P extends IPointData = Point>(position: IPointData, from?: DisplayObject, point?: P, skipUpdate?: boolean): P;
  750. /**
  751. * Set the parent Container of this DisplayObject.
  752. * @param container - The Container to add this DisplayObject to.
  753. * @returns - The Container that this DisplayObject was added to.
  754. */
  755. setParent(container: Container): Container;
  756. /**
  757. * Convenience function to set the position, scale, skew and pivot at once.
  758. * @param x - The X position
  759. * @param y - The Y position
  760. * @param scaleX - The X scale value
  761. * @param scaleY - The Y scale value
  762. * @param rotation - The rotation
  763. * @param skewX - The X skew value
  764. * @param skewY - The Y skew value
  765. * @param pivotX - The X pivot value
  766. * @param pivotY - The Y pivot value
  767. * @returns - The DisplayObject instance
  768. */
  769. setTransform(x?: number, y?: number, scaleX?: number, scaleY?: number, rotation?: number, skewX?: number, skewY?: number, pivotX?: number, pivotY?: number): this;
  770. /**
  771. * Base destroy method for generic display objects. This will automatically
  772. * remove the display object from its parent Container as well as remove
  773. * all current event listeners and internal references. Do not use a DisplayObject
  774. * after calling `destroy()`.
  775. * @param _options
  776. */
  777. destroy(_options?: IDestroyOptions | boolean): void;
  778. /**
  779. * @protected
  780. * @member {PIXI.Container}
  781. */
  782. get _tempDisplayObjectParent(): TemporaryDisplayObject;
  783. /**
  784. * Used in Renderer, cacheAsBitmap and other places where you call an `updateTransform` on root
  785. *
  786. * ```
  787. * const cacheParent = elem.enableTempParent();
  788. * elem.updateTransform();
  789. * elem.disableTempParent(cacheParent);
  790. * ```
  791. * @returns - current parent
  792. */
  793. enableTempParent(): Container;
  794. /**
  795. * Pair method for `enableTempParent`
  796. * @param cacheParent - Actual parent of element
  797. */
  798. disableTempParent(cacheParent: Container): void;
  799. /**
  800. * The position of the displayObject on the x axis relative to the local coordinates of the parent.
  801. * An alias to position.x
  802. */
  803. get x(): number;
  804. set x(value: number);
  805. /**
  806. * The position of the displayObject on the y axis relative to the local coordinates of the parent.
  807. * An alias to position.y
  808. */
  809. get y(): number;
  810. set y(value: number);
  811. /**
  812. * Current transform of the object based on world (parent) factors.
  813. * @readonly
  814. */
  815. get worldTransform(): Matrix;
  816. /**
  817. * Current transform of the object based on local factors: position, scale, other stuff.
  818. * @readonly
  819. */
  820. get localTransform(): Matrix;
  821. /**
  822. * The coordinate of the object relative to the local coordinates of the parent.
  823. * @since 4.0.0
  824. */
  825. get position(): ObservablePoint;
  826. set position(value: IPointData);
  827. /**
  828. * The scale factors of this object along the local coordinate axes.
  829. *
  830. * The default scale is (1, 1).
  831. * @since 4.0.0
  832. */
  833. get scale(): ObservablePoint;
  834. set scale(value: IPointData);
  835. /**
  836. * The center of rotation, scaling, and skewing for this display object in its local space. The `position`
  837. * is the projection of `pivot` in the parent's local space.
  838. *
  839. * By default, the pivot is the origin (0, 0).
  840. * @since 4.0.0
  841. */
  842. get pivot(): ObservablePoint;
  843. set pivot(value: IPointData);
  844. /**
  845. * The skew factor for the object in radians.
  846. * @since 4.0.0
  847. */
  848. get skew(): ObservablePoint;
  849. set skew(value: IPointData);
  850. /**
  851. * The rotation of the object in radians.
  852. * 'rotation' and 'angle' have the same effect on a display object; rotation is in radians, angle is in degrees.
  853. */
  854. get rotation(): number;
  855. set rotation(value: number);
  856. /**
  857. * The angle of the object in degrees.
  858. * 'rotation' and 'angle' have the same effect on a display object; rotation is in radians, angle is in degrees.
  859. */
  860. get angle(): number;
  861. set angle(value: number);
  862. /**
  863. * The zIndex of the displayObject.
  864. *
  865. * If a container has the sortableChildren property set to true, children will be automatically
  866. * sorted by zIndex value; a higher value will mean it will be moved towards the end of the array,
  867. * and thus rendered on top of other display objects within the same container.
  868. * @see PIXI.Container#sortableChildren
  869. */
  870. get zIndex(): number;
  871. set zIndex(value: number);
  872. /**
  873. * Indicates if the object is globally visible.
  874. * @readonly
  875. */
  876. get worldVisible(): boolean;
  877. /**
  878. * Sets a mask for the displayObject. A mask is an object that limits the visibility of an
  879. * object to the shape of the mask applied to it. In PixiJS a regular mask must be a
  880. * {@link PIXI.Graphics} or a {@link PIXI.Sprite} object. This allows for much faster masking in canvas as it
  881. * utilities shape clipping. Furthermore, a mask of an object must be in the subtree of its parent.
  882. * Otherwise, `getLocalBounds` may calculate incorrect bounds, which makes the container's width and height wrong.
  883. * To remove a mask, set this property to `null`.
  884. *
  885. * For sprite mask both alpha and red channel are used. Black mask is the same as transparent mask.
  886. * @example
  887. * const graphics = new PIXI.Graphics();
  888. * graphics.beginFill(0xFF3300);
  889. * graphics.drawRect(50, 250, 100, 100);
  890. * graphics.endFill();
  891. *
  892. * const sprite = new PIXI.Sprite(texture);
  893. * sprite.mask = graphics;
  894. * @todo At the moment, PIXI.CanvasRenderer doesn't support PIXI.Sprite as mask.
  895. */
  896. get mask(): Container | MaskData | null;
  897. set mask(value: Container | MaskData | null);
  898. }
  899. export declare interface IDestroyOptions {
  900. children?: boolean;
  901. texture?: boolean;
  902. baseTexture?: boolean;
  903. }
  904. /**
  905. * @private
  906. */
  907. export declare class TemporaryDisplayObject extends DisplayObject {
  908. calculateBounds: () => null;
  909. removeChild: (child: DisplayObject) => null;
  910. render: (renderer: Renderer) => null;
  911. sortDirty: boolean;
  912. }
  913. export { }