include: A ton of little documentation tweaks, fixes, and improvements.
This is just stuff I noticed while working on the wikiheaders updates. A thorough pass over all the docs would not be terrible, and maybe a simple script to check for consistency (does everything have a `\since` on it? etc) might be nice, too.
This commit is contained in:
Ryan C. Gordon
@@ -28,18 +28,18 @@
|
||||
* and drawing tablets or suitably equipped mobile / tablet devices.
|
||||
*
|
||||
* To get started with pens:
|
||||
* - Listen to ::SDL_PenMotionEvent and ::SDL_PenButtonEvent
|
||||
* - To avoid treating pen events as mouse events, ignore ::SDL_MouseMotionEvent and ::SDL_MouseButtonEvent
|
||||
* whenever "which" == ::SDL_PEN_MOUSEID.
|
||||
* - Listen to SDL_PenMotionEvent and SDL_PenButtonEvent
|
||||
* - To avoid treating pen events as mouse events, ignore SDL_MouseMotionEvent and SDL_MouseButtonEvent
|
||||
* whenever "which" == SDL_PEN_MOUSEID.
|
||||
*
|
||||
* This header file describes advanced functionality that can be useful for managing user configuration
|
||||
* and understanding the capabilities of the attached pens.
|
||||
*
|
||||
* We primarily identify pens by ::SDL_PenID. The implementation makes a best effort to relate each :SDL_PenID
|
||||
* to the same physical device during a session. Formerly valid ::SDL_PenID values remain valid
|
||||
* We primarily identify pens by SDL_PenID. The implementation makes a best effort to relate each :SDL_PenID
|
||||
* to the same physical device during a session. Formerly valid SDL_PenID values remain valid
|
||||
* even if a device disappears.
|
||||
*
|
||||
* For identifying pens across sessions, the API provides the type ::SDL_GUID .
|
||||
* For identifying pens across sessions, the API provides the type SDL_GUID .
|
||||
*/
|
||||
|
||||
#ifndef SDL_pen_h_
|
||||
@@ -57,7 +57,7 @@ extern "C" {
|
||||
|
||||
typedef Uint32 SDL_PenID; /**< SDL_PenIDs identify pens uniquely within a session */
|
||||
|
||||
#define SDL_PEN_INVALID ((SDL_PenID)0) /**< Reserved invalid ::SDL_PenID is valid */
|
||||
#define SDL_PEN_INVALID ((SDL_PenID)0) /**< Reserved invalid SDL_PenID is valid */
|
||||
|
||||
#define SDL_PEN_MOUSEID ((SDL_MouseID)-2) /**< Device ID for mouse events triggered by pen events */
|
||||
|
||||
@@ -66,16 +66,20 @@ typedef Uint32 SDL_PenID; /**< SDL_PenIDs identify pens uniquely within a sessio
|
||||
/**
|
||||
* Pen axis indices
|
||||
*
|
||||
* Below are the valid indices to the "axis" array from ::SDL_PenMotionEvent and ::SDL_PenButtonEvent.
|
||||
* The axis indices form a contiguous range of ints from 0 to ::SDL_PEN_AXIS_LAST, inclusive.
|
||||
* Below are the valid indices to the "axis" array from SDL_PenMotionEvent and SDL_PenButtonEvent.
|
||||
* The axis indices form a contiguous range of ints from 0 to SDL_PEN_AXIS_LAST, inclusive.
|
||||
* All "axis[]" entries are either normalised to 0..1 or report a (positive or negative)
|
||||
* angle in degrees, with 0.0 representing the centre.
|
||||
* Not all pens/backends support all axes: unsupported entries are always "0.0f".
|
||||
*
|
||||
* To convert angles for tilt and rotation into vector representation, use
|
||||
* SDL_sinf on the XTILT, YTILT, or ROTATION component, e.g., "SDL_sinf(xtilt * SDL_PI_F / 180.0)".
|
||||
* SDL_sinf on the XTILT, YTILT, or ROTATION component, for example:
|
||||
*
|
||||
* `SDL_sinf(xtilt * SDL_PI_F / 180.0)`.
|
||||
*
|
||||
* \since This enum is available since SDL 3.0.0
|
||||
*/
|
||||
typedef enum
|
||||
typedef enum SDL_PenAxis
|
||||
{
|
||||
SDL_PEN_AXIS_PRESSURE = 0, /**< Pen pressure. Unidirectional: 0..1.0 */
|
||||
SDL_PEN_AXIS_XTILT, /**< Pen horizontal tilt angle. Bidirectional: -90.0..90.0 (left-to-right).
|
||||
@@ -89,7 +93,7 @@ typedef enum
|
||||
SDL_PEN_AXIS_LAST = SDL_PEN_NUM_AXES - 1 /**< Last axis index plus 1 */
|
||||
} SDL_PenAxis;
|
||||
|
||||
/* Pen flags. These share a bitmask space with ::SDL_BUTTON_LEFT and friends. */
|
||||
/* Pen flags. These share a bitmask space with SDL_BUTTON_LEFT and friends. */
|
||||
#define SDL_PEN_FLAG_DOWN_BIT_INDEX 13 /* Bit for storing that pen is touching the surface */
|
||||
#define SDL_PEN_FLAG_INK_BIT_INDEX 14 /* Bit for storing has-non-eraser-capability status */
|
||||
#define SDL_PEN_FLAG_ERASER_BIT_INDEX 15 /* Bit for storing is-eraser or has-eraser-capability property */
|
||||
@@ -98,41 +102,31 @@ typedef enum
|
||||
#define SDL_PEN_CAPABILITY(capbit) (1ul << (capbit))
|
||||
#define SDL_PEN_AXIS_CAPABILITY(axis) SDL_PEN_CAPABILITY((axis) + SDL_PEN_FLAG_AXIS_BIT_OFFSET)
|
||||
|
||||
/**
|
||||
* Pen tips
|
||||
* @{
|
||||
*/
|
||||
/* Pen tips */
|
||||
#define SDL_PEN_TIP_INK SDL_PEN_FLAG_INK_BIT_INDEX /**< Regular pen tip (for drawing) touched the surface */
|
||||
#define SDL_PEN_TIP_ERASER SDL_PEN_FLAG_ERASER_BIT_INDEX /**< Eraser pen tip touched the surface */
|
||||
/** @} */
|
||||
|
||||
|
||||
/**
|
||||
* \defgroup SDL_PEN_CAPABILITIES Pen capabilities
|
||||
* Pen capabilities reported by ::SDL_GetPenCapabilities
|
||||
* @{
|
||||
*/
|
||||
/* Pen capabilities reported by SDL_GetPenCapabilities */
|
||||
#define SDL_PEN_DOWN_MASK SDL_PEN_CAPABILITY(SDL_PEN_FLAG_DOWN_BIT_INDEX) /**< Pen tip is currently touching the drawing surface. */
|
||||
#define SDL_PEN_INK_MASK SDL_PEN_CAPABILITY(SDL_PEN_FLAG_INK_BIT_INDEX) /**< Pen has a regular drawing tip (::SDL_GetPenCapabilities). For events (::SDL_PenButtonEvent, ::SDL_PenMotionEvent, ::SDL_GetPenStatus) this flag is mutually exclusive with ::SDL_PEN_ERASER_MASK . */
|
||||
#define SDL_PEN_ERASER_MASK SDL_PEN_CAPABILITY(SDL_PEN_FLAG_ERASER_BIT_INDEX) /**< Pen has an eraser tip (::SDL_GetPenCapabilities) or is being used as eraser (::SDL_PenButtonEvent , ::SDL_PenMotionEvent , ::SDL_GetPenStatus) */
|
||||
#define SDL_PEN_AXIS_PRESSURE_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_PRESSURE) /**< Pen provides pressure information in axis ::SDL_PEN_AXIS_PRESSURE */
|
||||
#define SDL_PEN_AXIS_XTILT_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_XTILT) /**< Pen provides horizontal tilt information in axis ::SDL_PEN_AXIS_XTILT */
|
||||
#define SDL_PEN_AXIS_YTILT_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_YTILT) /**< Pen provides vertical tilt information in axis ::SDL_PEN_AXIS_YTILT */
|
||||
#define SDL_PEN_AXIS_DISTANCE_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_DISTANCE) /**< Pen provides distance to drawing tablet in ::SDL_PEN_AXIS_DISTANCE */
|
||||
#define SDL_PEN_AXIS_ROTATION_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_ROTATION) /**< Pen provides barrel rotation information in axis ::SDL_PEN_AXIS_ROTATION */
|
||||
#define SDL_PEN_AXIS_SLIDER_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_SLIDER) /**< Pen provides slider / finger wheel or similar in axis ::SDL_PEN_AXIS_SLIDER */
|
||||
#define SDL_PEN_INK_MASK SDL_PEN_CAPABILITY(SDL_PEN_FLAG_INK_BIT_INDEX) /**< Pen has a regular drawing tip (SDL_GetPenCapabilities). For events (SDL_PenButtonEvent, SDL_PenMotionEvent, SDL_GetPenStatus) this flag is mutually exclusive with SDL_PEN_ERASER_MASK . */
|
||||
#define SDL_PEN_ERASER_MASK SDL_PEN_CAPABILITY(SDL_PEN_FLAG_ERASER_BIT_INDEX) /**< Pen has an eraser tip (SDL_GetPenCapabilities) or is being used as eraser (SDL_PenButtonEvent , SDL_PenMotionEvent , SDL_GetPenStatus) */
|
||||
#define SDL_PEN_AXIS_PRESSURE_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_PRESSURE) /**< Pen provides pressure information in axis SDL_PEN_AXIS_PRESSURE */
|
||||
#define SDL_PEN_AXIS_XTILT_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_XTILT) /**< Pen provides horizontal tilt information in axis SDL_PEN_AXIS_XTILT */
|
||||
#define SDL_PEN_AXIS_YTILT_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_YTILT) /**< Pen provides vertical tilt information in axis SDL_PEN_AXIS_YTILT */
|
||||
#define SDL_PEN_AXIS_DISTANCE_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_DISTANCE) /**< Pen provides distance to drawing tablet in SDL_PEN_AXIS_DISTANCE */
|
||||
#define SDL_PEN_AXIS_ROTATION_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_ROTATION) /**< Pen provides barrel rotation information in axis SDL_PEN_AXIS_ROTATION */
|
||||
#define SDL_PEN_AXIS_SLIDER_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_SLIDER) /**< Pen provides slider / finger wheel or similar in axis SDL_PEN_AXIS_SLIDER */
|
||||
|
||||
#define SDL_PEN_AXIS_BIDIRECTIONAL_MASKS (SDL_PEN_AXIS_XTILT_MASK | SDL_PEN_AXIS_YTILT_MASK)
|
||||
/**< Masks for all axes that may be bidirectional */
|
||||
/** @} */
|
||||
|
||||
/**
|
||||
* Pen types
|
||||
*
|
||||
* Some pens identify as a particular type of drawing device (e.g., an airbrush or a pencil).
|
||||
*
|
||||
* \since This enum is available since SDL 3.0.0
|
||||
*/
|
||||
typedef enum
|
||||
typedef enum SDL_PenSubtype
|
||||
{
|
||||
SDL_PEN_TYPE_UNKNOWN = 0,
|
||||
SDL_PEN_TYPE_ERASER = 1, /**< Eraser */
|
||||
@@ -149,15 +143,15 @@ typedef enum
|
||||
/**
|
||||
* Retrieves all pens that are connected to the system.
|
||||
*
|
||||
* Yields an array of ::SDL_PenID values. These identify and track pens
|
||||
* Yields an array of SDL_PenID values. These identify and track pens
|
||||
* throughout a session. To track pens across sessions (program restart), use
|
||||
* ::SDL_GUID .
|
||||
* SDL_GUID .
|
||||
*
|
||||
* \param count The number of pens in the array (number of array elements
|
||||
* minus 1, i.e., not counting the terminator 0).
|
||||
* \returns A 0 terminated array of ::SDL_PenID values, or NULL on error. The
|
||||
* array must be freed with ::SDL_free(). On a NULL return,
|
||||
* ::SDL_GetError() is set.
|
||||
* \returns A 0 terminated array of SDL_PenID values, or NULL on error. The
|
||||
* array must be freed with SDL_free(). On a NULL return,
|
||||
* SDL_GetError() is set.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0
|
||||
*/
|
||||
@@ -166,29 +160,29 @@ extern DECLSPEC SDL_PenID *SDLCALL SDL_GetPens(int *count);
|
||||
/**
|
||||
* Retrieves the pen's current status.
|
||||
*
|
||||
* If the pen is detached (cf. ::SDL_PenConnected), this operation may return
|
||||
* If the pen is detached (cf. SDL_PenConnected), this operation may return
|
||||
* default values.
|
||||
*
|
||||
* \param instance_id The pen to query.
|
||||
* \param x Out-mode parameter for pen x coordinate. May be NULL.
|
||||
* \param y Out-mode parameter for pen y coordinate. May be NULL.
|
||||
* \param axes Out-mode parameter for axis information. May be null. The axes
|
||||
* are in the same order as ::SDL_PenAxis.
|
||||
* are in the same order as SDL_PenAxis.
|
||||
* \param num_axes Maximum number of axes to write to "axes".
|
||||
* \returns a bit mask with the current pen button states (::SDL_BUTTON_LMASK
|
||||
* etc.), possibly ::SDL_PEN_DOWN_MASK, and exactly one of
|
||||
* ::SDL_PEN_INK_MASK or ::SDL_PEN_ERASER_MASK , or 0 on error (see
|
||||
* ::SDL_GetError()).
|
||||
* \returns a bit mask with the current pen button states (SDL_BUTTON_LMASK
|
||||
* etc.), possibly SDL_PEN_DOWN_MASK, and exactly one of
|
||||
* SDL_PEN_INK_MASK or SDL_PEN_ERASER_MASK , or 0 on error (see
|
||||
* SDL_GetError()).
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0
|
||||
*/
|
||||
extern DECLSPEC Uint32 SDLCALL SDL_GetPenStatus(SDL_PenID instance_id, float *x, float *y, float *axes, size_t num_axes);
|
||||
|
||||
/**
|
||||
* Retrieves an ::SDL_PenID for the given ::SDL_GUID.
|
||||
* Retrieves an SDL_PenID for the given SDL_GUID.
|
||||
*
|
||||
* \param guid A pen GUID.
|
||||
* \returns A valid ::SDL_PenID, or ::SDL_PEN_INVALID if there is no matching
|
||||
* \returns A valid SDL_PenID, or SDL_PEN_INVALID if there is no matching
|
||||
* SDL_PenID.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0
|
||||
@@ -196,11 +190,11 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetPenStatus(SDL_PenID instance_id, float *x,
|
||||
extern DECLSPEC SDL_PenID SDLCALL SDL_GetPenFromGUID(SDL_GUID guid);
|
||||
|
||||
/**
|
||||
* Retrieves the ::SDL_GUID for a given ::SDL_PenID.
|
||||
* Retrieves the SDL_GUID for a given SDL_PenID.
|
||||
*
|
||||
* \param instance_id The pen to query.
|
||||
* \returns The corresponding pen GUID; persistent across multiple sessions.
|
||||
* If "instance_id" is ::SDL_PEN_INVALID, returns an all-zeroes GUID.
|
||||
* If "instance_id" is SDL_PEN_INVALID, returns an all-zeroes GUID.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0
|
||||
*/
|
||||
@@ -209,7 +203,7 @@ extern DECLSPEC SDL_GUID SDLCALL SDL_GetPenGUID(SDL_PenID instance_id);
|
||||
/**
|
||||
* Checks whether a pen is still attached.
|
||||
*
|
||||
* If a pen is detached, it will not show up for ::SDL_GetPens(). Other
|
||||
* If a pen is detached, it will not show up for SDL_GetPens(). Other
|
||||
* operations will still be available but may return default values.
|
||||
*
|
||||
* \param instance_id A pen ID.
|
||||
@@ -221,23 +215,23 @@ extern DECLSPEC SDL_GUID SDLCALL SDL_GetPenGUID(SDL_PenID instance_id);
|
||||
extern DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id);
|
||||
|
||||
/**
|
||||
* Retrieves a human-readable description for a ::SDL_PenID.
|
||||
* Retrieves a human-readable description for a SDL_PenID.
|
||||
*
|
||||
* \param instance_id The pen to query.
|
||||
* \returns A string that contains the name of the pen, intended for human
|
||||
* consumption. The string might or might not be localised, depending
|
||||
* on platform settings. It is not guaranteed to be unique; use
|
||||
* ::SDL_GetPenGUID() for (best-effort) unique identifiers. The
|
||||
* SDL_GetPenGUID() for (best-effort) unique identifiers. The
|
||||
* pointer is managed by the SDL pen subsystem and must not be
|
||||
* deallocated. The pointer remains valid until SDL is shut down.
|
||||
* Returns NULL on error (cf. ::SDL_GetError())
|
||||
* Returns NULL on error (cf. SDL_GetError())
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0
|
||||
*/
|
||||
extern DECLSPEC const char *SDLCALL SDL_GetPenName(SDL_PenID instance_id);
|
||||
|
||||
/**
|
||||
* Pen capabilities, as reported by ::SDL_GetPenCapabilities()
|
||||
* Pen capabilities, as reported by SDL_GetPenCapabilities()
|
||||
*/
|
||||
typedef struct SDL_PenCapabilityInfo
|
||||
{
|
||||
@@ -247,7 +241,7 @@ typedef struct SDL_PenCapabilityInfo
|
||||
} SDL_PenCapabilityInfo;
|
||||
|
||||
/**
|
||||
* Retrieves capability flags for a given ::SDL_PenID.
|
||||
* Retrieves capability flags for a given SDL_PenID.
|
||||
*
|
||||
* \param instance_id The pen to query.
|
||||
* \param capabilities Detail information about pen capabilities, such as the
|
||||
@@ -259,14 +253,14 @@ typedef struct SDL_PenCapabilityInfo
|
||||
extern DECLSPEC Uint32 SDLCALL SDL_GetPenCapabilities(SDL_PenID instance_id, SDL_PenCapabilityInfo *capabilities);
|
||||
|
||||
/**
|
||||
* Retrieves the pen type for a given ::SDL_PenID.
|
||||
* Retrieves the pen type for a given SDL_PenID.
|
||||
*
|
||||
* \param instance_id The pen to query.
|
||||
* \returns The corresponding pen type (cf. ::SDL_PenSubtype) or 0 on error.
|
||||
* \returns The corresponding pen type (cf. SDL_PenSubtype) or 0 on error.
|
||||
* Note that the pen type does not dictate whether the pen tip is
|
||||
* ::SDL_PEN_TIP_INK or ::SDL_PEN_TIP_ERASER; to determine whether a
|
||||
* SDL_PEN_TIP_INK or SDL_PEN_TIP_ERASER; to determine whether a
|
||||
* pen is being used for drawing or in eraser mode, check either the
|
||||
* pen tip on ::SDL_EVENT_PEN_DOWN, or the flag ::SDL_PEN_ERASER_MASK
|
||||
* pen tip on SDL_EVENT_PEN_DOWN, or the flag SDL_PEN_ERASER_MASK
|
||||
* in the pen state.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0
|
||||
|
||||
Reference in New Issue
Block a user