NAME
SDL3 - Perl Wrapper for the Simple DirectMedia Layer 3.0
SYNOPSIS
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 { }DESCRIPTION
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.
This is very much still under construction. There are a few examples in this distribution's eg/ directory but a few games and other demos I've written may be found on github: https://github.com/sanko/SDL3.pm-demos.
Features
Each feature listed below is a tag you may use.
:all
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.
:asyncio - Async I/O
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 - Atomic Operations
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 - Audio Playback, Recording, and Mixing
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.
:bits - CategoryBlendmode
Functions for fiddling with bits and bitmasks.
:blendmode - Blend modes
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.
:camera - Camera Support
Video capture for the SDL library.
:clipboard - Clipboard Handling
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.
:cpuinfo - CPU Feature Detection
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.
:dialog - File Dialogs
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.
:error - Error Handling
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().
:events - Event Handling
Event queue management.
:filesystem - Filesystem Access
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.
:gamepad - Gamepad Support
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.
:gpu - 3D Rendering and GPU Compute
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.
:guid - GUIDs
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.
:haptic - Force Feedback Support
The SDL haptic subsystem manages haptic (force feedback) devices.
:hidapi - HIDAPI
HID devices.
:hints - Configuration Variables
Functions to set and get configuration hints, as well as listing each of them alphabetically.
:init - Initialization and Shutdown
All SDL programs need to initialize the library before starting to work with it.
:iostream - I/O Streams
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.
:joystick - Joystick Support
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.
:keyboard - Keyboard Support
SDL keyboard management.
:keycode - Keyboard Keycodes
Defines constants which identify keyboard keys and modifiers.
:loadso - Shared Object/DLL Management
System-dependent library loading routines.
See SDL3: CategorySharedObject
:locale - Locale Info
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.
:log - Log Handling
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.
:main - Application entry points
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.
:messagebox - Message Boxes
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).
:metal - Metal support
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.
:misc - Miscellaneous
SDL API functions that don't fit elsewhere.
:mouse - Mouse Support
Any GUI application has to deal with the mouse, and SDL provides functions to manage mouse input and the displayed cursor.
:mutex - Thread Synchronization Primitives
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.
:pen - Pen Support
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.
:pixels - Pixel Formats and Conversion Routines
SDL offers facilities for pixel management.
:platform - Platform Detection
SDL provides a means to identify the app's platform, both at compile time and runtime.
:power - Power Management Status
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 - Process Control
Process control support.
These functions provide a cross-platform way to spawn and manage OS-level processes.
:properties - Object Properties
A property is a variable that can be created and retrieved by name at runtime.
:rect - Rectangle Functions
Some helper functions for managing rectangles and 2D points, in both integer and floating point versions.
:render - 2D Accelerated Rendering
SDL 2D rendering functions.
:scancode - Keyboard Scancodes
The SDL keyboard scancode representation.
An SDL scancode is the physical representation of a key on the keyboard, independent of language and keyboard mapping.
:sensor - Sensors
SDL sensor management.
These APIs grant access to gyros and accelerometers on various platforms.
:storage - Storage Abstraction
The storage API is a high-level API designed to abstract away the portability issues that come up when using something lower-level.
:surface - Surface Creation and Simple Drawing
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.
:stdinc - Standard Library Functionality
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).
:system - Platform-specific Functionality
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.
:thread - Thread Management
SDL offers cross-platform thread management functions. These are mostly concerned with starting threads, setting their priority, and dealing with their termination.
:time - Date and Time
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.
:timer - Timer Support
SDL provides time management functionality. It is useful for dealing with (usually) small durations of time.
:touch - Touch Support
SDL offers touch input, on platforms that support it. It can manage multiple touch devices and track multiple fingers on those devices.
:tray - System Tray
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.
:version - Querying SDL Version
Functionality to query the current SDL version, both as headers the app was compiled against, and a library the app is linked to.
:video - Display and Window Management
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.
:vulkan - Vulkan Support
Functions for creating Vulkan surfaces on SDL windows.
See Also
The project's repo: https://github.com/Perl-SDL3/SDL3.pm
The SDL3 Wiki: https://wiki.libsdl.org/SDL3/FrontPage
LICENSE
This software is Copyright (c) 2025 by Sanko Robinson <sanko@cpan.org>.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)See the LICENSE file for full text.
AUTHOR
Sanko Robinson <sanko@cpan.org>