SDL 3.0
SDL_pen.h File Reference
#include "SDL_error.h"
#include "SDL_guid.h"
#include "SDL_stdinc.h"
+ Include dependency graph for SDL_pen.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  SDL_PenCapabilityInfo
 

Macros

#define SDL_PEN_INVALID   ((Uint32)0)
 
#define SDL_PEN_MOUSEID   ((Uint32)-2)
 
#define SDL_PEN_INFO_UNKNOWN   (-1)
 
#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 */
 
#define SDL_PEN_FLAG_AXIS_BIT_OFFSET   16 /* Bit for storing has-axis-0 property */
 
#define SDL_PEN_CAPABILITY(capbit)   (1ul << (capbit))
 
#define SDL_PEN_AXIS_CAPABILITY(axis)   SDL_PEN_CAPABILITY((axis) + SDL_PEN_FLAG_AXIS_BIT_OFFSET)
 
#define SDL_PEN_DOWN_MASK   SDL_PEN_CAPABILITY(SDL_PEN_FLAG_DOWN_BIT_INDEX)
 
#define SDL_PEN_INK_MASK   SDL_PEN_CAPABILITY(SDL_PEN_FLAG_INK_BIT_INDEX)
 
#define SDL_PEN_ERASER_MASK   SDL_PEN_CAPABILITY(SDL_PEN_FLAG_ERASER_BIT_INDEX)
 
#define SDL_PEN_AXIS_PRESSURE_MASK   SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_PRESSURE)
 
#define SDL_PEN_AXIS_XTILT_MASK   SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_XTILT)
 
#define SDL_PEN_AXIS_YTILT_MASK   SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_YTILT)
 
#define SDL_PEN_AXIS_DISTANCE_MASK   SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_DISTANCE)
 
#define SDL_PEN_AXIS_ROTATION_MASK   SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_ROTATION)
 
#define SDL_PEN_AXIS_SLIDER_MASK   SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_SLIDER)
 
#define SDL_PEN_AXIS_BIDIRECTIONAL_MASKS   (SDL_PEN_AXIS_XTILT_MASK | SDL_PEN_AXIS_YTILT_MASK)
 
#define SDL_PEN_TIP_INK   SDL_PEN_FLAG_INK_BIT_INDEX
 
#define SDL_PEN_TIP_ERASER   SDL_PEN_FLAG_ERASER_BIT_INDEX
 

Typedefs

typedef Uint32 SDL_PenID
 

Enumerations

enum  SDL_PenAxis {
  SDL_PEN_AXIS_PRESSURE = 0 ,
  SDL_PEN_AXIS_XTILT ,
  SDL_PEN_AXIS_YTILT ,
  SDL_PEN_AXIS_DISTANCE ,
  SDL_PEN_AXIS_ROTATION ,
  SDL_PEN_AXIS_SLIDER ,
  SDL_PEN_NUM_AXES ,
  SDL_PEN_AXIS_LAST = SDL_PEN_NUM_AXES - 1
}
 
enum  SDL_PenSubtype {
  SDL_PEN_TYPE_ERASER = 1 ,
  SDL_PEN_TYPE_PEN ,
  SDL_PEN_TYPE_PENCIL ,
  SDL_PEN_TYPE_BRUSH ,
  SDL_PEN_TYPE_AIRBRUSH ,
  SDL_PEN_TYPE_LAST = SDL_PEN_TYPE_AIRBRUSH
}
 

Functions

SDL_PenIDSDL_GetPens (int *count)
 
Uint32 SDL_GetPenStatus (SDL_PenID instance_id, float *x, float *y, float *axes, size_t num_axes)
 
SDL_PenID SDL_GetPenFromGUID (SDL_GUID guid)
 
SDL_GUID SDL_GetPenGUID (SDL_PenID instance_id)
 
SDL_bool SDL_PenConnected (SDL_PenID instance_id)
 
const char * SDL_GetPenName (SDL_PenID instance_id)
 
Uint32 SDL_GetPenCapabilities (SDL_PenID instance_id, SDL_PenCapabilityInfo *capabilities)
 
SDL_PenSubtype SDL_GetPenType (SDL_PenID instance_id)
 

Detailed Description

Include file for SDL pen event handling.

This file describes operations for pressure-sensitive pen (stylus and/or eraser) handling, e.g., for input and drawing tablets or suitably equipped mobile / tablet devices.

To get started with pens:

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 even if a device disappears.

For identifying pens across sessions, the API provides the type SDL_GUID .

Definition in file SDL_pen.h.

Macro Definition Documentation

◆ SDL_PEN_AXIS_CAPABILITY

#define SDL_PEN_AXIS_CAPABILITY (   axis)    SDL_PEN_CAPABILITY((axis) + SDL_PEN_FLAG_AXIS_BIT_OFFSET)

Definition at line 98 of file SDL_pen.h.

◆ SDL_PEN_CAPABILITY

#define SDL_PEN_CAPABILITY (   capbit)    (1ul << (capbit))

Definition at line 97 of file SDL_pen.h.

◆ SDL_PEN_FLAG_AXIS_BIT_OFFSET

#define SDL_PEN_FLAG_AXIS_BIT_OFFSET   16 /* Bit for storing has-axis-0 property */

Definition at line 95 of file SDL_pen.h.

◆ SDL_PEN_FLAG_DOWN_BIT_INDEX

#define SDL_PEN_FLAG_DOWN_BIT_INDEX   13 /* Bit for storing that pen is touching the surface */

Definition at line 92 of file SDL_pen.h.

◆ SDL_PEN_FLAG_ERASER_BIT_INDEX

#define SDL_PEN_FLAG_ERASER_BIT_INDEX   15 /* Bit for storing is-eraser or has-eraser-capability property */

Definition at line 94 of file SDL_pen.h.

◆ SDL_PEN_FLAG_INK_BIT_INDEX

#define SDL_PEN_FLAG_INK_BIT_INDEX   14 /* Bit for storing has-non-eraser-capability status */

Definition at line 93 of file SDL_pen.h.

◆ SDL_PEN_INFO_UNKNOWN

#define SDL_PEN_INFO_UNKNOWN   (-1)

Marks unknown information when querying the pen

Definition at line 63 of file SDL_pen.h.

◆ SDL_PEN_INVALID

#define SDL_PEN_INVALID   ((Uint32)0)

Reserved invalid SDL_PenID is valid

Definition at line 59 of file SDL_pen.h.

◆ SDL_PEN_MOUSEID

#define SDL_PEN_MOUSEID   ((Uint32)-2)

Device ID for mouse events triggered by pen events

Definition at line 61 of file SDL_pen.h.

◆ SDL_PEN_TIP_ERASER

#define SDL_PEN_TIP_ERASER   SDL_PEN_FLAG_ERASER_BIT_INDEX

Eraser pen tip touched the surface

Definition at line 105 of file SDL_pen.h.

◆ SDL_PEN_TIP_INK

#define SDL_PEN_TIP_INK   SDL_PEN_FLAG_INK_BIT_INDEX

Pen tips Regular pen tip (for drawing) touched the surface

Definition at line 104 of file SDL_pen.h.

Typedef Documentation

◆ SDL_PenID

typedef Uint32 SDL_PenID

SDL_PenIDs identify pens uniquely within a session

Definition at line 57 of file SDL_pen.h.

Enumeration Type Documentation

◆ SDL_PenAxis

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. 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)".

Enumerator
SDL_PEN_AXIS_PRESSURE 

Pen pressure. Unidirectional: 0..1.0

SDL_PEN_AXIS_XTILT 

Pen horizontal tilt angle. Bidirectional: -90.0..90.0 (left-to-right). The physical max/min tilt may be smaller than -90.0 / 90.0, cf. SDL_PenCapabilityInfo

SDL_PEN_AXIS_YTILT 

Pen vertical tilt angle. Bidirectional: -90.0..90.0 (top-to-down). The physical max/min tilt may be smaller than -90.0 / 90.0, cf. SDL_PenCapabilityInfo

SDL_PEN_AXIS_DISTANCE 

Pen distance to drawing surface. Unidirectional: 0.0..1.0

SDL_PEN_AXIS_ROTATION 

Pen barrel rotation. Bidirectional: -180..179.9 (clockwise, 0 is facing up, -180.0 is facing down).

SDL_PEN_AXIS_SLIDER 

Pen finger wheel or slider (e.g., Airbrush Pen). Unidirectional: 0..1.0

SDL_PEN_NUM_AXES 

Last valid axis index

SDL_PEN_AXIS_LAST 

Last axis index plus 1

Definition at line 77 of file SDL_pen.h.

78{
79 SDL_PEN_AXIS_PRESSURE = 0, /**< Pen pressure. Unidirectional: 0..1.0 */
80 SDL_PEN_AXIS_XTILT, /**< Pen horizontal tilt angle. Bidirectional: -90.0..90.0 (left-to-right).
81 The physical max/min tilt may be smaller than -90.0 / 90.0, cf. SDL_PenCapabilityInfo */
82 SDL_PEN_AXIS_YTILT, /**< Pen vertical tilt angle. Bidirectional: -90.0..90.0 (top-to-down).
83 The physical max/min tilt may be smaller than -90.0 / 90.0, cf. SDL_PenCapabilityInfo */
84 SDL_PEN_AXIS_DISTANCE, /**< Pen distance to drawing surface. Unidirectional: 0.0..1.0 */
85 SDL_PEN_AXIS_ROTATION, /**< Pen barrel rotation. Bidirectional: -180..179.9 (clockwise, 0 is facing up, -180.0 is facing down). */
86 SDL_PEN_AXIS_SLIDER, /**< Pen finger wheel or slider (e.g., Airbrush Pen). Unidirectional: 0..1.0 */
87 SDL_PEN_NUM_AXES, /**< Last valid axis index */
88 SDL_PEN_AXIS_LAST = SDL_PEN_NUM_AXES - 1 /**< Last axis index plus 1 */
SDL_PenAxis
Definition SDL_pen.h:78
@ SDL_PEN_AXIS_PRESSURE
Definition SDL_pen.h:79
@ SDL_PEN_AXIS_XTILT
Definition SDL_pen.h:80
@ SDL_PEN_AXIS_SLIDER
Definition SDL_pen.h:86
@ SDL_PEN_AXIS_DISTANCE
Definition SDL_pen.h:84
@ SDL_PEN_NUM_AXES
Definition SDL_pen.h:87
@ SDL_PEN_AXIS_YTILT
Definition SDL_pen.h:82
@ SDL_PEN_AXIS_LAST
Definition SDL_pen.h:88
@ SDL_PEN_AXIS_ROTATION
Definition SDL_pen.h:85

◆ SDL_PenSubtype

Pen types

Some pens identify as a particular type of drawing device (e.g., an airbrush or a pencil).

Enumerator
SDL_PEN_TYPE_ERASER 

Eraser

SDL_PEN_TYPE_PEN 

Generic pen; this is the default.

SDL_PEN_TYPE_PENCIL 

Pencil

SDL_PEN_TYPE_BRUSH 

Brush-like device

SDL_PEN_TYPE_AIRBRUSH 

Airbrush device that "sprays" ink

SDL_PEN_TYPE_LAST 

Last valid pen type

Definition at line 134 of file SDL_pen.h.

135{
136 SDL_PEN_TYPE_ERASER = 1, /**< Eraser */
137 SDL_PEN_TYPE_PEN, /**< Generic pen; this is the default. */
138 SDL_PEN_TYPE_PENCIL, /**< Pencil */
139 SDL_PEN_TYPE_BRUSH, /**< Brush-like device */
140 SDL_PEN_TYPE_AIRBRUSH, /**< Airbrush device that "sprays" ink */
141 SDL_PEN_TYPE_LAST = SDL_PEN_TYPE_AIRBRUSH /**< Last valid pen type */
SDL_PenSubtype
Definition SDL_pen.h:135
@ SDL_PEN_TYPE_BRUSH
Definition SDL_pen.h:139
@ SDL_PEN_TYPE_LAST
Definition SDL_pen.h:141
@ SDL_PEN_TYPE_PEN
Definition SDL_pen.h:137
@ SDL_PEN_TYPE_ERASER
Definition SDL_pen.h:136
@ SDL_PEN_TYPE_PENCIL
Definition SDL_pen.h:138
@ SDL_PEN_TYPE_AIRBRUSH
Definition SDL_pen.h:140

Function Documentation

◆ SDL_GetPenCapabilities()

Uint32 SDL_GetPenCapabilities ( SDL_PenID  instance_id,
SDL_PenCapabilityInfo capabilities 
)
extern

Retrieves capability flags for a given SDL_PenID.

Parameters
instance_idThe pen to query.
capabilitiesDetail information about pen capabilities, such as the number of buttons
Returns
a set of capability flags, cf. SDL_PEN_CAPABILITIES
Since
This function is available since SDL 3.0.0

◆ SDL_GetPenFromGUID()

SDL_PenID SDL_GetPenFromGUID ( SDL_GUID  guid)
extern

Retrieves an SDL_PenID for the given SDL_GUID.

Parameters
guidA pen GUID.
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
See also
SDL_GUID

◆ SDL_GetPenGUID()

SDL_GUID SDL_GetPenGUID ( SDL_PenID  instance_id)
extern

Retrieves the SDL_GUID for a given SDL_PenID.

Parameters
instance_idThe pen to query.
Returns
The corresponding pen GUID; persistent across multiple sessions. If "instance_id" is SDL_PEN_INVALID, returns an all-zeroes GUID.
Since
This function is available since SDL 3.0.0
See also
SDL_PenForID

◆ SDL_GetPenName()

const char * SDL_GetPenName ( SDL_PenID  instance_id)
extern

Retrieves a human-readable description for a SDL_PenID.

Parameters
instance_idThe 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())
Since
This function is available since SDL 3.0.0

◆ SDL_GetPens()

SDL_PenID * SDL_GetPens ( int *  count)
extern

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 .

Parameters
countThe 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.
Since
This function is available since SDL 3.0.0

◆ SDL_GetPenStatus()

Uint32 SDL_GetPenStatus ( SDL_PenID  instance_id,
float *  x,
float *  y,
float *  axes,
size_t  num_axes 
)
extern

Retrieves the pen's current status.

If the pen is detached (cf. SDL_PenConnected), this operation may return default values.

Parameters
instance_idThe pen to query.
xOut-mode parameter for pen x coordinate. May be NULL.
yOut-mode parameter for pen y coordinate. May be NULL.
axesOut-mode parameter for axis information. May be null. The axes are in the same order as SDL_PenAxis.
num_axesMaximum 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()).
Since
This function is available since SDL 3.0.0

◆ SDL_GetPenType()

SDL_PenSubtype SDL_GetPenType ( SDL_PenID  instance_id)
extern

Retrieves the pen type for a given SDL_PenID.

Parameters
instance_idThe 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.
Since
This function is available since SDL 3.0.0

◆ SDL_PenConnected()

SDL_bool SDL_PenConnected ( SDL_PenID  instance_id)
extern

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.

Parameters
instance_idA pen ID.
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.0.0