Crystal Space: iEngine 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

# iEngine Struct Reference
[Crystal Space 3D Engine]

This interface is the main interface to the 3D engine. More...

`#include <iengine/engine.h>`

Inheritance diagram for iEngine:

[legend]
List of all members.

## Public Member Functions
virtual iObject * | QueryObject ()=0
| Get the iObject for the engine.
Sector handling
virtual void | AddEngineFrameCallback (iEngineFrameCallback *cb)=0
| Add a frame callback.
virtual void | AddEngineSectorCallback (iEngineSectorCallback *cb)=0
| Add a sector callback.
virtual iSector * | CreateSector (const char *name)=0
| Create a empty sector with given name.
virtual iSector * | FindSector (const char *name, iRegion *region=0)=0
| Find the given sector.
virtual csPtr< iSectorIterator > | GetNearbySectors (iSector *sector, const csBox3 &box)=0
| This routine returns an iterator to iterate over all nearby sectors.
virtual csPtr< iSectorIterator > | GetNearbySectors (iSector *sector, const csVector3 &pos, float radius)=0
| This routine returns an iterator to iterate over all nearby sectors.
virtual iSectorList * | GetSectors ()=0
| Get the list of sectors.
virtual void | RemoveEngineFrameCallback (iEngineFrameCallback *cb)=0
| Remove a frame callback.
virtual void | RemoveEngineSectorCallback (iEngineSectorCallback *cb)=0
| Remove a sector callback.
Mesh handling
virtual void | AddMeshAndChildren (iMeshWrapper *mesh)=0
| Convenience function to add a mesh and all children of that mesh to the engine.
virtual csPtr< iMeshWrapper > | CreateMeshWrapper (const char *name)=0
| Create an uninitialized mesh wrapper Assign to a csRef.
virtual csPtr< iMeshWrapper > | CreateMeshWrapper (const char *classid, const char *name, iSector *sector=0, const csVector3 &pos=csVector3(0, 0, 0))=0
| Create a mesh wrapper from a class id.
virtual csPtr< iMeshWrapper > | CreateMeshWrapper (iMeshObject *meshobj, const char *name, iSector *sector=0, const csVector3 &pos=csVector3(0, 0, 0))=0
| Create a mesh wrapper for an existing mesh object.
virtual csPtr< iMeshWrapper > | CreateMeshWrapper (iMeshFactoryWrapper *factory, const char *name, iSector *sector=0, const csVector3 &pos=csVector3(0, 0, 0))=0
| Convenience function to create a mesh object for a given factory.
virtual csPtr< iMeshWrapper > | CreateSectorWallsMesh (iSector *sector, const char *name)=0
| Convenience function to create the thing containing the convex outline of a sector.
virtual csPtr< iMeshWrapper > | CreateThingMesh (iSector *sector, const char *name)=0
| Convenience function to create a thing mesh in a sector.
virtual iMeshWrapper * | FindMeshObject (const char *name, iRegion *region=0)=0
| Find the given mesh object.
virtual iMeshList * | GetMeshes ()=0
| Get the list of meshes.
virtual csPtr< iMeshWrapperIterator > | GetNearbyMeshes (iSector *sector, const csVector3 &start, const csVector3 &end, bool crossPortals=true)=0
| This routine returns an iterator to iterate over all meshes that intersect with a beam.
virtual csPtr< iMeshWrapperIterator > | GetNearbyMeshes (iSector *sector, const csBox3 &box, bool crossPortals=true)=0
| This routine returns an iterator to iterate over all meshes that are in a box.
virtual csPtr< iMeshWrapperIterator > | GetNearbyMeshes (iSector *sector, const csVector3 &pos, float radius, bool crossPortals=true)=0
| This routine returns an iterator to iterate over all meshes that are within a radius of a given position.
virtual csPtr< iMeshWrapper > | LoadMeshWrapper (const char *name, const char *loaderClassId, iDataBuffer *input, iSector *sector, const csVector3 &pos)=0
| Convenience function to load a mesh object from a given loader plugin.
virtual void | WantToDie (iMeshWrapper *mesh)=0
| Sometimes a mesh wants to destruct itself (for example a particle system that has only limited lifetime).
Render priority functions
virtual void | ClearRenderPriorities ()=0
| Clear all render priorities.
virtual long | GetAlphaRenderPriority ()=0
| Get the render priority for alpha objects (attached to 'alpha' name).
virtual long | GetObjectRenderPriority ()=0
| Get the render priority for general objects (attached to 'object' name).
virtual long | GetPortalRenderPriority ()=0
| Get the render priority for portal objects (attached to 'portal' name).
virtual long | GetRenderPriority (const char *name) const =0
| Get a render priority by name.
virtual int | GetRenderPriorityCount () const =0
| Get the number of render priorities.
virtual const char * | GetRenderPriorityName (long priority) const =0
| Get the name of the render priority or 0 if none existant.
virtual csRenderPrioritySorting | GetRenderPrioritySorting (long priority) const =0
| Get the render priority sorting flag.
virtual csRenderPrioritySorting | GetRenderPrioritySorting (const char *name) const =0
| Get the render priority sorting flag.
virtual long | GetSkyRenderPriority ()=0
| Get the render priority for sky objects (attached to 'sky' name).
virtual long | GetWallRenderPriority ()=0
| Get the render priority for wall objects (attached to 'wall' name).
virtual void | RegisterRenderPriority (const char *name, long priority, csRenderPrioritySorting rendsort=CS_RENDPRI_SORT_NONE)=0
| Register a new render priority.
Material handling
virtual csPtr< iMaterial > | CreateBaseMaterial (iTextureWrapper *txt)=0
| Create a base material that can be used to give to the texture manager.
virtual iMaterialWrapper * | CreateMaterial (const char *name, iTextureWrapper *texture)=0
| Register a material to be loaded during Prepare().
virtual iMaterialWrapper * | FindMaterial (const char *name, iRegion *region=0)=0
| Find the given material.
virtual iMaterialList * | GetMaterialList () const =0
| Get the list of all materials.
Texture handling
virtual iTextureWrapper * | CreateBlackTexture (const char *name, int w, int h, csColor *transp, int flags)=0
| Create a black texture.
virtual iTextureWrapper * | CreateTexture (const char *name, const char *fileName, csColor *transp, int flags)=0
| Create a texture from a file.
virtual iTextureWrapper * | FindTexture (const char *name, iRegion *region=0)=0
| Find the given texture.
virtual int | GetTextureFormat () const =0
| Query the format to load textures (usually this depends on texture manager).
virtual iTextureList * | GetTextureList () const =0
| Get the list of all textures.
Camera handling
virtual csPtr< iCamera > | CreateCamera ()=0
| Create a new camera.
virtual iCameraPosition * | FindCameraPosition (const char *name, iRegion *region=0)=0
| Find the given camera position.
virtual iCameraPositionList * | GetCameraPositions ()=0
| Get the list of camera positions.
Other
virtual csPtr< iFrustumView > | CreateFrustumView ()=0
| Create a iFrustumView instance that you can give to iVisibilityCuller->CastShadows().
virtual csPtr< iObjectWatcher > | CreateObjectWatcher ()=0
| Create an object watcher instance that you can use to watch other objects.
virtual void | DelayedRemoveObject (csTicks delay, iBase *object)=0
| This function can be used to remove an object after a specific amount of time.
virtual void | DeleteAll ()=0
| Delete everything in the engine.
virtual iCollection * | FindCollection (const char *name, iRegion *region=0)=0
| Find the given collection.
virtual iCollectionList * | GetCollections ()=0
| Get the list of collections.
virtual csPtr< iObjectIterator > | GetNearbyObjects (iSector *sector, const csVector3 &pos, float radius, bool crossPortals=true)=0
| This routine returns an iterator to iterate over all objects that are within a radius of a given position.
virtual iSharedVariableList * | GetVariableList () const =0
| Get the list of all shared variables.
virtual csPtr< iMeshWrapperIterator > | GetVisibleMeshes (iSector *sector, const csFrustum &frustum)=0
| This routine returns an iterator to iterate over all meshes that are potentially visible as seen from a given position.
virtual csPtr< iMeshWrapperIterator > | GetVisibleMeshes (iSector *sector, const csVector3 &pos)=0
| This routine returns an iterator to iterate over all meshes that are potentially visible as seen from a given position.
virtual csPtr< iObjectIterator > | GetVisibleObjects (iSector *sector, const csFrustum &frustum)=0
| This routine returns an iterator to iterate over all objects that are potentially visible as seen from a given position.
virtual csPtr< iObjectIterator > | GetVisibleObjects (iSector *sector, const csVector3 &pos)=0
| This routine returns an iterator to iterate over all objects that are potentially visible as seen from a given position.
virtual void | RemoveDelayedRemoves (bool remove=false)=0
| Clear all delayed removals.
virtual bool | RemoveObject (iBase *object)=0
| Convenience function to 'remove' a CS object from the engine.
virtual void | ResetWorldSpecificSettings ()=0
| Reset a subset of flags/settings (which may differ from one world/map to another) to its defaults.
Light handling
virtual csPtr< iLight > | CreateLight (const char *name, const csVector3 &pos, float radius, const csColor &color, csLightDynamicType dyntype=CS_LIGHT_DYNAMICTYPE_STATIC)=0
| Create a static/pseudo-dynamic light.
virtual iLight * | FindLight (const char *Name, bool RegionOnly=false) const =0
| Find a static/pseudo-dynamic light by name.
virtual iLight * | FindLightID (const char *light_id) const =0
| Find a static/pseudo-dynamic light by id.
virtual void | GetAmbientLight (csColor &) const =0
| Return the amount of ambient light.
virtual void | GetDefaultAmbientLight (csColor &c) const =0
| Return the default amount of ambient light.
virtual csPtr< iLightIterator > | GetLightIterator (iRegion *region=0)=0
| Create an iterator to iterate over all static lights of the engine.
virtual int | GetNearbyLights (iSector *sector, const csBox3 &box, iLight **lights, int max_num_lights)=0
| This routine returns all lights which might affect an object with some bounding box.
virtual int | GetNearbyLights (iSector *sector, const csVector3 &pos, iLight **lights, int max_num_lights)=0
| This routine returns all lights which might affect an object at some position.
virtual void | RemoveLight (iLight *light)=0
| Remove a light and update all lightmaps.
virtual void | SetAmbientLight (const csColor &)=0
| Set the amount of ambient light.
Saving/loading
virtual csPtr< iLoaderContext > | CreateLoaderContext (iRegion *region=0, bool curRegOnly=true)=0
| Create a loader context that you can give to loader plugins.
virtual bool | GetSaveableFlag ()=0
| Get whether saving should be possible (default OFF).
virtual void | SetSaveableFlag (bool enable)=0
| Set whether saving should be possible (default OFF).
Mesh factory handling
virtual csPtr< iMeshFactoryWrapper > | CreateMeshFactory (const char *name)=0
| Create an uninitialized mesh factory wrapper Assign to a csRef.
virtual csPtr< iMeshFactoryWrapper > | CreateMeshFactory (iMeshObjectFactory *factory, const char *name)=0
| Create a mesh factory wrapper for an existing mesh factory Assign to a csRef.
virtual csPtr< iMeshFactoryWrapper > | CreateMeshFactory (const char *classId, const char *name)=0
| Convenience function to create a mesh factory from a given type.
virtual iMeshFactoryWrapper * | FindMeshFactory (const char *name, iRegion *region=0)=0
| Find the given mesh factory.
virtual iMeshFactoryList * | GetMeshFactories ()=0
| Get the list of mesh factories.
virtual csPtr< iMeshFactoryWrapper > | LoadMeshFactory (const char *name, const char *loaderClassId, iDataBuffer *input)=0
| Convenience function to load a mesh factory from a given loader plugin.
Portal handling
virtual csPtr< iMeshWrapper > | CreatePortal (const char *name, iSector *sourceSector, const csVector3 &pos, iSector *destSector, csVector3 *vertices, int num_vertices, iPortal *&portal)=0
| Convenience function to create a portal from one sector to another.
virtual csPtr< iMeshWrapper > | CreatePortal (const char *name, iMeshWrapper *parentMesh, iSector *destSector, csVector3 *vertices, int num_vertices, iPortal *&portal)=0
| Convenience function to create a portal from one sector to another and make this portal a child mesh of another mesh.
virtual csPtr< iMeshWrapper > | CreatePortalContainer (const char *name, iSector *sector=0, const csVector3 &pos=csVector3(0, 0, 0))=0
| Create an empty portal container in some sector.
Region handling
virtual iRegion * | CreateRegion (const char *name)=0
| Create a new region and add it to the region list.
virtual iRegionList * | GetRegions ()=0
| Get the list of all regions.
Drawing related
virtual void | Draw (iCamera *c, iClipper2D *clipper, iMeshWrapper *mesh=0)=0
| Draw the 3D world given a camera and a clipper.
virtual int | GetBeginDrawFlags () const =0
| Get the required flags for 3D->BeginDraw() which should be called from the application.
virtual bool | GetClearScreen () const =0
| Get the value of the clear screen flag set with SetClearScreen().
virtual bool | GetClearZBuf () const =0
| Get the value of the clear Z-buffer flag set with SetClearZBuf().
virtual iTextureHandle * | GetContext () const =0
| Return the current drawing context.
virtual iRenderLoop * | GetCurrentDefaultRenderloop ()=0
| Returns the current render loop.
virtual uint | GetCurrentFrameNumber () const =0
| Get the current framenumber.
virtual bool | GetDefaultClearScreen () const =0
| Get default clear screen flag.
virtual bool | GetDefaultClearZBuf () const =0
| Get default clear z-buffer flag.
virtual iRenderLoopManager * | GetRenderLoopManager ()=0
| Retrieve the render loop manager.
virtual iRenderView * | GetTopLevelClipper () const =0
| Get the top-level clipper.
virtual void | PrecacheDraw (iRegion *region=0)=0
| This function precaches all meshes by calling GetRenderMeshes() on them.
virtual void | SetClearScreen (bool yesno)=0
| Require that the screen is cleared every frame.
virtual void | SetClearZBuf (bool yesno)=0
| Require that the Z-buffer is cleared every frame.
virtual void | SetContext (iTextureHandle *ctxt)=0
| Set the drawing context.
virtual bool | SetCurrentDefaultRenderloop (iRenderLoop *loop)=0
| Set the current render loop.
Preparation and relighting methods
virtual void | ForceRelight (iLight *light, iRegion *region=0)=0
| Force a relight for the given light.
virtual void | ForceRelight (iRegion *region=0, iProgressMeter *meter=0)=0
| Force a relight of all lighting.
virtual iCacheManager * | GetCacheManager ()=0
| Get the cache manager that the engine is currently using.
virtual void | GetDefaultMaxLightmapSize (int &w, int &h)=0
| Retrieve default maximum lightmap size.
virtual int | GetLightingCacheMode ()=0
| Get the mode for the lighting cache.
virtual int | GetMaxLightmapAspectRatio () const =0
| Get the maximum aspect ratio for lightmaps.
virtual void | GetMaxLightmapSize (int &w, int &h)=0
| Retrieve maximum lightmap size.
virtual bool | Prepare (iProgressMeter *meter=0)=0
| Prepare the engine.
virtual void | PrepareMeshes ()=0
| Calls UpdateMove for all meshes to initialise bounding boxes.
virtual void | PrepareTextures ()=0
| Prepare the textures.
virtual void | SetCacheManager (iCacheManager *cache_mgr)=0
| Set the cache manager that the engine will use.
virtual void | SetLightingCacheMode (int mode)=0
| Set the mode for the lighting cache (combination of CS_ENGINE_CACHE_???).
virtual void | SetMaxLightmapSize (int w, int h)=0
| Set the maximum lightmap dimensions.
virtual void | SetVFSCacheManager (const char *vfspath=0)=0
| Set the cache manager to the default VFS based cache manager.
virtual void | ShineLights (iRegion *region=0, iProgressMeter *meter=0)=0
| Calculate all lighting information.

## Detailed Description

This interface is the main interface to the 3D engine.

The engine is responsible for creating new engine-specific objects such as sectors, mesh objects, mesh object factories, lights, and so on.

Main creators of instances implementing this interface:

- 3D Engine plugin (crystalspace.engine.3d)

Main ways to get pointers to this interface:

- csQueryRegistry<iEngine> ()

Main users of this interface:

- Application.

Definition at line 176 of file engine.h.

## Member Function Documentation

virtual void iEngine::AddEngineFrameCallback | ( | iEngineFrameCallback * | cb | ) | `[pure virtual]`

Add a frame callback.

This will call IncRef() on the callback So make sure you call DecRef() to release your own reference.

virtual void iEngine::AddEngineSectorCallback | ( | iEngineSectorCallback * | cb | ) | `[pure virtual]`

Add a sector callback.

This will call IncRef() on the callback So make sure you call DecRef() to release your own reference.

virtual void iEngine::AddMeshAndChildren | ( | iMeshWrapper * | mesh | ) | `[pure virtual]`

Convenience function to add a mesh and all children of that mesh to the engine.

virtual void iEngine::ClearRenderPriorities | ( |  | ) | `[pure virtual]`

Clear all render priorities.

virtual csPtr<iMaterial> iEngine::CreateBaseMaterial | ( | iTextureWrapper * | txt | ) | `[pure virtual]`

Create a base material that can be used to give to the texture manager.

Assign to a csRef.

Parameters:

  | txt | The texture map this material will use. Note that this can be 0 in which case a base material without texture will be created.

Note:
  You will need to call iMaterialWrapper::Register() and iMaterialWrapper::GetMaterialHandler()->Prepare() on you new material if you load the material after iEngine::Prepare() has been called.

virtual iTextureWrapper* iEngine::CreateBlackTexture | ( | const char * | name,
|  | int | w,
|  | int | h,
|  | csColor * | transp,
|  | int | flags |
| ) |  |  | `[pure virtual]`

Create a black texture.

This is mostly useful for procedural textures.

Parameters:

  | name | The name to use for this texture in the engine
  | w | the texture width (must be a power of 2, eg 64, 128, 256, 512...)
  | h | the texture height (must be a power of 2, eg 64, 128, 256, 512...)
  | transp | pixels in the image with this key color will be considered transparent instead of being drawn
  | flags | see CreateTexture()

See also:
  CreateTexture() note about registering textures.

virtual csPtr<iCamera> iEngine::CreateCamera | ( |  | ) | `[pure virtual]`

Create a new camera.

Assign to a csRef.

virtual csPtr<iFrustumView> iEngine::CreateFrustumView | ( |  | ) | `[pure virtual]`

Create a iFrustumView instance that you can give to iVisibilityCuller->CastShadows().

You can initialize that instance so that your own function is called for every object that is being visited.

virtual csPtr<iLight> iEngine::CreateLight | ( | const char * | name,
|  | const csVector3 & | pos,
|  | float | radius,
|  | const csColor & | color,
|  | csLightDynamicType | dyntype = `CS_LIGHT_DYNAMICTYPE_STATIC` |
| ) |  |  | `[pure virtual]`

Create a static/pseudo-dynamic light.

Assign to a csRef.

Parameters:

  | name | the engine name for this light (may be 0)
  | pos | the position of this light in world coordinates
  | radius | the maximum distance at which this light will affect objects
  | color | the color of this light (also affects light intensity)
  | dyntype | is the type of the light. This can be CS_LIGHT_DYNAMICTYPE_DYNAMIC, CS_LIGHT_DYNAMICTYPE_PSEUDO, or CS_LIGHT_DYNAMICTYPE_STATIC. Note that after creating a light you must add it to a sector by calling sector->GetLights ()->Add (light); If the light is dynamic you also must call Setup() to calculate lighting. Otherwise you must use engine->ForceRelight() if you create a light after calling engine->Prepare(). Otherwise you can let engine->Prepare() do it.

Note! If you are using a system with hardware accelerated lighting (i.e. no lightmaps) then the discussion above is not relevant.

virtual csPtr<iLoaderContext> iEngine::CreateLoaderContext | ( | iRegion * | region = `0`,
|  | bool | curRegOnly = `true` |
| ) |  |  | `[pure virtual]`

Create a loader context that you can give to loader plugins.

It will basically allow loader plugins to find materials.

Parameters:

  | region | optional loader region
  | curRegOnly | if region is valid and and curRegOnly is true then only that region will be searched. Assign to a csRef.

virtual iMaterialWrapper* iEngine::CreateMaterial | ( | const char * | name,
|  | iTextureWrapper * | texture |
| ) |  |  | `[pure virtual]`

Register a material to be loaded during Prepare().

Parameters:

  | name | engine name for this material
  | texture | texture to use for this material

virtual csPtr<iMeshFactoryWrapper> iEngine::CreateMeshFactory | ( | const char * | name | ) | `[pure virtual]`

Create an uninitialized mesh factory wrapper Assign to a csRef.

Parameters:

  | name | the engine name for the factory wrapper

virtual csPtr<iMeshFactoryWrapper> iEngine::CreateMeshFactory | ( | iMeshObjectFactory * | factory,
|  | const char * | name |
| ) |  |  | `[pure virtual]`

Create a mesh factory wrapper for an existing mesh factory Assign to a csRef.

Parameters:

  | factory | the mesh factory to be wrapped, the engine doesn't "know" about a mesh factory until associated with a FactoryWrapper
  | name | the engine name for the factory wrapper

virtual csPtr<iMeshFactoryWrapper> iEngine::CreateMeshFactory | ( | const char * | classId,
|  | const char * | name |
| ) |  |  | `[pure virtual]`

Convenience function to create a mesh factory from a given type.

Parameters:

  | classId | the SCF name of the plugin (like 'crystalspace.mesh.object.ball'). The type plugin will only be loaded if needed.
  | name | The factory will be registered with the engine under the given name. If there is already a factory with that name no new factory will be created but the found one is returned instead. If the name is 0 then no name will be set and no check will happen if the factory already exists.

Returns:
  0 on failure; you must assign the result to a csRef or use DecRef().

virtual csPtr<iMeshWrapper> iEngine::CreateMeshWrapper | ( | const char * | name | ) | `[pure virtual]`

Create an uninitialized mesh wrapper Assign to a csRef.

virtual csPtr<iMeshWrapper> iEngine::CreateMeshWrapper | ( | const char * | classid,
|  | const char * | name,
|  | iSector * | sector = `0`,
|  | const csVector3 & | pos = `csVector3(0, 0, 0)` |
| ) |  |  | `[pure virtual]`

Create a mesh wrapper from a class id.

This function will first make a factory from the plugin and then see if that factory itself implements iMeshObject too. This means this function is useful to create thing mesh objects (which are both factory and object at the same time). If that fails this function will call NewInstance() on the factory and return that object then.

Parameters:

  | classid | The SCF name of the plugin (like 'crystalspace.mesh.object.ball'). The type plugin will only be loaded if needed.
  | name | The engine name for the mesh wrapper; may be null. Different mesh objects can have the same name (in contrast with factory objects).
  | sector | the sector to initially place this mesh in If 'sector' is 0 then the mesh object will not be set to a position.
  | pos | the position in the sector

Returns:
  The meshwrapper on success (assign to a csRef), or 0 on failure.

virtual csPtr<iMeshWrapper> iEngine::CreateMeshWrapper | ( | iMeshObject * | meshobj,
|  | const char * | name,
|  | iSector * | sector = `0`,
|  | const csVector3 & | pos = `csVector3(0, 0, 0)` |
| ) |  |  | `[pure virtual]`

Create a mesh wrapper for an existing mesh object.

Parameters:

  | meshobj | the mesh object
  | name | The engine name for the mesh wrapper; may be null. Different mesh objects can have the same name (in contrast with factory objects).
  | sector | the sector to initially place this mesh in If 'sector' is 0 then the mesh object will not be set to a position.
  | pos | the position in the sector

Returns:
  The meshwrapper on success (assign to a csRef), or 0 on failure.

virtual csPtr<iMeshWrapper> iEngine::CreateMeshWrapper | ( | iMeshFactoryWrapper * | factory,
|  | const char * | name,
|  | iSector * | sector = `0`,
|  | const csVector3 & | pos = `csVector3(0, 0, 0)` |
| ) |  |  | `[pure virtual]`

Convenience function to create a mesh object for a given factory.

Parameters:

  | factory | the factory that will produce this mesh
  | name | The engine name for the mesh wrapper; may be null. Different mesh objects can have the same name (in contrast with factory objects).
  | sector | the sector to initially place this mesh in If 'sector' is 0 then the mesh object will not be set to a position.
  | pos | the position in the sector

Returns:
  The meshwrapper on success (assign to a csRef), or 0 on failure.

virtual csPtr<iObjectWatcher> iEngine::CreateObjectWatcher | ( |  | ) | `[pure virtual]`

Create an object watcher instance that you can use to watch other objects.

The engine will not keep a reference to this object.

virtual csPtr<iMeshWrapper> iEngine::CreatePortal | ( | const char * | name,
|  | iSector * | sourceSector,
|  | const csVector3 & | pos,
|  | iSector * | destSector,
|  | csVector3 * | vertices,
|  | int | num_vertices,
|  | iPortal *& | portal |
| ) |  |  | `[pure virtual]`

Convenience function to create a portal from one sector to another.

Use SCF_QUERY_INTERFACE with iPortalContainer on the returned mesh for more control over the portal(s) in the portal object.

Parameters:

  | name | is the name of the portal container mesh to create the portal in. If the sourceSector already has a mesh with that name then that will be used. If there is already a mesh with that name but it is not a portal container then a new mesh will be created.
  | sourceSector | is the sector where the portal container will be placed.
  | pos | the position inside that sector.
  | destSector | the sector where the single portal that is created inside the portal object will point too.
  | vertices | list of vertices comprising the portal.
  | num_vertices | number of elements in 'vertices'.
  | portal | return value for the created portal.

Returns:
  The meshwrapper on success (assign to a csRef), or 0 on failure.

virtual csPtr<iMeshWrapper> iEngine::CreatePortal | ( | const char * | name,
|  | iMeshWrapper * | parentMesh,
|  | iSector * | destSector,
|  | csVector3 * | vertices,
|  | int | num_vertices,
|  | iPortal *& | portal |
| ) |  |  | `[pure virtual]`

Convenience function to create a portal from one sector to another and make this portal a child mesh of another mesh.

Use SCF_QUERY_INTERFACE with iPortalContainer on the returned mesh for more control over the portal(s) in the portal object.

Parameters:

  | name | is the name of the portal container mesh to create the portal in. If the parentMesh already has a mesh with that name then that will be used. If there is already a mesh with that name but it is not a portal container then a new mesh will be created.
  | parentMesh | is the mesh where the portal container will be placed as a child.
  | destSector | is the sector where the single portal that is created inside the portal object will point too.
  | vertices | list of vertices comprising the portal.
  | num_vertices | number of elements in 'vertices'.
  | portal | is a return value for the created portal.

Returns:
  The meshwrapper on success (assign to a csRef), or 0 on failure.

virtual csPtr<iMeshWrapper> iEngine::CreatePortalContainer | ( | const char * | name,
|  | iSector * | sector = `0`,
|  | const csVector3 & | pos = `csVector3(0, 0, 0)` |
| ) |  |  | `[pure virtual]`

Create an empty portal container in some sector.

Use this portal container to create portals to other sectors. Use SCF_QUERY_INTERFACE with iPortalContainer on the mesh object inside the returned mesh to control the portals.

Parameters:

  | name | of the portal mesh.
  | sector | is the location of the portal object and not the sector the portals will point too. If not given then the portal container is not put in any mesh.
  | pos | is an optional position inside the sector (if given).

Returns:
  The meshwrapper on success (assign to a csRef), or 0 on failure.

virtual iRegion* iEngine::CreateRegion | ( | const char * | name | ) | `[pure virtual]`

Create a new region and add it to the region list.

If the region already exists then this function will just return the pointer to that region.

Parameters:

  | name | the engine name for the region

Remarks:
  Can be removed with RemoveObject().

virtual iSector* iEngine::CreateSector | ( | const char * | name | ) | `[pure virtual]`

Create a empty sector with given name.

Parameters:

  | name | the sector name

virtual csPtr<iMeshWrapper> iEngine::CreateSectorWallsMesh | ( | iSector * | sector,
|  | const char * | name |
| ) |  |  | `[pure virtual]`

Convenience function to create the thing containing the convex outline of a sector.

The thing will be empty but it will have CS_ZBUF_FILL set (so that the Z-buffer will be filled by the polygons of this object) and have 'wall' as render priority. This version creates a mesh wrapper. Assign to a csRef.

Parameters:

  | sector | the sector to add walls to
  | name | the engine name of the walls mesh that will be created

virtual iTextureWrapper* iEngine::CreateTexture | ( | const char * | name,
|  | const char * | fileName,
|  | csColor * | transp,
|  | int | flags |
| ) |  |  | `[pure virtual]`

Create a texture from a file.

Parameters:

  | name | The name to use for this texture in the engine
  | fileName | the filename (on the VFS!) of the texture to load
  | transp | pixels in the image with this key color will be considered transparent instead of being drawn
  | flags | One or more texturing flags OR'd together, flag include CS_TEXTURE_2D image will be used only for 2D drawing CS_TEXTURE_3D image will be textured onto 3D polygon (this is almost always the flag you want) CS_TEXTURE_NOMIPMAPS texture will not be mipmapped before use

Note:
  You will need to call iTextureWrapper::Register() on you new texture if you load the texture after iEngine::Prepare() has been called.

virtual csPtr<iMeshWrapper> iEngine::CreateThingMesh | ( | iSector * | sector,
|  | const char * | name |
| ) |  |  | `[pure virtual]`

Convenience function to create a thing mesh in a sector.

This mesh will have CS_ZBUF_USE set (use Z-buffer fully) and have 'object' as render priority. This means this function is useful for general objects. Assign to a csRef.

Parameters:

  | sector | the sector to add the object to
  | name | the engine name of the mesh that will be created

virtual void iEngine::DelayedRemoveObject | ( | csTicks | delay,
|  | iBase * | object |
| ) |  |  | `[pure virtual]`

This function can be used to remove an object after a specific amount of time.

This is mostly useful for particle systems (like explosions) that you want to live for a specific time before they are automatically cleaned up by the engine. Note that calling this function will cause the engine to keep an additional reference until it is time to delete the object.

virtual void iEngine::DeleteAll | ( |  | ) | `[pure virtual]`

Delete everything in the engine.

virtual void iEngine::Draw | ( | iCamera * | c,
|  | iClipper2D * | clipper,
|  | iMeshWrapper * | mesh = `0` |
| ) |  |  | `[pure virtual]`

Draw the 3D world given a camera and a clipper.

Note that in order to be able to draw using the given 3D driver all textures must have been registered to that driver (using Prepare()). Note that you need to call Prepare() again if you switch to another 3D driver.

If a mesh is given then only that single mesh is rendered. Note that in that case the mesh will only be rendered if it is in the same sector as the camera!

virtual iCameraPosition* iEngine::FindCameraPosition | ( | const char * | name,
|  | iRegion * | region = `0` |
| ) |  |  | `[pure virtual]`

Find the given camera position.

The name can be a normal name. In that case this function will look in all regions except if region is not 0 in which case it will only look in that region. If the name is specified as 'regionname/objectname' then this function will only look in the specified region and return 0 if that region doesn't contain the object or the region doesn't exist. In this case the region parameter is ignored.

Parameters:

  | name | the engine name of the desired camera position
  | region | if specified, search only this region (also see note above)

virtual iCollection* iEngine::FindCollection | ( | const char * | name,
|  | iRegion * | region = `0` |
| ) |  |  | `[pure virtual]`

Find the given collection.

The name can be a normal name. In that case this function will look in all regions except if region is not 0 in which case it will only look in that region. If the name is specified as 'regionname/objectname' then this function will only look in the specified region and return 0 if that region doesn't contain the object or the region doesn't exist. In this case the region parameter is ignored.

Parameters:

  | name | the engine name of the desired collection
  | region | if specified, search only this region (also see note above)

Deprecated:
  Collections are obsolete.

virtual iLight* iEngine::FindLight | ( | const char * | Name,
|  | bool | RegionOnly = `false` |
| ) |  |  | const`[pure virtual]`

Find a static/pseudo-dynamic light by name.

Parameters:

  | Name | the engine name of the desired light
  | RegionOnly | (parameter presently unused)

virtual iLight* iEngine::FindLightID | ( | const char * | light_id | ) | const`[pure virtual]`

Find a static/pseudo-dynamic light by id.

Parameters:

  | light_id | a 16-byte MD5 checksum for the light.

virtual iMaterialWrapper* iEngine::FindMaterial | ( | const char * | name,
|  | iRegion * | region = `0` |
| ) |  |  | `[pure virtual]`

Find the given material.

The name can be a normal name. In that case this function will look in all regions except if region is not 0 in which case it will only look in that region. If the name is specified as 'regionname/objectname' then this function will only look in the specified region and return 0 if that region doesn't contain the object or the region doesn't exist. In this case the region parameter is ignored.

Parameters:

  | name | the engine name of the desired material
  | region | if specified, search only this region (also see note above)

virtual iMeshFactoryWrapper* iEngine::FindMeshFactory | ( | const char * | name,
|  | iRegion * | region = `0` |
| ) |  |  | `[pure virtual]`

Find the given mesh factory.

The name can be a normal name. In that case this function will look in all regions except if region is not 0 in which case it will only look in that region. If the name is specified as 'regionname/objectname' then this function will only look in the specified region and return 0 if that region doesn't contain the object or the region doesn't exist. In this case the region parameter is ignored.

Parameters:

  | name | the engine name of the desired mesh factory
  | region | if specified, search only this region (also see note above)

virtual iMeshWrapper* iEngine::FindMeshObject | ( | const char * | name,
|  | iRegion * | region = `0` |
| ) |  |  | `[pure virtual]`

Find the given mesh object.

The name can be a normal name. In that case this function will look in all regions except if region is not 0 in which case it will only look in that region. If the name is specified as 'regionname/objectname' then this function will only look in the specified region and return 0 if that region doesn't contain the object or the region doesn't exist. In this case the region parameter is ignored.

Parameters:

  | name | the engine name of the desired mesh
  | region | if specified, search only this region (also see note above)

virtual iSector* iEngine::FindSector | ( | const char * | name,
|  | iRegion * | region = `0` |
| ) |  |  | `[pure virtual]`

Find the given sector.

The name can be a normal name. In that case this function will look in all regions except if region is not 0 in which case it will only look in that region. If the name is specified as 'regionname/objectname' then this function will only look in the specified region and return 0 if that region doesn't contain the object or the region doesn't exist. In this case the region parameter is ignored.

Parameters:

  | name | the engine name of the desired sector
  | region | if specified, search only this region (also see note above)

virtual iTextureWrapper* iEngine::FindTexture | ( | const char * | name,
|  | iRegion * | region = `0` |
| ) |  |  | `[pure virtual]`

Find the given texture.

The name can be a normal name. In that case this function will look in all regions except if region is not 0 in which case it will only look in that region. If the name is specified as 'regionname/objectname' then this function will only look in the specified region and return 0 if that region doesn't contain the object or the region doesn't exist. In this case the region parameter is ignored.

Parameters:

  | name | the engine name of the desired texture
  | region | if specified, search only this region (also see note above)

virtual void iEngine::ForceRelight | ( | iLight * | light,
|  | iRegion * | region = `0` |
| ) |  |  | `[pure virtual]`

Force a relight for the given light.

This is useful to update the lightmaps after a static or pseudo-dynamic light has been added (don't use this for dynamic lights). If there are a lot of objects this function can be slow. The optional region can be given to limit calculation to objects in the region.

The current flags set with SetLightingCacheMode() controls if the lightmaps will be cached or not.

Parameters:

  | light | The newly added light to shine
  | region | If supplied, only affect objects in this region

virtual void iEngine::ForceRelight | ( | iRegion * | region = `0`,
|  | iProgressMeter * | meter = `0` |
| ) |  |  | `[pure virtual]`

Force a relight of all lighting.

It is better to call this instead of calling engine->Prepare() again as engine->Prepare() will also do other stuff (like registering textures). Warning! This function can be very slow (depending on the number of lights and objects in the world). The optional region can be given to limit calculation to objects in the region.

The current flags set with SetLightingCacheMode() controls if the lightmaps will be cached or not.

Parameters:

  | region | only relight objects in this region (will relight every object in the engine by default)
  | meter | If supplied, the meter object will be called back periodically to report the progress of engine lighting calculation.

virtual long iEngine::GetAlphaRenderPriority | ( |  | ) | `[pure virtual]`

Get the render priority for alpha objects (attached to 'alpha' name).

virtual void iEngine::GetAmbientLight | ( | csColor & |  | ) | const`[pure virtual]`

Return the amount of ambient light.

virtual int iEngine::GetBeginDrawFlags | ( |  | ) | const`[pure virtual]`

Get the required flags for 3D->BeginDraw() which should be called from the application.

These flags must be or-ed with optional other flags that the application might be interested in. Use SetClearZBuf() to let this function return that the Z-buffer must be cleared.

virtual iCacheManager* iEngine::GetCacheManager | ( |  | ) | `[pure virtual]`

Get the cache manager that the engine is currently using.

virtual iCameraPositionList* iEngine::GetCameraPositions | ( |  | ) | `[pure virtual]`

Get the list of camera positions.

virtual bool iEngine::GetClearScreen | ( |  | ) | const`[pure virtual]`

Get the value of the clear screen flag set with SetClearScreen().

virtual bool iEngine::GetClearZBuf | ( |  | ) | const`[pure virtual]`

Get the value of the clear Z-buffer flag set with SetClearZBuf().

virtual iCollectionList* iEngine::GetCollections | ( |  | ) | `[pure virtual]`

Get the list of collections.

Deprecated:
  Collections are obsolete.

virtual iTextureHandle* iEngine::GetContext | ( |  | ) | const`[pure virtual]`

Return the current drawing context.

virtual iRenderLoop* iEngine::GetCurrentDefaultRenderloop | ( |  | ) | `[pure virtual]`

Returns the current render loop.

Remarks:
  This will the loop that is set to be the current default with SetCurrentDefaultRenderloop(). This doesn't have to be the engine's default render loop (note the difference between the "current" and "default" render loop - former one is the loop used currently for drawing, latter one is a default loop created at engine initialization time.) To retrieve the default loop, use

        GetRenderLoopManager()->Retrieve (#CS_DEFAULT_RENDERLOOP_NAME);

virtual uint iEngine::GetCurrentFrameNumber | ( |  | ) | const`[pure virtual]`

Get the current framenumber.

This should be incremented once every Draw

virtual void iEngine::GetDefaultAmbientLight | ( | csColor & | c | ) | const`[pure virtual]`

Return the default amount of ambient light.

virtual bool iEngine::GetDefaultClearScreen | ( |  | ) | const`[pure virtual]`

Get default clear screen flag.

virtual bool iEngine::GetDefaultClearZBuf | ( |  | ) | const`[pure virtual]`

Get default clear z-buffer flag.

virtual void iEngine::GetDefaultMaxLightmapSize | ( | int & | w,
|  | int & | h |
| ) |  |  | `[pure virtual]`

Retrieve default maximum lightmap size.

Parameters:

  | w | lightmap width
  | h | lightmap height

virtual int iEngine::GetLightingCacheMode | ( |  | ) | `[pure virtual]`

Get the mode for the lighting cache.

virtual csPtr<iLightIterator> iEngine::GetLightIterator | ( | iRegion * | region = `0` | ) | `[pure virtual]`

Create an iterator to iterate over all static lights of the engine.

Assign to a csRef.

Parameters:

  | region | only iterate over the lights in this region (otherwise iterate over all lights)

virtual iMaterialList* iEngine::GetMaterialList | ( |  | ) | const`[pure virtual]`

Get the list of all materials.

virtual int iEngine::GetMaxLightmapAspectRatio | ( |  | ) | const`[pure virtual]`

Get the maximum aspect ratio for lightmaps.

virtual void iEngine::GetMaxLightmapSize | ( | int & | w,
|  | int & | h |
| ) |  |  | `[pure virtual]`

Retrieve maximum lightmap size.

Parameters:

  | w | lightmap width
  | h | lightmap height

virtual iMeshList* iEngine::GetMeshes | ( |  | ) | `[pure virtual]`

Get the list of meshes.

virtual iMeshFactoryList* iEngine::GetMeshFactories | ( |  | ) | `[pure virtual]`

Get the list of mesh factories.

virtual int iEngine::GetNearbyLights | ( | iSector * | sector,
|  | const csBox3 & | box,
|  | iLight ** | lights,
|  | int | max_num_lights |
| ) |  |  | `[pure virtual]`

This routine returns all lights which might affect an object with some bounding box.

It will only return as many lights as the size that you specified for the light array. The returned lights are not guaranteed to be sorted but they are guaranteed to be the specified number of lights closest to the given position.
This function returns the actual number of lights added to the 'lights' array.

virtual int iEngine::GetNearbyLights | ( | iSector * | sector,
|  | const csVector3 & | pos,
|  | iLight ** | lights,
|  | int | max_num_lights |
| ) |  |  | `[pure virtual]`

This routine returns all lights which might affect an object at some position.

It will only return as many lights as the size that you specified for the light array. The returned lights are not guaranteed to be sorted but they are guaranteed to be the specified number of lights closest to the given position.
This function returns the actual number of lights added to the 'lights' array.

virtual csPtr<iMeshWrapperIterator> iEngine::GetNearbyMeshes | ( | iSector * | sector,
|  | const csVector3 & | start,
|  | const csVector3 & | end,
|  | bool | crossPortals = `true` |
| ) |  |  | `[pure virtual]`

This routine returns an iterator to iterate over all meshes that intersect with a beam.

If crossPortals is true it will search through portals. Otherwise it will limit the search to the sector passed in. Portal visibility is tested fromt the start of the beam.

virtual csPtr<iMeshWrapperIterator> iEngine::GetNearbyMeshes | ( | iSector * | sector,
|  | const csBox3 & | box,
|  | bool | crossPortals = `true` |
| ) |  |  | `[pure virtual]`

This routine returns an iterator to iterate over all meshes that are in a box.

If crossPortals is true it will search through portals. Otherwise it will limit the search to the sector passed in. Portal visibility is tested with the center of the box.

virtual csPtr<iMeshWrapperIterator> iEngine::GetNearbyMeshes | ( | iSector * | sector,
|  | const csVector3 & | pos,
|  | float | radius,
|  | bool | crossPortals = `true` |
| ) |  |  | `[pure virtual]`

This routine returns an iterator to iterate over all meshes that are within a radius of a given position.

If crossPortals is true it will search through portals. Otherwise it will limit the search to the sector passed in.

virtual csPtr<iObjectIterator> iEngine::GetNearbyObjects | ( | iSector * | sector,
|  | const csVector3 & | pos,
|  | float | radius,
|  | bool | crossPortals = `true` |
| ) |  |  | `[pure virtual]`

This routine returns an iterator to iterate over all objects that are within a radius of a given position.

The current implementation only does meshes but in future lights will also be supported. You can use SCF_QUERY_INTERFACE to get any interface from the returned objects. If crossPortals is true it will search through portals. Otherwise it will limit the search to the sector passed in. If you only want to have meshes then it is more efficient to call GetNearbyMeshes() as you can then avoid the call to SCF_QUERY_INTERFACE.

virtual csPtr<iSectorIterator> iEngine::GetNearbySectors | ( | iSector * | sector,
|  | const csBox3 & | box |
| ) |  |  | `[pure virtual]`

This routine returns an iterator to iterate over all nearby sectors.

Assign to a csRef. In the iterator you can also fetch the position for every sector. Normally that position will be equal to the given input position here (pos) but if there are space warping portals involved then the position returned by the iterator is the warped position relative to the sector returned by the iterator.

virtual csPtr<iSectorIterator> iEngine::GetNearbySectors | ( | iSector * | sector,
|  | const csVector3 & | pos,
|  | float | radius |
| ) |  |  | `[pure virtual]`

This routine returns an iterator to iterate over all nearby sectors.

Assign to a csRef. In the iterator you can also fetch the position for every sector. Normally that position will be equal to the given input position here (pos) but if there are space warping portals involved then the position returned by the iterator is the warped position relative to the sector returned by the iterator.

virtual long iEngine::GetObjectRenderPriority | ( |  | ) | `[pure virtual]`

Get the render priority for general objects (attached to 'object' name).

virtual long iEngine::GetPortalRenderPriority | ( |  | ) | `[pure virtual]`

Get the render priority for portal objects (attached to 'portal' name).

virtual iRegionList* iEngine::GetRegions | ( |  | ) | `[pure virtual]`

Get the list of all regions.

virtual iRenderLoopManager* iEngine::GetRenderLoopManager | ( |  | ) | `[pure virtual]`

Retrieve the render loop manager.

virtual long iEngine::GetRenderPriority | ( | const char * | name | ) | const`[pure virtual]`

Get a render priority by name.

Parameters:

  | name | is the name you want (usually one of 'sky', 'portal', 'wall', 'object', or 'alpha' but you can define your own render priorities).

Returns:
  0 if render priority doesn't exist.

virtual int iEngine::GetRenderPriorityCount | ( |  | ) | const`[pure virtual]`

Get the number of render priorities.

virtual const char* iEngine::GetRenderPriorityName | ( | long | priority | ) | const`[pure virtual]`

Get the name of the render priority or 0 if none existant.

virtual csRenderPrioritySorting iEngine::GetRenderPrioritySorting | ( | long | priority | ) | const`[pure virtual]`

Get the render priority sorting flag.

virtual csRenderPrioritySorting iEngine::GetRenderPrioritySorting | ( | const char * | name | ) | const`[pure virtual]`

Get the render priority sorting flag.

virtual bool iEngine::GetSaveableFlag | ( |  | ) | `[pure virtual]`

Get whether saving should be possible (default OFF).

virtual iSectorList* iEngine::GetSectors | ( |  | ) | `[pure virtual]`

Get the list of sectors.

virtual long iEngine::GetSkyRenderPriority | ( |  | ) | `[pure virtual]`

Get the render priority for sky objects (attached to 'sky' name).

virtual int iEngine::GetTextureFormat | ( |  | ) | const`[pure virtual]`

Query the format to load textures (usually this depends on texture manager).

virtual iTextureList* iEngine::GetTextureList | ( |  | ) | const`[pure virtual]`

Get the list of all textures.

virtual iRenderView* iEngine::GetTopLevelClipper | ( |  | ) | const`[pure virtual]`

Get the top-level clipper.

virtual iSharedVariableList* iEngine::GetVariableList | ( |  | ) | const`[pure virtual]`

Get the list of all shared variables.

virtual csPtr<iMeshWrapperIterator> iEngine::GetVisibleMeshes | ( | iSector * | sector,
|  | const csFrustum & | frustum |
| ) |  |  | `[pure virtual]`

This routine returns an iterator to iterate over all meshes that are potentially visible as seen from a given position.

This routine has a frustum restricting the view. CURRENTLY NOT IMPLEMENTED!

virtual csPtr<iMeshWrapperIterator> iEngine::GetVisibleMeshes | ( | iSector * | sector,
|  | const csVector3 & | pos |
| ) |  |  | `[pure virtual]`

This routine returns an iterator to iterate over all meshes that are potentially visible as seen from a given position.

This routine assumes full 360 degree visibility. CURRENTLY NOT IMPLEMENTED!

virtual csPtr<iObjectIterator> iEngine::GetVisibleObjects | ( | iSector * | sector,
|  | const csFrustum & | frustum |
| ) |  |  | `[pure virtual]`

This routine returns an iterator to iterate over all objects that are potentially visible as seen from a given position.

This routine has a frustum restricting the view. You can use SCF_QUERY_INTERFACE to get any interface from the returned objects.

If you only want meshes then use GetVisibleMeshes(). CURRENTLY NOT IMPLEMENTED!

virtual csPtr<iObjectIterator> iEngine::GetVisibleObjects | ( | iSector * | sector,
|  | const csVector3 & | pos |
| ) |  |  | `[pure virtual]`

This routine returns an iterator to iterate over all objects that are potentially visible as seen from a given position.

This routine assumes full 360 degree visibility. You can use SCF_QUERY_INTERFACE to get any interface from the returned objects.

If you only want meshes then use GetVisibleMeshes(). CURRENTLY NOT IMPLEMENTED!

virtual long iEngine::GetWallRenderPriority | ( |  | ) | `[pure virtual]`

Get the render priority for wall objects (attached to 'wall' name).

virtual csPtr<iMeshFactoryWrapper> iEngine::LoadMeshFactory | ( | const char * | name,
|  | const char * | loaderClassId,
|  | iDataBuffer * | input |
| ) |  |  | `[pure virtual]`

Convenience function to load a mesh factory from a given loader plugin.

Parameters:

  | name | engine name for the mesh factory
  | loaderClassId | the SCF class name of the desired mesh factory plugin
  | input | data to initialize the mesh factory (plugin-specific) Assign to a csRef.

virtual csPtr<iMeshWrapper> iEngine::LoadMeshWrapper | ( | const char * | name,
|  | const char * | loaderClassId,
|  | iDataBuffer * | input,
|  | iSector * | sector,
|  | const csVector3 & | pos |
| ) |  |  | `[pure virtual]`

Convenience function to load a mesh object from a given loader plugin.

Parameters:

  | name | The engine name for the mesh wrapper; may be null. Different mesh objects can have the same name (in contrast with factory objects).
  | loaderClassId | the SCF class of the loader to use to create the meshwrapper
  | input | data passed to the loader to generate the mesh
  | sector | the sector to initially place this mesh in If 'sector' is 0 then the mesh object will not be set to a position.
  | pos | the position in the sector

Returns:
  The meshwrapper on success (assign to a csRef), or 0 on failure.

virtual void iEngine::PrecacheDraw | ( | iRegion * | region = `0` | ) | `[pure virtual]`

This function precaches all meshes by calling GetRenderMeshes() on them.

By doing this the level will run smoother if you walk through it because all meshes will have had a chance to update caches and stuff.

Parameters:

  | region | is an optional region. If given then only objects in that region will be precached.

virtual bool iEngine::Prepare | ( | iProgressMeter * | meter = `0` | ) | `[pure virtual]`

Prepare the engine.

This function must be called after you loaded/created the world. It will prepare all lightmaps for use and also free all images that were loaded for the texture manager (the texture manager should have them locally now). The optional progress meter will be used to report progress.

The behaviour regarding cached lighting depends on the flag you can set with the SetLightingCacheMode() function. The default behaviour is to read the lightmap cache when present but don't calculate lighting if cache is not present.

Parameters:

  | meter | If supplied, the meter object will be called back periodically to report the progress of engine preparation.

virtual void iEngine::PrepareMeshes | ( |  | ) | `[pure virtual]`

Calls UpdateMove for all meshes to initialise bounding boxes.

Prepare() will call this function automatically so you normally don't have to call it.

virtual void iEngine::PrepareTextures | ( |  | ) | `[pure virtual]`

Prepare the textures.

It will initialise all loaded textures for the texture manager. (Normally you shouldn't call this function directly, because it will be called by Prepare() for you. This function will also prepare all loaded materials after preparing the textures.

virtual iObject* iEngine::QueryObject | ( |  | ) | `[pure virtual]`

Get the iObject for the engine.

virtual void iEngine::RegisterRenderPriority | ( | const char * | name,
|  | long | priority,
|  | csRenderPrioritySorting | rendsort = `CS_RENDPRI_SORT_NONE` |
| ) |  |  | `[pure virtual]`

Register a new render priority.

Render priorities are assigned to objects and controls the order in which objects are rendered by the engine.

Parameters:

  | name | a name to refer to this render priority
  | priority | a numerical priority; this is used to order the render priorities where lower numbers are rendered before higher numbers.
  | rendsort | One of the CS_RENDPRI_... flags. By default this is CS_RENDPRI_SORT_NONE. The following values are possible: CS_RENDPRI_SORT_NONE: objects in this render priority are not sorted. CS_RENDPRI_SORT_FRONT2BACK: sort objects front to back (as seen from camera viewpoint). CS_RENDPRI_SORT_BACK2FRONT: sort objects back to front.

Note:
  The default render priorities are 'sky', 'portal', 'wall', 'object' and 'alpha' (in that priority order, where sky is rendered first and alpha is rendered last). Should you wish to add your own render priority, you must call ClearRenderPriorities() and re-add the default render priorities along with your own new priorities.

virtual void iEngine::RemoveDelayedRemoves | ( | bool | remove = `false` | ) | `[pure virtual]`

Clear all delayed removals.

Parameters:

  | remove | if true then the objects will also be removed from engine. Otherwise they are simply removed from this list.

virtual void iEngine::RemoveEngineFrameCallback | ( | iEngineFrameCallback * | cb | ) | `[pure virtual]`

Remove a frame callback.

virtual void iEngine::RemoveEngineSectorCallback | ( | iEngineSectorCallback * | cb | ) | `[pure virtual]`

Remove a sector callback.

virtual void iEngine::RemoveLight | ( | iLight * | light | ) | `[pure virtual]`

Remove a light and update all lightmaps.

This function only works correctly for dynamic or pseudo-dynamic static lights. If you give a normal static light then the light will be removed but lightmaps will not be affected. You can call ForceRelight() to force relighting then.

The current flags set with SetLightingCacheMode() controls if the lightmaps will be cached or not.

Parameters:

  | light | the light to remove

virtual bool iEngine::RemoveObject | ( | iBase * | object | ) | `[pure virtual]`

Convenience function to 'remove' a CS object from the engine.

This will not clear the object but it will remove all references to that object that the engine itself keeps. This function works for: iCameraPosition, iCollection, iLight, iMaterialWrapper, iMeshFactoryWrapper,iMeshWrapper, iRegion, iSector and iTextureWrapper. Note that the object is only removed if the resulting ref count will become zero. So basically this function only releases the references that the engine holds.

This function returns true if the engine recognized the object as one on which it can operate.

This function will also remove the object from the region it may be in.

virtual void iEngine::ResetWorldSpecificSettings | ( |  | ) | `[pure virtual]`

Reset a subset of flags/settings (which may differ from one world/map to another) to its defaults.

This currently includes:

- clear z buffer flag
- lightmap cell size
- maximum lightmap size

virtual void iEngine::SetAmbientLight | ( | const csColor & |  | ) | `[pure virtual]`

Set the amount of ambient light.

This has no effect until you recalculate the lightmaps.

virtual void iEngine::SetCacheManager | ( | iCacheManager * | cache_mgr | ) | `[pure virtual]`

Set the cache manager that the engine will use.

If this is not done then the engine will use its own cache manager based on VFS. This will do an incref on the given cache manager and a decref on the old one. The engine will release the cache manager at destruction time. To set the cache manager to the default VFS based cache manager for a given VFS directory you can use the following code:

     engine->SetVFSCacheManager ("/bla/bla");

virtual void iEngine::SetClearScreen | ( | bool | yesno | ) | `[pure virtual]`

Require that the screen is cleared every frame.

The engine itself will not use this setting but will only return the correct flag in GetBeginDrawFlags() so that the screen is actually cleared. Note that this requires that the application actually uses GetBeginDrawFlags() in the call to g3d->BeginDraw() (which it should). By default this flag is false. It is useful to set this flag to true if you have a level that doesn't itself have another way to initialize the screen.

Parameters:

  | yesno | true to clear the screen before each frame, false to leave the screen as-is (which may leave garbage on the screen)

virtual void iEngine::SetClearZBuf | ( | bool | yesno | ) | `[pure virtual]`

Require that the Z-buffer is cleared every frame.

The engine itself will not use this setting but will only return the correct flag in GetBeginDrawFlags() so that the Z-buffer is actually cleared. Note that this requires that the application actually uses GetBeginDrawFlags() in the call to g3d->BeginDraw() (which it should). By default this flag is false. It is useful to set this flag to true if you have a level that doesn't itself have another way to initialize the Z-buffer.

Parameters:

  | yesno | true to clear the Z buffer after each frame, false to leave the zbuffer as-is

virtual void iEngine::SetContext | ( | iTextureHandle * | ctxt | ) | `[pure virtual]`

Set the drawing context.

This is a texture handle that is used as the procedural texture to render on. If this is 0 then the screen is assumed.

virtual bool iEngine::SetCurrentDefaultRenderloop | ( | iRenderLoop * | loop | ) | `[pure virtual]`

Set the current render loop.

Parameters:

  | loop | The loop to be made the current render loop.

Returns:
  Whether the change was successful (a value of 0 for `will` let the method fail.)

virtual void iEngine::SetLightingCacheMode | ( | int | mode | ) | `[pure virtual]`

Set the mode for the lighting cache (combination of CS_ENGINE_CACHE_???).

Default is CS_ENGINE_CACHE_READ | CS_ENGINE_CACHE_NOUPDATE.

Parameters:

  | mode | CS_ENGINE_CACHE_READ: Read the cache. CS_ENGINE_CACHE_WRITE: Write the cache. CS_ENGINE_CACHE_NOUPDATE: Don't update lighting automatically if it is not up-to-date. This is on by default. If you disable this then lighting will be calculated even if CS_ENGINE_CACHE_WRITE is not set which means that the resulting calculation is not written to the cache.

virtual void iEngine::SetMaxLightmapSize | ( | int | w,
|  | int | h |
| ) |  |  | `[pure virtual]`

Set the maximum lightmap dimensions.

Polys with lightmaps larger than this are not lit.

Parameters:

  | w | lightmap width
  | h | lightmap height

virtual void iEngine::SetSaveableFlag | ( | bool | enable | ) | `[pure virtual]`

Set whether saving should be possible (default OFF).

To allow saving of a world after it has been loaded, some objects may need to keep track of extra data that would otherwise not be needed if the world will never be written out again. The 'saveable' flag informs those objects about whether to keep that information or not. Saving a world with this flag disables is still possible, but the result might incomplete.

virtual void iEngine::SetVFSCacheManager | ( | const char * | vfspath = `0` | ) | `[pure virtual]`

Set the cache manager to the default VFS based cache manager.

Note that this function will not change the VFS current directory.

Parameters:

  | vfspath | is the path that will be used for the cache manager. If 0 then the current VFS directory will be used instead.

virtual void iEngine::ShineLights | ( | iRegion * | region = `0`,
|  | iProgressMeter * | meter = `0` |
| ) |  |  | `[pure virtual]`

Calculate all lighting information.

Normally you shouldn't call this function directly, because it will be called by Prepare(). If the optional 'region' parameter is given then only lights will be recalculated for the given region.

Parameters:

  | region | If supplied, only calculate lighting for lights and objects in the given region.
  | meter | If supplied, the meter object will be called back periodically to report the progress of engine lighting calculation.

virtual void iEngine::WantToDie | ( | iMeshWrapper * | mesh | ) | `[pure virtual]`

Sometimes a mesh wants to destruct itself (for example a particle system that has only limited lifetime).

It can do that by calling this function on itself. The engine will then remove the object before the next frame.

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

- iengine/engine.h