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

Thu Apr 30 21:41:01 PDT 2026

>From description:
> Note that the actual DEF node name definition
must be located in the scene graph before any USE references.
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 ConventionsModels are simple representations for some part of reality. Simulations show the behavior of models over time.
  *  Clarity is essential when naming components to design a meaningful model.
  *  Names matter, suggesting how to think about purpose and relationships.
  *  These naming conventions are suitable for X3D scenes, XML tagset design, accompanying HTML pages, and corresponding source code written JavaScript/Java/Python/etc.
  *  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).
  *  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.
  *  Using clear and consistent names for node names and DEF labels greatly improves the clarity of how a scene works.
  *  In effect, descriptive names can make the purpose and mechanics of a scene self-documenting.
  *  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) 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 toanother 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 semanticsNode 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 (mailto: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 (mailto:x3d-public at web3d.org)
http://web3d.org/mailman/listinfo/x3d-public_web3d.org

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20260501/6b00f8e0/attachment-0001.html>