Dokumentation ...

examples/simple/main.cpp

@@ -56,16 +56,21 @@ void main() {
 
 auto main() -> int {
 
+    // Ausgabefenster ... sieht aus als wäre es auf dem Stack
     auto window = paradiso::Window();
 
-    window.set_size(paradiso::Size{.width = 1280, .height = 720})
-        .set_position(paradiso::Point{.x = 100, .y = 100})
-        .set_title("PardiSO")
-        .set_visible(true);
+    // wir bauen ein Fenster ...
+    window
+        .set_size(paradiso::Size{.width = 1280, .height = 720}) // ... Grösse
+        .set_position(paradiso::Point{.x = 100, .y = 100})      // ... Position
+        .set_title("PardiSO")                                   // ... Titel
+        .set_visible(true); // ... und jetzt anzeigen!
 
+    // der Fenster Kontext
     auto ctx = paradiso::Context{};
 
-    auto sprite = paradiso::Sprite {
+    // als Beispiel eine Sprite mit farbiger Textur
+    auto sprite = paradiso::Sprite{
         .bitmap = paradiso::Bitmap::from_data(
             paradiso::Size{2, 2},
             paradiso::RGBA::from_rgba(0x00, 0xFF, 0x00, 0x80), // G
@@ -74,35 +79,58 @@ auto main() -> int {
             paradiso::RGBA::from_rgba(0xFF, 0x00, 0xFF, 0x80)) // C
     };
 
+    // das eigentliche 2D rendering sub-system
     auto renderer = paradiso::Renderer{};
 
+    // ein Shader (Schattierungsprogramm)
     auto shader = paradiso::Shader{};
 
+    // hier werden die Shader Programme geladen, kompiliert usw.
     setup_shaders(shader);
 
+    // kein schönes Design: dies sind globale Variablen ...
     uint8_t slider_value = 0xFF;
     bool want_close{false};
-    int frame_counter = 10;
 
+    // eine sehr rudimentäre Eingabebehandlung. Bei vorhandenen
+    // Eingaben landen diese hier. Wer sich am Design beteiligen
+    // möchte, kann hier einen eleganteren Vorschlag machen
     window.set_keyboardcallback(
         [&](auto& w, int key, int scancode, int action, int mods) {
             if (key == 'Q' || key == 256)
                 want_close = true;
-            else if (key == 'A' ) {
+            else if (key == 'A') {
                 slider_value += 10;
             }
         });
 
+    // das update führt den hier mitgegebnen Ausdruck innerhalb der internen
+    // Updates des Fensters auf. Es wird hier auch explizit ein bool gefordert
+    // damit das update auch zu jederzeit unterbrochen werden kann
     while (window.update([&](auto& w) -> bool {
+        // Context behandelt den sogenannten viewport - Hintergrund löschen,
+        // grösse usw. werden hier behandelt
 
-        ctx.set_clearcolor(paradiso::RGBA::from_rgb(slider_value, slider_value, slider_value));
+        ctx.set_clearcolor(
+            paradiso::RGBA::from_rgb(slider_value, slider_value, slider_value));
+
+        // ein viewport stellt die Sicht der Kamera dar, d.h. bei quadratischen
+        // Pixeln sollte hier auch eine dementsprechende Grösse eingestellt
+        // werden
         ctx.set_viewport(paradiso::Rectangle{
-            .size = w.client_size()
+            .size =
+                w.client_size().minimal_extent() // wir wollen das
+                                                 // Seitenverhältnis beibehalten
         });
+
+        // hier wird das eigentliche löschen des vorherigen Inhalts ausgelöst
         ctx.clear();
 
+        // Ein `renderer` kann nur mit einer Sprite verwendet werden!
+        // Aber ein Shader kann man für mehrere Sprite-Renderer Kombis verwenden
         renderer.draw(sprite, shader);
 
+        // ... signalisiere ob wir weitermachen wollen ...
         return !want_close;
     })) {
     };

src/lib/include/paradiso/bitmap.hpp

@@ -23,44 +23,70 @@
 #ifndef PARADISO_BITMAP_HPP
 #define PARADISO_BITMAP_HPP
 
-#include <paradiso/globals.hpp>
 #include <paradiso/geometry.hpp>
+#include <paradiso/globals.hpp>
 #include <paradiso/rgba.hpp>
 
-
-
 namespace paradiso {
+/**
+ * @brief aggregate to handle bitmap data
+ */
 struct Bitmap final {
 
+    /**
+     * @brief creates an empty bitmap
+     * @param[in] size extent of bitmap
+     * @return an empty bitmap
+     */
     constexpr static Bitmap empty(Size size) noexcept {
         return {.size = size, .data = std::vector<RGBA>{size.area()}};
     }
 
+    /**
+     * @brief creates a bitmap from manually adding data
+     * @param[in] size extent of bitmap
+     * @param[in] values values to set the bitmap from
+     * @return bitmap with data from this call
+     */
     template <typename... Arguments>
     static constexpr Bitmap from_data(Size size, Arguments... values) noexcept {
         assert(sizeof...(Arguments) == size.height * size.width);
-        return {
-            .size = size,
-            .data = {values...}
-            };
+        return {.size = size, .data = {values...}};
     }
 
+    /**
+     * @brief fills a bitmap uniformly
+     * @param[in] color RGBA value of a color
+     * @return reference to itself
+     */
     constexpr auto fill(const RGBA& color) noexcept {
         std::fill(data.begin(), data.end(), color);
         return *this;
     }
 
+    /**
+     * @brief access a pixel by position
+     * @param[in] x x-component of position
+     * @param[in] y y-component of position
+     * @return reference to pixel data at position
+     */
     constexpr RGBA& pixel(std::integral auto x, std::integral auto y) {
         return data[y * size.width + x];
     }
 
+    /**
+     * @brief access a pixel by position
+     * @param[in] x x-component of position
+     * @param[in] y y-component of position
+     * @return const reference to pixel data at position
+     */
     constexpr const RGBA& pixel(std::integral auto x,
                                 std::integral auto y) const {
         return data[y * size.width + x];
     }
 
-    Size size{.width = 0, .height = 0};
-    std::vector<RGBA> data{};
+    Size size{.width = 0, .height = 0}; //!< extent of bitmap
+    std::vector<RGBA> data{};           //!< data storage
 };
 } // namespace paradiso
 

src/lib/include/paradiso/geometry.hpp

@@ -25,37 +25,34 @@
 
 #include <paradiso/globals.hpp>
 
-namespace paradiso
-{
+namespace paradiso {
 
-    struct Point final
-    {
+struct Point final {
     using value_type = int32_t;
     value_type x{0}, y{0};
-    };
+};
 
-    struct Size final
-    {
+struct Size final {
     using value_type = uint32_t;
     value_type width{0}, height{0};
 
-        constexpr auto area() const noexcept
-        {
-            return width * height;
-        }
-    };
+    constexpr auto area() const noexcept { return width * height; }
 
-    struct Rectangle
-    {
+    constexpr Size minimal_extent() const noexcept {
+        return {.width = std::min(width, height),
+                .height = std::min(width, height)};
+    }
+};
+
+struct Rectangle {
     Point position;
     Size size;
 
-        constexpr bool contains(const Point &p) const noexcept
-        {
+    constexpr bool contains(const Point& p) const noexcept {
         return p.x >= position.x && p.x <= position.x + size.width &&
                p.y >= position.y && p.y <= position.y + size.height;
     }
-    };
-}
+};
+} // namespace paradiso
 
 #endif

src/lib/include/paradiso/sprite.hpp

@@ -23,21 +23,22 @@
 #ifndef PARADISO_SPRITE_HPP
 #define PARADISO_SPRITE_HPP
 
-#include <paradiso/bitmap.hpp>
 #include <paradiso/globals.hpp>
+#include <paradiso/bitmap.hpp>
 #include <paradiso/matrix.hpp>
 #include <paradiso/vector.hpp>
 
 namespace paradiso {
 
+/**
+ * @brief simple sprite handler
+*/
 struct Sprite final {
     using ChangeCountType = std::uint64_t;
 
-    static constexpr Sprite create() noexcept { return {}; }
+    Bitmap bitmap{}; //!< associated bitmap 
 
-    Bitmap bitmap{};
-
-    Vector2<float> pivot{Vector2<float>::zero()};
+    Vector2<float> pivot{Vector2<float>::zero()}; //!< center point
 
     // 0      3    |      y
     // +------+    |      ^
@@ -46,23 +47,23 @@ struct Sprite final {
     // +------+    |   z
     // 1      2    |
 
-    std::array<std::uint32_t, 6> indices{0, 1, 2, 0, 2, 3};
+    std::array<std::uint32_t, 6> indices{0, 1, 2, 0, 2, 3}; //!< topology
 
-    std::array<Vector3<float>, 4> vertices{
+    std::array<Vector3<float>, 4> vertices{ //!< geometry
         Vector3<float>::make(-1.0f, +1.0f, 0.0f),
         Vector3<float>::make(-1.0f, -1.0f, 0.0f),
         Vector3<float>::make(+1.0f, -1.0f, 0.0f),
         Vector3<float>::make(+1.0f, +1.0f, 0.0f)};
 
-    std::array<Vector3<float>, 4> normals{
+    std::array<Vector3<float>, 4> normals{ //!< normals
         Vector3<float>::z_axis(), Vector3<float>::z_axis(),
         Vector3<float>::z_axis(), Vector3<float>::z_axis()};
 
-    std::array<Vector2<float>, 4> texture_coordinates{
+    std::array<Vector2<float>, 4> texture_coordinates{ //!< UV coordinates
         Vector2<float>::make(0.0f, 0.0f), Vector2<float>::make(1.0f, 0.0f),
         Vector2<float>::make(1.0f, 1.0f), Vector2<float>::make(0.0f, 1.0f)};
 
-    ChangeCountType change_count{};
+    ChangeCountType change_count{}; //!< cookie to track changes
 };
 } // namespace paradiso