diff options
| author | julieng <julien.gattelier@gmail.com> | 2021-10-02 17:20:24 +0200 |
|---|---|---|
| committer | SphinxKnight <SphinxKnight@users.noreply.github.com> | 2021-10-02 17:30:20 +0200 |
| commit | 1407c8fdef01ecd0ffb8a8bd46e7113f119b9fde (patch) | |
| tree | 30a56efd3eff3a01bd1611e1840fdbbfacf544a4 /files/fr/web/api/webvr_api | |
| parent | c05efa8d7ae464235cf83d7c0956e42dc6974103 (diff) | |
| download | translated-content-1407c8fdef01ecd0ffb8a8bd46e7113f119b9fde.tar.gz translated-content-1407c8fdef01ecd0ffb8a8bd46e7113f119b9fde.tar.bz2 translated-content-1407c8fdef01ecd0ffb8a8bd46e7113f119b9fde.zip | |
convert content to md
Diffstat (limited to 'files/fr/web/api/webvr_api')
| -rw-r--r-- | files/fr/web/api/webvr_api/index.md | 169 | ||||
| -rw-r--r-- | files/fr/web/api/webvr_api/using_vr_controllers_with_webvr/index.md | 204 |
2 files changed, 182 insertions, 191 deletions
diff --git a/files/fr/web/api/webvr_api/index.md b/files/fr/web/api/webvr_api/index.md index 4d41a433a3..4a082d8609 100644 --- a/files/fr/web/api/webvr_api/index.md +++ b/files/fr/web/api/webvr_api/index.md @@ -3,97 +3,78 @@ title: WebVR API slug: Web/API/WebVR_API translation_of: Web/API/WebVR_API --- -<div>{{DefaultAPISidebar("WebVR API")}}{{Deprecated_Header}}</div> - -<p>WebVR fournit un support pour les dispositifs de réalité virtuelle - par exemple pour les casques de réalité virtuelle comme l'Oculus Rift - aux applications Web, permettant aux développeurs de traduire les informations de position et de mouvement de l'appareil en mouvements autour d'une scène 3D. Cela a de nombreuses applications très intéressantes, des visites de produits virtuels aux applications de formation interactive en passant par des jeux en première personne dans un environnement immersif.</p> - -<h2 id="Concepts_and_usage">Concepts et usage</h2> - -<p><img alt="Croquis d'une personne assise sur une chaise et portant des lunettes portant la mention « Head mounted display (HMD) » faisant face à un moniteur avec une webcam portant la mention « Position sensor »." src="hw-setup.png"></p> - -<p>Tous les périphériques de réalité virtuelle connectés à votre ordinateur seront donné grâce à la méthode {{domxref("Navigator.getVRDisplays()")}}. Cela retournera un tableau d'objets représentant les périphériques, qui auront l'héritage de l'objet {{domxref("VRDevice")}} — généralement un casque de réalité virtuelle renverra deux périphériques — le casque lui-même, représenté par {{domxref("HMDVRDevice")}}, et la caméra capteur de position qui suit la position de votre tête, représenté par {{domxref("PositionSensorVRDevice")}}.</p> - -<p>L'objet {{domxref("PositionSensorVRDevice")}} contient la méthode {{domxref("PositionSensorVRDevice.getState","getState()")}}, qui retourne un objet {{domxref("VRPositionState")}} — cela représente l'état du capteur à un timecode donné, et inclus les propriétés avec des données utiles tel que la vélocité, l'accélération et l'orientation, utiles pour mettre à jour le rendu de la scène pour chaque image en accord avec le mouvement du casque de réalité virtuelle.</p> - -<p>La méthode {{domxref("HMDVRDevice.getEyeParameters()")}} retourne un objet {{domxref("VREyeParameters")}}, qui peut être utilisé pour obtenir l'information du champ de vision — combien le casque de réalité virtuel peut afficher de la scène. Le {{domxref("VREyeParameters.currentFieldOfView")}} retourne un objet {{domxref("VRFieldOfView")}} qui contient quatre angles décrivant le champ de vision actuel depuis le point central. Vous pouvez aussi changer le champ de vision en utilisant {{domxref("HMDVRDevice.setFieldOfView()")}}.</p> - -<h2 id="Interfaces_WebVR">Interfaces WebVR</h2> - -<dl> - <dt>{{domxref("VRDisplay")}}</dt> - <dd>Représente un périphérique de réalité virtuelle supporté par cette API. Il inclut des informations générales comme les IDs et des descriptions de l'appareil, ainsi que des méthodes pour commencer à présenter une scène RV, récupérer les paramètres visuels, les capacités d'affichage et d'autres fonctionnalités importantes.</dd> - <dt>{{domxref("VRDisplayCapabilities")}}</dt> - <dd>Décrit les capacités d'un appareil {{domxref("VRDisplay")}} — ses fonctionalités peuvent être utilisée pour tester les capacités du périphérique, par exemple peut-il retourner l'information de position.</dd> - <dt>{{domxref("VRPose")}}</dt> - <dd>Représente l'état de la position à un timecode donné (qui inclut l'orientation, la position, la vélocité et l'accélération).</dd> - <dt>{{domxref("VREyeParameters")}}</dt> - <dd>Donne accès à l'ensemble des informations requises pour faire le rendu d'une scène pour l'oeil indiqué, dont les informations de champ de vision.</dd> - <dt>{{domxref("VRFieldOfView")}}</dt> - <dd>Représente le champ de vision actuel définit par quatre angles décrivant la vue depuis le point central.</dd> - <dt>{{domxref("VRLayer")}}</dt> - <dd>Représente un calque d'un objet {{domxref("VRDisplay")}}.</dd> - <dt>{{domxref("VRStageParameters")}}</dt> - <dd>Représente les données décrivant l'espace physique disponible pour les périphériques de réalité virtuelle pouvant offrir une expérience dans une pièce réelle.</dd> -</dl> - -<h3 id="Extensions_à_d'autres_interfaces">Extensions à d'autres interfaces</h3> - -<dl> - <dt>{{domxref("Gamepad.displayId")}} {{readonlyInline}}</dt> - <dd><dfn>Retourne l'ID {{domxref("VRDisplay.displayId")}} du périphérique {{domxref("VRDisplay")}} associé — l'appareil RV où la manette de jeu contrôle la scene affichée.</dfn></dd> - <dt>{{domxref("Navigator.activeVRDisplays")}} {{readonlyInline}}</dt> - <dd>Retourne un tableau contenant tous les périphériques (objet {{domxref("VRDisplay")}}) qui sont actifs (quand {{domxref("VRDisplay.ispresenting")}} est à <code>true</code>).</dd> - <dt>{{domxref("Navigator.getVRDisplays()")}}</dt> - <dd>Retourne un tableau contenant tous les périphériques (objet {{domxref("VRDisplay")}}) disponibles qui sont connectés à l'ordinateur.</dd> - <dt>{{domxref("Window.onvrdisplayconnected")}}</dt> - <dd>Représente un gestionaire d'événements qui s'exécute lorsqu'un appareil RV compatible a été connecté à l'ordinateur (quand l'événement {{event("vrdisplayconnected")}} est déclenché).</dd> - <dt>{{domxref("Window.onvrdisplaydisconnected")}}</dt> - <dd>Représente un gestionaire d'événements qui s'exécute lorsqu'un appareil RV compatible a été déconnecté de l'ordinateur (quand l'événement {{event("vrdisplaydisconnected")}} est déclenché).</dd> - <dt>{{domxref("Window.onvrdisplaypresentchange")}}</dt> - <dd>Représente un gestionaire d'événements qui s'exécute lorsque l'état de présentation d'un appareil change — i.e. un changement de l'état "présente" à "ne présente pas", ou vice versa (quand l'événement {{event("onvrdisplaypresentchange")}} est déclenché).</dd> -</dl> - -<h2 id="Examples">Examples</h2> - -<p>Vous pouvez retrouver plusieurs exemples dans ces repos Github:</p> - -<ul> - <li><a href="https://github.com/aframevr/aframe">A-Frame</a>: un framework web Open source pour construire des expériences RV. Plusieurs exemples.</li> - <li><a href="https://github.com/mdn/webvr-tests">mdn/webvr-tests</a>: Démos simples conçus pour illustrer des fonctionalités d'usage de base.</li> - <li><a href="https://github.com/MozVR/">MozVR team</a>: Plus de démos avancés, la source de la spec WebVR, et plus!</li> -</ul> - -<h2 id="Specifications">Specifications</h2> - -<table class="standard-table"> - <tbody> - <tr> - <th scope="col">Specification</th> - <th scope="col">Status</th> - <th scope="col">Comment</th> - </tr> - <tr> - <td>{{SpecName('WebVR')}}</td> - <td>{{Spec2('WebVR')}}</td> - <td>Initial definition</td> - </tr> - </tbody> -</table> - -<h2 id="Browser_compatibility">Compatibilité des navigateurs</h2> - -<h3 id="Navigator.getVRDisplays"><code>Navigator.getVRDisplays</code></h3> - -<p>{{Compat("api.Navigator.getVRDisplays")}}</p> - -<h2 id="See_also">Voir aussi</h2> - -<ul> - <li><a href="https://webvr.info">webvr.info</a> - Up-to-date information about WebVR, browser setup, and community.</li> - <li><a href="https://iswebvrready.com">Is WebVR Ready?</a> - Up-to-date information about WebVR browser support (including experimental builds).</li> - <li><a href="http://mozvr.com/">MozVr.com</a> — demos, downloads, and other resources from the Mozilla VR team.</li> - <li><a href="https://aframe.io">A-Frame</a> — a web framework for building VR experiences (with HTML), from the Mozilla VR team.</li> - <li><a href="http://dsmu.me/ConsoleGameOnWeb/">Console Game on Web</a> — a collection of interesting game concept demos, some of which include WebVR.</li> - <li><a href="https://github.com/MozVR/vr-web-examples/tree/master/threejs-vr-boilerplate">threejs-vr-boilerplate</a> — a very useful starter template for writing WebVR apps into.</li> - <li><a href="https://developer.oculus.com/">Oculus Rift homepage</a></li> -</ul> +{{DefaultAPISidebar("WebVR API")}}{{Deprecated_Header}} + +WebVR fournit un support pour les dispositifs de réalité virtuelle - par exemple pour les casques de réalité virtuelle comme l'Oculus Rift - aux applications Web, permettant aux développeurs de traduire les informations de position et de mouvement de l'appareil en mouvements autour d'une scène 3D. Cela a de nombreuses applications très intéressantes, des visites de produits virtuels aux applications de formation interactive en passant par des jeux en première personne dans un environnement immersif. + +## Concepts et usage + + + +Tous les périphériques de réalité virtuelle connectés à votre ordinateur seront donné grâce à la méthode {{domxref("Navigator.getVRDisplays()")}}. Cela retournera un tableau d'objets représentant les périphériques, qui auront l'héritage de l'objet {{domxref("VRDevice")}} — généralement un casque de réalité virtuelle renverra deux périphériques — le casque lui-même, représenté par {{domxref("HMDVRDevice")}}, et la caméra capteur de position qui suit la position de votre tête, représenté par {{domxref("PositionSensorVRDevice")}}. + +L'objet {{domxref("PositionSensorVRDevice")}} contient la méthode {{domxref("PositionSensorVRDevice.getState","getState()")}}, qui retourne un objet {{domxref("VRPositionState")}} — cela représente l'état du capteur à un timecode donné, et inclus les propriétés avec des données utiles tel que la vélocité, l'accélération et l'orientation, utiles pour mettre à jour le rendu de la scène pour chaque image en accord avec le mouvement du casque de réalité virtuelle. + +La méthode {{domxref("HMDVRDevice.getEyeParameters()")}} retourne un objet {{domxref("VREyeParameters")}}, qui peut être utilisé pour obtenir l'information du champ de vision — combien le casque de réalité virtuel peut afficher de la scène. Le {{domxref("VREyeParameters.currentFieldOfView")}} retourne un objet {{domxref("VRFieldOfView")}} qui contient quatre angles décrivant le champ de vision actuel depuis le point central. Vous pouvez aussi changer le champ de vision en utilisant {{domxref("HMDVRDevice.setFieldOfView()")}}. + +## Interfaces WebVR + +- {{domxref("VRDisplay")}} + - : Représente un périphérique de réalité virtuelle supporté par cette API. Il inclut des informations générales comme les IDs et des descriptions de l'appareil, ainsi que des méthodes pour commencer à présenter une scène RV, récupérer les paramètres visuels, les capacités d'affichage et d'autres fonctionnalités importantes. +- {{domxref("VRDisplayCapabilities")}} + - : Décrit les capacités d'un appareil {{domxref("VRDisplay")}} — ses fonctionalités peuvent être utilisée pour tester les capacités du périphérique, par exemple peut-il retourner l'information de position. +- {{domxref("VRPose")}} + - : Représente l'état de la position à un timecode donné (qui inclut l'orientation, la position, la vélocité et l'accélération). +- {{domxref("VREyeParameters")}} + - : Donne accès à l'ensemble des informations requises pour faire le rendu d'une scène pour l'oeil indiqué, dont les informations de champ de vision. +- {{domxref("VRFieldOfView")}} + - : Représente le champ de vision actuel définit par quatre angles décrivant la vue depuis le point central. +- {{domxref("VRLayer")}} + - : Représente un calque d'un objet {{domxref("VRDisplay")}}. +- {{domxref("VRStageParameters")}} + - : Représente les données décrivant l'espace physique disponible pour les périphériques de réalité virtuelle pouvant offrir une expérience dans une pièce réelle. + +### Extensions à d'autres interfaces + +- {{domxref("Gamepad.displayId")}} {{readonlyInline}} + - : _Retourne l'ID {{domxref("VRDisplay.displayId")}} du périphérique {{domxref("VRDisplay")}} associé — l'appareil RV où la manette de jeu contrôle la scene affichée._ +- {{domxref("Navigator.activeVRDisplays")}} {{readonlyInline}} + - : Retourne un tableau contenant tous les périphériques (objet {{domxref("VRDisplay")}}) qui sont actifs (quand {{domxref("VRDisplay.ispresenting")}} est à `true`). +- {{domxref("Navigator.getVRDisplays()")}} + - : Retourne un tableau contenant tous les périphériques (objet {{domxref("VRDisplay")}}) disponibles qui sont connectés à l'ordinateur. +- {{domxref("Window.onvrdisplayconnected")}} + - : Représente un gestionaire d'événements qui s'exécute lorsqu'un appareil RV compatible a été connecté à l'ordinateur (quand l'événement {{event("vrdisplayconnected")}} est déclenché). +- {{domxref("Window.onvrdisplaydisconnected")}} + - : Représente un gestionaire d'événements qui s'exécute lorsqu'un appareil RV compatible a été déconnecté de l'ordinateur (quand l'événement {{event("vrdisplaydisconnected")}} est déclenché). +- {{domxref("Window.onvrdisplaypresentchange")}} + - : Représente un gestionaire d'événements qui s'exécute lorsque l'état de présentation d'un appareil change — i.e. un changement de l'état "présente" à "ne présente pas", ou vice versa (quand l'événement {{event("onvrdisplaypresentchange")}} est déclenché). + +## Examples + +Vous pouvez retrouver plusieurs exemples dans ces repos Github: + +- [A-Frame](https://github.com/aframevr/aframe): un framework web Open source pour construire des expériences RV. Plusieurs exemples. +- [mdn/webvr-tests](https://github.com/mdn/webvr-tests): Démos simples conçus pour illustrer des fonctionalités d'usage de base. +- [MozVR team](https://github.com/MozVR/): Plus de démos avancés, la source de la spec WebVR, et plus! + +## Specifications + +| Specification | Status | Comment | +| ---------------------------- | ------------------------ | ------------------ | +| {{SpecName('WebVR')}} | {{Spec2('WebVR')}} | Initial definition | + +## Compatibilité des navigateurs + +### `Navigator.getVRDisplays` + +{{Compat("api.Navigator.getVRDisplays")}} + +## Voir aussi + +- [webvr.info](https://webvr.info) - Up-to-date information about WebVR, browser setup, and community. +- [Is WebVR Ready?](https://iswebvrready.com) - Up-to-date information about WebVR browser support (including experimental builds). +- [MozVr.com](http://mozvr.com/) — demos, downloads, and other resources from the Mozilla VR team. +- [A-Frame](https://aframe.io) — a web framework for building VR experiences (with HTML), from the Mozilla VR team. +- [Console Game on Web](http://dsmu.me/ConsoleGameOnWeb/) — a collection of interesting game concept demos, some of which include WebVR. +- [threejs-vr-boilerplate](https://github.com/MozVR/vr-web-examples/tree/master/threejs-vr-boilerplate) — a very useful starter template for writing WebVR apps into. +- [Oculus Rift homepage](https://developer.oculus.com/) diff --git a/files/fr/web/api/webvr_api/using_vr_controllers_with_webvr/index.md b/files/fr/web/api/webvr_api/using_vr_controllers_with_webvr/index.md index ac6babdad9..eaf25ee8e6 100644 --- a/files/fr/web/api/webvr_api/using_vr_controllers_with_webvr/index.md +++ b/files/fr/web/api/webvr_api/using_vr_controllers_with_webvr/index.md @@ -4,137 +4,142 @@ slug: Web/API/WebVR_API/Using_VR_controllers_with_WebVR translation_of: Web/API/WebVR_API/Using_VR_controllers_with_WebVR original_slug: Web/API/WebVR_API/Utiliser_des_contrôleurs_de_realite_virtuelle_pour_du_WebVR --- -<div>{{APIRef("WebVR API")}}</div> +{{APIRef("WebVR API")}} -<p>La plupart des matériels de WebVR possède des contrôleurs qui viennent avec le casque de réalité virtuelle. Ceux-ci peuvent être utilisés dans les application WebVR grâce à l'<a href="/en-US/docs/Web/API/Gamepad_API">API Gamepad</a>, et plus spécifiquement avec l'<a href="/en-US/docs/Web/API/Gamepad_API#Experimental_Gamepad_extensions">API Gamepad Extensions</a> qui ajoute des API pour accéder, entre autres, à la <a href="/en-US/docs/Web/API/GamepadPose">position du controller</a>, au <a href="/en-US/docs/Web/API/GamepadHapticActuator">retour haptique</a>, etc.. Cet article fournit les bases pour utiliser ces API.</p> +La plupart des matériels de WebVR possède des contrôleurs qui viennent avec le casque de réalité virtuelle. Ceux-ci peuvent être utilisés dans les application WebVR grâce à l'[API Gamepad](/en-US/docs/Web/API/Gamepad_API), et plus spécifiquement avec l'[API Gamepad Extensions](/en-US/docs/Web/API/Gamepad_API#Experimental_Gamepad_extensions) qui ajoute des API pour accéder, entre autres, à la [position du controller](/en-US/docs/Web/API/GamepadPose), au [retour haptique](/en-US/docs/Web/API/GamepadHapticActuator), etc.. Cet article fournit les bases pour utiliser ces API. -<h2 id="L'API_WebVR">L'API WebVR</h2> +## L'API WebVR -<p>L'<a href="/en-US/docs/Web/API/WebVR_API">API WebVR</a> est jeune mais possède déjà des fonctionnalités très interressantes pour le web et pour que les développeur·euse·s puisse créer des expériences de réalité virtuelle sur le web. Cela est possible grâce à un accès aux données des casques de réalité virtuelle connectés à votre ordinateur. Ceux-ci seront indentifié comme des objets {{domxref("VRDisplay")}},que vous pourrez manipuler pour commencer et arrêter l'affichage dans le casque, récupérer des données de mouvement (orientation, position...) qui pourront être utilisés pour mettre à jour l'affichage d'une animation, par exemple.</p> +L'[API WebVR](/en-US/docs/Web/API/WebVR_API) est jeune mais possède déjà des fonctionnalités très interressantes pour le web et pour que les développeur·euse·s puisse créer des expériences de réalité virtuelle sur le web. Cela est possible grâce à un accès aux données des casques de réalité virtuelle connectés à votre ordinateur. Ceux-ci seront indentifié comme des objets {{domxref("VRDisplay")}},que vous pourrez manipuler pour commencer et arrêter l'affichage dans le casque, récupérer des données de mouvement (orientation, position...) qui pourront être utilisés pour mettre à jour l'affichage d'une animation, par exemple. -<p>Avant de commencer, vous devriez être déjà avoir des bases de l'API WebVR. Si ce n'est pas le cas, allez lire l'article <a href="/en-US/docs/Web/API/WebVR_API/Using_the_WebVR_API">Utiliser l'API WebVR</a>, vous aurez également des détails sur la compatibilité des navigateurs web ou du matériel nécessaire.</p> +Avant de commencer, vous devriez être déjà avoir des bases de l'API WebVR. Si ce n'est pas le cas, allez lire l'article [Utiliser l'API WebVR](/en-US/docs/Web/API/WebVR_API/Using_the_WebVR_API), vous aurez également des détails sur la compatibilité des navigateurs web ou du matériel nécessaire. -<h2 id="L'API_Gamepad">L'API Gamepad</h2> +## L'API Gamepad -<p>L'<a href="/en-US/docs/Web/API/Gamepad_API">API Gamepad</a> est une API assez bien compatible, qui donne aux développeur·euse·s l'accès aux manettes de jeu, connectés à leur ordinateur et de les utilisé dans dans applications web. Les contrôleurs peuvent basiquement être accessible comme des objets {{domxref("Gamepad")}}, avec lesquels nous pouvons faire des requêtes pour savoir quels boutons sont appuyés ou quels joystick sont actionnés, etc..</p> +L'[API Gamepad](/en-US/docs/Web/API/Gamepad_API) est une API assez bien compatible, qui donne aux développeur·euse·s l'accès aux manettes de jeu, connectés à leur ordinateur et de les utilisé dans dans applications web. Les contrôleurs peuvent basiquement être accessible comme des objets {{domxref("Gamepad")}}, avec lesquels nous pouvons faire des requêtes pour savoir quels boutons sont appuyés ou quels joystick sont actionnés, etc.. -<p>Vous pouvez avoir plus d'information sur l'usage de API de base des Gamepad avec l'article <a href="/en-US/docs/Web/API/Gamepad_API/Using_the_Gamepad_API">Utilisez l'API Gamepad</a>, et <a href="/en-US/docs/Games/Techniques/Controls_Gamepad_API">Implementer des contrôles en utilisant l'API Gamepad</a>.</p> +Vous pouvez avoir plus d'information sur l'usage de API de base des Gamepad avec l'article [Utilisez l'API Gamepad](/en-US/docs/Web/API/Gamepad_API/Using_the_Gamepad_API), et [Implementer des contrôles en utilisant l'API Gamepad](/en-US/docs/Games/Techniques/Controls_Gamepad_API). -<p>Dans cet article, nous allons nous attardez sur les nouvelles fonctionnalités offertes dans l'API {{specname("GamepadExtensions")}}, laquelle donne accès à des informations avancés comme des données de position ou d'orientation, ou encore contrôler les retours haptiques (vibrations), et bien plus. Cette API est toute nouvelle et, pour l'instant, seulement disponible dans les versions Beta ou Nightly de Firefox 55 (et suppérieur).</p> +Dans cet article, nous allons nous attardez sur les nouvelles fonctionnalités offertes dans l'API {{specname("GamepadExtensions")}}, laquelle donne accès à des informations avancés comme des données de position ou d'orientation, ou encore contrôler les retours haptiques (vibrations), et bien plus. Cette API est toute nouvelle et, pour l'instant, seulement disponible dans les versions Beta ou Nightly de Firefox 55 (et suppérieur). -<h2 id="Types_de_contrôlleurs">Types de contrôlleurs</h2> +## Types de contrôlleurs -<p>Il y a deux principaux types de contrôleurs utilisés pour la réalité virtuelle :</p> +Il y a deux principaux types de contrôleurs utilisés pour la réalité virtuelle : -<ul> - <li>les "6DoF" (six degrés de liberté) sont des contrôleurs qui donne accès aux informations de position et d'orientation. Un exemple notable serait les manettes du HTC Vive.</li> - <li>les "3DoF" (trois degrés de liberté) sont des contrôleurs qui donne uniquement accès aux informations d'orientation. Un exemple notable serait la manette du Google Daydream, qui peut être tourné pour sélectionner des objets 3D comme un pointeur laser, mais ne peux être bougé dans la scène 3D.</li> -</ul> +- les "6DoF" (six degrés de liberté) sont des contrôleurs qui donne accès aux informations de position et d'orientation. Un exemple notable serait les manettes du HTC Vive. +- les "3DoF" (trois degrés de liberté) sont des contrôleurs qui donne uniquement accès aux informations d'orientation. Un exemple notable serait la manette du Google Daydream, qui peut être tourné pour sélectionner des objets 3D comme un pointeur laser, mais ne peux être bougé dans la scène 3D. -<h2 id="Basic_controller_access">Basic controller access</h2> +## Basic controller access -<p>Now onto some code. Let's look first at the basics of how we get access to VR controllers with the Gamepad API. There are a few strange nuances to bear in mind here, so it is worth taking a look.</p> +Now onto some code. Let's look first at the basics of how we get access to VR controllers with the Gamepad API. There are a few strange nuances to bear in mind here, so it is worth taking a look. -<p>We've written up a simple example to demonstrate — see our <a href="https://github.com/mdn/webvr-tests/blob/master/vr-controller-basic-info/index.html">vr-controller-basic-info</a> source code (<a href="https://mdn.github.io/webvr-tests/vr-controller-basic-info/">see it running live here also</a>). This demo simply outputs information on the VR displays and gamepads connected to your computer.</p> +We've written up a simple example to demonstrate — see our [vr-controller-basic-info](https://github.com/mdn/webvr-tests/blob/master/vr-controller-basic-info/index.html) source code ([see it running live here also](https://mdn.github.io/webvr-tests/vr-controller-basic-info/)). This demo simply outputs information on the VR displays and gamepads connected to your computer. -<h3 id="Getting_the_display_information">Getting the display information</h3> +### Getting the display information -<p>The first notable code is as follows:</p> +The first notable code is as follows: -<pre class="brush: js">var initialRun = true; +```js +var initialRun = true; -if(navigator.getVRDisplays && navigator.getGamepads) { +if(navigator.getVRDisplays && navigator.getGamepads) { info.textContent = 'WebVR API and Gamepad API supported.' reportDisplays(); } else { info.textContent = 'WebVR API and/or Gamepad API not supported by this browser.' -}</pre> +} +``` -<p>Here we first use a tracking variable, <code>initialRun</code>, to note that this is the first time we have loaded the page. You'll find out more about this later on. Next, we detect to see if the WebVR and Gamepad APIs are supported by cheking for the existence of the {{domxref("Navigator.getVRDisplays()")}} and {{domxref("Navigator.getGamepads()")}} methods. If so, we run our <code>reportDisplays()</code> custom function to start the process off. This function looks like so:</p> +Here we first use a tracking variable, `initialRun`, to note that this is the first time we have loaded the page. You'll find out more about this later on. Next, we detect to see if the WebVR and Gamepad APIs are supported by cheking for the existence of the {{domxref("Navigator.getVRDisplays()")}} and {{domxref("Navigator.getGamepads()")}} methods. If so, we run our `reportDisplays()` custom function to start the process off. This function looks like so: -<pre class="brush: js">function reportDisplays() { +```js +function reportDisplays() { navigator.getVRDisplays().then(function(displays) { console.log(displays.length + ' displays'); - for(var i = 0; i < displays.length; i++) { + for(var i = 0; i < displays.length; i++) { var cap = displays[i].capabilities; // cap is a VRDisplayCapabilities object var listItem = document.createElement('li'); - listItem.innerHTML = '<strong>Display ' + (i+1) + '</strong>' - + '<br>VR Display ID: ' + displays[i].displayId - + '<br>VR Display Name: ' + displays[i].displayName - + '<br>Display can present content: ' + cap.canPresent - + '<br>Display is separate from the computer\'s main display: ' + cap.hasExternalDisplay - + '<br>Display can return position info: ' + cap.hasPosition - + '<br>Display can return orientation info: ' + cap.hasOrientation - + '<br>Display max layers: ' + cap.maxLayers; + listItem.innerHTML = '<strong>Display ' + (i+1) + '</strong>' + + '<br>VR Display ID: ' + displays[i].displayId + + '<br>VR Display Name: ' + displays[i].displayName + + '<br>Display can present content: ' + cap.canPresent + + '<br>Display is separate from the computer\'s main display: ' + cap.hasExternalDisplay + + '<br>Display can return position info: ' + cap.hasPosition + + '<br>Display can return orientation info: ' + cap.hasOrientation + + '<br>Display max layers: ' + cap.maxLayers; list.appendChild(listItem); } setTimeout(reportGamepads, 1000); // For VR, controllers will only be active after their corresponding headset is active }); -}</pre> +} +``` -<p>This function first uses the promise-based {{domxref("Navigator.getVRDisplays()")}} method, which resolves with an array containing {{domxref("VRDisplay")}} objects representing the connected displays. Next, it prints out each display's {{domxref("VRDisplay.displayId")}} and {{domxref("VRDisplay.displayName")}} values, and a number of useful values contained in the display's associated {{domxref("VRCapabilities")}} object. The most useful of these are {{domxref("VRCapabilities.hasOrientation","hasOrientation")}} and {{domxref("VRCapabilities.hasPosition","hasPosition")}}, which allow you to detect whether the device can return orientation and position data and set up your app accordingly.</p> +This function first uses the promise-based {{domxref("Navigator.getVRDisplays()")}} method, which resolves with an array containing {{domxref("VRDisplay")}} objects representing the connected displays. Next, it prints out each display's {{domxref("VRDisplay.displayId")}} and {{domxref("VRDisplay.displayName")}} values, and a number of useful values contained in the display's associated {{domxref("VRCapabilities")}} object. The most useful of these are {{domxref("VRCapabilities.hasOrientation","hasOrientation")}} and {{domxref("VRCapabilities.hasPosition","hasPosition")}}, which allow you to detect whether the device can return orientation and position data and set up your app accordingly. -<p>The last line contained in this function is a {{domxref("WindowOrWorkerGlobalScope.setTimeout()")}} call, which runs the <code>reportGamepads()</code> function after a 1 second delay. Why do we need to do this? First of all, VR controllers will only be ready after their associated VR headset is active, so we need to invoke this after <code>getVRDisplays()</code> has been called and returned the display information. Second, the Gamepad API is much older than the WebVR API, and not promise-based. As you'll see later, the <code>getGamepads()</code> method is synchronous, and just returns the <code>Gamepad</code> objects immediately — it doesn't wait for the controller to be ready to report information. Unless you wait for a little while, returned information may not be accurate (at least, this is what we found in our tests).</p> +The last line contained in this function is a {{domxref("WindowOrWorkerGlobalScope.setTimeout()")}} call, which runs the `reportGamepads()` function after a 1 second delay. Why do we need to do this? First of all, VR controllers will only be ready after their associated VR headset is active, so we need to invoke this after `getVRDisplays()` has been called and returned the display information. Second, the Gamepad API is much older than the WebVR API, and not promise-based. As you'll see later, the `getGamepads()` method is synchronous, and just returns the `Gamepad` objects immediately — it doesn't wait for the controller to be ready to report information. Unless you wait for a little while, returned information may not be accurate (at least, this is what we found in our tests). -<h3 id="Getting_the_Gamepad_information">Getting the Gamepad information</h3> +### Getting the Gamepad information -<p>The <code>reportGamepads()</code> function looks like this:</p> +The `reportGamepads()` function looks like this: -<pre class="brush: js">function reportGamepads() { +```js +function reportGamepads() { var gamepads = navigator.getGamepads(); console.log(gamepads.length + ' controllers'); - for(var i = 0; i < gamepads.length; ++i) { + for(var i = 0; i < gamepads.length; ++i) { var gp = gamepads[i]; var listItem = document.createElement('li'); listItem.classList = 'gamepad'; - listItem.innerHTML = '<strong>Gamepad ' + gp.index + '</strong> (' + gp.id + ')' - + '<br>Associated with VR Display ID: ' + gp.displayId - + '<br>Gamepad associated with which hand: ' + gp.hand - + '<br>Available haptic actuators: ' + gp.hapticActuators.length - + '<br>Gamepad can return position info: ' + gp.pose.hasPosition - + '<br>Gamepad can return orientation info: ' + gp.pose.hasOrientation; + listItem.innerHTML = '<strong>Gamepad ' + gp.index + '</strong> (' + gp.id + ')' + + '<br>Associated with VR Display ID: ' + gp.displayId + + '<br>Gamepad associated with which hand: ' + gp.hand + + '<br>Available haptic actuators: ' + gp.hapticActuators.length + + '<br>Gamepad can return position info: ' + gp.pose.hasPosition + + '<br>Gamepad can return orientation info: ' + gp.pose.hasOrientation; list.appendChild(listItem); } initialRun = false; -}</pre> +} +``` -<p>This works in a similar manner to <code>reportDisplays()</code> — we get an array of {{domxref("Gamepad")}} objects using the non-promise-based <code>getGamepads()</code> method, then cycle through each one and print out information on each:</p> +This works in a similar manner to `reportDisplays()` — we get an array of {{domxref("Gamepad")}} objects using the non-promise-based `getGamepads()` method, then cycle through each one and print out information on each: -<ul> - <li>The {{domxref("Gamepad.displayId")}} property is the same as the <code>displayId</code> of the headet the controller is associated with, and therefore useful for tying controller and headset information together.</li> - <li>The {{domxref("Gamepad.index")}} property is unique numerical index that identifies each connected controller.</li> - <li>{{domxref("Gamepad.hand")}} returns which hand the controller is expected to be held in.</li> - <li>{{domxref("Gamepad.hapticActuators")}} returns an array of the haptic actuators available in the controller. Here we are returning its length so we can see how many each has available.</li> - <li>Finally, we return {{domxref("GamepadPose.hasPosition")}} and {{domxref("GamepadPose.hasOrientation")}} to show whether the controller can return position and orientation data. This works just the same as for the displays, except that in the case of gamepads these values are available on the pose object, not the capabilities object.</li> -</ul> +- The {{domxref("Gamepad.displayId")}} property is the same as the `displayId` of the headet the controller is associated with, and therefore useful for tying controller and headset information together. +- The {{domxref("Gamepad.index")}} property is unique numerical index that identifies each connected controller. +- {{domxref("Gamepad.hand")}} returns which hand the controller is expected to be held in. +- {{domxref("Gamepad.hapticActuators")}} returns an array of the haptic actuators available in the controller. Here we are returning its length so we can see how many each has available. +- Finally, we return {{domxref("GamepadPose.hasPosition")}} and {{domxref("GamepadPose.hasOrientation")}} to show whether the controller can return position and orientation data. This works just the same as for the displays, except that in the case of gamepads these values are available on the pose object, not the capabilities object. -<p>Note that we also gave each list item containing controller information a class name of <code>gamepad</code>. We'll explain what this is for later.</p> +Note that we also gave each list item containing controller information a class name of `gamepad`. We'll explain what this is for later. -<p>The last thing to do here is set the <code>initialRun</code> variable to <code>false</code>, as the initial run is now over.</p> +The last thing to do here is set the `initialRun` variable to `false`, as the initial run is now over. -<h3 id="Gamepad_events">Gamepad events</h3> +### Gamepad events -<p>To finish off this section, we'll look at the gamepad-associated events. There are two we need concern ourselves with — {{event("gamepadconnected")}} and {{event("gamepaddisconnected")}} — and it is fairly obvious what they do.</p> +To finish off this section, we'll look at the gamepad-associated events. There are two we need concern ourselves with — {{event("gamepadconnected")}} and {{event("gamepaddisconnected")}} — and it is fairly obvious what they do. -<p>At the end of our example we first include the <code>removeGamepads()</code> function:</p> +At the end of our example we first include the `removeGamepads()` function: -<pre class="brush: js">function removeGamepads() { +```js +function removeGamepads() { var gpLi = document.querySelectorAll('.gamepad'); - for(var i = 0; i < gpLi.length; i++) { + for(var i = 0; i < gpLi.length; i++) { list.removeChild(gpLi[i]); } reportGamepads(); -}</pre> +} +``` -<p>This function simply grabs references to all list items with a class name of <code>gamepad</code>, and removes them from the DOM. Then it re-runs <code>reportGamepads()</code> to populate the list with the updated list of connected controllers.</p> +This function simply grabs references to all list items with a class name of `gamepad`, and removes them from the DOM. Then it re-runs `reportGamepads()` to populate the list with the updated list of connected controllers. -<p><code>removeGamepads()</code> will be run each time a gamepad is connected or disconnected, via the following event handlers:</p> +`removeGamepads()` will be run each time a gamepad is connected or disconnected, via the following event handlers: -<pre class="brush: js">window.addEventListener('gamepadconnected', function(e) { +```js +window.addEventListener('gamepadconnected', function(e) { info.textContent = 'Gamepad ' + e.gamepad.index + ' connected.'; if(!initialRun) { setTimeout(removeGamepads, 1000); @@ -144,25 +149,27 @@ if(navigator.getVRDisplays && navigator.getGamepads) { window.addEventListener('gamepaddisconnected', function(e) { info.textContent = 'Gamepad ' + e.gamepad.index + ' disconnected.'; setTimeout(removeGamepads, 1000); -});</pre> +}); +``` -<p>We have <code>setTimeout()</code> calls in place here — like we did with the initialization code at the top of the script — to make sure that the gamepads are ready to report their information when <code>reportGamepads()</code> is called in each case.</p> +We have `setTimeout()` calls in place here — like we did with the initialization code at the top of the script — to make sure that the gamepads are ready to report their information when `reportGamepads()` is called in each case. -<p>But there's one more thing to note — you'll see that inside the <code>gamepadconnected</code> handler, the timeout is only run if <code>initialRun</code> is <code>false</code>. This is because if your gamepads are connected when the document first loads, <code>gamepadconnected</code> is fired once for each gamepad, therefore <code>removeGamepads()</code>/<code>reportGamepads()</code> will be run several times. This could lead to inaccurate results, therefore we only want to run <code>removeGamepads()</code> inside the <code>gamepadconnected</code> handler after the initial run, not during it. This is what <code>initialRun</code> is for.</p> +But there's one more thing to note — you'll see that inside the `gamepadconnected` handler, the timeout is only run if `initialRun` is `false`. This is because if your gamepads are connected when the document first loads, `gamepadconnected` is fired once for each gamepad, therefore `removeGamepads()`/`reportGamepads()` will be run several times. This could lead to inaccurate results, therefore we only want to run `removeGamepads()` inside the `gamepadconnected` handler after the initial run, not during it. This is what `initialRun` is for. -<h2 id="Introducing_a_real_demo">Introducing a real demo</h2> +## Introducing a real demo -<p>Now let's look at the Gamepad API being used inside a real WebVR demo. You can find this demo at <a href="https://github.com/mdn/webvr-tests/tree/master/raw-webgl-controller-example">raw-webgl-controller-example</a> (<a href="https://mdn.github.io/webvr-tests/raw-webgl-controller-example/">see it live here also</a>).</p> +Now let's look at the Gamepad API being used inside a real WebVR demo. You can find this demo at [raw-webgl-controller-example](https://github.com/mdn/webvr-tests/tree/master/raw-webgl-controller-example) ([see it live here also](https://mdn.github.io/webvr-tests/raw-webgl-controller-example/)). -<p>In exactly the same way as our <a href="https://github.com/mdn/webvr-tests/tree/master/raw-webgl-example">raw-webgl-example</a> (see <a href="/en-US/docs/Web/API/WebVR_API/Using_the_WebVR_API">Using the WebVR API</a> for details), this renders a spinning 3D cube, which you can choose to present in a VR display. The only difference is that, while in VR presenting mode, this demo allows you to move the cube by moving a VR controller (the original demo moves the cube as you move your VR headset).</p> +In exactly the same way as our [raw-webgl-example](https://github.com/mdn/webvr-tests/tree/master/raw-webgl-example) (see [Using the WebVR API](/en-US/docs/Web/API/WebVR_API/Using_the_WebVR_API) for details), this renders a spinning 3D cube, which you can choose to present in a VR display. The only difference is that, while in VR presenting mode, this demo allows you to move the cube by moving a VR controller (the original demo moves the cube as you move your VR headset). -<p>We'll explore the code differences in this version below — see <a href="https://github.com/mdn/webvr-tests/blob/master/raw-webgl-controller-example/webgl-demo.js">webgl-demo.js</a>.</p> +We'll explore the code differences in this version below — see [webgl-demo.js](https://github.com/mdn/webvr-tests/blob/master/raw-webgl-controller-example/webgl-demo.js). -<h3 id="Accessing_the_gamepad_data">Accessing the gamepad data</h3> +### Accessing the gamepad data -<p>Inside the <code>drawVRScene()</code> function, you'll find this bit of code:</p> +Inside the `drawVRScene()` function, you'll find this bit of code: -<pre class="brush: js">var gamepads = navigator.getGamepads(); +```js +var gamepads = navigator.getGamepads(); var gp = gamepads[0]; if(gp) { @@ -172,15 +179,17 @@ if(gp) { if(poseStatsDisplayed) { displayPoseStats(gpPose); } -}</pre> +} +``` -<p>Here we get the connected gamepads with {{domxref("Navigator.getGamepads")}}, then store the first gamepad detected in the <code>gp</code> variable. As we only need one gamepad for this demo, we'll just ignore the others.</p> +Here we get the connected gamepads with {{domxref("Navigator.getGamepads")}}, then store the first gamepad detected in the `gp` variable. As we only need one gamepad for this demo, we'll just ignore the others. -<p>The next thing we do is to get the {{domxref("GamepadPose")}} object for the controller stored in gpPose (by querying {{domxref("Gamepad.pose")}}), and also store the current gamepad position and orientation for this frame in variables so they are easuy to access later. We also display the post stats for this frame in the DOM using the <code>displayPoseStats()</code> function. All of this is only done if <code>gp</code> actually has a value (if a gamepad is connected), which stops the demo erroring if we don't have our gamepad connected.</p> +The next thing we do is to get the {{domxref("GamepadPose")}} object for the controller stored in gpPose (by querying {{domxref("Gamepad.pose")}}), and also store the current gamepad position and orientation for this frame in variables so they are easuy to access later. We also display the post stats for this frame in the DOM using the `displayPoseStats()` function. All of this is only done if `gp` actually has a value (if a gamepad is connected), which stops the demo erroring if we don't have our gamepad connected. -<p>Slightly later in the code, you can find this block:</p> +Slightly later in the code, you can find this block: -<pre class="brush: js">if(gp && gpPose.hasPosition) { +```js +if(gp && gpPose.hasPosition) { mvTranslate([ 0.0 + (curPos[0] * 15) - (curOrient[1] * 15), 0.0 + (curPos[1] * 15) + (curOrient[0] * 15), @@ -198,17 +207,19 @@ if(gp) { 0.0, -15.0 ]); -}</pre> +} +``` -<p>Here we alter the position of the cube on the screen according to the {{domxref("GamepadPose.position","position")}} and {{domxref("GamepadPose.orientation","orientation")}} data received from the connected controller. These values (stored in <code>curPos</code> and <code>curOrient</code>) are {{domxref("Float32Array")}}s containing the X, Y, and Z values (here we are just using [0] which is X, and [1] which is Y).</p> +Here we alter the position of the cube on the screen according to the {{domxref("GamepadPose.position","position")}} and {{domxref("GamepadPose.orientation","orientation")}} data received from the connected controller. These values (stored in `curPos` and `curOrient`) are {{domxref("Float32Array")}}s containing the X, Y, and Z values (here we are just using \[0] which is X, and \[1] which is Y). -<p>If the <code>gp</code> variable has a <code>Gamepad</code> object inside it and it can return position values (<code>gpPose.hasPosition</code>), indicating a 6DoF controller, we modify the cube position using position and orientation values. If only the former is true, indicating a 3DoF controller, we modify the cube position using the orientation values only. If there is no gamepad connected, we don't modify the cube position at all.</p> +If the `gp` variable has a `Gamepad` object inside it and it can return position values (`gpPose.hasPosition`), indicating a 6DoF controller, we modify the cube position using position and orientation values. If only the former is true, indicating a 3DoF controller, we modify the cube position using the orientation values only. If there is no gamepad connected, we don't modify the cube position at all. -<h3 id="Displaying_the_gamepad_pose_data">Displaying the gamepad pose data</h3> +### Displaying the gamepad pose data -<p>In the <code>displayPoseStats()</code> function, we grab all of the data we want to display out of the {{domxref("GamepadPose")}} object passed into it, then print them into the UI panel that exists in the demo for displaying such data:</p> +In the `displayPoseStats()` function, we grab all of the data we want to display out of the {{domxref("GamepadPose")}} object passed into it, then print them into the UI panel that exists in the demo for displaying such data: -<pre class="brush: js">function displayPoseStats(pose) { +```js +function displayPoseStats(pose) { var pos = pose.position; var orient = pose.orientation; var linVel = pose.linearVelocity; @@ -242,15 +253,14 @@ if(gp) { } else { angAccStats.textContent = 'Angular acceleration not reported'; } -}</pre> +} +``` -<p>This article has given you a very basic idea of how to use the Gamepad Extensions to use VR controllers inside WebVR apps. In a real app you'd probably have a much more complex control system in effect, with controls assigned to the buttons on the VR controllers, and the display being affected by both the display pose and the controller poses simultaneously. Here however, we just wanted to isolate the pure Gamepad Extensions parts of that.</p> +This article has given you a very basic idea of how to use the Gamepad Extensions to use VR controllers inside WebVR apps. In a real app you'd probably have a much more complex control system in effect, with controls assigned to the buttons on the VR controllers, and the display being affected by both the display pose and the controller poses simultaneously. Here however, we just wanted to isolate the pure Gamepad Extensions parts of that. -<h2 id="See_also">See also</h2> +## See also -<ul> - <li><a href="/en-US/docs/Web/API/WebVR_API">WebVR API</a></li> - <li><a href="/en-US/docs/Web/API/Gamepad_API">Gamepad API</a></li> - <li><a href="/en-US/docs/Web/API/WebVR_API/Using_the_WebVR_API">Using the WebVR API</a></li> - <li><a href="/en-US/docs/Games/Techniques/Controls_Gamepad_API">Implementing controls using the Gamepad API</a></li> -</ul> +- [WebVR API](/en-US/docs/Web/API/WebVR_API) +- [Gamepad API](/en-US/docs/Web/API/Gamepad_API) +- [Using the WebVR API](/en-US/docs/Web/API/WebVR_API/Using_the_WebVR_API) +- [Implementing controls using the Gamepad API](/en-US/docs/Games/Techniques/Controls_Gamepad_API) |