/*
 * Copyright (C) 2016 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

//! \file

#ifndef TNT_FILAMENT_INDIRECT_LIGHT_H
#define TNT_FILAMENT_INDIRECT_LIGHT_H

#include <filament/FilamentAPI.h>

#include <utils/compiler.h>

#include <math/mathfwd.h>

namespace filament {

class Engine;
class Texture;

class FIndirectLight;

/**
 * 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.
 *
 * @note
 * 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::destroy(const IndirectLight*).
 *
 * ~~~~~~~~~~~{.cpp}
 *  filament::Engine* engine = filament::Engine::create();
 *
 *  filament::IndirectLight* environment = filament::IndirectLight::Builder()
 *              .reflections(cubemap)
 *              .build(*engine);
 *
 *  engine->destroy(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](https://en.wikipedia.org/wiki/Spherical_harmonics) (SH) of 1, 2 or
 * 3 bands, respectively 1, 4 or 9 coefficients.
 *
 * @note
 * Use the **cmgen** tool to generate the `SH` 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 Scene, Light, Texture, Skybox
 */
class UTILS_PUBLIC IndirectLight : public FilamentAPI {
    struct BuilderDetails;

public:

    //! Use Builder to construct an IndirectLight object instance
    class Builder : public BuilderBase<BuilderDetails> {
        friend struct BuilderDetails;
    public:
        Builder() noexcept;
        Builder(Builder const& rhs) noexcept;
        Builder(Builder&& rhs) noexcept;
        ~Builder() noexcept;
        Builder& operator=(Builder const& rhs) noexcept;
        Builder& operator=(Builder&& rhs) noexcept;

        /**
         * Set the reflections cubemap mipmap chain.
         *
         * @param cubemap   A mip-mapped cubemap generated by **cmgen**. Each cubemap level
         *                  encodes a the irradiance for a roughness level.
         *
         * @return This Builder, for chaining calls.
         *
         */
        Builder& reflections(Texture const* cubemap) noexcept;

        /**
         * Sets the irradiance as Spherical Harmonics.
         *
         * The irradiance must be pre-convolved by \f$ \langle n \cdot l \rangle \f$ and
         * pre-multiplied by the Lambertian diffuse BRDF \f$ \frac{1}{\pi} \f$ and
         * specified as Spherical Harmonics coefficients.
         *
         * Additionally, these Spherical Harmonics coefficients must be pre-scaled by the
         * reconstruction factors \f$ A_{l}^{m} \f$ below.
         *
         * The final coefficients can be generated using the `cmgen` tool.
         *
         * The index in the \p sh array is given by:
         *
         *  `index(l, m) = l * (l + 1) + m`
         *
         *  \f$ sh[index(l,m)] = L_{l}^{m} \frac{1}{\pi} A_{l}^{m} \hat{C_{l}} \f$
         *
         *   index |  l  |  m  |  \f$ A_{l}^{m} \f$ |  \f$ \hat{C_{l}} \f$  |  \f$ \frac{1}{\pi} A_{l}^{m}\hat{C_{l}} \f$ |
         *  :-----:|:---:|:---:|:------------------:|:---------------------:|:--------------------------------------------:
         *     0   |  0  |  0  |      0.282095      |       3.1415926       |   0.282095
         *     1   |  1  | -1  |     -0.488602      |       2.0943951       |  -0.325735
         *     2   |  ^  |  0  |      0.488602      |       ^               |   0.325735
         *     3   |  ^  |  1  |     -0.488602      |       ^               |  -0.325735
         *     4   |  2  | -2  |      1.092548      |       0.785398        |   0.273137
         *     5   |  ^  | -1  |     -1.092548      |       ^               |  -0.273137
         *     6   |  ^  |  0  |      0.315392      |       ^               |   0.078848
         *     7   |  ^  |  1  |     -1.092548      |       ^               |  -0.273137
         *     8   |  ^  |  2  |      0.546274      |       ^               |   0.136569
         *
         *
         * Only 1, 2 or 3 bands are allowed.
         *
         * @param bands     Number of spherical harmonics bands. Must be 1, 2 or 3.
         * @param sh        Array containing the spherical harmonics coefficients.
         *                  The size of the array must be \f$ bands^{2} \f$.
         *                  (i.e. 1, 4 or 9 coefficients respectively).
         *
         * @return This Builder, for chaining calls.
         *
         * @note
         * Because the coefficients are pre-scaled, `sh[0]` is the environment's
         * average irradiance.
         */
        Builder& irradiance(uint8_t bands, math::float3 const* sh) noexcept;

        /**
         * Sets the irradiance from the radiance expressed as Spherical Harmonics.
         *
         * The radiance must be specified as Spherical Harmonics coefficients \f$ L_{l}^{m} \f$
         *
         * The index in the \p sh array is given by:
         *
         *  `index(l, m) = l * (l + 1) + m`
         *
         *  \f$ sh[index(l,m)] = L_{l}^{m} \f$
         *
         *   index |  l  |  m
         *  :-----:|:---:|:---:
         *     0   |  0  |  0
         *     1   |  1  | -1
         *     2   |  ^  |  0
         *     3   |  ^  |  1
         *     4   |  2  | -2
         *     5   |  ^  | -1
         *     6   |  ^  |  0
         *     7   |  ^  |  1
         *     8   |  ^  |  2
         *
         * @param bands     Number of spherical harmonics bands. Must be 1, 2 or 3.
         * @param sh        Array containing the spherical harmonics coefficients.
         *                  The size of the array must be \f$ bands^{2} \f$.
         *                  (i.e. 1, 4 or 9 coefficients respectively).
         *
         * @return This Builder, for chaining calls.
         */
        Builder& radiance(uint8_t bands, math::float3 const* sh) noexcept;

        /**
         * Sets the irradiance as a cubemap.
         *
         * The irradiance can alternatively be specified as a cubemap instead of Spherical
         * Harmonics coefficients. It may or may not be more efficient, depending on your
         * hardware (essentially, it's trading ALU for bandwidth).
         *
         * @param cubemap   Cubemap representing the Irradiance pre-convolved by
         *                  \f$ \langle n \cdot l \rangle \f$.
         *
         * @return This Builder, for chaining calls.
         *
         * @note
         * This irradiance cubemap can be generated with the **cmgen** tool.
         *
         * @see irradiance(uint8_t bands, math::float3 const* sh)
         */
        Builder& irradiance(Texture const* cubemap) noexcept;

        /**
         * (optional) Environment intensity.
         *
         * Because the environment is encoded usually relative to some reference, the
         * range can be adjusted with this method.
         *
         * @param envIntensity  Scale factor applied to the environment and irradiance such that
         *                      the result is in cd/m^2 (lux) units (default = 30000)
         *
         * @return This Builder, for chaining calls.
         */
        Builder& intensity(float envIntensity) noexcept;

        /**
         * Specifies the rigid-body transformation to apply to the IBL.
         *
         * @param rotation 3x3 rotation matrix. Must be a rigid-body transform.
         *
         * @return This Builder, for chaining calls.
         */
        Builder& rotation(math::mat3f const& rotation) noexcept;

        /**
         * Creates the IndirectLight object and returns a pointer to it.
         *
         * @param engine Reference to the filament::Engine to associate this IndirectLight with.
         *
         * @return pointer to the newly created object or nullptr if exceptions are disabled and
         *         an error occurred.
         *
         * @exception utils::PostConditionPanic if a runtime error occurred, such as running out of
         *            memory or other resources.
         * @exception utils::PreConditionPanic if a parameter to a builder function was invalid.
         */
        IndirectLight* build(Engine& engine);

    private:
        friend class FIndirectLight;
    };

    /**
     * Sets the environment's intensity.
     *
     * Because the environment is encoded usually relative to some reference, the
     * range can be adjusted with this method.
     *
     * @param intensity  Scale factor applied to the environment and irradiance such that
     *                   the result is in cd/m^2 units (default = 30000)
     */
    void setIntensity(float intensity) noexcept;

    /**
     * Returns the environment's intensity in cd/m^2.
     */
    float getIntensity() const noexcept;

    /**
     * Sets the rigid-body transformation to apply to the IBL.
     *
     * @param rotation 3x3 rotation matrix. Must be a rigid-body transform.
     */
    void setRotation(math::mat3f const& rotation) noexcept;

    /**
     * Returns the rigid-body transformation applied to the IBL.
     */
    const math::mat3f& getRotation() const noexcept;

    /**
     * Returns the associated reflection map, or null if it does not exist.
     */
    Texture const* getReflectionsTexture() const noexcept;

    /**
     * Returns the associated irradiance map, or null if it does not exist.
     */
    Texture const* getIrradianceTexture() const noexcept;

    /**
     * Helper to estimate the direction of the dominant light in the environment represented by
     * spherical harmonics.
     *
     * 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.
     *
     * @param sh        3-band spherical harmonics
     *
     * @return A unit vector representing the direction of the dominant light
     *
     * @see LightManager::Builder::direction()
     * @see getColorEstimate()
     */
    static math::float3 getDirectionEstimate(const math::float3 sh[9]) noexcept;

    /**
     * Helper to estimate the color and relative intensity of the environment represented by
     * spherical harmonics 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.
     *
     * @param sh        3-band spherical harmonics
     * @param direction a unit vector representing the direction of the light to estimate the
     *                  color of. Typically this the value returned by getDirectionEstimate().
     *
     * @return 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 LightManager::Builder::color()
     * @see LightManager::Builder::intensity()
     * @see getDirectionEstimate, getIntensity, setIntensity
     */
    static math::float4 getColorEstimate(const math::float3 sh[9], math::float3 direction) noexcept;


    /** @deprecated use static versions instead */
    UTILS_DEPRECATED
    math::float3 getDirectionEstimate() const noexcept;

    /** @deprecated use static versions instead */
    UTILS_DEPRECATED
    math::float4 getColorEstimate(math::float3 direction) const noexcept;
};

} // namespace filament

#endif // TNT_FILAMENT_INDIRECT_LIGHT_H