Merge tag 'v01.01.00.00' into develop
[tidl/tidl-api.git] / tidl_api / inc / configuration.h
index 8ed6be2f5d6616b23b04da7919f5e303e013e74a..531bb6dc2bb9798156a4717d7305f338aeb72e68 100644 (file)
@@ -38,7 +38,13 @@ namespace tidl {
 
 /*! @class Configuration
     @brief Specifies the configuration required for a network
 
 /*! @class Configuration
     @brief Specifies the configuration required for a network
+
+    The Configuration object is used to specify various parameters required
+    for network execution. Applications can directly initialize fields in an
+    instance of Configuration or use the ReadFromFile method to read the
+    configuration from a file.
 */
 */
+
 class Configuration
 {
   public:
 class Configuration
 {
   public:
@@ -46,13 +52,14 @@ class Configuration
     //! Number of frames of input data (can be 0 if data is not read from file)
     int     numFrames;
 
     //! Number of frames of input data (can be 0 if data is not read from file)
     int     numFrames;
 
-    //! Height of the input frame
+    //! Height of the input image. Used by the API, must be specified.
     int     inHeight;
 
     int     inHeight;
 
-    //! Width of the input frame
+    //! Width of the input image. Used by the API, must be specified.
     int     inWidth;
 
     //! Number of channels in the input frame (e.g. 3 for BGR)
     int     inWidth;
 
     //! Number of channels in the input frame (e.g. 3 for BGR)
+    //! Used by the API, must be specified.
     int     inNumChannels;
 
     //! @private
     int     inNumChannels;
 
     //! @private
@@ -69,27 +76,44 @@ class Configuration
     //! outputs of previous layersGroupId, instead of from user application
     bool     enableInternalInput;
 
     //! outputs of previous layersGroupId, instead of from user application
     bool     enableInternalInput;
 
-    //! Size of the device side heap, used for allocating memory required to
+    //! @brief Size of the device side network heap
+    //! This heap is used for allocating memory required to
     //! run the network on the device. One per Execution Object.
     size_t NETWORK_HEAP_SIZE;
 
     //! run the network on the device. One per Execution Object.
     size_t NETWORK_HEAP_SIZE;
 
-    //! Size of the heap used for parameter data. One per Executor.
+    //! @brief Size of the device side heap used for parameter data.
+    //! The size depends on the size of the parameter binary file. The
+    //! constructor for ``Configuration`` sets PARAM_HEAP_SIZE to 9MB.
+    //! There is one parameter heap for each instance of ``Executor`` .
     size_t PARAM_HEAP_SIZE;
 
     size_t PARAM_HEAP_SIZE;
 
-    //! @brief Location of the input file
-    //! Can be empty if input data is provided by frameworks such as OpenCV.
+    //! @brief Path to the input image file.
+    //! This field is not used by the TIDL API itself. It can be used by
+    //! applications to load an input image into a buffer. Can be empty if
+    //! the application uses frameworks such as OpenCV to read images. Refer
+    //! examples/test/main.cpp for usage.
     std::string inData;
 
     std::string inData;
 
-    //! Location of the output file
-    //! Can be empty if output data is consumed by frameworks such as OpenCV.
+    //! @brief Path to the output image file.
+    //! This field is not used by the TIDL API itself. It can be used by
+    //! applications to specify a name for the output file. Can be empty
+    //! if the application uses frameworks such as OpenCV to read images.
+    //! Refer examples/test/main.cpp for usage.
     std::string outData;
 
     std::string outData;
 
-    //! Path to the TIDL network binary file
+    //! Path to the TIDL network binary file.
+    //! Used by the API, must be specified.
     std::string netBinFile;
 
     //! Path to the TIDL parameter binary file
     std::string netBinFile;
 
     //! Path to the TIDL parameter binary file
+    //! Used by the API, must be specified.
     std::string paramsBinFile;
 
     std::string paramsBinFile;
 
+    //! Map of layer index to layer group id. Used to override layer group
+    //! assigment for layers. Any layer not specified in this map will
+    //! retain its existing mapping.
+    std::map<int, int> layerIndex2LayerGroupId;
+
     //! Enable tracing of output buffers associated with each layer
     bool enableOutputTrace;
 
     //! Enable tracing of output buffers associated with each layer
     bool enableOutputTrace;
 
@@ -98,21 +122,16 @@ class Configuration
 
     //! Debug - Shows total size of PARAM and NETWORK heaps. Also shows bytes
     //! available after all allocations. Can be used to adjust the heap
 
     //! Debug - Shows total size of PARAM and NETWORK heaps. Also shows bytes
     //! available after all allocations. Can be used to adjust the heap
-    //! size
+    //! size.
     bool showHeapStats;
 
     bool showHeapStats;
 
-    //! Map of layer index to layer group id. Used to override layer group
-    //! assigment for layers. Any layer not specified in this map will
-    //! retain its existing mapping.
-    std::map<int, int> layerIndex2LayerGroupId;
-
     //! Default constructor.
     Configuration();
 
     //! Validate the fields in the configuration object
     bool Validate() const;
 
     //! Default constructor.
     Configuration();
 
     //! Validate the fields in the configuration object
     bool Validate() const;
 
-    //! Print the configuration
+    //! Debug - Print the configuration.
     void Print(std::ostream& os = std::cout) const;
 
     //! Read a configuration from the specified file and validate
     void Print(std::ostream& os = std::cout) const;
 
     //! Read a configuration from the specified file and validate