SDL.SDL · BlitzMax

Simple DirectMedia Layer is a cross-platform development library designed to provide low level access to audio, keyboard, mouse, joystick, and graphics hardware via OpenGL and Direct3D.

SDL is a wrapper around operating-system-specific functions that a game needs to access.

It provides a common framework for accessing these functions for multiple operating systems (cross-platform). SDL provides support for 2D pixel operations, sound, file access, event handling, timing and threading. It is often used to complement OpenGL by setting up the graphical output an providing mouse and keyboard input, since OpenGL comprises only rendering.

Types

Type	Description
TSDLStream	An SDL-based data stream type.

Structs

Struct	Description
SSDLRect	A rectangle, with the origin at the upper left (integer).

Enums

Enum	Description
ESDLHintPriority	The different hint priorities defined by SDL.

Functions

`Function OpenSDLStream:TSDLStream( file:String, readable:Int, writeMode:Int )`

Opens an SDL stream for reading/writing.

Returns

A stream object.

`Function SDLGetBasePath:String()`

Get the directory where the application was run from.

This is where the application data directory is. This is not necessarily a fast call, though, so you should call this once near startup and save the string if you need it.
Mac OS X and iOS Specific Functionality: If the application is in a ".app" bundle, this function returns the Resource directory (e.g. MyApp.app/Contents/Resources/). This behaviour can be overridden by adding a property to the Info.plist file. Adding a string key with the name SDL_FILESYSTEM_BASE_DIR_TYPE with a supported value will change the behaviour.

`Function SDLGetPrefPath:String(org:String, app:String)`

Returns the preferences dir.

This is meant to be where the application can write personal files (Preferences and save games, etc.) that are specific to the application. This directory is unique per user and per application. The path will be Null if there is a problem (creating directory failed, etc.)
The return path will be guaranteed to end with a path separator ('' on Windows, '/' on most other platforms). You should assume the path returned by this function is the only safe place to write files (and that GetBasePath(), while it might be writable, or even the parent of the returned path, aren't where you should be writing things).
Both the org and app strings may become part of a directory name, so please follow these rules:

Try to use the same org string (including case-sensitivity) for all your applications that use this function.
Always use a unique app string for each one, and make sure it never changes for an app once you've decided on it.
Only use letters, numbers, and spaces. Avoid punctuation like "Game Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient.

`Function SDLAndroidGetExternalStoragePath:String()`

Gets the path used for external storage for this application.

This path is unique to your application, but is public and can be written to by other applications. Your external storage path is typically: /storage/sdcard0/Android/data/your.app.package/files.

Returns

The path used for external storage for this application on success or NULL on failure; call SDLGetError() for more information.

`Function SDLAndroidGetExternalStorageState:Int()`

Gets the current state of external storage.

The current state of external storage, a bitmask of these values: SDL_ANDROID_EXTERNAL_STORAGE_READ, SDL_ANDROID_EXTERNAL_STORAGE_WRITE. If external storage is currently unavailable, this will return 0.

`Function SDLAndroidGetInternalStoragePath:String()`

Gets the path used for internal storage for this application.

This path is unique to your application and cannot be written to by other applications. Your internal storage path is typically: /data/data/your.app.package/files.

Returns

The path used for internal storage or NULL on failure; call SDLGetError() for more information.

`Function SDLGetAndroidSDKVersion:Int()`

Returns the API level of the current device.

`Function SDLIsAndroidTV:Int()`

Returns True if the application is running on Android TV.

`Function SDLIsChromebook:Int()`

Returns True if the application is running on a Chromebook.

`Function SDLIsDeXMode:Int()`

Returns True is the application is running on a Samsung DeX docking station.

`Function SDLAndroidBackButton()`

Triggers the Android system back button behavior.

`Function SDLHasClipboardText:Int()`

Return a flag indicating whether the clipboard exists and contains a text string that is non-empty.

`Function SDLGetClipboardText:String()`

Returns the clipboard text.

`Function SDLSetClipboardText:Int(text:String)`

Puts text into the clipboard.

Returns

0 on success or a negative error code on failure.

`Function SDLLogSetAllPriority(priority:Int)`

Sets the priority of all log categories.

If you are debugging SDL, you might want to call this with SDL_LOG_PRIORITY_WARN.

`Function SDLGetPowerInfo:Int(seconds:Int Var, percent:Int Var)`

Gets the current power supply details.

You should never take a battery status as absolute truth. Batteries (especially failing batteries) are delicate hardware, and the values reported here are best estimates based on what that hardware reports. It's not uncommon for older batteries to lose stored power much faster than it reports, or completely drain when reporting it has 20 percent left, etc. Battery status can change at any time; if you are concerned with power state, you should call this function frequently, and perhaps ignore changes until they seem to be stable for a few seconds.

Returns

One of SDL_POWERSTATE_UNKNOWN, SDL_POWERSTATE_ON_BATTERY, SDL_POWERSTATE_NO_BATTERY, SDL_POWERSTATE_CHARGING, or SDL_POWERSTATE_CHARGED.

`Function SDLGetPixelFormatName:String(format:UInt)`

Gets the human readable name of a pixel format

`Function SDLGetTicks:UInt()`

Gets the number of milliseconds since the SDL library initialization.

This value wraps if the program runs for more than 49 days.

Returns

A value representing the number of milliseconds since the SDL library initialized.

`Function SDLGetError:String()`

Retrieves a message about the last error that occurred.

Returns

A message with information about the specific error that occurred, or an empty string if there hasn't been an error message set since the last call to SDLClearError(). The message is only applicable when an SDL function has signaled an error. You must check the return values of SDL function calls to determine when to appropriately call SDLGetError().

`Function SDLClearError()`

Clears any previous error message.

`Function SDLAudioInit:Int(name:String)`

(re)Initialises the audio subsystem.

`Function SDLGetCPUCount:Int()`

Returns the total number of logical CPU cores.

On CPUs that include technologies such as hyperthreading, the number of logical cores may be more than the number of physical cores.

`Function SDLGetCPUCacheLineSize:Int()`

Returns the L1 cache line size of the CPU.

This is useful for determining multi-threaded structure padding or SIMD prefetch sizes.

`Function SDLHasRDTSC:Int()`

Returns True if the CPU has the RDTSC instruction.

`Function SDLHasAltiVec:Int()`

Returns True if the CPU has AltiVec features.

`Function SDLHasMMX:Int()`

Returns True if the CPU has MMX features.

`Function SDLHas3DNow:Int()`

Returns True if the CPU has 3DNow! features.

`Function SDLHasSSE:Int()`

Returns True if the CPU has SSE features.

`Function SDLHasSSE2:Int()`

Returns True if the CPU has SSE2 features.

`Function SDLHasSSE3:Int()`

Returns True if the CPU has SSE3 features.

`Function SDLHasSSE41:Int()`

Returns True if the CPU has SSE4.1 features.

`Function SDLHasSSE42:Int()`

Returns True if the CPU has SSE4.2 features.

`Function SDLHasAVX:Int()`

Returns True if the CPU has AVX features.

`Function SDLHasAVX2:Int()`

Returns True if the CPU has AVX2 features.

`Function SDLHasAVX512F:Int()`

Returns True if the CPU has AVX-512F (foundation) features.

`Function SDLHasARMSIMD:Int()`

Returns True if the CPU has ARM SIMD (ARMv6) features.

`Function SDLHasNEON:Int()`

Returns True if the CPU has NEON (ARM SIMD) features.

`Function SDLHasLSX:Int()`

Determines whether the CPU has LSX (LOONGARCH SIMD) features.

This always returns False on CPUs that aren't using LOONGARCH instruction sets.

Returns

True if the CPU has LOONGARCH LSX features or False if not.

`Function SDLHasLASX:Int()`

Determines whether the CPU has LASX (LOONGARCH SIMD) features.

This always returns False on CPUs that aren't using LOONGARCH instruction sets.

Returns

True if the CPU has LOONGARCH LASX features or False if not.

`Function SDLIsTablet:Int()`

Returns True if the current device is a tablet.

`Function SDLSetHintWithPriority:Int(name:String, value:string, priority:ESDLHintPriority)`

Returns True if the hint was set.

Consts

`Const SDL_APP_TERMINATING:Int = $101`

The application is being terminated by the OS.

Called on iOS in applicationWillTerminate(). Called on Android in onDestroy()

`Const SDL_APP_LOWMEMORY:Int = $102`

The application is low on memory, free memory if possible.

Called on iOS in applicationDidReceiveMemoryWarning(). Called on Android in onLowMemory()

`Const SDL_APP_WILLENTERBACKGROUND:Int = $103`

The application is about to enter the background.

Called on iOS in applicationWillResignActive(). Called on Android in onPause()

`Const SDL_APP_DIDENTERBACKGROUND:Int = $104`

The application did enter the background and may not get CPU for some time.

Called on iOS in applicationDidEnterBackground(). Called on Android in onPause()

`Const SDL_APP_WILLENTERFOREGROUND:Int = $105`

The application is about to enter the foreground.

Called on iOS in applicationWillEnterForeground(). Called on Android in onResume()

`Const SDL_APP_DIDENTERFOREGROUND:Int = $106`

The application is now interactive.

Called on iOS in applicationDidBecomeActive(). Called on Android in onResume()

`Const SDL_LOG_CATEGORY_APPLICATION:Int = 0`

Application log category.

Has a default log priority of SDL_LOG_PRIORITY_INFO.