SDL3 - Perl Wrapper for the Simple DirectMedia Layer 3.0
use v5.40;
use SDL3 qw[:all :main];
my ( $x, $y, $dx, $dy, $ren ) = ( 300, 200, 5, 5 );
sub SDL_AppInit( $app, $ac, $av ) {
state $win;
SDL_Init(SDL_INIT_VIDEO);
SDL_CreateWindowAndRenderer( 'Bouncing Box', 640, 480, 0, \$win, \$ren );
SDL_SetRenderVSync( $ren, 1 );
SDL_APP_CONTINUE;
}
sub SDL_AppEvent( $app, $ev ) {
$ev->{type} == SDL_EVENT_QUIT ? SDL_APP_SUCCESS : SDL_APP_CONTINUE;
}
sub SDL_AppIterate($app) {
$dx *= -1 if $x <= 0 || $x >= 620; # Bounce X (Window 640 - Rect 20)
$dy *= -1 if $y <= 0 || $y >= 460; # Bounce Y (Window 480 - Rect 20)
$x += $dx;
$y += $dy;
SDL_SetRenderDrawColor( $ren, 20, 20, 30, 255 );
SDL_RenderClear($ren);
SDL_SetRenderDrawColor( $ren, int($x) % 255, int($y) % 255, 200, 255 );
SDL_RenderFillRect( $ren, { x => $x, y => $y, w => 20, h => 20 } );
SDL_RenderPresent($ren);
SDL_APP_CONTINUE;
}
sub SDL_AppQuit { }This module provides a Perl wrapper for SDL3, a cross-platform development library designed to provide low level access to audio, keyboard, mouse, joystick, and graphics hardware.
There are a few examples in this distribution's eg/ directory but games and other demos I've written may be found on
github: https://github.com/sanko/SDL3.pm-demos.
Each feature listed below is a tag you may use.
This binds all functions, defines all types, and imports them into your package.
See the SDL3 Wiki for documentation of the hundreds of types and functions you'll have access to with this import tag.
SDL offers a way to perform I/O asynchronously. This allows an app to read or write files without waiting for data to actually transfer; the functions that request I/O never block while the request is fulfilled.
Atomic operations.
IMPORTANT: If you are not an expert in concurrent lockless programming, you should not be using any functions in this file. You should be protecting your data structures with full mutexes instead.
Audio functionality for the SDL library.
All audio in SDL3 revolves around SDL_AudioStream. Whether you want to play or record audio, convert it, stream it,
buffer it, or mix it, you're going to be passing it through an audio stream.
Functions for fiddling with bits and bitmasks.
Blend modes decide how two colors will mix together. There are both standard modes for basic needs and a means to create custom modes, dictating what sort of math to do on what color components.
Video capture for the SDL library.
SDL provides access to the system clipboard, both for reading information from other processes and publishing information of its own.
This is not just text! SDL apps can access and publish data by mimetype.
CPU feature detection for SDL.
These functions are largely concerned with reporting if the system has access to various SIMD instruction sets, but also has other important info to share, such as system RAM size and number of logical CPU cores.
File dialog support.
SDL offers file dialogs, to let users select files with native GUI interfaces. There are "open" dialogs, "save" dialogs, and folder selection dialogs. The app can control some details, such as filtering to specific files, or whether multiple files can be selected by the user.
Note that launching a file dialog is a non-blocking operation; control returns to the app immediately, and a callback is called later (possibly in another thread) when the user makes a choice.
Simple error message routines for SDL.
Most apps will interface with these APIs in exactly one function: when almost any SDL function call reports failure, you can get a human-readable string of the problem from SDL_GetError().
Event queue management.
SDL offers an API for examining and manipulating the system's filesystem. This covers most things one would need to do with directories, except for actual file I/O.
SDL provides a low-level joystick API, which just treats joysticks as an arbitrary pile of buttons, axes, and hat switches. If you're planning to write your own control configuration screen, this can give you a lot of flexibility, but that's a lot of work, and most things that we consider "joysticks" now are actually console-style gamepads. So SDL provides the gamepad API on top of the lower-level joystick functionality.
The GPU API offers a cross-platform way for apps to talk to modern graphics hardware. It offers both 3D graphics and compute support, in the style of Metal, Vulkan, and Direct3D 12.
A GUID is a 128-bit value that represents something that is uniquely identifiable by this value: "globally unique."
SDL provides functions to convert a GUID to/from a string.
The SDL haptic subsystem manages haptic (force feedback) devices.
HID devices.
Functions to set and get configuration hints, as well as listing each of them alphabetically.
All SDL programs need to initialize the library before starting to work with it.
SDL provides an abstract interface for reading and writing data streams. It offers implementations for files, memory, etc, and the app can provide their own implementations, too.
SDL_IOStream is not related to the standard C++ iostream class, other than both are abstract interfaces to read/write data.
SDL joystick support.
This is the lower-level joystick handling. If you want the simpler option, where what each button does is well-defined, you should use the gamepad API instead.
SDL keyboard management.
Defines constants which identify keyboard keys and modifiers.
System-dependent library loading routines.
See SDL3: CategorySharedObject
A struct to provide locale data.
This provides a way to get a list of preferred locales (language plus country) for the user. There is exactly one function: SDL_GetPreferredLocales(), which handles all the heavy lifting, and offers documentation on all the strange ways humans might have configured their language settings.
Simple log messages with priorities and categories. A message's SDL_LogPriority signifies how important the message
is. A message's SDL_LogCategory signifies from what domain it belongs to. Every category has a minimum priority
specified: when a message belongs to that category, it will only be sent out if it has that minimum priority or higher.
This is a special import tag that informs SDL to use its new callback based App system.
You must define SDL_AppInit, SDL_AppEvent, SDL_AppIterate, and SDL_AppQuit in your code.
See eg/hello_world.pl for an example and SDL3: CategoryMain.
SDL offers a simple message box API, which is useful for simple alerts, such as informing the user when something fatal happens at startup without the need to build a UI for it (or informing the user _before_ your UI is ready).
Functions to creating Metal layers and views on SDL windows.
This provides some platform-specific glue for Apple platforms. Most macOS and iOS apps can use SDL without these functions, but this API they can be useful for specific OS-level integration tasks.
SDL API functions that don't fit elsewhere.
Any GUI application has to deal with the mouse, and SDL provides functions to manage mouse input and the displayed cursor.
SDL offers several thread synchronization primitives. This document can't cover the complicated topic of thread safety, but reading up on what each of these primitives are, why they are useful, and how to correctly use them is vital to writing correct and safe multithreaded programs.
SDL pen event handling.
SDL provides an API for pressure-sensitive pen (stylus and/or eraser) handling, e.g., for input and drawing tablets or suitably equipped mobile / tablet devices.
SDL offers facilities for pixel management.
SDL provides a means to identify the app's platform, both at compile time and runtime.
SDL power management routines.
Well, routine.
There is a single function in this category: SDL_GetPowerInfo().
This function is useful for games on the go. This allows an app to know if it's running on a draining battery, which can be useful if the app wants to reduce processing, or perhaps framerate, to extend the duration of the battery's charge. Perhaps the app just wants to show a battery meter when fullscreen, or alert the user when the power is getting extremely low, so they can save their game.
Process control support.
These functions provide a cross-platform way to spawn and manage OS-level processes.
A property is a variable that can be created and retrieved by name at runtime.
Some helper functions for managing rectangles and 2D points, in both integer and floating point versions.
SDL 2D rendering functions.
The SDL keyboard scancode representation.
An SDL scancode is the physical representation of a key on the keyboard, independent of language and keyboard mapping.
SDL sensor management.
These APIs grant access to gyros and accelerometers on various platforms.
The storage API is a high-level API designed to abstract away the portability issues that come up when using something lower-level.
SDL surfaces are buffers of pixels in system RAM. These are useful for passing around and manipulating images that are not stored in GPU memory.
SDL provides its own implementation of some of the most important C runtime functions. Using these functions allows an app to have access to common C functionality without depending on a specific C runtime (or a C runtime at all).
Platform-specific SDL API functions. These are functions that deal with needs of specific operating systems, that didn't make sense to offer as platform-independent, generic APIs.
Most apps can make do without these functions, but they can be useful for integrating with other parts of a specific system, adding platform-specific polish to an app, or solving problems that only affect one target.
SDL offers cross-platform thread management functions. These are mostly concerned with starting threads, setting their priority, and dealing with their termination.
SDL realtime clock and date/time routines.
There are two data types that are used in this category: SDL_Time, which represents the nanoseconds since a specific moment (an "epoch"), and SDL_DateTime, which breaks time down into human-understandable components: years, months, days, hours, etc.
Much of the functionality is involved in converting those two types to other useful forms.
SDL provides time management functionality. It is useful for dealing with (usually) small durations of time.
SDL offers touch input, on platforms that support it. It can manage multiple touch devices and track multiple fingers on those devices.
SDL offers a way to add items to the "system tray" (more correctly called the "notification area" on Windows). On platforms that offer this concept, an SDL app can add a tray icon, submenus, checkboxes, and clickable entries, and register a callback that is fired when the user clicks on these pieces.
Functionality to query the current SDL version, both as headers the app was compiled against, and a library the app is linked to.
SDL's video subsystem is largely interested in abstracting window management from the underlying operating system. You can create windows, manage them in various ways, set them fullscreen, and get events when interesting things happen with them, such as the mouse or keyboard interacting with a window.
Functions for creating Vulkan surfaces on SDL windows.
The project's repo: https://github.com/Perl-SDL3/SDL3.pm
The SDL3 Wiki: https://wiki.libsdl.org/SDL3/FrontPage
This software is Copyright (c) 2025 by Sanko Robinson [email protected].
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)
See the LICENSE file for full text.
Sanko Robinson [email protected]