home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / msdn_vcb / samples / vc98 / sdk / graphics / directx / tri3 / d3dapp.h < prev    next >
C/C++ Source or Header  |  1997-07-14  |  17KB  |  431 lines
  1. /*
  2.  *  Copyright (C) 1995, 1996 Microsoft Corporation. All Rights Reserved.
  3.  *
  4.  *  File: d3dapp.h
  5.  *
  6.  *  Header to be included in source using D3DApp.  Contains D3DApp function
  7.  *  prototypes and defines.
  8.  *
  9.  *  D3DApp is a collection of helper functions for Direct3D applications.
  10.  *  D3DApp consists of the following files:
  11.  *    d3dapp.h    Main D3DApp header to be included by application
  12.  *      d3dappi.h   Internal header
  13.  *      d3dapp.c    D3DApp functions seen by application.
  14.  *      ddcalls.c   All calls to DirectDraw objects except textures
  15.  *      d3dcalls.c  All calls to Direct3D objects except textures
  16.  *      texture.c   Texture loading and managing texture list
  17.  *      misc.c        Miscellaneous calls
  18.  */
  19.  
  20. #ifndef __D3DAPP_H__
  21. #define __D3DAPP_H__
  22.  
  23. #define INITGUID
  24.  
  25. #include <ddraw.h>
  26. #include <d3d.h>
  27.  
  28. #ifdef __cplusplus
  29. extern "C" {
  30. #endif
  31.  
  32. /*
  33.  * DEFINES
  34.  */
  35. #define D3DAPP_WINDOWMINIMUM 50        /* smallest buffer size allowed */
  36. #define D3DAPP_DEFAULTWINDOWDIM 320 /* replaces window size if invalid */
  37. #define D3DAPP_MINBUFFERSIZE 15360  /* minimum "maximum buffer size" for a
  38.                        D3D driver to be accepted */
  39. #define D3DAPP_MINVERTEXCOUNT 320   /* minimum "maximum vertex count" for a
  40.                        D3D driver to be accepted */
  41. #define D3DAPP_MAXD3DDRIVERS 5        /* maximum Direct3D drivers ever expected
  42.                        to find */
  43. #define D3DAPP_MAXTEXTUREFORMATS 50 /* maximum texture formats */
  44. #define D3DAPP_MAXMODES 50        /* maximum display modes ever expected to
  45.                        be reported by DirectDraw */
  46. #define D3DAPP_MAXTEXTURES 15        /* maximum number of textures that wil be
  47.                        loaded and managed */
  48. #define D3DAPP_MAXCLEARRECTS 30        /* maximum num. rectangles (ie extents)
  49.                        for clearing */
  50. #define D3DAPP_BOGUS -100        /* unused parameters accept this */
  51. #define D3DAPP_YOUDECIDE -25        /* Use this for certain parameters to
  52.                        have D3DApp decide an appropriate
  53.                        value for you */
  54. #define D3DAPP_USEWINDOW -24        /* Used in place of fullscreen mode */
  55.  
  56. /*
  57.  * DATA STRUCTURES
  58.  */
  59.  
  60. /*
  61.  * D3DAppD3DDriver structure
  62.  * Describes a D3D driver
  63.  */
  64. typedef struct tagD3DAppD3DDriver {
  65.     char Name[30];    /* short name of the driver */
  66.     char About[50];    /* short string about the driver */
  67.     D3DDEVICEDESC Desc; /* D3DDEVICEDESC for complete information */
  68.     GUID Guid;        /* it's GUID */
  69.     BOOL bIsHardware;    /* does this driver represent a hardware device? */
  70.     BOOL bDoesTextures; /* does this driver do texture mapping? */
  71.     BOOL bDoesZBuffer;  /* can this driver use a z-buffer? */
  72.     BOOL bCanDoWindow;    /* can it render to Window's display depth? */
  73. } D3DAppD3DDriver;
  74.  
  75. /*
  76.  * D3DAppTextureFormat stucture
  77.  * Describes a texture format
  78.  */
  79. typedef struct tagD3DAppTextureFormat {
  80.     DDSURFACEDESC ddsd;    /* DDSURFACEDESC for complete information */
  81.     BOOL bPalettized;    /* is this format palettized */
  82.     int RedBPP;        /* number of red, */
  83.     int BlueBPP;    /*                blue, */
  84.     int GreenBPP;    /*                      and green bits per pixel */
  85.     int IndexBPP;    /* number of bits in palette index */
  86. } D3DAppTextureFormat;
  87.  
  88. /*
  89.  * D3DAppMode structure
  90.  * Describes a display mode
  91.  */
  92. typedef struct tagD3DAppMode {
  93.     int     w;              /* width */
  94.     int        h;              /* height */
  95.     int        bpp;          /* bits per pixel */
  96.     BOOL    bThisDriverCanDo; /*can current D3D driver render in this mode?*/
  97. } D3DAppMode;
  98.  
  99. /*
  100.  * D3DAppInfo structure
  101.  * Contains all the information D3DApp makes available to the application. A
  102.  * pointer to the internal, read only copy is returned by the initializing
  103.  * function.
  104.  */
  105. typedef struct tagD3DAppInfo {
  106.     HWND            hwnd;       /*handle of window being managed*/
  107.     /*
  108.      * Direct3D objects and information
  109.      */
  110.     LPDIRECT3D2            lpD3D;       /* D3D object */
  111.     LPDIRECT3DDEVICE2        lpD3DDevice;   /* D3D device */
  112.     LPDIRECT3DVIEWPORT2        lpD3DViewport; /* D3D viewport, created by
  113.                           application */
  114.     int                NumDrivers;       /* number of D3D drivers avail. */
  115.     int                CurrDriver;       /* number of curr. D3D driver */
  116.     D3DAppD3DDriver        Driver[D3DAPP_MAXD3DDRIVERS]; /* avail. drivers*/
  117.     D3DAppD3DDriver        ThisDriver;       /* description of this driver,
  118.                        identical to Driver[CurrDriver] */
  119.  
  120.     int                NumTextureFormats; /* num texture formats avail*/
  121.     int                CurrTextureFormat; /* current texture format
  122.           will only change if driver changes or when app changes it*/
  123.     D3DAppTextureFormat     TextureFormat[D3DAPP_MAXTEXTUREFORMATS];
  124.                       /* description of all avail. formats */
  125.     D3DAppTextureFormat     ThisTextureFormat; /* description of this format,
  126.                  identical to TextureFormat[CurrTextureFormat] */
  127.  
  128.     int                NumTextures;    /* number of textures in D3DApp's
  129.                            texture list */
  130.     char            ImageFile[D3DAPP_MAXTEXTURES][50]; /* files */
  131.     D3DTEXTUREHANDLE        TextureHandle[D3DAPP_MAXTEXTURES]; /* handles */
  132.     LPDIRECTDRAWSURFACE        lpTextureSurf[D3DAPP_MAXTEXTURES]; /* surfaces */
  133.     LPDIRECT3DTEXTURE2        lpTexture[D3DAPP_MAXTEXTURES]; /* texture objs */
  134.     int                NumUsableTextures; /* the number of currently usable
  135.                           textures (e.g. for a hardware
  136.                           device there may not be enough
  137.                               video memory*/
  138.     /*
  139.      * DirectDraw objects and information
  140.      */
  141.     LPDIRECTDRAW        lpDD;       /* DirectDraw object */
  142.     BOOL            bIsPrimary;    /* Is this the primary DD device?
  143.            If FALSE, we're using a hardware DD device that cannot
  144.            display a window and so only fullscreen modes are available */
  145.     LPDIRECTDRAWSURFACE        lpFrontBuffer; /* front buffer surface */
  146.     LPDIRECTDRAWSURFACE        lpBackBuffer;  /* back buffer surface */
  147.     LPDIRECTDRAWSURFACE        lpZBuffer;     /* z-buffer surface */
  148.     BOOL            bBackBufferInVideo; /* back buf in video mem? */
  149.     BOOL            bZBufferInVideo;    /* is Z-buf in video mem? */
  150.  
  151.     int                NumModes; /* number of available display modes */
  152.     int                CurrMode; /* number of current display mode (only
  153.                          when fullscreen) */
  154.     D3DAppMode            Mode[D3DAPP_MAXMODES]; /* desc avail modes */
  155.     D3DAppMode            ThisMode; /* description of this mode, identical
  156.                      to Mode[CurrMode] */
  157.     BOOL            bFullscreen; /* in fullscreen exclusive mode? */
  158.     D3DAppMode            WindowsDisplay; /* current Windows disply mode */
  159.  
  160.     SIZE            szClient;          /* dimensions of client win */
  161.     POINT            pClientOnPrimary; /* position of client win */
  162.  
  163.     BOOL            bPaused;           /* the app is paused */
  164.     BOOL            bAppActive;           /* the app is active */
  165.     BOOL            bTexturesDisabled; /* textures are disabled */
  166.     BOOL            bOnlySystemMemory; /* all surfaces forced into
  167.                           system memory */
  168.     BOOL            bOnlyEmulation;    /* no hardware DD or D3D
  169.                           devices allowed */
  170.     BOOL            bMinimized;           /* app window is minimized */
  171.     BOOL            bRenderingIsOK;    /* All objects etc. necessary
  172.                           for rendering are in ok */
  173. } D3DAppInfo;
  174.  
  175. /*
  176.  * D3DAppRenderState structure
  177.  * The "render state" is the status of this collection of D3D options and
  178.  * variables.  This structure is used to get and set the render state.  The
  179.  * render state will only change during program initialization and when
  180.  * the application sets it.
  181.  */
  182. typedef struct tagD3DAppRenderState {
  183.     BOOL             bZBufferOn;    /* Z buffer is on */
  184.     BOOL             bPerspCorrect; /* perspective correction is on */
  185.     D3DSHADEMODE     ShadeMode;     /* flat, gouraud, phong? */
  186.     D3DTEXTUREFILTER TextureFilter; /* linear or bi-linear texture filter */
  187.     D3DTEXTUREBLEND  TextureBlend;  /* Use shade mode or copy mode? */
  188.     D3DFILLMODE      FillMode;        /* solid, lines or points? */
  189.     BOOL             bDithering;    /* dithering is on */
  190.     BOOL             bSpecular;        /* specular highlights are on */
  191.     BOOL             bAntialiasing; /* anti-aliasing is on */
  192.  
  193.     BOOL         bFogEnabled;   /* fog is on */
  194.     D3DCOLOR         FogColor;        /* fog color */
  195.     D3DFOGMODE         FogMode;        /* linear, exp. etc. */
  196.     D3DVALUE         FogStart;        /* begining depth */
  197.     D3DVALUE         FogEnd;        /* ending depth */
  198. } D3DAppRenderState;
  199.  
  200. /*
  201.  * FUNCTION PROTOTYPES
  202.  */
  203.  
  204. /*
  205.  * D3DAppCreateFromHWND
  206.  *
  207.  * Call this before all other D3DApp functions (except AddTexture).  
  208.  * Initializes all DD and D3D objects necessary for rendering, enumerates the
  209.  * available display modes and drivers and loads textures specified by prior
  210.  * AddTexture() calls.  Caller passes the handle of the window to be manged
  211.  * and callback functions to execute for device creation and destruction.
  212.  * 
  213.  * DeviceCreateCallback is executed AFTER the creation of D3D device and all
  214.  * objects D3DApp created using the device.  This allows an application to
  215.  * reconstruct the scene and create any additional objects.  The callback
  216.  * must create and return (in the variable provided) the DIRECT3DVIEWPORT
  217.  * from the given width and height.  The returned pointer is stored in the
  218.  * D3DAppInfo structure and used for clearing and setting the render state.
  219.  * A NULL pointer is fine if D3DApp is not used for either of these
  220.  * functions. The create callback will always be called before any calls to
  221.  * the destroy callback.  The boolean returned indicates success or failure.
  222.  *
  223.  * DeviceDestroyCallback is executed BEFORE the D3D device and objects
  224.  * created by D3DApp using the device are released.  This allows an
  225.  * application to save data regarding the scene or release any objects
  226.  * created from the device before it is destroyed.  The DIRECT3DVIEWPORT
  227.  * should be released in this callback.  The boolean returned indicates the
  228.  * success or failure.
  229.  *
  230.  * A pointer to the internal D3DAppInfo data structure is returned.  This
  231.  * should be READ ONLY!
  232.  *
  233.  * The DirectDraw device, Direct3D driver, display mode and texture format
  234.  * will all be chosen by D3DApp.  Hardware DD and D3D devices are prefered.
  235.  * Mono lighting D3D drivers are prefered.  Paletted texture formats are
  236.  * prefered.  If possible, the current window size will be used, otherwise
  237.  * a fullscreen mode will be selected.
  238.  *
  239.  * Call AddTexture() to add textures to be loaded upon initialization.
  240.  *
  241.  * Valid flags:
  242.  *    D3DAPP_ONLYSYSTEMMEMORY  Force all surfaces into system memory.  Also
  243.  *                             disables hardware DD and D3D drivers.
  244.  *    D3DAPP_ONLYD3DEMULATION  Disable D3D hardware
  245.  *    D3DAPP_ONLYDDEMULATION   Disable DD hardware
  246.  */
  247. #define D3DAPP_ONLYSYSTEMMEMORY 0x00000001
  248. #define D3DAPP_ONLYD3DEMULATION    0x00000002
  249. #define D3DAPP_ONLYDDEMULATION    0x00000004
  250. BOOL D3DAppCreateFromHWND(DWORD flags, HWND hwnd,
  251.               BOOL(*DeviceCreateCallback)(int, int,
  252.                               LPDIRECT3DVIEWPORT2*,
  253.                               LPVOID),
  254.               LPVOID lpCreateContext,
  255.               BOOL(*DeviceDestroyCallback)(LPVOID),
  256.               LPVOID lpDestroyContext,
  257.               D3DAppInfo** D3DApp);
  258.  
  259. /*
  260.  * D3DAppWindowProc
  261.  * To be truly effective, D3DApp should be allowed to trap incoming window
  262.  * messages such as WM_SIZE.  Call D3DAppWindowProc at the begining of the
  263.  * application's main window WindowProc with the message information.  If
  264.  * bStopProcessing is set to TRUE, stop processing the message and return
  265.  * lresult.
  266.  */
  267. BOOL D3DAppWindowProc(BOOL* bStopProcessing, LRESULT* lresult, HWND hwnd,
  268.               UINT message, WPARAM wParam, LPARAM lParam);
  269.  
  270. /*
  271.  * D3DAppFullscreen
  272.  * Places the app in a fullscreen mode using the current driver.
  273.  */
  274. BOOL D3DAppFullscreen(int mode);
  275.  
  276. /*
  277.  * D3DAppWindow
  278.  * Places the application in windowed mode at the given client size.  If w
  279.  * and h are D3DAPP_YOUDECIDE, D3DApp will decide on a suitable client size.
  280.  * If called while in fullscreen, restores the display mode and returns the
  281.  * hooked window to the size it was before a call to D3DAppFullscreen or to
  282.  * the size specified.
  283.  */
  284. BOOL D3DAppWindow(int w, int h);
  285.  
  286. /*
  287.  * D3DAppChangeDriver 
  288.  * Changes the driver.  If the current display mode is incompatible with the
  289.  * driver, a new one will be selected and employed.  A new texture format is
  290.  * selected and textures are reloaded, hence their handles may change.  By
  291.  * default, paletted formats are prefered.
  292.  */
  293. BOOL D3DAppChangeDriver(int driver, DWORD flags);
  294.  
  295. /*
  296.  * D3DAppAddTexture
  297.  * D3DApp has an internal list of textures which it maintains.  The image
  298.  * files will be reloaded when necessary and the texture handles, objects and
  299.  * surfaces will always be up to date and available in the D3DAppInfo
  300.  * structure.  D3DAppAddTextures adds the given PPM image file to this
  301.  * list.
  302.  *
  303.  * This is the only function which can be called before CreateD3DAppFromHWND.
  304.  * Use it to create a list of textures to load during this creation function.
  305.  *
  306.  * The handles and texture objects will change when the device or texture
  307.  * format changes.  To react to changes in the texture objects and surfaces,
  308.  * use the callback for D3D device creation/release and make necessary
  309.  * changes whenever calling D3DAppChangeTextureFormat.
  310.  *
  311.  * Image files are searched for in the current directory, D3DPATH env var, 
  312.  * and the "Software\Microsoft\Direct3D\4.0\D3D Path" registry entry.
  313.  *
  314.  */
  315. BOOL D3DAppAddTexture(const char* imagefile);
  316.  
  317. /*
  318.  * D3DAppChangeTextureFormat
  319.  * Changes all textures to the given format.  Texture handles and objects
  320.  * will change.
  321.  */
  322. BOOL D3DAppChangeTextureFormat(int format);
  323.  
  324. /*
  325.  * D3DAppDisableTextures
  326.  * Disables the textures by turning handles to NULL.  If the driver changes,
  327.  * textures are not loaded until this state is toggled by another call with a
  328.  * TRUE flag.
  329.  */
  330. BOOL D3DAppDisableTextures(BOOL flag);
  331.  
  332. /*
  333.  * D3DAppSwapTextures
  334.  * Swaps first texture with the second, second with third, etc. while keeping
  335.  * the handles array the same.
  336.  */
  337. BOOL D3DAppSwapTextures(void);
  338.  
  339. /*
  340.  * D3DAppSetRenderState
  341.  * Uses a D3D execute buffer to set the render state.  If lpState is NULL,
  342.  * the current settings are reset.
  343.  */
  344. BOOL D3DAppSetRenderState(D3DAppRenderState* lpState);
  345.  
  346. /*
  347.  * D3DAppGetRenderState
  348.  * Returns the current render state.
  349.  */
  350. BOOL D3DAppGetRenderState(D3DAppRenderState* lpState);
  351.  
  352. /*
  353.  * D3DAppShowBackBuffer
  354.  * Blts or flips the back buffer to the primary surface.  In the windowed
  355.  * case, only the dirty portion of the front buffer is blt'ed over.  The
  356.  * dirty region of front and back buffers is maintained by calls to
  357.  * D3DAppRenderExtents(). D3DAPP_SHOWALL will force the entire front buffer
  358.  * to be updated.
  359.  */
  360. #define D3DAPP_SHOWALL 0x00000001
  361. BOOL D3DAppShowBackBuffer(DWORD flags);
  362.  
  363. /*
  364.  * D3DAppRenderExtents
  365.  * Tells D3DApp the extents of all regions updated on the back buffer as a
  366.  * list of D3DRECTs (no more than D3DAPP_MAXCLEARRECTS).  Call this before
  367.  * clearing the back buffer.  If the D3DAPP_CLEARALL flag is set, the extents
  368.  * are ignored and the entire back buffer is assumed to have changed.
  369.  */
  370. #define D3DAPP_CLEARALL 0x00000001
  371. BOOL D3DAppRenderExtents(DWORD dwCount, LPD3DRECT extent, DWORD flags);
  372.  
  373. /*
  374.  * D3DAppClearBackBuffer
  375.  * Clears the back buffer and Z-buffer (if enabled).  D3DAPP_CLEARALL can be
  376.  * used to clear the entire back buffer.
  377.  */
  378. #define D3DAPP_CLEARALL 0x00000001
  379. BOOL D3DAppClearBackBuffer(DWORD flags);
  380.  
  381. /*
  382.  * D3DAppCheckForLostSurfaces
  383.  * Checks all surfaces D3DApp has allocated and restores them if necessary.
  384.  * An error is returned on any type of failure, but it may be best to ignore
  385.  * it since restoring surface can fail for non-fatal reasons and the app may
  386.  * just want to spin.
  387.  */
  388. BOOL D3DAppCheckForLostSurfaces(void);
  389.  
  390. /*
  391.  * D3DAppPause
  392.  * Use D3DAppPause(TRUE) to pause the app and D3DAppPause(FALSE) to unpause.
  393.  * When fullscreen, the menu bar is redrawn.  bPaused is updated to reflect
  394.  * the current status.
  395.  */
  396. BOOL D3DAppPause(BOOL flag);
  397.  
  398. /*
  399.  * D3DAppErrorToString
  400.  * Converts a DirectDraw, Direct3D or Direct3D RM error code to a string.
  401.  */
  402. char* D3DAppErrorToString(HRESULT error);
  403.  
  404. /*
  405.  * D3DAppCreateSurface
  406.  * Creates a surface described by ddsd.  Will force the surface into
  407.  * systemmemory if D3DApp was initialized with D3DAPP_ONLYSYSTEMMEMORY.
  408.  */
  409. BOOL D3DAppCreateSurface(DDSURFACEDESC *ddsd, LPDIRECTDRAWSURFACE *lplpSurf);
  410.  
  411. /*
  412.  * D3DAppLastError
  413.  * D3DAppLastErrorString
  414.  * Returns the last D3DApp error as a string and HRESULT.
  415.  */
  416. HRESULT D3DAppLastError(void);
  417. char* D3DAppLastErrorString(void);
  418.  
  419. /*
  420.  * D3DAppDestroy
  421.  * Destroys all objects including Direct Draw.  Call before program
  422.  * termination.
  423.  */
  424. BOOL D3DAppDestroy(void);
  425.  
  426. #ifdef __cplusplus
  427. };
  428. #endif
  429.  
  430. #endif // __D3DAPP_H__
  431.