SDL_intrin.h: Add documentation.

.wikiheaders-options

@@ -23,7 +23,7 @@ manpageheaderfiletext = Defined in SDL3/%fname%
 headercategoryeval = s/\ASDL_test_?.*?\.h\Z//; s/\ASDL_?(.*?)\.h\Z/$1/; ucfirst();
 
 quickrefenabled = 1
-quickrefcategoryorder = Init,Hints,Error,Version,Properties,Log,Video,Events,Keyboard,Mouse,Touch,Gamepad,Joystick,Haptic,Audio,Time,Timer,Render,SharedObject,Thread,Mutex,Atomic,Filesystem,IOStream,AsyncIO,Storage,Pixels,Surface,Blendmode,Rect,Camera,Clipboard,Dialog,GPU,Messagebox,Vulkan,Metal,Platform,Power,Sensor,Process,Bits,Endian,Assert,CPUInfo,Locale,System,Misc,GUID,Main,Stdinc
+quickrefcategoryorder = Init,Hints,Error,Version,Properties,Log,Video,Events,Keyboard,Mouse,Touch,Gamepad,Joystick,Haptic,Audio,Time,Timer,Render,SharedObject,Thread,Mutex,Atomic,Filesystem,IOStream,AsyncIO,Storage,Pixels,Surface,Blendmode,Rect,Camera,Clipboard,Dialog,GPU,Messagebox,Vulkan,Metal,Platform,Power,Sensor,Process,Bits,Endian,Assert,CPUInfo,Intrinsics,Locale,System,Misc,GUID,Main,Stdinc
 quickreftitle = SDL3 API Quick Reference
 quickrefurl = https://libsdl.org/
 quickrefdesc = The latest version of this document can be found at https://wiki.libsdl.org/SDL3/QuickReference

include/SDL3/SDL_intrin.h

@@ -19,8 +19,31 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
-/*
- * Header file for CPU intrinsics for SDL
+/* WIKI CATEGORY: Intrinsics */
+
+/**
+ * # CategoryIntrinsics
+ *
+ * SDL does some preprocessor gymnastics to determine if any CPU-specific
+ * compiler intrinsics are available, as this is not necessarily an easy
+ * thing to calculate, and sometimes depends on quirks of a system, versions
+ * of build tools, and other external forces.
+ *
+ * Apps including SDL's headers will be able to check consistent preprocessor
+ * definitions to decide if it's safe to use compiler intrinsics for a
+ * specific CPU architecture. This check only tells you that the compiler is
+ * capable of using those intrinsics; at runtime, you should still check
+ * if they are available on the current system with the
+ * [CPU info functions](https://wiki.libsdl.org/SDL3/CategoryCPUInfo), such as
+ * SDL_HasSSE() or SDL_HasNEON(). Otherwise, the process might crash for using
+ * an unsupported CPU instruction.
+ *
+ * SDL only sets preprocessor defines for CPU intrinsics if they are
+ * supported, so apps should check with `#ifdef` and not `#if`.
+ *
+ * SDL will also include the appropriate instruction-set-specific support
+ * headers, so if SDL decides to define SDL_SSE2_INTRINSICS, it will
+ * also `#include <emmintrin.h>` as well.
  */
 
 #ifndef SDL_intrin_h_
@@ -28,6 +51,150 @@
 
 #include <SDL3/SDL_stdinc.h>
 
+#ifdef SDL_WIKI_DOCUMENTATION_SECTION
+
+/**
+ * Defined if (and only if) the compiler supports Loongarch LSX intrinsics.
+ *
+ * If this macro is defined, SDL will have already included `<lsxintrin.h>`
+ *
+ * \since This macro is available since 3.1.3.
+ *
+ * \sa SDL_LASX_INTRINSICS
+ */
+#define SDL_LSX_INTRINSICS 1
+
+/**
+ * Defined if (and only if) the compiler supports Loongarch LSX intrinsics.
+ *
+ * If this macro is defined, SDL will have already included `<lasxintrin.h>`
+ *
+ * \since This macro is available since 3.1.3.
+ *
+ * \sa SDL_LASX_INTRINSICS
+ */
+#define SDL_LASX_INTRINSICS 1
+
+/**
+ * Defined if (and only if) the compiler supports Intel MMX intrinsics.
+ *
+ * If this macro is defined, SDL will have already included `<mmintrin.h>`
+ *
+ * \since This macro is available since 3.1.3.
+ *
+ * \sa SDL_SSE_INTRINSICS
+ */
+#define SDL_MMX_INTRINSICS 1
+
+/**
+ * Defined if (and only if) the compiler supports Intel SSE intrinsics.
+ *
+ * If this macro is defined, SDL will have already included `<xmmintrin.h>`
+ *
+ * \since This macro is available since 3.1.3.
+ *
+ * \sa SDL_SSE2_INTRINSICS
+ * \sa SDL_SSE3_INTRINSICS
+ * \sa SDL_SSE4_1_INTRINSICS
+ * \sa SDL_SSE4_2_INTRINSICS
+ */
+#define SDL_SSE_INTRINSICS 1
+
+/**
+ * Defined if (and only if) the compiler supports Intel SSE2 intrinsics.
+ *
+ * If this macro is defined, SDL will have already included `<emmintrin.h>`
+ *
+ * \since This macro is available since 3.1.3.
+ *
+ * \sa SDL_SSE_INTRINSICS
+ * \sa SDL_SSE3_INTRINSICS
+ * \sa SDL_SSE4_1_INTRINSICS
+ * \sa SDL_SSE4_2_INTRINSICS
+ */
+#define SDL_SSE2_INTRINSICS 1
+
+/**
+ * Defined if (and only if) the compiler supports Intel SSE3 intrinsics.
+ *
+ * If this macro is defined, SDL will have already included `<pmmintrin.h>`
+ *
+ * \since This macro is available since 3.1.3.
+ *
+ * \sa SDL_SSE_INTRINSICS
+ * \sa SDL_SSE2_INTRINSICS
+ * \sa SDL_SSE4_1_INTRINSICS
+ * \sa SDL_SSE4_2_INTRINSICS
+ */
+#define SDL_SSE3_INTRINSICS 1
+
+/**
+ * Defined if (and only if) the compiler supports Intel SSE4.1 intrinsics.
+ *
+ * If this macro is defined, SDL will have already included `<smmintrin.h>`
+ *
+ * \since This macro is available since 3.1.3.
+ *
+ * \sa SDL_SSE_INTRINSICS
+ * \sa SDL_SSE2_INTRINSICS
+ * \sa SDL_SSE3_INTRINSICS
+ * \sa SDL_SSE4_2_INTRINSICS
+ */
+#define SDL_SSE4_1_INTRINSICS 1
+
+/**
+ * Defined if (and only if) the compiler supports Intel SSE4.2 intrinsics.
+ *
+ * If this macro is defined, SDL will have already included `<nmmintrin.h>`
+ *
+ * \since This macro is available since 3.1.3.
+ *
+ * \sa SDL_SSE_INTRINSICS
+ * \sa SDL_SSE2_INTRINSICS
+ * \sa SDL_SSE3_INTRINSICS
+ * \sa SDL_SSE4_1_INTRINSICS
+ */
+#define SDL_SSE4_2_INTRINSICS 1
+
+/**
+ * Defined if (and only if) the compiler supports Intel AVX intrinsics.
+ *
+ * If this macro is defined, SDL will have already included `<immintrin.h>`
+ *
+ * \since This macro is available since 3.1.3.
+ *
+ * \sa SDL_AVX2_INTRINSICS
+ * \sa SDL_AVX512F_INTRINSICS
+ */
+#define SDL_AVX_INTRINSICS 1
+
+/**
+ * Defined if (and only if) the compiler supports Intel AVX2 intrinsics.
+ *
+ * If this macro is defined, SDL will have already included `<immintrin.h>`
+ *
+ * \since This macro is available since 3.1.3.
+ *
+ * \sa SDL_AVX_INTRINSICS
+ * \sa SDL_AVX512F_INTRINSICS
+ */
+#define SDL_AVX2_INTRINSICS 1
+
+/**
+ * Defined if (and only if) the compiler supports Intel AVX-512F intrinsics.
+ *
+ * AVX-512F is also sometimes referred to as "AVX-512 Foundation."
+ *
+ * If this macro is defined, SDL will have already included `<immintrin.h>`
+ *
+ * \since This macro is available since 3.1.3.
+ *
+ * \sa SDL_AVX_INTRINSICS
+ * \sa SDL_AVX2_INTRINSICS
+ */
+#define SDL_AVX512F_INTRINSICS 1
+#endif
+
 /* Need to do this here because intrin.h has C++ code in it */
 /* Visual Studio 2005 has a bug where intrin.h conflicts with winnt.h */
 #if defined(_MSC_VER) && (_MSC_VER >= 1500) && (defined(_M_IX86) || defined(_M_X64))