WebVR API

Conceptos y uso

El método Navigator.getVRDisplays() devuelve cualquier dispositivo de RV conectado a tu computadora; cada uno estará representado por un objeto VRDisplay.

VRDisplay es la interfaz central de la API WebVR; a través de sus propiedades y métodos puedes acceder a funcionalidades para:

• Obtener información útil que nos permita identificar el visor, qué capacidades tiene, controladores asociados a él y más.
• Obtener los datos de cada fotograma de contenido que quieras presentar en un visor, y enviar esos fotogramas para mostrarlos a un ritmo constante.
• Iniciar y detener la presentación de contenido en el visor.

Una aplicación WebVR típica (sencilla) funcionaría así:

1. Se usa Navigator.getVRDisplays() para obtener una referencia al visor de RV.
2. Se usa VRDisplay.requestPresent() para empezar a presentar contenido en el visor de RV.
3. Se usa el método propio de WebVR VRDisplay.requestAnimationFrame() para ejecutar el bucle de renderizado de la aplicación a la frecuencia de actualización adecuada para el visor.
4. Dentro del bucle de renderizado, obtienes los datos necesarios para mostrar el fotograma en curso (VRDisplay.getFrameData()), dibujas la escena dos veces (una por cada ojo) y luego envías la vista renderizada al visor para mostrarla al usuario (VRDisplay.submitFrame()).

Además, WebVR 1.1 añade varios eventos al objeto Window para que JavaScript pueda responder a los cambios en el estado del visor.

Disponibilidad de la API

La API WebVR, que nunca se ratificó como estándar web, ha quedado obsoleta en favor de la API WebXR, que avanza con buen ritmo hacia el final de su proceso de estandarización. Por eso, deberías intentar actualizar el código existente para que use la API más reciente. En general, la transición debería ser bastante sencilla.

Además, en algunos dispositivos o navegadores, WebVR requiere que la página se cargue en un contexto seguro, a través de una conexión HTTPS. Si la página no es totalmente segura, los métodos y funciones de WebVR no estarán disponibles. Puedes comprobarlo fácilmente verificando si el método getVRDisplays() de Navigator es NULL:

if (!navigator.getVRDisplays) {
  console.error("WebVR no está disponible");
} else {
  /* Usar WebVR */
}

Uso de controladores: combinación de WebVR con la API Gamepad

Muchas configuraciones de hardware de WebVR incluyen controladores que acompañan al visor. Pueden usarse en aplicaciones WebVR mediante la API Gamepad y, en concreto, mediante la API de extensiones de Gamepad, que añade características a la API para acceder a la pose del controlador, los actuadores hápticos y más.

Interfaces de WebVR

VRDisplay

Representa cualquier dispositivo de RV compatible con esta API. Incluye información genérica, como los ID y las descripciones del dispositivo, además de métodos para empezar a presentar una escena de RV, obtener los parámetros de los ojos y las capacidades del visor, y otras funcionalidades importantes.

VRDisplayCapabilities

Describe las capacidades de un VRDisplay; sus características sirven para comprobar qué puede hacer el dispositivo de RV, por ejemplo, si es capaz de devolver información de posición.

VRDisplayEvent

Representa el objeto de evento de los eventos relacionados con WebVR (consulta los eventos de Window enumerados más abajo).

VRFrameData

Representa toda la información necesaria para renderizar un solo fotograma de una escena de RV; se construye mediante VRDisplay.getFrameData().

VRPose

Representa el estado de posición en una marca de tiempo determinada (que incluye orientación, posición, velocidad y aceleración).

VREyeParameters

Proporciona acceso a toda la información necesaria para renderizar correctamente una escena para cada ojo, incluida la información del campo de visión.

VRFieldOfView

Representa un campo de visión definido por 4 valores distintos en grados que describen la vista desde un punto central.

VRLayerInit

Representa una capa que se presentará en un VRDisplay.

VRStageParameters

Representa los valores que describen el área del escenario para dispositivos que admiten experiencias a escala de sala.

Extensiones a otras interfaces

La API WebVR amplía las siguientes API y añade las características que se indican.

Gamepad

Gamepad.displayId Read only

Devuelve el VRDisplay.displayId del VRDisplay asociado, es decir, el VRDisplay cuya escena controla el gamepad.

Navigator

Navigator.activeVRDisplays Read only

Devuelve un array con todos los objetos VRDisplay que están presentando contenido en este momento (VRDisplay.isPresenting es true).

Navigator.getVRDisplays()

Devuelve una promesa que se resuelve con un array de objetos VRDisplay que representan los visores de RV disponibles conectados a la computadora.

Eventos de Window

vrdisplaypresentchange

Se dispara cuando cambia el estado de presentación de un visor de RV, es decir, cuando pasa de presentar contenido a no hacerlo, o viceversa.

vrdisplayconnect

Se dispara cuando se conecta a la computadora un visor de RV compatible.

vrdisplaydisconnect

Se dispara cuando se desconecta de la computadora un visor de RV compatible.

vrdisplayactivate

Se dispara cuando ya se puede presentar contenido en un visor.

vrdisplaydeactivate

Se dispara cuando ya no se puede presentar contenido en un visor.

Ejemplos

Puedes encontrar varios ejemplos en estos lugares:

• webvr-tests: ejemplos muy sencillos que acompañan la documentación de WebVR en MDN.
• Carmel starter kit: ejemplos sencillos y bien comentados que acompañan a Carmel, el navegador WebVR de Facebook.
• WebVR.info samples: ejemplos algo más detallados, junto con el código fuente
• Página principal de A-Frame: ejemplos que muestran el uso de A-Frame

Especificaciones

Esta API se especificó en la antigua API WebVR, que ha sido reemplazada por la WebXR Device API. Ya no está en camino de convertirse en un estándar.

Hasta que todos los navegadores hayan implementado las nuevas API WebXR, se recomienda recurrir a frameworks como A-Frame, Babylon.js o Three.js, o a un polyfill, para desarrollar aplicaciones WebXR que funcionen en todos los navegadores. Para más información, consulta la guía Porting from WebVR to WebXR de Meta.

Compatibilidad con navegadores

Véase también

• A-Frame: framework web de código abierto para crear experiencias de RV.
• webvr.info: información actualizada sobre WebVR, la configuración de navegadores y la comunidad.
• threejs-vr-boilerplate: una plantilla de inicio útil sobre la que escribir aplicaciones WebVR.
• Web VR polyfill: implementación de WebVR en JavaScript.
• WebVR Directory: lista de sitios WebVR de calidad.