A representation of a texture.
A texture resource holds pixel data accessible by the GPU,
organized as an image, a cube of images, an array of images, or a 3D image
(volume texture).
Assign texture resources to material parameters to provide color and fine
surface-rendering details.
Asynchronously creates a texture resource from a file URL with creation options.
- Parameters:
- url: The path or address of the file to load into the texture resource.
- resourceName: A unique name the method assigns to the resource it loads,
for use in network synchronization.
- options: The options to use when loading the resource.
Asynchronously creates a texture resource from a file URL.
- Parameters:
- url: The path or address of the file to load into the texture resource.
- resourceName: A unique name the method assigns to the resource it loads,
for use in network synchronization.
Synchronously creates a 2D texture resource from a pixel Metal buffer, or data.
Loading a ``TextureResource`` 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.
See ``init(named:in:)`` for an example that demonstrates how to safely load content.
RealityKit efficiently creates a 2D texture from raw pixel bytes, with full control over the values and pixel format.
See ``init(dimensions:format:contents:)-5wn8m`` for more details.
- Parameters:
- dimensions: The width and height of the texture to create.
- format: The semantic interpretation of the pixel data.
- contents: Pixel data the system copies into the created texture.
Asynchronously creates a 2D texture resource from a pixel Metal buffer, or data.
RealityKit efficiently creates a 2D texture from raw pixel bytes, with full control over the values and pixel format.
```swift
var mips: [TextureResource.Contents.MipmapLevel] = []
// Create the various mipmap levels.
// A `bufferMipsInfo` structure describes the mipmap packing in the source `MTLBuffer`.
for mipInfo in bufferMipsInfo {
mips.append(.mip(
unsafeBuffer: buffer,
offset: mipInfo.offset,
size: mipInfo.size,
bytesPerRow: mipInfo.width * bytesPerPixel
))
}
let texture = try await TextureResource(
dimensions: .dimensions(width: width, height: height),
format: .color(.displayP3, pixelFormat: .rgba8Unorm),
contents: TextureResource.Contents(mipmapLevels: mips)
)
```
See ``init(named:in:)`` for an example of optimally loading textures with
other content.
- Parameters:
- dimensions: The width and height of the texture to create.
- format: The semantic interpretation of the pixel data.
- contents: Pixel data the system copies into the created texture.
Synchronously creates a 3D texture resource from a pixel Metal buffer, or data.
RealityKit efficiently creates a 3D texture from raw pixel bytes, with full control over the values and pixel format.
See ``init(dimensions:format:contents:)-64sua`` for more details.
Loading a ``TextureResource`` 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.
See ``init(named:in:)`` for an example that demonstrates how to safely load content.
- Parameters:
- dimensions: The dimensions of the 3D texture to create.
- format: The semantic interpretation of the pixel data.
- contents: Pixel data the system copies into the created texture.
Asynchronously creates a 3D texture resource from a pixel Metal buffer, or data.
RealityKit efficiently creates a 3D texture from raw pixel bytes, with full control over the values and pixel format.
You can assign the resulting texture to a material you create in Reality Composer Pro that requires a 3D texture.
```swift
var mips: [TextureResource.Contents.MipmapLevel] = []
// Create the various mipmap levels.
// A `bufferMipsInfo` structure describes the mipmap packing in the source `MTLBuffer`.
for mipInfo in bufferMipsInfo {
// A mipmap contains all of the depth slices,
// each with a stride that `bytesPerImage` specifies.
mips.append(.mip(
unsafeBuffer: buffer,
offset: mipInfo.offset,
size: mipInfo.size,
bytesPerRow: mipInfo.width * bytesPerPixel,
bytesPerImage: mipInfo.width * mipInfo.height * bytesPerPixel
))
}
let texture = try TextureResource(
dimensions: .dimensions(width: width, height: height, depth: depth),
format: .color(.displayP3, pixelFormat: .rgba8Unorm),
contents: TextureResource.Contents(mipmapLevels: mips)
)
```
See ``init(named:in:)`` for an example of optimally loading textures with
other content.
- Parameters:
- dimensions: The dimensions of the 3D texture to create.
- format: The semantic interpretation of the pixel data.
- contents: Pixel data the system copies into the created texture.
Synchronously creates a cube texture resource from a pixel Metal buffer, or data.
Loading a ``TextureResource`` 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.
See ``init(named:in:)`` for an example that demonstrates how to safely load content.
RealityKit efficiently creates a cube texture from raw pixel bytes, with full control over the values and pixel format.
See ``init(dimensions:format:contents:)-75en1`` for more details.
- Parameters:
- dimensions: The dimensions of the cube texture to create.
- format: The semantic interpretation of the pixel data.
- contents: Pixel data the system copies into the created texture.
Asynchronously creates a cube texture resource from a pixel Metal buffer, or data.
RealityKit efficiently creates a cube texture from raw pixel bytes, with full control over the values and pixel format.
Use the resulting texture to create an ``EnvironmentResource``,
or assign it to a material in Reality Composer Pro that requires
a cube texture type.
```swift
var mips: [TextureResource.Contents.MipmapLevel] = []
// Create the various mipmap levels.
// A `bufferMipsInfo` structure describes the mipmap packing in the source `MTLBuffer`.
for mipInfo in bufferMipsInfo {
var faceSlices = [TextureResource.Contents.Slice]()
for faceInfo in mipInfo {
faceSlices.append(.slice(
unsafeBuffer: buffer,
offset: faceInfo.offset,
size: faceInfo.size,
bytesPerRow: faceInfo.width * bytesPerPixel
))
}
mips.append(.mip(slices: faceSlices))
}
let texture = try TextureResource(
dimensions: .dimensions(faceSize: faceSize),
format: .color(.displayP3, pixelFormat: .rgba8Unorm),
contents: TextureResource.Contents(mipmapLevels: mips)
)
```
See ``init(named:in:)`` for an example of optimally loading textures with
other content.
- Parameters:
- dimensions: The dimensions of the cube texture to create.
- format: The semantic interpretation of the pixel data.
- contents: Pixel data the system copies into the created texture.
Synchronously creates a 2D array texture resource from a pixel Metal buffer, or data.
Loading a ``TextureResource`` 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.
See ``init(named:in:)`` for an example that demonstrates how to safely load content.
RealityKit efficiently creates a 2D array texture from raw pixel bytes, with full control over the values and pixel format.
See ``init(dimensions:format:contents:)-324ls`` for more details.
- Parameters:
- dimensions: The dimensions of the 2D array texture to create.
- format: The semantic interpretation of the pixel data.
- contents: Pixel data the system copies into the created texture.
Asynchronously creates a 2D array texture resource from a pixel Metal buffer, or data.
RealityKit efficiently creates a 2D array texture from raw pixel bytes, with full control over the values and pixel format.
You can assign the resulting texture to a material you create in Reality Composer Pro that requires a 2D texture array.
```swift
var mips: [TextureResource.Contents.MipmapLevel] = []
// Create the various mipmap levels.
// A `bufferMipsInfo` structure describes the mipmap packing in the source `MTLBuffer`.
for mipInfo in bufferMipsInfo {
var slices = [TextureResource.Contents.Slice]()
for sliceInfo in mipInfo {
slices.append(.slice(
unsafeBuffer: buffer,
offset: sliceInfo.offset,
size: sliceInfo.size,
bytesPerRow: sliceInfo.width * bytesPerPixel
))
}
mips.append(.mip(slices: slices))
}
let texture = try TextureResource(
dimensions: .dimensions(width: width, height: height, length: arrayLength),
format: .color(.displayP3, pixelFormat: .rgba8Unorm),
contents: TextureResource.Contents(mipmapLevels: mips)
)
```
See ``init(named:in:)`` for an example of optimally loading textures with
other content.
- Parameters:
- dimensions: The dimensions of the 2D array texture to create.
- format: The semantic interpretation of the pixel data.
- contents: Pixel data the system copies into the created texture.
get · iOS 18.0+
arrayLength
TypeScript
get arrayLength(): Promise<number>
Swift declaration
@MainActor @preconcurrency var arrayLength: Int { get }
The number of slices in the texture array.
The value is `0` if it isn't a texture array.
get · iOS 18.0+
pixelFormat
TypeScript
get pixelFormat(): Promise<_Metal_MTLPixelFormat>
Swift declaration
@MainActor @preconcurrency var pixelFormat: MTLPixelFormat { get }
The texture's pixel format.
get · iOS 18.0+
textureType
TypeScript
get textureType(): Promise<_Metal_MTLTextureType>
Swift declaration
@MainActor @preconcurrency var textureType: MTLTextureType { get }
The dimension and arrangement of the texture image data.
Asynchronously replaces the texture with a Core Graphics image.
Don't use this method for updates at frame-rate frequency.
For frequent texture changes, see ``replace(withDrawables:)``.
To ensure consistent usage of this texture resource, pass the same semantic
in `options` that you use to create the resource.
- Note: The contents of a modified texture resource don't sync between network clients.
- Parameters:
- cgImage: The source image.
- options: Options that specify the type of texture to create.
To preserve `TextureResource` usage, specify the same semantic.
Synchronously creates a cube texture resource from a 2D image of cube faces.
Loading a ``TextureResource`` 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.
See ``init(named:in:)`` for an example that demonstrates how to safely load content.
RealityKit extracts the cube faces from the source 2D image using a convention based on
its aspect ratio. See ``init(cubeFromImage:named:options:)-9dcus`` for more details.
```swift
if let source = CGImageSourceCreateWithURL(url as CFURL, nil),
let image = CGImageSourceCreateImageAtIndex(source, 0, nil) {
// Create a cube texture from the image.
let cube = try TextureResource(
cubeFromImage: image,
options: TextureResource.CreateOptions(semantic: .hdrColor))
// Create an environment resource from the cube texture.
let environment = try EnvironmentResource(
cube: cube, options: EnvironmentResource.CreateOptions())
// Assign the environment to an image-based light component.
let lightEntity = Entity()
lightEntity.components.set(ImageBasedLightComponent(source: .single(environment)))
...
}
```
- Parameters:
- cgImage: The source image.
- resourceName: A unique name for syncing the texture resource across the network.
The name is empty if you don't include one.
- options: A configuration for generating the texture.
Asynchronously creates a cube texture resource from a 2D image of cube faces.
RealityKit extracts the cube faces from the source 2D image using a convention based on
its aspect ratio, which needs to be one of the following:
- If `height == 6 * width`, RealityKit treats the source image as a vertical strip of the cube faces, containing [+X, -X, +Y, -Y, +Z, -Z] from top to bottom:
- If `6 * height == width`, RealityKit treats the source image as a horizontal strip of the cube faces, containing [+X, -X, +Y, -Y, +Z, -Z] from left to right:
- If `height / 3 == width / 4`, RealityKit treats the source image as a cross layout of the cube faces as follows:
```
[+Y]
[+X][-Z][-X][+Z]
[-Y]
```
Use the resulting texture to create an ``EnvironmentResource``,
or assign it to a material in Reality Composer Pro that requires
a cube texture type.
```swift
if let source = CGImageSourceCreateWithURL(url as CFURL, nil),
let image = CGImageSourceCreateImageAtIndex(source, 0, nil) {
// Create a cube texture from the image.
let cube = try await TextureResource(
cubeFromImage: image, options: TextureResource.CreateOptions(semantic: .hdrColor))
// Create an environment resource from the cube texture.
let environment = try await EnvironmentResource(
cube: cube, options: EnvironmentResource.CreateOptions())
await MainActor.run {
// Assign the environment to an image-based light component.
let lightEntity = Entity()
lightEntity.components.set(
ImageBasedLightComponent(source: .single(environment)))
...
}
}
```
- Parameters:
- cgImage: The source image.
- resourceName: A unique name for syncing the texture resource across the network.
The name is empty if you don't include one.
- options: A configuration for generating the texture.
get · iOS 15.0+
drawableQueue
TypeScript
get drawableQueue(): Promise<(TextureResource_DrawableQueue) | null>
Swift declaration
@MainActor @preconcurrency var drawableQueue: TextureResource.DrawableQueue? { get }
Asynchronously generates a texture resource from an in-memory Core
Graphics image.
This method creates a texture resource from an existing
<doc://com.apple.documentation/documentation/coregraphics/cgimage> with
specific options.
RealityKit uses the resource name to identify
resources, and to match texture resources between networked peers.
Specify a unique name for each texture resource you load or generate.
- Parameters:
- cgImage: The source image.
- resourceName: A unique name for syncing the texture resource across the network.
The name is empty if you don't include one.
- options: A configuration for generating the texture.
- Returns: A texture resource.
Synchronously creates a 2D texture array by generating it from images.
RealityKit creates a <doc://com.apple.documentation/documentation/metal/mtltexturetype/type2darray>
texture with`'arrayLength == slices.count` from an array of images.
You can assign the resulting texture to a material you create in Reality Composer Pro that requires a 2D texture array.
Loading a ``TextureResource`` 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.
See ``init(named:in:)`` for an example that demonstrates how to safely load content.
```swift
// Create a 2D array texture from image slices.
let texture2DArray = try await TextureResource.texture2DArray(
slices: [image0, image1, image2],
options: TextureResource.CreateOptions(semantic: .color))
// Assign the 2D array texture to a compatible shader graph material parameter.
var material = try await ShaderGraphMaterial(
named: "/Root/Spaceship/MaterialWith2DArray", from: url)
try material.setParameter(
name: "input2DArray", value: .textureResource(texture2DArray))
```
- Parameters:
- slices: The source images, one per 2D array index. All images need to have the same size and format.
- resourceName: A unique name for syncing the texture resource across the network.
The name is empty if you don't include one.
- options: A configuration for generating the texture.
Asynchronously creates a 2D texture array by generating it from images.
RealityKit creates a <doc://com.apple.documentation/documentation/metal/mtltexturetype/type2darray>
texture with `arrayLength == slices.count` from an array of images.
You can assign the resulting texture to a material you create in Reality Composer Pro that requires a 2D texture array.
```swift
// Create a 2D array texture from image slices.
let texture2DArray = try TextureResource.texture2DArray(
slices: [image0, image1, image2],
options: TextureResource.CreateOptions(semantic: .color))
Task {
// Assign the 2D array texture to a compatible shader graph material parameter.
var material = try await ShaderGraphMaterial(
named: "/Root/Spaceship/MaterialWith2DArray", from: url)
try material.setParameter(
name: "input2DArray", value: .textureResource(texture2DArray))
}
```
- Parameters:
- slices: The source images, one per 2D array index. All images need to have the same size and format.
- resourceName: A unique name for syncing the texture resource across the network.
The name is empty if you don't include one.
- options: A configuration for generating the texture.
get · iOS 15.0+
mipmapLevelCount
TypeScript
get mipmapLevelCount(): Promise<number>
Swift declaration
@MainActor @preconcurrency var mipmapLevelCount: Int { get }
The number of mipmaps for the texture.
Mipmaps are additional copies of the same texture at different
resolutions. This property contains the number of different versions of
the texture, including the original-size version.
Synchronously creates a cube texture resource from an equirectangular image.
Loading a ``TextureResource`` 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.
See ``init(named:in:)`` for an example that demonstrates how to safely load content.
RealityKit samples the source equirectangular image at the specified quality level to generate
the cube texture. See ``init(cubeFromEquirectangular:named:quality:faceSize:options:)-bqd7``
for equirectangular image requirements.
```swift
if let source = CGImageSourceCreateWithURL(url as CFURL, nil),
let image = CGImageSourceCreateImageAtIndex(source, 0, nil) {
// Create a cube texture from the image.
let cube = try TextureResource(
cubeFromEquirectangular: image, quality: .normal,
options: TextureResource.CreateOptions(semantic: .hdrColor))
// Create an environment resource from the cube texture.
let environment = try EnvironmentResource(
cube: cube, options: EnvironmentResource.CreateOptions())
// Assign the environment to an image-based light component.
let lightEntity = Entity()
lightEntity.components.set(ImageBasedLightComponent(
source: .single(environment)))
...
}
```
- Parameters:
- cgImage: The source image.
- resourceName: A unique name for syncing the texture resource across the network.
The name is empty if you don't include one.
- quality: The sampling quality the initializer applies as it generates the cube texture.
- faceSize: The length of the cube's sides, in pixels.
When `faceSize` is `nil`, RealityKit computes the size based on the equirectangular image's dimensions.
RealityKit clamps the value to the source image's height.
For best results, pass values that are one-third of the cubeʻs width or less.
- options: A configuration for generating the texture.
Asynchronously creates a cube texture resource from an equirectangular image.
RealityKit samples the source equirectangular image at the specified quality level to generate
the cube texture.
The equirectangular image, also known as a *latitude-longitude image*, contains a flattened
map of the surroundings where:
- The width is a `360°` clockwise scan along the horizon, starting from behind (+z-axis)
- The height is a -90° (bottom) to +90° (top) vertical scan
To preserve all details equirectangular images require a `2:1` aspect ratio.
Use the resulting texture to create an ``EnvironmentResource``,
or assign it to a material in Reality Composer Pro that requires
a cube texture type.
```swift
if let source = CGImageSourceCreateWithURL(url as CFURL, nil),
let image = CGImageSourceCreateImageAtIndex(source, 0, nil) {
// Create a cube texture from the image.
let cube = try await TextureResource(
cubeFromEquirectangular: image, quality: .normal,
options: TextureResource.CreateOptions(semantic: .hdrColor))
// Create an environment resource from the cube texture.
let environment = try await EnvironmentResource(
cube: cube, options: EnvironmentResource.CreateOptions())
await MainActor.run {
// Assign the environment to an image-based light component.
let lightEntity = Entity()
lightEntity.components.set(
ImageBasedLightComponent(source: .single(environment)))
...
}
}
```
- Note: ``EnvironmentResource/CreateOptions/SamplingQuality-swift.enum/high`` and
``EnvironmentResource/CreateOptions/SamplingQuality-swift.enum/veryHigh``, along with
``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 a cube's memory and disk usage.
- Parameters:
- cgImage: The source image.
- resourceName: A unique name for syncing the texture resource across the network.
The name is empty if you don't include one.
- quality: The sampling quality the initializer applies as it generates the cube texture.
- faceSize: The dimension of a cube face.
When `faceSize` is `nil`, RealityKit computes the size based on the equirectangular image's dimensions.
RealityKit clamps the value to the source image's height.
For best results, pass values that are one-third of the cubeʻs width or less.
- options: A configuration for generating the texture.
method · iOS 15.0+
copy
TypeScript
copyTo(texture: SDKHandle): Promise<void>
Swift declaration
@MainActor @preconcurrency func copy(to texture: any MTLTexture) throws
Copies texture data to another texture.
This method blocks until it finishes copying the data. If you have an attached ``TextureResource/DrawableQueue`` on
this resource, this function detaches it.
This method copies all available mipmap sizes to `texture`.
It's recommended that you provide a value for ``CreateOptions/semantic`` when creating this resource. Specifying a
semantic enables RealityKit to select an appropriate pixel format for the target texture.
Here's an example using ``copy(to:)`` to get a texture resource's raw pixel data:
```swift
let device: MTLDevice = ...
let resource: TextureResource = ...
let descriptor = MTLTextureDescriptor.texture2DDescriptor(
pixelFormat: .rgba8Unorm,
width: resource.width, // Needs to match the texture resource.
height: resource.height, // Needs to match the texture resource.
mipmapped: false)
descriptor.usage = .shaderWrite // This is required for copying.
guard let texture = device.makeTexture(descriptor: descriptor)
else { throw ... }
try resource.copy(to: texture)
#if os(OSX) // The managed mode exists only in OSX.
if texture.storageMode == .managed {
// You need to synchronize the managed textures before accessing their data.
guard let commandBuffer = device.makeCommandQueue()?.makeCommandBuffer(),
let blitEncoder = commandBuffer.makeBlitCommandEncoder()
else { throw ... }
blitEncoder.synchronize(resource: texture)
blitEncoder.endEncoding()
commandBuffer.commit()
commandBuffer.waitUntilCompleted()
}
#endif
// Getting the raw pixel bytes.
let bytesPerRow = 4 * texture.width
var bytes = [UInt8](repeating: 0, count: texture.height * bytesPerRow)
bytes.withUnsafeMutableBytes { bytesPtr in
texture.getBytes(
bytesPtr.baseAddress!,
bytesPerRow: bytesPerRow,
from: .init(origin: .init(), size: .init(width: texture.width, height: texture.height, depth: 1)),
mipmapLevel: 0
)
}
```
- Parameters:
- texture: The target texture for copying the data. It needs to have the same width and height as ``TextureResource``, and
<doc://com.apple.documentation/documentation/metal/mtltextureusage/1515854-shaderwrite> usage.
method · iOS 18.0+
copy
TypeScript
copyTo33360(texture: SDKHandle): Promise<void>
Swift declaration
@MainActor @preconcurrency func copy(to texture: any MTLTexture) async throws
Asynchronously copies texture data to another texture.
This method copies all available mipmap sizes to `texture`.
It's recommended that you provide a value for ``CreateOptions/semantic`` when creating this resource. Specifying a
semantic enables RealityKit to select an appropriate pixel format for the target texture.
- Parameters:
- texture: The target texture for copying the data. It needs to have the same width and height as ``TextureResource``, and
<doc://com.apple.documentation/documentation/metal/mtltextureusage/1515854-shaderwrite> usage.
Synchronously creates a cube texture resource from face images.
Provide the cube faces in the following order: [`+X`, `-X`, `+Y`, `-Y`, `+Z`, `-Z`].
See ``cube(slices:named:options:)-57yj1`` for more details.
Loading a ``TextureResource`` 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.
See ``init(named:in:)`` for an example that demonstrates how to safely load content.
```swift
// Create a cube texture from image slices.
let cube = try TextureResource.cube(
slices: [posXImage, negXImage, posYImage, negYImage, posZImage, negZImage],
options: TextureResource.CreateOptions(semantic: .hdrColor)
)
// Create an environment resource from the cube texture.
let environment = try EnvironmentResource(
cube: cube,
options: EnvironmentResource.CreateOptions()
)
// Assign the environment to an image-based light component.
let lightEntity = Entity()
lightEntity.components.set(ImageBasedLightComponent(source: .single(environment)))
...
```
- Parameters:
- slices: The source images for each cube face in [`+X`, `-X`, `+Y`, `-Y`, `+Z`, `-Z`] order. All images need to be square, and of equal size and format.
- resourceName: A unique name for syncing the texture resource across the network.
The name is empty if you don't include one.
- options: A configuration for generating the texture.
Asynchronously creates a cube texture resource from face images.
Provide the cube faces in the following order: [`+X`, `-X`, `+Y`, `-Y`, `+Z`, `-Z`].
|||||||
|-|-|-|-|-|-|
Use the resulting texture to create an ``EnvironmentResource``,
or assign it to a material in Reality Composer Pro that requires
a cube texture type.
```swift
// Create a cube texture from image slices.
let cube = try await TextureResource.cube(
slices: [posXImage, negXImage, posYImage, negYImage, posZImage, negZImage],
options: TextureResource.CreateOptions(semantic: .hdrColor)
)
// Create an environment resource from the cube texture.
let environment = try await EnvironmentResource(
cube: cube,
options: EnvironmentResource.CreateOptions()
)
await MainActor.run {
// Assign the environment to an image-based light component.
let lightEntity = Entity()
lightEntity.components.set(ImageBasedLightComponent(
source: .single(environment)))
...
}
```
- Parameters:
- slices: The source images for each cube face in [`+X`, `-X`, `+Y`, `-Y`, `+Z`, `-Z`] order.
All images need to be square, and of equal size.
- resourceName: A unique name for syncing the texture resource across the network.
The name is empty if you don't include one.
- options: A configuration for generating the texture.
Synchronously loads a texture resource from a URL with options.
Loading a ``TextureResource`` 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.
See ``init(named:in:)`` for an example that demonstrates how to safely load content.
This method loads the image that the `URL` specifies, and creates a texture
resource from it.
The method blocks until it finishes loading the image and creating
the texture resource.
RealityKit uses the resource name to identify resources, and to match
texture resources between networked peers. Specify a unique name for
each texture resource you load or generate.
- Parameters:
- url: The URL of the resource.
- resourceName: A unique name the method assigns to the resource it loads,
for use in network synchronization.
- options: A configuration for generating the texture.
- Returns: The loaded resource.
Synchronously loads a texture resource from a URL.
Loading a ``TextureResource`` 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.
See ``init(named:in:)`` for an example that demonstrates how to safely load content.
This method loads the image that the `URL` specifies, and creates a texture
resource from it. The method blocks until it finishes loading the image and creating
the texture resource.
RealityKit uses the resource name to distinguish resources locally, and to match texture
resources between networked peers.
Specify a unique name for each texture resource you load or generate.
- Parameters:
- url: The path or address of the file to load.
- resourceName: A unique name the method assigns to the resource it loads,
for use in network synchronization.
- Returns: The loaded resource.
get · iOS 18.0+
depth
TypeScript
get depth(): Promise<number>
Swift declaration
@MainActor @preconcurrency var depth: Int { get }
The depth of the texture image, in pixels.
The value is `0` if the texture isn't a 3D texture.
Synchronously creates a texture resource from an in-memory Core Graphics image.
Loading a ``TextureResource`` 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.
See ``init(named:in:)`` for an example that demonstrates how to safely load content.
This method creates a texture resource from an existing
<doc://com.apple.documentation/documentation/coregraphics/cgimage> with
specific options.
RealityKit uses the resource name to identify
resources, and to match texture resources between networked peers.
Specify a unique name for each texture resource you load or generate.
- Parameters:
- cgImage: The source image.
- resourceName: A unique name for syncing the texture resource across the network.
The name is empty if you don't include one.
- options: A configuration for generating the texture.
Asynchronously creates a texture resource from an in-memory Core
Graphics image.
This method creates a texture resource from an existing
<doc://com.apple.documentation/documentation/coregraphics/cgimage> with
specific options.
RealityKit uses the resource name to identify
resources, and to match texture resources between networked peers.
Specify a unique name for each texture resource you load or generate.
- Parameters:
- cgImage: The source image.
- resourceName: A unique name for syncing the texture resource across the network.
The name is empty if you don't include one.
- options: A configuration for generating the texture.
get · iOS 15.0+
width
TypeScript
get width(): Promise<number>
Swift declaration
@MainActor @preconcurrency var width: Int { get }
The width of the texture image, in pixels.
get · iOS 15.0+
height
TypeScript
get height(): Promise<number>
Swift declaration
@MainActor @preconcurrency var height: Int { get }
Replaces a texture resource with a low-level texture.
- Warning: It's more efficient to use ``LowLevelTexture/replace(using:)``
to update a ``LowLevelTexture`` on the GPU than it is to update the `TextureResource`.
Prefer to update the `LowLevelTexture` directly instead.
- Note: This method marks the asset as mutated, preventing newly loaded entities from sharing
the texture.
- Parameter texture: The texture data that defines the resource.
Asynchronously replaces the texture with a Core Graphics image.
Don't use this method for updates at frame-rate frequency.
For frequent texture changes, see ``replace(withDrawables:)``.
To ensure consistent usage of this texture resource, pass the same semantic
in `options` that you use to create the resource.
- Note: The contents of a modified texture resource don't sync between network clients.
- Parameters:
- cgImage: The source image.
- options: Options that specify the type of texture to create. To preserve `TextureResource` usage, specify the same semantic.
Dynamically replaces the texture with a Core Graphics image.
This method blocks until the resource updates.
Don't use this method for updates at frame-rate frequency.
For frequent texture changes, see ``replace(withDrawables:)``.
If you have an attached ``TextureResource/DrawableQueue`` on this resource, this function detaches it.
To ensure consistent usage of this texture resource, pass the same semantic in `options` that you use
to create the resource.
- Note: The contents of a modified texture resource don't sync between network clients.
- Parameters:
- cgImage: The source image.
- options: Options that specify the type of texture to create.
Synchronously creates a texture resource from an in-memory Core Graphics image.
This method creates a texture resource from an existing
<doc://com.apple.documentation/documentation/coregraphics/cgimage> with
specific options.
RealityKit uses the resource name to identify
resources, and to match texture resources between networked peers.
Specify a unique name for each texture resource you load or generate.
- Parameters:
- cgImage: The source image.
- resourceName: A unique name for syncing the texture resource across the network.
The name is empty if you don't include one.
- options: A configuration for generating the texture.
- Returns: A texture resource.
get · iOS 15.0+
semantic
TypeScript
get semantic(): Promise<(TextureResource_Semantic) | null>
Swift declaration
@MainActor @preconcurrency var semantic: TextureResource.Semantic? { get }
Asynchronously copies texture data to another texture.
This function is asynchronous. It returns immediately and runs in the background, calling `completionHandler` when it finishes or errors.
This method copies all available mipmap sizes to `texture`.
It's recommended that you provide a value for ``CreateOptions/semantic`` when creating this resource. Specifying a
semantic enables RealityKit to select an appropriate pixel format for the target texture.
- Parameters:
- texture: The target texture for copying the data.
It needs to have the same width and height as ``TextureResource``, and
<doc://com.apple.documentation/documentation/metal/mtltextureusage/1515854-shaderwrite> usage.
- completionHandler: The system calls this closure after it finishes copying the data, with a `nil` error if it succeeds.
Asynchronously loads a texture resource from a URL with options.
RealityKit uses the resource name to distinguish resources locally, and to match
texture resources between networked peers. Specify a unique name for
each texture resource you load or generate.
- Parameters:
- url: The path or address of the file to load.
- resourceName: A unique name the method assigns to the resource it loads,
for use in network synchronization.
- options: A configuration for generating the texture.
- Returns: A load operation that publishes the resource.
Asynchronously loads a texture resource from a URL.
RealityKit uses the resource name to distinguish resources locally, and to match
texture resources between networked peers. Specify a unique name for
each texture resource you load or generate.
- Parameters:
- url: The path or address of the file to load.
- resourceName: A unique name the method assigns to the resource it loads,
for use in network synchronization.
- Returns: A load operation that publishes the resource.
Synchronously creates a 3D texture by generating it from images.
RealityKit creates a <doc://com.apple.documentation/documentation/metal/mtltexturetype/type3d>
texture with `depth == slices.count` from an array of images.
You can assign the resulting texture to a material you create in Reality Composer Pro that requires a 3D texture.
Loading a ``TextureResource`` 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.
See ``init(named:in:)`` for an example that demonstrates how to safely load content.
```swift
// Create a 3D texture from image slices.
let texture3D = try TextureResource.texture3D(
slices: [image0, image1, image2, image3],
options: TextureResource.CreateOptions(semantic: .color))
Task {
// Assign the 3D texture to a compatible shader graph material parameter.
var material = try await ShaderGraphMaterial(
named: "/Root/Alien/MaterialWith3DTexture", from: url)
try material.setParameter(
name: "input3DTexture",
value: .textureResource(texture3D))
}
```
- Parameters:
- slices: The source images, one per depth index.
All images need to be square, and of equal size and format.
- resourceName: A unique name for syncing the texture resource across the network.
The name is empty if you don't include one.
- options: A configuration for generating the texture.
Asynchronously creates a 3D texture by generating it from images.
RealityKit creates a <doc://com.apple.documentation/documentation/metal/mtltexturetype/type3d>
texture with `depth == slices.count` from an array of images.
You can assign the resulting texture to a material you create in Reality Composer Pro that requires a 3D texture.
```swift
// Create a 3D texture from image slices.
let texture3D = try await TextureResource.texture3D(
slices: [image0, image1, image2, image3],
options: TextureResource.CreateOptions(semantic: .color))
// Assign the 3D texture to a compatible shader graph material parameter.
var material = try await ShaderGraphMaterial(
named: "/Root/Alien/MaterialWith3DTexture", from: url)
try material.setParameter(
name: "input3DTexture",
value: .textureResource(texture3D))
```
- Parameters:
- slices: The source images, one per depth index.
All images need to be square, and of equal size and format.
- resourceName: A unique name for syncing the texture resource across the network.
The name is empty if you don't include one.
- options: A configuration for generating the texture.
