Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Improved documentation.

  • Loading branch information...
commit c355b693fe18e6f6790364558541deb3e09369cb 1 parent fd59fa5
@stephanemagnenat stephanemagnenat authored
View
2  Doxyfile.in
@@ -1244,7 +1244,7 @@ INCLUDE_FILE_PATTERNS =
# undefined via #undef or recursively expanded use the := operator
# instead of the = operator.
-PREDEFINED =
+PREDEFINED = HAVE_OPENCL
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
# this tag can be used to specify a list of macro names that should be expanded.
View
8 nabo/kdtree_cpu.cpp
@@ -53,6 +53,10 @@ namespace Nabo
using namespace std;
+ //! Return the number of bit required to store a value
+ /** \param v value to store
+ * \return number of bits required
+ */
template<typename T>
T getStorageBitCount(T v)
{
@@ -65,6 +69,10 @@ namespace Nabo
return 64;
}
+ //! Return the index of the maximum value of a vector
+ /** \param v vector
+ * \return index of maximum value, 0 if the vector is empty
+ */
template<typename T>
size_t argMax(const typename NearestNeighbourSearch<T>::Vector& v)
{
View
32 nabo/kdtree_opencl.cpp
@@ -54,6 +54,7 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
namespace cl
{
+ //! Vector of device
typedef std::vector<Device> Devices;
}
@@ -67,19 +68,25 @@ namespace Nabo
using namespace std;
+ //! Template to retrieve type-specific code for CL support
template<typename T>
struct EnableCLTypeSupport {};
+ //! CL support code for float
template<> struct EnableCLTypeSupport<float>
{
+ //! Return CL code to enable float support and set it for use by our CL code
static string code(const cl::Device& device)
{
return "typedef float T;\n";
}
};
+ //! CL support code for double
template<> struct EnableCLTypeSupport<double>
{
+ //! Return CL code to enable double support and set it for use by our CL code.
+ /** This is more complex than float as double is not supported by default. */
static string code(const cl::Device& device)
{
string s;
@@ -97,15 +104,19 @@ namespace Nabo
}
};
+ //! Cache CL source code (including defines and support code)
struct SourceCacher
{
+ //! Vector of devices
typedef std::vector<cl::Device> Devices;
+ //! Map of cached programmes
typedef std::map<std::string, cl::Program> ProgramCache;
- cl::Context context;
- Devices devices;
- ProgramCache cachedPrograms;
+ cl::Context context; //!< context in which programs are cached
+ Devices devices; //!< devices linked to the context
+ ProgramCache cachedPrograms; //!< cached programs
+ //! Create a source cacher for a given device type, retrieves a list of devices
SourceCacher(const cl_device_type deviceType)
{
// looking for platforms, AMD drivers do not like the default for creating context
@@ -140,29 +151,34 @@ namespace Nabo
throw runtime_error("No devices on OpenCL platform");
}
+ //! Destroy the cache, programs will be released automatically
~SourceCacher()
{
cerr << "Destroying source cacher containing " << cachedPrograms.size() << " cached programs" << endl;
}
+ //! Return whether program source is cached
bool contains(const std::string& source)
{
return cachedPrograms.find(source) != cachedPrograms.end();
}
};
+ //! Create and manage CL contexts and corresponding source caches
class ContextManager
{
public:
+ //! A map from device to caches
typedef std::map<cl_device_type, SourceCacher*> Devices;
- ContextManager() {}
+ //! Destroy the manager and all caches
~ContextManager()
{
cerr << "Destroying CL context manager, used " << devices.size() << " contexts" << endl;
for (Devices::iterator it(devices.begin()); it != devices.end(); ++it)
delete it->second;
}
+ //! Create a new contexc for a given type of device
cl::Context& createContext(const cl_device_type deviceType)
{
boost::mutex::scoped_lock lock(mutex);
@@ -175,6 +191,7 @@ namespace Nabo
}
return it->second->context;
}
+ //! Return the cache for a given type of device
SourceCacher* getSourceCacher(const cl_device_type deviceType)
{
boost::mutex::scoped_lock lock(mutex);
@@ -185,10 +202,11 @@ namespace Nabo
}
protected:
- Devices devices;
- boost::mutex mutex;
+ Devices devices; //!< devices with caches
+ boost::mutex mutex; //!< mutex to protect concurrent accesses to devices
};
+ //! Static instance of context manager
static ContextManager contextManager;
template<typename T>
@@ -200,7 +218,7 @@ namespace Nabo
}
template<typename T>
- void OpenCLSearch<T>::initOpenCL(const char* clFileName, const char* kernelName, const string& additionalDefines)
+ void OpenCLSearch<T>::initOpenCL(const char* clFileName, const char* kernelName, const std::string& additionalDefines)
{
const bool collectStatistics(creationOptionFlags & NearestNeighbourSearch<T>::TOUCH_STATISTICS);
View
8 nabo/nabo.h
@@ -170,13 +170,13 @@ namespace Nabo
{
//! Create an empty parameter vector
Parameters(){}
- /*! Create a parameter vector with a single entry
- * \param key entry key
+ //! Create a parameter vector with a single entry
+ /** \param key entry key
* \param value entry value
*/
Parameters(const std::string& key, const boost::any& value){(*this)[key] = value;}
- /*! Get the value of a key, return defaultValue if the key does not exist
- * \param key requested key
+ //! Get the value of a key, return defaultValue if the key does not exist
+ /** \param key requested key
* \param defaultValue value to return if the key does not exist
* \return value of the key, or defaultValue if the key does not exist
*/
View
98 nabo/nabo_private.h
@@ -148,8 +148,8 @@ namespace Nabo
const T* pt; //!< pointer to first value of point data, 0 if end of bucket
Index index; //!< index of point
- /*! create a new bucket entry for a point in the data
- * \param pt pointer to first component of the point, components must be continuous
+ //! create a new bucket entry for a point in the data
+ /** \param pt pointer to first component of the point, components must be continuous
* \param index index of the point in the data
*/
BucketEntry(const T* pt = 0, const Index index = 0): pt(pt), index(index) {}
@@ -205,13 +205,19 @@ namespace Nabo
using NearestNeighbourSearch<T>::checkSizesKnn;
protected:
- const cl_device_type deviceType;
- cl::Context& context;
- cl::Kernel knnKernel;
- cl::CommandQueue queue;
- cl::Buffer cloudCL;
+ const cl_device_type deviceType; //!< the type of device to run CL code on (CL_DEVICE_TYPE_CPU or CL_DEVICE_TYPE_GPU)
+ cl::Context& context; //!< the CL context
+ cl::Kernel knnKernel; //!< the kernel to perform knnSearch
+ cl::CommandQueue queue; //!< the command queue
+ cl::Buffer cloudCL; //!< the buffer for the input data
+ //! constructor, calls NearestNeighbourSearch<T>(cloud)
OpenCLSearch(const Matrix& cloud, const Index dim, const unsigned creationOptionFlags, const cl_device_type deviceType);
+ //! Initialize CL support
+ /** \param clFileName name of file containing CL code
+ * \param kernelName name of the CL kernel function
+ * \param additionalDefines additional CL code to pass to compiler
+ */
void initOpenCL(const char* clFileName, const char* kernelName, const std::string& additionalDefines = "");
public:
@@ -228,6 +234,7 @@ namespace Nabo
using OpenCLSearch<T>::initOpenCL;
+ //! constructor, calls OpenCLSearch<T>(cloud, ...)
BruteForceSearchOpenCL(const Matrix& cloud, const Index dim, const unsigned creationOptionFlags, const cl_device_type deviceType);
};
@@ -253,44 +260,57 @@ namespace Nabo
using OpenCLSearch<T>::initOpenCL;
protected:
+ //! Point during kd-tree construction
struct BuildPoint
{
- Vector pos;
- size_t index;
+ Vector pos; //!< point
+ size_t index; //!< index of point in cloud
+ //! Construct a build point, at a given pos with a specific index
BuildPoint(const Vector& pos = Vector(), const size_t index = 0): pos(pos), index(index) {}
};
+ //! points during kd-tree construction
typedef std::vector<BuildPoint> BuildPoints;
+ //! iterator to points during kd-tree construction
typedef typename BuildPoints::iterator BuildPointsIt;
+ //! const-iterator to points during kd-tree construction
typedef typename BuildPoints::const_iterator BuildPointsCstIt;
+ //! Functor to compare point values on a given dimension
struct CompareDim
{
- size_t dim;
+ size_t dim; //!< dimension on which to compare
+ //! Build the functor for a specific dimension
CompareDim(const size_t dim):dim(dim){}
+ //! Compare the values of p0 and p1 on dim, and return whether p0[dim] < p1[dim]
bool operator() (const BuildPoint& p0, const BuildPoint& p1) { return p0.pos(dim) < p1.pos(dim); }
};
+ //! Tree node for CL
struct Node
{
- int dim; // -1 == invalid, <= -2 = index of pt
- T cutVal;
- Node(const int dim = -1, const T cutVal = 0):
- dim(dim), cutVal(cutVal) {}
+ int dim; //!< dimension of the cut, or, if negative, index of the point: -1 == invalid, <= -2 = index of pt
+ T cutVal; //!< value of the cut
+ //! Build a tree node, with a given dimension and value to cut on, or, if leaf and dim <= -2, the index of the point as (-dim-2)
+ Node(const int dim = -1, const T cutVal = 0):dim(dim), cutVal(cutVal) {}
};
+ //! dense vector of search nodes
typedef std::vector<Node> Nodes;
- Nodes nodes;
+ Nodes nodes; //!< search nodes
+ cl::Buffer nodesCL; //!< CL buffer for search nodes
+
- cl::Buffer nodesCL;
+ inline size_t childLeft(size_t pos) const { return 2*pos + 1; } //!< Return the left child of pos
+ inline size_t childRight(size_t pos) const { return 2*pos + 2; } //!< Return the right child of pos
+ inline size_t parent(size_t pos) const { return (pos-1)/2; } //!< Return the parent of pos
+ size_t getTreeDepth(size_t size) const; //!< Return the max depth of a tree of a given size
+ size_t getTreeSize(size_t size) const; //!< Return the storage size of tree of a given size
- inline size_t childLeft(size_t pos) const { return 2*pos + 1; }
- inline size_t childRight(size_t pos) const { return 2*pos + 2; }
- inline size_t parent(size_t pos) const { return (pos-1)/2; }
- size_t getTreeDepth(size_t size) const;
- size_t getTreeSize(size_t size) const;
+ //! Recurse to build nodes
void buildNodes(const BuildPointsIt first, const BuildPointsIt last, const size_t pos, const Vector minValues, const Vector maxValues);
public:
+ //! constructor, calls OpenCLSearch<T>(cloud, ...)
KDTreeBalancedPtInLeavesStackOpenCL(const Matrix& cloud, const Index dim, const unsigned creationOptionFlags, const cl_device_type deviceType);
};
@@ -316,38 +336,52 @@ namespace Nabo
using OpenCLSearch<T>::initOpenCL;
protected:
+ //! a point during kd-tree construction is just its index
typedef Index BuildPoint;
+ //! points during kd-tree construction
typedef std::vector<BuildPoint> BuildPoints;
+ //! iterator to points during kd-tree construction
typedef typename BuildPoints::iterator BuildPointsIt;
+ //! const-iterator to points during kd-tree construction
typedef typename BuildPoints::const_iterator BuildPointsCstIt;
+ //! Functor to compare point values on a given dimension
struct CompareDim
{
- const Matrix& cloud;
- size_t dim;
+ const Matrix& cloud; //!< reference to data points used to compare
+ size_t dim; //!< dimension on which to compare
+ //! Build the functor for a specific dimension on a specific cloud
CompareDim(const Matrix& cloud, const size_t dim): cloud(cloud), dim(dim){}
+ //! Compare the values of p0 and p1 on dim, and return whether p0[dim] < p1[dim]
bool operator() (const BuildPoint& p0, const BuildPoint& p1) { return cloud.coeff(dim, p0) < cloud.coeff(dim, p1); }
};
+ //! Tree node for CL
struct Node
{
- int dim; // >=0 cut dim, -1 == leaf, -2 == invalid
- Index index;
+ int dim; //!< dimension of the cut, or, if -1 == leaf, -2 == invalid
+ Index index; //!< index of the point to cut
+ //! Build a tree node, with a given index and a given dimension to cut on
Node(const int dim = -2, const Index index = 0):dim(dim), index(index) {}
};
+ //! dense vector of search nodes
typedef std::vector<Node> Nodes;
- Nodes nodes;
- cl::Buffer nodesCL;
+ Nodes nodes; //!< search nodes
+ cl::Buffer nodesCL; //!< CL buffer for search nodes
+
+
+ inline size_t childLeft(size_t pos) const { return 2*pos + 1; } //!< Return the left child of pos
+ inline size_t childRight(size_t pos) const { return 2*pos + 2; } //!< Return the right child of pos
+ inline size_t parent(size_t pos) const { return (pos-1)/2; } //!< Return the parent of pos
+ size_t getTreeDepth(size_t size) const; //!< Return the max depth of a tree of a given size
+ size_t getTreeSize(size_t size) const; //!< Return the storage size of tree of a given size
- inline size_t childLeft(size_t pos) const { return 2*pos + 1; }
- inline size_t childRight(size_t pos) const { return 2*pos + 2; }
- inline size_t parent(size_t pos) const { return (pos-1)/2; }
- size_t getTreeDepth(size_t size) const;
- size_t getTreeSize(size_t size) const;
+ //! Recurse to build nodes
void buildNodes(const BuildPointsIt first, const BuildPointsIt last, const size_t pos, const Vector minValues, const Vector maxValues);
public:
+ //! constructor, calls OpenCLSearch<T>(cloud, ...)
KDTreeBalancedPtInNodesStackOpenCL(const Matrix& cloud, const Index dim, const unsigned creationOptionFlags, const cl_device_type deviceType);
};
Please sign in to comment.
Something went wrong with that request. Please try again.