From 73b294cb1cd933f45a433c217736a16592b17ccb Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" Date: Fri, 6 Sep 2024 15:09:29 -0400 Subject: [PATCH] SDL_platform_defines.h: Added documentation, and a little whitespace. wikiheaders needs the documentation in the first row of the line, at least currently, so I've only indented things I could get away with, but it might be a little easier to follow the preprocessor logic now. --- docs/README-documentation-rules.md | 4 + include/SDL3/SDL_platform_defines.h | 377 ++++++++++++++++++++++++---- 2 files changed, 328 insertions(+), 53 deletions(-) diff --git a/docs/README-documentation-rules.md b/docs/README-documentation-rules.md index 4506dc0b2f..ae705378f7 100644 --- a/docs/README-documentation-rules.md +++ b/docs/README-documentation-rules.md @@ -64,6 +64,10 @@ Note the `/**` at the start of the comment. That's a "Doxygen-style" comment, and wikiheaders will treat this differently than a comment with one `*`, as this signifies that this is not just a comment, but _documentation_. +These comments _must_ start in the first column of the line, or wikiheaders +will ignore them, even with the "/**" start (we should improve the script +someday to handle this, but currently this is a requirement). + We do _not_ parse every magic Doxygen tag, and we don't parse them in `@param` format. The goal here was to mostly coexist with people that might want to run Doxygen on the SDL headers, not to build Doxygen from scratch. That diff --git a/include/SDL3/SDL_platform_defines.h b/include/SDL3/SDL_platform_defines.h index ea717cc8d6..4f878e3b20 100644 --- a/include/SDL3/SDL_platform_defines.h +++ b/include/SDL3/SDL_platform_defines.h @@ -29,180 +29,451 @@ #define SDL_platform_defines_h_ #ifdef _AIX -#define SDL_PLATFORM_AIX 1 + +/** + * A preprocessor macro that is only defined if compiling for AIX. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_AIX 1 #endif + #ifdef __HAIKU__ -#define SDL_PLATFORM_HAIKU 1 + +/** + * A preprocessor macro that is only defined if compiling for Haiku OS. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_HAIKU 1 #endif + #if defined(bsdi) || defined(__bsdi) || defined(__bsdi__) -#define SDL_PLATFORM_BSDI 1 + +/** + * A preprocessor macro that is only defined if compiling for BSDi + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_BSDI 1 #endif + #if defined(__FreeBSD__) || defined(__FreeBSD_kernel__) || defined(__DragonFly__) + +/** + * A preprocessor macro that is only defined if compiling for FreeBSD. + * + * \since This macro is available since SDL 3.0.0. + */ #define SDL_PLATFORM_FREEBSD 1 #endif + #if defined(hpux) || defined(__hpux) || defined(__hpux__) -#define SDL_PLATFORM_HPUX 1 + +/** + * A preprocessor macro that is only defined if compiling for HP-UX. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_HPUX 1 #endif + #if defined(sgi) || defined(__sgi) || defined(__sgi__) || defined(_SGI_SOURCE) -#define SDL_PLATFORM_IRIX 1 + +/** + * A preprocessor macro that is only defined if compiling for IRIX. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_IRIX 1 #endif + #if (defined(linux) || defined(__linux) || defined(__linux__)) -#define SDL_PLATFORM_LINUX 1 + +/** + * A preprocessor macro that is only defined if compiling for Linux. + * + * Note that Android, although ostensibly a Linux-based system, will not + * define this. It defines SDL_PLATFORM_ANDROID instead. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_LINUX 1 #endif + #if defined(ANDROID) || defined(__ANDROID__) -#undef SDL_PLATFORM_LINUX /* do we need to do this? */ -#define SDL_PLATFORM_ANDROID 1 + +/** + * A preprocessor macro that is only defined if compiling for Android. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_ANDROID 1 +#undef SDL_PLATFORM_LINUX #endif + #ifdef __NGAGE__ + +/** + * A preprocessor macro that is only defined if compiling for Nokia N-Gage. + * + * \since This macro is available since SDL 3.0.0. + */ #define SDL_PLATFORM_NGAGE 1 #endif #if defined(__unix__) || defined(__unix) || defined(unix) -#define SDL_PLATFORM_UNIX 1 + +/** + * A preprocessor macro that is only defined if compiling for a Unix-like + * system. + * + * Other platforms, like Linux, might define this in addition to their primary + * define. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_UNIX 1 #endif #ifdef __APPLE__ -#define SDL_PLATFORM_APPLE 1 + +/** + * A preprocessor macro that is only defined if compiling for Apple platforms. + * + * iOS, macOS, etc will additionally define a more specific platform macro. + * + * \since This macro is available since SDL 3.0.0. + * + * \sa SDL_PLATFORM_MACOS + * \sa SDL_PLATFORM_IOS + * \sa SDL_PLATFORM_TVOS + * \sa SDL_PLATFORM_VISIONOS + */ +#define SDL_PLATFORM_APPLE 1 + /* lets us know what version of macOS we're compiling on */ #include #ifndef __has_extension /* Older compilers don't support this */ -#define __has_extension(x) 0 -#include -#undef __has_extension + #define __has_extension(x) 0 + #include + #undef __has_extension #else -#include + #include #endif /* Fix building with older SDKs that don't define these - See this for more information: - https://stackoverflow.com/questions/12132933/preprocessor-macro-for-os-x-targets + See this for more information: + https://stackoverflow.com/questions/12132933/preprocessor-macro-for-os-x-targets */ #ifndef TARGET_OS_MACCATALYST -#define TARGET_OS_MACCATALYST 0 + #define TARGET_OS_MACCATALYST 0 #endif #ifndef TARGET_OS_IOS -#define TARGET_OS_IOS 0 + #define TARGET_OS_IOS 0 #endif #ifndef TARGET_OS_IPHONE -#define TARGET_OS_IPHONE 0 + #define TARGET_OS_IPHONE 0 #endif #ifndef TARGET_OS_TV -#define TARGET_OS_TV 0 + #define TARGET_OS_TV 0 #endif #ifndef TARGET_OS_SIMULATOR -#define TARGET_OS_SIMULATOR 0 + #define TARGET_OS_SIMULATOR 0 #endif #ifndef TARGET_OS_VISION -#define TARGET_OS_VISION 0 + #define TARGET_OS_VISION 0 #endif #if TARGET_OS_TV -#define SDL_PLATFORM_TVOS 1 + +/** + * A preprocessor macro that is only defined if compiling for tvOS. + * + * \since This macro is available since SDL 3.0.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_TVOS 1 #endif + #if TARGET_OS_VISION + +/** + * A preprocessor macro that is only defined if compiling for VisionOS. + * + * \since This macro is available since SDL 3.0.0. + * + * \sa SDL_PLATFORM_APPLE + */ #define SDL_PLATFORM_VISIONOS 1 #endif + #if TARGET_OS_IPHONE -#define SDL_PLATFORM_IOS 1 + +/** + * A preprocessor macro that is only defined if compiling for iOS. + * + * \since This macro is available since SDL 3.0.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_IOS 1 + #else -#define SDL_PLATFORM_MACOS 1 + +/** + * A preprocessor macro that is only defined if compiling for macOS. + * + * \since This macro is available since SDL 3.0.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_MACOS 1 + #if MAC_OS_X_VERSION_MIN_REQUIRED < 1070 -# error SDL for macOS only supports deploying on 10.7 and above. + #error SDL for macOS only supports deploying on 10.7 and above. #endif /* MAC_OS_X_VERSION_MIN_REQUIRED < 1070 */ #endif /* TARGET_OS_IPHONE */ -#endif /* defined(SDL_PLATFORM_APPLE) */ +#endif /* defined(__APPLE__) */ #ifdef __EMSCRIPTEN__ + +/** + * A preprocessor macro that is only defined if compiling for Emscripten. + * + * \since This macro is available since SDL 3.0.0. + */ #define SDL_PLATFORM_EMSCRIPTEN 1 #endif + #ifdef __NetBSD__ + +/** + * A preprocessor macro that is only defined if compiling for NetBSD. + * + * \since This macro is available since SDL 3.0.0. + */ #define SDL_PLATFORM_NETBSD 1 #endif + #ifdef __OpenBSD__ -#define SDL_PLATFORM_OPENBSD 1 + +/** + * A preprocessor macro that is only defined if compiling for OpenBSD. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_OPENBSD 1 #endif + #if defined(__OS2__) || defined(__EMX__) -#define SDL_PLATFORM_OS2 1 + +/** + * A preprocessor macro that is only defined if compiling for OS/2. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_OS2 1 #endif + #if defined(osf) || defined(__osf) || defined(__osf__) || defined(_OSF_SOURCE) -#define SDL_PLATFORM_OSF 1 + +/** + * A preprocessor macro that is only defined if compiling for Tru64 (OSF/1). + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_OSF 1 #endif + #ifdef __QNXNTO__ + +/** + * A preprocessor macro that is only defined if compiling for QNX Neutrino. + * + * \since This macro is available since SDL 3.0.0. + */ #define SDL_PLATFORM_QNXNTO 1 #endif + #if defined(riscos) || defined(__riscos) || defined(__riscos__) + +/** + * A preprocessor macro that is only defined if compiling for RISC OS. + * + * \since This macro is available since SDL 3.0.0. + */ #define SDL_PLATFORM_RISCOS 1 #endif + #if defined(__sun) && defined(__SVR4) -#define SDL_PLATFORM_SOLARIS 1 + +/** + * A preprocessor macro that is only defined if compiling for SunOS/Solaris. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_SOLARIS 1 #endif #if defined(__CYGWIN__) + +/** + * A preprocessor macro that is only defined if compiling for Cygwin. + * + * \since This macro is available since SDL 3.0.0. + */ #define SDL_PLATFORM_CYGWIN 1 #endif #if defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) -#define SDL_PLATFORM_WINDOWS 1 /* Win32 api and Windows-based OSs */ + +/** + * A preprocessor macro that is only defined if compiling for Windows. + * + * This also covers several other platforms, like Microsoft GDK, Xbox, WinRT, + * etc. Each will have their own more-specific platform macros, too. + * + * \since This macro is available since SDL 3.0.0. + * + * \sa SDL_PLATFORM_WIN32 + * \sa SDL_PLATFORM_XBOXONE + * \sa SDL_PLATFORM_XBOXSERIES + * \sa SDL_PLATFORM_WINGDK + * \sa SDL_PLATFORM_GDK + */ +#define SDL_PLATFORM_WINDOWS 1 /* Try to find out if we're compiling for WinRT, GDK or non-WinRT/GDK */ #if defined(_MSC_VER) && defined(__has_include) -#if __has_include() -#define HAVE_WINAPIFAMILY_H 1 -#else -#define HAVE_WINAPIFAMILY_H 0 -#endif + #if __has_include() + #define HAVE_WINAPIFAMILY_H 1 + #else + #define HAVE_WINAPIFAMILY_H 0 + #endif -/* If _USING_V110_SDK71_ is defined it means we are using the Windows XP toolset. */ + /* If _USING_V110_SDK71_ is defined it means we are using the Windows XP toolset. */ #elif defined(_MSC_VER) && (_MSC_VER >= 1700 && !_USING_V110_SDK71_) /* _MSC_VER == 1700 for Visual Studio 2012 */ -#define HAVE_WINAPIFAMILY_H 1 + #define HAVE_WINAPIFAMILY_H 1 #else -#define HAVE_WINAPIFAMILY_H 0 + #define HAVE_WINAPIFAMILY_H 0 #endif #if HAVE_WINAPIFAMILY_H -#include -#define WINAPI_FAMILY_WINRT (!WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP) && WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_APP)) + #include + #define WINAPI_FAMILY_WINRT (!WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP) && WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_APP)) #else -#define WINAPI_FAMILY_WINRT 0 + #define WINAPI_FAMILY_WINRT 0 #endif /* HAVE_WINAPIFAMILY_H */ #if HAVE_WINAPIFAMILY_H && HAVE_WINAPIFAMILY_H -#define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP) + #define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP) #else -#define SDL_WINAPI_FAMILY_PHONE 0 + #define SDL_WINAPI_FAMILY_PHONE 0 #endif #if WINAPI_FAMILY_WINRT #error Windows RT/UWP is no longer supported in SDL + #elif defined(_GAMING_DESKTOP) /* GDK project configuration always defines _GAMING_XXX */ + +/** + * A preprocessor macro that is only defined if compiling for Microsoft GDK + * for Windows. + * + * \since This macro is available since SDL 3.0.0. + */ #define SDL_PLATFORM_WINGDK 1 + #elif defined(_GAMING_XBOX_XBOXONE) -#define SDL_PLATFORM_XBOXONE 1 + +/** + * A preprocessor macro that is only defined if compiling for Xbox One. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_XBOXONE 1 + #elif defined(_GAMING_XBOX_SCARLETT) + +/** + * A preprocessor macro that is only defined if compiling for Xbox Series. + * + * \since This macro is available since SDL 3.0.0. + */ #define SDL_PLATFORM_XBOXSERIES 1 + #else -#define SDL_PLATFORM_WIN32 1 + +/** + * A preprocessor macro that is only defined if compiling for desktop Windows. + * + * Despite the "32", this also covers 64-bit Windows; as an informal + * convention, its system layer tends to still be referred to as "the Win32 + * API." + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_WIN32 1 + #endif -#endif /* defined(WIN32) || defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) */ +#endif /* defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) */ + /* This is to support generic "any GDK" separate from a platform-specific GDK */ #if defined(SDL_PLATFORM_WINGDK) || defined(SDL_PLATFORM_XBOXONE) || defined(SDL_PLATFORM_XBOXSERIES) -#define SDL_PLATFORM_GDK 1 + +/** + * A preprocessor macro that is only defined if compiling for Microsoft GDK on + * any platform. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_GDK 1 #endif + #if defined(__PSP__) || defined(__psp__) -#define SDL_PLATFORM_PSP 1 + +/** + * A preprocessor macro that is only defined if compiling for Sony PSP. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_PSP 1 #endif + #if defined(__PS2__) || defined(PS2) -#define SDL_PLATFORM_PS2 1 + +/** + * A preprocessor macro that is only defined if compiling for Sony PlayStation + * 2. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_PS2 1 #endif #if defined(__vita__) || defined(__psp2__) -#define SDL_PLATFORM_VITA 1 + +/** + * A preprocessor macro that is only defined if compiling for Sony Vita. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_VITA 1 #endif #ifdef __3DS__ + +/** + * A preprocessor macro that is only defined if compiling for Nintendo 3DS. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_3DS 1 + #undef __3DS__ -#define SDL_PLATFORM_3DS 1 #endif #endif /* SDL_platform_defines_h_ */