Pointer Lock API

Pointer lock (en français Capture du curseur, précedement appelé mouse lock) permet d'obtenir des informations sur le déplacement de la souris par rapport au temps écoulé (autrement dit les deltas) et ne se cantonne donc pas seulement à la position absolue du curseur sur l'écran. Cette interface confère l'accès aux données brutes de la souris, permet de verrouiller la cible des évènements à un élément unique, retire les limites de distance dans une direction donnée et cache le curseur.

Cette API est utile pour les applications qui ont besoin d'être attentives aux infos renvoyées par la souris afin de controler des mouvements ou faire pivoter des objets sur leurs axes.

Les jeux 3D de type FPS (First Person Shooter), les outils de modelisation, les vidéos immersives ou encore les cartes satellites sont autant de candidats idéals. L'utilisateur peut en effet changer l'angle de vue en bougeant simplement sa souris et sans cliquer sur aucun bouton ce qui les laisse donc disponibles pour effectuer d'autres actions.

Comme Pointer lock continue de déclencher des évènements même quand le curseur est en dehors des limites du navigateur ou de l'écran, cela résoud les inconvénients précédents où l'utilisateur devait faire attention de ne pas cliquer par inadvertance sur une autre fenêtre.

Concepts de base

Pointer Lock partage des similtudes avec mouse capture. Mouse capture offre un flot ininterrompu d'évènements sur un élément cible quand la souris glisse mais s'arrete quand le bouton est relaché. Pour cette raison, Pointer lock diffère de la capture de souris sur les points suivants :

• Persistance. Pointer lock ne libère pas la souris tant qu'un appel explicite à l'API n'ait été effectué ou que l'utilisateur face un mouvement spécial.
• Ne se limite pas aux bordures du navigateur ou de l'écran.
• Continue de déclencher des évènements peu importe l'état des boutons de la souris.
• Cache le curseur.

Exemple

Le code qui suit présente comment mettre en place Pointer Lock dans une page web.

<button onclick="lockPointer();">Capture le!</button>
<div id="pointer-lock-element"></div>
<script>
// Note: au moment de la rédaction, seuls Mozilla et WebKit supportent Pointer Lock.

// L'élement qui sera mis en mode fullscreen et qui capturera le curseur.
var elem;

document.addEventListener("mousemove", function(e) {
  var movementX = e.movementX       ||
                  e.mozMovementX    ||
                  e.webkitMovementX ||
                  0,
      movementY = e.movementY       ||
                  e.mozMovementY    ||
                  e.webkitMovementY ||
                  0;

  // Affiche les valeurs de différence de mouvement de la souris relative au dernier appelle de l'événement.
  console.log("movementX=" + movementX, "movementY=" + movementY);
}, false);

function fullscreenChange() {
  if (document.webkitFullscreenElement === elem ||
      document.mozFullscreenElement === elem ||
      document.mozFullScreenElement === elem) { // Le caractère 'S' majuscule de l'ancien API. (note de traduction: ?)
    // L'élément est en plein écran, nous pouvons maintenant faire une requête pour capturer le curseur.
    elem.requestPointerLock = elem.requestPointerLock    ||
                              elem.mozRequestPointerLock ||
                              elem.webkitRequestPointerLock;
    elem.requestPointerLock();
  }
}

document.addEventListener('fullscreenchange', fullscreenChange, false);
document.addEventListener('mozfullscreenchange', fullscreenChange, false);
document.addEventListener('webkitfullscreenchange', fullscreenChange, false);

function pointerLockChange() {
  if (document.mozPointerLockElement === elem ||
      document.webkitPointerLockElement === elem) {
    console.log("Pointer Lock was successful.");
  } else {
    console.log("Pointer Lock was lost.");
  }
}

document.addEventListener('pointerlockchange', pointerLockChange, false);
document.addEventListener('mozpointerlockchange', pointerLockChange, false);
document.addEventListener('webkitpointerlockchange', pointerLockChange, false);

function pointerLockError() {
  console.log("Une erreur est survenue lors de la capture du curseur.");
}

document.addEventListener('pointerlockerror', pointerLockError, false);
document.addEventListener('mozpointerlockerror', pointerLockError, false);
document.addEventListener('webkitpointerlockerror', pointerLockError, false);

function lockPointer() {
  elem = document.getElementById("pointer-lock-element");
  // On débute par mettre l'élément en plein écran. L'implémentation actuelle
  // demande à ce que l'élément soit en plein écran (fullscreen) pour
  // pouvoir capturer le pointeur--c'est une chose qui sera probablement
  // modifiée dans le futur.
  elem.requestFullscreen = elem.requestFullscreen    ||
                           elem.mozRequestFullscreen ||
                           elem.mozRequestFullScreen || // Le caractère 'S' majuscule de l'ancienne API. (note de traduction: ?)
                           elem.webkitRequestFullscreen;
  elem.requestFullscreen();
}
</script>

Vue d'ensemble des méthodes/propriétées

L'API Pointer lock, semblable à l'API Fullscreen, étend les les éléments DOM en ajoutant une nouvelle méthode, requestPointerLock, qui est vendor-prefixed (la méthode est préfixé par le nom de l'éditeur de navigateur) pour l'instant. On l'utilise comme suit:

element.webkitRequestPointerLock(); // Chrome

element.mozRequestPointerLock(); // Firefox

Les implementations actuels de requestPointerLock sont fermenent liées à requestFullScreen et à l'API Fullscreen. Avant qu'un élément puissent capturer le cusreur, il faut d'abord qu'elle soit en pleine écran. Comme il a été démontré ci-haut, le processus de capture du curseur est asyncrone, avec des événements (pointerlockchange, pointerlockerror) indiquant le succès ou l'échec de la requête. Cela correspond à la façon dont l'API Fullscreen fonctionne, avec ça méthode requestFullScreen et ces événements fullscreenchange et fullscreenerror.

L'API Pointer lock étend aussi l'interface document, ajoutant à la fois une nouvelle propriété et une nouvelle méthode. La nouvelle propriété est utilisée pour avoir accès à l'élément qui capture actuellement le pointeur (s'il y en a un), et est nommée pointerLockElement qui, pour l'instant, est vendor-prefixed. La nouvelle méthode du document est exitPointerLock et, comme le nom l'indique, elle est utilisée pour sortir de l'état du curseur capturer.

La propriété pointerLockElement est utile pour déterminer si un élément capture actuelement le cuseur (par exemple, pour faire une vérfication booléaine) et aussi pour obtenir la référence de l'élément capturant, s'il y en a un. L'exemple qui suit les utilises tout les deux:

document.pointerLockElement = document.pointerLockElement    ||
                              document.mozPointerLockElement ||
                              document.webkitPointerLockElement;

// 1) Used as a boolean check--are we pointer locked?
if (!!document.pointerLockElement) {
  // pointer is locked
} else {
  // pointer is not locked
}

// 2) Used to access the pointer locked element
if (document.pointerLockElement === someElement) {
  // someElement is currently pointer locked
}

La méthode exitPointerLock du document est utilisée pour sortir le curseur de l'état capturée, et comme requestPointerLock, fonctionne de façon asyncrone en utilisant les événements pointerlockchange et pointerlockerror:

document.exitPointerLock = document.exitPointerLock    ||
                           document.mozExitPointerLock ||
                           document.webkitExitPointerLock;

function pointerLockChange() {
  document.pointerLockElement = document.pointerLockElement    ||
                                document.mozPointerLockElement ||
                                document.webkitPointerLockElement;

  if (!!document.pointerLockElement) {
    console.log("Still locked.");
  } else {
    console.log("Exited lock.");
  }
}

document.addEventListener('pointerlockchange', pointerLockChange, false);
document.addEventListener('mozpointerlockchange', pointerLockChange, false);
document.addEventListener('webkitpointerlockchange', pointerLockChange, false);

// Attempt to unlock
document.exitPointerLock();

pointerlockchange event

When the Pointer lock state changes—for example, when calling requestPointerLock, exitPointerLock, the user pressing the ESC key, etc.—the pointerlockchange event is dispatched to the document. This is a simple event and contains no extra data.

pointerlockerror event

When there is an error caused by calling requestPointerLock or exitPointerLock, the pointerlockerror event is dispatched to the document. This is a simple event and contains no extra data.

Extensions to mouse events

The Pointer lock API extends the normal MouseEvent with movement attributes.

partial interface MouseEvent {
    readonly attribute long movementX;
    readonly attribute long movementY;
};

Two new parameters to mouse events—movementX and movementY—provide the change in mouse positions. The values of the parameters are the same as the difference between the values of MouseEvent properties, screenX and screenY, which are stored in two subsequent mousemove events, eNow and ePrevious. In other words, the Pointer lock parameter movementX = eNow.screenX - ePrevious.screenX.

Locked state

When Pointer lock is enabled, the standard MouseEvent properties clientX, clientY, screenX, and screenY are held constant, as if the mouse is not moving. The movementX and movementY properties continue to provide the mouse's change in position. There is no limit to movementX and movementY values if the mouse is continuously moving in a single direction. The concept of the mouse cursor does not exist and the cursor cannot move off the window or be clamped by a screen edge.

Unlocked state

The parameters movementX and movementY are valid regardless of the mouse lock state, and are available even when unlocked for convenience.

When the mouse is unlocked, the system cursor can exit and re-enter the browser window. If that happens, movementX and movementY could be set to zero.

iframe limitations

Pointer lock can only lock one iframe at a time. If you lock one iframe, you cannot try to lock another iframe and transfer the target to it; Pointer lock will error out. To avoid this limitation, first unlock the locked iframe, and then lock the other.

While iframes work by default, "sandboxed" iframes block Pointer lock. The ability to avoid this limitation, in the form of the attribute/value combination <iframe sandbox="allow-pointer-lock">, is expected to appear in Chrome soon.

Spécifications

Browser compatibility

* Requires the feature be enabled in about:flags or Chrome started with the --enable-pointer-lock flag.

Voir aussi

MouseEvent