From 0c4289182651f35e2b987531b7144e75982ca9d1 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Thu, 19 Dec 2024 16:42:14 -0500
Subject: [PATCH] include: Filled in more documentation gaps.
---
include/SDL3/SDL_endian.h | 82 +++++++++++++++++++++++++-
include/SDL3/SDL_timer.h | 121 ++++++++++++++++++++++++++++++++++++++
include/SDL3/SDL_touch.h | 50 ++++++++++++++--
3 files changed, 245 insertions(+), 8 deletions(-)
diff --git a/include/SDL3/SDL_endian.h b/include/SDL3/SDL_endian.h
index 86aa4aa6b052c..bccf5a45d732b 100644
--- a/include/SDL3/SDL_endian.h
+++ b/include/SDL3/SDL_endian.h
@@ -64,12 +64,70 @@ _m_prefetch(void *__P)
* \name The two types of endianness
*/
/* @{ */
+
+
+/**
+ * A value to represent littleendian byteorder.
+ *
+ * This is used with the preprocessor macro SDL_BYTEORDER, to determine a
+ * platform's byte ordering:
+ *
+ * ```c
+ * #if SDL_BYTEORDER == SDL_LIL_ENDIAN
+ * SDL_Log("This system is littleendian.");
+ * #endif
+ * ```
+ *
+ * \since This macro is available since SDL 3.1.3.
+ *
+ * \sa SDL_BYTEORDER
+ * \sa SDL_BIG_ENDIAN
+ */
#define SDL_LIL_ENDIAN 1234
+
+/**
+ * A value to represent bigendian byteorder.
+ *
+ * This is used with the preprocessor macro SDL_BYTEORDER, to determine a
+ * platform's byte ordering:
+ *
+ * ```c
+ * #if SDL_BYTEORDER == SDL_BIG_ENDIAN
+ * SDL_Log("This system is bigendian.");
+ * #endif
+ * ```
+ *
+ * \since This macro is available since SDL 3.1.3.
+ *
+ * \sa SDL_BYTEORDER
+ * \sa SDL_LIL_ENDIAN
+ */
#define SDL_BIG_ENDIAN 4321
+
/* @} */
#ifndef SDL_BYTEORDER
-#ifdef SDL_PLATFORM_LINUX
+#ifdef SDL_WIKI_DOCUMENTATION_SECTION
+/**
+ * A macro that reports the target system's byte order.
+ *
+ * This is set to either SDL_LIL_ENDIAN or SDL_BIG_ENDIAN (and maybe other
+ * values in the future, if something else becomes popular). This can be
+ * tested with the preprocessor, so decisions can be made at compile time.
+ *
+ * ```c
+ * #if SDL_BYTEORDER == SDL_BIG_ENDIAN
+ * SDL_Log("This system is bigendian.");
+ * #endif
+ * ```
+ *
+ * \since This macro is available since SDL 3.1.3.
+ *
+ * \sa SDL_LIL_ENDIAN
+ * \sa SDL_BIG_ENDIAN
+ */
+#define SDL_BYTEORDER SDL_LIL_ENDIAN___or_maybe___SDL_BIG_ENDIAN
+#elif defined(SDL_PLATFORM_LINUX)
#include <endian.h>
#define SDL_BYTEORDER __BYTE_ORDER
#elif defined(SDL_PLATFORM_SOLARIS)
@@ -110,8 +168,28 @@ _m_prefetch(void *__P)
#endif /* !SDL_BYTEORDER */
#ifndef SDL_FLOATWORDORDER
+#ifdef SDL_WIKI_DOCUMENTATION_SECTION
+/**
+ * A macro that reports the target system's floating point word order.
+ *
+ * This is set to either SDL_LIL_ENDIAN or SDL_BIG_ENDIAN (and maybe other
+ * values in the future, if something else becomes popular). This can be
+ * tested with the preprocessor, so decisions can be made at compile time.
+ *
+ * ```c
+ * #if SDL_FLOATWORDORDER == SDL_BIG_ENDIAN
+ * SDL_Log("This system's floats are bigendian.");
+ * #endif
+ * ```
+ *
+ * \since This macro is available since SDL 3.1.3.
+ *
+ * \sa SDL_LIL_ENDIAN
+ * \sa SDL_BIG_ENDIAN
+ */
+#define SDL_FLOATWORDORDER SDL_LIL_ENDIAN___or_maybe___SDL_BIG_ENDIAN
/* predefs from newer gcc versions: */
-#if defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_BIG_ENDIAN__) && defined(__FLOAT_WORD_ORDER__)
+#elif defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_BIG_ENDIAN__) && defined(__FLOAT_WORD_ORDER__)
#if (__FLOAT_WORD_ORDER__ == __ORDER_LITTLE_ENDIAN__)
#define SDL_FLOATWORDORDER SDL_LIL_ENDIAN
#elif (__FLOAT_WORD_ORDER__ == __ORDER_BIG_ENDIAN__)
diff --git a/include/SDL3/SDL_timer.h b/include/SDL3/SDL_timer.h
index 62206cc778332..aaae6c0cf98cb 100644
--- a/include/SDL3/SDL_timer.h
+++ b/include/SDL3/SDL_timer.h
@@ -38,16 +38,137 @@ extern "C" {
#endif
/* SDL time constants */
+
+/**
+ * Number of milliseconds in a second.
+ *
+ * This is always 1000.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
#define SDL_MS_PER_SECOND 1000
+
+/**
+ * Number of microseconds in a second.
+ *
+ * This is always 1000000.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
#define SDL_US_PER_SECOND 1000000
+
+/**
+ * Number of nanoseconds in a second.
+ *
+ * This is always 1000000000.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
#define SDL_NS_PER_SECOND 1000000000LL
+
+/**
+ * Number of nanoseconds in a millisecond.
+ *
+ * This is always 1000000.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
#define SDL_NS_PER_MS 1000000
+
+/**
+ * Number of nanoseconds in a microsecond.
+ *
+ * This is always 1000.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
#define SDL_NS_PER_US 1000
+
+/**
+ * Convert seconds to nanoseconds.
+ *
+ * This only converts whole numbers, not fractional seconds.
+ *
+ * \param S the number of seconds to convert.
+ * \return S, expressed in nanoseconds.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
#define SDL_SECONDS_TO_NS(S) (((Uint64)(S)) * SDL_NS_PER_SECOND)
+
+/**
+ * Convert nanoseconds to seconds.
+ *
+ * This performs a division, so the results can be dramatically different
+ * if `NS` is an integer or floating point value.
+ *
+ * \param NS the number of nanoseconds to convert.
+ * \return NS, expressed in seconds.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
#define SDL_NS_TO_SECONDS(NS) ((NS) / SDL_NS_PER_SECOND)
+
+/**
+ * Convert milliseconds to nanoseconds.
+ *
+ * This only converts whole numbers, not fractional milliseconds.
+ *
+ * \param MS the number of milliseconds to convert.
+ * \return MS, expressed in nanoseconds.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
#define SDL_MS_TO_NS(MS) (((Uint64)(MS)) * SDL_NS_PER_MS)
+
+/**
+ * Convert nanoseconds to milliseconds.
+ *
+ * This performs a division, so the results can be dramatically different
+ * if `NS` is an integer or floating point value.
+ *
+ * \param NS the number of nanoseconds to convert.
+ * \return NS, expressed in milliseconds.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
#define SDL_NS_TO_MS(NS) ((NS) / SDL_NS_PER_MS)
+
+/**
+ * Convert microseconds to nanoseconds.
+ *
+ * This only converts whole numbers, not fractional microseconds.
+ *
+ * \param US the number of microseconds to convert.
+ * \return US, expressed in nanoseconds.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
#define SDL_US_TO_NS(US) (((Uint64)(US)) * SDL_NS_PER_US)
+
+/**
+ * Convert nanoseconds to microseconds.
+ *
+ * This performs a division, so the results can be dramatically different
+ * if `NS` is an integer or floating point value.
+ *
+ * \param NS the number of nanoseconds to convert.
+ * \return NS, expressed in microseconds.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
#define SDL_NS_TO_US(NS) ((NS) / SDL_NS_PER_US)
/**
diff --git a/include/SDL3/SDL_touch.h b/include/SDL3/SDL_touch.h
index 3eb47d52d5aa9..30d91111a2d26 100644
--- a/include/SDL3/SDL_touch.h
+++ b/include/SDL3/SDL_touch.h
@@ -38,21 +38,51 @@
extern "C" {
#endif
+/**
+ * A unique ID for a touch device.
+ *
+ * This ID is valid for the time the device is connected to the system, and is
+ * never reused for the lifetime of the application.
+ *
+ * The value 0 is an invalid ID.
+ *
+ * \since This datatype is available since SDL 3.1.3.
+ */
typedef Uint64 SDL_TouchID;
+
+/**
+ * A unique ID for a single finger on a touch device.
+ *
+ * This ID is valid for the time the finger (stylus, etc) is touching, and is
+ * never reused for the lifetime of the application.
+ *
+ * The same physical finger will have a different ID if it lifts off the touch
+ * device and then starts a new touch, so this ID tracks the lifetime of a
+ * single continuous touch.
+ *
+ * The value 0 is an invalid ID.
+ *
+ * \since This datatype is available since SDL 3.1.3.
+ */
typedef Uint64 SDL_FingerID;
+/**
+ * An enum that describes the type of a touch device.
+ *
+ * \since This enum is available since SDL 3.1.3.
+ */
typedef enum SDL_TouchDeviceType
{
SDL_TOUCH_DEVICE_INVALID = -1,
- SDL_TOUCH_DEVICE_DIRECT, /* touch screen with window-relative coordinates */
- SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE, /* trackpad with absolute device coordinates */
- SDL_TOUCH_DEVICE_INDIRECT_RELATIVE /* trackpad with screen cursor-relative coordinates */
+ SDL_TOUCH_DEVICE_DIRECT, /**< touch screen with window-relative coordinates */
+ SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE, /**< trackpad with absolute device coordinates */
+ SDL_TOUCH_DEVICE_INDIRECT_RELATIVE /**< trackpad with screen cursor-relative coordinates */
} SDL_TouchDeviceType;
/**
* Data about a single finger in a multitouch event.
*
- * Each touch even is a collection of fingers that are simultaneously in
+ * Each touch event is a collection of fingers that are simultaneously in
* contact with the touch device (so a "touch" can be a "multitouch," in
* reality), and this struct reports details of the specific fingers.
*
@@ -68,10 +98,18 @@ typedef struct SDL_Finger
float pressure; /**< the quantity of pressure applied, normalized (0...1) */
} SDL_Finger;
-/* Used as the device ID for mouse events simulated with touch input */
+/**
+ * The SDL_MouseID for mouse events simulated with touch input.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
#define SDL_TOUCH_MOUSEID ((SDL_MouseID)-1)
-/* Used as the SDL_TouchID for touch events simulated with mouse input */
+/**
+ * The SDL_TouchID for touch events simulated with mouse input.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
#define SDL_MOUSE_TOUCHID ((SDL_TouchID)-1)