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

# deRender.hpp

Go to the documentation of this file.

    00001 ///////////////////////////////////////////////////////////////////////////////
    00002 /// @file deRender.hpp
    00003 ///
    00004 /// @brief High-level Rendering interface
    00005 ///
    00006 /// @author Assassin
    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 Feb 2002
    00023 /// @author Assassin
    00024 /// @remarks Initial Creation
    00025 ///
    00026 ///////////////////////////////////////////////////////////////////////////////
    00027
    00028 #ifndef DERENDER_HPP
    00029 #define DERENDER_HPP
    00030
    00031 #include "deGlobalTypes.hpp"
    00032 #include "deDriver.hpp"
    00033 #include "deMath.hpp"
    00034
    00035 #if defined(DERENDER_DLL_EXPORTS) || defined(DESTINY3D_EXPORT_ALL)
    00036 #   define DERENDER_API extern "C" DEDLL_EXPORT
    00037 #elif defined(DESTINY3D_STATIC_LINK)
    00038 #   define DERENDER_API extern "C"
    00039 #else
    00040 #   define DERENDER_API extern "C" DEDLL_IMPORT
    00041 #endif
    00042
    00043 #ifdef USING_DESTINY3D
    00044 #ifdef _DEBUG
    00045 #   ifdef DESTINY3D_STATIC_LINK
    00046 #       pragma comment(lib, "deRender_sd")
    00047 #   else
    00048 #       pragma comment(lib, "deRenderd")
    00049 #   endif //DESTINY3D_STATIC_LINK
    00050 #else
    00051 #   ifdef DESTINY3D_STATIC_LINK
    00052 #       pragma comment(lib, "deRender_s")
    00053 #   else
    00054 #       pragma comment(lib, "deRender")
    00055 #   endif //DESTINY3D_STATIC_LINK
    00056 #endif //_DEBUG
    00057 #endif //USING_DESTINY3D
    00058
    00059
    00060 class IdePortal;
    00061 class IdeCamera;
    00062 class IdeWorld;
    00063 class Ide2DCollection;
    00064 class IdeRender;
    00065 class IdeSurface;
    00066 class IdeVertexBuffer;
    00067 class IdeRenderTexture;
    00068 class IdeRenderMaterial;
    00069 class IdeRenderLight;
    00070 class IdeSceneLight;
    00071 class IdeSurface;
    00072
    00073 // factory functions
    00074 /// initialize the Render system
    00075 DERENDER_API deBoolean IdeRender_Initialize();
    00076 /// get a pointer to an IdeRender singleton.
    00077 DERENDER_API IdeRender* IdeRender_GetPtr();
    00078 /// destroy the IdeRender singleton
    00079 DERENDER_API void IdeRender_Destroy();
    00080 /// release all drivers held by IdeDriver
    00081 DERENDER_API void IdeRender_DestroyDriverLinkages();
    00082
    00083 typedef IdeRender* (*fIdeRender_GetPtr)();
    00084 typedef void (*fIdeRender_Destroy)();
    00085 typedef void (*fIdeRender_DestroyDriverLinkages)();
    00086
    00087 #define DERENDER_MAX_LIGHTS (32)
    00088
    00089 /// Interface to a high-level rendering API.
    00090 /// IdeRender interfaces with the deScene, deDriver, and de2D modules to handle
    00091 /// rendering of 3D scenes with 2D composite overlays.
    00092 /// Related functions: IdeRender_GetPtr.
    00093 //class IdeRender
    00094 DE3D_INTERFACE_(IdeRender)
    00095 {
    00096 protected:
    00097     virtual ~IdeRender(void) {}
    00098 public:
    00099
    00100     /// flags for indicating rendering styles
    00101     enum RenderFlag_t
    00102     {
    00103         Render_Dot = 0,     ///< render dots (points)
    00104         Render_Mesh,        ///< render wireframe meshes
    00105         Render_Fill,        ///< render solid-filled triangles (default value)
    00106         Render_FillAndMesh, ///< render solid-filled with wireframe on top
    00107         Render_DepthMesh,   ///< render only visible wireframe pieces
    00108         Render_CullCW,      ///< cull faces with clockwise vertex winding (default value)
    00109         Render_CullCCW,     ///< cull faces with counter-clockwise vertex winding
    00110         Render_CullNone,    ///< cull no faces according to vertex winding
    00111         Render_NoWaterMark,
    00112         Render_WaterMark,
    00113         Render_WaterMarkFade,
    00114         Render_MaxFlag,
    00115         Render_Force32 = 0x7FFFFFFF
    00116     };
    00117
    00118     /// flag for setting render-states in a group
    00119     // this is really a hack and should be superceded by the shader system
    00120     enum StencilType_t
    00121     {
    00122         Stencil_Disable = 0,///< No stenciling comparisons or operations
    00123         Stencil_DrawOn,     ///< render only when stencil value is Ref. Overloads Comparison to EQUAL if ALWAYS is specified
    00124         Stencil_SetTo,      ///< set rendered pixels to stencil value Ref
    00125         Stencil_Invert,     ///< invert stencil value on rendered pixels
    00126         Stencil_Increment,  ///< increment rendered pixels' stencil values, and wrap if X is non-zero
    00127         Stencil_Decrement,  ///< decrement rendered pixels' stencil values, and wrap if X is non-zero
    00128         Stencil_UseColor,   ///< not a stencil state, call with boolean value in Ref for color buffer rendering
    00129         Stencil_MaxFlag,
    00130         Stencil_Force32 = 0x7FFFFFFF
    00131     };
    00132
    00133     // another hack, this will be superceded by IdeSurface
    00134     struct deRenderSurface
    00135     {
    00136         deBoolean           Transparency;
    00137         IdeRenderMaterial*  Material;
    00138         IdeRenderTexture*   Texture;
    00139         short               TexBaseIndex, TexDetailIndex;
    00140         short               BumpBaseIndex, BumpDetailIndex;
    00141         short               SpecMapIndex, EmissiveIndex;
    00142         // insert shader entries here
    00143         void*               VProgram;
    00144         void*               DiffuseShader;
    00145         void*               TextureShader;
    00146         void*               SpecShader;
    00147     };
    00148
    00149     /// a structure used by the scenegraph to have geometry rendered
    00150     struct deRenderObject
    00151     {
    00152         IdeVertexBuffer*    VB;
    00153         IdeVertexBuffer*    IndexOverride;
    00154         long                IndexOffset;
    00155         IdeSurface*         pSurface;
    00156         deBoolean           isSky;
    00157         deTransformInfo     Transform;
    00158         IdeSceneLight*      Lights[DERENDER_MAX_LIGHTS];
    00159         // put in info about base texture, bumpmap, specmap, etc
    00160         // update: forget that, it's all going into the shader/surface system
    00161         deRenderSurface     SurfaceDetail; // deprecated by IdeSurface, remove soon
    00162     };
    00163
    00164     /// Structure keeping statistical information about a rendered frame.
    00165     /// This information can be useful for optimizing your application and content.
    00166     struct deRenderStats
    00167     {
    00168         /// information extracted from the driver
    00169         IdeDriver::deDriverStats    DriverStats;
    00170         /// count of how many things were rendered
    00171         long VertexRenders, IndexRenders, PrimitiveRenders;
    00172         /// count of items regarding vertex buffers
    00173         long VBufferRenders, VBufferUpdates, VBufferSubRenders;
    00174         /// total number of vertex buffers used (and number that had indexed data)
    00175         long VBuffersTotal, VBuffersIndexed;
    00176         /// number of textures used
    00177         long TexturesTotal;
    00178         /// number of texture switches
    00179         long TexturesChanged;
    00180         /// number of material changes during the frame
    00181         long MaterialsChanged;
    00182         /// number of bitmaps total and in relation to a vertex buffer
    00183         long BitmapsTotal, MinBitmapsPer, MaxBitmapsPer;
    00184         /// number of lights per vertex buffer
    00185         long MinLightsPer, MaxLightsPer;
    00186         /// each index stores the number of vertices rendered with that number of lights.
    00187         /// ie, LightsVertNum[3] is the number of vertices rendered with 3 lights affecting them.
    00188         long LightsVertNum[9];
    00189         /// the scene may be rendered more than one time to optimize certain things
    00190         long RenderPasses, VertexPasses;
    00191         /// the frustum far plane distance used for rendering
    00192         deFloat FarPlaneDistUsed;
    00193         // perhaps a bit of info about # of pixels Cleared
    00194     };
    00195
    00196     /// set a flag for the next call to Render to use.
    00197     /// see IdeRender::RenderFlag_t for notes on usage
    00198     virtual deBoolean SetRenderFlag(IdeRender::RenderFlag_t Flag) = 0;
    00199
    00200     /// Set a pre-defined stencil method.
    00201     /// notes on how stenciling works and what it does:
    00202     /// <br>(StencilRef & StencilMask) RenderCmpFunc (StencilBufferValue & StencilMask)<br>
    00203     /// That is the comparison performed for each pixel drawn when stenciling is enabled.
    00204     /// The StencilRef value is compared with the StencilBufferValue, using a comparison function
    00205     /// to evaluate success or failure of the test. If the stencil test fails, the operation for
    00206     /// STENCILFAIL will be performed. If the stencil test passes and the depth-test fails, the
    00207     /// operatation for STENCILZFAIL will be performed. If both the stencil and depth tests pass,
    00208     /// the operation for STENCILPASS will be performed.
    00209     /// <br>If modifying values in the stencil buffer, the write-mask is applied to the bits being
    00210     /// altered. Using the StencilMaks and WriteMask, you can effectively store more than one useful
    00211     /// "channel" of stencil information and modify it. However, there is usually a maximum of 8 bits
    00212     /// available for use in stenciling, so not too much detail can be stored if the stencil channel
    00213     /// is being "shared" in such a way. For Destiny3D, the aim is to perform stenciled lighting
    00214     /// and stenciled portaling on the same geometry by sharing out the stencil buffer in this
    00215     /// manner.
    00216     /// @param pDriver valid render-capable driver
    00217     /// @param Stencil any valid value of StencilType_t
    00218     /// @param Ref the StencilRef value
    00219     /// @param X a special-use flag argument, used with some stencil types to specify behavior
    00220     /// @param Comparison a comparison function for comparing current stencil value to reference value.
    00221     ///                   see IdeDriver documentation for notes on how stenciling works
    00222     /// @param StencilTest the test for which the operation will be performed. Default is STENCILPASS,
    00223     ///                    can also be STENCILFAIL or STENCILZFAIL
    00224     /// @param StencilMask the stenciling read-mask
    00225     /// @param WriteMask the stenciling write-mask
    00226     virtual deBoolean SetStencilState(  IdeDriver * pDriver, StencilType_t Stencil, DWORD Ref, DWORD X,
    00227                                         IdeDriver::RenderCmpFunc Comparison = IdeDriver::COMPARE_ALWAYS,
    00228                                         IdeDriver::RenderState StencilTest = IdeDriver::RENDER_STENCILPASS,
    00229                                         DWORD StencilMask = 0xff, DWORD WriteMask = 0xff) = 0;
    00230
    00231     /// Render a scene from a given vantage point, possibly doing some cleanup work with optional params
    00232     /// @param cam a camera containing details of how to render the scene
    00233     /// @param DeltaTime time elapsed since the last call to Render
    00234     /// @param UseSG set to true if the scenegraph is to be traversed
    00235     /// @param ClearColorBuffer (optional, default false) if true, the color buffer will be cleared to the stored BGColor
    00236     /// @param BeginFrame (optional, default false) will call BeginFrame(...) for you
    00237     /// @param EndFrame (optional, default false) will call EndFrame(...) for you
    00238     virtual deBoolean Render(IdeCamera * cam, deDouble DeltaTime, deBoolean UseSG = deTRUE, deBoolean ClearColorBuffer = DE_FALSE, deBoolean BeginFrame = DE_FALSE, deBoolean EndFrame = DE_FALSE) = 0;
    00239     /// Just like Render() except instead of rendering to the screen, it renders to a texture.
    00240     /// the texture to be used is handled through the Target parameter, and the texture on the video
    00241     /// hardware after the render will not match the bitmap in system memory. BeginFrame should
    00242     /// still be called before this method, so that statistics are properly handled. The camera's
    00243     /// viewport will be used when rendering to the texture, so the camera viewport must be the
    00244     /// correct size for the texture being rendered into. However, the aspect ratio of the camera can
    00245     /// be locked to something other than width/height so that the texture can be mapped in a
    00246     /// way that doesn't require it to be viewed as square.
    00247     /// @param Target The bitmap which acts as the handle to the texture to be rendered into.
    00248     ///               This bitmap must have been added to the driver after having been set to
    00249     ///               have render-target capability.
    00250     virtual deBoolean RenderTexture(IdeBitmap * Target, IdeCamera * cam, deDouble DeltaTime) = 0;
    00251     /// begin a frame before rendering geometry.
    00252     /// @param WindowHandle the window with an attached driver to be used
    00253     /// @param ClearColorBuffer (optional, default true) if true, the color buffer will be cleared to the stored BGColor
    00254     virtual deBoolean BeginFrame(HWND WindowHandle, deBoolean ClearColorBuffer = DE_TRUE) = 0;
    00255     /// end a frame and present the back-buffer to the screen
    00256     /// @param WindowHandle the window with an attached driver to be used
    00257     /// @param DeltaTime time elapsed since the last call to EndFrame
    00258     virtual deBoolean EndFrame(HWND WindowHandle, deDouble DeltaTime) = 0;
    00259
    00260     // for use by scenegraph only
    00261     virtual IdeDriver * CurrentPassDriver() = 0;
    00262     virtual void RenderPrepBuffer(deRenderObject & obj) = 0;
    00263     virtual void RenderPrepBatch(long Level, IdePortal * Portal, deRect & Viewport, deTransformInfo * PortalPos, deTransformInfo * Concat) = 0;
    00264     virtual deDouble GetTimeStep() = 0;
    00265
    00266     /// set the relative path that contains Destiny3D driver files (defaults to "." which is current directory)
    00267     virtual void SetDriverPath(const char * RelativePath) = 0;
    00268     /// returns a pointer to internally-held IdeDriverLoad interface
    00269     virtual IdeDriverLoad* GetDriverLoad() = 0;
    00270     /// attach a driver to the specified window. The driver will not be ready for rendering
    00271     /// @return a valid IdeDriver pointer if success, NULL if failure
    00272     /// @param hWnd a valid window handle to attach a driver to
    00273     /// @param DriverName (optional, defualt = "Direct3D8") string containing the name of driver to use
    00274     virtual IdeDriver * AttachToWindow(HWND hWnd, char * DriverName = "Direct3D8") = 0;
    00275     /// detach and destroy a driver attached to the specified window
    00276     virtual deBoolean DetachFromWindow(HWND hWnd) = 0;
    00277     /// update the driver's knowledge of the window's client rect, ie after a WM_SIZE message is received
    00278     virtual void UpdateWindow(HWND hWnd) = 0;
    00279     virtual void UpdateDisplay() = 0;
    00280
    00281     /// load a driver up and prepare it for rendering
    00282     /// @return true if successful, false if failure to use specified format
    00283     /// @param hWnd a valid window handle to attach a driver to
    00284     /// @param Display user-filled driver settings to be used in initializing the driver.
    00285     /// @param DriverName (optional, defualt = "Direct3D") string containing the name of driver to use
    00286     virtual deBoolean LoadDriver(HWND hWnd, IdeDriver::deDisplay * Display, char * DriverName = "Direct3D8") = 0;
    00287     /// check a driver-enumerated resolution
    00288     /// @return false if pDriver is NULL or if Adapter or EntryNum are outside valid ranges, true otherwise
    00289     /// @param Width pointer to integer to store width of entry into
    00290     /// @param Height pointer to integer to store height of entry into
    00291     /// @param RefreshRate pointer to integer to store screen refresh rate (in hertz) of entry into
    00292     virtual deBoolean GetResolution(IdeDriver * pDriver, long Adapter, long EntryNum, long * Width, long * Height, long * RefreshRate) = 0;
    00293     /// a rather high-level method of finding a format close to what you want for z-buffer.
    00294     /// @pre Adapter, Bpp, and Windowed variables in Display set to appropriate values.
    00295     ///      ZDepth and StencilDepth values in Display set to minimum acceptable bit-depth values.
    00296     /// @post Display contains a valid combination of values to call LoadDriver() with.
    00297     ///       The user should check the values of ZDepth, StencilDepth, and Zpp upon failure,
    00298     ///       so that he can adjust game settings to what is possible.
    00299     /// @return true if a format was found that satisfies criteria set, false if criteria could not be met.
    00300     /// @param pDriver pointer to a valid IdeDriver interface
    00301     /// @param Display pointer to a IdeDriver::deDisplay structure meeting the pre-requisites
    00302     /// @param PreferStencil upon failure to find a good format, satisfy stencil buffer needs before depth-buffer needs (if true)
    00303     virtual deBoolean QueryFormat(IdeDriver * pDriver, IdeDriver::deDisplay * Display, deBoolean PreferStencil = deFALSE) = 0;
    00304
    00305     /// set the color that the color-buffer will be cleared to.
    00306     /// ie, 0x00102030 will set the color to 16 red intensity, 32 green intensity, and 48 blue intensity
    00307     /// out of a maximum intensity of 255
    00308     virtual void SetBGColor(deARGB color) = 0;
    00309     /// set the maximum depth of T-portal progression.
    00310     /// Each T-Portal clears a portion of the screen as part of the rendering process,
    00311     /// so using a high number can adversely affect your framerate. Default value = 8.
    00312     virtual void SetMaxTPortalDepth(long MaxDepth = 8) = 0;
    00313     virtual void SetMaxLights(long MaxHWLights = 32, long MaxTexLights = 4) = 0;
    00314     /// clear the entire color-buffer to a specified color, possibly also clearing the Z-buffer
    00315     virtual deBoolean ClearBackground(HWND hWnd, deARGB color = 0x00000000, deBoolean ClearZ = DE_TRUE) = 0;
    00316     /// enable or disable texturing on all geometry rendered through this interface
    00317     virtual void EnableTexturing(deBoolean Enabled) = 0;
    00318
    00319     /// Specify a user-handled 2D collection for a driver attached to specified window to use.
    00320     /// This method invokes Collection->Claim(), and then Release() on its currently held collection.
    00321     virtual deBoolean Use2DCollection(HWND hWnd, Ide2DCollection * Collection) = 0;
    00322     /// Get the 2D collection that is being used by the driver attached to specified window.
    00323     /// This method does NOT invoke Claim() on the returned collection, but user code may do so.
    00324     virtual Ide2DCollection * Get2DCollection(HWND hWnd) = 0;
    00325
    00326     /// call before BeginFrame with a user-handled instance of the structure to be filled
    00327     /// with information. the data will be valid after a call to Render() or EndFrame()
    00328     virtual void SetStatStruct(deRenderStats * StatStruct) = 0;
    00329
    00330     virtual deBoolean Screenshot(HWND hWnd, const char* filename, long ScreenSizes = 1) = 0;
    00331
    00332     /// get the current frame ID number.
    00333     /// clamped to [0 <-> 2^31-1]
    00334     virtual long GetFrameNum() = 0;
    00335 };
    00336
    00337 #endif