[x3d-public] X3DJSAIL: Many DEFs with same value

[John Carlson]

I think USE before DEF will likely break a lot of things.  What are we
trying to accommodate with the change, and can we adapt what we are trying
to accommodate?

It seems like agreeing on HAnimHumanoid and HAnimSegment MFNode and SFNode
fields ordering is a lot less intrusive than USE before DEF, but IDK.

Can we lay out potential solutions to USE before DEF for HAnim before
changing the standard?

Thanks,

John

On Fri, May 1, 2026 at 12:37 AM Don Brutzman <don.brutzman at gmail.com> wrote:

> Good observation.  Prior definition of DEF values should not matter to
> ROUTEs either.
>
> This is a recent change that has not received any negative technical
> feedback.  Browser support is still catching up.
>
> all the best, Don
> --
> X3D Graphics, Maritime Robotics, Distributed Simulation
> Relative Motion Consulting  https://RelativeMotion.info
>
>
> On Thu, Apr 30, 2026 at 9:41 PM Joe D Williams <joedwil at earthlink.net>
> wrote:
>
>> From description:
>>
>> > Note that the actual DEF node name definition
>>
>>
>>
>> Followed by:
>>
>> > NOTE   DEF names are not required to precede USE references.
>>
>>
>>
>> (in the User Code)?
>>
>>
>>
>> Wondering if this rule is any different than for ROUTE connections?
>>
>> Timers and interpolators must appear before Route can reference them.
>>
>> proto definitions before instances. Same for DEF/USE, lthe DEF must
>> appear first or else What gets put in?
>>
>> So, I don't understand that last note.
>>
>> Thanks,
>>
>> Joe
>>
>>
>>
>>
>>
>>
>>
>> -----Original Message-----
>> From: Don Brutzman <don.brutzman at gmail.com>
>> Sent: Apr 30, 2026 11:05 AM
>> To: Extensible 3D (X3D) Graphics public discussion <x3d-public at web3d.org>
>> Cc: Joe D Williams <joedwil at earthlink.net>, John Carlson <
>> yottzumm at gmail.com>
>> Subject: Re: [x3d-public] X3DJSAIL: Many DEFs with same value
>>
>>
>> Multiple duplicate DEF names in a single X3D model is a bad practice, for
>> multiple reasons.
>>
>> I've updated Scene Authoring Hints accordingly, see highlighted text
>> which follows plus additional references.  Hope this helps.
>>
>>    - X3D Scene Authoring Hints: Naming Conventions
>>    -
>>    https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#NamingConventions
>>
>> 🔖
>>> <https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#NamingConventions>
>>>  *Naming Conventions*
>>>
>>> Models are simple representations for some part of reality. Simulations
>>> show the behavior of models over time.
>>>
>>>    1. Clarity is essential when naming components to design a
>>>    meaningful model.
>>>    2. Names matter, suggesting how to think about purpose and
>>>    relationships.
>>>    3. These naming conventions are suitable for X3D scenes, XML tagset
>>>    design, accompanying HTML pages, and corresponding source code written
>>>    JavaScript/Java/Python/etc.
>>>    4. These naming conventions also match the node and field naming
>>>    conventions found in the X3D Standards
>>>    <https://www.web3d.org/x3d/progress> themselves (and elsewhere).
>>>    5. Success Metric: when is a name successful?
>>>    (Ironic) Answer: when no one has to discuss that name any more, it
>>>    is simply understood.
>>>
>>> Naming conventions are appropriate for file names, DEF node identifiers
>>> and USE node references, prototype names, unique IDs, and more.
>>>
>>> Here is a combined set of guidelines.
>>>
>>>    1. Using clear and consistent names for node names and DEF labels
>>>    greatly improves the clarity of how a scene works.
>>>    2. In effect, descriptive names can make the purpose and mechanics
>>>    of a scene self-documenting.
>>>    3. Avoid duplicate DEF
>>>    <https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#DuplicateDEF> identifier
>>>    naming as a bad practice, even when identical names might seem
>>>    reasonable when declaring a prototype in a model. The resulting model will
>>>    fail XML validation, fail semantic query, and not make sense due to unclear
>>>    definitions.  Bookmarks in X3D Documentation pages will also fail since
>>>    duplicate paragraph anchors will be present.
>>>
>>> [...]
>>
>>
>>> 🔖
>>> <https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#ProtoDeclare>
>>>  *Prototype Declarations* define a template for a new node
>>>
>>>    - Follow Naming Conventions
>>>    <https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#NamingConventions> for
>>>    node and field
>>>    <https://www.web3d.org/x3d/content/X3dTooltips.html#field>
>>>     definitions.
>>>    - Provide useful/safe default initialization values for each field,
>>>    rather than depending on default field values internal to the
>>>    ProtoBody.
>>>    - Include annotation tooltips for each field.
>>>    - Avoid copying ProtoDeclare definitions into additional scenes,
>>>    instead copy ExternProtoDeclare/ProtoInstance definitions.
>>>    - Tooltips for ProtoDeclare
>>>    <https://www.web3d.org/x3d/content/X3dTooltips.html#ProtoDeclare>,
>>>    ProtoInterface
>>>    <https://www.web3d.org/x3d/content/X3dTooltips.html#ProtoInterface>
>>>     and ProtoBody
>>>    <https://www.web3d.org/x3d/content/X3dTooltips.html#ProtoBody>
>>>    - Avoid duplicate DEF names for nodes inside multiple prototype
>>>    declarations contained in a single file. Although the DEF namespaces
>>>    contained inside each independent ProtoBody declaration are logically
>>>    independent from an X3D perspective, duplicate DEF names will provoke XML
>>>    validation errors regarding duplicate ID names. They can also easily lead
>>>    to author confusion, providing semantic ambiguity both notionally and if
>>>    performing Semantic Web Queries in Turtle.
>>>    - X3D Specification clause: Prototype Semantic
>>>    <https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/concepts.html#PrototypeSemantics>
>>>
>>> Further discussion can also be found in
>>
>>    - *X3D: Extensible 3D Graphics for Web Authors
>>    <https://x3dgraphics.com/>,* Don Brutzman and Leonard Daly, Morgan
>>    Kaufmann Publishers, Elsevier, 2007
>>    - https://x3dgraphics.com
>>    - Chapter 3 Grouping Nodes, 2. Concepts, 1.4 DEF and USE (pp 71-72)
>>
>> 2.4. DEF and USE
>>> DEF and USE names are the X3D mechanism for efficiently defining and
>>> copying a
>>> node, multiple nodes, or even groups of nodes. Copied nodes require far
>>> less memory
>>> and computation because they need only be created once. This efficiency
>>> can greatly
>>> improve rendering performance when extensively used in large scenes.
>>> When a node is given a DEF name, that name is an identification label
>>> that is unique
>>> in the file. The DEF name must start with a letter and can contain
>>> letters, numbers, and
>>> the special characters underscore, hyphen, and period. DEF names must
>>> not include
>>> whitespace or other special characters. Uppercase and lowercase
>>> alphabetic characters
>>> are considered strictly different; therefore, DEF names are case
>>> sensitive.
>>> USE names refer back to a node with a DEF name. These references allow
>>> faster and
>>> more efficient rendering of graphics objects. Note that the actual DEF
>>> node name definition
>>> must be located in the scene graph before any USE references. This
>>> permits X3D
>>> browsers to read and load a scene graph in a single pass, avoiding
>>> undefined references
>>> and thereby yielding faster parsing and loading. This performance boost
>>> not only helps
>>> when users first load a scene, but is also valuable when further
>>> subscenes are loaded
>>> within a parent scene. Authors also must be careful with animation of
>>> the fields of a DEF
>>> node, because this will equally affect all of the USE copies.
>>> When authoring large scenes, using descriptive DEF names improves
>>> clarity and
>>> helps document a model. CamelCaseNaming is a good way to accomplish
>>> this: capitalize
>>> each word, never use abbreviations, strive for clarity, and be brief but
>>> complete.
>>> Avoiding underscore characters improves readability, because
>>> pretty-print HTML versions
>>> of scenes usually hyperlink these names, and underlined hyperlinks hide
>>
>>  underscore characters from the user. ROUTE statements that connect one
>>> node’s field to
>>
>> another node’s field are much more understandable when the purpose and
>>> type of the
>>> node are evident in the DEF names themselves. Examples provided with
>>> this book strive
>>> to provide useful examples of good naming practices. ROUTE connections
>>> are covered
>>> in Chapter 7, Event Animation and Interpolation.
>>> A good rule of thumb is that a proper DEF name can be sensibly used in a
>>> sentence.
>>> For example, “The fraction_changed field of the SpinningBoxClock
>>> TimeSensor node
>>> is ROUTED to the set_fraction field of the SpinningBoxInterpolator
>>> node.” Although
>>> a bit long winded, such sentences provide a clear and sensible
>>> explanation for a given
>>> behavior.
>>
>>
>> Authoritative reference is always X3D Architecture.
>>
>>    - X3D Architecture v4.1 draft, clause 4 Concepts, 4.4.3 DEF/USE
>>    semantics
>>    -
>>    https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/concepts.html#DEF_USE_Semantics
>>
>> 4.4.3 DEF/USE semantics
>>>
>>> Node DEF names are limited in scope to a single X3D file, prototype
>>> definition, or string submitted to either CreateX3DFromString,
>>> CreateX3DFromStream, or CreateX3DFromURL X3D browser service (as specified
>>> in ISO/IEC 19775-2
>>> <https://www.web3d.org/specifications/X3Dv4Draft/references.html#I19775_2>
>>> ).
>>>
>>> The USE statement does not create a copy of the node identified by a DEF
>>> name. Instead, the same node is inserted into the scene graph a second
>>> time, resulting in the node having multiple parents (see 4.3.5
>>> Transformation hierarchy
>>> <https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/concepts.html#TransformationHierarchy>,
>>> for restrictions on self-referential nodes).
>>>
>>> Node names shall be unique in the context within which the associated
>>> DEF name occurs. Any USE node reference without a corresponding DEF,
>>> within the scope of the current scene or prototype declaration, is an error.
>>>
>>> NOTE   DEF names are not required to precede USE references.
>>>
>> Have fun building understandable models with X3D!  😁 👍
>>
>> all the best, Don
>> --
>> X3D Graphics, Maritime Robotics, Distributed Simulation
>> Relative Motion Consulting  https://RelativeMotion.info
>>
>> On Thu, Apr 30, 2026 at 3:25 AM John Carlson via x3d-public <
>> x3d-public at web3d.org> wrote:
>>
>>> Summary: to employ multiple DEFs with same value, employ a table per
>>> name scope of DEF information in per Java thread java.lang.ThreadLocal
>>> memory for encoded output with one DEF per DEF/USE value.  See bolded table
>>> description below.
>>>
>>> Feel free to forward.
>>>
>>> Is many DEFs with same value for a scenegraph node being considered in
>>> discussions?  Say I want to addChild() the same Shape node several times to
>>> different Transforms, and the Shape node or descendants have DEFs in
>>> them.  In X3DJSAIL, of course.   This is easily done in an SAI binding
>>> like X3DJSAIL, just use the same variable passed to several addChild()
>>> methods.
>>>
>>>
>>> If it is allowed, what comes out in XML?  I am hoping one leading DEF
>>> and several USEs for backwards compatibility.  I think Castle has shown
>>> that this is doable.
>>>
>>> I am not saying VRML, XML, DOM, or HTML should have multiple parents of
>>> a child node. If a browser wants to implement a proxy when a DEF/USE
>>> appears more than once, they should be free to do that.  (Hint:
>>> JavaScript’s Proxy class.) Maybe each mention of a DEF value (second or
>>> following) or USE value (any natural number of them) should create a Proxy
>>> on setting or adding?
>>>
>>> I do think the encodings are doing the right thing, no changes there.
>>> How can we achieve that output and support multiple parents (references or
>>> proxies to children) in X3DJSAIL with one DEF node per DEF value output?
>>>
>>> I’m particularly wondering for X3DJSAIL.
>>>
>>> Do we need proxies, or will table(s) also solve the issue of multiple
>>> DEFs, and replace all but the first with USE on output?  Also perhaps
>>> assuming there’s a DEF table per name scope.  How does X3DJSAIL support
>>> name scopes? (I’m clueless, currently).  *I’m imagining a table with
>>> DEF_value, DEF_found, reference_count, DEF_nodes and USE_nodes columns.
>>> Maybe a name_scope and node_type_name as well.*  These table(s) would
>>> be initialized when output begins potentially when a name scope is entered,
>>> and filled out as the XML is created.   Multiple threads?  The table can be
>>> stored in ThreadLocal memory.  Bingo, if it’s still a thing.
>>>
>>> Please let me know if such a thing is already available.
>>>
>>> Someone else can solve for X3DPSAIL?
>>>
>>> Will this also handle USE before DEF?
>>>
>>> John
>>> _______________________________________________
>>> x3d-public mailing list
>>> x3d-public at web3d.org
>>> http://web3d.org/mailman/listinfo/x3d-public_web3d.org
>>
>>
>> must be located in the scene graph before any USE references.
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20260501/dd35adef/attachment-0001.html>