SDL 3.0
SDL_assert.h File Reference
+ Include dependency graph for SDL_assert.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  SDL_AssertData
 

Macros

#define SDL_ASSERT_LEVEL   1
 
#define SDL_TriggerBreakpoint()
 
#define SDL_FUNCTION   "???"
 
#define SDL_FILE   __FILE__
 
#define SDL_LINE   __LINE__
 
#define SDL_NULL_WHILE_LOOP_CONDITION   (0)
 
#define SDL_disabled_assert(condition)    do { (void) sizeof ((condition)); } while (SDL_NULL_WHILE_LOOP_CONDITION)
 
#define SDL_AssertBreakpoint()   SDL_TriggerBreakpoint()
 
#define SDL_enabled_assert(condition)
 
#define SDL_assert(condition)   SDL_disabled_assert(condition)
 
#define SDL_assert_release(condition)   SDL_disabled_assert(condition)
 
#define SDL_assert_paranoid(condition)   SDL_disabled_assert(condition)
 
#define SDL_assert_always(condition)   SDL_enabled_assert(condition)
 

Typedefs

typedef SDL_AssertState(* SDL_AssertionHandler) (const SDL_AssertData *data, void *userdata)
 

Enumerations

enum  SDL_AssertState {
  SDL_ASSERTION_RETRY ,
  SDL_ASSERTION_BREAK ,
  SDL_ASSERTION_ABORT ,
  SDL_ASSERTION_IGNORE ,
  SDL_ASSERTION_ALWAYS_IGNORE
}
 

Functions

SDL_AssertState SDL_ReportAssertion (SDL_AssertData *data, const char *func, const char *file, int line)
 
void SDL_SetAssertionHandler (SDL_AssertionHandler handler, void *userdata)
 
SDL_AssertionHandler SDL_GetDefaultAssertionHandler (void)
 
SDL_AssertionHandler SDL_GetAssertionHandler (void **puserdata)
 
const SDL_AssertDataSDL_GetAssertionReport (void)
 
void SDL_ResetAssertionReport (void)
 

Detailed Description

Header file for assertion SDL API functions

Definition in file SDL_assert.h.

Macro Definition Documentation

◆ SDL_assert

#define SDL_assert (   condition)    SDL_disabled_assert(condition)

Definition at line 337 of file SDL_assert.h.

◆ SDL_assert_always

#define SDL_assert_always (   condition)    SDL_enabled_assert(condition)

An assertion test that always performed.

This macro is always enabled no matter what SDL_ASSERT_LEVEL is set to. You almost never want to use this, as it could trigger on an end-user's system, crashing your program.

One can set the environment variable "SDL_ASSERT" to one of several strings ("abort", "break", "retry", "ignore", "always_ignore") to force a default behavior, which may be desirable for automation purposes. If your platform requires GUI interfaces to happen on the main thread but you're debugging an assertion in a background thread, it might be desirable to set this to "break" so that your debugger takes control as soon as assert is triggered, instead of risking a bad UI interaction (deadlock, etc) in the application.

Note that SDL_ASSERT is an environment variable and not an SDL hint! Please refer to your platform's documentation for how to set it!

Parameters
conditionboolean value to test
Since
This macro is available since SDL 3.0.0.

Definition at line 378 of file SDL_assert.h.

◆ SDL_ASSERT_LEVEL

#define SDL_ASSERT_LEVEL   1

Definition at line 46 of file SDL_assert.h.

◆ SDL_assert_paranoid

#define SDL_assert_paranoid (   condition)    SDL_disabled_assert(condition)

Definition at line 339 of file SDL_assert.h.

◆ SDL_assert_release

#define SDL_assert_release (   condition)    SDL_disabled_assert(condition)

Definition at line 338 of file SDL_assert.h.

◆ SDL_AssertBreakpoint

#define SDL_AssertBreakpoint ( )    SDL_TriggerBreakpoint()

Definition at line 211 of file SDL_assert.h.

◆ SDL_disabled_assert

#define SDL_disabled_assert (   condition)     do { (void) sizeof ((condition)); } while (SDL_NULL_WHILE_LOOP_CONDITION)

Definition at line 133 of file SDL_assert.h.

134 { (void) sizeof ((condition)); } while (SDL_NULL_WHILE_LOOP_CONDITION)
#define SDL_NULL_WHILE_LOOP_CONDITION
Definition SDL_assert.h:130

◆ SDL_enabled_assert

#define SDL_enabled_assert (   condition)
Value:
do { \
while ( !(condition) ) { \
static struct SDL_AssertData sdl_assert_data = { 0, 0, #condition, 0, 0, 0, 0 }; \
const SDL_AssertState sdl_assert_state = SDL_ReportAssertion(&sdl_assert_data, SDL_FUNCTION, SDL_FILE, SDL_LINE); \
if (sdl_assert_state == SDL_ASSERTION_RETRY) { \
continue; /* go again. */ \
} else if (sdl_assert_state == SDL_ASSERTION_BREAK) { \
SDL_AssertBreakpoint(); \
} \
break; /* not retrying. */ \
} \
SDL_AssertState
Definition SDL_assert.h:150
@ SDL_ASSERTION_RETRY
Definition SDL_assert.h:151
@ SDL_ASSERTION_BREAK
Definition SDL_assert.h:152
SDL_AssertState SDL_ReportAssertion(SDL_AssertData *data, const char *func, const char *file, int line)
#define SDL_FILE
Definition SDL_assert.h:107
#define SDL_FUNCTION
Definition SDL_assert.h:105
#define SDL_LINE
Definition SDL_assert.h:108
const char * condition
Definition SDL_assert.h:171

Definition at line 222 of file SDL_assert.h.

223 { \
224 while ( !(condition) ) { \
225 static struct SDL_AssertData sdl_assert_data = { 0, 0, #condition, 0, 0, 0, 0 }; \
226 const SDL_AssertState sdl_assert_state = SDL_ReportAssertion(&sdl_assert_data, SDL_FUNCTION, SDL_FILE, SDL_LINE); \
227 if (sdl_assert_state == SDL_ASSERTION_RETRY) { \
228 continue; /* go again. */ \
229 } else if (sdl_assert_state == SDL_ASSERTION_BREAK) { \
230 SDL_AssertBreakpoint(); \
231 } \
232 break; /* not retrying. */ \
233 } \

◆ SDL_FILE

#define SDL_FILE   __FILE__

Definition at line 107 of file SDL_assert.h.

◆ SDL_FUNCTION

#define SDL_FUNCTION   "???"

Definition at line 105 of file SDL_assert.h.

◆ SDL_LINE

#define SDL_LINE   __LINE__

Definition at line 108 of file SDL_assert.h.

◆ SDL_NULL_WHILE_LOOP_CONDITION

#define SDL_NULL_WHILE_LOOP_CONDITION   (0)

Definition at line 130 of file SDL_assert.h.

◆ SDL_TriggerBreakpoint

#define SDL_TriggerBreakpoint ( )

Definition at line 97 of file SDL_assert.h.

Typedef Documentation

◆ SDL_AssertionHandler

typedef SDL_AssertState(* SDL_AssertionHandler) (const SDL_AssertData *data, void *userdata)

A callback that fires when an SDL assertion fails.

Parameters
dataa pointer to the SDL_AssertData structure corresponding to the current assertion
userdatawhat was passed as userdata to SDL_SetAssertionHandler()
Returns
an SDL_AssertState value indicating how to handle the failure.

Definition at line 389 of file SDL_assert.h.

Enumeration Type Documentation

◆ SDL_AssertState

Possible outcomes from a triggered assertion.

When an enabled assertion triggers, it may call the assertion handler (possibly one provided by the app via SDL_SetAssertionHandler), which will return one of these values, possibly after asking the user.

Then SDL will respond based on this outcome (loop around to retry the condition, try to break in a debugger, kill the program, or ignore the problem).

Since
This enum is available since SDL 3.0.0.
Enumerator
SDL_ASSERTION_RETRY 

Retry the assert immediately.

SDL_ASSERTION_BREAK 

Make the debugger trigger a breakpoint.

SDL_ASSERTION_ABORT 

Terminate the program.

SDL_ASSERTION_IGNORE 

Ignore the assert.

SDL_ASSERTION_ALWAYS_IGNORE 

Ignore the assert from now on.

Definition at line 149 of file SDL_assert.h.

150{
151 SDL_ASSERTION_RETRY, /**< Retry the assert immediately. */
152 SDL_ASSERTION_BREAK, /**< Make the debugger trigger a breakpoint. */
153 SDL_ASSERTION_ABORT, /**< Terminate the program. */
154 SDL_ASSERTION_IGNORE, /**< Ignore the assert. */
155 SDL_ASSERTION_ALWAYS_IGNORE /**< Ignore the assert from now on. */
@ SDL_ASSERTION_ABORT
Definition SDL_assert.h:153
@ SDL_ASSERTION_IGNORE
Definition SDL_assert.h:154
@ SDL_ASSERTION_ALWAYS_IGNORE
Definition SDL_assert.h:155

Function Documentation

◆ SDL_GetAssertionHandler()

SDL_AssertionHandler SDL_GetAssertionHandler ( void **  puserdata)
extern

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().

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.

Parameters
puserdatapointer 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 3.0.0.
See also
SDL_SetAssertionHandler

◆ SDL_GetAssertionReport()

const SDL_AssertData * SDL_GetAssertionReport ( void  )
extern

Get a list of all assertion failures.

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:

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;
}
const SDL_AssertData * SDL_GetAssertionReport(void)
const struct SDL_AssertData * next
Definition SDL_assert.h:175
unsigned int trigger_count
Definition SDL_assert.h:170
const char * function
Definition SDL_assert.h:174
SDL_bool always_ignore
Definition SDL_assert.h:169
const char * filename
Definition SDL_assert.h:172
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 3.0.0.
See also
SDL_ResetAssertionReport

◆ SDL_GetDefaultAssertionHandler()

SDL_AssertionHandler SDL_GetDefaultAssertionHandler ( void  )
extern

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.

Returns
the default SDL_AssertionHandler that is called when an assert triggers.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetAssertionHandler

◆ SDL_ReportAssertion()

SDL_AssertState SDL_ReportAssertion ( SDL_AssertData data,
const char *  func,
const char *  file,
int  line 
)
extern

Never call this directly.

Use the SDL_assert* macros instead.

Parameters
dataassert data structure
funcfunction name
filefile name
lineline number
Returns
assert state
Since
This function is available since SDL 3.0.0.

◆ SDL_ResetAssertionReport()

void SDL_ResetAssertionReport ( void  )
extern

Clear the list of all assertion failures.

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.

Since
This function is available since SDL 3.0.0.
See also
SDL_GetAssertionReport

◆ SDL_SetAssertionHandler()

void SDL_SetAssertionHandler ( SDL_AssertionHandler  handler,
void *  userdata 
)
extern

Set an application-defined assertion handler.

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 is NOT reset to SDL's internal handler upon SDL_Quit()!

Parameters
handlerthe SDL_AssertionHandler function to call when an assertion fails or NULL for the default handler
userdataa pointer that is passed to handler
Since
This function is available since SDL 3.0.0.
See also
SDL_GetAssertionHandler