This patch adds an API for querying pressure-
sensitive pens, cf. SDL_pen.h:
- Enumerate all pens
- Get pen capabilities, names, GUIDs
- Distinguishes pens and erasers
- Distinguish attached and detached pens
- Pressure and tilt support
- Rotation, distance, throttle wheel support
(throttle wheel untested)
- Pen type and meta-information reporting
(partially tested)
Pen event reporting:
- Three new event structures: PenTip, PenMotion, and
PenButton
- Report location with sub-pixel precision
- Include axis and button status, is-eraser flag
Internal pen tracker, intended to be independent
of platform APIs, cf. SDL_pen_c.h:
- Track known pens
- Handle pen hotplugging
Automatic test:
- testautomation_pen.c
Other features:
- XInput2 implementation, incl. hotplugging
- Wayland implementation, incl. hotplugging
- Backward compatibility: pen events default to
emulating pens with mouse ID SDL_PEN_MOUSEID
- Can be toggled via SDL_HINT_PEN_NOT_MOUSE
- Test/demo program (testpen)
- Wacom pen feature identification by pen ID
Acknowledgements:
- Ping Cheng (Wacom) provided extensive feedback
on Wacom pen features and detection so that
hopefully untested Wacom devices have a
realistic chance of working out of the box.
This gives applications and binding systems a clearer view of what the hardware is so they can make intelligent decisions about how to present things to the user.
Gamepad mappings continue to use abxy for the face buttons for simplicity and compatibility with earlier versions of SDL, however the "SDL_GAMECONTROLLER_USE_BUTTON_LABELS" hint no longer has any effect.
Fixes https://github.com/libsdl-org/SDL/issues/6117
If the done signal is emitted by the common event handler, the window and all of its children have already been destroyed, so don't try to render with invalid renderer objects.
This lets apps optionally have a handful of callbacks for their entry points instead of a single main function. If used, the actual main/SDL_main/whatever entry point will be implemented in the single-header library SDL_main.h and the app will implement four separate functions:
First:
int SDL_AppInit(int argc, char **argv);
This will be called once before anything else. argc/argv work like they always do. If this returns 0, the app runs. If it returns < 0, the app calls SDL_AppQuit and terminates with an exit code that reports an error to the platform. If it returns > 0, the app calls SDL_AppQuit and terminates with an exit code that reports success to the platform. This function should not go into an infinite mainloop; it should do any one-time startup it requires and then return.
Then:
int SDL_AppIterate(void);
This is called over and over, possibly at the refresh rate of the display or some other metric that the platform dictates. This is where the heart of your app runs. It should return as quickly as reasonably possible, but it's not a "run one memcpy and that's all the time you have" sort of thing. The app should do any game updates, and render a frame of video. If it returns < 0, SDL will call SDL_AppQuit and terminate the process with an exit code that reports an error to the platform. If it returns > 0, the app calls SDL_AppQuit and terminates with an exit code that reports success to the platform. If it returns 0, then SDL_AppIterate will be called again at some regular frequency. The platform may choose to run this more or less (perhaps less in the background, etc), or it might just call this function in a loop as fast as possible. You do not check the event queue in this function (SDL_AppEvent exists for that).
Next:
int SDL_AppEvent(const SDL_Event *event);
This will be called once for each event pushed into the SDL queue. This may be called from any thread, and possibly in parallel to SDL_AppIterate. The fields in event do not need to be free'd (as you would normally need to do for SDL_EVENT_DROP_FILE, etc), and your app should not call SDL_PollEvent, SDL_PumpEvent, etc, as SDL will manage this for you. Return values are the same as from SDL_AppIterate(), so you can terminate in response to SDL_EVENT_QUIT, etc.
Finally:
void SDL_AppQuit(void);
This is called once before terminating the app--assuming the app isn't being forcibly killed or crashed--as a last chance to clean up. After this returns, SDL will call SDL_Quit so the app doesn't have to (but it's safe for the app to call it, too). Process termination proceeds as if the app returned normally from main(), so atexit handles will run, if your platform supports that.
The app does not implement SDL_main if using this. To turn this on, define SDL_MAIN_USE_CALLBACKS before including SDL_main.h. Defines like SDL_MAIN_HANDLED and SDL_MAIN_NOIMPL are also respected for callbacks, if the app wants to do some sort of magic main implementation thing.
In theory, on most platforms these can be implemented in the app itself, but this saves some #ifdefs in the app and lets everyone struggle less against some platforms, and might be more efficient in the long run, too.
On some platforms, it's possible this is the only reasonable way to go, but we haven't actually hit one that 100% requires it yet (but we will, if we want to write a RetroArch backend, for example).
Using the callback entry points works on every platform, because on platforms that don't require them, we can fake them with a simple loop in an internal implementation of the usual SDL_main.
The primary way we expect people to write SDL apps is with SDL_main, and this is not intended to replace it. If the app chooses to use this, it just removes some platform-specific details they might have to otherwise manage, and maybe removes a barrier to entry on some future platform.
Fixes#6785.
Reference PR #8247.
Almost nothing checks these return values, and there's no reason a valid
lock should fail to operate. The cases where a lock isn't valid (it's a
bogus pointer, it was previously destroyed, a thread is unlocking a lock it
doesn't own, etc) are undefined behavior and always were, and should be
treated as an application bug.
Reference Issue #8096.
The following objects now have properties that can be user modified:
* SDL_AudioStream
* SDL_Gamepad
* SDL_Joystick
* SDL_RWops
* SDL_Renderer
* SDL_Sensor
* SDL_Surface
* SDL_Texture
* SDL_Window
Also switched the D3D11 and D3D12 renderers to use real NV12 textures for NV12 data.
The combination of these two changes allows us to implement 0-copy video decode and playback for D3D11 in testffmpeg without any access to the renderer internals.
This avoids assuming that the pixels are suitably aligned for direct
access, which there's no guarantee that they are; in particular,
3-bytes-per-pixel RGB images are likely to have 3 out of 4 pixels
misaligned. On x86, dereferencing a misaligned pointer does what you
would expect, but on other architectures it's undefined whether it will
work, crash with SIGBUS, or silently give a wrong answer.
Signed-off-by: Simon McVittie <smcv@collabora.com>
We can't rely on irrational numbers like pi being represented exactly,
particularly when compiling for i386, where the i387 floating-point
interface carries out calculations in registers that have higher
precision than the actual double-precision variable. The 1980s were a
strange time.
Resolves: https://github.com/libsdl-org/SDL/issues/8311
Signed-off-by: Simon McVittie <smcv@collabora.com>
Now it offers the total requested bytes in addition to the amount
immediately needed (and immediately needed might be zero if the stream
already has enough queued to satisfy the request.
You can see it in action in testaudio by mousing over a logical device; it
will show a visualizer for the current PCM (whatever is currently being
recorded on a capture device, or whatever is being mixed for output on
playback devices).
Fixes#8122.
This is meant to offer a simplified API for people that are either migrating
directly from SDL2 with minimal effort or just want to make noise without
any of the fancy new API features.
Users of this API can just deal with a single SDL_AudioStream as their only
object/handle into the audio subsystem.
They are still allowed to open multiple devices (or open the same device
multiple times), but cannot change stream bindings on logical devices opened
through this function.
Destroying the single audio stream will also close the logical device behind
the scenes.
The sequence order of the four paddles is not obvious, with SDL and Xbox
controllers swapping the order of P2 and P3 relative to each other.
If we group them into left and right, then it becomes more obvious.
Signed-off-by: Simon McVittie <smcv@collabora.com>
According to #8088 it has no value as an automated test, and by
default it takes long enough to hit the default test timeout.
Resolves: #8088
Signed-off-by: Simon McVittie <smcv@collabora.com>
The current status is stored in the SDL_rwops 'status' field to be able to determine whether a 0 return value is caused by end of file, an error, or a non-blocking source not being ready.
The functions to read sized datatypes now return SDL_bool so you can detect read errors.
Fixes https://github.com/libsdl-org/SDL/issues/6729
Zombie devices just sit there doing nothing until a new default device
is chosen, and then they migrate all their logical devices before being
destroyed.
This lets the system deal with the likely outcome of a USB headset being
the default audio device, and when its cable is yanked out, the backend
will likely announce this _before_ it chooses a new default (or, perhaps,
the only device in the system got yanked out and there _isn't_ a new
default to be had until the user plugs the cable back in).
This lets the audio device hold on without disturbing the app until it can
seamlessly migrate audio, and it also means the backend does not have to
be careful in how it announces device events, since SDL will manage the
time between a device loss and its replacement.
Note that this _only_ applies to things opened as the default device
(SDL_AUDIO_DEVICE_DEFAULT_OUTPUT, etc). If those USB headphones are the
default, and one SDL_OpenAudioDevice() call asked for them specifically and
the other just said "give me the system default," the explicitly requested
open will get a device-lost notification immediately. The other open will
live on as a zombie until it can migrate to the new default.
This drops the complexity of the PulseAudio hotplug thread dramatically,
back to what it was previously, since it no longer needs to fight against
Pulse's asychronous nature, but just report device disconnects and new
default choices as they arrive.
loopwave has been updated to not check for device removals anymore; since
it opens the default device, this is now managed for it; it no longer
needs to close and reopen a device, and as far as it knows, the device
is never lost in the first place.
When using the Wayland video driver or X11 under XWayland, create a renderer and present a frame as part of window creation, as Wayland requires that a frame be presented for the window to be fully mapped and displayed onscreen. This fixes the grab and expected window size tests.
This also disables the window positioning tests when running under the Wayland driver, as Wayland does not allow application windows to position themselves in the desktop space, which renders the tests unreliable and subject to spurious failure.
main features:
- No more sdl-build-options/sdl-shared-build-options/sdl-global-options
- Dependency information is stored on SDL3-collector for sdl3.pc
- Use helper functions to modify the SDL targets;
- sdl_sources to add sources
- sdl_glob_sources to add glob soruces
- sdl_link_dependency to add a link dependency that might also
appear in sdl3.pc/SDL3Config.cmake
- sdl_compile_definitions to add macro's
- sdl_compile_options for compile options
- sdl_include_directories for include directories
They avoid repeated checks for existence of the SDL targets
- A nice feature of the previous is the ability to generate
a sdl3.pc or SDL3Config.cmake that describes its dependencies
accurately.
various:
- remove duplicate libc symbol list
- add CheckVulkan
- remove unused HAVE_MPROTECT
- add checks for getpagesize
Add the flag "--suspend-when-occluded" to testgl, testgles2, and testsprite, which, when used, will suspend rendering and throttle the event loop when the occlusion flag is set on the window.
The gamepad vs joystick events always happen in this order:
SDL_EVENT_JOYSTICK_ADDED
SDL_EVENT_GAMEPAD_ADDED
SDL_EVENT_GAMEPAD_REMAPPED
SDL_EVENT_GAMEPAD_REMOVED
SDL_EVENT_JOYSTICK_REMOVED
Whenever a mapping is changed, any controller affected by that mapping will generate a gamepad event. You will only get one SDL_EVENT_GAMEPAD_REMAPPED event per controller per batch of mapping changes, where SDL_AddGamepadMappingsFromFile() and SDL_AddGamepadMapping() are each a batch of changes.
Also renamed most cases of SDL_GAMEPAD_TYPE_UNKNOWN to SDL_GAMEPAD_TYPE_STANDARD, and SDL_GetGamepadType() will return SDL_GAMEPAD_TYPE_UNKNOWN only if the gamepad is invalid.
Removing SDL_GAMEPAD_TYPE_VIRTUAL allows a virtual controller to emulate another gamepad type. The other controller types can be treated as generic controllers by applications without special glyph or functionality treatment.
If a device is positively identified as an accelerometer, pointing stick
or clickpad, then we don't need to second-guess it.
In practice this does not change the result for any device in our
test data, so add some artificial records that exercise this.
Signed-off-by: Simon McVittie <smcv@collabora.com>
In newer kernels, devices that can be positively identified as a
particular device type (for example accelerometers) get a property
bit set. Plumb this information through into the function, but don't
use it for anything just yet.
Signed-off-by: Simon McVittie <smcv@collabora.com>
The props array was too small for the highest property bits to be set,
although in practice this didn't matter since only the lower-order bits
have a meaning. Make it consistent with all the others.
Signed-off-by: Simon McVittie <smcv@collabora.com>
udev distinguishes between ID_INPUT_KEY, a device with any keyboard keys
at all (including for example USB numeric keypads, Bluetooth headsets
with volume control buttons, and some game controllers; and
ID_INPUT_KEYBOARD, a reasonably fully-featured keyboard that you could
use for general-purpose text entry. If we do the same here, then it's
useful input to our heuristics for identifying devices: for example,
a device with ID_INPUT_KEY could reasonably be a gamepad, but a device
with ID_INPUT_KEYBOARD certainly isn't.
Resolves: https://github.com/libsdl-org/SDL/issues/7827
Signed-off-by: Simon McVittie <smcv@collabora.com>
We don't currently use these for anything, but we might start using
them as input to our heuristics as part of #7697.
Signed-off-by: Simon McVittie <smcv@collabora.com>
We don't currently use these in our device-classification heuristic,
but it could be a useful input in future.
Thanks to Sam Lantinga, Ben Fradella, kevenwyld and schlegp for
providing some of these.
Signed-off-by: Simon McVittie <smcv@collabora.com>
The comments here disagreed with the actual bytes. According to
https://elixir.bootlin.com/linux/v6.3.7/source/drivers/hid/hid-wiimote-modules.c,
the Balance Board reports BTN_A and ABS_HAT0X, HAT0Y, HAT1X and HAT1Y.
This means the comments here were correct, but the .abs bits shown
were in the wrong byte.
Matching the Wii U Pro Controller against the same kernel source, it
appears to be correct: it's the same representation as a PS3 gamepad,
except that it lacks the Z and RZ axes for analogue triggers.
Signed-off-by: Simon McVittie <smcv@collabora.com>
Some of the test data previously seen here was guessed from kernel
source code, and not all of it was correct. The following devices have
now been verified against `evemu-describe` output with Linux 6.3
(thanks to Jeremy Whiting for collecting this):
- basic Wiimote
- buttons
- 3-axis accelerometer
- infra-red sensor for Sensor Bar location (precise aim)
- Motion Plus accessory (3-axis gyroscope)
- Nunchuck accessory (joystick, 2 buttons, second 3-axis accelerometer)
- Classic Controller accessory (a complete traditional gamepad)
Signed-off-by: Simon McVittie <smcv@collabora.com>
This slightly newer device than the one from #7814 is functionally
equivalent when connected via USB. When connected via Bluetooth, it has
a different button mapping.
Thanks to Sam Lantinga.
Signed-off-by: Simon McVittie <smcv@collabora.com>
https://github.com/ValveSoftware/steam-devices/pull/34 lists several
more devices that are functionally equivalent to this one from the
point of view of their evdev metadata. Thanks to apgrc.
Signed-off-by: Simon McVittie <smcv@collabora.com>
Also make details of PS4 gamepads (which are very similar from an evdev
point of view) more specific.
Thanks to Sam Lantinga and Jeremy Whiting for recording these.
Signed-off-by: Simon McVittie <smcv@collabora.com>
Like the Stadia controller, this is unusual because it represents the
Share button as the Record key from a multimedia keyboard (as of Linux
6.2.11 with the xpad driver). Thanks to Jeremy Whiting.
Signed-off-by: Simon McVittie <smcv@collabora.com>
This is a bit unusual because it has a small number of what would
ordinarily be keyboard keys. Thanks to Jeremy Whiting for recording
this.
Signed-off-by: Simon McVittie <smcv@collabora.com>
A newer evemu-describe transcript has this same controller with its
buttons mapped differently, presumably a result of driver changes in
the Linux kernel. Either way, we should recognise it as a gamepad.
Thanks to Jeremy Whiting.
Signed-off-by: Simon McVittie <smcv@collabora.com>
This didn't include any buttons, which I assume was because I
transcribed them incorrectly rather than reflecting reality. Confirmed
against another Switch Pro Controller on a more recent kernel (thanks
to Jeremy Whiting).
Signed-off-by: Simon McVittie <smcv@collabora.com>
We don't need to re-test the heuristic with the same input data, but
knowing that another device has equivalent evdev metadata is useful
information to record. Thanks to Jeremy Whiting.
Signed-off-by: Simon McVittie <smcv@collabora.com>
This was reported by Rémi Bernon as an example of older SDL's non-udev
code path going wrong for touchpads when the invoking user happens to
be in the input group, which I believe was fixed by fdd945f2.
Signed-off-by: Simon McVittie <smcv@collabora.com>
Sam Lantinga
Christoph Reichenbach
Sylvain Becker
Anonymous Maarten
Ryan C. Gordon
Frank Praznik
Ivan Mogilko
ilyas-taouaou
Ozkan Sezer
Simon McVittie
Brick
luzpaz
Linus Probert