From 40f51b9e3b3117682728c24918697686db85c9df Mon Sep 17 00:00:00 2001
From: Claudio Hoffmann <hoffmanncl72341@th-nuernberg.de>
Date: Tue, 19 Jan 2021 18:44:01 +0100
Subject: [PATCH] Final comments!

---
 Entity.hpp                |  4 +++-
 PixelBuffer.cpp           |  3 +++
 PixelBuffer.hpp           | 31 ++++++++++++++++++++++++-------
 Platform_Win32Console.cpp |  1 +
 Projectile.hpp            |  3 +++
 5 files changed, 34 insertions(+), 8 deletions(-)

diff --git a/Entity.hpp b/Entity.hpp
index 8fb4f49..83a1768 100644
--- a/Entity.hpp
+++ b/Entity.hpp
@@ -18,7 +18,9 @@ protected:
 	float hittime = 0.0f;
 	Color hitcolor;
 
-	// Entity-specific step method.
+	// Entity-specific step method. This one was already implemented in all
+	// derived classes, which is why [PlayerX] and [PlayerY] are passed like
+	// that.
 	virtual void doStep(
 		float PlayerX, float PlayerY, FloatSeconds const & Frametime, Level &level
 	);
diff --git a/PixelBuffer.cpp b/PixelBuffer.cpp
index 050f0ba..d1696e6 100644
--- a/PixelBuffer.cpp
+++ b/PixelBuffer.cpp
@@ -40,6 +40,9 @@ Color DynamicPixelBuffer::peekUnchecked(PixelPoint const &pos) const
 Color& DynamicPixelBuffer::at(PixelPoint const& pos)
 {
 	if(pos.x < 0 || pos.x >= w() || pos.y < 0 || pos.y >= h()) {
+		// Might have been inspired by Daniel J. Bernstein's "boringcc"
+		// proposal:
+		// https://groups.google.com/g/boring-crypto/c/48qa1kWignU/m/dY0R7SjnDAAJ
 		trap = _t;
 		return trap;
 	}
diff --git a/PixelBuffer.hpp b/PixelBuffer.hpp
index 44c6333..55d73d3 100644
--- a/PixelBuffer.hpp
+++ b/PixelBuffer.hpp
@@ -54,11 +54,15 @@ static constexpr Color _t = { ColorValue::_t };
 // turn needed by PixelIterator...
 class PixelIterator;
 
+// Actually more of a pixel shader interface rather than a buffer... Might
+// have been inspired by Go's Image interface:
+// https://golang.org/pkg/image/#Image
 class PixelBuffer {
 	friend class PixelIterator;
 
 private:
-	// Why does C++ not have destructive moves?! :(
+	// Why does C++ not have destructive moves?! :( These could be `const` and
+	// `public` otherwise.
 	int width;
 	int height;
 
@@ -75,7 +79,7 @@ public:
 	int const w() const { return width; }
 	int const h() const { return height; }
 
-	// Bounds-checked, read-only accessor.
+	// Bounds-checked accessor.
 	Color peek(PixelPoint const &pos) const;
 
 	constexpr PixelBuffer(int w, int h)
@@ -86,6 +90,9 @@ public:
 	PixelIterator end() const;
 };
 
+// May not have been worth the over-engineering effort, given that it "just"
+// flattens two nested `for` loop into a single one… but look, we can also get
+// rid of the bounds checks this way! Then again, it's read-only… oh well.
 class PixelIterator {
 protected:
 	PixelBuffer const *const buffer;
@@ -116,12 +123,17 @@ public:
 	}
 };
 
+// A PixelBuffer with a std::array<W, H> as its buffer. Can be used if the
+// size is known at compile time. Has a constexpr constructor, making it
+// especially useful for sprite definitions.
 template <size_t W, size_t H> class StaticPixelBuffer : public PixelBuffer {
 public:
+	// Since we take string literals with an implicit \0 at the end, the input
+	// type has to have 1 more column.
 	using BufferType      = std::array<std::array<Color, (W    )>, H>;
 	using BufferInputType = std::array<std::array<char,  (W + 1)>, H>;
 
-	const BufferType buffer;
+	BufferType const buffer;
 
 	constexpr StaticPixelBuffer(BufferInputType const &chars)
 		: PixelBuffer(W, H), buffer(filter_null_terminators(chars)) {
@@ -166,11 +178,15 @@ protected:
 	}
 };
 
+// A PixelBuffer with a std::vector<Color> as its buffer. Also has unique
+// blitting methods for copying the contents of other PixelBuffers to certain
+// positions within this buffer.
 class DynamicPixelBuffer : public PixelBuffer {
 public:
 	DynamicPixelBuffer(int w, int h);
 
 	Color peekUnchecked(PixelPoint const &pos) const;
+	// Returns [trap] if [pos] is outside the buffer boundaries.
 	Color& at(PixelPoint const &pos);
 	void clear(Color ch = {});
 
@@ -181,9 +197,11 @@ protected:
 	std::vector<Color> buffer;
 };
 
-// Pixel shaders
-// -------------
-
+// Base class for any pixel shader that takes an existing PixelBuffer as its
+// input.
+// …yeah, it does nothing other than enforce that structure. Why did we end up
+// with this class? Eh, maybe it's nice for semantic reasons. Maybe.
+// (Prof. Teßmann would disagree)
 class ShadedPixelBuffer : public PixelBuffer {
 protected:
 	PixelBuffer const& input;
@@ -193,6 +211,5 @@ public:
 		: PixelBuffer(input.w(), input.h()), input(input) {
 	}
 };
-// -------------
 
 #endif // PIXELBUFFER_HPP
diff --git a/Platform_Win32Console.cpp b/Platform_Win32Console.cpp
index 70f6599..881cdba 100644
--- a/Platform_Win32Console.cpp
+++ b/Platform_Win32Console.cpp
@@ -22,6 +22,7 @@ void fatal(std::wstring_view message)
 	ExitProcess(1);
 }
 
+// You know, I'm too old to not handle errors the right way.
 void fatal_from_lasterror(
 	std::wstring_view file, unsigned int line, DWORD lasterror
 )
diff --git a/Projectile.hpp b/Projectile.hpp
index 1408ca3..e61c1f0 100644
--- a/Projectile.hpp
+++ b/Projectile.hpp
@@ -6,6 +6,9 @@
 //Hauerch71498 ----------------------------------------------------------------------------------------------
 class Level;
 
+// Did not manage to derive this from Entity during crunch time, since we
+// didn't need its functionality. That's why it still has its own [x] and [y]
+// members.
 class Projectile
 {
 public:
-- 
GitLab