Skip to main content

渲染图层

¥Render Layers

PixiJS 层 API 指南​

¥PixiJS Layer API Guide

PixiJS Layer API 提供了一种强大的方法来控制对象的渲染顺序，而不受场景图中逻辑父子关系的影响。使用 RenderLayers，你可以将对象的转换方式（通过其逻辑父级）与它们在屏幕上的可视化绘制方式分离开来。

¥The PixiJS Layer API provides a powerful way to control the rendering order of objects independently of their logical parent-child relationships in the scene graph. With RenderLayers, you can decouple how objects are transformed (via their logical parent) from how they are visually drawn on the screen.

使用 RenderLayers 可确保这些元素在视觉上具有优先级，同时保持逻辑上的父子关系。示例包括：

¥Using RenderLayers ensures these elements are visually prioritized while maintaining logical parent-child relationships. Examples include:

  • 带有健康条的角色：确保健康栏始终出现在世界顶部，即使角色移动到对象后面。

    ¥A character with a health bar: Ensure the health bar always appears on top of the world, even if the character moves behind an object.

  • UI 元素，如分数计数器或通知：无论游戏世界的复杂程度如何，都让它们保持可见。

    ¥UI elements like score counters or notifications: Keep them visible regardless of the game world’s complexity.

  • 教程中的高亮元素：想象一下，在一个教程中，你需要在高亮特定对象的同时推回大多数游戏元素。RenderLayers 可以直观地拆分这些。高亮的对象可以放置在前景图层中，以在推回图层上方进行渲染。

    ¥Highlighting Elements in Tutorials: Imagine a tutorial where you need to push back most game elements while highlighting a specific object. RenderLayers can split these visually. The highlighted object can be placed in a foreground layer to be rendered above a push back layer.

本指南解释了关键概念，提供了实际示例，并强调了常见的陷阱，以帮助你有效地使用 Layer API。

¥This guide explains the key concepts, provides practical examples, and highlights common gotchas to help you use the Layer API effectively.

关键概念​

¥Key Concepts

  1. 独立渲染顺序：

    ¥Independent Rendering Order:

    • RenderLayers 允许独立于逻辑层次结构控制绘制顺序，确保对象按所需顺序渲染。

      ¥RenderLayers allow control of the draw order independently of the logical hierarchy, ensuring objects are rendered in the desired order.

  2. 逻辑父级保持完整：

    ¥Logical Parenting Stays Intact:

    • 即使附加到 RenderLayers，对象也会从其逻辑父级保持变换（例如，位置、比例、旋转）。

      ¥Objects maintain transformations (e.g., position, scale, rotation) from their logical parent, even when attached to RenderLayers.

  3. 显式对象管理：

    ¥Explicit Object Management:

    • 对象从场景图或图层中移除后必须手动重新分配到图层，以确保对渲染进行精心控制。

      ¥Objects must be manually reassigned to a layer after being removed from the scene graph or layer, ensuring deliberate control over rendering.

  4. 动态排序：

    ¥Dynamic Sorting:

    • 在层内，可以使用 zIndex 和 sortChildren 动态重新排序对象，以细粒度控制渲染顺序。

      ¥Within layers, objects can be dynamically reordered using zIndex and sortChildren for fine-grained control of rendering order.

基本 API 使用​

¥Basic API Usage

首先让我们创建两个我们想要渲染的项目，红色人和蓝色人。

¥First lets create two items that we want to render, red guy and blue guy.

const redGuy = new PIXI.Sprite('red guy');
redGuy.tint = 0xff0000;

const blueGuy = new PIXI.Sprite('blue guy');
blueGuy.tint = 0x0000ff;

stage.addChild(redGuy, blueGuy);

alt text

现在我们知道红色人将首先被渲染，然后是蓝色人。现在在这个简单的例子中，你只需对红色人和蓝色人的 zIndex 进行排序即可帮助重新排序。

¥Now we know that red guy will be rendered first, then blue guy. Now in this simple example you could get away with just sorting the zIndex of the red guy and blue guy to help reorder.

但这是一个关于渲染层的指南，所以让我们创建其中一个。

¥But this is a guide about render layers, so lets create one of those.

使用 renderLayer.attach 将对象分配给图层。这会覆盖由其逻辑父级定义的对象的默认渲染顺序。

¥Use renderLayer.attach to assign an object to a layer. This overrides the object’s default render order defined by its logical parent.

// a layer..
const layer = new RenderLayer();
stage.addChild(layer);
layer.attach(redGuy);

alt text

所以现在我们的场景图顺序是：

¥So now our scene graph order is:

|- stage
    |-- redGuy
    |-- blueGuy
    |-- layer

我们的渲染顺序是：

¥And our render order is:

|- stage
    |-- blueGuy
    |-- layer
        |-- redGuy

发生这种情况是因为该层现在是舞台中的最后一个子项。由于红色人影附加到图层，因此它将在场景图中的图层位置处进行渲染。但是，它在逻辑上仍然保持在场景层次结构中的同一位置。

¥This happens because the layer is now the last child in the stage. Since the red guy is attached to the layer, it will be rendered at the layer's position in the scene graph. However, it still logically remains in the same place in the scene hierarchy.

3.​

现在让我们从图层中删除红色人。要阻止对象在图层中渲染，请使用 removeFromLayer。从图层中移除后，对象仍将位于场景图中，并将按照其场景图顺序进行渲染。

¥Now let's remove the red guy from the layer. To stop an object from being rendered in a layer, use removeFromLayer. Once removed from the layer, its still going to be in the scene graph, and will be rendered in its scene graph order.


layer.detach(redGuy); //  Stop rendering the rect via the layer

alt text

从逻辑父级（removeChild）中移除对象会自动将其从图层中移除。

¥Removing an object from its logical parent (removeChild) automatically removes it from the layer.


stage.removeChild(redGuy); // if the red guy was removed from the stage, it will also be removed from the layer

alt text

但是，如果你从舞台上移除红色人，然后将其添加回舞台，它将不会再次添加到图层中。

¥However, if you remove the red guy from the stage and then add it back to the stage, it will not be added to the layer again.

// add red guy to his original position
stage.addChildAt(redGuy, 0);

alt text

你需要自己将其重新连接到层。

¥You will need to reattach it to the layer yourself.


layer.attach(redGuy); // re attach it to the layer again!

alt text

这看起来很麻烦，但实际上是一件好事。这意味着你可以完全控制对象的渲染顺序，并且可以随时更改它。这也意味着你不会意外将对象添加到容器中，并让它自动重新附加到可能仍然存在也可能不存在的层 - 这会相当混乱，并导致一些很难调试的错误！

¥This may seem like a pain, but it's actually a good thing. It means that you have full control over the render order of the object, and you can change it at any time. It also means you can't accidentally add an object to a container and have it automatically re-attach to a layer that may or may not still be around - it would be quite confusing and lead to some very hard to debug bugs!

5.​

图层在场景图中的位置决定了其相对于其他图层和对象的渲染优先级。

¥The layer’s position in the scene graph determines its render priority relative to other layers and objects.


// reparent the layer to render first in the stage
stage.addChildAt(layer, 0);

alt text

完整示例​

¥Complete Example

这是一个真实的例子，展示了如何使用 RenderLayers 将 ap 播放器 ui 设置在世界之巅。

¥Here’s a real-world example that shows how to use RenderLayers to set ap player ui on top of the world.


陷阱以及需要注意的事项​

¥Gotchas and Things to Watch Out For

  1. 手动重新分配：

    ¥Manual Reassignment:

    • 当对象重新添加到逻辑父级时，它不会自动与其上一个层重新关联。始终将对象明确地重新分配给层。

      ¥When an object is re-added to a logical parent, it does not automatically reassociate with its previous layer. Always reassign the object to the layer explicitly.

  2. 嵌套子级：

    ¥Nested Children:

    • 如果删除父容器，其所有子容器都会自动从图层中删除。谨慎处理复杂的层次结构。

      ¥If you remove a parent container, all its children are automatically removed from layers. Be cautious with complex hierarchies.

  3. 在层内排序：

    ¥Sorting Within Layers:

    • 可以使用图层中的对象的 zIndex 属性动态排序。这对于细粒度控制渲染顺序很有用。

      ¥Objects in a layer can be sorted dynamically using their zIndex property. This is useful for fine-grained control of render order.

    rect.zIndex = 10; // Higher values render later
    layer.sortableChildren = true; // Enable sorting
    layer.sortRenderLayerChildren(); // Apply the sorting

  4. 图层重叠：

    ¥Layer Overlap:

    • 如果多个图层重叠，它们在场景图中的顺序决定了渲染优先级。确保分层逻辑与你想要的视觉输出一致。

      ¥If multiple layers overlap, their order in the scene graph determines the render priority. Ensure the layering logic aligns with your desired visual output.

最佳实践​

¥Best Practices

  1. 战略分组：最小化图层数量以优化性能。

    ¥Group Strategically: Minimize the number of layers to optimize performance.

  2. 用于视觉清晰度：为需要明确控制渲染顺序的对象保留图层。

    ¥Use for Visual Clarity: Reserve layers for objects that need explicit control over render order.

  3. 测试动态变化：验证在特定场景设置中添加、删除或重新分配对象到图层的行为是否符合预期。

    ¥Test Dynamic Changes: Verify that adding, removing, or reassigning objects to layers behaves as expected in your specific scene setup.

通过理解和有效利用 RenderLayers，你可以精确控制场景的视觉渲染，同时保持干净、合乎逻辑的层次结构。

¥By understanding and leveraging RenderLayers effectively, you can achieve precise control over your scene's visual presentation while maintaining a clean and logical hierarchy.