Extensible 3D (X3D)
Part 1: Architecture and base components
Annex L
(informative)
HTML authoring guidelines
L.1 Introduction and table of contentsThis annex describes basic X3D scene integration within an HTML page and provides guidelines for X3D browser implementers when targeting HTML environments [W3C-HTML5]. These recommended practices are intended to encourage use of X3D models compatibly with HTML pages when used in a single Web X3D browser.
Table L.1 lists the major topics in this annex.
L.2 X3D implementations in HTML X3D browsersThe Hypertext Markup Language (HTML) is the World Wide Web’s core markup language. HTML is a general description language for documents and online applications [W3C-HTML5]. As part of HTML, the Document Object Model (DOM) defines a string-based node tree for representing HTML or XML documents, and also defines event-based processing methods that can be implemented by multiple programming languages [W3C-DOM] [W3C-HTML5].
This document specifies a general-purpose architecture for publishing and sharing 3D graphics models. Since X3D utilizes Web standards and includes an XML file encoding, it is well suited for integration in HTML pages over the World Wide Web.
The X3D design supports multiple goals related to use with HTML/DOM:
These general guidelines for X3D model display and interaction as part of Web-page presentations allow continuing innovation and adaptability.
L.3 Page integrationThere are two basic approaches to loading X3D models within HTML pages:
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.
There are also two basic approaches for the visual presentation of X3D models: either
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 scene presentation.
HTML has two syntax definitions: HTML syntax (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 document .
The reserved id attribute on each X3D node can be considered a unique identifier when used as part of an encompassing HTML/DOM context. Any id identifiers are in a distinct separate namespace from X3D DEF identifiers and thus are not applicable for USE nodes, ROUTE statements, or Script references.
Cascading Style Sheets (CSS) is a language for describing the rendering of structured documents (such as HTML and XML) on various display surfaces including screen and paper. CSS is a core language for the World Wide Web that is commonly used for separation of content and presentation, improving layout flexibility.
Design goals for using CSS with X3D include achieving levels of functionality similar to that which exists for using CSS with HTML.
CSS comprises multiple specifications listed in the latest version of CSS Snapshot Recommendation [W3C-CSS-Snapshot]. CSS can be applied and used for Web pages using HTML syntax or XHTML syntax [W3C-HTML5], Scalable Vector Graphics (SVG) [W3C-SVG], and Extensible Markup Language (XML) [W3C-XML] documents, such as models defined using the X3D XML encoding in ISO/IEC 19776-1.
The reserved class attribute on each X3D node can provide a space-separated list of classes that pertain from associated stylesheets.
The reserved style attribute on each X3D node permits direct definition of style information, rather than referring to styles defined in a separate document [W3C-CSS-Style] [W3C-CSS-Snapshot].
CSS styling of X3D models follows the specific styling of the parent media element on the HTML page.
The CSS style attribute is not used to override the FontStyle/ScreenFontStyle style field, which is reserved for native X3D style definitions. Instead the parent Text node's CSS style attribute can be used to override FontStyle/ScreenFontStyle styling, if appropriate and supported.
Cross-origin resource sharing (CORS) "is a mechanism that allows restricted resources on a web page to be requested from another domain, outside the domain from which the first resource was served."
"CORS defines a way in which a X3D browser and server can interact to determine whether it is safe to allow the cross-origin request." HTML Web X3D browser limitations may similarly restrict loading remote content (such as an JavaScript X3D browser) from a remote system. Restrictions apply for any combination of locally served content and remotely served content, including local file system.
Details regarding CORS operation by a Web X3D browser are specified in [WHATWG-Fetch].
L.4 Event handling, user focus and interactionAn example approach to HTML X3D Event-Passing Connections is shown in Figure L.1, Example HTML X3D Rendering Synchronization and Event-Passing Connections. This diagram illustrates potential timing and synchronization for rendering of an HTML page and an X3D model, with possibility of event passing between them. It is important to achieve repeatable behavior and efficient rendering with interactive response to user focus.
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.
Figure L.1 — Example HTML X3D Rendering Synchronization and Event-Passing Connections
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.
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.
JavaScript is a programming language that conforms to the ECMAScript specification. The names are often used interchangeably, with ECMAScript indicating strictly specified formal definitions (see ISO/IEC 16262 Information technology — ECMAScript language specification).
Specified ECMAScript Application Programming Interface (API) capabilities for X3D Script node are defined functionally and syntactically in ISO/IEC 19775-2 X3D Scene Authoring Interface (SAI) and ISO/IEC 19776-1 — X3D ECMAScript encoding, respectively.
X3D browser implementations and language versions for JavaScript/ECMAScript engines can vary. Since X3D SAI functional requirements are carefully scoped to match the essential capabilities of this core Web programming language, a single JavaScript/ECMAScript engine can typically be used for both HTML and X3D event handling.
Within a Web X3D browser, implementations for HTML and X3D may share a single JavaScript/ECMAScript engine. Such integration is often important for both performance and synchronization issues. This consideration is especially important when considering the demanding response-time requirements of immersive interfaces and spatial body-tracking devices. To aid portability and avoid unintended overloading of variable references, it is good practice for X3D Script authors to avoid the use of variables with global scope.
User focus of attention refers to which part of an HTML page is receiving user-directed events such as selection, dragging, and text input. Such capturing of events for callback handling may seem simple but nevertheless can become quite sophisticated, and multiple approaches may be necessary since both displays and device interfaces can vary widely.
X3D provides a consistent selection and navigation interface across a wide range of devices that is based on platform-neutral definitions for model interaction. Suggested device mappings providing consistent user semantics are defined in Annex G Recommended navigation behaviours. Such flexibility is especially important when designing model displays and interactions that support user accessibility.
Web X3D browsers implementing HTML pay close attention to user focus according to [W3C-HTML5] and correspondingly direct user-driven events to appropriate sections of the document graph through the DOM [W3C-DOM]. These are the governing references regarding disposition of events according to user focus prior to receipt by the X3D render engine.
Of interest is that X3D scenes can include Background transparency field that may reveal underlying HTML content unobscured by geometry. X3D browsers may optionally pass user-driven events back to the underlying page layers for further HTML/DOM processing.