From 0f6c2b592db761146ad55804069c1a2e60e814c6 Mon Sep 17 00:00:00 2001 From: Pascal Engeler <engelerp@phys.ethz.ch> Date: Tue, 7 Sep 2021 12:12:20 +0200 Subject: [PATCH] more documentation --- README.md | 264 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 235 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 8d6893a..e58f3e0 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,9 @@ Resources are organized in a single folder called `ft_top`. It contains the foll The program accesses these resources at runtime. +## File Formats +Todo + # Building the Project ## Windows In order to build the project, the following steps must be followed @@ -858,12 +861,36 @@ Creates and stores the SDL and OpenGL infrastructures (window, renderer, context **Public Function Members** -- `SDL_Window* window() const` +- **`SDL_Window* window() const`** + - Description: Return the window + - Preconditions: N/A + - Postconditions: The window is returned + - Notes: N/A - `SDL_Renderer* renderer() const` + - Description: Return the renderer + - Preconditions: N/A + - Postconditions: The renderer is returned + - Notes: N/A - `SDL_Context context() const` + - Description: Return the context + - Preconditions: N/A + - Postconditions: The context is returned + - Notes: N/A - `bool init(const std::string name, const int width, const int height)` + - Description: Initialize everything + - Preconditions: `name` is the window name, `width` and `height` are width and height of the window in pixels + - Postconditions: An OpenGL context has been created and connected to the `SDL_Window`. The OpenGL functions have been loaded via glad. + - Notes: N/A - `void destroy()` + - Description: Destruct all resources + - Preconditions: N/A + - Postconditions: All resources have been destroyed + - Notes: N/A - `void quit()` + - Description: Quit the application + - Preconditions: N/A + - Postconditions: All resources have been destroyed and the application has quit + - Notes: N/A **Private Function Members** @@ -875,14 +902,14 @@ N/A **Private Data Members** -- `SDL_Window* window_` -- `SDL_Renderer* renderer_` -- `SDL_Context context_` +- `SDL_Window* window_`: Window +- `SDL_Renderer* renderer_`: Renderer +- `SDL_Context context_`: Context **Notes** -Todo +N/A ### InputHandler ([input_handler.hpp](include/input_handler.hpp), [input_handler.cpp](src/input_handler.cpp)) **Description** @@ -900,6 +927,10 @@ Todo **Public Function Members** - `void update(Toolbox& tb)` + - Description: Collect all current SDL events and store them as `Pevent`s in the toolbox `events` + - Preconditions: N/A + - Postconditions: The toolbox `events` have been updated + - Notes: N/A **Private Function Members** @@ -971,14 +1002,23 @@ Todo - `PatternHandler()` - `PatternHandler(const PatternHandler&)` - `PatternHandler(Toolbox& tb)` + - Notes: This constructor sets up the necessary OpenGL objects and loads the textures **Public Function Members** - `void update(Toolbox& tb)` + - Description: Checks the mailbox, and upon requests draws the desired structure into the static damping texture + - Preconditions: Correctly constructed object + - Postconditions: All messages concerning patterns have been handled + - Notes: N/A **Private Function Members** - `bool load_damping_texture_(const Toolbox& tb, const std::string file, GLuint* texture_target)` + - Description: Load a damping texture from file, upload it to the GPU and return the texture handler in the `GLuint` out argument. + - Preconditions: `file` is the texture file without extension, `texture_target` is an out argument + - Postconditions: The texture has been uploaded to the GPU and has handler `texture_target` + - Notes: N/A **Public Data Members** @@ -1047,6 +1087,10 @@ Todo **Public Function Members** - `Pevent operator()(const SDL_Event&) const` + - Description: Generate a `Pevent` from and `SDL_Event` + - Preconditions: N/A + - Postconditions: Returns a `Pevent` that corresponds to the `SDL_Event` passed as argument. + - Notes: N/A **Private Function Members** @@ -1066,7 +1110,6 @@ N/A N/A - ### Shader ([shader.hpp](include/shader.hpp), [shader.cpp](src/shader.cpp)) **Description** @@ -1080,6 +1123,7 @@ Todo - `Shader()` - `Shader(const char* vertexPath, const char* fragmentPath)` + - Notes: This is the correct way to initialize a shader from sources. - `Shader(const Shader&)` - `Shader& operator=(const Shader&)` - `~Shader()` @@ -1087,14 +1131,50 @@ Todo **Public Function Members** - `void clean_up()` + - Description: Clean up the OpenGL resources associated with this shader + - Preconditions: N/A + - Postconditions: N/A + - Notes: N/A - `void use()` + - Description: Activates the shader + - Preconditions: Correctly constructed object + - Postconditions: The shader program is used + - Notes: N/A - `void setBool(const std::string& name, bool value) const` + - Description: Set a boolean uniform + - Preconditions: `name` is the name of the target uniform, `value` the target value. + - Postconditions: The target uniform has been set to `value` + - Notes: N/A - `void setInt(const std::string& name, int value) const` + - Description: Set an integer uniform + - Preconditions: `name` is the name of the target uniform, `value` the target value. + - Postconditions: The target uniform has been set to `value` + - Notes: N/A - `void setFloat(const std::string& name, float value) const` + - Description: Set a float uniform + - Preconditions: `name` is the name of the target uniform, `value` the target value. + - Postconditions: The target uniform has been set to `value` + - Notes: N/A - `void setVec2(const std::string& name, glm::vec2 value) const` + - Description: Set a vec2 uniform + - Preconditions: `name` is the name of the target uniform, `value` the target value. + - Postconditions: The target uniform has been set to `value` + - Notes: N/A - `void setVec3(const std::string& name, glm::vec3 value) const` + - Description: Set a vec3 uniform + - Preconditions: `name` is the name of the target uniform, `value` the target value. + - Postconditions: The target uniform has been set to `value` + - Notes: N/A - `void setVec4(const std::string& name, glm::vec4 value) const` + - Description: Set a vec4 uniform + - Preconditions: `name` is the name of the target uniform, `value` the target value. + - Postconditions: The target uniform has been set to `value` + - Notes: N/A - `void setMat(const std::string& name, glm::mat4 value) const` + - Description: Set a mat4 uniform + - Preconditions: `name` is the name of the target uniform, `value` the target value. + - Postconditions: The target uniform has been set to `value` + - Notes: N/A **Private Function Members** @@ -1102,7 +1182,7 @@ N/A **Public Data Members** -- `unsigned int ID`: +- `unsigned int ID`: OpenGL handle of the shader program **Private Data Members** @@ -1115,7 +1195,9 @@ N/A ### SlimBlockchainHandler ([slim_blockchain_handler.hpp](include/slim_blockchain_handler.hpp), [slim_blockchain_handler.cpp](src/slim_blockchain_handler.cpp)) **Description** -Handles everything related to rectangular blocks, especially the immediate mode (`Spielen`). +Handles everything related to rectangular blocks, especially the immediate mode (`Spielen`). +Drawing is handled in a batched manner: There are eraselists and drawlists that store objects that are to be drawn or erased. +The drawcalls are issued at the very end of the update-cycle, all in one. **Usage** @@ -1128,15 +1210,44 @@ Todo **Public Function Members** - `void update(Toolbox& tb)` + - Description: Update the toolbox - first handle messages, then handle events, update erase-/drawlists (dynamic and static) and finally draw the updated state to the dynamic damping and wave 1 textures. + - Preconditions: Fully initialized object + - Postconditions: The state has been updated and drawn to the necessary textures + - Notes: N/A - `size_t num_blocks()` + - Description: Get the current number of active blocks + - Preconditions: N/A + - Postconditions: The number of blocks is returned + - Notes: N/A **Private Function Members** - `void clear_blocks_()` + - Description: Erases all current blocks + - Preconditions: N/A + - Postconditions: All blocks have been erased, `dragpairs_` and `blockchain_` are empty + - Notes: N/A - `void update_blocks_(const Toolbox&, bool reload_all)` -- `void in_wave_window_(const Toolbox&, const Pevent&) const` + - Description: Updates the state of the block tracking. First, the draw-/eraselists are checked for duplicated inputs (e.g. draw at R, erase at R, draw at R', erase at R', draw at R''). + Then the vertices of blocks to be drawn / erased are calculated, and the queues are executed in the order: erase dynamic blocks, draw static blocks, draw dynamic blocks. + - Preconditions: N/A + - Postconditions: N/A + - Notes: N/A +- `bool in_wave_window_(const Toolbox&, const Pevent&) const` + - Description: Check if a `Pevent` is within the wave window + - Preconditions: N/A + - Postconditions: Returns `true` if the passed `Pevent` is in the wave window, `false` else + - Notes: N/A - `void xywhs_to_vertices_(const Toolbox&, const std::vector<bool>& duplicates, const std::vector<glm::ivec4>& xywhs, std::vector<float>& vertices) const` + - Description: Calculate all vertices corresponding to the `EfficientBlock` `xywh` coordinates stored in `xywhs` and store them in `vertices`, while ignoring `xywhs[i]` if `duplicates[i] == true`. + - Preconditions: N/A + - Postconditions: The vertices corresponding to the non-duplicate marked `xywhs` coordinates have been calculated and are stored in `vertices`. Previous contents of `vertices` have been deleted. + - Notes: If duplicates are not tracked (e.g. for static blocks, which can't be erased), pass `std::vector<bool>(xywhs.size(), false)` as `duplicates`. - `void find_dynamic_duplicates_()` + - Description: Find duplicates in the dynamic draw-/eraselists and store them in the members `drawlist_dynamic_duplicates_` and `eraselist_dynamic_duplicates_`, respectively + - Preconditions: N/A + - Postconditions: The dynamic duplicate storing members have been updated according to the current dynamic draw-/eraselists + - Notes: This takes care that one erase can only delete one draw. **Public Data Members** @@ -1144,21 +1255,23 @@ N/A **Private Data Members** -- `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_` +- `int previous_mstate_`: The tb.mstate of the previous frame +- `std::list<EfficientBlock> blockchain_`: list of current `EfficientBlocks` +- `std::list<std::pair<EfficientBlock*, SDL_FingerID> > dragpairs_`: list of blocks and their controlling finger +- `Shader shader_drawblocks_`: Shader used to draw blocks +- `GLuint vao_, vbo_`: OpenGL infrastructure, vertex array object and vertex buffer object +- `GLuint fbo_wave_, fbo_dynamic_, fbo_static_`: framebuffer objects targeting the wave 1 texture, the dynamic damping texture, and the static damping texture, respectively +- `std::vector<glm::ivec4> drawlist_static_`: xywh coordinates of blocks to be drawn to the static damping texture +- `std::vector<glm::ivec4> drawlist_dynamic_`: xywh coordinates of blocks to be drawn to the dynamic damping texture +- `std::vector<glm::ivec4> eraselist_dynamic_`: xywh coordinates of blocks to be erased from the dynamic damping texture +- `std::vector<bool> drawlist_dynamic_duplicates_`: marks which indices of the dynamic drawlist are duplicates (i.e. paired with an entry of the dynamic eraselist) +- `std::vector<bool> eraselist_dynamic_duplicates_`: marks which indices of the dynamic eraselist are duplicates (i.e. paired with an entry of the dynamic drawlist) **Notes** 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. +There used to be issues with this class, because duplicates were not tracked / tracked incorrectly. For example, one frame can contain several move commands, e.g. move to R, then move to R'. +Because erasing is completed before drawing is started, this would leave blocks at R and R', unless the draw and erase at R are marked as net-0x90. ### TimeoutHandler ([timeout_handler.hpp](include/timeout_handler.hpp), [timeout_handler.cpp](src/timeout_handler.cpp)) **Description** @@ -1172,10 +1285,15 @@ Todo **Constructors and Destructors** - `TimeoutHandler(int seconds_to_timeout)` + - Notes: This constructs a timeout handler with timeout `seconds_to_timeout` **Public Function Members** - `void update(Toolbox& tb)` + - Description: Check how much time has passed since an event has last come in, and if it exceeds the timeout, post reset messages and reset the timer. + - Preconditions: N/A + - Postconditions: If the timer exceeds the timeout, a reset has been posted. If `tb.events` is not empty or the timer has exceeded the timeout, the timer has been reset. + - Notes: The reset messages need to be adjusted if more components are added. Potentially, one could add a messagetarget `ALL`, with a message `RESET` everyone listens to. **Private Function Members** @@ -1187,8 +1305,8 @@ N/A **Private Data Members** -- `int seconds_to_timeout_` -- `std::chrono::time_point<std::chrono::high_resolution_clock> time_last_input_` +- `int seconds_to_timeout_`: Number of seconds that constitute a timeout +- `std::chrono::time_point<std::chrono::high_resolution_clock> time_last_input_`: Time of last user input **Notes** @@ -1211,6 +1329,10 @@ Todo **Public Function Members** - `void newFrame()` + - Description: Start a new frame + - Preconditions: N/A + - Postconditions: `mailbox` and `events` have been cleared + - Notes: Call this function at the very beginning of each frame **Private Function Members** @@ -1226,7 +1348,8 @@ N/A **Notes** -N/A +For full initialization, this class needs external objects. More precisely, after construction, it needs a `WaveHandler` to call `WaveHandler::generate_and_transfer_textures` on it. +Else the textures stay un-initialized. ### WaveHandler ([wave_handler.hpp](include/wave_handler.hpp), [wave_handler.cpp](src/wave_handler.cpp)) **Description** @@ -1244,37 +1367,120 @@ Todo **Public Function Members** - `bool initialize(const std::string damping_file, const std::string palette_file)` + - Description: Fully initialize the object (especially shaders, textures, framebuffers and other OpenGL infrastructure) + - Preconditions: N/A + - Postconditions: The object is fully initialized + - Notes: Without a call to this function, the object is not functional. - `void update(Toolbox&)` + - Description: Handle all messages addressed to this object + - Preconditions: N/A + - Postconditions: All relevant messages have been handled + - Notes: N/A - `void prepare_step()` + - Description: Prepare for timestepping by combining the dynamic and static damping textures into one texture. + - Preconditions: N/A + - Postconditions: The texture `tex_comp_damp_` has been updated + - Notes: N/A - `bool step(Toolbox& tb, const int num_dsteps)` + - Description: Perform `num_dsteps` double-timesteps on the wave + - Preconditions: N/A + - Postconditions: 2*`num_dsteps` timesteps have been performed and the latest step is stored in `tex_comp_wave_1_`. + - Notes: Always returns `true` - `bool render()` + - Description: Render `tex_comp_damp_` and `tex_wave_1_` using the color scheme `tex_palette_` to the current screenbuffer using shader `shdr_2d_` + - Preconditions: N/A + - Postconditions: The state has been rendered + - Notes: Always returns `true` - `GLuint get_damping_tex() const` + - Description: Get the combined damping texture + - Preconditions: N/A + - Postconditions: The combined damping texture handler is returned + - Notes: N/A - `unsigned get_width() const` + - Description: Get the window width + - Preconditions: N/A + - Postconditions: The window width is returned + - Notes: N/A - `unsigned get_height() const` + - Description: Get the window height + - Preconditions: N/A + - Postconditions: The window height is returned + - Notes: N/A - `void generate_and_transfer_textures(Toolbox&)` + - Description: Generate textures and transfer these and existing textures to the `Toolbox`. + - Preconditions: N/A + - Postconditions: Three textures have been generated and initialized correctly: `tb.tex_damp_clean`, `tb.tex_wave_clean`, `tb.tex_const_zero`. + Four textures have been transferred to the `Toolbox`: `tex_comp_damp_dynamic_`, `tex_comp_damp_static_`, `tex_comp_wave_0_`, `tex_comp_wave_1_` + - Notes: This function has to be called to fully initialize the `Toolbox` **Private Function Members** - `bool initialize_2D_data_()` + - Description: Initialize OpenGL infrastructure to perform timesteps + - Preconditions: N/A + - Postconditions: The objects `num_elements_2d`, `vao_2d_`, `vbo_2d_`, `ebo_2d_` have been initialized + - Notes: N/A - `bool initialize_3D_data_()` + - Description: Do not call + - Preconditions: N/A + - Postconditions: N/A + - Notes: N/A - `bool initialize_comp_data_(const std::string)` + - Description: Initialize damping and wave textures, and time stepping framebuffers + - Preconditions: The argument specifies the damping file, without extension. + - Postconditions: The vanilla damping profile has been loaded from file, or a backup has been generated in case the file is missing. + The damping textures `tex_comp_damp_`, `tex_comp_damp_dynamic_`, `tex_comp_damp_static_` have been generated and initialized. + The wave textures `tex_comp_wave_0_` and `tex_comp_wave_1_` have been generated and initialized. + The framebuffers `fb_comp_0_`, `fb_comp_1_`, `fb_comp_damp_` have been generated and initialized. + - Notes: Always returns `true` - `bool initialize_render_data_(const std::string)` + - Description: Load the colour palette and upload it to the GPU, initialize rendering infrastructure + - Preconditions: The argument specifies a file where the colour palette texture can be found (without extension) + - Postconditions: The colour palette has been loaded from file and uploaded to the GPU in texture `tex_palette_`. + The rendering infrastructure, namely `vao_render_`, `vbo_render_`, `ebo_render_` have been generated and initialized. + - Notes: Always returns `true`, except when the colour palette file is invalid. - `bool initialize_shaders_()` + - Description: Initialize all shaders + - Preconditions: N/A + - Postconditions: The following shaders have been initialized from source: `shdr_step_`(stepwave), `shdr_2d_`(render2d), `shdr_2d_dbg_`(render2d), `shdr_damp_`(combine_damping) and their uniforms have been set + - Notes: Always returns `true` - `bool load_damping_(const std::string)` + - Description: Load a damping texture from file into `tex_damp_data_` + - Preconditions: The argument specifies a damping file without file extension + - Postconditions: The damping texture has been loaded into `tex_damp_data_`. On success, `true` has been returned, `false` else. + - Notes: In the same directory, there needs to be a `.conf` and a `.texture` file with the specified name. + This function is very inefficient and can be optimized. - `bool load_palette_(const std::string)` + - Description: Load the colour palette texture from file into `palette_` + - Preconditions: The argument specifies the palette file without file extension + - Postconditions: The colour palette texture has been loaded into `palette_`. On success, `true` has been returned, `false` else. + - Notes: In the same directory, there needs to be a `.conf` and a `.texture` file with the specified name. **Public Data Members** Todo **Private Data Members** - -Todo +Only relevant members are listed + +- `const int width_, height_`: Window dimensions +- `const int texwidth_, texheight_`: Texture dimensions +- `const int texoffset_left_, texoffset_right_, texoffset_bottom_, texoffset_top_`: Offsets in pixels in textures from the screen +- `const std::string shader_path_`: Path to shaders +- `GLuint vbo_2d_, vao_2d_, ebo_2d_, num_elements_2d_`: Timestepping OpenGL infrastructure +- `GLuint vbo_render_, vao_render_, ebo_render_, num_elements_render_`: Rendering OpenGL infrastructure +- `GLuint fb_comp_0_, fb_comp_1_, fb_comp_damp_`: Framebuffers targeting wave texture 0 `tex_comp_wave_0_`, wave texture 1 `tex_comp_wave_1_` and the combined damping texture `tex_comp_damp_`, respectively. +- `GLuint tex_comp_wave_0_, tex_comp_wave_1_`: Wave textures 0 and 1, between which timestepping happens. The latest state is always in `tex_comp_wave_1_`, and the first step of a chain goes from 1 to 0. +- `GLuint tex_comp_damp_`: Combined damping texture +- `GLuint tex_comp_damp_dynamic_, tex_comp_damp_static_`: Dynamic damping texture (for obstacles that are dynamic like "Spielen" blocks) and static damping texture (for static obstacles like drawings and predefined structures) +- `std::vector<float> palette_`: colour palette texture data +- `GLuint tex_palette_`: Colour palette texture handle +- `Shader shdr_step_, shdr_2d_, shdr_2d_dbg_, shdr_damp_`: Shaders used for timestepping, rendering (without and with debugging) and damping combination +- `std::vector<float> tex_wave_data_, tex_damp_data_`: The vanilla wave and damping texture data **Notes** -Todo - +This class predates the Toolbox and is not yet well integrated into the flow. All member functions assume the object is fully initialized. ## Enums ([enums.hpp](include/enums.hpp)) **`MSTATE`** (Mouse State): `IMMEDIATE` (Zeichnen), `PLACE`, `DELETE`, `MOVE`, `DRAW` (Zeichnen), `Erase` (Radieren) @@ -1283,9 +1489,9 @@ Todo **`GSTATE`** (Game State): `RUN`, `FREEZE`, `EXIT` -**`MESSAGETARGET`**: `BLOCKCHAIN`, `DRAWER`, `GUI`, `WAVE`, `PATTERN` +**`MESSAGETARGET`** (Possible targets for messages): `BLOCKCHAIN`, `DRAWER`, `GUI`, `WAVE`, `PATTERN` -**`BLOCKCHAINMESSAGE`**: `CLEAR`, `PATTERN_SINGLESLIT`, `PATTERN_DOUBLESLIT`, `PATTER_LATTICE`, `PATTERN_WAVEGUIDE`, `PATTERN_SSH`, `PATTERN_FRESNEL` +**`BLOCKCHAINMESSAGE`** (Possible messages to the `SlimBlockchainHandler`): `CLEAR`, `PATTERN_SINGLESLIT`, `PATTERN_DOUBLESLIT`, `PATTER_LATTICE`, `PATTERN_WAVEGUIDE`, `PATTERN_SSH`, `PATTERN_FRESNEL` **`PATTERNMESSAGE`**: `PATTERN_SINGLESLIT`, `PATTERN_DOUBLESLIT`, `PATTER_LATTICE`, `PATTERN_WAVEGUIDE`, `PATTERN_SSH`, `PATTERN_FRESNEL` -- GitLab