Restructure and more docs fixes. Write readme

Author: Derpius

CMakeLists.txt

@@ -52,4 +52,5 @@ add_library(BSPParser
         src/displacements/sub-edge-iterator.cpp
         src/displacements/normal-blending.cpp
         src/displacements/normal-blending.hpp
+        src/phys-model.hpp
 )

README.md

@@ -4,12 +4,110 @@ Simple and modern library for parsing the Valve BSP map format.
 
 Documentation: https://taservers.github.io/BSPParser/
 
-See also: https://github.com/TAServers/MDLParser and https://github.com/TAServers/VTFParser
+See also:
+
+- https://github.com/TAServers/MDLParser
+- https://github.com/TAServers/VTFParser
+- https://github.com/TAServers/PHYParser
 
 ## What's included
 
-TODO
+- Class for parsing and abstracing the `BSP` file format for the Source engine.
+- Helper functions to simplify accessing the complex data structures of the BSP (see example below)
+- Enums and structs with decent coverage of the BSP lumps and their versions.
+- Runtime errors for issues when parsing the data due to corruption or a bug in the parser.
 
 ## Example
 
-TODO
+Generating a triangle list for all models in the BSP:
+
+```cpp
+#include "BSPParser.hpp"
+
+// Load from a file on disk, an API, or somewhere in memory
+const auto bspData = ...;
+
+// Parse the data (you should wrap this in a try/catch)
+const BspParser::Bsp bsp(bspData);
+
+// We want to render the BSP, so pay the performance cost of smoothing displacement normals
+bsp.smoothNeighbouringDisplacements();
+
+// For each model...
+BspParser::Accessors::iterateModels(
+  bsp,
+  [&bsp](
+    const BspParser::Structs::Model& model,
+    const std::vector<BspParser::PhysModel>& physicsModels
+  ) {
+    // For each face...
+    BspParser::Accessors::iterateFaces(
+      bsp,
+      model,
+      [&bsp](
+        const BspParser::Structs::Face& face,
+        const BspParser::Structs::Plane& plane,
+        const BspParser::Structs::TexInfo& textureInfo,
+        const std::span<const int32_t> surfaceEdges
+      ) {
+        if (isFaceNoDraw(surfaceEdges, textureInfo)) {
+          return;
+        }
+
+        // For each vertex... (you can use getVertexCount to preallocate memory for a single face or the whole BSP)
+        BspParser::Accessors::generateVertices(
+          bsp,
+          face,
+          plane,
+          textureInfo,
+          surfaceEdges,
+          [](const BspParser::Vertex& vertex) {
+            // Use vertex.position, vertex.normal, etc.
+          }
+        );
+
+        // For each index... (you can use getTriangleListIndexCount to preallocate memory here too)
+        BspParser::Accessors::generateTriangleListIndices(
+          bsp,
+          face,
+          surfaceEdges,
+          [](const int32_t index0, const int32_t index1, const int32_t index2) {
+            // Use triangle indices (always clockwise winding)
+          }
+        );
+      }
+    );
+  }
+);
+```
+
+Generating colliders for all physmeshes in the BSP:
+
+```cpp
+#include "BSPParser.hpp"
+
+// Load from a file on disk, an API, or somewhere in memory
+const auto bspData = ...;
+
+// Parse the data (you should wrap this in a try/catch)
+const BspParser::Bsp bsp(bspData);
+
+// We don't want to render the BSP, so don't smooth normals this time
+// bsp.smoothNeighbouringDisplacements();
+
+// For each model...
+BspParser::Accessors::iterateModels(
+  bsp,
+  [&bsp](
+    const BspParser::Structs::Model& model,
+    const std::vector<BspParser::PhysModel>& physicsModels
+  ) {
+    for (const auto& physicsModel : physicsModels) {
+      // You don't have to use PhyParser here, any solution for parsing .phy file data will do
+      const auto [solidsForModel, _] = PhyParser::parseSurfaces(physicsModel.collisionData, physicsModel.solidCount);
+
+      // Use solids to build your colliders...
+    }
+  }
+);
+```

src/accessors/face-accessors.cpp

@@ -15,9 +15,9 @@ namespace BspParser::Accessors {
 
   void iterateModels(
     const Bsp& bsp,
-    const std::function<void(const Structs::Model& model, const std::vector<Bsp::PhysModel>& physicsModels)>& iteratee
+    const std::function<void(const Structs::Model& model, const std::vector<PhysModel>& physicsModels)>& iteratee
   ) {
-    std::vector<Bsp::PhysModel> physicsModels;
+    std::vector<PhysModel> physicsModels;
 
     for (int32_t modelIndex = 0; modelIndex < bsp.models.size(); modelIndex++) {
       physicsModels.clear();

src/accessors/face-accessors.hpp

@@ -17,7 +17,7 @@ namespace BspParser::Accessors {
    */
   void iterateModels(
     const Bsp& bsp,
-    const std::function<void(const Structs::Model& model, const std::vector<Bsp::PhysModel>& physicsModels)>& iteratee
+    const std::function<void(const Structs::Model& model, const std::vector<PhysModel>& physicsModels)>& iteratee
   );
 
   /**

src/bsp.cpp

@@ -127,7 +127,7 @@ namespace BspParser {
     );
   }
 
-  std::vector<Bsp::PhysModel> Bsp::parsePhysCollideLump() const {
+  std::vector<PhysModel> Bsp::parsePhysCollideLump() const {
     const auto& lumpHeader = header->lumps.at(static_cast<size_t>(Enums::Lump::PhysCollide));
     assertLumpHeaderValid(Enums::Lump::PhysCollide, lumpHeader);
 

src/bsp.hpp

@@ -1,6 +1,7 @@
 #pragma once
 
 #include "errors.hpp"
+#include "phys-model.hpp"
 #include "displacements/triangulated-displacement.hpp"
 #include "enums/lump.hpp"
 #include "helpers/offset-data-view.hpp"
@@ -26,31 +27,6 @@ namespace BspParser {
    * @note Does not take ownership of the passed data. It is your responsibility to ensure the lifetime of the BSP does not exceed that of the underlying data.
    */
   struct Bsp {
-    /**
-     * Raw physmesh solid and text data for a given model.
-     */
-    struct PhysModel {
-      /**
-       * Index into the model lump this physics model is for
-       */
-      int32_t modelIndex;
-
-      /**
-       * Total number of solids in the collision surface sections
-       */
-      int32_t solidCount;
-
-      /**
-       * Raw .PHY solid data. Use `PhyParser::parseSurfaces` from the accompanying PHYParser library to parse this.
-       */
-      std::span<const std::byte> collisionData;
-
-      /**
-       * Raw .PHY text section data. Use `PhyParser::parseTextSection` from the accompanying PHYParser library to parse this.
-       */
-      std::span<const std::byte> textSectionData;
-    };
-
     explicit Bsp(std::span<const std::byte> data);
 
     std::span<const std::byte> data;

src/phys-model.hpp

@@ -0,0 +1,31 @@
+#pragma once
+
+#include <cstdint>
+#include <span>
+
+namespace BspParser {
+  /**
+   * Raw physmesh solid and text data for a given model.
+   */
+  struct PhysModel {
+    /**
+     * Index into the model lump this physics model is for
+     */
+    int32_t modelIndex = 0;
+
+    /**
+     * Total number of solids in the collision surface sections
+     */
+    int32_t solidCount = 0;
+
+    /**
+     * Raw .PHY solid data. Use `PhyParser::parseSurfaces` from the accompanying PHYParser library to parse this.
+     */
+    std::span<const std::byte> collisionData;
+
+    /**
+     * Raw .PHY text section data. Use `PhyParser::parseTextSection` from the accompanying PHYParser library to parse this.
+     */
+    std::span<const std::byte> textSectionData;
+  };
+}