From c486959e713d0ae45c648ac24dae8cde72e834c6 Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" Date: Wed, 24 Mar 2021 10:47:03 -0400 Subject: [PATCH] headers: Fix up bullet lists, now that wikiheaders.pl can handle them. --- include/SDL.h | 2 +- include/SDL_audio.h | 15 ++++----------- include/SDL_blendmode.h | 32 +++++++++++--------------------- include/SDL_events.h | 16 ++++++---------- include/SDL_filesystem.h | 17 ++++++----------- include/SDL_hints.h | 1 + include/SDL_joystick.h | 11 +---------- include/SDL_messagebox.h | 2 -- include/SDL_mouse.h | 3 --- include/SDL_platform.h | 4 ---- include/SDL_rwops.h | 2 -- include/SDL_system.h | 20 -------------------- include/SDL_video.h | 25 +++---------------------- 13 files changed, 33 insertions(+), 117 deletions(-) diff --git a/include/SDL.h b/include/SDL.h index a69541679..f4576d619 100644 --- a/include/SDL.h +++ b/include/SDL.h @@ -118,7 +118,7 @@ extern "C" { * events subsystem * - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem * - `SDL_INIT_GAMECONTROLLER`: controller subsystem; automatically - * initializes the joystick subsystem + * initializes the joystick subsystem * - `SDL_INIT_EVENTS`: events subsystem * - `SDL_INIT_EVERYTHING`: all of the above subsystems * - `SDL_INIT_NOPARACHUTE`: compatibility; this flag is ignored diff --git a/include/SDL_audio.h b/include/SDL_audio.h index 99d8a2b8b..2c05d1755 100644 --- a/include/SDL_audio.h +++ b/include/SDL_audio.h @@ -300,12 +300,11 @@ extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void); * With two notable exceptions: * * - If `obtained` is NULL, we use `desired` (and allow no changes), which - * means desired will be modified to have the correct values for silence, etc, - * and SDL will convert any differences between your app's specific request - * and the hardware behind the scenes. - * + * means desired will be modified to have the correct values for silence, + * etc, and SDL will convert any differences between your app's specific + * request and the hardware behind the scenes. * - The return value is always success or failure, and not a device ID, which - * means you can only have one device open at a time with this function. + * means you can only have one device open at a time with this function. * * \param desired an SDL_AudioSpec structure representing the desired output * format. Please refer to the SDL_OpenAudioDevice documentation @@ -464,9 +463,7 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index, * 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 @@ -477,13 +474,10 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index, * 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. @@ -493,7 +487,6 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index, * 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. * diff --git a/include/SDL_blendmode.h b/include/SDL_blendmode.h index 919588a70..7627e324c 100644 --- a/include/SDL_blendmode.h +++ b/include/SDL_blendmode.h @@ -113,13 +113,9 @@ typedef enum * `alphaOperation(src, dst)` can return one of the following: * * - `src + dst` - * * - `src - dst` - * * - `dst - src` - * * - `min(src, dst)` - * * - `max(src, dst)` * * The red, green, and blue components are always multiplied with the first, @@ -140,28 +136,22 @@ typedef enum * SDL_BlendMode enumeration. * * - **direct3d**: Supports `SDL_BLENDOPERATION_ADD` with all factors. - * * - **direct3d11**: Supports all operations with all factors. However, some - * factors produce unexpected results with `SDL_BLENDOPERATION_MINIMUM` and - * `SDL_BLENDOPERATION_MAXIMUM`. - * + * factors produce unexpected results with `SDL_BLENDOPERATION_MINIMUM` and + * `SDL_BLENDOPERATION_MAXIMUM`. * - **opengl**: Supports the `SDL_BLENDOPERATION_ADD` operation with all - * factors. OpenGL versions 1.1, 1.2, and 1.3 do not work correctly with - * SDL 2.0.6. - * + * factors. OpenGL versions 1.1, 1.2, and 1.3 do not work correctly with + * SDL 2.0.6. * - **opengles**: Supports the `SDL_BLENDOPERATION_ADD` operation with all - * factors. Color and alpha factors need to be the same. OpenGL ES 1 - * implementation specific: May also support `SDL_BLENDOPERATION_SUBTRACT` - * and `SDL_BLENDOPERATION_REV_SUBTRACT`. May support color and alpha - * operations being different from each other. May support color and alpha - * factors being different from each other. - * + * factors. Color and alpha factors need to be the same. OpenGL ES 1 + * implementation specific: May also support `SDL_BLENDOPERATION_SUBTRACT` + * and `SDL_BLENDOPERATION_REV_SUBTRACT`. May support color and alpha + * operations being different from each other. May support color and alpha + * factors being different from each other. * - **opengles2**: Supports the `SDL_BLENDOPERATION_ADD`, - * `SDL_BLENDOPERATION_SUBTRACT`, `SDL_BLENDOPERATION_REV_SUBTRACT` operations - * with all factors. - * + * `SDL_BLENDOPERATION_SUBTRACT`, `SDL_BLENDOPERATION_REV_SUBTRACT` operations + * with all factors. * - **psp**: No custom blend mode support. - * * - **software**: No custom blend mode support. * * Some renderers do not provide an alpha component for the default render diff --git a/include/SDL_events.h b/include/SDL_events.h index a2f3e3c8e..6a04391fe 100644 --- a/include/SDL_events.h +++ b/include/SDL_events.h @@ -672,15 +672,13 @@ typedef enum * `action` may be any of the following: * * - `SDL_ADDEVENT`: up to `numevents` events will be added to the back of - * the event queue. - * + * the event queue. * - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue, - * within the specified minimum and maximum type, will be returned to the - * caller and will _not_ be removed from the queue. - * + * within the specified minimum and maximum type, will be returned to the + * caller and will _not_ be removed from the queue. * - `SDL_GETEVENT`: up to `numevents` events at the front of the event queue, - * within the specified minimum and maximum type, will be returned to the - * caller and will be removed from the queue. + * within the specified minimum and maximum type, will be returned to the + * caller and will be removed from the queue. * * You may have to call SDL_PumpEvents() before calling this function. * Otherwise, the events may not be ready to be filtered when you call @@ -1050,10 +1048,8 @@ extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, * `state` may be any of the following: * * - `SDL_QUERY`: returns the current processing state of the specified event - * * - `SDL_IGNORE` (aka `SDL_DISABLE`): the event will automatically be dropped - * from the event queue and will not be filtered - * + * from the event queue and will not be filtered * - `SDL_ENABLE`: the event will be processed normally * * \param type the type of event; see SDL_EventType for details diff --git a/include/SDL_filesystem.h b/include/SDL_filesystem.h index 55c93eee9..d06dbe9ed 100644 --- a/include/SDL_filesystem.h +++ b/include/SDL_filesystem.h @@ -54,13 +54,11 @@ extern "C" { * application in /Applications/SDLApp/MyApp.app): * * - `resource`: bundle resource directory (the default). For example: - * `/Applications/SDLApp/MyApp.app/Contents/Resources` - * + * `/Applications/SDLApp/MyApp.app/Contents/Resources` * - `bundle`: the Bundle directory. Fpr example: - * `/Applications/SDLApp/MyApp.app/` - * + * `/Applications/SDLApp/MyApp.app/` * - `parent`: the containing directory of the bundle. For example: - * `/Applications/SDLApp/` + * `/Applications/SDLApp/` * * The returned path is guaranteed to end with a path separator ('\' on * Windows, '/' on most other platforms). @@ -111,15 +109,12 @@ extern DECLSPEC char *SDLCALL SDL_GetBasePath(void); * follow these rules: * * - Try to use the same org string (_including case-sensitivity_) for all - * your applications that use this function. - * + * your applications that use this function. * - Always use a unique app string for each one, and make sure it never - * changes for an app once you've decided on it. - * + * changes for an app once you've decided on it. * - Unicode characters are legal, as long as it's UTF-8 encoded, but... - * * - ...only use letters, numbers, and spaces. Avoid punctuation like "Game - * Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient. + * Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient. * * The returned path is guaranteed to end with a path separator ('\' on * Windows, '/' on most other platforms). diff --git a/include/SDL_hints.h b/include/SDL_hints.h index 90e45de98..f7acfffce 100644 --- a/include/SDL_hints.h +++ b/include/SDL_hints.h @@ -1319,6 +1319,7 @@ extern "C" { * * Since it's driver-specific, it's only supported where possible and * implemented. Currently supported the following drivers: + * * - KMSDRM (kmsdrm) * - Raspberry Pi (raspberrypi) */ diff --git a/include/SDL_joystick.h b/include/SDL_joystick.h index cfdbcd8db..006d5fdce 100644 --- a/include/SDL_joystick.h +++ b/include/SDL_joystick.h @@ -666,26 +666,17 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAxisInitialState(SDL_Joystick *j * 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; hat indices start at index - * 0 + * \param hat the hat index to get the state from; indices start at index 0 * \returns the current hat position. * * \sa SDL_JoystickNumHats diff --git a/include/SDL_messagebox.h b/include/SDL_messagebox.h index 02f546902..c2aef70fa 100644 --- a/include/SDL_messagebox.h +++ b/include/SDL_messagebox.h @@ -148,9 +148,7 @@ extern DECLSPEC int SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *message * `flags` may be any of the following: * * - `SDL_MESSAGEBOX_ERROR`: error dialog - * * - `SDL_MESSAGEBOX_WARNING`: warning dialog - * * - `SDL_MESSAGEBOX_INFORMATION`: informational dialog * * This function should be called on the thread that created the parent diff --git a/include/SDL_mouse.h b/include/SDL_mouse.h index 3bfc4d195..2704c0d6e 100644 --- a/include/SDL_mouse.h +++ b/include/SDL_mouse.h @@ -255,11 +255,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(void); * 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=1: transparent - * * - data=1, mask=0: inverted color if possible, black if not. * * Cursors created with this function must be freed with SDL_FreeCursor(). diff --git a/include/SDL_platform.h b/include/SDL_platform.h index ea3aadd6a..ebaa25242 100644 --- a/include/SDL_platform.h +++ b/include/SDL_platform.h @@ -191,13 +191,9 @@ extern "C" { * Here are the names returned for some (but not all) supported platforms: * * - "Windows" - * * - "Mac OS X" - * * - "Linux" - * * - "iOS" - * * - "Android" * * \returns the name of the platform. If the correct platform name is not diff --git a/include/SDL_rwops.h b/include/SDL_rwops.h index 88003e403..09fe33b75 100644 --- a/include/SDL_rwops.h +++ b/include/SDL_rwops.h @@ -201,9 +201,7 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWsize(SDL_RWops *context); * `whence` may be any of the following values: * * - `RW_SEEK_SET`: seek from the beginning of data - * * - `RW_SEEK_CUR`: seek relative to current read point - * * - `RW_SEEK_END`: seek relative to the end of data * * If this stream can not seek, it will return -1. diff --git a/include/SDL_system.h b/include/SDL_system.h index 753272e5d..6fea7d30e 100644 --- a/include/SDL_system.h +++ b/include/SDL_system.h @@ -197,45 +197,25 @@ extern DECLSPEC void * SDLCALL SDL_AndroidGetActivity(void); * Query Android API level of the current device. * * - API level 30: Android 11 - * * - API level 29: Android 10 - * * - API level 28: Android 9 - * * - API level 27: Android 8.1 - * * - API level 26: Android 8.0 - * * - API level 25: Android 7.1 - * * - API level 24: Android 7.0 - * * - API level 23: Android 6.0 - * * - API level 22: Android 5.1 - * * - API level 21: Android 5.0 - * * - API level 20: Android 4.4W - * * - API level 19: Android 4.4 - * * - API level 18: Android 4.3 - * * - API level 17: Android 4.2 - * * - API level 16: Android 4.1 - * * - API level 15: Android 4.0.3 - * * - API level 14: Android 4.0 - * * - API level 13: Android 3.2 - * * - API level 12: Android 3.1 - * * - API level 11: Android 3.0 - * * - API level 10: Android 2.3.3 * * \returns Android API level. diff --git a/include/SDL_video.h b/include/SDL_video.h index 7a2c5042c..f803adf23 100644 --- a/include/SDL_video.h +++ b/include/SDL_video.h @@ -469,13 +469,9 @@ extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes(int displayIndex); * The display modes are sorted in this priority: * * - width -> largest to smallest - * * - height -> largest to smallest - * * - bits per pixel -> more colors to fewer colors - * * - packed pixel layout -> largest to smallest - * * - refresh rate -> highest to lowest * * \param displayIndex the index of the display to query @@ -619,29 +615,18 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window); * `flags` may be any of the following OR'd together: * * - `SDL_WINDOW_FULLSCREEN`: fullscreen window - * - * - `SDL_WINDOW_FULLSCREEN_DESKTOP: fullscreen window at desktop resolution - * + * - `SDL_WINDOW_FULLSCREEN_DESKTOP`: fullscreen window at desktop resolution * - `SDL_WINDOW_OPENGL`: window usable with an OpenGL context - * * - `SDL_WINDOW_VULKAN`: window usable with a Vulkan instance - * * - `SDL_WINDOW_METAL`: window usable with a Metal instance - * * - `SDL_WINDOW_HIDDEN`: window is not visible - * * - `SDL_WINDOW_BORDERLESS`: no window decoration - * * - `SDL_WINDOW_RESIZABLE`: window can be resized - * * - `SDL_WINDOW_MINIMIZED`: window is minimized - * * - `SDL_WINDOW_MAXIMIZED`: window is maximized - * * - `SDL_WINDOW_INPUT_GRABBED`: window has grabbed input focus - * * - `SDL_WINDOW_ALLOW_HIGHDPI`: window should be created in high-DPI mode if - * supported (>= SDL 2.0.1) + * supported (>= SDL 2.0.1) * * `SDL_WINDOW_SHOWN` is ignored by SDL_CreateWindow(). The SDL_Window is * implicitly shown if SDL_WINDOW_HIDDEN is not set. `SDL_WINDOW_SHOWN` may be @@ -1594,7 +1579,7 @@ extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path); * There are some quirks to looking up OpenGL functions that require some * extra care from the application. If you code carefully, you can handle * these quirks without any platform-specific code, though: - + * * - On Windows, function pointers are specific to the current GL context; * this means you need to have created a GL context and made it current before * calling SDL_GL_GetProcAddress(). If you recreate your context or create a @@ -1604,7 +1589,6 @@ extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path); * but it is still the way the wgl API is documented to work and you should * expect crashes if you don't respect it. Store a copy of the function * pointers that comes and goes with context lifespan. - * * - On X11, function pointers returned by this function are valid for any * context, and can even be looked up before a context is created at all. This * means that, for at least some common OpenGL implementations, if you look up @@ -1614,17 +1598,14 @@ extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path); * the appropriate extension with SDL_GL_ExtensionSupported(), or verifying * that the version of OpenGL you're using offers the function as core * functionality. - * * - Some OpenGL drivers, on all platforms, *will* return NULL if a function * isn't supported, but you can't count on this behavior. Check for extensions * you use, and if you get a NULL anyway, act as if that extension wasn't * available. This is probably a bug in the driver, but you can code * defensively for this scenario anyhow. - * * - Just because you're on Linux/Unix, don't assume you'll be using X11. * Next-gen display servers are waiting to replace it, and may or may not make * the same promises about function pointers. - * * - OpenGL function pointers must be declared `APIENTRY` as in the example * code. This will ensure the proper calling convention is followed on * platforms where this matters (Win32) thereby avoiding stack corruption.