Added support for desktop full screen with pillarboxing and letterboxing

and started adding some comments to the code

include/AssetManager.h

@@ -22,14 +22,38 @@ typedef enum {
 } AssetType;
 typedef struct asset_manager AssetManager;
 
+/**
+ * Attempts to allocate an AssetManager object on the heap.
+ *
+ * Returns the pointer to the object when it succeeds, or NULL if it fails.
+ */
 AssetManager *create_asset_manager();
+
+/**
+ * Attempts to load an asset to the manager from a file path.
+ *
+ * Returns the AssetID on success or an INVALID_ID in the case of failure.
+ */
 AssetID load_asset_to_manager(AssetManager *am, const char *path,
                               AssetType type, Renderer *renderer);
+
+/**
+ * Removes an asset from the manager using its ID.
+ *
+ * Does nothing if the ID is not valid.
+ */
 void remove_asset_from_manager(AssetManager *am, AssetID *id_ptr);
+
 SDL_Texture *get_texture(AssetManager *am, AssetID id);
 TTF_Font *get_font(AssetManager *am, AssetID id);
 Mix_Chunk *get_audio_chunk(AssetManager *am, AssetID id);
 Mix_Music *get_music(AssetManager *am, AssetID id);
+
+/**
+ * Frees the memory allocated to the AssetManager object and performs the
+ * necessary cleanup to free all memory that were allocated to the loaded
+ * assets.
+ */
 void destroy_asset_manager(AssetManager **am);
 
 #ifdef __cplusplus

include/GameEngine.h

@@ -4,6 +4,7 @@
 #include "AssetManager.h"
 #include "ObjectStore.h"
 #include "SDL_pixels.h"
+#include "SDL_rect.h"
 #include "Window.h"
 #include "reusable_ids.h"
 #include <stdbool.h>
@@ -13,20 +14,68 @@
 extern "C" {
 #endif // !__cplusplus
 
+// GENERAL ENGINE API
+
+/**
+ * Initialises the game engine. Returns true on success and false on failure.
+ *
+ * The audio_tracks parameter determines how many audio tracks to be allocated.
+ * Pass 0 if you want to allocate the default number.
+ */
 bool init_engine(const char *game_name, WindowSize window_size,
                  SDL_Color window_background_color, bool full_screen,
                  uint8_t audio_tracks);
+
 bool game_running();
-WindowSize get_window_defined_size();
-WindowSize get_window_drawable_size();
+void close_engine();
+// END GENERAL ENGINE API
+
+// ASSET MANAGEMENT API
 ObjectID add_object(void *object, EventHandlerPtr eh, UpdateFuncPtr uf,
                     RenderFuncPtr rf);
 void remove_object(ObjectID *id);
+// END ASSET MANAGEMENT API
+
+// ASSET MANAGEMENT API
 AssetID load_asset(const char *path, AssetType type);
+void close_asset(AssetID *id);
+// END ASSET MANAGEMENT API
+
+// RENDERING API
+
+/**
+ * Returns the user-defined window size or the screen size when in full screen.
+ */
+WindowSize get_window_defined_size();
+
+/**
+ * Returns the actual window size which can be different from the user-defined
+ * size or the screen size if the window is on a display that supports high DPI.
+ */
+WindowSize get_window_real_size();
+
+/**
+ * Returns the valid drawing area which can be a portion of the screen when
+ * running in full screen mode and the width to height ratio of the user-defined
+ * window size is different from the width to height ratio of the screen.
+ */
+WindowDrawingArea get_window_drawing_area();
+
+void fill_rectangle(float x, float y, float w, float h, SDL_Color color);
+
+/**
+ * Ensures that a rendered rectangle is clipped to the drawing area when it is
+ * smaller than the actual size of the window.
+ */
+void clip_render_rect_to_drawing_area(SDL_FRect *rect);
+
 void render_texture_asset(AssetID id, float x, float y, float w, float h);
 void render_text_with_font_asset(AssetID id, const char *text, float x,
                                  float y);
 void set_font_asset_size(AssetID id, uint32_t size);
+// END RENDERING API
+
+// AUDIO API
 int8_t play_audio_asset(AssetID id, int16_t loops, bool fade_in,
                         uint32_t fade_length_in_ms);
 void pause_audio_asset_on_track(AssetID id, uint8_t track);
@@ -56,11 +105,13 @@ void stop_playing_music();
 void fade_out_playing_music(uint32_t fade_length_in_ms);
 void set_playing_music_volume(int8_t volume);
 bool is_music_playing();
-void close_asset(AssetID *id);
+// END AUDIO API
+
+// GAME LOOP API
 void handle_events();
 void update();
 void render();
-void close_engine();
+// END GAME LOOP API
 
 #ifdef __cplusplus
 }

include/ObjectStore.h

@@ -17,13 +17,36 @@ typedef void (*RenderFuncPtr)(void *object);
 
 typedef struct object_store ObjectStore;
 
+/**
+ * Attempts to allocate an ObjectStore object on the heap.
+ *
+ * Returns the pointer to the object when it succeeds, or NULL if it fails.
+ */
 ObjectStore *create_object_store();
+
+/**
+ * Attempts to add an object to the store.
+ *
+ * Returns the ObjectID on success or an INVALID_ID in the case of failure.
+ */
 ObjectID add_object_to_store(ObjectStore *os, void *object, EventHandlerPtr eh,
                              UpdateFuncPtr uf, RenderFuncPtr rf);
+
+/**
+ * Removes an object from the store using its ID.
+ *
+ * Does nothing if the ID is not valid.
+ */
 void remove_object_from_store(ObjectStore *os, ObjectID *id_ptr);
+
 void handle_all_objects_events(ObjectStore *os, const SDL_Event *event);
 void update_all_objects(ObjectStore *os, float delta);
 void render_all_objects(ObjectStore *os);
+
+/**
+ * Frees the memory allocated to the ObjectStore object and performs the
+ * necessary cleanup.
+ */
 void destroy_object_store(ObjectStore **os);
 
 #ifdef DEBUG_ENGINE

include/Renderer.h

@@ -14,16 +14,41 @@ extern "C" {
 
 typedef struct renderer Renderer;
 
-Renderer *create_renderer();
-bool init_renderer(Renderer *renderer, SDL_Window *window);
-void get_drawable_size(Renderer *renderer, int32_t *w, int32_t *h);
+/**
+ * Attempts to allocate a Renderer object on the heap.
+ *
+ * Returns the pointer to the object when it succeeds, or NULL if it fails.
+ */
+Renderer *create_renderer(SDL_Window *window);
+
+/**
+ * Returns the valid drawable area that the renderer can use.
+ *
+ * Useful when rendering on screens that support high DPI since the drawable
+ * area is usually bigger than the user-defined size.
+ */
+void get_render_output_size(Renderer *renderer, int32_t *w, int32_t *h);
+
+/**
+ * Attempts to load an SDL_Texture from a file path.
+ *
+ * Returns a pointer to the object if it succeeds or NULL when it fails.
+ */
 SDL_Texture *load_texture(const Renderer *renderer, const char *path);
+
 void render_clear(const Renderer *renderer, SDL_Color color);
+void fill_rect(const Renderer *renderer, SDL_Color color, float x, float y,
+               float w, float h);
 void render_surface(const Renderer *renderer, SDL_Surface *surface, float x,
                     float y, float w, float h);
 void render_texture(const Renderer *renderer, SDL_Texture *texture, float x,
                     float y, float w, float h);
 void swap_buffers(const Renderer *renderer);
+
+/**
+ * Frees the memory allocated to the Renderer object and performs the
+ * necessary cleanup.
+ */
 void destroy_renderer(Renderer **renderer);
 
 #ifdef __cplusplus

include/Window.h

@@ -16,12 +16,27 @@ typedef struct window_size {
   int32_t height;
 } WindowSize;
 
+typedef struct drawing_area {
+  float x;
+  float y;
+  float width;
+  float height;
+} WindowDrawingArea;
+
 typedef struct window {
+  // We need to store the defined size because the coordinates of the mouse
+  // cursor are calculated according to it. In the case of displays that support
+  // high DPI, this creates a problem, because the mouse coordinates retrieved
+  // from an SDL_Event won't work with the actual window size. By storing the
+  // defined size of the window, this allows us to convert the mouse coordinates
+  // to a ratio of the defined size, then multiply that ratio by the real size.
   WindowSize defined_size;
-  WindowSize drawable_size;
+  WindowSize real_size;
+  WindowDrawingArea drawing_area;
   Renderer *renderer;
   SDL_Window *SDL_base_window;
   SDL_Color background_color;
+  bool full_screen;
 } Window;
 
 bool init_window(Window *wnd, const char *title, WindowSize size,