add nullability attributes to filament public APIs

google · Feb 1, 2024 · 34f8b9a · 34f8b9a
1 parent 6d07443
commit 34f8b9a
Show file tree

Hide file tree

Showing 36 changed files with 349 additions and 309 deletions.
diff --git a/filament/include/filament/BufferObject.h b/filament/include/filament/BufferObject.h
@@ -84,16 +84,15 @@ 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.
          * @exception utils::PreConditionPanic if a parameter to a builder function was invalid.
          *
          * @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
@@ -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
@@ -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
@@ -39,56 +39,43 @@ 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
      * @param name Name of the property we want the data address of
      * @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<typename T>
-    inline T* getPropertyAddress(const char* name) {
+    inline T* UTILS_NULLABLE getPropertyAddress(const char* UTILS_NONNULL name) {
         return static_cast<T*>(getPropertyAddress(name));
     }
 
     template<typename T>
-    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<T*>(getPropertyAddress(name));
     }
 
     template<typename T>
-    inline bool getPropertyAddress(const char* name, T** p) {
+    inline bool getPropertyAddress(const char* UTILS_NONNULL name,
+            T* UTILS_NULLABLE* UTILS_NONNULL p) {
         *p = getPropertyAddress<T>(name);
         return *p != nullptr;
     }
 
     template<typename T>
-    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<T>(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;