upgrade to Filament 1.21.0

ios/include/viewer/AutomationEngine.h

@@ -0,0 +1,264 @@
+/*
+ * Copyright (C) 2020 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 VIEWER_AUTOMATION_ENGINE_H
+#define VIEWER_AUTOMATION_ENGINE_H
+
+#include <viewer/AutomationSpec.h>
+
+namespace filament {
+
+class ColorGrading;
+class Engine;
+class LightManager;
+class MaterialInstance;
+class Renderer;
+class View;
+
+namespace viewer {
+
+/**
+ * The AutomationEngine makes it easy to push a bag of settings values to Filament.
+ * It can also be used to iterate through settings permutations for testing purposes.
+ *
+ * When creating an automation engine for testing purposes, clients give it an immutable reference
+ * to an AutomationSpec. It is always in one of two states: running or idle. The running state can
+ * be entered immediately (startRunning) or by requesting batch mode (startBatchMode).
+ *
+ * When executing a test, clients should call tick() after each frame is rendered, which gives
+ * automation an opportunity to push settings to Filament, increment the current test index (if
+ * enough time has elapsed), and request an asychronous screenshot.
+ *
+ * The time to sleep between tests is configurable and can be set to zero. Automation also waits a
+ * specified minimum number of frames between tests.
+ *
+ * Batch mode is meant for non-interactive applications. In batch mode, automation defers applying
+ * the first test case until the client unblocks it via signalBatchMode(). This is useful when
+ * waiting for a large model file to become fully loaded. Batch mode also offers a query
+ * (shouldClose) that is triggered after the last test has been invoked.
+ */
+class UTILS_PUBLIC AutomationEngine {
+public:
+    /**
+     * Allows users to toggle screenshots, change the sleep duration between tests, etc.
+     */
+    struct Options {
+        /**
+         * Minimum time that automation waits between applying a settings object and advancing
+         * to the next test case. Specified in seconds.
+         */
+        float sleepDuration = 0.2;
+
+        /**
+         * Similar to sleepDuration, but expressed as a frame count. Both the minimum sleep time
+         * and the minimum frame count must be elapsed before automation advances to the next test.
+         */
+        int minFrameCount = 2;
+
+        /**
+         * If true, test progress is dumped to the utils Log (info priority).
+         */
+        bool verbose = true;
+
+        /**
+         * If true, the tick function writes out a screenshot before advancing to the next test.
+         */
+        bool exportScreenshots = false;
+
+        /**
+         * If true, the tick function writes out a settings JSON file before advancing.
+         */
+        bool exportSettings = false;
+    };
+
+    /**
+     * Collection of Filament objects that can be modified by the automation engine.
+     */
+    struct ViewerContent {
+        View* view;
+        Renderer* renderer;
+        MaterialInstance* const* materials;
+        size_t materialCount;
+        LightManager* lightManager;
+        Scene* scene;
+        IndirectLight* indirectLight;
+        utils::Entity sunlight;
+        utils::Entity* assetLights;
+        size_t assetLightCount;
+    };
+
+    /**
+     * Creates an automation engine and places it in an idle state.
+     *
+     * @param spec     Specifies a set of settings permutations (owned by the client).
+     * @param settings Client-owned settings object. This not only supplies the initial
+     *                 state, it also receives changes during tick(). This is useful when
+     *                 building automation into an application that has a settings UI.
+     *
+     * @see setOptions
+     * @see startRunning
+     */
+    AutomationEngine(const AutomationSpec* spec, Settings* settings) :
+            mSpec(spec), mSettings(settings) {}
+
+    /**
+     * Shortcut constructor that creates an automation engine from a JSON string.
+     *
+     * This constructor can be used if the user does not need to monitor how the settings
+     * change over time and does not need ownership over the AutomationSpec.
+     *
+     * An example of a JSON spec can be found by searching the repo for DEFAULT_AUTOMATION.
+     * This is documented using a JSON schema (look for viewer/schemas/automation.json).
+     *
+     * @param jsonSpec Valid JSON string that conforms to the automation schema.
+     * @param size     Number of characters in the JSON string.
+     * @return         Automation engine or null if unable to read the JSON.
+     */
+    static AutomationEngine* createFromJSON(const char* jsonSpec, size_t size);
+
+    /**
+     * Creates an automation engine for the sole purpose of pushing settings, or for executing
+     * the default test sequence.
+     *
+     * To see how the default test sequence is generated, search for DEFAULT_AUTOMATION.
+     */
+    static AutomationEngine* createDefault();
+
+    /**
+     * Activates the automation test. During the subsequent call to tick(), the first test is
+     * applied and automation enters the running state.
+     */
+    void startRunning();
+
+    /**
+     * Activates the automation test, but enters a paused state until the user calls
+     * signalBatchMode().
+     */
+    void startBatchMode();
+
+    /**
+     * Notifies the automation engine that time has passed, a new frame has been rendered.
+     *
+     * This is when settings get applied, screenshots are (optionally) exported, and the internal
+     * test counter is potentially incremented.
+     *
+     * @param content       Contains the Filament View, Materials, and Renderer that get modified.
+     * @param deltaTime     The amount of time that has passed since the previous tick in seconds.
+     */
+    void tick(const ViewerContent& content, float deltaTime);
+
+    /**
+     * Mutates a set of client-owned Filament objects according to a JSON string.
+     *
+     * This method is an alternative to tick(). It allows clients to use the automation engine as a
+     * remote control, as opposed to iterating through a predetermined test sequence.
+     *
+     * This updates the stashed Settings object, then pushes those settings to the given
+     * Filament objects. Clients can optionally call getColorGrading() after calling this method.
+     *
+     * @param json       Contains the JSON string with a set of changes that need to be pushed.
+     * @param jsonLength Number of characters in the json string.
+     * @param content    Contains a set of Filament objects that you want to mutate.
+     */
+    void applySettings(const char* json, size_t jsonLength, const ViewerContent& content);
+
+    /**
+     * Gets a color grading object that corresponds to the latest settings.
+     *
+     * This method either returns a cached instance, or it destroys the cached instance and creates
+     * a new one.
+     */
+    ColorGrading* getColorGrading(Engine* engine);
+
+    /**
+     * Gets the current viewer options.
+     *
+     * NOTE: Focal length here might be different from the user-specified value, due to DoF options.
+     */
+    ViewerOptions getViewerOptions() const;
+
+    /**
+     * Signals that batch mode can begin. Call this after all meshes and textures finish loading.
+     */
+    void signalBatchMode() { mBatchModeAllowed = true; }
+
+    /**
+     * Cancels an in-progress automation session.
+     */
+    void stopRunning() { mIsRunning = false; }
+
+    /**
+     * Signals that the application is closing, so all pending screenshots should be cancelled.
+     */
+    void terminate();
+
+    /**
+     * Configures the automation engine for users who wish to set up a custom sleep time
+     * between tests, etc.
+     */
+    void setOptions(Options options) { mOptions = options; }
+
+    /**
+     * Returns true if automation is in batch mode and all tests have finished.
+     */
+    bool shouldClose() const { return mShouldClose; }
+
+    /**
+     * Convenience function that writes out a JSON file to disk containing all settings.
+     *
+     * @param Settings State vector to serialize.
+     * @param filename Desired JSON filename.
+     */
+    static void exportSettings(const Settings& settings, const char* filename);
+
+    Options getOptions() const { return mOptions; }
+    bool isRunning() const { return mIsRunning; }
+    size_t currentTest() const { return mCurrentTest; }
+    size_t testCount() const { return mSpec->size(); }
+    bool isBatchModeEnabled() const { return mBatchModeEnabled; }
+    const char* getStatusMessage() const;
+    ~AutomationEngine();
+
+private:
+    AutomationSpec const * const mSpec;
+    Settings * const mSettings;
+    Options mOptions;
+
+    Engine* mColorGradingEngine = nullptr;
+    ColorGrading* mColorGrading = nullptr;
+    ColorGradingSettings mColorGradingSettings = {};
+
+    size_t mCurrentTest;
+    float mElapsedTime;
+    int mElapsedFrames;
+    bool mIsRunning = false;
+    bool mBatchModeEnabled = false;
+    bool mRequestStart = false;
+    bool mShouldClose = false;
+    bool mBatchModeAllowed = false;
+    bool mTerminated = false;
+    bool mOwnsSettings = false;
+
+public:
+    // For internal use from a screenshot callback.
+    void requestClose() { mShouldClose = true; }
+    bool isTerminated() const { return mTerminated; }
+};
+
+} // namespace viewer
+} // namespace filament
+
+#endif // VIEWER_AUTOMATION_ENGINE_H

ios/include/viewer/AutomationSpec.h

@@ -0,0 +1,86 @@
+/*
+ * Copyright (C) 2020 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 VIEWER_AUTOMATION_SPEC_H
+#define VIEWER_AUTOMATION_SPEC_H
+
+#include <viewer/Settings.h>
+
+#include <utils/compiler.h>
+
+namespace filament {
+namespace viewer {
+
+/**
+ * Immutable list of Settings objects generated from a JSON spec.
+ *
+ * Each top-level item in the JSON spec is an object with "name", "base" and "permute".
+ * The "base" object specifies a single set of changes to apply to default settings.
+ * The optional "permute" object specifies a cross product of changes to apply to the base.
+ *
+ * The following example generates a total of 5 test cases.
+ * [{
+ *    "name": "simple",
+ *    "base": {
+ *      "view.dof.cocScale": 1.0,
+ *      "view.bloom.strength": 0.5
+ *   },
+ *   "permute": {
+ *     "view.bloom.enabled": [false, true],
+ *     "view.dof.enabled": [false, true]
+ *   }
+ * },
+ * {
+ *   "name": "ppoff",
+ *   "base": {
+ *     "view.postProcessingEnabled": false
+ *   }
+ * }]
+ */
+class UTILS_PUBLIC AutomationSpec {
+public:
+
+    // Parses a JSON spec, then generates a list of Settings objects.
+    // Returns null on failure (see utils log for warnings and errors).
+    // Clients should release memory using "delete".
+    static AutomationSpec* generate(const char* jsonSpec, size_t size);
+
+    // Generates a list of Settings objects using an embedded JSON spec.
+    static AutomationSpec* generateDefaultTestCases();
+
+    // Returns the number of generated Settings objects.
+    size_t size() const;
+
+    // Gets a generated Settings object and copies it out.
+    // Returns false if the given index is out of bounds.
+    bool get(size_t index, Settings* out) const;
+
+    // Returns the name of the JSON group for a given Settings object.
+    char const* getName(size_t index) const;
+
+    // Frees all Settings objects and name strings.
+    ~AutomationSpec();
+
+private:
+    struct Impl;
+    AutomationSpec(Impl*);
+    Impl* mImpl;
+};
+
+} // namespace viewer
+} // namespace filament
+
+#endif // VIEWER_AUTOMATION_SPEC_H

ios/include/viewer/RemoteServer.h

@@ -0,0 +1,102 @@
+/*
+ * Copyright (C) 2021 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 VIEWER_REMOTE_SERVER_H
+#define VIEWER_REMOTE_SERVER_H
+
+#include <viewer/Settings.h>
+
+#include <utils/compiler.h>
+
+#include <stddef.h>
+#include <mutex>
+
+class CivetServer;
+
+namespace filament {
+namespace viewer {
+
+class MessageSender;
+class MessageReceiver;
+
+/**
+ * Encapsulates a message sent from the web client.
+ *
+ * All instances of ReceivedMessage and their data / strings are owned by RemoteServer.
+ * These can be freed via RemoteServer::releaseReceivedMessage().
+ */
+struct ReceivedMessage {
+    char* label;
+    char* buffer;
+    size_t bufferByteCount;
+    size_t messageUid;
+};
+
+/**
+ * Manages a tiny WebSocket server that can receive model data and viewer settings.
+ *
+ * Client apps can call peekReceivedMessage to check for new data, or acquireReceivedMessage
+ * to pop it off the small internal queue. When they are done examining the message contents
+ * they should call releaseReceivedMessage.
+ */
+class UTILS_PUBLIC RemoteServer {
+public:
+    RemoteServer(int port = 8082);
+    ~RemoteServer();
+    bool isValid() const { return mMessageSender; }
+
+    /**
+     * Checks if a download is currently in progress and returns its label.
+     * Returns null if nothing is being downloaded.
+     */
+    char const* peekIncomingLabel() const;
+
+    /**
+     * Pops a message off the incoming queue or returns null if there are no unread messages.
+     *
+     * After examining its contents, users should free the message with releaseReceivedMessage.
+     */
+    ReceivedMessage const* acquireReceivedMessage();
+
+    /**
+     * Frees the memory that holds the contents of a received message.
+     */
+    void releaseReceivedMessage(ReceivedMessage const* message);
+
+    void sendMessage(const Settings& settings);
+    void sendMessage(const char* label, const char* buffer, size_t bufsize);
+
+    // For internal use (makes JNI simpler)
+    ReceivedMessage const* peekReceivedMessage() const;
+
+private:
+    void enqueueReceivedMessage(ReceivedMessage* message);
+    void setIncomingMessage(ReceivedMessage* message);
+    MessageSender* mMessageSender = nullptr;
+    MessageReceiver* mMessageReceiver = nullptr;
+    size_t mNextMessageUid = 0;
+    static const size_t kMessageCapacity = 4;
+    ReceivedMessage* mReceivedMessages[kMessageCapacity] = {};
+    ReceivedMessage* mIncomingMessage = nullptr;
+    JsonSerializer mSerializer;
+    mutable std::mutex mReceivedMessagesMutex;
+    friend class MessageReceiver;
+};
+
+} // namespace viewer
+} // namespace filament
+
+#endif // VIEWER_REMOTE_SERVER_H

ios/include/viewer/Settings.h

@@ -0,0 +1,226 @@
+/*
+ * Copyright (C) 2020 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 VIEWER_SETTINGS_H
+#define VIEWER_SETTINGS_H
+
+#include <filament/ColorGrading.h>
+#include <filament/IndirectLight.h>
+#include <filament/LightManager.h>
+#include <filament/MaterialInstance.h>
+#include <filament/Scene.h>
+#include <filament/View.h>
+
+#include <utils/compiler.h>
+
+#include <math/vec3.h>
+#include <math/vec4.h>
+
+#include <stddef.h>
+#include <stdint.h>
+
+#include <string>
+
+namespace filament {
+
+class Skybox;
+class Renderer;
+
+namespace viewer {
+
+struct ColorGradingSettings;
+struct DynamicLightingSettings;
+struct MaterialSettings;
+struct Settings;
+struct ViewSettings;
+struct LightSettings;
+struct ViewerOptions;
+
+enum class ToneMapping : uint8_t {
+    LINEAR        = 0,
+    ACES_LEGACY   = 1,
+    ACES          = 2,
+    FILMIC        = 3,
+    GENERIC       = 4,
+    DISPLAY_RANGE = 5,
+};
+
+using AmbientOcclusionOptions = filament::View::AmbientOcclusionOptions;
+using ScreenSpaceReflectionsOptions = filament::View::ScreenSpaceReflectionsOptions;
+using AntiAliasing = filament::View::AntiAliasing;
+using BloomOptions = filament::View::BloomOptions;
+using DepthOfFieldOptions = filament::View::DepthOfFieldOptions;
+using Dithering = filament::View::Dithering;
+using FogOptions = filament::View::FogOptions;
+using RenderQuality = filament::View::RenderQuality;
+using ShadowType = filament::View::ShadowType;
+using DynamicResolutionOptions = filament::View::DynamicResolutionOptions;
+using MultiSampleAntiAliasingOptions = filament::View::MultiSampleAntiAliasingOptions;
+using TemporalAntiAliasingOptions = filament::View::TemporalAntiAliasingOptions;
+using VignetteOptions = filament::View::VignetteOptions;
+using VsmShadowOptions = filament::View::VsmShadowOptions;
+using LightManager = filament::LightManager;
+
+// These functions push all editable property values to their respective Filament objects.
+void applySettings(const ViewSettings& settings, View* dest);
+void applySettings(const MaterialSettings& settings, MaterialInstance* dest);
+void applySettings(const LightSettings& settings, IndirectLight* ibl, utils::Entity sunlight,
+        utils::Entity* sceneLights, size_t sceneLightCount, LightManager* lm, Scene* scene, View* view);
+void applySettings(const ViewerOptions& settings, Camera* camera, Skybox* skybox,
+        Renderer* renderer);
+
+// Creates a new ColorGrading object based on the given settings.
+UTILS_PUBLIC
+ColorGrading* createColorGrading(const ColorGradingSettings& settings, Engine* engine);
+
+class UTILS_PUBLIC JsonSerializer {
+public:
+    JsonSerializer();
+    ~JsonSerializer();
+
+    // Writes a human-readable JSON string into an internal buffer and returns the result.
+    const std::string& writeJson(const Settings& in);
+
+    // Reads the given JSON blob and updates the corresponding fields in the given Settings object.
+    // - The given JSON blob need not specify all settings.
+    // - Returns true if successful.
+    // - This function writes warnings and error messages into the utils log.
+    bool readJson(const char* jsonChunk, size_t size, Settings* out);
+
+private:
+    class Context;
+    Context* context;
+};
+
+struct GenericToneMapperSettings {
+    float contrast = 1.55f;
+    float midGrayIn = 0.18f;
+    float midGrayOut = 0.215f;
+    float hdrMax = 10.0f;
+    bool operator!=(const GenericToneMapperSettings &rhs) const { return !(rhs == *this); }
+    bool operator==(const GenericToneMapperSettings &rhs) const;
+};
+
+struct ColorGradingSettings {
+    bool enabled = true;
+    filament::ColorGrading::QualityLevel quality = filament::ColorGrading::QualityLevel::MEDIUM;
+    ToneMapping toneMapping = ToneMapping::ACES_LEGACY;
+    GenericToneMapperSettings genericToneMapper;
+    bool luminanceScaling = false;
+    bool gamutMapping = false;
+    float exposure = 0.0f;
+    float nightAdaptation = 0.0f;
+    float temperature = 0.0f;
+    float tint = 0.0f;
+    math::float3 outRed{1.0f, 0.0f, 0.0f};
+    math::float3 outGreen{0.0f, 1.0f, 0.0f};
+    math::float3 outBlue{0.0f, 0.0f, 1.0f};
+    math::float4 shadows{1.0f, 1.0f, 1.0f, 0.0f};
+    math::float4 midtones{1.0f, 1.0f, 1.0f, 0.0f};
+    math::float4 highlights{1.0f, 1.0f, 1.0f, 0.0f};
+    math::float4 ranges{0.0f, 0.333f, 0.550f, 1.0f};
+    float contrast = 1.0f;
+    float vibrance = 1.0f;
+    float saturation = 1.0f;
+    math::float3 slope{1.0f};
+    math::float3 offset{0.0f};
+    math::float3 power{1.0f};
+    math::float3 gamma{1.0f};
+    math::float3 midPoint{1.0f};
+    math::float3 scale{1.0f};
+    bool linkedCurves = false;
+    bool operator!=(const ColorGradingSettings &rhs) const { return !(rhs == *this); }
+    bool operator==(const ColorGradingSettings &rhs) const;
+};
+
+struct DynamicLightingSettings {
+    float zLightNear = 5;
+    float zLightFar = 100;
+};
+
+// This defines fields in the same order as the setter methods in filament::View.
+struct ViewSettings {
+    // standalone View settings
+    AntiAliasing antiAliasing = AntiAliasing::FXAA;
+    Dithering dithering = Dithering::TEMPORAL;
+    ShadowType shadowType = ShadowType::PCF;
+    bool postProcessingEnabled = true;
+
+    // View Options (sorted)
+    AmbientOcclusionOptions ssao;
+    ScreenSpaceReflectionsOptions screenSpaceReflections;
+    BloomOptions bloom;
+    DepthOfFieldOptions dof;
+    DynamicResolutionOptions dsr;
+    FogOptions fog;
+    MultiSampleAntiAliasingOptions msaa;
+    RenderQuality renderQuality;
+    TemporalAntiAliasingOptions taa;
+    VignetteOptions vignette;
+    VsmShadowOptions vsmShadowOptions;
+
+    // Custom View Options
+    ColorGradingSettings colorGrading;
+    DynamicLightingSettings dynamicLighting;
+};
+
+template <typename T>
+struct MaterialProperty { std::string name; T value; };
+
+// This struct has a fixed size for simplicity. Each non-empty property name is an override.
+struct MaterialSettings {
+    static constexpr size_t MAX_COUNT = 4;
+    MaterialProperty<float> scalar[MAX_COUNT];
+    MaterialProperty<math::float3> float3[MAX_COUNT];
+    MaterialProperty<math::float4> float4[MAX_COUNT];
+};
+
+struct LightSettings {
+    bool enableShadows = true;
+    bool enableSunlight = true;
+    LightManager::ShadowOptions shadowOptions;
+    SoftShadowOptions softShadowOptions;
+    float sunlightIntensity = 100000.0f;
+    math::float3 sunlightDirection = {0.6, -1.0, -0.8};;
+    math::float3 sunlightColor = filament::Color::toLinear<filament::ACCURATE>({ 0.98, 0.92, 0.89});
+    float iblIntensity = 30000.0f;
+    float iblRotation = 0.0f;
+};
+
+struct ViewerOptions {
+    float cameraAperture = 16.0f;
+    float cameraSpeed = 125.0f;
+    float cameraISO = 100.0f;
+    float groundShadowStrength = 0.75f;
+    bool groundPlaneEnabled = false;
+    bool skyboxEnabled = true;
+    sRGBColor backgroundColor = { 0.0f };
+    float cameraFocalLength = 28.0f;
+    float cameraFocusDistance = 10.0f;
+    bool autoScaleEnabled = true;
+};
+
+struct Settings {
+    ViewSettings view;
+    MaterialSettings material;
+    LightSettings lighting;
+    ViewerOptions viewer;
+};
+
+} // namespace viewer
+} // namespace filament
+
+#endif // VIEWER_SETTINGS_H

ios/include/viewer/SimpleViewer.h

@@ -0,0 +1,265 @@
+/*
+ * Copyright (C) 2020 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 VIEWER_SIMPLEVIEWER_H
+#define VIEWER_SIMPLEVIEWER_H
+
+#include <filament/Box.h>
+#include <filament/DebugRegistry.h>
+#include <filament/Engine.h>
+#include <filament/IndirectLight.h>
+#include <filament/Scene.h>
+#include <filament/View.h>
+
+#include <gltfio/Animator.h>
+#include <gltfio/FilamentAsset.h>
+
+#include <viewer/Settings.h>
+
+#include <utils/Entity.h>
+#include <utils/compiler.h>
+
+#include <math/mat4.h>
+#include <math/vec3.h>
+
+#include <vector>
+
+namespace filagui {
+    class ImGuiHelper;
+}
+
+namespace filament {
+namespace viewer {
+
+/**
+ * \class SimpleViewer SimpleViewer.h viewer/SimpleViewer.h
+ * \brief Manages the state for a simple glTF viewer with imgui controls and a tree view.
+ *
+ * This is a utility that can be used across multiple platforms, including web.
+ *
+ * \note If you don't need ImGui controls, there is no need to use this class, just use AssetLoader
+ * instead.
+ */
+class UTILS_PUBLIC SimpleViewer {
+public:
+    using Animator = gltfio::Animator;
+    using FilamentAsset = gltfio::FilamentAsset;
+    using FilamentInstance =  gltfio::FilamentInstance;
+
+    static constexpr int DEFAULT_SIDEBAR_WIDTH = 350;
+
+    /**
+     * Constructs a SimpleViewer that has a fixed association with the given Filament objects.
+     *
+     * Upon construction, the simple viewer may create some additional Filament objects (such as
+     * light sources) that it owns.
+     */
+    SimpleViewer(filament::Engine* engine, filament::Scene* scene, filament::View* view,
+            int sidebarWidth = DEFAULT_SIDEBAR_WIDTH);
+
+    /**
+     * Destroys the SimpleViewer and any Filament entities that it owns.
+     */
+    ~SimpleViewer();
+
+    /**
+     * Adds the asset's ready-to-render entities into the scene.
+     *
+     * The viewer does not claim ownership over the asset or its entities. Clients should use
+     * AssetLoader and ResourceLoader to load an asset before passing it in.
+     *
+     * @param asset The asset to view.
+     * @param instanceToAnimate Optional instance from which to get the animator.
+     */
+    void populateScene(FilamentAsset* asset, FilamentInstance* instanceToAnimate = nullptr);
+
+    /**
+     * Removes the current asset from the viewer.
+     *
+     * This removes all the asset entities from the Scene, but does not destroy them.
+     */
+    void removeAsset();
+
+    /**
+     * Sets or changes the current scene's IBL to allow the UI manipulate it.
+     */
+    void setIndirectLight(filament::IndirectLight* ibl, filament::math::float3 const* sh3);
+
+    /**
+     * Applies the currently-selected glTF animation to the transformation hierarchy and updates
+     * the bone matrices on all renderables.
+     */
+    void applyAnimation(double currentTime);
+
+    /**
+     * Constructs ImGui controls for the current frame and responds to everything that the user has
+     * changed since the previous frame.
+     *
+     * If desired this can be used in conjunction with the filagui library, which allows clients to
+     * render ImGui controls with Filament.
+     */
+    void updateUserInterface();
+
+    /**
+     * Alternative to updateUserInterface that uses an internal instance of ImGuiHelper.
+     *
+     * This utility method is designed for clients that do not want to manage their own instance of
+     * ImGuiHelper (e.g., JavaScript clients).
+     *
+     * Behind the scenes this simply calls ImGuiHelper->render() and passes updateUserInterface into
+     * its callback. Note that the first call might be slower since it requires the creation of the
+     * internal ImGuiHelper instance.
+     */
+    void renderUserInterface(float timeStepInSeconds, filament::View* guiView, float pixelRatio);
+
+    /**
+     * Event-passing methods, useful only when SimpleViewer manages its own instance of ImGuiHelper.
+     * The key codes used in these methods are just normal ASCII/ANSI codes.
+     * @{
+     */
+    void mouseEvent(float mouseX, float mouseY, bool mouseButton, float mouseWheelY, bool control);
+    void keyDownEvent(int keyCode);
+    void keyUpEvent(int keyCode);
+    void keyPressEvent(int charCode);
+    /** @}*/
+
+    /**
+     * Retrieves the current width of the ImGui "window" which we are using as a sidebar.
+     * Clients can monitor this value to adjust the size of the view.
+     */
+    int getSidebarWidth() const { return mSidebarWidth; }
+
+    /**
+     * Allows clients to inject custom UI.
+     */
+    void setUiCallback(std::function<void()> callback) { mCustomUI = callback; }
+
+    /**
+     * Draws the bounding box of each renderable.
+     * Defaults to false.
+     */
+    void enableWireframe(bool b) { mEnableWireframe = b; }
+
+    /**
+     * Enables a built-in light source (useful for creating shadows).
+     * Defaults to true.
+     */
+    void enableSunlight(bool b) { mSettings.lighting.enableSunlight = b; }
+
+    /**
+     * Enables dithering on the view.
+     * Defaults to true.
+     */
+    void enableDithering(bool b) {
+        mSettings.view.dithering = b ? Dithering::TEMPORAL : Dithering::NONE;
+    }
+
+    /**
+     * Enables FXAA antialiasing in the post-process pipeline.
+     * Defaults to true.
+     */
+    void enableFxaa(bool b) {
+        mSettings.view.antiAliasing = b ? AntiAliasing::FXAA : AntiAliasing::NONE;
+    }
+
+    /**
+     * Enables hardware-based MSAA antialiasing.
+     * Defaults to true.
+     */
+    void enableMsaa(bool b) {
+        mSettings.view.msaa.sampleCount = 4;
+        mSettings.view.msaa.enabled = b;
+    }
+
+    /**
+     * Enables screen-space ambient occlusion in the post-process pipeline.
+     * Defaults to true.
+     */
+    void enableSSAO(bool b) { mSettings.view.ssao.enabled = b; }
+
+    /**
+     * Enables Bloom.
+     * Defaults to true.
+     */
+    void enableBloom(bool bloom) { mSettings.view.bloom.enabled = bloom; }
+
+    /**
+     * Adjusts the intensity of the IBL.
+     * See also filament::IndirectLight::setIntensity().
+     * Defaults to 30000.0.
+     */
+    void setIBLIntensity(float brightness) { mSettings.lighting.iblIntensity = brightness; }
+
+    /**
+     * Updates the transform at the root node according to the autoScaleEnabled setting.
+     */
+    void updateRootTransform();
+
+    /**
+     * Gets a modifiable reference to stashed state.
+     */
+    Settings& getSettings() { return mSettings; }
+
+    void stopAnimation() { mCurrentAnimation = 0; }
+
+    int getCurrentCamera() const { return mCurrentCamera; }
+
+private:
+    void updateIndirectLight();
+
+    // Immutable properties set from the constructor.
+    filament::Engine* const mEngine;
+    filament::Scene* const mScene;
+    filament::View* const mView;
+    const utils::Entity mSunlight;
+
+    // Lazily instantiated fields.
+    filagui::ImGuiHelper* mImGuiHelper = nullptr;
+
+    // Properties that can be changed from the application.
+    FilamentAsset* mAsset = nullptr;
+    Animator* mAnimator = nullptr;
+    filament::IndirectLight* mIndirectLight = nullptr;
+    std::function<void()> mCustomUI;
+
+    // Properties that can be changed from the UI.
+    int mCurrentAnimation = 1; // It is a 1-based index and 0 means not playing animation
+    int mCurrentVariant = 0;
+    bool mResetAnimation = true;
+    bool mEnableWireframe = false;
+    int mVsmMsaaSamplesLog2 = 1;
+    Settings mSettings;
+    int mSidebarWidth;
+    uint32_t mFlags;
+    utils::Entity mCurrentMorphingEntity;
+    std::vector<float> mMorphWeights;
+
+    // 0 is the default "free camera". Additional cameras come from the gltf file (1-based index).
+    int mCurrentCamera = 0;
+
+    // Color grading UI state.
+    float mToneMapPlot[1024];
+    float mRangePlot[1024 * 3];
+    float mCurvePlot[1024 * 3];
+};
+
+UTILS_PUBLIC
+filament::math::mat4f fitIntoUnitCube(const filament::Aabb& bounds, float zoffset);
+
+} // namespace viewer
+} // namespace filament
+
+#endif // VIEWER_SIMPLEVIEWER_H