Skip to content

Commit cdf373c

Browse files
fburgerdevfburgerdev
committed
feat(docs): add docstrings
as well as move and rename definitions
1 parent dc81d7e commit cdf373c

13 files changed

Lines changed: 192 additions & 176 deletions

File tree

‎examples/pirate_bay/scripts/fps.hh‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,8 +46,8 @@ namespace Parrot {
4646
}
4747
}
4848
else if (auto* mp = we->getMousePress()) {
49-
if (mp->state == MouseState::PRESSED) {
50-
if (mp->button == MouseButton::LEFT) {
49+
if (mp->state == MousePress::State::PRESSED) {
50+
if (mp->button == MousePress::Button::LEFT) {
5151
if (!_captured) {
5252
_captured = true;
5353
stage->window.setCursorState(CursorState::CAPTURED);

‎src/app/app_config.hh‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ namespace Parrot {
1515
string name = "App";
1616
stdf::path asset_dir = ".";
1717
LoadingPolicy loading_policy = LoadingPolicy::LAZY_LOAD;
18-
UnloadingPolicy unloading_policy = UnloadingPolicy::UNLOAD_APP;
18+
UnloadingPolicy unloading_policy = UnloadingPolicy::UNLOAD_NEVER;
1919
AssetHandle<StageConfig> main_stage;
2020
};
2121
}

‎src/app/component_registry.hh‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,10 @@
55
#include "graphics/render_object.hh"
66

77
namespace Parrot {
8+
/// @trivial
89
using CameraComponent = BasicComponent<Camera>;
10+
/// @trivial
911
using LightComponent = BasicComponent<Light>;
12+
/// @trivial
1013
using RenderObjectComponent = BasicComponent<RenderObject>;
1114
}

‎src/asset/asset_policy.hh‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,11 @@
33
namespace Parrot {
44
/// @brief Determines, when Assets are loaded into memory.
55
enum class LoadingPolicy {
6-
// PRELOAD_APP,
7-
// PRELOAD_SCENE,
86
LAZY_LOAD, ///< Load an Asset into memory only if it's used
97
};
108
/// @brief Determines, when Assets are released from memory.
119
enum class UnloadingPolicy {
12-
UNLOAD_APP, ///< Release an Asset only when the App terminates,
13-
// UNLOAD_SCENE,
10+
UNLOAD_NEVER, ///< Release an Asset only when the AssetManager is destroyed
1411
UNLOAD_UNUSED, ///< Release an Asset instantly when it's unused
1512
};
1613
}

‎src/graphics/camera.cc‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -109,22 +109,22 @@ namespace Parrot {
109109
}
110110

111111
// << (stream)
112-
ostream& operator<<(ostream& stream, const PerspectiveCamera& camera) {
112+
ostream& operator<<(ostream& stream, const PerspectiveCamera& cam) {
113113
stream << "PerspectiveCamera(";
114-
stream << "fov=" << camera.fov << ",";
115-
stream << "zrange=" << camera.z_range << ")";
114+
stream << "fov=" << cam.fov << ",";
115+
stream << "zrange=" << cam.z_range << ")";
116116
return stream;
117117
}
118-
ostream& operator<<(ostream& stream, const OrthographicCamera& camera) {
118+
ostream& operator<<(ostream& stream, const OrthographicCamera& cam) {
119119
stream << "OrthographicCamera(";
120-
stream << "scale=" << camera.scale << ",";
121-
stream << "zrange=" << camera.z_range << ")";
120+
stream << "scale=" << cam.scale << ",";
121+
stream << "zrange=" << cam.z_range << ")";
122122
return stream;
123123
}
124-
ostream& operator<<(ostream& stream, const Camera& camera) {
125-
std::visit([&](const auto& specific_camera) {
126-
stream << specific_camera;
127-
}, camera.value);
124+
ostream& operator<<(ostream& stream, const Camera& cam) {
125+
std::visit([&](const auto& specific_cam) {
126+
stream << specific_cam;
127+
}, cam.value);
128128
return stream;
129129
}
130130
}

‎src/graphics/camera.hh‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,12 +10,18 @@ namespace Parrot {
1010
struct PerspectiveCamera {
1111
Mat4x4<float32> calcProjectionMatrix(float32 aspect) const;
1212

13+
/// @trivial
14+
friend ostream& operator<<(ostream& stream, const PerspectiveCamera& cam);
15+
1316
float32 fov = DEFAULT_FOV;
1417
Vec2<float32> z_range = DEFAULT_ZRANGE;
1518
};
1619
struct OrthographicCamera {
1720
Mat4x4<float32> calcProjectionMatrix(float32 aspect) const;
1821

22+
/// @trivial
23+
friend ostream& operator<<(ostream& stream, const OrthographicCamera& cam);
24+
1925
float32 scale = DEFAULT_SCALE;
2026
Vec2<float32> z_range = DEFAULT_ZRANGE;
2127
};
@@ -28,11 +34,10 @@ namespace Parrot {
2834
void loadFromSerialNode(const SerialNode& node, AssetAPI& api);
2935
Mat4x4<float32> calcProjectionMatrix(float32 aspect) const;
3036

31-
Variant<
32-
PerspectiveCamera, OrthographicCamera
33-
> value = PerspectiveCamera();
37+
/// @trivial
38+
friend ostream& operator<<(ostream& stream, const Camera& cam);
39+
40+
/// @trivial
41+
Variant<PerspectiveCamera, OrthographicCamera> value = PerspectiveCamera();
3442
};
35-
ostream& operator<<(ostream& stream, const OrthographicCamera& camera);
36-
ostream& operator<<(ostream& stream, const PerspectiveCamera& camera);
37-
ostream& operator<<(ostream& stream, const Camera& camera);
3843
}

‎src/graphics/image.hh‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,21 +15,30 @@ namespace Parrot {
1515
public:
1616
Image(const stdf::path& filepath, Opt<stdf::path> debug_root = {});
1717
Image(strview name, const uchar* buffer, usize size);
18+
/// @trivial
1819
Image(const Image& other);
20+
/// @trivial
1921
Image(Image&& other) noexcept;
2022
Image(const AssetPath& path, AssetAPI& api);
2123
Image(const SerialNode& node, const AssetPath& path, AssetAPI& api);
24+
/// @trivial
2225
~Image();
26+
/// @trivial
2327
Image& operator=(const Image& other);
28+
/// @trivial
2429
Image& operator=(Image&& other) noexcept;
2530

2631
void safeAsBMP(
2732
const stdf::path& filepath, Opt<stdf::path> debug_root = {}
2833
) const;
2934

35+
/// @trivial
3036
uint getWidth() const;
37+
/// @trivial
3138
uint getHeight() const;
39+
/// @trivial
3240
ImageFormat getFormat() const;
41+
/// @return Pointer to the beginning of the pixel buffer (row-major)
3342
const uchar* getBytes() const;
3443
private:
3544
static stdf::path getDebugFilepath(

‎src/graphics/light.hh‎

Lines changed: 40 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,44 +3,74 @@
33
#include "utils/math_matrix.hh"
44

55
namespace Parrot {
6+
/// @brief Global light source illuminating all objects uniformly.
67
struct AmbientLight {
8+
/// @trivial
9+
friend ostream& operator<<(ostream& stream, const AmbientLight& light);
10+
11+
/// @trivial
712
DefaultFloat intensity = 1;
13+
/// @trivial
814
Vec3<uint8> color = { 255, 255, 255 };
915
};
16+
/// @brief Light source illuminating objects based on their surface normals.
1017
struct DirectionalLight {
18+
/// @trivial
19+
friend ostream& operator<<(ostream& stream, const DirectionalLight& light);
20+
21+
/// @trivial
1122
Vec3<DefaultFloat> direction = { 0, 0, 1 };
23+
/// @trivial
1224
DefaultFloat intensity = 1;
25+
/// @trivial
1326
Vec3<uint8> color = { 255, 255, 255 };
1427
};
28+
/// @brief Light source illuminating objects close to it
29+
/// based on their distance to the light.
1530
struct PointLight {
31+
/// @trivial
32+
friend ostream& operator<<(ostream& stream, const PointLight& light);
33+
34+
/// @trivial
1635
Vec3<DefaultFloat> position = { 0, 0, 0 };
36+
/// @brief Maximum distance to the objects the light illuminates.
1737
DefaultFloat range = 1;
38+
/// @trivial
1839
DefaultFloat intensity = 1;
40+
/// @trivial
1941
Vec3<uint8> color = { 255, 255, 255 };
2042
};
43+
/// @brief Light source illuminating objects in a cone shape,
44+
/// like a flashlight.
2145
struct SpotLight {
46+
/// @trivial
47+
friend ostream& operator<<(ostream& stream, const SpotLight& light);
48+
49+
/// @trivial
2250
Vec3<DefaultFloat> position = { 0, 0, 0 };
51+
/// @trivial
2352
Vec3<DefaultFloat> direction = { 0, 0, 1 };
24-
DefaultFloat angle = PI<> / 2;
53+
/// @brief Angle of the cone in which the light illuminates objects.
54+
DefaultFloat angle = PI<> / 4;
55+
/// @trivial
2556
DefaultFloat intensity = 1;
57+
/// @trivial
2658
Vec3<uint8> color = { 255, 255, 255 };
2759
};
2860

61+
/// @brief One of the following light sources:
62+
// AmbientLight, DirectionalLight, PointLight, SpotLight.
2963
class Light : public Asset {
3064
public:
3165
Light(const AssetPath& path, AssetAPI& api);
3266
Light(const SerialNode& node, const AssetPath& path, AssetAPI& api);
3367

3468
void loadFromSerialNode(const SerialNode& node, AssetAPI& api);
3569

36-
Variant<
37-
AmbientLight, DirectionalLight, PointLight, SpotLight
38-
> value;
39-
};
70+
/// @trivial
71+
friend ostream& operator<<(ostream& stream, const Light& source);
4072

41-
ostream& operator<<(ostream& stream, const AmbientLight& light);
42-
ostream& operator<<(ostream& stream, const DirectionalLight& light);
43-
ostream& operator<<(ostream& stream, const PointLight& light);
44-
ostream& operator<<(ostream& stream, const SpotLight& light);
45-
ostream& operator<<(ostream& stream, const Light& source);
73+
/// @trivial
74+
Variant<AmbientLight, DirectionalLight, PointLight, SpotLight> value;
75+
};
4676
}

‎src/graphics/mesh.hh‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,24 +9,34 @@ namespace Parrot {
99
using AttributeGPU = Pair<DTypeGPU, uint>;
1010

1111
struct Vertex {
12+
/// @return List of attributes
13+
/// so that the GPU understands the memory layout of Vertex.
1214
static List<AttributeGPU> attributes();
1315

16+
/// @trivial
1417
Vec3<float32> position = { 0, 0, 0 };
18+
/// @warning This vector is expected to be normalized.
1519
Vec3<float32> normal = { 0, 0, -1 };
20+
/// @brief UV coordinates ranging from (0, 0) to (1, 1).
1621
Vec2<float32> tex_coords = { 0, 0 };
22+
/// @brief Tangent vector orthonormal to the @c normal.
23+
/// @warning This vector is expected to be normalized.
1724
Vec3<float32> tangent = { 1, 0, 0 };
1825
};
1926

2027
class Mesh : public UUIDObject {
2128
public:
29+
/// @trivial
2230
Mesh() = default;
2331
template<class Vertices, class Indices>
2432
Mesh(Vertices&& vertices, Indices&& indices);
2533

2634
void addTriangle(Vertex v1, Vertex v2, Vertex v3);
2735
void addQuadrangle(Vertex v1, Vertex v2, Vertex v3, Vertex v4);
2836

37+
/// @trivial
2938
List<Vertex> vertices;
39+
/// @brief List of triangle indices referring to the index in @c vertices.
3040
List<uint32> indices;
3141
};
3242
}

‎src/graphics/model.hh‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,19 @@ namespace Parrot {
66
struct ModelMaterial {
77
usize tex_index = 0xFFFFFF;
88
};
9+
/// @brief Pair of Mesh and index to associated ModelMaterial.
910
using SubModel = Pair<Mesh, usize>;
11+
/// @brief Graphics model consisting of (multiple) Meshes and Materials.
1012
class Model : public Asset {
1113
public:
14+
/// @trivial
1215
Model(strview name);
1316
Model(const AssetPath& path, AssetAPI& api);
1417
Model(const SerialNode& node, const AssetPath& path, AssetAPI& api);
1518

1619
List<SubModel> submodels;
20+
/// @warning The order of the elements is important since they are being
21+
/// referenced by their index in @c submodels
1722
List<ModelMaterial> model_materials;
1823
List<TextureConfig> textures;
1924
};

0 commit comments

Comments
 (0)