documentation

.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

README.md

@@ -0,0 +1,3 @@
+# Krimi Dinner Engine
+
+Source code für die Krimi Dinner Engine.

app/src/main/cpp/AssetManager.h

@@ -1,29 +1,59 @@
 #ifndef KRIMI_DINNER_ENGINE_ASSETMANAGER_H
 #define KRIMI_DINNER_ENGINE_ASSETMANAGER_H
 
+/// @file AssetManager.h
+/// @brief Access to asset files
+
 #include "Texture.h"
 #include "Renderer.h"
 
+// Predefine, because that saves us from including android headers here
 struct AAssetManager;
 
+/// @brief Buffer for a loaded asset file
 struct FileBuffer
 {
+    /// Read-only data
     const void* data;
+
+    /// Number of bytes in @ref data
     size_t size;
 
+    /// Internal, don't modify
     void* internal;
 };
 
+/// @brief Provides access to asset files
 class AssetManager {
 public:
+    /// The singleton pointer
     static AssetManager* ptr;
 
+    /// @brief Creates the singleton instance
+    ///
+    /// Sets @ref ptr to the singleton instance
+    /// \param android_asset_manager Pointer to the android asset manager object
     static void create(AAssetManager* android_asset_manager);
 
+    /// @brief Loads an asset file
+    ///
+    /// You must free the asset buffer via @ref releaseFileBuffer after you are done with it.
+    /// \param path Path to the asset file
+    /// \param p_file_buffer Receives the file buffer, if the asset was loaded successfully
+    /// \return @c true if the asset was loaded successfully, @c false otherwise
     bool loadFile(const char* path, FileBuffer* p_file_buffer);
 
+    /// @brief Helper for loading a texture
+    ///
+    /// You should not need this, because the renderer is responsible for loading textures.
+    /// \param path Path to the texture file
+    /// \param p_texture Receives the texture object
+    /// \return @c true if the texture was loaded successfully, @c false otherwise
     bool loadTexture(const char* path, Texture* p_texture);
 
+    /// @brief Frees the resources allocated for an asset file
+    ///
+    /// \param fb The file buffer returned by the load function
     void releaseFileBuffer(FileBuffer& fb);
 
 private:

app/src/main/cpp/Hash.h

@@ -3,9 +3,16 @@
 
 #include <stdint.h>
 
+/// \file Hash.h
+/// \brief Hash table implementation
+
+/// Special key value used for empty slots
 static constexpr uint64_t HASH_EMPTY_KEY = 0;
+
+/// Special key value used for deleted slots
 static constexpr uint64_t HASH_TOMBSTONE_KEY = 1;
 
+/// \brief A hash table
 class Hash
 {
 public:
@@ -15,10 +22,24 @@ public:
     Hash& operator=(const Hash& rhs);
     ~Hash();
 
+    /// @brief Retrieves a value
+    ///
+    /// \param key The key
+    /// \param default_value Default value
+    /// \return The value for @c key, or @c default_value, if the key was not found
     uint64_t lookup(uint64_t key, uint64_t default_value);
 
+    /// @brief Inserts a value
+    ///
+    /// Replaces the old value, if a key-value pair with @c key was already inserted.
+    /// \param key The key
+    /// \param value The value
+    /// \return @c true if the insert was successful, @c false otherwise
     bool insert(uint64_t key, uint64_t value);
 
+    /// @brief Removes a key-value pair from the hash table
+    ///
+    /// \param key The key
     void remove(uint64_t key);
 
 private:
@@ -28,6 +49,7 @@ private:
     uint64_t* m_values;
 };
 
+/// Alias for compatibility
 using nt_hash = Hash;
 
 #endif

app/src/main/cpp/Log.h

@@ -1,6 +1,9 @@
 #ifndef KRIMI_DINNER_ENGINE_LOG_H
 #define KRIMI_DINNER_ENGINE_LOG_H
 
+/// @file Log.h
+/// @brief Logging macros
+
 #include <android/log.h>
 
 #define LOG_TAG "KrimiDinnerEngine"

app/src/main/cpp/NativeEngine.h

@@ -1,24 +1,31 @@
 #ifndef KRIMI_DINNER_ENGINE_NATIVEENGINE_H
 #define KRIMI_DINNER_ENGINE_NATIVEENGINE_H
 
+/// @file NativeEngine.h
+/// @brief Android game activity code
+
 #include "Position.h"
 #include "StringRepository.h"
 
 #include <game-activity/native_app_glue/android_native_app_glue.h>
 #include <EGL/egl.h>
 
+/// @brief State that is saved between app resumes
 struct NativeEngineState
 {
     bool has_focus;
 };
 
+/// @brief Interface to the android game activity
 class NativeEngine {
 public:
     NativeEngine(struct android_app* app);
     ~NativeEngine();
 
+    /// Main loop
     void gameLoop();
 
+    /// Handles app commands
     void handleAppCmd(int32_t event);
 
 private:

app/src/main/cpp/Position.h

@@ -1,10 +1,16 @@
 #ifndef KRIMI_DINNER_ENGINE_POSITION_H
 #define KRIMI_DINNER_ENGINE_POSITION_H
 
+/// @file Position.h
+/// @brief 2d position
+
+/// @brief A 2d position
+///
+/// The position (0,0) is the top-left corner of the screen.
 struct Position
 {
-    float x;
+    float x; ///< X-Coordinate
-    float y;
+    float y; ///< Y-Coordinate
 };
 
 #endif //KRIMI_DINNER_ENGINE_POSITION_H

app/src/main/cpp/Renderer.h

@@ -1,6 +1,9 @@
 #ifndef KRIMI_DINNER_ENGINE_RENDERER_H
 #define KRIMI_DINNER_ENGINE_RENDERER_H
 
+/// @file Renderer.h
+/// @brief GLES3 renderer
+
 #include <GLES3/gl3.h>
 #include <unordered_map>
 #include <vector>
@@ -8,27 +11,90 @@
 #include "Texture.h"
 #include "StringRepository.h"
 
+/// @brief Renderer singleton
 class Renderer
 {
 public:
+    /// The singleton instance
     static Renderer* ptr;
 
+    /// @brief Creates the singleton and sets @ref Renderer::ptr
     static void create();
 
+    /// @brief Destroys the singleton, only call this if you know what you are doing.
     static void destroy();
 
+    /// \brief Adds a white rectangle to the screen
+    /// \param x X-coordinate of the top-left corner
+    /// \param y Y-coordinate of the top-left corner
+    /// \param w width in pixels
+    /// \param h height in pixels
     void addRect(float x, float y, float w, float h);
 
+    /// @brief Adds a textured rectangle to the screen
+    /// \param x X-coordinate of the top-left corner
+    /// \param y Y-coordinate of the top-left corner
+    /// \param w width in pixels
+    /// \param h height in pixels
+    /// \param texture String handle in the global string repository of the texture file name
     void addRect(float x, float y, float w, float h, StringHandle texture);
 
+    /// @brief Adds a colored rectangle to the screen
+    /// \param x X-coordinate of the top-left corner
+    /// \param y Y-coordinate of the top-left corner
+    /// \param w width in pixels
+    /// \param h height in pixels
+    /// \param r red [0,1]
+    /// \param g green [0,1]
+    /// \param b blue [0,1]
+    /// \param a alpha [0,1]
     void addRect(float x, float y, float w, float h, float r, float g, float b, float a);
 
+    /// @brief Adds a tinted textured rectangle to the screen
+    /// \param x X-coordinate of the top-left corner
+    /// \param y Y-coordinate of the top-left corner
+    /// \param w width in pixels
+    /// \param h height in pixels
+    /// \param r red [0,1]
+    /// \param g green [0,1]
+    /// \param b blue [0,1]
+    /// \param a alpha [0,1]
+    /// \param texture String handle in the global string repository of the texture file name
     void addRect(float x, float y, float w, float h, float r, float g, float b, float a, StringHandle texture);
 
+    /// @brief Adds a textured rectangle to the screen
+    /// \param x X-coordinate of the top-left corner
+    /// \param y Y-coordinate of the top-left corner
+    /// \param w width in pixels
+    /// \param h height in pixels
+    /// \param texture String handle in the global string repository of the texture file name
+    /// \param src_x top left corner of the source rectangle inside the texture [0, 1]
+    /// \param src_y top left corner of the source rectangle inside the texture [0, 1]
+    /// \param src_w width of the source rectangle inside the texture [0, 1]
+    /// \param src_h height of the source rectangle inside the texture [0, 1]
     void addRect(float x, float y, float w, float h, StringHandle texture, float src_x, float src_y, float src_w, float src_h);
 
+    /// @brief Adds a tinted textured rectangle to the screen
+    /// \param x X-coordinate of the top-left corner
+    /// \param y Y-coordinate of the top-left corner
+    /// \param w width in pixels
+    /// \param h height in pixels
+    /// \param r red [0,1]
+    /// \param g green [0,1]
+    /// \param b blue [0,1]
+    /// \param a alpha [0,1]
+    /// \param texture String handle in the global string repository of the texture file name
+    /// \param src_x top left corner of the source rectangle inside the texture [0, 1]
+    /// \param src_y top left corner of the source rectangle inside the texture [0, 1]
+    /// \param src_w width of the source rectangle inside the texture [0, 1]
+    /// \param src_h height of the source rectangle inside the texture [0, 1]
     void addRect(float x, float y, float w, float h, float r, float g, float b, float a, StringHandle texture, float src_x, float src_y, float src_w, float src_h);
 
+    /// @brief Renders the frame
+    ///
+    /// You don't need to call this.
+    /// @param width width of the screen
+    /// @param height height of the screen
     void renderFrame(float width, float height);
 
 private:

app/src/main/cpp/StringRepository.cpp

@@ -81,4 +81,7 @@ void StringRepository::freeAll()
 {
     m_one_past_last_char = 0;
     m_hash = Hash();
+    m_buffer_size = 0;
+    free(m_buffer);
+    m_buffer = nullptr;
 }

app/src/main/cpp/StringRepository.h

@@ -1,32 +1,47 @@
 #ifndef KRIMI_DINNER_ENGINE_STRINGREPOSITORY_H
 #define KRIMI_DINNER_ENGINE_STRINGREPOSITORY_H
 
+/// @file StringRepository.h
+/// @brief String storage
+
 #include <stdint.h>
 #include "Hash.h"
 
+/// A string handle
 using StringHandle = uint32_t;
 
 // Alias for compatibility
 using nt_string_handle = StringHandle;
 
+/// @brief Stores strings
 class StringRepository
 {
 public:
-    // The default string repository
+    /// The default string repository
     static StringRepository* global;
 
     StringRepository() = default;
     StringRepository(const StringRepository& copy);
     ~StringRepository();
 
+    /// @brief Adds a string to the string repository
+    /// @param string the string
+    /// @param length length in bytes
     StringHandle internStringLength(const char* string, unsigned int length);
 
+    /// @brief Adds a string to the string repository
+    /// @param string the string
     StringHandle internString(const char* string);
 
+    /// @brief Retrieves a string value
+    /// @param handle The string handle
+    /// @return The string
     const char* getString(StringHandle handle);
 
+    /// @brief Frees a string
     void releaseString(StringHandle handle);
 
+    /// @brief Frees all strings inside the repository
     void freeAll();
 
 private:

app/src/main/cpp/Texture.h

@@ -1,10 +1,14 @@
 #ifndef KRIMI_DINNER_ENGINE_TEXTURE_H
 #define KRIMI_DINNER_ENGINE_TEXTURE_H
 
+/// @file Texture.h
+/// @brief Texture object
+
 #include <GLES3/gl3.h>
 
 class Renderer;
 
+/// @brief A opengl texture
 class Texture
 {
 public:
@@ -14,8 +18,10 @@ public:
     Texture(Texture&&) = default;
     Texture& operator=(const Texture&) = default;
 
+    /// @brief Destroys the texture
     void destroy();
 
+    /// @brief Binds the texture to @c GL_TEXTURE_2D
     void bind() const;
 
 private:

app/src/main/cpp/TouchInput.h

@@ -1,18 +1,31 @@
 #ifndef KRIMI_DINNER_ENGINE_TOUCHINPUT_H
 #define KRIMI_DINNER_ENGINE_TOUCHINPUT_H
 
+/// @file TouchInput.h
+/// @brief Touch input events
+
 #include "Position.h"
 
+/// @brief Describes the kind of input event
 enum class TouchInputEventKind
 {
+    /// The user "tapped" a specific position on the screen
     Tap,
+
+    /// The user "swiped" from a start position to an end position
     Swipe
 };
 
+/// @brief Describes a touch input event
 struct TouchInputEvent
 {
+    /// The kind of event
     TouchInputEventKind kind;
+
+    /// The start position for swipe events, or the touched position for tap events
     Position start;
+
+    /// The end position for swipe events, or the touched position for tap events
     Position end;
 };