Compare Revisions

Pointer Lock API

Revision 301681:

Revision 301681 by Steffen on

Revision 319203:

Revision 319203 by dgash on

Title:
Pointer Lock API
Pointer Lock API
Slug:
API/Pointer_Lock_API
API/Pointer_Lock_API
Tags:
"mouse lock","NeedsEditorialReview","Games"
"mouse lock","NeedsEditorialReview","Games"
Content:

Revision 301681
Revision 319203
n11      <a class="external" href="http://dvcs.w3.org/hg/webevents/rn11      Pointer lock (formerly called mouse lock) provides input me
>aw-file/default/mouse-lock.html" title="http://dvcs.w3.org/hg/web>thods based on the movement of the mouse over time (i.e., deltas)
>events/raw-file/default/mouse-lock.html">Pointer Lock</a> (former>, not just the absolute position of the mouse cursor. It gives yo
>ly called mouse lock) provides input methods based on the movemen>u access to raw mouse movement, locks the target of mouse events 
>t of the mouse over time (i.e., deltas), not just the absolute po>to a single element, eliminates limits on how far mouse movement 
>sition of the mouse cursor. It gives you access to raw mouse move>can go in a single direction, and removes the cursor from view.
>ment, locks the target of mouse events to a single element, elimi 
>nates limits on how far mouse movement can go in a single directi 
>on, and removes the cursor from view. 
12    </p>
13    <p>12    </p>
13    <p>
14      This API is useful for applications that require significan14      This API is useful for applications that require significan
>t mouse input to control movements, rotate objects, and change en>t mouse input to control movements, rotate objects, and change en
>tries. It is particularly essential for highly visual application>tries. It is particularly essential for highly visual application
>s, such as those that use first-person perspective as well as 3D >s, such as those that use first-person perspective, as well as 3D
>views and modeling.> views and modeling.
n20      Pointer Lock lets you continue to access mouse events even n20      Pointer lock lets you access mouse events even when the cur
>when the cursor goes past the boundary of the browser or screen. >sor goes past the boundary of the browser or screen. For example,
>For example, your users can continue to rotate or manipulate a 3D> your users can continue to rotate or manipulate a 3D model by mo
> model by moving the mouse without end. Without mouse lock, the r>ving the mouse without end. Without Pointer lock, the rotation or
>otation or manipulation stops the moment the mouse cursor reaches> manipulation stops the moment the pointer reaches the edge of th
> the edge of the browser or screen. Game players would be particu>e browser or screen. Game players will be particularly thrilled b
>larly thrilled by this feature, as they can feverishly click butt>y this feature, as they can feverishly click buttons and swipe th
>ons and swipe the mouse cursor back and forth without worrying ab>e mouse cursor back and forth without worrying about leaving the 
>out leaving the game play area and accidentally clicking another >game play area and accidentally clicking another application that
>application that would take mouse focus away from the game. A tra> would take mouse focus away from the game. A tragedy!
>gedy! 
n23      Basic Conceptsn23      Basic concepts
24    </h2>
25    <p>24    </h2>
25    <p>
26      Pointer&nbsp;Lock is related to <a href="/en/DOM/element.se26      Pointer&nbsp;Lock is related to <a href="/en/DOM/element.se
>tCapture" title="element.setCapture">mouse capture</a>. Mouse cap>tCapture" title="element.setCapture">mouse capture</a>. Mouse cap
>ture provides continued delivery of events to a target element wh>ture provides continued delivery of events to a target element wh
>ile a mouse is being dragged, but it stops when the mouse button >ile a mouse is being dragged, but it stops when the mouse button 
>is released. Pointer Lock is different from mouse capture in the >is released. Pointer lock is different from mouse capture in the 
>following ways:>following ways:
n29      <li>It is persistent.&nbsp;Pointer Lock does not release thn29      <li>It is persistent.&nbsp;Pointer lock does not release th
>e mouse until an explicit API call or the user uses a specific re>e mouse until an explicit API call is made or the user uses a spe
>lease gesture.>cific release gesture.
n118      Method/Properties&nbsp;overviewn118      Method/properties&nbsp;overview
119    </h2>
120    <p>119    </h2>
120    <p>
121      The Pointer Lock API, similar to the Fullscreen API, extend121      The Pointer lock API, similar to the Fullscreen API, extend
>s DOM elements by adding two new methods, <code>requestPointerLoc>s DOM elements by adding a new method, <code>requestPointerLock</
>k</code>, which is vendor prefixed for now.&nbsp; You write it as>code>, which is vendor-prefixed for now. You write it as follows:
> follows: 
n129      Current implementations of <code>requestPointerLock</code> n129      Current implementations of <code>requestPointerLock</code> 
>are tightly bound to <code>requestFullScreen</code> and the Fulls>are tightly bound to <code>requestFullScreen</code> and the Fulls
>creen API.&nbsp; Before an element can be pointer locked, it must>creen API.&nbsp; Before an element can be pointer locked, it must
> first enter the fullscreen state.&nbsp; As was demonstrated abov> first enter the fullscreen state.&nbsp; As demonstrated above, t
>e, the process of locking the pointer is asynchronous, with event>he process of locking the pointer is asynchronous, with events (<
>s (<code>pointerlockchange</code>, <code>pointerlockerror</code>)>code>pointerlockchange</code>, <code>pointerlockerror</code>) ind
> indicating the success and failure of the request.&nbsp; This ma>icating the success or failure of the request.&nbsp; This matches
>tches how the Fullscreen API works, with its <code>requestFullScr> how the Fullscreen API works, with its <code>requestFullScreen</
>een</code> method and <code>fullscreenchange</code> and <code>ful>code> method and <code>fullscreenchange</code> and <code>fullscre
>lscreenerror</code> events.>enerror</code> events.
130    </p>
131    <p>130    </p>
132      The Pointer Lock API also extends the <code>document</code>
> interface, adding both a new property and a new method.&nbsp; Th 
>e new property is used for accessing the currently locked element 
> (if any), and is named <code>pointerLockElement</code>, which is 
> vendor prefixed for now.&nbsp; The new method on <code>document< 
>/code> is <code>exitPointerLock</code>, and just as the name impl 
>ies, it is used to exit pointer lock. 
133    </p>131    <p>
132      The Pointer lock API also extends the <code>document</code>
 > interface, adding both a new property and a new method.&nbsp; Th
 >e new property is used for accessing the currently locked element
 > (if any), and is named <code>pointerLockElement</code>, which is
 > vendor-prefixed for now. The new method on <code>document</code>
 > is <code>exitPointerLock</code>&nbsp;and, as the name implies, i
 >t is used to exit Pointer lock.
134    <p>133    </p>
135      The <code>pointerLockElement</code> property is useful for 134    <p>
>determining whether or not any element is currently pointer locke 
>d (e.g., for doing a boolean check) and also for obtaining a refe 
>rence to the locked element, if any.&nbsp; Here is an example of  
>both uses: 
135      The <code>pointerLockElement</code> property is useful for 
 >determining if any element is currently pointer locked (e.g., for
 > doing a boolean check) and also for obtaining a reference to the
 > locked element, if any. Here is an example of both uses:
n185      When the Pointer Lock state changes, for example, when calln185      When the Pointer lock state changes—for example, when calli
>ing <code>requestPointerLock</code>, <code>exitPointerLock</code>>ng <code>requestPointerLock</code>, <code>exitPointerLock</code>,
>, the user pressing the ESC key, etc.the&nbsp;<code>pointerlock> the user pressing the ESC key, etc.the&nbsp;<code>pointerlockch
>change</code> event is dispatched to the <code>document</code>.&n>ange</code> event is dispatched to the <code>document</code>.&nbs
>bsp; This is a simple event and contains no extra data.>p; This is a simple event and contains no extra data.
n203      The&nbsp;Pointer&nbsp;Lock API extends the normal <code>Moun203      The&nbsp;Pointer lock API extends the normal <code>MouseEve
>seEvent</code> with movement attributes.>nt</code> with movement attributes.
n215      Two new parameters to mouse events—<code>movementX</code>&nn215      Two new parameters to mouse events—<code>movementX</code>&n
>bsp;and&nbsp;<code>movementY</code>—provide the change in mouse p>bsp;and&nbsp;<code>movementY</code>—provide the change in mouse p
>ositions. The values of the parameters are the same as the differ>ositions. The values of the parameters are the same as the differ
>ence between the values of&nbsp;<a href="/en/DOM/MouseEvent" titl>ence between the values of&nbsp;<a href="/en/DOM/MouseEvent" titl
>e="en/DOM/Event/UIEvent/MouseEvent"><code>MouseEvent</code></a>&n>e="en/DOM/Event/UIEvent/MouseEvent"><code>MouseEvent</code></a>&n
>bsp;properties,&nbsp;<code>screenX</code>&nbsp;and&nbsp;<code>scr>bsp;properties,&nbsp;<code>screenX</code>&nbsp;and&nbsp;<code>scr
>eenY</code>, which are stored in two subsequent&nbsp;<code>mousem>eenY</code>, which are stored in two subsequent&nbsp;<code>mousem
>ove</code>&nbsp;events,&nbsp;<code>eNow</code>&nbsp;and&nbsp;<cod>ove</code>&nbsp;events,&nbsp;<code>eNow</code>&nbsp;and&nbsp;<cod
>e>ePrevious</code>. In other words, the Pointer Lock parameter:&n>e>ePrevious</code>. In other words, the Pointer lock parameter&nb
>bsp;<code>movementX = eNow.screenX - ePrevious.screenX</code>.>sp;<code>movementX = eNow.screenX - ePrevious.screenX</code>.
n221      When pointer&nbsp;lock is enabled, the standard <code>Mousen221      When Pointer&nbsp;lock is enabled, the standard <code>Mouse
>Event</code> properties, <code>clientX</code>, <code>clientY</cod>Event</code> properties&nbsp;<code>clientX</code>, <code>clientY<
>e>, <code>screenX</code>, and <code>screenY</code> are held const>/code>, <code>screenX</code>, and <code>screenY</code> are held c
>ant—as if the mouse is not moving. The <code>movementX</code> and>onstantas if the mouse is not moving. The <code>movementX</code
> <code>movement</code>Y properties continue to provide the mouse'>> and <code>movement</code>Y properties continue to provide the m
>s change in position. There is no limit to <code>movementX</code>>ouse's change in position. There is no limit to <code>movementX</
> and <code>movement</code>Y values if the mouse is continuously m>code> and <code>movement</code>Y values if the mouse is continuou
>oving in a single direction. The concept of the mouse cursor does>sly moving in a single direction. The concept of the mouse cursor
> not exist and the cursor cannot move off the window or be clampe> does not exist and the cursor cannot move off the window or be c
>d by a screen edge.>lamped by a screen edge.
n227      Parameters,&nbsp;<code>movementX</code>&nbsp;and&nbsp;<coden227      The parameters&nbsp;<code>movementX</code>&nbsp;and&nbsp;<c
>>movementY</code>&nbsp;are valid regardless of&nbsp;mouse&nbsp;lo>ode>movementY</code>&nbsp;are valid regardless of the mouse&nbsp;
>ck state, and are available even when unlocked for convenience.>lock state, and are available even when unlocked for convenience.
nn231    </p>
232    <h2>
233      iframe limitations
234    </h2>
235    <p>
236      Pointer lock can only lock one iframe at a time. If you loc
 >k one iframe, you cannot try to lock another iframe and transfer 
 >the target to it; Pointer lock will error out. To avoid this, fir
 >st unlock the locked iframe, and then lock the other.
237    </p>
238    <p>
239      While iframes work by default, "sandboxed" iframes block Po
 >inter lock. The ability to avoid this limitation, in the form of 
 >the attribute/value combination <code>&lt;iframe sandbox="allow-p
 >ointer-lock"&gt;</code>, is expected to appear in Chrome soon.
t267                Targeting 22{{ property_prefix("webkit") }}*t276                Targeting 23{{ property_prefix("webkit") }}*

Back to History