Skip to content

Expand and revise examples section #89

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 18 commits into
base: main
Choose a base branch
from
Open

Expand and revise examples section #89

Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
e1ec3a2
fleshed out the examples and added a couple more
zachernuk Jul 8, 2024
d4850aa
Update index.html
zachernuk Jul 11, 2024
c762cf4
Update index.html
zachernuk Jul 11, 2024
f9a657b
Update index.html
zachernuk Jul 11, 2024
7c0993b
Update index.html
zachernuk Jul 11, 2024
5420d3a
Update index.html
zachernuk Jul 11, 2024
b77cce9
Update index.html
zachernuk Jul 11, 2024
3ad1e88
Update index.html
zachernuk Jul 11, 2024
5e037a9
Update the multiple-format question to reflect my best understanding …
zachernuk Jul 22, 2024
f636735
propose `stagemode` as an attribute name for the orbit-style interact…
zachernuk Jul 23, 2024
b5bfa2a
update the computation into the active voice, and reflect that it's c…
zachernuk Jul 23, 2024
9fabdc7
Update index.html
zachernuk Jul 23, 2024
aacf9b3
Update index.html
zachernuk Jul 23, 2024
d83b03f
Update index.html
zachernuk Jul 23, 2024
97f2282
Update the bounding box info to be clearer
zachernuk Jul 24, 2024
b2a7762
use aria-describedby instead of alt-text as the vehicle for accessibl…
zachernuk Jul 24, 2024
25db3a0
revised the bounding box representation to be based on two DOMPoint o…
zachernuk Aug 5, 2024
96a1258
Update the explainer with more up-to-date thinking!
zachernuk Sep 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 145 additions & 0 deletions images/bounding-box.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
167 changes: 162 additions & 5 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,68 @@ <h3>
<h2>
Examples
</h2>
<h3>
Loading and parsing
</h3>
<p>
A model element whose source path resolves to a valid resource
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure there's a lot of value to adding this example here because it's so limited (plus it doesn't really deal with "loading or parsing", just very simple error handling). Consider that, like any event handling element, the element will deal (in one way or another) with all these event handler attributes:
https://html.spec.whatwg.org/#event-handlers-on-elements,-document-objects,-and-window-objects

Also, if we end up treating these elements as akin to media elements, then we might end up using these error codes, etc.:
https://html.spec.whatwg.org/#error-codes

I'd be inclined to either rename this section "Error handling" or removing it entirely until we figure out if model is a media element.

dispatch a `load` event upon the successful fetching and
presentation of the resource data. If the asset fails to load,
for instance due to an invalid URL, a failure to fetch,
or a failure in the source format's parsing process, the user agent dispatches an
`error` event.
</p>
<aside class="example" title="Error handling">
<pre class="js">
const model = document.querySelector("model");
model.addEventListener("error", () => {
// Handle error
});
</pre>
</aside>
<h3>
Processing model contents
</h3>
<p data-cite="infra geometry-1" >
A 3D asset file contains positional data for the surfaces and objects
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The text in this section feels more like spec text than an example (it's a bit uncommon to talk about how the internals work in an example)... I wonder if we should move this or actually simplify all this into an example of usage?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@marcoscaceres I think it's not example content at all, yeah - I'll pull it out of this PR. Is there a good section name / description of this kind of content you'd recommend instead?

within it. Following the successful processing of a model resource, the
{{Model}}'s {{Model/boundingBox}} attribute references a
[[\DOMBoundingBoxReadOnly]] internal slot, which
is a nullable [=map=] of whose values are {{DOMPoint}}s.
The slot contains four entries:
</p>
<dl data-cite="infra geometry-1">
<dt>"min"</dt>
<dd>A {{DOMPoint}} representing the minimum dimension, in world
space, that the contents of a model occupies.</dd>
<dt>"max"</dt>
<dd>A {{DOMPoint}} representing the maximum dimension, in world
space, that the contents of a model occupies.</dd>
<dt>"center"</dt>
<dd>A {{DOMPoint}} representing the mean of the min and max
dimensions, in world space, of the bounding box that the contents of
a model occupies.</dd>
<dt>"radius"</dt>
<dd>A floating-point number representing the radius of effective
bounding sphere from the center of the box.
</dd>
</dl>
<p>
If a model does not contain a valid resource, the [[\DOMBoundingBoxReadOnly]] internal slot is null.
</p>
</p>
<figure>
<img alt="" src=
"images/bounding-box.svg">
<figcaption>Visual aid demonstrating the extent of an object's bounding box</figcaption>
</figure>
<aside class="note">
The bounding box and sphere is often computed based on the visible object
hierarchy on the first animation frame (if an animation is present),
and according only to the geometry information directly specified.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: "specified" by who? (can we change this to active voice?)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

updated to reflect that rendering contexts generally compute it this way - it may need to be called out as non-normative or otherwise an observation of the state of the art.

While animation effects and geometric displacement based on material
data can alter these values, it is not required to integrate them.
</aside>
<h3>
Adding a model to a document
</h3>
Expand All @@ -115,7 +177,7 @@ <h3>
document:
</p>
<pre class="html">
&lt;model src="3d-assets/car"&gt;&lt;/model&gt;
&lt;model src="3d-assets/teapot"&gt;&lt;/model&gt;
</pre>
<p>
By using content negotiation the user agent relies on the server to
Expand All @@ -125,18 +187,112 @@ <h3>
<h3>
Enabling interactivity
</h3>
<aside class="example" title="Interactive rotation">
<p>
The following example shows how to enable the interactive orbit
rotation of a model in a document:
</p>
<pre class="html">
&lt;model <b>stagemode="orbit"</b> src="3d-assets/teapot"&gt;&lt;/model&gt;
</pre>
<p>
See [orbit mode] for more details on the behavior of
orbit mode.
</p>
</aside>
<aside class="issue" data-number="20"></aside>
<h3>
Programmatic view control
</h3>
<aside class="example">
<p>
The following example shows how to use the Javascript API to control
the `entityTransform`:
</p>
<pre class="html">
&lt;model src="3d-assets/teapot"&gt;&lt;/model&gt;
&lt;script&gt;
const model = document.querySelector('model');

function update() {
requestAnimationFrame(update);
model.entityTransform = new DOMMatrix().rotate(0, performance.now()/10, 0);
}

requestAnimationFrame(update);
&lt;/script&gt;
</pre>
<p data-cite="infra geometry-1">
See {{DOMMatrix}} for more details on the methods available for
modifying the view transform.
</p>
</aside>
<h3>
Supporting multiple formats
</h3>
<aside class="example">
<p>
The following example shows a list of potential source formats
that can be selected from:
</p>
<pre class="html">
&lt;model&gt;
&lt;source src="3d-assets/teapot.usdz" type="model/vnd.pixar.usd"&gt;
&lt;source src="3d-assets/teapot.gltf" type="model/gltf-binary"&gt;
&lt;/model&gt;
</pre>
`&lt;model&gt;` source selection follows `&lt;video&gt;` selection,
where the top-level `src` attribute takes precedence if present,
followed by the first compatible `&lt;source&gt;` element encountered.
</aside>
<aside class="issue" data-number="21"></aside>
<h3>
Providing fallback content for legacy user agents
</h3>
<aside class="example">
<p>
The following example shows the inclusion of fallback content:
</p>
<pre class="html">
&lt;model&gt;
&lt;source src="3d-assets/teapot"&gt;
&lt;img src="images/teapot-fallback-thumbnail.png"&gt;
&lt;/model&gt;
</pre>
</aside>
<aside class="issue" data-number="22"></aside>
<h3>
Providing an image-based light (IBL)
</h3>
<aside class="example">
<p>
The following example shows the inclusion of a custom image-based
light
</p>
<pre class="html">
&lt;model environmentmap="images/teahouse-interior-1k.hdr"&gt;
&lt;source src="3d-assets/teapot" &gt;
&lt;/model&gt;
</pre>
</aside>
<h3>
Making `model` accessible
</h3>
<aside class="example">
<p>
The following example shows the inclusion of descriptive language
characterizing the appearance of the model:
</p>
<pre class="html">

&lt;figure&gt;
&lt;model alt="A gray, ceramic teapot with an innovative spout" &gt;
Copy link
Contributor

@marcoscaceres marcoscaceres Jul 23, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still think we should get rid of alt=... the html around it or inside the element provides way better and more accessible fallback content (eg., <figurecaption>).

&lt;source src="3d-assets/teapot"&gt;
&lt;/model&gt;
&lt;figcaption&gt;Note the innovative spout&lt;/figcaption&gt;
&lt;/figure&gt;
</pre>
</aside>
<aside class="issue" data-number="23"></aside>
</section>
<section>
Expand All @@ -157,8 +313,8 @@ <h2>
[=Embedded content=].
</dd>
<dd>
If the element has an `interactive` attribute: [=interactive
content=].
If the element has a relevant value for its `stagemode`
attribute: [=orbit content=].
</dd>
<dd>
[=Palpable content=].
Expand Down Expand Up @@ -198,7 +354,8 @@ <h2>
automatically when the page is loaded
</dd>
<dd>
[^model/interactive^] — Allows the user to interact with the model
[^model/stagemode^] — Specifies a mode for the user to
interact with the model within
</dd>
<dd>
[^model/crossorigin^] — How the element handles crossorigin requests
Expand Down Expand Up @@ -246,7 +403,7 @@ <h3>
<code><dfn class="element-attr" data-dfn-for="model">autoplay</dfn></code> attribute
</h3>
<h3>
<code><dfn class="element-attr" data-dfn-for="model">interactive</dfn></code> attribute
<code><dfn class="element-attr" data-dfn-for="model">stagemode</dfn></code> attribute
</h3>
<h3>
<code><dfn class="element-attr" data-dfn-for="model">controls</dfn></code> attribute
Expand Down
Loading