feat: avoiding enter xr btn Merge PR #236 from TiborUdvari/feat/user-…

…actionless-init

docs/_sidebar.md

@@ -7,6 +7,7 @@
 - __QUICK START__
   - [Device and Browser Support](device-support.html)
   - [Immersive Web Emulator](quick-start/emulator.md)
+  - [Tips](quick-start/tips.md)
   - [Examples](quick-start/examples.md)
 ***
 - __REFERENCE__

docs/quick-start/tips.md

@@ -0,0 +1,24 @@
+## Avoiding the Enter XR Button
+![Enter XR Button](../assets/docs/enter-ar.png)
+
+Usually, you must press a button before starting an immersive AR or VR session. This is a security measure to prevent websites from overwhelming users. However, pressing this button each time you want to test a change in your code can be tedious. 
+
+By default, p5.xr `createCanvas` will attempt to launch the session without requiring the button press. If you use the [Immersive Web Emulator](quick-start/emulator.md) or have turned off the webxr-enforce-user-activation flag in your XR device browser, this will work directly. Otherwise, you must click the button to launch the interactive session.
+
+```javascript
+function setup() {
+    createCanvas(windowWidth, windowHeight, AR);
+} 
+```
+
+If you want to see the button while coding, you can launch the session like below.
+
+```javascript
+function setup() {
+    createCanvas(windowWidth, windowHeight, AR_BUTTON);
+} 
+```
+
+To allow sketches to launch directly on your XR device browser, navigate to `chrome://flags/#webxr-enforce-user-activation` and disable that flag. Note that this option may not be available in all browsers.
+
+![Meta Quest Browser User Activation Flag](../assets/docs/webxr-user-activation.jpg)

src/p5xr/core/constants.js

@@ -1,5 +1,34 @@
 export const LEFT = 'left';
 export const RIGHT = 'right';
 
+/**
+ * One of the four possible values of a an XR session (AR, VR, AR_BUTTON or VR_BUTTON)
+ * AR and VR attempt to launch the session without user action
+ * @property {String} AR
+ * @final
+ */
 export const AR = 'AR';
+
+/**
+ * One of the four possible values of a an XR session (AR, VR, AR_BUTTON or VR_BUTTON)
+ * AR and VR attempt to launch the session without user action
+ * @property {String} VR
+ * @final
+ */
 export const VR = 'VR';
+
+/**
+ * One of the four possible values of a an XR session (AR, VR, AR_BUTTON or VR_BUTTON)
+ * AR_BUTTON and VR_BUTTON do not attempt to launch the session without user action
+ * @property {String} AR_BUTTON
+ * @final
+ */
+export const AR_BUTTON = 'AR_BUTTON';
+
+/**
+ * One of the four possible values of a an XR session (AR, VR, AR_BUTTON or VR_BUTTON)
+ * AR_BUTTON and VR_BUTTON do not attempt to launch the session without user action
+ * @property {String} VR_BUTTON
+ * @final
+ */
+export const VR_BUTTON = 'VR_BUTTON';

src/p5xr/core/p5overrides.js

@@ -21,12 +21,22 @@ import compareVersions from '../utilities/versionComparator';
 const originalCreateCanvas = p5.prototype.createCanvas;
 p5.prototype.createCanvas = function (w, h, renderer, canvas) {
   let effectiveRenderer = renderer;
-  if (renderer === constants.AR || renderer === constants.VR) {
+  const isXRNoUserAction =
+    renderer === constants.AR || renderer === constants.VR;
+  const isXRUserAction =
+    renderer === constants.AR_BUTTON || renderer === constants.VR_BUTTON;
+  if (isXRUserAction || isXRNoUserAction) {
     noLoop();
-    p5xr.instance = renderer === constants.AR ? new p5ar() : new p5vr();
+    p5xr.instance =
+      renderer === constants.AR || renderer === constants.AR_BUTTON
+        ? new p5ar()
+        : new p5vr();
     effectiveRenderer = WEBGL;
     w = windowWidth;
     h = windowHeight;
+    if (isXRNoUserAction) {
+      p5xr.instance.startXRWithoutUserAction();
+    }
   }
   originalCreateCanvas.call(
     this,

src/p5xr/core/p5xr.js

@@ -211,6 +211,15 @@ export default class p5xr {
     }
   }
 
+  /**
+   * Attempts to start an interactive session outside of the normal flow
+   * Useful for development with the Immersive Web Emulator or when a special flag is activated to bypass the need for a user action
+   */
+  startXRWithoutUserAction() {
+    this.hasImmersive = true;
+    this.__onXRButtonClicked();
+  }
+
   /**
    * This is where the actual p5 canvas is first created, and
    * the GL rendering context is accessed by p5vr.