geemili
/
SDL
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Sync SDL3 wiki -> header

main
SDL Wiki Bot 2024-04-10 19:59:14 +00:00
parent 557f26e6f0
commit b2239cb7ba
2 changed files with 35 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
include/SDL3/SDL_assert.h
View File

@ -120,12 +120,12 @@ disable assertions.
* Possible outcomes from a triggered assertion. * Possible outcomes from a triggered assertion.
* *
* When an enabled assertion triggers, it may call the assertion handler * When an enabled assertion triggers, it may call the assertion handler
* (possibly one provided by the app via SDL_SetAssertionHandler), which * (possibly one provided by the app via SDL_SetAssertionHandler), which will
* will return one of these values, possibly after asking the user. * return one of these values, possibly after asking the user.
* *
* Then SDL will respond based on this outcome (loop around to * Then SDL will respond based on this outcome (loop around to retry the
* retry the condition, try to break in a debugger, kill the program, or * condition, try to break in a debugger, kill the program, or ignore the
* ignore the problem). * problem).
* *
* \since This enum is available since SDL 3.0.0. * \since This enum is available since SDL 3.0.0.
*/ */
@ -218,21 +218,22 @@ extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *data
/* Enable various levels of assertions. */ /* Enable various levels of assertions. */
#ifdef SDL_WIKI_DOCUMENTATION_SECTION #ifdef SDL_WIKI_DOCUMENTATION_SECTION
/** /**
* An assertion test that is normally performed only in debug builds. * An assertion test that is normally performed only in debug builds.
* *
* This macro is enabled when the SDL_ASSERT_LEVEL is >= 2, otherwise it * This macro is enabled when the SDL_ASSERT_LEVEL is >= 2, otherwise it is
* is disabled. This is meant to only do these tests in debug builds, so * disabled. This is meant to only do these tests in debug builds, so they can
* they can tend to be more expensive, and they are meant to bring everything * tend to be more expensive, and they are meant to bring everything to a halt
* to a halt when they fail, with the programmer there to assess the problem. * when they fail, with the programmer there to assess the problem.
* *
* In short: you can sprinkle these around liberally and assume they will * In short: you can sprinkle these around liberally and assume they will
* evaporate out of the build when building for end-users. * evaporate out of the build when building for end-users.
* *
* When assertions are disabled, this wraps `condition` in a `sizeof` * When assertions are disabled, this wraps `condition` in a `sizeof`
* operator, which means any function calls and side effects will not run, * operator, which means any function calls and side effects will not run, but
* but the compiler will not complain about any otherwise-unused variables * the compiler will not complain about any otherwise-unused variables that
* that are only referenced in the assertion. * are only referenced in the assertion.
* *
* One can set the environment variable "SDL_ASSERT" to one of several strings * One can set the environment variable "SDL_ASSERT" to one of several strings
* ("abort", "break", "retry", "ignore", "always_ignore") to force a default * ("abort", "break", "retry", "ignore", "always_ignore") to force a default
@ -254,18 +255,18 @@ extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *data
/** /**
* An assertion test that is performed even in release builds. * An assertion test that is performed even in release builds.
* *
* This macro is enabled when the SDL_ASSERT_LEVEL is >= 1, otherwise it * This macro is enabled when the SDL_ASSERT_LEVEL is >= 1, otherwise it is
* is disabled. This is meant to be for tests that are cheap to make and * disabled. This is meant to be for tests that are cheap to make and
* extremely unlikely to fail; generally it is frowned upon to have an * extremely unlikely to fail; generally it is frowned upon to have an
* assertion failure in a release build, so these assertions generally need * assertion failure in a release build, so these assertions generally need to
* to be of more than life-and-death importance if there's a chance they * be of more than life-and-death importance if there's a chance they might
* might trigger. You should almost always consider handling these cases more * trigger. You should almost always consider handling these cases more
* gracefully than an assert allows. * gracefully than an assert allows.
* *
* When assertions are disabled, this wraps `condition` in a `sizeof` * When assertions are disabled, this wraps `condition` in a `sizeof`
* operator, which means any function calls and side effects will not run, * operator, which means any function calls and side effects will not run, but
* but the compiler will not complain about any otherwise-unused variables * the compiler will not complain about any otherwise-unused variables that
* that are only referenced in the assertion. * are only referenced in the assertion.
* *
* One can set the environment variable "SDL_ASSERT" to one of several strings * One can set the environment variable "SDL_ASSERT" to one of several strings
* ("abort", "break", "retry", "ignore", "always_ignore") to force a default * ("abort", "break", "retry", "ignore", "always_ignore") to force a default
@ -287,15 +288,15 @@ extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *data
/** /**
* An assertion test that is performed only when built with paranoid settings. * An assertion test that is performed only when built with paranoid settings.
* *
* This macro is enabled when the SDL_ASSERT_LEVEL is >= 3, otherwise it * This macro is enabled when the SDL_ASSERT_LEVEL is >= 3, otherwise it is
* is disabled. This is a higher level than both release and debug, so these * disabled. This is a higher level than both release and debug, so these
* tests are meant to be expensive and only run when specifically looking * tests are meant to be expensive and only run when specifically looking for
* for extremely unexpected failure cases in a special build. * extremely unexpected failure cases in a special build.
* *
* When assertions are disabled, this wraps `condition` in a `sizeof` * When assertions are disabled, this wraps `condition` in a `sizeof`
* operator, which means any function calls and side effects will not run, * operator, which means any function calls and side effects will not run, but
* but the compiler will not complain about any otherwise-unused variables * the compiler will not complain about any otherwise-unused variables that
* that are only referenced in the assertion. * are only referenced in the assertion.
* *
* One can set the environment variable "SDL_ASSERT" to one of several strings * One can set the environment variable "SDL_ASSERT" to one of several strings
* ("abort", "break", "retry", "ignore", "always_ignore") to force a default * ("abort", "break", "retry", "ignore", "always_ignore") to force a default
@ -338,9 +339,9 @@ extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *data
/** /**
* An assertion test that always performed. * An assertion test that always performed.
* *
* This macro is always enabled no matter what SDL_ASSERT_LEVEL is set to. * This macro is always enabled no matter what SDL_ASSERT_LEVEL is set to. You
* You almost never want to use this, as it could trigger on an end-user's * almost never want to use this, as it could trigger on an end-user's system,
* system, crashing your program. * crashing your program.
* *
* One can set the environment variable "SDL_ASSERT" to one of several strings * One can set the environment variable "SDL_ASSERT" to one of several strings
* ("abort", "break", "retry", "ignore", "always_ignore") to force a default * ("abort", "break", "retry", "ignore", "always_ignore") to force a default

8
include/SDL3/SDL_atomic.h
View File

@ -339,11 +339,11 @@ extern DECLSPEC int SDLCALL SDL_AtomicGet(SDL_AtomicInt *a);
extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v);
#ifndef SDL_AtomicIncRef #ifndef SDL_AtomicIncRef
/** /**
* Increment an atomic variable used as a reference count. * Increment an atomic variable used as a reference count.
* *
* ***Note: If you don't know what this macro is for, you shouldn't use * ***Note: If you don't know what this macro is for, you shouldn't use it!***
* it!***
* *
* \param a a pointer to an SDL_AtomicInt to increment. * \param a a pointer to an SDL_AtomicInt to increment.
* \returns the previous value of the atomic variable. * \returns the previous value of the atomic variable.
@ -356,11 +356,11 @@ extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v);
#endif #endif
#ifndef SDL_AtomicDecRef #ifndef SDL_AtomicDecRef
/** /**
* Decrement an atomic variable used as a reference count. * Decrement an atomic variable used as a reference count.
* *
* ***Note: If you don't know what this macro is for, you shouldn't use * ***Note: If you don't know what this macro is for, you shouldn't use it!***
* it!***
* *
* \param a a pointer to an SDL_AtomicInt to increment. * \param a a pointer to an SDL_AtomicInt to increment.
* \returns SDL_TRUE if the variable reached zero after decrementing, * \returns SDL_TRUE if the variable reached zero after decrementing,