Main Page Modules Namespace List Class Hierarchy Alphabetical List Compound List File List Namespace Members Compound Members File Members Related Pages

# deApi.hpp

Go to the documentation of this file.

    00001 ///////////////////////////////////////////////////////////////////////////////
    00002 /// @file deApi.hpp
    00003 ///
    00004 /// @brief DestinyEdit API
    00005 ///
    00006 /// @author jwvanderbeck
    00007 ///
    00008 /// This file is the intellectual property of Novus Delta, LLC.. Usage of the
    00009 /// contents of this file is subject to the Destiny3D Member License which
    00010 /// can be found at http://www.destiny3d.com.  Any other usage is prohibited.
    00011 ///
    00012 /// This file is distributed "AS IS" without warranty of any kind.  Novus
    00013 /// Delta, LLC. does not guarantee the fitness of the contents of this file
    00014 /// for any particular purpose.
    00015 ///
    00016 /// Copyright (C) 2001-2003 Novus Delta, LLC. All Rights Reserved.
    00017 ///
    00018 /// <hr>
    00019 ///                                 Change History
    00020 /// <hr>
    00021 ///
    00022 /// @date Mar 2003
    00023 /// @author jwvanderbeck
    00024 /// @remarks Creation
    00025 ///
    00026 ///////////////////////////////////////////////////////////////////////////////
    00027
    00028 #define USING_DESTINY3D
    00029 #define DESTINY3D_STATIC_LINK
    00030 #define DEAPI_VERSION 50
    00031
    00032 #include "deGlobalTypes.hpp"
    00033 #include "deFileSystem.hpp"
    00034 #include "deArray.hpp"
    00035 #include "deString.hpp"
    00036 #include "deList.hpp"
    00037 #include "deRender.hpp"
    00038 #include "deCamera.hpp"
    00039 #include "deScene.hpp"
    00040 #include "deDriver.hpp"
    00041 #include "de2D.hpp"
    00042 #include "deBitmap.hpp"
    00043 #include "deBrush.hpp"
    00044
    00045
    00046 #ifdef DEAPI_EXPORT
    00047 #define DEAPI DEDLL_EXPORT
    00048 #else
    00049 #define DEAPI DEDLL_IMPORT
    00050 #pragma comment(lib,"deApi")
    00051 #endif
    00052
    00053 #ifdef WIN32
    00054 #include "windows.h"
    00055 #endif
    00056
    00057 //
    00058 // Forward Defines
    00059 //
    00060 class deApi;
    00061 //
    00062 // Api Types
    00063 class deApiTypes;
    00064 //
    00065 // Api Object Handles
    00066 class deApiHandle;
    00067 //
    00068 // Api Objects
    00069 class deApiObject;
    00070 class deApiNode;
    00071 class deApiNodeTree;
    00072 class deApiAttribute;
    00073 class deApiAttribute_Float;
    00074 class deApiAttributeCollection;
    00075 class deApiStaticBrush;
    00076 class deApiOutputWindow;
    00077 class deApiRender;
    00078 class deApiCamera;
    00079 class deApiViewport;
    00080 class deApiViewportLayout;
    00081 //
    00082 // Function Sets
    00083 class deApiFn_Attribute;
    00084 class deApiFn_OutputWindow;
    00085 class deApiFn_NodeTree;
    00086 class deApiFn_Render;
    00087 class deApiFn_Camera;
    00088 class deApiFn_Viewport;
    00089 class deApiFn_ViewportLayout;
    00090
    00091 //
    00092 // deApiType
    00093 //
    00094 // This class provides dynamic runtime type information services for the api
    00095 #define DECLARE_RTI \
    00096     public:\
    00097         static deApiType Type;
    00098
    00099 #define DEFINE_RTI(name,parent)\
    00100     deApiType name::Type(#name, &parent::Type);
    00101 #define DECLARE_RTI_BASE(name)\
    00102     deApiType name::Type(#name, NULL);
    00103
    00104 class DEAPI deApiType
    00105 {
    00106     public:
    00107         deApiType();
    00108         deApiType(const deString& sName, deApiType* pParent);
    00109         virtual ~deApiType();
    00110         deString& GetName();
    00111         deString& GetParentName();
    00112         deString& GetBaseName();
    00113         deApiType* GetParent();
    00114         deApiType* GetBase();
    00115         bool IsA(const deApiType* pType);
    00116         bool IsA(const deString& sType);
    00117         // todo
    00118         // implement downcasting from base to derived
    00119         void* SafeCast(const deApiType* pCastTo);
    00120         void* SafeCast(const deString& sType);
    00121     private:
    00122         deString    m_sName;
    00123         deApiType*  m_pParent;
    00124 };
    00125
    00126 //
    00127 // deApiTypes
    00128 //
    00129 // This class simply defines some enumerated types used elsewhere
    00130 class DEAPI deApiTypes
    00131 {
    00132     public:
    00133         enum StatusCode
    00134         {
    00135             sError = -1000,
    00136             sInvalidFunctionSet,
    00137             sInvalidObjectType,
    00138             sNullObject,
    00139             sInvalidAttributeType,
    00140             sOk = 0,
    00141             sOutOfRange = 65535
    00142         };
    00143 };
    00144
    00145 //
    00146 // Api Object Handles
    00147 //
    00148 // deApiHandle
    00149 //
    00150 // Encapsulates an api object handle, shielding the actual object behind the
    00151 // handle for safety and security
    00152 class DEAPI deApiHandle
    00153 {
    00154     friend class deApiNodeTree;
    00155
    00156     public:
    00157         //
    00158         // Used to query the handle to see if it is useable with a specified function set
    00159 //      bool CanUseApiFnSet(deApiTypes::FunctionSet fnType);
    00160         bool IsA(const deApiType* pType);
    00161         bool IsA(const deString& sType);
    00162         //
    00163         // Does the handle reference a null or invalid api object?
    00164         bool IsNull();
    00165         //
    00166         // Return the underlying object's runtime ID
    00167         unsigned long GetRuntimeID();
    00168         //
    00169         // Destroy the underlying api object referenced by this handle.
    00170         // The object will not be physically destroyed until this and
    00171         // all other outstanding handles are released.  This only flags
    00172         // it for destruction.
    00173         bool Destroy();
    00174         //
    00175         // Overloaded assignment operator
    00176         deApiHandle& operator=(deApiHandle& rhs);
    00177         //
    00178         // Overloaded copy constructor
    00179         deApiHandle(const deApiHandle& rhs);
    00180         //
    00181         // Default constructor
    00182         deApiHandle();
    00183         //
    00184         // Default destructor
    00185         ~deApiHandle();
    00186     private:
    00187         //
    00188         // Used by deApiObjectNodeTree to link the handle to its underlying api object
    00189         void SetRuntimeID(unsigned long runtimeID);
    00190         //
    00191         // Helper function to de-reference underlying object for internal use
    00192         deApiObject* Dereference();
    00193     private:
    00194         //
    00195         // Underlying object's runtime ID. The handle itself does not have a runtime ID
    00196         unsigned long   runtimeID;
    00197         //
    00198         // Is the underlying object invalid?
    00199         bool            bNull;
    00200 };
    00201
    00202
    00203 #ifdef DEAPI_PRIVATE
    00204     #include "../../deApi/deApi_Private.hpp"
    00205 #endif
    00206
    00207 //
    00208 // Function Sets
    00209 //
    00210 //
    00211 // deApiFn_Attribute
    00212 //
    00213 // Function set for working with attribute objects.  Creation and Manipulation.
    00214 class DEAPI deApiFn_Attribute
    00215 {
    00216     public:
    00217         enum DataType
    00218         {
    00219             Invalid = 0,
    00220             Float,
    00221             Int,
    00222             Vector,
    00223             Bool,
    00224             Color_RGB,
    00225             Color_Alpha,
    00226             Color_ARGB,
    00227             UV,
    00228             UVW,
    00229             Transform,
    00230             OutOfRange = 65535
    00231         };
    00232
    00233         deApiFn_Attribute();
    00234         ~deApiFn_Attribute();
    00235
    00236         //
    00237         // Create a new attribute object with the specified parameters
    00238         deApiHandle Create(DataType AttributeType, const deString& sName, const deString& sDescription);
    00239         //
    00240         // Add this attribute to the specified collection
    00241         bool AddToCollection(deApiObject* pCollection);
    00242
    00243     // TODO:
    00244     // Hook this into the handle stuff, and decide whether to split
    00245     // the collections off into a seperate function set or not.  Also make
    00246     // the attribute member object into a generic base class if possible
    00247     private:
    00248         deApiAttribute*             m_pAttribute;
    00249         deApiAttributeCollection*   m_pAttributeCollection;
    00250         DataType                    m_type;
    00251 };
    00252 //
    00253 // deApiFn_OutputWindow
    00254 //
    00255 // Provides functions for manipulating a text output/log window for the editor/api.
    00256 class DEAPI deApiFn_OutputWindow
    00257 {
    00258     public:
    00259         //
    00260         // default constructor
    00261         deApiFn_OutputWindow();
    00262         //
    00263         // default destructor
    00264         ~deApiFn_OutputWindow();
    00265         //
    00266         // Create a new output window
    00267         deApiHandle Create(int x, int y, int width, int height, const deString& title, bool bSizeable=true, bool bCaption=true);
    00268         //
    00269         // Bind function set to an existing handle
    00270         deApiTypes::StatusCode BindHandle(deApiHandle handle);
    00271         //
    00272         // Add text to the output window. This function will add a complete
    00273         // line of text to the output window, and add a carriage return/line feed
    00274         // to the end.
    00275         void AddLogText(const deString& sText);
    00276         //
    00277         // Show or Hide the output window
    00278         void Hide(bool bHide);
    00279         //
    00280         // Save the contents of the window to a text file
    00281         void WriteToFile(const deString& sFileName);
    00282     private:
    00283         deApiOutputWindow*  pOutputWindow;
    00284 };
    00285 //
    00286 // deApiFn_NodeTree
    00287 //
    00288 // Provides functions for manipulating the underlying node tree itself.  The node tree is
    00289 // the lower level tree orginazation where every persistent object is stored.  This
    00290 // tree is also a linkage of operations.  Nodes can be connected together to form a chain
    00291 // of operations, with the output of one feeding into the input of the next.
    00292 class DEAPI deApiFn_NodeTree
    00293 {
    00294     public:
    00295         deApiHandle GetNode(unsigned long iRuntimeID);
    00296       void GetNodes(deTArray<unsigned long>& aReturn, deString& TypeFilter = deString(""), int iMaxCount = -1);
    00297 };
    00298 //
    00299 // deApiFn_Render
    00300 //
    00301 // Encapsulates both the rendering and display subsystems of Destiny3D.
    00302 // Most of this is automated for simple use, though more advanced hooks
    00303 // will probably be provided later on.
    00304 class DEAPI deApiFn_Render
    00305 {
    00306     public:
    00307         void Init(deString& sDriverName);
    00308         void Update(float fTime);
    00309 };
    00310 //
    00311 // deApiFn_Camera
    00312 //
    00313 // Creation and manipulation of cameras
    00314 class DEAPI deApiFn_Camera
    00315 {
    00316     public:
    00317         deApiHandle Create();
    00318         void SetFOV(deDouble dDegrees);
    00319         void SetOrthoWidth(deDouble dWidth);
    00320         void EnableOrtho(bool bEnable);
    00321         deTransform GetTransform();
    00322         void SetTransform(deTransform transform);
    00323         void SetName(const deString sName);
    00324         deString GetName();
    00325         deDouble GetFOV();
    00326         deDouble GetOrthoWidth();
    00327         bool IsOrtho();
    00328         deDouble GetNearClip();
    00329         deDouble GetFarClip();
    00330         void SetClip(deDouble dNear, deDouble dFar);
    00331    private:
    00332       deApiCamera       *m_pCamera;
    00333 };
    00334 //
    00335 // deApiFn_Viewport
    00336 //
    00337 // Creation and manipulation of viewports
    00338 class DEAPI deApiFn_Viewport
    00339 {
    00340     public:
    00341         void Hide(bool bHide);
    00342         void Freeze(bool bFreeze);
    00343         deApiTypes::StatusCode SetCamera(deApiHandle hCamera);
    00344         void SetBGColor(deARGB color);
    00345       void Maximize(bool bMaximized);
    00346       void SetName(const deString& sName);
    00347       deString& GetName();
    00348 };
    00349 //
    00350 // deApiFn_ViewportLayout
    00351 //
    00352 // A "Viewport Layout" defines the layout of the currently displayed viewports.
    00353 // The layout defines how many viewports are visible, the relative width and height of each viewport,
    00354 // the camera attached to each, as well as the name of each.
    00355 // Layouts can be saved, loaded, and edited in realtime by the user.  The viewport layout only defines
    00356 // the layout at the time the layout is applied.  Any characteristic of it can subsequently be changed
    00357 // by the user, and thus its properties should not be assumed.
    00358 //
    00359 // Note: When creating a layout, it is important to make sure you do not leave any window space uncovered
    00360 // by viewports.  In otherwords, the combined width and height of all viewports must be EQUAL to 100%.
    00361 // The results are undefined (read unpredictable), if the combined values are less than or greater than 100%.
    00362 class DEAPI deApiFn_ViewportLayout
    00363 {
    00364    public:
    00365       deApiHandle Create();
    00366       void SetName(const deString& sName);
    00367       deString& GetName();
    00368       void WriteToFile(const deString& sFileName);
    00369       void LoadFromFile(const deString& sFileName);
    00370       void SetViewportCount(int iViewports);
    00371       int GetViewportCount();
    00372       void SetViewportRect(int iViewport, deFloatRect fRect);
    00373       deFloatRect GetViewportRect(int iViewport);
    00374       void SetViewportName(const deString& sName);
    00375       deString& GetViewportName();
    00376       void SetViewportCamera(int iViewport, deApiHandle hCamera);
    00377       deApiHandle GetViewportCamera(int iViewport);
    00378    private:
    00379       deTArray<deFloatRect>      m_arrayViewportRects;
    00380       deTArray<deString>         m_sViewportNames;
    00381 };
    00382
    00383
    00384 //
    00385 // Helper Macros
    00386 #define DEAPI_FAILED(status)(status < 0)
    00387 #define DEAPI_SUCCEEDED(status)(status >= 0)
    00388 #define DEAPI_PASSED(status)(status >= 0)
    00389
    00390 //
    00391 // Stand-Alone API Init
    00392 //
    00393 // This is used only when developing a stand-alone application that uses the API, but is
    00394 // not a plug-in to the editor.  When developing a standard plugin, this must not be used
    00395 extern "C" DEAPI bool deApi_InitStandAlone(HWND hParentWindow);