diff --git a/include/SDL3/SDL_endian.h b/include/SDL3/SDL_endian.h index 86aa4aa6b0..bccf5a45d7 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 #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 62206cc778..aaae6c0cf9 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 3eb47d52d5..30d91111a2 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)