maobo/cup_edit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update headers

Browse Source
This commit is contained in:
Nick Fisher
2022-12-05 17:51:44 +08:00
parent 58942ba94d
commit e0f9cfbde6
234 changed files with 62619 additions and 9800 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
ios/include/filament/Camera.h
View File

@@ -98,7 +98,7 @@ namespace filament {
* The *near* plane distance greatly affects the depth-buffer resolution.
*
* Example: Precision at 1m, 10m, 100m and 1Km for various near distances assuming a 32-bit float
* depth-buffer
* depth-buffer:
*
* near (m) | 1 m | 10 m | 100 m | 1 Km
* -----------:|:------:|:-------:|:--------:|:--------:
@@ -107,11 +107,31 @@ namespace filament {
* 0.1 | 3.6e-7 | 7.0e-5 | 0.0072 | 0.43
* 1.0 | 0 | 3.8e-6 | 0.0007 | 0.07
*
*
* As can be seen in the table above, the depth-buffer precision drops rapidly with the
* distance to the camera.
*
* Make sure to pick the highest *near* plane distance possible.
*
* On Vulkan and Metal platforms (or OpenGL platforms supporting either EXT_clip_control or
* ARB_clip_control extensions), the depth-buffer precision is much less dependent on the *near*
* plane value:
*
* near (m) | 1 m | 10 m | 100 m | 1 Km
* -----------:|:------:|:-------:|:--------:|:--------:
* 0.001 | 1.2e-7 | 9.5e-7 | 7.6e-6 | 6.1e-5
* 0.01 | 1.2e-7 | 9.5e-7 | 7.6e-6 | 6.1e-5
* 0.1 | 5.9e-8 | 9.5e-7 | 1.5e-5 | 1.2e-4
* 1.0 | 0 | 9.5e-7 | 7.6e-6 | 1.8e-4
*
*
* Choosing the *far* plane distance
* =================================
*
* The far plane distance is always set internally to infinity for rendering, however it is used for
* culling and shadowing calculations. It is important to keep a reasonable ratio between
* the near and far plane distances. Typically a ratio in the range 1:100 to 1:100000 is
* commanded. Larger values may causes rendering artifacts or trigger assertions in debug builds.
*
*
* Exposure
* ========
@@ -167,14 +187,12 @@ public:
* Precondition: \p far > near for PROJECTION::PERSPECTIVE or
* \p far != near for PROJECTION::ORTHO
*
* @attention these parameters are silently modified to meet the preconditions above.
*
* @see Projection, Frustum
*/
void setProjection(Projection projection,
double left, double right,
double bottom, double top,
double near, double far) noexcept;
double near, double far);
/** Sets the projection matrix from the field-of-view.
*
@@ -187,7 +205,7 @@ public:
* @see Fov.
*/
void setProjection(double fovInDegrees, double aspect, double near, double far,
Fov direction = Fov::VERTICAL) noexcept;
Fov direction = Fov::VERTICAL);
/** Sets the projection matrix from the focal length.
*
@@ -197,7 +215,7 @@ public:
* @param far distance in world units from the camera to the far plane. \p far > \p near.
*/
void setLensProjection(double focalLengthInMillimeters,
double aspect, double near, double far) noexcept;
double aspect, double near, double far);
/** Sets a custom projection matrix.
*
@@ -308,47 +326,39 @@ public:
//! Returns the frustum's near plane
float getNear() const noexcept;
double getNear() const noexcept;
//! Returns the frustum's far plane used for culling
float getCullingFar() const noexcept;
double getCullingFar() const noexcept;
/** Sets the camera's view matrix.
/** Sets the camera's model matrix.
*
* Helper method to set the camera's entity transform component.
* It has the same effect as calling:
*
* ~~~~~~~~~~~{.cpp}
* engine.getTransformManager().setTransform(
* engine.getTransformManager().getInstance(camera->getEntity()), view);
* engine.getTransformManager().getInstance(camera->getEntity()), model);
* ~~~~~~~~~~~
*
* @param view The camera position and orientation provided as a rigid transform matrix.
* @param model The camera position and orientation provided as a rigid transform matrix.
*
* @note The Camera "looks" towards its -z axis
*
* @warning \p view must be a rigid transform
* @warning \p model must be a rigid transform
*/
void setModelMatrix(const math::mat4& view) noexcept;
void setModelMatrix(const math::mat4f& view) noexcept; //!< \overload
void setModelMatrix(const math::mat4& model) noexcept;
void setModelMatrix(const math::mat4f& model) noexcept; //!< @overload
/** Sets the camera's view matrix
/** Sets the camera's model matrix
*
* @param eye The position of the camera in world space.
* @param center The point in world space the camera is looking at.
* @param up A unit vector denoting the camera's "up" direction.
*/
void lookAt(const math::float3& eye,
const math::float3& center,
const math::float3& up) noexcept;
/** Sets the camera's view matrix, assuming up is along the y axis
*
* @param eye The position of the camera in world space.
* @param center The point in world space the camera is looking at.
*/
void lookAt(const math::float3& eye,
const math::float3& center) noexcept;
void lookAt(math::double3 const& eye,
math::double3 const& center,
math::double3 const& up = math::double3{0, 1, 0}) noexcept;
/** Returns the camera's model matrix
*
@@ -369,7 +379,7 @@ public:
math::mat4 getViewMatrix() const noexcept;
//! Returns the camera's position in world space
math::float3 getPosition() const noexcept;
math::double3 getPosition() const noexcept;
//! Returns the camera's normalized left vector
math::float3 getLeftVector() const noexcept;

201
ios/include/filament/Engine.h
View File

@@ -54,6 +54,22 @@ class LightManager;
class RenderableManager;
class TransformManager;
#ifndef FILAMENT_PER_RENDER_PASS_ARENA_SIZE_IN_MB
# define FILAMENT_PER_RENDER_PASS_ARENA_SIZE_IN_MB 3
#endif
#ifndef FILAMENT_PER_FRAME_COMMANDS_SIZE_IN_MB
# define FILAMENT_PER_FRAME_COMMANDS_SIZE_IN_MB 2
#endif
#ifndef FILAMENT_MIN_COMMAND_BUFFERS_SIZE_IN_MB
# define FILAMENT_MIN_COMMAND_BUFFERS_SIZE_IN_MB 1
#endif
#ifndef FILAMENT_COMMAND_BUFFER_SIZE_IN_MB
# define FILAMENT_COMMAND_BUFFER_SIZE_IN_MB (FILAMENT_MIN_COMMAND_BUFFERS_SIZE_IN_MB * 3)
#endif
/**
* Engine is filament's main entry-point.
*
@@ -151,6 +167,103 @@ class UTILS_PUBLIC Engine {
public:
using Platform = backend::Platform;
using Backend = backend::Backend;
using DriverConfig = backend::Platform::DriverConfig;
/**
* Config is used to define the memory footprint used by the engine, such as the
* command buffer size. Config can be used to customize engine requirements based
* on the applications needs.
*
* .perRenderPassArenaSizeMB (default: 3 MiB)
* +--------------------------+
* | |
* | .perFrameCommandsSizeMB |
* | (default 2 MiB) |
* | |
* +--------------------------+
* | (froxel, etc...) |
* +--------------------------+
*
*
* .commandBufferSizeMB (default 3MiB)
* +--------------------------+
* | .minCommandBufferSizeMB |
* +--------------------------+
* | .minCommandBufferSizeMB |
* +--------------------------+
* | .minCommandBufferSizeMB |
* +--------------------------+
* : :
* : :
*
*/
struct Config {
/**
* Size in MiB of the low-level command buffer arena.
*
* Each new command buffer is allocated from here. If this buffer is too small the program
* might terminate or rendering errors might occur.
*
* This is typically set to minCommandBufferSizeMB * 3, so that up to 3 frames can be
* batched-up at once.
*
* This value affects the application's memory usage.
*/
uint32_t commandBufferSizeMB = FILAMENT_COMMAND_BUFFER_SIZE_IN_MB;
/**
* Size in MiB of the per-frame data arena.
*
* This is the main arena used for allocations when preparing a frame.
* e.g.: Froxel data and high-level commands are allocated from this arena.
*
* If this size is too small, the program will abort on debug builds and have undefined
* behavior otherwise.
*
* This value affects the application's memory usage.
*/
uint32_t perRenderPassArenaSizeMB = FILAMENT_PER_RENDER_PASS_ARENA_SIZE_IN_MB;
/**
* Size in MiB of the backend's handle arena.
*
* Backends will fallback to slower heap-based allocations when running out of space and
* log this condition.
*
* If 0, then the default value for the given platform is used
*
* This value affects the application's memory usage.
*/
uint32_t driverHandleArenaSizeMB = 0;
/**
* Minimum size in MiB of a low-level command buffer.
*
* This is how much space is guaranteed to be available for low-level commands when a new
* buffer is allocated. If this is too small, the engine might have to stall to wait for
* more space to become available, this situation is logged.
*
* This value does not affect the application's memory usage.
*/
uint32_t minCommandBufferSizeMB = FILAMENT_MIN_COMMAND_BUFFERS_SIZE_IN_MB;
/**
* Size in MiB of the per-frame high level command buffer.
*
* This buffer is related to the number of draw calls achievable within a frame, if it is
* too small, the program will abort on debug builds and have undefined behavior otherwise.
*
* It is allocated from the 'per-render-pass arena' above. Make sure that at least 1 MiB is
* left in the per-render-pass arena when deciding the size of this buffer.
*
* This value does not affect the application's memory usage.
*/
uint32_t perFrameCommandsSizeMB = FILAMENT_PER_FRAME_COMMANDS_SIZE_IN_MB;
};
/**
* Creates an instance of Engine
@@ -175,6 +288,8 @@ public:
* Setting this parameter will force filament to use the OpenGL
* implementation (instead of Vulkan for instance).
*
* @param config A pointer to optional parameters to specify memory size
* configuration options. If nullptr, then defaults used.
*
* @return A pointer to the newly created Engine, or nullptr if the Engine couldn't be created.
*
@@ -189,7 +304,8 @@ public:
* This method is thread-safe.
*/
static Engine* create(Backend backend = Backend::DEFAULT,
Platform* platform = nullptr, void* sharedGLContext = nullptr);
Platform* platform = nullptr, void* sharedGLContext = nullptr,
const Config* config = nullptr);
#if UTILS_HAS_THREADING
/**
@@ -231,10 +347,14 @@ public:
* when creating filament's internal context.
* Setting this parameter will force filament to use the OpenGL
* implementation (instead of Vulkan for instance).
*
* @param config A pointer to optional parameters to specify memory size
* configuration options
*/
static void createAsync(CreateCallback callback, void* user,
Backend backend = Backend::DEFAULT,
Platform* platform = nullptr, void* sharedGLContext = nullptr);
Platform* platform = nullptr, void* sharedGLContext = nullptr,
const Config* config = nullptr);
/**
* Retrieve an Engine* from createAsync(). This must be called from the same thread than
@@ -306,6 +426,45 @@ public:
*/
static void destroy(Engine* engine);
using FeatureLevel = backend::FeatureLevel;
/**
* Query the feature level supported by the selected backend.
*
* A specific feature level needs to be set before the corresponding features can be used.
*
* @return FeatureLevel supported the selected backend.
* @see setActiveFeatureLevel
*/
FeatureLevel getSupportedFeatureLevel() const noexcept;
/**
* Activate all features of a given feature level. By default FeatureLevel::FEATURE_LEVEL_1 is
* active. The selected feature level must not be higher than the value returned by
* getActiveFeatureLevel() and it's not possible lower the active feature level.
*
* @param featureLevel the feature level to activate. If featureLevel is lower than
* getActiveFeatureLevel(), the current (higher) feature level is kept.
* If featureLevel is higher than getSupportedFeatureLevel(), an exception
* is thrown, or the program is terminated if exceptions are disabled.
*
* @return the active feature level.
*
* @see getSupportedFeatureLevel
* @see getActiveFeatureLevel
*/
FeatureLevel setActiveFeatureLevel(FeatureLevel featureLevel);
/**
* Returns the currently active feature level.
* @return currently active feature level
* @see getSupportedFeatureLevel
* @see setActiveFeatureLevel
*/
FeatureLevel getActiveFeatureLevel() const noexcept;
/**
* @return EntityManager used by filament
*/
@@ -335,6 +494,28 @@ public:
*/
void enableAccurateTranslations() noexcept;
/**
* Enables or disables automatic instancing of render primitives. Instancing of render
* primitives can greatly reduce CPU overhead but requires the instanced primitives to be
* identical (i.e. use the same geometry) and use the same MaterialInstance. If it is known
* that the scene doesn't contain any identical primitives, automatic instancing can have some
* overhead and it is then best to disable it.
*
* Disabled by default.
*
* @param enable true to enable, false to disable automatic instancing.
*
* @see RenderableManager
* @see MaterialInstance
*/
void setAutomaticInstancingEnabled(bool enable) noexcept;
/**
* @return true if automatic instancing is enabled, false otherwise.
* @see setAutomaticInstancingEnabled
*/
bool isAutomaticInstancingEnabled() const noexcept;
/**
* Creates a SwapChain from the given Operating System's native window handle.
*
@@ -544,6 +725,22 @@ public:
*/
utils::JobSystem& getJobSystem() noexcept;
#if defined(__EMSCRIPTEN__)
/**
* WebGL only: Tells the driver to reset any internal state tracking if necessary.
*
* This is only useful when integrating an external renderer into Filament on platforms
* like WebGL, where share contexts do not exist. Filament keeps track of the GL
* state it has set (like which texture is bound), and does not re-set that state if
* it does not think it needs to. However, if an external renderer has set different
* state in the mean time, Filament will use that new state unknowingly.
*
* If you are in this situation, call this function - ideally only once per frame,
* immediately after calling Engine::execute().
*/
void resetBackendState() noexcept;
#endif
DebugRegistry& getDebugRegistry() noexcept;
protected:

8
ios/include/filament/Frustum.h
View File

@@ -115,7 +115,13 @@ private:
math::float4 mPlanes[6];
};
} // namespace filament
#if !defined(NDEBUG)
namespace utils::io {
class ostream;
} // namespace utils::io
utils::io::ostream& operator<<(utils::io::ostream& out, filament::Frustum const& frustum);
#endif
#endif // TNT_FILAMENT_FRUSTUM_H

33
ios/include/filament/LightManager.h
View File

@@ -226,7 +226,7 @@ public:
* @see ShadowCascades::computeLogSplits
* @see ShadowCascades::computePracticalSplits
*/
float cascadeSplitPositions[3] = { 0.25f, 0.50f, 0.75f };
float cascadeSplitPositions[3] = { 0.125f, 0.25f, 0.50f };
/** Constant bias in world units (e.g. meters) by which shadows are moved away from the
* light. 1mm by default.
@@ -266,9 +266,29 @@ public:
* Controls whether the shadow map should be optimized for resolution or stability.
* When set to true, all resolution enhancing features that can affect stability are
* disabling, resulting in significantly lower resolution shadows, albeit stable ones.
*
* Setting this flag to true always disables LiSPSM (see below).
*
* @see lispsm
*/
bool stable = false;
/**
* LiSPSM, or light-space perspective shadow-mapping is a technique allowing to better
* optimize the use of the shadow-map texture. When enabled the effective resolution of
* shadows is greatly improved and yields result similar to using cascades without the
* extra cost. LiSPSM comes with some drawbacks however, in particular it is incompatible
* with blurring because it effectively affects the blur kernel size.
*
* Blurring is only an issue when using ShadowType::VSM with a large blur or with
* ShadowType::PCSS however.
*
* If these blurring artifacts become problematic, this flag can be used to disable LiSPSM.
*
* @see stable
*/
bool lispsm = true;
/**
* Constant bias in depth-resolution units by which shadows are moved away from the
* light. The default value of 0.5 is used to round depth values up.
@@ -328,6 +348,14 @@ public:
*/
uint8_t msaaSamples = 1;
/**
* When elvsm is set to true, "Exponential Layered VSM without Layers" are used. It is
* an improvement to the default EVSM which suffers important light leaks. Enabling
* ELVSM for a single shadowmap doubles the memory usage of all shadow maps.
* ELVSM is mostly useful when large blurs are used.
*/
bool elvsm = false;
/**
* Blur width for the VSM blur. Zero do disable.
* The maximum value is 125.
@@ -418,9 +446,6 @@ public:
* @param enable Enables or disables casting shadows from this Light.
*
* @return This Builder, for chaining calls.
*
* @warning
* - Only a Type.DIRECTIONAL, Type.SUN, Type.SPOT, or Type.FOCUSED_SPOT light can cast shadows
*/
Builder& castShadows(bool enable) noexcept;

4
ios/include/filament/MaterialChunkType.h
View File

@@ -45,11 +45,13 @@ enum UTILS_PUBLIC ChunkType : uint64_t {
MaterialSpirv = charTo64bitNum("MAT_SPIR"),
MaterialMetal = charTo64bitNum("MAT_METL"),
MaterialShaderModels = charTo64bitNum("MAT_SMDL"),
MaterialSamplerBindings = charTo64bitNum("MAT_SAMP"), // no longer used
MaterialSamplerBindings = charTo64bitNum("MAT_SAMP"),
MaterialUniformBindings = charTo64bitNum("MAT_UNIF"),
MaterialProperties = charTo64bitNum("MAT_PROP"),
MaterialName = charTo64bitNum("MAT_NAME"),
MaterialVersion = charTo64bitNum("MAT_VERS"),
MaterialFeatureLevel = charTo64bitNum("MAT_FEAT"),
MaterialShading = charTo64bitNum("MAT_SHAD"),
MaterialBlendingMode = charTo64bitNum("MAT_BLEN"),
MaterialTransparencyMode = charTo64bitNum("MAT_TRMD"),

3
ios/include/filament/MaterialEnums.h
View File

@@ -27,7 +27,7 @@
namespace filament {
// update this when a new version of filament wouldn't work with older materials
static constexpr size_t MATERIAL_VERSION = 25;
static constexpr size_t MATERIAL_VERSION = 28;
/**
* Supported shading models
@@ -160,6 +160,7 @@ static constexpr size_t MAX_CUSTOM_ATTRIBUTES = 8;
enum class MaterialDomain : uint8_t {
SURFACE = 0, //!< shaders applied to renderables
POST_PROCESS = 1, //!< shaders applied to rendered buffers
COMPUTE = 2, //!< compute shader
};
/**

237
ios/include/filament/MaterialInstance.h
View File

@@ -34,12 +34,27 @@ class Material;
class Texture;
class TextureSampler;
class UniformBuffer;
class UniformInterfaceBlock;
class BufferInterfaceBlock;
class UTILS_PUBLIC MaterialInstance : public FilamentAPI {
template<size_t N>
using StringLiteralHelper = const char[N];
struct StringLiteral {
const char* data;
size_t size;
template<size_t N>
StringLiteral(StringLiteralHelper<N> const& s) noexcept // NOLINT(google-explicit-constructor)
: data(s), size(N - 1) {
}
};
public:
using CullingMode = filament::backend::CullingMode;
using TransparencyMode = filament::TransparencyMode;
using StencilCompareFunc = filament::backend::SamplerCompareFunc;
using StencilOperation = filament::backend::StencilOperation;
using StencilFace = filament::backend::StencilFace;
template<typename T>
using is_supported_parameter_t = typename std::enable_if<
@@ -88,23 +103,51 @@ public:
/**
* Set a uniform by name
*
* @param name Name of the parameter as defined by Material. Cannot be nullptr.
* @param value Value of the parameter to set.
* @param name Name of the parameter as defined by Material. Cannot be nullptr.
* @param nameLength Length in `char` of the name parameter.
* @param value Value of the parameter to set.
* @throws utils::PreConditionPanic if name doesn't exist or no-op if exceptions are disabled.
*/
template<typename T, typename = is_supported_parameter_t<T>>
void setParameter(const char* name, T const& value) noexcept;
void setParameter(const char* name, size_t nameLength, T const& value);
/** inline helper to provide the name as a null-terminated string literal */
template<typename T, typename = is_supported_parameter_t<T>>
inline void setParameter(StringLiteral name, T const& value) {
setParameter<T>(name.data, name.size, value);
}
/** inline helper to provide the name as a null-terminated C string */
template<typename T, typename = is_supported_parameter_t<T>>
inline void setParameter(const char* name, T const& value) {
setParameter<T>(name, strlen(name), value);
}
/**
* Set a uniform array by name
*
* @param name Name of the parameter array as defined by Material. Cannot be nullptr.
* @param values Array of values to set to the named parameter array.
* @param count Size of the array to set.
* @param name Name of the parameter array as defined by Material. Cannot be nullptr.
* @param nameLength Length in `char` of the name parameter.
* @param values Array of values to set to the named parameter array.
* @param count Size of the array to set.
* @throws utils::PreConditionPanic if name doesn't exist or no-op if exceptions are disabled.
*/
template<typename T, typename = is_supported_parameter_t<T>>
void setParameter(const char* name, const T* values, size_t count) noexcept;
void setParameter(const char* name, size_t nameLength, const T* values, size_t count);
/** inline helper to provide the name as a null-terminated string literal */
template<typename T, typename = is_supported_parameter_t<T>>
inline void setParameter(StringLiteral name, const T* values, size_t count) {
setParameter<T>(name.data, name.size, values, count);
}
/** inline helper to provide the name as a null-terminated C string */
template<typename T, typename = is_supported_parameter_t<T>>
inline void setParameter(const char* name, const T* values, size_t count) {
setParameter<T>(name, strlen(name), values, count);
}
/**
* Set a texture as the named parameter
@@ -112,48 +155,100 @@ public:
* Note: Depth textures can't be sampled with a linear filter unless the comparison mode is set
* to COMPARE_TO_TEXTURE.
*
* @param name Name of the parameter as defined by Material. Cannot be nullptr.
* @param texture Non nullptr Texture object pointer.
* @param sampler Sampler parameters.
* @param name Name of the parameter as defined by Material. Cannot be nullptr.
* @param nameLength Length in `char` of the name parameter.
* @param texture Non nullptr Texture object pointer.
* @param sampler Sampler parameters.
* @throws utils::PreConditionPanic if name doesn't exist or no-op if exceptions are disabled.
*/
void setParameter(const char* name,
Texture const* texture, TextureSampler const& sampler) noexcept;
void setParameter(const char* name, size_t nameLength,
Texture const* texture, TextureSampler const& sampler);
/** inline helper to provide the name as a null-terminated string literal */
inline void setParameter(StringLiteral name,
Texture const* texture, TextureSampler const& sampler) {
setParameter(name.data, name.size, texture, sampler);
}
/** inline helper to provide the name as a null-terminated C string */
inline void setParameter(const char* name,
Texture const* texture, TextureSampler const& sampler) {
setParameter(name, strlen(name), texture, sampler);
}
/**
* Set an RGB color as the named parameter.
* A conversion might occur depending on the specified type
*
* @param name Name of the parameter as defined by Material. Cannot be nullptr.
* @param type Whether the color value is encoded as Linear or sRGB.
* @param color Array of read, green, blue channels values.
* @param name Name of the parameter as defined by Material. Cannot be nullptr.
* @param nameLength Length in `char` of the name parameter.
* @param type Whether the color value is encoded as Linear or sRGB.
* @param color Array of read, green, blue channels values.
* @throws utils::PreConditionPanic if name doesn't exist or no-op if exceptions are disabled.
*/
void setParameter(const char* name, RgbType type, math::float3 color) noexcept;
void setParameter(const char* name, size_t nameLength, RgbType type, math::float3 color);
/** inline helper to provide the name as a null-terminated string literal */
inline void setParameter(StringLiteral name, RgbType type, math::float3 color) {
setParameter(name.data, name.size, type, color);
}
/** inline helper to provide the name as a null-terminated C string */
inline void setParameter(const char* name, RgbType type, math::float3 color) {
setParameter(name, strlen(name), type, color);
}
/**
* Set an RGBA color as the named parameter.
* A conversion might occur depending on the specified type
*
* @param name Name of the parameter as defined by Material. Cannot be nullptr.
* @param type Whether the color value is encoded as Linear or sRGB/A.
* @param color Array of read, green, blue and alpha channels values.
* @param name Name of the parameter as defined by Material. Cannot be nullptr.
* @param nameLength Length in `char` of the name parameter.
* @param type Whether the color value is encoded as Linear or sRGB/A.
* @param color Array of read, green, blue and alpha channels values.
* @throws utils::PreConditionPanic if name doesn't exist or no-op if exceptions are disabled.
*/
void setParameter(const char* name, RgbaType type, math::float4 color) noexcept;
void setParameter(const char* name, size_t nameLength, RgbaType type, math::float4 color);
/** inline helper to provide the name as a null-terminated string literal */
inline void setParameter(StringLiteral name, RgbaType type, math::float4 color) {
setParameter(name.data, name.size, type, color);
}
/** inline helper to provide the name as a null-terminated C string */
inline void setParameter(const char* name, RgbaType type, math::float4 color) {
setParameter(name, strlen(name), type, color);
}
/**
* Set up a custom scissor rectangle; by default this encompasses the View.
* Set-up a custom scissor rectangle; by default it is disabled.
*
* @param left left coordinate of the scissor box
* @param bottom bottom coordinate of the scissor box
* The scissor rectangle gets clipped by the View's viewport, in other words, the scissor
* cannot affect fragments outside of the View's Viewport.
*
* Currently the scissor is not compatible with dynamic resolution and should always be
* disabled when dynamic resolution is used.
*
* @param left left coordinate of the scissor box relative to the viewport
* @param bottom bottom coordinate of the scissor box relative to the viewport
* @param width width of the scissor box
* @param height height of the scissor box
*
* @see unsetScissor
* @see View::setViewport
* @see View::setDynamicResolutionOptions
*/
void setScissor(uint32_t left, uint32_t bottom, uint32_t width, uint32_t height) noexcept;
/**
* Returns the scissor rectangle to its default setting, which encompasses the View.
* Returns the scissor rectangle to its default disabled setting.
*
* Currently the scissor is not compatible with dynamic resolution and should always be
* disabled when dynamic resolution is used.
*
* @see View::setDynamicResolutionOptions
*/
void unsetScissor() noexcept;
@@ -227,6 +322,98 @@ public:
* Overrides the default depth testing state that was set on the material.
*/
void setDepthCulling(bool enable) noexcept;
/**
* Overrides the default stencil-buffer write state that was set on the material.
*/
void setStencilWrite(bool enable) noexcept;
/**
* Sets the stencil comparison function (default is StencilCompareFunc::A).
*
* It's possible to set separate stencil comparison functions; one for front-facing polygons,
* and one for back-facing polygons. The face parameter determines the comparison function(s)
* updated by this call.
*/
void setStencilCompareFunction(StencilCompareFunc func,
StencilFace face = StencilFace::FRONT_AND_BACK) noexcept;
/**
* Sets the stencil fail operation (default is StencilOperation::KEEP).
*
* The stencil fail operation is performed to update values in the stencil buffer when the
* stencil test fails.
*
* It's possible to set separate stencil fail operations; one for front-facing polygons, and one
* for back-facing polygons. The face parameter determines the stencil fail operation(s) updated
* by this call.
*/
void setStencilOpStencilFail(StencilOperation op,
StencilFace face = StencilFace::FRONT_AND_BACK) noexcept;
/**
* Sets the depth fail operation (default is StencilOperation::KEEP).
*
* The depth fail operation is performed to update values in the stencil buffer when the depth
* test fails.
*
* It's possible to set separate depth fail operations; one for front-facing polygons, and one
* for back-facing polygons. The face parameter determines the depth fail operation(s) updated
* by this call.
*/
void setStencilOpDepthFail(StencilOperation op,
StencilFace face = StencilFace::FRONT_AND_BACK) noexcept;
/**
* Sets the depth-stencil pass operation (default is StencilOperation::KEEP).
*
* The depth-stencil pass operation is performed to update values in the stencil buffer when
* both the stencil test and depth test pass.
*
* It's possible to set separate depth-stencil pass operations; one for front-facing polygons,
* and one for back-facing polygons. The face parameter determines the depth-stencil pass
* operation(s) updated by this call.
*/
void setStencilOpDepthStencilPass(StencilOperation op,
StencilFace face = StencilFace::FRONT_AND_BACK) noexcept;
/**
* Sets the stencil reference value (default is 0).
*
* The stencil reference value is the left-hand side for stencil comparison tests. It's also
* used as the replacement stencil value when StencilOperation is REPLACE.
*
* It's possible to set separate stencil reference values; one for front-facing polygons, and
* one for back-facing polygons. The face parameter determines the reference value(s) updated by
* this call.
*/
void setStencilReferenceValue(uint8_t value,
StencilFace face = StencilFace::FRONT_AND_BACK) noexcept;
/**
* Sets the stencil read mask (default is 0xFF).
*
* The stencil read mask masks the bits of the values participating in the stencil comparison
* test- both the value read from the stencil buffer and the reference value.
*
* It's possible to set separate stencil read masks; one for front-facing polygons, and one for
* back-facing polygons. The face parameter determines the stencil read mask(s) updated by this
* call.
*/
void setStencilReadMask(uint8_t readMask,
StencilFace face = StencilFace::FRONT_AND_BACK) noexcept;
/**
* Sets the stencil write mask (default is 0xFF).
*
* The stencil write mask masks the bits in the stencil buffer updated by stencil operations.
*
* It's possible to set separate stencil write masks; one for front-facing polygons, and one for
* back-facing polygons. The face parameter determines the stencil write mask(s) updated by this
* call.
*/
void setStencilWriteMask(uint8_t writeMask,
StencilFace face = StencilFace::FRONT_AND_BACK) noexcept;
};
} // namespace filament

8
ios/include/filament/Options.h
View File

@@ -390,6 +390,14 @@ struct VsmShadowOptions {
*/
bool mipmapping = false;
/**
* Whether to use a 32-bits or 16-bits texture format for VSM shadow maps. 32-bits
* precision is rarely needed, but it does reduces light leaks as well as "fading"
* of the shadows in some situations. Setting highPrecision to true for a single
* shadow map will double the memory usage of all shadow maps.
*/
bool highPrecision = false;
/**
* VSM minimum variance scale, must be positive.
*/

28
ios/include/filament/RenderableManager.h
View File

@@ -40,7 +40,6 @@ namespace filament {
class BufferObject;
class Engine;
class IndexBuffer;
class Material;
class MaterialInstance;
class Renderer;
class SkinningBuffer;
@@ -161,10 +160,17 @@ public:
/**
* Binds a material instance to the specified primitive.
*
* If no material is specified for a given primitive, Filament will fall back to a basic default material.
* If no material is specified for a given primitive, Filament will fall back to a basic
* default material.
*
* @param index zero-based index of the primitive, must be less than the count passed to Builder constructor
* The MaterialInstance's material must have a feature level equal or lower to the engine's
* selected feature level.
*
* @param index zero-based index of the primitive, must be less than the count passed to
* Builder constructor
* @param materialInstance the material to bind
*
* @see Engine::setActiveFeatureLevel
*/
Builder& material(size_t index, MaterialInstance const* materialInstance) noexcept;
@@ -560,6 +566,11 @@ public:
inline void setMorphTargetBufferAt(Instance instance, uint8_t level, size_t primitiveIndex,
MorphTargetBuffer* morphTargetBuffer);
/**
* Get a MorphTargetBuffer to the given primitive or null if it doesn't exist.
*/
MorphTargetBuffer* getMorphTargetBufferAt(Instance instance, uint8_t level, size_t primitiveIndex) const noexcept;
/**
* Gets the number of morphing in the given entity.
*/
@@ -590,10 +601,17 @@ public:
/**
* Changes the material instance binding for the given primitive.
*
* \see Builder::material()
* The MaterialInstance's material must have a feature level equal or lower to the engine's
* selected feature level.
*
* @exception utils::PreConditionPanic if the engine doesn't support the material's
* feature level.
*
* @see Builder::material()
* @see Engine::setActiveFeatureLevel
*/
void setMaterialInstanceAt(Instance instance,
size_t primitiveIndex, MaterialInstance const* materialInstance) noexcept;
size_t primitiveIndex, MaterialInstance const* materialInstance);
/**
* Retrieves the material instance that is bound to the given primitive.

6
ios/include/filament/Renderer.h
View File

@@ -80,8 +80,8 @@ public:
// refresh-rate of the display in Hz. set to 0 for offscreen or turn off frame-pacing.
float refreshRate = 60.0f;
[[deprecated]] uint64_t presentationDeadlineNanos = 0;
[[deprecated]] uint64_t vsyncOffsetNanos = 0;
UTILS_DEPRECATED uint64_t presentationDeadlineNanos = 0;
UTILS_DEPRECATED uint64_t vsyncOffsetNanos = 0;
};
/**
@@ -119,6 +119,8 @@ public:
struct ClearOptions {
/** Color to use to clear the SwapChain */
math::float4 clearColor = {};
/** Value to clear the stencil buffer */
uint8_t clearStencil = 0u;
/**
* Whether the SwapChain should be cleared using the clearColor. Use this if translucent
* View will be drawn, for instance.

3
ios/include/filament/Stream.h
View File

@@ -92,8 +92,7 @@ public:
* By default, Stream objects are ACQUIRED and must have external images pushed to them via
* <pre>Stream::setAcquiredImage</pre>.
*
* To create a NATIVE stream, call one of the <pre>stream</pre> methods
* on the builder.
* To create a NATIVE stream, call the <pre>stream</pre> method on the builder.
*/
class Builder : public BuilderBase<BuilderDetails> {
friend struct BuilderDetails;

143
ios/include/filament/Texture.h
View File

@@ -68,6 +68,9 @@ class UTILS_PUBLIC Texture : public FilamentAPI {
public:
static constexpr const size_t BASE_LEVEL = 0;
//! Face offsets for all faces of a cubemap
struct FaceOffsets;
using PixelBufferDescriptor = backend::PixelBufferDescriptor; //!< Geometry of a pixel buffer
using Sampler = backend::SamplerType; //!< Type of sampler
using InternalFormat = backend::TextureFormat; //!< Internal texel format
@@ -75,7 +78,6 @@ public:
using Format = backend::PixelDataFormat; //!< Pixel color format
using Type = backend::PixelDataType; //!< Pixel data format
using CompressedType = backend::CompressedPixelDataType; //!< Compressed pixel data format
using FaceOffsets = backend::FaceOffsets; //!< Cube map faces offsets
using Usage = backend::TextureUsage; //!< Usage affects texel layout
using Swizzle = backend::TextureSwizzle; //!< Texture swizzle
@@ -133,7 +135,8 @@ public:
* effectively create a 3D texture.
* @param depth Depth of the texture in texels (default: 1).
* @return This Builder, for chaining calls.
* @attention This Texture instance must use Sampler::SAMPLER_3D or Sampler::SAMPLER_2D_ARRAY or it has no effect.
* @attention This Texture instance must use Sampler::SAMPLER_3D or
* Sampler::SAMPLER_2D_ARRAY or it has no effect.
*/
Builder& depth(uint32_t depth) noexcept;
@@ -289,59 +292,8 @@ public:
InternalFormat getFormat() const noexcept;
/**
* Specify the image of a 2D texture for a level.
*
* @param engine Engine this texture is associated to.
* @param level Level to set the image for.
* @param buffer Client-side buffer containing the image to set.
*
* @attention \p engine must be the instance passed to Builder::build()
* @attention \p level must be less than getLevels().
* @attention \p buffer's Texture::Format must match that of getFormat().
* @attention This Texture instance must use Sampler::SAMPLER_2D or
* Sampler::SAMPLER_EXTERNAL. IF the later is specified
* and external textures are supported by the driver implementation,
* this method will have no effect, otherwise it will behave as if the
* texture was specified with driver::SamplerType::SAMPLER_2D.
*
* @note
* This is equivalent to calling:
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* setImage(engine, level, 0, 0, getWidth(level), getHeight(level), buffer);
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* @see Builder::sampler()
*/
void setImage(Engine& engine, size_t level, PixelBufferDescriptor&& buffer) const;
/**
* Updates a sub-image of a 2D texture for a level.
*
* @param engine Engine this texture is associated to.
* @param level Level to set the image for.
* @param xoffset Left offset of the sub-region to update.
* @param yoffset Bottom offset of the sub-region to update.
* @param width Width of the sub-region to update.
* @param height Height of the sub-region to update.
* @param buffer Client-side buffer containing the image to set.
*
* @attention \p engine must be the instance passed to Builder::build()
* @attention \p level must be less than getLevels().
* @attention \p buffer's Texture::Format must match that of getFormat().
* @attention This Texture instance must use Sampler::SAMPLER_2D or
* Sampler::SAMPLER_EXTERNAL. IF the later is specified
* and external textures are supported by the driver implementation,
* this method will have no effect, otherwise it will behave as if the
* texture was specified with Sampler::SAMPLER_2D.
*
* @see Builder::sampler()
*/
void setImage(Engine& engine, size_t level,
uint32_t xoffset, uint32_t yoffset, uint32_t width, uint32_t height,
PixelBufferDescriptor&& buffer) const;
/**
* Updates a sub-image of a 3D texture or 2D texture array for a level.
* Updates a sub-image of a 3D texture or 2D texture array for a level. Cubemaps are treated
* like a 2D array of six layers.
*
* @param engine Engine this texture is associated to.
* @param level Level to set the image for.
@@ -356,7 +308,8 @@ public:
* @attention \p engine must be the instance passed to Builder::build()
* @attention \p level must be less than getLevels().
* @attention \p buffer's Texture::Format must match that of getFormat().
* @attention This Texture instance must use Sampler::SAMPLER_3D or Sampler::SAMPLER_2D_array.
* @attention This Texture instance must use Sampler::SAMPLER_3D, Sampler::SAMPLER_2D_ARRAY
* or Sampler::SAMPLER_CUBEMAP.
*
* @see Builder::sampler()
*/
@@ -365,6 +318,33 @@ public:
uint32_t width, uint32_t height, uint32_t depth,
PixelBufferDescriptor&& buffer) const;
/**
* inline helper to update a 2D texture
*
* @see setImage(Engine& engine, size_t level,
* uint32_t xoffset, uint32_t yoffset, uint32_t zoffset,
* uint32_t width, uint32_t height, uint32_t depth,
* PixelBufferDescriptor&& buffer)
*/
inline void setImage(Engine& engine, size_t level, PixelBufferDescriptor&& buffer) const {
setImage(engine, level, 0, 0, 0,
uint32_t(getWidth(level)), uint32_t(getHeight(level)), 1, std::move(buffer));
}
/**
* inline helper to update a 2D texture
*
* @see setImage(Engine& engine, size_t level,
* uint32_t xoffset, uint32_t yoffset, uint32_t zoffset,
* uint32_t width, uint32_t height, uint32_t depth,
* PixelBufferDescriptor&& buffer)
*/
inline void setImage(Engine& engine, size_t level,
uint32_t xoffset, uint32_t yoffset, uint32_t width, uint32_t height,
PixelBufferDescriptor&& buffer) const {
setImage(engine, level, xoffset, yoffset, 0, width, height, 1, std::move(buffer));
}
/**
* Specify all six images of a cube map level.
*
@@ -382,7 +362,13 @@ public:
* @attention This Texture instance must use Sampler::SAMPLER_CUBEMAP or it has no effect
*
* @see Texture::CubemapFace, Builder::sampler()
*
* @deprecated Instead, use setImage(Engine& engine, size_t level,
* uint32_t xoffset, uint32_t yoffset, uint32_t zoffset,
* uint32_t width, uint32_t height, uint32_t depth,
* PixelBufferDescriptor&& buffer)
*/
UTILS_DEPRECATED
void setImage(Engine& engine, size_t level,
PixelBufferDescriptor&& buffer, const FaceOffsets& faceOffsets) const;
@@ -510,6 +496,51 @@ public:
void generatePrefilterMipmap(Engine& engine,
PixelBufferDescriptor&& buffer, const FaceOffsets& faceOffsets,
PrefilterOptions const* options = nullptr);
/** @deprecated */
struct FaceOffsets {
using size_type = size_t;
union {
struct {
size_type px; //!< +x face offset in bytes
size_type nx; //!< -x face offset in bytes
size_type py; //!< +y face offset in bytes
size_type ny; //!< -y face offset in bytes
size_type pz; //!< +z face offset in bytes
size_type nz; //!< -z face offset in bytes
};
size_type offsets[6];
};
size_type operator[](size_t n) const noexcept { return offsets[n]; }
size_type& operator[](size_t n) { return offsets[n]; }
FaceOffsets() noexcept = default;
explicit FaceOffsets(size_type faceSize) noexcept {
px = faceSize * 0;
nx = faceSize * 1;
py = faceSize * 2;
ny = faceSize * 3;
pz = faceSize * 4;
nz = faceSize * 5;
}
FaceOffsets(const FaceOffsets& rhs) noexcept {
px = rhs.px;
nx = rhs.nx;
py = rhs.py;
ny = rhs.ny;
pz = rhs.pz;
nz = rhs.nz;
}
FaceOffsets& operator=(const FaceOffsets& rhs) noexcept {
px = rhs.px;
nx = rhs.nx;
py = rhs.py;
ny = rhs.ny;
pz = rhs.pz;
nz = rhs.nz;
return *this;
}
};
};
} // namespace filament

47
ios/include/filament/View.h
View File

@@ -220,7 +220,6 @@ public:
*
* Renderable objects can have one or several layers associated to them. Layers are
* represented with an 8-bits bitmask, where each bit corresponds to a layer.
* @see RenderableManager::setLayerMask().
*
* This call sets which of those layers are visible. Renderables in invisible layers won't be
* rendered.
@@ -229,11 +228,24 @@ public:
* @param values a bitmask where each bit sets the visibility of the corresponding layer
* (1: visible, 0: invisible), only layers in \p select are affected.
*
* @note By default all layers are visible.
* @see RenderableManager::setLayerMask().
*
* @note By default only layer 0 (bitmask 0x01) is visible.
* @note This is a convenient way to quickly show or hide sets of Renderable objects.
*/
void setVisibleLayers(uint8_t select, uint8_t values) noexcept;
/**
* Helper function to enable or disable a visibility layer.
* @param layer layer between 0 and 7 to enable or disable
* @param enabled true to enable the layer, false to disable it
* @see RenderableManager::setVisibleLayers()
*/
inline void setLayerEnabled(size_t layer, bool enabled) noexcept {
const uint8_t mask = 1u << layer;
setVisibleLayers(mask, enabled ? mask : 0);
}
/**
* Get the visible layers.
*
@@ -637,6 +649,33 @@ public:
*/
bool isFrontFaceWindingInverted() const noexcept;
/**
* Enables use of the stencil buffer.
*
* The stencil buffer is an 8-bit, per-fragment unsigned integer stored alongside the depth
* buffer. The stencil buffer is cleared at the beginning of a frame and discarded after the
* color pass.
*
* Each fragment's stencil value is set during rasterization by specifying stencil operations on
* a Material. The stencil buffer can be used as a mask for later rendering by setting a
* Material's stencil comparison function and reference value. Fragments that don't pass the
* stencil test are then discarded.
*
* Post-processing must be enabled in order to use the stencil buffer.
*
* A renderable's priority (see RenderableManager::setPriority) is useful to control the order
* in which primitives are drawn.
*
* @param enabled True to enable the stencil buffer, false disables it (default)
*/
void setStencilBufferEnabled(bool enabled) noexcept;
/**
* Returns true if the stencil buffer is enabled.
* See setStencilBufferEnabled() for more information.
*/
bool isStencilBufferEnabled() const noexcept;
// for debugging...
//! debugging: allows to entirely disable frustum culling. (culling enabled by default).
@@ -697,7 +736,7 @@ public:
PickingQuery& query = pick(x, y, [](PickingQueryResult const& result, PickingQuery* pq) {
void* user = pq->storage;
(*static_cast<T**>(user)->*method)(result);
});
}, handler);
query.storage[0] = instance;
}
@@ -720,7 +759,7 @@ public:
T* that = static_cast<T*>(user);
(that->*method)(result);
that->~T();
});
}, handler);
new(query.storage) T(std::move(instance));
}