Crystal Space: iLoader Struct Reference (Crystal Space Public API Reference)

| ## Public API Reference

- Main Page
- Modules
- Namespaces
- Classes
- Files
- Related Pages

- Alphabetical List
- Class List
- Class Hierarchy
- Class Members

# iLoader Struct Reference
[Loading & Saving support]

This interface represents the map loader. More...

`#include <imap/loader.h>`

Inheritance diagram for iLoader:

[legend]
List of all members.

## Public Member Functions
virtual bool | GetAutoRegions ()=0
| Get whether to load each file into a separate region.
virtual bool | Load (iDocumentNode *node, iBase *&result, iRegion *region=0, bool curRegOnly=true, bool checkDupes=false, iStreamSource *ssource=0, const char *override_name=0, iMissingLoaderData *missingdata=0)=0
| Load a node.
virtual bool | Load (iDataBuffer *buffer, iBase *&result, iRegion *region=0, bool curRegOnly=true, bool checkDupes=false, iStreamSource *ssource=0, const char *override_name=0, iMissingLoaderData *missingdata=0)=0
| Load a file.
virtual bool | Load (const char *fname, iBase *&result, iRegion *region=0, bool curRegOnly=true, bool checkDupes=false, iStreamSource *ssource=0, const char *override_name=0, iMissingLoaderData *missingdata=0)=0
| Load a file.
virtual csPtr< iImage > | LoadImage (iDataBuffer *buf, int Format=CS_IMGFMT_INVALID)=0
| Load an image file.
virtual csPtr< iImage > | LoadImage (const char *Filename, int Format=CS_IMGFMT_INVALID)=0
| Load an image file.
virtual bool | LoadLibrary (iDocumentNode *lib_node, iRegion *region=0, bool curRegOnly=true, bool checkDupes=false, iStreamSource *ssource=0, iMissingLoaderData *missingdata=0)=0
| Load library from a 'library' node.
virtual bool | LoadLibraryFile (const char *filename, iRegion *region=0, bool curRegOnly=true, bool checkDupes=false, iStreamSource *ssource=0, iMissingLoaderData *missingdata=0)=0
| Load library from a VFS file.
virtual bool | LoadMap (iDocumentNode *world_node, bool clearEngine=true, iRegion *region=0, bool curRegOnly=true, bool checkDupes=false, iStreamSource *ssource=0, iMissingLoaderData *missingdata=0)=0
| Load a map from the given 'world' node.
virtual bool | LoadMapFile (const char *filename, bool clearEngine=true, iRegion *region=0, bool curRegOnly=true, bool checkDupes=false, iStreamSource *ssource=0, iMissingLoaderData *missingdata=0)=0
| Load a map file.
virtual csPtr< iMeshWrapper > | LoadMeshObject (const char *fname, iStreamSource *ssource=0)=0
| Load a mesh object from a file.
virtual csPtr< iMeshFactoryWrapper > | LoadMeshObjectFactory (const char *fname, iStreamSource *ssource=0)=0
| Load a Mesh Object Factory from a file.
virtual bool | LoadShader (const char *filename)=0
| Load a shader from a file.
virtual csPtr< iSndSysStream > | LoadSoundStream (const char *fname, int mode3d)=0
| New Sound System: Load a sound file and create a stream from it.
virtual csPtr< iSndSysData > | LoadSoundSysData (const char *fname)=0
| New Sound System: Load a sound file and return an iSndSysData object.
virtual iSndSysWrapper * | LoadSoundWrapper (const char *name, const char *fname)=0
| New Sound System: Load a sound file, create sound data and create a wrapper object for it.
virtual iSndSysWrapper * | LoadSoundWrapper (const char *name, const char *fname, int mode3d)=0
| New Sound System: Load a sound file, create a stream and create a wrapper object for it.
virtual iTextureWrapper * | LoadTexture (const char *Name, iDataBuffer *buf, int Flags=CS_TEXTURE_3D, iTextureManager *tm=0, bool reg=true, bool create_material=true, bool free_image=true)=0
| Load a texture as with LoadTexture() above and register it with the engine.
virtual csPtr< iTextureHandle > | LoadTexture (iDataBuffer *buf, int Flags=CS_TEXTURE_3D, iTextureManager *tm=0, csRef< iImage > *image=0)=0
| Load an image as with LoadImage() and create a texture handle from it.
virtual iTextureWrapper * | LoadTexture (const char *Name, const char *FileName, int Flags=CS_TEXTURE_3D, iTextureManager *tm=0, bool reg=true, bool create_material=true, bool free_image=true, iRegion *region=0)=0
| Load a texture as with LoadTexture() above and register it with the engine.
virtual csPtr< iTextureHandle > | LoadTexture (const char *Filename, int Flags=CS_TEXTURE_3D, iTextureManager *tm=0, csRef< iImage > *image=0)=0
| Load an image as with LoadImage() and create a texture handle from it.
virtual void | SetAutoRegions (bool autoRegions)=0
| Set whether to load each file into a separate region.
virtual csPtr< iLoaderStatus > | ThreadedLoadMapFile (const char *filename, iRegion *region=0, bool curRegOnly=true, bool checkDupes=false)=0
| Load a map file in a thread.

## Detailed Description

This interface represents the map loader.

Definition at line 134 of file loader.h.

## Member Function Documentation

virtual bool iLoader::GetAutoRegions | ( |  | ) | `[pure virtual]`

Get whether to load each file into a separate region.

virtual bool iLoader::Load | ( | iDocumentNode * | node,
|  | iBase *& | result,
|  | iRegion * | region = `0`,
|  | bool | curRegOnly = `true`,
|  | bool | checkDupes = `false`,
|  | iStreamSource * | ssource = `0`,
|  | const char * | override_name = `0`,
|  | iMissingLoaderData * | missingdata = `0` |
| ) |  |  | `[pure virtual]`

Load a node.

This is a smart function that will try to recognize what kind of node it is. It recognizes the following types of nodes:

- 'world' node: in that case 'result' will be set to the engine.
- 'library' node: 'result' will be 0.
- 'meshfact' node: 'result' will be the mesh factory wrapper.
- 'meshobj' node: 'result' will be the mesh wrapper.

Returns false on failure.
Note! In case a world node is loaded this function will NOT clear the engine!
Note! In case a mesh factory or mesh object is loaded this function will not actually do anything checkDupes is true and the mesh or factory is already in memory (with that name). This function will still return true in that case and set 'result' to the correct object.
Note! Use SCF_QUERY_INTERFACE on 'result' to detect what type was loaded.

Parameters:

  | node | is the node from which to read.
  | result | will be set to the loaded result (see above).
  | region | is 0 by default which means that all loaded objects are not added to any region. If you give a region here then all loaded objects will be added to that region.
  | curRegOnly | is true by default which means that it will only find materials/factories/... from current region if that is given.
  | checkDupes | if true then materials, textures, and mesh factories will only be loaded if they don't already exist in the entire engine (ignoring regions). By default this is false because it is very legal for different world files to have different objects with the same name. Only use checkDupes == true if you know that your objects have unique names accross all world files.
  | ssource | is an optional stream source for faster loading.
  | override_name | if this is given the the name of the loaded object will be set to that. This only works in case of meshfact, meshobj, and 3ds or md2 model.
  | missingdata | is an optional callback in case data is missing. The application can then provide that missing data in some other way.

virtual bool iLoader::Load | ( | iDataBuffer * | buffer,
|  | iBase *& | result,
|  | iRegion * | region = `0`,
|  | bool | curRegOnly = `true`,
|  | bool | checkDupes = `false`,
|  | iStreamSource * | ssource = `0`,
|  | const char * | override_name = `0`,
|  | iMissingLoaderData * | missingdata = `0` |
| ) |  |  | `[pure virtual]`

Load a file.

This is a smart function that will try to recognize what kind of file it is. It recognizes the following types of files:

- 'world' file: in that case 'result' will be set to the engine.
- 'library' file: 'result' will be 0.
- 'meshfact' file: 'result' will be the mesh factory wrapper.
- 'meshobj' file: 'result' will be the mesh wrapper.
- 3ds/md2 models: 'result' will be the mesh factory wrapper.

Returns false on failure.
Note! In case a world file is loaded this function will NOT clear the engine!
Note! In case a mesh factory or mesh object is loaded this function will not actually do anything checkDupes is true and the mesh or factory is already in memory (with that name). This function will still return true in that case and set 'result' to the correct object.
Note! Use SCF_QUERY_INTERFACE on 'result' to detect what type was loaded.

Parameters:

  | buffer | is a buffer for the model contents.
  | result | will be set to the loaded result (see above).
  | region | is 0 by default which means that all loaded objects are not added to any region. If you give a region here then all loaded objects will be added to that region.
  | curRegOnly | is true by default which means that it will only find materials/factories/... from current region if that is given.
  | checkDupes | if true then materials, textures, and mesh factories will only be loaded if they don't already exist in the entire engine (ignoring regions). By default this is false because it is very legal for different world files to have different objects with the same name. Only use checkDupes == true if you know that your objects have unique names accross all world files.
  | ssource | is an optional stream source for faster loading.
  | override_name | if this is given the the name of the loaded object will be set to that. This only works in case of meshfact, meshobj, and 3ds or md2 model.
  | missingdata | is an optional callback in case data is missing. The application can then provide that missing data in some other way.

virtual bool iLoader::Load | ( | const char * | fname,
|  | iBase *& | result,
|  | iRegion * | region = `0`,
|  | bool | curRegOnly = `true`,
|  | bool | checkDupes = `false`,
|  | iStreamSource * | ssource = `0`,
|  | const char * | override_name = `0`,
|  | iMissingLoaderData * | missingdata = `0` |
| ) |  |  | `[pure virtual]`

Load a file.

This is a smart function that will try to recognize what kind of file it is. It recognizes the following types of files:

- 'world' file: in that case 'result' will be set to the engine.
- 'library' file: 'result' will be 0.
- 'meshfact' file: 'result' will be the mesh factory wrapper.
- 'meshobj' file: 'result' will be the mesh wrapper.
- 3ds/md2 models: 'result' will be the mesh factory wrapper.

Returns false on failure.
Note! In case a world file is loaded this function will NOT clear the engine!
Note! In case a mesh factory or mesh object is loaded this function will not actually do anything checkDupes is true and the mesh or factory is already in memory (with that name). This function will still return true in that case and set 'result' to the correct object.
Note! Use SCF_QUERY_INTERFACE on 'result' to detect what type was loaded.

Parameters:

  | fname | is a VFS filename for the XML file.
  | result | will be set to the loaded result (see above).
  | region | is 0 by default which means that all loaded objects are not added to any region. If you give a region here then all loaded objects will be added to that region.
  | curRegOnly | is true by default which means that it will only find materials/factories/... from current region if that is given.
  | checkDupes | if true then materials, textures, and mesh factories will only be loaded if they don't already exist in the entire engine (ignoring regions). By default this is false because it is very legal for different world files to have different objects with the same name. Only use checkDupes == true if you know that your objects have unique names accross all world files.
  | ssource | is an optional stream source for faster loading.
  | override_name | if this is given the the name of the loaded object will be set to that. This only works in case of meshfact, meshobj, and 3ds or md2 model.
  | missingdata | is an optional callback in case data is missing. The application can then provide that missing data in some other way.

virtual csPtr<iImage> iLoader::LoadImage | ( | iDataBuffer * | buf,
|  | int | Format = `CS_IMGFMT_INVALID` |
| ) |  |  | `[pure virtual]`

Load an image file.

The image will be loaded in the format requested by the engine. If no engine exists, the format is taken from the video renderer. If no video renderer exists, this function fails. You may also request an alternate format to override the above sequence. This version reads the image from a data buffer.

virtual csPtr<iImage> iLoader::LoadImage | ( | const char * | Filename,
|  | int | Format = `CS_IMGFMT_INVALID` |
| ) |  |  | `[pure virtual]`

Load an image file.

The image will be loaded in the format requested by the engine. If no engine exists, the format is taken from the video renderer. If no video renderer exists, this function fails. You may also request an alternate format to override the above sequence.

virtual bool iLoader::LoadLibrary | ( | iDocumentNode * | lib_node,
|  | iRegion * | region = `0`,
|  | bool | curRegOnly = `true`,
|  | bool | checkDupes = `false`,
|  | iStreamSource * | ssource = `0`,
|  | iMissingLoaderData * | missingdata = `0` |
| ) |  |  | `[pure virtual]`

Load library from a 'library' node.

Parameters:

  | lib_node | is the 'library' node from an XML document.
  | region | is 0 by default which means that all loaded objects are not added to any region. If you give a region here then all loaded objects will be added to that region.
  | curRegOnly | is true by default which means that it will only find materials/factories/... from current region if that is given.
  | checkDupes | if true then materials, textures, and mesh factories will only be loaded if they don't already exist in the entire engine (ignoring regions). By default this is false because it is very legal for different world files to have different objects with the same name. Only use checkDupes == true if you know that your objects have unique names accross all world files.
  | ssource | is an optional stream source for faster loading.
  | missingdata | is an optional callback in case data is missing. The application can then provide that missing data in some other way.

virtual bool iLoader::LoadLibraryFile | ( | const char * | filename,
|  | iRegion * | region = `0`,
|  | bool | curRegOnly = `true`,
|  | bool | checkDupes = `false`,
|  | iStreamSource * | ssource = `0`,
|  | iMissingLoaderData * | missingdata = `0` |
| ) |  |  | `[pure virtual]`

Load library from a VFS file.

Parameters:

  | filename | is a VFS filename for the XML file.
  | region | is 0 by default which means that all loaded objects are not added to any region. If you give a region here then all loaded objects will be added to that region.
  | curRegOnly | is true by default which means that it will only find materials/factories/... from current region if that is given.
  | checkDupes | if true then materials, textures, and mesh factories will only be loaded if they don't already exist in the entire engine (ignoring regions). By default this is false because it is very legal for different world files to have different objects with the same name. Only use checkDupes == true if you know that your objects have unique names accross all world files.
  | ssource | is an optional stream source for faster loading.
  | missingdata | is an optional callback in case data is missing. The application can then provide that missing data in some other way.

virtual bool iLoader::LoadMap | ( | iDocumentNode * | world_node,
|  | bool | clearEngine = `true`,
|  | iRegion * | region = `0`,
|  | bool | curRegOnly = `true`,
|  | bool | checkDupes = `false`,
|  | iStreamSource * | ssource = `0`,
|  | iMissingLoaderData * | missingdata = `0` |
| ) |  |  | `[pure virtual]`

Load a map from the given 'world' node.

If 'clearEngine' is true then the current contents of the engine will be deleted before loading. If 'region' is not 0 then portals will only connect to the sectors in that region, things will only use thing templates defined in that region and meshes will only use mesh factories defined in that region. If the region is not 0 and curRegOnly is true then objects (materials, factories, ...) will only be found in the given region.

Parameters:

  | world_node | is the 'world' node from an XML document.
  | clearEngine | is true by default which means that the previous contents of the engine is cleared (all objects/sectors/... are removed).
  | region | is 0 by default which means that all loaded objects are not added to any region. If you give a region here then all loaded objects will be added to that region.
  | curRegOnly | is true by default which means that it will only find materials/factories/... from current region if that is given.
  | checkDupes | if true then materials, textures, and mesh factories will only be loaded if they don't already exist in the entire engine (ignoring regions). By default this is false because it is very legal for different world files to have different objects with the same name. Only use checkDupes == true if you know that your objects have unique names accross all world files.
  | ssource | is an optional stream source for faster loading.
  | missingdata | is an optional callback in case data is missing. The application can then provide that missing data in some other way.

virtual bool iLoader::LoadMapFile | ( | const char * | filename,
|  | bool | clearEngine = `true`,
|  | iRegion * | region = `0`,
|  | bool | curRegOnly = `true`,
|  | bool | checkDupes = `false`,
|  | iStreamSource * | ssource = `0`,
|  | iMissingLoaderData * | missingdata = `0` |
| ) |  |  | `[pure virtual]`

Load a map file.

If 'clearEngine' is true then the current contents of the engine will be deleted before loading. If 'region' is not 0 then portals will only connect to the sectors in that region, things will only use thing templates defined in that region and meshes will only use mesh factories defined in that region. If the region is not 0 and curRegOnly is true then objects (materials, factories, ...) will only be found in the given region.

Parameters:

  | filename | is a VFS filename for the XML file.
  | clearEngine | is true by default which means that the previous contents of the engine is cleared (all objects/sectors/... are removed).
  | region | is 0 by default which means that all loaded objects are not added to any region. If you give a region here then all loaded objects will be added to that region.
  | curRegOnly | is true by default which means that it will only find materials/factories/... from current region if that is given.
  | checkDupes | if true then materials, textures, and mesh factories will only be loaded if they don't already exist in the entire engine (ignoring regions). By default this is false because it is very legal for different world files to have different objects with the same name. Only use checkDupes == true if you know that your objects have unique names accross all world files.
  | ssource | is an optional stream source for faster loading.
  | missingdata | is an optional callback in case data is missing. The application can then provide that missing data in some other way.

virtual csPtr<iMeshWrapper> iLoader::LoadMeshObject | ( | const char * | fname,
|  | iStreamSource * | ssource = `0` |
| ) |  |  | `[pure virtual]`

Load a mesh object from a file.

The mesh object is not automatically added to any sector.

Parameters:

  | fname | is the VFS name of the file.
  | ssource | is an optional stream source for faster loading.

virtual csPtr<iMeshFactoryWrapper> iLoader::LoadMeshObjectFactory | ( | const char * | fname,
|  | iStreamSource * | ssource = `0` |
| ) |  |  | `[pure virtual]`

Load a Mesh Object Factory from a file.

Parameters:

  | fname | is the VFS name of the file.
  | ssource | is an optional stream source for faster loading.

virtual bool iLoader::LoadShader | ( | const char * | filename | ) | `[pure virtual]`

Load a shader from a file.

virtual csPtr<iSndSysStream> iLoader::LoadSoundStream | ( | const char * | fname,
|  | int | mode3d |
| ) |  |  | `[pure virtual]`

New Sound System: Load a sound file and create a stream from it.

Parameters:

  | fname | is the VFS filename.
  | mode3d | is one of CS_SND3D_DISABLE, CS_SND3D_RELATIVE, or CS_SND3D_ABSOLUTE.

virtual csPtr<iSndSysData> iLoader::LoadSoundSysData | ( | const char * | fname | ) | `[pure virtual]`

New Sound System: Load a sound file and return an iSndSysData object.

virtual iSndSysWrapper* iLoader::LoadSoundWrapper | ( | const char * | name,
|  | const char * | fname |
| ) |  |  | `[pure virtual]`

New Sound System: Load a sound file, create sound data and create a wrapper object for it.

Parameters:

  | name | of the sound.
  | fname | is the VFS filename.

virtual iSndSysWrapper* iLoader::LoadSoundWrapper | ( | const char * | name,
|  | const char * | fname,
|  | int | mode3d |
| ) |  |  | `[pure virtual]`

New Sound System: Load a sound file, create a stream and create a wrapper object for it.

Deprecated:
  Use LoadSoundStream() without mode3d parameter. The mode should be given at the time the stream is created later.

Parameters:

  | name | of the sound.
  | fname | is the VFS filename.
  | mode3d | is one of CS_SND3D_DISABLE, CS_SND3D_RELATIVE, or CS_SND3D_ABSOLUTE.

virtual iTextureWrapper* iLoader::LoadTexture | ( | const char * | Name,
|  | iDataBuffer * | buf,
|  | int | Flags = `CS_TEXTURE_3D`,
|  | iTextureManager * | tm = `0`,
|  | bool | reg = `true`,
|  | bool | create_material = `true`,
|  | bool | free_image = `true` |
| ) |  |  | `[pure virtual]`

Load a texture as with LoadTexture() above and register it with the engine.

This version reads the image from a data buffer.

Parameters:

  | Name | The name that the engine will use for the wrapper.
  | buf | Buffer containing the image file data.
  | Flags | Accepts the flags described in ivideo/txtmgr.h. The texture manager determines the format, so choosing an alternate format doesn't make sense here. Instead you may choose an alternate texture manager.
  | tm | Texture manager, used to determine the format the image is to be loaded in (defaults to CS_IMGFMT_TRUECOLOR if no texture manager is specified).
  | reg | if true then the texture and material will be registered to the texture manager. Set 'register' to false if you plan on calling 'engine->Prepare()' later as that function will take care of registering too.
  | create_material | if true then this function also creates a material for the texture.
  | free_image | if true then after registration the loaded image will be removed immediatelly. This saves some memory. Set to false if you want to keep it. free_image is ignored if reg is false.

virtual csPtr<iTextureHandle> iLoader::LoadTexture | ( | iDataBuffer * | buf,
|  | int | Flags = `CS_TEXTURE_3D`,
|  | iTextureManager * | tm = `0`,
|  | csRef< iImage > * | image = `0` |
| ) |  |  | `[pure virtual]`

Load an image as with LoadImage() and create a texture handle from it.

This version reads the image from a data buffer.

Parameters:

  | buf | Buffer containing the image file data.
  | Flags | Accepts the flags described in ivideo/txtmgr.h. The texture manager determines the format, so choosing an alternate format doesn't make sense here. Instead you may choose an alternate texture manager.
  | tm | Texture manager, used to determine the format the image is to be loaded in (defaults to CS_IMGFMT_TRUECOLOR if no texture manager is specified).
  | image | Optionally returns a reference to the loaded image.

virtual iTextureWrapper* iLoader::LoadTexture | ( | const char * | Name,
|  | const char * | FileName,
|  | int | Flags = `CS_TEXTURE_3D`,
|  | iTextureManager * | tm = `0`,
|  | bool | reg = `true`,
|  | bool | create_material = `true`,
|  | bool | free_image = `true`,
|  | iRegion * | region = `0` |
| ) |  |  | `[pure virtual]`

Load a texture as with LoadTexture() above and register it with the engine.

Parameters:

  | Name | The name that the engine will use for the wrapper.
  | FileName | VFS path to the image file to load.
  | Flags | Accepts the flags described in ivideo/txtmgr.h. The texture manager determines the format, so choosing an alternate format doesn't make sense here. Instead you may choose an alternate texture manager.
  | tm | Texture manager, used to determine the format the image is to be loaded in (defaults to CS_IMGFMT_TRUECOLOR if no texture manager is specified).
  | reg | If true then the texture and material will be registered to the texture manager. Set 'register' to false if you plan on calling 'engine->Prepare()' later as that function will take care of registering too.
  | create_material | If true then this function also creates a material for the texture.
  | free_image | If true then after registration the loaded image will be removed immediatelly. This saves some memory. Set to false if you want to keep it. free_image is ignored if reg is false.
  | region | [optional] Region to register the texture and material to.

virtual csPtr<iTextureHandle> iLoader::LoadTexture | ( | const char * | Filename,
|  | int | Flags = `CS_TEXTURE_3D`,
|  | iTextureManager * | tm = `0`,
|  | csRef< iImage > * | image = `0` |
| ) |  |  | `[pure virtual]`

Load an image as with LoadImage() and create a texture handle from it.

Parameters:

  | Filename | VFS path to the image file to load.
  | Flags | Accepts the flags described in ivideo/txtmgr.h. The texture manager determines the format, so choosing an alternate format doesn't make sense here. Instead you may choose an alternate texture manager.
  | tm | Texture manager, used to determine the format the image is to be loaded in (defaults to CS_IMGFMT_TRUECOLOR if no texture manager is specified).
  | image | Optionally returns a reference to the loaded image.

virtual void iLoader::SetAutoRegions | ( | bool | autoRegions | ) | `[pure virtual]`

Set whether to load each file into a separate region.

virtual csPtr<iLoaderStatus> iLoader::ThreadedLoadMapFile | ( | const char * | filename,
|  | iRegion * | region = `0`,
|  | bool | curRegOnly = `true`,
|  | bool | checkDupes = `false` |
| ) |  |  | `[pure virtual]`

Load a map file in a thread.

If 'region' is not 0 then portals will only connect to the sectors in that region, things will only use thing templates defined in that region and meshes will only use mesh factories defined in that region. If the region is not 0 and curRegOnly is true then objects (materials, factories, ...) will only be found in the given region.

If you use 'checkDupes' == true then materials, textures, and mesh factories will only be loaded if they don't already exist in the entire engine (ignoring regions). By default this is false because it is very legal for different world files to have different objects with the same name. Only use checkDupes == true if you know that your objects have unique names accross all world files.

This function returns immediatelly. You can check the iLoaderStatus instance that is returned to see if the map has finished loading or if there was an error.

Todo:
  This is not implemented! Implement me or remove me!

The documentation for this struct was generated from the following file:

- imap/loader.h