diff --git a/src/picovga.h b/src/picovga.h index 98197a3..61a4399 100644 --- a/src/picovga.h +++ b/src/picovga.h @@ -4,10 +4,6 @@ * @author Miroslav Nemecek */ -// ---------------------------------------------------------------------------- -// Base data types -// ---------------------------------------------------------------------------- - #ifndef _PICOVGA_H #define _PICOVGA_H @@ -20,7 +16,15 @@ /// @defgroup OverclockGroup CPU Overclocking /// @defgroup TextGroup Text Printing /// @defgroup PWMGroup PWM Audio +/// @defgroup RandomGroup Random Number Generator /// @defgroup Core1Group Second Core +/// @defgroup UtilsGroup Utility Functions +/// @defgroup TypesGroup Base types and Constants + +/** + * @addtogroup TypesGroup + * @{ +*/ typedef signed char s8; typedef unsigned char u8; @@ -109,6 +113,8 @@ typedef unsigned char Bool; #define PI 3.14159265358979324 #define PI2 (3.14159265358979324*2) +/// @} + // ---------------------------------------------------------------------------- // Includes // ---------------------------------------------------------------------------- diff --git a/src/util/pwmsnd.h b/src/util/pwmsnd.h index 90fdeac..5909e54 100644 --- a/src/util/pwmsnd.h +++ b/src/util/pwmsnd.h @@ -5,12 +5,6 @@ * @see PWMGroup */ -// **************************************************************************** -// -// PWM sound output -// -// **************************************************************************** - #ifndef _PWMSND_H #define _PWMSND_H diff --git a/src/util/rand.h b/src/util/rand.h index 93155dd..a7e2a0e 100644 --- a/src/util/rand.h +++ b/src/util/rand.h @@ -1,14 +1,25 @@ - -// **************************************************************************** -// -// Random number generator -// -// **************************************************************************** +/** + * @file + * @brief Random number generator + * @author Miroslav Nemecek + * @see RandomGroup +*/ #ifndef _RAND_H #define _RAND_H -// Random Generator +/** + * @addtogroup RandomGroup + * @details The cRandom library replaces and extends the standard random number generator. A 64-bit number is used as seed, + * which ensures sufficient randomness of the number. The limited randomness of the standard 32-bit generator can be observed, + * for example, when generating terrain - it will appear as waves in the terrain. You can either use the global variable Rand + * and the functions belonging to it, or create another local generator cRandom. The following functions refer to the global + * Rand generator. It is recommended to use the RandInitSeed() function when starting the program to ensure the generator is + * non-repeating. + * @{ +*/ + +/// Random Generator class cRandom { private: @@ -18,66 +29,76 @@ private: public: - // shift random generator seed + /// Shift random generator seed inline void Shift() { m_Seed = m_Seed*214013 + 2531011; } - // get/set random generator seed + /// Get random number seed inline u64 Seed() const { return m_Seed; } + + /// Set random number seed inline void SetSeed(u64 seed) { m_Seed = seed; } - // Set random seed from ROSC counter + /// Set random seed from ROSC counter void InitSeed(); - // generate integer random number in full range - u8 U8(); - u16 U16(); - u32 U32(); - u64 U64(); + u8 U8(); ///< Generate integer random number in full range + u16 U16(); ///< Generate integer random number in full range + u32 U32(); ///< Generate integer random number in full range + u64 U64(); ///< Generate integer random number in full range - inline s8 S8() { return (s8)this->U8(); } - inline s16 S16() { return (s16)this->U16(); } - inline s32 S32() { return (s32)this->U32(); } - inline s64 S64() { return (s64)this->U64(); } + inline s8 S8() { return (s8)this->U8(); } ///< Generate integer random number in full range + inline s16 S16() { return (s16)this->U16(); } ///< Generate integer random number in full range + inline s32 S32() { return (s32)this->U32(); } ///< Generate integer random number in full range + inline s64 S64() { return (s64)this->U64(); } ///< Generate integer random number in full range - // generate float random number in range 0 (including) to 1 (excluding) + /// Generate float random number in range 0 (including) to 1 (excluding) float Float(); - // generate double random number in range 0 (including) to 1 (excluding) + /// Generate double random number in range 0 (including) to 1 (excluding) double Double(); - // generate random number in range 0 to MAX (including) - u8 U8Max(u8 max); - u16 U16Max(u16 max); - u32 U32Max(u32 max); - u64 U64Max(u64 max); + + u8 U8Max(u8 max); ///< Generate random number in range 0 to MAX (including) + u16 U16Max(u16 max); ///< Generate random number in range 0 to MAX (including) + u32 U32Max(u32 max); ///< Generate random number in range 0 to MAX (including) + u64 U64Max(u64 max); ///< Generate random number in range 0 to MAX (including) - s8 S8Max(s8 max); - s16 S16Max(s16 max); - s32 S32Max(s32 max); - s64 S64Max(s64 max); + s8 S8Max(s8 max); ///< Generate random number in range 0 to MAX (including) + s16 S16Max(s16 max); ///< Generate random number in range 0 to MAX (including) + s32 S32Max(s32 max); ///< Generate random number in range 0 to MAX (including) + s64 S64Max(s64 max); ///< gGenerate random number in range 0 to MAX (including) - // generate decimal random number in range 0 (including) to MAX (excluding) + /// Generate decimal random number in range 0 (including) to MAX (excluding) float FloatMax(float max); + /// Generate decimal random number in range 0 (including) to MAX (excluding) double DoubleMax(double max); - // generate random number in range MIN to MAX (including) - // If MIN > MAX, then number is generated out of interval. + /// Generate random number in range MIN to MAX (including). If MIN > MAX, then number is generated out of interval. u8 U8MinMax(u8 min, u8 max); + /// Generate random number in range MIN to MAX (including). If MIN > MAX, then number is generated out of interval. u16 U16MinMax(u16 min, u16 max); + /// Generate random number in range MIN to MAX (including). If MIN > MAX, then number is generated out of interval. u32 U32MinMax(u32 min, u32 max); + /// Generate random number in range MIN to MAX (including). If MIN > MAX, then number is generated out of interval. u64 U64MinMax(u64 min, u64 max); + /// Generate random number in range MIN to MAX (including). If MIN > MAX, then number is generated out of interval. s8 S8MinMax(s8 min, s8 max); + /// Generate random number in range MIN to MAX (including). If MIN > MAX, then number is generated out of interval. s16 S16MinMax(s16 min, s16 max); + /// Generate random number in range MIN to MAX (including). If MIN > MAX, then number is generated out of interval. s32 S32MinMax(s32 min, s32 max); + /// Generate random number in range MIN to MAX (including). If MIN > MAX, then number is generated out of interval. s64 S64MinMax(s64 min, s64 max); + /// Generate random number in range MIN to MAX (including). If MIN > MAX, then number is generated out of interval. float FloatMinMax(float min, float max); + /// Generate random number in range MIN to MAX (including). If MIN > MAX, then number is generated out of interval. double DoubleMinMax(double min, double max); }; -// Gaussian random float number generator +/// Gaussian random float number generator class cGaussFRandom { private: @@ -91,19 +112,20 @@ private: public: - // get/set random generator seed and initialize generator + /// Get random number seed inline u64 Seed() const { return m_Rand.Seed(); } + /// Set random number seed inline void SetSeed(u64 seed) { m_Rand.SetSeed(seed); m_CacheOK = False; } - // generate Gaussian random number (mean = center, sigma = width) + /// Generate Gaussian random number (mean = center, sigma = width) float Gauss(float mean = 0, float sigma = 1); }; -// Gaussian random double number generator +/// Gaussian random double number generator class cGaussDRandom { private: @@ -117,95 +139,123 @@ private: public: - // get/set random generator seed and initialize generator + /// Get random number seed inline u64 Seed() const { return m_Rand.Seed(); } + /// Set random number seed inline void SetSeed(u64 seed) { m_Rand.SetSeed(seed); m_CacheOK = False; } - // generate Gaussian random number (mean = center, sigma = width) + /// Generate Gaussian random number (mean = center, sigma = width) double Gauss(double mean = 0, double sigma = 1); }; -// global random generator +/// Global random generator extern cRandom Rand; -// global Gaussian random float number generator +/// Global Gaussian random float number generator extern cGaussFRandom GaussFRand; -// global Gaussian random double number generator +/// Global Gaussian random double number generator extern cGaussDRandom GaussDRand; -// random generator seed +/// Get random generator seed inline u64 RandSeed() { return Rand.Seed(); } +/// Set random generator seed inline void RandSetSeed(u64 seed) { Rand.SetSeed(seed); } -// Set random seed from ROSC counter +/// Set random seed from ROSC counter inline void RandInitSeed() { Rand.InitSeed(); } -// generate integer random number in full range +/// Generate integer random number in full range inline u8 RandU8() { return Rand.U8(); } +/// Generate integer random number in full range inline u16 RandU16() { return Rand.U16(); } +/// Generate integer random number in full range inline u32 RandU32() { return Rand.U32(); } +/// Generate integer random number in full range inline u64 RandU64() { return Rand.U64(); } +/// Generate integer random number in full range inline s8 RandS8() { return Rand.S8(); } +/// Generate integer random number in full range inline s16 RandS16() { return Rand.S16(); } +/// Generate integer random number in full range inline s32 RandS32() { return Rand.S32(); } +/// Generate integer random number in full range inline s64 RandS64() { return Rand.S64(); } -// generate float random number in range 0 (including) to 1 (excluding) +/// Generate float random number in range 0 (including) to 1 (excluding) inline float RandFloat() { return Rand.Float(); } -// generate double random number in range 0 (including) to 1 (excluding) +/// Generate double random number in range 0 (including) to 1 (excluding) inline double RandDouble() { return Rand.Double(); } -// generate random number in range 0 to MAX (including) +/// Generate random number in range 0 to MAX (including) inline u8 RandU8Max(u8 max) { return Rand.U8Max(max); } +/// Generate random number in range 0 to MAX (including) inline u16 RandU16Max(u16 max) { return Rand.U16Max(max); } +/// Generate random number in range 0 to MAX (including) inline u32 RandU32Max(u32 max) { return Rand.U32Max(max); } +/// Generate random number in range 0 to MAX (including) inline u64 RandU64Max(u64 max) { return Rand.U64Max(max); } +/// Generate random number in range 0 to MAX (including) inline s8 RandS8Max(s8 max) { return Rand.S8Max(max); } +/// Generate random number in range 0 to MAX (including) inline s16 RandS16Max(s16 max) { return Rand.S16Max(max); } +/// Generate random number in range 0 to MAX (including) inline s32 RandS32Max(s32 max) { return Rand.S32Max(max); } +/// Generate random number in range 0 to MAX (including) inline s64 RandS64Max(s64 max) { return Rand.S64Max(max); } -// generate decimal random number in range 0 (including) to MAX (excluding) +/// Generate decimal random number in range 0 (including) to MAX (excluding) inline float RandFloatMax(float max) { return Rand.FloatMax(max); } +/// Generate decimal random number in range 0 (including) to MAX (excluding) inline double RandDoubleMax(double max) { return Rand.DoubleMax(max); } -// generate random number in range MIN to MAX (including) -// If MIN > MAX, then number is generated out of interval. +/// Generate random number in range MIN to MAX (including). If MIN > MAX, then number is generated out of interval. inline u8 RandU8MinMax(u8 min, u8 max) { return Rand.U8MinMax(min, max); } +/// Generate random number in range MIN to MAX (including). If MIN > MAX, then number is generated out of interval. inline u16 RandU16MinMax(u16 min, u16 max) { return Rand.U16MinMax(min, max); } +/// Generate random number in range MIN to MAX (including). If MIN > MAX, then number is generated out of interval. inline u32 RandU32MinMax(u32 min, u32 max) { return Rand.U32MinMax(min, max); } +/// Generate random number in range MIN to MAX (including). If MIN > MAX, then number is generated out of interval. inline u64 RandU64MinMax(u64 min, u64 max) { return Rand.U64MinMax(min, max); } +/// Generate random number in range MIN to MAX (including). If MIN > MAX, then number is generated out of interval. inline s8 RandS8MinMax(s8 min, s8 max) { return Rand.S8MinMax(min, max); } +/// Generate random number in range MIN to MAX (including). If MIN > MAX, then number is generated out of interval. inline s16 RandS16MinMax(s16 min, s16 max) { return Rand.S16MinMax(min, max); } +/// Generate random number in range MIN to MAX (including). If MIN > MAX, then number is generated out of interval. inline s32 RandS32MinMax(s32 min, s32 max) { return Rand.S32MinMax(min, max); } +/// Generate random number in range MIN to MAX (including). If MIN > MAX, then number is generated out of interval. inline s64 RandS64MinMax(s64 min, s64 max) { return Rand.S64MinMax(min, max); } +/// Generate random number in range MIN to MAX (including). If MIN > MAX, then number is generated out of interval. inline float RandFloatMinMax(float min, float max) { return Rand.FloatMinMax(min, max); } +/// Generate random number in range MIN to MAX (including). If MIN > MAX, then number is generated out of interval. inline double RandDoubleMinMax(double min, double max) { return Rand.DoubleMinMax(min, max); } -// generate Gaussian random number (mean = center, sigma = width) +/// Generate Gaussian random number (mean = center, sigma = width) inline float RandGaussF(float mean = 0, float sigma = 1) { return GaussFRand.Gauss(mean, sigma); } +/// Generate Gaussian random number (mean = center, sigma = width) inline double RandGaussD(double mean = 0, double sigma = 1) { return GaussDRand.Gauss(mean, sigma); } -// 1D coordinate noise generator (output -1..+1) +/// 1D coordinate noise generator (output -1..+1) float Noise1D(int x, int seed); -// 2D coordinate noise generator (output -1..+1) +/// 2D coordinate noise generator (output -1..+1) float Noise2D(int x, int y, int seed); -// 3D coordinate noise generator (output -1..+1) +/// 3D coordinate noise generator (output -1..+1) float Noise3D(int x, int y, int z, int seed); -// interpolated 1D noise (output -1..+1, scale = 1...) +/// Interpolated 1D noise (output -1..+1, scale = 1...) float SmoothNoise1D(float x, int scale, int seed); -// interpolated 2D noise (output -1..+1, scale = 1...) +/// Interpolated 2D noise (output -1..+1, scale = 1...) float SmoothNoise2D(float x, float y, int scale, int seed); +/// @} + #endif // _RAND_H diff --git a/src/vga_util.h b/src/vga_util.h index 876485a..3401182 100644 --- a/src/vga_util.h +++ b/src/vga_util.h @@ -1,29 +1,71 @@ - -// **************************************************************************** -// -// VGA utilities -// -// **************************************************************************** +/** + * @file + * @brief VGA utilities + * @author Miroslav Nemecek + * @see VideoModeGroup +*/ #ifndef _VGA_UTIL_H #define _VGA_UTIL_H -// convert image from 16-color to 8x8 attribute format +/** + * @addtogroup UtilsGroup + * @brief Utility functions + * @{ +*/ + +/** + * @brief Convert image from 16-color to 8x8 attribute format + * @param dst Destination image + * @param attr Destination attribute data + * @param src Source image + * @param w Image width + * @param h Image height + * @param pal Palette +*/ void Attr8Conv(u8* dst, u8* attr, const u8* src, int w, int h, const u8* pal); -// convert image from 4-color to 2-plane format (width must be multiply of 8) +/** + * @brief Convert image from 4-color to 2-plane format (width must be multiply of 8) + * @param plane0 First plane destination + * @param plane1 Second plane destionation + * @param src Soure image + * @param w Image width + * @param h Image height +*/ void Plane2Conv(u8* plane0, u8* plane1, const u8* src, int w, int h); -// invert image +/** + * @brief Invert image + * @param dst Image data + * @param num Length of image in bytes +*/ void ImgInvert(u8* dst, int num); -// decode unsigned number into ASCIIZ text buffer (returns number of digits) +/** + * @brief Decode unsigned number into ASCIIZ text buffer + * @param buf Destination buffer + * @param num Number to decode + * @returns Number of digits +*/ int DecUNum(char* buf, u32 num); -// decode signed number into ASCIIZ text buffer (returns number of digits) +/** + * @brief Decode signed number into ASCIIZ text buffer + * @param buf Destination buffer + * @param num Number to decode + * @returns Number of digits +*/ int DecNum(char* buf, s32 num); -// prepare image with white key transparency (copy and increment pixels) +/** + * @brief Prepare image with white key transparency (copy and increment pixels) + * @param dst Destination image + * @param src Source image + * @param num Number of bytes to copy +*/ void CopyWhiteImg(u8* dst, const u8* src, int num); +/// @} + #endif // _VGA_UTIL_H