From 33daa484e9bdb9329bcf8cc531bf4cb06ce86526 Mon Sep 17 00:00:00 2001 From: Miloslav Ciz Date: Wed, 8 Jan 2025 22:05:54 +0100 Subject: [PATCH] Add some comments --- game.h | 75 +++++++++++++++++++++++++++++++----------------------- racing.h | 5 +++- renderer.h | 57 ++++++++++++++++++++++++++++++++++------- 3 files changed, 95 insertions(+), 42 deletions(-) diff --git a/game.h b/game.h index e596a26..9c54624 100644 --- a/game.h +++ b/game.h @@ -147,8 +147,6 @@ uint8_t LCR_gameGetNextAudioSample(void); //------------------------------------------------------------------------------ -#include "settings.h" - #define LCR_LOG0(s) ; #define LCR_LOG1(s) ; #define LCR_LOG2(s) ; @@ -180,6 +178,30 @@ uint8_t LCR_gameGetNextAudioSample(void); #define LCR_GAME_STATE_LOADING_MAP 0x04 #define LCR_GAME_STATE_END 0xff +// forward decls of pixel drawing functions for the renderer + +/** + Internal pixel drawing function that draws pixel at specified screen coords + without checking for safety (it's faster but can only be done if we know for + sure we're not drawing outside the screen). +*/ +void LCR_drawPixelXYUnsafe(unsigned int x, unsigned int y, uint16_t color); + +/** + Internal pixel drawing function that checks for out-of-screen coordinates. Use + this if the pixel can potentially lie of screen (however if you know it won't, + use the normal unsafe function in sake of performance). +*/ +static inline void LCR_drawPixelXYSafe(unsigned int x, unsigned int y, + uint_fast16_t color); + +#include "constants.h" +#include "racing.h" +#include "settings.h" +#include "audio.h" +#include "assets.h" +#include "renderer.h" + struct { uint8_t state; @@ -225,22 +247,6 @@ uint8_t LCR_gameMusicOn(void) #endif } -void LCR_drawPixelXYUnsafe(unsigned int x, unsigned int y, - uint16_t color); - -/** - Internal pixel drawing function that checks for out-of-screen coordinates. Use - this if the pixel can potentially lie of screen (however if you know it won't, - use the normal unsafe function in sake of performance). -*/ -static inline void LCR_drawPixelXYSafe(unsigned int x, unsigned int y, - uint_fast16_t color); - -#include "racing.h" -#include "assets.h" -#include "renderer.h" -#include "audio.h" - void LCR_drawPixelXYUnsafe(unsigned int x, unsigned int y, uint16_t color) { @@ -287,6 +293,9 @@ void LCR_gameResetRun(void) LCR_game.runTimeMS = 0; } +/** + Rewinds the global resource reading head to the beginning. +*/ void LCR_gameRewindResourceFile(void) { LCR_appendResourceStr(""); @@ -294,10 +303,10 @@ void LCR_gameRewindResourceFile(void) } /** - Reads the next resource file character while merging the internal resource - file with the optional user file. First the internal file will be read, - immediately followed by the user file, then zero char will return and - reading will start over. + Reads the next global resource file character (merged internal resource file + with the optional user file). First the internal file will be read, + immediately followed by the user file, then zero char will be returned and + then reading starts over. */ char LCR_gameGetNextResourceFileChar(void) { @@ -337,7 +346,7 @@ char LCR_gameGetNextResourceFileChar(void) /** Similar to LCR_gameGetNextResourceFileChar, but returns 0 instead of the - resource string separator character. This function is means to be used by + resource string separator character. This function is meant to be used by functions that load something from a string while expecting a zero terminated string. */ @@ -453,8 +462,7 @@ void LCR_gameInit(void) /** Loads up to LCR_RESOURCE_ITEM_CHUNK items of given type, starting at given - index (among items of the same type). This will also load the menu item - names. + index (among items of the same type). This will also load the menu item names. */ void LCR_gameLoadResourceFileChunk(unsigned int startIndex, char magicNumber) { @@ -499,8 +507,7 @@ void LCR_gameLoadResourceFileChunk(unsigned int startIndex, char magicNumber) } else if (i == 1 && state != 255) { - if ( - c == LCR_RESOURCE_FILE_SEPARATOR || + if (c == LCR_RESOURCE_FILE_SEPARATOR || c == LCR_RESOURCE_FILE_SEPARATOR2 || state >= 1 + LCR_MENU_STRING_SIZE - 1) { @@ -622,6 +629,10 @@ void LCR_gameDraw3DView(void) } } +/** + Helper subroutine, handles user input during main loop frame, EXCEPT for the + driving input (that is handled in the loop itself). +*/ void LCR_gameHandleInput(void) { int tabSwitchedTo = -1; @@ -812,11 +823,10 @@ void LCR_gameHandleInput(void) uint8_t LCR_gameStep(uint32_t time) { uint32_t sleep = 0; - int paused = - LCR_game.state == LCR_GAME_STATE_MENU || + int paused = LCR_game.state == LCR_GAME_STATE_MENU || LCR_game.state == LCR_GAME_STATE_RUN_STARTING; - LCR_LOG2("game step start"); + LCR_LOG2("game step (start)"); LCR_game.time = time; @@ -876,6 +886,7 @@ uint8_t LCR_gameStep(uint32_t time) } int engineIntensity = LCR_carSpeedKMH() * 2; + LCR_audioSetEngineIntensity(paused ? 0 : (engineIntensity < 256 ? engineIntensity : 255)); @@ -890,7 +901,7 @@ uint8_t LCR_gameStep(uint32_t time) // handle rendering: if (time >= LCR_game.nextRenderFrameTime) { - LCR_LOG2("gonna render next frame"); + LCR_LOG2("rendering next frame"); while (time >= LCR_game.nextRenderFrameTime) LCR_game.nextRenderFrameTime += 1000 / LCR_SETTING_FPS; @@ -935,7 +946,7 @@ uint8_t LCR_gameStep(uint32_t time) } LCR_game.frame++; - LCR_LOG2("game step end"); + LCR_LOG2("game step (end)"); return LCR_game.state != LCR_GAME_STATE_END; } diff --git a/racing.h b/racing.h index 842ce39..5057d44 100644 --- a/racing.h +++ b/racing.h @@ -730,7 +730,7 @@ void _LCR_drawPhysicsDebugPixel(uint16_t x, uint16_t y, uint8_t color) for (int j = -1; j <= 2; ++j) for (int i = -1; i <= 2; ++i) - LCR_drawPixelXYUnsafe(x + i,y + j,c); + LCR_drawPixelXYUnsafe(x + i,y + j,c); // TODO: should be separated, make this independent of game module } } @@ -1209,6 +1209,9 @@ uint32_t LCR_racingStep(unsigned int input) return result; } +/** + Draws a simple 3D debug overlap of the physics world. +*/ void LCR_physicsDebugDraw(LCR_GameUnit camPos[3], LCR_GameUnit camRot[2], LCR_GameUnit camFov) { diff --git a/renderer.h b/renderer.h index e1d2813..a945356 100644 --- a/renderer.h +++ b/renderer.h @@ -1,5 +1,15 @@ /** - 3D renderer: implements 3D rendering. + Renderer: implements 3D and 2D rendering. + + Some comments: + + - The map 3D model is divided into 4x4x4 chunks, i.e. 64 in total, out of + which only 8 are loaded at any time, depending on where the camera is and + where it is looking. This is to save resources, we don't draw the far away + chunks or those behind the camera. + - Extremely simple LOD of far away chunks is implemented: we keep an 8x8x8 + bit map of where there is empty space and where there is "something", then + for far away areas with "something" we just draw some 2D rectangles. */ #ifndef _LCR_RENDERER_H @@ -49,10 +59,10 @@ struct { - S3L_Scene scene; - S3L_Model3D mapModel; ///< whole map model - S3L_Model3D *carModel; - S3L_Model3D *ghostModel; + S3L_Scene scene; ///< Whole 3D scene. + S3L_Model3D mapModel; ///< Whole map model. + S3L_Model3D *carModel; ///< Shortcut pointer to the car model in scene. + S3L_Model3D *ghostModel; ///< Shortcut pointer to the ghost model in scene. /** The scene model array. @@ -199,6 +209,11 @@ void LCR_rendererDrawText(const char *text, int x, int y, uint16_t color, } } +/** + Used as a fragment shader by small3dlib. This function will be called for + every rasterized 3D pixel, we use it write actual pixels to the screen with + shading, texturing etc. +*/ void _LCR_pixelFunc3D(S3L_PixelInfo *pixel) { #if LCR_SETTING_POTATO_GRAPHICS @@ -726,6 +741,11 @@ void _LCR_cullHiddenMapTris(void) } } +/** + Rearranges map triangles so that they're grouped by chunks. Order of triangles + doesn't matter much in rendering, so we exploit this to use order for + chunking. +*/ void _LCR_makeMapChunks(void) { LCR_LOG1("making map chunks"); @@ -928,6 +948,10 @@ uint8_t _LCR_buildMapModel(void) return 1; } +/** + Computes the binary 3D grid of simple LODs (these just say whether in given + area is "something" or not) for currently loaded map. +*/ void _LCR_rendererComputeLOD(void) { LCR_LOG1("computing LOD"); @@ -993,6 +1017,10 @@ void LCR_rendererMarkTakenCP(int x, int y, int z) } } +/** + Creates everything that's needed to start rendering the currently loaded map, + returns success (1 or 0). +*/ uint8_t LCR_rendererLoadMap(void) { LCR_LOG0("loading map"); @@ -1203,8 +1231,14 @@ void LCR_rendererDrawRect(int x, int y, unsigned int w, unsigned int h, } } -void _LCR_rendererDrawLODBlock(int blockX, int blockY, int blockZ, unsigned int size, - uint16_t color, uint8_t variability) +/** + Draws a very simple LOD block (just a few 2D rectangles) meant to represent + far away geometry. The size parameter says base size in pixels (will be + affected by perspective), variability is used to create slightly different + shapes of blocks. +*/ +void _LCR_rendererDrawLODBlock(int blockX, int blockY, int blockZ, + unsigned int size, uint16_t color, uint8_t variability) { LCR_LOG2("drawing LOD block"); @@ -1381,6 +1415,11 @@ void LCR_rendererDrawSky(int sky, S3L_Unit offsetH, S3L_Unit offsetV) #endif } +/** + Loads a map chunk at chunk coords into given scene model. The chunk param says + into which model to load the chunk (0 to 7), the x, y and z params are the + coordinates (may even be outside the map). +*/ void _LCR_rendererLoadMapChunk(uint8_t chunk, int8_t x, int8_t y, int8_t z) { LCR_renderer.models[chunk] = LCR_renderer.mapModel; @@ -1443,8 +1482,8 @@ S3L_Unit _LCR_rendererSmoothRot(S3L_Unit angleOld, S3L_Unit angleNew, } /** - Loads the map models with 8 chunks that are nearest to a certain point - towards which the camera is looking. + Loads the map models with 8 chunks that are nearest to a certain point towards + which the camera is looking. */ void _LCR_rendererLoadMapChunks(void) {