[ts][pixi-v8] Multiple containers added via addSlotObject() do not batch when sharing the same clipping mask

[PGawlas]

Hi,

We’ve encountered an issue with the addSlotObject() method in PIXI Spine. When we add multiple containers to a Spine instance using addSlotObject(), and all of the corresponding slots are masked using the same clipping attachment, each container still generates a separate draw calls (multiple draw calls per single attachment due to extra stencil bufor draw calls).

It seems that even though the same clipping mask is shared, the containers do not batch together as expected. This significantly increases the number of draw calls and impacts performance.

Is there any possibility to optimize this behavior?

In our projects, we often attach many containers to a Spine instance, and sometimes these containers are also masked in Spine by clipping attachments. This significantly increases the number of draw calls and likely affects overall performance.

[PGawlas]

mask_empty.json

I'm attaching the example spine json file, if you add PIXI Sprites by addSlotObjects() on slots from empty1 to empty8, rendering produces a very high number of draw calls.

[davidetan]

Hello, as far as I remember, that does not depend on our implementation, but on how Pixi behaves with masks.

When you say:

It seems that even though the same clipping mask is shared, the containers do not batch together as expected.

Did you try reproducing the same thing without a Spine game object? I mean, adding a couple of sprites masked by the same shared mask.
If it behaves the same way, I'm sorry but there's nothing we can do on our side. Could you try reproducing it?

[PGawlas]

Hi,

In PIXI I would create parent container and apply mask to it, so all of them would be rendered at once.

I guess that in Spine when there are multiple slots with addSlotObject() attachments, you add mask to each of this attachment separately, right?

Maybe there would be room for optimization and under the hood create similar container with just a single mask, if all attachments use the same spine clipping attachment, and are next to each other in draw order list.

[PGawlas]

PIXI Playground Example

If link does not work, please past this code in the playground app: https://pixijs.com/8.x/playground

import { Application, Assets, Container, Sprite, Graphics } from 'pixi.js';

(async () => {
  // Create a new application
  const app = new Application();

  // Initialize the application
  await app.init({ background: '#1099bb', resizeTo: window });

  // Append the application canvas to the document body
  document.body.appendChild(app.canvas);

  // Create and add a container to the stage
  const container = new Container();

  app.stage.addChild(container);

  // Load the bunny texture
  const texture = await Assets.load('https://pixijs.com/assets/bunny.png');

  const bunny1 = container.addChild(new Sprite(texture));
  const bunny2 = container.addChild(new Sprite(texture));
  const bunny3 = container.addChild(new Sprite(texture));
  const bunny4 = container.addChild(new Sprite(texture));

  const mask = new Graphics().rect(50, 190, 200, 120).fill(0xffffff);
  container.addChild(mask);
  container.mask = mask;

  // Center the sprite's anchor point
  bunny1.anchor.set(0.5);
  bunny2.anchor.set(0.5);
  bunny3.anchor.set(0.5);
  bunny4.anchor.set(0.5);

  // Move the sprite to the center of the screen
  bunny1.position.set(100, 200);
  bunny2.position.set(100, 300);
  bunny3.position.set(200, 200);
  bunny4.position.set(200, 300);
})();

[davidetan]

The Pixi objects added with addSlotObject follow the slot (bone) transform.
If we grouped different objects like these under a single container, we wouldn’t be able to make each object follow its respective transform, since they would all follow the container’s transform instead.
Or, from another point of view, we wouldn’t know which bone transform to use among the slot transforms to control the container’s transform.

Right now, I can’t see a valid solution to this problem, since the objects added with addSlotObject must follow the bone’s transform — that’s the main purpose of addSlotObject — and grouping these objects under the same container would break this behavior.

Do you have any ideas on how to work around this?

[PGawlas]

Hmm I'm not 100% sure, but I guess objects can still have they own transforms, and Container transforms are applied on top of the object ones like:

realX = container.x + object.x;

So if container would not have any transforms like positions, scale. rotation etc, and would be used only for masking, that should not affect object transforms, and maybe could work.

[PGawlas]

I wonder if updateAndSetPixiMask would be good place to add this logic, maybe when mask is computed we could create PIXI.Container as well, and instead of attaching mask to object ( which are named container in code :D ) attach it to the created container, and then put object in this created Container.

And if this method is called another time for next object, if it used the same mask, we would just add it to container as it already exist.

[davidetan]

updateAndSetPixiMask is where the mask is managed, so it’s exactly the place where any modification related to masks must be made.

[PGawlas]

BTW, we noticed this issue during the migration from PIXI 6 to PIXI 8. In the previous implementation for PIXI 6, everything worked fine and there was only one mask, but I realize that the current implementation is a complete overhaul and things work differently now.

[davidetan]

I'll give it a try. It shouldn't be hard since there's already a grouping by mask.

[PGawlas]

Thanks! I'm happy to test it once you have something ready.

I also found a similar implementation in the old Spine Runtime, maybe it’ll help a bit.

https://github.com/pixijs-userland/spine/blob/master/packages/base/src/SpineBase.ts [from line 434]

[davidetan]

@PGawlas Unfortunately, I found an issue with this approach.
If we render all Pixi objects added with addSlotObject in a single pass (grouped by the same clipping attachment/Pixi mask), we lose the "z-order" of the Spine slots.

For example, the order from bottom to top is:

• Spine region (A)
• Clipping attachment (start)
• Spine region (B)
• Pixi object (C)
• Spine region (D)
• Pixi object (E) <--- clipping attachment ends here

So the expected order is A -> B -> C -> D -> E.

If we want to optimize it, we’d need to group C and E under container F.
But when should we render F? Possible orders are:

• A -> B -> F(C,E) -> D | Wrong, E is before D now
• A -> B -> D -> F(C,E) | Wrong, C is after D now

I think the only actual solution is not to use Spine’s internal clipping logic, but to use Pixi masks to clip Spine attachments as well. In that case, we would group B, C, D, and E together under F and assign them the mask corresponding to the clipping attachment.
The order is now consistent: A -> F(B,C,D,E)

However, this would break batching in normal situations. If there are no slot objects with clipping masks, we would break batching due to the clipping performed on the WebGL side. This means it needs to be an opt-in behavior, and I don’t like that idea at all.

[PGawlas]

Yes, I'm aware of it. I was thinking of grouping only Pixi Objects if there are next to each other in draw order as described in comment above.

Maybe there would be room for optimization and under the hood create similar container with just a single mask, if all attachments use the same spine clipping attachment, and are next to each other in draw order list.

So in your example, there wouldn't be any improvement, but if there would be more of them next to each other then group them in containers.

So in your example left it as it is:
A -> B -> C -> D -> E
(or add container with only one child, if that's better from code perspective):
A -> B -> F(C) -> D -> G(E)
but if there are more of them, add grouping by container:

Spine region (A)
Clipping attachment (start)
Spine region (B)
Pixi object (C)
Pixi object (D)
Pixi object (E)
Spine region (F)
Pixi object (G) <--- clipping attachment ends here

render:
A -> B -> H(C, D, E) -> F -> G

that would be completly fine and probably optimize a lot of use cases anyway.