diff --git a/include/gp/iterator.hpp b/include/gp/iterator.hpp index 11cbeee..689e41e 100644 --- a/include/gp/iterator.hpp +++ b/include/gp/iterator.hpp @@ -4,6 +4,7 @@ #include // BUG: none of this is in a namespace +// TODO: Specify the concept of an iterator /** * @brief An enumeration that may be used to determine iterator categories diff --git a/include/gp/quotient_filter.hpp b/include/gp/quotient_filter.hpp index fbbb0b8..32feffc 100644 --- a/include/gp/quotient_filter.hpp +++ b/include/gp/quotient_filter.hpp @@ -11,7 +11,11 @@ namespace gp { + // TODO: Specify the concept of a skipstone + /** + * @brief An abstraction for exploring and picking in a list sequencially + */ struct linear_skipstone { constexpr static size_t ccbits = 1; constexpr static size_t cclast = 1; @@ -24,6 +28,9 @@ namespace gp { } }; + /** + * @brief An abstraction for exploring and picking in a list in a non sequencial but still relatively cache friendly way + */ struct stepcache_skipstone { constexpr static size_t ccbits = 7; constexpr static size_t cclast = 127; @@ -73,6 +80,15 @@ namespace gp { } }; + /** + * @brief A datastructure to accurately check belonging in a set in a probabilistic way. + * More precise than a bloomfilter, less space efficient, can allow deletion (handle with care) + * + * @tparam hash_type the type of hash storage type + * @tparam magnitude the size of the filter as a power of 2 + * @tparam remainder the number of bits of remainder of the quotient \f$\frac{h}{m}\f$ where \f$h\f$ is a hash and \f$m\f$ the magnitude of the set, can throw away bits + * @tparam skipstone_t the type of sequence exploration to perform + */ template class quotient_filter { constexpr static size_t phys_size = (1 << magnitude) / 32; diff --git a/include/gp/rendering/bmp_viewport.hpp b/include/gp/rendering/bmp_viewport.hpp index 82063ac..596e05d 100644 --- a/include/gp/rendering/bmp_viewport.hpp +++ b/include/gp/rendering/bmp_viewport.hpp @@ -10,6 +10,12 @@ #include namespace gp{ + /** + * @brief A bmp format viewport that can be used to generate and export bmp file contents + * + * @tparam lazy if true, will expect the source to be a function, else would expect it to be a buffer + * @tparam color_type the type that represents the color. as of now only gp::vec4_g is supported + */ template class bmp_viewport { public: diff --git a/include/gp/rendering/renderer.hpp b/include/gp/rendering/renderer.hpp index e43c0c3..d06fec4 100644 --- a/include/gp/rendering/renderer.hpp +++ b/include/gp/rendering/renderer.hpp @@ -33,6 +33,10 @@ struct render_point{ using sdf_t = gp::function; using material_t = gp::function; + +/** + * @brief A pure ray-marching renderer. Prints pixels on order. + */ class renderer { using g_t = gp_config::rendering::default_type; constexpr static auto epsilon = gp_config::rendering::epsilon; diff --git a/include/gp/variant.hpp b/include/gp/variant.hpp index 0d5b164..8dd123c 100644 --- a/include/gp/variant.hpp +++ b/include/gp/variant.hpp @@ -15,6 +15,11 @@ namespace gp{ + /** + * @brief A form of variant that expect only classes whose size is strictly defined at compile time + * + * @tparam T The list of types accepted by the variant + */ template class fixed_variant final { std::size_t index = std::numeric_limits::max(); @@ -29,6 +34,12 @@ namespace gp{ : fixed_variant(typename first_of::type{}) {} + /** + * @brief Construct a new fixed variant from an object that is legal in it + * + * @tparam U A type that belongs in the list of types the variant supports + * @param value The copied value + */ template,T...>::value,int> = 0> fixed_variant(U& value) : index{r_index_of, T...>::value} @@ -52,6 +63,12 @@ namespace gp{ static_assert(list_contains_class::value, "list_contains_class doesn't work properly"); static_assert(!list_contains_class::value, "list_contains_class doesn't work properly"); + /** + * @brief Construct a new fixed variant from an object that is legal in it by moving said object + * + * @tparam U A type that belongs in the list of types the variant supports + * @param value The moved value + */ template,T...>::value,int> = 0> fixed_variant(U&& value) : index{r_index_of, T...>::value} @@ -97,11 +114,24 @@ namespace gp{ mvtor(oth.buffer, buffer); } + /** + * @brief Gives an alternative (value usable in a switch statement) representing the given type + * + * @tparam U the type to match against + * @return constexpr size_t a value that can be used in the case part of a switch case statement + * @see type() + */ template constexpr static size_t alt() { return r_index_of::value; } + /** + * @brief Gives the type as can be matched in a switch statement using alternatives + * + * @return size_t a value that can be used in the switch part of a switch case statement + * @see alt() + */ size_t type() const { return index; } @@ -170,6 +200,13 @@ namespace gp{ } } + /** + * @brief Brutally decay the variant into the given type. + Will throw (@see bad_variant_access) if exceptions are enabled, else behaviour is undefined. + * + * @tparam U the type to decay towards + * @return constexpr U& a decayed reference to the variant + */ template constexpr U& value() { @@ -183,6 +220,13 @@ namespace gp{ return *reinterpret_cast(buffer); } + /** + * @brief Tests if the variant is of a particular type. + * + * @tparam U the type to match against + * @return true if the types match + * @return false if the types don't match + */ template constexpr bool is_a() { diff --git a/include/gp/vector.hpp b/include/gp/vector.hpp index b96dfa5..9aaeaa4 100644 --- a/include/gp/vector.hpp +++ b/include/gp/vector.hpp @@ -6,6 +6,12 @@ #include namespace gp{ + /** + * @brief A vector type most similar to that of the standard library + * Always uses polymorphic allocation, no small value optimization + * + * @tparam T + */ template class vector final { T* ary = nullptr; @@ -116,11 +122,26 @@ namespace gp{ } } + /** + * @brief Ensures the vector can hold at least 1 more element + * + * @return true if it is at least now possible to fit one more element + * @return false if fiting one more element is not possible even now + */ bool grow() { if(sz == cap) return reserve(1 + sz + (sz >> 1)); return true; } + /** + * @brief Reserves space so that the capacity is at least equal to the provided value. + * + * This will never shrink the datastructure + * + * @param new_cap the new capacity + * @return true on success + * @return false on failure + */ bool reserve(size_t new_cap) { if(new_cap <= cap) return true; @@ -147,6 +168,13 @@ namespace gp{ constexpr const T& operator[] (size_t off) const { + if constexpr (gp_config::has_buffer_bounds) + { + gp_config::assertion( + off < sz, + "Array bounds infringed" + ); + } return ary[off]; } @@ -160,6 +188,13 @@ namespace gp{ return cap; } + /** + * @brief Adds the provided value to the vector + * + * @param value + * @return true on success + * @return false on failure + */ constexpr bool push_back(T& value) { if(grow()) { new(ary+sz) T(value); @@ -169,6 +204,14 @@ namespace gp{ return false; } + + /** + * @brief Moves the provided value to the vector + * + * @param value + * @return true on success + * @return false on failure + */ constexpr bool push_back(T&& value) { if(grow()) { new(ary+sz) T(gp::move(value)); @@ -178,6 +221,13 @@ namespace gp{ return false; } + /** + * @brief Constructs a new element at the end of the vector + * + * @param value the parameters to be sent to the constructor of T + * @return true on success + * @return false on failure + */ template constexpr bool emplace_back(U&&... value) { if(grow()) { @@ -188,6 +238,11 @@ namespace gp{ return false; } + /** + * @brief moves the last element of the vector out if it exists, returning an optional. + * + * @return constexpr gp::optional contains a value if it existed, else it is empty + */ constexpr gp::optional pop_back() { if(sz == 0) return gp::nullopt; sz--; @@ -253,6 +308,12 @@ namespace gp{ return !(*this == oth); } + /** + * @brief Provides a span access to the vector + * + * @return A buffer of the vector. + * It is invalidated by any operation that may change the size of the vector. + */ gp::buffer as_buffer() { return gp::buffer{(T*)ary, (T*)ary+sz};