From 5d0c2caf783489a2f34e59806e9444d9bfcf0a5b Mon Sep 17 00:00:00 2001 From: Kevin Trogant Date: Mon, 17 Oct 2022 16:27:45 +0200 Subject: [PATCH] documentation --- .idea/vcs.xml | 6 +++ README.md | 3 ++ app/src/main/cpp/AssetManager.h | 30 ++++++++++++ app/src/main/cpp/Hash.h | 22 +++++++++ app/src/main/cpp/Log.h | 3 ++ app/src/main/cpp/NativeEngine.h | 7 +++ app/src/main/cpp/Position.h | 10 +++- app/src/main/cpp/Renderer.h | 66 +++++++++++++++++++++++++++ app/src/main/cpp/StringRepository.cpp | 3 ++ app/src/main/cpp/StringRepository.h | 17 ++++++- app/src/main/cpp/Texture.h | 6 +++ app/src/main/cpp/TouchInput.h | 13 ++++++ 12 files changed, 183 insertions(+), 3 deletions(-) create mode 100644 .idea/vcs.xml create mode 100644 README.md diff --git a/.idea/vcs.xml b/.idea/vcs.xml new file mode 100644 index 0000000..94a25f7 --- /dev/null +++ b/.idea/vcs.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..e1560f6 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# Krimi Dinner Engine + +Source code für die Krimi Dinner Engine. diff --git a/app/src/main/cpp/AssetManager.h b/app/src/main/cpp/AssetManager.h index 955aae8..29c77e4 100644 --- a/app/src/main/cpp/AssetManager.h +++ b/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: diff --git a/app/src/main/cpp/Hash.h b/app/src/main/cpp/Hash.h index 5e00a66..60b197b 100644 --- a/app/src/main/cpp/Hash.h +++ b/app/src/main/cpp/Hash.h @@ -3,9 +3,16 @@ #include +/// \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 diff --git a/app/src/main/cpp/Log.h b/app/src/main/cpp/Log.h index 563491d..d19f0f6 100644 --- a/app/src/main/cpp/Log.h +++ b/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 #define LOG_TAG "KrimiDinnerEngine" diff --git a/app/src/main/cpp/NativeEngine.h b/app/src/main/cpp/NativeEngine.h index deb9261..63cc0b2 100644 --- a/app/src/main/cpp/NativeEngine.h +++ b/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 #include +/// @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: diff --git a/app/src/main/cpp/Position.h b/app/src/main/cpp/Position.h index 076ccc7..b71110b 100644 --- a/app/src/main/cpp/Position.h +++ b/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 y; + float x; ///< X-Coordinate + float y; ///< Y-Coordinate }; #endif //KRIMI_DINNER_ENGINE_POSITION_H diff --git a/app/src/main/cpp/Renderer.h b/app/src/main/cpp/Renderer.h index c5be621..86684d0 100644 --- a/app/src/main/cpp/Renderer.h +++ b/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 #include #include @@ -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: diff --git a/app/src/main/cpp/StringRepository.cpp b/app/src/main/cpp/StringRepository.cpp index 727c6b0..dd04aef 100644 --- a/app/src/main/cpp/StringRepository.cpp +++ b/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; } diff --git a/app/src/main/cpp/StringRepository.h b/app/src/main/cpp/StringRepository.h index 5f3cd63..2365c0e 100644 --- a/app/src/main/cpp/StringRepository.h +++ b/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 #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: diff --git a/app/src/main/cpp/Texture.h b/app/src/main/cpp/Texture.h index 4a69f50..04ff217 100644 --- a/app/src/main/cpp/Texture.h +++ b/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 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: diff --git a/app/src/main/cpp/TouchInput.h b/app/src/main/cpp/TouchInput.h index 760c6d5..35f9397 100644 --- a/app/src/main/cpp/TouchInput.h +++ b/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; };