Most of the raw input events are dispatched in the main windows message loop. We only dispatch device change messages separately when we need them to be completely up to date.
It's legitimate to have a surface with 0 width or height (null 'pixels' pointer).
But calling SDL_FillRects would wrongly set the error "You must lock the surface".
src/joystick/windows/SDL_rawinputjoystick.c: In function 'RAWINPUT_HandleStatePacket':
src/joystick/windows/SDL_rawinputjoystick.c:1343:9: warning: suggest explicit braces to avoid ambiguous 'else'
multiply gyro values by sensitivity
When the hardware calibration fails, values read from sensors need to be multiplied by default sensitivity (16 for gyro, 1 for accelerometer).
Simon McVittie
When watching for hotplug events we can poll the inotify fd, but we
still need to scan /dev/input once per process, otherwise we'll fail
to detect devices that were already connected.
Flatpak[1] and pressure-vessel[2] are known to use user namespaces,
therefore udev event notification via netlink won't work reliably.
Both frameworks provide a filesystem API that libraries can use to
detect them. Do that, and automatically fall back from udev-based
device discovery to the inotify-based fallback introduced in Bug #5337.
[1] <https://flatpak.org/>
[2] <https://gitlab.steamos.cloud/steamrt/steam-runtime-tools/-/tree/master/pressure-vessel>
Signed-off-by: Simon McVittie <smcv@collabora.com>
Alex S
Evdev headers aren't actually included in the base system (well, it has a private copy), they are available through the devel/evdev-proto port instead. We also have devel/libinotify and devel/libudev-devd shims, I didn't verify whether they work with SDL.
This fixes bad report parsing for various newer Xbox controllers, and this driver is now preferred over XInput, since it handles more than 4 controllers.
C.W. Betts
This patch adds support to the GameController framework on macOS Big Sur and later, adding support for MFi controllers as well as rumble support for PS4 and Xbox One. There is some code to make sure that the IOKit joystick handler doesn't include two controllers at once.
While the GameController framework is present in earlier versions of macOS, there was no public, approved way of checking if a specific IOHIDDevice is a controller that GameController could handle. This was changed in Big Sur.
Added support for the PS4 controller gyro and accelerometer on iOS and HIDAPI drivers
Also fixed an issue with the accelerometer on iOS having inverted axes
As the name suggests, the hint should only apply to SDL_THREAD_PRIORITY_TIME_CRITICAL
The resulting priorities for my current distro result in these values:
| High | Time Critical
Hint |--------------|-----------------
0 | P=10 N=-10 | P=5 N=-15
1 | P=10 N=-10 | P=-21 N=0
Spooky
For some reason the Logitech Extreme 3D joystick was added to SDL_gamecontrollerdb.h in the linux section only.
This breaks the joystick in linux as it is not a gamepad. I am unable to correctly use or map the Logitech Exteme 3D joystick in games that use SDL2 in linux.
Please remove Logitech Extreme 3D from SDL_gamecontrollerdb.h Linux section. It is a joystick not a gamepad.
Bart van der Werf
When directinput fails to load, but a controlller is plugged in, an access violation happens.
This is due to IEventHandler_CRawGameControllerVtbl_InvokeAdded calling SDL_DINPUT_JoystickPresent which does not check if dinput is assigned signalling initialization of directinput.
Joel Linn
This fixes two types of MSVC compiler warnings.
- One parameter in the function signatures of two WGI event handlers had one level of indirection too much (and did not match Windows SDK headers). The indirection was cast away so it still worked.
- size_t was implicitly cast to UINT32 for a number of (constant) string lengths.
wahil1976
This patch adds the KBIO text input driver for FreeBSD, which allows text input to fully work without text spilling out into the console. It also supports accented input, AltGr keys and Alt Lock combinations.
Tested with US accent keys layout and various AltGr layouts.
This improves SDL's ability to detect joystick hotplug in a container
environment.
We cannot reliably receive events from udev in a container, because they
are delivered as netlink events, which are authenticated by their uid
being 0. However, in a user namespace created by an unprivileged user
(for example bubblewrap, as used by Flatpak and Steam's
pressure-vessel-wrap), the kernel does not allow us to map uid 0, and
the netlink events appear to be from the kernel's overflowuid (typically
65534/nobody), meaning libudev cannot distinguish between genuine uevents
from udevd and an attack by a malicious local user.
Signed-off-by: Simon McVittie <smcv@collabora.com>
Anything with X, Y and Z axes but no buttons is probably an
accelerometer (this is the assumption made in udev).
Signed-off-by: Simon McVittie <smcv@collabora.com>
Previously we only checked for at least one button or key and at least
the X and Y absolute axes, but this has both false positives and false
negatives.
Graphics tablets, trackpads and touchscreens all have buttons and
absolute X and Y axes, but we don't want to detect those as joysticks.
On normal Linux systems ordinary users do not have access to these
device nodes, but members of the 'input' group do.
Conversely, some game controllers only have digital buttons and no
analogue axes (the Nintendo Wiimote is an example), and some have axes
and no buttons (steering wheels or flight simulator rudders might not
have buttons).
Use the more elaborate heuristic factored out from SDL's udev code path
to handle these cases.
In an ideal world we could use exactly the same heuristic as udev's
input_id builtin, but that isn't under a suitable license for inclusion
in SDL, so we have to use a parallel implementation of something
vaguely similar.
Signed-off-by: Simon McVittie <smcv@collabora.com>
This works on capability bitfields that can either come from udev or
from ioctls, so it is equally applicable to both udev and non-udev
input device detection.
Signed-off-by: Simon McVittie <smcv@collabora.com>
Device enumeration via libudev can fail in a container for two reasons:
* the netlink protocol between udevd and libudev is considered private,
so there is no API guarantee that the version of libudev in a container
will understand netlink messages from a dissimilar version of udevd
on the host system;
* the netlink protocol between udevd and libudev relies for security on
being able to check the uid of each message, but in a container with
a user namespace where host uid 0 is not mapped, the libudev client
cannot distinguish between messages from host uid 0 and messages from
a different, malicious user on the host
To make this easier to experiment with, always compile the fallback
code path even if libudev is disabled. libudev remains the default if
enabled at compile time, but the fallback code path can be forced.
Signed-off-by: Simon McVittie <smcv@collabora.com>
GetAsyncKeyState() and GetRawInputData() report the state of the physical
buttons without applying the user's primary/secondary mouse button swap
preference. Swap the buttons returned from these functions, so we expose a
consistent view of the buttons to SDL callers. This new behavior also matches
the behavior of macOS and X11 backends.
See the Remarks section of the GetAsyncKeyState() function on MSDN.
We should only perform the VK_LEFT, VK_UP, etc. mapping if none of the other
special mappings apply. This allows the scancode normalization for the number
pad to take place as intended.
When we request realtime priority from rtkit, we have a rttime limit. If we exceed
that limit, the kernel will send SIGKILL to the process to terminate it.
This isn't something that most high priority processes will want, only processes
that selectively opt into SCHED_RR/FIFO through SDL_HINT_THREAD_PRIORITY_POLICY
should be subject to this level of scrutiny.
This change:
* Switches non-apple posix OSs to use SCHED_OTHER instead of SCHED_RR
for SDL_THREAD_PRIORITY_HIGH/SDL_THREAD_PRIORITY_TIME_CRITICAL.
* Fixes using a hardcoded RLIMIT_RTTIME, instead queries it from rtkit
* Only sets RLIMIT_RTTIME for MakeRealtime rtkit requests
* Adds a note regarding the possible SIGKILL with SDL_HINT_THREAD_PRIORITY_POLICY
* Introduces SDL_HINT_THREAD_FORCE_REALTIME_TIME_CRITICAL to allow apps to acquire realtime scheduling policies on Linux
CPU Vendor ID "Shanghai" and "CentaurHauls" belongs to Zhaoxin.
Background:
Shanghai Zhaoxin Semiconductor Co., Ltd ("Zhaoxin") , established in 2013,
headquartered in Zhangjiang, Shanghai, China. Zhaoxin aims at providing
general-purpose x86 processors.
Related Zhaoxin Linux Kernel patch can be found at
https://lore.kernel.org/lkml/01042674b2f741b2aed1f797359bdffb@zhaoxin.com
Best regards.
Debugging inside rtkit showed we were failing the RLIMIT_RTTIME check, now that we're asking for realtime and not just high-priority due to a change in SDL.
Between that and the DBus code in SDL being wrong in previous changelist I'm not sure how this could have ever worked.
Nov 02 20:34:15 redcore rtkit-daemon[2825]: Failed to parse MakeThreadRealtime() method call: Argument 1 is specified to be of type "uint32", but is actually of type "int32"
Nov 02 20:34:15 redcore rtkit-daemon[2825]: Failed to parse MakeThreadRealtime() method call: Argument 1 is specified to be of type "uint32", but is actually of type "int32"
Docs:
http://git.0pointer.net/rtkit.git/tree/README
CLIENTS:
To be able to make use of realtime scheduling clients may
request so with a small D-Bus interface that is accessible on
the interface org.freedesktop.RealtimeKit1 as object
/org/freedesktop/RealtimeKit1 on the service
org.freedesktop.RealtimeKit1:
void MakeThreadRealtime(u64 thread_id, u32 priority);
void MakeThreadHighPriority(u64 thread_id, s32 priority);
wcodelyokoyt
The atom name that X11_GetAtomName() returns never gets freed, which result in a minor memory leak (14 bytes?) every time the user drops a file on a window.
You can see the line in question here:
6b6170caf6/src/video/x11/SDL_x11events.c (L1350)
Fix: call XFree on name after the while loop.
Joel Linn
This patch fixes a MSVC warning, which is dependent on the regional settings of the build system. Although the character is inside a comment and harmless, it is undesirable to disable the warning for this.
OpenGL leaves the final line segment open, SDL's software renderer does not,
so we need a tiny bit of trigonometry here to move one more pixel in the right
direction.
Xbox Elite controllers use AUX1-AUX4 to represent the paddle buttons when using the HIDAPI driver
PS4 and PS5 controllers use AUX1 to represent the touchpad button
Nintendo Switch Pro controllers use AUX1 to represent the capture button
This allows one to build Raspberry Pi versions on an ancient version of
Raspbian and get both the KMSDRM and RPI video targets built into SDL, giving
maximum binary compatibility from linking against an older glibc, etc, but
also making one library that can access video on all RPi models and OS
releases.
batyastudios
Basicly there is problem and somewhat a solution: https://discourse.libsdl.org/t/setwindowmaximumsize-bug/28267
If you SDL_SetWindowMaximumSize() after SDL_SetWindowMinimumSize() with one of axes have the same value, function will have no effect.
This: (line 2144@SDL_video.c)
if (max_w <= window->min_w || max_h <= window->min_h) {
SDL_SetError("SDL_SetWindowMaximumSize(): Tried to set maximum size smaller than minimum size");
return;
}
May be changed to this:
if (max_w < window->min_w || max_h < window->min_h) {
SDL_SetError("SDL_SetWindowMaximumSize(): Tried to set maximum size smaller than minimum size");
return;
}
When converting audio from signed to unsigned values of vice-versa
the silence value chosen by SDL was the value of the device, not
of the stream that the data was being put into. After conversion
this would lead to a very high or low value, making the speaker
jump to a extreme positon, leading to an audible noise whenever
creating, destroying or playing scilence on a device that reqired
such conversion.
UnmapNotify event does not mean that window has been iconified. It
just reports that window changed state from mapped to unmapped.
XReparentWindow can unmap and remap window if it was mapped. This
causes unnecessary events - HIDDEN, MINIMIZED, RESTORED and SHOW.
These events are problematic with Metacity 3.36+ which started to
remove window decorations from fullscreen windows.
- SDL makes decorated window fullscreen
- Metacity removes decorations
- SDL gets UnmapNotify and exits from fullscreen
- Metacity re-adds decorations
As SDL will also get MapNotify event it will try to restore
window state causing above steps to repeat.
https://bugzilla.libsdl.org/show_bug.cgi?id=5314
Add a minimal my_gradd.h containing structures and constants only used
by SDL_os2vman.c -- based on public knowledge from around the internet
including pages from http://www.osfree.org and http://www.edm2.com .
Original code assigned MCIMixSetup.ulSamplesPerSec value to it, but it
is just the freq... We now change spec->samples only either if it is 0
or we changed the frequency, by picking a default of ~46 ms at desired
frequency (code taken from SDL_audio.c:prepare_audiospec()).
With this, the crashes I have been experiencing are gone.
- video: VideoBootStrap->available() is gone.
- thread: all important SDL_CreateThread internal data now put into
struct SDL_Thread: changes to SDL_SYS_CreateThread().
- events / video: SDL_SetDoubleClickTime() removed -- functionality
moved to SDL_mouse.c:SDL_MouseDoubleClickTimeChanged().
- video: struct SDL_VideoDevice-> CreateWindow and CreateWindowFrom
members renamed to CreateSDLWindow and CreateSDLWindowFrom
Has been happening with testfilesystem from 2.0.6 and newer because
of commit 572a721879ef.
Also set error strings in certain error conditions.
Also applied coding style / whitespace fixes, while I was there.
- Displays may have been added, removed or changed and all cached monitor
handles are invalidated as a result.
- Display events are handled in three steps:
1. Mark all currently know displays as invalid
2. Enumerate all displays, adding new ones and marking known displays as valid
3. Remove all displays still invalid after enumeration
- Display connect/disconnect events are sent when displays are added or removed
after initial setup
(Also see: https://bugzilla.libsdl.org/show_bug.cgi?id=4822)
Building the current tree against 10.8 SDK, clang emits the following warning:
src/video/cocoa/SDL_cocoawindow.m:1846:27: warning: instance method '-isOperatingSystemAtLeastVersion:' not found (return type defaults to 'id') [-Wobjc-method-access]
![processInfo isOperatingSystemAtLeastVersion:version]) {
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/opt/MacOSX10.8.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSProcessInfo.h:20:12: note: receiver is instance of class declared here
@interface NSProcessInfo : NSObject {
^
1 warning generated.
isOperatingSystemAtLeastVersion is an 10.10 thing.
loadNibNamed:owner:topLevelObjects is available on 10.8 and newer.
There is an issue report here about an app failing to function on
10.7 and earlier: https://discourse.libsdl.org/t/28179
I _think_ this is a right thing to do; it fixes a .wav file I have here that
has blockalign==2 when channels==2 and bitspersample==16, which otherwise
would fail.
Add hint SDL_HINT_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO not to pause audio when
the app goes to background.
(It requires SDL_ANDROID_BLOCK_ON_PAUSE as "Non blocking")
SDL_cocoametalview was consuming the first click rather than passing it
through to the SDLView underneath which overrides [NSView acceptsFirstMouse]
based on the user's SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH preference.
that are mapped to it and automatically invalidate them when it is freed
- refcount is kept so that an external application can still create a reference
to SDL_Surface.
- lock_data was un-used and is now renamed and used as a list keep track of the blitmap
"In the second half of 2021, new apps will be required to publish with the Android App Bundle on Google Play"
(see https://developer.android.com/guide/app-bundle)
And "Android App Bundles don't support APK expansion (*.obb) files".
It is a protocol error to attempt to create a pointer confine (i.e.
`SDL_SetWindowGrab`) while a locked pointer is active, and vice-versa.
Instead of aborting due to a protocol error, this commit makes SDL
gracefully downgrade locked pointers to confines when appropriate.
We now handle HiDPI correctly, and touches are clamped to the viewport. So
if you are rendering to a logical 640x480 in a 720p window, and touch the
letterboxing at point (640,700), it will report the touch at (0.5,1.0) instead
of outside the documented range.
Previously the first card with non-empty connectors, encoders
and crtcs would be selected, however KMSDRM_VideoInit could still reject
it if the connector was not connected. This allow finding the first card
(in a multi GPU setup) that is actually connected to a display.
Manuel Alfayate Corchete
I noticed pt2-clone had problems with it's optional hardware mouse on the KMSDRM backend: cursor had a transparent block around it.
So I was investigating and it seems that a GBM cursor needs it's pixels to be alpha-premultiplied instead of straight-alpha.
A
lso, I was previously relying on "manual testing" for the cursor size, but it's far better to use whatever the DRM driver recommends via drmGetCap(): any working driver should make a size recommendation via drmGetCap(), so that's what we use now. I took this decision because I found out that the AMDGPU driver reported working cursor sizes that would appear garbled on screen, and only the recommended cursor size works.
This fixes a case where you render to the backbuffer, then render to a render
target, set the current target back to the backbuffer, and then present
without drawing anything else; in this circumstance, the Present command
would never happen.
Fixes Bugzilla #5011.
This is handled in in the higher-level SDL_GL_LoadLibrary().
All uses of SDL_EGL_LoadLibrary (which calls the Only version) are just
target-specific wrappers for their own GL_LoadLibrary hook, with two
exceptions which now handle driver_loaded correctly (although it's
questionable if these init-if-no-one-did-it-correctly-already code blocks
should exist at all, fwiw).
Fixes Bugzilla #5190.
Instead of creating an X11 connection to test that X11 is available,
closing the connection, and then reconnecting for real, use the same
connection to handle both cases.
The X11 connection retry delay mechanism in the case where X11 is
dynamically loaded has been removed. It was only necessary to avoid
authetnication token reuse from the XOpenDisplay call that used to
exist in X11_Available. Now that this call is only made once, it
is no longer needed.
Also drop unused and inapplicable code from a comment.
***
The two are only ever called together, and combining them makes it possible
to eliminate redundant symbol loading and redundant attempts to connect
to a display server.
Manuel Alfayate Corchete
This small patch fixes the KMSDRM_CreateSurfaces() call in KMSDRM_CreateWindow(), that was segfaulting deeper into SDL internals because the windata->viddata pointer wasn't set before the KMSDRM_CreateSurfaces() call.
So that's what this small patch does.
Now, L?VE2D works perfectly well on the Raspberry Pi 3, instead of just segfaulting.
JackBoosY
In src/video/winrt/SDL_winrtgamebar.cpp line 55:
virtual HRESULT STDMETHODCALLTYPE add_VisibilityChanged(
__FIEventHandler_1_IInspectable *handler,
Windows::Foundation::EventRegistrationToken *token) = 0;
The macro __FIEventHandler_1_IInspectable defined in windows.fondation.h(Windows10 SDK 10.0.17763.0) line 3576:
#define __FIVector_1_Windows__CFoundation__CPoint ABI::Windows::Foundation::Collections::__FIVector_1_Windows__CFoundation__CPoint_t
but no longer exists in Windows 10 SDK 10.0.19041.0.
After searching this macro in the sdk include path, I found that it was defined in many header files. But it should be replaced in windows.system.h .
On some systems, GetClipCursor() impacts performance when called frequently, so only call it every once in a while to make sure we haven't lost our capture.
Manuel Alfayate Corchete
I'm trying to build SDL2 with threads support here in GNU/Linux, both X86 and ARM, and it does not seem to be possible ATM:
/home/manuel/src/SDLLLL/src/core/linux/SDL_threadprio.c:233:26: error: 'rtkit_max_realtime_priority' undeclared (first use in this function)
Manuel Alfayate Corchete
This patch is needed so programs that do this work as expected:
1) Start in a different video mode than the mode used by the system and then...
2) Try to go fullscreen with the mode originally used by the system via SetWindowFullScreen() with the SDL_WINDOW_FULLSCREEN_DESKTOP flag.
An example would be pt2-clone in https://github.com/8bitbubsy/pt2-clone.
This program does this:
Starts with:
video.window = SDL_CreateWindow("", SDL_WINDOWPOS_CENTERED,
SDL_WINDOWPOS_CENTERED, screenW, screenH, windowFlags);
and then, *IF* the user has configured it in fullscreen mode in its .ini, it tries to go fullscreen with the desktop mode:
SDL_SetWindowFullscreen(video.window, SDL_WINDOW_FULLSCREEN_DESKTOP);
This sequence of operations is currently failing because SDL_SetDisplayModeForDisplay() in SDL_video.c fails because display->desktop_mode is not being initialized with its correct value: SetDisplayMode() in SDL_kmsdrmvideo.c will not be able to set the mode because it detects the mode to have a driverdata of 0x0 ("if (!modedata)") and rightfully returns an error.
So, the included patch fixes this small problem, and programs that first change the video mode and then try to go fullscreen with the system video mode will now work.
The patch simply fixes an small omission, but its really needed now that dynamic video mode changing was implemented on the KMSDRM backend.
Ryan C. Gordon
As discussed here:
https://discourse.libsdl.org/t/question-about-implementation-of-sdl-updatewindowsurfacerects/27561
"As you can see this function [WIN_UpdateWindowFramebuffer, in src/video/windows/SDL_windowsframebuffer.c] calls BitBlt on entire screen, even though it accepts the rects. Rects variable is not even used in this function at all. Now my question is why is that the case?"
Anthony Pesch
I was looking into my own input bug and noticed an issue in the HIDAPI code while looking over it. I don't have a controller that goes down this path to test and try to provoke the issue, but it looks pretty straight forward.
The memmove to shift the joystick id array on disconnect isn't scaling the size by sizeof(SDL_JoystickID), likely corrupting the ids on disconnect.
It currently behaves like a locking key which is pressed
when Caps Lock is enabled and released when disabled. This
means that apps that trigger events on Caps Lock key down will
only fire these events every other time Caps Lock is pressed.
Lacky
It looks like refactoring of SDL2 internal API has broken SDL_RenderFillRect for DirectFB. In new version function SDL_RenderFillRect returns 0, but rectangle is not visible.
Replacing "count" with "len" in the argument list for SDL_memcpy in DirectFB_QueueFillRects fixes problem.
Jan Bujak
I wrote a new driver for my gamepad on Linux. I'd like SDL to support it out-of-box, as currently it just treats it as a generic joystick instead of a gamepad. From what I can see the only way to do that is to either 1) pick one of the already supported controllers' PID, VID and button layouts and have my driver send that (effectively lying that it's something else), or 2) submit a preconfigured, hardcoded mapping to SDL.
Both of those, in my opinion, are silly when we already have the Linux Gamepad Specification which standarizes this:
https://www.kernel.org/doc/html/v4.15/input/gamepad.html
Unfortunately SDL doesn't make use of it currently. So I've took it upon myself to add it; patch is in the attachments.
Basically what the patch does is that if SDL finds no built-it controller mappings for a given joystick it then asks the joystick backend to autodetect it, and that uses the relevant evdev bits to figure out which button/axis is which. (See the specs for more details.)
With this patch applied my own driver for my controller works out-of-box with SDL with no extra configuration and is correctly recognized as a gamepad; this is also going to be the case for any other driver which follows the Linux Gamepad Specification.
Arithmatic operations promote Uint8 to signed int. If the top bit of a
Uint8 is set, and it is left shifted 24 places, then the result is not
representable in a signed 32 bit int. This would be undefined behaviour
on systems where int is 32 bits.
It makes it clearer who owns the memory, and more reasonable to free it on
failure in the creating function.
(and, of course, pacifies static analysis.)
Manuel Alfayate Corchete
On the KMSDRM backend, there is no such thing as a desktop, yet some programs could (and DO) use SDL_GetGlobalMouseState().
So I think its good idea that, in KMSDRM, it returns the same mouse coordinates anyway as SDL_GetMouseState() would return. There is nothing else it could return, as far as I can understand, since there is no desktop anyway.
This small patch does precisely that.
Manuel Alfayate Corchete
The KMSDRM backend was doing things wrong because of some small (but important) misconceptions on how KMS/DRM works: to implement a largely broken non-vsync refresh mechanism, the SwapWindow() function was issuing new pageflips before previous ones had completed, thus causing EBUSY returns, buffer mismanagement, etc... resulting in general breakage on vsync disabling from apps, that would not allow vsync to work again without KMSDRM video re-initialization.
To further clarify, on most DRM drivers async pageflips are NOT working nowadays, so all issued pageflips will complete on next VBLANK, NOT ASAP (calling drmModePageFlip() with the DRM_MODE_PAGE_FLIP_ASYNC flag will return error).
The old code was assuming that can just issue a synchronous (=on VBLANK) pageflip and then pass a 0 timeout to the pull() function so we do not wait for the pageflip event, thinking that this will lead to correct non-vsynced screen updates from the program: That is plain wrong.
Each pageflip has to be waite before issuing a new one, ALWAYS. And if we do not support ASYNC pageflips on the DRM driver level, then we are forced to wait for the next VBLANK. There is no way around it.
I have also added many comments on the KMSDRM code. This is needed for future reference for me or others who may need to look at this code: KMS/DRM terminology regarding what SYNC and ASYNC mean in pageflip terms, and where to do certain things and why, is not trivial. It is not desirable or possible to invest time on researching the same concepts every time there is need to dive into this code. So please leave all these comments in the patch.
