| 1 |
/* |
| 2 |
* Copyright (C) 2021 The Android Open Source Project |
| 3 |
* |
| 4 |
* Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 |
* you may not use this file except in compliance with the License. |
| 6 |
* You may obtain a copy of the License at |
| 7 |
* |
| 8 |
* http://www.apache.org/licenses/LICENSE-2.0 |
| 9 |
* |
| 10 |
* Unless required by applicable law or agreed to in writing, software |
| 11 |
* distributed under the License is distributed on an "AS IS" BASIS, |
| 12 |
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 |
* See the License for the specific language governing permissions and |
| 14 |
* limitations under the License. |
| 15 |
*/ |
| 16 |
|
| 17 |
#ifndef TNT_IBL_PREFILTER_IBLPREFILTER_H |
| 18 |
#define TNT_IBL_PREFILTER_IBLPREFILTER_H |
| 19 |
|
| 20 |
#include <utils/Entity.h> |
| 21 |
|
| 22 |
#include <filament/Texture.h> |
| 23 |
|
| 24 |
namespace filament { |
| 25 |
class Engine; |
| 26 |
class View; |
| 27 |
class Scene; |
| 28 |
class Renderer; |
| 29 |
class Material; |
| 30 |
class MaterialInstance; |
| 31 |
class VertexBuffer; |
| 32 |
class IndexBuffer; |
| 33 |
class Camera; |
| 34 |
class Texture; |
| 35 |
} // namespace filament |
| 36 |
|
| 37 |
/** |
| 38 |
* IBLPrefilterContext creates and initializes GPU state common to all environment map filters |
| 39 |
* supported. Typically, only one instance per filament Engine of this object needs to exist. |
| 40 |
* |
| 41 |
* Usage Example: |
| 42 |
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 43 |
* #include <filament/Engine.h> |
| 44 |
* using namespace filament; |
| 45 |
* |
| 46 |
* Engine* engine = Engine::create(); |
| 47 |
* |
| 48 |
* IBLPrefilterContext context(engine); |
| 49 |
* IBLPrefilterContext::SpecularFilter filter(context); |
| 50 |
* Texture* texture = filter(environment_cubemap); |
| 51 |
* |
| 52 |
* IndirectLight* indirectLight = IndirectLight::Builder() |
| 53 |
* .reflections(texture) |
| 54 |
* .build(engine); |
| 55 |
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 56 |
*/ |
| 57 |
class IBLPrefilterContext { |
| 58 |
public: |
| 59 |
|
| 60 |
/** |
| 61 |
* Creates an IBLPrefilter context. |
| 62 |
* @param engine filament engine to use |
| 63 |
*/ |
| 64 |
IBLPrefilterContext(filament::Engine& engine); |
| 65 |
|
| 66 |
/** |
| 67 |
* Destroys all GPU resources created during initialization. |
| 68 |
*/ |
| 69 |
~IBLPrefilterContext() noexcept; |
| 70 |
|
| 71 |
// not copyable |
| 72 |
IBLPrefilterContext(IBLPrefilterContext const&) = delete; |
| 73 |
IBLPrefilterContext& operator=(IBLPrefilterContext const&) = delete; |
| 74 |
|
| 75 |
// movable |
| 76 |
IBLPrefilterContext(IBLPrefilterContext&& rhs) noexcept; |
| 77 |
IBLPrefilterContext& operator=(IBLPrefilterContext&& rhs); |
| 78 |
|
| 79 |
// ------------------------------------------------------------------------------------------- |
| 80 |
|
| 81 |
/** |
| 82 |
* EquirectangularToCubemap is use to convert an equirectangluar image to a cubemap. |
| 83 |
*/ |
| 84 |
class EquirectangularToCubemap { |
| 85 |
public: |
| 86 |
/** |
| 87 |
* Creates a EquirectangularToCubemap processor. |
| 88 |
* @param context IBLPrefilterContext to use |
| 89 |
*/ |
| 90 |
explicit EquirectangularToCubemap(IBLPrefilterContext& context); |
| 91 |
|
| 92 |
/** |
| 93 |
* Destroys all GPU resources created during initialization. |
| 94 |
*/ |
| 95 |
~EquirectangularToCubemap() noexcept; |
| 96 |
|
| 97 |
EquirectangularToCubemap(EquirectangularToCubemap const&) = delete; |
| 98 |
EquirectangularToCubemap& operator=(EquirectangularToCubemap const&) = delete; |
| 99 |
EquirectangularToCubemap(EquirectangularToCubemap&& rhs) noexcept; |
| 100 |
EquirectangularToCubemap& operator=(EquirectangularToCubemap&& rhs); |
| 101 |
|
| 102 |
/** |
| 103 |
* Converts an equirectangular image to a cubemap. |
| 104 |
* @param equirectangular Texture to convert to a cubemap. |
| 105 |
* - Can't be null. |
| 106 |
* - Must be a 2d texture |
| 107 |
* - Must have equirectangular geometry, that is width == 2*height. |
| 108 |
* - Must be allocated with all mip levels. |
| 109 |
* - Must be SAMPLEABLE |
| 110 |
* @param outCubemap Output cubemap. If null the texture is automatically created |
| 111 |
* with default parameters (size of 256 with 5 levels). |
| 112 |
* - Must be a cubemap |
| 113 |
* - Must have SAMPLEABLE and COLOR_ATTACHMENT usage bits |
| 114 |
* @return returns outCubemap |
| 115 |
*/ |
| 116 |
filament::Texture* operator()( |
| 117 |
filament::Texture const* equirectangular, |
| 118 |
filament::Texture* outCubemap = nullptr); |
| 119 |
|
| 120 |
private: |
| 121 |
IBLPrefilterContext& mContext; |
| 122 |
filament::Material* mEquirectMaterial = nullptr; |
| 123 |
}; |
| 124 |
|
| 125 |
|
| 126 |
/** |
| 127 |
* SpecularFilter is a GPU based implementation of the specular probe pre-integration filter. |
| 128 |
* An instance of SpecularFilter is needed per filter configuration. A filter configuration |
| 129 |
* contains the filter's kernel and sample count. |
| 130 |
*/ |
| 131 |
class SpecularFilter { |
| 132 |
public: |
| 133 |
enum class Kernel : uint8_t { |
| 134 |
D_GGX, // Trowbridge-reitz distribution |
| 135 |
}; |
| 136 |
|
| 137 |
/** |
| 138 |
* Filter configuration. |
| 139 |
*/ |
| 140 |
struct Config { |
| 141 |
uint16_t sampleCount = 1024u; //!< filter sample count (max 2048) |
| 142 |
uint8_t levelCount = 5u; //!< number of roughness levels |
| 143 |
Kernel kernel = Kernel::D_GGX; //!< filter kernel |
| 144 |
}; |
| 145 |
|
| 146 |
/** |
| 147 |
* Filtering options for the current environment. |
| 148 |
*/ |
| 149 |
struct Options { |
| 150 |
float hdrLinear = 1024.0f; //!< no HDR compression up to this value |
| 151 |
float hdrMax = 16384.0f; //!< HDR compression between hdrLinear and hdrMax |
| 152 |
float lodOffset = 1.0f; //!< Good values are 1.0 or 2.0. Higher values help with heavily HDR inputs. |
| 153 |
bool generateMipmap = true; //!< set to false if the environment map already has mipmaps |
| 154 |
}; |
| 155 |
|
| 156 |
/** |
| 157 |
* Creates a SpecularFilter processor. |
| 158 |
* @param context IBLPrefilterContext to use |
| 159 |
* @param config Configuration of the filter |
| 160 |
*/ |
| 161 |
SpecularFilter(IBLPrefilterContext& context, Config config); |
| 162 |
|
| 163 |
/** |
| 164 |
* Creates a filter with the default configuration. |
| 165 |
* @param context IBLPrefilterContext to use |
| 166 |
*/ |
| 167 |
explicit SpecularFilter(IBLPrefilterContext& context); |
| 168 |
|
| 169 |
/** |
| 170 |
* Destroys all GPU resources created during initialization. |
| 171 |
*/ |
| 172 |
~SpecularFilter() noexcept; |
| 173 |
|
| 174 |
SpecularFilter(SpecularFilter const&) = delete; |
| 175 |
SpecularFilter& operator=(SpecularFilter const&) = delete; |
| 176 |
SpecularFilter(SpecularFilter&& rhs) noexcept; |
| 177 |
SpecularFilter& operator=(SpecularFilter&& rhs); |
| 178 |
|
| 179 |
/** |
| 180 |
* Generates a prefiltered cubemap. |
| 181 |
* @param options Options for this environment |
| 182 |
* @param environmentCubemap Environment cubemap (input). Can't be null. |
| 183 |
* This cubemap must be SAMPLEABLE and must have all its |
| 184 |
* levels allocated. If Options.generateMipmap is true, |
| 185 |
* the mipmap levels will be overwritten, otherwise |
| 186 |
* it is assumed that all levels are correctly initialized. |
| 187 |
* @param outReflectionsTexture Output prefiltered texture or, if null, it is |
| 188 |
* automatically created with some default parameters. |
| 189 |
* outReflectionsTexture must be a cubemap, it must have |
| 190 |
* at least COLOR_ATTACHMENT and SAMPLEABLE usages and at |
| 191 |
* least the same number of levels than requested by Config. |
| 192 |
* @return returns outReflectionsTexture |
| 193 |
*/ |
| 194 |
filament::Texture* operator()(Options options, |
| 195 |
filament::Texture const* environmentCubemap, |
| 196 |
filament::Texture* outReflectionsTexture = nullptr); |
| 197 |
|
| 198 |
/** |
| 199 |
* Generates a prefiltered cubemap. |
| 200 |
* @param environmentCubemap Environment cubemap (input). Can't be null. |
| 201 |
* This cubemap must be SAMPLEABLE and must have all its |
| 202 |
* levels allocated. All mipmap levels will be overwritten. |
| 203 |
* @param outReflectionsTexture Output prefiltered texture or, if null, it is |
| 204 |
* automatically created with some default parameters. |
| 205 |
* outReflectionsTexture must be a cubemap, it must have |
| 206 |
* at least COLOR_ATTACHMENT and SAMPLEABLE usages and at |
| 207 |
* least the same number of levels than requested by Config. |
| 208 |
* @return returns outReflectionsTexture |
| 209 |
*/ |
| 210 |
filament::Texture* operator()( |
| 211 |
filament::Texture const* environmentCubemap, |
| 212 |
filament::Texture* outReflectionsTexture = nullptr); |
| 213 |
|
| 214 |
// TODO: option for progressive filtering |
| 215 |
|
| 216 |
// TODO: add a callback for when the processing is done? |
| 217 |
|
| 218 |
private: |
| 219 |
filament::Texture* createReflectionsTexture(); |
| 220 |
IBLPrefilterContext& mContext; |
| 221 |
filament::Material* mKernelMaterial = nullptr; |
| 222 |
filament::Texture* mKernelTexture = nullptr; |
| 223 |
uint32_t mSampleCount = 0u; |
| 224 |
uint8_t mLevelCount = 1u; |
| 225 |
}; |
| 226 |
|
| 227 |
private: |
| 228 |
friend class Filter; |
| 229 |
filament::Engine& mEngine; |
| 230 |
filament::Renderer* mRenderer{}; |
| 231 |
filament::Scene* mScene{}; |
| 232 |
filament::VertexBuffer* mVertexBuffer{}; |
| 233 |
filament::IndexBuffer* mIndexBuffer{}; |
| 234 |
filament::Camera* mCamera{}; |
| 235 |
utils::Entity mFullScreenQuadEntity{}; |
| 236 |
utils::Entity mCameraEntity{}; |
| 237 |
filament::View* mView{}; |
| 238 |
filament::Material* mIntegrationMaterial{}; |
| 239 |
}; |
| 240 |
|
| 241 |
#endif //TNT_IBL_PREFILTER_IBLPREFILTER_H |