gosu 1.3.0 → 1.4.0

data/dependencies/SDL/include/SDL_keyboard.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2020 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
@@ -55,154 +55,253 @@ typedef struct SDL_Keysym
 /* Function prototypes */
 
 /**
- *  \brief Get the window which currently has keyboard focus.
+ * Query the window which currently has keyboard focus.
+ *
+ * \returns the window with keyboard focus.
+ *
+ * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void);
 
 /**
- *  \brief Get a snapshot of the current state of the keyboard.
+ * Get a snapshot of the current state of the keyboard.
+ *
+ * The pointer returned is a pointer to an internal SDL array. It will be
+ * valid for the whole lifetime of the application and should not be freed by
+ * the caller.
+ *
+ * A array element with a value of 1 means that the key is pressed and a value
+ * of 0 means that it is not. Indexes into this array are obtained by using
+ * SDL_Scancode values.
+ *
+ * Use SDL_PumpEvents() to update the state array.
  *
- *  \param numkeys if non-NULL, receives the length of the returned array.
+ * This function gives you the current state after all events have been
+ * processed, so if a key or button has been pressed and released before you
+ * process events, then the pressed state will never show up in the
+ * SDL_GetKeyboardState() calls.
  *
- *  \return An array of key states. Indexes into this array are obtained by using ::SDL_Scancode values.
+ * Note: This function doesn't take into account whether shift has been
+ * pressed or not.
  *
- *  \b Example:
- *  \code
- *  const Uint8 *state = SDL_GetKeyboardState(NULL);
- *  if ( state[SDL_SCANCODE_RETURN] )   {
- *      printf("<RETURN> is pressed.\n");
- *  }
- *  \endcode
+ * \param numkeys if non-NULL, receives the length of the returned array
+ * \returns a pointer to an array of key states.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_PumpEvents
  */
 extern DECLSPEC const Uint8 *SDLCALL SDL_GetKeyboardState(int *numkeys);
 
 /**
- *  \brief Get the current key modifier state for the keyboard.
+ * Get the current key modifier state for the keyboard.
+ *
+ * \returns an OR'd combination of the modifier keys for the keyboard. See
+ *          SDL_Keymod for details.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetKeyboardState
+ * \sa SDL_SetModState
  */
 extern DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void);
 
 /**
- *  \brief Set the current key modifier state for the keyboard.
+ * Set the current key modifier state for the keyboard.
+ *
+ * The inverse of SDL_GetModState(), SDL_SetModState() allows you to impose
+ * modifier key states on your application. Simply pass your desired modifier
+ * states into `modstate`. This value may be a bitwise, OR'd combination of
+ * SDL_Keymod values.
+ *
+ * This does not change the keyboard state, only the key modifier flags that
+ * SDL reports.
+ *
+ * \param modstate the desired SDL_Keymod for the keyboard
  *
- *  \note This does not change the keyboard state, only the key modifier flags.
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetModState
  */
 extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
 
 /**
- *  \brief Get the key code corresponding to the given scancode according
- *         to the current keyboard layout.
+ * Get the key code corresponding to the given scancode according to the
+ * current keyboard layout.
+ *
+ * See SDL_Keycode for details.
  *
- *  See ::SDL_Keycode for details.
+ * \param scancode the desired SDL_Scancode to query
+ * \returns the SDL_Keycode that corresponds to the given SDL_Scancode.
  *
- *  \sa SDL_GetKeyName()
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetKeyName
+ * \sa SDL_GetScancodeFromKey
  */
 extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode);
 
 /**
- *  \brief Get the scancode corresponding to the given key code according to the
- *         current keyboard layout.
+ * Get the scancode corresponding to the given key code according to the
+ * current keyboard layout.
+ *
+ * See SDL_Scancode for details.
  *
- *  See ::SDL_Scancode for details.
+ * \param key the desired SDL_Keycode to query
+ * \returns the SDL_Scancode that corresponds to the given SDL_Keycode.
  *
- *  \sa SDL_GetScancodeName()
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetKeyFromScancode
+ * \sa SDL_GetScancodeName
  */
 extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key);
 
 /**
- *  \brief Get a human-readable name for a scancode.
+ * Get a human-readable name for a scancode.
+ *
+ * See SDL_Scancode for details.
+ *
+ * **Warning**: The returned name is by design not stable across platforms,
+ * e.g. the name for `SDL_SCANCODE_LGUI` is "Left GUI" under Linux but "Left
+ * Windows" under Microsoft Windows, and some scancodes like
+ * `SDL_SCANCODE_NONUSBACKSLASH` don't have any name at all. There are even
+ * scancodes that share names, e.g. `SDL_SCANCODE_RETURN` and
+ * `SDL_SCANCODE_RETURN2` (both called "Return"). This function is therefore
+ * unsuitable for creating a stable cross-platform two-way mapping between
+ * strings and scancodes.
+ *
+ * \param scancode the desired SDL_Scancode to query
+ * \returns a pointer to the name for the scancode. If the scancode doesn't
+ *          have a name this function returns an empty string ("").
  *
- *  \return A pointer to the name for the scancode.
- *          If the scancode doesn't have a name, this function returns
- *          an empty string ("").
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_Scancode
+ * \sa SDL_GetScancodeFromKey
+ * \sa SDL_GetScancodeFromName
  */
 extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_Scancode scancode);
 
 /**
- *  \brief Get a scancode from a human-readable name
+ * Get a scancode from a human-readable name.
  *
- *  \return scancode, or SDL_SCANCODE_UNKNOWN if the name wasn't recognized
+ * \param name the human-readable scancode name
+ * \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't
+ *          recognized; call SDL_GetError() for more information.
  *
- *  \sa SDL_Scancode
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetKeyFromName
+ * \sa SDL_GetScancodeFromKey
+ * \sa SDL_GetScancodeName
  */
 extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *name);
 
 /**
- *  \brief Get a human-readable name for a key.
+ * Get a human-readable name for a key.
+ *
+ * See SDL_Scancode and SDL_Keycode for details.
  *
- *  \return A pointer to a UTF-8 string that stays valid at least until the next
- *          call to this function. If you need it around any longer, you must
- *          copy it.  If the key doesn't have a name, this function returns an
- *          empty string ("").
+ * \param key the desired SDL_Keycode to query
+ * \returns a pointer to a UTF-8 string that stays valid at least until the
+ *          next call to this function. If you need it around any longer, you
+ *          must copy it. If the key doesn't have a name, this function
+ *          returns an empty string ("").
  *
- *  \sa SDL_Keycode
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetKeyFromName
+ * \sa SDL_GetKeyFromScancode
+ * \sa SDL_GetScancodeFromKey
  */
 extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDL_Keycode key);
 
 /**
- *  \brief Get a key code from a human-readable name
+ * Get a key code from a human-readable name.
+ *
+ * \param name the human-readable key name
+ * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call
+ *          SDL_GetError() for more information.
  *
- *  \return key code, or SDLK_UNKNOWN if the name wasn't recognized
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_Keycode
+ * \sa SDL_GetKeyFromScancode
+ * \sa SDL_GetKeyName
+ * \sa SDL_GetScancodeFromName
  */
 extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name);
 
 /**
- *  \brief Start accepting Unicode text input events.
- *         This function will show the on-screen keyboard if supported.
+ * Start accepting Unicode text input events.
  *
- *  \sa SDL_StopTextInput()
- *  \sa SDL_SetTextInputRect()
- *  \sa SDL_HasScreenKeyboardSupport()
+ * This function will start accepting Unicode text input events in the focused
+ * SDL window, and start emitting SDL_TextInputEvent (SDL_TEXTINPUT) and
+ * SDL_TextEditingEvent (SDL_TEXTEDITING) events. Please use this function in
+ * pair with SDL_StopTextInput().
+ *
+ * On some platforms using this function activates the screen keyboard.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_SetTextInputRect
+ * \sa SDL_StopTextInput
  */
 extern DECLSPEC void SDLCALL SDL_StartTextInput(void);
 
 /**
- *  \brief Return whether or not Unicode text input events are enabled.
+ * Check whether or not Unicode text input events are enabled.
+ *
+ * \returns SDL_TRUE if text input events are enabled else SDL_FALSE.
  *
- *  \sa SDL_StartTextInput()
- *  \sa SDL_StopTextInput()
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_StartTextInput
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputActive(void);
 
 /**
- *  \brief Stop receiving any text input events.
- *         This function will hide the on-screen keyboard if supported.
+ * Stop receiving any text input events.
+ *
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_StartTextInput()
- *  \sa SDL_HasScreenKeyboardSupport()
+ * \sa SDL_StartTextInput
  */
 extern DECLSPEC void SDLCALL SDL_StopTextInput(void);
 
 /**
- *  \brief Set the rectangle used to type Unicode text inputs.
- *         This is used as a hint for IME and on-screen keyboard placement.
+ * Set the rectangle used to type Unicode text inputs.
+ *
+ * \param rect the SDL_Rect structure representing the rectangle to receive
+ *             text (ignored if NULL)
+ *
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_StartTextInput()
+ * \sa SDL_StartTextInput
  */
 extern DECLSPEC void SDLCALL SDL_SetTextInputRect(SDL_Rect *rect);
 
 /**
- *  \brief Returns whether the platform has some screen keyboard support.
+ * Check whether the platform has screen keyboard support.
  *
- *  \return SDL_TRUE if some keyboard support is available else SDL_FALSE.
+ * \returns SDL_TRUE if the platform has some screen keyboard support or
+ *          SDL_FALSE if not.
  *
- *  \note Not all screen keyboard functions are supported on all platforms.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_IsScreenKeyboardShown()
+ * \sa SDL_StartTextInput
+ * \sa SDL_IsScreenKeyboardShown
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void);
 
 /**
- *  \brief Returns whether the screen keyboard is shown for given window.
+ * Check whether the screen keyboard is shown for given window.
  *
- *  \param window The window for which screen keyboard should be queried.
+ * \param window the window for which screen keyboard should be queried
+ * \returns SDL_TRUE if screen keyboard is shown or SDL_FALSE if not.
  *
- *  \return SDL_TRUE if screen keyboard is shown else SDL_FALSE.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_HasScreenKeyboardSupport()
+ * \sa SDL_HasScreenKeyboardSupport
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenKeyboardShown(SDL_Window *window);
 

data/dependencies/SDL/include/SDL_keycode.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2020 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
@@ -52,7 +52,7 @@ typedef enum
     SDLK_UNKNOWN = 0,
 
     SDLK_RETURN = '\r',
-    SDLK_ESCAPE = '\033',
+    SDLK_ESCAPE = '\x1B',
     SDLK_BACKSPACE = '\b',
     SDLK_TAB = '\t',
     SDLK_SPACE = ' ',
@@ -147,7 +147,7 @@ typedef enum
     SDLK_INSERT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_INSERT),
     SDLK_HOME = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HOME),
     SDLK_PAGEUP = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEUP),
-    SDLK_DELETE = '\177',
+    SDLK_DELETE = '\x7F',
     SDLK_END = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_END),
     SDLK_PAGEDOWN = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEDOWN),
     SDLK_RIGHT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RIGHT),
@@ -338,12 +338,14 @@ typedef enum
     KMOD_NUM = 0x1000,
     KMOD_CAPS = 0x2000,
     KMOD_MODE = 0x4000,
-    KMOD_RESERVED = 0x8000,
+    KMOD_SCROLL = 0x8000,
 
     KMOD_CTRL = KMOD_LCTRL | KMOD_RCTRL,
     KMOD_SHIFT = KMOD_LSHIFT | KMOD_RSHIFT,
     KMOD_ALT = KMOD_LALT | KMOD_RALT,
-    KMOD_GUI = KMOD_LGUI | KMOD_RGUI
+    KMOD_GUI = KMOD_LGUI | KMOD_RGUI,
+
+    KMOD_RESERVED = KMOD_SCROLL /* This is for source-level compatibility with SDL 2.0.0. */
 } SDL_Keymod;
 
 #endif /* SDL_keycode_h_ */

data/dependencies/SDL/include/SDL_loadso.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2020 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
@@ -51,22 +51,56 @@ extern "C" {
 #endif
 
 /**
- *  This function dynamically loads a shared object and returns a pointer
- *  to the object handle (or NULL if there was an error).
- *  The 'sofile' parameter is a system dependent name of the object file.
+ * Dynamically load a shared object.
+ *
+ * \param sofile a system-dependent name of the object file
+ * \returns an opaque pointer to the object handle or NULL if there was an
+ *          error; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LoadFunction
+ * \sa SDL_UnloadObject
  */
 extern DECLSPEC void *SDLCALL SDL_LoadObject(const char *sofile);
 
 /**
- *  Given an object handle, this function looks up the address of the
- *  named function in the shared object and returns it.  This address
- *  is no longer valid after calling SDL_UnloadObject().
+ * Look up the address of the named function in a shared object.
+ *
+ * This function pointer is no longer valid after calling SDL_UnloadObject().
+ *
+ * This function can only look up C function names. Other languages may have
+ * name mangling and intrinsic language support that varies from compiler to
+ * compiler.
+ *
+ * Make sure you declare your function pointers with the same calling
+ * convention as the actual library function. Your code will crash
+ * mysteriously if you do not do this.
+ *
+ * If the requested function doesn't exist, NULL is returned.
+ *
+ * \param handle a valid shared object handle returned by SDL_LoadObject()
+ * \param name the name of the function to look up
+ * \returns a pointer to the function or NULL if there was an error; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LoadObject
+ * \sa SDL_UnloadObject
  */
 extern DECLSPEC void *SDLCALL SDL_LoadFunction(void *handle,
                                                const char *name);
 
 /**
- *  Unload a shared object from memory.
+ * Unload a shared object from memory.
+ *
+ * \param handle a valid shared object handle returned by SDL_LoadObject()
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LoadFunction
+ * \sa SDL_LoadObject
  */
 extern DECLSPEC void SDLCALL SDL_UnloadObject(void *handle);
 

data/dependencies/SDL/include/SDL_locale.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2020 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
@@ -47,44 +47,46 @@ typedef struct SDL_Locale
 } SDL_Locale;
 
 /**
- *  \brief Report the user's preferred locale.
+ * Report the user's preferred locale.
  *
- *  This returns an array of SDL_Locale structs, the final item zeroed out.
- *  When the caller is done with this array, it should call SDL_free() on
- *  the returned value; all the memory involved is allocated in a single
- *  block, so a single SDL_free() will suffice.
+ * This returns an array of SDL_Locale structs, the final item zeroed out.
+ * When the caller is done with this array, it should call SDL_free() on the
+ * returned value; all the memory involved is allocated in a single block, so
+ * a single SDL_free() will suffice.
  *
- *  Returned language strings are in the format xx, where 'xx' is an ISO-639
- *  language specifier (such as "en" for English, "de" for German, etc).
- *  Country strings are in the format YY, where "YY" is an ISO-3166 country
- *  code (such as "US" for the United States, "CA" for Canada, etc). Country
- *  might be NULL if there's no specific guidance on them (so you might get
- *  { "en", "US" } for American English, but { "en", NULL } means "English
- *  language, generically"). Language strings are never NULL, except to
- *  terminate the array.
+ * Returned language strings are in the format xx, where 'xx' is an ISO-639
+ * language specifier (such as "en" for English, "de" for German, etc).
+ * Country strings are in the format YY, where "YY" is an ISO-3166 country
+ * code (such as "US" for the United States, "CA" for Canada, etc). Country
+ * might be NULL if there's no specific guidance on them (so you might get {
+ * "en", "US" } for American English, but { "en", NULL } means "English
+ * language, generically"). Language strings are never NULL, except to
+ * terminate the array.
  *
- *  Please note that not all of these strings are 2 characters; some are
- *  three or more.
+ * Please note that not all of these strings are 2 characters; some are three
+ * or more.
  *
- *  The returned list of locales are in the order of the user's preference.
- *  For example, a German citizen that is fluent in US English and knows
- *  enough Japanese to navigate around Tokyo might have a list like:
- *  { "de", "en_US", "jp", NULL }. Someone from England might prefer British
- *  English (where "color" is spelled "colour", etc), but will settle for
- *  anything like it: { "en_GB", "en", NULL }.
+ * The returned list of locales are in the order of the user's preference. For
+ * example, a German citizen that is fluent in US English and knows enough
+ * Japanese to navigate around Tokyo might have a list like: { "de", "en_US",
+ * "jp", NULL }. Someone from England might prefer British English (where
+ * "color" is spelled "colour", etc), but will settle for anything like it: {
+ * "en_GB", "en", NULL }.
  *
- *  This function returns NULL on error, including when the platform does not
- *  supply this information at all.
+ * This function returns NULL on error, including when the platform does not
+ * supply this information at all.
  *
- *  This might be a "slow" call that has to query the operating system. It's
- *  best to ask for this once and save the results. However, this list can
- *  change, usually because the user has changed a system preference outside
- *  of your program; SDL will send an SDL_LOCALECHANGED event in this case,
- *  if possible, and you can call this function again to get an updated copy
- *  of preferred locales.
+ * This might be a "slow" call that has to query the operating system. It's
+ * best to ask for this once and save the results. However, this list can
+ * change, usually because the user has changed a system preference outside of
+ * your program; SDL will send an SDL_LOCALECHANGED event in this case, if
+ * possible, and you can call this function again to get an updated copy of
+ * preferred locales.
  *
- *   \return array of locales, terminated with a locale with a NULL language
- *           field. Will return NULL on error.
+ * \return array of locales, terminated with a locale with a NULL language
+ *         field. Will return NULL on error.
+ *
+ * \since This function is available since SDL 2.0.14.
  */
 extern DECLSPEC SDL_Locale * SDLCALL SDL_GetPreferredLocales(void);