[opencl] Added docs

qgis · Aug 8, 2018 · 329402a · 329402a
1 parent 5aa5465
commit 329402a
Show file tree

Hide file tree

Showing 2 changed files with 37 additions and 3 deletions.
diff --git a/src/core/qgsopenclutils.cpp b/src/core/qgsopenclutils.cpp
@@ -186,9 +186,9 @@ QString QgsOpenClUtils::sourceFromBaseName( const QString &baseName )
   return sourceFromPath( path );
 }
 
-QString QgsOpenClUtils::buildLog( cl::BuildError &e )
+QString QgsOpenClUtils::buildLog( cl::BuildError &error )
 {
-  cl::BuildLogType build_logs = e.getBuildLog();
+  cl::BuildLogType build_logs = error.getBuildLog();
   QString build_log;
   if ( build_logs.size() > 0 )
     build_log = QString::fromStdString( build_logs[0].second );

diff --git a/src/core/qgsopenclutils.h b/src/core/qgsopenclutils.h
@@ -44,12 +44,20 @@ class CORE_EXPORT QgsOpenClUtils
 {
   public:
 
+    /**
+     * The ExceptionBehavior enum define how exceptions generated by OpenCL should be treated
+     */
     enum ExceptionBehavior
     {
       Catch,  // Write errors in the message log and silently fail
       Throw   // Write errors in the message log and re-throw exceptions
     };
 
+    /**
+     * The Info enum maps to OpenCL info constants
+     *
+     * \see deviceInfo()
+     */
     enum Info
     {
       Name = CL_DEVICE_NAME,
@@ -62,14 +70,38 @@ class CORE_EXPORT QgsOpenClUtils
       MaxMemAllocSize = CL_DEVICE_MAX_MEM_ALLOC_SIZE
     };
 
+    //! Returs true if OpenCL is enabled in the user settings
     static bool enabled();
+
+    /**
+     * Checks whether a suitable OpenCL platform and device is found on this system and initialize the QGIS OpenCL system
+     * This function must be called before using QGIS OpenCL utils
+     */
     static bool available();
+
+    //! Set the OpenCL user setting to \a enabled
     static void setEnabled( bool enabled );
-    static QString buildLog( cl::BuildError &e );
+
+    //! Extract and return the build log error from \a error
+    static QString buildLog( cl::BuildError &error );
+
+    //! Read an OpenCL source file from \a path
     static QString sourceFromPath( const QString &path );
+
+    //! Return the full path to a an OpenCL source file from the \a baseName ('.cl' extension is automatically appended)
     static QString sourceFromBaseName( const QString &baseName );
+
+    //! OpenCL string for message logs
     static QLatin1String LOGMESSAGE_TAG;
+
+    //! Return a string representation from an OpenCL \a errorCode
     static QString errorText( const int errorCode );
+
+    /**
+     * Build the program from \a source in the given \a context and depending on \a exeptionBehavior
+     * can throw or catch the exceptions
+     * \return the built program
+     */
     static cl::Program buildProgram( const cl::Context &context, const QString &source, ExceptionBehavior exceptionBehavior = Catch );
 
     /**
@@ -80,6 +112,8 @@ class CORE_EXPORT QgsOpenClUtils
      *         and enabled
      */
     static cl::Context context();
+
+
     static QString sourcePath();
     static void setSourcePath( const QString &value );
     static QString deviceInfo( const Info infoType = Info::Name );