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:

g++ -shared -fPIC -lSDL3 -o grogs.so grogs.cpp

Or with pkg-config:

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.