From e35349b418d7eeb553c20bec8a5a1a240e7becf2 Mon Sep 17 00:00:00 2001 From: Jon Thysell Date: Tue, 7 Dec 2021 11:07:28 -0800 Subject: [PATCH] Doxygen comments part 1 - headers --- src/Bitmaps.c | 19 +++++++- src/Bitmaps.h | 79 ++++++++++++++++++++++++++++++- src/Common.h | 18 +++++++ src/GameEndScene.h | 23 +++++++++ src/GameEngine.h | 103 +++++++++++++++++++++++++++++++++++++++++ src/GameWindow.h | 42 +++++++++++++++++ src/LevelEndScene.c | 2 +- src/LevelEndScene.h | 23 +++++++++ src/LevelSelectScene.c | 2 +- src/LevelSelectScene.h | 23 +++++++++ src/Levels.h | 20 ++++++++ src/MacCommon.c | 15 ------ src/MacCommon.h | 82 ++++++++++++++++++++++++++++++-- src/MacLO.h | 17 +++++++ src/PlayScene.c | 4 +- src/PlayScene.h | 23 +++++++++ src/Scenes.h | 16 ++++++- src/Sounds.h | 26 +++++++++++ src/TitleScene.c | 2 +- src/TitleScene.h | 23 +++++++++ src/WindowBuffer.h | 24 ++++++++++ src/stdbool.h | 7 +++ src/stdint.h | 55 +++++++++++++++++----- 23 files changed, 608 insertions(+), 40 deletions(-) diff --git a/src/Bitmaps.c b/src/Bitmaps.c index ed906a0..3a7a599 100644 --- a/src/Bitmaps.c +++ b/src/Bitmaps.c @@ -25,6 +25,21 @@ #define StarRectPadding 2 +const int16_t MonthOffset[] = { + 0, // Jan + 31, // Feb + 60, // Mar + 91, // Apr + 121, // May + 152, // Jun + 182, // Jul + 213, // Aug + 244, // Sep + 274, // Oct + 305, // Nov + 335, // Dec +}; + int16_t Bitmaps_GetOverrideBaseResID(); PicHandle Bitmaps_GetPict(const int16_t holidayResID, const int16_t offset); @@ -247,7 +262,7 @@ void Bitmaps_DrawSlashChar(const Bitmaps *pBitmaps, const uint8_t scale) DrawScaledPic(pBitmaps->SlashCharPict, scale); } -void Bitmaps_GetHalfStarsRect(const Bitmaps *pBitmaps, const uint8_t halfStars, const uint8_t maxStars, const uint8_t scale, Rect *pDestRect) +void Bitmaps_GetHalfStarsRect(const Bitmaps *pBitmaps, const uint8_t maxStars, const uint8_t scale, Rect *pDestRect) { uint8_t stars; Rect starRect, paddingRect; @@ -303,7 +318,7 @@ void Bitmaps_DrawHalfStars(const Bitmaps *pBitmaps, const uint8_t halfStars, con } } -void Bitmaps_GetSoundRect(const Bitmaps *pBitmaps, const bool enabled, const uint8_t scale, Rect *pDestRect) +void Bitmaps_GetSoundRect(const Bitmaps *pBitmaps, const uint8_t scale, Rect *pDestRect) { Rect r; diff --git a/src/Bitmaps.h b/src/Bitmaps.h index 15dcdbd..91575e4 100644 --- a/src/Bitmaps.h +++ b/src/Bitmaps.h @@ -1,14 +1,26 @@ // Copyright (c) Jon Thysell // Licensed under the MIT License. +/** + * @file Bitmaps.h + * + * This file provides a Bitmaps type which contains handles to every + * picture resource used by the game, as well as functions for loading + * and drawing those pictures. + */ + #ifndef BITMAPS_H #define BITMAPS_H #include "MacCommon.h" +/** The number of numeric digit pictures. */ #define NumCharPictCount 10 + +/** The number of star pictures. */ #define StarPictCount 3 +/** Struct containing handles to every picture resource. */ typedef struct sBitmaps { PicHandle TitlePict; @@ -26,19 +38,82 @@ typedef struct sBitmaps PicHandle LightOnPict; } Bitmaps; +/** + * Initializes the Bitmaps by loading each picture resource. + * @param pBitmaps The Bitmaps. + */ void Bitmaps_Init(Bitmaps *pBitmaps); +/** + * Gets the rect bounding a number drawn using the (scaled) pictures. + * @param pBitmaps The Bitmaps. + * @param number The target number. + * @param scale The scale factor. + * @param pDestRect The Rect bounding the scaled picture. + */ void Bitmaps_GetNumberRect(const Bitmaps *pBitmaps, const uint32_t number, const uint8_t scale, Rect *pDestRect); + +/** + * Draws a number using the (scaled) pictures at the pen's location. + * @param pBitmaps The Bitmaps. + * @param number The target number. + * @param scale The scale factor. + */ void Bitmaps_DrawNumber(const Bitmaps *pBitmaps, const uint32_t number, const uint8_t scale); +/** + * Draws an "A" using the (scaled) picture at the pen's location. + * @param pBitmaps The Bitmaps. + * @param scale The scale factor. + */ void Bitmaps_DrawAChar(const Bitmaps *pBitmaps, const uint8_t scale); + +/** + * Draws a "B" using the (scaled) picture at the pen's location. + * @param pBitmaps The Bitmaps. + * @param scale The scale factor. + */ void Bitmaps_DrawBChar(const Bitmaps *pBitmaps, const uint8_t scale); + +/** + * Draws an "/" using the (scaled) picture at the pen's location. + * @param pBitmaps The Bitmaps. + * @param scale The scale factor. + */ void Bitmaps_DrawSlashChar(const Bitmaps *pBitmaps, const uint8_t scale); -void Bitmaps_GetHalfStarsRect(const Bitmaps *pBitmaps, const uint8_t halfStars, const uint8_t maxStars, const uint8_t scale, Rect *pDestRect); +/** + * Gets the rect bounding stars drawn using the (scaled) pictures. + * @param pBitmaps The Bitmaps. + * @param maxStars The number of stars. + * @param scale The scale factor. + * @param pDestRect The Rect bounding the scaled picture. + */ +void Bitmaps_GetHalfStarsRect(const Bitmaps *pBitmaps, const uint8_t maxStars, const uint8_t scale, Rect *pDestRect); + +/** + * Draws (partially) filled stars using the (scaled) pictures. + * @param pBitmaps The Bitmaps. + * @param halfStars The number of half-stars to fill. + * @param maxStars The total number of stars. + * @param scale The scale factor. + */ void Bitmaps_DrawHalfStars(const Bitmaps *pBitmaps, const uint8_t halfStars, const uint8_t maxStars, const uint8_t scale); -void Bitmaps_GetSoundRect(const Bitmaps *pBitmaps, const bool enabled, const uint8_t scale, Rect *pDestRect); +/** + * Gets the rect bounding the sound icon using the (scaled) pictures. + * @param pBitmaps The Bitmaps. + * @param scale The scale factor. + * @param pDestRect The Rect bounding the scaled picture. + */ +void Bitmaps_GetSoundRect(const Bitmaps *pBitmaps, const uint8_t scale, Rect *pDestRect); + +/** + * Draws the sound icon using the (scaled) pictures. + * @param pBitmaps The Bitmaps. + * @param enabled Whether sound is enabled or not. + * @param scale The scale factor. + */ void Bitmaps_DrawSound(const Bitmaps *pBitmaps, const bool enabled, const uint8_t scale); #endif diff --git a/src/Common.h b/src/Common.h index 5368017..04c1e37 100644 --- a/src/Common.h +++ b/src/Common.h @@ -1,19 +1,37 @@ // Copyright (c) Jon Thysell // Licensed under the MIT License. +/** + * @file Common.h + * + * This file includes some common utility functions and macros. + */ + #ifndef COMMON_H #define COMMON_H #include "stdbool.h" #include "stdint.h" +/** Get the minimum of a and b. */ #define min(a,b) ((a)<(b)?(a):(b)) + +/** Get the maximum of a and b. */ #define max(a,b) ((a)>(b)?(a):(b)) +/** Gets the bit within value. */ #define bitRead(value, bit) (((value) >> (bit)) & 0x01) + +/** Sets the bit within value. */ #define bitSet(value, bit) ((value) |= (1UL << (bit))) + +/** Clears the bit within value. */ #define bitClear(value, bit) ((value) &= ~(1UL << (bit))) + +/** Toggles the bit within value. */ #define bitToggle(value, bit) ((value) ^= (1UL << (bit))) + +/** Sets the bit within value to bitValue. */ #define bitWrite(value, bit, bitValue) ((bitBalue) ? bitSet(value, bit) : bitClear(value, bit)) #endif diff --git a/src/GameEndScene.h b/src/GameEndScene.h index fcfee87..1242e24 100644 --- a/src/GameEndScene.h +++ b/src/GameEndScene.h @@ -1,13 +1,36 @@ // Copyright (c) Jon Thysell // Licensed under the MIT License. +/** + * @file GameEndScene.h + * + * This file provides the functions to initialize, draw, and respond to + * clicks when the GameWindow is set to the LevelSelect scene. + */ + #ifndef GAMEENDSCENE_H #define GAMEENDSCENE_H #include "GameWindow.h" +/** + * Initializes the GameEnd scene for the given GameWindow. + * @param pGameWindow The GameWindow. + */ void GameEndScene_Init(GameWindow *pGameWindow); + +/** + * Draws the GameEnd scene for the given GameWindow. + * @param pGameWindow The GameWindow. + * @param fullRefresh Whether or not the whole scene needs to be redrawn. + */ void GameEndScene_Draw(const GameWindow *pGameWindow, bool fullRefresh); + +/** + * Handles clicks on the GameEnd scene for the given GameWindow. + * @param pGameWindow The GameWindow. + * @param pPosition The local position where the click occured. + */ void GameEndScene_Click(GameWindow *pGameWindow, const Point *pPosition); #endif diff --git a/src/GameEngine.h b/src/GameEngine.h index 167e612..2fc10ca 100644 --- a/src/GameEngine.h +++ b/src/GameEngine.h @@ -1,19 +1,34 @@ // Copyright (c) Jon Thysell // Licensed under the MIT License. +/** + * @file GameEngine.h + * + * This file provides the GameEngine type, which manages the the game of + * Light Out, including current level information and the user's progress. + */ + #ifndef GAMEENGINE_H #define GAMEENGINE_H #include "Levels.h" +/** The size (width and height) of a puzzle. */ extern const int8_t PuzzleSize; +/** The max number of full stars for completing a puzzle. */ extern const uint8_t MaxStars; + +/** The max number of half-stars for completing a puzzle. */ extern const uint8_t MaxHalfStars; + +/** The min number of half-stars for completing a puzzle. */ extern const uint8_t MinHalfStars; +/** The max number of half-stars for completing every puzzle in a set. */ extern const uint16_t PerfectScore; +/** Struct containing all the data needed for a game. */ typedef struct GameEngine { uint8_t ScoresA[LevelCount]; @@ -26,38 +41,126 @@ typedef struct GameEngine uint16_t Moves; } GameEngine; +/** + * Initializes the GameEngine. + * @param pGameEngine The GameEngine. + */ void GameEngine_Init(GameEngine *pGameEngine); +/** + * Starts a new game, selecting the first unfinshed level in the set. + * @param pGameEngine The GameEngine. + * @param setB The set. + */ void GameEngine_NewGame(GameEngine *pGameEngine, const bool setB); +/** + * Resets the scores for all levels to zero. + * @param pGameEngine The GameEngine. + */ void GameEngine_ResetGame(GameEngine *pGameEngine); +/** + * Starts the given level. + * @param pGameEngine The GameEngine. + * @param level The level to start. + */ void GameEngine_StartLevel(GameEngine *pGameEngine, const int8_t level); +/** + * Marks the current level as complete, saving the score. + * @param pGameEngine The GameEngine. + */ void GameEngine_CompleteLevel(GameEngine *pGameEngine); +/** + * Advances the game to the next level in the set. + * @param pGameEngine The GameEngine. + */ void GameEngine_NextLevel(GameEngine *pGameEngine); +/** + * Resets the current level to its initial state. + * @param pGameEngine The GameEngine. + */ void GameEngine_ResetLevel(GameEngine *pGameEngine); +/** + * Gets the state of the light at the given coordinates. + * @param pGameEngine The GameEngine. + * @param x The x coordinate of the light. + * @param y The y coordinate of the light. + * @return Whether the light is on or not. + */ bool GameEngine_GetLight(const GameEngine *pGameEngine, const int8_t x, const int8_t y); +/** + * Gets whether the current level has been completed. + * @param pGameEngine The GameEngine. + * @return Whether all of the lights are off. + */ bool GameEngine_IsCompleted(const GameEngine *pGameEngine); +/** + * Gets whether or not the given level can be played. + * @param pGameEngine The GameEngine. + * @param level The level. + * @return Whether the level can be played. + */ bool GameEngine_IsEnabled(const GameEngine *pGameEngine, const int8_t level); +/** + * Gets whether or not the last level has just been completed. + * @param pGameEngine The GameEngine. + * @return Whether or not the game is over. + */ bool GameEngine_IsGameOver(const GameEngine *pGameEngine); +/** + * Gets the number of half-stars the user stands to earn given the current + * state of the level they're trying to solve. + * @param pGameEngine The GameEngine. + * @return The number of half-stars. + */ uint8_t GameEngine_GetHalfStars(const GameEngine *pGameEngine); +/** + * Gets the number of half-stars the user won for a given level. + * @param pGameEngine The GameEngine. + * @param level The level. + * @return The number of half-stars won. + */ uint8_t GameEngine_GetScore(const GameEngine *pGameEngine, const int8_t level); +/** + * Gets the total number of half-stars the user has won across the set. + * @param pGameEngine The GameEngine. + * @return The total number of half-stars won. + */ uint16_t GameEngine_GetTotalScore(const GameEngine *pGameEngine); +/** + * Toggles the lights centered at the given coordinates. + * @param pGameEngine The GameEngine. + * @param x The x coordinate of the center light. + * @param y The y coordinate of the center light. + */ void GameEngine_ToggleLights(GameEngine *pGameEngine, const int8_t x, const int8_t y); +/** + * Gets whether the given light changed after the last toggle. + * @param pGameEngine The GameEngine. + * @param x The x coordinate of the light. + * @param y The y coordinate of the light. + * @return Whether the light changed. + */ bool GameEngine_LightChanged(const GameEngine *pGameEngine, const int8_t x, const int8_t y); +/** + * Gets whether the number of half-stars changed after the last toggle. + * @param pGameEngine The GameEngine. + * @return Whether the number of half-stars changed. + */ bool GameEngine_HalfStarsChanged(const GameEngine *pGameEngine); #endif diff --git a/src/GameWindow.h b/src/GameWindow.h index 8ef5ce8..b0e616c 100644 --- a/src/GameWindow.h +++ b/src/GameWindow.h @@ -1,6 +1,16 @@ // Copyright (c) Jon Thysell // Licensed under the MIT License. +/** + * @file GameWindow.h + * + * This file provides the GameWindow type, which, as MacLO is essentially + * played entirely within one Window, essentially manages the entire game. + * GameWindow keeps track of the core GameEngine as well as the current scene, + * which it calls to handle rendering and to handle user interaction based + * on the state of both. + */ + #ifndef GAMEWINDOW_H #define GAMEWINDOW_H @@ -11,8 +21,10 @@ #include "Sounds.h" #include "Scenes.h" +/** The background pattern of the window. */ #define WindowPattern black +/** Struct containing everything the game needs. */ typedef struct sGameWindow { WindowPtr Window; @@ -28,13 +40,43 @@ typedef struct sGameWindow GameEndScene GameEndScene; } GameWindow; +/** + * Initializes the GameWindow. + * @param pGameWindow The GameWindow. + */ void GameWindow_Init(GameWindow *pGameWindow); + +/** + * Draws the GameWindow. + * @param pGameWindow The GameWindow. + * @param fullRefresh Whether or not the whole screen needs to be redrawn. + */ void GameWindow_Draw(const GameWindow *pGameWindow, bool fullRefresh); + +/** + * Handles clicks on the GameWindow. + * @param pGameWindow The GameWindow. + * @param pPosition The local position where the click occured. + */ void GameWindow_Click(GameWindow *pGameWindow, const Point *pPosition); +/** + * Changes the GameWindow to the given scene. + * @param pGameWindow The GameWindow. + * @param sceneId The new scene. + */ void GameWindow_SetScene(GameWindow *pGameWindow, const SceneId sceneId); + +/** + * Activates the GameWindow. + * @param pGameWindow The GameWindow. + */ void GameWindow_Show(const GameWindow *pGameWindow); +/** + * Resets the level scores of the GameWindow. + * @param pGameWindow The GameWindow. + */ void GameWindow_ClearScores(GameWindow *pGameWindow); #endif diff --git a/src/LevelEndScene.c b/src/LevelEndScene.c index 4a2f364..da06d82 100644 --- a/src/LevelEndScene.c +++ b/src/LevelEndScene.c @@ -22,7 +22,7 @@ void LevelEndScene_Init(GameWindow *pGameWindow) CenterRect(&r, &(pGameWindow->LevelEndScene.LevelRect)); // Setup half-stars - Bitmaps_GetHalfStarsRect(&(pGameWindow->Bitmaps), GameEngine_GetHalfStars(&(pGameWindow->Engine)), MaxStars, HalfStarScale, &(pGameWindow->LevelEndScene.HalfStarsRect)); + Bitmaps_GetHalfStarsRect(&(pGameWindow->Bitmaps), MaxStars, HalfStarScale, &(pGameWindow->LevelEndScene.HalfStarsRect)); GetBoxRect(pContentRect, Center, &r); CenterRect(&r, &(pGameWindow->LevelEndScene.HalfStarsRect)); diff --git a/src/LevelEndScene.h b/src/LevelEndScene.h index 47becb5..113418a 100644 --- a/src/LevelEndScene.h +++ b/src/LevelEndScene.h @@ -1,13 +1,36 @@ // Copyright (c) Jon Thysell // Licensed under the MIT License. +/** + * @file LevelEndScene.h + * + * This file provides the functions to initialize, draw, and respond to + * clicks when the GameWindow is set to the LevelEnd scene. + */ + #ifndef LEVELENDSCENE_H #define LEVELENDSCENE_H #include "GameWindow.h" +/** + * Initializes the LevelEnd scene for the given GameWindow. + * @param pGameWindow The GameWindow. + */ void LevelEndScene_Init(GameWindow *pGameWindow); + +/** + * Draws the LevelEnd scene for the given GameWindow. + * @param pGameWindow The GameWindow. + * @param fullRefresh Whether or not the whole scene needs to be redrawn. + */ void LevelEndScene_Draw(const GameWindow *pGameWindow, bool fullRefresh); + +/** + * Handles clicks on the LevelEnd scene for the given GameWindow. + * @param pGameWindow The GameWindow. + * @param pPosition The local position where the click occured. + */ void LevelEndScene_Click(GameWindow *pGameWindow, const Point *pPosition); #endif diff --git a/src/LevelSelectScene.c b/src/LevelSelectScene.c index 42da3db..2dae8ec 100644 --- a/src/LevelSelectScene.c +++ b/src/LevelSelectScene.c @@ -141,7 +141,7 @@ void LevelSelectScene_Draw(const GameWindow *pGameWindow, bool fullRefresh) if (GameEngine_IsEnabled(&(pGameWindow->Engine), level)) { // Draw half-stars - Bitmaps_GetHalfStarsRect(&(pGameWindow->Bitmaps), GameEngine_GetScore(&(pGameWindow->Engine), level), MaxStars, LevelTextScale, &levelHalfStarsRect); + Bitmaps_GetHalfStarsRect(&(pGameWindow->Bitmaps), MaxStars, LevelTextScale, &levelHalfStarsRect); GetBoxRect(&levelRect, Bottom, &r); GetBoxRect(&r, Top, &r); diff --git a/src/LevelSelectScene.h b/src/LevelSelectScene.h index b552297..196d8fa 100644 --- a/src/LevelSelectScene.h +++ b/src/LevelSelectScene.h @@ -1,13 +1,36 @@ // Copyright (c) Jon Thysell // Licensed under the MIT License. +/** + * @file LevelSelectScene.h + * + * This file provides the functions to initialize, draw, and respond to + * clicks when the GameWindow is set to the LevelSelect scene. + */ + #ifndef LEVELSELECTSCENE_H #define LEVELSELECTSCENE_H #include "GameWindow.h" +/** + * Initializes the LevelSelect scene for the given GameWindow. + * @param pGameWindow The GameWindow. + */ void LevelSelectScene_Init(GameWindow *pGameWindow); + +/** + * Draws the LevelSelect scene for the given GameWindow. + * @param pGameWindow The GameWindow. + * @param fullRefresh Whether or not the whole scene needs to be redrawn. + */ void LevelSelectScene_Draw(const GameWindow *pGameWindow, bool fullRefresh); + +/** + * Handles clicks on the LevelSelect scene for the given GameWindow. + * @param pGameWindow The GameWindow. + * @param pPosition The local position where the click occured. + */ void LevelSelectScene_Click(GameWindow *pGameWindow, const Point *pPosition); #endif diff --git a/src/Levels.h b/src/Levels.h index 0e42a3c..3c12f2f 100644 --- a/src/Levels.h +++ b/src/Levels.h @@ -1,16 +1,36 @@ // Copyright (c) Jon Thysell // Licensed under the MIT License. +/** + * @file Levels.h + * + * This file provides functions for loading the light puzzles, or levels, + * as well as the "par" for each level. Each light puzzle is stored as 25 + * bits within a 32-bit integer. + */ + #ifndef LEVELS_H #define LEVELS_H #include "stdint.h" #include "stdbool.h" +/** The number of levels in each set. */ #define LevelCount 50 +/** + * Gets the lights for a given set and level number. + * @param level The level number. + * @param setB Whether or not to load from Set B. + * @return The lights. + */ uint32_t Levels_GetLightsForLevel(const int8_t level, const bool setB); +/** + * Gets the minimum number of toggles to solve a given level number. + * @param level The level number. + * @return The minimum number of toggles to complete the level. + */ uint16_t Levels_GetParForLevel(const int8_t level); #endif diff --git a/src/MacCommon.c b/src/MacCommon.c index 89e2b63..92537df 100644 --- a/src/MacCommon.c +++ b/src/MacCommon.c @@ -8,21 +8,6 @@ #define ConfirmYesResult 2 -const int16_t MonthOffset[] = { - 0, // Jan - 31, // Feb - 60, // Mar - 91, // Apr - 121, // May - 152, // Jun - 182, // Jul - 213, // Aug - 244, // Sep - 274, // Oct - 305, // Nov - 335, // Dec -}; - void ShowError(Str255 message, bool isFatal) { ParamText(message, EmptyString, EmptyString, EmptyString); diff --git a/src/MacCommon.h b/src/MacCommon.h index c344fd8..8d5751a 100644 --- a/src/MacCommon.h +++ b/src/MacCommon.h @@ -1,19 +1,31 @@ // Copyright (c) Jon Thysell // Licensed under the MIT License. +/** + * @file MacCommon.h + * + * This file includes some common utility functions for use by Macintosh + * applications and the Macintosh Toolbox. + */ + #ifndef MACCOMMON_H #define MACCOMMON_H #include "Common.h" +/** The first non-reserved resource ID. */ #define BaseResID 128 + +/** Constant to put a Window to the top of the stack. */ #define MoveToFront (WindowPtr)-1L +/** An empty Pascal string. */ #define EmptyString "\p" + +/** A nil filter. */ #define NilFilterProc nil -extern const int16_t MonthOffset[]; - +/** Enum defining nine equal boxes within a rectangle. */ typedef enum eBoxAlignment { Top, @@ -27,23 +39,87 @@ typedef enum eBoxAlignment Center } BoxAlignment; -pascal OSErr SetDialogDefaultItem(DialogPtr theDialog, int16_t newItem) = { 0x303C, 0x0304, 0xAA68 }; +/** + * Toolbox function to set the default Button in a Dialog. + * @param theDialog The target Dialog. + * @param itemID The ID of the Button to set as the default. + * @return An error code. + */ +pascal OSErr SetDialogDefaultItem(DialogPtr theDialog, int16_t itemID) = { 0x303C, 0x0304, 0xAA68 }; +/** + * Displays an error message and optionally terminates the application. + * @param message The message to display. + * @param isFatal Whether or not the application should terminate. + */ void ShowError(Str255 message, bool isFatal); +/** + * Prompts the user to confirm continuing with a (destructive) action. + * @param message The message to display. + * @return The user's choice whether or not to continue. + */ bool ShowConfirm(Str255 message); +/** + * Centers an inner Rect within a static outer Rect. + * @param pOuterRect The static outer Rect. + * @param pInnerRect The inner Rect to move. + */ void CenterRect(const Rect *pOuterRect, Rect *pInnerRect); + +/** + * Centers an inner Rect horizontally within a static outer Rect. + * @param pOuterRect The static outer Rect. + * @param pInnerRect The inner Rect to move. + */ void CenterRectH(const Rect *pOuterRect, Rect *pInnerRect); + +/** + * Centers an inner Rect vertically within a static outer Rect. + * @param pOuterRect The static outer Rect. + * @param pInnerRect The inner Rect to move. + */ void CenterRectV(const Rect *pOuterRect, Rect *pInnerRect); +/** + * Combines two Rects into a new Rect, by moving the right Rect directly + * to the right of the left Rect (tops aligned), and finding the smallest + * Rect which contains them both. + * @param pLeftRect The Rect on the left. + * @param pRightRect The Rect on the right. + * @param pDestRect The concatenated Rect. + */ void ConcatenateRect(const Rect *pLeftRect, const Rect *pRightRect, Rect *pDestRect); +/** + * Gets the Rect at the given BoxAlignment within the static outer Rect. + * @param pOuterRect The static outer Rect. + * @param boxAlignment The target BoxAlignment. + * @param pBoxRect The Rect within the outer rect at the BoxAlignment. + */ void GetBoxRect(const Rect *pOuterRect, const BoxAlignment boxAlignment, Rect *pBoxRect); +/** + * Gets the Rect which bounds the given picture. + * @param picHandle The target picture. + * @param pDestRect The Rect bounding the picture. + */ void GetPictureRect(const PicHandle picHandle, Rect *pDestRect); +/** + * Gets the Rect which bounds the given picture if it had been scaled. + * @param picHandle The target picture. + * @param scale The scale factor. + * @param pDestRect The Rect bounding the scaled picture. + */ void GetScaledPicFrame(const PicHandle picHandle, const uint8_t scale, Rect *pDestRect); + +/** + * Draws the given picture scaled at the pen's location. + * @param picHandle The target picture. + * @param scale The scale factor. + */ void DrawScaledPic(const PicHandle pic, const uint8_t scale); #endif diff --git a/src/MacLO.h b/src/MacLO.h index d4d7924..c006515 100644 --- a/src/MacLO.h +++ b/src/MacLO.h @@ -1,11 +1,28 @@ // Copyright (c) Jon Thysell // Licensed under the MIT License. +/** + * @file MacLO.h + * + * This file provides the functions necessary to setup the application. + */ + #ifndef MACLO_H #define MACLO_H +/** + * Initialize the Macintosh Toolbox managers. + */ void MacLO_ToolBoxInit(); + +/** + * Initialize the application. + */ void MacLO_AppInit(); + +/** + * Run the main loop of the application. + */ void MacLO_MainLoop(); #endif diff --git a/src/PlayScene.c b/src/PlayScene.c index cc888ce..b853e92 100644 --- a/src/PlayScene.c +++ b/src/PlayScene.c @@ -45,7 +45,7 @@ void PlayScene_Init(GameWindow *pGameWindow) CenterRect(&r, &(pGameWindow->PlayScene.LevelRect)); // Setup half-stars - Bitmaps_GetHalfStarsRect(&(pGameWindow->Bitmaps), GameEngine_GetHalfStars(&(pGameWindow->Engine)), MaxStars, HalfStarScale, &(pGameWindow->PlayScene.HalfStarsRect)); + Bitmaps_GetHalfStarsRect(&(pGameWindow->Bitmaps), MaxStars, HalfStarScale, &(pGameWindow->PlayScene.HalfStarsRect)); GetBoxRect(&(pGameWindow->PlayScene.HUDRect), Center, &r); CenterRect(&r, &(pGameWindow->PlayScene.HalfStarsRect)); @@ -67,7 +67,7 @@ void PlayScene_Init(GameWindow *pGameWindow) CenterRect(&r, &(pGameWindow->PlayScene.RetryButtonRect)); // Setup sound button - Bitmaps_GetSoundRect(&(pGameWindow->Bitmaps), pGameWindow->Sounds.Enabled, 1, &(pGameWindow->PlayScene.SoundButtonRect)); + Bitmaps_GetSoundRect(&(pGameWindow->Bitmaps), 1, &(pGameWindow->PlayScene.SoundButtonRect)); GetBoxRect(&(pGameWindow->PlayScene.HUDRect), BottomRight, &r); CenterRect(&r, &(pGameWindow->PlayScene.SoundButtonRect)); } diff --git a/src/PlayScene.h b/src/PlayScene.h index 466d330..bcbaea8 100644 --- a/src/PlayScene.h +++ b/src/PlayScene.h @@ -1,13 +1,36 @@ // Copyright (c) Jon Thysell // Licensed under the MIT License. +/** + * @file PlayScene.h + * + * This file provides the functions to initialize, draw, and respond to + * clicks when the GameWindow is set to the Play scene. + */ + #ifndef PLAYSCENE_H #define PLAYSCENE_H #include "GameWindow.h" +/** + * Initializes the Play scene for the given GameWindow. + * @param pGameWindow The GameWindow. + */ void PlayScene_Init(GameWindow *pGameWindow); + +/** + * Draws the Play scene for the given GameWindow. + * @param pGameWindow The GameWindow. + * @param fullRefresh Whether or not the whole scene needs to be redrawn. + */ void PlayScene_Draw(const GameWindow *pGameWindow, bool fullRefresh); + +/** + * Handles clicks on the Play scene for the given GameWindow. + * @param pGameWindow The GameWindow. + * @param pPosition The local position where the click occured. + */ void PlayScene_Click(GameWindow *pGameWindow, const Point *pPosition); #endif diff --git a/src/Scenes.h b/src/Scenes.h index be21742..5d0bbe0 100644 --- a/src/Scenes.h +++ b/src/Scenes.h @@ -1,11 +1,20 @@ // Copyright (c) Jon Thysell // Licensed under the MIT License. +/** + * @file Scenes.h + * + * This file provides a variety of scene-specific types which contain the + * data that those scenes require to render properly. + */ + #ifndef SCENES_H #define SCENES_H -#define NumScenes 4 +/** The total number of scenes. */ +#define NumScenes 5 +/** Enum defining unique IDs for each scene. */ typedef enum eSceneId { Title, @@ -15,6 +24,7 @@ typedef enum eSceneId GameEnd } SceneId; +/** Struct containing data needed for the Title scene. */ typedef struct sTitleScene { Rect TitleRect; @@ -23,6 +33,7 @@ typedef struct sTitleScene Rect SoundButtonRect; } TitleScene; +/** Struct containing data needed for the LevelSelect scene. */ typedef struct sLevelSelectScene { int8_t PageNumber; @@ -33,6 +44,7 @@ typedef struct sLevelSelectScene Rect LevelGridRect; } LevelSelectScene; +/** Struct containing data needed for the Play scene. */ typedef struct sPlayScene { Rect PlayfieldRect; @@ -44,6 +56,7 @@ typedef struct sPlayScene Rect SoundButtonRect; } PlayScene; +/** Struct containing data needed for the LevelEnd scene. */ typedef struct sLevelEndScene { Rect LevelRect; @@ -53,6 +66,7 @@ typedef struct sLevelEndScene Rect NextButtonRect; } LevelEndScene; +/** Struct containing data needed for the GameEnd scene. */ typedef struct sGameEndScene { Rect SetRect; diff --git a/src/Sounds.h b/src/Sounds.h index d7cfdf8..03c7d36 100644 --- a/src/Sounds.h +++ b/src/Sounds.h @@ -1,6 +1,13 @@ // Copyright (c) Jon Thysell // Licensed under the MIT License. +/** + * @file Sounds.h + * + * This file provides a Sounds type which contains handles to every + * sound resource used by the game, as well as functions for playing them. + */ + #ifndef SOUNDS_H #define SOUNDS_H @@ -8,6 +15,7 @@ #include "MacCommon.h" +/** Struct containing handles to every sound resource. */ typedef struct sSounds { bool Enabled; @@ -16,10 +24,28 @@ typedef struct sSounds Handle DoneSnd; } Sounds; +/** + * Initializes the Sounds by loading each sound resource. + * @param pSounds The Sounds. + */ void Sounds_Init(Sounds *pSounds); +/** + * Plays the "click" sound. + * @param pSounds The Sounds. + */ void Sounds_PlayClickSnd(const Sounds *pSounds); + +/** + * Plays the "retry" sound. + * @param pSounds The Sounds. + */ void Sounds_PlayRetrySnd(const Sounds *pSounds); + +/** + * Plays the "done" sound. + * @param pSounds The Sounds. + */ void Sounds_PlayDoneSnd(const Sounds *pSounds); #endif diff --git a/src/TitleScene.c b/src/TitleScene.c index 92e9995..7ab9e09 100644 --- a/src/TitleScene.c +++ b/src/TitleScene.c @@ -29,7 +29,7 @@ void TitleScene_Init(GameWindow *pGameWindow) CenterRect(&r, &(pGameWindow->TitleScene.SetBRect)); // Setup sound button - Bitmaps_GetSoundRect(&(pGameWindow->Bitmaps), pGameWindow->Sounds.Enabled, TitleTextScale, &(pGameWindow->TitleScene.SoundButtonRect)); + Bitmaps_GetSoundRect(&(pGameWindow->Bitmaps), TitleTextScale, &(pGameWindow->TitleScene.SoundButtonRect)); GetBoxRect(pContentRect, Bottom, &r); CenterRect(&r, &(pGameWindow->TitleScene.SoundButtonRect)); } diff --git a/src/TitleScene.h b/src/TitleScene.h index 1ace401..2d3bdd5 100644 --- a/src/TitleScene.h +++ b/src/TitleScene.h @@ -1,13 +1,36 @@ // Copyright (c) Jon Thysell // Licensed under the MIT License. +/** + * @file TitleScene.h + * + * This file provides the functions to initialize, draw, and respond to + * clicks when the GameWindow is set to the Title scene. + */ + #ifndef TITLESCENE_H #define TITLESCENE_H #include "GameWindow.h" +/** + * Initializes the Title scene for the given GameWindow. + * @param pGameWindow The GameWindow. + */ void TitleScene_Init(GameWindow *pGameWindow); + +/** + * Draws the Title scene for the given GameWindow. + * @param pGameWindow The GameWindow. + * @param fullRefresh Whether or not the whole scene needs to be redrawn. + */ void TitleScene_Draw(const GameWindow *pGameWindow, bool fullRefresh); + +/** + * Handles clicks on the Title scene for the given GameWindow. + * @param pGameWindow The GameWindow. + * @param pPosition The local position where the click occured. + */ void TitleScene_Click(GameWindow *pGameWindow, const Point *pPosition); #endif diff --git a/src/WindowBuffer.h b/src/WindowBuffer.h index 7350572..a94ff5a 100644 --- a/src/WindowBuffer.h +++ b/src/WindowBuffer.h @@ -1,17 +1,41 @@ // Copyright (c) Jon Thysell // Licensed under the MIT License. +/** + * @file WindowBuffer.h + * + * This file provides a WindowBuffer type which manages offscreen buffering + * of Toolbox drawing commands on behalf of a Window. + */ + #ifndef WINDOWBUFFER_H #define WINDOWBUFFER_H +/** Struct containing pointers to the Window and its offscreen buffer. */ typedef struct sWindowBuffer { WindowPtr Window; GrafPtr Buffer; } WindowBuffer; +/** + * Initializes the WindowBuffer for the given Window. + * @param pWindowBuffer The WindowBuffer. + * @param window The Window to buffer. + */ void WindowBuffer_Init(WindowBuffer *pWindowBuffer, const WindowPtr window); + +/** + * Start redirecting drawing to the offscreen buffer. + * @param pWindowBuffer The WindowBuffer. + */ void WindowBuffer_StartDraw(const WindowBuffer *pWindowBuffer); + +/** + * Stop redirecting drawing to the offscreen buffer, and immediately copy + * everything from the buffer to the Window. + * @param pWindowBuffer The WindowBuffer. + */ void WindowBuffer_EndDraw(const WindowBuffer *pWindowBuffer); #endif \ No newline at end of file diff --git a/src/stdbool.h b/src/stdbool.h index 624d7ca..3d12ac1 100644 --- a/src/stdbool.h +++ b/src/stdbool.h @@ -1,9 +1,16 @@ // Copyright (c) Jon Thysell // Licensed under the MIT License. +/** + * @file stdbool.h + * + * This file backports the 'bool' boolean type from C99 to C89. + */ + #ifndef STDBOOL_H #define STDBOOL_H +/** Boolean type. */ typedef Boolean bool; #endif diff --git a/src/stdint.h b/src/stdint.h index 58d73fe..ad79cf5 100644 --- a/src/stdint.h +++ b/src/stdint.h @@ -1,41 +1,72 @@ // Copyright (c) Jon Thysell // Licensed under the MIT License. +/** + * @file stdint.h + * + * This file backports the fixed-width integer types from C99 to C89. + */ + #ifndef STDINT_H #define STDINT_H #include #if !defined(UINT8_MAX) && defined(UCHAR_MAX) && (UCHAR_MAX) == 0xFFU + +/** Unsigned integer type with width of exactly 8 bits. */ typedef unsigned char uint8_t; + +/** Signed integer type with width of exactly 8 bits. */ typedef signed char int8_t; + +/** The max value of an uint8_t. */ #define UINT8_MAX UCHAR_MAX + +/** The max value of an int8_t. */ #define INT8_MAX CHAR_MAX + +/** The min value of an int8_t. */ #define INT8_MIN CHAR_MIN + #endif #if !defined(UINT16_MAX) && defined(USHRT_MAX) && (USHRT_MAX) == 0xFFFFU -typedef unsigned short uint16_t; -typedef signed short int16_t; -#define UINT16_MAX USHRT_MAX -#define INT16_MAX SHRT_MAX -#define INT16_MIN SHRT_MIN -#endif -#if !defined(UINT32_MAX) && defined(UINT_MAX) && (UINT_MAX) == 0xFFFFFFFFUL -typedef unsigned int uint32_t; -typedef signed int int32_t; -#define UINT32_MAX UINT_MAX -#define INT32_MAX INT_MAX -#define INT32_MIN INT_MIN +/** Unsigned integer type with width of exactly 16 bits. */ +typedef unsigned short uint16_t; + +/** Signed integer type with width of exactly 16 bits. */ +typedef signed short int16_t; + +/** The max value of an uint16_t. */ +#define UINT16_MAX USHRT_MAX + +/** The max value of an int16_t. */ +#define INT16_MAX SHRT_MAX + +/** The min value of an int16_t. */ +#define INT16_MIN SHRT_MIN + #endif #if !defined(UINT32_MAX) && defined(ULONG_MAX) && (ULONG_MAX) == 0xFFFFFFFFUL + +/** Unsigned integer type with width of exactly 32 bits. */ typedef unsigned long uint32_t; + +/** Signed integer type with width of exactly 32 bits. */ typedef signed long int32_t; + +/** The max value of an uint32_t. */ #define UINT32_MAX ULONG_MAX + +/** The max value of an int32_t. */ #define INT32_MAX LONG_MAX + +/** The min value of an int32_t. */ #define INT32_MIN LONG_MIN + #endif #endif