PharoSDL3

Pharo Smalltalk bindings for SDL3 (Simple DirectMedia Layer).

SDL3 is a cross-platform development library designed to provide low-level access to audio, keyboard, mouse, joystick, and graphics hardware. It is used by video playback software, emulators, and games.

Installation

1. Load the Pharo project

In a Pharo 14 image, evaluate the following Metacello script:

Metacello new
    baseline: 'SDL3';
    repository: 'github://tinchodias/PharoSDL3:dev/src';
    load

Alternatively, from your terminal:

curl https://get.pharo.org/140+vm | bash
./pharo Pharo.image metacello install --save github://tinchodias/PharoSDL3:dev/src SDL3

2. Install the SDL3 library

Ensure the SDL3 library is available on your system so Pharo's FFI can find it.

• MacOS: brew install sdl3
• Linux: Build from source or use your package manager.
• Windows: Download the DLL from SDL releases and place it in the same folder as your Pharo image.

Demos & Tests

The project includes automated tests as well as interactive demos. These demos complement automated testing by allowing for human verification of visual rendering and event handling.

Important: Pharo's UI and SDL2 (used by default in Pharo 14) conflict with SDL3's event loop in some environments. Therefore, it is recommended to run SDL3 applications in headless mode or ensure proper event handling.

To run tests from the terminal:

./pharo Pharo.image test 'SDL3-Tests'

Available demos:

• Basic Windows: ./pharo Pharo.image eval 'SDL3Demo run01MultipleWindows'
• Events & Input: ./pharo Pharo.image eval 'SDL3Demo run04HandleEvents'
• System Tray: ./pharo Pharo.image eval 'SDL3Demo run08TrayMenu'
• GPU shader effects: ./pharo Pharo.image eval 'SDL3GPURenderStateDemo new run' (Video)
• GPU low-level API: ./pharo Pharo.image eval 'SDL3GPUClearDemo new run'

OSWindow backend

It can be test by:

1. Download Pharo 14 via zeroconf script: curl https://get.pharo.org/140+vm | bash
2. Load this project's baseline
3. Save and Close
4. Run in terminal: PHARO_WINDOW_DRIVER=OSSDL3Driver ./pharo-ui Pharo.image
5. Verify that OSWindowDriver current answers a OSSDL3Driver

Mapping SDL3 Functions to Pharo Methods

The bindings follow a consistent naming convention to map C functions to Pharo methods.

1. Low-level API (LibSDL3)

The LibSDL3 class provides direct access to the C API.

• Prefix Removal: The SDL_ prefix is removed.
• CamelCase: The first letter of the function name is lowercased.
• Keywords: Function parameters are converted into Pharo keywords.

You can browse a mapping table in our wiki with a complete mapping from SDL functions to each Pharo method in LibSDL3.

Examples:

• SDL_Init(flags) maps to LibSDL3 >> init: flags
• SDL_CreateWindow(title, w, h, flags) maps to LibSDL3 >> newWindowTitle:w:h:flags:

2. High-level API (Convenience Methods)

Object-oriented classes like SDL3Window and SDL3Renderer provide more idiomatic Smalltalk methods.

• Accessors: Getter and setter functions are converted to Smalltalk-style accessors by omitting the Get and Set prefixes.
  • SDL_GetWindowFlags(window) maps to SDL3Window >> flags
  • SDL_SetWindowBordered(window, bordered) maps to SDL3Window >> bordered: bordered
• Output Parameters (Into): When a function returns values via pointers (output parameters), the Pharo method typically uses the Into keyword in the selector.
  • SDL_GetWindowSize(window, &w, &h) maps to SDL3Window >> getSizeIntoW:w h:h
  • SDL_GetRenderClipRect(renderer, &rect) maps to SDL3Renderer >> getRenderClipRectInto: rect

You can explore all available functions in the LibSDL3 class or by browsing the object classes. The tables in our wiki page can help, as well.

More Information

• Is this code generated? Yes, it was initially generated with CIG and post-processed manually.
• Wiki: Check the project wiki for post-processing details and technical documentation.

License

This project is licensed under the MIT license.