import { MASK_TYPES, settings, utils } from '@pixi/core';
import { DisplayObject } from './DisplayObject';
import type { MaskData, Renderer, Matrix, Rectangle } from '@pixi/core';
import type { IDestroyOptions } from './DisplayObject';
function sortChildren(a: DisplayObject, b: DisplayObject): number
{
if (a.zIndex === b.zIndex)
{
return a._lastSortedIndex - b._lastSortedIndex;
}
return a.zIndex - b.zIndex;
}
export interface Container extends GlobalMixins.Container, DisplayObject {}
/**
* Container is a general-purpose display object that holds children. It also adds built-in support for advanced
* rendering features like masking and filtering.
*
* It is the base class of all display objects that act as a container for other objects, including Graphics
* and Sprite.
*
* ```js
* import { BlurFilter } from '@pixi/filter-blur';
* import { Container } from '@pixi/display';
* import { Graphics } from '@pixi/graphics';
* import { Sprite } from '@pixi/sprite';
*
* let container = new Container();
* let sprite = Sprite.from("https://s3-us-west-2.amazonaws.com/s.cdpn.io/693612/IaUrttj.png");
*
* sprite.width = 512;
* sprite.height = 512;
*
* // Adds a sprite as a child to this container. As a result, the sprite will be rendered whenever the container
* // is rendered.
* container.addChild(sprite);
*
* // Blurs whatever is rendered by the container
* container.filters = [new BlurFilter()];
*
* // Only the contents within a circle at the center should be rendered onto the screen.
* container.mask = new Graphics()
* .beginFill(0xffffff)
* .drawCircle(sprite.width / 2, sprite.height / 2, Math.min(sprite.width, sprite.height) / 2)
* .endFill();
* ```
* @memberof PIXI
*/
export class Container<T extends DisplayObject = DisplayObject> extends DisplayObject
{
/**
* The array of children of this container.
* @readonly
*/
public readonly children: T[];
/**
* If set to true, the container will sort its children by zIndex value
* when updateTransform() is called, or manually if sortChildren() is called.
*
* This actually changes the order of elements in the array, so should be treated
* as a basic solution that is not performant compared to other solutions,
* such as @link https://github.com/pixijs/pixi-display
*
* Also be aware of that this may not work nicely with the addChildAt() function,
* as the zIndex sorting may cause the child to automatically sorted to another position.
* @see PIXI.settings.SORTABLE_CHILDREN
*/
public sortableChildren: boolean;
/**
* Should children be sorted by zIndex at the next updateTransform call.
*
* Will get automatically set to true if a new child is added, or if a child's zIndex changes.
*/
public sortDirty: boolean;
public parent: Container;
public containerUpdateTransform: () => void;
protected _width: number;
protected _height: number;
constructor()
{
super();
this.children = [];
this.sortableChildren = settings.SORTABLE_CHILDREN;
this.sortDirty = false;
/**
* Fired when a DisplayObject is added to this Container.
* @event PIXI.Container#childAdded
* @param {PIXI.DisplayObject} child - The child added to the Container.
* @param {PIXI.Container} container - The container that added the child.
* @param {number} index - The children's index of the added child.
*/
/**
* Fired when a DisplayObject is removed from this Container.
* @event PIXI.DisplayObject#childRemoved
* @param {PIXI.DisplayObject} child - The child removed from the Container.
* @param {PIXI.Container} container - The container that removed the child.
* @param {number} index - The former children's index of the removed child
*/
}
/**
* Overridable method that can be used by Container subclasses whenever the children array is modified.
* @param _length
*/
protected onChildrenChange(_length?: number): void
{
/* empty */
}
/**
* Adds one or more children to the container.
*
* Multiple items can be added like so: `myContainer.addChild(thingOne, thingTwo, thingThree)`
* @param {...PIXI.DisplayObject} children - The DisplayObject(s) to add to the container
* @returns {PIXI.DisplayObject} - The first child that was added.
*/
addChild<U extends T[]>(...children: U): U[0]
{
// if there is only one argument we can bypass looping through the them
if (children.length > 1)
{
// loop through the array and add all children
for (let i = 0; i < children.length; i++)
{
// eslint-disable-next-line prefer-rest-params
this.addChild(children[i]);
}
}
else
{
const child = children[0];
// if the child has a parent then lets remove it as PixiJS objects can only exist in one place
if (child.parent)
{
child.parent.removeChild(child);
}
child.parent = this;
this.sortDirty = true;
// ensure child transform will be recalculated
child.transform._parentID = -1;
this.children.push(child);
// ensure bounds will be recalculated
this._boundsID++;
// TODO - lets either do all callbacks or all events.. not both!
this.onChildrenChange(this.children.length - 1);
this.emit('childAdded', child, this, this.children.length - 1);
child.emit('added', this);
}
return children[0];
}
/**
* Adds a child to the container at a specified index. If the index is out of bounds an error will be thrown
* @param {PIXI.DisplayObject} child - The child to add
* @param {number} index - The index to place the child in
* @returns {PIXI.DisplayObject} The child that was added.
*/
addChildAt<U extends T>(child: U, index: number): U
{
if (index < 0 || index > this.children.length)
{
throw new Error(`${child}addChildAt: The index ${index} supplied is out of bounds ${this.children.length}`);
}
if (child.parent)
{
child.parent.removeChild(child);
}
child.parent = this;
this.sortDirty = true;
// ensure child transform will be recalculated
child.transform._parentID = -1;
this.children.splice(index, 0, child);
// ensure bounds will be recalculated
this._boundsID++;
// TODO - lets either do all callbacks or all events.. not both!
this.onChildrenChange(index);
child.emit('added', this);
this.emit('childAdded', child, this, index);
return child;
}
/**
* Swaps the position of 2 Display Objects within this container.
* @param child - First display object to swap
* @param child2 - Second display object to swap
*/
swapChildren(child: T, child2: T): void
{
if (child === child2)
{
return;
}
const index1 = this.getChildIndex(child);
const index2 = this.getChildIndex(child2);
this.children[index1] = child2;
this.children[index2] = child;
this.onChildrenChange(index1 < index2 ? index1 : index2);
}
/**
* Returns the index position of a child DisplayObject instance
* @param child - The DisplayObject instance to identify
* @returns - The index position of the child display object to identify
*/
getChildIndex(child: T): number
{
const index = this.children.indexOf(child);
if (index === -1)
{
throw new Error('The supplied DisplayObject must be a child of the caller');
}
return index;
}
/**
* Changes the position of an existing child in the display object container
* @param child - The child DisplayObject instance for which you want to change the index number
* @param index - The resulting index number for the child display object
*/
setChildIndex(child: T, index: number): void
{
if (index < 0 || index >= this.children.length)
{
throw new Error(`The index ${index} supplied is out of bounds ${this.children.length}`);
}
const currentIndex = this.getChildIndex(child);
utils.removeItems(this.children, currentIndex, 1); // remove from old position
this.children.splice(index, 0, child); // add at new position
this.onChildrenChange(index);
}
/**
* Returns the child at the specified index
* @param index - The index to get the child at
* @returns - The child at the given index, if any.
*/
getChildAt(index: number): T
{
if (index < 0 || index >= this.children.length)
{
throw new Error(`getChildAt: Index (${index}) does not exist.`);
}
return this.children[index];
}
/**
* Removes one or more children from the container.
* @param {...PIXI.DisplayObject} children - The DisplayObject(s) to remove
* @returns {PIXI.DisplayObject} The first child that was removed.
*/
removeChild<U extends T[]>(...children: U): U[0]
{
// if there is only one argument we can bypass looping through the them
if (children.length > 1)
{
// loop through the arguments property and remove all children
for (let i = 0; i < children.length; i++)
{
this.removeChild(children[i]);
}
}
else
{
const child = children[0];
const index = this.children.indexOf(child);
if (index === -1) return null;
child.parent = null;
// ensure child transform will be recalculated
child.transform._parentID = -1;
utils.removeItems(this.children, index, 1);
// ensure bounds will be recalculated
this._boundsID++;
// TODO - lets either do all callbacks or all events.. not both!
this.onChildrenChange(index);
child.emit('removed', this);
this.emit('childRemoved', child, this, index);
}
return children[0];
}
/**
* Removes a child from the specified index position.
* @param index - The index to get the child from
* @returns The child that was removed.
*/
removeChildAt(index: number): T
{
const child = this.getChildAt(index);
// ensure child transform will be recalculated..
child.parent = null;
child.transform._parentID = -1;
utils.removeItems(this.children, index, 1);
// ensure bounds will be recalculated
this._boundsID++;
// TODO - lets either do all callbacks or all events.. not both!
this.onChildrenChange(index);
child.emit('removed', this);
this.emit('childRemoved', child, this, index);
return child;
}
/**
* Removes all children from this container that are within the begin and end indexes.
* @param beginIndex - The beginning position.
* @param endIndex - The ending position. Default value is size of the container.
* @returns - List of removed children
*/
removeChildren(beginIndex = 0, endIndex = this.children.length): T[]
{
const begin = beginIndex;
const end = endIndex;
const range = end - begin;
let removed;
if (range > 0 && range <= end)
{
removed = this.children.splice(begin, range);
for (let i = 0; i < removed.length; ++i)
{
removed[i].parent = null;
if (removed[i].transform)
{
removed[i].transform._parentID = -1;
}
}
this._boundsID++;
this.onChildrenChange(beginIndex);
for (let i = 0; i < removed.length; ++i)
{
removed[i].emit('removed', this);
this.emit('childRemoved', removed[i], this, i);
}
return removed;
}
else if (range === 0 && this.children.length === 0)
{
return [];
}
throw new RangeError('removeChildren: numeric values are outside the acceptable range.');
}
/** Sorts children by zIndex. Previous order is maintained for 2 children with the same zIndex. */
sortChildren(): void
{
let sortRequired = false;
for (let i = 0, j = this.children.length; i < j; ++i)
{
const child = this.children[i];
child._lastSortedIndex = i;
if (!sortRequired && child.zIndex !== 0)
{
sortRequired = true;
}
}
if (sortRequired && this.children.length > 1)
{
this.children.sort(sortChildren);
}
this.sortDirty = false;
}
/** Updates the transform on all children of this container for rendering. */
updateTransform(): void
{
if (this.sortableChildren && this.sortDirty)
{
this.sortChildren();
}
this._boundsID++;
this.transform.updateTransform(this.parent.transform);
// TODO: check render flags, how to process stuff here
this.worldAlpha = this.alpha * this.parent.worldAlpha;
for (let i = 0, j = this.children.length; i < j; ++i)
{
const child = this.children[i];
if (child.visible)
{
child.updateTransform();
}
}
}
/**
* Recalculates the bounds of the container.
*
* This implementation will automatically fit the children's bounds into the calculation. Each child's bounds
* is limited to its mask's bounds or filterArea, if any is applied.
*/
calculateBounds(): void
{
this._bounds.clear();
this._calculateBounds();
for (let i = 0; i < this.children.length; i++)
{
const child = this.children[i];
if (!child.visible || !child.renderable)
{
continue;
}
child.calculateBounds();
// TODO: filter+mask, need to mask both somehow
if (child._mask)
{
const maskObject = ((child._mask as MaskData).isMaskData
? (child._mask as MaskData).maskObject : child._mask) as Container;
if (maskObject)
{
maskObject.calculateBounds();
this._bounds.addBoundsMask(child._bounds, maskObject._bounds);
}
else
{
this._bounds.addBounds(child._bounds);
}
}
else if (child.filterArea)
{
this._bounds.addBoundsArea(child._bounds, child.filterArea);
}
else
{
this._bounds.addBounds(child._bounds);
}
}
this._bounds.updateID = this._boundsID;
}
/**
* Retrieves the local bounds of the displayObject as a rectangle object.
*
* Calling `getLocalBounds` may invalidate the `_bounds` of the whole subtree below. If using it inside a render()
* call, it is advised to call `getBounds()` immediately after to recalculate the world bounds of the subtree.
* @param rect - Optional rectangle to store the result of the bounds calculation.
* @param skipChildrenUpdate - Setting to `true` will stop re-calculation of children transforms,
* it was default behaviour of pixi 4.0-5.2 and caused many problems to users.
* @returns - The rectangular bounding area.
*/
public getLocalBounds(rect?: Rectangle, skipChildrenUpdate = false): Rectangle
{
const result = super.getLocalBounds(rect);
if (!skipChildrenUpdate)
{
for (let i = 0, j = this.children.length; i < j; ++i)
{
const child = this.children[i];
if (child.visible)
{
child.updateTransform();
}
}
}
return result;
}
/**
* Recalculates the content bounds of this object. This should be overriden to
* calculate the bounds of this specific object (not including children).
* @protected
*/
protected _calculateBounds(): void
{
// FILL IN//
}
/**
* Renders this object and its children with culling.
* @protected
* @param {PIXI.Renderer} renderer - The renderer
*/
protected _renderWithCulling(renderer: Renderer): void
{
const sourceFrame = renderer.renderTexture.sourceFrame;
// If the source frame is empty, stop rendering.
if (!(sourceFrame.width > 0 && sourceFrame.height > 0))
{
return;
}
// Render the content of the container only if its bounds intersect with the source frame.
// All filters are on the stack at this point, and the filter source frame is bound:
// therefore, even if the bounds to non intersect the filter frame, the filter
// is still applied and any filter padding that is in the frame is rendered correctly.
let bounds: Rectangle;
let transform: Matrix;
// If cullArea is set, we use this rectangle instead of the bounds of the object. The cullArea
// rectangle must completely contain the container and its children including filter padding.
if (this.cullArea)
{
bounds = this.cullArea;
transform = this.worldTransform;
}
// If the container doesn't override _render, we can skip the bounds calculation and intersection test.
else if (this._render !== Container.prototype._render)
{
bounds = this.getBounds(true);
}
// Render the container if the source frame intersects the bounds.
if (bounds && sourceFrame.intersects(bounds, transform))
{
this._render(renderer);
}
// If the bounds are defined by cullArea and do not intersect with the source frame, stop rendering.
else if (this.cullArea)
{
return;
}
// Unless cullArea is set, we cannot skip the children if the bounds of the container do not intersect
// the source frame, because the children might have filters with nonzero padding, which may intersect
// with the source frame while the bounds do not: filter padding is not included in the bounds.
// If cullArea is not set, render the children with culling temporarily enabled so that they are not rendered
// if they are out of frame; otherwise, render the children normally.
for (let i = 0, j = this.children.length; i < j; ++i)
{
const child = this.children[i];
const childCullable = child.cullable;
child.cullable = childCullable || !this.cullArea;
child.render(renderer);
child.cullable = childCullable;
}
}
/**
* Renders the object using the WebGL renderer.
*
* The _render method is be overriden for rendering the contents of the
* container itself. This `render` method will invoke it, and also invoke the `render` methods of all
* children afterward.
*
* If `renderable` or `visible` is false or if `worldAlpha` is not positive or if `cullable` is true and
* the bounds of this object are out of frame, this implementation will entirely skip rendering.
* See PIXI.DisplayObject for choosing between `renderable` or `visible`. Generally,
* setting alpha to zero is not recommended for purely skipping rendering.
*
* When your scene becomes large (especially when it is larger than can be viewed in a single screen), it is
* advised to employ **culling** to automatically skip rendering objects outside of the current screen.
* See cullable and cullArea.
* Other culling methods might be better suited for a large number static objects; see
* @pixi-essentials/cull and
* pixi-cull.
*
* The renderAdvanced method is internally used when when masking or
* filtering is applied on a container. This does, however, break batching and can affect performance when
* masking and filtering is applied extensively throughout the scene graph.
* @param renderer - The renderer
*/
render(renderer: Renderer): void
{
// if the object is not visible or the alpha is 0 then no need to render this element
if (!this.visible || this.worldAlpha <= 0 || !this.renderable)
{
return;
}
// do a quick check to see if this element has a mask or a filter.
if (this._mask || this.filters?.length)
{
this.renderAdvanced(renderer);
}
else if (this.cullable)
{
this._renderWithCulling(renderer);
}
else
{
this._render(renderer);
for (let i = 0, j = this.children.length; i < j; ++i)
{
this.children[i].render(renderer);
}
}
}
/**
* Render the object using the WebGL renderer and advanced features.
* @param renderer - The renderer
*/
protected renderAdvanced(renderer: Renderer): void
{
const filters = this.filters;
const mask = this._mask as MaskData;
// push filter first as we need to ensure the stencil buffer is correct for any masking
if (filters)
{
if (!this._enabledFilters)
{
this._enabledFilters = [];
}
this._enabledFilters.length = 0;
for (let i = 0; i < filters.length; i++)
{
if (filters[i].enabled)
{
this._enabledFilters.push(filters[i]);
}
}
}
const flush = (filters && this._enabledFilters?.length)
|| (mask && (!mask.isMaskData
|| (mask.enabled && (mask.autoDetect || mask.type !== MASK_TYPES.NONE))));
if (flush)
{
renderer.batch.flush();
}
if (filters && this._enabledFilters?.length)
{
renderer.filter.push(this, this._enabledFilters);
}
if (mask)
{
renderer.mask.push(this, this._mask);
}
if (this.cullable)
{
this._renderWithCulling(renderer);
}
else
{
this._render(renderer);
for (let i = 0, j = this.children.length; i < j; ++i)
{
this.children[i].render(renderer);
}
}
if (flush)
{
renderer.batch.flush();
}
if (mask)
{
renderer.mask.pop(this);
}
if (filters && this._enabledFilters?.length)
{
renderer.filter.pop();
}
}
/**
* To be overridden by the subclasses.
* @param _renderer - The renderer
*/
protected _render(_renderer: Renderer): void // eslint-disable-line no-unused-vars
{
// this is where content itself gets rendered...
}
/**
* Removes all internal references and listeners as well as removes children from the display list.
* Do not use a Container after calling `destroy`.
* @param options - Options parameter. A boolean will act as if all options
* have been set to that value
* @param {boolean} [options.children=false] - if set to true, all the children will have their destroy
* method called as well. 'options' will be passed on to those calls.
* @param {boolean} [options.texture=false] - Only used for child Sprites if options.children is set to true
* Should it destroy the texture of the child sprite
* @param {boolean} [options.baseTexture=false] - Only used for child Sprites if options.children is set to true
* Should it destroy the base texture of the child sprite
*/
destroy(options?: IDestroyOptions | boolean): void
{
super.destroy();
this.sortDirty = false;
const destroyChildren = typeof options === 'boolean' ? options : options?.children;
const oldChildren = this.removeChildren(0, this.children.length);
if (destroyChildren)
{
for (let i = 0; i < oldChildren.length; ++i)
{
oldChildren[i].destroy(options);
}
}
}
/** The width of the Container, setting this will actually modify the scale to achieve the value set. */
get width(): number
{
return this.scale.x * this.getLocalBounds().width;
}
set width(value: number)
{
const width = this.getLocalBounds().width;
if (width !== 0)
{
this.scale.x = value / width;
}
else
{
this.scale.x = 1;
}
this._width = value;
}
/** The height of the Container, setting this will actually modify the scale to achieve the value set. */
get height(): number
{
return this.scale.y * this.getLocalBounds().height;
}
set height(value: number)
{
const height = this.getLocalBounds().height;
if (height !== 0)
{
this.scale.y = value / height;
}
else
{
this.scale.y = 1;
}
this._height = value;
}
}
/**
* Container default updateTransform, does update children of container.
* Will crash if there's no parent element.
* @memberof PIXI.Container#
* @method containerUpdateTransform
*/
Container.prototype.containerUpdateTransform = Container.prototype.updateTransform;