From 34f8b9aa20f71ca68dc5e9260f3eb751bf11af11 Mon Sep 17 00:00:00 2001 From: Mathias Agopian Date: Thu, 25 Jan 2024 15:21:20 -0800 Subject: [PATCH] add nullability attributes to filament public APIs --- filament/include/filament/BufferObject.h | 5 +- filament/include/filament/Camera.h | 2 +- filament/include/filament/ColorGrading.h | 7 +- filament/include/filament/DebugRegistry.h | 59 +++---- filament/include/filament/Engine.h | 147 +++++++++--------- filament/include/filament/Fence.h | 2 +- filament/include/filament/Frustum.h | 4 +- filament/include/filament/IndexBuffer.h | 5 +- filament/include/filament/IndirectLight.h | 19 +-- filament/include/filament/InstanceBuffer.h | 7 +- filament/include/filament/LightManager.h | 8 +- filament/include/filament/Material.h | 52 +++---- filament/include/filament/MaterialInstance.h | 41 ++--- filament/include/filament/MorphTargetBuffer.h | 11 +- filament/include/filament/RenderTarget.h | 9 +- filament/include/filament/RenderableManager.h | 95 +++++++---- filament/include/filament/Renderer.h | 14 +- filament/include/filament/Scene.h | 12 +- filament/include/filament/SkinningBuffer.h | 9 +- filament/include/filament/Skybox.h | 10 +- filament/include/filament/Stream.h | 15 +- filament/include/filament/SwapChain.h | 9 +- filament/include/filament/Texture.h | 13 +- filament/include/filament/TransformManager.h | 4 +- filament/include/filament/VertexBuffer.h | 8 +- filament/include/filament/View.h | 42 ++--- filament/src/Material.cpp | 2 +- filament/src/ShadowMap.h | 2 +- filament/src/ShadowMapManager.h | 2 +- filament/src/Stream.cpp | 3 +- filament/src/details/DebugRegistry.h | 4 + filament/src/details/Engine.cpp | 16 +- filament/src/details/MaterialInstance.cpp | 2 +- filament/src/details/Stream.cpp | 6 +- filament/src/details/View.h | 2 +- libs/utils/include/utils/compiler.h | 8 + 36 files changed, 348 insertions(+), 308 deletions(-) diff --git a/filament/include/filament/BufferObject.h b/filament/include/filament/BufferObject.h index 61dad944c1..74a4b1ff39 100644 --- a/filament/include/filament/BufferObject.h +++ b/filament/include/filament/BufferObject.h @@ -84,8 +84,7 @@ public: * * @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 @@ public: * * @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 6c5f36ccd6..74f34af0fe 100644 --- a/filament/include/filament/Camera.h +++ b/filament/include/filament/Camera.h @@ -306,7 +306,7 @@ public: * @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 94a11c109d..e5c8f3cae3 100644 --- a/filament/include/filament/ColorGrading.h +++ b/filament/include/filament/ColorGrading.h @@ -203,7 +203,7 @@ public: * * @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 @@ public: * * @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 691067d765..d5e1d8e983 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 @@ public: * @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 @@ public: * @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 @@ public: * @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 15ae07b1f4..1b5c63a317 100644 --- a/filament/include/filament/Engine.h +++ b/filament/include/filament/Engine.h @@ -309,7 +309,7 @@ public: #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 +348,7 @@ public: * * @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 +356,7 @@ public: * * @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 +364,7 @@ public: * * @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 +379,7 @@ public: * @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 +394,17 @@ public: * 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 +419,18 @@ public: * 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 +447,7 @@ public: * 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 +477,7 @@ public: * \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 +504,7 @@ public: * \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 +652,11 @@ public: * `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 +666,42 @@ public: * @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 +711,7 @@ public: * 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 +723,17 @@ public: /** * 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 +743,38 @@ public: * @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 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* 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 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 +814,7 @@ public: * * @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 +845,7 @@ public: * @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 +858,7 @@ public: * @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 fa0de519ab..673d12cdb9 100644 --- a/filament/include/filament/Fence.h +++ b/filament/include/filament/Fence.h @@ -76,7 +76,7 @@ public: * @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 f9936d48a5..ceec55eb82 100644 --- a/filament/include/filament/Frustum.h +++ b/filament/include/filament/Frustum.h @@ -79,14 +79,14 @@ public: * @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 5218e93c29..35b8a10ef2 100644 --- a/filament/include/filament/IndexBuffer.h +++ b/filament/include/filament/IndexBuffer.h @@ -89,8 +89,7 @@ public: * * @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 @@ public: * * @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 0021dbe0cd..c230dac8fe 100644 --- a/filament/include/filament/IndirectLight.h +++ b/filament/include/filament/IndirectLight.h @@ -116,7 +116,7 @@ public: * @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 @@ public: * 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 @@ public: * * @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 @@ public: * * @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 @@ public: * 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 @@ public: /** * 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 @@ public: * @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 @@ public: * @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 b32cac53c5..2135152d88 100644 --- a/filament/include/filament/InstanceBuffer.h +++ b/filament/include/filament/InstanceBuffer.h @@ -68,12 +68,12 @@ public: * @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 @@ public: * @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 fd3184bf7c..22d663f2ea 100644 --- a/filament/include/filament/LightManager.h +++ b/filament/include/filament/LightManager.h @@ -176,7 +176,7 @@ public: * 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 @@ public: * 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 @@ public: * @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 @@ public: * @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 15098c81d9..b4b9bbed3e 100644 --- a/filament/include/filament/Material.h +++ b/filament/include/filament/Material.h @@ -74,7 +74,7 @@ public: */ 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 @@ public: * @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 @@ public: * 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 @@ public: * 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 @@ public: */ 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 @@ public: * * @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 @@ public: * * @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 @@ public: * @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 @@ public: * * @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 @@ public: * * @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 @@ public: * * @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 913f179ae8..a0edd13554 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 @@ public: * @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 @@ public: * @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 @@ public: /** 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 @@ public: * @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 @@ public: * @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 @@ public: * @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 @@ public: } /** 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 @@ public: * @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 @@ public: } /** 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 24e28b80ee..655bb8d848 100644 --- a/filament/include/filament/MorphTargetBuffer.h +++ b/filament/include/filament/MorphTargetBuffer.h @@ -68,14 +68,13 @@ public: * * @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 @@ public: * @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 @@ public: * @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 @@ public: * @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 bf70d03a25..fc76111da7 100644 --- a/filament/include/filament/RenderTarget.h +++ b/filament/include/filament/RenderTarget.h @@ -106,7 +106,7 @@ public: * @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 @@ public: /** * 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 @@ public: * @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 75b9d95015..6024fd2e59 100644 --- a/filament/include/filament/RenderableManager.h +++ b/filament/include/filament/RenderableManager.h @@ -129,7 +129,7 @@ public: * 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 @@ public: * @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 @@ public: * * @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 @@ public: * @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 @@ public: * @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 @@ public: * @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 @@ public: * @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 @@ public: * 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 @@ public: 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 @@ public: * 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 @@ public: * @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 @@ public: * @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 @@ public: * @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 @@ public: 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 @@ protected: ~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 8b7fb28bdc..fdc291b1fd 100644 --- a/filament/include/filament/Renderer.h +++ b/filament/include/filament/Renderer.h @@ -181,14 +181,14 @@ public: * * @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 @@ public: * @see * endFrame() */ - bool beginFrame(SwapChain* swapChain, + bool beginFrame(SwapChain* UTILS_NONNULL swapChain, uint64_t vsyncSteadyClockTimeNano = 0u); /** @@ -335,7 +335,7 @@ public: * 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 @@ public: * 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 @@ public: * 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 @@ public: * 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 3d20266aaf..9df6285c4a 100644 --- a/filament/include/filament/Scene.h +++ b/filament/include/filament/Scene.h @@ -75,14 +75,14 @@ public: * * @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 @@ public: * @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 @@ public: * @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 @@ public: * @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 @@ public: * @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 94610085c5..36ae30ed43 100644 --- a/filament/include/filament/SkinningBuffer.h +++ b/filament/include/filament/SkinningBuffer.h @@ -74,8 +74,7 @@ public: * * @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 @@ public: * * @see SkinningBuffer::setBones */ - SkinningBuffer* build(Engine& engine); + SkinningBuffer* UTILS_NONNULL build(Engine& engine); private: friend class FSkinningBuffer; }; @@ -96,7 +95,7 @@ public: * @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 @@ public: * @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 3bf1c8c9fb..ce203aae6a 100644 --- a/filament/include/filament/Skybox.h +++ b/filament/include/filament/Skybox.h @@ -92,7 +92,7 @@ public: * * @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 @@ public: * * @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 @@ public: 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 2b294b7bcb..6cafbacc8b 100644 --- a/filament/include/filament/Stream.h +++ b/filament/include/filament/Stream.h @@ -114,7 +114,7 @@ public: * * @return This Builder, for chaining calls. */ - Builder& stream(void* stream) noexcept; + Builder& stream(void* UTILS_NULLABLE stream) noexcept; /** * @@ -141,9 +141,9 @@ public: * * @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 @@ public: * * @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 @@ public: * @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 fab42dfc56..8db477ade0 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 @@ public: */ 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 @@ public: * * @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 @@ public: * * @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 ee2721faa5..1b7c39ea5e 100644 --- a/filament/include/filament/Texture.h +++ b/filament/include/filament/Texture.h @@ -204,14 +204,13 @@ public: * * @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 @@ public: * @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 @@ public: * 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 @@ public: * @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 @@ public: */ 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 adb345547c..5d612a1634 100644 --- a/filament/include/filament/TransformManager.h +++ b/filament/include/filament/TransformManager.h @@ -140,7 +140,7 @@ public: * 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 @@ public: * @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 e9a1c6ef30..fccbd0046f 100644 --- a/filament/include/filament/VertexBuffer.h +++ b/filament/include/filament/VertexBuffer.h @@ -163,14 +163,13 @@ public: * * @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 @@ public: * 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 2d8fd4366d..e4ba827aad 100644 --- a/filament/include/filament/View.h +++ b/filament/include/filament/View.h @@ -93,7 +93,7 @@ public: * 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 @@ public: * * @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 @@ public: * 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 @@ public: * * @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 @@ public: * * @see setRenderTarget */ - RenderTarget* getRenderTarget() const noexcept; + RenderTarget* UTILS_NULLABLE getRenderTarget() const noexcept; /** * Sets the rectangular region to render to. @@ -187,7 +187,7 @@ public: * 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 @@ public: * 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 @@ public: 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 @@ public: /** 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 @@ public: * @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 @@ public: */ 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 @@ public: */ 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 @@ public: * 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 24fd6015dc..e48de9c0b5 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/ShadowMap.h b/filament/src/ShadowMap.h index b1678503dd..ce1ee86062 100644 --- a/filament/src/ShadowMap.h +++ b/filament/src/ShadowMap.h @@ -163,7 +163,7 @@ public: 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 9ef55995e9..5c38048ebe 100644 --- a/filament/src/ShadowMapManager.h +++ b/filament/src/ShadowMapManager.h @@ -100,7 +100,7 @@ public: // 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 c895248e37..8bba0dd6b5 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 44fc081892..94dfec1941 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 40d9c7c314..93915e7b4e 100644 --- a/filament/src/details/Engine.cpp +++ b/filament/src/details/Engine.cpp @@ -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 6fc3db2364..9c8a88a30b 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 71945cd7eb..317113ace0 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 18ec785318..204f11b9d5 100644 --- a/filament/src/details/View.h +++ b/filament/src/details/View.h @@ -490,7 +490,7 @@ private: 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/libs/utils/include/utils/compiler.h b/libs/utils/include/utils/compiler.h index 7d62a389bb..710c901eef 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