upgrade to Filament 1.21.0

ios/include/ibl/Cubemap.h

@@ -0,0 +1,199 @@
+/*
+ * Copyright (C) 2015 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.
+ */
+
+#ifndef IBL_CUBEMAP_H
+#define IBL_CUBEMAP_H
+
+#include <ibl/Image.h>
+
+#include <utils/compiler.h>
+
+#include <math/vec4.h>
+#include <math/vec3.h>
+#include <math/vec2.h>
+
+#include <algorithm>
+
+namespace filament {
+namespace ibl {
+
+/**
+ * Generic cubemap class. It handles writing / reading into the 6 faces of a cubemap.
+ *
+ * Seamless trilinear filtering is handled.
+ *
+ * This class doesn't own the face data, it's just a "view" on the 6 images.
+ *
+ * @see CubemapUtils
+ *
+ */
+class UTILS_PUBLIC Cubemap {
+public:
+
+    /**
+     *  Initialize the cubemap with a given size, but no face is set and no memory is allocated.
+     *
+     *  Usually Cubemaps are created using CubemapUtils.
+     *
+     * @see CubemapUtils
+     */
+    explicit Cubemap(size_t dim);
+
+    Cubemap(Cubemap&&) = default;
+    Cubemap& operator=(Cubemap&&) = default;
+
+    ~Cubemap();
+
+
+    enum class Face : uint8_t {
+        PX = 0,     // left            +----+
+        NX,         // right           | PY |
+        PY,         // bottom     +----+----+----+----+
+        NY,         // top        | NX | PZ | PX | NZ |
+        PZ,         // back       +----+----+----+----+
+        NZ          // front           | NY |
+                    //                 +----+
+    };
+
+    using Texel = filament::math::float3;
+
+
+    //! releases all images and reset the cubemap size
+    void resetDimensions(size_t dim);
+
+    //! assigns an image to a face.
+    void setImageForFace(Face face, const Image& image);
+
+    //! retrieves the image attached to a face
+    inline const Image& getImageForFace(Face face) const;
+
+    //! retrieves the image attached to a face
+    inline Image& getImageForFace(Face face);
+
+    //! computes the center of a pixel at coordinate x, y
+    static inline filament::math::float2 center(size_t x, size_t y);
+
+    //! computes a direction vector from a face and a location of the center of pixel in an Image
+    inline filament::math::float3 getDirectionFor(Face face, size_t x, size_t y) const;
+
+    //! computes a direction vector from a face and a location in pixel in an Image
+    inline filament::math::float3 getDirectionFor(Face face, float x, float y) const;
+
+    //! samples the cubemap at the given direction using nearest neighbor filtering
+    inline Texel const& sampleAt(const filament::math::float3& direction) const;
+
+    //! samples the cubemap at the given direction using bilinear filtering
+    inline Texel filterAt(const filament::math::float3& direction) const;
+
+    //! samples an image at the given location in pixel using bilinear filtering
+    static Texel filterAt(const Image& image, float x, float y);
+    static Texel filterAtCenter(const Image& image, size_t x, size_t y);
+
+    //! samples two cubemaps in a given direction and lerps the result by a given lerp factor
+    static Texel trilinearFilterAt(const Cubemap& c0, const Cubemap& c1, float lerp,
+            const filament::math::float3& direction);
+
+    //! reads a texel at a given address
+    inline static const Texel& sampleAt(void const* data) {
+        return *static_cast<Texel const*>(data);
+    }
+
+    //! writes a texel at a given address
+    inline static void writeAt(void* data, const Texel& texel) {
+        *static_cast<Texel*>(data) = texel;
+    }
+
+    //! returns the size of the cubemap in pixels
+    size_t getDimensions() const;
+
+    /**
+     * Prepares a cubemap for seamless access to its faces.
+     *
+     * @warning All faces of the cubemap must be backed-up by the same Image, and must already
+     * be spaced by 2 lines/rows.
+     */
+    void makeSeamless();
+
+    struct Address {
+        Face face;
+        float s = 0;
+        float t = 0;
+    };
+
+    //! returns the face and texture coordinates of the given direction
+    static Address getAddressFor(const filament::math::float3& direction);
+
+private:
+    size_t mDimensions = 0;
+    float mScale = 1;
+    float mUpperBound = 0;
+    Image mFaces[6];
+};
+
+// ------------------------------------------------------------------------------------------------
+
+inline const Image& Cubemap::getImageForFace(Face face) const {
+    return mFaces[int(face)];
+}
+
+inline Image& Cubemap::getImageForFace(Face face) {
+    return mFaces[int(face)];
+}
+
+inline filament::math::float2 Cubemap::center(size_t x, size_t y) {
+    return { x + 0.5f, y + 0.5f };
+}
+
+inline filament::math::float3 Cubemap::getDirectionFor(Face face, size_t x, size_t y) const {
+    return getDirectionFor(face, x + 0.5f, y + 0.5f);
+}
+
+inline filament::math::float3 Cubemap::getDirectionFor(Face face, float x, float y) const {
+    // map [0, dim] to [-1,1] with (-1,-1) at bottom left
+    float cx = (x * mScale) - 1;
+    float cy = 1 - (y * mScale);
+
+    filament::math::float3 dir;
+    const float l = std::sqrt(cx * cx + cy * cy + 1);
+    switch (face) {
+        case Face::PX:  dir = {   1, cy, -cx }; break;
+        case Face::NX:  dir = {  -1, cy,  cx }; break;
+        case Face::PY:  dir = {  cx,  1, -cy }; break;
+        case Face::NY:  dir = {  cx, -1,  cy }; break;
+        case Face::PZ:  dir = {  cx, cy,   1 }; break;
+        case Face::NZ:  dir = { -cx, cy,  -1 }; break;
+    }
+    return dir * (1 / l);
+}
+
+inline Cubemap::Texel const& Cubemap::sampleAt(const filament::math::float3& direction) const {
+    Cubemap::Address addr(getAddressFor(direction));
+    const size_t x = std::min(size_t(addr.s * mDimensions), mDimensions - 1);
+    const size_t y = std::min(size_t(addr.t * mDimensions), mDimensions - 1);
+    return sampleAt(getImageForFace(addr.face).getPixelRef(x, y));
+}
+
+inline Cubemap::Texel Cubemap::filterAt(const filament::math::float3& direction) const {
+    Cubemap::Address addr(getAddressFor(direction));
+    addr.s = std::min(addr.s * mDimensions, mUpperBound);
+    addr.t = std::min(addr.t * mDimensions, mUpperBound);
+    return filterAt(getImageForFace(addr.face), addr.s, addr.t);
+}
+
+} // namespace ibl
+} // namespace filament
+
+#endif /* IBL_CUBEMAP_H */

ios/include/ibl/CubemapIBL.h

@@ -0,0 +1,91 @@
+/*
+ * Copyright (C) 2015 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.
+ */
+
+#ifndef IBL_CUBEMAPIBL_H
+#define IBL_CUBEMAPIBL_H
+
+#include <math/vec3.h>
+
+#include <utils/Slice.h>
+#include <utils/compiler.h>
+
+#include <vector>
+
+#include <stdint.h>
+#include <stddef.h>
+
+namespace utils {
+class JobSystem;
+} // namespace utils
+
+namespace filament {
+namespace ibl {
+
+class Cubemap;
+class Image;
+
+/**
+ * Generates cubemaps for the IBL.
+ */
+class UTILS_PUBLIC CubemapIBL {
+public:
+    typedef void (*Progress)(size_t, float, void*);
+
+    /**
+     * Computes a roughness LOD using prefiltered importance sampling GGX
+     *
+     * @param dst               the destination cubemap
+     * @param levels            a list of prefiltered lods of the source environment
+     * @param linearRoughness   roughness
+     * @param maxNumSamples     number of samples for importance sampling
+     * @param updater           a callback for the caller to track progress
+     */
+    static void roughnessFilter(
+            utils::JobSystem& js, Cubemap& dst, const utils::Slice<Cubemap>& levels,
+            float linearRoughness, size_t maxNumSamples, math::float3 mirror, bool prefilter,
+            Progress updater = nullptr, void* userdata = nullptr);
+
+    static void roughnessFilter(
+            utils::JobSystem& js, Cubemap& dst, const std::vector<Cubemap>& levels,
+            float linearRoughness, size_t maxNumSamples, math::float3 mirror, bool prefilter,
+            Progress updater = nullptr, void* userdata = nullptr);
+
+    //! Computes the "DFG" term of the "split-sum" approximation and stores it in a 2D image
+    static void DFG(utils::JobSystem& js, Image& dst, bool multiscatter, bool cloth);
+
+    /**
+     * Computes the diffuse irradiance using prefiltered importance sampling GGX
+     *
+     * @note Usually this is done using spherical harmonics instead.
+     *
+     * @param dst               the destination cubemap
+     * @param levels            a list of prefiltered lods of the source environment
+     * @param maxNumSamples     number of samples for importance sampling
+     * @param updater           a callback for the caller to track progress
+     *
+     * @see CubemapSH
+     */
+    static void diffuseIrradiance(utils::JobSystem& js, Cubemap& dst, const std::vector<Cubemap>& levels,
+            size_t maxNumSamples = 1024, Progress updater = nullptr, void* userdata = nullptr);
+
+    // for debugging. ignore.
+    static void brdf(utils::JobSystem& js, Cubemap& dst, float linearRoughness);
+};
+
+} // namespace ibl
+} // namespace filament
+
+#endif /* IBL_CUBEMAPIBL_H */

ios/include/ibl/CubemapSH.h

@@ -0,0 +1,125 @@
+/*
+ * Copyright (C) 2015 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.
+ */
+
+#ifndef IBL_CUBEMAPSH_H
+#define IBL_CUBEMAPSH_H
+
+
+#include <utils/compiler.h>
+
+#include <math/mat3.h>
+#include <math/vec3.h>
+
+#include <memory>
+#include <vector>
+
+namespace utils {
+class JobSystem;
+} // namespace utils
+
+namespace filament {
+namespace ibl {
+
+class Cubemap;
+
+/**
+ * Computes spherical harmonics
+ */
+class UTILS_PUBLIC CubemapSH {
+public:
+    /**
+     * Spherical Harmonics decomposition of the given cubemap
+     * Optionally calculates irradiance by convolving with truncated cos.
+     */
+    static std::unique_ptr<math::float3[]> computeSH(
+            utils::JobSystem& js, const Cubemap& cm, size_t numBands, bool irradiance);
+
+    /**
+     * Render given spherical harmonics into a cubemap
+     */
+    static void renderSH(utils::JobSystem& js, Cubemap& cm,
+            const std::unique_ptr<math::float3[]>& sh, size_t numBands);
+
+    static void windowSH(std::unique_ptr<math::float3[]>& sh, size_t numBands, float cutoff);
+
+    /**
+     * Compute spherical harmonics of the irradiance of the given cubemap.
+     * The SH basis are pre-scaled for easier rendering by the shader. The resulting coefficients
+     * are not spherical harmonics (as they're scalled by various factors). In particular they
+     * cannot be rendered with renderSH() above. Instead use renderPreScaledSH3Bands() which
+     * is exactly the code ran by our shader.
+     */
+    static void preprocessSHForShader(std::unique_ptr<math::float3[]>& sh);
+
+    /**
+     * Render pre-scaled irrandiance SH
+     */
+    static void renderPreScaledSH3Bands(utils::JobSystem& js, Cubemap& cm,
+            const std::unique_ptr<math::float3[]>& sh);
+
+    static constexpr size_t getShIndex(ssize_t m, size_t l) {
+        return SHindex(m, l);
+    }
+
+private:
+    class float5 {
+        float v[5];
+    public:
+        float5() = default;
+        constexpr float5(float a, float b, float c, float d, float e) : v{ a, b, c, d, e } {}
+        constexpr float operator[](size_t i) const { return v[i]; }
+        float& operator[](size_t i) { return v[i]; }
+    };
+
+    static inline const float5 multiply(const float5 M[5], float5 x) noexcept {
+        return float5{
+                M[0][0] * x[0] + M[1][0] * x[1] + M[2][0] * x[2] + M[3][0] * x[3] + M[4][0] * x[4],
+                M[0][1] * x[0] + M[1][1] * x[1] + M[2][1] * x[2] + M[3][1] * x[3] + M[4][1] * x[4],
+                M[0][2] * x[0] + M[1][2] * x[1] + M[2][2] * x[2] + M[3][2] * x[3] + M[4][2] * x[4],
+                M[0][3] * x[0] + M[1][3] * x[1] + M[2][3] * x[2] + M[3][3] * x[3] + M[4][3] * x[4],
+                M[0][4] * x[0] + M[1][4] * x[1] + M[2][4] * x[2] + M[3][4] * x[3] + M[4][4] * x[4]
+        };
+    };
+
+
+    static inline constexpr size_t SHindex(ssize_t m, size_t l) {
+        return l * (l + 1) + m;
+    }
+
+    static void computeShBasis(float* SHb, size_t numBands, const math::float3& s);
+
+    static float Kml(ssize_t m, size_t l);
+
+    static std::vector<float> Ki(size_t numBands);
+
+    static constexpr float computeTruncatedCosSh(size_t l);
+
+    static float sincWindow(size_t l, float w);
+
+    static math::float3 rotateShericalHarmonicBand1(math::float3 band1, math::mat3f const& M);
+
+    static float5 rotateShericalHarmonicBand2(float5 const& band2, math::mat3f const& M);
+
+        // debugging only...
+    static float Legendre(ssize_t l, ssize_t m, float x);
+    static float TSH(int l, int m, const math::float3& d);
+    static void printShBase(std::ostream& out, int l, int m);
+};
+
+} // namespace ibl
+} // namespace filament
+
+#endif /* IBL_CUBEMAPSH_H */

ios/include/ibl/CubemapUtils.h

@@ -0,0 +1,124 @@
+/*
+ * Copyright (C) 2015 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.
+ */
+
+#ifndef IBL_CUBEMAP_UTILS_H
+#define IBL_CUBEMAP_UTILS_H
+
+#include <ibl/Cubemap.h>
+#include <ibl/Image.h>
+
+#include <utils/compiler.h>
+
+#include <functional>
+
+namespace utils {
+class JobSystem;
+} // namespace utils
+
+namespace filament {
+namespace ibl {
+
+class CubemapIBL;
+
+/**
+ * Create and convert Cubemap formats
+ */
+class UTILS_PUBLIC CubemapUtils {
+public:
+    //! Creates a cubemap object and its backing Image
+    static Cubemap create(Image& image, size_t dim, bool horizontal = true);
+
+    struct EmptyState {
+    };
+
+    template<typename STATE>
+    using ScanlineProc = std::function<
+            void(STATE& state, size_t y, Cubemap::Face f, Cubemap::Texel* data, size_t width)>;
+
+    template<typename STATE>
+    using ReduceProc = std::function<void(STATE& state)>;
+
+    //! process the cubemap using multithreading
+    template<typename STATE>
+    static void process(Cubemap& cm,
+            utils::JobSystem& js,
+            ScanlineProc<STATE> proc,
+            ReduceProc<STATE> reduce = [](STATE&) {},
+            const STATE& prototype = STATE());
+
+    //! process the cubemap
+    template<typename STATE>
+    static void processSingleThreaded(Cubemap& cm,
+            utils::JobSystem& js,
+            ScanlineProc<STATE> proc,
+            ReduceProc<STATE> reduce = [](STATE&) {},
+            const STATE& prototype = STATE());
+
+    //! clamps image to acceptable range
+    static void clamp(Image& src);
+
+    static void highlight(Image& src);
+
+    //! Downsamples a cubemap by helf in x and y using a box filter
+    static void downsampleCubemapLevelBoxFilter(utils::JobSystem& js, Cubemap& dst, const Cubemap& src);
+
+    //! Return the name of a face (suitable for a file name)
+    static const char* getFaceName(Cubemap::Face face);
+
+    //! computes the solid angle of a pixel of a face of a cubemap
+    static float solidAngle(size_t dim, size_t u, size_t v);
+
+    //! Sets a Cubemap faces from a cross image
+    static void setAllFacesFromCross(Cubemap& cm, const Image& image);
+
+private:
+
+    //move these into cmgen?
+    static void setFaceFromCross(Cubemap& cm, Cubemap::Face face, const Image& image);
+    static Image createCubemapImage(size_t dim, bool horizontal = true);
+
+#ifndef FILAMENT_IBL_LITE
+
+public:
+
+    //! Converts horizontal or vertical cross Image to a Cubemap
+    static void crossToCubemap(utils::JobSystem& js, Cubemap& dst, const Image& src);
+
+    //! Converts equirectangular Image to a Cubemap
+    static void equirectangularToCubemap(utils::JobSystem& js, Cubemap& dst, const Image& src);
+
+    //! Converts a Cubemap to an equirectangular Image
+    static void cubemapToEquirectangular(utils::JobSystem& js, Image& dst, const Cubemap& src);
+
+    //! Converts a Cubemap to an octahedron
+    static void cubemapToOctahedron(utils::JobSystem& js, Image& dst, const Cubemap& src);
+
+    //! mirror the cubemap in the horizontal direction
+    static void mirrorCubemap(utils::JobSystem& js, Cubemap& dst, const Cubemap& src);
+
+    //! generates a UV grid in the cubemap -- useful for debugging.
+    static void generateUVGrid(utils::JobSystem& js, Cubemap& cml, size_t gridFrequencyX, size_t gridFrequencyY);
+
+#endif
+
+    friend class CubemapIBL;
+};
+
+
+} // namespace ibl
+} // namespace filament
+
+#endif /* IBL_CUBEMAP_UTILS_H */

ios/include/ibl/Image.h

@@ -0,0 +1,77 @@
+/*
+ * Copyright (C) 2015 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.
+ */
+
+#ifndef IBL_IMAGE_H
+#define IBL_IMAGE_H
+
+#include <math/scalar.h>
+#include <math/vec3.h>
+#include <math/vec4.h>
+
+#include <utils/compiler.h>
+
+#include <memory>
+
+namespace filament {
+namespace ibl {
+
+class UTILS_PUBLIC Image {
+public:
+    Image();
+    Image(size_t w, size_t h, size_t stride = 0);
+
+    void reset();
+
+    void set(Image const& image);
+
+    void subset(Image const& image, size_t x, size_t y, size_t w, size_t h);
+
+    bool isValid() const { return mData != nullptr; }
+
+    size_t getWidth() const { return mWidth; }
+
+    size_t getStride() const { return mBpr / getBytesPerPixel(); }
+
+    size_t getHeight() const { return mHeight; }
+
+    size_t getBytesPerRow() const { return mBpr; }
+
+    size_t getBytesPerPixel() const { return sizeof(math::float3); }
+
+    void* getData() const { return mData; }
+
+    size_t getSize() const { return mBpr * mHeight; }
+
+    void* getPixelRef(size_t x, size_t y) const;
+
+    std::unique_ptr<uint8_t[]> detach() { return std::move(mOwnedData); }
+
+private:
+    size_t mBpr = 0;
+    size_t mWidth = 0;
+    size_t mHeight = 0;
+    std::unique_ptr<uint8_t[]> mOwnedData;
+    void* mData = nullptr;
+};
+
+inline void* Image::getPixelRef(size_t x, size_t y) const {
+    return static_cast<uint8_t*>(mData) + y * getBytesPerRow() + x * getBytesPerPixel();
+}
+
+} // namespace ibl
+} // namespace filament
+
+#endif /* IBL_IMAGE_H */

ios/include/ibl/utilities.h

@@ -0,0 +1,57 @@
+/*
+ * Copyright (C) 2015 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.
+ */
+
+#ifndef IBL_UTILITIES_H
+#define IBL_UTILITIES_H
+
+#include <math.h>
+
+#include <math/vec2.h>
+#include <math/vec3.h>
+
+namespace filament {
+namespace ibl {
+
+template<typename T>
+static inline constexpr T sq(T x) {
+    return x * x;
+}
+
+template<typename T>
+static inline constexpr T log4(T x) {
+    // log2(x)/log2(4)
+    // log2(x)/2
+    return std::log2(x) * T(0.5);
+}
+
+inline bool isPOT(size_t x) {
+    return !(x & (x - 1));
+}
+
+inline filament::math::float2 hammersley(uint32_t i, float iN) {
+    constexpr float tof = 0.5f / 0x80000000U;
+    uint32_t bits = i;
+    bits = (bits << 16u) | (bits >> 16u);
+    bits = ((bits & 0x55555555u) << 1u) | ((bits & 0xAAAAAAAAu) >> 1u);
+    bits = ((bits & 0x33333333u) << 2u) | ((bits & 0xCCCCCCCCu) >> 2u);
+    bits = ((bits & 0x0F0F0F0Fu) << 4u) | ((bits & 0xF0F0F0F0u) >> 4u);
+    bits = ((bits & 0x00FF00FFu) << 8u) | ((bits & 0xFF00FF00u) >> 8u);
+    return { i * iN, bits * tof };
+}
+
+} // namespace ibl
+} // namespace filament
+#endif /* IBL_UTILITIES_H */