Debian Codegraph @

libs/iblprefilter/include/filament-iblprefilter/IBLPrefilterContext.h

raw
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