Forests::PageLoader Class Reference

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

#include <PagedGeometry.h>

Inheritance diagram for Forests::PageLoader:

Public Member Functions
virtual void	loadPage (PageInfo &page)=0
	This should be overridden to load a specified region of entities. More...
virtual void	unloadPage (PageInfo &page)
	This may be overridden (optional) to unload custom data associated with a page. More...
virtual void	frameUpdate ()
	Provides a method for you to perform per-frame tasks for your PageLoader if overridden (optional) More...
virtual	~PageLoader ()
	Destructor This is defined here so the destructors of derived classes are called properly. More...

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)
	Call this from loadPage() to add an entity to the page being loaded. More...

Friends
class	GeometryPageManager

Detailed 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.

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.

Member Function Documentation

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::TreeLoader3D, Forests::TreeLoader2D, and Forests::GrassLoader.

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::GrassLoader.

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.

Referenced by Forests::PagedGeometry::update().

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.

References Forests::GeometryPage::addEntity(), and Forests::GeometryPage::addEntityToBoundingBox().