Instance Property

sphericalHarmonicsCoefficients

Data containing the spherical harmonics coefficients for the light.

Declaration

var sphericalHarmonicsCoefficients: Data? { get }

Discussion

Spherical harmonic coefficients describe the distribution of light around a light source with less high-frequency detail than a cube map texture, but they can be used more efficiently in real-time rendering. Use the generateSphericalHarmonics(fromIrradiance:) method to create spherical harmonics data based on the light probe’s irradiance texture.

The data is an array of 32-bit floating-point values, containing three noninterleaved data sets corresponding to the red, green, and blue sets of coefficients. The array’s length is determined by the sphericalHarmonicsLevel property:

  • At level 0, the array has 1 coefficient (3 values).

  • At level 1, the array has 4 coefficients (3 sets of 4 values, 12 values total).

  • At level 2, the array has 9 coefficients (3 sets of 9 values, 27 values total).

  • At level 3, the array has 16 coefficients (3 sets of 16 values, 48 values total).

  • Spherical harmonics levels beyond 3 are not supported.

For example, the code below shows how to access the second coefficient at level 2.

func numberOfCoefficients(at level: Int) -> Int {
    return (level + 1) * (level + 1)
}
func offsetForLevel(_ level: Int) -> Int {
    return numberOfCoefficients(at: level - 1) - 1
}
guard let coeffs = light.sphericalHarmonicsCoefficients
    else { fatalError("light does not have spherical harmonics") }
let totalCount = numberOfCoefficients(at: light.sphericalHarmonicsLevel)
let offset = offsetForLevel(2) // level 2 has three sets of coefficients, at indexes 3...5
let index = 1 // get the second of 3 coefficients on level 2 (zero-based index)
coeffs.withUnsafeBytes { (bytes: UnsafePointer<Float>) -> () in
    let red = bytes[offset + index]
    let green = bytes[totalCount + offset + index]
    let blue = bytes[totalCount * 2 + offset + index]
}

See Also

Working with Spherical Harmonics

func generateSphericalHarmonics(fromIrradiance: Int)

Generates spherical harmonics information based on the light probe’s irradiance texture.

var sphericalHarmonicsLevel: Int

The number of levels of spherical harmonics information in the light probe.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software