diff --git a/CMakeLists.txt b/CMakeLists.txt index 4d22f122c3d..91ab2922d83 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -706,7 +706,7 @@ function(get_resgen_vars ARCHIVE_DIR ARCHIVE_NAME) set(RESGEN_OUTPUTS "${OUTPUTS}" PARENT_SCOPE) set(RESGEN_FLAGS -qx ${ARCHIVE_DIR} -p ${ARCHIVE_NAME} PARENT_SCOPE) set(RESGEN_SOURCE "${ARCHIVE_DIR}/${ARCHIVE_NAME}${ASM_SUFFIX}.S" PARENT_SCOPE) - set(RESGEN_SOURCE_FLAGS "-I${ARCHIVE_DIR} ${ASM_ARCH_FLAG}" PARENT_SCOPE) + set(RESGEN_SOURCE_FLAGS "-I'${ARCHIVE_DIR}' ${ASM_ARCH_FLAG}" PARENT_SCOPE) endif() endfunction() diff --git a/README.md b/README.md index 01bfe81f16f..bb2c074eb15 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ repositories { } dependencies { - implementation 'com.google.android.filament:filament-android:1.50.2' + implementation 'com.google.android.filament:filament-android:1.50.3' } ``` @@ -51,7 +51,7 @@ Here are all the libraries available in the group `com.google.android.filament`: iOS projects can use CocoaPods to install the latest release: ```shell -pod 'Filament', '~> 1.50.2' +pod 'Filament', '~> 1.50.3' ``` ### Snapshots diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 589c677709a..209a0afdec2 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -7,6 +7,9 @@ A new header is inserted each time a *tag* is created. Instead, if you are authoring a PR for the main branch, add your release note to [NEW_RELEASE_NOTES.md](./NEW_RELEASE_NOTES.md). +## v1.50.3 + + ## v1.50.2 diff --git a/android/filament-android/src/main/cpp/Engine.cpp b/android/filament-android/src/main/cpp/Engine.cpp index 51499a14bc9..05893cbd5bf 100644 --- a/android/filament-android/src/main/cpp/Engine.cpp +++ b/android/filament-android/src/main/cpp/Engine.cpp @@ -484,7 +484,8 @@ extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBu extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBuilderConfig(JNIEnv*, jclass, jlong nativeBuilder, jlong commandBufferSizeMB, jlong perRenderPassArenaSizeMB, jlong driverHandleArenaSizeMB, jlong minCommandBufferSizeMB, jlong perFrameCommandsSizeMB, - jlong jobSystemThreadCount, jlong stereoscopicEyeCount) { + jlong jobSystemThreadCount, jlong stereoscopicEyeCount, + jlong resourceAllocatorCacheSizeMB, jlong resourceAllocatorCacheMaxAge) { Engine::Builder* builder = (Engine::Builder*) nativeBuilder; Engine::Config config = { .commandBufferSizeMB = (uint32_t) commandBufferSizeMB, @@ -494,6 +495,8 @@ extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBu .perFrameCommandsSizeMB = (uint32_t) perFrameCommandsSizeMB, .jobSystemThreadCount = (uint32_t) jobSystemThreadCount, .stereoscopicEyeCount = (uint8_t) stereoscopicEyeCount, + .resourceAllocatorCacheSizeMB = (uint32_t) resourceAllocatorCacheSizeMB, + .resourceAllocatorCacheMaxAge = (uint8_t) resourceAllocatorCacheMaxAge, }; builder->config(&config); } diff --git a/android/filament-android/src/main/java/com/google/android/filament/Engine.java b/android/filament-android/src/main/java/com/google/android/filament/Engine.java index 014cc33ceec..6b4647e2ac1 100644 --- a/android/filament-android/src/main/java/com/google/android/filament/Engine.java +++ b/android/filament-android/src/main/java/com/google/android/filament/Engine.java @@ -211,7 +211,8 @@ public Builder config(Config config) { nSetBuilderConfig(mNativeBuilder, config.commandBufferSizeMB, config.perRenderPassArenaSizeMB, config.driverHandleArenaSizeMB, config.minCommandBufferSizeMB, config.perFrameCommandsSizeMB, - config.jobSystemThreadCount, config.stereoscopicEyeCount); + config.jobSystemThreadCount, config.stereoscopicEyeCount, + config.resourceAllocatorCacheSizeMB, config.resourceAllocatorCacheMaxAge); return this; } @@ -356,6 +357,18 @@ public static class Config { * @see Engine#getMaxStereoscopicEyes */ public long stereoscopicEyeCount = 2; + + /* + * Size in MiB of the frame graph texture cache. This should be adjusted based on the + * size of used render targets (typically the screen). + */ + public long resourceAllocatorCacheSizeMB = 64; + + /* + * This value determines for how many frames are texture entries kept in the cache. + * The default value of 30 corresponds to about half a second at 60 fps. + */ + public long resourceAllocatorCacheMaxAge = 30; } private Engine(long nativeEngine, Config config) { @@ -1227,7 +1240,8 @@ private static void assertDestroy(boolean success) { private static native void nSetBuilderConfig(long nativeBuilder, long commandBufferSizeMB, long perRenderPassArenaSizeMB, long driverHandleArenaSizeMB, long minCommandBufferSizeMB, long perFrameCommandsSizeMB, long jobSystemThreadCount, - long stereoscopicEyeCount); + long stereoscopicEyeCount, + long resourceAllocatorCacheSizeMB, long resourceAllocatorCacheMaxAge); private static native void nSetBuilderFeatureLevel(long nativeBuilder, int ordinal); private static native void nSetBuilderSharedContext(long nativeBuilder, long sharedContext); private static native long nBuilderBuild(long nativeBuilder); diff --git a/android/gradle.properties b/android/gradle.properties index e9b4bb3f457..53e64758c22 100644 --- a/android/gradle.properties +++ b/android/gradle.properties @@ -1,5 +1,5 @@ GROUP=com.google.android.filament -VERSION_NAME=1.50.2 +VERSION_NAME=1.50.3 POM_DESCRIPTION=Real-time physically based rendering engine for Android. diff --git a/build/linux/combine-static-libs.sh b/build/linux/combine-static-libs.sh index 4d0c7930812..71157dafa33 100755 --- a/build/linux/combine-static-libs.sh +++ b/build/linux/combine-static-libs.sh @@ -125,7 +125,13 @@ if [[ "${has_universal}" == "true" ]]; then arch_output="${OUTPUT_PATH%.a}_${arch}.a" arch_outputs+=("$arch_output") - combine_static_libs "$arch_output" $(find "$(pwd)/${archs_temp_dir}/${arch}" -iname '*.a') + + archives=() + while IFS= read -r -d $'\0'; do + archives+=("$REPLY") + done < <(find "$(pwd)/${archs_temp_dir}/${arch}" -iname '*.a' -print0) + + combine_static_libs "$arch_output" "$archives" done # Finally, combine the single-architecture archives into a universal binary. diff --git a/filament/backend/include/backend/Platform.h b/filament/backend/include/backend/Platform.h index b4924916bd7..b89fb98f7fd 100644 --- a/filament/backend/include/backend/Platform.h +++ b/filament/backend/include/backend/Platform.h @@ -84,7 +84,7 @@ class UTILS_PUBLIC Platform { * * @return nullptr on failure, or a pointer to the newly created driver. */ - virtual backend::Driver* createDriver(void* sharedContext, + virtual backend::Driver* UTILS_NULLABLE createDriver(void* UTILS_NULLABLE sharedContext, const DriverConfig& driverConfig) noexcept = 0; /** @@ -102,7 +102,8 @@ class UTILS_PUBLIC Platform { * cache. */ using InsertBlobFunc = utils::Invocable< - void(const void* key, size_t keySize, const void* value, size_t valueSize)>; + void(const void* UTILS_NONNULL key, size_t keySize, + const void* UTILS_NONNULL value, size_t valueSize)>; /* * RetrieveBlobFunc is an Invocable to an application-provided function that a @@ -110,7 +111,8 @@ class UTILS_PUBLIC Platform { * cache. */ using RetrieveBlobFunc = utils::Invocable< - size_t(const void* key, size_t keySize, void* value, size_t valueSize)>; + size_t(const void* UTILS_NONNULL key, size_t keySize, + void* UTILS_NONNULL value, size_t valueSize)>; /** * Sets the callback functions that the backend can use to interact with caching functionality @@ -163,7 +165,8 @@ class UTILS_PUBLIC Platform { * @param value pointer to the beginning of the value data that is to be inserted * @param valueSize specifies the size in byte of the data pointed to by */ - void insertBlob(const void* key, size_t keySize, const void* value, size_t valueSize); + void insertBlob(const void* UTILS_NONNULL key, size_t keySize, + const void* UTILS_NONNULL value, size_t valueSize); /** * To retrieve the binary value associated with a given key from the cache, a @@ -182,7 +185,8 @@ class UTILS_PUBLIC Platform { * @return If the cache contains a value associated with the given key then the * size of that binary value in bytes is returned. Otherwise 0 is returned. */ - size_t retrieveBlob(const void* key, size_t keySize, void* value, size_t valueSize); + size_t retrieveBlob(const void* UTILS_NONNULL key, size_t keySize, + void* UTILS_NONNULL value, size_t valueSize); private: InsertBlobFunc mInsertBlob; diff --git a/filament/backend/include/backend/platforms/OpenGLPlatform.h b/filament/backend/include/backend/platforms/OpenGLPlatform.h index da3f2fda6be..12deb801303 100644 --- a/filament/backend/include/backend/platforms/OpenGLPlatform.h +++ b/filament/backend/include/backend/platforms/OpenGLPlatform.h @@ -21,6 +21,8 @@ #include #include +#include + #include namespace filament::backend { @@ -41,8 +43,8 @@ class OpenGLPlatform : public Platform { * Derived classes can use this to instantiate the default OpenGLDriver backend. * This is typically called from your implementation of createDriver() */ - static Driver* createDefaultDriver(OpenGLPlatform* platform, - void* sharedContext, const DriverConfig& driverConfig); + static Driver* UTILS_NULLABLE createDefaultDriver(OpenGLPlatform* UTILS_NONNULL platform, + void* UTILS_NULLABLE sharedContext, const DriverConfig& driverConfig); ~OpenGLPlatform() noexcept override; @@ -69,7 +71,8 @@ class OpenGLPlatform : public Platform { * @return The driver's SwapChain object. * */ - virtual SwapChain* createSwapChain(void* nativeWindow, uint64_t flags) noexcept = 0; + virtual SwapChain* UTILS_NONNULL createSwapChain( + void* UTILS_NULLABLE nativeWindow, uint64_t flags) noexcept = 0; /** * Return whether createSwapChain supports the SWAP_CHAIN_CONFIG_SRGB_COLORSPACE flag. @@ -90,13 +93,14 @@ class OpenGLPlatform : public Platform { * TODO: we need a more generic way of passing construction parameters * A void* might be enough. */ - virtual SwapChain* createSwapChain(uint32_t width, uint32_t height, uint64_t flags) noexcept = 0; + virtual SwapChain* UTILS_NULLABLE createSwapChain( + uint32_t width, uint32_t height, uint64_t flags) noexcept = 0; /** * Called by the driver to destroys the SwapChain * @param swapChain SwapChain to be destroyed. */ - virtual void destroySwapChain(SwapChain* swapChain) noexcept = 0; + virtual void destroySwapChain(SwapChain* UTILS_NONNULL swapChain) noexcept = 0; /** * Returns the set of buffers that must be preserved up to the call to commit(). @@ -109,7 +113,7 @@ class OpenGLPlatform : public Platform { * @return buffer that must be preserved * @see commit() */ - virtual TargetBufferFlags getPreservedFlags(SwapChain* swapChain) noexcept; + virtual TargetBufferFlags getPreservedFlags(SwapChain* UTILS_NONNULL swapChain) noexcept; /** * Called by the driver to establish the default FBO. The default implementation returns 0. @@ -123,14 +127,16 @@ class OpenGLPlatform : public Platform { * @param drawSwapChain SwapChain to draw to. It must be bound to the default FBO. * @param readSwapChain SwapChain to read from (for operation like `glBlitFramebuffer`) */ - virtual void makeCurrent(SwapChain* drawSwapChain, SwapChain* readSwapChain) noexcept = 0; + virtual void makeCurrent( + SwapChain* UTILS_NONNULL drawSwapChain, + SwapChain* UTILS_NONNULL readSwapChain) noexcept = 0; /** * Called by the driver once the current frame finishes drawing. Typically, this should present * the drawSwapChain. This is for example where `eglMakeCurrent()` would be called. * @param swapChain the SwapChain to present. */ - virtual void commit(SwapChain* swapChain) noexcept = 0; + virtual void commit(SwapChain* UTILS_NONNULL swapChain) noexcept = 0; /** * Set the time the next committed buffer should be presented to the user at. @@ -155,14 +161,14 @@ class OpenGLPlatform : public Platform { * * @return A Fence object. The default implementation returns nullptr. */ - virtual Fence* createFence() noexcept; + virtual Fence* UTILS_NULLABLE createFence() noexcept; /** * Destroys a Fence object. The default implementation does nothing. * * @param fence Fence to destroy. */ - virtual void destroyFence(Fence* fence) noexcept; + virtual void destroyFence(Fence* UTILS_NONNULL fence) noexcept; /** * Waits on a Fence. @@ -172,7 +178,7 @@ class OpenGLPlatform : public Platform { * @return Whether the fence signaled or timed out. See backend::FenceStatus. * The default implementation always return backend::FenceStatus::ERROR. */ - virtual backend::FenceStatus waitFence(Fence* fence, uint64_t timeout) noexcept; + virtual backend::FenceStatus waitFence(Fence* UTILS_NONNULL fence, uint64_t timeout) noexcept; // -------------------------------------------------------------------------------------------- @@ -186,13 +192,13 @@ class OpenGLPlatform : public Platform { * @param nativeStream The native stream, this parameter depends on the concrete implementation. * @return A new Stream object. */ - virtual Stream* createStream(void* nativeStream) noexcept; + virtual Stream* UTILS_NULLABLE createStream(void* UTILS_NULLABLE nativeStream) noexcept; /** * Destroys a Stream. * @param stream Stream to destroy. */ - virtual void destroyStream(Stream* stream) noexcept; + virtual void destroyStream(Stream* UTILS_NONNULL stream) noexcept; /** * The specified stream takes ownership of the texture (tname) object @@ -202,20 +208,21 @@ class OpenGLPlatform : public Platform { * @param stream Stream to take ownership of the texture * @param tname GL texture id to "bind" to the Stream. */ - virtual void attach(Stream* stream, intptr_t tname) noexcept; + virtual void attach(Stream* UTILS_NONNULL stream, intptr_t tname) noexcept; /** * Destroys the texture associated to the stream * @param stream Stream to detach from its texture */ - virtual void detach(Stream* stream) noexcept; + virtual void detach(Stream* UTILS_NONNULL stream) noexcept; /** * Updates the content of the texture attached to the stream. * @param stream Stream to update * @param timestamp Output parameter: Timestamp of the image bound to the texture. */ - virtual void updateTexImage(Stream* stream, int64_t* timestamp) noexcept; + virtual void updateTexImage(Stream* UTILS_NONNULL stream, + int64_t* UTILS_NONNULL timestamp) noexcept; // -------------------------------------------------------------------------------------------- @@ -228,13 +235,13 @@ class OpenGLPlatform : public Platform { * implementation could just return { 0, GL_TEXTURE_2D } at this point. The actual * values can be delayed until setExternalImage. */ - virtual ExternalTexture *createExternalImageTexture() noexcept; + virtual ExternalTexture* UTILS_NULLABLE createExternalImageTexture() noexcept; /** * Destroys an external texture handle and associated data. * @param texture a pointer to the handle to destroy. */ - virtual void destroyExternalImage(ExternalTexture* texture) noexcept; + virtual void destroyExternalImage(ExternalTexture* UTILS_NONNULL texture) noexcept; // called on the application thread to allow Filament to take ownership of the image @@ -247,7 +254,7 @@ class OpenGLPlatform : public Platform { * @param externalImage A token representing the platform's external image. * @see destroyExternalImage */ - virtual void retainExternalImage(void* externalImage) noexcept; + virtual void retainExternalImage(void* UTILS_NONNULL externalImage) noexcept; /** * Called to bind the platform-specific externalImage to an ExternalTexture. @@ -261,7 +268,8 @@ class OpenGLPlatform : public Platform { * @param texture an in/out pointer to ExternalTexture, id and target can be updated if necessary. * @return true on success, false on error. */ - virtual bool setExternalImage(void* externalImage, ExternalTexture* texture) noexcept; + virtual bool setExternalImage(void* UTILS_NONNULL externalImage, + ExternalTexture* UTILS_NONNULL texture) noexcept; /** * The method allows platforms to convert a user-supplied external image object into a new type diff --git a/filament/include/filament/BufferObject.h b/filament/include/filament/BufferObject.h index 61dad944c16..74a4b1ff390 100644 --- a/filament/include/filament/BufferObject.h +++ b/filament/include/filament/BufferObject.h @@ -84,8 +84,7 @@ class UTILS_PUBLIC BufferObject : public FilamentAPI { * * @param engine Reference to the filament::Engine to associate this BufferObject with. * - * @return pointer to the newly created object or nullptr if exceptions are disabled and - * an error occurred. + * @return pointer to the newly created object * * @exception utils::PostConditionPanic if a runtime error occurred, such as running out of * memory or other resources. @@ -93,7 +92,7 @@ class UTILS_PUBLIC BufferObject : public FilamentAPI { * * @see IndexBuffer::setBuffer */ - BufferObject* build(Engine& engine); + BufferObject* UTILS_NONNULL build(Engine& engine); private: friend class FBufferObject; }; diff --git a/filament/include/filament/Camera.h b/filament/include/filament/Camera.h index 6c5f36ccd63..74f34af0fec 100644 --- a/filament/include/filament/Camera.h +++ b/filament/include/filament/Camera.h @@ -306,7 +306,7 @@ class UTILS_PUBLIC Camera : public FilamentAPI { * @see setCustomProjection * @see Engine::Config::stereoscopicEyeCount */ - void setCustomEyeProjection(math::mat4 const* projection, size_t count, + void setCustomEyeProjection(math::mat4 const* UTILS_NONNULL projection, size_t count, math::mat4 const& projectionForCulling, double near, double far); /** Sets an additional matrix that scales the projection matrix. diff --git a/filament/include/filament/ColorGrading.h b/filament/include/filament/ColorGrading.h index 94a11c109d5..e5c8f3cae3f 100644 --- a/filament/include/filament/ColorGrading.h +++ b/filament/include/filament/ColorGrading.h @@ -203,7 +203,7 @@ class UTILS_PUBLIC ColorGrading : public FilamentAPI { * * @return This Builder, for chaining calls */ - Builder& toneMapper(const ToneMapper* toneMapper) noexcept; + Builder& toneMapper(ToneMapper const* UTILS_NULLABLE toneMapper) noexcept; /** * Selects the tone mapping operator to apply to the HDR color buffer as the last @@ -473,10 +473,9 @@ class UTILS_PUBLIC ColorGrading : public FilamentAPI { * * @param engine Reference to the filament::Engine to associate this ColorGrading with. * - * @return pointer to the newly created object or nullptr if exceptions are disabled and - * an error occurred. + * @return pointer to the newly created object. */ - ColorGrading* build(Engine& engine); + ColorGrading* UTILS_NONNULL build(Engine& engine); private: friend class FColorGrading; diff --git a/filament/include/filament/DebugRegistry.h b/filament/include/filament/DebugRegistry.h index 691067d7655..d5e1d8e983b 100644 --- a/filament/include/filament/DebugRegistry.h +++ b/filament/include/filament/DebugRegistry.h @@ -39,27 +39,12 @@ namespace filament { class UTILS_PUBLIC DebugRegistry : public FilamentAPI { public: - /** - * Type of a property - */ - enum Type { - BOOL, INT, FLOAT, FLOAT2, FLOAT3, FLOAT4 - }; - - /** - * Information about a property - */ - struct Property { - const char* name; //!< property name - Type type; //!< property type - }; - /** * Queries whether a property exists * @param name The name of the property to query * @return true if the property exists, false otherwise */ - bool hasProperty(const char* name) const noexcept; + bool hasProperty(const char* UTILS_NONNULL name) const noexcept; /** * Queries the address of a property's data from its name @@ -67,28 +52,30 @@ class UTILS_PUBLIC DebugRegistry : public FilamentAPI { * @return Address of the data of the \p name property * @{ */ - void* getPropertyAddress(const char* name); + void* UTILS_NULLABLE getPropertyAddress(const char* UTILS_NONNULL name); - void const* getPropertyAddress(const char* name) const noexcept; + void const* UTILS_NULLABLE getPropertyAddress(const char* UTILS_NONNULL name) const noexcept; template - inline T* getPropertyAddress(const char* name) { + inline T* UTILS_NULLABLE getPropertyAddress(const char* UTILS_NONNULL name) { return static_cast(getPropertyAddress(name)); } template - inline T const* getPropertyAddress(const char* name) const noexcept { + inline T const* UTILS_NULLABLE getPropertyAddress(const char* UTILS_NONNULL name) const noexcept { return static_cast(getPropertyAddress(name)); } template - inline bool getPropertyAddress(const char* name, T** p) { + inline bool getPropertyAddress(const char* UTILS_NONNULL name, + T* UTILS_NULLABLE* UTILS_NONNULL p) { *p = getPropertyAddress(name); return *p != nullptr; } template - inline bool getPropertyAddress(const char* name, T* const* p) const noexcept { + inline bool getPropertyAddress(const char* UTILS_NONNULL name, + T* const UTILS_NULLABLE* UTILS_NONNULL p) const noexcept { *p = getPropertyAddress(name); return *p != nullptr; } @@ -101,12 +88,12 @@ class UTILS_PUBLIC DebugRegistry : public FilamentAPI { * @return true if the operation was successful, false otherwise. * @{ */ - bool setProperty(const char* name, bool v) noexcept; - bool setProperty(const char* name, int v) noexcept; - bool setProperty(const char* name, float v) noexcept; - bool setProperty(const char* name, math::float2 v) noexcept; - bool setProperty(const char* name, math::float3 v) noexcept; - bool setProperty(const char* name, math::float4 v) noexcept; + bool setProperty(const char* UTILS_NONNULL name, bool v) noexcept; + bool setProperty(const char* UTILS_NONNULL name, int v) noexcept; + bool setProperty(const char* UTILS_NONNULL name, float v) noexcept; + bool setProperty(const char* UTILS_NONNULL name, math::float2 v) noexcept; + bool setProperty(const char* UTILS_NONNULL name, math::float3 v) noexcept; + bool setProperty(const char* UTILS_NONNULL name, math::float4 v) noexcept; /** @}*/ /** @@ -116,20 +103,20 @@ class UTILS_PUBLIC DebugRegistry : public FilamentAPI { * @return true if the call was successful and \p v was updated * @{ */ - bool getProperty(const char* name, bool* v) const noexcept; - bool getProperty(const char* name, int* v) const noexcept; - bool getProperty(const char* name, float* v) const noexcept; - bool getProperty(const char* name, math::float2* v) const noexcept; - bool getProperty(const char* name, math::float3* v) const noexcept; - bool getProperty(const char* name, math::float4* v) const noexcept; + bool getProperty(const char* UTILS_NONNULL name, bool* UTILS_NONNULL v) const noexcept; + bool getProperty(const char* UTILS_NONNULL name, int* UTILS_NONNULL v) const noexcept; + bool getProperty(const char* UTILS_NONNULL name, float* UTILS_NONNULL v) const noexcept; + bool getProperty(const char* UTILS_NONNULL name, math::float2* UTILS_NONNULL v) const noexcept; + bool getProperty(const char* UTILS_NONNULL name, math::float3* UTILS_NONNULL v) const noexcept; + bool getProperty(const char* UTILS_NONNULL name, math::float4* UTILS_NONNULL v) const noexcept; /** @}*/ struct DataSource { - void const* data; + void const* UTILS_NULLABLE data; size_t count; }; - DataSource getDataSource(const char* name) const noexcept; + DataSource getDataSource(const char* UTILS_NONNULL name) const noexcept; struct FrameHistory { using duration_ms = float; diff --git a/filament/include/filament/Engine.h b/filament/include/filament/Engine.h index 15ae07b1f49..904cbda4a3f 100644 --- a/filament/include/filament/Engine.h +++ b/filament/include/filament/Engine.h @@ -305,11 +305,23 @@ class UTILS_PUBLIC Engine { * @see Engine::getMaxStereoscopicEyes */ uint8_t stereoscopicEyeCount = 2; + + /* + * Size in MiB of the frame graph texture cache. This should be adjusted based on the + * size of used render targets (typically the screen). + */ + uint32_t resourceAllocatorCacheSizeMB = 64; + + /* + * This value determines for how many frames are texture entries kept in the cache. + * The default value of 30 corresponds to about half a second at 60 fps. + */ + uint32_t resourceAllocatorCacheMaxAge = 30; }; #if UTILS_HAS_THREADING - using CreateCallback = void(void* user, void* token); + using CreateCallback = void(void* UTILS_NULLABLE user, void* UTILS_NONNULL token); #endif /** @@ -348,7 +360,7 @@ class UTILS_PUBLIC Engine { * * @return A reference to this Builder for chaining calls. */ - Builder& platform(Platform* platform) noexcept; + Builder& platform(Platform* UTILS_NULLABLE platform) noexcept; /** * @param config A pointer to optional parameters to specify memory size @@ -356,7 +368,7 @@ class UTILS_PUBLIC Engine { * * @return A reference to this Builder for chaining calls. */ - Builder& config(const Config* config) noexcept; + Builder& config(const Config* UTILS_NULLABLE config) noexcept; /** * @param sharedContext A platform-dependant context used as a shared context @@ -364,7 +376,7 @@ class UTILS_PUBLIC Engine { * * @return A reference to this Builder for chaining calls. */ - Builder& sharedContext(void* sharedContext) noexcept; + Builder& sharedContext(void* UTILS_NULLABLE sharedContext) noexcept; /** * @param featureLevel The feature level at which initialize Filament. @@ -379,7 +391,7 @@ class UTILS_PUBLIC Engine { * @param callback Callback called once the engine is initialized and it is safe to * call Engine::getEngine(). */ - void build(utils::Invocable&& callback) const; + void build(utils::Invocable&& callback) const; #endif /** @@ -394,16 +406,17 @@ class UTILS_PUBLIC Engine { * allocate the command buffer. If exceptions are disabled, this condition if * fatal and this function will abort. */ - Engine* build() const; + Engine* UTILS_NULLABLE build() const; }; /** * Backward compatibility helper to create an Engine. * @see Builder */ - static inline Engine* create(Backend backend = Backend::DEFAULT, - Platform* platform = nullptr, void* sharedContext = nullptr, - const Config* config = nullptr) { + static inline Engine* UTILS_NULLABLE create(Backend backend = Backend::DEFAULT, + Platform* UTILS_NULLABLE platform = nullptr, + void* UTILS_NULLABLE sharedContext = nullptr, + const Config* UTILS_NULLABLE config = nullptr) { return Engine::Builder() .backend(backend) .platform(platform) @@ -418,16 +431,18 @@ class UTILS_PUBLIC Engine { * Backward compatibility helper to create an Engine asynchronously. * @see Builder */ - static inline void createAsync(CreateCallback callback, void* user, + static inline void createAsync(CreateCallback callback, + void* UTILS_NULLABLE user, Backend backend = Backend::DEFAULT, - Platform* platform = nullptr, void* sharedContext = nullptr, - const Config* config = nullptr) { + Platform* UTILS_NULLABLE platform = nullptr, + void* UTILS_NULLABLE sharedContext = nullptr, + const Config* UTILS_NULLABLE config = nullptr) { Engine::Builder() .backend(backend) .platform(platform) .sharedContext(sharedContext) .config(config) - .build([callback, user](void* token) { + .build([callback, user](void* UTILS_NONNULL token) { callback(user, token); }); } @@ -444,7 +459,7 @@ class UTILS_PUBLIC Engine { * allocate the command buffer. If exceptions are disabled, this condition if fatal and * this function will abort. */ - static Engine* getEngine(void* token); + static Engine* UTILS_NULLABLE getEngine(void* UTILS_NONNULL token); #endif @@ -474,7 +489,7 @@ class UTILS_PUBLIC Engine { * \remark * This method is thread-safe. */ - static void destroy(Engine** engine); + static void destroy(Engine* UTILS_NULLABLE* UTILS_NULLABLE engine); /** * Destroy the Engine instance and all associated resources. @@ -501,7 +516,7 @@ class UTILS_PUBLIC Engine { * \remark * This method is thread-safe. */ - static void destroy(Engine* engine); + static void destroy(Engine* UTILS_NULLABLE engine); /** * Query the feature level supported by the selected backend. @@ -649,11 +664,11 @@ class UTILS_PUBLIC Engine { * `ANativeWindow*`. * @param flags One or more configuration flags as defined in `SwapChain`. * - * @return A pointer to the newly created SwapChain or nullptr if it couldn't be created. + * @return A pointer to the newly created SwapChain. * * @see Renderer.beginFrame() */ - SwapChain* createSwapChain(void* nativeWindow, uint64_t flags = 0) noexcept; + SwapChain* UTILS_NONNULL createSwapChain(void* UTILS_NULLABLE nativeWindow, uint64_t flags = 0) noexcept; /** @@ -663,42 +678,42 @@ class UTILS_PUBLIC Engine { * @param height Height of the drawing buffer in pixels. * @param flags One or more configuration flags as defined in `SwapChain`. * - * @return A pointer to the newly created SwapChain or nullptr if it couldn't be created. + * @return A pointer to the newly created SwapChain. * * @see Renderer.beginFrame() */ - SwapChain* createSwapChain(uint32_t width, uint32_t height, uint64_t flags = 0) noexcept; + SwapChain* UTILS_NONNULL createSwapChain(uint32_t width, uint32_t height, uint64_t flags = 0) noexcept; /** * Creates a renderer associated to this engine. * * A Renderer is intended to map to a *window* on screen. * - * @return A pointer to the newly created Renderer or nullptr if it couldn't be created. + * @return A pointer to the newly created Renderer. */ - Renderer* createRenderer() noexcept; + Renderer* UTILS_NONNULL createRenderer() noexcept; /** * Creates a View. * - * @return A pointer to the newly created View or nullptr if it couldn't be created. + * @return A pointer to the newly created View. */ - View* createView() noexcept; + View* UTILS_NONNULL createView() noexcept; /** * Creates a Scene. * - * @return A pointer to the newly created Scene or nullptr if it couldn't be created. + * @return A pointer to the newly created Scene. */ - Scene* createScene() noexcept; + Scene* UTILS_NONNULL createScene() noexcept; /** * Creates a Camera component. * * @param entity Entity to add the camera component to. - * @return A pointer to the newly created Camera or nullptr if it couldn't be created. + * @return A pointer to the newly created Camera. */ - Camera* createCamera(utils::Entity entity) noexcept; + Camera* UTILS_NONNULL createCamera(utils::Entity entity) noexcept; /** * Returns the Camera component of the given entity. @@ -708,7 +723,7 @@ class UTILS_PUBLIC Engine { * have a Camera component. The pointer is valid until destroyCameraComponent() * is called or the entity itself is destroyed. */ - Camera* getCameraComponent(utils::Entity entity) noexcept; + Camera* UTILS_NULLABLE getCameraComponent(utils::Entity entity) noexcept; /** * Destroys the Camera component associated with the given entity. @@ -720,17 +735,17 @@ class UTILS_PUBLIC Engine { /** * Creates a Fence. * - * @return A pointer to the newly created Fence or nullptr if it couldn't be created. + * @return A pointer to the newly created Fence. */ - Fence* createFence() noexcept; + Fence* UTILS_NONNULL createFence() noexcept; - bool destroy(const BufferObject* p); //!< Destroys a BufferObject object. - bool destroy(const VertexBuffer* p); //!< Destroys an VertexBuffer object. - bool destroy(const Fence* p); //!< Destroys a Fence object. - bool destroy(const IndexBuffer* p); //!< Destroys an IndexBuffer object. - bool destroy(const SkinningBuffer* p); //!< Destroys a SkinningBuffer object. - bool destroy(const MorphTargetBuffer* p); //!< Destroys a MorphTargetBuffer object. - bool destroy(const IndirectLight* p); //!< Destroys an IndirectLight object. + bool destroy(const BufferObject* UTILS_NULLABLE p); //!< Destroys a BufferObject object. + bool destroy(const VertexBuffer* UTILS_NULLABLE p); //!< Destroys an VertexBuffer object. + bool destroy(const Fence* UTILS_NULLABLE p); //!< Destroys a Fence object. + bool destroy(const IndexBuffer* UTILS_NULLABLE p); //!< Destroys an IndexBuffer object. + bool destroy(const SkinningBuffer* UTILS_NULLABLE p); //!< Destroys a SkinningBuffer object. + bool destroy(const MorphTargetBuffer* UTILS_NULLABLE p); //!< Destroys a MorphTargetBuffer object. + bool destroy(const IndirectLight* UTILS_NULLABLE p); //!< Destroys an IndirectLight object. /** * Destroys a Material object @@ -740,38 +755,38 @@ class UTILS_PUBLIC Engine { * @exception utils::PreConditionPanic is thrown if some MaterialInstances remain. * no-op if exceptions are disabled and some MaterialInstances remain. */ - bool destroy(const Material* p); - bool destroy(const MaterialInstance* p); //!< Destroys a MaterialInstance object. - bool destroy(const Renderer* p); //!< Destroys a Renderer object. - bool destroy(const Scene* p); //!< Destroys a Scene object. - bool destroy(const Skybox* p); //!< Destroys a SkyBox object. - bool destroy(const ColorGrading* p); //!< Destroys a ColorGrading object. - bool destroy(const SwapChain* p); //!< Destroys a SwapChain object. - bool destroy(const Stream* p); //!< Destroys a Stream object. - bool destroy(const Texture* p); //!< Destroys a Texture object. - bool destroy(const RenderTarget* p); //!< Destroys a RenderTarget object. - bool destroy(const View* p); //!< Destroys a View object. - bool destroy(const InstanceBuffer* p); //!< Destroys an InstanceBuffer object. - void destroy(utils::Entity e); //!< Destroys all filament-known components from this entity - - bool isValid(const BufferObject* p); //!< Tells whether a BufferObject object is valid - bool isValid(const VertexBuffer* p); //!< Tells whether an VertexBuffer object is valid - bool isValid(const Fence* p); //!< Tells whether a Fence object is valid - bool isValid(const IndexBuffer* p); //!< Tells whether an IndexBuffer object is valid - bool isValid(const SkinningBuffer* p); //!< Tells whether a SkinningBuffer object is valid - bool isValid(const MorphTargetBuffer* p); //!< Tells whether a MorphTargetBuffer object is valid - bool isValid(const IndirectLight* p); //!< Tells whether an IndirectLight object is valid - bool isValid(const Material* p); //!< Tells whether an IndirectLight object is valid - bool isValid(const Renderer* p); //!< Tells whether a Renderer object is valid - bool isValid(const Scene* p); //!< Tells whether a Scene object is valid - bool isValid(const Skybox* p); //!< Tells whether a SkyBox object is valid - bool isValid(const ColorGrading* p); //!< Tells whether a ColorGrading object is valid - bool isValid(const SwapChain* p); //!< Tells whether a SwapChain object is valid - bool isValid(const Stream* p); //!< Tells whether a Stream object is valid - bool isValid(const Texture* p); //!< Tells whether a Texture object is valid - bool isValid(const RenderTarget* p); //!< Tells whether a RenderTarget object is valid - bool isValid(const View* p); //!< Tells whether a View object is valid - bool isValid(const InstanceBuffer* p); //!< Tells whether an InstanceBuffer object is valid + bool destroy(const Material* UTILS_NULLABLE p); + bool destroy(const MaterialInstance* UTILS_NULLABLE p); //!< Destroys a MaterialInstance object. + bool destroy(const Renderer* UTILS_NULLABLE p); //!< Destroys a Renderer object. + bool destroy(const Scene* UTILS_NULLABLE p); //!< Destroys a Scene object. + bool destroy(const Skybox* UTILS_NULLABLE p); //!< Destroys a SkyBox object. + bool destroy(const ColorGrading* UTILS_NULLABLE p); //!< Destroys a ColorGrading object. + bool destroy(const SwapChain* UTILS_NULLABLE p); //!< Destroys a SwapChain object. + bool destroy(const Stream* UTILS_NULLABLE p); //!< Destroys a Stream object. + bool destroy(const Texture* UTILS_NULLABLE p); //!< Destroys a Texture object. + bool destroy(const RenderTarget* UTILS_NULLABLE p); //!< Destroys a RenderTarget object. + bool destroy(const View* UTILS_NULLABLE p); //!< Destroys a View object. + bool destroy(const InstanceBuffer* UTILS_NULLABLE p); //!< Destroys an InstanceBuffer object. + void destroy(utils::Entity e); //!< Destroys all filament-known components from this entity + + bool isValid(const BufferObject* UTILS_NULLABLE p); //!< Tells whether a BufferObject object is valid + bool isValid(const VertexBuffer* UTILS_NULLABLE p); //!< Tells whether an VertexBuffer object is valid + bool isValid(const Fence* UTILS_NULLABLE p); //!< Tells whether a Fence object is valid + bool isValid(const IndexBuffer* UTILS_NULLABLE p); //!< Tells whether an IndexBuffer object is valid + bool isValid(const SkinningBuffer* UTILS_NULLABLE p); //!< Tells whether a SkinningBuffer object is valid + bool isValid(const MorphTargetBuffer* UTILS_NULLABLE p); //!< Tells whether a MorphTargetBuffer object is valid + bool isValid(const IndirectLight* UTILS_NULLABLE p); //!< Tells whether an IndirectLight object is valid + bool isValid(const Material* UTILS_NULLABLE p); //!< Tells whether an IndirectLight object is valid + bool isValid(const Renderer* UTILS_NULLABLE p); //!< Tells whether a Renderer object is valid + bool isValid(const Scene* UTILS_NULLABLE p); //!< Tells whether a Scene object is valid + bool isValid(const Skybox* UTILS_NULLABLE p); //!< Tells whether a SkyBox object is valid + bool isValid(const ColorGrading* UTILS_NULLABLE p); //!< Tells whether a ColorGrading object is valid + bool isValid(const SwapChain* UTILS_NULLABLE p); //!< Tells whether a SwapChain object is valid + bool isValid(const Stream* UTILS_NULLABLE p); //!< Tells whether a Stream object is valid + bool isValid(const Texture* UTILS_NULLABLE p); //!< Tells whether a Texture object is valid + bool isValid(const RenderTarget* UTILS_NULLABLE p); //!< Tells whether a RenderTarget object is valid + bool isValid(const View* UTILS_NULLABLE p); //!< Tells whether a View object is valid + bool isValid(const InstanceBuffer* UTILS_NULLABLE p); //!< Tells whether an InstanceBuffer object is valid /** * Kicks the hardware thread (e.g. the OpenGL, Vulkan or Metal thread) and blocks until @@ -811,7 +826,7 @@ class UTILS_PUBLIC Engine { * * @return A pointer to the default Material instance (a singleton). */ - const Material* getDefaultMaterial() const noexcept; + Material const* UTILS_NONNULL getDefaultMaterial() const noexcept; /** * Returns the resolved backend. @@ -842,7 +857,7 @@ class UTILS_PUBLIC Engine { * @return A pointer to the Platform object that was provided to Engine::create, or the * Filament-created one. */ - Platform* getPlatform() const noexcept; + Platform* UTILS_NULLABLE getPlatform() const noexcept; /** * Allocate a small amount of memory directly in the command stream. The allocated memory is @@ -855,7 +870,7 @@ class UTILS_PUBLIC Engine { * @note there is no need to destroy this buffer, it will be freed automatically when * the current command buffer is executed. */ - void* streamAlloc(size_t size, size_t alignment = alignof(double)) noexcept; + void* UTILS_NULLABLE streamAlloc(size_t size, size_t alignment = alignof(double)) noexcept; /** * Invokes one iteration of the render loop, used only on single-threaded platforms. diff --git a/filament/include/filament/Fence.h b/filament/include/filament/Fence.h index fa0de519abb..673d12cdb92 100644 --- a/filament/include/filament/Fence.h +++ b/filament/include/filament/Fence.h @@ -76,7 +76,7 @@ class UTILS_PUBLIC Fence : public FilamentAPI { * @return FenceStatus::CONDITION_SATISFIED on success, * FenceStatus::ERROR otherwise. */ - static FenceStatus waitAndDestroy(Fence* fence, Mode mode = Mode::FLUSH); + static FenceStatus waitAndDestroy(Fence* UTILS_NONNULL fence, Mode mode = Mode::FLUSH); protected: // prevent heap allocation diff --git a/filament/include/filament/Frustum.h b/filament/include/filament/Frustum.h index f9936d48a57..ceec55eb823 100644 --- a/filament/include/filament/Frustum.h +++ b/filament/include/filament/Frustum.h @@ -79,14 +79,14 @@ class UTILS_PUBLIC Frustum { * @param planes six plane equations encoded as in getNormalizedPlane() in * left, right, bottom, top, far, near order */ - void getNormalizedPlanes(math::float4 planes[6]) const noexcept; + void getNormalizedPlanes(math::float4 planes[UTILS_NONNULL 6]) const noexcept; /** * Returns all six frustum planes in left, right, bottom, top, far, near order * @return six plane equations encoded as in getNormalizedPlane() in * left, right, bottom, top, far, near order */ - math::float4 const* getNormalizedPlanes() const noexcept { return mPlanes; } + math::float4 const* UTILS_NONNULL getNormalizedPlanes() const noexcept { return mPlanes; } /** * Returns whether a box intersects the frustum (i.e. is visible) diff --git a/filament/include/filament/IndexBuffer.h b/filament/include/filament/IndexBuffer.h index 5218e93c292..35b8a10ef26 100644 --- a/filament/include/filament/IndexBuffer.h +++ b/filament/include/filament/IndexBuffer.h @@ -89,8 +89,7 @@ class UTILS_PUBLIC IndexBuffer : public FilamentAPI { * * @param engine Reference to the filament::Engine to associate this IndexBuffer with. * - * @return pointer to the newly created object or nullptr if exceptions are disabled and - * an error occurred. + * @return pointer to the newly created object. * * @exception utils::PostConditionPanic if a runtime error occurred, such as running out of * memory or other resources. @@ -98,7 +97,7 @@ class UTILS_PUBLIC IndexBuffer : public FilamentAPI { * * @see IndexBuffer::setBuffer */ - IndexBuffer* build(Engine& engine); + IndexBuffer* UTILS_NONNULL build(Engine& engine); private: friend class FIndexBuffer; }; diff --git a/filament/include/filament/IndirectLight.h b/filament/include/filament/IndirectLight.h index 0021dbe0cd9..c230dac8fe6 100644 --- a/filament/include/filament/IndirectLight.h +++ b/filament/include/filament/IndirectLight.h @@ -116,7 +116,7 @@ class UTILS_PUBLIC IndirectLight : public FilamentAPI { * @return This Builder, for chaining calls. * */ - Builder& reflections(Texture const* cubemap) noexcept; + Builder& reflections(Texture const* UTILS_NULLABLE cubemap) noexcept; /** * Sets the irradiance as Spherical Harmonics. @@ -162,7 +162,7 @@ class UTILS_PUBLIC IndirectLight : public FilamentAPI { * Because the coefficients are pre-scaled, `sh[0]` is the environment's * average irradiance. */ - Builder& irradiance(uint8_t bands, math::float3 const* sh) noexcept; + Builder& irradiance(uint8_t bands, math::float3 const* UTILS_NONNULL sh) noexcept; /** * Sets the irradiance from the radiance expressed as Spherical Harmonics. @@ -194,7 +194,7 @@ class UTILS_PUBLIC IndirectLight : public FilamentAPI { * * @return This Builder, for chaining calls. */ - Builder& radiance(uint8_t bands, math::float3 const* sh) noexcept; + Builder& radiance(uint8_t bands, math::float3 const* UTILS_NONNULL sh) noexcept; /** * Sets the irradiance as a cubemap. @@ -213,7 +213,7 @@ class UTILS_PUBLIC IndirectLight : public FilamentAPI { * * @see irradiance(uint8_t bands, math::float3 const* sh) */ - Builder& irradiance(Texture const* cubemap) noexcept; + Builder& irradiance(Texture const* UTILS_NULLABLE cubemap) noexcept; /** * (optional) Environment intensity. @@ -249,7 +249,7 @@ class UTILS_PUBLIC IndirectLight : public FilamentAPI { * memory or other resources. * @exception utils::PreConditionPanic if a parameter to a builder function was invalid. */ - IndirectLight* build(Engine& engine); + IndirectLight* UTILS_NONNULL build(Engine& engine); private: friend class FIndirectLight; @@ -286,12 +286,12 @@ class UTILS_PUBLIC IndirectLight : public FilamentAPI { /** * Returns the associated reflection map, or null if it does not exist. */ - Texture const* getReflectionsTexture() const noexcept; + Texture const* UTILS_NULLABLE getReflectionsTexture() const noexcept; /** * Returns the associated irradiance map, or null if it does not exist. */ - Texture const* getIrradianceTexture() const noexcept; + Texture const* UTILS_NULLABLE getIrradianceTexture() const noexcept; /** * Helper to estimate the direction of the dominant light in the environment represented by @@ -314,7 +314,7 @@ class UTILS_PUBLIC IndirectLight : public FilamentAPI { * @see LightManager::Builder::direction() * @see getColorEstimate() */ - static math::float3 getDirectionEstimate(const math::float3 sh[9]) noexcept; + static math::float3 getDirectionEstimate(const math::float3 sh[UTILS_NONNULL 9]) noexcept; /** * Helper to estimate the color and relative intensity of the environment represented by @@ -334,7 +334,8 @@ class UTILS_PUBLIC IndirectLight : public FilamentAPI { * @see LightManager::Builder::intensity() * @see getDirectionEstimate, getIntensity, setIntensity */ - static math::float4 getColorEstimate(const math::float3 sh[9], math::float3 direction) noexcept; + static math::float4 getColorEstimate(const math::float3 sh[UTILS_NONNULL 9], + math::float3 direction) noexcept; /** @deprecated use static versions instead */ diff --git a/filament/include/filament/InstanceBuffer.h b/filament/include/filament/InstanceBuffer.h index b32cac53c50..2135152d883 100644 --- a/filament/include/filament/InstanceBuffer.h +++ b/filament/include/filament/InstanceBuffer.h @@ -68,12 +68,12 @@ class UTILS_PUBLIC InstanceBuffer : public FilamentAPI { * @param localTransforms an array of math::mat4f with length instanceCount, must remain * valid until after build() is called */ - Builder& localTransforms(math::mat4f const* localTransforms) noexcept; + Builder& localTransforms(math::mat4f const* UTILS_NULLABLE localTransforms) noexcept; /** * Creates the InstanceBuffer object and returns a pointer to it. */ - InstanceBuffer* build(Engine& engine); + InstanceBuffer* UTILS_NONNULL build(Engine& engine); private: friend class FInstanceBuffer; @@ -93,7 +93,8 @@ class UTILS_PUBLIC InstanceBuffer : public FilamentAPI { * @param count the number of local transforms * @param offset index of the first instance to set local transforms */ - void setLocalTransforms(math::mat4f const* localTransforms, size_t count, size_t offset = 0); + void setLocalTransforms(math::mat4f const* UTILS_NONNULL localTransforms, + size_t count, size_t offset = 0); protected: // prevent heap allocation diff --git a/filament/include/filament/LightManager.h b/filament/include/filament/LightManager.h index fd3184bf7cc..22d663f2ea4 100644 --- a/filament/include/filament/LightManager.h +++ b/filament/include/filament/LightManager.h @@ -176,7 +176,7 @@ class UTILS_PUBLIC LightManager : public FilamentAPI { * Retrieve the Entities of all the components of this manager. * @return A list, in no particular order, of all the entities managed by this manager. */ - utils::Entity const* getEntities() const noexcept; + utils::Entity const* UTILS_NONNULL getEntities() const noexcept; /** * Gets an Instance representing the Light component associated with the given Entity. @@ -394,7 +394,7 @@ class UTILS_PUBLIC LightManager : public FilamentAPI { * positions into * @param cascades the number of shadow cascades, at most 4 */ - static void computeUniformSplits(float* splitPositions, uint8_t cascades); + static void computeUniformSplits(float* UTILS_NONNULL splitPositions, uint8_t cascades); /** * Utility method to compute ShadowOptions::cascadeSplitPositions according to a logarithmic @@ -406,7 +406,7 @@ class UTILS_PUBLIC LightManager : public FilamentAPI { * @param near the camera near plane * @param far the camera far plane */ - static void computeLogSplits(float* splitPositions, uint8_t cascades, + static void computeLogSplits(float* UTILS_NONNULL splitPositions, uint8_t cascades, float near, float far); /** @@ -426,7 +426,7 @@ class UTILS_PUBLIC LightManager : public FilamentAPI { * @param lambda a float in the range [0, 1] that interpolates between log and * uniform split schemes */ - static void computePracticalSplits(float* splitPositions, uint8_t cascades, + static void computePracticalSplits(float* UTILS_NONNULL splitPositions, uint8_t cascades, float near, float far, float lambda); }; diff --git a/filament/include/filament/Material.h b/filament/include/filament/Material.h index 15098c81d90..b4b9bbed3e2 100644 --- a/filament/include/filament/Material.h +++ b/filament/include/filament/Material.h @@ -74,7 +74,7 @@ class UTILS_PUBLIC Material : public FilamentAPI { */ struct ParameterInfo { //! Name of the parameter. - const char* name; + const char* UTILS_NONNULL name; //! Whether the parameter is a sampler (texture). bool isSampler; //! Whether the parameter is a subpass type. @@ -110,7 +110,7 @@ class UTILS_PUBLIC Material : public FilamentAPI { * @param payload Pointer to the material data, must stay valid until build() is called. * @param size Size of the material data pointed to by "payload" in bytes. */ - Builder& package(const void* payload, size_t size); + Builder& package(const void* UTILS_NONNULL payload, size_t size); template using is_supported_constant_parameter_t = typename std::enable_if< @@ -132,11 +132,11 @@ class UTILS_PUBLIC Material : public FilamentAPI { * in the material definition. */ template> - Builder& constant(const char* name, size_t nameLength, T value); + Builder& constant(const char* UTILS_NONNULL name, size_t nameLength, T value); /** inline helper to provide the constant name as a null-terminated C string */ template> - inline Builder& constant(const char* name, T value) { + inline Builder& constant(const char* UTILS_NONNULL name, T value) { return constant(name, strlen(name), value); } @@ -152,7 +152,7 @@ class UTILS_PUBLIC Material : public FilamentAPI { * memory or other resources. * @exception utils::PreConditionPanic if a parameter to a builder function was invalid. */ - Material* build(Engine& engine); + Material* UTILS_NULLABLE build(Engine& engine); private: friend class FMaterial; }; @@ -198,22 +198,22 @@ class UTILS_PUBLIC Material : public FilamentAPI { */ void compile(CompilerPriorityQueue priority, UserVariantFilterMask variants, - backend::CallbackHandler* handler = nullptr, - utils::Invocable&& callback = {}) noexcept; + backend::CallbackHandler* UTILS_NULLABLE handler = nullptr, + utils::Invocable&& callback = {}) noexcept; inline void compile(CompilerPriorityQueue priority, UserVariantFilterBit variants, - backend::CallbackHandler* handler = nullptr, - utils::Invocable&& callback = {}) noexcept { + backend::CallbackHandler* UTILS_NULLABLE handler = nullptr, + utils::Invocable&& callback = {}) noexcept { compile(priority, UserVariantFilterMask(variants), handler, - std::forward>(callback)); + std::forward>(callback)); } inline void compile(CompilerPriorityQueue priority, - backend::CallbackHandler* handler = nullptr, - utils::Invocable&& callback = {}) noexcept { + backend::CallbackHandler* UTILS_NULLABLE handler = nullptr, + utils::Invocable&& callback = {}) noexcept { compile(priority, UserVariantFilterBit::ALL, handler, - std::forward>(callback)); + std::forward>(callback)); } /** @@ -225,13 +225,13 @@ class UTILS_PUBLIC Material : public FilamentAPI { * * @return A pointer to the new instance. */ - MaterialInstance* createInstance(const char* name = nullptr) const noexcept; + MaterialInstance* UTILS_NONNULL createInstance(const char* UTILS_NULLABLE name = nullptr) const noexcept; //! Returns the name of this material as a null-terminated string. - const char* getName() const noexcept; + const char* UTILS_NONNULL getName() const noexcept; //! Returns the shading model of this material. - Shading getShading() const noexcept; + Shading getShading() const noexcept; //! Returns the interpolation mode of this material. This affects how variables are interpolated. Interpolation getInterpolation() const noexcept; @@ -317,13 +317,13 @@ class UTILS_PUBLIC Material : public FilamentAPI { * * @return The number of parameters written to the parameters pointer. */ - size_t getParameters(ParameterInfo* parameters, size_t count) const noexcept; + size_t getParameters(ParameterInfo* UTILS_NONNULL parameters, size_t count) const noexcept; //! Indicates whether a parameter of the given name exists on this material. - bool hasParameter(const char* name) const noexcept; + bool hasParameter(const char* UTILS_NONNULL name) const noexcept; //! Indicates whether an existing parameter is a sampler or not. - bool isSampler(const char* name) const noexcept; + bool isSampler(const char* UTILS_NONNULL name) const noexcept; /** * Sets the value of the given parameter on this material's default instance. @@ -334,7 +334,7 @@ class UTILS_PUBLIC Material : public FilamentAPI { * @see getDefaultInstance() */ template - void setDefaultParameter(const char* name, T value) noexcept { + void setDefaultParameter(const char* UTILS_NONNULL name, T value) noexcept { getDefaultInstance()->setParameter(name, value); } @@ -347,8 +347,8 @@ class UTILS_PUBLIC Material : public FilamentAPI { * * @see getDefaultInstance() */ - void setDefaultParameter(const char* name, Texture const* texture, - TextureSampler const& sampler) noexcept { + void setDefaultParameter(const char* UTILS_NONNULL name, + Texture const* UTILS_NULLABLE texture, TextureSampler const& sampler) noexcept { getDefaultInstance()->setParameter(name, texture, sampler); } @@ -361,7 +361,7 @@ class UTILS_PUBLIC Material : public FilamentAPI { * * @see getDefaultInstance() */ - void setDefaultParameter(const char* name, RgbType type, math::float3 color) noexcept { + void setDefaultParameter(const char* UTILS_NONNULL name, RgbType type, math::float3 color) noexcept { getDefaultInstance()->setParameter(name, type, color); } @@ -374,15 +374,15 @@ class UTILS_PUBLIC Material : public FilamentAPI { * * @see getDefaultInstance() */ - void setDefaultParameter(const char* name, RgbaType type, math::float4 color) noexcept { + void setDefaultParameter(const char* UTILS_NONNULL name, RgbaType type, math::float4 color) noexcept { getDefaultInstance()->setParameter(name, type, color); } //! Returns this material's default instance. - MaterialInstance* getDefaultInstance() noexcept; + MaterialInstance* UTILS_NONNULL getDefaultInstance() noexcept; //! Returns this material's default instance. - MaterialInstance const* getDefaultInstance() const noexcept; + MaterialInstance const* UTILS_NONNULL getDefaultInstance() const noexcept; protected: // prevent heap allocation diff --git a/filament/include/filament/MaterialInstance.h b/filament/include/filament/MaterialInstance.h index 913f179ae83..a0edd13554d 100644 --- a/filament/include/filament/MaterialInstance.h +++ b/filament/include/filament/MaterialInstance.h @@ -47,7 +47,7 @@ class UTILS_PUBLIC MaterialInstance : public FilamentAPI { using StringLiteralHelper = const char[N]; struct StringLiteral { - const char* data; + const char* UTILS_NONNULL data; size_t size; template StringLiteral(StringLiteralHelper const& s) noexcept // NOLINT(google-explicit-constructor) @@ -95,17 +95,18 @@ class UTILS_PUBLIC MaterialInstance : public FilamentAPI { * @param name A name for the new MaterialInstance or nullptr to use the template's name * @return A new MaterialInstance */ - static MaterialInstance* duplicate(MaterialInstance const* other, const char* name = nullptr) noexcept; + static MaterialInstance* UTILS_NONNULL duplicate(MaterialInstance const* UTILS_NONNULL other, + const char* UTILS_NULLABLE name = nullptr) noexcept; /** * @return the Material associated with this instance */ - Material const* getMaterial() const noexcept; + Material const* UTILS_NONNULL getMaterial() const noexcept; /** * @return the name associated with this instance */ - const char* getName() const noexcept; + const char* UTILS_NONNULL getName() const noexcept; /** * Set a uniform by name @@ -116,7 +117,7 @@ class UTILS_PUBLIC MaterialInstance : public FilamentAPI { * @throws utils::PreConditionPanic if name doesn't exist or no-op if exceptions are disabled. */ template> - void setParameter(const char* name, size_t nameLength, T const& value); + void setParameter(const char* UTILS_NONNULL name, size_t nameLength, T const& value); /** inline helper to provide the name as a null-terminated string literal */ template> @@ -126,7 +127,7 @@ class UTILS_PUBLIC MaterialInstance : public FilamentAPI { /** inline helper to provide the name as a null-terminated C string */ template> - inline void setParameter(const char* name, T const& value) { + inline void setParameter(const char* UTILS_NONNULL name, T const& value) { setParameter(name, strlen(name), value); } @@ -141,17 +142,19 @@ class UTILS_PUBLIC MaterialInstance : public FilamentAPI { * @throws utils::PreConditionPanic if name doesn't exist or no-op if exceptions are disabled. */ template> - void setParameter(const char* name, size_t nameLength, const T* values, size_t count); + void setParameter(const char* UTILS_NONNULL name, size_t nameLength, + const T* UTILS_NONNULL values, size_t count); /** inline helper to provide the name as a null-terminated string literal */ template> - inline void setParameter(StringLiteral name, const T* values, size_t count) { + inline void setParameter(StringLiteral name, const T* UTILS_NONNULL values, size_t count) { setParameter(name.data, name.size, values, count); } /** inline helper to provide the name as a null-terminated C string */ template> - inline void setParameter(const char* name, const T* values, size_t count) { + inline void setParameter(const char* UTILS_NONNULL name, + const T* UTILS_NONNULL values, size_t count) { setParameter(name, strlen(name), values, count); } @@ -168,18 +171,18 @@ class UTILS_PUBLIC MaterialInstance : public FilamentAPI { * @param sampler Sampler parameters. * @throws utils::PreConditionPanic if name doesn't exist or no-op if exceptions are disabled. */ - void setParameter(const char* name, size_t nameLength, - Texture const* texture, TextureSampler const& sampler); + void setParameter(const char* UTILS_NONNULL name, size_t nameLength, + Texture const* UTILS_NULLABLE 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) { + Texture const* UTILS_NULLABLE 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) { + inline void setParameter(const char* UTILS_NONNULL name, + Texture const* UTILS_NULLABLE texture, TextureSampler const& sampler) { setParameter(name, strlen(name), texture, sampler); } @@ -194,7 +197,8 @@ class UTILS_PUBLIC MaterialInstance : public FilamentAPI { * @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, size_t nameLength, RgbType type, math::float3 color); + void setParameter(const char* UTILS_NONNULL 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) { @@ -202,7 +206,7 @@ class UTILS_PUBLIC MaterialInstance : public FilamentAPI { } /** inline helper to provide the name as a null-terminated C string */ - inline void setParameter(const char* name, RgbType type, math::float3 color) { + inline void setParameter(const char* UTILS_NONNULL name, RgbType type, math::float3 color) { setParameter(name, strlen(name), type, color); } @@ -217,7 +221,8 @@ class UTILS_PUBLIC MaterialInstance : public FilamentAPI { * @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, size_t nameLength, RgbaType type, math::float4 color); + void setParameter(const char* UTILS_NONNULL 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) { @@ -225,7 +230,7 @@ class UTILS_PUBLIC MaterialInstance : public FilamentAPI { } /** inline helper to provide the name as a null-terminated C string */ - inline void setParameter(const char* name, RgbaType type, math::float4 color) { + inline void setParameter(const char* UTILS_NONNULL name, RgbaType type, math::float4 color) { setParameter(name, strlen(name), type, color); } diff --git a/filament/include/filament/MorphTargetBuffer.h b/filament/include/filament/MorphTargetBuffer.h index 24e28b80ee2..655bb8d848d 100644 --- a/filament/include/filament/MorphTargetBuffer.h +++ b/filament/include/filament/MorphTargetBuffer.h @@ -68,14 +68,13 @@ class UTILS_PUBLIC MorphTargetBuffer : public FilamentAPI { * * @param engine Reference to the filament::Engine to associate this MorphTargetBuffer with. * - * @return pointer to the newly created object or nullptr if exceptions are disabled and - * an error occurred. + * @return pointer to the newly created object. * * @exception utils::PostConditionPanic if a runtime error occurred, such as running out of * memory or other resources. * @exception utils::PreConditionPanic if a parameter to a builder function was invalid. */ - MorphTargetBuffer* build(Engine& engine); + MorphTargetBuffer* UTILS_NONNULL build(Engine& engine); private: friend class FMorphTargetBuffer; }; @@ -95,7 +94,7 @@ class UTILS_PUBLIC MorphTargetBuffer : public FilamentAPI { * @see setTangentsAt */ void setPositionsAt(Engine& engine, size_t targetIndex, - math::float3 const* positions, size_t count, size_t offset = 0); + math::float3 const* UTILS_NONNULL positions, size_t count, size_t offset = 0); /** * Updates positions for the given morph target. @@ -110,7 +109,7 @@ class UTILS_PUBLIC MorphTargetBuffer : public FilamentAPI { * @see setTangentsAt */ void setPositionsAt(Engine& engine, size_t targetIndex, - math::float4 const* positions, size_t count, size_t offset = 0); + math::float4 const* UTILS_NONNULL positions, size_t count, size_t offset = 0); /** * Updates tangents for the given morph target. @@ -126,7 +125,7 @@ class UTILS_PUBLIC MorphTargetBuffer : public FilamentAPI { * @see setPositionsAt */ void setTangentsAt(Engine& engine, size_t targetIndex, - math::short4 const* tangents, size_t count, size_t offset = 0); + math::short4 const* UTILS_NONNULL tangents, size_t count, size_t offset = 0); /** * Returns the vertex count of this MorphTargetBuffer. diff --git a/filament/include/filament/RenderTarget.h b/filament/include/filament/RenderTarget.h index bf70d03a25e..fc76111da74 100644 --- a/filament/include/filament/RenderTarget.h +++ b/filament/include/filament/RenderTarget.h @@ -106,7 +106,7 @@ class UTILS_PUBLIC RenderTarget : public FilamentAPI { * @param texture The associated texture object. * @return A reference to this Builder for chaining calls. */ - Builder& texture(AttachmentPoint attachment, Texture* texture) noexcept; + Builder& texture(AttachmentPoint attachment, Texture* UTILS_NULLABLE texture) noexcept; /** * Sets the mipmap level for a given attachment point. @@ -138,10 +138,9 @@ class UTILS_PUBLIC RenderTarget : public FilamentAPI { /** * Creates the RenderTarget object and returns a pointer to it. * - * @return pointer to the newly created object or nullptr if exceptions are disabled and - * an error occurred. + * @return pointer to the newly created object. */ - RenderTarget* build(Engine& engine); + RenderTarget* UTILS_NONNULL build(Engine& engine); private: friend class FRenderTarget; @@ -152,7 +151,7 @@ class UTILS_PUBLIC RenderTarget : public FilamentAPI { * @param attachment Attachment point * @return A Texture object or nullptr if no texture is set for this attachment point */ - Texture* getTexture(AttachmentPoint attachment) const noexcept; + Texture* UTILS_NULLABLE getTexture(AttachmentPoint attachment) const noexcept; /** * Returns the mipmap level set on the given attachment point diff --git a/filament/include/filament/RenderableManager.h b/filament/include/filament/RenderableManager.h index 75b9d95015e..6024fd2e599 100644 --- a/filament/include/filament/RenderableManager.h +++ b/filament/include/filament/RenderableManager.h @@ -129,7 +129,7 @@ class UTILS_PUBLIC RenderableManager : public FilamentAPI { * Retrieve the Entities of all the components of this manager. * @return A list, in no particular order, of all the entities managed by this manager. */ - utils::Entity const* getEntities() const noexcept; + utils::Entity const* UTILS_NONNULL getEntities() const noexcept; /** * The transformation associated with a skinning joint. @@ -190,9 +190,19 @@ class UTILS_PUBLIC RenderableManager : public FilamentAPI { * @param maxIndex specifies the maximum index contained in the index buffer * @param count number of indices to read (for triangles, this should be a multiple of 3) */ - Builder& geometry(size_t index, PrimitiveType type, VertexBuffer* vertices, IndexBuffer* indices, size_t offset, size_t minIndex, size_t maxIndex, size_t count) noexcept; - Builder& geometry(size_t index, PrimitiveType type, VertexBuffer* vertices, IndexBuffer* indices, size_t offset, size_t count) noexcept; //!< \overload - Builder& geometry(size_t index, PrimitiveType type, VertexBuffer* vertices, IndexBuffer* indices) noexcept; //!< \overload + Builder& geometry(size_t index, PrimitiveType type, + VertexBuffer* UTILS_NONNULL vertices, + IndexBuffer* UTILS_NONNULL indices, + size_t offset, size_t minIndex, size_t maxIndex, size_t count) noexcept; + + Builder& geometry(size_t index, PrimitiveType type, + VertexBuffer* UTILS_NONNULL vertices, + IndexBuffer* UTILS_NONNULL indices, + size_t offset, size_t count) noexcept; //!< \overload + + Builder& geometry(size_t index, PrimitiveType type, + VertexBuffer* UTILS_NONNULL vertices, + IndexBuffer* UTILS_NONNULL indices) noexcept; //!< \overload /** * Binds a material instance to the specified primitive. @@ -209,7 +219,8 @@ class UTILS_PUBLIC RenderableManager : public FilamentAPI { * * @see Engine::setActiveFeatureLevel */ - Builder& material(size_t index, MaterialInstance const* materialInstance) noexcept; + Builder& material(size_t index, + MaterialInstance const* UTILS_NONNULL materialInstance) noexcept; /** * The axis-aligned bounding box of the renderable. @@ -357,7 +368,8 @@ class UTILS_PUBLIC RenderableManager : public FilamentAPI { * @param count 0 to disable, otherwise the number of bone transforms (up to 255) * @param offset offset in the SkinningBuffer */ - Builder& skinning(SkinningBuffer* skinningBuffer, size_t count, size_t offset) noexcept; + Builder& skinning(SkinningBuffer* UTILS_NONNULL skinningBuffer, + size_t count, size_t offset) noexcept; /** @@ -375,8 +387,8 @@ class UTILS_PUBLIC RenderableManager : public FilamentAPI { * @param boneCount 0 to disable, otherwise the number of bone transforms (up to 255) * @param transforms the initial set of transforms (one for each bone) */ - Builder& skinning(size_t boneCount, math::mat4f const* transforms) noexcept; - Builder& skinning(size_t boneCount, Bone const* bones) noexcept; //!< \overload + Builder& skinning(size_t boneCount, math::mat4f const* UTILS_NONNULL transforms) noexcept; + Builder& skinning(size_t boneCount, Bone const* UTILS_NONNULL bones) noexcept; //!< \overload Builder& skinning(size_t boneCount) noexcept; //!< \overload /** @@ -405,7 +417,8 @@ class UTILS_PUBLIC RenderableManager : public FilamentAPI { * @see VertexBuffer:Builder:advancedSkinning */ Builder& boneIndicesAndWeights(size_t primitiveIndex, - math::float2 const* indicesAndWeights, size_t count, size_t bonesPerVertex) noexcept; + math::float2 const* UTILS_NONNULL indicesAndWeights, + size_t count, size_t bonesPerVertex) noexcept; /** * Define bone indices and weights "pairs" for vertex skinning as a float2. @@ -468,10 +481,11 @@ class UTILS_PUBLIC RenderableManager : public FilamentAPI { * @param count number of vertices in the morph target buffer to read, must equal the geometry's count (for triangles, this should be a multiple of 3) */ Builder& morphing(uint8_t level, size_t primitiveIndex, - MorphTargetBuffer* morphTargetBuffer, size_t offset, size_t count) noexcept; + MorphTargetBuffer* UTILS_NONNULL morphTargetBuffer, + size_t offset, size_t count) noexcept; inline Builder& morphing(uint8_t level, size_t primitiveIndex, - MorphTargetBuffer* morphTargetBuffer) noexcept; + MorphTargetBuffer* UTILS_NONNULL morphTargetBuffer) noexcept; /** * Sets the drawing order for blended primitives. The drawing order is either global or @@ -538,7 +552,8 @@ class UTILS_PUBLIC RenderableManager : public FilamentAPI { * the result of Engine::getMaxAutomaticInstances(). * @param instanceBuffer an InstanceBuffer containing at least instanceCount transforms */ - Builder& instances(size_t instanceCount, InstanceBuffer* instanceBuffer) noexcept; + Builder& instances(size_t instanceCount, + InstanceBuffer* UTILS_NONNULL instanceBuffer) noexcept; /** * Adds the Renderable component to an entity. @@ -565,18 +580,18 @@ class UTILS_PUBLIC RenderableManager : public FilamentAPI { friend class FRenderPrimitive; friend class FRenderableManager; struct Entry { - VertexBuffer* vertices = nullptr; - IndexBuffer* indices = nullptr; + VertexBuffer* UTILS_NULLABLE vertices = nullptr; + IndexBuffer* UTILS_NULLABLE indices = nullptr; size_t offset = 0; size_t minIndex = 0; size_t maxIndex = 0; size_t count = 0; - MaterialInstance const* materialInstance = nullptr; + MaterialInstance const* UTILS_NULLABLE materialInstance = nullptr; PrimitiveType type = PrimitiveType::TRIANGLES; uint16_t blendOrder = 0; bool globalBlendOrderEnabled = false; struct { - MorphTargetBuffer* buffer = nullptr; + MorphTargetBuffer* UTILS_NULLABLE buffer = nullptr; size_t offset = 0; size_t count = 0; } morphing; @@ -694,8 +709,11 @@ class UTILS_PUBLIC RenderableManager : public FilamentAPI { * Updates the bone transforms in the range [offset, offset + boneCount). * The bones must be pre-allocated using Builder::skinning(). */ - void setBones(Instance instance, Bone const* transforms, size_t boneCount = 1, size_t offset = 0); - void setBones(Instance instance, math::mat4f const* transforms, size_t boneCount = 1, size_t offset = 0); //!< \overload + void setBones(Instance instance, Bone const* UTILS_NONNULL transforms, + size_t boneCount = 1, size_t offset = 0); + + void setBones(Instance instance, math::mat4f const* UTILS_NONNULL transforms, + size_t boneCount = 1, size_t offset = 0); //!< \overload /** * Associates a region of a SkinningBuffer to a renderable instance @@ -708,7 +726,7 @@ class UTILS_PUBLIC RenderableManager : public FilamentAPI { * @param count Size of the region in bones, must be smaller or equal to 256. * @param offset Start offset of the region in bones */ - void setSkinningBuffer(Instance instance, SkinningBuffer* skinningBuffer, + void setSkinningBuffer(Instance instance, SkinningBuffer* UTILS_NONNULL skinningBuffer, size_t count, size_t offset); /** @@ -723,24 +741,25 @@ class UTILS_PUBLIC RenderableManager : public FilamentAPI { * @param offset Index of the first morph target weight to set at instance. */ void setMorphWeights(Instance instance, - float const* weights, size_t count, size_t offset = 0); + float const* UTILS_NONNULL weights, size_t count, size_t offset = 0); /** * Associates a MorphTargetBuffer to the given primitive. */ void setMorphTargetBufferAt(Instance instance, uint8_t level, size_t primitiveIndex, - MorphTargetBuffer* morphTargetBuffer, size_t offset, size_t count); + MorphTargetBuffer* UTILS_NONNULL morphTargetBuffer, size_t offset, size_t count); /** * Utility method to change a MorphTargetBuffer to the given primitive */ inline void setMorphTargetBufferAt(Instance instance, uint8_t level, size_t primitiveIndex, - MorphTargetBuffer* morphTargetBuffer); + MorphTargetBuffer* UTILS_NONNULL 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; + MorphTargetBuffer* UTILS_NULLABLE getMorphTargetBufferAt(Instance instance, + uint8_t level, size_t primitiveIndex) const noexcept; /** * Gets the number of morphing in the given entity. @@ -782,20 +801,22 @@ class UTILS_PUBLIC RenderableManager : public FilamentAPI { * @see Engine::setActiveFeatureLevel */ void setMaterialInstanceAt(Instance instance, - size_t primitiveIndex, MaterialInstance const* materialInstance); + size_t primitiveIndex, MaterialInstance const* UTILS_NONNULL materialInstance); /** * Retrieves the material instance that is bound to the given primitive. */ - MaterialInstance* getMaterialInstanceAt(Instance instance, size_t primitiveIndex) const noexcept; + MaterialInstance* UTILS_NULLABLE getMaterialInstanceAt( + Instance instance, size_t primitiveIndex) const noexcept; /** * Changes the geometry for the given primitive. * * \see Builder::geometry() */ - void setGeometryAt(Instance instance, size_t primitiveIndex, - PrimitiveType type, VertexBuffer* vertices, IndexBuffer* indices, + void setGeometryAt(Instance instance, size_t primitiveIndex, PrimitiveType type, + VertexBuffer* UTILS_NONNULL vertices, + IndexBuffer* UTILS_NONNULL indices, size_t offset, size_t count) noexcept; /** @@ -856,7 +877,9 @@ class UTILS_PUBLIC RenderableManager : public FilamentAPI { template::type, typename = typename is_supported_index_type::type> - static Box computeAABB(VECTOR const* vertices, INDEX const* indices, size_t count, + static Box computeAABB( + VECTOR const* UTILS_NONNULL vertices, + INDEX const* UTILS_NONNULL indices, size_t count, size_t stride = sizeof(VECTOR)) noexcept; protected: @@ -864,21 +887,25 @@ class UTILS_PUBLIC RenderableManager : public FilamentAPI { ~RenderableManager() = default; }; -RenderableManager::Builder& RenderableManager::Builder::morphing(uint8_t level, size_t primitiveIndex, - MorphTargetBuffer* morphTargetBuffer) noexcept { +RenderableManager::Builder& RenderableManager::Builder::morphing( + uint8_t level, size_t primitiveIndex, + MorphTargetBuffer* UTILS_NONNULL morphTargetBuffer) noexcept { return morphing(level, primitiveIndex, morphTargetBuffer, 0, morphTargetBuffer->getVertexCount()); } -void RenderableManager::setMorphTargetBufferAt(Instance instance, uint8_t level, size_t primitiveIndex, - MorphTargetBuffer* morphTargetBuffer) { +void RenderableManager::setMorphTargetBufferAt( + Instance instance, uint8_t level, size_t primitiveIndex, + MorphTargetBuffer* UTILS_NONNULL morphTargetBuffer) { setMorphTargetBufferAt(instance, level, primitiveIndex, morphTargetBuffer, 0, morphTargetBuffer->getVertexCount()); } template -Box RenderableManager::computeAABB(VECTOR const* vertices, INDEX const* indices, size_t count, - size_t stride) noexcept { +Box RenderableManager::computeAABB( + VECTOR const* UTILS_NONNULL vertices, + INDEX const* UTILS_NONNULL indices, + size_t count, size_t stride) noexcept { math::float3 bmin(FLT_MAX); math::float3 bmax(-FLT_MAX); for (size_t i = 0; i < count; ++i) { diff --git a/filament/include/filament/Renderer.h b/filament/include/filament/Renderer.h index 8b7fb28bdce..fdc291b1fd1 100644 --- a/filament/include/filament/Renderer.h +++ b/filament/include/filament/Renderer.h @@ -181,14 +181,14 @@ class UTILS_PUBLIC Renderer : public FilamentAPI { * * @return A pointer to the Engine instance this Renderer is associated to. */ - Engine* getEngine() noexcept; + Engine* UTILS_NONNULL getEngine() noexcept; /** * Get the Engine that created this Renderer. * * @return A constant pointer to the Engine instance this Renderer is associated to. */ - inline Engine const* getEngine() const noexcept { + inline Engine const* UTILS_NONNULL getEngine() const noexcept { return const_cast(this)->getEngine(); } @@ -264,7 +264,7 @@ class UTILS_PUBLIC Renderer : public FilamentAPI { * @see * endFrame() */ - bool beginFrame(SwapChain* swapChain, + bool beginFrame(SwapChain* UTILS_NONNULL swapChain, uint64_t vsyncSteadyClockTimeNano = 0u); /** @@ -335,7 +335,7 @@ class UTILS_PUBLIC Renderer : public FilamentAPI { * beginFrame(), endFrame(), View * */ - void render(View const* view); + void render(View const* UTILS_NONNULL view); /** * Copy the currently rendered view to the indicated swap chain, using the @@ -350,7 +350,7 @@ class UTILS_PUBLIC Renderer : public FilamentAPI { * copyFrame() should be called after a frame is rendered using render() * but before endFrame() is called. */ - void copyFrame(SwapChain* dstSwapChain, Viewport const& dstViewport, + void copyFrame(SwapChain* UTILS_NONNULL dstSwapChain, Viewport const& dstViewport, Viewport const& srcViewport, uint32_t flags = 0); /** @@ -490,7 +490,7 @@ class UTILS_PUBLIC Renderer : public FilamentAPI { * readPixels() is intended for debugging and testing. It will impact performance significantly. * */ - void readPixels(RenderTarget* renderTarget, + void readPixels(RenderTarget* UTILS_NONNULL renderTarget, uint32_t xoffset, uint32_t yoffset, uint32_t width, uint32_t height, backend::PixelBufferDescriptor&& buffer); @@ -517,7 +517,7 @@ class UTILS_PUBLIC Renderer : public FilamentAPI { * However, internally, renderStandaloneView() is highly multi-threaded to both improve * performance in mitigate the call's latency. */ - void renderStandaloneView(View const* view); + void renderStandaloneView(View const* UTILS_NONNULL view); /** diff --git a/filament/include/filament/Scene.h b/filament/include/filament/Scene.h index 3d20266aaf7..9df6285c4aa 100644 --- a/filament/include/filament/Scene.h +++ b/filament/include/filament/Scene.h @@ -75,14 +75,14 @@ class UTILS_PUBLIC Scene : public FilamentAPI { * * @param skybox The Skybox to use to fill untouched pixels, or nullptr to unset the Skybox. */ - void setSkybox(Skybox* skybox) noexcept; + void setSkybox(Skybox* UTILS_NULLABLE skybox) noexcept; /** * Returns the Skybox associated with the Scene. * * @return The associated Skybox, or nullptr if there is none. */ - Skybox* getSkybox() const noexcept; + Skybox* UTILS_NULLABLE getSkybox() const noexcept; /** * Set the IndirectLight to use when rendering the Scene. @@ -93,7 +93,7 @@ class UTILS_PUBLIC Scene : public FilamentAPI { * @param ibl The IndirectLight to use when rendering the Scene or nullptr to unset. * @see getIndirectLight */ - void setIndirectLight(IndirectLight* ibl) noexcept; + void setIndirectLight(IndirectLight* UTILS_NULLABLE ibl) noexcept; /** * Get the IndirectLight or nullptr if none is set. @@ -101,7 +101,7 @@ class UTILS_PUBLIC Scene : public FilamentAPI { * @return the the IndirectLight or nullptr if none is set * @see setIndirectLight */ - IndirectLight* getIndirectLight() const noexcept; + IndirectLight* UTILS_NULLABLE getIndirectLight() const noexcept; /** * Adds an Entity to the Scene. @@ -120,7 +120,7 @@ class UTILS_PUBLIC Scene : public FilamentAPI { * @param entities Array containing entities to add to the scene. * @param count Size of the entity array. */ - void addEntities(const utils::Entity* entities, size_t count); + void addEntities(const utils::Entity* UTILS_NONNULL entities, size_t count); /** * Removes the Renderable from the Scene. @@ -139,7 +139,7 @@ class UTILS_PUBLIC Scene : public FilamentAPI { * @param entities Array containing entities to remove from the scene. * @param count Size of the entity array. */ - void removeEntities(const utils::Entity* entities, size_t count); + void removeEntities(const utils::Entity* UTILS_NONNULL entities, size_t count); /** * Returns the total number of Entities in the Scene, whether alive or not. diff --git a/filament/include/filament/SkinningBuffer.h b/filament/include/filament/SkinningBuffer.h index 94610085c50..36ae30ed438 100644 --- a/filament/include/filament/SkinningBuffer.h +++ b/filament/include/filament/SkinningBuffer.h @@ -74,8 +74,7 @@ class UTILS_PUBLIC SkinningBuffer : public FilamentAPI { * * @param engine Reference to the filament::Engine to associate this SkinningBuffer with. * - * @return pointer to the newly created object or nullptr if exceptions are disabled and - * an error occurred. + * @return pointer to the newly created object. * * @exception utils::PostConditionPanic if a runtime error occurred, such as running out of * memory or other resources. @@ -83,7 +82,7 @@ class UTILS_PUBLIC SkinningBuffer : public FilamentAPI { * * @see SkinningBuffer::setBones */ - SkinningBuffer* build(Engine& engine); + SkinningBuffer* UTILS_NONNULL build(Engine& engine); private: friend class FSkinningBuffer; }; @@ -96,7 +95,7 @@ class UTILS_PUBLIC SkinningBuffer : public FilamentAPI { * @param offset offset in elements (not bytes) in the SkinningBuffer (not in transforms) * @see RenderableManager::setSkinningBuffer */ - void setBones(Engine& engine, RenderableManager::Bone const* transforms, + void setBones(Engine& engine, RenderableManager::Bone const* UTILS_NONNULL transforms, size_t count, size_t offset = 0); /** @@ -107,7 +106,7 @@ class UTILS_PUBLIC SkinningBuffer : public FilamentAPI { * @param offset offset in elements (not bytes) in the SkinningBuffer (not in transforms) * @see RenderableManager::setSkinningBuffer */ - void setBones(Engine& engine, math::mat4f const* transforms, + void setBones(Engine& engine, math::mat4f const* UTILS_NONNULL transforms, size_t count, size_t offset = 0); /** diff --git a/filament/include/filament/Skybox.h b/filament/include/filament/Skybox.h index 3bf1c8c9fb5..ce203aae6a1 100644 --- a/filament/include/filament/Skybox.h +++ b/filament/include/filament/Skybox.h @@ -92,7 +92,7 @@ class UTILS_PUBLIC Skybox : public FilamentAPI { * * @see Texture */ - Builder& environment(Texture* cubemap) noexcept; + Builder& environment(Texture* UTILS_NONNULL cubemap) noexcept; /** * Indicates whether the sun should be rendered. The sun can only be @@ -136,9 +136,9 @@ class UTILS_PUBLIC Skybox : public FilamentAPI { * * @param engine Reference to the filament::Engine to associate this Skybox with. * - * @return pointer to the newly created object, or nullptr if the light couldn't be created. + * @return pointer to the newly created object. */ - Skybox* build(Engine& engine); + Skybox* UTILS_NONNULL build(Engine& engine); private: friend class FSkybox; @@ -172,9 +172,9 @@ class UTILS_PUBLIC Skybox : public FilamentAPI { float getIntensity() const noexcept; /** - * @return the associated texture, or null if it does not exist + * @return the associated texture */ - Texture const* getTexture() const noexcept; + Texture const* UTILS_NONNULL getTexture() const noexcept; protected: // prevent heap allocation diff --git a/filament/include/filament/Stream.h b/filament/include/filament/Stream.h index 2b294b7bcb9..6cafbacc8b3 100644 --- a/filament/include/filament/Stream.h +++ b/filament/include/filament/Stream.h @@ -114,7 +114,7 @@ class UTILS_PUBLIC Stream : public FilamentAPI { * * @return This Builder, for chaining calls. */ - Builder& stream(void* stream) noexcept; + Builder& stream(void* UTILS_NULLABLE stream) noexcept; /** * @@ -141,9 +141,9 @@ class UTILS_PUBLIC Stream : public FilamentAPI { * * @param engine Reference to the filament::Engine to associate this Stream with. * - * @return pointer to the newly created object, or nullptr if the stream couldn't be created. + * @return pointer to the newly created object. */ - Stream* build(Engine& engine); + Stream* UTILS_NONNULL build(Engine& engine); private: friend class FStream; @@ -171,11 +171,12 @@ class UTILS_PUBLIC Stream : public FilamentAPI { * * @param image Pointer to AHardwareBuffer, casted to void* since this is a public header. * @param callback This is triggered by Filament when it wishes to release the image. - * It callback tales two arguments: the AHardwareBuffer and the userdata. + * The callback tales two arguments: the AHardwareBuffer and the userdata. * @param userdata Optional closure data. Filament will pass this into the callback when it * releases the image. */ - void setAcquiredImage(void* image, Callback callback, void* userdata) noexcept; + void setAcquiredImage(void* UTILS_NONNULL image, + Callback UTILS_NONNULL callback, void* UTILS_NULLABLE userdata) noexcept; /** * @see setAcquiredImage(void*, Callback, void*) @@ -187,7 +188,9 @@ class UTILS_PUBLIC Stream : public FilamentAPI { * @param userdata Optional closure data. Filament will pass this into the callback when it * releases the image. */ - void setAcquiredImage(void* image, backend::CallbackHandler* handler, Callback callback, void* userdata) noexcept; + void setAcquiredImage(void* UTILS_NONNULL image, + backend::CallbackHandler* UTILS_NULLABLE handler, + Callback UTILS_NONNULL callback, void* UTILS_NULLABLE userdata) noexcept; /** * Updates the size of the incoming stream. Whether this value is used is diff --git a/filament/include/filament/SwapChain.h b/filament/include/filament/SwapChain.h index fab42dfc56e..8db477ade08 100644 --- a/filament/include/filament/SwapChain.h +++ b/filament/include/filament/SwapChain.h @@ -152,7 +152,7 @@ class Engine; class UTILS_PUBLIC SwapChain : public FilamentAPI { public: using FrameScheduledCallback = backend::FrameScheduledCallback; - using FrameCompletedCallback = utils::Invocable; + using FrameCompletedCallback = utils::Invocable; /** * Requests a SwapChain with an alpha channel. @@ -236,7 +236,7 @@ class UTILS_PUBLIC SwapChain : public FilamentAPI { */ static bool isSRGBSwapChainSupported(Engine& engine) noexcept; - void* getNativeWindow() const noexcept; + void* UTILS_NULLABLE getNativeWindow() const noexcept; /** * FrameScheduledCallback is a callback function that notifies an application when Filament has @@ -269,7 +269,8 @@ class UTILS_PUBLIC SwapChain : public FilamentAPI { * * @see PresentCallable */ - void setFrameScheduledCallback(FrameScheduledCallback callback, void* user = nullptr); + void setFrameScheduledCallback(FrameScheduledCallback UTILS_NULLABLE callback, + void* UTILS_NULLABLE user = nullptr); /** * FrameCompletedCallback is a callback function that notifies an application when a frame's @@ -290,7 +291,7 @@ class UTILS_PUBLIC SwapChain : public FilamentAPI { * * @see CallbackHandler */ - void setFrameCompletedCallback(backend::CallbackHandler* handler = nullptr, + void setFrameCompletedCallback(backend::CallbackHandler* UTILS_NULLABLE handler = nullptr, FrameCompletedCallback&& callback = {}) noexcept; diff --git a/filament/include/filament/Texture.h b/filament/include/filament/Texture.h index ee2721faa57..1b7c39ea5e9 100644 --- a/filament/include/filament/Texture.h +++ b/filament/include/filament/Texture.h @@ -204,14 +204,13 @@ class UTILS_PUBLIC Texture : public FilamentAPI { * * @param engine Reference to the filament::Engine to associate this Texture with. * - * @return pointer to the newly created object or nullptr if exceptions are disabled and - * an error occurred. + * @return pointer to the newly created object. * * @exception utils::PostConditionPanic if a runtime error occurred, such as running out of * memory or other resources. * @exception utils::PreConditionPanic if a parameter to a builder function was invalid. */ - Texture* build(Engine& engine); + Texture* UTILS_NONNULL build(Engine& engine); /* no user serviceable parts below */ @@ -400,7 +399,7 @@ class UTILS_PUBLIC Texture : public FilamentAPI { * @see Builder::sampler() * */ - void setExternalImage(Engine& engine, void* image) noexcept; + void setExternalImage(Engine& engine, void* UTILS_NONNULL image) noexcept; /** * Specify the external image and plane to associate with this Texture. Typically the external @@ -431,7 +430,7 @@ class UTILS_PUBLIC Texture : public FilamentAPI { * kCVPixelFormatType_420YpCbCr8BiPlanarFullRange images. On platforms * other than iOS, this method is a no-op. */ - void setExternalImage(Engine& engine, void* image, size_t plane) noexcept; + void setExternalImage(Engine& engine, void* UTILS_NONNULL image, size_t plane) noexcept; /** * Specify the external stream to associate with this Texture. Typically the external @@ -450,7 +449,7 @@ class UTILS_PUBLIC Texture : public FilamentAPI { * @see Builder::sampler(), Stream * */ - void setExternalStream(Engine& engine, Stream* stream) noexcept; + void setExternalStream(Engine& engine, Stream* UTILS_NULLABLE stream) noexcept; /** * Generates all the mipmap levels automatically. This requires the texture to have a @@ -500,7 +499,7 @@ class UTILS_PUBLIC Texture : public FilamentAPI { */ void generatePrefilterMipmap(Engine& engine, PixelBufferDescriptor&& buffer, const FaceOffsets& faceOffsets, - PrefilterOptions const* options = nullptr); + PrefilterOptions const* UTILS_NULLABLE options = nullptr); /** @deprecated */ diff --git a/filament/include/filament/TransformManager.h b/filament/include/filament/TransformManager.h index adb345547cb..5d612a1634c 100644 --- a/filament/include/filament/TransformManager.h +++ b/filament/include/filament/TransformManager.h @@ -140,7 +140,7 @@ class UTILS_PUBLIC TransformManager : public FilamentAPI { * Retrieve the Entities of all the components of this manager. * @return A list, in no particular order, of all the entities managed by this manager. */ - utils::Entity const* getEntities() const noexcept; + utils::Entity const* UTILS_NONNULL getEntities() const noexcept; /** * Enables or disable the accurate translation mode. Disabled by default. @@ -224,7 +224,7 @@ class UTILS_PUBLIC TransformManager : public FilamentAPI { * @param count The maximum number of children to retrieve. * @return The number of children written to the pointer. */ - size_t getChildren(Instance i, utils::Entity* children, size_t count) const noexcept; + size_t getChildren(Instance i, utils::Entity* UTILS_NONNULL children, size_t count) const noexcept; /** * Returns an iterator to the Instance of the first child of the given parent. diff --git a/filament/include/filament/VertexBuffer.h b/filament/include/filament/VertexBuffer.h index e9a1c6ef306..fccbd0046f8 100644 --- a/filament/include/filament/VertexBuffer.h +++ b/filament/include/filament/VertexBuffer.h @@ -163,14 +163,13 @@ class UTILS_PUBLIC VertexBuffer : public FilamentAPI { * * @param engine Reference to the filament::Engine to associate this VertexBuffer with. * - * @return pointer to the newly created object or nullptr if exceptions are disabled and - * an error occurred. + * @return pointer to the newly created object. * * @exception utils::PostConditionPanic if a runtime error occurred, such as running out of * memory or other resources. * @exception utils::PreConditionPanic if a parameter to a builder function was invalid. */ - VertexBuffer* build(Engine& engine); + VertexBuffer* UTILS_NONNULL build(Engine& engine); private: friend class FVertexBuffer; @@ -209,7 +208,8 @@ class UTILS_PUBLIC VertexBuffer : public FilamentAPI { * and Builder::bufferCount() - 1. * @param bufferObject The handle to the GPU data that will be used in this buffer slot. */ - void setBufferObjectAt(Engine& engine, uint8_t bufferIndex, BufferObject const* bufferObject); + void setBufferObjectAt(Engine& engine, uint8_t bufferIndex, + BufferObject const* UTILS_NONNULL bufferObject); protected: // prevent heap allocation diff --git a/filament/include/filament/View.h b/filament/include/filament/View.h index 2d8fd4366dc..e4ba827aad2 100644 --- a/filament/include/filament/View.h +++ b/filament/include/filament/View.h @@ -93,7 +93,7 @@ class UTILS_PUBLIC View : public FilamentAPI { * Sets the View's name. Only useful for debugging. * @param name Pointer to the View's name. The string is copied. */ - void setName(const char* name) noexcept; + void setName(const char* UTILS_NONNULL name) noexcept; /** * Returns the View's name @@ -102,7 +102,7 @@ class UTILS_PUBLIC View : public FilamentAPI { * * @attention Do *not* free the pointer or modify its content. */ - const char* getName() const noexcept; + const char* UTILS_NULLABLE getName() const noexcept; /** * Set this View instance's Scene. @@ -118,19 +118,19 @@ class UTILS_PUBLIC View : public FilamentAPI { * There is no reference-counting. * Make sure to dissociate a Scene from all Views before destroying it. */ - void setScene(Scene* scene); + void setScene(Scene* UTILS_NULLABLE scene); /** * Returns the Scene currently associated with this View. * @return A pointer to the Scene associated to this View. nullptr if no Scene is set. */ - Scene* getScene() noexcept; + Scene* UTILS_NULLABLE getScene() noexcept; /** * Returns the Scene currently associated with this View. * @return A pointer to the Scene associated to this View. nullptr if no Scene is set. */ - Scene const* getScene() const noexcept { + Scene const* UTILS_NULLABLE getScene() const noexcept { return const_cast(this)->getScene(); } @@ -145,7 +145,7 @@ class UTILS_PUBLIC View : public FilamentAPI { * * @param renderTarget Render target associated with view, or nullptr for the swap chain. */ - void setRenderTarget(RenderTarget* renderTarget) noexcept; + void setRenderTarget(RenderTarget* UTILS_NULLABLE renderTarget) noexcept; /** * Gets the offscreen render target associated with this view. @@ -154,7 +154,7 @@ class UTILS_PUBLIC View : public FilamentAPI { * * @see setRenderTarget */ - RenderTarget* getRenderTarget() const noexcept; + RenderTarget* UTILS_NULLABLE getRenderTarget() const noexcept; /** * Sets the rectangular region to render to. @@ -187,7 +187,7 @@ class UTILS_PUBLIC View : public FilamentAPI { * There is no reference-counting. * Make sure to dissociate a Camera from all Views before destroying it. */ - void setCamera(Camera* camera) noexcept; + void setCamera(Camera* UTILS_NONNULL camera) noexcept; /** * Returns the Camera currently associated with this View. @@ -404,13 +404,13 @@ class UTILS_PUBLIC View : public FilamentAPI { * There is no reference-counting. * Make sure to dissociate a ColorGrading from all Views before destroying it. */ - void setColorGrading(ColorGrading* colorGrading) noexcept; + void setColorGrading(ColorGrading* UTILS_NULLABLE colorGrading) noexcept; /** * Returns the color grading transforms currently associated to this view. * @return A pointer to the ColorGrading associated to this View. */ - const ColorGrading* getColorGrading() const noexcept; + const ColorGrading* UTILS_NULLABLE getColorGrading() const noexcept; /** * Sets ambient occlusion options. @@ -716,10 +716,10 @@ class UTILS_PUBLIC View : public FilamentAPI { bool isFrustumCullingEnabled() const noexcept; //! debugging: sets the Camera used for rendering. It may be different from the culling camera. - void setDebugCamera(Camera* camera) noexcept; + void setDebugCamera(Camera* UTILS_NULLABLE camera) noexcept; //! debugging: returns a Camera from the point of view of *the* dominant directional light used for shadowing. - Camera const* getDirectionalLightCamera() const noexcept; + Camera const* UTILS_NULLABLE getDirectionalLightCamera() const noexcept; /** Result of a picking query */ @@ -748,11 +748,12 @@ class UTILS_PUBLIC View : public FilamentAPI { /** User data for PickingQueryResultCallback */ struct PickingQuery { // note: this is enough to store a std::function<> -- just saying... - void* storage[4]; + void* UTILS_NULLABLE storage[4]; }; /** callback type used for picking queries. */ - using PickingQueryResultCallback = void(*)(PickingQueryResult const& result, PickingQuery* pq); + using PickingQueryResultCallback = + void(*)(PickingQueryResult const& result, PickingQuery* UTILS_NONNULL pq); /** * Helper for creating a picking query from Foo::method, by pointer. @@ -766,8 +767,8 @@ class UTILS_PUBLIC View : public FilamentAPI { * @param handler Handler to dispatch the callback or nullptr for the default handler. */ template - void pick(uint32_t x, uint32_t y, T* instance, - backend::CallbackHandler* handler = nullptr) noexcept { + void pick(uint32_t x, uint32_t y, T* UTILS_NONNULL instance, + backend::CallbackHandler* UTILS_NULLABLE handler = nullptr) noexcept { PickingQuery& query = pick(x, y, [](PickingQueryResult const& result, PickingQuery* pq) { (static_cast(pq->storage[0])->*method)(result); }, handler); @@ -787,7 +788,7 @@ class UTILS_PUBLIC View : public FilamentAPI { */ template void pick(uint32_t x, uint32_t y, T instance, - backend::CallbackHandler* handler = nullptr) noexcept { + backend::CallbackHandler* UTILS_NULLABLE handler = nullptr) noexcept { static_assert(sizeof(instance) <= sizeof(PickingQuery::storage), "user data too large"); PickingQuery& query = pick(x, y, [](PickingQueryResult const& result, PickingQuery* pq) { T* const that = static_cast(reinterpret_cast(pq->storage)); @@ -808,7 +809,7 @@ class UTILS_PUBLIC View : public FilamentAPI { */ template void pick(uint32_t x, uint32_t y, T functor, - backend::CallbackHandler* handler = nullptr) noexcept { + backend::CallbackHandler* UTILS_NULLABLE handler = nullptr) noexcept { static_assert(sizeof(functor) <= sizeof(PickingQuery::storage), "functor too large"); PickingQuery& query = pick(x, y, handler, (PickingQueryResultCallback)[](PickingQueryResult const& result, PickingQuery* pq) { @@ -834,8 +835,9 @@ class UTILS_PUBLIC View : public FilamentAPI { * 8*sizeof(void*) bytes of user data. This user data is later accessible * in the PickingQueryResultCallback callback 3rd parameter. */ - PickingQuery& pick(uint32_t x, uint32_t y, backend::CallbackHandler* handler, - PickingQueryResultCallback callback) noexcept; + PickingQuery& pick(uint32_t x, uint32_t y, + backend::CallbackHandler* UTILS_NULLABLE handler, + PickingQueryResultCallback UTILS_NONNULL callback) noexcept; /** * Set the value of material global variables. There are up-to four such variable each of diff --git a/filament/src/Material.cpp b/filament/src/Material.cpp index 24fd6015dc1..e48de9c0b50 100644 --- a/filament/src/Material.cpp +++ b/filament/src/Material.cpp @@ -25,7 +25,7 @@ MaterialInstance* Material::createInstance(const char* name) const noexcept { } const char* Material::getName() const noexcept { - return downcast(this)->getName().c_str(); + return downcast(this)->getName().c_str_safe(); } Shading Material::getShading() const noexcept { diff --git a/filament/src/ResourceAllocator.cpp b/filament/src/ResourceAllocator.cpp index 06d21a3de3c..b8d1e6698e5 100644 --- a/filament/src/ResourceAllocator.cpp +++ b/filament/src/ResourceAllocator.cpp @@ -16,15 +16,30 @@ #include "ResourceAllocator.h" -#include "private/backend/DriverApi.h" +#include #include "details/Texture.h" +#include +#include +#include +#include + +#include "private/backend/DriverApi.h" + +#include +#include #include #include -#include +#include +#include +#include #include +#include + +#include +#include using namespace utils; @@ -42,8 +57,7 @@ ResourceAllocator::AssociativeContainer::AssociativeContainer() { template UTILS_NOINLINE -ResourceAllocator::AssociativeContainer::~AssociativeContainer() noexcept { -} +ResourceAllocator::AssociativeContainer::~AssociativeContainer() noexcept = default; template UTILS_NOINLINE @@ -78,9 +92,9 @@ void ResourceAllocator::AssociativeContainer::emplace(ARGS&& ... args) ResourceAllocatorInterface::~ResourceAllocatorInterface() = default; size_t ResourceAllocator::TextureKey::getSize() const noexcept { - size_t pixelCount = width * height * depth; + size_t const pixelCount = width * height * depth; size_t size = pixelCount * FTexture::getFormatSize(format); - size_t s = std::max(uint8_t(1), samples); + size_t const s = std::max(uint8_t(1), samples); if (s > 1) { // if we have MSAA, we assume N times the storage size *= s; @@ -94,8 +108,10 @@ size_t ResourceAllocator::TextureKey::getSize() const noexcept { return size; } -ResourceAllocator::ResourceAllocator(DriverApi& driverApi) noexcept - : mBackend(driverApi) { +ResourceAllocator::ResourceAllocator(Engine::Config const& config, DriverApi& driverApi) noexcept + : mCacheCapacity(config.resourceAllocatorCacheSizeMB << 20), + mCacheMaxAge(config.resourceAllocatorCacheMaxAge), + mBackend(driverApi) { } ResourceAllocator::~ResourceAllocator() noexcept { @@ -112,7 +128,7 @@ void ResourceAllocator::terminate() noexcept { } } -RenderTargetHandle ResourceAllocator::createRenderTarget(const char* name, +RenderTargetHandle ResourceAllocator::createRenderTarget(const char*, TargetBufferFlags targetBufferFlags, uint32_t width, uint32_t height, uint8_t samples, MRT color, TargetBufferInfo depth, TargetBufferInfo stencil) noexcept { @@ -181,7 +197,7 @@ void ResourceAllocator::destroyTexture(TextureHandle h) noexcept { // move it to the cache const TextureKey key = it->second; - uint32_t size = key.getSize(); + uint32_t const size = key.getSize(); mTextureCache.emplace(key, TextureCachePayload{ h, mAge, size }); mCacheSize += size; @@ -208,9 +224,9 @@ void ResourceAllocator::gc() noexcept { auto& textureCache = mTextureCache; for (auto it = textureCache.begin(); it != textureCache.end();) { const size_t ageDiff = age - it->second.age; - if (ageDiff >= CACHE_MAX_AGE) { + if (ageDiff >= mCacheMaxAge) { it = purge(it); - if (mCacheSize < CACHE_CAPACITY) { + if (mCacheSize < mCacheCapacity) { // if we're not at capacity, only purge a single entry per gc, trying to // avoid a burst of work. break; @@ -220,7 +236,7 @@ void ResourceAllocator::gc() noexcept { } } - if (UTILS_UNLIKELY(mCacheSize >= CACHE_CAPACITY)) { + if (UTILS_UNLIKELY(mCacheSize >= mCacheCapacity)) { // make a copy of our CacheContainer to a vector using Vector = FixedCapacityVector>; auto cache = Vector::with_capacity(textureCache.size()); @@ -233,14 +249,14 @@ void ResourceAllocator::gc() noexcept { // now remove entries until we're at capacity auto curr = cache.begin(); - while (mCacheSize >= CACHE_CAPACITY) { + while (mCacheSize >= mCacheCapacity) { // by construction this entry must exist purge(textureCache.find(curr->first)); ++curr; } // Since we're sorted already, reset the oldestAge of the whole system - size_t oldestAge = cache.front().second.age; + size_t const oldestAge = cache.front().second.age; for (auto& it : textureCache) { it.second.age -= oldestAge; } diff --git a/filament/src/ResourceAllocator.h b/filament/src/ResourceAllocator.h index d16a046c6c1..220b6f6fbff 100644 --- a/filament/src/ResourceAllocator.h +++ b/filament/src/ResourceAllocator.h @@ -17,6 +17,8 @@ #ifndef TNT_FILAMENT_RESOURCEALLOCATOR_H #define TNT_FILAMENT_RESOURCEALLOCATOR_H +#include + #include #include #include @@ -27,7 +29,9 @@ #include #include +#include +#include #include namespace filament { @@ -62,7 +66,8 @@ class ResourceAllocatorInterface { class ResourceAllocator final : public ResourceAllocatorInterface { public: - explicit ResourceAllocator(backend::DriverApi& driverApi) noexcept; + explicit ResourceAllocator( + Engine::Config const& config, backend::DriverApi& driverApi) noexcept; ~ResourceAllocator() noexcept override; void terminate() noexcept; @@ -89,9 +94,8 @@ class ResourceAllocator final : public ResourceAllocatorInterface { void gc() noexcept; private: - // TODO: these should be settings of the engine - static constexpr size_t CACHE_CAPACITY = 64u << 20u; // 64 MiB - static constexpr size_t CACHE_MAX_AGE = 30u; + size_t const mCacheCapacity; + size_t const mCacheMaxAge; struct TextureKey { const char* name; // doesn't participate in the hash diff --git a/filament/src/ShadowMap.h b/filament/src/ShadowMap.h index b1678503dd6..ce1ee860622 100644 --- a/filament/src/ShadowMap.h +++ b/filament/src/ShadowMap.h @@ -163,7 +163,7 @@ class ShadowMap { FCamera const& getCamera() const noexcept { return *mCamera; } // use only for debugging - FCamera const& getDebugCamera() const noexcept { return *mDebugCamera; } + FCamera const* getDebugCamera() const noexcept { return mDebugCamera; } // Update SceneInfo struct for a given light static void updateSceneInfoDirectional(const math::mat4f& Mv, FScene const& scene, diff --git a/filament/src/ShadowMapManager.h b/filament/src/ShadowMapManager.h index 9ef55995e9b..5c38048ebed 100644 --- a/filament/src/ShadowMapManager.h +++ b/filament/src/ShadowMapManager.h @@ -100,7 +100,7 @@ class ShadowMapManager { // for debugging only FCamera const* getDirectionalLightCamera() const noexcept { - return &getShadowMap(0).getDebugCamera(); + return getShadowMap(0).getDebugCamera(); } private: diff --git a/filament/src/Stream.cpp b/filament/src/Stream.cpp index c895248e371..8bba0dd6b57 100644 --- a/filament/src/Stream.cpp +++ b/filament/src/Stream.cpp @@ -28,7 +28,8 @@ void Stream::setAcquiredImage(void* image, Callback callback, void* userdata) no downcast(this)->setAcquiredImage(image, callback, userdata); } -void Stream::setAcquiredImage(void* image, backend::CallbackHandler* handler, Callback callback, void* userdata) noexcept { +void Stream::setAcquiredImage(void* image, + backend::CallbackHandler* handler, Callback callback, void* userdata) noexcept { downcast(this)->setAcquiredImage(image, handler, callback, userdata); } diff --git a/filament/src/details/DebugRegistry.h b/filament/src/details/DebugRegistry.h index 44fc0818925..94dfec19414 100644 --- a/filament/src/details/DebugRegistry.h +++ b/filament/src/details/DebugRegistry.h @@ -34,6 +34,10 @@ class FEngine; class FDebugRegistry : public DebugRegistry { public: + enum Type { + BOOL, INT, FLOAT, FLOAT2, FLOAT3, FLOAT4 + }; + FDebugRegistry() noexcept; void registerProperty(std::string_view name, bool* p) noexcept { diff --git a/filament/src/details/Engine.cpp b/filament/src/details/Engine.cpp index 40d9c7c314b..c09711afa19 100644 --- a/filament/src/details/Engine.cpp +++ b/filament/src/details/Engine.cpp @@ -252,7 +252,7 @@ void FEngine::init() { slog.i << "FEngine feature level: " << int(mActiveFeatureLevel) << io::endl; - mResourceAllocator = new ResourceAllocator(driverApi); + mResourceAllocator = new ResourceAllocator(mConfig, driverApi); mFullScreenTriangleVb = downcast(VertexBuffer::Builder() .vertexCount(3) @@ -709,7 +709,9 @@ const FMaterial* FEngine::getSkyboxMaterial() const noexcept { template inline T* FEngine::create(ResourceList& list, typename T::Builder const& builder) noexcept { T* p = mHeapAllocator.make(*this, builder); - list.insert(p); + if (UTILS_UNLIKELY(p)) { // this should never happen + list.insert(p); + } return p; } @@ -771,7 +773,7 @@ FRenderTarget* FEngine::createRenderTarget(const RenderTarget::Builder& builder) FRenderer* FEngine::createRenderer() noexcept { FRenderer* p = mHeapAllocator.make(*this); - if (p) { + if (UTILS_UNLIKELY(p)) { // should never happen mRenderers.insert(p); } return p; @@ -780,7 +782,7 @@ FRenderer* FEngine::createRenderer() noexcept { FMaterialInstance* FEngine::createMaterialInstance(const FMaterial* material, const FMaterialInstance* other, const char* name) noexcept { FMaterialInstance* p = mHeapAllocator.make(*this, other, name); - if (p) { + if (UTILS_UNLIKELY(p)) { // should never happen auto pos = mMaterialInstances.emplace(material, "MaterialInstance"); pos.first->second.insert(p); } @@ -793,7 +795,7 @@ FMaterialInstance* FEngine::createMaterialInstance(const FMaterial* material, FScene* FEngine::createScene() noexcept { FScene* p = mHeapAllocator.make(*this); - if (p) { + if (UTILS_UNLIKELY(p)) { // should never happen mScenes.insert(p); } return p; @@ -801,7 +803,7 @@ FScene* FEngine::createScene() noexcept { FView* FEngine::createView() noexcept { FView* p = mHeapAllocator.make(*this); - if (p) { + if (UTILS_UNLIKELY(p)) { // should never happen mViews.insert(p); } return p; @@ -809,7 +811,7 @@ FView* FEngine::createView() noexcept { FFence* FEngine::createFence() noexcept { FFence* p = mHeapAllocator.make(*this); - if (p) { + if (UTILS_UNLIKELY(p)) { // should never happen std::lock_guard const guard(mFenceListLock); mFences.insert(p); } @@ -825,7 +827,7 @@ FSwapChain* FEngine::createSwapChain(void* nativeWindow, uint64_t flags) noexcep getDriverApi().setupExternalImage(nativeWindow); } FSwapChain* p = mHeapAllocator.make(*this, nativeWindow, flags); - if (p) { + if (UTILS_UNLIKELY(p)) { // should never happen mSwapChains.insert(p); } return p; diff --git a/filament/src/details/MaterialInstance.cpp b/filament/src/details/MaterialInstance.cpp index 6fc3db2364a..9c8a88a30ba 100644 --- a/filament/src/details/MaterialInstance.cpp +++ b/filament/src/details/MaterialInstance.cpp @@ -269,7 +269,7 @@ const char* FMaterialInstance::getName() const noexcept { // the instance's CString rather than calling empty(). This allows instances to override the // parent material's name with a blank string. if (mName.data() == nullptr) { - return mMaterial->getName().c_str(); + return mMaterial->getName().c_str_safe(); } return mName.c_str(); } diff --git a/filament/src/details/Stream.cpp b/filament/src/details/Stream.cpp index 71945cd7eb9..317113ace03 100644 --- a/filament/src/details/Stream.cpp +++ b/filament/src/details/Stream.cpp @@ -86,11 +86,13 @@ void FStream::terminate(FEngine& engine) noexcept { engine.getDriverApi().destroyStream(mStreamHandle); } -void FStream::setAcquiredImage(void* image, Callback callback, void* userdata) noexcept { +void FStream::setAcquiredImage(void* image, + Callback callback, void* userdata) noexcept { mEngine.getDriverApi().setAcquiredImage(mStreamHandle, image, nullptr, callback, userdata); } -void FStream::setAcquiredImage(void* image, CallbackHandler* handler, Callback callback, void* userdata) noexcept { +void FStream::setAcquiredImage(void* image, + CallbackHandler* handler, Callback callback, void* userdata) noexcept { mEngine.getDriverApi().setAcquiredImage(mStreamHandle, image, handler, callback, userdata); } diff --git a/filament/src/details/View.h b/filament/src/details/View.h index 18ec7853186..204f11b9d56 100644 --- a/filament/src/details/View.h +++ b/filament/src/details/View.h @@ -490,7 +490,7 @@ class FView : public View { FScene* mScene = nullptr; // The camera set by the user, used for culling and viewing - FCamera* mCullingCamera = nullptr; + FCamera* /* UTILS_NONNULL */ mCullingCamera = nullptr; // FIXME: should alaways be non-null // The optional (debug) camera, used only for viewing FCamera* mViewingCamera = nullptr; diff --git a/ios/CocoaPods/Filament.podspec b/ios/CocoaPods/Filament.podspec index ebefa012fb3..5b53805fa63 100644 --- a/ios/CocoaPods/Filament.podspec +++ b/ios/CocoaPods/Filament.podspec @@ -1,12 +1,12 @@ Pod::Spec.new do |spec| spec.name = "Filament" - spec.version = "1.50.2" + spec.version = "1.50.3" spec.license = { :type => "Apache 2.0", :file => "LICENSE" } spec.homepage = "https://google.github.io/filament" spec.authors = "Google LLC." spec.summary = "Filament is a real-time physically based rendering engine for Android, iOS, Windows, Linux, macOS, and WASM/WebGL." spec.platform = :ios, "11.0" - spec.source = { :http => "https://github.com/google/filament/releases/download/v1.50.2/filament-v1.50.2-ios.tgz" } + spec.source = { :http => "https://github.com/google/filament/releases/download/v1.50.3/filament-v1.50.3-ios.tgz" } # Fix linking error with Xcode 12; we do not yet support the simulator on Apple silicon. spec.pod_target_xcconfig = { diff --git a/libs/utils/include/utils/compiler.h b/libs/utils/include/utils/compiler.h index 7d62a389bb8..710c901eef8 100644 --- a/libs/utils/include/utils/compiler.h +++ b/libs/utils/include/utils/compiler.h @@ -179,6 +179,14 @@ # define UTILS_HAS_FEATURE_CXX_THREAD_LOCAL 0 #endif +#if defined(__clang__) +#define UTILS_NONNULL _Nonnull +#define UTILS_NULLABLE _Nullable +#else +#define UTILS_NONNULL +#define UTILS_NULLABLE +#endif + #if defined(_MSC_VER) // MSVC does not support loop unrolling hints # define UTILS_UNROLL diff --git a/web/filament-js/package.json b/web/filament-js/package.json index c7ad9bd95fc..7ebc0a0ff4b 100644 --- a/web/filament-js/package.json +++ b/web/filament-js/package.json @@ -1,6 +1,6 @@ { "name": "filament", - "version": "1.50.2", + "version": "1.50.3", "description": "Real-time physically based rendering engine", "main": "filament.js", "module": "filament.js",