191 lines
4.6 KiB
Markdown
191 lines
4.6 KiB
Markdown
# 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 ¢erX -int ¢erY -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`.
|