From f86d6b5cab47c539bd5065e6884c191672d7ebe5 Mon Sep 17 00:00:00 2001 From: Pascal Engeler <engelerp@phys.ethz.ch> Date: Fri, 3 Sep 2021 15:59:52 +0200 Subject: [PATCH] written more documentation --- README.md | 260 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 183 insertions(+), 77 deletions(-) diff --git a/README.md b/README.md index 50b3b3e..8d6893a 100644 --- a/README.md +++ b/README.md @@ -656,7 +656,7 @@ Draws and controls all functionality related to the GUI. - **Preconditions**: - Fully setup `Toolbox` + Fully setup `Toolbox`, correct paths to images and fonts - **Postconditions**: @@ -842,31 +842,43 @@ N/A ### Infrastructure ([infrastructure.hpp](include/infrastructure.hpp), [infrastructure.cpp](src/infrastructure.cpp)) **Description** -Todo +Creates and stores the SDL and OpenGL infrastructures (window, renderer, context). **Usage** -Todo +- Default construct object +- Call `init` +- at end of life, call `quit` **Constructors and Destructors** -Todo +- `Infrastructure(SDL_Window*, SDL_RENDERER*, SDL_GLContext)` +- `Infrastructure()` +- `Infrastructure(const Infrastructure&)` **Public Function Members** -Todo +- `SDL_Window* window() const` +- `SDL_Renderer* renderer() const` +- `SDL_Context context() const` +- `bool init(const std::string name, const int width, const int height)` +- `void destroy()` +- `void quit()` **Private Function Members** -Todo +N/A **Public Data Members** -Todo +N/A **Private Data Members** -Todo +- `SDL_Window* window_` +- `SDL_Renderer* renderer_` +- `SDL_Context context_` + **Notes** @@ -875,7 +887,7 @@ Todo ### InputHandler ([input_handler.hpp](include/input_handler.hpp), [input_handler.cpp](src/input_handler.cpp)) **Description** -Todo +Reads all input from SDL, preprocesses it and stores it in the `Toolbox` event chain **Usage** @@ -883,32 +895,32 @@ Todo **Constructors and Destructors** -Todo +- `InputHandler()` **Public Function Members** -Todo +- `void update(Toolbox& tb)` **Private Function Members** -Todo +N/A **Public Data Members** -Todo +N/A **Private Data Members** -Todo +N/A **Notes** -Todo +N/A ### Message ([message.hpp](include/message.hpp), [message.cpp](src/message.cpp)) **Description** -Todo +Represents a message to one of the components **Usage** @@ -916,32 +928,39 @@ Todo **Constructors and Destructors** -Todo +- `Message()` +- `Message(BLOCKCHAINMESSAGE message)` +- `Message(DRAWERMESSAGE message)` +- `Message(GUIMESSAGE message)` +- `Message(WAVEMESSAGE message)` +- `Message(PATTERNMESSAGE message)` **Public Function Members** -Todo +N/A **Private Function Members** -Todo +N/A **Public Data Members** -Todo +- `MESSAGETARGET target` +- `std::variant<BLOCKCHAINMESSAGE, DRAWERMESSAGE, GUIMESSAGE, WAVEMESSAGE, PATTERNMESSAGE> message` +- `bool handled` **Private Data Members** -Todo +N/A **Notes** -Todo +Access the correct message by first checking the `target`, and then calling `T message = std::get<T>(m.message)`, where `T` is the message type. ### PatternHandler ([pattern_handler.hpp](include/pattern_handler.hpp), [pattern_handler.cpp](src/pattern_handler.cpp)) **Description** -Todo +Handles the placement of predefined patterns. **Usage** @@ -949,32 +968,34 @@ Todo **Constructors and Destructors** -Todo +- `PatternHandler()` +- `PatternHandler(const PatternHandler&)` +- `PatternHandler(Toolbox& tb)` **Public Function Members** -Todo +- `void update(Toolbox& tb)` **Private Function Members** -Todo +- `bool load_damping_texture_(const Toolbox& tb, const std::string file, GLuint* texture_target)` **Public Data Members** -Todo +N/A **Private Data Members** -Todo +- `GLuint texture_*_` **Notes** -Todo +N/A ### Pevent ([pevent.hpp](include/pevent.hpp), [pevent.cpp](src/pevent.cpp)) **Description** -Todo +Stores `SDL_Event`s in a more convenient way. **Usage** @@ -982,32 +1003,74 @@ Todo **Constructors and Destructors** -Todo +- `Pevent()` +- `Pevent(const SDL_Event&)` **Public Function Members** -Todo +N/A **Private Function Members** -Todo +N/A **Public Data Members** -Todo +- `SDL_Event event` +- `unsigned itcoord_x, itcoord_y` +- `float fscoord_x, fscoord_y` +- `PEVENTTYPE type` +- `SDL_FingerID finger_id` **Private Data Members** -Todo +N/A **Notes** +Objects of this type should be constructed by something like the `PeventFactory`. + +### PeventFactory ([pevent.hpp](include/pevent.hpp), [pevent.cpp](src/pevent.cpp)) +**Description** + +Constructs `Pevent` objects. + +**Usage** + Todo +**Constructors and Destructors** + +- `PeventFactory()` +- `PeventFactory(const int screen_w, const int screen_h, const int texture_w, const int texture_h, const int texoffset_left, const int texoffset_right, const int texoffset_bottom, const int texoffset_top)` + - This constructor should be changed to take a `Toolbox` instead. +**Public Function Members** + +- `Pevent operator()(const SDL_Event&) const` + +**Private Function Members** + +N/A + +**Public Data Members** + +N/A + +**Private Data Members** + +- `int screen_w_, screen_h_`: screen width and height in pixels +- `int texture_w_, texture_h_`: texture width and height in texels +- `int texoffset_left_, texoffset_right_, texoffset_bottom_, texoffset_top_`: screen offsets in the texture (buffer sizes) + +**Notes** + +N/A + + ### Shader ([shader.hpp](include/shader.hpp), [shader.cpp](src/shader.cpp)) **Description** -Todo +Represents a GLSL shader. **Usage** @@ -1015,32 +1078,44 @@ Todo **Constructors and Destructors** -Todo +- `Shader()` +- `Shader(const char* vertexPath, const char* fragmentPath)` +- `Shader(const Shader&)` +- `Shader& operator=(const Shader&)` +- `~Shader()` **Public Function Members** -Todo +- `void clean_up()` +- `void use()` +- `void setBool(const std::string& name, bool value) const` +- `void setInt(const std::string& name, int value) const` +- `void setFloat(const std::string& name, float value) const` +- `void setVec2(const std::string& name, glm::vec2 value) const` +- `void setVec3(const std::string& name, glm::vec3 value) const` +- `void setVec4(const std::string& name, glm::vec4 value) const` +- `void setMat(const std::string& name, glm::mat4 value) const` **Private Function Members** -Todo +N/A **Public Data Members** -Todo +- `unsigned int ID`: **Private Data Members** -Todo +N/A **Notes** -Todo +N/A ### SlimBlockchainHandler ([slim_blockchain_handler.hpp](include/slim_blockchain_handler.hpp), [slim_blockchain_handler.cpp](src/slim_blockchain_handler.cpp)) **Description** -Todo +Handles everything related to rectangular blocks, especially the immediate mode (`Spielen`). **Usage** @@ -1048,32 +1123,47 @@ Todo **Constructors and Destructors** -Todo +- `SlimBlockchainHandler(Toolbox& tb)` **Public Function Members** -Todo +- `void update(Toolbox& tb)` +- `size_t num_blocks()` **Private Function Members** -Todo +- `void clear_blocks_()` +- `void update_blocks_(const Toolbox&, bool reload_all)` +- `void in_wave_window_(const Toolbox&, const Pevent&) const` +- `void xywhs_to_vertices_(const Toolbox&, const std::vector<bool>& duplicates, const std::vector<glm::ivec4>& xywhs, std::vector<float>& vertices) const` +- `void find_dynamic_duplicates_()` **Public Data Members** -Todo +N/A **Private Data Members** -Todo +- `int previous_mstate_` +- `std::list<EfficientBlock> blockchain_` +- `std::list<std::pair<EfficientBlock*, SDL_FingerID> > dragpairs_` +- `Shader shader_drawblocks_` +- `GLuint vao_, vbo_` +- `GLuint fbo_wave_, fbo_dynamic_, fbo_static_` +- `std::vector<glm::ivec4> drawlist_static_` +- `std::vector<glm::ivec4> drawlist_dynamic_` +- `std::vector<glm::ivec4> eraselist_dynamic_` +- `std::vector<bool> drawlist_dynamic_duplicates_` +- `std::vector<bool> eraselist_dynamic_duplicates_` **Notes** -Todo +One should unify all the framebuffers used over all objects, they could be collected in the `Toolbox`. The same is true for functions that check whether a `Pevent` is in the GUI or in the wave window. ### TimeoutHandler ([timeout_handler.hpp](include/timeout_handler.hpp), [timeout_handler.cpp](src/timeout_handler.cpp)) **Description** -Todo +Keeps track of the time since the last user input, and resets the state of the application when a set threshold is surpassed. **Usage** @@ -1081,32 +1171,34 @@ Todo **Constructors and Destructors** -Todo +- `TimeoutHandler(int seconds_to_timeout)` **Public Function Members** -Todo +- `void update(Toolbox& tb)` **Private Function Members** -Todo +N/A **Public Data Members** -Todo +N/A **Private Data Members** -Todo +- `int seconds_to_timeout_` +- `std::chrono::time_point<std::chrono::high_resolution_clock> time_last_input_` **Notes** -Todo +N/A ### Toolbox ([toolbox.hpp](include/toolbox.hpp), [toolbox.cpp](src/toolbox.cpp)) **Description** -Todo +Stores all information needed by several components. Has a mailbox to which messages to other components can be posted and a event chain where user input is stored. +The Toolbox is passed from one component to the next, so each component has all the tools when it needs to perform a specific task. **Usage** @@ -1114,32 +1206,32 @@ Todo **Constructors and Destructors** -Todo +- `Toolbox(const int screen_w, const int screen_h, const int texture_w, const int texture_h, const int texoffset_left, const int texoffset_right, const int texoffset_bottom, const int texoffset_top, const std::string shaderpath, const std::string texturepath, const std::string resourcepath)` **Public Function Members** -Todo +- `void newFrame()` **Private Function Members** -Todo +N/A **Public Data Members** -Todo +Check the source, there are ~50 members and they are well documented. **Private Data Members** -Todo +N/A **Notes** -Todo +N/A ### WaveHandler ([wave_handler.hpp](include/wave_handler.hpp), [wave_handler.cpp](src/wave_handler.cpp)) **Description** -Todo +Handles simulation and rendering of the wave. **Usage** @@ -1147,15 +1239,29 @@ Todo **Constructors and Destructors** -Todo +- `WaveHandler(Toolbox&)` **Public Function Members** -Todo +- `bool initialize(const std::string damping_file, const std::string palette_file)` +- `void update(Toolbox&)` +- `void prepare_step()` +- `bool step(Toolbox& tb, const int num_dsteps)` +- `bool render()` +- `GLuint get_damping_tex() const` +- `unsigned get_width() const` +- `unsigned get_height() const` +- `void generate_and_transfer_textures(Toolbox&)` **Private Function Members** -Todo +- `bool initialize_2D_data_()` +- `bool initialize_3D_data_()` +- `bool initialize_comp_data_(const std::string)` +- `bool initialize_render_data_(const std::string)` +- `bool initialize_shaders_()` +- `bool load_damping_(const std::string)` +- `bool load_palette_(const std::string)` **Public Data Members** @@ -1171,25 +1277,25 @@ Todo ## Enums ([enums.hpp](include/enums.hpp)) -**`MSTATE`** +**`MSTATE`** (Mouse State): `IMMEDIATE` (Zeichnen), `PLACE`, `DELETE`, `MOVE`, `DRAW` (Zeichnen), `Erase` (Radieren) -**`SSTATE`** +**`SSTATE`** (Source State): `RUN`, `STOP` -**`GSTATE`** +**`GSTATE`** (Game State): `RUN`, `FREEZE`, `EXIT` -**`MESSAGETARGET`** +**`MESSAGETARGET`**: `BLOCKCHAIN`, `DRAWER`, `GUI`, `WAVE`, `PATTERN` -**`BLOCKCHAINMESSAGE`** +**`BLOCKCHAINMESSAGE`**: `CLEAR`, `PATTERN_SINGLESLIT`, `PATTERN_DOUBLESLIT`, `PATTER_LATTICE`, `PATTERN_WAVEGUIDE`, `PATTERN_SSH`, `PATTERN_FRESNEL` -**`PATTERNMESSAGE`** +**`PATTERNMESSAGE`**: `PATTERN_SINGLESLIT`, `PATTERN_DOUBLESLIT`, `PATTER_LATTICE`, `PATTERN_WAVEGUIDE`, `PATTERN_SSH`, `PATTERN_FRESNEL` -**`DRAWERMESSAGE`** +**`DRAWERMESSAGE`**: `CLEAR` -**`GUIMESSAGE`** +**`GUIMESSAGE`**: n/a -**`WAVEMESSAGE`** +**`WAVEMESSAGE`**: `RESET_WAVE`, `RESET_DAMPING`, `DIMENSION_2D`, `DIMENSION_3D`, `DEBUG_ON`, `DEBUG_OFF` -**`PEVENTTYPE`** +**`PEVENTTYPE`**: `DOWN`, `UP`, `MOVE`, `OTHER` ## ImGui Customization The ImGui library has been customized in the following way: -- GitLab