PerspectiveMesh
Renders a PIXI.PerspectiveMesh.
PIXI.PerspectiveMesh description from PixiJS
sourceContainer 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.
Transforms
The [transform]{@link Container#localTransform} of a display object describes the projection from its local coordinate space to its parent's local coordinate space. The following properties are derived from the transform:
| Property | Description |
|---|---|
| [pivot]{@link Container#pivot} | Invariant under rotation, scaling, and skewing. The projection of into the parent's space of the pivot is equal to position, regardless of the other three transformations. In other words, It is the center of rotation, scaling, and skewing. |
| [position]{@link Container#position} | Translation. This is the position of the [pivot]{@link Container#pivot} in the parent's local space. The default value of the pivot is the origin (0,0). If the top-left corner of your display object is (0,0) in its local space, then the position will be its top-left corner in the parent's local space. |
| [scale]{@link Container#scale} | Scaling. This will stretch (or compress) the display object's projection. The scale factors are along the local coordinate axes. In other words, the display object is scaled before rotated or skewed. The center of scaling is the [pivot]{@link Container#pivot}. |
| [rotation]{@link Container#rotation} | Rotation. This will rotate the display object's projection by this angle (in radians). |
| [skew]{@link Container#skew} |
Skewing. This can be used to deform a rectangular display object into a parallelogram. In PixiJS, skew has a slightly different behaviour than the conventional meaning. It can be thought of the net rotation applied to the coordinate axes (separately). For example, if "skew.x" is ⍺ and "skew.y" is β, then the line x = 0 will be rotated by ⍺ (y = -x*cot⍺) and the line y = 0 will be rotated by β (y = x*tanβ). A line y = x*tanϴ (i.e. a line at angle ϴ to the x-axis in local-space) will be rotated by an angle between ⍺ and β. It can be observed that if skew is applied equally to both axes, then it will be equivalent to applying a rotation. Indeed, if "skew.x" = -ϴ and "skew.y" = ϴ, it will produce an equivalent of "rotation" = ϴ. Another quite interesting observation is that "skew.x", "skew.y", rotation are commutative operations. Indeed, because rotation is essentially a careful combination of the two. |
| [angle]{@link Container#angle} | Rotation. This is an alias for [rotation]{@link Container#rotation}, but in degrees. |
| [x]{@link Container#x} | Translation. This is an alias for position.x! |
| [y]{@link Container#y} | Translation. This is an alias for position.y! |
| [width]{@link Container#width} | Implemented in [Container]{@link Container}. Scaling. The width property calculates scale.x by dividing the "requested" width by the local bounding box width. It is indirectly an abstraction over scale.x, and there is no concept of user-defined width. |
| [height]{@link Container#height} | Implemented in [Container]{@link Container}. Scaling. The height property calculates scale.y by dividing the "requested" height by the local bounding box height. It is indirectly an abstraction over scale.y, and there is no concept of user-defined height. |
Alpha
This alpha sets a display object's relative opacity w.r.t its parent. For example, if the alpha of a display object is 0.5 and its parent's alpha is 0.5, then it will be rendered with 25% opacity (assuming alpha is not applied on any ancestor further up the chain).
Renderable vs Visible
The renderable and visible properties can be used to prevent a display object from being rendered to the
screen. However, there is a subtle difference between the two. When using renderable, the transforms of the display
object (and its children subtree) will continue to be calculated. When using visible, the transforms will not
be calculated.
import { BlurFilter, Container, Graphics, Sprite } from 'pixi.js';
const container = new Container();
const 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();
RenderGroup
In PixiJS v8, containers can be set to operate in 'render group mode', transforming them into entities akin to a stage in traditional rendering paradigms. A render group is a root renderable entity, similar to a container, but it's rendered in a separate pass with its own unique set of rendering instructions. This approach enhances rendering efficiency and organization, particularly in complex scenes.
You can enable render group mode on any container using container.enableRenderGroup() or by initializing a new container with the render group property set to true (new Container({isRenderGroup: true})). The method you choose depends on your specific use case and setup requirements.
An important aspect of PixiJS’s rendering process is the automatic treatment of rendered scenes as render groups. This conversion streamlines the rendering process, but understanding when and how this happens is crucial to fully leverage its benefits.
One of the key advantages of using render groups is the performance efficiency in moving them. Since transformations are applied at the GPU level, moving a render group, even one with complex and numerous children, doesn't require recalculating the rendering instructions or performing transformations on each child. This makes operations like panning a large game world incredibly efficient.
However, it's crucial to note that render groups do not batch together. This means that turning every container into a render group could actually slow things down, as each render group is processed separately. It's best to use render groups judiciously, at a broader level, rather than on a per-child basis. This approach ensures you get the performance benefits without overburdening the rendering process.
RenderGroups maintain their own set of rendering instructions, ensuring that changes or updates within a render group don't affect the rendering instructions of its parent or other render groups. This isolation ensures more stable and predictable rendering behavior.
Additionally, renderGroups can be nested, allowing for powerful options in organizing different aspects of your scene. This feature is particularly beneficial for separating complex game graphics from UI elements, enabling intricate and efficient scene management in complex applications.
This means that Containers have 3 levels of matrix to be mindful of:
- localTransform, this is the transform of the container based on its own properties
- groupTransform, this it the transform of the container relative to the renderGroup it belongs too
- worldTransform, this is the transform of the container relative to the Scene being rendered
Usage
<script> // ported from https://pixijs.com/8.x/examples/mesh-and-shaders/perspective-mesh import { PerspectiveMesh, Container, getApp } from 'svelte-pixi' import { onMount } from 'svelte' import * as PIXI from 'pixi.js'
const { app } = getApp() const texture = PIXI.Texture.from('/assets/eggHead.png')
let meshX = 380 let meshY = 220
const initialCorners = [ { x: 0, y: 0 }, { x: texture.width, y: 0 }, { x: texture.width, y: texture.height }, { x: 0, y: texture.height } ] let corners = $state(initialCorners.map((p) => ({ ...p })))
function handlePointerMove(e) { const mouseX = e.global.x const mouseY = e.global.y const angleY = -(mouseX - meshX) / 10; const angleX = -(mouseY - meshY) / 10; rotate3D(angleX, angleY, 300) }
function rotate3D(angleX, angleY, perspective) { const radX = (angleX * Math.PI) / 180; const radY = (angleY * Math.PI) / 180; const cosX = Math.cos(radX); const sinX = Math.sin(radX); const cosY = Math.cos(radY); const sinY = Math.sin(radY);
for (let i = 0; i < initialCorners.length; i++) { const src = initialCorners[i]; const out = corners[i]; const x = src.x - texture.width / 2; const y = src.y - texture.height / 2; let z = 0; // Assume initial z is 0 for this 2D plane
// Rotate around Y axis const xY = cosY * x - sinY * z;
z = sinY * x + cosY * z;
// Rotate around X axis const yX = cosX * y - sinX * z;
z = sinX * y + cosX * z;
// Apply perspective projection const scale = perspective / (perspective - z);
out.x = xY * scale + texture.width / 2; out.y = yX * scale + texture.height / 2; }
corners = corners }</script>
<PerspectiveMesh x={meshX} y={meshY} {texture} pivot={{ x: texture.width / 2, y: texture.height / 2}} x0={corners[0].x} y0={corners[0].y} x1={corners[1].x} y1={corners[1].y} x2={corners[2].x} y2={corners[2].y} x3={corners[3].x} y3={corners[3].y}/><Container hitArea={app.screen} eventMode="static" onpointermove={handlePointerMove}/><script> // ported from https://pixijs.com/8.x/examples/mesh-and-shaders/perspective-mesh import { PerspectiveMesh, Container, getApp } from 'svelte-pixi/svelte-4' import { onMount } from 'svelte' import * as PIXI from 'pixi.js'
const { app } = getApp() const texture = PIXI.Texture.from('/assets/eggHead.png')
let meshX = 380 let meshY = 220
const initialCorners = [ { x: 0, y: 0 }, { x: texture.width, y: 0 }, { x: texture.width, y: texture.height }, { x: 0, y: texture.height } ] let corners = initialCorners.map((p) => ({ ...p }))
function handlePointerMove(e) { const mouseX = e.detail.global.x const mouseY = e.detail.global.y const angleY = -(mouseX - meshX) / 10; const angleX = -(mouseY - meshY) / 10; rotate3D(angleX, angleY, 300) }
function rotate3D(angleX, angleY, perspective) { const radX = (angleX * Math.PI) / 180; const radY = (angleY * Math.PI) / 180; const cosX = Math.cos(radX); const sinX = Math.sin(radX); const cosY = Math.cos(radY); const sinY = Math.sin(radY);
for (let i = 0; i < initialCorners.length; i++) { const src = initialCorners[i]; const out = corners[i]; const x = src.x - texture.width / 2; const y = src.y - texture.height / 2; let z = 0; // Assume initial z is 0 for this 2D plane
// Rotate around Y axis const xY = cosY * x - sinY * z;
z = sinY * x + cosY * z;
// Rotate around X axis const yX = cosX * y - sinX * z;
z = sinX * y + cosX * z;
// Apply perspective projection const scale = perspective / (perspective - z);
out.x = xY * scale + texture.width / 2; out.y = yX * scale + texture.height / 2; }
corners = corners }</script>
<PerspectiveMesh x={meshX} y={meshY} {texture} pivot={{ x: texture.width / 2, y: texture.height / 2}} x0={corners[0].x} y0={corners[0].y} x1={corners[1].x} y1={corners[1].y} x2={corners[2].x} y2={corners[2].y} x3={corners[3].x} y3={corners[3].y}/><Container hitArea={app.screen} eventMode="static" on:pointermove={handlePointerMove}/>API
Props
* denotes required
| Name | Description |
|---|---|
texture* | PIXI.Texture<PIXI.TextureSource<any>> |
accessible | booleanFlag for if the object is accessible. If true AccessibilityManager will overlay a shadow div with attributes set |
accessibleChildren | booleanSetting to false will prevent any children inside this container to be accessible. Defaults to true. |
accessibleHint | nullstringSets the aria-label attribute of the shadow div |
accessiblePointerEvents | "visible""inherit""none""auto""visiblePainted""visibleFill""visibleStroke""painted""fill""stroke""all"Specify the pointer-events the accessible div will use Defaults to auto. |
accessibleTitle | nullstringSets the title attribute of the shadow div If accessibleTitle AND accessibleHint has not been this will default to 'container [tabIndex]' |
accessibleType | "object""label""a""abbr""address""area""article""aside""audio""b""base""bdi""bdo""blockquote""body""br""button""canvas""caption""cite""code""col""colgroup""data""datalist""dd""del""details""dfn""dialog""div""dl""dt""em""embed""fieldset""figcaption""figure""footer""form""h1""h2""h3""h4""h5""h6""head""header""hgroup""hr""html""i""iframe""img""input""ins""kbd""legend""li""link""main""map""mark""menu""meta""meter""nav""noscript""ol""optgroup""option""output""p""picture""pre""progress""q""rp""rt""ruby""s""samp""script""search""section""select""slot""small""source""span""strong""style""sub""summary""sup""table""tbody""td""template""textarea""tfoot""th""thead""time""title""tr""track""u""ul""var""video""wbr"Specify the type of div the accessible layer is. Screen readers treat the element differently depending on this type. Defaults to button. |
alpha | number |
angle | numberThe angle of the object in degrees.
|
boundsArea | PIXI.RectangleAn optional bounds area for this container. Setting this rectangle will stop the renderer from recursively measuring the bounds of each children and instead use this single boundArea.
|
cacheAsBitmap | booleanLegacy property for backwards compatibility with PixiJS v7 and below.
Use |
cacheAsTexture | PIXI.CacheAsTextureOptionsboolean |
cullable | booleanControls whether this object should be culled when out of view. When true, the object will not be rendered if its bounds are outside the visible area. |
cullableChildren | booleanControls whether children of this container can be culled. When false, skips recursive culling checks for better performance. |
cullArea | PIXI.RectangleCustom shape used for culling calculations instead of object bounds. Defined in local space coordinates relative to the object.
|
cursor | "none""progress""auto""default""context-menu""help""pointer""wait""cell""crosshair""text""vertical-text""alias""copy""move""no-drop""not-allowed""e-resize""n-resize""ne-resize""nw-resize""s-resize""se-resize""sw-resize""w-resize""ns-resize""ew-resize""nesw-resize""col-resize""nwse-resize""row-resize""all-scroll""zoom-in""zoom-out""grab""grabbing"string & {}The cursor style to display when the mouse pointer is hovering over the object. Accepts any valid CSS cursor value or custom cursor URL. |
effects | PIXI.Effect[]todo Needs docs |
eventMode | "none""auto""passive""static""dynamic"Enable interaction events for the Container. Touch, pointer and mouse events are supported. |
filterArea | PIXI.RectangleThe area the filter is applied to. This is used as an optimization to define a specific region for filter effects instead of calculating the display object bounds each frame.
|
filters | readonly PIXI.Filter[]Sets the filters for the displayObject. Filters are visual effects that can be applied to any display object and its children.
|
height | numberThe height of the Container,
|
hitArea | nullPIXI.IHitAreaDefines a custom hit area for pointer interaction testing. When set, this shape will be used for hit testing instead of the container's standard bounds. |
instance | T |
interactive | booleanWhether this object should fire UI events. This is an alias for |
interactiveChildren | booleanControls whether children of this container can receive pointer events. Setting this to false allows PixiJS to skip hit testing on all children, improving performance for containers with many non-interactive children. |
isRenderGroup | boolean |
label | stringThe instance label of the object. |
mask | numberPIXI.Container<PIXI.ContainerChild>Partial<PIXI.MaskOptionsAndMask> |
name | stringThe instance name of the object. |
onadded | () => voidCalled when the instance is added to its parent or stage |
onclick | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
oncreate | (instance: T) => voidCalled on creation of the component. You can use this to do any setup on the instance directly |
onglobalmousemove | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the Fired when the mouse moves anywhere, regardless of whether the pointer is over this object.
The object must have |
onglobalpointermove | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the Fired when the pointer moves anywhere, regardless of whether the pointer is over this object.
The object must have |
onglobaltouchmove | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the Fired when a touch interaction moves anywhere, regardless of whether the pointer is over this object.
The object must have |
onmousedown | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
onmouseenter | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
onmouseleave | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
onmousemove | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
onmouseout | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
onmouseover | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
onmouseup | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
onmouseupoutside | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
onpointercancel | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
onpointerdown | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
onpointerenter | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
onpointerleave | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
onpointermove | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
onpointerout | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
onpointerover | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
onpointertap | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
onpointerup | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
onpointerupoutside | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
onremoved | () => voidCalled when the instance removed from its parent or stage |
onrightclick | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
onrightdown | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
onrightup | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
onrightupoutside | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
ontap | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
ontouchcancel | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
ontouchend | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
ontouchendoutside | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
ontouchmove | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
ontouchstart | nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>Property-based event handler for the |
pivot | number[number, number]{ x: number; y: number }PIXI.PointThe center of rotation, scaling, and skewing for this display object in its local space.
The By default, the pivot is the origin (0, 0). |
position | number[number, number]{ x: number; y: number }PIXI.PointThe coordinate of the object relative to the local coordinates of the parent. |
renderable | booleanControls whether this object can be rendered. If false the object will not be drawn, but the transform will still be updated. This is different from visible, which skips transform updates. |
rotation | numberThe rotation of the object in radians.
|
scale | number[number, number]{ x: number; y: number }PIXI.PointThe scale factors of this object along the local coordinate axes. The default scale is (1, 1). |
shader | nullSHADERRepresents the vertex and fragment shaders that processes the geometry and runs on the GPU. Can be shared between multiple Mesh objects. |
skew | number[number, number]{ x: number; y: number }PIXI.PointThe skew factor for the object in radians. Skewing is a transformation that distorts the object by rotating it differently at each point, creating a non-uniform shape. |
sortableChildren | booleanIf set to true, the container will sort its children by This actually changes the order of elements in the array of children, so it will affect the rendering order.
|
state | PIXI.State |
tabIndex | numberSets the tabIndex of the shadow div. You can use this to set the order of the elements when using the tab key to navigate. |
verticesX | numberNumber of vertices along the X axis. More vertices allow for more detailed deformations. |
verticesY | numberNumber of vertices along the Y axis. More vertices allow for more detailed deformations. |
visible | booleanThe visibility of the object. If false the object will not be drawn, and the transform will not be updated. |
width | numberThe width of the Container, setting this will actually modify the scale to achieve the value set.
|
x | numberThe position of the container on the x axis relative to the local coordinates of the parent. An alias to position.x |
x0 | numberThe x-coordinate of the top-left corner |
x1 | numberThe x-coordinate of the top-right corner |
x2 | numberThe x-coordinate of the bottom-right corner |
x3 | numberThe x-coordinate of the bottom-left corner |
y | numberThe position of the container on the y axis relative to the local coordinates of the parent. An alias to position.y |
y0 | numberThe y-coordinate of the top-left corner |
y1 | numberThe y-coordinate of the top-right corner |
y2 | numberThe y-coordinate of the bottom-right corner |
y3 | numberThe y-coordinate of the bottom-left corner |
zIndex | numberThe zIndex of the container. Controls the rendering order of children within their parent container. A higher value will mean it will be moved towards the front of the rendering order. |
Snippets
| Name | Type |
|---|---|
| children | Snippet<[instance: T]> |
Props
| Name | Description |
|---|---|
instance | PIXI.PerspectiveMeshThe PIXI.PerspectiveMesh instance. Can be set or bound to. |
shader | PIXI.ShaderRepresents the vertex and fragment shaders that processes the geometry and runs on the GPU. Can be shared between multiple Mesh objects. |
state | PIXI.StateRepresents the WebGL state the Mesh required to render, excludes shader and geometry. E.g., blend mode, culling, depth testing, direction of rendering triangles, backface, etc. |
texture | PIXI.Texture |
verticesX 10 | number |
verticesY 10 | number |
x0 | number |
x1 | number |
x2 | number |
x3 | number |
y0 | number |
y1 | number |
y2 | number |
y3 | number |
Additional props are passed on to Container
Slots
| Name | Props | Fallback |
|---|---|---|
| default | {} |
Events
| Name | Type | Detail |
|---|---|---|
| added | forwarded | |
| click | forwarded | |
| create | forwarded | |
| globalmousemove | forwarded | |
| globalpointermove | forwarded | |
| globaltouchmove | forwarded | |
| mousedown | forwarded | |
| mousemove | forwarded | |
| mouseout | forwarded | |
| mouseover | forwarded | |
| mouseup | forwarded | |
| mouseupoutside | forwarded | |
| pointercancel | forwarded | |
| pointerdown | forwarded | |
| pointermove | forwarded | |
| pointerout | forwarded | |
| pointerover | forwarded | |
| pointertap | forwarded | |
| pointerup | forwarded | |
| pointerupoutside | forwarded | |
| removed | forwarded | |
| removedFrom | forwarded | |
| rightclick | forwarded | |
| rightdown | forwarded | |
| rightup | forwarded | |
| rightupoutside | forwarded | |
| tap | forwarded | |
| touchcancel | forwarded | |
| touchend | forwarded | |
| touchendoutside | forwarded | |
| touchmove | forwarded | |
| touchstart | forwarded |