Add `set_cursor_lock` and distinguish between grabbing (confining) cursor and locking cursor

[alvinhochun]

Currently there is a set_cursor_grab API which is supposed to confine the cursor movement to within the window client area, but sometimes the user may want to lock the cursor to the current position instead (e.g. for camera control). Also, the web platform does not support confining the cursor but does support locking the cursor with the Pointer Lock API. Therefore, I would suggest adding a new API set_cursor_lock to lock the cursor to the current position, and fixing the set_cursor_grab API to actually confine the cursor on all supported platforms.

A better alternative would be to change set_cursor_grab to take an enum CursorGrabState { Off, Confine, Lock } so that only one of the two cursor grabbing modes can be active at once.

	set_cursor_grab / Confine	set_cursor_lock / Lock
Windows	Supported, already implemented	Supported, unimplemented (could reuse cursor grab impl.)
Linux (X11)	Supported, already implemented	Unknown (could just move the mouse after mouse moved?)
Linux (Wayland)	Supported, unimplemented (#1678)	Supported, already implemented for set_cursor_grab
macOS	Supported, unimplemented (#1093)	Supported, already implemented for set_cursor_grab
iOS	Not supported	Not supported
Android	Not supported	Not supported
Web	Not supported	Supported, unimplemented (#1674)

[kchibisov]

After thinking about this issue I wonder how those functions could relate to each other?

By that I mean if I do set_cursor_grab(true), what the following set_cursor_lock(true) should do? Vise versa?

So we can make them

• Mutually exclusive
• Lock > grab, meaning if the cursor is locked, grab won't do anything until unlock. And on unlock the pending grab will apply.

I personally think that the second variant is something more logical, however the first option is also worth considering.

The point here that such behavior must be explicitly defined, so we should agree on that before hand.

[alvinhochun]

If we want them to be mutually exclusive, then perhaps the API should be changed to something like this?

fn set_cursor_grab(&self, grab_mode: CursorGrabMode) -> Result<CursorGrabState, ExternalError>;
fn get_cursor_grab(&self) -> CursorGrabState;

enum CursorGrabMode {
    Off,
    Confine,
    Lock,
    ConfineOrLock,
    LockOrConfine,
}

enum CursorGrabState {
    Off,
    Confine,
    Lock,
}

This would also handle the case where the user may want either confine or lock without having to manually handle the Err and call the other function.

[kchibisov]

This would also handle the case where the user may want either confine or lock without having to manually handle the Err and call the other function.

Yeah, but the point is that behavior for both is very different and you need a special handling for lock, but not for confine, so in the end I feel like I'd suggest to go without mutually exclusive things, but I don't really have a good opinion on that, since I've never used both of them other than testing on examples, so the real usecase is not something I can speak for.

[alvinhochun]

Thinking about it for a bit, it seems better to have them mutually exclusive and controlled via one common API, since they are quite related to each other. Instead of having two states in which one would affect another, keeping them as one state seems to be clearer. If the user would want to go back to confine after releasing lock, they can always explicitly request for that.

Consider getting the current cursor grab state - there isn't an existing getter but we really should add one. If both cursor grab and cursor lock are enabled, then how would the user tell which one is really active? They would have to check for both and derive that cursor grab is not active because cursor lock overrides the cursor grab. If instead they are one single API then it will be more straightforward.

[chrisduerr]

I'm strongly in favor of using an enum with a single endpoint for this. I don't think anything else makes much sense.

I'm not sure if I'd support ConfineOrLock or LockOrConfine though, that just seems a bit odd from an API design perspective. Maybe a single "any lock mode" enum option would be fine though. Generally users should be aware of what platforms they're running on, so they should pass the correct things at compile time anyways, instead of relying in runtime checks.

[alvinhochun]

I'm not sure if I'd support ConfineOrLock or LockOrConfine though, that just seems a bit odd from an API design perspective. Maybe a single "any lock mode" enum option would be fine though. Generally users should be aware of what platforms they're running on, so they should pass the correct things at compile time anyways, instead of relying in runtime checks.

I realized that these two options don't really make sense. If we assume that cursor lock will be supported on all platforms that also support confine, then those who want cursor lock can just request it without worrying about fallback. Those who want confine would most likely still want to be using the absolute cursor position, so now I don't really see a potential use case of falling back to cursor lock.

[kchibisov]

The users may perform or just by handling Result, so having enum for that with 3 variants(none,lock,confine) is fine.

[francesco-cattoglio]

I really like the idea of a "lock cursor" API, since there are many use cases for it (FPS camera and input sliders are the first two that come to my mind), and I like it being in the same API of cursor grab, it does make sense to me. I wonder if cursor hiding should be part of the same API somehow, since web dictates cursor hiding on mouse lock.
Just a quick question though: when the cursor is locked, what kind of events would still be generated? My initial guest would be only Device ones, and no Window events. Am I correct?

[kchibisov]

Right, only device events, and I don't really want cursor hiding in the API of the locking, since it's not like that on some platforms, and I don't understand what the point of always hiding the cursor. if the user wants they can hide it by themselves.