[x3d-public] (upper/lower) Case of X3D Enum values for Web Audio API nodes in X3D Sound Component

[Michalis Kamburelis]

I'd say that X3D enums should follow first and fore-most the X3D
conventions, so be uppercase.

Otherwise we'll land in unavoidable confusion. E.g. myself, as a
developer who wants to implement the new X3D sound features on top of
OpenAL and FMOD (as these are the sound libraries we support in Castle
Game Engine, https://castle-engine.io/manual_sound.php ) for desktop /
mobile / console, not on top of WebAudio (for HTML), I would found
lowercase enums weird and I would wonder whether it's a mistake in X3D
spec :)

X3D defines at various places stuff that matches other specs (like
OpenGL or glTF), and that's good!, and each time we wanted to match
X3D conventions. Small things like uppercase->lowecase can surely be
just handled by a particular implementation.

Actually, I would recommend even implementations of X3D on top of
WebAudio to *not* just take the strings from X3D and pass them to
WebAudio API. Instead, convert X3D SFString enums to your language
enums (C# enums, Pascal enums, whatever is suitable in your language),
and perform validation by the way (that the string actually matches
one of the allowed values), and only at the end convert them back to
WebAudio strings. This way you do validation in the middle, and this
way you have a clean API on the code side using your language enums.

Regards,
Michalis

pon., 12 gru 2022 o 18:34 Brutzman, Donald (Don) (CIV)
<brutzman at nps.edu> napisał(a):
>
> Thanks for your excellent comment Holger.  Captured as follows:
>
>
>
> Mantis 1411: enumeration values for Web Audio nodes do not follow CAPITALIZATION conventions
> https://www.web3d.org/member-only/mantis/view.php?id=1411
>
>
>
> Description
>
> The updated X3D Sound Component includes support for W3C Web Audio capabilities.
>
> * X3D4 Architecture, clause 16 Sound Component
> * https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-DIS/Part01/components/sound.html
>
> * Web Audio API, World Wide Web Consortium (W3C) Candidate Recommendation, 11 June 2020.
> * https://www.w3.org/TR/webaudio
>
> Examples include:
>
> ================
>
> 16.3.1 X3DSoundChannelNode
> X3DSoundChannelNode : X3DSoundNode {
>   SFString [in,out] channelCountMode "max" ["max", "clamped-max", "explicit"]
>   SFString [in,out] channelInterpretation "speakers" ["speakers", "discrete"]
>   MFNode [in,out] children NULL [X3DSoundChannelNode,X3DSoundProcessingNode,X3DSoundSourceNode]
> [...]
>
> ================
> 16.3.2 X3DSoundDestinationNode
> X3DSoundDestinationNode : X3DSoundNode {
> [...]
>   SFString [in,out] channelCountMode "max" ["max", "clamped-max", "explicit"]
>   SFString [in,out] channelInterpretation "speakers" ["speakers", "discrete"]
>
> ================
>
> 16.4.4 BiquadFilter
> BiquadFilter : X3DSoundProcessingNode {
>   SFString [in,out] channelCountMode "max" ["max", "clamped-max", "explicit"]
>   SFString [in,out] channelInterpretation "speakers" ["speakers", "discrete"]
> [...]
>   SFString [in,out] type "lowpass" ["lowpass", "highpass", "bandpass", "lowshelf",
>                                                       "highshelf", "peaking", "notch", "allpass"]
>
> ================
>
> Instead, the chosen enumerations exactly match spelling and capitalization of Web Audio API.
> * https://www.w3.org/TR/webaudio/#enumdef-channelcountmode
> * https://www.w3.org/TR/webaudio/#enumdef-channelinterpretation
>
> Question to be confirmed:
> a. change capitalization to match X3D naming conventions for enumerations, or
> b. maintain exact matches with Web Audio API to maximize interoperability and avoid errors
>
>
>
>
>
> So there is the reason why.  I think that exact matching eliminates large classes of potential future errors by implementers and authors.
>
>
>
> Thanos, Efi, Dick (co-designers) and everyone:  additional insight regarding change or confirmation welcome.
>
>
>
> 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 https:// faculty.nps.edu/brutzman
>
>
>
> From: x3d-public <x3d-public-bounces at web3d.org> On Behalf Of Holger Seelig
> Sent: Saturday, December 10, 2022 12:30 PM
> To: X3D <x3d-public at web3d.org>
> Subject: [x3d-public] Case of X3D Enum values
>
>
>
> The X3D standard defines several enum values in SFString or MFString format, all past enums are in uppercase format,. This should be standard for all future enums!
>
>
>
> Deviating therefrom the field values of „ channelCountMode“, „ channelInterpretation“, and „ type“ in the Sound component are in lowercase, wondering why this is the case.
>
>
>
> Best regards,
>
> Holger Seelig
>
>
>
> _______________________________________________
> x3d-public mailing list
> x3d-public at web3d.org
> http://web3d.org/mailman/listinfo/x3d-public_web3d.org