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