Unit X3DLoad

Classes, Interfaces, Objects and Records
Types

Description

Loading scenes as X3D nodes.

Every format except VRML/X3D is handled by converting it into X3D nodes graph. This allows to use our great X3D renderer, tools, saving to X3D and such, on every model.

Basic guide for adding a new format:

  • Particular formats are implemented inside various X3DLoadInternalXxx units. Implementation of this unit calls them. In the future, a mechanism that allows you to "register" an importer, without modifying this unit's implementation, may be done — report if needed.

  • Scene formats are also listed in the file filters constants: see LoadScene_FileFilters . Each format has a file filter to specifically choose this format, and also is added to the "All Scenes" filter.

  • Enable view3dscene to associate with this file format on freedesktops (GNOME, and other following freedesktop.org specs). For this,

    1. Update view3dscene MIME database. Simply add appopriate element to ../../../view3dscene/desktop/view3dscene.xml. Format of that MIME xml file is self-explanatory. It's good idea to google first to search for standard MIME type for your model format (e.g. wikipedia shows mime types for formats). If none is found, just use application/x-???, where ??? is some short name for your format.

    2. After adding to MIME database, you want to also add format to ../../../view3dscene/desktop/view3dscene.desktop, to indicate that view3dscene handles this MIME type.

    3. Finally, also add this to ../../../view3dscene/desktop/install_thumbnailer.sh, so that GNOME nautilus thumbnailers for this MIME types can be installed.

  • You probably also want to extend documentation. At least https://castle-engine.io/creating_data_model_formats.php , it lists all supported scene formats.

Uses

Overview

Functions and Procedures

function LoadNode(const URL: string; const NilOnUnrecognizedFormat: boolean = false): TX3DRootNode;
function Load3D(const URL: string; const AllowStdIn: boolean = false; const NilOnUnrecognizedFormat: boolean = false): TX3DRootNode; deprecated 'use LoadNode, and note it has one less parameter (AllowStdIn is not implemented anymore)';
procedure Load3DSequence( const URL: string; const AllowStdIn: boolean; const KeyNodes: TX3DNodeList; const KeyTimes: TSingleList; out ScenesPerTime: Cardinal; out Epsilon: Single; out TimeLoop, TimeBackwards: boolean); deprecated 'use LoadNode instead of Load3DSequence';

Constants

LoadScene_FileFilters = 'All Files|*|' + '*All Scenes|*.wrl;*.wrl.gz;*.wrz;*.x3d;*.x3dz;*.x3d.gz;*.x3dv;*.x3dvz;*.x3dv.gz;*.kanim;*.castle-anim-frames;*.dae;*.iv;*.3ds;*.md3;*.obj;*.geo;*.json;*.stl;*.glb;*.gltf|' + 'VRML (*.wrl, *.wrl.gz, *.wrz)|*.wrl;*.wrl.gz;*.wrz|' + 'X3D XML (*.x3d, *.x3dz, *.x3d.gz)|*.x3d;*.x3dz;*.x3d.gz|' + 'X3D classic (*.x3dv, *.x3dvz, *.x3dv.gz)|*.x3dv;*.x3dvz;*.x3dv.gz|' + 'Castle Animation Frames (*.castle-anim-frames, *.kanim)|*.castle-anim-frames;*.kanim|' + 'glTF (*.glb, *.gltf)|*.glb;*.gltf|' + 'Collada (*.dae)|*.dae|' + 'Inventor (*.iv)|*.iv|' + '3D Studio (*.3ds)|*.3ds|' + 'Quake 3 engine models (*.md3)|*.md3|' + 'Wavefront (*.obj)|*.obj|' + 'Videoscape (*.geo)|*.geo|' + 'Spine animation (*.json)|*.json|' + 'Standard Triangle Language (*.stl)|*.stl';
Load3D_FileFilters = LoadScene_FileFilters deprecated 'use LoadScene_FileFilters';
SaveX3D_FileFilters = 'All files|*|' + '*X3D XML (*.x3d)|*.x3d|' + 'X3D XML (compressed) (*.x3dz, *.x3d.gz)|*.x3dz;*.x3d.gz|' + 'X3D classic (*.x3dv)|*.x3dv|' + 'X3D classic (compressed) (*.x3dvz, *.x3dv.gz)|*.x3dvz;*.x3dv.gz';
Load3DSequence_FileFilters = LoadScene_FileFilters deprecated 'use LoadScene_FileFilters, and use LoadNode instead of Load3DSequence';
DefaultBakedAnimationSmoothness = 1;

Variables

BakedAnimationSmoothness: Single = DefaultBakedAnimationSmoothness;

Description

Functions and Procedures

function LoadNode(const URL: string; const NilOnUnrecognizedFormat: boolean = false): TX3DRootNode;

Load a scene as X3D node. Guesses scene format based on the URL extension. We load a large number of formats, see https://castle-engine.io/creating_data_model_formats.php .

All the scene formats are loaded as a graph of X3D nodes.

URL is downloaded using the CastleDownload unit, so it supports files, http resources and more. See https://castle-engine.io/manual_network.php about supported URL schemes. If you all you care about is loading normal files, then just pass a normal filename (absolute or relative to the current directory) as the URL parameter.

To actually display, animate and do many other things with the loaded model, you usually want to load it to TCastleScene, using the TCastleSceneCore.Load method. Like this:

var
  RootNode: TX3DRootNode;
  Scene: TCastleScene;
begin
  RootNode := LoadNode('my_model.x3d');
  Scene := TCastleScene.Create(Application);
  Scene.Load(RootNode, true);
  // The 2nd parameter of Load says that Scene owns RootNode
end;

Actually, in most cases you don't need to use LoadNode (and this unit, X3DLoad) at all, and you can simply load from an URL:

var
  Scene: TCastleScene;
begin
  Scene := TCastleScene.Create(Application);
  Scene.Load('my_model.x3d');
  // you can access Scene.RootNode after loading, if needed
end;

Note that usually you want to load models from the game data, so you would actually use 'castle-data:/my_model.x3d' URL instead of 'my_model.x3d'.

function Load3D(const URL: string; const AllowStdIn: boolean = false; const NilOnUnrecognizedFormat: boolean = false): TX3DRootNode; deprecated 'use LoadNode, and note it has one less parameter (AllowStdIn is not implemented anymore)';

Warning: this symbol is deprecated: use LoadNode, and note it has one less parameter (AllowStdIn is not implemented anymore)

 
procedure Load3DSequence( const URL: string; const AllowStdIn: boolean; const KeyNodes: TX3DNodeList; const KeyTimes: TSingleList; out ScenesPerTime: Cardinal; out Epsilon: Single; out TimeLoop, TimeBackwards: boolean); deprecated 'use LoadNode instead of Load3DSequence';

Warning: this symbol is deprecated: use LoadNode instead of Load3DSequence

Load various model formats as animation expressed by VRML/X3D sequence.

For model formats that cannot express animations (like GEO or Wavefront OBJ) or that express animations in a single file (like VRML/X3D >= 2.0) we load them exactly like LoadNode, adding exactly one item to KeyNodes. So this function handles at least the same model formats as LoadNode.

Additionally, we load castle-anim-frames and MD3 formats to a sequence of frames.

Parameters
KeyNodes
Sequence of root nodes will be stored there. Pass here some created and empty instance of TX3DNodeList.
KeyTimes
Sequence of time values. Pass here some created and empty instance of TSingleList.

Constants

LoadScene_FileFilters = 'All Files|*|' + '*All Scenes|*.wrl;*.wrl.gz;*.wrz;*.x3d;*.x3dz;*.x3d.gz;*.x3dv;*.x3dvz;*.x3dv.gz;*.kanim;*.castle-anim-frames;*.dae;*.iv;*.3ds;*.md3;*.obj;*.geo;*.json;*.stl;*.glb;*.gltf|' + 'VRML (*.wrl, *.wrl.gz, *.wrz)|*.wrl;*.wrl.gz;*.wrz|' + 'X3D XML (*.x3d, *.x3dz, *.x3d.gz)|*.x3d;*.x3dz;*.x3d.gz|' + 'X3D classic (*.x3dv, *.x3dvz, *.x3dv.gz)|*.x3dv;*.x3dvz;*.x3dv.gz|' + 'Castle Animation Frames (*.castle-anim-frames, *.kanim)|*.castle-anim-frames;*.kanim|' + 'glTF (*.glb, *.gltf)|*.glb;*.gltf|' + 'Collada (*.dae)|*.dae|' + 'Inventor (*.iv)|*.iv|' + '3D Studio (*.3ds)|*.3ds|' + 'Quake 3 engine models (*.md3)|*.md3|' + 'Wavefront (*.obj)|*.obj|' + 'Videoscape (*.geo)|*.geo|' + 'Spine animation (*.json)|*.json|' + 'Standard Triangle Language (*.stl)|*.stl';

File filters for files loaded by TCastleSceneCore.Load and LoadNode. Suitable for TFileFilterList.AddFiltersFromString and TCastleWindowBase.FileDialog.

Load3D_FileFilters = LoadScene_FileFilters deprecated 'use LoadScene_FileFilters';

Warning: this symbol is deprecated: use LoadScene_FileFilters

TODO: and X3D binary (*.x3db;*.x3db.gz)

SaveX3D_FileFilters = 'All files|*|' + '*X3D XML (*.x3d)|*.x3d|' + 'X3D XML (compressed) (*.x3dz, *.x3d.gz)|*.x3dz;*.x3d.gz|' + 'X3D classic (*.x3dv)|*.x3dv|' + 'X3D classic (compressed) (*.x3dvz, *.x3dv.gz)|*.x3dvz;*.x3dv.gz';
 
Load3DSequence_FileFilters = LoadScene_FileFilters deprecated 'use LoadScene_FileFilters, and use LoadNode instead of Load3DSequence';

Warning: this symbol is deprecated: use LoadScene_FileFilters, and use LoadNode instead of Load3DSequence

File filters for files loaded by Load3DSequence, suitable for TFileFilterList.AddFiltersFromString and TCastleWindowBase.FileDialog.

DefaultBakedAnimationSmoothness = 1;
 

Variables

BakedAnimationSmoothness: Single = DefaultBakedAnimationSmoothness;

A smoothness value for "baked" animations loaded from castle-anim-frames files. This is multiplied by the scenes_per_time value recorded in castle-anim-frames file (30 by default), and determines the number of extra frames we add to the baked animation (between key frames).


Generated by PasDoc 0.15.0.