OgreMemoryAllocatorConfig.h File Reference

This file configures Ogre's memory allocators. More...

#include "OgreMemoryAllocatedObject.h"
#include "OgreHeaderPrefix.h"
#include "OgreMemorySTLAllocator.h"
#include "OgreHeaderSuffix.h"

Namespaces
namespace	Ogre

Macros
#define	OGRE_ALLOC_T(T, count, category)   static_cast<T*>(::Ogre::CategorisedAllocPolicy<category>::allocateBytes(sizeof(T)*(count)))
	Allocate a block of memory for a primitive type, and indicate the category of usage.
#define	OGRE_ALLOC_T_ALIGN(T, count, category, align)   static_cast<T*>(::Ogre::CategorisedAlignAllocPolicy<category, align>::allocateBytes(sizeof(T)*(count)))
	Allocate a block of memory for a primitive type aligned to user defined boundaries, and indicate the category of usage.
#define	OGRE_ALLOC_T_SIMD(T, count, category)   static_cast<T*>(::Ogre::CategorisedAlignAllocPolicy<category>::allocateBytes(sizeof(T)*(count)))
	Allocate a block of memory for a primitive type aligned to SIMD boundaries, and indicate the category of usage.
#define	OGRE_DELETE   delete
#define	OGRE_DELETE_ARRAY_T(ptr, T, count, category)   if(ptr){for (size_t b = 0; b < count; ++b) { (ptr)[b].~T();} ::Ogre::CategorisedAllocPolicy<category>::deallocateBytes((void*)ptr);}
	Free the memory allocated with OGRE_NEW_ARRAY_T. Category is required to be restated to ensure the matching policy is used, count and type to call destructor.
#define	OGRE_DELETE_ARRAY_T_ALIGN(ptr, T, count, category, align)   if(ptr){for (size_t _b = 0; _b < count; ++_b) { (ptr)[_b].~T();} ::Ogre::CategorisedAlignAllocPolicy<category, align>::deallocateBytes((void*)ptr);}
	Free the memory allocated with OGRE_NEW_ARRAY_T_ALIGN. Category is required to be restated to ensure the matching policy is used, count and type to call destructor.
#define	OGRE_DELETE_ARRAY_T_SIMD(ptr, T, count, category)   if(ptr){for (size_t b = 0; b < count; ++b) { (ptr)[b].~T();} ::Ogre::CategorisedAlignAllocPolicy<category>::deallocateBytes((void*)ptr);}
	Free the memory allocated with OGRE_NEW_ARRAY_T_SIMD. Category is required to be restated to ensure the matching policy is used, count and type to call destructor.
#define	OGRE_DELETE_T(ptr, T, category)   if(ptr){(ptr)->~T(); ::Ogre::CategorisedAllocPolicy<category>::deallocateBytes((void*)ptr);}
	Free the memory allocated with OGRE_NEW_T. Category is required to be restated to ensure the matching policy is used.
#define	OGRE_DELETE_T_ALIGN(ptr, T, category, align)   if(ptr){(ptr)->~T(); ::Ogre::CategorisedAlignAllocPolicy<category, align>::deallocateBytes((void*)ptr);}
	Free the memory allocated with OGRE_NEW_T_ALIGN. Category is required to be restated to ensure the matching policy is used.
#define	OGRE_DELETE_T_SIMD(ptr, T, category)   if(ptr){(ptr)->~T(); ::Ogre::CategorisedAlignAllocPolicy<category>::deallocateBytes((void*)ptr);}
	Free the memory allocated with OGRE_NEW_T_SIMD. Category is required to be restated to ensure the matching policy is used.
#define	OGRE_FREE(ptr, category)   ::Ogre::CategorisedAllocPolicy<category>::deallocateBytes((void*)ptr)
	Free the memory allocated with OGRE_MALLOC or OGRE_ALLOC_T. Category is required to be restated to ensure the matching policy is used.
#define	OGRE_FREE_ALIGN(ptr, category, align)   ::Ogre::CategorisedAlignAllocPolicy<category, align>::deallocateBytes((void*)ptr)
	Free the memory allocated with either OGRE_MALLOC_ALIGN or OGRE_ALLOC_T_ALIGN. Category is required to be restated to ensure the matching policy is used.
#define	OGRE_FREE_SIMD(ptr, category)   ::Ogre::CategorisedAlignAllocPolicy<category>::deallocateBytes((void*)ptr)
	Free the memory allocated with either OGRE_MALLOC_SIMD or OGRE_ALLOC_T_SIMD. Category is required to be restated to ensure the matching policy is used.
#define	OGRE_MALLOC(bytes, category)   ::Ogre::CategorisedAllocPolicy<category>::allocateBytes(bytes)
	Allocate a block of raw memory, and indicate the category of usage.
#define	OGRE_MALLOC_ALIGN(bytes, category, align)   ::Ogre::CategorisedAlignAllocPolicy<category, align>::allocateBytes(bytes)
	Allocate a block of raw memory aligned to user defined boundaries, and indicate the category of usage.
#define	OGRE_MALLOC_SIMD(bytes, category)   ::Ogre::CategorisedAlignAllocPolicy<category>::allocateBytes(bytes)
	Allocate a block of raw memory aligned to SIMD boundaries, and indicate the category of usage.
#define	OGRE_NEW   new
#define	OGRE_NEW_ARRAY_T(T, count, category)   ::Ogre::constructN(static_cast<T*>(::Ogre::CategorisedAllocPolicy<category>::allocateBytes(sizeof(T)*(count))), count)
	Allocate a block of memory for 'count' primitive types - do not use for classes that inherit from AllocatedObject.
#define	OGRE_NEW_ARRAY_T_ALIGN(T, count, category, align)   ::Ogre::constructN(static_cast<T*>(::Ogre::CategorisedAlignAllocPolicy<category, align>::allocateBytes(sizeof(T)*(count))), count)
	Allocate a block of memory for 'count' primitive types aligned to user defined boundaries - do not use for classes that inherit from AllocatedObject.
#define	OGRE_NEW_ARRAY_T_SIMD(T, count, category)   ::Ogre::constructN(static_cast<T*>(::Ogre::CategorisedAlignAllocPolicy<category>::allocateBytes(sizeof(T)*(count))), count)
	Allocate a block of memory for 'count' primitive types aligned to SIMD boundaries - do not use for classes that inherit from AllocatedObject.
#define	OGRE_NEW_T(T, category)   new (::Ogre::CategorisedAllocPolicy<category>::allocateBytes(sizeof(T))) T
	Allocate space for one primitive type, external type or non-virtual type with constructor parameters.
#define	OGRE_NEW_T_ALIGN(T, category, align)   new (::Ogre::CategorisedAlignAllocPolicy<category, align>::allocateBytes(sizeof(T))) T
	Allocate space for one primitive type, external type or non-virtual type aligned to user defined boundaries.
#define	OGRE_NEW_T_SIMD(T, category)   new (::Ogre::CategorisedAlignAllocPolicy<category>::allocateBytes(sizeof(T))) T
	Allocate space for one primitive type, external type or non-virtual type aligned to SIMD boundaries.

Typedefs
typedef ScriptingAllocatedObject	Ogre::AbstractNodeAlloc
typedef AnimationAllocatedObject	Ogre::AnimableAlloc
typedef AnimationAllocatedObject	Ogre::AnimationAlloc
typedef AllocatedObject< AnimationAllocPolicy >	Ogre::AnimationAllocatedObject
typedef CategorisedAllocPolicy< Ogre::MEMCATEGORY_ANIMATION >	Ogre::AnimationAllocPolicy
typedef GeneralAllocatedObject	Ogre::ArchiveAlloc
typedef GeometryAllocatedObject	Ogre::BatchedGeometryAlloc
typedef RenderSysAllocatedObject	Ogre::BufferAlloc
typedef GeometryAllocatedObject	Ogre::BufferPackedAlloc
typedef GeneralAllocatedObject	Ogre::CodecAlloc
typedef ResourceAllocatedObject	Ogre::CompositorInstAlloc
typedef GeneralAllocatedObject	Ogre::ConfigAlloc
typedef GeneralAllocatedObject	Ogre::ControllerAlloc
typedef GeometryAllocatedObject	Ogre::DebugGeomAlloc
typedef GeneralAllocatedObject	Ogre::DynLibAlloc
typedef GeometryAllocatedObject	Ogre::EdgeDataAlloc
typedef GeneralAllocatedObject	Ogre::FactoryAlloc
typedef GeneralAllocatedObject	Ogre::FileSystemLayerAlloc
typedef SceneObjAllocatedObject	Ogre::FXAlloc
typedef AllocatedObject< GeneralAllocPolicy >	Ogre::GeneralAllocatedObject
typedef CategorisedAllocPolicy< Ogre::MEMCATEGORY_GENERAL >	Ogre::GeneralAllocPolicy
typedef AllocatedObject< GeometryAllocPolicy >	Ogre::GeometryAllocatedObject
typedef CategorisedAllocPolicy< Ogre::MEMCATEGORY_GEOMETRY >	Ogre::GeometryAllocPolicy
typedef RenderSysAllocatedObject	Ogre::GpuParamsAlloc
typedef ResourceSimdAllocObject	Ogre::HlmsAlloc
typedef GeneralAllocatedObject	Ogre::ImageAlloc
typedef GeometryAllocatedObject	Ogre::IndexDataAlloc
typedef SceneCtlAllocatedObject	Ogre::LodAlloc
typedef GeneralAllocatedObject	Ogre::LogAlloc
typedef SceneObjAllocatedObject	Ogre::MovableAlloc
typedef SceneCtlAllocatedObject	Ogre::NodeAlloc
typedef SceneObjAllocatedObject	Ogre::OverlayAlloc
typedef ResourceAllocatedObject	Ogre::PassAlloc
typedef GeometryAllocatedObject	Ogre::PatchAlloc
typedef GeneralAllocatedObject	Ogre::PluginAlloc
typedef GeneralAllocatedObject	Ogre::ProfilerAlloc
typedef GeometryAllocatedObject	Ogre::ProgMeshAlloc
typedef SceneCtlAllocatedObject	Ogre::RenderQueueAlloc
typedef RenderSysAllocatedObject	Ogre::RenderSysAlloc
typedef AllocatedObject< RenderSysAllocPolicy >	Ogre::RenderSysAllocatedObject
typedef CategorisedAllocPolicy< Ogre::MEMCATEGORY_RENDERSYS >	Ogre::RenderSysAllocPolicy
typedef ResourceAllocatedObject	Ogre::ResourceAlloc
typedef AllocatedObject< ResourceAllocPolicy >	Ogre::ResourceAllocatedObject
typedef CategorisedAllocPolicy< Ogre::MEMCATEGORY_RESOURCE >	Ogre::ResourceAllocPolicy
typedef AllocatedObject< ResourceSimdAllocPolicy >	Ogre::ResourceSimdAllocObject
typedef CategorisedAlignAllocPolicy< Ogre::MEMCATEGORY_RESOURCE >	Ogre::ResourceSimdAllocPolicy
typedef GeneralAllocatedObject	Ogre::RootAlloc
typedef AllocatedObject< SceneCtlAlignPolicy >	Ogre::SceneCtlAlignedObject
typedef CategorisedAlignAllocPolicy< Ogre::MEMCATEGORY_SCENE_CONTROL >	Ogre::SceneCtlAlignPolicy
typedef AllocatedObject< SceneCtlAllocPolicy >	Ogre::SceneCtlAllocatedObject
typedef CategorisedAllocPolicy< Ogre::MEMCATEGORY_SCENE_CONTROL >	Ogre::SceneCtlAllocPolicy
typedef SceneCtlAlignedObject	Ogre::SceneMgtAlignedAlloc
typedef SceneCtlAllocatedObject	Ogre::SceneMgtAlloc
typedef AllocatedObject< SceneObjAllocPolicy >	Ogre::SceneObjAllocatedObject
typedef CategorisedAllocPolicy< Ogre::MEMCATEGORY_SCENE_OBJECTS >	Ogre::SceneObjAllocPolicy
typedef ScriptingAllocatedObject	Ogre::ScriptCompilerAlloc
typedef AllocatedObject< ScriptingAllocPolicy >	Ogre::ScriptingAllocatedObject
typedef CategorisedAllocPolicy< Ogre::MEMCATEGORY_SCRIPTING >	Ogre::ScriptingAllocPolicy
typedef ScriptingAllocatedObject	Ogre::ScriptTranslatorAlloc
typedef GeneralAllocatedObject	Ogre::SerializerAlloc
typedef SceneCtlAllocatedObject	Ogre::ShadowDataAlloc
typedef GeometryAllocatedObject	Ogre::StagingBufferAlloc
typedef GeneralAllocatedObject	Ogre::StereoDriverAlloc
typedef GeneralAllocatedObject	Ogre::StreamAlloc
typedef SceneObjAllocatedObject	Ogre::SubEntityAlloc
typedef ResourceAllocatedObject	Ogre::SubMeshAlloc
typedef ResourceAllocatedObject	Ogre::TechniqueAlloc
typedef ResourceAllocatedObject	Ogre::TextureUnitStateAlloc
typedef GeneralAllocatedObject	Ogre::TimerAlloc
typedef GeneralAllocatedObject	Ogre::UtilityAlloc
typedef GeometryAllocatedObject	Ogre::VertexArrayObjectAlloc
typedef GeometryAllocatedObject	Ogre::VertexDataAlloc
typedef RenderSysAllocatedObject	Ogre::ViewportAlloc

Enumerations
enum	Ogre::MemoryCategory {   Ogre::MEMCATEGORY_GENERAL = 0 , Ogre::MEMCATEGORY_GEOMETRY = 1 , Ogre::MEMCATEGORY_ANIMATION = 2 , Ogre::MEMCATEGORY_SCENE_CONTROL = 3 ,   Ogre::MEMCATEGORY_SCENE_OBJECTS = 4 , Ogre::MEMCATEGORY_RESOURCE = 5 , Ogre::MEMCATEGORY_SCRIPTING = 6 , Ogre::MEMCATEGORY_RENDERSYS = 7 ,   Ogre::MEMCATEGORY_COUNT = 8 }
	A set of categories that indicate the purpose of a chunk of memory being allocated. More...

Functions
template<typename T >
T *	Ogre::constructN (T *basePtr, size_t count)
	Utility function for constructing an array of objects with placement new, without using new[] (which allocates an undocumented amount of extra memory and so isn't appropriate for custom allocators).
template<typename T >
void	Ogre::deletePtr (T *ptr)
	Function which invokes OGRE_DELETE on a given pointer.

Detailed Description

This file configures Ogre's memory allocators.

You can modify this file to alter the allocation routines used for Ogre's main objects.

When customising memory allocation, all you need to do is provide one or more custom allocation policy classes. These classes need to implement:

// Allocate bytes - file/line/func information should be optional, 
// will be provided when available but not everywhere (e.g. release mode, STL allocations)
static inline void* allocateBytes(size_t count, const char* file = 0, int line = 0, const char* func = 0);
// Free bytes
static inline void deallocateBytes(void* ptr);
// Return the max number of bytes available to be allocated in a single allocation
static inline size_t getMaxAllocationSize();

Policies are then used as implementations for the wrapper classes and macros which call them. AllocatedObject for example provides the hooks to override the new and delete operators for a class and redirect the functionality to the policy. STLAllocator is a class which is provided to STL containers in order to hook up allocation of the containers members to the allocation policy.

In addition to linking allocations to policies, this class also defines a number of macros to allow debugging information to be passed along with allocations, such as the file and line number they originate from. It's important to realise that we do not redefine the 'new' and 'delete' symbols with macros, because that's very difficult to consistently do when other libraries are also trying to do the same thing; instead we use dedicated 'OGRE_' prefixed macros. See OGRE_NEW and related items.

The base macros you can use are listed below, in order of preference and with their conditions stated:

• OGRE_NEW - use to allocate an object which have custom new/delete operators to handle custom allocations, usually this means it's derived from Ogre::AllocatedObject. Free the memory using OGRE_DELETE. You can in fact use the regular new/delete for these classes but you won't get any line number debugging if you do. The memory category is automatically derived for these classes; for all other allocations you have to specify it.
• OGRE_NEW_T - use to allocate a single class / struct that does not have custom new/delete operators, either because it is non-virtual (Vector3, Quaternion), or because it is from an external library (e.g. STL). You must deallocate with OGRE_DELETE_T if you expect the destructor to be called. You may free the memory using OGRE_FREE if you are absolutely sure there is no destructor to be called. These macros ensure that constructors and destructors are called correctly even though the memory originates externally (via placement new). Also note that you have to specify the type and memory category so that the correct allocator can be derived, when both allocating and freeing.
• OGRE_NEW_ARRAY_T - as OGRE_NEW_T except with an extra parameter to construct multiple instances in contiguous memory. Again constructors and destructors are called. Free with OGRE_DELETE_ARRAY_T.
• OGRE_ALLOC_T - use to allocate a set of primitive types conveniently with type safety. This can also be used for classes and structs but it is imperative that you understand that neither the constructor nor the destructor will be called. Sometimes you want this because it's more efficient just to grab/free a chunk of memory without having to iterate over each element constructing / destructing. Free the memory with OGRE_FREE.
• OGRE_MALLOC - the most raw form of allocation, just a set of bytes. Use OGRE_FREE to release.
• _SIMD and _ALIGN variants - all of the above have variations which allow aligned memory allocations. The _SIMD versions align automatically to the SIMD requirements of your platform, the _ALIGN variants allow user-defined alignment to be specified.

Here are some examples:

 
AllocatedClass* obj = OGRE_NEW AllocatedClass();
OGRE_DELETE obj;
AllocatedClass* array = OGRE_NEW AllocatedClass[10];
OGRE_DELETE [] obj;
ExternalClass* obj = OGRE_NEW_T(ExternalClass, MEMCATEGORY_GENERAL)(constructorArgs);
OGRE_DELETE_T(obj, ExternalClass, MEMCATEGORY_GENERAL);
ExternalClass* obj = OGRE_NEW_ARRAY_T(ExternalClass, 10, MEMCATEGORY_GENERAL);
OGRE_DELETE_ARRAY_T(obj, NonVirtualClass, 10, MEMCATEGORY_GENERAL);
long* pLong = OGRE_ALLOC_T(long, 10, MEMCATEGORY_GENERAL);
OGRE_FREE(pLong, MEMCATEGORY_GENERAL);
long* pLong = OGRE_NEW_T(long, MEMCATEGORY_GENERAL)(0);
OGRE_FREE(pLong, MEMCATEGORY_GENERAL);
void* pVoid = OGRE_MALLOC(1024, MEMCATEGORY_GENERAL);
OGRE_FREE(pVoid, MEMCATEGORY_GENERAL);

OGRE_ALLOC_T is also the route to go for allocating real primitive types like int & float. You free the memory using OGRE_FREE, and both variants have SIMD and custom alignment variants.