DemiSel
/
encantar-js
Beobachten 1
Favorisieren 0
Fork 0
Code Issues 0 Pull-Requests 0 Releases 0 Wiki Aktivität
Quellcode durchsuchen

Docs: addons WIP

customisations
alemart vor 6 Monaten
Ursprung
8ed604f722
Commit
84fac41f81
3 geänderte Dateien mit 425 neuen und 0 gelöschten Zeilen
Geteilte Ansicht Diff-Statistik anzeigen
  1. 127
    0
      docs/addons/ar-button.md
  2. 120
    0
      docs/addons/ar-clickable.md
  3. 178
    0
      docs/addons/ar-video-player.md

+ 127
- 0
docs/addons/ar-button.md Datei anzeigen 

@@ -0,0 +1,127 @@
1 
+# AR Button
2 
+
3 
+An A-Frame component and primitive for creating buttons. Buttons respond to clicks and are used to perform some action. They're customizable and built on top of the [ar-clickable](./ar-clickable.md) component.
4 
+
5 
+!!! tip "Important"
6 
+
7 
+    AR Buttons **require** an [ar-pointer-tracker](../api/plugin-aframe.md#ar-pointer-tracker) in your scene!
8 
+
9 
+![AR Buttons](../img/demo-box.gif){ .responsive }
10 
+
11 
+## Properties
12 
+
13 
+| Property | Description | Default |
14 
+| -------- | ----------- | ------- |
15 
+| `enabled` | Whether or not the button is enabled. | `true` |
16 
+| `src` | The graphic of the button. If none is provided, a default graphic is used. | `""` |
17 
+| `width` | The width of the button. | `0.5` |
18 
+| `height` | The height of the button. | `0.5` |
19 
+| `color` | The color tint of the button. | `"white"` |
20 
+| `pressed-color` | The color tint of the button when pressed. | `"#ffd855"` |
21 
+| `disabled-color` | The color tint of the button when disabled. | `"gray"` |
22 
+
23 
+## Look and feel
24 
+
25 
+### Setting the text
26 
+
27 
+You can set a text by attaching the `text` component to your `<ar-button>`:
28 
+
29 
+```html
30 
+<ar-button
31 
+    width="0.75" height="0.25"
32 
+    text="value: Button; align: center; color: black; wrapCount: 15"
33 
+></ar-button>
34 
+```
35 
+
36 
+Refer to the [documentation of the text component](https://aframe.io/docs/1.7.0/components/text.html){ ._blank } for more details.
37 
+
38 
+### Changing the colors
39 
+
40 
+Changing the colors is simple to do:
41 
+
42 
+```html
43 
+<ar-button id="my-button" color="lime" pressed-color="tomato"></ar-button>
44 
+```
45 
+
46 
+### Customizing the graphic
47 
+
48 
+You can also customize the graphic of your `<ar-button>` by changing its `src` property. You'll typically set it to a query selector that refers to an image:
49 
+
50 
+```html
51 
+<ar-button id="my-button" src="#my-button-image"></ar-button>
52 
+
53 
+<!-- ... -->
54 
+
55 
+<a-assets>
56 
+  <img id="my-button-image" src="assets/my-button-image.png">
57 
+</a-assets>
58 
+```
59 
+
60 
+!!! tip "Tip: changing the graphic when pressed"
61 
+
62 
+    If you also want to change the graphic of the button when it's being pressed, set its `pressed-color` to white and employ `ar-onmousedown` and `ar-onmouseup` as follows:
63 
+
64 
+    ```html
65 
+    <ar-button pressed-color="white"
66 
+      src="#my-button-image"
67 
+      ar-onmouseup="ar-button.src: #my-button-image"
68 
+      ar-onmousedown="ar-button.src: #my-pressed-button-image"
69 
+    ></ar-button>
70 
+    ```
71 
+
72 
+## Detecting clicks
73 
+
74 
+### Using ar-onclick
75 
+
76 
+AR Buttons are built on top of [AR Clickables](./ar-clickable.md) and respond to the [same events](./ar-clickable.md#events). In particular, the `"click"` event should be listened to in order to initiate an action. The `ar-onclick` component makes that really easy:
77 
+
78 
+```html
79 
+<!-- Change the graphic of the button when it's clicked -->
80 
+<ar-button src="#image-1" ar-onclick="ar-button.src: #image-2"></ar-button>
81 
+```
82 
+
83 
+Button clicks can also affect other entities:
84 
+
85 
+```html
86 
+<!-- Make the sphere visible when clicking the button -->
87 
+<ar-button ar-onclick="_target: #sphere; visible: true"></ar-button>
88 
+<a-sphere id="sphere" position="1 0 0" visible="false"></a-sphere>
89 
+```
90 
+
91 
+Refer to the documentation of [ar-clickable](./ar-clickable.md#declarative-handlers) for details on `ar-onclick`.
92 
+
93 
+### Using JavaScript
94 
+
95 
+While `ar-onclick` is easy-to-use, it's limited to setting properties. For advanced usage, you need JavaScript. Write a component and listen to the `"click"` event as in the template below:
96 
+
97 
+```js
98 
+/*
99 
+  Usage:
100 
+  <ar-button do-something-on-click></ar-button>
101 
+*/
102 
+AFRAME.registerComponent('do-something-on-click', {
103 
+
104 
+    dependencies: [ 'ar-button' ],
105 
+
106 
+    init()
107 
+    {
108 
+        this._onclick = this._onclick.bind(this);
109 
+    },
110 
+
111 
+    play()
112 
+    {
113 
+        this.el.addEventListener('click', this._onclick);
114 
+    },
115 
+
116 
+    pause()
117 
+    {
118 
+        this.el.removeEventListener('click', this._onclick);
119 
+    },
120 
+
121 
+    _onclick()
122 
+    {
123 
+        console.log('Do something! ;)');
124 
+    },
125 
+
126 
+});
127 
+```

+ 120
- 0
docs/addons/ar-clickable.md Datei anzeigen 

@@ -0,0 +1,120 @@
1 
+# AR Clickable
2 
+
3 
+An A-Frame component that turns 3D and 2D objects into "clickables" that respond to pointer input. Registered entities will receive certain [events](#events). You can add interactivity to them by employing easy-to-use [declarative event handlers](#declarative-handlers) such as `ar-onclick`, or by [writing your own event handlers in JavaScript](#advanced-usage).
4 
+
5 
+!!! tip "Important"
6 
+
7 
+    AR Clickables **require** an [ar-pointer-tracker](../api/plugin-aframe.md#ar-pointer-tracker) in your scene!
8 
+
9 
+![AR Clickables](../img/demo-box.gif){ .responsive }
10 
+
11 
+## Properties
12 
+
13 
+| Property | Description | Default |
14 
+| -------- | ----------- | ------- |
15 
+| `enabled` | Whether or not the entity will receive certain [events](#events). | `true` |
16 
+
17 
+## Declarative handlers
18 
+
19 
+### Overview
20 
+
21 
+Declarative event handlers are components used to register event listeners that set properties. They provide an easy way to create interactivity within your HTML page. There is a component for each [event](#event):
22 
+
23 
+| Handler | Description |
24 
+| ------- | ----------- |
25 
+| `ar-onclick` | Triggered when the entity receives a `"click"` event. |
26 
+| `ar-onmousedown` | Triggered when the entity receives a `"mousedown"` event. |
27 
+| `ar-onmouseup` | Triggered when the entity receives a `"mouseup"` event. |
28 
+
29 
+*Example*
30 
+
31 
+```html
32 
+<!-- Turn a yellow box into red when clicked -->
33 
+<a-box color="yellow" ar-onclick="material.color: red"></a-box>
34 
+```
35 
+
36 
+!!! question "Where is ar-clickable?"
37 
+
38 
+    Whenever using a declarative handler, `ar-clickable` is implied. There is no need to set it explicitly.
39 
+
40 
+### Special properties
41 
+
42 
+The following special properties are used to further customize the declarative handlers:
43 
+
44 
+| Property | Description |
45 
+| -------- | ----------- |
46 
+| `_target` | Query selector to be used when setting properties on a different entity. |
47 
+| `_delay` | Delay, in milliseconds, before setting the properties. |
48 
+
49 
+!!! question "What about event-set?"
50 
+
51 
+    Declarative handlers are similar to A-Frame's event-set in their usage, but there are differences behind the scenes. Whenever working with AR Clickables, usage of the declarative handlers presented in this page is preferred.
52 
+
53 
+### Multiple handlers
54 
+
55 
+Use double-underscores (`__`) to attach multiple handlers of the same type to a single entity:
56 
+
57 
+*Example*
58 
+
59 
+```html
60 
+<!-- Turn a yellow box into red when clicked,
61 
+     and then turn it back to yellow after a second -->
62 
+<a-box color="yellow"
63 
+    ar-onclick__1="material.color: red"
64 
+    ar-onclick__2="_delay: 1000; material.color: yellow"
65 
+></a-box>
66 
+```
67 
+
68 
+## Events
69 
+
70 
+Entities with an attached `ar-clickable` receive events analogous to mouse events of the 2D web:
71 
+
72 
+| Event name | Description |
73 
+| ---------- | ----------- |
74 
+| `"click"` | The entity was clicked. |
75 
+| `"mousedown"` | Fired whenever a pointing device button is pressed while the pointer is intersecting the entity. |
76 
+| `"mouseup"` | Triggered whenever a pointing device button is released after `"mousedown"` is fired. |
77 
+
78 
+Event details:
79 
+
80 
+| Detail | Description |
81 
+| ------ | ----------- |
82 
+| `intersection` | three.js intersection object, or `null` if that is unavailable. |
83 
+| `pointer` | The [TrackablePointer](../api/trackable-pointer.md) associated with the event. |
84 
+
85 
+## Advanced usage
86 
+
87 
+You can also write your own event handlers in JavaScript as in the template below:
88 
+
89 
+```js
90 
+/*
91 
+  Usage:
92 
+  <a-box alert-on-click></a-box>
93 
+*/
94 
+AFRAME.registerComponent('alert-on-click', {
95 
+
96 
+    dependencies: [ 'ar-clickable' ],
97 
+
98 
+    init()
99 
+    {
100 
+        this._onclick = this._onclick.bind(this);
101 
+    },
102 
+
103 
+    play()
104 
+    {
105 
+        this.el.addEventListener('click', this._onclick);
106 
+    },
107 
+
108 
+    pause()
109 
+    {
110 
+        this.el.removeEventListener('click', this._onclick);
111 
+    },
112 
+
113 
+    _onclick(event)
114 
+    {
115 
+        alert('You clicked me!');
116 
+        console.log(event.detail);
117 
+    },
118 
+
119 
+});
120 
+```

+ 178
- 0
docs/addons/ar-video-player.md Datei anzeigen 

@@ -0,0 +1,178 @@
1 
+# Video Player
2 
+
3 
+An A-Frame solution for playing videos in AR. `<ar-video-player>` is tailored for AR with encantar.js. Unlike A-Frame's standard `<a-video>`, `<ar-video-player>` handles corner cases for AR and includes easy-to-use controls, so you can focus on creating your projects rather than dealing with the various technicalities and edge cases of video playback on the browser.
4 
+
5 
+<div style="text-align: center">
6 
+<iframe width="560" height="315" src="https://www.youtube.com/embed/sz4Fmf3zyho?si=e4Ry5jcYAvxPfAKe" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
7 
+</div>
8 
+
9 
+!!! tip "It's easy to use!"
10 
+
11 
+    The Video Player Add-On includes a working demo that you can easily modify. This page documents it in depth and is meant to be used as a reference.
12 
+
13 
+## Properties
14 
+
15 
+| Property | Description | Default |
16 
+| -------- | ----------- | ------- |
17 
+| `src` | Query selector of a `<video>` element. | `""` |
18 
+| `width` | Width of the player. | `2` |
19 
+| `height` | Height of the player. | `1.125` |
20 
+
21 
+!!! tip
22 
+
23 
+    Place your `<video>` tag(s) inside `<a-assets>`:
24 
+
25 
+    ```html
26 
+    <ar-root>
27 
+      <ar-video-player src="#my-video">
28 
+        <!-- ... video controls ... -->
29 
+      </ar-video-player>
30 
+    </ar-root>
31 
+
32 
+    <!-- ... -->
33 
+
34 
+    <a-assets>
35 
+      <video id="my-video" playsinline>
36 
+        <source src="assets/my-video.mp4" type="video/mp4" />
37 
+        <source src="assets/my-video.webm" type="video/webm" />
38 
+      </video>
39 
+    </a-assets>
40 
+    ```
41 
+
42 
+!!! tip "Aspect ratio"
43 
+
44 
+    Make sure that the `width` and the `height` of your `<ar-video-player>` match the aspect ratio of your video. The default size is appropriate for the commonly used 16:9 widescreen ratio.
45 
+
46 
+## Video controls
47 
+
48 
+### Overview
49 
+
50 
+You may attach the `ar-video-control` component to any [AR Button](./ar-button.md) (typically) or to any [AR Clickable](./ar-clickable.md) (in general) in order to let the user control the video with a click. What exactly happens with a click depends on the selected [action](#actions).
51 
+
52 
+Add the `ar-video-control` component to a descendant of `<ar-video-player>` as in this example:
53 
+
54 
+```html
55 
+<ar-video-player src="#my-video">
56 
+
57 
+    <!-- The play button is a descendant of ar-video-player -->
58 
+    <ar-button id="play-button" position="0 0.9 0"
59 
+        ar-video-control="action: play"
60 
+    ></ar-button>
61 
+
62 
+</ar-video-player>
63 
+```
64 
+
65 
+### Properties
66 
+
67 
+| Property | Description | Default |
68 
+| -------- | ----------- | ------- |
69 
+| `action` | The [action](#actions) to be performed. | `""` |
70 
+
71 
+### Actions
72 
+
73 
+| Action | Description |
74 
+| ------ | ----------- |
75 
+| `"play"` | Play the video. |
76 
+| `"pause"` | Pause the video. |
77 
+| `"toggle"` | Toggle the video playback. |
78 
+| `"stop"` | Pause and rewind the video. |
79 
+| `"rewind"` | Rewind the video without pausing it. |
80 
+| `"mute"` | Mute the video. |
81 
+| `"unmute"` | Unmute the video. |
82 
+| `"toggleAudio"` | Toggle the audio. |
83 
+
84 
+## Declarative handlers
85 
+
86 
+### Overview
87 
+
88 
+Declarative event handlers are components used to register event listeners that set properties. They provide an easy way to create interactivity within your HTML page. There is a component for each [event](#event):
89 
+
90 
+| Handler | Description |
91 
+| ------- | ----------- |
92 
+| `ar-onvideoplay` | Triggered when the video is played. |
93 
+| `ar-onvideopause` | Triggered when the video is paused. |
94 
+| `ar-onvideoended` | Triggered when the video reaches its end. |
95 
+
96 
+These handlers can be added to `<ar-video-player>` itself or to any of its descendants:
97 
+
98 
+```html
99 
+<!-- Make the video player translucent when not playing a video -->
100 
+<ar-video-player src="#my-video" transparent="true" opacity="0.5"
101 
+    ar-onvideoplay="opacity: 1"
102 
+    ar-onvideopause="opacity: 0.5"
103 
+    ar-onvideoended="opacity: 0.5"
104 
+>
105 
+  <!-- ... video controls ... -->
106 
+</ar-video-player>
107 
+```
108 
+
109 
+[Video controls](#video-controls) may be combined with declarative handlers for easy customization:
110 
+
111 
+```html
112 
+<!-- Make the pause button appear when the video starts playing.
113 
+     Make it disappear when the video ends or is paused. -->
114 
+<ar-video-player src="#my-video">
115 
+
116 
+    <!-- The pause button is a descendant of ar-video-player -->
117 
+    <ar-button id="pause-button" position="0 -0.9 0"
118 
+        visible="false" enabled="false"
119 
+        ar-onvideoplay="visible: true; ar-button.enabled: true"
120 
+        ar-onvideopause="visible: false; ar-button.enabled: false"
121 
+        ar-onvideoended="visible: false; ar-button.enabled: false"
122 
+        ar-video-control="action: pause"
123 
+    ></ar-button>
124 
+
125 
+</ar-video-player>
126 
+```
127 
+
128 
+### Special properties
129 
+
130 
+The following special properties are used to further customize the declarative handlers:
131 
+
132 
+| Property | Description |
133 
+| -------- | ----------- |
134 
+| `_target` | Query selector to be used when setting properties on a different entity. |
135 
+| `_delay` | Delay, in milliseconds, before setting the properties. |
136 
+
137 
+!!! question "What about event-set?"
138 
+
139 
+    Declarative handlers are similar to A-Frame's event-set in their usage, but there are differences behind the scenes. Whenever working with the Video Player, usage of the declarative handlers presented in this page is preferred.
140 
+
141 
+### Multiple handlers
142 
+
143 
+Use double-underscores (`__`) to attach multiple handlers of the same type to a single entity:
144 
+
145 
+```html
146 
+<!-- Make two animated characters show up as soon as the video reaches its end -->
147 
+<ar-video-player src="#my-video"
148 
+    ar-onvideoended__1="_target: #animated-character-1; visible: true"
149 
+    ar-onvideoended__2="_target: #animated-character-2; visible: true"
150 
+>
151 
+  <!-- ... video controls ... -->
152 
+</ar-video-player>
153 
+
154 
+<!-- ... -->
155 
+
156 
+<a-entity id="animated-character-1" visible="false" ... ></a-entity>
157 
+<a-entity id="animated-character-2" visible="false" ... ></a-entity>
158 
+```
159 
+
160 
+## Events
161 
+
162 
+The `<ar-video-player>` emits the following events based on the state of the underlying `<video>` element:
163 
+
164 
+| Event name | Description |
165 
+| ---------- | ----------- |
166 
+| `"videoplay"` | Triggered whenever the video is played. |
167 
+| `"videopause"` | Triggered whenever the video is paused. |
168 
+| `"videoended"` | Triggered whenever the video reaches its end. |
169 
+
170 
+## Methods
171 
+
172 
+| Method | Description |
173 
+| ------ | ----------- |
174 
+| `invoke(action)` | Perform an [action](#video-controls). |
175 
+
176 
+## Autoplay
177 
+
178 
+Usage of the `autoplay` attribute on the `<video>` tag is discouraged. Video playback may be blocked due to browser policies and the Video Player will not show up in AR as soon as the page is loaded. It's typically better to wait for user input in order to initiate the playback, e.g., have the user click on a play button. If the page receives no user interaction, then you may still play your video as long as it's muted. See also: [artargetfound](../api/plugin-aframe.md#artargetfound) event.

Verfassen Vorschau
Laden…
Abbrechen
Speichern