rso_interface_1.h

Go to the documentation of this file.

/*! \file
  \brief  Defines the RSO interface, which provides a generic way of accessing RSOs and other content, disti::RSOInterface1.
 
  \par Copyright Information
 
  Copyright (c) 2017 by The DiSTI Corporation.<br>
  11301 Corporate Blvd; Suite 100<br>
  Orlando, Florida 32817<br>
  USA<br>
  <br>
  All rights reserved.<br>
 
  This Software contains proprietary trade secrets of DiSTI and may not be
reproduced, in whole or part, in any form, or by any means of electronic,
mechanical, or otherwise, without the written permission of DiSTI.  Said
permission may be derived through the purchase of applicable DiSTI product
licenses which detail the distribution rights of this content and any
Derivative Works based on this or other copyrighted DiSTI Software.
 
  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.
 
  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES.  DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
EXCEED FIVE DOLLARS (US$5.00).
 
  The aforementioned terms and restrictions are governed by the laws of the
State of Florida and the United States of America.
 
*/
#ifndef _RSO_INTERFACE_1_H
#define _RSO_INTERFACE_1_H
 
// !!! NOTICE !!!
// To maintain compatibility with existing RSOs this header cannot be changed.
 
namespace disti
{
////////////////////////////////////////////////////////////////////////////////
// In order for the RSO to be discovered in a .DLL or .so file,
// The following "C" funtions need to be defined.
// They are only comments here.
////////////////////////////////////////////////////////////////////////////////
// RSOInterface1* GetRSOInterface1_ClassNameHere()
// Optionally:
// const char* GlsDefaultClassName()
////////////////////////////////////////////////////////////////////////////////
 
/** The RSOInterface1 class defines an abstract interface to an RSO instance. 
  */
class RSOInterface1
{
public:
    ////////////////////////////////////////////////////////////////////////////////
    // Forward declaration of support classes
    ////////////////////////////////////////////////////////////////////////////////
    class Vector;
    class MatrixD;
    class OpenGLMatrices;
    class PlaneClass;
    class Culler;
    class Event;
    class LocationEvent;
    class MouseEvent;
    class KeyboardEvent;
    class ObjectEvent;
    class EmittedEventHandler;
    class ResourceFilter;
 
public:
    ////////////////////////////////////////////////////////////////////////////////
    /// The RSO Interface methods
    ////////////////////////////////////////////////////////////////////////////////
 
    /// Perform component simulation.
    /// Any non-drawing activities can be performed here.
    /// Call this before PreDraw()
    /// \param time The current application time in seconds.
    virtual void Calculate( double time ) = 0;
 
    /// Calculate transformations and perform culling
    /// Call this before Draw()
    /// \param current The current state of the OpenGL matrices.
    /// \param culler The current culler state.
    virtual void PreDraw( const OpenGLMatrices& current, Culler& culler ) = 0;
 
    /// Draw the object via OpenGL
    /// Call this after PreDraw()
    virtual void Draw() = 0;
 
    /// Set the string value for a given named resource.
    /// \param resourceName The name of the resource to set.
    /// \param resourceVal The new string value to set for the resource.
    virtual void SetResource( const char* resourceName, const char* resourceVal ) = 0;
 
    /// Get the string value for the given resource
    /// \param resourceName The name of the resource whose value is to be returned.
    /// \return The string value for the given resource, or empty string if not found.
    virtual const char* GetResource( const char* resourceName ) = 0;
 
    /// Get a list of the resources for the component.
    /// Each resource is separated by a newline ('\n') with the output controlled by filter.
    /// filter may be NULL in which case the default values are used.
    /// \param filter The filter parameters to use.
    /// \return A string containing the list of resource data that passes the filter.
    virtual const char* GetResources( ResourceFilter* filter = 0 ) = 0;
 
    /// Allow the object to handle an event
    /// \param ev The event to handle.
    /// \return True if the event was handled by the component.
    virtual bool HandleInput( Event* ev ) = 0;
 
    /// Allow for handling events from inside the object.
    /// The emitted event handler will be passed events that are from inside the component
    /// \param handler pointer to the EmittedEventHandler object to use or NULL to remove the current event handler.
    /// \return true if this component may emit events, false if this component will never emit events.
    virtual bool SetEmittedEventHandler( EmittedEventHandler* handler ) = 0;
 
    /// Pick3D returns true if the RSO was picked.
    /// \param winLoc          Device coordinates for the mouse click.  Z value should be set to 0 to ensure pick ray starts at near clip plane.
    /// \param logicalCoords   The start of the pick ray in logical coordinates.  Should be calculated from the winLoc using this->WindowToLogical(winLoc, logicalCoords, &directionVector).
    /// \param scale           Current window scale. Affects picking radius of outlines.  Initial value should typically be 1.0.
    /// \param directionVector The direction of the pick ray in logical coordinates.  Should be calculated from the winLoc using this->WindowToLogical(winLoc, logicalCoords, &directionVector).
    /// \param collisionWinLoc  Returns where the pick vector intersects the object that is hit in device coordinates.
    /// \param drawnMatrices   The matrices used to draw the object, including matrices set by parents that may have
    ///                        dynamically rotated, translated or scaled this object.  Initial value should typically be a default OpenGLMatrices() object.
    /// \return True if the object was picked.
    virtual bool Pick3D( const Vector& winLoc,
        const Vector&                  logicalCoords,
        float                          scale,
        const Vector&                  directionVector,
        Vector&                        collisionWinLoc,
        const OpenGLMatrices&          drawnMatrices )
        = 0;
 
    /// Get the bounding sphere for the component in the components coordinate system
    /// \param center If the method returns true, contains the center point of the sphere. If the method returns false, value is undefined.
    /// \param radius If the method returns true, contains the radius of the sphere. If the method returns false, value is undefined.
    /// \returns true if the bounding sphere was returned, false if the bounding sphere is not available.
    virtual bool GetBoundingSphere( Vector* center, float* radius ) = 0;
 
    /// Get the extents of the component when drawn with the given transformation matrix, as a coordinate system-aligned box
    /// \param min If the method returns true, contains the point corresponding with the 1st corner of the box.  If the method returns false, value is undefined.
    /// \param max If the method returns true, contains the point corresponding with the 2nd corner of the box.  If the method returns false, value is undefined.
    /// \param transform Transformation matrix from A to B where A is the component's coordinate system and B is the coordinate system to compute the bounding box in. (If NULL then identity matrix is assumed)
    /// \returns true if the extents were calculated, false if the extents could not be calculated.
    virtual bool GetBoundingBox( Vector* min, Vector* max, const MatrixD* transform = 0 ) = 0;
 
    /// \return A new instance of the RSO that is a clone of this object or NULL if not possible.
    virtual RSOInterface1* CloneObject() = 0;
 
    /// Safely delete the object.
    virtual void DeleteInstance() = 0;
 
protected:
    /// Protected destructor so it can't be deleted directly.
    virtual ~RSOInterface1() {}
 
public:
    ////////////////////////////////////////////////////////////////////////////////
    // Supporting classes
    ////////////////////////////////////////////////////////////////////////////////
 
    /** Vector */
    class Vector
    {
    public:
        float _x; ///< The X component.
        float _y; ///< The Y component.
        float _z; ///< The Z component.
 
        Vector()
            : _x( 0 )
            , _y( 0 )
            , _z( 0 )
        {}
 
        /// Set all three components.
        /// \param x The new X component to set.
        /// \param y The new Y component to set.
        /// \param z The new Z component to set.
        inline void Set( float x, float y, float z )
        {
            _x = x;
            _y = y;
            _z = z;
        }
 
        /// \return The X component.
        inline float X() { return _x; }
 
        /// \return The Y component.
        inline float Y() { return _y; }
 
        /// \return The Z component.
        inline float Z() { return _z; }
    };
 
    /** MatrixD contains the data for a 4x4 matrix */
    class MatrixD
    {
    public:
        double _data[ 4 * 4 ]; ///< Raw column-major matrix data.
 
        // Uninitialized data
        MatrixD()
        {}
 
        /// Constructor
        /// \param data A double array to copy from.
        MatrixD( double* data )
        {
            _data[ 0 ]  = data[ 0 ];
            _data[ 1 ]  = data[ 1 ];
            _data[ 2 ]  = data[ 2 ];
            _data[ 3 ]  = data[ 3 ];
            _data[ 4 ]  = data[ 4 ];
            _data[ 5 ]  = data[ 5 ];
            _data[ 6 ]  = data[ 6 ];
            _data[ 7 ]  = data[ 7 ];
            _data[ 8 ]  = data[ 8 ];
            _data[ 9 ]  = data[ 9 ];
            _data[ 10 ] = data[ 10 ];
            _data[ 11 ] = data[ 11 ];
            _data[ 12 ] = data[ 12 ];
            _data[ 13 ] = data[ 13 ];
            _data[ 14 ] = data[ 14 ];
            _data[ 15 ] = data[ 15 ];
        }
    };
 
    /** OpenGLMatrices is used to pass the current OpenGL matrices to PreDraw */
    class OpenGLMatrices
    {
    public:
        int*     _viewPort;    ///< Pointer to viewport array size 4.
        MatrixD* _projMatrix;  ///< The projection matrix.
        MatrixD* _modelMatrix; ///< The modelview matrix.
 
        OpenGLMatrices()
            : _viewPort( 0 )
            , _projMatrix( 0 )
            , _modelMatrix( 0 )
        {}
 
        /// Constructor
        /// \param viewPort The new viewport array.
        /// \param projMatrix The new projection matrix.
        /// \param modelMatrix The new modelview matrix.
        OpenGLMatrices( int* viewPort, MatrixD* projMatrix, MatrixD* modelMatrix )
            : _viewPort( viewPort )
            , _projMatrix( projMatrix )
            , _modelMatrix( modelMatrix )
        {}
    };
 
    /** The PlaneClass is used to define the clipping planes for culling */
    class PlaneClass
    {
    public:
        float _a; ///< Coefficient to describe a 3D plane: aX + bY + cZ + d = 0
        float _b; ///< Coefficient to describe a 3D plane: aX + bY + cZ + d = 0
        float _c; ///< Coefficient to describe a 3D plane: aX + bY + cZ + d = 0
        float _d; ///< Coefficient to describe a 3D plane: aX + bY + cZ + d = 0
 
        PlaneClass()
            : _a( 0 )
            , _b( 0 )
            , _c( 0 )
            , _d( 0 )
        {}
 
        /// Set all components.
        /// \param a The A component to set.
        /// \param b The B component to set.
        /// \param c The C component to set.
        /// \param d The D component to set.
        inline void Set( float a, float b, float c, float d )
        {
            _a = a;
            _b = b;
            _c = c;
            _d = d;
        }
 
        /// \return The A component.
        inline float A() { return _a; }
 
        /// \return The B component.
        inline float B() { return _b; }
 
        /// \return The C component.
        inline float C() { return _c; }
 
        /// \return The D component.
        inline float D() { return _d; }
    };
 
    /** Defines culling parameters for PreDraw */
    class Culler
    {
    public:
        bool       _enabled;     ///< Whether or not culling is enabled.
        PlaneClass _planes[ 6 ]; ///< Array of six clipping planes to define the frustum.
 
        Culler()
            : _enabled( false )
        {}
    };
 
    /** Base class for events */
    class Event
    {
    public:
        /** Event Type Enum */
        typedef enum
        {
            EVENT_MOUSE = 0,  /**< A Mouse (or touch screen) event */
            EVENT_KEYBOARD,   /**< A Keyboard event */
            EVENT_TIMER,      /**< Unused */
            EVENT_OBJECT,     /**< An event emitted by an object */
            EVENT_KEYBOARD_UP /**< A Keyboard up event (uses KeyboardEvent class) */
        } EventTypeEnum;
 
        /** Event Subtype Enum */
        typedef enum
        {
            MOUSE_DOWN = 0,    /**< A Mouse button was pushed down */
            MOUSE_UP,          /**< A Mouse button was released */
            MOUSE_MOVE,        /**< The mouse moved */
            MOUSE_DRAG,        /**< The mouse moved while a button was held down */
            MOUSE_LEAVE,       /**< The mouse exited the object */
            MOUSE_ENTER,       /**< The mouse entered the object */
            MOUSE_WHEEL_MINUS, /**< The mouse wheel was turned in the negative direction */
            MOUSE_WHEEL_PLUS   /**< The mouse wheel was turned in the positive direction */
        } EventSubtypeEnum;
 
        unsigned short _eventType;    /**< Major event code. see EventTypeEnum */
        unsigned short _eventSubtype; /**< Minor event code. see EventSubtypeEnum */
 
        /**
            Special Key State
        */
        typedef enum
        {
            NONE_STATE        = 0,
            SHIFT_STATE       = 0x00010000,
            CAPS_LOCK_STATE   = 0x00020000,
            CTRL_STATE        = 0x00040000,
            ALT_STATE         = 0x00080000,
            NUM_LOCK_STATE    = 0x00100000,
            META_STATE        = 0x00400000,
            SCROLL_LOCK_STATE = 0x00800000,
            BUTTON1_STATE     = 0x01000000,
            BUTTON2_STATE     = 0x02000000,
            BUTTON3_STATE     = 0x04000000
        } SpecialKeyState;
 
        Event()
            : _eventType( 0 )
            , // Derived classes MUST set the appropriate event type
            _eventSubtype( MOUSE_DOWN )
        {}
 
        virtual ~Event() {}
 
        /// \return The type of this event.
        inline unsigned short EventType() { return _eventType; }
 
        /// Set the primary type of this event. i.e. EVENT_MOUSE
        /// \param value The new primary type to set.
        inline void EventType( unsigned short value ) { _eventType = value; }
 
        /// \return The subtype of this event.
        inline unsigned short EventSubType() { return _eventSubtype; }
 
        /// Set the secondary type of this event. i.e. MOUSE_DOWN
        /// \param value The new secondary type to set.
        inline void EventSubType( unsigned short value ) { _eventSubtype = value; }
    };
 
    /** An event associated with a specific location in the application window.
      * Base class for MouseEvent and KeyboardEvent.
      */
    class LocationEvent : public Event
    {
    public:
        Vector _winLoc; /**< Location of the event in window coordinates
                                * x and y window coordinates in pixels.  
                                * z is from 0.0 -> 1.0 and represents the depth.  
                                * z == 0 is at the near cliping plane.
                                * z == 0.5 represents half way between near
                                * and far cliping planes. 
                                */
        LocationEvent()
        {}
 
        /// \return The window coordinates of the this event.
        inline Vector WinLoc() { return _winLoc; }
 
        /// Sets the window coordinates of this event.
        /// \param value The new window coordinates to set.
        inline void WinLoc( Vector value ) { _winLoc = value; }
    };
 
    /** An event containing mouse input. */
    class MouseEvent : public LocationEvent
    {
    public:
        /** Mouse Button Type */
        typedef enum
        {
            MOUSE_LBUTTON    = 1, /**< Mask that matches only left mouse button */
            MOUSE_MBUTTON    = 2, /**< Mask that matches only middle mouse button */
            MOUSE_RBUTTON    = 4, /**< Mask that matches only right mouse button */
            MOUSE_BUTTON_ANY = 7  /**< Mask that matches any mouse button */
        } MouseButtonType;
 
        unsigned char _buttonMask; /**< bitfield: which button was pressed for this event ( MouseButtonType )*/
        unsigned char _clicks;     /**< # of times a button was pressed */
        int           _modifiers;  /**< bitfield: which buttons or modifiers were depressed before event ( \sa SpecialKeyState) */
 
        MouseEvent()
            : _buttonMask( 0 )
            , _clicks( 0 )
            , _modifiers( NONE_STATE )
        {
            _eventType = EVENT_MOUSE;
        }
 
        /// \return The current button mask of this event.
        inline unsigned char ButtonMask() { return _buttonMask; }
 
        /// Set the button mask for this event. i.e. Which buttons are down.
        /// \param value The new button mask to set.
        inline void ButtonMask( unsigned char value ) { _buttonMask = value; }
 
        /// \return The number of clicks associated with this event.
        inline unsigned char Clicks() { return _clicks; }
 
        /// Set the number of clicks associated with this event. i.e. single or double click
        /// \param value The new number of clicks to set
        inline void Clicks( unsigned char value ) { _clicks = value; }
 
        /// \return The current keyboard modifers of this event.
        inline int Modifiers() { return _modifiers; }
 
        /// Set the keyboard modifers for this event. e.g. control being held.
        /// \param value The new keyboard modifers to set.
        inline void Modifiers( int value ) { _modifiers = value; }
    };
 
    /** An event containing keyboard input */
    class KeyboardEvent : public LocationEvent
    {
    public:
        ///< \details The KeySymCodeEnum enumeration. Used by keysym (use ascii letters for all other keys):
        enum
        {
            KEY_Button      = 0xfee8,
            KEY_BackSpace   = 0xff08,
            KEY_Tab         = 0xff09,
            KEY_Enter       = 0xff0d,
            KEY_Pause       = 0xff13,
            KEY_Scroll_Lock = 0xff14,
            KEY_Escape      = 0xff1b,
            KEY_Home        = 0xff50,
            KEY_Left        = 0xff51,
            KEY_Up          = 0xff52,
            KEY_Right       = 0xff53,
            KEY_Down        = 0xff54,
            KEY_Page_Up     = 0xff55,
            KEY_Page_Down   = 0xff56,
            KEY_End         = 0xff57,
            KEY_Print       = 0xff61,
            KEY_Insert      = 0xff63,
            KEY_Menu        = 0xff67,
            KEY_Num_Lock    = 0xff7f,
            KEY_KP          = 0xff80,
            KEY_KP_Enter    = 0xff8d,
            KEY_KP_Last     = 0xffbd,
            KEY_F           = 0xffbd,
            KEY_F_Last      = 0xffe0,
            KEY_Shift_L     = 0xffe1,
            KEY_Shift_R     = 0xffe2,
            KEY_Control_L   = 0xffe3,
            KEY_Control_R   = 0xffe4,
            KEY_Caps_Lock   = 0xffe5,
            KEY_Meta_L      = 0xffe7,
            KEY_Meta_R      = 0xffe8,
            KEY_Alt_L       = 0xffe9,
            KEY_Alt_R       = 0xffea,
            KEY_Delete      = 0xffff
        } KeySymCodeEnum;
 
        int _keysym;    /**< Code for key that was pressed ( \sa KeySymCodeEnum) */
        int _modifiers; /**< bitfield: which modifiers or buttons were pressed ( \sa SpecialKeyState) */
 
        KeyboardEvent()
            : _keysym( 0 )
            , _modifiers( 0 )
        {
            _eventType = EVENT_KEYBOARD;
        }
 
        /// \return The key symbol code for this event.
        inline int KeySym() { return _keysym; }
 
        /// Set the key symbol associated with this event.
        /// \param value The new symbol to set.
        inline void KeySym( int value ) { _keysym = value; }
 
        /// \return The current keyboard modifiers for this event.
        inline int Modifiers() { return _modifiers; }
 
        /// Set the keyboard modifiers for this event, e.g. shift is held.
        /// \param value The new modifiers to set.
        inline void Modifiers( int value ) { _modifiers = value; }
    };
 
    /** An event that is emitted from a simulation object */
    class ObjectEvent : public Event
    {
    public:
        char* _initiator; /**< The qualified name of the object that initiated the event */
        char* _eventName; /**< String event name */
        char* _eventData; /**< Any additional data for this event.  A NULL terminated string */
 
        ObjectEvent()
            : _initiator( 0 )
            , _eventName( 0 )
            , _eventData( 0 )
        {
            _eventType = EVENT_OBJECT;
        }
 
        virtual ~ObjectEvent()
        {
            if( _initiator )
            {
                delete _initiator;
                _initiator = 0;
            }
            if( _eventName )
            {
                delete _eventName;
                _eventName = 0;
            }
            if( _eventData )
            {
                delete _eventData;
                _eventData = 0;
            }
        }
 
        /// \return The initiator name.
        inline const char* Initiator() const
        {
            return _initiator;
        }
 
        /// Set the initiator name.
        /// \param value The new name to set.
        virtual void Initiator( const char* value )
        {
            if( _initiator )
            {
                delete[] _initiator;
                _initiator = 0;
            }
            if( value )
            {
                _initiator = new char[ RSOInterface1::strlen( value ) + 1 ];
                RSOInterface1::strcpy( _initiator, value );
            }
        }
 
        /// \return The event name.
        inline const char* EventName() const
        {
            return _eventName;
        }
 
        /// Set the event name.
        /// \param value The new name to set.
        virtual void EventName( const char* value )
        {
            if( _eventName )
            {
                delete[] _eventName;
                _eventName = 0;
            }
            if( value )
            {
                _eventName = new char[ RSOInterface1::strlen( value ) + 1 ];
                RSOInterface1::strcpy( _eventName, value );
            }
        }
 
        /// \return The event data.
        inline const char* EventData() const
        {
            return _eventData;
        }
 
        /// Set the event data.
        /// \param value The new string data to set.
        virtual void EventData( const char* value )
        {
            if( _eventData )
            {
                delete[] _eventData;
                _eventData = 0;
            }
            if( value )
            {
                _eventData = new char[ RSOInterface1::strlen( value ) + 1 ];
                RSOInterface1::strcpy( _eventData, value );
            }
        }
    };
 
    /** The emitted event handler is an object provided by the 
        container to handle events emitted from the component.
    */
    class EmittedEventHandler
    {
    protected:
        virtual ~EmittedEventHandler() {}
 
    public:
        /// Called by the component to pass an event
        /// to the container. Most containers will only handle ObjectEvents.
        /// \param ev The event to handle
        /// \return int Reserved. Currently always -1.
        virtual int HandleEvent( Event* ev ) = 0;
    };
 
    /** The resource filter is a parameter to the GetResources method */
    class ResourceFilter
    {
    protected:
        virtual ~ResourceFilter() {}
 
    public:
        /// \return The levels of qualification to show in the name.
        virtual int LevelsUp() const = 0;
 
        /// How many levels of qualification to show in the name.
        /// -1 means full qualification.
        /// Default: -1
        /// \param value The new levels of qualification to show.
        virtual void LevelsUp( int value ) = 0;
 
        /// \return The number of levels of children to show.
        virtual int GroupLevelsDown() const = 0;
 
        /// How many levels of children to show.
        ///  0 means don't show any children properties
        /// -1 means all the way down.
        /// Default: -1
        /// \param value The new levels of children to show.
        virtual void GroupLevelsDown( int value ) = 0;
 
        /// \return True if only a list of names will be returned.
        virtual bool NamesOnly() const = 0;
 
        /// If true, only a list of names will be returned.
        /// Values will not be returned.
        /// The format changes to not include the ":".
        /// Default: false
        /// \param value The new names only flag.
        virtual void NamesOnly( bool value ) = 0;
 
        /// Manage the list of excluded attributes.
        /// \param str The name of the new exclude item to add.
        virtual void AddExclude( const char* str ) = 0;
 
        /// \return The number of entries in the exclude list.
        /// Default: 0
        virtual int ExcludeCount() const = 0;
 
        /// Returns NULL if index >= ExcludeCount() or index < -1
        /// \param index The index of the exlcusion item to return.
        /// \return The name of the item associated with the index.
        virtual const char* GetExclude( int index ) const = 0;
 
        /// Manage the list of included attributes.
        /// \param str The name of the new include item to add.
        virtual void AddInclude( const char* str ) = 0;
 
        /// \return The number of entries in the include list.
        /// Default: 0
        virtual int IncludeCount() const = 0;
 
        /// Returns NULL if index >= IncludeCount() or index < -1.
        /// \param index The index of the inclusion item to return.
        /// \return The name of the item associated with the index.
        virtual const char* GetInclude( int index ) const = 0;
 
        /// Check a name against the filters.
        /// Exclude list takes precedence.
        /// \param name The name to check against the filter.
        /// \return True if the name passes the filter (to be included in the result).
        virtual bool PassFilter( const char* name ) const = 0;
    };
 
    ////////////////////////////////////////////////////////////////////////////////
    // Support class utility methods
    ////////////////////////////////////////////////////////////////////////////////
 
    /// Return the length of the given C string.
    /// \param str The string whose length is to be computed.
    /// \return The length of the string in bytes.
    static inline unsigned int strlen( const char* str )
    {
        unsigned int i = 0;
        while( str[ i ] != '\0' )
        {
            i++;
        }
        return i;
    }
 
    /// Copy the given C string from src to dest.
    /// \param dest The destination memory region.
    /// \param src The source memory region.
    /// \return The destination memory region.
    static inline char* strcpy( char* dest, const char* src )
    {
        unsigned int i = 0;
        while( ( dest[ i ] = src[ i ] ) != '\0' )
        {
            i++;
        }
        return dest;
    }
};
 
} // end namespace disti
 
#endif