jovian / venusian-sdl3

0.8.x-dev 2026-09-18 17:49 UTC

Requires

• php: ^8.4|^8.5|^8.6
• jovian/sdl3: ^0.8.0
• venusian-surface/contracts: ^0.8.0
• venusian-surface/drawing: ^0.8.0
• venusian-surface/human-input: ^0.8.0
• venusian-surface/stage: ^0.8.0
• venusian-voyager/contracts: ^0.8.0
• venusian-voyager/nuts-and-bolts: ^0.8.0

Requires (Dev)

• pestphp/pest: ^4

MIT

• Angel Gonzalez

• framework
• input
• stage
• gpu
• sdl3
• venusian

Published on Packagist.org on 2026-09-18 17:51 UTC

README

SDL3 composition for Venusian Surface. Installing it publishes three container aliases: stage.sdl3, the stage host that mints whole SDL windows an engine owns (and lends that engine a GL context, a CAMetalLayer or a Vulkan surface); gpu.sdl3, the SDL_GPU engine that draws into a stage; and input.sdl3, the input engine that reads keyboard, mouse and gamepads from SDL.

Install

composer require jovian/venusian-sdl3

Example

use Surface\Stage\MagicAliases\Stage;

$stage = Stage::open('main', 'sdl3', 1024, 640, 'sdl3')   // engine, then host
    ->setTitle('Orbit')
    ->show();                                            // stages are minted hidden

Host

SdlStageSession (stage.sdl3) mints both kinds. The provider passes config('stage.cpu_renderer', 'software') (STAGE_CPU_RENDERER) into the session; null lets SDL pick a renderer.

Kind	Session verb	Window	Present
GPU	open / mintStage	SdlStagedWindow	executor into a lent layer (HOST_WINDOW / GL / Metal / Vulkan)
CPU	openCPU / mintCPUStage	SdlCPUStagedWindow	canvas rgba8() — software renderer, streaming RGBA32 texture, StageFit + NEAREST

Both implement RoutableStage so the pump routes by window id. CPU flags are RESIZABLE | HIGH_PIXEL_DENSITY | HIDDEN with no GL / Metal / Vulkan. Canvas size is fixed; a resize rescales.

Input

input.sdl3 (Surface's default input engine) reads keyboard, text and mouse for sdl3 stage windows, and gamepads on every OS with no SDL window needed. Keys are layout-independent scancodes. Every SDL gamepad is a game controller, id sdl3-<instance_id>. The dock polls the engine each tick; a sketch only reads.

• mouse()->window(): the stage under SDL's mouse focus after each poll; null when the pointer is over no stage. Position is the last one reported.
• mouse()->wheel(): dy > 0 = up/away from the user, whatever the OS scroll direction ("natural" scrolling is undone).
• Focus loss: SDL releases held keys itself (key-ups arrive as events).
• Scancode 83 reads Key::NUM_LOCK (SDL's name); the Mac Clear key sends it, so it is NUM_LOCK here and CLEAR on appkit.

use Surface\Contracts\HumanInput\Key;
use Surface\HumanInput\MagicAliases\HumanInput;

$sdl = HumanInput::engine('sdl3');               // connects on first use
$sdl->keyboard()->isPressed(Key::SPACE);
$sdl->mouse()->window();                         // stage name under the pointer, or null
foreach ($sdl->gameControllers() as $id => $pad) {   // $id is 'sdl3-<instance_id>'; SDL ids start at 1
    $pad->leftStick();                           // ['x' => -1…1, 'y' => -1…1], y down = +
}