[x3d-public] SAI browser options vs. properties

[Andreas Plesch]

I am going through the spec. with regards to SAI use of browser
options and browser properties, and find that there seem to be gaps
and some oversights.

Starting with Table 9.2 in

https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/networking.html#t-BrowserProperties

the table and section is called Browser options but the url anchor is
called BrowserProperties. Also, the section 9.2.4 seems misplaced in
the Networking component, as there does not appear to be a
recognizable relevance to urls or networking.

Continuing to the abstract SAI spec., the setBrowserOption definition
at section 6.3.26 in

https://www.web3d.org/documents/specifications/19775-2/V3.3/Part02/servRef.html#setBrowserOption

then refers to Table 9.2 as options which is consistent.

In, addition there is a set of browser properties (really
capabilities) defined in

https://www.web3d.org/documents/specifications/19775-2/V3.3/Part02/servRef.html#getBrowserProperties

and Rendering Properties (hardware limits) defined in

https://www.web3d.org/documents/specifications/19775-2/V3.3/Part02/servRef.html#getRenderingProperties

For some reason the Javascript SAI does not seem to have equivalent
browser properties or functions: The tables 7.2 and 7.3 do not list
anything related in

https://www.web3d.org/documents/specifications/19777-1/V3.3/Part1/functions.html#BrowserServices

However, the abstract-to-js mapping table 5.2.4 in

https://www.web3d.org/documents/specifications/19777-1/V3.3/Part1/tables.html#BrowserServices

lists both getRenderingProperties and getBrowserProperties js
functions. So there may be omissions in table 7.2 in the functions
chapter.
Table 5.2.4 does not list an js function for the abstract
setBrowserOption method. So it seems to missing, intentionally (see
below) or by accident.

The Java SAI does have getRenderingProperties and getBrowserProperties
both in the tables section

https://www.web3d.org/documents/specifications/19777-2/V3.0/Part2/tables.html#BrowserServices

and in the functions section

https://www.web3d.org/documents/specifications/19777-2/V3.0/Part2/functions.html#BrowserServices

However, the description of the functions is inconsistent with the
abstract SAI. The first paragraph is identical for both
getRenderingProperties and getBrowserProperties and says:

"The map will contain key/value pairs for all the available rendering
properties that may be set. A table of the standard properties is
defined in Table 9.2 Browser properties of ISO/IEC 19775-1 (see
2.[I19775]). ..."

This seems to be a copy and paste mistake. Table 9.2 is not the
correct table to refer to. The correct tables are listed in the
abstract SAI (
https://www.web3d.org/documents/specifications/19775-2/V3.3/Part02/servRef.html#t-StandardRenderingPropertyDefinitions
and
https://www.web3d.org/documents/specifications/19775-2/V3.3/Part02/servRef.html#t-StandardPropertiesDescribingExtension
). I think this may be fixed in revisions.

Similar to javascript SAI, the java SAI also does not define a
function for the abstract setBrowserOption method, either
intentionally (see below) or by accident.

In summary, there are three browser settings related SAI methods,
defined in the abstract SAI. The first method, setBrowserOption , does
not seem to be available as a function in the JS or Java SAI, probably
intentionally (see below). Also, the abstract SAI references table 9.2
which seems out of place in the Networking component, and the
section's and table's URL anchor refers to BrowserProperty rather than
BrowserOption.
The other two methods are available in the JS and Java SAI. For JS,
there seems to be an omission in tables 7.2 or 7.3, and for Java the
description refers to an incorrect table.

x_ite implements the setBrowserOption method:
https://github.com/create3000/x_ite/blob/63a3cfc9df68f5cbea1bc40e383fc90f652c40d9/src/x_ite/Browser/X3DBrowser.js#L609
in terms of a field to a Browser object. It uses the method to change
browser settings requested from its GUI.
I am wondering if there are other browsers which implement setBrowserOption ?

This review was prompted by the idea of adding a BrowserOption
"logLevel", enabling logging of routed events to the console. In
addition of SAI, attribute to the X3D element could trigger setting
BrowserOptions. In fact,

https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/networking.html#BrowserProperties

(should become #BrowserOptions) says that the way a browser option is
set, is implementation specific and lists a number of different
suggestions. This is probably the reason there is not a concrete SAI
method. Using attributes to the X3D element could therefore become a
recommended, compatible way to set a browser option.

This review does seem to suggest that a new browser option
("logLevel") in table 9.2 together with a paragraph would be simple
way to add logging capability to X3D.

-Andreas









-- 
Andreas Plesch
Waltham, MA 02453