struct · iOS 15.0+ · SDK 27.1
struct SurfaceShaderThe custom material’s surface shader function. Custom materials work together with a surface shader function to render entities. The ``CustomMaterial`` properties related to rendering, such as ``CustomMaterial/baseColor-swift.property`` and ``CustomMaterial/normal-swift.property``, are available in the surface shader function, but RealityKit doesn’t use them directly. Instead, the material’s surface shader function allows you to calculate or specify all the material parameters that RealityKit uses to render your entity, such as ``CustomMaterial/baseColor-swift.property``, ``CustomMaterial/normal-swift.property``, and ``CustomMaterial/roughness-swift.property``. RealityKit’s fragment shader calls your surface shader function once for each pixel it renders. Here’s a simple example of a surface shader that sets the entity’s base color: ```cpp #include <metal_stdlib> #include <RealityKit/RealityKit.h> // Specify the current default namespace as metal so that it's not // necessary to prefix Metal Standard Library symbols. using namespace metal; [[visible]] void mySurfaceShader(realitykit::surface_parameters params) { // Set the base color params.surface().set_base_color(half3(1.0, 0.5, 0.5)); } ``` For more information on creating custom materials and writing shader functions, see <doc:modifying-realitykit-rendering-using-custom-materials>.
get constantValues(): _Metal_MTLFunctionConstantValuesvar constantValues: MTLFunctionConstantValues { get set }The constant values to use when RealityKit creates your function. These correspond to constants defined in your metal code.
set constantValues(value: _Metal_MTLFunctionConstantValues)var constantValues: MTLFunctionConstantValues { get set }The constant values to use when RealityKit creates your function. These correspond to constants defined in your metal code.
get name(): stringvar name: StringThe name of the surface shader function. This is the name of the Metal function the custom material uses as its surface shader. The name needs to match the name of a Metal function in your Xcode project and can’t include parameters or parentheses.
set name(value: string)var name: StringThe name of the surface shader function. This is the name of the Metal function the custom material uses as its surface shader. The name needs to match the name of a Metal function in your Xcode project and can’t include parameters or parentheses.
static initNamedInConstantValues(name: string, library: SDKHandle, constantValues: _Metal_MTLFunctionConstantValues): CustomMaterial_SurfaceShaderinit(named name: String, in library: any MTLLibrary, constantValues: MTLFunctionConstantValues)Creates a surface shader with the specified function constant values. Function constants allow you to better share code or toggle features in your shaders without runtime performance costs by resolving their values at compile time. To use function constants, first define them within your metal code: ```cpp constant bool kEnableBasicLighting [[function_constant(0)]]; [[stitchable]] void surfaceShader(realitykit::surface_parameters params) { float3 baseColor = float3(1,0,0); if (kEnableBasicLighting) { float3 lighting = params.geometry().normal() * params.geometry().view_direction() * baseColor; params.surface().set_emissive_color(half3(lighting)); } else { params.surface().set_emissive_color(half3(baseColor)); } } ``` Then initialize a surface shader with a ``Metal/MTLFunctionConstantValues`` object that defines values for your constants. ```swift let constants = MTLFunctionConstantValues() var yes = true funcConstants.setConstantValue(&yes, type: .bool, index: 0) let geom = CustomMaterial.SurfaceShader.init(named: "surfaceShader", in: library, constantValues: constants) ```
static initNamedIn(name: string, library: SDKHandle): CustomMaterial_SurfaceShaderinit(named name: String, in library: any MTLLibrary)Creates a surface shader object from a named function in a Metal library. To create a surface shader for a custom material, create a Metal file in your Xcode project. Prefix the function with the keyword `[[visible]]`. The function needs to take a single parameter of type `realitykit::surface_parameters`. Here’s what a minimal surface shader function looks like: ```cpp #include <metal_stdlib> #include <RealityKit/RealityKit.h> // Specify the current default namespace as metal so our code // doesn't have to to prefix Metal Standard Library symbols. using namespace metal; [[visible]] void mySurfaceShader(realitykit::surface_parameters params) { // Calculate parameters needed for rendering. } ``` To create a custom material using this shader, get a reference to your app’s Metal library: ```swift guard let device = MTLCreateSystemDefaultDevice() else { fatalError("Error creating default metal device.") } guard let library = maybeDevice.makeDefaultLibrary() else { fatalError("Error creating default metal library") } ``` Once you have a reference to your Metal library, use it to create the surface shader reference: ```swift let surfaceShader = CustomMaterial.SurfaceShader( named: "mySurfaceShader", in: library ) ``` - Important: RealityKit loads surface shader functions by name, so name your surface shader uniquely and to exactly match the `named` parameter. For more information on creating custom materials and writing shader functions, see <doc:modifying-realitykit-rendering-using-custom-materials>. - Parameters: - name: The name of the surface shader function. - library: The Metal library that contains the function.
get library(): SDKHandlevar library: any MTLLibrary { get set }The Metal library that contains this surface shader function.
set library(value: SDKHandle)var library: any MTLLibrary { get set }The Metal library that contains this surface shader function.
No declarations were skipped in this snapshot.