Merge branch 'improve_docs'

.gitignore

@@ -1,7 +1,7 @@
 build
 render.ppm
-RayTracerTest
 *.o
 *.obj
 *.exe
-doxygen
+doxygen/html
+examples/Basic

CMakeLists.txt

@@ -14,14 +14,14 @@ if((CMAKE_CXX_COMPILER_ID STREQUAL GNU) OR (CMAKE_CXX_COMPILER_ID MATCHES Clang)
   set(cxxflags ${gnu_cxxflags})
 endif((CMAKE_CXX_COMPILER_ID STREQUAL GNU) OR (CMAKE_CXX_COMPILER_ID MATCHES Clang))
 
-add_library(Fast_BVH INTERFACE)
+add_library(FastBVH INTERFACE)
 
-target_include_directories(Fast_BVH INTERFACE "${CMAKE_CURRENT_SOURCE_DIR}/include")
+target_include_directories(FastBVH INTERFACE "${CMAKE_CURRENT_SOURCE_DIR}/include")
 
-add_executable(Fast_BVH_RayTracerTest RayTracerTest.cpp)
+add_executable(FastBVH_RayTracerTest RayTracerTest.cpp)
 
-target_link_libraries(Fast_BVH_RayTracerTest PRIVATE Fast_BVH)
+target_link_libraries(FastBVH_RayTracerTest PRIVATE FastBVH)
 
-target_compile_options(Fast_BVH_RayTracerTest PRIVATE ${cxxflags})
+target_compile_options(FastBVH_RayTracerTest PRIVATE ${cxxflags})
 
-set_target_properties(Fast_BVH_RayTracerTest PROPERTIES OUTPUT_NAME RayTracerTest)
+set_target_properties(FastBVH_RayTracerTest PROPERTIES OUTPUT_NAME RayTracerTest)

Doxyfile

@@ -32,7 +32,7 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = "Fast BVH"
+PROJECT_NAME           = "Fast-BVH"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version
@@ -790,7 +790,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = "include/fast_bvh"
+INPUT                  = "include/fast_bvh" "doxygen"
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -815,50 +815,7 @@ INPUT_ENCODING         = UTF-8
 # *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f95, *.f03, *.f08,
 # *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf and *.qsf.
 
-FILE_PATTERNS          = *.c \
-                         *.cc \
-                         *.cxx \
-                         *.cpp \
-                         *.c++ \
-                         *.java \
-                         *.ii \
-                         *.ixx \
-                         *.ipp \
-                         *.i++ \
-                         *.inl \
-                         *.idl \
-                         *.ddl \
-                         *.odl \
-                         *.h \
-                         *.hh \
-                         *.hxx \
-                         *.hpp \
-                         *.h++ \
-                         *.cs \
-                         *.d \
-                         *.php \
-                         *.php4 \
-                         *.php5 \
-                         *.phtml \
-                         *.inc \
-                         *.m \
-                         *.markdown \
-                         *.md \
-                         *.mm \
-                         *.dox \
-                         *.py \
-                         *.pyw \
-                         *.f90 \
-                         *.f95 \
-                         *.f03 \
-                         *.f08 \
-                         *.f \
-                         *.for \
-                         *.tcl \
-                         *.vhd \
-                         *.vhdl \
-                         *.ucf \
-                         *.qsf
+FILE_PATTERNS          = *.h *.md
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.
@@ -982,7 +939,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE =
+USE_MDFILE_AS_MAINPAGE = "doxygen/README.md"
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing

Makefile

@@ -6,30 +6,36 @@ CXXFLAGS := $(CXXFLAGS) -std=c++14
 
 VPATH += include/fast_bvh
 
+headers := include/FastBVH/BBox.h \
+           include/FastBVH/BVH.h \
+           include/FastBVH/IntersectionInfo.h \
+           include/FastBVH/Ray.h \
+           include/FastBVH/Traverser.h \
+           include/FastBVH/Vector3.h
+
+example_headers := examples/Log.h \
+                   examples/Sphere.h \
+                   examples/Stopwatch.h
+
+examples := examples/Basic
+
 .PHONY: all
 all: simple-target
 
 .PHONY: simple-target
-simple-target: RayTracerTest
-
-RayTracerTest: RayTracerTest.o
-	$(CXX) $(LDFLAGS) $^ -o $@ $(LDLIBS)
-
-RayTracerTest.o: RayTracerTest.cpp BVH.h BBox.h Ray.h Vector3.h Log.h \
- Object.h IntersectionInfo.h Sphere.h
+simple-target: $(examples)
 
-BBox.o: BBox.cpp BBox.h Ray.h Vector3.h Log.h
+examples/Basic: examples/Basic.cpp $(headers) $(example_headers)
 
-BVH.o: BVH.cpp BVH.h BBox.h Ray.h Vector3.h Log.h Object.h \
- IntersectionInfo.h Stopwatch.h
+examples/%: examples/%.cpp
+	$(CXX) $(CXXFLAGS) $< -o $@
 
 .PHONY: clean
 clean:
-	$(RM) RayTracerTest *.o
+	$(RM) $(examples)
 
 .PHONY: test
-test: RayTracerTest
-	./RayTracerTest
+test:
 
 .PHONY: docs
 docs:

doxygen/GettingStarted.md

@@ -0,0 +1,68 @@
+Getting Started
+===============
+
+### Installation
+
+Since Fast-BVH is a header-only library, all you have to to is get the header files into an include directory your project can use.
+
+You can do this either by:
+
+ - Copying all the files into a directory in your project, like `third-party/Fast-BVH/include` or something similar
+ - Add the project to yours as a [git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
+ - Download a ZIP file of the project and extract it to your a place in your project
+
+If your project uses CMake, you can add Fast-BVH as a subdirectory and link to the target `FastBVH` and CMake will take care of adding the include directories to the targets that use the library.
+For example:
+
+```cmake
+add_subdirectory(third-party/Fast-BVH)
+
+target_link_libraries(myAwesomeRayTracer PRIVATE FastBVH)
+```
+
+Note that even though the command is called `target_link_libraries`, there's no linking or compilation taking place.
+In CMake, `FastBVH` is an "interface" library. This means that it's only meant to relay things like include directories, compiler flags, etc.
+
+### Preparing the Scene Data
+
+Most ray tracers use primitive shapes to build a scene.
+For this example, we'll be using a sphere as a primitive shape.
+Just note that we could also be using a triangle, a voxel, or polygonal surface.
+
+```cxx
+#include <vector>
+
+struct Sphere final {
+  float x;
+  float y;
+  float z;
+  float radius;
+};
+
+int main() {
+
+  std::vector<Sphere> spheres;
+  spheres.emplace_back({ 0, 0, 0, 0.1 });
+  spheres.emplace_back({ 2, 0, 0, 1.0 });
+  spheres.emplace_back({ 1, 3, 2, 0.5 });
+
+  return 0;
+}
+```
+
+### Building a BVH
+
+Now that you've got the project in a usable format, you can start building your first BVH.
+
+Start by including the directory for the @ref FastBVH::BVH data structure.
+
+```cxx
+#include <FastBVH/BVH.h>
+
+int main() {
+
+  return 0;
+}
+```
+
+

doxygen/README.md

@@ -0,0 +1,13 @@
+Fast-BVH
+========
+
+Welcome to the documentation for the Fast-BVH project.
+Here you'll find reference to the various structures and interfaces,
+as well as some tutorials to help you get started.
+
+If you're here for reference material, you can go ahead and checkout the two main classes:
+
+ - @ref FastBVH::BVH
+ - @ref FastBVH::Traverser
+
+If you're here to learn, you can checkout out the [Getting Started](doxygen/GettingStarted.md) page.

RayTracerTest.cpp → examples/Basic.cpp

@@ -2,10 +2,12 @@
 #include <vector>
 #include <cstdlib>
 
-#include <fast_bvh/BVH.h>
-#include <fast_bvh/Traverser.h>
+#include <FastBVH/BVH.h>
+#include <FastBVH/Traverser.h>
 
+#include "Log.h"
 #include "Sphere.h"
+#include "Stopwatch.h"
 
 using std::vector;
 
@@ -33,8 +35,20 @@ int main() {
     objects.emplace_back(Sphere<float>(randVector3(), .005f));
   }
 
+  BVH<float, Sphere<float>> bvh;
+
+  Stopwatch sw;
+
   // Compute a BVH for this object set
-  BVH<float, Sphere<float>> bvh(std::move(objects));
+  bvh.build(std::move(objects));
+
+  // Output tree build time and statistics
+  double constructionTime = sw.read();
+
+  LOG_STAT("Built BVH (%u nodes, with %u leafs) in %.02f ms",
+           (unsigned int) bvh.getNodeCount(),
+           (unsigned int) bvh.getLeafCount(),
+           1000.0 * constructionTime);
 
   // Allocate space for some image pixels
   const unsigned int width=800, height=800;

Sphere.h → examples/Sphere.h

@@ -1,6 +1,6 @@
 #pragma once
 
-#include <fast_bvh/IntersectionInfo.h>
+#include <FastBVH/IntersectionInfo.h>
 
 #include <cmath>
 

include/fast_bvh/Stopwatch.h → examples/Stopwatch.h

@@ -4,7 +4,7 @@
 
 namespace FastBVH {
 
-//! Used for profiling the performance
+//! \brief Used for profiling the performance
 //! of the BVH construction.
 class Stopwatch final {
   //! A type definition for the clock used by this class.

include/fast_bvh/BBox.h → include/FastBVH/BBox.h

@@ -1,46 +1,84 @@
 #pragma once
 
-#include <fast_bvh/Ray.h>
-#include <fast_bvh/Vector3.h>
+#include <FastBVH/Ray.h>
+#include <FastBVH/Vector3.h>
 
 #include <utility>
 
 #include <cstdint>
 
 namespace FastBVH {
 
+//! \brief Represents an axis-aligned bounding box.
+//! This could also be called an AABB.
+//! It's used to represent the space occupied
+//! by a primitive.
+//! \tparam Float The floating point type used
+//! by the minimum and maximum point components.
 template <typename Float>
 struct BBox final {
 
+  //! A simple type definition for a 3D vector.
   using Vec3 = Vector3<Float>;
 
+  //! The minimum point of the bounding box.
   Vec3 min;
+  //! The maximum point of the bounding box.
   Vec3 max;
+  //! The difference between the max and min
+  //! points of the bounding box.
   Vec3 extent;
 
+  //! Constructs an uninitialized bounding box.
   constexpr BBox() noexcept { }
 
+  //! Constructs a bounding box with
+  //! a specified minimum and maximum.
   constexpr BBox(const Vec3& min, const Vec3& max) noexcept
     : min(min), max(max), extent(max - min) {}
 
+  //! Constructs a bounding box around
+  //! a single point. The volume occupied
+  //! by the box after using this construction
+  //! will always be zero.
   constexpr BBox(const Vec3& p) noexcept : BBox(p, p) {}
 
+  //! Expands the volume of the bounding box to fit a new point.
+  //! \param p The point to expand the volume for.
   void expandToInclude(const Vec3& p) noexcept {
     min = FastBVH::min(min, p);
     max = FastBVH::max(max, p);
     extent = max - min;
   }
 
+  //! Expands the volume of the bounding box to fit the space of another box.
+  //! \param b The box to expand the volume for.
   void expandToInclude(const BBox& b) noexcept {
     min = FastBVH::min(min, b.min);
     max = FastBVH::max(max, b.max);
     extent = max - min;
   }
 
+  //! Checks for intersection between a ray and the box.
+  //! \param ray The ray being traced.
+  //! \param tnear The scale to the nearest box hit.
+  //! \param tfar The scale to the farthest box hit.
+  //! \return True if the ray hits the box, false otherwise.
   bool intersect(const Ray<Float>& ray, Float *tnear, Float *tfar) const noexcept;
 
+  //! Determines the index of the dimension
+  //! that has the largest space between the
+  //! minimum and maximum points of the box.
+  //! \return The index of the dimension that
+  //! has the most amount of space between the
+  //! minimum and maximum box points. A value of
+  //! zero indicates the X-axis, a value of one
+  //! indicates the Y-axis, and a value of two
+  //! indicates the Z-axis.
   uint32_t maxDimension() const noexcept;
 
+  //! Calculates the surface area of the box.
+  //! \return The surface area of the bounding box.
   constexpr Float surfaceArea() const noexcept {
     return 2.0f * ((extent.x * extent.z) + (extent.x * extent.y) + (extent.y * extent.z));
   }