All Functions and Procedures

AA Circle

AA Ellipse

AA Line

AA-Polygon

AA-Trigon

Arc

Bezier

Filled rectangle (Box)

Circle

Ellipse

Filled Circle

Filled Ellipse

Filled Pie

Filled Polygon

Filled Trigon

Characters/Strings

Horizontal line

Convenience functions *

Individual loading functions *

Load an image from an SDL data source. The 'type' may be one of: "BMP", "GIF", "PNG", etc.

If the image format supports a transparent pixel, SDL will set the colorkey for the surface. You can enable RLE acceleration on the surface afterwards by calling: SDL_SetColorKey(image, SDL_RLEACCEL, image->format->colorkey);

Unloads libraries loaded with IMG_Init *

Individual saving functions *

We'll use SDL for reporting errors *

Close the mixer, halting all playing audio *

Change the expiration delay for a particular channel. The sample will stop playing after the 'ticks' milliseconds have elapsed, or remove the expiration if 'ticks' is -1

Free an audio chunk previously loaded *

Get the Mix_Chunk currently associated with a mixer channel Returns NULL if it's an invalid channel, or there's no chunk associated.

Get a pointer to the user data for the current music hook *

Get a list of chunk/music decoders that this build of SDL_mixer provides. This list can change between builds AND runs of the program, if external libraries that add functionality become available. You must successfully call Mix_OpenAudio() before calling these functions. This API is only available in SDL_mixer 1.2.9 and later.

// usage... int i; const int total = Mix_GetNumChunkDecoders(); for (i = 0; i < total; i++) printf("Supported chunk decoder: [%s]\n", Mix_GetChunkDecoder(i));

Appearing in this list doesn't promise your specific audio file will decode...but it's handy to know if you have, say, a functioning Timidity install.

These return values are static, read-only data; do not modify or free it. The pointers remain valid until you call Mix_CloseAudio().

Finds the first available channel in a group of channels, returning -1 if none are available.

Assign several consecutive channels to a group *

Finds the "most recent" (i.e. last) sample playing in a group of channels *

Halt playing of a particular channel *

This function gets the version of the dynamically linked SDL_mixer library. it should NOT be used to fill a version structure, instead you should use the SDL_MIXER_VERSION() macro.

Load a music file from an SDL_RWop object assuming a specific format *

Open the mixer with a certain audio format *

Pause/Resume the music stream *

The same as above, but the sound is played at most 'ticks' milliseconds *

Find out what the actual audio device parameters are. This function returns 1 if the audio has been opened, 0 otherwise.

Load a wave file of the mixer format from a memory buffer *

Register a special effect function. At mixing time, the channel data is copied into a buffer and passed through each registered effect function. After it passes through all the functions, it is mixed into the final output stream. The copy to buffer is performed once, then each effect function performs on the output of the previous effect. Understand that this extra copy to a buffer is not performed if there are no effects registered for a given chunk, which saves CPU cycles, and any given effect will be extra cycles, too, so it is crucial that your code run fast. Also note that the data that your function is given is in the format of the sound device, and not the format you gave to Mix_OpenAudio(), although they may in reality be the same. This is an unfortunate but necessary speed concern. Use Mix_QuerySpec() to determine if you can handle the data before you register your effect, and take appropriate actions. You may also specify a callback (Mix_EffectDone_t) that is called when the channel finishes playing. This gives you a more fine-grained control than Mix_ChannelFinished(), in case you need to free effect-specific resources, etc. If you don't need this, you can specify NULL. You may set the callbacks before or after calling Mix_PlayChannel(). Things like Mix_SetPanning() are just internal special effect functions, so if you are using that, you've already incurred the overhead of a copy to a separate buffer, and that these effects will be in the queue with any functions you've registered. The list of registered effects for a channel is reset when a chunk finishes playing, so you need to explicitly set them with each call to Mix_PlayChannel*(). You may also register a special effect function that is to be run after final mixing occurs. The rules for these callbacks are identical to those in Mix_RegisterEffect, but they are run after all the channels and the music have been mixed into a single stream, whereas channel-specific effects run on a given channel before any other mixing occurs. These global effect callbacks are call "posteffects". Posteffects only have their Mix_EffectDone_t function called when they are unregistered (since the main output stream is never "done" in the same sense as a channel). You must unregister them manually when you've had enough. Your callback will be told that the channel being mixed is (MIX_CHANNEL_POST) if the processing is considered a posteffect.

After all these effects have finished processing, the callback registered through Mix_SetPostMix() runs, and then the stream goes to the audio device.

DO NOT EVER call SDL_LockAudio() from your callback function!

returns zero if error (no such channel), nonzero if added. Error messages can be retrieved from Mix_GetError().

We'll use SDL for reporting errors *

Set the current position in the music stream. This returns 0 if successful, or -1 if it failed or isn't implemented. This function is only implemented for MOD music formats (set pattern order number) and for OGG, FLAC, MP3_MAD, MP3_MPG and MODPLUG music (set position in seconds), at the moment.

Set the position of a channel. (angle) is an integer from 0 to 360, that specifies the location of the sound in relation to the listener. (angle) will be reduced as neccesary (540 becomes 180 degrees, -100 becomes 260). Angle 0 is due north, and rotates clockwise as the value increases. For efficiency, the precision of this effect may be limited (angles 1 through 7 might all produce the same effect, 8 through 15 are equal, etc). (distance) is an integer between 0 and 255 that specifies the space between the sound and the listener. The larger the number, the further away the sound is. Using 255 does not guarantee that the channel will be culled from the mixing process or be completely silent. For efficiency, the precision of this effect may be limited (distance 0 through 5 might all produce the same effect, 6 through 10 are equal, etc). Setting (angle) and (distance) to 0 unregisters this effect, since the data would be unchanged.

If you need more precise positional audio, consider using OpenAL for spatialized effects instead of SDL_mixer. This is only meant to be a basic effect for simple "3D" games.

If the audio device is configured for mono output, then you won't get any effectiveness from the angle; however, distance attenuation on the channel will still occur. While this effect will function with stereo voices, it makes more sense to use voices with only one channel of sound, so when they are mixed through this effect, the positioning will sound correct. You can convert them to mono through SDL before giving them to the mixer in the first place if you like.

Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and the positioning will be done to the final mixed stream before passing it on to the audio device.

This is a convenience wrapper over Mix_SetDistance() and Mix_SetPanning().

returns zero if error (no such channel or Mix_RegisterEffect() fails), nonzero if position effect is enabled. Error messages can be retrieved from Mix_GetError().

Causes a channel to reverse its stereo. This is handy if the user has his speakers hooked up backwards, or you would like to have a minor bit of psychedelia in your sound code. :) Calling this function with (flip) set to non-zero reverses the chunks's usual channels. If (flip) is zero, the effect is unregistered.

This uses the Mix_RegisterEffect() API internally, and thus is probably more CPU intensive than having the user just plug in his speakers correctly. Mix_SetReverseStereo() returns without registering the effect function if the audio device is not configured for stereo output.

If you specify MIX_CHANNEL_POST for (channel), then this the effect is used on the final mixed stream before sending it on to the audio device (a posteffect).

returns zero if error (no such channel or Mix_RegisterEffect() fails), nonzero if reversing effect is enabled. Note that an audio device in mono mode is a no-op, but this call will return successful in that case. Error messages can be retrieved from Mix_GetError().

Synchro value is set by MikMod from modules while playing *

You may not need to call this explicitly, unless you need to stop an effect from processing in the middle of a chunk's playback. Posteffects are never implicitly unregistered as they are for channels, but they may be explicitly unregistered through this function by specifying MIX_CHANNEL_POST for a channel. returns zero if error (no such channel or effect), nonzero if removed. Error messages can be retrieved from Mix_GetError().

Set the volume in the range of 0-128 of a specific channel or chunk. If the specified channel is -1, set volume for all channels. Returns the original volume. If the specified volume is -1, just return the current volume.

Rotozoom functions

Rounded-Corner Filled rectangle (Box)

Rounded-Corner Rectangle

Add a socket to a set of sockets to be checked for available data *

Allocate/Free a UDP packet vector (array of packets) of 'howmany' packets, each 'size' bytes long. A pointer to the first packet in the array is returned, or NULL if the function ran out of memory.

This function checks to see if data is available for reading on the given set of sockets. If 'timeout' is 0, it performs a quick poll, otherwise the function returns when either data is available for reading, or the timeout in milliseconds has elapsed, which ever occurs first. This function returns the number of sockets ready for reading, or -1 if there was an error with the select() system call.

Free a set of sockets allocated by SDL_NetAllocSocketSet() *

Get the addresses of network interfaces on this system. This returns the number of addresses saved in 'addresses'

This function gets the version of the dynamically linked SDL_net library. it should NOT be used to fill a version structure, instead you should use the SDL_NET_VERSION() macro.

Resolve an ip address to a host name in canonical form. If the ip couldn't be resolved, this function returns NULL, otherwise a pointer to a static buffer containing the hostname is returned. Note that this function is not thread-safe.

After calling SDLNet_CheckSockets(), you can use this function on a socket that was in the socket set, to find out if data is available for reading.

Close a TCP network socket *

Open a TCP network socket If ip.host is INADDR_NONE or INADDR_ANY, this creates a local server socket on the given port, otherwise a TCP connection to the remote host and port is attempted. The address passed in should already be swapped to network byte order (addresses returned from SDLNet_ResolveHost() are already in the correct form). The newly created socket is returned, or NULL if there was an error.

Send 'len' bytes of 'data' over the non-server socket 'sock' This function returns the actual amount of data sent. If the return value is less than the amount of data sent, then either the remote connection was closed, or an unknown socket error occurred.

Close a UDP network socket *

Open a UDP network socket If 'port' is non-zero, the UDP socket is bound to a local port. The 'port' should be given in native byte order, but is used internally in network (big endian) byte order, in addresses, etc. This allows other systems to send to this socket via a known port.

Receive a vector of pending packets from the UDP socket. The returned packets contain the source address and the channel they arrived on. If they did not arrive on a bound channel, the the channel will be set to -1. The channels are checked in highest to lowest order, so if an address is bound to multiple channels, the highest channel with the source address bound will be returned. This function returns the number of packets read from the network, or -1 on error. This function does not block, so can return 0 packets pending.

Send a vector of packets to the the channels specified within the packet. If the channel specified in the packet is -1, the packet will be sent to the address in the 'src' member of the packet. Each packet will be updated with the status of the packet after it has been sent, -1 if the packet send failed. This function returns the number of packets sent.

Unbind all addresses from the given channel *

Calculate the arc cosine of x; that is, the value (in radians) whose cosine equals x.

\since This function is available since SDL 2.0.8.

Create an SDL_PixelFormat structure corresponding to a pixel format.

Returned structure may come from a shared global cache (i.e. not newly allocated), and hence should not be modified, especially the palette. Weird errors such as `Blit combination not supported` may occur.

\param pixel_format one of the SDL_PixelFormatEnum values \returns the new SDL_PixelFormat structure or NULL on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_FreeFormat

RWFrom functions*

Calculate the arc sine of x; that is, the value (in radians) whose sine equals x.

\since This function is available since SDL 2.0.8.

Calculate the arc tangent of y/x, using the signs of the two arguments to determine the quadrant of the result.

\since This function is available since SDL 2.0.4.

Calculate the arc tangent of x; that is, the value (in radians) whose tangent equals x.

\since This function is available since SDL 2.0.8.

Set an atomic variable to a new value if it is currently an old value.

Decrement an atomic variable used as a reference count and check if it reached zero after decrementing.

Get the value of a pointer atomically.

Lock a spin lock by setting it to a non-zero value.

Set a pointer to a new value atomically, and return the old value.

Unlock a spin lock by setting it to 0.

Always returns immediately.

Use this function to shut down audio if you initialized it with SDL_AudioInit().

This function is 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_Quit() or SDL_QuitSubSystem().

\since This function is available since SDL 2.0.0.

\sa SDL_AudioInit

Clear any pending data in the stream without converting it

\since This function is available since SDL 2.0.7.

\sa SDL_NewAudioStream \sa SDL_AudioStreamPut \sa SDL_AudioStreamGet \sa SDL_AudioStreamAvailable \sa SDL_AudioStreamFlush \sa SDL_FreeAudioStream

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 \returns the number of bytes read from the stream, or -1 on error

\since This function is available since SDL 2.0.7.

\sa SDL_NewAudioStream \sa SDL_AudioStreamPut \sa SDL_AudioStreamAvailable \sa SDL_AudioStreamFlush \sa SDL_AudioStreamClear \sa SDL_FreeAudioStream

SDL_surface.h uses #define to change all SDL_BlitSurface() calls into SDL_UpperBlit() calls. * Since Pascal macro support is very limited, we workaround by outright pointing SDL_BlitSurface() to SDL_UpperBlit().

Initialize an SDL_AudioCVT structure for conversion.

Before an SDL_AudioCVT structure can be used to convert audio data it must be initialized with source and destination information.

This function will zero out every field of the SDL_AudioCVT, so it must be called before the application fills in the final buffer information.

Once this function has returned successfully, and reported that a conversion is necessary, the application fills in the rest of the fields in SDL_AudioCVT, now that it knows how large a buffer it needs to allocate, and then can call SDL_ConvertAudio() to complete the conversion.

\param cvt an SDL_AudioCVT structure filled in with audio conversion information \param src_format the source format of the audio data; for more info see SDL_AudioFormat \param src_channels the number of channels in the source \param src_rate the frequency (sample-frames-per-second) of the source \param dst_format the destination format of the audio data; for more info see SDL_AudioFormat \param dst_channels the number of channels in the destination \param dst_rate the frequency (sample-frames-per-second) of the destination \returns 1 if the audio filter is prepared, 0 if no conversion is needed, or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_ConvertAudio

/** Calculate a 256 entry gamma ramp for a gamma value.

\param gamma a gamma value where 0.0 is black and 1.0 is identity \param ramp an array of 256 values filled in with the gamma ramp

\since This function is available since SDL 2.0.0.

\sa SDL_SetWindowGammaRamp

Capture the mouse and to track input outside an SDL window.

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. For that, you should probably use SDL_SetRelativeMouseMode() or SDL_SetWindowGrab(), depending on your goals.

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.

Please note that as of SDL 2.0.22, SDL will attempt to "auto capture" the mouse while the user is pressing a button; this is to try and make mouse behavior more consistent between platforms, and deal with the common case of a user dragging the mouse outside of the window. This means that if you are calling SDL_CaptureMouse() only to deal with this situation, you no longer have to (although it is safe to do so). If this causes problems for your app, you can disable auto capture by setting the `SDL_HINT_MOUSE_AUTO_CAPTURE` hint to zero.

\param enabled SDL_TRUE to enable capturing, SDL_FALSE to disable. \returns 0 on success or -1 if not supported; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.4.

\sa SDL_GetGlobalMouseState

Calculate the smallest integral value that is not less than x.

\since This function is available since SDL 2.0.8.

\brief Clear the error message for the current thread

Drop any queued audio data waiting to be sent to the hardware.

Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For output devices, the hardware will start playing silence if more audio isn't queued. For capture devices, the hardware will start filling the empty queue with new data if the capture device isn't paused.

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 or any unprocessed microphone input during a level change in your game.

You may not queue or dequeue audio on a device that is using an application-supplied callback; calling this function on such a device always returns 0. You have to use the audio callback or queue audio, 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

\since This function is available since SDL 2.0.4.

\sa SDL_GetQueuedAudioSize \sa SDL_QueueAudio \sa SDL_DequeueAudio

Use this function to shut down audio processing and close the audio device.

The application should close open audio devices once they are no longer needed. Calling this function will wait until the device's audio callback is not running, release the audio hardware and then clean up internal state. No further audio will play from this device once this function returns.

This function may block briefly while pending audio data is played by the hardware, so that applications don't drop the last buffer of data they supplied.

The device ID is invalid as soon as the device is closed, and is eligible for reuse in a new SDL_OpenAudioDevice() call immediately.

\param dev an audio device previously opened with SDL_OpenAudioDevice()

\since This function is available since SDL 2.0.0.

\sa SDL_OpenAudioDevice

The compiler barrier prevents the compiler from reordering reads and writes to globally visible variables across the call.

Restart all threads that are waiting on the condition variable.

\param cond the condition variable to signal \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

Wait until a condition variable is signaled.

This function unlocks the specified `mutex` and waits for another thread to call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable `cond`. Once the condition variable is signaled, the mutex is re-locked and the function returns.

The mutex must be locked before calling this function.

This function is the equivalent of calling SDL_CondWaitTimeout() with a time length of SDL_MUTEX_MAXWAIT.

\param cond the condition variable to wait on \param mutex the mutex used to coordinate thread access \returns 0 when it is signaled or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

Convert audio data to a desired audio format.

This function does the actual audio data conversion, after the application has called SDL_BuildAudioCVT() to prepare the conversion information and then filled in the buffer details.

Once the application has initialized the `cvt` structure using SDL_BuildAudioCVT(), allocated an audio buffer and filled it with audio data in the source format, this function will convert the buffer, in-place, to the desired format.

The data conversion may go through several passes; any given pass may possibly temporarily increase the size of the data. For example, SDL might expand 16-bit data to 32 bits before resampling to a lower frequency, shrinking the data size after having grown it briefly. Since the supplied buffer will be both the source and destination, converting as necessary in-place, the application must allocate a buffer that will fully contain the data during its largest conversion pass. After SDL_BuildAudioCVT() returns, the application should set the `cvt->len` field to the size, in bytes, of the source data, and allocate a buffer that is `cvt->len * cvt->len_mult` bytes long for the `buf` field.

The source data should be copied into this buffer before the call to SDL_ConvertAudio(). Upon successful return, this buffer will contain the converted audio, and `cvt->len_cvt` will be the size of the converted data, in bytes. Any bytes in the buffer past `cvt->len_cvt` are undefined once this function returns.

\param cvt an SDL_AudioCVT structure that was previously set up by SDL_BuildAudioCVT(). \returns 0 if the conversion was completed successfully or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_BuildAudioCVT

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

Return a number whose absolute value matches that of x, but the sign matches that of y.

\since This function is available since SDL 2.0.4.

Calculate the cosine of x, where x is given in radians.

\since This function is available since SDL 2.0.4.

Create a color cursor.

\param surface an SDL_Surface structure representing the cursor image \param hot_x the x position of the cursor hot spot \param hot_y the y position of the cursor hot spot \returns the new cursor on success or NULL on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_CreateCursor \sa SDL_FreeCursor

Create a cursor using the specified bitmap data and mask (in MSB format).

`mask` has to be in MSB (Most Significant Bit) format.

The cursor width (`w`) must be a multiple of 8 bits.

The cursor is created in black and white according to the following:

- data=0, mask=1: white - data=1, mask=1: black - data=0, mask=0: transparent - data=1, mask=0: inverted color if possible, black if not.

Cursors created with this function must be freed with SDL_FreeCursor().

If you want to have a color cursor, or create your cursor from an SDL_Surface, you should use SDL_CreateColorCursor(). Alternately, you can hide the cursor and draw your own as part of your game's rendering, but it will be bound to the framerate.

Also, since SDL 2.0.0, SDL_CreateSystemCursor() is available, which provides twelve readily available system cursors to pick from.

\param data the color value for each pixel of the cursor \param mask the mask value for each pixel of the cursor \param w the width of the cursor \param h the height of the cursor \param hot_x the X-axis location of the upper left corner of the cursor relative to the actual mouse position \param hot_y the Y-axis location of the upper left corner of the cursor relative to the actual mouse position \returns a new cursor with the specified parameters on success or NULL on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_FreeCursor \sa SDL_SetCursor \sa SDL_ShowCursor

Create a 2D rendering context for a window.

window The window where rendering is displayed. index The index of the rendering driver to initialize, or -1 to initialize the first one supporting the requested flags. flags ::SDL_RendererFlags.

A valid rendering context or NULL if there was an error.

SDL_CreateSoftwareRenderer() SDL_GetRendererInfo() SDL_DestroyRenderer()

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 NIL if window creation failed.

\since This function is available since SDL 2.0.0.

\sa SDL_DestroyWindow

Create a system cursor.

\param id an SDL_SystemCursor enum value \returns a cursor on success or NULL on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_FreeCursor

Create a texture from an existing surface.

renderer The renderer. surface The surface containing pixel data used to fill the texture.

The created texture is returned, or 0 on error.

The surface is not modified or freed by this function.

SDL_QueryTexture() SDL_DestroyTexture()

Create a new thread with a specific stack size.

SDL makes an attempt to report `name` to the system, so that debuggers can display it. Not all platforms support this.

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:

https://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. You generally need to specify a stack that is a multiple of the system's page size (in many cases, this is 4 kilobytes, but check your system documentation).

In SDL 2.1, stack size will be folded into the original SDL_CreateThread function, but for backwards compatibility, this is currently a separate function.

\param fn the SDL_ThreadFunction function to call in the new thread \param name the name of the thread \param stacksize the size, in bytes, to allocate for the new thread stack. \param data a pointer that is passed to `fn` \returns an opaque pointer to the new thread object on success, NULL if the new thread could not be created; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.9.

\sa SDL_WaitThread

Create a window and default renderer

width The width of the window height The height of the window window_flags The flags used to create the window window A pointer filled with the window, or NULL on error renderer A pointer filled with the renderer, or NULL on error

0 on success, or -1 on error

Wait a specified number of milliseconds before returning.

/** \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 /

Destroy a condition variable.

\param cond the condition variable to destroy

\since This function is available since SDL 2.0.0.

Destroy the rendering context for a window and free associated textures.

SDL_CreateRenderer()

Destroy the specified texture.

SDL_CreateTexture() SDL_CreateTextureFromSurface()

Destroy the surface associated with the window.

\param window the window to update \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.28.0.

\sa SDL_GetWindowSurface \sa SDL_HasWindowSurface

Prevent the screen from being blanked by a screensaver

SDL_IsScreenSaverEnabled() SDL_EnableScreenSaver()

Allow the screen to be blanked by a screensaver

SDL_IsScreenSaverEnabled() SDL_DisableScreenSaver()

Calculate a minimal rectangle enclosing a set of points

SDL_TRUE if any points were within the clipping rect

This function allows you to set the state of processing certain events. - If state is set to SDL_IGNORE, that event will be automatically dropped from the event queue and will not event be filtered. - If state is set to SDL_ENABLE, that event will be processed normally. - If state is set to SDL_QUERY, SDL_EventState() will return the current processing state of the specified event.

Calculate the value of e (the base of natural logarithms) raised to the power of x.

\since This function is available since SDL 2.0.9.

Calculate the absolute value of x.

\since This function is available since SDL 2.0.8.

Request a window to demand attention from the user.

\param window the window to be flashed \param operation the flash operation \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.16.

Calculate the largest integral value that is not greater than x.

\since This function is available since SDL 2.0.8.

Calculate the floating-point remainder of dividing x by y.

\since This function is available since SDL 2.0.8.

Returns true if the rectangle has no area.

Returns true if the two rectangles are equal, within some given epsilon.

\since This function is available since SDL 2.0.22.

Free an audio stream

\since This function is available since SDL 2.0.7.

\sa SDL_NewAudioStream \sa SDL_AudioStreamPut \sa SDL_AudioStreamGet \sa SDL_AudioStreamAvailable \sa SDL_AudioStreamFlush \sa SDL_AudioStreamClear

Free an SDL_PixelFormat structure allocated by SDL_AllocFormat().

\param format the SDL_PixelFormat structure to free

\since This function is available since SDL 2.0.0.

\sa SDL_AllocFormat

Free data previously allocated with SDL_LoadWAV() or SDL_LoadWAV_RW().

After a WAVE file has been opened with SDL_LoadWAV() or SDL_LoadWAV_RW() its data can eventually be freed with SDL_FreeWAV(). It is safe to call this function with a NULL pointer.

\param audio_buf a pointer to the buffer created by SDL_LoadWAV() or SDL_LoadWAV_RW()

\since This function is available since SDL 2.0.0.

\sa SDL_LoadWAV \sa SDL_LoadWAV_RW

Close a controller previously opened with SDL_GameControllerOpen().

Return the SDL_GameController associated with an instance id.

Return the sfSymbolsName for a given axis on a game controller on Apple platforms.

Returns the sfSymbolsName, or NIL if the name can't be found. Do _not_ pass this string to SDL_free().

Returns SDL_TRUE if the controller has been opened and currently connected, or SDL_FALSE if it has not.

turn this string into a axis mapping

Get the SDL joystick layer binding for this controller button mapping

turn this string into a button mapping

Get the underlying joystick object used by a controller

Get the number of touchpads on a game controller.

Get the USB product ID of an opened controller, if available. If the product ID isn't available, this function returns 0.

Get the current state of a game controller sensor.

The number of values and interpretation of the data is sensor dependent. See sdlsensor.inc for the details for each type of sensor.

Get the current state of a game controller sensor with the timestamp of the last update.

The number of values and interpretation of the data is sensor dependent. See SDL_sensor.h for the details for each type of sensor.

\param gamecontroller The controller to query \param type The type of sensor to query \param timestamp A pointer filled with the timestamp in microseconds of the current sensor reading if available, or 0 if not \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.

\since This function is available since SDL 2.26.0.

Get the Steam Input handle of an opened controller, if available.

Returns an InputHandle_t for the controller that can be used with Steam Input API: https://partner.steamgames.com/doc/api/ISteamInput

\param gamecontroller the game controller object to query. \returns the gamepad handle, or 0 if unavailable.

\since This function is available since SDL 2.30.0.

turn this button enum into a string mapping

Get the type of this currently opened controller

This is the same name as returned by SDL_GameControllerTypeForIndex(), but it takes a controller identifier instead of the (unstable) device index.

Query whether a game controller has a given axis.

This merely reports whether the controller's mapping defined this axis, as that is all the information SDL has about the physical device.

Query whether a game controller has an LED.

Query whether a game controller has rumble support on triggers.

Query whether sensor data reporting is enabled for a game controller.

Get the mapping of a game controller. This can be called before any controllers are opened.

Returns the mapping string. Must be freed with SDL_free(). Returns NIL if no mapping is available.

Get the mapping at a particular index.

Returns the mapping string. Must be freed with SDL_free(). Returns NIL if the index is out of range.

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.

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 the value which will identify this controller in future controller events.

A controller identifier, or NULL if an error occurred.

Get the implementation dependent path for the game controller.

This function can be called before any controllers are opened.

`joystick_index` is the same as the `device_index` passed to SDL_JoystickOpen().

\param joystick_index the device_index of a device, from zero to SDL_NumJoysticks()-1 \returns the implementation-dependent path for the game controller, or NIL if there is no path or the index is invalid.

\since This function is available since SDL 2.24.0.

\sa SDL_GameControllerPath

Start a rumble effect in the game controller's triggers.

Each call to this function cancels any previous trigger rumble effect, and calling it with 0 intensity stops any rumbling.

Note that this is rumbling of the _triggers_ and not the game controller as a whole. This is currently only supported on Xbox One controllers. If you want the (more common) whole-controller rumble, use SDL_GameControllerRumble() instead.

Returns 0, or -1 if trigger rumble isn't supported on this controller

Update a game controller's LED color.

Returns 0, or -1 if this controller does not have a modifiable LED.

Set whether data reporting for a game controller sensor is enabled.

Update the current state of the open game controllers.

This is called automatically by the event loop if any game controller events are enabled.

Get the preferred audio format of a specific audio device.

This function is only valid after a successfully initializing the audio subsystem. The values returned by this function reflect the latest call to SDL_GetNumAudioDevices(); re-call that function to redetect available hardware.

`spec` will be filled with the sample rate, sample format, and channel count.

\param index the index of the audio device; valid values range from 0 to SDL_GetNumAudioDevices() - 1 \param iscapture non-zero to query the list of recording devices, zero to query the list of output devices. \param spec The SDL_AudioSpec to be initialized by this function. \returns 0 on success, nonzero on error

\since This function is available since SDL 2.0.16.

\sa SDL_GetNumAudioDevices \sa SDL_GetDefaultAudioInfo

Use this function to get the name of a built in audio driver.

The list of audio drivers is given in the order that they are normally initialized by default; the drivers that seem more reasonable to choose first (as far as the SDL developers believe) are earlier in the list.

The names of drivers are all simple, low-ASCII identifiers, like "alsa", "coreaudio" or "xaudio2". These never have Unicode characters, and are not meant to be proper names.

\param index the index of the audio driver; the value ranges from 0 to SDL_GetNumAudioDrivers() - 1 \returns the name of the audio driver at the requested index, or NULL if an invalid index was specified.

\since This function is available since SDL 2.0.0.

\sa SDL_GetNumAudioDrivers

Get the directory where the application was run from.

This is not necessarily a fast call, so you should call this once near startup and save the string if you need it.

**Mac OS X and iOS Specific Functionality**: If the application is in a ".app" bundle, this function returns the Resource directory (e.g. MyApp.app/Contents/Resources/). This behaviour can be overridden by adding a property to the Info.plist file. Adding a string key with the name SDL_FILESYSTEM_BASE_DIR_TYPE with a supported value will change the behaviour.

Supported values for the SDL_FILESYSTEM_BASE_DIR_TYPE property (Given an application in /Applications/SDLApp/MyApp.app):

- `resource`: bundle resource directory (the default). For example: `/Applications/SDLApp/MyApp.app/Contents/Resources` - `bundle`: the Bundle directory. For example: `/Applications/SDLApp/MyApp.app/` - `parent`: the containing directory of the bundle. For example: `/Applications/SDLApp/`

The returned path is guaranteed to end with a path separator ('\' on Windows, '/' on most other platforms).

The pointer returned is owned by the caller. Please call SDL_free() on the pointer when done with it.

\returns an absolute path in UTF-8 encoding to the application data directory. nil will be returned on error or when the platform doesn't implement this functionality, call SDL_GetError() for more information.

\since This function is available since SDL 2.0.1.

\sa SDL_GetPrefPath

Gets the clipping rectangle for the destination surface in a blit.

rect must be a pointer to a valid rectangle which will be filled with the correct values.

Gets the color key (transparent pixel) in a blittable surface.

surface The surface to update key A pointer filled in with the transparent pixel in the native surface format

0 on success, or -1 if the surface is not valid or colorkey is not enabled.

This function returns the number of CPU cores available.

Fill in information about the current display mode.

Get the active cursor.

This function returns a pointer to the current cursor which is owned by the library. It is not necessary to free the cursor with SDL_FreeCursor().

\returns the active cursor or NULL if there is no mouse.

\since This function is available since SDL 2.0.0.

\sa SDL_SetCursor

Get the default cursor.

\returns the default cursor on success or NULL on failure.

\since This function is available since SDL 2.0.0.

\sa SDL_CreateSystemCursor

Get the desktop area represented by a display, with the primary display located at 0,0

0 on success, or -1 if the index is out of range.

SDL_GetNumVideoDisplays()

Fill in information about a specific display mode.

The display modes are sorted in this priority: bits per pixel -> more colors to fewer colors width -> largest to smallest height -> largest to smallest refresh rate -> highest to lowest

SDL_GetNumDisplayModes()

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

\brief Get the last error message that was set

SDL API functions may set error messages and then succeed, so you should only use the error value if a function fails.

This returns a pointer to a static buffer for convenience and should not be called by multiple threads simultaneously.

\return a pointer to the last error message that was set

Return the current event filter - can be used to "chain" filters. If there is no event filter set, this function returns SDL_FALSE.

Get the current state of the mouse in relation to the desktop.

This works similarly to 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 filled in with the current X coord relative to the desktop; can be NULL \param y filled in with the current Y coord relative to the desktop; can be NULL \returns the current button state as a bitmask which can be tested using the SDL_BUTTON(X) macros.

\since This function is available since SDL 2.0.4.

\sa SDL_CaptureMouse

/** \brief Get a hint

\return The string value of a hint variable. /

Get the device information encoded in a SDL_JoystickGUID structure

\param guid the SDL_JoystickGUID you wish to get info about \param vendor A pointer filled in with the device VID, or 0 if not available \param product A pointer filled in with the device PID, or 0 if not available \param version A pointer filled in with the device version, or 0 if not available \param crc16 A pointer filled in with a CRC used to distinguish different products with the same VID/PID, or 0 if not available

\since This function is available since SDL 2.26.0.

\sa SDL_JoystickGetDeviceGUID

Get a snapshot of the current state of the keyboard.

The pointer returned is a pointer to an internal SDL array. It will be valid for the whole lifetime of the application and should not be freed by the caller.

A array element with a value of 1 means that the key is pressed and a value of 0 means that it is not. Indexes into this array are obtained by using SDL_Scancode values.

Use SDL_PumpEvents() to update the state array.

This function gives you the current state after all events have been processed, so if a key or button has been pressed and released before you process events, then the pressed state will never show up in the SDL_GetKeyboardState() calls.

Note: This function doesn't take into account whether shift has been pressed or not.

\param numkeys if non-nil, receives the length of the returned array \returns a pointer to an array of key states.

\since This function is available since SDL 2.0.0.

\sa SDL_PumpEvents \sa SDL_ResetKeyboard

Get the key code corresponding to the given scancode according to the current keyboard layout.

See SDL_Keycode for details.

\param scancode the desired SDL_Scancode to query \returns the SDL_Keycode that corresponds to the given SDL_Scancode.

\since This function is available since SDL 2.0.0.

\sa SDL_GetKeyName \sa SDL_GetScancodeFromKey

Get the current set of SDL memory functions

\since This function is available since SDL 2.0.7.

Get the window which currently has mouse focus.

\returns the window with mouse focus.

\since This function is available since SDL 2.0.0.

Get the number of outstanding (unfreed) allocations

\since This function is available since SDL 2.0.7.

Use this function to get the number of built-in audio drivers.

This function returns a hardcoded number. This never returns a negative value; if there are no drivers compiled into this build of SDL, this function returns zero. The presence of a driver in this list does not mean it will function, it just means SDL is capable of interacting with that interface. For example, a build of SDL might have esound support, but if there's no esound server available, SDL's esound driver would fail if used.

By default, SDL tries all drivers, in its preferred order, until one is found to be usable.

\returns the number of built-in audio drivers.

\since This function is available since SDL 2.0.0.

\sa SDL_GetAudioDriver

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.

SDL_GetRenderDriverInfo() SDL_CreateRenderer()

Get the number of active fingers for a given touch device.

Get the number of video drivers compiled into SDL

SDL_GetVideoDriver()

Get the current value of the high resolution counter

Get the human readable name of a pixel format.

\param format the pixel format to query \returns the human readable name of the specified pixel format or `SDL_PIXELFORMAT_UNKNOWN` if the format isn't recognized.

\since This function is available since SDL 2.0.0.

Get the index of the display containing a point

\param point the point to query \returns the index of the display containing the point or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.24.0.

\sa SDL_GetDisplayBounds \sa SDL_GetNumVideoDisplays

\brief Report the user's preferred locale.

This returns an array of SDL_Locale structs, the final item zeroed out. When the caller is done with this array, it should call SDL_free() on the returned value; all the memory involved is allocated in a single block, so a single SDL_free() will suffice.

Returned language strings are in the format xx, where 'xx' is an ISO-639 language specifier (such as 'en' for English, 'de' for German, etc). Country strings are in the format YY, where 'YY' is an ISO-3166 country code (such as "US" for the United States, 'CA' for Canada, etc). Country might be NULL if there's no specific guidance on them (so you might get ( 'en', 'US' ) for American English, but ( 'en', NIL ) means "English language, generically"). Language strings are never NIL, except to terminate the array.

Please note that not all of these strings are 2 characters; some are three or more.

The returned list of locales are in the order of the user's preference. For example, a German citizen that is fluent in US English and knows enough Japanese to navigate around Tokyo might have a list like: [ 'de', 'en_US', 'jp', NIL ]. Someone from England might prefer British English (where "color" is spelled "colour", etc), but will settle for anything like it: [ 'en_GB', 'en', NIL ].

This function returns NIL on error, including when the platform does not supply this information at all.

This might be a "slow" call that has to query the operating system. It's best to ask for this once and save the results. However, this list can change, usually because the user has changed a system preference outside of your program; SDL will send an SDL_LOCALECHANGED event in this case, if possible, and you can call this function again to get an updated copy of preferred locales.

\return array of locales, terminated with a locale with a NIL language field. Will return NIL on error.

Get UTF-8 text from the primary selection, which must be freed with SDL_free().

This functions returns empty string if there was not enough memory left for a copy of the primary selection's content.

\returns the primary selection text on success or an empty string on failure; call SDL_GetError() for more information. Caller must call SDL_free() on the returned pointer when done with it (even if there was an error).

\since This function is available since SDL 2.26.1.

\sa SDL_HasPrimarySelectionText \sa SDL_SetPrimarySelectionText

Get the index of the display primarily containing a rect

\param rect the rect to query \returns the index of the display entirely containing the rect or closest to the center of the rect on success or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.24.0.

\sa SDL_GetDisplayBounds \sa SDL_GetNumVideoDisplays

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 (where `X` is generally 1 for the left, 2 for middle, 3 for the right button), and `x` and `y` are set to the mouse deltas since the last call to SDL_GetRelativeMouseState() or since event initialization. You can pass NULL for either `x` or `y`.

\param x a pointer filled with the last recorded x coordinate of the mouse \param y a pointer filled with the last recorded y coordinate of the mouse \returns a 32-bit button bitmask of the relative button state.

\since This function is available since SDL 2.0.0.

\sa SDL_GetMouseState

Get the color used for drawing operations (Rect, Line and Clear).

renderer The renderer from which drawing color should be queried. r A pointer to the red value used to draw on the rendering target. g A pointer to the green value used to draw on the rendering target. b A pointer to the blue value used to draw on the rendering target. a A pointer to the alpha value used to draw on the rendering target, usually SDL_ALPHA_OPAQUE (255).

0 on success, or -1 on error

Get the renderer associated with a window.

Get the output size of a rendering context.

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.

Get RGB values from a pixel in the specified format.

This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).

\param pixel a pixel value \param format an SDL_PixelFormat structure describing the format of the pixel \param r a pointer filled in with the red component \param g a pointer filled in with the green component \param b a pointer filled in with the blue component

\since This function is available since SDL 2.0.0.

\sa SDL_GetRGBA \sa SDL_MapRGB \sa SDL_MapRGBA

Get the scancode corresponding to the given key code according to the current keyboard layout.

See SDL_Scancode for details.

\param key the desired SDL_Keycode to query \returns the SDL_Scancode that corresponds to the given SDL_Keycode.

\since This function is available since SDL 2.0.0.

\sa SDL_GetKeyFromScancode \sa SDL_GetScancodeName

Get a human-readable name for a scancode.

See SDL_Scancode for details.

**Warning**: The returned name is by design not stable across platforms, e.g. the name for `SDL_SCANCODE_LGUI` is "Left GUI" under Linux but "Left Windows" under Microsoft Windows, and some scancodes like `SDL_SCANCODE_NONUSBACKSLASH` don't have any name at all. There are even scancodes that share names, e.g. `SDL_SCANCODE_RETURN` and `SDL_SCANCODE_RETURN2` (both called "Return"). This function is therefore unsuitable for creating a stable cross-platform two-way mapping between strings and scancodes.

\param scancode the desired SDL_Scancode to query \returns a pointer to the name for the scancode. If the scancode doesn't have a name this function returns an empty string ("").

\since This function is available since SDL 2.0.0.

\sa SDL_GetScancodeFromKey \sa SDL_GetScancodeFromName

Get the additional alpha value used in blit operations.

surface The surface to query. alpha A pointer filled in with the current alpha value.

0 on success, or -1 if the surface is not valid.

SDL_SetSurfaceAlphaMod()

Get the additional color value used in blit operations.

surface The surface to query. r A pointer filled in with the current red color value. g A pointer filled in with the current green color value. b A pointer filled in with the current blue color value.

0 on success, or -1 if the surface is not valid.

SDL_SetSurfaceColorMod()

Get the additional alpha value used in render copy operations.

texture The texture to query. alpha A pointer filled in with the current alpha value.

0 on success, or -1 if the texture is not valid.

SDL_SetTextureAlphaMod()

Get the additional color value used in render copy operations.

texture The texture to query. r A pointer filled in with the current red color value. g A pointer filled in with the current green color value. b A pointer filled in with the current blue color value.

0 on success, or -1 if the texture is not valid.

SDL_SetTextureColorMod()

Get the user-specified pointer associated with a texture.

Get the thread name as it was specified in SDL_CreateThread().

This is internal memory, not to be freed by the caller, and remains valid until the specified thread is cleaned up by SDL_WaitThread().

\param thread the thread to query \returns a pointer to a UTF-8 string that names the specified thread, or NULL if it doesn't have a name.

\since This function is available since SDL 2.0.0.

\sa SDL_CreateThread

Get the number of milliseconds since SDL library initialization.

Note that you should not use the SDL_TICKS_PASSED macro with values returned by this function, as that macro does clever math to compensate for the 32-bit overflow every ˜49 days that SDL_GetTicks() suffers from. 64-bit values from this function can be safely compared directly.

Get the type of the given touch device.

\since This function is available since SDL 2.0.10.

Get the touch device name as reported from the driver, or NIL if the index is invalid.

\since This function is available since SDL 2.0.22.

Get the name of a built in video driver.

The video drivers are presented in the order in which they are normally checked during initialization.

SDL_GetNumVideoDrivers()

Get the brightness (gamma correction) for a window.

The last brightness value passed to SDL_SetWindowBrightness()

SDL_SetWindowBrightness()

Get the display index associated with a window.

the display index of the display containing the center of the window, or -1 on error.

Get the window flags.

Get the gamma ramp for a window.

red A pointer to a 256 element array of 16-bit quantities to hold the translation table for the red channel, or nil. green A pointer to a 256 element array of 16-bit quantities to hold the translation table for the green channel, or nil. blue A pointer to a 256 element array of 16-bit quantities to hold the translation table for the blue channel, or nil.

0 on success, or -1 if gamma ramps are unsupported.

SDL_SetWindowGammaRamp()

Get the raw ICC profile data for the screen the window is currently on.

Data returned should be freed with SDL_free().

\param window the window to query \param size the size of the ICC profile \returns the raw ICC profile data on success or NIL on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.18.

Get a window's keyboard grab mode.

Returns SDL_TRUE if keyboard is grabbed, and SDL_FALSE otherwise.

SDL_SetWindowKeyboardGrab()

Get the minimum size of a window's client area.

w Pointer to variable for storing the minimum width, may be nil h Pointer to variable for storing the minimum height, may be nil

SDL_GetWindowMaximumSize() SDL_SetWindowMinimumSize()

Get the mouse confinement rectangle of a window.

Returns A pointer to the mouse confinement rectangle of a window, or NULL if there isn't one.

SDL_SetWindowMouseRect()

Get the pixel format associated with the window.

Get the size of a window's client area.

w Pointer to variable for storing the width, may be nil h Pointer to variable for storing the height, may be nil

SDL_SetWindowSize()

Get the SDL surface associated with the window.

The window's framebuffer surface, or nil 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.

You may not combine this with 3D or the rendering API on this window.

SDL_UpdateWindowSurface() SDL_UpdateWindowSurfaceRects()

Get driver-specific information about a window.

You must include SDL_syswm.h for the declaration of SDL_SysWMinfo.

The caller must initialize the `info` structure's version by using `SDL_VERSION(&info.version)`, and then this function will fill in the rest of the structure with information about the given window.

\param window the window about which information is being requested \param info an SDL_SysWMinfo structure filled in with window information \returns SDL_TRUE if the function is implemented and the `version` member of the `info` struct is valid, or SDL_FALSE if the information could not be retrieved; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\brief Get the YUV conversion mode, returning the correct mode for the resolution when the current conversion mode is SDL_YUV_CONVERSION_AUTOMATIC

Bind the texture to the current OpenGL/ES/ES2 context for use with OpenGL instructions.

texture The SDL texture to bind texw A pointer to a float that will be filled with the texture width texh A pointer to a float that will be filled with the texture height

0 on success, or -1 if the operation is not supported

Delete an OpenGL context.

SDL_GL_CreateContext()

Get the actual value for an attribute from the current context.

Get the currently active OpenGL window.

Get the address of an OpenGL function.

Dynamically load an OpenGL library.

path The platform dependent OpenGL library name, or nil to open the default OpenGL library.

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.

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

SDL_GL_GetProcAddress() SDL_GL_UnloadLibrary()

Reset all previously set OpenGL context attributes to their default values

Set the swap interval for the current OpenGL context.

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.

0 on success, or -1 if setting the swap interval is not supported.

SDL_GL_GetSwapInterval()

Unbind a texture from the current OpenGL/ES/ES2 context.

texture The SDL texture to unbind

0 on success, or -1 if the operation is not supported

Convert a GUID string into a ::SDL_GUID structure.

Performs no error checking. If this function is given a string containing an invalid GUID, the function will silently succeed, but the GUID generated will not be useful.

\param pchGUID string containing an ASCII representation of a GUID \returns a ::SDL_GUID structure.

\since This function is available since SDL 2.24.0.

\sa SDL_GUIDToString

Close a haptic device previously opened with SDL_HapticOpen().

\param haptic the SDL_Haptic device to close

\since This function is available since SDL 2.0.0.

\sa SDL_HapticOpen

Check to see if an effect is supported by a haptic device.

\param haptic the SDL_Haptic device to query \param effect the desired effect to query \returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't, or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_HapticNewEffect \sa SDL_HapticQuery

Get the index of a haptic device.

\param haptic the SDL_Haptic device to query \returns the index of the specified haptic device or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_HapticOpen \sa SDL_HapticOpened

Create a new haptic effect on a specified device.

\param haptic an SDL_Haptic device to create the effect on \param effect an SDL_HapticEffect structure containing the properties of the effect to create \returns the ID of the effect on success or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_HapticDestroyEffect \sa SDL_HapticRunEffect \sa SDL_HapticUpdateEffect

Get 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 SDL_Haptic device to query \returns the number of effects the haptic device can store or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_HapticNumEffectsPlaying \sa SDL_HapticQuery

Open 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 \returns the device identifier or NULL on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_HapticClose \sa SDL_HapticIndex \sa SDL_HapticOpenFromJoystick \sa SDL_HapticOpenFromMouse \sa SDL_HapticPause \sa SDL_HapticSetAutocenter \sa SDL_HapticSetGain \sa SDL_HapticStopAll

Open 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 opened 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 the SDL_Joystick to create a haptic device from \returns a valid haptic device identifier on success or NULL on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_HapticClose \sa SDL_HapticOpen \sa SDL_JoystickIsHaptic

Pause 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 the SDL_Haptic device to pause \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_HapticUnpause

Initialize a haptic device for simple rumble playback.

\param haptic the haptic device to initialize for simple rumble playback \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_HapticOpen \sa SDL_HapticRumblePlay \sa SDL_HapticRumbleStop \sa SDL_HapticRumbleSupported

Stop the simple rumble on a haptic device.

\param haptic the haptic device to stop the rumble effect on \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_HapticRumbleInit \sa SDL_HapticRumblePlay \sa SDL_HapticRumbleSupported

Run the haptic effect on its associated haptic device.

To repeat the effect over and over indefinitely, set `iterations` to `SDL_HAPTIC_INFINITY`. (Repeats the envelope - attack and fade.) To make one instance of the effect last indefinitely (so the effect does not fade), set the effect's `length` in its structure/union to `SDL_HAPTIC_INFINITY` instead.

\param haptic the SDL_Haptic device to run the effect on \param effect the ID of the haptic effect to run \param iterations the number of iterations to run the effect; use `SDL_HAPTIC_INFINITY` to repeat forever \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_HapticDestroyEffect \sa SDL_HapticGetEffectStatus \sa SDL_HapticStopEffect

Set the global gain of the specified haptic 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 the SDL_Haptic device to set the gain on \param gain value to set the gain to, should be between 0 and 100 (0 - 100) \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_HapticQuery

Stop the haptic effect on its associated haptic device.

*

\param haptic the SDL_Haptic device to stop the effect on \param effect the ID of the haptic effect to stop \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_HapticDestroyEffect \sa SDL_HapticRunEffect

Update the properties of an effect.

Can be used dynamically, although behavior when dynamically changing direction may be strange. Specifically the effect may re-upload itself and start playing from the start. You also cannot change the type either when running SDL_HapticUpdateEffect().

\param haptic the SDL_Haptic device that has the effect \param effect the identifier of the effect to update \param data an SDL_HapticEffect structure containing the new effect properties to use \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_HapticDestroyEffect \sa SDL_HapticNewEffect \sa SDL_HapticRunEffect

This function returns true if the CPU has AltiVec features.

This always returns false on CPUs that aren't using PowerPC instruction sets.

This function returns true if the CPU has AVX features.

This always returns false on CPUs that aren't using Intel instruction sets.

Determine whether the CPU has AVX-512F (foundation) features.

This always returns false on CPUs that aren't using Intel instruction sets.

\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

Determine whether two rectangles intersect with float precision.

If either pointer is NIL the function will return SDL_FALSE.

\param A an SDL_FRect structure representing the first rectangle \param B an SDL_FRect structure representing the second rectangle \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.

\since This function is available since SDL 2.0.22.

\sa SDL_IntersectRect

Determine whether the CPU has NEON (ARM SIMD) features.

This always returns false on CPUs that aren't using ARM instruction sets.

This function returns true if the CPU has the RDTSC instruction.

This always returns false on CPUs that aren't using Intel instruction sets.

This function returns true if the CPU has SSE features.

This always returns false on CPUs that aren't using Intel instruction sets.

This function returns true if the CPU has SSE3 features.

This always returns false on CPUs that aren't using Intel instruction sets.

This function returns true if the CPU has SSE4.2 features.

This always returns false on CPUs that aren't using Intel instruction sets.

Return whether the window has a surface associated with it.

\returns SDL_TRUE if there is a surface associated with the window, or SDL_FALSE otherwise.

\since This function is available since SDL 2.28.0.

\sa SDL_GetWindowSurface

Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers

\param active SDL_TRUE to start the scan, SDL_FALSE to stop the scan

\since This function is available since SDL 2.0.18.

Check to see if devices may have been added or removed.

Enumerating the HID devices is an expensive operation, so you can call this to see if there have been any system device changes since the last call to this function. A change in the counter returned doesn't necessarily mean that anything has changed, but you can call SDL_hid_enumerate() to get an updated device list.

Calling this function for the first time may cause a thread or other system resource to be allocated to track device change notifications.

\returns a change counter that is incremented with each potential device change, or 0 if device change detection isn't available.

\since This function is available since SDL 2.0.18.

\sa SDL_hid_enumerate

Finalize the HIDAPI library.

This function frees all of the static data associated with HIDAPI. It should be called at the end of execution to avoid memory leaks.

\returns 0 on success and -1 on error.

\since This function is available since SDL 2.0.18.

\sa SDL_hid_init

Get a feature report from a HID device.

Set the first byte of `data` to the Report ID of the report to be read. Make sure to allow space for this extra byte in `data`. Upon return, the first byte will still contain the Report ID, and the report data will start in data[1].

\param dev A device handle returned from SDL_hid_open(). \param data A buffer to put the read data into, including the Report ID. Set the first byte of `data` to the Report ID of the report to be read, or set it to zero if your device does not use numbered reports. \param length The number of bytes to read, including an extra byte for the report ID. The buffer can be longer than the actual report. \returns the number of bytes read plus one for the report ID (which is still in the first byte), or -1 on error.

\since This function is available since SDL 2.0.18.

Get The Manufacturer String from a HID device.

\param dev A device handle returned from SDL_hid_open(). \param string A wide string buffer to put the data into. \param maxlen The length of the buffer in multiples of wchar_t. \returns 0 on success and -1 on error.

\since This function is available since SDL 2.0.18.

Get The Serial Number String from a HID device.

\param dev A device handle returned from SDL_hid_open(). \param string A wide string buffer to put the data into. \param maxlen The length of the buffer in multiples of wchar_t. \returns 0 on success and -1 on error.

\since This function is available since SDL 2.0.18.

Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally a serial number.

If `serial_number` is NULL, the first device with the specified VID and PID is opened.

\param vendor_id The Vendor ID (VID) of the device to open. \param product_id The Product ID (PID) of the device to open. \param serial_number The Serial Number of the device to open (optionally NIL). \returns a pointer to a SDL_hid_device object on success or NIL on failure.

\since This function is available since SDL 2.0.18.

Read an Input report from a HID device.

Input reports are returned to the host through the INTERRUPT IN endpoint. The first byte will contain the Report number if the device uses numbered reports.

\param dev A device handle returned from SDL_hid_open(). \param data A buffer to put the read data into. \param length The number of bytes to read. For devices with multiple reports, make sure to read an extra byte for the report number. \returns the actual number of bytes read and -1 on error. If no packet was available to be read and the handle is in non-blocking mode, this function returns 0.

\since This function is available since SDL 2.0.18.

Send a Feature report to the device.

Feature reports are sent over the Control endpoint as a Set_Report transfer. The first byte of `data` must contain the Report ID. For devices which only support a single report, this must be set to 0x0. The remaining bytes contain the report data. Since the Report ID is mandatory, calls to SDL_hid_send_feature_report() will always contain one more byte than the report contains. For example, if a hid report is 16 bytes long, 17 bytes must be passed to SDL_hid_send_feature_report(): the Report ID (or 0x0, for devices which do not use numbered reports), followed by the report data (16 bytes). In this example, the length passed in would be 17.

\param dev A device handle returned from SDL_hid_open(). \param data The data to send, including the report number as the first byte. \param length The length in bytes of the data to send, including the report number. \returns the actual number of bytes written and -1 on error.

\since This function is available since SDL 2.0.18.

Write an Output report to a HID device.

The first byte of `data` must contain the Report ID. For devices which only support a single report, this must be set to 0x0. The remaining bytes contain the report data. Since the Report ID is mandatory, calls to SDL_hid_write() will always contain one more byte than the report contains. For example, if a hid report is 16 bytes long, 17 bytes must be passed to SDL_hid_write(), the Report ID (or 0x0, for devices with a single report), followed by the report data (16 bytes). In this example, the length passed in would be 17.

SDL_hid_write() will send the data on the first OUT endpoint, if one exists. If it does not, it will send the data through the Control Endpoint (Endpoint 0).

\param dev A device handle returned from SDL_hid_open(). \param data The data to send, including the report number as the first byte. \param length The length in bytes of the data to send. \returns the actual number of bytes written and -1 on error.

\since This function is available since SDL 2.0.18.

This function converts a string between encodings in one pass, returning a string that must be freed with SDL_free(), or NIL on error.

\since This function is available since SDL 2.0.0.

SDL_imageFilterAbsDiff: D = | S1 - S2 |

SDL_imageFilterAddByte: D = saturation255(S + C)

SDL_imageFilterAddUsInt32: D = saturation255(S + (usInt32)C)

SDL_imageFilterBitAnd: D = S1 & S2

SDL_imageFilterBitOr: D = S1 | S2

SDL_imageFilterDiv: D = S1 / S2 (non-MMX)

Detect MMX capability in CPU

SDL_imageFilterMultByByte: D = saturation255(S * C)

SDL_imageFilterMultDivby4: D = saturation255(S1/2 * S2/2)

SDL_imageFilterNormalizeLinear: D = saturation255((Nmax - Nmin)/(Cmax - Cmin)*(S - Cmin) + Nmin)

SDL_imageFilterShiftLeftByte: D = (S << N)

SDL_imageFilterShiftRight: D = saturation0(S >> N)

SDL_imageFilterShiftRightUsInt32: D = saturation0((usInt32)S >> N)

SDL_imageFilterSubByte: D = saturation0(S - C)

This macro can be used to fill a version structure with the compile-time version of the SDL_image library.

Calculate the intersection of two rectangles with float precision.

If `result` is NIL then this function will return SDL_FALSE.

\param A an SDL_FRect structure representing the first rectangle \param B an SDL_FRect structure representing the second rectangle \param result an SDL_FRect structure filled in with the intersection of rectangles `A` and `B` \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.

\since This function is available since SDL 2.0.22.

\sa SDL_HasIntersectionF

Calculate the intersection of two rectangles.

SDL_TRUE if there is an intersection, SDL_FALSE otherwise.

Check if the provided ASCII character is an alphanumeric character.

\returns 1 if the check passes, 0 otherwise.

\since This function is available since SDL 2.0.16.

Check if the provided ASCII character is a blank character (a space or a tab).

\returns 1 if the check passes, 0 otherwise.

\since This function is available since SDL 2.0.16.

Check if the provided ASCII character is a decimal digit.

\returns 1 if the check passes, 0 otherwise.

\since This function is available since SDL 2.0.4.

Check if the provided ASCII character is a printable character (excluding space).

\returns 1 if the check passes, 0 otherwise.

\since This function is available since SDL 2.0.16.

The flag is set to 1 because 0x1? is not in the printable ASCII range *

Check if the provided ASCII character is any printable character which is not a space or an alphanumeric character.

\returns 1 if the check passes, 0 otherwise.

\since This function is available since SDL 2.0.16.

Returns whether the screensaver is currently enabled (default on).

SDL_EnableScreenSaver() SDL_DisableScreenSaver()

Check if the provided ASCII character is a whitespace character. This set includes the following characters: space, form feed (FF), newline/line feed (LF), carriage return (CR), horizontal tab (HT), vertical tab (VT).

\returns 1 if the check passes, 0 otherwise.

\since This function is available since SDL 2.0.4.

Check whether or not Unicode text input events are enabled.

\returns SDL_TRUE if text input events are enabled else SDL_FALSE.

\since This function is available since SDL 2.0.0.

\sa SDL_StartTextInput

Check if the provided ASCII character is an uppercase letter.

\returns 1 if the check passes, 0 otherwise.

\since This function is available since SDL 2.0.12.

Attach a new virtual joystick.

\returns the joystick's device index, or -1 if an error occurred.

\since This function is available since SDL 2.0.14.

Close a joystick previously opened with SDL_JoystickOpen().

\param joystick The joystick device to close

\since This function is available since SDL 2.0.0.

\sa SDL_JoystickOpen

Detach a virtual joystick.

\param device_index a value previously returned from SDL_JoystickAttachVirtual() \returns 0 on success, or -1 if an error occurred.

\since This function is available since SDL 2.0.14.

Get the SDL_Joystick associated with an instance id.

\param instance_id the instance id to get the SDL_Joystick for \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.4.

Get the status of a specified joystick.

\param joystick the joystick to query \returns SDL_TRUE if the joystick has been opened, SDL_FALSE if it has not; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_JoystickClose \sa SDL_JoystickOpen

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.

\param joystick an SDL_Joystick structure containing joystick information \param axis the axis to query; the axis indices start at index 0 \param state Upon return, the initial value is supplied here. \return SDL_TRUE if this axis has any initial value, or SDL_FALSE if not.

\since This function is available since SDL 2.0.6.

Get the current state of a button on a joystick.

\param joystick an SDL_Joystick structure containing joystick information \param button the button index to get the state from; indices start at index 0 \returns 1 if the specified button is pressed, 0 otherwise.

\since This function is available since SDL 2.0.0.

\sa SDL_JoystickNumButtons

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.

\param device_index the index of the joystick to query (the N'th joystick on the system \returns the instance id of the selected joystick. If called on an invalid index, this function returns zero

\since This function is available since SDL 2.0.6.

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.

\param device_index the index of the joystick to query (the N'th joystick on the system \returns the USB product ID of the selected joystick. If called on an invalid index, this function returns zero

\since This function is available since SDL 2.0.6.

Get the type of a joystick, if available.

This can be called before any joysticks are opened.

\param device_index the index of the joystick to query (the N'th joystick on the system \returns the SDL_JoystickType of the selected joystick. If called on an invalid index, this function returns `SDL_JOYSTICK_TYPE_UNKNOWN`

\since This function is available since SDL 2.0.6.

Get the firmware version of an opened joystick, if available.

If the firmware version isn't available this function returns 0.

\param joystick the SDL_Joystick obtained from SDL_JoystickOpen() \returns the firmware version of the selected joystick, or 0 if unavailable.

\since This function is available since SDL 2.24.0.

Convert a GUID string into a SDL_JoystickGUID structure.

Performs no error checking. If this function is given a string containing an invalid GUID, the function will silently succeed, but the GUID generated will not be useful.

\param pchGUID string containing an ASCII representation of a GUID \returns a SDL_JoystickGUID structure.

\since This function is available since SDL 2.0.0.

\sa SDL_JoystickGetGUIDString

Get the current state of a POV hat on a joystick.

The returned value will be 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`

\param joystick an SDL_Joystick structure containing joystick information \param hat the hat index to get the state from; indices start at index 0 \returns the current hat position.

\since This function is available since SDL 2.0.0.

\sa SDL_JoystickNumHats

Get the USB product ID of an opened joystick, if available.

If the product ID isn't available this function returns 0.

\param joystick the SDL_Joystick obtained from SDL_JoystickOpen() \returns the USB product ID of the selected joystick, or 0 if unavailable.

\since This function is available since SDL 2.0.6.

Get the serial number of an opened joystick, if available.

Returns the serial number of the joystick, or NULL if it is not available.

\param joystick the SDL_Joystick obtained from SDL_JoystickOpen() \returns the serial number of the selected joystick, or NULL if unavailable.

\since This function is available since SDL 2.0.14.

Get the USB vendor ID of an opened joystick, if available.

If the vendor ID isn't available this function returns 0.

\param joystick the SDL_Joystick obtained from SDL_JoystickOpen() \returns the USB vendor ID of the selected joystick, or 0 if unavailable.

\since This function is available since SDL 2.0.6.

Query whether a joystick has rumble support.

\param joystick The joystick to query \return SDL_TRUE if the joystick has rumble, SDL_FALSE otherwise.

\since This function is available since SDL 2.0.18.

\sa SDL_JoystickRumble

Get the instance ID of an opened joystick.

\param joystick an SDL_Joystick structure containing joystick information \returns the instance ID of the specified joystick on success or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_JoystickOpen

Query whether or not the joystick at a given device index is virtual.

\param device_index a joystick device index. \returns SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise.

\since This function is available since SDL 2.0.14.

Get the implementation dependent name of a joystick.

This can be called before any joysticks are opened.

\param device_index the index of the joystick to query (the N'th joystick on the system) \returns the name of the selected joystick. If no name can be found, this function returns NULL; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_JoystickName \sa SDL_JoystickOpen

Get the number of trackballs on a joystick.

Joystick trackballs have only relative motion events associated with them and their state cannot be polled.

Most joysticks do not have trackballs.

\param joystick an SDL_Joystick structure containing joystick information \returns the number of trackballs on success or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_JoystickGetBall

Get the number of POV hats on a joystick.

\param joystick an SDL_Joystick structure containing joystick information \returns the number of POV hats on success or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_JoystickGetHat \sa SDL_JoystickOpen

Get the implementation dependent path of a joystick.

\param joystick the SDL_Joystick obtained from SDL_JoystickOpen() \returns the path of the selected joystick. If no path can be found, this function returns NULL; call SDL_GetError() for more information.

\since This function is available since SDL 2.24.0.

\sa SDL_JoystickPathForIndex

Start 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 \returns 0, or -1 if rumble isn't supported on this joystick

\since This function is available since SDL 2.0.9.

\sa SDL_JoystickHasRumble

Send a joystick specific effect packet

\param joystick The joystick to affect \param data The data to send to the joystick \param size The size of the data to send to the joystick \returns 0, or -1 if this joystick or driver doesn't support effect packets

\since This function is available since SDL 2.0.16.

Set the player index of an opened joystick.

\param joystick the SDL_Joystick obtained from SDL_JoystickOpen() \param player_index Player index to assign to this joystick, or -1 to clear the player index and turn off player LEDs.

\since This function is available since SDL 2.0.12.

Set values on an opened, virtual-joystick's button.

Please note that values set here will not be applied until the next call to SDL_JoystickUpdate, which can either be called directly, or can be called indirectly through various other SDL APIs, including, but not limited to the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout, SDL_WaitEvent.

\param joystick the virtual joystick on which to set state. \param button the specific button on the virtual joystick to set. \param value the new value for the specified button. \returns 0 on success, -1 on error.

\since This function is available since SDL 2.0.14.

Update the current state of the open joysticks.

This is called automatically by the event loop if any joystick events are enabled.

\since This function is available since SDL 2.0.0.

\sa SDL_JoystickEventState

Load a surface from a seekable SDL data stream (memory or file).

If freesrc is non-zero, the stream will be closed after being read.

The new surface should be freed with SDL_FreeSurface().

the new surface, or NULL if there was an error.

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.

Look up the address of the named function in a shared object.

This function pointer is no longer valid after calling SDL_UnloadObject().

This function can only look up C function names. Other languages may have name mangling and intrinsic language support that varies from compiler to compiler.

Make sure you declare your function pointers with the same calling convention as the actual library function. Your code will crash mysteriously if you do not do this.

If the requested function doesn't exist, nil is returned.

\param handle a valid shared object handle returned by SDL_LoadObject() \param name the name of the function to look up \returns a pointer to the function or nil if there was an error; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_LoadObject \sa SDL_UnloadObject

Loads a WAV from a file. Compatibility convenience function.

This function is a legacy means of locking the audio device.

New programs might want to use SDL_LockAudioDevice() instead. This function is equivalent to calling...

```c SDL_LockAudioDevice(1); ```

...and is only useful if you used the legacy SDL_OpenAudio() function.

\since This function is available since SDL 2.0.0.

\sa SDL_LockAudioDevice \sa SDL_UnlockAudio \sa SDL_UnlockAudioDevice

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.

As of SDL 2.26.0, you can take the joystick lock around reinitializing the joystick subsystem, to prevent other threads from seeing joysticks in an uninitialized state. However, all open joysticks will be closed and SDL functions called with them will fail.

\since This function is available since SDL 2.0.7.

Locking for multi-threaded access to the sensor API

If you are using the sensor API or handling events from multiple threads you should use these locking functions to protect access to the sensors.

In particular, you are guaranteed that the sensor list won't change, so the API functions that take a sensor index will be valid, and sensor events will not be delivered.

\since This function is available since SDL 2.0.14.

Lock a portion of the texture for write-only pixel access.

texture The texture to lock for access, which was created with SDL_TEXTUREACCESS_STREAMING. rect A pointer to the rectangle to lock for access. If the rect is NULL, the entire texture will be locked. pixels This is filled in with a pointer to the locked pixels, appropriately offset by the locked area. pitch This is filled in with the pitch of the locked pixels.

0 on success, or -1 if the texture is not valid or was not created with ::SDL_TEXTUREACCESS_STREAMING.

SDL_UnlockTexture()

\brief Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO

Calculate the base 10 logarithm of x.

\since This function is available since SDL 2.0.8.

\brief Log a message with SDL_LOG_PRIORITY_DEBUG

\brief Get the current log output function.

\brief Log a message with SDL_LOG_PRIORITY_INFO

\brief Log a message with the specified category and priority.

\brief Set the priority of all log categories

\brief Set the priority of a particular log category

\brief Log a message with SDL_LOG_PRIORITY_WARN

This is a semi-private blit function and it performs low-level surface scaled blitting only.

Round to nearest integer, away from zero.

\since This function is available since SDL 2.0.16.

Map an RGB triple to an opaque pixel value for a given pixel format.

This function maps the RGB color value to the specified pixel format and returns the pixel value best approximating the given RGB color value for the given pixel format.

If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned.

If the specified pixel format has an alpha component it will be returned as all 1 bits (fully opaque).

If the pixel format bpp (color depth) is less than 32-bpp then the unused upper bits of the return value can safely be ignored (e.g., with a 16-bpp format the return value can be assigned to a Uint16, and similarly a Uint8 for an 8-bpp format).

\param format an SDL_PixelFormat structure describing the pixel format \param r the red component of the pixel in the range 0-255 \param g the green component of the pixel in the range 0-255 \param b the blue component of the pixel in the range 0-255 \returns a pixel value

\since This function is available since SDL 2.0.0.

\sa SDL_GetRGB \sa SDL_GetRGBA \sa SDL_MapRGBA

Convert a bpp value and RGBA masks to an enumerated pixel format.

This will return `SDL_PIXELFORMAT_UNKNOWN` if the conversion wasn't possible.

\param bpp a bits per pixel value; usually 15, 16, or 32 \param Rmask the red mask for the format \param Gmask the green mask for the format \param Bmask the blue mask for the format \param Amask the alpha mask for the format \returns one of the SDL_PixelFormatEnum values

\since This function is available since SDL 2.0.0.

\sa SDL_PixelFormatEnumToMasks

Minimize a window to an iconic representation.

SDL_RestoreWindow()

Mix audio data in a specified format.

This takes an audio buffer `src` of `len` bytes of `format` data and mixes it into `dst`, performing addition, volume adjustment, and overflow clipping. The buffer pointed to by `dst` must also be `len` bytes of `format` data.

This is provided for convenience – you can mix your own audio data.

Do not use this function for mixing together more than two streams of sample data. The output from repeated application of this function may be distorted by clipping, because there is no accumulator with greater range than the input (not to mention this being an inefficient way of doing it).

It is a common misconception that this function is required to write audio data to an output stream in an audio callback. While you can do that, SDL_MixAudioFormat() is really only needed when you're mixing a single audio stream with a volume adjustment.

\param dst the destination for the mixed audio \param src the source audio buffer to be mixed \param format the SDL_AudioFormat structure representing the desired audio format \param len the length of the audio buffer in bytes \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME for full audio volume

\since This function is available since SDL 2.0.0.

Query whether or not the current mouse has haptic capabilities.

\returns SDL_TRUE if the mouse is haptic or SDL_FALSE if it isn't.

\since This function is available since SDL 2.0.0.

\sa SDL_HapticOpenFromMouse

This macro can be used to fill a version structure with the compile-time version of the SDL_net library.

Calculate the natural logarithm of x.

\since This function is available since SDL 2.0.4.

SDL2-for-Pascal: ATTENTION: The original C name of this function is SDL_log, but since Pascal names are case-insensitive, it is in conflict with SDL_Log (logging function). Hence we decided to rename it.

Count the number of haptic devices attached to the system.

\returns the number of haptic devices detected on the system or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_HapticName

Count the number of sensors attached to the system right now.

\returns the number of sensors detected.

\since This function is available since SDL 2.0.9.

Functions used by iOS application delegates to notify SDL about state changes

Open a specific audio device.

SDL_OpenAudio(), unlike this function, always acts on device ID 1. As such, this function will never return a 1 so as not to conflict with the legacy function.

Please note that SDL 2.0 before 2.0.5 did not support recording; as such, this function would fail if `iscapture` was not zero. Starting with SDL 2.0.5, recording is implemented and this value can be non-zero.

Passing in a `device` name of NULL requests the most reasonable default (and is equivalent to what SDL_OpenAudio() does to choose a device). 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.

An opened audio device starts out paused, and should be enabled for playing by calling SDL_PauseAudioDevice(devid, 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.

The audio callback runs in a separate thread in most cases; you can prevent race conditions between your callback and other threads without fully pausing playback with SDL_LockAudioDevice(). For more information about the callback, see SDL_AudioSpec.

Managing the audio spec via 'desired' and 'obtained':

When filling in the desired audio spec structure:

- `desired->freq` should be the frequency in sample-frames-per-second (Hz). - `desired->format` should be the audio format (`AUDIO_S16SYS`, etc). - `desired->samples` is the desired size of the audio buffer, in _sample frames_ (with stereo output, two samples–left and right–would make a single sample frame). 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 reduce latency, but can lead to underflow if the application is doing heavy processing and cannot fill the audio buffer in time. Note that the number of sample frames is directly related to time by the following formula: `ms = (sampleframes*1000)/freq` - `desired->size` is the size in _bytes_ of the audio buffer, and is calculated by SDL_OpenAudioDevice(). You don't initialize this. - `desired->silence` is the value used to set the buffer to silence, and is calculated by SDL_OpenAudioDevice(). You don't initialize this. - `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_LockAudioDevice() and SDL_UnlockAudioDevice() 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). - `desired->userdata` is passed as the first parameter to your callback function. If you passed a NULL callback, this value is ignored.

`allowed_changes` can have the following flags OR'd together:

- `SDL_AUDIO_ALLOW_FREQUENCY_CHANGE` - `SDL_AUDIO_ALLOW_FORMAT_CHANGE` - `SDL_AUDIO_ALLOW_CHANNELS_CHANGE` - `SDL_AUDIO_ALLOW_SAMPLES_CHANGE` - `SDL_AUDIO_ALLOW_ANY_CHANGE`

These flags specify how SDL should behave when a device cannot offer a specific feature. If the application requests a feature that the hardware doesn't offer, SDL will always try to get the closest equivalent.

For example, if you ask for float32 audio format, but the sound card only supports int16, SDL will set the hardware to int16. If you had set SDL_AUDIO_ALLOW_FORMAT_CHANGE, SDL will change the format in the `obtained` structure. If that flag was *not* set, SDL will prepare to convert your callback's float32 audio to int16 before feeding it to the hardware and will keep the originally requested format in the `obtained` structure.

The resulting audio specs, varying depending on hardware and on what changes were allowed, will then be written back to `obtained`.

If your application can only handle one specific data format, pass a zero for `allowed_changes` and let SDL transparently handle any differences.

\param device a UTF-8 string reported by SDL_GetAudioDeviceName() or a driver-specific name as appropriate. NULL requests the most reasonable default device. \param iscapture non-zero to specify a device should be opened for recording, not playback \param desired an SDL_AudioSpec structure representing the desired output format; see SDL_OpenAudio() for more information \param obtained an SDL_AudioSpec structure filled in with the actual output format; see SDL_OpenAudio() for more information \param allowed_changes 0, or one or more flags OR'd together \returns a valid device ID that is > 0 on success or 0 on failure; call SDL_GetError() for more information.

For compatibility with SDL 1.2, this will never return 1, since SDL reserves that ID for the legacy SDL_OpenAudio() function.

\since This function is available since SDL 2.0.0.

\sa SDL_CloseAudioDevice \sa SDL_GetAudioDeviceName \sa SDL_LockAudioDevice \sa SDL_OpenAudio \sa SDL_PauseAudioDevice \sa SDL_UnlockAudioDevice

This function is a legacy means of pausing the audio device.

New programs might want to use SDL_PauseAudioDevice() instead. This function is equivalent to calling...

```c SDL_PauseAudioDevice(1, pause_on); ```

...and is only useful if you used the legacy SDL_OpenAudio() function.

\param pause_on non-zero to pause, 0 to unpause

\since This function is available since SDL 2.0.0.

\sa SDL_GetAudioStatus \sa SDL_PauseAudioDevice

Checks the event queue for messages and optionally returns them.

If action is SDL_ADDEVENT, up to numevents events will be added to the back of the event queue.

If action is SDL_PEEKEVENT, up to 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 action is SDL_GETEVENT, up to 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.

Result: The number of events actually stored, or -1 if there was an error.

This function is thread-safe.

Convert one of the enumerated pixel formats to a bpp value and RGBA masks.

\param format one of the SDL_PixelFormatEnum values \param bpp a bits per pixel value; usually 15, 16, or 32 \param Rmask a pointer filled in with the red mask for the format \param Gmask a pointer filled in with the green mask for the format \param Bmask a pointer filled in with the blue mask for the format \param Amask a pointer filled in with the alpha mask for the format \returns SDL_TRUE on success or SDL_FALSE if the conversion wasn't possible; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_MasksToPixelFormatEnum

Returns true if point resides inside a rectangle.

Polls for currently pending events.

1 if there are any pending events, or 0 if there are none available.

event - If not nil, the next event is removed from the queue and stored in that area.

Calculate the value of x raised to the power of y.

\since This function is available since SDL 2.0.8.

Add an event to the event queue.

1 on success, 0 if the event was filtered, or -1 if the event queue was full or there was some other error.

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

Note that SDL2 does not support planar audio. You will need to resample from planar audio formats into a non-planar one (see SDL_AudioFormat) before queuing audio.

\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 \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.4.

\sa SDL_ClearQueuedAudio \sa SDL_GetQueuedAudioSize

This function cleans up specific SDL subsystems

Read endian functions

Read an item of the specified endianness and return in native format.

/** Begin recording a gesture on a specified touch device or all touch devices.

If the parameter `touchId` is -1 (i.e., all devices), this function will always return 1, regardless of whether there actually are any devices.

\param touchId the touch device id, or -1 for all touch devices \returns 1 on success or 0 if the specified device could not be found.

\since This function is available since SDL 2.0.0.

\sa SDL_GetTouchDevice

Returns true if the two rectangles are equal.

Remove a timer knowing its ID.

A boolean value indicating success or failure.

It is not safe to remove a timer multiple times.

Copy a portion of the texture to the current rendering target.

renderer The renderer which should copy parts of a texture. texture The source texture. srcrect A pointer to the source rectangle, or NULL for the entire texture. dstrect A pointer to the destination rectangle, or NULL for the entire rendering target.

0 on success, or -1 on error

Copy a portion of the source texture to the current rendering target, rotating it by angle around the given center

renderer The renderer which should copy parts of a texture. texture The source texture. srcrect A pointer to the source rectangle, or NIL for the entire texture. dstrect A pointer to the destination rectangle, or NIL for the entire rendering target. angle An angle in degrees that indicates the rotation that will be applied to dstrect, rotating it in a clockwise direction center A pointer to a point indicating the point around which dstrect will be rotated (if NIL, rotation will be done around dstrect.w/2, dstrect.h/2). flip An SDL_RendererFlip value stating which flipping actions should be performed on the texture

0 on success, or -1 on error

Draw a line on the current rendering target.

renderer The renderer which should draw a line. x1 The x coordinate of the start point. y1 The y coordinate of the start point. x2 The x coordinate of the end point. y2 The y coordinate of the end point.

0 on success, or -1 on error

\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

Draw a point on the current rendering target.

renderer The renderer which should draw a point. x The x coordinate of the point. y The y coordinate of the point.

0 on success, or -1 on error

Draw multiple points on the current rendering target.

renderer The renderer which should draw multiple points. points The points to draw count The number of points to draw

0 on success, or -1 on error

Draw a rectangle on the current rendering target.

renderer The renderer which should draw a rectangle. rect A pointer to the destination rectangle, or NULL to outline the entire rendering target.

0 on success, or -1 on error

Draw some number of rectangles on the current rendering target.

renderer The renderer which should draw multiple rectangles. rects A pointer to an array of destination rectangles. count The number of rectangles.

0 on success, or -1 on error

Fill a rectangle on the current rendering target with the drawing color.

renderer The renderer which should fill a rectangle. rect A pointer to the destination rectangle, or NULL for the entire rendering target.

0 on success, or -1 on error

Fill some number of rectangles on the current rendering target with the drawing color.

renderer The renderer which should fill multiple rectangles. rects A pointer to an array of destination rectangles. count The number of rectangles.

0 on success, or -1 on error

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.

Render a list of triangles, optionally using a texture and indices into the vertex arrays. Color and alpha modulation is done per vertex. SDL_SetTextureColorMod and SDL_SetTextureAlphaMod are ignored.

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

Get the Metal command encoder for the current frame

This function returns a raw Pointer, so SDL doesn't have to include Metal's headers, but it can be safely cast to an `id<MTLRenderCommandEncoder>`.

Note that as of SDL 2.0.18, this will return NULL if Metal refuses to give SDL a drawable to render to, which might happen if the window is hidden/minimized/offscreen. This doesn't apply to command encoders for render targets, just the window's backbacker. Check your return values!

Get the drawing scale for the current target.

renderer The renderer from which drawing scale should be queried. scaleX A pointer filled in with the horizontal scaling factor scaleY A pointer filled in with the vertical scaling factor

SDL_RenderSetScale()

Get the window associated with a renderer.

Get real coordinates of point in window when given logical coordinates of point in renderer. Logical coordinates will differ from real coordinate when render is scaled and logical renderer size set.

Read pixels from the current rendering target.

renderer The renderer from which pixels should be read. rect A pointer to the rectangle to read, or NULL for the entire render target. format The desired format of the pixel data, or 0 to use the format of the rendering target pixels A pointer to be filled in with the pixel data pitch The pitch of the pixels parameter.

0 on success, or -1 if pixel reading is not supported.

This is a very slow operation, and should not be used frequently.

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

Set the drawing scale for rendering on the current target.

renderer The renderer for which the drawing scale should be set. scaleX The horizontal scaling factor 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.

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.

SDL_RenderGetScale() SDL_RenderSetLogicalSize()

Toggle VSync of the given renderer.

Get logical coordinates of point in renderer when given real coordinates of point in window. Logical coordinates will differ from real coordinates when render is scaled and logical renderer size set.

Reset all hints to the default values.

This will reset all hints to the value of the associated environment variable, or NIL if the environment isn't set. Callbacks will be called normally with this change.

\since This function is available since SDL 2.26.0.

\sa SDL_GetHint \sa SDL_SetHint \sa SDL_ResetHint

Restore the size and position of a minimized or maximized window.

SDL_MaximizeWindow() SDL_MinimizeWindow()

Round to nearest integral value, away from zero.

\since This function is available since SDL 2.0.16.

don't know if this works

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.

Return the size of the file in this rwops, or -1 if unknown

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.

TODO : Check: Why AnsiString instead of PAnsiChar used here? Compare SDL_LoadBMP macro.

Save a currently loaded Dollar Gesture template.

\param gestureId a gesture id \param dst a SDL_RWops to save to \returns 1 on success or 0 on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

\sa SDL_LoadDollarTemplates \sa SDL_SaveAllDollarTemplates

Calculate x multiplied by the floating-point radix to the power of n. On most systems, the radix is 2, making this equivalent to x*(2**n).

\since This function is available since SDL 2.0.8.

See if a semaphore has a positive value and decrement it if it does.

This function checks to see if the semaphore pointed to by `sem` has a positive value and atomically decrements the semaphore value if it does. If the semaphore doesn't have a positive value, the function immediately returns SDL_MUTEX_TIMEDOUT.

\param sem the semaphore to wait on \returns 0 if the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait would block, or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

Wait until a semaphore has a positive value and then decrements it.

This function suspends the calling thread until either the semaphore pointed to by `sem` has a positive value or the call is interrupted by a signal or error. If the call is successful it will atomically decrement the semaphore value.

This function is the equivalent of calling SDL_SemWaitTimeout() with a time length of SDL_MUTEX_MAXWAIT.

\param sem the semaphore wait on \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.

\since This function is available since SDL 2.0.0.

Close a sensor previously opened with SDL_SensorOpen().

\param sensor The SDL_Sensor object to close

\since This function is available since SDL 2.0.9.

Get the current state of an opened sensor.

The number of values and interpretation of the data is sensor dependent.

\param sensor The SDL_Sensor object to query \param data A pointer filled with the current sensor state \param num_values The number of values to write to data \returns 0 or -1 if an error occurred.

\since This function is available since SDL 2.0.9.

Get the instance ID of a sensor.

\param device_index The sensor to get instance id from \returns the sensor instance ID, or -1 if `device_index` is out of range.

\since This function is available since SDL 2.0.9.

Get the platform dependent type of a sensor.

\param device_index The sensor to check \returns the sensor platform dependent type, or -1 if `device_index` is out of range.

\since This function is available since SDL 2.0.9.