coderofsalvation/xrfragment
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

finetune docs + spec

Browse source
This commit is contained in:
Leon van Kammen 2025-09-20 10:46:23 +02:00
parent d326a0cd05
commit 746762e0a8
5 changed files with 176 additions and 159 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
doc/RFC_XR_Fragments.html
View file

@ -413,7 +413,18 @@ For example, to render a portal with a preview-version of the scene, create an 3
<p><span class="index" id="idxref:6"></span>
<span class="index" id="idxref:7"></span></p>
<p>These are <strong>optional</strong> auto-loaded <a href="">side-car files</a> to enable hasslefree <a href="#XR%20Movies">XR Movies</a>.<br>
<p>Compatible 3D fileformats: <a href="https://www.khronos.org/gltf/">glTF</a>, <a href="https://openusd.org/release/spec_usdz.html">usdz</a>, <a href="https://en.wikipedia.org/wiki/Wavefront_.obj_file">obj</a>, <a href="https://www.khronos.org/collada">collada</a>, <a href="https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4">THREE.json</a>, <a href="https://en.wikipedia.org/wiki/X3D">X3D</a> e.g.
<br></p>
<p>A 3D scene-file can be considered <b>XR Fragment-compatible</b> when it contains metadata:
1. implicit: there&rsquo;s at least one object with a name (*)
2. explicit: (optional) object(s) have (level2) href extras.</p>
<blockquote>
<p>* = last wins in case of non-unique names</p>
</blockquote>
<p>There are <strong>optional</strong> auto-loaded <a href="">side-car files</a> to enable hasslefree <a href="#XR%20Movies">XR Movies</a>.<br>
they can accomodate developers or applications who (for whatever reason) must not modify the 3D scene-file (a <code>.glb</code> e.g.).</p>
<h2 id="via-href-metadata">via href metadata</h2>
@ -490,11 +501,10 @@ This can be done via (objectname/metadata) key/value-pairs in a JSON <a href="ht
</ul>
<pre><code class="language-json">{
&quot;/&quot;:
&quot;aria-description&quot;: &quot;description of scene&quot;,
},
&quot;aria-description&quot;: &quot;description of scene&quot;,
&quot;button&quot;: {
&quot;href&quot;: &quot;#roomB&quot;
&quot;href&quot;: &quot;#roomB&quot;,
&quot;aria-description&quot;: &quot;description of room&quot;
}
}
</code></pre>
@ -696,16 +706,11 @@ XR Fragments Level3 makes the 3D timeline, as well as URL-referenced files <stro
<p>controls the animation(s) of the scene (or <code>src</code> resource which contains a timeline)</p>
<p>| fragment | type | functionality |
| <b>#t</b>=start,stop | <a href="default:`#t=0,0`">[vector2]</a> | start,stop (in seconds |</p>
| <b>#t</b>=start,stop | <a href="default:`#t=0`">[vector2]</a> | start,stop (in seconds |</p>
<p>| Example Value | Explanation |
| <code>#t=1</code> | play (3D) animations from 1 seconds till end (and stop) |
| <code>#t=1,100</code> | play (3D) animations from 1 till 100 seconds (and stop) |
| <code>#t=0,0</code> | stop (3D) animations at frame 0 |</p>
<blockquote>
<p>Use [[#s 🌱]] to control playback speed</p>
</blockquote>
| <code>#t=1,100</code> | play (3D) animations from 1 till 100 seconds (and stop) |</p>
<h2 id="specify-playback-loopmode">Specify playback loopmode</h2>

23
doc/RFC_XR_Fragments.md
View file

@ -292,7 +292,16 @@ For example, to render a portal with a preview-version of the scene, create an 3
(!Level0: Files )
(!Level0: Files)
These are **optional** auto-loaded [side-car files]() to enable hasslefree [XR Movies](#XR%20Movies).<br>
Compatible 3D fileformats: [glTF](https://www.khronos.org/gltf/), [usdz](https://openusd.org/release/spec_usdz.html), [obj](https://en.wikipedia.org/wiki/Wavefront_.obj_file), [collada](https://www.khronos.org/collada), [THREE.json](https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4), [X3D](https://en.wikipedia.org/wiki/X3D) e.g.
<br>
A 3D scene-file can be considered <b>XR Fragment-compatible</b> when it contains metadata:
1. implicit: there's at least one object with a name (*)
2. explicit: (optional) object(s) have (level2) href extras.
> \* = last wins in case of non-unique names
There are **optional** auto-loaded [side-car files]() to enable hasslefree [XR Movies](#XR%20Movies).<br>
they can accomodate developers or applications who (for whatever reason) must not modify the 3D scene-file (a `.glb` e.g.).
## via href metadata
@ -363,11 +372,10 @@ This can be done via (objectname/metadata) key/value-pairs in a JSON [sidecar-fi
```json
{
"/":
"aria-description": "description of scene",
},
"aria-description": "description of scene",
"button": {
"href": "#roomB"
"href": "#roomB",
"aria-description": "description of room"
}
}
```
@ -512,15 +520,12 @@ XR Fragments Level3 makes the 3D timeline, as well as URL-referenced files **con
controls the animation(s) of the scene (or `src` resource which contains a timeline)
| fragment | type | functionality |
| <b>#t</b>=start,stop | [[vector2]] (default:`#t=0,0`) | start,stop (in seconds |
| <b>#t</b>=start,stop | [[vector2]] (default:`#t=0`) | start,stop (in seconds |
| Example Value | Explanation |
| `#t=1` | play (3D) animations from 1 seconds till end (and stop) |
| `#t=1,100` | play (3D) animations from 1 till 100 seconds (and stop) |
| `#t=0,0` | stop (3D) animations at frame 0 |
> Use [[#s 🌱]] to control playback speed
## Specify playback loopmode

232
doc/RFC_XR_Fragments.txt
View file

@ -3,7 +3,7 @@
Jens & Leon Internet Engineering Task Force L.R. van Kammen
Internet-Draft 19 September 2025
Internet-Draft 20 September 2025
Intended status: Informational
@ -42,7 +42,7 @@ Status of This Memo
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 23 March 2026.
This Internet-Draft will expire on 24 March 2026.
Copyright Notice
@ -53,7 +53,7 @@ Copyright Notice
van Kammen Expires 23 March 2026 [Page 1]
van Kammen Expires 24 March 2026 [Page 1]
Internet-Draft XR Fragments September 2025
@ -78,11 +78,11 @@ Table of Contents
6.1. XR Fragment URL Grammar . . . . . . . . . . . . . . . . . 8
7. Spatial Referencing 3D . . . . . . . . . . . . . . . . . . . 8
8. Level0: Files . . . . . . . . . . . . . . . . . . . . . . . . 9
8.1. via href metadata . . . . . . . . . . . . . . . . . . . . 9
8.1. via href metadata . . . . . . . . . . . . . . . . . . . . 10
8.2. via chained extension . . . . . . . . . . . . . . . . . . 10
8.3. via subdocuments/xattr . . . . . . . . . . . . . . . . . 10
8.4. JSON sidecar-file . . . . . . . . . . . . . . . . . . . . 11
9. Level1: URI . . . . . . . . . . . . . . . . . . . . . . . . . 11
9. Level1: URI . . . . . . . . . . . . . . . . . . . . . . . . . 12
9.1. List of URI Fragments . . . . . . . . . . . . . . . . . . 13
9.2. List of *_explicit_ metadata . . . . . . . . . . . . . . 14
10. Level2: href links . . . . . . . . . . . . . . . . . . . . . 14
@ -109,7 +109,7 @@ Table of Contents
van Kammen Expires 23 March 2026 [Page 2]
van Kammen Expires 24 March 2026 [Page 2]
Internet-Draft XR Fragments September 2025
@ -165,7 +165,7 @@ Internet-Draft XR Fragments September 2025
van Kammen Expires 23 March 2026 [Page 3]
van Kammen Expires 24 March 2026 [Page 3]
Internet-Draft XR Fragments September 2025
@ -221,7 +221,7 @@ Internet-Draft XR Fragments September 2025
van Kammen Expires 23 March 2026 [Page 4]
van Kammen Expires 24 March 2026 [Page 4]
Internet-Draft XR Fragments September 2025
@ -277,7 +277,7 @@ Internet-Draft XR Fragments September 2025
van Kammen Expires 23 March 2026 [Page 5]
van Kammen Expires 24 March 2026 [Page 5]
Internet-Draft XR Fragments September 2025
@ -333,7 +333,7 @@ Internet-Draft XR Fragments September 2025
van Kammen Expires 23 March 2026 [Page 6]
van Kammen Expires 24 March 2026 [Page 6]
Internet-Draft XR Fragments September 2025
@ -389,7 +389,7 @@ Internet-Draft XR Fragments September 2025
van Kammen Expires 23 March 2026 [Page 7]
van Kammen Expires 24 March 2026 [Page 7]
Internet-Draft XR Fragments September 2025
@ -445,7 +445,7 @@ Internet-Draft XR Fragments September 2025
van Kammen Expires 23 March 2026 [Page 8]
van Kammen Expires 24 March 2026 [Page 8]
Internet-Draft XR Fragments September 2025
@ -483,7 +483,30 @@ Internet-Draft XR Fragments September 2025
8. Level0: Files
These are *optional* auto-loaded side-car files to enable hasslefree
Compatible 3D fileformats: glTF (https://www.khronos.org/gltf/), usdz
(https://openusd.org/release/spec_usdz.html), obj
(https://en.wikipedia.org/wiki/Wavefront_.obj_file), collada
(https://www.khronos.org/collada), THREE.json
(https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4),
X3D (https://en.wikipedia.org/wiki/X3D) e.g.
A 3D scene-file can be considered <b>XR Fragment-compatible</b> when
it contains metadata: 1. implicit: there's at least one object with a
name (*) 2. explicit: (optional) object(s) have (level2) href extras.
| * = last wins in case of non-unique names
van Kammen Expires 24 March 2026 [Page 9]
Internet-Draft XR Fragments September 2025
There are *optional* auto-loaded side-car files to enable hasslefree
XR Movies (#XR%20Movies).
they can accomodate developers or applications who (for whatever
reason) must not modify the 3D scene-file (a .glb e.g.).
@ -498,14 +521,6 @@ Internet-Draft XR Fragments September 2025
*heuristics*:
van Kammen Expires 23 March 2026 [Page 9]
Internet-Draft XR Fragments September 2025
* if at least one href custom property/extra is found in a 3D scene
* The viewer should poll for the above mentioned sidecar-file
extensions (and present accordingly)
@ -535,6 +550,18 @@ Internet-Draft XR Fragments September 2025
| NOTE: in the examples below we use the href-heuristic, but also
| the .xrf. chained-extension applies here.
van Kammen Expires 24 March 2026 [Page 10]
Internet-Draft XR Fragments September 2025
myspreadsheet.ods
└── explainer.glb <--- 'href' extra [heuristic] detected inside!
├── explainer.ogg (soundtrack to play when global 3D animation starts)
@ -554,14 +581,6 @@ myspreadsheet.ods
| (https://www.lesbonscomptes.com/pxattr/index.html) for lowlevel
| access.
van Kammen Expires 23 March 2026 [Page 10]
Internet-Draft XR Fragments September 2025
8.4. JSON sidecar-file
For developers, sidecar-file can allow for defining *explicit* XR
@ -573,11 +592,10 @@ Internet-Draft XR Fragments September 2025
* experience.json <----
{
"/":
"aria-description": "description of scene",
},
"aria-description": "description of scene",
"button": {
"href": "#roomB"
"href": "#roomB",
"aria-description": "description of room"
}
}
@ -592,6 +610,14 @@ Internet-Draft XR Fragments September 2025
| In THREE.js-code this would boil down to:
van Kammen Expires 24 March 2026 [Page 11]
Internet-Draft XR Fragments September 2025
scene.userData['aria-description'] = "description of scene"
scene.getObjectByName("button").userData.href = "#roomB"
@ -608,16 +634,6 @@ Internet-Draft XR Fragments September 2025
(publishing thru a game-editor e.g.), XR Fragments *integrates all*
which allows a universal viewing experience.
van Kammen Expires 23 March 2026 [Page 11]
Internet-Draft XR Fragments September 2025
+───────────────────────────────────────────────────────────────────────────────────────────────+
│ │
│ U R N │
@ -653,23 +669,7 @@ Internet-Draft XR Fragments September 2025
van Kammen Expires 23 March 2026 [Page 12]
van Kammen Expires 24 March 2026 [Page 12]
Internet-Draft XR Fragments September 2025
@ -725,7 +725,7 @@ Internet-Draft XR Fragments September 2025
van Kammen Expires 23 March 2026 [Page 13]
van Kammen Expires 24 March 2026 [Page 13]
Internet-Draft XR Fragments September 2025
@ -781,7 +781,7 @@ Internet-Draft XR Fragments September 2025
van Kammen Expires 23 March 2026 [Page 14]
van Kammen Expires 24 March 2026 [Page 14]
Internet-Draft XR Fragments September 2025
@ -819,33 +819,29 @@ Internet-Draft XR Fragments September 2025
contains a timeline)
| fragment | type | functionality | | <b>#t</b>=start,stop |
[vector2] (default:`#t=0,0`) | start,stop (in seconds |
[vector2] (default:`#t=0`) | start,stop (in seconds |
| Example Value | Explanation | | #t=1 | play (3D) animations from 1
seconds till end (and stop) | | #t=1,100 | play (3D) animations from
1 till 100 seconds (and stop) | | #t=0,0 | stop (3D) animations at
frame 0 |
| Use [[#s 🌱]] to control playback speed
1 till 100 seconds (and stop) |
11.2. Specify playback loopmode
This compensates a missing element from Media Fragments to enable/
disable temporal looping. .
van Kammen Expires 23 March 2026 [Page 15]
Internet-Draft XR Fragments September 2025
| fragment | type | functionality | | <b>#loop</b> | string | enables
animation/video/audio loop | | <b>#-loop</b> | string | disables
animation/video/audio loop |
van Kammen Expires 24 March 2026 [Page 15]
Internet-Draft XR Fragments September 2025
11.3. Controlling embedded content
use [[URI Templates]] to control embedded media, for example a simple
@ -888,21 +884,20 @@ Internet-Draft XR Fragments September 2025
[img[objecteleport.png]]
van Kammen Expires 23 March 2026 [Page 16]
Internet-Draft XR Fragments September 2025
Usecases: * show/hide objects/buttons (menu e.g.) in front of user *
embed remote (object within) 3D file via remote URL * instance an
interactive object near the user regardless of location * instance
HUD or semi-transparent-textured-sphere (LUT) around the user
van Kammen Expires 24 March 2026 [Page 16]
Internet-Draft XR Fragments September 2025
<div class="border padding" style="border:4px solid #888"> <span
class="big hi1">#!menu</span> </div>
@ -944,21 +939,21 @@ Internet-Draft XR Fragments September 2025
5. hide the *instanced object* when clicked again (toggle
visibility)
van Kammen Expires 23 March 2026 [Page 17]
Internet-Draft XR Fragments September 2025
| *NOTE*: level2 teleportation links, as well as instancing
| mitigates the 'broken embedded image'-issue of HTML: *always*
| attaching the href-values to *a 3D (preview) object* (that way
| broken links will not break the design).
van Kammen Expires 24 March 2026 [Page 17]
Internet-Draft XR Fragments September 2025
*Example:* clicking a 3D button with title 'menu' and href (#href)-
value xrf:menu.glb?instance#t=4,5 would instance a 3D menu (menu.glb)
in front of the user, and loop its animation between from 4-5 seconds
@ -1003,16 +998,18 @@ Internet-Draft XR Fragments September 2025
* href: xrf://#|bar
| *NOTE*: sharing is limited to (internal objects) via xrf: scheme-
| only
van Kammen Expires 23 March 2026 [Page 18]
van Kammen Expires 24 March 2026 [Page 18]
Internet-Draft XR Fragments September 2025
| *NOTE*: sharing is limited to (internal objects) via xrf: scheme-
| only
12.5. xrf:// URI scheme
Prefixing the xrf: to href (#href)-values *will prevent* level2
@ -1057,18 +1054,18 @@ Internet-Draft XR Fragments September 2025
0,0,0 as camera coordinate (XR: add user-height) (example (https:
//github.com/coderofsalvation/xrfragment/blob/main/src/3rd/js/
three/navigator.js#L31]]))
3. IF a camera-object exists with name cam assume that user(camera)
position
van Kammen Expires 23 March 2026 [Page 19]
van Kammen Expires 24 March 2026 [Page 19]
Internet-Draft XR Fragments September 2025
3. IF a camera-object exists with name cam assume that user(camera)
position
14.1. UX
End-users should always have read/write access to:
@ -1117,7 +1114,10 @@ Internet-Draft XR Fragments September 2025
van Kammen Expires 23 March 2026 [Page 20]
van Kammen Expires 24 March 2026 [Page 20]
Internet-Draft XR Fragments September 2025
@ -1173,7 +1173,7 @@ Internet-Draft XR Fragments September 2025
van Kammen Expires 23 March 2026 [Page 21]
van Kammen Expires 24 March 2026 [Page 21]
Internet-Draft XR Fragments September 2025
@ -1229,7 +1229,7 @@ Internet-Draft XR Fragments September 2025
van Kammen Expires 23 March 2026 [Page 22]
van Kammen Expires 24 March 2026 [Page 22]
Internet-Draft XR Fragments September 2025
@ -1285,7 +1285,7 @@ Internet-Draft XR Fragments September 2025
van Kammen Expires 23 March 2026 [Page 23]
van Kammen Expires 24 March 2026 [Page 23]
Internet-Draft XR Fragments September 2025
@ -1341,7 +1341,7 @@ Internet-Draft XR Fragments September 2025
van Kammen Expires 23 March 2026 [Page 24]
van Kammen Expires 24 March 2026 [Page 24]
Internet-Draft XR Fragments September 2025
@ -1397,7 +1397,7 @@ Internet-Draft XR Fragments September 2025
van Kammen Expires 23 March 2026 [Page 25]
van Kammen Expires 24 March 2026 [Page 25]
Internet-Draft XR Fragments September 2025
@ -1453,7 +1453,7 @@ Internet-Draft XR Fragments September 2025
van Kammen Expires 23 March 2026 [Page 26]
van Kammen Expires 24 March 2026 [Page 26]
Internet-Draft XR Fragments September 2025
@ -1509,7 +1509,7 @@ Internet-Draft XR Fragments September 2025
van Kammen Expires 23 March 2026 [Page 27]
van Kammen Expires 24 March 2026 [Page 27]
Internet-Draft XR Fragments September 2025
@ -1565,7 +1565,7 @@ Internet-Draft XR Fragments September 2025
van Kammen Expires 23 March 2026 [Page 28]
van Kammen Expires 24 March 2026 [Page 28]
Internet-Draft XR Fragments September 2025
@ -1621,7 +1621,7 @@ Internet-Draft XR Fragments September 2025
van Kammen Expires 23 March 2026 [Page 29]
van Kammen Expires 24 March 2026 [Page 29]
Internet-Draft XR Fragments September 2025
@ -1677,7 +1677,7 @@ Internet-Draft XR Fragments September 2025
van Kammen Expires 23 March 2026 [Page 30]
van Kammen Expires 24 March 2026 [Page 30]
Internet-Draft XR Fragments September 2025
@ -1733,4 +1733,4 @@ Internet-Draft XR Fragments September 2025
van Kammen Expires 23 March 2026 [Page 31]
van Kammen Expires 24 March 2026 [Page 31]

24
doc/RFC_XR_Fragments.xml
View file

@ -307,7 +307,14 @@ For example, to render a portal with a preview-version of the scene, create an 3
</blockquote></section>
<section anchor="level0-files"><name>Level0: Files</name>
<iref item="Level0: Files"/><iref item="Level0: Files"/><t>These are <strong>optional</strong> auto-loaded <eref target="">side-car files</eref> to enable hasslefree <eref target="#XR%20Movies">XR Movies</eref>.<br />
<iref item="Level0: Files"/><iref item="Level0: Files"/><t>Compatible 3D fileformats: <eref target="https://www.khronos.org/gltf/">glTF</eref>, <eref target="https://openusd.org/release/spec_usdz.html">usdz</eref>, <eref target="https://en.wikipedia.org/wiki/Wavefront_.obj_file">obj</eref>, <eref target="https://www.khronos.org/collada">collada</eref>, <eref target="https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4">THREE.json</eref>, <eref target="https://en.wikipedia.org/wiki/X3D">X3D</eref> e.g.
<br />
</t>
<t>A 3D scene-file can be considered &lt;b&gt;XR Fragment-compatible&lt;/b&gt; when it contains metadata:
1. implicit: there's at least one object with a name (*)
2. explicit: (optional) object(s) have (level2) href extras.</t>
<blockquote><t>* = last wins in case of non-unique names</t>
</blockquote><t>There are <strong>optional</strong> auto-loaded <eref target="">side-car files</eref> to enable hasslefree <eref target="#XR%20Movies">XR Movies</eref>.<br />
they can accomodate developers or applications who (for whatever reason) must not modify the 3D scene-file (a <tt>.glb</tt> e.g.).</t>
@ -379,11 +386,10 @@ This can be done via (objectname/metadata) key/value-pairs in a JSON <eref targe
</ul>
<sourcecode type="json"><![CDATA[{
"/":
"aria-description": "description of scene",
},
"aria-description": "description of scene",
"button": {
"href": "#roomB"
"href": "#roomB",
"aria-description": "description of room"
}
}
]]>
@ -561,13 +567,11 @@ XR Fragments Level3 makes the 3D timeline, as well as URL-referenced files <stro
<section anchor="animation-s-timeline"><name>Animation(s) timeline</name>
<t>controls the animation(s) of the scene (or <tt>src</tt> resource which contains a timeline)</t>
<t>| fragment | type | functionality |
| &lt;b&gt;#t&lt;/b&gt;=start,stop | <eref target="default:`#t=0,0`">[vector2]</eref> | start,stop (in seconds |</t>
| &lt;b&gt;#t&lt;/b&gt;=start,stop | <eref target="default:`#t=0`">[vector2]</eref> | start,stop (in seconds |</t>
<t>| Example Value | Explanation |
| <tt>#t=1</tt> | play (3D) animations from 1 seconds till end (and stop) |
| <tt>#t=1,100</tt> | play (3D) animations from 1 till 100 seconds (and stop) |
| <tt>#t=0,0</tt> | stop (3D) animations at frame 0 |</t>
<blockquote><t>Use [[#s 🌱]] to control playback speed</t>
</blockquote></section>
| <tt>#t=1,100</tt> | play (3D) animations from 1 till 100 seconds (and stop) |</t>
</section>
<section anchor="specify-playback-loopmode"><name>Specify playback loopmode</name>
<t>This compensates a missing element from Media Fragments to enable/disable temporal looping. .</t>

27
index.html
View file

File diff suppressed because one or more lines are too long