[#79] Update comments in header of asset_loader.

modules/asset_loader/include/vkcv/asset/asset_loader.hpp

@@ -11,17 +11,8 @@
 #include <cstdint>
 #include <filesystem>
 
-/** These macros define limits of the following structs. Implementations can
- * test against these limits when performing sanity checks. The main constraint
- * expressed is that of the data type: Material indices are identified by a
- * uint8_t in the VertexGroup struct, so there can't be more than UINT8_MAX
- * materials in the mesh. Should these limits be too narrow, the data type has
- * to be changed, but the current ones should be generous enough for most use
- * cases. */
-#define MAX_MATERIALS_PER_MESH UINT8_MAX
-#define MAX_VERTICES_PER_VERTEX_GROUP UINT32_MAX
-
-/** LOADING MESHES
+
+/* LOADING MESHES
  * The description of meshes is a hierarchy of structures with the Mesh at the
  * top.
  *
@@ -46,19 +37,25 @@
 
 namespace vkcv::asset {
 
-/* These return codes are limited to the asset loader module. If unified return
- * codes are defined for the vkcv framework, these will be used instead. */
+/**
+ * These return codes are limited to the asset loader module. If unified return
+ * codes are defined for the vkcv framework, these will be used instead.
+ */
 #define ASSET_ERROR 0
 #define ASSET_SUCCESS 1
 
-/** This enum matches modes in fx-gltf, the library returns a standard mode
- * (TRIANGLES) if no mode is given in the file. */
+/**
+ * This enum matches modes in fx-gltf, the library returns a standard mode
+ * (TRIANGLES) if no mode is given in the file.
+ */
 enum class PrimitiveMode : uint8_t {
 	POINTS=0, LINES, LINELOOP, LINESTRIP, TRIANGLES, TRIANGLESTRIP,
 	TRIANGLEFAN
 };
 
-/** The indices in the index buffer can be of different bit width. */
+/**
+ * The indices in the index buffer can be of different bit width.
+ */
 enum class IndexType : uint8_t { UNDEFINED=0, UINT8=1, UINT16=2, UINT32=3 };
 
 /**
@@ -77,7 +74,9 @@ typedef struct {
 	int addressModeU, addressModeV, addressModeW;
 } Sampler;
 
-/** struct for defining the loaded texture */
+/**
+ * This struct describes a loaded texture.
+ */
 typedef struct {
 	int sampler;		// index into the sampler array of the Scene
 	uint8_t channels;	// number of channels
@@ -85,8 +84,10 @@ typedef struct {
 	std::vector<uint8_t> data;	// binary data of the decoded texture
 } Texture;
 
-/** The asset loader module only supports the PBR-MetallicRoughness model for
- * materials.*/
+/**
+ * The asset loader module only supports the PBR-MetallicRoughness model for
+ * materials.
+ */
 typedef struct {
 	uint16_t textureMask;	// bit mask with active texture targets
 	// Indices into the Scene.textures vector
@@ -99,14 +100,17 @@ typedef struct {
 	struct { float r, g, b; } emissiveFactor;
 } Material;
 
-/** Flags for the bit-mask in the Material struct. To check if a material has a
+/**
+ * Flags for the bit-mask in the Material struct. To check if a material has a
  * certain texture target, you can use the hasTexture() function below, passing
- * the material struct and the enum. */
+ * the material struct and the enum.
+ */
 enum class PBRTextureTarget {
 	baseColor=1, metalRough=2, normal=4, occlusion=8, emissive=16
 };
 
-/** This macro translates the index of an enum in the defined order to an
+/**
+ * This macro translates the index of an enum in the defined order to an
  * integer with a single bit set in the corresponding place. It is used for
  * working with the bitmask of texture targets ("textureMask") in the Material
  * struct:
@@ -135,17 +139,21 @@ enum class PrimitiveType : uint32_t {
     COLOR_0, JOINTS_0, WEIGHTS_0
 };
 
-/** These integer values are used the same way in OpenGL, Vulkan and glTF. This
+/**
+ * These integer values are used the same way in OpenGL, Vulkan and glTF. This
  * enum is not needed for translation, it's only for the programmers
  * convenience (easier to read in if/switch statements etc). While this enum
  * exists in (almost) the same definition in the fx-gltf library, we want to
- * avoid exposing that dependency, thus it is re-defined here. */
+ * avoid exposing that dependency, thus it is re-defined here.
+ */
 enum class ComponentType : uint16_t {
     NONE = 0, INT8 = 5120, UINT8 = 5121, INT16 = 5122, UINT16 = 5123,
     UINT32 = 5125, FLOAT32 = 5126
 };
 
-/** This struct describes one vertex attribute of a vertex buffer. */
+/**
+ * This struct describes one vertex attribute of a vertex buffer.
+ */
 typedef struct {
     PrimitiveType type;			// POSITION, NORMAL, ...
     uint32_t offset;			// offset in bytes
@@ -155,11 +163,13 @@ typedef struct {
     uint8_t  componentCount;		// eg. 3 for vec3
 } VertexAttribute;
 
-/** This struct represents one (possibly the only) part of a mesh. There is
+/**
+ * This struct represents one (possibly the only) part of a mesh. There is
  * always one vertexBuffer and zero or one indexBuffer (indexed rendering is
  * common but not always used). If there is no index buffer, this is indicated
  * by indexBuffer.data being empty. Each vertex buffer can have one or more
- * vertex attributes. */
+ * vertex attributes.
+ */
 typedef struct {
 	enum PrimitiveMode mode;	// draw as points, lines or triangle?
 	size_t numIndices, numVertices;
@@ -176,9 +186,11 @@ typedef struct {
 	int materialIndex;		// index to one of the materials
 } VertexGroup;
 
-/** This struct represents a single mesh as it was loaded from a glTF file. It
+/**
+ * This struct represents a single mesh as it was loaded from a glTF file. It
  * consists of at least one VertexGroup, which then references other resources
- * such as Materials. */
+ * such as Materials.
+ */
 typedef struct {
 	std::string name;
 	std::array<float, 16> modelMatrix;
@@ -204,7 +216,7 @@ typedef struct {
  * @param path must be the path to a glTF or glb file.
  * @param scene is a reference to a Scene struct that will be filled with the
  * 	content of the glTF file being loaded.
- * */
+ */
 int loadScene(const std::filesystem::path &path, Scene &scene);