@MainActor @preconcurrency class EnvironmentResource
An environmental resource that contains background and lighting information for a scene.
RealityKit supports image-based lighting that enables realistic reflections on your scene's 3D
content. You can define the look of your scene's background by supplying an environment resource
image that determines the general color of the room, and the location of any spotlights or shadowed areas
within the reflection. RealityKit applies the image's characteristics to your scene's reflective content.
RealityKit checks a bundle for an environment resource by the filename you supply to one of the load functions.
### Create a skybox folder
To add an environment resource to your Xcode project, make a folder with a name that ends in `.skybox` and
place a single image inside.
Ensure that the image is an environment map of equirectangular projection, also
known as a *latitude-longitude projection*.
Drag the folder into the Project navigator.
In the options pane, choose to create a folder reference (not a group), and add the folder to your app's targets.
At build time, Xcode compiles the image for use as an environment resource and inserts the result into the app bundle.
RealityKit supports the same input formats as Image I/O, such as `.png` and `.jpg`
However, to achieve rich, vibrant lighting, use a `.exr` or `.hdr` format, which support a wide dynamic range.
Synchronously creates an environment resource from an equirectangular image.
Loading an ``EnvironmentResource`` with this method blocks the main actor because it’s synchronous, so only call it from a command-line application.
The method can stall a regular app, which makes it visibly hitch, and the system terminates an app if its UI becomes unresponsive.
- Parameters:
- cgImage: The source equirectangular (latitude, longitude) image. To preserve all details use an image where the width is half the height.
- parameter options: A configuration for generating the environment resource.
Asynchronously generates an environment resource from an equirectangular image.
- Parameters:
- cgImage: The source equirectangular (latitude, longitude) image. To preserve all details use an image where the width is half the height.
- parameter options: A configuration for generating the environment resource.
Synchronously creates an environment resource from an equirectangular image.
Loading an ``EnvironmentResource`` with this method blocks the main actor because it’s synchronous, so only call it from a command-line application.
The method can stall a regular app, which makes it visibly hitch, and the system terminates an app if its UI becomes unresponsive.
- Parameters:
- cgImage: The source equirectangular (latitude, longitude) image. To preserve all details use an image where the width is half the height.
- resourceName: A unique name the method assigns to the resource it loads,
for use in network synchronization.
Asynchronously generates an environment resource from an equirectangular image.
- Parameters:
- cgImage: The source equirectangular (latitude, longitude) image. To preserve all details use an image where the width is half the height.
- resourceName: A unique name the method assigns to the resource it loads,
for use in network synchronization.
Synchronously generates an environment resource from a cube texture resource.
Loading an ``EnvironmentResource`` with this method blocks the main actor because it’s synchronous, so only call it from a command-line application.
The method can stall a regular app, which makes it visibly hitch, and the system terminates an app if its UI becomes unresponsive.
RealityKit generates an environment resource from a skybox cube texture of the environment.
The created environment shares the input skybox.
See ``init(cube:options:)-4xqiz`` for more details.
```swift
// Use compression and high quality options to export optimized resources.
let cube = try await TextureResource(
cubeFromEquirectangular: image,
quality: .high,
options: TextureResource.CreateOptions(semantic: .hdrColor)
)
let options = EnvironmentResource.CreateOptions(
samplingQuality: .high,
specularCubeDimension: cube.width/2,
compression: .astc(blockSize: .block4x4, quality: .high)
)
// Create an environment resource from the cube texture.
let environment = try await EnvironmentResource(
cube: cube, options: EnvironmentResource.CreateOptions(
samplingQuality: .high,
specularCubeDimension: cube.width/2,
compression: .astc(blockSize: .block4x4, quality: .high)
)
)
await MainActor.run {
// Assign the environment to an image-based light component.
let lightEntity = Entity()
lightEntity.components.set(ImageBasedLightComponent(
source: .single(environment)
))
...
}
```
- parameter cubeTexture: A skybox cube texture of type `.cubeType` and `.color` or `.hdrColor` semantics.
- parameter options: A configuration for generating the environment resource.
- Note: If you request `.astc` compression and `cubeTexture` isn't already
compressed, RealityKit compresses it.
Asynchronously creates an environment resource from a cube texture.
RealityKit generates an environment resource from a skybox cube texture of the environment.
The created environment shares the input skybox.
- Note: ``CreateOptions/SamplingQuality-swift.enum/high`` and ``CreateOptions/SamplingQuality-swift.enum/veryHigh``,
along with ``TextureResource/Compression/astc(blockSize:quality:)`` compression options, are only available in macOS.
Use these options to write optimized scenes for all target platforms when exporting from macOS with ``Entity/write(to:)``.
Compression options also significantly reduce an environmental resource's memory and disk usage.
```swift
// Use compression and high quality options to export optimized resources.
let cube = try TextureResource(
cubeFromEquirectangular: image,
quality: .high,
options: TextureResource.CreateOptions(semantic: .color)
)
let options = EnvironmentResource.CreateOptions(
samplingQuality: .high,
specularCubeDimension: cube.width/2,
compression: .astc(blockSize: .block4x4, quality: .high)
)
let environment = try EnvironmentResource(
cube: cube,
options: EnvironmentResource.CreateOptions(
samplingQuality: .high,
specularCubeDimension: cube.width/2,
compression: .astc(blockSize: .block4x4, quality: .high)
)
)
let lightEntity = Entity()
lightEntity.components.set(ImageBasedLightComponent(
source: .single(environment)
))
...
```
- parameter cubeTexture: A skybox cube texture of type `.cubeType` with `.color` or `.hdrColor` semantics.
- parameter options: A configuration for generating the environment resource.
- Note: If you request `.astc` compression and `cubeTexture` isn't already
compressed, RealityKit compresses it.
Synchronously loads an environment resource from a bundle.
Loading an ``EnvironmentResource`` with this method blocks the main actor because it’s synchronous, so only call it from a command-line application.
The method can stall a regular app, which makes it visibly hitch, and the system terminates an app if its UI becomes unresponsive.
If your image file is at the path `Foo.skybox/Bar.exr` in your Xcode project,
use `Bar` for the name parameter.
To add an environment resource to your Xcode project, see ``EnvironmentResource``.
- Important: This function blocks the calling thread while RealityKit loads the requested resource.
- Parameters:
- name: The image name without the file extension.
- bundle: The bundle to search for the resource. Use `nil` to indicate the app’s bundle.
- Returns: The environment resource that loads from the specified bundle.
Creates an EnvironmentResource a skybox, specular and diffuse texture resources.
- parameters:
- skyboxTexture: a skybox texture to preserve. If nil, derives a low-resolution proxy from
other inputs for lower memory usage.
- specularTexture: an image based light specular texture.
- diffuseTexture: an image based light diffuse texture.
- Note: `SkyboxGenerator` and `ImageBasedLightTextureGenerator` can generate
required textures into a `LowLevelTexture`, itself wrapped as a `TextureResource`.
- Note: The skybox is not needed for image based lighting with `VirtualEnvironmentProbeComponent`
and `ImageBasedLightComponent`.
get · iOS 18.0+
skybox
TypeScript
get skybox(): Promise<TextureResource>
Swift declaration
@MainActor @preconcurrency var skybox: TextureResource { get }
The cube color texture that contains environment surrounding details, or a low-resolution proxy
of the original skybox if the `EnvironmentResource` was created with `CreateOptions(skyboxMode: .discard)`.
The skybox contains the environment's detailed surroundings as a cube texture, which you can use to render the background
of a scene.
The skybox texture determines the environment's lighting.
You can assign the skybox texture to a ``ShaderGraphMaterial`` cube texture parameter.
```swift
// Load an environment resource.
let env = try await EnvironmentResource(
named: environmentResourceName, in: Bundle.main)
// Assign its skybox to a material's cube map texture parameter.
var skyboxCubeMaterial = try await ShaderGraphMaterial(named: materialUSDPath,
from: sceneResourceName,
in: contentBundle)
try await skyboxCubeMaterial.setParameter(name: cubeTextureParameterName,
value: .textureResource(env.skybox))
skyboxCubeMaterial.faceCulling = .front
// Apply to a background sky dome sphere.
let skyDome = await ModelEntity(mesh: .generateSphere(radius: 1E3),
materials: [skyboxCubeMaterial])
await MainActor.run {
sceneRootEntity.addChild(skyDome)
// Also use the environment resource for lighting.
let probe = VirtualEnvironmentProbeComponent.Probe(environment: env)
sceneRootEntity.components.set(VirtualEnvironmentProbeComponent(source: .single(probe)))
}
```
Asynchronously loads an environment resource from a bundle.
If your image file is at the path `Foo.skybox/Bar.exr` in your Xcode project, use
`Bar` for the name parameter.
You need to call this function with the `async` keyword from an asynchronous context,
such as from within a <doc://com.apple.documentation/documentation/swift/task> closure.
To add an environment resource to your Xcode project, see ``EnvironmentResource``.
- Parameters:
- name: The image name without the file extension.
- bundle: The bundle to search for the resource. Use `nil` to indicate the app’s bundle.
- Returns: The environment resource that loads from the specified bundle.
