Develop
Develop
Select your platform

Layer blending modes

Updated: Oct 3, 2025

What is a blending mode?

Blending modes determine how layers are rendered when they overlap with other objects or the background in your scene. Spatial SDK supports multiple blending modes specifically for layers to achieve different visual effects and optimize performance.
Technical terms:
  • Alpha channel: The component of an image that controls transparency or opacity.
  • Depth buffer: Memory that stores depth information for each pixel, determining which objects appear in front of others.
  • Alpha test: A binary decision process that determines whether a pixel is rendered based on its alpha value.

How do blending modes work?

Blending modes in Spatial SDK control how the rendering pipeline handles transparency, depth writing, and color blending. They solve common rendering challenges such as:
  • Ensuring proper visual layering of objects in 3D space
  • Controlling how transparent objects interact with other scene elements
  • Optimizing performance by using appropriate rendering techniques
Each blending mode represents a different approach to these challenges, offering tradeoffs between visual quality and performance. The right blending mode depends on your specific use case and the visual effects you want to achieve.

Using blending modes

Spatial SDK offers three primary blending modes to handle different transparency and rendering requirements in your applications.

Configure opaque mode

Opaque mode treats every pixel as fully solid with no transparency. It’s ideal for solid objects with no transparency needs.
Key characteristics:
  • Writes color for every pixel of the object
  • Ignores any alpha channel in the texture
  • Writes depth information for every pixel, ensuring proper occlusion
  • Displays crisp edges with aliasing at boundaries
Set the renderMode in UIPanelRenderOptions to PanelRenderMode.Layer. Set layerBlendType to PanelShapeLayerBlendType.OPAQUE:
Known issue:ReadableMediaPanelRenderOptions with PanelRenderMode.Mesh() incorrectly creates a compositor layer. See Known issues for details and workarounds.
UIPanelSettings(
  rendering =
    UIPanelRenderOptions(
      renderMode =
          PanelRenderMode.Layer(
            layerBlendType = PanelShapeLayerBlendType.OPAQUE,
          )
    ),
)

Using PanelConfigOptions (advanced API)

options.layerBlendType = PanelShapeLayerBlendType.OPAQUE
Example of Opaque blending mode

Enable mask mode

The Mask blending mode is the default for new panel settings APIs. It uses the alpha channel as a binary decision maker for pixel rendering. It’s suitable for objects with hard-edged transparency like foliage, chain-link fences, or text.
Key characteristics:
  • Uses the alpha channel to determine if a pixel is rendered
  • Writes color only for pixels that pass the alpha test
  • Writes depth only for pixels that pass the alpha test
  • No color blending occurs - pixels are either fully rendered or not rendered at all
  • Creates aliased (non-smooth) edges
Set layerBlendType to PanelShapeLayerBlendType.MASKED:
UIPanelSettings(
  rendering =
    UIPanelRenderOptions(
      renderMode =
          PanelRenderMode.Layer(
            layerBlendType = PanelShapeLayerBlendType.MASKED,
          )
    ),
)

Using PanelConfigOptions (advanced API)

options.layerBlendType = PanelShapeLayerBlendType.MASKED
Example of Mask blending mode

Work with alpha blended mode

Alpha Blended mode provides smooth transparency effects by blending colors based on alpha values. It’s ideal for translucent objects like glass, water, or semi-transparent UI elements. This mode provides a smooth transition for opaque to transparent pixels, reducing aliasing inside the panel and provides increased quality for alpha blend edges.
Key characteristics:
  • Writes all pixels using alpha values for blending
  • Does NOT write to the depth buffer
    • This is crucial because writing depth would prevent objects behind it from rendering
  • May have alpha ordering issues when multiple transparent layers overlap
Alpha Blended mode creates the most realistic transparency effects but requires careful ordering of transparent objects in your scene to avoid visual artifacts.
Set layerBlendType to PanelShapeLayerBlendType.ALPHA_BLEND:
UIPanelSettings(
  rendering =
    UIPanelRenderOptions(
      renderMode =
          PanelRenderMode.Layer(
            layerBlendType = PanelShapeLayerBlendType.ALPHA_BLEND,
          )
    ),
)

Using PanelConfigOptions (advanced API)

options.layerBlendType = PanelShapeLayerBlendType.ALPHA_BLEND
Example of Alpha Blended mode

Best practices

  • Use mask mode for most use cases (this is the default for new panel settings APIs)
  • Use opaque mode when you need maximum performance and no transparency
  • Use alpha blended mode for smooth transparency effects (for example, glass, water, semi-transparent UI elements)
  • Be mindful of draw order when using transparent objects to avoid visual artifacts
Performance considerations:
  • Opaque objects render faster than transparent ones
  • Mask mode is more efficient than full Alpha Blending
  • Limit the number of transparent objects in your scene for better performance

Troubleshooting

  • Z-fighting with transparent objects: ensure proper sorting order; consider adjusting the z-position slightly
  • Artifacts at transparent edges: try using Mask mode instead of Alpha Blended mode, or ensure proper feathering is enabled
  • Transparent objects not visible: verify that your alpha values are set correctly and you’re using the appropriate blend mode
  • Performance issues with transparency: reduce the number of transparent objects or switch to a more performant blending mode
Did you find this page helpful?
Thumbs up icon
Thumbs down icon
Nav Logo
Virtual reality / Meta Horizon
Virtual reality / Meta Horizon
Virtual reality / Meta Horizon
English (US)
© 2025 Meta