[x3d-public] L.3.1 Re: Annex L HTML authoring guidelines for X3D4; naming Script versus X3DScript (combined)

Don Brutzman brutzman at nps.edu
Sat Jan 30 14:17:48 PST 2021 

BLUF: All comments resolved, here are resulting specification changes.  Marked-up version of specification attached.  Last review call for this round.

On 1/27/2021 9:39 PM, Don Brutzman wrote:
> Apologies for delay before responding, thanks for your thoroughness and patience.
> 
> Andreas, here are your 5 posts combined in one message with a few reactions interspersed.
> 
> Reference: ballot version
> 
> * X3D4 Working Draft 3 (WD3), Annex L HTML authoring guidelines
>    https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-WD3/Part01/htmlGuidelines.html
> 
> ===================================================================================
> HTML X3D Guidelines feedback: still pending
> 
>> Thanks to Andreas Plesch for great emails, we will consider his points next week.
>>
>> [5.1]    [x3d-public] L.3.1 Re: Annex L HTML authoring guidelines for X3D4; naming Script versus X3DScript
>>         http://web3d.org/pipermail/x3d-public_web3d.org/2020-December/014276.html
> 
> On 12/15/2020 1:29 AM, Andreas Plesch wrote:
>>
>> Hello Don,
>>
>> comments for section
>>
>> L.3.1 Content definition and page presentation
>>
>> It is helpful to define the two basic approaches to load X3D on a HTML
>> page initially.
>>
>> "Loading an external X3D model into a canvas portion of the HTML page."
>>
>> In reality, both approaches need to use a canvas portion/element of
>> the HTML page since this is the only way to render 3d graphics. So
>> this sentence is a bit misleading. The emphasis here should be on
>> "external". I suggest
>>
>> "Referencing an external X3D model in a HTML page media element."
>>
>> to avoid canvas, and point to similar HTML media elements such as img or video.
> 
> Sounds excellent.

"There are two basic approaches to loading X3D models within HTML pages:

Including X3D model elements within an HTML page, or else
Referencing an external X3D model in an HTML page media element."

>> "the HTML/DOM id attribute can be used for performing HTML event
>> callbacks using JavaScript."
>>
>> While being able to use the id attribute for selecting DOM nodes is
>> important, modern HTML can select nodes based on any CSS selector,
>> such as other attributes, classes, or node names. It would be expected
>> that such identification of nodes is also possible with X3D elements.
>>
>> "the HTML/DOM id attribute can be used for selecting X3D model
>> elements using JavaScript, as well as any other HTML selector."
>>
>> Selectors are defined in the HTML5 spec. (by referencing a css spec.).
> 
> Very good.  I will discuss with Dick on specification editors' teleconference and we will refine prose along the lines you suggest.

"For X3D elements appearing within HTML document source, the HTML/DOM id attribute can be used for selecting X3D model elements using HTML-page Script nodes (as can any other HTML selector such as CSS). Such node identification is similar to the use of DEF when X3D events are passed by a ROUTE connection, allowing disambiguation of specific node instances when needed."

>> "Float above/below other layers of content on the HTML page."
>>
>> I am actually not sure what to make of this option. This option of
>> representation would be considered a style of the canvas element
>> mentioned in the first option. Any element on an HTML page can be
>> styled to float above or below other layers. Consider:
>>
>> "The visual representation of X3D models on the HTML page conforms to
>> an HTML canvas, including:
>>
>> Reserve a dedicated rectangular area (similar to historic EMBED
>> element), or else
>> Float above/below other layers of content.
>> "
>>
>> Given this, the background of an X3D model can also be defined by the
>> background of a canvas style. The expected layering from bottom to top
>> would be:
>>
>> - canvas style background (default transparent)
>> - X3D background (if not null)
>>
>> It may not be necessary to fully define this layering here since it is
>> automatic given that a canvas is used for X3D rendering. It will be
>> necessary if x3d becomes independent of canvas.
> 
> Wellll, am hoping to avoid getting too involved in specific details here (especially since they may change over time).
> 
> The key point is that X3D scene background can include transparency, so full integration of 3D with hypertext layout is possible when using a careful approach to layering and layout.
> 
> We'll look at this verbiage further, thanks for discussion of points and candidate prose.

We discussed at length, only minor changes.

"There are also two basic approaches for the visual presentation of X3D models: either

* Reserve a dedicated rectangular canvas (similar to historic EMBED element), or else
* Float above/below other layers of content on the HTML page.

X3D Background transparency field allows HTML layer(s) beneath an X3D model to be visible (whether floating or fixed). This capability can support special layouts for page composition.

Each approach is expected to follow [W3C-HTML5] and [W3C-DOM] rules for page composition, and X3D rules for model definition scene presentation."

>> ..continued, -Andreas
> 
> ===================================================================================
>> [5.2]    http://web3d.org/pipermail/x3d-public_web3d.org/2020-December/014328.html
> 
> On 12/30/2020 9:30 AM, Andreas Plesch wrote:
>>
>> Hello Don,
>>
>> between the years a few continued comments on Appendix L:
>> https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-WD3/Part01/htmlGuidelines.html
>>
>> Section L.3.2
>>
>> "L.3.2 Syntax, capitalization and validation
>>
>> HTML has two encodings: HTML encoding (lower case, no self-closing
>> tags) and XHTML encoding (CamelCase capitalization, well-formed XML
>> elements).
>>
>> The naming of X3D elements and attributes match the allowed syntax of
>> HTML where they appear, i.e. matching case conventions for a given
>> HTML or XHTML encoding.
>>
>> X3D validation according to schema, DOCTYPE or other mechanisms
>> requires strict compliance to upper/lower case name definitions in
>> this specification."
>>
>> Strictly speaking, HTML encoding is case insensitive and allows lower
>> case, upper case or CamelCase. All browsers are case insensitive for
>> HTML tags, eg "<cAnVaS>" is allowed. All lower case tags are
>> informally recommended and widely used since their use avoids
>> complications. XHTML is XML and case sensitive.
> 
> OK.  I had thought X3DOM was rigorous about lower case, good to know that HTML browser is "in charge" here.
> 
> I believe HTML encoding does not allow <SelfClosingTags/> and so will recheck that.

* HTML5
   https://www.w3.org/TR/html52
   TML 5.2
   W3C Recommendation, 14 December 2017

Corrected terms:  HTML Syntax and XHTML Syntax.

"HTML has two syntax definitions: HTML syntax (lower mixed case, some restrictions on self-closing tags) and XHTML syntax (CamelCase capitalization, well-formed XML elements).

The capitalization of X3D elements and attributes shall match the allowed syntax of HTML where they appear, matching case conventions for a given HTML or XHTML syntax.

X3D model validation according to schema, DOCTYPE or other mechanisms typically requires strict compliance to upper/lower case name definitions in this specification."

> Main point to communicate is that HTML Encoding and XHTML Encoding are the governing references.
> 
>> X3D validation in HTML should therefore also allow case insensitivity.
>> eg. "<tRaNsFoRm>" would be valid. The appendix would recommend lower
>> case X3D tags in HTML as a convention.
>> If case insensitivity in HTML is not possible for validation purposes,
>> lower case would need to be explicitly required in the wording.
>> Currently, the intention of the last sentence is unclear. I think it
>> means that X3D validation is only possible in XHTML ?
> 
> Am considering that irregularly capitalized elements/attributes might always be cleaned up by a tool prior to validation, so don't want to rule it out...
> 
> but yes in general the XHTML encoding is needed for validation by X3D schema/DTD and that was the intended point to communicate.
> 
> As before Dick and I will review and finalize.

"X3D validation according to schema, DOCTYPE or other mechanisms typically requires strict compliance to upper/lower case name definitions in this specification."
  
>> .. continued, -Andreas
> 
> ===================================================================================
>> [5.3]    http://web3d.org/pipermail/x3d-public_web3d.org/2020-December/014327.html
> 
> On 12/30/2020 9:55 AM, Andreas Plesch wrote:
>>
>> https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-WD3/Part01/htmlGuidelines.html
>>
>> Section L.3.3 Cascading Style Sheets (CSS) considerations
>>
>> The content refers to the 3d model elements' styling. I think adding
>> guidelines for styling capabilities of the rectangle of X3D graphics
>> on the page would be expected as well.
>>
>> This includes outline details, z-order in layering, positioning on the
>> page, size, background style, post processing effects and other
>> capabilities.
>>
>> Consider adding a sentence like
>>
>> "The CSS styling of X3D models on the HTML page follows the styling of
>> an HTML canvas."
>>
>> would encompass all existing styling options. All web browser
>> implementations allow this styling since they are using a Canvas
>> element in the first place.
> 
> A general statement like yours is very helpful and sounds good to me.  We are being careful to avoid defining any requirements for HTML usage.

Dick and I discussion didn't continue through this point.  Adapted form of your statement:

"CSS styling of X3D models follows the specific styling of the parent media element on the HTML page."

I believe this characteristic is already a necessary outcome if we are following CSS.  It would also seem to apply to any Inline content that gets loaded.  Thus styling across composite scenes appears possible.

Still thinking we should avoid getting explicit here, these are guidelines and HTML/CSS recommendations are the controlling specification.

>> continued ...
>>
>> -Andreas
> 
> ===================================================================================
>> [5.4]    http://web3d.org/pipermail/x3d-public_web3d.org/2021-January/014345.html
> 
> 
> On 1/3/2021 8:20 PM, Andreas Plesch wrote:
>>
>> Hi Don,
>>
>> Continuing to work through appendix L, there is
>>
>> "L.4.1 HTML and X3D synchronization"
>>
>> https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-WD3/Part01/htmlGuidelines.html#HtmlEventsX3dEvents
>>
>> Given the challenging subject, let me put down first comments, and
>> then hopefully extract recommendations. Apologies for the lengthy
>> comment which arose to gather and explain the background.
>>
>> The figure L1 is a great way to introduce the subject in general terms
>> and to invite more structured thinking.
> 
> thanks.  a long time coming...
> 
>> On the HTML side, the typical developer approach does not include a
>> concept of an event cascade in the X3D sense. Events happen/are
>> fired/are dispatched, and scripts can react to them but the rendering
>> is decoupled; the web browser independently decides when to render a
>> frame, mostly trying to keep a constant 60 fps rate. On the other hand
>> there is a cascade in the sense that scripts can generate their own
>> events which are then listened to and so invoke other scripts. x3dom
>> does something like that to implement x3d events. So the two boxes in
>> the figure showing the event cycles for HTML and X3D in parallel are
>> helpful. In between the two boxes is where the synchronization occurs.
>> That makes a lot of sense. There is currently the statement: "Event
>> passing and network access can occur after each render loop." which
>> seems to come from a X3D perspective, and perhaps can be improved.
> 
> Clearer wording is always good.  Not trying to enforce jargon, just explain friendly cooperation between technologies.  8)
> 
>> The only way to access the render loop of a web browser is through the
>> DOM method "requestAnimationFrame". That method is called by the
>> browser engine whenever it feels it has time to do script processing,
>> but not more frequently than about 60 fps. In addition, DOM events are
>> generated, listened to and corresponding callbacks invoked as they
>> occur, asynchronous to rendering. Also network access is generally
>> asynchronous and callback or promise based.
> 
> Understood that this is narrowly defined, and we definitely don't want to imply how to utilize that.
> 
> Am expecting that a number of implementation approaches can meet these behavior guidelines satisfactorily.
> 
>> On the X3D side, in contrast, there is the event cascade and a well
>> defined sequence of rendering of frames. Starting from an originating
>> event (from a user interaction, or a network communication),
>> everything happens sequentially. When all processing concludes, a new
>> frame can be rendered.
>>
>> Given asynchronous HTML and sequential X3D, how is it then possible to
>> synchronize ? How do we enable sensible, and ideally reproducible
>> event passing between HTML and X3D ?
> 
> yes that is the precise goal.  with allowable relaxations on event sequencing and causality so that authors can craft stable behaviors, just was we described bounded determinism for X3D Script node.
> 
>> Let's look at x3dom and x-ite, first at passing events from HTML to
>> X3D. x3dom simply passes DOM ui events to its X3D processing as they
>> occur, after the appropriate translation of event type and data. The
>> hope is that processing of these events including their X3D cascades
>> is done before the next requestAnimationFrame call is issued by the
>> web browser. This works well, perhaps because the web browser does not
>> dispatch ui events while it is rendering webgl, and does not render
>> while it is processing X3D. In a sense, the web browser regulates
>> itself by budgeting time it uses for X3D processing (through scripts)
>> and for rendering. But there is no attempt to guarantee completing a
>> full cascade before a frame is rendered, by x3dom. I think x-ite works
>> similarly because I do not recall seeing buffering of input events, or
>> checking that a previous cascade is finished although it is possible
>> that I overlooked something.
>>
>> Now let's look at passing X3D events to HTML. x3dom optionally can
>> pass all output X3D events to HTML via its onoutputchange attribute
>> assigning a callback script to a node. The callback is invoked
>> immediately when a X3D output event occurs (most are implemented).
>> This works well because HTML does not need to wait for a render loop
>> to finish before processing, due its asynchronous event design. There
>> is no need for synchronization from the HTML side. [As a side note,
>> x3dom does not generate a real HTML DOM event; it just passes a
>> payload to the callback.] . x-ite, by itself, does not pass X3D events
>> to HTML at all. My x_ite_dom plugin adds that functionality by
>> forwarding all X3D output events as custom HTML DOM events to HTML
>> with a name and payload following X3D conventions. This leads to a lot
>> of DOM events being generated but there does not seem to be a
>> performance hit (as long as there are no listeners to the events).
>> This is implemented through the X3D SAI method "addFieldCallback" . I
>> am not sure when exactly the added field callback is supposed to be
>> invoked but probably at the end of a X3D cascade. Perhaps, however,
>> x_ite invokes it immediately when a field is changed. It does not
>> matter much since HTML expects DOM events happening at any time.
>>
>> So I think it is not quite appropriate to require that "Event passing
>> can occur after each render loop". I would suggest replacing the
>> statement in the figure with a more general statement like
>>
>> "Synchronization through event exchange and shared network access."
> 
> yes that is the fundamental relationship.
> 
>> [Networking may be another discussion.]
> 
> Well any networking is via url or Script access, on either HTML or X3D side..
> 
> .. so, interestingly, networking on each side is largely internal and relatively isolated from the other side.

Caveat already in place prior to the figure confirms that the provided approach is conceptual and not normative:

"These relationships are conceptual and not necessarily indicative of any individual implementation, in a manner similar to 'Figure 4.1 — X3D architecture and Figure 4.3 — Conceptual execution model'. Multiple design variations are permitted for HTML-X3D implementations as long as the functional requirements of relevant HTML and X3D specifications are met."

>> After the figure there is the sentence:
>>
>> "Shared HTML events and X3D events (if available) are sent and
>> received at end of each respective render cycle."
>>
>> It is nice in its symmetry and simplicity but given that HTML does not
>> really have the concept of an accessible end of a render cycle, this
>> sentence may need to be expanded or shortened.
> 
> Was thinking that even if HTML sends events in the middle of an X3D render loop, the X3D render engine is not required to process them until it is ready to do so.  So tandem draw-by-draw updates will recur.
> 
>> First, the fact that X3D gets its input events from HTML events may be
>> seen as an implementation detail (of TouchSensor, for example). So how
>> the sharing of HTML events with X3D happens may not have to be
>> detailed. If there is a desire to share all possible HTML events with
>> X3D (for example, a user resizing the Canvas), that would first
>> require specifying a X3D mechanism (perhaps through meta nodes?).
> 
> I'd say that the X3D render engine gets to decide when that effectively occurs.
> 
>> That leaves sharing of X3D events with HTML. What about replacing the
>> sentence with
>>
>> "Available X3D events are shared with the HTML engine at the end of
>> the X3D event cascade via mechanisms such as dispatching a custom HTML
>> event, or invoking an author callback." ?
> 
> OK with me, will ponder + discuss with Dick + tweak prose.

Append third sentence to paragraph following the figure:

"Shared HTML events and X3D events (if available) are sent and received at end of each respective render cycle. Once initiated, an X3D event cascade proceeds to completion before any further external events are exchanged (see 4.4.8.3 Execution model). Available X3D events are shared with the HTML engine via mechanisms such as dispatching a custom HTML event, or invoking an author-defined callback."

Also made the following paragraph stricter/unambiguous:

"Note that both HTML and X3D specifications include definitions for a Script node, so disambiguation is necessary. One possible approach is to require that X3D Script nodes can only appear between X3D elements within an HTML page, and HTML Script nodes are forbidden from appearing between X3D elements. An alternative approach is that any X3D Script node located within HTML page might be renamed X3DScript to avoid any node naming collisions."

>> A lot of words for a few smallish suggestions but hopefully this can
>> be helpful for further considerations,
>>
>> Thanks for reading,
>>
>> -Andreas
> 
> much appreciated, very helpful Andreas.

and once again thanks for continued review.

> ===================================================================================
>> [5.5]    http://web3d.org/pipermail/x3d-public_web3d.org/2021-January/014352.html
> 
> On 1/4/2021 9:53 AM, Andreas Plesch wrote:
>>
>> Hi Don,
>>
>> Please feel free to combine or divide these comments as you see fit,
>> for further consideration.
>>
>> One comment:
>>
>> On Mon, Jan 4, 2021 at 1:21 AM Don Brutzman <brutzman at nps.edu> wrote:
>>>
>>> Thanks for the many thoughtful insights Andreas.  Really useful.
>>>
>>> Dick and I will ponder, and recommend everyone do the same.  All feedback always welcome.
>>>
>>> To our great advantage: we are not legislating how current browser software engines work, rather defining long-term guidelines that serve author needs.
>>
>> Long term (5-10 years ?) guidelines for design and vision purposes are
>> useful but I do think we need to keep in mind and reference current
>> browser software behaviour and engineering in order to have some
>> actual impact on any reader of this appendix in the specification. In
>> other words, let's also have a short and medium term (1-5 years ?)
>> target. This would likely require agreeing with and accommodating
>> behaviour of current browsers.
> 
> Yes, hopefully by keeping a light touch on these Guidelines our mutual complementary HTML-X3D design will remain reasonably consistent over time.
> 
>>> Further context: coming up soon now is revision to 19775-2 X3D Scene Access Interface (SAI) as well as corresponding updates to each of the corresponding programming-language binding specification for ECMAScript, Java, Python, etc.
>>>
>>> * https://www.web3d.org/standards
>>>
>>> So with our "design hats" still on: if there are changes or additions to these APIs that can best support complementary interoperation between X3D and HTML5 across multiple modes, both for browser-based and server-based X3D, then they will be good to consider.
>>
>> Perhaps an X3D API to receive HTML browser events:
>>
>> X3DBrowser.addDOMEventListener
>>
>> modelled after
>>
>> https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener
>>
>> and conversely an API to dispatch out events as HTML DOM events,
>> similar to addFieldCallback:
>>
>> https://www.web3d.org/documents/specifications/19777-1/V3.3/Part1/functions.html#t-FieldFunctions
>>
>> field.DOMEvent
>>
>> modelled after https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent
>>
>> Cheers, -Andreas
> Yes we will definitely want to add a few minimalist method(s) to SAI that might remain unchanged over time and useful to authors who are exercising these Guidelines.

These issues appear to belong in SAI and don't need to be added here in Annex L.

> ===================================================================================
> 
> Glad that we should be able to reasonably address each of your excellent points with prose refinement, not any major rethinking/refactoring/redesign of these guidelines.
> 
> OK end is in sight, will keep pressing on to the finish line with editors review.  Again thanks.

Wow we did it.  Have fun with X3D and HTML5!  8)

all the best, Don
-- 
Don Brutzman  Naval Postgraduate School, Code USW/Br       brutzman at nps.edu
Watkins 270,  MOVES Institute, Monterey CA 93943-5000 USA   +1.831.656.2149
X3D graphics, virtual worlds, navy robotics http://faculty.nps.edu/brutzman
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Extensible 3D (X3D), ISO_IEC 19775-1_202x, Annex L HTML authoring guidelines.pdf
Type: application/pdf
Size: 378890 bytes
Desc: not available
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20210130/bcf1e17a/attachment-0001.pdf>

More information about the x3d-public mailing list