libraries/grogs/README.md

# grogs (Ground graphics) library

This library uses SDL3 to add graphics support to Ground, including window management, event handling, and simple 2D drawing.

## Compiling

First, ensure SDL3 is installed on your system. Then:

```bash
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

### Window Management

#### `fun -int !initSDL -string &windowTitle -int &width -int &height`

Initializes SDL and creates a window. **This must be run before any other Grogs functions!**

**Arguments:**
- `windowTitle`: Title of the window
- `width`: Window width in pixels
- `height`: Window height in pixels

**Returns:**
- `0`: Success
- `1`: SDL initialization or window creation failed
- `2`: Already initialized

**Example:**
```
pusharg "My Awesome Window" 800 600
call !grogs:initSDL &result
```

#### `fun -int !getWindowSize -int &dimension`

Gets window dimensions.

**Arguments:**
- `dimension`: `0` for width, `1` for height

**Returns:** The requested dimension, or `-1` if not initialized.

#### `fun -int !cleanup`

Properly cleans up SDL resources. Call this before your program exits.

**Returns:** Always `0`

### Event Handling

#### `fun -int !pollEvent`

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:**
```
# 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`.