Added support for desktop full screen with pillarboxing and letterboxing

and started adding some comments to the code

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
 }