proc getPlatform(): cstring {...}{.importc: "SDL_GetPlatform", cdecl.}-
Apparently this is needed by several Windows compilers
Set up for C function definitions, even when using C++
\brief Gets the name of the platform.
proc malloc(size: uint): pointer {...}{.importc: "SDL_malloc", cdecl.}-
proc calloc(nmemb: uint; size: uint): pointer {...}{.importc: "SDL_calloc", cdecl.}-
proc realloc(mem: pointer; size: uint): pointer {...}{.importc: "SDL_realloc", cdecl.}-
proc free(mem: pointer) {...}{.importc: "SDL_free", cdecl.}-
proc getMemoryFunctions(mallocFunc: ptr malloc_func; callocFunc: ptr calloc_func;
reallocFunc: ptr realloc_func; freeFunc: ptr free_func) {...}{.
importc: "SDL_GetMemoryFunctions", cdecl.}-
\brief Get the current set of SDL memory functions
proc setMemoryFunctions(mallocFunc: malloc_func; callocFunc: calloc_func;
reallocFunc: realloc_func; freeFunc: free_func): cint {...}{.
importc: "SDL_SetMemoryFunctions", cdecl.}-
\brief Replace SDL's memory allocation functions with a custom set
\note If you are replacing SDL's memory functions, you should call
SDL_GetNumAllocations() and be very careful if it returns non-zero.
That means that your free function will be called with memory
allocated by the previous memory allocation functions.
proc getNumAllocations(): cint {...}{.importc: "SDL_GetNumAllocations", cdecl.}-
\brief Get the number of outstanding (unfreed) allocations
proc getenv(name: cstring): cstring {...}{.importc: "SDL_getenv", cdecl.}-
proc setenv(name: cstring; value: cstring; overwrite: cint): cint {...}{.
importc: "SDL_setenv", cdecl.}-
proc qsort(base: pointer; nmemb: uint; size: uint;
compare: proc (a1: pointer; a2: pointer): cint {...}{.cdecl.}) {...}{.
importc: "SDL_qsort", cdecl.}-
proc abs(x: cint): cint {...}{.importc: "SDL_abs", cdecl.}-
proc isdigit(x: cint): cint {...}{.importc: "SDL_isdigit", cdecl.}-
proc isspace(x: cint): cint {...}{.importc: "SDL_isspace", cdecl.}-
proc isupper(x: cint): cint {...}{.importc: "SDL_isupper", cdecl.}-
proc islower(x: cint): cint {...}{.importc: "SDL_islower", cdecl.}-
proc toupper(x: cint): cint {...}{.importc: "SDL_toupper", cdecl.}-
proc tolower(x: cint): cint {...}{.importc: "SDL_tolower", cdecl.}-
proc memset(dst: pointer; c: cint; len: uint): pointer {...}{.importc: "SDL_memset", cdecl.}-
proc memcpy(dst: pointer; src: pointer; len: uint): pointer {...}{.importc: "SDL_memcpy", cdecl.}-
proc memmove(dst: pointer; src: pointer; len: uint): pointer {...}{.importc: "SDL_memmove",
cdecl.}-
proc memcmp(s1: pointer; s2: pointer; len: uint): cint {...}{.importc: "SDL_memcmp", cdecl.}-
proc wcslen(wstr: ptr wchar_t): uint {...}{.importc: "SDL_wcslen", cdecl.}-
proc wcslcpy(dst: ptr wchar_t; src: ptr wchar_t; maxlen: uint): uint {...}{.
importc: "SDL_wcslcpy", cdecl.}-
proc wcslcat(dst: ptr wchar_t; src: ptr wchar_t; maxlen: uint): uint {...}{.
importc: "SDL_wcslcat", cdecl.}-
proc wcsdup(wstr: ptr wchar_t): ptr wchar_t {...}{.importc: "SDL_wcsdup", cdecl.}-
proc wcsstr(haystack: ptr wchar_t; needle: ptr wchar_t): ptr wchar_t {...}{.
importc: "SDL_wcsstr", cdecl.}-
proc wcscmp(str1: ptr wchar_t; str2: ptr wchar_t): cint {...}{.importc: "SDL_wcscmp", cdecl.}-
proc wcsncmp(str1: ptr wchar_t; str2: ptr wchar_t; maxlen: uint): cint {...}{.
importc: "SDL_wcsncmp", cdecl.}-
proc strlen(str: cstring): uint {...}{.importc: "SDL_strlen", cdecl.}-
proc strlcpy(dst: cstring; src: cstring; maxlen: uint): uint {...}{.importc: "SDL_strlcpy",
cdecl.}-
proc utf8strlcpy(dst: cstring; src: cstring; dstBytes: uint): uint {...}{.
importc: "SDL_utf8strlcpy", cdecl.}-
proc strlcat(dst: cstring; src: cstring; maxlen: uint): uint {...}{.importc: "SDL_strlcat",
cdecl.}-
proc strdup(str: cstring): cstring {...}{.importc: "SDL_strdup", cdecl.}-
proc strrev(str: cstring): cstring {...}{.importc: "SDL_strrev", cdecl.}-
proc strupr(str: cstring): cstring {...}{.importc: "SDL_strupr", cdecl.}-
proc strlwr(str: cstring): cstring {...}{.importc: "SDL_strlwr", cdecl.}-
proc strchr(str: cstring; c: cint): cstring {...}{.importc: "SDL_strchr", cdecl.}-
proc strrchr(str: cstring; c: cint): cstring {...}{.importc: "SDL_strrchr", cdecl.}-
proc strstr(haystack: cstring; needle: cstring): cstring {...}{.importc: "SDL_strstr", cdecl.}-
proc strtokr(s1: cstring; s2: cstring; saveptr: ptr cstring): cstring {...}{.
importc: "SDL_strtokr", cdecl.}-
proc utf8strlen(str: cstring): uint {...}{.importc: "SDL_utf8strlen", cdecl.}-
proc itoa(value: cint; str: cstring; radix: cint): cstring {...}{.importc: "SDL_itoa", cdecl.}-
proc uitoa(value: cuint; str: cstring; radix: cint): cstring {...}{.importc: "SDL_uitoa", cdecl.}-
proc ltoa(value: clong; str: cstring; radix: cint): cstring {...}{.importc: "SDL_ltoa", cdecl.}-
proc ultoa(value: culong; str: cstring; radix: cint): cstring {...}{.importc: "SDL_ultoa",
cdecl.}-
proc lltoa(value: Sint64; str: cstring; radix: cint): cstring {...}{.importc: "SDL_lltoa",
cdecl.}-
proc ulltoa(value: Uint64; str: cstring; radix: cint): cstring {...}{.importc: "SDL_ulltoa",
cdecl.}-
proc atoi(str: cstring): cint {...}{.importc: "SDL_atoi", cdecl.}-
proc atof(str: cstring): cdouble {...}{.importc: "SDL_atof", cdecl.}-
proc strtol(str: cstring; endp: ptr cstring; base: cint): clong {...}{.importc: "SDL_strtol",
cdecl.}-
proc strtoul(str: cstring; endp: ptr cstring; base: cint): culong {...}{.
importc: "SDL_strtoul", cdecl.}-
proc strtoll(str: cstring; endp: ptr cstring; base: cint): Sint64 {...}{.
importc: "SDL_strtoll", cdecl.}-
proc strtoull(str: cstring; endp: ptr cstring; base: cint): Uint64 {...}{.
importc: "SDL_strtoull", cdecl.}-
proc strtod(str: cstring; endp: ptr cstring): cdouble {...}{.importc: "SDL_strtod", cdecl.}-
proc strcmp(str1: cstring; str2: cstring): cint {...}{.importc: "SDL_strcmp", cdecl.}-
proc strncmp(str1: cstring; str2: cstring; maxlen: uint): cint {...}{.importc: "SDL_strncmp",
cdecl.}-
proc strcasecmp(str1: cstring; str2: cstring): cint {...}{.importc: "SDL_strcasecmp", cdecl.}-
proc strncasecmp(str1: cstring; str2: cstring; len: uint): cint {...}{.
importc: "SDL_strncasecmp", cdecl.}-
proc sscanf(text: cstring; fmt: cstring): cint {...}{.importc: "SDL_sscanf", cdecl, varargs.}-
proc vsscanf(text: cstring; fmt: cstring; ap: va_list): cint {...}{.importc: "SDL_vsscanf",
cdecl.}-
proc snprintf(text: cstring; maxlen: uint; fmt: cstring): cint {...}{.
importc: "SDL_snprintf", cdecl, varargs.}-
proc vsnprintf(text: cstring; maxlen: uint; fmt: cstring; ap: va_list): cint {...}{.
importc: "SDL_vsnprintf", cdecl.}-
proc acos(x: cdouble): cdouble {...}{.importc: "SDL_acos", cdecl.}-
proc acosf(x: cfloat): cfloat {...}{.importc: "SDL_acosf", cdecl.}-
proc asin(x: cdouble): cdouble {...}{.importc: "SDL_asin", cdecl.}-
proc asinf(x: cfloat): cfloat {...}{.importc: "SDL_asinf", cdecl.}-
proc atan(x: cdouble): cdouble {...}{.importc: "SDL_atan", cdecl.}-
proc atanf(x: cfloat): cfloat {...}{.importc: "SDL_atanf", cdecl.}-
proc atan2(x: cdouble; y: cdouble): cdouble {...}{.importc: "SDL_atan2", cdecl.}-
proc atan2f(x: cfloat; y: cfloat): cfloat {...}{.importc: "SDL_atan2f", cdecl.}-
proc ceil(x: cdouble): cdouble {...}{.importc: "SDL_ceil", cdecl.}-
proc ceilf(x: cfloat): cfloat {...}{.importc: "SDL_ceilf", cdecl.}-
proc copysign(x: cdouble; y: cdouble): cdouble {...}{.importc: "SDL_copysign", cdecl.}-
proc copysignf(x: cfloat; y: cfloat): cfloat {...}{.importc: "SDL_copysignf", cdecl.}-
proc cos(x: cdouble): cdouble {...}{.importc: "SDL_cos", cdecl.}-
proc cosf(x: cfloat): cfloat {...}{.importc: "SDL_cosf", cdecl.}-
proc exp(x: cdouble): cdouble {...}{.importc: "SDL_exp", cdecl.}-
proc expf(x: cfloat): cfloat {...}{.importc: "SDL_expf", cdecl.}-
proc fabs(x: cdouble): cdouble {...}{.importc: "SDL_fabs", cdecl.}-
proc fabsf(x: cfloat): cfloat {...}{.importc: "SDL_fabsf", cdecl.}-
proc floor(x: cdouble): cdouble {...}{.importc: "SDL_floor", cdecl.}-
proc floorf(x: cfloat): cfloat {...}{.importc: "SDL_floorf", cdecl.}-
proc fmod(x: cdouble; y: cdouble): cdouble {...}{.importc: "SDL_fmod", cdecl.}-
proc fmodf(x: cfloat; y: cfloat): cfloat {...}{.importc: "SDL_fmodf", cdecl.}-
proc log(x: cdouble): cdouble {...}{.importc: "SDL_log", cdecl.}-
proc logf(x: cfloat): cfloat {...}{.importc: "SDL_logf", cdecl.}-
proc log10(x: cdouble): cdouble {...}{.importc: "SDL_log10", cdecl.}-
proc log10f(x: cfloat): cfloat {...}{.importc: "SDL_log10f", cdecl.}-
proc pow(x: cdouble; y: cdouble): cdouble {...}{.importc: "SDL_pow", cdecl.}-
proc powf(x: cfloat; y: cfloat): cfloat {...}{.importc: "SDL_powf", cdecl.}-
proc scalbn(x: cdouble; n: cint): cdouble {...}{.importc: "SDL_scalbn", cdecl.}-
proc scalbnf(x: cfloat; n: cint): cfloat {...}{.importc: "SDL_scalbnf", cdecl.}-
proc sin(x: cdouble): cdouble {...}{.importc: "SDL_sin", cdecl.}-
proc sinf(x: cfloat): cfloat {...}{.importc: "SDL_sinf", cdecl.}-
proc sqrt(x: cdouble): cdouble {...}{.importc: "SDL_sqrt", cdecl.}-
proc sqrtf(x: cfloat): cfloat {...}{.importc: "SDL_sqrtf", cdecl.}-
proc tan(x: cdouble): cdouble {...}{.importc: "SDL_tan", cdecl.}-
proc tanf(x: cfloat): cfloat {...}{.importc: "SDL_tanf", cdecl.}-
proc iconv_open(tocode: cstring; fromcode: cstring): iconv_t {...}{.
importc: "SDL_iconv_open", cdecl.}-
proc iconv_close(cd: iconv_t): cint {...}{.importc: "SDL_iconv_close", cdecl.}-
proc iconv(cd: iconv_t; inbuf: ptr cstring; inbytesleft: ptr uint; outbuf: ptr cstring;
outbytesleft: ptr uint): uint {...}{.importc: "SDL_iconv", cdecl.}-
proc iconv_string(tocode: cstring; fromcode: cstring; inbuf: cstring; inbytesleft: uint): cstring {...}{.
importc: "SDL_iconv_string", cdecl.}-
This function converts a string between encodings in one pass, returning a
string that must be freed with SDL_free() or NULL on error.
proc main(argc: cint; argv: UncheckedArray[cstring]): cint {...}{.importc: "SDL_main", cdecl.}-
proc setMainReady() {...}{.importc: "SDL_SetMainReady", cdecl.}-
This is called by the real SDL main function to let the rest of the
library know that initialization was done properly.
Calling this yourself without knowing what you're doing can cause
crashes and hard to diagnose problems with your application.
proc reportAssertion(a1: ptr AssertData; a2: cstring; a3: cstring; a4: cint): AssertState {...}{.
importc: "SDL_ReportAssertion", cdecl.}-
Never call this directly. Use the SDL_assert macros.
proc setAssertionHandler(handler: AssertionHandler; userdata: pointer) {...}{.
importc: "SDL_SetAssertionHandler", cdecl.}-
\brief 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 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()!
Return SDL_AssertState value of how to handle the assertion failure.
\param handler Callback function, called when an assertion fails.
\param userdata A pointer passed to the callback as-is.
proc getDefaultAssertionHandler(): AssertionHandler {...}{.
importc: "SDL_GetDefaultAssertionHandler", cdecl.}-
\brief 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.
\return The default SDL_AssertionHandler that is called when an assert triggers.
proc getAssertionHandler(puserdata: ptr pointer): AssertionHandler {...}{.
importc: "SDL_GetAssertionHandler", cdecl.}-
\brief 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().
\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.
proc getAssertionReport(): ptr AssertData {...}{.importc: "SDL_GetAssertionReport", cdecl.}-
\brief Get a list of all assertion failures.
Get all assertions triggered since last call to SDL_ResetAssertionReport(),
or the start of the program.
The proper way to examine this data looks something like this:
<code>
const SDL_AssertDataitem = 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>
\return List of all assertions.
\sa SDL_ResetAssertionReport
proc resetAssertionReport() {...}{.importc: "SDL_ResetAssertionReport", cdecl.}-
\brief Reset the list of all assertion failures.
Reset list of all assertions triggered.
\sa SDL_GetAssertionReport
proc atomicTryLock(lock: ptr SpinLock): bool {...}{.importc: "SDL_AtomicTryLock", cdecl.}-
\brief Try to lock a spin lock by setting it to a non-zero value.
\param lock Points to the lock.
\return SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already held.
proc atomicLock(lock: ptr SpinLock) {...}{.importc: "SDL_AtomicLock", cdecl.}-
\brief Lock a spin lock by setting it to a non-zero value.
\param lock Points to the lock.
proc atomicUnlock(lock: ptr SpinLock) {...}{.importc: "SDL_AtomicUnlock", cdecl.}-
\brief Unlock a spin lock by setting it to 0. Always returns immediately
\param lock Points to the lock.
proc memoryBarrierReleaseFunction() {...}{.importc: "SDL_MemoryBarrierReleaseFunction",
cdecl.}-
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,
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.
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
proc memoryBarrierAcquireFunction() {...}{.importc: "SDL_MemoryBarrierAcquireFunction",
cdecl.}-
proc atomicCAS(a: ptr atomic_t; oldval: cint; newval: cint): bool {...}{.
importc: "SDL_AtomicCAS", cdecl.}-
\brief 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!
proc atomicSet(a: ptr atomic_t; v: cint): cint {...}{.importc: "SDL_AtomicSet", cdecl.}-
\brief Set an atomic variable to a value.
\return The previous value of the atomic variable.
proc atomicGet(a: ptr atomic_t): cint {...}{.importc: "SDL_AtomicGet", cdecl.}-
\brief Get the value of an atomic variable
proc atomicAdd(a: ptr atomic_t; v: cint): cint {...}{.importc: "SDL_AtomicAdd", cdecl.}-
\brief Add to an atomic variable.
\return The previous value of the atomic variable.
\note This same style can be used for any number operation
proc atomicCASPtr(a: ptr pointer; oldval: pointer; newval: pointer): bool {...}{.
importc: "SDL_AtomicCASPtr", cdecl.}-
\brief 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!
proc atomicSetPtr(a: ptr pointer; v: pointer): pointer {...}{.importc: "SDL_AtomicSetPtr",
cdecl.}-
\brief Set a pointer to a value atomically.
\return The previous value of the pointer.
proc atomicGetPtr(a: ptr pointer): pointer {...}{.importc: "SDL_AtomicGetPtr", cdecl.}-
\brief Get the value of a pointer atomically.
proc setError(fmt: cstring): cint {...}{.importc: "SDL_SetError", cdecl, varargs.}-
Some compilers use a special export keyword
By default SDL uses the C calling convention
Removed DECLSPEC on Symbian OS because SDL cannot be a DLL in EPOC
Force structure packing at 4 byte alignment.
This is necessary if the header is included in code which has structure
packing set to an alternate value, say for loading structures from disk.
The packing is reset to the previous value in close_code.h
Apparently this is needed by several Windows compilers
Set up for C function definitions, even when using C++
Public functions
SDL_SetError() unconditionally returns -1.
proc getError(): cstring {...}{.importc: "SDL_GetError", cdecl.}-
proc clearError() {...}{.importc: "SDL_ClearError", cdecl.}-
proc error(code: errorcode): cint {...}{.importc: "SDL_Error", cdecl.}-
SDL_Error() unconditionally returns -1.
proc createMutex(): ptr mutex {...}{.importc: "SDL_CreateMutex", cdecl.}-
Create a mutex, initialized unlocked.
proc lockMutex(mutex: ptr mutex): cint {...}{.importc: "SDL_LockMutex", cdecl.}-
proc tryLockMutex(mutex: ptr mutex): cint {...}{.importc: "SDL_TryLockMutex", cdecl.}-
Try to lock the mutex
\return 0, SDL_MUTEX_TIMEDOUT, or -1 on error
proc unlockMutex(mutex: ptr mutex): cint {...}{.importc: "SDL_UnlockMutex", cdecl.}-
proc destroyMutex(mutex: ptr mutex) {...}{.importc: "SDL_DestroyMutex", cdecl.}-
Destroy a mutex.
proc createSemaphore(initialValue: Uint32): ptr sem {...}{.importc: "SDL_CreateSemaphore",
cdecl.}-
Create a semaphore, initialized with value, returns NULL on failure.
proc destroySemaphore(sem: ptr sem) {...}{.importc: "SDL_DestroySemaphore", cdecl.}-
Destroy a semaphore.
proc semWait(sem: ptr sem): cint {...}{.importc: "SDL_SemWait", cdecl.}-
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.
proc semTryWait(sem: ptr sem): cint {...}{.importc: "SDL_SemTryWait", cdecl.}-
Non-blocking variant of SDL_SemWait().
\return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait would
block, and -1 on error.
proc semWaitTimeout(sem: ptr sem; ms: Uint32): cint {...}{.importc: "SDL_SemWaitTimeout",
cdecl.}-
Variant of SDL_SemWait() with a timeout in milliseconds.
\return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait does not
succeed in the allotted time, and -1 on error.
\warning On some platforms this function is implemented by looping with a
delay of 1 ms, and so should be avoided if possible.
proc semPost(sem: ptr sem): cint {...}{.importc: "SDL_SemPost", cdecl.}-
Atomically increases the semaphore's count (not blocking).
\return 0, or -1 on error.
proc semValue(sem: ptr sem): Uint32 {...}{.importc: "SDL_SemValue", cdecl.}-
Returns the current count of the semaphore.
proc createCond(): ptr cond {...}{.importc: "SDL_CreateCond", cdecl.}-
Create a condition variable.
Typical use of condition variables:
Thread A:
SDL_LockMutex(lock);
while ( ! condition ) {
SDL_CondWait(cond, lock);
}
SDL_UnlockMutex(lock);
Thread B:
SDL_LockMutex(lock);
...
condition = true;
...
SDL_CondSignal(cond);
SDL_UnlockMutex(lock);
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.
proc destroyCond(cond: ptr cond) {...}{.importc: "SDL_DestroyCond", cdecl.}-
Destroy a condition variable.
proc condSignal(cond: ptr cond): cint {...}{.importc: "SDL_CondSignal", cdecl.}-
Restart one of the threads that are waiting on the condition variable.
\return 0 or -1 on error.
proc condBroadcast(cond: ptr cond): cint {...}{.importc: "SDL_CondBroadcast", cdecl.}-
Restart all threads that are waiting on the condition variable.
\return 0 or -1 on error.
proc condWait(cond: ptr cond; mutex: ptr mutex): cint {...}{.importc: "SDL_CondWait", cdecl.}-
Wait on the condition variable, unlocking the provided mutex.
\warning The mutex must be locked before entering this function!
The mutex is re-locked once the condition variable is signaled.
\return 0 when it is signaled, or -1 on error.
proc condWaitTimeout(cond: ptr cond; mutex: ptr mutex; ms: Uint32): cint {...}{.
importc: "SDL_CondWaitTimeout", cdecl.}-
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.
\warning On some platforms this function is implemented by looping with a
delay of 1 ms, and so should be avoided if possible.
proc createThread(fn: ThreadFunction; name: cstring; data: pointer): ptr Thread {...}{.
importc: "SDL_CreateThread", cdecl.}-
Create a thread with a default stack size.
This is equivalent to calling:
SDL_CreateThreadWithStackSize(fn, name, 0, data);
proc createThreadWithStackSize(fn: ThreadFunction; name: cstring; stacksize: uint;
data: pointer): ptr Thread {...}{.
importc: "SDL_CreateThreadWithStackSize", cdecl.}-
Create a thread.
Thread naming is a little complicated: Most systems have very small
limits for the string length (Haiku has 32 bytes, Linux currently has 16,
Visual C++ 6.0 has nine!), and possibly other arbitrary rules. You'll
have to see what happens with your system's debugger. The name should be
UTF-8 (but using the naming limits of C identifiers is a better bet).
There are no requirements for thread naming conventions, so long as the
string is null-terminated UTF-8, but these guidelines are helpful in
choosing a name:
http:stackoverflow.com/questions/149932/naming-conventions-for-threads
If a system imposes requirements, SDL will try to munge the string for
it (truncate, etc), but the original string contents will be available
from SDL_GetThreadName().
The size (in bytes) of the new stack can be specified. Zero means "use
the system default" which might be wildly different between platforms
(x86 Linux generally defaults to eight megabytes, an embedded device
might be a few kilobytes instead).
In SDL 2.1, stacksize will be folded into the original SDL_CreateThread
function.
proc getThreadName(thread: ptr Thread): cstring {...}{.importc: "SDL_GetThreadName", cdecl.}-
Get the thread name, as it was specified in SDL_CreateThread().
This function returns a pointer to a UTF-8 string that names the
specified thread, or NULL if it doesn't have a name. This is internal
memory, not to be free()'d by the caller, and remains valid until the
specified thread is cleaned up by SDL_WaitThread().
proc getThreadID(thread: ptr Thread): threadID {...}{.importc: "SDL_GetThreadID", cdecl.}-
Get the thread identifier for the specified thread.
Equivalent to SDL_ThreadID() if the specified thread is NULL.
proc setThreadPriority(priority: ThreadPriority): cint {...}{.
importc: "SDL_SetThreadPriority", cdecl.}-
Set the priority for the current thread
proc waitThread(thread: ptr Thread; status: ptr cint) {...}{.importc: "SDL_WaitThread", cdecl.}-
Wait for a thread to finish. Threads that haven't been detached will
remain (as a "zombie") until this function cleans them up. Not doing so
is a resource leak.
Once a thread has been cleaned up through this function, the SDL_Thread
that references it becomes invalid and should not be referenced again.
As such, only one thread may call SDL_WaitThread() on another.
The return code for the thread function is placed in the area
pointed to by \c status, if \c status is not NULL.
You may not wait on a thread that has been used in a call to
SDL_DetachThread(). Use either that function or this one, but not
both, or behavior is undefined.
It is safe to pass NULL to this function; it is a no-op.
proc detachThread(thread: ptr Thread) {...}{.importc: "SDL_DetachThread", cdecl.}-
A thread may be "detached" to signify that it should not remain until
another thread has called SDL_WaitThread() on it. Detaching a thread
is useful for long-running threads that nothing needs to synchronize
with or further manage. When a detached thread is done, it simply
goes away.
There is no way to recover the return code of a detached thread. If you
need this, don't detach the thread and instead use SDL_WaitThread().
Once a thread is detached, you should usually assume the SDL_Thread isn't
safe to reference again, as it will become invalid immediately upon
the detached thread's exit, instead of remaining until someone has called
SDL_WaitThread() to finally clean it up. As such, don't detach the same
thread more than once.
If a thread has already exited when passed to SDL_DetachThread(), it will
stop waiting for a call to SDL_WaitThread() and clean up immediately.
It is not safe to detach a thread that might be used with SDL_WaitThread().
You may not call SDL_WaitThread() on a thread that has been detached.
Use either that function or this one, but not both, or behavior is
undefined.
It is safe to pass NULL to this function; it is a no-op.
proc tLSCreate(): TLSID {...}{.importc: "SDL_TLSCreate", cdecl.}-
\brief Create an identifier that is globally visible to all threads but refers to data that is thread-specific.
\return The newly created thread local storage identifier, or 0 on error
\code
static SDL_SpinLock tls_lock;
static SDL_TLSID thread_local_storage;
void SetMyThreadData(voidvalue)
{
if (!thread_local_storage) {
SDL_AtomicLock(&tls_lock);
if (!thread_local_storage) {
thread_local_storage = SDL_TLSCreate();
}
SDL_AtomicUnlock(&tls_lock);
}
SDL_TLSSet(thread_local_storage, value, 0);
}
voidGetMyThreadData(void)
{
return SDL_TLSGet(thread_local_storage);
}
\endcode
\sa SDL_TLSGet()
\sa SDL_TLSSet()
proc tLSGet(id: TLSID): pointer {...}{.importc: "SDL_TLSGet", cdecl.}-
\brief Get the value associated with a thread local storage ID for the current thread.
\param id The thread local storage ID
\return The value associated with the ID for the current thread, or NULL if no value has been set.
\sa SDL_TLSCreate()
\sa SDL_TLSSet()
proc tLSSet(id: TLSID; value: pointer; destructor: proc (a1: pointer) {...}{.cdecl.}): cint {...}{.
importc: "SDL_TLSSet", cdecl.}-
\brief Set the value associated with a thread local storage ID for the current thread.
\param id The thread local storage ID
\param value The value to associate with the ID for the current thread
\param destructor A function called when the thread exits, to free the value.
\return 0 on success, -1 on error
\sa SDL_TLSCreate()
\sa SDL_TLSGet()
proc rWFromFile(file: cstring; mode: cstring): ptr RWops {...}{.importc: "SDL_RWFromFile",
cdecl.}-
\name RWFrom functions
Functions to create SDL_RWops structures from various data streams.
@{
proc rWFromFP(fp: File; autoclose: bool): ptr RWops {...}{.importc: "SDL_RWFromFP", cdecl.}-
proc rWFromMem(mem: pointer; size: cint): ptr RWops {...}{.importc: "SDL_RWFromMem", cdecl.}-
proc rWFromConstMem(mem: pointer; size: cint): ptr RWops {...}{.
importc: "SDL_RWFromConstMem", cdecl.}-
proc allocRW(): ptr RWops {...}{.importc: "SDL_AllocRW", cdecl.}-
@}
RWFrom functions
proc freeRW(area: ptr RWops) {...}{.importc: "SDL_FreeRW", cdecl.}-
proc rWsize(context: ptr RWops): Sint64 {...}{.importc: "SDL_RWsize", cdecl.}-
Return the size of the file in this rwops, or -1 if unknown
proc rWseek(context: ptr RWops; offset: Sint64; whence: cint): Sint64 {...}{.
importc: "SDL_RWseek", cdecl.}-
Seek to \c offset relative to \c whence, one of stdio's whence values:
RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END
\return the final offset in the data stream, or -1 on error.
proc rWtell(context: ptr RWops): Sint64 {...}{.importc: "SDL_RWtell", cdecl.}-
Return the current offset in the data stream, or -1 on error.
proc rWread(context: ptr RWops; `ptr`: pointer; size: uint; maxnum: uint): uint {...}{.
importc: "SDL_RWread", cdecl.}-
Read up to \c maxnum objects each of size \c size from the data
stream to the area pointed at by \c ptr.
\return the number of objects read, or 0 at error or end of file.
proc rWwrite(context: ptr RWops; `ptr`: pointer; size: uint; num: uint): uint {...}{.
importc: "SDL_RWwrite", cdecl.}-
Write exactly \c num objects each of size \c size from the area
pointed at by \c ptr to data stream.
\return the number of objects written, or 0 at error or end of file.
proc rWclose(context: ptr RWops): cint {...}{.importc: "SDL_RWclose", cdecl.}-
Close and free an allocated SDL_RWops structure.
\return 0 if successful or -1 on write error when flushing data.
proc loadFile_RW(src: ptr RWops; datasize: ptr uint; freesrc: cint): pointer {...}{.
importc: "SDL_LoadFile_RW", cdecl.}-
Load all the data from an SDL data stream.
The data is allocated with a zero byte at the end (null terminated)
If \c datasize is not NULL, it is filled with the size of the data read.
If \c freesrc is non-zero, the stream will be closed after being read.
The data should be freed with SDL_free().
\return the data, or NULL if there was an error.
proc loadFile(file: cstring; datasize: ptr uint): pointer {...}{.importc: "SDL_LoadFile",
cdecl.}-
Load an entire file.
The data is allocated with a zero byte at the end (null terminated)
If \c datasize is not NULL, it is filled with the size of the data read.
If \c freesrc is non-zero, the stream will be closed after being read.
The data should be freed with SDL_free().
\return the data, or NULL if there was an error.
proc readU8(src: ptr RWops): Uint8 {...}{.importc: "SDL_ReadU8", cdecl.}-
\name Read endian functions
Read an item of the specified endianness and return in native format.
@{
proc readLE16(src: ptr RWops): Uint16 {...}{.importc: "SDL_ReadLE16", cdecl.}-
proc readBE16(src: ptr RWops): Uint16 {...}{.importc: "SDL_ReadBE16", cdecl.}-
proc readLE32(src: ptr RWops): Uint32 {...}{.importc: "SDL_ReadLE32", cdecl.}-
proc readBE32(src: ptr RWops): Uint32 {...}{.importc: "SDL_ReadBE32", cdecl.}-
proc readLE64(src: ptr RWops): Uint64 {...}{.importc: "SDL_ReadLE64", cdecl.}-
proc readBE64(src: ptr RWops): Uint64 {...}{.importc: "SDL_ReadBE64", cdecl.}-
proc writeU8(dst: ptr RWops; value: Uint8): uint {...}{.importc: "SDL_WriteU8", cdecl.}-
@}
Read endian functions
\name Write endian functions
Write an item of native format to the specified endianness.
@{
proc writeLE16(dst: ptr RWops; value: Uint16): uint {...}{.importc: "SDL_WriteLE16", cdecl.}-
proc writeBE16(dst: ptr RWops; value: Uint16): uint {...}{.importc: "SDL_WriteBE16", cdecl.}-
proc writeLE32(dst: ptr RWops; value: Uint32): uint {...}{.importc: "SDL_WriteLE32", cdecl.}-
proc writeBE32(dst: ptr RWops; value: Uint32): uint {...}{.importc: "SDL_WriteBE32", cdecl.}-
proc writeLE64(dst: ptr RWops; value: Uint64): uint {...}{.importc: "SDL_WriteLE64", cdecl.}-
proc writeBE64(dst: ptr RWops; value: Uint64): uint {...}{.importc: "SDL_WriteBE64", cdecl.}-
proc getNumAudioDrivers(): cint {...}{.importc: "SDL_GetNumAudioDrivers", cdecl.}-
Function prototypes
\name Driver discovery functions
These functions return the list of built in audio drivers, in the
order that they are normally initialized by default.
@{
proc getAudioDriver(index: cint): cstring {...}{.importc: "SDL_GetAudioDriver", cdecl.}-
proc audioInit(driverName: cstring): cint {...}{.importc: "SDL_AudioInit", cdecl.}-
@}
\name Initialization and cleanup
\internal These functions are 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_Init() or SDL_InitSubSystem().
@{
proc audioQuit() {...}{.importc: "SDL_AudioQuit", cdecl.}-
proc getCurrentAudioDriver(): cstring {...}{.importc: "SDL_GetCurrentAudioDriver", cdecl.}-
@}
This function returns the name of the current audio driver, or NULL
if no driver has been initialized.
proc openAudio(desired: ptr AudioSpec; obtained: ptr AudioSpec): cint {...}{.
importc: "SDL_OpenAudio", cdecl.}-
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.
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 = (samples1000)/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.
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.
proc getNumAudioDevices(iscapture: cint): cint {...}{.importc: "SDL_GetNumAudioDevices",
cdecl.}-
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().
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()).
proc getAudioDeviceName(index: cint; iscapture: cint): cstring {...}{.
importc: "SDL_GetAudioDeviceName", cdecl.}-
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.
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.
proc openAudioDevice(device: cstring; iscapture: cint; desired: ptr AudioSpec;
obtained: ptr AudioSpec; allowedChanges: cint): AudioDeviceID {...}{.
importc: "SDL_OpenAudioDevice", cdecl.}-
Open a specific audio device. Passing in a device name of NULL requests
the most reasonable default (and is equivalent to calling SDL_OpenAudio()).
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.
\return 0 on error, a valid device ID that is >= 2 on success.
SDL_OpenAudio(), unlike this function, always acts on device ID 1.
proc getAudioStatus(): AudioStatus {...}{.importc: "SDL_GetAudioStatus", cdecl.}-
proc getAudioDeviceStatus(dev: AudioDeviceID): AudioStatus {...}{.
importc: "SDL_GetAudioDeviceStatus", cdecl.}-
proc pauseAudio(pauseOn: cint) {...}{.importc: "SDL_PauseAudio", cdecl.}-
@}
Audio State
\name Pause audio functions
These functions pause and unpause the audio callback processing.
They should be called with a parameter of 0 after opening the audio
device to start playing sound. This is so you can safely initialize
data for your callback function after opening the audio device.
Silence will be written to the audio device during the pause.
@{
proc pauseAudioDevice(dev: AudioDeviceID; pauseOn: cint) {...}{.
importc: "SDL_PauseAudioDevice", cdecl.}-
proc loadWAV_RW(src: ptr RWops; freesrc: cint; spec: ptr AudioSpec;
audioBuf: ptr ptr Uint8; audioLen: ptr Uint32): ptr AudioSpec {...}{.
importc: "SDL_LoadWAV_RW", cdecl.}-
@}
Pause audio functions
\brief 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.
If \c 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.
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.
It's necessary to use SDL_FreeWAV() to free the audio data returned in
\c 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.
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.
It is required that the data source supports seeking.
Example:
\code
SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);
\endcode
\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.
proc freeWAV(audioBuf: ptr Uint8) {...}{.importc: "SDL_FreeWAV", cdecl.}-
This function frees data previously allocated with SDL_LoadWAV_RW()
proc buildAudioCVT(cvt: ptr AudioCVT; srcFormat: AudioFormat; srcChannels: Uint8;
srcRate: cint; dstFormat: AudioFormat; dstChannels: Uint8;
dstRate: cint): cint {...}{.importc: "SDL_BuildAudioCVT", cdecl.}-
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.
\return 0 if no conversion is needed, 1 if the audio filter is set up,
or -1 on error.
proc convertAudio(cvt: ptr AudioCVT): cint {...}{.importc: "SDL_ConvertAudio", cdecl.}-
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.
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->lencvt->len_mult bytes long.
\return 0 on success or -1 if \c cvt->buf is NULL.
proc newAudioStream(srcFormat: AudioFormat; srcChannels: Uint8; srcRate: cint;
dstFormat: AudioFormat; dstChannels: Uint8; dstRate: cint): ptr AudioStream {...}{.
importc: "SDL_NewAudioStream", cdecl.}-
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.
\sa SDL_AudioStreamPut
\sa SDL_AudioStreamGet
\sa SDL_AudioStreamAvailable
\sa SDL_AudioStreamFlush
\sa SDL_AudioStreamClear
\sa SDL_FreeAudioStream
proc audioStreamPut(stream: ptr AudioStream; buf: pointer; len: cint): cint {...}{.
importc: "SDL_AudioStreamPut", cdecl.}-
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.
\sa SDL_NewAudioStream
\sa SDL_AudioStreamGet
\sa SDL_AudioStreamAvailable
\sa SDL_AudioStreamFlush
\sa SDL_AudioStreamClear
\sa SDL_FreeAudioStream
proc audioStreamGet(stream: ptr AudioStream; buf: pointer; len: cint): cint {...}{.
importc: "SDL_AudioStreamGet", cdecl.}-
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
\sa SDL_NewAudioStream
\sa SDL_AudioStreamPut
\sa SDL_AudioStreamAvailable
\sa SDL_AudioStreamFlush
\sa SDL_AudioStreamClear
\sa SDL_FreeAudioStream
proc audioStreamAvailable(stream: ptr AudioStream): cint {...}{.
importc: "SDL_AudioStreamAvailable", cdecl.}-
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.
\sa SDL_NewAudioStream
\sa SDL_AudioStreamPut
\sa SDL_AudioStreamGet
\sa SDL_AudioStreamFlush
\sa SDL_AudioStreamClear
\sa SDL_FreeAudioStream
proc audioStreamFlush(stream: ptr AudioStream): cint {...}{.
importc: "SDL_AudioStreamFlush", cdecl.}-
Tell the stream that you're done sending data, and anything being buffered
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.
\sa SDL_NewAudioStream
\sa SDL_AudioStreamPut
\sa SDL_AudioStreamGet
\sa SDL_AudioStreamAvailable
\sa SDL_AudioStreamClear
\sa SDL_FreeAudioStream
proc audioStreamClear(stream: ptr AudioStream) {...}{.importc: "SDL_AudioStreamClear",
cdecl.}-
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
proc freeAudioStream(stream: ptr AudioStream) {...}{.importc: "SDL_FreeAudioStream", cdecl.}-
Free an audio stream
\sa SDL_NewAudioStream
\sa SDL_AudioStreamPut
\sa SDL_AudioStreamGet
\sa SDL_AudioStreamAvailable
\sa SDL_AudioStreamFlush
\sa SDL_AudioStreamClear
proc mixAudio(dst: ptr Uint8; src: ptr Uint8; len: Uint32; volume: cint) {...}{.
importc: "SDL_MixAudio", cdecl.}-
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.
proc mixAudioFormat(dst: ptr Uint8; src: ptr Uint8; format: AudioFormat; len: Uint32;
volume: cint) {...}{.importc: "SDL_MixAudioFormat", cdecl.}-
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.
proc queueAudio(dev: AudioDeviceID; data: pointer; len: Uint32): cint {...}{.
importc: "SDL_QueueAudio", cdecl.}-
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.)
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.
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 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.
\sa SDL_GetQueuedAudioSize
\sa SDL_ClearQueuedAudio
proc dequeueAudio(dev: AudioDeviceID; data: pointer; len: Uint32): Uint32 {...}{.
importc: "SDL_DequeueAudio", cdecl.}-
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.)
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.
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.
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.
\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.
\sa SDL_GetQueuedAudioSize
\sa SDL_ClearQueuedAudio
proc getQueuedAudioSize(dev: AudioDeviceID): Uint32 {...}{.
importc: "SDL_GetQueuedAudioSize", cdecl.}-
Get the number of bytes of still-queued audio.
For playback device:
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.
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.
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.
You should not call SDL_LockAudio() on the device before querying; SDL
handles locking internally for this function.
\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
proc clearQueuedAudio(dev: AudioDeviceID) {...}{.importc: "SDL_ClearQueuedAudio", cdecl.}-
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.
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!).
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.
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 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.
\param dev The device ID of which to clear the audio queue.
\sa SDL_QueueAudio
\sa SDL_GetQueuedAudioSize
proc lockAudio() {...}{.importc: "SDL_LockAudio", cdecl.}-
\name Audio lock functions
The lock manipulated by these functions protects the callback function.
During a SDL_LockAudio()/SDL_UnlockAudio() pair, you can be guaranteed that
the callback function is not running. Do not call these from the callback
function or you will cause deadlock.
@{
proc lockAudioDevice(dev: AudioDeviceID) {...}{.importc: "SDL_LockAudioDevice", cdecl.}-
proc unlockAudio() {...}{.importc: "SDL_UnlockAudio", cdecl.}-
proc unlockAudioDevice(dev: AudioDeviceID) {...}{.importc: "SDL_UnlockAudioDevice", cdecl.}-
proc closeAudio() {...}{.importc: "SDL_CloseAudio", cdecl.}-
@}
Audio lock functions
This function shuts down audio processing and closes the audio device.
proc closeAudioDevice(dev: AudioDeviceID) {...}{.importc: "SDL_CloseAudioDevice", cdecl.}-
proc setClipboardText(text: cstring): cint {...}{.importc: "SDL_SetClipboardText", cdecl.}-
Some compilers use a special export keyword
By default SDL uses the C calling convention
Removed DECLSPEC on Symbian OS because SDL cannot be a DLL in EPOC
Force structure packing at 4 byte alignment.
This is necessary if the header is included in code which has structure
packing set to an alternate value, say for loading structures from disk.
The packing is reset to the previous value in close_code.h
Apparently this is needed by several Windows compilers
Set up for C function definitions, even when using C++
Function prototypes
\brief Put UTF-8 text into the clipboard
\sa SDL_GetClipboardText()
proc getClipboardText(): cstring {...}{.importc: "SDL_GetClipboardText", cdecl.}-
\brief Get UTF-8 text from the clipboard, which must be freed with SDL_free()
\sa SDL_SetClipboardText()
proc hasClipboardText(): bool {...}{.importc: "SDL_HasClipboardText", cdecl.}-
\brief Returns a flag indicating whether the clipboard exists and contains a text string that is non-empty
\sa SDL_GetClipboardText()
proc getCPUCount(): cint {...}{.importc: "SDL_GetCPUCount", cdecl.}-
This function returns the number of CPU cores available.
proc getCPUCacheLineSize(): cint {...}{.importc: "SDL_GetCPUCacheLineSize", cdecl.}-
This function returns the L1 cache line size of the CPU
This is useful for determining multi-threaded structure padding
or SIMD prefetch sizes.
proc hasRDTSC(): bool {...}{.importc: "SDL_HasRDTSC", cdecl.}-
This function returns true if the CPU has the RDTSC instruction.
proc hasAltiVec(): bool {...}{.importc: "SDL_HasAltiVec", cdecl.}-
This function returns true if the CPU has AltiVec features.
proc hasMMX(): bool {...}{.importc: "SDL_HasMMX", cdecl.}-
This function returns true if the CPU has MMX features.
proc has3DNow(): bool {...}{.importc: "SDL_Has3DNow", cdecl.}-
This function returns true if the CPU has 3DNow! features.
proc hasSSE(): bool {...}{.importc: "SDL_HasSSE", cdecl.}-
This function returns true if the CPU has SSE features.
proc hasSSE2(): bool {...}{.importc: "SDL_HasSSE2", cdecl.}-
This function returns true if the CPU has SSE2 features.
proc hasSSE3(): bool {...}{.importc: "SDL_HasSSE3", cdecl.}-
This function returns true if the CPU has SSE3 features.
proc hasSSE41(): bool {...}{.importc: "SDL_HasSSE41", cdecl.}-
This function returns true if the CPU has SSE4.1 features.
proc hasSSE42(): bool {...}{.importc: "SDL_HasSSE42", cdecl.}-
This function returns true if the CPU has SSE4.2 features.
proc hasAVX(): bool {...}{.importc: "SDL_HasAVX", cdecl.}-
This function returns true if the CPU has AVX features.
proc hasAVX2(): bool {...}{.importc: "SDL_HasAVX2", cdecl.}-
This function returns true if the CPU has AVX2 features.
proc hasAVX512F(): bool {...}{.importc: "SDL_HasAVX512F", cdecl.}-
This function returns true if the CPU has AVX-512F (foundation) features.
proc hasARMSIMD(): bool {...}{.importc: "SDL_HasARMSIMD", cdecl.}-
This function returns true if the CPU has ARM SIMD (ARMv6) features.
proc hasNEON(): bool {...}{.importc: "SDL_HasNEON", cdecl.}-
This function returns true if the CPU has NEON (ARM SIMD) features.
proc getSystemRAM(): cint {...}{.importc: "SDL_GetSystemRAM", cdecl.}-
This function returns the amount of RAM configured in the system, in MB.
proc sIMDGetAlignment(): uint {...}{.importc: "SDL_SIMDGetAlignment", cdecl.}-
\brief 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.
proc sIMDAlloc(len: uint): pointer {...}{.importc: "SDL_SIMDAlloc", cdecl.}-
\brief 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.
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.
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.
\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.
\sa SDL_SIMDAlignment
\sa SDL_SIMDFree
proc sIMDFree(`ptr`: pointer) {...}{.importc: "SDL_SIMDFree", cdecl.}-
\brief Deallocate 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.
However, SDL_SIMDFree(NULL) is a legal no-op.
\sa SDL_SIMDAlloc
proc getPixelFormatName(format: Uint32): cstring {...}{.
importc: "SDL_GetPixelFormatName", cdecl.}-
\brief Get the human readable name of a pixel format
proc pixelFormatEnumToMasks(format: Uint32; bpp: ptr cint; Rmask: ptr Uint32;
Gmask: ptr Uint32; Bmask: ptr Uint32; Amask: ptr Uint32): bool {...}{.
importc: "SDL_PixelFormatEnumToMasks", cdecl.}-
\brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
\return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
\sa SDL_MasksToPixelFormatEnum()
proc masksToPixelFormatEnum(bpp: cint; Rmask: Uint32; Gmask: Uint32; Bmask: Uint32;
Amask: Uint32): Uint32 {...}{.
importc: "SDL_MasksToPixelFormatEnum", cdecl.}-
\brief Convert a bpp and RGBA masks to an enumerated pixel format.
\return The pixel format, or ::SDL_PIXELFORMAT_UNKNOWN if the conversion
wasn't possible.
\sa SDL_PixelFormatEnumToMasks()
proc allocFormat(pixelFormat: Uint32): ptr PixelFormat {...}{.importc: "SDL_AllocFormat",
cdecl.}-
\brief Create an SDL_PixelFormat structure from a pixel format enum.
proc freeFormat(format: ptr PixelFormat) {...}{.importc: "SDL_FreeFormat", cdecl.}-
\brief Free an SDL_PixelFormat structure.
proc allocPalette(ncolors: cint): ptr Palette {...}{.importc: "SDL_AllocPalette", cdecl.}-
\brief Create a palette structure with the specified number of color
entries.
\return A new palette, or NULL if there wasn't enough memory.
\note The palette entries are initialized to white.
\sa SDL_FreePalette()
proc setPixelFormatPalette(format: ptr PixelFormat; palette: ptr Palette): cint {...}{.
importc: "SDL_SetPixelFormatPalette", cdecl.}-
\brief Set the palette for a pixel format structure.
proc setPaletteColors(palette: ptr Palette; colors: ptr Color; firstcolor: cint;
ncolors: cint): cint {...}{.importc: "SDL_SetPaletteColors", cdecl.}-
\brief Set a range of colors in a palette.
\param palette The palette to modify.
\param colors An array of colors to copy into the palette.
\param firstcolor The index of the first palette entry to modify.
\param ncolors The number of entries to modify.
\return 0 on success, or -1 if not all of the colors could be set.
proc freePalette(palette: ptr Palette) {...}{.importc: "SDL_FreePalette", cdecl.}-
\brief Free a palette created with SDL_AllocPalette().
\sa SDL_AllocPalette()
proc mapRGB(format: ptr PixelFormat; r: Uint8; g: Uint8; b: Uint8): Uint32 {...}{.
importc: "SDL_MapRGB", cdecl.}-
\brief Maps an RGB triple to an opaque pixel value for a given pixel format.
\sa SDL_MapRGBA
proc mapRGBA(format: ptr PixelFormat; r: Uint8; g: Uint8; b: Uint8; a: Uint8): Uint32 {...}{.
importc: "SDL_MapRGBA", cdecl.}-
\brief Maps an RGBA quadruple to a pixel value for a given pixel format.
\sa SDL_MapRGB
proc getRGB(pixel: Uint32; format: ptr PixelFormat; r: ptr Uint8; g: ptr Uint8; b: ptr Uint8) {...}{.
importc: "SDL_GetRGB", cdecl.}-
\brief Get the RGB components from a pixel of the specified format.
\sa SDL_GetRGBA
proc getRGBA(pixel: Uint32; format: ptr PixelFormat; r: ptr Uint8; g: ptr Uint8;
b: ptr Uint8; a: ptr Uint8) {...}{.importc: "SDL_GetRGBA", cdecl.}-
\brief Get the RGBA components from a pixel of the specified format.
\sa SDL_GetRGB
proc calculateGammaRamp(gamma: cfloat; ramp: ptr Uint16) {...}{.
importc: "SDL_CalculateGammaRamp", cdecl.}-
\brief Calculate a 256 entry gamma ramp for a gamma value.
proc hasIntersection(A: ptr Rect; B: ptr Rect): bool {...}{.importc: "SDL_HasIntersection",
cdecl.}-
\brief Determine whether two rectangles intersect.
\return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
proc intersectRect(A: ptr Rect; B: ptr Rect; result: ptr Rect): bool {...}{.
importc: "SDL_IntersectRect", cdecl.}-
\brief Calculate the intersection of two rectangles.
\return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
proc unionRect(A: ptr Rect; B: ptr Rect; result: ptr Rect) {...}{.importc: "SDL_UnionRect", cdecl.}-
\brief Calculate the union of two rectangles.
proc enclosePoints(points: ptr Point; count: cint; clip: ptr Rect; result: ptr Rect): bool {...}{.
importc: "SDL_EnclosePoints", cdecl.}-
\brief Calculate a minimal rectangle enclosing a set of points
\return SDL_TRUE if any points were within the clipping rect
proc intersectRectAndLine(rect: ptr Rect; X1: ptr cint; Y1: ptr cint; X2: ptr cint;
Y2: ptr cint): bool {...}{.importc: "SDL_IntersectRectAndLine",
cdecl.}-
\brief Calculate the intersection of a rectangle and line segment.
\return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
proc composeCustomBlendMode(srcColorFactor: BlendFactor;
dstColorFactor: BlendFactor;
colorOperation: BlendOperation;
srcAlphaFactor: BlendFactor;
dstAlphaFactor: BlendFactor;
alphaOperation: BlendOperation): BlendMode {...}{.
importc: "SDL_ComposeCustomBlendMode", cdecl.}-
\brief Create a custom blend mode, which may or may not be supported by a given renderer
\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 result of the blend mode operation will be:
dstRGB = dstRGB dstColorFactor colorOperation srcRGB srcColorFactor
and
dstA = dstA dstAlphaFactor alphaOperation srcA srcAlphaFactor
proc createRGBSurface(flags: Uint32; width: cint; height: cint; depth: cint;
Rmask: Uint32; Gmask: Uint32; Bmask: Uint32; Amask: Uint32): ptr Surface {...}{.
importc: "SDL_CreateRGBSurface", cdecl.}-
Allocate and free an RGB surface.
If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
If the depth is greater than 8 bits, the pixel format is set using the
flags '[RGB]mask'.
If the function runs out of memory, it will return NULL.
\param flags The \c flags are obsolete and should be set to 0.
\param width The width in pixels of the surface to create.
\param height The height in pixels of the surface to create.
\param depth The depth in bits of the surface to create.
\param Rmask The red mask of the surface to create.
\param Gmask The green mask of the surface to create.
\param Bmask The blue mask of the surface to create.
\param Amask The alpha mask of the surface to create.
proc createRGBSurfaceWithFormat(flags: Uint32; width: cint; height: cint; depth: cint;
format: Uint32): ptr Surface {...}{.
importc: "SDL_CreateRGBSurfaceWithFormat", cdecl.}-
!!! FIXME for 2.1: why does this ask for depth? Format provides that.
proc createRGBSurfaceFrom(pixels: pointer; width: cint; height: cint; depth: cint;
pitch: cint; Rmask: Uint32; Gmask: Uint32; Bmask: Uint32;
Amask: Uint32): ptr Surface {...}{.
importc: "SDL_CreateRGBSurfaceFrom", cdecl.}-
proc createRGBSurfaceWithFormatFrom(pixels: pointer; width: cint; height: cint;
depth: cint; pitch: cint; format: Uint32): ptr Surface {...}{.
importc: "SDL_CreateRGBSurfaceWithFormatFrom", cdecl.}-
proc freeSurface(surface: ptr Surface) {...}{.importc: "SDL_FreeSurface", cdecl.}-
proc setSurfacePalette(surface: ptr Surface; palette: ptr Palette): cint {...}{.
importc: "SDL_SetSurfacePalette", cdecl.}-
\brief Set the palette used by a surface.
\return 0, or -1 if the surface format doesn't use a palette.
\note A single palette can be shared with many surfaces.
proc lockSurface(surface: ptr Surface): cint {...}{.importc: "SDL_LockSurface", cdecl.}-
\brief Sets up a surface for directly accessing the pixels.
Between calls to SDL_LockSurface() / SDL_UnlockSurface(), you can write
to and read from \c surface->pixels, using the pixel format stored in
\c surface->format. Once you are done accessing the surface, you should
use SDL_UnlockSurface() to release it.
Not all surfaces require locking. If SDL_MUSTLOCK(surface) evaluates
to 0, then you can read and write to the surface at any time, and the
pixel format of the surface will not change.
No operating system or library calls should be made between lock/unlock
pairs, as critical system locks may be held during this time.
SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
\sa SDL_UnlockSurface()
proc unlockSurface(surface: ptr Surface) {...}{.importc: "SDL_UnlockSurface", cdecl.}-
\sa SDL_LockSurface()
proc loadBMP_RW(src: ptr RWops; freesrc: cint): ptr Surface {...}{.importc: "SDL_LoadBMP_RW",
cdecl.}-
Load a surface from a seekable SDL data stream (memory or file).
If \c freesrc is non-zero, the stream will be closed after being read.
The new surface should be freed with SDL_FreeSurface().
\return the new surface, or NULL if there was an error.
proc saveBMP_RW(surface: ptr Surface; dst: ptr RWops; freedst: cint): cint {...}{.
importc: "SDL_SaveBMP_RW", cdecl.}-
Save a surface to a seekable SDL data stream (memory or file).
Surfaces with a 24-bit, 32-bit and paletted 8-bit format get saved in the
BMP directly. Other RGB formats with 8-bit or higher get converted to a
24-bit surface or, if they have an alpha mask or a colorkey, to a 32-bit
surface before they are saved. YUV and paletted 1-bit and 4-bit formats are
not supported.
If \c freedst is non-zero, the stream will be closed after being written.
\return 0 if successful or -1 if there was an error.
proc setSurfaceRLE(surface: ptr Surface; flag: cint): cint {...}{.
importc: "SDL_SetSurfaceRLE", cdecl.}-
\brief Sets the RLE acceleration hint for a surface.
\return 0 on success, or -1 if the surface is not valid
\note If RLE is enabled, colorkey and alpha blending blits are much faster,
but the surface must be locked before directly accessing the pixels.
proc setColorKey(surface: ptr Surface; flag: cint; key: Uint32): cint {...}{.
importc: "SDL_SetColorKey", cdecl.}-
\brief Sets the color key (transparent pixel) in a blittable surface.
\param surface The surface to update
\param flag Non-zero to enable colorkey and 0 to disable colorkey
\param key The transparent pixel in the native surface format
\return 0 on success, or -1 if the surface is not valid
You can pass SDL_RLEACCEL to enable RLE accelerated blits.
proc hasColorKey(surface: ptr Surface): bool {...}{.importc: "SDL_HasColorKey", cdecl.}-
\brief Returns whether the surface has a color key
\return SDL_TRUE if the surface has a color key, or SDL_FALSE if the surface is NULL or has no color key
proc getColorKey(surface: ptr Surface; key: ptr Uint32): cint {...}{.
importc: "SDL_GetColorKey", cdecl.}-
\brief Gets the color key (transparent pixel) in a blittable surface.
\param surface The surface to update
\param key A pointer filled in with the transparent pixel in the native
surface format
\return 0 on success, or -1 if the surface is not valid or colorkey is not
enabled.
proc setSurfaceColorMod(surface: ptr Surface; r: Uint8; g: Uint8; b: Uint8): cint {...}{.
importc: "SDL_SetSurfaceColorMod", cdecl.}-
\brief Set an additional color value used in blit operations.
\param surface The surface to update.
\param r The red color value multiplied into blit operations.
\param g The green color value multiplied into blit operations.
\param b The blue color value multiplied into blit operations.
\return 0 on success, or -1 if the surface is not valid.
\sa SDL_GetSurfaceColorMod()
proc getSurfaceColorMod(surface: ptr Surface; r: ptr Uint8; g: ptr Uint8; b: ptr Uint8): cint {...}{.
importc: "SDL_GetSurfaceColorMod", cdecl.}-
\brief Get the additional color value used in blit operations.
\param surface The surface to query.
\param r A pointer filled in with the current red color value.
\param g A pointer filled in with the current green color value.
\param b A pointer filled in with the current blue color value.
\return 0 on success, or -1 if the surface is not valid.
\sa SDL_SetSurfaceColorMod()
proc setSurfaceAlphaMod(surface: ptr Surface; alpha: Uint8): cint {...}{.
importc: "SDL_SetSurfaceAlphaMod", cdecl.}-
\brief Set an additional alpha value used in blit operations.
\param surface The surface to update.
\param alpha The alpha value multiplied into blit operations.
\return 0 on success, or -1 if the surface is not valid.
\sa SDL_GetSurfaceAlphaMod()
proc getSurfaceAlphaMod(surface: ptr Surface; alpha: ptr Uint8): cint {...}{.
importc: "SDL_GetSurfaceAlphaMod", cdecl.}-
\brief Get the additional alpha value used in blit operations.
\param surface The surface to query.
\param alpha A pointer filled in with the current alpha value.
\return 0 on success, or -1 if the surface is not valid.
\sa SDL_SetSurfaceAlphaMod()
proc setSurfaceBlendMode(surface: ptr Surface; blendMode: BlendMode): cint {...}{.
importc: "SDL_SetSurfaceBlendMode", cdecl.}-
\brief Set the blend mode used for blit operations.
\param surface The surface to update.
\param blendMode ::SDL_BlendMode to use for blit blending.
\return 0 on success, or -1 if the parameters are not valid.
\sa SDL_GetSurfaceBlendMode()
proc getSurfaceBlendMode(surface: ptr Surface; blendMode: ptr BlendMode): cint {...}{.
importc: "SDL_GetSurfaceBlendMode", cdecl.}-
\brief Get the blend mode used for blit operations.
\param surface The surface to query.
\param blendMode A pointer filled in with the current blend mode.
\return 0 on success, or -1 if the surface is not valid.
\sa SDL_SetSurfaceBlendMode()
proc setClipRect(surface: ptr Surface; rect: ptr Rect): bool {...}{.
importc: "SDL_SetClipRect", cdecl.}-
Sets the clipping rectangle for the destination surface in a blit.
If the clip rectangle is NULL, clipping will be disabled.
If the clip rectangle doesn't intersect the surface, the function will
return SDL_FALSE and blits will be completely clipped. Otherwise the
function returns SDL_TRUE and blits to the surface will be clipped to
the intersection of the surface area and the clipping rectangle.
Note that blits are automatically clipped to the edges of the source
and destination surfaces.
proc getClipRect(surface: ptr Surface; rect: ptr Rect) {...}{.importc: "SDL_GetClipRect",
cdecl.}-
Gets the clipping rectangle for the destination surface in a blit.
\c rect must be a pointer to a valid rectangle which will be filled
with the correct values.
proc duplicateSurface(surface: ptr Surface): ptr Surface {...}{.
importc: "SDL_DuplicateSurface", cdecl.}-
Creates a new surface identical to the existing surface
proc convertSurface(src: ptr Surface; fmt: ptr PixelFormat; flags: Uint32): ptr Surface {...}{.
importc: "SDL_ConvertSurface", cdecl.}-
Creates a new surface of the specified format, and then copies and maps
the given surface to it so the blit of the converted surface will be as
fast as possible. If this function fails, it returns NULL.
The \c flags parameter is passed to SDL_CreateRGBSurface() and has those
semantics. You can also pass ::SDL_RLEACCEL in the flags parameter and
SDL will try to RLE accelerate colorkey and alpha blits in the resulting
surface.
proc convertSurfaceFormat(src: ptr Surface; pixelFormat: Uint32; flags: Uint32): ptr Surface {...}{.
importc: "SDL_ConvertSurfaceFormat", cdecl.}-
proc convertPixels(width: cint; height: cint; srcFormat: Uint32; src: pointer;
srcPitch: cint; dstFormat: Uint32; dst: pointer; dstPitch: cint): cint {...}{.
importc: "SDL_ConvertPixels", cdecl.}-
\brief Copy a block of pixels of one format to another format
\return 0 on success, or -1 if there was an error
proc fillRect(dst: ptr Surface; rect: ptr Rect; color: Uint32): cint {...}{.
importc: "SDL_FillRect", cdecl.}-
Performs a fast fill of the given rectangle with \c color.
If \c rect is NULL, the whole surface will be filled with \c color.
The color should be a pixel of the format used by the surface, and
can be generated by the SDL_MapRGB() function.
\return 0 on success, or -1 on error.
proc fillRects(dst: ptr Surface; rects: ptr Rect; count: cint; color: Uint32): cint {...}{.
importc: "SDL_FillRects", cdecl.}-
proc upperBlit(src: ptr Surface; srcrect: ptr Rect; dst: ptr Surface; dstrect: ptr Rect): cint {...}{.
importc: "SDL_UpperBlit", cdecl.}-
This is the public blit function, SDL_BlitSurface(), and it performs
rectangle validation and clipping before passing it to SDL_LowerBlit()
proc lowerBlit(src: ptr Surface; srcrect: ptr Rect; dst: ptr Surface; dstrect: ptr Rect): cint {...}{.
importc: "SDL_LowerBlit", cdecl.}-
This is a semi-private blit function and it performs low-level surface
blitting only.
proc softStretch(src: ptr Surface; srcrect: ptr Rect; dst: ptr Surface; dstrect: ptr Rect): cint {...}{.
importc: "SDL_SoftStretch", cdecl.}-
\brief Perform a fast, low quality, stretch blit between two surfaces of the
same pixel format.
\note This function uses a static buffer, and is not thread-safe.
proc upperBlitScaled(src: ptr Surface; srcrect: ptr Rect; dst: ptr Surface;
dstrect: ptr Rect): cint {...}{.importc: "SDL_UpperBlitScaled", cdecl.}-
This is the public scaled blit function, SDL_BlitScaled(), and it performs
rectangle validation and clipping before passing it to SDL_LowerBlitScaled()
proc lowerBlitScaled(src: ptr Surface; srcrect: ptr Rect; dst: ptr Surface;
dstrect: ptr Rect): cint {...}{.importc: "SDL_LowerBlitScaled", cdecl.}-
This is a semi-private blit function and it performs low-level surface
scaled blitting only.
proc setYUVConversionMode(mode: YUV_CONVERSION_MODE) {...}{.
importc: "SDL_SetYUVConversionMode", cdecl.}-
\brief Set the YUV conversion mode
proc getYUVConversionMode(): YUV_CONVERSION_MODE {...}{.
importc: "SDL_GetYUVConversionMode", cdecl.}-
\brief Get the YUV conversion mode
proc getYUVConversionModeForResolution(width: cint; height: cint): YUV_CONVERSION_MODE {...}{.
importc: "SDL_GetYUVConversionModeForResolution", cdecl.}-
\brief Get the YUV conversion mode, returning the correct mode for the resolution when the current conversion mode is SDL_YUV_CONVERSION_AUTOMATIC
proc getNumVideoDrivers(): cint {...}{.importc: "SDL_GetNumVideoDrivers", cdecl.}-
Function prototypes
\brief Get the number of video drivers compiled into SDL
\sa SDL_GetVideoDriver()
proc getVideoDriver(index: cint): cstring {...}{.importc: "SDL_GetVideoDriver", cdecl.}-
\brief Get the name of a built in video driver.
\note The video drivers are presented in the order in which they are
normally checked during initialization.
\sa SDL_GetNumVideoDrivers()
proc videoInit(driverName: cstring): cint {...}{.importc: "SDL_VideoInit", cdecl.}-
\brief Initialize the video subsystem, optionally specifying a video driver.
\param driver_name Initialize a specific driver by name, or NULL for the
default video driver.
\return 0 on success, -1 on error
This function initializes the video subsystem; setting up a connection
to the window manager, etc, and determines the available display modes
and pixel formats, but does not initialize a window or graphics mode.
\sa SDL_VideoQuit()
proc videoQuit() {...}{.importc: "SDL_VideoQuit", cdecl.}-
\brief Shuts down the video subsystem.
This function closes all windows, and restores the original video mode.
\sa SDL_VideoInit()
proc getCurrentVideoDriver(): cstring {...}{.importc: "SDL_GetCurrentVideoDriver", cdecl.}-
\brief Returns the name of the currently initialized video driver.
\return The name of the current video driver or NULL if no driver
has been initialized
\sa SDL_GetNumVideoDrivers()
\sa SDL_GetVideoDriver()
proc getNumVideoDisplays(): cint {...}{.importc: "SDL_GetNumVideoDisplays", cdecl.}-
\brief Returns the number of available video displays.
\sa SDL_GetDisplayBounds()
proc getDisplayName(displayIndex: cint): cstring {...}{.importc: "SDL_GetDisplayName",
cdecl.}-
\brief Get the name of a display in UTF-8 encoding
\return The name of a display, or NULL for an invalid display index.
\sa SDL_GetNumVideoDisplays()
proc getDisplayBounds(displayIndex: cint; rect: ptr Rect): cint {...}{.
importc: "SDL_GetDisplayBounds", cdecl.}-
\brief Get the desktop area represented by a display, with the primary
display located at 0,0
\return 0 on success, or -1 if the index is out of range.
\sa SDL_GetNumVideoDisplays()
proc getDisplayUsableBounds(displayIndex: cint; rect: ptr Rect): cint {...}{.
importc: "SDL_GetDisplayUsableBounds", cdecl.}-
\brief Get the usable desktop area represented by a display, with the
primary display located at 0,0
This is the same area as SDL_GetDisplayBounds() reports, but with portions
reserved by the system removed. For example, on Mac OS X, this subtracts
the area occupied by the menu bar and dock.
Setting a window to be fullscreen generally bypasses these unusable areas,
so these are good guidelines for the maximum space available to a
non-fullscreen window.
\return 0 on success, or -1 if the index is out of range.
\sa SDL_GetDisplayBounds()
\sa SDL_GetNumVideoDisplays()
proc getDisplayDPI(displayIndex: cint; ddpi: ptr cfloat; hdpi: ptr cfloat;
vdpi: ptr cfloat): cint {...}{.importc: "SDL_GetDisplayDPI", cdecl.}-
\brief Get the dots/pixels-per-inch for a display
\note Diagonal, horizontal and vertical DPI can all be optionally
returned if the parameter is non-NULL.
\return 0 on success, or -1 if no DPI information is available or the index is out of range.
\sa SDL_GetNumVideoDisplays()
proc getDisplayOrientation(displayIndex: cint): DisplayOrientation {...}{.
importc: "SDL_GetDisplayOrientation", cdecl.}-
\brief Get the orientation of a display
\return The orientation of the display, or SDL_ORIENTATION_UNKNOWN if it isn't available.
\sa SDL_GetNumVideoDisplays()
proc getNumDisplayModes(displayIndex: cint): cint {...}{.
importc: "SDL_GetNumDisplayModes", cdecl.}-
\brief Returns the number of available display modes.
\sa SDL_GetDisplayMode()
proc getDisplayMode(displayIndex: cint; modeIndex: cint; mode: ptr DisplayMode): cint {...}{.
importc: "SDL_GetDisplayMode", cdecl.}-
\brief Fill in information about a specific display mode.
\note The display modes are sorted in this priority:
\li bits per pixel -> more colors to fewer colors
\li width -> largest to smallest
\li height -> largest to smallest
\li refresh rate -> highest to lowest
\sa SDL_GetNumDisplayModes()
proc getDesktopDisplayMode(displayIndex: cint; mode: ptr DisplayMode): cint {...}{.
importc: "SDL_GetDesktopDisplayMode", cdecl.}-
\brief Fill in information about the desktop display mode.
proc getCurrentDisplayMode(displayIndex: cint; mode: ptr DisplayMode): cint {...}{.
importc: "SDL_GetCurrentDisplayMode", cdecl.}-
\brief Fill in information about the current display mode.
proc getClosestDisplayMode(displayIndex: cint; mode: ptr DisplayMode;
closest: ptr DisplayMode): ptr DisplayMode {...}{.
importc: "SDL_GetClosestDisplayMode", cdecl.}-
\brief Get the closest match to the requested display mode.
\param displayIndex The index of display from which mode should be queried.
\param mode The desired display mode
\param closest A pointer to a display mode to be filled in with the closest
match of the available display modes.
\return The passed in value \c closest, or NULL if no matching video mode
was available.
The available display modes are scanned, and \c closest is filled in with the
closest mode matching the requested mode and returned. The mode format and
refresh_rate default to the desktop mode if they are 0. The modes are
scanned with size being first priority, format being second priority, and
finally checking the refresh_rate. If all the available modes are too
small, then NULL is returned.
\sa SDL_GetNumDisplayModes()
\sa SDL_GetDisplayMode()
proc getWindowDisplayIndex(window: ptr Window): cint {...}{.
importc: "SDL_GetWindowDisplayIndex", cdecl.}-
\brief Get the display index associated with a window.
\return the display index of the display containing the center of the
window, or -1 on error.
proc setWindowDisplayMode(window: ptr Window; mode: ptr DisplayMode): cint {...}{.
importc: "SDL_SetWindowDisplayMode", cdecl.}-
\brief Set the display mode used when a fullscreen window is visible.
By default the window's dimensions and the desktop format and refresh rate
are used.
\param window The window for which the display mode should be set.
\param mode The mode to use, or NULL for the default mode.
\return 0 on success, or -1 if setting the display mode failed.
\sa SDL_GetWindowDisplayMode()
\sa SDL_SetWindowFullscreen()
proc getWindowDisplayMode(window: ptr Window; mode: ptr DisplayMode): cint {...}{.
importc: "SDL_GetWindowDisplayMode", cdecl.}-
\brief Fill in information about the display mode used when a fullscreen
window is visible.
\sa SDL_SetWindowDisplayMode()
\sa SDL_SetWindowFullscreen()
proc getWindowPixelFormat(window: ptr Window): Uint32 {...}{.
importc: "SDL_GetWindowPixelFormat", cdecl.}-
\brief Get the pixel format associated with the window.
proc createWindow(title: cstring; x: cint; y: cint; w: cint; h: cint; flags: Uint32): ptr Window {...}{.
importc: "SDL_CreateWindow", cdecl.}-
\brief Create a window with the specified position, dimensions, and flags.
\param title The title of the window, in UTF-8 encoding.
\param x The x position of the window, ::SDL_WINDOWPOS_CENTERED, or
::SDL_WINDOWPOS_UNDEFINED.
\param y The y position of the window, ::SDL_WINDOWPOS_CENTERED, or
::SDL_WINDOWPOS_UNDEFINED.
\param w The width of the window, in screen coordinates.
\param h The height of the window, in screen coordinates.
\param flags The flags for the window, a mask of any of the following:
::SDL_WINDOW_FULLSCREEN, ::SDL_WINDOW_OPENGL,
::SDL_WINDOW_HIDDEN, ::SDL_WINDOW_BORDERLESS,
::SDL_WINDOW_RESIZABLE, ::SDL_WINDOW_MAXIMIZED,
::SDL_WINDOW_MINIMIZED, ::SDL_WINDOW_INPUT_GRABBED,
::SDL_WINDOW_ALLOW_HIGHDPI, ::SDL_WINDOW_VULKAN.
\return The created window, or NULL if window creation failed.
If the window is created with the SDL_WINDOW_ALLOW_HIGHDPI flag, its size
in pixels may differ from its size in screen coordinates on platforms with
high-DPI support (e.g. iOS and Mac OS X). Use SDL_GetWindowSize() to query
the client area's size in screen coordinates, and SDL_GL_GetDrawableSize(),
SDL_Vulkan_GetDrawableSize(), or SDL_GetRendererOutputSize() to query the
drawable size in pixels.
If the window is created with any of the SDL_WINDOW_OPENGL or
SDL_WINDOW_VULKAN flags, then the corresponding LoadLibrary function
(SDL_GL_LoadLibrary or SDL_Vulkan_LoadLibrary) is called and the
corresponding UnloadLibrary function is called by SDL_DestroyWindow().
If SDL_WINDOW_VULKAN is specified and there isn't a working Vulkan driver,
SDL_CreateWindow() will fail because SDL_Vulkan_LoadLibrary() will fail.
\note On non-Apple devices, SDL requires you to either not link to the
Vulkan loader or link to a dynamic library version. This limitation
may be removed in a future version of SDL.
\sa SDL_DestroyWindow()
\sa SDL_GL_LoadLibrary()
\sa SDL_Vulkan_LoadLibrary()
proc createWindowFrom(data: pointer): ptr Window {...}{.importc: "SDL_CreateWindowFrom",
cdecl.}-
\brief Create an SDL window from an existing native window.
\param data A pointer to driver-dependent window creation data
\return The created window, or NULL if window creation failed.
\sa SDL_DestroyWindow()
proc getWindowID(window: ptr Window): Uint32 {...}{.importc: "SDL_GetWindowID", cdecl.}-
\brief Get the numeric ID of a window, for logging purposes.
proc getWindowFromID(id: Uint32): ptr Window {...}{.importc: "SDL_GetWindowFromID", cdecl.}-
\brief Get a window from a stored ID, or NULL if it doesn't exist.
proc getWindowFlags(window: ptr Window): Uint32 {...}{.importc: "SDL_GetWindowFlags", cdecl.}-
\brief Get the window flags.
proc setWindowTitle(window: ptr Window; title: cstring) {...}{.
importc: "SDL_SetWindowTitle", cdecl.}-
\brief Set the title of a window, in UTF-8 format.
\sa SDL_GetWindowTitle()
proc getWindowTitle(window: ptr Window): cstring {...}{.importc: "SDL_GetWindowTitle", cdecl.}-
\brief Get the title of a window, in UTF-8 format.
\sa SDL_SetWindowTitle()
proc setWindowIcon(window: ptr Window; icon: ptr Surface) {...}{.
importc: "SDL_SetWindowIcon", cdecl.}-
\brief Set the icon for a window.
\param window The window for which the icon should be set.
\param icon The icon for the window.
proc setWindowData(window: ptr Window; name: cstring; userdata: pointer): pointer {...}{.
importc: "SDL_SetWindowData", cdecl.}-
\brief Associate an arbitrary named pointer with a window.
\param window The window to associate with the pointer.
\param name The name of the pointer.
\param userdata The associated pointer.
\return The previous value associated with 'name'
\note The name is case-sensitive.
\sa SDL_GetWindowData()
proc getWindowData(window: ptr Window; name: cstring): pointer {...}{.
importc: "SDL_GetWindowData", cdecl.}-
\brief Retrieve the data pointer associated with a window.
\param window The window to query.
\param name The name of the pointer.
\return The value associated with 'name'
\sa SDL_SetWindowData()
proc setWindowPosition(window: ptr Window; x: cint; y: cint) {...}{.
importc: "SDL_SetWindowPosition", cdecl.}-
\brief Set the position of a window.
\param window The window to reposition.
\param x The x coordinate of the window in screen coordinates, or
::SDL_WINDOWPOS_CENTERED or ::SDL_WINDOWPOS_UNDEFINED.
\param y The y coordinate of the window in screen coordinates, or
::SDL_WINDOWPOS_CENTERED or ::SDL_WINDOWPOS_UNDEFINED.
\note The window coordinate origin is the upper left of the display.
\sa SDL_GetWindowPosition()
proc getWindowPosition(window: ptr Window; x: ptr cint; y: ptr cint) {...}{.
importc: "SDL_GetWindowPosition", cdecl.}-
\brief Get the position of a window.
\param window The window to query.
\param x Pointer to variable for storing the x position, in screen
coordinates. May be NULL.
\param y Pointer to variable for storing the y position, in screen
coordinates. May be NULL.
\sa SDL_SetWindowPosition()
proc setWindowSize(window: ptr Window; w: cint; h: cint) {...}{.importc: "SDL_SetWindowSize",
cdecl.}-
\brief Set the size of a window's client area.
\param window The window to resize.
\param w The width of the window, in screen coordinates. Must be >0.
\param h The height of the window, in screen coordinates. Must be >0.
\note Fullscreen windows automatically match the size of the display mode,
and you should use SDL_SetWindowDisplayMode() to change their size.
The window size in screen coordinates may differ from the size in pixels, if
the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a platform with
high-dpi support (e.g. iOS or OS X). Use SDL_GL_GetDrawableSize() or
SDL_GetRendererOutputSize() to get the real client area size in pixels.
\sa SDL_GetWindowSize()
\sa SDL_SetWindowDisplayMode()
proc getWindowSize(window: ptr Window; w: ptr cint; h: ptr cint) {...}{.
importc: "SDL_GetWindowSize", cdecl.}-
\brief Get the size of a window's client area.
\param window The window to query.
\param w Pointer to variable for storing the width, in screen
coordinates. May be NULL.
\param h Pointer to variable for storing the height, in screen
coordinates. May be NULL.
The window size in screen coordinates may differ from the size in pixels, if
the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a platform with
high-dpi support (e.g. iOS or OS X). Use SDL_GL_GetDrawableSize() or
SDL_GetRendererOutputSize() to get the real client area size in pixels.
\sa SDL_SetWindowSize()
proc getWindowBordersSize(window: ptr Window; top: ptr cint; left: ptr cint;
bottom: ptr cint; right: ptr cint): cint {...}{.
importc: "SDL_GetWindowBordersSize", cdecl.}-
\brief Get the size of a window's borders (decorations) around the client area.
\param window The window to query.
\param top Pointer to variable for storing the size of the top border. NULL is permitted.
\param left Pointer to variable for storing the size of the left border. NULL is permitted.
\param bottom Pointer to variable for storing the size of the bottom border. NULL is permitted.
\param right Pointer to variable for storing the size of the right border. NULL is permitted.
\return 0 on success, or -1 if getting this information is not supported.
\note if this function fails (returns -1), the size values will be
initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as
if the window in question was borderless.
proc setWindowMinimumSize(window: ptr Window; minW: cint; minH: cint) {...}{.
importc: "SDL_SetWindowMinimumSize", cdecl.}-
\brief Set the minimum size of a window's client area.
\param window The window to set a new minimum size.
\param min_w The minimum width of the window, must be >0
\param min_h The minimum height of the window, must be >0
\note You can't change the minimum size of a fullscreen window, it
automatically matches the size of the display mode.
\sa SDL_GetWindowMinimumSize()
\sa SDL_SetWindowMaximumSize()
proc getWindowMinimumSize(window: ptr Window; w: ptr cint; h: ptr cint) {...}{.
importc: "SDL_GetWindowMinimumSize", cdecl.}-
\brief Get the minimum size of a window's client area.
\param window The window to query.
\param w Pointer to variable for storing the minimum width, may be NULL
\param h Pointer to variable for storing the minimum height, may be NULL
\sa SDL_GetWindowMaximumSize()
\sa SDL_SetWindowMinimumSize()
proc setWindowMaximumSize(window: ptr Window; maxW: cint; maxH: cint) {...}{.
importc: "SDL_SetWindowMaximumSize", cdecl.}-
\brief Set the maximum size of a window's client area.
\param window The window to set a new maximum size.
\param max_w The maximum width of the window, must be >0
\param max_h The maximum height of the window, must be >0
\note You can't change the maximum size of a fullscreen window, it
automatically matches the size of the display mode.
\sa SDL_GetWindowMaximumSize()
\sa SDL_SetWindowMinimumSize()
proc getWindowMaximumSize(window: ptr Window; w: ptr cint; h: ptr cint) {...}{.
importc: "SDL_GetWindowMaximumSize", cdecl.}-
\brief Get the maximum size of a window's client area.
\param window The window to query.
\param w Pointer to variable for storing the maximum width, may be NULL
\param h Pointer to variable for storing the maximum height, may be NULL
\sa SDL_GetWindowMinimumSize()
\sa SDL_SetWindowMaximumSize()
proc setWindowBordered(window: ptr Window; bordered: bool) {...}{.
importc: "SDL_SetWindowBordered", cdecl.}-
\brief Set the border state of a window.
This will add or remove the window's SDL_WINDOW_BORDERLESS flag and
add or remove the border from the actual window. This is a no-op if the
window's border already matches the requested state.
\param window The window of which to change the border state.
\param bordered SDL_FALSE to remove border, SDL_TRUE to add border.
\note You can't change the border state of a fullscreen window.
\sa SDL_GetWindowFlags()
proc setWindowResizable(window: ptr Window; resizable: bool) {...}{.
importc: "SDL_SetWindowResizable", cdecl.}-
\brief Set the user-resizable state of a window.
This will add or remove the window's SDL_WINDOW_RESIZABLE flag and
allow/disallow user resizing of the window. This is a no-op if the
window's resizable state already matches the requested state.
\param window The window of which to change the resizable state.
\param resizable SDL_TRUE to allow resizing, SDL_FALSE to disallow.
\note You can't change the resizable state of a fullscreen window.
\sa SDL_GetWindowFlags()
proc showWindow(window: ptr Window) {...}{.importc: "SDL_ShowWindow", cdecl.}-
\brief Show a window.
\sa SDL_HideWindow()
proc hideWindow(window: ptr Window) {...}{.importc: "SDL_HideWindow", cdecl.}-
\brief Hide a window.
\sa SDL_ShowWindow()
proc raiseWindow(window: ptr Window) {...}{.importc: "SDL_RaiseWindow", cdecl.}-
\brief Raise a window above other windows and set the input focus.
proc maximizeWindow(window: ptr Window) {...}{.importc: "SDL_MaximizeWindow", cdecl.}-
\brief Make a window as large as possible.
\sa SDL_RestoreWindow()
proc minimizeWindow(window: ptr Window) {...}{.importc: "SDL_MinimizeWindow", cdecl.}-
\brief Minimize a window to an iconic representation.
\sa SDL_RestoreWindow()
proc restoreWindow(window: ptr Window) {...}{.importc: "SDL_RestoreWindow", cdecl.}-
\brief Restore the size and position of a minimized or maximized window.
\sa SDL_MaximizeWindow()
\sa SDL_MinimizeWindow()
proc setWindowFullscreen(window: ptr Window; flags: Uint32): cint {...}{.
importc: "SDL_SetWindowFullscreen", cdecl.}-
\brief Set a window's fullscreen state.
\return 0 on success, or -1 if setting the display mode failed.
\sa SDL_SetWindowDisplayMode()
\sa SDL_GetWindowDisplayMode()
proc getWindowSurface(window: ptr Window): ptr Surface {...}{.
importc: "SDL_GetWindowSurface", cdecl.}-
\brief Get the SDL surface associated with the window.
\return The window's framebuffer surface, or NULL on error.
A new surface will be created with the optimal format for the window,
if necessary. This surface will be freed when the window is destroyed.
\note You may not combine this with 3D or the rendering API on this window.
\sa SDL_UpdateWindowSurface()
\sa SDL_UpdateWindowSurfaceRects()
proc updateWindowSurface(window: ptr Window): cint {...}{.
importc: "SDL_UpdateWindowSurface", cdecl.}-
\brief Copy the window surface to the screen.
\return 0 on success, or -1 on error.
\sa SDL_GetWindowSurface()
\sa SDL_UpdateWindowSurfaceRects()
proc updateWindowSurfaceRects(window: ptr Window; rects: ptr Rect; numrects: cint): cint {...}{.
importc: "SDL_UpdateWindowSurfaceRects", cdecl.}-
\brief Copy a number of rectangles on the window surface to the screen.
\return 0 on success, or -1 on error.
\sa SDL_GetWindowSurface()
\sa SDL_UpdateWindowSurface()
proc setWindowGrab(window: ptr Window; grabbed: bool) {...}{.importc: "SDL_SetWindowGrab",
cdecl.}-
\brief Set a window's input grab mode.
\param window The window for which the input grab mode should be set.
\param grabbed This is SDL_TRUE to grab input, and SDL_FALSE to release input.
If the caller enables a grab while another window is currently grabbed,
the other window loses its grab in favor of the caller's window.
\sa SDL_GetWindowGrab()
proc getWindowGrab(window: ptr Window): bool {...}{.importc: "SDL_GetWindowGrab", cdecl.}-
\brief Get a window's input grab mode.
\return This returns SDL_TRUE if input is grabbed, and SDL_FALSE otherwise.
\sa SDL_SetWindowGrab()
proc getGrabbedWindow(): ptr Window {...}{.importc: "SDL_GetGrabbedWindow", cdecl.}-
\brief Get the window that currently has an input grab enabled.
\return This returns the window if input is grabbed, and NULL otherwise.
\sa SDL_SetWindowGrab()
proc setWindowBrightness(window: ptr Window; brightness: cfloat): cint {...}{.
importc: "SDL_SetWindowBrightness", cdecl.}-
\brief Set the brightness (gamma correction) for a window.
\return 0 on success, or -1 if setting the brightness isn't supported.
\sa SDL_GetWindowBrightness()
\sa SDL_SetWindowGammaRamp()
proc getWindowBrightness(window: ptr Window): cfloat {...}{.
importc: "SDL_GetWindowBrightness", cdecl.}-
\brief Get the brightness (gamma correction) for a window.
\return The last brightness value passed to SDL_SetWindowBrightness()
\sa SDL_SetWindowBrightness()
proc setWindowOpacity(window: ptr Window; opacity: cfloat): cint {...}{.
importc: "SDL_SetWindowOpacity", cdecl.}-
\brief Set the opacity for a window
\param window The window which will be made transparent or opaque
\param opacity Opacity (0.0f - transparent, 1.0f - opaque) This will be
clamped internally between 0.0f and 1.0f.
\return 0 on success, or -1 if setting the opacity isn't supported.
\sa SDL_GetWindowOpacity()
proc getWindowOpacity(window: ptr Window; outOpacity: ptr cfloat): cint {...}{.
importc: "SDL_GetWindowOpacity", cdecl.}-
\brief Get the opacity of a window.
If transparency isn't supported on this platform, opacity will be reported
as 1.0f without error.
\param window The window in question.
\param out_opacity Opacity (0.0f - transparent, 1.0f - opaque)
\return 0 on success, or -1 on error (invalid window, etc).
\sa SDL_SetWindowOpacity()
proc setWindowModalFor(modalWindow: ptr Window; parentWindow: ptr Window): cint {...}{.
importc: "SDL_SetWindowModalFor", cdecl.}-
\brief Sets the window as a modal for another window (TODO: reconsider this function and/or its name)
\param modal_window The window that should be modal
\param parent_window The parent window
\return 0 on success, or -1 otherwise.
proc setWindowInputFocus(window: ptr Window): cint {...}{.
importc: "SDL_SetWindowInputFocus", cdecl.}-
\brief Explicitly sets input focus to the window.
You almost certainly want SDL_RaiseWindow() instead of this function. Use
this with caution, as you might give focus to a window that's completely
obscured by other windows.
\param window The window that should get the input focus
\return 0 on success, or -1 otherwise.
\sa SDL_RaiseWindow()
proc setWindowGammaRamp(window: ptr Window; red: ptr Uint16; green: ptr Uint16;
blue: ptr Uint16): cint {...}{.importc: "SDL_SetWindowGammaRamp",
cdecl.}-
\brief Set the gamma ramp for a window.
\param window The window for which the gamma ramp should be set.
\param red The translation table for the red channel, or NULL.
\param green The translation table for the green channel, or NULL.
\param blue The translation table for the blue channel, or NULL.
\return 0 on success, or -1 if gamma ramps are unsupported.
Set the gamma translation table for the red, green, and blue channels
of the video hardware. Each table is an array of 256 16-bit quantities,
representing a mapping between the input and output for that channel.
The input is the index into the array, and the output is the 16-bit
gamma value at that index, scaled to the output color precision.
\sa SDL_GetWindowGammaRamp()
proc getWindowGammaRamp(window: ptr Window; red: ptr Uint16; green: ptr Uint16;
blue: ptr Uint16): cint {...}{.importc: "SDL_GetWindowGammaRamp",
cdecl.}-
\brief Get the gamma ramp for a window.
\param window The window from which the gamma ramp should be queried.
\param red A pointer to a 256 element array of 16-bit quantities to hold
the translation table for the red channel, or NULL.
\param green A pointer to a 256 element array of 16-bit quantities to hold
the translation table for the green channel, or NULL.
\param blue A pointer to a 256 element array of 16-bit quantities to hold
the translation table for the blue channel, or NULL.
\return 0 on success, or -1 if gamma ramps are unsupported.
\sa SDL_SetWindowGammaRamp()
proc setWindowHitTest(window: ptr Window; callback: HitTest; callbackData: pointer): cint {...}{.
importc: "SDL_SetWindowHitTest", cdecl.}-
\brief Provide a callback that decides if a window region has special properties.
Normally windows are dragged and resized by decorations provided by the
system window manager (a title bar, borders, etc), but for some apps, it
makes sense to drag them from somewhere else inside the window itself; for
example, one might have a borderless window that wants to be draggable
from any part, or simulate its own title bar, etc.
This function lets the app provide a callback that designates pieces of
a given window as special. This callback is run during event processing
if we need to tell the OS to treat a region of the window specially; the
use of this callback is known as "hit testing."
Mouse input may not be delivered to your application if it is within
a special area; the OS will often apply that input to moving the window or
resizing the window and not deliver it to the application.
Specifying NULL for a callback disables hit-testing. Hit-testing is
disabled by default.
Platforms that don't support this functionality will return -1
unconditionally, even if you're attempting to disable hit-testing.
Your callback may fire at any time, and its firing does not indicate any
specific behavior (for example, on Windows, this certainly might fire
when the OS is deciding whether to drag your window, but it fires for lots
of other reasons, too, some unrelated to anything you probably care about
_and when the mouse isn't actually at the location it is testing_).
Since this can fire at any time, you should try to keep your callback
efficient, devoid of allocations, etc.
\param window The window to set hit-testing on.
\param callback The callback to call when doing a hit-test.
\param callback_data An app-defined void pointer passed to the callback.
\return 0 on success, -1 on error (including unsupported).
proc destroyWindow(window: ptr Window) {...}{.importc: "SDL_DestroyWindow", cdecl.}-
\brief Destroy a window.
proc isScreenSaverEnabled(): bool {...}{.importc: "SDL_IsScreenSaverEnabled", cdecl.}-
\brief Returns whether the screensaver is currently enabled (default off).
\sa SDL_EnableScreenSaver()
\sa SDL_DisableScreenSaver()
proc enableScreenSaver() {...}{.importc: "SDL_EnableScreenSaver", cdecl.}-
\brief Allow the screen to be blanked by a screensaver
\sa SDL_IsScreenSaverEnabled()
\sa SDL_DisableScreenSaver()
proc disableScreenSaver() {...}{.importc: "SDL_DisableScreenSaver", cdecl.}-
\brief Prevent the screen from being blanked by a screensaver
\sa SDL_IsScreenSaverEnabled()
\sa SDL_EnableScreenSaver()
proc gL_LoadLibrary(path: cstring): cint {...}{.importc: "SDL_GL_LoadLibrary", cdecl.}-
\name OpenGL support functions
@{
\brief Dynamically load an OpenGL library.
\param path The platform dependent OpenGL library name, or NULL to open the
default OpenGL library.
\return 0 on success, or -1 if the library couldn't be loaded.
This should be done after initializing the video driver, but before
creating any OpenGL windows. If no OpenGL library is loaded, the default
library will be loaded upon creation of the first OpenGL window.
\note If you do this, you need to retrieve all of the GL functions used in
your program from the dynamic library using SDL_GL_GetProcAddress().
\sa SDL_GL_GetProcAddress()
\sa SDL_GL_UnloadLibrary()
proc gL_GetProcAddress(`proc`: cstring): pointer {...}{.importc: "SDL_GL_GetProcAddress",
cdecl.}-
\brief Get the address of an OpenGL function.
proc gL_UnloadLibrary() {...}{.importc: "SDL_GL_UnloadLibrary", cdecl.}-
\brief Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary().
\sa SDL_GL_LoadLibrary()
proc gL_ExtensionSupported(extension: cstring): bool {...}{.
importc: "SDL_GL_ExtensionSupported", cdecl.}-
\brief Return true if an OpenGL extension is supported for the current
context.
proc gL_ResetAttributes() {...}{.importc: "SDL_GL_ResetAttributes", cdecl.}-
\brief Reset all previously set OpenGL context attributes to their default values
proc gL_SetAttribute(attr: GLattr; value: cint): cint {...}{.
importc: "SDL_GL_SetAttribute", cdecl.}-
\brief Set an OpenGL window attribute before window creation.
\return 0 on success, or -1 if the attribute could not be set.
proc gL_GetAttribute(attr: GLattr; value: ptr cint): cint {...}{.
importc: "SDL_GL_GetAttribute", cdecl.}-
\brief Get the actual value for an attribute from the current context.
\return 0 on success, or -1 if the attribute could not be retrieved.
The integer at \c value will be modified in either case.
proc gL_CreateContext(window: ptr Window): GLContext {...}{.
importc: "SDL_GL_CreateContext", cdecl.}-
\brief Create an OpenGL context for use with an OpenGL window, and make it
current.
\sa SDL_GL_DeleteContext()
proc gL_MakeCurrent(window: ptr Window; context: GLContext): cint {...}{.
importc: "SDL_GL_MakeCurrent", cdecl.}-
\brief Set up an OpenGL context for rendering into an OpenGL window.
\note The context must have been created with a compatible window.
proc gL_GetCurrentWindow(): ptr Window {...}{.importc: "SDL_GL_GetCurrentWindow", cdecl.}-
\brief Get the currently active OpenGL window.
proc gL_GetCurrentContext(): GLContext {...}{.importc: "SDL_GL_GetCurrentContext", cdecl.}-
\brief Get the currently active OpenGL context.
proc gL_GetDrawableSize(window: ptr Window; w: ptr cint; h: ptr cint) {...}{.
importc: "SDL_GL_GetDrawableSize", cdecl.}-
\brief Get the size of a window's underlying drawable in pixels (for use
with glViewport).
\param window Window from which the drawable size should be queried
\param w Pointer to variable for storing the width in pixels, may be NULL
\param h Pointer to variable for storing the height in pixels, may be NULL
This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI
drawable, i.e. the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a
platform with high-DPI support (Apple calls this "Retina"), and not disabled
by the SDL_HINT_VIDEO_HIGHDPI_DISABLED hint.
\sa SDL_GetWindowSize()
\sa SDL_CreateWindow()
proc gL_SetSwapInterval(interval: cint): cint {...}{.importc: "SDL_GL_SetSwapInterval",
cdecl.}-
\brief Set the swap interval for the current OpenGL context.
\param interval 0 for immediate updates, 1 for updates synchronized with the
vertical retrace. If the system supports it, you may
specify -1 to allow late swaps to happen immediately
instead of waiting for the next retrace.
\return 0 on success, or -1 if setting the swap interval is not supported.
\sa SDL_GL_GetSwapInterval()
proc gL_GetSwapInterval(): cint {...}{.importc: "SDL_GL_GetSwapInterval", cdecl.}-
\brief Get the swap interval for the current OpenGL context.
\return 0 if there is no vertical retrace synchronization, 1 if the buffer
swap is synchronized with the vertical retrace, and -1 if late
swaps happen immediately instead of waiting for the next retrace.
If the system can't determine the swap interval, or there isn't a
valid current context, this will return 0 as a safe default.
\sa SDL_GL_SetSwapInterval()
proc gL_SwapWindow(window: ptr Window) {...}{.importc: "SDL_GL_SwapWindow", cdecl.}-
\brief Swap the OpenGL buffers for a window, if double-buffering is
supported.
proc gL_DeleteContext(context: GLContext) {...}{.importc: "SDL_GL_DeleteContext", cdecl.}-
\brief Delete an OpenGL context.
\sa SDL_GL_CreateContext()
proc getKeyboardFocus(): ptr Window {...}{.importc: "SDL_GetKeyboardFocus", cdecl.}-
Function prototypes
\brief Get the window which currently has keyboard focus.
proc getKeyboardState(numkeys: ptr cint): ptr Uint8 {...}{.importc: "SDL_GetKeyboardState",
cdecl.}-
\brief Get a snapshot of the current state of the keyboard.
\param numkeys if non-NULL, receives the length of the returned array.
\return An array of key states. Indexes into this array are obtained by using ::SDL_Scancode values.
\b Example:
\code
const Uint8state = SDL_GetKeyboardState(NULL);
if ( state[SDL_SCANCODE_RETURN] ) {
printf("<RETURN> is pressed.\n");
}
\endcode
proc getModState(): Keymod {...}{.importc: "SDL_GetModState", cdecl.}-
\brief Get the current key modifier state for the keyboard.
proc setModState(modstate: Keymod) {...}{.importc: "SDL_SetModState", cdecl.}-
\brief Set the current key modifier state for the keyboard.
\note This does not change the keyboard state, only the key modifier flags.
proc getKeyFromScancode(scancode: Scancode): Keycode {...}{.
importc: "SDL_GetKeyFromScancode", cdecl.}-
\brief Get the key code corresponding to the given scancode according
to the current keyboard layout.
See ::SDL_Keycode for details.
\sa SDL_GetKeyName()
proc getScancodeFromKey(key: Keycode): Scancode {...}{.importc: "SDL_GetScancodeFromKey",
cdecl.}-
\brief Get the scancode corresponding to the given key code according to the
current keyboard layout.
See ::SDL_Scancode for details.
\sa SDL_GetScancodeName()
proc getScancodeName(scancode: Scancode): cstring {...}{.importc: "SDL_GetScancodeName",
cdecl.}-
\brief Get a human-readable name for a scancode.
\return A pointer to the name for the scancode.
If the scancode doesn't have a name, this function returns
an empty string ("").
\sa SDL_Scancode
proc getScancodeFromName(name: cstring): Scancode {...}{.
importc: "SDL_GetScancodeFromName", cdecl.}-
\brief Get a scancode from a human-readable name
\return scancode, or SDL_SCANCODE_UNKNOWN if the name wasn't recognized
\sa SDL_Scancode
proc getKeyName(key: Keycode): cstring {...}{.importc: "SDL_GetKeyName", cdecl.}-
\brief Get a human-readable name for a key.
\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 ("").
\sa SDL_Keycode
proc getKeyFromName(name: cstring): Keycode {...}{.importc: "SDL_GetKeyFromName", cdecl.}-
\brief Get a key code from a human-readable name
\return key code, or SDLK_UNKNOWN if the name wasn't recognized
\sa SDL_Keycode
proc startTextInput() {...}{.importc: "SDL_StartTextInput", cdecl.}-
\brief Start accepting Unicode text input events.
This function will show the on-screen keyboard if supported.
\sa SDL_StopTextInput()
\sa SDL_SetTextInputRect()
\sa SDL_HasScreenKeyboardSupport()
proc isTextInputActive(): bool {...}{.importc: "SDL_IsTextInputActive", cdecl.}-
\brief Return whether or not Unicode text input events are enabled.
\sa SDL_StartTextInput()
\sa SDL_StopTextInput()
proc stopTextInput() {...}{.importc: "SDL_StopTextInput", cdecl.}-
\brief Stop receiving any text input events.
This function will hide the on-screen keyboard if supported.
\sa SDL_StartTextInput()
\sa SDL_HasScreenKeyboardSupport()
proc setTextInputRect(rect: ptr Rect) {...}{.importc: "SDL_SetTextInputRect", cdecl.}-
\brief Set the rectangle used to type Unicode text inputs.
This is used as a hint for IME and on-screen keyboard placement.
\sa SDL_StartTextInput()
proc hasScreenKeyboardSupport(): bool {...}{.importc: "SDL_HasScreenKeyboardSupport",
cdecl.}-
\brief Returns whether the platform has some screen keyboard support.
\return SDL_TRUE if some keyboard support is available else SDL_FALSE.
\note Not all screen keyboard functions are supported on all platforms.
\sa SDL_IsScreenKeyboardShown()
proc isScreenKeyboardShown(window: ptr Window): bool {...}{.
importc: "SDL_IsScreenKeyboardShown", cdecl.}-
\brief Returns whether the screen keyboard is shown for given window.
\param window The window for which screen keyboard should be queried.
\return SDL_TRUE if screen keyboard is shown else SDL_FALSE.
\sa SDL_HasScreenKeyboardSupport()
proc getMouseFocus(): ptr Window {...}{.importc: "SDL_GetMouseFocus", cdecl.}-
Function prototypes
\brief Get the window which currently has mouse focus.
proc getMouseState(x: ptr cint; y: ptr cint): Uint32 {...}{.importc: "SDL_GetMouseState", cdecl.}-
\brief Retrieve the current state of the mouse.
The current button state is returned as a button bitmask, which can
be tested using the SDL_BUTTON(X) macros, and x and y are set to the
mouse cursor position relative to the focus window for the currently
selected mouse. You can pass NULL for either x or y.
proc getGlobalMouseState(x: ptr cint; y: ptr cint): Uint32 {...}{.
importc: "SDL_GetGlobalMouseState", cdecl.}-
\brief Get the current state of the mouse, in relation to the desktop
This works just like SDL_GetMouseState(), but the coordinates will be
reported relative to the top-left of the desktop. This can be useful if
you need to track the mouse outside of a specific window and
SDL_CaptureMouse() doesn't fit your needs. For example, it could be
useful if you need to track the mouse while dragging a window, where
coordinates relative to a window might not be in sync at all times.
\note SDL_GetMouseState() returns the mouse position as SDL understands
it from the last pump of the event queue. This function, however,
queries the OS for the current mouse position, and as such, might
be a slightly less efficient function. Unless you know what you're
doing and have a good reason to use this function, you probably want
SDL_GetMouseState() instead.
\param x Returns the current X coord, relative to the desktop. Can be NULL.
\param y Returns the current Y coord, relative to the desktop. Can be NULL.
\return The current button state as a bitmask, which can be tested using the SDL_BUTTON(X) macros.
\sa SDL_GetMouseState
proc getRelativeMouseState(x: ptr cint; y: ptr cint): Uint32 {...}{.
importc: "SDL_GetRelativeMouseState", cdecl.}-
\brief Retrieve the relative state of the mouse.
The current button state is returned as a button bitmask, which can
be tested using the SDL_BUTTON(X) macros, and x and y are set to the
mouse deltas since the last call to SDL_GetRelativeMouseState().
proc warpMouseInWindow(window: ptr Window; x: cint; y: cint) {...}{.
importc: "SDL_WarpMouseInWindow", cdecl.}-
\brief Moves the mouse to the given position within the window.
\param window The window to move the mouse into, or NULL for the current mouse focus
\param x The x coordinate within the window
\param y The y coordinate within the window
\note This function generates a mouse motion event
proc warpMouseGlobal(x: cint; y: cint): cint {...}{.importc: "SDL_WarpMouseGlobal", cdecl.}-
\brief Moves the mouse to the given position in global screen space.
\param x The x coordinate
\param y The y coordinate
\return 0 on success, -1 on error (usually: unsupported by a platform).
\note This function generates a mouse motion event
proc setRelativeMouseMode(enabled: bool): cint {...}{.
importc: "SDL_SetRelativeMouseMode", cdecl.}-
\brief Set relative mouse mode.
\param enabled Whether or not to enable relative mode
\return 0 on success, or -1 if relative mode is not supported.
While the mouse is in relative mode, the cursor is hidden, and the
driver will try to report continuous motion in the current window.
Only relative motion events will be delivered, the mouse position
will not change.
\note This function will flush any pending mouse motion.
\sa SDL_GetRelativeMouseMode()
proc captureMouse(enabled: bool): cint {...}{.importc: "SDL_CaptureMouse", cdecl.}-
\brief Capture the mouse, to track input outside an SDL window.
\param enabled Whether or not to enable capturing
Capturing enables your app to obtain mouse events globally, instead of
just within your window. Not all video targets support this function.
When capturing is enabled, the current window will get all mouse events,
but unlike relative mode, no change is made to the cursor and it is
not restrained to your window.
This function may also deny mouse input to other windows--both those in
your application and others on the system--so you should use this
function sparingly, and in small bursts. For example, you might want to
track the mouse while the user is dragging something, until the user
releases a mouse button. It is not recommended that you capture the mouse
for long periods of time, such as the entire time your app is running.
While captured, mouse events still report coordinates relative to the
current (foreground) window, but those coordinates may be outside the
bounds of the window (including negative values). Capturing is only
allowed for the foreground window. If the window loses focus while
capturing, the capture will be disabled automatically.
While capturing is enabled, the current window will have the
SDL_WINDOW_MOUSE_CAPTURE flag set.
\return 0 on success, or -1 if not supported.
proc getRelativeMouseMode(): bool {...}{.importc: "SDL_GetRelativeMouseMode", cdecl.}-
\brief Query whether relative mouse mode is enabled.
\sa SDL_SetRelativeMouseMode()
proc createCursor(data: ptr Uint8; mask: ptr Uint8; w: cint; h: cint; hotX: cint; hotY: cint): ptr Cursor {...}{.
importc: "SDL_CreateCursor", cdecl.}-
\brief Create a cursor, using the specified bitmap data and
mask (in MSB format).
The cursor width must be a multiple of 8 bits.
The cursor is created in black and white according to the following:
<table>
<tr><td> data </td><td> mask </td><td> resulting pixel on screen </td></tr>
<tr><td> 0 </td><td> 1 </td><td> White </td></tr>
<tr><td> 1 </td><td> 1 </td><td> Black </td></tr>
<tr><td> 0 </td><td> 0 </td><td> Transparent </td></tr>
<tr><td> 1 </td><td> 0 </td><td> Inverted color if possible, black
if not. </td></tr>
</table>
\sa SDL_FreeCursor()
proc createColorCursor(surface: ptr Surface; hotX: cint; hotY: cint): ptr Cursor {...}{.
importc: "SDL_CreateColorCursor", cdecl.}-
\brief Create a color cursor.
\sa SDL_FreeCursor()
proc createSystemCursor(id: SystemCursor): ptr Cursor {...}{.
importc: "SDL_CreateSystemCursor", cdecl.}-
\brief Create a system cursor.
\sa SDL_FreeCursor()
proc setCursor(cursor: ptr Cursor) {...}{.importc: "SDL_SetCursor", cdecl.}-
\brief Set the active cursor.
proc getCursor(): ptr Cursor {...}{.importc: "SDL_GetCursor", cdecl.}-
\brief Return the active cursor.
proc getDefaultCursor(): ptr Cursor {...}{.importc: "SDL_GetDefaultCursor", cdecl.}-
\brief Return the default cursor.
proc freeCursor(cursor: ptr Cursor) {...}{.importc: "SDL_FreeCursor", cdecl.}-
\brief Frees a cursor created with SDL_CreateCursor() or similar functions.
\sa SDL_CreateCursor()
\sa SDL_CreateColorCursor()
\sa SDL_CreateSystemCursor()
proc showCursor(toggle: cint): cint {...}{.importc: "SDL_ShowCursor", cdecl.}-
\brief Toggle whether or not the cursor is shown.
\param toggle 1 to show the cursor, 0 to hide it, -1 to query the current
state.
\return 1 if the cursor is shown, or 0 if the cursor is hidden.
proc lockJoysticks() {...}{.importc: "SDL_LockJoysticks", cdecl.}-
Function prototypes
Locking for multi-threaded access to the joystick API
If you are using the joystick API or handling events from multiple threads
you should use these locking functions to protect access to the joysticks.
In particular, you are guaranteed that the joystick list won't change, so
the API functions that take a joystick index will be valid, and joystick
and game controller events will not be delivered.
proc unlockJoysticks() {...}{.importc: "SDL_UnlockJoysticks", cdecl.}-
proc numJoysticks(): cint {...}{.importc: "SDL_NumJoysticks", cdecl.}-
Count the number of joysticks attached to the system right now
proc joystickNameForIndex(deviceIndex: cint): cstring {...}{.
importc: "SDL_JoystickNameForIndex", cdecl.}-
Get the implementation dependent name of a joystick.
This can be called before any joysticks are opened.
If no name can be found, this function returns NULL.
proc joystickGetDevicePlayerIndex(deviceIndex: cint): cint {...}{.
importc: "SDL_JoystickGetDevicePlayerIndex", cdecl.}-
Get the player index of a joystick, or -1 if it's not available
This can be called before any joysticks are opened.
proc joystickGetDeviceGUID(deviceIndex: cint): JoystickGUID {...}{.
importc: "SDL_JoystickGetDeviceGUID", cdecl.}-
Return the GUID for the joystick at this index
This can be called before any joysticks are opened.
proc joystickGetDeviceVendor(deviceIndex: cint): Uint16 {...}{.
importc: "SDL_JoystickGetDeviceVendor", cdecl.}-
Get the USB vendor ID of a joystick, if available.
This can be called before any joysticks are opened.
If the vendor ID isn't available this function returns 0.
proc joystickGetDeviceProduct(deviceIndex: cint): Uint16 {...}{.
importc: "SDL_JoystickGetDeviceProduct", cdecl.}-
Get the USB product ID of a joystick, if available.
This can be called before any joysticks are opened.
If the product ID isn't available this function returns 0.
proc joystickGetDeviceProductVersion(deviceIndex: cint): Uint16 {...}{.
importc: "SDL_JoystickGetDeviceProductVersion", cdecl.}-
Get the product version of a joystick, if available.
This can be called before any joysticks are opened.
If the product version isn't available this function returns 0.
proc joystickGetDeviceType(deviceIndex: cint): JoystickType {...}{.
importc: "SDL_JoystickGetDeviceType", cdecl.}-
Get the type of a joystick, if available.
This can be called before any joysticks are opened.
proc joystickGetDeviceInstanceID(deviceIndex: cint): JoystickID {...}{.
importc: "SDL_JoystickGetDeviceInstanceID", cdecl.}-
Get the instance ID of a joystick.
This can be called before any joysticks are opened.
If the index is out of range, this function will return -1.
proc joystickOpen(deviceIndex: cint): ptr Joystick {...}{.importc: "SDL_JoystickOpen", cdecl.}-
Open a joystick for use.
The index passed as an argument refers to the N'th joystick on the system.
This index is not the value which will identify this joystick in future
joystick events. The joystick's instance id (::SDL_JoystickID) will be used
there instead.
\return A joystick identifier, or NULL if an error occurred.
proc joystickFromInstanceID(instanceId: JoystickID): ptr Joystick {...}{.
importc: "SDL_JoystickFromInstanceID", cdecl.}-
Return the SDL_Joystick associated with an instance id.
proc joystickFromPlayerIndex(playerIndex: cint): ptr Joystick {...}{.
importc: "SDL_JoystickFromPlayerIndex", cdecl.}-
Return the SDL_Joystick associated with a player index.
proc joystickName(joystick: ptr Joystick): cstring {...}{.importc: "SDL_JoystickName", cdecl.}-
Return the name for this currently opened joystick.
If no name can be found, this function returns NULL.
proc joystickGetPlayerIndex(joystick: ptr Joystick): cint {...}{.
importc: "SDL_JoystickGetPlayerIndex", cdecl.}-
Get the player index of an opened joystick, or -1 if it's not available
For XInput controllers this returns the XInput user index.
proc joystickSetPlayerIndex(joystick: ptr Joystick; playerIndex: cint) {...}{.
importc: "SDL_JoystickSetPlayerIndex", cdecl.}-
Set the player index of an opened joystick
proc joystickGetGUID(joystick: ptr Joystick): JoystickGUID {...}{.
importc: "SDL_JoystickGetGUID", cdecl.}-
Return the GUID for this opened joystick
proc joystickGetVendor(joystick: ptr Joystick): Uint16 {...}{.
importc: "SDL_JoystickGetVendor", cdecl.}-
Get the USB vendor ID of an opened joystick, if available.
If the vendor ID isn't available this function returns 0.
proc joystickGetProduct(joystick: ptr Joystick): Uint16 {...}{.
importc: "SDL_JoystickGetProduct", cdecl.}-
Get the USB product ID of an opened joystick, if available.
If the product ID isn't available this function returns 0.
proc joystickGetProductVersion(joystick: ptr Joystick): Uint16 {...}{.
importc: "SDL_JoystickGetProductVersion", cdecl.}-
Get the product version of an opened joystick, if available.
If the product version isn't available this function returns 0.
proc joystickGetType(joystick: ptr Joystick): JoystickType {...}{.
importc: "SDL_JoystickGetType", cdecl.}-
Get the type of an opened joystick.
proc joystickGetGUIDString(guid: JoystickGUID; pszGUID: cstring; cbGUID: cint) {...}{.
importc: "SDL_JoystickGetGUIDString", cdecl.}-
Return a string representation for this guid. pszGUID must point to at least 33 bytes
(32 for the string plus a NULL terminator).
proc joystickGetGUIDFromString(pchGUID: cstring): JoystickGUID {...}{.
importc: "SDL_JoystickGetGUIDFromString", cdecl.}-
Convert a string into a joystick guid
proc joystickGetAttached(joystick: ptr Joystick): bool {...}{.
importc: "SDL_JoystickGetAttached", cdecl.}-
Returns SDL_TRUE if the joystick has been opened and currently connected, or SDL_FALSE if it has not.
proc joystickInstanceID(joystick: ptr Joystick): JoystickID {...}{.
importc: "SDL_JoystickInstanceID", cdecl.}-
Get the instance ID of an opened joystick or -1 if the joystick is invalid.
proc joystickNumAxes(joystick: ptr Joystick): cint {...}{.importc: "SDL_JoystickNumAxes",
cdecl.}-
Get the number of general axis controls on a joystick.
proc joystickNumBalls(joystick: ptr Joystick): cint {...}{.
importc: "SDL_JoystickNumBalls", cdecl.}-
Get the number of trackballs on a joystick.
Joystick trackballs have only relative motion events associated
with them and their state cannot be polled.
proc joystickNumHats(joystick: ptr Joystick): cint {...}{.importc: "SDL_JoystickNumHats",
cdecl.}-
Get the number of POV hats on a joystick.
proc joystickNumButtons(joystick: ptr Joystick): cint {...}{.
importc: "SDL_JoystickNumButtons", cdecl.}-
Get the number of buttons on a joystick.
proc joystickUpdate() {...}{.importc: "SDL_JoystickUpdate", cdecl.}-
Update the current state of the open joysticks.
This is called automatically by the event loop if any joystick
events are enabled.
proc joystickEventState(state: cint): cint {...}{.importc: "SDL_JoystickEventState", cdecl.}-
Enable/disable joystick event polling.
If joystick events are disabled, you must call SDL_JoystickUpdate()
yourself and check the state of the joystick when you want joystick
information.
The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE.
proc joystickGetAxis(joystick: ptr Joystick; axis: cint): Sint16 {...}{.
importc: "SDL_JoystickGetAxis", cdecl.}-
Get the current state of an axis control on a joystick.
The state is a value ranging from -32768 to 32767.
The axis indices start at index 0.
proc joystickGetAxisInitialState(joystick: ptr Joystick; axis: cint; state: ptr Sint16): bool {...}{.
importc: "SDL_JoystickGetAxisInitialState", cdecl.}-
Get the initial state of an axis control on a joystick.
The state is a value ranging from -32768 to 32767.
The axis indices start at index 0.
\return SDL_TRUE if this axis has any initial value, or SDL_FALSE if not.
proc joystickGetHat(joystick: ptr Joystick; hat: cint): Uint8 {...}{.
importc: "SDL_JoystickGetHat", cdecl.}-
@}
Get the current state of a POV hat on a joystick.
The hat indices start at index 0.
\return The return value is one of the following positions:
- ::SDL_HAT_CENTERED
- ::SDL_HAT_UP
- ::SDL_HAT_RIGHT
- ::SDL_HAT_DOWN
- ::SDL_HAT_LEFT
- ::SDL_HAT_RIGHTUP
- ::SDL_HAT_RIGHTDOWN
- ::SDL_HAT_LEFTUP
- ::SDL_HAT_LEFTDOWN
proc joystickGetBall(joystick: ptr Joystick; ball: cint; dx: ptr cint; dy: ptr cint): cint {...}{.
importc: "SDL_JoystickGetBall", cdecl.}-
Get the ball axis change since the last poll.
\return 0, or -1 if you passed it invalid parameters.
The ball indices start at index 0.
proc joystickGetButton(joystick: ptr Joystick; button: cint): Uint8 {...}{.
importc: "SDL_JoystickGetButton", cdecl.}-
Get the current state of a button on a joystick.
The button indices start at index 0.
proc joystickRumble(joystick: ptr Joystick; lowFrequencyRumble: Uint16;
highFrequencyRumble: Uint16; durationMs: Uint32): cint {...}{.
importc: "SDL_JoystickRumble", cdecl.}-
Trigger a rumble effect
Each call to this function cancels any previous rumble effect, and calling it with 0 intensity stops any rumbling.
\param joystick The joystick 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
\return 0, or -1 if rumble isn't supported on this joystick
proc joystickClose(joystick: ptr Joystick) {...}{.importc: "SDL_JoystickClose", cdecl.}-
Close a joystick previously opened with SDL_JoystickOpen().
proc joystickCurrentPowerLevel(joystick: ptr Joystick): JoystickPowerLevel {...}{.
importc: "SDL_JoystickCurrentPowerLevel", cdecl.}-
Return the battery level of this joystick
proc gameControllerAddMappingsFromRW(rw: ptr RWops; freerw: cint): cint {...}{.
importc: "SDL_GameControllerAddMappingsFromRW", cdecl.}-
To count the number of game controllers in the system for the following:
int nJoysticks = SDL_NumJoysticks();
int nGameControllers = 0;
for (int i = 0; i < nJoysticks; i++) {
if (SDL_IsGameController(i)) {
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
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 any 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 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",
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
If \c freerw is non-zero, the stream will be closed after being read.
\return number of mappings added, -1 on error
proc gameControllerAddMapping(mappingString: cstring): cint {...}{.
importc: "SDL_GameControllerAddMapping", cdecl.}-
Add or update an existing mapping configuration
\return 1 if mapping is added, 0 if updated, -1 on error
proc gameControllerNumMappings(): cint {...}{.importc: "SDL_GameControllerNumMappings",
cdecl.}-
Get the number of mappings installed
\return the number of mappings
proc gameControllerMappingForIndex(mappingIndex: cint): cstring {...}{.
importc: "SDL_GameControllerMappingForIndex", cdecl.}-
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.
proc gameControllerMappingForGUID(guid: JoystickGUID): cstring {...}{.
importc: "SDL_GameControllerMappingForGUID", cdecl.}-
Get a mapping string for a GUID
\return the mapping string. Must be freed with SDL_free(). Returns NULL if no mapping is available
proc gameControllerMapping(gamecontroller: ptr GameController): cstring {...}{.
importc: "SDL_GameControllerMapping", cdecl.}-
Get a mapping string for an open GameController
\return the mapping string. Must be freed with SDL_free(). Returns NULL if no mapping is available
proc isGameController(joystickIndex: cint): bool {...}{.importc: "SDL_IsGameController",
cdecl.}-
Is the joystick on this index supported by the game controller interface?
proc gameControllerNameForIndex(joystickIndex: cint): cstring {...}{.
importc: "SDL_GameControllerNameForIndex", cdecl.}-
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.
proc gameControllerTypeForIndex(joystickIndex: cint): GameControllerType {...}{.
importc: "SDL_GameControllerTypeForIndex", cdecl.}-
Get the type of a game controller.
This can be called before any controllers are opened.
proc gameControllerMappingForDeviceIndex(joystickIndex: cint): cstring {...}{.
importc: "SDL_GameControllerMappingForDeviceIndex", cdecl.}-
Get the mapping of a game controller.
This can be called before any controllers are opened.
\return the mapping string. Must be freed with SDL_free(). Returns NULL if no mapping is available
proc gameControllerOpen(joystickIndex: cint): ptr GameController {...}{.
importc: "SDL_GameControllerOpen", cdecl.}-
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.
\return A controller identifier, or NULL if an error occurred.
proc gameControllerFromInstanceID(joyid: JoystickID): ptr GameController {...}{.
importc: "SDL_GameControllerFromInstanceID", cdecl.}-
Return the SDL_GameController associated with an instance id.
proc gameControllerFromPlayerIndex(playerIndex: cint): ptr GameController {...}{.
importc: "SDL_GameControllerFromPlayerIndex", cdecl.}-
Return the SDL_GameController associated with a player index.
proc gameControllerName(gamecontroller: ptr GameController): cstring {...}{.
importc: "SDL_GameControllerName", cdecl.}-
Return the name for this currently opened controller
proc gameControllerGetType(gamecontroller: ptr GameController): GameControllerType {...}{.
importc: "SDL_GameControllerGetType", cdecl.}-
Return the type of this currently opened controller
proc gameControllerGetPlayerIndex(gamecontroller: ptr GameController): cint {...}{.
importc: "SDL_GameControllerGetPlayerIndex", cdecl.}-
Get the player index of an opened game controller, or -1 if it's not available
For XInput controllers this returns the XInput user index.
proc gameControllerSetPlayerIndex(gamecontroller: ptr GameController;
playerIndex: cint) {...}{.
importc: "SDL_GameControllerSetPlayerIndex", cdecl.}-
Set the player index of an opened game controller
proc gameControllerGetVendor(gamecontroller: ptr GameController): Uint16 {...}{.
importc: "SDL_GameControllerGetVendor", cdecl.}-
Get the USB vendor ID of an opened controller, if available.
If the vendor ID isn't available this function returns 0.
proc gameControllerGetProduct(gamecontroller: ptr GameController): Uint16 {...}{.
importc: "SDL_GameControllerGetProduct", cdecl.}-
Get the USB product ID of an opened controller, if available.
If the product ID isn't available this function returns 0.
proc gameControllerGetProductVersion(gamecontroller: ptr GameController): Uint16 {...}{.
importc: "SDL_GameControllerGetProductVersion", cdecl.}-
Get the product version of an opened controller, if available.
If the product version isn't available this function returns 0.
proc gameControllerGetAttached(gamecontroller: ptr GameController): bool {...}{.
importc: "SDL_GameControllerGetAttached", cdecl.}-
Returns SDL_TRUE if the controller has been opened and currently connected,
or SDL_FALSE if it has not.
proc gameControllerGetJoystick(gamecontroller: ptr GameController): ptr Joystick {...}{.
importc: "SDL_GameControllerGetJoystick", cdecl.}-
Get the underlying joystick object used by a controller
proc gameControllerEventState(state: cint): cint {...}{.
importc: "SDL_GameControllerEventState", cdecl.}-
Enable/disable controller event polling.
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.
proc gameControllerUpdate() {...}{.importc: "SDL_GameControllerUpdate", cdecl.}-
Update the current state of the open game controllers.
This is called automatically by the event loop if any game controller
events are enabled.
proc gameControllerGetAxisFromString(pchString: cstring): GameControllerAxis {...}{.
importc: "SDL_GameControllerGetAxisFromString", cdecl.}-
turn this string into a axis mapping
proc gameControllerGetStringForAxis(axis: GameControllerAxis): cstring {...}{.
importc: "SDL_GameControllerGetStringForAxis", cdecl.}-
turn this axis enum into a string mapping
proc gameControllerGetBindForAxis(gamecontroller: ptr GameController;
axis: GameControllerAxis): GameControllerButtonBind {...}{.
importc: "SDL_GameControllerGetBindForAxis", cdecl.}-
Get the SDL joystick layer binding for this controller button mapping
proc gameControllerGetAxis(gamecontroller: ptr GameController;
axis: GameControllerAxis): Sint16 {...}{.
importc: "SDL_GameControllerGetAxis", cdecl.}-
Get the current state of an axis control on a game controller.
The state is a value ranging from -32768 to 32767 (except for the triggers,
which range from 0 to 32767).
The axis indices start at index 0.
proc gameControllerGetButtonFromString(pchString: cstring): GameControllerButton {...}{.
importc: "SDL_GameControllerGetButtonFromString", cdecl.}-
turn this string into a button mapping
proc gameControllerGetStringForButton(button: GameControllerButton): cstring {...}{.
importc: "SDL_GameControllerGetStringForButton", cdecl.}-
turn this button enum into a string mapping
proc gameControllerGetBindForButton(gamecontroller: ptr GameController;
button: GameControllerButton): GameControllerButtonBind {...}{.
importc: "SDL_GameControllerGetBindForButton", cdecl.}-
Get the SDL joystick layer binding for this controller button mapping
proc gameControllerGetButton(gamecontroller: ptr GameController;
button: GameControllerButton): Uint8 {...}{.
importc: "SDL_GameControllerGetButton", cdecl.}-
Get the current state of a button on a game controller.
The button indices start at index 0.
proc gameControllerRumble(gamecontroller: ptr GameController;
lowFrequencyRumble: Uint16; highFrequencyRumble: Uint16;
durationMs: Uint32): cint {...}{.
importc: "SDL_GameControllerRumble", cdecl.}-
Trigger a rumble effect
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
\return 0, or -1 if rumble isn't supported on this joystick
proc gameControllerClose(gamecontroller: ptr GameController) {...}{.
importc: "SDL_GameControllerClose", cdecl.}-
Close a controller previously opened with SDL_GameControllerOpen().
proc getNumTouchDevices(): cint {...}{.importc: "SDL_GetNumTouchDevices", cdecl.}-
Function prototypes
\brief Get the number of registered touch devices.
proc getTouchDevice(index: cint): TouchID {...}{.importc: "SDL_GetTouchDevice", cdecl.}-
\brief Get the touch ID with the given index, or 0 if the index is invalid.
proc getTouchDeviceType(touchID: TouchID): TouchDeviceType {...}{.
importc: "SDL_GetTouchDeviceType", cdecl.}-
\brief Get the type of the given touch device.
proc getNumTouchFingers(touchID: TouchID): cint {...}{.importc: "SDL_GetNumTouchFingers",
cdecl.}-
\brief Get the number of active fingers for a given touch device.
proc getTouchFinger(touchID: TouchID; index: cint): ptr Finger {...}{.
importc: "SDL_GetTouchFinger", cdecl.}-
\brief Get the finger object of the given touch, with the given index.
proc recordGesture(touchId: TouchID): cint {...}{.importc: "SDL_RecordGesture", cdecl.}-
Function prototypes
\brief Begin Recording a gesture on the specified touch, or all touches (-1)
proc saveAllDollarTemplates(dst: ptr RWops): cint {...}{.
importc: "SDL_SaveAllDollarTemplates", cdecl.}-
\brief Save all currently loaded Dollar Gesture templates
proc saveDollarTemplate(gestureId: GestureID; dst: ptr RWops): cint {...}{.
importc: "SDL_SaveDollarTemplate", cdecl.}-
\brief Save a currently loaded Dollar Gesture template
proc loadDollarTemplates(touchId: TouchID; src: ptr RWops): cint {...}{.
importc: "SDL_LoadDollarTemplates", cdecl.}-
\brief Load Dollar Gesture templates from a file
proc pumpEvents() {...}{.importc: "SDL_PumpEvents", cdecl.}-
Function prototypes
Pumps the event loop, gathering events from the input devices.
This function updates the event queue and internal input device state.
This should only be run in the thread that sets the video mode.
proc peepEvents(events: ptr Event; numevents: cint; action: eventaction;
minType: Uint32; maxType: Uint32): cint {...}{.importc: "SDL_PeepEvents",
cdecl.}-
Checks the event queue for messages and optionally returns them.
If \c action is ::SDL_ADDEVENT, up to \c numevents events will be added to
the back of the event queue.
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.
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.
\return The number of events actually stored, or -1 if there was an error.
This function is thread-safe.
proc hasEvent(kind: Uint32): bool {...}{.importc: "SDL_HasEvent", cdecl.}-
@}
Checks to see if certain event types are in the event queue.
proc hasEvents(minType: Uint32; maxType: Uint32): bool {...}{.importc: "SDL_HasEvents", cdecl.}-
proc flushEvent(kind: Uint32) {...}{.importc: "SDL_FlushEvent", cdecl.}-
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.
proc flushEvents(minType: Uint32; maxType: Uint32) {...}{.importc: "SDL_FlushEvents", cdecl.}-
proc pollEvent(event: ptr Event): cint {...}{.importc: "SDL_PollEvent", cdecl.}-
\brief Polls for currently pending events.
\return 1 if there are any pending events, or 0 if there are none available.
\param event If not NULL, the next event is removed from the queue and
stored in that area.
proc waitEvent(event: ptr Event): cint {...}{.importc: "SDL_WaitEvent", cdecl.}-
\brief Waits indefinitely for the next available event.
\return 1, or 0 if there was an error while waiting for events.
\param event If not NULL, the next event is removed from the queue and
stored in that area.
proc waitEventTimeout(event: ptr Event; timeout: cint): cint {...}{.
importc: "SDL_WaitEventTimeout", cdecl.}-
\brief Waits until the specified timeout (in milliseconds) for the next
available event.
\return 1, or 0 if there was an error while waiting for events.
\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.
proc pushEvent(event: ptr Event): cint {...}{.importc: "SDL_PushEvent", cdecl.}-
\brief 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.
proc setEventFilter(filter: EventFilter; userdata: pointer) {...}{.
importc: "SDL_SetEventFilter", cdecl.}-
Sets 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(voiduserdata, SDL_Event event);
\endcode
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!
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.
proc getEventFilter(filter: ptr EventFilter; userdata: ptr pointer): bool {...}{.
importc: "SDL_GetEventFilter", cdecl.}-
Return the current event filter - can be used to "chain" filters.
If there is no event filter set, this function returns SDL_FALSE.
proc addEventWatch(filter: EventFilter; userdata: pointer) {...}{.
importc: "SDL_AddEventWatch", cdecl.}-
Add a function which is called when an event is added to the queue.
proc delEventWatch(filter: EventFilter; userdata: pointer) {...}{.
importc: "SDL_DelEventWatch", cdecl.}-
Remove an event watch function added with SDL_AddEventWatch()
proc filterEvents(filter: EventFilter; userdata: pointer) {...}{.
importc: "SDL_FilterEvents", cdecl.}-
Run the filter function on the current event queue, removing any
events for which the filter returns 0.
proc eventState(kind: Uint32; state: cint): Uint8 {...}{.importc: "SDL_EventState", cdecl.}-
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.
proc registerEvents(numevents: cint): Uint32 {...}{.importc: "SDL_RegisterEvents", cdecl.}-
This function allocates a set of user-defined events, and returns
the beginning event number for that set of events.
If there aren't enough user-defined events left, this function
returns (Uint32)-1
proc getBasePath(): cstring {...}{.importc: "SDL_GetBasePath", cdecl.}-
Some compilers use a special export keyword
By default SDL uses the C calling convention
Removed DECLSPEC on Symbian OS because SDL cannot be a DLL in EPOC
Force structure packing at 4 byte alignment.
This is necessary if the header is included in code which has structure
packing set to an alternate value, say for loading structures from disk.
The packing is reset to the previous value in close_code.h
Apparently this is needed by several Windows compilers
Set up for C function definitions, even when using C++
\brief Get the path where the application resides.
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 returns an absolute path in UTF-8 encoding, and is guaranteed to
end with a path separator ('\\' on Windows, '/' most other places).
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.
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.
\return String of base dir in UTF-8 encoding, or NULL on error.
\sa SDL_GetPrefPath
proc getPrefPath(org: cstring; app: cstring): cstring {...}{.importc: "SDL_GetPrefPath",
cdecl.}-
\brief 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.
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\\"
On Linux, the string might look like:
"/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.)
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.
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.
This returns an absolute path in UTF-8 encoding, and is guaranteed to
end with a path separator ('\\' on Windows, '/' most other places).
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.
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).
Some platforms can't determine the pref path, and on other
platforms, this might be meaningless. In such cases, this function will
return NULL.
\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
proc numHaptics(): cint {...}{.importc: "SDL_NumHaptics", cdecl.}-
Function prototypes
\brief Count the number of haptic devices attached to the system.
\return Number of haptic devices detected on the system.
proc hapticName(deviceIndex: cint): cstring {...}{.importc: "SDL_HapticName", cdecl.}-
\brief 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.
\param device_index Index of the device to get its name.
\return Name of the device or NULL on error.
\sa SDL_NumHaptics
proc hapticOpen(deviceIndex: cint): ptr Haptic {...}{.importc: "SDL_HapticOpen", cdecl.}-
\brief Opens a haptic device for use.
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().
\param device_index Index of the device to open.
\return Device identifier or NULL on error.
\sa SDL_HapticIndex
\sa SDL_HapticOpenFromMouse
\sa SDL_HapticOpenFromJoystick
\sa SDL_HapticClose
\sa SDL_HapticSetGain
\sa SDL_HapticSetAutocenter
\sa SDL_HapticPause
\sa SDL_HapticStopAll
proc hapticOpened(deviceIndex: cint): cint {...}{.importc: "SDL_HapticOpened", cdecl.}-
\brief Checks if the haptic device at 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.
\sa SDL_HapticOpen
\sa SDL_HapticIndex
proc hapticIndex(haptic: ptr Haptic): cint {...}{.importc: "SDL_HapticIndex", cdecl.}-
\brief Gets 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.
\sa SDL_HapticOpen
\sa SDL_HapticOpened
proc mouseIsHaptic(): cint {...}{.importc: "SDL_MouseIsHaptic", cdecl.}-
\brief Gets whether or not the current mouse has haptic capabilities.
\return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
\sa SDL_HapticOpenFromMouse
proc hapticOpenFromMouse(): ptr Haptic {...}{.importc: "SDL_HapticOpenFromMouse", cdecl.}-
\brief Tries to open a haptic device from the current mouse.
\return The haptic device identifier or NULL on error.
\sa SDL_MouseIsHaptic
\sa SDL_HapticOpen
proc joystickIsHaptic(joystick: ptr Joystick): cint {...}{.
importc: "SDL_JoystickIsHaptic", cdecl.}-
\brief Checks to see 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.
\sa SDL_HapticOpenFromJoystick
proc hapticOpenFromJoystick(joystick: ptr Joystick): ptr Haptic {...}{.
importc: "SDL_HapticOpenFromJoystick", cdecl.}-
\brief Opens 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.
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.
\param joystick Joystick to create a haptic device from.
\return A valid haptic device identifier on success or NULL on error.
\sa SDL_HapticOpen
\sa SDL_HapticClose
proc hapticClose(haptic: ptr Haptic) {...}{.importc: "SDL_HapticClose", cdecl.}-
\brief Closes a haptic device previously opened with SDL_HapticOpen().
\param haptic Haptic device to close.
proc hapticNumEffects(haptic: ptr Haptic): cint {...}{.importc: "SDL_HapticNumEffects",
cdecl.}-
\brief Returns 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().
\param haptic The haptic device to query effect max.
\return The number of effects the haptic device can store or
-1 on error.
\sa SDL_HapticNumEffectsPlaying
\sa SDL_HapticQuery
proc hapticNumEffectsPlaying(haptic: ptr Haptic): cint {...}{.
importc: "SDL_HapticNumEffectsPlaying", cdecl.}-
\brief Returns 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.
\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.
\sa SDL_HapticNumEffects
\sa SDL_HapticQuery
proc hapticQuery(haptic: ptr Haptic): cuint {...}{.importc: "SDL_HapticQuery", cdecl.}-
\brief Gets 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 haptic device to query.
\return Haptic features in bitwise manner (OR'd).
\sa SDL_HapticNumEffects
\sa SDL_HapticEffectSupported
proc hapticNumAxes(haptic: ptr Haptic): cint {...}{.importc: "SDL_HapticNumAxes", cdecl.}-
\brief Gets the number of haptic axes the device has.
\sa SDL_HapticDirection
proc hapticEffectSupported(haptic: ptr Haptic; effect: ptr HapticEffect): cint {...}{.
importc: "SDL_HapticEffectSupported", cdecl.}-
\brief Checks to see if effect is supported by haptic.
\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.
\sa SDL_HapticQuery
\sa SDL_HapticNewEffect
proc hapticNewEffect(haptic: ptr Haptic; effect: ptr HapticEffect): cint {...}{.
importc: "SDL_HapticNewEffect", cdecl.}-
\brief Creates a new haptic effect on the 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.
\sa SDL_HapticUpdateEffect
\sa SDL_HapticRunEffect
\sa SDL_HapticDestroyEffect
proc hapticUpdateEffect(haptic: ptr Haptic; effect: cint; data: ptr HapticEffect): cint {...}{.
importc: "SDL_HapticUpdateEffect", cdecl.}-
\brief Updates 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().
\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.
\sa SDL_HapticNewEffect
\sa SDL_HapticRunEffect
\sa SDL_HapticDestroyEffect
proc hapticRunEffect(haptic: ptr Haptic; effect: cint; iterations: Uint32): cint {...}{.
importc: "SDL_HapticRunEffect", cdecl.}-
\brief Runs 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.
\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.
\sa SDL_HapticStopEffect
\sa SDL_HapticDestroyEffect
\sa SDL_HapticGetEffectStatus
proc hapticStopEffect(haptic: ptr Haptic; effect: cint): cint {...}{.
importc: "SDL_HapticStopEffect", cdecl.}-
\brief Stops 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
proc hapticDestroyEffect(haptic: ptr Haptic; effect: cint) {...}{.
importc: "SDL_HapticDestroyEffect", cdecl.}-
\brief Destroys a haptic effect on the device.
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.
\sa SDL_HapticNewEffect
proc hapticGetEffectStatus(haptic: ptr Haptic; effect: cint): cint {...}{.
importc: "SDL_HapticGetEffectStatus", cdecl.}-
\brief Gets the status of the current effect on the haptic device.
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.
\sa SDL_HapticRunEffect
\sa SDL_HapticStopEffect
proc hapticSetGain(haptic: ptr Haptic; gain: cint): cint {...}{.
importc: "SDL_HapticSetGain", cdecl.}-
\brief Sets the global gain of the device.
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.
\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.
\sa SDL_HapticQuery
proc hapticSetAutocenter(haptic: ptr Haptic; autocenter: cint): cint {...}{.
importc: "SDL_HapticSetAutocenter", cdecl.}-
\brief Sets the global autocenter of the device.
Autocenter should be between 0 and 100. Setting it to 0 will disable
autocentering.
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.
\sa SDL_HapticQuery
proc hapticPause(haptic: ptr Haptic): cint {...}{.importc: "SDL_HapticPause", cdecl.}-
\brief Pauses a haptic device.
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.
\param haptic Haptic device to pause.
\return 0 on success or -1 on error.
\sa SDL_HapticUnpause
proc hapticUnpause(haptic: ptr Haptic): cint {...}{.importc: "SDL_HapticUnpause", cdecl.}-
\brief Unpauses a haptic device.
Call to unpause after SDL_HapticPause().
\param haptic Haptic device to unpause.
\return 0 on success or -1 on error.
\sa SDL_HapticPause
proc hapticStopAll(haptic: ptr Haptic): cint {...}{.importc: "SDL_HapticStopAll", cdecl.}-
\brief Stops all the currently playing effects on a haptic device.
\param haptic Haptic device to stop.
\return 0 on success or -1 on error.
proc hapticRumbleSupported(haptic: ptr Haptic): cint {...}{.
importc: "SDL_HapticRumbleSupported", cdecl.}-
\brief Checks to see if 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.
\sa SDL_HapticRumbleInit
\sa SDL_HapticRumblePlay
\sa SDL_HapticRumbleStop
proc hapticRumbleInit(haptic: ptr Haptic): cint {...}{.importc: "SDL_HapticRumbleInit",
cdecl.}-
\brief Initializes the haptic device for simple rumble playback.
\param haptic Haptic device to initialize for simple rumble playback.
\return 0 on success or -1 on error.
\sa SDL_HapticOpen
\sa SDL_HapticRumbleSupported
\sa SDL_HapticRumblePlay
\sa SDL_HapticRumbleStop
proc hapticRumblePlay(haptic: ptr Haptic; strength: cfloat; length: Uint32): cint {...}{.
importc: "SDL_HapticRumblePlay", cdecl.}-
\brief Runs simple rumble 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.
\sa SDL_HapticRumbleSupported
\sa SDL_HapticRumbleInit
\sa SDL_HapticRumbleStop
proc hapticRumbleStop(haptic: ptr Haptic): cint {...}{.importc: "SDL_HapticRumbleStop",
cdecl.}-
\brief Stops the simple rumble on a haptic device.
\param haptic Haptic to stop the rumble on.
\return 0 on success or -1 on error.
\sa SDL_HapticRumbleSupported
\sa SDL_HapticRumbleInit
\sa SDL_HapticRumblePlay
proc setHintWithPriority(name: cstring; value: cstring; priority: HintPriority): bool {...}{.
importc: "SDL_SetHintWithPriority", cdecl.}-
\brief Set a hint with a specific priority
The priority controls the behavior when setting a hint that already
has a value. Hints will replace existing hints of their priority and
lower. Environment variables are considered to have override priority.
\return SDL_TRUE if the hint was set, SDL_FALSE otherwise
proc setHint(name: cstring; value: cstring): bool {...}{.importc: "SDL_SetHint", cdecl.}-
\brief Set a hint with normal priority
\return SDL_TRUE if the hint was set, SDL_FALSE otherwise
proc getHint(name: cstring): cstring {...}{.importc: "SDL_GetHint", cdecl.}-
\brief Get a hint
\return The string value of a hint variable.
proc getHintBoolean(name: cstring; defaultValue: bool): bool {...}{.
importc: "SDL_GetHintBoolean", cdecl.}-
\brief Get a hint
\return The boolean value of a hint variable.
proc addHintCallback(name: cstring; callback: HintCallback; userdata: pointer) {...}{.
importc: "SDL_AddHintCallback", cdecl.}-
\brief Add a function to watch a particular hint
\param name The hint to watch
\param callback The function to call when the hint value changes
\param userdata A pointer to pass to the callback function
proc delHintCallback(name: cstring; callback: HintCallback; userdata: pointer) {...}{.
importc: "SDL_DelHintCallback", cdecl.}-
\brief Remove a function watching a particular hint
\param name The hint being watched
\param callback The function being called when the hint value changes
\param userdata A pointer being passed to the callback function
proc clearHints() {...}{.importc: "SDL_ClearHints", cdecl.}-
\brief Clear all hints
This function is called during SDL_Quit() to free stored hints.
proc loadObject(sofile: cstring): pointer {...}{.importc: "SDL_LoadObject", cdecl.}-
Some compilers use a special export keyword
By default SDL uses the C calling convention
Removed DECLSPEC on Symbian OS because SDL cannot be a DLL in EPOC
Force structure packing at 4 byte alignment.
This is necessary if the header is included in code which has structure
packing set to an alternate value, say for loading structures from disk.
The packing is reset to the previous value in close_code.h
Apparently this is needed by several Windows compilers
Set up for C function definitions, even when using C++
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.
proc loadFunction(handle: pointer; name: cstring): pointer {...}{.
importc: "SDL_LoadFunction", cdecl.}-
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().
proc unloadObject(handle: pointer) {...}{.importc: "SDL_UnloadObject", cdecl.}-
Unload a shared object from memory.
proc logSetAllPriority(priority: LogPriority) {...}{.importc: "SDL_LogSetAllPriority",
cdecl.}-
\brief Set the priority of all log categories
proc logSetPriority(category: cint; priority: LogPriority) {...}{.
importc: "SDL_LogSetPriority", cdecl.}-
\brief Set the priority of a particular log category
proc logGetPriority(category: cint): LogPriority {...}{.importc: "SDL_LogGetPriority",
cdecl.}-
\brief Get the priority of a particular log category
proc logResetPriorities() {...}{.importc: "SDL_LogResetPriorities", cdecl.}-
\brief Reset all priorities to default.
\note This is called in SDL_Quit().
proc logVerbose(category: cint; fmt: cstring) {...}{.importc: "SDL_LogVerbose", cdecl,
varargs.}-
\brief Log a message with SDL_LOG_PRIORITY_VERBOSE
proc logDebug(category: cint; fmt: cstring) {...}{.importc: "SDL_LogDebug", cdecl, varargs.}-
\brief Log a message with SDL_LOG_PRIORITY_DEBUG
proc logInfo(category: cint; fmt: cstring) {...}{.importc: "SDL_LogInfo", cdecl, varargs.}-
\brief Log a message with SDL_LOG_PRIORITY_INFO
proc logWarn(category: cint; fmt: cstring) {...}{.importc: "SDL_LogWarn", cdecl, varargs.}-
\brief Log a message with SDL_LOG_PRIORITY_WARN
proc logError(category: cint; fmt: cstring) {...}{.importc: "SDL_LogError", cdecl, varargs.}-
\brief Log a message with SDL_LOG_PRIORITY_ERROR
proc logCritical(category: cint; fmt: cstring) {...}{.importc: "SDL_LogCritical", cdecl,
varargs.}-
\brief Log a message with SDL_LOG_PRIORITY_CRITICAL
proc logMessage(category: cint; priority: LogPriority; fmt: cstring) {...}{.
importc: "SDL_LogMessage", cdecl, varargs.}-
\brief Log a message with the specified category and priority.
proc logMessageV(category: cint; priority: LogPriority; fmt: cstring; ap: va_list) {...}{.
importc: "SDL_LogMessageV", cdecl.}-
\brief Log a message with the specified category and priority.
proc logGetOutputFunction(callback: ptr LogOutputFunction; userdata: ptr pointer) {...}{.
importc: "SDL_LogGetOutputFunction", cdecl.}-
\brief Get the current log output function.
proc logSetOutputFunction(callback: LogOutputFunction; userdata: pointer) {...}{.
importc: "SDL_LogSetOutputFunction", cdecl.}-
\brief This function allows you to replace the default log output
function with one of your own.
proc showMessageBox(messageboxdata: ptr MessageBoxData; buttonid: ptr cint): cint {...}{.
importc: "SDL_ShowMessageBox", cdecl.}-
\brief Create a modal message box.
\param messageboxdata The SDL_MessageBoxData structure with title, text, etc.
\param buttonid The pointer to which user id of hit button should be copied.
\return -1 on error, otherwise 0 and buttonid contains user id of button
hit or -1 if dialog was closed.
\note This function should be called on the thread that created the parent
window, or on the main thread if the messagebox has no parent. It will
block execution of that thread until the user clicks a button or
closes the messagebox.
proc showSimpleMessageBox(flags: Uint32; title: cstring; message: cstring;
window: ptr Window): cint {...}{.
importc: "SDL_ShowSimpleMessageBox", cdecl.}-
\brief Create a simple modal message box
\param flags ::SDL_MessageBoxFlags
\param title UTF-8 title text
\param message UTF-8 message text
\param window The parent window, or NULL for no parent
\return 0 on success, -1 on error
\sa SDL_ShowMessageBox
proc metal_CreateView(window: ptr Window): MetalView {...}{.
importc: "SDL_Metal_CreateView", cdecl.}-
\name Metal support functions
@{
\brief Create a CAMetalLayer-backed NSView/UIView and attach it to the
specified window.
On macOS, this doesnot associate a MTLDevice with the CAMetalLayer on its
own. It is up to user code to do that.
The returned handle can be casted directly to a NSView or UIView, and the
CAMetalLayer can be accessed from the view's 'layer' property.
\code
SDL_MetalView metalview = SDL_Metal_CreateView(window);
UIViewuiview = (__bridge UIView)metalview;
CAMetalLayermetallayer = (CAMetalLayer)uiview.layer;
[...]
SDL_Metal_DestroyView(metalview);
\endcode
\sa SDL_Metal_DestroyView
proc metal_DestroyView(view: MetalView) {...}{.importc: "SDL_Metal_DestroyView", cdecl.}-
\brief Destroy an existing SDL_MetalView object.
This should be called before SDL_DestroyWindow, if SDL_Metal_CreateView was
called after SDL_CreateWindow.
\sa SDL_Metal_CreateView
proc getPowerInfo(secs: ptr cint; pct: ptr cint): PowerState {...}{.
importc: "SDL_GetPowerInfo", cdecl.}-
\brief Get the current power supply details.
\param secs Seconds of battery life left. You can pass a NULL here if
you don't care. Will return -1 if we can't determine a
value, or we're not running on a battery.
\param pct Percentage of battery life left, between 0 and 100. You can
pass a NULL here if you don't care. Will return -1 if we
can't determine a value, or we're not running on a battery.
\return The state of the battery (if any).
proc getNumRenderDrivers(): cint {...}{.importc: "SDL_GetNumRenderDrivers", cdecl.}-
Function prototypes
\brief Get the number of 2D rendering drivers available for the current
display.
A render driver is a set of code that handles rendering and texture
management on a particular display. Normally there is only one, but
some drivers may have several available with different capabilities.
\sa SDL_GetRenderDriverInfo()
\sa SDL_CreateRenderer()
proc getRenderDriverInfo(index: cint; info: ptr RendererInfo): cint {...}{.
importc: "SDL_GetRenderDriverInfo", cdecl.}-
\brief Get information about a specific 2D rendering driver for the current
display.
\param index The index of the driver to query information about.
\param info A pointer to an SDL_RendererInfo struct to be filled with
information on the rendering driver.
\return 0 on success, -1 if the index was out of range.
\sa SDL_CreateRenderer()
proc createWindowAndRenderer(width: cint; height: cint; windowFlags: Uint32;
window: ptr ptr Window; renderer: ptr ptr Renderer): cint {...}{.
importc: "SDL_CreateWindowAndRenderer", cdecl.}-
\brief Create a window and default renderer
\param width The width of the window
\param height The height of the window
\param window_flags The flags used to create the window
\param window A pointer filled with the window, or NULL on error
\param renderer A pointer filled with the renderer, or NULL on error
\return 0 on success, or -1 on error
proc createRenderer(window: ptr Window; index: cint; flags: Uint32): ptr Renderer {...}{.
importc: "SDL_CreateRenderer", cdecl.}-
\brief Create a 2D rendering context for a window.
\param window The window where rendering is displayed.
\param index The index of the rendering driver to initialize, or -1 to
initialize the first one supporting the requested flags.
\param flags ::SDL_RendererFlags.
\return A valid rendering context or NULL if there was an error.
\sa SDL_CreateSoftwareRenderer()
\sa SDL_GetRendererInfo()
\sa SDL_DestroyRenderer()
proc createSoftwareRenderer(surface: ptr Surface): ptr Renderer {...}{.
importc: "SDL_CreateSoftwareRenderer", cdecl.}-
\brief Create a 2D software rendering context for a surface.
\param surface The surface where rendering is done.
\return A valid rendering context or NULL if there was an error.
\sa SDL_CreateRenderer()
\sa SDL_DestroyRenderer()
proc getRenderer(window: ptr Window): ptr Renderer {...}{.importc: "SDL_GetRenderer", cdecl.}-
\brief Get the renderer associated with a window.
proc getRendererInfo(renderer: ptr Renderer; info: ptr RendererInfo): cint {...}{.
importc: "SDL_GetRendererInfo", cdecl.}-
\brief Get information about a rendering context.
proc getRendererOutputSize(renderer: ptr Renderer; w: ptr cint; h: ptr cint): cint {...}{.
importc: "SDL_GetRendererOutputSize", cdecl.}-
\brief Get the output size in pixels of a rendering context.
proc createTexture(renderer: ptr Renderer; format: Uint32; access: cint; w: cint; h: cint): ptr Texture {...}{.
importc: "SDL_CreateTexture", cdecl.}-
\brief Create a texture for a rendering context.
\param renderer The renderer.
\param format The format of the texture.
\param access One of the enumerated values in ::SDL_TextureAccess.
\param w The width of the texture in pixels.
\param h The height of the texture in pixels.
\return The created texture is returned, or NULL if no rendering context was
active, the format was unsupported, or the width or height were out
of range.
\note The contents of the texture are not defined at creation.
\sa SDL_QueryTexture()
\sa SDL_UpdateTexture()
\sa SDL_DestroyTexture()
proc createTextureFromSurface(renderer: ptr Renderer; surface: ptr Surface): ptr Texture {...}{.
importc: "SDL_CreateTextureFromSurface", cdecl.}-
\brief Create a texture from an existing surface.
\param renderer The renderer.
\param surface The surface containing pixel data used to fill the texture.
\return The created texture is returned, or NULL on error.
\note The surface is not modified or freed by this function.
\sa SDL_QueryTexture()
\sa SDL_DestroyTexture()
proc queryTexture(texture: ptr Texture; format: ptr Uint32; access: ptr cint; w: ptr cint;
h: ptr cint): cint {...}{.importc: "SDL_QueryTexture", cdecl.}-
\brief Query the attributes of a texture
\param texture A texture to be queried.
\param format A pointer filled in with the raw format of the texture. The
actual format may differ, but pixel transfers will use this
format.
\param access A pointer filled in with the actual access to the texture.
\param w A pointer filled in with the width of the texture in pixels.
\param h A pointer filled in with the height of the texture in pixels.
\return 0 on success, or -1 if the texture is not valid.
proc setTextureColorMod(texture: ptr Texture; r: Uint8; g: Uint8; b: Uint8): cint {...}{.
importc: "SDL_SetTextureColorMod", cdecl.}-
\brief Set an additional color value used in render copy operations.
\param texture The texture to update.
\param r The red color value multiplied into copy operations.
\param g The green color value multiplied into copy operations.
\param b The blue color value multiplied into copy operations.
\return 0 on success, or -1 if the texture is not valid or color modulation
is not supported.
\sa SDL_GetTextureColorMod()
proc getTextureColorMod(texture: ptr Texture; r: ptr Uint8; g: ptr Uint8; b: ptr Uint8): cint {...}{.
importc: "SDL_GetTextureColorMod", cdecl.}-
\brief Get the additional color value used in render copy operations.
\param texture The texture to query.
\param r A pointer filled in with the current red color value.
\param g A pointer filled in with the current green color value.
\param b A pointer filled in with the current blue color value.
\return 0 on success, or -1 if the texture is not valid.
\sa SDL_SetTextureColorMod()
proc setTextureAlphaMod(texture: ptr Texture; alpha: Uint8): cint {...}{.
importc: "SDL_SetTextureAlphaMod", cdecl.}-
\brief Set an additional alpha value used in render copy operations.
\param texture The texture to update.
\param alpha The alpha value multiplied into copy operations.
\return 0 on success, or -1 if the texture is not valid or alpha modulation
is not supported.
\sa SDL_GetTextureAlphaMod()
proc getTextureAlphaMod(texture: ptr Texture; alpha: ptr Uint8): cint {...}{.
importc: "SDL_GetTextureAlphaMod", cdecl.}-
\brief Get the additional alpha value used in render copy operations.
\param texture The texture to query.
\param alpha A pointer filled in with the current alpha value.
\return 0 on success, or -1 if the texture is not valid.
\sa SDL_SetTextureAlphaMod()
proc setTextureBlendMode(texture: ptr Texture; blendMode: BlendMode): cint {...}{.
importc: "SDL_SetTextureBlendMode", cdecl.}-
\brief Set the blend mode used for texture copy operations.
\param texture The texture to update.
\param blendMode ::SDL_BlendMode to use for texture blending.
\return 0 on success, or -1 if the texture is not valid or the blend mode is
not supported.
\note If the blend mode is not supported, the closest supported mode is
chosen.
\sa SDL_GetTextureBlendMode()
proc getTextureBlendMode(texture: ptr Texture; blendMode: ptr BlendMode): cint {...}{.
importc: "SDL_GetTextureBlendMode", cdecl.}-
\brief Get the blend mode used for texture copy operations.
\param texture The texture to query.
\param blendMode A pointer filled in with the current blend mode.
\return 0 on success, or -1 if the texture is not valid.
\sa SDL_SetTextureBlendMode()
proc setTextureScaleMode(texture: ptr Texture; scaleMode: ScaleMode): cint {...}{.
importc: "SDL_SetTextureScaleMode", cdecl.}-
\brief Set the scale mode used for texture scale operations.
\param texture The texture to update.
\param scaleMode ::SDL_ScaleMode to use for texture scaling.
\return 0 on success, or -1 if the texture is not valid.
\note If the scale mode is not supported, the closest supported mode is
chosen.
\sa SDL_GetTextureScaleMode()
proc getTextureScaleMode(texture: ptr Texture; scaleMode: ptr ScaleMode): cint {...}{.
importc: "SDL_GetTextureScaleMode", cdecl.}-
\brief Get the scale mode used for texture scale operations.
\param texture The texture to query.
\param scaleMode A pointer filled in with the current scale mode.
\return 0 on success, or -1 if the texture is not valid.
\sa SDL_SetTextureScaleMode()
proc updateTexture(texture: ptr Texture; rect: ptr Rect; pixels: pointer; pitch: cint): cint {...}{.
importc: "SDL_UpdateTexture", cdecl.}-
\brief Update the given texture rectangle with new pixel data.
\param texture The texture to update
\param rect A pointer to the rectangle of pixels to update, or NULL to
update the entire texture.
\param pixels The raw pixel data in the format of the texture.
\param pitch The number of bytes in a row of pixel data, including padding between lines.
The pixel data must be in the format of the texture. The pixel format can be
queried with SDL_QueryTexture.
\return 0 on success, or -1 if the texture is not valid.
\note This is a fairly slow function.
proc updateYUVTexture(texture: ptr Texture; rect: ptr Rect; Yplane: ptr Uint8;
Ypitch: cint; Uplane: ptr Uint8; Upitch: cint; Vplane: ptr Uint8;
Vpitch: cint): cint {...}{.importc: "SDL_UpdateYUVTexture", cdecl.}-
\brief Update a rectangle within a planar YV12 or IYUV texture with new pixel data.
\param texture The texture to update
\param rect A pointer to the rectangle of pixels to update, or NULL to
update the entire texture.
\param Yplane The raw pixel data for the Y plane.
\param Ypitch The number of bytes between rows of pixel data for the Y plane.
\param Uplane The raw pixel data for the U plane.
\param Upitch The number of bytes between rows of pixel data for the U plane.
\param Vplane The raw pixel data for the V plane.
\param Vpitch The number of bytes between rows of pixel data for the V plane.
\return 0 on success, or -1 if the texture is not valid.
\note You can use SDL_UpdateTexture() as long as your pixel data is
a contiguous block of Y and U/V planes in the proper order, but
this function is available if your pixel data is not contiguous.
proc lockTexture(texture: ptr Texture; rect: ptr Rect; pixels: ptr pointer;
pitch: ptr cint): cint {...}{.importc: "SDL_LockTexture", cdecl.}-
\brief Lock a portion of the texture for write-only pixel access.
\param texture The texture to lock for access, which was created with
::SDL_TEXTUREACCESS_STREAMING.
\param rect A pointer to the rectangle to lock for access. If the rect
is NULL, the entire texture will be locked.
\param pixels This is filled in with a pointer to the locked pixels,
appropriately offset by the locked area.
\param pitch This is filled in with the pitch of the locked pixels.
\return 0 on success, or -1 if the texture is not valid or was not created with ::SDL_TEXTUREACCESS_STREAMING.
\sa SDL_UnlockTexture()
proc lockTextureToSurface(texture: ptr Texture; rect: ptr Rect;
surface: ptr ptr Surface): cint {...}{.
importc: "SDL_LockTextureToSurface", cdecl.}-
\brief Lock a portion of the texture for write-only pixel access.
Expose it as a SDL surface.
\param texture The texture to lock for access, which was created with
::SDL_TEXTUREACCESS_STREAMING.
\param rect A pointer to the rectangle to lock for access. If the rect
is NULL, the entire texture will be locked.
\param surface This is filled in with a SDL surface representing the locked area
Surface is freed internally after calling SDL_UnlockTexture or SDL_DestroyTexture.
\return 0 on success, or -1 if the texture is not valid or was not created with ::SDL_TEXTUREACCESS_STREAMING.
\sa SDL_UnlockTexture()
proc unlockTexture(texture: ptr Texture) {...}{.importc: "SDL_UnlockTexture", cdecl.}-
\brief Unlock a texture, uploading the changes to video memory, if needed.
If SDL_LockTextureToSurface() was called for locking, the SDL surface is freed.
\sa SDL_LockTexture()
\sa SDL_LockTextureToSurface()
proc renderTargetSupported(renderer: ptr Renderer): bool {...}{.
importc: "SDL_RenderTargetSupported", cdecl.}-
\brief Determines whether a window supports the use of render targets
\param renderer The renderer that will be checked
\return SDL_TRUE if supported, SDL_FALSE if not.
proc setRenderTarget(renderer: ptr Renderer; texture: ptr Texture): cint {...}{.
importc: "SDL_SetRenderTarget", cdecl.}-
\brief Set a texture as the current rendering target.
\param renderer The renderer.
\param texture The targeted texture, which must be created with the SDL_TEXTUREACCESS_TARGET flag, or NULL for the default render target
\return 0 on success, or -1 on error
\sa SDL_GetRenderTarget()
proc getRenderTarget(renderer: ptr Renderer): ptr Texture {...}{.
importc: "SDL_GetRenderTarget", cdecl.}-
\brief Get the current render target or NULL for the default render target.
\return The current render target
\sa SDL_SetRenderTarget()
proc renderSetLogicalSize(renderer: ptr Renderer; w: cint; h: cint): cint {...}{.
importc: "SDL_RenderSetLogicalSize", cdecl.}-
\brief Set device independent resolution for rendering
\param renderer The renderer for which resolution should be set.
\param w The width of the logical resolution
\param h The height of the logical resolution
This function uses the viewport and scaling functionality to allow a fixed logical
resolution for rendering, regardless of the actual output resolution. If the actual
output resolution doesn't have the same aspect ratio the output rendering will be
centered within the output display.
If the output display is a window, mouse events in the window will be filtered
and scaled so they seem to arrive within the logical resolution.
\note If this function results in scaling or subpixel drawing by the
rendering backend, it will be handled using the appropriate
quality hints.
\sa SDL_RenderGetLogicalSize()
\sa SDL_RenderSetScale()
\sa SDL_RenderSetViewport()
proc renderGetLogicalSize(renderer: ptr Renderer; w: ptr cint; h: ptr cint) {...}{.
importc: "SDL_RenderGetLogicalSize", cdecl.}-
\brief Get device independent resolution for rendering
\param renderer The renderer from which resolution should be queried.
\param w A pointer filled with the width of the logical resolution
\param h A pointer filled with the height of the logical resolution
\sa SDL_RenderSetLogicalSize()
proc renderSetIntegerScale(renderer: ptr Renderer; enable: bool): cint {...}{.
importc: "SDL_RenderSetIntegerScale", cdecl.}-
\brief Set whether to force integer scales for resolution-independent rendering
\param renderer The renderer for which integer scaling should be set.
\param enable Enable or disable integer scaling
This function restricts the logical viewport to integer values - that is, when
a resolution is between two multiples of a logical size, the viewport size is
rounded down to the lower multiple.
\sa SDL_RenderSetLogicalSize()
proc renderGetIntegerScale(renderer: ptr Renderer): bool {...}{.
importc: "SDL_RenderGetIntegerScale", cdecl.}-
\brief Get whether integer scales are forced for resolution-independent rendering
\param renderer The renderer from which integer scaling should be queried.
\sa SDL_RenderSetIntegerScale()
proc renderSetViewport(renderer: ptr Renderer; rect: ptr Rect): cint {...}{.
importc: "SDL_RenderSetViewport", cdecl.}-
\brief Set the drawing area for rendering on the current target.
\param renderer The renderer for which the drawing area should be set.
\param rect The rectangle representing the drawing area, or NULL to set the viewport to the entire target.
The x,y of the viewport rect represents the origin for rendering.
\return 0 on success, or -1 on error
\note If the window associated with the renderer is resized, the viewport is automatically reset.
\sa SDL_RenderGetViewport()
\sa SDL_RenderSetLogicalSize()
proc renderGetViewport(renderer: ptr Renderer; rect: ptr Rect) {...}{.
importc: "SDL_RenderGetViewport", cdecl.}-
\brief Get the drawing area for the current target.
\sa SDL_RenderSetViewport()
proc renderSetClipRect(renderer: ptr Renderer; rect: ptr Rect): cint {...}{.
importc: "SDL_RenderSetClipRect", cdecl.}-
\brief Set the clip rectangle for the current target.
\param renderer The renderer for which clip rectangle should be set.
\param rect A pointer to the rectangle to set as the clip rectangle,
relative to the viewport, or NULL to disable clipping.
\return 0 on success, or -1 on error
\sa SDL_RenderGetClipRect()
proc renderGetClipRect(renderer: ptr Renderer; rect: ptr Rect) {...}{.
importc: "SDL_RenderGetClipRect", cdecl.}-
\brief Get the clip rectangle for the current target.
\param renderer The renderer from which clip rectangle should be queried.
\param rect A pointer filled in with the current clip rectangle, or
an empty rectangle if clipping is disabled.
\sa SDL_RenderSetClipRect()
proc renderIsClipEnabled(renderer: ptr Renderer): bool {...}{.
importc: "SDL_RenderIsClipEnabled", cdecl.}-
\brief Get whether clipping is enabled on the given renderer.
\param renderer The renderer from which clip state should be queried.
\sa SDL_RenderGetClipRect()
proc renderSetScale(renderer: ptr Renderer; scaleX: cfloat; scaleY: cfloat): cint {...}{.
importc: "SDL_RenderSetScale", cdecl.}-
\brief Set the drawing scale for rendering on the current target.
\param renderer The renderer for which the drawing scale should be set.
\param scaleX The horizontal scaling factor
\param scaleY The vertical scaling factor
The drawing coordinates are scaled by the x/y scaling factors
before they are used by the renderer. This allows resolution
independent drawing with a single coordinate system.
\note If this results in scaling or subpixel drawing by the
rendering backend, it will be handled using the appropriate
quality hints. For best results use integer scaling factors.
\sa SDL_RenderGetScale()
\sa SDL_RenderSetLogicalSize()
proc renderGetScale(renderer: ptr Renderer; scaleX: ptr cfloat; scaleY: ptr cfloat) {...}{.
importc: "SDL_RenderGetScale", cdecl.}-
\brief Get the drawing scale for the current target.
\param renderer The renderer from which drawing scale should be queried.
\param scaleX A pointer filled in with the horizontal scaling factor
\param scaleY A pointer filled in with the vertical scaling factor
\sa SDL_RenderSetScale()
proc setRenderDrawColor(renderer: ptr Renderer; r: Uint8; g: Uint8; b: Uint8; a: Uint8): cint {...}{.
importc: "SDL_SetRenderDrawColor", cdecl.}-
\brief Set the color used for drawing operations (Rect, Line and Clear).
\param renderer The renderer for which drawing color should be set.
\param r The red value used to draw on the rendering target.
\param g The green value used to draw on the rendering target.
\param b The blue value used to draw on the rendering target.
\param a The alpha value used to draw on the rendering target, usually
::SDL_ALPHA_OPAQUE (255).
\return 0 on success, or -1 on error
proc getRenderDrawColor(renderer: ptr Renderer; r: ptr Uint8; g: ptr Uint8; b: ptr Uint8;
a: ptr Uint8): cint {...}{.importc: "SDL_GetRenderDrawColor", cdecl.}-
\brief Get the color used for drawing operations (Rect, Line and Clear).
\param renderer The renderer from which drawing color should be queried.
\param r A pointer to the red value used to draw on the rendering target.
\param g A pointer to the green value used to draw on the rendering target.
\param b A pointer to the blue value used to draw on the rendering target.
\param a A pointer to the alpha value used to draw on the rendering target,
usually ::SDL_ALPHA_OPAQUE (255).
\return 0 on success, or -1 on error
proc setRenderDrawBlendMode(renderer: ptr Renderer; blendMode: BlendMode): cint {...}{.
importc: "SDL_SetRenderDrawBlendMode", cdecl.}-
\brief Set the blend mode used for drawing operations (Fill and Line).
\param renderer The renderer for which blend mode should be set.
\param blendMode ::SDL_BlendMode to use for blending.
\return 0 on success, or -1 on error
\note If the blend mode is not supported, the closest supported mode is
chosen.
\sa SDL_GetRenderDrawBlendMode()
proc getRenderDrawBlendMode(renderer: ptr Renderer; blendMode: ptr BlendMode): cint {...}{.
importc: "SDL_GetRenderDrawBlendMode", cdecl.}-
\brief Get the blend mode used for drawing operations.
\param renderer The renderer from which blend mode should be queried.
\param blendMode A pointer filled in with the current blend mode.
\return 0 on success, or -1 on error
\sa SDL_SetRenderDrawBlendMode()
proc renderClear(renderer: ptr Renderer): cint {...}{.importc: "SDL_RenderClear", cdecl.}-
\brief Clear the current rendering target with the drawing color
This function clears the entire rendering target, ignoring the viewport and
the clip rectangle.
\return 0 on success, or -1 on error
proc renderDrawPoint(renderer: ptr Renderer; x: cint; y: cint): cint {...}{.
importc: "SDL_RenderDrawPoint", cdecl.}-
\brief Draw a point on the current rendering target.
\param renderer The renderer which should draw a point.
\param x The x coordinate of the point.
\param y The y coordinate of the point.
\return 0 on success, or -1 on error
proc renderDrawPoints(renderer: ptr Renderer; points: ptr Point; count: cint): cint {...}{.
importc: "SDL_RenderDrawPoints", cdecl.}-
\brief Draw multiple points on the current rendering target.
\param renderer The renderer which should draw multiple points.
\param points The points to draw
\param count The number of points to draw
\return 0 on success, or -1 on error
proc renderDrawLine(renderer: ptr Renderer; x1: cint; y1: cint; x2: cint; y2: cint): cint {...}{.
importc: "SDL_RenderDrawLine", cdecl.}-
\brief Draw a line on the current rendering target.
\param renderer The renderer which should draw a line.
\param x1 The x coordinate of the start point.
\param y1 The y coordinate of the start point.
\param x2 The x coordinate of the end point.
\param y2 The y coordinate of the end point.
\return 0 on success, or -1 on error
proc renderDrawLines(renderer: ptr Renderer; points: ptr Point; count: cint): cint {...}{.
importc: "SDL_RenderDrawLines", cdecl.}-
\brief Draw a series of connected lines on the current rendering target.
\param renderer The renderer which should draw multiple lines.
\param points The points along the lines
\param count The number of points, drawing count-1 lines
\return 0 on success, or -1 on error
proc renderDrawRect(renderer: ptr Renderer; rect: ptr Rect): cint {...}{.
importc: "SDL_RenderDrawRect", cdecl.}-
\brief Draw a rectangle on the current rendering target.
\param renderer The renderer which should draw a rectangle.
\param rect A pointer to the destination rectangle, or NULL to outline the entire rendering target.
\return 0 on success, or -1 on error
proc renderDrawRects(renderer: ptr Renderer; rects: ptr Rect; count: cint): cint {...}{.
importc: "SDL_RenderDrawRects", cdecl.}-
\brief Draw some number of rectangles on the current rendering target.
\param renderer The renderer which should draw multiple rectangles.
\param rects A pointer to an array of destination rectangles.
\param count The number of rectangles.
\return 0 on success, or -1 on error
proc renderFillRect(renderer: ptr Renderer; rect: ptr Rect): cint {...}{.
importc: "SDL_RenderFillRect", cdecl.}-
\brief Fill a rectangle on the current rendering target with the drawing color.
\param renderer The renderer which should fill a rectangle.
\param rect A pointer to the destination rectangle, or NULL for the entire
rendering target.
\return 0 on success, or -1 on error
proc renderFillRects(renderer: ptr Renderer; rects: ptr Rect; count: cint): cint {...}{.
importc: "SDL_RenderFillRects", cdecl.}-
\brief Fill some number of rectangles on the current rendering target with the drawing color.
\param renderer The renderer which should fill multiple rectangles.
\param rects A pointer to an array of destination rectangles.
\param count The number of rectangles.
\return 0 on success, or -1 on error
proc renderCopy(renderer: ptr Renderer; texture: ptr Texture; srcrect: ptr Rect;
dstrect: ptr Rect): cint {...}{.importc: "SDL_RenderCopy", cdecl.}-
\brief Copy a portion of the texture to the current rendering target.
\param renderer The renderer which should copy parts of a texture.
\param texture The source texture.
\param srcrect A pointer to the source rectangle, or NULL for the entire
texture.
\param dstrect A pointer to the destination rectangle, or NULL for the
entire rendering target.
\return 0 on success, or -1 on error
proc renderCopyEx(renderer: ptr Renderer; texture: ptr Texture; srcrect: ptr Rect;
dstrect: ptr Rect; angle: cdouble; center: ptr Point;
flip: RendererFlip): cint {...}{.importc: "SDL_RenderCopyEx", cdecl.}-
\brief Copy a portion of the source texture to the current rendering target, rotating it by angle around the given center
\param renderer The renderer which should copy parts of a texture.
\param texture The source texture.
\param srcrect A pointer to the source rectangle, or NULL for the entire
texture.
\param dstrect A pointer to the destination rectangle, or NULL for the
entire rendering target.
\param angle An angle in degrees that indicates the rotation that will be applied to dstrect, rotating it in a clockwise direction
\param center A pointer to a point indicating the point around which dstrect will be rotated (if NULL, rotation will be done around dstrect.w/2, dstrect.h/2).
\param flip An SDL_RendererFlip value stating which flipping actions should be performed on the texture
\return 0 on success, or -1 on error
proc renderDrawPointF(renderer: ptr Renderer; x: cfloat; y: cfloat): cint {...}{.
importc: "SDL_RenderDrawPointF", cdecl.}-
\brief Draw a point on the current rendering target.
\param renderer The renderer which should draw a point.
\param x The x coordinate of the point.
\param y The y coordinate of the point.
\return 0 on success, or -1 on error
proc renderDrawPointsF(renderer: ptr Renderer; points: ptr FPoint; count: cint): cint {...}{.
importc: "SDL_RenderDrawPointsF", cdecl.}-
\brief Draw multiple points on the current rendering target.
\param renderer The renderer which should draw multiple points.
\param points The points to draw
\param count The number of points to draw
\return 0 on success, or -1 on error
proc renderDrawLineF(renderer: ptr Renderer; x1: cfloat; y1: cfloat; x2: cfloat;
y2: cfloat): cint {...}{.importc: "SDL_RenderDrawLineF", cdecl.}-
\brief Draw a line on the current rendering target.
\param renderer The renderer which should draw a line.
\param x1 The x coordinate of the start point.
\param y1 The y coordinate of the start point.
\param x2 The x coordinate of the end point.
\param y2 The y coordinate of the end point.
\return 0 on success, or -1 on error
proc renderDrawLinesF(renderer: ptr Renderer; points: ptr FPoint; count: cint): cint {...}{.
importc: "SDL_RenderDrawLinesF", cdecl.}-
\brief Draw a series of connected lines on the current rendering target.
\param renderer The renderer which should draw multiple lines.
\param points The points along the lines
\param count The number of points, drawing count-1 lines
\return 0 on success, or -1 on error
proc renderDrawRectF(renderer: ptr Renderer; rect: ptr FRect): cint {...}{.
importc: "SDL_RenderDrawRectF", cdecl.}-
\brief Draw a rectangle on the current rendering target.
\param renderer The renderer which should draw a rectangle.
\param rect A pointer to the destination rectangle, or NULL to outline the entire rendering target.
\return 0 on success, or -1 on error
proc renderDrawRectsF(renderer: ptr Renderer; rects: ptr FRect; count: cint): cint {...}{.
importc: "SDL_RenderDrawRectsF", cdecl.}-
\brief Draw some number of rectangles on the current rendering target.
\param renderer The renderer which should draw multiple rectangles.
\param rects A pointer to an array of destination rectangles.
\param count The number of rectangles.
\return 0 on success, or -1 on error
proc renderFillRectF(renderer: ptr Renderer; rect: ptr FRect): cint {...}{.
importc: "SDL_RenderFillRectF", cdecl.}-
\brief Fill a rectangle on the current rendering target with the drawing color.
\param renderer The renderer which should fill a rectangle.
\param rect A pointer to the destination rectangle, or NULL for the entire
rendering target.
\return 0 on success, or -1 on error
proc renderFillRectsF(renderer: ptr Renderer; rects: ptr FRect; count: cint): cint {...}{.
importc: "SDL_RenderFillRectsF", cdecl.}-
\brief Fill some number of rectangles on the current rendering target with the drawing color.
\param renderer The renderer which should fill multiple rectangles.
\param rects A pointer to an array of destination rectangles.
\param count The number of rectangles.
\return 0 on success, or -1 on error
proc renderCopyF(renderer: ptr Renderer; texture: ptr Texture; srcrect: ptr Rect;
dstrect: ptr FRect): cint {...}{.importc: "SDL_RenderCopyF", cdecl.}-
\brief Copy a portion of the texture to the current rendering target.
\param renderer The renderer which should copy parts of a texture.
\param texture The source texture.
\param srcrect A pointer to the source rectangle, or NULL for the entire
texture.
\param dstrect A pointer to the destination rectangle, or NULL for the
entire rendering target.
\return 0 on success, or -1 on error
proc renderCopyExF(renderer: ptr Renderer; texture: ptr Texture; srcrect: ptr Rect;
dstrect: ptr FRect; angle: cdouble; center: ptr FPoint;
flip: RendererFlip): cint {...}{.importc: "SDL_RenderCopyExF", cdecl.}-
\brief Copy a portion of the source texture to the current rendering target, rotating it by angle around the given center
\param renderer The renderer which should copy parts of a texture.
\param texture The source texture.
\param srcrect A pointer to the source rectangle, or NULL for the entire
texture.
\param dstrect A pointer to the destination rectangle, or NULL for the
entire rendering target.
\param angle An angle in degrees that indicates the rotation that will be applied to dstrect, rotating it in a clockwise direction
\param center A pointer to a point indicating the point around which dstrect will be rotated (if NULL, rotation will be done around dstrect.w/2, dstrect.h/2).
\param flip An SDL_RendererFlip value stating which flipping actions should be performed on the texture
\return 0 on success, or -1 on error
proc renderReadPixels(renderer: ptr Renderer; rect: ptr Rect; format: Uint32;
pixels: pointer; pitch: cint): cint {...}{.
importc: "SDL_RenderReadPixels", cdecl.}-
\brief Read pixels from the current rendering target.
\param renderer The renderer from which pixels should be read.
\param rect A pointer to the rectangle to read, or NULL for the entire
render target.
\param format The desired format of the pixel data, or 0 to use the format
of the rendering target
\param pixels A pointer to be filled in with the pixel data
\param pitch The pitch of the pixels parameter.
\return 0 on success, or -1 if pixel reading is not supported.
\warning This is a very slow operation, and should not be used frequently.
proc renderPresent(renderer: ptr Renderer) {...}{.importc: "SDL_RenderPresent", cdecl.}-
\brief Update the screen with rendering performed.
proc destroyTexture(texture: ptr Texture) {...}{.importc: "SDL_DestroyTexture", cdecl.}-
\brief Destroy the specified texture.
\sa SDL_CreateTexture()
\sa SDL_CreateTextureFromSurface()
proc destroyRenderer(renderer: ptr Renderer) {...}{.importc: "SDL_DestroyRenderer", cdecl.}-
\brief Destroy the rendering context for a window and free associated
textures.
\sa SDL_CreateRenderer()
proc renderFlush(renderer: ptr Renderer): cint {...}{.importc: "SDL_RenderFlush", cdecl.}-
\brief Force the rendering context to flush any pending commands to the
underlying rendering API.
You do not need to (and in fact, shouldn't) call this function unless
you are planning to call into OpenGL/Direct3D/Metal/whatever directly
in addition to using an SDL_Renderer.
This is for a very-specific case: if you are using SDL's render API,
you asked for a specific renderer backend (OpenGL, Direct3D, etc),
you set SDL_HINT_RENDER_BATCHING to "1", and you plan to make
OpenGL/D3D/whatever calls in addition to SDL render API calls. If all of
this applies, you should call SDL_RenderFlush() between calls to SDL's
render API and the low-level API you're using in cooperation.
In all other cases, you can ignore this function. This is only here to
get maximum performance out of a specific situation. In all other cases,
SDL will do the right thing, perhaps at a performance loss.
This function is first available in SDL 2.0.10, and is not needed in
2.0.9 and earlier, as earlier versions did not queue rendering commands
at all, instead flushing them to the OS immediately.
proc gL_BindTexture(texture: ptr Texture; texw: ptr cfloat; texh: ptr cfloat): cint {...}{.
importc: "SDL_GL_BindTexture", cdecl.}-
\brief Bind the texture to the current OpenGL/ES/ES2 context for use with
OpenGL instructions.
\param texture The SDL texture to bind
\param texw A pointer to a float that will be filled with the texture width
\param texh A pointer to a float that will be filled with the texture height
\return 0 on success, or -1 if the operation is not supported
proc gL_UnbindTexture(texture: ptr Texture): cint {...}{.importc: "SDL_GL_UnbindTexture",
cdecl.}-
\brief Unbind a texture from the current OpenGL/ES/ES2 context.
\param texture The SDL texture to unbind
\return 0 on success, or -1 if the operation is not supported
proc renderGetMetalLayer(renderer: ptr Renderer): pointer {...}{.
importc: "SDL_RenderGetMetalLayer", cdecl.}-
\brief Get the CAMetalLayer associated with the given Metal renderer
\param renderer The renderer to query
\return CAMetalLayer on success, or NULL if the renderer isn't a Metal renderer
\sa SDL_RenderGetMetalCommandEncoder()
proc renderGetMetalCommandEncoder(renderer: ptr Renderer): pointer {...}{.
importc: "SDL_RenderGetMetalCommandEncoder", cdecl.}-
\brief Get the Metal command encoder for the current frame
\param renderer The renderer to query
\return id<MTLRenderCommandEncoder> on success, or NULL if the renderer isn't a Metal renderer
\sa SDL_RenderGetMetalLayer()
proc numSensors(): cint {...}{.importc: "SDL_NumSensors", cdecl.}-
Gyroscope sensor
The gyroscope returns the current rate of rotation in radians per second.
The rotation is positive in the counter-clockwise direction. That is,
an observer looking from a positive location on one of the axes would
see positive rotation on that axis when it appeared to be rotating
counter-clockwise.
values[0]: Angular speed around the x axis
values[1]: Angular speed around the y axis
values[2]: Angular speed around the z axis
For phones held in portrait mode, the axes are defined as follows:
-X ... +X : left ... right
-Y ... +Y : bottom ... top
-Z ... +Z : farther ... closer
The axis data is not changed when the phone is rotated.
\sa SDL_GetDisplayOrientation()
Function prototypes
\brief Count the number of sensors attached to the system right now
proc sensorGetDeviceName(deviceIndex: cint): cstring {...}{.
importc: "SDL_SensorGetDeviceName", cdecl.}-
\brief Get the implementation dependent name of a sensor.
This can be called before any sensors are opened.
\return The sensor name, or NULL if device_index is out of range.
proc sensorGetDeviceType(deviceIndex: cint): SensorType {...}{.
importc: "SDL_SensorGetDeviceType", cdecl.}-
\brief Get the type of a sensor.
This can be called before any sensors are opened.
\return The sensor type, or SDL_SENSOR_INVALID if device_index is out of range.
proc sensorGetDeviceNonPortableType(deviceIndex: cint): cint {...}{.
importc: "SDL_SensorGetDeviceNonPortableType", cdecl.}-
\brief Get the platform dependent type of a sensor.
This can be called before any sensors are opened.
\return The sensor platform dependent type, or -1 if device_index is out of range.
proc sensorGetDeviceInstanceID(deviceIndex: cint): SensorID {...}{.
importc: "SDL_SensorGetDeviceInstanceID", cdecl.}-
\brief Get the instance ID of a sensor.
This can be called before any sensors are opened.
\return The sensor instance ID, or -1 if device_index is out of range.
proc sensorOpen(deviceIndex: cint): ptr Sensor {...}{.importc: "SDL_SensorOpen", cdecl.}-
\brief Open a sensor for use.
The index passed as an argument refers to the N'th sensor on the system.
\return A sensor identifier, or NULL if an error occurred.
proc sensorFromInstanceID(instanceId: SensorID): ptr Sensor {...}{.
importc: "SDL_SensorFromInstanceID", cdecl.}-
Return the SDL_Sensor associated with an instance id.
proc sensorGetName(sensor: ptr Sensor): cstring {...}{.importc: "SDL_SensorGetName", cdecl.}-
\brief Get the implementation dependent name of a sensor.
\return The sensor name, or NULL if the sensor is NULL.
proc sensorGetType(sensor: ptr Sensor): SensorType {...}{.importc: "SDL_SensorGetType",
cdecl.}-
\brief Get the type of a sensor.
This can be called before any sensors are opened.
\return The sensor type, or SDL_SENSOR_INVALID if the sensor is NULL.
proc sensorGetNonPortableType(sensor: ptr Sensor): cint {...}{.
importc: "SDL_SensorGetNonPortableType", cdecl.}-
\brief Get the platform dependent type of a sensor.
This can be called before any sensors are opened.
\return The sensor platform dependent type, or -1 if the sensor is NULL.
proc sensorGetInstanceID(sensor: ptr Sensor): SensorID {...}{.
importc: "SDL_SensorGetInstanceID", cdecl.}-
\brief Get the instance ID of a sensor.
This can be called before any sensors are opened.
\return The sensor instance ID, or -1 if the sensor is NULL.
proc sensorGetData(sensor: ptr Sensor; data: ptr cfloat; numValues: cint): cint {...}{.
importc: "SDL_SensorGetData", cdecl.}-
Get the current state of an opened sensor.
The number of values and interpretation of the data is sensor dependent.
\param sensor The 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.
proc sensorClose(sensor: ptr Sensor) {...}{.importc: "SDL_SensorClose", cdecl.}-
Close a sensor previously opened with SDL_SensorOpen()
proc sensorUpdate() {...}{.importc: "SDL_SensorUpdate", cdecl.}-
Update the current state of the open sensors.
This is called automatically by the event loop if sensor events are enabled.
This needs to be called from the thread that initialized the sensor subsystem.
proc createShapedWindow(title: cstring; x: cuint; y: cuint; w: cuint; h: cuint;
flags: Uint32): ptr Window {...}{.
importc: "SDL_CreateShapedWindow", cdecl.}-
\brief Create a window that can be shaped with the specified position, dimensions, and flags.
\param title The title of the window, in UTF-8 encoding.
\param x The x position of the window, ::SDL_WINDOWPOS_CENTERED, or
::SDL_WINDOWPOS_UNDEFINED.
\param y The y position of the window, ::SDL_WINDOWPOS_CENTERED, or
::SDL_WINDOWPOS_UNDEFINED.
\param w The width of the window.
\param h The height of the window.
\param flags The flags for the window, a mask of SDL_WINDOW_BORDERLESS with any of the following:
::SDL_WINDOW_OPENGL, ::SDL_WINDOW_INPUT_GRABBED,
::SDL_WINDOW_HIDDEN, ::SDL_WINDOW_RESIZABLE,
::SDL_WINDOW_MAXIMIZED, ::SDL_WINDOW_MINIMIZED,
::SDL_WINDOW_BORDERLESS is always set, and ::SDL_WINDOW_FULLSCREEN is always unset.
\return The window created, or NULL if window creation failed.
\sa SDL_DestroyWindow()
proc isShapedWindow(window: ptr Window): bool {...}{.importc: "SDL_IsShapedWindow", cdecl.}-
\brief Return whether the given window is a shaped window.
\param window The window to query for being shaped.
\return SDL_TRUE if the window is a window that can be shaped, SDL_FALSE if the window is unshaped or NULL.
\sa SDL_CreateShapedWindow
proc setWindowShape(window: ptr Window; shape: ptr Surface;
shapeMode: ptr WindowShapeMode): cint {...}{.
importc: "SDL_SetWindowShape", cdecl.}-
\brief Set the shape and parameters of a shaped window.
\param window The shaped window whose parameters should be set.
\param shape A surface encoding the desired shape for the window.
\param shape_mode The parameters to set for the shaped window.
\return 0 on success, SDL_INVALID_SHAPE_ARGUMENT on an invalid shape argument, or SDL_NONSHAPEABLE_WINDOW
if the SDL_Window given does not reference a valid shaped window.
\sa SDL_WindowShapeMode
\sa SDL_GetShapedWindowMode.
proc getShapedWindowMode(window: ptr Window; shapeMode: ptr WindowShapeMode): cint {...}{.
importc: "SDL_GetShapedWindowMode", cdecl.}-
\brief Get the shape parameters of a shaped window.
\param window The shaped window whose parameters should be retrieved.
\param shape_mode An empty shape-mode structure to fill, or NULL to check whether the window has a shape.
\return 0 if the window has a shape and, provided shape_mode was not NULL, shape_mode has been filled with the mode
data, SDL_NONSHAPEABLE_WINDOW if the SDL_Window given is not a shaped window, or SDL_WINDOW_LACKS_SHAPE if
the SDL_Window given is a shapeable window currently lacking a shape.
\sa SDL_WindowShapeMode
\sa SDL_SetWindowShape
proc isTablet(): bool {...}{.importc: "SDL_IsTablet", cdecl.}-
Some compilers use a special export keyword
By default SDL uses the C calling convention
Removed DECLSPEC on Symbian OS because SDL cannot be a DLL in EPOC
Force structure packing at 4 byte alignment.
This is necessary if the header is included in code which has structure
packing set to an alternate value, say for loading structures from disk.
The packing is reset to the previous value in close_code.h
Apparently this is needed by several Windows compilers
Set up for C function definitions, even when using C++
Platform specific functions for Windows
Platform specific functions for Linux
Platform specific functions for iOS
Platform specific functions for Android
Platform specific functions for WinRT
\brief Return true if the current device is a tablet.
proc onApplicationWillTerminate() {...}{.importc: "SDL_OnApplicationWillTerminate", cdecl.}-
Functions used by iOS application delegates to notify SDL about state changes
proc onApplicationDidReceiveMemoryWarning() {...}{.
importc: "SDL_OnApplicationDidReceiveMemoryWarning", cdecl.}-
proc onApplicationWillResignActive() {...}{.importc: "SDL_OnApplicationWillResignActive",
cdecl.}-
proc onApplicationDidEnterBackground() {...}{.importc: "SDL_OnApplicationDidEnterBackground",
cdecl.}-
proc onApplicationWillEnterForeground() {...}{.importc: "SDL_OnApplicationWillEnterForeground",
cdecl.}-
proc onApplicationDidBecomeActive() {...}{.importc: "SDL_OnApplicationDidBecomeActive",
cdecl.}-
proc getTicks(): Uint32 {...}{.importc: "SDL_GetTicks", cdecl.}-
Some compilers use a special export keyword
By default SDL uses the C calling convention
Removed DECLSPEC on Symbian OS because SDL cannot be a DLL in EPOC
Force structure packing at 4 byte alignment.
This is necessary if the header is included in code which has structure
packing set to an alternate value, say for loading structures from disk.
The packing is reset to the previous value in close_code.h
Apparently this is needed by several Windows compilers
Set up for C function definitions, even when using C++
\brief Get the number of milliseconds since the SDL library initialization.
\note This value wraps if the program runs for more than ~49 days.
proc getPerformanceCounter(): Uint64 {...}{.importc: "SDL_GetPerformanceCounter", cdecl.}-
\brief Get the current value of the high resolution counter
proc getPerformanceFrequency(): Uint64 {...}{.importc: "SDL_GetPerformanceFrequency",
cdecl.}-
\brief Get the count per second of the high resolution counter
proc delay(ms: Uint32) {...}{.importc: "SDL_Delay", cdecl.}-
\brief Wait a specified number of milliseconds before returning.
proc addTimer(interval: Uint32; callback: TimerCallback; param: pointer): TimerID {...}{.
importc: "SDL_AddTimer", cdecl.}-
\brief Add a new timer to the pool of timers already running.
\return A timer ID, or 0 when an error occurs.
proc removeTimer(id: TimerID): bool {...}{.importc: "SDL_RemoveTimer", cdecl.}-
\brief Remove a timer knowing its ID.
\return A boolean value indicating success or failure.
\warning It is not safe to remove a timer multiple times.
proc getVersion(ver: ptr Version) {...}{.importc: "SDL_GetVersion", cdecl.}-
\brief Get the version of SDL that is linked against your program.
If you are linking to SDL dynamically, then it is possible that the
current version will be different than the version you compiled against.
This function returns the current version, while SDL_VERSION() is a
macro that tells you what version you compiled with.
\code
SDL_version compiled;
SDL_version linked;
SDL_VERSION(&compiled);
SDL_GetVersion(&linked);
printf("We compiled against SDL version %d.%d.%d ...\n",
compiled.major, compiled.minor, compiled.patch);
printf("But we linked against SDL version %d.%d.%d.\n",
linked.major, linked.minor, linked.patch);
\endcode
This function may be called safely at any time, even before SDL_Init().
\sa SDL_VERSION
proc getRevision(): cstring {...}{.importc: "SDL_GetRevision", cdecl.}-
\brief Get the code revision of SDL that is linked against your program.
Returns an arbitrary string (a hash value) uniquely identifying the
exact revision of the SDL library in use, and is only useful in comparing
against other revisions. It is NOT an incrementing number.
proc getRevisionNumber(): cint {...}{.importc: "SDL_GetRevisionNumber", cdecl.}-
\brief Get the revision number of SDL that is linked against your program.
Returns a number uniquely identifying the exact revision of the SDL
library in use. It is an incrementing number based on commits to
hg.libsdl.org.
proc init(flags: Uint32): cint {...}{.importc: "SDL_Init", cdecl.}-
@}
This function initializes the subsystems specified by \c flags
proc initSubSystem(flags: Uint32): cint {...}{.importc: "SDL_InitSubSystem", cdecl.}-
This function initializes specific SDL subsystems
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.
proc quitSubSystem(flags: Uint32) {...}{.importc: "SDL_QuitSubSystem", cdecl.}-
This function cleans up specific SDL subsystems
proc wasInit(flags: Uint32): Uint32 {...}{.importc: "SDL_WasInit", cdecl.}-
This function returns a mask of the specified subsystems which have
previously been initialized.
If \c flags is 0, it returns a mask of all initialized subsystems.
proc quit() {...}{.importc: "SDL_Quit", cdecl.}-
This function cleans up all initialized subsystems. You should
call it upon all exit conditions.