//     [in]  HRESULT hr: The error code to be deciphered.
//     [in]  DWORD strLength: Length of the string passed in.
//     [out] LPSTR pStr:  The string output. This string of appropriate
//                       size needs to be passed in.
//-------------------------------------------------------------------------
void WINAPI
    D3DXGetErrorString(HRESULT hr, 
                       DWORD   strLength, 
                       LPSTR   pStr);

//-------------------------------------------------------------------------
// D3DXMakeDDPixelFormat: Fills in a DDPIXELFORMAT structure based on the 
// ---------------------   D3DX surface format requested.
//
// Params:
//     [in]  D3DX_SURFACEFORMAT d3dxFormat: Surface format.
//     [out] DDPIXELFORMAT*     pddpf:      Pixel format matching the given
//                                          surface format.
//-------------------------------------------------------------------------
HRESULT WINAPI
    D3DXMakeDDPixelFormat(D3DX_SURFACEFORMAT d3dxFormat, 
                          DDPIXELFORMAT*     pddpf);

//-------------------------------------------------------------------------
// D3DXMakeSurfaceFormat: Determines the surface format corresponding to 
// ---------------------  a given DDPIXELFORMAT. 
//
// Params:
//     [in]  DDPIXELFORMAT* pddpf: Pixel format.
// Return Value:
//     D3DX_SURFACEFORMAT: Surface format matching the given pixel format.
//                         D3DX_SF_UNKNOWN if the format is not supported
//-------------------------------------------------------------------------
D3DX_SURFACEFORMAT WINAPI
    D3DXMakeSurfaceFormat(DDPIXELFORMAT* pddpf);

#ifdef __cplusplus
}
#endif //__cplusplus    

///////////////////////////////////////////////////////////////////////////
// Interfaces:
///////////////////////////////////////////////////////////////////////////

//-------------------------------------------------------------------------
// ID3DXContext interface: 
//
// This encapsulates all the stuff that the app might 
// want to do at initialization time and any global control over d3d and 
// ddraw.
//-------------------------------------------------------------------------


DECLARE_INTERFACE_(ID3DXContext, IUnknown)
{
    //
    // IUnknown methods 
    //
    STDMETHOD(QueryInterface)(THIS_ REFIID riid, LPVOID* ppvObj) PURE;
    STDMETHOD_(ULONG,AddRef)(THIS) PURE;
    STDMETHOD_(ULONG,Release)(THIS) PURE;

    // Get the DDraw and Direct3D objects to call DirectDraw or
    // Direct3D Immediate Mode functions. 
    // If the objects don't exist (because they have not
    // been created for some reason) NULL is returned.
    // All the objects returned in the following Get* functions
    // are addref'ed. It is the application's responsibility to
    // release them when no longer needed.
    STDMETHOD_(LPDIRECTDRAW7,GetDD)(THIS) PURE;
    STDMETHOD_(LPDIRECT3D7,GetD3D)(THIS) PURE;
    STDMETHOD_(LPDIRECT3DDEVICE7,GetD3DDevice)(THIS) PURE;

    // Get the various buffers that get created at the init time
    // These are addref'ed as well. It is the application's responsibility
    // to release them before the app quits or when it needs a resize.
    STDMETHOD_(LPDIRECTDRAWSURFACE7,GetPrimary)(THIS) PURE;
    STDMETHOD_(LPDIRECTDRAWSURFACE7,GetZBuffer)(THIS) PURE;
    STDMETHOD_(LPDIRECTDRAWSURFACE7,GetBackBuffer)(THIS_ DWORD which) PURE;

    // Get the associated window handles 
    STDMETHOD_(HWND,GetWindow)(THIS) PURE;
    STDMETHOD_(HWND,GetFocusWindow)(THIS) PURE;

    // 
    // Various Get methods, in case the user had specified default
    // parameters
    //
    STDMETHOD(GetDeviceIndex)(THIS_ 
                              LPDWORD pDeviceIndex, 
                              LPDWORD pHwLevel) PURE;

    STDMETHOD_(DWORD, GetNumBackBuffers)(THIS) PURE;

    STDMETHOD(GetNumBits)(THIS_
                          LPDWORD pColorBits, 
                          LPDWORD pDepthBits,
                          LPDWORD pAlphaBits, 
                          LPDWORD pStencilBits) PURE;

    STDMETHOD(GetBufferSize)(THIS_ 
                             LPDWORD pWidth, 
                             LPDWORD pHeight) PURE;

    // Get the flags that were used to create this context
    STDMETHOD_(DWORD, GetCreationFlags)(THIS) PURE;
    STDMETHOD_(DWORD, GetRefreshRate)(THIS) PURE;
    
    // Restoring surfaces in case stuff is lost
    STDMETHOD(RestoreSurfaces)(THIS) PURE;
    
    // Resize all the buffers to the new width and height
    STDMETHOD(Resize)(THIS_ DWORD width, DWORD height) PURE;

    // Update the frame using a flip or a blit,
    // If the D3DX_UPDATE_NOVSYNC flag is set, blit is used if the 
    // driver cannot flip without waiting for vsync in full-screen mode.
    STDMETHOD(UpdateFrame)(THIS_ DWORD flags) PURE;

    // Render a string at the specified coordinates, with the specified 
    // colour. This is only provided as a convenience for 
    // debugging/information during development.
    // topLeftX and topLeftY represent the location of the top left corner
    // of the string, on the render target.  
    // The coordinate and color parameters each have a range of 0.0-1.0
    STDMETHOD(DrawDebugText)(THIS_
                             float topLeftX, 
                             float topLeftY,
                             D3DCOLOR color,
                             LPSTR pString) PURE;

    // Clears to the current viewport
    // The following are the valid flags:
    // D3DCLEAR_TARGET  (to clear the render target )
    // D3DCLEAR_ZBUFFER (to clear the depth-buffer )
    // D3DCLEAR_STENCIL (to clear the stencil-buffer )
    STDMETHOD(Clear)(THIS_ DWORD ClearFlags) PURE;

    STDMETHOD(SetClearColor)(THIS_ D3DCOLOR color ) PURE;
    STDMETHOD(SetClearDepth)(THIS_ float z) PURE;
    STDMETHOD(SetClearStencil)(THIS_ DWORD stencil) PURE;
};


//-------------------------------------------------------------------------
// Flags for Update member function:
//

// Flag to indicate that blit should be used instead of a flip
// for full-screen rendering.
#define D3DX_UPDATE_NOVSYNC (1<<0)

///////////////////////////////////////////////////////////////////////////
// Texturing APIs:
///////////////////////////////////////////////////////////////////////////
#ifdef __cplusplus
extern "C" {
#endif //__cplusplus
    
//-------------------------------------------------------------------------
// D3DXCheckTextureRequirements: Return information about texture creation 
// ----------------------------  (used by CreateTexture, CreateTextureFromFile
//                                and CreateCubeMapTexture)
//
// Parameters:
//
//  pd3dDevice
//      The D3D device with which the texture is going to be used.
//  pFlags   
//      allows specification of D3DX_TEXTURE_NOMIPMAP
//      D3DX_TEXTURE_NOMIPMAP may be returned in the case where mipmap creation 
//      is not supported.
//  pWidth
//      width in pixels or NULL 
//      returns corrected width
//  pHeight       
//      height in pixels or NULL
//      returns corrected height
//  pPixelFormat
//      surface format 
//      returns best match to input format
//
//  Notes: 1. Unless the flags is set to specifically prevent creating 
//            mipmaps, mipmaps are generated all the way till 1x1 surface.
//         2. width, height and pixelformat are altered based on available 
//            hardware. For example:
//              a. Texture dimensions may be required to be powers of 2
//              b. We may require width == height for some devices
//              c. If PixelFormat is unavailable, a best fit is made
//-------------------------------------------------------------------------
HRESULT WINAPI 
    D3DXCheckTextureRequirements( LPDIRECT3DDEVICE7     pd3dDevice,
                                  LPDWORD               pFlags, 
                                  LPDWORD               pWidth,  
                                  LPDWORD               pHeight,  
                                  D3DX_SURFACEFORMAT*   pPixelFormat);

//-------------------------------------------------------------------------
// D3DXCreateTexture: Create an empty texture object
// -----------------
//
// Parameters:
//
//  pd3dDevice
//      The D3D device with which the texture is going to be used.
//  pFlags   
//      allows specification of D3DX_TEXTURE_NOMIPMAP
//      D3DX_TEXTURE_NOMIPMAP may be returned in the case where mipmap creation 
//      is not supported. Additionally, D3DX_TEXTURE_STAGE<n> can be specified
//      to indicate which texture stage the texture is for e.g. 
//      D3D_TEXTURE_STAGE1 indicates that the texture is for use with texture 
//      stage one. Stage Zero is the default if no TEXTURE_STAGE flags are
//      set.
//  pWidth
//      width in pixels; 0 or NULL is unacceptable
//      returns corrected width
//  pHeight       
//      height in pixels; 0 or NULL is unacceptable
//      returns corrected height
//  pPixelFormat
//      surface format. D3DX_DEFAULT is unacceptable.
//      returns actual format that was used
//  pDDPal
//      DDraw palette that is set (if present) on paletted surfaces.
//      It is ignored even if it is set, for non-paletted surfaces.
//  ppDDSurf
//      The ddraw surface that will be created
//  pNumMipMaps
//      the number of mipmaps actually generated
//
//  Notes: See notes for D3DXCheckTextureRequirements. 
//-------------------------------------------------------------------------
HRESULT WINAPI 
    D3DXCreateTexture( LPDIRECT3DDEVICE7     pd3dDevice,
                       LPDWORD               pFlags, 
                       LPDWORD               pWidth,  
                       LPDWORD               pHeight,  
                       D3DX_SURFACEFORMAT*   pPixelFormat,
                       LPDIRECTDRAWPALETTE   pDDPal,
                       LPDIRECTDRAWSURFACE7* ppDDSurf,
                       LPDWORD               pNumMipMaps);

//-------------------------------------------------------------------------
// D3DXCreateCubeMapTexture: Create blank cube-map texture
// ------------------------
//
// Parameters:
//
//  pd3dDevice
//      The D3D device with which the texture is going to be used.
//  pFlags   
//      allows specification of D3DX_TEXTURE_NOMIPMAP
//      D3DX_TEXTURE_NOMIPMAP may be returned in the case where mipmap creation 
//      is not supported. Additionally, D3DX_TEXTURE_STAGE<n> can be specified
//      to indicate which texture stage the texture is for e.g. 
//      D3D_TEXTURE_STAGE1 indicates that the texture is for use with texture 
//      stage one. Stage Zero is the default if no TEXTURE_STAGE flags are