[x3d-public] allowing full capabilities for X3D node reuse with Inline EXPORT/IMPORT AS/USE
GPU Group
gpugroup at gmail.com
Thu Oct 9 13:09:43 PDT 2025
Holger, very interesting. I'd love to know how you did it, if it's not too
hard to explain.
-Doug
On Thu, Oct 9, 2025 at 2:01 PM Holger Seelig <holger.seelig at yahoo.de> wrote:
> I have made an experimental implementation of this new feature. You can
> already use and play with it in the special preview playground:
>
>
> https://create3000.github.io/preview/playground/?url=https://create3000.github.io/Library/Tests/Components/Core/use-exported-node.x3dv
>
> This scene loads an inline file which exports a single green cube. This
> cube is imported into the scene and used a second time.
>
> There is also a experimental feature ‚USE before DEF‘ enabled in this
> preview playground. This feature seems important for me to get this all
> work in all cases.
>
> Best regards,
> Holger
>
> —
> Holger Seelig
> Leipzig, Germany
>
> holger.seelig at yahoo.de
> https://create3000.github.io/x_ite/
> https://patreon.com/X_ITE
>
>
>
> Am 09.10.2025 um 18:51 schrieb Don Brutzman via x3d-public <
> x3d-public at web3d.org>:
>
> Hi Doug. Thanks for looking this over.
>
> I meant to also note earlier that this proposed change in semantics has no
> effect on any existing EXPORT/IMPORT statements in any existing X3D
> models, versions 3.0 through 4.0.
>
> Am glad to see you describing how FreeWrl supports EXPORT/IMPORT to date.
>
> Certainly refactoring half a gazillion lines of code is likely not
> worthwhile for such an extensibility feature... don't want to risk
> provoking side-effect problems. Unless you want to, of course... :)
>
> I'm following your points. Seems sensible, but maybe any changes to the
> existing functionality you describe is pretty similar to other handling
> that is already in place. Please consider the following short reactions,
> and correct me if wrong:
>
> - Inline nodes exist and receive few ROUTE connections, there are not
> many fields there (url load etc.)
> - IMPORT creates a node reference that points somewhere in the scene
> subgraph loaded by Inline
> - That IMPORT reference can already send/receive events via ROUTE, as
> long defined in the spec.
> - In essence, the proposal says such a node reference might be treated
> in the same manner as other USE nodes, which are also node references.
>
> Again appreciate all consideration. Even if this is impractical for
> FreeWrl, your opinion on feasibility in general remains welcome. Am not
> trying to check boxes on a feature list, and am not trying to push a
> nontrivial architectural change. Rather am trying to enable significantly
> more scalable extensibility by removing a small existing constraint on
> usage.
>
> p.s. curiously, since the specification intentionally never mandates error
> responses, it seems like a browser implementation might satisfactorily
> permit IMPORT node references to behave similarly as USE node references,
> if it wants. hmmm...
>
> Have fun with X3D! 😀
>
> all the best, Don
> --
> X3D Graphics, Maritime Robotics, Distributed Simulation
> Relative Motion Consulting https://RelativeMotion.info
> <https://relativemotion.info/>
>
>
> On Thu, Oct 9, 2025 at 9:14 AM GPU Group <gpugroup at gmail.com> wrote:
>
>> Don,
>> "synchronization" I suspect the change would break (25 year old,
>> currently unmaintained) freewrl. I like the use-case you mention for the
>> change, seems well worth a big change. Final nail in freewrl coffin? Not
>> necessarily but would require insight and ambition to refactor 500,000
>> lines of code to allow a layer of abstraction / uncertainty around every
>> node and route in the scenegraph.
>> -Doug
>> more..
>> tests for new conformance would be
>> - if routes can dangle before an Inline is loaded, and after an Inline is
>> unloaded
>> - by dangle I mean point harmlessly TO nothing / unloaded node, without
>> being garbage collected
>> - no error or warning is issued when a route dangles
>> - if Inlined nodes are to be treated like regular scenegraph nodes, would
>> that mean all routes to regular scenegraph nodes should be able to dangle?
>> - current specs: a test for deleting a regular scenegraph node: have an
>> active route to it, and see if something breaks when the node is deleted
>> -- would that need to change so instead of garbage collecting routes to
>> deleted nodes, they dangle, and (somehow) are allowed to hook back up to
>> new added nodes?
>> freewrl current Inline mechanism:
>> - Inlines are loaded, parsed in a separate thread, and can be loaded and
>> unloaded with true/false field on Inline
>> - on each rendering frame, when Inline node is rendered/drawn/visited, it
>> does a little work to check the load progress/status, and makes any changes
>> to IMPORT routes and AS nodes as needed
>> - freewrl uses special routes to Inlined IMPORTed nodes, which can
>> 'dangle' (called weak routes in freewrl) while waiting for the inline to
>> load (rest of scene can be rendering).
>> - the special routes get an extra complex lookup to see if the TO node is
>> loaded
>> - versus deleting a regular scenegraph node would trigger a search for
>> routes to the deleted node, and the routes would be deleted/garbage
>> collected too
>> - and normal routes, freewrl uses memory addresses for start and end node
>> fields, and does a memory copy of field value during routing loop, (versus
>> weak/dangling route complex lookup in separate loop)
>> - when an Inline EXPORTed node is loaded it is allocated to a memory
>> address via malloc. when unloaded and free(), and reloaded and
>> reallocated, it would be loaded in a different memory address, so can't do
>> a simple memcpy with old address during routing, needs to check if node
>> loaded and what's the new memory address
>> SUMMARY: freewrl seems to be missing a layer of abstraction around or
>> flag for each node and route that would allow a USE of an Inlined AS node
>> and IMPORT route to enjoy equal status in the scenegraph. Not immediately
>> obvious how to fix / refactor.
>>
>>
>>
>>
>>
>> On Wed, Oct 8, 2025 at 1:27 PM Don Brutzman via x3d-public <
>> x3d-public at web3d.org> wrote:
>>
>>> [BLUF summary: proposed specification change to allow regular re-USE of
>>> imported node references.]
>>>
>>> Am trying to write a prototype for HAnim, and hoped that I might EXPORT
>>> a large model so that a smaller scene might IMPORT the HAnimHumanoid for
>>> further reuse (as a USE node in a prototype). Example EXPORT:
>>>
>>> - 3D Example Archives: Humanoid Animation, Characters, Jin LOA 2
>>> - Articulated 3D game character designed with a general graphics
>>> tool, then converted into an X3D HAnim model and available for IMPORT as
>>> JinLOA2.
>>> -
>>> https://www.web3d.org/x3d/content/examples/HumanoidAnimation/Characters/JinLOA2Index.html
>>> - <!-- This node has an EXPORT
>>> <https://www.web3d.org/x3d/content/examples/HumanoidAnimation/Characters/JinLOA2.html#JinLOA2> connection
>>> that can exchange events with a parent X3D model. -->
>>> <HAnimHumanoid DEF='hanim_JinLOA2
>>> <https://www.web3d.org/x3d/content/examples/HumanoidAnimation/Characters/JinLOA2.html#hanim_JinLOA2>
>>> ' loa='2' name='JinLOA2' scale='0.0225 0.0225 0.0225'> on line 30
>>> <https://www.web3d.org/x3d/content/examples/HumanoidAnimation/Characters/JinLOA2.html#30>
>>>
>>> - <EXPORT localDEF='hanim_JinLOA2
>>> <https://www.web3d.org/x3d/content/examples/HumanoidAnimation/Characters/JinLOA2.html#hanim_JinLOA2>
>>> ' AS='JinLOA2'/> on line 1319
>>> <https://www.web3d.org/x3d/content/examples/HumanoidAnimation/Characters/JinLOA2.html#1319>
>>>
>>>
>>> Hmmm, please notice that medium-size HAnim model is (1319 - 30 = 1289) lines
>>> long... gee, wouldn't it be nice to Inline and IMPORT that model in ~3
>>> lines instead, with added benefit of being able to reuse pose and motion
>>> animations with it also.
>>>
>>> However the current X3D Architecture appears to restrict the usage of
>>> imported nodes solely to receiving/sending events. That restriction
>>> permits writing ROUTE connections, but a blocker if trying to write a
>>> prototype or trying other node re-USE.
>>>
>>> EXPORT and IMPORT statements are rarely used, but have been around a
>>> long time... since X3D 3.0, about 25 years maybe. They have potential for
>>> great expressive power and extensibility (the X in X3D). However, am
>>> guessing that the reuse limitation of IMPORT nodes has likely inhibited our
>>> adoption. If I recall correctly, the primary objection (way back then) to
>>> allowing full access to an imported node reference was uncertainty about
>>> how it might all work, perhaps complicated by run-time synchronization
>>> concerns.
>>>
>>> We have come a long way since then. It seems pretty clear that an
>>> Inline node loads an external scene graph into the current scene graph.
>>> Further, the EXPORT statement identifies a specific node (sub graph) within
>>> that inlined scene graph.
>>>
>>> The straightforward way to think about this: Inline EXPORT/IMPORT
>>> provides a reference to a node in the currently loaded scene graph. Given
>>> that the author has a reference to an active node, they ought to be able to
>>> utilize that node reference just like any other DEF/USE node reference.
>>>
>>> I propose we relax the legacy (25-year) restriction and allow IMPORT
>>> node references to be treated the same as USE node references.
>>>
>>> Towards that end, have written out suggested changes in the draft v4.1
>>> architecture, adding to a number of editorial improvements already
>>> accomplished as part of
>>>
>>> - Mantis 1470: add EXPORT/IMPORT field DESCRIPTION for X3D
>>> Architecture 4.1; also allow reuse
>>> - https://mantis.web3d.org/view.php?id=14701470: add EXPORT/IMPORT
>>> field DESCRIPTION for X3D Architecture 4.1
>>>
>>> Request review, considerations and reactions. The markup changes at
>>> first look complex but are essentially all geared towards the single
>>> objective of allowing re-use of IMPORT nodes. Lots of markup shows that
>>> there are few actual changes to existing prose, most of it is simply
>>> editorial re-organization for clarity.
>>>
>>> This is a good topic for this week's specification editors call on
>>> Friday (9 pacific).
>>> ______________________________
>>>
>>> For easy review, current markup follows. *First is Concepts.*
>>>
>>> - X3D Architecture v4.1, clause 4 Concepts, 4.4.6 EXPORT/IMPORT
>>> semantics
>>> -
>>> https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/concepts.html#ExportImportSemantics
>>>
>>> 4.4.6 EXPORT/IMPORT semantics Import/Export semantics
>>>
>>> Editors note: there are few actual changes here, most are simply
>>> switching the order of EXPORT and IMPORT. Added functionality: imported
>>> node reuse.
>>>
>>> The EXPORT feature allows authors to identify specific parts of an X3D
>>> model which might be safely shared and reused by other X3D models. The
>>> IMPORT feature allows authors to incorporate content defined within Inline
>>> nodes or created programmatically into the namespace of the containing file
>>> for the purposes of event routing and reusing scene subgraphs on a
>>> per-node basis. In contrast with external prototyping (see 4.4.5
>>> External prototype semantics
>>> <https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/concepts.html#Externalprototypesemantics>),
>>> which allows access to individual fields of nodes defined as prototypes in
>>> external files, IMPORT provides access to all the fields of an externally
>>> defined node with a single statement (see 9.2.6 IMPORT statement
>>> <https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/components/networking.html#IMPORTStatement>
>>> ).
>>>
>>> Importing nodes from an Inlined file is accomplished with two
>>> statements: EXPORT and IMPORT. IMPORT and EXPORT. The IMPORT statement
>>> is used in the containing file to define which nodes of an Inline are to be
>>> incorporated into the containing file's namespace. The EXPORT statement
>>> is used in the file being Inlined, to control access over which nodes
>>> within a file are visible to other files (see 9.2.5 EXPORT statement
>>> <https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/components/networking.html#EXPORTStatement>).
>>> EXPORT statements are not allowed in prototype declarations. The IMPORT
>>> statement is used in the containing file to define which nodes of an Inline
>>> are to be incorporated into the containing file's namespace.
>>>
>>> In contrast with external prototyping (see 4.4.5 External prototype
>>> semantics
>>> <https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/concepts.html#Externalprototypesemantics>),
>>> which allows access to individual fields of nodes defined as prototypes in
>>> external files, IMPORT provides access to all the fields of an externally
>>> defined node with a single statement (see 9.2.6 IMPORT statement
>>> <https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/components/networking.html#IMPORTStatement>
>>> ).
>>>
>>> ______________________________
>>>
>>> *Next is the EXPORT statement.*
>>>
>>> - X3D Architecture v4.1, clause 9 Networking component, 9.2.5 EXPORT
>>> statement
>>> -
>>> https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/components/networking.html#EXPORTStatement
>>>
>>> 9.2.5 EXPORT statement
>>>
>>> The EXPORT statement is used within an X3D file to specify nodes that
>>> may be imported into other scenes when Inlining that file. Only named nodes
>>> exported with an EXPORT statement are eligible to be imported into another
>>> scene. file. DEF names are used to identify exported nodes. See 4.4.6
>>> EXPORT/IMPORT semantics
>>> <https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/concepts.html#ExportImportSemantics> for
>>> further details.
>>>
>>> EXPORT statements may appear anywhere in the file and have the following
>>> form:
>>>
>>> EXPORT <NodeDEFName> [ AS <ExportedNodeDEFName> ]
>>> [DESCRIPTION "a simple description of intended EXPORT purpose"]
>>>
>>> EXPORT <NodeName> [ AS <ExportedNodeName> ]
>>>
>>> The EXPORT statement has the following components:
>>>
>>> 1. The local DEF name of the node to be exported if the current
>>> scene is retrieved externally via Inline,
>>> 2. An optional alternative DEF name that is used AS a default as an alias
>>> for the exported node when importing it into other scenes, files,
>>> 3. An optional simple DESCRIPTION of intended purpose for the node
>>> provided via EXPORT.
>>>
>>> The EXPORT statement has the following semantics:
>>>
>>> 4. Once imported into a containing scene, events may be routed to or
>>> from the fields of an exported node in exactly the same manner as
>>> any node defined with DEF.
>>> 5. Exported nodes imported into a containing scene may be referenced
>>> via a USE statement in the importing scene. may not be instanced via
>>> the USE statement.
>>> 6. Exportation may not be propagated across multiple files; that is,
>>> a node imported into one scene using the IMPORT statement may not then be
>>> further exported into another scene using the EXPORT statement.
>>> 7. Nodes shall not be exported from within the body of a PROTO
>>> declaration.
>>> 8. Any scene with an EXPORT statement shall apply UNIT statement
>>> adjustments as needed to the fields of any exported nodes and child nodes.
>>> 9. The EXPORT statement can appear wherever a ROUTE statement is
>>> allowed, and shall be contained within the Inline node to which it refers.
>>>
>>> The following example illustrates the use of the EXPORT statement
>>> (Classic VRML encoding):
>>>
>>> EXAMPLE
>>>
>>> DEF T1 Transform {
>>> # additional nodes and fields...
>>> }# additional nodes and fields...
>>>
>>> EXPORT T1 AS rootTransform
>>>
>>> In the above example, node T1 is exported for use by other X3D scenes.
>>> The optional AS keyword defines the exported name of *T1* as
>>> *rootTransform* (*i.e.*, other scenes may import the node only using
>>> the name rootTransform). All defined alias AS names shall also meet
>>> appropriate uniqueness requirements in the local DEF namespace of the
>>> parent scene.
>>>
>>> ______________________________
>>> *Next is the IMPORT statement.*
>>>
>>> - X3D Architecture v4.1, clause 9 Networking component, 9.2.6 IMPORT
>>> statement
>>> -
>>> https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/components/networking.html#IMPORTStatement
>>>
>>> 9.2.6 IMPORT statement
>>>
>>> The IMPORT statement is used within an X3D file to specify nodes, which
>>> are defined within Inline files or programmatically created content, that
>>> are to be brought into the namespace of the containing file for the
>>> purposes of event routing. Once a node is imported, events may be sent to
>>> its fields via ROUTEs, or routed from any fields of the node which have
>>> output events. DEF names are used to identify nodes. See 4.4.6
>>> EXPORT/IMPORT semantics
>>> <https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/concepts.html#ExportImportSemantics> for
>>> further details.
>>>
>>> IMPORT statements may appear anywhere in the file and have the following
>>> form:
>>>
>>> IMPORT <InlineNodeDEFName>*.*<ExportedNameFromInlinedFile> [ AS
>>> <NewLocalNodeDEFName> ]
>>> [DESCRIPTION "a simple description of intended IMPORT purpose"]
>>>
>>> IMPORT <InlineNodeName>*.*<ExportedNameFromInlinedFile> [ AS
>>> <NewLocalNodeName> ]
>>>
>>> The IMPORT statement has the following components:
>>>
>>> 1. The DEF name of the Inline node that contains the node to be
>>> imported,
>>> 2. The DEF name of the node to import,
>>> 3. An optional alternative DEF name that is used AS as an alias for
>>> the imported node within the run-time name scope, to help prevent avoid
>>> potential DEF name clashes within the parent scene containing the
>>> IMPORT statement,
>>> 4. An optional simple DESCRIPTION of intended purpose for the node
>>> provided via IMPORT.
>>>
>>> The IMPORT statement has the following semantics:
>>>
>>> 5. Once imported, events may be routed to or from the fields of an imported
>>> node in the Inline scene, in exactly the same manner as any node
>>> defined locally with DEF.
>>> 6. Editors note: the following is an important change, otherwise an
>>> imported node cannot be utilized other than by receiving ROUTEd events (as
>>> shown by the InlineImport.x3d
>>> <https://www.web3d.org/x3d/content/examples/Basic/X3dSpecifications/InlineImportIndex.html>
>>> example).
>>> Nodes imported into an X3D scene using the IMPORT statement may be
>>> referenced not be instanced via the USE statement.
>>> 7. Only nodes that are exported from within the Inline scene via an
>>> EXPORT statement may be imported using a corresponding IMPORT statement.
>>> 8. The IMPORT statement can appear wherever a ROUTE statement is
>>> allowed, and shall follow the Inline node to which it refers.
>>>
>>> Any node reference that is obtained via IMPORT from an exporting scene
>>> is also available as a USE node in the importing scene. This requirement is
>>> necessary for the node reference retrieved by IMPORT to have full
>>> capabilities in the importing scene. Nevertheless, important
>>> synchronization considerations arise when one or more Inline models are
>>> loaded as part of the current scene graph.
>>>
>>> 9. A single Inline node is allowed to have multiple IMPORT
>>> statements. The state of nodes within that currently loaded Inline model
>>> are consistently maintained as part of the current scene.
>>> 10. Multiple Inline nodes with separate IMPORT statements are
>>> completely independent, even if each independent Inline is retrieving a
>>> copy of the same original model.
>>>
>>> The following example illustrates the use of the IMPORT statement
>>> (Classic VRML encoding syntax):
>>>
>>> EXAMPLE
>>>
>>> DEF MyInline I1 Inline {
>>> url "someurl.x3d"
>>> }
>>> IMPORT MyInline.rootTransform AS ImportedTransform I1.rootTransform AS I1Root ...
>>> # ROUTE events into the imported node, which is now a part of an Inline scene subgraph
>>> DEF PI PositionInterpolator { } { ... }
>>> ROUTE PI.value_changed TO ImportedTransform.set_translation I1Root.set_translation
>>>
>>> # also USE the imported node (and associated scene subgraph) elsewhere in the parent scene
>>> Group {
>>> USE ImportedTransform
>>> }
>>>
>>> # also USE the imported node when defining an instance of a MyNewTransform prototype
>>> MyNewTransform {
>>> children USE ImportedTransform
>>> }
>>>
>>> In the above example,
>>>
>>> - rootTransform is externally defined as a Transform node in the
>>> file someurl.x3d and exported via an EXPORT statement. (see 4.4.6
>>> Import/Export semantics
>>> <https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/concepts.html#ExportImportSemantics>
>>> ).
>>> - The optional AS keyword in the IMPORT statement defines an alias
>>> for the MyInline.rootTransform rootTransform DEF. , so that
>>> - Within the containing scene, the node is referenced using the AS
>>> alias name ImportedTransform. DEF name I1Root.
>>>
>>> All defined alias AS names shall also meet appropriate uniqueness
>>> requirements in the local DEF namespace of the parent scene.
>>>
>>> ______________________________
>>> Additional thanks to Joe Williams, Holger Seelig, and Nicholas Polys for
>>> contributing to this analysis and potential improvement.
>>>
>>> All feedback welcome! This simple functional refinement has potential
>>> for much X3D scalability and extensibility.
>>>
>>> Thanks in advance for considering the possibilities.
>>>
>>> all the best, Don
>>> --
>>> X3D Graphics, Maritime Robotics, Distributed Simulation
>>> Relative Motion Consulting https://RelativeMotion.info
>>> <https://relativemotion.info/>
>>> _______________________________________________
>>> x3d-public mailing list
>>> x3d-public at web3d.org
>>> http://web3d.org/mailman/listinfo/x3d-public_web3d.org
>>>
>> _______________________________________________
> x3d-public mailing list
> 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/20251009/ed8f0eca/attachment-0001.html>
More information about the x3d-public
mailing list