From 781659f5c1a0c9e5d57348ce3e28194f3d9cdeef Mon Sep 17 00:00:00 2001
From: Pascal Engeler <engelerp@phys.ethz.ch>
Date: Tue, 7 Sep 2021 16:19:19 +0200
Subject: [PATCH] consistent formating in readme
---
README.md | 618 +++++++++++-------------------------------------------
1 file changed, 122 insertions(+), 496 deletions(-)
diff --git a/README.md b/README.md
index 08bcf99..55d2d06 100644
--- a/README.md
+++ b/README.md
@@ -102,115 +102,45 @@ Todo
**Constructors and Destructors**
- `Drawer(Toolbox&)`
- - **Notes**:
-
- The argument is unused. It should be removed.
-
+ - Notes: The argument is unused. It should be removed.
- `Drawer(const Drawer&) = default`
-
- `~Drawer() = default`
**Public Function Members**
- `void start_drawing(const float x, const float y)`:
- - **Description**
-
- Start drawing at coordinates (`x`, `y`) (typically fingerdown location). Doesn't draw anything.
-
- - **Preconditions**
-
- - **Postconditions**
-
- Drawing start is set to (x, y).
-
- - **Notes**
-
- Nothing is drawn by this function. (x, y) are typically the fingerdown coordinates.
-
+ - Description: Start drawing at coordinates (`x`, `y`) (typically fingerdown location). Doesn't draw anything.
+ - Preconditions:
+ - Postconditions:Drawing start is set to (x, y).
+ - Notes: Nothing is drawn by this function. (x, y) are typically the fingerdown coordinates.
- `bool draw(const float x, const float y, Toolbox& tb, bool drawing)`
- - **Description**
-
- Draw a stroke from the last position to (x, y), with strokewidth controlled by `drawing` (`true`->`tb.drawing_width`, `false`->`tb.erasing_width`).
-
- - **Preconditions**
-
- A `GL_ARRAY_BUFFER` is bound and the Opengl state is set as desired
-
- - **Postconditions**
-
- The points of the new segment have been calculated and uploaded to the currently bound `GL_ARRAY_BUFFER`, a call to `glDrawArrays` has been done to draw the segment.
-
+ - Description: Draw a stroke from the last position to (x, y), with strokewidth controlled by `drawing` (`true`->`tb.drawing_width`, `false`->`tb.erasing_width`).
+ - Preconditions: A `GL_ARRAY_BUFFER` is bound and the Opengl state is set as desired
+ - Postconditions: The points of the new segment have been calculated and uploaded to the currently bound `GL_ARRAY_BUFFER`, a call to `glDrawArrays` has been done to draw the segment.
Returns `true` if something was drawn, and `false` else (typically when new point is same as last point).
-
- - **Notes**
-
+ - Notes:
- `void redraw(Toolbox&)`
- - **Description**:
-
- Redraws the last drawn stroke.
-
- - **Preconditions**:
-
- `draw` has been called at least once, and since the last call to `draw`, the then-bound `GL_ARRAY_BUFFER` has not been modified.
-
- - **Postconditions**:
-
- A drawcall `glDrawArrays` has been issued.
-
- - **Notes**:
-
+ - Description: Redraws the last drawn stroke.
+ - Preconditions: `draw` has been called at least once, and since the last call to `draw`, the then-bound `GL_ARRAY_BUFFER` has not been modified.
+ - Postconditions: A drawcall `glDrawArrays` has been issued.
+ - Notes:
- `void erase(const float x, const float y, Toolbox& tb)` **DEPRECATED**
- - **Description**:
-
-
-
- - **Preconditions**:
-
-
-
- - **Postconditions**:
-
-
-
- - **Notes**:
-
- Use `draw(x, y, tb, false)` instead.
-
+ - Notes: Use `draw(x, y, tb, false)` instead.
- `int num_drawn()`
- - **Description**:
-
- Returns the number of calls to `draw` and `erase` that have been performed by this object.
-
- - **Preconditions**:
-
-
-
- - **Postconditions**:
-
-
-
- - **Notes**:
+ - Description: Returns the number of calls to `draw` and `erase` that have been performed by this object.
+ - Preconditions:
+ - Postconditions:
+ - Notes:
**Private Function Members**
- `bool calculate_points_(Toolbox& tb, bool drawing)`
- - **Description**:
-
- Calculate the triangulation of the stroke represented by the internal parameters, and store them in `points_`.
+ - Description: Calculate the triangulation of the stroke represented by the internal parameters, and store them in `points_`.
The stroke width is controlled by `drawing` (`true`->`tb.drawing_width`, `false`->`tb.erasing_width`).
-
- - **Preconditions**:
-
- The points (`x0_`, `y0_`) and (`x1_`, `y1_`) are set as desired.
-
- - **Postconditions**:
-
- If the points (`x0_`, `y0_`), (`x1_`, `y1_`) are the same, false has been returned and the call has no effect.
+ - Preconditions: The points (`x0_`, `y0_`) and (`x1_`, `y1_`) are set as desired.
+ - Postconditions: If the points (`x0_`, `y0_`), (`x1_`, `y1_`) are the same, false has been returned and the call has no effect.
Else, `true` has been returned, and the vertices that make up the segment between these two points with the desired width have been calculated and stored in `points_`.
-
-
- - **Notes**:
-
+ - Notes:
**Public Data Members**
@@ -218,16 +148,9 @@ Todo
N/A
**Private Data Members**
-- `float x0_, y0_, x1_, y1_`
-
- Internal representation of old ('0') and new ('1') points.
-- `int num_drawn_`
-
- Number of calls to `draw` and `erase`.
-
-- `std::vector<float> points_`
-
- Vertex coordinates that represent the stroke between old and new points, as calculated by `calculate_points_`.
+- `float x0_, y0_, x1_, y1_`: Internal representation of old ('0') and new ('1') points.
+- `int num_drawn_`: Number of calls to `draw` and `erase`.
+- `std::vector<float> points_`: Vertex coordinates that represent the stroke between old and new points, as calculated by `calculate_points_`.
**Notes**
@@ -246,93 +169,36 @@ This class handles all aspects of the `Zeichnen` / `Radieren` functionality. It
**Constructors and Destructors**
- `DrawingHandler(Toolbox&)`
- - **Notes**
-
- `Toolbox` is needed to find shader sources and obtain handles to the damping and wave textures.
-
+ - Notes: `Toolbox` is needed to find shader sources and obtain handles to the damping and wave textures.
- `~DrawingHandler()`
**Public Function Members**
- `void update(Toolbox&)`
-
- - **Description**:
-
- Handles messages directed to it, parses events and takes the necessary actions (spawn / delete `Drawer`s, draw with `Drawer`s using correct infrastructure).
-
- - **Preconditions**:
-
- The object is initialized correctly.
-
- - **Postconditions**:
-
- The desired portions have been drawn to static damping and to the wave 1 texture.
-
- - **Notes**:
-
- N/A
-
+ - Description: Handles messages directed to it, parses events and takes the necessary actions (spawn / delete `Drawer`s, draw with `Drawer`s using correct infrastructure).
+ - Preconditions: The object is initialized correctly.
+ - Postconditions: The desired portions have been drawn to static damping and to the wave 1 texture.
+ - Notes:
- `size_t num_drawers()`
-
- - **Description**:
-
- Returns the current number of active `Drawer`s.
-
- - **Preconditions**:
-
- N/A
-
- - **Postconditions**:
-
- N/A
-
- - **Notes**:
-
- N/A
+ - Description: Returns the current number of active `Drawer`s.
+ - Preconditions:
+ - Postconditions:
+ - Notes:
**Private Function Members**
- `void draw_(Toolbox&)`
-
- - **Notes**:
-
- Does nothing.
-
+ - Notes: Does nothing.
- `bool in_wave_window_(const Toolbox&, const Pevent&) const`
-
- - **Description**:
-
- Check if an event is within the wave window.
-
- - **Preconditions**:
-
- N/A
-
- - **Postconditions**:
-
- Returns `true` if the event is in the wave window, and `false` else (i.e. when event is in the GUI window).
-
- - **Notes**:
-
- N/A
-
+ - Description: Check if an event is within the wave window.
+ - Preconditions:
+ - Postconditions: Returns `true` if the event is in the wave window, and `false` else (i.e. when event is in the GUI window).
+ - Notes:
- `std::array<float, 2> drawerCoordinates_(const Pevent&, const Toolbox&)`
-
- - **Description**:
-
- Compute drawer coordinates of a `Pevent`.
-
- - **Preconditions**:
-
- N/A
-
- - **Postconditions**:
-
- N/A
-
- - **Notes**:
-
- The method `Drawer::draw` should be called with the return values of this function.
+ - Description: Compute drawer coordinates of a `Pevent`.
+ - Preconditions:
+ - Postconditions:
+ - Notes: The method `Drawer::draw` should be called with the return values of this function.
**Public Data Members**
@@ -393,128 +259,40 @@ Represents a rectangular block. Scaled down version of the previous `Block`, opt
**Public Function Members**
- `void request_removal()`
-
- - **Description**:
-
- Mark block for removal
-
- - **Preconditions**:
-
- N/A
-
- - **Postconditions**:
-
- Block is marked for removal
-
- - **Notes**:
-
- N/A
-
+ - Description: Mark block for removal
+ - Preconditions:
+ - Postconditions: Block is marked for removal
+ - Notes:
- `void translate(int new_x, int new_y)`
-
- - **Description**:
-
- Translate block to new (LLC) texel-coordinates.
-
- - **Preconditions**:
-
- N/A
-
- - **Postconditions**:
-
- Block has been translated to (`new_x`, `new_y`).
-
- - **Notes**:
-
- N/A
-
+ - Description: Translate block to new (LLC) texel-coordinates.
+ - Preconditions:
+ - Postconditions: Block has been translated to (`new_x`, `new_y`).
+ - Notes:
- `bool needs_removal() const`
-
- - **Description**:
-
- Check if block is marked for removal.
-
- - **Preconditions**:
-
- N/A
-
- - **Postconditions**:
-
- Returns `true` if block has been marked for removal, and `false` else.
-
- - **Notes**:
-
- N/A
-
+ - Description: Check if block is marked for removal.
+ - Preconditions:
+ - Postconditions: Returns `true` if block has been marked for removal, and `false` else.
+ - Notes:
- `glm::ivec4 xywh() const`
-
- - **Description**:
-
- Get coordinates and dimensions of block.
-
- - **Preconditions**:
-
- N/A
-
- - **Postconditions**:
-
- Returns a `glm::ivec4`; `[0]`->x, `[1]`->y, `[2]`->width, `[3]`->height.
-
- - **Notes**:
-
-
-
+ - Description: Get coordinates and dimensions of block.
+ - Preconditions:
+ - Postconditions: Returns a `glm::ivec4`; `[0]`->x, `[1]`->y, `[2]`->width, `[3]`->height.
+ - Notes:
- `bool is_inside(int x, int y) const`
-
- - **Description**:
-
- Check if a point lies within the block.
-
- - **Preconditions**:
-
- N/A
-
- - **Postconditions**:
-
- Returns `true` if point (`x`, `y`) is inside the block, `false` else.
-
- - **Notes**:
-
- N/A
-
+ - Description: Check if a point lies within the block.
+ - Preconditions:
+ - Postconditions: Returns `true` if point (`x`, `y`) is inside the block, `false` else.
+ - Notes:
- `int width() const`
-
- - **Description**:
-
- Get the width of the block.
-
- - **Preconditions**:
-
- N/A
-
- - **Postconditions**:
-
- Returns the width of the block in texels.
-
- - **Notes**:
-
-
-
+ - Description: Get the width of the block.
+ - Preconditions:
+ - Postconditions: Returns the width of the block in texels.
+ - Notes:
- `int height() const`
-
- - **Description**:
-
- Get the height of the block.
-
- - **Preconditions**:
-
-
-
- - **Postconditions**:
-
- Returns the height of the block in texels.
-
- - **Notes**:
+ - Description: Get the height of the block.
+ - Preconditions:
+ - Postconditions: Returns the height of the block in texels.
+ - Notes:
**Private Function Members**
@@ -527,13 +305,8 @@ N/A
**Private Data Members**
-- `glm::ivec4 xywh_`
-
- Coordinates and dimensions of block
-
-- `bool needs_removal_`
-
- Is block marked for removal?
+- `glm::ivec4 xywh_`: Coordinates and dimensions of block
+- `bool needs_removal_`: Is block marked for removal?
**Notes**
@@ -559,42 +332,20 @@ Logs events directly from the `Toolbox` and sorts them by type in 16-deep circul
- `void push_events(Toolbox&)`
- - **Description**:
-
- Catch events from `Toolbox`
-
- - **Preconditions**:
-
- New events have been captured by the `Toolbox`
-
- - **Postconditions**:
-
- The events have been sorted into their corresponding circular buffer
-
- - **Notes**:
-
- N/A
+ - Description: Catch events from `Toolbox`
+ - Preconditions: New events have been captured by the `Toolbox`
+ - Postconditions: The events have been sorted into their corresponding circular buffer
+ - Notes:
**Non-Member Functions**
- `std::string ptos(const Pevent&, const Toolbox&)`
- - **Description**:
-
- Convert a `Pevent` to a `std::string`.
-
- - **Preconditions**:
-
- N/A
-
- - **Postconditions**:
-
- Returns a `std::string` that describes the `Pevent`.
-
- - **Notes**:
-
- The `Toolbox` argument is used for coordinate transformation.
+ - Description: Convert a `Pevent` to a `std::string`.
+ - Preconditions:
+ - Postconditions: Returns a `std::string` that describes the `Pevent`.
+ - Notes: The `Toolbox` argument is used for coordinate transformation.
**Private Function Members**
@@ -603,26 +354,11 @@ N/A
**Public Data Members**
-- `unsigned i_down, i_up, i_move, i_other`
-
- Index where next event is to be inserted.
-
-- `std::array<Pevent, 16> events_down`
-
- Events of down-type.
-
-- `std::array<Pevent, 16> events_up`
-
- Events of up-type.
-
-- `std::array<Pevent, 16> events_move`
-
- Events of move-type.
-
-- `std::array<Pevent, 16> events_other`
-
- Events of other-type.
-
+- `unsigned i_down, i_up, i_move, i_other`: Index where next event is to be inserted.
+- `std::array<Pevent, 16> events_down`: Events of down-type.
+- `std::array<Pevent, 16> events_up`: Events of up-type.
+- `std::array<Pevent, 16> events_move`: Events of move-type.
+- `std::array<Pevent, 16> events_other`: Events of other-type.
**Private Data Members**
@@ -652,173 +388,63 @@ Draws and controls all functionality related to the GUI.
**Public Function Members**
- **`void init(Toolbox& tb, const std::string path_img, const std::string path_ttf)`**
-
- - **Description**:
-
- Initialize all GUI related infrastructure
-
- - **Preconditions**:
-
- Fully setup `Toolbox`, correct paths to images and fonts
-
- - **Postconditions**:
-
- Fonts and images have been loaded, ImGui is fully initialized.
-
- - **Notes**:
+ - Description: Initialize all GUI related infrastructure
+ - Preconditions: Fully setup `Toolbox`, correct paths to images and fonts
+ - Postconditions: Fonts and images have been loaded, ImGui is fully initialized.
+ - Notes:
- **`void update(Toolbox& tb)`**
- - **Description**:
-
- Update the GUI
-
- - **Preconditions**:
-
- N/A
-
- - **Postconditions**:
-
- Tasks performed:
+ - Description: Update the GUI
+ - Preconditions:
+ - Postconditions: Tasks performed:
- Check if application has to quit and handle this
- Check if there is a new finger that controls the GUI, or if the controlling finger was released
- Handle any input to the GUI, pass it on to ImGui for processing
- Construct the GUI
-
- - **Notes**:
-
- N/A
+ - Notes:
- **`void render(Toolbox& tb)`**
-
- - **Description**:
-
- Render the GUI to the screenbuffer.
-
- - **Preconditions**:
-
- N/A
-
- - **Postconditions**:
-
- The GUI is drawn on the screenbuffer.
-
- - **Notes**:
-
- N/A
+ - Description: Render the GUI to the screenbuffer.
+ - Preconditions:
+ - Postconditions: The GUI is drawn on the screenbuffer.
+ - Notes:
**Private Function Members**
- **`bool isInGuiWindow_(const Pevent&) const`**
-
- - **Description**:
-
- Check if a `Pevent` is within the GUI window.
-
- - **Preconditions**:
-
- N/A
-
- - **Postconditions**:
-
- Returns `true` if the `Pevent` is within the GUI window, `false` else.
-
- - **Notes**:
-
- N/A
-
+ - Description: Check if a `Pevent` is within the GUI window.
+ - Preconditions:
+ - Postconditions: Returns `true` if the `Pevent` is within the GUI window, `false` else.
+ - Notes:
- **`void draw_gui_(Toolbox& tb)`**
-
- - **Description**:
-
- Construct a semi-old version of the GUI
-
- - **Preconditions**:
-
- All resources have been loaded
-
- - **Postconditions**:
-
- N/A
-
- - **Notes**:
-
- N/A
-
+ - Description: Construct a semi-old version of the GUI
+ - Preconditions: All resources have been loaded
+ - Postconditions:
+ - Notes:
- **`void draw_gui_ft_(Toolbox& tb)`**
-
- - **Description**:
-
- Construct the GUI used at FocusTerra
-
- - **Preconditions**:
-
- All resources have been loaded.
-
- - **Postconditions**:
-
- N/A
-
- - **Notes**:
-
- N/A
-
+ - Description: Construct the GUI used at FocusTerra
+ - Preconditions: All resources have been loaded.
+ - Postconditions:
+ - Notes:
- **`void draw_old_gui_(Toolbox& tb)`**
-
- - **Description**:
-
- Construct the old GUI.
-
- - **Preconditions**:
-
- All resources have been loaded
-
- - **Postconditions**:
-
- N/A
-
- - **Notes**:
-
- N/A
-
+ - Description: Construct the old GUI.
+ - Preconditions: All resources have been loaded
+ - Postconditions:
+ - Notes:
- **`void load_button_textures_(const std::string path)`**
-
- - **Description**:
-
- Load all necessary images into textures.
-
- - **Preconditions**:
-
- All images can be found in `path`, and they all have the correct format.
-
- - **Postconditions**:
-
- All images have been uploaded to the GPU as textures and can be accessed with the corresponding private members `btex_*_*`.
-
- - **Notes**:
-
- N/A
-
+ - Description: Load all necessary images into textures.
+ - Preconditions: All images can be found in `path`, and they all have the correct format.
+ - Postconditions: All images have been uploaded to the GPU as textures and can be accessed with the corresponding private members `btex_*_*`.
+ - Notes:
- **`void load_image_to_texture_(const std::string file, GLuint& texture)`**
-
- - **Description**:
-
- Load an image (rgba) from file into an OpenGL texture using stbi.
-
- - **Preconditions**:
-
- The target image has format RGBA
-
- - **Postconditions**:
-
- The image has been uploaded to the GPU as a texture, and its handle has been copied into the address specified by `texture`
-
- - **Notes**:
-
-
+ - Description: Load an image (rgba) from file into an OpenGL texture using stbi.
+ - Preconditions: The target image has format RGBA
+ - Postconditions: The image has been uploaded to the GPU as a texture, and its handle has been copied into the address specified by `texture`
+ - Notes:
**Public Data Members**
--
GitLab