Blitz3D+ Command Reference

MouseXSpeed ( )

Parameters

None.

Description

Returns how far the mouse has moved horizontally since the last time you asked.

This is relative mouse movement, and it is the command behind mouse-look. Where MouseX gives you a position that stops at the edge of the screen, MouseXSpeed keeps handing out movement for as long as the player keeps sliding the mouse, which is exactly what a first-person camera or an endlessly spinning turntable needs. The classic pattern is to turn the camera by MouseXSpeed()*sensitivity each frame and warp the pointer back to the middle of the screen with MoveMouse.

The value is the difference since your previous call to this same command, not since the previous frame, so it only makes sense if you call it exactly once per loop. Call it twice and the second call reports the movement that happened between the two calls, which is usually zero. Skip a few frames and the value you finally get is the whole movement that piled up in the meantime.

Because MoveMouse also updates the internal reference point, warping the pointer back to the centre does not produce a phantom jump on the next call - the movement you get is the player's, not yours.

Gotcha: the first call after your program starts, or after the window regains focus, can report a large jump as the reference point catches up. Read and discard one value when you enter mouse-look mode. Pair with HidePointer so the arrow does not sit in the middle of your view.

See also: MouseYSpeed, MouseZSpeed, MouseX, MoveMouse, HidePointer.

Example

; MouseXSpeed Example
; -------------------

Graphics 640,480,0,2
SetBuffer BackBuffer()

; Hide the Windows pointer - we steer with movement deltas instead
HidePointer

aim_x#=320
aim_y#=240

While Not KeyDown(1)

    Cls

    ; MouseXSpeed returns how far the mouse moved horizontally since
    ; the last call (MouseYSpeed is its vertical partner).
    xs=MouseXSpeed()
    ys=MouseYSpeed()

    ; FPS-style aiming: re-centre the pointer every frame and steer
    ; the crosshair with the deltas - the pointer itself can never
    ; get stuck at the edge of the screen.
    MoveMouse 320,240

    aim_x=aim_x+xs
    aim_y=aim_y+ys

    ; Wrap the crosshair at the window edges
    If aim_x<0 Then aim_x=aim_x+640
    If aim_x>639 Then aim_x=aim_x-640
    If aim_y<0 Then aim_y=aim_y+480
    If aim_y>479 Then aim_y=aim_y-480

    ; Crosshair
    Color 255,255,0
    Oval aim_x-10,aim_y-10,20,20,False
    Line aim_x-14,aim_y,aim_x+14,aim_y
    Line aim_x,aim_y-14,aim_x,aim_y+14

    Color 255,255,255
    Text 0,0,"Move the mouse to drift the crosshair (no screen edges)   Esc: exit"
    Text 0,20,"MouseXSpeed() this frame: "+xs
    Text 0,40,"MouseYSpeed() this frame: "+ys

    Flip

Wend

End

Index