ref: 75aa83e890a17ee2bcb27a0d2ca4ed6e3626649e
parent: e16f95d69325033d0207f4399547bdb16af98562
author: Olav Sørensen <olav.sorensen@live.no>
date: Thu Mar 30 11:55:55 EDT 2023
Updates for pt_pal_editor
--- a/pt_pal_editor/make-macos.sh
+++ b/pt_pal_editor/make-macos.sh
@@ -39,7 +39,7 @@
}
echo Compiling x86_64 binary...
-CFLAGS="-target x86_64-apple-macos10.7 -mmacosx-version-min=10.7 -arch x86_64 -mmmx -mfpmath=sse -msse2 -O3"
+CFLAGS="-target x86_64-apple-macos10.9 -mmacosx-version-min=10.9 -arch x86_64 -mmmx -mfpmath=sse -msse2 -O3"
LDFLAGS=
export SDKROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk
compile $TARGET_X86_64
--- a/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL.h
+++ b/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL.h
@@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
- Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@@ -29,37 +29,42 @@
#ifndef SDL_h_
#define SDL_h_
-#include "SDL_main.h"
-#include "SDL_stdinc.h"
-#include "SDL_assert.h"
-#include "SDL_atomic.h"
-#include "SDL_audio.h"
-#include "SDL_clipboard.h"
-#include "SDL_cpuinfo.h"
-#include "SDL_endian.h"
-#include "SDL_error.h"
-#include "SDL_events.h"
-#include "SDL_filesystem.h"
-#include "SDL_gamecontroller.h"
-#include "SDL_haptic.h"
-#include "SDL_hints.h"
-#include "SDL_joystick.h"
-#include "SDL_loadso.h"
-#include "SDL_log.h"
-#include "SDL_messagebox.h"
-#include "SDL_mutex.h"
-#include "SDL_power.h"
-#include "SDL_render.h"
-#include "SDL_rwops.h"
-#include "SDL_sensor.h"
-#include "SDL_shape.h"
-#include "SDL_system.h"
-#include "SDL_thread.h"
-#include "SDL_timer.h"
-#include "SDL_version.h"
-#include "SDL_video.h"
+#include <SDL2/SDL_main.h>
+#include <SDL2/SDL_stdinc.h>
+#include <SDL2/SDL_assert.h>
+#include <SDL2/SDL_atomic.h>
+#include <SDL2/SDL_audio.h>
+#include <SDL2/SDL_clipboard.h>
+#include <SDL2/SDL_cpuinfo.h>
+#include <SDL2/SDL_endian.h>
+#include <SDL2/SDL_error.h>
+#include <SDL2/SDL_events.h>
+#include <SDL2/SDL_filesystem.h>
+#include <SDL2/SDL_gamecontroller.h>
+#include <SDL2/SDL_guid.h>
+#include <SDL2/SDL_haptic.h>
+#include <SDL2/SDL_hidapi.h>
+#include <SDL2/SDL_hints.h>
+#include <SDL2/SDL_joystick.h>
+#include <SDL2/SDL_loadso.h>
+#include <SDL2/SDL_log.h>
+#include <SDL2/SDL_messagebox.h>
+#include <SDL2/SDL_metal.h>
+#include <SDL2/SDL_mutex.h>
+#include <SDL2/SDL_power.h>
+#include <SDL2/SDL_render.h>
+#include <SDL2/SDL_rwops.h>
+#include <SDL2/SDL_sensor.h>
+#include <SDL2/SDL_shape.h>
+#include <SDL2/SDL_system.h>
+#include <SDL2/SDL_thread.h>
+#include <SDL2/SDL_timer.h>
+#include <SDL2/SDL_version.h>
+#include <SDL2/SDL_video.h>
+#include <SDL2/SDL_locale.h>
+#include <SDL2/SDL_misc.h>
-#include "begin_code.h"
+#include <SDL2/begin_code.h>
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {@@ -90,37 +95,130 @@
/* @} */
/**
- * This function initializes the subsystems specified by \c flags
+ * Initialize the SDL library.
+ *
+ * SDL_Init() simply forwards to calling SDL_InitSubSystem(). Therefore, the
+ * two may be used interchangeably. Though for readability of your code
+ * SDL_InitSubSystem() might be preferred.
+ *
+ * The file I/O (for example: SDL_RWFromFile) and threading (SDL_CreateThread)
+ * subsystems are initialized by default. Message boxes
+ * (SDL_ShowSimpleMessageBox) also attempt to work without initializing the
+ * video subsystem, in hopes of being useful in showing an error dialog when
+ * SDL_Init fails. You must specifically initialize other subsystems if you
+ * use them in your application.
+ *
+ * Logging (such as SDL_Log) works without initialization, too.
+ *
+ * `flags` may be any of the following OR'd together:
+ *
+ * - `SDL_INIT_TIMER`: timer subsystem
+ * - `SDL_INIT_AUDIO`: audio subsystem
+ * - `SDL_INIT_VIDEO`: video subsystem; automatically initializes the events
+ * subsystem
+ * - `SDL_INIT_JOYSTICK`: joystick subsystem; automatically initializes the
+ * events subsystem
+ * - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem
+ * - `SDL_INIT_GAMECONTROLLER`: controller subsystem; automatically
+ * initializes the joystick subsystem
+ * - `SDL_INIT_EVENTS`: events subsystem
+ * - `SDL_INIT_EVERYTHING`: all of the above subsystems
+ * - `SDL_INIT_NOPARACHUTE`: compatibility; this flag is ignored
+ *
+ * Subsystem initialization is ref-counted, you must call SDL_QuitSubSystem()
+ * for each SDL_InitSubSystem() to correctly shutdown a subsystem manually (or
+ * call SDL_Quit() to force shutdown). If a subsystem is already loaded then
+ * this call will increase the ref-count and return.
+ *
+ * \param flags subsystem initialization flags
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_InitSubSystem
+ * \sa SDL_Quit
+ * \sa SDL_SetMainReady
+ * \sa SDL_WasInit
*/
extern DECLSPEC int SDLCALL SDL_Init(Uint32 flags);
/**
- * This function initializes specific SDL subsystems
+ * Compatibility function to initialize the SDL library.
*
- * Subsystem initialization is ref-counted, you must call
- * SDL_QuitSubSystem() for each SDL_InitSubSystem() to correctly
- * shutdown a subsystem manually (or call SDL_Quit() to force shutdown).
- * If a subsystem is already loaded then this call will
- * increase the ref-count and return.
+ * In SDL2, this function and SDL_Init() are interchangeable.
+ *
+ * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Init
+ * \sa SDL_Quit
+ * \sa SDL_QuitSubSystem
*/
extern DECLSPEC int SDLCALL SDL_InitSubSystem(Uint32 flags);
/**
- * This function cleans up specific SDL subsystems
+ * Shut down specific SDL subsystems.
+ *
+ * If you start a subsystem using a call to that subsystem's init function
+ * (for example SDL_VideoInit()) instead of SDL_Init() or SDL_InitSubSystem(),
+ * SDL_QuitSubSystem() and SDL_WasInit() will not work. You will need to use
+ * that subsystem's quit function (SDL_VideoQuit()) directly instead. But
+ * generally, you should not be using those functions directly anyhow; use
+ * SDL_Init() instead.
+ *
+ * You still need to call SDL_Quit() even if you close all open subsystems
+ * with SDL_QuitSubSystem().
+ *
+ * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_InitSubSystem
+ * \sa SDL_Quit
*/
extern DECLSPEC void SDLCALL SDL_QuitSubSystem(Uint32 flags);
/**
- * This function returns a mask of the specified subsystems which have
- * previously been initialized.
+ * Get a mask of the specified subsystems which are currently initialized.
*
- * If \c flags is 0, it returns a mask of all initialized subsystems.
+ * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
+ * \returns a mask of all initialized subsystems if `flags` is 0, otherwise it
+ * returns the initialization status of the specified subsystems.
+ *
+ * The return value does not include SDL_INIT_NOPARACHUTE.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Init
+ * \sa SDL_InitSubSystem
*/
extern DECLSPEC Uint32 SDLCALL SDL_WasInit(Uint32 flags);
/**
- * This function cleans up all initialized subsystems. You should
- * call it upon all exit conditions.
+ * Clean up all initialized subsystems.
+ *
+ * You should call this function even if you have already shutdown each
+ * initialized subsystem with SDL_QuitSubSystem(). It is safe to call this
+ * function even in the case of errors in initialization.
+ *
+ * If you start a subsystem using a call to that subsystem's init function
+ * (for example SDL_VideoInit()) instead of SDL_Init() or SDL_InitSubSystem(),
+ * then you must use that subsystem's quit function (SDL_VideoQuit()) to shut
+ * it down before calling SDL_Quit(). But generally, you should not be using
+ * those functions directly anyhow; use SDL_Init() instead.
+ *
+ * You can use this function with atexit() to ensure that it is run when your
+ * application is shutdown, but it is not wise to do this from a library or
+ * other dynamically loaded code.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Init
+ * \sa SDL_QuitSubSystem
*/
extern DECLSPEC void SDLCALL SDL_Quit(void);
@@ -128,7 +226,7 @@
#ifdef __cplusplus
}
#endif
-#include "close_code.h"
+#include <SDL2/close_code.h>
#endif /* SDL_h_ */
--- a/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_assert.h
+++ b/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_assert.h
@@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
- Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@@ -22,9 +22,9 @@
#ifndef SDL_assert_h_
#define SDL_assert_h_
-#include "SDL_config.h"
+#include <SDL2/SDL_stdinc.h>
-#include "begin_code.h"
+#include <SDL2/begin_code.h>
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {@@ -51,8 +51,14 @@
/* Don't include intrin.h here because it contains C++ code */
extern void __cdecl __debugbreak(void);
#define SDL_TriggerBreakpoint() __debugbreak()
+#elif _SDL_HAS_BUILTIN(__builtin_debugtrap)
+ #define SDL_TriggerBreakpoint() __builtin_debugtrap()
#elif ( (!defined(__NACL__)) && ((defined(__GNUC__) || defined(__clang__)) && (defined(__i386__) || defined(__x86_64__))) )
#define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "int $3\n\t" )
+#elif ( defined(__APPLE__) && (defined(__arm64__) || defined(__aarch64__)) ) /* this might work on other ARM targets, but this is a known quantity... */
+ #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "brk #22\n\t" )
+#elif defined(__APPLE__) && defined(__arm__)
+ #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "bkpt #22\n\t" )
#elif defined(__386__) && defined(__WATCOMC__)
#define SDL_TriggerBreakpoint() { _asm { int 0x03 } }#elif defined(HAVE_SIGNAL_H) && !defined(__WATCOMC__)
@@ -65,7 +71,7 @@
#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 supports __func__ as a standard. */
# define SDL_FUNCTION __func__
-#elif ((__GNUC__ >= 2) || defined(_MSC_VER) || defined (__WATCOMC__))
+#elif ((defined(__GNUC__) && (__GNUC__ >= 2)) || defined(_MSC_VER) || defined (__WATCOMC__))
# define SDL_FUNCTION __FUNCTION__
#else
# define SDL_FUNCTION "???"
@@ -185,28 +191,37 @@
#define SDL_assert_always(condition) SDL_enabled_assert(condition)
+/**
+ * A callback that fires when an SDL assertion fails.
+ *
+ * \param data a pointer to the SDL_AssertData structure corresponding to the
+ * current assertion
+ * \param userdata what was passed as `userdata` to SDL_SetAssertionHandler()
+ * \returns an SDL_AssertState value indicating how to handle the failure.
+ */
typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)(
const SDL_AssertData* data, void* userdata);
/**
- * \brief Set an application-defined assertion handler.
+ * Set an application-defined assertion handler.
*
- * This allows an app to show its own assertion UI and/or force the
- * response to an assertion failure. If the app doesn't provide this, SDL
- * will try to do the right thing, popping up a system-specific GUI dialog,
- * and probably minimizing any fullscreen windows.
+ * This function allows an application to show its own assertion UI and/or
+ * force the response to an assertion failure. If the application doesn't
+ * provide this, SDL will try to do the right thing, popping up a
+ * system-specific GUI dialog, and probably minimizing any fullscreen windows.
*
- * This callback may fire from any thread, but it runs wrapped in a mutex, so
- * it will only fire from one thread at a time.
+ * This callback may fire from any thread, but it runs wrapped in a mutex, so
+ * it will only fire from one thread at a time.
*
- * Setting the callback to NULL restores SDL's original internal handler.
+ * This callback is NOT reset to SDL's internal handler upon SDL_Quit()!
*
- * This callback is NOT reset to SDL's internal handler upon SDL_Quit()!
+ * \param handler the SDL_AssertionHandler function to call when an assertion
+ * fails or NULL for the default handler
+ * \param userdata a pointer that is passed to `handler`
*
- * Return SDL_AssertState value of how to handle the assertion failure.
+ * \since This function is available since SDL 2.0.0.
*
- * \param handler Callback function, called when an assertion fails.
- * \param userdata A pointer passed to the callback as-is.
+ * \sa SDL_GetAssertionHandler
*/
extern DECLSPEC void SDLCALL SDL_SetAssertionHandler(
SDL_AssertionHandler handler,
@@ -213,64 +228,84 @@
void *userdata);
/**
- * \brief Get the default assertion handler.
+ * Get the default assertion handler.
*
- * This returns the function pointer that is called by default when an
- * assertion is triggered. This is an internal function provided by SDL,
- * that is used for assertions when SDL_SetAssertionHandler() hasn't been
- * used to provide a different function.
+ * This returns the function pointer that is called by default when an
+ * assertion is triggered. This is an internal function provided by SDL, that
+ * is used for assertions when SDL_SetAssertionHandler() hasn't been used to
+ * provide a different function.
*
- * \return The default SDL_AssertionHandler that is called when an assert triggers.
+ * \returns the default SDL_AssertionHandler that is called when an assert
+ * triggers.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_GetAssertionHandler
*/
extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler(void);
/**
- * \brief Get the current assertion handler.
+ * Get the current assertion handler.
*
- * This returns the function pointer that is called when an assertion is
- * triggered. This is either the value last passed to
- * SDL_SetAssertionHandler(), or if no application-specified function is
- * set, is equivalent to calling SDL_GetDefaultAssertionHandler().
+ * This returns the function pointer that is called when an assertion is
+ * triggered. This is either the value last passed to
+ * SDL_SetAssertionHandler(), or if no application-specified function is set,
+ * is equivalent to calling SDL_GetDefaultAssertionHandler().
*
- * \param puserdata Pointer to a void*, which will store the "userdata"
- * pointer that was passed to SDL_SetAssertionHandler().
- * This value will always be NULL for the default handler.
- * If you don't care about this data, it is safe to pass
- * a NULL pointer to this function to ignore it.
- * \return The SDL_AssertionHandler that is called when an assert triggers.
+ * The parameter `puserdata` is a pointer to a void*, which will store the
+ * "userdata" pointer that was passed to SDL_SetAssertionHandler(). This value
+ * will always be NULL for the default handler. If you don't care about this
+ * data, it is safe to pass a NULL pointer to this function to ignore it.
+ *
+ * \param puserdata pointer which is filled with the "userdata" pointer that
+ * was passed to SDL_SetAssertionHandler()
+ * \returns the SDL_AssertionHandler that is called when an assert triggers.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_SetAssertionHandler
*/
extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetAssertionHandler(void **puserdata);
/**
- * \brief Get a list of all assertion failures.
+ * Get a list of all assertion failures.
*
- * Get all assertions triggered since last call to SDL_ResetAssertionReport(),
- * or the start of the program.
+ * This function gets all assertions triggered since the last call to
+ * SDL_ResetAssertionReport(), or the start of the program.
*
- * The proper way to examine this data looks something like this:
+ * The proper way to examine this data looks something like this:
*
- * <code>
- * const SDL_AssertData *item = SDL_GetAssertionReport();
- * while (item) {- * printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n",- * item->condition, item->function, item->filename,
- * item->linenum, item->trigger_count,
- * item->always_ignore ? "yes" : "no");
- * item = item->next;
- * }
- * </code>
+ * ```c
+ * const SDL_AssertData *item = SDL_GetAssertionReport();
+ * while (item) {+ * printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n",+ * item->condition, item->function, item->filename,
+ * item->linenum, item->trigger_count,
+ * item->always_ignore ? "yes" : "no");
+ * item = item->next;
+ * }
+ * ```
*
- * \return List of all assertions.
- * \sa SDL_ResetAssertionReport
+ * \returns a list of all failed assertions or NULL if the list is empty. This
+ * memory should not be modified or freed by the application.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_ResetAssertionReport
*/
extern DECLSPEC const SDL_AssertData * SDLCALL SDL_GetAssertionReport(void);
/**
- * \brief Reset the list of all assertion failures.
+ * Clear the list of all assertion failures.
*
- * Reset list of all assertions triggered.
+ * This function will clear the list of all assertions triggered up to that
+ * point. Immediately following this call, SDL_GetAssertionReport will return
+ * no items. In addition, any previously-triggered assertions will be reset to
+ * a trigger_count of zero, and their always_ignore state will be false.
*
- * \sa SDL_GetAssertionReport
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetAssertionReport
*/
extern DECLSPEC void SDLCALL SDL_ResetAssertionReport(void);
@@ -284,7 +319,7 @@
#ifdef __cplusplus
}
#endif
-#include "close_code.h"
+#include <SDL2/close_code.h>
#endif /* SDL_assert_h_ */
--- a/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_atomic.h
+++ b/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_atomic.h
@@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
- Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@@ -59,10 +59,10 @@
#ifndef SDL_atomic_h_
#define SDL_atomic_h_
-#include "SDL_stdinc.h"
-#include "SDL_platform.h"
+#include <SDL2/SDL_stdinc.h>
+#include <SDL2/SDL_platform.h>
-#include "begin_code.h"
+#include <SDL2/begin_code.h>
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
@@ -89,25 +89,51 @@
typedef int SDL_SpinLock;
/**
- * \brief Try to lock a spin lock by setting it to a non-zero value.
+ * Try to lock a spin lock by setting it to a non-zero value.
*
- * \param lock Points to the lock.
+ * ***Please note that spinlocks are dangerous if you don't know what you're
+ * doing. Please be careful using any sort of spinlock!***
*
- * \return SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already held.
+ * \param lock a pointer to a lock variable
+ * \returns SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already
+ * held.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AtomicLock
+ * \sa SDL_AtomicUnlock
*/
extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTryLock(SDL_SpinLock *lock);
/**
- * \brief Lock a spin lock by setting it to a non-zero value.
+ * Lock a spin lock by setting it to a non-zero value.
*
- * \param lock Points to the lock.
+ * ***Please note that spinlocks are dangerous if you don't know what you're
+ * doing. Please be careful using any sort of spinlock!***
+ *
+ * \param lock a pointer to a lock variable
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AtomicTryLock
+ * \sa SDL_AtomicUnlock
*/
extern DECLSPEC void SDLCALL SDL_AtomicLock(SDL_SpinLock *lock);
/**
- * \brief Unlock a spin lock by setting it to 0. Always returns immediately
+ * Unlock a spin lock by setting it to 0.
*
- * \param lock Points to the lock.
+ * Always returns immediately.
+ *
+ * ***Please note that spinlocks are dangerous if you don't know what you're
+ * doing. Please be careful using any sort of spinlock!***
+ *
+ * \param lock a pointer to a lock variable
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AtomicLock
+ * \sa SDL_AtomicTryLock
*/
extern DECLSPEC void SDLCALL SDL_AtomicUnlock(SDL_SpinLock *lock);
@@ -126,7 +152,7 @@
/* This is correct for all CPUs when using GCC or Solaris Studio 12.1+. */
#define SDL_CompilerBarrier() __asm__ __volatile__ ("" : : : "memory")#elif defined(__WATCOMC__)
-extern _inline void SDL_CompilerBarrier (void);
+extern __inline void SDL_CompilerBarrier(void);
#pragma aux SDL_CompilerBarrier = "" parm [] modify exact [];
#else
#define SDL_CompilerBarrier() \
@@ -137,20 +163,22 @@
* Memory barriers are designed to prevent reads and writes from being
* reordered by the compiler and being seen out of order on multi-core CPUs.
*
- * A typical pattern would be for thread A to write some data and a flag,
- * and for thread B to read the flag and get the data. In this case you
- * would insert a release barrier between writing the data and the flag,
+ * A typical pattern would be for thread A to write some data and a flag, and
+ * for thread B to read the flag and get the data. In this case you would
+ * insert a release barrier between writing the data and the flag,
* guaranteeing that the data write completes no later than the flag is
- * written, and you would insert an acquire barrier between reading the
- * flag and reading the data, to ensure that all the reads associated
- * with the flag have completed.
+ * written, and you would insert an acquire barrier between reading the flag
+ * and reading the data, to ensure that all the reads associated with the flag
+ * have completed.
*
- * In this pattern you should always see a release barrier paired with
- * an acquire barrier and you should gate the data reads/writes with a
- * single flag variable.
+ * In this pattern you should always see a release barrier paired with an
+ * acquire barrier and you should gate the data reads/writes with a single
+ * flag variable.
*
* For more information on these semantics, take a look at the blog post:
* http://preshing.com/20120913/acquire-and-release-semantics
+ *
+ * \since This function is available since SDL 2.0.6.
*/
extern DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void);
extern DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void);
@@ -209,6 +237,26 @@
#endif
#endif
+/* "REP NOP" is PAUSE, coded for tools that don't know it by that name. */
+#if (defined(__GNUC__) || defined(__clang__)) && (defined(__i386__) || defined(__x86_64__))
+ #define SDL_CPUPauseInstruction() __asm__ __volatile__("pause\n") /* Some assemblers can't do REP NOP, so go with PAUSE. */+#elif (defined(__arm__) && __ARM_ARCH >= 7) || defined(__aarch64__)
+ #define SDL_CPUPauseInstruction() __asm__ __volatile__("yield" ::: "memory")+#elif (defined(__powerpc__) || defined(__powerpc64__))
+ #define SDL_CPUPauseInstruction() __asm__ __volatile__("or 27,27,27");+#elif defined(_MSC_VER) && (defined(_M_IX86) || defined(_M_X64))
+ #define SDL_CPUPauseInstruction() _mm_pause() /* this is actually "rep nop" and not a SIMD instruction. No inline asm in MSVC x86-64! */
+#elif defined(_MSC_VER) && (defined(_M_ARM) || defined(_M_ARM64))
+ #define SDL_CPUPauseInstruction() __yield()
+#elif defined(__WATCOMC__) && defined(__386__)
+ /* watcom assembler rejects PAUSE if CPU < i686, and it refuses REP NOP as an invalid combination. Hardcode the bytes. */
+ extern __inline void SDL_CPUPauseInstruction(void);
+ #pragma aux SDL_CPUPauseInstruction = "db 0f3h,90h"
+#else
+ #define SDL_CPUPauseInstruction()
+#endif
+
+
/**
* \brief A type representing an atomic integer value. It is a struct
* so people don't accidentally use numeric operations on it.
@@ -216,32 +264,73 @@
typedef struct { int value; } SDL_atomic_t;/**
- * \brief Set an atomic variable to a new value if it is currently an old value.
+ * Set an atomic variable to a new value if it is currently an old value.
*
- * \return SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise.
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
*
- * \note If you don't know what this function is for, you shouldn't use it!
-*/
+ * \param a a pointer to an SDL_atomic_t variable to be modified
+ * \param oldval the old value
+ * \param newval the new value
+ * \returns SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AtomicCASPtr
+ * \sa SDL_AtomicGet
+ * \sa SDL_AtomicSet
+ */
extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCAS(SDL_atomic_t *a, int oldval, int newval);
/**
- * \brief Set an atomic variable to a value.
+ * Set an atomic variable to a value.
*
- * \return The previous value of the atomic variable.
+ * This function also acts as a full memory barrier.
+ *
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
+ *
+ * \param a a pointer to an SDL_atomic_t variable to be modified
+ * \param v the desired value
+ * \returns the previous value of the atomic variable.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_AtomicGet
*/
extern DECLSPEC int SDLCALL SDL_AtomicSet(SDL_atomic_t *a, int v);
/**
- * \brief Get the value of an atomic variable
+ * Get the value of an atomic variable.
+ *
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
+ *
+ * \param a a pointer to an SDL_atomic_t variable
+ * \returns the current value of an atomic variable.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_AtomicSet
*/
extern DECLSPEC int SDLCALL SDL_AtomicGet(SDL_atomic_t *a);
/**
- * \brief Add to an atomic variable.
+ * Add to an atomic variable.
*
- * \return The previous value of the atomic variable.
+ * This function also acts as a full memory barrier.
*
- * \note This same style can be used for any number operation
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
+ *
+ * \param a a pointer to an SDL_atomic_t variable to be modified
+ * \param v the desired value to add
+ * \returns the previous value of the atomic variable.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_AtomicDecRef
+ * \sa SDL_AtomicIncRef
*/
extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v);
@@ -263,23 +352,54 @@
#endif
/**
- * \brief Set a pointer to a new value if it is currently an old value.
+ * Set a pointer to a new value if it is currently an old value.
*
- * \return SDL_TRUE if the pointer was set, SDL_FALSE otherwise.
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
*
- * \note If you don't know what this function is for, you shouldn't use it!
-*/
+ * \param a a pointer to a pointer
+ * \param oldval the old pointer value
+ * \param newval the new pointer value
+ * \returns SDL_TRUE if the pointer was set, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AtomicCAS
+ * \sa SDL_AtomicGetPtr
+ * \sa SDL_AtomicSetPtr
+ */
extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCASPtr(void **a, void *oldval, void *newval);
/**
- * \brief Set a pointer to a value atomically.
+ * Set a pointer to a value atomically.
*
- * \return The previous value of the pointer.
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
+ *
+ * \param a a pointer to a pointer
+ * \param v the desired pointer value
+ * \returns the previous value of the pointer.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_AtomicCASPtr
+ * \sa SDL_AtomicGetPtr
*/
extern DECLSPEC void* SDLCALL SDL_AtomicSetPtr(void **a, void* v);
/**
- * \brief Get the value of a pointer atomically.
+ * Get the value of a pointer atomically.
+ *
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
+ *
+ * \param a a pointer to a pointer
+ * \returns the current value of a pointer.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_AtomicCASPtr
+ * \sa SDL_AtomicSetPtr
*/
extern DECLSPEC void* SDLCALL SDL_AtomicGetPtr(void **a);
@@ -288,7 +408,7 @@
}
#endif
-#include "close_code.h"
+#include <SDL2/close_code.h>
#endif /* SDL_atomic_h_ */
--- a/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_audio.h
+++ b/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_audio.h
@@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
- Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@@ -19,6 +19,8 @@
3. This notice may not be removed or altered from any source distribution.
*/
+/* !!! FIXME: several functions in here need Doxygen comments. */
+
/**
* \file SDL_audio.h
*
@@ -28,14 +30,14 @@
#ifndef SDL_audio_h_
#define SDL_audio_h_
-#include "SDL_stdinc.h"
-#include "SDL_error.h"
-#include "SDL_endian.h"
-#include "SDL_mutex.h"
-#include "SDL_thread.h"
-#include "SDL_rwops.h"
+#include <SDL2/SDL_stdinc.h>
+#include <SDL2/SDL_error.h>
+#include <SDL2/SDL_endian.h>
+#include <SDL2/SDL_mutex.h>
+#include <SDL2/SDL_thread.h>
+#include <SDL2/SDL_rwops.h>
-#include "begin_code.h"
+#include <SDL2/begin_code.h>
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {@@ -170,7 +172,7 @@
* 2: FL FR (stereo)
* 3: FL FR LFE (2.1 surround)
* 4: FL FR BL BR (quad)
- * 5: FL FR FC BL BR (quad + center)
+ * 5: FL FR LFE BL BR (4.1 surround)
* 6: FL FR FC LFE SL SR (5.1 surround - last two can also be BL BR)
* 7: FL FR FC LFE BC SL SR (6.1 surround)
* 8: FL FR FC LFE BL BR SL SR (7.1 surround)
@@ -212,9 +214,12 @@
* set both its (buf) field to a pointer that is aligned to 16 bytes, and its
* (len) field to something that's a multiple of 16, if possible.
*/
-#ifdef __GNUC__
+#if defined(__GNUC__) && !defined(__CHERI_PURE_CAPABILITY__)
/* This structure is 84 bytes on 32-bit architectures, make sure GCC doesn't
pad it out to 88 bytes to guarantee ABI compatibility between compilers.
+ This is not a concern on CHERI architectures, where pointers must be stored
+ at aligned locations otherwise they will become invalid, and thus structs
+ containing pointers cannot be packed without giving a warning or error.
vvv
The next time we rev the ABI, make sure to size the ints and add padding.
*/
@@ -248,7 +253,48 @@
* order that they are normally initialized by default.
*/
/* @{ */+
+/**
+ * Use this function to get the number of built-in audio drivers.
+ *
+ * This function returns a hardcoded number. This never returns a negative
+ * value; if there are no drivers compiled into this build of SDL, this
+ * function returns zero. The presence of a driver in this list does not mean
+ * it will function, it just means SDL is capable of interacting with that
+ * interface. For example, a build of SDL might have esound support, but if
+ * there's no esound server available, SDL's esound driver would fail if used.
+ *
+ * By default, SDL tries all drivers, in its preferred order, until one is
+ * found to be usable.
+ *
+ * \returns the number of built-in audio drivers.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetAudioDriver
+ */
extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
+
+/**
+ * Use this function to get the name of a built in audio driver.
+ *
+ * The list of audio drivers is given in the order that they are normally
+ * initialized by default; the drivers that seem more reasonable to choose
+ * first (as far as the SDL developers believe) are earlier in the list.
+ *
+ * The names of drivers are all simple, low-ASCII identifiers, like "alsa",
+ * "coreaudio" or "xaudio2". These never have Unicode characters, and are not
+ * meant to be proper names.
+ *
+ * \param index the index of the audio driver; the value ranges from 0 to
+ * SDL_GetNumAudioDrivers() - 1
+ * \returns the name of the audio driver at the requested index, or NULL if an
+ * invalid index was specified.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetNumAudioDrivers
+ */
extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
/* @} */
@@ -260,60 +306,103 @@
* use. You should normally use SDL_Init() or SDL_InitSubSystem().
*/
/* @{ */+
+/**
+ * Use this function to initialize a particular audio driver.
+ *
+ * This function is used internally, and should not be used unless you have a
+ * specific need to designate the audio driver you want to use. You should
+ * normally use SDL_Init() or SDL_InitSubSystem().
+ *
+ * \param driver_name the name of the desired audio driver
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AudioQuit
+ */
extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
+
+/**
+ * Use this function to shut down audio if you initialized it with
+ * SDL_AudioInit().
+ *
+ * This function is used internally, and should not be used unless you have a
+ * specific need to specify the audio driver you want to use. You should
+ * normally use SDL_Quit() or SDL_QuitSubSystem().
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AudioInit
+ */
extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
/* @} */
/**
- * This function returns the name of the current audio driver, or NULL
- * if no driver has been initialized.
+ * Get the name of the current audio driver.
+ *
+ * The returned string points to internal static memory and thus never becomes
+ * invalid, even if you quit the audio subsystem and initialize a new driver
+ * (although such a case would return a different static string from another
+ * call to this function, of course). As such, you should not modify or free
+ * the returned string.
+ *
+ * \returns the name of the current audio driver or NULL if no driver has been
+ * initialized.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AudioInit
*/
extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
/**
- * This function opens the audio device with the desired parameters, and
- * returns 0 if successful, placing the actual hardware parameters in the
- * structure pointed to by \c obtained. If \c obtained is NULL, the audio
- * data passed to the callback function will be guaranteed to be in the
- * requested format, and will be automatically converted to the hardware
- * audio format if necessary. This function returns -1 if it failed
- * to open the audio device, or couldn't set up the audio thread.
+ * This function is a legacy means of opening the audio device.
*
- * When filling in the desired audio spec structure,
- * - \c desired->freq should be the desired audio frequency in samples-per-
- * second.
- * - \c desired->format should be the desired audio format.
- * - \c desired->samples is the desired size of the audio buffer, in
- * samples. This number should be a power of two, and may be adjusted by
- * the audio driver to a value more suitable for the hardware. Good values
- * seem to range between 512 and 8096 inclusive, depending on the
- * application and CPU speed. Smaller values yield faster response time,
- * but can lead to underflow if the application is doing heavy processing
- * and cannot fill the audio buffer in time. A stereo sample consists of
- * both right and left channels in LR ordering.
- * Note that the number of samples is directly related to time by the
- * following formula: \code ms = (samples*1000)/freq \endcode
- * - \c desired->size is the size in bytes of the audio buffer, and is
- * calculated by SDL_OpenAudio().
- * - \c desired->silence is the value used to set the buffer to silence,
- * and is calculated by SDL_OpenAudio().
- * - \c desired->callback should be set to a function that will be called
- * when the audio device is ready for more data. It is passed a pointer
- * to the audio buffer, and the length in bytes of the audio buffer.
- * This function usually runs in a separate thread, and so you should
- * protect data structures that it accesses by calling SDL_LockAudio()
- * and SDL_UnlockAudio() in your code. Alternately, you may pass a NULL
- * pointer here, and call SDL_QueueAudio() with some frequency, to queue
- * more audio samples to be played (or for capture devices, call
- * SDL_DequeueAudio() with some frequency, to obtain audio samples).
- * - \c desired->userdata is passed as the first parameter to your callback
- * function. If you passed a NULL callback, this value is ignored.
+ * This function remains for compatibility with SDL 1.2, but also because it's
+ * slightly easier to use than the new functions in SDL 2.0. The new, more
+ * powerful, and preferred way to do this is SDL_OpenAudioDevice().
*
- * The audio device starts out playing silence when it's opened, and should
- * be enabled for playing by calling \c SDL_PauseAudio(0) when you are ready
- * for your audio callback function to be called. Since the audio driver
- * may modify the requested size of the audio buffer, you should allocate
- * any local mixing buffers after you open the audio device.
+ * This function is roughly equivalent to:
+ *
+ * ```c
+ * SDL_OpenAudioDevice(NULL, 0, desired, obtained, SDL_AUDIO_ALLOW_ANY_CHANGE);
+ * ```
+ *
+ * With two notable exceptions:
+ *
+ * - If `obtained` is NULL, we use `desired` (and allow no changes), which
+ * means desired will be modified to have the correct values for silence,
+ * etc, and SDL will convert any differences between your app's specific
+ * request and the hardware behind the scenes.
+ * - The return value is always success or failure, and not a device ID, which
+ * means you can only have one device open at a time with this function.
+ *
+ * \param desired an SDL_AudioSpec structure representing the desired output
+ * format. Please refer to the SDL_OpenAudioDevice
+ * documentation for details on how to prepare this structure.
+ * \param obtained an SDL_AudioSpec structure filled in with the actual
+ * parameters, or NULL.
+ * \returns 0 if successful, placing the actual hardware parameters in the
+ * structure pointed to by `obtained`.
+ *
+ * If `obtained` is NULL, the audio data passed to the callback
+ * function will be guaranteed to be in the requested format, and
+ * will be automatically converted to the actual hardware audio
+ * format if necessary. If `obtained` is NULL, `desired` will have
+ * fields modified.
+ *
+ * This function returns a negative error code on failure to open the
+ * audio device or failure to set up the audio thread; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_CloseAudio
+ * \sa SDL_LockAudio
+ * \sa SDL_PauseAudio
+ * \sa SDL_UnlockAudio
*/
extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
SDL_AudioSpec * obtained);
@@ -330,62 +419,262 @@
typedef Uint32 SDL_AudioDeviceID;
/**
- * Get the number of available devices exposed by the current driver.
- * Only valid after a successfully initializing the audio subsystem.
- * Returns -1 if an explicit list of devices can't be determined; this is
- * not an error. For example, if SDL is set up to talk to a remote audio
- * server, it can't list every one available on the Internet, but it will
- * still allow a specific host to be specified to SDL_OpenAudioDevice().
+ * Get the number of built-in audio devices.
*
- * In many common cases, when this function returns a value <= 0, it can still
- * successfully open the default device (NULL for first argument of
- * SDL_OpenAudioDevice()).
+ * This function is only valid after successfully initializing the audio
+ * subsystem.
+ *
+ * Note that audio capture support is not implemented as of SDL 2.0.4, so the
+ * `iscapture` parameter is for future expansion and should always be zero for
+ * now.
+ *
+ * This function will return -1 if an explicit list of devices can't be
+ * determined. Returning -1 is not an error. For example, if SDL is set up to
+ * talk to a remote audio server, it can't list every one available on the
+ * Internet, but it will still allow a specific host to be specified in
+ * SDL_OpenAudioDevice().
+ *
+ * In many common cases, when this function returns a value <= 0, it can still
+ * successfully open the default device (NULL for first argument of
+ * SDL_OpenAudioDevice()).
+ *
+ * This function may trigger a complete redetect of available hardware. It
+ * should not be called for each iteration of a loop, but rather once at the
+ * start of a loop:
+ *
+ * ```c
+ * // Don't do this:
+ * for (int i = 0; i < SDL_GetNumAudioDevices(0); i++)
+ *
+ * // do this instead:
+ * const int count = SDL_GetNumAudioDevices(0);
+ * for (int i = 0; i < count; ++i) { do_something_here(); }+ * ```
+ *
+ * \param iscapture zero to request playback devices, non-zero to request
+ * recording devices
+ * \returns the number of available devices exposed by the current driver or
+ * -1 if an explicit list of devices can't be determined. A return
+ * value of -1 does not necessarily mean an error condition.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetAudioDeviceName
+ * \sa SDL_OpenAudioDevice
*/
extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
/**
- * Get the human-readable name of a specific audio device.
- * Must be a value between 0 and (number of audio devices-1).
- * Only valid after a successfully initializing the audio subsystem.
- * The values returned by this function reflect the latest call to
- * SDL_GetNumAudioDevices(); recall that function to redetect available
- * hardware.
+ * Get the human-readable name of a specific audio device.
*
- * The string returned by this function is UTF-8 encoded, read-only, and
- * managed internally. You are not to free it. If you need to keep the
- * string for any length of time, you should make your own copy of it, as it
- * will be invalid next time any of several other SDL functions is called.
+ * This function is only valid after successfully initializing the audio
+ * subsystem. The values returned by this function reflect the latest call to
+ * SDL_GetNumAudioDevices(); re-call that function to redetect available
+ * hardware.
+ *
+ * The string returned by this function is UTF-8 encoded, read-only, and
+ * managed internally. You are not to free it. If you need to keep the string
+ * for any length of time, you should make your own copy of it, as it will be
+ * invalid next time any of several other SDL functions are called.
+ *
+ * \param index the index of the audio device; valid values range from 0 to
+ * SDL_GetNumAudioDevices() - 1
+ * \param iscapture non-zero to query the list of recording devices, zero to
+ * query the list of output devices.
+ * \returns the name of the audio device at the requested index, or NULL on
+ * error.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetNumAudioDevices
+ * \sa SDL_GetDefaultAudioInfo
*/
extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index,
int iscapture);
+/**
+ * Get the preferred audio format of a specific audio device.
+ *
+ * This function is only valid after a successfully initializing the audio
+ * subsystem. The values returned by this function reflect the latest call to
+ * SDL_GetNumAudioDevices(); re-call that function to redetect available
+ * hardware.
+ *
+ * `spec` will be filled with the sample rate, sample format, and channel
+ * count.
+ *
+ * \param index the index of the audio device; valid values range from 0 to
+ * SDL_GetNumAudioDevices() - 1
+ * \param iscapture non-zero to query the list of recording devices, zero to
+ * query the list of output devices.
+ * \param spec The SDL_AudioSpec to be initialized by this function.
+ * \returns 0 on success, nonzero on error
+ *
+ * \since This function is available since SDL 2.0.16.
+ *
+ * \sa SDL_GetNumAudioDevices
+ * \sa SDL_GetDefaultAudioInfo
+ */
+extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
+ int iscapture,
+ SDL_AudioSpec *spec);
+
/**
- * Open a specific audio device. Passing in a device name of NULL requests
- * the most reasonable default (and is equivalent to calling SDL_OpenAudio()).
+ * Get the name and preferred format of the default audio device.
*
- * The device name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but
- * some drivers allow arbitrary and driver-specific strings, such as a
- * hostname/IP address for a remote audio server, or a filename in the
- * diskaudio driver.
+ * Some (but not all!) platforms have an isolated mechanism to get information
+ * about the "default" device. This can actually be a completely different
+ * device that's not in the list you get from SDL_GetAudioDeviceSpec(). It can
+ * even be a network address! (This is discussed in SDL_OpenAudioDevice().)
*
- * \return 0 on error, a valid device ID that is >= 2 on success.
+ * As a result, this call is not guaranteed to be performant, as it can query
+ * the sound server directly every time, unlike the other query functions. You
+ * should call this function sparingly!
*
- * SDL_OpenAudio(), unlike this function, always acts on device ID 1.
+ * `spec` will be filled with the sample rate, sample format, and channel
+ * count, if a default device exists on the system. If `name` is provided,
+ * will be filled with either a dynamically-allocated UTF-8 string or NULL.
+ *
+ * \param name A pointer to be filled with the name of the default device (can
+ * be NULL). Please call SDL_free() when you are done with this
+ * pointer!
+ * \param spec The SDL_AudioSpec to be initialized by this function.
+ * \param iscapture non-zero to query the default recording device, zero to
+ * query the default output device.
+ * \returns 0 on success, nonzero on error
+ *
+ * \since This function is available since SDL 2.24.0.
+ *
+ * \sa SDL_GetAudioDeviceName
+ * \sa SDL_GetAudioDeviceSpec
+ * \sa SDL_OpenAudioDevice
*/
-extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char
- *device,
- int iscapture,
- const
- SDL_AudioSpec *
- desired,
- SDL_AudioSpec *
- obtained,
- int
- allowed_changes);
+extern DECLSPEC int SDLCALL SDL_GetDefaultAudioInfo(char **name,
+ SDL_AudioSpec *spec,
+ int iscapture);
+/**
+ * Open a specific audio device.
+ *
+ * SDL_OpenAudio(), unlike this function, always acts on device ID 1. As such,
+ * this function will never return a 1 so as not to conflict with the legacy
+ * function.
+ *
+ * Please note that SDL 2.0 before 2.0.5 did not support recording; as such,
+ * this function would fail if `iscapture` was not zero. Starting with SDL
+ * 2.0.5, recording is implemented and this value can be non-zero.
+ *
+ * Passing in a `device` name of NULL requests the most reasonable default
+ * (and is equivalent to what SDL_OpenAudio() does to choose a device). The
+ * `device` name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but
+ * some drivers allow arbitrary and driver-specific strings, such as a
+ * hostname/IP address for a remote audio server, or a filename in the
+ * diskaudio driver.
+ *
+ * An opened audio device starts out paused, and should be enabled for playing
+ * by calling SDL_PauseAudioDevice(devid, 0) when you are ready for your audio
+ * callback function to be called. Since the audio driver may modify the
+ * requested size of the audio buffer, you should allocate any local mixing
+ * buffers after you open the audio device.
+ *
+ * The audio callback runs in a separate thread in most cases; you can prevent
+ * race conditions between your callback and other threads without fully
+ * pausing playback with SDL_LockAudioDevice(). For more information about the
+ * callback, see SDL_AudioSpec.
+ *
+ * Managing the audio spec via 'desired' and 'obtained':
+ *
+ * When filling in the desired audio spec structure:
+ *
+ * - `desired->freq` should be the frequency in sample-frames-per-second (Hz).
+ * - `desired->format` should be the audio format (`AUDIO_S16SYS`, etc).
+ * - `desired->samples` is the desired size of the audio buffer, in _sample
+ * frames_ (with stereo output, two samples--left and right--would make a
+ * single sample frame). This number should be a power of two, and may be
+ * adjusted by the audio driver to a value more suitable for the hardware.
+ * Good values seem to range between 512 and 8096 inclusive, depending on
+ * the application and CPU speed. Smaller values reduce latency, but can
+ * lead to underflow if the application is doing heavy processing and cannot
+ * fill the audio buffer in time. Note that the number of sample frames is
+ * directly related to time by the following formula: `ms =
+ * (sampleframes*1000)/freq`
+ * - `desired->size` is the size in _bytes_ of the audio buffer, and is
+ * calculated by SDL_OpenAudioDevice(). You don't initialize this.
+ * - `desired->silence` is the value used to set the buffer to silence, and is
+ * calculated by SDL_OpenAudioDevice(). You don't initialize this.
+ * - `desired->callback` should be set to a function that will be called when
+ * the audio device is ready for more data. It is passed a pointer to the
+ * audio buffer, and the length in bytes of the audio buffer. This function
+ * usually runs in a separate thread, and so you should protect data
+ * structures that it accesses by calling SDL_LockAudioDevice() and
+ * SDL_UnlockAudioDevice() in your code. Alternately, you may pass a NULL
+ * pointer here, and call SDL_QueueAudio() with some frequency, to queue
+ * more audio samples to be played (or for capture devices, call
+ * SDL_DequeueAudio() with some frequency, to obtain audio samples).
+ * - `desired->userdata` is passed as the first parameter to your callback
+ * function. If you passed a NULL callback, this value is ignored.
+ *
+ * `allowed_changes` can have the following flags OR'd together:
+ *
+ * - `SDL_AUDIO_ALLOW_FREQUENCY_CHANGE`
+ * - `SDL_AUDIO_ALLOW_FORMAT_CHANGE`
+ * - `SDL_AUDIO_ALLOW_CHANNELS_CHANGE`
+ * - `SDL_AUDIO_ALLOW_SAMPLES_CHANGE`
+ * - `SDL_AUDIO_ALLOW_ANY_CHANGE`
+ *
+ * These flags specify how SDL should behave when a device cannot offer a
+ * specific feature. If the application requests a feature that the hardware
+ * doesn't offer, SDL will always try to get the closest equivalent.
+ *
+ * For example, if you ask for float32 audio format, but the sound card only
+ * supports int16, SDL will set the hardware to int16. If you had set
+ * SDL_AUDIO_ALLOW_FORMAT_CHANGE, SDL will change the format in the `obtained`
+ * structure. If that flag was *not* set, SDL will prepare to convert your
+ * callback's float32 audio to int16 before feeding it to the hardware and
+ * will keep the originally requested format in the `obtained` structure.
+ *
+ * The resulting audio specs, varying depending on hardware and on what
+ * changes were allowed, will then be written back to `obtained`.
+ *
+ * If your application can only handle one specific data format, pass a zero
+ * for `allowed_changes` and let SDL transparently handle any differences.
+ *
+ * \param device a UTF-8 string reported by SDL_GetAudioDeviceName() or a
+ * driver-specific name as appropriate. NULL requests the most
+ * reasonable default device.
+ * \param iscapture non-zero to specify a device should be opened for
+ * recording, not playback
+ * \param desired an SDL_AudioSpec structure representing the desired output
+ * format; see SDL_OpenAudio() for more information
+ * \param obtained an SDL_AudioSpec structure filled in with the actual output
+ * format; see SDL_OpenAudio() for more information
+ * \param allowed_changes 0, or one or more flags OR'd together
+ * \returns a valid device ID that is > 0 on success or 0 on failure; call
+ * SDL_GetError() for more information.
+ *
+ * For compatibility with SDL 1.2, this will never return 1, since
+ * SDL reserves that ID for the legacy SDL_OpenAudio() function.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_CloseAudioDevice
+ * \sa SDL_GetAudioDeviceName
+ * \sa SDL_LockAudioDevice
+ * \sa SDL_OpenAudio
+ * \sa SDL_PauseAudioDevice
+ * \sa SDL_UnlockAudioDevice
+ */
+extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(
+ const char *device,
+ int iscapture,
+ const SDL_AudioSpec *desired,
+ SDL_AudioSpec *obtained,
+ int allowed_changes);
+
+
/**
* \name Audio state
*
@@ -398,10 +687,39 @@
SDL_AUDIO_PLAYING,
SDL_AUDIO_PAUSED
} SDL_AudioStatus;
+
+/**
+ * This function is a legacy means of querying the audio device.
+ *
+ * New programs might want to use SDL_GetAudioDeviceStatus() instead. This
+ * function is equivalent to calling...
+ *
+ * ```c
+ * SDL_GetAudioDeviceStatus(1);
+ * ```
+ *
+ * ...and is only useful if you used the legacy SDL_OpenAudio() function.
+ *
+ * \returns the SDL_AudioStatus of the audio device opened by SDL_OpenAudio().
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetAudioDeviceStatus
+ */
extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void);
-extern DECLSPEC SDL_AudioStatus SDLCALL
-SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
+/**
+ * Use this function to get the current audio state of an audio device.
+ *
+ * \param dev the ID of an audio device previously opened with
+ * SDL_OpenAudioDevice()
+ * \returns the SDL_AudioStatus of the specified audio device.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_PauseAudioDevice
+ */
+extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
/* @} *//* Audio State */
/**
@@ -414,62 +732,140 @@
* Silence will be written to the audio device during the pause.
*/
/* @{ */+
+/**
+ * This function is a legacy means of pausing the audio device.
+ *
+ * New programs might want to use SDL_PauseAudioDevice() instead. This
+ * function is equivalent to calling...
+ *
+ * ```c
+ * SDL_PauseAudioDevice(1, pause_on);
+ * ```
+ *
+ * ...and is only useful if you used the legacy SDL_OpenAudio() function.
+ *
+ * \param pause_on non-zero to pause, 0 to unpause
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetAudioStatus
+ * \sa SDL_PauseAudioDevice
+ */
extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
+
+/**
+ * Use this function to pause and unpause audio playback on a specified
+ * device.
+ *
+ * This function pauses and unpauses the audio callback processing for a given
+ * device. Newly-opened audio devices start in the paused state, so you must
+ * call this function with **pause_on**=0 after opening the specified audio
+ * device to start playing sound. This allows you to safely initialize data
+ * for your callback function after opening the audio device. Silence will be
+ * written to the audio device while paused, and the audio callback is
+ * guaranteed to not be called. Pausing one device does not prevent other
+ * unpaused devices from running their callbacks.
+ *
+ * Pausing state does not stack; even if you pause a device several times, a
+ * single unpause will start the device playing again, and vice versa. This is
+ * different from how SDL_LockAudioDevice() works.
+ *
+ * If you just need to protect a few variables from race conditions vs your
+ * callback, you shouldn't pause the audio device, as it will lead to dropouts
+ * in the audio playback. Instead, you should use SDL_LockAudioDevice().
+ *
+ * \param dev a device opened by SDL_OpenAudioDevice()
+ * \param pause_on non-zero to pause, 0 to unpause
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LockAudioDevice
+ */
extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
int pause_on);
/* @} *//* Pause audio functions */
/**
- * \brief Load the audio data of a WAVE file into memory
+ * Load the audio data of a WAVE file into memory.
*
- * Loading a WAVE file requires \c src, \c spec, \c audio_buf and \c audio_len
- * to be valid pointers. The entire data portion of the file is then loaded
- * into memory and decoded if necessary.
+ * Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len` to
+ * be valid pointers. The entire data portion of the file is then loaded into
+ * memory and decoded if necessary.
*
- * If \c freesrc is non-zero, the data source gets automatically closed and
- * freed before the function returns.
+ * If `freesrc` is non-zero, the data source gets automatically closed and
+ * freed before the function returns.
*
- * Supported are RIFF WAVE files with the formats PCM (8, 16, 24, and 32 bits),
- * IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and A-law and
- * µ-law (8 bits). Other formats are currently unsupported and cause an error.
+ * Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and
+ * 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and
+ * A-law and mu-law (8 bits). Other formats are currently unsupported and
+ * cause an error.
*
- * If this function succeeds, the pointer returned by it is equal to \c spec
- * and the pointer to the audio data allocated by the function is written to
- * \c audio_buf and its length in bytes to \c audio_len. The \ref SDL_AudioSpec
- * members \c freq, \c channels, and \c format are set to the values of the
- * audio data in the buffer. The \c samples member is set to a sane default and
- * all others are set to zero.
+ * If this function succeeds, the pointer returned by it is equal to `spec`
+ * and the pointer to the audio data allocated by the function is written to
+ * `audio_buf` and its length in bytes to `audio_len`. The SDL_AudioSpec
+ * members `freq`, `channels`, and `format` are set to the values of the audio
+ * data in the buffer. The `samples` member is set to a sane default and all
+ * others are set to zero.
*
- * It's necessary to use SDL_FreeWAV() to free the audio data returned in
- * \c audio_buf when it is no longer used.
+ * It's necessary to use SDL_FreeWAV() to free the audio data returned in
+ * `audio_buf` when it is no longer used.
*
- * Because of the underspecification of the Waveform format, there are many
- * problematic files in the wild that cause issues with strict decoders. To
- * provide compatibility with these files, this decoder is lenient in regards
- * to the truncation of the file, the fact chunk, and the size of the RIFF
- * chunk. The hints SDL_HINT_WAVE_RIFF_CHUNK_SIZE, SDL_HINT_WAVE_TRUNCATION,
- * and SDL_HINT_WAVE_FACT_CHUNK can be used to tune the behavior of the
- * loading process.
+ * Because of the underspecification of the .WAV format, there are many
+ * problematic files in the wild that cause issues with strict decoders. To
+ * provide compatibility with these files, this decoder is lenient in regards
+ * to the truncation of the file, the fact chunk, and the size of the RIFF
+ * chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`,
+ * `SDL_HINT_WAVE_TRUNCATION`, and `SDL_HINT_WAVE_FACT_CHUNK` can be used to
+ * tune the behavior of the loading process.
*
- * Any file that is invalid (due to truncation, corruption, or wrong values in
- * the headers), too big, or unsupported causes an error. Additionally, any
- * critical I/O error from the data source will terminate the loading process
- * with an error. The function returns NULL on error and in all cases (with the
- * exception of \c src being NULL), an appropriate error message will be set.
+ * Any file that is invalid (due to truncation, corruption, or wrong values in
+ * the headers), too big, or unsupported causes an error. Additionally, any
+ * critical I/O error from the data source will terminate the loading process
+ * with an error. The function returns NULL on error and in all cases (with
+ * the exception of `src` being NULL), an appropriate error message will be
+ * set.
*
- * It is required that the data source supports seeking.
+ * It is required that the data source supports seeking.
*
- * Example:
- * \code
- * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);- * \endcode
+ * Example:
*
- * \param src The data source with the WAVE data
- * \param freesrc A integer value that makes the function close the data source if non-zero
- * \param spec A pointer filled with the audio format of the audio data
- * \param audio_buf A pointer filled with the audio data allocated by the function
- * \param audio_len A pointer filled with the length of the audio data buffer in bytes
- * \return NULL on error, or non-NULL on success.
+ * ```c
+ * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, &spec, &buf, &len);+ * ```
+ *
+ * Note that the SDL_LoadWAV macro does this same thing for you, but in a less
+ * messy way:
+ *
+ * ```c
+ * SDL_LoadWAV("sample.wav", &spec, &buf, &len);+ * ```
+ *
+ * \param src The data source for the WAVE data
+ * \param freesrc If non-zero, SDL will _always_ free the data source
+ * \param spec An SDL_AudioSpec that will be filled in with the wave file's
+ * format details
+ * \param audio_buf A pointer filled with the audio data, allocated by the
+ * function.
+ * \param audio_len A pointer filled with the length of the audio data buffer
+ * in bytes
+ * \returns This function, if successfully called, returns `spec`, which will
+ * be filled with the audio data format of the wave source data.
+ * `audio_buf` will be filled with a pointer to an allocated buffer
+ * containing the audio data, and `audio_len` is filled with the
+ * length of that audio buffer in bytes.
+ *
+ * This function returns NULL if the .WAV file cannot be opened, uses
+ * an unknown data format, or is corrupt; call SDL_GetError() for
+ * more information.
+ *
+ * When the application is done with the data returned in
+ * `audio_buf`, it should call SDL_FreeWAV() to dispose of it.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_FreeWAV
+ * \sa SDL_LoadWAV
*/
extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
int freesrc,
@@ -485,18 +881,53 @@
SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
/**
- * This function frees data previously allocated with SDL_LoadWAV_RW()
+ * Free data previously allocated with SDL_LoadWAV() or SDL_LoadWAV_RW().
+ *
+ * After a WAVE file has been opened with SDL_LoadWAV() or SDL_LoadWAV_RW()
+ * its data can eventually be freed with SDL_FreeWAV(). It is safe to call
+ * this function with a NULL pointer.
+ *
+ * \param audio_buf a pointer to the buffer created by SDL_LoadWAV() or
+ * SDL_LoadWAV_RW()
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LoadWAV
+ * \sa SDL_LoadWAV_RW
*/
extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf);
/**
- * This function takes a source format and rate and a destination format
- * and rate, and initializes the \c cvt structure with information needed
- * by SDL_ConvertAudio() to convert a buffer of audio data from one format
- * to the other. An unsupported format causes an error and -1 will be returned.
+ * Initialize an SDL_AudioCVT structure for conversion.
*
- * \return 0 if no conversion is needed, 1 if the audio filter is set up,
- * or -1 on error.
+ * Before an SDL_AudioCVT structure can be used to convert audio data it must
+ * be initialized with source and destination information.
+ *
+ * This function will zero out every field of the SDL_AudioCVT, so it must be
+ * called before the application fills in the final buffer information.
+ *
+ * Once this function has returned successfully, and reported that a
+ * conversion is necessary, the application fills in the rest of the fields in
+ * SDL_AudioCVT, now that it knows how large a buffer it needs to allocate,
+ * and then can call SDL_ConvertAudio() to complete the conversion.
+ *
+ * \param cvt an SDL_AudioCVT structure filled in with audio conversion
+ * information
+ * \param src_format the source format of the audio data; for more info see
+ * SDL_AudioFormat
+ * \param src_channels the number of channels in the source
+ * \param src_rate the frequency (sample-frames-per-second) of the source
+ * \param dst_format the destination format of the audio data; for more info
+ * see SDL_AudioFormat
+ * \param dst_channels the number of channels in the destination
+ * \param dst_rate the frequency (sample-frames-per-second) of the destination
+ * \returns 1 if the audio filter is prepared, 0 if no conversion is needed,
+ * or a negative error code on failure; call SDL_GetError() for more
+ * information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_ConvertAudio
*/
extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
SDL_AudioFormat src_format,
@@ -507,16 +938,42 @@
int dst_rate);
/**
- * Once you have initialized the \c cvt structure using SDL_BuildAudioCVT(),
- * created an audio buffer \c cvt->buf, and filled it with \c cvt->len bytes of
- * audio data in the source format, this function will convert it in-place
- * to the desired format.
+ * Convert audio data to a desired audio format.
*
- * The data conversion may expand the size of the audio data, so the buffer
- * \c cvt->buf should be allocated after the \c cvt structure is initialized by
- * SDL_BuildAudioCVT(), and should be \c cvt->len*cvt->len_mult bytes long.
+ * This function does the actual audio data conversion, after the application
+ * has called SDL_BuildAudioCVT() to prepare the conversion information and
+ * then filled in the buffer details.
*
- * \return 0 on success or -1 if \c cvt->buf is NULL.
+ * Once the application has initialized the `cvt` structure using
+ * SDL_BuildAudioCVT(), allocated an audio buffer and filled it with audio
+ * data in the source format, this function will convert the buffer, in-place,
+ * to the desired format.
+ *
+ * The data conversion may go through several passes; any given pass may
+ * possibly temporarily increase the size of the data. For example, SDL might
+ * expand 16-bit data to 32 bits before resampling to a lower frequency,
+ * shrinking the data size after having grown it briefly. Since the supplied
+ * buffer will be both the source and destination, converting as necessary
+ * in-place, the application must allocate a buffer that will fully contain
+ * the data during its largest conversion pass. After SDL_BuildAudioCVT()
+ * returns, the application should set the `cvt->len` field to the size, in
+ * bytes, of the source data, and allocate a buffer that is `cvt->len *
+ * cvt->len_mult` bytes long for the `buf` field.
+ *
+ * The source data should be copied into this buffer before the call to
+ * SDL_ConvertAudio(). Upon successful return, this buffer will contain the
+ * converted audio, and `cvt->len_cvt` will be the size of the converted data,
+ * in bytes. Any bytes in the buffer past `cvt->len_cvt` are undefined once
+ * this function returns.
+ *
+ * \param cvt an SDL_AudioCVT structure that was previously set up by
+ * SDL_BuildAudioCVT().
+ * \returns 0 if the conversion was completed successfully or a negative error
+ * code on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_BuildAudioCVT
*/
extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt);
@@ -532,22 +989,24 @@
typedef struct _SDL_AudioStream SDL_AudioStream;
/**
- * Create a new audio stream
+ * Create a new audio stream.
*
- * \param src_format The format of the source audio
- * \param src_channels The number of channels of the source audio
- * \param src_rate The sampling rate of the source audio
- * \param dst_format The format of the desired audio output
- * \param dst_channels The number of channels of the desired audio output
- * \param dst_rate The sampling rate of the desired audio output
- * \return 0 on success, or -1 on error.
+ * \param src_format The format of the source audio
+ * \param src_channels The number of channels of the source audio
+ * \param src_rate The sampling rate of the source audio
+ * \param dst_format The format of the desired audio output
+ * \param dst_channels The number of channels of the desired audio output
+ * \param dst_rate The sampling rate of the desired audio output
+ * \returns 0 on success, or -1 on error.
*
- * \sa SDL_AudioStreamPut
- * \sa SDL_AudioStreamGet
- * \sa SDL_AudioStreamAvailable
- * \sa SDL_AudioStreamFlush
- * \sa SDL_AudioStreamClear
- * \sa SDL_FreeAudioStream
+ * \since This function is available since SDL 2.0.7.
+ *
+ * \sa SDL_AudioStreamPut
+ * \sa SDL_AudioStreamGet
+ * \sa SDL_AudioStreamAvailable
+ * \sa SDL_AudioStreamFlush
+ * \sa SDL_AudioStreamClear
+ * \sa SDL_FreeAudioStream
*/
extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioFormat src_format,
const Uint8 src_channels,
@@ -557,80 +1016,91 @@
const int dst_rate);
/**
- * Add data to be converted/resampled to the stream
+ * Add data to be converted/resampled to the stream.
*
- * \param stream The stream the audio data is being added to
- * \param buf A pointer to the audio data to add
- * \param len The number of bytes to write to the stream
- * \return 0 on success, or -1 on error.
+ * \param stream The stream the audio data is being added to
+ * \param buf A pointer to the audio data to add
+ * \param len The number of bytes to write to the stream
+ * \returns 0 on success, or -1 on error.
*
- * \sa SDL_NewAudioStream
- * \sa SDL_AudioStreamGet
- * \sa SDL_AudioStreamAvailable
- * \sa SDL_AudioStreamFlush
- * \sa SDL_AudioStreamClear
- * \sa SDL_FreeAudioStream
+ * \since This function is available since SDL 2.0.7.
+ *
+ * \sa SDL_NewAudioStream
+ * \sa SDL_AudioStreamGet
+ * \sa SDL_AudioStreamAvailable
+ * \sa SDL_AudioStreamFlush
+ * \sa SDL_AudioStreamClear
+ * \sa SDL_FreeAudioStream
*/
extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const void *buf, int len);
/**
- * Get converted/resampled data from the stream
+ * Get converted/resampled data from the stream
*
- * \param stream The stream the audio is being requested from
- * \param buf A buffer to fill with audio data
- * \param len The maximum number of bytes to fill
- * \return The number of bytes read from the stream, or -1 on error
+ * \param stream The stream the audio is being requested from
+ * \param buf A buffer to fill with audio data
+ * \param len The maximum number of bytes to fill
+ * \returns the number of bytes read from the stream, or -1 on error
*
- * \sa SDL_NewAudioStream
- * \sa SDL_AudioStreamPut
- * \sa SDL_AudioStreamAvailable
- * \sa SDL_AudioStreamFlush
- * \sa SDL_AudioStreamClear
- * \sa SDL_FreeAudioStream
+ * \since This function is available since SDL 2.0.7.
+ *
+ * \sa SDL_NewAudioStream
+ * \sa SDL_AudioStreamPut
+ * \sa SDL_AudioStreamAvailable
+ * \sa SDL_AudioStreamFlush
+ * \sa SDL_AudioStreamClear
+ * \sa SDL_FreeAudioStream
*/
extern DECLSPEC int SDLCALL SDL_AudioStreamGet(SDL_AudioStream *stream, void *buf, int len);
/**
- * Get the number of converted/resampled bytes available. The stream may be
- * buffering data behind the scenes until it has enough to resample
- * correctly, so this number might be lower than what you expect, or even
- * be zero. Add more data or flush the stream if you need the data now.
+ * Get the number of converted/resampled bytes available.
*
- * \sa SDL_NewAudioStream
- * \sa SDL_AudioStreamPut
- * \sa SDL_AudioStreamGet
- * \sa SDL_AudioStreamFlush
- * \sa SDL_AudioStreamClear
- * \sa SDL_FreeAudioStream
+ * The stream may be buffering data behind the scenes until it has enough to
+ * resample correctly, so this number might be lower than what you expect, or
+ * even be zero. Add more data or flush the stream if you need the data now.
+ *
+ * \since This function is available since SDL 2.0.7.
+ *
+ * \sa SDL_NewAudioStream
+ * \sa SDL_AudioStreamPut
+ * \sa SDL_AudioStreamGet
+ * \sa SDL_AudioStreamFlush
+ * \sa SDL_AudioStreamClear
+ * \sa SDL_FreeAudioStream
*/
extern DECLSPEC int SDLCALL SDL_AudioStreamAvailable(SDL_AudioStream *stream);
/**
* Tell the stream that you're done sending data, and anything being buffered
- * should be converted/resampled and made available immediately.
+ * should be converted/resampled and made available immediately.
*
- * It is legal to add more data to a stream after flushing, but there will
- * be audio gaps in the output. Generally this is intended to signal the
- * end of input, so the complete output becomes available.
+ * It is legal to add more data to a stream after flushing, but there will be
+ * audio gaps in the output. Generally this is intended to signal the end of
+ * input, so the complete output becomes available.
*
- * \sa SDL_NewAudioStream
- * \sa SDL_AudioStreamPut
- * \sa SDL_AudioStreamGet
- * \sa SDL_AudioStreamAvailable
- * \sa SDL_AudioStreamClear
- * \sa SDL_FreeAudioStream
+ * \since This function is available since SDL 2.0.7.
+ *
+ * \sa SDL_NewAudioStream
+ * \sa SDL_AudioStreamPut
+ * \sa SDL_AudioStreamGet
+ * \sa SDL_AudioStreamAvailable
+ * \sa SDL_AudioStreamClear
+ * \sa SDL_FreeAudioStream
*/
extern DECLSPEC int SDLCALL SDL_AudioStreamFlush(SDL_AudioStream *stream);
/**
- * Clear any pending data in the stream without converting it
+ * Clear any pending data in the stream without converting it
*
- * \sa SDL_NewAudioStream
- * \sa SDL_AudioStreamPut
- * \sa SDL_AudioStreamGet
- * \sa SDL_AudioStreamAvailable
- * \sa SDL_AudioStreamFlush
- * \sa SDL_FreeAudioStream
+ * \since This function is available since SDL 2.0.7.
+ *
+ * \sa SDL_NewAudioStream
+ * \sa SDL_AudioStreamPut
+ * \sa SDL_AudioStreamGet
+ * \sa SDL_AudioStreamAvailable
+ * \sa SDL_AudioStreamFlush
+ * \sa SDL_FreeAudioStream
*/
extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream);
@@ -637,30 +1107,73 @@
/**
* Free an audio stream
*
- * \sa SDL_NewAudioStream
- * \sa SDL_AudioStreamPut
- * \sa SDL_AudioStreamGet
- * \sa SDL_AudioStreamAvailable
- * \sa SDL_AudioStreamFlush
- * \sa SDL_AudioStreamClear
+ * \since This function is available since SDL 2.0.7.
+ *
+ * \sa SDL_NewAudioStream
+ * \sa SDL_AudioStreamPut
+ * \sa SDL_AudioStreamGet
+ * \sa SDL_AudioStreamAvailable
+ * \sa SDL_AudioStreamFlush
+ * \sa SDL_AudioStreamClear
*/
extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream);
#define SDL_MIX_MAXVOLUME 128
+
/**
- * This takes two audio buffers of the playing audio format and mixes
- * them, performing addition, volume adjustment, and overflow clipping.
- * The volume ranges from 0 - 128, and should be set to ::SDL_MIX_MAXVOLUME
- * for full audio volume. Note this does not change hardware volume.
- * This is provided for convenience -- you can mix your own audio data.
+ * This function is a legacy means of mixing audio.
+ *
+ * This function is equivalent to calling...
+ *
+ * ```c
+ * SDL_MixAudioFormat(dst, src, format, len, volume);
+ * ```
+ *
+ * ...where `format` is the obtained format of the audio device from the
+ * legacy SDL_OpenAudio() function.
+ *
+ * \param dst the destination for the mixed audio
+ * \param src the source audio buffer to be mixed
+ * \param len the length of the audio buffer in bytes
+ * \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
+ * for full audio volume
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_MixAudioFormat
*/
extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
Uint32 len, int volume);
/**
- * This works like SDL_MixAudio(), but you specify the audio format instead of
- * using the format of audio device 1. Thus it can be used when no audio
- * device is open at all.
+ * Mix audio data in a specified format.
+ *
+ * This takes an audio buffer `src` of `len` bytes of `format` data and mixes
+ * it into `dst`, performing addition, volume adjustment, and overflow
+ * clipping. The buffer pointed to by `dst` must also be `len` bytes of
+ * `format` data.
+ *
+ * This is provided for convenience -- you can mix your own audio data.
+ *
+ * Do not use this function for mixing together more than two streams of
+ * sample data. The output from repeated application of this function may be
+ * distorted by clipping, because there is no accumulator with greater range
+ * than the input (not to mention this being an inefficient way of doing it).
+ *
+ * It is a common misconception that this function is required to write audio
+ * data to an output stream in an audio callback. While you can do that,
+ * SDL_MixAudioFormat() is really only needed when you're mixing a single
+ * audio stream with a volume adjustment.
+ *
+ * \param dst the destination for the mixed audio
+ * \param src the source audio buffer to be mixed
+ * \param format the SDL_AudioFormat structure representing the desired audio
+ * format
+ * \param len the length of the audio buffer in bytes
+ * \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
+ * for full audio volume
+ *
+ * \since This function is available since SDL 2.0.0.
*/
extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
const Uint8 * src,
@@ -668,161 +1181,166 @@
Uint32 len, int volume);
/**
- * Queue more audio on non-callback devices.
+ * Queue more audio on non-callback devices.
*
- * (If you are looking to retrieve queued audio from a non-callback capture
- * device, you want SDL_DequeueAudio() instead. This will return -1 to
- * signify an error if you use it with capture devices.)
+ * If you are looking to retrieve queued audio from a non-callback capture
+ * device, you want SDL_DequeueAudio() instead. SDL_QueueAudio() will return
+ * -1 to signify an error if you use it with capture devices.
*
- * SDL offers two ways to feed audio to the device: you can either supply a
- * callback that SDL triggers with some frequency to obtain more audio
- * (pull method), or you can supply no callback, and then SDL will expect
- * you to supply data at regular intervals (push method) with this function.
+ * SDL offers two ways to feed audio to the device: you can either supply a
+ * callback that SDL triggers with some frequency to obtain more audio (pull
+ * method), or you can supply no callback, and then SDL will expect you to
+ * supply data at regular intervals (push method) with this function.
*
- * There are no limits on the amount of data you can queue, short of
- * exhaustion of address space. Queued data will drain to the device as
- * necessary without further intervention from you. If the device needs
- * audio but there is not enough queued, it will play silence to make up
- * the difference. This means you will have skips in your audio playback
- * if you aren't routinely queueing sufficient data.
+ * There are no limits on the amount of data you can queue, short of
+ * exhaustion of address space. Queued data will drain to the device as
+ * necessary without further intervention from you. If the device needs audio
+ * but there is not enough queued, it will play silence to make up the
+ * difference. This means you will have skips in your audio playback if you
+ * aren't routinely queueing sufficient data.
*
- * This function copies the supplied data, so you are safe to free it when
- * the function returns. This function is thread-safe, but queueing to the
- * same device from two threads at once does not promise which buffer will
- * be queued first.
+ * This function copies the supplied data, so you are safe to free it when the
+ * function returns. This function is thread-safe, but queueing to the same
+ * device from two threads at once does not promise which buffer will be
+ * queued first.
*
- * You may not queue audio on a device that is using an application-supplied
- * callback; doing so returns an error. You have to use the audio callback
- * or queue audio with this function, but not both.
+ * You may not queue audio on a device that is using an application-supplied
+ * callback; doing so returns an error. You have to use the audio callback or
+ * queue audio with this function, but not both.
*
- * You should not call SDL_LockAudio() on the device before queueing; SDL
- * handles locking internally for this function.
+ * You should not call SDL_LockAudio() on the device before queueing; SDL
+ * handles locking internally for this function.
*
- * \param dev The device ID to which we will queue audio.
- * \param data The data to queue to the device for later playback.
- * \param len The number of bytes (not samples!) to which (data) points.
- * \return 0 on success, or -1 on error.
+ * Note that SDL2 does not support planar audio. You will need to resample
+ * from planar audio formats into a non-planar one (see SDL_AudioFormat)
+ * before queuing audio.
*
- * \sa SDL_GetQueuedAudioSize
- * \sa SDL_ClearQueuedAudio
+ * \param dev the device ID to which we will queue audio
+ * \param data the data to queue to the device for later playback
+ * \param len the number of bytes (not samples!) to which `data` points
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.4.
+ *
+ * \sa SDL_ClearQueuedAudio
+ * \sa SDL_GetQueuedAudioSize
*/
extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len);
/**
- * Dequeue more audio on non-callback devices.
+ * Dequeue more audio on non-callback devices.
*
- * (If you are looking to queue audio for output on a non-callback playback
- * device, you want SDL_QueueAudio() instead. This will always return 0
- * if you use it with playback devices.)
+ * If you are looking to queue audio for output on a non-callback playback
+ * device, you want SDL_QueueAudio() instead. SDL_DequeueAudio() will always
+ * return 0 if you use it with playback devices.
*
- * SDL offers two ways to retrieve audio from a capture device: you can
- * either supply a callback that SDL triggers with some frequency as the
- * device records more audio data, (push method), or you can supply no
- * callback, and then SDL will expect you to retrieve data at regular
- * intervals (pull method) with this function.
+ * SDL offers two ways to retrieve audio from a capture device: you can either
+ * supply a callback that SDL triggers with some frequency as the device
+ * records more audio data, (push method), or you can supply no callback, and
+ * then SDL will expect you to retrieve data at regular intervals (pull
+ * method) with this function.
*
- * There are no limits on the amount of data you can queue, short of
- * exhaustion of address space. Data from the device will keep queuing as
- * necessary without further intervention from you. This means you will
- * eventually run out of memory if you aren't routinely dequeueing data.
+ * There are no limits on the amount of data you can queue, short of
+ * exhaustion of address space. Data from the device will keep queuing as
+ * necessary without further intervention from you. This means you will
+ * eventually run out of memory if you aren't routinely dequeueing data.
*
- * Capture devices will not queue data when paused; if you are expecting
- * to not need captured audio for some length of time, use
- * SDL_PauseAudioDevice() to stop the capture device from queueing more
- * data. This can be useful during, say, level loading times. When
- * unpaused, capture devices will start queueing data from that point,
- * having flushed any capturable data available while paused.
+ * Capture devices will not queue data when paused; if you are expecting to
+ * not need captured audio for some length of time, use SDL_PauseAudioDevice()
+ * to stop the capture device from queueing more data. This can be useful
+ * during, say, level loading times. When unpaused, capture devices will start
+ * queueing data from that point, having flushed any capturable data available
+ * while paused.
*
- * This function is thread-safe, but dequeueing from the same device from
- * two threads at once does not promise which thread will dequeued data
- * first.
+ * This function is thread-safe, but dequeueing from the same device from two
+ * threads at once does not promise which thread will dequeue data first.
*
- * You may not dequeue audio from a device that is using an
- * application-supplied callback; doing so returns an error. You have to use
- * the audio callback, or dequeue audio with this function, but not both.
+ * You may not dequeue audio from a device that is using an
+ * application-supplied callback; doing so returns an error. You have to use
+ * the audio callback, or dequeue audio with this function, but not both.
*
- * You should not call SDL_LockAudio() on the device before queueing; SDL
- * handles locking internally for this function.
+ * You should not call SDL_LockAudio() on the device before dequeueing; SDL
+ * handles locking internally for this function.
*
- * \param dev The device ID from which we will dequeue audio.
- * \param data A pointer into where audio data should be copied.
- * \param len The number of bytes (not samples!) to which (data) points.
- * \return number of bytes dequeued, which could be less than requested.
+ * \param dev the device ID from which we will dequeue audio
+ * \param data a pointer into where audio data should be copied
+ * \param len the number of bytes (not samples!) to which (data) points
+ * \returns the number of bytes dequeued, which could be less than requested;
+ * call SDL_GetError() for more information.
*
- * \sa SDL_GetQueuedAudioSize
- * \sa SDL_ClearQueuedAudio
+ * \since This function is available since SDL 2.0.5.
+ *
+ * \sa SDL_ClearQueuedAudio
+ * \sa SDL_GetQueuedAudioSize
*/
extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *data, Uint32 len);
/**
- * Get the number of bytes of still-queued audio.
+ * Get the number of bytes of still-queued audio.
*
- * For playback device:
+ * For playback devices: this is the number of bytes that have been queued for
+ * playback with SDL_QueueAudio(), but have not yet been sent to the hardware.
*
- * This is the number of bytes that have been queued for playback with
- * SDL_QueueAudio(), but have not yet been sent to the hardware. This
- * number may shrink at any time, so this only informs of pending data.
+ * Once we've sent it to the hardware, this function can not decide the exact
+ * byte boundary of what has been played. It's possible that we just gave the
+ * hardware several kilobytes right before you called this function, but it
+ * hasn't played any of it yet, or maybe half of it, etc.
*
- * Once we've sent it to the hardware, this function can not decide the
- * exact byte boundary of what has been played. It's possible that we just
- * gave the hardware several kilobytes right before you called this
- * function, but it hasn't played any of it yet, or maybe half of it, etc.
+ * For capture devices, this is the number of bytes that have been captured by
+ * the device and are waiting for you to dequeue. This number may grow at any
+ * time, so this only informs of the lower-bound of available data.
*
- * For capture devices:
+ * You may not queue or dequeue audio on a device that is using an
+ * application-supplied callback; calling this function on such a device
+ * always returns 0. You have to use the audio callback or queue audio, but
+ * not both.
*
- * This is the number of bytes that have been captured by the device and
- * are waiting for you to dequeue. This number may grow at any time, so
- * this only informs of the lower-bound of available data.
+ * You should not call SDL_LockAudio() on the device before querying; SDL
+ * handles locking internally for this function.
*
- * You may not queue audio on a device that is using an application-supplied
- * callback; calling this function on such a device always returns 0.
- * You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use
- * the audio callback, but not both.
+ * \param dev the device ID of which we will query queued audio size
+ * \returns the number of bytes (not samples!) of queued audio.
*
- * You should not call SDL_LockAudio() on the device before querying; SDL
- * handles locking internally for this function.
+ * \since This function is available since SDL 2.0.4.
*
- * \param dev The device ID of which we will query queued audio size.
- * \return Number of bytes (not samples!) of queued audio.
- *
- * \sa SDL_QueueAudio
- * \sa SDL_ClearQueuedAudio
+ * \sa SDL_ClearQueuedAudio
+ * \sa SDL_QueueAudio
+ * \sa SDL_DequeueAudio
*/
extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev);
/**
- * Drop any queued audio data. For playback devices, this is any queued data
- * still waiting to be submitted to the hardware. For capture devices, this
- * is any data that was queued by the device that hasn't yet been dequeued by
- * the application.
+ * Drop any queued audio data waiting to be sent to the hardware.
*
- * Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For
- * playback devices, the hardware will start playing silence if more audio
- * isn't queued. Unpaused capture devices will start filling the queue again
- * as soon as they have more data available (which, depending on the state
- * of the hardware and the thread, could be before this function call
- * returns!).
+ * Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For
+ * output devices, the hardware will start playing silence if more audio isn't
+ * queued. For capture devices, the hardware will start filling the empty
+ * queue with new data if the capture device isn't paused.
*
- * This will not prevent playback of queued audio that's already been sent
- * to the hardware, as we can not undo that, so expect there to be some
- * fraction of a second of audio that might still be heard. This can be
- * useful if you want to, say, drop any pending music during a level change
- * in your game.
+ * This will not prevent playback of queued audio that's already been sent to
+ * the hardware, as we can not undo that, so expect there to be some fraction
+ * of a second of audio that might still be heard. This can be useful if you
+ * want to, say, drop any pending music or any unprocessed microphone input
+ * during a level change in your game.
*
- * You may not queue audio on a device that is using an application-supplied
- * callback; calling this function on such a device is always a no-op.
- * You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use
- * the audio callback, but not both.
+ * You may not queue or dequeue audio on a device that is using an
+ * application-supplied callback; calling this function on such a device
+ * always returns 0. You have to use the audio callback or queue audio, but
+ * not both.
*
- * You should not call SDL_LockAudio() on the device before clearing the
- * queue; SDL handles locking internally for this function.
+ * You should not call SDL_LockAudio() on the device before clearing the
+ * queue; SDL handles locking internally for this function.
*
- * This function always succeeds and thus returns void.
+ * This function always succeeds and thus returns void.
*
- * \param dev The device ID of which to clear the audio queue.
+ * \param dev the device ID of which to clear the audio queue
*
- * \sa SDL_QueueAudio
- * \sa SDL_GetQueuedAudioSize
+ * \since This function is available since SDL 2.0.4.
+ *
+ * \sa SDL_GetQueuedAudioSize
+ * \sa SDL_QueueAudio
+ * \sa SDL_DequeueAudio
*/
extern DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev);
@@ -836,16 +1354,139 @@
* function or you will cause deadlock.
*/
/* @{ */+
+/**
+ * This function is a legacy means of locking the audio device.
+ *
+ * New programs might want to use SDL_LockAudioDevice() instead. This function
+ * is equivalent to calling...
+ *
+ * ```c
+ * SDL_LockAudioDevice(1);
+ * ```
+ *
+ * ...and is only useful if you used the legacy SDL_OpenAudio() function.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LockAudioDevice
+ * \sa SDL_UnlockAudio
+ * \sa SDL_UnlockAudioDevice
+ */
extern DECLSPEC void SDLCALL SDL_LockAudio(void);
+
+/**
+ * Use this function to lock out the audio callback function for a specified
+ * device.
+ *
+ * The lock manipulated by these functions protects the audio callback
+ * function specified in SDL_OpenAudioDevice(). During a
+ * SDL_LockAudioDevice()/SDL_UnlockAudioDevice() pair, you can be guaranteed
+ * that the callback function for that device is not running, even if the
+ * device is not paused. While a device is locked, any other unpaused,
+ * unlocked devices may still run their callbacks.
+ *
+ * Calling this function from inside your audio callback is unnecessary. SDL
+ * obtains this lock before calling your function, and releases it when the
+ * function returns.
+ *
+ * You should not hold the lock longer than absolutely necessary. If you hold
+ * it too long, you'll experience dropouts in your audio playback. Ideally,
+ * your application locks the device, sets a few variables and unlocks again.
+ * Do not do heavy work while holding the lock for a device.
+ *
+ * It is safe to lock the audio device multiple times, as long as you unlock
+ * it an equivalent number of times. The callback will not run until the
+ * device has been unlocked completely in this way. If your application fails
+ * to unlock the device appropriately, your callback will never run, you might
+ * hear repeating bursts of audio, and SDL_CloseAudioDevice() will probably
+ * deadlock.
+ *
+ * Internally, the audio device lock is a mutex; if you lock from two threads
+ * at once, not only will you block the audio callback, you'll block the other
+ * thread.
+ *
+ * \param dev the ID of the device to be locked
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_UnlockAudioDevice
+ */
extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev);
+
+/**
+ * This function is a legacy means of unlocking the audio device.
+ *
+ * New programs might want to use SDL_UnlockAudioDevice() instead. This
+ * function is equivalent to calling...
+ *
+ * ```c
+ * SDL_UnlockAudioDevice(1);
+ * ```
+ *
+ * ...and is only useful if you used the legacy SDL_OpenAudio() function.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LockAudio
+ * \sa SDL_UnlockAudioDevice
+ */
extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
+
+/**
+ * Use this function to unlock the audio callback function for a specified
+ * device.
+ *
+ * This function should be paired with a previous SDL_LockAudioDevice() call.
+ *
+ * \param dev the ID of the device to be unlocked
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LockAudioDevice
+ */
extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
/* @} *//* Audio lock functions */
/**
- * This function shuts down audio processing and closes the audio device.
+ * This function is a legacy means of closing the audio device.
+ *
+ * This function is equivalent to calling...
+ *
+ * ```c
+ * SDL_CloseAudioDevice(1);
+ * ```
+ *
+ * ...and is only useful if you used the legacy SDL_OpenAudio() function.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_OpenAudio
*/
extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
+
+/**
+ * Use this function to shut down audio processing and close the audio device.
+ *
+ * The application should close open audio devices once they are no longer
+ * needed. Calling this function will wait until the device's audio callback
+ * is not running, release the audio hardware and then clean up internal
+ * state. No further audio will play from this device once this function
+ * returns.
+ *
+ * This function may block briefly while pending audio data is played by the
+ * hardware, so that applications don't drop the last buffer of data they
+ * supplied.
+ *
+ * The device ID is invalid as soon as the device is closed, and is eligible
+ * for reuse in a new SDL_OpenAudioDevice() call immediately.
+ *
+ * \param dev an audio device previously opened with SDL_OpenAudioDevice()
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_OpenAudioDevice
+ */
extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
/* Ends C function definitions when using C++ */
@@ -852,7 +1493,7 @@
#ifdef __cplusplus
}
#endif
-#include "close_code.h"
+#include <SDL2/close_code.h>
#endif /* SDL_audio_h_ */
--- a/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_bits.h
+++ b/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_bits.h
@@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
- Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@@ -28,9 +28,9 @@
#ifndef SDL_bits_h_
#define SDL_bits_h_
-#include "SDL_stdinc.h"
+#include <SDL2/SDL_stdinc.h>
-#include "begin_code.h"
+#include <SDL2/begin_code.h>
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {@@ -45,13 +45,12 @@
* with 0. This operation can also be stated as "count leading zeroes" and
* "log base 2".
*
- * \return Index of the most significant bit, or -1 if the value is 0.
+ * \return the index of the most significant bit, or -1 if the value is 0.
*/
#if defined(__WATCOMC__) && defined(__386__)
-extern _inline int _SDL_clz_watcom (Uint32);
-#pragma aux _SDL_clz_watcom = \
+extern __inline int _SDL_bsr_watcom(Uint32);
+#pragma aux _SDL_bsr_watcom = \
"bsr eax, eax" \
- "xor eax, 31" \
parm [eax] nomemory \
value [eax] \
modify exact [eax] nomemory;
@@ -72,7 +71,13 @@
if (x == 0) {return -1;
}
- return 31 - _SDL_clz_watcom(x);
+ return _SDL_bsr_watcom(x);
+#elif defined(_MSC_VER)
+ unsigned long index;
+ if (_BitScanReverse(&index, x)) {+ return index;
+ }
+ return -1;
#else
/* Based off of Bit Twiddling Hacks by Sean Eron Anderson
* <seander@cs.stanford.edu>, released in the public domain.
@@ -114,7 +119,7 @@
#ifdef __cplusplus
}
#endif
-#include "close_code.h"
+#include <SDL2/close_code.h>
#endif /* SDL_bits_h_ */
--- a/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_blendmode.h
+++ b/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_blendmode.h
@@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
- Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@@ -28,7 +28,7 @@
#ifndef SDL_blendmode_h_
#define SDL_blendmode_h_
-#include "begin_code.h"
+#include <SDL2/begin_code.h>
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {@@ -50,6 +50,9 @@
SDL_BLENDMODE_MOD = 0x00000004, /**< color modulate
dstRGB = srcRGB * dstRGB
dstA = dstA */
+ SDL_BLENDMODE_MUL = 0x00000008, /**< color multiply
+ dstRGB = (srcRGB * dstRGB) + (dstRGB * (1-srcA))
+ dstA = (srcA * dstA) + (dstA * (1-srcA)) */
SDL_BLENDMODE_INVALID = 0x7FFFFFFF
/* Additional custom blend modes can be returned by SDL_ComposeCustomBlendMode() */
@@ -64,9 +67,8 @@
SDL_BLENDOPERATION_ADD = 0x1, /**< dst + src: supported by all renderers */
SDL_BLENDOPERATION_SUBTRACT = 0x2, /**< dst - src : supported by D3D9, D3D11, OpenGL, OpenGLES */
SDL_BLENDOPERATION_REV_SUBTRACT = 0x3, /**< src - dst : supported by D3D9, D3D11, OpenGL, OpenGLES */
- SDL_BLENDOPERATION_MINIMUM = 0x4, /**< min(dst, src) : supported by D3D11 */
- SDL_BLENDOPERATION_MAXIMUM = 0x5 /**< max(dst, src) : supported by D3D11 */
-
+ SDL_BLENDOPERATION_MINIMUM = 0x4, /**< min(dst, src) : supported by D3D9, D3D11 */
+ SDL_BLENDOPERATION_MAXIMUM = 0x5 /**< max(dst, src) : supported by D3D9, D3D11 */
} SDL_BlendOperation;
/**
@@ -84,23 +86,99 @@
SDL_BLENDFACTOR_ONE_MINUS_DST_COLOR = 0x8, /**< 1-dstR, 1-dstG, 1-dstB, 1-dstA */
SDL_BLENDFACTOR_DST_ALPHA = 0x9, /**< dstA, dstA, dstA, dstA */
SDL_BLENDFACTOR_ONE_MINUS_DST_ALPHA = 0xA /**< 1-dstA, 1-dstA, 1-dstA, 1-dstA */
-
} SDL_BlendFactor;
/**
- * \brief Create a custom blend mode, which may or may not be supported by a given renderer
+ * Compose a custom blend mode for renderers.
*
- * \param srcColorFactor source color factor
- * \param dstColorFactor destination color factor
- * \param colorOperation color operation
- * \param srcAlphaFactor source alpha factor
- * \param dstAlphaFactor destination alpha factor
- * \param alphaOperation alpha operation
+ * The functions SDL_SetRenderDrawBlendMode and SDL_SetTextureBlendMode accept
+ * the SDL_BlendMode returned by this function if the renderer supports it.
*
- * The result of the blend mode operation will be:
- * dstRGB = dstRGB * dstColorFactor colorOperation srcRGB * srcColorFactor
- * and
- * dstA = dstA * dstAlphaFactor alphaOperation srcA * srcAlphaFactor
+ * A blend mode controls how the pixels from a drawing operation (source) get
+ * combined with the pixels from the render target (destination). First, the
+ * components of the source and destination pixels get multiplied with their
+ * blend factors. Then, the blend operation takes the two products and
+ * calculates the result that will get stored in the render target.
+ *
+ * Expressed in pseudocode, it would look like this:
+ *
+ * ```c
+ * dstRGB = colorOperation(srcRGB * srcColorFactor, dstRGB * dstColorFactor);
+ * dstA = alphaOperation(srcA * srcAlphaFactor, dstA * dstAlphaFactor);
+ * ```
+ *
+ * Where the functions `colorOperation(src, dst)` and `alphaOperation(src,
+ * dst)` can return one of the following:
+ *
+ * - `src + dst`
+ * - `src - dst`
+ * - `dst - src`
+ * - `min(src, dst)`
+ * - `max(src, dst)`
+ *
+ * The red, green, and blue components are always multiplied with the first,
+ * second, and third components of the SDL_BlendFactor, respectively. The
+ * fourth component is not used.
+ *
+ * The alpha component is always multiplied with the fourth component of the
+ * SDL_BlendFactor. The other components are not used in the alpha
+ * calculation.
+ *
+ * Support for these blend modes varies for each renderer. To check if a
+ * specific SDL_BlendMode is supported, create a renderer and pass it to
+ * either SDL_SetRenderDrawBlendMode or SDL_SetTextureBlendMode. They will
+ * return with an error if the blend mode is not supported.
+ *
+ * This list describes the support of custom blend modes for each renderer in
+ * SDL 2.0.6. All renderers support the four blend modes listed in the
+ * SDL_BlendMode enumeration.
+ *
+ * - **direct3d**: Supports all operations with all factors. However, some
+ * factors produce unexpected results with `SDL_BLENDOPERATION_MINIMUM` and
+ * `SDL_BLENDOPERATION_MAXIMUM`.
+ * - **direct3d11**: Same as Direct3D 9.
+ * - **opengl**: Supports the `SDL_BLENDOPERATION_ADD` operation with all
+ * factors. OpenGL versions 1.1, 1.2, and 1.3 do not work correctly with SDL
+ * 2.0.6.
+ * - **opengles**: Supports the `SDL_BLENDOPERATION_ADD` operation with all
+ * factors. Color and alpha factors need to be the same. OpenGL ES 1
+ * implementation specific: May also support `SDL_BLENDOPERATION_SUBTRACT`
+ * and `SDL_BLENDOPERATION_REV_SUBTRACT`. May support color and alpha
+ * operations being different from each other. May support color and alpha
+ * factors being different from each other.
+ * - **opengles2**: Supports the `SDL_BLENDOPERATION_ADD`,
+ * `SDL_BLENDOPERATION_SUBTRACT`, `SDL_BLENDOPERATION_REV_SUBTRACT`
+ * operations with all factors.
+ * - **psp**: No custom blend mode support.
+ * - **software**: No custom blend mode support.
+ *
+ * Some renderers do not provide an alpha component for the default render
+ * target. The `SDL_BLENDFACTOR_DST_ALPHA` and
+ * `SDL_BLENDFACTOR_ONE_MINUS_DST_ALPHA` factors do not have an effect in this
+ * case.
+ *
+ * \param srcColorFactor the SDL_BlendFactor applied to the red, green, and
+ * blue components of the source pixels
+ * \param dstColorFactor the SDL_BlendFactor applied to the red, green, and
+ * blue components of the destination pixels
+ * \param colorOperation the SDL_BlendOperation used to combine the red,
+ * green, and blue components of the source and
+ * destination pixels
+ * \param srcAlphaFactor the SDL_BlendFactor applied to the alpha component of
+ * the source pixels
+ * \param dstAlphaFactor the SDL_BlendFactor applied to the alpha component of
+ * the destination pixels
+ * \param alphaOperation the SDL_BlendOperation used to combine the alpha
+ * component of the source and destination pixels
+ * \returns an SDL_BlendMode that represents the chosen factors and
+ * operations.
+ *
+ * \since This function is available since SDL 2.0.6.
+ *
+ * \sa SDL_SetRenderDrawBlendMode
+ * \sa SDL_GetRenderDrawBlendMode
+ * \sa SDL_SetTextureBlendMode
+ * \sa SDL_GetTextureBlendMode
*/
extern DECLSPEC SDL_BlendMode SDLCALL SDL_ComposeCustomBlendMode(SDL_BlendFactor srcColorFactor,
SDL_BlendFactor dstColorFactor,
@@ -113,7 +191,7 @@
#ifdef __cplusplus
}
#endif
-#include "close_code.h"
+#include <SDL2/close_code.h>
#endif /* SDL_blendmode_h_ */
--- a/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_clipboard.h
+++ b/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_clipboard.h
@@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
- Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@@ -28,9 +28,9 @@
#ifndef SDL_clipboard_h_
#define SDL_clipboard_h_
-#include "SDL_stdinc.h"
+#include <SDL2/SDL_stdinc.h>
-#include "begin_code.h"
+#include <SDL2/begin_code.h>
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {@@ -39,32 +39,102 @@
/* Function prototypes */
/**
- * \brief Put UTF-8 text into the clipboard
+ * Put UTF-8 text into the clipboard.
*
- * \sa SDL_GetClipboardText()
+ * \param text the text to store in the clipboard
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetClipboardText
+ * \sa SDL_HasClipboardText
*/
extern DECLSPEC int SDLCALL SDL_SetClipboardText(const char *text);
/**
- * \brief Get UTF-8 text from the clipboard, which must be freed with SDL_free()
+ * Get UTF-8 text from the clipboard, which must be freed with SDL_free().
*
- * \sa SDL_SetClipboardText()
+ * This functions returns empty string if there was not enough memory left for
+ * a copy of the clipboard's content.
+ *
+ * \returns the clipboard text on success or an empty string on failure; call
+ * SDL_GetError() for more information. Caller must call SDL_free()
+ * on the returned pointer when done with it (even if there was an
+ * error).
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HasClipboardText
+ * \sa SDL_SetClipboardText
*/
extern DECLSPEC char * SDLCALL SDL_GetClipboardText(void);
/**
- * \brief Returns a flag indicating whether the clipboard exists and contains a text string that is non-empty
+ * Query whether the clipboard exists and contains a non-empty text string.
*
- * \sa SDL_GetClipboardText()
+ * \returns SDL_TRUE if the clipboard has text, or SDL_FALSE if it does not.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetClipboardText
+ * \sa SDL_SetClipboardText
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasClipboardText(void);
+/**
+ * Put UTF-8 text into the primary selection.
+ *
+ * \param text the text to store in the primary selection
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.26.0.
+ *
+ * \sa SDL_GetPrimarySelectionText
+ * \sa SDL_HasPrimarySelectionText
+ */
+extern DECLSPEC int SDLCALL SDL_SetPrimarySelectionText(const char *text);
+/**
+ * Get UTF-8 text from the primary selection, which must be freed with
+ * SDL_free().
+ *
+ * This functions returns empty string if there was not enough memory left for
+ * a copy of the primary selection's content.
+ *
+ * \returns the primary selection text on success or an empty string on
+ * failure; call SDL_GetError() for more information. Caller must
+ * call SDL_free() on the returned pointer when done with it (even if
+ * there was an error).
+ *
+ * \since This function is available since SDL 2.26.0.
+ *
+ * \sa SDL_HasPrimarySelectionText
+ * \sa SDL_SetPrimarySelectionText
+ */
+extern DECLSPEC char * SDLCALL SDL_GetPrimarySelectionText(void);
+
+/**
+ * Query whether the primary selection exists and contains a non-empty text
+ * string.
+ *
+ * \returns SDL_TRUE if the primary selection has text, or SDL_FALSE if it
+ * does not.
+ *
+ * \since This function is available since SDL 2.26.0.
+ *
+ * \sa SDL_GetPrimarySelectionText
+ * \sa SDL_SetPrimarySelectionText
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_HasPrimarySelectionText(void);
+
+
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}
#endif
-#include "close_code.h"
+#include <SDL2/close_code.h>
#endif /* SDL_clipboard_h_ */
--- a/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_config.h
+++ b/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_config.h
@@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
- Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@@ -22,7 +22,7 @@
#ifndef SDL_config_h_
#define SDL_config_h_
-#include "SDL_platform.h"
+#include <SDL2/SDL_platform.h>
/**
* \file SDL_config.h
@@ -30,22 +30,28 @@
/* Add any platform that doesn't build using the configure system. */
#if defined(__WIN32__)
-#include "SDL_config_windows.h"
+#include <SDL2/SDL_config_windows.h>
#elif defined(__WINRT__)
-#include "SDL_config_winrt.h"
+#include <SDL2/SDL_config_winrt.h>
+#elif defined(__WINGDK__)
+#include <SDL2/SDL_config_wingdk.h>
+#elif defined(__XBOXONE__) || defined(__XBOXSERIES__)
+#include <SDL2/SDL_config_xbox.h>
#elif defined(__MACOSX__)
-#include "SDL_config_macosx.h"
+#include <SDL2/SDL_config_macosx.h>
#elif defined(__IPHONEOS__)
-#include "SDL_config_iphoneos.h"
+#include <SDL2/SDL_config_iphoneos.h>
#elif defined(__ANDROID__)
-#include "SDL_config_android.h"
-#elif defined(__PSP__)
-#include "SDL_config_psp.h"
+#include <SDL2/SDL_config_android.h>
#elif defined(__OS2__)
-#include "SDL_config_os2.h"
+#include <SDL2/SDL_config_os2.h>
+#elif defined(__EMSCRIPTEN__)
+#include <SDL2/SDL_config_emscripten.h>
+#elif defined(__NGAGE__)
+#include <SDL2/SDL_config_ngage.h>
#else
/* This is a minimal configuration just to get SDL running on new platforms. */
-#include "SDL_config_minimal.h"
+#include <SDL2/SDL_config_minimal.h>
#endif /* platform config */
#ifdef USING_GENERATED_CONFIG_H
--- a/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_config_macosx.h
+++ b/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_config_macosx.h
@@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
- Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@@ -23,7 +23,7 @@
#define SDL_config_macosx_h_
#define SDL_config_h_
-#include "SDL_platform.h"
+#include <SDL2/SDL_platform.h>
/* This gets us MAC_OS_X_VERSION_MIN_REQUIRED... */
#include <AvailabilityMacros.h>
@@ -52,6 +52,7 @@
#define HAVE_LIBUNWIND_H 1
/* C library functions */
+#define HAVE_DLOPEN 1
#define HAVE_MALLOC 1
#define HAVE_CALLOC 1
#define HAVE_REALLOC 1
@@ -62,6 +63,7 @@
#define HAVE_PUTENV 1
#define HAVE_UNSETENV 1
#define HAVE_QSORT 1
+#define HAVE_BSEARCH 1
#define HAVE_ABS 1
#define HAVE_BCOPY 1
#define HAVE_MEMSET 1
@@ -74,6 +76,7 @@
#define HAVE_STRCHR 1
#define HAVE_STRRCHR 1
#define HAVE_STRSTR 1
+#define HAVE_STRTOK_R 1
#define HAVE_STRTOL 1
#define HAVE_STRTOUL 1
#define HAVE_STRTOLL 1
@@ -85,6 +88,7 @@
#define HAVE_STRNCMP 1
#define HAVE_STRCASECMP 1
#define HAVE_STRNCASECMP 1
+#define HAVE_STRCASESTR 1
#define HAVE_VSSCANF 1
#define HAVE_VSNPRINTF 1
#define HAVE_M_PI 1
@@ -114,8 +118,12 @@
#define HAVE_LOGF 1
#define HAVE_LOG10 1
#define HAVE_LOG10F 1
+#define HAVE_LROUND 1
+#define HAVE_LROUNDF 1
#define HAVE_POW 1
#define HAVE_POWF 1
+#define HAVE_ROUND 1
+#define HAVE_ROUNDF 1
#define HAVE_SCALBN 1
#define HAVE_SCALBNF 1
#define HAVE_SIN 1
@@ -124,6 +132,8 @@
#define HAVE_SQRTF 1
#define HAVE_TAN 1
#define HAVE_TANF 1
+#define HAVE_TRUNC 1
+#define HAVE_TRUNCF 1
#define HAVE_SIGACTION 1
#define HAVE_SETJMP 1
#define HAVE_NANOSLEEP 1
@@ -130,6 +140,18 @@
#define HAVE_SYSCONF 1
#define HAVE_SYSCTLBYNAME 1
+#if defined(__has_include) && (defined(__i386__) || defined(__x86_64))
+# if __has_include(<immintrin.h>)
+# define HAVE_IMMINTRIN_H 1
+# endif
+#endif
+
+#if (MAC_OS_X_VERSION_MAX_ALLOWED >= 1070)
+#define HAVE_O_CLOEXEC 1
+#endif
+
+#define HAVE_GCC_ATOMICS 1
+
/* Enable various audio drivers */
#define SDL_AUDIO_DRIVER_COREAUDIO 1
#define SDL_AUDIO_DRIVER_DISK 1
@@ -136,10 +158,16 @@
#define SDL_AUDIO_DRIVER_DUMMY 1
/* Enable various input drivers */
+#define SDL_JOYSTICK_HIDAPI 1
#define SDL_JOYSTICK_IOKIT 1
-#define SDL_JOYSTICK_HIDAPI 1
+#define SDL_JOYSTICK_VIRTUAL 1
#define SDL_HAPTIC_IOKIT 1
+/* The MFI controller support requires ARC Objective C runtime */
+#if MAC_OS_X_VERSION_MIN_REQUIRED >= 1080 && !defined(__i386__)
+#define SDL_JOYSTICK_MFI 1
+#endif
+
/* Enable the dummy sensor driver */
#define SDL_SENSOR_DUMMY 1
@@ -157,19 +185,15 @@
#define SDL_VIDEO_DRIVER_COCOA 1
#define SDL_VIDEO_DRIVER_DUMMY 1
#undef SDL_VIDEO_DRIVER_X11
-#define SDL_VIDEO_DRIVER_X11_DYNAMIC "/usr/X11R6/lib/libX11.6.dylib"
-#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XEXT "/usr/X11R6/lib/libXext.6.dylib"
-#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XINERAMA "/usr/X11R6/lib/libXinerama.1.dylib"
-#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XINPUT2 "/usr/X11R6/lib/libXi.6.dylib"
-#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XRANDR "/usr/X11R6/lib/libXrandr.2.dylib"
-#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XSS "/usr/X11R6/lib/libXss.1.dylib"
-#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XVIDMODE "/usr/X11R6/lib/libXxf86vm.1.dylib"
+#define SDL_VIDEO_DRIVER_X11_DYNAMIC "/opt/X11/lib/libX11.6.dylib"
+#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XEXT "/opt/X11/lib/libXext.6.dylib"
+#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XINPUT2 "/opt/X11/lib/libXi.6.dylib"
+#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XRANDR "/opt/X11/lib/libXrandr.2.dylib"
+#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XSS "/opt/X11/lib/libXss.1.dylib"
#define SDL_VIDEO_DRIVER_X11_XDBE 1
-#define SDL_VIDEO_DRIVER_X11_XINERAMA 1
#define SDL_VIDEO_DRIVER_X11_XRANDR 1
#define SDL_VIDEO_DRIVER_X11_XSCRNSAVER 1
#define SDL_VIDEO_DRIVER_X11_XSHAPE 1
-#define SDL_VIDEO_DRIVER_X11_XVIDMODE 1
#define SDL_VIDEO_DRIVER_X11_HAS_XKBKEYCODETOKEYSYM 1
#ifdef MAC_OS_X_VERSION_10_8
@@ -180,7 +204,6 @@
*/
#define SDL_VIDEO_DRIVER_X11_XINPUT2 1
#define SDL_VIDEO_DRIVER_X11_SUPPORTS_GENERIC_EVENTS 1
-#define SDL_VIDEO_DRIVER_X11_CONST_PARAM_XEXTADDDISPLAY 1
#endif
#ifndef SDL_VIDEO_RENDER_OGL
@@ -191,9 +214,15 @@
#define SDL_VIDEO_RENDER_OGL_ES2 1
#endif
-#ifndef SDL_VIDEO_RENDER_METAL
/* Metal only supported on 64-bit architectures with 10.11+ */
-#if TARGET_CPU_X86_64 && (MAC_OS_X_VERSION_MAX_ALLOWED >= 101100)
+#if TARGET_RT_64_BIT && (MAC_OS_X_VERSION_MAX_ALLOWED >= 101100)
+#define SDL_PLATFORM_SUPPORTS_METAL 1
+#else
+#define SDL_PLATFORM_SUPPORTS_METAL 0
+#endif
+
+#ifndef SDL_VIDEO_RENDER_METAL
+#if SDL_PLATFORM_SUPPORTS_METAL
#define SDL_VIDEO_RENDER_METAL 1
#else
#define SDL_VIDEO_RENDER_METAL 0
@@ -217,14 +246,23 @@
#define SDL_VIDEO_OPENGL_GLX 1
#endif
-/* Enable Vulkan support */
-/* Metal/Vulkan Portability only supported on 64-bit architectures with 10.11+ */
-#if TARGET_CPU_X86_64 && (MAC_OS_X_VERSION_MAX_ALLOWED >= 101100)
+/* Enable Vulkan and Metal support */
+#ifndef SDL_VIDEO_VULKAN
+#if SDL_PLATFORM_SUPPORTS_METAL
#define SDL_VIDEO_VULKAN 1
#else
#define SDL_VIDEO_VULKAN 0
#endif
+#endif
+#ifndef SDL_VIDEO_METAL
+#if SDL_PLATFORM_SUPPORTS_METAL
+#define SDL_VIDEO_METAL 1
+#else
+#define SDL_VIDEO_METAL 0
+#endif
+#endif
+
/* Enable system power support */
#define SDL_POWER_MACOSX 1
@@ -232,7 +270,6 @@
#define SDL_FILESYSTEM_COCOA 1
/* Enable assembly routines */
-#define SDL_ASSEMBLY_ROUTINES 1
#ifdef __ppc__
#define SDL_ALTIVEC_BLITTERS 1
#endif
--- a/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_copying.h
+++ b/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_copying.h
@@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
- Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
--- a/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_cpuinfo.h
+++ b/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_cpuinfo.h
@@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
- Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@@ -28,17 +28,26 @@
#ifndef SDL_cpuinfo_h_
#define SDL_cpuinfo_h_
-#include "SDL_stdinc.h"
+#include <SDL2/SDL_stdinc.h>
/* Need to do this here because intrin.h has C++ code in it */
/* Visual Studio 2005 has a bug where intrin.h conflicts with winnt.h */
#if defined(_MSC_VER) && (_MSC_VER >= 1500) && (defined(_M_IX86) || defined(_M_X64))
#ifdef __clang__
-/* Many of the intrinsics SDL uses are not implemented by clang with Visual Studio */
-#undef __MMX__
-#undef __SSE__
-#undef __SSE2__
-#else
+/* As of Clang 11, '_m_prefetchw' is conflicting with the winnt.h's version,
+ so we define the needed '_m_prefetch' here as a pseudo-header, until the issue is fixed. */
+
+#ifndef __PRFCHWINTRIN_H
+#define __PRFCHWINTRIN_H
+
+static __inline__ void __attribute__((__always_inline__, __nodebug__))
+_m_prefetch(void *__P)
+{+ __builtin_prefetch (__P, 0, 3 /* _MM_HINT_T0 */);
+}
+
+#endif /* __PRFCHWINTRIN_H */
+#endif /* __clang__ */
#include <intrin.h>
#ifndef _WIN64
#ifndef __MMX__
@@ -54,9 +63,14 @@
#ifndef __SSE2__
#define __SSE2__
#endif
-#endif /* __clang__ */
+#ifndef __SSE3__
+#define __SSE3__
+#endif
#elif defined(__MINGW64_VERSION_MAJOR)
#include <intrin.h>
+#if !defined(SDL_DISABLE_ARM_NEON_H) && defined(__ARM_NEON)
+# include <arm_neon.h>
+#endif
#else
/* altivec.h redefining bool causes a number of problems, see bugs 3993 and 4392, so you need to explicitly define SDL_ENABLE_ALTIVEC_H to have it included. */
#if defined(HAVE_ALTIVEC_H) && defined(__ALTIVEC__) && !defined(__APPLE_ALTIVEC__) && defined(SDL_ENABLE_ALTIVEC_H)
@@ -65,7 +79,7 @@
#if !defined(SDL_DISABLE_ARM_NEON_H)
# if defined(__ARM_NEON)
# include <arm_neon.h>
-# elif defined(__WINDOWS__) || defined(__WINRT__)
+# elif defined(__WINDOWS__) || defined(__WINRT__) || defined(__GDK__)
/* Visual Studio doesn't define __ARM_ARCH, but _M_ARM (if set, always 7), and _M_ARM64 (if set, always 1). */
# if defined(_M_ARM)
# include <armintr.h>
@@ -73,15 +87,26 @@
# define __ARM_NEON 1 /* Set __ARM_NEON so that it can be used elsewhere, at compile time */
# endif
# if defined (_M_ARM64)
-# include <armintr.h>
-# include <arm_neon.h>
+# include <arm64intr.h>
+# include <arm64_neon.h>
# define __ARM_NEON 1 /* Set __ARM_NEON so that it can be used elsewhere, at compile time */
+# define __ARM_ARCH 8
# endif
# endif
#endif
+#endif /* compiler version */
+
#if defined(__3dNOW__) && !defined(SDL_DISABLE_MM3DNOW_H)
#include <mm3dnow.h>
#endif
+#if defined(__loongarch_sx) && !defined(SDL_DISABLE_LSX_H)
+#include <lsxintrin.h>
+#define __LSX__
+#endif
+#if defined(__loongarch_asx) && !defined(SDL_DISABLE_LASX_H)
+#include <lasxintrin.h>
+#define __LASX__
+#endif
#if defined(HAVE_IMMINTRIN_H) && !defined(SDL_DISABLE_IMMINTRIN_H)
#include <immintrin.h>
#else
@@ -98,9 +123,8 @@
#include <pmmintrin.h>
#endif
#endif /* HAVE_IMMINTRIN_H */
-#endif /* compiler version */
-#include "begin_code.h"
+#include <SDL2/begin_code.h>
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {@@ -114,156 +138,456 @@
#define SDL_CACHELINE_SIZE 128
/**
- * This function returns the number of CPU cores available.
+ * Get the number of CPU cores available.
+ *
+ * \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.
+ *
+ * \since This function is available since SDL 2.0.0.
*/
extern DECLSPEC int SDLCALL SDL_GetCPUCount(void);
/**
- * This function returns the L1 cache line size of the CPU
+ * Determine the L1 cache line size of the CPU.
*
- * This is useful for determining multi-threaded structure padding
- * or SIMD prefetch sizes.
+ * This is useful for determining multi-threaded structure padding or SIMD
+ * prefetch sizes.
+ *
+ * \returns the L1 cache line size of the CPU, in bytes.
+ *
+ * \since This function is available since SDL 2.0.0.
*/
extern DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void);
/**
- * This function returns true if the CPU has the RDTSC instruction.
+ * Determine whether the CPU has the RDTSC instruction.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has the RDTSC instruction or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasRDTSC(void);
/**
- * This function returns true if the CPU has AltiVec features.
+ * Determine whether the CPU has AltiVec features.
+ *
+ * This always returns false on CPUs that aren't using PowerPC instruction
+ * sets.
+ *
+ * \returns SDL_TRUE if the CPU has AltiVec features or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasAltiVec(void);
/**
- * This function returns true if the CPU has MMX features.
+ * Determine whether the CPU has MMX features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has MMX features or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasMMX(void);
/**
- * This function returns true if the CPU has 3DNow! features.
+ * Determine whether the CPU has 3DNow! features.
+ *
+ * This always returns false on CPUs that aren't using AMD instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has 3DNow! features or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_Has3DNow(void);
/**
- * This function returns true if the CPU has SSE features.
+ * Determine whether the CPU has SSE features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has SSE features or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE(void);
/**
- * This function returns true if the CPU has SSE2 features.
+ * Determine whether the CPU has SSE2 features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has SSE2 features or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE2(void);
/**
- * This function returns true if the CPU has SSE3 features.
+ * Determine whether the CPU has SSE3 features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has SSE3 features or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE3(void);
/**
- * This function returns true if the CPU has SSE4.1 features.
+ * Determine whether the CPU has SSE4.1 features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has SSE4.1 features or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE41(void);
/**
- * This function returns true if the CPU has SSE4.2 features.
+ * Determine whether the CPU has SSE4.2 features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has SSE4.2 features or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE42(void);
/**
- * This function returns true if the CPU has AVX features.
+ * Determine whether the CPU has AVX features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has AVX features or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX(void);
/**
- * This function returns true if the CPU has AVX2 features.
+ * Determine whether the CPU has AVX2 features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has AVX2 features or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.4.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX2(void);
/**
- * This function returns true if the CPU has AVX-512F (foundation) features.
+ * Determine whether the CPU has AVX-512F (foundation) features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has AVX-512F features or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.9.
+ *
+ * \sa SDL_HasAVX
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void);
/**
- * This function returns true if the CPU has NEON (ARM SIMD) features.
+ * Determine whether the CPU has ARM SIMD (ARMv6) features.
+ *
+ * This is different from ARM NEON, which is a different instruction set.
+ *
+ * This always returns false on CPUs that aren't using ARM instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has ARM SIMD features or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.12.
+ *
+ * \sa SDL_HasNEON
*/
+extern DECLSPEC SDL_bool SDLCALL SDL_HasARMSIMD(void);
+
+/**
+ * Determine whether the CPU has NEON (ARM SIMD) features.
+ *
+ * This always returns false on CPUs that aren't using ARM instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has ARM NEON features or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.6.
+ */
extern DECLSPEC SDL_bool SDLCALL SDL_HasNEON(void);
/**
- * This function returns the amount of RAM configured in the system, in MB.
+ * Determine whether the CPU has LSX (LOONGARCH SIMD) features.
+ *
+ * This always returns false on CPUs that aren't using LOONGARCH instruction
+ * sets.
+ *
+ * \returns SDL_TRUE if the CPU has LOONGARCH LSX features or SDL_FALSE if
+ * not.
+ *
+ * \since This function is available since SDL 2.24.0.
*/
+extern DECLSPEC SDL_bool SDLCALL SDL_HasLSX(void);
+
+/**
+ * Determine whether the CPU has LASX (LOONGARCH SIMD) features.
+ *
+ * This always returns false on CPUs that aren't using LOONGARCH instruction
+ * sets.
+ *
+ * \returns SDL_TRUE if the CPU has LOONGARCH LASX features or SDL_FALSE if
+ * not.
+ *
+ * \since This function is available since SDL 2.24.0.
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_HasLASX(void);
+
+/**
+ * Get the amount of RAM configured in the system.
+ *
+ * \returns the amount of RAM configured in the system in MiB.
+ *
+ * \since This function is available since SDL 2.0.1.
+ */
extern DECLSPEC int SDLCALL SDL_GetSystemRAM(void);
/**
- * \brief Report the alignment this system needs for SIMD allocations.
+ * Report the alignment this system needs for SIMD allocations.
*
* This will return the minimum number of bytes to which a pointer must be
- * aligned to be compatible with SIMD instructions on the current machine.
- * For example, if the machine supports SSE only, it will return 16, but if
- * it supports AVX-512F, it'll return 64 (etc). This only reports values for
- * instruction sets SDL knows about, so if your SDL build doesn't have
- * SDL_HasAVX512F(), then it might return 16 for the SSE support it sees and
- * not 64 for the AVX-512 instructions that exist but SDL doesn't know about.
- * Plan accordingly.
+ * aligned to be compatible with SIMD instructions on the current machine. For
+ * example, if the machine supports SSE only, it will return 16, but if it
+ * supports AVX-512F, it'll return 64 (etc). This only reports values for
+ * instruction sets SDL knows about, so if your SDL build doesn't have
+ * SDL_HasAVX512F(), then it might return 16 for the SSE support it sees and
+ * not 64 for the AVX-512 instructions that exist but SDL doesn't know about.
+ * Plan accordingly.
+ *
+ * \returns the alignment in bytes needed for available, known SIMD
+ * instructions.
+ *
+ * \since This function is available since SDL 2.0.10.
*/
extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
/**
- * \brief Allocate memory in a SIMD-friendly way.
+ * Allocate memory in a SIMD-friendly way.
*
* This will allocate a block of memory that is suitable for use with SIMD
- * instructions. Specifically, it will be properly aligned and padded for
- * the system's supported vector instructions.
+ * instructions. Specifically, it will be properly aligned and padded for the
+ * system's supported vector instructions.
*
- * The memory returned will be padded such that it is safe to read or write
- * an incomplete vector at the end of the memory block. This can be useful
- * so you don't have to drop back to a scalar fallback at the end of your
- * SIMD processing loop to deal with the final elements without overflowing
- * the allocated buffer.
+ * The memory returned will be padded such that it is safe to read or write an
+ * incomplete vector at the end of the memory block. This can be useful so you
+ * don't have to drop back to a scalar fallback at the end of your SIMD
+ * processing loop to deal with the final elements without overflowing the
+ * allocated buffer.
*
- * You must free this memory with SDL_FreeSIMD(), not free() or SDL_free()
- * or delete[], etc.
+ * You must free this memory with SDL_FreeSIMD(), not free() or SDL_free() or
+ * delete[], etc.
*
- * Note that SDL will only deal with SIMD instruction sets it is aware of;
- * for example, SDL 2.0.8 knows that SSE wants 16-byte vectors
- * (SDL_HasSSE()), and AVX2 wants 32 bytes (SDL_HasAVX2()), but doesn't
- * know that AVX-512 wants 64. To be clear: if you can't decide to use an
- * instruction set with an SDL_Has*() function, don't use that instruction
- * set with memory allocated through here.
+ * Note that SDL will only deal with SIMD instruction sets it is aware of; for
+ * example, SDL 2.0.8 knows that SSE wants 16-byte vectors (SDL_HasSSE()), and
+ * AVX2 wants 32 bytes (SDL_HasAVX2()), but doesn't know that AVX-512 wants
+ * 64. To be clear: if you can't decide to use an instruction set with an
+ * SDL_Has*() function, don't use that instruction set with memory allocated
+ * through here.
*
* SDL_AllocSIMD(0) will return a non-NULL pointer, assuming the system isn't
- * out of memory.
+ * out of memory, but you are not allowed to dereference it (because you only
+ * own zero bytes of that buffer).
*
- * \param len The length, in bytes, of the block to allocated. The actual
- * allocated block might be larger due to padding, etc.
- * \return Pointer to newly-allocated block, NULL if out of memory.
+ * \param len The length, in bytes, of the block to allocate. The actual
+ * allocated block might be larger due to padding, etc.
+ * \returns a pointer to the newly-allocated block, NULL if out of memory.
*
- * \sa SDL_SIMDAlignment
+ * \since This function is available since SDL 2.0.10.
+ *
+ * \sa SDL_SIMDGetAlignment
+ * \sa SDL_SIMDRealloc
* \sa SDL_SIMDFree
*/
extern DECLSPEC void * SDLCALL SDL_SIMDAlloc(const size_t len);
/**
- * \brief Deallocate memory obtained from SDL_SIMDAlloc
+ * Reallocate memory obtained from SDL_SIMDAlloc
*
* It is not valid to use this function on a pointer from anything but
- * SDL_SIMDAlloc(). It can't be used on pointers from malloc, realloc,
- * SDL_malloc, memalign, new[], etc.
+ * SDL_SIMDAlloc(). It can't be used on pointers from malloc, realloc,
+ * SDL_malloc, memalign, new[], etc.
*
+ * \param mem The pointer obtained from SDL_SIMDAlloc. This function also
+ * accepts NULL, at which point this function is the same as
+ * calling SDL_SIMDAlloc with a NULL pointer.
+ * \param len The length, in bytes, of the block to allocated. The actual
+ * allocated block might be larger due to padding, etc. Passing 0
+ * will return a non-NULL pointer, assuming the system isn't out of
+ * memory.
+ * \returns a pointer to the newly-reallocated block, NULL if out of memory.
+ *
+ * \since This function is available since SDL 2.0.14.
+ *
+ * \sa SDL_SIMDGetAlignment
+ * \sa SDL_SIMDAlloc
+ * \sa SDL_SIMDFree
+ */
+extern DECLSPEC void * SDLCALL SDL_SIMDRealloc(void *mem, const size_t len);
+
+/**
+ * Deallocate memory obtained from SDL_SIMDAlloc
+ *
+ * It is not valid to use this function on a pointer from anything but
+ * SDL_SIMDAlloc() or SDL_SIMDRealloc(). It can't be used on pointers from
+ * malloc, realloc, SDL_malloc, memalign, new[], etc.
+ *
* However, SDL_SIMDFree(NULL) is a legal no-op.
*
+ * The memory pointed to by `ptr` is no longer valid for access upon return,
+ * and may be returned to the system or reused by a future allocation. The
+ * pointer passed to this function is no longer safe to dereference once this
+ * function returns, and should be discarded.
+ *
+ * \param ptr The pointer, returned from SDL_SIMDAlloc or SDL_SIMDRealloc, to
+ * deallocate. NULL is a legal no-op.
+ *
+ * \since This function is available since SDL 2.0.10.
+ *
* \sa SDL_SIMDAlloc
+ * \sa SDL_SIMDRealloc
*/
extern DECLSPEC void SDLCALL SDL_SIMDFree(void *ptr);
-/* vi: set ts=4 sw=4 expandtab: */
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}
#endif
-#include "close_code.h"
+#include <SDL2/close_code.h>
#endif /* SDL_cpuinfo_h_ */
--- a/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_endian.h
+++ b/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_endian.h
@@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
- Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@@ -28,8 +28,25 @@
#ifndef SDL_endian_h_
#define SDL_endian_h_
-#include "SDL_stdinc.h"
+#include <SDL2/SDL_stdinc.h>
+#if defined(_MSC_VER) && (_MSC_VER >= 1400)
+/* As of Clang 11, '_m_prefetchw' is conflicting with the winnt.h's version,
+ so we define the needed '_m_prefetch' here as a pseudo-header, until the issue is fixed. */
+#ifdef __clang__
+#ifndef __PRFCHWINTRIN_H
+#define __PRFCHWINTRIN_H
+static __inline__ void __attribute__((__always_inline__, __nodebug__))
+_m_prefetch(void *__P)
+{+ __builtin_prefetch(__P, 0, 3 /* _MM_HINT_T0 */);
+}
+#endif /* __PRFCHWINTRIN_H */
+#endif /* __clang__ */
+
+#include <intrin.h>
+#endif
+
/**
* \name The two types of endianness
*/
@@ -42,11 +59,26 @@
#ifdef __linux__
#include <endian.h>
#define SDL_BYTEORDER __BYTE_ORDER
-#else /* __linux__ */
+#elif defined(__OpenBSD__) || defined(__DragonFly__)
+#include <endian.h>
+#define SDL_BYTEORDER BYTE_ORDER
+#elif defined(__FreeBSD__) || defined(__NetBSD__)
+#include <sys/endian.h>
+#define SDL_BYTEORDER BYTE_ORDER
+/* predefs from newer gcc and clang versions: */
+#elif defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_BIG_ENDIAN__) && defined(__BYTE_ORDER__)
+#if (__BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__)
+#define SDL_BYTEORDER SDL_LIL_ENDIAN
+#elif (__BYTE_ORDER__ == __ORDER_BIG_ENDIAN__)
+#define SDL_BYTEORDER SDL_BIG_ENDIAN
+#else
+#error Unsupported endianness
+#endif /**/
+#else
#if defined(__hppa__) || \
defined(__m68k__) || defined(mc68000) || defined(_M_M68K) || \
- (defined(__MIPS__) && defined(__MISPEB__)) || \
- defined(__ppc__) || defined(__POWERPC__) || defined(_M_PPC) || \
+ (defined(__MIPS__) && defined(__MIPSEB__)) || \
+ defined(__ppc__) || defined(__POWERPC__) || defined(__powerpc__) || defined(__PPC__) || \
defined(__sparc__)
#define SDL_BYTEORDER SDL_BIG_ENDIAN
#else
@@ -55,8 +87,30 @@
#endif /* __linux__ */
#endif /* !SDL_BYTEORDER */
+#ifndef SDL_FLOATWORDORDER /* Not defined in SDL_config.h? */
+/* predefs from newer gcc versions: */
+#if defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_BIG_ENDIAN__) && defined(__FLOAT_WORD_ORDER__)
+#if (__FLOAT_WORD_ORDER__ == __ORDER_LITTLE_ENDIAN__)
+#define SDL_FLOATWORDORDER SDL_LIL_ENDIAN
+#elif (__FLOAT_WORD_ORDER__ == __ORDER_BIG_ENDIAN__)
+#define SDL_FLOATWORDORDER SDL_BIG_ENDIAN
+#else
+#error Unsupported endianness
+#endif /**/
+#elif defined(__MAVERICK__)
+/* For Maverick, float words are always little-endian. */
+#define SDL_FLOATWORDORDER SDL_LIL_ENDIAN
+#elif (defined(__arm__) || defined(__thumb__)) && !defined(__VFP_FP__) && !defined(__ARM_EABI__)
+/* For FPA, float words are always big-endian. */
+#define SDL_FLOATWORDORDER SDL_BIG_ENDIAN
+#else
+/* By default, assume that floats words follow the memory system mode. */
+#define SDL_FLOATWORDORDER SDL_BYTEORDER
+#endif /* __FLOAT_WORD_ORDER__ */
+#endif /* !SDL_FLOATWORDORDER */
-#include "begin_code.h"
+
+#include <SDL2/begin_code.h>
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {@@ -65,8 +119,31 @@
/**
* \file SDL_endian.h
*/
-#if defined(__GNUC__) && defined(__i386__) && \
- !(__GNUC__ == 2 && __GNUC_MINOR__ == 95 /* broken gcc version */)
+
+/* various modern compilers may have builtin swap */
+#if defined(__GNUC__) || defined(__clang__)
+# define HAS_BUILTIN_BSWAP16 (_SDL_HAS_BUILTIN(__builtin_bswap16)) || \
+ (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 8))
+# define HAS_BUILTIN_BSWAP32 (_SDL_HAS_BUILTIN(__builtin_bswap32)) || \
+ (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3))
+# define HAS_BUILTIN_BSWAP64 (_SDL_HAS_BUILTIN(__builtin_bswap64)) || \
+ (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3))
+
+ /* this one is broken */
+# define HAS_BROKEN_BSWAP (__GNUC__ == 2 && __GNUC_MINOR__ <= 95)
+#else
+# define HAS_BUILTIN_BSWAP16 0
+# define HAS_BUILTIN_BSWAP32 0
+# define HAS_BUILTIN_BSWAP64 0
+# define HAS_BROKEN_BSWAP 0
+#endif
+
+#if HAS_BUILTIN_BSWAP16
+#define SDL_Swap16(x) __builtin_bswap16(x)
+#elif defined(_MSC_VER) && (_MSC_VER >= 1400)
+#pragma intrinsic(_byteswap_ushort)
+#define SDL_Swap16(x) _byteswap_ushort(x)
+#elif defined(__i386__) && !HAS_BROKEN_BSWAP
SDL_FORCE_INLINE Uint16
SDL_Swap16(Uint16 x)
{@@ -73,7 +150,7 @@
__asm__("xchgb %b0,%h0": "=q"(x):"0"(x));return x;
}
-#elif defined(__GNUC__) && defined(__x86_64__)
+#elif defined(__x86_64__)
SDL_FORCE_INLINE Uint16
SDL_Swap16(Uint16 x)
{@@ -80,7 +157,7 @@
__asm__("xchgb %b0,%h0": "=Q"(x):"0"(x));return x;
}
-#elif defined(__GNUC__) && (defined(__powerpc__) || defined(__ppc__))
+#elif (defined(__powerpc__) || defined(__ppc__))
SDL_FORCE_INLINE Uint16
SDL_Swap16(Uint16 x)
{@@ -89,7 +166,7 @@
__asm__("rlwimi %0,%2,8,16,23": "=&r"(result):"0"(x >> 8), "r"(x));return (Uint16)result;
}
-#elif defined(__GNUC__) && (defined(__M68000__) || defined(__M68020__)) && !defined(__mcoldfire__)
+#elif (defined(__m68k__) && !defined(__mcoldfire__))
SDL_FORCE_INLINE Uint16
SDL_Swap16(Uint16 x)
{@@ -97,7 +174,7 @@
return x;
}
#elif defined(__WATCOMC__) && defined(__386__)
-extern _inline Uint16 SDL_Swap16(Uint16);
+extern __inline Uint16 SDL_Swap16(Uint16);
#pragma aux SDL_Swap16 = \
"xchg al, ah" \
parm [ax] \
@@ -110,7 +187,12 @@
}
#endif
-#if defined(__GNUC__) && defined(__i386__)
+#if HAS_BUILTIN_BSWAP32
+#define SDL_Swap32(x) __builtin_bswap32(x)
+#elif defined(_MSC_VER) && (_MSC_VER >= 1400)
+#pragma intrinsic(_byteswap_ulong)
+#define SDL_Swap32(x) _byteswap_ulong(x)
+#elif defined(__i386__) && !HAS_BROKEN_BSWAP
SDL_FORCE_INLINE Uint32
SDL_Swap32(Uint32 x)
{@@ -117,7 +199,7 @@
__asm__("bswap %0": "=r"(x):"0"(x));return x;
}
-#elif defined(__GNUC__) && defined(__x86_64__)
+#elif defined(__x86_64__)
SDL_FORCE_INLINE Uint32
SDL_Swap32(Uint32 x)
{@@ -124,18 +206,18 @@
__asm__("bswapl %0": "=r"(x):"0"(x));return x;
}
-#elif defined(__GNUC__) && (defined(__powerpc__) || defined(__ppc__))
+#elif (defined(__powerpc__) || defined(__ppc__))
SDL_FORCE_INLINE Uint32
SDL_Swap32(Uint32 x)
{Uint32 result;
- __asm__("rlwimi %0,%2,24,16,23": "=&r"(result):"0"(x >> 24), "r"(x));- __asm__("rlwimi %0,%2,8,8,15": "=&r"(result):"0"(result), "r"(x));- __asm__("rlwimi %0,%2,24,0,7": "=&r"(result):"0"(result), "r"(x));+ __asm__("rlwimi %0,%2,24,16,23": "=&r"(result): "0" (x>>24), "r"(x));+ __asm__("rlwimi %0,%2,8,8,15" : "=&r"(result): "0" (result), "r"(x));+ __asm__("rlwimi %0,%2,24,0,7" : "=&r"(result): "0" (result), "r"(x));return result;
}
-#elif defined(__GNUC__) && (defined(__M68000__) || defined(__M68020__)) && !defined(__mcoldfire__)
+#elif (defined(__m68k__) && !defined(__mcoldfire__))
SDL_FORCE_INLINE Uint32
SDL_Swap32(Uint32 x)
{@@ -143,20 +225,11 @@
return x;
}
#elif defined(__WATCOMC__) && defined(__386__)
-extern _inline Uint32 SDL_Swap32(Uint32);
-#ifndef __SW_3 /* 486+ */
+extern __inline Uint32 SDL_Swap32(Uint32);
#pragma aux SDL_Swap32 = \
"bswap eax" \
parm [eax] \
modify [eax];
-#else /* 386-only */
-#pragma aux SDL_Swap32 = \
- "xchg al, ah" \
- "ror eax, 16" \
- "xchg al, ah" \
- parm [eax] \
- modify [eax];
-#endif
#else
SDL_FORCE_INLINE Uint32
SDL_Swap32(Uint32 x)
@@ -166,25 +239,28 @@
}
#endif
-#if defined(__GNUC__) && defined(__i386__)
+#if HAS_BUILTIN_BSWAP64
+#define SDL_Swap64(x) __builtin_bswap64(x)
+#elif defined(_MSC_VER) && (_MSC_VER >= 1400)
+#pragma intrinsic(_byteswap_uint64)
+#define SDL_Swap64(x) _byteswap_uint64(x)
+#elif defined(__i386__) && !HAS_BROKEN_BSWAP
SDL_FORCE_INLINE Uint64
SDL_Swap64(Uint64 x)
{- union
- {- struct
- {+ union {+ struct {Uint32 a, b;
} s;
Uint64 u;
} v;
v.u = x;
- __asm__("bswapl %0 ; bswapl %1 ; xchgl %0,%1": "=r"(v.s.a), "=r"(v.s.b):"0"(v.s.a),- "1"(v.s.
- b));
+ __asm__("bswapl %0 ; bswapl %1 ; xchgl %0,%1"+ : "=r"(v.s.a), "=r"(v.s.b)
+ : "0" (v.s.a), "1"(v.s.b));
return v.u;
}
-#elif defined(__GNUC__) && defined(__x86_64__)
+#elif defined(__x86_64__)
SDL_FORCE_INLINE Uint64
SDL_Swap64(Uint64 x)
{@@ -191,6 +267,14 @@
__asm__("bswapq %0": "=r"(x):"0"(x));return x;
}
+#elif defined(__WATCOMC__) && defined(__386__)
+extern __inline Uint64 SDL_Swap64(Uint64);
+#pragma aux SDL_Swap64 = \
+ "bswap eax" \
+ "bswap edx" \
+ "xchg eax,edx" \
+ parm [eax edx] \
+ modify [eax edx];
#else
SDL_FORCE_INLINE Uint64
SDL_Swap64(Uint64 x)
@@ -212,8 +296,7 @@
SDL_FORCE_INLINE float
SDL_SwapFloat(float x)
{- union
- {+ union {float f;
Uint32 ui32;
} swapper;
@@ -222,6 +305,11 @@
return swapper.f;
}
+/* remove extra macros */
+#undef HAS_BROKEN_BSWAP
+#undef HAS_BUILTIN_BSWAP16
+#undef HAS_BUILTIN_BSWAP32
+#undef HAS_BUILTIN_BSWAP64
/**
* \name Swap to native
@@ -229,22 +317,22 @@
*/
/* @{ */#if SDL_BYTEORDER == SDL_LIL_ENDIAN
-#define SDL_SwapLE16(X) (X)
-#define SDL_SwapLE32(X) (X)
-#define SDL_SwapLE64(X) (X)
+#define SDL_SwapLE16(X) (X)
+#define SDL_SwapLE32(X) (X)
+#define SDL_SwapLE64(X) (X)
#define SDL_SwapFloatLE(X) (X)
-#define SDL_SwapBE16(X) SDL_Swap16(X)
-#define SDL_SwapBE32(X) SDL_Swap32(X)
-#define SDL_SwapBE64(X) SDL_Swap64(X)
+#define SDL_SwapBE16(X) SDL_Swap16(X)
+#define SDL_SwapBE32(X) SDL_Swap32(X)
+#define SDL_SwapBE64(X) SDL_Swap64(X)
#define SDL_SwapFloatBE(X) SDL_SwapFloat(X)
#else
-#define SDL_SwapLE16(X) SDL_Swap16(X)
-#define SDL_SwapLE32(X) SDL_Swap32(X)
-#define SDL_SwapLE64(X) SDL_Swap64(X)
+#define SDL_SwapLE16(X) SDL_Swap16(X)
+#define SDL_SwapLE32(X) SDL_Swap32(X)
+#define SDL_SwapLE64(X) SDL_Swap64(X)
#define SDL_SwapFloatLE(X) SDL_SwapFloat(X)
-#define SDL_SwapBE16(X) (X)
-#define SDL_SwapBE32(X) (X)
-#define SDL_SwapBE64(X) (X)
+#define SDL_SwapBE16(X) (X)
+#define SDL_SwapBE32(X) (X)
+#define SDL_SwapBE64(X) (X)
#define SDL_SwapFloatBE(X) (X)
#endif
/* @} *//* Swap to native */
@@ -253,7 +341,7 @@
#ifdef __cplusplus
}
#endif
-#include "close_code.h"
+#include <SDL2/close_code.h>
#endif /* SDL_endian_h_ */
--- a/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_error.h
+++ b/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_error.h
@@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
- Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@@ -28,9 +28,9 @@
#ifndef SDL_error_h_
#define SDL_error_h_
-#include "SDL_stdinc.h"
+#include <SDL2/SDL_stdinc.h>
-#include "begin_code.h"
+#include <SDL2/begin_code.h>
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {@@ -37,9 +37,96 @@
#endif
/* Public functions */
-/* SDL_SetError() unconditionally returns -1. */
+
+
+/**
+ * Set the SDL error message for the current thread.
+ *
+ * Calling this function will replace any previous error message that was set.
+ *
+ * This function always returns -1, since SDL frequently uses -1 to signify an
+ * failing result, leading to this idiom:
+ *
+ * ```c
+ * if (error_code) {+ * return SDL_SetError("This operation has failed: %d", error_code);+ * }
+ * ```
+ *
+ * \param fmt a printf()-style message format string
+ * \param ... additional parameters matching % tokens in the `fmt` string, if
+ * any
+ * \returns always -1.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_ClearError
+ * \sa SDL_GetError
+ */
extern DECLSPEC int SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
+
+/**
+ * Retrieve a message about the last error that occurred on the current
+ * thread.
+ *
+ * It is possible for multiple errors to occur before calling SDL_GetError().
+ * Only the last error is returned.
+ *
+ * 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 SDL_GetError(). You should *not* use the results of
+ * SDL_GetError() to decide if an error has occurred! Sometimes SDL will set
+ * an error string even when reporting success.
+ *
+ * SDL will *not* clear the error string for successful API calls. You *must*
+ * check return values for failure cases before you can assume the error
+ * string applies.
+ *
+ * Error strings are set per-thread, so an error set in a different thread
+ * will not interfere with the current thread's operation.
+ *
+ * The returned string is internally allocated and must not be freed by the
+ * application.
+ *
+ * \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 SDL_ClearError(). 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 SDL_GetError().
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_ClearError
+ * \sa SDL_SetError
+ */
extern DECLSPEC const char *SDLCALL SDL_GetError(void);
+
+/**
+ * Get the last error message that was set for the current thread.
+ *
+ * This allows the caller to copy the error string into a provided buffer, but
+ * otherwise operates exactly the same as SDL_GetError().
+ *
+ * \param errstr A buffer to fill with the last error message that was set for
+ * the current thread
+ * \param maxlen The size of the buffer pointed to by the errstr parameter
+ * \returns the pointer passed in as the `errstr` parameter.
+ *
+ * \since This function is available since SDL 2.0.14.
+ *
+ * \sa SDL_GetError
+ */
+extern DECLSPEC char * SDLCALL SDL_GetErrorMsg(char *errstr, int maxlen);
+
+/**
+ * Clear any previous error message for this thread.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetError
+ * \sa SDL_SetError
+ */
extern DECLSPEC void SDLCALL SDL_ClearError(void);
/**
@@ -69,7 +156,7 @@
#ifdef __cplusplus
}
#endif
-#include "close_code.h"
+#include <SDL2/close_code.h>
#endif /* SDL_error_h_ */
--- a/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_events.h
+++ b/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_events.h
@@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
- Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@@ -28,18 +28,18 @@
#ifndef SDL_events_h_
#define SDL_events_h_
-#include "SDL_stdinc.h"
-#include "SDL_error.h"
-#include "SDL_video.h"
-#include "SDL_keyboard.h"
-#include "SDL_mouse.h"
-#include "SDL_joystick.h"
-#include "SDL_gamecontroller.h"
-#include "SDL_quit.h"
-#include "SDL_gesture.h"
-#include "SDL_touch.h"
+#include <SDL2/SDL_stdinc.h>
+#include <SDL2/SDL_error.h>
+#include <SDL2/SDL_video.h>
+#include <SDL2/SDL_keyboard.h>
+#include <SDL2/SDL_mouse.h>
+#include <SDL2/SDL_joystick.h>
+#include <SDL2/SDL_gamecontroller.h>
+#include <SDL2/SDL_quit.h>
+#include <SDL2/SDL_gesture.h>
+#include <SDL2/SDL_touch.h>
-#include "begin_code.h"
+#include <SDL2/begin_code.h>
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {@@ -50,7 +50,7 @@
#define SDL_PRESSED 1
/**
- * \brief The types of events that can be delivered.
+ * The types of events that can be delivered.
*/
typedef enum
{@@ -85,6 +85,8 @@
Called on Android in onResume()
*/
+ SDL_LOCALECHANGED, /**< The user's locale preferences have changed. */
+
/* Display events */
SDL_DISPLAYEVENT = 0x150, /**< Display state change */
@@ -100,6 +102,7 @@
SDL_KEYMAPCHANGED, /**< Keymap changed due to a system event such as an
input language or keyboard layout change.
*/
+ SDL_TEXTEDITING_EXT, /**< Extended keyboard text editing (composition) */
/* Mouse events */
SDL_MOUSEMOTION = 0x400, /**< Mouse moved */
@@ -115,6 +118,7 @@
SDL_JOYBUTTONUP, /**< Joystick button released */
SDL_JOYDEVICEADDED, /**< A new joystick has been inserted into the system */
SDL_JOYDEVICEREMOVED, /**< An opened joystick has been removed */
+ SDL_JOYBATTERYUPDATED, /**< Joystick battery level change */
/* Game controller events */
SDL_CONTROLLERAXISMOTION = 0x650, /**< Game controller axis motion */
@@ -123,6 +127,10 @@
SDL_CONTROLLERDEVICEADDED, /**< A new Game controller has been inserted into the system */
SDL_CONTROLLERDEVICEREMOVED, /**< An opened Game controller has been removed */
SDL_CONTROLLERDEVICEREMAPPED, /**< The controller mapping was updated */
+ SDL_CONTROLLERTOUCHPADDOWN, /**< Game controller touchpad was touched */
+ SDL_CONTROLLERTOUCHPADMOTION, /**< Game controller touchpad finger was moved */
+ SDL_CONTROLLERTOUCHPADUP, /**< Game controller touchpad finger was lifted */
+ SDL_CONTROLLERSENSORUPDATE, /**< Game controller sensor was updated */
/* Touch events */
SDL_FINGERDOWN = 0x700,
@@ -135,7 +143,7 @@
SDL_MULTIGESTURE,
/* Clipboard events */
- SDL_CLIPBOARDUPDATE = 0x900, /**< The clipboard changed */
+ SDL_CLIPBOARDUPDATE = 0x900, /**< The clipboard or primary selection changed */
/* Drag and drop events */
SDL_DROPFILE = 0x1000, /**< The system requests a file open */
@@ -154,6 +162,9 @@
SDL_RENDER_TARGETS_RESET = 0x2000, /**< The render targets have been reset and their contents need to be updated */
SDL_RENDER_DEVICE_RESET, /**< The device has been reset and all textures need to be recreated */
+ /* Internal events */
+ SDL_POLLSENTINEL = 0x7F00, /**< Signals the end of an event poll cycle */
+
/** Events ::SDL_USEREVENT through ::SDL_LASTEVENT are for your use,
* and should be allocated with SDL_RegisterEvents()
*/
@@ -234,6 +245,19 @@
Sint32 length; /**< The length of selected editing text */
} SDL_TextEditingEvent;
+/**
+ * \brief Extended keyboard text editing event structure (event.editExt.*) when text would be
+ * truncated if stored in the text buffer SDL_TextEditingEvent
+ */
+typedef struct SDL_TextEditingExtEvent
+{+ Uint32 type; /**< ::SDL_TEXTEDITING_EXT */
+ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
+ Uint32 windowID; /**< The window with keyboard focus, if any */
+ char* text; /**< The editing text, which should be freed with SDL_free(), and will not be NULL */
+ Sint32 start; /**< The start cursor of selected editing text */
+ Sint32 length; /**< The length of selected editing text */
+} SDL_TextEditingExtEvent;
#define SDL_TEXTINPUTEVENT_TEXT_SIZE (32)
/**
@@ -292,6 +316,10 @@
Sint32 x; /**< The amount scrolled horizontally, positive to the right and negative to the left */
Sint32 y; /**< The amount scrolled vertically, positive away from the user and negative toward the user */
Uint32 direction; /**< Set to one of the SDL_MOUSEWHEEL_* defines. When FLIPPED the values in X and Y will be opposite. Multiply by -1 to change them back */
+ float preciseX; /**< The amount scrolled horizontally, positive to the right and negative to the left, with float precision (added in 2.0.18) */
+ float preciseY; /**< The amount scrolled vertically, positive away from the user and negative toward the user, with float precision (added in 2.0.18) */
+ Sint32 mouseX; /**< X coordinate, relative to window (added in 2.26.0) */
+ Sint32 mouseY; /**< Y coordinate, relative to window (added in 2.26.0) */
} SDL_MouseWheelEvent;
/**
@@ -370,6 +398,16 @@
Sint32 which; /**< The joystick device index for the ADDED event, instance id for the REMOVED event */
} SDL_JoyDeviceEvent;
+/**
+ * \brief Joysick battery level change event structure (event.jbattery.*)
+ */
+typedef struct SDL_JoyBatteryEvent
+{+ Uint32 type; /**< ::SDL_JOYBATTERYUPDATED */
+ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
+ SDL_JoystickID which; /**< The joystick instance id */
+ SDL_JoystickPowerLevel level; /**< The joystick battery level */
+} SDL_JoyBatteryEvent;
/**
* \brief Game controller axis motion event structure (event.caxis.*)
@@ -414,6 +452,34 @@
} SDL_ControllerDeviceEvent;
/**
+ * \brief Game controller touchpad event structure (event.ctouchpad.*)
+ */
+typedef struct SDL_ControllerTouchpadEvent
+{+ Uint32 type; /**< ::SDL_CONTROLLERTOUCHPADDOWN or ::SDL_CONTROLLERTOUCHPADMOTION or ::SDL_CONTROLLERTOUCHPADUP */
+ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
+ SDL_JoystickID which; /**< The joystick instance id */
+ Sint32 touchpad; /**< The index of the touchpad */
+ Sint32 finger; /**< The index of the finger on the touchpad */
+ float x; /**< Normalized in the range 0...1 with 0 being on the left */
+ float y; /**< Normalized in the range 0...1 with 0 being at the top */
+ float pressure; /**< Normalized in the range 0...1 */
+} SDL_ControllerTouchpadEvent;
+
+/**
+ * \brief Game controller sensor event structure (event.csensor.*)
+ */
+typedef struct SDL_ControllerSensorEvent
+{+ Uint32 type; /**< ::SDL_CONTROLLERSENSORUPDATE */
+ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
+ SDL_JoystickID which; /**< The joystick instance id */
+ Sint32 sensor; /**< The type of the sensor, one of the values of ::SDL_SensorType */
+ float data[3]; /**< Up to 3 values from the sensor, as defined in SDL_sensor.h */
+ Uint64 timestamp_us; /**< The timestamp of the sensor reading in microseconds, if the hardware provides this information. */
+} SDL_ControllerSensorEvent;
+
+/**
* \brief Audio device event structure (event.adevice.*)
*/
typedef struct SDL_AudioDeviceEvent
@@ -442,6 +508,7 @@
float dx; /**< Normalized in the range -1...1 */
float dy; /**< Normalized in the range -1...1 */
float pressure; /**< Normalized in the range 0...1 */
+ Uint32 windowID; /**< The window underneath the finger, if any */
} SDL_TouchFingerEvent;
@@ -501,6 +568,7 @@
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Sint32 which; /**< The instance ID of the sensor */
float data[6]; /**< Up to 6 values from the sensor - additional values can be queried using SDL_SensorGetData() */
+ Uint64 timestamp_us; /**< The timestamp of the sensor reading in microseconds, if the hardware provides this information. */
} SDL_SensorEvent;
/**
@@ -556,56 +624,81 @@
*/
typedef union SDL_Event
{- Uint32 type; /**< Event type, shared with all events */
- SDL_CommonEvent common; /**< Common event data */
- SDL_DisplayEvent display; /**< Window event data */
- SDL_WindowEvent window; /**< Window event data */
- SDL_KeyboardEvent key; /**< Keyboard event data */
- SDL_TextEditingEvent edit; /**< Text editing event data */
- SDL_TextInputEvent text; /**< Text input event data */
- SDL_MouseMotionEvent motion; /**< Mouse motion event data */
- SDL_MouseButtonEvent button; /**< Mouse button event data */
- SDL_MouseWheelEvent wheel; /**< Mouse wheel event data */
- SDL_JoyAxisEvent jaxis; /**< Joystick axis event data */
- SDL_JoyBallEvent jball; /**< Joystick ball event data */
- SDL_JoyHatEvent jhat; /**< Joystick hat event data */
- SDL_JoyButtonEvent jbutton; /**< Joystick button event data */
- SDL_JoyDeviceEvent jdevice; /**< Joystick device change event data */
- SDL_ControllerAxisEvent caxis; /**< Game Controller axis event data */
- SDL_ControllerButtonEvent cbutton; /**< Game Controller button event data */
- SDL_ControllerDeviceEvent cdevice; /**< Game Controller device event data */
- SDL_AudioDeviceEvent adevice; /**< Audio device event data */
- SDL_SensorEvent sensor; /**< Sensor event data */
- SDL_QuitEvent quit; /**< Quit request event data */
- SDL_UserEvent user; /**< Custom event data */
- SDL_SysWMEvent syswm; /**< System dependent window event data */
- SDL_TouchFingerEvent tfinger; /**< Touch finger event data */
- SDL_MultiGestureEvent mgesture; /**< Gesture event data */
- SDL_DollarGestureEvent dgesture; /**< Gesture event data */
- SDL_DropEvent drop; /**< Drag and drop event data */
+ Uint32 type; /**< Event type, shared with all events */
+ SDL_CommonEvent common; /**< Common event data */
+ SDL_DisplayEvent display; /**< Display event data */
+ SDL_WindowEvent window; /**< Window event data */
+ SDL_KeyboardEvent key; /**< Keyboard event data */
+ SDL_TextEditingEvent edit; /**< Text editing event data */
+ SDL_TextEditingExtEvent editExt; /**< Extended text editing event data */
+ SDL_TextInputEvent text; /**< Text input event data */
+ SDL_MouseMotionEvent motion; /**< Mouse motion event data */
+ SDL_MouseButtonEvent button; /**< Mouse button event data */
+ SDL_MouseWheelEvent wheel; /**< Mouse wheel event data */
+ SDL_JoyAxisEvent jaxis; /**< Joystick axis event data */
+ SDL_JoyBallEvent jball; /**< Joystick ball event data */
+ SDL_JoyHatEvent jhat; /**< Joystick hat event data */
+ SDL_JoyButtonEvent jbutton; /**< Joystick button event data */
+ SDL_JoyDeviceEvent jdevice; /**< Joystick device change event data */
+ SDL_JoyBatteryEvent jbattery; /**< Joystick battery event data */
+ SDL_ControllerAxisEvent caxis; /**< Game Controller axis event data */
+ SDL_ControllerButtonEvent cbutton; /**< Game Controller button event data */
+ SDL_ControllerDeviceEvent cdevice; /**< Game Controller device event data */
+ SDL_ControllerTouchpadEvent ctouchpad; /**< Game Controller touchpad event data */
+ SDL_ControllerSensorEvent csensor; /**< Game Controller sensor event data */
+ SDL_AudioDeviceEvent adevice; /**< Audio device event data */
+ SDL_SensorEvent sensor; /**< Sensor event data */
+ SDL_QuitEvent quit; /**< Quit request event data */
+ SDL_UserEvent user; /**< Custom event data */
+ SDL_SysWMEvent syswm; /**< System dependent window event data */
+ SDL_TouchFingerEvent tfinger; /**< Touch finger event data */
+ SDL_MultiGestureEvent mgesture; /**< Gesture event data */
+ SDL_DollarGestureEvent dgesture; /**< Gesture event data */
+ SDL_DropEvent drop; /**< Drag and drop event data */
- /* This is necessary for ABI compatibility between Visual C++ and GCC
- Visual C++ will respect the push pack pragma and use 52 bytes for
- this structure, and GCC will use the alignment of the largest datatype
- within the union, which is 8 bytes.
+ /* This is necessary for ABI compatibility between Visual C++ and GCC.
+ Visual C++ will respect the push pack pragma and use 52 bytes (size of
+ SDL_TextEditingEvent, the largest structure for 32-bit and 64-bit
+ architectures) for this union, and GCC will use the alignment of the
+ largest datatype within the union, which is 8 bytes on 64-bit
+ architectures.
So... we'll add padding to force the size to be 56 bytes for both.
+
+ On architectures where pointers are 16 bytes, this needs rounding up to
+ the next multiple of 16, 64, and on architectures where pointers are
+ even larger the size of SDL_UserEvent will dominate as being 3 pointers.
*/
- Uint8 padding[56];
+ Uint8 padding[sizeof(void *) <= 8 ? 56 : sizeof(void *) == 16 ? 64 : 3 * sizeof(void *)];
} SDL_Event;
/* Make sure we haven't broken binary compatibility */
-SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == 56);
+SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NULL)->padding));
/* Function prototypes */
/**
- * Pumps the event loop, gathering events from the input devices.
+ * Pump the event loop, gathering events from the input devices.
*
- * This function updates the event queue and internal input device state.
+ * This function updates the event queue and internal input device state.
*
- * This should only be run in the thread that sets the video mode.
+ * **WARNING**: This should only be run in the thread that initialized the
+ * video subsystem, and for extra safety, you should consider only doing those
+ * things on the main thread in any case.
+ *
+ * SDL_PumpEvents() gathers all the pending input information from devices and
+ * places it in the event queue. Without calls to SDL_PumpEvents() no events
+ * would ever be placed on the queue. Often the need for calls to
+ * SDL_PumpEvents() is hidden from the user since SDL_PollEvent() and
+ * SDL_WaitEvent() implicitly call SDL_PumpEvents(). However, if you are not
+ * polling or waiting for events (e.g. you are filtering them), then you must
+ * call SDL_PumpEvents() to force an event queue update.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_PollEvent
+ * \sa SDL_WaitEvent
*/
extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
@@ -618,22 +711,42 @@
} SDL_eventaction;
/**
- * Checks the event queue for messages and optionally returns them.
+ * Check the event queue for messages and optionally return them.
*
- * If \c action is ::SDL_ADDEVENT, up to \c numevents events will be added to
- * the back of the event queue.
+ * `action` may be any of the following:
*
- * If \c action is ::SDL_PEEKEVENT, up to \c numevents events at the front
- * of the event queue, within the specified minimum and maximum type,
- * will be returned and will not be removed from the queue.
+ * - `SDL_ADDEVENT`: up to `numevents` events will be added to the back of the
+ * event queue.
+ * - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue,
+ * within the specified minimum and maximum type, will be returned to the
+ * caller and will _not_ be removed from the queue.
+ * - `SDL_GETEVENT`: up to `numevents` events at the front of the event queue,
+ * within the specified minimum and maximum type, will be returned to the
+ * caller and will be removed from the queue.
*
- * If \c action is ::SDL_GETEVENT, up to \c numevents events at the front
- * of the event queue, within the specified minimum and maximum type,
- * will be returned and will be removed from the queue.
+ * You may have to call SDL_PumpEvents() before calling this function.
+ * Otherwise, the events may not be ready to be filtered when you call
+ * SDL_PeepEvents().
*
- * \return The number of events actually stored, or -1 if there was an error.
+ * This function is thread-safe.
*
- * This function is thread-safe.
+ * \param events destination buffer for the retrieved events
+ * \param numevents if action is SDL_ADDEVENT, the number of events to add
+ * back to the event queue; if action is SDL_PEEKEVENT or
+ * SDL_GETEVENT, the maximum number of events to retrieve
+ * \param action action to take; see [[#action|Remarks]] for details
+ * \param minType minimum value of the event type to be considered;
+ * SDL_FIRSTEVENT is a safe choice
+ * \param maxType maximum value of the event type to be considered;
+ * SDL_LASTEVENT is a safe choice
+ * \returns the number of events actually stored or a negative error code on
+ * failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_PollEvent
+ * \sa SDL_PumpEvents
+ * \sa SDL_PushEvent
*/
extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
SDL_eventaction action,
@@ -641,113 +754,354 @@
/* @} */
/**
- * Checks to see if certain event types are in the event queue.
+ * Check for the existence of a certain event type in the event queue.
+ *
+ * If you need to check for a range of event types, use SDL_HasEvents()
+ * instead.
+ *
+ * \param type the type of event to be queried; see SDL_EventType for details
+ * \returns SDL_TRUE if events matching `type` are present, or SDL_FALSE if
+ * events matching `type` are not present.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HasEvents
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type);
+
+
+/**
+ * Check for the existence of certain event types in the event queue.
+ *
+ * If you need to check for a single event type, use SDL_HasEvent() instead.
+ *
+ * \param minType the low end of event type to be queried, inclusive; see
+ * SDL_EventType for details
+ * \param maxType the high end of event type to be queried, inclusive; see
+ * SDL_EventType for details
+ * \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are
+ * present, or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HasEvents
+ */
extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType);
/**
- * This function clears events from the event queue
- * This function only affects currently queued events. If you want to make
- * sure that all pending OS events are flushed, you can call SDL_PumpEvents()
- * on the main thread immediately before the flush call.
+ * Clear events of a specific type from the event queue.
+ *
+ * This will unconditionally remove any events from the queue that match
+ * `type`. If you need to remove a range of event types, use SDL_FlushEvents()
+ * instead.
+ *
+ * It's also normal to just ignore events you don't care about in your event
+ * loop without calling this function.
+ *
+ * This function only affects currently queued events. If you want to make
+ * sure that all pending OS events are flushed, you can call SDL_PumpEvents()
+ * on the main thread immediately before the flush call.
+ *
+ * \param type the type of event to be cleared; see SDL_EventType for details
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_FlushEvents
*/
extern DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
+
+/**
+ * Clear events of a range of types from the event queue.
+ *
+ * This will unconditionally remove any events from the queue that are in the
+ * range of `minType` to `maxType`, inclusive. If you need to remove a single
+ * event type, use SDL_FlushEvent() instead.
+ *
+ * It's also normal to just ignore events you don't care about in your event
+ * loop without calling this function.
+ *
+ * This function only affects currently queued events. If you want to make
+ * sure that all pending OS events are flushed, you can call SDL_PumpEvents()
+ * on the main thread immediately before the flush call.
+ *
+ * \param minType the low end of event type to be cleared, inclusive; see
+ * SDL_EventType for details
+ * \param maxType the high end of event type to be cleared, inclusive; see
+ * SDL_EventType for details
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_FlushEvent
+ */
extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
/**
- * \brief Polls for currently pending events.
+ * Poll for currently pending events.
*
- * \return 1 if there are any pending events, or 0 if there are none available.
+ * If `event` is not NULL, the next event is removed from the queue and stored
+ * in the SDL_Event structure pointed to by `event`. The 1 returned refers to
+ * this event, immediately stored in the SDL Event structure -- not an event
+ * to follow.
*
- * \param event If not NULL, the next event is removed from the queue and
- * stored in that area.
+ * If `event` is NULL, it simply returns 1 if there is an event in the queue,
+ * but will not remove it from the queue.
+ *
+ * As this function may implicitly call SDL_PumpEvents(), you can only call
+ * this function in the thread that set the video mode.
+ *
+ * SDL_PollEvent() is the favored way of receiving system events since it can
+ * be done from the main loop and does not suspend the main loop while waiting
+ * on an event to be posted.
+ *
+ * The common practice is to fully process the event queue once every frame,
+ * usually as a first step before updating the game's state:
+ *
+ * ```c
+ * while (game_is_still_running) {+ * SDL_Event event;
+ * while (SDL_PollEvent(&event)) { // poll until all events are handled!+ * // decide what to do with this event.
+ * }
+ *
+ * // update game state, draw the current frame
+ * }
+ * ```
+ *
+ * \param event the SDL_Event structure to be filled with the next event from
+ * the queue, or NULL
+ * \returns 1 if there is a pending event or 0 if there are none available.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetEventFilter
+ * \sa SDL_PeepEvents
+ * \sa SDL_PushEvent
+ * \sa SDL_SetEventFilter
+ * \sa SDL_WaitEvent
+ * \sa SDL_WaitEventTimeout
*/
extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
/**
- * \brief Waits indefinitely for the next available event.
+ * Wait indefinitely for the next available event.
*
- * \return 1, or 0 if there was an error while waiting for events.
+ * If `event` is not NULL, the next event is removed from the queue and stored
+ * in the SDL_Event structure pointed to by `event`.
*
- * \param event If not NULL, the next event is removed from the queue and
- * stored in that area.
+ * As this function may implicitly call SDL_PumpEvents(), you can only call
+ * this function in the thread that initialized the video subsystem.
+ *
+ * \param event the SDL_Event structure to be filled in with the next event
+ * from the queue, or NULL
+ * \returns 1 on success or 0 if there was an error while waiting for events;
+ * call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_PollEvent
+ * \sa SDL_PumpEvents
+ * \sa SDL_WaitEventTimeout
*/
extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
/**
- * \brief Waits until the specified timeout (in milliseconds) for the next
- * available event.
+ * Wait until the specified timeout (in milliseconds) for the next available
+ * event.
*
- * \return 1, or 0 if there was an error while waiting for events.
+ * If `event` is not NULL, the next event is removed from the queue and stored
+ * in the SDL_Event structure pointed to by `event`.
*
- * \param event If not NULL, the next event is removed from the queue and
- * stored in that area.
- * \param timeout The timeout (in milliseconds) to wait for next event.
+ * As this function may implicitly call SDL_PumpEvents(), you can only call
+ * this function in the thread that initialized the video subsystem.
+ *
+ * \param event the SDL_Event structure to be filled in with the next event
+ * from the queue, or NULL
+ * \param timeout the maximum number of milliseconds to wait for the next
+ * available event
+ * \returns 1 on success or 0 if there was an error while waiting for events;
+ * call SDL_GetError() for more information. This also returns 0 if
+ * the timeout elapsed without an event arriving.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_PollEvent
+ * \sa SDL_PumpEvents
+ * \sa SDL_WaitEvent
*/
extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event,
int timeout);
/**
- * \brief Add an event to the event queue.
+ * Add an event to the event queue.
*
- * \return 1 on success, 0 if the event was filtered, or -1 if the event queue
- * was full or there was some other error.
+ * The event queue can actually be used as a two way communication channel.
+ * Not only can events be read from the queue, but the user can also push
+ * their own events onto it. `event` is a pointer to the event structure you
+ * wish to push onto the queue. The event is copied into the queue, and the
+ * caller may dispose of the memory pointed to after SDL_PushEvent() returns.
+ *
+ * Note: Pushing device input events onto the queue doesn't modify the state
+ * of the device within SDL.
+ *
+ * This function is thread-safe, and can be called from other threads safely.
+ *
+ * Note: Events pushed onto the queue with SDL_PushEvent() get passed through
+ * the event filter but events added with SDL_PeepEvents() do not.
+ *
+ * For pushing application-specific events, please use SDL_RegisterEvents() to
+ * get an event type that does not conflict with other code that also wants
+ * its own custom event types.
+ *
+ * \param event the SDL_Event to be added to the queue
+ * \returns 1 on success, 0 if the event was filtered, or a negative error
+ * code on failure; call SDL_GetError() for more information. A
+ * common reason for error is the event queue being full.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_PeepEvents
+ * \sa SDL_PollEvent
+ * \sa SDL_RegisterEvents
*/
extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
+/**
+ * A function pointer used for callbacks that watch the event queue.
+ *
+ * \param userdata what was passed as `userdata` to SDL_SetEventFilter()
+ * or SDL_AddEventWatch, etc
+ * \param event the event that triggered the callback
+ * \returns 1 to permit event to be added to the queue, and 0 to disallow
+ * it. When used with SDL_AddEventWatch, the return value is ignored.
+ *
+ * \sa SDL_SetEventFilter
+ * \sa SDL_AddEventWatch
+ */
typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
/**
- * Sets up a filter to process all events before they change internal state and
- * are posted to the internal event queue.
+ * Set up a filter to process all events before they change internal state and
+ * are posted to the internal event queue.
*
- * The filter is prototyped as:
- * \code
- * int SDL_EventFilter(void *userdata, SDL_Event * event);
- * \endcode
+ * If the filter function returns 1 when called, then the event will be added
+ * to the internal queue. If it returns 0, then the event will be dropped from
+ * the queue, but the internal state will still be updated. This allows
+ * selective filtering of dynamically arriving events.
*
- * If the filter returns 1, then the event will be added to the internal queue.
- * If it returns 0, then the event will be dropped from the queue, but the
- * internal state will still be updated. This allows selective filtering of
- * dynamically arriving events.
+ * **WARNING**: Be very careful of what you do in the event filter function,
+ * as it may run in a different thread!
*
- * \warning Be very careful of what you do in the event filter function, as
- * it may run in a different thread!
+ * On platforms that support it, if the quit event is generated by an
+ * interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the
+ * application at the next event poll.
*
- * There is one caveat when dealing with the ::SDL_QuitEvent event type. The
- * event filter is only called when the window manager desires to close the
- * application window. If the event filter returns 1, then the window will
- * be closed, otherwise the window will remain open if possible.
+ * There is one caveat when dealing with the ::SDL_QuitEvent event type. The
+ * event filter is only called when the window manager desires to close the
+ * application window. If the event filter returns 1, then the window will be
+ * closed, otherwise the window will remain open if possible.
*
- * If the quit event is generated by an interrupt signal, it will bypass the
- * internal queue and be delivered to the application at the next event poll.
+ * Note: Disabled events never make it to the event filter function; see
+ * SDL_EventState().
+ *
+ * Note: If you just want to inspect events without filtering, you should use
+ * SDL_AddEventWatch() instead.
+ *
+ * Note: Events pushed onto the queue with SDL_PushEvent() get passed through
+ * the event filter, but events pushed onto the queue with SDL_PeepEvents() do
+ * not.
+ *
+ * \param filter An SDL_EventFilter function to call when an event happens
+ * \param userdata a pointer that is passed to `filter`
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AddEventWatch
+ * \sa SDL_EventState
+ * \sa SDL_GetEventFilter
+ * \sa SDL_PeepEvents
+ * \sa SDL_PushEvent
*/
extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
void *userdata);
/**
- * Return the current event filter - can be used to "chain" filters.
- * If there is no event filter set, this function returns SDL_FALSE.
+ * Query the current event filter.
+ *
+ * This function can be used to "chain" filters, by saving the existing filter
+ * before replacing it with a function that will call that saved filter.
+ *
+ * \param filter the current callback function will be stored here
+ * \param userdata the pointer that is passed to the current event filter will
+ * be stored here
+ * \returns SDL_TRUE on success or SDL_FALSE if there is no event filter set.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_SetEventFilter
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
void **userdata);
/**
- * Add a function which is called when an event is added to the queue.
+ * Add a callback to be triggered when an event is added to the event queue.
+ *
+ * `filter` will be called when an event happens, and its return value is
+ * ignored.
+ *
+ * **WARNING**: Be very careful of what you do in the event filter function,
+ * as it may run in a different thread!
+ *
+ * If the quit event is generated by a signal (e.g. SIGINT), it will bypass
+ * the internal queue and be delivered to the watch callback immediately, and
+ * arrive at the next event poll.
+ *
+ * Note: the callback is called for events posted by the user through
+ * SDL_PushEvent(), but not for disabled events, nor for events by a filter
+ * callback set with SDL_SetEventFilter(), nor for events posted by the user
+ * through SDL_PeepEvents().
+ *
+ * \param filter an SDL_EventFilter function to call when an event happens.
+ * \param userdata a pointer that is passed to `filter`
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_DelEventWatch
+ * \sa SDL_SetEventFilter
*/
extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter,
void *userdata);
/**
- * Remove an event watch function added with SDL_AddEventWatch()
+ * Remove an event watch callback added with SDL_AddEventWatch().
+ *
+ * This function takes the same input as SDL_AddEventWatch() to identify and
+ * delete the corresponding callback.
+ *
+ * \param filter the function originally passed to SDL_AddEventWatch()
+ * \param userdata the pointer originally passed to SDL_AddEventWatch()
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AddEventWatch
*/
extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter,
void *userdata);
/**
- * Run the filter function on the current event queue, removing any
- * events for which the filter returns 0.
+ * Run a specific filter function on the current event queue, removing any
+ * events for which the filter returns 0.
+ *
+ * See SDL_SetEventFilter() for more information. Unlike SDL_SetEventFilter(),
+ * this function does not change the filter permanently, it only uses the
+ * supplied filter until this function returns.
+ *
+ * \param filter the SDL_EventFilter function to call when an event happens
+ * \param userdata a pointer that is passed to `filter`
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetEventFilter
+ * \sa SDL_SetEventFilter
*/
extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
void *userdata);
@@ -759,13 +1113,23 @@
#define SDL_ENABLE 1
/**
- * This function allows you to set the state of processing certain events.
- * - If \c state is set to ::SDL_IGNORE, that event will be automatically
- * dropped from the event queue and will not be filtered.
- * - If \c state is set to ::SDL_ENABLE, that event will be processed
- * normally.
- * - If \c state is set to ::SDL_QUERY, SDL_EventState() will return the
- * current processing state of the specified event.
+ * Set the state of processing events by type.
+ *
+ * `state` may be any of the following:
+ *
+ * - `SDL_QUERY`: returns the current processing state of the specified event
+ * - `SDL_IGNORE` (aka `SDL_DISABLE`): the event will automatically be dropped
+ * from the event queue and will not be filtered
+ * - `SDL_ENABLE`: the event will be processed normally
+ *
+ * \param type the type of event; see SDL_EventType for details
+ * \param state how to process the event
+ * \returns `SDL_DISABLE` or `SDL_ENABLE`, representing the processing state
+ * of the event before this function makes any changes to it.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetEventState
*/
extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state);
/* @} */
@@ -772,11 +1136,22 @@
#define SDL_GetEventState(type) SDL_EventState(type, SDL_QUERY)
/**
- * This function allocates a set of user-defined events, and returns
- * the beginning event number for that set of events.
+ * Allocate a set of user-defined events, and return the beginning event
+ * number for that set of events.
*
- * If there aren't enough user-defined events left, this function
- * returns (Uint32)-1
+ * Calling this function with `numevents` <= 0 is an error and will return
+ * (Uint32)-1.
+ *
+ * Note, (Uint32)-1 means the maximum unsigned 32-bit integer value (or
+ * 0xFFFFFFFF), but is clearer to write.
+ *
+ * \param numevents the number of events to be allocated
+ * \returns the beginning event number, or (Uint32)-1 if there are not enough
+ * user-defined events left.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_PushEvent
*/
extern DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
@@ -784,7 +1159,7 @@
#ifdef __cplusplus
}
#endif
-#include "close_code.h"
+#include <SDL2/close_code.h>
#endif /* SDL_events_h_ */
--- a/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_filesystem.h
+++ b/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_filesystem.h
@@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
- Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@@ -28,9 +28,9 @@
#ifndef SDL_filesystem_h_
#define SDL_filesystem_h_
-#include "SDL_stdinc.h"
+#include <SDL2/SDL_stdinc.h>
-#include "begin_code.h"
+#include <SDL2/begin_code.h>
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
@@ -38,89 +38,102 @@
#endif
/**
- * \brief Get the path where the application resides.
+ * Get the directory where the application was run from.
*
- * Get the "base path". This is the directory where the application was run
- * from, which is probably the installation directory, and may or may not
- * be the process's current working directory.
+ * This is not necessarily a fast call, so you should call this once near
+ * startup and save the string if you need it.
*
- * This returns an absolute path in UTF-8 encoding, and is guaranteed to
- * end with a path separator ('\\' on Windows, '/' most other places).+ * **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.
*
- * The pointer returned by this function is owned by you. Please call
- * SDL_free() on the pointer when you are done with it, or it will be a
- * memory leak. This is not necessarily a fast call, though, so you should
- * call this once near startup and save the string if you need it.
+ * Supported values for the SDL_FILESYSTEM_BASE_DIR_TYPE property (Given an
+ * application in /Applications/SDLApp/MyApp.app):
*
- * Some platforms can't determine the application's path, and on other
- * platforms, this might be meaningless. In such cases, this function will
- * return NULL.
+ * - `resource`: bundle resource directory (the default). For example:
+ * `/Applications/SDLApp/MyApp.app/Contents/Resources`
+ * - `bundle`: the Bundle directory. For example:
+ * `/Applications/SDLApp/MyApp.app/`
+ * - `parent`: the containing directory of the bundle. For example:
+ * `/Applications/SDLApp/`
*
- * \return String of base dir in UTF-8 encoding, or NULL on error.
+ * **Nintendo 3DS Specific Functionality**: This function returns "romfs"
+ * directory of the application as it is uncommon to store resources outside
+ * the executable. As such it is not a writable directory.
*
+ * The returned path is guaranteed to end with a path separator ('\' on+ * Windows, '/' on most other platforms).
+ *
+ * The pointer returned is owned by the caller. Please call SDL_free() on the
+ * pointer when done with it.
+ *
+ * \returns an absolute path in UTF-8 encoding to the application data
+ * directory. NULL will be returned on error or when the platform
+ * doesn't implement this functionality, call SDL_GetError() for more
+ * information.
+ *
+ * \since This function is available since SDL 2.0.1.
+ *
* \sa SDL_GetPrefPath
*/
extern DECLSPEC char *SDLCALL SDL_GetBasePath(void);
/**
- * \brief Get the user-and-app-specific path where files can be written.
+ * Get the user-and-app-specific path where files can be written.
*
* Get the "pref dir". This is meant to be where users can write personal
- * files (preferences and save games, etc) that are specific to your
- * application. This directory is unique per user, per application.
+ * files (preferences and save games, etc) that are specific to your
+ * application. This directory is unique per user, per application.
*
- * This function will decide the appropriate location in the native filesystem,
- * create the directory if necessary, and return a string of the absolute
- * path to the directory in UTF-8 encoding.
+ * This function will decide the appropriate location in the native
+ * filesystem, create the directory if necessary, and return a string of the
+ * absolute path to the directory in UTF-8 encoding.
*
* On Windows, the string might look like:
- * "C:\\Users\\bob\\AppData\\Roaming\\My Company\\My Program Name\\"
*
+ * `C:\\Users\\bob\\AppData\\Roaming\\My Company\\My Program Name\\`
+ *
* On Linux, the string might look like:
- * "/home/bob/.local/share/My Program Name/"
*
+ * `/home/bob/.local/share/My Program Name/`
+ *
* On Mac OS X, the string might look like:
- * "/Users/bob/Library/Application Support/My Program Name/"
*
- * (etc.)
+ * `/Users/bob/Library/Application Support/My Program Name/`
*
- * You specify the name of your organization (if it's not a real organization,
- * your name or an Internet domain you own might do) and the name of your
- * application. These should be untranslated proper names.
+ * You should assume the path returned by this function is the only safe place
+ * to write files (and that SDL_GetBasePath(), while it might be writable, or
+ * even the parent of the returned path, isn'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:
+ * 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.
- * - Unicode characters are legal, as long as it's UTF-8 encoded, but...
- * - ...only use letters, numbers, and spaces. Avoid punctuation like
- * "Game Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient.
+ * - 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.
+ * - Unicode characters are legal, as long as it's UTF-8 encoded, but...
+ * - ...only use letters, numbers, and spaces. Avoid punctuation like "Game
+ * Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient.
*
- * This returns an absolute path in UTF-8 encoding, and is guaranteed to
- * end with a path separator ('\\' on Windows, '/' most other places).+ * The returned path is guaranteed to end with a path separator ('\' on+ * Windows, '/' on most other platforms).
*
- * The pointer returned by this function is owned by you. Please call
- * SDL_free() on the pointer when you are done with it, or it will be a
- * memory leak. This is not necessarily a fast call, though, so you should
- * call this once near startup and save the string if you need it.
+ * The pointer returned is owned by the caller. Please call SDL_free() on the
+ * pointer when done with it.
*
- * You should assume the path returned by this function is the only safe
- * place to write files (and that SDL_GetBasePath(), while it might be
- * writable, or even the parent of the returned path, aren't where you
- * should be writing things).
+ * \param org the name of your organization
+ * \param app the name of your application
+ * \returns a UTF-8 string of the user directory in platform-dependent
+ * notation. NULL if there's a problem (creating directory failed,
+ * etc.).
*
- * Some platforms can't determine the pref path, and on other
- * platforms, this might be meaningless. In such cases, this function will
- * return NULL.
+ * \since This function is available since SDL 2.0.1.
*
- * \param org The name of your organization.
- * \param app The name of your application.
- * \return UTF-8 string of user dir in platform-dependent notation. NULL
- * if there's a problem (creating directory failed, etc).
- *
* \sa SDL_GetBasePath
*/
extern DECLSPEC char *SDLCALL SDL_GetPrefPath(const char *org, const char *app);
@@ -129,7 +142,7 @@
#ifdef __cplusplus
}
#endif
-#include "close_code.h"
+#include <SDL2/close_code.h>
#endif /* SDL_filesystem_h_ */
--- a/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_gamecontroller.h
+++ b/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_gamecontroller.h
@@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
- Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@@ -28,12 +28,13 @@
#ifndef SDL_gamecontroller_h_
#define SDL_gamecontroller_h_
-#include "SDL_stdinc.h"
-#include "SDL_error.h"
-#include "SDL_rwops.h"
-#include "SDL_joystick.h"
+#include <SDL2/SDL_stdinc.h>
+#include <SDL2/SDL_error.h>
+#include <SDL2/SDL_rwops.h>
+#include <SDL2/SDL_sensor.h>
+#include <SDL2/SDL_joystick.h>
-#include "begin_code.h"
+#include <SDL2/begin_code.h>
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {@@ -57,6 +58,23 @@
struct _SDL_GameController;
typedef struct _SDL_GameController SDL_GameController;
+typedef enum
+{+ SDL_CONTROLLER_TYPE_UNKNOWN = 0,
+ SDL_CONTROLLER_TYPE_XBOX360,
+ SDL_CONTROLLER_TYPE_XBOXONE,
+ SDL_CONTROLLER_TYPE_PS3,
+ SDL_CONTROLLER_TYPE_PS4,
+ SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_PRO,
+ SDL_CONTROLLER_TYPE_VIRTUAL,
+ SDL_CONTROLLER_TYPE_PS5,
+ SDL_CONTROLLER_TYPE_AMAZON_LUNA,
+ SDL_CONTROLLER_TYPE_GOOGLE_STADIA,
+ SDL_CONTROLLER_TYPE_NVIDIA_SHIELD,
+ SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_LEFT,
+ SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT,
+ SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_PAIR
+} SDL_GameControllerType;
typedef enum
{@@ -87,6 +105,8 @@
/**
* To count the number of game controllers in the system for the following:
+ *
+ * ```c
* int nJoysticks = SDL_NumJoysticks();
* int nGameControllers = 0;
* for (int i = 0; i < nJoysticks; i++) {@@ -94,6 +114,7 @@
* nGameControllers++;
* }
* }
+ * ```
*
* Using the SDL_HINT_GAMECONTROLLERCONFIG hint or the SDL_GameControllerAddMapping() you can add support for controllers SDL is unaware of or cause an existing controller to have a different binding. The format is:
* guid,name,mappings
@@ -107,17 +128,39 @@
* Buttons can be used as a controller axis and vice versa.
*
* This string shows an example of a valid mapping for a controller
- * "03000000341a00003608000000000000,PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7",
*
+ * ```c
+ * "03000000341a00003608000000000000,PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7",
+ * ```
*/
/**
- * Load a set of mappings from a seekable SDL data stream (memory or file), filtered by the current SDL_GetPlatform()
- * A community sourced database of controllers is available at https://raw.github.com/gabomdq/SDL_GameControllerDB/master/gamecontrollerdb.txt
+ * Load a set of Game Controller mappings from a seekable SDL data stream.
*
- * If \c freerw is non-zero, the stream will be closed after being read.
- *
- * \return number of mappings added, -1 on error
+ * You can call this function several times, if needed, to load different
+ * database files.
+ *
+ * If a new mapping is loaded for an already known controller GUID, the later
+ * version will overwrite the one currently loaded.
+ *
+ * Mappings not belonging to the current platform or with no platform field
+ * specified will be ignored (i.e. mappings for Linux will be ignored in
+ * Windows, etc).
+ *
+ * This function will load the text database entirely in memory before
+ * processing it, so take this into consideration if you are in a memory
+ * constrained environment.
+ *
+ * \param rw the data stream for the mappings to be added
+ * \param freerw non-zero to close the stream after being read
+ * \returns the number of mappings added or -1 on error; call SDL_GetError()
+ * for more information.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_GameControllerAddMapping
+ * \sa SDL_GameControllerAddMappingsFromFile
+ * \sa SDL_GameControllerMappingForGUID
*/
extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw, int freerw);
@@ -129,133 +172,421 @@
#define SDL_GameControllerAddMappingsFromFile(file) SDL_GameControllerAddMappingsFromRW(SDL_RWFromFile(file, "rb"), 1)
/**
- * Add or update an existing mapping configuration
+ * Add support for controllers that SDL is unaware of or to cause an existing
+ * controller to have a different binding.
*
- * \return 1 if mapping is added, 0 if updated, -1 on error
+ * The mapping string has the format "GUID,name,mapping", where GUID is the
+ * string value from SDL_JoystickGetGUIDString(), name is the human readable
+ * string for the device and mappings are controller mappings to joystick
+ * ones. Under Windows there is a reserved GUID of "xinput" that covers all
+ * XInput devices. The mapping format for joystick is: {| |bX |a joystick+ * button, index X |- |hX.Y |hat X with value Y |- |aX |axis X of the joystick
+ * |} Buttons can be used as a controller axes and vice versa.
+ *
+ * This string shows an example of a valid mapping for a controller:
+ *
+ * ```c
+ * "341a3608000000000000504944564944,Afterglow PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7"
+ * ```
+ *
+ * \param mappingString the mapping string
+ * \returns 1 if a new mapping is added, 0 if an existing mapping is updated,
+ * -1 on error; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerMapping
+ * \sa SDL_GameControllerMappingForGUID
*/
extern DECLSPEC int SDLCALL SDL_GameControllerAddMapping(const char* mappingString);
/**
- * Get the number of mappings installed
+ * Get the number of mappings installed.
*
- * \return the number of mappings
+ * \returns the number of mappings.
+ *
+ * \since This function is available since SDL 2.0.6.
*/
extern DECLSPEC int SDLCALL SDL_GameControllerNumMappings(void);
/**
- * Get the mapping at a particular index.
+ * Get the mapping at a particular index.
*
- * \return the mapping string. Must be freed with SDL_free(). Returns NULL if the index is out of range.
+ * \returns the mapping string. Must be freed with SDL_free(). Returns NULL if
+ * the index is out of range.
+ *
+ * \since This function is available since SDL 2.0.6.
*/
extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForIndex(int mapping_index);
/**
- * Get a mapping string for a GUID
+ * Get the game controller mapping string for a given GUID.
*
- * \return the mapping string. Must be freed with SDL_free(). Returns NULL if no mapping is available
+ * The returned string must be freed with SDL_free().
+ *
+ * \param guid a structure containing the GUID for which a mapping is desired
+ * \returns a mapping string or NULL on error; call SDL_GetError() for more
+ * information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickGetDeviceGUID
+ * \sa SDL_JoystickGetGUID
*/
extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForGUID(SDL_JoystickGUID guid);
/**
- * Get a mapping string for an open GameController
+ * Get the current mapping of a Game Controller.
*
- * \return the mapping string. Must be freed with SDL_free(). Returns NULL if no mapping is available
+ * The returned string must be freed with SDL_free().
+ *
+ * Details about mappings are discussed with SDL_GameControllerAddMapping().
+ *
+ * \param gamecontroller the game controller you want to get the current
+ * mapping for
+ * \returns a string that has the controller's mapping or NULL if no mapping
+ * is available; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerAddMapping
+ * \sa SDL_GameControllerMappingForGUID
*/
-extern DECLSPEC char * SDLCALL SDL_GameControllerMapping(SDL_GameController * gamecontroller);
+extern DECLSPEC char * SDLCALL SDL_GameControllerMapping(SDL_GameController *gamecontroller);
/**
- * Is the joystick on this index supported by the game controller interface?
+ * Check if the given joystick is supported by the game controller interface.
+ *
+ * `joystick_index` is the same as the `device_index` passed to
+ * SDL_JoystickOpen().
+ *
+ * \param joystick_index the device_index of a device, up to
+ * SDL_NumJoysticks()
+ * \returns SDL_TRUE if the given joystick is supported by the game controller
+ * interface, SDL_FALSE if it isn't or it's an invalid index.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerNameForIndex
+ * \sa SDL_GameControllerOpen
*/
extern DECLSPEC SDL_bool SDLCALL SDL_IsGameController(int joystick_index);
/**
- * Get the implementation dependent name of a game controller.
- * This can be called before any controllers are opened.
- * If no name can be found, this function returns NULL.
+ * Get the implementation dependent name for the game controller.
+ *
+ * This function can be called before any controllers are opened.
+ *
+ * `joystick_index` is the same as the `device_index` passed to
+ * SDL_JoystickOpen().
+ *
+ * \param joystick_index the device_index of a device, from zero to
+ * SDL_NumJoysticks()-1
+ * \returns the implementation-dependent name for the game controller, or NULL
+ * if there is no name or the index is invalid.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerName
+ * \sa SDL_GameControllerOpen
+ * \sa SDL_IsGameController
*/
extern DECLSPEC const char *SDLCALL SDL_GameControllerNameForIndex(int joystick_index);
/**
- * Get the mapping of a game controller.
- * This can be called before any controllers are opened.
+ * Get the implementation dependent path for the game controller.
*
- * \return the mapping string. Must be freed with SDL_free(). Returns NULL if no mapping is available
+ * This function can be called before any controllers are opened.
+ *
+ * `joystick_index` is the same as the `device_index` passed to
+ * SDL_JoystickOpen().
+ *
+ * \param joystick_index the device_index of a device, from zero to
+ * SDL_NumJoysticks()-1
+ * \returns the implementation-dependent path for the game controller, or NULL
+ * if there is no path or the index is invalid.
+ *
+ * \since This function is available since SDL 2.24.0.
+ *
+ * \sa SDL_GameControllerPath
*/
+extern DECLSPEC const char *SDLCALL SDL_GameControllerPathForIndex(int joystick_index);
+
+/**
+ * Get the type of a game controller.
+ *
+ * This can be called before any controllers are opened.
+ *
+ * \param joystick_index the device_index of a device, from zero to
+ * SDL_NumJoysticks()-1
+ * \returns the controller type.
+ *
+ * \since This function is available since SDL 2.0.12.
+ */
+extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerTypeForIndex(int joystick_index);
+
+/**
+ * Get the mapping of a game controller.
+ *
+ * This can be called before any controllers are opened.
+ *
+ * \param joystick_index the device_index of a device, from zero to
+ * SDL_NumJoysticks()-1
+ * \returns the mapping string. Must be freed with SDL_free(). Returns NULL if
+ * no mapping is available.
+ *
+ * \since This function is available since SDL 2.0.9.
+ */
extern DECLSPEC char *SDLCALL SDL_GameControllerMappingForDeviceIndex(int joystick_index);
/**
- * Open a game controller for use.
- * The index passed as an argument refers to the N'th game controller on the system.
- * This index is not the value which will identify this controller in future
- * controller events. The joystick's instance id (::SDL_JoystickID) will be
- * used there instead.
+ * Open a game controller for use.
*
- * \return A controller identifier, or NULL if an error occurred.
+ * `joystick_index` is the same as the `device_index` passed to
+ * SDL_JoystickOpen().
+ *
+ * The index passed as an argument refers to the N'th game controller on the
+ * system. This index is not the value which will identify this controller in
+ * future controller events. The joystick's instance id (SDL_JoystickID) will
+ * be used there instead.
+ *
+ * \param joystick_index the device_index of a device, up to
+ * SDL_NumJoysticks()
+ * \returns a gamecontroller identifier or NULL if an error occurred; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerClose
+ * \sa SDL_GameControllerNameForIndex
+ * \sa SDL_IsGameController
*/
extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerOpen(int joystick_index);
/**
- * Return the SDL_GameController associated with an instance id.
+ * Get the SDL_GameController associated with an instance id.
+ *
+ * \param joyid the instance id to get the SDL_GameController for
+ * \returns an SDL_GameController on success or NULL on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.4.
*/
extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromInstanceID(SDL_JoystickID joyid);
/**
- * Return the name for this currently opened controller
+ * Get the SDL_GameController associated with a player index.
+ *
+ * Please note that the player index is _not_ the device index, nor is it the
+ * instance id!
+ *
+ * \param player_index the player index, which is not the device index or the
+ * instance id!
+ * \returns the SDL_GameController associated with a player index.
+ *
+ * \since This function is available since SDL 2.0.12.
+ *
+ * \sa SDL_GameControllerGetPlayerIndex
+ * \sa SDL_GameControllerSetPlayerIndex
*/
+extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromPlayerIndex(int player_index);
+
+/**
+ * Get the implementation-dependent name for an opened game controller.
+ *
+ * This is the same name as returned by SDL_GameControllerNameForIndex(), but
+ * it takes a controller identifier instead of the (unstable) device index.
+ *
+ * \param gamecontroller a game controller identifier previously returned by
+ * SDL_GameControllerOpen()
+ * \returns the implementation dependent name for the game controller, or NULL
+ * if there is no name or the identifier passed is invalid.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerNameForIndex
+ * \sa SDL_GameControllerOpen
+ */
extern DECLSPEC const char *SDLCALL SDL_GameControllerName(SDL_GameController *gamecontroller);
/**
- * Get the player index of an opened game controller, or -1 if it's not available
+ * Get the implementation-dependent path for an opened game controller.
*
- * For XInput controllers this returns the XInput user index.
+ * This is the same path as returned by SDL_GameControllerNameForIndex(), but
+ * it takes a controller identifier instead of the (unstable) device index.
+ *
+ * \param gamecontroller a game controller identifier previously returned by
+ * SDL_GameControllerOpen()
+ * \returns the implementation dependent path for the game controller, or NULL
+ * if there is no path or the identifier passed is invalid.
+ *
+ * \since This function is available since SDL 2.24.0.
+ *
+ * \sa SDL_GameControllerPathForIndex
*/
+extern DECLSPEC const char *SDLCALL SDL_GameControllerPath(SDL_GameController *gamecontroller);
+
+/**
+ * Get the type of this currently opened controller
+ *
+ * This is the same name as returned by SDL_GameControllerTypeForIndex(), but
+ * it takes a controller identifier instead of the (unstable) device index.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \returns the controller type.
+ *
+ * \since This function is available since SDL 2.0.12.
+ */
+extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerGetType(SDL_GameController *gamecontroller);
+
+/**
+ * Get the player index of an opened game controller.
+ *
+ * For XInput controllers this returns the XInput user index.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \returns the player index for controller, or -1 if it's not available.
+ *
+ * \since This function is available since SDL 2.0.9.
+ */
extern DECLSPEC int SDLCALL SDL_GameControllerGetPlayerIndex(SDL_GameController *gamecontroller);
/**
- * Get the USB vendor ID of an opened controller, if available.
- * If the vendor ID isn't available this function returns 0.
+ * Set the player index of an opened game controller.
+ *
+ * \param gamecontroller the game controller object to adjust.
+ * \param player_index Player index to assign to this controller, or -1 to
+ * clear the player index and turn off player LEDs.
+ *
+ * \since This function is available since SDL 2.0.12.
*/
-extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetVendor(SDL_GameController * gamecontroller);
+extern DECLSPEC void SDLCALL SDL_GameControllerSetPlayerIndex(SDL_GameController *gamecontroller, int player_index);
/**
- * Get the USB product ID of an opened controller, if available.
- * If the product ID isn't available this function returns 0.
+ * Get the USB vendor ID of an opened controller, if available.
+ *
+ * If the vendor ID isn't available this function returns 0.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \return the USB vendor ID, or zero if unavailable.
+ *
+ * \since This function is available since SDL 2.0.6.
*/
-extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProduct(SDL_GameController * gamecontroller);
+extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetVendor(SDL_GameController *gamecontroller);
/**
- * Get the product version of an opened controller, if available.
- * If the product version isn't available this function returns 0.
+ * Get the USB product ID of an opened controller, if available.
+ *
+ * If the product ID isn't available this function returns 0.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \return the USB product ID, or zero if unavailable.
+ *
+ * \since This function is available since SDL 2.0.6.
*/
-extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProductVersion(SDL_GameController * gamecontroller);
+extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProduct(SDL_GameController *gamecontroller);
/**
- * Returns SDL_TRUE if the controller has been opened and currently connected,
- * or SDL_FALSE if it has not.
+ * Get the product version of an opened controller, if available.
+ *
+ * If the product version isn't available this function returns 0.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \return the USB product version, or zero if unavailable.
+ *
+ * \since This function is available since SDL 2.0.6.
*/
+extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProductVersion(SDL_GameController *gamecontroller);
+
+/**
+ * Get the firmware version of an opened controller, if available.
+ *
+ * If the firmware version isn't available this function returns 0.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \return the controller firmware version, or zero if unavailable.
+ *
+ * \since This function is available since SDL 2.24.0.
+ */
+extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetFirmwareVersion(SDL_GameController *gamecontroller);
+
+/**
+ * Get the serial number of an opened controller, if available.
+ *
+ * Returns the serial number of the controller, or NULL if it is not
+ * available.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \return the serial number, or NULL if unavailable.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC const char * SDLCALL SDL_GameControllerGetSerial(SDL_GameController *gamecontroller);
+
+/**
+ * Check if a controller has been opened and is currently connected.
+ *
+ * \param gamecontroller a game controller identifier previously returned by
+ * SDL_GameControllerOpen()
+ * \returns SDL_TRUE if the controller has been opened and is currently
+ * connected, or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerClose
+ * \sa SDL_GameControllerOpen
+ */
extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerGetAttached(SDL_GameController *gamecontroller);
/**
- * Get the underlying joystick object used by a controller
+ * Get the Joystick ID from a Game Controller.
+ *
+ * This function will give you a SDL_Joystick object, which allows you to use
+ * the SDL_Joystick functions with a SDL_GameController object. This would be
+ * useful for getting a joystick's position at any given time, even if it
+ * hasn't moved (moving it would produce an event, which would have the axis'
+ * value).
+ *
+ * The pointer returned is owned by the SDL_GameController. You should not
+ * call SDL_JoystickClose() on it, for example, since doing so will likely
+ * cause SDL to crash.
+ *
+ * \param gamecontroller the game controller object that you want to get a
+ * joystick from
+ * \returns a SDL_Joystick object; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
*/
extern DECLSPEC SDL_Joystick *SDLCALL SDL_GameControllerGetJoystick(SDL_GameController *gamecontroller);
/**
- * Enable/disable controller event polling.
+ * Query or change current state of Game Controller events.
*
- * If controller events are disabled, you must call SDL_GameControllerUpdate()
- * yourself and check the state of the controller when you want controller
- * information.
+ * If controller events are disabled, you must call SDL_GameControllerUpdate()
+ * yourself and check the state of the controller when you want controller
+ * information.
*
- * The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE.
+ * Any number can be passed to SDL_GameControllerEventState(), but only -1, 0,
+ * and 1 will have any effect. Other numbers will just be returned.
+ *
+ * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`
+ * \returns the same value passed to the function, with exception to -1
+ * (SDL_QUERY), which will return the current state.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickEventState
*/
extern DECLSPEC int SDLCALL SDL_GameControllerEventState(int state);
/**
- * Update the current state of the open game controllers.
+ * Manually pump game controller updates if not using the loop.
*
- * This is called automatically by the event loop if any game controller
- * events are enabled.
+ * This function is called automatically by the event loop if events are
+ * enabled. Under such circumstances, it will not be necessary to call this
+ * function.
+ *
+ * \since This function is available since SDL 2.0.0.
*/
extern DECLSPEC void SDLCALL SDL_GameControllerUpdate(void);
@@ -282,17 +613,55 @@
} SDL_GameControllerAxis;
/**
- * turn this string into a axis mapping
+ * Convert a string into SDL_GameControllerAxis enum.
+ *
+ * This function is called internally to translate SDL_GameController mapping
+ * strings for the underlying joystick device into the consistent
+ * SDL_GameController mapping. You do not normally need to call this function
+ * unless you are parsing SDL_GameController mappings in your own code.
+ *
+ * Note specially that "righttrigger" and "lefttrigger" map to
+ * `SDL_CONTROLLER_AXIS_TRIGGERRIGHT` and `SDL_CONTROLLER_AXIS_TRIGGERLEFT`,
+ * respectively.
+ *
+ * \param str string representing a SDL_GameController axis
+ * \returns the SDL_GameControllerAxis enum corresponding to the input string,
+ * or `SDL_CONTROLLER_AXIS_INVALID` if no match was found.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetStringForAxis
*/
-extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromString(const char *pchString);
+extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromString(const char *str);
/**
- * turn this axis enum into a string mapping
+ * Convert from an SDL_GameControllerAxis enum to a string.
+ *
+ * The caller should not SDL_free() the returned string.
+ *
+ * \param axis an enum value for a given SDL_GameControllerAxis
+ * \returns a string for the given axis, or NULL if an invalid axis is
+ * specified. The string returned is of the format used by
+ * SDL_GameController mapping strings.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetAxisFromString
*/
extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForAxis(SDL_GameControllerAxis axis);
/**
- * Get the SDL joystick layer binding for this controller button mapping
+ * Get the SDL joystick layer binding for a controller axis mapping.
+ *
+ * \param gamecontroller a game controller
+ * \param axis an axis enum value (one of the SDL_GameControllerAxis values)
+ * \returns a SDL_GameControllerButtonBind describing the bind. On failure
+ * (like the given Controller axis doesn't exist on the device), its
+ * `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetBindForButton
*/
extern DECLSPEC SDL_GameControllerButtonBind SDLCALL
SDL_GameControllerGetBindForAxis(SDL_GameController *gamecontroller,
@@ -299,16 +668,39 @@
SDL_GameControllerAxis axis);
/**
- * Get the current state of an axis control on a game controller.
+ * Query whether a game controller has a given axis.
*
- * The state is a value ranging from -32768 to 32767 (except for the triggers,
- * which range from 0 to 32767).
+ * This merely reports whether the controller's mapping defined this axis, as
+ * that is all the information SDL has about the physical device.
*
- * The axis indices start at index 0.
+ * \param gamecontroller a game controller
+ * \param axis an axis enum value (an SDL_GameControllerAxis value)
+ * \returns SDL_TRUE if the controller has this axis, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.14.
*/
+extern DECLSPEC SDL_bool SDLCALL
+SDL_GameControllerHasAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis);
+
+/**
+ * Get the current state of an axis control on a game controller.
+ *
+ * The axis indices start at index 0.
+ *
+ * The state is a value ranging from -32768 to 32767. Triggers, however, range
+ * from 0 to 32767 (they never return a negative value).
+ *
+ * \param gamecontroller a game controller
+ * \param axis an axis index (one of the SDL_GameControllerAxis values)
+ * \returns axis state (including 0) on success or 0 (also) on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetButton
+ */
extern DECLSPEC Sint16 SDLCALL
-SDL_GameControllerGetAxis(SDL_GameController *gamecontroller,
- SDL_GameControllerAxis axis);
+SDL_GameControllerGetAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis);
/**
* The list of buttons available from a controller
@@ -331,59 +723,351 @@
SDL_CONTROLLER_BUTTON_DPAD_DOWN,
SDL_CONTROLLER_BUTTON_DPAD_LEFT,
SDL_CONTROLLER_BUTTON_DPAD_RIGHT,
+ SDL_CONTROLLER_BUTTON_MISC1, /* Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button */
+ SDL_CONTROLLER_BUTTON_PADDLE1, /* Xbox Elite paddle P1 */
+ SDL_CONTROLLER_BUTTON_PADDLE2, /* Xbox Elite paddle P3 */
+ SDL_CONTROLLER_BUTTON_PADDLE3, /* Xbox Elite paddle P2 */
+ SDL_CONTROLLER_BUTTON_PADDLE4, /* Xbox Elite paddle P4 */
+ SDL_CONTROLLER_BUTTON_TOUCHPAD, /* PS4/PS5 touchpad button */
SDL_CONTROLLER_BUTTON_MAX
} SDL_GameControllerButton;
/**
- * turn this string into a button mapping
+ * Convert a string into an SDL_GameControllerButton enum.
+ *
+ * This function is called internally to translate SDL_GameController mapping
+ * strings for the underlying joystick device into the consistent
+ * SDL_GameController mapping. You do not normally need to call this function
+ * unless you are parsing SDL_GameController mappings in your own code.
+ *
+ * \param str string representing a SDL_GameController axis
+ * \returns the SDL_GameControllerButton enum corresponding to the input
+ * string, or `SDL_CONTROLLER_AXIS_INVALID` if no match was found.
+ *
+ * \since This function is available since SDL 2.0.0.
*/
-extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFromString(const char *pchString);
+extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFromString(const char *str);
/**
- * turn this button enum into a string mapping
+ * Convert from an SDL_GameControllerButton enum to a string.
+ *
+ * The caller should not SDL_free() the returned string.
+ *
+ * \param button an enum value for a given SDL_GameControllerButton
+ * \returns a string for the given button, or NULL if an invalid button is
+ * specified. The string returned is of the format used by
+ * SDL_GameController mapping strings.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetButtonFromString
*/
extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForButton(SDL_GameControllerButton button);
/**
- * Get the SDL joystick layer binding for this controller button mapping
+ * Get the SDL joystick layer binding for a controller button mapping.
+ *
+ * \param gamecontroller a game controller
+ * \param button an button enum value (an SDL_GameControllerButton value)
+ * \returns a SDL_GameControllerButtonBind describing the bind. On failure
+ * (like the given Controller button doesn't exist on the device),
+ * its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetBindForAxis
*/
extern DECLSPEC SDL_GameControllerButtonBind SDLCALL
SDL_GameControllerGetBindForButton(SDL_GameController *gamecontroller,
SDL_GameControllerButton button);
+/**
+ * Query whether a game controller has a given button.
+ *
+ * This merely reports whether the controller's mapping defined this button,
+ * as that is all the information SDL has about the physical device.
+ *
+ * \param gamecontroller a game controller
+ * \param button a button enum value (an SDL_GameControllerButton value)
+ * \returns SDL_TRUE if the controller has this button, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasButton(SDL_GameController *gamecontroller,
+ SDL_GameControllerButton button);
/**
- * Get the current state of a button on a game controller.
+ * Get the current state of a button on a game controller.
*
- * The button indices start at index 0.
+ * \param gamecontroller a game controller
+ * \param button a button index (one of the SDL_GameControllerButton values)
+ * \returns 1 for pressed state or 0 for not pressed state or error; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetAxis
*/
extern DECLSPEC Uint8 SDLCALL SDL_GameControllerGetButton(SDL_GameController *gamecontroller,
SDL_GameControllerButton button);
/**
- * Trigger a rumble effect
- * Each call to this function cancels any previous rumble effect, and calling it with 0 intensity stops any rumbling.
+ * Get the number of touchpads on a game controller.
*
- * \param gamecontroller The controller to vibrate
- * \param low_frequency_rumble The intensity of the low frequency (left) rumble motor, from 0 to 0xFFFF
- * \param high_frequency_rumble The intensity of the high frequency (right) rumble motor, from 0 to 0xFFFF
- * \param duration_ms The duration of the rumble effect, in milliseconds
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpads(SDL_GameController *gamecontroller);
+
+/**
+ * Get the number of supported simultaneous fingers on a touchpad on a game
+ * controller.
*
- * \return 0, or -1 if rumble isn't supported on this joystick
+ * \since This function is available since SDL 2.0.14.
*/
+extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpadFingers(SDL_GameController *gamecontroller, int touchpad);
+
+/**
+ * Get the current state of a finger on a touchpad on a game controller.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC int SDLCALL SDL_GameControllerGetTouchpadFinger(SDL_GameController *gamecontroller, int touchpad, int finger, Uint8 *state, float *x, float *y, float *pressure);
+
+/**
+ * Return whether a game controller has a particular sensor.
+ *
+ * \param gamecontroller The controller to query
+ * \param type The type of sensor to query
+ * \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasSensor(SDL_GameController *gamecontroller, SDL_SensorType type);
+
+/**
+ * Set whether data reporting for a game controller sensor is enabled.
+ *
+ * \param gamecontroller The controller to update
+ * \param type The type of sensor to enable/disable
+ * \param enabled Whether data reporting should be enabled
+ * \returns 0 or -1 if an error occurred.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC int SDLCALL SDL_GameControllerSetSensorEnabled(SDL_GameController *gamecontroller, SDL_SensorType type, SDL_bool enabled);
+
+/**
+ * Query whether sensor data reporting is enabled for a game controller.
+ *
+ * \param gamecontroller The controller to query
+ * \param type The type of sensor to query
+ * \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerIsSensorEnabled(SDL_GameController *gamecontroller, SDL_SensorType type);
+
+/**
+ * Get the data rate (number of events per second) of a game controller
+ * sensor.
+ *
+ * \param gamecontroller The controller to query
+ * \param type The type of sensor to query
+ * \return the data rate, or 0.0f if the data rate is not available.
+ *
+ * \since This function is available since SDL 2.0.16.
+ */
+extern DECLSPEC float SDLCALL SDL_GameControllerGetSensorDataRate(SDL_GameController *gamecontroller, SDL_SensorType type);
+
+/**
+ * Get the current state of a game controller sensor.
+ *
+ * The number of values and interpretation of the data is sensor dependent.
+ * See SDL_sensor.h for the details for each type of sensor.
+ *
+ * \param gamecontroller The controller to query
+ * \param type The type of sensor to query
+ * \param data A pointer filled with the current sensor state
+ * \param num_values The number of values to write to data
+ * \return 0 or -1 if an error occurred.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorData(SDL_GameController *gamecontroller, SDL_SensorType type, float *data, int num_values);
+
+/**
+ * Get the current state of a game controller sensor with the timestamp of the
+ * last update.
+ *
+ * The number of values and interpretation of the data is sensor dependent.
+ * See SDL_sensor.h for the details for each type of sensor.
+ *
+ * \param gamecontroller The controller to query
+ * \param type The type of sensor to query
+ * \param timestamp A pointer filled with the timestamp in microseconds of the
+ * current sensor reading if available, or 0 if not
+ * \param data A pointer filled with the current sensor state
+ * \param num_values The number of values to write to data
+ * \return 0 or -1 if an error occurred.
+ *
+ * \since This function is available since SDL 2.26.0.
+ */
+extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorDataWithTimestamp(SDL_GameController *gamecontroller, SDL_SensorType type, Uint64 *timestamp, float *data, int num_values);
+
+/**
+ * Start a rumble effect on a game controller.
+ *
+ * Each call to this function cancels any previous rumble effect, and calling
+ * it with 0 intensity stops any rumbling.
+ *
+ * \param gamecontroller The controller to vibrate
+ * \param low_frequency_rumble The intensity of the low frequency (left)
+ * rumble motor, from 0 to 0xFFFF
+ * \param high_frequency_rumble The intensity of the high frequency (right)
+ * rumble motor, from 0 to 0xFFFF
+ * \param duration_ms The duration of the rumble effect, in milliseconds
+ * \returns 0, or -1 if rumble isn't supported on this controller
+ *
+ * \since This function is available since SDL 2.0.9.
+ *
+ * \sa SDL_GameControllerHasRumble
+ */
extern DECLSPEC int SDLCALL SDL_GameControllerRumble(SDL_GameController *gamecontroller, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);
/**
- * Close a controller previously opened with SDL_GameControllerOpen().
+ * Start a rumble effect in the game controller's triggers.
+ *
+ * Each call to this function cancels any previous trigger rumble effect, and
+ * calling it with 0 intensity stops any rumbling.
+ *
+ * Note that this is rumbling of the _triggers_ and not the game controller as
+ * a whole. This is currently only supported on Xbox One controllers. If you
+ * want the (more common) whole-controller rumble, use
+ * SDL_GameControllerRumble() instead.
+ *
+ * \param gamecontroller The controller to vibrate
+ * \param left_rumble The intensity of the left trigger rumble motor, from 0
+ * to 0xFFFF
+ * \param right_rumble The intensity of the right trigger rumble motor, from 0
+ * to 0xFFFF
+ * \param duration_ms The duration of the rumble effect, in milliseconds
+ * \returns 0, or -1 if trigger rumble isn't supported on this controller
+ *
+ * \since This function is available since SDL 2.0.14.
+ *
+ * \sa SDL_GameControllerHasRumbleTriggers
*/
+extern DECLSPEC int SDLCALL SDL_GameControllerRumbleTriggers(SDL_GameController *gamecontroller, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms);
+
+/**
+ * Query whether a game controller has an LED.
+ *
+ * \param gamecontroller The controller to query
+ * \returns SDL_TRUE, or SDL_FALSE if this controller does not have a
+ * modifiable LED
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasLED(SDL_GameController *gamecontroller);
+
+/**
+ * Query whether a game controller has rumble support.
+ *
+ * \param gamecontroller The controller to query
+ * \returns SDL_TRUE, or SDL_FALSE if this controller does not have rumble
+ * support
+ *
+ * \since This function is available since SDL 2.0.18.
+ *
+ * \sa SDL_GameControllerRumble
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasRumble(SDL_GameController *gamecontroller);
+
+/**
+ * Query whether a game controller has rumble support on triggers.
+ *
+ * \param gamecontroller The controller to query
+ * \returns SDL_TRUE, or SDL_FALSE if this controller does not have trigger
+ * rumble support
+ *
+ * \since This function is available since SDL 2.0.18.
+ *
+ * \sa SDL_GameControllerRumbleTriggers
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasRumbleTriggers(SDL_GameController *gamecontroller);
+
+/**
+ * Update a game controller's LED color.
+ *
+ * \param gamecontroller The controller to update
+ * \param red The intensity of the red LED
+ * \param green The intensity of the green LED
+ * \param blue The intensity of the blue LED
+ * \returns 0, or -1 if this controller does not have a modifiable LED
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC int SDLCALL SDL_GameControllerSetLED(SDL_GameController *gamecontroller, Uint8 red, Uint8 green, Uint8 blue);
+
+/**
+ * Send a controller specific effect packet
+ *
+ * \param gamecontroller The controller to affect
+ * \param data The data to send to the controller
+ * \param size The size of the data to send to the controller
+ * \returns 0, or -1 if this controller or driver doesn't support effect
+ * packets
+ *
+ * \since This function is available since SDL 2.0.16.
+ */
+extern DECLSPEC int SDLCALL SDL_GameControllerSendEffect(SDL_GameController *gamecontroller, const void *data, int size);
+
+/**
+ * Close a game controller previously opened with SDL_GameControllerOpen().
+ *
+ * \param gamecontroller a game controller identifier previously returned by
+ * SDL_GameControllerOpen()
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerOpen
+ */
extern DECLSPEC void SDLCALL SDL_GameControllerClose(SDL_GameController *gamecontroller);
+/**
+ * Return the sfSymbolsName for a given button on a game controller on Apple
+ * platforms.
+ *
+ * \param gamecontroller the controller to query
+ * \param button a button on the game controller
+ * \returns the sfSymbolsName or NULL if the name can't be found
+ *
+ * \since This function is available since SDL 2.0.18.
+ *
+ * \sa SDL_GameControllerGetAppleSFSymbolsNameForAxis
+ */
+extern DECLSPEC const char* SDLCALL SDL_GameControllerGetAppleSFSymbolsNameForButton(SDL_GameController *gamecontroller, SDL_GameControllerButton button);
+/**
+ * Return the sfSymbolsName for a given axis on a game controller on Apple
+ * platforms.
+ *
+ * \param gamecontroller the controller to query
+ * \param axis an axis on the game controller
+ * \returns the sfSymbolsName or NULL if the name can't be found
+ *
+ * \since This function is available since SDL 2.0.18.
+ *
+ * \sa SDL_GameControllerGetAppleSFSymbolsNameForButton
+ */
+extern DECLSPEC const char* SDLCALL SDL_GameControllerGetAppleSFSymbolsNameForAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis);
+
+
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}
#endif
-#include "close_code.h"
+#include <SDL2/close_code.h>
#endif /* SDL_gamecontroller_h_ */
--- a/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_gesture.h
+++ b/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_gesture.h
@@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
- Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@@ -28,14 +28,14 @@
#ifndef SDL_gesture_h_
#define SDL_gesture_h_
-#include "SDL_stdinc.h"
-#include "SDL_error.h"
-#include "SDL_video.h"
+#include <SDL2/SDL_stdinc.h>
+#include <SDL2/SDL_error.h>
+#include <SDL2/SDL_video.h>
-#include "SDL_touch.h"
+#include <SDL2/SDL_touch.h>
-#include "begin_code.h"
+#include <SDL2/begin_code.h>
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {@@ -46,41 +46,71 @@
/* Function prototypes */
/**
- * \brief Begin Recording a gesture on the specified touch, or all touches (-1)
+ * Begin recording a gesture on a specified touch device or all touch devices.
*
+ * If the parameter `touchId` is -1 (i.e., all devices), this function will
+ * always return 1, regardless of whether there actually are any devices.
*
+ * \param touchId the touch device id, or -1 for all touch devices
+ * \returns 1 on success or 0 if the specified device could not be found.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetTouchDevice
*/
extern DECLSPEC int SDLCALL SDL_RecordGesture(SDL_TouchID touchId);
/**
- * \brief Save all currently loaded Dollar Gesture templates
+ * Save all currently loaded Dollar Gesture templates.
*
+ * \param dst a SDL_RWops to save to
+ * \returns the number of saved templates on success or 0 on failure; call
+ * SDL_GetError() for more information.
*
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LoadDollarTemplates
+ * \sa SDL_SaveDollarTemplate
*/
extern DECLSPEC int SDLCALL SDL_SaveAllDollarTemplates(SDL_RWops *dst);
/**
- * \brief Save a currently loaded Dollar Gesture template
+ * Save a currently loaded Dollar Gesture template.
*
+ * \param gestureId a gesture id
+ * \param dst a SDL_RWops to save to
+ * \returns 1 on success or 0 on failure; call SDL_GetError() for more
+ * information.
*
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LoadDollarTemplates
+ * \sa SDL_SaveAllDollarTemplates
*/
extern DECLSPEC int SDLCALL SDL_SaveDollarTemplate(SDL_GestureID gestureId,SDL_RWops *dst);
/**
- * \brief Load Dollar Gesture templates from a file
+ * Load Dollar Gesture templates from a file.
*
+ * \param touchId a touch id
+ * \param src a SDL_RWops to load from
+ * \returns the number of loaded templates on success or a negative error code
+ * (or 0) on failure; call SDL_GetError() for more information.
*
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_SaveAllDollarTemplates
+ * \sa SDL_SaveDollarTemplate
*/
extern DECLSPEC int SDLCALL SDL_LoadDollarTemplates(SDL_TouchID touchId, SDL_RWops *src);
-
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}
#endif
-#include "close_code.h"
+#include <SDL2/close_code.h>
#endif /* SDL_gesture_h_ */
--- /dev/null
+++ b/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_guid.h
@@ -1,0 +1,100 @@
+/*
+ Simple DirectMedia Layer
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
+
+ This software is provided 'as-is', without any express or implied
+ warranty. In no event will the authors be held liable for any damages
+ arising from the use of this software.
+
+ Permission is granted to anyone to use this software for any purpose,
+ including commercial applications, and to alter it and redistribute it
+ freely, subject to the following restrictions:
+
+ 1. The origin of this software must not be misrepresented; you must not
+ claim that you wrote the original software. If you use this software
+ in a product, an acknowledgment in the product documentation would be
+ appreciated but is not required.
+ 2. Altered source versions must be plainly marked as such, and must not be
+ misrepresented as being the original software.
+ 3. This notice may not be removed or altered from any source distribution.
+*/
+
+/**
+ * \file SDL_guid.h
+ *
+ * Include file for handling ::SDL_GUID values.
+ */
+
+#ifndef SDL_guid_h_
+#define SDL_guid_h_
+
+#include <SDL2/SDL_stdinc.h>
+#include <SDL2/SDL_error.h>
+
+#include <SDL2/begin_code.h>
+/* Set up for C function definitions, even when using C++ */
+#ifdef __cplusplus
+extern "C" {+#endif
+
+/**
+ * An SDL_GUID is a 128-bit identifier for an input device that
+ * identifies that device across runs of SDL programs on the same
+ * platform. If the device is detached and then re-attached to a
+ * different port, or if the base system is rebooted, the device
+ * should still report the same GUID.
+ *
+ * GUIDs are as precise as possible but are not guaranteed to
+ * distinguish physically distinct but equivalent devices. For
+ * example, two game controllers from the same vendor with the same
+ * product ID and revision may have the same GUID.
+ *
+ * GUIDs may be platform-dependent (i.e., the same device may report
+ * different GUIDs on different operating systems).
+ */
+typedef struct {+ Uint8 data[16];
+} SDL_GUID;
+
+/* Function prototypes */
+
+/**
+ * Get an ASCII string representation for a given ::SDL_GUID.
+ *
+ * You should supply at least 33 bytes for pszGUID.
+ *
+ * \param guid the ::SDL_GUID you wish to convert to string
+ * \param pszGUID buffer in which to write the ASCII string
+ * \param cbGUID the size of pszGUID
+ *
+ * \since This function is available since SDL 2.24.0.
+ *
+ * \sa SDL_GUIDFromString
+ */
+extern DECLSPEC void SDLCALL SDL_GUIDToString(SDL_GUID guid, char *pszGUID, int cbGUID);
+
+/**
+ * Convert a GUID string into a ::SDL_GUID structure.
+ *
+ * Performs no error checking. If this function is given a string containing
+ * an invalid GUID, the function will silently succeed, but the GUID generated
+ * will not be useful.
+ *
+ * \param pchGUID string containing an ASCII representation of a GUID
+ * \returns a ::SDL_GUID structure.
+ *
+ * \since This function is available since SDL 2.24.0.
+ *
+ * \sa SDL_GUIDToString
+ */
+extern DECLSPEC SDL_GUID SDLCALL SDL_GUIDFromString(const char *pchGUID);
+
+/* Ends C function definitions when using C++ */
+#ifdef __cplusplus
+}
+#endif
+#include <SDL2/close_code.h>
+
+#endif /* SDL_guid_h_ */
+
+/* vi: set ts=4 sw=4 expandtab: */
--- a/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_haptic.h
+++ b/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_haptic.h
@@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
- Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@@ -76,7 +76,7 @@
* }
*
* // Create the effect
- * memset( &effect, 0, sizeof(SDL_HapticEffect) ); // 0 is safe default
+ * SDL_memset( &effect, 0, sizeof(SDL_HapticEffect) ); // 0 is safe default
* effect.type = SDL_HAPTIC_SINE;
* effect.periodic.direction.type = SDL_HAPTIC_POLAR; // Polar coordinates
* effect.periodic.direction.dir[0] = 18000; // Force comes from south
@@ -107,11 +107,11 @@
#ifndef SDL_haptic_h_
#define SDL_haptic_h_
-#include "SDL_stdinc.h"
-#include "SDL_error.h"
-#include "SDL_joystick.h"
+#include <SDL2/SDL_stdinc.h>
+#include <SDL2/SDL_error.h>
+#include <SDL2/SDL_joystick.h>
-#include "begin_code.h"
+#include <SDL2/begin_code.h>
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {@@ -336,6 +336,14 @@
*/
#define SDL_HAPTIC_SPHERICAL 2
+/**
+ * \brief Use this value to play an effect on the steering wheel axis. This
+ * provides better compatibility across platforms and devices as SDL will guess
+ * the correct axis.
+ * \sa SDL_HapticDirection
+ */
+#define SDL_HAPTIC_STEERING_AXIS 3
+
/* @} *//* Direction encodings */
/* @} *//* Haptic features */
@@ -444,6 +452,7 @@
* \sa SDL_HAPTIC_POLAR
* \sa SDL_HAPTIC_CARTESIAN
* \sa SDL_HAPTIC_SPHERICAL
+ * \sa SDL_HAPTIC_STEERING_AXIS
* \sa SDL_HapticEffect
* \sa SDL_HapticNumAxes
*/
@@ -811,196 +820,240 @@
/* Function prototypes */
+
/**
- * \brief Count the number of haptic devices attached to the system.
+ * Count the number of haptic devices attached to the system.
*
- * \return Number of haptic devices detected on the system.
+ * \returns the number of haptic devices detected on the system or a negative
+ * error code on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticName
*/
extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
/**
- * \brief Get the implementation dependent name of a haptic device.
+ * Get the implementation dependent name of a haptic device.
*
- * This can be called before any joysticks are opened.
- * If no name can be found, this function returns NULL.
+ * This can be called before any joysticks are opened. If no name can be
+ * found, this function returns NULL.
*
- * \param device_index Index of the device to get its name.
- * \return Name of the device or NULL on error.
+ * \param device_index index of the device to query.
+ * \returns the name of the device or NULL on failure; call SDL_GetError() for
+ * more information.
*
- * \sa SDL_NumHaptics
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_NumHaptics
*/
extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
/**
- * \brief Opens a haptic device for use.
+ * Open a haptic device for use.
*
- * The index passed as an argument refers to the N'th haptic device on this
- * system.
+ * The index passed as an argument refers to the N'th haptic device on this
+ * system.
*
- * When opening a haptic device, its gain will be set to maximum and
- * autocenter will be disabled. To modify these values use
- * SDL_HapticSetGain() and SDL_HapticSetAutocenter().
+ * When opening a haptic device, its gain will be set to maximum and
+ * autocenter will be disabled. To modify these values use SDL_HapticSetGain()
+ * and SDL_HapticSetAutocenter().
*
- * \param device_index Index of the device to open.
- * \return Device identifier or NULL on error.
+ * \param device_index index of the device to open
+ * \returns the device identifier or NULL on failure; call SDL_GetError() for
+ * more information.
*
- * \sa SDL_HapticIndex
- * \sa SDL_HapticOpenFromMouse
- * \sa SDL_HapticOpenFromJoystick
- * \sa SDL_HapticClose
- * \sa SDL_HapticSetGain
- * \sa SDL_HapticSetAutocenter
- * \sa SDL_HapticPause
- * \sa SDL_HapticStopAll
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticClose
+ * \sa SDL_HapticIndex
+ * \sa SDL_HapticOpenFromJoystick
+ * \sa SDL_HapticOpenFromMouse
+ * \sa SDL_HapticPause
+ * \sa SDL_HapticSetAutocenter
+ * \sa SDL_HapticSetGain
+ * \sa SDL_HapticStopAll
*/
extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index);
/**
- * \brief Checks if the haptic device at index has been opened.
+ * Check if the haptic device at the designated index has been opened.
*
- * \param device_index Index to check to see if it has been opened.
- * \return 1 if it has been opened or 0 if it hasn't.
+ * \param device_index the index of the device to query
+ * \returns 1 if it has been opened, 0 if it hasn't or on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticOpen
- * \sa SDL_HapticIndex
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticIndex
+ * \sa SDL_HapticOpen
*/
extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);
/**
- * \brief Gets the index of a haptic device.
+ * Get the index of a haptic device.
*
- * \param haptic Haptic device to get the index of.
- * \return The index of the haptic device or -1 on error.
+ * \param haptic the SDL_Haptic device to query
+ * \returns the index of the specified haptic device or a negative error code
+ * on failure; call SDL_GetError() for more information.
*
- * \sa SDL_HapticOpen
- * \sa SDL_HapticOpened
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticOpen
+ * \sa SDL_HapticOpened
*/
extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);
/**
- * \brief Gets whether or not the current mouse has haptic capabilities.
+ * Query whether or not the current mouse has haptic capabilities.
*
- * \return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
+ * \returns SDL_TRUE if the mouse is haptic or SDL_FALSE if it isn't.
*
- * \sa SDL_HapticOpenFromMouse
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticOpenFromMouse
*/
extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
/**
- * \brief Tries to open a haptic device from the current mouse.
+ * Try to open a haptic device from the current mouse.
*
- * \return The haptic device identifier or NULL on error.
+ * \returns the haptic device identifier or NULL on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_MouseIsHaptic
- * \sa SDL_HapticOpen
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticOpen
+ * \sa SDL_MouseIsHaptic
*/
extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);
/**
- * \brief Checks to see if a joystick has haptic features.
+ * Query if a joystick has haptic features.
*
- * \param joystick Joystick to test for haptic capabilities.
- * \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
- * or -1 if an error occurred.
+ * \param joystick the SDL_Joystick to test for haptic capabilities
+ * \returns SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't, or a
+ * negative error code on failure; call SDL_GetError() for more
+ * information.
*
- * \sa SDL_HapticOpenFromJoystick
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticOpenFromJoystick
*/
extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
/**
- * \brief Opens a haptic device for use from a joystick device.
+ * Open a haptic device for use from a joystick device.
*
- * You must still close the haptic device separately. It will not be closed
- * with the joystick.
+ * You must still close the haptic device separately. It will not be closed
+ * with the joystick.
*
- * When opening from a joystick you should first close the haptic device before
- * closing the joystick device. If not, on some implementations the haptic
- * device will also get unallocated and you'll be unable to use force feedback
- * on that device.
+ * When opened from a joystick you should first close the haptic device before
+ * closing the joystick device. If not, on some implementations the haptic
+ * device will also get unallocated and you'll be unable to use force feedback
+ * on that device.
*
- * \param joystick Joystick to create a haptic device from.
- * \return A valid haptic device identifier on success or NULL on error.
+ * \param joystick the SDL_Joystick to create a haptic device from
+ * \returns a valid haptic device identifier on success or NULL on failure;
+ * call SDL_GetError() for more information.
*
- * \sa SDL_HapticOpen
- * \sa SDL_HapticClose
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticClose
+ * \sa SDL_HapticOpen
+ * \sa SDL_JoystickIsHaptic
*/
extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
joystick);
/**
- * \brief Closes a haptic device previously opened with SDL_HapticOpen().
+ * Close a haptic device previously opened with SDL_HapticOpen().
*
- * \param haptic Haptic device to close.
+ * \param haptic the SDL_Haptic device to close
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticOpen
*/
extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
/**
- * \brief Returns the number of effects a haptic device can store.
+ * Get the number of effects a haptic device can store.
*
- * On some platforms this isn't fully supported, and therefore is an
- * approximation. Always check to see if your created effect was actually
- * created and do not rely solely on SDL_HapticNumEffects().
+ * On some platforms this isn't fully supported, and therefore is an
+ * approximation. Always check to see if your created effect was actually
+ * created and do not rely solely on SDL_HapticNumEffects().
*
- * \param haptic The haptic device to query effect max.
- * \return The number of effects the haptic device can store or
- * -1 on error.
+ * \param haptic the SDL_Haptic device to query
+ * \returns the number of effects the haptic device can store or a negative
+ * error code on failure; call SDL_GetError() for more information.
*
- * \sa SDL_HapticNumEffectsPlaying
- * \sa SDL_HapticQuery
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticNumEffectsPlaying
+ * \sa SDL_HapticQuery
*/
extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
/**
- * \brief Returns the number of effects a haptic device can play at the same
- * time.
+ * Get the number of effects a haptic device can play at the same time.
*
- * This is not supported on all platforms, but will always return a value.
- * Added here for the sake of completeness.
+ * This is not supported on all platforms, but will always return a value.
*
- * \param haptic The haptic device to query maximum playing effects.
- * \return The number of effects the haptic device can play at the same time
- * or -1 on error.
+ * \param haptic the SDL_Haptic device to query maximum playing effects
+ * \returns the number of effects the haptic device can play at the same time
+ * or a negative error code on failure; call SDL_GetError() for more
+ * information.
*
- * \sa SDL_HapticNumEffects
- * \sa SDL_HapticQuery
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticNumEffects
+ * \sa SDL_HapticQuery
*/
extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic);
/**
- * \brief Gets the haptic device's supported features in bitwise manner.
+ * Get the haptic device's supported features in bitwise manner.
*
- * Example:
- * \code
- * if (SDL_HapticQuery(haptic) & SDL_HAPTIC_CONSTANT) {- * printf("We have constant haptic effect!\n");- * }
- * \endcode
+ * \param haptic the SDL_Haptic device to query
+ * \returns a list of supported haptic features in bitwise manner (OR'd), or 0
+ * on failure; call SDL_GetError() for more information.
*
- * \param haptic The haptic device to query.
- * \return Haptic features in bitwise manner (OR'd).
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_HapticNumEffects
- * \sa SDL_HapticEffectSupported
+ * \sa SDL_HapticEffectSupported
+ * \sa SDL_HapticNumEffects
*/
extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);
/**
- * \brief Gets the number of haptic axes the device has.
+ * Get the number of haptic axes the device has.
*
- * \sa SDL_HapticDirection
+ * The number of haptic axes might be useful if working with the
+ * SDL_HapticDirection effect.
+ *
+ * \param haptic the SDL_Haptic device to query
+ * \returns the number of axes on success or a negative error code on failure;
+ * call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
*/
extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);
/**
- * \brief Checks to see if effect is supported by haptic.
+ * Check to see if an effect is supported by a haptic device.
*
- * \param haptic Haptic device to check on.
- * \param effect Effect to check to see if it is supported.
- * \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
+ * \param haptic the SDL_Haptic device to query
+ * \param effect the desired effect to query
+ * \returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't, or a
+ * negative error code on failure; call SDL_GetError() for more
+ * information.
*
- * \sa SDL_HapticQuery
- * \sa SDL_HapticNewEffect
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticNewEffect
+ * \sa SDL_HapticQuery
*/
extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic,
SDL_HapticEffect *
@@ -1007,35 +1060,43 @@
effect);
/**
- * \brief Creates a new haptic effect on the device.
+ * Create a new haptic effect on a specified device.
*
- * \param haptic Haptic device to create the effect on.
- * \param effect Properties of the effect to create.
- * \return The identifier of the effect on success or -1 on error.
+ * \param haptic an SDL_Haptic device to create the effect on
+ * \param effect an SDL_HapticEffect structure containing the properties of
+ * the effect to create
+ * \returns the ID of the effect on success or a negative error code on
+ * failure; call SDL_GetError() for more information.
*
- * \sa SDL_HapticUpdateEffect
- * \sa SDL_HapticRunEffect
- * \sa SDL_HapticDestroyEffect
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticRunEffect
+ * \sa SDL_HapticUpdateEffect
*/
extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic,
SDL_HapticEffect * effect);
/**
- * \brief Updates the properties of an effect.
+ * Update the properties of an effect.
*
- * Can be used dynamically, although behavior when dynamically changing
- * direction may be strange. Specifically the effect may reupload itself
- * and start playing from the start. You cannot change the type either when
- * running SDL_HapticUpdateEffect().
+ * Can be used dynamically, although behavior when dynamically changing
+ * direction may be strange. Specifically the effect may re-upload itself and
+ * start playing from the start. You also cannot change the type either when
+ * running SDL_HapticUpdateEffect().
*
- * \param haptic Haptic device that has the effect.
- * \param effect Identifier of the effect to update.
- * \param data New effect properties to use.
- * \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device that has the effect
+ * \param effect the identifier of the effect to update
+ * \param data an SDL_HapticEffect structure containing the new effect
+ * properties to use
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticNewEffect
- * \sa SDL_HapticRunEffect
- * \sa SDL_HapticDestroyEffect
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticNewEffect
+ * \sa SDL_HapticRunEffect
*/
extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic,
int effect,
@@ -1042,22 +1103,26 @@
SDL_HapticEffect * data);
/**
- * \brief Runs the haptic effect on its associated haptic device.
+ * Run the haptic effect on its associated haptic device.
*
- * If iterations are ::SDL_HAPTIC_INFINITY, it'll run the effect over and over
- * repeating the envelope (attack and fade) every time. If you only want the
- * effect to last forever, set ::SDL_HAPTIC_INFINITY in the effect's length
- * parameter.
+ * To repeat the effect over and over indefinitely, set `iterations` to
+ * `SDL_HAPTIC_INFINITY`. (Repeats the envelope - attack and fade.) To make
+ * one instance of the effect last indefinitely (so the effect does not fade),
+ * set the effect's `length` in its structure/union to `SDL_HAPTIC_INFINITY`
+ * instead.
*
- * \param haptic Haptic device to run the effect on.
- * \param effect Identifier of the haptic effect to run.
- * \param iterations Number of iterations to run the effect. Use
- * ::SDL_HAPTIC_INFINITY for infinity.
- * \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device to run the effect on
+ * \param effect the ID of the haptic effect to run
+ * \param iterations the number of iterations to run the effect; use
+ * `SDL_HAPTIC_INFINITY` to repeat forever
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticStopEffect
- * \sa SDL_HapticDestroyEffect
- * \sa SDL_HapticGetEffectStatus
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticGetEffectStatus
+ * \sa SDL_HapticStopEffect
*/
extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic,
int effect,
@@ -1064,166 +1129,204 @@
Uint32 iterations);
/**
- * \brief Stops the haptic effect on its associated haptic device.
+ * Stop the haptic effect on its associated haptic device.
*
- * \param haptic Haptic device to stop the effect on.
- * \param effect Identifier of the effect to stop.
- * \return 0 on success or -1 on error.
+ * *
*
- * \sa SDL_HapticRunEffect
- * \sa SDL_HapticDestroyEffect
+ * \param haptic the SDL_Haptic device to stop the effect on
+ * \param effect the ID of the haptic effect to stop
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticRunEffect
*/
extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic,
int effect);
/**
- * \brief Destroys a haptic effect on the device.
+ * Destroy a haptic effect on the device.
*
- * This will stop the effect if it's running. Effects are automatically
- * destroyed when the device is closed.
+ * This will stop the effect if it's running. Effects are automatically
+ * destroyed when the device is closed.
*
- * \param haptic Device to destroy the effect on.
- * \param effect Identifier of the effect to destroy.
+ * \param haptic the SDL_Haptic device to destroy the effect on
+ * \param effect the ID of the haptic effect to destroy
*
- * \sa SDL_HapticNewEffect
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticNewEffect
*/
extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic,
int effect);
/**
- * \brief Gets the status of the current effect on the haptic device.
+ * Get the status of the current effect on the specified haptic device.
*
- * Device must support the ::SDL_HAPTIC_STATUS feature.
+ * Device must support the SDL_HAPTIC_STATUS feature.
*
- * \param haptic Haptic device to query the effect status on.
- * \param effect Identifier of the effect to query its status.
- * \return 0 if it isn't playing, 1 if it is playing or -1 on error.
+ * \param haptic the SDL_Haptic device to query for the effect status on
+ * \param effect the ID of the haptic effect to query its status
+ * \returns 0 if it isn't playing, 1 if it is playing, or a negative error
+ * code on failure; call SDL_GetError() for more information.
*
- * \sa SDL_HapticRunEffect
- * \sa SDL_HapticStopEffect
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticRunEffect
+ * \sa SDL_HapticStopEffect
*/
extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic,
int effect);
/**
- * \brief Sets the global gain of the device.
+ * Set the global gain of the specified haptic device.
*
- * Device must support the ::SDL_HAPTIC_GAIN feature.
+ * Device must support the SDL_HAPTIC_GAIN feature.
*
- * The user may specify the maximum gain by setting the environment variable
- * SDL_HAPTIC_GAIN_MAX which should be between 0 and 100. All calls to
- * SDL_HapticSetGain() will scale linearly using SDL_HAPTIC_GAIN_MAX as the
- * maximum.
+ * The user may specify the maximum gain by setting the environment variable
+ * `SDL_HAPTIC_GAIN_MAX` which should be between 0 and 100. All calls to
+ * SDL_HapticSetGain() will scale linearly using `SDL_HAPTIC_GAIN_MAX` as the
+ * maximum.
*
- * \param haptic Haptic device to set the gain on.
- * \param gain Value to set the gain to, should be between 0 and 100.
- * \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device to set the gain on
+ * \param gain value to set the gain to, should be between 0 and 100 (0 - 100)
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticQuery
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticQuery
*/
extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
/**
- * \brief Sets the global autocenter of the device.
+ * Set the global autocenter of the device.
*
- * Autocenter should be between 0 and 100. Setting it to 0 will disable
- * autocentering.
+ * Autocenter should be between 0 and 100. Setting it to 0 will disable
+ * autocentering.
*
- * Device must support the ::SDL_HAPTIC_AUTOCENTER feature.
+ * Device must support the SDL_HAPTIC_AUTOCENTER feature.
*
- * \param haptic Haptic device to set autocentering on.
- * \param autocenter Value to set autocenter to, 0 disables autocentering.
- * \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device to set autocentering on
+ * \param autocenter value to set autocenter to (0-100)
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticQuery
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticQuery
*/
extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic,
int autocenter);
/**
- * \brief Pauses a haptic device.
+ * Pause a haptic device.
*
- * Device must support the ::SDL_HAPTIC_PAUSE feature. Call
- * SDL_HapticUnpause() to resume playback.
+ * Device must support the `SDL_HAPTIC_PAUSE` feature. Call
+ * SDL_HapticUnpause() to resume playback.
*
- * Do not modify the effects nor add new ones while the device is paused.
- * That can cause all sorts of weird errors.
+ * Do not modify the effects nor add new ones while the device is paused. That
+ * can cause all sorts of weird errors.
*
- * \param haptic Haptic device to pause.
- * \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device to pause
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticUnpause
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticUnpause
*/
extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic);
/**
- * \brief Unpauses a haptic device.
+ * Unpause a haptic device.
*
- * Call to unpause after SDL_HapticPause().
+ * Call to unpause after SDL_HapticPause().
*
- * \param haptic Haptic device to unpause.
- * \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device to unpause
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticPause
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticPause
*/
extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic);
/**
- * \brief Stops all the currently playing effects on a haptic device.
+ * Stop all the currently playing effects on a haptic device.
*
- * \param haptic Haptic device to stop.
- * \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device to stop
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
*/
extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic);
/**
- * \brief Checks to see if rumble is supported on a haptic device.
+ * Check whether rumble is supported on a haptic device.
*
- * \param haptic Haptic device to check to see if it supports rumble.
- * \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
+ * \param haptic haptic device to check for rumble support
+ * \returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't, or a
+ * negative error code on failure; call SDL_GetError() for more
+ * information.
*
- * \sa SDL_HapticRumbleInit
- * \sa SDL_HapticRumblePlay
- * \sa SDL_HapticRumbleStop
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticRumbleInit
+ * \sa SDL_HapticRumblePlay
+ * \sa SDL_HapticRumbleStop
*/
extern DECLSPEC int SDLCALL SDL_HapticRumbleSupported(SDL_Haptic * haptic);
/**
- * \brief Initializes the haptic device for simple rumble playback.
+ * Initialize a haptic device for simple rumble playback.
*
- * \param haptic Haptic device to initialize for simple rumble playback.
- * \return 0 on success or -1 on error.
+ * \param haptic the haptic device to initialize for simple rumble playback
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticOpen
- * \sa SDL_HapticRumbleSupported
- * \sa SDL_HapticRumblePlay
- * \sa SDL_HapticRumbleStop
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticOpen
+ * \sa SDL_HapticRumblePlay
+ * \sa SDL_HapticRumbleStop
+ * \sa SDL_HapticRumbleSupported
*/
extern DECLSPEC int SDLCALL SDL_HapticRumbleInit(SDL_Haptic * haptic);
/**
- * \brief Runs simple rumble on a haptic device
+ * Run a simple rumble effect on a haptic device.
*
- * \param haptic Haptic device to play rumble effect on.
- * \param strength Strength of the rumble to play as a 0-1 float value.
- * \param length Length of the rumble to play in milliseconds.
- * \return 0 on success or -1 on error.
+ * \param haptic the haptic device to play the rumble effect on
+ * \param strength strength of the rumble to play as a 0-1 float value
+ * \param length length of the rumble to play in milliseconds
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticRumbleSupported
- * \sa SDL_HapticRumbleInit
- * \sa SDL_HapticRumbleStop
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticRumbleInit
+ * \sa SDL_HapticRumbleStop
+ * \sa SDL_HapticRumbleSupported
*/
extern DECLSPEC int SDLCALL SDL_HapticRumblePlay(SDL_Haptic * haptic, float strength, Uint32 length );
/**
- * \brief Stops the simple rumble on a haptic device.
+ * Stop the simple rumble on a haptic device.
*
- * \param haptic Haptic to stop the rumble on.
- * \return 0 on success or -1 on error.
+ * \param haptic the haptic device to stop the rumble effect on
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticRumbleSupported
- * \sa SDL_HapticRumbleInit
- * \sa SDL_HapticRumblePlay
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticRumbleInit
+ * \sa SDL_HapticRumblePlay
+ * \sa SDL_HapticRumbleSupported
*/
extern DECLSPEC int SDLCALL SDL_HapticRumbleStop(SDL_Haptic * haptic);
@@ -1231,7 +1334,7 @@
#ifdef __cplusplus
}
#endif
-#include "close_code.h"
+#include <SDL2/close_code.h>
#endif /* SDL_haptic_h_ */
--- /dev/null
+++ b/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_hidapi.h
@@ -1,0 +1,451 @@
+/*
+ Simple DirectMedia Layer
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
+
+ This software is provided 'as-is', without any express or implied
+ warranty. In no event will the authors be held liable for any damages
+ arising from the use of this software.
+
+ Permission is granted to anyone to use this software for any purpose,
+ including commercial applications, and to alter it and redistribute it
+ freely, subject to the following restrictions:
+
+ 1. The origin of this software must not be misrepresented; you must not
+ claim that you wrote the original software. If you use this software
+ in a product, an acknowledgment in the product documentation would be
+ appreciated but is not required.
+ 2. Altered source versions must be plainly marked as such, and must not be
+ misrepresented as being the original software.
+ 3. This notice may not be removed or altered from any source distribution.
+*/
+
+/**
+ * \file SDL_hidapi.h
+ *
+ * Header file for SDL HIDAPI functions.
+ *
+ * This is an adaptation of the original HIDAPI interface by Alan Ott,
+ * and includes source code licensed under the following BSD license:
+ *
+ Copyright (c) 2010, Alan Ott, Signal 11 Software
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright notice,
+ this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+ * Neither the name of Signal 11 Software nor the names of its
+ contributors may be used to endorse or promote products derived from
+ this software without specific prior written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ POSSIBILITY OF SUCH DAMAGE.
+ *
+ * If you would like a version of SDL without this code, you can build SDL
+ * with SDL_HIDAPI_DISABLED defined to 1. You might want to do this for example
+ * on iOS or tvOS to avoid a dependency on the CoreBluetooth framework.
+ */
+
+#ifndef SDL_hidapi_h_
+#define SDL_hidapi_h_
+
+#include <SDL2/SDL_stdinc.h>
+
+#include <SDL2/begin_code.h>
+/* Set up for C function definitions, even when using C++ */
+#ifdef __cplusplus
+extern "C" {+#endif
+
+/**
+ * \brief A handle representing an open HID device
+ */
+struct SDL_hid_device_;
+typedef struct SDL_hid_device_ SDL_hid_device; /**< opaque hidapi structure */
+
+/** hidapi info structure */
+/**
+ * \brief Information about a connected HID device
+ */
+typedef struct SDL_hid_device_info
+{+ /** Platform-specific device path */
+ char *path;
+ /** Device Vendor ID */
+ unsigned short vendor_id;
+ /** Device Product ID */
+ unsigned short product_id;
+ /** Serial Number */
+ wchar_t *serial_number;
+ /** Device Release Number in binary-coded decimal,
+ also known as Device Version Number */
+ unsigned short release_number;
+ /** Manufacturer String */
+ wchar_t *manufacturer_string;
+ /** Product string */
+ wchar_t *product_string;
+ /** Usage Page for this Device/Interface
+ (Windows/Mac only). */
+ unsigned short usage_page;
+ /** Usage for this Device/Interface
+ (Windows/Mac only).*/
+ unsigned short usage;
+ /** The USB interface which this logical device
+ represents.
+
+ * Valid on both Linux implementations in all cases.
+ * Valid on the Windows implementation only if the device
+ contains more than one interface. */
+ int interface_number;
+
+ /** Additional information about the USB interface.
+ Valid on libusb and Android implementations. */
+ int interface_class;
+ int interface_subclass;
+ int interface_protocol;
+
+ /** Pointer to the next device */
+ struct SDL_hid_device_info *next;
+} SDL_hid_device_info;
+
+
+/**
+ * Initialize the HIDAPI library.
+ *
+ * This function initializes the HIDAPI library. Calling it is not strictly
+ * necessary, as it will be called automatically by SDL_hid_enumerate() and
+ * any of the SDL_hid_open_*() functions if it is needed. This function should
+ * be called at the beginning of execution however, if there is a chance of
+ * HIDAPI handles being opened by different threads simultaneously.
+ *
+ * Each call to this function should have a matching call to SDL_hid_exit()
+ *
+ * \returns 0 on success and -1 on error.
+ *
+ * \since This function is available since SDL 2.0.18.
+ *
+ * \sa SDL_hid_exit
+ */
+extern DECLSPEC int SDLCALL SDL_hid_init(void);
+
+/**
+ * Finalize the HIDAPI library.
+ *
+ * This function frees all of the static data associated with HIDAPI. It
+ * should be called at the end of execution to avoid memory leaks.
+ *
+ * \returns 0 on success and -1 on error.
+ *
+ * \since This function is available since SDL 2.0.18.
+ *
+ * \sa SDL_hid_init
+ */
+extern DECLSPEC int SDLCALL SDL_hid_exit(void);
+
+/**
+ * Check to see if devices may have been added or removed.
+ *
+ * Enumerating the HID devices is an expensive operation, so you can call this
+ * to see if there have been any system device changes since the last call to
+ * this function. A change in the counter returned doesn't necessarily mean
+ * that anything has changed, but you can call SDL_hid_enumerate() to get an
+ * updated device list.
+ *
+ * Calling this function for the first time may cause a thread or other system
+ * resource to be allocated to track device change notifications.
+ *
+ * \returns a change counter that is incremented with each potential device
+ * change, or 0 if device change detection isn't available.
+ *
+ * \since This function is available since SDL 2.0.18.
+ *
+ * \sa SDL_hid_enumerate
+ */
+extern DECLSPEC Uint32 SDLCALL SDL_hid_device_change_count(void);
+
+/**
+ * Enumerate the HID Devices.
+ *
+ * This function returns a linked list of all the HID devices attached to the
+ * system which match vendor_id and product_id. If `vendor_id` is set to 0
+ * then any vendor matches. If `product_id` is set to 0 then any product
+ * matches. If `vendor_id` and `product_id` are both set to 0, then all HID
+ * devices will be returned.
+ *
+ * \param vendor_id The Vendor ID (VID) of the types of device to open.
+ * \param product_id The Product ID (PID) of the types of device to open.
+ * \returns a pointer to a linked list of type SDL_hid_device_info, containing
+ * information about the HID devices attached to the system, or NULL
+ * in the case of failure. Free this linked list by calling
+ * SDL_hid_free_enumeration().
+ *
+ * \since This function is available since SDL 2.0.18.
+ *
+ * \sa SDL_hid_device_change_count
+ */
+extern DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_enumerate(unsigned short vendor_id, unsigned short product_id);
+
+/**
+ * Free an enumeration Linked List
+ *
+ * This function frees a linked list created by SDL_hid_enumerate().
+ *
+ * \param devs Pointer to a list of struct_device returned from
+ * SDL_hid_enumerate().
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *devs);
+
+/**
+ * Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally
+ * a serial number.
+ *
+ * If `serial_number` is NULL, the first device with the specified VID and PID
+ * is opened.
+ *
+ * \param vendor_id The Vendor ID (VID) of the device to open.
+ * \param product_id The Product ID (PID) of the device to open.
+ * \param serial_number The Serial Number of the device to open (Optionally
+ * NULL).
+ * \returns a pointer to a SDL_hid_device object on success or NULL on
+ * failure.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number);
+
+/**
+ * Open a HID device by its path name.
+ *
+ * The path name be determined by calling SDL_hid_enumerate(), or a
+ * platform-specific path name can be used (eg: /dev/hidraw0 on Linux).
+ *
+ * \param path The path name of the device to open
+ * \returns a pointer to a SDL_hid_device object on success or NULL on
+ * failure.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path, int bExclusive /* = false */);
+
+/**
+ * Write an Output report to a HID device.
+ *
+ * The first byte of `data` must contain the Report ID. For devices which only
+ * support a single report, this must be set to 0x0. The remaining bytes
+ * contain the report data. Since the Report ID is mandatory, calls to
+ * SDL_hid_write() will always contain one more byte than the report contains.
+ * For example, if a hid report is 16 bytes long, 17 bytes must be passed to
+ * SDL_hid_write(), the Report ID (or 0x0, for devices with a single report),
+ * followed by the report data (16 bytes). In this example, the length passed
+ * in would be 17.
+ *
+ * SDL_hid_write() will send the data on the first OUT endpoint, if one
+ * exists. If it does not, it will send the data through the Control Endpoint
+ * (Endpoint 0).
+ *
+ * \param dev A device handle returned from SDL_hid_open().
+ * \param data The data to send, including the report number as the first
+ * byte.
+ * \param length The length in bytes of the data to send.
+ * \returns the actual number of bytes written and -1 on error.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigned char *data, size_t length);
+
+/**
+ * Read an Input report from a HID device with timeout.
+ *
+ * Input reports are returned to the host through the INTERRUPT IN endpoint.
+ * The first byte will contain the Report number if the device uses numbered
+ * reports.
+ *
+ * \param dev A device handle returned from SDL_hid_open().
+ * \param data A buffer to put the read data into.
+ * \param length The number of bytes to read. For devices with multiple
+ * reports, make sure to read an extra byte for the report
+ * number.
+ * \param milliseconds timeout in milliseconds or -1 for blocking wait.
+ * \returns the actual number of bytes read and -1 on error. If no packet was
+ * available to be read within the timeout period, this function
+ * returns 0.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsigned char *data, size_t length, int milliseconds);
+
+/**
+ * Read an Input report from a HID device.
+ *
+ * Input reports are returned to the host through the INTERRUPT IN endpoint.
+ * The first byte will contain the Report number if the device uses numbered
+ * reports.
+ *
+ * \param dev A device handle returned from SDL_hid_open().
+ * \param data A buffer to put the read data into.
+ * \param length The number of bytes to read. For devices with multiple
+ * reports, make sure to read an extra byte for the report
+ * number.
+ * \returns the actual number of bytes read and -1 on error. If no packet was
+ * available to be read and the handle is in non-blocking mode, this
+ * function returns 0.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC int SDLCALL SDL_hid_read(SDL_hid_device *dev, unsigned char *data, size_t length);
+
+/**
+ * Set the device handle to be non-blocking.
+ *
+ * In non-blocking mode calls to SDL_hid_read() will return immediately with a
+ * value of 0 if there is no data to be read. In blocking mode, SDL_hid_read()
+ * will wait (block) until there is data to read before returning.
+ *
+ * Nonblocking can be turned on and off at any time.
+ *
+ * \param dev A device handle returned from SDL_hid_open().
+ * \param nonblock enable or not the nonblocking reads - 1 to enable
+ * nonblocking - 0 to disable nonblocking.
+ * \returns 0 on success and -1 on error.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int nonblock);
+
+/**
+ * Send a Feature report to the device.
+ *
+ * Feature reports are sent over the Control endpoint as a Set_Report
+ * transfer. The first byte of `data` must contain the Report ID. For devices
+ * which only support a single report, this must be set to 0x0. The remaining
+ * bytes contain the report data. Since the Report ID is mandatory, calls to
+ * SDL_hid_send_feature_report() will always contain one more byte than the
+ * report contains. For example, if a hid report is 16 bytes long, 17 bytes
+ * must be passed to SDL_hid_send_feature_report(): the Report ID (or 0x0, for
+ * devices which do not use numbered reports), followed by the report data (16
+ * bytes). In this example, the length passed in would be 17.
+ *
+ * \param dev A device handle returned from SDL_hid_open().
+ * \param data The data to send, including the report number as the first
+ * byte.
+ * \param length The length in bytes of the data to send, including the report
+ * number.
+ * \returns the actual number of bytes written and -1 on error.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev, const unsigned char *data, size_t length);
+
+/**
+ * Get a feature report from a HID device.
+ *
+ * Set the first byte of `data` to the Report ID of the report to be read.
+ * Make sure to allow space for this extra byte in `data`. Upon return, the
+ * first byte will still contain the Report ID, and the report data will start
+ * in data[1].
+ *
+ * \param dev A device handle returned from SDL_hid_open().
+ * \param data A buffer to put the read data into, including the Report ID.
+ * Set the first byte of `data` to the Report ID of the report to
+ * be read, or set it to zero if your device does not use numbered
+ * reports.
+ * \param length The number of bytes to read, including an extra byte for the
+ * report ID. The buffer can be longer than the actual report.
+ * \returns the number of bytes read plus one for the report ID (which is
+ * still in the first byte), or -1 on error.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev, unsigned char *data, size_t length);
+
+/**
+ * Close a HID device.
+ *
+ * \param dev A device handle returned from SDL_hid_open().
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC void SDLCALL SDL_hid_close(SDL_hid_device *dev);
+
+/**
+ * Get The Manufacturer String from a HID device.
+ *
+ * \param dev A device handle returned from SDL_hid_open().
+ * \param string A wide string buffer to put the data into.
+ * \param maxlen The length of the buffer in multiples of wchar_t.
+ * \returns 0 on success and -1 on error.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC int SDLCALL SDL_hid_get_manufacturer_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen);
+
+/**
+ * Get The Product String from a HID device.
+ *
+ * \param dev A device handle returned from SDL_hid_open().
+ * \param string A wide string buffer to put the data into.
+ * \param maxlen The length of the buffer in multiples of wchar_t.
+ * \returns 0 on success and -1 on error.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC int SDLCALL SDL_hid_get_product_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen);
+
+/**
+ * Get The Serial Number String from a HID device.
+ *
+ * \param dev A device handle returned from SDL_hid_open().
+ * \param string A wide string buffer to put the data into.
+ * \param maxlen The length of the buffer in multiples of wchar_t.
+ * \returns 0 on success and -1 on error.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC int SDLCALL SDL_hid_get_serial_number_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen);
+
+/**
+ * Get a string from a HID device, based on its string index.
+ *
+ * \param dev A device handle returned from SDL_hid_open().
+ * \param string_index The index of the string to get.
+ * \param string A wide string buffer to put the data into.
+ * \param maxlen The length of the buffer in multiples of wchar_t.
+ * \returns 0 on success and -1 on error.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev, int string_index, wchar_t *string, size_t maxlen);
+
+/**
+ * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers
+ *
+ * \param active SDL_TRUE to start the scan, SDL_FALSE to stop the scan
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC void SDLCALL SDL_hid_ble_scan(SDL_bool active);
+
+/* Ends C function definitions when using C++ */
+#ifdef __cplusplus
+}
+#endif
+#include <SDL2/close_code.h>
+
+#endif /* SDL_hidapi_h_ */
+
+/* vi: set sts=4 ts=4 sw=4 expandtab: */
--- a/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_hints.h
+++ b/pt_pal_editor/release/macos/pt_pal_editor-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_hints.h
@@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
- Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@@ -39,9 +39,9 @@
#ifndef SDL_hints_h_
#define SDL_hints_h_
-#include "SDL_stdinc.h"
+#include <SDL2/SDL_stdinc.h>
-#include "begin_code.h"
+#include <SDL2/begin_code.h>
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {@@ -48,288 +48,504 @@
#endif
/**
- * \brief A variable controlling how 3D acceleration is used to accelerate the SDL screen surface.
+ * \brief A variable controlling whether the Android / iOS built-in
+ * accelerometer should be listed as a joystick device.
*
- * SDL can try to accelerate the SDL screen surface by using streaming
- * textures with a 3D rendering engine. This variable controls whether and
- * how this is done.
+ * This variable can be set to the following values:
+ * "0" - The accelerometer is not listed as a joystick
+ * "1" - The accelerometer is available as a 3 axis joystick (the default).
+ */
+#define SDL_HINT_ACCELEROMETER_AS_JOYSTICK "SDL_ACCELEROMETER_AS_JOYSTICK"
+
+/**
+ * \brief Specify the behavior of Alt+Tab while the keyboard is grabbed.
*
+ * By default, SDL emulates Alt+Tab functionality while the keyboard is grabbed
+ * and your window is full-screen. This prevents the user from getting stuck in
+ * your application if you've enabled keyboard grab.
+ *
+ * The variable can be set to the following values:
+ * "0" - SDL will not handle Alt+Tab. Your application is responsible
+ for handling Alt+Tab while the keyboard is grabbed.
+ * "1" - SDL will minimize your window when Alt+Tab is pressed (default)
+*/
+#define SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED "SDL_ALLOW_ALT_TAB_WHILE_GRABBED"
+
+/**
+ * \brief If set to "0" then never set the top most bit on a SDL Window, even if the video mode expects it.
+ * This is a debugging aid for developers and not expected to be used by end users. The default is "1"
+ *
* This variable can be set to the following values:
- * "0" - Disable 3D acceleration
- * "1" - Enable 3D acceleration, using the default renderer.
- * "X" - Enable 3D acceleration, using X where X is one of the valid rendering drivers. (e.g. "direct3d", "opengl", etc.)
+ * "0" - don't allow topmost
+ * "1" - allow topmost
+ */
+#define SDL_HINT_ALLOW_TOPMOST "SDL_ALLOW_TOPMOST"
+
+/**
+ * \brief Android APK expansion main file version. Should be a string number like "1", "2" etc.
*
- * By default SDL tries to make a best guess for each platform whether
- * to use acceleration or not.
+ * Must be set together with SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION.
+ *
+ * If both hints were set then SDL_RWFromFile() will look into expansion files
+ * after a given relative path was not found in the internal storage and assets.
+ *
+ * By default this hint is not set and the APK expansion files are not searched.
*/
-#define SDL_HINT_FRAMEBUFFER_ACCELERATION "SDL_FRAMEBUFFER_ACCELERATION"
+#define SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION "SDL_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION"
+
+/**
+ * \brief Android APK expansion patch file version. Should be a string number like "1", "2" etc.
+ *
+ * Must be set together with SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION.
+ *
+ * If both hints were set then SDL_RWFromFile() will look into expansion files
+ * after a given relative path was not found in the internal storage and assets.
+ *
+ * By default this hint is not set and the APK expansion files are not searched.
+ */
+#define SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION "SDL_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION"
/**
- * \brief A variable specifying which render driver to use.
+ * \brief A variable to control whether the event loop will block itself when the app is paused.
*
- * If the application doesn't pick a specific renderer to use, this variable
- * specifies the name of the preferred renderer. If the preferred renderer
- * can't be initialized, the normal default renderer is used.
+ * The variable can be set to the following values:
+ * "0" - Non blocking.
+ * "1" - Blocking. (default)
*
- * This variable is case insensitive and can be set to the following values:
- * "direct3d"
- * "opengl"
- * "opengles2"
- * "opengles"
- * "metal"
- * "software"
+ * The value should be set before SDL is initialized.
+ */
+#define SDL_HINT_ANDROID_BLOCK_ON_PAUSE "SDL_ANDROID_BLOCK_ON_PAUSE"
+
+/**
+ * \brief A variable to control whether SDL will pause audio in background
+ * (Requires SDL_ANDROID_BLOCK_ON_PAUSE as "Non blocking")
*
- * The default varies by platform, but it's the first one in the list that
- * is available on the current platform.
+ * The variable can be set to the following values:
+ * "0" - Non paused.
+ * "1" - Paused. (default)
+ *
+ * The value should be set before SDL is initialized.
*/
-#define SDL_HINT_RENDER_DRIVER "SDL_RENDER_DRIVER"
+#define SDL_HINT_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO "SDL_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO"
/**
- * \brief A variable controlling whether the OpenGL render driver uses shaders if they are available.
+ * \brief A variable to control whether we trap the Android back button to handle it manually.
+ * This is necessary for the right mouse button to work on some Android devices, or
+ * to be able to trap the back button for use in your code reliably. If set to true,
+ * the back button will show up as an SDL_KEYDOWN / SDL_KEYUP pair with a keycode of
+ * SDL_SCANCODE_AC_BACK.
*
- * This variable can be set to the following values:
- * "0" - Disable shaders
- * "1" - Enable shaders
+ * The variable can be set to the following values:
+ * "0" - Back button will be handled as usual for system. (default)
+ * "1" - Back button will be trapped, allowing you to handle the key press
+ * manually. (This will also let right mouse click work on systems
+ * where the right mouse button functions as back.)
*
- * By default shaders are used if OpenGL supports them.
+ * The value of this hint is used at runtime, so it can be changed at any time.
*/
-#define SDL_HINT_RENDER_OPENGL_SHADERS "SDL_RENDER_OPENGL_SHADERS"
+#define SDL_HINT_ANDROID_TRAP_BACK_BUTTON "SDL_ANDROID_TRAP_BACK_BUTTON"
/**
- * \brief A variable controlling whether the Direct3D device is initialized for thread-safe operations.
+ * \brief Specify an application name.
+ *
+ * This hint lets you specify the application name sent to the OS when
+ * required. For example, this will often appear in volume control applets for
+ * audio streams, and in lists of applications which are inhibiting the
+ * screensaver. You should use a string that describes your program ("My Game+ * 2: The Revenge")
*
- * This variable can be set to the following values:
- * "0" - Thread-safety is not enabled (faster)
- * "1" - Thread-safety is enabled
+ * Setting this to "" or leaving it unset will have SDL use a reasonable
+ * default: probably the application's name or "SDL Application" if SDL
+ * doesn't have any better information.
*
- * By default the Direct3D device is created with thread-safety disabled.
+ * Note that, for audio streams, this can be overridden with
+ * SDL_HINT_AUDIO_DEVICE_APP_NAME.
+ *
+ * On targets where this is not supported, this hint does nothing.
*/
-#define SDL_HINT_RENDER_DIRECT3D_THREADSAFE "SDL_RENDER_DIRECT3D_THREADSAFE"
+#define SDL_HINT_APP_NAME "SDL_APP_NAME"
/**
- * \brief A variable controlling whether to enable Direct3D 11+'s Debug Layer.
+ * \brief A variable controlling whether controllers used with the Apple TV
+ * generate UI events.
*
- * This variable does not have any effect on the Direct3D 9 based renderer.
+ * When UI events are generated by controller input, the app will be
+ * backgrounded when the Apple TV remote's menu button is pressed, and when the
+ * pause or B buttons on gamepads are pressed.
*
+ * More information about properly making use of controllers for the Apple TV
+ * can be found here:
+ * https://developer.apple.com/tvos/human-interface-guidelines/remote-and-controllers/
+ *
* This variable can be set to the following values:
- * "0" - Disable Debug Layer use
- * "1" - Enable Debug Layer use
+ * "0" - Controller input does not generate UI events (the default).
+ * "1" - Controller input generates UI events.
+ */
+#define SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS "SDL_APPLE_TV_CONTROLLER_UI_EVENTS"
+
+/**
+ * \brief A variable controlling whether the Apple TV remote's joystick axes
+ * will automatically match the rotation of the remote.
*
- * By default, SDL does not use Direct3D Debug Layer.
+ * This variable can be set to the following values:
+ * "0" - Remote orientation does not affect joystick axes (the default).
+ * "1" - Joystick axes are based on the orientation of the remote.
*/
-#define SDL_HINT_RENDER_DIRECT3D11_DEBUG "SDL_RENDER_DIRECT3D11_DEBUG"
+#define SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION "SDL_APPLE_TV_REMOTE_ALLOW_ROTATION"
/**
- * \brief A variable controlling the scaling policy for SDL_RenderSetLogicalSize.
+ * \brief A variable controlling the audio category on iOS and Mac OS X
*
* This variable can be set to the following values:
- * "0" or "letterbox" - Uses letterbox/sidebars to fit the entire rendering on screen
- * "1" or "overscan" - Will zoom the rendering so it fills the entire screen, allowing edges to be drawn offscreen
*
- * By default letterbox is used
+ * "ambient" - Use the AVAudioSessionCategoryAmbient audio category, will be muted by the phone mute switch (default)
+ * "playback" - Use the AVAudioSessionCategoryPlayback category
+ *
+ * For more information, see Apple's documentation:
+ * https://developer.apple.com/library/content/documentation/Audio/Conceptual/AudioSessionProgrammingGuide/AudioSessionCategoriesandModes/AudioSessionCategoriesandModes.html
*/
-#define SDL_HINT_RENDER_LOGICAL_SIZE_MODE "SDL_RENDER_LOGICAL_SIZE_MODE"
+#define SDL_HINT_AUDIO_CATEGORY "SDL_AUDIO_CATEGORY"
/**
- * \brief A variable controlling the scaling quality
+ * \brief Specify an application name for an audio device.
*
- * This variable can be set to the following values:
- * "0" or "nearest" - Nearest pixel sampling
- * "1" or "linear" - Linear filtering (supported by OpenGL and Direct3D)
- * "2" or "best" - Currently this is the same as "linear"
+ * Some audio backends (such as PulseAudio) allow you to describe your audio
+ * stream. Among other things, this description might show up in a system
+ * control panel that lets the user adjust the volume on specific audio
+ * streams instead of using one giant master volume slider.
*
- * By default nearest pixel sampling is used
+ * This hints lets you transmit that information to the OS. The contents of
+ * this hint are used while opening an audio device. You should use a string
+ * that describes your program ("My Game 2: The Revenge")+ *
+ * Setting this to "" or leaving it unset will have SDL use a reasonable
+ * default: this will be the name set with SDL_HINT_APP_NAME, if that hint is
+ * set. Otherwise, it'll probably the application's name or "SDL Application"
+ * if SDL doesn't have any better information.
+ *
+ * On targets where this is not supported, this hint does nothing.
*/
-#define SDL_HINT_RENDER_SCALE_QUALITY "SDL_RENDER_SCALE_QUALITY"
+#define SDL_HINT_AUDIO_DEVICE_APP_NAME "SDL_AUDIO_DEVICE_APP_NAME"
/**
- * \brief A variable controlling whether updates to the SDL screen surface should be synchronized with the vertical refresh, to avoid tearing.
+ * \brief Specify an application name for an audio device.
*
- * This variable can be set to the following values:
- * "0" - Disable vsync
- * "1" - Enable vsync
+ * Some audio backends (such as PulseAudio) allow you to describe your audio
+ * stream. Among other things, this description might show up in a system
+ * control panel that lets the user adjust the volume on specific audio
+ * streams instead of using one giant master volume slider.
*
- * By default SDL does not sync screen surface updates with vertical refresh.
+ * This hints lets you transmit that information to the OS. The contents of
+ * this hint are used while opening an audio device. You should use a string
+ * that describes your what your program is playing ("audio stream" is+ * probably sufficient in many cases, but this could be useful for something
+ * like "team chat" if you have a headset playing VoIP audio separately).
+ *
+ * Setting this to "" or leaving it unset will have SDL use a reasonable
+ * default: "audio stream" or something similar.
+ *
+ * On targets where this is not supported, this hint does nothing.
*/
-#define SDL_HINT_RENDER_VSYNC "SDL_RENDER_VSYNC"
+#define SDL_HINT_AUDIO_DEVICE_STREAM_NAME "SDL_AUDIO_DEVICE_STREAM_NAME"
/**
- * \brief A variable controlling whether the screensaver is enabled.
+ * \brief Specify an application role for an audio device.
*
- * This variable can be set to the following values:
- * "0" - Disable screensaver
- * "1" - Enable screensaver
+ * Some audio backends (such as Pipewire) allow you to describe the role of
+ * your audio stream. Among other things, this description might show up in
+ * a system control panel or software for displaying and manipulating media
+ * playback/capture graphs.
*
- * By default SDL will disable the screensaver.
+ * This hints lets you transmit that information to the OS. The contents of
+ * this hint are used while opening an audio device. You should use a string
+ * that describes your what your program is playing (Game, Music, Movie,
+ * etc...).
+ *
+ * Setting this to "" or leaving it unset will have SDL use a reasonable
+ * default: "Game" or something similar.
+ *
+ * On targets where this is not supported, this hint does nothing.
*/
-#define SDL_HINT_VIDEO_ALLOW_SCREENSAVER "SDL_VIDEO_ALLOW_SCREENSAVER"
+#define SDL_HINT_AUDIO_DEVICE_STREAM_ROLE "SDL_AUDIO_DEVICE_STREAM_ROLE"
/**
- * \brief A variable controlling whether the X11 VidMode extension should be used.
+ * \brief A variable controlling speed/quality tradeoff of audio resampling.
*
+ * If available, SDL can use libsamplerate ( http://www.mega-nerd.com/SRC/ )
+ * to handle audio resampling. There are different resampling modes available
+ * that produce different levels of quality, using more CPU.
+ *
+ * If this hint isn't specified to a valid setting, or libsamplerate isn't
+ * available, SDL will use the default, internal resampling algorithm.
+ *
+ * As of SDL 2.26, SDL_ConvertAudio() respects this hint when libsamplerate is available.
+ *
+ * This hint is currently only checked at audio subsystem initialization.
+ *
* This variable can be set to the following values:
- * "0" - Disable XVidMode
- * "1" - Enable XVidMode
*
- * By default SDL will use XVidMode if it is available.
+ * "0" or "default" - Use SDL's internal resampling (Default when not set - low quality, fast)
+ * "1" or "fast" - Use fast, slightly higher quality resampling, if available
+ * "2" or "medium" - Use medium quality resampling, if available
+ * "3" or "best" - Use high quality resampling, if available
*/
-#define SDL_HINT_VIDEO_X11_XVIDMODE "SDL_VIDEO_X11_XVIDMODE"
+#define SDL_HINT_AUDIO_RESAMPLING_MODE "SDL_AUDIO_RESAMPLING_MODE"
/**
- * \brief A variable controlling whether the X11 Xinerama extension should be used.
+ * \brief A variable controlling whether SDL updates joystick state when getting input events
*
* This variable can be set to the following values:
- * "0" - Disable Xinerama
- * "1" - Enable Xinerama
*
- * By default SDL will use Xinerama if it is available.
+ * "0" - You'll call SDL_JoystickUpdate() manually
+ * "1" - SDL will automatically call SDL_JoystickUpdate() (default)
+ *
+ * This hint can be toggled on and off at runtime.
*/
-#define SDL_HINT_VIDEO_X11_XINERAMA "SDL_VIDEO_X11_XINERAMA"
+#define SDL_HINT_AUTO_UPDATE_JOYSTICKS "SDL_AUTO_UPDATE_JOYSTICKS"
/**
- * \brief A variable controlling whether the X11 XRandR extension should be used.
+ * \brief A variable controlling whether SDL updates sensor state when getting input events
*
* This variable can be set to the following values:
- * "0" - Disable XRandR
- * "1" - Enable XRandR
*
- * By default SDL will not use XRandR because of window manager issues.
+ * "0" - You'll call SDL_SensorUpdate() manually
+ * "1" - SDL will automatically call SDL_SensorUpdate() (default)
+ *
+ * This hint can be toggled on and off at runtime.
*/
-#define SDL_HINT_VIDEO_X11_XRANDR "SDL_VIDEO_X11_XRANDR"
+#define SDL_HINT_AUTO_UPDATE_SENSORS "SDL_AUTO_UPDATE_SENSORS"
/**
- * \brief A variable controlling whether the X11 _NET_WM_PING protocol should be supported.
+ * \brief Prevent SDL from using version 4 of the bitmap header when saving BMPs.
*
- * This variable can be set to the following values:
- * "0" - Disable _NET_WM_PING
- * "1" - Enable _NET_WM_PING
+ * The bitmap header version 4 is required for proper alpha channel support and
+ * SDL will use it when required. Should this not be desired, this hint can
+ * force the use of the 40 byte header version which is supported everywhere.
*
- * By default SDL will use _NET_WM_PING, but for applications that know they
- * will not always be able to respond to ping requests in a timely manner they can
- * turn it off to avoid the window manager thinking the app is hung.
- * The hint is checked in CreateWindow.
+ * The variable can be set to the following values:
+ * "0" - Surfaces with a colorkey or an alpha channel are saved to a
+ * 32-bit BMP file with an alpha mask. SDL will use the bitmap
+ * header version 4 and set the alpha mask accordingly.
+ * "1" - Surfaces with a colorkey or an alpha channel are saved to a
+ * 32-bit BMP file without an alpha mask. The alpha channel data
+ * will be in the file, but applications are going to ignore it.
+ *
+ * The default value is "0".
*/
-#define SDL_HINT_VIDEO_X11_NET_WM_PING "SDL_VIDEO_X11_NET_WM_PING"
+#define SDL_HINT_BMP_SAVE_LEGACY_FORMAT "SDL_BMP_SAVE_LEGACY_FORMAT"
/**
- * \brief A variable controlling whether the X11 _NET_WM_BYPASS_COMPOSITOR hint should be used.
- *
- * This variable can be set to the following values:
- * "0" - Disable _NET_WM_BYPASS_COMPOSITOR
- * "1" - Enable _NET_WM_BYPASS_COMPOSITOR
- *
- * By default SDL will use _NET_WM_BYPASS_COMPOSITOR
- *
+ * \brief Override for SDL_GetDisplayUsableBounds()
+ *
+ * If set, this hint will override the expected results for
+ * SDL_GetDisplayUsableBounds() for display index 0. Generally you don't want
+ * to do this, but this allows an embedded system to request that some of the
+ * screen be reserved for other uses when paired with a well-behaved
+ * application.
+ *
+ * The contents of this hint must be 4 comma-separated integers, the first
+ * is the bounds x, then y, width and height, in that order.
*/
-#define SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR "SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR"
+#define SDL_HINT_DISPLAY_USABLE_BOUNDS "SDL_DISPLAY_USABLE_BOUNDS"
/**
- * \brief A variable controlling whether the window frame and title bar are interactive when the cursor is hidden
+ * \brief Disable giving back control to the browser automatically
+ * when running with asyncify
*
- * This variable can be set to the following values:
- * "0" - The window frame is not interactive when the cursor is hidden (no move, resize, etc)
- * "1" - The window frame is interactive when the cursor is hidden
+ * With -s ASYNCIFY, SDL2 calls emscripten_sleep during operations
+ * such as refreshing the screen or polling events.
*
- * By default SDL will allow interaction with the window frame when the cursor is hidden
+ * This hint only applies to the emscripten platform
+ *
+ * The variable can be set to the following values:
+ * "0" - Disable emscripten_sleep calls (if you give back browser control manually or use asyncify for other purposes)
+ * "1" - Enable emscripten_sleep calls (the default)
*/
-#define SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN "SDL_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN"
+#define SDL_HINT_EMSCRIPTEN_ASYNCIFY "SDL_EMSCRIPTEN_ASYNCIFY"
/**
- * \brief A variable to specify custom icon resource id from RC file on Windows platform
+ * \brief override the binding element for keyboard inputs for Emscripten builds
+ *
+ * This hint only applies to the emscripten platform
+ *
+ * The variable can be one of
+ * "#window" - The javascript window object (this is the default)
+ * "#document" - The javascript document object
+ * "#screen" - the javascript window.screen object
+ * "#canvas" - the WebGL canvas element
+ * any other string without a leading # sign applies to the element on the page with that ID.
*/
-#define SDL_HINT_WINDOWS_INTRESOURCE_ICON "SDL_WINDOWS_INTRESOURCE_ICON"
-#define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL"
+#define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT"
/**
- * \brief A variable controlling whether the windows message loop is processed by SDL
+ * \brief A variable that controls whether Steam Controllers should be exposed using the SDL joystick and game controller APIs
*
- * This variable can be set to the following values:
- * "0" - The window message loop is not run
- * "1" - The window message loop is processed in SDL_PumpEvents()
+ * The variable can be set to the following values:
+ * "0" - Do not scan for Steam Controllers
+ * "1" - Scan for Steam Controllers (the default)
*
- * By default SDL will process the windows message loop
+ * The default value is "1". This hint must be set before initializing the joystick subsystem.
*/
-#define SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP "SDL_WINDOWS_ENABLE_MESSAGELOOP"
+#define SDL_HINT_ENABLE_STEAM_CONTROLLERS "SDL_ENABLE_STEAM_CONTROLLERS"
/**
- * \brief A variable controlling whether grabbing input grabs the keyboard
+ * \brief A variable controlling verbosity of the logging of SDL events pushed onto the internal queue.
*
+ * This variable can be set to the following values, from least to most verbose:
+ *
+ * "0" - Don't log any events (default)
+ * "1" - Log most events (other than the really spammy ones).
+ * "2" - Include mouse and finger motion events.
+ * "3" - Include SDL_SysWMEvent events.
+ *
+ * This is generally meant to be used to debug SDL itself, but can be useful
+ * for application developers that need better visibility into what is going
+ * on in the event queue. Logged events are sent through SDL_Log(), which
+ * means by default they appear on stdout on most platforms or maybe
+ * OutputDebugString() on Windows, and can be funneled by the app with
+ * SDL_LogSetOutputFunction(), etc.
+ *
+ * This hint can be toggled on and off at runtime, if you only need to log
+ * events for a small subset of program execution.
+ */
+#define SDL_HINT_EVENT_LOGGING "SDL_EVENT_LOGGING"
+
+/**
+ * \brief A variable controlling whether raising the window should be done more forcefully
+ *
* This variable can be set to the following values:
- * "0" - Grab will affect only the mouse
- * "1" - Grab will affect mouse and keyboard
+ * "0" - No forcing (the default)
+ * "1" - Extra level of forcing
*
- * By default SDL will not grab the keyboard so system shortcuts still work.
+ * At present, this is only an issue under MS Windows, which makes it nearly impossible to
+ * programmatically move a window to the foreground, for "security" reasons. See
+ * http://stackoverflow.com/a/34414846 for a discussion.
*/
-#define SDL_HINT_GRAB_KEYBOARD "SDL_GRAB_KEYBOARD"
+#define SDL_HINT_FORCE_RAISEWINDOW "SDL_HINT_FORCE_RAISEWINDOW"
/**
- * \brief A variable setting the double click time, in milliseconds.
+ * \brief A variable controlling how 3D acceleration is used to accelerate the SDL screen surface.
+ *
+ * SDL can try to accelerate the SDL screen surface by using streaming
+ * textures with a 3D rendering engine. This variable controls whether and
+ * how this is done.
+ *
+ * This variable can be set to the following values:
+ * "0" - Disable 3D acceleration
+ * "1" - Enable 3D acceleration, using the default renderer.
+ * "X" - Enable 3D acceleration, using X where X is one of the valid rendering drivers. (e.g. "direct3d", "opengl", etc.)
+ *
+ * By default SDL tries to make a best guess for each platform whether
+ * to use acceleration or not.
*/
-#define SDL_HINT_MOUSE_DOUBLE_CLICK_TIME "SDL_MOUSE_DOUBLE_CLICK_TIME"
+#define SDL_HINT_FRAMEBUFFER_ACCELERATION "SDL_FRAMEBUFFER_ACCELERATION"
/**
- * \brief A variable setting the double click radius, in pixels.
+ * \brief A variable that lets you manually hint extra gamecontroller db entries.
+ *
+ * The variable should be newline delimited rows of gamecontroller config data, see SDL_gamecontroller.h
+ *
+ * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER)
+ * You can update mappings after the system is initialized with SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping()
*/
-#define SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS "SDL_MOUSE_DOUBLE_CLICK_RADIUS"
+#define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG"
/**
- * \brief A variable setting the speed scale for mouse motion, in floating point, when the mouse is not in relative mode
+ * \brief A variable that lets you provide a file with extra gamecontroller db entries.
+ *
+ * The file should contain lines of gamecontroller config data, see SDL_gamecontroller.h
+ *
+ * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER)
+ * You can update mappings after the system is initialized with SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping()
*/
-#define SDL_HINT_MOUSE_NORMAL_SPEED_SCALE "SDL_MOUSE_NORMAL_SPEED_SCALE"
+#define SDL_HINT_GAMECONTROLLERCONFIG_FILE "SDL_GAMECONTROLLERCONFIG_FILE"
/**
- * \brief A variable setting the scale for mouse motion, in floating point, when the mouse is in relative mode
+ * \brief A variable that overrides the automatic controller type detection
+ *
+ * The variable should be comma separated entries, in the form: VID/PID=type
+ *
+ * The VID and PID should be hexadecimal with exactly 4 digits, e.g. 0x00fd
+ *
+ * The type should be one of:
+ * Xbox360
+ * XboxOne
+ * PS3
+ * PS4
+ * PS5
+ * SwitchPro
+ *
+ * This hint affects what driver is used, and must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER)
*/
-#define SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE "SDL_MOUSE_RELATIVE_SPEED_SCALE"
+#define SDL_HINT_GAMECONTROLLERTYPE "SDL_GAMECONTROLLERTYPE"
/**
- * \brief A variable controlling whether relative mouse mode is implemented using mouse warping
+ * \brief A variable containing a list of devices to skip when scanning for game controllers.
*
- * This variable can be set to the following values:
- * "0" - Relative mouse mode uses raw input
- * "1" - Relative mouse mode uses mouse warping
+ * The format of the string is a comma separated list of USB VID/PID pairs
+ * in hexadecimal form, e.g.
*
- * By default SDL will use raw input for relative mouse mode
+ * 0xAAAA/0xBBBB,0xCCCC/0xDDDD
+ *
+ * The variable can also take the form of @file, in which case the named
+ * file will be loaded and interpreted as the value of the variable.
*/
-#define SDL_HINT_MOUSE_RELATIVE_MODE_WARP "SDL_MOUSE_RELATIVE_MODE_WARP"
+#define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES "SDL_GAMECONTROLLER_IGNORE_DEVICES"
/**
- * \brief Allow mouse click events when clicking to focus an SDL window
+ * \brief If set, all devices will be skipped when scanning for game controllers except for the ones listed in this variable.
*
- * This variable can be set to the following values:
- * "0" - Ignore mouse clicks that activate a window
- * "1" - Generate events for mouse clicks that activate a window
+ * The format of the string is a comma separated list of USB VID/PID pairs
+ * in hexadecimal form, e.g.
*
- * By default SDL will ignore mouse clicks that activate a window
+ * 0xAAAA/0xBBBB,0xCCCC/0xDDDD
+ *
+ * The variable can also take the form of @file, in which case the named
+ * file will be loaded and interpreted as the value of the variable.
*/
-#define SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH "SDL_MOUSE_FOCUS_CLICKTHROUGH"
+#define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT"
/**
- * \brief A variable controlling whether touch events should generate synthetic mouse events
+ * \brief If set, game controller face buttons report their values according to their labels instead of their positional layout.
+ *
+ * For example, on Nintendo Switch controllers, normally you'd get:
*
- * This variable can be set to the following values:
- * "0" - Touch events will not generate mouse events
- * "1" - Touch events will generate mouse events
+ * (Y)
+ * (X) (B)
+ * (A)
*
- * By default SDL will generate mouse events for touch events
+ * but if this hint is set, you'll get:
+ *
+ * (X)
+ * (Y) (A)
+ * (B)
+ *
+ * The variable can be set to the following values:
+ * "0" - Report the face buttons by position, as though they were on an Xbox controller.
+ * "1" - Report the face buttons by label instead of position
+ *
+ * The default value is "1". This hint may be set at any time.
*/
-#define SDL_HINT_TOUCH_MOUSE_EVENTS "SDL_TOUCH_MOUSE_EVENTS"
+#define SDL_HINT_GAMECONTROLLER_USE_BUTTON_LABELS "SDL_GAMECONTROLLER_USE_BUTTON_LABELS"
/**
- * \brief A variable controlling whether mouse events should generate synthetic touch events
+ * \brief A variable controlling whether grabbing input grabs the keyboard
*
* This variable can be set to the following values:
- * "0" - Mouse events will not generate touch events (default for desktop platforms)
- * "1" - Mouse events will generate touch events (default for mobile platforms, such as Android and iOS)
+ * "0" - Grab will affect only the mouse
+ * "1" - Grab will affect mouse and keyboard
+ *
+ * By default SDL will not grab the keyboard so system shortcuts still work.
*/
+#define SDL_HINT_GRAB_KEYBOARD "SDL_GRAB_KEYBOARD"
-#define SDL_HINT_MOUSE_TOUCH_EVENTS "SDL_MOUSE_TOUCH_EVENTS"
-
/**
- * \brief Minimize your SDL_Window if it loses key focus when in fullscreen mode. Defaults to true.
+ * \brief A variable containing a list of devices to ignore in SDL_hid_enumerate()
*
+ * For example, to ignore the Shanwan DS3 controller and any Valve controller, you might
+ * have the string "0x2563/0x0523,0x28de/0x0000"
*/
-#define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS"
+#define SDL_HINT_HIDAPI_IGNORE_DEVICES "SDL_HIDAPI_IGNORE_DEVICES"
/**
* \brief A variable controlling whether the idle timer is disabled on iOS.
@@ -349,43 +565,36 @@
#define SDL_HINT_IDLE_TIMER_DISABLED "SDL_IOS_IDLE_TIMER_DISABLED"
/**
- * \brief A variable controlling which orientations are allowed on iOS/Android.
+ * \brief A variable to control whether certain IMEs should handle text editing internally instead of sending SDL_TEXTEDITING events.
*
- * In some circumstances it is necessary to be able to explicitly control
- * which UI orientations are allowed.
- *
- * This variable is a space delimited list of the following values:
- * "LandscapeLeft", "LandscapeRight", "Portrait" "PortraitUpsideDown"
+ * The variable can be set to the following values:
+ * "0" - SDL_TEXTEDITING events are sent, and it is the application's
+ * responsibility to render the text from these events and
+ * differentiate it somehow from committed text. (default)
+ * "1" - If supported by the IME then SDL_TEXTEDITING events are not sent,
+ * and text that is being composed will be rendered in its own UI.
*/
-#define SDL_HINT_ORIENTATIONS "SDL_IOS_ORIENTATIONS"
+#define SDL_HINT_IME_INTERNAL_EDITING "SDL_IME_INTERNAL_EDITING"
/**
- * \brief A variable controlling whether controllers used with the Apple TV
- * generate UI events.
+ * \brief A variable to control whether certain IMEs should show native UI components (such as the Candidate List) instead of suppressing them.
*
- * When UI events are generated by controller input, the app will be
- * backgrounded when the Apple TV remote's menu button is pressed, and when the
- * pause or B buttons on gamepads are pressed.
- *
- * More information about properly making use of controllers for the Apple TV
- * can be found here:
- * https://developer.apple.com/tvos/human-interface-guidelines/remote-and-controllers/
- *
- * This variable can be set to the following values:
- * "0" - Controller input does not generate UI events (the default).
- * "1" - Controller input generates UI events.
+ * The variable can be set to the following values:
+ * "0" - Native UI components are not display. (default)
+ * "1" - Native UI components are displayed.
*/
-#define SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS "SDL_APPLE_TV_CONTROLLER_UI_EVENTS"
+#define SDL_HINT_IME_SHOW_UI "SDL_IME_SHOW_UI"
/**
- * \brief A variable controlling whether the Apple TV remote's joystick axes
- * will automatically match the rotation of the remote.
+ * \brief A variable to control if extended IME text support is enabled.
+ * If enabled then SDL_TextEditingExtEvent will be issued if the text would be truncated otherwise.
+ * Additionally SDL_TextInputEvent will be dispatched multiple times so that it is not truncated.
*
- * This variable can be set to the following values:
- * "0" - Remote orientation does not affect joystick axes (the default).
- * "1" - Joystick axes are based on the orientation of the remote.
+ * The variable can be set to the following values:
+ * "0" - Legacy behavior. Text can be truncated, no heap allocations. (default)
+ * "1" - Modern behavior.
*/
-#define SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION "SDL_APPLE_TV_REMOTE_ALLOW_ROTATION"
+#define SDL_HINT_IME_SUPPORT_EXTENDED_TEXT "SDL_IME_SUPPORT_EXTENDED_TEXT"
/**
* \brief A variable controlling whether the home indicator bar on iPhone X
@@ -399,115 +608,166 @@
#define SDL_HINT_IOS_HIDE_HOME_INDICATOR "SDL_IOS_HIDE_HOME_INDICATOR"
/**
- * \brief A variable controlling whether the Android / iOS built-in
- * accelerometer should be listed as a joystick device.
+ * \brief A variable that lets you enable joystick (and gamecontroller) events even when your app is in the background.
*
- * This variable can be set to the following values:
- * "0" - The accelerometer is not listed as a joystick
- * "1" - The accelerometer is available as a 3 axis joystick (the default).
+ * The variable can be set to the following values:
+ * "0" - Disable joystick & gamecontroller input events when the
+ * application is in the background.
+ * "1" - Enable joystick & gamecontroller input events when the
+ * application is in the background.
+ *
+ * The default value is "0". This hint may be set at any time.
*/
-#define SDL_HINT_ACCELEROMETER_AS_JOYSTICK "SDL_ACCELEROMETER_AS_JOYSTICK"
+#define SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS "SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS"
/**
- * \brief A variable controlling whether the Android / tvOS remotes
- * should be listed as joystick devices, instead of sending keyboard events.
+ * \brief A variable controlling whether the HIDAPI joystick drivers should be used.
*
* This variable can be set to the following values:
- * "0" - Remotes send enter/escape/arrow key events
- * "1" - Remotes are available as 2 axis, 2 button joysticks (the default).
- */
-#define SDL_HINT_TV_REMOTE_AS_JOYSTICK "SDL_TV_REMOTE_AS_JOYSTICK"
-
-/**
- * \brief A variable that lets you disable the detection and use of Xinput gamepad devices
+ * "0" - HIDAPI drivers are not used
+ * "1" - HIDAPI drivers are used (the default)
*
- * The variable can be set to the following values:
- * "0" - Disable XInput detection (only uses direct input)
- * "1" - Enable XInput detection (the default)
+ * This variable is the default for all drivers, but can be overridden by the hints for specific drivers below.
*/
-#define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED"
+#define SDL_HINT_JOYSTICK_HIDAPI "SDL_JOYSTICK_HIDAPI"
/**
- * \brief A variable that causes SDL to use the old axis and button mapping for XInput devices.
+ * \brief A variable controlling whether the HIDAPI driver for Nintendo GameCube controllers should be used.
*
- * This hint is for backwards compatibility only and will be removed in SDL 2.1
+ * This variable can be set to the following values:
+ * "0" - HIDAPI driver is not used
+ * "1" - HIDAPI driver is used
*
- * The default value is "0". This hint must be set before SDL_Init()
+ * The default is the value of SDL_HINT_JOYSTICK_HIDAPI
*/
-#define SDL_HINT_XINPUT_USE_OLD_JOYSTICK_MAPPING "SDL_XINPUT_USE_OLD_JOYSTICK_MAPPING"
+#define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE "SDL_JOYSTICK_HIDAPI_GAMECUBE"
/**
- * \brief A variable that lets you manually hint extra gamecontroller db entries.
+ * \brief A variable controlling whether "low_frequency_rumble" and "high_frequency_rumble" is used to implement
+ * the GameCube controller's 3 rumble modes, Stop(0), Rumble(1), and StopHard(2)
+ * this is useful for applications that need full compatibility for things like ADSR envelopes.
+ * Stop is implemented by setting "low_frequency_rumble" to "0" and "high_frequency_rumble" ">0"
+ * Rumble is both at any arbitrary value,
+ * StopHard is implemented by setting both "low_frequency_rumble" and "high_frequency_rumble" to "0"
*
- * The variable should be newline delimited rows of gamecontroller config data, see SDL_gamecontroller.h
+ * This variable can be set to the following values:
+ * "0" - Normal rumble behavior is behavior is used (default)
+ * "1" - Proper GameCube controller rumble behavior is used
*
- * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER)
- * You can update mappings after the system is initialized with SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping()
*/
-#define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG"
+#define SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE "SDL_JOYSTICK_GAMECUBE_RUMBLE_BRAKE"
/**
- * \brief A variable that lets you provide a file with extra gamecontroller db entries.
- *
- * The file should contain lines of gamecontroller config data, see SDL_gamecontroller.h
- *
- * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER)
- * You can update mappings after the system is initialized with SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping()
- */
-#define SDL_HINT_GAMECONTROLLERCONFIG_FILE "SDL_GAMECONTROLLERCONFIG_FILE"
+ * \brief A variable controlling whether the HIDAPI driver for Nintendo Switch Joy-Cons should be used.
+ *
+ * This variable can be set to the following values:
+ * "0" - HIDAPI driver is not used
+ * "1" - HIDAPI driver is used
+ *
+ * The default is the value of SDL_HINT_JOYSTICK_HIDAPI
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_JOY_CONS "SDL_JOYSTICK_HIDAPI_JOY_CONS"
/**
- * \brief A variable containing a list of devices to skip when scanning for game controllers.
- *
- * The format of the string is a comma separated list of USB VID/PID pairs
- * in hexadecimal form, e.g.
- *
- * 0xAAAA/0xBBBB,0xCCCC/0xDDDD
- *
- * The variable can also take the form of @file, in which case the named
- * file will be loaded and interpreted as the value of the variable.
- */
-#define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES "SDL_GAMECONTROLLER_IGNORE_DEVICES"
+ * \brief A variable controlling whether Nintendo Switch Joy-Con controllers will be combined into a single Pro-like controller when using the HIDAPI driver
+ *
+ * This variable can be set to the following values:
+ * "0" - Left and right Joy-Con controllers will not be combined and each will be a mini-gamepad
+ * "1" - Left and right Joy-Con controllers will be combined into a single controller (the default)
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_COMBINE_JOY_CONS "SDL_JOYSTICK_HIDAPI_COMBINE_JOY_CONS"
/**
- * \brief If set, all devices will be skipped when scanning for game controllers except for the ones listed in this variable.
+ * \brief A variable controlling whether Nintendo Switch Joy-Con controllers will be in vertical mode when using the HIDAPI driver
+ *
+ * This variable can be set to the following values:
+ * "0" - Left and right Joy-Con controllers will not be in vertical mode (the default)
+ * "1" - Left and right Joy-Con controllers will be in vertical mode
+ *
+ * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER)
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS "SDL_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS"
+
+/**
+ * \brief A variable controlling whether the HIDAPI driver for Amazon Luna controllers connected via Bluetooth should be used.
+ *
+ * This variable can be set to the following values:
+ * "0" - HIDAPI driver is not used
+ * "1" - HIDAPI driver is used
+ *
+ * The default is the value of SDL_HINT_JOYSTICK_HIDAPI
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_LUNA "SDL_JOYSTICK_HIDAPI_LUNA"
+
+/**
+ * \brief A variable controlling whether the HIDAPI driver for Nintendo Online classic controllers should be used.
+ *
+ * This variable can be set to the following values:
+ * "0" - HIDAPI driver is not used
+ * "1" - HIDAPI driver is used
+ *
+ * The default is the value of SDL_HINT_JOYSTICK_HIDAPI
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_NINTENDO_CLASSIC "SDL_JOYSTICK_HIDAPI_NINTENDO_CLASSIC"
+
+/**
+ * \brief A variable controlling whether the HIDAPI driver for NVIDIA SHIELD controllers should be used.
+ *
+ * This variable can be set to the following values:
+ * "0" - HIDAPI driver is not used
+ * "1" - HIDAPI driver is used
+ *
+ * The default is the value of SDL_HINT_JOYSTICK_HIDAPI
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_SHIELD "SDL_JOYSTICK_HIDAPI_SHIELD"
+
+/**
+ * \brief A variable controlling whether the HIDAPI driver for PS3 controllers should be used.
*
- * The format of the string is a comma separated list of USB VID/PID pairs
- * in hexadecimal form, e.g.
+ * This variable can be set to the following values:
+ * "0" - HIDAPI driver is not used
+ * "1" - HIDAPI driver is used
*
- * 0xAAAA/0xBBBB,0xCCCC/0xDDDD
+ * The default is the value of SDL_HINT_JOYSTICK_HIDAPI on macOS, and "0" on other platforms.
*
- * The variable can also take the form of @file, in which case the named
- * file will be loaded and interpreted as the value of the variable.
+ * It is not possible to use this driver on Windows, due to limitations in the default drivers
+ * installed. See https://github.com/ViGEm/DsHidMini for an alternative driver on Windows.
*/
-#define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT"
+#define SDL_HINT_JOYSTICK_HIDAPI_PS3 "SDL_JOYSTICK_HIDAPI_PS3"
/**
- * \brief A variable that lets you enable joystick (and gamecontroller) events even when your app is in the background.
+ * \brief A variable controlling whether the HIDAPI driver for PS4 controllers should be used.
*
- * The variable can be set to the following values:
- * "0" - Disable joystick & gamecontroller input events when the
- * application is in the background.
- * "1" - Enable joystick & gamecontroller input events when the
- * application is in the background.
+ * This variable can be set to the following values:
+ * "0" - HIDAPI driver is not used
+ * "1" - HIDAPI driver is used
*
- * The default value is "0". This hint may be set at any time.
+ * The default is the value of SDL_HINT_JOYSTICK_HIDAPI
*/
-#define SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS "SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS"
+#define SDL_HINT_JOYSTICK_HIDAPI_PS4 "SDL_JOYSTICK_HIDAPI_PS4"
/**
- * \brief A variable controlling whether the HIDAPI joystick drivers should be used.
+ * \brief A variable controlling whether extended input reports should be used for PS4 controllers when using the HIDAPI driver.
*
* This variable can be set to the following values:
- * "0" - HIDAPI drivers are not used
- * "1" - HIDAPI drivers are used (the default)
+ * "0" - extended reports are not enabled (the default)
+ * "1" - extended reports
*
- * This variable is the default for all drivers, but can be overridden by the hints for specific drivers below.
+ * Extended input reports allow rumble on Bluetooth PS4 controllers, but
+ * break DirectInput handling for applications that don't use SDL.
+ *
+ * Once extended reports are enabled, they can not be disabled without
+ * power cycling the controller.
+ *
+ * For compatibility with applications written for versions of SDL prior
+ * to the introduction of PS5 controller support, this value will also
+ * control the state of extended reports on PS5 controllers when the
+ * SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE hint is not explicitly set.
*/
-#define SDL_HINT_JOYSTICK_HIDAPI "SDL_JOYSTICK_HIDAPI"
+#define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE "SDL_JOYSTICK_HIDAPI_PS4_RUMBLE"
/**
- * \brief A variable controlling whether the HIDAPI driver for PS4 controllers should be used.
+ * \brief A variable controlling whether the HIDAPI driver for PS5 controllers should be used.
*
* This variable can be set to the following values:
* "0" - HIDAPI driver is not used
@@ -515,25 +775,38 @@
*
* The default is the value of SDL_HINT_JOYSTICK_HIDAPI
*/
-#define SDL_HINT_JOYSTICK_HIDAPI_PS4 "SDL_JOYSTICK_HIDAPI_PS4"
+#define SDL_HINT_JOYSTICK_HIDAPI_PS5 "SDL_JOYSTICK_HIDAPI_PS5"
/**
- * \brief A variable controlling whether extended input reports should be used for PS4 controllers when using the HIDAPI driver.
+ * \brief A variable controlling whether the player LEDs should be lit to indicate which player is associated with a PS5 controller.
*
* This variable can be set to the following values:
+ * "0" - player LEDs are not enabled
+ * "1" - player LEDs are enabled (the default)
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_PS5_PLAYER_LED "SDL_JOYSTICK_HIDAPI_PS5_PLAYER_LED"
+
+/**
+ * \brief A variable controlling whether extended input reports should be used for PS5 controllers when using the HIDAPI driver.
+ *
+ * This variable can be set to the following values:
* "0" - extended reports are not enabled (the default)
* "1" - extended reports
*
- * Extended input reports allow rumble on Bluetooth PS4 controllers, but
+ * Extended input reports allow rumble on Bluetooth PS5 controllers, but
* break DirectInput handling for applications that don't use SDL.
*
* Once extended reports are enabled, they can not be disabled without
* power cycling the controller.
+ *
+ * For compatibility with applications written for versions of SDL prior
+ * to the introduction of PS5 controller support, this value defaults to
+ * the value of SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE.
*/
-#define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE "SDL_JOYSTICK_HIDAPI_PS4_RUMBLE"
+#define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE "SDL_JOYSTICK_HIDAPI_PS5_RUMBLE"
/**
- * \brief A variable controlling whether the HIDAPI driver for Steam Controllers should be used.
+ * \brief A variable controlling whether the HIDAPI driver for Google Stadia controllers should be used.
*
* This variable can be set to the following values:
* "0" - HIDAPI driver is not used
@@ -541,6 +814,18 @@
*
* The default is the value of SDL_HINT_JOYSTICK_HIDAPI
*/
+#define SDL_HINT_JOYSTICK_HIDAPI_STADIA "SDL_JOYSTICK_HIDAPI_STADIA"
+
+/**
+ * \brief A variable controlling whether the HIDAPI driver for Bluetooth Steam Controllers should be used.
+ *
+ * This variable can be set to the following values:
+ * "0" - HIDAPI driver is not used
+ * "1" - HIDAPI driver is used for Steam Controllers, which requires Bluetooth access
+ * and may prompt the user for permission on iOS and Android.
+ *
+ * The default is "0"
+ */
#define SDL_HINT_JOYSTICK_HIDAPI_STEAM "SDL_JOYSTICK_HIDAPI_STEAM"
/**
@@ -555,6 +840,57 @@
#define SDL_HINT_JOYSTICK_HIDAPI_SWITCH "SDL_JOYSTICK_HIDAPI_SWITCH"
/**
+ * \brief A variable controlling whether the Home button LED should be turned on when a Nintendo Switch Pro controller is opened
+ *
+ * This variable can be set to the following values:
+ * "0" - home button LED is turned off
+ * "1" - home button LED is turned on
+ *
+ * By default the Home button LED state is not changed. This hint can also be set to a floating point value between 0.0 and 1.0 which controls the brightness of the Home button LED.
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_HOME_LED "SDL_JOYSTICK_HIDAPI_SWITCH_HOME_LED"
+
+/**
+ * \brief A variable controlling whether the Home button LED should be turned on when a Nintendo Switch Joy-Con controller is opened
+ *
+ * This variable can be set to the following values:
+ * "0" - home button LED is turned off
+ * "1" - home button LED is turned on
+ *
+ * By default the Home button LED state is not changed. This hint can also be set to a floating point value between 0.0 and 1.0 which controls the brightness of the Home button LED.
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_JOYCON_HOME_LED "SDL_JOYSTICK_HIDAPI_JOYCON_HOME_LED"
+
+/**
+ * \brief A variable controlling whether the player LEDs should be lit to indicate which player is associated with a Nintendo Switch controller.
+ *
+ * This variable can be set to the following values:
+ * "0" - player LEDs are not enabled
+ * "1" - player LEDs are enabled (the default)
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED "SDL_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED"
+
+/**
+ * \brief A variable controlling whether the HIDAPI driver for Nintendo Wii and Wii U controllers should be used.
+ *
+ * This variable can be set to the following values:
+ * "0" - HIDAPI driver is not used
+ * "1" - HIDAPI driver is used
+ *
+ * This driver doesn't work with the dolphinbar, so the default is SDL_FALSE for now.
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_WII "SDL_JOYSTICK_HIDAPI_WII"
+
+/**
+ * \brief A variable controlling whether the player LEDs should be lit to indicate which player is associated with a Wii controller.
+ *
+ * This variable can be set to the following values:
+ * "0" - player LEDs are not enabled
+ * "1" - player LEDs are enabled (the default)
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_WII_PLAYER_LED "SDL_JOYSTICK_HIDAPI_WII_PLAYER_LED"
+
+/**
* \brief A variable controlling whether the HIDAPI driver for XBox controllers should be used.
*
* This variable can be set to the following values:
@@ -561,97 +897,182 @@
* "0" - HIDAPI driver is not used
* "1" - HIDAPI driver is used
*
- * The default is the value of SDL_HINT_JOYSTICK_HIDAPI
+ * The default is "0" on Windows, otherwise the value of SDL_HINT_JOYSTICK_HIDAPI
*/
#define SDL_HINT_JOYSTICK_HIDAPI_XBOX "SDL_JOYSTICK_HIDAPI_XBOX"
/**
- * \brief A variable that controls whether Steam Controllers should be exposed using the SDL joystick and game controller APIs
+ * \brief A variable controlling whether the HIDAPI driver for XBox 360 controllers should be used.
*
- * The variable can be set to the following values:
- * "0" - Do not scan for Steam Controllers
- * "1" - Scan for Steam Controllers (the default)
+ * This variable can be set to the following values:
+ * "0" - HIDAPI driver is not used
+ * "1" - HIDAPI driver is used
*
- * The default value is "1". This hint must be set before initializing the joystick subsystem.
+ * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX
*/
-#define SDL_HINT_ENABLE_STEAM_CONTROLLERS "SDL_ENABLE_STEAM_CONTROLLERS"
+#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 "SDL_JOYSTICK_HIDAPI_XBOX_360"
-
/**
- * \brief If set to "0" then never set the top most bit on a SDL Window, even if the video mode expects it.
- * This is a debugging aid for developers and not expected to be used by end users. The default is "1"
+ * \brief A variable controlling whether the player LEDs should be lit to indicate which player is associated with an Xbox 360 controller.
*
* This variable can be set to the following values:
- * "0" - don't allow topmost
- * "1" - allow topmost
+ * "0" - player LEDs are not enabled
+ * "1" - player LEDs are enabled (the default)
*/
-#define SDL_HINT_ALLOW_TOPMOST "SDL_ALLOW_TOPMOST"
+#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED "SDL_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED"
/**
- * \brief A variable that controls the timer resolution, in milliseconds.
+ * \brief A variable controlling whether the HIDAPI driver for XBox 360 wireless controllers should be used.
*
- * The higher resolution the timer, the more frequently the CPU services
- * timer interrupts, and the more precise delays are, but this takes up
- * power and CPU time. This hint is only used on Windows 7 and earlier.
+ * This variable can be set to the following values:
+ * "0" - HIDAPI driver is not used
+ * "1" - HIDAPI driver is used
*
- * See this blog post for more information:
- * http://randomascii.wordpress.com/2013/07/08/windows-timer-resolution-megawatts-wasted/
+ * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX_360
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_WIRELESS "SDL_JOYSTICK_HIDAPI_XBOX_360_WIRELESS"
+
+/**
+ * \brief A variable controlling whether the HIDAPI driver for XBox One controllers should be used.
*
- * If this variable is set to "0", the system timer resolution is not set.
+ * This variable can be set to the following values:
+ * "0" - HIDAPI driver is not used
+ * "1" - HIDAPI driver is used
*
- * The default value is "1". This hint may be set at any time.
+ * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX
*/
-#define SDL_HINT_TIMER_RESOLUTION "SDL_TIMER_RESOLUTION"
+#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE "SDL_JOYSTICK_HIDAPI_XBOX_ONE"
-
/**
- * \brief A variable describing the content orientation on QtWayland-based platforms.
+ * \brief A variable controlling whether the Home button LED should be turned on when an Xbox One controller is opened
*
- * On QtWayland platforms, windows are rotated client-side to allow for custom
- * transitions. In order to correctly position overlays (e.g. volume bar) and
- * gestures (e.g. events view, close/minimize gestures), the system needs to
- * know in which orientation the application is currently drawing its contents.
+ * This variable can be set to the following values:
+ * "0" - home button LED is turned off
+ * "1" - home button LED is turned on
*
- * This does not cause the window to be rotated or resized, the application
- * needs to take care of drawing the content in the right orientation (the
- * framebuffer is always in portrait mode).
- *
- * This variable can be one of the following values:
- * "primary" (default), "portrait", "landscape", "inverted-portrait", "inverted-landscape"
+ * By default the Home button LED state is not changed. This hint can also be set to a floating point value between 0.0 and 1.0 which controls the brightness of the Home button LED. The default brightness is 0.4.
*/
-#define SDL_HINT_QTWAYLAND_CONTENT_ORIENTATION "SDL_QTWAYLAND_CONTENT_ORIENTATION"
+#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED "SDL_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED"
/**
- * \brief Flags to set on QtWayland windows to integrate with the native window manager.
+ * \brief A variable controlling whether the RAWINPUT joystick drivers should be used for better handling XInput-capable devices.
+ *
+ * This variable can be set to the following values:
+ * "0" - RAWINPUT drivers are not used
+ * "1" - RAWINPUT drivers are used (the default)
+ */
+#define SDL_HINT_JOYSTICK_RAWINPUT "SDL_JOYSTICK_RAWINPUT"
+
+/**
+ * \brief A variable controlling whether the RAWINPUT driver should pull correlated