- cmake, configure (CheckDLOPEN): --enable-sdl-dlopen is now history..
detach the dl api discovery from SDL_LOADSO_DLOPEN functionality.
define HAVE_DLOPEN. also define DYNAPI_NEEDS_DLOPEN (CheckDLOPEN is
called only for relevant platforms.)
- update SDL_config.in and SDL_config.cmake accordingly.
- SDL_dynapi.h: set SDL_DYNAMIC_API to 0 if DYNAPI_NEEDS_DLOPEN is
defined, but HAVE_DLOPEN is not.
- pthread/SDL_systhread.c: conditionalize dl api use to HAVE_DLOPEN
- SDL_x11opengl.c, SDL_DirectFB_opengl.c, SDL_naclopengles.c: rely
on HAVE_DLOPEN, not SDL_LOADSO_DLOPEN.
- SDL_config_android.h, SDL_config_iphoneos.h, SDL_config_macosx.h,
SDL_config_pandora.h, and SDL_config_wiz.h: define HAVE_DLOPEN.
Closes: https://github.com/libsdl-org/SDL/pull/4351
Without this change, driver names don't get matched correctly;
for example "a" can get matched with "alsa" since it only checks
whether the string matches up to the length of the requested
driver name.
Without this change, driver names don't get matched correctly;
for example "x" can get matched with "x11" since it only checks
whether the string matches up to the length of the requested
driver name.
b08b1bde introduced a subtle bug. Despite not using D-Bus types directly,
the code used the SDL_USE_LIBDBUS definition set by SDL_dbus.h to conditionally
compile calls SDL_DBus_ScreensaverTickle() and SDL_DBus_ScreensaverInhibit().
As a result, it still compiled without SDL_dbus.h included, but screensaver
suspension silently failed to work.
The D-Bus stuff could probably use some tweaks to be harder to accidentally
break, but for now just restore the header includes.
Configure events from compositors have an extremely annoying habit of giving us
completely bogus sizes, from all sorts of places. Thankfully, the protocol
gives us the ability to completely ignore the width/height and just stick with
what we know, so for all windows that are not meant to be resized, pretend we
never even got the width/height at all, the compositor is required to respect
our dimensions whether they match configure's suggestion or not.
Otherwise only the display resolution is changed, but the SDL window size
(and for example the window-surface size) aren't adjusted accordingly
and thus don't fill the whole screen.
See #3313
.. and maybe other platforms as well (though X11 was not affected)?
The issue was that passing a higher resolution than the current desktop
resolution to SDL_CreateWindow() with SDL_WINDOW_FULLSCREEN didn't switch
to that resolution (even though it did switch to lower resolutions).
When creating a fullscreen window, window->fullscreen wasn't even set
at all (only zeroed out), setting it only happened if the user explicitly
called SDL_SetWindowDisplayMode(). So without that, SDL_CreateWindow()
-> SDL_UpdateFullscreenMode() -> SDL_GetWindowDisplayMode() used the
resolution from window->windowed.w/h which were limited to the desktop size
due to some weird combination of WIN_AdjustWindowRectWithStyle() and
WIN_WindowProc() being called after a call to SetWindowPos().
fixes#3313
This prevents a race if two threads that need d-bus try to init it at the
same time. Note that SDL_Init will likely handle this from a single thread
at startup, but there are places outside of init where one might trigger
D-Bus init, like setting thread priority (a common first thing for a new
thread to do) resulting in SDL trying to use RTKit.
Fixes#4587.
This reintroduces the fix from 0e16ee8330, but just marks
the viewport state as dirty after a clear that needs to expand the
viewport to fill the render target, as we'll need to also reset
the orthographic projection state elsewhere, and that won't
happen if we clear the dirty flag here.
Fixes#4210.
(again.)
(...sorry...!)
The Renderer logical scaling code scales mouse coordinates, and needs to
take the window DPI into account on HIGHDPI windows. However, the
variable which tracks this, renderer->dpi_scale, is set once when the
renderer is created, and then not updated. In the event that the window
is moved to another screen, or the screen DPI otherwise changes, this
will be outdates, and potentially the coordinates will be all wrong.
So let's update the dpi_scale on the SIZE_CHANGED event: it's at least a
possibility that this will be issued on some OSes when DPI changes, and
it's otherwise already handled by SDL_Renderer's event filter.
Otherwise you might have set the viewport to the full size of
the render target in SDL's API but this change hasn't been
transmitted to Direct3D yet by the time we attempt to clear.
Fixes#4210.
SDL_AddHintCallback() uses SDL_malloc(), which means this would
run before main(), so the app wouldn't be able to supply its own
replacement SDL_malloc() implementation in time.
This code was moved to under SDL_Init. Since the hint callback
already makes efforts to not override the app manifest's
orientation settings, this is safe to move until after pre-main()
startup.
Fixes#4449.
This removes the CM_Register_Notification code on WinRT. Note
that this API _is_ available to UWP apps as of Windows 10.0.17763
(version 1809, released October 2018), according to:
https://docs.microsoft.com/en-us/uwp/win32-and-com/win32-apis#apis-from-api-ms-win-devices-config-l1-1-1dll
So it might be worth readding with some sort of preprocessor check
for minimum targeted version, or whatever is appropriate for WinRT
development.
This was causing configure events to not inform SDL of window size
changes, even when they were based on resizes that we fully expected. The
result was fullscreen->windowed not working at all, because it would
retain the desktop resolution instead of reverting to the floating size
that it had before moving to fullscreen mode.
Fixes Super Hexagon fullscreen toggling.
The flush has been removed in e5f9fae034.
Unfortunately, even though ideally the flush shouldn't be necessary,
our resize sequence isn't... well, perfect, and removing that flush causes
tons of troubles.
We're also still flushing in other paths where the window size can be
changed by the compositor and where we may potentially have to obey that
change, like in Wayland_MaximizeWindow.
This also removes the hack introduced in 7f261d3b76,
which introduces problems with protocol violations and seems to not be
necessary when flushing.
We have issues with correct resize sequence and happen to commit old-sized
buffers even after configure event for the new size has been already
acknowledged. While the reason for that stays unknown, let's at least
workaround the problem by faking window geometry into expected size.
This does not fix visual glitch on e.g. fullscreen toggling, but having
a split-second glitch is still a much better outcome than being
terminated by the compositor for protocol violation.
This was causing window changes to completely break, resulting in broken
decorations and bizarre frame timing, I don't know what exactly it's doing
but it's not good. Kept the libdecor_frame_is_floating logic, at least.
Commit 871c11191b removed delayed
resize handling, but it left the whole structure untouched that
now became unnecessary. To help with code clarity, get rid
of the structure where pending resize state used to be stored
and pass all the data directly to Wayland_HandlePendingResize
(now renamed to Wayland_HandleResize, since it's not "pending"
anymore but applied immediately)
Otherwise our windows have no window decoration on compositors that
support xdg-decoration-unstable-v1, but default to client-side mode.
Contrary to what the comment was stating, there is nothing in the protocol
that would make redundant calls to zxdg_toplevel_decoration_v1::set_mode
problematic.
Some Wayland compositors send (0,0) as "suggested" configure event sizes to
indicate that the client has to decide on its own which sizes to used. This
is commonly done when restoring from maximised, fullscreen or tiles states
to fullscreen.
We now store the last known floating states in a new set of variables and
restore them when we receive such a (0,0) configure event.
From the vfork manpage:
> The vfork() function has the same effect as fork(2), except that
> the behavior is undefined if the process created by vfork() either
> modifies any data other than a variable of type pid_t used to store
> the return value from vfork(), or returns from the function in which
> vfork() was called, or calls any other function before successfully
> calling _exit(2) or one of the exec(3) family of functions.
unsetenv is still called inside a child process, so it does not
influence the rest of the application.
This fixes a crash on pressing keyboard button when compositor sends
zero as repeat rate, indicating that key repeat should be disabled.
From Wayland protocol spec:
> Negative values for either rate or delay are illegal. A rate of zero
> will disable any repeating (regardless of the value of delay).
This is a workaround and not a proper fix, but this is possibly complicated,
and possibly a corner case, so this will do for 2.0.16, if not the
foreseeable future.
Reference issue #4561
When we removed the OpenGL resize workaround it introduced a problem for
fullscreen windows in particular: When leaving fullscreen we tried to send a
resize event, but UpdateFullscreenMode would send a SIZE_CHANGED immediately
after, deleting our resize event and causing the following configure event's
resize to be ignored. This timing issue resulted in fullscreen windows not
being resized at all when becoming a floating window.
By always forcing resize events from configure events, we ensure that RESIZED
always makes it through. SetWindowSize-type changes should be unaffected as
they do not fire configure events.
The RenderDrawLinesWithRects and RenderDrawLinesWithRectsF functions can
sometimes call QueueCmdFillRects() with the data pointed to by frects
uninitialised. This can occur if none of the lines can be replaced with
rects, in which case the frects array is empty, and nrects is 0.
gcc 10.3.0 will detect this possibility, and print a warning like:
/home/david/Development/SDL/src/render/SDL_render.c: In function 'RenderDrawLinesWithRectsF':
/home/david/Development/SDL/src/render/SDL_render.c:2725:15: warning: '<unknown>' may be used uninitialized [-Wmaybe-uninitialized]
2725 | retval += QueueCmdFillRects(renderer, frects, nrects);
| ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/home/david/Development/SDL/src/render/SDL_render.c:499:1: note: by argument 2 of type 'const SDL_FRect *' to 'QueueCmdFillRects' declared here
499 | QueueCmdFillRects(SDL_Renderer *renderer, const SDL_FRect * rects, const int count)
| ^~~~~~~~~~~~~~~~~
This is harmless, because when this is uninitialised, nrects is always
0, so QueueCmdFillRects() does nothing anyway. We therefore can work
around this by only calling QueueCmdFillRects() when nrects is nonzero.
Somewhat impressively, gcc recognises that this is now safe.
This is needed to support CHERI, and thus Arm's experimental Morello
prototype, where pointers are implemented using unforgeable capabilities
that include bounds and permissions metadata to provide fine-grained
spatial and referential memory safety, as well as revocation by sweeping
memory to provide heap temporal memory safety.
The C standard does not guarantee that if two pointers compare equal
they are the same pointer, as C pointers have a notion of provenance,
and compilers have been known to exploit this during optimisation. For
CHERI, this becomes even more important, as in-place expansion can
result in realloc returning a capability to the same address but with
increased capability bounds, and so reusing the old capability will trap
trying to access outside the bounds of the original allocation.
In the case that ptr == mem, memdiff and ptrdiff should still be equal,
so the only overhead is a small amount of pointer arithmetic and a store
of the new pointer (which is required per the C standard in order to not
be undefined behaviour when next loaded).
This also fixes the calculation of oldmem to use uintptr_t rather than
size_t as casting the pointer to size_t on CHERI will strip the
capability metadata, including the validity tag, with the subsequent
cast back to void * resulting in a null-derived capability whose
validity tag is clear and thus cannot be dereferenced without trapping.
This is needed to support CHERI, and thus Arm's experimental Morello
prototype, where pointers are implemented using unforgeable capabilities
that include bounds and permissions metadata to provide fine-grained
spatial and referential memory safety, as well as revocation by sweeping
memory to provide heap temporal memory safety.
On most systems (anything with a flat memory hierarchy rather than using
segment-based addressing), size_t and uintptr_t are the same type.
However, on CHERI, size_t is just an integer offset, whereas uintptr_t
is still a capability as described above. Casting a pointer to size_t
will strip the metadata and validity tag, and casting from size_t to a
pointer will result in a null-derived capability whose validity tag is
not set, and thus cannot be dereferenced without faulting.
The audio and cursor casts were harmless as they intend to stuff an
integer into a pointer, but using uintptr_t is the idiomatic way to do
that and silences our compiler warnings (which our build tool makes
fatal by default as they often indicate real problems). The iconv and
egl casts were true positives as SDL_iconv_t and iconv_t are pointer
types, as is NativeDisplayType on most OSes, so this would have trapped
at run time when using the round-tripped pointers. The gles2 casts were
also harmless; the OpenGL API defines this argument to be a pointer type
(and uses the argument name "pointer"), but it in fact represents an
integer offset, so like audio and cursor the additional idiomatic cast
is needed to silence the warning.
When choosing an X11 Visual for a window based on its GLX capabilities, first
try glXChooseFBConfig (if available) before falling back to glXChooseVisual.
This normally does not make a difference because most GLX drivers create a
Visual for every GLXFBConfig, exposing all of the same capabilities.
For GLX render offload configurations (also know as "PRIME") where one GPU is
providing GLX rendering support for windows on an X screen running on a
different GPU, the GPU doing the offloading needs to use the Visuals that were
created by the host GPU's driver rather than being able to add its own. This
means that there may be fewer Visuals available for all of the GLXFBConfigs the
guest driver wants to expose. In order to handle that situation, the NVIDIA GLX
driver creates many GLXFBConfigs that map to the same Visual when running in a
render offload configuration.
This can result in a glXChooseVisual request failing to find a supported Visual
when there is a GLXFBConfig for that configuration that would have worked. For
example, when the game "Unnamed SDVX Clone" [1] tries to create a configuration
with multisample, glXChooseVisual fails because the Visual assigned to the
multisample GLXFBConfigs is shared with the GLXFBConfigs without multisample.
Avoid this problem by using glXChooseFBConfig, when available, to find a
GLXFBConfig with the requested capabilities and then using
glXGetVisualFromFBConfig to find the corresponding X11 Visual. This allows the
game to run, although it doesn't make me any better at actually playing it...
Signed-off-by: Aaron Plattner <aplattner@nvidia.com>
Fixes: https://forums.developer.nvidia.com/t/prime-run-cannot-create-window-x-glxcreatecontext/180214
[1] https://github.com/Drewol/unnamed-sdvx-clone
As of [1], SDL now compiles with a warning in SDL_waylandevents.c on
32-bit systems under gcc 10.3.0:
/tmp/SDL/src/video/wayland/SDL_waylandevents.c: In function 'seat_handle_capabilities':
/tmp/SDL/src/video/wayland/SDL_waylandevents.c:958:22: warning: cast from pointer to integer of different size [-Wpointer-to-int-cast]
958 | SDL_AddTouch((SDL_TouchID)seat, SDL_TOUCH_DEVICE_DIRECT, "wayland_touch");
| ^
/tmp/SDL/src/video/wayland/SDL_waylandevents.c:964:22: warning: cast from pointer to integer of different size [-Wpointer-to-int-cast]
964 | SDL_DelTouch((SDL_TouchID)seat);
| ^
This is due to SDL_TouchID always being 32-bit, but seat being a pointer
which is (obviously) only 32-bit on 32-bit systems. The conversion is
therefore harmless, so silence it with an extra cast via intptr_t.
This is what the cocoa backend does (and is similar to what the Win32
backend does, except with size_t).
Fixes: 03c19efbd1 ("Added support for multiple seats with touch input on Wayland")
[1]: 03c19efbd1
When wayland is not dynamically loaded (--enable-wayland-shared=no)
libdecor.h is not included unless SDL_VIDEO_DRIVER_WAYLAND_DYNAMIC
is set, so it fails to build. We can't simply move the libdecor.h
include above the #ifdef SDL_VIDEO_DRIVER_WAYLAND_DYNAMIC block, as
libdecor.h itself #includes wayland headers we need to replace with
#defines. Instead, duplicate the #include.
Fixes https://github.com/libsdl-org/SDL/issues/4543
Note that this doesn't fix any of the underlying issues of libdecor
being treated as part of wayland, it just fixes the build. A better
solution would probably be to decouple the wayland dynamic loading
from the libdecor dynamic loading completely, though that is a lot
more work...
Each window can have at most one zxdg toplevel decoration, but as of
[1], we accidentally create two. (If libdecor is not in use). This
causes wayland windows with server-side decorations (e.g. on KDE/KWin)
to crash with the message:
zxdg_decoration_manager_v1@7: error 1: decoration has been already constructed
This extra zxdg_decoration_manager_v1.get_toplevel_decoration() call was
introduced while deprecating wl-shell and xdg-shell-stable[1] support,
and possibly was a bad interaction with [2], which moved the decoration
creation around.
Fixes: 6aae5b44f8 ("Remove wl-shell and xdg-shell-unstable-v6 support (#4323)")
[1]: https://github.com/libsdl-org/SDL/pull/4323
[2]: https://github.com/libsdl-org/SDL/pull/4374
WASAPI_WaitDevice is used for audio playback and capture, but needs to
behave slighty different.
For playback `GetCurrentPadding` returns the padding which is already
queued, so WaitDevice should return when buffer length falls below the
buffer threshold (`maxpadding`).
For capture `GetCurrentPadding` returns the available data which can be
read, so WaitDevice can return as soon as any data is available.
In the old implementation WaitDevice could suddenly hang. This is
because on many capture devices the buffer (`padding`) wasn't filled
fast enough to surpass `maxpadding`. But if at one point (due to unlucky
timing) more than maxpadding frames were available, WaitDevice would not
return anymore.
Issue #3234 is probably related to this.
On modern CPUs, there's no penalty for using the unaligned instruction on
aligned memory, but now it can vectorize unaligned data too, which even if
it's not optimal, is still going to be faster than the scalar fallback.
Fixes#4532.
The Game Controller Kit doesn't show the controllers at startup, so the HIDAPI driver sees them first and therefore gets preference when a controller is supported by both drivers.
This fixes bug https://github.com/libsdl-org/SDL/issues/4209
This prevents an assertion whem LINUX_JoystickGetGamepadMapping tried to
open the stick temporarily and messed with global state by doing so. Now
the global state is only set in LINUX_JoystickOpen, but the common code
is shared by both interfaces.
Fixes#4198.
Wayland video subsystem uses a mix of libc and SDL function.
This patch switches libc functions to SDL ones and fixes a mismatch in memory
allocation/dealoccation of SDL_Cursor in SDL_waylandmouse.c (calloc on line 201
and SDL_free on line 313) which caused memory corruption if custom memory
allocator where provided to SDL.
As written, these contain undefined stack contents, which in practice
causes crashes/hangs and/or triggers the validation layers (they
complain about `pNext` and `flags` not being NULL).
When hint SDL_HINT_OPENGL_ES_DRIVER is set to "1" (e.g. for ANGLE support), assertion due to !_this->gl_config.driver_loaded can be causes while EGL is available.
When relative mode is enabled and not using warp mode, the cursor is
being clipped to the window. Therefore there is no reason to restore the
cursor position to the center.
Avoiding the warp to center simplifies mouse position event flow, as we
are no longer potentially receiving mouse events for the automated
movement of the cursor and can be (mostly) assured that an incoming
event from the windowing system is that of external means.
The implementation of clip logic for relative mode seemed to
unnecessarily limit the usable area to the middle of the window, in a
2x2 pixel region. This has the adverse side effect of moving the
operating system cursor to that location, even if it is in a valid
location in the window.
While in most scenarios this is handled correctly (by storing the
original position of the cursor in the window and restoring when leaving
relative mode), there are edge cases where this clip operation can cause
WM_MOUSEMOVE to fire at a point in time where it counts as a relative
delta from SDL's perspective.
X11_SetDisplayMode currently calls X11_XRRSetCrtcConfig alone. This results
in the monitor's viewport getting changed, but the underlying screen dimensions
stay the same.
The spec indicates that RRSetCrtcConfig only changes the crtc mode and has no effect
on the screen dimensions, only mentioning that the new crtc must fit entirely within the
screen size. For the size to change, RRSetScreenSize also needs to be called.
This affects Metro Exodus on Linux, when changing the resolution in the in-game settings
Metro gets stuck in a loop waiting for the size of its vulkan surface to change. Because
XRRSetScreenSize is not called the screen size is never changed, the vulkan surface dimensions
do not change, and Metro hangs forever watching for a surface size update that will
never come.
This change disables the CRTC, calls XRRSetScreenSize, and then updates the
CRTC configuration. This fixes changing the resolution from the Metro settings.
Tested with:
Metro Exodus, Portal 2
To enter Bluetooth pairing mode hold B and Action (button with circle) buttons for 3 seconds.
It works via usual HIDAPI if special filter driver is not installed:
https://www.amazon.com/gp/help/customer/display.html?nodeId=GZCT4CTFHXLHEB9T
With that driver installed it mimics Xbox One controller and works via XInput under Windows.
Under DInput this controller is not usable at all.
It is called from WGI before the normal joystick detection has been run, so it needs to actually enumerate currently connected devices.
We can skip the logic checking for other drivers also supporting this device, because that logic is duplicated from the call site.
Not only is it more efficient to batch process pending events, it is
necessary for correctness with the Win32 backend. WIN_PumpEvents() runs
periodic updates of the cursor clip region and disambiguation of
left and right shift keys in addition to standard event processing.
SDL_GetBasePath grows its path buffer for long paths, but GetModuleFileNameExW always truncates and succeeds,
so `len` was always equal to (buflen - 1) which is 127. This is easily fixed by checking for (buflen - 1) instead of buflen.
For paths longer than MAX_PATH, this problem sometimes got hidden by Windows path shortening ("C:\PROGRA~1\" etc.).
Tested on Windows 10 x64 19041 and 10586.
SDL_JoystickSetVirtualAxisInner() and SDL_JoystickSetVirtualHatInner()
did not properly sanitize the 'axis' and 'hat' parameters.
Signed-off-by: Paul Cercueil <paul@crapouillou.net>
Based on a patch by Jochen Schäfer <josch1710@live.de> :
The problem is, that in the initialization code uses the same structure for
desktop_mode and current_mode. See SDL_os2video.c:OS2_VideoInit():
stSDLDisplay.desktop_mode = stSDLDisplayMode;
stSDLDisplay.current_mode = stSDLDisplayMode;
...
stSDLDisplayMode.driverdata = pDisplayData;
Then, if you call GetDisplayModes, current_mode will added to the modes
list, with the same driverdata pointer to desktop_mode.
SDL_AddDisplayMode( display, &display->current_mode );
When VideoQuit gets called, first the modes list gets freed including the
driverdata, the desktop_mode gets freed. See SDL_video.c:SDL_VideoQuit():
for (j = display->num_display_modes; j--;) {
SDL_free(display->display_modes[j].driverdata);
display->display_modes[j].driverdata = NULL;
}
SDL_free(display->display_modes);
display->display_modes = NULL;
SDL_free(display->desktop_mode.driverdata);
display->desktop_mode.driverdata = NULL;
So, the display_modes[j].driverdata gets freed, but desktop_mode->driverdata
points to the same memory, but is not NULL'ed. When desktop_mode->driverdata
gets freed the memory is already freed, and libcx crashes the application on
SDL_Quit.
Based on a patch by Jochen Schäfer <josch1710@live.de> :
On a T420 pressing the ACPI button for volume control, big scancodes
were emitted. This was causing an overflow, because missing guards.
- Do not call IDirectInputDevice8_QueryInterface(device, &IID_IDirectInputDevice8,...) on DIRECTINPUTDEVICE8 device
- Get joystick VendorID and ProductID via IDirectInputDevice8_GetProperty(.., DIPROP_VIDPID, ..) call instead of messing with DIDEVICEINSTANCE.guidProduct
- Normalize HID device interface path to upper case for stable operation of XInput check
- Remove useless RawInput calls in SDL_IsXInputDevice() - just check for "IG_" string in HID device interface path that we already have
There shouldn't be any observable behavior changes.
We can be in a situation where we receive a win32 hook callback on the same
thread that is currently waiting. In that case, we do still need to trigger
a wakeup when an event is pushed because the hook itself won't necessarily
do that (depending on what we return from the hook).
When possible use native os functions to make a blocking call waiting for
an incoming event. Previous behavior was to continuously poll the event
queue with a small delay between each poll.
The blocking call uses a new optional video driver event,
WaitEventTimeout, if available. It is called only if an window
already shown is available. If present the window is designated
using the variable wakeup_window to receive a wakeup event if
needed.
The WaitEventTimeout function accept a timeout parameter. If
positive the call will wait for an event or return if the timeout
expired without any event. If the timeout is zero it will
implement a polling behavior. If the timeout is negative the
function will block indefinetely waiting for an event.
To let the main thread sees events sent form a different thread
a "wake-up" signal is sent to the main thread if the main thread
is in a blocking state. The wake-up event is sent to the designated
wakeup_window if present.
The wake-up event is sent only if the PushEvent call is coming
from a different thread. Before sending the wake-up event
the ID of the thread making the blocking call is saved using the
variable blocking_thread_id and it is compared to the current
thread's id to decide if the wake-up event should be sent.
Two new optional video device methods are introduced:
WaitEventTimeout
SendWakeupEvent
in addition the mutex
wakeup_lock
which is defined and initialized but only for the drivers supporting the
methods above.
If the methods are not present the system behaves as previously
performing a periodic polling of the events queue.
The blocking call is disabled if a joystick or sensor is detected
and falls back to previous behavior.