Package 

Class IndirectLight

  • 
public class IndirectLight

    IndirectLight is used to simulate environment lighting, a form of global illumination.

    Environment lighting has a two components:

    • irradiance
    • reflections (specular component)

    Environments are usually captured as high-resolution HDR equirectangular images and processed by the cmgen tool to generate the data needed by IndirectLight.

    Currently IndirectLight is intended to be used for "distant probes", that is, to represent global illumination from a distant (i.e. at infinity) environment, such as the sky or distant mountains. Only a single IndirectLight can be used in a Scene. This limitation will be lifted in the future.

    Creation and destruction

    An IndirectLight object is created using the IndirectLight.Builder and destroyed by calling destroyIndirectLight.

     Engine engine = Engine.create();

 Scene scene = engine.createScene();

 IndirectLight environment = new IndirectLight.Builder()
             .reflections(cubemap)
             .irradiance(numBands, sphericalHarmonicsCoefficients)
             .build(engine);

 scene.setIndirectLight(environment);
    Irradiance

    The irradiance represents the light that comes from the environment and shines an object's surface. The irradiance is calculated automatically from the Reflections (see below), and generally doesn't need to be provided explicitly. However, it can be provided separately from the Reflections as Spherical Harmonics (SH) of 1, 2 or 3 bands, respectively 1, 4 or 9 coefficients.

    Use the cmgen tool to generate the Spherical Harmonics for a given environment.

    Reflections

    The reflections on object surfaces (specular component) is calculated from a specially filtered cubemap pyramid generated by the cmgen tool.

    • Constructor Detail

      • IndirectLight

        IndirectLight(long indirectLight)

    • Method Detail

      • setIntensity

         void setIntensity(float intensity)

        Sets the environment's intensity.

        Because the environment is encoded usually relative to some reference, therange can be adjusted with this method.

        Parameters:
        intensity - Scale factor applied to the environment and irradiance such thatthe result is in lux, or lumen/m^2 (default = 30000)

      • getIntensity

         float getIntensity()

        Returns the environment's intensity in lux, or lumen/m^2.

      • setRotation

         void setRotation(@NonNull() @Size(min = 9) Array<float> rotation)

        Sets the rigid-body transformation to apply to the IBL.

        Parameters:
        rotation - 3x3 rotation matrix.

      • getRotation

        @NonNull()@Size(min = 9) Array<float> getRotation(@Nullable() @Size(min = 9) Array<float> rotation)

        Returns the rigid-body transformation applied to the IBL.

        Parameters:
        rotation - an array of 9 floats to receive the rigid-body transformation applied tothe IBL or null

      • getDirectionEstimate

        @NonNull()@Size(min = 3) static Array<float> getDirectionEstimate(@NonNull() Array<float> sh, @Nullable() @Size(min = 3) Array<float> direction)

        Helper to estimate the direction of the dominant light in the environment.

        This assumes that there is only a single dominant light (such as the sun in outdoorsenvironments), if it's not the case the direction returned will be an average of thevarious lights based on their intensity.

        If there are no clear dominant light, as is often the case with low dynamic range (LDR)environments, this method may return a wrong or unexpected direction.

        The dominant light direction can be used to set a directional light's direction,for instance to produce shadows that match the environment.

        Parameters:
        sh - pre-scaled 3-bands spherical harmonics
        direction - an array of 3 floats to receive a unit vector representing the direction ofthe dominant light or null

      • getColorEstimate

        @NonNull()@Size(min = 4) static Array<float> getColorEstimate(@Nullable() @Size(min = 4) Array<float> colorIntensity, @NonNull() Array<float> sh, float x, float y, float z)

        Helper to estimate the color and relative intensity of the environment in a given direction.

        This can be used to set the color and intensity of a directional light. In this casemake sure to multiply this relative intensity by the the intensity of this indirect light.

        Parameters:
        colorIntensity - an array of 4 floats to receive the result or null
        sh - pre-scaled 3-bands spherical harmonics
        x - the x coordinate of a unit vector representing the direction of the light
        y - the x coordinate of a unit vector representing the direction of the light
        z - the x coordinate of a unit vector representing the direction of the light