A component that configures the rendering order for an entity's model.
## Overview
Tell the renderer to draw a model on top of another by adding
a `ModelSortGroupComponent` instance to both entities.
A model sort group component gives you control over the rendering
order for entities within the same ``ModelSortGroup``.
You can configure the group to render models in a specific order,
even if that order contradicts their relative positions to each other in the
scene.
The scenario below shows a living room scene that has two rectangular cuboids
which overlap and form the shape of a plus symbol.
The blue cuboid is opaque and taller than it is wide.
The red cuboid is transparent and wider than it is tall.
@Row {
@Column{}
@Column(size: 5) {
@Image(
source: modelsortgroupcomponent-not-set,
alt: "A screenshot of a living room scene with two rectangular cuboids that overlap. The vertical cuboid is an opaque blue, and the horizontal cuboid is a translucent red. The red cuboid appears in front of the blue one, which gives the area where they overlap a purple hue."
)
}
@Column{}
}
The sections below demonstrate how to change the default behavior by
configuring the properties of the model sort group component.
### Set the draw order
To tell the renderer to draw the red cuboid
before the blue one, add a `ModelSortGroupComponent` instance to both
cuboids.
Then set both component's ``order`` property so that the red cuboid's
component has a smaller value than the blue cuboid's component.
```swift
let redCuboid = Entity()
let blueCuboid = Entity()
// ...
// Create a group for both cuboids.
let group = ModelSortGroup(depthPass: nil)
let redSortComponent = ModelSortGroupComponent(
group: group,
order: 1
)
redCuboid.components.set(redSortComponent)
let blueSortComponent = ModelSortGroupComponent(
group: group,
order: 2
)
blueCuboid.components.set(blueSortComponent)
```
The renderer draws the red cuboid first and then doesn't draw the part of the
blue cuboid where the two cuboids overlap because the nearest face of the
red cuboid in the overlapping area is closer to the camera.
@Row {
@Column{}
@Column(size: 5) {
@Image(
source: modelsortgroupcomponent-none-redfirst,
alt: "A screenshot of a living room scene with two rectangular cuboids that overlap. The vertical cuboid is an opaque blue, and the horizontal cuboid is a translucent red. The red cuboid appears in front of the blue one, and in the area where they overlap, the blue cuboid isn't visible, which reveals the scene's background through the red one."
)
}
@Column{}
}
If the renderer instead draws the blue cuboid first,
and the translucent red cuboid second,
the blue cuboid is once again visible in the overlapping area.
@Row {
@Column{}
@Column(size: 5) {
@Image(
source: modelsortgroupcomponent-none-bluefirst,
alt: "A screenshot of a living room scene with two rectangular cuboids that overlap. The vertical cuboid is an opaque blue, and the horizontal cuboid is a translucent red. The red cuboid appears in front of the blue one, which gives the area where they overlap a purple hue."
)
}
@Column{}
}
Rendering the blue cuboid produces the same result as if the two cuboids
weren't in a sort group.
### Set the depth pass
In the examples in the previous section, the renderer draws each model's
depth and color together, at the same time.
To draw each entity's color and depth separately, set the ``ModelSortGroup/depthPass-swift.property`` property of a ``ModelSortGroup`` instance, which changes the rendering sequence
for each model in the group that either draws their colors first or their
depths first.
- Tip: You can also set the property with the ``ModelSortGroup/init(depthPass:)`` initializer.
To draw each model's color on the first pass and then the depth, set the
property to ``ModelSortGroup/DepthPass-swift.enum/postPass``.
```swift
// Draw the color first, depth second.
let group = ModelSortGroup(depthPass: .postPass)
```
| **Red First** | **Blue First** |
|:-:|:-:|
|  |  | |
The ``ModelSortGroup/DepthPass-swift.enum/postPass`` option tells the
renderer to draw entities in reverse order, which gives the effect that the
last model it draws appears in front.
The depth pass ``ModelSortGroup/DepthPass-swift.enum/prePass`` draws each
entity's depth on the first pass, then their color.
```swift
// Draw the depth first, color second.
let group = ModelSortGroup(depthPass: .prePass)
```
| **Red First** | **Blue First** |
|:-:|:-:|
|  |  |
The ``ModelSortGroup/DepthPass-swift.enum/prePass`` option tells the renderer
to write the depth buffer for the group's entities first.
The renderer doesn't draw the blue cuboid in the overlapping area, regardless
of order, because the red cuboid has a shallower depth in all parts of the
overlapping area.
- Tip: Check out <doc://com.apple.documentation/documentation/visionos/swift-splash>
which has an implementation that leverages `ModelSortGroupComponent`.
Creates a model sort group component.
- Parameters:
- group: A group the component's entity belongs to.
- order: An integer value in the range `(Int32.min, Int32.max)` that
represents when the renderer draws the model relative to other the
models in its group.
- Warning: Don't pass `Int32.max` or `Int32.min` to the `order` parameter
because the framework reserves these as sentinel values, and using them
may trigger erratic behavior.
get · iOS 18.0+
group
TypeScript
get group(): ModelSortGroup
Swift declaration
var group: ModelSortGroup { get set }
The group that the component's entity belongs to.
The renderer only draws entities with the same ``ModelSortGroup`` relative to each other.
- Note: Membership only applies to the entity that directly owns this component,
but not to its descendants.
set · iOS 18.0+
group
TypeScript
set group(value: ModelSortGroup)
Swift declaration
var group: ModelSortGroup { get set }
The group that the component's entity belongs to.
The renderer only draws entities with the same ``ModelSortGroup`` relative to each other.
- Note: Membership only applies to the entity that directly owns this component,
but not to its descendants.
get · iOS 18.0+
order
TypeScript
get order(): number
Swift declaration
var order: Int32 { get set }
An integer value that represents when the renderer draws the model
relative to other the models in its group.
The renderer draws models in ascending order, starting with the
components with the smallest value.
You can tell the renderer that it only needs to order entities by their
depths by setting the component's ``order`` property to the sam value
for those entities.
- Warning: Don't set `order` to `Int32.max` or `Int32.min` because the
framework reserves these as sentinel values, and assigning their values
may trigger erratic behavior.
set · iOS 18.0+
order
TypeScript
set order(value: number)
Swift declaration
var order: Int32 { get set }
An integer value that represents when the renderer draws the model
relative to other the models in its group.
The renderer draws models in ascending order, starting with the
components with the smallest value.
You can tell the renderer that it only needs to order entities by their
depths by setting the component's ``order`` property to the sam value
for those entities.
- Warning: Don't set `order` to `Int32.max` or `Int32.min` because the
framework reserves these as sentinel values, and assigning their values
may trigger erratic behavior.
