gitea/SDL3_fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Sync wiki -> headers.

Browse Source
This commit is contained in:
Ryan C. Gordon
2023-11-13 13:03:42 -05:00
parent e5ffd6d8eb
commit 8766aa39d6
4 changed files with 78 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
include/SDL3/SDL_pen.h
View File

@@ -147,15 +147,13 @@ typedef enum
/**
* Retrieves all pens that are connected to the system.
*
* 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 .
* 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 .
*
* \param[out] 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.TBD
*/
@@ -168,15 +166,11 @@ extern DECLSPEC SDL_PenID *SDLCALL SDL_GetPens(int *count);
* default values.
*
* \param instance_id The pen to query.
* \param[out] x Out-mode parameter for pen x coordinate. May be NULL.
* \param[out] y Out-mode parameter for pen y coordinate. May be NULL.
* \param[out] axes Out-mode parameter for axis information. May be null. The axes are in the same order as for
* ::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.TBD
*/
@@ -186,12 +180,12 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetPenStatus(SDL_PenID instance_id, float *x,
* 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 SDL_PenID.
* \returns A valid ::SDL_PenID, or ::SDL_PEN_INVALID if there is no matching
* SDL_PenID.
*
* \since This function is available since SDL 3.TBD
*
* \sa SDL_GUID()
* \sa SDL_GUID
*/
extern DECLSPEC SDL_PenID SDLCALL SDL_GetPenFromGUID(SDL_GUID guid);
@@ -199,25 +193,24 @@ extern DECLSPEC SDL_PenID SDLCALL SDL_GetPenFromGUID(SDL_GUID guid);
* 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.TBD
*
* \sa SDL_PenForID()
* \sa SDL_PenForID
*/
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 operations will still be available but may return default values.
* 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.
* \returns SDL_TRUE if "instance_id" is valid and the corresponding pen is attached, or
* SDL_FALSE otherwise.
* \returns SDL_TRUE if "instance_id" is valid and the corresponding pen is
* attached, or SDL_FALSE otherwise.
*
* \since This function is available since SDL 3.TBD
*/
@@ -227,14 +220,13 @@ extern DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id);
* 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 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 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
* 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())
*
* \since This function is available since SDL 3.TBD
*/
@@ -254,10 +246,7 @@ typedef struct SDL_PenCapabilityInfo
* Retrieves capability flags for a given ::SDL_PenID.
*
* \param instance_id The pen to query.
* \param[out] capabilities Detail information about pen capabilities, such as the number of buttons
*
* \returns a set of capability flags, cf. SDL_PEN_CAPABILITIES. Returns 0 on error
* (cf. ::SDL_GetError())
* \returns a set of capability flags, cf. \link SDL_PEN_CAPABILITIES
*
* \since This function is available since SDL 3.TBD
*/
@@ -267,10 +256,13 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetPenCapabilities(SDL_PenID instance_id, SDL
* 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. 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 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 in the pen state.
* \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
* 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
* in the pen state.
*
* \since This function is available since SDL 3.TBD
*/
extern DECLSPEC SDL_PenSubtype SDLCALL SDL_GetPenType(SDL_PenID instance_id);