Minor updates to Graphics API and documentation
authorDavid Steele <david.steele@samsung.com>
Wed, 23 Jan 2019 13:27:24 +0000 (13:27 +0000)
committerDavid Steele <david.steele@samsung.com>
Wed, 23 Jan 2019 13:27:24 +0000 (13:27 +0000)
Change-Id: I9cc127dfa04c18311803d1a2fe2762c01aff0d61

dali/graphics-api/graphics-api-controller.h
dali/graphics-api/graphics-api-pipeline-factory.h
dali/graphics-api/graphics-api-render-command.h
dali/graphics-api/graphics-api-shader.h
dali/internal/update/manager/update-manager.cpp
dali/internal/update/rendering/scene-graph-renderer.cpp

index ecac45a74c9c0d976c1ce78c559c72fc59e7cfdc..7b1ce36f20c285eaa16eb4176c7f6c027e2566e3 100644 (file)
@@ -118,7 +118,7 @@ public:
   virtual SamplerFactory& GetSamplerFactory() = 0;
 
   /**
-   * @brief alAllocates render command ( depends on implementation );
+   * @brief Allocates render command ( depends on implementation );
    * @return
    */
   virtual std::unique_ptr<RenderCommand> AllocateRenderCommand() = 0;
@@ -212,11 +212,9 @@ protected:
   Controller& operator=( Controller&& ) = default;
 
   /**
-   * Objects of this type should not directly.
+   * Objects of this type should not be directly instantiated.
    */
   Controller() = default;
-
-private:
 };
 
 } // namespace Graphics
index 54b3be0fc7c39ce33aee9aebc966697385f9b0d4..e6add782b1d342c3db3df48fbcbb4ba81bf8a097 100644 (file)
@@ -25,10 +25,9 @@ namespace Dali
 {
 namespace Graphics
 {
-class PipelineCache;
 
 /**
- * @brief Interface class for ShaderFactory types in the graphics API.
+ * @brief Interface class for generating Pipeline types in the graphics API.
  */
 class PipelineFactory
 {
index 0d88374e4167b2141a435c8d0185da9f96596ad4..d70ae1f4c0ed43370c46e1976a42a14cb6cd0069 100644 (file)
@@ -55,6 +55,10 @@ constexpr uint32_t RENDER_COMMAND_UPDATE_DRAW_BIT               = 1 << 7;
 constexpr uint32_t RENDER_COMMAND_UPDATE_PUSH_CONSTANTS_BIT     = 1 << 8;
 constexpr uint32_t RENDER_COMMAND_UPDATE_ALL_BITS               = 0xffff;
 
+/**
+ * Class which defines a render operation.
+ * First, bind the relevant graphics objects to the command, finally call the Draw method.
+ */
 class RenderCommand
 {
 public:
@@ -67,6 +71,9 @@ public:
     INDEX_TYPE_UINT32,
   };
 
+  /**
+   * DrawType defines whether vertices are read contiguously, or use a secondary index
+   */
   enum class DrawType
   {
     UNDEFINED_DRAW,
@@ -79,8 +86,14 @@ public:
    */
   struct UniformBufferBinding
   {
-    UniformBufferBinding() :
-    buffer( nullptr ), offset( 0u ), dataSize( 0u ), binding( 0u ) {}
+    UniformBufferBinding()
+    : buffer( nullptr ),
+      offset( 0u ),
+      dataSize( 0u ),
+      binding( 0u )
+    {
+    }
+
     const Buffer*  buffer;
     uint32_t offset;
     uint32_t dataSize;
@@ -112,7 +125,7 @@ public:
   };
 
   /**
-   *
+   * Structure describes texture binding
    */
   struct TextureBinding
   {
@@ -146,11 +159,10 @@ public:
     }
 
     friend std::ostream& operator<<(std::ostream& ss, const TextureBinding& object);
-
   };
 
   /**
-   *
+   * structure defining the sampler binding
    */
   struct SamplerBinding
   {
@@ -172,7 +184,7 @@ public:
   };
 
   /**
-   *
+   * structure defining the index buffer binding
    */
   struct IndexBufferBinding
   {
@@ -204,6 +216,9 @@ public:
     friend std::ostream& operator<<(std::ostream& ss, const IndexBufferBinding&);
   };
 
+  /**
+   * structure defining the framebuffer (if any) of the render target
+   */
   struct RenderTargetBinding
   {
     const Framebuffer*                    framebuffer { nullptr };
@@ -211,8 +226,8 @@ public:
     Framebuffer::DepthStencilClearColor   depthStencilClearColor {};
     float framebufferWidth; // Store the framebuffer size in case we need to set viewport
     float framebufferHeight;
+    void* pNext{ nullptr };
 
-    void*    pNext{ nullptr };
     RenderTargetBinding() = default;
 
     RenderTargetBinding& SetFramebuffer( const Framebuffer* value )
@@ -236,6 +251,9 @@ public:
     friend std::ostream& operator<<(std::ostream& ss, const RenderTargetBinding&);
   };
 
+  /**
+   * Structure defining the draw command
+   */
   struct DrawCommand
   {
     DrawCommand() : drawType( DrawType::UNDEFINED_DRAW )
@@ -329,7 +347,7 @@ public:
   };
 
   /**
-   *
+   * Structure defining the push constants
    */
   struct PushConstantsBinding
   {
@@ -359,6 +377,9 @@ public:
     friend std::ostream& operator<<(std::ostream& ss, const PushConstantsBinding&);
   };
 
+  /**
+   * Constructor
+   */
   RenderCommand()
   : mVertexBufferBindings(),
     mUniformBufferBindings(),
@@ -435,13 +456,6 @@ public:
     return *this;
   }
 
-  RenderCommand& Draw( DrawCommand&& drawCommand )
-  {
-    mDrawCommand = drawCommand;
-    mUpdateFlags |= RENDER_COMMAND_UPDATE_DRAW_BIT;
-    return *this;
-  }
-
   RenderCommand& BindPipeline( const Pipeline* pipeline )
   {
     if( !mPipeline || mPipeline != pipeline )
@@ -459,6 +473,13 @@ public:
     return *this;
   }
 
+  RenderCommand& Draw( DrawCommand&& drawCommand )
+  {
+    mDrawCommand = drawCommand;
+    mUpdateFlags |= RENDER_COMMAND_UPDATE_DRAW_BIT;
+    return *this;
+  }
+
   static std::vector<TextureBinding> NewTextureBindings()
   {
     return std::vector<TextureBinding>{};
@@ -529,7 +550,6 @@ public:
   const std::vector<TextureBinding>*        mTextureBindings;
   std::vector<SamplerBinding>               mSamplerBindings;
 
-
   IndexBufferBinding                        mIndexBufferBinding;
   RenderTargetBinding                       mRenderTargetBinding;
   DrawCommand                               mDrawCommand;
@@ -542,12 +562,12 @@ protected:
 public:
   // WARNING: Be careful with these - all libraries must be built with DEBUG_ENABLED
   // to ensure every instantiation has the same size.
+  // They should always be the last attributes in this class.
 #if defined(DEBUG_ENABLED)
   // Debug
   std::string                               mDebugString{""};
   void*                                     mDebugObject{nullptr};
 #endif
-
 };
 
 } // namespace Graphics
index e0c5154be29816ad45921e3bba72a8deb0438dd5..11e2b39dbcd99885ccbd65639df25365f35227b7 100644 (file)
@@ -103,7 +103,7 @@ protected:
   Shader& operator=(Shader&&) = default;
 
   /**
-   * Objects of this type should not directly.
+   * Objects of this type should not be directly instantiated.
    */
   Shader() = default;
 };
index 5bd986060807e2438813483be358b155999f798c..3bac6b12618e5a3814cd034dea1467bbd316eb1a 100644 (file)
@@ -810,8 +810,8 @@ uint32_t UpdateManager::Update( float elapsedSeconds,
     mImpl->messageQueue.IsSceneUpdateRequired()     || // ..a message that modifies the scene graph node tree is queued OR
     gestureUpdated;                                    // ..a gesture property was updated OR
 
-  // Although the scene-graph may not require an update, we still need to synchronize double-buffered
-  // values if the scene was updated in the previous frame.
+  // Although the scene-graph may not require an update, we still need to synchronize
+  // double-buffered values if the scene was updated in the previous frame.
   if( updateScene || mImpl->previousUpdateScene )
   {
     //Reset properties from the previous update
@@ -819,15 +819,15 @@ uint32_t UpdateManager::Update( float elapsedSeconds,
     mImpl->transformManager.ResetToBaseValue();
   }
 
-  // Process the queued scene messages. Note, MessageQueue::FlushQueue may be called
-  // between calling IsSceneUpdateRequired() above and here, so updateScene should
-  // be set again
+  // Process the queued scene messages. Note, MessageQueue::FlushQueue may be called between calling
+  // IsSceneUpdateRequired() above and here, so updateScene should be set again
   updateScene |= mImpl->messageQueue.ProcessMessages( bufferIndex );
   updateScene |= resumed;
 
-  // Although the scene-graph may not require an update, we still need to synchronize double-buffered
-  // renderer lists if the scene was updated in the previous frame.
-  // We should not start skipping update steps or reusing lists until there has been two frames where nothing changes
+  // Although the scene-graph may not require an update, we still need to synchronize
+  // double-buffered renderer lists if the scene was updated in the previous frame.  We should not
+  // start skipping update steps or reusing lists until there have been two frames where nothing
+  // changes
   if( updateScene || mImpl->previousUpdateScene )
   {
     //Animate
@@ -904,7 +904,7 @@ uint32_t UpdateManager::Update( float elapsedSeconds,
         }
       }
 
-      // Pass the graphics back end the total number of renderers that were discarded this frame.
+      // Pass the total number of renderers that were discarded this frame to the graphics backend.
       // This may trigger garbage collection.
       if( numberOfDiscardedRenderers > 0 )
       {
index e9b1fd2324802dbfaf275b5735a6c55ca39ce82b..9a5ae970933330325c6d8d428c8d317d9672e4dc 100644 (file)
@@ -524,8 +524,8 @@ void Renderer::SetTextures( TextureSet* textureSet )
   mTextureSet = textureSet;
   mTextureSet->AddObserver( this );
 
-  // Rebind textures to make sure old data won't be used
-  // Note, why are we binding textures for render commands on all buffer indexes?
+  // Rebind textures to make sure old data won't be used. Ensure this
+  // occurs for both buffers.
   mRenderCommands.BindTextures( mTextureBindings );
 
   DALI_LOG_INFO( gTextureFilter, Debug::General, "SG::Renderer(%p)::SetTextures( SG::TS:%p )\n"