Extend grogs, better example program

grogs/README.md

@@ -1,6 +1,6 @@
 # grogs (Ground graphics) library
 
-This library uses SDL3 to add graphics support to Ground.
+This library uses SDL3 to add graphics support to Ground, including window management, event handling, and simple 2D drawing.
 
 ## Compiling
 
@@ -10,50 +10,181 @@ First, ensure SDL3 is installed on your system. Then:
 g++ -shared -fPIC -lSDL3 -o grogs.so grogs.cpp
 ```
 
+Or with pkg-config:
+
+```bash
+g++ -shared -fPIC $(pkg-config --cflags --libs sdl3) -o grogs.so grogs.cpp
+```
+
 ## Functions
 
-### fun -int !initSDL -string &windowTitle -int &width -int &height
+### Window Management
 
-This function initialises SDL for use in Grogs. **This must be run before trying to run any other Grogs functions!**
+#### `fun -int !initSDL -string &windowTitle -int &width -int &height`
 
-First argument is the window title, second and third are width and height of the window, respectively.
+Initializes SDL and creates a window. **This must be run before any other Grogs functions!**
 
-If everything goes fine, returns 0.
+**Arguments:**
+- `windowTitle`: Title of the window
+- `width`: Window width in pixels
+- `height`: Window height in pixels
 
-If SDL couldn't create the window, returns 1. If already initialized, returns 2.
-
-Example:
+**Returns:**
+- `0`: Success
+- `1`: SDL initialization or window creation failed
+- `2`: Already initialized
 
+**Example:**
 ```
-pusharg "My Awesome Window" 640 480
-!grogs:initSDL &result
+pusharg "My Awesome Window" 800 600
+call !grogs:initSDL &result
 ```
 
-### fun -int !pollEvent
+#### `fun -int !getWindowSize -int &dimension`
 
-Returns a code for an event that has been polled. For now, only window closing is supported, which will return 0. Anything else for now will return -1.
+Gets window dimensions.
 
-### fun -int !clearRenderer
+**Arguments:**
+- `dimension`: `0` for width, `1` for height
 
-Clears the renderer of any pixels to be rendered. Returns 0, unless SDL is not initialized.
+**Returns:** The requested dimension, or `-1` if not initialized.
 
-### fun -int !renderFrame
+#### `fun -int !cleanup`
 
-Renders frame on the screen. Whichever pixels have been set will be displayed. Returns 0, unless SDL is not initialized.
+Properly cleans up SDL resources. Call this before your program exits.
 
-### fun -int !setPixel -int &xpos -int &ypos -int &red -int &green -int &blue
+**Returns:** Always `0`
 
-Sets a pixel at the desired location to the desired colour. Returns 0, unless SDL is not initialized.
+### Event Handling
 
-First argument: xpos
-Second argument: ypos
-Third argument: red value (0 to 255)
-Fourth argument: green value (0 to 255)
-Fifth argument: blue value (0 to 255)
+#### `fun -int !pollEvent`
 
-This example sets the pixel at (10, 10) to white (RGB(255, 255, 255)):
+Polls for SDL events and returns event type codes.
 
+**Returns:**
+- `0`: Quit event (window closed)
+- `1`: Key pressed down
+- `2`: Key released
+- `3`: Mouse button pressed
+- `4`: Mouse button released
+- `5`: Mouse moved
+- `6`: Other event
+- `-1`: No event
+
+#### `fun -int !getLastKey`
+
+Gets the key code of the last key event (after calling `pollEvent`).
+
+**Returns:** SDL key code, or `-1` if no key event or not initialized.
+
+#### `fun -int !getMousePos -int &coord`
+
+Gets current mouse position.
+
+**Arguments:**
+- `coord`: `0` for X coordinate, `1` for Y coordinate
+
+**Returns:** Mouse coordinate, or `-1` if not initialized.
+
+### Rendering
+
+#### `fun -int !clearRenderer [optional: -int &red -int &green -int &blue]`
+
+Clears the renderer. Optionally specify background color.
+
+**Arguments (optional):**
+- `red`: Red value (0-255)
+- `green`: Green value (0-255)
+- `blue`: Blue value (0-255)
+
+**Returns:** `0` on success, `-1` if not initialized.
+
+**Examples:**
 ```
-pusharg 10 10 255 255 255
-call !grogs:setPixel &result
+# Clear to black (default)
+call !grogs:clearRenderer &result
+
+# Clear to blue background
+pusharg 0 100 200
+call !grogs:clearRenderer &result
 ```
+
+#### `fun -int !renderFrame`
+
+Presents the rendered frame to the screen.
+
+**Returns:** `0` on success, `-1` if not initialized.
+
+### Drawing Functions
+
+#### `fun -int !setPixel -int &x -int &y -int &red -int &green -int &blue`
+
+Sets a single pixel to the specified color.
+
+**Arguments:**
+- `x`, `y`: Pixel coordinates
+- `red`, `green`, `blue`: Color values (0-255, automatically clamped)
+
+**Returns:** `0` on success, `-1` if not initialized or out of bounds.
+
+#### `fun -int !drawLine -int &x1 -int &y1 -int &x2 -int &y2 -int &red -int &green -int &blue`
+
+Draws a line between two points.
+
+**Arguments:**
+- `x1`, `y1`: Start point coordinates
+- `x2`, `y2`: End point coordinates
+- `red`, `green`, `blue`: Line color (0-255)
+
+**Returns:** `0` on success, `-1` if not initialized.
+
+#### `fun -int !drawRect -int &x -int &y -int &width -int &height -int &red -int &green -int &blue`
+
+Draws a filled rectangle.
+
+**Arguments:**
+- `x`, `y`: Top-left corner coordinates
+- `width`, `height`: Rectangle dimensions
+- `red`, `green`, `blue`: Fill color (0-255)
+
+**Returns:** `0` on success, `-1` if not initialized or invalid dimensions.
+
+#### `fun -int !drawRectOutline -int &x -int &y -int &width -int &height -int &red -int &green -int &blue`
+
+Draws a rectangle outline (border only).
+
+**Arguments:** Same as `drawRect`
+
+**Returns:** `0` on success, `-1` if not initialized or invalid dimensions.
+
+#### `fun -int !drawCircle -int &centerX -int &centerY -int &radius -int &red -int &green -int &blue`
+
+Draws a filled circle.
+
+**Arguments:**
+- `centerX`, `centerY`: Circle center coordinates
+- `radius`: Circle radius in pixels
+- `red`, `green`, `blue`: Fill color (0-255)
+
+**Returns:** `0` on success, `-1` if not initialized or invalid radius.
+
+### Utility Functions
+
+#### `fun -int !delay -int &milliseconds`
+
+Pauses execution for the specified time. Useful for frame rate control.
+
+**Arguments:**
+- `milliseconds`: Delay duration
+
+**Returns:** `0` on success, `-1` if negative value provided.
+
+## Error Handling
+
+All functions return status codes. Always check return values:
+- `0`: Success
+- `1`: SDL-specific error
+- `2`: Already initialized (initSDL only)
+- `-1`: General error (not initialized, invalid parameters, out of bounds, etc.)
+
+Functions that require SDL to be initialized will print error messages and return `-1` if called before `initSDL`.