gosu 1.3.0 → 1.4.0

data/dependencies/SDL/include/SDL_mutex.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
@@ -59,38 +59,105 @@ struct SDL_mutex;
 typedef struct SDL_mutex SDL_mutex;
 
 /**
- *  Create a mutex, initialized unlocked.
+ * Create a new mutex.
+ *
+ * All newly-created mutexes begin in the _unlocked_ state.
+ *
+ * Calls to SDL_LockMutex() will not return while the mutex is locked by
+ * another thread. See SDL_TryLockMutex() to attempt to lock without blocking.
+ *
+ * SDL mutexes are reentrant.
+ *
+ * \returns the initialized and unlocked mutex or NULL on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_DestroyMutex
+ * \sa SDL_LockMutex
+ * \sa SDL_TryLockMutex
+ * \sa SDL_UnlockMutex
  */
 extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void);
 
 /**
- *  Lock the mutex.
+ * Lock the mutex.
+ *
+ * This will block until the mutex is available, which is to say it is in the
+ * unlocked state and the OS has chosen the caller as the next thread to lock
+ * it. Of all threads waiting to lock the mutex, only one may do so at a time.
+ *
+ * It is legal for the owning thread to lock an already-locked mutex. It must
+ * unlock it the same number of times before it is actually made available for
+ * other threads in the system (this is known as a "recursive mutex").
  *
- *  \return 0, or -1 on error.
+ * \param mutex the mutex to lock
+ * \return 0, or -1 on error.
+ *
+ * \since This function is available since SDL 2.0.0.
  */
-#define SDL_mutexP(m)   SDL_LockMutex(m)
 extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_mutex * mutex);
+#define SDL_mutexP(m)   SDL_LockMutex(m)
 
 /**
- *  Try to lock the mutex
+ * Try to lock a mutex without blocking.
+ *
+ * This works just like SDL_LockMutex(), but if the mutex is not available,
+ * this function returns `SDL_MUTEX_TIMEOUT` immediately.
  *
- *  \return 0, SDL_MUTEX_TIMEDOUT, or -1 on error
+ * This technique is useful if you need exclusive access to a resource but
+ * don't want to wait for it, and will return to it to try again later.
+ *
+ * \param mutex the mutex to try to lock
+ * \returns 0, `SDL_MUTEX_TIMEDOUT`, or -1 on error; call SDL_GetError() for
+ *          more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_CreateMutex
+ * \sa SDL_DestroyMutex
+ * \sa SDL_LockMutex
+ * \sa SDL_UnlockMutex
  */
 extern DECLSPEC int SDLCALL SDL_TryLockMutex(SDL_mutex * mutex);
 
 /**
- *  Unlock the mutex.
+ * Unlock the mutex.
+ *
+ * It is legal for the owning thread to lock an already-locked mutex. It must
+ * unlock it the same number of times before it is actually made available for
+ * other threads in the system (this is known as a "recursive mutex").
  *
- *  \return 0, or -1 on error.
+ * It is an error to unlock a mutex that has not been locked by the current
+ * thread, and doing so results in undefined behavior.
  *
- *  \warning It is an error to unlock a mutex that has not been locked by
- *           the current thread, and doing so results in undefined behavior.
+ * It is also an error to unlock a mutex that isn't locked at all.
+ *
+ * \param mutex the mutex to unlock.
+ * \returns 0, or -1 on error.
+ *
+ * \since This function is available since SDL 2.0.0.
  */
-#define SDL_mutexV(m)   SDL_UnlockMutex(m)
 extern DECLSPEC int SDLCALL SDL_UnlockMutex(SDL_mutex * mutex);
+#define SDL_mutexV(m)   SDL_UnlockMutex(m)
 
 /**
- *  Destroy a mutex.
+ * Destroy a mutex created with SDL_CreateMutex().
+ *
+ * This function must be called on any mutex that is no longer needed. Failure
+ * to destroy a mutex will result in a system memory or resource leak. While
+ * it is safe to destroy a mutex that is _unlocked_, it is not safe to attempt
+ * to destroy a locked mutex, and may result in undefined behavior depending
+ * on the platform.
+ *
+ * \param mutex the mutex to destroy
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_CreateMutex
+ * \sa SDL_LockMutex
+ * \sa SDL_TryLockMutex
+ * \sa SDL_UnlockMutex
  */
 extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex * mutex);
 
@@ -107,50 +174,151 @@ struct SDL_semaphore;
 typedef struct SDL_semaphore SDL_sem;
 
 /**
- *  Create a semaphore, initialized with value, returns NULL on failure.
+ * Create a semaphore.
+ *
+ * This function creates a new semaphore and initializes it with the value
+ * `initial_value`. Each wait operation on the semaphore will atomically
+ * decrement the semaphore value and potentially block if the semaphore value
+ * is 0. Each post operation will atomically increment the semaphore value and
+ * wake waiting threads and allow them to retry the wait operation.
+ *
+ * \param initial_value the starting value of the semaphore
+ * \returns a new semaphore or NULL on failure; call SDL_GetError() for more
+ *          information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_DestroySemaphore
+ * \sa SDL_SemPost
+ * \sa SDL_SemTryWait
+ * \sa SDL_SemValue
+ * \sa SDL_SemWait
+ * \sa SDL_SemWaitTimeout
  */
 extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
 
 /**
- *  Destroy a semaphore.
+ * Destroy a semaphore.
+ *
+ * It is not safe to destroy a semaphore if there are threads currently
+ * waiting on it.
+ *
+ * \param sem the semaphore to destroy
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_CreateSemaphore
+ * \sa SDL_SemPost
+ * \sa SDL_SemTryWait
+ * \sa SDL_SemValue
+ * \sa SDL_SemWait
+ * \sa SDL_SemWaitTimeout
  */
 extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem);
 
 /**
- *  This function suspends the calling thread until the semaphore pointed
- *  to by \c sem has a positive count. It then atomically decreases the
- *  semaphore count.
+ * Wait until a semaphore has a positive value and then decrements it.
+ *
+ * This function suspends the calling thread until either the semaphore
+ * pointed to by `sem` has a positive value or the call is interrupted by a
+ * signal or error. If the call is successful it will atomically decrement the
+ * semaphore value.
+ *
+ * This function is the equivalent of calling SDL_SemWaitTimeout() with a time
+ * length of `SDL_MUTEX_MAXWAIT`.
+ *
+ * \param sem the semaphore wait on
+ * \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_CreateSemaphore
+ * \sa SDL_DestroySemaphore
+ * \sa SDL_SemPost
+ * \sa SDL_SemTryWait
+ * \sa SDL_SemValue
+ * \sa SDL_SemWait
+ * \sa SDL_SemWaitTimeout
  */
 extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem);
 
 /**
- *  Non-blocking variant of SDL_SemWait().
+ * See if a semaphore has a positive value and decrement it if it does.
+ *
+ * This function checks to see if the semaphore pointed to by `sem` has a
+ * positive value and atomically decrements the semaphore value if it does. If
+ * the semaphore doesn't have a positive value, the function immediately
+ * returns SDL_MUTEX_TIMEDOUT.
+ *
+ * \param sem the semaphore to wait on
+ * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait would
+ *          block, or a negative error code on failure; call SDL_GetError()
+ *          for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
  *
- *  \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait would
- *          block, and -1 on error.
+ * \sa SDL_CreateSemaphore
+ * \sa SDL_DestroySemaphore
+ * \sa SDL_SemPost
+ * \sa SDL_SemValue
+ * \sa SDL_SemWait
+ * \sa SDL_SemWaitTimeout
  */
 extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem);
 
 /**
- *  Variant of SDL_SemWait() with a timeout in milliseconds.
+ * Wait until a semaphore has a positive value and then decrements it.
  *
- *  \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait does not
- *          succeed in the allotted time, and -1 on error.
+ * This function suspends the calling thread until either the semaphore
+ * pointed to by `sem` has a positive value, the call is interrupted by a
+ * signal or error, or the specified time has elapsed. If the call is
+ * successful it will atomically decrement the semaphore value.
  *
- *  \warning On some platforms this function is implemented by looping with a
- *           delay of 1 ms, and so should be avoided if possible.
+ * \param sem the semaphore to wait on
+ * \param ms the length of the timeout, in milliseconds
+ * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait does not
+ *          succeed in the allotted time, 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_CreateSemaphore
+ * \sa SDL_DestroySemaphore
+ * \sa SDL_SemPost
+ * \sa SDL_SemTryWait
+ * \sa SDL_SemValue
+ * \sa SDL_SemWait
  */
 extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem * sem, Uint32 ms);
 
 /**
- *  Atomically increases the semaphore's count (not blocking).
+ * Atomically increment a semaphore's value and wake waiting threads.
+ *
+ * \param sem the semaphore to increment
+ * \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.
  *
- *  \return 0, or -1 on error.
+ * \sa SDL_CreateSemaphore
+ * \sa SDL_DestroySemaphore
+ * \sa SDL_SemTryWait
+ * \sa SDL_SemValue
+ * \sa SDL_SemWait
+ * \sa SDL_SemWaitTimeout
  */
 extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem);
 
 /**
- *  Returns the current count of the semaphore.
+ * Get the current value of a semaphore.
+ *
+ * \param sem the semaphore to query
+ * \returns the current value of the semaphore.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_CreateSemaphore
  */
 extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem * sem);
 
@@ -167,72 +335,124 @@ struct SDL_cond;
 typedef struct SDL_cond SDL_cond;
 
 /**
- *  Create a condition variable.
- *
- *  Typical use of condition variables:
+ * Create a condition variable.
  *
- *  Thread A:
- *    SDL_LockMutex(lock);
- *    while ( ! condition ) {
- *        SDL_CondWait(cond, lock);
- *    }
- *    SDL_UnlockMutex(lock);
+ * \returns a new condition variable or NULL on failure; call SDL_GetError()
+ *          for more information.
  *
- *  Thread B:
- *    SDL_LockMutex(lock);
- *    ...
- *    condition = true;
- *    ...
- *    SDL_CondSignal(cond);
- *    SDL_UnlockMutex(lock);
+ * \since This function is available since SDL 2.0.0.
  *
- *  There is some discussion whether to signal the condition variable
- *  with the mutex locked or not.  There is some potential performance
- *  benefit to unlocking first on some platforms, but there are some
- *  potential race conditions depending on how your code is structured.
- *
- *  In general it's safer to signal the condition variable while the
- *  mutex is locked.
+ * \sa SDL_CondBroadcast
+ * \sa SDL_CondSignal
+ * \sa SDL_CondWait
+ * \sa SDL_CondWaitTimeout
+ * \sa SDL_DestroyCond
  */
 extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void);
 
 /**
- *  Destroy a condition variable.
+ * Destroy a condition variable.
+ *
+ * \param cond the condition variable to destroy
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_CondBroadcast
+ * \sa SDL_CondSignal
+ * \sa SDL_CondWait
+ * \sa SDL_CondWaitTimeout
+ * \sa SDL_CreateCond
  */
 extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond);
 
 /**
- *  Restart one of the threads that are waiting on the condition variable.
+ * Restart one of the threads that are waiting on the condition variable.
  *
- *  \return 0 or -1 on error.
+ * \param cond the condition variable to signal
+ * \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_CondBroadcast
+ * \sa SDL_CondWait
+ * \sa SDL_CondWaitTimeout
+ * \sa SDL_CreateCond
+ * \sa SDL_DestroyCond
  */
 extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond);
 
 /**
- *  Restart all threads that are waiting on the condition variable.
+ * Restart all threads that are waiting on the condition variable.
+ *
+ * \param cond the condition variable to signal
+ * \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.
  *
- *  \return 0 or -1 on error.
+ * \sa SDL_CondSignal
+ * \sa SDL_CondWait
+ * \sa SDL_CondWaitTimeout
+ * \sa SDL_CreateCond
+ * \sa SDL_DestroyCond
  */
 extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond);
 
 /**
- *  Wait on the condition variable, unlocking the provided mutex.
+ * Wait until a condition variable is signaled.
  *
- *  \warning The mutex must be locked before entering this function!
+ * This function unlocks the specified `mutex` and waits for another thread to
+ * call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable
+ * `cond`. Once the condition variable is signaled, the mutex is re-locked and
+ * the function returns.
  *
- *  The mutex is re-locked once the condition variable is signaled.
+ * The mutex must be locked before calling this function.
  *
- *  \return 0 when it is signaled, or -1 on error.
+ * This function is the equivalent of calling SDL_CondWaitTimeout() with a
+ * time length of `SDL_MUTEX_MAXWAIT`.
+ *
+ * \param cond the condition variable to wait on
+ * \param mutex the mutex used to coordinate thread access
+ * \returns 0 when it is signaled 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_CondBroadcast
+ * \sa SDL_CondSignal
+ * \sa SDL_CondWaitTimeout
+ * \sa SDL_CreateCond
+ * \sa SDL_DestroyCond
  */
 extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mutex);
 
 /**
- *  Waits for at most \c ms milliseconds, and returns 0 if the condition
- *  variable is signaled, ::SDL_MUTEX_TIMEDOUT if the condition is not
- *  signaled in the allotted time, and -1 on error.
+ * Wait until a condition variable is signaled or a certain time has passed.
+ *
+ * This function unlocks the specified `mutex` and waits for another thread to
+ * call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable
+ * `cond`, or for the specified time to elapse. Once the condition variable is
+ * signaled or the time elapsed, the mutex is re-locked and the function
+ * returns.
+ *
+ * The mutex must be locked before calling this function.
+ *
+ * \param cond the condition variable to wait on
+ * \param mutex the mutex used to coordinate thread access
+ * \param ms the maximum time to wait, in milliseconds, or `SDL_MUTEX_MAXWAIT`
+ *           to wait indefinitely
+ * \returns 0 if the condition variable is signaled, `SDL_MUTEX_TIMEDOUT` if
+ *          the condition is not signaled in the allotted time, or a negative
+ *          error code on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
  *
- *  \warning On some platforms this function is implemented by looping with a
- *           delay of 1 ms, and so should be avoided if possible.
+ * \sa SDL_CondBroadcast
+ * \sa SDL_CondSignal
+ * \sa SDL_CondWait
+ * \sa SDL_CreateCond
+ * \sa SDL_DestroyCond
  */
 extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond * cond,
                                                 SDL_mutex * mutex, Uint32 ms);

data/dependencies/SDL/include/SDL_name.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

data/dependencies/SDL/include/SDL_opengl.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

data/dependencies/SDL/include/SDL_opengles.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

data/dependencies/SDL/include/SDL_opengles2.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
@@ -26,7 +26,7 @@
  */
 #include "SDL_config.h"
 
-#ifndef _MSC_VER
+#if !defined(_MSC_VER) && !defined(SDL_USE_BUILTIN_OPENGL_DEFINITIONS)
 
 #ifdef __IPHONEOS__
 #include <OpenGLES/ES2/gl.h>