Pointer Lock API

Pointer Lock partage des similtudes avec la capture de souris. La capture de souris offre un flot ininterrompu d'évènements sur un élément cible quand la souris glisse mais s'arrête 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'a pas été effectué ou que l'utilisateur n'a pas fait un mouvement spécifique.
• 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.

Cette section fournit une brève description de chaque propriété et méthode associée à la spécification de Pointer Lock.

L'API Pointer lock, de manière similaire à l'API Fullscreen, étend les les éléments DOM en ajoutant une nouvelle méthode, requestPointerLock(). Comme le préfixe fournisseur a récemment été retiré, vous devriez utiliser la syntaxe ci-dessous, par exemple pour demander un verrouillage deu pointeur sur un élément canvas:

canvas.requestPointerLock =
  canvas.requestPointerLock ||
  canvas.mozRequestPointerLock ||
  canvas.webkitPointerLockElement;

canvas.requestPointerLock();

L'API Pointer Lock étend également l'interface Document, ajoutant à la fois une nouvelle propriété et une nouvelle méthode. La propriété pointerLockElement est utilisée pour accéder à l'élément actuellement verrouillé (s'il y en a). La méthode exitPointerLock() est utilisée pour libérer le verrou du pointeur.

La propriété pointerLockElement est utile pour déterminer si un élément est actuellement verrouillé (pour une vérification booléenne par exemple) et également pour obtenir une référence vers l'élément s'il existe.

Voici un exemple d'utilisation de pointerLockElement:

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

// 1) Utiliser une vérification booléenne--le pointeur est-il verrouillé?
if (!!document.pointerLockElement) {
  // pointeur verrouillé
} else {
  // pointeur non verrouillé
}

// 2) Accéder à l'élément verrouillé
if (document.pointerLockElement === someElement) {
  // someElement est l'élément sur lequel le pointeur est verrouillé
}

La méthode Document.exitPointerLock() est utilisée pour libérer le verrouillage du pinteur, et, comme requestPointerLock, marche de manière asynchrone, on utilise les événements pointerlockchange et pointerlockerror, que vous verrez plus en détails ci-dessous.

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

// Essaie de déverrouiller
document.exitPointerLock();

Quand l'état de verrouillage du pointeur change — par exemple quand on appelle requestPointerLock(), exitPointerLock(), que l'utilisateur presse la touche ECHAP, etc.—l'événement pointerlockchange est envoyé au document. C'est un simple événement qui ne contient pas de données supplémentaires.

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

function pointerLockChange() {
  if (!!document.pointerLockElement) {
    console.log("Verrouillé.");
  } else {
    console.log("Non verrouillé.");
  }
}

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

Quand une erreur est causée par l'appel de requestPointerLock() ou exitPointerLock(), l'événement pointerlockerror est envoyé au document. C'est un simple événement qui ne contient pas de données supplémentaires.

document.addEventListener("pointerlockerror", lockError, false);
document.addEventListener("mozpointerlockerror", lockError, false);
document.addEventListener("webkitpointerlockerror", pointerLockChange, false);

function lockError(e) {
  alert("Pointer lock failed");
}

L'API Pointer lock étend l'interface MouseEvent normale avec les attributs de mouvement. Deux nouveaux attributs sont ajoutés aux événements de souris —movementX et movementY— fournissant le changement de position de la souris. Ces paramètres ont pour valeur les différences entre les valeurs des propriétés de screenX / screenY stockées dans les événements mousemove, eNow et ePrevious. En d'autres termes, movementX = eNow.screenX - ePrevious.screenX.

Quand le verrouillage du pointeur est activé, les propriétés standard clientX, clientY, screenX, et screenY sont gardées constantes, comme si la souris ne bougeait pas. Les propriétés movementX et movementY continuent de fournir le changement de position de la souris. Il n'y a pas de limite aux valeurs movementX et movementY, si la souris continue de bouger toujours dans la même direction. Le curseur de la souris n'existe pas et il ne peut pas sortir de la fenêtre ou être bloqué par un bord de l'écran.

Les paramètres movementX et movementY sont disponibles quel que soit l'état de la souris, verrou ou non.

Quand la souris est déverrouillée, il est possible que le curseur soit en dehors de la fenêtre et il est alors remis automatiquement à l'intérieur. Si cela arrive, movementX et movementY sont définis à zéro.

Nous avons écrit une démo de verrouillage de pointer pour vous montrer comment l'utiliser pour mettre en place un système de contrôle simple (voir le code source). La démo ressemble à ça:

Cette démo utilise JavaScript pour dessiner une balle dans un élément <canvas>. Quand vous cliquez sur le canvas, le verrouillage du pointeur est utilisé pour supprimer le curseur de la souris à l'écran et vous permettre de déplacer la balle avec la souris. Voyons comment cela fonctionne.

On définit les positions initiales x et y sur le canvas:

var x = 50;
var y = 50;

Les méthodes de verrouillage de pointeur sont préfixées dans les anciennes versions des navigateurs, on prend donc en compte les différentes implémentations des navigateurs:

canvas.requestPointerLock =
  canvas.requestPointerLock ||
  canvas.mozRequestPointerLock ||
  canvas.webkitRequestPointerLock;

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

Maintenant, on définit un gestionnaire d'événement qui appelle la méthode requestPointerLock() quand le canvas est cliqué, ce qui déclenche le verrouillage du pointeur.

canvas.onclick = function () {
  canvas.requestPointerLock();
};

Et maintenant le gestionnaire d'événement pour le verrouillage: pointerlockchange. Quand cet événement se déclenche, on appelle lockChangeAlert() pour gérer le changement.

// Gestionnaire d'événement de changement d'état du verrouilllage pour les différents navigateurs
document.addEventListener("pointerlockchange", lockChangeAlert, false);
document.addEventListener("mozpointerlockchange", lockChangeAlert, false);
document.addEventListener("webkitpointerlockchange", lockChangeAlert, false);

La fonction suivante vérifie si la propriété pointLockElement est sur notre canvas. Si c'est le cas, on attache un gestionnaire d'événement pour gérer les mouvements de la souris avec la fonction updatePosition(). Sinon, elle enlève le gestionnaire d'événement.

function lockChangeAlert() {
  if (document.pointerLockElement === canvas) {
    console.log("The pointer lock status is now locked");
    document.addEventListener("mousemove", updatePosition, false);
  } else {
    console.log("The pointer lock status is now unlocked");
    document.removeEventListener("mousemove", updatePosition, false);
  }
}

La fonction updatePosition() met à jour la position de la balle sur le canvas (les valeurs x et y), et inclut également des instructions if() pour vérifier si la balle est sortie des bords du canvas. Dans ce cas, la balle se ressort au bord opposé. Elle vérifie également si un appel à requestAnimationFrame() a été effectué et si ce n'est pas le cas, l'appelle pour qu'elle déclenche la fonction canvasDraw() et mette à jour le canvas. Un tracker est mis en place pour afficher les valeurs X et Y à l'écran, pour référence.

var tracker = document.getElementById("tracker");

var animation;
function updatePosition(e) {
  x += e.movementX;
  y += e.movementY;
  if (x > canvas.width + RADIUS) {
    x = -RADIUS;
  }
  if (y > canvas.height + RADIUS) {
    y = -RADIUS;
  }
  if (x < -RADIUS) {
    x = canvas.width + RADIUS;
  }
  if (y < -RADIUS) {
    y = canvas.height + RADIUS;
  }
  tracker.textContent = "X position: " + x + ", Y position: " + y;

  if (!animation) {
    animation = requestAnimationFrame(function () {
      animation = null;
      canvasDraw();
    });
  }
}

La fonction canvasDraw() affiche la balle aux position x et y en cours:

function canvasDraw() {
  ctx.fillStyle = "black";
  ctx.fillRect(0, 0, canvas.width, canvas.height);
  ctx.fillStyle = "#f00";
  ctx.beginPath();
  ctx.arc(x, y, RADIUS, 0, degToRad(360), true);
  ctx.fill();
}

Le verrouilage du pointeur ne peut concerner qu'une seule iframe à la fois. Quand vous verrouillez une iframe, vous ne pouvez pas essayer de verrouiller une autre iframe et y transférer la cible; une erreur sera levée. Pour éviter cette limitation, déverrouillez d'abord la première iframe, puis verrouillez la seconde.

Tandis que cela fonctionne pour les iframes par défaut, les iframes en "sandbox" bloquent le verrouillage. La possibilité d'éviter cette limitation, sous la forme de la combinaison attribut/valeur <iframe sandbox="allow-pointer-lock">, devrait bientôt apparaître dans Chrome.

• MouseEvent