source: GTP/trunk/App/Games/Jungle_Rumble/src/physic/physics/include/NxUserEntityReport.h @ 1378

#ifndef NX_PHYSICS_NXUSERENTITYREPORT
#define NX_PHYSICS_NXUSERENTITYREPORT
/*----------------------------------------------------------------------------*\
|
|                                               Public Interface to NovodeX Technology
|
|                                                            www.novodex.com
|
\*----------------------------------------------------------------------------*/
/** \addtogroup physics
  @{
*/

#include "Nxp.h"

/**
        \brief The user needs to pass an instance of this class to several of the scene collision
        routines in NxScene.
        
        There are usually two ways to report a variable set of entities
        to the user: using a dynamic array (e.g. an STL vector) or using a callback (called
        for each entity). The first way is fast, but can lead to dynamic allocations and/or
        wasted memory when it would just be possible to handle each entity on-the-fly. The
        second way provides this, but suffers from call overhead. This class combines best
        of both worlds by reporting a small number of entities to the user at the same time,
        via a callback (the onEvent function). This number of entities is user-defined, hence
        it is possible to fallback to the usual array or callback behaviours by adjusting it.
        (Please refer to the comments below for details).

        Returning true lets the SDK continue the collision query, returning false stops it.

        NxUserEntityReport usage:

        A typical collision function will look like this:

        NxU32 someCollisionFunc(NxU32 nbEntities, const Entity** entities, NxUserEntityReport<const Entity*>* callback);

        You have multiple ways to use this:

        1) Using a fixed-size array in your app. This can happen for example when you query
        some entities, and you already have a buffer big enough to handle all of them. In
        that case you don't have to worry about dynamic allocations or callbacks, just do:

        // maxEntities = size of entity buffer
        // entityBuffer = a buffer large enough to contain all entities
        NxU32 nbEntities = someCollisionFunc(maxEntities, entityBuffer, NULL);

        If the buffer is not large enough, the SDK will keep writing entities to the buffer
        until it is full, and then return. You might miss some entities in this case.

        2) Using a callback. This is the default way to use NxUserEntityReport.

        // First define your callback object

        class UserEntityReport : public NxUserEntityReport<Entity*>
                {
                public:

                virtual bool onEvent(NxU32 nbEntities, Entity** entities);
                };

        UserEntityReport myReport;

        // Then later, do the collision calls

        NxU32 nbEntities = someCollisionFunc(0, NULL, &myReport);

        In this case, the SDK will report a limited set of entities at the same time
        (usually 64), through the onEvent() function. The memory used to store
        those entities is internally allocated on the stack.

        3) Using a callback and your own memory buffers. this is the same as the previous
        version, except you can customize the query by specifying both a memory buffer
        and a callback:

        NxU32 nbEntities = someCollisionFunc(maxEntities, myBuffer, &myReport);

        In this case, entities are reported through the onEvent() function as in case 2),
        but those differences apply:

        - the number of entities reported at the same time ("nbEntities" parameter in
        onEvent) is lesser or equal to "maxEntities".

        - the memory used to store the entities ("entities" parameter in onEvent) is the
        same as the user's input buffer ("myBuffer").

        This 3rd way to use NxUserEntityReport is only provided in sake of flexibility,
        but should not be needed in most cases.

         <b>Threading:</b> It is not necessary to make this class thread safe as it will only be called in the context of the
     user thread.

*/

template<class T>
class NxUserEntityReport
        {
        public:

        /**
        \brief This is called to report a number of entities to the user.

        'nbEntities' is the number of returned entities, which are stored in the
        'entities' memory buffer.

        After processing the entities in your application, return true to continue
        the query (in which case onEvent might get called again), or false to end it.

        \param[in] nbEntities The number of returned entities, which are stored in the 'entities' memory buffer.
        \param[in] entities Array of entities.
        \return true to continue processing, false to end processing.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes
        */
        virtual bool onEvent(NxU32 nbEntities, T* entities) = 0;
        };

/** @} */
#endif


//AGCOPYRIGHTBEGIN
///////////////////////////////////////////////////////////////////////////
// Copyright © 2005 AGEIA Technologies.
// All rights reserved. www.ageia.com
///////////////////////////////////////////////////////////////////////////
//AGCOPYRIGHTEND