浏览代码

Update docs

customisations
alemart 6 个月前
父节点
当前提交
888afb62ab

+ 1
- 1
docs/addons/ar-button.md 查看文件

6
 
6
 
7
     AR Buttons **require** an [ar-pointer-tracker](../api/plugin-aframe.md#ar-pointer-tracker) in your scene!
7
     AR Buttons **require** an [ar-pointer-tracker](../api/plugin-aframe.md#ar-pointer-tracker) in your scene!
8
 
8
 
9
-![AR Buttons](../img/demo-box.gif){ .responsive }
9
+![AR Buttons](../img/addon-buttons.gif){ .responsive }
10
 
10
 
11
 ## Properties
11
 ## Properties
12
 
12
 

+ 2
- 2
docs/addons/ar-clickable.md 查看文件

6
 
6
 
7
     AR Clickables **require** an [ar-pointer-tracker](../api/plugin-aframe.md#ar-pointer-tracker) in your scene!
7
     AR Clickables **require** an [ar-pointer-tracker](../api/plugin-aframe.md#ar-pointer-tracker) in your scene!
8
 
8
 
9
-![AR Clickables](../img/demo-box.gif){ .responsive }
9
+![AR Clickables](../img/addon-clickables.gif){ .responsive }
10
 
10
 
11
 ## Properties
11
 ## Properties
12
 
12
 
48
 
48
 
49
 !!! question "What about event-set?"
49
 !!! question "What about event-set?"
50
 
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.
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 recommended.
52
 
52
 
53
 ### Multiple handlers
53
 ### Multiple handlers
54
 
54
 

+ 13
- 12
docs/addons/ar-video-player.md 查看文件

1
 # Video Player
1
 # Video Player
2
 
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>
3
+An A-Frame component and primitive for playing videos in AR. `<ar-video-player>` is tailored for 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 and designing your projects rather than dealing with the various technicalities of video playback in the browser.
8
 
4
 
9
 !!! tip "It's easy to use!"
5
 !!! tip "It's easy to use!"
10
 
6
 
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.
7
     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
 
8
 
9
+<div style="text-align: center">
10
+<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>
11
+</div>
12
+
13
 ## Properties
13
 ## Properties
14
 
14
 
15
 | Property | Description | Default |
15
 | Property | Description | Default |
39
     </a-assets>
39
     </a-assets>
40
     ```
40
     ```
41
 
41
 
42
-!!! tip "Aspect ratio"
42
+!!! info "Aspect ratio"
43
 
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.
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
 
45
 
54
 ```html
54
 ```html
55
 <ar-video-player src="#my-video">
55
 <ar-video-player src="#my-video">
56
 
56
 
57
-    <!-- The play button is a descendant of ar-video-player -->
58
-    <ar-button id="play-button" position="0 0.9 0"
57
+    <!-- The play button is placed inside ar-video-player -->
58
+    <ar-button id="play-button" position="0 -0.9 0"
59
         ar-video-control="action: play"
59
         ar-video-control="action: play"
60
     ></ar-button>
60
     ></ar-button>
61
 
61
 
80
 | `"mute"` | Mute the video. |
80
 | `"mute"` | Mute the video. |
81
 | `"unmute"` | Unmute the video. |
81
 | `"unmute"` | Unmute the video. |
82
 | `"toggleAudio"` | Toggle the audio. |
82
 | `"toggleAudio"` | Toggle the audio. |
83
+| `""` | Do nothing. |
83
 
84
 
84
 ## Declarative handlers
85
 ## Declarative handlers
85
 
86
 
113
      Make it disappear when the video ends or is paused. -->
114
      Make it disappear when the video ends or is paused. -->
114
 <ar-video-player src="#my-video">
115
 <ar-video-player src="#my-video">
115
 
116
 
116
-    <!-- The pause button is a descendant of ar-video-player -->
117
+    <!-- The pause button is placed inside ar-video-player -->
117
     <ar-button id="pause-button" position="0 -0.9 0"
118
     <ar-button id="pause-button" position="0 -0.9 0"
118
         visible="false" enabled="false"
119
         visible="false" enabled="false"
119
         ar-onvideoplay="visible: true; ar-button.enabled: true"
120
         ar-onvideoplay="visible: true; ar-button.enabled: true"
136
 
137
 
137
 !!! question "What about event-set?"
138
 !!! question "What about event-set?"
138
 
139
 
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
+    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 recommended.
140
 
141
 
141
 ### Multiple handlers
142
 ### Multiple handlers
142
 
143
 
171
 
172
 
172
 | Method | Description |
173
 | Method | Description |
173
 | ------ | ----------- |
174
 | ------ | ----------- |
174
-| `invoke(action)` | Perform an [action](#video-controls). |
175
+| `invoke(action)` | Perform an [action](#actions). |
175
 
176
 
176
 ## Autoplay
177
 ## Autoplay
177
 
178
 
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.
179
+Usage of the `autoplay` attribute on the `<video>` tag is discouraged. Video playback may be blocked due to browser policies. In addition, the Video Player will not show up in AR at the exact moment 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.

+ 102
- 0
docs/addons/asset-manager.md 查看文件

1
+# Asset Manager
2
+
3
+A framework-agnostic solution for preloading assets such as: 3D models, video clips, audio files and more. Preloading assets is typically done in the `preload()` method when using the plugins for [babylon.js](../api/plugin-babylon.md#preload) or [three.js](../api/plugin-three.md#preload).
4
+
5
+## Methods
6
+
7
+### preload
8
+
9
+`assetManager.preload(url: string | string[], options?: object): Promise<void>`
10
+
11
+Preload one or more assets.
12
+
13
+**Arguments**
14
+
15
+* `url: string | string[]`. Absolute or relative URL(s) of the asset(s).
16
+* `options: object, optional`. An object with the following keys (all are optional):
17
+    * `timeout: number`. Timeout value, in seconds. Defaults to infinity (i.e., no timeout).
18
+
19
+**Returns**
20
+
21
+A promise that is resolved as soon as all assets are preloaded, or that is rejected on error.
22
+
23
+**Example**
24
+
25
+```js
26
+class MyDemo exports ARDemo
27
+{
28
+    // ...
29
+
30
+    preload()
31
+    {
32
+        return this._assetManager.preload([
33
+            'assets/mage.glb',
34
+            'assets/cat.glb',
35
+            'assets/meow.wav',
36
+        ], { timeout: 30 });
37
+    }
38
+
39
+    // ...
40
+
41
+    constructor()
42
+    {
43
+        super();
44
+
45
+        // ...
46
+
47
+        this._assetManager = new AssetManager();
48
+
49
+        // ...
50
+    }
51
+}
52
+```
53
+
54
+### url
55
+
56
+`assetManager.url(filename: string): string`
57
+
58
+Gets an [object URL](https://developer.mozilla.org/en-US/docs/Web/API/URL/createObjectURL_static){ ._blank } of a preloaded asset.
59
+
60
+**Arguments**
61
+
62
+* `filename: string`. The filename of the asset.
63
+
64
+**Returns**
65
+
66
+An object URL.
67
+
68
+**Example**
69
+
70
+```js
71
+// If the asset is located at "assets/mage.glb",
72
+// then its filename is "mage.glb"
73
+const mageURL = this._assetManager.url('mage.glb');
74
+```
75
+
76
+### file
77
+
78
+`assetManager.file(filename: string): File`
79
+
80
+Gets a [File](https://developer.mozilla.org/en-US/docs/Web/API/File){ ._blank } corresponding to a preloaded asset.
81
+
82
+**Arguments**
83
+
84
+* `filename: string`. The filename of the asset.
85
+
86
+**Returns**
87
+
88
+A File object.
89
+
90
+### has
91
+
92
+`assetManager.has(filename: string): boolean`
93
+
94
+Checks if an asset has been preloaded.
95
+
96
+**Arguments**
97
+
98
+* `filename: string`. The filename of the asset.
99
+
100
+**Returns**
101
+
102
+Returns `true` if an asset with the given `filename` has been preloaded.

+ 77
- 0
docs/addons/index.md 查看文件

1
+# Add-Ons
2
+
3
+Add-Ons provide an enriched experience with additional features that enhance the core of encantar.js. They're offered to supporters who purchase the various demos. Become a supporter and get exclusive access to these features!
4
+
5
+<style>
6
+.addon-container { display: flex; flex-direction: row; justify-content: space-between; align-items: center; margin: 4em 0; }
7
+.addon-container h2 { margin-top: 0; }
8
+.addon-container img { width: 100%; height: auto; }
9
+.addon-container:nth-child(2n+1) > div:nth-child(2) { min-width: 426px; margin-left: 32px; }
10
+.addon-container:nth-child(2n) > div:nth-child(2) { min-width: 426px; margin-right: 32px; order: -1; }
11
+</style>
12
+
13
+<div class="addon-container" markdown>
14
+  <div markdown>
15
+
16
+## Video Player
17
+
18
+Enchant your audience with this [easy-to-use and customizable](./ar-video-player.md) Video Player! Videos in AR are suitable for: product marketing, AR business cards, educational materials, interactive art, entertainment, and more!
19
+
20
+[I want this!](https://ko-fi.com/s/697a184728){ .md-button ._blank }
21
+
22
+  </div>
23
+  <div>
24
+    <iframe width="426" height="240" src="https://www.youtube.com/embed/sz4Fmf3zyho?si=1aI6_Odv2iebIjbL" 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>
25
+  </div>
26
+</div>
27
+
28
+<div class="addon-container" markdown>
29
+  <div markdown>
30
+
31
+## AR Buttons
32
+
33
+Add interactivity to your scenes with easy-to-use buttons for AR! You can [customize their images and colors](./ar-button.md). They're bundled with the Video Player.
34
+
35
+[I want this!](https://ko-fi.com/s/697a184728){ .md-button ._blank }
36
+
37
+  </div>
38
+  <div markdown>
39
+
40
+![AR Buttons](../img/addon-buttons.gif)
41
+
42
+  </div>
43
+</div>
44
+
45
+<div class="addon-container" markdown>
46
+  <div markdown>
47
+
48
+## AR Clickables
49
+
50
+Turn 3D and 2D objects into "clickables" that respond to touch or mouse input. AR Clickables are the building blocks of AR Buttons and are included with them.
51
+
52
+[I want this!](https://ko-fi.com/s/697a184728){ .md-button ._blank }
53
+
54
+  </div>
55
+  <div markdown>
56
+
57
+![AR Clickables](../img/addon-clickables.gif)
58
+
59
+  </div>
60
+</div>
61
+
62
+<div class="addon-container" markdown>
63
+  <div markdown>
64
+
65
+## Asset Manager
66
+
67
+Framework-agnostic solution for preloading assets such as: 3D models, video clips, audio files and more. This Add-On is bundled with the core.
68
+
69
+[I want this!](https://ko-fi.com/s/3ee4182cb6){ .md-button ._blank }
70
+
71
+  </div>
72
+  <div markdown>
73
+
74
+![Asset Manager](../img/demo-cat.gif)
75
+
76
+  </div>
77
+</div>

+ 49
- 0
docs/addons/more-addons.md 查看文件

1
+# More Add-Ons
2
+
3
+Documentation of A-Frame components bundled with the core.
4
+
5
+## ar-scan-gimmick
6
+
7
+Use `ar-scan-gimmick` to display an image in the [HUD](../api/hud.md) while the physical scene is being scanned (i.e., before an image target is tracked). Make sure to add the entity to [ar-hud](../api/plugin-aframe.md#ar-hud).
8
+
9
+*Example*
10
+
11
+```html
12
+<ar-viewport>
13
+  <ar-hud>
14
+
15
+    <!-- ar-scan-gimmick is part of the HUD -->
16
+    <ar-scan-gimmick></ar-scan-gimmick>
17
+
18
+  </ar-hud>
19
+</ar-viewport>
20
+```
21
+
22
+### Properties
23
+
24
+| Property | Description | Default |
25
+| -------- | ----------- | ------- |
26
+| `opacity` | Opacity value. | `1` |
27
+| `src` | URL of an image. If none is provided, a default image is used. | `""` |
28
+
29
+## gltf-anim
30
+
31
+An easy-to-use component for animating 3D models.
32
+
33
+*Example*
34
+
35
+```html
36
+<!-- Animate a 3D model in AR -->
37
+<ar-root>
38
+  <a-entity gltf-model="#mage-model" gltf-anim="clip: Idle"></a-entity>
39
+</ar-root>
40
+```
41
+
42
+### Properties
43
+
44
+| Property | Description | Default |
45
+| -------- | ----------- | ------- |
46
+| `clip` | The name of an animation clip. | `""` |
47
+| `loop` | Whether or not the animation should loop. | `true` |
48
+| `speed` | Multiplier of the playback speed. | `1` |
49
+| `transitionDuration` | Duration, in seconds, of transitions between clips. | `0` |

二进制
docs/img/addon-buttons.gif 查看文件


二进制
docs/img/addon-clickables.gif 查看文件


二进制
docs/img/demo-box.gif 查看文件


二进制
docs/img/demo-cat.gif 查看文件


二进制
docs/img/video-player.gif 查看文件


+ 15
- 4
docs/index.md 查看文件

2
 
2
 
3
 The Augmented Reality engine that will enchant you!
3
 The Augmented Reality engine that will enchant you!
4
 
4
 
5
-:heart:{ .heart } encantar.js is an Augmented Reality technology which I develop independently. Support this work by [purchasing your copy](https://ko-fi.com/s/3ee4182cb6). You can also [become a sponsor](https://github.com/sponsors/alemart).
5
+:heart:{ .heart } encantar.js is an Augmented Reality technology which I develop independently. Support this work by [purchasing your copy](./download.md). You can also [become a sponsor](https://github.com/sponsors/alemart).
6
 
6
 
7
-[:star2: Try it!](./demos/hello-aframe/poster.html){ .md-button ._blank } [:video_game: Play a game!](./demos/basketball/poster.html){ .md-button ._blank } [:sparkles: Demos](./demos.md){ .md-button ._blank } [:books: Learn](./tutorial/introduction.md){ .md-button }
7
+<style>
8
+.md-button { padding-left: 1.5em !important; padding-right: 1.5em !important; }
9
+#gallery { display: flex; justify-content: center; }
10
+#gallery img { height: 128px; margin: 0 2px; }
11
+</style>
8
 
12
 
9
-[![Demo](./img/mage.gif)](./demos/hello-aframe/poster.html){ ._blank } [![Game](./img/basketball.gif)](./demos/basketball/poster.html){ ._blank }
13
+[:star2: Try it!](./demos/hello-aframe/poster.html){ .md-button ._blank } [:video_game: Play a game!](./demos/basketball/poster.html){ .md-button ._blank } [:sparkles: Demos](./demos.md){ .md-button ._blank } [:heart_eyes: Add-Ons](./addons/index.md){ .md-button } [:books: Learn](./tutorial/introduction.md){ .md-button }
14
+
15
+<div id="gallery">
16
+  <a href="demos/hello-aframe/poster.html" target="_blank"><img src="img/mage.gif" alt="Demo"></a>
17
+  <a href="demos/basketball/poster.html" target="_blank"><img src="img/basketball.gif" alt="Game"></a>
18
+  <a href="addons/"><img src="img/video-player.gif" alt="Video Player"></a>
19
+</div>
10
 
20
 
11
 ## Features
21
 ## Features
12
 
22
 
13
 * **Image tracking**: track detailed images such as book covers, cartoons and photos. No need of manual training!
23
 * **Image tracking**: track detailed images such as book covers, cartoons and photos. No need of manual training!
14
 * **Pointer tracking**: create interactive experiences based on touch and mouse input with an easy-to-use API.
24
 * **Pointer tracking**: create interactive experiences based on touch and mouse input with an easy-to-use API.
15
-* **Plugins**: use encantar.js with the 3D framework of your choice, including A-Frame, Babylon.js, Three.js and more!
25
+* **Plugins**: use encantar.js with the 3D framework of your choice, including: A-Frame, Babylon.js, Three.js and more!
26
+* **Add-Ons**: create rich experiences with additional features that enhance the core of encantar.js!
16
 
27
 
17
 ## Key points
28
 ## Key points
18
 
29
 

+ 16
- 8
mkdocs.yml 查看文件

50
     - 'Welcome!': 'index.md'
50
     - 'Welcome!': 'index.md'
51
     - 'Download': 'download.md'
51
     - 'Download': 'download.md'
52
     - 'Demos': 'demos.md'
52
     - 'Demos': 'demos.md'
53
+    - 'Add-Ons': 'addons/index.md'
53
     - 'Learn': 'tutorial/introduction.md'
54
     - 'Learn': 'tutorial/introduction.md'
54
     - 'API Reference': 'api/ar.md'
55
     - 'API Reference': 'api/ar.md'
55
     - 'Recommendations': 'recommendations.md'
56
     - 'Recommendations': 'recommendations.md'
58
     - 'License': 'license.md'
59
     - 'License': 'license.md'
59
   - 'Download': 'download.md'
60
   - 'Download': 'download.md'
60
   - 'Demos': 'demos.md'
61
   - 'Demos': 'demos.md'
62
+  - 'Add-Ons':
63
+    - 'Introduction': 'addons/index.md'
64
+    - 'AR Button API': 'addons/ar-button.md'
65
+    - 'AR Clickable API': 'addons/ar-clickable.md'
66
+    - 'Video Player API': 'addons/ar-video-player.md'
67
+    - 'Asset Manager API': 'addons/asset-manager.md'
68
+    - 'More Add-Ons': 'addons/more-addons.md'
61
   - 'Learn':
69
   - 'Learn':
62
     - 'Introduction': 'tutorial/introduction.md'
70
     - 'Introduction': 'tutorial/introduction.md'
63
     - 'Concepts': 'tutorial/concepts.md'
71
     - 'Concepts': 'tutorial/concepts.md'
79
       - 'Time': 'api/time-manager.md'
87
       - 'Time': 'api/time-manager.md'
80
       - 'Settings': 'api/settings.md'
88
       - 'Settings': 'api/settings.md'
81
       - 'Resolution': 'api/resolution.md'
89
       - 'Resolution': 'api/resolution.md'
90
+    - 'Plugins':
91
+      - 'A-Frame': 'api/plugin-aframe.md'
92
+      - 'Babylon.js': 'api/plugin-babylon.md'
93
+      - 'Three.js': 'api/plugin-three.md'
82
     - 'Trackers':
94
     - 'Trackers':
83
       - 'Image tracker':
95
       - 'Image tracker':
84
         - 'ImageTracker': 'api/image-tracker.md'
96
         - 'ImageTracker': 'api/image-tracker.md'
99
       - 'VideoSource': 'api/video-source.md'
111
       - 'VideoSource': 'api/video-source.md'
100
       - 'PointerSource': 'api/pointer-source.md'
112
       - 'PointerSource': 'api/pointer-source.md'
101
       - 'Source': 'api/source.md'
113
       - 'Source': 'api/source.md'
114
+    - 'Visualization':
115
+      - 'Viewport': 'api/viewport.md'
116
+      - 'HUD': 'api/hud.md'
117
+      - 'Gizmos': 'api/gizmos.md'
102
     - 'Geometry':
118
     - 'Geometry':
103
       - 'Pose': 'api/pose.md'
119
       - 'Pose': 'api/pose.md'
104
       - 'Viewer': 'api/viewer.md'
120
       - 'Viewer': 'api/viewer.md'
110
       - 'Vector3': 'api/vector3.md'
126
       - 'Vector3': 'api/vector3.md'
111
       - 'Quaternion': 'api/quaternion.md'
127
       - 'Quaternion': 'api/quaternion.md'
112
       - 'Ray': 'api/ray.md'
128
       - 'Ray': 'api/ray.md'
113
-    - 'Visualization':
114
-      - 'Viewport': 'api/viewport.md'
115
-      - 'HUD': 'api/hud.md'
116
-      - 'Gizmos': 'api/gizmos.md'
117
     - 'Events':
129
     - 'Events':
118
       - 'AREvent': 'api/ar-event.md'
130
       - 'AREvent': 'api/ar-event.md'
119
       - 'AREventListener': 'api/ar-event-listener.md'
131
       - 'AREventListener': 'api/ar-event-listener.md'
120
       - 'AREventTarget': 'api/ar-event-target.md'
132
       - 'AREventTarget': 'api/ar-event-target.md'
121
       - 'AREventType': 'api/ar-event-type.md'
133
       - 'AREventType': 'api/ar-event-type.md'
122
-    - 'Plugins':
123
-      - 'A-Frame': 'api/plugin-aframe.md'
124
-      - 'Babylon.js': 'api/plugin-babylon.md'
125
-      - 'Three.js': 'api/plugin-three.md'
126
     - 'Speedy':
134
     - 'Speedy':
127
       - 'Speedy': 'api/speedy.md'
135
       - 'Speedy': 'api/speedy.md'
128
       - 'SpeedySize': 'api/speedy-size.md'
136
       - 'SpeedySize': 'api/speedy-size.md'

正在加载...
取消
保存