From a790a678836afa4f954d75584219c06789b961d8 Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" Date: Fri, 3 May 2024 13:01:41 -0400 Subject: [PATCH] include: Filling in more documentation gaps. --- include/SDL3/SDL_audio.h | 1 - include/SDL3/SDL_cpuinfo.h | 12 ++-- include/SDL3/SDL_surface.h | 14 ++++- include/SDL3/SDL_system.h | 110 +++++++++++++++++++++++++++++++------ include/SDL3/SDL_video.h | 25 +++++---- 5 files changed, 125 insertions(+), 37 deletions(-) diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h index e6ae924bcf..08a1b7c149 100644 --- a/include/SDL3/SDL_audio.h +++ b/include/SDL3/SDL_audio.h @@ -312,7 +312,6 @@ typedef struct SDL_AudioSpec * * \sa SDL_CreateAudioStream */ -struct SDL_AudioStream; /**< this is opaque to the outside world. */ typedef struct SDL_AudioStream SDL_AudioStream; diff --git a/include/SDL3/SDL_cpuinfo.h b/include/SDL3/SDL_cpuinfo.h index 59a4b32539..8c077299d6 100644 --- a/include/SDL3/SDL_cpuinfo.h +++ b/include/SDL3/SDL_cpuinfo.h @@ -36,10 +36,14 @@ extern "C" { #endif -/* This is a guess for the cacheline size used for padding. - * Most x86 processors have a 64 byte cache line. - * The 64-bit PowerPC processors have a 128 byte cache line. - * We'll use the larger value to be generally safe. +/** + * A guess for the cacheline size used for padding. + * + * Most x86 processors have a 64 byte cache line. The 64-bit PowerPC + * processors have a 128 byte cache line. We use the larger value to be + * generally safe. + * + * \since This macro is available since SDL 3.0.0. */ #define SDL_CACHELINE_SIZE 128 diff --git a/include/SDL3/SDL_surface.h b/include/SDL3/SDL_surface.h index 7d124a6a84..5e519c6859 100644 --- a/include/SDL3/SDL_surface.h +++ b/include/SDL3/SDL_surface.h @@ -66,10 +66,18 @@ extern "C" { */ #define SDL_MUSTLOCK(S) (((S)->flags & SDL_RLEACCEL) != 0) -typedef struct SDL_BlitMap SDL_BlitMap; /* this is an opaque type. */ +/** + * An opaque type used in SDL_Surface. + * + * This is used by SDL to keep track of how blit operations should work + * internally; it is not for use directly by applications. + * + * \since This struct is available since SDL 3.0.0. + */ +typedef struct SDL_BlitMap SDL_BlitMap; /** - * The scaling mode + * The scaling mode. * * \since This enum is available since SDL 3.0.0. */ @@ -81,7 +89,7 @@ typedef enum SDL_ScaleMode } SDL_ScaleMode; /** - * The flip mode + * The flip mode. * * \since This enum is available since SDL 3.0.0. */ diff --git a/include/SDL3/SDL_system.h b/include/SDL3/SDL_system.h index 0d79c7143d..2070d50cd6 100644 --- a/include/SDL3/SDL_system.h +++ b/include/SDL3/SDL_system.h @@ -568,49 +568,125 @@ extern DECLSPEC SDL_WinRT_DeviceFamily SDLCALL SDL_WinRTGetDeviceFamily(); */ extern DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void); -/* Functions used by iOS app delegates to notify SDL about state changes. - * - * These functions allow iOS apps that have their own event handling to hook - * into SDL to generate SDL events. These map directly to iOS-specific - * events, but since they don't do anything iOS-specific internally, they - * are available on all platforms, in case they might be useful for some - * specific paradigm. Most apps do not need to use these directly; SDL's - * internal event code will handle all this for windows created by - * SDL_CreateWindow! - */ +/* Functions used by iOS app delegates to notify SDL about state changes. */ -/* +/** + * Let iOS apps with external event handling report + * onApplicationWillTerminate. + * + * This functions allows iOS apps that have their own event handling to hook + * into SDL to generate SDL events. This maps directly to an iOS-specific + * event, but since it doesn't do anything iOS-specific internally, it is + * available on all platforms, in case it might be useful for some specific + * paradigm. Most apps do not need to use this directly; SDL's internal event + * code will handle all this for windows created by SDL_CreateWindow! + * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. */ extern DECLSPEC void SDLCALL SDL_OnApplicationWillTerminate(void); -/* +/** + * Let iOS apps with external event handling report + * onApplicationDidReceiveMemoryWarning. + * + * This functions allows iOS apps that have their own event handling to hook + * into SDL to generate SDL events. This maps directly to an iOS-specific + * event, but since it doesn't do anything iOS-specific internally, it is + * available on all platforms, in case it might be useful for some specific + * paradigm. Most apps do not need to use this directly; SDL's internal event + * code will handle all this for windows created by SDL_CreateWindow! + * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. */ extern DECLSPEC void SDLCALL SDL_OnApplicationDidReceiveMemoryWarning(void); -/* +/** + * Let iOS apps with external event handling report + * onApplicationWillResignActive. + * + * This functions allows iOS apps that have their own event handling to hook + * into SDL to generate SDL events. This maps directly to an iOS-specific + * event, but since it doesn't do anything iOS-specific internally, it is + * available on all platforms, in case it might be useful for some specific + * paradigm. Most apps do not need to use this directly; SDL's internal event + * code will handle all this for windows created by SDL_CreateWindow! + * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. */ extern DECLSPEC void SDLCALL SDL_OnApplicationWillResignActive(void); -/* +/** + * Let iOS apps with external event handling report + * onApplicationDidEnterBackground. + * + * This functions allows iOS apps that have their own event handling to hook + * into SDL to generate SDL events. This maps directly to an iOS-specific + * event, but since it doesn't do anything iOS-specific internally, it is + * available on all platforms, in case it might be useful for some specific + * paradigm. Most apps do not need to use this directly; SDL's internal event + * code will handle all this for windows created by SDL_CreateWindow! + * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. */ extern DECLSPEC void SDLCALL SDL_OnApplicationDidEnterBackground(void); -/* +/** + * Let iOS apps with external event handling report + * onApplicationWillEnterForeground. + * + * This functions allows iOS apps that have their own event handling to hook + * into SDL to generate SDL events. This maps directly to an iOS-specific + * event, but since it doesn't do anything iOS-specific internally, it is + * available on all platforms, in case it might be useful for some specific + * paradigm. Most apps do not need to use this directly; SDL's internal event + * code will handle all this for windows created by SDL_CreateWindow! + * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. */ extern DECLSPEC void SDLCALL SDL_OnApplicationWillEnterForeground(void); -/* +/** + * Let iOS apps with external event handling report + * onApplicationDidBecomeActive. + * + * This functions allows iOS apps that have their own event handling to hook + * into SDL to generate SDL events. This maps directly to an iOS-specific + * event, but since it doesn't do anything iOS-specific internally, it is + * available on all platforms, in case it might be useful for some specific + * paradigm. Most apps do not need to use this directly; SDL's internal event + * code will handle all this for windows created by SDL_CreateWindow! + * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. */ extern DECLSPEC void SDLCALL SDL_OnApplicationDidBecomeActive(void); #ifdef SDL_PLATFORM_IOS -/* + +/** + * Let iOS apps with external event handling report + * onApplicationDidChangeStatusBarOrientation. + * + * This functions allows iOS apps that have their own event handling to hook + * into SDL to generate SDL events. This maps directly to an iOS-specific + * event, but since it doesn't do anything iOS-specific internally, it is + * available on all platforms, in case it might be useful for some specific + * paradigm. Most apps do not need to use this directly; SDL's internal event + * code will handle all this for windows created by SDL_CreateWindow! + * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. */ extern DECLSPEC void SDLCALL SDL_OnApplicationDidChangeStatusBarOrientation(void); diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h index 4f1c50825d..43e6c339c1 100644 --- a/include/SDL3/SDL_video.h +++ b/include/SDL3/SDL_video.h @@ -45,19 +45,20 @@ extern "C" { typedef Uint32 SDL_DisplayID; typedef Uint32 SDL_WindowID; -/* - * Global video properties. +/* Global video properties... */ + +/** + * The pointer to the global `wl_display` object used by the Wayland video + * backend. * - * - `SDL_PROP_GLOBAL_VIDEO_WAYLAND_WL_DISPLAY_POINTER`: the pointer to - * the global `wl_display` object used by the Wayland video backend. Can be - * set before the video subsystem is initialized to import an external - * `wl_display` object from an application or toolkit for use in SDL, or - * read after initialization to export the `wl_display` used by the - * Wayland video backend. Setting this property after the video subsystem - * has been initialized has no effect, and reading it when the video - * subsystem is uninitialized will either return the user provided value, - * if one was set prior to initialization, or NULL. See - * docs/README-wayland.md for more information. + * Can be set before the video subsystem is initialized to import an external + * `wl_display` object from an application or toolkit for use in SDL, or read + * after initialization to export the `wl_display` used by the Wayland video + * backend. Setting this property after the video subsystem has been + * initialized has no effect, and reading it when the video subsystem is + * uninitialized will either return the user provided value, if one was set + * prior to initialization, or NULL. See docs/README-wayland.md for more + * information. */ #define SDL_PROP_GLOBAL_VIDEO_WAYLAND_WL_DISPLAY_POINTER "SDL.video.wayland.wl_display"