readme & comments/cleanup

Author: SirJosh3917

README.md

@@ -0,0 +1,76 @@
+# Sorting Visualizer [![Nightly Build](https://github.com/SirJosh3917/SortingVisualizer/workflows/Nightly%20Build/badge.svg)](https://github.com/SirJosh3917/SortingVisualizer/actions)
+
+<p align=center>
+    <img src="./assets/sorting.gif"/>
+</p>
+
+This sorting visualizer was a simple project to introduce myself to
+
+- How a modern C++ project is architected
+- How to use CMake
+- How to organize a project
+- How to setup CI/CD for a C++ project
+- How to write C++20 code
+
+and it was a successful learning project. Overall, the take-away feeling I have from this project is that Rust is just C++, but if designed properly without baggage.
+
+## Download
+
+To download, please [download the build artifacts from the latest CI/CD run](https://github.com/SirJosh3917/SortingVisualizer/actions). After clicking the name of the latest run, scroll down and you should see an "Artifacts" section.
+
+## About
+
+This project, which is primarily a learning experiment to figure out the proper way to structure a C++ program, can hopefully be used to help others design and structure their own C++ SFML projects. As such, this project tries to be as simple as possible in that regard so that the reader can understand the concepts and introduce their own abstractions or bloat around the core process.
+
+- This project is written in C++ 20. [SFML](https://www.sfml-dev.org/) was chosen to create the sorting display with.
+
+- The resulting binary is statically linked to SFML so that there is no need for the user to install it, and on Windows builds, the standard C++ library is statically linked to as well so that users do not have to install the VC++ runtime.
+
+- A `.clang-format` file, and the accompanying [Clang-Format VSCode extension](https://marketplace.visualstudio.com/items?itemName=xaver.clang-format) is used to ensure style consistency across the codebase.
+
+- CMake is used to automatically generate and build the project for each platform.
+
+- Github Actions is used to build and create artifacts of the program on every new commit.
+
+## Building
+
+Because this project statically links SFML, SFML needs to be built from source with static linking in mind. Please [check out the Github Actions file](https://github.com/SirJosh3917/SortingVisualizer/blob/main/.github/workflows/nightly_build.yml) for the most up-to-date steps to build the project.
+
+1. Install SFML dependencies
+
+On Ubuntu flavors of Linux, this involves installing `libxcursor-dev mesa-common-dev libfreetype6-dev libxrandr-dev libudev-dev libogg-dev libflac-dev libvorbis-dev libopenal-dev`.
+
+No dependencies are needed on Windows.
+
+2. Build SFML from source
+
+Clone the SFML github repository, enable flags for static linking, and build. On Linux, build with the `-DBUILD_SHARED_LIBS=FALSE` flag only to statically link SFML. On Windows, build with the `-DSFML_USE_STATIC_STD_LIBS=TRUE -DBUILD_SHARED_LIBS=FALSE` flags to statically link SFML and the VC++ runtime.
+
+```bash
+# Linux
+git clone https://github.com/SFML/SFML --depth 1
+pushd SFML
+  cmake -B build -DBUILD_SHARED_LIBS=FALSE
+  cmake --build build --config Release
+  sudo cmake --install build --config Release
+popd
+
+# Windows
+git clone https://github.com/SFML/SFML --depth 1
+pushd SFML
+  cmake -B build -DSFML_USE_STATIC_STD_LIBS=TRUE -DBUILD_SHARED_LIBS=FALSE
+  cmake --build build --config Release
+  cmake --install build --config Release
+popd
+rm -Recurse -Force SFML
+```
+
+3. Build Sorting Visualizer
+
+Finally, use CMake to build Sorting Visualizer. Make sure you've ran `cmake --install` when building SFML in the previous step, otherwise it won't be installed in your path.
+
+```shell
+cmake -B build
+cmake --build build --config Release
+cmake --install build --config Release
+```

assets/sorting.gif

@@ -1,4 +1,7 @@
 #pragma once
 #include <SortingVisualizer/Collection.hpp>
 
+/**
+ * Performs bubble sort.
+ */
 const void bubbleSort(Collection &collection);

include/SortingVisualizer/Algorithms/BubbleSort.hpp

@@ -1,4 +1,7 @@
 #pragma once
 #include <SortingVisualizer/Collection.hpp>
 
+/**
+ * Performs Quicksort. As an implementation detail, it uses Hoare's partitioning algorithm.
+ */
 const void quickSort(Collection &collection, int64_t low = 0, int64_t high = -1);

include/SortingVisualizer/Algorithms/QuickSort.hpp

@@ -3,10 +3,16 @@
 #include <stdint.h>
 #include <vector>
 
+/**
+ * Representation of a bar - it has a value, and a color.
+ */
 struct Bar
 {
 	uint64_t value;
 	sf::Color color;
 };
 
+/**
+ * Converts a series of values into a series of bars.
+ */
 std::vector<Bar> toBars(std::vector<uint64_t> values);

include/SortingVisualizer/Bar.hpp

@@ -12,12 +12,18 @@ enum class Order
 	EQUAL
 };
 
+/**
+ * Metadata that tracks when a comparison was made.
+ */
 struct Comparison
 {
 	std::size_t leftIdx;
 	std::size_t rightIdx;
 };
 
+/**
+ * Metadata that tracks when a swap was performed.
+ */
 struct Swap
 {
 	std::size_t leftIdx;
@@ -28,12 +34,22 @@ struct Swap
 using SingleDecision = std::variant<Comparison, Swap>;
 using Decision = std::variant<SingleDecision, std::vector<SingleDecision>>;
 
+/**
+ * Some weird class that allows the parallel sorting magic crud or something,,,
+ */
 class InternalDecisions
 {
 public:
 	std::vector<std::variant<SingleDecision, std::vector<InternalDecisions>>> decisions;
 };
 
+/**
+ * A class that encapsulates its contents, and exists as a container to
+ *
+ * - Abstractly perform operations, such as comparing and swapping
+ * - Record the performed operations to play back later
+ * - Will play back the performed operation with the maximum amount of requested parallelism
+ */
 class Collection
 {
 private:

include/SortingVisualizer/Collection.hpp

@@ -6,6 +6,10 @@
 #include <memory>
 #include <stdint.h>
 
+/**
+ * Class that contains bars, and can draw the bars. It also allows setting the bars from another thread, so that
+ * the sorting and drawing are independent of one another.
+ */
 class Display
 {
 private:

include/SortingVisualizer/Display.hpp

@@ -2,6 +2,7 @@
 
 const std::size_t hoarePartition(Collection &collection, int64_t low, int64_t high)
 {
+	// why, yes i just copied this code from the internet - how could you tell?
 	auto pivot = low;
 	auto left = low - 1;
 	auto right = high + 1;
@@ -29,13 +30,12 @@ const std::size_t hoarePartition(Collection &collection, int64_t low, int64_t hi
 	return right;
 }
 
-const void w(Collection &c) {}
-
 const void quickSort(Collection &collection, int64_t low, int64_t high)
 {
 	if (high == -1) high = collection.length() - 1;
 	if (low >= high) return;
 
+	// don't yell at me for the formatting i'm too lazy to configure clang-tidy
 	auto pivot = hoarePartition(collection, low, high);
 	collection.doParallel(
 		{[low, pivot](Collection &c) { quickSort(c, low, pivot); }, [pivot, high](Collection &c) { quickSort(c, pivot + 1, high); }});

src/SortingVisualizer/Algorithms/QuickSort.cpp

@@ -11,6 +11,20 @@ const uint64_t Collection::max() const { return *std::max_element(this->values.b
 
 std::vector<uint64_t> Collection::contents() const { return this->values; }
 
+////////////////////
+// TODO: CLEAN UP //
+////////////////////
+//
+// see, the joke is that i call it a "TODO" but don't plan to ever do it
+// and holy hell is this a god-class of a method
+//
+// see i could explain so much and clean up so much code but it's just way easier if i
+// just, y'know
+// ...
+// didn't :)
+//
+// have fun!
+
 std::vector<Decision> Collection::getDecisions(const std::size_t parallelWorkers) const
 {
 	std::vector<Decision> resultantDecisions;
@@ -146,7 +160,7 @@ void Collection::followThroughDecision(const SingleDecision &decision)
 	}
 	else
 	{
-		// other is a comparison we don't care about
+		// if the decision is a comparison, we don't have any bar state to update
 	}
 }
 

src/SortingVisualizer/Collection.cpp

@@ -1,5 +1,4 @@
 #include <SFML/Graphics.hpp>
-// #include <SortingVisualizer/Algorithms/BubbleSort.hpp>
 #include <SortingVisualizer/Algorithms/QuickSort.hpp>
 #include <SortingVisualizer/Bar.hpp>
 #include <SortingVisualizer/Collection.hpp>
@@ -12,6 +11,15 @@
 #include <thread>
 #include <tuple>
 
+////////////////////
+// TODO: CLEAN UP //
+////////////////////
+//
+// see, the joke is that i call it a "TODO" but don't plan to ever do it
+// as a sidenote i made comments every so often so it's obvious what should be put into a function if i ever decide to not feel lazy
+// (narrator: he never did)
+
+// helper method for sorter below
 void handleSingleDecision(SingleDecision &decision, std::vector<Bar> &bars, std::vector<std::size_t> &coloredBars)
 {
 	if (std::holds_alternative<Swap>(decision))
@@ -36,8 +44,10 @@ void handleSingleDecision(SingleDecision &decision, std::vector<Bar> &bars, std:
 	}
 }
 
+// worker on a separate thread that will update the display's bars
 void sorter(std::tuple<Collection *, Display *> container)
 {
+	// boiler plate of container -> collection & display
 	auto collectionPtr = std::get<0>(container);
 	auto displayPtr = std::get<1>(container);
 
@@ -47,13 +57,16 @@ void sorter(std::tuple<Collection *, Display *> container)
 	auto collection = *collectionPtr;
 	auto display = *displayPtr;
 
+	// sort the collection
 	auto bars = toBars(collection.contents());
 	quickSort(collection);
 
+	// display the sorting
 	for (auto &decision : collection.getDecisions(1000))
 	{
 		std::vector<std::size_t> coloredBars;
 
+		// change colors of bars, and add them to coloredBars to change them back later
 		if (std::holds_alternative<std::vector<SingleDecision>>(decision))
 		{
 			auto decisions = std::get<std::vector<SingleDecision>>(decision);
@@ -88,14 +101,15 @@ int main()
 	// seed RNG
 	std::srand(std::time(0));
 
+	// setup window
 	sf::ContextSettings settings;
 	settings.antialiasingLevel = 4;
 	settings.majorVersion = 3;
 
 	auto window = sf::RenderWindow(sf::VideoMode(800, 600), "Sorting Visualizer", sf::Style::Default, settings);
 	window.setVerticalSyncEnabled(true);
-	window.setFramerateLimit(60);
 
+	// setup collection of values
 	std::vector<uint64_t> values;
 	auto len = 100;
 	for (auto i = 1; i <= len; ++i)
@@ -105,13 +119,14 @@ int main()
 	std::shuffle(values.begin(), values.end(), std::mt19937(std::random_device()()));
 	auto collection = Collection(values);
 
+	// setup display
 	auto display = Display(window, collection);
 
-	auto dirty = true;
-
+	// launch sorter on another thread
 	sf::Thread sortAlgo(&sorter, std::make_tuple<Collection *, Display *>(&collection, &display));
 	sortAlgo.launch();
 
+	// event loop thing
 	while (window.isOpen())
 	{
 		sf::Event event;
@@ -122,17 +137,15 @@ int main()
 				// SFML views are useful in games, but for me, i'd prefer if i was dealing with everything
 				// as if it were regular window coordinates
 				window.setView(sf::View(sf::FloatRect(0.0f, 0.0f, event.size.width, event.size.height)));
-
-				// we modified the view, we want to guarantee a re-render
-				dirty = true;
 			}
 			else if (event.type == sf::Event::LostFocus)
 			{
+				// no reason to update the window at 60+fps if it's not in focus
 				window.setFramerateLimit(12);
 			}
 			else if (event.type == sf::Event::GainedFocus)
 			{
-				window.setFramerateLimit(60);
+				window.setFramerateLimit(0);
 			}
 			else if (event.type == sf::Event::Closed)
 			{