mirrors/SDL
1
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2026-04-23 15:56:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

include: Filled in more documentation gaps.

Browse Source
This commit is contained in:
Ryan C. Gordon
2024-12-19 16:42:14 -05:00
parent 3ce68f80bc
commit 0c42891826
3 changed files with 245 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
include/SDL3/SDL_endian.h
View File

@@ -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__)

121
include/SDL3/SDL_timer.h
View File

@@ -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)
/**

50
include/SDL3/SDL_touch.h
View File

@@ -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)