📝 Add some comments

plugins/csp-atmospheres/bruneton-preprocessor/Metadata.hpp

@@ -12,19 +12,19 @@
 
 #include <glm/glm.hpp>
 
+/// The preprocessor not only generates textures, but also some metadata which is needed to render
+/// the atmosphere. This struct is used to store this metadata.
 struct Metadata {
-  /// The angular radius of the Sun needs to be specified. As SPICE is not fully available when
-  /// the plugin is loaded, we cannot compute it. Also, this actually varies in reality.
+  /// The angular radius of the Sun as well as the RGB illuminance at the planet's average distance
+  /// to the Sun is required during rendering.
   float     mSunAngularRadius{};
   glm::vec3 mSunIlluminance{};
 
-  /// Larger values reduce circular banding artifacts around sun for thick atmospheres.
+  /// As the scattering textures are 4D textures stored in 3D textures, we need to know the number
+  /// of textures packed next to each other in the layers of the 3D texture.
   int32_t mScatteringTextureNuSize{};
 
-  /// The maximum Sun zenith angle for which atmospheric scattering must be precomputed, in
-  /// radians (for maximum precision, use the smallest Sun zenith angle yielding negligible sky
-  /// light radiance values. For instance, for the Earth case, 102 degrees is a good choice for
-  /// most cases (120 degrees is necessary for very high exposure values).
+  /// The maximum Sun zenith angle for which atmospheric scattering was be precomputed.
   float mMaxSunZenithAngle{};
 };
 

plugins/csp-atmospheres/bruneton-preprocessor/Params.hpp

@@ -11,20 +11,13 @@
 
 #include "../../../../src/cs-core/Settings.hpp"
 
-/// This atmospheric model is based on an implementation of multiple-scattering by Eric Bruneton.
-/// The main difference to the original implementation is that this variant uses phase functions,
-/// extinction coefficients, and density distributions loaded from CSV files instead of analytic
-/// descriptions.
-/// More information on the original implementation can be found in the repo by Eric Bruneton:
-/// https://github.com/ebruneton/precomputed_atmospheric_scattering as well as in his paper
-/// "Precomputed Atmospheric Scattering" (https://hal.inria.fr/inria-00288758/en).
-/// The default values for the model parameters further down this file are based on the parameters
-/// from Eric Bruneton:
+/// The default values for the preprocessor parameters further down this file are based on the
+/// parameters from Eric Bruneton:
 /// https://github.com/ebruneton/precomputed_atmospheric_scattering/blob/master/atmosphere/constants.h
 struct Params {
 
   /// This stores file paths to the CSV files containing the respective data. See the README of
-  /// this plugin for a more detailed description.
+  /// this preprocessor for a more detailed description.
   struct ScatteringComponent {
     std::string mPhaseFile;
     std::string mBetaScaFile;
@@ -48,7 +41,7 @@ struct Params {
   };
 
   /// This stores file paths to the CSV files containing the respective data. See the README of
-  /// this plugin for a more detailed description.
+  /// this preprocessor for a more detailed description.
   struct AbsorbingComponent {
     std::string mBetaAbsFile;
     std::string mDensityFile;

plugins/csp-atmospheres/bruneton-preprocessor/Preprocessor.cpp

@@ -23,9 +23,11 @@
 
 // While implementing the atmospheric model into CosmoScout VR, we have refactored some parts of the
 // code, however this is mostly related to how variables are named and how input parameters are
-// passed to the model. The only fundamental change is that the phase functions for aerosols and
-// molecules as well as their density distributions are now loaded from CSV files and then later
-// sampled from textures.
+// passed to the model.
+// Architecture-wise, the main difference is that the preprocessing is now done offline, so all code
+// which is only required during rendering has been refactored out. Functionality-wise, the only
+// fundamental change is that the phase functions for aerosols and molecules as well as their
+// density distributions are now loaded from CSV files and then later sampled from textures.
 
 // Below, we will indicate for each group of function whether something has been changed and a link
 // to the original explanations of the methods by Eric Bruneton.

plugins/csp-atmospheres/bruneton-preprocessor/Preprocessor.hpp

@@ -19,14 +19,14 @@
 #include <string>
 #include <vector>
 
-/// The C++ implementation of this atmospheric model is based on this class by Eric Bruneton:
+/// The preprocessor is based on this class by Eric Bruneton:
 /// https://github.com/ebruneton/precomputed_atmospheric_scattering/blob/master/atmosphere/model.h
 /// While we refactored / restyled large parts of the code, the overall flow of control remains the
 /// same.
-
+/// See the source file for more information.
 class Preprocessor {
  public:
-  /// If only three wavelengths are used during rendering, these three are used:
+  /// If only three wavelengths are used during preprocessing, these three are used:
   static constexpr float kLambdaR = 680.0;
   static constexpr float kLambdaG = 550.0;
   static constexpr float kLambdaB = 440.0;

plugins/csp-atmospheres/bruneton-preprocessor/main.cpp

@@ -24,6 +24,10 @@ void printHelp() {
 }
 
 ////////////////////////////////////////////////////////////////////////////////////////////////////
+// This preprocessor loads the CSV files containing the scattering data and precomputes the       //
+// textures which are needed to render the atmosphere. The preprocessor is based on the           //
+// implementation by Eric Bruneton: https://github.com/ebruneton/precomputed_atmospheric_scattering
+// See the Preprocessor class for more information.                                               //
 ////////////////////////////////////////////////////////////////////////////////////////////////////
 
 int main(int argc, char** argv) {
@@ -95,7 +99,7 @@ int main(int argc, char** argv) {
                              "they should be exactly for 440 nm, 550 nm, and 680 nm!");
   }
 
-  // Initialize SDL
+  // Initialize SDL.
   if (SDL_Init(SDL_INIT_VIDEO) < 0) {
     SDL_Log("Unable to initialize SDL: %s", SDL_GetError());
     return 1;
@@ -106,7 +110,7 @@ int main(int argc, char** argv) {
   SDL_GL_SetAttribute(SDL_GL_CONTEXT_MINOR_VERSION, 3);
   SDL_GL_SetAttribute(SDL_GL_CONTEXT_PROFILE_MASK, SDL_GL_CONTEXT_PROFILE_CORE);
 
-  // Create a window (invisible)
+  // Create a window (invisible).
   SDL_Window* window = SDL_CreateWindow("OpenGL", SDL_WINDOWPOS_UNDEFINED, SDL_WINDOWPOS_UNDEFINED,
       0, // width
       0, // height
@@ -118,10 +122,10 @@ int main(int argc, char** argv) {
     return 1;
   }
 
-  // Create OpenGL context
+  // Create OpenGL context.
   SDL_GLContext context = SDL_GL_CreateContext(window);
 
-  // Initialize GLEW
+  // Initialize GLEW.
   glewExperimental = GL_TRUE;
   if (glewInit() != GLEW_OK) {
     SDL_Log("Failed to initialize GLEW");
@@ -138,9 +142,10 @@ int main(int argc, char** argv) {
   // Create the output directory if it does not exist.
   cs::utils::filesystem::createDirectoryRecursively(boost::filesystem::system_complete(cOutput));
 
+  // Save the precomputed textures.
   preprocessor.save(cOutput);
 
-  // Clean up
+  // Clean up.
   SDL_GL_DeleteContext(context);
   SDL_DestroyWindow(window);
   SDL_Quit();