Forests::PageLoader Class Reference

Description

A class which you extend to provide a callback function for loading entities.

Note

PagedGeometry comes pre-installed with several PageLoader classes, so you probably won't need to create you're own from scratch. See TreeLoader2D, TreeLoader3D, and GrassLoader for more info.

Unlike most entity managers, PagedGeometry does not allow you to simply add all your entities to the object, and let the engine run from that point on. Since the PagedGeometry engine is designed to work with extremely large game areas, preloading everything would take far too much memory. Instead, it pages the geometry. In other words, it loads the geometry only as needed.

Whenever the engine needs a specific region of geometry to be loaded, it calls on your page loader class's loadPage() function. It's completely up to you how this function loads the entities, just as long as it gets the job done. When loadPage() is called, you are provided with a PageInfo variable, which specifies the boundary which must be loaded (in addition to other useful info). Make sure you don't add anything outside of this boundary, otherwise the results may be unpredictable.

Within loadPage(), you add entities by calling addEntity(). Simply supply the entity you want to add (you can add the same entity as many times as you want - in fact, you should do this as much as possible for better performance), and it's position, rotation, and scale (optional).

Note that your page loader may be asked to load an area which is out of your world's bounds (if you have any). In this case simply return without adding any entities.

To set up a page loader, just make a new sub-class (call it anything you want) of PageLoader. Your class must have one function:

void loadPage(const PageInfo &page);

Make sure you get the declaration right, otherwise it won't compile. The rest is up to you. You can define your own member functions if that helps, just as long as your loadPage() function does it's job right.

Once you've created your PageLoader-derived class, you need to attach it to a PagedGeometry object. To do this, simply create an instance of your class, and call

pagedGeometry->setPageLoader(yourPageLoader);

Remember: If you ever delete a PagedGeometry object, you will have to delete your page loader yourself (if you want to). The PagedGeometry destructor won't do this for you.

Definition at line 998 of file PagedGeometry.h.

Inheritance diagram for Forests::PageLoader:

Public Member Functions
virtual void	loadPage (PageInfo &page)=0
virtual void	unloadPage (PageInfo &page)
virtual void	frameUpdate ()
virtual	~PageLoader ()

Protected Member Functions
void	addEntity (Ogre::Entity *ent, const Ogre::Vector3 &position, const Ogre::Quaternion &rotation, const Ogre::Vector3 &scale=Ogre::Vector3::UNIT_SCALE, const Ogre::ColourValue &color=Ogre::ColourValue::White)

Private Attributes
GeometryPage *	geomPage

Friends
class	GeometryPageManager

Constructor & Destructor Documentation

~PageLoader()

virtual Forests::PageLoader::~PageLoader ( )

inlinevirtual

Destructor This is defined here so the destructors of derived classes are called properly.

Whether or not you actually implement a destructor is up to you.

Definition at line 1059 of file PagedGeometry.h.

Member Function Documentation

addEntity()

void Forests::PageLoader::addEntity ( Ogre::Entity *  ent, const Ogre::Vector3 &  position, const Ogre::Quaternion &  rotation, const Ogre::Vector3 &  scale = Ogre::Vector3::UNIT_SCALE, const Ogre::ColourValue &  color = Ogre::ColourValue::White  )

inlineprotected

Call this from loadPage() to add an entity to the page being loaded.

Parameters

ent	The entity to add. You may add the same entity multiple times.
position	The position where the entity will be placed.
rotation	The rotation to apply to the entity.
scale	The scale to apply to the entity.
color	The color to apply to the whole entity

Note

This copies the entity into the page, so don't make copies of the entity yourself; you may simply add the same entity over and over again. You are also free to destroy any entities you used when you are finished adding them.

Warning

This does not double-check whether or not your entity is within the proper boundaries (for better performance), so be careful not to add entities out of bounds. Depending on what current page types are being used, an out-of-bounds entity could cause your program to crash.

See also

PagedGeometry::addDetailLevel() for information about page types.

Definition at line 1081 of file PagedGeometry.h.

frameUpdate()

virtual void Forests::PageLoader::frameUpdate ( )

inlinevirtual

Provides a method for you to perform per-frame tasks for your PageLoader if overridden (optional)

frameUpdate() is completely optional, and unnecessary in most cases. However, if you ever need to update anything in your PageLoader per-frame, this function is here for that purpose.

Warning

This function is actually called every time PagedGeometry::update() is called, so if the application doesn't call PagedGeometry::update() as it should, this function will not be called either.

Note

frameUpdate() will be called after PagedGeometry::update() is called but before any GeometryPage's are actually loaded/unloaded for the frame.

Reimplemented in Forests::GrassLoader.

Definition at line 1052 of file PagedGeometry.h.

loadPage()

virtual void Forests::PageLoader::loadPage ( PageInfo &  page )

pure virtual

This should be overridden to load a specified region of entities.

Parameters

page	A PageInfo variable which includes boundary information and other useful values.

Override this function to load entities within the specified boundary. The boundary information is contained in the "page" parameter, along with other useful information as well (see the PageInfo documentation for more info about this).

Simply use the member function addEntity() to add all the entities you want. If you create your own objects inside this function, you are responsible for deleting it appropriately in unloadPage() or somewhere else. The PageInfo::userData member is useful here since you can point it to your data structures for later reference in unloadPage().

Warning

Do not ever add an entity outside of the given region, otherwise this may crash the program (depending on how the current page types handle this situation).

See also

PagedGeometry::addDetailLevel() for information about page types.

Implemented in Forests::RandomTreeLoader, Forests::GrassLoader, and Forests::TreeLoader2D.

unloadPage()

virtual void Forests::PageLoader::unloadPage ( PageInfo &  page )

inlinevirtual

This may be overridden (optional) to unload custom data associated with a page.

Parameters

page	A PageInfo variable which includes boundary information and other useful values.

During a PageLoader::loadPage() call, you are supposed to add entities by calling the addEntity() member function. In case you created anything else (particle systems, sound effects, etc.), this function gives you a chance to delete them along with the rest of the entities added with addEntity().

Note

Entities added with addEntity() will automatically be deleted after this function returns, so you don't need to worry about them.

In most cases you won't need to implement this function in your page loader at all, since addEntity() is usually all that is used.

Reimplemented in Forests::RandomTreeLoader, and Forests::GrassLoader.

Definition at line 1037 of file PagedGeometry.h.

Friends And Related Symbol Documentation

GeometryPageManager

friend class GeometryPageManager

friend

Definition at line 1088 of file PagedGeometry.h.

Field Documentation

geomPage

GeometryPage* Forests::PageLoader::geomPage

private

Definition at line 1091 of file PagedGeometry.h.

---

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

• source/main/terrain/paged/PagedGeometry.h