From 55167402f41d6125806cbfa3f7fb034d01ccc94c Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" Date: Tue, 14 Oct 2025 14:07:08 -0400 Subject: [PATCH] pen: Improved docs for SDL_PenDeviceType. --- include/SDL3/SDL_pen.h | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/include/SDL3/SDL_pen.h b/include/SDL3/SDL_pen.h index 1ddb4b569d..2752e58624 100644 --- a/include/SDL3/SDL_pen.h +++ b/include/SDL3/SDL_pen.h @@ -130,18 +130,31 @@ typedef enum SDL_PenAxis /** * An enum that describes the type of a pen device. * + * A "direct" device is a pen that touches a graphic display (like an + * Apple Pencil on an iPad's screen). "Indirect" devices touch an external + * tablet surface that is connected to the machine but is not a display (like + * a lower-end Wacom tablet connected over USB). + * + * Apps may use this information to decide if they should draw a cursor; if + * the pen is touching the screen directly, a cursor doesn't make sense and + * can be in the way, but becomes necessary for indirect devices to know where + * on the display they are interacting. + * * \since This enum is available since SDL 3.4.0. */ typedef enum SDL_PenDeviceType { - SDL_PEN_DEVICE_TYPE_INVALID = -1, - SDL_PEN_DEVICE_TYPE_UNKNOWN, - SDL_PEN_DEVICE_TYPE_DIRECT, - SDL_PEN_DEVICE_TYPE_INDIRECT + SDL_PEN_DEVICE_TYPE_INVALID = -1, /**< Not a valid pen device. */ + SDL_PEN_DEVICE_TYPE_UNKNOWN, /**< Don't know specifics of this pen. */ + SDL_PEN_DEVICE_TYPE_DIRECT, /**< Pen touches display. */ + SDL_PEN_DEVICE_TYPE_INDIRECT /**< Pen touches something that isn't the display. */ } SDL_PenDeviceType; /** * Get the device type of the given pen. + + * Many platforms do not supply this information, so an app must always be + * prepared to get an SDL_PEN_DEVICE_TYPE_UNKNOWN result. * * \param instance_id the pen instance ID. * \returns the device type of the given pen, or SDL_PEN_DEVICE_TYPE_INVALID