Some documentation additions

doc/modules.md

@@ -1,119 +1,122 @@
 The overall source code is structured where each .c represents a particular module. These modules are:
 
 ## 2D modules
-|File|Functionality|
+|Module|Functionality|
 |--------|-------|
-|Bitmap.c|Represents a 2D array of pixels (and encoding/decoding to PNG)
+|Bitmap|Represents a 2D array of pixels (and encoding/decoding to PNG)
-|Drawer2D.c|Contains a variety of drawing operations on bitmaps (including text and fonts)
+|Drawer2D|Contains a variety of drawing operations on bitmaps (including text and fonts)
-|PackedCol.c|32 bit RGBA color in a format suitable for using as color component of a vertex
+|PackedCol|32 bit RGBA color in a format suitable for using as color component of a vertex
+|SystemFonts|Drawing, measuring, and retrieving the list of platform/system specific fonts
 
 ## Audio modules
-|File|Functionality|
+|Module|Functionality|
 |--------|-------|
-|Audio.c|Playing music and dig/place/step sounds, and abstracts a PCM audio playing API
+|Audio|Playing music and dig/place/step sounds, and abstracts a PCM audio playing API
-|Vorbis.c| Decodes [ogg vorbis](https://xiph.org/vorbis/) audio into PCM audio samples
+|Vorbis| Decodes [ogg vorbis](https://xiph.org/vorbis/) audio into PCM audio samples
 
 ## Entity modules
-|File|Functionality|
+|Module|Functionality|
 |--------|-------|
-|Entity.c|Represents an in-game entity, and manages updating and rendering all entities
+|Entity|Represents an in-game entity, and manages updating and rendering all entities
-|EntityComponents.c|Various components that can be used by entities (e.g. tilt, animation, hacks state)
+|EntityComponents|Various components that can be used by entities (e.g. tilt, animation, hacks state)
-|Model.c|Contains the list of entity models, and provides relevant methods for entity models
+|Model|Contains the list of entity models, and provides relevant methods for entity models
-|Particle.c|Represents particle effects, and manages rendering and spawning particles
+|Particle|Represents particle effects, and manages rendering and spawning particles
 
 ## Game modules
 |File|Functionality|
 |--------|-------|
-|Block.c|Stores properties and data for blocks (e.g. collide type, draw type, sound type)
+|Block|Stores properties and data for blocks (e.g. collide type, draw type, sound type)
-|BlockPhysics.c|Implements simple block physics for singleplayer
+|BlockPhysics|Implements simple block physics for singleplayer
-|Camera.c|Represents a camera (can be first or third person)
+|Camera|Represents a camera (can be first or third person)
-|Chat.c|Manages sending, adding, logging and handling chat
+|Chat|Manages sending, adding, logging and handling chat
-|Game.c|Manages the overall game loop, state, and variables (e.g. renders a frame, runs scheduled tasks)
+|Game|Manages the overall game loop, state, and variables (e.g. renders a frame, runs scheduled tasks)
-|Input.c|Manages keyboard, mouse, and touch state and events, and implements base handlers for them
+|Input|Manages keyboard, mouse, and touch state and events, and implements base handlers for them
-|Inventory.c|Manages inventory hotbar, and ordering of blocks in the inventory menu
+|Inventory|Manages inventory hotbar, and ordering of blocks in the inventory menu
 
 ## Game gui modules
 |File|Functionality|
 |--------|-------|
-|Gui.c|Describes and manages the 2D GUI elements on screen
+|Gui|Describes and manages the 2D GUI elements on screen
-|IsometricDrawer.c|Draws 2D isometric blocks for the hotbar and inventory UIs
+|IsometricDrawer|Draws 2D isometric blocks for the hotbar and inventory UIs
-|Menus.c|Contains all 2D non-menu screens (e.g. inventory, HUD, loading, chat)
+|Menus|Contains all 2D non-menu screens (e.g. inventory, HUD, loading, chat)
-|Screens.c|Contains all 2D menu screens (e.g. pause menu, keys list menu, font list menu)
+|Screens|Contains all 2D menu screens (e.g. pause menu, keys list menu, font list menu)
-|Widgets.c|Contains individual GUI widgets (e.g. button, label)
+|Widgets|Contains individual GUI widgets (e.g. button, label)
 
 ## Graphics modules
-|File|Functionality|
+|Module|Functionality|
 |--------|-------|
-|Builder.c|Converts a 16x16x16 chunk into a mesh of vertices
+|Builder|Converts a 16x16x16 chunk into a mesh of vertices
-|Drawer.c|Draws the vertices for a cuboid region
+|Drawer|Draws the vertices for a cuboid region
-|Graphics.c|Abstracts a 3D graphics rendering API
+|Graphics|Abstracts a 3D graphics rendering API
 
 ## I/O modules
-|File|Functionality|
+|Module|Functionality|
 |--------|-------|
-|Deflate.c|Decodes and encodes data compressed using DEFLATE (in addition to GZIP/ZLIB headers)
+|Deflate|Decodes and encodes data compressed using DEFLATE (in addition to GZIP/ZLIB headers)
-|Stream.c|Abstract reading and writing data to/from various sources in a streaming manner
+|Stream|Abstract reading and writing data to/from various sources in a streaming manner
 
 ## Launcher modules 
-|File|Functionality|
+|Module|Functionality|
 |--------|-------|
-|Launcher.c|Manages the overall launcher loop, state, and variables (e.g. resets pixels in areas, marks areas as needing to be redrawn)
+|Launcher|Manages the overall launcher loop, state, and variables (e.g. resets pixels in areas, marks areas as needing to be redrawn)
-|LScreens.c|Contains all the menus in the launcher (e.g. servers list, updates menu, main menu)
+|LBackend|Handles the rendering of widgets and forwarding input events to screens/menus
-|LWeb.c|Responsible for launcher related web requests (e.g. signing in, fetching servers list)
+|LScreens|Contains all the menus in the launcher (e.g. servers list, updates menu, main menu)
-|LWidgets.c|Contains individual launcher GUI widgets (e.g. button, label, input textbox)
+|LWeb|Responsible for launcher related web requests (e.g. signing in, fetching servers list)
-|Resources.c|Responsible for checking, downloading, and creating the default assets (e.g. default.zip, sounds)
+|LWidgets|Contains individual launcher GUI widgets (e.g. button, label, input textbox)
+|Resources|Responsible for checking, downloading, and creating the default assets (e.g. default.zip, sounds)
 
 ## Map modules 
-|File|Description|
+|Module|Description|
 |--------|-------|
-|Formats.c|Imports/exports a world from/to several map file formats (e.g. .cw, .dat, .lvl)
+|Formats|Imports/exports a world from/to several map file formats (e.g. .cw, .dat, .lvl)
-|Generator.c|Generates a new world in either a flatgrass or Minecraft Classic style
+|Generator|Generates a new world in either a flatgrass or Minecraft Classic style
-|Lighting.c|Gets lighting colors at coordinates in the world
+|Lighting|Gets lighting colors at coordinates in the world
-|World.c|Manages fixed size 3D array of blocks and associated environment metadata
+|World|Manages fixed size 3D array of blocks and associated environment metadata
 
 ## Math/Physics modules 
-|File|Description|
+|Module|Description|
 |--------|-------|
-|ExtMath.c|Math functions, math constants, and a Random Number Generator
+|ExtMath|Math functions, math constants, and a Random Number Generator
-|Physics.c|AABBs and geometry intersection
+|Physics|AABBs and geometry intersection
-|Picking.c|Performs raytracing to e.g. determine the picked/selected block in the world
+|Picking|Performs raytracing to e.g. determine the picked/selected block in the world
-|Vectors.c|Contains vector,matrix,and frustum culling
+|Vectors|Contains vector,matrix,and frustum culling
 
 ## Network modules 
-|File|Description|
+|Module|Description|
 |--------|-------|
-|Http.c|Performs GET and POST requests in the background
+|Http|Performs GET and POST requests in the background
-|Protocol.c|Implements Minecraft Classic, CPE, and WoM environment protocols
+|Protocol|Implements Minecraft Classic, CPE, and WoM environment protocols
-|Server.c|Manages a connection to a singleplayer or multiplayer server
+|Server|Manages a connection to a singleplayer or multiplayer server
+|SSL|Performs SSL/TLS encryption and decryption
 
 ## Platform modules
-|File|Description|
+|Module|Description|
 |--------|-------|
-|Logger.c|Manages logging to client.log, and dumping state in both intentional and unhandled crashes
+|Logger|Manages logging to client.log, and dumping state in both intentional and unhandled crashes
-|Platform.c|Abstracts platform specific functionality. (e.g. opening a file, allocating memory, starting a thread)
+|Platform|Abstracts platform specific functionality. (e.g. opening a file, allocating memory, starting a thread)
-|Program.c|Parses command line arguments, and then starts either the Game or Launcher
+|Program|Parses command line arguments, and then starts either the Game or Launcher
-|Window.c|Abstracts creating and managing a window (e.g. setting titlebar text, entering fullscreen)
+|Window|Abstracts creating and managing a window (e.g. setting titlebar text, entering fullscreen)
 
 ## Rendering modules
-|File|Description|
+|Module|Description|
 |--------|-------|
-|AxisLinesRenderer.c|Renders 3 lines showing direction of each axis
+|AxisLinesRenderer|Renders 3 lines showing direction of each axis
-|EnvRenderer.c|Renders environment of the world (clouds, sky, skybox, world sides/edges, etc)
+|EnvRenderer|Renders environment of the world (clouds, sky, skybox, world sides/edges, etc)
-|HeldBlockRenderer.c|Renders the block currently being held in bottom right corner
+|HeldBlockRenderer|Renders the block currently being held in bottom right corner
-|MapRenderer.c|Renders the blocks of the world by diving it into chunks, and manages sorting/updating these chunks
+|MapRenderer|Renders the blocks of the world by diving it into chunks, and manages sorting/updating these chunks
-|PickedPosRenderer.c|Renders an outline around the block currently being looked at
+|PickedPosRenderer|Renders an outline around the block currently being looked at
-|SelectionBox.c|Renders and stores selection boxes
+|SelectionBox|Renders and stores selection boxes
 
 ## Texture pack modules
-|File|Functionality|
+|Module|Functionality|
 |--------|-------|
-|Animations.c|Everything relating to texture animations (including default water/lava ones)
+|Animations|Everything relating to texture animations (including default water/lava ones)
-|TexturePack.c|Everything relating to texture packs (e.g. extracting .zip, terrain atlas, etc)
+|TexturePack|Everything relating to texture packs (e.g. extracting .zip, terrain atlas, etc)
 
 ## Utility modules
-|File|Functionality|
+|Module|Functionality|
 |--------|-------|
-|Event.c|Contains all events and provies helper methods for using events
+|Event|Contains all events and provies helper methods for using events
-|Options.c|Retrieves options from and sets options in options.txt
+|Options|Retrieves options from and sets options in options.txt
-|String.c|Implements operations for a string with a buffer, length, and capacity
+|String|Implements operations for a string with a buffer, length, and capacity
-|Utils.c|Various general utility functions
+|Utils|Various general utility functions

doc/overriding-defaults.md

@@ -1,15 +1,30 @@
-#### Note: By default, ClassiCube automatically selects the recommended backends for the platform. <br> It is recommended that you do *NOT* change the backends unless you know exactly what you are doing.
+Although ClassiCube strives to be as platform independent as possible, in some cases it will need to use system specific code
+
+For instance:
+* Texture creation for 3D graphics rendering
+* Buffer allocation for audio output
+* High resolution time measurement
+* Window creation
+
+For simplicity, related system specific code is grouped together as a Module (e.g. `Audio`), which can then be implemented using a backend (e.g. `WinMM`, `OpenAL`, `OpenSL ES`, etc)
+
+#### Note: By default, ClassiCube automatically selects the recommended backends for the system. <br> It is recommended that you do *NOT* change the backends unless you know exactly what you are doing.
+
+However, on some systems there are potentially multiple backends for a Module. For example on Windows:
+* OpenGL could be used instead of Direct3D 9 for the 3D rendering backend
+* SDL could be used instead of the native WinAPI for the window backend
 
 TODO finish this
 
 TODO introduction (explaining platform specific modules, and how classicube has to integrate with one of them)
 
-Two ways
+There are two ways of changing the backend that gets used for the system:
 1) Changing the defines in `Core.h`
 2) Adding `-DCC_BUILD_MANUAL` to compilation flags and then manually defining module backends via additional compilation flags
 
 When manually compiling the source code, 1) is usually the easiest. <br>
 For automated scripts compiling every single commit, 2) is the recommended approach
+TODO: Move this into table
 
 
 ### 3D Graphics backends
@@ -34,6 +49,7 @@ The OpenGL backend can be further customised:
 
 ### SSL backends
 * CC_BUILD_SCHANNEL
+* CC_BUILD_BEARSSL
 
 ### Window backends
 * CC_BUILD_SDL

doc/portability.md

@@ -1,6 +1,6 @@
 Although most of the code is platform-independent, some per-platform functionality is required.
 
-By default I try to automatically define appropriate backends for your OS in Core.h. Define ```CC_BUILD_MANUAL``` to disable this.
+By default I try to automatically define appropriate backends for your system in `Core.h`. Define ```CC_BUILD_MANUAL``` to disable this.
 
 ## Before you start
 * IEEE floating support is required.
@@ -58,7 +58,7 @@ I don't really test these platforms at all, only when I suspect some changes to
 |Linux ARM | Raspberry pi | ARM64 should work too |
 |Linux SPARC | Debian | Didn't really work due to lack of 24-bit colours |
 |Linux Alpha | Debian | 
-|HaikuOS | Nightly | Requires SDL for windowing
+|HaikuOS | Nightly | 
 
 ## Porting
 
@@ -123,10 +123,11 @@ Define:
 - ```CC_BUILD_GLMODERN``` - Use modern OpenGL shaders
 - ```CC_BUILD_GLES``` - Makes these shaders compatible with OpenGL ES
 
-### Http
+### HTTP
 HTTP, HTTPS, and setting request/getting response headers
 
 Define:
-- ```CC_BUILD_CURL``` - use libcurl for http
+- ```CC_BUILD_HTTPCLIENT``` - use built in simple HTTP backend
+- ```CC_BUILD_CURL``` - use libcurl for HTTP
 
 Supporting connection reuse is highly recommended. (but not required)

doc/strings.md

@@ -203,10 +203,105 @@ std::sprintf -> String_Format1/2/3/4
 ```
 
 
-## lifetime examples
 
-Stack allocated returning example
 
-Mem_Alloc/Mem_Free and function example
+## Lifetime examples
 
-UNSAFE and mutating characters example
+Managing the lifetime of strings is important, as not properly managing them can cause issues.
+
+For example, consider the following function:
+```C
+const cc_string* GetString(void);
+
+void PrintSomething(void) {
+	cc_string* str = GetString();
+	// .. other code ..
+	Chat_Add(str);
+}
+```
+
+Without knowing the lifetime of the string returned from `GetString`, using it might either:
+* Work just fine
+* Sometimes work fine
+* Cause a subtle issue
+* Cause a major problem
+ptodo rearrange
+
+### Constant string return example
+```C
+const cc_string* GetString(void) {
+	static cc_string str = String_FromConst("ABC");
+	return &str;
+}
+```
+
+This will work fine - as long as the caller does not modify the returned string at all
+
+### Stack allocated string return example
+
+```C
+const cc_string* GetString(void) {
+	char strBuffer[1024];
+	cc_string str = String_FromArray(strBuffer);
+	
+	String_AppendConst(&str, "ABC");
+	return &str;
+}
+```
+
+This will **almost certainly cause problems** - after `GetString` returns, the contents of both `str` and `strBuffer` may be changed to arbitary values (as once `GetString` returns, their contents are then eligible to be overwritten by other stack allocated variables)
+
+As a general rule, you should **NEVER** return a string allocated on the stack
+
+### Dynamically allocated string return example
+
+```C
+const cc_string* GetString(void) {
+	char* buffer   = Mem_Alloc(1024, 1, "string buffer");
+	cc_string* str = Mem_Alloc(1, sizeof(cc_string), "string"); 
+	
+	*str = String_Init(buffer, 0, 1024);
+	String_AppendConst(str, "ABC");
+	return str;
+}
+```
+
+This will work fine - however, now you also need to remember to `Mem_Free` both the string and its buffer to avoid a memory leak
+
+As a general rule, you should avoid returning a dynamically allocated string
+
+### UNSAFE mutable string return example
+
+```C
+char global_buffer[1024];
+cc_string global_str = String_FromArray(global_buffer);
+
+const cc_string* GetString(void) {
+	return &global_str;
+}
+```
+
+Depending on what functions are called in-between `GetString` and `Chat_Add`, `global_str` or its contents may be modified - which can result in an unexpected value being displayed in chat
+
+This potential issue is not just theoretical - it has actually resulted in several real bugs in ClassiCube itself
+
+As a general rule, for unsafe functions returning a string that may be mutated behind your back, you should try to maintain a reference to the string for as short of time as possible
+
+### Reducing string lifetime issues
+
+In general, for functions that produce strings, you should try to leave the responsibility of managing the string's lifetime up to the calling function to avoid these pitfalls
+
+The example from before could instead be rewritten like so:
+
+```C
+void GetString(cc_string* str);
+
+void PrintSomething(void) {
+	char strBuffer[256];
+	cc_string str = String_InitArray(strBuffer);
+	GetString(&str);
+	
+	// .. other code ..
+	Chat_Add(&str);
+}
+```