[Ohrrpgce] Mouse locking; gfx_directx

[Ralph Versteegen]

On 1 October 2010 18:07, Jay Tennant <hierandel8 at crazyleafgames.com> wrote:
>> From: James Paige <Bob at HamsterRepublic.com>
>> Sent: Thursday, September 30, 2010 10:41 AM
>>
>> On Fri, Oct 01, 2010 at 04:19:11AM +1300, Ralph Versteegen wrote:
>> > Jay's recent work to rewrite the mouse handling in gfx_directx means
>> > that it's now nearly time to make it the default backend on Windows,
>> > after a couple minor things have been sorted out.
>> >
>> > But the point of this email is mouse locking. My idea of locking the
>> > mouse to the window in-game by default was very confused; I'd written
>> > a game long ago where you scroll the camera by moving the mouse
>> > against the screen edge, and this is something done in many games.
>> > This works badly if the mouse isn't locked (actually, the more typical
>> > solution is to play in fullscreen). However making locking the default
>> > was extremely misguided because I've never seen any other OHR game do
>> > this. I think I've seen mouseregion used though (in Slimes?) This was
>> > rushed before the last release; now I agree that locking is annoying
>> >
>> > The mouseregion(-1,-1,-1,-1) command can be used to turn off locking.
>> > I suggest making non-locked the default and making this command a
>> > no-op.
>>
>> This is a good plan.
>>
>> > Backends could optionally continue to allow toggle locking with
>> > ScrollLock (does this really need to be advertised in the window
>> > title?)
>>
>> Escaping from the mouse lock needs to be advertised in the window title,
>> but getting into the lock does not need to be advertised.
>>
>> > I'm not sure we really need a plotscript command to turn on
>> > locking at all. But mouse region also allows setting a smaller
>> > rectangular mouse region. I think we can get away with just clipping
>> > the reported mouse position, but still letting it leave the screen.
>>
>> Full-screen seems like a good enough workaround for anybody who wants
>> mouse-locking.
>>
>> > Whenever we get that mythical configuration menu, we can stick an
>> > option for mouse locking in there.
>> >
>> > Jay kept the ScrollLock key in gfx_directx, but now it does something
>> > different: it freezes mouse input and unhides the mouse cursor. It's
>> > kind of useful because it's not otherwise possible to click and drag
>> > the window frame, but that sounds like a bug. Other than that, is it
>> > useful?
>
> Oops! I didn't understand the purpose of io_mouserect() correctly. Wait,
> are we talking about io_mouserect()?

Actually, I completely forgot we had io_mouserect to specify clipping
rectangles, rather than just some function to toggle clipping to the
window!

> I actually did not change the functionality of the ScrollLock key between
> v1.7 and v1.8 of the gfx_directx backend (gfx_directx_old.dll and
> gfx_directx.dll). Do you mean I interpreted it differently altogether?

Well yes, it's completely different. Not because you changed
ScrollLock, but because you got rid of clipping.

The confusion arises because gfx_directx did not support not clipping
previously, while the other backends all did, so we came up with a
crappy plan to handle that.

> Part of the confusion backend-side was the function names and purpose.
> In particular of mouse input, io_setmousevisibility() and io_mouserect()
> are the prime functions for acquiring mouse input. As I understand it,
> io_setmousevisibility() was to acquire the mouse for input. io_mouserect()
> was not well understood, so I ignored it.
>
> If io_mouserect() was to lock the mouse to the window (and obviously
> acquire the mouse for input), then managing state becomes shaky
> guesswork. It'd probably be better if the engine managed whether
> the mouse is an intended acquisition for input, and whether it is also
> supposed to be locked to the window rect.

The purpose of io_mouserect was only to enable/disable a clipping region.
io_setmousevisibility was for hiding/showing the cursor.
There wasn't any function to "acquire" the mouse, rather it was
assumed that the mouse state could be polled with the other io
functions without that having any implications/requirements for the
state of the backend.

> I elect we present an interface in replacement of io_setmousevisibility()
> and io_mouserect(): gfx_AcquireMouse(). Here's the prototype in c++:
>
> enum gfx_MouseAcquisition {
> gfx_MA_Release = 0x0,
> gfx_MA_Acquire = 0x1,
> gfx_MA_Lock = 0x2,
> };
>
> int gfx_AcquireMouse(gfx_MouseAcquisition ma);
>
> The value for gfx_MA_Release drops mouse input altogether. gfx_MA_Acquire
> is the equivalent to io_setmousevisibility(), or acquiring the mouse for
> input. gfx_MA_Lock would be the equivalent to io_mouserect(), or locking
> the mouse to the window and acquiring it for input.

Replacing these functions with gfx_AcquireMouse sounds like a good
idea, but I don't agree with having to hide the mouse cursor to be
able to read input. Why does the mouse have to be acquired to read its
state? Why have a way to freeze mouse input from the abckend, when
that can be handled more simply in allmodex.bas?

There are one or two other changes to mouse input I'd like to see. In
particular I'd like to know when the curosr is off the window, rather
than just freezing it at its last position (at least one of fb and sdl
probably will not be able to support this, but that's acceptable)

> Whenever the engine needs the mouse input, call
> gfx_AcquireMouse(gfx_MA_Acquire). If the engine needs the mouse input and
> needs to restrict the mouse to the window, call
> gfx_AcquireMouse(gfx_MA_Lock).
>
> This also should be legal:
>
> gfx_AcquireMouse(gfx_MA_Lock); //lock and acquire
> gfx_AcquireMouse(gfx_MA_Acquire); //only acquire
>
> in order to free the mouse from the window, but maintain
> mouse input.
>
> The engine should really maintain the "clipped" mouse coordinates, perhaps
> by doing a floating point scale of reported mouse coordinates (from
> io_getmouse()) in the range of (0,0)-(319,199). There's no reason the
> backend should be calculating those values.

The engine can emulate a clip rectangle by moving the mouse, but
that's something that works much better when done in the backend.
Anyway, I'm quite happy with having no support for it in gfx_directx,
disabling the existing support in the other backends for now, and
maybe coming back to it later when we have a way to enable mouse
clipping. All this forward planning is starting to become too much for
me.

>> I haven't tested it myself yet (gotta go dig up a Windows box
>> somewhere)...
>
>
>
>