API Pointer Lock

Conceptos bsicos

Pointer Lock est relacionado con mouse capture. Mouse capture proporciona una entrega continua de eventos a un elemento de destino mientras se arrastra el mouse, pero se detiene cuando se suelta el botn del mouse. Pointer Lock se diferencia de la captura de mouse en lo siguiente:

• Es persistente: Pointer Lock no libera el mouse hasta que se realiza una llamada explcita a la API o el usuario utiliza un gesto de liberacin especfico.
• No est limitado por los lmites del navegador o de la pantalla.
• Contina enviando eventos independientemente del estado del botn del mouse.
• Oculta el cursor.

Descripcin de mtodos/propiedades

Esta seccin proporciona una breve descripcin de cada propiedad y mtodo relacionado con la especificacin de bloqueo de puntero.

requestPointerLock()

La API Pointer Lock, similar a la Fullscreen API, ampla los elementos DOM aadiendo un nuevo mtodo, requestPointerLock(). El siguiente ejemplo solicita el bloqueo de puntero en un elemento <canvas>:

canvas.addEventListener("click", async () => {
  await canvas.requestPointerLock();
});

Los sistemas operativos activan la aceleracin del ratn por defecto, lo que resulta til cuando a veces se desea un movimiento lento y preciso (piensa en que podras utilizar un paquete de grficos), pero tambin quieres mover grandes distancias con un movimiento ms rpido del ratn (piensa en el desplazamiento y la seleccin de varios archivos). Sin embargo, para algunos juegos de perspectiva en primera persona, se prefieren los datos de entrada brutos del ratn para controlar la rotacin de la cmara, donde el mismo movimiento de distancia, rpido o lento, da como resultado la misma rotacin. Segn los jugadores profesionales, esto mejora la experiencia de juego y aumenta la precisin.

Para desactivar la aceleracin del ratn a nivel de sistema operativo y acceder a la entrada sin procesar del ratn, puedes establecer unadjustedMovement a true:

canvas.addEventListener("click", async () => {
  await canvas.requestPointerLock({
    unadjustedMovement: true,
  });
});

Gestin de las versiones con y sin promesa de requestPointerLock()

El fragmento de cdigo anterior seguir funcionando en navegadores que no soporten la versin basada en promesas de requestPointerLock() o la opcin unadjustedMovement el operador await est permitido delante de una funcin que no devuelva una promesa, y el objeto options simplemente ser ignorado en los navegadores que no lo soporten.

Sin embargo, esto podra ser confuso, y tiene otros posibles efectos secundarios (por ejemplo, tratar de utilizar requestPointerLock().then() arrojara un error en los navegadores que no lo soportan), por lo que es posible que desee manejar esto explcitamente utilizando cdigo en las siguientes lneas:

function requestPointerLockWithUnadjustedMovement() {
  const promise = myTargetElement.requestPointerLock({
    unadjustedMovement: true,
  });

  if (!promise) {
    console.log("no se admite la desactivacin de la aceleracin del mouse");
    return;
  }

  return promise
    .then(() => console.log("el puntero est bloqueado"))
    .catch((error) => {
      if (error.name === "NotSupportedError") {
        // Es posible que algunas plataformas no admitan el movimiento no ajustado.
        // Puede solicitar de nuevo un bloqueo de puntero normal.
        return myTargetElement.requestPointerLock();
      }
    });
}

pointerLockElement y exitPointerLock()

La API de bloqueo de puntero tambin ampla la interfaz Document, aadiendo una nueva propiedad y un nuevo mtodo:

• pointerLockElement se utiliza para acceder al elemento bloqueado actualmente (si existe).
• exitPointerLock() se utiliza para salir del bloqueo del puntero.

La propiedad pointerLockElement es til para determinar si algn elemento est actualmente bloqueado por puntero (por ejemplo, para hacer una comprobacin booleana) y tambin para obtener una referencia al elemento bloqueado, si existe.

He aqu un ejemplo de utilizacin de pointerLockElement:

if (document.pointerLockElement === canvas) {
  console.log("El estado de bloqueo del puntero ahora est bloqueado");
} else {
  console.log("El estado de bloqueo del puntero ahora est desbloqueado");
}

El mtodo Document.exitPointerLock() se utiliza para salir del bloqueo de puntero, y al igual que requestPointerLock, funciona de forma asncrona utilizando los eventos pointerlockchange y pointerlockerror, de los que se hablar ms adelante.

document.exitPointerLock();

Evento pointerlockchange

Cuando cambia el estado de bloqueo del puntero por ejemplo, al llamar a requestPointerLock() o exitPointerLock(), al pulsar el usuario la tecla ESC, etc. se enva al document el evento pointerlockchange. Se trata de un evento simple que no contiene datos adicionales.

document.addEventListener("pointerlockchange", lockChangeAlert, false);

function lockChangeAlert() {
  if (document.pointerLockElement === canvas) {
    console.log("El estado de bloqueo del puntero ahora est bloqueado");
    // Haz algo til como respuesta
  } else {
    console.log("El estado de bloqueo del puntero ahora est desbloqueado");
    // Haz algo til como respuesta
  }
}

Evento pointerlockerror

Cuando se produce un error al llamar a requestPointerLock() o exitPointerLock(), se enva el evento pointerlockerror al document. Se trata de un evento simple que no contiene datos adicionales.

document.addEventListener("pointerlockerror", lockError, false);

function lockError(e) {
  alert("El bloqueo del puntero fall");
}

Extensiones a eventos de ratn

La API de bloqueo de puntero ampla la interfaz normal MouseEvent con atributos de movimiento. Dos nuevos atributos para eventos de ratn movementX y movementY proporcionan el cambio en las posiciones del ratn. Los valores de los parmetros son los mismos que la diferencia entre los valores de las propiedades MouseEvent, screenX y screenY, que se almacenan en dos eventos posteriores mousemove, eNow y ePrevious. En otras palabras, el parmetro de bloqueo del puntero movementX = eNow.screenX - ePrevious.screenX.

Estado de bloqueo

Cuando el bloqueo de puntero est activado, las propiedades MouseEvent estndar clientX, clientY, screenX y screenY se mantienen constantes, como si el ratn no se moviera. Las propiedades movementX y movementY siguen proporcionando el cambio de posicin del ratn. No hay lmite para los valores movementX y movementY si el ratn se mueve continuamente en una nica direccin. El concepto de cursor del ratn no existe y el cursor no puede moverse fuera de la ventana ni ser sujetado por un borde de la pantalla.

Estado desbloqueado

Los parmetros movementX y movementY son vlidos independientemente del estado de bloqueo del ratn, y estn disponibles incluso cuando est desbloqueado para mayor comodidad.

Cuando el ratn est desbloqueado, el cursor del sistema puede salir y volver a entrar en la ventana del navegador. Si eso ocurre, movementX y movementY podran ponerse a cero.

Ejemplo sencillo de recorrido

Hemos escrito una demo de bloqueo de puntero (ver cdigo fuente) para mostrarle cmo utilizarlo para configurar un sistema de control sencillo. Esta demo utiliza JavaScript para dibujar una bola encima de un elemento <canvas>. Al hacer clic en el lienzo, se utiliza el bloqueo del puntero para eliminar el puntero del ratn y permitirle mover la bola directamente con el ratn. Veamos cmo funciona esto.

Establecemos las posiciones iniciales x e y en el lienzo:

let x = 50;
let y = 50;

A continuacin configuramos un detector de eventos para que ejecute el mtodo requestPointerLock() en el lienzo cuando se haga clic sobre l, lo que iniciar el bloqueo del puntero. La comprobacin de document.pointerLockElement es para ver si ya hay un bloqueo de puntero activo - no queremos seguir llamando a requestPointerLock() en el lienzo cada vez que hacemos clic dentro de l si ya tenemos un bloqueo de puntero.

canvas.addEventListener("click", async () => {
  if (!document.pointerLockElement) {
    await canvas.requestPointerLock({
      unadjustedMovement: true,
    });
  }
});

Ahora vamos a detectar el evento de bloqueo de puntero: pointerlockchange. Cuando esto ocurre, ejecutamos una funcin llamada lockChangeAlert() para manejar el cambio.

document.addEventListener("pointerlockchange", lockChangeAlert, false);

Esta funcin comprueba la propiedad pointerLockElement para ver si es nuestro canvas. Si es as, adjunta un listener de eventos para manejar los movimientos del ratn con la funcin updatePosition(). Si no es as, elimina el listener de nuevo.

function lockChangeAlert() {
  if (document.pointerLockElement === canvas) {
    console.log("El estado de bloqueo del puntero ahora est bloqueado");
    document.addEventListener("mousemove", updatePosition, false);
  } else {
    console.log("El estado de bloqueo del puntero ahora est desbloqueado");
    document.removeEventListener("mousemove", updatePosition, false);
  }
}

La funcin updatePosition() actualiza la posicin de la bola en el lienzo (x e y), y tambin incluye sentencias if () para comprobar si la bola se ha salido de los bordes del lienzo. Si es as, hace que la bola se desplace hasta el borde opuesto. Tambin incluye una comprobacin de si se ha hecho previamente una llamada a requestAnimationFrame(), y si es as, la llama de nuevo si es necesario, y llama a la funcin canvasDraw() que actualiza la escena del lienzo. Tambin se configura un rastreador para escribir los valores X e Y en la pantalla, como referencia.

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

let 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(() => {
      animation = null;
      canvasDraw();
    });
  }
}

La funcin canvasDraw() dibuja la bola en las posiciones x e y actuales:

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();
}

Limitaciones de IFrame

Pointer Lock slo puede bloquear un <iframe> a la vez. Si bloqueas un <iframe>, no puedes bloquear otro y transferirle el objetivo; el bloqueo de puntero dar error. Para evitar esta limitacin, desbloquea primero el <iframe> bloqueado, y luego bloquea el otro.

Mientras que <iframe> funciona por defecto, los <iframe> "aislados" bloquean el bloqueo de puntero. Para evitar esta limitacin, utilice <iframe sandbox="allow-pointer-lock">.

Especificaciones

Compatibilidad con navegadores

api.Document.exitPointerLock

api.Element.requestPointerLock

Vase tambin

• MouseEvent
• Element.requestPointerLock()