73 lines
3.3 KiB
Markdown
73 lines
3.3 KiB
Markdown
<link rel="stylesheet" href="/doc/style.css"/>
|
||
<link href="https://fonts.cdnfonts.com/css/montserrat" rel="stylesheet"/>
|
||
> version 1.0.0
|
||
|
||
date: 2023-03-31T19:50:20+0200 (generated by `./make doc`)
|
||
|
||
[](https://github.com/coderofsalvation/xrfragment/actions)
|
||
|
||
|
||
|
||
# `://foo.com/my3d.asset#pos=1,0,0&prio=-5`
|
||
|
||
# URI parser
|
||
|
||
> icanhazcode? yes, see [URI.hx](https://github.com/coderofsalvation/xrfragment/blob/main/src/xrfragment/URI.hx)
|
||
|
||
1. fragment URI starts with `#`
|
||
1. fragments are split by `&`
|
||
1. `=` is used to split fragment key/values
|
||
1. fragment-values are urlencoded (space becomes `+` using `encodeUriComponent` e.g.)
|
||
1. every recognized fragment key/value-pair is added to a central map/associative array/object
|
||
|
||
# XR Fragments (key/value params)
|
||
|
||
> ⛁ = define in 3D asset-file (as custom property or default projection)<br>
|
||
> ☇ = mutable, using navigator URI (`document.location.href` e.g.)<br>
|
||
|
||
| param | type | scope(s) | category | notes |
|
||
|---------|---------------|-------|--------------------|---------------------------------|
|
||
| prio | int (-10..1) | ⛁ | Asset loading / linking | \#static allow client to ignore lower-prio objects in the renderloop, to compensate frame-drop/cpu/gpu-overload scenario’soc/notes/prio.md |
|
||
| pos | 3D vector | ⛁ ☇ |HREF navigation/portals | |
|
||
| q | string | ⛁ |Query Selector | |
|
||
|
||
|
||
# XR Fragments parser
|
||
note: community parsers will prolly outperform this initial parser :)
|
||
> icanhazcode? yes, see [Parser.hx](https://github.com/coderofsalvation/xrfragment/blob/main/src/xrfragment/Parser.hx)
|
||
|
||
the gist of it:
|
||
1. each key has a regex to validate its value-type (see regexes)
|
||
1. `|` is used to split multiple/fallback values
|
||
1. `,` assumes 1D/2D/3D vector-values like x[,y[,z]]
|
||
1. parseFloat(..) and parseInt(..) is applied to vector/float and int values
|
||
1. anything else will be treated as string-value
|
||
1. incompatible value-types will be dropped / not used
|
||
|
||
> the xrfragment specification should stay simple enough
|
||
> for anyone to write a parser using either regexes or grammar/lexers
|
||
> therefore expressions/comprehensions are not supported (max wildcard/comparison operators for queries e.g.)
|
||
|
||
# Parser Value types
|
||
|
||
| type | info | format | example |
|
||
|------|------|--------|----------------------------------|
|
||
|vector| x,y,z| comma-separated | #pos=1,2,3 |
|
||
|string| color| FFFFFF (hex) | #fog=5m,FFAACC |
|
||
|string| | | #q=-sun |
|
||
|int | | [-]x[xxxxx] | #price:>=100 |
|
||
|float | | [-]x[.xxxx] (ieee)| #prio=-20 |
|
||
|array | mixed| \|-separated | #pos=0,0,0\|90,0,0 |
|
||
|
||
> rule for thumb: type-limitations will piggyback JSON limitations (IEEE floatsize e.g.)
|
||
|
||
1. hex colors are detected using regex `/^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/`
|
||
1. integers are detected using regex `/^[0-9]+$/`
|
||
1. floats are detected using regex `/^[0-9]+\.[0-9]+$/`
|
||
1. vectors are detected using regex `/[,]/` (but can also be an string referring to an entity-ID in the asset)
|
||
1. anything else is string `/.*/`
|
||
|
||
# Tests
|
||
|
||
the spec is tested with [JSON unittests](./../src/spec) consumed by [Test.hx](./../src/Test.hx) to cross-test all languages.
|