mirrors/SDL
1
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2026-04-20 22:35:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

wikiheaders: bridge wiki Category docs to the headers!

Browse Source 
Did an initial cleanup on the headers and wrote a few pieces of documentation,
but this needs more work to fill out the documentation.
This commit is contained in:
Ryan C. Gordon
2024-05-16 10:44:37 -04:00
parent 558630d59c
commit 5e6d85b8f0
68 changed files with 617 additions and 388 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
include/SDL3/SDL_assert.h
View File

@@ -20,9 +20,39 @@
*/
/**
* \file SDL_assert.h
* # CategoryAssert
*
* Header file for assertion SDL API functions
* A helpful assertion macro!
*
* SDL assertions operate like your usual `assert` macro, but with some added
* features:
*
* - It uses a trick with the `sizeof` operator, so disabled assertions
* vaporize out of the compiled code, but variables only referenced in the
* assertion won't trigger compiler warnings about being unused.
* - It is safe to use with a dangling-else: `if (x) SDL_assert(y); else
* do_something();`
* - It works the same everywhere, instead of counting on various platforms'
* compiler and C runtime to behave.
* - It provides multiple levels of assertion (SDL_assert, SDL_assert_release,
* SDL_assert_paranoid) instead of a single all-or-nothing option.
* - It offers a variety of responses when an assertion fails (retry, trigger
* the debugger, abort the program, ignore the failure once, ignore it for
* the rest of the program's run).
* - It tries to show the user a dialog by default, if possible, but the app
* can provide a callback to handle assertion failures however they like.
* - It lets failed assertions be retried. Perhaps you had a network failure
* and just want to retry the test after plugging your network cable back
* in? You can.
* - It lets the user ignore an assertion failure, if there's a harmless
* problem that one can continue past.
* - It lets the user mark an assertion as ignored for the rest of the
* program's run; if there's a harmless problem that keeps popping up.
* - It provides statistics and data on all failed assertions to the app.
* - It allows the default assertion handler to be controlled with environment
* variables, in case an automated script needs to control it.
*
* To use it: do a debug build and just sprinkle around tests check your code!
*/
#ifndef SDL_assert_h_

30
include/SDL3/SDL_atomic.h
View File

@@ -20,31 +20,29 @@
*/
/**
* \file SDL_atomic.h
* # CategoryAtomic
*
* Atomic operations.
*
* IMPORTANT:
* If you are not an expert in concurrent lockless programming, you should
* not be using any functions in this file. You should be protecting your
* data structures with full mutexes instead.
* IMPORTANT: If you are not an expert in concurrent lockless programming, you
* should not be using any functions in this file. You should be protecting
* your data structures with full mutexes instead.
*
* Seriously, here be dragons!
* ^^^^^^^^^^^^^^^^^^^^^^^^^^^
* ***Seriously, here be dragons!***
*
* You can find out a little more about lockless programming and the
* subtle issues that can arise here:
* You can find out a little more about lockless programming and the subtle
* issues that can arise here:
* https://learn.microsoft.com/en-us/windows/win32/dxtecharts/lockless-programming
*
* There's also lots of good information here:
* http://www.1024cores.net/home/lock-free-algorithms
* http://preshing.com/
*
* These operations may or may not actually be implemented using
* processor specific atomic operations. When possible they are
* implemented as true processor specific atomic operations. When that
* is not possible the are implemented using locks that *do* use the
* available atomic operations.
* - https://www.1024cores.net/home/lock-free-algorithms
* - https://preshing.com/
*
* These operations may or may not actually be implemented using processor
* specific atomic operations. When possible they are implemented as true
* processor specific atomic operations. When that is not possible the are
* implemented using locks that *do* use the available atomic operations.
*
* All of the atomic operations that modify memory are full memory barriers.
*/

47
include/SDL3/SDL_audio.h
View File

@@ -20,11 +20,43 @@
*/
/**
* \file SDL_audio.h
* # CategoryAudio
*
* Audio functionality for the SDL library.
* Audio functionality for the SDL library.
*
* All audio in SDL3 revolves around SDL_AudioStream. Whether you want to play
* or record audio, convert it, stream it, buffer it, or mix it, you're going
* to be passing it through an audio stream.
*
* Audio streams are quite flexible; they can accept any amount of data at a
* time, in any supported format, and output it as needed in any other format,
* even if the data format changes on either side halfway through.
*
* An app opens an audio device and binds any number of audio streams to it,
* feeding more data to it as available. When the devices needs more data, it
* will pull it from all bound streams and mix them together for playback.
*
* Audio streams can also use an app-provided callback to supply data
* on-demand, which maps pretty closely to the SDL2 audio model.
*
* SDL also provides a simple .WAV loader in SDL_LoadWAV (and SDL_LoadWAV_IO
* if you aren't reading from a file) as a basic means to load sound data into
* your program.
*
* For multi-channel audio, the default SDL channel mapping is:
*
* ```
* 2: FL FR (stereo)
* 3: FL FR LFE (2.1 surround)
* 4: FL FR BL BR (quad)
* 5: FL FR LFE BL BR (4.1 surround)
* 6: FL FR FC LFE SL SR (5.1 surround - last two can also be BL BR)
* 7: FL FR FC LFE BC SL SR (6.1 surround)
* 8: FL FR FC LFE BL BR SL SR (7.1 surround)
* ```
*/
#ifndef SDL_audio_h_
#define SDL_audio_h_
@@ -42,17 +74,6 @@
extern "C" {
#endif
/*
* For multi-channel audio, the default SDL channel mapping is:
* 2: FL FR (stereo)
* 3: FL FR LFE (2.1 surround)
* 4: FL FR BL BR (quad)
* 5: FL FR LFE BL BR (4.1 surround)
* 6: FL FR FC LFE SL SR (5.1 surround - last two can also be BL BR)
* 7: FL FR FC LFE BC SL SR (6.1 surround)
* 8: FL FR FC LFE BL BR SL SR (7.1 surround)
*/
/**
* Audio format flags.
*

8
include/SDL3/SDL_begin_code.h
View File

@@ -22,11 +22,9 @@
/* WIKI CATEGORY: BeginCode */
/**
* \file SDL_begin_code.h
*
* This file sets things up for C dynamic library function definitions,
* static inlined functions, and structures aligned at 4-byte alignment.
* If you don't like ugly C preprocessor code, don't look at this file. :)
* SDL_begin_code.h sets things up for C dynamic library function definitions,
* static inlined functions, and structures aligned at 4-byte alignment.
* If you don't like ugly C preprocessor code, don't look at this file. :)
*/
/* This shouldn't be nested -- included it around code only. */

4
include/SDL3/SDL_bits.h
View File

@@ -20,9 +20,9 @@
*/
/**
* \file SDL_bits.h
* # CategoryBits
*
* Functions for fiddling with bits and bitmasks.
* Functions for fiddling with bits and bitmasks.
*/
#ifndef SDL_bits_h_

6
include/SDL3/SDL_blendmode.h
View File

@@ -20,9 +20,11 @@
*/
/**
* \file SDL_blendmode.h
* # CategoryBlendmode
*
* Header file declaring the SDL_BlendMode enumeration
* Blend modes decide how two colors will mix together. There are both
* standard modes for basic needs and a means to create custom modes,
* dictating what sort of math to do what on what color components.
*/
#ifndef SDL_blendmode_h_

9
include/SDL3/SDL_camera.h
View File

@@ -20,9 +20,14 @@
*/
/**
* \file SDL_camera.h
* # CategoryCamera
*
* Video Capture for the SDL library.
* Video capture for the SDL library.
*
* This API lets apps read input from video sources, like webcams. Camera
* devices can be enumerated, queried, and opened. Once opened, it will
* provide SDL_Surface objects as new frames of video come in. These surfaces
* can be uploaded to an SDL_Texture or processed as pixels in memory.
*/
#ifndef SDL_camera_h_

7
include/SDL3/SDL_clipboard.h
View File

@@ -20,9 +20,12 @@
*/
/**
* \file SDL_clipboard.h
* # CategoryClipboard
*
* Include file for SDL clipboard handling
* SDL provides access to the system clipboard, both for reading information
* from other processes and publishing information of its own.
*
* This is not just text! SDL apps can access and publish data by mimetype.
*/
#ifndef SDL_clipboard_h_

8
include/SDL3/SDL_close_code.h
View File

@@ -19,11 +19,9 @@
3. This notice may not be removed or altered from any source distribution.
*/
/**
* \file SDL_close_code.h
*
* This file reverses the effects of SDL_begin_code.h and should be included
* after you finish any function and structure declarations in your headers
/*
* This file reverses the effects of SDL_begin_code.h and should be included
* after you finish any function and structure declarations in your headers
*/
#ifndef SDL_begin_code_h

6
include/SDL3/SDL_copying.h
View File

@@ -19,8 +19,4 @@
3. This notice may not be removed or altered from any source distribution.
*/
/**
* \file SDL_copying.h
*
* Header file containing SDL's license.
*/
/* Header file containing SDL's license. */

8
include/SDL3/SDL_cpuinfo.h
View File

@@ -22,9 +22,13 @@
/* WIKI CATEGORY: CPUInfo */
/**
* \file SDL_cpuinfo.h
* # CategoryCPUInfo
*
* CPU feature detection for SDL.
* CPU feature detection for SDL.
*
* These functions are largely concerned with reporting if the system has
* access to various SIMD instruction sets, but also has other important info
* to share, such as system RAM size and number of logical CPU cores.
*/
#ifndef SDL_cpuinfo_h_

6
include/SDL3/SDL_dialog.h
View File

@@ -19,6 +19,12 @@
3. This notice may not be removed or altered from any source distribution.
*/
/**
* # CategoryDialog
*
* File dialog support.
*/
#ifndef SDL_dialog_h_
#define SDL_dialog_h_

6
include/SDL3/SDL_egl.h
View File

@@ -19,10 +19,8 @@
3. This notice may not be removed or altered from any source distribution.
*/
/**
* \file SDL_egl.h
*
* This is a simple file to encapsulate the EGL API headers.
/*
* This is a simple file to encapsulate the EGL API headers.
*/
#include <SDL3/SDL_platform_defines.h>

4
include/SDL3/SDL_endian.h
View File

@@ -20,9 +20,9 @@
*/
/**
* \file SDL_endian.h
* # CategoryEndian
*
* Functions for reading and writing endian-specific values
* Functions for reading and writing endian-specific values.
*/
#ifndef SDL_endian_h_

4
include/SDL3/SDL_error.h
View File

@@ -20,9 +20,9 @@
*/
/**
* \file SDL_error.h
* # CategoryError
*
* Simple error message routines for SDL.
* Simple error message routines for SDL.
*/
#ifndef SDL_error_h_

4
include/SDL3/SDL_events.h
View File

@@ -20,9 +20,9 @@
*/
/**
* \file SDL_events.h
* # CategoryEvents
*
* Include file for SDL event handling.
* Event queue management.
*/
#ifndef SDL_events_h_

4
include/SDL3/SDL_filesystem.h
View File

@@ -20,9 +20,9 @@
*/
/**
* \file SDL_filesystem.h
* # CategoryFilesystem
*
* Include file for filesystem SDL API functions
* SDL Filesystem API.
*/
#ifndef SDL_filesystem_h_

44
include/SDL3/SDL_gamepad.h
View File

@@ -20,9 +20,37 @@
*/
/**
* \file SDL_gamepad.h
* # CategoryGamepad
*
* Include file for SDL gamepad event handling
* SDL provides a low-level joystick API, which just treats joysticks as an
* arbitrary pile of buttons, axes, and hat switches. If you're planning to
* write your own control configuration screen, this can give you a lot of
* flexibility, but that's a lot of work, and most things that we consider
* "joysticks" now are actually console-style gamepads. So SDL provides the
* gamepad API on top of the lower-level joystick functionality.
*
* The difference betweena joystick and a gamepad is that a gamepad tells you
* _where_ a button or axis is on the device. You don't speak to gamepads in
* terms of arbitrary numbers like "button 3" or "axis 2" but in standard
* locations: the d-pad, the shoulder buttons, triggers, A/B/X/Y (or
* X/O/Square/Triangle, if you will).
*
* One turns a joystick into a gamepad by providing a magic configuration
* string, which tells SDL the details of a specific device: when you see this
* specific hardware, if button 2 gets pressed, this is actually D-Pad Up,
* etc.
*
* SDL has many popular controllers configured out of the box, and users can
* add their own controller details through an environment variable if it's
* otherwise unknown to SDL.
*
* In order to use these functions, SDL_Init() must have been called with the
* SDL_INIT_GAMEPAD flag. This causes SDL to scan the system for gamepads, and
* load appropriate drivers.
*
* If you would like to receive gamepad updates while the application is in
* the background, you should set the following hint before calling
* SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS
*/
#ifndef SDL_gamepad_h_
@@ -41,18 +69,6 @@
extern "C" {
#endif
/**
* \file SDL_gamepad.h
*
* In order to use these functions, SDL_Init() must have been called
* with the ::SDL_INIT_GAMEPAD flag. This causes SDL to scan the system
* for gamepads, and load appropriate drivers.
*
* If you would like to receive gamepad updates while the application
* is in the background, you should set the following hint before calling
* SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS
*/
/**
* The structure used to identify an SDL gamepad
*

5
include/SDL3/SDL_guid.h
View File

@@ -22,9 +22,10 @@
/* WIKI CATEGORY: GUID */
/**
* \file SDL_guid.h
* # CategoryGUID
*
* Include file for handling ::SDL_GUID values.
* A GUID is a 128-bit value that represents something that is uniquely
* identifiable by this value: "globally unique."
*/
#ifndef SDL_guid_h_

25
include/SDL3/SDL_haptic.h
View File

@@ -20,21 +20,21 @@
*/
/**
* \file SDL_haptic.h
* # CategoryHaptic
*
* The SDL haptic subsystem manages haptic (force feedback) devices.
* The SDL haptic subsystem manages haptic (force feedback) devices.
*
* The basic usage is as follows:
* The basic usage is as follows:
*
* - Initialize the subsystem (SDL_INIT_HAPTIC).
* - Open a haptic device.
* - SDL_OpenHaptic() to open from index.
* - SDL_OpenHapticFromJoystick() to open from an existing joystick.
* - Create an effect (SDL_HapticEffect).
* - Upload the effect with SDL_CreateHapticEffect().
* - Run the effect with SDL_RunHapticEffect().
* - (optional) Free the effect with SDL_DestroyHapticEffect().
* - Close the haptic device with SDL_CloseHaptic().
* - Initialize the subsystem (SDL_INIT_HAPTIC).
* - Open a haptic device.
* - SDL_OpenHaptic() to open from index.
* - SDL_OpenHapticFromJoystick() to open from an existing joystick.
* - Create an effect (SDL_HapticEffect).
* - Upload the effect with SDL_CreateHapticEffect().
* - Run the effect with SDL_RunHapticEffect().
* - (optional) Free the effect with SDL_DestroyHapticEffect().
* - Close the haptic device with SDL_CloseHaptic().
*
* Simple rumble example:
*
@@ -113,6 +113,7 @@
* Note that the SDL haptic subsystem is not thread-safe.
*/
#ifndef SDL_haptic_h_
#define SDL_haptic_h_

67
include/SDL3/SDL_hidapi.h
View File

@@ -22,43 +22,46 @@
/* WIKI CATEGORY: HIDAPI */
/**
* \file SDL_hidapi.h
* # CategoryHIDAPI
*
* Header file for SDL HIDAPI functions.
* Header file for SDL HIDAPI functions.
*
* This is an adaptation of the original HIDAPI interface by Alan Ott,
* and includes source code licensed under the following BSD license:
* This is an adaptation of the original HIDAPI interface by Alan Ott, and
* includes source code licensed under the following BSD license:
*
Copyright (c) 2010, Alan Ott, Signal 11 Software
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of Signal 11 Software nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
* ```
* Copyright (c) 2010, Alan Ott, Signal 11 Software
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* * Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
* * Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* * Neither the name of Signal 11 Software nor the names of its
* contributors may be used to endorse or promote products derived from
* this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
* ```
*
* If you would like a version of SDL without this code, you can build SDL
* with SDL_HIDAPI_DISABLED defined to 1. You might want to do this for example
* on iOS or tvOS to avoid a dependency on the CoreBluetooth framework.
* with SDL_HIDAPI_DISABLED defined to 1. You might want to do this for
* example on iOS or tvOS to avoid a dependency on the CoreBluetooth
* framework.
*/
#ifndef SDL_hidapi_h_

20
include/SDL3/SDL_hints.h
View File

@@ -20,20 +20,20 @@
*/
/**
* \file SDL_hints.h
* # CategoryHints
*
* Official documentation for SDL configuration variables
* Official documentation for SDL configuration variables
*
* This file contains functions to set and get configuration hints,
* as well as listing each of them alphabetically.
* This file contains functions to set and get configuration hints, as well as
* listing each of them alphabetically.
*
* The convention for naming hints is SDL_HINT_X, where "SDL_X" is
* the environment variable that can be used to override the default.
* The convention for naming hints is SDL_HINT_X, where "SDL_X" is the
* environment variable that can be used to override the default.
*
* In general these hints are just that - they may or may not be
* supported or applicable on any given platform, but they provide
* a way for an application or user to give the library a hint as
* to how they would like the library to work.
* In general these hints are just that - they may or may not be supported or
* applicable on any given platform, but they provide a way for an application
* or user to give the library a hint as to how they would like the library to
* work.
*/
#ifndef SDL_hints_h_

5
include/SDL3/SDL_init.h
View File

@@ -20,11 +20,12 @@
*/
/**
* \file SDL_init.h
* # CategoryInit
*
* Init and quit header for the SDL library
* SDL subsystem init and quit functions.
*/
#ifndef SDL_init_h_
#define SDL_init_h_

4
include/SDL3/SDL_intrin.h
View File

@@ -19,9 +19,7 @@
3. This notice may not be removed or altered from any source distribution.
*/
/**
* \file SDL_intrin.h
*
/*
* Header file for CPU intrinsics for SDL
*/

11
include/SDL3/SDL_iostream.h
View File

@@ -22,13 +22,14 @@
/* WIKI CATEGORY: IOStream */
/**
* \file SDL_iostream.h
* # CategoryIOStream
*
* This file provides a general interface for SDL to read and write
* data streams. It can easily be extended to files, memory, etc.
* SDL provides an abstract interface for reading and writing data streams. It
* offers implementations for files, memory, etc, and the app can provideo
* their own implementations, too.
*
* SDL_IOStream is not related to the standard C++ iostream class, other
* than both are abstract interfaces to read/write data.
* SDL_IOStream is not related to the standard C++ iostream class, other than
* both are abstract interfaces to read/write data.
*/
#ifndef SDL_iostream_h_

25
include/SDL3/SDL_joystick.h
View File

@@ -20,19 +20,26 @@
*/
/**
* \file SDL_joystick.h
* # CategoryJoystick
*
* Include file for SDL joystick event handling
* SDL joystick support.
*
* The term "instance_id" is the current instantiation of a joystick device in the system, if the joystick is removed and then re-inserted
* then it will get a new instance_id, instance_id's are monotonically increasing identifiers of a joystick plugged in.
* This is the lower-level joystick handling. If you want the simpler option,
* where what buttons does what is well-defined, you should use the gamepad
* API instead.
*
* The term "player_index" is the number assigned to a player on a specific
* controller. For XInput controllers this returns the XInput user index.
* Many joysticks will not be able to supply this information.
* The term "instance_id" is the current instantiation of a joystick device in
* the system, if the joystick is removed and then re-inserted then it will
* get a new instance_id, instance_id's are monotonically increasing
* identifiers of a joystick plugged in.
*
* The term JoystickGUID is a stable 128-bit identifier for a joystick device that does not change over time, it identifies class of
* the device (a X360 wired controller for example). This identifier is platform dependent.
* The term "player_index" is the number assigned to a player on a specific
* controller. For XInput controllers this returns the XInput user index. Many
* joysticks will not be able to supply this information.
*
* The term SDL_JoystickGUID is a stable 128-bit identifier for a joystick
* device that does not change over time, it identifies class of the device (a
* X360 wired controller for example). This identifier is platform dependent.
*/
#ifndef SDL_joystick_h_

4
include/SDL3/SDL_keyboard.h
View File

@@ -20,9 +20,9 @@
*/
/**
* \file SDL_keyboard.h
* # CategoryKeyboard
*
* Include file for SDL keyboard event handling
* SDL keyboard management.
*/
#ifndef SDL_keyboard_h_

4
include/SDL3/SDL_keycode.h
View File

@@ -20,9 +20,9 @@
*/
/**
* \file SDL_keycode.h
* # CategoryKeycode
*
* Defines constants which identify keyboard keys and modifiers.
* Defines constants which identify keyboard keys and modifiers.
*/
#ifndef SDL_keycode_h_

28
include/SDL3/SDL_loadso.h
View File

@@ -22,22 +22,22 @@
/* WIKI CATEGORY: SharedObject */
/**
* \file SDL_loadso.h
* # CategorySharedObject
*
* System dependent library loading routines
* System-dependent library loading routines.
*
* Some things to keep in mind:
* \li These functions only work on C function names. Other languages may
* have name mangling and intrinsic language support that varies from
* compiler to compiler.
* \li 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.
* \li Avoid namespace collisions. If you load a symbol from the library,
* it is not defined whether or not it goes into the global symbol
* namespace for the application. If it does and it conflicts with
* symbols in your code or other shared libraries, you will not get
* the results you expect. :)
* Some things to keep in mind:
*
* - These functions only work on 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.
* - Avoid namespace collisions. If you load a symbol from the library, it is
* not defined whether or not it goes into the global symbol namespace for
* the application. If it does and it conflicts with symbols in your code or
* other shared libraries, you will not get the results you expect. :)
*/
#ifndef SDL_loadso_h_

4
include/SDL3/SDL_locale.h
View File

@@ -20,9 +20,9 @@
*/
/**
* \file SDL_locale.h
* # CategoryLocale
*
* Include file for SDL locale services
* SDL locale services.
*/
#ifndef SDL_locale_h

17
include/SDL3/SDL_log.h
View File

@@ -20,18 +20,19 @@
*/
/**
* \file SDL_log.h
* # CategoryLog
*
* Simple log messages with categories and priorities.
* Simple log messages with categories and priorities.
*
* By default logs are quiet, but if you're debugging SDL you might want:
* By default logs are quiet, but if you're debugging SDL you might want:
*
* SDL_LogSetAllPriority(SDL_LOG_PRIORITY_WARN);
* SDL_LogSetAllPriority(SDL_LOG_PRIORITY_WARN);
*
* Here's where the messages go on different platforms:
* Windows: debug output stream
* Android: log output
* Others: standard error output (stderr)
* Here's where the messages go on different platforms:
*
* - Windows: debug output stream
* - Android: log output
* - Others: standard error output (stderr)
*/
#ifndef SDL_log_h_

26
include/SDL3/SDL_main.h
View File

@@ -19,15 +19,11 @@
3. This notice may not be removed or altered from any source distribution.
*/
#ifndef SDL_main_h_
#define SDL_main_h_
#include <SDL3/SDL_platform_defines.h>
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_error.h>
#include <SDL3/SDL_events.h>
/*
/**
* # CategoryMain
*
* Redefine main() on some platforms so that it is called by SDL.
*
* For details on how SDL_main works, and how to use it, please refer to:
*
* https://wiki.libsdl.org/SDL3/README/main-functions
@@ -35,11 +31,13 @@
* (or docs/README-main-functions.md in the SDL source tree)
*/
/**
* \file SDL_main.h
*
* Redefine main() on some platforms so that it is called by SDL.
*/
#ifndef SDL_main_h_
#define SDL_main_h_
#include <SDL3/SDL_platform_defines.h>
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_error.h>
#include <SDL3/SDL_events.h>
#ifndef SDL_MAIN_HANDLED
#ifdef SDL_PLATFORM_WIN32

6
include/SDL3/SDL_messagebox.h
View File

@@ -19,6 +19,12 @@
3. This notice may not be removed or altered from any source distribution.
*/
/**
* # CategoryMessagebox
*
* Message box support routines.
*/
#ifndef SDL_messagebox_h_
#define SDL_messagebox_h_

4
include/SDL3/SDL_metal.h
View File

@@ -20,9 +20,9 @@
*/
/**
* \file SDL_metal.h
* # CategoryMetal
*
* Header file for functions to creating Metal layers and views on SDL windows.
* Functions to creating Metal layers and views on SDL windows.
*/
#ifndef SDL_metal_h_

4
include/SDL3/SDL_misc.h
View File

@@ -20,9 +20,9 @@
*/
/**
* \file SDL_misc.h
* # CategoryMisc
*
* Include file for SDL API functions that don't fit elsewhere.
* SDL API functions that don't fit elsewhere.
*/
#ifndef SDL_misc_h_

4
include/SDL3/SDL_mouse.h
View File

@@ -20,9 +20,9 @@
*/
/**
* \file SDL_mouse.h
* # CategoryMouse
*
* Include file for SDL mouse event handling.
* SDL mouse handling.
*/
#ifndef SDL_mouse_h_

4
include/SDL3/SDL_mutex.h
View File

@@ -23,9 +23,9 @@
#define SDL_mutex_h_
/**
* \file SDL_mutex.h
* # CategoryMutex
*
* Functions to provide thread synchronization primitives.
* Functions to provide thread synchronization primitives.
*/
#include <SDL3/SDL_stdinc.h>

6
include/SDL3/SDL_oldnames.h
View File

@@ -19,10 +19,8 @@
3. This notice may not be removed or altered from any source distribution.
*/
/**
* \file SDL_oldnames.h
*
* Definitions to ease transition from SDL2 code
/*
* Definitions to ease transition from SDL2 code
*/
#ifndef SDL_oldnames_h_

14
include/SDL3/SDL_opengl.h
View File

@@ -19,17 +19,11 @@
3. This notice may not be removed or altered from any source distribution.
*/
/**
* \file SDL_opengl.h
/*
* This is a simple file to encapsulate the OpenGL API headers.
*
* This is a simple file to encapsulate the OpenGL API headers.
*/
/**
* \def NO_SDL_GLEXT
*
* Define this if you have your own version of glext.h and want to disable the
* version included in SDL_opengl.h.
* Define NO_SDL_GLEXT if you have your own version of glext.h and want
* to disable the version included in SDL_opengl.h.
*/
#ifndef SDL_opengl_h_

7
include/SDL3/SDL_opengles.h
View File

@@ -19,11 +19,10 @@
3. This notice may not be removed or altered from any source distribution.
*/
/**
* \file SDL_opengles.h
*
* This is a simple file to encapsulate the OpenGL ES 1.X API headers.
/*
* This is a simple file to encapsulate the OpenGL ES 1.X API headers.
*/
#include <SDL3/SDL_platform_defines.h>
#ifdef SDL_PLATFORM_IOS

7
include/SDL3/SDL_opengles2.h
View File

@@ -19,11 +19,10 @@
3. This notice may not be removed or altered from any source distribution.
*/
/**
* \file SDL_opengles2.h
*
* This is a simple file to encapsulate the OpenGL ES 2.0 API headers.
/*
* This is a simple file to encapsulate the OpenGL ES 2.0 API headers.
*/
#include <SDL3/SDL_platform_defines.h>
#if !defined(_MSC_VER) && !defined(SDL_USE_BUILTIN_OPENGL_DEFINITIONS)

28
include/SDL3/SDL_pen.h
View File

@@ -20,26 +20,26 @@
*/
/**
* \file SDL_pen.h
* # CategoryPen
*
* Include file for SDL pen event handling.
* Include file for SDL pen event handling.
*
* This file describes operations for pressure-sensitive pen (stylus and/or eraser) handling, e.g., for input
* and drawing tablets or suitably equipped mobile / tablet devices.
* This file describes operations for pressure-sensitive pen (stylus and/or
* eraser) handling, e.g., for input and drawing tablets or suitably equipped
* mobile / tablet devices.
*
* To get started with pens:
* - Listen to SDL_PenMotionEvent and SDL_PenButtonEvent
* - To avoid treating pen events as mouse events, ignore SDL_MouseMotionEvent and SDL_MouseButtonEvent
* whenever "which" == SDL_PEN_MOUSEID.
* To get started with pens:
*
* This header file describes advanced functionality that can be useful for managing user configuration
* and understanding the capabilities of the attached pens.
* - Listen to SDL_PenMotionEvent and SDL_PenButtonEvent
* - To avoid treating pen events as mouse events, ignore SDL_MouseMotionEvent
* and SDL_MouseButtonEvent whenever `which` == SDL_PEN_MOUSEID.
*
* We primarily identify pens by SDL_PenID. The implementation makes a best effort to relate each :SDL_PenID
* to the same physical device during a session. Formerly valid SDL_PenID values remain valid
* even if a device disappears.
* We primarily identify pens by SDL_PenID. The implementation makes a best
* effort to relate each SDL_PenID to the same physical device during a
* session. Formerly valid SDL_PenID values remain valid even if a device
* disappears.
*
* For identifying pens across sessions, the API provides the type SDL_GUID .
* For identifying pens across sessions, the API provides the type SDL_GUID .
*/
#ifndef SDL_pen_h_

6
include/SDL3/SDL_pixels.h
View File

@@ -19,6 +19,12 @@
3. This notice may not be removed or altered from any source distribution.
*/
/**
* # CategoryPixels
*
* Pixel management.
*/
#ifndef SDL_pixels_h_
#define SDL_pixels_h_

5
include/SDL3/SDL_platform.h
View File

@@ -20,9 +20,10 @@
*/
/**
* \file SDL_platform.h
* # CategoryPlatform
*
* Header file for platform functions.
* SDL provides a means to identify the app's platform, both at compile time
* and runtime.
*/
#ifndef SDL_platform_h_

8
include/SDL3/SDL_platform_defines.h
View File

@@ -19,12 +19,10 @@
3. This notice may not be removed or altered from any source distribution.
*/
/* WIKI CATEGORY: PlatformDefines */
/* WIKI CATEGORY: Platform */
/**
* \file SDL_platform_defines.h
*
* Try to get a standard set of platform defines.
/*
* SDL_platform_defines.h tries to get a standard set of platform defines.
*/
#ifndef SDL_platform_defines_h_

4
include/SDL3/SDL_power.h
View File

@@ -23,9 +23,9 @@
#define SDL_power_h_
/**
* \file SDL_power.h
* # CategoryPower
*
* Header for the SDL power management routines.
* SDL power management routines.
*/
#include <SDL3/SDL_stdinc.h>

5
include/SDL3/SDL_properties.h
View File

@@ -20,11 +20,12 @@
*/
/**
* \file SDL_properties.h
* # CategoryProperties
*
* Header file for SDL properties.
* SDL properties.
*/
#ifndef SDL_properties_h_
#define SDL_properties_h_

5
include/SDL3/SDL_rect.h
View File

@@ -20,9 +20,10 @@
*/
/**
* \file SDL_rect.h
* # CategoryRect
*
* Header file for SDL_rect definition and management functions.
* Some helper functions for managing rectangles and 2D points, in both
* interger and floating point versions.
*/
#ifndef SDL_rect_h_

36
include/SDL3/SDL_render.h
View File

@@ -20,29 +20,31 @@
*/
/**
* \file SDL_render.h
* # CategoryRender
*
* Header file for SDL 2D rendering functions.
* Header file for SDL 2D rendering functions.
*
* This API supports the following features:
* * single pixel points
* * single pixel lines
* * filled rectangles
* * texture images
* This API supports the following features:
*
* The primitives may be drawn in opaque, blended, or additive modes.
* - single pixel points
* - single pixel lines
* - filled rectangles
* - texture images
* - 2D polygons
*
* The texture images may be drawn in opaque, blended, or additive modes.
* They can have an additional color tint or alpha modulation applied to
* them, and may also be stretched with linear interpolation.
* The primitives may be drawn in opaque, blended, or additive modes.
*
* This API is designed to accelerate simple 2D operations. You may
* want more functionality such as polygons and particle effects and
* in that case you should use SDL's OpenGL/Direct3D support or one
* of the many good 3D engines.
* The texture images may be drawn in opaque, blended, or additive modes. They
* can have an additional color tint or alpha modulation applied to them, and
* may also be stretched with linear interpolation.
*
* These functions must be called from the main thread.
* See this bug for details: https://github.com/libsdl-org/SDL/issues/986
* This API is designed to accelerate simple 2D operations. You may want more
* functionality such as polygons and particle effects and in that case you
* should use SDL's OpenGL/Direct3D support or one of the many good 3D
* engines.
*
* These functions must be called from the main thread. See this bug for
* details: https://github.com/libsdl-org/SDL/issues/986
*/
#ifndef SDL_render_h_

12
include/SDL3/SDL_revision.h
View File

@@ -19,14 +19,14 @@
3. This notice may not be removed or altered from any source distribution.
*/
/**
* \file SDL_revision.h
*
* Header file containing the SDL revision
*/
/* WIKI CATEGORY: Version */
/*
* SDL_revision.h contains the SDL revision, which might be defined on the
* compiler command line, or generated right into the header itself by the
* build system.
*/
#ifndef SDL_revision_h_
#define SDL_revision_h_

4
include/SDL3/SDL_scancode.h
View File

@@ -20,9 +20,9 @@
*/
/**
* \file SDL_scancode.h
* # CategoryScancode
*
* Defines keyboard scancodes.
* Defines keyboard scancodes.
*/
#ifndef SDL_scancode_h_

4
include/SDL3/SDL_sensor.h
View File

@@ -20,9 +20,9 @@
*/
/**
* \file SDL_sensor.h
* # CategorySensor
*
* Include file for SDL sensor event handling
* SDL sensor management.
*/
#ifndef SDL_sensor_h_

8
include/SDL3/SDL_stdinc.h
View File

@@ -20,11 +20,11 @@
*/
/**
* \file SDL_stdinc.h
* # CategoryStdinc
*
* This is a general header that includes C language support. It implements
* a subset of the C runtime: these should all behave the same way as their
* C runtime equivalents, but with an SDL_ prefix.
* This is a general header that includes C language support. It implements a
* subset of the C runtime: these should all behave the same way as their C
* runtime equivalents, but with an SDL_ prefix.
*/
#ifndef SDL_stdinc_h_

4
include/SDL3/SDL_storage.h
View File

@@ -20,9 +20,9 @@
*/
/**
* \file SDL_storage.h
* # CategoryStorage
*
* Include file for storage container SDL API functions
* SDL storage container management.
*/
#ifndef SDL_storage_h_

4
include/SDL3/SDL_surface.h
View File

@@ -20,9 +20,9 @@
*/
/**
* \file SDL_surface.h
* # CategorySurface
*
* Header file for ::SDL_Surface definition and management functions.
* SDL_Surface definition and management functions.
*/
#ifndef SDL_surface_h_

4
include/SDL3/SDL_system.h
View File

@@ -20,9 +20,9 @@
*/
/**
* \file SDL_system.h
* # CategorySystem
*
* Include file for platform specific SDL API functions
* Platform-specific SDL API functions.
*/
#ifndef SDL_system_h_

2
include/SDL3/SDL_test_assert.h
View File

@@ -20,8 +20,6 @@
*/
/**
* \file SDL_test_assert.h
*
* Assertion functions of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.

2
include/SDL3/SDL_test_crc32.h
View File

@@ -20,8 +20,6 @@
*/
/**
* \file SDL_test_crc32.h
*
* CRC32 functions of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.

3
include/SDL3/SDL_test_fuzzer.h
View File

@@ -20,8 +20,6 @@
*/
/**
* \file SDL_test_fuzzer.h
*
* Fuzzer functions of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
@@ -49,7 +47,6 @@ extern "C" {
/**
* \file
* Note: The fuzzer implementation uses a static instance of random context
* internally which makes it thread-UNsafe.
*/

4
include/SDL3/SDL_thread.h
View File

@@ -23,9 +23,9 @@
#define SDL_thread_h_
/**
* \file SDL_thread.h
* # CategoryThread
*
* Header for the SDL thread management routines.
* SDL thread management routines.
*/
#include <SDL3/SDL_stdinc.h>

4
include/SDL3/SDL_time.h
View File

@@ -23,9 +23,9 @@ freely, subject to the following restrictions:
#define SDL_time_h_
/**
* \file SDL_time.h
* # CategoryTime
*
* Header for the SDL realtime clock and date/time routines.
* SDL realtime clock and date/time routines.
*/
#include <SDL3/SDL_error.h>

4
include/SDL3/SDL_timer.h
View File

@@ -23,9 +23,9 @@
#define SDL_timer_h_
/**
* \file SDL_timer.h
* # CategoryTimer
*
* Header for the SDL time management routines.
* SDL time management routines.
*/
#include <SDL3/SDL_stdinc.h>

4
include/SDL3/SDL_touch.h
View File

@@ -20,9 +20,9 @@
*/
/**
* \file SDL_touch.h
* # CategoryTouch
*
* Include file for SDL touch event handling.
* SDL touch management.
*/
#ifndef SDL_touch_h_

5
include/SDL3/SDL_version.h
View File

@@ -20,9 +20,10 @@
*/
/**
* \file SDL_version.h
* # CategoryVersion
*
* This header defines the current SDL version.
* Functionality to query the current SDL version, both as headers the app was
* compiled against, and a library the app is linked to.
*/
#ifndef SDL_version_h_

4
include/SDL3/SDL_video.h
View File

@@ -20,9 +20,9 @@
*/
/**
* \file SDL_video.h
* # CategoryVideo
*
* Header file for SDL video functions.
* SDL video functions.
*/
#ifndef SDL_video_h_

4
include/SDL3/SDL_vulkan.h
View File

@@ -20,9 +20,9 @@
*/
/**
* \file SDL_vulkan.h
* # CategoryVulkan
*
* Header file for functions to creating Vulkan surfaces on SDL windows.
* Functions for creating Vulkan surfaces on SDL windows.
*/
#ifndef SDL_vulkan_h_