Memory Allocation

From CEGUI Wiki - Crazy Eddie's GUI System (Open Source)
Jump to: navigation, search

Written for CEGUI 0.8

Works with versions 0.8.x (stable)

Works with latest CEGUI stable!

CEGUI offers custom memory allocators in version 0.8. Starting with version 1.0 all Custom Allocators are removed again. The performance benefits mentioned in this article have meanwhile become neglectable in new operating systems such as Windows 7.

The 0.8 custom allocator feature allows you to custom allocate all CEGUI classes not using system heap at all. Preliminary tests with nedmalloc show ~40% performance increase when loading layouts. Other than that CEGUI doesn't allocate and deallocate at runtime so performance difference is negligible once everything is loaded. The main reason for all this hassle and increased code unreadability (new vs CEGUI_NEW_AO) is avoiding the use of system heap, not performance benefits (these are just a nice side effect). Avoiding system heap is apparently (as this was requested by multiple users) needed for games on consoles and PCs.


Instead of spoon feeding you the implementation merely allows you to delegate allocation. It's inspired by Ogre and allows very easy delegation to Ogre's allocators (included in CEGUIMemoryOgreAllocator.h). See CEGUIMemoryStdAllocator.h for base code for your own sophisticated allocators.

Supported allocation schemes (stock)

  • No custom allocation (new, delete, new [], delete [])
  • Std allocator (malloc, free)
  • Ogre allocator (uses Ogre's allocation schemes)

(It is very easy to add more allocators though, see the Std allocator for base code)

How does this concern end users (developers) of the library

If you don't care about allocation and are OK with using the system heap (this should hopefully be the majority), everything stays the same. "new" works the same as CEGUI_NEW_AO, CEGUI_NEW_PT and "new []" is the same as CEGUI_NEW_ARRAY_PT. The same applies to delete counterparts.

If you plan to use custom allocators you have to use CEGUI_NEW_AO (new allocated object) and CEGUI_DELETE_AO (delete allocated object) in symmetric pairs to allocate everything that is inherited from AllocatedObject<T> from the CEGUI namespace. Unless you delve deep into the codebase you shouldn't encounter CEGUI_NEW_PT (new primitive type), CEGUI_DELETE_PT (delete primitive type) and their array variants (CEGUI_NEW_ARRAY_PT, CEGUI_DELETE_ARRAY_PT).

Implementation details

Most classes are inherited from AllocatedObject<TheClass>. This base class does the dirty work of overloading new and delete for given class. The overloaded new and delete operators call allocator configured to work with given class.

For classes/types where this can't be done (mostly "primitive types") we use CEGUI_NEW_PT and supply desired allocator as a parameter to that macro. Same with CEGUI_DELETE_PT and their array variants.