Package com.google.android.filament

Class IndirectLight

  • public class IndirectLight
extends java.lang.Object
    IndirectLight is used to simulate environment lighting, a form of global illumination.

    Environment lighting has a two components:

    1. irradiance
    2. 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 Engine.destroyIndirectLight(com.google.android.filament.IndirectLight).

      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.

    See Also:
    Scene, LightManager, Texture, Skybox

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  IndirectLight.Builder
      Use Builder to construct an IndirectLight object instance.

    • Constructor Summary

      Constructors 
      Constructor Description
      IndirectLight​(long indirectLight)  

    • Constructor Detail

      • IndirectLight

        public IndirectLight​(long indirectLight)

    • Method Detail

      • setIntensity

        public void setIntensity​(float intensity)
        Sets the environment's intensity.

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

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

      • getIntensity

        public float getIntensity()
        Returns the environment's intensity in lux, or lumen/m^2.

      • setRotation

        public void setRotation​(@NonNull @Size(min=9L)
                        float[] rotation)
        Sets the rigid-body transformation to apply to the IBL.
        Parameters:
        rotation - 3x3 rotation matrix. Must be a rigid-body transform.

      • getRotation

        @NonNull
@Size(min=9L)
public float[] getRotation​(@Nullable @Size(min=9L)
                           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 to the IBL or null
        Returns:
        the rotation paramter if it was provided, or a newly allocated float array containing the rigid-body transformation applied to the IBL

      • getDirectionEstimate

        @NonNull
@Size(min=3L)
public static float[] getDirectionEstimate​(@NonNull
                                           float[] sh,
                                           @Nullable @Size(min=3L)
                                           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 outdoors environments), if it's not the case the direction returned will be an average of the various 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 of the dominant light or null
        Returns:
        the direction paramter if it was provided, or a newly allocated float array containing a unit vector representing the direction of the dominant light
        See Also:
        LightManager.Builder.direction(float, float, float), getColorEstimate(float[], float[], float, float, float)

      • getDirectionEstimate

        @Deprecated
@NonNull
@Size(min=3L)
public float[] getDirectionEstimate​(@Nullable @Size(min=3L)
                                    float[] direction)
        Deprecated.

      • getColorEstimate

        @NonNull
@Size(min=4L)
public static float[] getColorEstimate​(@Nullable @Size(min=4L)
                                       float[] colorIntensity,
                                       @NonNull
                                       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 case make 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
        Returns:
        A vector of 4 floats where the first 3 components represent the linear color and the 4th component represents the intensity of the dominant light
        See Also:
        LightManager.Builder.color(float, float, float), LightManager.Builder.intensity(float), getDirectionEstimate(float[], float[]), getIntensity(), setIntensity(float)

      • getColorEstimate

        @Deprecated
@NonNull
@Size(min=4L)
public float[] getColorEstimate​(@Nullable @Size(min=4L)
                                float[] colorIntensity,
                                float x,
                                float y,
                                float z)
        Deprecated.

      • getReflectionsTexture

        @Nullable
public Texture getReflectionsTexture()

      • getIrradianceTexture

        @Nullable
public Texture getIrradianceTexture()

      • getNativeObject

        public long getNativeObject()